@aperant/framework 0.8.7 → 0.10.0

package/src/cli/install/mcp-provision.mjs

@@ -0,0 +1,293 @@
+/**
+ * install/mcp-provision.mjs — TOFU install-time MCP-server + skill provisioner.
+ *
+ * Called from cmdInit (the only call site — the QUICK fast-path never invokes
+ * init, so the Fast Path Guarantee is structurally untouched). Detects the
+ * project's runtime, then for each selected host CLI that supports the action:
+ *
+ *   - kind 'mcp-server' (electron/tauri) → write the server into the host's
+ *     MCP config (claude → .mcp.json JSON merge; codex → .codex/config.toml
+ *     TOML upsert).
+ *   - kind 'skill' (agent-browser) → copy the vendored SKILL.md into the
+ *     host's skill dir (claude → .claude/skills/; codex → .agents/skills/).
+ *
+ * Every write is TOFU/idempotent (ID-05): if the target server id / table /
+ * skill file already exists, SKIP (never diff/merge/overwrite) — this is the
+ * must-not-clobber invariant for a hand-authored electron
+ * SCREENSHOT_ENCRYPTION_KEY (US-3) and a user-edited agent-browser skill
+ * (US-6). Each action appends one audit line to .aperant/events/{date}.jsonl.
+ *
+ * Gated behind config.verification.provision_mcp (default true) so users can
+ * opt out. Never throws — wraps the body in try/catch → {status:'error'}.
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+import { appendJsonl, atomicWriteJson, atomicWriteText } from '../util/atomic-write.mjs'
+import { dailyEventsPath } from '../util/events-path.mjs'
+import { capabilityToProvisionIds, PROVISION_SPECS } from './mcp-server-specs.mjs'
+import { loadRuntimeCapabilities } from './runtime-detect.mjs'
+import { upsertMcpServerToml } from './toml-merge.mjs'
+
+/**
+ * Per-host writer registry (ID-07, ID-08). v1 = claude + codex. The MCP
+ * config path AND skill dir are EXPLICIT per host — neither is derived from
+ * the runtime's installRoot (Codex's MCP path .codex/config.toml diverges
+ * from its skill dir .agents/skills/). Adding gemini/opencode later = one
+ * entry each.
+ *
+ * @type {Record<string, {mcpFormat: 'json'|'toml', mcpConfigPath: string, skillDir: string}>}
+ */
+const HOST_PROVISION_WRITERS = {
+	claude: { mcpFormat: 'json', mcpConfigPath: '.mcp.json', skillDir: '.claude/skills' },
+	codex: { mcpFormat: 'toml', mcpConfigPath: '.codex/config.toml', skillDir: '.agents/skills' },
+}
+
+/**
+ * Substitute the per-project socket basename into the tauri launcher
+ * template, deriving uniqueness from the project dir basename.
+ *
+ * @param {string} template
+ * @param {string} targetDir
+ * @returns {string}
+ */
+function renderTauriLauncher(template, targetDir) {
+	const slug =
+		basename(resolve(targetDir))
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, '-')
+			.replace(/^-+|-+$/g, '') || 'tauri'
+	return template.replaceAll('{{PROJECT_SOCKET}}', slug)
+}
+
+/**
+ * Write the electron/tauri MCP server into a Claude `.mcp.json`. JSON merge:
+ * read-or-{}, ensure mcpServers, SKIP if the server id already exists, else
+ * insert {type:'stdio', command, args, env?} preserving all sibling keys.
+ *
+ * TOFU non-clobber (ID-05): if the existing file fails to parse OR parses to
+ * a non-plain-object root (array / null / primitive), do NOT overwrite it —
+ * return `skipped_unsafe` with a reason so the caller can audit it and leave
+ * the file byte-identical. (`typeof [] === 'object'` is why arrays must be
+ * excluded explicitly: a `.mcp.json` containing `[]` would otherwise pass the
+ * object guard, drop the user's content on stringify, and report `written`.)
+ *
+ * @param {string} configPath — absolute path to .mcp.json
+ * @param {string} serverId
+ * @param {import('./mcp-server-specs.mjs').McpServerSpec} spec
+ * @returns {{action: 'written'|'skipped'|'skipped_unsafe', reason?: string}}
+ */
+function writeClaudeMcpServer(configPath, serverId, spec) {
+	let config = {}
+	if (existsSync(configPath)) {
+		try {
+			config = JSON.parse(readFileSync(configPath, 'utf-8'))
+		} catch {
+			// Malformed JSON: overwriting would erase every hand-authored MCP
+			// server. Leave the file untouched and surface it.
+			return { action: 'skipped_unsafe', reason: 'malformed_json' }
+		}
+		if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+			// Non-plain-object root (array / null / primitive): same non-clobber
+			// rule — never overwrite content we cannot safely merge into.
+			return { action: 'skipped_unsafe', reason: 'non_object_root' }
+		}
+	}
+	if (config.mcpServers === null || typeof config.mcpServers !== 'object') {
+		config.mcpServers = {}
+	}
+	// TOFU: never clobber a hand-authored server id.
+	if (Object.hasOwn(config.mcpServers, serverId)) return { action: 'skipped' }
+
+	const entry = { type: 'stdio', command: spec.command, args: spec.args ?? [] }
+	if (spec.env && Object.keys(spec.env).length > 0) entry.env = spec.env
+	config.mcpServers[serverId] = entry
+	atomicWriteJson(configPath, config)
+	return { action: 'written' }
+}
+
+/**
+ * Write the electron/tauri MCP server into a Codex `.codex/config.toml`.
+ *
+ * @param {string} configPath — absolute path to .codex/config.toml
+ * @param {string} serverId
+ * @param {import('./mcp-server-specs.mjs').McpServerSpec} spec
+ * @returns {{action: 'written'|'skipped'}}
+ */
+function writeCodexMcpServer(configPath, serverId, spec) {
+	const existing = existsSync(configPath) ? readFileSync(configPath, 'utf-8') : ''
+	const { content, action } = upsertMcpServerToml(existing, serverId, {
+		command: spec.command,
+		args: spec.args ?? [],
+		...(spec.env && Object.keys(spec.env).length > 0 ? { env: spec.env } : {}),
+	})
+	if (action === 'written') atomicWriteText(configPath, content)
+	return { action }
+}
+
+/**
+ * Copy the vendored skill into a host skill dir. TOFU: never overwrite an
+ * existing agent-browser/SKILL.md (a user may have edited it).
+ *
+ * @param {string} skillDestPath — absolute <skillDir>/<skillId>/SKILL.md
+ * @param {string} vendoredSkillPath — absolute source path
+ * @returns {'written'|'skipped'}
+ */
+function copySkill(skillDestPath, vendoredSkillPath) {
+	if (existsSync(skillDestPath)) return 'skipped'
+	mkdirSync(dirname(skillDestPath), { recursive: true })
+	// copyFileSync is fine here — atomicWriteText would re-read; the dest is
+	// guaranteed absent (TOFU check above) so there is no clobber risk.
+	copyFileSync(vendoredSkillPath, skillDestPath)
+	return 'written'
+}
+
+/**
+ * Provision MCP servers + skills for the selected host CLIs.
+ *
+ * @param {Object} opts
+ * @param {string} opts.targetDir — project root being installed into
+ * @param {string[]} opts.selectedRuntimes — the runtimes the user selected
+ * @param {object} opts.config — the effective merged project config
+ * @param {string} opts.frameworkRoot — absolute path to packages/framework (for vendored skill resolution)
+ * @returns {{status: 'ok'|'disabled'|'error', writes?: Array<{host:string, spec_id:string, kind:string, action:string}>, reason?: string}}
+ */
+export function provisionMcpConfig(opts) {
+	const targetDir = resolve(opts.targetDir)
+	const config = opts.config ?? {}
+	const selected = Array.isArray(opts.selectedRuntimes) ? opts.selectedRuntimes : []
+	const frameworkRoot = opts.frameworkRoot
+
+	try {
+		// (1) Opt-out gate (default true).
+		if (config?.verification?.provision_mcp === false) {
+			appendEvent(targetDir, 'mcp-provision.disabled', {
+				reason: 'verification.provision_mcp=false',
+			})
+			return { status: 'disabled' }
+		}
+
+		// (2) Detect runtime → derive spec ids.
+		const runtimeCaps = loadRuntimeCapabilities(targetDir)
+		const specIds = capabilityToProvisionIds(runtimeCaps)
+
+		/** @type {Array<{host:string, spec_id:string, kind:string, action:string}>} */
+		const writes = []
+
+		// Iterate every (selected host, spec) pair.
+		for (const host of selected) {
+			const writer = HOST_PROVISION_WRITERS[host]
+			if (!writer) {
+				// Selected host with no writer (gemini/opencode/... in v1) — record
+				// once as unsupported_host, no write.
+				writes.push({ host, spec_id: '*', kind: '*', action: 'unsupported_host' })
+				appendEvent(targetDir, 'mcp-provision.unsupported_host', { host })
+				continue
+			}
+
+			for (const specId of specIds) {
+				const spec = PROVISION_SPECS[specId]
+				if (!spec) continue
+
+				if (spec.kind === 'mcp-server') {
+					const configPath = join(targetDir, writer.mcpConfigPath)
+					const { action, reason } =
+						writer.mcpFormat === 'json'
+							? writeClaudeMcpServer(configPath, specId, spec)
+							: writeCodexMcpServer(configPath, specId, spec)
+					writes.push({ host, spec_id: specId, kind: 'mcp-server', action })
+					appendEvent(targetDir, `mcp-provision.${action}`, {
+						host,
+						spec_id: specId,
+						config_path: writer.mcpConfigPath,
+						...(reason ? { reason } : {}),
+					})
+					// (5) tauri needs its launcher script — only provision it once the
+					// MCP config entry is actually written, so a TOFU-skipped or
+					// skipped_unsafe config never leaves an orphan launcher + a
+					// misleading audit line.
+					if (spec.requiresLauncherScript && frameworkRoot && action === 'written') {
+						provisionTauriLauncher(targetDir, frameworkRoot, writes)
+					}
+				} else if (spec.kind === 'skill') {
+					if (!frameworkRoot) continue
+					const vendoredSkillPath = resolve(frameworkRoot, spec.vendoredSkillRelPath)
+					const skillDestPath = join(targetDir, writer.skillDir, spec.skillId, 'SKILL.md')
+					const action = copySkill(skillDestPath, vendoredSkillPath)
+					writes.push({ host, spec_id: specId, kind: 'skill', action })
+					appendEvent(
+						targetDir,
+						`skill-provision.${action}`,
+						{
+							host,
+							spec_id: specId,
+							skill_dir: writer.skillDir,
+						},
+						'skill_provision',
+					)
+				}
+			}
+		}
+
+		return { status: 'ok', writes }
+	} catch (e) {
+		return { status: 'error', reason: e instanceof Error ? e.message : String(e) }
+	}
+}
+
+/**
+ * Copy the tauri launcher template into the project's scripts/ dir (TOFU).
+ * Records its own audit line; appends to `writes` with a synthetic host.
+ *
+ * @param {string} targetDir
+ * @param {string} frameworkRoot
+ * @param {Array<{host:string, spec_id:string, kind:string, action:string}>} writes
+ */
+function provisionTauriLauncher(targetDir, frameworkRoot, writes) {
+	const destPath = join(targetDir, 'scripts', 'tauri-mcp.sh')
+	// Already recorded a launcher write/skip for this run? Only provision once.
+	if (writes.some((w) => w.kind === 'launcher')) return
+	if (existsSync(destPath)) {
+		writes.push({ host: '-', spec_id: 'tauri', kind: 'launcher', action: 'skipped' })
+		appendEvent(targetDir, 'mcp-provision.skipped', {
+			host: '-',
+			spec_id: 'tauri',
+			launcher: 'scripts/tauri-mcp.sh',
+		})
+		return
+	}
+	const templatePath = resolve(frameworkRoot, 'drivers/tauri/scripts/tauri-mcp.sh')
+	const template = readFileSync(templatePath, 'utf-8')
+	atomicWriteText(destPath, renderTauriLauncher(template, targetDir))
+	writes.push({ host: '-', spec_id: 'tauri', kind: 'launcher', action: 'written' })
+	appendEvent(targetDir, 'mcp-provision.written', {
+		host: '-',
+		spec_id: 'tauri',
+		launcher: 'scripts/tauri-mcp.sh',
+	})
+}
+
+/**
+ * Append one audit line to .aperant/events/{date}.jsonl, mirroring the
+ * daily-events shape. `kind` discriminates the provisioning channel:
+ * `mcp_provision` for MCP-server + launcher events, `skill_provision` for
+ * skill-copy events.
+ *
+ * @param {string} targetDir
+ * @param {string} op — e.g. mcp-provision.written, skill-provision.skipped
+ * @param {Record<string, unknown>} [extra]
+ * @param {string} [kind] — audit channel (default `mcp_provision`)
+ */
+function appendEvent(targetDir, op, extra = {}, kind = 'mcp_provision') {
+	try {
+		const path = dailyEventsPath(targetDir)
+		appendJsonl(path, {
+			ts: new Date().toISOString(),
+			kind,
+			op,
+			...extra,
+		})
+	} catch {
+		// Audit is best-effort — never fail provisioning on a log write error.
+	}
+}

