toolroll 0.9.0 → 0.9.2

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.d.ts

@@ -2,7 +2,7 @@
  * (the React view's data, plus a plain fallback page the view replaces). */
 import type { BrowserFlowView } from "./browser-workspace.js";
 import type { FlowRow, Store } from "./store.js";
-export declare const FLOWS_CSS = ".flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;gap:8px;margin:10px 0 0}@media(max-width:600px){.flows input,.flows select{font-size:16px}}";
+export declare const FLOWS_CSS = ".flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;gap:8px;margin:10px 0 0}@media(max-width:600px){.flows input,.flows select{font-size:16px}}@media(max-width:760px){.flows .card{padding:10px 12px;margin:8px 0;position:relative}.flows .flow-row{row-gap:2px}.flows .flow-row h2 a::after{content:\"\";position:absolute;inset:0;border-radius:inherit}.flows .flow-counts{line-height:1.35}}";
 /** The flows a person can open, with how many cards wait in each, and the new-flow form. */
 export declare function flowsListHtml(store: Store, flows: readonly FlowRow[], projects: readonly string[], csrf: string, canCreate: boolean, problem: string | null): string;
 /** One flow's canvas for one person. */

package/dist/flows-ui.js

@@ -13,7 +13,7 @@ import { callWords, receiptWords } from "./teammate-tools.js";
 import { undoFor } from "./teammate-week.js";
 const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 const projectName = (repo) => repo.split(/[\\/]/).filter(Boolean).pop() ?? repo;
-export const FLOWS_CSS = `.flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;gap:8px;margin:10px 0 0}@media(max-width:600px){.flows input,.flows select{font-size:16px}}`;
+export const FLOWS_CSS = `.flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;gap:8px;margin:10px 0 0}@media(max-width:600px){.flows input,.flows select{font-size:16px}}@media(max-width:760px){.flows .card{padding:10px 12px;margin:8px 0;position:relative}.flows .flow-row{row-gap:2px}.flows .flow-row h2 a::after{content:"";position:absolute;inset:0;border-radius:inherit}.flows .flow-counts{line-height:1.35}}`;
 /** The flows a person can open, with how many cards wait in each, and the new-flow form. */
 export function flowsListHtml(store, flows, projects, csrf, canCreate, problem) {
     const rows = flows.map(flow => {
@@ -71,11 +71,12 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
         const decision = parseSortDecision(decisions.get(card.id)?.decisionJson ?? null);
         const shown = stage?.kind === "approval" && definition !== null ? draftFor(definition, stage) : null;
         // v91: when a Wait zone gives up (or moves on), or a zone's time limit comes.
-        const clock = stage?.wait ?? stage?.limit;
+        // An "hours" wait has no deadline of its own: it goes on when the clock reaches its hours.
+        const clock = stage?.wait?.for === "hours" ? stage.limit : stage?.wait ?? stage?.limit;
         const until = card.state !== "active" || stage === undefined || clock === undefined ? null : new Date(Date.parse(store.flowCardEnteredAt(card.id) ?? card.updatedAt) + clock.minutes * 60_000);
         const deadline = until === null || until.getTime() <= Date.now() ? null : {
             at: until.toISOString(),
-            label: stage.wait !== undefined ? (stage.wait.for === "reply" ? "No reply by" : "Moves on at") : stage.limit.to !== null ? `Moves to ${title(stage.limit.to)} at` : "Reminder at",
+            label: stage.wait !== undefined && stage.wait.for !== "hours" ? (stage.wait.for === "reply" ? "No reply by" : "Moves on at") : stage.limit.to !== null ? `Moves to ${title(stage.limit.to)} at` : "Reminder at",
         };
         // Its open question: one of its own, or (v94) a tool call waiting for approval.
         const asked = card.state === "active" ? store.openTeammateQuestionOn(card.id, card.entry) : null;
@@ -129,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

@@ -1,4 +1,4 @@
-export declare const FLOW_STAGE_KINDS: readonly ["inbox", "task", "report", "approval", "check", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "done"];
+export declare const FLOW_STAGE_KINDS: readonly ["inbox", "task", "report", "approval", "check", "pull-request", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "done"];
 export type FlowStageKind = (typeof FLOW_STAGE_KINDS)[number];
 export declare const FLOW_COLORS: readonly ["slate", "blue", "violet", "amber", "green", "rose"];
 export type FlowColor = (typeof FLOW_COLORS)[number];
@@ -48,11 +48,18 @@ export type FlowTool = {
     name: string;
     args: string;
 };
-/** wait (v91): for a reply to the card's email (next: replied, onFail: no reply in time), or for a set time (then next). */
+/** wait (v91): for a reply to the card's email (next: replied, onFail: no reply in time), or for a set time (then next).
+ * "hours": until the clock is between `from` and `to` (like 22:00–06:00), in the computer's time zone unless one is named. */
 export type FlowWait = {
-    for: "reply" | "time";
+    for: "reply" | "time" | "hours";
     minutes: number;
+    from?: string;
+    to?: string;
+    timeZone?: string;
 };
+/** How a Pull request zone merges once checks pass. */
+export declare const FLOW_MERGE_METHODS: readonly ["squash", "merge", "rebase"];
+export type FlowMergeMethod = (typeof FLOW_MERGE_METHODS)[number];
 /** A time limit on a zone (v91): after this long, the person it waits on is reminded, and a Holding or
  * "Person decides" zone can move the card on (`to`). */
 export type FlowLimit = {
@@ -102,6 +109,8 @@ export type FlowStage = {
     teammate?: string;
     /** v96: a "Teammate handles it" zone sends what the teammate writes back to whoever asked (the person who added the card, its chat thread, or the teammate's manager). */
     reply?: boolean;
+    /** pull-request: merge once checks pass, this way. Only allowed after a "Person decides" zone, and a card merges only when a person approved it after it was built. */
+    merge?: FlowMergeMethod;
     /** Where a card goes when this zone's step succeeds, and when it fails or is sent back (sort: when it isn't sure). */
     next: string | null;
     onFail: string | null;
@@ -132,12 +141,18 @@ export declare const LONGEST_WAIT_MINUTES: number;
 export declare function durationMinutes(value: unknown): number | null;
 /** Minutes in the words people use: "3 days", "1 day 4 hours", "45 minutes". */
 export declare function durationWords(minutes: number): string;
+/** "22:00", "9:30" as "HH:MM"; null when it isn't a time of day. */
+export declare function clockTime(value: unknown): string | null;
+/** Whether a time falls inside an "hours" wait (22:00–06:00 runs past midnight), in its time zone or this computer's. */
+export declare function withinHours(wait: Pick<FlowWait, "from" | "to" | "timeZone">, now: Date): boolean;
 /** Who decides at an approval zone: its named person, the flow's owner, or null for anyone who approves on the project. */
 export declare function deciderOf(stage: Pick<FlowStage, "approver" | "toOwner">, flow: {
     owner: string;
 }): string | null;
 /** A flow as drawn on the canvas, checked whole. Throws in plain words. */
 export declare function validateFlowDefinition(input: unknown): 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. */
@@ -194,10 +209,15 @@ export type FlowStepInput = {
     server?: string;
     tool?: string;
     args?: Record<string, unknown> | string;
-    /** wait (v91): for a reply (the default) or a set time, and how long ("3 days"); where a card goes when no reply comes. */
-    waitFor?: "reply" | "time";
+    /** wait (v91): for a reply (the default) or a set time, and how long ("3 days"); where a card goes when no reply comes.
+     * "hours": until the clock is between `from` and `until` ("22:00", "06:00"). */
+    waitFor?: "reply" | "time" | "hours";
     wait?: string | number;
     ifNoReply?: string;
+    from?: string;
+    until?: string;
+    /** pull-request: merge once checks pass (true is squash). Needs a decision before it. */
+    merge?: boolean | FlowMergeMethod;
     /** Any step but wait and done (v91): remind after this long ("2 days"; "none" removes it), and on holding and approval steps, move the card to this step then. */
     remindAfter?: string | number;
     thenMoveTo?: string;
@@ -211,6 +231,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
@@ -220,10 +242,14 @@ export declare const DRAFT_DEFAULT = "Write a short, friendly reply to the perso
 export declare function flowFromSteps(input: unknown, previous?: FlowDefinition | null): FlowDefinition;
 /** What confirming a new or changed flow means, in the canvas's words: each step's job and path, what changed, and that the usual approvals still apply. */
 export declare function flowTerms(definition: FlowDefinition, previous: FlowDefinition | null): string[];
-/** Ready-made flows: the coding flow is the whole business process around a change. */
+/** The label an issue gets to become work: what the Issues to PRs template and the issue starter flow watch for. */
+export declare const ISSUE_LABEL = "toolroll";
+/** Ready-made flows: the coding flow is the whole business process around a change. A template's `trigger`
+ * (a trigger's settings, as flow-triggers.ts reads them) is added with it. */
 export declare const FLOW_TEMPLATES: readonly {
     id: string;
     label: string;
     about: string;
     definition: FlowDefinition;
+    trigger?: Record<string, unknown>;
 }[];