@agent-flow-board/bridge 0.0.0-stage → 0.2.0

package/dist/hooks/call.js

@@ -0,0 +1,79 @@
+// CALLING THE SERVER FROM A HOOK. A HOOK MUST BE QUICK AND MUST NEVER BREAK THE TOOL, SO EVERY FAILURE BECOMES AN EMPTY ANSWER.
+// -- DEP-MODULES -- //
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { configDir } from '../tokenStore.js';
+import { installedModVersion } from './modVersion.js';
+// -- CONSTANTS -- //
+const TIMEOUT_MS = 4000;
+// -- FUNCTIONS -- //
+/** The slug of the org the token belongs to, remembered in the bridge's folder so each hook costs one request. */
+async function orgOf(server, token, fetchImpl) {
+    // Named by the token too, so signing in again as another organisation does not keep sending to the old one
+    const who = createHash('sha256').update(token).digest('hex').slice(0, 12);
+    const file = join(configDir(), `org-${new URL(server).host.replace(/[^A-Za-z0-9.-]/g, '_')}-${who}.txt`);
+    try {
+        const cached = readFileSync(file, 'utf8').trim();
+        if (cached)
+            return cached;
+    }
+    catch {
+        /* Not remembered yet */
+    }
+    const res = await fetchImpl(`${server}/api/v1/me`, {
+        headers: { authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(TIMEOUT_MS)
+    });
+    if (!res.ok)
+        return null;
+    const me = (await res.json());
+    const slug = me.orgs?.[0]?.slug ?? null;
+    if (slug) {
+        mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+        writeFileSync(file, slug, { mode: 0o600 });
+    }
+    return slug;
+}
+// -- STATES -- //
+let warned = false;
+// -- FUNCTIONS -- //
+/** A hook still answers empty when it cannot reach the board, but says why once on stderr so the failure is not silent. */
+function warnOnce(reason) {
+    if (warned)
+        return;
+    warned = true;
+    process.stderr.write(`agent-flow-board hook: ${reason}
+`);
+}
+/** Sends one event and returns the answer, or null on any problem (no token, offline, a refusal, a slow server). */
+export async function callHook(o, event) {
+    if (!o.token) {
+        warnOnce('no sign-in found, so no progress reminder or claim release will reach the board. Run: agent-flow-board login');
+        return null;
+    }
+    try {
+        const org = await orgOf(o.server, o.token, o.fetch);
+        if (!org) {
+            warnOnce(`the server ${o.server} did not give an organisation for this sign-in.`);
+            return null;
+        }
+        // A Claude Code start tells the board which editor status mod is installed, so it can say when a newer one is served
+        const modVersion = event.tool === 'claude-code' && event.event === 'start'
+            ? installedModVersion(o.home)
+            : undefined;
+        const res = await o.fetch(`${o.server}/api/v1/orgs/${org}/hooks`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${o.token}`, 'content-type': 'application/json' },
+            body: JSON.stringify(modVersion ? { ...event, modVersion } : event),
+            signal: AbortSignal.timeout(TIMEOUT_MS)
+        });
+        if (!res.ok)
+            warnOnce(`the server answered ${res.status} to a hook event.`);
+        return res.ok ? (await res.json()) : null;
+    }
+    catch {
+        warnOnce(`the server ${o.server} could not be reached, so the board is not told about this session.`);
+        return null;
+    }
+}

package/dist/hooks/gitHook.js

@@ -0,0 +1,56 @@
+// THE LOCAL GIT HOOK: A POST-COMMIT WARNING WHEN A COMMIT NAMES NO BOARD ITEM. WARN ONLY, IT NEVER BLOCKS A COMMIT (ADR-014)
+// The hook is a short block between markers, so it can sit beside a hook the person already has and be removed cleanly.
+// -- DEP-MODULES -- //
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+// -- CONSTANTS -- //
+const START = '# >>> agent-flow-board (warn only) >>>';
+const END = '# <<< agent-flow-board <<<';
+const BLOCK = `${START}
+# Warns when a commit names no board item. It never blocks, and it does nothing when the tool is not installed.
+if command -v agent-flow-board >/dev/null 2>&1; then agent-flow-board git-hook check || true; fi
+${END}`;
+const TRAILER = /^(?:board-item|items?|refs?|closes|fixes)\s*:\s*\S/im;
+const SUBJECT_REF = /\([A-Za-z][A-Za-z0-9]{1,9}-[A-Za-z0-9][A-Za-z0-9-]{0,30}\)\s*$/;
+// -- FUNCTIONS -- //
+function hookPath(repo) {
+    const rel = execFileSync('git', ['-C', repo, 'rev-parse', '--git-path', 'hooks/post-commit'], {
+        encoding: 'utf8'
+    }).trim();
+    return resolve(repo, rel);
+}
+/** Adds the warning to the repository's post-commit hook, next to anything already there. Returns the file. */
+export function installGitHook(repo) {
+    const path = hookPath(repo);
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    if (existing?.includes(START))
+        return { path, created: false };
+    mkdirSync(dirname(path), { recursive: true });
+    const head = existing ?? '#!/bin/sh\n';
+    writeFileSync(path, `${head.replace(/\n*$/, '\n')}\n${BLOCK}\n`);
+    chmodSync(path, 0o755);
+    return { path, created: existing === null };
+}
+/** Removes only the block this tool wrote. A hook that held nothing else is left empty of it. */
+export function uninstallGitHook(repo) {
+    const path = hookPath(repo);
+    if (!existsSync(path))
+        return false;
+    const text = readFileSync(path, 'utf8');
+    if (!text.includes(START))
+        return false;
+    const start = text.indexOf(START);
+    const end = text.indexOf(END, start);
+    writeFileSync(path, (text.slice(0, start) + text.slice(end + END.length)).replace(/\n{3,}/g, '\n\n'));
+    return true;
+}
+/** The warning for a commit message, or null when it names an item. */
+export function checkCommit(message) {
+    if (TRAILER.test(message) || SUBJECT_REF.test((message.split('\n')[0] ?? '').trim()))
+        return null;
+    return 'This commit names no board item. Add a line such as "Item: CKT-20261017-0950" to the message, or ignore this when the work belongs to no item. The board only warns.';
+}
+export function lastCommitMessage(repo) {
+    return execFileSync('git', ['-C', repo, 'log', '-1', '--format=%B'], { encoding: 'utf8' });
+}

package/dist/hooks/modVersion.js

@@ -0,0 +1,26 @@
+// THE VERSION OF THE EDITOR STATUS MOD THIS PERSON HAS INSTALLED (AFB-20261108-0856)
+// The setup prompt writes the mod to ~/.claude/skills/afb-flow-status. The hook sends the version on a start so the board can say
+// when a newer one is served. A hook must never fail or slow down because of this file, so every problem means "no version".
+// -- DEP-MODULES -- //
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// -- CONSTANTS -- //
+const MOD_FOLDER = ['.claude', 'skills', 'afb-flow-status'];
+const VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}$/;
+/** A manifest is a few hundred bytes: a file far bigger than that is not read. */
+const MAX_BYTES = 64 * 1024;
+// -- FUNCTIONS -- //
+/** The installed mod's plain major.minor.patch version, or undefined when there is no mod, no readable manifest or no plain version. */
+export function installedModVersion(home = homedir()) {
+    try {
+        const text = readFileSync(join(home, ...MOD_FOLDER, '.claude-plugin', 'plugin.json'), 'utf8');
+        if (text.length > MAX_BYTES)
+            return undefined;
+        const version = JSON.parse(text).version;
+        return typeof version === 'string' && VERSION.test(version) ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hooks/settings.js

@@ -0,0 +1,49 @@
+// THE HOOK SETTINGS EACH TOOL NEEDS, PRINTED FOR THE PERSON TO PASTE. THE BRIDGE NEVER EDITS A TOOL'S SETTINGS BY ITSELF.
+// Hook commands carry no quotes around their paths, so they work where a shell strips them (cmd /c on Windows).
+// -- FUNCTIONS -- //
+/** The settings block for one tool, or null for a name that is not known. */
+export function hookSettings(tool, server, org) {
+    // With an organisation the hook reads that organisation's sign in
+    const bin = (adapter, event = '') => `agent-flow-board hook ${adapter}${event ? ` ${event}` : ''} --server ${server}${org ? ` --org ${org}` : ''}`;
+    if (tool === 'claude' || tool === 'claude-code') {
+        const command = (timeout) => [{ type: 'command', command: bin('claude'), timeout }];
+        return JSON.stringify({
+            hooks: {
+                SessionStart: [{ hooks: command(15) }],
+                UserPromptSubmit: [{ hooks: command(10) }],
+                PreToolUse: [{ matcher: '^mcp__.*__(item_status|flow_set_status)$', hooks: command(10) }],
+                PostToolUse: [{ matcher: '.*', hooks: command(10) }],
+                Stop: [{ hooks: command(20) }],
+                // The conversation ended: the server lets go of this session's claim
+                SessionEnd: [{ hooks: command(10) }]
+            }
+        }, null, 2);
+    }
+    if (tool === 'antigravity' || tool === 'agy') {
+        const at = (event, timeout) => ({
+            type: 'command',
+            command: bin('antigravity', event),
+            timeout
+        });
+        return JSON.stringify({
+            'agent-flow-board': {
+                PostToolUse: [{ matcher: '*', hooks: [at('PostToolUse', 15)] }],
+                PreInvocation: [at('PreInvocation', 25)],
+                Stop: [at('Stop', 25)]
+            }
+        }, null, 2);
+    }
+    if (tool === 'gemini') {
+        const command = (timeout) => [{ type: 'command', command: bin('gemini'), timeout }];
+        return JSON.stringify({
+            hooks: {
+                SessionStart: [{ hooks: command(15000) }],
+                BeforeAgent: [{ hooks: command(10000) }],
+                BeforeTool: [{ matcher: 'mcp_.*(item_status|flow_set_status)', hooks: command(10000) }],
+                AfterTool: [{ matcher: '.*', hooks: command(10000) }],
+                AfterAgent: [{ hooks: command(20000) }]
+            }
+        }, null, 2);
+    }
+    return null;
+}

package/dist/hooks/setup.js

@@ -0,0 +1,124 @@
+// THE SETUP COMMAND: PUT THE BRIDGE'S CLAUDE CODE HOOKS INTO A REPO'S SETTINGS FILE WITHOUT TOUCHING ANYTHING ELSE IN IT.
+// An earlier rule said the bridge never edits a tool's settings by itself (settings.ts). This command is the one place that does, and
+// only when the person or an agent runs it on purpose: it merges, it keeps every hook that is not the bridge's, it backs the file up
+// outside the repo first, and it refuses a file it cannot read as plain JSON instead of guessing.
+// -- DEP-MODULES -- //
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { hookSettings } from './settings.js';
+// -- CONSTANTS -- //
+/** A command of the bridge's Claude hook, whatever its server, organisation or timeout. */
+const BRIDGE_HOOK = /(^|[\\/\s"'])agent-flow-board(\.cmd|\.exe)?["']?\s+hook\s+claude\b/;
+// -- FUNCTIONS -- //
+const isBridge = (entry) => Array.isArray(entry.hooks) &&
+    entry.hooks.length > 0 &&
+    entry.hooks.every((h) => typeof h.command === 'string' && BRIDGE_HOOK.test(h.command));
+/**
+ * What the settings file should hold after setup. `existing` is the file's text, or null when there is none. Hooks of the bridge are
+ * replaced (so a run with another organisation changes them, and a second run changes nothing); every other hook, key and entry stays.
+ */
+export function planSetup(existing, server, org) {
+    const generated = hookSettings('claude', server, org);
+    if (!generated)
+        return { ok: false, error: 'No hook settings for Claude Code.' };
+    const wanted = JSON.parse(generated).hooks ?? {};
+    let settings = {};
+    if (existing !== null && existing.trim() !== '') {
+        try {
+            const parsed = JSON.parse(existing);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                return { ok: false, error: 'The settings file is not a JSON object.' };
+            settings = parsed;
+        }
+        catch {
+            return {
+                ok: false,
+                error: 'The settings file is not plain JSON (a comment or a trailing comma?), so it was not changed. Add the hooks by hand: agent-flow-board hooks print claude --server <address> --org <slug>'
+            };
+        }
+    }
+    if (settings.hooks !== undefined &&
+        (typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)))
+        return { ok: false, error: 'The "hooks" key of the settings file is not an object.' };
+    const hooks = { ...(settings.hooks ?? {}) };
+    let added = 0;
+    let replaced = 0;
+    let kept = 0;
+    for (const [event, entries] of Object.entries(wanted)) {
+        const current = Array.isArray(hooks[event]) ? hooks[event] : [];
+        const others = current.filter((e) => !isBridge(e));
+        const ours = current.filter(isBridge);
+        kept += others.length;
+        // The bridge's entries go last and in a fixed order, so running it again gives the same file
+        hooks[event] = [...others, ...entries];
+        const same = JSON.stringify(ours) === JSON.stringify(entries);
+        if (ours.length === 0)
+            added += entries.length;
+        else if (!same)
+            replaced += entries.length;
+    }
+    // Events the file has that the bridge does not use stay as they are
+    for (const [event, entries] of Object.entries(hooks))
+        if (!(event in wanted) && Array.isArray(entries))
+            kept += entries.length;
+    const next = { ...settings, hooks };
+    // Compared as data, so a file that only differs in how it is spaced is left as the person wrote it
+    const changed = existing === null || JSON.stringify(settings) !== JSON.stringify(next);
+    return {
+        ok: true,
+        text: JSON.stringify(next, null, '\t') + '\n',
+        added,
+        replaced,
+        kept,
+        changed
+    };
+}
+/** Where the backup of a repo's settings file goes: the bridge's own folder, never the repo, so it cannot be committed by accident. */
+export function backupPath(configDir, file, now = Date.now()) {
+    const key = createHash('sha256').update(resolve(file)).digest('hex').slice(0, 12);
+    const stamp = new Date(now).toISOString().replace(/[:.]/g, '-');
+    return join(configDir, 'backups', `${key}-${stamp}.bak`);
+}
+/** Runs the setup for one repo folder. Writes the file atomically; backs the old one up first. Never throws. */
+export function runSetup(options) {
+    try {
+        const file = join(options.repo, '.claude', options.shared ? 'settings.json' : 'settings.local.json');
+        const existing = existsSync(file) ? readFileSync(file, 'utf8') : null;
+        const plan = planSetup(existing, options.server, options.org);
+        if (!plan.ok)
+            return { ok: false, error: `${file}: ${plan.error}` };
+        if (!plan.changed)
+            return {
+                ok: true,
+                file,
+                changed: false,
+                added: 0,
+                replaced: 0,
+                kept: plan.kept,
+                backup: null
+            };
+        let backup = null;
+        if (existing !== null) {
+            backup = backupPath(options.configDir, file, options.now);
+            mkdirSync(dirname(backup), { recursive: true, mode: 0o700 });
+            writeFileSync(backup, existing, { mode: 0o600 });
+        }
+        mkdirSync(dirname(file), { recursive: true });
+        const temp = `${file}.${process.pid}.tmp`;
+        writeFileSync(temp, plan.text);
+        renameSync(temp, file);
+        return {
+            ok: true,
+            file,
+            changed: true,
+            added: plan.added,
+            replaced: plan.replaced,
+            kept: plan.kept,
+            backup
+        };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/hooks/statusFile.js

@@ -0,0 +1,116 @@
+// THE STATUS FILE OF A CONVERSATION: WHAT THE BOARD SAYS IT WORKS ON, KEPT BESIDE THE BRIDGE FOR AN EDITOR STATUS LINE.
+// The hook answer carries the status when the bridge asks for it. The bridge writes it to <config dir>/status/<conversation id>.json
+// so the editor mod reads a local file and needs no token. The file holds the status fields only, never a token or a verifier.
+// A hook must never fail or slow down because of this file, so every function here swallows its errors.
+// -- DEP-MODULES -- //
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- CONSTANTS -- //
+/** Files older than this are removed when a conversation starts. */
+export const PURGE_AFTER_MS = 2 * 24 * 60 * 60 * 1000;
+const ENDED = '.ended';
+const TEMP = '.tmp';
+/** A rename over a file another process holds can fail for a moment on Windows (antivirus, a parallel hook). */
+const RENAME_TRIES = 4;
+// -- FUNCTIONS -- //
+/**
+ * The file name of a conversation, or null when its id is not plain. An id comes from a tool's payload, so it is never used as a
+ * path unless it is made only of letters, digits, dots, dashes and underscores and does not start with a dot.
+ */
+export function statusName(externalId) {
+    return /^[A-Za-z0-9_-][A-Za-z0-9._-]{7,99}$/.test(externalId) ? externalId : null;
+}
+/** Waits a few milliseconds without spinning, for the retry of a rename. */
+function pause(ms) {
+    try {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    }
+    catch {
+        /* No wait available: the retry runs at once */
+    }
+}
+function writeAtomic(dir, name, body) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const temp = join(dir, `${name}.${process.pid}${TEMP}`);
+    writeFileSync(temp, body, { mode: 0o600 });
+    for (let i = 0; i < RENAME_TRIES; i++) {
+        try {
+            renameSync(temp, join(dir, `${name}.json`));
+            return;
+        }
+        catch (error) {
+            if (i === RENAME_TRIES - 1) {
+                rmSync(temp, { force: true });
+                throw error;
+            }
+            pause(15 * (i + 1));
+        }
+    }
+}
+/** The time the file in place was asked for, or 0 when there is none or it cannot be read. */
+function askedAtOf(dir, name) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, `${name}.json`), 'utf8'));
+        return typeof parsed.asOf === 'number' ? parsed.asOf : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Removes the files nobody asked for in two days: finished conversations, crashed ones and leftovers of a failed write. */
+export function purgeStatus(dir, now = Date.now()) {
+    try {
+        for (const file of readdirSync(dir)) {
+            const path = join(dir, file);
+            try {
+                if (now - statSync(path).mtimeMs > PURGE_AFTER_MS)
+                    rmSync(path, { force: true });
+            }
+            catch {
+                /* A file that vanished meanwhile is gone, which is the point */
+            }
+        }
+    }
+    catch {
+        /* No folder yet */
+    }
+}
+/**
+ * Applies one hook event to the files. `asked` is the time the request left, so two answers that come back in the wrong order never
+ * replace a newer file with an older one. It never throws and never prints.
+ */
+export function applyStatusFile(dir, event, answer, asked, now = Date.now()) {
+    try {
+        const name = statusName(event.externalId);
+        if (!name)
+            return;
+        if (event.event === 'end') {
+            // A last hook of the same conversation may still be on its way: the marker keeps it from writing the file again
+            rmSync(join(dir, `${name}.json`), { force: true });
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            writeFileSync(join(dir, `${name}${ENDED}`), String(now), { mode: 0o600 });
+            return;
+        }
+        if (event.event === 'start') {
+            // A resumed conversation starts again under the same id
+            rmSync(join(dir, `${name}${ENDED}`), { force: true });
+            purgeStatus(dir, now);
+        }
+        if (!event.status)
+            return;
+        if (existsSync(join(dir, `${name}${ENDED}`)))
+            return;
+        if (!answer?.status) {
+            // The board did not answer a call that may have changed the claim: an old file would show a wrong item
+            if (event.event === 'tool')
+                rmSync(join(dir, `${name}.json`), { force: true });
+            return;
+        }
+        if (askedAtOf(dir, name) > asked)
+            return;
+        writeAtomic(dir, name, JSON.stringify({ v: 1, asOf: asked, writtenAt: now, status: answer.status }));
+    }
+    catch {
+        /* A failed write is never a failed hook */
+    }
+}

package/dist/mockup.js

@@ -0,0 +1,145 @@
+// agent-flow-board mockup push <file.html>: UPLOADS ONE MOCKUP FILE TO THE BOARD OVER /api/v1 WITH THE BRIDGE'S OWN SIGN IN
+// It reads the file by path from the agent's own folder, so the HTML never passes through a model's output. It is never queued, never
+// goes through the MCP forwarder and changes nothing in the bridge protocol: a failed push says so and the agent runs it again.
+// -- DEP-MODULES -- //
+import { randomBytes } from 'node:crypto';
+import { lstatSync, readFileSync } from 'node:fs';
+import { extname } from 'node:path';
+// -- CONSTANTS -- //
+/** The server's own cap for one version (50 MB). The server checks it again, this only stops a hopeless upload early. */
+export const MAX_MOCKUP_BYTES = 50 * 1024 * 1024;
+export const MAX_SCREENSHOT_BYTES = 5 * 1024 * 1024;
+const TRIES = 3;
+/** A kit's summary travels in the address, so it is kept short here. */
+const MAX_KIT_SUMMARY = 4000;
+// -- FUNCTIONS -- //
+/** The message of a failed call: the server's own words when it sent them. */
+async function failure(res) {
+    try {
+        const j = (await res.json());
+        if (j.error?.message)
+            return `${j.error.message} (${res.status})`;
+    }
+    catch {
+        /* Not JSON */
+    }
+    return `The server answered ${res.status}.`;
+}
+/** Only a plain HTML or PNG file of a sane size is read: never a link, a folder or some other file an agent was talked into naming. */
+function readFileChecked(path, kinds, max, what) {
+    const st = lstatSync(path, { throwIfNoEntry: false });
+    if (!st)
+        throw new Error(`The ${what} file ${path} does not exist.`);
+    if (!st.isFile())
+        throw new Error(`The ${what} path ${path} is not a plain file.`);
+    if (!kinds.includes(extname(path).toLowerCase()))
+        throw new Error(`The ${what} must be a ${kinds.join(' or ')} file.`);
+    if (st.size === 0)
+        throw new Error(`The ${what} file is empty.`);
+    if (st.size > max)
+        throw new Error(`The ${what} is ${Math.ceil(st.size / 1024 / 1024)} MB, more than the ${Math.floor(max / 1024 / 1024)} MB limit.`);
+    return new Uint8Array(readFileSync(path));
+}
+/** One call, tried again on a network failure or a 5xx with the same request id, so a repeat can never publish twice. */
+async function call(o, method, path, body, headers, requestId) {
+    let last = 'The server could not be reached.';
+    for (let i = 0; i < TRIES; i++) {
+        try {
+            const res = await o.fetch(`${o.server}/api/v1${path}`, {
+                method,
+                body,
+                headers: {
+                    authorization: `Bearer ${o.token}`,
+                    'idempotency-key': requestId,
+                    ...headers
+                }
+            });
+            if (res.status < 500)
+                return res;
+            last = await failure(res);
+        }
+        catch (e) {
+            last = e instanceof Error ? e.message : String(e);
+        }
+        if (i < TRIES - 1)
+            await (o.wait ?? ((ms) => new Promise((r) => setTimeout(r, ms))))(500 * (i + 1));
+    }
+    throw new Error(last);
+}
+export async function pushMockup(o) {
+    if (!o.token)
+        throw new Error('Not signed in. Run: agent-flow-board login --server <url> --org <slug>');
+    if (!o.item && !o.project && !o.mockup)
+        throw new Error('Name the plan (--item), a project (--project) or the mockup (--mockup).');
+    const html = readFileChecked(o.file, ['.html', '.htm'], MAX_MOCKUP_BYTES, 'mockup');
+    const shot = o.screenshot
+        ? readFileChecked(o.screenshot, ['.png'], MAX_SCREENSHOT_BYTES, 'screenshot')
+        : null;
+    const id = randomBytes(8).toString('hex');
+    const base = `/orgs/${encodeURIComponent(o.org)}`;
+    const q = new URLSearchParams();
+    for (const [k, v] of [
+        ['item', o.item],
+        ['project', o.project],
+        ['mockup', o.mockup],
+        ['title', o.title]
+    ])
+        if (v)
+            q.set(k, v);
+    if (o.another)
+        q.set('another', 'true');
+    const res = await call(o, 'POST', `${base}/mockups?${q}`, html, { 'content-type': 'text/html' }, `mockup-push-${id}`);
+    if (!res.ok)
+        throw new Error(await failure(res));
+    const made = (await res.json());
+    const at = `${base}/mockups/${made.mockup.id}/versions/${made.version.number}`;
+    let notes = false;
+    if (o.keepNotes || o.freeNotes) {
+        const n = await call(o, 'PUT', `${at}/notes`, JSON.stringify({ keepNotes: o.keepNotes ?? '', freeNotes: o.freeNotes ?? '' }), { 'content-type': 'application/json' }, `mockup-notes-${id}`);
+        if (!n.ok)
+            o.log(`The mockup is published, but its notes were not saved: ${await failure(n)}`);
+        else
+            notes = true;
+    }
+    let screenshot = false;
+    if (shot) {
+        const s = await call(o, 'PUT', `${at}/screenshot`, shot, { 'content-type': 'image/png' }, `mockup-shot-${id}`);
+        if (!s.ok)
+            o.log(`The mockup is published, but its screenshot was not saved: ${await failure(s)}`);
+        else
+            screenshot = true;
+    }
+    const warnings = made.warnings ?? [];
+    for (const w of warnings)
+        o.log(`Warning: ${w}`);
+    return {
+        mockupId: made.mockup.id,
+        version: made.version.number,
+        url: `${o.server}/${o.org}/${made.projectKey}/mockups/${made.mockup.id}`,
+        notes,
+        screenshot,
+        warnings
+    };
+}
+/** Uploads the project's kit file (colours, fonts, icons) by path, the same way. The warnings are printed and never change the exit code. */
+export async function pushKit(o) {
+    if (!o.token)
+        throw new Error('Not signed in. Run: agent-flow-board login --server <url> --org <slug>');
+    const html = readFileChecked(o.file, ['.html', '.htm'], MAX_MOCKUP_BYTES, 'kit');
+    const q = new URLSearchParams();
+    if (o.commit)
+        q.set('builtFromCommit', o.commit.slice(0, 80));
+    if (o.summary) {
+        if (o.summary.length > MAX_KIT_SUMMARY)
+            throw new Error(`The summary is ${o.summary.length.toLocaleString('en-US')} characters; the bridge sends at most ${MAX_KIT_SUMMARY.toLocaleString('en-US')}. Shorten it.`);
+        q.set('summary', o.summary);
+    }
+    const res = await call(o, 'PUT', `/orgs/${encodeURIComponent(o.org)}/projects/${encodeURIComponent(o.project)}/mockup-kit?${q}`, html, { 'content-type': 'text/html' }, `mockup-kit-${randomBytes(8).toString('hex')}`);
+    if (!res.ok)
+        throw new Error(await failure(res));
+    const made = (await res.json());
+    const warnings = made.warnings ?? [];
+    for (const w of warnings)
+        o.log(`Warning: ${w}`);
+    return { number: made.number, warnings };
+}