toolroll 0.9.104 → 0.9.105

package/dist/flow-gallery.js

@@ -1,20 +1,3 @@
-/**
- * The flow gallery: ready-made flows grouped by what they're for (Ship code, Keep it healthy, Hear from users,
- * Operations). Each says in one line what it promises, what it needs, and asks only what it must (a project,
- * a label, a schedule, a branch, a test command). A preview says in plain words what it will do and never do;
- * using one makes an ordinary flow (its zones), its triggers and any script it runs, together or not at all.
- *
- * A template is data — steps in the lead's vocabulary, trigger settings and scripts, with `{{ask.<key>}}`
- * where an answer goes and `{{script.<name>}}` where its script's name goes — so it can be written out as a
- * shared flow file later. Every one is built only from existing zone and trigger kinds, and none merges:
- * a pull request it opens waits for a person.
- *
- * A template that puts a connected tool to work names it (`tools`): a one-click service (ONE_CLICK) or the Figma
- * desktop app. Its research steps read that tool and only read; a build gets the project's tools as any build does.
- *
- * Every template without its own send zone can end with "Send me the result" (a "Send to me" zone before its end),
- * off unless asked for (`send-result: yes`): what the flow did reaches the person in their chat apps.
- */
 import { createHash } from "node:crypto";
 import { scanForSecrets } from "./evidence.js";
 import { flowDefinitionOf } from "./flow-engine.js";
@@ -30,13 +13,11 @@ export const GALLERY_GROUPS = [
     { id: "users", label: "Hear from users" },
     { id: "ops", label: "Operations" },
 ];
-/** Weekly upkeep's package managers: what each runs. A script that fails (exits non-zero) when something is out of date. */
 export const OUTDATED_COMMANDS = {
     npm: { label: "npm (npm outdated)", command: "npm outdated" },
     pip: { label: "pip (pip list --outdated)", command: "out=\"$(python3 -m pip list --outdated 2>/dev/null | tail -n +3)\"\nif [ -n \"$out\" ]; then echo \"$out\"; exit 1; fi" },
     cargo: { label: "cargo (cargo outdated)", command: "cargo outdated --root-deps-only --exit-code 1" },
 };
-/** The card's Linear issue key, read from its source as the Linear trigger stored it ("Linear ENG-123"); "none" skips the comment. */
 export const LINEAR_KEY = `key="$(sed -n 's/.*"source":{"kind":"linear","label":"Linear \\([A-Z][A-Z0-9]*-[0-9][0-9]*\\)".*/\\1/p' | head -n 1)"
 if [ -n "$key" ]; then echo "$key"; echo "goto: Found"; else echo none; echo "goto: None"; fi`;
 const NEVER_MERGES = "Never merges. Each pull request waits for you.";
@@ -50,10 +31,8 @@ const SORTS = "OpenRouter (Jev sorts)";
 const WEEKLY = { key: "schedule", default: "monday 09:00", label: "When", hint: "Like “monday 09:00”." };
 const weekly = (title) => ({ kind: "schedule", schedule: "{{ask.schedule}}", title });
 const send = (title) => ({ id: "send", title, kind: "send" });
