toolroll 0.9.1 → 0.9.3

package/dist/flows-cli.js

@@ -0,0 +1,403 @@
+/** `toolroll flows …`: set up and inspect flows from a terminal, through the
+ * same helpers the console and the lead's flow tool use — flowFromSteps,
+ * FLOW_TEMPLATES, the starter flows, addFlowTriggerTo, saveScript and
+ * addCardToFlow — so a flow made here is checked exactly as one drawn there.
+ * Reads need no login; every write is an approver's, proved by --as/--token
+ * (or the remembered login), and lands in the ledger as a console request
+ * does. create, edit, archive and trigger add preview until --yes. */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { envelopeJson } from './envelope.js';
+import { addCardToFlow, advanceFlows, flowDefinitionOf } from './flow-engine.js';
+import { saveScript } from './flow-scripts.js';
+import { STARTER_FLOWS, starterFlowOf, starterOf, startersFor, starterTerms, switchOnStarter } from './flow-starters.js';
+import { addFlowTriggerTo, checkFlowTriggerNow, describeTrigger, removeFlowTrigger, triggerConfigOf, validateTriggerConfig } from './flow-triggers.js';
+import { deciderOf, FLOW_KIND_WORDS, FLOW_TEMPLATES, flowDigest, flowFromSteps, flowTerms, stepsFor } from './flows.js';
+import { verifyApproverByPassword } from './principal.js';
+import { projectName } from './project.js';
+const EXIT = { ok: 0, failed: 1, usage: 2, refused: 3 };
+const json = { name: 'json', takesValue: false, meaning: 'answer with one machine envelope on stdout' };
+const db = { name: 'db', takesValue: true, meaning: 'path to the database file (defaults to the installation\'s)' };
+const as = { name: 'as', takesValue: true, meaning: 'the approver making the change (default: the remembered login)' };
+const token = { name: 'token', takesValue: true, meaning: "that approver's password" };
+const yes = { name: 'yes', takesValue: false, meaning: 'make the previewed change' };
+const repo = { name: 'repo', takesValue: true, meaning: 'the project checkout root' };
+const steps = { name: 'steps', takesValue: true, meaning: "a JSON file (or - for stdin) with the steps in order, as the lead's flow tool takes them" };
+const read = [json, db];
+const write = [json, db, as, token];
+export const FLOWS_DESCRIPTORS = [
+    { action: 'list', synopsis: 'list flows: id, name, project, zones, triggers and cards waiting', mutation: 'none', flags: [...read, repo] },
+    { action: 'show', synopsis: 'one flow: zones with their next and failure paths, triggers and recent cards', mutation: 'none', positionals: ['flow'], flags: read },
+    { action: 'create', synopsis: 'create a flow from --template <id> (a template or starter flow) or --steps <file|->; previews until --yes', mutation: 'unkeyed', flags: [...write, yes, repo,
+            { name: 'name', takesValue: true, meaning: "the flow's name (a template's label when left out)" },
+            { name: 'template', takesValue: true, meaning: `one of ${[...FLOW_TEMPLATES.map(one => one.id), ...STARTER_FLOWS.map(one => one.id)].join(', ')}` }, steps] },
+    { action: 'edit', synopsis: "replace a flow's steps (kept steps by id) and optionally rename it; previews until --yes", mutation: 'unkeyed', positionals: ['flow'], flags: [...write, yes, steps, { name: 'name', takesValue: true, meaning: 'a new name' }] },
+    { action: 'trigger add', synopsis: 'add a trigger from JSON or a JSON file (any kind: button, schedule, github, linear, flow, webhook, email, chat); previews until --yes', mutation: 'unkeyed', positionals: ['flow', 'trigger'], flags: [...write, yes] },
+    { action: 'trigger pause', synopsis: 'pause a trigger', mutation: 'identity-idempotent', positionals: ['flow', 'trigger'], flags: write },
+    { action: 'trigger resume', synopsis: 'turn a paused trigger on again', mutation: 'identity-idempotent', positionals: ['flow', 'trigger'], flags: write },
+    { action: 'trigger remove', synopsis: 'remove a trigger; cards it added stay', mutation: 'identity-idempotent', positionals: ['flow', 'trigger'], flags: write },
+    { action: 'trigger check', synopsis: 'run a checked trigger (or a schedule\'s script) now, like Check now', mutation: 'unkeyed', positionals: ['flow', 'trigger'], flags: write },
+    { action: 'script save', synopsis: "save a project script (a new version when it exists)", mutation: 'identity-idempotent', flags: [...write, repo,
+            { name: 'name', takesValue: true, meaning: 'lowercase letters, numbers and dashes' },
+            { name: 'file', takesValue: true, meaning: 'run this path in the project' },
+            { name: 'body', takesValue: true, meaning: 'a local file holding the script itself' },
+            { name: 'about', takesValue: true, meaning: 'one line: what it checks or does' },
+            { name: 'language', takesValue: true, meaning: 'shell (default), python or node' },
+            { name: 'timeout-minutes', takesValue: true, meaning: '1 to 60 (default 15)' }] },
+    { action: 'card add', synopsis: 'add a card, in the first zone unless --zone names one', mutation: 'unkeyed', positionals: ['flow'], flags: [...write,
+            { name: 'title', takesValue: true, meaning: "the card's title" },
+            { name: 'description', takesValue: true, meaning: 'its details' },
+            { name: 'zone', takesValue: true, meaning: 'a zone id or name' }] },
+    { action: 'archive', synopsis: 'archive a flow: its cards stop moving and its triggers stop; previews until --yes', mutation: 'identity-idempotent', positionals: ['flow'], flags: [...write, yes] },
+];
+/** `--file` is a value here (a path in the project), where elsewhere it is a switch. */
+export const FLOWS_VALUE_FLAGS = new Set(['file']);
+export async function runFlowsCommand(positional, flags, context) {
+    const [first, second] = positional;
+    const action = first === 'trigger' || first === 'script' || first === 'card' ? `${first} ${second ?? ''}`.trim() : first ?? 'list';
+    const command = `flows ${action}`;
+    const args = positional.slice(action.split(' ').length);
+    const fail = (reason, message, code = EXIT.refused, extra = {}) => {
+        context.write(context.json ? envelopeJson({ ok: false, command, reason, message, ...extra }) : message);
+        return code;
+    };
+    const ok = (result, lines) => { context.write(context.json ? envelopeJson({ ok: true, command, ...result }) : lines.join('\n')); return EXIT.ok; };
+    const descriptor = FLOWS_DESCRIPTORS.find(one => one.action === action);
+    if (descriptor === undefined)
+        return fail('usage', `Use flows ${FLOWS_DESCRIPTORS.map(one => one.action).join(' | ')}.`, EXIT.usage);
+    const known = new Set(descriptor.flags.map(one => one.name));
+    for (const name of flags.keys())
+        if (!known.has(name) && name !== 'help')
+            return fail('usage', `--${name} is not a flows ${action} option.`, EXIT.usage);
+    const text = (key) => { const value = flags.get(key); return typeof value === 'string' ? value : null; };
+    const readInput = context.readInput ?? ((path) => readFileSync(path === '-' ? 0 : resolve(path), 'utf8'));
+    const { store } = context;
+    // ---- reads: what the installation holds, no login needed
+    const projectOf = (given) => given === null ? null : context.projects.find(one => one === given || one === resolve(given)) ?? null;
+    const flowOf = (value, repos) => {
+        const flow = value !== undefined && /^[1-9][0-9]{0,9}$/.test(value) ? store.getFlow(Number(value)) : null;
+        return flow !== null && flow.state === 'active' && repos.includes(flow.repo) ? flow : null;
+    };
+    if (action === 'list') {
+        const given = text('repo');
+        const project = projectOf(given);
+        if (given !== null && project === null)
+            return fail('unknown-project', 'That isn\'t a project Toolroll knows.');
+        const flows = store.listFlows(project === null ? context.projects : [project]).map(flow => listed(store, flow));
+        return ok({ flows }, flows.length === 0 ? ['No flows yet. Create one: toolroll flows create --repo <path> --name <name> --template coding'] : flows.map(one => `#${one.id}  ${one.name} · ${one.project} · ${one.zones.length} zone${one.zones.length === 1 ? '' : 's'} · ${one.triggers} trigger${one.triggers === 1 ? '' : 's'} · ${one.cardsWaiting} card${one.cardsWaiting === 1 ? '' : 's'} waiting`));
+    }
+    if (action === 'show') {
+        const flow = flowOf(args[0], context.projects);
+        if (flow === null)
+            return fail('unknown-flow', 'No such flow in your projects. toolroll flows list names them.');
+        const shown = describeFlow(store, flow);
+        return ok({ flow: shown }, showLines(shown));
+    }
+    // ---- writes: an approver's, on a project they can reach
+    if (context.credentials === null)
+        return fail('unauthenticated', 'Changing a flow needs an approver: pass --as <you> --token <your password> (or sign in once with toolroll up).');
+    const acting = context.credentials;
+    const reachable = context.projects.filter(one => store.accountCanAccess(acting.name, one));
+    const verified = verifyApproverByPassword(store, acting.name, acting.token, reachable);
+    if (!verified.ok)
+        return fail('unauthenticated', 'That name and password aren\'t an approver\'s. Nothing was changed.');
+    const who = verified.who.name;
+    const now = context.clock();
+    // Each write, taken or refused, is a line in the ledger, like a console request.
+    const record = (project, outcome, detail = null) => {
+        store.recordAction({ at: context.clock().toISOString(), actor: who, repo: project, taskId: null, runId: null, action: command, outcome, source: 'request', detail: `command line${detail === null ? '' : ` · ${detail}`}` });
+    };
+    const refuse = (project, reason, message, code = EXIT.refused) => { record(project, 'refused', reason); return fail(reason, message, code); };
+    const settle = (project) => { try {
+        advanceFlows(store, project, context.clock(), { evidenceRoot: context.evidenceRoot });
+    }
+    catch { /* the next worker pass retries */ } };
+    const preview = (project, title, terms, extra) => ok({ applied: false, repo: project, title, terms, ...extra }, [title, ...terms.map(one => `  ${one.replace(/\n/g, '\n     ')}`), '', 'Nothing has changed. Add --yes to make this change.']);
+    const readJson = (value, what) => {
+        let raw;
+        try {
+            raw = value.trim().startsWith('{') || value.trim().startsWith('[') ? value : readInput(value);
+        }
+        catch {
+            return { ok: false, message: `The ${what} file couldn't be read.` };
+        }
+        try {
+            return { ok: true, value: JSON.parse(raw) };
+        }
+        catch {
+            return { ok: false, message: `The ${what} aren't valid JSON.` };
+        }
+    };
+    const stepsOf = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) && 'steps' in value ? value.steps : value;
+    if (action === 'create') {
+        const given = text('repo');
+        if (given === null)
+            return fail('usage', 'Use flows create --repo <path> --name <name> (--template <id> | --steps <file|->).', EXIT.usage);
+        const project = projectOf(given);
+        if (project === null || !reachable.includes(project))
+            return refuse(null, 'unknown-project', 'That isn\'t one of your projects. toolroll repos lists them.');
+        const templateId = text('template'), stepsFile = text('steps');
+        if ((templateId === null) === (stepsFile === null))
+            return fail('usage', 'Give --template or --steps, not both.', EXIT.usage);
+        const name = (text('name') ?? '').replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, 80);
+        const starter = templateId === null ? null : starterOf(templateId);
+        if (starter !== null) {
+            // A starter flow: its zones and its trigger, together, under its own name.
+            if (name !== '' && name !== starter.name)
+                return fail('usage', `A starter flow keeps its name, ${starter.name}.`, EXIT.usage);
+            if (starterFlowOf(store, starter, project) !== null)
+                return refuse(project, 'already-on', `${starter.name} is already on in ${projectName(project)}.`);
+            const blocked = startersFor(store, project).find(one => one.id === starter.id)?.blocked ?? null;
+            if (blocked !== null)
+                return refuse(project, 'blocked', blocked);
+            if (!flags.has('yes'))
+                return preview(project, `Switch on ${starter.name} in ${projectName(project)}`, starterTerms(store, starter, project), { starter: starter.id });
+            const switched = switchOnStarter(store, starter, project, who, now, context.configDir);
+            if (!switched.ok)
+                return refuse(project, 'refused', switched.said);
+            record(project, 'accepted', `flow #${switched.flow}`);
+            return ok({ applied: true, flow: describeFlow(store, store.getFlow(switched.flow)) }, [`${switched.said} Flow #${switched.flow}.`]);
+        }
+        const template = templateId === null ? null : FLOW_TEMPLATES.find(one => one.id === templateId) ?? null;
+        if (templateId !== null && template === null)
+            return fail('usage', `Choose a template: ${[...FLOW_TEMPLATES.map(one => one.id), ...STARTER_FLOWS.map(one => one.id)].join(', ')}.`, EXIT.usage);
+        let definition;
+        if (template !== null)
+            definition = structuredClone(template.definition);
+        else {
+            const input = readJson(stepsFile, 'steps');
+            if (!input.ok)
+                return refuse(project, 'invalid-steps', input.message);
+            try {
+                definition = flowFromSteps(stepsFor(stepsOf(input.value), who), null);
+            }
+            catch (error) {
+                return refuse(project, 'invalid-steps', error instanceof Error ? error.message : 'Those steps aren\'t a flow.');
+            }
+        }
+        const flowName = name || template?.label || '';
+        if (flowName === '')
+            return fail('usage', 'Name the flow with --name.', EXIT.usage);
+        const terms = flowTerms(definition, null);
+        if (template?.trigger !== undefined) {
+            const draft = { id: 0, repo: project, name: flowName, definitionJson: JSON.stringify(definition), revision: 1, state: 'active', createdBy: who, createdAt: now.toISOString(), updatedBy: who, updatedAt: now.toISOString(), owner: who };
+            try {
+                terms.push(`Starts cards from: ${describeTrigger(validateTriggerConfig(template.trigger, { store, flow: draft, definition, actor: who }), store)}. Only what happens from now on counts.`);
+            }
+            catch (error) {
+                return refuse(project, 'invalid-trigger', error instanceof Error ? error.message : 'Its trigger isn\'t valid.');
+            }
+        }
+        if (!flags.has('yes'))
+            return preview(project, `Create the ${flowName} flow in ${projectName(project)}`, terms, { definition });
+        let id;
+        try {
+            id = store.transact(() => {
+                const made = store.createFlow({ repo: project, name: flowName, definitionJson: JSON.stringify(definition), by: who }, now);
+                if (template?.trigger !== undefined) {
+                    const trigger = addFlowTriggerTo(store, store.getFlow(made), template.trigger, who, now, context.configDir);
+                    if (!trigger.ok)
+                        throw new Error(trigger.message);
+                }
+                return made;
+            });
+        }
+        catch (error) {
+            return refuse(project, 'invalid-trigger', error instanceof Error ? error.message : 'Its trigger isn\'t valid.');
+        }
+        record(project, 'accepted', `flow #${id}`);
+        return ok({ applied: true, flow: describeFlow(store, store.getFlow(id)) }, [`Created ${flowName}, flow #${id}. Add cards with toolroll flows card add ${id} --title "…".`]);
+    }
+    if (action === 'script save') {
+        const given = text('repo');
+        if (given === null || text('name') === null)
+            return fail('usage', 'Use flows script save --repo <path> --name <name> (--file <path in project> | --body <file>) --about "<one line>".', EXIT.usage);
+        const project = projectOf(given);
+        if (project === null || !reachable.includes(project))
+            return refuse(null, 'unknown-project', 'That isn\'t one of your projects. toolroll repos lists them.');
+        let body;
+        const bodyFile = text('body');
+        if (bodyFile !== null) {
+            try {
+                body = readInput(bodyFile);
+            }
+            catch {
+                return refuse(project, 'unreadable', 'The --body file couldn\'t be read.');
+            }
+        }
+        const saved = saveScript(store, project, { name: text('name'), about: text('about') ?? undefined, body, file: text('file') ?? undefined, language: text('language') ?? undefined, timeoutMinutes: text('timeout-minutes') ?? undefined }, who, now);
+        if (!saved.ok)
+            return refuse(project, 'invalid-script', saved.message);
+        record(project, 'accepted', `script ${String(text('name')).trim().toLowerCase()} v${saved.version}`);
+        settle(project);
+        return ok({ applied: true, repo: project, script: store.flowScript(project, String(text('name')).trim().toLowerCase()), said: saved.said }, [saved.said]);
+    }
+    // Everything else names a flow in one of this person's projects.
+    const flow = flowOf(args[0], reachable);
+    if (flow === null)
+        return refuse(null, 'unknown-flow', 'No such flow in your projects. toolroll flows list names them.');
+    const definition = flowDefinitionOf(flow);
+    if (action === 'archive') {
+        const cards = store.flowCards(flow.id, false).length, triggers = store.flowTriggers(flow.id).filter(one => one.state === 'active').length;
+        if (!flags.has('yes'))
+            return preview(flow.repo, `Archive the ${flow.name} flow`, [
+                `It leaves the flows list. ${cards === 0 ? 'No cards are in it.' : `Its ${cards} active card${cards === 1 ? '' : 's'} stop moving.`}${triggers === 0 ? '' : ` Its ${triggers} trigger${triggers === 1 ? '' : 's'} stop adding cards.`}`,
+                'Tasks its cards filed stay as they are.',
+            ], { flowId: flow.id });
+        if (!store.archiveFlow(flow.id, who, now))
+            return refuse(flow.repo, 'stale', 'Someone archived it just now.');
+        record(flow.repo, 'accepted', `flow #${flow.id}`);
+        return ok({ applied: true, flowId: flow.id }, [`Archived ${flow.name}.`]);
+    }
+    if (definition === null)
+        return refuse(flow.repo, 'unreadable', 'This flow\'s drawing can\'t be read. Save it again from the editor.');
+    if (action === 'edit') {
+        const stepsFile = text('steps');
+        if (stepsFile === null && text('name') === null)
+            return fail('usage', 'Use flows edit <flow> --steps <file|-> [--name <name>].', EXIT.usage);
+        let next = definition;
+        if (stepsFile !== null) {
+            const input = readJson(stepsFile, 'steps');
+            if (!input.ok)
+                return refuse(flow.repo, 'invalid-steps', input.message);
+            try {
+                next = flowFromSteps(stepsFor(stepsOf(input.value), who), definition);
+            }
+            catch (error) {
+                return refuse(flow.repo, 'invalid-steps', error instanceof Error ? error.message : 'Those steps aren\'t a flow.');
+            }
+        }
+        const name = (text('name') ?? flow.name).replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, 80) || flow.name;
+        const redrawn = flowDigest(next) !== flowDigest(definition);
+        if (!redrawn && name === flow.name)
+            return fail('no-change', 'That\'s the flow as it is now.');
+        if (!flags.has('yes'))
+            return preview(flow.repo, `Change the ${flow.name} flow`, [...(name === flow.name ? [] : [`Renames it to ${name}.`]), ...(redrawn ? flowTerms(next, definition) : [])], { flowId: flow.id, revision: flow.revision, definition: next });
+        if (!store.saveFlow(flow.id, { name, definitionJson: JSON.stringify(next), sawRevision: flow.revision, by: who }, now))
+            return refuse(flow.repo, 'stale', 'Someone else changed this flow. Look again, then make yours.');
+        record(flow.repo, 'accepted', `flow #${flow.id}`);
+        settle(flow.repo);
+        return ok({ applied: true, flow: describeFlow(store, store.getFlow(flow.id)) }, [`Saved ${name}.`]);
+    }
+    if (action === 'card add') {
+        const title = text('title');
+        if (title === null)
+            return fail('usage', 'Use flows card add <flow> --title "<title>" [--description "<details>"] [--zone <zone>].', EXIT.usage);
+        const named = text('zone');
+        const stage = named === null ? null : definition.stages.find(one => one.id === named.trim() || one.title.toLowerCase() === named.trim().toLowerCase()) ?? null;
+        if (named !== null && stage === null)
+            return refuse(flow.repo, 'unknown-zone', `This flow has no zone called ${named}.`);
+        const added = addCardToFlow(store, flow, { title, description: text('description'), stage: stage?.id ?? null }, who, now);
+        if (!added.ok)
+            return refuse(flow.repo, 'invalid-card', added.message);
+        record(flow.repo, 'accepted', `flow #${flow.id} card #${added.card}`);
+        settle(flow.repo);
+        const card = store.getFlowCard(added.card);
+        return ok({ applied: true, card: card === null ? { id: added.card } : cardOf(definition, card), said: added.said }, [`${added.said} Card #${added.card}.`]);
+    }
+    if (action === 'trigger add') {
+        if (args[1] === undefined)
+            return fail('usage', 'Use flows trigger add <flow> <json|file|->, like \'{"kind":"schedule","schedule":"daily 09:00","title":"Standup"}\'.', EXIT.usage);
+        const input = readJson(args[1], 'trigger settings');
+        if (!input.ok)
+            return refuse(flow.repo, 'invalid-trigger', input.message);
+        let config;
+        try {
+            config = validateTriggerConfig(input.value, { store, flow, definition, actor: who });
+        }
+        catch (error) {
+            return refuse(flow.repo, 'invalid-trigger', error instanceof Error ? error.message : 'That trigger isn\'t valid.');
+        }
+        const words = describeTrigger(config, store);
+        if (!flags.has('yes')) {
+            const zone = definition.stages.find(one => one.id === (config.zone ?? definition.start))?.title ?? 'the first zone';
+            return preview(flow.repo, `Add a trigger to ${flow.name}`, [words, `Cards start in ${zone}.`, 'Work a card starts still waits for your usual approvals.'], { flowId: flow.id, trigger: config });
+        }
+        const made = addFlowTriggerTo(store, flow, input.value, who, now, context.configDir);
+        if (!made.ok)
+            return refuse(flow.repo, 'invalid-trigger', made.message);
+        record(flow.repo, 'accepted', `flow #${flow.id} trigger #${made.id}`);
+        settle(flow.repo);
+        // A webhook's address (and GitHub's signing secret) is shown this once, never stored readable.
+        return ok({ applied: true, triggerId: made.id, said: made.said, ...(made.reveal === null ? {} : { reveal: made.reveal }) }, [
+            `${made.said} Trigger #${made.id}: ${words}`,
+            ...(made.reveal === null ? [] : [`  address: ${made.reveal.address ?? `<your public address>${made.reveal.path}`}`, ...(made.reveal.secret === null ? [] : [`  signing secret: ${made.reveal.secret}`])]),
+        ]);
+    }
+    // trigger pause | resume | remove | check <flow> <trigger>
+    const trigger = args[1] !== undefined && /^[1-9][0-9]{0,9}$/.test(args[1]) ? store.getFlowTrigger(Number(args[1])) : null;
+    if (trigger === null || trigger.flow !== flow.id || trigger.state === 'removed')
+        return refuse(flow.repo, 'unknown-trigger', 'That trigger isn\'t on this flow. toolroll flows show <flow> names them.');
+    if (action === 'trigger check') {
+        const checked = await checkFlowTriggerNow(store, trigger, now, context.triggerIo);
+        record(flow.repo, checked.ok ? 'accepted' : 'refused', `flow #${flow.id} trigger #${trigger.id}`);
+        settle(flow.repo);
+        return checked.ok ? ok({ applied: true, triggerId: trigger.id, said: checked.said }, [checked.said]) : fail('check-failed', checked.said);
+    }
+    if (action === 'trigger remove')
+        removeFlowTrigger(store, trigger, now, context.configDir);
+    else
+        store.updateFlowTrigger(trigger.id, { state: action === 'trigger pause' ? 'paused' : 'active' }, now);
+    record(flow.repo, 'accepted', `flow #${flow.id} trigger #${trigger.id}`);
+    settle(flow.repo);
+    const said = action === 'trigger remove' ? 'Trigger removed.' : action === 'trigger pause' ? 'Trigger paused.' : 'Trigger on again.';
+    return ok({ applied: true, triggerId: trigger.id, said }, [said]);
+}
+function listed(store, flow) {
+    const definition = flowDefinitionOf(flow);
+    const cards = store.flowCards(flow.id, false);
+    return { id: flow.id, name: flow.name, repo: flow.repo, project: projectName(flow.repo), zones: definition?.stages.map(one => one.title) ?? [],
+        triggers: store.flowTriggers(flow.id).filter(one => one.state === 'active').length, cardsWaiting: cards.length,
+        needDecision: cards.filter(card => definition?.stages.find(one => one.id === card.stage)?.kind === 'approval').length };
+}
+/** One zone and every path out of it, by zone id. */
+function zoneOf(stage, flow) {
+    return {
+        id: stage.id, title: stage.title, kind: stage.kind, does: FLOW_KIND_WORDS[stage.kind].label,
+        next: stage.next, ifFails: stage.onFail,
+        ...(stage.sort === null ? {} : { answers: stage.sort.answers.map(one => ({ answer: one.answer, to: one.to })), sureAt: stage.sort.sureAt }),
+        ...(stage.routes === undefined || stage.routes.length === 0 ? {} : { routes: stage.routes.map(one => ({ answer: one.answer, to: one.to })) }),
+        ...(stage.limit === undefined ? {} : { remindAfterMinutes: stage.limit.minutes, thenMoveTo: stage.limit.to }),
+        ...(stage.kind === 'approval' ? { decider: deciderOf(stage, flow) } : {}),
+        ...(stage.script === null ? {} : { script: stage.script }),
+        ...(stage.merge === undefined ? {} : { merge: stage.merge }),
+        ...(stage.teammate === undefined ? {} : { teammate: stage.teammate }),
+    };
+}
+function cardOf(definition, card) {
+    return { id: card.id, title: card.title, zone: card.stage, zoneTitle: definition?.stages.find(one => one.id === card.stage)?.title ?? card.stage, state: card.state, waiting: card.waiting, task: card.task ?? card.primaryTask, updatedAt: card.updatedAt };
+}
+function describeFlow(store, flow) {
+    const definition = flowDefinitionOf(flow);
+    return {
+        id: flow.id, name: flow.name, repo: flow.repo, project: projectName(flow.repo), owner: flow.owner, revision: flow.revision, readable: definition !== null,
+        start: definition?.start ?? null,
+        zones: definition?.stages.map(stage => zoneOf(stage, flow)) ?? [],
+        triggers: store.flowTriggers(flow.id).map(trigger => {
+            const config = triggerConfigOf(trigger);
+            return { id: trigger.id, kind: trigger.kind, state: trigger.state, words: config === null ? 'This trigger can\'t be read.' : describeTrigger(config, store),
+                zone: config?.zone ?? definition?.start ?? null, nextAt: trigger.nextAt, lastAt: trigger.lastAt, lastOutcome: trigger.lastOutcome, failing: trigger.failures > 0 };
+        }),
+        cards: store.flowCards(flow.id, true).slice(0, 10).map(card => cardOf(definition, card)),
+    };
+}
+function showLines(flow) {
+    const title = (id) => id === null ? null : flow.zones.find(one => one.id === id)?.title ?? id;
+    if (!flow.readable)
+        return [`#${flow.id} ${flow.name} · ${flow.project}`, 'This flow\'s drawing can\'t be read. Save it again from the editor.'];
+    return [
+        `#${flow.id} ${flow.name} · ${flow.project} · owner ${flow.owner}`,
+        '', 'Zones',
+        ...flow.zones.flatMap((zone, index) => [
+            `  ${index + 1}. ${zone.title} (${zone.id}) — ${zone.does}${zone.id === flow.start ? ' · start' : ''}`,
+            ...('answers' in zone && zone.answers !== undefined ? zone.answers.map(one => `     ${one.answer} → ${title(one.to)}`) : []),
+            ...('routes' in zone && zone.routes !== undefined ? zone.routes.map(one => `     ${one.answer} → ${title(one.to)}`) : []),
+            ...(zone.next === null ? [] : [`     next → ${title(zone.next)}`]),
+            ...(zone.ifFails === null ? [] : [`     ${zone.kind === 'approval' ? 'sent back' : zone.kind === 'sort' ? 'not sure' : zone.kind === 'wait' ? 'no reply' : 'if it fails'} → ${title(zone.ifFails)}`]),
+        ]),
+        '', 'Triggers',
+        ...(flow.triggers.length === 0 ? ['  none — add one with toolroll flows trigger add'] : flow.triggers.map(one => `  #${one.id} ${one.state === 'active' ? '' : `(${one.state}) `}${one.words} → ${title(one.zone)}${one.lastOutcome === null ? '' : ` · last: ${one.lastOutcome}`}`)),
+        '', 'Recent cards',
+        ...(flow.cards.length === 0 ? ['  none'] : flow.cards.map(one => `  #${one.id} ${one.title} · ${one.state === 'active' ? one.zoneTitle : one.state}${one.waiting === null ? '' : ` · ${one.waiting}`}`)),
+    ];
+}

