@aperant/framework 0.6.2

package/src/cli/commands/docs-audit.mjs

@@ -0,0 +1,159 @@
+/**
+ * commands/docs-audit.mjs — CLI entry point for the docs-coherence audit (C33).
+ *
+ * Used by:
+ *   - `/apt:review` Pass 6 (spec §In scope #3)
+ *   - Standalone debugging (`apt-tools docs-audit .`)
+ *   - CI pre-commit (`docs-audit . --format json | jq '.findings | length'`)
+ *
+ * Flags:
+ *   --diff-files <csv>    explicit CSV of diff files (deleted/renamed inferred from git)
+ *   --since <ref>         compute diff from <ref>..HEAD via `git diff --name-status`
+ *   --dry-run             skip git invocations entirely (empty diffFacts)
+ *   --policy <path>       path to an override policy JSON (testing hook)
+ *   --format json|md      output format (default json)
+ */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { auditDocsDrift } from '../docs-audit/audit.mjs'
+import { loadDocsPolicy } from '../docs-audit/policy.mjs'
+import { parseFlags } from '../util/args.mjs'
+import { err, ok, UsageError } from '../util/result.mjs'
+
+/**
+ * Sentinel error class for helper-level usage failures inside cmdDocsAudit.
+ * The dispatcher catches it and converts it into the standard err() envelope.
+ */
+class DocsAuditUsageError extends UsageError {
+	constructor(message) {
+		super(message)
+		this.name = 'DocsAuditUsageError'
+	}
+}
+
+export async function cmdDocsAudit(projectDir, extraArgs) {
+	if (!projectDir) return err('Usage: apt-tools docs-audit <project-dir> [flags]')
+	const root = resolve(projectDir)
+	const flags = parseFlags(extraArgs)
+	const format = (flags.get('format') || 'json').toLowerCase()
+
+	let policy
+	try {
+		policy = resolvePolicy(root, flags)
+	} catch (e) {
+		if (e instanceof DocsAuditUsageError) return err(e.message)
+		throw e
+	}
+	const diffFacts = resolveDiffFacts(root, flags)
+
+	const result = await auditDocsDrift({ projectDir: root, policy, diffFacts })
+
+	const payload = {
+		status: 'ok',
+		command: 'docs-audit',
+		findings: result.findings,
+		patch_plan: result.patch_plan,
+		dropped: result.dropped,
+	}
+	if (format === 'md') {
+		payload.markdown = renderMarkdown(result)
+	}
+	return ok(payload)
+}
+
+function resolvePolicy(root, flags) {
+	const overridePath = flags.get('policy')
+	if (overridePath) {
+		try {
+			const raw = JSON.parse(readFileSync(resolve(overridePath), 'utf-8'))
+			return raw
+		} catch (e) {
+			throw new DocsAuditUsageError(
+				`docs-audit: could not load --policy from ${overridePath}: ${e.message}`,
+			)
+		}
+	}
+	return loadDocsPolicy(root)
+}
+
+function resolveDiffFacts(root, flags) {
+	if (flags.has('dry-run')) {
+		return { deletedPaths: [], renamedPaths: [], addedExports: [], removedExports: [] }
+	}
+	const explicit = flags.get('diff-files')
+	if (explicit && typeof explicit === 'string') {
+		// Treat each entry as a candidate deleted path. Without git access we
+		// can't distinguish deletions from mere changes, but the grep engine
+		// only false-positives on benign in-prose mentions — it still succeeds.
+		return {
+			deletedPaths: explicit
+				.split(',')
+				.map((s) => s.trim())
+				.filter(Boolean),
+			renamedPaths: [],
+			addedExports: [],
+			removedExports: [],
+		}
+	}
+	if (!existsSync(resolve(root, '.git'))) {
+		return { deletedPaths: [], renamedPaths: [], addedExports: [], removedExports: [] }
+	}
+	try {
+		const since = flags.get('since')
+		const args = since
+			? ['diff', '--name-status', `${since}..HEAD`]
+			: ['diff', 'HEAD', '--name-status']
+		const out = execFileSync('git', args, {
+			cwd: root,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+		return parseNameStatus(out)
+	} catch {
+		return { deletedPaths: [], renamedPaths: [], addedExports: [], removedExports: [] }
+	}
+}
+
+function parseNameStatus(raw) {
+	const deletedPaths = []
+	const renamedPaths = []
+	for (const line of raw.split('\n')) {
+		const t = line.trim()
+		if (!t) continue
+		// Format: "D\tpath"   or   "R100\told\tnew"
+		const parts = t.split('\t').filter(Boolean)
+		const code = parts[0]
+		if (code?.startsWith('D') && parts[1]) {
+			deletedPaths.push(parts[1])
+		} else if (code?.startsWith('R') && parts[1] && parts[2]) {
+			renamedPaths.push({ from: parts[1], to: parts[2] })
+		}
+	}
+	return { deletedPaths, renamedPaths, addedExports: [], removedExports: [] }
+}
+
+function renderMarkdown(result) {
+	const out = ['### Docs-coherence audit', '']
+	if (result.findings.length === 0 && result.patch_plan.length === 0) {
+		out.push('_No docs-drift detected._')
+		return out.join('\n')
+	}
+	if (result.findings.length > 0) {
+		out.push('**Findings (flag-drift):**')
+		for (const f of result.findings) {
+			out.push(
+				`- \`${f.file}:${f.line}\` — ${f.stale_claim} (${f.confidence})` +
+					(f.suggested_rewrite ? ` → \`${f.suggested_rewrite}\`` : ''),
+			)
+		}
+	}
+	if (result.patch_plan.length > 0) {
+		out.push('', '**Patch plan (auto-update):**')
+		for (const p of result.patch_plan) {
+			out.push(`- \`${p.file}:${p.line}\` — ${p.stale_claim}`)
+		}
+	}
+	return out.join('\n')
+}

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

@@ -0,0 +1,108 @@
+/**
+ * commands/edit-check.mjs — ACI edit-check parse gate (C29).
+ *
+ * Layer 1 (post-CLI-layering refactor, subtask 13). cmdEditCheck returns
+ * { envelope, exitCode } — every fail() site became return err().
+ */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { extname } from 'node:path'
+import { err, ok } from '../util/result.mjs'
+
+export function cmdEditCheck(args) {
+	const path = args[0]
+	if (!path) return err('Usage: apt-tools edit-check <path>')
+	if (!existsSync(path)) return err(`File not found: ${path}`)
+	const ext = extname(path).toLowerCase()
+	const content = readFileSync(path, 'utf-8')
+	const lines = content.split('\n').length
+
+	// JSON: strict parse
+	if (ext === '.json') {
+		try {
+			JSON.parse(content)
+			return ok({ status: 'ok', command: 'edit-check', path, check: 'json-parse', lines })
+		} catch (e) {
+			return err(`JSON parse failed: ${e.message}`)
+		}
+	}
+
+	// JS/MJS/CJS: node --check
+	if (['.js', '.mjs', '.cjs'].includes(ext)) {
+		try {
+			execFileSync('node', ['--check', path], { stdio: 'pipe' })
+			return ok({ status: 'ok', command: 'edit-check', path, check: 'node-syntax', lines })
+		} catch (e) {
+			const msg = e.stderr ? String(e.stderr).slice(0, 500) : e.message
+			return err(`Syntax check failed: ${msg}`)
+		}
+	}
+
+	// TS/TSX/JSX: structural check (balanced braces + no obvious truncation
+	// markers). Full type check is out-of-scope for edit-check — that's what
+	// verify runs later.
+	if (['.ts', '.tsx', '.jsx'].includes(ext)) {
+		const stack = []
+		const pairs = { '}': '{', ')': '(', ']': '[' }
+		let inString = null
+		let inLineComment = false
+		let inBlockComment = false
+		let prev = ''
+		for (let i = 0; i < content.length; i++) {
+			const c = content[i]
+			if (inLineComment) {
+				if (c === '\n') inLineComment = false
+				prev = c
+				continue
+			}
+			if (inBlockComment) {
+				if (prev === '*' && c === '/') inBlockComment = false
+				prev = c
+				continue
+			}
+			if (inString) {
+				if (c === inString && prev !== '\\') inString = null
+				prev = c
+				continue
+			}
+			if (c === '/' && prev === '/') {
+				inLineComment = true
+				prev = c
+				continue
+			}
+			if (c === '*' && prev === '/') {
+				inBlockComment = true
+				prev = c
+				continue
+			}
+			if (c === '"' || c === "'" || c === '`') {
+				inString = c
+				prev = c
+				continue
+			}
+			if ('{(['.includes(c)) stack.push(c)
+			else if (')]}'.includes(c)) {
+				if (stack.pop() !== pairs[c])
+					return err(`Structural check failed: unmatched '${c}' at offset ${i}`)
+			}
+			prev = c
+		}
+		if (stack.length !== 0)
+			return err(`Structural check failed: ${stack.length} unclosed bracket(s)`)
+		if (/\.\.\.\s*(truncated|rest of file|omitted)/i.test(content)) {
+			return err('Structural check failed: truncation marker detected')
+		}
+		return ok({ status: 'ok', command: 'edit-check', path, check: 'ts-structural', lines })
+	}
+
+	// Other file types (md, css, etc.) — no check, just report.
+	return ok({
+		status: 'ok',
+		command: 'edit-check',
+		path,
+		check: 'none',
+		lines,
+		note: 'no checker for this file type',
+	})
+}

package/src/cli/commands/effects.mjs

@@ -0,0 +1,415 @@
+/**
+ * commands/effects.mjs — pending-effects outbox (record/list/ack/drain/clear) (C29).
+ *
+ * The outbox is the low-volume authoritative event queue: agents append
+ * structured entries, a drainer replays them into canonical apt-tools paths.
+ * Storage: .aperant/pending-effects.jsonl (one JSON entry per line).
+ * Concurrency: every read/write goes through withFileLock on the file itself.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { findMilestoneScopeGlobal, loadRoadmapForScope } from '../roadmap/io.mjs'
+import { applyLifecyclePhaseSideEffect } from '../roadmap/lifecycle.mjs'
+import { parseFlags } from '../util/args.mjs'
+import { withFileLock } from '../util/fs-lock.mjs'
+import { err, ok, rawText } from '../util/result.mjs'
+
+function effectsPath(projectDir) {
+	return join(resolve(projectDir), '.aperant', 'pending-effects.jsonl')
+}
+
+function readEffects(filePath) {
+	if (!existsSync(filePath)) return []
+	const raw = readFileSync(filePath, 'utf-8')
+	const out = []
+	for (const line of raw.split('\n')) {
+		const trimmed = line.trim()
+		if (!trimmed) continue
+		try {
+			out.push(JSON.parse(trimmed))
+		} catch {
+			// Skip corrupt lines silently — record/ack rewrite the file so
+			// corruption self-heals on the next mutation.
+		}
+	}
+	return out
+}
+
+function writeEffects(filePath, entries) {
+	mkdirSync(dirname(filePath), { recursive: true })
+	const body = entries.map((e) => JSON.stringify(e)).join('\n')
+	const tmpPath = filePath + '.tmp.' + process.pid
+	writeFileSync(tmpPath, entries.length === 0 ? '' : body + '\n', 'utf-8')
+	renameSync(tmpPath, filePath)
+}
+
+function generateEffectId() {
+	const ts = Date.now().toString(36)
+	const rand = Math.random().toString(36).slice(2, 8)
+	return `ef-${ts}-${rand}`
+}
+
+export function cmdEffects(subcommand, projectDir, extraArgs) {
+	if (!subcommand)
+		return err(
+			'Usage: apt-tools effects <record|list|ack|drain|pending-count|clear> <project-dir> [flags]',
+		)
+	if (!projectDir) return err('Usage: apt-tools effects ' + subcommand + ' <project-dir> [flags]')
+
+	const filePath = effectsPath(projectDir)
+	const flags = parseFlags(extraArgs)
+
+	switch (subcommand) {
+		case 'record': {
+			const op = flags.get('op')
+			const agent = flags.get('agent')
+			const mode = flags.get('mode') || ''
+			const affectsRaw = flags.get('affects') || ''
+			const contextRaw = flags.get('context') || ''
+
+			if (!op) return err('Required: --op <operation-name>')
+			if (!agent) return err('Required: --agent <agent-type>')
+
+			const affects = affectsRaw
+				? affectsRaw
+						.split(',')
+						.map((s) => s.trim())
+						.filter(Boolean)
+				: []
+
+			let context = {}
+			if (contextRaw) {
+				try {
+					context = JSON.parse(contextRaw)
+				} catch (e) {
+					return err(`Invalid JSON for --context: ${e.message}`)
+				}
+			}
+
+			const entry = {
+				id: generateEffectId(),
+				op,
+				agent,
+				mode,
+				affects,
+				context,
+				created_at: new Date().toISOString(),
+				attempts: 0,
+			}
+
+			withFileLock(
+				filePath,
+				() => {
+					const entries = readEffects(filePath)
+					entries.push(entry)
+					writeEffects(filePath, entries)
+				},
+				{ projectRoot: resolve(projectDir) },
+			)
+
+			return ok({ status: 'ok', command: 'effects-record', id: entry.id, entry })
+		}
+
+		case 'list': {
+			const format = flags.get('format') || 'text'
+			const entries = withFileLock(filePath, () => readEffects(filePath), {
+				projectRoot: resolve(projectDir),
+			})
+
+			if (format === 'json') {
+				return ok({ status: 'ok', command: 'effects-list', count: entries.length, entries })
+			}
+			// Raw-text path: build the human-readable string and route through
+			// wrap()'s rawText shape (subtask 15) — no JSON envelope wrapper.
+			// (Subtask 20: replaces the legacy `process.stdout.write + return
+			// undefined` pattern that depended on wrap()'s now-deleted
+			// legacy-tolerance branch.)
+			let text
+			if (entries.length === 0) {
+				text = 'No pending effects.\n'
+			} else {
+				const lines = [`${entries.length} pending effect(s):`, '']
+				for (const e of entries) {
+					lines.push(`  ${e.id}`)
+					lines.push(`    op:      ${e.op}`)
+					lines.push(`    agent:   ${e.agent}`)
+					if (e.mode) lines.push(`    mode:    ${e.mode}`)
+					if (e.affects.length) lines.push(`    affects: ${e.affects.join(', ')}`)
+					lines.push(`    created: ${e.created_at}`)
+					lines.push('')
+				}
+				text = `${lines.join('\n')}`
+			}
+			return rawText(text, 0)
+		}
+
+		case 'pending-count': {
+			const entries = withFileLock(filePath, () => readEffects(filePath), {
+				projectRoot: resolve(projectDir),
+			})
+			return ok({ status: 'ok', command: 'effects-pending-count', count: entries.length })
+		}
+
+		case 'ack': {
+			const id = flags.get('id')
+			if (!id) return err('Required: --id <effect-id>')
+
+			let removed = null
+			let unknown = false
+			withFileLock(
+				filePath,
+				() => {
+					const entries = readEffects(filePath)
+					const idx = entries.findIndex((e) => e.id === id)
+					if (idx === -1) {
+						// Tolerate unknown ids so drain retries and concurrent
+						// drainers are safe. The caller pattern-matches on
+						// status:ok and can inspect `removed`/`note` to detect
+						// the no-op.
+						unknown = true
+						return
+					}
+					removed = entries.splice(idx, 1)[0]
+					writeEffects(filePath, entries)
+				},
+				{ projectRoot: resolve(projectDir) },
+			)
+			if (unknown) {
+				return ok({
+					status: 'ok',
+					command: 'effects-ack',
+					id,
+					removed: null,
+					note: 'unknown-id',
+				})
+			}
+			return ok({ status: 'ok', command: 'effects-ack', id, removed })
+		}
+
+		case 'clear': {
+			withFileLock(filePath, () => writeEffects(filePath, []), { projectRoot: resolve(projectDir) })
+			return ok({ status: 'ok', command: 'effects-clear' })
+		}
+
+		case 'drain': {
+			const targetDir = resolve(projectDir)
+			const dryRun = extraArgs.includes('--dry-run')
+			const verbose = extraArgs.includes('--verbose')
+			const limitRaw = flags.get('limit')
+			const limit = limitRaw ? Math.max(0, parseInt(limitRaw, 10) || 0) : 0
+
+			// ── Op contract (authoritative, pure JS state machine) ───────────
+			// Every op lives in one of three buckets:
+			//   - ack-only:     no mutation, drop from queue
+			//   - phase-trans:  (now empty) — lifecycle phase transitions moved
+			//                   to `task update --lifecycle-phase` and `task
+			//                   close --verdict approved`, which call the shared
+			//                   `applyLifecyclePhaseSideEffect` helper inline.
+			//   - decision:     append to decisions ledger
+			// The unknown-op ack-only fallback below silently absorbs any
+			// legacy `task.*.start` / `task.*.complete` entries left in an
+			// in-flight queue on upgrade, so this change is forward-compatible.
+			const ACK_ONLY_OPS = new Set(['roadmap.render'])
+			const PHASE_TRANSITIONS = {}
+
+			const transitions = []
+			const commits = []
+			let drained = 0
+			let failed = 0
+			let parked = 0
+
+			function logv(msg) {
+				if (verbose) process.stderr.write(`[effects-drain] ${msg}\n`)
+			}
+
+			function resolveScopeForEntry(entry) {
+				const ctx = entry.context || {}
+				if (ctx.scope) return ctx.scope
+				if (ctx.milestone_id) return findMilestoneScopeGlobal(targetDir, ctx.milestone_id)
+				return null
+			}
+
+			function applyPhaseTransition(entry, spec) {
+				const ctx = entry.context || {}
+				const scope = resolveScopeForEntry(entry)
+				if (!scope) {
+					logv(`  ${entry.op}: no scope (missing linkage) — no-op`)
+					return null
+				}
+				if (!ctx.milestone_id || !ctx.phase_id) {
+					logv(`  ${entry.op}: missing milestone_id/phase_id — no-op`)
+					return null
+				}
+				// Delegate to the shared helper. It mirrors the legacy behavior —
+				// from-state guard, saveRoadmapForScope, syncRoadmapInProcess — and
+				// returns null on any no-op branch. We just add verbose logging
+				// around the delegation so `--verbose` drains keep reading like the
+				// old inlined flow.
+				const task = {
+					scope,
+					milestone_id: ctx.milestone_id,
+					phase_id: ctx.phase_id,
+				}
+				const result = applyLifecyclePhaseSideEffect(targetDir, task, spec, entry.op, {
+					dryRun,
+				})
+				if (!result) {
+					// Re-derive the diagnostic the old inlined version printed.
+					const roadmap = loadRoadmapForScope(targetDir, scope)
+					if (!roadmap) {
+						logv(`  ${entry.op}: no roadmap for scope "${scope}" — no-op`)
+					} else {
+						const milestone = (roadmap.milestones || []).find((m) => m.id === ctx.milestone_id)
+						if (!milestone) {
+							logv(`  ${entry.op}: milestone "${ctx.milestone_id}" not found — no-op`)
+						} else {
+							const phase = (milestone.phases || []).find((p) => p.id === ctx.phase_id)
+							if (!phase) {
+								logv(`  ${entry.op}: phase "${ctx.phase_id}" not found — no-op`)
+							} else if (phase.status !== spec.from) {
+								logv(
+									`  ${entry.op}: phase "${ctx.phase_id}" status="${phase.status}" (expected "${spec.from}") — no-op`,
+								)
+							}
+						}
+					}
+					return null
+				}
+				if (result.commit) commits.push(result.commit)
+				return result.transition
+			}
+
+			function applyDecisionRecorded(entry) {
+				const ctx = entry.context || {}
+				const indexPath = join(targetDir, '.aperant', 'decisions', 'INDEX.md')
+				const taskId = ctx.task_id || '-'
+				const source = entry.mode || '-'
+				const summary = (ctx.summary || 'decision recorded').replace(/\|/g, '\\|')
+				const artifactPath = ctx.artifact_path || '-'
+				const date = new Date().toISOString().slice(0, 10)
+				const row = `| ${date} | ${taskId} | ${source} | ${summary} | ${artifactPath} |`
+
+				if (dryRun) return
+
+				mkdirSync(dirname(indexPath), { recursive: true })
+				let body
+				if (existsSync(indexPath)) {
+					body = readFileSync(indexPath, 'utf-8')
+					// Idempotent: dedupe by (task_id, artifact_path) pair.
+					const dedupeKey = `| ${taskId} |`
+					const artifactKey = `| ${artifactPath} |`
+					const existingLines = body.split('\n')
+					const hit = existingLines.find((l) => l.includes(dedupeKey) && l.includes(artifactKey))
+					if (hit) {
+						logv(`  decision.recorded: already in ledger — no-op`)
+						return
+					}
+					if (!body.endsWith('\n')) body += '\n'
+					body += row + '\n'
+				} else {
+					body =
+						'# Decisions Ledger\n\n| Date | Task | Source | Summary | Artifact |\n|---|---|---|---|---|\n'
+					body += row + '\n'
+				}
+				writeFileSync(indexPath, body, 'utf-8')
+			}
+
+			// ── Drain loop under the effects-file lock ──────────────────────
+			withFileLock(
+				filePath,
+				() => {
+					const entries = readEffects(filePath)
+					const remaining = []
+					const deadQueue = []
+
+					const budget = limit > 0 ? Math.min(limit, entries.length) : entries.length
+
+					for (let i = 0; i < entries.length; i++) {
+						const entry = entries[i]
+						if (i >= budget) {
+							// --limit: leave the rest in the queue for the next pass.
+							remaining.push(entry)
+							continue
+						}
+						logv(`processing ${entry.id} op=${entry.op}`)
+						try {
+							if (ACK_ONLY_OPS.has(entry.op)) {
+								drained += 1
+								continue
+							}
+							const transSpec = PHASE_TRANSITIONS[entry.op]
+							if (transSpec) {
+								const t = applyPhaseTransition(entry, transSpec)
+								if (t) transitions.push(t)
+								drained += 1
+								continue
+							}
+							if (entry.op === 'decision.recorded') {
+								applyDecisionRecorded(entry)
+								drained += 1
+								continue
+							}
+							// Unknown op — ack and move on (forward-compat).
+							logv(`  unknown op "${entry.op}" — ack-only`)
+							drained += 1
+						} catch (err) {
+							failed += 1
+							const attempts = (entry.attempts || 0) + 1
+							entry.attempts = attempts
+							entry.last_error = String(err && err.message ? err.message : err)
+							if (attempts >= 3) {
+								parked += 1
+								deadQueue.push({
+									...entry,
+									error: entry.last_error,
+									parked_at: new Date().toISOString(),
+								})
+								logv(`  parked after ${attempts} attempts: ${entry.last_error}`)
+							} else {
+								remaining.push(entry)
+								logv(`  retry queued (attempt ${attempts}/3): ${entry.last_error}`)
+							}
+						}
+					}
+
+					if (dryRun) {
+						// --dry-run: report but do not persist drained/parked state.
+						return
+					}
+
+					writeEffects(filePath, remaining)
+
+					if (deadQueue.length > 0) {
+						const deadPath = join(targetDir, '.aperant', 'pending-effects.dead.jsonl')
+						mkdirSync(dirname(deadPath), { recursive: true })
+						const deadBody =
+							(existsSync(deadPath) ? readFileSync(deadPath, 'utf-8') : '') +
+							deadQueue.map((e) => JSON.stringify(e)).join('\n') +
+							'\n'
+						writeFileSync(deadPath, deadBody, 'utf-8')
+					}
+				},
+				{ projectRoot: targetDir },
+			)
+
+			// Compute pending_after post-drain (outside the lock — informational).
+			const pendingAfter = existsSync(filePath) ? readEffects(filePath).length : 0
+
+			return ok({
+				status: 'ok',
+				command: 'effects-drain',
+				drained,
+				failed,
+				parked,
+				pending_after: pendingAfter,
+				transitions,
+				commits,
+				dry_run: dryRun || undefined,
+			})
+		}
+
+		default:
+			return err(`Unknown effects subcommand: ${subcommand}`)
+	}
+}