-/** A person's choice: build it, or end there. A reply goes to the build as its note. */
 const choose = (title, yes, build) => ({ id: "choose", title, kind: "choose", options: [{ label: yes, goesTo: build }, { label: "Ignore", goesTo: "end" }], ifReplied: build });
 export const GALLERY = [
-    // ---------------------------------------------------------------- Ship code
     {
         id: "overnight-bug-bash", name: "Overnight bug bash", group: "ship",
         promise: "Bugs filed during the day are fixed overnight; the results wait for you in the morning.",
@@ -181,7 +160,6 @@ export const GALLERY = [
         id: "linear-to-prs", name: "Linear issues to PRs", group: "ship", tools: ["linear"],
         promise: "Labelled Linear issues are built, and the issue gets the pull request link.",
         needs: ["GitHub", "A Linear API key"], asks: [{ key: "team", default: "ENG", label: "Linear team", hint: "Its short key, like ENG." }, { key: "label", default: ISSUE_LABEL, label: "Issue label" }],
-        // The issue's key comes from the card's source ("Linear ENG-123"), as the trigger stored it, never from a model.
         scripts: [{ name: "linear-issue-key", about: "Prints the Linear issue the card came from, or none.", body: LINEAR_KEY, timeoutMinutes: 1 }],
         steps: [
             { id: "build", title: "Build it", kind: "task", instructions: work("Build this issue: {{card.title}}\n\n{{card.description}}") },
@@ -193,7 +171,6 @@ export const GALLERY = [
         does: ["Watches {{ask.team}} issues labelled “{{ask.label}}” in Linear.", "Builds each one as a task, under your usual approvals, and opens a pull request.", "Comments the pull request link on the issue, through Linear."],
         never: NEVER_MERGES,
     },
-    // ---------------------------------------------------------- Keep it healthy
     {
         id: "fix-ci", name: "Fix failing CI", group: "health",
         promise: "When CI fails on your main branch, a fix is built and opened for review.",
@@ -267,7 +244,6 @@ export const GALLERY = [
         never: NEVER_MERGES,
     },
     {
-        // v126: the direct road from a signed outside request to a build that waits for your approval.
         id: "webhook-to-build", name: "Webhook to build", group: "health",
         promise: "A signed request from any tool becomes a build, under your usual approvals.",
         needs: ["A tool that can send signed webhooks", "GitHub"], asks: [],
@@ -300,7 +276,6 @@ export const GALLERY = [
             { id: "done", title: "Done", kind: "done" },
             { id: "ignored", title: "Ignored", kind: "done" },
         ],
-        // v126: signed by Sentry and read by Toolroll's Sentry reader: one card per issue, linked to it.
         triggers: [{ kind: "webhook", sender: "sentry", title: "Error" }],
         does: ["Adds a Sentry webhook. Once the flow is made, open its Triggers and choose New address; in Sentry create an Internal Integration (Settings → Developer Settings), paste that address as its Webhook URL, turn on Alert Rule Action and Issue events, then paste its Client Secret under Signing on the flow's Triggers.", "One card per Sentry issue, however often it alerts, linked to the issue.", "Jev keeps errors in your code that are new or frequent, and drops noise; ones it isn't sure about wait for you.",
             "Each kept error is researched, then fixed as a task, under your usual approvals.", "What you approve opens a pull request."],
@@ -352,12 +327,10 @@ export const GALLERY = [
             pr,
             send("Send the fix"),
         ],
-        // v126: signed by Vercel and read by Toolroll's Vercel reader: failed deployments only, one card each.
         triggers: [{ kind: "webhook", sender: "vercel", title: "Failed deployment" }],
         does: ["Adds a Vercel webhook. Once the flow is made, open its Triggers and choose New address; in Vercel (Settings → Webhooks) paste that address and choose Deployment Error, then paste the secret Vercel shows under Signing on the flow's Triggers. Put your Vercel project ID in Signing too, so only its deployments add cards.", "Reads the build log and finds the cause.", "Builds a fix as a task, under your usual approvals, opens a pull request and sends it to you."],
         never: NEVER_MERGES,
     },
-    // ---------------------------------------------------------- Hear from users
     {
         id: "feedback-to-feature", name: "Feedback to feature", group: "users",
         promise: "Feedback is sorted into bugs, ideas and questions; ideas get a short spec for you to decide.",
@@ -431,7 +404,6 @@ export const GALLERY = [
         does: ["Reads your Intercom conversations {{ask.schedule-words}} and ranks the bug reports by how many people hit each.", "You fix the top one, reply with the number of another, or ignore them.", "The fix is built as a task, under your usual approvals, opens a pull request and is sent to you."],
         never: NEVER_MERGES,
     },
-    // ------------------------------------------------------------------ Operations
     ...[
         ["research", "Research a question, have a person check it, then share it.", [], "Never shares an answer you haven't checked."],
         ["spam-filter", "Jev screens what a public form or webhook brings in.", [SORTS], "Never deletes anything; filtered cards are kept."],
@@ -444,12 +416,9 @@ export const GALLERY = [
         id, name: FLOW_TEMPLATES.find(one => one.id === id).label, group: "ops", promise, needs: [...needs], asks: [], definition: drawn(id), triggers: [], does: [about(id)], never,
     })),
 ];
-/** The blank flow, for starting from nothing. */
 export const BLANK = { id: "blank", name: "Blank flow", group: "ops", promise: about("blank"), needs: [], asks: [], definition: drawn("blank"), triggers: [], does: [about("blank")], never: "Does nothing until you add zones." };
 export const galleryTemplateOf = (id) => id === BLANK.id ? BLANK : GALLERY.find(one => one.id === id) ?? null;
-/** A tool's name ("Mobbin", "Figma (desktop app)"); null for an id that's neither a one-click service nor an app on this computer. */
 export const galleryToolLabel = (id) => oneClickOf(id)?.label ?? localConnectOf(id)?.label ?? null;
-/** The zones that use a tool: a tool step on it, or a research or build step that names it ("With Mobbin, …"). */
 export function zonesUsing(definition, id) {
     const label = galleryToolLabel(id);
     if (label === null)
@@ -457,11 +426,9 @@ export function zonesUsing(definition, id) {
     const word = new RegExp(`\\b${label.replace(/\s*\(.*\)$/, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
     return definition.stages.filter(one => one.tool?.server === id || ((one.kind === "report" || one.kind === "task") && word.test(one.instructions ?? ""))).map(one => one.title);
 }
-/** A template's tools, each with its state in a project's connections (connectionsOf), or none without a project. */
 export function galleryToolsOf(template, definition, connections) {
     return (template.tools ?? []).map(id => ({ id, label: galleryToolLabel(id) ?? id, state: connections === null ? null : connections.find(one => one.id === id)?.state ?? "open", zones: zonesUsing(definition, id) }));
 }
-/** Each question's default for a project: the branch pull requests go to, when that's set up. */
 export function galleryDefaults(store, template, repo) {
     const publishing = repo === null ? { on: false } : publishingOf(store, repo);
     return Object.fromEntries(template.asks.map(ask => [ask.key, ask.key === "branch" && publishing.on ? publishing.base : ask.default]));
@@ -474,16 +441,11 @@ const oneLine = (value, cap, what) => {
         throw new Error(`That ${what} looks like it holds a key or password. Keep secrets out of it.`);
     return said;
 };
-/** The optional last step every template offers, and the answer that turns it on. */
 export const SEND_RESULT = { key: "send-result", title: "Send me the result", does: "When a card finishes, sends you what was done (its summary, links and screenshots) in your chat apps." };
-/** A template that already sends its result to the person: it isn't offered "Send me the result" again. */
 export const sendsAlready = (template) => galleryDiagram(template).stages.some(one => one.kind === "send");
-/** A flow with "Send me the result" before its end: every path into its main Done zone passes through it first.
- * A flow that already has a send zone is left as it is, so nobody gets the result twice. */
 export function withSendResult(definition) {
     if (definition.stages.some(one => one.kind === "send"))
         return definition;
-    // Its main end: Done, else an end that isn't a filtered-out one (drawn in rose), else any end.
     const ends = definition.stages.filter(one => one.kind === "done");
     const end = ends.find(one => one.id === "done") ?? ends.find(one => one.zone.color !== "rose") ?? ends[0];
     if (end === undefined)
@@ -499,16 +461,13 @@ export function withSendResult(definition) {
         ...(one.routes === undefined ? {} : { routes: one.routes.map(route => ({ ...route, to: into(route.to) })) }),
         ...(one.options === undefined || choiceTargets(one).length === 0 ? {} : { options: one.options.map(option => ({ ...option, to: into(option.to) })) }),
     }));
-    // Where the end was, and the end moves along to make room.
     const send = { id, title: SEND_RESULT.title, kind: "send", zone: { ...end.zone, color: "green", h: 220 }, instructions: null, planning: null, approver: null,
         message: null, close: null, script: null, sort: null, next: end.id, onFail: null };
     const moved = stages.map(one => one.id === end.id ? { ...one, zone: { ...one.zone, x: one.zone.x + Math.max(300, one.zone.w + 40) } } : one);
     return { ...definition, ...(definition.start === end.id ? { start: id } : {}), stages: [...moved.filter(one => one.id !== end.id), send, moved.find(one => one.id === end.id)] };
 }
-/** The answers, checked in plain words, with what they fill in. Throws. */
 export function checkAnswers(template, given) {
     const answers = {};
-    // Off unless asked for; only said when on, so a template's answers read as before.
     if (given[SEND_RESULT.key] === "yes")
         answers[SEND_RESULT.key] = "yes";
     for (const ask of template.asks) {
@@ -530,7 +489,6 @@ export function checkAnswers(template, given) {
             const said = oneLine(value, 80, "schedule");
             if (scheduleFromWords(said) === null)
                 throw new Error("Say when like “daily 02:00”, “weekdays 09:00” or “monday 09:00”.");
-            // Said without a time zone, it runs in this computer's, like the plane review.
             const zoned = /@/.test(scheduleFromWords(said)) || /^every \d/i.test(said) ? null : scheduleFromWords(`${said} ${localTimeZone()}`);
             answers["schedule"] = zoned === null ? said : `${said} ${localTimeZone()}`;
             answers["schedule-words"] = scheduleWords(said);
@@ -560,7 +518,6 @@ function localTimeZone() {
         return "UTC";
     }
 }
-/** "daily 02:00" as "every day at 02:00", the way a sentence says it. */
 function scheduleWords(said) {
     const daily = /^(?:every day|daily)(?: at)? (\d{1,2}:\d{2})/i.exec(said);
     if (daily !== null)
@@ -573,7 +530,6 @@ function scheduleWords(said) {
         return `every ${weekly[1].charAt(0).toUpperCase()}${weekly[1].slice(1).toLowerCase()} at ${weekly[2]}`;
     return said;
 }
-/** Fill `{{ask.<key>}}` and `{{script.<name>}}` through a template's data; the card's own fill-ins stay. */
 function fill(value, answers, scripts, github) {
     if (typeof value === "string")
         return value.replace(/\{\{(ask|script)\.([a-z-]+)\}\}|\{\{github\}\}/g, (whole, kind, key) => kind === undefined ? github ?? "your GitHub repository" : (kind === "ask" ? answers[key] : scripts[key]) ?? whole);
@@ -583,12 +539,10 @@ function fill(value, answers, scripts, github) {
         return Object.fromEntries(Object.entries(value).map(([key, one]) => [key, fill(one, answers, scripts, github)]));
     return value;
 }
-/** A template made concrete for a project and its answers: its zones, triggers and scripts, checked. Throws in plain words. */
 export function buildFromGallery(store, template, repo, given) {
     if (template.github === true && githubRepoOf(repo) === null)
         throw new Error("This project isn't on GitHub, so this can't watch it.");
     const answers = checkAnswers(template, given);
-    // A script keeps its name unless the project already has a different one by that name; then it gets a free one.
     const names = {};
     const scripts = (template.scripts ?? []).map(script => {
         const body = fill(script.body, answers, {}, null);
@@ -610,7 +564,6 @@ export function buildFromGallery(store, template, repo, given) {
     const github = githubRepoOf(repo);
     const drawn = template.definition !== undefined ? structuredClone(template.definition)
         : flowFromSteps(fill(template.ownSteps !== undefined && isToolrollRepo(repo) ? template.ownSteps : template.steps, answers, names, github), null);
-    // One that already sends doesn't take the answer, so it reads as it was asked.
     if (drawn.stages.some(one => one.kind === "send"))
         delete answers[SEND_RESULT.key];
     const sends = answers[SEND_RESULT.key] === "yes";
@@ -618,14 +571,12 @@ export function buildFromGallery(store, template, repo, given) {
     return { template, repo, answers, definition, triggers: fill(template.triggers, answers, names, github), scripts,
         does: [...fill(template.does, answers, names, github), ...(sends && definition !== drawn ? [SEND_RESULT.does] : [])], never: template.never };
 }
-/** A template's zones as its defaults draw them, for the gallery's small drawing; no project needed. */
 export function galleryDiagram(template) {
     if (template.definition !== undefined)
         return template.definition;
     const names = Object.fromEntries((template.scripts ?? []).map(one => [one.name, one.name]));
     return flowFromSteps(fill(template.steps, checkAnswers(template, {}), names, null), null);
 }
-/** What using a template will do, in words, before anything is made: its triggers checked as the flow will have them. Throws. */
 export function previewGallery(store, template, repo, given, actor, now) {
     const built = buildFromGallery(store, template, repo, given);
     const draft = { id: 0, repo, name: template.name, definitionJson: JSON.stringify(built.definition), revision: 1, state: "active", createdBy: actor, createdAt: now.toISOString(), updatedBy: actor, updatedAt: now.toISOString(), owner: actor };
@@ -635,12 +586,9 @@ export function previewGallery(store, template, repo, given, actor, now) {
         steps.push(...built.scripts.filter(one => !one.existing).map(one => `Adds the ${one.name} script to this project: ${one.body.split("\n")[0]}${one.body.includes("\n") ? " …" : ""}`));
     return { built, startsFrom, steps, tools: galleryToolsOf(template, built.definition, connectionsOf(store, repo)), digest: galleryDigest(template.id, repo, built.answers) };
 }
-/** What a preview showed: the template, the project and the answers. Creating checks the person saw these. */
 export function galleryDigest(id, repo, answers) {
     return createHash("sha256").update(JSON.stringify([id, repo, Object.entries(answers).sort(([a], [b]) => a.localeCompare(b))])).digest("hex").slice(0, 24);
 }
-/** Use a template in a project: its scripts, its flow and its triggers, together or not at all. */
-/** Whether a template's triggers bring in items from anyone: making it takes the person's password. */
 export function galleryAdmitsAnyone(template) {
     return template.triggers.some(one => rawAdmitsAnyone(one));
 }
@@ -659,7 +607,6 @@ export function useGalleryTemplate(store, template, repo, given, input) {
             const id = store.createFlow({ repo, name, definitionJson: JSON.stringify(built.definition), by: input.by }, input.now);
             const made = store.getFlow(id);
             for (const trigger of built.triggers) {
-                // No one is shown the gallery's addresses: a webhook is made with none until its panel makes one (v126).
                 const added = addFlowTriggerTo(store, made, { ...trigger, zone: trigger["zone"] ?? flowDefinitionOf(made).start }, input.by, input.now, input.dir, { shown: false, ...(input.widening === undefined ? {} : { widening: input.widening }) });
                 if (!added.ok)
                     throw new Error(added.message);
@@ -668,7 +615,6 @@ export function useGalleryTemplate(store, template, repo, given, input) {
             }
             return id;
         });
-        // A webhook's address is a secret shown once: it's made on the flow's Triggers panel, where it can be copied.
         return { ok: true, flow, said: hook ? `${name} is ready. To get its webhook address, open Triggers and choose New address.` : `${name} is ready.` };
     }
     catch (error) {

package/dist/flow-insights.js

@@ -1,9 +1,3 @@
-/**
- * Flow insights (v84): how work moves through a flow and where it breaks,
- * read from what the flow already records — every card's moves (flow_event)
- * and every script or update step's run (flow_step_run, with its log). No
- * model, no sampling: counts over a window, per zone and per script.
- */
 import { flowDefinitionOf } from "./flow-engine.js";
 import { parseSortDecision } from "./flow-sort.js";
 const median = (values) => {
@@ -13,7 +7,6 @@ const median = (values) => {
     const middle = Math.floor(sorted.length / 2);
     return sorted.length % 2 === 1 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
 };
-/** One flow's insights over the last `days` days. */
 export function flowInsights(store, flow, now, days = 30) {
     const since = new Date(now.getTime() - days * 86_400_000);
     const definition = flowDefinitionOf(flow);
@@ -90,7 +83,6 @@ export function flowInsights(store, flow, now, days = 30) {
         })),
     };
 }
-/** Each problem a plane review trigger of this flow noted in the window (one note per problem a day), and on how many days. */
 function recurringProblems(store, flow, since) {
     const rows = store.handle.prepare(`SELECT e.key, e.card, e.at, c.title FROM flow_trigger_event e JOIN flow_trigger t ON t.id = e.trigger LEFT JOIN flow_card c ON c.id = e.card
     WHERE t.flow = ? AND json_extract(t.config_json, '$.kind') = 'plane-review' AND substr(e.key, 1, 6) = 'plane:' AND e.at >= ? ORDER BY e.rowid`).all(flow.id, since.toISOString());
@@ -123,14 +115,12 @@ function sortInsight(stage, runs, byCard) {
         else
             insight.notSure++;
         insight.costUsd += decision.cost ?? 0;
-        // Where the sort sent the card, and what happened to it next.
         const moves = byCard.get(run.card) ?? [];
         const sent = moves.findIndex(one => one.fromStage === stage.id && one.actor === "flow" && one.at >= run.startedAt);
         const after = sent === -1 ? undefined : moves[sent + 1];
         const picked = sort.answers.find(one => one.answer === decision.answer)?.to ?? null;
         let right = null;
         if (after !== undefined && after.actor !== "flow" && after.outcome === "moved" && targets.has(after.toStage)) {
-            // A person placed it where an answer leads: that is what the answer should have been.
             right = after.toStage === picked;
             if (decision.confident && !right)
                 insight.corrected++;
@@ -147,7 +137,6 @@ function sortInsight(stage, runs, byCard) {
         }
     }
     insight.costUsd = Math.round(insight.costUsd * 1_000_000) / 1_000_000;
-    // Say so only with enough cards behind it.
     const at = Math.round(sort.sureAt * 100);
     const below = bands.find(one => one.to <= at && one.to > at - 15 && one.of >= 5);
     const above = bands.filter(one => one.from >= at && one.of >= 5);
@@ -158,7 +147,6 @@ function sortInsight(stage, runs, byCard) {
         insight.suggestion = `Cards Jev was ${below.from}–${below.to}% sure about were right ${below.right} of ${below.of} times. You could let it act alone from ${below.from}%.`;
     return insight;
 }
-/** One line for a flow's list entry: where it has had the most trouble lately. */
 export function troubleWords(insights) {
     const worst = insights.breaks[0];
     return worst === undefined ? null : `most trouble in ${worst.title} (${worst.problems} of ${worst.of} in the last ${insights.days} days)`;

package/dist/flow-items.js

@@ -1,13 +1,3 @@
-/**
- * A research report's items in a flow's message (flow-send.ts): after a report step, each item is listed under the
- * summary, numbered — its title in bold, its why in plain lines, and its link named by its source ("Mobbin", or the
- * site's name). Each screenshot of an item is captioned with the same number, its title and how it plugs in
- * (result-shots.ts), so "2." in the album is item 2 in the text.
- *
- * The message is written in reply-shape.ts's canonical form (`**bold**`, `[label](url)`), which every channel renders
- * in its own format. Its words go through the channel's own cleaner first. Fitted to a channel's limit, each why is
- * shortened evenly first; then the summary, then the titles; past that it is split into parts. Links are never cut.
- */
 export { readFlowItems } from "./contracts/flow-send.js";
 const PLUG_CHARS = 160;
 const NAMES = {
@@ -16,7 +6,6 @@ const NAMES = {
 };
 const cutTo = (text, cap) => cap <= 0 ? "" : text.length <= cap ? text : `${text.slice(0, Math.max(0, cap - 1)).trimEnd()}…`;
 const oneLine = (text) => text.replace(/\s+/g, " ").trim();
-/** A link's source by name: a few known sites as they write themselves, else the site's own name from its address. */
 export function itemSource(url) {
     let host;
     try {
@@ -31,12 +20,10 @@ export function itemSource(url) {
     const labels = host.split(".");
     if (labels.length < 2 || /^[0-9.]+$/.test(host) || host.includes(":"))
         return host;
-    // "bbc.co.uk" is the BBC's; "developer.apple.com" is Apple's.
     const short = labels.length >= 3 && labels[labels.length - 1].length === 2 && labels[labels.length - 2].length <= 3;
     const name = labels[labels.length - (short ? 3 : 2)];
     return name === "" ? host : `${name.charAt(0).toUpperCase()}${name.slice(1)}`;
 }
-/** A why as plain lines: its own lines, or "the pattern; why it fits us; how it plugs in" one to a line. */
 export function whyLines(why) {
     const lines = why.split(/\n+/).map(one => one.trim()).filter(one => one !== "");
     if (lines.length !== 1)
@@ -44,21 +31,16 @@ export function whyLines(why) {
     const parts = lines[0].split(/;\s+/).map(one => one.trim()).filter(one => one !== "");
     return parts.length >= 2 && parts.length <= 4 ? parts.map(one => `${one.charAt(0).toUpperCase()}${one.slice(1)}`) : lines;
 }
-/** How an item plugs in, in one line: the why's last line when it has several, else the image's caption, else the why. */
 export function itemPlug(why, imageCaption) {
     const lines = whyLines(why);
     const words = lines.length >= 2 ? lines[lines.length - 1] : imageCaption !== null && imageCaption.trim() !== "" ? imageCaption : lines.join(" ");
     return cutTo(oneLine(words), PLUG_CHARS);
 }
-/** A screenshot's caption: its item's number, title and how it plugs in. */
 export function itemCaption(number, item) {
     return item.plug === "" ? `${number}. ${item.title}` : `${number}. ${item.title} · ${item.plug}`;
 }
-/** Plain words can't become bold or a link by accident. */
 const inert = (text) => text.replace(/\*\*/g, "*").replace(/\]\(/g, "] (");
-/** A link the canonical form keeps whole: the characters it stops at are written percent-encoded, as browsers read them. */
 const linkable = (url) => url.replace(/[()[\]<>"'`\s]/g, char => `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
-/** The message's own words through a channel's cleaner — head, summary, each title and why, and tail — before it is fitted. */
 export function cleanFlowMessage(message, clean) {
     return { head: clean(message.head), summary: clean(message.summary), items: message.items.map(item => ({ ...item, title: clean(item.title), why: clean(item.why) })),
         tail: message.tail.map(clean) };
@@ -72,7 +54,6 @@ function blocks(message, whyCap, summaryCap, titleCap) {
     return [inert(message.head), inert(cutTo(message.summary, summaryCap)), ...items, ...message.tail.map(inert)].filter(one => one.trim() !== "");
 }
 const compose = (message, whyCap, summaryCap, titleCap) => blocks(message, whyCap, summaryCap, titleCap).join("\n\n");
-/** The largest n in [0, high] that fits, or -1. */
 function largest(high, fits) {
     if (!fits(0))
         return -1;
@@ -86,7 +67,6 @@ function largest(high, fits) {
     }
     return low;
 }
-/** Whole pieces packed into as few parts as fit, joined by `glue`; a piece too long alone is broken by `smaller`. */
 function pack(pieces, glue, fits, smaller) {
     const parts = [];
     let open = "";
@@ -101,7 +81,6 @@ function pack(pieces, glue, fits, smaller) {
     }
     return open === "" ? parts : [...parts, open];
 }
-/** A line longer than a whole part, in the longest prefixes that fit (never splitting a surrogate pair). */
 function chop(line, fits) {
     const out = [];
     for (let rest = line; rest !== "";) {
@@ -113,12 +92,6 @@ function chop(line, fits) {
     }
     return out;
 }
-/**
- * The message in canonical form, as parts within `limit` as `measure` counts each once the channel renders it: one
- * whole part when it fits; else every why shortened to the same length; then the summary; then the titles. When the
- * head, links and tail alone are over the limit, the whole message goes in several parts instead, split between
- * blocks (else between lines). Every link stays.
- */
 export function fitFlowMessage(message, limit, measure) {
     const fits = (text) => measure(text) <= limit;
     const full = compose(message, Infinity, Infinity, Infinity);

package/dist/flow-live.js

@@ -1,34 +1,11 @@
-/**
- * The live canvas (v88): a flow open in several browsers stays the same in
- * all of them, and each shows who else has it open.
- *
- * - A change nudge. When the live bus says the workspace was written
- *   (live-bus.ts), one small read checks the flow's fingerprint (its revision, cards, moves, comments,
- *   watchers, step runs, linked task progress and triggers); when it changed, every open page
- *   hears "change" and reads the flow again the usual way. The nudge
- *   carries no card data: what a page shows is always what its own read
- *   returned, under its own checks.
- * - Who's here. Each open page says which card it has open and whether it
- *   is changing the flow; everyone else on the flow hears the list, by
- *   name. It lives in memory only and goes when the page closes or hides.
- *
- * Streams are refresh hints only: nothing here writes, and a page that
- * can't keep one open falls back to reading every few seconds. With nothing
- * written, an open flow costs no reads; a 30-second check heals a miss.
- */
 import { browserViewOf } from "./flow-browser.js";
 import { createHash } from "node:crypto";
 import { createLiveRooms } from "./live-bus.js";
-// Statements belong to their database, without keeping closed Stores alive.
 const fingerprintStatements = new WeakMap();
 function fingerprintStatement(store) {
     const cached = fingerprintStatements.get(store.handle);
     if (cached !== undefined)
         return cached;
-    // Match Store.taskFamilyOf/taskFamilyProjection: built-in tasks, same-repo
-    // edges, a revision brief bound to the parent's run, and at most 63 edges.
-    // Walk up only from active cards, then down from their proven roots. A
-    // missing/invalid/cyclic/over-depth ancestry leaves the linked task alone.
     const statement = store.handle.prepare(`WITH RECURSIVE linked AS MATERIALIZED (
       SELECT DISTINCT tr.id AS ref_id, tr.external_id AS id, tr.repo, tr.revision_of, tr.revision_brief_artifact
       FROM flow_card c JOIN task_ref tr ON tr.external_id = c.task AND tr.backend = 'built-in'
@@ -85,24 +62,16 @@ function fingerprintStatement(store) {
     fingerprintStatements.set(store.handle, statement);
     return statement;
 }
-/** What changes when anything on the canvas changes: metadata only, kept short and opaque. */
 export function flowFingerprint(store, flow, now = new Date()) {
-    // A revision can progress while its card still links to the original task,
-    // including a build in another project. The page read admits the viewer;
-    // this stream only carries a hash. No evidence files or logs are read.
     const row = fingerprintStatement(store).get({ $flow: flow, $now: now.toISOString() });
     if (row === undefined)
         return null;
-    // Browser use (flow-browser.ts): an approval, a revocation, a changed covered script or a signer who lost standing
-    // changes what the page says, so it is part of what open pages are nudged on.
     const saved = store.getFlow(flow);
     const browser = saved === null ? null : browserViewOf(store, saved);
     const browserKey = browser === null ? "" : `${browser.status}:${browser.digest ?? ""}:${browser.signedAt ?? ""}:${browser.problem === null ? "" : "x"}`;
     return createHash("sha256").update([...Object.values(row).map(String), browserKey].join("|")).digest("hex").slice(0, 16);
 }
-/** Rooms keyed by flow. With a bus, a write reaches every open page at once; without one, only the safety net. */
 export function createFlowRooms(fingerprint, options = {}) {
-    /** Everyone on the flow but you, one line per person however many pages they have open. */
     const others = (viewers, me) => {
         const people = new Map();
         for (const one of viewers) {

package/dist/flow-people.js

@@ -1,17 +1,8 @@
-/**
- * People on flow cards (v83): who owns a card, who follows it, what was said
- * on it, and who hears about what. A notification about a card goes to the
- * people it concerns — the one who decides, its owner, its watchers, whoever
- * was @mentioned — on their own paired phone or chat, never to everyone.
- * A "Tell the team" zone still posts to everyone; that is what it is for.
- */
 import { scanForSecrets } from "./evidence.js";
 import { flowCardHref } from "./flow-engine.js";
-/** Everyone who may take part in a project's flows: approvers who can reach the project. */
 export function flowPeople(store, repo) {
     return store.listApprovers().map(one => one.name).filter(name => store.accountCanAccess(name, repo));
 }
-/** The people a comment @mentions: known names only, each once, in the order written. */
 export function mentionsIn(body, people) {
     const found = [];
     for (const match of body.matchAll(/(^|[^A-Za-z0-9_.@-])@([A-Za-z0-9][A-Za-z0-9_.-]{0,63})/g)) {
@@ -21,8 +12,6 @@ export function mentionsIn(body, people) {
     }
     return found;
 }
-/** One notification per person, to that person only. The actor never notifies themself. */
-/** A notice's body: whole up to 2,000 characters; longer, its start and a line saying the rest is on the card it links. */
 const NOTICE_CHARS = 2000;
 function noticeBody(body) {
     if (body.length <= NOTICE_CHARS)
@@ -48,11 +37,9 @@ export function notifyPeople(store, card, people, actor, event, now) {
     }
     return sent;
 }
-/** Who follows a card: its owner and its watchers. */
 export function cardFollowers(store, card) {
     return [...new Set([...(card.owner === null ? [] : [card.owner]), ...store.flowCardWatchers(card.id)])];
 }
-/** Make someone (or no one) a card's owner. The new owner follows it and hears so. */
 export function assignFlowCard(store, card, owner, actor, now) {
     const flow = store.getFlow(card.flow);
     if (flow === null || card.state !== "active")
@@ -72,7 +59,6 @@ export function watchFlowCard(store, card, name, watching, now) {
     store.setFlowCardWatcher(card.id, name, watching, now);
     return { ok: true, said: watching ? "You'll hear about this card." : "You won't hear about this card unless someone mentions you.", card: card.id };
 }
-/** A comment on a card: keys refused; the people it @mentions, the owner and watchers hear about it; the author and anyone mentioned follow it from now on. */
 export function commentOnFlowCard(store, card, author, text, now) {
     const flow = store.getFlow(card.flow);
     if (flow === null)

package/dist/flow-pull-request.js

@@ -1,17 +1,3 @@
-/**
- * A flow's Pull request zone (flows.ts): the card's built result becomes a pull request under the project's pull
- * request setup — the same grant, publisher and merge as Complete → pull request (pull-request-flow.ts) — and CI
- * decides where the card goes: on when checks pass (merging first when the zone says so), down the failure path
- * when they fail, with the failing check named on the card. A failure path back to a Build zone becomes a revision
- * of that same work carrying the failure, as a person's send back does.
- *
- * A zone that merges only ever merges a card a person approved (a "Person decides" zone) after it was last built:
- * the flow can't be drawn otherwise (validateFlowDefinition), and a card moved in by hand or by a trigger is checked
- * here too. Without that approval the checks passing leave it waiting for a person.
- *
- * Model-free, in the worker's step pass. The publisher and CI observation run in the watch loop; this reads what
- * they recorded, and reads GitHub itself only to name a failing check and to merge.
- */
 import { createHash } from "node:crypto";
 import { assignmentOf } from "./assignment.js";
 import { cardFollowers, notifyPeople } from "./flow-people.js";
@@ -20,18 +6,12 @@ import { failingCheckOf, mergePullRequest, owePullRequest, pullRequestBlocker, p
 import { requestResultChanges } from "./result-actions.js";
 import { revisionSourceOf } from "./result-review.js";
 import { cardTaskArchived } from "./task-archive.js";
-/** Whether a person approved this card at a "Person decides" zone since it was last built; their name when so.
- * The MOST RECENT decision governs (approval policy §1.7): it must be a person's recorded decision, after the card's
- * last build by the current definition AND after the exact build being merged finished (`builtAt`), so editing the
- * flow can't let an older person decision stand behind a newer machine one. */
 export function approvedSinceBuild(store, definition, card, builtAt = null) {
     const kindOf = (id) => definition.stages.find(one => one.id === id)?.kind ?? null;
     const events = store.flowEvents(card.id);
     let built = -1;
     events.forEach((event, index) => { if (kindOf(event.fromStage) === "task" || kindOf(event.toStage) === "task")
         built = index; });
-    // The latest DECISION of any kind governs: only decideFlowCard writes `approved` or `sent-back` (from a decision
-    // zone), whatever the zones are called now, so a send-back after a yes takes that yes back.
     const latest = events.slice(built + 1).reverse().find(event => event.outcome === "approved" || event.outcome === "sent-back");
     if (latest === undefined || latest.authority !== "person")
         return null;
@@ -39,11 +19,8 @@ export function approvedSinceBuild(store, definition, card, builtAt = null) {
         return null;
     return latest.actor;
 }
-/** One pass of a Pull request zone for one card. Returns whether it changed anything. */
 export async function pullRequestStep(store, flow, definition, stage, card, now, io) {
     const titleOf = (id) => definition.stages.find(one => one.id === id)?.title ?? "another zone";
-    // Every write after GitHub answers re-proves, in its own transaction, that the card's work wasn't put away meanwhile
-    // (v145): a put away that committed first leaves the card where it is, saying nothing to anyone.
     const unlessHeld = (write) => store.transact(() => cardTaskArchived(store, card.id) ? false : write());
     const waiting = (said) => unlessHeld(() => {
         if (card.waiting === said)
@@ -71,8 +48,6 @@ export async function pullRequestStep(store, flow, definition, stage, card, now,
             body: `${said}${stage.onFail === null ? "" : `\n\nIt's back in ${titleOf(stage.onFail)}${revision === null ? "" : `, as revision ${revision}`}.`}` }, now);
         return true;
     };
-    // Publishing that can't proceed is not the build's fault: rebuilding wouldn't change it, so the card waits here,
-    // saying what to do, and the people on it hear once. It carries on by itself once the cause is fixed.
     const stuck = (said) => unlessHeld(() => {
         if (!waiting(said))
             return false;
@@ -80,7 +55,6 @@ export async function pullRequestStep(store, flow, definition, stage, card, now,
         notifyPeople(store, card, people, null, { key: `pr-stuck:${card.entry}`, subject: `${stage.title} is waiting on you for “${card.title}”`, attention: true, body: said }, now);
         return true;
     });
-    // With no failure path, a card that didn't pass waits for a person to move it (a move is a fresh visit).
     if (stage.onFail === null && card.waiting !== null && card.waiting.endsWith(" Fix it, then move the card to try again."))
         return false;
     const task = card.primaryTask;
@@ -92,7 +66,6 @@ export async function pullRequestStep(store, flow, definition, stage, card, now,
     if (publication === null || pullRequestFollowOf(store, publication.id) === null) {
         if (publication === null) {
             const blocked = pullRequestBlocker(store, runId);
-            // Only a result that can't be published as built goes back to be built again.
             if (blocked !== null && (blocked === "This result has no commit to publish." || blocked.includes("looks like a secret")))
                 return failed(blocked);
             if (blocked === "Pull requests aren't set up for this project.")
@@ -106,7 +79,6 @@ export async function pullRequestStep(store, flow, definition, stage, card, now,
         const said = `Couldn't open the pull request: ${publication.lastError ?? "GitHub refused it"}. The commit is safe locally. Fix that, then move the card back to Build for a fresh result.`;
         if (card.waiting === said)
             return false;
-        // A pull request opened for this commit anyway (another pass, or a person) is the card's pull request.
         if (await adoptPublishedPullRequest(store, publication, io.gh, () => now))
             publication = store.publicationForRun(runId);
         else
@@ -120,7 +92,6 @@ export async function pullRequestStep(store, flow, definition, stage, card, now,
         return passed(`${pr} was merged on GitHub.`, `Merged: ${link}`);
     if (publication.remoteState === "CLOSED")
         return failed(`${pr} was closed on GitHub without merging.`);
-    // Only what CI said since the card came here counts: a card moved back to try again waits for a fresh look.
     const entered = store.flowCardEnteredAt(card.id) ?? card.updatedAt;
     const fresh = publication.lastCheckAt !== null && publication.lastCheckAt >= entered;
     if (!fresh || publication.lastCheckState === "running")
@@ -130,10 +101,8 @@ export async function pullRequestStep(store, flow, definition, stage, card, now,
     if (publication.lastCheckState === "failing") {
         const found = await failingCheckOf(io.gh, publication);
         const said = found === null ? `CI failed on ${pr}. GitHub couldn't be read to name the check.` : `CI check “${found.check}” failed on ${pr}.`;
-        // Back to a Build zone: a revision of the same work, carrying the failure (fenced as untrusted CI output).
         let revision = null;
         const target = definition.stages.find(one => one.id === stage.onFail);
-        // No revision of work put away while GitHub answered (v145).
         if (cardTaskArchived(store, card.id))
             return false;
         if (target?.kind === "task" && io.evidenceRoot !== undefined) {
@@ -148,7 +117,6 @@ export async function pullRequestStep(store, flow, definition, stage, card, now,
         }
         return failed(said, revision);
     }
-    // Checks pass.
     if (stage.merge === undefined)
         return passed(`${pr} passed its checks.`, `Pull request: ${link} (checks passed)`);
     const approver = approvedSinceBuild(store, definition, card, store.getRun(runId)?.finishedAt ?? null);