@aperant/framework 0.8.0 → 0.8.4

package/skills/apt-zoom-out/SKILL.md

@@ -26,8 +26,8 @@ Tiny skill. High signal. The user named an area; you produce a one-page
 orientation so they (or a future agent) can plan or edit without
 re-learning the codebase from scratch.
 
-**Pocock adoption note.** This skill descends from Matt Pocock's `zoom-out`
-discipline. Aperant's router is dynamic and LLM-driven, so unlike Pocock's
+**Aperant adoption note.** This skill descends from 's `zoom-out`
+discipline. Aperant's router is dynamic and LLM-driven, so unlike 's
 upstream this skill is **router-invocable** (no `disable-model-invocation:
 true` flag). The work-intent — "give me a broader picture of X" — is
 genuine and the router resolves natural-language triggers without forcing
@@ -37,7 +37,7 @@ the user to remember the verb name.
 
 - Dropped into a new module / package / area of the monorepo
 - About to plan a feature that crosses an unfamiliar boundary
-- The codebase has CONTEXT.md (Pocock glossary) and you want to load it
+- The codebase has CONTEXT.md (Aperant glossary) and you want to load it
   alongside the structural map
 
 ## When Not to Use

package/src/cli/commands/adr.mjs

@@ -1,5 +1,5 @@
 /**
- * commands/adr.mjs — `apt-tools adr write` (Pocock adoption ST-6, AC5).
+ * commands/adr.mjs — `apt-tools adr write`.
  *
  * Writes an ADR under `docs/adr/NNNN-slug.md` ONLY when all three Nygard
  * gates pass: hard-to-reverse AND surprising-without-context AND

package/src/cli/commands/audit-branch-current.mjs

@@ -0,0 +1,250 @@
+/**
+ * commands/audit-branch-current.mjs — pre-PR rebase gate envelope for apt:ship §0.7.
+ *
+ * Pure read-only branch-drift audit. Given a base ref (default `main`), reports
+ * how many commits HEAD is ahead/behind `origin/<base>`, captures the current
+ * `origin/<base>` tip SHA (the lease target for any subsequent
+ * `--force-with-lease=refs/heads/<branch>:<sha>` push), and probes whether a
+ * trial merge against the remote tip would conflict.
+ *
+ * Single network call: `git fetch origin <base>`. Fetch failure is recovered
+ * as `audit_warning: 'fetch-failed'` — the envelope still returns, just with
+ * stale counts. No `git rebase`, no `git push`, no `git reset` — the SKILL.md
+ * prose owns history rewrites.
+ *
+ * Envelope:
+ *
+ *   {
+ *     status:             'ok',
+ *     command:            'audit-branch-current',
+ *     projectDir:         string,
+ *     base:               string,
+ *     ahead:              number,           // commits HEAD has over origin/<base>
+ *     behind:             number,           // commits origin/<base> has over HEAD
+ *     remote_tip_sha:     string | null,    // origin/<base> after fetch
+ *     mergeable:          boolean | null,   // null when probe unavailable
+ *     conflicts_preview?: string[],         // populated only when mergeable=false
+ *     audit_warning?:     string            // 'fetch-failed' | 'git-version-too-old' | ...
+ *   }
+ *
+ * Spec cross-ref: .aperant/tasks/apt-ship-pre-pr-rebase-gate-audit-branch_21-05-26/spec.md
+ *
+ * @internal
+ */
+
+import { execFileSync } from 'node:child_process'
+import { resolve } from 'node:path'
+import { err, ok } from '../util/result.mjs'
+
+/**
+ * Try-execute a git command, returning {ok, stdout, stderr, code}. Never throws.
+ *
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function gitTry(cwd, args) {
+	try {
+		const stdout = execFileSync('git', args, {
+			cwd,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'pipe'],
+		})
+		return { ok: true, stdout, stderr: '', code: 0 }
+	} catch (e) {
+		// execFileSync throws an error whose `stdout`, `stderr`, and `status`
+		// properties carry the captured output and exit code.
+		return {
+			ok: false,
+			stdout: typeof e?.stdout === 'string' ? e.stdout : (e?.stdout?.toString() ?? ''),
+			stderr: typeof e?.stderr === 'string' ? e.stderr : (e?.stderr?.toString() ?? ''),
+			code: typeof e?.status === 'number' ? e.status : 1,
+		}
+	}
+}
+
+/**
+ * Parse `--base <ref>` (or `--base=<ref>`) from extraArgs. Defaults to 'main'.
+ *
+ * @param {string[]} extraArgs
+ * @returns {string}
+ */
+function parseBaseFlag(extraArgs) {
+	for (let i = 0; i < extraArgs.length; i++) {
+		const a = extraArgs[i]
+		if (a === '--base' && i + 1 < extraArgs.length) return extraArgs[i + 1]
+		if (a.startsWith('--base=')) return a.slice('--base='.length)
+	}
+	return 'main'
+}
+
+/**
+ * Parse `git merge-tree --write-tree --no-messages HEAD origin/<base>` output
+ * for conflict file paths. Modern (git ≥ 2.38) merge-tree emits, on conflict:
+ *
+ *   <tree-OID>
+ *   <conflict report lines, each "<mode> <stage> <oid>\t<path>" for stage > 0>
+ *   (NUL separator)
+ *   <textual conflict messages>
+ *
+ * Older variants emit a `+<<<<<<< ... +======= ... +>>>>>>>` diff per file.
+ * For correctness we use the stable form: extract file paths from the conflict
+ * report. The report includes the SAME path multiple times (once per non-zero
+ * stage), so we de-dupe.
+ *
+ * @param {string} stdout
+ * @returns {string[]}
+ */
+function parseConflictPaths(stdout) {
+	const paths = new Set()
+	for (const rawLine of stdout.split('\n')) {
+		const line = rawLine.replace(/\0/g, '')
+		if (!line.trim()) continue
+		// Match "<mode> <oid> <stage>\t<path>" — git merge-tree --write-tree
+		// emits conflict report lines as "<mode> <oid> <stage>\t<path>".
+		// Stage 0 means no conflict, so we only surface stage ≥ 1.
+		const m = line.match(/^(\d{6})\s+([0-9a-f]{4,40})\s+(\d)\t(.+)$/)
+		if (m) {
+			const stage = Number.parseInt(m[3], 10)
+			if (stage >= 1) paths.add(m[4])
+			continue
+		}
+		// Fallback (older git): the textual report block prefixes paths with
+		// "CONFLICT (content): Merge conflict in <path>".
+		const c = line.match(/Merge conflict in (.+)$/)
+		if (c) paths.add(c[1].trim())
+	}
+	return Array.from(paths).sort()
+}
+
+/**
+ * Detect "git too old" from merge-tree stderr. Pre-2.38 git rejects
+ * `--write-tree` outright; older still rejects merge-tree's modern arg
+ * shape entirely. We treat any non-zero-with-no-output as "version too old"
+ * — callers are expected to fall back gracefully.
+ *
+ * @param {string} stderr
+ * @returns {boolean}
+ */
+function isGitVersionTooOld(stderr) {
+	return /unknown option|did you mean|usage: git merge-tree/i.test(stderr)
+}
+
+/**
+ * @param {string} projectDir
+ * @param {string[]} extraArgs
+ */
+export function auditBranchCurrent(projectDir, extraArgs = []) {
+	if (!projectDir) {
+		return err('Usage: apt-tools audit branch-current <project-dir> [--base <ref>]')
+	}
+	const targetDir = resolve(projectDir)
+	const base = parseBaseFlag(extraArgs)
+
+	/** @type {string | undefined} */
+	let auditWarning
+	/** @type {string[]} */
+	const warnings = []
+
+	// 1. Fetch origin <base>. Tolerate failure (offline, no remote, etc.).
+	const fetch = gitTry(targetDir, ['fetch', 'origin', base])
+	if (!fetch.ok) {
+		auditWarning = 'fetch-failed'
+		warnings.push(fetch.stderr.trim().split('\n').slice(0, 3).join(' | '))
+	}
+
+	// 2. Resolve origin/<base> tip.
+	let remoteTipSha = null
+	const tip = gitTry(targetDir, ['rev-parse', `origin/${base}`])
+	if (tip.ok) {
+		remoteTipSha = tip.stdout.trim()
+	} else {
+		// No origin/<base> ref at all — emit an envelope with null counts so the
+		// caller can recognise the gap. The SKILL.md prose treats null counts as
+		// "audit unavailable, STOP with a clear message" rather than proceeding.
+		return ok({
+			status: 'ok',
+			command: 'audit-branch-current',
+			projectDir: targetDir,
+			base,
+			ahead: null,
+			behind: null,
+			remote_tip_sha: null,
+			mergeable: null,
+			audit_warning: auditWarning ?? 'no-remote-base-ref',
+			warnings,
+		})
+	}
+
+	// 3. Counts.
+	let ahead = 0
+	let behind = 0
+	const aheadOut = gitTry(targetDir, ['rev-list', '--count', `origin/${base}..HEAD`])
+	const behindOut = gitTry(targetDir, ['rev-list', '--count', `HEAD..origin/${base}`])
+	if (aheadOut.ok) ahead = Number.parseInt(aheadOut.stdout.trim(), 10) || 0
+	if (behindOut.ok) behind = Number.parseInt(behindOut.stdout.trim(), 10) || 0
+
+	// 4. Mergeability.
+	//    - When behind === 0, the branch is current or strictly ahead — no
+	//      remote changes to integrate, mergeable = true by definition.
+	//    - When behind > 0 AND ahead === 0, the branch is strictly fast-forward
+	//      behind — a clean fast-forward rebase is always mergeable.
+	//    - When diverged (behind > 0 AND ahead > 0), probe via git merge-tree.
+	let mergeable
+	/** @type {string[] | undefined} */
+	let conflictsPreview
+	if (behind === 0) {
+		mergeable = true
+	} else if (behind > 0 && ahead === 0) {
+		mergeable = true
+	} else {
+		// Diverged. Run modern merge-tree trial.
+		const probe = gitTry(targetDir, [
+			'merge-tree',
+			'--write-tree',
+			'--no-messages',
+			'HEAD',
+			`origin/${base}`,
+		])
+		if (probe.ok) {
+			mergeable = true
+		} else if (probe.code === 1) {
+			// Documented merge-tree exit-code semantics: 0 clean, 1 conflict,
+			// other = invocation error.
+			mergeable = false
+			conflictsPreview = parseConflictPaths(probe.stdout)
+		} else if (isGitVersionTooOld(probe.stderr)) {
+			mergeable = null
+			auditWarning = auditWarning ?? 'git-version-too-old'
+			warnings.push(`git merge-tree --write-tree unsupported: ${probe.stderr.trim().slice(0, 200)}`)
+		} else {
+			// Unknown probe failure — treat as unknown rather than asserting
+			// clean.
+			mergeable = null
+			auditWarning = auditWarning ?? 'merge-tree-probe-failed'
+			warnings.push(
+				`git merge-tree probe failed (code ${probe.code}): ${probe.stderr.trim().slice(0, 200)}`,
+			)
+		}
+	}
+
+	const envelope = {
+		status: 'ok',
+		command: 'audit-branch-current',
+		projectDir: targetDir,
+		base,
+		ahead,
+		behind,
+		remote_tip_sha: remoteTipSha,
+		mergeable,
+	}
+	if (conflictsPreview && conflictsPreview.length > 0) {
+		envelope.conflicts_preview = conflictsPreview
+	}
+	if (auditWarning) envelope.audit_warning = auditWarning
+	if (warnings.length > 0) envelope.warnings = warnings
+	return ok(envelope)
+}
+
+// Test-only export for unit-level parser coverage (not part of the public CLI
+// contract).
+export { parseConflictPaths as __parseConflictPathsForTests }

