@bluenotelogic/harness 0.1.0

package/dist/oauth.js

@@ -0,0 +1,345 @@
+/**
+ * OAuth 2.1 client for Blue Note Memory — authorization-code + PKCE over a loopback
+ * redirect, with a device-code fallback for headless machines.
+ *
+ * WHY LOOPBACK AND NOT A FIXED PORT: this is a public native client, so RFC 8252 §7.3
+ * applies — bind an ephemeral port and register a regex redirect. The `blue-note-mem-mcp`
+ * client on Blue Note ID already has `http://(127\.0\.0\.1|localhost):[0-9]{1,5}/.*`
+ * registered for exactly this. A fixed port would collide with whatever else is running.
+ *
+ * WHY WE STILL CALL /register: Authentik has no RFC 7591 dynamic client registration, so
+ * mem-mcp serves a shim that hands back the pre-registered public client_id. Calling it is
+ * the spec-correct discovery path and costs one request; `--client-id` skips it.
+ *
+ * NO CLIENT SECRET ANYWHERE. A public client cannot keep one, which is the whole point:
+ * PKCE is what binds the authorization code to this process.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+/**
+ * PKCE S256. The verifier is 32 random bytes base64url-encoded (43 chars — comfortably
+ * inside RFC 7636's 43..128 range); the challenge is its SHA-256, also base64url.
+ */
+export function createPkce() {
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+export function base64url(buf) {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+ * Constant-time compare for the `state` parameter. Not strictly required — state is an
+ * integrity check, not a secret — but a length-independent comparison keeps the callback
+ * handler free of an early-exit oracle, and it costs nothing.
+ */
+export function safeEqual(a, b) {
+    const ba = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ba.length !== bb.length)
+        return false;
+    return timingSafeEqual(ba, bb);
+}
+/**
+ * Every discovered endpoint must be https and live on the same host as the issuer, and
+ * must not smuggle credentials in the userinfo part. Same rule the PHP side applies in
+ * lib/Auth/BlueNoteOidc.php — a metadata document is attacker-influencable input, so a
+ * redirected authorization_endpoint is a credential-phishing primitive if left unchecked.
+ *
+ * Loopback (http://127.0.0.1) is exempt because that is our OWN redirect target, never a
+ * discovered endpoint.
+ */
+export function assertSafeEndpoint(url, issuer, what) {
+    let u;
+    let iss;
+    try {
+        u = new URL(url);
+        iss = new URL(issuer);
+    }
+    catch {
+        throw new Error(`${what} is not a valid URL: ${url}`);
+    }
+    if (u.protocol !== "https:")
+        throw new Error(`${what} must be https, got: ${url}`);
+    if (u.username || u.password)
+        throw new Error(`${what} must not embed credentials: ${url}`);
+    if (u.host !== iss.host) {
+        throw new Error(`${what} host (${u.host}) does not match issuer host (${iss.host})`);
+    }
+}
+async function getJson(url, what) {
+    const res = await fetch(url, { headers: { accept: "application/json" } });
+    if (!res.ok)
+        throw new Error(`${what}: ${res.status} ${res.statusText} from ${url}`);
+    return (await res.json());
+}
+/**
+ * RFC 9728 protected-resource metadata -> RFC 8414 authorization-server metadata.
+ *
+ * The resource document is what a spec-compliant MCP client finds from the endpoint's
+ * `401 + WWW-Authenticate: Bearer resource_metadata="..."`. We follow the same chain
+ * rather than hardcoding paths, so a self-hosted deployment works with only `--url`.
+ */
+export async function discover(baseUrl) {
+    const prm = await getJson(`${baseUrl}/.well-known/oauth-protected-resource`, "protected-resource metadata");
+    const servers = prm["authorization_servers"];
+    const asBase = Array.isArray(servers) && typeof servers[0] === "string" ? servers[0] : baseUrl;
+    const doc = await getJson(`${asBase.replace(/\/$/, "")}/.well-known/oauth-authorization-server`, "authorization-server metadata");
+    const issuer = String(doc["issuer"] ?? asBase);
+    const meta = {
+        issuer,
+        authorization_endpoint: String(doc["authorization_endpoint"] ?? ""),
+        token_endpoint: String(doc["token_endpoint"] ?? ""),
+        device_authorization_endpoint: optString(doc["device_authorization_endpoint"]),
+        registration_endpoint: optString(doc["registration_endpoint"]),
+        code_challenge_methods_supported: Array.isArray(doc["code_challenge_methods_supported"])
+            ? doc["code_challenge_methods_supported"]
+            : undefined,
+    };
+    if (!meta.authorization_endpoint || !meta.token_endpoint) {
+        throw new Error("authorization-server metadata is missing authorization_endpoint/token_endpoint");
+    }
+    assertSafeEndpoint(meta.authorization_endpoint, issuer, "authorization_endpoint");
+    assertSafeEndpoint(meta.token_endpoint, issuer, "token_endpoint");
+    if (meta.device_authorization_endpoint) {
+        assertSafeEndpoint(meta.device_authorization_endpoint, issuer, "device_authorization_endpoint");
+    }
+    if (meta.registration_endpoint) {
+        assertSafeEndpoint(meta.registration_endpoint, issuer, "registration_endpoint");
+    }
+    // Refuse to downgrade. If the server does not advertise S256 we would be left with
+    // `plain`, which offers no protection against an intercepted authorization code.
+    const methods = meta.code_challenge_methods_supported;
+    if (methods && !methods.includes("S256")) {
+        throw new Error("authorization server does not advertise PKCE S256 — refusing to continue");
+    }
+    return meta;
+}
+function optString(v) {
+    return typeof v === "string" && v !== "" ? v : undefined;
+}
+/** The DCR shim. Any failure falls back to the caller's default client_id. */
+export async function registerClient(meta, fallbackClientId) {
+    if (!meta.registration_endpoint)
+        return fallbackClientId;
+    try {
+        const res = await fetch(meta.registration_endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                client_name: "Blue Note harness CLI",
+                redirect_uris: ["http://127.0.0.1/callback"],
+                grant_types: ["authorization_code", "refresh_token"],
+                response_types: ["code"],
+                token_endpoint_auth_method: "none",
+            }),
+        });
+        if (!res.ok)
+            return fallbackClientId;
+        const body = (await res.json());
+        return optString(body["client_id"]) ?? fallbackClientId;
+    }
+    catch {
+        return fallbackClientId;
+    }
+}
+async function postForm(url, form) {
+    return fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+        body: new URLSearchParams(form).toString(),
+    });
+}
+/**
+ * Browser flow. Resolves with an access token, or rejects on timeout / user denial.
+ *
+ * The listener binds 127.0.0.1 EXPLICITLY (not 0.0.0.0) so nothing off-box can reach the
+ * callback, and it shuts down the moment it has an answer — a lingering listener holding a
+ * valid `state` is a needless window.
+ */
+export async function authorizeViaBrowser(opts) {
+    const { meta, clientId, scope, resource } = opts;
+    const log = opts.log ?? (() => { });
+    const timeoutMs = opts.timeoutMs ?? 5 * 60_000;
+    const pkce = createPkce();
+    const state = base64url(randomBytes(24));
+    const { code, redirectUri, server } = await new Promise((resolve, reject) => {
+        const srv = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end("not found");
+                return;
+            }
+            const err = url.searchParams.get("error");
+            const gotState = url.searchParams.get("state") ?? "";
+            const gotCode = url.searchParams.get("code") ?? "";
+            if (err) {
+                respond(res, `Authorization failed: ${err}`);
+                reject(new Error(`authorization denied: ${err}`));
+                return;
+            }
+            if (!safeEqual(gotState, state)) {
+                // A mismatched state means this callback did not come from the request we made.
+                respond(res, "State mismatch — request rejected. You can close this tab.");
+                reject(new Error("state mismatch — possible CSRF, aborting"));
+                return;
+            }
+            if (!gotCode) {
+                respond(res, "No authorization code returned.");
+                reject(new Error("no authorization code in callback"));
+                return;
+            }
+            respond(res, "Signed in. You can close this tab and return to the terminal.");
+            const addr = srv.address();
+            resolve({ code: gotCode, redirectUri: loopbackUri(addr.port), server: srv });
+        });
+        srv.on("error", reject);
+        // Port 0 = let the OS pick a free ephemeral port.
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            const authUrl = new URL(meta.authorization_endpoint);
+            authUrl.searchParams.set("response_type", "code");
+            authUrl.searchParams.set("client_id", clientId);
+            authUrl.searchParams.set("redirect_uri", loopbackUri(addr.port));
+            authUrl.searchParams.set("scope", scope);
+            authUrl.searchParams.set("state", state);
+            authUrl.searchParams.set("code_challenge", pkce.challenge);
+            authUrl.searchParams.set("code_challenge_method", "S256");
+            // RFC 8707: name the resource this token is for, so it cannot be replayed elsewhere.
+            authUrl.searchParams.set("resource", resource);
+            log(`Opening your browser to sign in to Blue Note ID…`);
+            log(`  If it does not open, paste this into a browser:\n  ${authUrl.toString()}\n`);
+            // Say how long the window is. Without this the process just dies at the deadline with no
+            // prior warning, which reads as a broken CLI rather than "you had five minutes".
+            log(`Waiting for you to sign in… (this window closes in ${Math.round(timeoutMs / 1000)}s — widen it with --timeout)`);
+            if (opts.openBrowser !== false)
+                openInBrowser(authUrl.toString());
+        });
+        setTimeout(() => {
+            srv.close();
+            reject(new Error(`timed out after ${Math.round(timeoutMs / 1000)}s waiting for the browser`));
+        }, timeoutMs).unref();
+    });
+    server.close();
+    const res = await postForm(meta.token_endpoint, {
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri,
+        client_id: clientId,
+        code_verifier: pkce.verifier,
+        resource,
+    });
+    if (!res.ok) {
+        throw new Error(`token exchange failed: ${res.status} ${await safeText(res)}`);
+    }
+    return (await res.json());
+}
+function loopbackUri(port) {
+    return `http://127.0.0.1:${port}/callback`;
+}
+function respond(res, message) {
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(`<!doctype html><meta charset="utf-8"><title>Blue Note Memory</title>` +
+        `<body style="font:16px/1.5 system-ui,sans-serif;padding:3rem;max-width:34rem;margin:auto">` +
+        `<h1 style="font-size:1.25rem">Blue Note Memory</h1><p>${escapeHtml(message)}</p></body>`);
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+/**
+ * Device-code flow — for a headless box, an SSH session, or any machine where opening a
+ * browser is not possible. Authentik supports this grant natively and `blue-note-mem-mcp`
+ * already has it enabled, so there is no server-side work behind this path.
+ */
+export async function authorizeViaDevice(opts) {
+    const { meta, clientId, scope, resource } = opts;
+    const log = opts.log ?? (() => { });
+    if (!meta.device_authorization_endpoint) {
+        throw new Error("this server does not advertise a device_authorization_endpoint");
+    }
+    const startRes = await postForm(meta.device_authorization_endpoint, {
+        client_id: clientId,
+        scope,
+    });
+    if (!startRes.ok) {
+        throw new Error(`device authorization failed: ${startRes.status} ${await safeText(startRes)}`);
+    }
+    const start = (await startRes.json());
+    const deviceCode = String(start["device_code"] ?? "");
+    const userCode = String(start["user_code"] ?? "");
+    const verifyUri = String(start["verification_uri_complete"] ?? start["verification_uri"] ?? "");
+    // RFC 8628 §3.5: honour the server's interval; default 5s. Poll faster and you get
+    // slow_down responses, which only makes the flow take longer.
+    let intervalMs = Math.max(1, Number(start["interval"] ?? 5)) * 1000;
+    const serverExpiry = Date.now() + Math.max(60, Number(start["expires_in"] ?? 600)) * 1000;
+    // A client-side --timeout can only ever SHORTEN this. The device code's lifetime belongs to
+    // the IdP (ours issues 60s), so waiting past it would only poll a code the server has already
+    // discarded — take whichever deadline lands first.
+    const expiresAt = opts.timeoutMs
+        ? Math.min(serverExpiry, Date.now() + opts.timeoutMs)
+        : serverExpiry;
+    log(`\n  Open:  ${verifyUri}`);
+    log(`  Code:  ${userCode}\n`);
+    // Surface the window: our IdP issues 60-second device codes, which is tight enough that a
+    // user who wanders off to find their password comes back to an expired one. Saying so beats
+    // a bare "expired" error after the fact.
+    log(`Waiting for you to approve… (this code expires in ${Math.round((expiresAt - Date.now()) / 1000)}s)`);
+    for (;;) {
+        if (Date.now() > expiresAt)
+            throw new Error("device code expired before approval");
+        await sleep(intervalMs);
+        const res = await postForm(meta.token_endpoint, {
+            grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+            device_code: deviceCode,
+            client_id: clientId,
+            resource,
+        });
+        if (res.ok)
+            return (await res.json());
+        const body = (await res.json().catch(() => ({})));
+        const error = String(body["error"] ?? "");
+        if (error === "authorization_pending")
+            continue;
+        if (error === "slow_down") {
+            intervalMs += 5000;
+            continue;
+        }
+        // Blue Note ID (Authentik) answers a still-pending device grant with `invalid_grant`
+        // instead of RFC 8628 §3.5's `authorization_pending`. A spec-literal client therefore
+        // aborts on the FIRST poll — roughly five seconds in, long before a human can approve —
+        // which made --device unusable against our own IdP. Treat it as pending: the expiresAt
+        // deadline above still bounds the loop, so a genuinely bad or revoked device_code ends
+        // as "device code expired before approval" rather than hanging forever.
+        if (error === "invalid_grant")
+            continue;
+        throw new Error(`device authorization failed: ${error || res.status}`);
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 300);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Best-effort browser launch. Failure is non-fatal — the URL is always printed first, so a
+ * machine with no default browser still completes the flow by copy/paste.
+ */
+function openInBrowser(url) {
+    const cmd = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open";
+    // `cmd /c start ""` needs the empty title argument or a quoted URL is taken as the title.
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    }
+    catch {
+        /* printed above; nothing to do */
+    }
+}
+//# sourceMappingURL=oauth.js.map

package/dist/oauth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.js","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}

