@shiyuphan/follow-me 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 follow-me contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# follow-me
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read a branch the way it was thought, not the way it was committed.
+
+follow-me takes a branch's net change and splits it into fine commits ordered so a reader
+can follow the author's thought process. Individual commits need not compile. The last
+commit's tree is byte-identical to the original tip, and follow-me proves it with git's own
+tree hash. Then it serves a local page where you walk the commits one by one, comment on any
+hunk or line, and hand the comments to a coding agent for the next version.
+
+Two people use it:
+
+- **The author** runs extract, check, apply and review to turn a messy branch into a readable
+  stack before asking for review. Comments on the split go back to the agent, which writes
+  the next plan.
+- **The reviewer** runs `follow-me walk` on someone else's branch to watch it being written,
+  with narration spoken as each line appears, and leaves comments on the code. The result is
+  a code review for the author.
+
+Inspired by [spark-joy](https://github.com/Dansyuqri/spark-joy)'s "split your own changes".
+
+## Install
+
+Requires Node 24 or newer and git. There is no build step; Node runs the TypeScript sources.
+
+```sh
+git clone https://github.com/<you>/follow-me
+cd follow-me && npm install && npm link   # puts `follow-me` on your PATH
+```
+
+## Author flow
+
+Run everything from the repo whose branch you want to split, with that branch checked out.
+
+```sh
+follow-me extract --base main      # anchor a session, list the units (hunks, files, modes)
+follow-me prompt                   # the planner prompt, for a coding agent to read
+# the agent writes .follow-me/<branch>/draft.json
+follow-me check                    # every problem with the draft, at once
+follow-me apply                    # write <branch>-split, prove the tree matches
+follow-me review                   # open the review page; end it to save reviews/v1.json
+follow-me feedback                 # the comments as markdown, for the agent
+```
+
+With Anthropic credentials in the environment, `follow-me plan` writes the draft itself.
+Otherwise the Claude Code skill in `skills/follow-me/` does it; link it into
+`.claude/skills/follow-me/` and ask Claude to split the branch.
+
+After a review, the agent reads the comments, writes a new draft that answers each one in
+`responses`, and runs `check` and `apply` again. Plans are versioned under
+`.follow-me/<branch>/plans/`, reviews under `reviews/`, and a comment counts as answered when
+a later plan lists it.
+
+## Reviewer flow
+
+```sh
+git checkout their-branch
+follow-me walk --base main         # extract, plan, and open playback
+```
+
+Playback walks the commits in order, speaks the narration the planner wrote, and types each
+added line out. Space pauses, `n` and `p` move between commits, and the speed and voice are
+adjustable. Pause on a line to comment on it. Finishing writes `reviews/vN.json`, and
+`follow-me feedback` renders it as a code review grouped by file.
+
+Narration uses the browser's built-in speech synthesis. No key, no network.
+
+## How it works
+
+Every unit comes from one `git diff base..tip`, so hunks of a file never overlap in base
+coordinates. A commit's version of a file is the base lines with that commit's change lines
+swapped in. Nothing is patched, so hunks can be assigned in any order and split by line.
+See `docs/DESIGN.md`.
+
+The user's working tree, index and branches are never touched. Commits are built in a
+temporary index with dates derived from the tip, so the same plan always yields the same
+SHAs and re-running `apply` is a no-op.
+
+## Safety
+
+- `apply` refuses to move a branch it did not create unless `--force`.
+- The review server binds `127.0.0.1` only and rejects cross-origin requests.
+- Everything under `.follow-me/` is ignored by git.
+
+## Development
+
+```sh
+npm run check        # biome, strict tsc, node --test
+node bin/follow-me.ts <command>
+```
+
+Tests run against real git repositories built by `test/fixture-repo.ts`.
+Decisions are logged in `docs/decisions.tsv`.

package/dist/bin/follow-me.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+// `follow-me prompt | head` closes stdout early; that is not an error worth a stack trace.
+process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE")
+        process.exit(0);
+    throw error;
+});
+process.exitCode = await main(process.argv.slice(2), process.cwd());

