@aperant/framework 0.10.0 → 0.12.0

package/src/cli/verify-proof/sandbox/apply.mjs

@@ -0,0 +1,401 @@
+/**
+ * apply.mjs — recipe applier with dry-run default + per-change
+ * confirmation + TOFU non-clobber + audit-row writing.
+ *
+ * Three layered concerns covered here (subtasks 3.1, 3.2, 3.3):
+ *
+ *   3.1 — `confirm:false` (the default) is a pure dry-run. Returns
+ *         the planned writes list; writes ZERO bytes under the
+ *         adopter's source tree (ID-02).
+ *
+ *   3.2 — TOFU non-clobber. Per-change skip semantics modeled on
+ *         install/mcp-provision.mjs's already_applied / user_modified
+ *         / malformed_json / non_object_root states:
+ *           - already_applied: target file contains the recipe's marker
+ *             substring → no write.
+ *           - user_modified:  target file exists, doesn't contain the
+ *             marker, AND its content sha256 doesn't match the
+ *             recipe's expected-before hash (when provided) → no write.
+ *           - malformed_json / non_object_root: applicable to
+ *             json-merge changes only.
+ *
+ *   3.3 — Audit-row writing under withLock to .aperant/recipes-applied/
+ *         {recipe-id}.json. Captures original_sha256 + applied_sha256
+ *         + recipe_version + applied_at per change. file-create rows
+ *         record original_sha256:null.
+ *
+ * Public contract:
+ *   applyRecipe({projectDir, recipeId, recipes, confirm, perChangeConfirm})
+ *     → {writes, skips, audit_path}
+ *
+ * No process.exit; no thrown errors except for usage-shape violations.
+ * The CLI command wraps this and translates to the {envelope, exitCode}
+ * shape.
+ */
+
+import { createHash } from 'node:crypto'
+import { chmodSync, existsSync, readFileSync } from 'node:fs'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { atomicWriteJson, atomicWriteText } from '../../util/atomic-write.mjs'
+import { withFileLock } from '../../util/fs-lock.mjs'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * Defense-in-depth: assert a recipe-declared path resolves under the
+ * expected root. Rejects absolute paths and `../` escapes regardless of
+ * what the recipe schema validator accepted.
+ *
+ * Throws — caller surfaces the message in audit + CLI envelope. We throw
+ * rather than skip because a malicious-path-in-recipe is a CONTRACT
+ * violation, not a TOFU skip case.
+ *
+ * @param {string} rootAbs — absolute root the path must stay under.
+ * @param {string} relPath — recipe-declared relative path.
+ * @param {string} label — 'change.path' | 'change.template' for the error message.
+ * @returns {string} the validated absolute path under rootAbs.
+ */
+function assertPathUnderRoot(rootAbs, relPath, label) {
+	if (typeof relPath !== 'string' || relPath.length === 0) {
+		throw new Error(`applyRecipe: ${label} must be a non-empty string`)
+	}
+	if (isAbsolute(relPath)) {
+		throw new Error(`applyRecipe: ${label} must be relative, got absolute: ${relPath}`)
+	}
+	const candidate = resolve(rootAbs, relPath)
+	const rel = relative(rootAbs, candidate)
+	if (rel.startsWith('..') || isAbsolute(rel)) {
+		throw new Error(`applyRecipe: ${label} escapes root: ${relPath}`)
+	}
+	return candidate
+}
+
+/**
+ * @typedef {Object} ApplyChangeRecord
+ * @property {string} path — adopter-relative target
+ * @property {'written'|'skipped'|'skipped_unsafe'} action
+ * @property {string} [skip_reason] — already_applied | user_modified | malformed_json | non_object_root | dry_run
+ * @property {string|null} original_sha256
+ * @property {string|null} applied_sha256
+ * @property {string} recipe_version
+ * @property {string} applied_at
+ * @property {string} kind
+ */
+
+/**
+ * @param {{
+ *   projectDir: string,
+ *   recipeId: string,
+ *   recipes: object[],
+ *   confirm?: boolean,
+ *   perChangeConfirm?: (change: object, preview: {before: string, after: string}) => Promise<'accept'|'skip'|'abort'>,
+ *   force?: boolean
+ * }} args
+ * @returns {Promise<{
+ *   writes: ApplyChangeRecord[],
+ *   skips: ApplyChangeRecord[],
+ *   audit_path: string|null,
+ *   aborted: boolean,
+ *   recipe_id: string,
+ *   recipe_version: string
+ * }>}
+ */
+export async function applyRecipe(args) {
+	const { projectDir, recipeId, recipes, confirm = false, perChangeConfirm, force = false } = args
+	if (!projectDir) throw new Error('applyRecipe: projectDir required')
+	if (!recipeId) throw new Error('applyRecipe: recipeId required')
+	if (!Array.isArray(recipes)) throw new Error('applyRecipe: recipes[] required')
+
+	const recipe = recipes.find((r) => r && r.recipeId === recipeId)
+	if (!recipe) throw new Error(`applyRecipe: recipe not found: ${recipeId}`)
+
+	const adopterRoot = resolve(projectDir)
+	const writes = []
+	const skips = []
+	let aborted = false
+	const at = new Date().toISOString()
+
+	for (const change of recipe.changes ?? []) {
+		// Defense-in-depth: reject path-traversal in recipe-declared paths
+		// regardless of schema validation. A malicious community recipe
+		// could otherwise write outside the adopter root via `../../`.
+		const targetAbs = assertPathUnderRoot(adopterRoot, change.path, 'change.path')
+		const exists = existsSync(targetAbs)
+		const before = exists ? safeReadFile(targetAbs) : ''
+		const beforeSha = exists ? sha256(before) : null
+		const afterContent = renderAfterContent(change, recipe)
+
+		// TOFU non-clobber checks — per-change skip decisions.
+		const tofu = decideTofu({ change, before, exists, force })
+		if (tofu.skip) {
+			skips.push({
+				path: change.path,
+				kind: change.kind,
+				action: tofu.unsafe ? 'skipped_unsafe' : 'skipped',
+				skip_reason: tofu.reason,
+				original_sha256: beforeSha,
+				applied_sha256: null,
+				recipe_version: recipe.recipeVersion,
+				applied_at: at,
+			})
+			continue
+		}
+
+		const preview = { before, after: afterContent }
+
+		if (!confirm) {
+			// Dry-run: no write, no per-change prompt. The plan is the output.
+			writes.push({
+				path: change.path,
+				kind: change.kind,
+				action: 'written',
+				skip_reason: 'dry_run',
+				original_sha256: beforeSha,
+				applied_sha256: null,
+				recipe_version: recipe.recipeVersion,
+				applied_at: at,
+			})
+			continue
+		}
+
+		// With --confirm: ask the user per change. Default WHEN NO
+		// confirmer is provided is `skip` (fail-safe per ID-02 — the
+		// framework never auto-applies without an explicit accept signal
+		// from the caller surface).
+		const verdict = perChangeConfirm ? await perChangeConfirm(change, preview) : 'skip'
+		if (verdict === 'abort') {
+			aborted = true
+			break
+		}
+		if (verdict === 'skip') {
+			skips.push({
+				path: change.path,
+				kind: change.kind,
+				action: 'skipped',
+				skip_reason: 'user_declined',
+				original_sha256: beforeSha,
+				applied_sha256: null,
+				recipe_version: recipe.recipeVersion,
+				applied_at: at,
+			})
+			continue
+		}
+
+		// Verdict 'accept' — perform the write.
+		const writeResult = performWrite(targetAbs, change, afterContent, before)
+		writes.push({
+			path: change.path,
+			kind: change.kind,
+			action: 'written',
+			skip_reason: null,
+			original_sha256: beforeSha,
+			applied_sha256: writeResult.applied_sha256,
+			recipe_version: recipe.recipeVersion,
+			applied_at: at,
+		})
+	}
+
+	// Audit row write — only when we actually wrote (or attempted to).
+	// For dry-runs we still return the plan in `writes` but do NOT touch
+	// the audit file. ID-02: dry-run never mutates state.
+	let auditPath = null
+	if (confirm) {
+		auditPath = join(adopterRoot, '.aperant', 'recipes-applied', `${recipe.recipeId}.json`)
+		writeAuditRow({
+			auditPath,
+			recipeId: recipe.recipeId,
+			recipeVersion: recipe.recipeVersion,
+			at,
+			writes,
+			skips,
+			aborted,
+		})
+	}
+
+	return {
+		writes,
+		skips,
+		audit_path: auditPath,
+		aborted,
+		recipe_id: recipe.recipeId,
+		recipe_version: recipe.recipeVersion,
+	}
+}
+
+/**
+ * TOFU decision per change. Returns {skip:true, reason, unsafe?} or
+ * {skip:false}.
+ */
+function decideTofu({ change, before, exists, force }) {
+	if (!exists) {
+		// New target — always safe to write.
+		return { skip: false }
+	}
+
+	// Marker check first — if the recipe's marker substring is already
+	// in the file, treat as idempotent application (regardless of kind).
+	if (
+		typeof change.marker === 'string' &&
+		change.marker.length > 0 &&
+		before.includes(change.marker)
+	) {
+		return { skip: true, reason: 'already_applied' }
+	}
+
+	// json-merge specific safety: only touch plain-object roots.
+	if (change.kind === 'json-merge') {
+		let parsed
+		try {
+			parsed = before === '' ? {} : JSON.parse(before)
+		} catch {
+			return { skip: true, reason: 'malformed_json', unsafe: true }
+		}
+		if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+			return { skip: true, reason: 'non_object_root', unsafe: true }
+		}
+	}
+
+	// `before` SHA divergence: target file exists but the recipe has an
+	// expected before-content/sha and it doesn't match. Without --force,
+	// skip as user_modified. A 64-char hex string is treated as a SHA;
+	// anything else is treated as a substring anchor.
+	if (!force && typeof change.before === 'string' && change.before.length > 0) {
+		if (/^[a-f0-9]{64}$/.test(change.before)) {
+			if (sha256(before) !== change.before) {
+				return { skip: true, reason: 'user_modified' }
+			}
+		} else if (!before.includes(change.before)) {
+			return { skip: true, reason: 'user_modified' }
+		}
+	}
+
+	return { skip: false }
+}
+
+/**
+ * Materialize the post-condition content for a change.
+ */
+function renderAfterContent(change, recipe) {
+	if (change.kind === 'json-merge') {
+		return JSON.stringify(change.after ?? {}, null, 2)
+	}
+	if (change.template) {
+		const tpl = locateRecipeTemplate(recipe, change.template)
+		if (tpl && existsSync(tpl)) return safeReadFile(tpl)
+	}
+	if (typeof change.after === 'string') return change.after
+	return ''
+}
+
+function performWrite(targetAbs, change, afterContent, before) {
+	if (change.kind === 'json-merge') {
+		// Deep-merge change.after into existing JSON (already verified to
+		// be plain-object root in decideTofu).
+		const parsed = before === '' ? {} : JSON.parse(before)
+		const merged = deepMerge(parsed, change.after ?? {})
+		atomicWriteJson(targetAbs, merged)
+		const out = `${JSON.stringify(merged, null, 2)}\n`
+		return { applied_sha256: sha256(out) }
+	}
+	if (change.kind === 'text-insert') {
+		// v1: append the patch block after the existing file content. Adopters
+		// confirm per-change; the diff has been previewed; explicit append is
+		// the safest non-destructive semantic for a v1.
+		const out = before + (before.endsWith('\n') ? '' : '\n') + afterContent
+		atomicWriteText(targetAbs, out)
+		return { applied_sha256: sha256(out) }
+	}
+	if (change.kind === 'file-create' || change.kind === 'helper-script') {
+		atomicWriteText(targetAbs, afterContent)
+		if (typeof change.mode === 'number') {
+			try {
+				chmodSync(targetAbs, change.mode)
+			} catch {
+				// chmod failure is non-fatal — the recipe's verify-sandbox step
+				// will surface a non-executable script as a self-test failure.
+			}
+		}
+		return { applied_sha256: sha256(afterContent) }
+	}
+	// Unknown kind — fail loud (ID-01). A recipe shipping an unrecognized
+	// change.kind is a contract violation, not a TOFU skip case.
+	throw Object.assign(
+		new Error(`applyRecipe: unknown change.kind '${change.kind}' on path '${change.path}'`),
+		{
+			code: 'E_UNKNOWN_CHANGE_KIND',
+			kind: change.kind,
+			path: change.path,
+		},
+	)
+}
+
+function deepMerge(a, b) {
+	if (b === null || typeof b !== 'object' || Array.isArray(b)) return b
+	if (a === null || typeof a !== 'object' || Array.isArray(a)) return b
+	const out = { ...a }
+	for (const k of Object.keys(b)) {
+		out[k] = k in a ? deepMerge(a[k], b[k]) : b[k]
+	}
+	return out
+}
+
+/**
+ * Write/update the audit row file under withFileLock. The lock helper is
+ * synchronous (it uses proper-lockfile's sync API + an Atomics.wait
+ * retry loop), so this function is sync — the caller already declared
+ * `await` for forward-compatibility with a future async lock.
+ */
+const AUDIT_ENTRIES_CAP = 50
+
+function writeAuditRow({ auditPath, recipeId, recipeVersion, at, writes, skips, aborted }) {
+	withFileLock(auditPath, () => {
+		const existing = existsSync(auditPath) ? JSON.parse(safeReadFile(auditPath) || '{}') : {}
+		const entries = Array.isArray(existing.entries) ? existing.entries : []
+		entries.push({
+			recipe_id: recipeId,
+			recipe_version: recipeVersion,
+			applied_at: at,
+			aborted,
+			writes,
+			skips,
+		})
+		// Cap to the last N entries to prevent unbounded disk growth (PRF-003).
+		const capped = entries.length > AUDIT_ENTRIES_CAP ? entries.slice(-AUDIT_ENTRIES_CAP) : entries
+		const doc = {
+			recipe_id: recipeId,
+			latest_version: recipeVersion,
+			last_applied_at: at,
+			entries: capped,
+		}
+		atomicWriteJson(auditPath, doc)
+	})
+}
+
+function safeReadFile(path) {
+	try {
+		return readFileSync(path, 'utf-8')
+	} catch {
+		return ''
+	}
+}
+
+function sha256(content) {
+	return createHash('sha256').update(content, 'utf-8').digest('hex')
+}
+
+function locateRecipeTemplate(recipe, templateName) {
+	// Defense-in-depth: a malicious recipe could otherwise specify
+	// `templateName: "../../etc/passwd"` and read arbitrary host files
+	// into the adopter source tree. Resolve under templates/ and assert.
+	// Also guard the recipeId itself — discoverBundledRecipes() skips schema
+	// validation, so the ^[a-z][a-z0-9_-]*$ pattern may not have been enforced.
+	if (typeof recipe.recipeId !== 'string' || !/^[a-z][a-z0-9_-]*$/.test(recipe.recipeId)) {
+		throw new Error(
+			`applyRecipe: invalid recipeId '${recipe.recipeId}' — must match ^[a-z][a-z0-9_-]*$`,
+		)
+	}
+	const frameworkRoot = resolve(__dirname, '..', '..', '..', '..')
+	const templatesRoot = join(frameworkRoot, 'recipes', recipe.recipeId, 'templates')
+	return assertPathUnderRoot(templatesRoot, templateName, 'change.template')
+}

