@brainmcp/brainmcp 0.1.12 → 0.1.14

package/dist/commands/dispatch.js

@@ -0,0 +1,287 @@
+import { cwd, stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import { BRAINMCP_CLI_PACKAGE_SPEC, BRAINMCP_GLOBAL_CLIENTS } from '../agent-config.js';
+import { CLI_EXIT_CODES } from '../lib/cli-contracts.js';
+import { assertClientId, CLIENT_IDS, clientLabel } from '../lib/config.js';
+import { doctor, init, initAll, printConfig, remove, } from './index.js';
+import { login, logout, whoami } from './auth.js';
+import { runHookRuntimeCli } from '../runtime/index.js';
+import { captureStatus, captureEnable, captureDisable, captureNow, capturePurgeLocal, capturePurgePreview, } from './capture.js';
+export const HELP = `brainmcp — configure BrainMCP for agent projects and authenticate companion CLI
+
+Recommended setup (supported agents, all projects):
+  npx --yes ${BRAINMCP_CLI_PACKAGE_SPEC} init --all --scope user
+
+Usage:
+  brainmcp init [--client <client>] [--workspace <id>] [--scope project|user] [--no-hooks] [--write-back-nudge] [--yes]
+  brainmcp init --all [--workspace <id>] [--scope project|user] [--no-hooks] [--write-back-nudge] [--yes]
+  brainmcp doctor [--client <client>] [--workspace <id>] [--scope project|user]
+  brainmcp print [--client <client>] [--workspace <id>] [--scope project|user]
+  brainmcp remove [--client <client>] [--scope project|user] [--yes]
+  brainmcp login [--capture-digests] [--allow-file-credentials] [--service-token-stdin] [--store-service-token] [--force] [--json]
+  brainmcp logout [--json]
+  brainmcp whoami [--json]
+  brainmcp hook <client> <event>
+  brainmcp capture [enable|disable|status|now|purge-local] [--dry-run] [--workspace <id>] [--include-prompts] [--yes] [--json]
+
+Clients: ${CLIENT_IDS.join(', ')}
+--all configures ${BRAINMCP_GLOBAL_CLIENTS.map(clientLabel).join(', ')} (generic is client-specific).
+Project scope is the default. User scope writes to each host's supported per-user locations.
+Every mutation previews a diff and needs confirmation unless a trailing CLI --yes is supplied.
+The leading npx --yes above accepts npm's package download; it does not skip the file preview.`;
+export function parseCliArgs(args) {
+    const [command, ...rawOptions] = args;
+    const result = {
+        command,
+        yes: false,
+        all: false,
+        captureDigests: false,
+        force: false,
+        json: false,
+        noHooks: false,
+        writeBackNudge: false,
+        enable: false,
+        disable: false,
+        status: false,
+        dryRun: false,
+        purge: false,
+        includePrompts: false,
+        now: false,
+        allowFileCredentials: false,
+        serviceTokenStdin: false,
+        storeServiceToken: false,
+    };
+    for (let index = 0; index < rawOptions.length; index += 1) {
+        const option = rawOptions[index];
+        if (option === '--yes' || option === '-y')
+            result.yes = true;
+        else if (option === '--all')
+            result.all = true;
+        else if (option === '--capture-digests')
+            result.captureDigests = true;
+        else if (option === '--force')
+            result.force = true;
+        else if (option === '--json')
+            result.json = true;
+        else if (option === '--enable' || option === 'enable')
+            result.enable = true;
+        else if (option === '--disable' || option === 'disable')
+            result.disable = true;
+        else if (option === '--status' || option === 'status')
+            result.status = true;
+        else if (option === '--dry-run')
+            result.dryRun = true;
+        else if (option === '--purge' || option === 'purge-local')
+            result.purge = true;
+        else if (option === '--include-prompts')
+            result.includePrompts = true;
+        else if (option === '--now' || option === 'now')
+            result.now = true;
+        else if (option === '--allow-file-credentials')
+            result.allowFileCredentials = true;
+        else if (option === '--service-token-stdin')
+            result.serviceTokenStdin = true;
+        else if (option === '--store-service-token')
+            result.storeServiceToken = true;
+        else if (option === '--no-hooks')
+            result.noHooks = true;
+        else if (option === '--write-back-nudge')
+            result.writeBackNudge = true;
+        else if (option === '--client')
+            result.client = assertClientId(readValue(rawOptions, ++index, option));
+        else if (option === '--workspace')
+            result.workspace = readValue(rawOptions, ++index, option);
+        else if (option === '--scope') {
+            const scope = readValue(rawOptions, ++index, option);
+            if (scope !== 'project' && scope !== 'user')
+                throw new Error('--scope must be project or user.');
+            result.scope = scope;
+        }
+        else if (option === '--root')
+            result.root = readValue(rawOptions, ++index, option);
+        else
+            throw new Error(`Unknown option: ${option}`);
+    }
+    if (command === 'capture') {
+        const actions = [result.enable, result.disable, result.status, result.now, result.purge].filter(Boolean);
+        if (actions.length > 1) {
+            throw new Error('Choose exactly one capture action: enable, disable, status, now, or purge-local.');
+        }
+        const effectiveNow = result.now || (actions.length === 0 && result.dryRun);
+        if (result.dryRun && !effectiveNow) {
+            throw new Error('--dry-run is valid only with `capture now`.');
+        }
+        if (result.includePrompts && !result.enable) {
+            throw new Error('--include-prompts is valid only with `capture enable`.');
+        }
+        if (result.workspace && !result.enable && !effectiveNow) {
+            throw new Error('--workspace is valid only with `capture enable` or `capture now`.');
+        }
+    }
+    return result;
+}
+function readValue(args, index, option) {
+    const value = args[index];
+    if (!value || value.startsWith('-'))
+        throw new Error(`${option} requires a value.`);
+    return value;
+}
+export async function defaultConfirm(message) {
+    if (!stdin.isTTY || !stdout.isTTY)
+        return false;
+    const readline = createInterface({ input: stdin, output: stdout });
+    try {
+        return (await readline.question(`${message} [y/N] `)).trim().toLowerCase() === 'y';
+    }
+    finally {
+        readline.close();
+    }
+}
+export async function dispatch(rawArgs, context = {}) {
+    const output = context.output ?? console.log;
+    const confirmFn = context.confirm ?? defaultConfirm;
+    const currentRoot = context.cwd ?? cwd();
+    const [command] = rawArgs;
+    if (!command || command === '--help' || command === '-h' || command === 'help') {
+        output(HELP);
+        return CLI_EXIT_CODES.SUCCESS;
+    }
+    if (command === 'hook') {
+        await runHookRuntimeCli(rawArgs.slice(1));
+        return CLI_EXIT_CODES.SUCCESS;
+    }
+    let parsed;
+    try {
+        parsed = parseCliArgs(rawArgs);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return CLI_EXIT_CODES.USAGE_ERROR;
+    }
+    if (parsed.all && parsed.client) {
+        console.error('Use either --all or --client, not both.');
+        return CLI_EXIT_CODES.USAGE_ERROR;
+    }
+    if (parsed.all && parsed.command !== 'init') {
+        console.error('--all is currently supported only by init.');
+        return CLI_EXIT_CODES.USAGE_ERROR;
+    }
+    const legacyOptions = {
+        root: parsed.root ?? currentRoot,
+        client: parsed.client,
+        workspace: parsed.workspace,
+        scope: parsed.scope ?? 'project',
+        yes: parsed.yes,
+        noHooks: parsed.noHooks,
+        writeBackNudge: parsed.writeBackNudge,
+        output,
+        confirm: confirmFn,
+    };
+    try {
+        switch (parsed.command) {
+            case 'init':
+                await (parsed.all ? initAll(legacyOptions) : init(legacyOptions));
+                return CLI_EXIT_CODES.SUCCESS;
+            case 'doctor':
+                await doctor(legacyOptions);
+                return CLI_EXIT_CODES.SUCCESS;
+            case 'print':
+                await printConfig(legacyOptions);
+                return CLI_EXIT_CODES.SUCCESS;
+            case 'remove':
+                await remove(legacyOptions);
+                return CLI_EXIT_CODES.SUCCESS;
+            case 'login':
+                if (parsed.serviceTokenStdin && parsed.captureDigests) {
+                    console.error('Service credential login cannot be mixed with --capture-digests.');
+                    return CLI_EXIT_CODES.USAGE_ERROR;
+                }
+                await login({
+                    captureDigests: parsed.captureDigests,
+                    force: parsed.force,
+                    json: parsed.json,
+                    allowFileCredentials: parsed.allowFileCredentials,
+                    serviceTokenStdin: parsed.serviceTokenStdin,
+                    storeServiceToken: parsed.storeServiceToken,
+                    output,
+                    openBrowser: context.openBrowser,
+                    store: context.store,
+                    oauthClient: context.oauthClient,
+                });
+                return CLI_EXIT_CODES.SUCCESS;
+            case 'logout':
+                await logout({
+                    json: parsed.json,
+                    output,
+                    store: context.store,
+                    oauthClient: context.oauthClient,
+                });
+                return CLI_EXIT_CODES.SUCCESS;
+            case 'whoami':
+                await whoami({
+                    json: parsed.json,
+                    output,
+                    store: context.store,
+                    apiClient: context.apiClient,
+                });
+                return CLI_EXIT_CODES.SUCCESS;
+            case 'capture': {
+                let result;
+                if (parsed.enable) {
+                    result = await captureEnable({
+                        baseDir: context.baseDir,
+                        includePrompts: parsed.includePrompts,
+                        workspace: parsed.workspace,
+                        apiClient: context.apiClient,
+                        store: context.store,
+                    });
+                }
+                else if (parsed.disable) {
+                    result = captureDisable({ baseDir: context.baseDir });
+                }
+                else if (parsed.purge) {
+                    const preview = capturePurgePreview({ baseDir: context.baseDir });
+                    const previewText = `${preview.queueItems} queue item(s), ${preview.sessionLedgers} session ledger(s), and ${preview.orientationCacheFiles} orientation cache file(s)`;
+                    const confirmed = parsed.yes || await confirmFn(`Delete ${previewText}? Credentials, preferences, and host configuration will be preserved.`);
+                    result = confirmed
+                        ? capturePurgeLocal({ baseDir: context.baseDir })
+                        : {
+                            exitCode: CLI_EXIT_CODES.SUCCESS,
+                            data: { purged: false, preview, message: 'Local capture purge cancelled; no files were deleted.' },
+                        };
+                }
+                else if (parsed.now || parsed.dryRun) {
+                    result = await captureNow({
+                        dryRun: parsed.dryRun,
+                        baseDir: context.baseDir,
+                        cwd: currentRoot,
+                        workspace: parsed.workspace,
+                        apiClient: context.apiClient,
+                        store: context.store,
+                    });
+                }
+                else {
+                    result = captureStatus({ baseDir: context.baseDir, json: parsed.json });
+                }
+                if (parsed.json) {
+                    output(JSON.stringify(result.data, null, 2));
+                }
+                else if (typeof result.data === 'object' && result.data !== null && 'message' in result.data) {
+                    output(String(result.data.message));
+                }
+                else {
+                    output(JSON.stringify(result.data, null, 2));
+                }
+                return result.exitCode;
+            }
+            default:
+                console.error(`Unknown command: ${parsed.command}\n\n${HELP}`);
+                return CLI_EXIT_CODES.USAGE_ERROR;
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return CLI_EXIT_CODES.GENERAL_ERROR;
+    }
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/commands/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/commands/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAItG,OAAO,EACL,MAAM,EACN,IAAI,EACJ,OAAO,EACP,WAAW,EACX,MAAM,GAEP,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,MAAM,CAAC,MAAM,IAAI,GAAG;;;cAGN,yBAAyB;;;;;;;;;;;;;;WAc5B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;mBACb,uBAAuB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;;;+FAGyB,CAAC;AA2BhG,MAAM,UAAU,YAAY,CAAC,IAAc;IACzC,MAAM,CAAC,OAAO,EAAE,GAAG,UAAU,CAAC,GAAG,IAAI,CAAC;IACtC,MAAM,MAAM,GAAkB;QAC5B,OAAO;QACP,GAAG,EAAE,KAAK;QACV,GAAG,EAAE,KAAK;QACV,cAAc,EAAE,KAAK;QACrB,KAAK,EAAE,KAAK;QACZ,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,KAAK;QACd,cAAc,EAAE,KAAK;QACrB,MAAM,EAAE,KAAK;QACb,OAAO,EAAE,KAAK;QACd,MAAM,EAAE,KAAK;QACb,MAAM,EAAE,KAAK;QACb,KAAK,EAAE,KAAK;QACZ,cAAc,EAAE,KAAK;QACrB,GAAG,EAAE,KAAK;QACV,oBAAoB,EAAE,KAAK;QAC3B,iBAAiB,EAAE,KAAK;QACxB,iBAAiB,EAAE,KAAK;KACzB,CAAC;IAEF,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAE,CAAC;QAClC,IAAI,MAAM,KAAK,OAAO,IAAI,MAAM,KAAK,IAAI;YAAE,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC;aACxD,IAAI,MAAM,KAAK,OAAO;YAAE,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC;aAC1C,IAAI,MAAM,KAAK,mBAAmB;YAAE,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;aACjE,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC;aAC9C,IAAI,MAAM,KAAK,QAAQ;YAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;aAC5C,IAAI,MAAM,KAAK,UAAU,IAAI,MAAM,KAAK,QAAQ;YAAE,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC;aACvE,IAAI,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;aAC1E,IAAI,MAAM,KAAK,UAAU,IAAI,MAAM,KAAK,QAAQ;YAAE,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC;aACvE,IAAI,MAAM,KAAK,WAAW;YAAE,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC;aACjD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,aAAa;YAAE,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC;aAC1E,IAAI,MAAM,KAAK,mBAAmB;YAAE,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;aACjE,IAAI,MAAM,KAAK,OAAO,IAAI,MAAM,KAAK,KAAK;YAAE,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC;aAC9D,IAAI,MAAM,KAAK,0BAA0B;YAAE,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAC;aAC9E,IAAI,MAAM,KAAK,uBAAuB;YAAE,MAAM,CAAC,iBAAiB,GAAG,IAAI,CAAC;aACxE,IAAI,MAAM,KAAK,uBAAuB;YAAE,MAAM,CAAC,iBAAiB,GAAG,IAAI,CAAC;aACxE,IAAI,MAAM,KAAK,YAAY;YAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;aACnD,IAAI,MAAM,KAAK,oBAAoB;YAAE,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;aAClE,IAAI,MAAM,KAAK,UAAU;YAAE,MAAM,CAAC,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;aAClG,IAAI,MAAM,KAAK,aAAa;YAAE,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;aACxF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,SAAS,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;YACrD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;YACjG,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;QACvB,CAAC;aAAM,IAAI,MAAM,KAAK,QAAQ;YAAE,MAAM,CAAC,IAAI,GAAG,SAAS,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;;YAChF,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACzG,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAC;QACtG,CAAC;QACD,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;QAC3E,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,MAAM,CAAC,cAAc,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,SAAS,CAAC,IAAc,EAAE,KAAa,EAAE,MAAc;IAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,oBAAoB,CAAC,CAAC;IACpF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAe;IAClD,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAChD,MAAM,QAAQ,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnE,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,QAAQ,CAAC,QAAQ,CAAC,GAAG,OAAO,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,GAAG,CAAC;IACrF,CAAC;YAAS,CAAC;QACT,QAAQ,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAcD,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAiB,EAAE,UAA2B,EAAE;IAC7E,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC;IAC7C,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,IAAI,cAAc,CAAC;IACpD,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC;IAEzC,MAAM,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC1B,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QAC/E,MAAM,CAAC,IAAI,CAAC,CAAC;QACb,OAAO,cAAc,CAAC,OAAO,CAAC;IAChC,CAAC;IAED,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1C,OAAO,cAAc,CAAC,OAAO,CAAC;IAChC,CAAC;IAED,IAAI,MAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAChE,OAAO,cAAc,CAAC,WAAW,CAAC;IACpC,CAAC;IAED,IAAI,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACzD,OAAO,cAAc,CAAC,WAAW,CAAC;IACpC,CAAC;IAED,IAAI,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;QAC5C,OAAO,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAC5D,OAAO,cAAc,CAAC,WAAW,CAAC;IACpC,CAAC;IAED,MAAM,aAAa,GAAmB;QACpC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,WAAW;QAChC,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,SAAS;QAChC,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,MAAM;QACN,OAAO,EAAE,SAAS;KACnB,CAAC;IAEF,IAAI,CAAC;QACH,QAAQ,MAAM,CAAC,OAAO,EAAE,CAAC;YACvB,KAAK,MAAM;gBACT,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;gBAClE,OAAO,cAAc,CAAC,OAAO,CAAC;YAChC,KAAK,QAAQ;gBACX,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;gBAC5B,OAAO,cAAc,CAAC,OAAO,CAAC;YAChC,KAAK,OAAO;gBACV,MAAM,WAAW,CAAC,aAAa,CAAC,CAAC;gBACjC,OAAO,cAAc,CAAC,OAAO,CAAC;YAChC,KAAK,QAAQ;gBACX,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;gBAC5B,OAAO,cAAc,CAAC,OAAO,CAAC;YAChC,KAAK,OAAO;gBACV,IAAI,MAAM,CAAC,iBAAiB,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;oBACtD,OAAO,CAAC,KAAK,CAAC,kEAAkE,CAAC,CAAC;oBAClF,OAAO,cAAc,CAAC,WAAW,CAAC;gBACpC,CAAC;gBACD,MAAM,KAAK,CAAC;oBACV,cAAc,EAAE,MAAM,CAAC,cAAc;oBACrC,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,oBAAoB,EAAE,MAAM,CAAC,oBAAoB;oBACjD,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;oBAC3C,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;oBAC3C,MAAM;oBACN,WAAW,EAAE,OAAO,CAAC,WAAW;oBAChC,KAAK,EAAE,OAAO,CAAC,KAAK;oBACpB,WAAW,EAAE,OAAO,CAAC,WAAW;iBACjC,CAAC,CAAC;gBACH,OAAO,cAAc,CAAC,OAAO,CAAC;YAChC,KAAK,QAAQ;gBACX,MAAM,MAAM,CAAC;oBACX,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,MAAM;oBACN,KAAK,EAAE,OAAO,CAAC,KAAK;oBACpB,WAAW,EAAE,OAAO,CAAC,WAAW;iBACjC,CAAC,CAAC;gBACH,OAAO,cAAc,CAAC,OAAO,CAAC;YAChC,KAAK,QAAQ;gBACX,MAAM,MAAM,CAAC;oBACX,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,MAAM;oBACN,KAAK,EAAE,OAAO,CAAC,KAAK;oBACpB,SAAS,EAAE,OAAO,CAAC,SAAS;iBAC7B,CAAC,CAAC;gBACH,OAAO,cAAc,CAAC,OAAO,CAAC;YAChC,KAAK,SAAS,CAAC,CAAC,CAAC;gBACf,IAAI,MAA2C,CAAC;gBAChD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;oBAClB,MAAM,GAAG,MAAM,aAAa,CAAC;wBAC3B,OAAO,EAAE,OAAO,CAAC,OAAO;wBACxB,cAAc,EAAE,MAAM,CAAC,cAAc;wBACrC,SAAS,EAAE,MAAM,CAAC,SAAS;wBAC3B,SAAS,EAAE,OAAO,CAAC,SAAS;wBAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;qBACrB,CAAC,CAAC;gBACL,CAAC;qBAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;oBAC1B,MAAM,GAAG,cAAc,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;gBACxD,CAAC;qBAAM,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;oBACxB,MAAM,OAAO,GAAG,mBAAmB,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;oBAClE,MAAM,WAAW,GAAG,GAAG,OAAO,CAAC,UAAU,mBAAmB,OAAO,CAAC,cAAc,2BAA2B,OAAO,CAAC,qBAAqB,4BAA4B,CAAC;oBACvK,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,IAAI,MAAM,SAAS,CAC7C,UAAU,WAAW,uEAAuE,CAC7F,CAAC;oBACF,MAAM,GAAG,SAAS;wBAChB,CAAC,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;wBACjD,CAAC,CAAC;4BACE,QAAQ,EAAE,cAAc,CAAC,OAAO;4BAChC,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,uDAAuD,EAAE;yBACnG,CAAC;gBACR,CAAC;qBAAM,IAAI,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;oBACvC,MAAM,GAAG,MAAM,UAAU,CAAC;wBACxB,MAAM,EAAE,MAAM,CAAC,MAAM;wBACrB,OAAO,EAAE,OAAO,CAAC,OAAO;wBACxB,GAAG,EAAE,WAAW;wBAChB,SAAS,EAAE,MAAM,CAAC,SAAS;wBAC3B,SAAS,EAAE,OAAO,CAAC,SAAS;wBAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;qBACrB,CAAC,CAAC;gBACL,CAAC;qBAAM,CAAC;oBACN,MAAM,GAAG,aAAa,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC1E,CAAC;gBACD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;oBAChB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;gBAC/C,CAAC;qBAAM,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,SAAS,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;oBAC/F,MAAM,CAAC,MAAM,CAAE,MAAM,CAAC,IAA6B,CAAC,OAAO,CAAC,CAAC,CAAC;gBAChE,CAAC;qBAAM,CAAC;oBACN,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;gBAC/C,CAAC;gBACD,OAAO,MAAM,CAAC,QAAQ,CAAC;YACzB,CAAC;YACD;gBACE,OAAO,CAAC,KAAK,CAAC,oBAAoB,MAAM,CAAC,OAAO,OAAO,IAAI,EAAE,CAAC,CAAC;gBAC/D,OAAO,cAAc,CAAC,WAAW,CAAC;QACtC,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACtE,OAAO,cAAc,CAAC,aAAa,CAAC;IACtC,CAAC;AACH,CAAC"}

package/dist/commands/index.d.ts

@@ -5,6 +5,8 @@ export type CommandOptions = {
     workspace?: string;
     scope: Scope;
     yes: boolean;
+    noHooks?: boolean;
+    writeBackNudge?: boolean;
     /** Test/embedding override. The CLI defaults to `os.homedir()`. */
     home?: string;
     /** Test/embedding override. The CLI defaults to `process.env`. */
@@ -22,3 +24,5 @@ export declare function initAll(options: CommandOptions): Promise<void>;
 export declare function remove(options: CommandOptions): Promise<void>;
 export declare function printConfig(options: CommandOptions): Promise<void>;
 export declare function doctor(options: CommandOptions): Promise<void>;
+export * from './auth.js';
+export * from './dispatch.js';

package/dist/commands/index.js

@@ -1,9 +1,14 @@
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { BRAIN_BOOTSTRAP_PROMPT, BRAIN_DOCS_URL, BRAIN_MCP_ENDPOINT, BRAIN_MCP_INITIAL_SCOPES, BRAIN_OAUTH_AUTH_METADATA_CANONICAL_URL, BRAIN_OAUTH_AUTH_METADATA_URL, BRAIN_OAUTH_ISSUER, BRAIN_OAUTH_RESOURCE_METADATA_COMPAT_URL, BRAIN_OAUTH_RESOURCE_METADATA_URL, BRAINMCP_CLI_CLIENTS, BRAINMCP_GLOBAL_CLIENTS, MCP_OAUTH_CLIENT_IDS, buildBrainmcpDoctorCommand, } from '../agent-config.js';
+import { BRAIN_BOOTSTRAP_PROMPT, BRAIN_DOCS_URL, BRAIN_MCP_ENDPOINT, BRAIN_MCP_INITIAL_SCOPES, BRAIN_OAUTH_AUTH_METADATA_CANONICAL_URL, BRAIN_OAUTH_AUTH_METADATA_URL, BRAIN_OAUTH_ISSUER, BRAIN_OAUTH_RESOURCE_METADATA_COMPAT_URL, BRAIN_OAUTH_RESOURCE_METADATA_URL, BRAINMCP_CLI_CLIENTS, BRAINMCP_GLOBAL_CLIENTS, MCP_OAUTH_CLIENT_IDS, buildBrainmcpDoctorCommand, buildBrainmcpInitCommand, buildBrainVerificationPrompt, GUIDANCE_VERSION, } from '../agent-config.js';
 import { clientLabel, guidancePreamble, renderGuidance, resolveWorkspace, targetFor, describeAntigravityServerConfig, } from '../lib/config.js';
 import { applyChanges, exists, readText, renderDiff, toAbsolute } from '../lib/files.js';
-import { parseJsonc, removeJsonServer, removeMarkdownBlock, removeTomlBlock, upsertJsonServer, upsertMarkdownBlock, upsertTomlBlock } from '../lib/managed.js';
+import { parseJsonc, removeJsoncPath, removeJsonServer, removeMarkdownBlock, removeTomlBlock, upsertJsoncPath, upsertJsonServer, upsertMarkdownBlock, upsertTomlBlock } from '../lib/managed.js';
+import { checkCredentialHealth, checkRuntimeDrift, checkConsentPreferences, checkQueueStatus, checkCompanionApiTarget } from '../runtime/doctor-checks.js';
+import { companionWorkspacesUrl } from '../lib/endpoints.js';
+import { getBrainHome } from '../runtime/storage.js';
+import { cliPackageVersion, getVersionedRuntimePath, loadPackagedRuntimeBundle, } from '../runtime/installer.js';
+import { removeClaudeManagedHooks, removeCodexManagedHooks, removeCursorManagedHooks, removeVsCodeManagedHooks, upsertClaudeManagedHooks, upsertCodexManagedHooks, upsertCursorManagedHooks, upsertVsCodeManagedHooks, } from '../hooks/managed-hooks.js';
 export async function detectClients(root) {
     const candidates = [
         ['cursor', ['.cursor', '.cursor/mcp.json']],
@@ -32,6 +37,7 @@ export async function chooseClient(options) {
 }
 export async function init(options) {
     const client = await chooseClient(options);
+    await assertSingleMcpConfigScope(options, [client]);
     const workspace = resolveWorkspace(options.workspace);
     const changes = await plannedChanges(options, client, workspace, 'init');
     await previewAndApply(changes, options);
@@ -40,6 +46,7 @@ export async function init(options) {
 }
 export async function initAll(options) {
     const workspace = resolveWorkspace(options.workspace);
+    await assertSingleMcpConfigScope(options, BRAINMCP_GLOBAL_CLIENTS);
     const groups = await Promise.all(BRAINMCP_GLOBAL_CLIENTS.map((client) => plannedChanges(options, client, workspace, 'init')));
     await previewAndApply(mergeFileChanges(groups.flat()), options);
     options.output(`BrainMCP configured for ${BRAINMCP_GLOBAL_CLIENTS.map(clientLabel).join(', ')}.`);
@@ -74,7 +81,9 @@ function renderSetupNextSteps(clients, scope, workspace) {
         '3. Log in to brain from every client you plan to use:',
         ...authorizationSteps,
         '4. In browser consent, review the scopes, select the workspace(s) this client may reach, and choose its default workspace.',
-        '5. In the project, ask: "Use brain to give me an overview of this workspace." Confirm the dashboard Connect view shows Agent seen.',
+        `5. Verify with a read-only agent prompt (guidance ${GUIDANCE_VERSION}):`,
+        `   ${buildBrainVerificationPrompt({ workspaceId: workspace })}`,
+        '   Confirm the dashboard Connect view shows Agent seen after a successful authenticated tool call.',
         '6. If the workspace is empty, copy and paste this bootstrap command into the connected agent:',
         ...BRAIN_BOOTSTRAP_PROMPT.split('\n').map((line) => `   ${line}`),
         '7. Follow the proposal status the agent reports. If it awaits Review, approve, edit, or reject it in the dashboard. The workspace is not populated until the proposal is applied.',
@@ -136,7 +145,20 @@ export async function doctor(options) {
     }
     if (guidance !== undefined) {
         const occurrences = (guidance.match(/brainmcp:managed:start/g) ?? []).length;
-        checks.push(['managed guidance markers', occurrences === 1, occurrences === 1 ? 'one managed block' : `${occurrences} managed blocks`]);
+        const normalizedGuidance = guidance.replace(/\r\n/g, '\n');
+        const ends = (guidance.match(/brainmcp:managed:end/g) ?? []).length;
+        const blocks = normalizedGuidance.match(/<!-- brainmcp:managed:start[^\n]*-->[\s\S]*?<!-- brainmcp:managed:end -->/g) ?? [];
+        const validMarkers = occurrences === 1 && ends === 1 && blocks.length === 1;
+        checks.push(['managed guidance markers', validMarkers, validMarkers ? 'one complete managed block' : `${occurrences} starts, ${ends} ends, ${blocks.length} complete blocks`]);
+        const installedWorkspace = blocks[0]?.match(/^Workspace id: (.+)$/m)?.[1]?.trim();
+        const expectedWorkspace = resolveWorkspace(options.workspace) ?? installedWorkspace;
+        const expectedGuidance = renderGuidance(client, expectedWorkspace).trim();
+        const currentGuidance = validMarkers && blocks[0] === expectedGuidance;
+        checks.push([
+            'managed guidance content', currentGuidance,
+            currentGuidance ? `matches bundled guidance ${GUIDANCE_VERSION}` :
+                `outdated or modified; preview repair with ${buildBrainmcpInitCommand({ client, scope: options.scope, workspaceId: expectedWorkspace })}`,
+        ]);
         checks.push(['workspace binding', !options.workspace || guidance.includes(`Workspace id: ${resolveWorkspace(options.workspace)}`), options.workspace ? 'requested workspace binding' : 'no workspace requested']);
         if ((client === 'vscode' || client === 'copilot') && options.scope === 'user') {
             checks.push([
@@ -157,38 +179,18 @@ export async function doctor(options) {
             ]);
         }
     }
-    if (client === 'cursor' || client === 'vscode' || client === 'copilot' || client === 'antigravity') {
-        const otherScope = options.scope === 'project' ? 'user' : 'project';
-        const otherTarget = resolveTarget({ ...options, scope: otherScope }, targetFor(client, otherScope));
-        if (otherTarget.configPath !== target.configPath) {
-            const otherConfig = await readText(otherTarget.configPath);
-            if (otherConfig === undefined) {
-                checks.push([
-                    'single MCP configuration scope',
-                    true,
-                    `no ${otherScope}-scope brain entry`,
-                ]);
-            }
-            else {
-                try {
-                    const duplicated = hasBrainServerConfig(otherConfig, otherTarget);
-                    checks.push([
-                        'single MCP configuration scope',
-                        !duplicated,
-                        duplicated
-                            ? `brain is also configured at ${otherTarget.configPath}; keep it in only one scope`
-                            : `no ${otherScope}-scope brain entry`,
-                    ]);
-                }
-                catch (error) {
-                    checks.push([
-                        'single MCP configuration scope',
-                        false,
-                        `cannot inspect ${otherTarget.configPath}: ${error instanceof Error ? error.message : String(error)}`,
-                    ]);
-                }
-            }
-        }
+    if (requiresSingleMcpConfigScope(client)) {
+        const otherScope = oppositeScope(options.scope);
+        const duplicate = await inspectOtherMcpConfigScope(options, client);
+        checks.push([
+            'single MCP configuration scope',
+            duplicate.status === 'absent',
+            duplicate.status === 'present'
+                ? `brain is also configured at ${duplicate.path}; keep it in only one scope`
+                : duplicate.status === 'invalid'
+                    ? `cannot inspect ${duplicate.path}: ${duplicate.error}`
+                    : `no ${otherScope}-scope brain entry`,
+        ]);
     }
     const fetchImpl = options.fetch ?? fetch;
     for (const [name, url] of [
@@ -253,11 +255,90 @@ export async function doctor(options) {
     catch (error) {
         checks.push(['endpoint challenge', false, error instanceof Error ? error.message : String(error)]);
     }
+    const apiOriginCheck = checkCompanionApiTarget();
+    checks.push([apiOriginCheck.name, apiOriginCheck.passed, apiOriginCheck.detail]);
+    try {
+        const workspacesUrl = companionWorkspacesUrl();
+        const workspaces = await fetchImpl(workspacesUrl, { headers: { accept: 'application/json' } });
+        const valid = workspaces.status === 401 || workspaces.status === 403;
+        checks.push([
+            'companion workspaces endpoint',
+            valid,
+            valid
+                ? `HTTP ${workspaces.status} at ${workspacesUrl}`
+                : `HTTP ${workspaces.status} at ${workspacesUrl}; companion REST belongs on the API origin, not MCP`,
+        ]);
+    }
+    catch (error) {
+        checks.push(['companion workspaces endpoint', false, error instanceof Error ? error.message : String(error)]);
+    }
+    const brainHome = options.home ? join(options.home, '.brainmcp') : getBrainHome();
+    const credCheck = await checkCredentialHealth(brainHome, { probeVault: !options.home });
+    checks.push([credCheck.name, credCheck.passed, credCheck.detail]);
+    const driftCheck = checkRuntimeDrift(cliPackageVersion(), brainHome);
+    checks.push([driftCheck.name, driftCheck.passed, driftCheck.detail]);
+    const consentCheck = checkConsentPreferences(brainHome);
+    checks.push([consentCheck.name, consentCheck.passed, consentCheck.detail]);
+    const queueCheck = checkQueueStatus(brainHome);
+    checks.push([queueCheck.name, queueCheck.passed, queueCheck.detail]);
     for (const [name, passed, detail] of checks)
         options.output(`${passed ? '✓' : '✗'} ${name}: ${detail}`);
     if (checks.some(([, passed]) => !passed))
         throw new Error('BrainMCP doctor found configuration issues.');
 }
+const SINGLE_SCOPE_MCP_CLIENTS = new Set([
+    'antigravity',
+    'codex',
+    'copilot',
+    'cursor',
+    'vscode',
+]);
+function requiresSingleMcpConfigScope(client) {
+    return SINGLE_SCOPE_MCP_CLIENTS.has(client);
+}
+function oppositeScope(scope) {
+    return scope === 'project' ? 'user' : 'project';
+}
+async function inspectOtherMcpConfigScope(options, client) {
+    const otherScope = oppositeScope(options.scope);
+    const currentTarget = resolveTarget(options, targetFor(client, options.scope));
+    const otherTarget = resolveTarget({ ...options, scope: otherScope }, targetFor(client, otherScope));
+    if (otherTarget.configPath === currentTarget.configPath) {
+        return { path: otherTarget.configPath, status: 'absent' };
+    }
+    const otherConfig = await readText(otherTarget.configPath);
+    if (otherConfig === undefined) {
+        return { path: otherTarget.configPath, status: 'absent' };
+    }
+    try {
+        return {
+            path: otherTarget.configPath,
+            status: hasBrainServerConfig(otherConfig, otherTarget) ? 'present' : 'absent',
+        };
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : String(error),
+            path: otherTarget.configPath,
+            status: 'invalid',
+        };
+    }
+}
+async function assertSingleMcpConfigScope(options, clients) {
+    for (const client of clients) {
+        if (!requiresSingleMcpConfigScope(client))
+            continue;
+        const duplicate = await inspectOtherMcpConfigScope(options, client);
+        if (duplicate.status === 'absent')
+            continue;
+        const otherScope = oppositeScope(options.scope);
+        if (duplicate.status === 'invalid') {
+            throw new Error(`Cannot inspect the existing ${clientLabel(client)} ${otherScope}-scope configuration at ${duplicate.path}: ${duplicate.error}`);
+        }
+        throw new Error(`Brain is already configured for ${clientLabel(client)} at ${duplicate.path} (${otherScope} scope). ` +
+            `Keep it in exactly one scope: run \`brainmcp remove --client ${client} --scope ${otherScope} --yes\`, then retry.`);
+    }
+}
 function hasBrainServerConfig(config, target) {
     if (target.format === 'toml') {
         return /\[mcp_servers\.brain\]/.test(config);
@@ -411,6 +492,84 @@ async function plannedChanges(options, client, workspace, mode) {
             }
         }
     }
+    const hookChanges = await plannedHookChanges(options, client, target, mode);
+    changes.push(...hookChanges);
+    return changes;
+}
+async function plannedHookChanges(options, client, target, mode) {
+    if (!target.supportsHooks || !target.hookPath)
+        return [];
+    if (mode === 'init' && options.noHooks)
+        return [];
+    const bundle = loadPackagedRuntimeBundle();
+    if (mode === 'init' && !bundle) {
+        throw new Error('The packaged BrainMCP hook runtime is missing. Reinstall or rebuild the CLI before enabling hooks.');
+    }
+    const home = options.home ?? homedir();
+    const brainHome = options.home ? join(options.home, '.brainmcp') : getBrainHome();
+    const version = cliPackageVersion();
+    const runtimePath = getVersionedRuntimePath(version, brainHome);
+    const hookFilePath = target.hookPath.startsWith('/')
+        ? target.hookPath
+        : options.scope === 'user'
+            ? join(home, target.hookPath)
+            : toAbsolute(options.root, target.hookPath);
+    const changes = [];
+    if (mode === 'init' && bundle) {
+        const existingRuntime = await readText(runtimePath);
+        if (existingRuntime !== bundle) {
+            changes.push({ path: runtimePath, before: existingRuntime, after: bundle });
+        }
+    }
+    const existingHook = await readText(hookFilePath);
+    let parsed = {};
+    if (existingHook?.trim()) {
+        parsed = parseJsonc(existingHook);
+    }
+    const next = mode === 'init'
+        ? client === 'claude-code'
+            ? upsertClaudeManagedHooks(parsed, runtimePath, { enableNudge: Boolean(options.writeBackNudge) })
+            : client === 'cursor'
+                ? upsertCursorManagedHooks(parsed, runtimePath)
+                : client === 'codex'
+                    ? upsertCodexManagedHooks(parsed, runtimePath)
+                    : upsertVsCodeManagedHooks(parsed, runtimePath)
+        : client === 'claude-code'
+            ? removeClaudeManagedHooks(parsed)
+            : client === 'cursor'
+                ? removeCursorManagedHooks(parsed)
+                : client === 'codex'
+                    ? removeCodexManagedHooks(parsed)
+                    : removeVsCodeManagedHooks(parsed);
+    const eventNames = client === 'claude-code'
+        ? ['SessionStart', 'UserPromptSubmit', 'PostToolUse', 'PreCompact', 'SessionEnd', 'Stop']
+        : client === 'cursor'
+            ? ['sessionStart', 'beforeSubmitPrompt', 'postToolUse', 'afterAgentResponse', 'preCompact', 'sessionEnd']
+            : client === 'codex'
+                ? ['SessionStart', 'UserPromptSubmit', 'PostToolUse', 'PreCompact', 'SessionEnd']
+                : ['SessionStart', 'UserPromptSubmit', 'PostToolUse', 'PreCompact'];
+    const nextRoot = next && typeof next === 'object' && !Array.isArray(next)
+        ? next
+        : {};
+    const nextHooks = nextRoot.hooks && typeof nextRoot.hooks === 'object' && !Array.isArray(nextRoot.hooks)
+        ? nextRoot.hooks
+        : {};
+    let after = existingHook ?? '{}\n';
+    if (client === 'cursor' && mode === 'init') {
+        after = upsertJsoncPath(after, ['version'], 1);
+    }
+    for (const eventName of eventNames) {
+        const value = nextHooks[eventName];
+        after = value === undefined
+            ? removeJsoncPath(after, ['hooks', eventName])
+            : upsertJsoncPath(after, ['hooks', eventName], value);
+    }
+    const meaningfulRootKeys = Object.keys(nextRoot).filter((key) => key !== 'version');
+    if (mode === 'remove' && meaningfulRootKeys.length === 0)
+        after = undefined;
+    if (existingHook !== after) {
+        changes.push({ path: hookFilePath, before: existingHook, after });
+    }
     return changes;
 }
 function resolveTarget(options, target) {
@@ -422,6 +581,7 @@ function resolveTarget(options, target) {
             ...target,
             configPath: join(codexHome, 'config.toml'),
             guidancePath: join(codexHome, 'AGENTS.md'),
+            hookPath: join(codexHome, 'hooks.json'),
             format: target.configFormat,
             rootKey: target.configRootKey,
         };
@@ -500,4 +660,6 @@ async function previewAndApply(changes, options) {
         ? `Applied changes with atomic per-file writes. Backups: ${backups.join(', ')}`
         : 'Applied changes with atomic per-file writes.');
 }
+export * from './auth.js';
+export * from './dispatch.js';
 //# sourceMappingURL=index.js.map