package/dist/flows-ui.js

@@ -130,7 +130,7 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
             zone: title(config?.zone ?? definition?.start ?? ""), zoneId: config?.zone ?? definition?.start ?? "", state: trigger.state, status: trigger.lastOutcome, statusAt: trigger.lastAt, failing: trigger.failures > 0,
             button: config?.kind === "button" ? { label: config.label, questions: config.questions } : null,
             hook: config !== null && takesDeliveries(config) ? { ready: hookReady(trigger, setup.dir), needsSecret: config.kind === "linear" } : null,
-            checkable: ((config?.kind === "github" || config?.kind === "linear") && config.delivery === "poll") || config?.kind === "email" || (config?.kind === "schedule" && config.script !== undefined),
+            checkable: ((config?.kind === "github" || config?.kind === "linear") && config.delivery === "poll") || config?.kind === "email" || (config?.kind === "schedule" && config.script !== undefined) || config?.kind === "plane-review",
             shared: config?.kind === "button" && trigger.hookHash !== null,
         };
     });

package/dist/flows.d.ts

@@ -150,18 +150,36 @@ export declare function deciderOf(stage: Pick<FlowStage, "approver" | "toOwner">
     owner: string;
 }): string | null;
 /** A flow as drawn on the canvas, checked whole. Throws in plain words. */