package/src/cli/commands/audit.mjs

@@ -28,6 +28,14 @@
  *       committable bucket is non-empty after staging (CI-friendly gate).
  *       Default: report-only, exits 0 regardless.
  *
+ *   apt-tools audit branch-current <project-dir> [--base <ref>]
+ *       Pre-PR rebase gate envelope for apt:ship §0.7. Pure read-only:
+ *       `git fetch origin <base>`, captures origin/<base> tip SHA, counts
+ *       ahead/behind, and (when diverged) probes mergeability with
+ *       `git merge-tree --write-tree`. Returns {ahead, behind,
+ *       remote_tip_sha, mergeable, conflicts_preview?}. Never mutates
+ *       HEAD, the index, the worktree, or any remote ref.
+ *
  * Single source of truth: buildPolicyIgnoreMatcher in share-policy.mjs is
  * the ONLY matcher anywhere in the CLI. If you add a new taxonomy class or
  * toggle, update share-policy and this command follows automatically.
@@ -46,6 +54,7 @@ import { selfStageCommittableWrites } from '../artifacts/self-stage.mjs'
 import { buildPolicyIgnoreMatcher, resolveSharePolicy } from '../config/share-policy.mjs'
 import { detectPublicRemote } from '../git/remote.mjs'
 import { err, exitWith, ok } from '../util/result.mjs'
