@shiyuphan/follow-me 0.4.0 → 0.5.0

package/dist/src/cli.js

@@ -5,11 +5,11 @@ import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DiffParseError, formatUnitRef, isUnitId } from "./diff.js";
 import { BranchRefusedError, branchHead, GitError, isOwnWork, signing, treeOf, writeBranch, } from "./git.js";
-import { fetchCarried, fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postReply, probeHealth, readServerRecord, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
-import { runInstall, runUninstall, syncSkills } from "./install.js";
+import { fetchCarried, fetchComments, fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postReply, probeHealth, readServerRecord, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
+import { findSkillDir, InstallError, runInstall, runUninstall, syncSkills, } from "./install.js";
 import { naiveDraft } from "./naive.js";
-import { isFields, serializePlanFile, validatePlan } from "./plan.js";
-import { renderEvents, renderPrompt, renderReport, reportItems, } from "./prompt.js";
+import { isCommentId, isConcernId, isFields, serializePlanFile, validatePlan, } from "./plan.js";
+import { renderEvents, renderPrompt, renderReport, renderShownComment, renderShownConcern, renderShownUnit, reportItems, } from "./prompt.js";
 import { RegistrationError, sessionIdOf } from "./server.js";
 import { BranchMovedError, cleanSessions, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, sinceLastPlan, } from "./session.js";
 import { checkSyntax } from "./syntax.js";
@@ -30,6 +30,9 @@ Other commands:
                                             Mermaid source
   explain [--commit <n>] [--unit <id>] [--lines <a-b>] --body <text> [--diagram <file>]
                                             start a thread on the page without being asked
+  show <h_…|c_…|k_…|path:line[@n|@base]>   print a unit, a comment's thread, a concern, or the
+                                            lines around path:line in commit n, instead of
+                                            reading files
   report [--json] [--markdown]              print the report of the latest review; --json lists
                                             the items to post to a merge request
 
@@ -82,6 +85,11 @@ Interactive loop (while the review page is open):
                                             --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
+  show <h_…|c_…|k_…|path:line[@n|@base]> [--branch <name>]
+                                            print a unit with the commits that take it, a
+                                            comment with its rows and thread, a concern with its
+                                            lines, or the lines around path:line at the tip, in
+                                            commit n of the plan, or in the base
   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
@@ -425,7 +433,7 @@ async function applyHosted(session, args, open) {
         say(`follow-me review: ${sessionUrl(open.port, swapped)}`);
         say(`the page now shows plan v${latest.version}; the comments on v${open.summary.version} are saved`);
     }
-    next("follow-me watch");
+    next(`run follow-me again; ${STILL_WORKING}`);
     return 0;
 }
 function signMode(args) {
@@ -489,6 +497,7 @@ function promptInput(session, mode, args, changes) {
         diff: session.diff,
         draftPath: session.draftPath,
         checkCommand: `follow-me check${branchFlag(args)}`,
+        ...skillFile(),
         ...(changes === undefined ? {} : { changes }),
     };
     if (mode === "walk")
@@ -502,6 +511,17 @@ function promptInput(session, mode, args, changes) {
         previousCommits: previous === undefined ? [] : projectedCommits(session, previous.version),
     };
 }
+/** The skill this package ships, which holds the rules prompt.md points at; none if it is missing. */
+function skillFile() {
+    try {
+        return { skillPath: join(findSkillDir(), "SKILL.md") };
+    }
+    catch (error) {
+        if (error instanceof InstallError)
+            return {};
+        throw error;
+    }
+}
 /** 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);
@@ -917,8 +937,7 @@ function evolveHandoff(session, cwd, mode, args, moved, hosted) {
         session.writeDraft(serializePlanFile(moved.draft));
     if (draftState(session).kind === "valid")
         return null;
-    const { since, vanished, added } = moved;
-    session.writePrompt(renderPrompt(promptInput(session, mode, args, { since, vanished, added })));
+    session.writePrompt(renderPrompt(promptInput(session, mode, args, moved)));
     say(`wrote ${relative(cwd, session.promptPath)}`);
     const step = `assign the new units in ${relative(cwd, session.draftPath)}, then run follow-me again`;
     next(hosted ? `${step}; ${STILL_WORKING}` : step);
@@ -1058,9 +1077,12 @@ async function listen(session, open, args) {
         const news = fresh.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")) {
+            const done = ended || news.some((e) => e.type === "submitted");
+            // The report that follows quotes every comment, so the digest only says what else happened.
+            const shown = done ? news.filter((e) => !isCommentEvent(e)) : news;
+            process.stdout.write(renderEvents(shown, ctx));
+            if (done) {
                 say();
                 if (ended) {
                     const stored = reviewsOf(session).find((r) => r.version === version);
@@ -1259,6 +1281,9 @@ async function feedback(cwd, args) {
     console.error("follow-me: feedback is now report; printing the same");
     return report(cwd, args, args.flags.has("walk"));
 }
+function isCommentEvent(event) {
+    return event.type === "comment" || event.type === "comment-updated";
+}
 /** Events the reviewer caused; the agent's own replies, explanations and version swaps are not news. */
 function isNews(event) {
     if (event.type === "version")
@@ -1357,7 +1382,7 @@ async function reply(cwd, args) {
         ...(diagram === undefined ? {} : { diagram }),
     });
     say(`replied ${id} to ${commentId}`);
-    next("follow-me watch");
+    next(`run follow-me again; ${STILL_WORKING}`);
     return 0;
 }
 /** The Mermaid source in --diagram's file, or undefined without the flag. */