package/dist/writers.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Turning a bundle into files on disk.
+ *
+ * 🔴 THE MERGE RULE IS NOT A NICETY — IT IS A SCAR.
+ * On 2026-07-17 the predecessor of this code (`bnl-provision-site-mcpjson.sh`) blindly
+ * overwrote three pre-existing `.mcp.json` files that defined unrelated servers. Two were
+ * recoverable from git; one (`boris-console`) had never been tracked and had to be
+ * reconstructed by hand. So: every write reads what is on disk first and replaces ONLY the
+ * keys it owns. A file that is not valid JSON is SKIPPED with a message — never rewritten,
+ * because "it looked broken" is exactly when someone's hand edit is sitting in it.
+ *
+ * Everything here is planned as pure data first (`FileChange[]`) and applied second, so
+ * `--dry-run` shows precisely what would happen and the merge logic is unit-testable
+ * without touching a filesystem.
+ */
+export interface FileChange {
+    path: string;
+    /** Current contents, or null when the file does not exist. */
+    before: string | null;
+    /** Contents to write, or null when nothing should be written. */
+    after: string | null;
+    /** Set when we deliberately declined to write; `after` is null and this explains why. */
+    skipped?: string;
+    /** Advisory shown to the user after a successful apply. */
+    note?: string;
+}
+/** True when the change would actually alter the file. */
+export declare function isNoop(c: FileChange): boolean;
+/**
+ * Merge our server entries into an existing `.mcp.json`.
+ *
+ * `servers` comes straight from the bundle's `mcp_json.mcpServers`, which is TOKENLESS —
+ * OAuth-capable hosts discover auth from the endpoint's 401 and keep their own credentials.
+ * That is what makes the resulting file safe to commit.
+ */
+export declare function planMcpJson(path: string, existing: string | null, servers: Record<string, unknown>): FileChange;
+/**
+ * `.claude/settings.local.json` — an `env` block Claude Code applies to every session.
+ *
+ * WHY THIS EXISTS AT ALL: the VS Code extension launches `claude` without sourcing a shell
+ * env file, so a `${VAR}` reference in `.mcp.json` would not expand there. This file is how
+ * the harness works from the VS Code button rather than only from `source .env && claude`.
+ * Only written when a token was minted — the OAuth path needs no env at all.
+ */
+export declare function planSettingsLocal(path: string, existing: string | null, env: Record<string, string>): FileChange;
+/**
+ * Codex `config.toml`.
+ *
+ * We do NOT parse TOML (that would mean a dependency, and this package has none). Instead:
+ * if a `[mcp_servers.<name>]` table already exists we leave the file completely alone and
+ * hand the user the snippet; otherwise we APPEND the table. Appending is safe because TOML
+ * tables are order-independent, and appending can never corrupt what is already there.
+ *
+ * The token itself never goes in here — it goes to `~/.codex/.env`, referenced by
+ * `bearer_token_env_var`, so the config file stays safe to read over someone's shoulder.
+ */
+export declare function planCodexConfig(path: string, existing: string | null, serverName: string, mcpUrl: string, tokenEnvVar: string): FileChange;
+/** `~/.codex/.env` — one KEY=value line, replaced in place if already present. */
+export declare function planEnvVar(path: string, existing: string | null, key: string, value: string): FileChange;
+/**
+ * `state/routing/{providers,profiles}.server.yaml` — materialized from the console's hosted
+ * routing. These are plain overwrites, and that is correct: the files live in a CLI-owned
+ * directory and their own banner says "Do not edit by hand". A local `providers.yaml` still
+ * takes precedence in the resolver, so nobody's hand-tuned routing is affected.
+ */
+export declare function planRoutingFile(path: string, existing: string | null, body: string): FileChange;
+/**
+ * Guard: refuse to write anything that looks like a credential into a repo-visible file.
+ *
+ * The default path must never mint or persist a secret, so this is a hard assertion rather
+ * than a warning — if it ever fires, a change has reintroduced exactly the problem this
+ * tool exists to remove.
+ */
+export declare function assertNoSecret(c: FileChange): void;
+export declare function readIfExists(path: string): string | null;
+export declare function apply(changes: FileChange[], dryRun: boolean): void;

