@flowrail/init 0.0.17 → 0.1.0

package/dist/codex-hooks-schema.js

@@ -0,0 +1,342 @@
+"use strict";
+/**
+ * Does Codex LOAD this `hooks.json`? (ADR-050 D8; adversarial-review BLOCKER.)
+ *
+ * Codex deserializes the file with serde into `HooksFile` and, on ANY error,
+ * drops the WHOLE file with only a warning (codex-rs/hooks/src/engine/
+ * discovery.rs `load_hooks_json`). So an edit that keeps FlowRail's handlers
+ * byte-identical but adds one malformed sibling disables FlowRail just as
+ * surely as deleting it. This mirrors the serde contract of openai/codex
+ * rust-v0.156.0 `codex-rs/config/src/hook_config.rs`:
+ *
+ *   HooksFile            deny_unknown_fields { description?: string|null, hooks?: HookEventsToml }
+ *   HookEventsToml       known events → Vec<MatcherGroup> (unknown keys ignored; null is an error)
+ *   MatcherGroup         { matcher?: string|null, hooks?: Vec<HookHandlerConfig> } (unknown keys ignored)
+ *   HookHandlerConfig    internally tagged on "type":
+ *     command            { command: string, commandWindows|command_windows?: string|null,
+ *                          timeout?: u64|null, async?: bool, statusMessage?: string|null,
+ *                          additionalContextLimit?: usize|null }
+ *     mcp_tool           { server: string, tool: string, input?: object (TOML-representable),
+ *                          timeout?: u64|null, statusMessage?: string|null }
+ *     prompt | agent     {}
+ *
+ * JSON.parse is not enough. serde_json rejects, where JSON.parse accepts:
+ *   - a duplicate KNOWN struct field (unknown ones are ignored);
+ *   - a float (`5.0`) where an integer is required;
+ *   - a lone UTF-16 surrogate escape (`"\ud800"`) in any string it decodes —
+ *     every object key it identifies, every string value it deserializes,
+ *     and everything inside a handler (buffered whole for the `type` tag) —
+ *     but NOT inside a value it ignores (an unknown event or group field);
+ *   - nesting deeper than its recursion limit (128) where it deserializes.
+ * Hence a small raw-token parser.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODEX_HOOK_EVENTS = void 0;
+exports.parseHooksJsonExact = parseHooksJsonExact;
+exports.codexWouldLoadHooksJson = codexWouldLoadHooksJson;
+/** serde_json's default recursion limit. */
+const SERDE_MAX_DEPTH = 128;
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+class RawJsonError extends Error {
+}
+function parseRaw(text) {
+    let i = 0;
+    let depth = 0;
+    const ws = () => {
+        while (i < text.length && (text[i] === ' ' || text[i] === '\t' || text[i] === '\n' || text[i] === '\r'))
+            i++;
+    };
+    const value = () => {
+        ws();
+        const c = text[i];
+        if (c === '{') {
+            i++;
+            depth++;
+            const at = depth;
+            const entries = [];
+            let loneKey = false;
+            ws();
+            if (text[i] === '}') {
+                i++;
+                depth--;
+                return { t: 'object', entries, loneKey, depth: at };
+            }
+            for (;;) {
+                ws();
+                if (text[i] !== '"')
+                    throw new RawJsonError('expected key');
+                const key = str();
+                if (key.lone)
+                    loneKey = true;
+                ws();
+                if (text[i++] !== ':')
+                    throw new RawJsonError('expected :');
+                entries.push([key.v, value()]);
+                ws();
+                if (text[i] === ',') {
+                    i++;
+                    continue;
+                }
+                if (text[i] === '}') {
+                    i++;
+                    depth--;
+                    return { t: 'object', entries, loneKey, depth: at };
+                }
+                throw new RawJsonError('expected , or }');
+            }
+        }
+        if (c === '[') {
+            i++;
+            depth++;
+            const at = depth;
+            const items = [];
+            ws();
+            if (text[i] === ']') {
+                i++;
+                depth--;
+                return { t: 'array', items, depth: at };
+            }
+            for (;;) {
+                items.push(value());
+                ws();
+                if (text[i] === ',') {
+                    i++;
+                    continue;
+                }
+                if (text[i] === ']') {
+                    i++;
+                    depth--;
+                    return { t: 'array', items, depth: at };
+                }
+                throw new RawJsonError('expected , or ]');
+            }
+        }
+        if (c === '"') {
+            const sv = str();
+            return { t: 'string', v: sv.v, lone: sv.lone };
+        }
+        if (text.startsWith('true', i)) {
+            i += 4;
+            return { t: 'bool', v: true };
+        }
+        if (text.startsWith('false', i)) {
+            i += 5;
+            return { t: 'bool', v: false };
+        }
+        if (text.startsWith('null', i)) {
+            i += 4;
+            return { t: 'null' };
+        }
+        const m = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(text.slice(i));
+        if (!m)
+            throw new RawJsonError('unexpected token');
+        i += m[0].length;
+        return { t: 'number', raw: m[0] };
+    };
+    const str = () => {
+        // Delegate escape handling to JSON.parse on the exact literal; it keeps
+        // a lone surrogate escape, which serde_json refuses to decode.
+        const start = i;
+        i++;
+        while (i < text.length && text[i] !== '"')
+            i += text[i] === '\\' ? 2 : 1;
+        if (i >= text.length)
+            throw new RawJsonError('unterminated string');
+        i++;
+        const v = JSON.parse(text.slice(start, i));
+        return { v, lone: LONE_SURROGATE.test(v) };
+    };
+    const v = value();
+    ws();
+    if (i !== text.length)
+        throw new RawJsonError('trailing data');
+    return v;
+}
+/** Would serde_json decode every string and container in ``v`` (a position
+ *  it deserializes rather than ignores)? */
+function decodable(v) {
+    switch (v.t) {
+        case 'string':
+            return !v.lone;
+        case 'array':
+            return v.depth < SERDE_MAX_DEPTH && v.items.every(decodable);
+        case 'object':
+            return v.depth < SERDE_MAX_DEPTH && !v.loneKey && v.entries.every(([, x]) => decodable(x));
+        default:
+            return true;
+    }
+}
+/** The hook events Codex 0.156 deserializes; any other key is ignored. */
+exports.CODEX_HOOK_EVENTS = new Set([
+    'PreToolUse', 'PermissionRequest', 'PostToolUse', 'PreCompact', 'PostCompact', 'SessionStart',
+    'SessionEnd', 'UserPromptSubmit', 'SubagentStart', 'SubagentStop', 'Stop', 'Interrupt',
+]);
+function fieldMap(obj, strictDuplicates) {
+    const out = new Map();
+    for (const [k, v] of obj.entries) {
+        if (out.has(k) && (strictDuplicates === 'all' || strictDuplicates.has(k))) {
+            throw new RawJsonError(`duplicate field ${k}`);
+        }
+        if (!out.has(k))
+            out.set(k, v);
+    }
+    return out;
+}
+const U64_MAX = BigInt('18446744073709551615');
+const isUnsignedInt = (v) => v.t === 'number' && /^(0|[1-9]\d*)$/.test(v.raw) && BigInt(v.raw) <= U64_MAX;
+const optString = (v) => v === undefined || v.t === 'null' || v.t === 'string';
+const optUint = (v) => v === undefined || v.t === 'null' || isUnsignedInt(v);
+function tomlRepresentable(v) {
+    if (v.t === 'null')
+        return false;
+    if (v.t === 'object')
+        return v.entries.every(([, x]) => tomlRepresentable(x));
+    if (v.t === 'array')
+        return v.items.every(tomlRepresentable);
+    return true;
+}
+const HANDLER_FIELDS = {
+    command: new Set(['command', 'commandWindows', 'command_windows', 'timeout', 'async', 'statusMessage', 'additionalContextLimit']),
+    mcp_tool: new Set(['server', 'tool', 'input', 'timeout', 'statusMessage']),
+    prompt: new Set(),
+    agent: new Set(),
+};
+function validateHandler(h) {
+    if (h.t !== 'object')
+        throw new RawJsonError('handler must be an object');
+    // Internally tagged: serde buffers the whole handler, decoding every string.
+    if (!decodable(h))
+        throw new RawJsonError('handler not decodable');
+    const tags = h.entries.filter(([k]) => k === 'type');
+    if (tags.length !== 1)
+        throw new RawJsonError(tags.length === 0 ? 'handler missing type' : 'duplicate field type');
+    const tag = tags[0][1];
+    if (tag.t !== 'string')
+        throw new RawJsonError('handler type must be a string');
+    const known = HANDLER_FIELDS[tag.v];
+    if (known === undefined)
+        throw new RawJsonError(`unknown handler type ${tag.v}`);
+    // Only KNOWN fields are rejected when repeated; unknown ones are ignored.
+    const f = fieldMap(h, known);
+    switch (tag.v) {
+        case 'command': {
+            const command = f.get('command');
+            if (!command || command.t !== 'string')
+                throw new RawJsonError('command must be a string');
+            if (f.has('commandWindows') && f.has('command_windows'))
+                throw new RawJsonError('duplicate field commandWindows');
+            if (!optString(f.get('commandWindows') ?? f.get('command_windows')))
+                throw new RawJsonError('commandWindows');
+            if (!optUint(f.get('timeout')))
+                throw new RawJsonError('timeout must be an unsigned integer');
+            const async = f.get('async');
+            if (async !== undefined && async.t !== 'bool')
+                throw new RawJsonError('async must be a boolean');
+            if (!optString(f.get('statusMessage')))
+                throw new RawJsonError('statusMessage');
+            if (!optUint(f.get('additionalContextLimit')))
+                throw new RawJsonError('additionalContextLimit');
+            return;
+        }
+        case 'mcp_tool': {
+            for (const k of ['server', 'tool']) {
+                const v = f.get(k);
+                if (!v || v.t !== 'string')
+                    throw new RawJsonError(`${k} must be a string`);
+            }
+            const input = f.get('input');
+            if (input !== undefined && (input.t !== 'object' || !tomlRepresentable(input)))
+                throw new RawJsonError('input');
+            if (!optUint(f.get('timeout')))
+                throw new RawJsonError('timeout');
+            if (!optString(f.get('statusMessage')))
+                throw new RawJsonError('statusMessage');
+            return;
+        }
+        default:
+            return;
+    }
+}
+/**
+ * The file as JavaScript values with every integer EXACT (a ``bigint``), so
+ * two values Codex tells apart never compare equal: JSON.parse maps
+ * ``9007199254740992`` and ``9007199254740993`` to one number. Throws on text
+ * that is not JSON.
+ */
+function parseHooksJsonExact(text) {
+    const toJs = (v) => {
+        switch (v.t) {
+            case 'object': {
+                // Own properties exactly as JSON.parse makes them (the last duplicate
+                // wins; `__proto__` is an ordinary key).
+                const out = {};
+                for (const [k, x] of v.entries) {
+                    Object.defineProperty(out, k, { value: toJs(x), enumerable: true, writable: true, configurable: true });
+                }
+                return out;
+            }
+            case 'array':
+                return v.items.map(toJs);
+            case 'string':
+                return v.v;
+            case 'number':
+                return /^-?(0|[1-9]\d*)$/.test(v.raw) ? BigInt(v.raw) : Number(v.raw);
+            case 'bool':
+                return v.v;
+            case 'null':
+                return null;
+        }
+    };
+    try {
+        return toJs(parseRaw(text));
+    }
+    catch (err) {
+        throw new SyntaxError(err.message);
+    }
+}
+/** True iff Codex 0.156 would load this text as a hooks file. */
+function codexWouldLoadHooksJson(text) {
+    try {
+        const root = parseRaw(text);
+        if (root.t !== 'object' || root.loneKey)
+            return false;
+        const top = fieldMap(root, 'all');
+        for (const k of top.keys())
+            if (k !== 'description' && k !== 'hooks')
+                return false;
+        const description = top.get('description');
+        if (!optString(description) || (description !== undefined && !decodable(description)))
+            return false;
+        const hooks = top.get('hooks');
+        if (hooks === undefined)
+            return true;
+        if (hooks.t !== 'object' || hooks.loneKey)
+            return false;
+        const events = fieldMap(hooks, exports.CODEX_HOOK_EVENTS);
+        for (const [event, groups] of events) {
+            // An unknown event's value is ignored, never decoded.
+            if (!exports.CODEX_HOOK_EVENTS.has(event))
+                continue;
+            if (groups.t !== 'array' || groups.depth >= SERDE_MAX_DEPTH)
+                return false;
+            for (const group of groups.items) {
+                if (group.t !== 'object' || group.loneKey || group.depth >= SERDE_MAX_DEPTH)
+                    return false;
+                const g = fieldMap(group, new Set(['matcher', 'hooks']));
+                const matcher = g.get('matcher');
+                if (!optString(matcher) || (matcher !== undefined && !decodable(matcher)))
+                    return false;
+                const handlers = g.get('hooks');
+                if (handlers === undefined)
+                    continue;
+                if (handlers.t !== 'array' || handlers.depth >= SERDE_MAX_DEPTH)
+                    return false;
+                handlers.items.forEach(validateHandler);
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/codex-init.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * `npx @flowrail/init --agent codex` (ADR-050 D9).
+ *
+ * Order is load-bearing: validate every file edit and install + self-test the
+ * EXACT hook release FIRST, and only then write Codex wiring. A wiring file
+ * pointing at a hook that cannot serve Codex would be worse than no wiring —
+ * Codex fails open on a broken hook.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCodexInit = runCodexInit;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const app_instance_1 = require("./app-instance");
+const connectivity_1 = require("./connectivity");
+const ci_workflow_1 = require("./ci-workflow");
+const codex_target_1 = require("./codex-target");
+const codex_doctor_script_1 = require("./codex-doctor-script");
+const codex_install_1 = require("./codex-install");
+const destinations_1 = require("./destinations");
+const env_1 = require("./env");
+const flowrail_yaml_1 = require("./flowrail-yaml");
+const gitignore_1 = require("./gitignore");
+const npm_hooks_1 = require("./npm-hooks");
+const preflight_1 = require("./preflight");
+const repo_scan_trigger_1 = require("./repo-scan-trigger");
+const skills_1 = require("./skills");
+const LITERAL_TOKEN_RE = /fs_poc_[A-Za-z0-9_-]{1,40}_[A-Fa-f0-9]{8,}/;
+function readIfExists(abs) {
+    return fs_1.default.existsSync(abs) ? fs_1.default.readFileSync(abs, 'utf8') : null;
+}
+function writeFile(abs, text) {
+    fs_1.default.mkdirSync(path_1.default.dirname(abs), { recursive: true });
+    fs_1.default.writeFileSync(abs, text, 'utf8');
+}
+async function runCodexInit(opts) {
+    const { projectRoot, log, mcpBaseUrl } = opts;
+    const { apiKey } = (0, env_1.readApiKeyFromEnv)(opts.env);
+    // The endpoint goes into every hook command; the hook only recognizes an
+    // http(s) URL there (ADR-050 D8), so anything else would be wiring that
+    // never counts as FlowRail — refuse it before touching anything.
+    if (!(0, codex_target_1.isValidEndpoint)(mcpBaseUrl)) {
+        throw new env_1.InitError('FLOWRAIL_MCP_URL must be a plain http(s) URL such as https://api.flowrail.ai — no credentials, ' +
+            'spaces, backslashes, percent-encoding or line breaks (it is written into tracked hook commands). The value is ' +
+            'not shown here because it may contain a credential.');
+    }
+    for (const phase of ['pre-write', 'pre-bash', 'stop', 'session-start']) {
+        if ((0, codex_target_1.parseCodexHookCommand)((0, codex_target_1.buildCodexHookCommand)(phase, mcpBaseUrl, codex_target_1.CODEX_HOOK_VERSION)) === null) {
+            throw new env_1.InitError(`internal error: the generated ${phase} hook command does not round-trip; nothing was changed.`);
+        }
+    }
+    // 1. Refuse a literal credential in any config init touches or reads.
+    (0, preflight_1.preflightNoLiteralTokens)(projectRoot);
+    const offenders = codex_target_1.CODEX_TRACKED_CONFIGS.filter((rel) => {
+        const text = readIfExists(path_1.default.join(projectRoot, rel));
+        return text !== null && LITERAL_TOKEN_RE.test(text);
+    });
+    if (offenders.length > 0) {
+        throw new env_1.InitError(`${offenders.join(', ')} contains a literal FlowRail API key. Remove it — Codex reads the key ` +
+            'from the FLOWRAIL_API_KEY environment variable — and re-run.');
+    }
+    // 2. Compute every edit up front; any conflict throws before a single write.
+    const hooksAbs = path_1.default.join(projectRoot, codex_target_1.CODEX_HOOKS_PATH);
+    const tomlAbs = path_1.default.join(projectRoot, codex_target_1.CODEX_CONFIG_PATH);
+    const agentsAbs = path_1.default.join(projectRoot, codex_target_1.AGENTS_MD_PATH);
+    const hooksMerge = (0, codex_target_1.mergeCodexHooks)(readIfExists(hooksAbs), mcpBaseUrl, codex_target_1.CODEX_HOOK_VERSION);
+    const nextToml = (0, codex_target_1.upsertCodexConfigToml)(readIfExists(tomlAbs), mcpBaseUrl);
+    const nextAgents = (0, codex_target_1.upsertAgentsMd)(readIfExists(agentsAbs));
+    // Nothing FlowRail writes may carry the credential — however it got there.
+    for (const [rel, text] of [
+        [codex_target_1.CODEX_HOOKS_PATH, hooksMerge.text],
+        [codex_target_1.CODEX_CONFIG_PATH, nextToml],
+        [codex_target_1.AGENTS_MD_PATH, nextAgents],
+    ]) {
+        if (text !== null && (text.includes(apiKey) || LITERAL_TOKEN_RE.test(text))) {
+            throw new env_1.InitError(`the ${rel} FlowRail would write contains an API key; nothing was changed.`);
+        }
+    }
+    // Every destination, checked before anything is installed or written: it
+    // must resolve inside the repo and outside .claude/ (the Claude Code
+    // install's territory), no parent may be a file, and it must be writable.
+    // A skills directory that is a link into .claude/skills (a dual-agent
+    // repo sharing skills) is left to the Claude Code install.
+    const skillsShared = (0, destinations_1.resolvesIntoClaude)(projectRoot, codex_target_1.CODEX_SKILLS_DIR);
+    const destinations = [
+        ...(skillsShared ? [] : skills_1.FLOWRAIL_SKILLS.map((skill) => path_1.default.join(codex_target_1.CODEX_SKILLS_DIR, skill, 'SKILL.md'))),
+        ...(hooksMerge.text !== null ? [codex_target_1.CODEX_HOOKS_PATH] : []),
+        ...(nextToml !== null ? [codex_target_1.CODEX_CONFIG_PATH] : []),
+        ...(nextAgents !== null ? [codex_target_1.AGENTS_MD_PATH] : []),
+        'flowrail.yaml',
+        ...(opts.ciGate.enabled ? [ci_workflow_1.CI_WORKFLOW_RELATIVE_PATH] : []),
+        '.gitignore',
+        codex_doctor_script_1.CODEX_DOCTOR_FILENAME,
+        ...(fs_1.default.existsSync(path_1.default.join(projectRoot, 'package.json')) ? ['package.json'] : []),
+        // Written later by the app-identity step; checked now all the same.
+        path_1.default.join('.flowrail', 'app.json'),
+    ];
+    (0, destinations_1.preflightDestinations)(projectRoot, destinations);
+    // 3. The exact hook release, proven able to serve Codex, BEFORE wiring.
+    log(`→ installing @flowrail/hook@${codex_target_1.CODEX_HOOK_VERSION}…`);
+    const hook = opts.hookInstaller
+        ? opts.hookInstaller()
+        : (0, codex_install_1.installAndVerifyCodexHook)(projectRoot, codex_target_1.CODEX_HOOK_VERSION);
+    log(`✓ installed @flowrail/hook ${hook.version} (Codex adapter verified)`);
+    log('→ self-testing the Codex hook (a patch adding a known test secret must be blocked)…');
+    (opts.hookSelfTest ?? (() => (0, codex_install_1.runCodexHookSelfTest)({ projectRoot, env: opts.env })))();
+    log('✓ Codex hook self-test passed — the patch carrying a test secret was blocked');
+    // 4. Wiring — all or nothing: a failed write restores every file it had
+    //    already changed.
+    const snapshot = (0, destinations_1.snapshotDestinations)(projectRoot, destinations);
+    try {
+        writeCodexWiring();
+    }
+    catch (err) {
+        (0, destinations_1.restoreDestinations)(snapshot);
+        throw new env_1.InitError(`writing the Codex wiring failed (${err instanceof Error ? err.message : String(err)}); ` +
+            'every wiring file FlowRail had changed was restored (the @flowrail/hook devDependency it ' +
+            'installed stays in package.json).');
+    }
+    function writeCodexWiring() {
+        if (skillsShared) {
+            const missing = skills_1.FLOWRAIL_SKILLS.filter((skill) => !fs_1.default.existsSync(path_1.default.join(projectRoot, codex_target_1.CODEX_SKILLS_DIR, skill, 'SKILL.md')));
+            log(`✓ ${codex_target_1.CODEX_SKILLS_DIR}/ is a link into .claude/ — its skills are managed by the Claude Code install (unchanged)`);
+            if (missing.length > 0) {
+                log(`FlowRail: ${missing.length} FlowRail skill(s) are missing there (${missing.join(', ')}). Run ` +
+                    '`npx --yes @flowrail/init@latest` for the Claude Code install, or replace the link, so Codex gets them.');
+            }
+        }
+        else {
+            (0, skills_1.copySkills)({
+                projectRoot,
+                skillsSourceDir: opts.skillsSourceDir ?? (0, skills_1.defaultSkillsSourceDir)(),
+                targetDir: codex_target_1.CODEX_SKILLS_DIR,
+            });
+            log(`✓ wrote ${skills_1.FLOWRAIL_SKILLS.length} skill(s) to ${codex_target_1.CODEX_SKILLS_DIR}/`);
+        }
+        if (hooksMerge.text !== null) {
+            writeFile(hooksAbs, hooksMerge.text);
+            log(`✓ wrote ${codex_target_1.CODEX_HOOKS_PATH} (${hooksMerge.actions.join('; ')})`);
+        }
+        else {
+            log(`✓ ${codex_target_1.CODEX_HOOKS_PATH} already wires FlowRail @flowrail/hook@${codex_target_1.CODEX_HOOK_VERSION} (unchanged)`);
+        }
+        if (nextToml !== null) {
+            writeFile(tomlAbs, nextToml);
+            log(`✓ wrote ${codex_target_1.CODEX_CONFIG_PATH} (mcp_servers.flowrail → ${opts.connectivityUrl}, bearer from FLOWRAIL_API_KEY)`);
+        }
+        else {
+            log(`✓ ${codex_target_1.CODEX_CONFIG_PATH} already defines the FlowRail MCP server (unchanged)`);
+        }
+        if (nextAgents !== null) {
+            writeFile(agentsAbs, nextAgents);
+            log(`✓ wrote the FlowRail section of ${codex_target_1.AGENTS_MD_PATH}`);
+        }
+        (0, flowrail_yaml_1.writeFlowrailYaml)(projectRoot);
+        log('✓ wrote flowrail.yaml');
+        if (opts.ciGate.enabled) {
+            (0, ci_workflow_1.writeCiWorkflow)(projectRoot, opts.ciGate.projectId);
+            log(`✓ wrote ${ci_workflow_1.CI_WORKFLOW_RELATIVE_PATH}`);
+        }
+        (0, gitignore_1.appendFlowrailToGitignore)(projectRoot);
+        log('✓ ensured .flowrail/ is in .gitignore');
+        (0, codex_doctor_script_1.writeCodexDoctorScript)(projectRoot, codex_target_1.CODEX_HOOK_VERSION);
+        log(`✓ wrote ${codex_doctor_script_1.CODEX_DOCTOR_FILENAME} (Codex readiness check)`);
+        const skipped = (hook) => log(`! left the ${hook} npm script unchanged (its ending would not combine safely); add \`&& node ${codex_doctor_script_1.CODEX_DOCTOR_FILENAME}\` to it yourself`);
+        if ((0, npm_hooks_1.patchNpmScripts)(projectRoot, codex_doctor_script_1.CODEX_DOCTOR_FILENAME, skipped)) {
+            log('✓ wired the Codex readiness check into predev/prebuild npm scripts');
+        }
+    }
+    // 5. Server reachability, app identity, retroactive scan — as for Claude Code.
+    log(`→ checking connectivity to ${opts.connectivityUrl}…`);
+    await (0, connectivity_1.checkConnectivity)({ apiKey, url: opts.connectivityUrl, fetcher: opts.connectivityFetcher });
+    log('✓ connectivity check passed');
+    try {
+        const rebind = opts.argv.includes('--rebind') || opts.env['FLOWRAIL_APP_REBIND'] === '1';
+        const appRegistrar = opts.appRegistrar;
+        const appResult = await (0, app_instance_1.ensureAppInstance)({
+            projectRoot,
+            mcpBaseUrl,
+            apiKey,
+            rebind,
+            log,
+            registerApp: appRegistrar === undefined
+                ? undefined
+                : async (args) => (await appRegistrar(args)) ?? { error: 'empty app registration response' },
+        });
+        log(`✓ app instance ${appResult.appInstanceId} (${appResult.status}) — .flowrail/app.json`);
+    }
+    catch (err) {
+        log(`FlowRail: app-instance identity step failed (${err instanceof Error ? err.message : String(err)}); continuing.`);
+    }
+    if (!(opts.argv.includes('--no-scan') || opts.argv.includes('--no-retro-scan'))) {
+        log('→ scanning your existing dependencies for known CVEs…');
+        try {
+            await (opts.repoScanner ?? repo_scan_trigger_1.defaultRepoScanner)({ projectRoot, mcpBaseUrl, apiKey, log });
+        }
+        catch (err) {
+            log(`FlowRail: retroactive scan could not complete (${err instanceof Error ? err.message : String(err)}); skipping.`);
+        }
+    }
+    // 6. Configured is not active: say exactly what Codex still needs.
+    log('');
+    log('FlowRail is configured for Codex (hooks, MCP server, skills, AGENTS.md).');
+    log('It becomes active only after two approvals in Codex, which FlowRail cannot grant:');
+    log('  1. Open this repo in Codex and trust the project when asked.');
+    log('  2. Run /hooks in Codex and approve the four FlowRail hooks.');
+    log(`Then run \`node ${codex_doctor_script_1.CODEX_DOCTOR_FILENAME}\` — it reports "readiness: active" once Codex runs them.`);
+    log('Start Codex from a shell where FLOWRAIL_API_KEY is set.');
+}

package/dist/codex-install.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Install the EXACT @flowrail/hook release the Codex wiring pins, prove it
+ * implements the Codex adapter, and prove it blocks a Codex patch carrying a
+ * test secret — all BEFORE any Codex wiring is written (ADR-050 D9, D11).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnCodexHookPreWrite = void 0;
+exports.buildCodexVerifyScript = buildCodexVerifyScript;
+exports.installAndVerifyCodexHook = installAndVerifyCodexHook;
+exports.buildCodexProbePayload = buildCodexProbePayload;
+exports.runCodexHookSelfTest = runCodexHookSelfTest;
+const child_process_1 = require("child_process");
+const env_1 = require("./env");
+const hook_install_1 = require("./hook-install");
+const verify_write_1 = require("./verify-write");
+const defaultExec = (file, args, options) => (0, child_process_1.execFileSync)(file, args, { cwd: options.cwd, stdio: ['ignore', 'pipe', 'pipe'] })
+    .toString()
+    .trim();
+/** Node one-liner run in the project: the installed package must be exactly
+ *  `version`, expose the `flowrail-hook` bin, and advertise the Codex agent in
+ *  `capabilities`. Prints the version on success. */
+function buildCodexVerifyScript(version) {
+    return [
+        "const path = require('path');",
+        "const cp = require('child_process');",
+        `const pkgPath = require.resolve(${JSON.stringify(`${hook_install_1.HOOK_PACKAGE}/package.json`)}, { paths: [process.cwd()] });`,
+        'const pkg = require(pkgPath);',
+        `if (pkg.version !== ${JSON.stringify(version)}) { console.error('installed ' + pkg.version + ', expected ${version}'); process.exit(2); }`,
+        `const binEntry = pkg.bin && typeof pkg.bin === 'object' ? pkg.bin[${JSON.stringify(hook_install_1.HOOK_BIN)}] : null;`,
+        "if (!binEntry) { console.error('package.json bin must name flowrail-hook'); process.exit(2); }",
+        "const r = cp.spawnSync(process.execPath, [path.resolve(path.dirname(pkgPath), binEntry), 'capabilities'], { encoding: 'utf8' });",
+        'let caps = null; try { caps = JSON.parse(r.stdout); } catch (e) {}',
+        "if (r.status !== 0 || !caps || !caps.agents || !caps.agents.codex || !(caps.adapter_protocol >= 1)) {",
+        "  console.error('this @flowrail/hook does not implement the Codex adapter: ' + (r.stdout || r.stderr || '').slice(0, 300));",
+        '  process.exit(2);',
+        '}',
+        'process.stdout.write(pkg.version);',
+    ].join('');
+}
+function installAndVerifyCodexHook(projectRoot, version, exec = defaultExec) {
+    let installOutput;
+    try {
+        installOutput = exec('npm', ['install', '--save-dev', '--save-exact', `${hook_install_1.HOOK_PACKAGE}@${version}`], {
+            cwd: projectRoot,
+        });
+    }
+    catch (err) {
+        throw new env_1.InitError(`npm install ${hook_install_1.HOOK_PACKAGE}@${version} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let verified;
+    try {
+        verified = exec('node', ['-e', buildCodexVerifyScript(version)], { cwd: projectRoot });
+    }
+    catch (err) {
+        throw new env_1.InitError(`${hook_install_1.HOOK_PACKAGE}@${version} is installed but cannot serve Codex: ` +
+            `${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { installOutput, version: verified || version };
+}
+/** A Codex `apply_patch` PreToolUse payload that adds the probe secret. */
+function buildCodexProbePayload(cwd) {
+    return JSON.stringify({
+        session_id: '',
+        hook_event_name: 'PreToolUse',
+        cwd,
+        tool_name: 'apply_patch',
+        tool_input: {
+            command: `*** Begin Patch\n*** Add File: ${verify_write_1.PROBE_PATH}\n+const awsKey = "${verify_write_1.PROBE_SECRET}";\n*** End Patch\n`,
+        },
+    });
+}
+const spawnCodexHookPreWrite = (binPath, stdin, env, cwd) => {
+    const r = (0, child_process_1.spawnSync)(process.execPath, [binPath, 'agent', 'codex', 'pre-write'], {
+        input: stdin,
+        env,
+        cwd,
+        encoding: 'utf8',
+        timeout: 30000,
+    });
+    return { status: r.status, stderr: r.stderr ?? '' };
+};
+exports.spawnCodexHookPreWrite = spawnCodexHookPreWrite;
+/**
+ * Prove the installed hook blocks a Codex patch that adds a known test
+ * secret. Like the Claude Code self-test it never sees the real key and its
+ * telemetry targets an unroutable loopback. This proves hook logic only —
+ * whether Codex LOADS and TRUSTS the hooks is the doctor's readiness check.
+ */
+function runCodexHookSelfTest(opts) {
+    const bin = (opts.resolveHookBinPath ?? verify_write_1.resolveInstalledHookBinPath)(opts.projectRoot);
+    const env = {
+        ...opts.env,
+        FLOWRAIL_API_KEY: 'flowrail-selftest',
+        FLOWRAIL_MCP_URL: 'http://127.0.0.1:1',
+    };
+    const { status, stderr } = (opts.runHook ?? exports.spawnCodexHookPreWrite)(bin, buildCodexProbePayload(opts.projectRoot), env, opts.projectRoot);
+    if (!(status === 2 && /secret pattern detected/i.test(stderr))) {
+        throw new env_1.InitError(`the Codex hook self-test did not block a test secret (exit ${String(status)}; ` +
+            `stderr: ${stderr.trim().slice(0, 200) || '<empty>'}). FlowRail would not protect Codex writes — aborting.`);
+    }
+}