@shiyuphan/follow-me 0.1.1 → 0.2.0

package/dist/src/comments.js

@@ -0,0 +1,300 @@
+import { isRepoPath, isUnitId } from "./diff.js";
+import { diagramProblem, isArray, isCommentId, isConcernId, isFields, isPlanVersion, isSeverity, } from "./plan.js";
+/**
+ * The wire formats of review state, parsed once at the boundary: comments, replies, concern
+ * decisions, the review file, its autosaved draft and the events a hosted session logs. Every
+ * parser returns the domain value or the reason it is not one, so a caller decides whether a bad
+ * item rejects a request or is skipped when reading a file.
+ */
+const REPLY_ID = /^r_[a-z2-7]{6}$/;
+export function isReplyId(value) {
+    return typeof value === "string" && REPLY_ID.test(value);
+}
+function isIndex(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0;
+}
+function parseAnchor(v) {
+    if (!isFields(v))
+        return "anchor is not an object";
+    if (v.kind === "plan")
+        return { kind: "plan" };
+    if (!isIndex(v.commit))
+        return "anchor.commit is not a commit index";
+    const commit = v.commit;
+    if (v.kind === "message" || v.kind === "position")
+        return { kind: v.kind, commit };
+    if (v.kind !== "hunk")
+        return "anchor.kind is unknown";
+    if (typeof v.unit !== "string" || !isUnitId(v.unit))
+        return "anchor.unit is not a unit id";
+    if (v.changes === null)
+        return { kind: "hunk", unit: v.unit, commit, changes: null };
+    if (!isArray(v.changes) || !v.changes.every(isIndex)) {
+        return "anchor.changes is not null or a list of change indices";
+    }
+    return { kind: "hunk", unit: v.unit, commit, changes: v.changes.filter(isIndex) };
+}
+/** A stored reply. Replies a client posts go through parseNewReply, which mints id and time. */
+export function parseReply(v) {
+    if (!isFields(v))
+        return "not an object";
+    if (!isReplyId(v.id))
+        return "id is not a reply id";
+    if (v.author !== "agent" && v.author !== "reviewer")
+        return 'author is not "agent" or "reviewer"';
+    if (typeof v.body !== "string" || typeof v.createdAt !== "string") {
+        return "body and createdAt must be strings";
+    }
+    if (v.diagram !== undefined && typeof v.diagram !== "string")
+        return "diagram is not a string";
+    return {
+        id: v.id,
+        author: v.author,
+        body: v.body,
+        ...(v.diagram === undefined ? {} : { diagram: v.diagram }),
+        createdAt: v.createdAt,
+    };
+}
+/** The body of POST .../replies: who speaks, what, and an optional Mermaid diagram. */
+export function parseNewReply(v) {
+    if (!isFields(v))
+        return "the reply is not an object";
+    if (v.author !== "agent" && v.author !== "reviewer")
+        return 'author is not "agent" or "reviewer"';
+    if (typeof v.body !== "string" || v.body.trim() === "")
+        return "body is not a non-empty string";
+    if (v.diagram === undefined)
+        return { author: v.author, body: v.body };
+    if (typeof v.diagram !== "string")
+        return "diagram is not a string";
+    const problem = diagramProblem(v.diagram);
+    if (problem !== null)
+        return `diagram: ${problem}`;
+    return { author: v.author, body: v.body, diagram: v.diagram };
+}
+function isString(v) {
+    return typeof v === "string";
+}
+/** Boundary parse of a comment, from a file or a request. Returns the reason when it is not one. */
+export function parseComment(v) {
+    if (!isFields(v))
+        return "not an object";
+    if (typeof v.id !== "string" || !isCommentId(v.id))
+        return "id is not a comment id";
+    const anchor = parseAnchor(v.anchor);
+    if (typeof anchor === "string")
+        return anchor;
+    const ctx = v.context;
+    if (!isFields(ctx) || typeof ctx.commitMessage !== "string") {
+        return "context.commitMessage is not a string";
+    }
+    const path = ctx.path;
+    if (path !== null && (typeof path !== "string" || !isRepoPath(path))) {
+        return "context.path is not null or a path";
+    }
+    const lines = ctx.lines;
+    if (lines !== undefined && !(isArray(lines) && lines.every(isString))) {
+        return "context.lines is not a list of strings";
+    }
+    if (typeof v.body !== "string" || typeof v.createdAt !== "string") {
+        return "body and createdAt must be strings";
+    }
+    if (v.kind !== undefined && v.kind !== "question")
+        return 'kind is not "question"';
+    const follows = v.follows;
+    if (follows !== undefined && !(typeof follows === "string" && isCommentId(follows))) {
+        return "follows is not a comment id";
+    }
+    const severity = v.severity;
+    if (severity !== undefined && !isSeverity(severity))
+        return "severity is unknown";
+    const replies = parseList(v.replies, parseReply, "replies");
+    if (typeof replies === "string")
+        return replies;
+    return {
+        id: v.id,
+        anchor,
+        context: {
+            commitMessage: ctx.commitMessage,
+            path,
+            ...(lines === undefined ? {} : { lines: lines.filter(isString) }),
+        },
+        body: v.body,
+        createdAt: v.createdAt,
+        ...(v.kind === "question" ? { kind: "question" } : {}),
+        ...(follows === undefined ? {} : { follows }),
+        ...(severity === undefined ? {} : { severity }),
+        ...(replies.length === 0 ? {} : { replies }),
+    };
+}
+function withDecision(concern, v) {
+    if (v.decision !== "kept" && v.decision !== "dismissed") {
+        return 'decision is not "kept" or "dismissed"';
+    }
+    if (v.severity !== undefined && !isSeverity(v.severity))
+        return "severity is unknown";
+    if (v.note !== undefined && typeof v.note !== "string")
+        return "note is not a string";
+    return {
+        concern,
+        decision: v.decision,
+        ...(v.severity === undefined ? {} : { severity: v.severity }),
+        ...(v.note === undefined || v.note.trim() === "" ? {} : { note: v.note }),
+    };
+}
+/** A stored decision. */
+export function parseDecision(v) {
+    if (!isFields(v))
+        return "not an object";
+    if (!isConcernId(v.concern))
+        return "concern is not a concern id";
+    return withDecision(v.concern, v);
+}
+/** The body of POST .../concerns/<id>; the id comes from the URL. */
+export function parseNewDecision(concern, v) {
+    if (!isFields(v))
+        return "the decision is not an object";
+    return withDecision(concern, v);
+}
+/** Absent reads as none. The first item that does not parse names its index and reason. */
+function parseList(raw, parse, what) {
+    if (raw === undefined)
+        return [];
+    if (!isArray(raw))
+        return `${what} is not an array`;
+    const out = [];
+    for (const [i, item] of raw.entries()) {
+        const parsed = parse(item);
+        if (typeof parsed === "string")
+            return `${what}[${i}]: ${parsed}`;
+        out.push(parsed);
+    }
+    return out;
+}
+function asCommentId(item) {
+    return typeof item === "string" && isCommentId(item) ? item : null;
+}
+function parseCommentId(item) {
+    return asCommentId(item) ?? "not a comment id";
+}
+/** Boundary parse of reviews/vN.json. Files written before walk mode existed have no mode. */
+export function parseReview(v) {
+    if (!isFields(v)) {
+        return "not an object";
+    }
+    if (v.schema !== "follow-me/review@1")
+        return 'schema is not "follow-me/review@1"';
+    const mode = v.mode ?? "split";
+    if (mode !== "split" && mode !== "walk")
+        return 'mode is not "split" or "walk"';
+    if (!isPlanVersion(v.planVersion))
+        return "planVersion is not a positive integer";
+    if (typeof v.planHash !== "string" || typeof v.endedAt !== "string") {
+        return "planHash and endedAt must be strings";
+    }
+    if (!isArray(v.comments))
+        return "comments is not an array";
+    const comments = parseList(v.comments, parseComment, "comments");
+    if (typeof comments === "string")
+        return comments;
+    const concerns = parseList(v.concerns, parseDecision, "concerns");
+    if (typeof concerns === "string")
+        return concerns;
+    const resolved = parseList(v.resolved, parseCommentId, "resolved");
+    if (typeof resolved === "string")
+        return resolved;
+    return {
+        schema: v.schema,
+        mode,
+        planVersion: v.planVersion,
+        planHash: v.planHash,
+        endedAt: v.endedAt,
+        comments,
+        ...(concerns.length === 0 ? {} : { concerns }),
+        ...(resolved.length === 0 ? {} : { resolved }),
+    };
+}
+function lenient(items, parse) {
+    if (!isArray(items))
+        return [];
+    return items.flatMap((item) => {
+        const parsed = parse(item);
+        return typeof parsed === "string" ? [] : [parsed];
+    });
+}
+/**
+ * Boundary parse of reviews/vN.draft.json. Unlike a finished review it is read leniently: an
+ * item that does not parse is dropped, so one bad entry never loses the rest of an autosave.
+ */
+export function parseDraft(v) {
+    if (!isFields(v) || !isArray(v.comments)) {
+        return "not a review draft";
+    }
+    return {
+        comments: lenient(v.comments, parseComment),
+        concerns: lenient(v.concerns, parseDecision),
+        resolved: lenient(v.resolved, parseCommentId),
+    };
+}
+export function parseEvent(v) {
+    if (!isFields(v))
+        return "not an object";
+    const { seq } = v;
+    if (typeof seq !== "number" || !Number.isInteger(seq) || seq < 1)
+        return "seq is not a number";
+    switch (v.type) {
+        case "comment":
+        case "comment-updated": {
+            const comment = parseComment(v.comment);
+            return typeof comment === "string" ? comment : { seq, type: v.type, comment };
+        }
+        case "comment-deleted": {
+            const id = asCommentId(v.id);
+            return id === null ? "id is not a comment id" : { seq, type: v.type, id };
+        }
+        case "reply": {
+            const id = asCommentId(v.commentId);
+            const reply = parseReply(v.reply);
+            if (id === null)
+                return "commentId is not a comment id";
+            return typeof reply === "string" ? reply : { seq, type: v.type, commentId: id, reply };
+        }
+        case "concern": {
+            if (!isConcernId(v.concernId))
+                return "concernId is not a concern id";
+            const decision = withDecision(v.concernId, v);
+            if (typeof decision === "string")
+                return decision;
+            const { concern: concernId, ...rest } = decision;
+            return { seq, type: v.type, concernId, ...rest };
+        }
+        case "resolved": {
+            const id = asCommentId(v.commentId);
+            if (id === null || typeof v.resolved !== "boolean") {
+                return "malformed resolved event";
+            }
+            return { seq, type: v.type, commentId: id, resolved: v.resolved };
+        }
+        case "version": {
+            if (!isPlanVersion(v.version) || typeof v.hash !== "string")
+                return "malformed version event";
+            return { seq, type: v.type, version: v.version, hash: v.hash };
+        }
+        case "ended":
+            return typeof v.review === "string"
+                ? { seq, type: v.type, review: v.review }
+                : "review is not a path";
+        default:
+            return "unknown event type";
+    }
+}
+/** The body of GET .../events: the latest seq and the events after the asked-for one. */
+export function parseEventBatch(v) {
+    if (!isFields(v))
+        return "not an object";
+    if (typeof v.seq !== "number" || !Number.isInteger(v.seq) || v.seq < 0) {
+        return "seq is not a number";
+    }
+    const events = parseList(v.events, parseEvent, "events");
+    return typeof events === "string" ? events : { seq: v.seq, events };
+}

