@shiyuphan/follow-me 0.2.0 → 0.3.0

package/dist/src/cli.js

@@ -1,35 +1,53 @@
-import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { PlanRequestError, requestPlan } from "./anthropic.js";
-import { DiffParseError, formatUnitRef } from "./diff.js";
-import { BranchRefusedError, branchHead, GitError, signing, treeOf, writeBranch, } from "./git.js";
-import { fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postReply, probeHealth, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
-import { runInstall, runUninstall } from "./install.js";
+import { DiffParseError, formatUnitRef, isUnitId } from "./diff.js";
+import { BranchRefusedError, branchHead, GitError, isOwnWork, signing, treeOf, writeBranch, } from "./git.js";
+import { fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postReply, probeHealth, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
+import { runInstall, runUninstall, syncSkills } from "./install.js";
 import { naiveDraft } from "./naive.js";
 import { serializePlanFile, validatePlan } from "./plan.js";
-import { renderEvents, renderPrompt, renderReport } from "./prompt.js";
+import { renderEvents, renderPrompt, renderReport, reportItems, } from "./prompt.js";
 import { RegistrationError, sessionIdOf } from "./server.js";
 import { BranchMovedError, cleanSessions, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, } from "./session.js";
 import { checkSyntax } from "./syntax.js";
 class UsageError extends Error {
     name = "UsageError";
 }
+const SHORT_USAGE = `usage: follow-me [--wait <seconds>] [--branch <name>]
+
+Run follow-me with no command. Each call does the next thing that is missing and returns: it
+writes the prompt for you to answer, reports what is wrong with your draft, opens the review for
+the user, then listens to them for up to --wait seconds (default 60, 0 for none) and prints what
+they flagged or asked. Do what its "next:" line says. Run it again to keep listening.
+
+Other commands:
+  reply <commentId> --body <text> [--diagram <file>]
+                                            answer under a comment on the page; the diagram is
+                                            Mermaid source
+  explain [--commit <n>] [--unit <id>] [--lines <a-b>] --body <text> [--diagram <file>]
+                                            start a thread on the page without being asked
+  report [--json] [--markdown]              print the report of the latest review; --json lists
+                                            the items to post to a merge request
+
+help --all lists every command.`;
 const USAGE = `usage: follow-me <command> [options]
 
+follow-me with no command is the entry point; see \`follow-me help\`. The commands below are what it
+runs, for when you want one step by hand.
+
 Split your own branch:
-  split [--base <ref>] [--branch <name>] [--model <id>] [--no-open]
-                                            extract, draft (with an Anthropic key), apply and
-                                            open the review in one go
+  split [--base <ref>] [--branch <name>] [--no-open]
+                                            extract, apply your agent's draft and open the
+                                            review in one go; without a valid draft it writes
+                                            the prompt for your agent and stops
   extract [--base <ref>] [--branch <name>]  anchor a session and list the units
   prompt [--walk] [--branch <name>]         print the planner prompt; your coding agent
                                             writes draft.json from it
-  plan [--walk] [--model <id>] [--branch <name>]
-                                            the same draft as prompt, written by the
-                                            Anthropic API
-  plan --naive [--branch <name>]            no API, no agent: one "wip: <path>" commit per
-                                            touched file, in diff order
+  plan --naive [--branch <name>]            no agent: one "wip: <path>" commit per touched
+                                            file, in diff order
   check [path] [--branch <name>] [--syntax "<cmd {file}>"]
                                             validate draft.json or the given plan file, and
                                             check that every file each commit writes parses;
@@ -40,11 +58,11 @@ Split your own branch:
                                             --name; never on <branch> or a checked-out branch;
                                             refuses a commit with a file that does not parse
                                             unless --allow-syntax-errors
-  review [--port <n>] [--detach] [--no-open] [--wait [--timeout <seconds>]]
-                                            open the plan review, commit by commit; --wait
-                                            returns only once the review ends
-  feedback [--walk] [--branch <name>]       print the latest plan review as markdown, or with
-                                            --walk the latest code review
+  review [--base <ref>] [--branch <name>] [--port <n>] [--detach] [--no-open]
+         [--wait [--timeout <seconds>]]     open the review, commit by commit; --wait returns
+                                            only once the review ends. After apply it reviews
+                                            your split; otherwise it plans for a reader and
+                                            reviews the code, applying nothing
   status                                    show the session's plans, reviews, lock and the
                                             branch apply writes
 
@@ -58,15 +76,22 @@ Interactive loop (while the review page is open):
   reply <commentId> --body <text> [--diagram <file>]
                                             answer under a comment on the page; the diagram is
                                             Mermaid source
-  report                                    print the consolidated report of the open review, or
-                                            of the last one that ended: issues by file and line
-                                            in both voices, then questions with answers
+  explain [--commit <n>] [--unit <id>] [--lines <a-b>] --body <text> [--diagram <file>]
+                                            start a thread on the page without being asked;
+                                            --lines are change lines of the unit, commits count
+                                            from 1; with no target it is about the whole plan.
+                                            watch leaves these out like your replies
+  report [--json] [--markdown] [--branch <name>]
+                                            print the report of the open review, or of the last
+                                            one that ended. Markdown lists issues by file and
+                                            line in both voices, then questions with answers;
+                                            --json lists the items to post to a merge request
+                                            (path, lines, severity, body, thread, excluded)
   apply, while the page is open, swaps it to the new plan version in place, same URL.
 
-Review someone else's branch:
-  walk [--base <ref>] [--branch <name>] [--model <id>] [--port <n>] [--detach] [--no-open]
-                                            watch a branch being written, narrated, and
-                                            review its code; nothing is applied
+Old names, still working:
+  walk                                      is review; prints one line saying so
+  feedback [--walk]                         is report; prints one line saying so
 
 Review server:
   server status                             show the review server and the sessions it hosts
@@ -78,14 +103,17 @@ Setup:
   install --list                            show each harness, its skill dirs and docs
   uninstall [--harness <ids>|--all] [--project] [--dry-run]
                                             remove the skill files install writes
+  upgrade [--harness <ids>|--all] [--project] [--dry-run]
+                                            update the package with npm, then refresh the
+                                            installed skill copies
   clean [--all] [--dry-run]                 remove sessions of deleted branches, finished
                                             review drafts and leftovers of dead processes;
                                             --all removes .follow-me/ entirely
   --version                                 print the version
   help                                      print this
 
---walk writes the prompt for a reviewer: a story with narration instead of a split.
-review and walk share one server per user: a running one hosts the session and the command
+--walk writes the prompt for a reviewer: a story with notes instead of a split.
+review shares one server per user: a running one hosts the session and the command
 prints its URL; otherwise the command serves until its review ends, or with --detach starts the
 server in the background. --port taken by another program falls back to a free port.
 --force lets apply move a branch follow-me did not create; it never allows <branch> itself.
@@ -462,36 +490,27 @@ function promptInput(session, mode, args) {
     };
     if (mode === "walk")
         return { ...common, mode };
+    const previous = session.plans().at(-1);
     return {
         ...common,
         mode,
-        previousPlan: session.plans().at(-1)?.file ?? null,
+        previousPlan: previous?.file ?? null,
         review: session.lastReview(),
+        previousCommits: previous === undefined ? [] : projectedCommits(session, previous.version),
     };
 }
-/** Asks the API for draft.json, feeding issues back once. Returns the plan when it validates. */
-async function draftWithApi(session, cwd, mode, args) {
-    const model = args.values.get("model");
-    const opts = model === undefined ? {} : { model };
-    let prompt = renderPrompt(promptInput(session, mode, args));
-    for (let round = 1; round <= 2; round++) {
-        const draft = await requestPlan(prompt, opts);
-        session.writeDraft(draft);
-        const verdict = validate(session, draft);
-        if (verdict.ok) {
-            say(`wrote ${relative(cwd, session.draftPath)} (${plural(verdict.plan.commits.length, "commit")})`);
-            return verdict.plan;
-        }
-        const issues = verdict.issues.map((issue) => `- ${formatIssue(issue)}`).join("\n");
-        prompt = `${prompt}\n\n## Your previous draft had these issues, write a corrected plan\n\n${issues}\n`;
-    }
-    say(`wrote ${relative(cwd, session.draftPath)} but it still has issues, repair it and run \`follow-me check${branchFlag(args)}\``);
-    return null;
+/** The commits of a frozen plan as projected now, or none when it no longer fits the branch. */
+function projectedCommits(session, version) {
+    const plan = session.plans().find((p) => p.version === version);
+    if (plan === undefined)
+        return [];
+    const verdict = validatePlan(session.diff, serializePlanFile(plan.file));
+    return verdict.ok ? verdict.plan.commits : [];
 }
-/** Writes the one-commit-per-file draft with no API call and no agent. */
+/** Writes the one-commit-per-file draft with no agent. */
 function naive(session, cwd, args) {
-    if (args.flags.has("walk") || args.values.has("model")) {
-        throw new UsageError("--naive writes no story, so --walk and --model do not apply");
+    if (args.flags.has("walk")) {
+        throw new UsageError("--naive writes no story, so --walk does not apply");
     }
     const draft = naiveDraft(session.diff);
     session.writeDraft(draft);
@@ -503,14 +522,11 @@ function naive(session, cwd, args) {
     return 0;
 }
 async function plan(cwd, args) {
-    const session = await openSession(cwd, sessionOpts(args));
-    const mode = modeOf(args);
-    if (args.flags.has("naive"))
-        return naive(session, cwd, args);
-    if ((await draftWithApi(session, cwd, mode, args)) === null)
+    if (!args.flags.has("naive")) {
+        console.error("follow-me plan: there is no built-in model planner; your coding agent writes the draft from `follow-me prompt`, or use --naive for one commit per file");
         return 1;
-    next(mode === "walk" ? `follow-me walk${branchFlag(args)}` : "follow-me apply");
-    return 0;
+    }
+    return naive(await openSession(cwd, sessionOpts(args)), cwd, args);
 }
 /** The latest frozen plan, or the draft frozen now when it validates. */
 function latestPlan(session) {
@@ -524,8 +540,8 @@ function latestPlan(session) {
         return null;
     return { version: session.freeze(verdict.plan), plan: verdict.plan };
 }
-function announce(mode, url, args) {
-    say(`follow-me ${mode === "walk" ? "code review" : "review"}: ${url}`);
+function announce(url, args) {
+    say(`follow-me review: ${url}`);
     if (!args.flags.has("no-open"))
         openBrowser(url);
 }
@@ -548,10 +564,10 @@ async function hostReview(session, mode, args, prepare, report) {
     const home = stateDir();
     const open = await openOnServer(session, mode);
     if (open !== null) {
-        announce(mode, sessionUrl(open.port, open.summary), args);
+        announce(sessionUrl(open.port, open.summary), args);
         return { kind: "elsewhere", ...open };
     }
-    return locked(session, mode === "walk" ? "walk" : "review", async (held) => {
+    return locked(session, "review", async (held) => {
         const prepared = await prepare();
         if (prepared === null)
             return { kind: "refused" };
@@ -577,12 +593,12 @@ async function hostReview(session, mode, args, prepare, report) {
             started = await startOrAttach(home, port, say);
         if (started.kind === "attached") {
             const summary = await registerWith(started.port, registration);
-            announce(mode, sessionUrl(started.port, summary), args);
+            announce(sessionUrl(started.port, summary), args);
             return { kind: "elsewhere", port: started.port, summary };
         }
         const { host } = started;
         const { summary, done } = await host.register(registration);
-        announce(mode, sessionUrl(host.port, summary), args);
+        announce(sessionUrl(host.port, summary), args);
         const review = await done;
         if (review === null)
             return { kind: "stopped" };
@@ -601,13 +617,10 @@ function exitCode(hosted) {
     }
     return hosted.kind === "refused" || hosted.kind === "stopped" ? 1 : 0;
 }
-function alreadyReviewed(session, mode, version, args) {
-    if (!reviewsOf(session, mode).some((r) => r.version === version))
+function alreadyReviewed(session, version, args) {
+    if (!reviewsOf(session).some((r) => r.version === version))
         return false;
-    const branch = branchFlag(args);
-    console.error(mode === "walk"
-        ? `follow-me: plan v${version} already has a code review; read it with \`follow-me feedback --walk${branch}\``
-        : `follow-me: plan v${version} already has a review; read it with \`follow-me feedback${branch}\`, then run \`follow-me split${branch}\` for the next plan`);
+    console.error(`follow-me: plan v${version} already has a review; read it with \`follow-me report${branchFlag(args)}\``);
     return true;
 }
 /** This session's review, of this mode or any, on the user's server when that holds its lock. */
@@ -630,13 +643,15 @@ function timeoutOf(args) {
     }
     return seconds;
 }
-/** The reviews in this mode's slot, oldest first. */
-function reviewsOf(session, mode) {
-    return mode === "walk" ? session.walkReviews() : session.reviews();
+/** Every finished review, oldest first, including reviewer reviews older builds stored apart. */
+function reviewsOf(session) {
+    const seen = new Set();
+    return [...session.reviews(), ...session.walkReviews()]
+        .filter((r) => !seen.has(r.version) && seen.add(r.version))
+        .sort((a, b) => a.version - b.version);
 }
-function savedReview(session, mode, version) {
-    const stored = reviewsOf(session, mode).find((r) => r.version === version);
-    return stored?.review ?? null;
+function savedReview(session, version) {
+    return reviewsOf(session).find((r) => r.version === version)?.review ?? null;
 }
 /**
  * Polls the server until it no longer hosts the session, then reads the review it saved. Null
@@ -649,31 +664,47 @@ async function waitForEnd(session, hosted, timeout) {
             return "timeout";
         await new Promise((resolve) => setTimeout(resolve, 250));
     }
-    return savedReview(session, hosted.summary.mode, hosted.summary.version);
+    return savedReview(session, hosted.summary.version);
 }
-function reportSplit(review) {
+function reportSaved(review) {
     say(`review v${review.planVersion} saved with ${plural(review.comments.length, "comment")}`);
-    next("follow-me feedback");
+    next("follow-me report");
 }
 function prepareSplit(session, args) {
     return async () => {
         const latest = latestPlan(session);
-        if (latest === null || alreadyReviewed(session, "split", latest.version, args))
+        if (latest === null || alreadyReviewed(session, latest.version, args))
             return null;
         return latest;
     };
 }
+/**
+ * Author mode when a split branch was applied for the latest plan: the plan is the author's own
+ * and the review is of it. Otherwise the reader is a reviewer meeting the branch, so the plan only
+ * orders the reading and nothing is applied. The wire keeps calling that mode "walk".
+ */
+function reviewMode(session) {
+    const applied = session.applied();
+    const latest = session.plans().at(-1);
+    return applied !== null && latest !== undefined && applied.version === latest.version
+        ? "split"
+        : "walk";
+}
+/** Hosts the review of the session: the plan for its author, or the code for a reviewer. */
 async function review(cwd, args) {
-    const session = await openSession(cwd);
+    const session = await openFresh(cwd, args);
     const timeout = timeoutOf(args);
     if (timeout !== undefined && !args.flags.has("wait")) {
         throw new UsageError("--timeout only applies with --wait");
     }
-    const hosted = await hostReview(session, "split", args, prepareSplit(session, args), reportSplit);
+    const open = await openOnServer(session, null);
+    const mode = open?.summary.mode ?? reviewMode(session);
+    const prepare = mode === "split" ? prepareSplit(session, args) : () => walkPlan(session, args);
+    const hosted = await hostReview(session, mode, args, prepare, reportSaved);
     if (hosted.kind !== "elsewhere")
         return exitCode(hosted);
     if (!args.flags.has("wait")) {
-        next("end the review on the page, then follow-me feedback");
+        next("end the review on the page, then follow-me report");
         return 0;
     }
     const ended = await waitForEnd(session, hosted, timeout);
@@ -683,7 +714,7 @@ async function review(cwd, args) {
     }
     if (ended === null)
         return exitCode({ kind: "stopped" });
-    reportSplit(ended);
+    reportSaved(ended);
     return 0;
 }
 /** Why split needs a new draft before it can go on, or null when draft.json is ready. */
@@ -721,49 +752,255 @@ function draftNeed(session, cwd, args) {
 function handOff(session, cwd, args, why) {
     session.writePrompt(renderPrompt(promptInput(session, "split", args)));
     const prompt = relative(cwd, session.promptPath);
-    say(`${why}, and neither ANTHROPIC_API_KEY nor ANTHROPIC_AUTH_TOKEN is set to ask the API for one.`);
+    say(`${why}.`);
     say(`Have your coding agent follow ${prompt} and write ${relative(cwd, session.draftPath)}, then run:`);
     say(`  follow-me check${branchFlag(args)}`);
     say(`  follow-me split${branchFlag(args)}`);
     next(`hand ${prompt} to your agent`);
 }
 /**
- * The author's one command: extract, draft through the API when it can, apply, and open the
- * review on the user's server. It stops with a handoff whenever an agent has to write the draft.
+ * The author's one command: extract, apply the agent's draft, and open the review on the user's
+ * server. It stops with a handoff whenever there is no valid draft.
  */
 async function split(cwd, args) {
     const session = await openFresh(cwd, args);
     say(headline(session));
     const open = await openOnServer(session, "split");
     if (open !== null) {
-        announce("split", sessionUrl(open.port, open.summary), args);
-        next("end the review on the page, then follow-me feedback");
+        announce(sessionUrl(open.port, open.summary), args);
+        next("end the review on the page, then follow-me report");
         return 0;
     }
     const need = draftNeed(session, cwd, args);
     if (need === "invalid")
         return 1;
     if (need !== null) {
-        if (!hasApiCredentials()) {
-            handOff(session, cwd, args, need);
-            return 1;
-        }
-        say(`${need}; asking the Anthropic API for one`);
-        const drafted = await draftWithApi(session, cwd, "split", args);
-        if (drafted === null)
-            return 1;
-        listPlan(drafted);
+        handOff(session, cwd, args, need);
+        return 1;
     }
     const applied = await locked(session, "apply", () => applyLocked(session, args));
     if (applied !== 0)
         return applied;
     const detached = { ...args, flags: new Set([...args.flags, "detach"]) };
-    const hosted = await hostReview(session, "split", detached, prepareSplit(session, args), reportSplit);
+    const hosted = await hostReview(session, "split", detached, prepareSplit(session, args), reportSaved);
     if (hosted.kind !== "elsewhere")
         return exitCode(hosted);
-    next("end the review on the page, then follow-me feedback");
+    next("end the review on the page, then follow-me report");
+    return 0;
+}
+/** The mode a bare `follow-me` works in: a split already applied, else whoever wrote the branch. */
+async function entryMode(session, args) {
+    if (args.flags.has("author") && args.flags.has("reviewer")) {
+        throw new UsageError("--author and --reviewer cannot be used together");
+    }
+    if (args.flags.has("reviewer"))
+        return "walk";
+    if (args.flags.has("author"))
+        return "split";
+    if (reviewMode(session) === "split")
+        return "split";
+    return (await isOwnWork(session.root, session.anchor.base, session.anchor.tip))
+        ? "split"
+        : "walk";
+}
+function draftState(session) {
+    let draft;
+    try {
+        draft = session.readDraft();
+    }
+    catch (error) {
+        if (error instanceof MissingDraftError)
+            return { kind: "missing" };
+        throw error;
+    }
+    const verdict = validatePlan(session.diff, draft, { lastReview: session.lastReview() });
+    if (verdict.ok)
+        return { kind: "valid", prepared: verdict.plan };
+    if (verdict.issues.some((issue) => issue.kind === "stale"))
+        return { kind: "stale" };
+    for (const issue of verdict.issues)
+        say(formatIssue(issue));
+    return { kind: "invalid" };
+}
+/** The newest review of a plan that still fits the branch, or null. */
+function reviewedPlan(session) {
+    const reviews = reviewsOf(session);
+    for (const stored of reviews.toReversed()) {
+        const plan = session.plans().find((p) => p.version === stored.version);
+        if (plan !== undefined && validatePlan(session.diff, serializePlanFile(plan.file)).ok) {
+            return stored;
+        }
+    }
+    return null;
+}
+/** Prints the finished review's report, which is what the agent works from from here on. */
+function finished(session, stored) {
+    const text = renderStored(session, stored);
+    if (text === null)
+        return 1;
+    say(`review v${stored.version} ended with ${plural(stored.review.comments.length, "comment")}`);
+    process.stdout.write(text);
+    say();
+    next("done; the user can port it with follow-me report --json");
+    return 0;
+}
+/** Writes the prompt for the agent and says where; used whenever there is no plan to review. */
+function promptHandoff(session, cwd, mode, args) {
+    session.writePrompt(renderPrompt(promptInput(session, mode, args)));
+    const prompt = relative(cwd, session.promptPath);
+    const draft = relative(cwd, session.draftPath);
+    say(`wrote ${prompt}`);
+    next(`write ${draft} from ${prompt}, then run follow-me again`);
     return 0;
 }
+function cursorPath(session) {
+    return join(session.dir, "cursor.json");
+}
+/** Where the last `follow-me` stopped reading this hosted session's events; 0 for a new one. */
+function readCursor(session, summary) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(cursorPath(session), "utf8"));
+    }
+    catch {
+        return 0;
+    }
+    if (typeof raw !== "object" || raw === null)
+        return 0;
+    const seen = "session" in raw ? raw.session : undefined;
+    const seq = "seq" in raw ? raw.seq : undefined;
+    const same = seen === `${summary.id}@${summary.openedAt}`;
+    return same && typeof seq === "number" && Number.isInteger(seq) && seq >= 0 ? seq : 0;
+}
+function writeCursor(session, summary, seq) {
+    const cursor = { session: `${summary.id}@${summary.openedAt}`, seq };
+    writeFileSync(cursorPath(session), `${JSON.stringify(cursor)}\n`);
+}
+function waitOf(args) {
+    const raw = args.values.get("wait");
+    if (raw === undefined)
+        return ENTRY_WAIT_SECONDS;
+    const seconds = Number(raw);
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        throw new UsageError(`--wait ${raw} is not a number of seconds`);
+    }
+    return seconds;
+}
+const ENTRY_WAIT_SECONDS = 60;
+/**
+ * Listens to the hosted review for up to --wait seconds and prints what the reviewer did. It
+ * returns at once with news, and with the report when the reviewer submitted or ended the review.
+ */
+async function listen(session, open, args) {
+    const { port, summary } = open;
+    const waitMs = waitOf(args) * 1000;
+    const deadline = Date.now() + waitMs;
+    let since = readCursor(session, summary);
+    let version = summary.version;
+    for (;;) {
+        const left = Math.max(0, deadline - Date.now());
+        let batch;
+        try {
+            batch = await pollEvents(port, summary, since, Math.min(left, POLL_MS));
+        }
+        catch (error) {
+            if (!(error instanceof RegistrationError))
+                throw error;
+            // The log restarted under us (a new server); read it from the start.
+            since = 0;
+            writeCursor(session, summary, 0);
+            continue;
+        }
+        since = batch.seq;
+        writeCursor(session, summary, since);
+        for (const event of batch.events)
+            if (event.type === "version")
+                version = event.version;
+        const news = batch.events.filter(isNews);
+        if (news.length > 0) {
+            const ctx = { commits: projectedCommits(session, version), units: session.diff.units };
+            process.stdout.write(renderEvents(news, ctx));
+            const ended = news.some((e) => e.type === "ended");
+            if (ended || news.some((e) => e.type === "submitted")) {
+                say();
+                if (ended) {
+                    const stored = reviewsOf(session).find((r) => r.version === version);
+                    if (stored !== undefined)
+                        return finished(session, stored);
+                }
+                process.stdout.write(await fetchReport(port, summary));
+                say();
+                next("done; the user can port it with follow-me report --json");
+                return 0;
+            }
+            next('answer with follow-me reply <id> --body "<markdown>" [--diagram file], or run follow-me again to keep listening');
+            return 0;
+        }
+        if (left <= 0) {
+            say(`nothing new on the review page in ${Math.round(waitMs / 1000)}s`);
+            next("run follow-me again to keep listening");
+            return 0;
+        }
+    }
+}
+/**
+ * The agent's one command. Each call does the next thing that is missing and returns: it writes
+ * the prompt, reports a bad draft, applies and opens the review, then listens to the reviewer
+ * and hands back the report once the review is submitted.
+ */
+async function entry(cwd, args) {
+    syncSkills(homedir(), say);
+    const session = await openFresh(cwd, args);
+    const hosted = await openOnServer(session, null);
+    if (hosted !== null)
+        return listen(session, hosted, args);
+    const mode = await entryMode(session, args);
+    const state = draftState(session);
+    if (state.kind === "invalid") {
+        next("fix the draft, then run follow-me again");
+        return 1;
+    }
+    const done = reviewedPlan(session);
+    if (state.kind === "valid") {
+        const reviewed = reviewsOf(session).find((r) => session.plans().find((p) => p.version === r.version)?.hash === state.prepared.hash);
+        if (reviewed !== undefined)
+            return finished(session, reviewed);
+    }
+    else if (done !== null) {
+        return finished(session, done);
+    }
+    let prepared = null;
+    if (state.kind === "valid") {
+        const syntax = await checkSyntax(state.prepared, syntaxOverride(args));
+        if (syntax.issues.length > 0) {
+            for (const line of formatSyntax(syntax))
+                say(line);
+            next("fix the draft, then run follow-me again");
+            return 1;
+        }
+        if (mode === "split") {
+            const code = await locked(session, "apply", () => applyLocked(session, args));
+            if (code !== 0) {
+                next("fix the draft, then run follow-me again");
+                return code;
+            }
+            prepared = latestPlan(session);
+        }
+        else
+            prepared = { version: session.freeze(state.prepared), plan: state.prepared };
+    }
+    else if (mode === "walk") {
+        prepared = walkablePlan(session);
+    }
+    if (prepared === null)
+        return promptHandoff(session, cwd, mode, args);
+    const prep = prepared;
+    const detached = { ...args, flags: new Set([...args.flags, "detach"]) };
+    const result = await hostReview(session, mode, detached, async () => prep, reportSaved);
+    if (result.kind !== "elsewhere")
+        return exitCode(result);
+    return listen(session, result, args);
+}
 /** Opens the session, re-extracting instead of failing when the branch moved or --base changed. */
 async function openFresh(cwd, args) {
     const opts = sessionOpts(args);
@@ -801,41 +1038,24 @@ function walkablePlan(session) {
     const verdict = validatePlan(session.diff, draft, { lastReview });
     return verdict.ok ? { version: session.freeze(verdict.plan), plan: verdict.plan } : null;
 }
-function hasApiCredentials() {
-    return Boolean(process.env["ANTHROPIC_API_KEY"] || process.env["ANTHROPIC_AUTH_TOKEN"]);
-}
+/** The old name of review; it prints one line saying so and goes on. */
 async function walk(cwd, args) {
-    const session = await openFresh(cwd, args);
-    const report = (review) => {
-        const saved = join(session.reviewsDir("walk"), `v${review.planVersion}.json`);
-        say(`code review saved to ${relative(cwd, saved)} with ${plural(review.comments.length, "comment")}`);
-        next(`follow-me feedback --walk${branchFlag(args)}, which prints it as a code review for the author`);
-    };
-    const hosted = await hostReview(session, "walk", args, () => walkPlan(session, cwd, args), report);
-    if (hosted.kind === "elsewhere") {
-        next(`end the code review on the page, then follow-me feedback --walk${branchFlag(args)}`);
-    }
-    return exitCode(hosted);
+    console.error("follow-me: walk is now review; running review");
+    return review(cwd, args);
 }
-async function walkPlan(session, cwd, args) {
-    let latest = walkablePlan(session);
+async function walkPlan(session, args) {
+    const latest = walkablePlan(session);
     if (latest === null) {
-        if (!hasApiCredentials()) {
-            say(`no plan for ${session.anchor.branch} yet, and neither ANTHROPIC_API_KEY nor ANTHROPIC_AUTH_TOKEN is set to ask the API for one.`);
-            say("Have a coding agent follow the prompt, then walk again:");
-            say(`  follow-me prompt --walk${branchFlag(args)}`);
-            say(`  follow-me walk${branchFlag(args)}`);
-            return null;
-        }
-        const drafted = await draftWithApi(session, cwd, "walk", args);
-        if (drafted === null)
-            return null;
-        latest = { version: session.freeze(drafted), plan: drafted };
+        say(`no plan for ${session.anchor.branch} yet.`);
+        say("Have a coding agent follow the prompt, then review again:");
+        say(`  follow-me prompt --walk${branchFlag(args)}`);
+        say(`  follow-me review${branchFlag(args)}`);
+        return null;
     }
-    return alreadyReviewed(session, "walk", latest.version, args) ? null : latest;
+    return alreadyReviewed(session, latest.version, args) ? null : latest;
 }
 /** The consolidated report of a saved review, or null after saying why it cannot be rendered. */
-function renderStored(session, stored) {
+function renderStored(session, stored, format = "markdown") {
     const plan = session.plans().find((p) => p.version === stored.version);
     if (plan === undefined) {
         console.error(`follow-me: review v${stored.version} refers to a plan that is missing`);
@@ -851,59 +1071,54 @@ function renderStored(session, stored) {
         .plans()
         .filter((p) => p.version > stored.version)
         .flatMap((p) => p.file.responses);
-    return renderReport(stored.review, verdict.plan.commits, session.diff.units, {
-        branch: session.anchor.branch,
-        responses,
-    });
-}
-async function feedback(cwd, args) {
-    const session = await openSession(cwd, sessionOpts(args));
-    const walk = args.flags.has("walk");
-    const walks = session.walkReviews();
-    const stored = walk ? walks.at(-1) : session.reviews().findLast((r) => r.review.mode === "split");
-    if (stored === undefined) {
-        const branch = branchFlag(args);
-        console.error(walk
-            ? `follow-me: no code review yet, run \`follow-me walk${branch}\` first`
-            : walks.length > 0
-                ? `follow-me: no plan review yet; \`follow-me feedback --walk${branch}\` prints the code review`
-                : "follow-me: no review yet, run `follow-me review` first");
-        return 1;
+    const opts = { branch: session.anchor.branch, responses };
+    if (format === "json") {
+        const items = reportItems(stored.review, verdict.plan.commits, session.diff.units, opts);
+        return `${JSON.stringify(items, null, 2)}\n`;
     }
-    const text = renderStored(session, stored);
-    if (text === null)
-        return 1;
-    process.stdout.write(text);
-    say();
-    next(stored.review.mode === "walk"
-        ? "hand this to the branch's author"
-        : `hand this to your agent, then follow-me check${branchFlag(args)}`);
-    return 0;
+    return renderReport(stored.review, verdict.plan.commits, session.diff.units, opts);
 }
-/** The consolidated report of the hosted review as it stands, else of the last one that ended. */
-async function report(cwd, args) {
+/**
+ * The report of the hosted review as it stands, else of the latest one that ended. --json lists
+ * the items to carry to a merge request; --markdown, the default, reads as the agent's to-do.
+ * --walk keeps reading only reviewer-mode reviews, as `feedback --walk` did.
+ */
+async function report(cwd, args, walkOnly = false) {
+    if (args.flags.has("json") && args.flags.has("markdown")) {
+        throw new UsageError("--json and --markdown cannot be used together");
+    }
     const session = await openSession(cwd, sessionOpts(args));
-    const open = await openOnServer(session, null);
+    const format = args.flags.has("json") ? "json" : "markdown";
+    const open = walkOnly ? null : await openOnServer(session, null);
     if (open !== null) {
-        process.stdout.write(await fetchReport(open.port, open.summary));
+        const text = await fetchReport(open.port, open.summary, format);
+        process.stdout.write(format === "json" ? `${JSON.stringify(JSON.parse(text), null, 2)}\n` : text);
         return 0;
     }
-    const ended = [...session.reviews(), ...session.walkReviews()].sort((a, b) => a.review.endedAt.localeCompare(b.review.endedAt));
+    const ended = (walkOnly ? session.walkReviews() : reviewsOf(session)).sort((a, b) => a.review.endedAt.localeCompare(b.review.endedAt));
     const stored = ended.at(-1);
     if (stored === undefined) {
         console.error("follow-me: no review is open and none has ended; run `follow-me review` first");
         return 1;
     }
-    const text = renderStored(session, stored);
+    const text = renderStored(session, stored, format);
     if (text === null)
         return 1;
     process.stdout.write(text);
     return 0;
 }
-/** Events the reviewer caused; the agent's own replies and version swaps are not news to it. */
+/** The old name of report. */
+async function feedback(cwd, args) {
+    console.error("follow-me: feedback is now report; printing the same");
+    return report(cwd, args, args.flags.has("walk"));
+}
+/** Events the reviewer caused; the agent's own replies, explanations and version swaps are not news. */
 function isNews(event) {
     if (event.type === "version")
         return false;
+    if (event.type === "comment" || event.type === "comment-updated") {
+        return event.comment.author !== "agent";
+    }
     return !(event.type === "reply" && event.reply.author === "agent");
 }
 const POLL_MS = 25_000;
@@ -926,17 +1141,26 @@ async function watch(cwd, args) {
     if (!Number.isInteger(since) || since < 0) {
         throw new UsageError(`--since ${sinceRaw} is not an event number`);
     }
+    // Comments are quoted as the plan they were made on wrote them; a swap changes which that is.
+    let version = open.summary.version;
+    const quoting = (events) => {
+        for (const event of events)
+            if (event.type === "version")
+                version = event.version;
+        return { commits: projectedCommits(session, version), units: session.diff.units };
+    };
     if (args.flags.has("follow")) {
         let ended = false;
         await followEvents(open.port, open.summary, since, (event) => {
             if (event.type === "ended")
                 ended = true;
+            const ctx = quoting([event]);
             if (!isNews(event))
                 return;
             if (args.flags.has("json"))
                 say(JSON.stringify(event));
             else
-                process.stdout.write(renderEvents([event]));
+                process.stdout.write(renderEvents([event], ctx));
         });
         if (ended)
             return 0;
@@ -952,6 +1176,7 @@ async function watch(cwd, args) {
         }
         const batch = await pollEvents(open.port, open.summary, since, Math.min(left, POLL_MS));
         since = batch.seq;
+        const ctx = quoting(batch.events);
         const news = batch.events.filter(isNews);
         if (news.length === 0)
             continue;
@@ -959,7 +1184,7 @@ async function watch(cwd, args) {
             for (const event of news)
                 say(JSON.stringify(event));
         else {
-            process.stdout.write(renderEvents(news));
+            process.stdout.write(renderEvents(news, ctx));
             next(news.some((e) => e.type === "ended")
                 ? "follow-me report"
                 : `follow-me reply <comment> --body <text>, or write a new draft and apply; then follow-me watch --since ${since}`);
@@ -974,16 +1199,7 @@ async function reply(cwd, args) {
     if (commentId === undefined || extra !== undefined || body === undefined) {
         throw new UsageError("usage: follow-me reply <commentId> --body <text> [--diagram <file>]");
     }
-    const diagramFile = args.values.get("diagram");
-    let diagram;
-    if (diagramFile !== undefined) {
-        try {
-            diagram = readFileSync(diagramFile, "utf8");
-        }
-        catch (error) {
-            throw new UsageError(`cannot read ${diagramFile}: ${error instanceof Error ? error.message : error}`);
-        }
-    }
+    const diagram = diagramOf(args);
     const session = await openSession(cwd, sessionOpts(args));
     const open = await openOnServer(session, null);
     if (open === null)
@@ -997,6 +1213,123 @@ async function reply(cwd, args) {
     next("follow-me watch");
     return 0;
 }
+/** The Mermaid source in --diagram's file, or undefined without the flag. */
+function diagramOf(args) {
+    const file = args.values.get("diagram");
+    if (file === undefined)
+        return undefined;
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch (error) {
+        throw new UsageError(`cannot read ${file}: ${error instanceof Error ? error.message : error}`);
+    }
+}
+/** "3" or "2-5" as the change indices they name. */
+function parseLineRange(raw) {
+    const m = /^(\d+)(?:-(\d+))?$/.exec(raw);
+    const from = Number(m?.[1]);
+    const to = Number(m?.[2] ?? m?.[1]);
+    if (m === null || to < from) {
+        throw new UsageError(`--lines ${raw} is not a change line or a range like 2-5`);
+    }
+    return Array.from({ length: to - from + 1 }, (_, i) => from + i);
+}
+/**
+ * Where an explanation points: --unit with --lines names change lines of a hunk, as the prompt
+ * numbers them, and the page marks their rows. --commit alone is the commit itself; nothing is
+ * the whole plan. Commits count from 1, as the prompt prints them.
+ */
+function explainTarget(session, version, args) {
+    const commitRaw = args.values.get("commit");
+    const unitRaw = args.values.get("unit");
+    const linesRaw = args.values.get("lines");
+    if (linesRaw !== undefined && unitRaw === undefined) {
+        throw new UsageError("--lines needs --unit");
+    }
+    if (commitRaw === undefined && unitRaw === undefined) {
+        return { anchor: { kind: "plan" }, context: { commitMessage: "", path: null } };
+    }
+    const commits = projectedCommits(session, version);
+    if (commits.length === 0) {
+        throw new UsageError(`plan v${version} no longer fits ${session.anchor.branch}`);
+    }
+    const unit = unitRaw === undefined || !isUnitId(unitRaw) ? undefined : session.diff.units.get(unitRaw);
+    if (unitRaw !== undefined && unit === undefined) {
+        throw new UsageError(`--unit ${unitRaw} is not a unit of this branch`);
+    }
+    let index = -1;
+    if (commitRaw !== undefined) {
+        index = Number(commitRaw) - 1;
+        if (!Number.isInteger(index) || index < 0 || index >= commits.length) {
+            throw new UsageError(`--commit ${commitRaw} is not one of the ${commits.length} commits`);
+        }
+    }
+    else {
+        index = commits.findIndex((c) => c.refs.some((r) => r.unit === unit?.id));
+    }
+    const commit = commits[index];
+    if (commit === undefined)
+        throw new UsageError(`no commit of plan v${version} takes ${unitRaw}`);
+    if (unit === undefined) {
+        return {
+            anchor: { kind: "message", commit: index },
+            context: { commitMessage: commit.message, path: null },
+        };
+    }
+    const ref = commit.refs.find((r) => r.unit === unit.id);
+    if (ref === undefined)
+        throw new UsageError(`commit ${index + 1} does not take ${unit.id}`);
+    const context = { commitMessage: commit.message, path: unit.path };
+    if (linesRaw === undefined) {
+        return { anchor: { kind: "hunk", unit: unit.id, commit: index, changes: null }, context };
+    }
+    if (unit.kind !== "hunk")
+        throw new UsageError(`--lines needs a text hunk, ${unit.id} is not one`);
+    const changes = parseLineRange(linesRaw);
+    const taken = ref.select.kind === "lines" ? ref.select.changes : null;
+    for (const n of changes) {
+        if (n >= unit.changeCount || (taken !== null && !taken.includes(n))) {
+            throw new UsageError(`commit ${index + 1} does not take change line ${n} of ${unit.id}`);
+        }
+    }
+    const rows = unit.body.flatMap((line, offset) => line.op !== " " && changes.includes(line.change) ? [{ line, offset }] : []);
+    return {
+        anchor: {
+            kind: "hunk",
+            unit: unit.id,
+            commit: index,
+            changes,
+            offsets: rows.map((r) => r.offset),
+        },
+        context: {
+            ...context,
+            lines: rows.map(({ line }) => `${line.op}${line.text.replace(/\r?\n$/, "")}`),
+        },
+    };
+}
+/** Starts a thread on the hosted page: the agent explains before anyone asks. */
+async function explain(cwd, args) {
+    const body = args.values.get("body");
+    if (body === undefined || args.positionals.length > 0) {
+        throw new UsageError("usage: follow-me explain [--commit <n>] [--unit <id>] [--lines <a-b>] --body <text> [--diagram <file>]");
+    }
+    const diagram = diagramOf(args);
+    const session = await openSession(cwd, sessionOpts(args));
+    const open = await openOnServer(session, null);
+    if (open === null)
+        return notOpen(session);
+    const target = explainTarget(session, open.summary.version, args);
+    const id = await postComment(open.port, open.summary, {
+        ...target,
+        body,
+        author: "agent",
+        ...(diagram === undefined ? {} : { diagram }),
+    });
+    say(`explained ${id}`);
+    next("follow-me watch");
+    return 0;
+}
 function describeLock(lock) {
     if (lock.kind === "free")
         return "free";
@@ -1111,17 +1444,53 @@ function skillTargets(args) {
     };
 }
 function missingDraft(error, cwd) {
-    return `no draft at ${relative(cwd, error.path)} yet; your coding agent writes it from \`follow-me prompt\`, or \`follow-me plan\` has the Anthropic API write it`;
+    return `no draft at ${relative(cwd, error.path)} yet; your coding agent writes it from \`follow-me prompt\`, or \`follow-me plan --naive\` writes one commit per file`;
 }
+const PACKAGE_NAME = "@shiyuphan/follow-me";
+/**
+ * Updates the global package, then refreshes every installed skill copy, which otherwise
+ * stays at the old version. FOLLOW_ME_UPGRADE_COMMAND replaces the npm call in tests.
+ */
+function upgrade(targets, cwd) {
+    const override = process.env["FOLLOW_ME_UPGRADE_COMMAND"];
+    const command = override === undefined
+        ? ["npm", "install", "-g", `${PACKAGE_NAME}@latest`]
+        : ["sh", "-c", override];
+    const [file, ...args] = command;
+    if (file === undefined)
+        return 1;
+    say(`${targets.dryRun ? "would run" : "running"}: ${override ?? command.join(" ")}`);
+    if (!targets.dryRun) {
+        try {
+            execFileSync(file, args, { stdio: "inherit" });
+        }
+        catch (error) {
+            console.error(`follow-me: upgrade failed: ${error instanceof Error ? error.message : error}`);
+            return 1;
+        }
+    }
+    const code = runInstall({ ...targets, list: false }, homedir(), cwd, say);
+    if (code === 0)
+        say(`next: follow-me --version`);
+    return code;
+}
+const HELP_OR_VERSION = new Set(["--help", "--version"]);
 export async function main(argv, cwd) {
     const [command, ...rest] = argv;
     try {
+        if (command === undefined || (command.startsWith("--") && !HELP_OR_VERSION.has(command))) {
+            const spec = {
+                values: ["wait", "base", "branch", "port", "syntax", "name"],
+                flags: ["no-open", "author", "reviewer", "allow-syntax-errors", "force", "sign", "no-sign"],
+            };
+            return await entry(cwd, parseArgs(argv, spec));
+        }
         switch (command) {
             case "extract": {
                 const args = parseArgs(rest, { values: ["base", "branch"] });
                 summarize(await extractSession(cwd, sessionOpts(args)), cwd);
                 const branch = branchFlag(args);
-                next(`follow-me prompt${branch}, or follow-me plan${branch} with an Anthropic key`);
+                next(`follow-me prompt${branch}, or follow-me plan --naive${branch}`);
                 return 0;
             }
             case "check":
@@ -1141,34 +1510,41 @@ export async function main(argv, cwd) {
                 return 0;
             }
             case "plan":
-                return await plan(cwd, parseArgs(rest, { values: ["model", "branch"], flags: ["walk", "naive"] }));
+                return await plan(cwd, parseArgs(rest, { values: ["branch"], flags: ["walk", "naive"] }));
             case "split": {
                 const spec = {
-                    values: ["base", "branch", "model", "syntax"],
+                    values: ["base", "branch", "syntax"],
                     flags: ["no-open", "allow-syntax-errors"],
                 };
                 return await split(cwd, parseArgs(rest, spec));
             }
             case "review": {
-                const spec = { values: ["port", "timeout"], flags: ["no-open", "detach", "wait"] };
+                const spec = {
+                    values: ["base", "branch", "port", "timeout"],
+                    flags: ["no-open", "detach", "wait"],
+                };
                 return await review(cwd, parseArgs(rest, spec));
             }
             case "walk": {
-                const spec = { values: ["base", "branch", "model", "port"], flags: ["no-open", "detach"] };
+                const spec = { values: ["base", "branch", "port"], flags: ["no-open", "detach"] };
                 return await walk(cwd, parseArgs(rest, spec));
             }
             case "server":
                 return await serverCommand(rest);
             case "feedback":
-                return await feedback(cwd, parseArgs(rest, { values: ["branch"], flags: ["walk"] }));
+                return await feedback(cwd, parseArgs(rest, { values: ["branch"], flags: ["walk", "json", "markdown"] }));
             case "watch": {
                 const spec = { values: ["since", "timeout", "branch"], flags: ["json", "follow"] };
                 return await watch(cwd, parseArgs(rest, spec));
             }
             case "reply":
                 return await reply(cwd, parseArgs(rest, { values: ["body", "diagram", "branch"] }));
+            case "explain": {
+                const spec = { values: ["commit", "unit", "lines", "body", "diagram", "branch"] };
+                return await explain(cwd, parseArgs(rest, spec));
+            }
             case "report":
-                return await report(cwd, parseArgs(rest, { values: ["branch"] }));
+                return await report(cwd, parseArgs(rest, { values: ["branch"], flags: ["json", "markdown"] }));
             case "clean": {
                 const args = parseArgs(rest, { flags: ["all", "dry-run"] });
                 const opts = { all: args.flags.has("all"), dryRun: args.flags.has("dry-run") };
@@ -1187,18 +1563,21 @@ export async function main(argv, cwd) {
                 const args = parseArgs(rest, { values: ["harness"], flags: ["all", "project", "dry-run"] });
                 return runUninstall(skillTargets(args), homedir(), cwd, say);
             }
-            case undefined:
+            case "upgrade": {
+                const args = parseArgs(rest, { values: ["harness"], flags: ["all", "project", "dry-run"] });
+                return upgrade(skillTargets(args), cwd);
+            }
             case "help":
             case "-h":
             case "--help":
-                say(USAGE);
-                return command === undefined ? 1 : 0;
+                say(parseArgs(rest, { flags: ["all"] }).flags.has("all") ? USAGE : SHORT_USAGE);
+                return 0;
             case "-v":
             case "--version":
                 say(`follow-me ${version()}`);
                 return 0;
             default:
-                throw new UsageError(`unknown command "${command}"\n${USAGE}`);
+                throw new UsageError(`unknown command "${command}"\n${SHORT_USAGE}`);
         }
     }
     catch (error) {
@@ -1210,7 +1589,6 @@ export async function main(argv, cwd) {
             SessionLockedError,
             RegistrationError,
             GitError,
-            PlanRequestError,
             NotARepositoryError,
         ];
         if (error instanceof MissingDraftError) {