@aperant/framework 0.8.1 → 0.8.4

package/src/cli/verify-proof/runtime-detect.mjs

@@ -0,0 +1,122 @@
+/**
+ * runtime-detect.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.
+ *
+ * Pattern: pure data in → pure data out. No filesystem walking, no exec.
+ * Use loadRuntimeCapabilities(projectDir) for the cwd-rooted variant.
+ */
+
+import { existsSync, readFileSync } 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.
+ * Returns empty capabilities if no package.json exists (malformed or
+ * missing — both cases fall through to "nothing detected").
+ *
+ * @param {string} projectDir
+ * @returns {RuntimeCapabilities}
+ */
+export function loadRuntimeCapabilities(projectDir) {
+	const pkgPath = join(resolve(projectDir), 'package.json')
+	if (!existsSync(pkgPath)) return emptyCapabilities()
+	let parsed
+	try {
+		parsed = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+	} catch {
+		return emptyCapabilities()
+	}
+	return detectFromPackageJson(parsed)
+}

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

@@ -0,0 +1,187 @@
+/**
+ * trust.mjs — driver trust enforcement (TOFU lock + policy file + decision).
+ *
+ * Implements ID-03:
+ *   - 4 trust tiers: first_party_signed (default-allow), community_verified,
+ *     community_unverified, local_unverified.
+ *   - Default policy: only first_party_signed auto-runs.
+ *   - Non-first-party drivers require one-time user approval; approval is
+ *     bound to a TOFU lock at .aperant/driver-tofu.json keyed by
+ *     {driver_id, version, manifest_sha256, artifact_digest}. Any drift
+ *     re-prompts.
+ *
+ * The audit log (audit.mjs) writes one line per decision (allow/deny).
+ * The execution layer (exec.mjs) enforces structured-only local_command.
+ *
+ * This module is decision-only: it does NOT prompt the user. The caller
+ * (workflow runner / apt-tools driver doctor) decides whether to invoke
+ * the prompt UX, then calls recordApproval() to persist the TOFU entry.
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+/**
+ * @typedef {import('@aperant/driver-sdk').DriverManifest} DriverManifest
+ */
+
+const TOFU_PATH = '.aperant/driver-tofu.json'
+const POLICY_PATH = '.aperant/policy.json'
+
+/**
+ * Compute a stable manifest hash for TOFU + audit lines.
+ * @param {DriverManifest} manifest
+ * @returns {string}
+ */
+export function manifestSha256(manifest) {
+	const stable = JSON.stringify(manifest, Object.keys(manifest).sort())
+	return createHash('sha256').update(stable).digest('hex')
+}
+
+/**
+ * Read the TOFU lock file. Returns an empty object if missing or malformed.
+ * @param {string} projectDir
+ * @returns {Record<string, {manifest_sha256: string, artifact_digest?: string, approved_at: string, trust_tier: string}>}
+ */
+export function readTofuLock(projectDir) {
+	const path = join(resolve(projectDir), TOFU_PATH)
+	if (!existsSync(path)) return {}
+	try {
+		return JSON.parse(readFileSync(path, 'utf-8'))
+	} catch {
+		return {}
+	}
+}
+
+/**
+ * Persist a TOFU lock file (atomic-ish: write + rename not used since we
+ * append-only to a tiny JSON; conflicting writes from parallel agents
+ * would clobber an entry but `.aperant/driver-tofu.json` is per-project,
+ * not per-agent).
+ *
+ * @param {string} projectDir
+ * @param {Record<string, unknown>} tofu
+ */
+export function writeTofuLock(projectDir, tofu) {
+	const path = join(resolve(projectDir), TOFU_PATH)
+	mkdirSync(dirname(path), { recursive: true })
+	writeFileSync(path, JSON.stringify(tofu, null, 2) + '\n', 'utf-8')
+}
+
+/**
+ * Build the canonical TOFU key for a (driver, version) pair. The hash is
+ * NOT part of the key — the value's manifest_sha256 + artifact_digest
+ * detect drift.
+ * @param {string} driverId
+ * @param {string} version
+ * @returns {string}
+ */
+export function tofuKey(driverId, version) {
+	return `${driverId}@${version}`
+}
+
+/**
+ * Read the project's policy file. Returns the default policy if missing.
+ * @param {string} projectDir
+ * @returns {{mode: 'first_party_only' | 'allowlist', allowed: string[], denied: string[]}}
+ */
+export function readPolicy(projectDir) {
+	const path = join(resolve(projectDir), POLICY_PATH)
+	const defaults = { mode: 'first_party_only', allowed: [], denied: [] }
+	if (!existsSync(path)) return defaults
+	try {
+		const parsed = JSON.parse(readFileSync(path, 'utf-8'))
+		return {
+			mode: parsed.mode === 'allowlist' ? 'allowlist' : 'first_party_only',
+			allowed: Array.isArray(parsed.allowed) ? parsed.allowed : [],
+			denied: Array.isArray(parsed.denied) ? parsed.denied : [],
+		}
+	} catch {
+		return defaults
+	}
+}
+
+/**
+ * Decide whether a driver invocation is allowed.
+ *
+ * @param {DriverManifest} manifest
+ * @param {ReturnType<typeof readTofuLock>} tofu
+ * @param {ReturnType<typeof readPolicy>} policy
+ * @returns {{decision: 'allow' | 'deny' | 'requires_approval', reason: string, expected_manifest_sha256?: string}}
+ */
+export function decide(manifest, tofu, policy) {
+	const tier = manifest.trust?.tier
+	const driverId = manifest.driverId
+	const version = manifest.version
+
+	// Policy denylist always wins.
+	if (policy.denied.includes(driverId)) {
+		return { decision: 'deny', reason: `policy denies driver ${driverId}` }
+	}
+
+	// first_party_signed: default-allow under either policy mode (unless
+	// explicitly denied above).
+	if (tier === 'first_party_signed') {
+		return { decision: 'allow', reason: 'first_party_signed driver — default allow' }
+	}
+
+	// first_party_only mode blocks every other tier.
+	if (policy.mode === 'first_party_only') {
+		return {
+			decision: 'deny',
+			reason: `policy.mode=first_party_only blocks ${tier} driver`,
+		}
+	}
+
+	// allowlist mode: require explicit allow entry AND a valid TOFU lock.
+	if (!policy.allowed.includes(driverId)) {
+		return {
+			decision: 'deny',
+			reason: `policy.mode=allowlist but ${driverId} not in allowed[]`,
+		}
+	}
+
+	// Check TOFU lock.
+	const key = tofuKey(driverId, version)
+	const entry = tofu[key]
+	const currentHash = manifestSha256(manifest)
+
+	if (!entry) {
+		return {
+			decision: 'requires_approval',
+			reason: `no TOFU entry for ${key} — first run requires approval`,
+			expected_manifest_sha256: currentHash,
+		}
+	}
+
+	if (entry.manifest_sha256 !== currentHash) {
+		return {
+			decision: 'requires_approval',
+			reason: `TOFU manifest_sha256 drift for ${key} — driver changed since approval, re-prompt required`,
+			expected_manifest_sha256: currentHash,
+		}
+	}
+
+	return { decision: 'allow', reason: `TOFU entry valid for ${key}` }
+}
+
+/**
+ * Persist a one-time approval for a (driver, version) pair into the TOFU
+ * lock. The caller is responsible for actually prompting the user; this
+ * function just writes the entry.
+ *
+ * @param {string} projectDir
+ * @param {DriverManifest} manifest
+ */
+export function recordApproval(projectDir, manifest) {
+	const tofu = readTofuLock(projectDir)
+	const key = tofuKey(manifest.driverId, manifest.version)
+	tofu[key] = {
+		manifest_sha256: manifestSha256(manifest),
+		artifact_digest: manifest.trust?.integrity?.artifact_digest,
+		approved_at: new Date().toISOString(),
+		trust_tier: manifest.trust?.tier,
+	}
+	writeTofuLock(projectDir, tofu)
+}

