@aperant/framework 0.15.0 → 0.17.0

package/src/cli/dispatch.mjs

@@ -86,6 +86,7 @@ import { cmdRiskCheck } from './commands/risk-check.mjs'
 import { cmdRoadmap } from './commands/roadmap.mjs'
 import { cmdRoute } from './commands/route.mjs'
 import { cmdSeed } from './commands/seed.mjs'
+import { cmdSparResolvePartner } from './commands/spar-resolve-partner.mjs'
 import { cmdStandards } from './commands/standards.mjs'
 import { cmdConfig, cmdState, cmdStateArtifacts, cmdStateUpdate } from './commands/state.mjs'
 import { cmdStatusline } from './commands/statusline.mjs'
@@ -285,6 +286,7 @@ export const DISPATCH = {
 	'author-skill': (args) => wrap(cmdAuthorSkill)(args[1], args.slice(2)),
 	'toolchain-detect': (args) => wrap(cmdToolchainDetect)(args[1], args.slice(2)),
 	'host-detect': () => wrap(cmdHostDetect)(),
+	'spar-resolve-partner': (args) => wrap(cmdSparResolvePartner)(args.slice(1)),
 	reconcile: (args) => wrap(cmdReconcile)(args[1], args.slice(2)),
 	standards: (args) => wrap(cmdStandards)(args[1], args.slice(2)),
 	'precompact-hook': (args) => wrap(cmdPrecompactHook)(args[1]),

package/src/cli/help.mjs

@@ -110,6 +110,7 @@ Commands:
   toolchain-detect <project-dir>          Detect project toolchain (linter, formatter, typecheck, test, build)
   health-check <project-dir>             Detect dirty state, stale locks, orphaned events, version drift
   host-detect                            Detect which AI CLI is running and its capability matrix
+  spar-resolve-partner [--partner codex|claude|gemini]   apt:spar live partner-model resolution — reads ~/.codex/config.toml LIVE (fail-closed, no baked default); codex returns {available,model,source,reason} + a transport-walk preference, claude/gemini return self_resolving
   reconcile <project-dir>               Resolve orchestration preferences against host capabilities
 
   migrate-pr-reviews <project-dir>       Migrate legacy .aperant/reviews/ → .aperant/pr-reviews/pr-{N}/rounds/{R}/ (idempotent)

package/src/cli/host/codex-config.mjs

@@ -0,0 +1,165 @@
+/**
+ * host/codex-config.mjs — live codex model resolution for `apt:spar` (Decision B + C).
+ *
+ * Aperant holds ZERO model names. The only source of truth for the codex
+ * partner's model is the user's live `~/.codex/config.toml`, read at invocation
+ * time with NO fallback default — mirroring the app's "Model selection —
+ * resolver-only, provider-is-output, LIVE" rule.
+ *
+ * Two exports:
+ *   - `parseTopLevelCodexModel(tomlText)` — a deterministic top-level TOML
+ *     `model = "<value>"` line parser (ID-04: top-level only; `[profiles.*]`
+ *     sections are inactive without `--profile`, which spar never passes).
+ *   - `resolveCodexSparModel({ home, existsSync, readFileSync })` — reads
+ *     `<home>/.codex/config.toml` LIVE each call and returns a fail-closed
+ *     `{ available, model, source, reason }` envelope. NEVER a baked constant.
+ *
+ * Parser hardening (plan-gate spar refinement #1). The bias rule is
+ * fail-closed: when a value is ambiguous, return `reason: 'unparseable'` rather
+ * than a wrong or truncated model. A too-strict parse that loses the MCP rung
+ * (falling through to the self-resolving plugin/CLI rungs) is acceptable; a
+ * too-loose parse that passes a wrong model is a bug.
+ */
+
+import { join } from 'node:path'
+
+/** Human-facing source label the SKILL + envelope reference. */
+export const CODEX_CONFIG_SOURCE = '~/.codex/config.toml'
+
+/**
+ * @typedef {Object} ParsedCodexModel
+ * @property {string|null} model — the resolved top-level model, or null.
+ * @property {null|'no_model_key'|'unparseable'} reason — null when a model
+ *   resolved; a machine reason otherwise.
+ */
+
+/**
+ * Parse the FIRST top-level `model = "<value>"` assignment from codex
+ * `config.toml` text. Scans line-by-line, stops at the first `[section]`
+ * header (top-level scope ends there), skips comment lines, and resolves the
+ * first top-level `model` key.
+ *
+ * Handles (refinement #1): a leading UTF-8 BOM, an inline `# comment` after the
+ * value, a no-space `model="x"` assignment, single-quoted TOML literal strings,
+ * and commented-out `#model = "x"` keys (skipped). A malformed / unterminated /
+ * escaped-quote value returns `reason: 'unparseable'` — never a truncated
+ * string. The first top-level `model` line is decisive: if it is malformed the
+ * parser returns `unparseable` rather than scanning for a later valid line
+ * (TOML forbids duplicate keys, and a later-line search would be too loose).
+ *
+ * @param {string} tomlText
+ * @returns {ParsedCodexModel}
+ */
+export function parseTopLevelCodexModel(tomlText) {
+	if (typeof tomlText !== 'string') return { model: null, reason: 'unparseable' }
+
+	// Strip a leading UTF-8 BOM so `model = "x"` still resolves.
+	let text = tomlText
+	if (text.charCodeAt(0) === 0xfeff) text = text.slice(1)
+
+	const lines = text.split(/\r?\n/)
+	for (const rawLine of lines) {
+		const line = rawLine.trimStart()
+		// A `[section]` (or `[[array.of.tables]]`) header ends the top-level
+		// scope — stop scanning; a model below this point is profile-scoped.
+		if (line.startsWith('[')) break
+		// Comment lines (incl. a commented-out `#model = "x"`) are skipped.
+		if (line.startsWith('#')) continue
+		// Top-level `model` assignment? The key must be EXACTLY `model` —
+		// `\s*=` rejects `model_provider`, `models`, `mcp_model`, etc.
+		const assign = line.match(/^model\s*=\s*(.*)$/)
+		if (!assign) continue
+		// First top-level model line is decisive (fail-closed on malformed).
+		return parseQuotedValue(assign[1])
+	}
+	return { model: null, reason: 'no_model_key' }
+}
+
+/**
+ * Parse a quoted TOML string value (the RHS of `model =`). Accepts a
+ * double-quoted basic string or a single-quoted literal string, each optionally
+ * followed by whitespace and/or an inline `# comment`. Any other shape
+ * (unquoted, unterminated, escaped, empty, or trailing non-comment junk) is
+ * fail-closed `unparseable`.
+ *
+ * @param {string} value — the text after `model\s*=\s*`.
+ * @returns {ParsedCodexModel}
+ */
+function parseQuotedValue(value) {
+	const first = value[0]
+	if (first === '"') {
+		const m = value.match(/^"([^"\n]*)"(.*)$/)
+		if (!m) return { model: null, reason: 'unparseable' } // unterminated
+		const inner = m[1]
+		// A backslash means TOML escapes are in play — do NOT attempt to
+		// unescape; fail closed rather than risk a wrong/truncated model.
+		if (inner.includes('\\')) return { model: null, reason: 'unparseable' }
+		if (!isOnlyTrailingComment(m[2])) return { model: null, reason: 'unparseable' }
+		if (inner.length === 0) return { model: null, reason: 'unparseable' }
+		return { model: inner, reason: null }
+	}
+	if (first === "'") {
+		// TOML literal strings carry no escapes.
+		const m = value.match(/^'([^'\n]*)'(.*)$/)
+		if (!m) return { model: null, reason: 'unparseable' }
+		const inner = m[1]
+		if (!isOnlyTrailingComment(m[2])) return { model: null, reason: 'unparseable' }
+		if (inner.length === 0) return { model: null, reason: 'unparseable' }
+		return { model: inner, reason: null }
+	}
+	// Unquoted / bare value — codex `model` is always a quoted string; bias
+	// fail-closed so a malformed line never yields a wrong model.
+	return { model: null, reason: 'unparseable' }
+}
+
+/**
+ * The text after a closing quote must be empty, whitespace, or an inline
+ * `# comment`. Anything else is malformed → fail closed.
+ *
+ * @param {string} rest
+ * @returns {boolean}
+ */
+function isOnlyTrailingComment(rest) {
+	const t = rest.trimStart()
+	return t === '' || t.startsWith('#')
+}
+
+/**
+ * @typedef {Object} CodexSparModelResolution
+ * @property {boolean} available — true iff a live top-level model resolved.
+ * @property {string|null} model — the resolved model, or null when unavailable.
+ * @property {string} source — the config source label (`~/.codex/config.toml`).
+ * @property {null|'config_missing'|'no_model_key'|'unparseable'} reason
+ */
+
+/**
+ * Read `<home>/.codex/config.toml` LIVE and resolve the top-level model.
+ * Fail-closed (Decision C / ID-03): a missing file, a missing top-level `model`
+ * key, or an unparseable value returns `available: false` with a machine reason
+ * and `model: null`. It NEVER substitutes a default. There is no module-level
+ * cached value — the file is re-read on every call.
+ *
+ * `existsSync` / `readFileSync` are injected so tests stay hermetic (no real
+ * `$HOME` read).
+ *
+ * @param {{ home: string, existsSync: (p: string) => boolean, readFileSync: (p: string, enc: string) => string }} deps
+ * @returns {CodexSparModelResolution}
+ */
+export function resolveCodexSparModel({ home, existsSync, readFileSync }) {
+	const source = CODEX_CONFIG_SOURCE
+	const configPath = join(home, '.codex', 'config.toml')
+	if (!existsSync(configPath)) {
+		return { available: false, model: null, source, reason: 'config_missing' }
+	}
+	let text
+	try {
+		text = readFileSync(configPath, 'utf-8')
+	} catch {
+		return { available: false, model: null, source, reason: 'config_missing' }
+	}
+	const { model, reason } = parseTopLevelCodexModel(text)
+	if (model) {
+		return { available: true, model, source, reason: null }
+	}
+	return { available: false, model: null, source, reason: reason ?? 'unparseable' }
+}

package/src/cli/install/legacy-paths.mjs

@@ -181,6 +181,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'agents/apt-improver.md',
 			'agents/apt-planner.md',
 			'agents/apt-pr-review-codebase-fit.md',
+			'agents/apt-pr-review-crossplatform.md',
 			'agents/apt-pr-review-fixer.md',
 			'agents/apt-pr-review-i18n.md',
 			'agents/apt-pr-review-logic.md',

package/src/cli/wfrun/run.mjs

@@ -66,6 +66,7 @@ const TOOL_COMMAND_ALLOWLIST = new Set([
 	'audit',
 	'toolchain-detect',
 	'host-detect',
+	'spar-resolve-partner',
 	'reconcile',
 	'team',
 	'active',