@flowrail/init 0.0.17 → 0.1.0

package/dist/codex-target.js

@@ -0,0 +1,480 @@
+"use strict";
+/**
+ * `npx @flowrail/init --agent codex` — the OpenAI Codex install target
+ * (ADR-050 D9, D11).
+ *
+ * Every writer here is a pure function over the file's current text so the
+ * orchestrator can validate EVERYTHING before writing ANYTHING:
+ *
+ *   - `.codex/hooks.json`: four FlowRail handlers, merged IN PLACE. Codex
+ *     trusts each handler by (source, event, group index, handler index,
+ *     definition hash), so an existing FlowRail handler keeps its exact
+ *     position, foreign handlers are never moved, and a no-op rerun leaves
+ *     the file byte-identical — otherwise every rerun would silently
+ *     de-trust FlowRail.
+ *   - `.codex/config.toml`: one uniquely delimited managed block for
+ *     `[mcp_servers.flowrail]`, semantically validated with a TOML parser
+ *     before and after the edit.
+ *   - `AGENTS.md`: one managed block; user content preserved.
+ *
+ * Init never writes Codex trust (`[hooks.state]`, project trust) and never
+ * writes under `$HOME`: trust is Codex's security control.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODEX_TRACKED_CONFIGS = exports.AGENTS_BLOCK = exports.AGENTS_END = exports.AGENTS_BEGIN = exports.TOML_BLOCK_END = exports.TOML_BLOCK_BEGIN = exports.LEGACY_FLOWRAIL_COMMAND_RE = exports.CODEX_APPROVED_TOOLS = exports.CODEX_HOOK_TIMEOUTS = exports.CODEX_SKILLS_DIR = exports.AGENTS_MD_PATH = exports.CODEX_CONFIG_PATH = exports.CODEX_HOOKS_PATH = exports.CODEX_HOOK_VERSION = void 0;
+exports.buildCodexHookCommand = buildCodexHookCommand;
+exports.isValidEndpoint = isValidEndpoint;
+exports.parseCodexHookCommand = parseCodexHookCommand;
+exports.findLegacyFlowrailHandlers = findLegacyFlowrailHandlers;
+exports.mergeCodexHooks = mergeCodexHooks;
+exports.renderCodexTomlBlock = renderCodexTomlBlock;
+exports.upsertCodexConfigToml = upsertCodexConfigToml;
+exports.upsertAgentsMd = upsertAgentsMd;
+const smol_toml_1 = require("smol-toml");
+const codex_hooks_schema_1 = require("./codex-hooks-schema");
+const json_spans_1 = require("./json-spans");
+const env_1 = require("./env");
+/** The exact @flowrail/hook release this init wires (ADR-050 D11). Moving it
+ *  rewrites the generated commands, so Codex asks the user to re-approve. */
+exports.CODEX_HOOK_VERSION = '0.1.0';
+exports.CODEX_HOOKS_PATH = '.codex/hooks.json';
+exports.CODEX_CONFIG_PATH = '.codex/config.toml';
+exports.AGENTS_MD_PATH = 'AGENTS.md';
+exports.CODEX_SKILLS_DIR = '.agents/skills';
+/** Explicit Codex timeouts (seconds). A Codex hook timeout is a SILENT
+ *  allow, so each sits well above the hook's own internal budget (47 s for
+ *  pre-write; the review surfaces keep the ADR-021 180 s). */
+exports.CODEX_HOOK_TIMEOUTS = {
+    'pre-write': 90,
+    'pre-bash': 60,
+    stop: 180,
+    'session-start': 180,
+};
+/** The MCP tools the FlowRail skills call; each gets an explicit
+ *  per-tool approval (never a blanket `default_tools_approval_mode`).
+ *  Hook-internal tools stay unapproved. */
+exports.CODEX_APPROVED_TOOLS = [
+    'flowrail_design_review',
+    'flowrail_get_design_review',
+    'flowrail_verify_code',
+    'flowrail_check_dep_install',
+    'flowrail_get_lineage',
+    'flowrail_review_app',
+];
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The native hook command (ADR-050 D8). MUST stay identical to
+ * `buildNativeHookCommand` in @flowrail/hook — a cross-package test pins it
+ * against the hook's own grammar parser.
+ */
+function buildCodexHookCommand(phase, mcpBaseUrl, version = exports.CODEX_HOOK_VERSION) {
+    // D11: an exact pin only — a range would let the executed code change
+    // under a command the user approved.
+    if (!EXACT_SEMVER_RE.test(version)) {
+        throw new env_1.InitError(`native hook commands pin an exact version, got ${JSON.stringify(version)}`);
+    }
+    return (`FLOWRAIL_MCP_URL=${shellQuote(mcpBaseUrl)} npx --yes -p ` +
+        `@flowrail/hook@${version} flowrail-hook agent codex ${phase}`);
+}
+const EXACT_SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const INSTALLER_COMMAND_RE = /^FLOWRAIL_MCP_URL=('(?:[^']|'\\'')*'|[A-Za-z0-9_@%+=:,./-]+) npx --yes -p @flowrail\/hook@(\S+) flowrail-hook agent codex (pre-write|pre-bash|stop|session-start)$/;
+/**
+ * Is ``url`` an endpoint a hook command can carry (ADR-050 D8)? An http(s)
+ * URL with no credentials, query or fragment (anything there would be
+ * written into tracked files), no whitespace or control characters (which
+ * the hook's grammar rejects), and no percent-encoding: a base URL never
+ * needs it, and an encoded path could carry a key past the key scan.
+ */
+function isValidEndpoint(url) {
+    if (/[\s\x00-\x1f\x7f\\%]/.test(url))
+        return false;
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    // A base URL needs no query or fragment; either could carry a token.
+    return ((u.protocol === 'https:' || u.protocol === 'http:') &&
+        u.username === '' &&
+        u.password === '' &&
+        u.search === '' &&
+        u.hash === '' &&
+        !url.includes('?') &&
+        !url.includes('#'));
+}
+/** Parse EXACTLY the installer's command text (the hook's grammar): the
+ *  endpoint, pin and phase — or null for anything else, however similar. */
+function parseCodexHookCommand(command) {
+    if (typeof command !== 'string')
+        return null;
+    const m = INSTALLER_COMMAND_RE.exec(command);
+    if (!m)
+        return null;
+    const baseUrl = m[1].startsWith("'") ? m[1].slice(1, -1).replace(/'\\''/g, "'") : m[1];
+    const version = m[2];
+    const phase = m[3];
+    if (!EXACT_SEMVER_RE.test(version) || !isValidEndpoint(baseUrl))
+        return null;
+    return command === buildCodexHookCommand(phase, baseUrl, version) ? { baseUrl, version, phase } : null;
+}
+const PLACEMENT = {
+    'pre-write': { event: 'PreToolUse', matcher: 'apply_patch' },
+    'pre-bash': { event: 'PreToolUse', matcher: 'Bash' },
+    stop: { event: 'Stop', matcher: null },
+    'session-start': { event: 'SessionStart', matcher: null },
+};
+/** A Claude Code FlowRail hook command: `[FLOWRAIL_*=… ]npx --yes -p
+ *  @flowrail/hook[@v] flowrail-hook <phase>` without the Codex namespace. */
+exports.LEGACY_FLOWRAIL_COMMAND_RE = /^(?:FLOWRAIL_[A-Z0-9_]*=\S+\s+)*npx\s+--yes\s+-p\s+@flowrail\/hook(?:@\S+)?\s+flowrail-hook\s+(pre-write|pre-bash|stop|session-start)\s*$/;
+/** Event names of the Claude Code FlowRail hooks in a hooks file. */
+function findLegacyFlowrailHandlers(text) {
+    let config;
+    try {
+        config = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    const hooks = config?.hooks;
+    if (!hooks || typeof hooks !== 'object')
+        return found;
+    for (const [event, groups] of Object.entries(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            for (const h of (group?.hooks ?? [])) {
+                const m = typeof h?.command === 'string' ? exports.LEGACY_FLOWRAIL_COMMAND_RE.exec(h.command) : null;
+                if (m)
+                    found.push(`${event} ${m[1]}`);
+            }
+        }
+    }
+    return found;
+}
+/** The phase of a FlowRail-owned handler: a `command` handler whose text is
+ *  exactly an installer command. A user's own hook that merely mentions
+ *  `flowrail-hook agent codex` is not ours, and is never rewritten. */
+function handlerPhase(handler) {
+    if (!handler || typeof handler !== 'object')
+        return null;
+    const h = handler;
+    if (h.type !== 'command')
+        return null;
+    return parseCodexHookCommand(h.command)?.phase ?? null;
+}
+/**
+ * Merge FlowRail's four handlers into `existingText` (null = no file).
+ * Existing FlowRail handlers are rewritten in place; missing ones are
+ * appended as new groups at the END of their event (never before foreign
+ * groups, which would shift their indices). A handler already equal to ours
+ * is left alone.
+ */
+function mergeCodexHooks(existingText, mcpBaseUrl, version = exports.CODEX_HOOK_VERSION) {
+    var _a;
+    const desiredFor = (phase) => ({
+        type: 'command',
+        command: buildCodexHookCommand(phase, mcpBaseUrl, version),
+        timeout: exports.CODEX_HOOK_TIMEOUTS[phase],
+    });
+    const groupFor = (phase) => {
+        const { matcher } = PLACEMENT[phase];
+        return matcher === null ? { hooks: [desiredFor(phase)] } : { matcher, hooks: [desiredFor(phase)] };
+    };
+    if (existingText === null) {
+        const hooks = {};
+        for (const phase of Object.keys(PLACEMENT)) {
+            (hooks[_a = PLACEMENT[phase].event] ?? (hooks[_a] = [])).push(groupFor(phase));
+        }
+        return {
+            text: JSON.stringify({ hooks }, null, 2) + '\n',
+            actions: Object.keys(PLACEMENT).map((p) => `added the FlowRail ${p} hook`),
+        };
+    }
+    let root;
+    try {
+        root = (0, json_spans_1.parseJsonSpans)(existingText);
+        if (root.t !== 'object')
+            throw new Error('not an object');
+    }
+    catch {
+        throw new env_1.InitError(`${exports.CODEX_HOOKS_PATH} is not a valid JSON object. Fix it or delete it before re-running.`);
+    }
+    const hooksEntry = root.entries.find((e) => e.key === 'hooks');
+    if (hooksEntry !== undefined && hooksEntry.value.t !== 'object') {
+        throw new env_1.InitError(`${exports.CODEX_HOOKS_PATH}: "hooks" must be an object.`);
+    }
+    // Codex drops a hooks file it cannot deserialize WHOLE, with only a
+    // warning — merging FlowRail into one would leave FlowRail silently off.
+    if (!(0, codex_hooks_schema_1.codexWouldLoadHooksJson)(existingText)) {
+        throw new env_1.InitError(`${exports.CODEX_HOOKS_PATH} is valid JSON but Codex would not load it: Codex drops the whole file on an ` +
+            'unknown top-level key, a duplicate key, a non-integer timeout or an unknown handler type, so ' +
+            "FlowRail's hooks would never run. Fix it and re-run.");
+    }
+    // A Claude Code FlowRail hook (the flagless `flowrail-hook <phase>`
+    // command, e.g. brought over by Codex's import) would receive Codex
+    // payloads and refuse every patch. It is not ours to rewrite silently.
+    const legacy = findLegacyFlowrailHandlers(existingText);
+    if (legacy.length > 0) {
+        throw new env_1.InitError(`${exports.CODEX_HOOKS_PATH} contains ${legacy.length} Claude Code FlowRail hook(s) (${legacy.join(', ')}). In Codex ` +
+            'they would block every apply_patch. Remove them from that file, then re-run — this installer adds the ' +
+            'Codex versions.');
+    }
+    // Edits touch ONLY FlowRail's own handlers and the places new groups or
+    // keys go. Every foreign byte — number formatting, key order, whitespace —
+    // is kept, so Codex's trust in the user's own handlers survives.
+    const edits = [];
+    const actions = [];
+    const newGroups = new Map();
+    const hooksObj = hooksEntry?.value;
+    for (const phase of Object.keys(PLACEMENT)) {
+        const { event, matcher } = PLACEMENT[phase];
+        const eventEntry = hooksObj?.entries.find((e) => e.key === event);
+        if (eventEntry !== undefined && eventEntry.value.t !== 'array') {
+            throw new env_1.InitError(`${exports.CODEX_HOOKS_PATH}: hooks.${event} must be an array.`);
+        }
+        const groups = eventEntry?.value?.items ?? [];
+        const found = [];
+        for (const group of groups) {
+            if (group.t !== 'object')
+                continue;
+            const handlers = group.entries.find((e) => e.key === 'hooks')?.value;
+            if (handlers?.t !== 'array')
+                continue;
+            for (const handler of handlers.items) {
+                const plain = JSON.parse(existingText.slice(handler.start, handler.end));
+                if (handlerPhase(plain) === phase)
+                    found.push({ group, handler });
+            }
+        }
+        if (found.length > 1) {
+            throw new env_1.InitError(`${exports.CODEX_HOOKS_PATH} defines the FlowRail ${phase} hook ${found.length} times. ` +
+                'Remove the duplicates (keep one) and re-run.');
+        }
+        if (found.length === 1) {
+            const { group, handler } = found[0];
+            const groupMatcher = group.t === 'object' ? group.entries.find((e) => e.key === 'matcher')?.value?.value : undefined;
+            // PreToolUse hooks sit under their exact matcher; Stop and SessionStart
+            // under none (a matcher there narrows when they fire, e.g. SessionStart
+            // `compact` skips a normal startup).
+            if (matcher === null ? groupMatcher !== undefined && groupMatcher !== null : groupMatcher !== matcher) {
+                throw new env_1.InitError(`${exports.CODEX_HOOKS_PATH}: the FlowRail ${phase} hook sits under matcher ${JSON.stringify(groupMatcher)}, ` +
+                    `not ${JSON.stringify(matcher)}. Move it back (or delete it) and re-run.`);
+            }
+            const desired = desiredFor(phase);
+            const current = JSON.parse(existingText.slice(handler.start, handler.end));
+            if (JSON.stringify(current) !== JSON.stringify(desired)) {
+                edits.push({ start: handler.start, end: handler.end, text: (0, json_spans_1.jsonAt)(desired, (0, json_spans_1.columnOf)(existingText, handler.start)) });
+                actions.push(`updated the FlowRail ${phase} hook in place`);
+            }
+            continue;
+        }
+        (newGroups.get(event) ?? newGroups.set(event, []).get(event)).push(groupFor(phase));
+        actions.push(`added the FlowRail ${phase} hook`);
+    }
+    // New groups go at the END of their event (never before foreign groups,
+    // which would shift their indices and revoke their trust).
+    const newEvents = [];
+    for (const [event, groups] of newGroups) {
+        const eventEntry = hooksObj?.entries.find((e) => e.key === event);
+        if (eventEntry === undefined) {
+            newEvents.push([event, groups]);
+            continue;
+        }
+        const arr = eventEntry.value;
+        if (arr.items.length === 0) {
+            edits.push({ start: arr.start, end: arr.end, text: (0, json_spans_1.jsonAt)(groups, (0, json_spans_1.columnOf)(existingText, eventEntry.keyStart)) });
+        }
+        else {
+            const last = arr.items[arr.items.length - 1];
+            const col = (0, json_spans_1.columnOf)(existingText, last.start);
+            edits.push({ start: last.end, end: last.end, text: groups.map((g) => `,\n${' '.repeat(col)}${(0, json_spans_1.jsonAt)(g, col)}`).join('') });
+        }
+    }
+    if (newEvents.length > 0) {
+        const obj = hooksObj ?? root;
+        const additions = hooksObj === undefined ? [['hooks', Object.fromEntries(newEvents)]] : newEvents;
+        if (obj.entries.length === 0) {
+            edits.push({ start: obj.start, end: obj.end, text: (0, json_spans_1.jsonAt)(Object.fromEntries(additions), (0, json_spans_1.columnOf)(existingText, obj.start)) });
+        }
+        else {
+            const lastEntry = obj.entries[obj.entries.length - 1];
+            const col = (0, json_spans_1.columnOf)(existingText, lastEntry.keyStart);
+            edits.push({
+                start: lastEntry.value.end,
+                end: lastEntry.value.end,
+                text: additions.map(([k, v]) => `,\n${' '.repeat(col)}${JSON.stringify(k)}: ${(0, json_spans_1.jsonAt)(v, col)}`).join(''),
+            });
+        }
+    }
+    if (edits.length === 0)
+        return { text: null, actions: [] };
+    const text = (0, json_spans_1.applyEdits)(existingText, edits);
+    if (!(0, codex_hooks_schema_1.codexWouldLoadHooksJson)(text)) {
+        throw new env_1.InitError(`internal error: the merged ${exports.CODEX_HOOKS_PATH} would not load in Codex; nothing was written.`);
+    }
+    return { text, actions };
+}
+// ---------------------------------------------------------------------------
+// .codex/config.toml
+// ---------------------------------------------------------------------------
+exports.TOML_BLOCK_BEGIN = '# >>> flowrail (managed by `npx @flowrail/init --agent codex`; edits inside are replaced on re-run)';
+exports.TOML_BLOCK_END = '# <<< flowrail';
+function tomlString(value) {
+    return JSON.stringify(value); // a JSON string literal is a valid TOML basic string
+}
+function findManagedBlock(text) {
+    const begin = text.indexOf(exports.TOML_BLOCK_BEGIN);
+    if (begin === -1) {
+        if (text.includes(exports.TOML_BLOCK_END)) {
+            throw new env_1.InitError(`${exports.CODEX_CONFIG_PATH} has a FlowRail end marker without a start marker. Fix it and re-run.`);
+        }
+        return null;
+    }
+    if (text.indexOf(exports.TOML_BLOCK_BEGIN, begin + 1) !== -1) {
+        throw new env_1.InitError(`${exports.CODEX_CONFIG_PATH} contains more than one FlowRail managed block. Keep one and re-run.`);
+    }
+    const endMarker = text.indexOf(exports.TOML_BLOCK_END, begin);
+    if (endMarker === -1) {
+        throw new env_1.InitError(`${exports.CODEX_CONFIG_PATH}: the FlowRail managed block is not closed. Fix it and re-run.`);
+    }
+    let end = endMarker + exports.TOML_BLOCK_END.length;
+    if (text[end] === '\n')
+        end += 1;
+    return { start: begin, end };
+}
+function parseTomlOrThrow(text, what) {
+    try {
+        return (0, smol_toml_1.parse)(text);
+    }
+    catch (err) {
+        throw new env_1.InitError(`${what} is not valid TOML (${err.message.split('\n')[0]}). Fix it before re-running.`);
+    }
+}
+function flowrailServer(doc) {
+    const servers = doc['mcp_servers'];
+    if (!servers || typeof servers !== 'object')
+        return undefined;
+    const entry = servers['flowrail'];
+    return entry && typeof entry === 'object' ? entry : undefined;
+}
+/** Explicit per-tool approval choices inside an existing managed block —
+ *  preserved across re-runs and upgrades (ADR-050 D9). */
+function existingApprovals(blockText) {
+    const out = {};
+    try {
+        const server = flowrailServer((0, smol_toml_1.parse)(blockText));
+        const tools = server?.['tools'];
+        if (tools && typeof tools === 'object') {
+            for (const [tool, spec] of Object.entries(tools)) {
+                const mode = spec?.approval_mode;
+                if (typeof mode === 'string')
+                    out[tool] = mode;
+            }
+        }
+    }
+    catch {
+        /* an unparseable block is replaced wholesale */
+    }
+    return out;
+}
+function renderCodexTomlBlock(mcpBaseUrl, approvals = {}) {
+    const lines = [
+        exports.TOML_BLOCK_BEGIN,
+        '[mcp_servers.flowrail]',
+        `url = ${tomlString(`${mcpBaseUrl.replace(/\/+$/, '')}/mcp`)}`,
+        'bearer_token_env_var = "FLOWRAIL_API_KEY"',
+        'startup_timeout_sec = 20',
+        'tool_timeout_sec = 150',
+        'http_headers = { "X-FlowRail-Agent" = "codex" }',
+    ];
+    for (const tool of exports.CODEX_APPROVED_TOOLS) {
+        lines.push('', `[mcp_servers.flowrail.tools.${tool}]`, `approval_mode = ${tomlString(approvals[tool] ?? 'approve')}`);
+    }
+    lines.push(exports.TOML_BLOCK_END);
+    return lines.join('\n') + '\n';
+}
+/**
+ * Upsert the managed block. Refuses — before anything is written — when the
+ * file is not valid TOML, when `mcp_servers.flowrail` is defined outside the
+ * block (in any representation), or when the result would not parse to the
+ * intended server definition. Returns null when the file is already current.
+ */
+function upsertCodexConfigToml(existingText, mcpBaseUrl) {
+    const text = existingText ?? '';
+    parseTomlOrThrow(text, exports.CODEX_CONFIG_PATH);
+    const block = findManagedBlock(text);
+    const outside = block ? text.slice(0, block.start) + text.slice(block.end) : text;
+    if (flowrailServer(parseTomlOrThrow(outside, exports.CODEX_CONFIG_PATH)) !== undefined) {
+        throw new env_1.InitError(`${exports.CODEX_CONFIG_PATH} already defines [mcp_servers.flowrail] outside FlowRail's managed block. ` +
+            'Remove that definition (init will write its own) and re-run.');
+    }
+    const rendered = renderCodexTomlBlock(mcpBaseUrl, block ? existingApprovals(text.slice(block.start, block.end)) : {});
+    let next;
+    if (block) {
+        next = text.slice(0, block.start) + rendered + text.slice(block.end);
+    }
+    else {
+        const sep = text === '' ? '' : text.endsWith('\n\n') ? '' : text.endsWith('\n') ? '\n' : '\n\n';
+        next = text + sep + rendered;
+    }
+    const result = flowrailServer(parseTomlOrThrow(next, `The updated ${exports.CODEX_CONFIG_PATH}`));
+    if (result?.['url'] !== `${mcpBaseUrl.replace(/\/+$/, '')}/mcp` || result?.['bearer_token_env_var'] !== 'FLOWRAIL_API_KEY') {
+        throw new env_1.InitError(`Could not add FlowRail's MCP server to ${exports.CODEX_CONFIG_PATH} safely (for example, mcp_servers is an inline ` +
+            'table). Convert it to [mcp_servers.<name>] tables and re-run.');
+    }
+    return next === existingText ? null : next;
+}
+// ---------------------------------------------------------------------------
+// AGENTS.md
+// ---------------------------------------------------------------------------
+exports.AGENTS_BEGIN = '<!-- flowrail:begin (managed by @flowrail/init; edits inside are replaced on re-run) -->';
+exports.AGENTS_END = '<!-- flowrail:end -->';
+exports.AGENTS_BLOCK = [
+    exports.AGENTS_BEGIN,
+    '## FlowRail',
+    '',
+    'This repository is protected by FlowRail. FlowRail checks file edits and shell commands',
+    'before they run and may block a tool call with a reason explaining what to change.',
+    '',
+    '- File edits go through the `apply_patch` tool. Patches run from the shell are blocked,',
+    '  because FlowRail cannot verify them.',
+    '- When a FlowRail block says a check is incomplete, retrying the same change later is safe.',
+    '- FlowRail skills are available in `.agents/skills/` (design review, verify, dependency',
+    '  check, lineage, app review) and use the `flowrail_*` MCP tools.',
+    exports.AGENTS_END,
+].join('\n') + '\n';
+/** Upsert the managed block, preserving everything else. Null = unchanged. */
+function upsertAgentsMd(existingText) {
+    const text = existingText ?? '';
+    const begin = text.indexOf(exports.AGENTS_BEGIN);
+    let next;
+    if (begin === -1) {
+        if (text.includes(exports.AGENTS_END)) {
+            throw new env_1.InitError(`${exports.AGENTS_MD_PATH} has a FlowRail end marker without a start marker. Fix it and re-run.`);
+        }
+        const sep = text === '' ? '' : text.endsWith('\n\n') ? '' : text.endsWith('\n') ? '\n' : '\n\n';
+        next = text + sep + exports.AGENTS_BLOCK;
+    }
+    else {
+        if (text.indexOf(exports.AGENTS_BEGIN, begin + 1) !== -1) {
+            throw new env_1.InitError(`${exports.AGENTS_MD_PATH} contains more than one FlowRail block. Keep one and re-run.`);
+        }
+        const endIdx = text.indexOf(exports.AGENTS_END, begin);
+        if (endIdx === -1)
+            throw new env_1.InitError(`${exports.AGENTS_MD_PATH}: the FlowRail block is not closed. Fix it and re-run.`);
+        let end = endIdx + exports.AGENTS_END.length;
+        if (text[end] === '\n')
+            end += 1;
+        next = text.slice(0, begin) + exports.AGENTS_BLOCK + text.slice(end);
+    }
+    return next === existingText ? null : next;
+}
+/** Files the Codex target writes or reads for a literal-token preflight. */
+exports.CODEX_TRACKED_CONFIGS = [exports.CODEX_HOOKS_PATH, exports.CODEX_CONFIG_PATH, exports.AGENTS_MD_PATH];