package/dist/src/git.js

@@ -54,6 +54,10 @@ async function resolveOptional(repo, ref) {
         throw error;
     }
 }
+/** The ref refs/heads/<name> points at, or null when there is no such branch. */
+export function branchHead(repo, name) {
+    return resolveOptional(repo, `refs/heads/${name}`);
+}
 export async function treeOf(repo, rev) {
     return toSha(await gitText(repo, ["rev-parse", "--verify", "--end-of-options", `${rev}^{tree}`]), `${rev}^{tree}`);
 }
@@ -84,7 +88,7 @@ export async function checkedOutBranches(repo) {
     return found;
 }
 export async function branchExists(repo, name) {
-    return (await resolveOptional(repo, `refs/heads/${name}`)) !== null;
+    return (await branchHead(repo, name)) !== null;
 }
 export async function defaultBaseRef(repo) {
     for (const name of ["main", "master"]) {
@@ -130,6 +134,17 @@ export async function loadDiff(repo, baseRef, tipRef) {
     const blobs = await catBlobs(repo, neededBlobs(rawZ, patchText));
     return parseDiff({ base, tip, baseTree, tipTree, rawZ, patch: patchText, blobs });
 }
+export async function signing(repo, mode) {
+    const configured = await gitText(repo, [
+        "config",
+        "--type=bool",
+        "--default=false",
+        "commit.gpgsign",
+    ]);
+    const format = await gitText(repo, ["config", "--default=openpgp", "gpg.format"]);
+    const on = mode === "config" ? configured === "true" : mode === "on";
+    return { on, format };
+}
 export class BranchRefusedError extends Error {
     name = "BranchRefusedError";
 }
@@ -201,6 +216,7 @@ async function adoptObjects(quarantine, objects) {
  * user's index and worktree are never touched, then moves refs/heads/<name> by compare-and-swap.
  * New objects go to a quarantine inside the object store and are adopted only right before the
  * ref moves, so a refused or failed write leaves neither refs nor objects behind.
+ * With opts.sign, commit-tree signs with gpg.format and user.signingkey.
  */
 export async function writeBranch(repo, diff, plan, opts) {
     const ref = `refs/heads/${opts.name}`;
@@ -242,7 +258,7 @@ export async function writeBranch(repo, diff, plan, opts) {
             await git(repo, ["update-index", "-z", "--index-info"], { env, input: Buffer.concat(lines) });
             tree = toSha(await gitText(repo, ["write-tree"], { env }), "write-tree");
             const message = commit.message.endsWith("\n") ? commit.message : `${commit.message}\n`;
-            head = toSha(await gitText(repo, ["commit-tree", "--no-gpg-sign", tree, "-p", head, "-F", "-"], {
+            head = toSha(await gitText(repo, ["commit-tree", opts.sign ? "-S" : "--no-gpg-sign", tree, "-p", head, "-F", "-"], {
                 input: message,
                 env: { ...env, ...identityEnv(who, n - 1 - commit.index) },
             }), "commit-tree");
@@ -251,7 +267,8 @@ export async function writeBranch(repo, diff, plan, opts) {
         if (tree !== diff.tipTree) {
             throw new Error(`the last commit's tree ${tree} differs from the tip tree ${diff.tipTree}`);
         }
-        const current = await resolveOptional(repo, ref);
+        const current = await branchHead(repo, opts.name);
+        // Unsigned commits, and deterministic signatures such as ssh ed25519, give the same SHAs.
         if (current === head)
             return { kind: "unchanged", branch: opts.name, head, commits };
         if (current !== null && !opts.force) {

package/dist/src/host.js

@@ -3,6 +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 { parseEvent, parseEventBatch } from "./comments.js";
 import { isPlanVersion, serializePlanFile, validatePlan } from "./plan.js";
 import { HEALTH_APP, isSessionId, loadDraftComments, PortInUseError, RegistrationError, startServer, } from "./server.js";
 import { BranchMovedError, isAlive, openSessionAt, SessionFileError, SessionLockedError, } from "./session.js";
@@ -103,7 +104,7 @@ function removeRecord(dir, pid) {
     if (readServerRecord(dir)?.pid === pid)
         rmSync(join(dir, RECORD), { force: true });
 }
-async function loadHosted(registration) {
+async function loadHosted(registration, held) {
     const { dir, mode, version, hash, lockToken } = registration;
     try {
         const session = await openSessionAt(dir);
@@ -112,8 +113,11 @@ async function loadHosted(registration) {
         if (stored === undefined || stored.hash !== hash) {
             throw new RegistrationError(`${branch} has no plan v${version} with hash ${hash}`);
         }
-        if (session.reviews().some((r) => r.version === version)) {
-            throw new RegistrationError(`plan v${version} of ${branch} already has a review`);
+        // Each mode has its own slot, so a walk can follow the author's review of the same plan.
+        const reviewed = mode === "walk" ? session.walkReviews() : session.reviews();
+        if (reviewed.some((r) => r.version === version)) {
+            const what = mode === "walk" ? "code review" : "review";
+            throw new RegistrationError(`plan v${version} of ${branch} already has a ${what}`);
         }
         const verdict = validatePlan(session.diff, serializePlanFile(stored.file), {
             lastReview: session.lastReview(),
@@ -121,14 +125,25 @@ async function loadHosted(registration) {
         if (!verdict.ok) {
             throw new RegistrationError(`plan v${version} no longer fits ${branch}; check it again`);
         }
-        const reviewsDir = join(session.dir, "reviews");
+        const reviewsDir = session.reviewsDir(mode);
         const comments = await loadDraftComments(reviewsDir, version);
+        const prior = session.priorReview(mode, version);
+        const previous = prior === null || prior.comments.length === 0
+            ? null
+            : {
+                version: prior.planVersion,
+                comments: prior.comments,
+                responses: stored.file.responses,
+            };
         const command = mode === "walk" ? "walk" : "review";
-        const lock = lockToken === null ? session.lock(command) : session.adoptLock(lockToken, command);
+        // A version swap runs inside the server that already owns this session's lock.
+        const release = held ??
+            (lockToken === null ? session.lock(command) : session.adoptLock(lockToken, command)).release;
         return {
             repo: session.root,
             reviewsDir,
-            release: lock.release,
+            release,
+            previous,
             state: {
                 mode,
                 anchor: session.anchor,
@@ -251,6 +266,64 @@ export async function registerWith(port, registration) {
         throw new RegistrationError("the server answered with a malformed session");
     return summary;
 }
+/** Moves the hosted session to a newer frozen plan; its id and URL stay. */
+export async function swapVersion(port, summary, version, hash) {
+    const swapped = parseSummary(await call(port, "POST", `${summary.url}api/version`, { version, hash }));
+    if (swapped === null)
+        throw new RegistrationError("the server answered with a malformed session");
+    return swapped;
+}
+/** 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}`;
+    const batch = parseEventBatch(await call(port, "GET", path));
+    if (typeof batch === "string")
+        throw new RegistrationError(`the server sent bad events: ${batch}`);
+    return batch;
+}
+/**
+ * Follows the session's event stream from `since`, calling `onEvent` for each event. Resolves when
+ * the server closes the stream, which it does after the `ended` event.
+ */
+export async function followEvents(port, summary, since, onEvent) {
+    const res = await fetch(`${sessionUrl(port, summary)}api/events/stream?since=${since}`);
+    if (!res.ok || res.body === null) {
+        throw new RegistrationError(`GET api/events/stream failed with ${res.status}`);
+    }
+    const decoder = new TextDecoder();
+    const gap = "\n\n";
+    let buffer = "";
+    for await (const chunk of res.body) {
+        buffer += decoder.decode(chunk, { stream: true });
+        for (let end = buffer.indexOf(gap); end !== -1; end = buffer.indexOf(gap)) {
+            const frame = buffer.slice(0, end);
+            buffer = buffer.slice(end + 2);
+            const data = frame.split("\n").find((l) => l.startsWith("data: "));
+            if (data === undefined)
+                continue;
+            const event = parseEvent(JSON.parse(data.slice(6)));
+            if (typeof event === "string")
+                throw new RegistrationError(`bad event on the stream: ${event}`);
+            onEvent(event);
+        }
+    }
+}
+/** Posts the agent's reply under a comment and returns the new reply's id. */
+export async function postReply(port, summary, commentId, reply) {
+    const path = `${summary.url}api/comments/${encodeURIComponent(commentId)}/replies`;
+    const body = await call(port, "POST", path, reply);
+    const id = isFields(body) ? body["id"] : undefined;
+    if (typeof id !== "string")
+        throw new RegistrationError("the server answered without a reply id");
+    return id;
+}
+/** The consolidated report of the hosted session as it stands. */
+export async function fetchReport(port, summary) {
+    const res = await fetch(`${sessionUrl(port, summary)}api/report`);
+    if (!res.ok)
+        throw new RegistrationError(`GET api/report failed with ${res.status}`);
+    return res.text();
+}
 export async function listSessions(port) {
     const raw = await call(port, "GET", "/api/sessions");
     if (!Array.isArray(raw))
@@ -263,6 +336,19 @@ export async function listSessions(port) {
 export function sessionUrl(port, summary) {
     return `http://127.0.0.1:${port}${summary.url}`;
 }
+/** Whether the server on this port still serves the session's state; a gone server serves none. */
+export async function stillHosted(port, summary) {
+    try {
+        const res = await fetch(`${sessionUrl(port, summary)}api/state`, {
+            signal: AbortSignal.timeout(2_000),
+        });
+        await res.body?.cancel();
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Stops the recorded server and waits for it to exit. Only a pid that answers as our server on
  * the recorded port is signalled, so a reused pid is never killed. A stale record is removed.

package/dist/src/install.js

@@ -51,7 +51,7 @@ function chooseHarnesses(options, home) {
  * and the generic one) plan the same file once.
  */
 export function planSkillFiles(options, home, repoRoot) {
-    const scope = options.user ? "user" : "project";
+    const scope = options.project ? "project" : "user";
     const byPath = new Map();
     for (const harness of chooseHarnesses(options, home)) {
         for (const file of plannedInstall(harness, scope, home, repoRoot)) {

package/dist/src/naive.js

@@ -0,0 +1,26 @@
+import { PLAN_SCHEMA } from "./plan.js";
+/**
+ * The plan that needs no planner: one commit per touched file in diff order, holding every unit
+ * of that file. It tells no story, but it runs the whole pipeline on a real branch. Returns the
+ * draft as the wire format, for validatePlan to judge like any other draft.
+ */
+export function naiveDraft(diff) {
+    const byPath = new Map();
+    for (const unit of diff.units.values()) {
+        byPath.set(unit.path, [...(byPath.get(unit.path) ?? []), unit]);
+    }
+    const commits = [...byPath].map(([path, units]) => ({
+        message: `wip: ${path}${suffix(units)}`,
+        units: units.map((u) => u.id),
+    }));
+    return { schema: PLAN_SCHEMA, base: diff.base, tip: diff.tip, commits, responses: [] };
+}
+/** Names what a file with no text hunk is, so `wip: logo.bin (binary)` says why it has no lines. */
+function suffix(units) {
+    if (units.some((u) => u.kind === "hunk"))
+        return "";
+    const first = units[0];
+    if (first === undefined)
+        return "";
+    return first.kind === "mode" ? " (mode)" : first.kind === "file" ? ` (${first.reason})` : "";
+}