package/src/cli/install/mcp-server-specs.mjs

@@ -0,0 +1,101 @@
+/**
+ * install/mcp-server-specs.mjs — single-sourced install-time provision specs.
+ *
+ * One registry, two kinds (ID-03):
+ *   - kind 'mcp-server' (electron, tauri): the {command, args, env?} the
+ *     installer writes into each host CLI's MCP config. Keyed by the SAME
+ *     `transport.mcp_server_id` string the driver manifests carry.
+ *   - kind 'skill' (agent-browser): the vendored SKILL.md the installer
+ *     copies into each host CLI's skill dir. Keyed by the SAME
+ *     `transport.skill_id` the browser driver manifest carries.
+ *
+ * We do NOT derive commands from the driver manifests — manifests are
+ * transport-agnostic by design (ID-01 keeps the verb→tool mapping in the
+ * driver; this is a separate install-only transport/skill concern). We do
+ * NOT add a per-driver mcp-server.json (over-engineering for 3 specs —
+ * CLAUDE.md Simplicity First).
+ *
+ * Pure module — no fs, no exec.
+ */
+
+/**
+ * @typedef {Object} McpServerSpec
+ * @property {'mcp-server'} kind
+ * @property {string} command
+ * @property {string[]} args
+ * @property {Record<string, string>} [env]
+ * @property {boolean} [requiresLauncherScript] — tauri: copy scripts/tauri-mcp.sh first
+ *
+ * @typedef {Object} SkillSpec
+ * @property {'skill'} kind
+ * @property {string} skillId
+ * @property {string} vendoredSkillRelPath — relative to the framework root
+ *
+ * @typedef {McpServerSpec | SkillSpec} ProvisionSpec
+ */
+
+/**
+ * The install-time provision specs, keyed by spec id.
+ *
+ * `electron` / `tauri` ids match each driver manifest's
+ * `transport.mcp_server_id`; `agent-browser` matches the browser driver
+ * manifest's `transport.skill_id`.
+ *
+ * @type {Record<string, ProvisionSpec>}
+ */
+export const PROVISION_SPECS = {
+	// kind 'mcp-server'
+	electron: {
+		kind: 'mcp-server',
+		command: 'npx',
+		args: ['-y', 'electron-mcp-server'],
+		// No SCREENSHOT_ENCRYPTION_KEY — left for the user to add per ID-09.
+		env: {},
+	},
+	tauri: {
+		kind: 'mcp-server',
+		// The tauri-plugin-mcp-server npm bin ships without a shebang, so it
+		// cannot be invoked via `npx -y`. We launch it through a generated
+		// scripts/tauri-mcp.sh (ID-04) — the proven racing-ai shape.
+		command: 'bash',
+		args: ['./scripts/tauri-mcp.sh'],
+		requiresLauncherScript: true,
+	},
+	// kind 'skill'
+	'agent-browser': {
+		kind: 'skill',
+		skillId: 'agent-browser',
+		// Vendored UNDER the browser driver (NOT skills/agent-browser/) so the
+		// install pipeline's discoverCanonicalFiles does not auto-install it
+		// into every project unconditionally — that would break the
+		// verification.provision_mcp opt-out (AC7) and the web-frontend runtime
+		// gate. The provisioner (mcp-provision.mjs) is the sole installer.
+		vendoredSkillRelPath: 'drivers/browser/skill/agent-browser/SKILL.md',
+	},
+}
+
+/**
+ * Map a project's runtime capabilities to the provision spec ids it
+ * triggers. A multi-surface monorepo (e.g. electron + nextjs) returns
+ * multiple ids.
+ *
+ *   is_electron                          → ['electron']
+ *   is_tauri                             → ['tauri']
+ *   is_web_frontend|is_nextjs|is_nuxt    → ['agent-browser']
+ *
+ * Accepts a partial capability record — only the flags it reads need be
+ * present (the rest default to absent/false).
+ *
+ * @param {Partial<import('../util/runtime-capabilities.mjs').RuntimeCapabilities>} runtimeCaps
+ * @returns {string[]}
+ */
+export function capabilityToProvisionIds(runtimeCaps) {
+	const ids = []
+	if (!runtimeCaps || typeof runtimeCaps !== 'object') return ids
+	if (runtimeCaps.is_electron) ids.push('electron')
+	if (runtimeCaps.is_tauri) ids.push('tauri')
+	if (runtimeCaps.is_web_frontend || runtimeCaps.is_nextjs || runtimeCaps.is_nuxt) {
+		ids.push('agent-browser')
+	}
+	return ids
+}

