pi-odd-worktree 1.0.0 → 1.1.0

package/README.md

@@ -18,6 +18,9 @@ alone; Herdr is optional.
 | `/warp` | panel | Moves this session to another checkout: no argument opens the selector (list, create, delete, extended list); `/warp <name>` jumps straight there. |
 | `/odd-list` | panel | Two-pane reader of this checkout's `odd/tasks/*.md`: list on the left, styled markdown on the right. |
 | `/issues` | panel | Full-screen reader of this checkout's repository issues — My issues / Assigned / Involved / All — with preview, comments, labels, assignees and close, gated on your repository role. |
+| `/codegraph-hook` | command | **Only when the CodeGraph CLI is installed.** Turns the edit/write sync on or off for the session. |
+| `/codegraph-init` | command | **Only when the CLI is installed.** Runs `codegraph init` at the session's current directory and says what happened: `initialized <path> — 1 file, 3 nodes, 3 edges`, or `already initialized at <path> — nothing to do`. |
+| `/codegraph-sync` | command | **Only when the CLI is installed.** Runs `codegraph sync` at the session's current directory and says what happened: `already up to date — nothing to sync`, `synced 3 changed files — 12 nodes`, or `no index in this checkout — run /codegraph-init first`. |
 
 A checkout's **name** is the slug of its branch, and its path is
 `<repo-parent>/<repo-name>-worktrees/<slug>`: the slug lowercases the branch and
@@ -33,6 +36,7 @@ interchangeably by `worktree_close`, and by `/warp`.
 | Node.js >= 18 and `git` | `engines` declares 18 as the floor, and every repository operation is a git child process. |
 | `herdr` — optional | Not required: only `worktree_create` tries a Herdr workspace association, and it falls back to plain `git`. |
 | `gh`, authenticated (`gh auth login`) | `/issues` only. Without it the command stays registered, says once per session what is missing, and never opens. |
+| `codegraph` — optional | Keeps each checkout's index fresh: `codegraph init` when a checkout is created, and a background `codegraph sync` after edits and writes. Absent, both stay off for the whole session. |
 | Gentle Shell — recommended | Supplies the presence and transport records the deletion guard reads to see sessions other than this one. |
 
 ```bash
@@ -160,18 +164,80 @@ the checkout's remote moves while the reader is open, mutations refuse with
 …); reopen /issues`, and the reads keep the displayed repository. An issue
 number on screen can never be sent to another repository.
 