package/dist/writers.js

@@ -0,0 +1,190 @@
+/**
+ * Turning a bundle into files on disk.
+ *
+ * 🔴 THE MERGE RULE IS NOT A NICETY — IT IS A SCAR.
+ * On 2026-07-17 the predecessor of this code (`bnl-provision-site-mcpjson.sh`) blindly
+ * overwrote three pre-existing `.mcp.json` files that defined unrelated servers. Two were
+ * recoverable from git; one (`boris-console`) had never been tracked and had to be
+ * reconstructed by hand. So: every write reads what is on disk first and replaces ONLY the
+ * keys it owns. A file that is not valid JSON is SKIPPED with a message — never rewritten,
+ * because "it looked broken" is exactly when someone's hand edit is sitting in it.
+ *
+ * Everything here is planned as pure data first (`FileChange[]`) and applied second, so
+ * `--dry-run` shows precisely what would happen and the merge logic is unit-testable
+ * without touching a filesystem.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+/** True when the change would actually alter the file. */
+export function isNoop(c) {
+    return c.after === null || c.after === c.before;
+}
+/**
+ * Merge our server entries into an existing `.mcp.json`.
+ *
+ * `servers` comes straight from the bundle's `mcp_json.mcpServers`, which is TOKENLESS —
+ * OAuth-capable hosts discover auth from the endpoint's 401 and keep their own credentials.
+ * That is what makes the resulting file safe to commit.
+ */
+export function planMcpJson(path, existing, servers) {
+    let doc = {};
+    if (existing !== null && existing.trim() !== "") {
+        try {
+            const parsed = JSON.parse(existing);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                throw new Error("not a JSON object");
+            }
+            doc = parsed;
+        }
+        catch (e) {
+            return {
+                path,
+                before: existing,
+                after: null,
+                skipped: `existing .mcp.json is not valid JSON (${e.message}) — ` +
+                    `left untouched. Fix or remove it by hand, then re-run.`,
+            };
+        }
+    }
+    const current = typeof doc["mcpServers"] === "object" && doc["mcpServers"] !== null && !Array.isArray(doc["mcpServers"])
+        ? doc["mcpServers"]
+        : {};
+    // Only our own keys are replaced. Any other server entry survives byte-for-byte through
+    // the round trip, which is the whole point of parsing rather than templating.
+    doc["mcpServers"] = { ...current, ...servers };
+    return { path, before: existing, after: JSON.stringify(doc, null, 2) + "\n" };
+}
+/**
+ * `.claude/settings.local.json` — an `env` block Claude Code applies to every session.
+ *
+ * WHY THIS EXISTS AT ALL: the VS Code extension launches `claude` without sourcing a shell
+ * env file, so a `${VAR}` reference in `.mcp.json` would not expand there. This file is how
+ * the harness works from the VS Code button rather than only from `source .env && claude`.
+ * Only written when a token was minted — the OAuth path needs no env at all.
+ */
+export function planSettingsLocal(path, existing, env) {
+    let doc = {};
+    if (existing !== null && existing.trim() !== "") {
+        try {
+            const parsed = JSON.parse(existing);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                throw new Error("not a JSON object");
+            }
+            doc = parsed;
+        }
+        catch (e) {
+            return {
+                path,
+                before: existing,
+                after: null,
+                skipped: `existing settings.local.json is not valid JSON (${e.message}) — left untouched.`,
+            };
+        }
+    }
+    const currentEnv = typeof doc["env"] === "object" && doc["env"] !== null && !Array.isArray(doc["env"])
+        ? doc["env"]
+        : {};
+    doc["env"] = { ...currentEnv, ...env };
+    return {
+        path,
+        before: existing,
+        after: JSON.stringify(doc, null, 2) + "\n",
+        note: "holds a plaintext token — make sure .claude/settings.local.json is gitignored",
+    };
+}
+/**
+ * Codex `config.toml`.
+ *
+ * We do NOT parse TOML (that would mean a dependency, and this package has none). Instead:
+ * if a `[mcp_servers.<name>]` table already exists we leave the file completely alone and
+ * hand the user the snippet; otherwise we APPEND the table. Appending is safe because TOML
+ * tables are order-independent, and appending can never corrupt what is already there.
+ *
+ * The token itself never goes in here — it goes to `~/.codex/.env`, referenced by
+ * `bearer_token_env_var`, so the config file stays safe to read over someone's shoulder.
+ */
+export function planCodexConfig(path, existing, serverName, mcpUrl, tokenEnvVar) {
+    const table = `[mcp_servers.${serverName}]`;
+    const block = `\n# Added by @bluenotelogic/harness. Codex cannot do OAuth yet, so it reads a token\n` +
+        `# from the environment; the value lives in ~/.codex/.env, never in this file.\n` +
+        `${table}\n` +
+        `url = "${mcpUrl}"\n` +
+        `bearer_token_env_var = "${tokenEnvVar}"\n`;
+    if (existing !== null && existing.includes(table)) {
+        return {
+            path,
+            before: existing,
+            after: null,
+            skipped: `${table} already present — left untouched. If the URL changed, update it by hand:\n` +
+                block.trim(),
+        };
+    }
+    const base = existing ?? "";
+    const sep = base === "" || base.endsWith("\n") ? "" : "\n";
+    return { path, before: existing, after: base + sep + block };
+}
+/** `~/.codex/.env` — one KEY=value line, replaced in place if already present. */
+export function planEnvVar(path, existing, key, value) {
+    const line = `${key}=${value}`;
+    const base = existing ?? "";
+    const re = new RegExp(`^${escapeRe(key)}=.*$`, "m");
+    const after = re.test(base)
+        ? base.replace(re, line)
+        : base + (base === "" || base.endsWith("\n") ? "" : "\n") + line + "\n";
+    return {
+        path,
+        before: existing,
+        after,
+        note: "holds a plaintext token — never commit it",
+    };
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * `state/routing/{providers,profiles}.server.yaml` — materialized from the console's hosted
+ * routing. These are plain overwrites, and that is correct: the files live in a CLI-owned
+ * directory and their own banner says "Do not edit by hand". A local `providers.yaml` still
+ * takes precedence in the resolver, so nobody's hand-tuned routing is affected.
+ */
+export function planRoutingFile(path, existing, body) {
+    return { path, before: existing, after: body.endsWith("\n") ? body : body + "\n" };
+}
+/**
+ * Guard: refuse to write anything that looks like a credential into a repo-visible file.
+ *
+ * The default path must never mint or persist a secret, so this is a hard assertion rather
+ * than a warning — if it ever fires, a change has reintroduced exactly the problem this
+ * tool exists to remove.
+ */
+export function assertNoSecret(c) {
+    if (c.after === null)
+        return;
+    const found = c.after.match(/\b(cmem|mcp)_[A-Za-z0-9_-]{16,}/);
+    if (found) {
+        throw new Error(`refusing to write what looks like a live token into ${c.path} ` +
+            `(matched ${found[0].slice(0, 8)}…). Tokens belong in ~/.codex/.env or ` +
+            `.claude/settings.local.json, never in a committed config.`);
+    }
+}
+export function readIfExists(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function apply(changes, dryRun) {
+    for (const c of changes) {
+        if (c.after === null || isNoop(c))
+            continue;
+        if (dryRun)
+            continue;
+        const dir = dirname(c.path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(c.path, c.after, "utf8");
+    }
+}
+//# sourceMappingURL=writers.js.map

package/dist/writers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writers.js","sourceRoot":"","sources":["../src/writers.ts"],"names":[],"mappings":"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"}