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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arben Apura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @agent-flow-board/bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The local bridge to an [Agent Flow Board](https://afb.arbenger.com) server. It forwards the board's MCP over stdio, runs the hooks of your coding tool (Claude Code, Antigravity, Gemini CLI) so the board stays true, and writes the status file that the editor status line reads. It holds no tool code: every tool lives on the server.
+
+## Install
+
+```
+npm install -g @agent-flow-board/bridge
+agent-flow-board
+```
+
+Needs Node 20 or later. Run it with no arguments to see its usage; the list should include `setup`. Install it globally: the hooks call the command several times per tool call, and a command started through `npx` each time is too slow.
+
+## Commands
+
+| Command                                                           | What it does                                                                                                                                                                                               |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent-flow-board login --server <url> --org <slug>`              | Signs in with a device code. The sign in is kept in your keychain, one entry per server and organisation.                                                                                                  |
+| `agent-flow-board login --json --server <url> --org <slug>`       | For an agent: line 1 holds the code and a verifier, so the agent can approve it through the board's MCP. It never prints a token.                                                                          |
+| `agent-flow-board setup --org <slug> --server <url>`              | Writes the Claude Code hooks into this repository's `.claude/settings.local.json` (`--shared` writes `settings.json`). It merges, keeps your other hooks and backs the old file up outside the repository. |
+| `agent-flow-board hooks print claude --server <url> --org <slug>` | Prints the hook settings to paste by hand.                                                                                                                                                                 |
+| `agent-flow-board mcp --server <url> --org <slug>`                | Forwards MCP over stdio, for tools that only speak stdio.                                                                                                                                                  |
+| `agent-flow-board queue list`                                     | Shows writes held while the board could not be reached.                                                                                                                                                    |
+
+The easy way to set everything up is the **Editor status** tab on the board's **Connect a tool** page: copy its prompt into Claude Code and the agent does the steps, asking you once before it writes anything.
+
+## What it writes
+
+- Your sign in: in the operating system keychain (an encrypted file where there is none).
+- `~/.agent-flow-board/status/<conversation id>.json`: what the board says a conversation works on. It holds no token and is removed when the conversation ends.
+- `~/.agent-flow-board/backups/`: backups of settings files that `setup` changed.
+
+## Licence
+
+MIT. See `LICENSE`.

package/dist/bridge.js

@@ -0,0 +1,256 @@
+// THE BRIDGE CORE (ADR-030): READS JSON-RPC LINES FROM A TOOL'S STDIN, FORWARDS EACH TO THE SERVER'S /mcp, WRITES THE REPLIES TO STDOUT.
+// It holds no tool code, schemas or workflow text, so a server update never needs a reconnect. It only adds three things:
+// sign in by device code, an offline queue for writes, and a protocol version check on start.
+// -- DEP-MODULES -- //
+import { createInterface } from 'node:readline';
+// -- CONSTANTS -- //
+export const BRIDGE_PROTOCOL_MAX = 1;
+/** The longest one request may take. A tool call can wait up to 50 seconds for a run, so this sits above that. */
+export const POST_TIMEOUT_MS = 90_000;
+const NETWORK_CODES = new Set([
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'ETIMEDOUT',
+    'ENETUNREACH',
+    'EHOSTUNREACH',
+    'EPIPE',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_SOCKET'
+]);
+// -- FUNCTIONS -- //
+/** A request that timed out: the board may or may not have taken it, so it is never treated as offline. */
+const isTimeout = (e) => e?.name === 'TimeoutError' ||
+    e?.name === 'AbortError';
+/** Only a real failure to reach the board counts. Any other TypeError is a bug and must be shown, not hidden as offline. */
+export const isNetworkError = (e) => {
+    if (!e || typeof e !== 'object')
+        return false;
+    const err = e;
+    if (err.code && NETWORK_CODES.has(err.code))
+        return true;
+    if (err.cause?.code && NETWORK_CODES.has(err.cause.code))
+        return true;
+    // Node's fetch reports a failed connection as a TypeError whose message is exactly this
+    return (e instanceof TypeError &&
+        /^(fetch failed|failed to fetch|network request failed)/i.test(String(err.message)));
+};
+/** The board refused the saved sign in. The person has to sign in again, which the bridge starts in the background. */
+class SignInNeeded extends Error {
+}
+/** Runs until stdin closes. */
+export async function runBridge(o) {
+    let token = o.getToken();
+    const postTimeout = o.postTimeoutMs ?? POST_TIMEOUT_MS;
+    let loginRunning = null;
+    /** Starts the device code sign in once. It runs in the background, so no call waits for the person to type a code. */
+    const startLogin = () => {
+        if (loginRunning)
+            return;
+        loginRunning = o
+            .login()
+            .then((t) => {
+            token = t;
+        })
+            .catch((err) => o.log(`Sign in failed: ${String(err?.message ?? err)}`))
+            .finally(() => {
+            loginRunning = null;
+        });
+    };
+    if (!token) {
+        o.log('No saved sign in. Starting the sign in.');
+        startLogin();
+    }
+    const protocolMax = o.protocolMax ?? BRIDGE_PROTOCOL_MAX;
+    let warnedProtocol = false;
+    /** Tool names known to only read, from the server's own annotations. Anything else is treated as a write. */
+    let readOnly = new Set();
+    let toolsKnown = false;
+    const write = (msg) => o.stdout.write(JSON.stringify(msg) + '\n');
+    const post = async (body) => {
+        const send = () => o.fetch(`${o.server}/mcp${o.org ? `/${o.org}` : ''}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream',
+                authorization: `Bearer ${token}`
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(postTimeout)
+        });
+        if (!token)
+            throw new SignInNeeded();
+        const res = await send();
+        if (res.status === 401) {
+            // The token expired or was revoked. The sign in starts in the background and this call says so, instead of waiting for it
+            o.log('The saved sign in is no longer valid. Starting the sign in.');
+            token = null;
+            startLogin();
+            throw new SignInNeeded();
+        }
+        return res;
+    };
+    const parse = async (res) => {
+        const text = await res.text();
+        if (!text.trim())
+            return null;
+        if ((res.headers.get('content-type') ?? '').includes('text/event-stream')) {
+            const line = text.split('\n').find((l) => l.startsWith('data:'));
+            return line ? JSON.parse(line.slice(5)) : null;
+        }
+        return JSON.parse(text);
+    };
+    const checkProtocol = (res) => {
+        const v = Number(res.headers.get('x-afb-protocol') ?? 0);
+        if (v > protocolMax && !warnedProtocol) {
+            warnedProtocol = true;
+            o.log(`This server speaks protocol ${v} and the bridge understands up to ${protocolMax}. Update it with: npx -y @agent-flow-board/bridge@latest`);
+        }
+    };
+    /** Sends one queued write as a real tools/call and says whether the board took it. */
+    const sendQueued = async (e) => {
+        try {
+            const res = await post({
+                jsonrpc: '2.0',
+                id: `replay-${Date.now()}`,
+                method: 'tools/call',
+                params: { name: e.name, arguments: e.args }
+            });
+            const body = await parse(res);
+            const result = body?.result;
+            if (res.status >= 500)
+                return { kind: 'offline' };
+            if (!res.ok || body?.error || result?.isError)
+                return {
+                    kind: 'refused',
+                    reason: result?.structuredContent?.error?.message ?? `The board answered ${res.status}.`
+                };
+            return { kind: 'ok' };
+        }
+        catch (err) {
+            if (err instanceof SignInNeeded || isTimeout(err) || isNetworkError(err))
+                return { kind: 'offline' };
+            return { kind: 'refused', reason: String(err.message) };
+        }
+    };
+    const replay = async () => {
+        if (o.queue.list().length === 0)
+            return;
+        const r = await o.queue.replay(sendQueued);
+        if (r.sent || r.held)
+            o.log(`Replayed ${r.sent} queued write${r.sent === 1 ? '' : 's'}${r.held ? `, ${r.held} held back (see: agent-flow-board queue list)` : ''}.`);
+    };
+    async function handle(msg) {
+        try {
+            const res = await post(msg);
+            checkProtocol(res);
+            const body = await parse(res);
+            if (msg.id === undefined)
+                return;
+            if (body) {
+                if (msg.method === 'tools/list') {
+                    const tools = body.result?.tools;
+                    if (tools) {
+                        readOnly = new Set(tools.filter((t) => t.annotations?.readOnlyHint).map((t) => t.name));
+                        toolsKnown = true;
+                    }
+                }
+                // An answer that failed before the server read the request (a refusal such as FORBIDDEN) carries no id: it answers this one
+                write(body.error && body.id == null ? { ...body, id: msg.id } : body);
+                void replay();
+            }
+            else
+                write({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    error: { code: -32603, message: `The board answered ${res.status} with no body.` }
+                });
+        }
+        catch (err) {
+            if (msg.id === undefined)
+                return;
+            if (err instanceof SignInNeeded) {
+                const text = 'The board did not accept the saved sign in. A sign in was started: open the address printed by the agent-flow-board bridge (or run "agent-flow-board login" in a terminal), type the code, then try again.';
+                if (msg.method === 'tools/call')
+                    write({
+                        jsonrpc: '2.0',
+                        id: msg.id,
+                        result: {
+                            isError: true,
+                            content: [{ type: 'text', text }],
+                            structuredContent: { error: { code: 'SIGN_IN_NEEDED', message: text } }
+                        }
+                    });
+                else
+                    write({ jsonrpc: '2.0', id: msg.id, error: { code: -32001, message: text } });
+                return;
+            }
+            if (isTimeout(err)) {
+                write({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    error: {
+                        code: -32000,
+                        message: `The board did not answer within ${Math.round(postTimeout / 1000)} seconds. The request may or may not have been applied: read the item before sending it again.`
+                    }
+                });
+                return;
+            }
+            if (!isNetworkError(err)) {
+                write({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    error: { code: -32603, message: String(err.message) }
+                });
+                return;
+            }
+            // The board cannot be reached. Reads say so, writes are queued and say they are queued.
+            const name = msg.params?.name;
+            if (msg.method === 'tools/call' && name && toolsKnown && !readOnly.has(name)) {
+                const q = o.queue.enqueue(name, msg.params?.arguments ?? {});
+                const out = {
+                    queued: true,
+                    queueId: q.id,
+                    message: 'The board cannot be reached. This write was saved on this computer and will be sent when it is back, in order. Nothing was recorded yet.'
+                };
+                write({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    result: { content: [{ type: 'text', text: JSON.stringify(out) }], structuredContent: out }
+                });
+            }
+            else {
+                write({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    error: {
+                        code: -32000,
+                        message: 'offline: the board cannot be reached, so this cannot be read right now.'
+                    }
+                });
+            }
+        }
+    }
+    const rl = createInterface({ input: o.stdin });
+    let chain = Promise.resolve();
+    rl.on('line', (line) => {
+        if (!line.trim())
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+            return;
+        }
+        // One message at a time keeps the order of writes exactly as the tool sent them
+        chain = chain.then(() => handle(msg));
+    });
+    const timer = o.replayEveryMs === 0 ? null : setInterval(() => void replay(), o.replayEveryMs ?? 15_000);
+    await new Promise((resolve) => rl.on('close', resolve));
+    await chain;
+    if (timer)
+        clearInterval(timer);
+}