+### CodeGraph stays fresh, when the CLI is installed
+
+The probe for `codegraph` on `PATH` runs **once per session** and is cached for
+everything below. Install the CLI mid-session and nothing changes until the next
+start, unless you set `CODEGRAPH_FORCE=1`, which answers "present" without
+probing.
+
+- **On creation**, `worktree_create` runs `codegraph init` inside the new
+  checkout, so it starts with its own index. A session where the gate answered
+  false reports that step as `skipped` and names the gate as the reason; it never
+  silently pretends to have indexed anything.
+- **On edits**, a successful `edit` or `write` schedules `codegraph sync` for the
+  git toplevel of the file touched, so a worktree syncs that worktree. The sync is
+  detached: the tool result never waits for it, and a failure never reaches you.
+- **Debounced and coalesced.** Rapid edits collapse into one sync after ~2s, and
+  an edit that lands while a sync runs starts exactly one more when it ends —
+  never a queue.
+- **One sync at a time across sessions**, guarded by
+  `<root>/.codegraph/pi-sync.lock` holding `{pid, startedAt}`. A lock held by a
+  live process means skip (the other session's sync already covers that tree),
+  with one bounded retry so the edit that raced it still lands. A dead pid or an
+  expired lock is taken over.
+- **Skipped when it would be wasted**: no `.codegraph/` in that checkout, or a
+  live CodeGraph daemon (`<root>/.codegraph/daemon.pid`, either the JSON record
+  1.6 writes or the older bare pid), whose own watcher is already syncing that
+  tree.
+- **Bounded**: a sync that never finishes is terminated after two minutes so a
+  checkout can never be wedged for the rest of the session.
+
+Three commands exist **only when the CLI is present**, and they do not appear at
+all otherwise:
+
+| Command | What it does |
+| --- | --- |
+| `/codegraph-hook` | Turns the edit/write sync on or off for the whole process. No argument toggles; `on`, `off` and `status` say it explicitly. It starts enabled. |
+| `/codegraph-init` | Runs `codegraph init` at the session's current directory. |
+| `/codegraph-sync` | Runs `codegraph sync` at the session's current directory. |
+
+The toggle lasts for the session — this package writes nothing to user
+configuration — so `CODEGRAPH_HOOK=0` is how you start a session with it off.
+
+### The `## ODD worktrees` block in the system prompt
+
+The primary session's system prompt gains a short section telling the agent where
+worktrees live, to resume an ODD in its assigned one, and — when `codegraph` is
+present — that creation indexes the checkout and edits sync it.
+
+It is **appended**, never substituted: the block rides
+`systemPromptOptions.appendSystemPrompt`, so whatever Gentle Shell (or any other
+extension) put there is preserved verbatim and our text lands after it. Two
+variants exist, with and without the CodeGraph sentences, chosen by the same
+session gate. Child and named-agent sessions get nothing, because their own
+instructions are already the bounded task they received. `ODD_WORKTREE_PROMPT=0`
+suppresses the block.
+
+One limit, stated plainly: a string has no "must be last" flag, so the block's
+position follows extension load order. It can sit before a later extension's
+short hint; it can never land inside or in place of another extension's text.
+
 ### Where state lives
 
 The worktree registry is per repository at `<git-common-dir>/pi-worktrees.json`,
 so every worktree of the same clone sees the same rows. Session names derived
 from an ODD write, and the warp's fork/resume bookkeeping, travel in the Pi
-session files the host already owns. Nothing is written to user configuration.
+session files the host already owns. The only other file this package writes is
+the short-lived `<root>/.codegraph/pi-sync.lock`. Nothing is written to user
+configuration.
 
 ### Deliberately absent
 
 This package is the worktree / ODD / issues surface only: no customize panel, no
 plugin-tools toggles, no Herdr plugin management, and no worktree↔issue
-association. There is nothing to configure, and the three commands are always on.
+association. There is nothing to configure, and `/warp`, `/odd-list` and
+`/issues` are always on (the three `/codegraph-*` commands follow the CLI).
 Paths, branches and arguments reach `git`, `herdr` and `gh` as fixed argv arrays,
 never as a shell string.
 

package/extensions/odd-worktree-tools.ts

@@ -7528,6 +7528,65 @@ function registerIssuesCommand(pi) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// `/codegraph-hook`, `/codegraph-init`, `/codegraph-sync` (T5 S9): the sync
+// hook's switch and the two on-demand CLI runs. The bodies live in
+// lib/codegraph-commands.js so they are testable without a host; this file only
+// registers them and hands their one-line result to the session UI.
+//
+// GATED REGISTRATION: the three commands do not exist at all in a session whose
+// gate says the `codegraph` CLI is absent, so they never appear in that
+// session's command list. The gate caches its answer per process (S3), so
+// asking at registration time costs one PATH probe for the whole session.
+function codegraphCommandsAvailable() {
+  try {
+    return libRequire("codegraph-session.js").hasCodegraph(process.env) === true;
+  } catch {
+    return false;
+  }
+}
+
+function registerCodegraphCommands(pi) {
+  if (typeof pi?.registerCommand !== "function") return;
+  if (!codegraphCommandsAvailable()) return;
+  const render = (ctx, result) => {
+    const notify = ctx && ctx.ui ? ctx.ui.notify : undefined;
+    if (typeof notify === "function") notify(result.text, result.level);
+    return result;
+  };
+  // A command never throws into the host: the lib returns a failure line
+  // instead of rejecting, and anything unforeseen is swallowed here.
+  const run = async (ctx, work) => {
+    try {
+      render(ctx, await work());
+    } catch {
+      // Nothing to report that the lib did not already describe.
+    }
+  };
+  pi.registerCommand("codegraph-hook", {
+    description: "Turn the automatic edit/write CodeGraph sync on or off: on, off, status (no argument toggles)",
+    handler: async (args, ctx) => {
+      await run(ctx, () => libRequire("codegraph-commands.js").codegraphHook(args));
+    },
+  });
+  pi.registerCommand("codegraph-init", {
+    description: "Initialize a CodeGraph index in this session's checkout: codegraph init .",
+    handler: async (args, ctx) => {
+      await run(ctx, () => libRequire("codegraph-commands.js").codegraphInit(args, ctx, {
+        run: libRunner(libRequire("worktree-git.js")),
+      }));
+    },
+  });
+  pi.registerCommand("codegraph-sync", {
+    description: "Sync this session's checkout CodeGraph index: codegraph sync .",
+    handler: async (args, ctx) => {
+      await run(ctx, () => libRequire("codegraph-commands.js").codegraphSync(args, ctx, {
+        run: libRunner(libRequire("worktree-git.js")),
+      }));
+    },
+  });
+}
+
 export default function (pi) {
   // A TOOL context has no session control, so `worktree_warp` queues the
   // `/warp` COMMAND through this handle (`sendUserMessage` with
@@ -7537,6 +7596,7 @@ export default function (pi) {
   registerWarpCommand(pi);
   registerOddCommand(pi);
   registerIssuesCommand(pi);
+  registerCodegraphCommands(pi);
   pi.registerTool(worktreeCreateTool);
   pi.registerTool(worktreeListTool);
   pi.registerTool(worktreeCloseTool);
@@ -7560,6 +7620,30 @@ export default function (pi) {
   });
   pi.on("tool_call", (event, ctx) => handleWorktreeOddEvent(event, ctx, pi));
   pi.on("tool_result", (event, ctx) => handleWorktreeOddEvent(event, ctx, pi, true));
+  // S1/S3: a successful edit or write asks for ONE background `codegraph sync`
+  // of that file's checkout. The call is fire-and-forget — never awaited, its
+  // decision never reaches the tool result, and a failure here is swallowed
+  // instead of surfacing as a broken edit.
+  pi.on("tool_result", (event) => {
+    try {
+      if (!event || (event.toolName !== "edit" && event.toolName !== "write")) return;
+      if (event.isError) return;
+      const filePath = event.input && event.input.path;
+      if (typeof filePath !== "string" || filePath.length === 0) return;
+      libRequire("codegraph-session.js").scheduleSync(filePath);
+    } catch {
+      // Index freshness is best effort and never touches the tool result.
+    }
+  });
+  // S7: the ODD worktree rules ride the prompt options, appended after the
+  // harness's own text. Sync mutation, so the host reads the final string.
+  pi.on("before_agent_start", (event) => {
+    try {
+      libRequire("odd-worktrees-prompt.js").appendOddWorktreesSection(event);
+    } catch {
+      // The prompt block is best effort.
+    }
+  });
   // Register every live checkout the registry does not own yet. Dispatched here
   // and awaited by the barrier below: the host runs session_start handlers one
   // at a time, so awaiting the scan inside this handler would put the session's

package/lib/codegraph-commands.js

@@ -0,0 +1,165 @@
+'use strict';
+// The three CodeGraph session commands' bodies (S9): `/codegraph-hook`,
+// `/codegraph-init` and `/codegraph-sync`.
+//
+// They are plain functions returning a render-ready result — `{ok, level,
+// text}` — so the extension only has to hand the line to `ctx.ui.notify`. The
+// registration itself is the extension's job and is gated on the session gate,
+// so a session without the CLI never lists these commands.
+//
+// `/codegraph-hook` flips the in-memory, process-wide switch owned by
+// `codegraph-session.js`: nothing is written to user configuration, and the
+// environment (`CODEGRAPH_HOOK=0`) is only the starting state.
+//
+// `init` and `sync` run the real CLI once, at the session's current directory,
+// through the injected `run` seam. The reported line is the child's real
+// outcome: a non-zero (or unstartable) child is a failure, and no path throws
+// into the command handler.
+
+const { isHookEnabled, setHookEnabled } = require('./codegraph-session.js');
+
+const CODEGRAPH_BIN = 'codegraph';
+const COMMANDS = { init: 'codegraph init', sync: 'codegraph sync' };
+
+function pick(deps, name, fallback) {
+  return deps && typeof deps[name] === 'function' ? deps[name] : fallback;
+}
+
+// The convention every other lib helper uses for its runner;
+// `runArgvAsync` resolves (never rejects) with `{status, stdout, stderr, error}`.
+function defaultRun(bin, args, cwd) {
+  return require('./worktree-git.js').runArgvAsync(bin, args, { cwd });
+}
+
+function sessionCwd(ctx) {
+  const cwd = ctx && ctx.cwd;
+  return typeof cwd === 'string' && cwd.length > 0 ? cwd : process.cwd();
+}
+
+// One line of child output, so a multi-line stack never becomes the message.
+function firstLine(text) {
+  const raw = String(text === undefined || text === null ? '' : text);
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.length > 0) return trimmed.length > 200 ? `${trimmed.slice(0, 200)}…` : trimmed;
+  }
+  return '';
+}
+
+function hookState() {
+  return isHookEnabled() ? 'enabled' : 'disabled';
+}
+
+// `/codegraph-hook` — no argument toggles; `on` and `off` set the state
+// explicitly; `status` only reports it.
+function codegraphHook(rawArgs) {
+  const raw = String(rawArgs === undefined || rawArgs === null ? '' : rawArgs).trim().toLowerCase();
+  if (raw === '' || raw === 'on' || raw === 'off') setHookEnabled(raw === '' ? !isHookEnabled() : raw === 'on');
+  else if (raw !== 'status') {
+    return { ok: false, level: 'error', text: `codegraph hook: unknown option "${raw}". Use on, off or status.` };
+  }
+  return { ok: true, level: 'info', text: `codegraph hook: ${hookState()}` };
+}
+
+// The CLI is chatty and decorative (a box around every line, ANSI colours, and
+// glyphs that change between releases), so the report is built from the plain
+// text it puts on stdout and stderr rather than from the exit status alone. The
+// captured shapes this reads:
+//
+//   init, fresh      "Initialized in <path>" / "Indexed N files" / "N nodes, M edges in Tms"
+//   init, indexed    "Already initialized in <path>" / "Use \"codegraph index\" to re-index ..."
+//   sync, clean      "Already up to date"
+//   sync, changed    "Synced N changed files" / "Modified: N — M nodes in Tms"
+//   sync, no index   "CodeGraph not initialized in <path>" (stderr, exit 1)
+const ANSI = /\u001b\[[0-9;]*[a-zA-Z]/g;
+
+function plain(text) {
+  return String(text === undefined || text === null ? '' : text).replace(ANSI, '');
+}
+
+function count(value, noun) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return '';
+  return `${n} ${noun}${n === 1 ? '' : 's'}`;
+}
+
+function summarize(label, out) {
+  const text = `${plain(out.stdout)}\n${plain(out.stderr)}`;
+  const path = (match) => (match && match[1] ? match[1].trim() : '');
+
+  const notIndexed = text.match(/not initialized in\s+(\S+)/i);
+  if (notIndexed) {
+    return { ok: false, level: 'error', text: `${label}: no index in this checkout — run /codegraph-init first` };
+  }
+  const already = text.match(/already initialized in\s+(\S+)/i);
+  if (already) {
+    return { ok: true, level: 'info', text: `${label}: already initialized at ${path(already)} — nothing to do, use /codegraph-sync to update` };
+  }
+  const upToDate = /already up to date/i.test(text);
+  if (upToDate) {
+    return { ok: true, level: 'info', text: `${label}: already up to date — nothing to sync` };
+  }
+  const synced = text.match(/synced\s+(\d+)\s+changed\s+files?/i);
+  if (synced) {
+    const nodes = text.match(/(\d+)\s+nodes?/i);
+    const counts = [count(synced[1], 'changed file'), nodes ? count(nodes[1], 'node') : ''].filter(Boolean).join(' — ');
+    return { ok: true, level: 'info', text: `${label}: synced ${counts}` };
+  }
+  const initialized = text.match(/initialized in\s+(\S+)/i);
+  if (initialized) {
+    const files = text.match(/indexed\s+(\d+)\s+files?/i);
+    const nodes = text.match(/(\d+)\s+nodes?/i);
+    const edges = text.match(/(\d+)\s+edges?/i);
+    const sorted = [
+      files ? count(files[1], 'file') : '',
+      nodes ? count(nodes[1], 'node') : '',
+      edges ? count(edges[1], 'edge') : '',
+    ].filter(Boolean).join(', ');
+    return { ok: true, level: 'info', text: `${label}: initialized ${path(initialized)}${sorted ? ` — ${sorted}` : ''}` };
+  }
+  return null;
+}
+
+async function runStep(verb, rawArgs, ctx, deps) {
+  const label = COMMANDS[verb];
+  const raw = String(rawArgs === undefined || rawArgs === null ? '' : rawArgs).trim();
+  if (raw !== '') return { ok: false, level: 'error', text: `${label}: takes no argument.` };
+
+  const cwd = sessionCwd(ctx);
+  let outcome;
+  try {
+    outcome = await pick(deps, 'run', defaultRun)(CODEGRAPH_BIN, [verb, '.'], cwd);
+  } catch (err) {
+    return { ok: false, level: 'error', text: `${label}: failed — ${firstLine((err && err.message) || String(err))}` };
+  }
+  const out = outcome && typeof outcome === 'object' ? outcome : {};
+  const summary = summarize(label, out);
+  // The CLI answers `sync` in a checkout with no index on stderr with exit 1,
+  // so the recognised message decides before the exit status does.
+  if (summary && (summary.ok || /no index/.test(summary.text))) return summary;
+  if (out.error) {
+    return { ok: false, level: 'error', text: `${label}: failed — ${firstLine(out.error) || 'unknown error'}` };
+  }
+  if (out.status !== 0) {
+    const exit = Number.isInteger(out.status) ? out.status : 'unknown';
+    const detail = firstLine(plain(out.stderr)) || firstLine(plain(out.stdout)) || 'no output';
+    return { ok: false, level: 'error', text: `${label}: exit ${exit} — ${detail}` };
+  }
+  return summary || { ok: true, level: 'info', text: `${label}: done` };
+}
+
+// `/codegraph-init` and `/codegraph-sync` — one awaited CLI run at the session's
+// current directory, reported by its real exit status.
+function codegraphInit(rawArgs, ctx, deps) {
+  return runStep('init', rawArgs, ctx, deps);
+}
+
+function codegraphSync(rawArgs, ctx, deps) {
+  return runStep('sync', rawArgs, ctx, deps);
+}
+
+module.exports = {
+  codegraphHook,
+  codegraphInit,
+  codegraphSync,
+};