@aperant/framework 0.9.0 → 0.10.0

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`, …).

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' }
+}

package/src/cli/util/events-path.mjs

@@ -0,0 +1,24 @@
+/**
+ * util/events-path.mjs — canonical path computation for the per-day event
+ * log at `.aperant/events/{YYYY-MM-DD}.jsonl` (ID-05).
+ *
+ * Lives in util/ so both the install layer (install/mcp-provision.mjs) and the
+ * verify-proof layer (verify-proof/audit.mjs) compute the same path WITHOUT
+ * install/ importing from verify-proof/ (the layer-boundary rule). Pure
+ * function — no fs, no exec.
+ */
+
+import { join, resolve } from 'node:path'
+
+/**
+ * Compute today's events filename relative to projectDir.
+ * @param {string} projectDir
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function dailyEventsPath(projectDir, now = new Date()) {
+	const yyyy = now.getUTCFullYear()
+	const mm = String(now.getUTCMonth() + 1).padStart(2, '0')
+	const dd = String(now.getUTCDate()).padStart(2, '0')
+	return join(resolve(projectDir), '.aperant/events', `${yyyy}-${mm}-${dd}.jsonl`)
+}

package/src/cli/util/runtime-capabilities.mjs

@@ -0,0 +1,216 @@
+/**
+ * util/runtime-capabilities.mjs — pure project-shape capability detection.
+ *
+ * Extracted from packages/core/src/prompts/prompt-loader.ts:572-595 so the
+ * framework CLI is self-contained (no @aperant/core dep). Same heuristics:
+ * read package.json's dependencies + devDependencies, return a capability
+ * record the resolver can score against.
+ *
+ * Lives in util/ so BOTH the verify-proof layer (verify-proof/runtime-detect.mjs
+ * re-exports it) AND the install layer (install/runtime-detect.mjs re-exports
+ * it) can share one implementation without install/ importing from
+ * verify-proof/ (the layer-boundary rule).
+ *
+ * Pattern: pure data in → pure data out. No filesystem walking, no exec.
+ * Use loadRuntimeCapabilities(projectDir) for the cwd-rooted variant.
+ *
+ * v0.8.6 — `loadRuntimeCapabilities` now ALSO walks `apps/*` by default
+ * (configurable via the second arg `{monorepo_globs}`) and OR-merges
+ * each match's `package.json` capabilities with the root. The default
+ * `['apps/*']` matches the canonical Aperant monorepo layout; adopters
+ * whose monorepo lives elsewhere (e.g. `packages/apps/*`) pass a
+ * custom `monorepo_globs`. Setting `monorepo_globs: []` disables the
+ * walk entirely (root-only escape hatch).
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+/**
+ * @typedef {Object} RuntimeCapabilities
+ * @property {boolean} is_electron
+ * @property {boolean} is_tauri
+ * @property {boolean} is_nextjs
+ * @property {boolean} is_nuxt
+ * @property {boolean} is_web_frontend
+ * @property {boolean} is_expo
+ * @property {boolean} is_react_native
+ * @property {boolean} has_node
+ */
+
+/** A capability record with every flag defaulted to false. */
+function emptyCapabilities() {
+	return {
+		is_electron: false,
+		is_tauri: false,
+		is_nextjs: false,
+		is_nuxt: false,
+		is_web_frontend: false,
+		is_expo: false,
+		is_react_native: false,
+		has_node: false,
+	}
+}
+
+/**
+ * Detect runtime capabilities from a parsed package.json object.
+ *
+ * @param {Record<string, unknown> | null} packageJson
+ * @returns {RuntimeCapabilities}
+ */
+export function detectFromPackageJson(packageJson) {
+	const capabilities = emptyCapabilities()
+	if (packageJson === null || typeof packageJson !== 'object') return capabilities
+
+	const allDeps = {
+		...(packageJson.dependencies ?? {}) /** @type {Record<string,string>} */,
+		...(packageJson.devDependencies ?? {}) /** @type {Record<string,string>} */,
+	}
+	const deps = new Set(Object.keys(allDeps).map((k) => k.toLowerCase()))
+
+	if (deps.has('electron') || [...deps].some((d) => d.startsWith('@electron'))) {
+		capabilities.is_electron = true
+	}
+	if (deps.has('@tauri-apps/api') || deps.has('tauri')) {
+		capabilities.is_tauri = true
+	}
+	if (deps.has('expo')) capabilities.is_expo = true
+	if (deps.has('react-native')) capabilities.is_react_native = true
+
+	// Web frontends — react/vue/svelte/angular/solid → frontend. BUT: an
+	// Electron app commonly bundles React as its renderer; in that case the
+	// runtime is "electron", not "web_frontend". Electron + react-native +
+	// expo + tauri all win over the web flag.
+	const isNativeContainer =
+		capabilities.is_electron ||
+		capabilities.is_tauri ||
+		capabilities.is_react_native ||
+		capabilities.is_expo
+	const webFrameworks = ['react', 'vue', 'svelte', 'angular', 'solid']
+	if (!isNativeContainer && webFrameworks.some((f) => deps.has(f))) {
+		capabilities.is_web_frontend = true
+	}
+
+	if (deps.has('next')) {
+		capabilities.is_nextjs = true
+		capabilities.is_web_frontend = true
+	}
+	if (deps.has('nuxt')) {
+		capabilities.is_nuxt = true
+		capabilities.is_web_frontend = true
+	}
+	if (deps.has('vite') && !isNativeContainer) {
+		capabilities.is_web_frontend = true
+	}
+
+	// Node-ish? Anything with a package.json + an entry point counts.
+	if (typeof packageJson.main === 'string' || typeof packageJson.module === 'string') {
+		capabilities.has_node = true
+	}
+	if (!capabilities.has_node && packageJson.scripts && typeof packageJson.scripts === 'object') {
+		capabilities.has_node = true
+	}
+
+	return capabilities
+}
+
+/**
+ * Load and detect capabilities from a project directory's package.json.
+ * v0.8.6 — also walks `monorepo_globs` (default `['apps/*']`) and
+ * OR-merges each match's capabilities with the root.
+ *
+ * @param {string} projectDir
+ * @param {{monorepo_globs?: string[]}} [opts]
+ * @returns {RuntimeCapabilities}
+ */
+export function loadRuntimeCapabilities(projectDir, opts) {
+	const root = resolve(projectDir)
+	const rootPkgPath = join(root, 'package.json')
+	let rootCaps = emptyCapabilities()
+	if (existsSync(rootPkgPath)) {
+		try {
+			rootCaps = detectFromPackageJson(JSON.parse(readFileSync(rootPkgPath, 'utf-8')))
+		} catch {
+			/* fall through with empty caps */
+		}
+	}
+
+	// Default to the canonical Aperant monorepo layout. Passing `[]`
+	// disables the walk entirely (root-only escape hatch per spec ID-05).
+	const globs = opts && Array.isArray(opts.monorepo_globs) ? opts.monorepo_globs : ['apps/*']
+	if (globs.length === 0) return rootCaps
+
+	let merged = rootCaps
+	for (const glob of globs) {
+		const matches = expandSimpleGlob(root, glob)
+		for (const dir of matches) {
+			const childPkgPath = join(dir, 'package.json')
+			if (!existsSync(childPkgPath)) continue
+			try {
+				const childCaps = detectFromPackageJson(JSON.parse(readFileSync(childPkgPath, 'utf-8')))
+				merged = orMergeCapabilities(merged, childCaps)
+			} catch {
+				/* skip malformed package.json */
+			}
+		}
+	}
+	return merged
+}
+
+/**
+ * Expand a simple `prefix/*` glob against the root. Supports ONLY the
+ * `<dir>/*` shape (matches each direct subdirectory of `<dir>`). Other
+ * glob syntax is intentionally rejected — v1 keeps the dep surface
+ * small. Fails closed on malformed patterns (returns []).
+ *
+ * @param {string} root
+ * @param {string} glob
+ * @returns {string[]}
+ */
+function expandSimpleGlob(root, glob) {
+	if (typeof glob !== 'string' || !glob.endsWith('/*')) return []
+	const prefix = glob.slice(0, -2)
+	if (prefix.length === 0 || prefix.includes('*')) return []
+	const dir = join(root, prefix)
+	if (!existsSync(dir)) return []
+	let entries
+	try {
+		entries = readdirSync(dir)
+	} catch {
+		return []
+	}
+	const matches = []
+	for (const name of entries) {
+		const sub = join(dir, name)
+		try {
+			if (statSync(sub).isDirectory()) matches.push(sub)
+		} catch {
+			/* skip unreadable entries */
+		}
+	}
+	return matches
+}
+
+/**
+ * Boolean OR-merge of two capability records. Any flag true in either
+ * input is true in the output. The "Electron wins over web" rule from
+ * `detectFromPackageJson` is preserved when this is called repeatedly —
+ * each child's flags are honest about that child's own shape, and the
+ * OR-merge just unions them.
+ *
+ * @param {RuntimeCapabilities} a
+ * @param {RuntimeCapabilities} b
+ * @returns {RuntimeCapabilities}
+ */
+function orMergeCapabilities(a, b) {
+	return {
+		is_electron: a.is_electron || b.is_electron,
+		is_tauri: a.is_tauri || b.is_tauri,
+		is_nextjs: a.is_nextjs || b.is_nextjs,
+		is_nuxt: a.is_nuxt || b.is_nuxt,
+		is_web_frontend: a.is_web_frontend || b.is_web_frontend,
+		is_expo: a.is_expo || b.is_expo,
+		is_react_native: a.is_react_native || b.is_react_native,
+		has_node: a.has_node || b.has_node,
+	}
+}

