agent-trellis 0.1.0 → 0.3.0

package/dist/core/canonical.js

@@ -4,11 +4,29 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
-import { parse as parseYaml } from "yaml";
+import { isMap, parse as parseYaml, parseDocument } from "yaml";
 import { ALL_AGENTS } from "./types.js";
+function fromServerDefYaml(def) {
+    const { static_env, ...rest } = def;
+    return static_env ? { ...rest, staticEnv: static_env } : rest;
+}
+/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
+ * `undefined` fields so the written YAML never gets a literal `null`
+ * for an omitted optional. */
+export function toServerDefYaml(def) {
+    const { staticEnv, ...rest } = def;
+    const out = { ...rest };
+    if (staticEnv)
+        out.static_env = staticEnv;
+    for (const key of Object.keys(out)) {
+        if (out[key] === undefined)
+            delete out[key];
+    }
+    return out;
+}
 function trellisRoot(homeDir) {
     return join(homeDir, ".trellis");
 }
@@ -58,12 +76,72 @@ function loadServersYaml(path) {
         return { servers: {}, knownHostInjected: [] };
     }
     const parsed = (parseYaml(readFileSync(path, "utf-8")) ?? {});
+    const servers = Object.fromEntries(Object.entries(parsed.servers ?? {}).map(([name, def]) => [name, fromServerDefYaml(def)]));
     return {
-        servers: parsed.servers ?? {},
+        servers,
         knownHostInjected: parsed.known_host_injected ?? [],
         hub: parsed.hub,
     };
 }