package/dist/src/anthropic.js

@@ -0,0 +1,101 @@
+import Anthropic from "@anthropic-ai/sdk";
+export const DEFAULT_MODEL = "claude-opus-5-5";
+const MAX_TOKENS = 64000;
+export class PlanRequestError extends Error {
+    failure;
+    constructor(failure, message) {
+        super(message);
+        this.name = "PlanRequestError";
+        this.failure = failure;
+    }
+}
+const narratedUnit = {
+    type: "object",
+    properties: { unit: { type: "string" }, narration: { type: "string" } },
+    required: ["unit", "narration"],
+    additionalProperties: false,
+};
+const unitList = { type: "array", items: { anyOf: [{ type: "string" }, narratedUnit] } };
+/**
+ * Mirrors PlanFile on the wire. Structured outputs need every property required and closed
+ * objects, so commit narration is nullable instead of optional; the plan parser reads null as none.
+ */
+export const PLAN_SCHEMA = {
+    type: "object",
+    properties: {
+        schema: { type: "string", enum: ["follow-me/plan@1"] },
+        base: { type: "string" },
+        tip: { type: "string" },
+        commits: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    message: { type: "string" },
+                    narration: { anyOf: [{ type: "string" }, { type: "null" }] },
+                    units: unitList,
+                },
+                required: ["message", "narration", "units"],
+                additionalProperties: false,
+            },
+        },
+        responses: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    comment: { type: "string" },
+                    status: { type: "string", enum: ["addressed", "declined", "deferred"] },
+                    note: { type: "string" },
+                },
+                required: ["comment", "status", "note"],
+                additionalProperties: false,
+            },
+        },
+    },
+    required: ["schema", "base", "tip", "commits", "responses"],
+    additionalProperties: false,
+};
+const sendWithAnthropic = async ({ model, prompt }) => {
+    const client = new Anthropic();
+    // Streaming because a 64k-token reply outlives the SDK's non-streaming timeout.
+    const stream = client.beta.messages.stream({
+        model,
+        max_tokens: MAX_TOKENS,
+        output_config: { effort: "high", format: { type: "json_schema", schema: PLAN_SCHEMA } },
+        betas: ["server-side-fallback-2026-07-01"],
+        fallbacks: "default",
+        messages: [{ role: "user", content: prompt }],
+    });
+    const message = await stream.finalMessage();
+    const text = message.content.flatMap((block) => (block.type === "text" ? [block.text] : []));
+    return {
+        stopReason: message.stop_reason,
+        text: text.join(""),
+        refusalExplanation: message.stop_details?.explanation ?? null,
+    };
+};
+/**
+ * Asks the model for a plan and returns the parsed JSON. The caller validates it as a plan,
+ * because a schema-conforming reply can still name units that do not exist.
+ */
+export async function requestPlan(prompt, opts = {}) {
+    const send = opts.send ?? sendWithAnthropic;
+    const reply = await send({ model: opts.model ?? DEFAULT_MODEL, prompt });
+    if (reply.stopReason === "refusal") {
+        const why = reply.refusalExplanation ? `: ${reply.refusalExplanation}` : "";
+        throw new PlanRequestError("refusal", `the model declined to write a plan${why}`);
+    }
+    if (reply.stopReason === "max_tokens") {
+        throw new PlanRequestError("truncated", `the plan did not fit in ${MAX_TOKENS} tokens; try a smaller diff`);
+    }
+    if (reply.text.trim() === "") {
+        throw new PlanRequestError("empty", "the model returned no text");
+    }
+    try {
+        return JSON.parse(reply.text);
+    }
+    catch {
+        throw new PlanRequestError("not-json", "the model's reply was not valid JSON");
+    }
+}