package/src/cli/install/runtime-detect.mjs

@@ -18,6 +18,15 @@ import { existsSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { MANIFEST_FILENAME } from './manifest.mjs'
 
+// Package.json-shape capability detection lives in util/ (shared with
+// verify-proof/runtime-detect.mjs). Re-exported here so install-layer callers
+// (e.g. install/mcp-provision.mjs) consume it from their OWN layer instead of
+// reaching across into verify-proof/.
+export {
+	detectFromPackageJson,
+	loadRuntimeCapabilities,
+} from '../util/runtime-capabilities.mjs'
+
 /**
  * @typedef {Object} RuntimeDescriptor
  * @property {string} id            Stable identifier (`claude`, `cursor`, …).
@@ -36,6 +45,18 @@ import { MANIFEST_FILENAME } from './manifest.mjs'
  *                                  capitalized form of `id`. Use for runtimes
  *                                  whose product branding differs from the
  *                                  internal id (C58: `kilo` → "Kilo Code").
+ * @property {string|null} nativeInstructionFile
+ *                                  The root-level instruction file this
+ *                                  runtime's native CLI reads (e.g. `claude`
+ *                                  reads `CLAUDE.md`, `codex` reads
+ *                                  `AGENTS.md`). `init` stamps the
+ *                                  `<!-- APT:framework-* -->` managed block
+ *                                  into every distinct non-null target for the
+ *                                  selected runtimes. `null` means the runtime
+ *                                  installs to its own surface (e.g. cursor →
+ *                                  `.cursor/rules`), NOT a root `.md` — `init`
+ *                                  skips null entries. Nullable by design, not
+ *                                  a future-work placeholder (ID-01).
  */
 
 /** @type {RuntimeDescriptor[]} */
@@ -46,6 +67,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.claude',
 		markers: ['.claude/settings.json', '.claude/settings.local.json'],
 		cliId: 'claude-code',
+		nativeInstructionFile: 'CLAUDE.md',
 	},
 	{
 		id: 'codex',
@@ -53,6 +75,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.agents',
 		markers: ['.codex/config.toml'],
 		cliId: 'codex',
+		nativeInstructionFile: 'AGENTS.md',
 	},
 	{
 		id: 'cursor',
@@ -60,6 +83,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.cursor',
 		markers: ['.cursor/settings.json'],
 		cliId: 'cursor',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'gemini',
@@ -67,6 +91,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.gemini',
 		markers: ['.gemini/settings.json'],
 		cliId: 'gemini-cli',
+		nativeInstructionFile: 'GEMINI.md',
 	},
 	{
 		id: 'opencode',
@@ -74,6 +99,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.opencode',
 		markers: ['.opencode/config.json'],
 		cliId: 'opencode',
+		nativeInstructionFile: 'AGENTS.md',
 	},
 	{
 		id: 'pi',
@@ -81,6 +107,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.pi',
 		markers: ['.pi/settings.json', '.pi/skills', '.pi/prompts'],
 		cliId: 'pi',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'kilo',
@@ -92,6 +119,7 @@ export const RUNTIMES = Object.freeze([
 		// migration per spec ID-01). `--kilocode` is also accepted as a
 		// deprecated alias of `--kilo` at the CLI flag parser layer.
 		displayLabel: 'Kilo Code',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'copilot',
@@ -99,6 +127,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.github/copilot',
 		markers: ['.github/copilot-instructions.md'],
 		cliId: 'copilot',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'antigravity',
@@ -106,6 +135,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.antigravity',
 		markers: ['.antigravity/config.json'],
 		cliId: 'antigravity',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'windsurf',
@@ -113,6 +143,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.windsurf',
 		markers: ['.windsurfrules'],
 		cliId: 'windsurf',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'augment',
@@ -120,6 +151,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.augment',
 		markers: ['.augment/config.json'],
 		cliId: 'augment',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'trae',
@@ -127,6 +159,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.trae',
 		markers: ['.trae/config.json'],
 		cliId: 'trae',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'qwen',
@@ -134,6 +167,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.qwen',
 		markers: ['.qwen/config.json'],
 		cliId: 'qwen',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'cline',
@@ -141,6 +175,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.cline',
 		markers: ['.cline/config.json'],
 		cliId: 'cline',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'codebuddy',
@@ -148,6 +183,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.codebuddy',
 		markers: ['.codebuddy/config.json'],
 		cliId: 'codebuddy',
+		nativeInstructionFile: null,
 	},
 ])
 

