@shiyuphan/follow-me 0.1.0 → 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

@@ -1,6 +1,5 @@
 import { execFile } from "node:child_process";
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { link, mkdir, mkdtemp, readdir, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { isSha, neededBlobs, parseDiff } from "./diff.js";
 export class GitError extends Error {
@@ -24,6 +23,13 @@ function git(repo, args, opts = {}) {
             else
                 resolve(stdout);
         });
+        // git can exit before reading its input (a bad ref, a missing repo). On Linux the
+        // pending write then fails with EPIPE; the callback above already carries git's
+        // real error, so that write failure is noise.
+        child.stdin?.on("error", (error) => {
+            if (error.code !== "EPIPE")
+                reject(error);
+        });
         child.stdin?.end(opts.input ?? "");
     });
 }
@@ -48,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}`);
 }
@@ -64,6 +74,22 @@ export async function currentBranch(repo) {
         throw error;
     }
 }
+/** Each branch checked out in some worktree of the repo, mapped to that worktree's path. */
+export async function checkedOutBranches(repo) {
+    const out = (await git(repo, ["worktree", "list", "--porcelain", "-z"])).toString("utf8");
+    const found = new Map();
+    let path = "";
+    for (const field of out.split("\0")) {
+        if (field.startsWith("worktree "))
+            path = field.slice("worktree ".length);
+        if (field.startsWith("branch refs/heads/"))
+            found.set(field.slice("branch refs/heads/".length), path);
+    }
+    return found;
+}
+export async function branchExists(repo, name) {
+    return (await branchHead(repo, name)) !== null;
+}
 export async function defaultBaseRef(repo) {
     for (const name of ["main", "master"]) {
         if ((await resolveOptional(repo, `refs/heads/${name}`)) !== null)
@@ -108,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";
 }
@@ -132,7 +169,7 @@ function identityEnv(who, back) {
         GIT_COMMITTER_DATE: date(who.committer),
     };
 }
-async function indexLine(repo, change, zero) {
+async function indexLine(repo, change, zero, env) {
     const entry = async () => {
         if (change.op === "delete")
             return `0 ${zero}`;
@@ -140,6 +177,7 @@ async function indexLine(repo, change, zero) {
             return `${change.entry.mode} ${change.entry.blob}`;
         const blob = await gitText(repo, ["hash-object", "-w", "--stdin"], {
             input: Buffer.from(change.bytes, "latin1"),
+            env,
         });
         return `${change.mode} ${toSha(blob, change.path)}`;
     };
@@ -149,9 +187,36 @@ async function indexLine(repo, change, zero) {
         Buffer.from([0]),
     ]);
 }
+/** Prefix of the quarantine directories writeBranch creates inside the object store. */
+export const QUARANTINE_PREFIX = "follow-me-incoming-";
+export async function objectsDir(repo) {
+    return gitText(repo, ["rev-parse", "--path-format=absolute", "--git-path", "objects"]);
+}
+/** Hard-links the quarantined loose objects into the store; an object already there stays. */
+async function adoptObjects(quarantine, objects) {
+    for (const fanout of await readdir(quarantine)) {
+        if (!/^[0-9a-f]{2}$/.test(fanout))
+            continue;
+        await mkdir(join(objects, fanout), { recursive: true });
+        for (const name of await readdir(join(quarantine, fanout))) {
+            if (name.startsWith("tmp_"))
+                continue;
+            try {
+                await link(join(quarantine, fanout, name), join(objects, fanout, name));
+            }
+            catch (error) {
+                if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+                    throw error;
+            }
+        }
+    }
+}
 /**
  * Writes the plan as commits on top of the merge-base through a temporary index, so the
  * 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}`;
@@ -161,15 +226,27 @@ export async function writeBranch(repo, diff, plan, opts) {
     catch {
         throw new BranchRefusedError(`"${opts.name}" is not a valid branch name`);
     }
+    if (opts.name === opts.source) {
+        throw new BranchRefusedError(`${opts.name} is the branch being split; the split always lands on a separate branch, so pick another --name (--force does not change this)`);
+    }
+    const worktree = (await checkedOutBranches(repo)).get(opts.name);
+    if (worktree !== undefined) {
+        throw new BranchRefusedError(`branch ${opts.name} is checked out in ${worktree}; moving it would leave that worktree out of sync, so pick another --name (--force does not change this)`);
+    }
     const who = await identities(repo, diff.tip);
     const zero = "0".repeat(diff.base.length);
     const n = plan.commits.length;
-    const dir = await mkdtemp(join(tmpdir(), "follow-me-index-"));
+    const objects = await objectsDir(repo);
+    const dir = await mkdtemp(join(objects, `${QUARANTINE_PREFIX}${process.pid}-`));
     const commits = [];
     let head = diff.base;
     let tree = diff.baseTree;
     try {
-        const env = { GIT_INDEX_FILE: join(dir, "index") };
+        const env = {
+            GIT_INDEX_FILE: join(dir, "index"),
+            GIT_OBJECT_DIRECTORY: dir,
+            GIT_ALTERNATE_OBJECT_DIRECTORIES: objects,
+        };
         await git(repo, ["read-tree", diff.baseTree], { env });
         for (const commit of plan.commits) {
             // Deletes go first so a file can give way to a directory of the same name.
@@ -177,34 +254,36 @@ export async function writeBranch(repo, diff, plan, opts) {
                 ...commit.changes.filter((c) => c.op === "delete"),
                 ...commit.changes.filter((c) => c.op !== "delete"),
             ];
-            const lines = await Promise.all(ordered.map((c) => indexLine(repo, c, zero)));
+            const lines = await Promise.all(ordered.map((c) => indexLine(repo, c, zero, env)));
             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: identityEnv(who, n - 1 - commit.index),
+                env: { ...env, ...identityEnv(who, n - 1 - commit.index) },
             }), "commit-tree");
             commits.push(head);
         }
