@aperant/framework 0.6.2

package/src/cli/commands/precompact-hook.mjs

@@ -0,0 +1,181 @@
+/**
+ * commands/precompact-hook.mjs — PreCompact hook installer + handler (C29).
+ *
+ * The installer-side merge logic now lives in install/claude-hooks.mjs so
+ * SessionStart and any future events can share it. This file owns the
+ * PreCompact-specific glue (command string + entry-identity substring) and
+ * the runtime PreCompact handler (cmdPrecompactHook).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { mergeClaudeHook } from '../install/claude-hooks.mjs'
+import { rawText } from '../util/result.mjs'
+
+/**
+ * Install or merge the apt-tools PreCompact hook into
+ * .claude/settings.local.json. Returns a short status string for the init
+ * output.
+ *
+ * The hook entry targets Claude Code's PreCompact event. When Claude Code is
+ * about to auto-compact (or a user runs /compact), it invokes registered
+ * PreCompact hooks; our hook emits task resume instructions that get injected
+ * into the compacted summary so the post-compact agent continues execution
+ * from build-progress.json instead of dying on a truncated summary.
+ *
+ * Per-developer, gitignored — hooks belong to the local dev environment
+ * because each collaborator may opt in or out.
+ */
+export function installPrecompactHook(projectDir) {
+	return mergeClaudeHook({
+		projectDir,
+		event: 'PreCompact',
+		matcher: '*',
+		command: 'node packages/framework/bin/apt-tools.mjs precompact-hook .',
+		identitySubstring: 'apt-tools.mjs precompact-hook',
+	})
+}
+
+/**
+ * Install the SessionStart hook that fires the apt-check-update worker.
+ * Coexists with PreCompact under settings.hooks.{PreCompact,SessionStart}.
+ */
+export function installSessionStartHook(projectDir) {
+	return mergeClaudeHook({
+		projectDir,
+		event: 'SessionStart',
+		matcher: '*',
+		command: 'node packages/framework/hooks/apt-check-update.js .',
+		identitySubstring: 'apt-check-update.js',
+	})
+}
+
+/**
+ * Claude Code PreCompact hook handler.
+ *
+ * Claude Code invokes registered PreCompact hooks right before it auto-compacts
+ * or manually compacts a conversation. Each hook receives a JSON object on stdin:
+ *
+ *   { hook_event_name: "PreCompact", trigger: "auto" | "manual",
+ *     custom_instructions: string | null, session_id, cwd, transcript_path, ... }
+ *
+ * Output protocol — plain stdout only. Claude Code's JSON hook schema whitelist
+ * exposes `hookSpecificOutput.additionalContext` for `UserPromptSubmit` and
+ * `PostToolUse` but NOT for `PreCompact`; emitting the nested envelope there
+ * fails schema validation and Claude Code drops the payload entirely (silent
+ * breakage — no task-resume context reaches the post-compact agent). The
+ * stable, documented path for PreCompact is plain text on stdout: Claude Code
+ * appends non-JSON hook stdout to the summarization prompt verbatim, which is
+ * exactly the behavior we need.
+ *
+ * What we emit:
+ *   - Active tasks from .aperant/state.json (task id, spec.md path, plan path,
+ *     progress path, current subtask).
+ *   - Resume instructions telling the post-compact agent: "re-read these files,
+ *     find the next pending subtask in the plan, and continue execution."
+ *
+ * Output is empty (no-op) when:
+ *   - No .aperant directory exists in cwd (not an Aperant project).
+ *   - state.json has no active tasks.
+ *   - The cwd is not inside an Aperant project root.
+ *
+ * Return shape (subtask 15): builds plain text and returns it via the
+ * `rawText` helper from util/result.mjs (`{ rawText, exitCode }`). The
+ * Layer 2 wrap() helper writes it through process.stdout.write and exits 0.
+ * No-op paths return `rawText('', 0)`.
+ */
+export function cmdPrecompactHook(projectDir) {
+	const targetDir = resolve(projectDir || process.cwd())
+	const aperantDir = join(targetDir, '.aperant')
+
+	// No-op: not an Aperant project.
+	if (!existsSync(aperantDir)) {
+		return rawText('', 0)
+	}
+
+	const statePath = join(aperantDir, 'state.json')
+	if (!existsSync(statePath)) {
+		return rawText('', 0)
+	}
+
+	let state
+	try {
+		state = JSON.parse(readFileSync(statePath, 'utf-8'))
+	} catch {
+		return rawText('', 0)
+	}
+
+	// Normalize active_task / active_tasks to a map.
+	let activeTasks = {}
+	if (state.active_tasks && typeof state.active_tasks === 'object') {
+		activeTasks = state.active_tasks
+	} else if (state.active_task) {
+		const oldId = state.active_task.id || 'legacy-task'
+		activeTasks = { [oldId]: state.active_task }
+	}
+
+	const taskIds = Object.keys(activeTasks)
+	if (taskIds.length === 0) {
+		return rawText('', 0)
+	}
+
+	// Drain stdin if piped — Claude Code pipes the hook payload to the hook.
+	// We don't need the content for our logic (cwd + state.json is enough),
+	// but leaving stdin unread can cause the parent to block on the pipe buffer.
+	try {
+		if (!process.stdin.isTTY) {
+			readFileSync(0, 'utf-8')
+		}
+	} catch {
+		// Ignore — stdin may not be piped in all invocation paths.
+	}
+
+	// Build the resume-instructions block.
+	const lines = []
+	lines.push('APERANT FRAMEWORK: you are mid-execution on one or more tasks. After compaction,')
+	lines.push('your previous in-memory state is gone — the source of truth is on disk.')
+	lines.push('')
+	lines.push(`Active tasks (${taskIds.length}):`)
+
+	for (const [taskId, task] of Object.entries(activeTasks)) {
+		// Resolve task_dir deterministically via getTaskDir() — the task object
+		// does not store its own directory path; it's always derived from id.
+		// Use project-relative path so the post-compact agent can Read it
+		// regardless of cwd changes.
+		const taskDir = join('.aperant', 'tasks', taskId)
+		// Real schema from cmdTask create: description, lifecycle_phase,
+		// progress.{subtasks_total, subtasks_completed, current_subtask}.
+		// Title/status are fallbacks for legacy or hand-edited state.
+		const description = task.description || task.title || taskId
+		const phase = task.lifecycle_phase || task.phase || task.status || 'active'
+		const progress = task.progress || {}
+		const total = progress.subtasks_total ?? 0
+		const completed = progress.subtasks_completed ?? 0
+		const currentSubtask = progress.current_subtask || task.current_subtask || 'unknown'
+
+		lines.push('')
+		lines.push(`  • ${taskId} — ${description}`)
+		lines.push(`    phase: ${phase}  (subtasks: ${completed}/${total})`)
+		lines.push(`    task_dir: ${taskDir}`)
+		lines.push(`    spec:     ${taskDir}/spec.md`)
+		lines.push(`    plan:     ${taskDir}/implementation_plan.json`)
+		lines.push(`    progress: ${taskDir}/build-progress.json`)
+		lines.push(`    last known subtask: ${currentSubtask}`)
+	}
+
+	lines.push('')
+	lines.push('TO RESUME (do this immediately after compaction, before anything else):')
+	lines.push('  1. Re-read implementation_plan.json AND build-progress.json for each active task.')
+	lines.push(
+		'  2. Find the first subtask with status="pending" whose dependencies are "completed".',
+	)
+	lines.push('  3. Continue executing from that subtask. Do NOT restart from the beginning.')
+	lines.push('  4. Do NOT ask the human to re-issue the task — checkpoint state is authoritative.')
+	lines.push('  5. If all subtasks are completed, run /apt:verify.')
+	lines.push('')
+	lines.push('This block is injected by the apt-tools PreCompact hook. It is how the Aperant')
+	lines.push('Framework survives auto-compact without bailing out to the human.')
+
+	// Plain text, not JSON — see function docstring for rationale.
+	return rawText(lines.join('\n') + '\n', 0)
+}