package/templates/adr-format.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/ADR-FORMAT.md
-Licensed under MIT. Modifications: ported as the Aperant ADR template
-emitted by `apt-tools adr write` with Nygard's 3-gate filter
-(hard-to-reverse AND surprising-without-context AND real-trade-off).
--->
-
 # ADR-NNNN: {Title}
 
 **Status:** {Proposed | Accepted | Deprecated | Superseded}

package/templates/aperant-claude-md-appendix.md

@@ -1,6 +1,6 @@
 This project uses the [Aperant Framework](https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework) for AI-assisted development.
 
-### Fast Path Guarantee (Pocock adoption ID-05)
+### Fast Path Guarantee
 
 QUICK track is **hard-exempt** from PRD-shaped spec.md, HITL/AFK metadata,
 vertical-slice subtask schema, TDD iron law (`apt:execute --tdd`), triage

package/templates/context-format.md

@@ -1,15 +1,7 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md
-Licensed under MIT. Modifications: ported as the Aperant CONTEXT.md
-template emitted by `apt-tools context write`. Adds the "Project glossary"
-header and example dialogue section.
--->
-
 # Project glossary (CONTEXT.md)
 
 This file is the persistent project glossary. Each term-block carries the
-following fields per Pocock's CONTEXT.md format:
+following fields per the Aperant CONTEXT.md format:
 
 - **{Term}** — definition (one line).
   - **Aliases to avoid:** comma-separated synonyms or near-synonyms that

