@onepointfour-packs/flaredeck-agent 0.2.209 → 0.2.211

package/dist/features/hand-back.d.ts

@@ -0,0 +1,60 @@
+import { type Worktree } from '../worktree.js';
+/** The card, as FlareDeck's REST API returns it — the fields the gate reads. */
+export type GateCard = {
+    code?: string;
+    lane?: {
+        type?: string | null;
+        name?: string | null;
+    } | null;
+    releases?: unknown[];
+    deployedAt?: unknown;
+    assigned_to?: {
+        uid?: string;
+    } | null;
+} | null;
+/**
+ * Cards handed to the lead, and the branch head at the time — so a retried tool call does not
+ * assign or message twice, and a card the lead gives back unchanged is its "move it".
+ */
+export declare function handBackMemory(): {
+    has: (code: string) => boolean;
+    headAt: (code: string) => string | undefined;
+    add: (code: string, head: string | null) => void;
+    forget: (code: string) => void;
+};
+export type HandBackMemory = ReturnType<typeof handBackMemory>;
+/** What the gate reads from git; the real functions unless a test says otherwise. */
+export type GateGit = {
+    tooEarlyToFinish: (tree: Worktree | null) => Promise<string | null>;
+    produced: (tree: Worktree) => Promise<{
+        commits: number;
+        pushed: boolean;
+    }>;
+    cardWorkOnBase: (path: string, base: string | undefined, code: string) => Promise<boolean>;
+    headOf: (tree: Worktree) => Promise<string | null>;
+};
+export type FinishGateDeps = {
+    /** The card from FlareDeck; absent when this harness has no FlareDeck REST access. */
+    card?: (ref: string) => Promise<GateCard>;
+    /** The card this turn is on: the code it resolved to, else the event's code or id. */
+    cardRef: () => string;
+    /** The card's code for messages, preferring the event's own. */
+    cardCode: () => string;
+    tree: Worktree | null;
+    /** Where this card's work starts: a card whose work is already merged there may move on. */
+    startFrom: string | undefined;
+    /** Has others' work in its care (a lead or manager): a card whose code is a worker's may move on. */
+    oversees: boolean;
+    /** Its lead, when it has one: finished work is handed there. */
+    lead: {
+        id: string;
+        name: string;
+    } | null;
+    selfId: string;
+    handedBack: HandBackMemory;
+    /** Assign the card to the lead and tell them, in one go. Throws when either fails. */
+    handToLead: (code: string, message: string) => Promise<void>;
+    log: (kind: 'tool' | 'warn', text: string) => void;
+    git?: GateGit;
+};
+export declare function finishGate(d: FinishGateDeps): (toLane?: string) => Promise<string | null>;

package/dist/features/hand-back.js

