@aperant/framework 0.6.2

package/src/cli/config/gitignore-drift.mjs

@@ -0,0 +1,94 @@
+/**
+ * gitignore-drift.mjs — dispatch-time warning when `.aperant/.gitignore`
+ * on disk no longer matches the content `buildAperantGitignoreTemplate`
+ * would emit for the project's current share policy (C34a).
+ *
+ * Non-blocking: never fails the command, never mutates exit code, never
+ * modifies the file. Single stderr line if drift is detected. Skipped for
+ * hot-path / machine-readable commands so router-style stdout stays clean.
+ *
+ * Silenced by `APT_SUPPRESS_GITIGNORE_DRIFT=1` for scripts + tests.
+ *
+ * @internal — consumed only from bin/apt-tools.mjs dispatch.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveSharePolicy } from './share-policy.mjs'
+import { buildAperantGitignoreTemplate } from './upgrade-gitignore.mjs'
+
+/**
+ * Commands that read machine-readable output or run on every turn. Their
+ * stderr feeds back into the LLM-facing router / detectors; a chatty drift
+ * warning would pollute the signal and flip exit-code-adjacent flags.
+ */
+const SKIP_COMMANDS = new Set([
+	'route',
+	'detect-project',
+	'detect-worktree',
+	'health-check',
+	'toolchain-detect',
+	'host-detect',
+	'--version',
+	'--help',
+	'-v',
+	'-h',
+])
+
+/**
+ * Pure comparison primitive — returns whether the on-disk `.aperant/.gitignore`
+ * differs from the policy-expected template. Returns `{ drifted: false }` when
+ * the `.aperant/` dir or file is absent (nothing to compare).
+ *
+ * @internal
+ */
+export function checkGitignoreDrift(projectRoot) {
+	const aperantDir = join(projectRoot, '.aperant')
+	if (!existsSync(aperantDir)) return { drifted: false, reason: 'no-aperant-dir' }
+	const gitignorePath = join(aperantDir, '.gitignore')
+	if (!existsSync(gitignorePath)) return { drifted: false, reason: 'no-gitignore' }
+
+	let config = {}
+	const configPath = join(aperantDir, 'config.json')
+	if (existsSync(configPath)) {
+		try {
+			config = JSON.parse(readFileSync(configPath, 'utf-8'))
+		} catch {
+			/* malformed config → treat as empty (solo defaults) */
+		}
+	}
+	const policy = resolveSharePolicy(config)
+	const expected = buildAperantGitignoreTemplate(policy)
+	let actual = ''
+	try {
+		actual = readFileSync(gitignorePath, 'utf-8')
+	} catch {
+		return { drifted: false, reason: 'read-failed' }
+	}
+	return { drifted: actual !== expected, reason: null }
+}
+
+/**
+ * Dispatch-time hook. Emits the drift warning on stderr if:
+ *   - `APT_SUPPRESS_GITIGNORE_DRIFT` is not `1`
+ *   - `command` is not in the hot-path allowlist
+ *   - `.aperant/.gitignore` exists AND does not match the expected template
+ *
+ * Never throws.
+ *
+ * @internal
+ */
+export function emitDriftWarningIfAny(projectRoot, command) {
+	try {
+		if (process.env.APT_SUPPRESS_GITIGNORE_DRIFT === '1') return
+		if (!command || SKIP_COMMANDS.has(command)) return
+		const { drifted } = checkGitignoreDrift(projectRoot)
+		if (drifted) {
+			process.stderr.write(
+				'[apt-tools] warning: .aperant/.gitignore is out of sync with share policy — run `apt-tools config upgrade-gitignore . --dry-run` to see the diff.\n',
+			)
+		}
+	} catch {
+		/* never block user command on drift check */
+	}
+}

package/src/cli/config/guard.mjs