package/templates/proof-verification.md

@@ -18,7 +18,17 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
     "updated": "{ISO timestamp}",
     "spec": "{spec.md path or task description}",
     "verdict": "pending | approved | approved_with_notes | rejected",
-    "tools": ["electron", "puppeteer", "cdp_video"]
+    "tools": ["electron", "puppeteer", "cdp_video"],
+    "selected_driver": {
+      "driverId": "electron",
+      "version": "0.1.0",
+      "manifest_sha256": "abc123...",
+      "trust_tier": "first_party_signed",
+      "sandbox_profile": "workspace_write"
+    },
+    "fallback_attempts": [
+      { "driver_id": "browser", "reason": "missing required capabilities: dump_state" }
+    ]
   },
 
   "automated_checks": {
@@ -66,8 +76,8 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
     {
       "registry_id": "terminals-settings-scrollback-slider",
       "name": "Scrollback buffer slider",
-      "reason": "blocked_by_platform",
-      "detail": "Slider interaction not supported via current MCP tools"
+      "reason": "unsatisfied_optional_capability",
+      "detail": "Selected driver does not implement the IDL verb required for slider interaction"
     }
   ],
 
@@ -149,7 +159,9 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
 | `updated` | string | OVERWRITE | ISO timestamp, updated on every write |
 | `spec` | string | IMMUTABLE | Path to spec or task description |
 | `verdict` | string | OVERWRITE | Derived from dimension scores after all tests |
-| `tools` | array | IMMUTABLE | MCP tools detected as available |
+| `tools` | array | IMMUTABLE | MCP tools / auxiliary capture tools detected as available |
+| `selected_driver` | object | IMMUTABLE | The verify-proof driver chosen by the resolver per ID-02. Fields: `driverId`, `version`, `manifest_sha256`, `trust_tier`, `sandbox_profile`. |
+| `fallback_attempts` | array | IMMUTABLE | Drivers the resolver REJECTED before selecting. Each entry has `driver_id` + `reason` (missing capabilities, stability filter, hash drift, policy denial). Audit trail for coverage-loss decisions. |
 
 ### automated_checks
 Each check has `status` (pass/fail) and `output` (captured terminal output). These are populated in step 3 before any manual testing begins.
@@ -188,9 +200,11 @@ Every registered sub-feature that does NOT have a test MUST appear here. Silence
 |-------|------|-------------|
 | `registry_id` | string | The sub-feature `id` from the feature registry |
 | `name` | string | Human-readable name of the skipped feature |
-| `reason` | string | One of: `time_constraint`, `blocked_by_platform`, `depends_on_other`, `not_applicable` |
+| `reason` | string | One of: `time_constraint`, `unsatisfied_optional_capability` (preferred), `depends_on_other`, `not_applicable`. **Legacy alias:** `blocked_by_platform` is read by the schema reader as an alias for `unsatisfied_optional_capability` and emits a deprecation warning. New writes MUST use the new reason. |
 | `detail` | string | Brief explanation of why this feature was skipped |
 
+> **Fail-closed, not a skip.** If a REQUIRED IDL capability has no implementing driver in the resolver chain, the resolver throws `unsatisfied_required_capability` (per ID-02) — aborts the run. That entry does NOT land in `skipped[]`; coverage loss is loud, deliberate, and audited via `meta.fallback_attempts[]`.
+
 ### dimensions
 Four QA dimensions, each with `score` (1-10) and `rationale` (string). Scores are evidence-based, never assumed.
 

package/workflows/verify-proof.md

@@ -53,17 +53,47 @@ mkdir -p "${PROOF_DIR}/screenshots"
 </step>
 
 <step name="pre_check">
-## 2. Pre-Check
+## 2. Pre-Check + Driver Selection
 
 If `implementation_plan.json` exists, verify all subtasks are completed.
 If any are pending: report and exit.
 
-Check which MCP tools are available:
-- Try `mcp__electron__get_electron_window_info` — if responds, Electron is available
-- Try `mcp__puppeteer__puppeteer_navigate` — if responds, browser is available
-- Check `apt-proof-video --version` — if available, CDP video capture is enabled
+### 2a. Resolve the verify-proof driver
 