@@ -0,0 +1,127 @@
+/**
+ * The finish gate: what happens when an agent calls a card finished (mark-card-done, or a move into
+ * a done or review lane — see CLAIMS_DONE in flaredeck-proxy.ts).
+ *
+ * Checked here rather than trusted, because a turn that produced nothing still reports confidently:
+ *  · a card already released moves on — its work is on an environment;
+ *  · otherwise the card must have commits of its own, published;
+ *  · and an agent that reports to a lead does not decide its own work is finished: the card is
+ *    handed to the lead for review, once, with the branch named.
+ *
+ * Returns null to let the call through, or the text the agent is told instead.
+ * Split out of serve.ts (docs/spec-harness-profiles.md, step 2).
+ */
+import { isAfterReleaseMove, isReleasedClose } from '../flaredeck-proxy.js';
+import { cardWorkOnBase, finishRefusalStands, headOf, leadGaveItBack, produced, tooEarlyToFinish } from '../worktree.js';
+/**
+ * Cards handed to the lead, and the branch head at the time — so a retried tool call does not
+ * assign or message twice, and a card the lead gives back unchanged is its "move it".
+ */
+export function handBackMemory() {
+    const handed = new Set();
+    const heads = new Map();
+    return {
+        has: (code) => handed.has(code),
+        headAt: (code) => heads.get(code),
+        add: (code, head) => { handed.add(code); if (head)
+            heads.set(code, head); },
+        forget: (code) => { handed.delete(code); heads.delete(code); },
+    };
+}
+const realGit = { tooEarlyToFinish, produced, cardWorkOnBase, headOf };
+export function finishGate(d) {
+    const git = d.git ?? realGit;
+    return async (toLane) => {
+        // A released card moving on to testing or review is the next step of the board's flow.
+        if (d.card) {
+            const here = await d.card(d.cardRef()).catch(() => null);
+            const released = !!here && ((Array.isArray(here.releases) && here.releases.length > 0) || !!here.deployedAt);
+            if (here && toLane && isAfterReleaseMove(toLane, here.lane?.type, here.lane?.name ?? '', released)) {
+                d.log('tool', `moving ${here.code || d.cardRef()} on to ${toLane} — it was released already, so this is the next step, not a hand-back`);
+                return null;
+            }
+            if (here && isReleasedClose(toLane ?? '', released)) {
+                d.log('tool', `closing ${here.code || d.cardRef()} — its work was released already`);
+                return null;
+            }
+        }
+        const { tree } = d;
+        const why = await git.tooEarlyToFinish(tree);
+        /* A LEAD moving a card on with nothing of its own on the branch is dispatch, not a claim of
+           finished work: the code lives on the worker's branch, often already merged. The gate refused
+           JARVIS moving HR-0634 (PR #75 merged, on qa) to "On test site", and the lead then flagged a
+           person to do the move — an intervention nobody needed. Kept for a lead that HAS committed
+           work of its own: that still has to be published before the card moves. */
+        const cardCode = d.cardCode();
+        if (why && tree && cardCode && (await git.produced(tree)).commits === 0 && await git.cardWorkOnBase(tree.path, d.startFrom, cardCode)) {
+            d.log('tool', `moving ${cardCode} on — its work is already merged into ${d.startFrom ?? 'the base branch'}, on an earlier branch`);
+            return null;
+        }
+        if (why && tree && !finishRefusalStands(why, d.oversees, (await git.produced(tree)).commits)) {
+            d.log('tool', `moving ${cardCode || 'the card'} on as lead — the work is on a worker's branch, not mine`);
+            return null;
+        }
+        if (why) {
+            d.log('warn', `refused a "done" on an empty branch: ${tree?.branch ?? '(no branch)'}`);
+            return why;
+        }
+        // If this agent reports to someone, it does not decide that its own work is finished. The lead
+        // said "I'll check its saved work myself before it goes anywhere" and then was never told: the
+        // card moved itself to Awaiting Deployment. A report hands back; the lead moves it, or comments
+        // and sends it back, which is what a lead is for.
+        if (!d.lead)
+            return null;
+        const code = d.cardRef();
+        if (!code)
+            return null;
+        const lead = d.lead;
+        // Handed over before, and the lead has given it back with nothing new on the branch: the lead
+        // reviewed it and wants it moved on. Let the move through instead of refusing again.
+        if (d.handedBack.has(code) && tree && d.card) {
+            const [here, head] = await Promise.all([d.card(code).catch(() => null), git.headOf(tree)]);
+            if (leadGaveItBack(d.handedBack.headAt(code), head, here?.assigned_to?.uid, d.selfId)) {
+                d.log('tool', `moving ${code} on — ${lead.name} reviewed it and gave it back, nothing new since`);
+                return null;
+            }
+            // Back with this worker and changed since (or we cannot tell): it is new work, handed to the
+            // lead again like the first time. Remembering the old hand-back forever refused HAL's second
+            // "done" on HR-1074 with "JARVIS's to verify" while the card stayed assigned to HAL (20 Oct).
+            if (here?.assigned_to?.uid && here.assigned_to.uid === d.selfId)
+                d.handedBack.forget(code);
+        }
+        if (!d.handedBack.has(code)) {
+            d.handedBack.add(code, tree ? await git.headOf(tree) : null);
+            const made = tree ? await git.produced(tree) : null;
+            let where = tree
+                ? `Branch \`${tree.branch}\`${made ? ` — ${made.commits} commit(s), ${made.pushed ? 'pushed' : 'NOT pushed'}` : ''}.`
+                : 'No branch: nothing of mine is in a checkout for this card.';
+            // A card folder: each repository with work on it, by name — the lead reviews each one.
+            if (tree?.companions?.length) {
+                const lines = [];
+                for (const t of [tree, ...tree.companions]) {
+                    const p = await git.produced(t);
+                    if (p.commits)
+                        lines.push(`  · ${t.path.split("/").pop()}: \`${t.branch}\` — ${p.commits} commit(s), ${p.pushed ? 'pushed' : 'NOT pushed'}`);
+                }
+                where = lines.length ? `Changed:\n${lines.join('\n')}` : where;
+            }
+            try {
+                await d.handToLead(code, `**${code} is ready for your review.**\n\n${where}\n\n` +
+                    `I have not moved it — it is assigned to you and still in its lane. ` +
+                    `Check the work and move it on, or comment on the card and I will fix it.`);
+                d.log('tool', `handed ${code} to ${lead.name} for review`);
+            }
+            catch (e) {
+                // A handback that did not happen must not read as one that did.
+                d.handedBack.forget(code);
+                const text = e instanceof Error ? e.message : String(e);
+                d.log('warn', `could not hand ${code} to ${lead.name}: ${text}`);
+                return `Could not hand this card to ${lead.name} for review (${text}). Do not move it; say so on the card instead.`;
+            }
+        }
+        return (`${code} is now ${lead.name}'s to verify, not yours to close. It is assigned to them and ` +
+            `they have been told, with your branch. Leave the lane alone — they move it on, or comment ` +
+            `and send it back to you. Your part is done; say nothing further about it being finished.`);
+    };
+}
+//# sourceMappingURL=hand-back.js.map