package/src/cli/commands/product-context.mjs

@@ -0,0 +1,77 @@
+/**
+ * commands/product-context.mjs — `apt-tools product-context <sub>` (C44).
+ *
+ * Thin wrapper over `design/product-context.mjs`. Current subcommands:
+ *
+ *   apt-tools product-context load [project-dir]
+ *     → prints the canonical JSON envelope:
+ *       {
+ *         status: 'ok' | 'error',
+ *         command: 'product-context-load',
+ *         path: '<abs path to .aperant/product-context.json>',
+ *         present: true | false,
+ *         source: 'aperant-file' | 'none',
+ *         productContext: { ... } | null,
+ *         errors: [string, ...],
+ *         warnings: [string, ...]
+ *       }
+ *     Exits 1 when `errors.length > 0`.
+ *
+ * Future subcommands (`validate`, `show`) layer onto the same dispatch
+ * shape. This module is intentionally framework-read-only: the app writes
+ * `.aperant/product-context.json` via `saveProjectContextForContext` and
+ * the framework consumes it. No LLM calls, no network.
+ */
+
+import { resolve as resolvePath } from 'node:path'
+import { loadProductContext } from '../design/product-context.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+
+/**
+ * @param {string | undefined} subcommand
+ * @param {string[] | undefined} extraArgs  positional + flags after the subcommand
+ */
+export function cmdProductContext(subcommand, extraArgs) {
+	if (!subcommand) {
+		return err(
+			'apt-tools product-context: missing subcommand. Usage: apt-tools product-context load [project-dir]',
+		)
+	}
+
+	switch (subcommand) {
+		case 'load':
+			return cmdLoad(extraArgs ?? [])
+		default:
+			return err(`apt-tools product-context: unknown subcommand "${subcommand}". Known: load`)
+	}
+}
+
+/**
+ * @param {string[]} args
+ */
+function cmdLoad(args) {
+	// First non-flag positional is the project dir. Default: process.cwd().
+	const positional = args.filter((a) => !a.startsWith('--'))
+	const projectDirArg = positional[0]
+	const projectDir = resolvePath(
+		process.cwd(),
+		projectDirArg && projectDirArg.length > 0 ? projectDirArg : '.',
+	)
+
+	const res = loadProductContext(projectDir)
+
+	const hasErrors = res.errors.length > 0
+
+	const envelope = {
+		status: hasErrors ? 'error' : 'ok',
+		command: 'product-context-load',
+		path: res.path,
+		present: res.present,
+		source: res.source,
+		productContext: res.productContext,
+		errors: res.errors,
+		warnings: res.warnings,
+	}
+
+	return hasErrors ? exitWith(envelope, 1) : ok(envelope)
+}

