@shiyuphan/follow-me 0.1.0 → 0.1.1

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" }];
+}

package/dist/src/host.js

@@ -0,0 +1,293 @@
+import { spawn } from "node:child_process";
+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 { 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";
+const RECORD = "server.json";
+const DEFAULT_IDLE_MS = 30_000;
+const START_TIMEOUT_MS = 10_000;
+const STOP_TIMEOUT_MS = 5_000;
+/** `FOLLOW_ME_HOME`, else `$XDG_STATE_HOME/follow-me`, else `~/.local/state/follow-me`. */
+export function stateDir(env = process.env, home = homedir()) {
+    const own = env["FOLLOW_ME_HOME"];
+    if (own)
+        return own;
+    const xdg = env["XDG_STATE_HOME"];
+    return join(xdg ? xdg : join(home, ".local", "state"), "follow-me");
+}
+/** How long a server waits for a new session after its last one ended. */
+export function idleMs(env = process.env) {
+    const raw = Number(env["FOLLOW_ME_IDLE_MS"]);
+    return Number.isInteger(raw) && raw >= 0 ? raw : DEFAULT_IDLE_MS;
+}
+function isPort(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535;
+}
+function isFields(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The record as written; a missing or unreadable one reads as no server. */
+export function readServerRecord(dir) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(join(dir, RECORD), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!isFields(raw))
+        return null;
+    const { pid, port, startedAt } = raw;
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+        return null;
+    if (!isPort(port) || typeof startedAt !== "string")
+        return null;
+    return { pid, port, startedAt };
+}
+/** The pid of the follow-me server answering on this port, or null for anything else. */
+export async function probeHealth(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
+            signal: AbortSignal.timeout(1_000),
+        });
+        const body = await res.json();
+        if (!isFields(body) || body["app"] !== HEALTH_APP)
+            return null;
+        const pid = body["pid"];
+        return typeof pid === "number" && Number.isInteger(pid) ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The user's server if its record names a live process that answers as ours. */
+export async function findServer(dir) {
+    const record = readServerRecord(dir);
+    if (record === null || !isAlive(record.pid))
+        return null;
+    return (await probeHealth(record.port)) === record.pid ? record : null;
+}
+/**
+ * Writes server.json unless a live server already owns it, and returns the record that holds.
+ * Linking a complete temp file fails when the record exists, so two servers starting at once
+ * cannot both claim it; a record left by a dead server is replaced.
+ */
+async function claimRecord(dir, mine) {
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, RECORD);
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+        writeFileSync(temp, `${JSON.stringify(mine, null, 2)}\n`);
+        try {
+            linkSync(temp, path);
+            return mine;
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+                throw error;
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+        const live = await findServer(dir);
+        if (live !== null)
+            return live;
+        rmSync(path, { force: true });
+    }
+    throw new Error(`could not claim ${path}`);
+}
+function removeRecord(dir, pid) {
+    if (readServerRecord(dir)?.pid === pid)
+        rmSync(join(dir, RECORD), { force: true });
+}
+async function loadHosted(registration) {
+    const { dir, mode, version, hash, lockToken } = registration;
+    try {
+        const session = await openSessionAt(dir);
+        const branch = session.anchor.branch;
+        const stored = session.plans().find((p) => p.version === version);
+        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`);
+        }
+        const verdict = validatePlan(session.diff, serializePlanFile(stored.file), {
+            lastReview: session.lastReview(),
+        });
+        if (!verdict.ok) {
+            throw new RegistrationError(`plan v${version} no longer fits ${branch}; check it again`);
+        }
+        const reviewsDir = join(session.dir, "reviews");
+        const comments = await loadDraftComments(reviewsDir, version);
+        const command = mode === "walk" ? "walk" : "review";
+        const lock = lockToken === null ? session.lock(command) : session.adoptLock(lockToken, command);
+        return {
+            repo: session.root,
+            reviewsDir,
+            release: lock.release,
+            state: {
+                mode,
+                anchor: session.anchor,
+                version,
+                planHash: verdict.plan.hash,
+                commits: verdict.plan.commits,
+                units: [...session.diff.units.values()],
+                comments,
+            },
+        };
+    }
+    catch (error) {
+        const refusal = error instanceof SessionLockedError ||
+            error instanceof BranchMovedError ||
+            error instanceof SessionFileError;
+        if (refusal)
+            throw new RegistrationError(error.message);
+        throw error;
+    }
+}
+export function portFallbackMessage(requested, used) {
+    return `port ${requested} is in use by another program, using ${used}`;
+}
+/**
+ * Starts this process as the user's server, or finds that one is already up. A requested port
+ * held by our own server means attach; held by anything else, the server takes a free port.
+ */
+export async function startOrAttach(dir, port, say) {
+    const requested = port ?? 0;
+    const options = { idleMs: idleMs(), load: loadHosted };
+    let host;
+    try {
+        host = await startServer({ ...options, port: requested });
+    }
+    catch (error) {
+        if (!(error instanceof PortInUseError))
+            throw error;
+        if ((await probeHealth(requested)) !== null)
+            return { kind: "attached", port: requested };
+        host = await startServer({ ...options, port: 0 });
+        say(portFallbackMessage(requested, host.port));
+    }
+    const mine = { pid: process.pid, port: host.port, startedAt: new Date().toISOString() };
+    const owner = await claimRecord(dir, mine);
+    if (owner.pid !== process.pid) {
+        await host.close();
+        return { kind: "attached", port: owner.port };
+    }
+    const stop = () => void host.close();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    void host.closed.then(() => {
+        process.off("SIGINT", stop);
+        process.off("SIGTERM", stop);
+        removeRecord(dir, process.pid);
+    });
+    return { kind: "started", host };
+}
+/**
+ * Starts the server as a detached `follow-me server run` and waits until it answers. Its output
+ * goes to server.log in the state dir.
+ */
+export async function spawnDetached(dir, port) {
+    mkdirSync(dir, { recursive: true });
+    const logPath = join(dir, "server.log");
+    const log = openSync(logPath, "a");
+    const script = process.argv[1];
+    if (script === undefined)
+        throw new Error("cannot tell which script runs follow-me");
+    const args = [...process.execArgv, script, "server", "run"];
+    if (port !== undefined)
+        args.push("--port", String(port));
+    const child = spawn(process.execPath, args, {
+        detached: true,
+        stdio: ["ignore", log, log],
+        env: process.env,
+    });
+    closeSync(log);
+    child.unref();
+    const deadline = Date.now() + START_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        const live = await findServer(dir);
+        if (live !== null)
+            return live;
+        if (child.exitCode !== null)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    throw new Error(`the review server did not start; see ${logPath}`);
+}
+async function call(port, method, path, body) {
+    const res = await fetch(`http://127.0.0.1:${port}${path}`, {
+        method,
+        headers: { "content-type": "application/json" },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    const payload = await res.json();
+    if (!res.ok) {
+        const reason = isFields(payload) ? payload["error"] : undefined;
+        throw new RegistrationError(typeof reason === "string" ? reason : `${method} ${path} failed with ${res.status}`);
+    }
+    return payload;
+}
+function parseSummary(raw) {
+    if (!isFields(raw))
+        return null;
+    const { id, url, repo, branch, mode, version, comments } = raw;
+    if (typeof url !== "string" || typeof repo !== "string")
+        return null;
+    if (typeof branch !== "string" || (mode !== "split" && mode !== "walk"))
+        return null;
+    if (!isSessionId(id) || !isPlanVersion(version) || typeof comments !== "number")
+        return null;
+    return { id, url, repo, branch, mode, version, comments };
+}
+/** Registers a session with the server on this port; the same session yields the same URL. */
+export async function registerWith(port, registration) {
+    const summary = parseSummary(await call(port, "POST", "/api/sessions", registration));
+    if (summary === null)
+        throw new RegistrationError("the server answered with a malformed session");
+    return summary;
+}
+export async function listSessions(port) {
+    const raw = await call(port, "GET", "/api/sessions");
+    if (!Array.isArray(raw))
+        throw new RegistrationError("the server listed malformed sessions");
+    return raw.flatMap((item) => {
+        const summary = parseSummary(item);
+        return summary === null ? [] : [summary];
+    });
+}
+export function sessionUrl(port, summary) {
+    return `http://127.0.0.1:${port}${summary.url}`;
+}
+/**
+ * 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.
+ */
+export async function stopServer(dir) {
+    const live = await findServer(dir);
+    if (live === null) {
+        const record = readServerRecord(dir);
+        if (record !== null)
+            removeRecord(dir, record.pid);
+        return null;
+    }
+    process.kill(live.pid, "SIGTERM");
+    const deadline = Date.now() + STOP_TIMEOUT_MS;
+    while (isAlive(live.pid)) {
+        if (Date.now() > deadline)
+            throw new Error(`server pid ${live.pid} did not stop`);
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    removeRecord(dir, live.pid);
+    return live;
+}
+export function openBrowser(url) {
+    const command = process.platform === "darwin" ? "open" : "xdg-open";
+    const child = spawn(command, [url], { stdio: "ignore", detached: true });
+    child.on("error", (error) => console.error(`could not open a browser: ${error.message}`));
+    child.unref();
+}

package/dist/src/install.js

@@ -0,0 +1,131 @@
+import { existsSync, mkdirSync, readFileSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+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 {
+    name = "InstallError";
+}
+/**
+ * The skill folder ships next to `dist/` in the package and next to `src/` in a checkout, so
+ * walk up from this module until a folder holds it.
+ */
+export function findSkillDir(from = import.meta.url) {
+    let dir = dirname(fileURLToPath(from));
+    for (;;) {
+        const candidate = join(dir, "skills", SKILL_NAME);
+        if (existsSync(join(candidate, "SKILL.md")))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            throw new InstallError(`cannot find skills/${SKILL_NAME} next to the package`);
+        dir = parent;
+    }
+}
+export function detectHarnesses(home) {
+    return HARNESSES.filter((h) => h.probes.some((probe) => existsSync(join(home, probe))));
+}
+function chooseHarnesses(options, home) {
+    if (options.all && options.harness !== undefined) {
+        throw new InstallError("use --all or --harness, not both");
+    }
+    if (options.all)
+        return HARNESSES;
+    if (options.harness !== undefined) {
+        return options.harness.split(",").map((id) => {
+            const found = findHarness(id.trim());
+            if (!found) {
+                const known = HARNESSES.map((h) => h.id).join(", ");
+                throw new InstallError(`unknown harness "${id}" (known: ${known})`);
+            }
+            return found;
+        });
+    }
+    const found = detectHarnesses(home);
+    if (found.length === 0) {
+        throw new InstallError("no harness config directory found; pass --harness <id> or --all (see --list)");
+    }
+    return found;
+}
+/**
+ * The files install writes and uninstall removes. Harnesses that share a skills directory (Codex
+ * and the generic one) plan the same file once.
+ */
+export function planSkillFiles(options, home, repoRoot) {
+    const scope = options.user ? "user" : "project";
+    const byPath = new Map();
+    for (const harness of chooseHarnesses(options, home)) {
+        for (const file of plannedInstall(harness, scope, home, repoRoot)) {
+            byPath.set(file.path, file);
+        }
+    }
+    return [...byPath.values()];
+}
+function writeSkill(skillDir, file, dryRun) {
+    const content = readFileSync(join(skillDir, file.source));
+    const current = existsSync(file.path) ? readFileSync(file.path) : null;
+    if (current?.equals(content))
+        return `unchanged ${file.path}`;
+    if (dryRun)
+        return `would write ${file.path}`;
+    mkdirSync(dirname(file.path), { recursive: true });
+    writeFileSync(file.path, content);
+    return `wrote ${file.path}`;
+}
+/** Removes the file and then its follow-me folder if that is left empty, never a parent. */
+function removeSkill(file, dryRun) {
+    if (!existsSync(file.path))
+        return `absent ${file.path}`;
+    if (dryRun)
+        return `would remove ${file.path}`;
+    rmSync(file.path);
+    const folder = dirname(file.path);
+    if (basename(folder) === SKILL_NAME) {
+        try {
+            rmdirSync(folder);
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOTEMPTY"))
+                throw error;
+        }
+    }
+    return `removed ${file.path}`;
+}
+function listTable() {
+    return HARNESSES.flatMap((h) => [
+        `${h.id}  ${h.name}`,
+        `  project  ${h.projectDir}/${SKILL_NAME}/SKILL.md`,
+        `  user     ~/${h.userDir}/${SKILL_NAME}/SKILL.md`,
+        `  docs     ${h.docs}`,
+    ]);
+}
+function reportingErrors(run) {
+    try {
+        run();
+        return 0;
+    }
+    catch (error) {
+        if (!(error instanceof InstallError))
+            throw error;
+        process.stderr.write(`follow-me: ${error.message}\n`);
+        return 1;
+    }
+}
+export function runInstall(options, home, repoRoot, say, skillDir = findSkillDir()) {
+    return reportingErrors(() => {
+        if (options.list) {
+            for (const line of listTable())
+                say(line);
+            return;
+        }
+        for (const file of planSkillFiles(options, home, repoRoot)) {
+            say(writeSkill(skillDir, file, options.dryRun));
+        }
+    });
+}
+export function runUninstall(options, home, repoRoot, say) {
+    return reportingErrors(() => {
+        for (const file of planSkillFiles(options, home, repoRoot)) {
+            say(removeSkill(file, options.dryRun));
+        }
+    });
+}