package/dist/features/hand-back.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hand-back.js","sourceRoot":"","sources":["../../src/features/hand-back.ts"],"names":[],"mappings":"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"}

package/dist/features/manage-pane.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The `manage` feature at the pane: a manager's person can sit at its terminal and answer the
+ * questions meant for them here, instead of on their phone. `/local` holds those questions at the
+ * pane; `/remote` (or ten minutes with nobody answering) sends them to the phone as they stand on
+ * the card. An answer typed here is written on the card first — an answer that exists only in a
+ * terminal is one nobody else can find — then the flag comes off and the card goes back to the
+ * agent. See presence.ts for the holding itself.
+ * Split out of serve.ts (docs/spec-harness-profiles.md, step 2).
+ */
+import type { HeldAsk, Mode, Presence } from '../presence.js';
+export type ManagePaneDeps = {
+    presence: Presence;
+    /** Only a manager's pane decides where its person's questions are shown. */
+    manages: () => boolean;
+    /** A FlareDeck tool, as this agent. */
+    call: (tool: string, args: Record<string, unknown>) => Promise<string>;
+    /** The card goes back to the agent with this note, its question answered. */
+    resume: (ask: HeldAsk, text: string) => void;
+    /** The pane's list of held questions changed. */
+    show: () => void;
+    /** This agent's name, for the answer's comment. */
+    agent: () => string;
+    log: (kind: 'warn' | 'you', text: string) => void;
+};
+export declare function managePane(d: ManagePaneDeps): {
+    sendOn: (a: HeldAsk) => Promise<void>;
+    setMode(mode: Mode): void;
+    answer(a: HeldAsk, answer: string): Promise<void>;
+    /** Every 15 seconds: a question nobody answered here in ten minutes goes to the phone. */
+    tick(): void;
+};

package/dist/features/manage-pane.js