@@ -1474,7 +1499,123 @@ async function explain(cwd, args) {
         ...(diagram === undefined ? {} : { diagram }),
     });
     say(`explained ${id}`);
-    next("follow-me watch");
+    next(`run follow-me again; ${STILL_WORKING}`);
+    return 0;
+}
+const SHOW_USAGE = "usage: follow-me show <h_…|c_…|k_…|path:line[@<commit>|@base]>";
+/** Every comment the session has, with the plan version it was made on: live ones first. */
+async function knownComments(session) {
+    const open = await openOnServer(session, null);
+    const live = open === null ? [] : await fetchComments(open.port, open.summary);
+    const saved = [
+        session.priorReview("split", null),
+        session.priorReview("walk", null),
+        ...reviewsOf(session).map((r) => r.review),
+    ].flatMap((r) => (r === null ? [] : [{ version: r.planVersion, comments: r.comments }]));
+    return [...live, ...saved];
+}
+const SHOW_MARGIN = 3;
+/**
+ * The lines around path:line as commit `at` of the latest plan writes the file (1-based), the
+ * base, or the tip when `at` is undefined. Read from the plan, so it works before any apply.
+ */
+function showLines(session, raw) {
+    const m = /^(.+):(\d+)(?:@(\d+|base))?$/.exec(raw);
+    const [, typed, lineRaw, at] = m ?? [];
+    if (typed === undefined || lineRaw === undefined)
+        throw new UsageError(SHOW_USAGE);
+    const path = Buffer.from(typed, "utf8").toString("latin1");
+    const file = [...session.diff.textFiles.values()].find((f) => f.path === path);
+    if (file === undefined) {
+        return `${typed} is not a text file this branch changes; it reads the same in every commit, so read it from the working tree\n`;
+    }
+    let text;
+    let label;
+    if (at === undefined) {
+        text = file.tip?.bytes ?? null;
+        label = "the tip";
+    }
+    else if (at === "base") {
+        text = file.base === null ? null : file.base.lines.join("");
+        label = "the base";
+    }
+    else {
+        const latest = session.plans().at(-1);
+        const commits = latest === undefined ? [] : projectedCommits(session, latest.version);
+        const n = Number(at);
+        if (n < 1 || n > commits.length) {
+            throw new UsageError(`@${at} is not one of the ${commits.length} commits of the plan`);
+        }
+        text = file.base === null ? null : file.base.lines.join("");
+        for (const commit of commits.slice(0, n)) {
+            for (const change of commit.changes) {
+                if (change.path !== path)
+                    continue;
+                text = change.op === "write" ? change.bytes : null;
+            }
+        }
+        label = `commit ${n}`;
+    }
+    if (text === null)
+        return `${typed} does not exist in ${label}\n`;
+    const lines = Buffer.from(text, "latin1").toString("utf8").split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    const line = Number(lineRaw);
+    if (line < 1 || line > lines.length) {
+        return `${typed} has ${plural(lines.length, "line")} in ${label}\n`;
+    }
+    const from = Math.max(1, line - SHOW_MARGIN);
+    const to = Math.min(lines.length, line + SHOW_MARGIN);
+    const width = String(to).length;
+    const rows = lines.slice(from - 1, to).map((l, i) => {
+        const n = from + i;
+        return `${n === line ? ">" : " "} ${String(n).padStart(width)}  ${l}`;
+    });
+    return `${typed}:${line} in ${label}\n${rows.join("\n")}\n`;
+}
+/** Expands a ref the agent was given to the lines and thread it names, so no file read is needed. */
+async function showRef(cwd, args) {
+    const [ref, extra] = args.positionals;
+    if (ref === undefined || extra !== undefined)
+        throw new UsageError(SHOW_USAGE);
+    const session = await openSession(cwd, sessionOpts(args));
+    const { units } = session.diff;
+    const latest = session.plans().at(-1);
+    if (isUnitId(ref)) {
+        const unit = units.get(ref);
+        if (unit === undefined) {
+            throw new UsageError(`${ref} is not a unit of the branch now; its hunk changed`);
+        }
+        const commits = latest === undefined ? [] : projectedCommits(session, latest.version);
+        process.stdout.write(renderShownUnit(unit, commits));
+        return 0;
+    }
+    if (/^c_[a-z2-7]{6}$/.test(ref) && isCommentId(ref)) {
+        for (const { version, comments } of await knownComments(session)) {
+            const comment = comments.find((c) => c.id === ref);
+            if (comment === undefined)
+                continue;
+            const ctx = { commits: projectedCommits(session, version), units };
+            process.stdout.write(renderShownComment(comment, ctx, version));
+            return 0;
+        }
+        throw new UsageError(`no comment ${ref} in this session`);
+    }
+    if (isConcernId(ref)) {
+        for (const plan of session.plans().toReversed()) {
+            const commits = projectedCommits(session, plan.version);
+            for (const commit of commits) {
+                const concern = commit.concerns?.find((k) => k.id === ref);
+                if (concern === undefined)
+                    continue;
+                process.stdout.write(renderShownConcern(concern, commit.index, { commits, units }));
+                return 0;
+            }
+        }
+        throw new UsageError(`no concern ${ref} in a plan that fits the branch`);
+    }
+    process.stdout.write(showLines(session, ref));
     return 0;
 }
 function describeLock(lock) {
@@ -1711,6 +1852,8 @@ export async function main(argv, cwd) {
                 const spec = { values: ["commit", "unit", "lines", "body", "diagram", "branch"] };
                 return await explain(cwd, parseArgs(rest, spec));
             }
+            case "show":
+                return await showRef(cwd, parseArgs(rest, { values: ["branch"] }));
             case "report":
                 return await report(cwd, parseArgs(rest, { values: ["branch"], flags: ["json", "markdown"] }));
             case "clean": {

package/dist/src/comments.js

@@ -187,7 +187,10 @@ export function parseNewDecision(concern, v) {
         return "the decision is not an object";
     return withDecision(concern, { ...v, decidedAt: undefined });
 }
-/** Absent reads as none. The first item that does not parse names its index and reason. */
+/**
+ * Absent reads as none. The first item that does not parse names its index and reason. Items
+ * are objects so a string result can only mean a failure; string values go through parseIds.
+ */
 function parseList(raw, parse, what) {
     if (raw === undefined)
         return [];
@@ -202,8 +205,26 @@ function parseList(raw, parse, what) {
     }
     return out;
 }
-function parseConcernId(item) {
-    return isConcernId(item) ? item : "not a concern id";
+/** Absent reads as none. The first item that is not an id of the kind names its index. */
+function parseIds(raw, is, what, kind) {
+    if (raw === undefined)
+        return [];
+    if (!isArray(raw))
+        return `${what} is not an array`;
+    const out = [];
+    for (const [i, item] of raw.entries()) {
+        if (!is(item))
+            return `${what}[${i}]: not a ${kind} id`;
+        out.push(item);
+    }
+    return out;
+}
+/** Keeps only the items that are ids of the kind. */
+function lenientIds(raw, is) {
+    return isArray(raw) ? raw.filter(is) : [];
+}
+function isCommentIdValue(item) {
+    return typeof item === "string" && isCommentId(item);
 }
 /** Absent reads as nothing excluded. */
 export function parseExcluded(v) {
@@ -211,17 +232,14 @@ export function parseExcluded(v) {
         return { comments: [], concerns: [] };
     if (!isFields(v))
         return "excluded is not an object";
-    const comments = parseList(v.comments, parseCommentId, "excluded.comments");
+    const comments = parseIds(v.comments, isCommentIdValue, "excluded.comments", "comment");
     if (typeof comments === "string")
         return comments;
-    const concerns = parseList(v.concerns, parseConcernId, "excluded.concerns");
+    const concerns = parseIds(v.concerns, isConcernId, "excluded.concerns", "concern");
     return typeof concerns === "string" ? concerns : { comments, concerns };
 }
 function asCommentId(item) {
-    return typeof item === "string" && isCommentId(item) ? item : null;
-}
-function parseCommentId(item) {
-    return asCommentId(item) ?? "not a comment id";
+    return isCommentIdValue(item) ? item : null;
 }
 function parseEarlierReplies(v) {
     if (!isFields(v))
@@ -286,7 +304,7 @@ export function parseReview(v) {
     const concerns = parseList(v.concerns, parseDecision, "concerns");
     if (typeof concerns === "string")
         return concerns;
-    const resolved = parseList(v.resolved, parseCommentId, "resolved");
+    const resolved = parseIds(v.resolved, isCommentIdValue, "resolved", "comment");
     if (typeof resolved === "string")
         return resolved;
     const excluded = parseExcluded(v.excluded);
@@ -329,7 +347,7 @@ export function parseDraft(v) {
     return {
         comments: lenient(v.comments, parseComment),
         concerns: lenient(v.concerns, parseDecision),
-        resolved: lenient(v.resolved, parseCommentId),
+        resolved: lenientIds(v.resolved, isCommentIdValue),
         excluded: typeof excluded === "string" ? { comments: [], concerns: [] } : excluded,
         earlierReplies: lenient(v.earlierReplies, parseEarlierReplies),
     };

package/dist/src/evolve.js

@@ -90,9 +90,13 @@ function carry(comment, oldUnits, newUnits) {
     const nowhere = { comment, unit: null, offsets: null, newLine: null };
     if (anchor.kind !== "hunk")
         return { ...nowhere, changed: false, path: comment.context.path };
+    // A comment on a whole hunk has no line; inventing one moves its card off the hunk's end.
+    const whole = anchor.changes === null && anchor.offsets === undefined;
     const kept = newUnits.get(anchor.unit);
     if (kept !== undefined) {
-        const newLine = kept.kind === "hunk" ? (tipLines(kept, newUnits)[firstRow(comment, kept)] ?? null) : null;
+        const newLine = kept.kind === "hunk" && !whole
+            ? (tipLines(kept, newUnits)[firstRow(comment, kept)] ?? null)
+            : null;
         return {
             comment,
             unit: kept.id,
@@ -118,6 +122,6 @@ function carry(comment, oldUnits, newUnits) {
     return {
         ...moved,
         unit: nearest.id,
-        newLine: landing(nearest, newUnits, oldLine, old.body[row]?.text),
+        newLine: whole ? null : landing(nearest, newUnits, oldLine, old.body[row]?.text),
     };
 }

package/dist/src/harness.js

@@ -68,7 +68,10 @@ export const HARNESSES = [
 export function findHarness(id) {
     return HARNESSES.find((h) => h.id === id);
 }
+/** The files of the skill folder, SKILL.md first. */
+export const SKILL_FILES = ["SKILL.md", "porting.md"];
 export function plannedInstall(harness, scope, home, repoRoot) {
     const root = scope === "user" ? join(home, harness.userDir) : join(repoRoot, harness.projectDir);
-    return [{ path: join(root, SKILL_NAME, "SKILL.md"), source: "SKILL.md" }];
+    // porting.md is read only when the user asks to post a review, so the skill stays short.
+    return SKILL_FILES.map((source) => ({ path: join(root, SKILL_NAME, source), source }));
 }

package/dist/src/host.js

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { closeSync, linkSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { parseCarried, parseEvent, parseEventBatch } from "./comments.js";
+import { parseCarried, parseComment, parseEvent, parseEventBatch, } from "./comments.js";
 import { carryComments } from "./evolve.js";
 import { isPlanVersion, serializePlanFile, validatePlan } from "./plan.js";
 import { HEALTH_APP, isSessionId, loadDraftComments, PortInUseError, RegistrationError, startServer, } from "./server.js";
@@ -295,6 +295,22 @@ export async function fetchCarried(port, summary) {
         return [carried];
     });
 }
+/** The comments of the hosted review, and of the version before a swap, with their versions. */
+export async function fetchComments(port, summary) {
+    const state = await call(port, "GET", `${summary.url}api/state`);
+    const parse = (raw) => (Array.isArray(raw) ? raw : []).flatMap((item) => {
+        const comment = parseComment(item);
+        return typeof comment === "string" ? [] : [comment];
+    });
+    if (!isFields(state))
+        throw new RegistrationError("the server sent no state");
+    const previous = state["previous"];
+    const out = [{ version: summary.version, comments: parse(state["comments"]) }];
+    if (isFields(previous) && isPlanVersion(previous["version"])) {
+        out.push({ version: previous["version"], comments: parse(previous["comments"]) });
+    }
+    return out;
+}
 /** One long poll of the session's event log: what happened after `since`, or nothing at timeout. */
 export async function pollEvents(port, summary, since, timeoutMs) {
     const path = `${summary.url}api/events?since=${since}&timeout=${timeoutMs}`;

package/dist/src/install.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, rmdirSync, rmSync, writeFileSync }
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { findHarness, HARNESSES, plannedInstall, SKILL_NAME, } from "./harness.js";
-class InstallError extends Error {
+export class InstallError extends Error {
     name = "InstallError";
 }
 /**