+/**
+ * Writes or replaces one server entry in `servers.yaml`, preserving
+ * every other entry's and comment's exact formatting (trellis-
+ * canonical-cli-crud design.md D3) — a `Document`-based edit
+ * (`setIn`), never `parse` + rebuild + `stringify`, which would
+ * re-serialize the whole file and lose anything hand-authored outside
+ * the touched entry. Refuses (no write) if the file doesn't exist yet
+ * (run `trellis init` first) or fails to parse.
+ */
+/**
+ * `trellis init`'s starter `servers.yaml` writes `servers: {}` — an empty
+ * flow-style map, since there's nothing to indent yet. `Document#setIn`
+ * inserting into an *existing* flow map keeps rendering it as flow, so
+ * the first `mcp add`/`migrate --only mcp` onto a fresh file — and every
+ * one after it — would render as one unreadable line (found via actually
+ * running the CLI against a fresh `init`, not by inspection). Forcing the
+ * touched map, and the newly-set entry's own map, to block style is a
+ * one-line, local fix — it never touches any sibling entry's own style,
+ * so a file someone deliberately kept flow-style elsewhere is untouched.
+ */
+function forceBlockStyle(node) {
+    if (isMap(node)) {
+        node.flow = false;
+    }
+}
+export function upsertServerYaml(path, name, def) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    doc.setIn(["servers", name], toServerDefYaml(def));
+    forceBlockStyle(doc.get("servers", true));
+    forceBlockStyle(doc.getIn(["servers", name], true));
+    writeFileSync(path, doc.toString());
+    return { ok: true };
+}
+/** Inverse of `upsertServerYaml` — same preservation guarantee, same
+ * refusal posture on a missing/unparseable file. */
+export function removeServerYaml(path, name) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    doc.deleteIn(["servers", name]);
+    writeFileSync(path, doc.toString());
+    return { ok: true };
+}
 function loadSecretsPolicyYaml(path, homeDir) {
     if (!existsSync(path)) {
         return { allowedVars: [], rejectPatterns: [] };
@@ -78,6 +156,26 @@ function loadSecretsPolicyYaml(path, homeDir) {
 /** `undefined` if the name has no entry in scope.yaml's map — "shared with
  * all four agents," the default. A recognized but empty list is left as
  * authored (an explicitly agent-less scope), not coerced to "all". */
+/** Missing file and `agents: []` both resolve to `[]` — zero managed
+ * agents (D1), never "everyone." An unrecognized id is dropped with a
+ * diagnostic, same posture as an unrecognized scope.yaml agent id. */
+function loadManagedYaml(path, diagnostics) {
+    if (!existsSync(path)) {
+        return [];
+    }
+    const parsed = (parseYaml(readFileSync(path, "utf-8")) ?? {});
+    const raw = parsed.agents ?? [];
+    const valid = [];
+    for (const id of raw) {
+        if (ALL_AGENTS.includes(id)) {
+            valid.push(id);
+        }
+        else {
+            diagnostics.push(`managed.yaml: "${id}" is not a recognized agent id — ignored`);
+        }
+    }
+    return valid;
+}
 function scopeFor(map, name) {
     return map?.[name];
 }
@@ -100,6 +198,7 @@ export function loadCanonicalSource(homeDir = homedir()) {
         throw new Error(`No canonical source at ${root}. Create it before running trellis sync — see docs/architecture.md's canonical schema.`);
     }
     const diagnostics = [];
+    const managedAgents = loadManagedYaml(join(root, "managed.yaml"), diagnostics);
     const scopeYaml = loadScopeYaml(join(root, "scope.yaml"));
     const skillDirs = listSkillDirs(join(root, "skills"));
     const knownSkillNames = new Set(skillDirs.map((s) => s.name));
@@ -135,6 +234,7 @@ export function loadCanonicalSource(homeDir = homedir()) {
     }
     return {
         instructionsFile: join(root, "agents.md"),
+        managedAgents,
         skills,
         agents,
         memories,

package/dist/core/types.d.ts

@@ -15,7 +15,15 @@ export declare const ALL_AGENTS: readonly AgentId[];
  * "Private / agent-specific capabilities".
  */
 export type Scope = AgentId[] | undefined;
-export declare function resolveScope(scope: Scope): readonly AgentId[];
+/**
+ * `managedAgents` is the hard outer boundary (trellis-managed-agents
+ * design.md D6): no-scope items resolve to it instead of `ALL_AGENTS`, and
+ * an item WITH an explicit scope is intersected with it, never returned
+ * verbatim — a skill scoped to `[kiro]` must still not reach Kiro if Kiro
+ * isn't in the managed set. Presence on the machine is irrelevant here;
+ * only membership in `managedAgents` is.
+ */
+export declare function resolveScope(scope: Scope, managedAgents: readonly AgentId[]): readonly AgentId[];
 export interface McpServerDef {
     transport: Transport;
     /** stdio only */
@@ -36,6 +44,23 @@ export interface McpServerDef {
      * docs/research.md "Secrets" and schema/secrets.policy.example.yaml.
      */
     env?: string[];
+    /**
+     * Literal, non-secret values written into the agent's config verbatim
+     * — distinct from `env`'s names-only, resolved-at-runtime contract.
+     * Still scanned against `reject_patterns` like every other literal
+     * field (trellis-mcp-static-env-and-disabled-servers design.md D2):
+     * this is for values that were never secrets (an email address, an
+     * environment tag), not an escape hatch for real credentials.
+     */
+    staticEnv?: Record<string, string>;
+    /**
+     * Defaults to `true`. `false` keeps the definition in canonical
+     * without writing it to any agent — matches a real host config's own
+     * "defined but currently off" state (e.g. Codex's `enabled = false`)
+     * that omitting the definition entirely can't represent, since that
+     * would also throw away the definition itself.
+     */
+    enabled?: boolean;
     /** Omit for "all agents" (the default). See `Scope`. */
     agents?: Scope;
 }
@@ -190,6 +215,9 @@ export interface CanonicalSource {
      * that decision.
      */
     instructionsFile: string;
+    /** From `~/.trellis/managed.yaml`. Missing file and `agents: []` both
+     * resolve to `[]` — zero managed agents, never "everyone" (D1). */
+    managedAgents: readonly AgentId[];
     skills: SkillRef[];
     agents: AgentProfile[];
     memories: MemoryEntry[];

package/dist/core/types.js

@@ -10,6 +10,15 @@ export const ALL_AGENTS = [
     "kiro",
     "pi",
 ];
-export function resolveScope(scope) {
-    return scope ?? ALL_AGENTS;
+/**
+ * `managedAgents` is the hard outer boundary (trellis-managed-agents
+ * design.md D6): no-scope items resolve to it instead of `ALL_AGENTS`, and
+ * an item WITH an explicit scope is intersected with it, never returned
+ * verbatim — a skill scoped to `[kiro]` must still not reach Kiro if Kiro
+ * isn't in the managed set. Presence on the machine is irrelevant here;
+ * only membership in `managedAgents` is.
+ */
+export function resolveScope(scope, managedAgents) {
+    const candidates = scope ?? managedAgents;
+    return candidates.filter((id) => managedAgents.includes(id));
 }

package/dist/lib/backup.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Structured, timestamped backup of every real write `sync`/`mcp sync`
+ * perform, and the only path any of them writes disk through — see
+ * openspec/changes/trellis-backup-rollback/design.md D3/D5 for why the
+ * write itself lives here rather than at each call site: a call site
+ * that only had to remember to *also* call a record function is exactly
+ * the class of bug trellis-managed-agents found in symlinkPlan.ts. A run
+ * directory is created lazily on the first recorded operation; a session
+ * that never records anything creates nothing on disk.
+ */
+export type BackupOperation = {
+    kind: "file-create";
+    path: string;
+    afterHash: string;
+} | {
+    kind: "file-overwrite";
+    path: string;
+    beforeFile: string;
+    beforeHash: string;
+    afterHash: string;
+} | {
+    kind: "symlink-create";
+    path: string;
+    afterLinkTarget: string;
+} | {
+    kind: "symlink-repair";
+    path: string;
+    beforeLinkTarget: string;
+    afterLinkTarget: string;
+} | {
+    kind: "symlink-remove";
+    path: string;
+    beforeLinkTarget: string;
+};
+export interface BackupManifest {
+    runId: string;
+    command: string;
+    startedAt: string;
+    operations: BackupOperation[];
+}
+export interface BackupSession {
+    writeFile(path: string, content: string): void;
+    createSymlink(path: string, linkTarget: string): Promise<void>;
+    repairSymlink(path: string, oldLinkTarget: string, newLinkTarget: string): Promise<void>;
+    removeSymlink(path: string, oldLinkTarget: string): Promise<void>;
+    /** Writes manifest.json. No-op (creates nothing) if zero operations
+     * were ever recorded. */
+    finalize(): void;
+}
+export declare function backupsRoot(homeDir: string): string;
+export declare function openBackupSession(homeDir: string, command: string): BackupSession;
+/** Used by `applySymlinkPlan` and every adapter's own read-before-repair
+ * logic — it needs the symlink's current stored target before the
+ * session's own repair/remove overwrites it. Not part of `BackupSession`
+ * itself: it's a read, not a recorded write. */
+export declare function currentLinkTarget(path: string): Promise<string | undefined>;

package/dist/lib/backup.js

@@ -0,0 +1,98 @@
+/**
+ * Structured, timestamped backup of every real write `sync`/`mcp sync`
+ * perform, and the only path any of them writes disk through — see
+ * openspec/changes/trellis-backup-rollback/design.md D3/D5 for why the
+ * write itself lives here rather than at each call site: a call site
+ * that only had to remember to *also* call a record function is exactly
+ * the class of bug trellis-managed-agents found in symlinkPlan.ts. A run
+ * directory is created lazily on the first recorded operation; a session
+ * that never records anything creates nothing on disk.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readlink, rm, symlink } from "node:fs/promises";
+import { basename, join } from "node:path";
+function sha256(content) {
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+/** `:` and `.` are legal in POSIX filenames but awkward across shells and
+ * some tooling; replaced so a run id is safe to pass around bare. */
+function runIdFor(command) {
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    return `${ts}-${command}`;
+}
+export function backupsRoot(homeDir) {
+    return join(homeDir, ".trellis", "backups");
+}
+export function openBackupSession(homeDir, command) {
+    const runId = runIdFor(command);
+    const runDir = join(backupsRoot(homeDir), runId);
+    const startedAt = new Date().toISOString();
+    const operations = [];
+    let dirCreated = false;
+    let fileIndex = 0;
+    function ensureDir() {
+        if (dirCreated)
+            return;
+        mkdirSync(join(runDir, "files"), { recursive: true });
+        dirCreated = true;
+    }
+    return {
+        writeFile(path, content) {
+            ensureDir();
+            const afterHash = sha256(content);
+            if (existsSync(path)) {
+                const before = readFileSync(path, "utf-8");
+                const relSnapshot = join("files", `${fileIndex}-${basename(path)}`);
+                fileIndex += 1;
+                writeFileSync(join(runDir, relSnapshot), before);
+                operations.push({
+                    kind: "file-overwrite",
+                    path,
+                    beforeFile: relSnapshot,
+                    beforeHash: sha256(before),
+                    afterHash,
+                });
+            }
+            else {
+                operations.push({ kind: "file-create", path, afterHash });
+            }
+            writeFileSync(path, content);
+        },
+        async createSymlink(path, linkTarget) {
+            ensureDir();
+            await rm(path, { force: true });
+            await symlink(linkTarget, path);
+            operations.push({ kind: "symlink-create", path, afterLinkTarget: linkTarget });
+        },
+        async repairSymlink(path, oldLinkTarget, newLinkTarget) {
+            ensureDir();
+            await rm(path, { force: true });
+            await symlink(newLinkTarget, path);
+            operations.push({ kind: "symlink-repair", path, beforeLinkTarget: oldLinkTarget, afterLinkTarget: newLinkTarget });
+        },
+        async removeSymlink(path, oldLinkTarget) {
+            ensureDir();
+            await rm(path, { force: true });
+            operations.push({ kind: "symlink-remove", path, beforeLinkTarget: oldLinkTarget });
+        },
+        finalize() {
+            if (!dirCreated)
+                return;
+            const manifest = { runId, command, startedAt, operations };
+            writeFileSync(join(runDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+        },
+    };
+}
+/** Used by `applySymlinkPlan` and every adapter's own read-before-repair
+ * logic — it needs the symlink's current stored target before the
+ * session's own repair/remove overwrites it. Not part of `BackupSession`
+ * itself: it's a read, not a recorded write. */
+export async function currentLinkTarget(path) {
+    try {
+        return await readlink(path);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/deepEqual.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Structural equality for plain JSON-shaped values — shared by every
+ * "does this already match what Trellis would write/has written"
+ * comparison (jsonMcp.ts's create/remove decisions, migrate-in's
+ * conflict detection) so they can't silently drift apart into two
+ * different notions of "equal."
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/dist/lib/deepEqual.js

@@ -0,0 +1,26 @@
+/**
+ * Structural equality for plain JSON-shaped values — shared by every
+ * "does this already match what Trellis would write/has written"
+ * comparison (jsonMcp.ts's create/remove decisions, migrate-in's
+ * conflict detection) so they can't silently drift apart into two
+ * different notions of "equal."
+ */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((value, index) => deepEqual(value, b[index]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length)
+            return false;
+        return aKeys.every((key) => deepEqual(a[key], b[key]));
+    }
+    return false;
+}

package/dist/lib/dirEquals.d.ts

@@ -5,3 +5,12 @@
  * paths, same bytes per file; anything else is unequal.
  */
 export declare function dirContentsEqual(a: string, b: string): boolean;
+export type DirImportDecision = "create" | "already-present" | "conflict";
+/**
+ * Shared create/already-present/conflict decision for copying a real
+ * directory into a canonical destination — used by both `migrate`'s
+ * own skill planning and `trellis skill add` (trellis-canonical-cli-crud
+ * design.md D2), so the two never silently drift apart on what counts
+ * as "safe to skip" vs. "a real conflict."
+ */
+export declare function decideDirImport(sourceDir: string, canonicalDir: string): DirImportDecision;

package/dist/lib/dirEquals.js

@@ -4,7 +4,7 @@
  * by this, not by name/mtime/hash-shortcut. Same set of relative file
  * paths, same bytes per file; anything else is unequal.
  */
-import { readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 function listFilesRecursive(dir) {
     const results = [];
@@ -37,3 +37,17 @@ export function dirContentsEqual(a, b) {
     }
     return true;
 }
+/**
+ * Shared create/already-present/conflict decision for copying a real
+ * directory into a canonical destination — used by both `migrate`'s
+ * own skill planning and `trellis skill add` (trellis-canonical-cli-crud
+ * design.md D2), so the two never silently drift apart on what counts
+ * as "safe to skip" vs. "a real conflict."
+ */
+export function decideDirImport(sourceDir, canonicalDir) {
+    if (!existsSync(canonicalDir))
+        return "create";
+    if (dirContentsEqual(sourceDir, canonicalDir))
+        return "already-present";
+    return "conflict";
+}

package/dist/lib/installAgent.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Install-then-manage (trellis-managed-agents design.md D5): selecting a
+ * not-yet-present agent into the managed set is itself the authorization
+ * to install it, but never silently — one confirmation, then a real
+ * `npm install -g <package>` child process. Kiro has no npm package (a
+ * desktop download) and is refused before this module is ever reached.
+ */
+import type { AgentId } from "../core/types.js";
+/** Only agents with a real `npm install -g <pkg>` command — Kiro's own
+ * `INSTALL_HINTS` entry is a download URL, not a package, and is never
+ * looked up here. */
+export declare const NPM_INSTALLABLE: Record<Exclude<AgentId, "kiro">, string>;
+export interface ConfirmAndInstallOptions {
+    /** Test/real seam, same pattern as onboard's `promptForAgent` — a real
+     * terminal confirmation by default. */
+    confirm?: (agent: AgentId, pkg: string) => Promise<boolean>;
+    /** Test/real seam — never a real `npm install` in a unit test. */
+    runInstall?: (pkg: string) => void;
+}
+export interface ConfirmAndInstallResult {
+    installed: boolean;
+    /** False only when the agent has no npm package at all (Kiro) — the
+     * caller refuses this agent with its download URL instead of prompting. */
+    installable: boolean;
+}
+export declare function confirmAndInstall(agent: AgentId, opts?: ConfirmAndInstallOptions): Promise<ConfirmAndInstallResult>;

package/dist/lib/installAgent.js

@@ -0,0 +1,46 @@
+/**
+ * Install-then-manage (trellis-managed-agents design.md D5): selecting a
+ * not-yet-present agent into the managed set is itself the authorization
+ * to install it, but never silently — one confirmation, then a real
+ * `npm install -g <package>` child process. Kiro has no npm package (a
+ * desktop download) and is refused before this module is ever reached.
+ */
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+/** Only agents with a real `npm install -g <pkg>` command — Kiro's own
+ * `INSTALL_HINTS` entry is a download URL, not a package, and is never
+ * looked up here. */
+export const NPM_INSTALLABLE = {
+    "claude-code": "@anthropic-ai/claude-code",
+    codex: "@openai/codex",
+    pi: "@earendil-works/pi-coding-agent",
+};
+async function confirmReal(agent, pkg) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`${agent} is not installed. Install it now (npm install -g ${pkg})? [y/N] `)).trim().toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+function runInstallReal(pkg) {
+    // argv array, never a shell string — the package name is never
+    // interpolated into anything a shell parses.
+    execFileSync("npm", ["install", "-g", pkg], { stdio: "inherit" });
+}
+export async function confirmAndInstall(agent, opts = {}) {
+    if (agent === "kiro") {
+        return { installed: false, installable: false };
+    }
+    const pkg = NPM_INSTALLABLE[agent];
+    const confirm = opts.confirm ?? confirmReal;
+    const runInstall = opts.runInstall ?? runInstallReal;
+    const agreed = await confirm(agent, pkg);
+    if (!agreed) {
+        return { installed: false, installable: true };
+    }
+    runInstall(pkg);
+    return { installed: true, installable: true };
+}

package/dist/lib/mcpMigrateRead.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Reads an agent's own real, already-configured MCP servers and converts
+ * each into canonical's `McpServerDef` shape — `trellis migrate --only
+ * mcp`'s read path (trellis-migrate-mcp-servers). Deliberately separate
+ * from each probe's own `AgentSnapshotMcpServer` (src/probes/*.ts) and its
+ * thin `{name, transport, probe?}` shape used by `doctor` — that shape
+ * discards exactly the fields this module needs, and extending it would
+ * risk `doctor`'s existing, extensively-tested behavior for no reason
+ * (design.md D1). pi has no static MCP config to read at all — no reader
+ * is defined for it; `migrate.ts` skips pi for the `mcp` category
+ * entirely, the same fact already established for skills/instructions.
+ */
+import type { McpServerDef } from "../core/types.js";
+export interface McpMigrateEntry {
+    name: string;
+    def: McpServerDef;
+}
+export interface McpMigrateUnsupported {
+    name: string;
+    reason: string;
+}
+export interface McpMigrateReadResult {
+    entries: McpMigrateEntry[];
+    unsupported: McpMigrateUnsupported[];
+}
+export declare function readClaudeCodeMcpDefs(homeDir: string): McpMigrateReadResult;
+export declare function readKiroMcpDefs(homeDir: string): McpMigrateReadResult;
+export interface CodexMcpEntryRich {
+    name: string;
+    enabled: boolean;
+    transport: {
+        type: string;
+        command?: string;
+        args?: string[];
+        env_vars?: string[];
+        /** Remote-transport fields. Confirmed by running the real,
+         * locally-installed `codex-cli 0.154.0` against a hand-written
+         * `url`-only server and a `url` + `bearer_token_env_var` server: the
+         * type string is `"streamable_http"` (not `"http"`), and the three
+         * `*headers*` fields come back `null` when unused. Codex's own
+         * config.toml schema (`tomlSection.ts`'s `renderServerSection`) has
+         * no way to distinguish `http` from `sse` at all — both render
+         * identically — so there is no lossy guess in always reading a
+         * remote entry back as `"http"`; that distinction was never stored. */
+        url?: string;
+        bearer_token_env_var?: string | null;
+        http_headers?: unknown;
+        env_http_headers?: unknown;
+        http_headers_helper?: unknown;
+    };
+}
+/**
+ * Pure conversion half — separated from the subprocess/file-read effects
+ * below so the stdio/non-stdio/malformed decision logic is unit-testable
+ * without a real `codex` binary on PATH (this codebase has no fake-codex
+ * fixture anywhere; codex's subprocess dependency is otherwise entirely
+ * untested at the unit level).
+ */
+export declare function buildCodexMcpReadResult(mcpEntries: CodexMcpEntryRich[], tomlContent: string | undefined): McpMigrateReadResult;
+/**
+ * Stdio only (design.md D2) — `codex mcp list --json`'s own output never
+ * exposes `url`/`bearer_token_env_var` in this codebase's `CodexMcpEntry`
+ * (src/probes/codex.ts), and this codebase has no verified evidence for
+ * what that subprocess reports for a non-stdio server. Guessing at an
+ * external tool's unverified output shape is exactly what this project's
+ * "verify, don't assume" discipline exists to prevent — a non-stdio
+ * entry is reported as unsupported instead.
+ */
+export declare function readCodexMcpDefs(homeDir: string): McpMigrateReadResult;