@@ -0,0 +1,60 @@
+export function managePane(d) {
+    /** Nobody answered here: the held question goes to the phone, as it stands on the card. */
+    const sendOn = async (a) => {
+        const label = a.code || a.card;
+        try {
+            const out = await d.call('set-needs-human', { card_id: a.code || a.card, ...(a.board ? { board_id: a.board } : {}), push_held: true });
+            d.log('warn', `${label}: ${out.split('\n').find((l) => l.startsWith('**Told**'))?.replace(/\*\*/g, '') ?? out.split('\n')[0]}`);
+        }
+        catch (e) {
+            d.log('warn', `${label}: could not send the question on to ${a.person}'s phone (${e instanceof Error ? e.message : String(e)}) — it is still on the card`);
+        }
+    };
+    return {
+        sendOn,
+        setMode(mode) {
+            if (!d.manages()) {
+                d.log('warn', '/local and /remote are for a manager\'s pane: they decide where questions for the person the manager reports to are shown.');
+                return;
+            }
+            d.presence.set(mode);
+            if (mode === 'local') {
+                d.log('you', 'local — questions for you are shown here and kept off your phone. One left unanswered for ten minutes goes to your phone, and this goes back to remote.');
+            }
+            else {
+                const waiting = d.presence.release();
+                d.log('you', `remote — questions go to FlareDeck and your phone${waiting.length ? `, including the ${waiting.length} waiting here` : ''}.`);
+                for (const a of waiting)
+                    void sendOn(a);
+            }
+            d.show();
+        },
+        async answer(a, answer) {
+            d.presence.take(a.card);
+            d.show();
+            const label = a.code || a.card;
+            d.log('you', `${label}: ${answer}`);
+            const ref = { card_id: a.code || a.card, ...(a.board ? { board_id: a.board } : {}) };
+            try {
+                await d.call('create-card-comment', { ...ref, comment: `**${a.person} answered at ${d.agent()}'s pane.**\n\n> ${a.question}\n\n${answer}` });
+                await d.call('clear-needs-human', ref);
+            }
+            catch (e) {
+                d.log('warn', `${label}: the answer could not be written to the card (${e instanceof Error ? e.message : String(e)}) — the agent still gets it`);
+            }
+            d.resume(a, `${a.person} answered your question at this pane.\n\nYou asked: ${a.question}\nThe answer: ${answer}\n\nIt is on the card as a comment and the flag is cleared. Carry on from where you stopped.`);
+        },
+        /** Every 15 seconds: a question nobody answered here in ten minutes goes to the phone. */
+        tick() {
+            const due = d.presence.expire();
+            if (due.length) {
+                d.log('warn', `nobody answered here in ten minutes — ${due.length === 1 ? 'that question has' : `${due.length} questions have`} gone to your phone, and this pane is remote again. /local when you are back.`);
+                for (const a of due)
+                    void sendOn(a);
+            }
+            if (due.length || d.presence.held().length)
+                d.show();
+        },
+    };
+}
+//# sourceMappingURL=manage-pane.js.map

package/dist/features/manage-pane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manage-pane.js","sourceRoot":"","sources":["../../src/features/manage-pane.ts"],"names":[],"mappings":"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"}

package/dist/features/release-wiring.d.ts

@@ -0,0 +1,18 @@
+import { type ReleaseDeps } from '../release.js';
+import type { Flaredeck } from '../flaredeck.js';
+/** Who approves a release this agent may not make alone: its manager, or the person it works for. */
+export type Approvers = {
+    manager?: string | null;
+    person?: string | null;
+};
+/** The repository a checkout came from. */
+export declare const originOf: (cwd: string) => Promise<string>;
+/** A card from FlareDeck's REST API, as the release tool needs it. */
+export declare function releaseCardInfo(c: any, now?: number): Awaited<ReturnType<NonNullable<ReleaseDeps['cardInfo']>>>;
+export declare function flaredeckReleaseDeps(o: {
+    mcpUrl: string;
+    tenant: string;
+    auth: () => Promise<string>;
+    deck: Flaredeck;
+    approvers: Approvers;
+}): Pick<ReleaseDeps, 'ladder' | 'approve' | 'originOf' | 'cardInfo' | 'record' | 'recordReleased' | 'watch'>;

package/dist/features/release-wiring.js

