@aperant/framework 0.8.7 → 0.10.0

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/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')
 }

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 }