package/src/cli/install/toml-merge.mjs

@@ -0,0 +1,139 @@
+/**
+ * install/toml-merge.mjs — dependency-free minimal TOML upsert for the
+ * Codex MCP-server config table.
+ *
+ * Codex's MCP config lives at project-root `.codex/config.toml` as:
+ *
+ *   [mcp_servers.<id>]
+ *   command = "bash"
+ *   args = ["./scripts/tauri-mcp.sh"]
+ *
+ *   [mcp_servers.<id>.env]
+ *   FOO = "bar"
+ *
+ * No TOML serializer ships in the framework and `@iarna/toml` is not a
+ * dependency, so we hand-roll the MINIMAL upsert covering ONLY this shape
+ * (string command, string[] args, optional nested env table of
+ * string=string). Presence is detected by scanning for the
+ * `[mcp_servers.<id>]` header line; if present, we SKIP unchanged (TOFU
+ * per ID-05) — never diff/merge/overwrite a hand-authored table. All other
+ * content is preserved verbatim; the new table block is appended at EOF.
+ *
+ * Pure module — string in, string out.
+ */
+
+/**
+ * Escape a string for a TOML basic (double-quoted) string. Only the
+ * characters that can occur in a command/arg/env value: backslash and
+ * double-quote.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function tomlString(s) {
+	return `"${String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+}
+
+/**
+ * Render a TOML array of double-quoted strings: `["a", "b"]`.
+ *
+ * @param {string[]} arr
+ * @returns {string}
+ */
+function tomlStringArray(arr) {
+	return `[${arr.map((a) => tomlString(a)).join(', ')}]`
+}
+
+/**
+ * Render a TOML key. A bare key (TOML `[A-Za-z0-9_-]+`) is emitted verbatim;
+ * any other key is quoted as a TOML basic string so a non-bare env name
+ * (e.g. one containing `.`, a space, or `"`) cannot break the table or inject
+ * extra structure.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+function tomlKey(key) {
+	return /^[A-Za-z0-9_-]+$/.test(key) ? key : tomlString(key)
+}
+
+/**
+ * Whether `existingToml` already declares a `[mcp_servers.<id>]` table.
+ * Matches the header at the start of a line (ignoring leading whitespace),
+ * permitting an optional TOML trailing comment (` # …`) after the header —
+ * a hand-authored `[mcp_servers.tauri] # my server` must still count as
+ * present, otherwise the upsert would append a DUPLICATE table and produce
+ * an unparseable config (two same-named tables). The id is taken literally
+ * (dotted-key TOML ids do not occur for our server ids — electron/tauri are
+ * bare) and regex-escaped defensively. A `#`-prefixed comment LINE that
+ * merely mentions the header is NOT a match (the header must be the first
+ * non-whitespace token).
+ *
+ * @param {string} existingToml
+ * @param {string} serverId
+ * @returns {boolean}
+ */
+export function hasMcpServerTable(existingToml, serverId) {
+	if (typeof existingToml !== 'string' || existingToml.length === 0) return false
+	const escapedId = serverId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+	// `[mcp_servers.<id>]` at line start (after optional indent), optionally
+	// followed by whitespace and/or a `#` trailing comment, to EOL.
+	const headerRe = new RegExp(`^\\s*\\[mcp_servers\\.${escapedId}\\]\\s*(#.*)?$`)
+	const lines = existingToml.split(/\r?\n/)
+	for (const line of lines) {
+		if (headerRe.test(line)) return true
+	}
+	return false
+}
+
+/**
+ * Upsert a `[mcp_servers.<id>]` table into a Codex config.toml string.
+ *
+ * TOFU (ID-05): if a `[mcp_servers.<id>]` table already exists, returns the
+ * input unchanged with `action: 'skipped'`. Otherwise appends the new table
+ * (and a nested `[mcp_servers.<id>.env]` table when `env` is non-empty) at
+ * EOF, preserving all existing content verbatim, and returns the new
+ * content with `action: 'written'`.
+ *
+ * @param {string} existingToml — current file contents ('' when the file is absent)
+ * @param {string} serverId
+ * @param {{command: string, args: string[], env?: Record<string, string>}} spec
+ * @returns {{content: string, action: 'written'|'skipped'}}
+ */
+export function upsertMcpServerToml(existingToml, serverId, spec) {
+	const existing = typeof existingToml === 'string' ? existingToml : ''
+	if (hasMcpServerTable(existing, serverId)) {
+		return { content: existing, action: 'skipped' }
+	}
+
+	const lines = []
+	lines.push(`[mcp_servers.${serverId}]`)
+	lines.push(`command = ${tomlString(spec.command)}`)
+	lines.push(`args = ${tomlStringArray(spec.args ?? [])}`)
+
+	const env = spec.env && typeof spec.env === 'object' ? spec.env : null
+	const envKeys = env ? Object.keys(env) : []
+	if (envKeys.length > 0) {
+		lines.push('')
+		lines.push(`[mcp_servers.${serverId}.env]`)
+		for (const key of envKeys) {
+			lines.push(`${tomlKey(key)} = ${tomlString(env[key])}`)
+		}
+	}
+
+	const block = lines.join('\n')
+
+	// Preserve existing content; separate the new block with exactly one blank
+	// line. An empty existing file yields just the block + trailing newline.
+	// Strip the existing file's trailing newline run first so a file that
+	// already ends in a blank line (`…\n\n`) does not produce a DOUBLE blank
+	// line before the appended block.
+	let content
+	if (existing.trim().length === 0) {
+		content = `${block}\n`
+	} else {
+		const head = existing.replace(/\n+$/, '')
+		content = `${head}\n\n${block}\n`
+	}
+	return { content, action: 'written' }
+}