@@ -0,0 +1,56 @@
+/**
+ * The release tool's connection to FlareDeck: the board's ladder, approvals from the agent's
+ * manager or person, what a card looks like now, and recording where a release went. The tool
+ * itself — what may be released where — is release.ts; this is only how it reaches FlareDeck.
+ * Split out of serve.ts (docs/spec-harness-profiles.md, step 2).
+ */
+import { spawn } from 'node:child_process';
+import { fetchLadder } from '../release.js';
+import { flaredeckDecider } from '../approval.js';
+import { callFlaredeckTool } from '../flaredeck-proxy.js';
+/** The repository a checkout came from. */
+export const originOf = (cwd) => new Promise((res) => {
+    const c = spawn('git', ['remote', 'get-url', 'origin'], { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+    let out = '';
+    c.stdout.on('data', (d) => (out += String(d)));
+    c.on('close', () => res(out.trim()));
+    c.on('error', () => res(''));
+});
+/** A card from FlareDeck's REST API, as the release tool needs it. */
+export function releaseCardInfo(c, now = Date.now()) {
+    if (!c)
+        return null;
+    const since = c.release_since ? Date.parse(String(c.release_since)) : NaN;
+    return {
+        laneType: c.lane?.type ?? null,
+        minutesInReleaseLane: String(c.lane?.type || '').toLowerCase() === 'release' && Number.isFinite(since) ? (now - since) / 60_000 : null,
+        releases: (Array.isArray(c.releases) ? c.releases : []).map((r) => ({ environment: String(r.environment ?? ''), sha: String(r.sha ?? '') })),
+    };
+}
+export function flaredeckReleaseDeps(o) {
+    const api = (path) => `${new URL(o.mcpUrl).origin}/api/v1/${encodeURIComponent(o.tenant)}/${path}`;
+    const post = async (path, body, ms) => fetch(api(path), {
+        method: 'POST', headers: { authorization: `Bearer ${await o.auth()}`, 'content-type': 'application/json' },
+        body: JSON.stringify(body), signal: AbortSignal.timeout(ms),
+    });
+    return {
+        ladder: (boardId) => fetchLadder(o.mcpUrl, o.tenant, boardId, o.auth),
+        approve: async (card, who, what) => {
+            const approvers = [who === 'person' ? o.approvers.person : o.approvers.manager].filter((x) => !!x);
+            if (!approvers.length)
+                return { allow: false, reason: `nobody is set as your ${who === 'person' ? 'person (Works for / reports to)' : 'manager'} in FlareDeck to approve it` };
+            const ask = flaredeckDecider(o.deck, card, 60 * 60_000, { approvers });
+            const v = await ask({ toolName: 'release', input: what }, { signal: new AbortController().signal });
+            return v.allow ? { allow: true } : { allow: false, ...(v.reason ? { reason: v.reason } : {}) };
+        },
+        originOf,
+        cardInfo: async (code) => releaseCardInfo(await o.deck.card(code).catch(() => null)),
+        record: async (card, text) => { await callFlaredeckTool(o.mcpUrl, await o.auth(), 'create-card-comment', { card_id: card, comment: text }); },
+        recordReleased: async (r) => {
+            const res = await post('cards/released', r, 20_000);
+            return res.ok ? (await res.json()) : null;
+        },
+        watch: async (card) => { await post('deploy-watch', { card_key: card }, 15_000); },
+    };
+}
+//# sourceMappingURL=release-wiring.js.map

package/dist/features/release-wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-wiring.js","sourceRoot":"","sources":["../../src/features/release-wiring.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAoB,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAM1D,2CAA2C;AAC3C,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAmB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;IAC5E,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IACtG,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACrC,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC,CAAC,CAAC;AAEH,sEAAsE;AACtE,MAAM,UAAU,eAAe,CAAC,CAAM,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACtD,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,KAAK,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC1E,OAAO;QACL,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,IAAI;QAC9B,oBAAoB,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI;QACtI,QAAQ,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;KAClJ,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,CAMpC;IACC,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;IAC3G,MAAM,IAAI,GAAG,KAAK,EAAE,IAAY,EAAE,IAAa,EAAE,EAAU,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;QAC/E,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC1G,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;KAC5D,CAAC,CAAC;IACH,OAAO;QACL,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC;QACrE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;YACjC,MAAM,SAAS,GAAG,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAChH,IAAI,CAAC,SAAS,CAAC,MAAM;gBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,iCAAiC,CAAC,CAAC,CAAC,SAAS,6BAA6B,EAAE,CAAC;YAC/K,MAAM,GAAG,GAAG,gBAAgB,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;YACvE,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,eAAe,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;YACpG,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QACjG,CAAC;QACD,QAAQ;QACR,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QACpF,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,GAAG,MAAM,iBAAiB,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,qBAAqB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7I,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;YAC1B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;YACpD,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,CAAE,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA4B,CAAC,CAAC,CAAC,IAAI,CAAC;QACxE,CAAC;QACD,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;KACnF,CAAC;AACJ,CAAC"}

package/dist/features/services.d.ts

@@ -0,0 +1,45 @@
+import type { StreamEvent } from '../stream.js';
+import type { Started, StartWith } from '../environment.js';
+type Repo = NonNullable<StreamEvent['baseBranches']>[number];
+export type ServiceDeps = {
+    /** The harness's folder for service clones. */
+    root: string;
+    /** git, never prompting, with FlareDeck's GitHub connection. */
+    git: (args: string[], cwd: string) => Promise<{
+        code: number;
+        out: string;
+    }>;
+    /** The GitHub token to clone with, when there is one. */
+    token: () => Promise<string | null>;
+    /** The start script kept in FlareDeck for a repository (an absolute path), if any. */
+    storedScript: (repository: string) => string | undefined;
+    start: (dir: string, onStep: (t: string) => void, declared?: string, w?: StartWith) => Promise<Started>;
+    stop: (dir: string, declared?: string, stored?: string) => Promise<boolean>;
+    log: (kind: 'tool' | 'warn', text: string) => void;
+    now?: () => number;
+};
+/** `https://github.com/Owner/Name` → `owner__name`. */
+export declare const serviceDir: (url: string) => string;
+/** The variable a dependency's address is given to the card's start script under. */
+export declare const envName: (s: string) => string;
+/** The deployed address for an environment: by its name, case-insensitively, else the only one. */
+export declare function deployedFor(sites: Record<string, string> | undefined, environment: string): string | undefined;
+/** A service unused this long is stopped. */
+export declare const SERVICE_IDLE_MS: number;
+export declare function createServices(d: ServiceDeps): {
+    /** A clone to cut a card folder's worktree from, when the repository is not checked out here. */
+    clone: (repository: string) => Promise<string | null>;
+    /**
+     * Everything a card needs running beside it, as environment variables for its own start
+     * script, and a line each for the agent. Never throws: what cannot be had is said, and the card
+     * still starts — it can always be tested against what IS running.
+     */
+    ensure(alongside: Repo[], environment: string): Promise<{
+        env: Record<string, string>;
+        notes: string[];
+    }>;
+    /** Stop services nothing has needed for a while. */
+    stopIdle(): Promise<void>;
+    stopAll(): Promise<void>;
+};
+export {};

package/dist/features/services.js

@@ -0,0 +1,147 @@
+/**
+ * What a card needs running beside its own repository — a site's API and CMS — so the change can
+ * be tested (`alongside` on the event; docs/spec-workspace-repositories.md).
+ *
+ * Each is used DEPLOYED when the repository has an address for the card's environment: always-
+ * current data and nothing to build, which is what PayInc's `payinc-local-stack.sh --api=dev` did by
+ * hand and the right default for a site card. Otherwise it is started LOCALLY, once, from a clean
+ * clone in the harness's own folder (never somebody's working tree — C3PO would not touch those),
+ * on the branch the card's environment names, and shared by every card that needs it until it has
+ * gone unused for a while.
+ *
+ * Its address reaches the card's own start script as FLAREDECK_<TYPE>_URL (FLAREDECK_API_URL,
+ * FLAREDECK_CMS_URL) and FLAREDECK_<OWNER_NAME>_URL.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** `https://github.com/Owner/Name` → `owner__name`. */
+export const serviceDir = (url) => url.replace(/\.git$/i, '').replace(/\/+$/, '').split(/[/:]/).slice(-2).join('__').toLowerCase().replace(/[^\w.-]/g, '_');
+/** The variable a dependency's address is given to the card's start script under. */
+export const envName = (s) => `FLAREDECK_${s.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_|_$/g, '')}_URL`;
+/** The deployed address for an environment: by its name, case-insensitively, else the only one. */
+export function deployedFor(sites, environment) {
+    const entries = Object.entries(sites ?? {});
+    const hit = entries.find(([k]) => k.toLowerCase() === environment.toLowerCase());
+    if (hit)
+        return hit[1];
+    // "*": the address for every environment (a bare address on Integrations → Repositories).
+    const any = entries.find(([k]) => k === '*');
+    if (any)
+        return any[1];
+    return entries.length === 1 ? entries[0][1] : undefined;
+}
+/** A service unused this long is stopped. */
+export const SERVICE_IDLE_MS = 2 * 60 * 60 * 1000;
+export function createServices(d) {
+    const now = d.now ?? Date.now;
+    const running = new Map();
+    /** A clone of the repository in the harness's folder, made if it is not there yet. */
+    const clone = async (r) => {
+        const dir = join(d.root, serviceDir(r.repository));
+        if (!existsSync(join(dir, '.git'))) {
+            const token = await d.token();
+            if (!token) {
+                d.log('warn', `${serviceDir(r.repository)}: not on this machine, and FlareDeck has no GitHub connection to clone it with`);
+                return null;
+            }
+            mkdirSync(d.root, { recursive: true });
+            const auth = `http.extraHeader=Authorization: Basic ${Buffer.from(`x-access-token:${token}`).toString('base64')}`;
+            d.log('tool', `cloning ${r.repository} to run beside this card`);
+            const c = await d.git(['-c', auth, 'clone', '--quiet', `${r.repository.replace(/\.git$/i, '')}.git`, dir], d.root);
+            if (c.code !== 0) {
+                d.log('warn', `could not clone ${r.repository}: ${c.out.split('\n').pop()}`);
+                return null;
+            }
+        }
+        return dir;
+    };
+    /** A clean clone of the repository on `branch`, in the harness's folder. */
+    const checkout = async (r) => {
+        const dir = await clone(r);
+        if (!dir)
+            return null;
+        const branch = r.branch || 'HEAD';
+        await d.git(['fetch', '--quiet', 'origin'], dir);
+        const co = await d.git(['checkout', '--quiet', '--detach', branch === 'HEAD' ? 'origin/HEAD' : `origin/${branch}`], dir);
+        if (co.code !== 0)
+            d.log('warn', `${serviceDir(r.repository)}: no branch ${branch} — using what is checked out`);
+        return dir;
+    };
+    return {
+        /** A clone to cut a card folder's worktree from, when the repository is not checked out here. */
+        clone: (repository) => clone({ repository }),
+        /**
+         * Everything a card needs running beside it, as environment variables for its own start
+         * script, and a line each for the agent. Never throws: what cannot be had is said, and the card
+         * still starts — it can always be tested against what IS running.
+         */
+        async ensure(alongside, environment) {
+            const env = {};
+            const notes = [];
+            const give = (r, url) => {
+                env[envName(r.component || 'service')] ??= url;
+                env[envName(serviceDir(r.repository))] = url;
+            };
+            for (const r of alongside) {
+                const name = serviceDir(r.repository);
+                const deployed = deployedFor(r.sites, environment);
+                if (deployed) {
+                    give(r, deployed);
+                    notes.push(`${name} (${r.component}): using the deployed one, ${deployed}`);
+                    continue;
+                }
+                const up = running.get(name);
+                if (up && up.branch === r.branch && up.started.ok) {
+                    up.usedAt = now();
+                    const url = Object.values(up.started.endpoints)[0];
+                    if (url) {
+                        give(r, url);
+                        notes.push(`${name} (${r.component}): already running, ${url}`);
+                        continue;
+                    }
+                }
+                const dir = await checkout(r);
+                if (!dir) {
+                    notes.push(`${name} (${r.component}): not running — it could not be checked out here`);
+                    continue;
+                }
+                const stored = d.storedScript(r.repository);
+                const started = await d.start(dir, (t) => d.log('tool', `${name}: ${t}`), r.environmentScript, stored ? { script: stored } : {});
+                if (!started.ran) {
+                    notes.push(`${name} (${r.component}): not running — it has no start script; declare an address for ${environment || 'this environment'} on Integrations → Repositories, or a start script`);
+                    continue;
+                }
+                if (!started.ok) {
+                    notes.push(`${name} (${r.component}): did not start — ${started.detail.split('\n').pop()}`);
+                    continue;
+                }
+                running.set(name, { dir, branch: r.branch, started, usedAt: now(), ...(r.environmentScript ? { declared: r.environmentScript } : {}), ...(stored ? { stored } : {}) });
+                const url = Object.values(started.endpoints)[0];
+                if (url) {
+                    give(r, url);
+                    notes.push(`${name} (${r.component}): started, ${url}`);
+                }
+                else
+                    notes.push(`${name} (${r.component}): started, but printed no address`);
+            }
+            return { env, notes };
+        },
+        /** Stop services nothing has needed for a while. */
+        async stopIdle() {
+            for (const [name, s] of running) {
+                if (now() - s.usedAt < SERVICE_IDLE_MS)
+                    continue;
+                running.delete(name);
+                await d.stop(s.dir, s.declared, s.stored).catch(() => false);
+                d.log('tool', `${name}: stopped — no card has needed it for ${Math.round(SERVICE_IDLE_MS / 3_600_000)}h`);
+            }
+        },
+        async stopAll() {
+            for (const [name, s] of running) {
+                running.delete(name);
+                await d.stop(s.dir, s.declared, s.stored).catch(() => false);
+            }
+        },
+    };
+}
+//# sourceMappingURL=services.js.map

package/dist/features/services.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.js","sourceRoot":"","sources":["../../src/features/services.ts"],"names":[],"mappings":"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"}