@shiyuphan/follow-me 0.1.0 → 0.2.0

package/dist/src/session.js

@@ -1,9 +1,10 @@
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
-import { dirname, join } from "node:path";
-import { isRepoPath, isSha, isUnitId } from "./diff.js";
-import { currentBranch, defaultBaseRef, loadDiff, repoRoot, resolveCommit } from "./git.js";
-import { isArray, isCommentId, isFields, isPlanVersion, parsePlanFile, planHash, serializePlanFile, } from "./plan.js";
+import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { parseDraft, parseReview } from "./comments.js";
+import { isSha } from "./diff.js";
+import { branchExists, currentBranch, defaultBaseRef, GitError, loadDiff, objectsDir, QUARANTINE_PREFIX, repoRoot, resolveCommit, } from "./git.js";
+import { isFields, isPlanVersion, parsePlanFile, planHash, serializePlanFile, } from "./plan.js";
 export class BranchMovedError extends Error {
     name = "BranchMovedError";
 }
@@ -11,15 +12,137 @@ export class BranchMovedError extends Error {
 export class SessionFileError extends Error {
     name = "SessionFileError";
 }
+/** draft.json has not been written yet. */
+export class MissingDraftError extends SessionFileError {
+    path;
+    constructor(path) {
+        super(`${path} does not exist yet`);
+        this.path = path;
+    }
+}
+/** The command ran outside any git work tree. */
+export class NotARepositoryError extends Error {
+    name = "NotARepositoryError";
+    constructor() {
+        super("not a git repository (run it inside the repo you want to split)");
+    }
+}
+/** Another live follow-me process holds the session's lock. */
+export class SessionLockedError extends Error {
+    name = "SessionLockedError";
+}
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists but belongs to another user.
+        return error instanceof Error && "code" in error && error.code === "EPERM";
+    }
+}
+export function readLock(path) {
+    const raw = readJson(path);
+    if (raw === undefined)
+        return { kind: "free" };
+    if (!isFields(raw))
+        throw new SessionFileError(`${path} is not a lock`);
+    const { pid, command } = raw;
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
+        throw new SessionFileError(`${path} is not a lock`);
+    }
+    if (typeof command !== "string")
+        throw new SessionFileError(`${path} is not a lock`);
+    return { kind: isAlive(pid) ? "held" : "stale", pid, command };
+}
+const LOCK_TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export function isLockToken(value) {
+    return typeof value === "string" && LOCK_TOKEN.test(value);
+}
+function newToken() {
+    const token = randomUUID();
+    if (!isLockToken(token))
+        throw new Error(`randomUUID returned ${token}`);
+    return token;
+}
+function lockContent(command, token) {
+    return `${JSON.stringify({ pid: process.pid, command, token })}\n`;
+}
+function holding(path, token) {
+    return {
+        token,
+        release: () => {
+            const raw = readJson(path);
+            if (isFields(raw) && raw.token === token)
+                rmSync(path, { force: true });
+        },
+    };
+}
+function isCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+/**
+ * Takes <dir>/lock for this process. The lock is written whole to a temp file and linked into
+ * place, which fails like open(wx) when the lock exists, so a reader never sees a half-written
+ * lock. A lock whose pid is dead is taken over.
+ */
+function acquireLock(dir, branch, command) {
+    const path = join(dir, "lock");
+    const token = newToken();
+    mkdirSync(dir, { recursive: true });
+    for (let attempt = 0;; attempt++) {
+        const temp = `${path}.${process.pid}.${token}.tmp`;
+        writeFileSync(temp, lockContent(command, token));
+        try {
+            linkSync(temp, path);
+            break;
+        }
+        catch (error) {
+            if (!isCode(error, "EEXIST"))
+                throw error;
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+        const state = readLock(path);
+        if (state.kind === "held" || attempt > 0) {
+            const who = state.kind === "free" ? "another process" : `pid ${state.pid}`;
+            const what = state.kind === "free" ? "follow-me" : `follow-me ${state.command}`;
+            throw new SessionLockedError(`the session for ${branch} is busy: ${who} is running ${what}; wait for it to finish or stop it`);
+        }
+        rmSync(path, { force: true });
+    }
+    return holding(path, token);
+}
+/**
+ * Takes over a lock another live process holds and is handing over, identified by its token.
+ * The holder waits for the handoff to finish, so nobody else can take the lock between the read
+ * and the rename; the old holder's release then finds a foreign token and leaves the lock alone.
+ */
+function adoptLock(dir, from, command) {
+    const path = join(dir, "lock");
+    const raw = readJson(path);
+    if (!isFields(raw) || raw.token !== from) {
+        throw new SessionLockedError(`${path} is not held by the process handing it over`);
+    }
+    const token = newToken();
+    const temp = `${path}.${process.pid}.${token}.tmp`;
+    writeFileSync(temp, lockContent(command, token));
+    renameSync(temp, path);
+    return holding(path, token);
+}
 export function slugOf(branch) {
     return branch.replaceAll("/", "-");
 }
-function writeJson(path, value) {
+function writeText(path, text) {
     mkdirSync(dirname(path), { recursive: true });
     const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
-    writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`);
+    writeFileSync(temp, text);
     renameSync(temp, path);
 }
+function writeJson(path, value) {
+    writeText(path, `${JSON.stringify(value, null, 2)}\n`);
+}
 function readJson(path) {
     let text;
     try {
@@ -65,101 +188,24 @@ function parseAnchor(v) {
 function parseApplied(v) {
     if (!isFields(v))
         return null;
-    const { schema, version, branch, head } = v;
+    const { schema, version, branch, head, hash = null, signed = null } = v;
     if (schema !== "follow-me/applied@1" || !isPlanVersion(version))
         return null;
     if (typeof branch !== "string" || typeof head !== "string" || !isSha(head))
         return null;
-    return { schema, version, branch, head };
-}
-function isCommitIndex(v) {
-    return typeof v === "number" && Number.isInteger(v) && v >= 0;
-}
-function parseCommentAnchor(v) {
-    if (!isFields(v))
-        return "anchor is not an object";
-    if (v.kind === "plan")
-        return { kind: "plan" };
-    if (!isCommitIndex(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(isCommitIndex)) {
-        return "anchor.changes is not null or a list of change indices";
-    }
-    return { kind: "hunk", unit: v.unit, commit, changes: v.changes.filter(isCommitIndex) };
-}
-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 = parseCommentAnchor(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";
-    }
-    if (typeof v.body !== "string" || typeof v.createdAt !== "string") {
-        return "body and createdAt must be strings";
-    }
-    return {
-        id: v.id,
-        anchor,
-        context: { commitMessage: ctx.commitMessage, path },
-        body: v.body,
-        createdAt: v.createdAt,
-    };
-}
-/** 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 = [];
-    for (const [i, raw] of v.comments.entries()) {
-        const c = parseComment(raw);
-        if (typeof c === "string")
-            return `comments[${i}]: ${c}`;
-        comments.push(c);
-    }
-    return {
-        schema: v.schema,
-        mode,
-        planVersion: v.planVersion,
-        planHash: v.planHash,
-        endedAt: v.endedAt,
-        comments,
-    };
+    if (hash !== null && typeof hash !== "string")
+        return null;
+    if (signed !== null && typeof signed !== "boolean")
+        return null;
+    return { schema, version, branch, head, hash, signed };
 }
 function makeSession(root, dir, anchor, diff) {
     const plansDir = join(dir, "plans");
-    const reviewsDir = join(dir, "reviews");
+    const splitReviews = join(dir, "reviews");
+    const walkReviewsDir = join(splitReviews, "walk");
+    const reviewsDir = (mode) => mode === "walk" ? walkReviewsDir : splitReviews;
     const draftPath = join(dir, "draft.json");
+    const promptPath = join(dir, "prompt.md");
     const appliedPath = join(dir, "applied.json");
     const plans = () => versions(plansDir).map(({ version, path }) => {
         const file = parsePlanFile(readJson(path));
@@ -170,30 +216,74 @@ function makeSession(root, dir, anchor, diff) {
         }
         return { version, file, hash: planHash(file) };
     });
-    const reviews = () => versions(reviewsDir).map(({ version, path }) => {
+    const reviewsIn = (mode) => versions(reviewsDir(mode)).map(({ version, path }) => {
         const review = parseReview(readJson(path));
         if (typeof review === "string")
             throw new SessionFileError(`${path}: ${review}`);
         return { version, review };
     });
+    const reviews = () => reviewsIn("split");
+    const walkReviews = () => [...reviews().filter((r) => r.review.mode === "walk"), ...reviewsIn("walk")].sort((a, b) => a.version - b.version);
+    const draftVersions = (mode) => {
+        const dir = reviewsDir(mode);
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir).flatMap((name) => {
+            const n = Number(/^v([1-9][0-9]*)\.draft\.json$/.exec(name)?.[1]);
+            return isPlanVersion(n) ? [n] : [];
+        });
+    };
+    const draftReview = (mode, version) => {
+        const path = join(reviewsDir(mode), `v${version}.draft.json`);
+        const draft = parseDraft(readJson(path));
+        if (typeof draft === "string")
+            throw new SessionFileError(`${path}: ${draft}`);
+        const { comments, concerns, resolved } = draft;
+        return {
+            schema: "follow-me/review@1",
+            mode,
+            planVersion: version,
+            planHash: plans().find((p) => p.version === version)?.hash ?? "",
+            endedAt: statSync(path).mtime.toISOString(),
+            comments,
+            ...(concerns.length === 0 ? {} : { concerns }),
+            ...(resolved.length === 0 ? {} : { resolved }),
+        };
+    };
+    const priorReview = (mode, before) => {
+        const below = (v) => before === null || v < before;
+        const done = (mode === "walk" ? walkReviews() : reviews().filter((r) => r.review.mode === mode))
+            .filter((r) => below(r.version))
+            .at(-1);
+        const unfinished = draftVersions(mode)
+            .filter((v) => below(v) && v > (done?.version ?? 0))
+            .sort((a, b) => a - b)
+            .at(-1);
+        return unfinished === undefined ? (done?.review ?? null) : draftReview(mode, unfinished);
+    };
     return {
         root,
         dir,
         anchor,
         diff,
         draftPath,
+        promptPath,
         plans,
+        reviewsDir,
         reviews,
-        lastReview: () => reviews().findLast((r) => r.review.mode === "split")?.review ?? null,
+        walkReviews,
+        lastReview: () => priorReview("split", null),
+        priorReview,
         readDraft: () => {
             const draft = readJson(draftPath);
             if (draft === undefined)
-                throw new SessionFileError(`${draftPath} does not exist yet`);
+                throw new MissingDraftError(draftPath);
             return draft;
         },
         writeDraft: (draft) => writeJson(draftPath, draft),
+        writePrompt: (text) => writeText(promptPath, text),
         writeReview: (review) => {
-            const path = join(reviewsDir, `v${review.planVersion}.json`);
+            const path = join(reviewsDir(review.mode), `v${review.planVersion}.json`);
             if (existsSync(path))
                 throw new SessionFileError(`${path} is already written`);
             writeJson(path, review);
@@ -208,6 +298,9 @@ function makeSession(root, dir, anchor, diff) {
             writeJson(join(plansDir, `v${version}.json`), serializePlanFile(plan.file));
             return version;
         },
+        lock: (command) => acquireLock(dir, anchor.branch, command),
+        adoptLock: (from, command) => adoptLock(dir, from, command),
+        lockState: () => readLock(join(dir, "lock")),
         applied: () => {
             const raw = readJson(appliedPath);
             if (raw === undefined)
@@ -217,16 +310,30 @@ function makeSession(root, dir, anchor, diff) {
                 throw new SessionFileError(`${appliedPath} is not an applied record`);
             return applied;
         },
-        recordApplied: (version, result) => writeJson(appliedPath, {
+        recordApplied: (plan, result) => writeJson(appliedPath, {
             schema: "follow-me/applied@1",
-            version,
+            version: plan.version,
             branch: result.branch,
             head: result.head,
+            hash: plan.hash,
+            signed: result.signed,
         }),
     };
 }
+/** The top level of the work tree holding cwd. */
+async function rootOf(cwd) {
+    try {
+        return await repoRoot(cwd);
+    }
+    catch (error) {
+        if (error instanceof GitError && error.message.includes("not a git repository")) {
+            throw new NotARepositoryError();
+        }
+        throw error;
+    }
+}
 async function locate(repo, branch) {
-    const root = await repoRoot(repo);
+    const root = await rootOf(repo);
     const name = branch ?? (await currentBranch(root));
     if (name === null)
         throw new Error("HEAD is detached; pass --branch <name>");
@@ -237,7 +344,7 @@ async function locate(repo, branch) {
         writeFileSync(ignore, "*\n");
     return { root, branch: name, dir: join(top, slugOf(name)) };
 }
-function readAnchor(dir) {
+function readAnchorIn(dir) {
     const path = join(dir, "session.json");
     const raw = readJson(path);
     if (raw === undefined)
@@ -247,10 +354,19 @@ function readAnchor(dir) {
         throw new SessionFileError(`${path} is not a session anchor`);
     return anchor;
 }
+function readAnchor(where) {
+    const anchor = readAnchorIn(where.dir);
+    if (anchor === null)
+        return null;
+    if (anchor.branch !== where.branch) {
+        throw new SessionFileError(`${where.dir} holds the session of branch ${anchor.branch}, and ${where.branch} maps to the same directory; rename one of the two branches`);
+    }
+    return anchor;
+}
 /** Anchors the session to the branch's current tip, creating it if needed. Plans and reviews stay. */
 export async function extractSession(repo, opts = {}) {
     const where = await locate(repo, opts.branch);
-    const baseRef = opts.base ?? readAnchor(where.dir)?.baseRef ?? (await defaultBaseRef(where.root));
+    const baseRef = opts.base ?? readAnchor(where)?.baseRef ?? (await defaultBaseRef(where.root));
     const diff = await loadDiff(where.root, baseRef, where.branch);
     const anchor = {
         schema: "follow-me/session@1",
@@ -266,7 +382,7 @@ export async function extractSession(repo, opts = {}) {
 /** Opens the session for a branch, creating it on first use. Throws if the branch moved since. */
 export async function openSession(repo, opts = {}) {
     const where = await locate(repo, opts.branch);
-    const anchor = readAnchor(where.dir);
+    const anchor = readAnchor(where);
     if (anchor === null)
         return extractSession(where.root, { ...opts, branch: where.branch });
     const tip = await resolveCommit(where.root, where.branch);
@@ -276,3 +392,94 @@ export async function openSession(repo, opts = {}) {
     const diff = await loadDiff(where.root, anchor.base, anchor.tip);
     return makeSession(where.root, where.dir, anchor, diff);
 }
+/**
+ * Opens the session stored in a `<root>/.follow-me/<slug>` directory, as the review server does
+ * when a CLI registers it. Throws like openSession when the branch moved.
+ */
+export async function openSessionAt(dir) {
+    const top = dirname(dir);
+    if (basename(top) !== ".follow-me")
+        throw new SessionFileError(`${dir} is not a session directory`);
+    const anchor = readAnchorIn(dir);
+    if (anchor === null)
+        throw new SessionFileError(`${dir} has no session.json`);
+    if (slugOf(anchor.branch) !== basename(dir)) {
+        throw new SessionFileError(`${dir} holds the session of branch ${anchor.branch}`);
+    }
+    return openSession(dirname(top), { branch: anchor.branch });
+}
+/** "<name>.<pid>.<random>.tmp" as written by writeJson, the lock and the review server. */
+function abandonedTemps(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { recursive: true, encoding: "utf8" })
+        .filter((name) => {
+        const pid = Number(/\.([0-9]+)\.[0-9a-f-]+\.tmp$/.exec(name)?.[1]);
+        return Number.isInteger(pid) && pid > 0 && !isAlive(pid);
+    })
+        .sort()
+        .map((name) => join(dir, name));
+}
+/** Review drafts for a version at or below the latest finished review; none can be resumed. */
+function deadReviewDrafts(reviewsDir) {
+    const latest = versions(reviewsDir).at(-1)?.version ?? 0;
+    if (!existsSync(reviewsDir))
+        return [];
+    return readdirSync(reviewsDir)
+        .filter((name) => {
+        const n = Number(/^v([1-9][0-9]*)\.draft\.json$/.exec(name)?.[1]);
+        return Number.isInteger(n) && n <= latest;
+    })
+        .sort()
+        .map((name) => join(reviewsDir, name));
+}
+/**
+ * Finds what follow-me left behind in this worktree: sessions whose branch is gone, review drafts
+ * no review can resume, locks and temp files of dead processes, and object quarantines of dead
+ * applies. With all, the whole .follow-me/ directory. Removes them unless dryRun. Sessions held by
+ * a live process are left alone, and all refuses while one exists.
+ */
+export async function cleanSessions(repo, opts) {
+    const root = await rootOf(repo);
+    const top = join(root, ".follow-me");
+    const sessions = existsSync(top)
+        ? readdirSync(top, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => join(top, e.name))
+            .sort()
+        : [];
+    const found = [];
+    for (const dir of sessions) {
+        const lock = readLock(join(dir, "lock"));
+        if (lock.kind === "held") {
+            if (!opts.all)
+                continue;
+            throw new SessionLockedError(`${dir} is busy: pid ${lock.pid} is running follow-me ${lock.command}; wait for it to finish or stop it`);
+        }
+        if (opts.all)
+            continue;
+        const anchor = readAnchorIn(dir);
+        if (anchor !== null && !(await branchExists(root, anchor.branch))) {
+            found.push(dir);
+            continue;
+        }
+        if (lock.kind === "stale")
+            found.push(join(dir, "lock"));
+        const reviews = join(dir, "reviews");
+        found.push(...abandonedTemps(dir), ...deadReviewDrafts(reviews), ...deadReviewDrafts(join(reviews, "walk")));
+    }
+    if (opts.all && existsSync(top))
+        found.push(top);
+    const objects = await objectsDir(root);
+    for (const name of readdirSync(objects).sort()) {
+        if (!name.startsWith(QUARANTINE_PREFIX))
+            continue;
+        const pid = Number(name.slice(QUARANTINE_PREFIX.length).split("-")[0]);
+        if (Number.isInteger(pid) && !isAlive(pid))
+            found.push(join(objects, name));
+    }
+    if (!opts.dryRun)
+        for (const path of found)
+            rmSync(path, { recursive: true, force: true });
+    return found;
+}