@aperant/framework 0.8.7 → 0.9.0

package/src/cli/commands/init.mjs

@@ -59,7 +59,7 @@ import { detectAgentRuntime } from '../util/agent-runtime.mjs'
 import { buildAptSection } from '../util/aperant-section.mjs'
 import { atomicWriteJson } from '../util/atomic-write.mjs'
 import { aperantBanner } from '../util/banner.mjs'
-import { copyDirRecursive, injectInstructionFile } from '../util/copy.mjs'
+import { checkInstructionFile, copyDirRecursive, injectInstructionFile } from '../util/copy.mjs'
 import { withFileLock } from '../util/fs-lock.mjs'
 import { emitInitConfigHint } from '../util/init-hints.mjs'
 import { err, exitWith, ok, rawText } from '../util/result.mjs'
@@ -1459,6 +1459,69 @@ async function renderOutro(answers, results, version, kernelResult) {
 	clack.outro(`Installed ${fileCount} files · v${version} · ${xverifyCopy}`)
 }
 
+/**
+ * Resolve the deduplicated set of root instruction-file paths the selected
+ * runtimes read. Each chosen runtime contributes its `nativeInstructionFile`
+ * (claude→CLAUDE.md, codex/opencode→AGENTS.md, gemini→GEMINI.md); runtimes
+ * mapped to `null` install to their own surface and contribute nothing.
+ * Filenames are deduplicated (codex + opencode both map to AGENTS.md → one
+ * target).
+ *
+ * Resolution rules:
+ *   - Multiple distinct targets (e.g. `--claude --codex`): write all of them
+ *     verbatim — that is the whole point of the fix (AC1, AC2, AC5).
+ *   - Exactly one resolved target that does NOT exist AND it is CLAUDE.md, but
+ *     AGENTS.md already exists (the `--claude` with a pre-seeded AGENTS.md and
+ *     no CLAUDE.md case, Risk 4 / AC9): redirect to the existing AGENTS.md
+ *     rather than creating an orphan CLAUDE.md. This is safe ONLY for the
+ *     claude runtime because native Claude Code reads AGENTS.md as well as
+ *     CLAUDE.md. The redirect is NOT applied for gemini (reads only GEMINI.md)
+ *     or codex/opencode (read only AGENTS.md) — redirecting those to an
+ *     unrelated existing file would reintroduce the very visibility gap this
+ *     fix closes, so their absent target is simply created.
+ *   - Zero resolved targets (no selected runtime maps to an instruction file):
+ *     fall back to the legacy heuristic — CLAUDE.md if present, else AGENTS.md
+ *     if present, else a new CLAUDE.md.
+ *
+ * @param {string[]} chosenIds
+ * @param {string} targetDir
+ * @returns {string[]} absolute instruction-file paths, deduplicated
+ */
+function resolveInstructionTargets(chosenIds, targetDir) {
+	const filenames = []
+	for (const id of chosenIds) {
+		const runtime = getRuntime(id)
+		const file = runtime?.nativeInstructionFile
+		if (file && !filenames.includes(file)) filenames.push(file)
+	}
+	const claudeMdPath = join(targetDir, 'CLAUDE.md')
+	const agentsMdPath = join(targetDir, 'AGENTS.md')
+	const resolved = filenames.map((name) => join(targetDir, name))
+
+	if (resolved.length === 0) {
+		// No selected runtime maps to an instruction file — legacy heuristic.
+		if (existsSync(claudeMdPath)) return [claudeMdPath]
+		if (existsSync(agentsMdPath)) return [agentsMdPath]
+		return [claudeMdPath]
+	}
+
+	if (resolved.length === 1 && !existsSync(resolved[0])) {
+		// Single registry target that doesn't exist yet. The ONLY safe redirect
+		// is claude→AGENTS.md (Risk 4 / AC9): native Claude Code reads AGENTS.md
+		// too, so when CLAUDE.md is absent but AGENTS.md exists (e.g. a prior
+		// codex install), writing AGENTS.md still serves claude and avoids an
+		// orphan CLAUDE.md. gemini/codex/opencode read only their own native
+		// file — redirecting them to an unrelated existing file would hide the
+		// catalog from their CLI, so we just create their target.
+		if (resolved[0] === claudeMdPath && existsSync(agentsMdPath)) return [agentsMdPath]
+		return resolved
+	}
+
+	// One or more registry targets, at least one exists OR multiple distinct
+	// targets — write the registry-resolved set verbatim.
+	return resolved
+}
+
 /**
  * Synchronous tail of init — runs after the runtime-install promise
  * resolves. Performs all .aperant/ + Claude-hook + remote-warning work
@@ -1652,15 +1715,19 @@ function finishInit(
 		copyDirRecursive(installedContextSrc, join(aperantDir, 'context', 'installed'))
 	}
 
-	const claudeMdPath = join(targetDir, 'CLAUDE.md')
-	const agentsMdPath = join(targetDir, 'AGENTS.md')
-	let instructionFile
-	if (existsSync(claudeMdPath)) instructionFile = claudeMdPath
-	else if (existsSync(agentsMdPath)) instructionFile = agentsMdPath
-	else instructionFile = claudeMdPath
+	// Resolve every distinct instruction file the selected runtimes read, then
+	// preflight ALL of them before writing ANY — so a single foreign-row abort
+	// leaves no file partially written (US-03 / AC3). Each chosen runtime maps
+	// to its `nativeInstructionFile` (claude→CLAUDE.md, codex/opencode→AGENTS.md,
+	// gemini→GEMINI.md); null-mapped runtimes install to their own surface and
+	// contribute no target. When the selected runtimes resolve to zero targets,
+	// or none of the resolved targets exist on disk, fall back to the legacy
+	// "pick the existing file" heuristic so e.g. `--claude` with a pre-seeded
+	// AGENTS.md (and no CLAUDE.md) still writes AGENTS.md (Risk 4 / AC9).
+	const instructionTargets = resolveInstructionTargets(chosenIds, targetDir)
 	// FRAMEWORK-BUG-023 — generate the section from discoverSkills before
 	// handing it to the writer. The writer also runs a foreign-row defensive
-	// check; if rows present in the file aren't in the generated set we
+	// check; if rows present in any file aren't in the generated set we
 	// signal exit-2 via the __earlyExit sentinel so cmdInit can route the
 	// envelope through exitWith() without writing a malformed install.
 	const aptSection = buildAptSection({
@@ -1668,11 +1735,59 @@ function finishInit(
 		targetDir,
 		cli: detectAgentRuntime(),
 	})
-	const injectionOutcome = injectInstructionFile(instructionFile, {
-		aptSection,
-		force: forceOverwriteCatalog,
+	// Preflight pass — check every target with the write-free helper; collect
+	// all aborting targets so the error lists every offender, not just the first.
+	const abortingTargets = []
+	for (const filePath of instructionTargets) {
+		const check = checkInstructionFile(filePath, { aptSection, force: forceOverwriteCatalog })
+		if (check.status === 'aborted-foreign-rows') {
+			abortingTargets.push({ path: basename(filePath), foreignRowIds: check.foreignRowIds })
+		}
+	}
+	if (abortingTargets.length > 0) {
+		const allForeignRowIds = [...new Set(abortingTargets.flatMap((t) => t.foreignRowIds))]
+		const fileList = abortingTargets.map((t) => t.path).join(', ')
+		return {
+			__earlyExit: exitWith(
+				{
+					ok: false,
+					status: 'error',
+					command: 'init',
+					code: 'instruction-file.foreign-rows',
+					message:
+						`${fileList} contains skill rows not present in the installed framework: ` +
+						`${allForeignRowIds.join(', ')}. ` +
+						'Re-run with --force-overwrite-catalog to regenerate anyway, or remove the foreign rows manually.',
+					foreignRowIds: allForeignRowIds,
+					instructionFile: { path: abortingTargets[0].path, status: 'aborted-foreign-rows' },
+					instructionFiles: abortingTargets.map((t) => ({
+						path: t.path,
+						status: 'aborted-foreign-rows',
+					})),
+				},
+				2,
+			),
+		}
+	}
+	// Write pass — no target aborted in the preflight, so write all.
+	const instructionFiles = instructionTargets.map((filePath) => {
+		const outcome = injectInstructionFile(filePath, {
+			aptSection,
+			force: forceOverwriteCatalog,
+		})
+		return {
+			path: basename(filePath),
+			status: outcome.status,
+			foreignRowIds: outcome.foreignRowIds,
+		}
 	})
-	if (injectionOutcome.status === 'aborted-foreign-rows') {
+	// TOCTOU guard: if a file gained foreign rows BETWEEN the preflight check and
+	// the write (e.g. another process wrote to it), surface the same error envelope
+	// the preflight uses rather than silently accepting partial writes.
+	const writtenAborts = instructionFiles.filter((f) => f.status === 'aborted-foreign-rows')
+	if (writtenAborts.length > 0) {
+		const allForeignRowIds = [...new Set(writtenAborts.flatMap((f) => f.foreignRowIds ?? []))]
+		const fileList = writtenAborts.map((f) => f.path).join(', ')
 		return {
 			__earlyExit: exitWith(
 				{
@@ -1681,17 +1796,22 @@ function finishInit(
 					command: 'init',
 					code: 'instruction-file.foreign-rows',
 					message:
-						`${basename(instructionFile)} contains skill rows not present in the installed framework: ` +
-						`${injectionOutcome.foreignRowIds.join(', ')}. ` +
+						`${fileList} contains skill rows not present in the installed framework: ` +
+						`${allForeignRowIds.join(', ')}. ` +
 						'Re-run with --force-overwrite-catalog to regenerate anyway, or remove the foreign rows manually.',
-					foreignRowIds: injectionOutcome.foreignRowIds,
-					instructionFile: basename(instructionFile),
+					foreignRowIds: allForeignRowIds,
+					instructionFile: { path: writtenAborts[0].path, status: 'aborted-foreign-rows' },
+					instructionFiles: writtenAborts.map((f) => ({
+						path: f.path,
+						status: 'aborted-foreign-rows',
+					})),
 				},
 				2,
 			),
 		}
 	}
-	const injectionResult = injectionOutcome.status
+	// Primary entry drives the backwards-compat singular alias + structure key.
+	const primaryInstructionFile = instructionFiles[0]
 
 	const installedClaude = chosenIds.includes('claude') || existsSync(join(targetDir, '.claude'))
 	const precompactResult = installedClaude
@@ -1730,9 +1850,11 @@ function finishInit(
 		'.aperant/events/': 'event log (git-ignored)',
 		'.aperant/prompts/': 'agent prompt templates',
 		'.aperant/install/last-install.json': 'cross-runtime install summary',
-		[basename(instructionFile)]: `APT section ${injectionResult}`,
 		'.claude/settings.local.json': `PreCompact hook ${precompactResult}; SessionStart hook ${sessionStartResult}`,
 	}
+	for (const f of instructionFiles) {
+		structure[f.path] = `APT section ${f.status}`
+	}
 	if (kernelResult) {
 		structure['.aperant/deps/'] =
 			kernelResult.status === 'installed'
@@ -1772,7 +1894,10 @@ function finishInit(
 		framework_version: version,
 		configCreated,
 		configMigrated,
-		instructionFile: { path: basename(instructionFile), status: injectionResult },
+		// Plural contract (ID-03): one entry per instruction file written.
+		// `instructionFile` (singular) is a backwards-compat alias = first entry.
+		instructionFiles,
+		instructionFile: primaryInstructionFile,
 		stateCreated,
 		seedsCreated,
 		publicRemoteWarning,

package/src/cli/commands/toolchain-detect.mjs

@@ -274,6 +274,32 @@ export function cmdToolchainDetect(projectDir, extraArgs = []) {
 	}
 	const scripts = packageJson?.scripts ?? {}
 
+	// FRAMEWORK-BUG-006 (Part B) — turbo cache-bypass detection.
+	// A turbo-backed verify command can replay a STALE CACHE HIT and report
+	// PASS while a broken import sits on disk (sighted on PR #244). When the
+	// project is turbo-backed we additionally emit a `no_cache_command`
+	// variant that appends turbo's `--force` flag so pr-review (and any
+	// consumer) can run a cache-bypassing verification. This is ADDITIVE —
+	// the existing `command` strings are never altered (ID-03).
+	const hasTurboConfig = existsSync(join(scopePath, 'turbo.json'))
+	// A package script "resolves through turbo" when its script body invokes
+	// the turbo CLI (e.g. "turbo run typecheck"). package.json scripts are
+	// hand-authored and tiny; a substring match on the `turbo` token is
+	// sufficient and avoids parsing shell.
+	function scriptIsTurboBacked(scriptName) {
+		const body = scripts[scriptName]
+		return typeof body === 'string' && /\bturbo\b/.test(body)
+	}
+	// Append --force to a turbo-backed package script so it reaches the
+	// underlying `turbo run …`. Only used when the command is known to be
+	// turbo-backed, so --force is always meaningful here. npm does NOT
+	// forward trailing args to the script unless they follow a `--`
+	// separator (`npm run typecheck --force` swallows --force as an npm flag),
+	// so insert `--` for npm. pnpm/yarn/bun forward trailing args directly.
+	function withTurboForce(command) {
+		return pm === 'npm' ? `${command} -- --force` : `${command} --force`
+	}
+
 	// Read pyproject.toml as string if present
 	let pyproject = null
 	const pyprojectPath = join(scopePath, 'pyproject.toml')
@@ -331,6 +357,19 @@ export function cmdToolchainDetect(projectDir, extraArgs = []) {
 	} else if (pyproject && pyproject.includes('[tool.mypy]')) {
 		typecheck = { tool: 'mypy', command: 'mypy .' }
 	}
+	// Additive turbo cache-bypass variant (FRAMEWORK-BUG-006). When the
+	// project is turbo-backed AND has a turbo-backed typecheck script, the
+	// plain command (often `tsc --noEmit` when tsconfig.json wins above) can
+	// be masked by a replayed turbo cache PASS. The no_cache_command routes
+	// through the turbo-backed script with `--force` so pr-review's post-fix
+	// typecheck cannot be fooled by a stale cache.
+	if (typecheck && hasTurboConfig) {
+		if (scriptIsTurboBacked('typecheck')) {
+			typecheck.no_cache_command = withTurboForce(`${pmRun} typecheck`)
+		} else if (scriptIsTurboBacked('type-check')) {
+			typecheck.no_cache_command = withTurboForce(`${pmRun} type-check`)
+		}
+	}
 
 	// --- Test ---
 	let test = null
@@ -364,6 +403,11 @@ export function cmdToolchainDetect(projectDir, extraArgs = []) {
 	if (!test && scripts.test) {
 		test = { tool: 'package-script', command: `${pmRun} test` }
 	}
+	// Additive turbo cache-bypass variant for tests (FRAMEWORK-BUG-006), same
+	// rationale as typecheck above — only when turbo backs the test script.
+	if (test && hasTurboConfig && scriptIsTurboBacked('test')) {
+		test.no_cache_command = withTurboForce(`${pmRun} test`)
+	}
 
 	// --- Build ---
 	let build = null