package/src/cli/verify-proof/sandbox/gate-predicate.mjs

@@ -0,0 +1,126 @@
+/**
+ * gate-predicate.mjs — extracted decision function for the sandbox
+ * precondition gate at apt-verify-proof/SKILL.md Step 2c.
+ *
+ * Refactored out of the SKILL.md prose so the e2e test (subtask 7.3)
+ * can call it directly without re-implementing the dispatch table.
+ *
+ * Inputs:
+ *   - config:           {verification?: {sandbox?: {enabled:bool, ...}}}
+ *   - stateFile:        the v2-shaped envelope read from
+ *                       .aperant/state/verify-proof-sandbox-verified.json
+ *                       OR null when the file is missing.
+ *   - parallelRequested: bool — true when /apt:verify-proof was invoked
+ *                       with --parallel.
+ *
+ * Returns:
+ *   - {action: 'proceed'}                — verified + approved, walker may run
+ *   - {action: 'skip-gate'}              — --parallel NOT requested OR
+ *                                          verification.sandbox absent;
+ *                                          Fast Path Guarantee (ID-07).
+ *   - {action: 'exit', envelope}         — verified:false OR state missing;
+ *                                          envelope is the v2 fail-loud shape.
+ *
+ * The `envelope` shape on exit is:
+ *   {status:'error', code:'E_SANDBOX_UNVERIFIED', verdict:'needs_human',
+ *    reason:'sandbox_unverified', remediation:'/apt:verify-proof setup'}
+ *
+ * No I/O, no process.exit — pure function for testability.
+ */
+
+const FAIL_ENVELOPE = Object.freeze({
+	status: 'error',
+	code: 'E_SANDBOX_UNVERIFIED',
+	verdict: 'needs_human',
+	reason: 'sandbox_unverified',
+	remediation: '/apt:verify-proof setup',
+})
+
+const STALE_VERDICT_ENVELOPE = Object.freeze({
+	status: 'error',
+	code: 'E_SANDBOX_VERDICT_STALE',
+	verdict: 'needs_human',
+	reason: 'sandbox_recipe_version_drift',
+	remediation: 'apt-tools verify-sandbox <project-dir>',
+})
+
+/**
+ * @typedef {Object} GateInput
+ * @property {object|null|undefined} config
+ * @property {object|null|undefined} stateFile
+ * @property {boolean} parallelRequested
+ */
+
+/**
+ * @typedef {Object} GateEnvelope
+ * @property {'error'} status
+ * @property {string} code
+ * @property {string} verdict
+ * @property {string} reason
+ * @property {string} remediation
+ */
+
+/**
+ * @typedef {Object} GateOutput
+ * @property {'proceed'|'skip-gate'|'exit'} action
+ * @property {GateEnvelope} [envelope]
+ */
+
+/**
+ * @param {GateInput} input
+ * @returns {GateOutput}
+ */
+export function gatePredicate({ config, stateFile, parallelRequested }) {
+	// (1) --parallel NOT requested → gate is a no-op (Fast Path Guarantee ID-07).
+	if (!parallelRequested) return { action: 'skip-gate' }
+
+	// (2) verification.sandbox is ABSENT → also skip-gate (the adopter
+	//     has not opted in; respect the absent-config branch as no-op).
+	const sandboxCfg = config?.verification?.sandbox
+	if (!sandboxCfg || sandboxCfg.enabled !== true) {
+		// Note: even though --parallel was requested, the absent-config
+		// branch returns skip-gate; the SKILL.md Step 2c prose handles
+		// the absent-config case via the first-run hook (Step 1) which
+		// is a UX surface, not a gate failure.
+		return { action: 'skip-gate' }
+	}
+
+	// (3) state file present + verified:true + verdict:'approved' → check version drift.
+	if (stateFile && stateFile.verified === true && stateFile.verdict === 'approved') {
+		// (3a) Version drift check: when both sides have recipeVersion, verify the
+		//      state file's version is in the active recipe's compatibleWithApplied[].
+		//      If either side has null/undefined recipeVersion, fall through (compat
+		//      with pre-LOG-003 state files that predate recipeVersion population).
+		const stateVersion = stateFile.recipeVersion ?? null
+		const activeVersion = sandboxCfg.recipeVersion ?? null
+		const compatibleWith = Array.isArray(sandboxCfg.compatibleWithApplied)
+			? sandboxCfg.compatibleWithApplied
+			: null
+
+		if (stateVersion && activeVersion && compatibleWith !== null) {
+			// Both sides versioned — only stale if the state version is NOT
+			// listed in the active recipe's compatibleWithApplied AND the
+			// versions differ.
+			if (stateVersion !== activeVersion && !compatibleWith.includes(stateVersion)) {
+				return { action: 'exit', envelope: { ...STALE_VERDICT_ENVELOPE } }
+			}
+		}
+
+		return { action: 'proceed' }
+	}
+
+	// (4) Everything else → fail loud with the v2 envelope.
+	return { action: 'exit', envelope: { ...FAIL_ENVELOPE } }
+}
+
+/**
+ * The frozen fail envelope — exported so callers can detect-and-match
+ * without re-stringifying.
+ */
+export const SANDBOX_UNVERIFIED_ENVELOPE = FAIL_ENVELOPE
+
+/**
+ * The frozen stale-verdict envelope — emitted when the state file's
+ * recipeVersion is no longer in the active recipe's compatibleWithApplied[].
+ */
+export const SANDBOX_VERDICT_STALE_ENVELOPE = STALE_VERDICT_ENVELOPE