+        if (tree !== diff.tipTree) {
+            throw new Error(`the last commit's tree ${tree} differs from the tip tree ${diff.tipTree}`);
+        }
+        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) {
+            if (opts.expectedOld === null) {
+                throw new BranchRefusedError(`branch ${opts.name} already exists and follow-me did not write it; pass --force to overwrite`);
+            }
+            if (current !== opts.expectedOld) {
+                throw new BranchRefusedError(`branch ${opts.name} moved since the last apply (expected ${opts.expectedOld}, found ${current}); pass --force to overwrite`);
+            }
+        }
+        await adoptObjects(dir, objects);
+        await git(repo, ["update-ref", "-m", "follow-me apply", ref, head, current ?? zero]);
+        return { kind: current === null ? "created" : "updated", branch: opts.name, head, commits };
     }
     finally {
         await rm(dir, { recursive: true, force: true });
     }
-    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);
-    if (current === head)
-        return { kind: "unchanged", branch: opts.name, head, commits };
-    if (current !== null && !opts.force) {
-        if (opts.expectedOld === null) {
-            throw new BranchRefusedError(`branch ${opts.name} already exists and follow-me did not write it; pass --force to overwrite`);
-        }
-        if (current !== opts.expectedOld) {
-            throw new BranchRefusedError(`branch ${opts.name} moved since the last apply (expected ${opts.expectedOld}, found ${current}); pass --force to overwrite`);
-        }
-    }
-    await git(repo, ["update-ref", "-m", "follow-me apply", ref, head, current ?? zero]);
-    return { kind: current === null ? "created" : "updated", branch: opts.name, head, commits };
 }

package/dist/src/harness.js

@@ -0,0 +1,74 @@
+import { join } from "node:path";
+export const SKILL_NAME = "follow-me";
+export const HARNESSES = [
+    {
+        id: "claude",
+        name: "Claude Code",
+        projectDir: ".claude/skills",
+        userDir: ".claude/skills",
+        format: "skill",
+        probes: [".claude"],
+        docs: "https://code.claude.com/docs/en/skills",
+    },
+    {
+        id: "opencode",
+        name: "OpenCode",
+        projectDir: ".opencode/skills",
+        userDir: ".config/opencode/skills",
+        format: "skill",
+        probes: [".config/opencode", ".opencode"],
+        docs: "https://opencode.ai/docs/skills/",
+    },
+    {
+        id: "codex",
+        name: "Codex CLI",
+        projectDir: ".agents/skills",
+        userDir: ".agents/skills",
+        format: "skill",
+        probes: [".codex"],
+        docs: "https://developers.openai.com/codex/skills",
+    },
+    {
+        id: "cursor",
+        name: "Cursor",
+        projectDir: ".cursor/skills",
+        userDir: ".cursor/skills",
+        format: "skill",
+        probes: [".cursor"],
+        docs: "https://cursor.com/docs/context/skills",
+    },
+    {
+        id: "gemini",
+        name: "Gemini CLI",
+        projectDir: ".gemini/skills",
+        userDir: ".gemini/skills",
+        format: "skill",
+        probes: [".gemini"],
+        docs: "https://geminicli.com/docs/cli/skills/",
+    },
+    {
+        id: "copilot",
+        name: "GitHub Copilot CLI",
+        projectDir: ".github/skills",
+        userDir: ".copilot/skills",
+        format: "skill",
+        probes: [".copilot"],
+        docs: "https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills",
+    },
+    {
+        id: "agents",
+        name: "Any Agent Skills client",
+        projectDir: ".agents/skills",
+        userDir: ".agents/skills",
+        format: "skill",
+        probes: [],
+        docs: "https://agentskills.io/client-implementation/adding-skills-support",
+    },
+];
+export function findHarness(id) {
+    return HARNESSES.find((h) => h.id === id);
+}
+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" }];
+}