visualproof 0.2.0 → 0.4.0

package/dist/server/agent.js

@@ -29,11 +29,15 @@
 import { historyEndpoints, historyWorld } from "./historyapi.js";
 import { PastBuilds } from "./pastdoc.js";
 import { spawnSync } from "node:child_process";
+import { packageVersion } from "./version.js";
+import { withoutReasons } from "../shared/timeline.js";
+import { childEnv } from "./children.js";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { gunzipSync } from "node:zlib";
 import { ACTIVITY_KINDS, ACTIVITY_WHO, cleanView, MAX_PINNED, SCHEMES, validName } from "../shared/collab.js";
 import { addressOf, readRegion, showing, writeSnapshot } from "../shared/sharesnap.js";
+import { encodeRecipe, readRecipe, RECIPE_PARAM, resolveRecipe, SAVE_PARAM } from "../shared/artrecipe.js";
 import { contextText, exactContext, readContext } from "../shared/context.js";
 import { compiledExcerpt, excerptOf } from "../shared/excerpt.js";
 import { tokenizeLean } from "../shared/lexer.js";
@@ -56,6 +60,7 @@ import { inTargets, nonStandardAxiom, offBoard, reviewQueue, TCB_SITES, whyChain
 import { reviewThen } from "../shared/pastgraph.js";
 import { contextAt, namespacesOf } from "../shared/scope.js";
 import { PLACES, search, SearchIndex, snippet } from "../shared/search.js";
+import { foldedAt, guessNames } from "../shared/declfind.js";
 import { fullWhen } from "../shared/titles.js";
 import { ALL_SITES, Graph } from "../shared/viewgraph.js";
 import { layoutKey, wholeLayout } from "../shared/board.js";
@@ -172,9 +177,6 @@ const PARTS = ["source", "context", "uses", "users", "describe", "print"];
 const WHERE = { statement: SITE_STMT, body: SITE_BODY, proof: SITE_PROOF, grammar: SITE_GRAMMAR };
 /** what a trusted standard axiom is trusted by */
 const STANDARD = "standard axiom";
-/** the last components of names Lean generates beside a declaration (extractor/Extract.lean,
- *  `generatedSuffixes`, and the like) */
-const GENERATED_LAST = /^(?:rec|recOn|casesOn|noConfusion|noConfusionType|ctorElim|ctorElimType|below|brecOn|binductionOn|ibelow|ctorIdx|toCtorIdx|ofNat|ofNat_ctorIdx|sizeOf_spec|injEq|inj|eq_def|induct|mutual_induct|fun_cases|induct_unfolding|ext_iff|congr_simp|mk|elim|(?:eq|match|proof)_\d+|_.*)$/;
 /** The graph on show, as the API reads it: built from the server's prepared view once per
  *  version. The page's review route reads it too (server/reviewapi.ts). */
 export class View {
@@ -372,41 +374,9 @@ export class AgentApi {
             this.view = new View(g.version, g.prep.metaGz, g.prep.edgesGz);
         return this.view;
     }
-    /** Up to five names like `name`: the same name in another case; then the same last component,
-     *  or one a typo or two away, in the same namespace first; then what the search finds. */
+    /** Up to five names like `name` (shared/declfind.ts, `guessNames`). */
     guess(v, name) {
-        const g = v.g;
-        const dot = name.lastIndexOf(".");
-        const last = name.slice(dot + 1).toLowerCase();
-        const ns = dot < 0 ? "" : name.slice(0, dot);
-        const scored = new Map();
-        const offer = (n, score) => {
-            if ((scored.get(n) ?? Infinity) > score)
-                scored.set(n, score);
-        };
-        const lower = name.toLowerCase();
-        const most = last.length < 5 ? 1 : 2;
-        // the graph's declarations, and the names Lean generated from a command that they fold
-        for (const name of [...g.nodes.map((n) => n.name), ...g.foldedInto.keys()]) {
-            if (name.toLowerCase() === lower)
-                offer(name, -1);
-            const k = name.lastIndexOf(".");
-            const d = editDistance(name.slice(k + 1).toLowerCase(), last, most);
-            if (d <= most)
-                offer(name, 2 * d + (name.slice(0, Math.max(0, k)) === ns ? 0 : 1));
-        }
-        let rank = 0;
-        for (const q of [name.slice(dot + 1), name.replace(/\./g, " ")]) {
-            if (q.trim().length < 2)
-                continue;
-            const f = search(v.index, q);
-            for (const h of [...f.hits.name, ...f.hits.statement].slice(0, 10))
-                offer(g.nodes[h.i].name, 10 + rank++);
-        }
-        return [...scored]
-            .sort((a, b) => a[1] - b[1] || a[0].length - b[0].length || (a[0] < b[0] ? -1 : 1))
-            .slice(0, 5)
-            .map(([n]) => n);
+        return guessNames(v.g, v.index, name);
     }
     /** A declaration by its full name, or the answer that there is none (with what was meant). A
      *  name the graph folds into a declaration is that declaration (`folded` says so). */
@@ -419,35 +389,10 @@ export class AgentApi {
         const guesses = this.guess(v, name.trim());
         return fail(404, `There is no declaration ${name} in the graph.`, guesses.length ? `Did you mean ${guesses[0]}? Names are full, as the search gives them.` : "Search for it: GET /api/agent/search?q=<words>.", { didYouMean: guesses });
     }
-    /** The declaration a name the graph has no node for is folded into: a declaration Lean generated
-     *  from a command (ViewNode.also), or a constructor, recursor, field, equation lemma… of a
-     *  declaration or of one so generated, which is a name one component below it. A name one
-     *  component below a declaration that is a typo or two away from a declaration beside it is
-     *  taken for that typo, not for something folded, unless its last component is one Lean
-     *  generates. */
+    /** The declaration a name the graph has no node for is folded into (shared/declfind.ts,
+     *  `foldedAt`). */
     foldedAt(v, name) {
-        const g = v.g;
-        const direct = g.foldedInto.get(name);
-        if (direct !== undefined)
-            return direct;
-        const dot = name.lastIndexOf(".");
-        if (dot <= 0)
-            return undefined;
-        const head = name.slice(0, dot), last = name.slice(dot + 1);
-        const at = g.byName.get(head) ?? g.foldedInto.get(head);
-        if (at === undefined || !last)
-            return undefined;
-        if (!GENERATED_LAST.test(last)) {
-            const most = last.length < 5 ? 1 : 2;
-            const near = (n) => n.length > head.length + 1 && n.startsWith(head + ".") && !n.includes(".", head.length + 1) && editDistance(n.slice(head.length + 1).toLowerCase(), last.toLowerCase(), most) <= most;
-            for (const n of g.nodes)
-                if (near(n.name))
-                    return undefined;
-            for (const n of g.foldedInto.keys())
-                if (near(n))
-                    return undefined;
-        }
-        return at;
+        return foldedAt(v.g, name);
     }
     /** What an answer about `asked` says when that name is folded into declaration `i`. */
     folded(v, asked, i) {
@@ -514,8 +459,10 @@ export class AgentApi {
         return {
             by: o.by,
             agent: !!o.agent,
-            // someone invited by a personal link: the name is theirs (CollabSpec decision 9)
-            ...(o.person ? { verified: true } : {}),
+            // someone invited by a personal link: the name is theirs (CollabSpec decision 9), unless
+            // someone else recorded it for them at the same screen, who is named (ReviewSpec decision 8)
+            ...(o.person && !o.recordedBy ? { verified: true } : {}),
+            ...(o.recordedBy ? { recordedBy: o.recordedBy.by } : {}),
             verdict: o.verdict,
             ...(o.comment ? { comment: o.comment } : {}),
             at: o.at,
@@ -873,7 +820,7 @@ export class AgentApi {
         const advise = !this.refuse(me, "advise");
         const byKey = new Map(this.endpoints.map((e) => [`${e.method} ${e.path}`, e]));
         return ok({
-            about: "VisualProof shows a Lean project's declarations, the TCB of its theorems (what a theorem's statement rests on) and the review people make of it. This is its API for AI agents.",
+            about: `VisualProof ${packageVersion()} shows a Lean project's declarations, the TCB of its theorems (what a theorem's statement rests on) and the review people make of it. This is its API for AI agents.`,
             you: {
                 name: me.name,
                 kind: me.kind,
@@ -1216,7 +1163,9 @@ export class AgentApi {
         if (typeof t !== "string")
             return t;
         try {
-            return { status: 200, body: null, text: { type: "text/javascript; charset=utf-8", body: readFileSync(MCP_FILE, "utf8") } };
+            // the file carries the version of the server it came from (UpdateSpec decision 11)
+            const body = readFileSync(MCP_FILE, "utf8").replace(/^const VERSION = "[^"\n]*";$/m, `const VERSION = ${JSON.stringify(packageVersion())};`);
+            return { status: 200, body: null, text: { type: "text/javascript; charset=utf-8", body } };
         }
         catch {
             return fail(404, "The MCP server is not beside this server.", "Use the HTTP API (GET /api/agent).");
@@ -2046,7 +1995,7 @@ export class AgentApi {
         // what the review's logs record, as the page reads it
         for (const [name, ops] of Object.entries(d.opinions))
             for (const o of ops)
-                out.push({ at: o.at, kind: "opinion", by: o.by, agent: !!o.agent, name, verdict: o.verdict, ...(o.comment ? { comment: o.comment } : {}) });
+                out.push({ at: o.at, kind: "opinion", by: o.by, ...(o.recordedBy ? { recordedBy: o.recordedBy.by } : {}), agent: !!o.agent, name, verdict: o.verdict, ...(o.comment ? { comment: o.comment } : {}) });
         // what an agent did at level full is marked as an agent's, as its advice is
         for (const [name, t] of Object.entries(d.targets))
             out.push({ at: t.at, kind: "target", by: t.by, agent: !!t.agent, name });
@@ -2077,7 +2026,7 @@ export class AgentApi {
                 out.push({ ...rest, ...who, moved: ops.flatMap((o) => (o.op === "clear" ? [] : [o.key])).slice(0, 100), undoneBy: undone.get(e.id) ?? null });
             }
             else
-                out.push({ ...e, ...who });
+                out.push({ ...withoutReasons(e), ...who });
         }
         const about = (a.query.get("name") ?? "").trim();
         // a note is about the declarations it names; a link, about the declaration it is on, or was on
@@ -2228,6 +2177,10 @@ export class AgentApi {
             unit = v.g.nodes[i].name;
         }
         const verdict = b.verdict;
+        // an agent's advice is its own: people record for one another at one screen, agents never
+        // (ReviewSpec decision 8)
+        if (b.for !== undefined)
+            return fail(403, "An agent records no opinion for anyone else.", "Leave out for: your advice is your own.");
         // "dispute" was the old name of a comment (renamed 2026-10-09): refused, with the new name
         if (verdict === "dispute")
             return fail(400, "verdict is approve or comment: \"dispute\" is now \"comment\".", "Use comment: send {name, verdict: \"comment\", comment}.");
@@ -2528,6 +2481,66 @@ export class AgentApi {
         }
         return { place: cleanView(next), temporary };
     }
+    /** A link to a picture of the board (ExportSpec decision 20, drafted 2026-10-15): a recipe
+     *  (shared/artrecipe.ts) checked, and resolved against the board of the view it names — the
+     *  Project's layout in the view's clustering — so that a name, a target or a cluster the board has
+     *  not is refused here rather than drawn as a picture unlike the one meant; the selection it gives
+     *  goes in the address, the recipe after it. The page that opens the link resolves it again
+     *  against the board it opens on, opens the artwork mode, and saves the files asked for. Nothing
+     *  changes here, and the link holds no key. */
+    async artwork(a) {
+        const no = needAgent(a.caller);
+        if (no)
+            return no;
+        const b = body(a);
+        const read = readRecipe(b.recipe);
+        if ("error" in read)
+            return fail(400, read.error, read.hint);
+        const r = read.recipe;
+        const save = b.save === undefined || b.save === null ? [] : typeof b.save === "string" ? b.save.split(",").map((k) => k.trim()) : null;
+        if (!save || save.some((k) => k !== "png" && k !== "svg"))
+            return fail(400, "save is png, svg or png,svg.", "The files the page saves once the board is ready; left out, none.");
+        const v = this.graph();
+        if (!(v instanceof View))
+            return v;
+        let sel = null;
+        if (r.selection) {
+            const i = this.find(v, r.selection.name, "selection.name");
+            if (typeof i !== "number")
+                return i;
+            sel = v.g.nodes[i].name;
+        }
+        const rec = r.view && r.view !== PROJECT ? this.world.views?.book.get(r.view) : undefined;
+        if (r.view && r.view !== PROJECT && !rec)
+            return fail(404, `There is no view ${r.view}.`, "GET /api/agent/views lists them; left out, the Project.");
+        const L = v.meta.layouts[rec?.clustering ?? "namespace"];
+        const res = resolveRecipe(r, {
+            clusters: L.clusters,
+            clusterOf: (name) => {
+                const i = v.g.byName.get(name);
+                return i === undefined ? undefined : L.cluster[i];
+            },
+            targets: Object.keys(this.world.review.data.targets),
+            projectCount: v.meta.projectCount,
+        });
+        if (res.problems.length)
+            return fail(404, `The recipe names what the board has not: ${res.problems.join("; ")}.`, "Clusters by key (GET /api/agent/views/view lists a view's), declarations and targets by full name (GET /api/agent/search; the targets: GET /api/agent/targets). A target of the review the graph no longer has is left out unsaid where the recipe does not name it.", { problems: res.problems });
+        const address = addressOf({ view: rec ? rec.id : null, scope: null, mode: r.selection?.mode ?? "tcb", selection: null, sel });
+        const link = `${a.base ?? ""}/#${address}&${RECIPE_PARAM}=${encodeRecipe(r)}${save.length ? `&${SAVE_PARAM}=${[...new Set(save)].join(",")}` : ""}`;
+        const look = res.look;
+        return ok({
+            ok: true,
+            link,
+            length: link.length,
+            size: [look.w, look.h],
+            names: look.labels === "chosen" ? res.named : look.labels,
+            targets: look.targets === "chosen" ? look.shownTargets : look.targets,
+            selection: sel ? { name: sel, mode: r.selection.mode ?? "tcb" } : null,
+            // names and targets beyond what the artwork carries, left out: said, not refused
+            left: res.left,
+            note: "It holds no key: it opens for whoever is let in already, or for a script that enters with the key (scripts/artwork-batch.mjs). The page that opens it resolves the recipe again against its board, opens the artwork mode fitted to the whole board, and saves the files asked for on that machine; nothing comes back here.",
+        });
+    }
     /** A link to what the agent looks at, or to a place it gives over its own, as a person's Share makes
      *  one with Exactly what I see (CollabSpec decision 7, the owner's decision of 2026-10-12): the
      *  address, and after it a snapshot of everything followed, which the page that opens it applies
@@ -2887,7 +2900,7 @@ export class AgentApi {
             {
                 method: "GET", path: "/api/agent/activity", brief: "the timeline", about: "The timeline, oldest first: opinions and advice, targets and key marks, files of the library added, retitled, archived or restored and links made, edited or removed (all from the review's logs), builds, TCB changes, targets taken off, prefixes trusted or no longer, views saved, renamed, rescoped, deleted or laid out afresh, notes added to a view or taken out of it, notes, layouts and their undoing.",
                 params: { since: "an ISO time (e.g. the `now` of your last answer) or an event id: what came after", name: "optional: only what is about this declaration (opinions, advice, notes that name it, key marks, links on it; a target's own events)", limit: "default 100, at most 1000 (the newest)" },
-                returns: "{now, events: [{at, kind, by?, agent?, …}] oldest first, more}; kinds: opinion, target, key (a key declaration as marked now: target, name), build, tcb, untarget, trust, untrust, view (a view saved, renamed, rescoped, deleted or laid out afresh: what, view, name, was?, scope; or a note of the project added to it or taken out of it: what items, note, text, shown), note (a note on a view written, edited or deleted: what, view, title, note, text), file (a file of the library: what is added, edited — its title, wasTitle the one before —, archived or restored; sha, title), link (what is made, edited or removed; id, subject, label, file, and an edit's changed (subject, label, place), wasSubject?, wasLabel?, auto? where VisualProof carried it with a renamed cluster), layout (with moved and undoneBy), undo; relayout only in a timeline kept from before views",
+                returns: "{now, events: [{at, kind, by?, agent?, …}] oldest first, more}; kinds: opinion, target, key (a key declaration as marked now: target, name), build, tcb, untarget, trust, untrust, view (a view saved, renamed, rescoped, deleted or laid out afresh: what, view, name, was?, scope; or a note of the project added to it or taken out of it: what items, note, text, shown), note (a note on a view written, edited or deleted: what, view, title, note, text), file (a file of the library: what is added, edited — its title, wasTitle the one before —, archived or restored; sha, title), link (what is made, edited or removed; id, subject, label, file, and an edit's changed (subject, label, place), wasSubject?, wasLabel?, auto? where VisualProof carried it with a renamed cluster), layout (with moved and undoneBy), undo, tool (the VisualProof version serving the site changed: from, to, setAside?); relayout only in a timeline kept from before views",
                 run: (a) => this.activity(a),
             },
             {
@@ -2920,6 +2933,12 @@ export class AgentApi {
                 returns: "{ok, link, exact, carries: what the link opens on, length, note, temporary?}",
                 run: (a) => this.viewLink(a),
             },
+            {
+                method: "POST", path: "/api/agent/artwork", about: "A link that opens the board as a picture, in the artwork mode, as the recipe says (ExportSpec decision 20): its size, its look, names by a rule, the targets marked, the selection — in words that hold on any project, so that one recipe makes the same kind of picture of every codebase; the page saves the PNG or SVG where asked, once the board is ready. It changes nothing, and holds no key. A name, a target or a cluster the board has not is refused (404, problems).",
+                params: { recipe: "the picture: {size, orientation, style, theme, transparent, colouring, border, title, subtitle, titleSize, footSize, source, names, targets, keys, notes, edges, selection, lit, view}, each optional (GET /api/agent/docs/export, \"Artwork\")", save: "png, svg or png,svg: the files the page saves once the board is ready; left out, none" },
+                returns: "{ok, link, length, size: [w, h], names: {clusters, decls: written wherever they fall; ruled: by the rule, each only where it covers no other name} | how the board writes them, targets, selection, left: names and targets left out for room, note}",
+                run: (a) => this.artwork(a),
+            },
             {
                 method: "POST", path: "/api/agent/pins", needs: "full", about: "Drop or let go of pins on the Project view, as people drag (for another view: POST /api/agent/views/arrange): one batch, recorded in the timeline with what it replaced, undoable at once.",
                 params: { mode: "namespace (default) or module", pins: `[{name or cluster, at: [x, y] in the parent's coordinates (GET /api/agent/place), or null to let go}], at most ${MAX_PINS}` },
@@ -3174,6 +3193,8 @@ export function doingOf(a) {
             return of("going to", clip(b.sel)) ?? of("going to the view of", clip(b.review)) ?? "moving its view";
         case "/api/agent/view/link":
             return "making a link to what it looks at";
+        case "/api/agent/artwork":
+            return "making a link to a picture of the board";
         case "/api/agent/ask-follow":
             return clip(b.who) ? `asking ${clip(b.who)} to follow it` : "asking everyone to follow it";
         case "/api/agent/opinion":
@@ -3226,24 +3247,6 @@ const str = (x) => (typeof x === "string" ? x : null);
 export function whoOf(c) {
     return { name: c.name ?? "", ...(c.token ? { token: c.token.id } : {}) };
 }
-/** The edit distance between two short strings, or `most + 1` once it is more than `most`. */
-function editDistance(a, b, most) {
-    if (Math.abs(a.length - b.length) > most)
-        return most + 1;
-    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
-    for (let i = 1; i <= a.length; i++) {
-        const row = [i];
-        let best = i;
-        for (let j = 1; j <= b.length; j++) {
-            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
-            best = Math.min(best, row[j]);
-        }
-        if (best > most)
-            return most + 1;
-        prev = row;
-    }
-    return Math.min(prev[b.length], most + 1);
-}
 /** An integer parameter within bounds, `dflt` when absent or not a number. */
 function clampInt(s, dflt, lo, hi) {
     const n = s === null || s.trim() === "" ? NaN : Number(s);
@@ -3258,7 +3261,7 @@ export function commitOf(root) {
     if (was && now - was.at < 10_000)
         return was.commit;
     const git = (...args) => {
-        const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 5000, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" }, stdio: ["ignore", "pipe", "ignore"] });
+        const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 5000, env: childEnv({ GIT_OPTIONAL_LOCKS: "0" }), stdio: ["ignore", "pipe", "ignore"] });
         return r.status === 0 ? r.stdout.trim() : null;
     };
     const hash = git("rev-parse", "HEAD");

package/dist/server/agentdocs.js

@@ -16,7 +16,7 @@ export const DOC_TOPICS = [
     { topic: "following", title: "Following", about: "where people are, your view, links to it, what people see" },
     { topic: "views", title: "Views and the layout", about: "queries, views, places, pins" },
     { topic: "library", title: "The library and links", about: "papers and images, their pages, links to them" },
-    { topic: "export", title: "Exported documents", about: "a view's document, typeset" },
+    { topic: "export", title: "Exported documents", about: "a view's document, typeset; a picture" },
     { topic: "history", title: "History and activity", about: "the timeline, builds, renames, the lost-and-found" },
     { topic: "talking", title: "Talking with people", about: "your inbox, replies, your state" },
     { topic: "mcp", title: "VisualProof's MCP server", about: "installing it, its tools and their actions" },