package/src/cli/verify-proof/sandbox/pattern-matcher.mjs

@@ -0,0 +1,127 @@
+/**
+ * pattern-matcher.mjs — sandbox-recipe pattern matcher.
+ *
+ * Walks the registered recipes' `match.capabilities[]` + `match.deps[]`
+ * predicates against the loaded runtime capabilities + package.json deps,
+ * and returns the FIRST matching recipe (or null with a human reason).
+ *
+ * Two-arg shape:
+ *   - `match.capabilities[]` — every entry must be `true` on the
+ *     RuntimeCapabilities record (AND semantics — all required).
+ *   - `match.deps[]` — at least one entry must appear in the merged
+ *     dependencies + devDependencies of the project's root package.json
+ *     (OR semantics — any-of).
+ *
+ * This split lets a recipe say "I need is_electron AND one of
+ * [@libsql/client, better-sqlite3]" without enumerating every combination.
+ *
+ * See: spec ID-04 (v1 ships ONE recipe — electron-libsql), AC5.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+/**
+ * @typedef {import('../../util/runtime-capabilities.mjs').RuntimeCapabilities} RuntimeCapabilities
+ */
+
+/**
+ * @typedef {Object} SandboxRecipe
+ * @property {string} recipeId
+ * @property {string} recipeVersion
+ * @property {string} name
+ * @property {string} description
+ * @property {{capabilities: string[], deps: string[]}} match
+ * @property {{logPattern: string, timeoutMs: number}} readiness
+ * @property {Array<object>} changes
+ * @property {string[]} compatibleWithApplied
+ */
+
+/**
+ * @typedef {Object} MatchResult
+ * @property {string|null} recipeId
+ * @property {string} reason
+ */
+
+/**
+ * @param {RuntimeCapabilities} runtimeCaps
+ * @param {Record<string, unknown> | null} packageJson
+ * @param {SandboxRecipe[]} recipes
+ * @returns {MatchResult}
+ */
+export function matchPattern(runtimeCaps, packageJson, recipes) {
+	if (!Array.isArray(recipes) || recipes.length === 0) {
+		return { recipeId: null, reason: 'no recipes registered' }
+	}
+
+	const deps = mergedDeps(packageJson)
+
+	for (const recipe of recipes) {
+		const reqCaps = recipe.match?.capabilities ?? []
+		const anyDeps = recipe.match?.deps ?? []
+
+		const capsOk = reqCaps.every((cap) => runtimeCaps && runtimeCaps[cap] === true)
+		if (!capsOk) continue
+
+		// deps[] is any-of — recipe matches if at least one declared dep is in
+		// the project. An empty deps[] means "no dep constraint" (cap-only match).
+		const depsOk = anyDeps.length === 0 || anyDeps.some((d) => deps.has(d.toLowerCase()))
+		if (!depsOk) continue
+
+		return { recipeId: recipe.recipeId, reason: 'matched' }
+	}
+
+	return {
+		recipeId: null,
+		reason: `no recipe available for runtime: ${describeRuntime(runtimeCaps)}`,
+	}
+}
+
+/**
+ * Convenience overload — load the project's package.json from disk.
+ *
+ * @param {string} projectDir
+ * @param {RuntimeCapabilities} runtimeCaps
+ * @param {SandboxRecipe[]} recipes
+ * @returns {MatchResult}
+ */
+export function matchPatternForProject(projectDir, runtimeCaps, recipes) {
+	const pkgPath = join(resolve(projectDir), 'package.json')
+	let pkg = null
+	if (existsSync(pkgPath)) {
+		try {
+			pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+		} catch {
+			/* fall through with pkg=null */
+		}
+	}
+	return matchPattern(runtimeCaps, pkg, recipes)
+}
+
+/**
+ * Build a Set of lowercased package names from dependencies + devDependencies.
+ *
+ * @param {Record<string, unknown> | null} packageJson
+ */
+function mergedDeps(packageJson) {
+	const out = new Set()
+	if (packageJson === null || typeof packageJson !== 'object') return out
+	const d = /** @type {Record<string, unknown>} */ (packageJson.dependencies)
+	const dd = /** @type {Record<string, unknown>} */ (packageJson.devDependencies)
+	if (d && typeof d === 'object') for (const k of Object.keys(d)) out.add(k.toLowerCase())
+	if (dd && typeof dd === 'object') for (const k of Object.keys(dd)) out.add(k.toLowerCase())
+	return out
+}
+
+/**
+ * One-line description of the detected runtime shape — used in the
+ * no-match reason so an adopter sees what the matcher saw.
+ *
+ * @param {RuntimeCapabilities} runtimeCaps
+ */
+function describeRuntime(runtimeCaps) {
+	if (!runtimeCaps || typeof runtimeCaps !== 'object') return 'unknown'
+	const active = Object.keys(runtimeCaps).filter((k) => runtimeCaps[k] === true)
+	if (active.length === 0) return 'no capabilities detected'
+	return active.join(', ')
+}