-Record available tools in verification.json `meta.tools` array.
+The workflow is **runtime-agnostic** — it refers to IDL verbs
+(`driver.click(target)`, `driver.screenshot(path)`), never to concrete
+MCP tool names. The driver layer (`packages/framework/drivers/*/`)
+maps verbs to transports. Auto-detect the runtime and select a driver:
+
+```bash
+# Detect the project's runtime capabilities + select a driver
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs detect-runtime .
+# → {status:"ok", runtime:{is_electron, is_tauri, is_nextjs, ...}, selected_driver_id:"..."}
+```
+
+The resolver picks the highest-scoring driver per ID-02 (capability_coverage
+> compatibility > stability > priority > locality). Adopters override
+auto-detect via `.aperant/config.json:verification.runtimes[]`:
+
+```json
+{ "verification": { "runtimes": ["electron", "cli"] } }
+```
+
+If no driver satisfies a REQUIRED capability, the resolver throws
+`unsatisfied_required_capability` — fail-closed, NOT a silent
+`blocked_by_platform` skip (per ID-02).
+
+### 2b. Probe optional evidence-capture tools
+
+```bash
+# CDP video capture (optional)
+apt-proof-video --version  # if available, CDP video is on
+```
+
+Record the selected driver + auxiliary tools in verification.json:
+`meta.selected_driver: {driverId, version, manifest_sha256, trust_tier,
+sandbox_profile}` and `meta.fallback_attempts: [{driver_id, reason}]`
+(see ST11's schema extension in `templates/proof-verification.md`).
 </step>
 
 <step name="automated_checks">
@@ -165,10 +195,14 @@ coverage = tested_count / registered_count
 **Every untested registered feature MUST go in the `skipped` array** with a reason.
 Valid skip reasons:
 - `time_constraint` — would take too long relative to value
-- `blocked_by_platform` — MCP tools cannot interact with this element
+- `unsatisfied_optional_capability` — the selected driver lacks an OPTIONAL IDL verb needed by this test (e.g. `assert_network` not implemented). Loud, deliberate skip.
 - `depends_on_other` — requires a feature not yet implemented
 - `not_applicable` — feature is deprecated or not relevant to this verification
 
+> **Legacy alias.** `blocked_by_platform` (pre-driver-architecture) is read by the schema reader as an alias for `unsatisfied_optional_capability` and emits a deprecation warning. New writes MUST use the new reason.
+
+> **Fail-closed, not a skip:** if a REQUIRED IDL capability has no implementing driver in the resolver chain, the resolver throws `unsatisfied_required_capability` (per ID-02). This aborts the run — it does NOT silently land in the `skipped` array. Coverage loss is loud, deliberate, and audited.
+
 Silence about untested features is NOT acceptable. Every registered sub-feature must appear
 either as a test (with `registry_id`) or in the `skipped` array.
 </step>
@@ -232,11 +266,17 @@ If CDP is NOT available, note it and proceed without video.
 For each test, in order:
 
 ### 7a. Perform the Action
-Actually do what the test says:
-- If it says "type X" → use `mcp__electron__send_command_to_electron` with `fill_input` or `send_keyboard_shortcut`
-- If it says "click X" → use the appropriate click tool
-- If it says "navigate to X" → navigate there
-- If it says "run command X" → run it
+Actually do what the test says — invoke the IDL verb on the selected driver:
+- If it says "type X" → `driver.type({ target, text: "X" })`
+- If it says "click X" → `driver.click({ target })`
+- If it says "navigate to X" → `driver.navigate({ url: "X" })`
+- If it says "press key X" → `driver.key({ key: "X" })`
+- If it says "run command X" → `driver.execute_js({ script: "X" })`
+
+The driver layer translates IDL verbs to its transport (an MCP server,
+a local binary, or a built-in HTTP request). Workflow prose names ONLY
+IDL verbs per ID-01 — concrete tool names live in
+`packages/framework/drivers/<driver>/driver.mjs`.
 
 ### 7b. Wait for Result
 Wait for the action to complete. If it involves loading, wait for the load.
@@ -245,8 +285,10 @@ Add a short delay (1-2 seconds) so the CDP capture also captures this state.
 ### 7c. Capture Evidence
 Take a screenshot AFTER the action completes:
 ```
-Tool: mcp__electron__take_screenshot
-Args: {"outputPath": "${PROOF_DIR}/screenshots/{feature-id}-test-{n}.png"}
+driver.screenshot({
+  target: { kind: "css", value: "body" },
+  output_path: "${PROOF_DIR}/screenshots/{feature-id}-test-{n}.png"
+})
 ```
 
 ### 7d. Analyze Evidence