package/src/cli/commands/profile.mjs

@@ -0,0 +1,122 @@
+/**
+ * commands/profile.mjs — `apt-tools profile <list|resolve|validate>` (C19).
+ *
+ * Mirrors commands/constitution.mjs: subcommand dispatch + JSON envelope via
+ * util/io.mjs:output + util/args.mjs:parseFlags. Read-only for v1 — no write
+ * subcommands.
+ *
+ *   apt-tools profile list <project-dir>
+ *     → { status, command: 'profile-list', count, profiles: [...] }
+ *
+ *   apt-tools profile validate <project-dir> --name <n>
+ *     → { status: 'ok'|'fail', command: 'profile-validate', name, chain?, reason?, errors? }
+ *
+ *   apt-tools profile resolve <project-dir> --name <n>
+ *     → { status: 'ok'|'fail', command: 'profile-resolve', name, chain?, resolved?, reason?, errors? }
+ */
+
+import { listProfiles } from '../profile/parse.mjs'
+import { resolveProfile } from '../profile/resolve.mjs'
+import { parseFlags } from '../util/args.mjs'
+import { err, ok, UsageError } from '../util/result.mjs'
+
+/**
+ * Sentinel error class for helper-level usage failures inside cmdProfile.
+ * The dispatcher catches it and converts it into the standard err() envelope.
+ */
+class ProfileUsageError extends UsageError {
+	constructor(message) {
+		super(message)
+		this.name = 'ProfileUsageError'
+	}
+}
+
+export async function cmdProfile(subcommand, projectDir, extraArgs) {
+	if (!subcommand) {
+		return err('Usage: apt-tools profile <list|resolve|validate> [project-dir] [flags]')
+	}
+	try {
+		switch (subcommand) {
+			case 'list':
+				return cmdProfileList(projectDir, extraArgs ?? [])
+			case 'validate':
+				return cmdProfileValidate(projectDir, extraArgs ?? [])
+			case 'resolve':
+				return cmdProfileResolve(projectDir, extraArgs ?? [])
+			default:
+				return err(`Unknown profile subcommand: ${subcommand}. Expected: list, validate, resolve`)
+		}
+	} catch (e) {
+		if (e instanceof ProfileUsageError) return err(e.message)
+		throw e
+	}
+}
+
+function cmdProfileList(projectDir, _extraArgs) {
+	if (!projectDir) throw new ProfileUsageError('Usage: apt-tools profile list <project-dir>')
+	const profiles = listProfiles(projectDir)
+	return ok({
+		status: 'ok',
+		command: 'profile-list',
+		count: profiles.length,
+		profiles,
+	})
+}
+
+function cmdProfileValidate(projectDir, extraArgs) {
+	if (!projectDir)
+		throw new ProfileUsageError('Usage: apt-tools profile validate <project-dir> --name <n>')
+	const flags = parseFlags(extraArgs)
+	const name = flags.get('name')
+	if (!name || typeof name !== 'string')
+		throw new ProfileUsageError('Required: --name <profile-name>')
+
+	// validate = resolve + discard the merged output. Cycle / depth / dangling
+	// extends / schema failures all surface through resolveProfile's failure
+	// shape, so we share one code path for both `validate` and `resolve`.
+	const result = resolveProfile(projectDir, name)
+	if (!result.ok) {
+		return ok({
+			status: 'fail',
+			command: 'profile-validate',
+			name,
+			reason: result.reason,
+			errors: result.errors,
+			chain: result.chain,
+		})
+	}
+	return ok({
+		status: 'ok',
+		command: 'profile-validate',
+		name,
+		chain: result.chain,
+	})
+}
+
+function cmdProfileResolve(projectDir, extraArgs) {
+	if (!projectDir)
+		throw new ProfileUsageError('Usage: apt-tools profile resolve <project-dir> --name <n>')
+	const flags = parseFlags(extraArgs)
+	const name = flags.get('name')
+	if (!name || typeof name !== 'string')
+		throw new ProfileUsageError('Required: --name <profile-name>')
+
+	const result = resolveProfile(projectDir, name)
+	if (!result.ok) {
+		return ok({
+			status: 'fail',
+			command: 'profile-resolve',
+			name,
+			reason: result.reason,
+			errors: result.errors,
+			chain: result.chain,
+		})
+	}
+	return ok({
+		status: 'ok',
+		command: 'profile-resolve',
+		name,
+		chain: result.chain,
+		resolved: result.resolved,
+	})
+}

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