package/src/cli/verify-proof/audit.mjs

@@ -12,21 +12,14 @@
  * lines but no line is ever overwritten.
  */
 
-import { appendFileSync, mkdirSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
+import { appendJsonl } from '../util/atomic-write.mjs'
+import { dailyEventsPath } from '../util/events-path.mjs'
 
-/**
- * Compute today's events filename relative to projectDir.
- * @param {string} projectDir
- * @param {Date} [now]
- * @returns {string}
- */
-export function dailyEventsPath(projectDir, now = new Date()) {
-	const yyyy = now.getUTCFullYear()
-	const mm = String(now.getUTCMonth() + 1).padStart(2, '0')
-	const dd = String(now.getUTCDate()).padStart(2, '0')
-	return join(resolve(projectDir), '.aperant/events', `${yyyy}-${mm}-${dd}.jsonl`)
-}
+// dailyEventsPath now lives in util/events-path.mjs (so install/ can share it
+// without crossing into verify-proof/). Re-exported here byte-for-byte so
+// every existing `import { dailyEventsPath } from '../verify-proof/audit.mjs'`
+// call site keeps working.
+export { dailyEventsPath }
 
 /**
  * Append a driver-invocation audit line.
@@ -45,11 +38,12 @@ export function dailyEventsPath(projectDir, now = new Date()) {
  */
 export function appendDriverEvent(projectDir, entry) {
 	const path = dailyEventsPath(projectDir)
-	mkdirSync(dirname(path), { recursive: true })
-	const line = JSON.stringify({
+	// Single canonical jsonl-append primitive for the event log (appendJsonl
+	// creates parent dirs, fsyncs, and locks on Windows). Keeps every writer to
+	// .aperant/events/{date}.jsonl on the same atomic path.
+	appendJsonl(path, {
 		ts: new Date().toISOString(),
 		kind: 'driver_invocation',
 		...entry,
 	})
-	appendFileSync(path, line + '\n', 'utf-8')
 }