add rev tracking engine

Author: jonathanlab

CLAUDE.md

@@ -46,6 +46,8 @@
 
 ### Avoid Barrel Files
 
+- Do not make use of index.ts
+
 Barrel files:
 
 - Break tree-shaking

apps/cli/src/cli.ts

@@ -1,3 +1,7 @@
+import { triggerBackgroundRefresh } from "@array/core/background-refresh";
+import { type ArrContext, initContext } from "@array/core/engine";
+import { dumpRefs } from "./commands/hidden/dump-refs";
+import { refreshPRInfo } from "./commands/hidden/refresh-pr-info";
 import {
   CATEGORY_LABELS,
   CATEGORY_ORDER,
@@ -159,17 +163,46 @@ export async function main(): Promise<void> {
     return;
   }
 
+  // Hidden commands
+  if (command === "__refresh-pr-info") {
+    await refreshPRInfo();
+    return;
+  }
+  if (command === "__dump-refs") {
+    await dumpRefs();
+    return;
+  }
+
   const handler = HANDLERS[command];
   if (handler) {
     const requiredLevel = getRequiredContext(command);
-    if (requiredLevel !== "none") {
-      const context = await checkContext();
-      if (!isContextValid(context, requiredLevel)) {
-        printContextError(context, requiredLevel);
-        process.exit(1);
-      }
+
+    // Commands that don't need context (auth, help, etc.)
+    if (requiredLevel === "none") {
+      await handler(parsed, null);
+      return;
+    }
+
+    // Check prerequisites (git, jj, arr initialized)
+    const prereqs = await checkContext();
+    if (!isContextValid(prereqs, requiredLevel)) {
+      printContextError(prereqs, requiredLevel);
+      process.exit(1);
+    }
+
+    // Initialize context with engine
+    let context: ArrContext | null = null;
+    try {
+      context = await initContext();
+
+      // Trigger background PR refresh (rate-limited)
+      triggerBackgroundRefresh(context.cwd);
+
+      await handler(parsed, context);
+    } finally {
+      // Auto-persist engine changes
+      context?.engine.persist();
     }
-    await handler(parsed);
     return;
   }
 

apps/cli/src/commands/checkout.ts

@@ -1,26 +1,23 @@
 import { checkout as checkoutCmd } from "@array/core/commands/checkout";
 import { changeLabel } from "@array/core/slugify";
 import { cyan, dim, formatSuccess, message } from "../utils/output";
-import { findChange, requireArg, unwrap } from "../utils/run";
+import { requireArg, unwrap } from "../utils/run";
 
 export async function checkout(id: string): Promise<void> {
   requireArg(id, "Usage: arr checkout <id>");
 
+  const result = unwrap(await checkoutCmd(id));
+
   // Handle trunk checkout - creates new empty change on main
   if (id === "main" || id === "master" || id === "trunk") {
-    unwrap(await checkoutCmd(id));
     message(formatSuccess(`Switched to ${cyan(id)}`));
     return;
   }
 
-  // For other targets, resolve via findChange first
-  const change = await findChange(id, { includeBookmarks: true });
-  unwrap(await checkoutCmd(change.changeId));
-
-  const label = changeLabel(change.description, change.changeId);
+  const label = changeLabel(result.change.description, result.change.changeId);
   message(
     formatSuccess(
-      `Switched to ${cyan(label)}: ${change.description || dim("(no description)")}`,
+      `Switched to ${cyan(label)}: ${result.change.description || dim("(no description)")}`,
     ),
   );
 }

apps/cli/src/commands/create.ts

@@ -1,4 +1,5 @@
 import { create as createCmd } from "@array/core/commands/create";
+import type { ArrContext } from "@array/core/engine";
 import { COMMANDS } from "../registry";
 import {
   arr,
@@ -11,13 +12,18 @@ import {
 import { requireArg, unwrap } from "../utils/run";
 import { showTip } from "../utils/tips";
 
-export async function create(msg: string): Promise<void> {
+export async function create(msg: string, ctx: ArrContext): Promise<void> {
   requireArg(
     msg,
     "Usage: arr create <description>\n  Creates a change with current file modifications",
   );
 
-  const result = unwrap(await createCmd(msg));
+  const result = unwrap(
+    await createCmd({
+      message: msg,
+      engine: ctx.engine,
+    }),
+  );
 
   message(formatSuccess(`Created ${cyan(result.bookmarkName)}`));
   indent(

apps/cli/src/commands/delete.ts

@@ -1,4 +1,5 @@
 import { deleteChange as deleteCmd } from "@array/core/commands/delete";
+import type { ArrContext } from "@array/core/engine";
 import { changeLabel } from "@array/core/slugify";
 import {
   cyan,
@@ -10,20 +11,20 @@ import {
   yellow,
 } from "../utils/output";
 import { confirm } from "../utils/prompt";
-import { findChange, requireArg, unwrap } from "../utils/run";
+import { requireArg, unwrap } from "../utils/run";
 
 export async function deleteChange(
   id: string,
+  ctx: ArrContext,
   options?: { yes?: boolean },
 ): Promise<void> {
   requireArg(id, "Usage: arr delete <id>");
 
-  const change = await findChange(id);
-  const label = changeLabel(change.description, change.changeId);
-
-  // Confirm deletion since work will be lost
+  // Note: We call deleteCmd which resolves the change internally.
+  // For confirmation, we show the raw id since we can't resolve beforehand without duplicating logic.
+  // The actual label will be shown in the success message.
   const confirmed = await confirm(
-    `Delete ${cyan(label)}? ${red("Work will be permanently lost.")}`,
+    `Delete ${cyan(id)}? ${red("Work will be permanently lost.")}`,
     { autoYes: options?.yes, default: false },
   );
 
@@ -32,8 +33,9 @@ export async function deleteChange(
     return;
   }
 
-  const result = unwrap(await deleteCmd(change.changeId));
+  const result = unwrap(await deleteCmd({ id, engine: ctx.engine }));
 
+  const label = changeLabel(result.change.description, result.change.changeId);
   message(formatSuccess(`Deleted change ${cyan(label)}`));
 
   if (result.movedTo) {

apps/cli/src/commands/hidden/dump-refs.ts

@@ -0,0 +1,31 @@
+import { $ } from "bun";
+
+/**
+ * Hidden debug command to dump all arr refs metadata.
+ * Usage: arr __dump-refs
+ *
+ * Shows the contents of all refs/arr/* blobs, which store
+ * metadata about changes (PR info, etc.).
+ */
+export async function dumpRefs(): Promise<void> {
+  const result =
+    await $`git for-each-ref refs/arr --format='%(refname:short)'`.quiet();
+  const refs = result.stdout.toString().trim().split("\n").filter(Boolean);
+
+  if (refs.length === 0) {
+    console.log("No arr refs found.");
+    return;
+  }
+
+  for (const ref of refs) {
+    console.log(`=== ${ref} ===`);
+    const blob = await $`git cat-file blob refs/${ref}`.quiet();
+    const content = blob.stdout.toString().trim();
+    try {
+      console.log(JSON.stringify(JSON.parse(content), null, 2));
+    } catch {
+      console.log(content);
+    }
+    console.log();
+  }
+}

apps/cli/src/commands/hidden/refresh-pr-info.ts

@@ -0,0 +1,17 @@
+import { syncPRInfo } from "@array/core/commands/sync-pr-info";
+import { initContext } from "@array/core/engine";
+
+/**
+ * Background PR info refresh command.
+ * Called by triggerBackgroundRefresh() as a detached process.
+ * Silently syncs PR info and exits.
+ */
+export async function refreshPRInfo(): Promise<void> {
+  try {
+    const context = await initContext();
+    await syncPRInfo({ engine: context.engine });
+    context.engine.persist();
+  } catch {
+    // Silent failure - background task shouldn't crash
+  }
+}

apps/cli/src/commands/log.ts

@@ -1,4 +1,5 @@
 import { log as logCmd } from "@array/core/commands/log";
+import type { ArrContext } from "@array/core/engine";
 import type { LogGraphData, PRInfo } from "@array/core/log-graph";
 import { COMMANDS } from "../registry";
 import {
@@ -7,24 +8,32 @@ import {
   dim,
   formatChangeId,
   formatCommitId,
-  formatDiffStats,
   green,
+  hint,
   magenta,
   message,
   red,
   yellow,
 } from "../utils/output";
 import { unwrap } from "../utils/run";
 
-export async function log(): Promise<void> {
-  const data = unwrap(await logCmd());
+export async function log(ctx: ArrContext): Promise<void> {
+  const data = unwrap(
+    await logCmd({
+      engine: ctx.engine,
+      trunk: ctx.trunk,
+    }),
+  );
 
+  // isEmpty means: on trunk with empty working copy and no tracked branches
+  // In this case, show a simplified view
   if (data.isEmpty) {
-    message(dim("No changes in stack"));
+    message(`${green("◉")} ${ctx.trunk} ${dim("(current)")}`);
+    hint(`Run ${cyan("arr create")} to start a new stack`);
     return;
   }
 
-  const output = renderLogGraph(data);
+  const output = renderLogGraph(data, ctx.trunk);
   message(output);
 
   if (data.modifiedCount > 0) {
@@ -35,7 +44,7 @@ export async function log(): Promise<void> {
   }
 }
 
-function renderLogGraph(data: LogGraphData): string {
+function renderLogGraph(data: LogGraphData, trunk: string): string {
   const output = data.rawOutput;
 
   // Process each line to handle placeholders
@@ -45,7 +54,8 @@ function renderLogGraph(data: LogGraphData): string {
   for (const line of lines) {
     let processed = line;
 
-    // {{LABEL:changeId|prefix|timestamp|description|conflict|wc|empty|immutable|localBookmarks|remoteBookmarks|added|removed|files}}
+    // {{LABEL:changeId|prefix|timestamp|description|conflict|wc|empty|immutable|localBookmarks|remoteBookmarks}}
+    // Note: jj outputs the graph marker (@, ○, ◆), we just output the label content
     processed = processed.replace(/\{\{LABEL:([^}]+)\}\}/g, (_, content) => {
       const parts = content.split("|");
       const [
@@ -54,20 +64,15 @@ function renderLogGraph(data: LogGraphData): string {
         timestamp,
         description,
         conflict,
-        wc,
+        _wc,
         empty,
-        immutable,
+        _immutable,
         localBookmarks,
         _remoteBookmarks,
-        added,
-        removed,
-        files,
       ] = parts;
 
-      const isWorkingCopy = wc === "1";
       const hasConflicts = conflict === "1";
       const isEmpty = empty === "1";
-      const isImmutable = immutable === "1";
       const bookmarks = localBookmarks
         ? localBookmarks.split(",").filter(Boolean)
         : [];
@@ -103,19 +108,7 @@ function renderLogGraph(data: LogGraphData): string {
       const badgeStr =
         badges.length > 0 ? ` ${dim("(")}${badges.join(", ")}${dim(")")}` : "";
 
-      // Diff stats
-      const filesChanged = Number(files) || 0;
-      const insertions = Number(added) || 0;
-      const deletions = Number(removed) || 0;
-      const statsStr =
-        filesChanged > 0
-          ? ` ${formatDiffStats({ filesChanged, insertions, deletions })}`
-          : "";
-
-      // Marker
-      const marker = isWorkingCopy ? green("◉") : isImmutable ? "◆" : "○";
-
-      return `${marker} ${label} ${shortId}${statsStr}${badgeStr}`;
+      return `${label} ${shortId}${badgeStr}`;
     });
 
     // {{TIME:timestamp}}
@@ -126,7 +119,7 @@ function renderLogGraph(data: LogGraphData): string {
 
     // {{HINT_EMPTY}}
     processed = processed.replace(/\{\{HINT_EMPTY\}\}/g, () => {
-      return `${dim("No changes yet")}\n${dim("Edit files, then:")}\n  ${arr(COMMANDS.create)} ${dim('"message"')} ${dim("to save as new change")}\n  ${arr(COMMANDS.down)} ${dim("to edit the change below")}`;
+      return `${dim("Run")} ${arr(COMMANDS.create)} ${dim('"message"')} ${dim("to save as a change")}`;
     });
 
     // {{HINT_UNCOMMITTED}}
@@ -175,10 +168,40 @@ function renderLogGraph(data: LogGraphData): string {
       },
     );
 
+    // {{TRUNK:bookmark}} - trunk label (prefer actual trunk name if present)
+    processed = processed.replace(
+      /\{\{TRUNK:([^}]*)\}\}/g,
+      (_, bookmarksStr) => {
+        const bookmarks = bookmarksStr.split(",").filter(Boolean);
+        // Prefer the actual trunk name if this commit has multiple bookmarks
+        if (bookmarks.includes(trunk)) {
+          return trunk;
+        }
+        return bookmarks[0] || "trunk";
+      },
+    );
+
     processedLines.push(processed);
   }
 
-  return processedLines.join("\n");
+  let result = processedLines.join("\n");
+
+  // Replace jj's graph markers with styled versions
+  // @ = working copy (green ◉)
+  // ○ = mutable commit (◯)
+  // ◆ = immutable commit (◯ - same as mutable, we don't distinguish)
+  // × = conflict (red ×)
+  // ~ = elided (│)
+  result = result.replace(/^(@)(\s+)/gm, `${green("◉")}$2`);
+  result = result.replace(/^(○)(\s+)/gm, "◯$2");
+  result = result.replace(/^(◆)(\s+)/gm, "◯$2");
+  result = result.replace(/^(×)(\s+)/gm, `${red("×")}$2`);
+  result = result.replace(/^(~)(\s+)/gm, "│$2");
+
+  // Remove trailing newlines
+  result = result.trimEnd();
+
+  return result;
 }
 
 function formatPRLine(prInfo: PRInfo, description: string): string {