-export declare function validateFlowDefinition(input: unknown): FlowDefinition;
+/** `stored`: reading a flow saved earlier, which keeps working under rules added since (its cards say what's wrong). */
+export declare function validateFlowDefinition(input: unknown, options?: {
+    stored?: boolean;
+}): FlowDefinition;
 /** The zones a card can reach from `start` without passing through a zone `stop` picks (those zones aren't included). */
 export declare function reachableWithout(stages: readonly FlowStage[], start: string, stop: (stage: FlowStage) => boolean): Set<string>;
 /** What a card's work is held to: the zones' steps and paths, never where they sit on the canvas. */
 export declare function flowDigest(definition: FlowDefinition): string;
-/** Fill a zone's text from the card: title, description, the latest note and earlier zones' reports. */
-export declare function fillFlowText(template: string, card: {
+type FlowFillCard = {
     title: string;
     description: string | null;
     note: string | null;
     outputs: Record<string, string>;
-}, encode?: (value: string) => string): string;
+};
+/** Fill a zone's text from the card: title, description, the latest note and earlier zones' reports. */
+export declare function fillFlowText(template: string, card: FlowFillCard, encode?: (value: string) => string): string;
+/** The task door's goal limit (task-text.ts). A work zone's goal is kept under it. */
+export declare const FLOW_GOAL_LIMIT = 2000;
+/** What stands in for the middle of a filled-in value the goal had no room for. */
+export declare const FLOW_CUT = "\u2026 (cut; the full text is on the card)";
+/** A work zone's words, plus the card and any send-back note when the words leave them out. "Fix the bug on the card"
+ * says nothing on its own (found in the real e2e: the builder saw only the branch name). */
+export declare function flowWorkTemplate(instructions: string, card: {
+    description: string | null;
+    note: string | null;
+}): string;
+/** A work zone's goal, filled from the card and kept under FLOW_GOAL_LIMIT: the zone's own words stay whole, and only the
+ * filled-in values are shortened (the longest first), each keeping its start and end. Null when the words alone leave no
+ * room, which a saved flow can't have (validateFlowDefinition). */
+export declare function fitFlowText(template: string, card: FlowFillCard, limit?: number): string | null;
 /** The first email address a card mentions, or "" — what {{card.email}} holds. */
 export declare function cardEmailOf(card: {
     title: string;
@@ -231,6 +249,8 @@ export type FlowStepInput = {
 };
 /** What a draft zone asks for when the steps leave it out. */
 export declare const DRAFT_DEFAULT = "Write a short, friendly reply to the person who sent this card, in plain words.";
+/** Steps as the lead's flow tool and `toolroll flows` take them: "me" as a decider is the person asking, stored by name. */
+export declare function stepsFor(steps: unknown, name: string): unknown;
 /**
  * A flow from an ordered list of steps: ids from names, each step leading
  * to the next, a Done zone at the end when none is listed, and a decision
@@ -251,3 +271,4 @@ export declare const FLOW_TEMPLATES: readonly {
     definition: FlowDefinition;
     trigger?: Record<string, unknown>;
 }[];
+export {};

package/dist/flows.js

@@ -273,7 +273,8 @@ export function deciderOf(stage, flow) {
     return stage.toOwner === true ? flow.owner : stage.approver;
 }
 /** A flow as drawn on the canvas, checked whole. Throws in plain words. */
-export function validateFlowDefinition(input) {
+/** `stored`: reading a flow saved earlier, which keeps working under rules added since (its cards say what's wrong). */
+export function validateFlowDefinition(input, options = {}) {
     const raw = input;
     if (raw === null || typeof raw !== "object" || !Array.isArray(raw.stages))
         throw new Error("A flow is a list of zones.");
@@ -336,6 +337,11 @@ export function validateFlowDefinition(input) {
             throw new Error(`Zone ${stage.title}: an answer can't send cards back into the same zone.`);
         if ((stage.kind === "task" || stage.kind === "report") && stage.instructions === null)
             throw new Error(`Zone ${stage.title}: say what the agent should do.`);
+        // A work zone's goal must fit a task: its own words whole, with room left for the card's details. Refused here, when the flow
+        // is saved, never when a card arrives. A flow saved before this rule is still read, and its card says why it can't file.
+        const over = !options.stored && (stage.kind === "task" || stage.kind === "report") && stage.instructions !== null ? flowGoalOverflow(stage.instructions) : 0;
+        if (over > 0)
+            throw new Error(`Zone ${stage.title}: its instructions leave no room for the card's details. Shorten them by ${over} characters.`);
         if (stage.kind === "draft" && stage.instructions === null)
             throw new Error(`Zone ${stage.title}: say what Claude should write.`);
         if (stage.kind === "notify" && stage.message === null)
@@ -434,9 +440,72 @@ export function flowDigest(definition) {
     const terms = definition.stages.map(({ zone: _zone, ...rest }) => rest);
     return createHash("sha256").update(JSON.stringify({ start: definition.start, terms })).digest("hex").slice(0, 32);
 }
+const FILLED = /\{\{\s*(card\.title|card\.description|card\.email|note|stage\.([a-z0-9-]+))\s*\}\}/g;
 /** Fill a zone's text from the card: title, description, the latest note and earlier zones' reports. */
 export function fillFlowText(template, card, encode = value => value) {
-    return template.replace(/\{\{\s*(card\.title|card\.description|card\.email|note|stage\.([a-z0-9-]+))\s*\}\}/g, (_match, key, stage) => encode(fillOne(key, stage, card))).trim();
+    return template.replace(FILLED, (_match, key, stage) => encode(fillOne(key, stage, card))).trim();
+}
+/** The task door's goal limit (task-text.ts). A work zone's goal is kept under it. */
+export const FLOW_GOAL_LIMIT = 2000;
+/** What stands in for the middle of a filled-in value the goal had no room for. */
+export const FLOW_CUT = "… (cut; the full text is on the card)";
+/** The least room each filled-in value keeps: the cut mark and 20 characters from each end. */
+const VALUE_ROOM = FLOW_CUT.length + 40;
+/** A work zone's words, plus the card and any send-back note when the words leave them out. "Fix the bug on the card"
+ * says nothing on its own (found in the real e2e: the builder saw only the branch name). */
+export function flowWorkTemplate(instructions, card) {
+    const names = (key) => new RegExp(`\\{\\{\\s*${key.replace(".", "\\.")}\\s*\\}\\}`).test(instructions);
+    const extra = [
+        ...(names("card.title") || names("card.description") ? [] : [`The card: {{card.title}}${card.description ? "\n\n{{card.description}}" : ""}`]),
+        ...(names("card.title") && !names("card.description") && card.description ? ["Details on the card:\n{{card.description}}"] : []),
+        ...(names("note") || !card.note ? [] : ["Changes asked for: {{note}}"]),
+    ];
+    return [instructions, ...extra].join("\n\n");
+}
+/** Characters a work zone's instructions leave no room for, with every filled-in value kept to its least room. 0 when they fit. */
+function flowGoalOverflow(instructions) {
+    const widest = flowWorkTemplate(instructions, { description: "x", note: "x" });
+    const values = [...widest.matchAll(FILLED)].length;
+    return Math.max(0, widest.replace(FILLED, "").length + values * VALUE_ROOM - (FLOW_GOAL_LIMIT - 1));
+}
+/** Script output can carry carriage returns, colour codes and hidden marks a task goal refuses; the goal drops them. */
+const goalSafe = (value) => value.replace(/\r\n?/g, "\n").replace(/[\u0000-\u0008\u000B-\u001F\u007F-\u009F\u2028\u2029\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/g, "");
+/** A value kept to `room` characters: its start and end, with the cut mark between. */
+function cutToRoom(value, room) {
+    if (value.length <= room)
+        return value;
+    const keep = room - FLOW_CUT.length;
+    let head = Math.ceil(keep / 2), from = value.length - (keep - head);
+    if (/[\uD800-\uDBFF]/.test(value[head - 1] ?? ""))
+        head--;
+    if (/[\uDC00-\uDFFF]/.test(value[from] ?? ""))
+        from++;
+    return value.slice(0, head) + FLOW_CUT + value.slice(from);
+}
+/** A work zone's goal, filled from the card and kept under FLOW_GOAL_LIMIT: the zone's own words stay whole, and only the
+ * filled-in values are shortened (the longest first), each keeping its start and end. Null when the words alone leave no
+ * room, which a saved flow can't have (validateFlowDefinition). */
+export function fitFlowText(template, card, limit = FLOW_GOAL_LIMIT) {
+    const values = [...template.matchAll(FILLED)].map(match => goalSafe(fillOne(match[1], match[2], card)));
+    const room = limit - 1 - template.replace(FILLED, "").length;
+    let each = Math.max(0, ...values.map(one => one.length));
+    const used = (cap) => values.reduce((sum, one) => sum + Math.min(one.length, cap), 0);
+    if (used(each) > room) {
+        // The widest cap every value can share: the shortest values stay whole, the longest are cut to it.
+        let low = 0, high = each;
+        while (low < high) {
+            const mid = Math.ceil((low + high) / 2);
+            if (used(mid) <= room)
+                low = mid;
+            else
+                high = mid - 1;
+        }
+        each = low;
+        if (each < FLOW_CUT.length + 2)
+            return null;
+    }
+    let at = 0;
+    return template.replace(FILLED, () => cutToRoom(values[at++], each)).trim();
 }
 /** The first email address a card mentions, or "" — what {{card.email}} holds. */
 export function cardEmailOf(card) {
@@ -493,6 +562,10 @@ function defaultInstructions(kind, earlier) {
         ? `{{card.title}}\n\n{{card.description}}${notes}\n\nChanges asked for (if any): {{note}}`
         : `Investigate this and write a short, clear report with a summary first: {{card.title}}\n\n{{card.description}}${notes}\n\nFeedback to address (if any): {{note}}`;
 }
+/** Steps as the lead's flow tool and `toolroll flows` take them: "me" as a decider is the person asking, stored by name. */
+export function stepsFor(steps, name) {
+    return Array.isArray(steps) ? steps.map(step => step !== null && typeof step === "object" && typeof step.decider === "string" && /^(me|myself|i|you|the operator)$/i.test(step.decider.trim()) ? { ...step, decider: name } : step) : steps;
+}
 /**
  * A flow from an ordered list of steps: ids from names, each step leading
  * to the next, a Done zone at the end when none is listed, and a decision

package/dist/guides.js

@@ -79,6 +79,29 @@ ${AUTHORITY_LINE}
     detail says why; \`toolroll sync\` refreshes trackers.
   - \`contest-open\`: a tournament is running on the task; a person picks.
 
+## Flows
+
+A flow is a process cards move through, drawn as zones. The terminal
+applies the console's rules exactly.
+
+- Read: \`toolroll flows list [--repo PATH] --json\` (id, name, project,
+  zones, triggers, cards waiting) and \`flows show <id> --json\` (each
+  zone's \`next\` and \`ifFails\` paths, triggers, recent cards).
+- Change, as an approver (\`--as <you> --token <t>\`, or the remembered
+  login): \`flows create --repo PATH --name <n> (--template <id> |
+  --steps <file|->)\` — steps in the lead's flow-tool format, in order;
+  \`flows edit <id> --steps <file|->\`; \`flows trigger add <id> <json|file>\`;
+  \`flows trigger pause|resume|remove|check <id> <trigger>\`; \`flows script
+  save --repo PATH --name <n> (--file <path in project> | --body <file>)
+  --about "<line>"\`; \`flows card add <id> --title <t> [--zone <z>]\`;
+  \`flows archive <id>\`.
+- create, edit, archive and trigger add answer with a preview
+  (\`applied: false\`, \`terms\`) until \`--yes\`. Show the person the terms
+  and run \`--yes\` only when they asked for exactly that change.
+- Refusals: \`unknown-project\`, \`unknown-flow\`, \`invalid-steps\` (such as a
+  pull request that merges without a decision before it), \`invalid-trigger\`,
+  \`invalid-script\`, \`unauthenticated\`, \`stale\`.
+
 ## What you may never do
 
 - Never approve scopes, answer decisions, or acquire approver tokens —

package/dist/keys.js

@@ -87,7 +87,10 @@ export function readAuthModeStrict(provider, home = homedir()) {
         raw = readFileSync(authModeFileFor(provider, home), "utf8");
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        // Inside the agents' fence the keys folder is out of reach: Linux masks it (the file reads as absent), and macOS
+        // refuses it (EPERM), which reads the same way — a Toolroll a flow's check zone starts has only its CLIs' own sign-ins.
+        // Any other unreadable file (EACCES: its permissions) is still a stated problem.
+        if (error.code === "ENOENT" || error.code === "EPERM")
             return { ok: true, mode: DEFAULT_AUTH_MODE[provider] };
         return { ok: false, problem: `the ${provider} auth-mode file cannot be read (${error.code ?? "error"}) — run \`keys auth ${provider} subscription|api-key\` to restate it` };
     }