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

package/dist/device.js

@@ -0,0 +1,61 @@
+// DEVICE CODE SIGN IN FOR THE BRIDGE (RFC 8628). THE PERSON TYPES THE CODE ON THE SERVER'S /device PAGE; NOTHING IS PRE FILLED.
+// -- DEP-MODULES -- //
+import { createHash, randomBytes } from 'node:crypto';
+// -- FUNCTIONS -- //
+/** How long one sign in call may take. The wait between polls is separate. */
+export const DEVICE_CALL_TIMEOUT_MS = 30_000;
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function deviceLogin(server, fetchImpl, log, options = {}) {
+    const wait = options.wait ?? sleep;
+    const verifier = options.pkce ? randomBytes(32).toString('base64url') : null;
+    const start = await fetchImpl(`${server}/oauth/device/code`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            client_name: options.name ?? 'agent-flow-board bridge',
+            ...(verifier
+                ? {
+                    code_challenge: createHash('sha256').update(verifier).digest('base64url'),
+                    code_challenge_method: 'S256'
+                }
+                : {})
+        }),
+        signal: AbortSignal.timeout(DEVICE_CALL_TIMEOUT_MS)
+    });
+    if (!start.ok)
+        throw new Error(`The server refused the sign in (${start.status}).`);
+    const d = (await start.json());
+    options.onCode?.({
+        userCode: d.user_code,
+        verifier,
+        verificationUri: d.verification_uri,
+        expiresInSeconds: d.expires_in
+    });
+    log(`To sign in, open ${d.verification_uri} and type this code: ${d.user_code}`);
+    log(`The code works for ${Math.floor(d.expires_in / 60)} minutes. Waiting for you to approve it...`);
+    let interval = d.interval * 1000;
+    const deadline = Date.now() + d.expires_in * 1000;
+    while (Date.now() < deadline) {
+        await wait(interval);
+        const res = await fetchImpl(`${server}/oauth/token`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                device_code: d.device_code
+            }).toString(),
+            signal: AbortSignal.timeout(DEVICE_CALL_TIMEOUT_MS)
+        });
+        const body = (await res.json());
+        if (body.access_token)
+            return { token: body.access_token, expiresInSeconds: body.expires_in ?? 0 };
+        if (body.error === 'authorization_pending')
+            continue;
+        if (body.error === 'slow_down') {
+            interval += 5000;
+            continue;
+        }
+        throw new Error(body.error_description ?? body.error ?? 'The sign in failed.');
+    }
+    throw new Error('The code expired before it was approved. Run the command again.');
+}

package/dist/hooks/adapters.js