@@ -0,0 +1,85 @@
+/**
+ * commands/risk-check.mjs — risk-check command (C29).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { classifyPath } from '../risk/globs.mjs'
+import { err, ok } from '../util/result.mjs'
+
+/** Risk ordering: Safe(0) < Normal(1) < Elevated(2) < Critical(3) < Destructive(4) */
+const RISK_ORDER = { Safe: 0, Normal: 1, Elevated: 2, Critical: 3, Destructive: 4 }
+
+/** Destructive operation types that override path-based classification */
+const DESTRUCTIVE_OPS = new Set(['delete', 'remove-dep', 'drop-table', 'force-push'])
+
+export function cmdRiskCheck(projectDir, extraArgs) {
+	if (!projectDir) {
+		return err('Usage: apt-tools risk-check <project-dir> --paths <p1> [--operation <type>]')
+	}
+
+	const targetDir = resolve(projectDir)
+
+	// Parse --paths
+	const pathsIdx = extraArgs.indexOf('--paths')
+	if (pathsIdx < 0) {
+		return err('Usage: apt-tools risk-check <project-dir> --paths <p1> [--operation <type>]')
+	}
+
+	// Collect paths until we hit another flag or end of args
+	const filePaths = []
+	for (let i = pathsIdx + 1; i < extraArgs.length; i++) {
+		if (extraArgs[i].startsWith('--')) break
+		filePaths.push(extraArgs[i])
+	}
+
+	if (filePaths.length === 0) {
+		return err('No file paths provided after --paths')
+	}
+
+	// Parse --operation
+	const opIdx = extraArgs.indexOf('--operation')
+	const operationType = opIdx >= 0 ? extraArgs[opIdx + 1] || null : null
+
+	// Read config
+	const configPath = join(targetDir, '.aperant', 'config.json')
+	let riskMap = { critical_paths: [], elevated_paths: [], safe_paths: [] }
+	if (existsSync(configPath)) {
+		try {
+			const config = JSON.parse(readFileSync(configPath, 'utf-8'))
+			if (config.risk_map) riskMap = config.risk_map
+		} catch {
+			/* use defaults */
+		}
+	}
+
+	// Classify each path
+	const matchedPaths = filePaths.map((fp) => {
+		const result = classifyPath(fp, riskMap)
+		return { path: fp, risk_class: result.risk_class, matched_pattern: result.matched_pattern }
+	})
+
+	// Find highest risk from path classification (start at lowest possible)
+	let highestRisk = matchedPaths[0].risk_class
+	let highestPattern = matchedPaths[0].matched_pattern
+	for (let i = 1; i < matchedPaths.length; i++) {
+		const mp = matchedPaths[i]
+		if (RISK_ORDER[mp.risk_class] > RISK_ORDER[highestRisk]) {
+			highestRisk = mp.risk_class
+			highestPattern = mp.matched_pattern
+		}
+	}
+
+	// Destructive operation override (D-11)
+	if (operationType && DESTRUCTIVE_OPS.has(operationType)) {
+		highestRisk = 'Destructive'
+		highestPattern = `operation:${operationType}`
+	}
+
+	return ok({
+		risk_class: highestRisk,
+		matched_pattern: highestPattern,
+		matched_paths: matchedPaths,
+		operation_type: operationType,
+	})
+}