package/dist/cli.js

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+// agent-flow-board mcp --server <url> [--org <slug>]   forward MCP over stdio to the server (to /mcp/<slug> with --org)
+// agent-flow-board login --server <url> [--org <slug>] sign in by device code
+// agent-flow-board login --json --server <url> --org <slug>   for an agent: line 1 holds userCode and verifier, it approves through MCP
+// agent-flow-board setup --org <slug> --server <url> [--dir <repo>] [--shared]   write the Claude hooks into the repo's .claude/settings.local.json
+// agent-flow-board logout --server <url> [--org <slug>]
+// agent-flow-board queue list | retry <id> | drop <id>
+// agent-flow-board hook claude|antigravity|gemini [event]   one hook event from stdin, one JSON object to stdout
+// agent-flow-board hooks print claude|antigravity|gemini [--org <slug>]   the settings to paste into the tool
+// agent-flow-board git-hook install|uninstall|check          the warn-only post-commit hook
+// agent-flow-board mockup push <file.html> --server <url> --org <slug> --item <ref>   upload one mockup file (never queued)
+// agent-flow-board mockup kit <file.html> --server <url> --org <slug> --project <key>   upload the project's kit (colours, fonts, icons)
+// -- DEP-MODULES -- //
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runBridge } from './bridge.js';
+import { ADAPTERS, runHook } from './hooks/adapters.js';
+import { callHook } from './hooks/call.js';
+import { checkCommit, installGitHook, lastCommitMessage, uninstallGitHook } from './hooks/gitHook.js';
+import { hookSettings } from './hooks/settings.js';
+import { runSetup } from './hooks/setup.js';
+import { applyStatusFile } from './hooks/statusFile.js';
+import { deviceLogin } from './device.js';
+import { pushKit, pushMockup } from './mockup.js';
+import { Queue } from './queue.js';
+import { accountKey, configDir, pickStore } from './tokenStore.js';
+// -- FUNCTIONS -- //
+const args = process.argv.slice(2);
+const flag = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+const cmd = args[0];
+const log = (s) => process.stderr.write(s + '\n');
+function serverUrl() {
+    const s = flag('--server') ?? process.env.AFB_SERVER;
+    if (!s) {
+        log('Say which server to use: --server https://board.example.com (or set AFB_SERVER).');
+        process.exit(2);
+    }
+    return s.replace(/\/$/, '');
+}
+/** An organisation slug as the app writes it. Anything else is ignored by a hook and refused by the other commands. */
+const ORG_SLUG = /^[a-z0-9][a-z0-9-]{1,38}$/;
+/** The organisation this run is for (--org), or undefined for the plain server sign in as before. */
+function orgFlag(strict = true) {
+    const o = flag('--org');
+    if (o === undefined)
+        return undefined;
+    if (ORG_SLUG.test(o))
+        return o;
+    if (strict) {
+        log('--org takes an organisation slug: lowercase letters, digits and dashes.');
+        process.exit(2);
+    }
+    return undefined;
+}
+const store = pickStore();
+/**
+ * The saved sign in for a server and organisation. Only the MCP bridge (legacy true) also tries an older sign in saved under the plain
+ * host, because /mcp/<slug> answers 403 if it is the wrong organisation. Hooks have no such check, so they never borrow it.
+ */
+const tokenFor = (server, org, legacy = false) => process.env.AFB_TOKEN ??
+    store.get(accountKey(server, org)) ??
+    (org && legacy ? store.get(accountKey(server)) : null);
+const queue = new Queue(join(configDir(), 'queue.json'));
+const fetchImpl = (input, init) => fetch(input, init);
+async function readStdin() {
+    const chunks = [];
+    for await (const c of process.stdin)
+        chunks.push(c);
+    const text = Buffer.concat(chunks).toString('utf8').trim();
+    try {
+        return text ? JSON.parse(text) : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Asks the organisation's own address whether this sign in belongs to it. Only a 403 means another organisation. */
+async function belongsToOrg(server, org, token) {
+    try {
+        const res = await fetchImpl(`${server}/mcp/${org}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream',
+                authorization: `Bearer ${token}`
+            },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'ping' })
+        });
+        // Only a refusal means another organisation, or no valid sign in
+        return res.status !== 403 && res.status !== 401;
+    }
+    catch {
+        // The board cannot be reached right now: keep the sign in, the first call checks again
+        return true;
+    }
+}
+async function main() {
+    if (cmd === 'hook') {
+        // A hook prints exactly one JSON object and always exits 0, so it can never break the tool that runs it
+        let out = {};
+        try {
+            const adapter = ADAPTERS[args[1] ?? ''];
+            const server = (flag('--server') ?? process.env.AFB_SERVER ?? '').replace(/\/$/, '');
+            if (adapter && server) {
+                const token = tokenFor(server, orgFlag(false));
+                out = await runHook(adapter, args[2] ?? '', await readStdin(), async (event) => {
+                    const asked = Date.now();
+                    const answer = await callHook({ server, token, fetch: fetchImpl }, event);
+                    // The status goes to this conversation's file, never to the tool. A failed write never fails the hook.
+                    applyStatusFile(join(configDir(), 'status'), event, answer, asked);
+                    return answer;
+                });
+            }
+        }
+        catch {
+            out = {};
+        }
+        process.stdout.write(JSON.stringify(out));
+        return;
+    }
+    if (cmd === 'hooks' && args[1] === 'print') {
+        const text = hookSettings(args[2] ?? '', serverUrl());
+        if (!text) {
+            log('Say which tool: claude, antigravity or gemini.');
+            process.exit(2);
+        }
+        process.stdout.write(text + '\n');
+        return;
+    }
+    if (cmd === 'git-hook') {
+        const repo = flag('--dir') ?? process.cwd();
+        if (args[1] === 'install') {
+            const r = installGitHook(repo);
+            log(r.created ? `Installed ${r.path}.` : `Already installed in ${r.path}.`);
+        }
+        else if (args[1] === 'uninstall') {
+            log(uninstallGitHook(repo) ? 'Removed.' : 'Nothing to remove.');
+        }
+        else if (args[1] === 'check') {
+            // Warn only: print the warning to the terminal and never fail the commit
+            const warning = checkCommit(lastCommitMessage(repo));
+            if (warning)
+                log(warning);
+        }
+        else {
+            log('Usage: agent-flow-board git-hook install|uninstall|check [--dir <repo>]');
+            process.exit(2);
+        }
+        return;
+    }
+    if (cmd === 'mockup') {
+        // One upload over /api/v1 with this machine's own sign in. It is never queued, so a failure is said out loud and run again
+        if (!['push', 'kit'].includes(args[1] ?? '') || !args[2] || args[2].startsWith('--')) {
+            log('Usage: agent-flow-board mockup push <file.html> --server <url> --org <slug> (--item <ref> | --project <key> | --mockup <id>) [--another] [--title <text>] [--keep <text> | --keep-file <path>] [--free <text> | --free-file <path>] [--screenshot <file.png>]\n       agent-flow-board mockup kit <file.html> --server <url> --org <slug> --project <key> [--commit <hash>] [--summary <text>]');
+            process.exit(2);
+        }
+        const server = serverUrl();
+        const org = orgFlag();
+        if (!org) {
+            log('Say which organisation: --org <slug>.');
+            process.exit(2);
+        }
+        if (args[1] === 'kit') {
+            const project = flag('--project');
+            if (!project) {
+                log('Say which project: --project <key>.');
+                process.exit(2);
+            }
+            const kit = await pushKit({
+                server,
+                org,
+                token: tokenFor(server, org, true) ?? '',
+                fetch: fetchImpl,
+                file: args[2],
+                project,
+                commit: flag('--commit'),
+                summary: flag('--summary'),
+                log
+            });
+            process.stdout.write(JSON.stringify(kit) + '\n');
+            return;
+        }
+        const text = (inline, file) => {
+            const path = flag(file);
+            return path ? readFileSync(path, 'utf8') : flag(inline);
+        };
+        const result = await pushMockup({
+            server,
+            org,
+            token: tokenFor(server, org, true) ?? '',
+            fetch: fetchImpl,
+            file: args[2],
+            item: flag('--item'),
+            project: flag('--project'),
+            mockup: flag('--mockup'),
+            another: args.includes('--another'),
+            title: flag('--title'),
+            keepNotes: text('--keep', '--keep-file'),
+            freeNotes: text('--free', '--free-file'),
+            screenshot: flag('--screenshot'),
+            log
+        });
+        process.stdout.write(JSON.stringify(result) + '\n');
+        return;
+    }
+    if (cmd === 'queue') {
+        const sub = args[1];
+        if (sub === 'retry' && args[2])
+            log(queue.retry(args[2]) ? 'Queued again.' : 'No such queued write.');
+        else if (sub === 'drop' && args[2])
+            log(queue.drop(args[2]) ? 'Dropped.' : 'No such queued write.');
+        else
+            for (const e of queue.list())
+                log(`${e.id}  ${e.state.padEnd(6)}  ${e.name}  ${e.key}${e.reason ? `  held: ${e.reason}` : ''}`);
+        return;
+    }
+    if (cmd === 'logout') {
+        const server = serverUrl();
+        const org = orgFlag();
+        store.delete(accountKey(server, org));
+        // An older sign in under the plain host may be what this organisation was using, so it goes too
+        if (org)
+            store.delete(accountKey(server));
+        log('Signed out.');
+        return;
+    }
+    if (cmd === 'setup') {
+        const server = serverUrl();
+        const org = orgFlag();
+        if (!org) {
+            log('setup needs --org <slug>: the organisation the hooks send to.');
+            process.exit(2);
+        }
+        const token = tokenFor(server, org);
+        if (!token) {
+            log(`Not signed in to ${org} on ${server}. Run: agent-flow-board login --json --server ${server} --org ${org}`);
+            process.exit(1);
+        }
+        if (!(await belongsToOrg(server, org, token))) {
+            log(`The saved sign in is not for ${org}. Run the login for ${org} again.`);
+            process.exit(1);
+        }
+        const result = runSetup({
+            repo: flag('--dir') ?? process.cwd(),
+            server,
+            org,
+            shared: args.includes('--shared'),
+            configDir: configDir()
+        });
+        process.stdout.write(JSON.stringify(result) + '\n');
+        if (!result.ok) {
+            log(`Setup failed: ${result.error}`);
+            process.exit(1);
+        }
+        log(result.changed
+            ? `Wrote ${result.file}: ${result.added} hook(s) added, ${result.replaced} replaced, ${result.kept} other hook(s) kept.${result.backup ? ` The old file is backed up at ${result.backup}.` : ''}`
+            : `${result.file} already has these hooks. Nothing was changed.`);
+        return;
+    }
+    if (cmd !== 'mcp' && cmd !== 'login') {
+        log('Usage: agent-flow-board mcp|login|logout --server <url>, setup --org <slug>, queue list|retry <id>|drop <id>, or mockup push <file.html>');
+        process.exit(2);
+    }
+    const server = serverUrl();
+    const org = orgFlag();
+    const account = accountKey(server, org);
+    // login --json is for an agent: the first line on stdout holds the code and the verifier it needs to approve the sign in through MCP
+    const asJson = cmd === 'login' && args.includes('--json');
+    if (asJson && !org) {
+        log('login --json needs --org <slug>: the agent approves the sign in for that organisation.');
+        process.exit(2);
+    }
+    const login = async () => {
+        const r = await deviceLogin(server, fetchImpl, log, asJson
+            ? {
+                pkce: true,
+                onCode: (c) => process.stdout.write(JSON.stringify(c) + '\n')
+            }
+            : {});
+        // The device approval lets the person choose the organisation, so it is checked against the one asked for before it is kept
+        if (org && !(await belongsToOrg(server, org, r.token))) {
+            throw new Error(`That sign in is for a different organisation than ${org}. It was not saved. Run the sign in again and choose ${org} when the approval page asks.`);
+        }
+        store.set(account, r.token);
+        log('Signed in.');
+        return r.token;
+    };
+    if (cmd === 'login') {
+        await login();
+        // The second line says it worked, with no token
+        if (asJson)
+            process.stdout.write(JSON.stringify({ signedIn: true, server, org }) + '\n');
+        return;
+    }
+    await runBridge({
+        server,
+        org,
+        fetch: fetchImpl,
+        getToken: () => tokenFor(server, org, true),
+        login,
+        queue,
+        stdin: process.stdin,
+        stdout: process.stdout,
+        log
+    });
+    // A background sign in may still be polling when the tool closes the bridge, and it must not keep this process alive
+    setTimeout(() => process.exit(0), 500).unref();
+}
+main().catch((e) => {
+    log(String(e instanceof Error ? e.message : e));
+    process.exit(1);
+});