toolroll 0.9.104 → 0.9.105

package/dist/flow-share.js

@@ -1,20 +1,3 @@
-/**
- * Flow files: a flow exported as readable JSON (*.toolroll-flow.json) and
- * imported on another installation (docs/design/flow-gallery.md, "Export
- * and import"; the schema is docs/flow-file.schema.json).
- *
- * The file speaks the lead's step vocabulary — titles, kinds, next/ifFails,
- * instructions — so a person can read and edit it. It never carries what
- * belongs to this installation: secrets and their values, webhook
- * addresses and hashes, tokens, people's names, chat bindings or cards.
- * Repository-specific values (the GitHub repository, labels, a branch,
- * a Linear team, who decides) become parameters the import asks for.
- *
- * An import is previewed in plain words first, always. Its triggers arrive
- * switched off until a person turns them on, its scripts arrive held until
- * a person approves them, and its instructions are shown as the untrusted
- * text they are.
- */
 import { scanForSecrets } from "./evidence.js";
 import { flowDefinitionOf } from "./flow-engine.js";
 import { readFlowSecrets } from "./flow-secrets.js";
@@ -26,17 +9,13 @@ import { readVersioned } from "./contracts/contract.js";
 import { FLOW_ALIASES, WEBHOOK_SENDERS, FLOW_FILE_FORMAT, legacyFlowNeed, legacySubagentStep, FLOW_FILE_VERSION, flowFileSchema } from "./contracts/flow.js";
 import { parseSchedule } from "./flow-schedule.js";
 export { FLOW_FILE_FORMAT, FLOW_FILE_VERSION };
-/** The largest flow file Toolroll reads or fetches. */
 export const FLOW_FILE_MAX_BYTES = 256 * 1024;
 export const FLOW_FILE_SUFFIX = ".toolroll-flow.json";
 const PARAM = /\{\{\s*param\.([a-z0-9][a-z0-9-]{0,39})\s*\}\}/g;
 const REMOVED = "[removed]";
