toolroll 0.8.2 → 0.9.1

package/dist/flows.js

@@ -30,14 +30,21 @@
  *               {{card.email}} is the first address the card mentions.
  * - tool      — (v87) calls one tool of one of the project's MCP servers
  *               (Settings → Tools), with arguments filled from the card.
+ * - pull-request — opens a pull request for the card's built result under
+ *               the project's pull request setup (flow-pull-request.ts),
+ *               waits for CI, and moves on when it passes or down the
+ *               failure path, naming the failing check, when it fails. It
+ *               can merge once checks pass, only after a person approved.
  * - done      — the end.
  *
  * The engine is deterministic and model-free: it runs in the worker's pass
  * beside routines, and no card ever skips an approval the task itself needs.
  */
 import { createHash } from "node:crypto";
-export const FLOW_STAGE_KINDS = ["inbox", "task", "report", "approval", "check", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "done"];
+export const FLOW_STAGE_KINDS = ["inbox", "task", "report", "approval", "check", "pull-request", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "done"];
 export const FLOW_COLORS = ["slate", "blue", "violet", "amber", "green", "rose"];
+/** How a Pull request zone merges once checks pass. */
+export const FLOW_MERGE_METHODS = ["squash", "merge", "rebase"];
 /** What each kind is called and does, in the words the canvas uses. */
 export const FLOW_KIND_WORDS = {
     inbox: { label: "Holding", about: "Cards wait here until someone moves them." },
@@ -45,6 +52,7 @@ export const FLOW_KIND_WORDS = {
     report: { label: "Research", about: "An agent investigates and writes a report. No code changes." },
     approval: { label: "Person decides", about: "Someone approves, or sends it back with a note." },
     check: { label: "Run a script", about: "Runs one of the project's scripts (shell, Python or Node) with no AI. It gets the card; what it prints is passed on, and it can pick where the card goes next. If it fails, the card takes its failure path." },
+    "pull-request": { label: "Pull request", about: "Opens a pull request for the card's built result and waits for CI. Green moves it on; red takes the failure path with the failing check named. It can merge once checks pass, only after a person approved." },
     update: { label: "Update where it came from", about: "Comments on the GitHub or Linear issue the card came from (and can close it), or answers in the chat thread it came from. Other cards pass straight through." },
     notify: { label: "Message", about: "Posts a message to the project's chat, then moves on." },
     request: { label: "Web request", about: "Calls an address on the web, like an API, with the card's details, and keeps what it answers. If it fails, the card takes its failure path." },
@@ -209,11 +217,42 @@ export function durationWords(minutes) {
 /** A Wait zone's settings, checked. */
 function validateWait(input, title) {
     const raw = (input ?? {});
+    if (raw["for"] === "hours") {
+        const from = clockTime(raw["from"]), to = clockTime(raw["to"]);
+        if (from === null || to === null || from === to)
+            throw new Error(`Zone ${title}: say the hours it waits for, like 22:00 to 06:00.`);
+        const zone = typeof raw["timeZone"] === "string" && raw["timeZone"].trim() !== "" ? raw["timeZone"].trim() : null;
+        if (zone !== null && !knownTimeZone(zone))
+            throw new Error(`Zone ${title}: ${zone} isn't a time zone, like Europe/London.`);
+        return { for: "hours", minutes: 0, from, to, ...(zone === null ? {} : { timeZone: zone }) };
+    }
     const minutes = durationMinutes(raw["minutes"]);
     if (minutes === null)
         throw new Error(`Zone ${title}: say how long it waits, from 1 minute to 30 days.`);
     return { for: raw["for"] === "time" ? "time" : "reply", minutes };
 }
+/** "22:00", "9:30" as "HH:MM"; null when it isn't a time of day. */
+export function clockTime(value) {
+    const match = typeof value === "string" ? /^\s*([01]?[0-9]|2[0-3]):([0-5][0-9])\s*$/.exec(value) : null;
+    return match === null ? null : `${match[1].padStart(2, "0")}:${match[2]}`;
+}
+function knownTimeZone(zone) {
+    try {
+        new Intl.DateTimeFormat("en-GB", { timeZone: zone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether a time falls inside an "hours" wait (22:00–06:00 runs past midnight), in its time zone or this computer's. */
+export function withinHours(wait, now) {
+    const parts = new Intl.DateTimeFormat("en-GB", { hour: "2-digit", minute: "2-digit", hourCycle: "h23", ...(wait.timeZone === undefined ? {} : { timeZone: wait.timeZone }) }).formatToParts(now);
+    const at = Number(parts.find(one => one.type === "hour")?.value ?? 0) * 60 + Number(parts.find(one => one.type === "minute")?.value ?? 0);
+    const minutesOf = (time) => { const [h = "0", m = "0"] = (time ?? "00:00").split(":"); return Number(h) * 60 + Number(m); };
+    const from = minutesOf(wait.from), to = minutesOf(wait.to);
+    return from < to ? at >= from && at < to : at >= from || at < to;
+}
 /** A zone's time limit, checked; null when it has none. Only Holding and "Person decides" zones move a card on. */
 function validateLimit(input, kind, title) {
     if (input === undefined || input === null)
@@ -270,6 +309,7 @@ export function validateFlowDefinition(input) {
             ...(kind === "email" ? { email: validateEmail(stage["email"], title) } : {}),
             ...(kind === "tool" ? { tool: validateTool(stage["tool"], title) } : {}),
             ...(kind === "wait" ? { wait: validateWait(stage["wait"], title) } : {}),
+            ...(kind === "pull-request" && stage["merge"] !== undefined && stage["merge"] !== null && stage["merge"] !== false ? { merge: validateMerge(stage["merge"], title) } : {}),
             ...((kind === "approval" || kind === "teammate") && stage["teammate"] !== undefined && stage["teammate"] !== null && stage["teammate"] !== "" ? { teammate: validateTeammate(stage["teammate"], title) } : {}),
             ...(kind === "teammate" ? validateRoutes(stage, title) : {}),
             ...(kind === "teammate" && stage["reply"] === true ? { reply: true } : {}),
@@ -308,8 +348,36 @@ export function validateFlowDefinition(input) {
             throw new Error(`Zone ${stage.title}: choose which teammate handles it.`);
     }
     const start = typeof raw.start === "string" && ids.has(raw.start) ? raw.start : stages[0].id;
+    // A zone that merges comes after a person's decision on every path to it: never merged without one.
+    const unapproved = reachableWithout(stages, start, one => one.kind === "approval");
+    for (const stage of stages) {
+        if (stage.merge !== undefined && unapproved.has(stage.id))
+            throw new Error(`Zone ${stage.title} merges, so a “Person decides” zone must come before it on every path.`);
+    }
     return { version: 1, start, stages };
 }
+/** A Pull request zone's merge: true is squash, the default. */
+function validateMerge(value, title) {
+    if (value === true)
+        return "squash";
+    if (typeof value === "string" && FLOW_MERGE_METHODS.includes(value))
+        return value;
+    throw new Error(`Zone ${title}: merge by squash, merge or rebase.`);
+}
+/** The zones a card can reach from `start` without passing through a zone `stop` picks (those zones aren't included). */
+export function reachableWithout(stages, start, stop) {
+    const seen = new Set();
+    const queue = [start];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        const stage = stages.find(one => one.id === id);
+        if (stage === undefined || seen.has(stage.id) || stop(stage))
+            continue;
+        seen.add(stage.id);
+        queue.push(...[stage.next, stage.onFail, stage.limit?.to ?? null, ...(stage.sort?.answers.map(one => one.to) ?? []), ...(stage.routes?.map(one => one.to) ?? [])].filter((one) => one !== null));
+    }
+    return seen;
+}
 /** A teammate's handle on a zone (v92): which teammate works it. Whether it exists is the project's to say, when a card arrives. */
 function validateTeammate(value, title) {
     if (typeof value !== "string" || !/^[a-z0-9][a-z0-9-]{0,31}$/.test(value))
@@ -387,13 +455,19 @@ function fillOne(key, stage, card) {
         return stage === undefined ? "" : card.outputs[stage] ?? "";
     }
 }
-const KIND_COLORS = { inbox: "slate", task: "blue", report: "violet", approval: "amber", check: "blue", update: "green", notify: "green", sort: "violet", draft: "violet", request: "blue", email: "green", tool: "blue", wait: "slate", teammate: "violet", done: "green" };
+const KIND_COLORS = { inbox: "slate", task: "blue", report: "violet", approval: "amber", check: "blue", "pull-request": "blue", update: "green", notify: "green", sort: "violet", draft: "violet", request: "blue", email: "green", tool: "blue", wait: "slate", teammate: "violet", done: "green" };
 /** A step id as the lead may write it (sort_by_hand, Sort-By-Hand) in the one form zones use. */
 const idOf = (value) => value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32);
 const slugOf = (title) => title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 28) || "zone";
 const overlaps = (a, b) => a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
 /** A wait step's settings: what it waits for and how long (3 days when neither the step nor the zone it keeps says). */
 function waitFromStep(step, old, title) {
+    if ((step.waitFor ?? old?.for) === "hours") {
+        const from = clockTime(step.from ?? old?.from ?? "22:00"), to = clockTime(step.until ?? old?.to ?? "06:00");
+        if (from === null || to === null)
+            throw new Error(`Step ${title}: say the hours it waits for, like from 22:00 until 06:00.`);
+        return { for: "hours", minutes: 0, from, to, ...(old?.timeZone === undefined ? {} : { timeZone: old.timeZone }) };
+    }
     const minutes = step.wait === undefined ? old?.minutes ?? 3 * 24 * 60 : durationMinutes(step.wait);
     if (minutes === null)
         throw new Error(`Step ${title}: say how long it waits, like "3 days" or "4 hours" (up to 30 days).`);
@@ -479,7 +553,9 @@ export function flowFromSteps(input, previous = null) {
             : kind === "wait" && typeof step.ifNoReply === "string" && step.ifNoReply.trim() !== "" ? step.ifNoReply : step.ifFails;
         const onFail = kind === "done" ? null
             : typeof notSure === "string" && notSure.trim() !== "" ? find(notSure, title)
-                : keptFail ?? (kind === "approval" ? worker?.id ?? (drafts[0].id === id ? null : drafts[0].id) : null);
+                : keptFail ?? (kind === "approval" ? worker?.id ?? (drafts[0].id === id ? null : drafts[0].id)
+                    // Red CI goes back to the build before it, carrying the failing check.
+                    : kind === "pull-request" ? [...earlier].reverse().find(one => one.kind === "task")?.id ?? null : null);
         // "owner": whoever owns the flow when the card arrives.
         const toOwner = kind === "approval" && (step.decider === undefined ? old?.toOwner === true : typeof step.decider === "string" && /^(owner|the owner|flow owner|the flow owner|the flow's owner)$/i.test(step.decider.trim()));
         const approver = kind !== "approval" || toOwner ? null
@@ -512,6 +588,7 @@ export function flowFromSteps(input, previous = null) {
             ...(kind === "email" ? { email: { to: step.to ?? old?.email?.to ?? "{{card.email}}", subject: step.subject ?? old?.email?.subject ?? "Re: {{card.title}}", body: step.body ?? old?.email?.body ?? "" } } : {}),
             ...(kind === "tool" ? { tool: { server: step.server ?? old?.tool?.server ?? "", name: step.tool ?? old?.tool?.name ?? "", args: typeof step.args === "string" ? step.args : step.args !== undefined ? JSON.stringify(step.args) : old?.tool?.args ?? "{}" } } : {}),
             ...(kind === "wait" ? { wait: waitFromStep(step, old?.wait ?? null, title) } : {}),
+            ...(kind === "pull-request" && (step.merge === undefined ? old?.merge !== undefined : step.merge !== false) ? { merge: step.merge === undefined || step.merge === true || step.merge === false ? old?.merge ?? "squash" : step.merge } : {}),
             // v92: "nobody" (or "none") takes a teammate off an approval step.
             ...((kind === "approval" || kind === "teammate") && (step.teammate === undefined ? old?.teammate !== undefined : !/^(nobody|none|no one)$/i.test(step.teammate.trim())) ? { teammate: idOf(step.teammate ?? old.teammate) } : {}),
             ...(kind === "teammate" ? step.routes !== undefined ? step.routes.length === 0 ? {} : { routes: step.routes.map(one => ({ answer: String(one.answer ?? "").trim(), to: find(String(one.goesTo ?? ""), title) })) } : old?.routes === undefined ? {} : { routes: old.routes } : {}),
@@ -641,11 +718,16 @@ export function flowTerms(definition, previous) {
             if (stage.sort.notes.length > 0)
                 lines.push(`Also notes: ${stage.sort.notes.map(one => one.kind === "score" ? `${one.question} (${one.levels?.join(" / ")})` : `${one.question} (yes or no)`).join("; ")}`);
         }
+        else if (stage.kind === "pull-request") {
+            const approval = [...definition.stages.slice(0, index)].reverse().find(one => one.kind === "approval");
+            lines.push("Opens a pull request for the card's built result, then waits for CI.", `Checks pass → ${stage.merge === undefined ? to(stage.next) : `merges it (${stage.merge}) and deletes its branch, only when a person approved it${approval === undefined ? "" : ` at ${approval.title}`} since it was built. Then → ${to(stage.next)}`}`, `Checks fail → ${stage.onFail === null ? "waits there, naming the failing check." : `${to(stage.onFail)} The failing check is named on the card.`}`);
+        }
         else if (stage.kind === "check")
             lines.push(`Runs the project's script “${stage.script}” with no AI.`, `Passes → ${to(stage.next)}${stage.onFail === null ? " Fails → waits there." : ` Fails → ${to(stage.onFail)}`}`);
         else if (stage.kind === "wait" && stage.wait !== undefined)
-            lines.push(stage.wait.for === "time" ? `Waits ${durationWords(stage.wait.minutes)}. Then → ${to(stage.next)}`
-                : `Waits up to ${durationWords(stage.wait.minutes)} for a reply to the card's email, from someone it was sent to. Reply → ${to(stage.next)} No reply → ${stage.onFail === null ? "stays there for a person." : to(stage.onFail)}`);
+            lines.push(stage.wait.for === "hours" ? `Waits until it's between ${stage.wait.from} and ${stage.wait.to}${stage.wait.timeZone === undefined ? "" : ` (${stage.wait.timeZone})`}; cards that arrive then go straight on. Then → ${to(stage.next)}`
+                : stage.wait.for === "time" ? `Waits ${durationWords(stage.wait.minutes)}. Then → ${to(stage.next)}`
+                    : `Waits up to ${durationWords(stage.wait.minutes)} for a reply to the card's email, from someone it was sent to. Reply → ${to(stage.next)} No reply → ${stage.onFail === null ? "stays there for a person." : to(stage.onFail)}`);
         else if (stage.next !== null)
             lines.push(`Then → ${to(stage.next)}${stage.onFail === null ? "" : ` If it fails → ${to(stage.onFail)}`}`);
         if (stage.limit !== undefined)
@@ -676,6 +758,8 @@ export function flowTerms(definition, previous) {
         terms.push("Sort steps send each card's title, details and earlier notes to Jev through your OpenRouter account.");
     if (definition.stages.some(one => one.kind === "request" || one.kind === "email" || one.kind === "tool"))
         terms.push("Web request, email and tool steps send what they're given outside this computer, with no one checking unless a decision comes before them.");
+    if (definition.stages.some(one => one.kind === "pull-request"))
+        terms.push(`Pull request steps push the card's branch to GitHub and open a pull request under this project's pull request setup.${definition.stages.some(one => one.merge !== undefined) ? " A merge happens only after a person approves the card; nothing merges without one." : " Nothing merges on its own."}`);
     if (definition.stages.some(one => one.kind === "draft"))
         terms.push("Draft steps send each card's text to Claude through the lead chat's sign-in. Nothing a draft writes is sent until a later step sends it.");
     if (definition.stages.some(one => one.teammate !== undefined))
@@ -684,7 +768,10 @@ export function flowTerms(definition, previous) {
 }
 const zone = (x, y, color, h = 300) => ({ x, y, w: 260, h, color });
 const stage = (id, title, kind, at, rest = {}) => ({ id, title, kind, zone: at, instructions: null, planning: kind === "task" ? "auto" : null, approver: null, message: null, close: kind === "update" ? true : null, script: null, sort: null, next: null, onFail: null, ...rest });
-/** 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 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 const FLOW_TEMPLATES = [
     {
         id: "coding",
@@ -710,6 +797,23 @@ export const FLOW_TEMPLATES = [
             ],
         },
     },
+    {
+        id: "issues-to-prs",
+        label: "Issues to PRs",
+        about: `GitHub issues labelled “${ISSUE_LABEL}” are built, a person approves, a pull request opens and waits for CI, then the issue gets a comment and is closed. Nothing merges on its own.`,
+        trigger: { kind: "github", watch: "issues", label: ISSUE_LABEL },
+        definition: {
+            version: 1,
+            start: "build",
+            stages: [
+                stage("build", "Build", "task", zone(0, 0, "blue"), { instructions: "{{card.title}}\n\n{{card.description}}\n\nChanges asked for (if any): {{note}}", next: "approve" }),
+                stage("approve", "Approve", "approval", zone(300, 0, "amber"), { toOwner: true, next: "pull-request", onFail: "build" }),
+                stage("pull-request", "Pull request", "pull-request", zone(600, 0, "blue"), { next: "update-issue", onFail: "build" }),
+                stage("update-issue", "Update the issue", "update", zone(900, 0, "green", 220), { message: "Done: {{card.title}}. {{stage.pull-request}}", next: "done" }),
+                stage("done", "Done", "done", zone(900, 280, "green", 220)),
+            ],
+        },
+    },
     {
         id: "research",
         label: "Research flow",

package/dist/integrations-ui.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Settings → Integrations: which integrations work. One row each: its name
+ * and state, the account it's connected as, when it last worked and last
+ * failed, what uses it, and one action. The list comes from saved checks; a
+ * render never waits on one (see integrations.ts).
+ */
+import { type Integration } from "./integrations.js";
+export declare const INTEGRATIONS_CSS: string;
+export declare function integrationsHtml(list: readonly Integration[], csrf: string, notice: {
+    said?: string | null;
+    problem?: string | null;
+    checking?: boolean;
+}): string;

package/dist/integrations-ui.js

@@ -0,0 +1,70 @@
+/**
+ * Settings → Integrations: which integrations work. One row each: its name
+ * and state, the account it's connected as, when it last worked and last
+ * failed, what uses it, and one action. The list comes from saved checks; a
+ * render never waits on one (see integrations.ts).
+ */
+import { STATE_WORDS } from "./integrations.js";
+import { whenUtc } from "./when-html.js";
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const when = (at) => whenUtc(at);
+export const INTEGRATIONS_CSS = `.integrations{max-width:760px;min-width:0}.integrations h2{margin:24px 0 6px;font-size:.9375rem}` +
+    `.integrations .integration{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:4px 16px;align-items:start;padding:12px 0;border-top:1px solid var(--so-line);min-width:0}` +
+    `.integrations .integration>:not(.integration-action),.integrations .integration-body>*{grid-column:1}.integrations .integration-body{display:contents}.integrations .integration:first-of-type{border-top:0}.integrations .integration-head{margin:0;display:flex;flex-wrap:wrap;gap:6px 10px;align-items:center;min-width:0}` +
+    `.integrations .integration-head strong{overflow-wrap:anywhere}.integrations .integration p{margin:2px 0 0;min-width:0;overflow-wrap:anywhere}` +
+    `.integrations .integration-action{grid-column:2;grid-row:1 / span 3;align-self:center;margin:0}.integrations .integration-action button,.integrations .integration-action .button-link{min-height:44px;white-space:nowrap}` +
+    `.integrations .integration .integration-action button{width:auto}.integrations .integration .integration-action a.integration-quiet{background:var(--so-paper);color:var(--so-ink);border:1px solid var(--so-input-line)}` +
+    `.integrations .integration-fix{color:var(--so-danger)}.integrations code{overflow-wrap:anywhere}.integrations details{margin-top:4px;font-size:.8125rem}.integrations summary{cursor:pointer;padding:4px 0}` +
+    `.integration-state{display:inline-flex;align-items:center;gap:6px;font-size:.75rem;font-weight:500;padding:0 8px;border-radius:5px;line-height:20px;white-space:nowrap}` +
+    `.integration-state i{width:6px;height:6px;border-radius:50%;background:currentColor}` +
+    `.integration-state--connected{color:var(--so-success);background:var(--so-success-soft)}.integration-state--broken{color:var(--so-danger);background:var(--so-danger-soft)}` +
+    `.integration-state--not-set-up,.integration-state--checking{color:var(--so-muted);background:var(--so-neutral-soft)}` +
+    // A phone: the action sits at the right of the name line, and the facts under it run on as one line.
+    `@media (max-width:760px){.integrations h2{margin:16px 0 0}.integrations .integration{gap:0 12px;padding:6px 0 8px}.integrations .integration-head{min-height:44px}` +
+    `.integrations .integration-action{grid-row:1;align-self:center}.integrations .integration-body{display:block;grid-column:1 / -1;line-height:1.35}` +
+    `.integrations .integration-body>p{margin:0}.integrations .integration-body>p.meta{display:inline}.integrations .integration-body>p.meta+p.meta::before{content:" · "}` +
+    `.integrations .integration-body>:not(.meta){margin-top:4px}.integrations .integration-body>:not(.meta)+p.meta{display:block;margin-top:2px}.integrations details{margin-top:2px}}`;
+const GROUPS = [
+    ["chat", "Chat"], ["code", "Code and issues"], ["mail", "Email"], ["tools", "MCP tools"], ["monitoring", "Monitoring"], ["agents", "Agents"],
+];
+function action(one, csrf) {
+    const a = one.action;
+    if (a.kind === "test") {
+        return csrf === "" ? "" : `<form method="post" action="/settings/integrations/test" class="integration-action"><input type="hidden" name="csrf" value="${e(csrf)}">` +
+            `<input type="hidden" name="key" value="${e(one.key)}"><button type="submit">Send test</button></form>`;
+    }
+    // A command is run where Toolroll runs; a page is linked. Fix and Set up both say which.
+    // Fix is the one filled action on the page; Set up stays quiet so a list of unused services doesn't shout.
+    if (a.href !== null)
+        return `<p class="integration-action"><a class="button-link${a.kind === "setup" ? " integration-quiet" : ""}" href="${e(a.href)}">${a.label}</a></p>`;
+    return "";
+}
+function row(one, csrf) {
+    const badge = !one.checked && one.state === "connected"
+        ? `<span class="integration-state integration-state--checking"><i aria-hidden="true"></i>Checking</span>`
+        : `<span class="integration-state integration-state--${one.state}"><i aria-hidden="true"></i>${STATE_WORDS[one.state]}</span>`;
+    const facts = [one.account, one.detail].filter(Boolean).map(e).join(" · ");
+    const command = one.action.kind !== "test" ? one.action.command : null;
+    const fix = one.action.kind === "fix" ? `<p class="integration-fix" role="status">${e(one.action.words)}</p>` : "";
+    const run = command === null || (one.action.kind === "fix" && one.action.words.includes(command)) ? "" : `<p class="meta">Run <code>${e(command)}</code> on the computer running Toolroll.</p>`;
+    const seen = [one.lastSuccessAt === null ? null : `Last success ${when(one.lastSuccessAt)}`, one.usedBy.length === 0 ? null : `Used by ${e(one.usedBy.join(", "))}`].filter(Boolean);
+    const history = one.state === "not-set-up" || seen.length === 0 ? "" : `<p class="meta">${seen.join(" · ")}</p>`;
+    const lastError = one.lastError === null || one.state === "not-set-up" ? "" : one.state === "broken" && one.action.kind === "fix" && one.action.words === one.lastError
+        ? `<p class="meta">Failed ${when(one.lastErrorAt ?? "")}</p>`
+        : `<details><summary>Last error ${one.lastErrorAt === null ? "" : when(one.lastErrorAt)}</summary><p class="meta">${e(one.lastError)}</p></details>`;
+    return `<div class="integration" data-integration="${e(one.key)}" data-state="${one.state}">` +
+        `<p class="integration-head"><strong>${e(one.name)}</strong> ${badge}</p>` +
+        action(one, csrf) +
+        `<div class="integration-body">${facts === "" ? "" : `<p class="meta">${facts}</p>`}${fix}${run}${history}${lastError}</div></div>`;
+}
+export function integrationsHtml(list, csrf, notice) {
+    const note = notice.problem ? `<p class="problem" role="alert">${e(notice.problem)}</p>` : notice.said ? `<p role="status">${e(notice.said)}</p>` : "";
+    const broken = list.filter(one => one.state === "broken").length;
+    const summary = broken > 0 ? `<p><strong>${broken} need${broken === 1 ? "s" : ""} fixing.</strong></p>`
+        : notice.checking || list.some(one => !one.checked) ? `<p class="meta" role="status">Checking in the background. Refresh in a few seconds.</p>` : "";
+    const sections = GROUPS.map(([group, title]) => {
+        const rows = list.filter(one => one.group === group);
+        return rows.length === 0 ? "" : `<h2>${title}</h2>${rows.map(one => row(one, csrf)).join("")}`;
+    }).join("");
+    return `<section class="integrations">${note}${summary}${sections}</section>`;
+}

package/dist/integrations.d.ts

@@ -0,0 +1,113 @@
+import type { Store } from "./store.js";
+import type { Runner } from "./backend.js";
+import type { ConnectionChecker } from "./provider-connection.js";
+export type IntegrationState = "connected" | "not-set-up" | "broken";
+export type IntegrationGroup = "chat" | "code" | "mail" | "tools" | "monitoring" | "agents";
+/** Where a person goes (or what they run) to set something up or fix it. */
+export type IntegrationPlace = {
+    href: string | null;
+    command: string | null;
+};
+export type IntegrationAction = ({
+    kind: "setup";
+    label: "Set up";
+} & IntegrationPlace) | {
+    kind: "test";
+    label: "Send test";
+} | ({
+    kind: "fix";
+    label: "Fix";
+    words: string;
+} & IntegrationPlace);
+export type Integration = {
+    key: string;
+    group: IntegrationGroup;
+    name: string;
+    state: IntegrationState;
+    /** The account or workspace name, never a credential. */
+    account: string | null;
+    /** One short fact, such as which projects can be pushed to. */
+    detail: string | null;
+    /** Whether a check has answered for this integration yet (always true for those with nothing to check). */
+    checked: boolean;
+    checkedAt: string | null;
+    lastSuccessAt: string | null;
+    lastError: string | null;
+    lastErrorAt: string | null;
+    usedBy: string[];
+    action: IntegrationAction;
+};
+export declare const STATE_WORDS: Record<IntegrationState, string>;
+export type ProbeResult = {
+    outcome: "ok";
+    account?: string | null;
+    detail?: string | null;
+} | {
+    outcome: "failed";
+    problem: string;
+    account?: string | null;
+    detail?: string | null;
+    fix?: Partial<IntegrationPlace>;
+} | {
+    outcome: "absent";
+    problem: string;
+    setup?: Partial<IntegrationPlace>;
+};
+export type IntegrationIo = {
+    store: Store;
+    /** The folder beside the database where credential files live; null when there is none. */
+    dir: string | null;
+    telegramTokenFile: string | null;
+    env: Record<string, string | undefined>;
+    /** The projects whose MCP tools and GitHub push rights are listed. */
+    repos: readonly string[];
+    fetch?: typeof fetch;
+    /** How `gh` runs (tests replace it). */
+    gh?: Runner;
+    /** The same sign-in check Settings → AI providers makes. */
+    checkConnection?: ConnectionChecker;
+    /** Where project tool secrets live. */
+    toolHome?: string;
+    /** Whether a mail server answers at host:port (tests replace it). */
+    reach?: (host: string, port: number, secure: boolean) => Promise<void>;
+    clock?: () => Date;
+};
+/** Remove every known secret value and anything shaped like a token; keep it to one short line. */
+export declare function scrubIntegrationText(text: string, secrets?: readonly (string | null | undefined)[]): string;
+type CheckRow = {
+    key: string;
+    outcome: "ok" | "failed" | "absent";
+    account: string | null;
+    detail: string | null;
+    problem: string | null;
+    checkedAt: string;
+    okAt: string | null;
+    error: string | null;
+    errorAt: string | null;
+};
+export declare function readIntegrationChecks(store: Store): Map<string, CheckRow>;
+export declare function recordIntegrationCheck(store: Store, key: string, result: ProbeResult, now: Date): void;
+/** Whether something answers at host:port: a connection opened and closed, no login and no message. */
+export declare function reachServer(host: string, port: number, secure: boolean): Promise<void>;
+/** Every integration as it stands now, from files and saved history only: no network, no process, never slow. */
+export declare function integrationsNow(io: IntegrationIo): Integration[];
+/** Run the checks (all, or the named ones), record each answer, and return the list. */
+export declare function checkIntegrations(io: IntegrationIo, keys?: readonly string[]): Promise<Integration[]>;
+/** The one line `status` and `onboard` add when something is Broken; null when nothing is. */
+export declare function integrationsBrokenLine(list: readonly Integration[]): string | null;
+/** The CLI's lines: one per integration, then the fix under anything Broken. */
+export declare function renderIntegrations(list: readonly Integration[]): string[];
+export type IntegrationMonitor = {
+    /** The list now, without waiting; starts a background check when the last one is older than the cache. */
+    list(): Integration[];
+    /** Check now and wait (Send test, or the first answer in a test). */
+    check(keys?: readonly string[]): Promise<Integration[]>;
+    /** Whether a background check is running. */
+    readonly checking: boolean;
+};
+/** Checks in the background with a short cache, as the first-run suggestions are: a render never waits on a check. */
+export declare function createIntegrationMonitor(io: () => IntegrationIo, options?: {
+    cacheMs?: number;
+    now?: () => number;
+}): IntegrationMonitor;
+export {};