@shiyuphan/follow-me 0.1.0 → 0.1.1

package/dist/src/session.js

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { isRepoPath, isSha, isUnitId } from "./diff.js";
-import { currentBranch, defaultBaseRef, loadDiff, repoRoot, resolveCommit } from "./git.js";
+import { branchExists, currentBranch, defaultBaseRef, loadDiff, objectsDir, QUARANTINE_PREFIX, repoRoot, resolveCommit, } from "./git.js";
 import { isArray, isCommentId, isFields, isPlanVersion, parsePlanFile, planHash, serializePlanFile, } from "./plan.js";
 export class BranchMovedError extends Error {
     name = "BranchMovedError";
@@ -11,6 +11,110 @@ export class BranchMovedError extends Error {
 export class SessionFileError extends Error {
     name = "SessionFileError";
 }
+/** 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("/", "-");
 }
@@ -208,6 +312,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)
@@ -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(dir) {
+    const reviewsDir = join(dir, "reviews");
+    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 repoRoot(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"));
+        found.push(...abandonedTemps(dir), ...deadReviewDrafts(dir));
+    }
+    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;
+}

package/dist/src/types.js

@@ -9,7 +9,8 @@
  *   git.ts      the only module that spawns git: load a Diff, write a branch from a ValidPlan.
  *   session.ts  the .follow-me/<slug>/ layout: session anchor, plans, reviews, draft.
  *   prompt.ts   the planner prompt for an agent, and the Anthropic API planner.
- *   server.ts   the local review server and its JSON API; serves ui/.
+ *   server.ts   the review server: a registry of hosted sessions, their JSON API, and ui/.
+ *   host.ts     the one server per user: its record in the state dir, attach, start, stop.
  *   cli.ts      argv -> one call into the modules above.
  */
 export {};

package/dist/ui/app.js

@@ -13,6 +13,9 @@ import {
 
 const $ = (id) => document.getElementById(id);
 
+/** "/s/<id>": this page's session on the shared server. Every session API sits under it. */
+const sessionPrefix = /^\/s\/[^/]+/.exec(location.pathname)?.[0] ?? "";
+
 /** Builds an element. Text always goes through textContent, never innerHTML. */
 function el(tag, props = {}, ...children) {
   const node = document.createElement(tag);
@@ -40,7 +43,7 @@ const openBoxes = new Set();
 const editing = new Set();
 
 async function api(method, path, body) {
-  const res = await fetch(path, {
+  const res = await fetch(`${sessionPrefix}${path}`, {
     method,
     headers: { "content-type": "application/json" },
     body: body === undefined ? undefined : JSON.stringify(body),
@@ -50,6 +53,27 @@ async function api(method, path, body) {
   return payload;
 }
 
+/** Links to every session the server hosts, so one tab can move between workstreams. */
+async function renderSwitcher() {
+  const res = await fetch("/api/sessions").catch(() => null);
+  if (!res?.ok) return;
+  const sessions = await res.json();
+  const here = `${sessionPrefix}/`;
+  const nav = $("sessions");
+  nav.hidden = sessions.length < 2;
+  nav.replaceChildren(
+    ...sessions.map((s) =>
+      el("a", {
+        href: s.url,
+        title: s.repo,
+        "aria-current": s.url === here ? "page" : undefined,
+        text: s.mode === "walk" ? `${s.branch} (walk)` : `${s.branch} v${s.version}`,
+      }),
+    ),
+    el("a", { href: "/", text: "All sessions" }),
+  );
+}
+
 function report(error) {
   $("status").textContent = error ? error.message : "";
 }
@@ -726,6 +750,7 @@ async function endReview() {
           el("code", { text: "follow-me feedback" }),
           " or hand the session to your agent.",
         ),
+    el("p", {}, el("a", { href: "/", text: "All sessions" })),
   );
   done.hidden = false;
 }
@@ -751,6 +776,8 @@ document.addEventListener("keydown", (event) => {
 });
 
 $("end").addEventListener("click", () => guarded(endReview));
+window.addEventListener("focus", () => renderSwitcher());
+renderSwitcher();
 
 guarded(async () => {
   state = await api("GET", "/api/state");

package/dist/ui/index.html

@@ -11,6 +11,7 @@
     <header class="topbar">
       <strong>follow-me</strong>
       <span id="summary" class="muted"></span>
+      <nav id="sessions" class="sessions" aria-label="Sessions" hidden></nav>
       <span id="status" class="status" role="status"></span>
       <button id="view-toggle" type="button" title="Play the branch commit by commit (space)">
         Play

package/dist/ui/style.css

@@ -63,6 +63,41 @@ body {
   background: var(--panel);
 }
 
+.sessions {
+  display: flex;
+  gap: 8px;
+  font-size: 13px;
+}
+
+.sessions[hidden] {
+  display: none;
+}
+
+.sessions a {
+  color: var(--accent);
+}
+
+.sessions a[aria-current="page"] {
+  color: var(--text);
+  font-weight: 600;
+  text-decoration: none;
+}
+
+body.index {
+  display: block;
+  height: auto;
+  padding: 16px 24px;
+}
+
+.session-index {
+  padding-left: 18px;
+}
+
+.session-index a {
+  color: var(--accent);
+  font-weight: 600;
+}
+
 .status {
   margin-left: auto;
   color: var(--del-text);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shiyuphan/follow-me",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Split a branch's final changes into fine, ordered commits that read like the author's thought process, review them hunk by hunk, and hand the review back to a coding agent.",
   "license": "MIT",
   "type": "module",

package/skills/follow-me/SKILL.md

@@ -8,7 +8,7 @@ description: Split the current branch's net change into fine, story-ordered comm
 follow-me rewrites a branch as small commits ordered so a reader follows your thinking. It never
 touches your working tree or index. It writes a new branch and keeps state in `.follow-me/<slug>/`.
 
-Run every command from the repo root. If `follow-me` is not on PATH, ask the user how it is installed.
+Run every command from the repo root. If `follow-me` is not on PATH, ask the user how to run it.
 
 ## First pass
 
@@ -23,7 +23,8 @@ Run every command from the repo root. If `follow-me` is not on PATH, ask the use
    lines are real mistakes.
 5. `follow-me apply` freezes the plan as the next version and writes the branch.
 6. Tell the user to run `follow-me review`. It opens a local page where they comment on messages,
-   positions, hunks and single lines.
+   positions, hunks and single lines. If you start it yourself, use `follow-me review --detach`,
+   which prints the page URL and returns; one server hosts every session the user has open.
 
 ## After a review
 
@@ -62,14 +63,3 @@ plan reviews only.
 - Use unit ids exactly as printed. `h_x:0-3,7` takes change lines 0 to 3 and 7 of that hunk.
   A bare `h_x` takes whatever lines no other commit claimed.
 - `f_` and `m_` units are whole; they never take line lists.
-
-## Install
-
-Copy or symlink this folder into the repo you want to use it in:
-
-```sh
-mkdir -p .claude/skills
-ln -s /path/to/follow-me/skills/follow-me .claude/skills/follow-me
-```
-
-For every repo at once, link it into `~/.claude/skills/follow-me` instead.