@aperant/framework 0.8.1 → 0.8.4

package/src/cli/dispatch.mjs

@@ -53,7 +53,9 @@ import { cmdDesignScan } from './commands/design-scan.mjs'
 import { cmdDesignTemplate } from './commands/design-template.mjs'
 import { cmdDesignValidate } from './commands/design-validate.mjs'
 import { cmdDetectProject } from './commands/detect-project.mjs'
+import { cmdDetectRuntime } from './commands/detect-runtime.mjs'
 import { cmdDocsAudit } from './commands/docs-audit.mjs'
+import { cmdDriverDoctor } from './commands/driver-doctor.mjs'
 import { cmdEditCheck } from './commands/edit-check.mjs'
 import { cmdEffects } from './commands/effects.mjs'
 import { cmdEvent } from './commands/event.mjs'
@@ -64,6 +66,7 @@ import { cmdHealthCheck } from './commands/health-check.mjs'
 import { cmdHostDetect, cmdReconcile } from './commands/host-detect.mjs'
 import { cmdInit } from './commands/init.mjs'
 import { cmdInitState } from './commands/init-state.mjs'
+import { cmdInstallFromSource } from './commands/install-from-source.mjs'
 import { cmdLock } from './commands/lock.mjs'
 import { cmdMigratePrReviews } from './commands/migrate-pr-reviews.mjs'
 import { cmdPersonas } from './commands/personas.mjs'