@@ -0,0 +1,39 @@
+/**
+ * @internal
+ * config/guard.mjs — gate .aperant/config.json writes behind a whitelist (R13).
+ *
+ * Today the only callers that legitimately write config.json are `init`
+ * (fresh install) and `setup` (`/apt:setup` customization). Every other
+ * subsystem reads config.json. Installing the rail now lets us catch it the
+ * moment a new code path tries to mutate config without registering as a
+ * sanctioned writer — the duplicate-edit race observed alongside the C29
+ * leak (worktree and main repo both flipping worktree_per_task concurrently)
+ * is exactly the failure mode this guard blocks.
+ *
+ * The APT_CONFIG_WRITER_OVERRIDE env var lets tests drive the guard without
+ * taking on the whitelist surface. It is NOT documented in the CLI help.
+ */
+
+/** @internal */
+export const ALLOWED_CONFIG_WRITERS = new Set(['init', 'setup'])
+
+/**
+ * Throw if `callerId` is not an approved config writer. Accepts the env
+ * override for test harnesses that need to exercise the write path without
+ * impersonating one of the sanctioned callers.
+ *
+ * @internal
+ */
+export function assertConfigWriteAllowed(callerId) {
+	const override = process.env.APT_CONFIG_WRITER_OVERRIDE
+	if (override && override === callerId) return
+	if (override && override === '*') return
+	if (!ALLOWED_CONFIG_WRITERS.has(callerId)) {
+		const err = new Error(
+			`config-write-forbidden: '${callerId}' is not an approved writer for .aperant/config.json. Allowed: ${[...ALLOWED_CONFIG_WRITERS].join(', ')}`,
+		)
+		err.code = 'config-write-forbidden'
+		err.caller = callerId
+		throw err
+	}
+}

package/src/cli/config/load.mjs

