toolroll 0.9.1 → 0.9.2

package/dist/cli.js

@@ -85,6 +85,8 @@ and any queue command + --help prints it too
   toolroll heartbeat <lease> / release <lease> / reap
   toolroll tick --runner <name> --token <t> --repo <path>
                                one unattended pass over the ready set
+  toolroll flows list | show <id> | create | edit | trigger | script | card | archive
+                               set up and inspect flows (writes preview until --yes)
   toolroll chat --as <you> --token <t>
                                talk to the mate: one conversation across every
                                project; it proposes, you confirm (--say "…" for one turn)
@@ -239,6 +241,7 @@ export const OPERATE_COMMANDS = new Set([
     "publish",
     "reconcile",
     "routine",
+    "flows",
     "config", "chat", "proposals", "mode", "people", "keys",
     "setup",
     "verify",

package/dist/desktop-update.d.ts

@@ -66,7 +66,6 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
-    version?: never;
     active: boolean;
     phase: string;
     detail: string;
@@ -80,6 +79,7 @@ export declare function desktopUpdateStatus(stateDir: string): {
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
+    version?: never;
     buildId?: never;
     workDir?: never;
 } | {

package/dist/flow-insights.d.ts

@@ -88,6 +88,15 @@ export type FlowInsights = {
     scripts: ScriptInsight[];
     sorts: SortInsight[];
     runs: StepRunInsight[];
+    /** A plane review's problems, the ones seen on the most days first: which causes keep coming back. */
+    recurring: RecurringProblem[];
+};
+export type RecurringProblem = {
+    problem: string;
+    title: string;
+    days: number;
+    lastSeen: string;
+    card: number | null;
 };
 /** One flow's insights over the last `days` days. */
 export declare function flowInsights(store: Store, flow: FlowRow, now: Date, days?: number): FlowInsights;

package/dist/flow-insights.js

@@ -83,12 +83,28 @@ export function flowInsights(store, flow, now, days = 30) {
             .map(one => ({ zone: one.zone, title: one.title, problems: one.failed + one.sentBack, of: Math.max(one.entered, one.failed + one.sentBack) })),
         scripts: [...scripts].map(([script, one]) => ({ script, runs: one.runs, passed: one.passed, failed: one.failed, typicalSeconds: median(one.durations) === null ? null : Math.round(median(one.durations)), lastFailure: one.lastFailure })),
         sorts,
+        recurring: recurringProblems(store, flow, since),
         runs: runs.slice(0, 40).map(run => ({
             card: run.card, cardTitle: run.cardTitle, entry: run.entry, zone: run.stage, zoneTitle: titleOf(run.stage), kind: run.kind, script: run.script, version: run.scriptVersion,
             state: run.state, result: run.result, exitCode: run.exitCode, durationMs: run.durationMs, at: run.finishedAt ?? run.startedAt, hasLog: run.log !== null && run.log !== "",
         })),
     };
 }
+/** Each problem a plane review trigger of this flow noted in the window (one note per problem a day), and on how many days. */
+function recurringProblems(store, flow, since) {
+    const rows = store.handle.prepare(`SELECT e.key, e.card, e.at, c.title FROM flow_trigger_event e JOIN flow_trigger t ON t.id = e.trigger LEFT JOIN flow_card c ON c.id = e.card
+    WHERE t.flow = ? AND json_extract(t.config_json, '$.kind') = 'plane-review' AND substr(e.key, 1, 6) = 'plane:' AND e.at >= ? ORDER BY e.rowid`).all(flow.id, since.toISOString());
+    const problems = new Map();
+    for (const row of rows) {
+        const match = /^plane:(.+):(\d{4}-\d{2}-\d{2})$/.exec(String(row["key"]));
+        if (match === null)
+            continue;
+        const had = problems.get(match[1]);
+        const card = row["card"] === null ? had?.card ?? null : Number(row["card"]);
+        problems.set(match[1], { problem: match[1], title: row["title"] === null ? had?.title ?? match[1] : String(row["title"]), days: (had?.days ?? 0) + 1, lastSeen: match[2], card });
+    }
+    return [...problems.values()].sort((a, b) => b.days - a.days || b.lastSeen.localeCompare(a.lastSeen)).slice(0, 20);
+}
 const BANDS = [[90, 101], [80, 90], [70, 80], [50, 70]];
 function sortInsight(stage, runs, byCard) {
     const sort = stage.sort;

package/dist/flow-starters.d.ts

@@ -1,6 +1,6 @@
 import { type FlowStepInput } from "./flows.js";
 import type { FlowRow, Store } from "./store.js";
-export declare const STARTER_IDS: readonly ["ci-fix", "issue-task", "overnight"];
+export declare const STARTER_IDS: readonly ["ci-fix", "issue-task", "overnight", "plane-review"];
 export type StarterId = (typeof STARTER_IDS)[number];
 export type StarterFlow = {
     id: StarterId;
@@ -12,16 +12,21 @@ export type StarterFlow = {
     does: (where: {
         github: string | null;
         branch: string;
+        own: boolean;
     }) => string[];
     /** What it never does. */
     never: string;
     github: boolean;
     steps: FlowStepInput[];
+    /** The steps in Toolroll's own repository, when they differ: there, every fix lands in Toolroll. */
+    ownSteps?: FlowStepInput[];
     trigger: (where: {
         branch: string;
     }) => Record<string, unknown>;
 };
 export declare const STARTER_FLOWS: readonly StarterFlow[];
+/** Whether a project is Toolroll's own source. */
+export declare function isToolrollRepo(repo: string): boolean;
 export declare const starterOf: (id: string) => StarterFlow | null;
 /** The flow a starter made in a project, while it is on. */
 export declare function starterFlowOf(store: Store, starter: StarterFlow, repo: string): FlowRow | null;

package/dist/flow-starters.js

@@ -4,11 +4,13 @@
  * 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";
 import { addFlowTriggerTo, githubRepoOf } from "./flow-triggers.js";
 import { flowFromSteps, ISSUE_LABEL } from "./flows.js";
 import { publishingOf } from "./pull-request-flow.js";
-export const STARTER_IDS = ["ci-fix", "issue-task", "overnight"];
+export const STARTER_IDS = ["ci-fix", "issue-task", "overnight", "plane-review"];
 export const STARTER_FLOWS = [
     {
         id: "ci-fix",
@@ -51,7 +53,47 @@ export const STARTER_FLOWS = [
         ],
         trigger: () => ({ kind: "button", label: "Queue for tonight", questions: ["What needs doing?", "Details"] }),
     },
+    {
+        id: "plane-review",
+        name: "Morning plane review",
+        summary: "What went wrong in Toolroll yesterday becomes cards, researched and fixed.",
+        does: ({ own }) => [
+            "Every day at 07:30, looks at failed runs, waiting tasks, sign-ins, plan limits, chat, integrations and checks.",
+            "One card per problem; one that comes back joins its card. A clean day adds nothing.",
+            own ? "Finds the cause in Toolroll's code, builds a fix under your usual approvals, and opens a pull request."
+                : "Finds the cause. One in this project gets a fix under your usual approvals and a pull request; one in Toolroll's settings gets a note of what to change.",
+            "Anything that fails waits in “Needs a look”.",
+        ],
+        never: "Never merges or ships anything without you. Each fix waits for your approval.",
+        github: false,
+        steps: planeReviewSteps(false),
+        ownSteps: planeReviewSteps(true),
+        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. */
+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."
+        : "This project uses Toolroll; it isn't Toolroll's own code. Find the root cause. If it is in this project's code, cite the files and lines and say what change fixes it. If it is in Toolroll or its settings (a sign-in, a plan limit, a chat app, an integration, the worker), say exactly what to change in Toolroll's settings, and start the report with “No build needed”.";
+    return [
+        { id: "find-cause", title: "Find the cause", kind: "report", ifFails: "needs-a-look",
+            instructions: `The morning plane review found a problem: {{card.title}}\n\n{{card.description}}\n\n${where}\n\nFeedback to address (if any): {{note}}` },
+        { id: "fix", title: "Fix it", kind: "task", ifFails: "needs-a-look",
+            instructions: `Fix the root cause of this problem, with a regression check where one fits: {{card.title}}\n\nThe report:\n{{stage.find-cause}}${own ? "" : "\n\nIf the report says “No build needed”, the cause is outside this project: change nothing and say so."}\n\nChanges asked for (if any): {{note}}` },
+        { id: "pull-request", title: "Pull request", kind: "pull-request", next: "done", ifFails: "needs-a-look" },
+        { id: "needs-a-look", title: "Needs a look", kind: "inbox", next: "done" },
+    ];
+}
+/** Whether a project is Toolroll's own source. */
+export function isToolrollRepo(repo) {
+    try {
+        return JSON.parse(readFileSync(join(repo, "package.json"), "utf8")).name === "toolroll";
+    }
+    catch {
+        return false;
+    }
+}
 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) {
@@ -64,7 +106,7 @@ export function startersFor(store, repo) {
     const branch = publishing.on ? publishing.base : "main";
     return STARTER_FLOWS.map(starter => {
         const flow = starterFlowOf(store, starter, repo);
-        return { id: starter.id, name: starter.name, summary: starter.summary, does: starter.does({ github, branch }), never: starter.never,
+        return { id: starter.id, name: starter.name, summary: starter.summary, does: starter.does({ github, branch, own: isToolrollRepo(repo) }), never: starter.never,
             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 };
     });
 }
@@ -78,7 +120,8 @@ export function switchOnStarter(store, starter, repo, by, now, dir) {
     const publishing = publishingOf(store, repo);
     try {
         const flow = store.transact(() => {
-            const id = store.createFlow({ repo, name: starter.name, definitionJson: JSON.stringify(flowFromSteps(starter.steps, null)), by }, now);
+            const steps = starter.ownSteps !== undefined && isToolrollRepo(repo) ? starter.ownSteps : starter.steps;
+            const id = store.createFlow({ repo, name: starter.name, definitionJson: JSON.stringify(flowFromSteps(steps, null)), by }, now);
             const made = store.getFlow(id);
             const trigger = addFlowTriggerTo(store, made, { ...starter.trigger({ branch: publishing.on ? publishing.base : "main" }), zone: flowDefinitionOf(made).start }, by, now, dir);
             if (!trigger.ok)

package/dist/flow-triggers.d.ts

@@ -3,7 +3,7 @@ import { type FlowAct } from "./flow-engine.js";
 import type { FlowDefinition } from "./flows.js";
 import { type MailReader } from "./mailbox.js";
 import type { FlowCardSource, FlowRow, FlowTriggerRow, Store } from "./store.js";
-export declare const FLOW_TRIGGER_KINDS: readonly ["button", "schedule", "github", "linear", "flow", "webhook", "email", "chat"];
+export declare const FLOW_TRIGGER_KINDS: readonly ["button", "schedule", "github", "linear", "flow", "webhook", "email", "chat", "plane-review"];
 export type FlowTriggerKind = (typeof FLOW_TRIGGER_KINDS)[number];
 export type TriggerConfig = {
     kind: "button";
@@ -64,6 +64,12 @@ export type TriggerConfig = {
     chat: string;
     binding: number;
     zone: string | null;
+}
+/** `schedule`: always daily, in the routines' form ("daily:07:30@Europe/London"). */
+ | {
+    kind: "plane-review";
+    schedule: string;
+    zone: string | null;
 };
 export type ChatApp = "slack" | "discord" | "teams" | "telegram";
 export declare const CHAT_APP_NAMES: Record<ChatApp, string>;
@@ -180,6 +186,19 @@ export declare function checkFlowTriggerNow(store: Store, trigger: FlowTriggerRo
     ok: boolean;
     said: string;
 }>;
+/**
+ * A plane review: the last 24 hours, one card per problem worth fixing. Each problem is noted once a day; a problem
+ * whose card is still open joins it (a note with the day's counts and evidence) instead of making another, and one
+ * whose card is finished starts a new card, since it came back. A clean day adds nothing and tells nobody.
+ * `scheduled` moves the trigger to its next morning; "Run now" leaves its times alone.
+ */
+export declare function firePlaneReview(store: Store, trigger: FlowTriggerRow, config: Extract<TriggerConfig, {
+    kind: "plane-review";
+}>, now: Date, scheduled: boolean): Promise<{
+    added: number;
+    joined: number;
+    said: string;
+}>;
 /** v96: a schedule (a teammate's routine) makes its card now, once per press, and keeps its own times. */
 export declare function runScheduleNow(store: Store, trigger: FlowTriggerRow, actor: string, now: Date): {
     ok: true;

package/dist/flow-triggers.js

@@ -13,6 +13,11 @@
  *              read-only over IMAP; optionally only from some senders or with words in the subject.
  * - chat     — messages in a Slack, Discord or Teams channel (v89), connected from the
  *              channel itself (chat-inbox.ts), never from here.
+ * - plane-review — every day at a set time (07:30 in the computer's time zone unless it says),
+ *              the plane's last 24 hours read straight from the store (plane-review.ts): one card
+ *              per distinct problem worth fixing, and the same problem on a later day joins its
+ *              card while that card is still open. A clean day makes nothing. Its row is kept as a
+ *              'schedule' (the table's kinds are fixed); its settings say what it is.
  *
  * GitHub and Linear are checked by the worker's pass — `gh` and one HTTPS
  * request, never a model — or pushed to a secret webhook address when the
@@ -32,11 +37,11 @@ import { mailboxAccess, mailCursorOf, mailCursorText, readThroughImap } from "./
 import { readFlowSecrets } from "./flow-secrets.js";
 import { tmpdir } from "node:os";
 import { envValue } from "./names.js";
-export const FLOW_TRIGGER_KINDS = ["button", "schedule", "github", "linear", "flow", "webhook", "email", "chat"];
+export const FLOW_TRIGGER_KINDS = ["button", "schedule", "github", "linear", "flow", "webhook", "email", "chat", "plane-review"];
 export const CHAT_APP_NAMES = { slack: "Slack", discord: "Discord", teams: "Teams", telegram: "Telegram" };
 /** What each kind is called on the canvas. */
 export const FLOW_TRIGGER_WORDS = {
-    button: "Button", schedule: "Schedule", github: "GitHub", linear: "Linear", flow: "Another flow", webhook: "Webhook", email: "Email inbox", chat: "Chat channel",
+    button: "Button", schedule: "Schedule", github: "GitHub", linear: "Linear", flow: "Another flow", webhook: "Webhook", email: "Email inbox", chat: "Chat channel", "plane-review": "Plane review",
 };
 /** How often the worker checks GitHub and Linear, and how it backs off when they don't answer. */
 export const POLL_EVERY_MS = 2 * 60_000;
@@ -116,7 +121,7 @@ export function validateTriggerConfig(raw, context) {
     const input = raw;
     const kind = input["kind"];
     if (!FLOW_TRIGGER_KINDS.includes(kind))
-        throw new Error("Choose what starts cards: a button, a schedule, GitHub, Linear, another flow, a webhook, an email inbox or a chat channel.");
+        throw new Error("Choose what starts cards: a button, a schedule, GitHub, Linear, another flow, a webhook, an email inbox, a chat channel or a plane review.");
     const named = words(input, "zone", 60, false);
     const zoneStage = named === null ? null : context.definition.stages.find(one => one.id === named || one.title.toLowerCase() === named.toLowerCase());
     if (named !== null && zoneStage === undefined)
@@ -199,6 +204,15 @@ export function validateTriggerConfig(raw, context) {
         case "chat":
             // Connecting a channel proves it's one the person is in: it happens in the channel, not here.
             throw new Error(`Connect a chat channel from the channel itself: where Toolroll is in Slack, Discord, Teams or a Telegram group, send “flow ${context.flow.id}”.`);
+        case "plane-review": {
+            const at = words(input, "at", 5, false) ?? "07:30";
+            const clock = /^(\d{1,2}):(\d{2})$/.exec(at);
+            const zoneName = words(input, "timeZone", 60, false) ?? localTimeZone();
+            const schedule = clock === null ? null : scheduleFromWords(`daily ${clock[1]}:${clock[2]} ${zoneName}`);
+            if (schedule === null)
+                throw new Error("Say the time it reviews the day as HH:MM, like 07:30, and a time zone like Europe/London.");
+            return { kind: "plane-review", schedule, zone };
+        }
         case "email": {
             const folder = words(input, "folder", 100, false) ?? "INBOX";
             const sender = words(input, "sender", 300, false);
@@ -208,6 +222,15 @@ export function validateTriggerConfig(raw, context) {
         }
     }
 }
+/** The computer's time zone, as the routines name one. */
+function localTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
 /** Addresses and domains from "priya@example.com, @shop.com, example.org". */
 function sendersOf(text) {
     return [...new Set(text.split(/[\s,;]+/).map(one => one.trim().toLowerCase().replace(/^@/, "")).filter(one => /^([a-z0-9._%+-]+@)?[a-z0-9-]+(\.[a-z0-9-]+)*\.[a-z]{2,}$/.test(one)))].slice(0, 20);
@@ -243,6 +266,10 @@ export function describeTrigger(config, store) {
         }
         case "webhook": return "Anything posted to its webhook address";
         case "chat": return `Every new message in a ${CHAT_APP_NAMES[config.app]} channel; replies in a card's thread join its discussion`;
+        case "plane-review": {
+            const schedule = parseSchedule(config.schedule);
+            return `Every day at ${schedule !== null && schedule.kind !== "every" ? schedule.hhmm : config.schedule}: reviews the last 24 hours of runs, tasks, sign-ins, chat, integrations and checks, and makes a card for each problem worth fixing`;
+        }
         case "email": return `Email arriving in ${config.folder === "INBOX" ? "the inbox" : config.folder}${config.sender === null ? "" : ` from ${config.sender}`}${config.subject === null ? "" : ` with “${config.subject}” in the subject`} (checked every 2 minutes)`;
     }
 }
@@ -263,6 +290,10 @@ export function triggerHeadline(config, store) {
         }
         case "webhook": return { name: "Webhook", detail: "Anything posted to its address" };
         case "chat": return { name: `${CHAT_APP_NAMES[config.app]} channel`, detail: "Each message is a card" };
+        case "plane-review": {
+            const schedule = parseSchedule(config.schedule);
+            return { name: `Plane review at ${schedule !== null && schedule.kind !== "every" ? schedule.hhmm : "a set time"}`, detail: "Problems from the last 24 hours" };
+        }
         case "email": return { name: config.folder === "INBOX" ? "New email" : `New email in ${config.folder}`, detail: config.sender !== null ? `From ${config.sender}` : config.subject !== null ? `Subject has “${config.subject}”` : "Email inbox" };
     }
 }
@@ -370,9 +401,10 @@ export function addFlowTriggerTo(store, flow, raw, actor, now, dir) {
     if (takesDeliveries(config) && dir === null)
         return { ok: false, message: "Webhook addresses are set up on the console." };
     const token = takesDeliveries(config) ? randomBytes(24).toString("base64url") : null;
-    const schedule = config.kind === "schedule" ? parseSchedule(config.schedule) : null;
+    const schedule = config.kind === "schedule" || config.kind === "plane-review" ? parseSchedule(config.schedule) : null;
     const id = store.addFlowTrigger({
-        flow: flow.id, kind: config.kind, configJson: JSON.stringify(config), hookHash: token === null ? null : hookHash(token),
+        // The table's kinds were fixed before plane reviews: one is kept as the daily schedule it is.
+        flow: flow.id, kind: config.kind === "plane-review" ? "schedule" : config.kind, configJson: JSON.stringify(config), hookHash: token === null ? null : hookHash(token),
         // Only what happens from now on: never the backlog of issues, runs or finished cards.
         cursor: config.kind === "flow" ? String(store.latestFlowEvent()) : config.kind === "github" || config.kind === "linear" ? now.toISOString() : null,
         // Email: the first check notes where the mailbox stands (no cursor yet), so only mail after this becomes cards.
@@ -484,6 +516,8 @@ export async function runFlowTriggers(store, repo, now, io) {
             }
             else if (config.kind === "schedule" && trigger.nextAt !== null && Date.parse(trigger.nextAt) <= now.getTime())
                 pass.added += fireSchedule(store, trigger, config, now);
+            else if (config.kind === "plane-review" && trigger.nextAt !== null && Date.parse(trigger.nextAt) <= now.getTime())
+                pass.added += (await firePlaneReview(store, trigger, config, now, true)).added;
             else if (config.kind === "flow")
                 pass.added += followFlow(store, trigger, config, now);
             else if (polled(config) && (trigger.nextAt === null || Date.parse(trigger.nextAt) <= now.getTime())) {
@@ -508,8 +542,12 @@ export async function checkFlowTriggerNow(store, trigger, now, io) {
         const fired = await fireScript(store, trigger, config, now, io, false);
         return { ok: fired.ok, said: fired.said };
     }
+    if (config?.kind === "plane-review") {
+        const fired = await firePlaneReview(store, trigger, config, now, false);
+        return { ok: true, said: fired.said };
+    }
     if (config === null || !polled(config))
-        return { ok: false, said: "Only GitHub, Linear and email triggers that are checked, and schedules that run a script, can be run now." };
+        return { ok: false, said: "Only GitHub, Linear and email triggers that are checked, schedules that run a script, and plane reviews can be run now." };
     const checked = await checkTrigger(store, trigger, config, now, io);
     return { ok: checked.ok, said: checked.said };
 }
@@ -536,6 +574,67 @@ function fireSchedule(store, trigger, config, now) {
     store.updateFlowTrigger(trigger.id, { nextAt: next, lastAt: now.toISOString(), lastOutcome: made.made === "added" ? "Added a card." : made.note ?? "Nothing new." }, now);
     return made.made === "added" ? 1 : 0;
 }
+/** The problem a plane review's event key names, and the day: `plane:<problem>:<YYYY-MM-DD>`. */
+const planeKey = (problem, day) => `plane:${problem}:${day}`;
+/** The card a plane review last made or joined for one problem, if any. */
+function planeCardOf(store, trigger, problem) {
+    const prefix = `plane:${problem}:`;
+    const row = store.handle.prepare("SELECT card FROM flow_trigger_event WHERE trigger = ? AND substr(key, 1, ?) = ? AND card IS NOT NULL ORDER BY rowid DESC LIMIT 1").get(trigger, prefix.length, prefix);
+    return row === undefined ? null : Number(row["card"]);
+}
+/**
+ * A plane review: the last 24 hours, one card per problem worth fixing. Each problem is noted once a day; a problem
+ * whose card is still open joins it (a note with the day's counts and evidence) instead of making another, and one
+ * whose card is finished starts a new card, since it came back. A clean day adds nothing and tells nobody.
+ * `scheduled` moves the trigger to its next morning; "Run now" leaves its times alone.
+ */
+export async function firePlaneReview(store, trigger, config, now, scheduled) {
+    const schedule = parseSchedule(config.schedule);
+    const next = scheduled && schedule !== null && trigger.nextAt !== null ? nextFireAt(schedule, trigger.nextAt, now) : trigger.nextAt;
+    const flow = store.getFlow(trigger.flow);
+    const done = (said, added = 0, joined = 0) => {
+        store.updateFlowTrigger(trigger.id, { nextAt: next, lastAt: now.toISOString(), lastOutcome: said }, now);
+        return { added, joined, said };
+    };
+    if (flow === null || flow.state !== "active")
+        return done("The flow isn't active.");
+    // Loaded when a review first runs: the reader reaches the integrations and task status, which reach back to these triggers.
+    const { problemCard, problemText, reviewPlane } = await import("./plane-review.js");
+    // Only the projects the flow's owner may see: a flow's cards are read by everyone on its project.
+    const owner = store.accountOf(flow.owner);
+    const problems = reviewPlane(store, now, repo => owner === null || (repo !== null && store.accountCanAccess(flow.owner, repo)) || (repo === null && owner.projects === null));
+    const timeZone = schedule !== null && schedule.kind !== "every" ? schedule.timezone ?? "UTC" : "UTC";
+    const day = new Intl.DateTimeFormat("en-CA", { year: "numeric", month: "2-digit", day: "2-digit", timeZone }).format(now);
+    const dayWords = new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone }).format(now);
+    let added = 0, joined = 0;
+    const skipped = [];
+    for (const problem of problems) {
+        const key = planeKey(problem.key, day);
+        if (store.flowTriggerSaw(trigger.id, key))
+            continue;
+        const had = planeCardOf(store, trigger.id, problem.key);
+        const card = had === null ? null : store.getFlowCard(had);
+        if (card !== null && card.state === "active") {
+            store.transact(() => {
+                store.addFlowComment({ card: card.id, author: "Plane review", body: `Again — ${problemText(problem, dayWords)}`.slice(0, 4000), mentions: [] }, now);
+                store.recordFlowTriggerEvent(trigger.id, key, card.id, problem.summary, now);
+            });
+            joined++;
+            continue;
+        }
+        const text = problemCard(problem, dayWords);
+        const made = makeCard(store, trigger, config, { key, title: text.title, description: text.description, source: { kind: "plane-review", label: "Plane review", url: null } }, "Plane review", now);
+        if (made.made === "added")
+            added++;
+        else if (made.note !== null)
+            skipped.push(made.note);
+    }
+    if (problems.length === 0)
+        return done("A clean day: nothing to fix.");
+    const parts = [added > 0 ? `Added ${plural(added, "card")}.` : null, joined > 0 ? `${plural(joined, "problem")} came back and joined ${joined === 1 ? "its card" : "their cards"}.` : null,
+        skipped.length > 0 ? `Left out ${plural(skipped.length, "problem")}: ${skipped[0]}.` : null].filter(one => one !== null);
+    return done(parts.length === 0 ? "Nothing new since this morning's review." : parts.join(" "), added, joined);
+}
 /** v96: a schedule (a teammate's routine) makes its card now, once per press, and keeps its own times. */
 export function runScheduleNow(store, trigger, actor, now) {
     const config = triggerConfigOf(trigger);

package/dist/flows-cli.d.ts

@@ -0,0 +1,228 @@
+import { type TriggerIo } from './flow-triggers.js';
+import type { Store } from './store.js';
+export declare const FLOWS_DESCRIPTORS: readonly [{
+    readonly action: 'list';
+    readonly synopsis: 'list flows: id, name, project, zones, triggers and cards waiting';
+    readonly mutation: 'none';
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }];
+}, {
+    readonly action: 'show';
+    readonly synopsis: 'one flow: zones with their next and failure paths, triggers and recent cards';
+    readonly mutation: 'none';
+    readonly positionals: readonly ['flow'];
+    readonly flags: {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[];
+}, {
+    readonly action: 'create';
+    readonly synopsis: 'create a flow from --template <id> (a template or starter flow) or --steps <file|->; previews until --yes';
+    readonly mutation: 'unkeyed';
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }, {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }, {
+        readonly name: 'name';
+        readonly takesValue: true;
+        readonly meaning: "the flow's name (a template's label when left out)";
+    }, {
+        readonly name: 'template';
+        readonly takesValue: true;
+        readonly meaning: `one of ${string}`;
+    }, {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }];
+}, {
+    readonly action: 'edit';
+    readonly synopsis: "replace a flow's steps (kept steps by id) and optionally rename it; previews until --yes";
+    readonly mutation: 'unkeyed';
+    readonly positionals: readonly ['flow'];
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }, {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }, {
+        readonly name: 'name';
+        readonly takesValue: true;
+        readonly meaning: 'a new name';
+    }];
+}, {
+    readonly action: 'trigger add';
+    readonly synopsis: 'add a trigger from JSON or a JSON file (any kind: button, schedule, github, linear, flow, webhook, email, chat); previews until --yes';
+    readonly mutation: 'unkeyed';
+    readonly positionals: readonly ['flow', 'trigger'];
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }];
+}, {
+    readonly action: 'trigger pause';
+    readonly synopsis: 'pause a trigger';
+    readonly mutation: 'identity-idempotent';
+    readonly positionals: readonly ['flow', 'trigger'];
+    readonly flags: {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[];
+}, {
+    readonly action: 'trigger resume';
+    readonly synopsis: 'turn a paused trigger on again';
+    readonly mutation: 'identity-idempotent';
+    readonly positionals: readonly ['flow', 'trigger'];
+    readonly flags: {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[];
+}, {
+    readonly action: 'trigger remove';
+    readonly synopsis: 'remove a trigger; cards it added stay';
+    readonly mutation: 'identity-idempotent';
+    readonly positionals: readonly ['flow', 'trigger'];
+    readonly flags: {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[];
+}, {
+    readonly action: 'trigger check';
+    readonly synopsis: 'run a checked trigger (or a schedule\'s script) now, like Check now';
+    readonly mutation: 'unkeyed';
+    readonly positionals: readonly ['flow', 'trigger'];
+    readonly flags: {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[];
+}, {
+    readonly action: 'script save';
+    readonly synopsis: "save a project script (a new version when it exists)";
+    readonly mutation: 'identity-idempotent';
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }, {
+        readonly name: 'name';
+        readonly takesValue: true;
+        readonly meaning: 'lowercase letters, numbers and dashes';
+    }, {
+        readonly name: 'file';
+        readonly takesValue: true;
+        readonly meaning: 'run this path in the project';
+    }, {
+        readonly name: 'body';
+        readonly takesValue: true;
+        readonly meaning: 'a local file holding the script itself';
+    }, {
+        readonly name: 'about';
+        readonly takesValue: true;
+        readonly meaning: 'one line: what it checks or does';
+    }, {
+        readonly name: 'language';
+        readonly takesValue: true;
+        readonly meaning: 'shell (default), python or node';
+    }, {
+        readonly name: 'timeout-minutes';
+        readonly takesValue: true;
+        readonly meaning: '1 to 60 (default 15)';
+    }];
+}, {
+    readonly action: 'card add';
+    readonly synopsis: 'add a card, in the first zone unless --zone names one';
+    readonly mutation: 'unkeyed';
+    readonly positionals: readonly ['flow'];
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        readonly name: 'title';
+        readonly takesValue: true;
+        readonly meaning: "the card's title";
+    }, {
+        readonly name: 'description';
+        readonly takesValue: true;
+        readonly meaning: 'its details';
+    }, {
+        readonly name: 'zone';
+        readonly takesValue: true;
+        readonly meaning: 'a zone id or name';
+    }];
+}, {
+    readonly action: 'archive';
+    readonly synopsis: 'archive a flow: its cards stop moving and its triggers stop; previews until --yes';
+    readonly mutation: 'identity-idempotent';
+    readonly positionals: readonly ['flow'];
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }];
+}];
+/** `--file` is a value here (a path in the project), where elsewhere it is a switch. */
+export declare const FLOWS_VALUE_FLAGS: ReadonlySet<string>;
+export type FlowsCliContext = {
+    store: Store;
+    write: (line: string) => void;
+    json: boolean;
+    clock: () => Date;
+    /** --as/--token, or the remembered login; null when neither. */
+    credentials: {
+        name: string;
+        token: string;
+    } | null;
+    /** Every project the installation knows (enrolled, opened or worked on). */
+    projects: readonly string[];
+    /** Beside the database: webhook secrets, the hooks address. */
+    configDir: string;
+    evidenceRoot: string;
+    triggerIo: TriggerIo;
+    /** Reads a file, or stdin for "-". */
+    readInput?: (path: string) => string;
+};
+type Flags = Map<string, string | true>;
+export declare function runFlowsCommand(positional: readonly string[], flags: Flags, context: FlowsCliContext): Promise<number>;
+export {};