+import { auditBranchCurrent } from './audit-branch-current.mjs'
 
 /**
  * Dispatch an `audit <subcommand>` call.
@@ -59,7 +68,7 @@ import { err, exitWith, ok } from '../util/result.mjs'
 export function cmdAudit(subcommand, projectDir, extraArgs = []) {
 	if (!subcommand) {
 		return err(
-			'Usage: apt-tools audit <privacy|visibility-signals|pending-artifacts> <project-dir> [flags]',
+			'Usage: apt-tools audit <privacy|visibility-signals|pending-artifacts|branch-current> <project-dir> [flags]',
 		)
 	}
 	if (!projectDir) {
@@ -73,9 +82,11 @@ export function cmdAudit(subcommand, projectDir, extraArgs = []) {
 			return auditVisibilitySignals(targetDir)
 		case 'pending-artifacts':
 			return auditPendingArtifacts(targetDir, extraArgs)
+		case 'branch-current':
+			return auditBranchCurrent(targetDir, extraArgs)
 		default:
 			return err(
-				`Unknown audit subcommand: ${subcommand}. Expected 'privacy', 'visibility-signals', or 'pending-artifacts'.`,
+				`Unknown audit subcommand: ${subcommand}. Expected 'privacy', 'visibility-signals', 'pending-artifacts', or 'branch-current'.`,
 			)
 	}
 }

package/src/cli/commands/check-version.mjs

@@ -29,7 +29,13 @@
  *     // `framework_version` field (read from package.json, never from
  *     // the cache).
  *     framework: {
- *       latest_version: '0.6.7' | null
+ *       latest_version: '0.6.7' | null,
+ *       // Bundle A (0.8.3) — additive nullable field. Set when a workspace
+ *       // `packages/framework/package.json` is found above the project root
+ *       // and its `name === '@aperant/framework'`. When workspace_version
+ *       // is ahead of the running kernel, `update_available` flips true
+ *       // regardless of cache state (workspace wins on self-host).
+ *       workspace_version: '0.8.3' | null
  *     },
  *     update_available: false,
  *     dev_install_ahead: false,
@@ -48,11 +54,13 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { findWorkspaceFrameworkVersion } from '../install/find-workspace-framework-version.mjs'
 import { readManifest } from '../install/manifest.mjs'
 import { detectInstalledRuntimes } from '../install/runtime-detect.mjs'
 import { readFreshUpdateCache } from '../install/update-chips.mjs'
 import { inspectManifestFiles } from '../install/version-header.mjs'
 import { err, ok } from '../util/result.mjs'
+import { compareVersions } from '../util/semver.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -167,6 +175,16 @@ export function cmdCheckVersion(projectDir) {
 		if (typeof c.lookup_error === 'string') lookupError = c.lookup_error
 	}
 
+	// Bundle A — additive `framework.workspace_version` field. When the
+	// workspace package.json is ahead of the running kernel, flip
+	// `update_available` true regardless of cache state (the workspace is
+	// the source of truth on self-host). schema_version stays at 1 (D-01).
+	const workspace = findWorkspaceFrameworkVersion(targetDir)
+	const workspaceVersion = workspace?.source_version ?? null
+	if (workspaceVersion && compareVersions(workspaceVersion, frameworkVersion) > 0) {
+		updateAvailable = true
+	}
+
 	return ok({
 		status,
 		command: 'check-version',
@@ -178,6 +196,7 @@ export function cmdCheckVersion(projectDir) {
 		// file-header schema comment.
 		framework: {
 			latest_version: latestVersion,
+			workspace_version: workspaceVersion,
 		},
 		update_available: updateAvailable,
 		dev_install_ahead: devInstallAhead,

package/src/cli/commands/context.mjs

@@ -1,8 +1,8 @@
 /**
- * commands/context.mjs — `apt-tools context write` (Pocock adoption ST-5, AC4).
+ * commands/context.mjs — `apt-tools context write`.
  *
  * Upserts a term-block into the project's CONTEXT.md (the persistent
- * project glossary). Format ported from Pocock's CONTEXT-FORMAT.md
+ * project glossary). Format ported from the Aperant CONTEXT-FORMAT.md
  * (see packages/framework/templates/context-format.md for the MIT
  * attribution + field semantics).
  *
@@ -192,7 +192,7 @@ export function cmdContext(subcommand, projectDir, extraArgs) {
 	} else {
 		source = `${HEADER}\n\n${HEADER_NOTE}\n\n`
 	}
-	// Ensure the file starts with the header even if it existed pre-Pocock.
+	// Ensure the file starts with the header even if it existed pre-vertical-slice.
 	if (!source.startsWith(HEADER)) {
 		source = `${HEADER}\n\n${HEADER_NOTE}\n\n${source}`
 	}

package/src/cli/commands/detect-runtime.mjs

@@ -0,0 +1,134 @@
+/**
+ * commands/detect-runtime.mjs — `apt-tools detect-runtime <projectDir>`.
+ *
+ * Exposes runtime-detect.mjs at the CLI surface so adopters can preview
+ * which driver Aperant will pick for /apt:verify-proof.
+ *
+ * Returns:
+ *   { status: 'ok', command: 'detect-runtime', projectDir,
+ *     runtime: { is_electron, is_tauri, is_nextjs, is_web_frontend, ... },
+ *     selected_driver_id: string | null,
+ *     fallback_attempts: [{ driver_id, reason }] }
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { err, ok } from '../util/result.mjs'
+import { resolveDriver } from '../verify-proof/resolver.mjs'
+import { loadRuntimeCapabilities } from '../verify-proof/runtime-detect.mjs'
+
+/** Default required capabilities — the smallest set that proves a driver is usable. */
+const DEFAULT_REQUIRED_CAPABILITIES = ['screenshot']
+
+/**
+ * Discover every driver manifest bundled with @aperant/framework.
+ * @param {string} frameworkRoot — absolute path to packages/framework or .aperant/deps/.../@aperant/framework
+ * @returns {Array<object>}
+ */
+function discoverBundledDrivers(frameworkRoot) {
+	const dir = join(frameworkRoot, 'drivers')
+	if (!existsSync(dir)) return []
+	const manifests = []
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue
+		const manifestPath = join(dir, entry.name, 'manifest.json')
+		if (!existsSync(manifestPath)) continue
+		try {
+			const parsed = JSON.parse(readFileSync(manifestPath, 'utf-8'))
+			manifests.push({ ...parsed, locality: 'bundled' })
+		} catch {
+			/* skip malformed manifests */
+		}
+	}
+	return manifests
+}
+
+/**
+ * Discover every user-installed driver manifest at .aperant/drivers/.
+ * @param {string} projectDir
+ * @returns {Array<object>}
+ */
+function discoverUserDrivers(projectDir) {
+	const dir = join(projectDir, '.aperant/drivers')
+	if (!existsSync(dir)) return []
+	const manifests = []
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue
+		const manifestPath = join(dir, entry.name, 'manifest.json')
+		if (!existsSync(manifestPath)) continue
+		try {
+			const parsed = JSON.parse(readFileSync(manifestPath, 'utf-8'))
+			manifests.push({ ...parsed, locality: 'user' })
+		} catch {
+			/* skip malformed manifests */
+		}
+	}
+	return manifests
+}
+
+/**
+ * @param {string} projectDir
+ * @param {string[]} [_extra]
+ */
+export function cmdDetectRuntime(projectDir, _extra = []) {
+	if (!projectDir) return err('Usage: apt-tools detect-runtime <project-dir>')
+	const target = resolve(projectDir)
+
+	// Detect runtime capabilities from project's package.json.
+	const runtime = loadRuntimeCapabilities(target)
+
+	// Discover bundled + user drivers.
+	// __dirname-equivalent under ESM: walk up from this file to the framework
+	// package root. fileURLToPath is portable across POSIX + Windows;
+	// new URL(...).pathname returns '/C:/...' on Windows which resolve()
+	// does not handle correctly.
+	const frameworkRoot = fileURLToPath(new URL('../../..', import.meta.url))
+	const bundled = discoverBundledDrivers(frameworkRoot)
+	const user = discoverUserDrivers(target)
+	const drivers = [...bundled, ...user]
+
+	// Read user override from .aperant/config.json:verification.runtimes[].
+	let override = []
+	const configPath = join(target, '.aperant/config.json')
+	if (existsSync(configPath)) {
+		try {
+			const cfg = JSON.parse(readFileSync(configPath, 'utf-8'))
+			if (Array.isArray(cfg?.verification?.runtimes)) {
+				override = cfg.verification.runtimes.filter((x) => typeof x === 'string')
+			}
+		} catch {
+			/* malformed config — ignore */
+		}
+	}
+
+	// Try resolving with the default minimum required capability.
+	let selected = null
+	let fallback_attempts = []
+	try {
+		const result = resolveDriver({
+			drivers,
+			runtime,
+			required_capabilities: DEFAULT_REQUIRED_CAPABILITIES,
+			override,
+		})
+		selected = result.selected.driverId
+		fallback_attempts = result.fallback_attempts
+	} catch (resolveErr) {
+		fallback_attempts = resolveErr && Array.isArray(resolveErr.attempts) ? resolveErr.attempts : []
+	}
+
+	return ok({
+		status: 'ok',
+		command: 'detect-runtime',
+		projectDir: target,
+		runtime,
+		discovered_drivers: drivers.map((d) => ({
+			driverId: d.driverId,
+			version: d.version,
+			locality: d.locality,
+		})),
+		selected_driver_id: selected,
+		fallback_attempts,
+	})
+}