@@ -0,0 +1,151 @@
+/**
+ * config/load.mjs — project config loader + task-isolation normalizer (C29).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { cliToInstallRoot } from '../install/cli-to-install-root.mjs'
+
+/**
+ * Load `.aperant/config.json` if present. Returns null if missing/malformed.
+ */
+export function loadProjectConfig(targetDir) {
+	const configPath = join(targetDir, '.aperant', 'config.json')
+	if (!existsSync(configPath)) return null
+	try {
+		return JSON.parse(readFileSync(configPath, 'utf-8'))
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Return a normalized task_isolation config object with safe fallbacks.
+ * Always returns a concrete object even when the project has no config at all,
+ * so callers can treat this as the single source of truth for isolation flags.
+ */
+export function getTaskIsolationConfig(projectDir) {
+	const defaults = {
+		worktree_per_task: false,
+		branch_prefix: 'apt',
+		from_branch: 'current',
+		push_on_create: true,
+		cleanup_on_close: 'ask',
+		// C54 — language-agnostic worktree bootstrap. All off by default so
+		// existing users (any project without `task_isolation.bootstrap_worktree`
+		// in config) see zero behavior change.
+		bootstrap_worktree: false,
+		max_parallel_installs: 2,
+		skip_bootstrap_for: [],
+		install_registry_allowlist: null, // null ⇒ use hardcoded manifest-scanner defaults
+		bootstrap_cmd: null, // custom install command (string[] argv); null ⇒ auto-detect
+	}
+	const config = loadProjectConfig(resolve(projectDir))
+	const user = config?.task_isolation || {}
+	// Allow pipeline.branch_prefix to act as the default when task_isolation
+	// doesn't specify its own — mirrors how /apt:ship already reads pipeline.
+	if (!user.branch_prefix && config?.pipeline?.branch_prefix) {
+		user.branch_prefix = config.pipeline.branch_prefix
+	}
+	return { ...defaults, ...user }
+}
+
+const __filename = fileURLToPath(import.meta.url)
+// packages/framework/src/cli/config/load.mjs → packages/framework
+const FRAMEWORK_ROOT = resolve(dirname(__filename), '..', '..', '..')
+
+/**
+ * Resolve the allowlist of trusted skill sources — spec §2.5 + subtask 7.
+ *
+ * When `.aperant/config.json` carries `trusted_skill_sources: [...]` the
+ * user value wins (typically used to allowlist a private skill marketplace
+ * clone). When absent we compute safe defaults:
+ *
+ *   1. <framework-repo>/skills                    (dev checkout)
+ *   2. <targetDir>/packages/framework/skills      (monorepo dev)
+ *   3. <targetDir>/.aperant/deps/node_modules/@aperant/framework/skills
+ *                                                 (consumer install)
+ *   4. <targetDir>/<cli-install-root>/skills      (currently-detected runtime)
+ *
+ * Any non-existent entry is pruned — the caller never has to existsSync().
+ *
+ * @param {string} projectDir
+ * @param {string} [cli]  result of detectHost().cli ('claude-code', etc.)
+ * @returns {string[]}    absolute paths, de-duplicated, order-preserving
+ */
+export function getTrustedSkillSources(projectDir, cli) {
+	const targetDir = resolve(projectDir)
+	const config = loadProjectConfig(targetDir)
+	const configured = Array.isArray(config?.trusted_skill_sources)
+		? config.trusted_skill_sources
+		: null
+
+	if (configured && configured.length > 0) {
+		// SEC-001: Relative paths are resolved against targetDir and then checked
+		// for containment — a relative path with "../" components could otherwise
+		// escape the project root and point at arbitrary filesystem locations. Only
+		// paths that resolve INSIDE targetDir are accepted as relative entries;
+		// paths that escape are rejected with a clear error so the failure is not
+		// silent.
+		//
+		// Absolute paths are accepted as-is (they represent legitimate use cases
+		// such as a shared skill marketplace clone or a framework install outside
+		// the project root). The attack surface for absolute paths is the same as
+		// for any other `config.json` mutation — if an attacker can write
+		// `config.json`, they can already inject skills directly. The real attack
+		// vector SEC-001 is guarding against is the subtle relative-path escape
+		// (e.g. `"../../../etc/evil"`).
+		const resolved = []
+		for (const p of configured) {
+			if (isAbsolute(p)) {
+				resolved.push(resolve(p))
+			} else {
+				const abs = resolve(targetDir, p)
+				const rel = relative(targetDir, abs)
+				if (rel.startsWith('..') || isAbsolute(rel)) {
+					throw new Error(
+						`trusted_skill_sources relative entry "${p}" escapes the project directory ` +
+							`"${targetDir}" (resolves to "${abs}"). ` +
+							'Relative paths must not use "../" components that walk above the project root. ' +
+							'Use an absolute path to reference a skill source outside the project.',
+					)
+				}
+				resolved.push(abs)
+			}
+		}
+		return resolved.filter((p, i, arr) => arr.indexOf(p) === i)
+	}
+
+	const defaults = []
+	// 1. Framework repo's own skills dir (what this process runs from)
+	const frameworkSkills = join(FRAMEWORK_ROOT, 'skills')
+	if (existsSync(frameworkSkills)) defaults.push(frameworkSkills)
+	// 2. Monorepo dev: packages/framework/skills under targetDir
+	const monorepoSkills = join(targetDir, 'packages', 'framework', 'skills')
+	if (monorepoSkills !== frameworkSkills && existsSync(monorepoSkills)) {
+		defaults.push(monorepoSkills)
+	}
+	// 3. Consumer install: pulled in via .aperant/deps
+	const consumerSkills = join(
+		targetDir,
+		'.aperant',
+		'deps',
+		'node_modules',
+		'@aperant',
+		'framework',
+		'skills',
+	)
+	if (existsSync(consumerSkills)) defaults.push(consumerSkills)
+	// 4. Host CLI's installed runtime skills — only when the router knows
+	// which runtime it's in. Some hosts (codex, claude-code) install into
+	// .codex/skills / .claude/skills etc; the router picks skills from
+	// the host-local directory so per-runtime transforms are honored.
+	const installRoot = cli ? cliToInstallRoot(cli) : null
+	if (installRoot) {
+		const runtimeSkills = join(targetDir, installRoot, 'skills')
+		if (existsSync(runtimeSkills)) defaults.push(runtimeSkills)
+	}
+
+	return defaults.filter((p, i, arr) => arr.indexOf(p) === i)
+}

package/src/cli/config/post-merge-sweep.mjs

@@ -0,0 +1,280 @@
+/**
+ * post-merge-sweep.mjs — dispatch-time passive sweeper for stuck
+ * `shipped-pending-merge` tasks (C57 Piece 2).
+ *
+ * AI agents ship a PR and walk away. Tasks then rot in
+ * `shipped-pending-merge` because nothing automatic invokes
+ * `apt-tools task close-merged`. This hook runs on every `apt-tools`
+ * dispatch (mirroring the gitignore-drift hook), checks a set of
+ * fast preflights, and — at most once every 10 minutes per repo —
+ * spawns a detached child to poll `gh pr view` and close any tasks
+ * whose PRs have terminally landed.
+ *
+ * Non-blocking: never fails the command, never mutates exit code,
+ * never throws. Single stderr line on actual sweep kick (not on
+ * every dispatch).
+ *
+ * Silenced by `APT_SUPPRESS_MERGE_SWEEP=1`. Skipped when
+ * `APT_INTERNAL_MERGE_SWEEP=1` is set in env (recursion guard for
+ * the spawned child's own dispatch loop).
+ *
+ * @internal — consumed only from bin/apt-tools.mjs dispatch.
+ */
+
+import { spawn } from 'node:child_process'
+import { closeSync, existsSync, openSync, readFileSync, statSync, writeSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Hot-path commands whose stderr feeds back into LLM-facing routers /
+ * detectors — chatty hook output would pollute classification signal.
+ *
+ * Plus `task` — so a `task close-merged` invocation does NOT re-trigger
+ * the sweep on its own dispatch (recursion guard #1).
+ */
+const SKIP_COMMANDS = new Set([
+	'route',
+	'detect-project',
+	'detect-worktree',
+	'health-check',
+	'toolchain-detect',
+	'host-detect',
+	'task', // recursion guard #1 — close-merged is a `task` subcommand
+	'--version',
+	'--help',
+	'-v',
+	'-h',
+])
+
+/**
+ * Cooldown window between sweep kicks, in milliseconds. Tasks that
+ * just shipped won't be merged in seconds — so polling more than
+ * once per 10 minutes wastes `gh pr view` rate budget. Configurable
+ * via `MERGE_SWEEP_COOLDOWN_MS` env var (mostly for tests).
+ */
+const DEFAULT_COOLDOWN_MS = 600_000 // 10 minutes
+
+function getCooldownMs() {
+	const raw = process.env.MERGE_SWEEP_COOLDOWN_MS
+	if (!raw) return DEFAULT_COOLDOWN_MS
+	const n = Number.parseInt(raw, 10)
+	return Number.isFinite(n) && n > 0 ? n : DEFAULT_COOLDOWN_MS
+}
+
+/**
+ * Pure preflight — returns the list of `shipped-pending-merge` task IDs
+ * whose `pr_url` is set. Returns `null` if state can't be read or no
+ * candidates exist (the dispatcher uses `null` as the short-circuit).
+ *
+ * @internal
+ */
+export function readShippedCandidates(projectRoot) {
+	const statePath = join(projectRoot, '.aperant', 'state.json')
+	if (!existsSync(statePath)) return null
+	let state
+	try {
+		state = JSON.parse(readFileSync(statePath, 'utf-8'))
+	} catch {
+		return null
+	}
+	const active = state?.active_tasks
+	if (!active || typeof active !== 'object') return null
+	const candidates = []
+	for (const [id, t] of Object.entries(active)) {
+		if (!t || typeof t !== 'object') continue
+		if (t.lifecycle_phase !== 'shipped-pending-merge') continue
+		if (!t.pr_url) continue
+		candidates.push({ id, pr_url: t.pr_url, worktree_path: t.worktree_path || null })
+	}
+	return candidates.length === 0 ? null : candidates
+}
+
+/**
+ * Returns true if the cooldown lock is "fresh" (last sweep too recent).
+ * Lock content is `{pid}:{ms-since-epoch}` but we only consult mtime.
+ *
+ * @internal
+ */
+export function isCooldownActive(lockPath, cooldownMs = getCooldownMs()) {
+	if (!existsSync(lockPath)) return false
+	try {
+		const st = statSync(lockPath)
+		return Date.now() - st.mtimeMs < cooldownMs
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Best-effort lease writer. Atomic enough for our needs (the lock
+ * itself is the cooldown token, not a critical-section guard — the
+ * destructive side effects all run in the detached child via the
+ * existing `task close-merged → task close` pipeline).
+ *
+ * @internal
+ */
+export function writeSweepLease(lockPath) {
+	try {
+		const fd = openSync(lockPath, 'w')
+		try {
+			writeSync(fd, `${process.pid}:${Date.now()}\n`)
+		} finally {
+			closeSync(fd)
+		}
+		return true
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Filter out candidates whose worktree contains the current cwd —
+ * sweeping into your own active worktree would pull the rug out from
+ * under you. Returns the deferred IDs alongside the kept ones.
+ *
+ * @internal
+ */
+export function partitionByCwd(candidates, cwd) {
+	const kept = []
+	const deferred = []
+	for (const c of candidates) {
+		if (c.worktree_path && cwd.startsWith(c.worktree_path)) {
+			deferred.push(c.id)
+		} else {
+			kept.push(c)
+		}
+	}
+	return { kept, deferred }
+}
+
+/**
+ * Resolve the absolute path to `bin/apt-tools.mjs`. The hook lives in
+ * `src/cli/config/`, the dispatcher in `bin/`. Same package, same install.
+ *
+ * @internal
+ */
+function resolveAptToolsBin() {
+	const here = dirname(fileURLToPath(import.meta.url))
+	// src/cli/config → ../../../bin/apt-tools.mjs
+	return resolve(here, '..', '..', '..', 'bin', 'apt-tools.mjs')
+}
+
+/**
+ * Spawn the detached close-merged child. Sets `APT_INTERNAL_MERGE_SWEEP=1`
+ * in env so the child's own dispatch hook doesn't recurse.
+ *
+ * Returns the child's PID on success, null on spawn failure.
+ *
+ * @internal
+ */
+export function spawnDetachedSweep(projectRoot, options = {}) {
+	const bin = options.binPath || resolveAptToolsBin()
+	try {
+		const child = spawn('node', [bin, 'task', 'close-merged', projectRoot], {
+			cwd: projectRoot,
+			env: {
+				...process.env,
+				APT_INTERNAL_MERGE_SWEEP: '1',
+			},
+			detached: true,
+			stdio: 'ignore',
+		})
+		child.unref()
+		return child.pid ?? null
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Dispatch-time hook. Runs through:
+ *   1. Suppression env → return.
+ *   2. Recursion-guard env → return.
+ *   3. SKIP_COMMANDS allowlist → return.
+ *   4. Read shipped-pending-merge candidates (no lock, fast). None → return.
+ *   5. Cooldown check via lease-file mtime → return if too recent.
+ *   6. Filter out candidates whose worktree contains cwd. All deferred → return.
+ *   7. Write lease (cooldown token).
+ *   8. Spawn detached `task close-merged <root>` child with recursion-guard env.
+ *   9. Print one stderr line so the user knows the sweep fired.
+ *
+ * Never throws. Returns `{ kicked, reason }` for tests; production callers
+ * wrap in try/catch and ignore.
+ *
+ * @internal
+ */
+export function maybeSweepShippedMergedTasks(projectRoot, command, options = {}) {
+	try {
+		if (process.env.APT_SUPPRESS_MERGE_SWEEP === '1') {
+			return { kicked: false, reason: 'suppressed' }
+		}
+		// Recursion guard #2 — child sets this so its own dispatcher noops.
+		if (process.env.APT_INTERNAL_MERGE_SWEEP === '1') {
+			return { kicked: false, reason: 'internal-recursion-guard' }
+		}
+		if (!command || SKIP_COMMANDS.has(command)) {
+			return { kicked: false, reason: 'skip-command' }
+		}
+		const root = resolve(projectRoot)
+		if (!existsSync(join(root, '.aperant'))) {
+			return { kicked: false, reason: 'no-aperant-dir' }
+		}
+
+		const candidates = readShippedCandidates(root)
+		if (!candidates) {
+			return { kicked: false, reason: 'no-candidates' }
+		}
+
+		const lockPath = join(root, '.aperant', '.merge-sweep.lock')
+		const cooldownMs = options.cooldownMs ?? getCooldownMs()
+		if (isCooldownActive(lockPath, cooldownMs)) {
+			return { kicked: false, reason: 'cooldown' }
+		}
+
+		const cwd = options.cwd ?? process.cwd()
+		const { kept, deferred } = partitionByCwd(candidates, cwd)
+		if (kept.length === 0) {
+			return {
+				kicked: false,
+				reason: 'all-deferred-by-cwd',
+				deferred,
+			}
+		}
+
+		// Acquire the cooldown lease. If we can't write it, skip — better
+		// to noop than to potentially fire two sweeps in quick succession.
+		if (!writeSweepLease(lockPath)) {
+			return { kicked: false, reason: 'lease-write-failed' }
+		}
+
+		// Spawn the detached child. The actual close work happens in the
+		// child via the existing `task close-merged` command, which already
+		// handles offline / rate-limit / unmerged-but-not-MERGED behavior.
+		const pid = options.spawnFn
+			? options.spawnFn(root)
+			: spawnDetachedSweep(root, { binPath: options.binPath })
+		if (pid === null) {
+			return { kicked: false, reason: 'spawn-failed' }
+		}
+
+		try {
+			process.stderr.write(
+				`[apt-tools] Auto-sweeping ${kept.length} pending PR(s) — run 'apt-tools task close-merged --dry-run' to preview, or APT_SUPPRESS_MERGE_SWEEP=1 to silence.\n`,
+			)
+		} catch {
+			/* stderr write failure is non-fatal */
+		}
+
+		return {
+			kicked: true,
+			reason: 'spawned',
+			pid,
+			candidate_count: kept.length,
+			deferred,
+		}
+	} catch {
+		// Belt-and-suspenders: never block user command on the sweep hook.
+		return { kicked: false, reason: 'hook-error' }
+	}
+}