@aperant/framework 0.8.6 → 0.9.0

package/src/cli/install/transforms/codex.mjs

@@ -14,6 +14,13 @@
  *     against installRoot `.agents` to land at `.agents/skills/<folder>/SKILL.md`).
  *     Markdown agents are NOT a Codex surface (custom-agents are TOML
  *     under `.codex/agents/`); only skills are emitted.
+ *   - agent inlining: Codex has no markdown agent-spawn surface, so a skill
+ *     declaring `spawns_agent: true` + `agent_name: X` would, on Claude, spawn
+ *     the X agent (whose prompt lives in agents/X.md). On Codex that file is
+ *     never installed and the spawn directive is stripped by the whitelist —
+ *     leaving the skill referencing a non-existent agent. To keep Codex at
+ *     parity, the referenced agent's body is appended inline to the skill body
+ *     so the model has the full methodology even without a spawn primitive.
  */
 
 import { basename, dirname } from 'node:path'
@@ -36,16 +43,33 @@ const KEEP = ['name', 'description']
  * @param {import('../pipeline.mjs').TransformInput} input
  * @returns {import('../pipeline.mjs').TransformOutput[]}
  */
-export function transform({ canonicalContent, canonicalRelPath, version, fileType }) {
+export function transform({
+	canonicalContent,
+	canonicalRelPath,
+	version,
+	fileType,
+	agentContentByName = {},
+}) {
 	const subbed = substituteVersion(canonicalContent, version)
 	const parsed = parseFrontmatter(subbed)
 	let payload
 	if (parsed.hasFrontmatter && parsed.fm) {
+		// Read the spawn directive BEFORE the whitelist strips it. On Codex
+		// there's no agent-spawn surface, so we inline the agent body instead.
+		const spawnsAgent = parsed.fm.spawns_agent === true
+		const agentName =
+			typeof parsed.fm.agent_name === 'string' && parsed.fm.agent_name.length > 0
+				? parsed.fm.agent_name
+				: null
 		// Whitelist filter: drop every frontmatter key NOT in KEEP.
 		for (const k of Object.keys(parsed.fm)) {
 			if (!KEEP.includes(k)) delete parsed.fm[k]
 		}
-		const wrappedBody = `<codex_agent_role>\n${parsed.body}\n</codex_agent_role>\n`
+		let body = parsed.body
+		if (spawnsAgent && agentName && agentContentByName[agentName]) {
+			body = `${body}\n\n${inlineAgentSection(agentName, agentContentByName[agentName], version)}`
+		}
+		const wrappedBody = `<codex_agent_role>\n${body}\n</codex_agent_role>\n`
 		payload = serializeFrontmatter({ ...parsed, body: wrappedBody })
 	} else {
 		payload = `<codex_agent_role>\n${subbed}\n</codex_agent_role>\n`
@@ -63,3 +87,28 @@ export function transform({ canonicalContent, canonicalRelPath, version, fileTyp
 	// another dead surface. Drop the agent branch entirely.
 	return []
 }
+
+/**
+ * Build the inlined-agent section appended to a Codex skill body. Strips the
+ * agent file's own frontmatter (Codex skills carry a single frontmatter block)
+ * and version-substitutes the body. The fenced header makes it unambiguous to
+ * the model that this is the methodology it should execute directly — there is
+ * no separate agent to spawn on Codex.
+ *
+ * @param {string} agentName
+ * @param {string} agentContent  raw canonical agent file (with frontmatter + {{APT_VERSION}})
+ * @param {string} version
+ * @returns {string}
+ */
+function inlineAgentSection(agentName, agentContent, version) {
+	const agentBody = parseFrontmatter(substituteVersion(agentContent, version)).body.trim()
+	return [
+		`## Inlined agent: ${agentName}`,
+		'',
+		`Codex has no separate agent-spawn surface. Where this skill says to spawn`,
+		`the \`${agentName}\` agent, execute the methodology below directly — you ARE`,
+		`that agent for this task.`,
+		'',
+		agentBody,
+	].join('\n')
+}

package/src/cli/install/version-header.mjs

@@ -99,7 +99,13 @@ export function inspectManifestFiles(manifest, installRoot, opts = {}) {
 			continue
 		}
 		const declared = parseVersionHeader(buf.toString('utf-8'))
-		if (declared === null && /\.(md|js|mjs|sh)$/.test(entry.path)) {
+		// `headerless` entries are files whose runtime transform legitimately
+		// strips the apt-skill-version header (e.g. Codex whitelists frontmatter
+		// to {name, description} and rejects unknown keys). For those, the
+		// installedHash check above is the sole drift signal — requiring a header
+		// would false-positive every install. The flag is recorded at install
+		// time by the pipeline from the post-transform content.
+		if (declared === null && !entry.headerless && /\.(md|js|mjs|sh)$/.test(entry.path)) {
 			stale.push({ path: entry.path, reason: 'missing_header' })
 			continue
 		}

package/src/cli/util/aperant-section.mjs

@@ -22,6 +22,20 @@ import { discoverSkills } from '../route/skill-discover.mjs'
 
 const SECTION_START = '<!-- APT:framework-start -->'
 const SECTION_END = '<!-- APT:framework-end -->'
+
+/**
+ * Matches the full APT managed block (start marker through end marker,
+ * inclusive). Exported so callers in the same package can reference a
+ * single source rather than inlining duplicate regex literals.
+ *
+ * `APT_SECTION_RE`       — no trailing newline; used for in-place replace.
+ * `APT_SECTION_STRIP_RE` — includes optional trailing newline; used for
+ *                          strip operations that want to remove the newline
+ *                          the block was preceded/followed by.
+ */
+export const APT_SECTION_RE = /<!-- APT:framework-start -->[\s\S]*?<!-- APT:framework-end -->/
+export const APT_SECTION_STRIP_RE =
+	/<!-- APT:framework-start -->[\s\S]*?<!-- APT:framework-end -->\n?/
 const SECTION_HEADING = '## Aperant Framework'
 const APPENDIX_REL_PATH = ['templates', 'aperant-claude-md-appendix.md']
 

package/src/cli/util/copy.mjs

@@ -20,7 +20,21 @@ import {
 	writeFileSync,
 } from 'node:fs'
 import { join } from 'node:path'
-import { extractAptSectionRowIds } from './aperant-section.mjs'
+import { APT_SECTION_RE, extractAptSectionRowIds } from './aperant-section.mjs'
+
+/**
+ * Return the row IDs present in `existing` that are NOT present in
+ * `aptSection`. An empty array means no foreign rows (safe to overwrite).
+ *
+ * @param {string} existing   Current on-disk file contents.
+ * @param {string} aptSection Output of buildAptSection().
+ * @returns {string[]}
+ */
+function computeForeignRowIds(existing, aptSection) {
+	const existingIds = new Set(extractAptSectionRowIds(existing))
+	const generatedIds = new Set(extractAptSectionRowIds(aptSection))
+	return [...existingIds].filter((id) => !generatedIds.has(id))
+}
 
 export function copyDirRecursive(src, dest) {
 	mkdirSync(dest, { recursive: true })
@@ -35,6 +49,42 @@ export function copyDirRecursive(src, dest) {
 	}
 }
 
+/**
+ * Preflight-only sibling of `injectInstructionFile`. Runs the same
+ * foreign-row defensive check against `filePath` but NEVER writes — used by
+ * the multi-target init flow to check every instruction target up-front so a
+ * single aborting target leaves NO file partially written (US-03 / AC3).
+ *
+ * Returns the same status vocabulary as `injectInstructionFile` minus the
+ * write side-effect: `'created'` (file absent → would be appended-to),
+ * `'updated'` (markers present, no foreign rows → would be replaced),
+ * `'aborted-foreign-rows'` (markers present with rows not in the generated
+ * set → init must abort). `force` short-circuits the foreign-row gate exactly
+ * as the writer does.
+ *
+ * @param {string} filePath
+ * @param {Object} opts
+ * @param {string} opts.aptSection   Output of buildAptSection().
+ * @param {boolean} [opts.force=false]
+ *                                    Bypass the foreign-row check.
+ * @returns {{ status: 'created' | 'updated' | 'aborted-foreign-rows', foreignRowIds?: string[] }}
+ */
+export function checkInstructionFile(filePath, { aptSection, force = false }) {
+	const existing = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : ''
+
+	if (existing.includes('<!-- APT:framework-start -->')) {
+		if (!force) {
+			const foreignRowIds = computeForeignRowIds(existing, aptSection)
+			if (foreignRowIds.length > 0) {
+				return { status: 'aborted-foreign-rows', foreignRowIds }
+			}
+		}
+		return { status: 'updated' }
+	}
+
+	return { status: 'created' }
+}
+
 /**
  * Write the (already-generated) APT section into `filePath`. Creates the
  * file if missing; replaces the section in-place if the markers are
@@ -60,17 +110,12 @@ export function injectInstructionFile(filePath, { aptSection, force = false }) {
 
 	if (existing.includes('<!-- APT:framework-start -->')) {
 		if (!force) {
-			const existingIds = new Set(extractAptSectionRowIds(existing))
-			const generatedIds = new Set(extractAptSectionRowIds(aptSection))
-			const foreignRowIds = [...existingIds].filter((id) => !generatedIds.has(id))
+			const foreignRowIds = computeForeignRowIds(existing, aptSection)
 			if (foreignRowIds.length > 0) {
 				return { status: 'aborted-foreign-rows', written: false, foreignRowIds }
 			}
 		}
-		const updated = existing.replace(
-			/<!-- APT:framework-start -->[\s\S]*?<!-- APT:framework-end -->/,
-			aptSection,
-		)
+		const updated = existing.replace(APT_SECTION_RE, aptSection)
 		writeFileSync(filePath, updated, 'utf-8')
 		return { status: 'updated', written: true }
 	}

package/src/cli/verify-proof/idl/index.mjs

@@ -8,16 +8,54 @@
  * refactor of every callsite.
  *
  * If you add a verb, edit packages/framework/src/driver-sdk/idl.ts.
+ *
+ * Defense-in-depth (issue #248). `@aperant/framework/driver-sdk` resolves
+ * via the package `exports` map to `dist/driver-sdk/index.js`. A *static*
+ * `export … from '@aperant/framework/driver-sdk'` here made this barrel —
+ * and therefore the whole apt-tools CLI, since `dispatch.mjs` eagerly
+ * imports `driver-doctor.mjs` which imports this barrel — crash at
+ * module-resolution time with an opaque `ERR_MODULE_NOT_FOUND` when the
+ * dist was not built (e.g. a CI step that skipped `pnpm build`), before
+ * any command body could run. Resolving the registry via a *dynamic*
+ * `await import()` wrapped in try/catch keeps that dependency off the
+ * hard module-link path: dist present (tests, post-build CI, published
+ * tarball) → the REAL registry values are re-exported unchanged; dist
+ * absent → empty/no-op fallbacks let the CLI load (so commands that don't
+ * touch the IDL registry, like `route`, still run) instead of crashing.
  */
 
-export {
-	ASSERTION_VERBS,
-	ASYNC_VERBS,
-	EVIDENCE_VERBS,
-	IDL_VERB_ARGS,
-	IDL_VERB_NAMES,
-	INTERACTION_VERBS,
-	isVerbResult,
-	LIFECYCLE_VERBS,
-	validateVerbArgs,
-} from '@aperant/framework/driver-sdk'
+/** @type {typeof import('@aperant/framework/driver-sdk')} */
+let _sdk
+try {
+	_sdk = await import('@aperant/framework/driver-sdk')
+} catch (err) {
+	// Only the intended "dist not built" condition degrades. A corrupt or
+	// partially-written dist (SyntaxError, broken transitive load) raises a
+	// different code and MUST surface, not be masked into an empty registry.
+	if (err?.code !== 'ERR_MODULE_NOT_FOUND') throw err
+	// dist/driver-sdk absent — degrade to empty registry so module load
+	// does not crash. Any code path that actually needs a verb registry
+	// (driver-doctor, the bundled drivers) requires a built dist anyway;
+	// commands that don't (e.g. `route`) keep working.
+	_sdk = {
+		ASSERTION_VERBS: [],
+		ASYNC_VERBS: [],
+		EVIDENCE_VERBS: [],
+		IDL_VERB_ARGS: {},
+		IDL_VERB_NAMES: [],
+		INTERACTION_VERBS: [],
+		isVerbResult: () => false,
+		LIFECYCLE_VERBS: [],
+		validateVerbArgs: () => ({ ok: true, errors: [] }),
+	}
+}
+
+export const ASSERTION_VERBS = _sdk.ASSERTION_VERBS
+export const ASYNC_VERBS = _sdk.ASYNC_VERBS
+export const EVIDENCE_VERBS = _sdk.EVIDENCE_VERBS
+export const IDL_VERB_ARGS = _sdk.IDL_VERB_ARGS
+export const IDL_VERB_NAMES = _sdk.IDL_VERB_NAMES
+export const INTERACTION_VERBS = _sdk.INTERACTION_VERBS
+export const isVerbResult = _sdk.isVerbResult
+export const LIFECYCLE_VERBS = _sdk.LIFECYCLE_VERBS
+export const validateVerbArgs = _sdk.validateVerbArgs

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

@@ -30,13 +30,60 @@
  * Existing `resolveDriver()` and `scoreDriver()` exports are unchanged.
  */
 
-import { UnsatisfiedRequiredCapabilityError } from '@aperant/framework/driver-sdk'
-
 /**
  * @typedef {import('@aperant/framework/driver-sdk').DriverManifest} DriverManifest
  * @typedef {import('./runtime-detect.mjs').RuntimeCapabilities} RuntimeCapabilities
  */
 
+/**
+ * Defense-in-depth (issue #248). The driver-sdk error class lives in
+ * `@aperant/framework/driver-sdk`, whose `exports` map resolves to
+ * `dist/driver-sdk/index.js`. An eager *static* top-level
+ * `import { UnsatisfiedRequiredCapabilityError } from '@aperant/framework/driver-sdk'`
+ * made the WHOLE apt-tools CLI crash at module-resolution time when the
+ * dist was not built (e.g. a CI step that skipped `pnpm build`): the
+ * static import is resolved at module-link, so an opaque
+ * `ERR_MODULE_NOT_FOUND` was raised before any command body — or any
+ * `--no-fail` downgrade in run-route-eval.mjs — could run.
+ *
+ * We instead resolve the class via a *dynamic* `await import()` that is
+ * wrapped in try/catch. Dynamic import is still evaluated at module
+ * load (top-level await), but its failure is now swallowable rather than
+ * a hard link-time crash:
+ *   - dist present (tests, post-build CI, published tarball) → the REAL
+ *     class is bound, so any thrown error stays
+ *     `instanceof UnsatisfiedRequiredCapabilityError` for every consumer
+ *     (including the resolver suites that import the class from the same
+ *     `@aperant/framework/driver-sdk` ESM specifier);
+ *   - dist absent → we fall back to a structurally identical local class
+ *     (same `.name` / `.capability` / `.attempts` shape, which
+ *     `detect-runtime.mjs` inspects via `.attempts`) so the CLI degrades
+ *     to a clear, catchable error instead of crashing at load.
+ *
+ * `resolveDriver` stays fully synchronous — the class is already bound by
+ * the time any importer of this module finishes linking.
+ *
+ * @type {new (message: string, capability?: string, attempts?: ReadonlyArray<{driver_id: string, reason: string}>) => Error}
+ */
+let UnsatisfiedRequiredCapabilityError
+try {
+	;({ UnsatisfiedRequiredCapabilityError } = await import('@aperant/framework/driver-sdk'))
+} catch (err) {
+	// Only the intended "dist not built" condition degrades. A corrupt or
+	// partially-written dist (SyntaxError, broken transitive load) raises a
+	// different code and MUST surface, not be masked into a silent fallback.
+	if (err?.code !== 'ERR_MODULE_NOT_FOUND') throw err
+	// dist/driver-sdk absent — degrade instead of crashing the CLI.
+	UnsatisfiedRequiredCapabilityError = class UnsatisfiedRequiredCapabilityError extends Error {
+		constructor(message, capability, attempts = []) {
+			super(message)
+			this.name = 'UnsatisfiedRequiredCapabilityError'
+			this.capability = capability
+			this.attempts = attempts
+		}
+	}
+}
+
 const STABILITY_RANK = { ga: 3, beta: 2, experimental: 1 }
 const LOCALITY_RANK = { bundled: 3, user: 2, registry: 1 }