@@ -0,0 +1,216 @@
+// THE THREE HOOK ADAPTERS: EACH TOOL'S OWN PAYLOAD TO ONE SMALL EVENT, AND THE SERVER'S ANSWER BACK IN THE TOOL'S OWN SHAPE (SPEC 9.3)
+// Claude Code and Antigravity payloads follow what was captured on real runs. The Gemini CLI mapping follows its documented hook
+// protocol and has not been captured on a real install. Every adapter prints one JSON object, `{}` when there is nothing to say.
+// -- CONSTANTS -- //
+// The board under its older name, and under a per organisation connection name (afb-<org-slug>)
+const BOARD_SERVER = /agent[-_]flow[-_]board|^(?:mcp_+)?afb-[a-z0-9]/i;
+// -- FUNCTIONS -- //
+const text = (v) => (typeof v === 'string' ? v : '');
+const obj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+/** The item a close call names, when the call is a close at all. */
+function closingFrom(args) {
+    const status = text(args.status).toUpperCase();
+    const item = text(args.item) || text(args.id);
+    return item && (status === 'COMPLETED' || status === 'REMOVED') && args.dryRun !== true
+        ? [{ item, status }]
+        : [];
+}
+// -- CLAUDE CODE -- //
+export const claude = {
+    tool: 'claude-code',
+    toEvent(_name, p) {
+        const sessionId = text(p.session_id);
+        if (!sessionId)
+            return null;
+        const base = {
+            tool: 'claude-code',
+            externalId: sessionId,
+            cwd: text(p.cwd) || undefined
+        };
+        const hook = text(p.hook_event_name);
+        // The editor mod reads the status file, so the events that can change what a conversation works on ask for the status:
+        // the start, each prompt, the stop, and a call of the board's own tools (a claim, a step, a release). Plain edits and reads do not.
+        if (hook === 'SessionStart')
+            return { ...base, event: 'start', status: true };
+        if (hook === 'UserPromptSubmit')
+            return { ...base, event: 'prompt', status: true };
+        // The conversation ended: the server lets go of this session's claim
+        if (hook === 'SessionEnd')
+            return { ...base, event: 'end' };
+        if (hook === 'Stop')
+            return { ...base, event: 'stop', stopActive: p.stop_hook_active === true, status: true };
+        const tool = text(p.tool_name);
+        const input = obj(p.tool_input);
+        if (hook === 'PreToolUse') {
+            if (/^mcp__.*__(item_status|flow_set_status)$/.test(tool) && BOARD_SERVER.test(tool)) {
+                const closing = closingFrom(input);
+                return closing.length ? { ...base, event: 'closing', closing } : null;
+            }
+            return null;
+        }
+        if (hook !== 'PostToolUse')
+            return null;
+        const subagent = Boolean(p.agent_id);
+        let action = { kind: 'read' };
+        if (/^(Edit|Write|MultiEdit|NotebookEdit)$/.test(tool))
+            action = { kind: 'edit', file: text(input.file_path) || text(input.notebook_path) };
+        else if (/^(Bash|PowerShell)$/.test(tool))
+            action = { kind: 'shell', command: text(input.command) };
+        else if (tool.startsWith('mcp__') && BOARD_SERVER.test(tool))
+            action = { kind: 'board', name: tool.split('__').pop() ?? '' };
+        return {
+            ...base,
+            event: 'tool',
+            subagent,
+            action,
+            ...(action.kind === 'board' ? { status: true } : {})
+        };
+    },
+    toOutput(event, a) {
+        if (!a)
+            return {};
+        if (event === 'start')
+            return {
+                hookSpecificOutput: {
+                    hookEventName: 'SessionStart',
+                    additionalContext: a.context ?? '',
+                    ...(a.title ? { sessionTitle: a.title } : {})
+                }
+            };
+        if (event === 'prompt' && a.title)
+            return { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', sessionTitle: a.title } };
+        // The nudge rides back from PostToolUse as context the agent reads before its next step
+        if (event === 'tool' && a.nudge)
+            return { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: a.nudge } };
+        if (event === 'closing' && a.ask)
+            return {
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'ask',
+                    permissionDecisionReason: a.ask
+                }
+            };
+        if (event === 'stop' && a.block)
+            return { decision: 'block', reason: a.block };
+        return {};
+    }
+};
+// -- ANTIGRAVITY AND agy -- //
+const AGY_EDIT = /^(write_to_file|replace_file_content|multi_replace_file_content|edit_file|create_file|delete_file)$/;
+export const antigravity = {
+    tool: 'antigravity',
+    toEvent(name, p) {
+        const conversation = text(p.conversationId);
+        if (!/^[A-Za-z0-9-]{8,64}$/.test(conversation))
+            return null;
+        const base = {
+            tool: 'antigravity',
+            // The prefix keeps a conversation id apart from the ids other tools use
+            externalId: `agy-${conversation}`,
+            cwd: (Array.isArray(p.workspacePaths) ? text(p.workspacePaths[0]) : '') || undefined
+        };
+        if (name === 'PreInvocation')
+            return Number(p.invocationNum ?? 0) === 0 ? { ...base, event: 'start' } : null;
+        if (name === 'Stop')
+            return { ...base, event: 'stop' };
+        if (name !== 'PostToolUse')
+            return null;
+        const call = obj(p.toolCall);
+        const args = obj(call.args);
+        const failed = text(p.error).trim() !== '';
+        const tool = text(call.name);
+        let action = { kind: 'read' };
+        if (AGY_EDIT.test(tool) || typeof args.TargetFile === 'string')
+            action = { kind: 'edit', file: text(args.TargetFile) || text(args.AbsolutePath) };
+        else if (tool === 'run_command')
+            action = { kind: 'shell', command: text(args.CommandLine) };
+        else if (tool === 'call_mcp_tool' && BOARD_SERVER.test(text(args.ServerName)))
+            action = { kind: 'board', name: text(args.ToolName) };
+        return { ...base, event: 'tool', failed, action };
+    },
+    toOutput(event, a) {
+        if (!a)
+            return {};
+        // Antigravity has no hook output that names a conversation, so the board label carries the title instead
+        if (event === 'start' && a.context)
+            return { injectSteps: [{ ephemeralMessage: a.context }] };
+        // GAP: no PostToolUse output was captured for Antigravity, so the nudge is not sent here. Its sessions still hear the
+        // progress line in every board reply and the Stop reminder, which name the steps that are not recorded.
+        // A Stop "continue" re-enters the agent loop. The server sends at most one per distinct code change.
+        if (event === 'stop' && a.block)
+            return { decision: 'continue', reason: a.block };
+        return {};
+    }
+};
+// -- GEMINI CLI -- //
+export const gemini = {
+    tool: 'gemini',
+    toEvent(_name, p) {
+        const sessionId = text(p.session_id);
+        if (!sessionId)
+            return null;
+        const base = { tool: 'gemini', externalId: sessionId, cwd: text(p.cwd) || undefined };
+        const hook = text(p.hook_event_name);
+        if (hook === 'SessionStart')
+            return { ...base, event: 'start' };
+        if (hook === 'BeforeAgent')
+            return { ...base, event: 'prompt' };
+        if (hook === 'AfterAgent')
+            return { ...base, event: 'stop', stopActive: p.stop_hook_active === true };
+        const tool = text(p.tool_name);
+        const input = obj(p.tool_input);
+        if (hook === 'BeforeTool') {
+            if (/^mcp_.*(item_status|flow_set_status)$/.test(tool) && BOARD_SERVER.test(tool)) {
+                const closing = closingFrom(input);
+                return closing.length ? { ...base, event: 'closing', closing } : null;
+            }
+            return null;
+        }
+        if (hook !== 'AfterTool')
+            return null;
+        let action = { kind: 'read' };
+        if (/^(write_file|replace|edit)$/.test(tool))
+            action = { kind: 'edit', file: text(input.file_path) || text(input.path) };
+        else if (tool === 'run_shell_command')
+            action = { kind: 'shell', command: text(input.command) };
+        else if (tool.startsWith('mcp_') && BOARD_SERVER.test(tool))
+            action = { kind: 'board', name: tool.split('_').pop() ?? '' };
+        return { ...base, event: 'tool', action };
+    },
+    toOutput(event, a) {
+        if (!a)
+            return {};
+        if (event === 'start')
+            return {
+                hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: a.context ?? '' }
+            };
+        // Not captured on a real install: AfterTool takes additionalContext in the documented protocol
+        if (event === 'tool' && a.nudge)
+            return { hookSpecificOutput: { hookEventName: 'AfterTool', additionalContext: a.nudge } };
+        // Gemini cannot ask before a tool call, so the close question is a message, never a block
+        if (event === 'closing' && a.ask)
+            return { systemMessage: a.ask };
+        if (event === 'stop' && a.block)
+            return { decision: 'deny', reason: a.block };
+        return {};
+    }
+};
+export const ADAPTERS = {
+    claude,
+    'claude-code': claude,
+    antigravity,
+    agy: antigravity,
+    gemini
+};
+/** Runs one hook: payload in, one JSON object out. Never throws, never blocks. */
+export async function runHook(adapter, name, payload, call) {
+    try {
+        const event = adapter.toEvent(name, payload);
+        if (!event)
+            return {};
+        return adapter.toOutput(event.event, await call(event));
+    }
+    catch {
+        return {};
+    }
+}

package/dist/hooks/call.js

@@ -0,0 +1,74 @@
+// 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';
+// -- 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;
+        }
+        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(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/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) };
+    }
+}