@aperant/framework 0.8.7 → 0.9.0

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 }