thurview 0.12.0 → 0.13.0

package/README.md

@@ -37,8 +37,8 @@ back with changes requested.
 
 <details>
 <summary><b>Other ways to install</b> - pin the skill to a release, install the
-command from npm, run from a checkout, session hooks, the review-fix
-skill</summary>
+command from npm, run from a checkout, session hooks, the thurview-design and
+review-fix skills</summary>
 
 `--global` installs for your user, so one install covers every repository.
 `universal` puts the one real copy in `~/.agents/skills/thurview`, the directory
@@ -92,10 +92,13 @@ with the reviews of its working directory. `thurview setup skill` links the
 skill from this checkout instead of the `skills` CLI copy; use one or the
 other.
 
-Also available: `review-fix`, the browserless companion skill described
-[below](#review-and-fix).
+Also available: `thurview-design`, which authors the design kind described
+[below](#how-it-works), and `review-fix`, the browserless companion skill
+described [below](#review-and-fix).
 
 ```sh
+npx skills@latest add https://github.com/Thurbeen/thurview \
+  --skill thurview-design --agent universal claude-code --global --yes
 npx skills@latest add https://github.com/Thurbeen/thurview \
   --skill review-fix --agent universal claude-code --global --yes
 ```
@@ -115,6 +118,12 @@ architecture well enough to spot design problems themselves. It has no diff and
 nothing to approve, it surfaces structure rather than grading it, and it states
 what it did not examine.
 
+And it reads a plan. A **design** is the same document over a change that is
+not written yet: one pinned commit — the code it argues from — anchors on the
+code as it stands, and what it would build declared as proposals, each attached
+to the code it lands in today. An anchor never points at code that does not
+exist; the reader approves the design or sends it back.
+
 It does not review the code for you. It helps you understand it fast enough
 to review it yourself.
 
@@ -201,20 +210,21 @@ bar.
 
 ## CLI
 
-| Command                                                               | Purpose                                                           |
-| --------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| `thurview scaffold [--pr N \| --base R --head R]`                     | Create a review pinned to exact commits (`--update` re-pins)      |
-| `thurview explain [<path>] [--commit R]`                              | Create a code explainer of a codebase or subsystem at one commit  |
-| `thurview info [--all]`                                               | Reviews bound to this worktree                                    |
-| `thurview publish --review ID [--view T] [--open]`                    | Validate the document and map, seal a revision                    |
-| `thurview open --review ID [--view T]`                                | Start the server if needed and open the browser                   |
-| `thurview wait --review ID [--timeout S]`                             | Block until the reader needs the agent                            |
-| `thurview threads list\|get\|reply\|resolve`                          | Read and answer threads                                           |
-| `thurview graph interfaces\|impact\|callers\|tests-for\|architecture` | Ask the code graph at a review's pins, or at `--base`/`--head`    |
-| `thurview forge status\|prior\|pass\|submit\|reply`                   | Read a change request through its forge, and post the review back |
-| `thurview serve` / `thurview stop`                                    | Run the server in the foreground / stop the background one        |
-| `thurview setup hooks\|skill\|status`                                 | Session hooks, agent skill, install state                         |
-| `thurview update`                                                     | Self-update from npm                                              |
+| Command                                                               | Purpose                                                               |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `thurview scaffold [--pr N \| --base R --head R]`                     | Create a review pinned to exact commits (`--update` re-pins)          |
+| `thurview explain [<path>] [--commit R]`                              | Create a code explainer of a codebase or subsystem at one commit      |
+| `thurview design [<path>] [--commit R]`                               | Create a design of what to build, pinned to the commit it argues from |
+| `thurview info [--all]`                                               | Reviews, explainers and designs bound to this worktree                |
+| `thurview publish --review ID [--view T] [--open]`                    | Validate the document and map, seal a revision                        |
+| `thurview open --review ID [--view T]`                                | Start the server if needed and open the browser                       |
+| `thurview wait --review ID [--timeout S]`                             | Block until the reader needs the agent                                |
+| `thurview threads list\|get\|reply\|resolve`                          | Read and answer threads                                               |
+| `thurview graph interfaces\|impact\|callers\|tests-for\|architecture` | Ask the code graph at a review's pins, or at `--base`/`--head`        |
+| `thurview forge status\|prior\|pass\|submit\|reply`                   | Read a change request through its forge, and post the review back     |
+| `thurview serve` / `thurview stop`                                    | Run the server in the foreground / stop the background one            |
+| `thurview setup hooks\|skill\|status`                                 | Session hooks, agent skill, install state                             |
+| `thurview update`                                                     | Self-update from npm                                                  |
 
 thurview is an [AXI](https://axi.md): built for agents that drive it through a
 shell. Output is [TOON](https://toonformat.dev) on stdout, errors are
@@ -302,12 +312,23 @@ An explainer writes the same files, minus `interfaces`: there is no change to
 derive a delta from, and `graph: base` on an anchor is an error because there
 is one commit.
 
+A design writes the same files, and `interfaces` means something else in it:
+each entry is a **proposal** — what the design would add, change or remove,
+with the anchor of the code that proposal lands in, replaces or plugs into
+today. `graph: base` is an error for the same reason as in an explainer, a
+`symbol:` entry is an error because no diff derived one, and a design that
+proposes nothing is refused: that document is an explainer. In its `map.yaml`,
+`base` is the structure as it stands and `nodes` the structure it proposes, so
+a proposed part may own files that do not exist yet while a `base` node may
+not.
+
 `thurview publish` rejects an anchor whose file or lines do not exist at the
 pinned commit, a call stack frame that claims an added or removed call the
 diff does not show, a storage operation on an unknown field, a map edge
 to an unknown node, an interface annotation for a symbol the change did not
 move, a declared interface whose anchor holds no added or deleted line, and an
-explainer that anchors nothing at all. The full format is in
+explainer that anchors nothing at all, and a design that proposes nothing or
+whose proposal names no site in the code as it stands. The full format is in
 [skills/thurview/references](skills/thurview/references).
 
 Optional guidance for the agent: `~/.thurview/THURVIEW.md` for you,

package/dist/cli.js

@@ -24,7 +24,7 @@ import { parseSubmission, longComments, buildPass } from "./forge/submission.js"
 import { VERSION } from "./version.js";
 const execFileP = promisify(execFile);
 const HERE = dirname(fileURLToPath(import.meta.url));
-const DESCRIPTION = "Guided, evidence-anchored reviews of a change and explainers of a codebase, read and answered in the browser";
+const DESCRIPTION = "Guided, evidence-anchored reviews of a change, explainers of a codebase and designs of what to build, read and answered in the browser";
 function note(msg) {
     process.stderr.write(msg + "\n");
 }
@@ -134,9 +134,9 @@ async function reviewRow(r, fields) {
         row["binding"] = bindingLabel(r.binding);
     if (fields.has("all") || fields.has("pins"))
         row["pins"] =
-            kindOf(r) === "explainer"
-                ? r.pins.head.slice(0, 12)
-                : `${r.pins.base.slice(0, 12)}..${r.pins.head.slice(0, 12)}`;
+            kindOf(r) === "review"
+                ? `${r.pins.base.slice(0, 12)}..${r.pins.head.slice(0, 12)}`
+                : r.pins.head.slice(0, 12);
     if (fields.has("all") || fields.has("worktree"))
         row["worktree"] = r.worktree;
     if (fields.has("all") || fields.has("inSync"))
@@ -323,6 +323,150 @@ const TEMPLATE_EXPLAIN_MAP = `# The structure of the code at the pinned commit:
 nodes: []
 edges: []
 `;
+const TEMPLATE_DESIGN_MD = (title) => `# ${title}
+
+**Summary**
+
+- The agent is still writing this design. The page offers the new revision
+  when the proposal lands.
+`;
+const TEMPLATE_DESIGN_DATA = `# Typed inputs for the design: actors, anchors, stores, and the proposals it
+# makes. A design is pinned to ONE commit - the code as it stands, which the
+# design changes - so every anchor reads that commit and \`graph: base\` is an
+# error.
+#
+# An anchor is evidence, never a proposal. It points at code that exists today:
+# what the design changes, and what constrains it.
+#
+# anchors:
+#   login:
+#     title: where a request is authenticated today
+#     peek: { file: src/auth.ts, from: 41, to: 58 }
+#
+# interfaces holds what the design WOULD add, change or remove. Each entry names
+# the interface, what it would let a consumer do, and the anchor of the code it
+# lands in, replaces or plugs into today. A design with no entry here proposes
+# nothing, and publish refuses it: that document is a code explainer.
+#
+# interfaces:
+#   strict:
+#     name: auth.login --strict
+#     change: added
+#     capability: Rejects an empty user instead of answering false.
+#     anchor: login
+actors: {}
+anchors: {}
+stores: {}
+interfaces: {}
+`;
+const TEMPLATE_DESIGN_MAP = `# The structure the design proposes, with the structure as it stands under
+# \`base\`, so the Map tab shows what it adds, changes and removes. A node under
+# \`nodes\` may own files that do not exist yet - that is a proposed part. A node
+# under \`base\` may not: it is a claim about today, and publish warns.
+# Seed base from \`thurview graph architecture\`.
+nodes: []
+edges: []
+`;
+const EXPLAINER = {
+    kind: "explainer",
+    command: "explain",
+    title: (scope, worktree) => scope === "**" ? worktree.split("/").pop() || "Codebase" : scope.replace(/\/\*\*$/, ""),
+    templates: { md: TEMPLATE_EXPLAIN_MD, data: TEMPLATE_EXPLAIN_DATA, map: TEMPLATE_EXPLAIN_MAP },
+};
+const DESIGN = {
+    kind: "design",
+    command: "design",
+    title: (scope) => (scope === "**" ? "Design" : `${scope.replace(/\/\*\*$/, "")} design`),
+    templates: { md: TEMPLATE_DESIGN_MD, data: TEMPLATE_DESIGN_DATA, map: TEMPLATE_DESIGN_MAP },
+};
+/** The kind with its article, so a generated sentence reads as one: "an explainer". */
+function kindWord(kind) {
+    return kind === "explainer" ? "an explainer" : kind === "design" ? "a design" : "a review";
+}
+/** The command that re-pins a document of this kind, for a message that offers it. */
+function repinCommand(kind) {
+    return kind === "review"
+        ? "thurview scaffold"
+        : `thurview ${kind === "design" ? "design" : "explain"}`;
+}
+async function pinOneCommit(p, k) {
+    const worktree = await worktreeOf(process.cwd());
+    if (!worktree)
+        throw new AxiError("not inside a git repository", "VALIDATION_ERROR", [
+            `Run \`thurview ${k.command}\` inside the source worktree`,
+        ]);
+    const existing = bool(p, "update") || str(p, "review") ? await resolveReview(str(p, "review")) : null;
+    if (existing && kindOf(existing) !== k.kind) {
+        const other = kindOf(existing);
+        throw new AxiError(`${short(existing.id)} is ${kindWord(other)}, not ${kindWord(k.kind)}`, "VALIDATION_ERROR", [
+            `Run \`${repinCommand(other)} --update --review ${short(existing.id)}\` to re-pin that ${other}`,
+            `Run \`thurview ${k.command}\` with no --review to start ${kindWord(k.kind)}`,
+        ]);
+    }
+    const scope = scopeGlob(p.positional[0] ?? existing?.binding.name);
+    let commit;
+    try {
+        commit = await g.revParse(worktree, str(p, "commit") ?? "HEAD");
+    }
+    catch (e) {
+        throw new AxiError(e.message, "VALIDATION_ERROR", [
+            `Pass a resolvable ref: \`thurview ${k.command} --commit <ref>\``,
+        ]);
+    }
+    // A scope that matches nothing is a typo, and a document of nothing would
+    // still publish and still state honest-looking coverage of zero files.
+    const files = await g.listFiles(worktree, commit);
+    const inScope = scope === "**" ? files : files.filter((f) => globToRegExp(scope).test(f));
+    if (!inScope.length)
+        throw new AxiError(`no file matches "${scope}" at ${commit.slice(0, 12)}`, "VALIDATION_ERROR", [
+            `Pass a path that exists at that commit: \`thurview ${k.command} src/server\``,
+            `Run \`thurview ${k.command}\` with no scope for the whole repository`,
+        ]);
+    const binding = { kind: "codebase", name: scope };
+    if (existing) {
+        existing.pins = { base: commit, head: commit };
+        existing.binding = binding;
+        if (str(p, "title"))
+            existing.title = str(p, "title");
+        await writeReview(existing);
+        return { review: existing, reused: false, scope, commit, worktree, inScope };
+    }
+    const match = bool(p, "new")
+        ? []
+        : (await reviewsFor(worktree)).filter((r) => kindOf(r) === k.kind &&
+            r.binding.name === scope &&
+            r.status !== "accepted" &&
+            r.status !== "closed");
+    if (match.length) {
+        const review = match[0];
+        review.pins = { base: commit, head: commit };
+        await writeReview(review);
+        return { review, reused: true, scope, commit, worktree, inScope };
+    }
+    const id = newId();
+    const review = {
+        schema: SCHEMA,
+        id,
+        kind: k.kind,
+        title: str(p, "title") || k.title(scope, worktree),
+        worktree,
+        repoRoot: worktree,
+        binding,
+        pins: { base: commit, head: commit },
+        status: "draft",
+        revision: 0,
+        dismissed: false,
+        createdAt: now(),
+        updatedAt: now(),
+    };
+    await mkdir(reviewDir(id), { recursive: true });
+    await writeText(join(reviewDir(id), "review.md"), k.templates.md(review.title));
+    await writeText(join(reviewDir(id), "data.yaml"), k.templates.data);
+    await writeText(join(reviewDir(id), "map.yaml"), k.templates.map);
+    await writeText(join(reviewDir(id), "theme.yaml"), TEMPLATE_THEME);
+    await writeReview(review);
+    return { review, reused: false, scope, commit, worktree, inScope };
+}
 // ---- commands ----
 const SPECS = {
     scaffold: {
@@ -368,8 +512,25 @@ const SPECS = {
             "thurview explain --update --review <id>",
         ],
     },
+    design: {
+        description: "Create a design or architecture document: what to build, argued against the code as it stands",
+        args: "[<path scope>]",
+        flags: {
+            commit: { kind: "string", help: "commit to pin (default: HEAD)" },
+            title: { kind: "string", help: "initial title" },
+            new: { kind: "boolean", help: "create another design even if one matches the scope" },
+            update: { kind: "boolean", help: "re-pin an existing design to a new commit" },
+            review: { kind: "string", help: "design to update (id prefix)" },
+        },
+        examples: [
+            "thurview design",
+            "thurview design src/server",
+            "thurview design --title 'Queue the forge pass'",
+            "thurview design --update --review <id>",
+        ],
+    },
     info: {
-        description: "Reviews and explainers bound to this worktree (or all of them with --all)",
+        description: "Reviews, explainers and designs bound to this worktree (or all of them with --all)",
         flags: {
             all: { kind: "boolean", help: "every review, not only this worktree" },
             fields: {
@@ -553,6 +714,7 @@ async function homeView() {
                 "Run `thurview scaffold` to create a review of the current branch",
                 "Run `thurview scaffold --pr <number>` for a pull request",
                 "Run `thurview explain [<path>]` to explain the codebase at HEAD instead",
+                "Run `thurview design [<path>]` to design a change before writing it",
             ],
         };
     const reviews = [];
@@ -719,87 +881,8 @@ const commands = {
     },
     async explain(args) {
         const p = parseFlags("explain", args, spec("explain").flags, 1);
-        const cwd = process.cwd();
-        const worktree = await worktreeOf(cwd);
-        if (!worktree)
-            throw new AxiError("not inside a git repository", "VALIDATION_ERROR", [
-                "Run `thurview explain` inside the source worktree",
-            ]);
-        const existing = bool(p, "update") || str(p, "review") ? await resolveReview(str(p, "review")) : null;
-        if (existing && kindOf(existing) !== "explainer")
-            throw new AxiError(`${short(existing.id)} is a review, not an explainer`, "VALIDATION_ERROR", [
-                "Run `thurview scaffold --update --review <id>` to re-pin a review",
-                "Run `thurview explain` with no --review to start an explainer",
-            ]);
-        const scope = scopeGlob(p.positional[0] ?? existing?.binding.name);
-        let commit;
-        try {
-            commit = await g.revParse(worktree, str(p, "commit") ?? "HEAD");
-        }
-        catch (e) {
-            throw new AxiError(e.message, "VALIDATION_ERROR", [
-                "Pass a resolvable ref: `thurview explain --commit <ref>`",
-            ]);
-        }
-        // A scope that matches nothing is a typo, and an explainer of nothing would
-        // still publish and still state honest-looking coverage of zero files.
-        const files = await g.listFiles(worktree, commit);
-        const inScope = scope === "**" ? files : files.filter((f) => globToRegExp(scope).test(f));
-        if (!inScope.length)
-            throw new AxiError(`no file matches "${scope}" at ${commit.slice(0, 12)}`, "VALIDATION_ERROR", [
-                "Pass a path that exists at that commit: `thurview explain src/server`",
-                "Run `thurview explain` with no scope for the whole repository",
-            ]);
-        const binding = { kind: "codebase", name: scope };
-        const defaultTitle = scope === "**" ? worktree.split("/").pop() || "Codebase" : scope.replace(/\/\*\*$/, "");
-        let review;
-        let reused = false;
-        if (existing) {
-            review = existing;
-            review.pins = { base: commit, head: commit };
-            review.binding = binding;
-            if (str(p, "title"))
-                review.title = str(p, "title");
-            await writeReview(review);
-        }
-        else {
-            const match = bool(p, "new")
-                ? []
-                : (await reviewsFor(worktree)).filter((r) => kindOf(r) === "explainer" &&
-                    r.binding.name === scope &&
-                    r.status !== "accepted" &&
-                    r.status !== "closed");
-            if (match.length) {
-                review = match[0];
-                reused = true;
-                review.pins = { base: commit, head: commit };
-                await writeReview(review);
-            }
-            else {
-                const id = newId();
-                review = {
-                    schema: SCHEMA,
-                    id,
-                    kind: "explainer",
-                    title: str(p, "title") || defaultTitle,
-                    worktree,
-                    repoRoot: worktree,
-                    binding,
-                    pins: { base: commit, head: commit },
-                    status: "draft",
-                    revision: 0,
-                    dismissed: false,
-                    createdAt: now(),
-                    updatedAt: now(),
-                };
-                await mkdir(reviewDir(id), { recursive: true });
-                await writeText(join(reviewDir(id), "review.md"), TEMPLATE_EXPLAIN_MD(review.title));
-                await writeText(join(reviewDir(id), "data.yaml"), TEMPLATE_EXPLAIN_DATA);
-                await writeText(join(reviewDir(id), "map.yaml"), TEMPLATE_EXPLAIN_MAP);
-                await writeText(join(reviewDir(id), "theme.yaml"), TEMPLATE_THEME);
-                await writeReview(review);
-            }
-        }
+        const pinned = await pinOneCommit(p, EXPLAINER);
+        const { review, scope, commit, worktree } = pinned;
         const dir = reviewDir(review.id);
         return {
             explainer: {
@@ -812,7 +895,7 @@ const commands = {
                 scope,
                 commit,
                 worktree,
-                reused,
+                reused: pinned.reused,
                 dir,
             },
             files: {
@@ -821,7 +904,7 @@ const commands = {
                 map: join(dir, "map.yaml"),
                 theme: join(dir, "theme.yaml"),
             },
-            scale: { filesInScope: inScope.length },
+            scale: { filesInScope: pinned.inScope.length },
             guidance: await guidanceFiles(worktree),
             help: [
                 `Run \`thurview graph architecture --review ${short(review.id)}\` for the clusters, their hubs and the links between them`,
@@ -830,6 +913,40 @@ const commands = {
             ],
         };
     },
+    async design(args) {
+        const p = parseFlags("design", args, spec("design").flags, 1);
+        const pinned = await pinOneCommit(p, DESIGN);
+        const { review, scope, commit, worktree } = pinned;
+        const dir = reviewDir(review.id);
+        return {
+            design: {
+                id: short(review.id),
+                uuid: review.id,
+                kind: "design",
+                title: review.title,
+                status: review.status,
+                rev: review.revision,
+                scope,
+                commit,
+                worktree,
+                reused: pinned.reused,
+                dir,
+            },
+            files: {
+                document: join(dir, "review.md"),
+                data: join(dir, "data.yaml"),
+                map: join(dir, "map.yaml"),
+                theme: join(dir, "theme.yaml"),
+            },
+            scale: { filesInScope: pinned.inScope.length },
+            guidance: await guidanceFiles(worktree),
+            help: [
+                `Run \`thurview graph architecture --review ${short(review.id)}\` for the structure the design has to fit`,
+                `Declare in ${join(dir, "data.yaml")} what the design would add, change or remove, each anchored to the code it lands in today`,
+                `Edit ${join(dir, "review.md")}, then run \`thurview publish --review ${short(review.id)}\``,
+            ],
+        };
+    },
     async info(args) {
         const p = parseFlags("info", args, spec("info").flags);
         const fields = new Set((str(p, "fields") ?? "").split(",").filter(Boolean));
@@ -1003,7 +1120,7 @@ const commands = {
         if (review.binding.kind === "codebase") {
             const tip = await g.revParse(review.worktree, "HEAD").catch(() => null);
             if (tip && tip !== review.pins.head)
-                warnings.push(`HEAD has moved past the pinned commit; run \`thurview explain --update --review ${short(review.id)}\` to re-pin`);
+                warnings.push(`HEAD has moved past the pinned commit; run \`${repinCommand(kind)} --update --review ${short(review.id)}\` to re-pin`);
         }
         if (review.binding.kind === "branch") {
             const tip = await g.revParse(review.worktree, review.binding.name).catch(() => null);
@@ -1058,7 +1175,9 @@ const commands = {
                 map: !!map,
                 ...(kind === "explainer"
                     ? { coverage: coverage ? coverage.verdict : "(unavailable)" }
-                    : { interfaces: doc.document.interfaces?.verdict ?? "(unavailable)" }),
+                    : kind === "design"
+                        ? { proposes: doc.document.interfaces?.verdict ?? "(unavailable)" }
+                        : { interfaces: doc.document.interfaces?.verdict ?? "(unavailable)" }),
                 theme: theme?.name ?? "default",
                 url: url ?? "(server not running)",
             },
@@ -1263,8 +1382,8 @@ const commands = {
         }
         // A next step has to name the same commits, or it answers about another change.
         const again = review ? "" : ` --base ${short(t.pins.base)} --head ${short(t.pins.head)}`;
-        if (review && kindOf(review) === "explainer" && (sub === "interfaces" || sub === "impact"))
-            throw new AxiError(`graph ${sub} compares two commits; an explainer is pinned to one`, "VALIDATION_ERROR", [
+        if (review && kindOf(review) !== "review" && (sub === "interfaces" || sub === "impact"))
+            throw new AxiError(`graph ${sub} compares two commits; ${kindOf(review) === "design" ? "a design" : "an explainer"} is pinned to one`, "VALIDATION_ERROR", [
                 `Run \`thurview graph architecture --review ${short(review.id)}\` for the structure at that commit`,
                 `Run \`thurview graph callers <name> --review ${short(review.id)}\` to follow one symbol`,
             ]);
@@ -1337,9 +1456,11 @@ const commands = {
                 ],
             };
         }
-        // An explainer is scoped to a path, so its structure is that path's, not the
-        // repository's: the same bound the Coverage tab accounts for.
-        if (review && kindOf(review) === "explainer") {
+        // An explainer and a design are both scoped to a path and pinned to one
+        // commit, so the structure they get back is that path's, not the
+        // repository's: for an explainer, the same bound the Coverage tab accounts
+        // for; for a design, the structure it has to fit.
+        if (review && kindOf(review) !== "review") {
             const scope = review.binding.name;
             const g0 = scopeGraph(head, scope);
             const allFiles = await g.listFiles(t.worktree, t.pins.head);
@@ -1885,7 +2006,7 @@ const commands = {
             return {
                 skill: installed,
                 help: [
-                    "Invoke them as /thurview and /review-fix in Claude Code, or by name in other agents",
+                    `Invoke them as ${names.map((n) => `/${n}`).join(", ")} in Claude Code, or by name in other agents`,
                     "Run `thurview setup hooks` for ambient context at session start",
                 ],
             };