-// ------------------------------------------------------------------ export
-/** A zone in the lead's words: only what it says, in the order a person reads it. */
 function stepOf(stage, ask) {
     const step = { id: stage.id, title: stage.title, kind: stage.kind };
     const words = (minutes) => durationMinutes(durationWords(minutes)) === minutes ? durationWords(minutes) : minutes;
-    // Only what the step's kind says: words a zone kept from a kind it was before stay behind.
     if (stage.instructions !== null && (stage.kind === "task" || stage.kind === "report" || stage.kind === "draft" || stage.kind === "subagent"))
         step["instructions"] = stage.instructions;
     if (stage.kind === "task")
@@ -69,7 +48,6 @@ function stepOf(stage, ask) {
     if (stage.request !== undefined)
         Object.assign(step, { method: stage.request.method, url: stage.request.url, headers: stage.request.headers, ...(stage.request.body === null ? {} : { body: stage.request.body }) });
     if (stage.email !== undefined) {
-        // A written-out address is someone's: the import asks for it. Fill-ins ({{card.email}}) stay.
         const to = /[^\s@{}]+@[^\s@{}]+/.test(stage.email.to) ? ask({ id: `email-to-${stage.id}`.slice(0, 40), about: `Who ${stage.title} emails` }) : stage.email.to;
         Object.assign(step, { to, subject: stage.email.subject, body: stage.email.body });
     }
@@ -84,7 +62,6 @@ function stepOf(stage, ask) {
         step["subagent"] = stage.subagent;
     if (stage.reply === true)
         step["reply"] = true;
-    // A choice's buttons; "end" ignores the card. A build in another project names a path on this computer, so it stays here.
     if (stage.options !== undefined)
         step["options"] = stage.options.map(one => ({ label: one.label, goesTo: one.to }));
     if (stage.limit !== undefined)
@@ -96,7 +73,6 @@ function stepOf(stage, ask) {
     step["at"] = { x: stage.zone.x, y: stage.zone.y, w: stage.zone.w, h: stage.zone.h, color: stage.zone.color };
     return step;
 }
-/** A trigger's settings for the file, or why it stays behind. */
 function triggerOf(config, ask) {
     const zone = config.zone === null ? {} : { zone: config.zone };
     switch (config.kind) {
@@ -112,8 +88,6 @@ function triggerOf(config, ask) {
             ...(config.state === null ? {} : { state: config.state }),
             ...(config.label === null ? {} : { label: ask({ id: "linear-label", about: "The Linear label issues need", default: config.label }) }),
             delivery: config.delivery, ...zone };
-        // v126: who signs it travels (never its secret or address: an imported signed webhook isn't set up until its
-        // secret is made or pasted there); the project and team it is scoped to are asked again, as another install's own.
         case "webhook": return { kind: "webhook", title: config.title, ...(config.titleField == null ? {} : { titleField: config.titleField }), ...(config.bodyField == null ? {} : { bodyField: config.bodyField }),
             ...((config.sender ?? "none") === "none" ? {} : { sender: config.sender }),
             ...(config.project == null ? {} : { project: ask({ id: "webhook-project", about: "The project the signed webhook's deliveries must come from", default: config.project }) }),
@@ -130,7 +104,6 @@ function triggerOf(config, ask) {
         case "flow": return "the trigger from another flow (it names a flow on this installation)";
     }
 }
-/** What a flow needs to run, as short keys the import puts in words. */
 function needsOf(definition, triggers, scripts) {
     const needs = new Set();
     for (const stage of definition.stages) {
@@ -164,7 +137,6 @@ function needsOf(definition, triggers, scripts) {
         needs.add(`script:${name}`);
     return [...needs].sort();
 }
-/** Everything that would name this installation or someone on it, to take out of the file's text. */
 function privateValues(store, flow, definition, dir) {
     const values = Object.values(readFlowSecrets(dir, flow.repo)).filter(value => value.length >= 6);
     const base = readHooksBase(dir);
@@ -181,7 +153,6 @@ function privateValues(store, flow, definition, dir) {
     return { values, names: [...names].filter(name => name.trim().length >= 3) };
 }
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-/** Text with secrets, hook addresses and people's names taken out. A line that looks like a key goes whole. */
 function scrubber(values, names) {
     const people = names.length === 0 ? null : new RegExp(`(?<![A-Za-z0-9_.@-])(?:${names.map(escapeRegExp).join("|")})(?![A-Za-z0-9_@-])`, "gi");
     return text => {
@@ -192,7 +163,6 @@ function scrubber(values, names) {
         return out.split("\n").map(line => scanForSecrets(line).length > 0 ? REMOVED : line).join("\n");
     };
 }
-/** Structural fields: ids and references, never prose. Scrubbing them would break the flow's paths. */
 const STRUCTURAL = new Set(["format", "id", "kind", "goesTo", "next", "ifFails", "ifNotSure", "ifNoReply", "ifReplied", "thenMoveTo", "zone", "script", "language", "planning", "runIn", "waitFor", "method", "watch", "from", "delivery", "color", "merge"]);
 function scrubDeep(value, scrub, key, inScripts) {
     if (typeof value === "string")
@@ -200,15 +170,12 @@ function scrubDeep(value, scrub, key, inScripts) {
     if (Array.isArray(value))
         return value.map(one => scrubDeep(one, scrub, key, inScripts));
     if (value !== null && typeof value === "object") {
-        // v126: a webhook's sender is one of a fixed few words (who signs it), never prose: kept as it is, even when an
-        // account happens to share its name. An email trigger's sender is people's addresses, and is still scrubbed.
         const record = value;
         const webhookSender = record["kind"] === "webhook" && typeof record["sender"] === "string" && WEBHOOK_SENDERS.includes(record["sender"]);
         return Object.fromEntries(Object.entries(record).map(([k, v]) => [k, webhookSender && k === "sender" ? v : scrubDeep(v, scrub, k, inScripts || k === "scripts")]));
     }
     return value;
 }
-/** A flow as a file: its zones and paths, its triggers' settings and the scripts it runs, nothing of this installation's. */
 export function exportFlow(store, flow, dir) {
     const definition = flowDefinitionOf(flow);
     if (definition === null)
@@ -221,7 +188,6 @@ export function exportFlow(store, flow, dir) {
         parameters.push({ ...parameter, id });
         return `{{param.${id}}}`;
     };
-    // The start goes first, so the file reads in order and the import starts where this flow does.
     const ordered = [...definition.stages.filter(one => one.id === definition.start), ...definition.stages.filter(one => one.id !== definition.start)];
     const zones = ordered.map(stage => stepOf(stage, ask));
     const left = [];
@@ -253,19 +219,15 @@ export function exportFlow(store, flow, dir) {
         format: FLOW_FILE_FORMAT, version: FLOW_FILE_VERSION, name: flow.name,
         about: ordered.map(one => one.title).join(" → "),
         needs: needsOf(definition, triggers, scripts.map(one => one.name)),
-        // Zones and triggers in the file's words (stepOf, triggerOf): what flowFileSchema reads back (flow-share.test.ts).
         parameters, zones: zones, triggers: triggers, scripts,
     };
     const file = scrubDeep(raw, scrubber(values, names), null, false);
     const slug = flow.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "flow";
     return { file, json: `${JSON.stringify(file, null, 2)}\n`, fileName: `${slug}${FLOW_FILE_SUFFIX}`, left };
 }
-// ------------------------------------------------------------------ reading
-/** A flow file refused: why, in plain words, each problem naming its path in the file (`zones[0].routes[0]: ...`). */
 export class FlowFileError extends Error {
 }
 const refuse = (message) => { throw new FlowFileError(message); };
-/** A zone from the file as the canvas stores it: references by id (or by title), the rest checked by validateFlowDefinition. */
 function stageInputOf(step, index, find) {
     const at = `zones[${index}]`;
     const kind = step["kind"];
@@ -314,7 +276,6 @@ function stageInputOf(step, index, find) {
         next: find(step["next"], `${at}.next`), onFail: find(fail, `${at}.${failKey}`),
     };
 }
-/** The zones as a flow, checked whole. Throws in plain words. */
 function definitionOf(zones) {
     const ids = zones.map(one => one["id"]);
     const find = (ref, path) => {
@@ -330,10 +291,8 @@ function definitionOf(zones) {
     ids.forEach((one, index) => { if (typeof one !== "string")
         refuse(`zones[${index}].id: required`); });
     const stages = zones.map((step, index) => stageInputOf(step, index, find));
-    // Its zones are the file's, in order: a zone's problem names the file's zone.
     try {
         const definition = validateFlowDefinition({ version: 1, start: stages[0]?.["id"], stages });
-        // An imported flow is a new one: each {{stage.…}} must be one its zone hands on.
         const references = stageReferenceProblems(definition, null);
         if (references.length > 0)
             throw new FlowContractError(references.map(one => one.line));
@@ -354,12 +313,6 @@ const plainText = (value, cap, what, required) => {
         return refuse(`The file's ${what} has hidden characters in it.`);
     return value.trim();
 };
-/**
- * Read a flow file: its size, its JSON and format, then its one schema (flowFileSchema: every zone, trigger, script
- * and parameter, strict about unknown keys — `zones[0].routes[0]: unknown key 'to' (did you mean goesTo?)`), and a
- * newer version refused plainly. Then what the schema can't say: no keys in a trigger, ids and names used once, each
- * {{param.x}} declared, every script valid and the zones a flow. Throws FlowFileError in plain words.
- */
 export function parseFlowFile(text) {
     if (Buffer.byteLength(text, "utf8") > FLOW_FILE_MAX_BYTES)
         refuse(`That file is too big: a flow file is at most ${FLOW_FILE_MAX_BYTES / 1024} KB.`);
@@ -375,7 +328,6 @@ export function parseFlowFile(text) {
     const input = raw;
     if (input["format"] !== FLOW_FILE_FORMAT)
         refuse("That isn't a Toolroll flow file: its format isn't \"toolroll-flow\".");
-    // Triggers that name something on the installation they were made on stay there; say so, not that the kind is unknown.
     (Array.isArray(input["triggers"]) ? input["triggers"] : []).forEach((one, index) => {
         const kind = one !== null && typeof one === "object" ? one["kind"] : undefined;
         if (kind === "chat")
@@ -383,7 +335,6 @@ export function parseFlowFile(text) {
         if (kind === "flow")
             refuse(`triggers[${index}].kind: a trigger from another flow can't come from a file; it names a flow on the installation it was made on`);
     });
-    // D5: a file written before subagents were named so (a "teammate" zone, a "teammate:" need) reads as one written since.
     if (Array.isArray(input["zones"]))
         input["zones"] = input["zones"].map(legacySubagentStep);
     if (Array.isArray(input["needs"]))
@@ -416,14 +367,12 @@ export function parseFlowFile(text) {
     });
     if (new Set(scripts.map(one => one.name)).size !== scripts.length)
         refuse("scripts: two have the same name");
-    // Every {{param.x}} names a parameter the file declares.
     for (const match of JSON.stringify([file.zones, triggers]).matchAll(PARAM))
         if (!parameters.some(one => one.id === match[1]))
             refuse(`The file uses {{param.${match[1]}}} but doesn't say what it asks for.`);
     definitionOf(file.zones);
     return { format: FLOW_FILE_FORMAT, version: FLOW_FILE_VERSION, name, about, needs: (file.needs ?? []).map(one => one.trim()), parameters, zones: file.zones, triggers, scripts };
 }
-/** --param k=v lines (or a form's fields) as values; refuses parameters the file doesn't ask for. */
 export function parameterValues(file, given) {
     const values = {};
     for (const [id, value] of Object.entries(given)) {
@@ -441,7 +390,6 @@ export function parameterValues(file, given) {
         else
             refuse(`This flow asks for ${parameter.id}: ${parameter.about}. Give it with --param ${parameter.id}=<value>.`);
     }
-    // In the file's order, so the same answers always read (and fingerprint) the same.
     return Object.fromEntries(file.parameters.map(one => [one.id, values[one.id]]));
 }
 function fill(value, values) {
@@ -462,7 +410,6 @@ export function needWords(need) {
     const [kind, name] = need.includes(":") ? [need.slice(0, need.indexOf(":")), need.slice(need.indexOf(":") + 1)] : [need, ""];
     return NEED_WORDS[need] ?? (kind === "secret" ? `A saved secret called ${name}` : kind === "tool" ? `The ${name} tool (Settings → Tools)` : kind === "subagent" ? `A subagent called ${name}` : kind === "script" ? `The ${name} script` : need);
 }
-/** The import in plain words, checked against the project it lands in. Throws FlowFileError. */
 export function planFlowImport(store, repo, file, given, actor) {
     const values = parameterValues(file, given);
     const zones = fill(file.zones, values);
@@ -493,7 +440,6 @@ export function planFlowImport(store, repo, file, given, actor) {
         const script = typeof trigger["script"] === "string" ? trigger["script"] : null;
         if (script !== null && !named.has(script) && store.flowScript(repo, script) === null)
             refuse(`A schedule runs a script called ${script}, which isn't in the file or this project.`);
-        // A script the import brings isn't saved yet: its schedule is checked without it, then said with it.
         let config;
         try {
             config = validateTriggerConfig(script !== null && store.flowScript(repo, script) === null ? { ...trigger, script: undefined, title: `Items from ${script}` } : trigger, { store, flow: draft, definition, actor });
@@ -508,9 +454,7 @@ export function planFlowImport(store, repo, file, given, actor) {
     });
     const project = repo.split(/[\\/]/).filter(Boolean).pop() ?? repo;
     const all = flowTerms(definition, null);
-    // An about line that only lists the zones says nothing the steps don't.
     const about = file.about === "" || file.about === definition.stages.map(one => one.title).join(" → ") ? null : `About, from the file: ${file.about}`;
-    // Scripts have their own lines; the rest of what it needs is said once.
     const needs = file.needs.filter(one => !one.startsWith("script:"));
     const parts = {
         about,
@@ -533,7 +477,6 @@ export function planFlowImport(store, repo, file, given, actor) {
     ];
     return { name: file.name, repo, definition, triggers, scripts: { add, kept }, values, title: `Import the ${file.name} flow into ${project}`, terms, parts };
 }
-/** Make the planned flow: scripts held, the flow, and its triggers switched off. One transaction. */
 export function importFlow(store, plan, actor, now, dir) {
     return store.transact(() => {
         for (const script of plan.scripts.add) {
@@ -551,9 +494,7 @@ export function importFlow(store, plan, actor, now, dir) {
         return { id, said: `Imported ${plan.name}.${off === 0 ? "" : ` Its ${off === 1 ? "trigger is" : `${off} triggers are`} off until you turn ${off === 1 ? "it" : "them"} on.`}${held === 0 ? "" : ` Approve its ${held === 1 ? "script" : `${held} scripts`} on the Scripts panel before ${held === 1 ? "it runs" : "they run"}.`}` };
     });
 }
-// ------------------------------------------------------------------ fetching
 const FETCH_HOSTS = new Set(["github.com", "gist.github.com", "raw.githubusercontent.com", "gist.githubusercontent.com"]);
-/** A gist or GitHub file page as the address of its raw text; null when it isn't one Toolroll fetches. */
 export function rawFlowUrl(address) {
     let url;
     try {
@@ -572,7 +513,6 @@ export function rawFlowUrl(address) {
         return `https://gist.github.com${url.pathname.replace(/\/+$/, "")}${/\/raw(\/|$)/.test(url.pathname) ? "" : "/raw"}`;
     return url.toString();
 }
-/** A flow file from a gist or GitHub, over HTTPS only, refused past the size cap. Throws FlowFileError in plain words. */
 export async function fetchFlowFile(address, fetcher = fetch) {
     if (!/^https:\/\//i.test(address.trim()))
         refuse("Flow files are fetched over HTTPS only. Use an https:// address, or download the file and import it.");

package/dist/flow-sort.js

@@ -1,24 +1,12 @@
-/**
- * Sort steps (v85): Jev, TypeSafe's decision model, reached through
- * OpenRouter's Decisions API with the operator's own OpenRouter key. One
- * request per card: the card is the `state`; the zone's question is a
- * choice over its answers, and each thing the zone also notes is a score
- * or a yes/no question in the same request. Jev answers in well under a
- * second, with how sure it is. It never writes text, so nothing it returns
- * is instructions: an answer is only ever one of the zone's own options.
- */
 import { inEvalWorld } from "./eval-gate.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { SORT_ROUTE_KEY, sortKeyOf, sortNoteKeyOf } from "./contracts/flow.js";
 import { readJevReply } from "./contracts/sort-answer.js";
 export const JEV_URL = "https://openrouter.ai/api/alpha/decisions";
 export const JEV_MODEL = "~typesafe/jev-latest";
-/** Jev reads up to 32,000 tokens; the card is kept well under that. */
 const STATE_CHARS = 40_000;
 const clip = (text, cap) => text.length <= cap ? text : `${text.slice(0, cap - 1)}…`;
-/** Key-shaped lines never leave the machine. */
 const blank = (text) => redactSecretLines(text, scanForSecrets(text));
-/** What Jev reads: the card, where it came from, the latest note and what earlier zones reported — bounded, keys blanked. */
 export function sortState(card, earlier) {
     const state = { title: blank(clip(card.title, 500)) };
     if (card.description !== null && card.description.trim() !== "")
@@ -38,7 +26,6 @@ export function sortState(card, earlier) {
     }
     return state;
 }
-/** The one request for a card: the zone's question over its answers, plus what it also notes. */
 export function sortRequest(sort, state) {
     const questions = {
         [SORT_ROUTE_KEY]: { type: "choice", instructions: `${sort.question} Read the card's title and details.`, criteria: Object.fromEntries(sort.answers.map(one => [sortKeyOf(one.answer), one.means])) },
@@ -50,9 +37,7 @@ export function sortRequest(sort, state) {
     }
     return { model: JEV_MODEL, state, questions };
 }
-/** Ask Jev through OpenRouter. Trouble reaching it (or a refused key, or no credit) is a reason to try again, in words. */
 export async function askJev(fetcher, key, request) {
-    // An eval world makes no provider call it can't gate and record (eval-gate.ts), so nothing is sent.
     if (inEvalWorld())
         return { ok: false, said: "An eval world makes no Jev call." };
     const started = Date.now();
@@ -71,7 +56,7 @@ export async function askJev(fetcher, key, request) {
     try {
         body = await response.json();
     }
-    catch { /* said below */ }
+    catch { }
     if (!response.ok) {
         const error = body["error"];
         const detail = typeof error?.message === "string" ? ` It said: ${clip(error.message.replace(/\s+/g, " "), 160)}` : "";
@@ -85,10 +70,6 @@ export async function askJev(fetcher, key, request) {
     return { ok: true, body, ms: Date.now() - started };
 }
 const shortLevel = (level) => level.split(":")[0].trim();
-/**
- * Jev's answers, read through the reply's contract (src/contracts/sort-answer.ts) and then against the zone's own
- * options only; anything else is a problem, never a route. Confidences and chances are clamped into 0–1.
- */
 export function readJevAnswers(stage, body, ms) {
     const sort = stage.sort;
     const read = readJevReply(body);
@@ -127,13 +108,11 @@ export function readJevAnswers(stage, body, ms) {
     };
 }
 const percent = (value) => `${Math.round(value * 100)}%`;
-/** The decision in one line, as the card and later zones read it ({{stage.<id>}}). */
 export function sortWords(decision) {
     const lead = decision.confident ? `${decision.answer}, ${percent(decision.sure)} sure.` : `Not sure: ${percent(decision.sure)} ${decision.answer}.`;
     const notes = decision.notes.map(one => one.kind === "score" ? `${one.question} ${shortLevel(one.answer)}.` : `${one.question} ${one.answer === "yes" ? "Yes" : "No"}.`);
     return [lead, ...notes].join(" ");
 }
-/** The run's log: every answer's chance and each note, for the Insights run view. */
 export function sortLog(stage, decision) {
     const lines = [`Jev (${decision.model}) · ${decision.ms} ms${decision.cost === null ? "" : ` · $${decision.cost.toFixed(6)}`}`, "", stage.sort.question];
     for (const [answer, chance] of Object.entries(decision.chances).sort((a, b) => b[1] - a[1]))
@@ -143,7 +122,6 @@ export function sortLog(stage, decision) {
         lines.push("", note.question, `  ${note.answer} (${percent(note.sure)} sure)`);
     return lines.join("\n");
 }
-/** A kept decision, or null when there is none or it can't be read. */
 export function parseSortDecision(json) {
     if (json === null)
         return null;
@@ -155,7 +133,6 @@ export function parseSortDecision(json) {
         return null;
     }
 }
-/** A card's chip on the canvas: the answer and how sure, and the first score's short level. */
 export function sortChip(decision) {
     const score = decision.notes.find(one => one.kind === "score");
     return [`${decision.answer} · ${percent(decision.sure)}`, ...(score === undefined ? [] : [shortLevel(score.answer)])].join(" · ");

package/dist/flow-starters-ui.js

@@ -4,13 +4,11 @@ import { btn, chip, group, note } from "./server/kit.js";
 export const STARTERS_CSS = `.fl-starter-does{margin:2px 0 0;padding-left:18px;font-size:12.5px;line-height:1.5;color:var(--so-muted)}.fl-starter-never{font-weight:500;color:var(--so-ink)}` +
     `.fl-trow[data-suggested="true"]{border-left:2px solid var(--so-ink);padding-left:12px}`;
 export function startersHtml(input) {
-    // The one asked about ("Do this every time…") comes first, marked.
     const ordered = [...input.starters].sort((a, b) => Number(b.id === input.suggested) - Number(a.id === input.suggested));
     const rows = ordered.map(one => {
         const action = one.on !== null ? btn("Open flow", { sm: true, href: `/flows/${one.on.flow}` })
             : one.blocked !== null || !input.canSwitch ? ""
                 : postForm("/settings/flows/on", btn("Switch on", { sm: true, type: "submit", attrs: { "aria-label": `Switch on ${one.name}` } }), { hidden: { repo: input.repo, starter: one.id } });
-        // What the yes agrees to, in full, before it; nothing to agree to once it's on or can't be.
         const line = one.on !== null ? chip("On", "done")
             : one.blocked !== null ? html `<span>${one.blocked}</span>`
                 : html `<span><ul class="fl-starter-does">${one.does.map(words => html `<li>${words}</li>`)}</ul><span class="fl-starter-never">${one.never}</span></span>`;

package/dist/flow-starters.js

@@ -1,9 +1,3 @@
-/**
- * Starter flows: flows that are on from day one, each switched on with one yes from `toolroll onboard`,
- * Settings → Flows, a task's "Do this every time…" or chat. Switching one on makes an ordinary flow (its zones)
- * and its trigger, exactly as drawing them by hand would; it is on while that flow is. Each says in plain words
- * what it will do and what it never does: no starter merges or ships anything without a person.
- */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { flowDefinitionOf } from "./flow-engine.js";
@@ -72,7 +66,6 @@ export const STARTER_FLOWS = [
         trigger: () => ({ kind: "plane-review", at: "07:30" }),
     },
 ];
-/** The morning plane review's steps: find the cause, fix it, open a pull request; any failure waits for a person. */
 export function planeReviewSteps(own) {
     const where = own
         ? "This project is Toolroll itself, so the fix belongs here. Find the root cause in this code: cite the files and lines, say why it happened, and say what change fixes it."
@@ -86,7 +79,6 @@ export function planeReviewSteps(own) {
         { id: "needs-a-look", title: "Needs a look", kind: "inbox", next: "done" },
     ];
 }
-/** Whether a project is Toolroll's own source. */
 export function isToolrollRepo(repo) {
     if (!folderAnswers(repo))
         return false;
@@ -98,11 +90,9 @@ export function isToolrollRepo(repo) {
     }
 }
 export const starterOf = (id) => STARTER_FLOWS.find(one => one.id === id) ?? null;
-/** The flow a starter made in a project, while it is on. */
 export function starterFlowOf(store, starter, repo) {
     return store.listFlows([repo]).find(one => one.name === starter.name && one.state === "active") ?? null;
 }
-/** Each starter for a project: what it does there, whether it's on, and why it can't be switched on when it can't. */
 export function startersFor(store, repo) {
     const github = githubRepoOf(repo);
     const publishing = publishingOf(store, repo);
@@ -113,7 +103,6 @@ export function startersFor(store, repo) {
             on: flow === null ? null : { flow: flow.id }, blocked: starter.github && github === null ? "This project isn't on GitHub, so this can't watch it." : null };
     });
 }
-/** Switch a starter on in a project: its flow (zones) and its trigger, together or not at all. Once is enough. */
 export function switchOnStarter(store, starter, repo, by, now, dir) {
     const had = starterFlowOf(store, starter, repo);
     if (had !== null)
@@ -137,13 +126,11 @@ export function switchOnStarter(store, starter, repo, by, now, dir) {
         return { ok: false, said: `${starter.name} couldn't be switched on: ${error instanceof Error ? error.message : "unknown"}` };
     }
 }
-/** The starter that would do a task's kind of work every time: fixing CI, an issue, or a queued job. */
 export function starterForWork(text) {
     const id = /\b(ci|checks?|build|pipeline|workflow)\b[^.\n]{0,60}\b(fail|failed|failing|failure|red|broken)\b|\b(fail|failed|failing|broken)\b[^.\n]{0,60}\b(ci|checks?|pipeline)\b/i.test(text) ? "ci-fix"
         : /github\.com\/[^/\s]+\/[^/\s]+\/issues\/\d+|\bissue\s*#?\d+|\bGitHub issue\b/i.test(text) ? "issue-task" : "overnight";
     return starterOf(id);
 }
-/** What switching a starter on means, for a chat card's terms. */
 export function starterTerms(store, starter, repo) {
     const view = startersFor(store, repo).find(one => one.id === starter.id);
     return [view.summary, ...view.does, view.never];