@aperant/framework 0.6.6 → 0.7.0

package/src/cli/install/runtime-migrate.mjs

@@ -0,0 +1,252 @@
+/**
+ * install/runtime-migrate.mjs — at-install cleanup of legacy install
+ * trees the framework no longer owns (FRAMEWORK-BUG-021).
+ *
+ * Codex was originally installed into `.agents/skills/` (commit 1a8dd8a8)
+ * and later moved to `.codex/`. Projects that upgraded across that move
+ * end up with a stale `.agents/skills/` tree that:
+ *
+ *   - keeps `.apt-version` on disk → the legacy fallback in
+ *     `readSkillInstallState` reports a stale codex install.
+ *   - shows up in `health-check` as `stale-skills`.
+ *   - leaves dozens of orphaned SKILL.md files the runtime no longer
+ *     reads.
+ *
+ * `runLegacyCleanup` runs once per `apt-tools init` when codex is in the
+ * requested runtime set. It is conservative by default:
+ *
+ *   - Only files listed in `LEGACY_INSTALL_PATHS.codex.framework_files`
+ *     are removed. User-added skill directories (`my-skill/`, …) are
+ *     preserved. If anything beyond the known framework set remains,
+ *     `retained[]` lists those paths.
+ *   - A present-and-current `apt-file-manifest.json` is treated as the
+ *     authoritative "this is a managed install, leave it alone" signal:
+ *     the function no-ops with `reason: 'managed'`.
+ *   - The caller can suppress cleanup entirely via `--keep-legacy` at the
+ *     init.mjs site; the function itself is dumb about flags.
+ */
+
+import { existsSync, readdirSync, rmdirSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { LEGACY_INSTALL_PATHS } from './legacy-paths.mjs'
+import { MANIFEST_FILENAME } from './manifest.mjs'
+
+/**
+ * @typedef {Object} LegacyCodexDetection
+ * @property {boolean} present              True when `.agents/skills/` exists.
+ * @property {string[]} frameworkFiles      Subset of `framework_files` that
+ *                                          actually exist on disk (relative
+ *                                          to install_root).
+ * @property {string[]} userFiles           Everything else under
+ *                                          install_root (relative to
+ *                                          install_root). May include both
+ *                                          files and directories. Drives the
+ *                                          `retained[]` warning.
+ * @property {boolean} hasAptVersion        Whether the legacy `.apt-version`
+ *                                          stamp is present.
+ * @property {boolean} hasManifest          Whether an
+ *                                          `apt-file-manifest.json` is
+ *                                          present at install_root (signals
+ *                                          a managed install — cleanup
+ *                                          should no-op).
+ */
+
+const LEGACY = LEGACY_INSTALL_PATHS.codex
+
+/**
+ * Recursively enumerate every file path under `dir`, returning paths
+ * relative to `dir`. Used to compute the "user files" set (anything not
+ * in the framework_files list).
+ *
+ * Returns []  when the dir doesn't exist. Swallows per-entry errors so a
+ * single unreadable symlink doesn't abort detection.
+ *
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function walkRelative(dir) {
+	/** @type {string[]} */
+	const out = []
+	if (!existsSync(dir)) return out
+	/** @param {string} current @param {string} rel */
+	const visit = (current, rel) => {
+		let entries
+		try {
+			entries = readdirSync(current, { withFileTypes: true })
+		} catch {
+			return
+		}
+		for (const entry of entries) {
+			const childPath = join(current, entry.name)
+			const childRel = rel ? `${rel}/${entry.name}` : entry.name
+			if (entry.isDirectory()) {
+				visit(childPath, childRel)
+			} else if (entry.isFile()) {
+				out.push(childRel)
+			}
+			// Symlinks / other entry types are intentionally ignored — the
+			// framework only ever writes regular files.
+		}
+	}
+	visit(dir, '')
+	return out
+}
+
+/**
+ * Probe the codex legacy install tree at `<targetDir>/.agents/skills/`.
+ *
+ * @param {string} targetDir
+ * @returns {LegacyCodexDetection}
+ */
+export function detectLegacyCodexTree(targetDir) {
+	const installRoot = join(targetDir, LEGACY.install_root)
+	if (!existsSync(installRoot)) {
+		return {
+			present: false,
+			frameworkFiles: [],
+			userFiles: [],
+			hasAptVersion: false,
+			hasManifest: false,
+		}
+	}
+
+	const onDisk = walkRelative(installRoot)
+	const frameworkSet = new Set(LEGACY.framework_files)
+	const frameworkFiles = onDisk.filter((p) => frameworkSet.has(p))
+	const userFiles = onDisk.filter((p) => !frameworkSet.has(p) && p !== MANIFEST_FILENAME)
+
+	return {
+		present: true,
+		frameworkFiles,
+		userFiles,
+		hasAptVersion: onDisk.includes('.apt-version'),
+		hasManifest: onDisk.includes(MANIFEST_FILENAME),
+	}
+}
+
+/**
+ * Try to remove a directory if it is empty. Swallows ENOTEMPTY / ENOENT
+ * so the caller can blindly sweep candidate dirs in any order.
+ *
+ * @param {string} dir
+ * @returns {boolean} true iff the dir was actually removed.
+ */
+function rmEmptyDir(dir) {
+	if (!existsSync(dir)) return false
+	try {
+		rmdirSync(dir)
+		return true
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Clean up the legacy `.agents/skills/` tree if it looks orphaned.
+ *
+ * Branches:
+ *   1. `present: false` OR `frameworkFiles.length === 0` → no-op,
+ *      `{ ran: false, reason: 'no-legacy' }`.
+ *   2. `hasManifest: true` → managed install, no-op,
+ *      `{ ran: false, reason: 'managed' }`.
+ *   3. Otherwise: per-file `unlinkSync` each framework-owned file;
+ *      `rmdirSync` any now-empty `apt-*` subdirectory; sweep
+ *      `.agents/skills/` only if it is empty; sweep `.agents/` only if
+ *      its `skills/` got removed and `.agents/` is empty.
+ *
+ * Returns `{ ran: true, removed, retained, rmdirs }` on the cleanup
+ * branch:
+ *   - `removed`  — relative paths under `install_root` that were unlinked.
+ *   - `retained` — relative paths under `install_root` that were NOT
+ *     removed (user-added skills / files not in the legacy set).
+ *   - `rmdirs`   — absolute paths of directories that were removed
+ *     (apt-* subdirs, the install_root itself, .agents/), in removal order.
+ *
+ * Atomicity: per-file unlink is non-atomic. A partial-failure scenario
+ * (process killed mid-loop) is tolerable — the next `init` run will
+ * re-detect the remaining framework files and finish the sweep.
+ *
+ * @param {{ targetDir: string, dryRun?: boolean }} args
+ * @returns {
+ *   | { ran: false, reason: 'no-legacy' | 'managed' }
+ *   | { ran: true, removed: string[], retained: string[], rmdirs: string[] }
+ * }
+ */
+export function runLegacyCleanup({ targetDir, dryRun = false }) {
+	const detection = detectLegacyCodexTree(targetDir)
+
+	if (!detection.present || detection.frameworkFiles.length === 0) {
+		return { ran: false, reason: 'no-legacy' }
+	}
+	if (detection.hasManifest) {
+		return { ran: false, reason: 'managed' }
+	}
+
+	const installRoot = join(targetDir, LEGACY.install_root)
+	const removed = []
+	const rmdirs = []
+
+	if (dryRun) {
+		// Dry-run: report what WOULD be removed without touching the filesystem.
+		// `retained` is the user-file set from the pre-walk (no sweep occurred).
+		// `rmdirs` is the set of apt-* subdirs that would become empty after removal.
+		const wouldRemove = detection.frameworkFiles
+		const retained = detection.userFiles
+		const candidateDirs = new Set()
+		for (const rel of wouldRemove) {
+			let parent = dirname(rel)
+			while (parent !== '.' && parent !== '') {
+				candidateDirs.add(parent)
+				parent = dirname(parent)
+			}
+		}
+		const wouldRmdirs = [...candidateDirs]
+			.sort((a, b) => b.length - a.length)
+			.map((rel) => join(installRoot, rel))
+		return { ran: true, dryRun: true, removed: wouldRemove, retained, rmdirs: wouldRmdirs }
+	}
+
+	for (const rel of detection.frameworkFiles) {
+		const abs = join(installRoot, rel)
+		try {
+			unlinkSync(abs)
+			removed.push(rel)
+		} catch {
+			/* best-effort: leave a partial sweep; next run finishes it */
+		}
+	}
+
+	// Sweep any now-empty `apt-*/` subdirs the unlinks left behind.
+	// Walk parent dirs of every removed file in reverse-depth order so
+	// nested `apt-pr-review/prompts/` empties before `apt-pr-review/`.
+	const candidateDirs = new Set()
+	for (const rel of removed) {
+		let parent = dirname(rel)
+		while (parent !== '.' && parent !== '') {
+			candidateDirs.add(parent)
+			parent = dirname(parent)
+		}
+	}
+	const sortedDirs = [...candidateDirs].sort((a, b) => b.length - a.length)
+	for (const rel of sortedDirs) {
+		const abs = join(installRoot, rel)
+		if (rmEmptyDir(abs)) rmdirs.push(abs)
+	}
+
+	// Sweep `.agents/skills/` only if fully empty after the per-file
+	// pass — preserves any user-added skill dirs.
+	if (rmEmptyDir(installRoot)) {
+		rmdirs.push(installRoot)
+		// Sweep `.agents/` only if it became empty too (i.e. no other
+		// `.agents/<sibling>` content the user keeps there).
+		const agentsRoot = dirname(installRoot)
+		if (rmEmptyDir(agentsRoot)) rmdirs.push(agentsRoot)
+	}
+
+	// Use the pre-walk's userFiles as `retained` — the post-walk only existed
+	// to defensively re-scan, but pre-walk already captured user files accurately.
+	// (PRF-002: avoid redundant detectLegacyCodexTree call.)
+	const retained = detection.userFiles
+
+	return { ran: true, removed, retained, rmdirs }
+}

package/src/cli/install/update-chips.mjs

@@ -60,6 +60,63 @@ export function readUpdateCache() {
 	}
 }
 
+/** Semver-shape pattern: MAJOR.MINOR.PATCH with optional pre-release and build metadata. */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+
+/**
+ * Read the worker's cache file with TTL and schema validation. Returns
+ * `{ fresh: true, cache }` when the cache exists, parses, declares
+ * `schema_version === 1`, and was written within `ttlMs` milliseconds.
+ * Returns `{ fresh: false }` when missing, stale, or schema mismatch.
+ *
+ * Security: `latest_version` and `installed_version` inside
+ * `cache.framework` are validated as semver strings. Invalid values are
+ * dropped (set to null) so they never propagate into shell-interpolated
+ * contexts.
+ *
+ * ENOENT and JSON parse errors stay silent (expected when the cache is
+ * missing or being rewritten). Unexpected errors are logged to stderr.
+ *
+ * @param {number} ttlMs  Maximum age in milliseconds before cache is treated as stale.
+ * @returns {{ fresh: true, cache: Record<string, unknown> } | { fresh: false }}
+ */
+export function readFreshUpdateCache(ttlMs) {
+	const path = updateCachePath()
+	if (!existsSync(path)) return { fresh: false }
+	let data
+	try {
+		data = JSON.parse(readFileSync(path, 'utf-8'))
+	} catch (err) {
+		// SyntaxError = malformed JSON (expected); anything else is unexpected.
+		if (!(err instanceof SyntaxError)) {
+			console.error('[update-cache] read failed:', err.message)
+		}
+		return { fresh: false }
+	}
+	try {
+		if (!data || typeof data !== 'object') return { fresh: false }
+		if (data.schema_version !== 1) return { fresh: false }
+		if (typeof data.checked_at !== 'string') return { fresh: false }
+		const age = Date.now() - new Date(data.checked_at).getTime()
+		if (!Number.isFinite(age) || age < 0 || age >= ttlMs) return { fresh: false }
+		// Validate semver fields in framework block — reject non-semver strings.
+		const fw = data.framework && typeof data.framework === 'object' ? data.framework : {}
+		const sanitized = { ...data, framework: { ...fw } }
+		for (const field of ['latest_version', 'installed_version']) {
+			if (
+				typeof sanitized.framework[field] === 'string' &&
+				!SEMVER_RE.test(sanitized.framework[field])
+			) {
+				sanitized.framework[field] = null
+			}
+		}
+		return { fresh: true, cache: sanitized }
+	} catch (err) {
+		console.error('[update-cache] read failed:', err.message)
+		return { fresh: false }
+	}
+}
+
 /**
  * Build the chip string array for a given cache. Empty array when there
  * are no chips to show. Order: stale_files first (most urgent), then

package/src/cli/release-notes/compile.mjs

@@ -0,0 +1,261 @@
+/**
+ * release-notes/compile.mjs — tag-time narrative compiler.
+ *
+ * Reads every `<output_dir>/_unreleased/PR-*.md` fragment, classifies each
+ * against the project's persona roster + filter mode, and writes
+ * `<output_dir>/<tag>.md`. Atomic-rename pattern: the fragments dir is
+ * cleared only AFTER the compiled file lands on disk, so a crash mid-write
+ * cannot orphan fragments without their compiled output.
+ *
+ * Non-negotiable invariant (ID-6): unmapped fragments (no persona tag, or
+ * a tag the roster doesn't recognize) MUST appear in a `## Needs Triage`
+ * section. Never silent-drop. The triage section is the human curator's
+ * safety net — its presence is asserted by TD-3.
+ */
+
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { loadProjectConfig } from '../config/load.mjs'
+import { readPersonas } from '../personas/sidecar.mjs'
+import { atomicWriteText } from '../util/atomic-write.mjs'
+import { resolveOutputDir, validateTag } from './output-dir.mjs'
+import { buildPersonaTierMap, classifyFragment, isNoneSentinel } from './persona-filter.mjs'
+
+const VALID_MODES = new Set(['primary', 'primary+secondary', 'all'])
+
+/** Pre-compiled at module level to avoid recompilation in the sort comparator (PRF-001). */
+const PR_FILENAME_RE = /^PR-(\d+)\.md$/
+
+/**
+ * Parse a single fragment file. Tolerant: missing keys default to empty
+ * strings; the body after `## Release note` is read verbatim.
+ *
+ * @param {string} text
+ * @returns {{ pr: string, date: string, persona: string, note: string, raw: string }}
+ */
+function parseFragment(text) {
+	const lines = text.split('\n')
+	let pr = ''
+	let date = ''
+	let persona = ''
+	let note = ''
+	let noteStart = -1
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]
+		if (line.startsWith('pr: ')) pr = line.slice(4).trim()
+		else if (line.startsWith('date: ')) date = line.slice(6).trim()
+		else if (line.startsWith('persona: ')) persona = line.slice(9).trim()
+		else if (line.startsWith('## Release note')) {
+			noteStart = i
+			break
+		}
+	}
+	if (noteStart >= 0) {
+		note = lines
+			.slice(noteStart + 1)
+			.join('\n')
+			.trim()
+	}
+	return { pr, date, persona, note, raw: text }
+}
+
+/**
+ * Resolve the output dir and persona filter mode from config + flag override.
+ *
+ * @param {string} projectDir
+ * @param {string | null} flagOverride
+ * @returns {{ outputDir: string, personaFilter: 'primary' | 'primary+secondary' | 'all' }}
+ */
+function resolveContext(projectDir, flagOverride) {
+	const config = loadProjectConfig(projectDir)
+	const outputDir = resolveOutputDir(projectDir, flagOverride)
+	const filterRaw = config?.changelog?.release_notes?.persona_filter
+	const personaFilter =
+		typeof filterRaw === 'string' && VALID_MODES.has(filterRaw)
+			? /** @type {'primary' | 'primary+secondary' | 'all'} */ (filterRaw)
+			: 'primary+secondary'
+	return { outputDir, personaFilter }
+}
+
+/**
+ * @typedef {Object} CompileInput
+ * @property {string} projectDir
+ * @property {string} tag
+ * @property {string | null} outputDir
+ */
+
+/**
+ * @typedef {Object} CompileResult
+ * @property {boolean} written
+ * @property {string} path
+ * @property {number} fragmentsTotal
+ * @property {number} fragmentsInBody
+ * @property {number} fragmentsInTriage
+ * @property {number} fragmentsFiltered
+ * @property {boolean} clearedUnreleased
+ */
+
+/**
+ * Compile every `_unreleased/PR-*.md` fragment into `<output_dir>/<tag>.md`.
+ *
+ * @param {CompileInput} input
+ * @returns {CompileResult}
+ */
+export function compileTag(input) {
+	validateTag(input.tag)
+	const { outputDir, personaFilter } = resolveContext(input.projectDir, input.outputDir)
+	const fragmentsDir = join(outputDir, '_unreleased')
+	const targetPath = join(outputDir, `${input.tag}.md`)
+
+	const rawFiles = existsSync(fragmentsDir)
+		? readdirSync(fragmentsDir).filter((f) => PR_FILENAME_RE.test(f))
+		: []
+	// Pre-compute PR numbers once to avoid re-running the regex in the comparator (PRF-001).
+	const withNumbers = rawFiles.map((f) => ({
+		f,
+		n: Number.parseInt(PR_FILENAME_RE.exec(f)?.[1] ?? '0', 10),
+	}))
+	withNumbers.sort((a, b) => a.n - b.n)
+	const fragments = withNumbers.map(({ f }) => ({
+		filename: f,
+		...parseFragment(readFileSync(join(fragmentsDir, f), 'utf-8')),
+	}))
+
+	const personasEnvelope = readPersonas(input.projectDir)
+	const tierMap = buildPersonaTierMap(personasEnvelope)
+
+	/** @type {Array<{ pr: string, date: string, persona: string, note: string, tier: 'primary' | 'secondary' | 'tertiary' }>} */
+	const bodyEntries = []
+	/** @type {Array<{ pr: string, date: string, persona: string, note: string, reason: string }>} */
+	const triageEntries = []
+	let filteredCount = 0
+
+	for (const frag of fragments) {
+		const { bucket, resolvedTier } = classifyFragment(frag.persona, tierMap, personaFilter)
+		if (bucket === 'body' && resolvedTier !== null && resolvedTier !== 'unknown') {
+			bodyEntries.push({
+				pr: frag.pr,
+				date: frag.date,
+				persona: frag.persona,
+				note: frag.note,
+				tier: resolvedTier,
+			})
+		} else if (bucket === 'triage' || resolvedTier === 'unknown') {
+			// Use the shared sentinel predicate so this label stays in lockstep
+			// with persona-filter.mjs's NONE_SENTINELS set. Without it, the
+			// classifier and labeller drift (e.g. literal "null" persona tags
+			// land in triage as 'unknown-persona' instead of 'no-persona-tag').
+			// 'unknown' tier (malformed tier value in personas.json) is also
+			// routed here — never silent-drop (ID-6 / LOG-001).
+			const reason = isNoneSentinel(frag.persona)
+				? 'no-persona-tag'
+				: resolvedTier === 'unknown'
+					? 'unknown-tier'
+					: 'unknown-persona'
+			triageEntries.push({
+				pr: frag.pr,
+				date: frag.date,
+				persona: frag.persona,
+				note: frag.note,
+				reason,
+			})
+		} else {
+			filteredCount++
+		}
+	}
+
+	const compiled = renderCompiled({
+		tag: input.tag,
+		body: bodyEntries,
+		triage: triageEntries,
+		filter: personaFilter,
+	})
+
+	atomicWriteText(targetPath, compiled)
+
+	// Clear _unreleased only AFTER the compiled file is durably written.
+	let clearedUnreleased = false
+	if (existsSync(fragmentsDir) && fragments.length > 0) {
+		for (const frag of fragments) {
+			rmSync(join(fragmentsDir, frag.filename), { force: true })
+		}
+		clearedUnreleased = true
+	}
+
+	return {
+		written: true,
+		path: targetPath,
+		fragmentsTotal: fragments.length,
+		fragmentsInBody: bodyEntries.length,
+		fragmentsInTriage: triageEntries.length,
+		fragmentsFiltered: filteredCount,
+		clearedUnreleased,
+	}
+}
+
+/**
+ * Render the per-tag compiled body.
+ *
+ * Layout:
+ *   # Release <tag>
+ *
+ *   (per-tier sections — primary first, then secondary, then tertiary
+ *    when filter==='all'. Each section's entries sorted by PR number.)
+ *
+ *   ## Needs Triage   (only when triage[] non-empty)
+ *
+ * @param {{
+ *   tag: string,
+ *   body: Array<{ pr: string, date: string, persona: string, note: string, tier: 'primary' | 'secondary' | 'tertiary' }>,
+ *   triage: Array<{ pr: string, date: string, persona: string, note: string, reason: string }>,
+ *   filter: 'primary' | 'primary+secondary' | 'all',
+ * }} input
+ * @returns {string}
+ */
+function renderCompiled(input) {
+	const lines = []
+	lines.push(`# Release ${input.tag}`)
+	lines.push('')
+	lines.push(`<!-- persona_filter: ${input.filter} -->`)
+	lines.push('')
+
+	const tiersInOrder = /** @type {const} */ (['primary', 'secondary', 'tertiary'])
+	for (const tier of tiersInOrder) {
+		const rows = input.body.filter((e) => e.tier === tier)
+		if (rows.length === 0) continue
+		lines.push(`## ${capitalize(tier)} personas`)
+		lines.push('')
+		for (const row of rows) {
+			lines.push(`- **PR #${row.pr}** (${row.persona}): ${row.note}`)
+		}
+		lines.push('')
+	}
+
+	if (input.triage.length > 0) {
+		lines.push('## Needs Triage')
+		lines.push('')
+		lines.push('_These fragments lack a recognized persona tag. Curate before publishing._')
+		lines.push('')
+		for (const row of input.triage) {
+			const personaLabel = row.persona && row.persona !== '(none)' ? row.persona : '(no tag)'
+			lines.push(`- **PR #${row.pr}** (${personaLabel}, ${row.reason}): ${row.note}`)
+		}
+		lines.push('')
+	}
+
+	if (input.body.length === 0 && input.triage.length === 0) {
+		lines.push('_No fragments to compile._')
+		lines.push('')
+	}
+
+	return lines.join('\n')
+}
+
+/**
+ * @param {string} s
+ * @returns {string}
+ */
+function capitalize(s) {
+	return s.length === 0 ? s : s[0].toUpperCase() + s.slice(1)
+}