@@ -213,6 +216,18 @@ export const DISPATCH = {
 	'state-update': (args) => wrap(cmdStateUpdate)(args[1], args.slice(2)),
 	'state-artifacts': (args) => wrap(cmdStateArtifacts)(args[1], args.slice(2)),
 	'detect-project': (args) => wrap(cmdDetectProject)(args[1]),
+	'detect-runtime': (args) => wrap(cmdDetectRuntime)(args[1], args.slice(2)),
+	driver: (args) => {
+		// `apt-tools driver doctor <project-dir>` — only subcommand for now.
+		if (args[1] === 'doctor') return wrap(cmdDriverDoctor)(args[2], args.slice(3))
+		return wrap(() => ({
+			envelope: {
+				status: 'error',
+				error: `Usage: apt-tools driver doctor <project-dir>. Unknown subcommand: ${args[1] ?? '(none)'}`,
+			},
+			exitCode: 1,
+		}))()
+	},
 	'features-audit': (args) => wrap(cmdFeaturesAudit)(args[1], args.slice(2)),
 	'init-state': (args) => wrap(cmdInitState)(args[1], args.slice(2)),
 	'risk-check': (args) => wrap(cmdRiskCheck)(args[1], args.slice(2)),
@@ -232,6 +247,7 @@ export const DISPATCH = {
 	'detect-worktree': (args) => wrap(cmdDetectWorktree)(args[1]),
 	template: (args) => wrap(cmdTemplate)(args[1]),
 	'check-version': (args) => wrap(cmdCheckVersion)(args[1]),
+	'install-from-source': (args) => wrap(cmdInstallFromSource)(args[1]),
 	'health-check': (args) => wrap(cmdHealthCheck)(args[1]),
 	route: (args) => wrap(cmdRoute)(args[1], args.slice(2)),
 	statusline: (args) => wrap(cmdStatusline)(args[1], args.slice(2)),
@@ -287,7 +303,7 @@ export const DISPATCH = {
 	},
 	'plan-approval': (args) => wrap(cmdPlanApproval)(args[1], args[2], args.slice(3)),
 
-	// ---- Pocock adoption (ST-5, ST-6, ST-10, ST-13) artifact writers + discoverability ----
+	// ---- Aperant adoption (ST-5, ST-6, ST-10, ST-13) artifact writers + discoverability ----
 	context: (args) => wrap(cmdContext)(args[1], args[2], args.slice(3)),
 	adr: (args) => wrap(cmdAdr)(args[1], args[2], args.slice(3)),
 	triage: (args) => wrap(cmdTriage)(args[1], args[2], args.slice(3)),

package/src/cli/gate/context.mjs

@@ -11,7 +11,13 @@
  *     taskId:       string,
  *     taskDir:      string,          // <sharedRoot>/.aperant/tasks/<taskId>/
  *     taskRecord:   object | null,   // state.active_tasks[taskId] (or null)
- *     config:       object           // .aperant/config.json (empty {} if none)
+ *     config:       object,          // .aperant/config.json (empty {} if none)
+ *     profile:      'lite' | 'full-pipeline'
+ *                                    // derived from taskRecord.track:
+ *                                    //   QUICK | DEBUG    → 'lite'
+ *                                    //   STANDARD | DEEP  → 'full-pipeline'
+ *                                    //   null taskRecord  → 'full-pipeline'
+ *                                    //                       (fail-closed)
  *   }
  *
  * The builder is side-effect-free — it never writes state, never mutates the
@@ -24,6 +30,8 @@ import { createCoordinationStore } from '../coordination/store.mjs'
 
 const SAFE_TASK_ID_PATTERN = /^[a-zA-Z0-9_-]+$/
 
+const KNOWN_TRACKS = new Set(['QUICK', 'STANDARD', 'DEEP', 'DEBUG'])
+
 function readJsonIfExists(path) {
 	if (!existsSync(path)) return null
 	try {
@@ -81,6 +89,16 @@ export function buildGateContext(projectRoot, taskId) {
 		config = readJsonIfExists(join(absRoot, '.aperant', 'config.json')) ?? {}
 	}
 
+	if (taskRecord?.track && !KNOWN_TRACKS.has(taskRecord.track)) {
+		process.stderr.write(
+			`[apt:gate] WARNING: unrecognized track "${taskRecord.track}" — defaulting to full-pipeline. ` +
+				`Expected one of: ${[...KNOWN_TRACKS].join(', ')}.\n`,
+		)
+	}
+
+	const profile =
+		taskRecord?.track === 'QUICK' || taskRecord?.track === 'DEBUG' ? 'lite' : 'full-pipeline'
+
 	return {
 		projectRoot: absRoot,
 		sharedRoot,
@@ -88,5 +106,6 @@ export function buildGateContext(projectRoot, taskId) {
 		taskDir,
 		taskRecord,
 		config,
+		profile,
 	}
 }

package/src/cli/gate/gates/consistency-check.mjs

@@ -23,6 +23,7 @@ const gate = {
 	description: 'Cross-artifact consistency (spec/plan/review/qa/progress) has no error drift.',
 	severity: 'blocking',
 	skills: ['ship'],
+	applies_to_profile: (ctx) => ctx.profile === 'full-pipeline',
 	async check(ctx) {
 		const inputs = [
 			join(ctx.taskDir, 'spec.md'),

package/src/cli/gate/gates/review-clean.mjs

@@ -26,6 +26,7 @@ const gate = {
 	description: 'review.json has no unresolved critical/major findings (skipped if absent)',
 	severity: 'blocking',
 	skills: ['ship'],
+	applies_to_profile: (ctx) => ctx.profile === 'full-pipeline',
 	async check(ctx) {
 		const path = join(ctx.taskDir, 'review.json')
 		const inputs = [path]

package/src/cli/gate/gates/verify-approved.mjs

@@ -53,6 +53,7 @@ const gate = {
 		'qa_signoff.json exists with verdict === "approved" (or "approved-with-notes" when configured)',
 	severity: 'blocking',
 	skills: ['ship'],
+	applies_to_profile: (ctx) => ctx.profile === 'full-pipeline',
 	async check(ctx) {
 		const path = join(ctx.taskDir, 'qa_signoff.json')
 		const inputs = [path]

package/src/cli/gate/registry.mjs

@@ -10,7 +10,12 @@
  *     description: string,                // human-readable one-liner
  *     severity:    'blocking' | 'warn',   // blocking gates halt the skill
  *     skills:      string[],              // skills this gate fires for
- *     check:       async (ctx) => GateVerdict
+ *     check:       async (ctx) => GateVerdict,
+ *     applies_to_profile?: (ctx) => boolean // optional; when present and
+ *                                         // returns false, the gate is
+ *                                         // skipped before cache lookup or
+ *                                         // check() invocation. Omit to
+ *                                         // apply universally (default).
  *   }
  *
  * A GateVerdict is:
@@ -57,6 +62,11 @@ export function registerGate(gate) {
 	if (typeof gate.check !== 'function') {
 		throw new Error(`registerGate(${gate.id}): check must be a function`)
 	}
+	if (gate.applies_to_profile !== undefined && typeof gate.applies_to_profile !== 'function') {
+		throw new Error(
+			`registerGate(${gate.id}): applies_to_profile, when present, must be a function`,
+		)
+	}
 	registry.set(gate.id, gate)
 	return gate
 }

package/src/cli/install/find-workspace-framework-version.mjs

@@ -0,0 +1,88 @@
+/**
+ * install/find-workspace-framework-version.mjs — Bundle A.
+ *
+ * Locates the workspace `packages/framework/package.json` above `targetDir`
+ * so the SessionStart worker and `apt-tools check-version` can detect the
+ * "self-host contributor's workspace is ahead of the installed kernel" case
+ * WITHOUT requiring the user to remember the `--from-source` flag.
+ *
+ * Mirrors the bounded-walk + semver-validation contract of the route-side
+ * `detectSourceWorkspaceDrift` (route/drift-detect.mjs:32-107), but returns
+ * just the source workspace metadata — the caller decides whether to flip
+ * `update_available` (worker / check-version branch on the comparison).
+ *
+ * Safe for hot paths: synchronous, file-existence + JSON parse only,
+ * bounded walk (6 segments max), no network, no spawn.
+ *
+ * Security: workspace `package.json:version` is validated against the same
+ * `SEMVER_RE` as `update-chips.mjs` so a poisoned `package.json` cannot
+ * propagate a non-semver value into downstream envelopes.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { SEMVER_RE } from '../util/semver.mjs'
+
+/** Max directory frames to walk before giving up. Mirrors route/drift-detect.mjs:32. */
+const MAX_WALK_DEPTH = 6
+
+/**
+ * Walk up from `start`, returning every directory frame including `start`
+ * itself. Stops at the filesystem root or at depth `MAX_WALK_DEPTH`
+ * (whichever comes first).
+ *
+ * @param {string} start
+ * @returns {string[]}
+ */
+function walkUp(start) {
+	const frames = []
+	let cur = start
+	for (let i = 0; i < MAX_WALK_DEPTH; i++) {
+		frames.push(cur)
+		const parent = dirname(cur)
+		if (parent === cur) break
+		cur = parent
+	}
+	return frames
+}
+
+/**
+ * Find the workspace `@aperant/framework` package above `targetDir`.
+ *
+ * @param {string} targetDir  Absolute path to start the walk from.
+ * @returns {null | { source_path: string, source_version: string }}
+ *   `source_path` is the absolute path to `packages/framework/package.json`.
+ *   `source_version` is the semver-validated `version` field. Returns null
+ *   when no workspace package is found, when the workspace package name is
+ *   not `@aperant/framework`, or when the workspace version fails the
+ *   semver-shape check.
+ */
+export function findWorkspaceFrameworkVersion(targetDir) {
+	if (!targetDir || typeof targetDir !== 'string') return null
+
+	for (const dir of walkUp(targetDir)) {
+		const candidate = join(dir, 'packages', 'framework', 'package.json')
+		if (!existsSync(candidate)) continue
+
+		let pkg
+		try {
+			pkg = JSON.parse(readFileSync(candidate, 'utf-8'))
+		} catch {
+			continue
+		}
+
+		// Guard against false matches on unrelated monorepos that happen to
+		// have a `packages/framework/` directory.
+		if (pkg?.name !== '@aperant/framework') continue
+
+		const sourceVersion = pkg?.version
+		if (typeof sourceVersion !== 'string' || !SEMVER_RE.test(sourceVersion)) continue
+
+		return {
+			source_path: candidate,
+			source_version: sourceVersion,
+		}
+	}
+
+	return null
+}

package/src/cli/install/install-from-source.mjs

@@ -0,0 +1,276 @@
+/**
+ * install/install-from-source.mjs — Bundle D part 1.
+ *
+ * `apt-tools install-from-source <project-dir>` for the Aperant-contributor
+ * self-host case. Resolves the workspace `@aperant/framework` chain — packs
+ * the framework itself AND every `workspace:*` dependency (currently
+ * `@aperant/driver-sdk`, but the walker is general). Hands the full tarball
+ * list to a single `npm install --prefix` invocation so the same-PR
+ * unpublished-pair case stops blowing up with `EUNSUPPORTEDPROTOCOL`.
+ *
+ * Stable envelope:
+ *   { status: 'ok',     tarballs: string[], kernel_path: string }
+ *   { status: 'error',  error: string, ...optional context }
+ *
+ * Test seams: `APT_PNPM_BIN` + `APT_NPM_BIN` mirror the existing
+ * `install-kernel.mjs` + worker patterns.
+ */
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { err, ok } from '../util/result.mjs'
+import { findWorkspaceFrameworkVersion } from './find-workspace-framework-version.mjs'
+import { KERNEL_BIN_REL_PATH } from './install-kernel.mjs'
+
+/**
+ * Locate the monorepo root given the workspace framework package.json path.
+ * `<root>/packages/framework/package.json` → `<root>`.
+ *
+ * @param {string} frameworkPkgPath
+ * @returns {string}
+ */
+function monorepoRootFrom(frameworkPkgPath) {
+	// `<root>/packages/framework/package.json` — go up THREE levels.
+	return dirname(dirname(dirname(frameworkPkgPath)))
+}
+
+/**
+ * Scan `<monorepoRoot>/packages/` for a directory whose `package.json:name`
+ * matches `pkgName`. Returns the directory path (containing package.json),
+ * or null if no match.
+ *
+ * @param {string} monorepoRoot
+ * @param {string} pkgName
+ * @returns {string|null}
+ */
+function findWorkspacePackage(monorepoRoot, pkgName) {
+	const packagesDir = join(monorepoRoot, 'packages')
+	if (!existsSync(packagesDir)) return null
+	let entries
+	try {
+		entries = readdirSync(packagesDir, { withFileTypes: true })
+	} catch {
+		return null
+	}
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue
+		const candidate = join(packagesDir, entry.name, 'package.json')
+		if (!existsSync(candidate)) continue
+		try {
+			const pkg = JSON.parse(readFileSync(candidate, 'utf-8'))
+			if (pkg?.name === pkgName) return join(packagesDir, entry.name)
+		} catch {
+			// Skip unreadable package.json files.
+		}
+	}
+	return null
+}
+
+/**
+ * pnpm-pack a workspace package into `tmpDir` and return the resulting
+ * tarball path. Uses `pnpm --filter <name> pack --pack-destination <tmp>`
+ * so workspace protocols resolve to concrete versions inside the tarball.
+ *
+ * `knownBefore` is the set of .tgz filenames already present in `tmpDir`
+ * before this call; the mtime fallback uses it to find only the NEW file,
+ * avoiding coarse-timestamp ambiguity when multiple packs land in the same
+ * directory.
+ *
+ * @param {string} monorepoRoot
+ * @param {string} pkgName
+ * @param {string} tmpDir
+ * @param {Set<string>} knownBefore  Filenames (not paths) present before this pack.
+ * @returns {{ tarball: string } | { error: string }}
+ */
+function packWorkspace(monorepoRoot, pkgName, tmpDir, knownBefore) {
+	const pnpmBin = process.env.APT_PNPM_BIN || 'pnpm'
+	const result = spawnSync(pnpmBin, ['--filter', pkgName, 'pack', '--pack-destination', tmpDir], {
+		cwd: monorepoRoot,
+		stdio: ['ignore', 'pipe', 'pipe'],
+		encoding: 'utf-8',
+		timeout: 120_000,
+	})
+	if (result.error) {
+		return { error: `pnpm spawn failed for ${pkgName}: ${result.error.message}` }
+	}
+	if (result.status !== 0) {
+		const stderr = (result.stderr || '').trim().slice(-600)
+		return { error: `pnpm pack ${pkgName} exited with ${result.status}: ${stderr || 'no stderr'}` }
+	}
+	// pnpm pack prints the resulting tarball path on stdout. Take the last
+	// `.tgz` line (pnpm sometimes emits warnings above the path line).
+	const tarballLine = (result.stdout || '')
+		.split('\n')
+		.map((s) => s.trim())
+		.reverse()
+		.find((s) => s.endsWith('.tgz'))
+	if (tarballLine) {
+		// `tarballLine` may be a bare filename (older pnpm) or an absolute path.
+		// Use `isAbsolute` so Windows backslash + drive-letter paths are also
+		// recognized — `startsWith('/')` was POSIX-only.
+		const tarball = isAbsolute(tarballLine) ? tarballLine : join(tmpDir, tarballLine)
+		// SEC-001: containment check — tarball must resolve to a child of tmpDir.
+		const resolvedTmpDir = resolve(tmpDir)
+		const resolvedTarball = resolve(tarball)
+		if (!resolvedTarball.startsWith(`${resolvedTmpDir}/`) && resolvedTarball !== resolvedTmpDir) {
+			return { error: `pnpm pack ${pkgName}: tarball path escapes tmpDir: ${tarball}` }
+		}
+		return { tarball }
+	}
+	// Fall back to scanning tmpDir for the NEW tgz when stdout was
+	// uninformative (some pnpm builds print only progress to stderr).
+	// Use `knownBefore` to find only files added by this pack, avoiding
+	// mtime coarse-timestamp ambiguity on FAT32/network filesystems.
+	try {
+		for (const f of readdirSync(tmpDir)) {
+			if (!f.endsWith('.tgz')) continue
+			if (knownBefore.has(f)) continue
+			return { tarball: join(tmpDir, f) }
+		}
+	} catch {
+		// fall through
+	}
+	return {
+		error: `pnpm pack ${pkgName}: no .tgz produced (stdout: ${result.stdout?.slice(-200)})`,
+	}
+}
+
+/**
+ * `apt-tools install-from-source <project-dir>` — pack the workspace
+ * framework + every `workspace:*` dep, then npm-install the full tarball
+ * list into `<project-dir>/.aperant/deps/`.
+ *
+ * @param {string} projectDir
+ * @returns {import('../util/result.mjs').CommandResult}
+ */
+export function cmdInstallFromSource(projectDir) {
+	if (!projectDir) {
+		return err('Usage: apt-tools install-from-source <project-dir>')
+	}
+	const targetDir = resolve(projectDir)
+
+	const workspace = findWorkspaceFrameworkVersion(targetDir)
+	if (!workspace) {
+		return err('install-from-source: no @aperant/framework workspace found above project-dir')
+	}
+	const monorepoRoot = monorepoRootFrom(workspace.source_path)
+
+	// QUA-001: re-read the workspace package.json with a try/catch — the file
+	// was validated by findWorkspaceFrameworkVersion but could change between
+	// the two reads (active monorepo, contributor machine).
+	let frameworkPkg
+	try {
+		frameworkPkg = JSON.parse(readFileSync(workspace.source_path, 'utf-8'))
+	} catch (e) {
+		return err(
+			`install-from-source: failed to read ${workspace.source_path}: ${e instanceof Error ? e.message : String(e)}`,
+		)
+	}
+
+	// Enumerate workspace:* deps from dependencies + peerDependencies.
+	const depSources = [frameworkPkg.dependencies, frameworkPkg.peerDependencies]
+	const workspaceDeps = []
+	for (const block of depSources) {
+		if (!block || typeof block !== 'object') continue
+		for (const [name, spec] of Object.entries(block)) {
+			if (typeof spec === 'string' && spec.startsWith('workspace:')) {
+				if (!workspaceDeps.includes(name)) workspaceDeps.push(name)
+			}
+		}
+	}
+
+	// Resolve each workspace dep to its `packages/<dir>` path. Reject hard
+	// when any dep cannot be located — we cannot pack what we cannot find.
+	const missingDeps = []
+	const resolvedDeps = []
+	for (const depName of workspaceDeps) {
+		const pkgDir = findWorkspacePackage(monorepoRoot, depName)
+		if (!pkgDir) {
+			missingDeps.push(depName)
+			continue
+		}
+		resolvedDeps.push({ name: depName, dir: pkgDir })
+	}
+	if (missingDeps.length > 0) {
+		return err(
+			`install-from-source: workspace:* dep(s) not found in packages/: ${missingDeps.join(', ')}`,
+		)
+	}
+
+	// PRF-001: include framework in the same pack loop — eliminates structural
+	// duplication and ensures per-pack knownBefore snapshots work uniformly.
+	const packTargets = [...resolvedDeps.map((d) => d.name), '@aperant/framework']
+
+	// Pack everything into a fresh tmp dir so accumulated stale tarballs
+	// from prior runs don't sneak in.
+	const tmpDir = mkdtempSync(join(tmpdir(), 'apt-install-from-source-'))
+	const tarballs = []
+
+	// QUA-002: wrap pack+install in try/finally so tmpDir is always removed.
+	try {
+		for (const pkgName of packTargets) {
+			// LOG-003: snapshot existing tgz filenames before each pack so the
+			// fallback can identify exactly the new file, even on coarse-timestamp
+			// filesystems (FAT32, some network mounts).
+			const knownBefore = new Set()
+			try {
+				for (const f of readdirSync(tmpDir)) {
+					if (f.endsWith('.tgz')) knownBefore.add(f)
+				}
+			} catch {
+				// tmpDir unreadable — proceed with empty set; fallback will still work.
+			}
+			const packResult = packWorkspace(monorepoRoot, pkgName, tmpDir, knownBefore)
+			if ('error' in packResult) return err(packResult.error)
+			tarballs.push(packResult.tarball)
+		}
+
+		// npm install --prefix .aperant/deps <tarball1> <tarball2> ...
+		const depsDir = join(targetDir, '.aperant', 'deps')
+		mkdirSync(depsDir, { recursive: true })
+
+		const npmBin = process.env.APT_NPM_BIN || 'npm'
+		const args = [
+			'install',
+			'--prefix',
+			depsDir,
+			...tarballs,
+			'--no-save',
+			'--no-package-lock',
+			'--no-audit',
+			'--no-fund',
+			'--silent',
+		]
+		const npmResult = spawnSync(npmBin, args, {
+			cwd: targetDir,
+			stdio: ['ignore', 'pipe', 'pipe'],
+			encoding: 'utf-8',
+			timeout: 180_000,
+		})
+		if (npmResult.error) {
+			return err(`install-from-source: npm spawn failed: ${npmResult.error.message}`)
+		}
+		if (npmResult.status !== 0) {
+			const stderr = (npmResult.stderr || '').trim().slice(-600)
+			return err(
+				`install-from-source: npm install --prefix exited with ${npmResult.status}: ${stderr || 'no stderr'}`,
+			)
+		}
+
+		const kernelPath = join(targetDir, KERNEL_BIN_REL_PATH)
+		if (!existsSync(kernelPath)) {
+			return err(`install-from-source: npm reported success but kernel not found at ${kernelPath}`)
+		}
+
+		return ok({
+			status: 'ok',
+			command: 'install-from-source',
+			tarballs,
+			kernel_path: kernelPath,
+		})
+	} finally {
+		rmSync(tmpDir, { recursive: true, force: true })
+	}
+}

package/src/cli/install/install-kernel.mjs

@@ -120,6 +120,30 @@ export function installKernel(targetDir, version, opts = {}) {
 	const kernelPath = join(targetDir, KERNEL_BIN_REL_PATH)
 	const npmBin = resolveNpmBin()
 
+	// Bundle B — idempotency short-circuit. When the kernel package.json
+	// already reports the requested version AND the kernel binary exists,
+	// skip the npm spawn entirely. Returns the same `status: 'installed'`
+	// envelope shape that downstream consumers branch on (init.mjs:1441,
+	// init.mjs:1735, apt-update/SKILL.md Scenario D) — no new enum value
+	// per D-02.
+	const installedPkgPath = join(depsDir, 'node_modules', '@aperant', 'framework', 'package.json')
+	if (existsSync(installedPkgPath) && existsSync(kernelPath)) {
+		try {
+			const installedPkg = JSON.parse(readFileSync(installedPkgPath, 'utf-8'))
+			if (installedPkg?.version === version) {
+				return {
+					status: 'installed',
+					kernelPath,
+					reason: 'already at target version',
+					durationMs: 0,
+				}
+			}
+		} catch {
+			// Malformed package.json — fall through to the npm install path
+			// (npm will reconcile / repair).
+		}
+	}
+
 	const t0 = Date.now()
 	const args = [
 		'install',