@aperant/framework 0.6.6 → 0.7.0

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

@@ -0,0 +1,133 @@
+/**
+ * release-notes/draft.mjs — towncrier-style per-PR fragment writer.
+ *
+ * Writes `<output_dir>/_unreleased/PR-<n>.md` for a single PR. Idempotent:
+ * if the target file already exists with byte-identical content, the call
+ * is a no-op and the envelope reports `written: false`. The same input
+ * always produces the same bytes on disk — that is the load-bearing
+ * invariant the news-fragment pattern depends on (zero merge conflicts
+ * on the unreleased file, AC2).
+ *
+ * Deterministic I/O only. No LLM calls. No prompt templates. The host
+ * LLM authors the note text and hands it in via --note.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { atomicWriteText } from '../util/atomic-write.mjs'
+import { resolveOutputDir } from './output-dir.mjs'
+
+/**
+ * Build the canonical fragment body. The shape is intentionally simple +
+ * stable so the compile step can parse it back without YAML / front-matter
+ * gymnastics. Date is the calling day in UTC, not a wall-clock timestamp —
+ * idempotency demands the same inputs produce the same bytes regardless of
+ * when the day they're called within.
+ *
+ * @param {{
+ *   pr: number,
+ *   note: string,
+ *   persona: string | null,
+ *   date: string,
+ *   commits: string[],
+ * }} input
+ * @returns {string}
+ */
+export function renderFragment(input) {
+	const personaLine = input.persona ? `persona: ${input.persona}` : 'persona: (none)'
+	const commitsLine =
+		input.commits.length === 0 ? 'commits: (none)' : `commits: ${input.commits.join(', ')}`
+	return [
+		`# PR-${input.pr}`,
+		'',
+		`date: ${input.date}`,
+		`pr: ${input.pr}`,
+		personaLine,
+		commitsLine,
+		'',
+		'## Release note',
+		'',
+		input.note.trim(),
+		'',
+	].join('\n')
+}
+
+/**
+ * Resolve the commits referencing a PR by number. Best-effort — if git is
+ * unavailable or no matching commits are found, returns an empty array.
+ * Caller can pass commits explicitly via --commits to bypass git inspection.
+ *
+ * @param {string} projectDir
+ * @param {number} pr
+ * @returns {string[]}
+ */
+function discoverCommitsForPr(projectDir, pr) {
+	try {
+		const out = execFileSync(
+			'git',
+			['-C', projectDir, 'log', '--no-merges', `--grep=#${pr}\\b`, '--format=%H'],
+			{ encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] },
+		)
+		return out
+			.split('\n')
+			.map((s) => s.trim())
+			.filter((s) => s.length > 0)
+			.map((sha) => sha.slice(0, 12))
+	} catch {
+		return []
+	}
+}
+
+/**
+ * @typedef {Object} DraftInput
+ * @property {string} projectDir
+ * @property {number} pr
+ * @property {string} note
+ * @property {string | null} persona
+ * @property {string | null} outputDir   // CLI flag override (relative to projectDir or absolute).
+ * @property {string[] | null} commits   // explicit commit list; null → autodetect via git log.
+ * @property {string | null} date        // ISO yyyy-mm-dd; null → today (UTC).
+ */
+
+/**
+ * @typedef {Object} DraftResult
+ * @property {boolean} written
+ * @property {string} path
+ * @property {string} reason     // 'created' | 'no-change' | 'updated'
+ */
+
+/**
+ * Write the PR fragment idempotently. Returns the result envelope.
+ *
+ * @param {DraftInput} input
+ * @returns {DraftResult}
+ */
+export function writeDraft(input) {
+	const outputDir = resolveOutputDir(input.projectDir, input.outputDir)
+	const unreleasedDir = join(outputDir, '_unreleased')
+	const target = join(unreleasedDir, `PR-${input.pr}.md`)
+
+	const date = input.date ?? new Date().toISOString().slice(0, 10)
+	const commits = input.commits ?? discoverCommitsForPr(input.projectDir, input.pr)
+
+	const body = renderFragment({
+		pr: input.pr,
+		note: input.note,
+		persona: input.persona,
+		date,
+		commits,
+	})
+
+	if (existsSync(target)) {
+		const existing = readFileSync(target, 'utf-8')
+		if (existing === body) {
+			return { written: false, path: target, reason: 'no-change' }
+		}
+		atomicWriteText(target, body)
+		return { written: true, path: target, reason: 'updated' }
+	}
+	atomicWriteText(target, body)
+	return { written: true, path: target, reason: 'created' }
+}

package/src/cli/release-notes/output-dir.mjs

@@ -0,0 +1,52 @@
+/**
+ * release-notes/output-dir.mjs — shared output directory resolver.
+ *
+ * Extracted from draft.mjs, compile.mjs, and publish.mjs to eliminate
+ * copy-paste duplication (QUA-003).
+ */
+
+import { resolve } from 'node:path'
+
+import { loadProjectConfig } from '../config/load.mjs'
+
+const DEFAULT_OUTPUT_DIR = 'docs/releases'
+
+/** Allowlist for release tag values — semver-compatible subset. */
+const TAG_PATTERN = /^[a-zA-Z0-9._-]+$/
+
+/**
+ * Validate a release tag. Throws if the tag contains path-traversal
+ * sequences (`..`, `/`) or characters outside the semver-compatible
+ * allowlist. Defends path.join calls in compile.mjs and publish.mjs
+ * against directory escape (SEC-001).
+ *
+ * @param {string} tag
+ * @returns {void}
+ */
+export function validateTag(tag) {
+	if (tag.includes('..') || tag.includes('/')) {
+		throw new Error(`Invalid --tag: "${tag}" contains path-traversal sequences (.. or /)`)
+	}
+	if (!TAG_PATTERN.test(tag)) {
+		throw new Error(
+			`Invalid --tag: "${tag}" must match /^[a-zA-Z0-9._-]+$/ (no spaces or special characters)`,
+		)
+	}
+}
+
+/**
+ * Resolve the canonical output directory from flag override → config → default.
+ * Flag override wins when present. Returns an absolute path.
+ *
+ * @param {string} projectDir
+ * @param {string | null} flagOverride
+ * @returns {string}
+ */
+export function resolveOutputDir(projectDir, flagOverride) {
+	const config = loadProjectConfig(projectDir)
+	const configured = config?.changelog?.release_notes?.output_dir
+	return resolve(
+		projectDir,
+		flagOverride ?? (typeof configured === 'string' ? configured : DEFAULT_OUTPUT_DIR),
+	)
+}

package/src/cli/release-notes/persona-filter.mjs

@@ -0,0 +1,126 @@
+/**
+ * release-notes/persona-filter.mjs — shared persona-filter logic.
+ *
+ * The compile + autodraft surfaces both need the same predicate: given a
+ * persona id (or name) extracted from a fragment, the project's
+ * `.aperant/personas.json` roster, and a filter mode, decide whether the
+ * fragment belongs in the user-facing body, in the "Needs Triage" bucket,
+ * or filtered out entirely.
+ *
+ * Three filter modes (config.changelog.release_notes.persona_filter):
+ *
+ *   - 'primary'             — only personas whose `tier === 'primary'`.
+ *   - 'primary+secondary'   — primary OR secondary. DEFAULT.
+ *   - 'all'                 — every tier passes (no filter).
+ *
+ * Triage rules (ID-6 in spec.md, never-silent-drop invariant):
+ *
+ *   - Fragment with no persona tag         → bucket = 'triage'.
+ *   - Fragment with a tag that doesn't
+ *     resolve to a known persona in the
+ *     roster                              → bucket = 'triage'.
+ *   - Fragment whose persona DOES resolve
+ *     but is filtered out by the mode     → bucket = 'filtered'.
+ *   - Fragment whose persona resolves AND
+ *     passes the mode                     → bucket = 'body', with the
+ *                                            resolved tier exposed for
+ *                                            grouping in compile output.
+ *
+ * The matcher is case-insensitive on persona names. Empty string and the
+ * literal sentinel `(none)` are both treated as "no tag" — the draft
+ * renderer writes `persona: (none)` when no --persona flag is passed.
+ */
+
+/** @typedef {'primary' | 'secondary' | 'tertiary' | 'unknown'} PersonaTier */
+/** @typedef {'body' | 'triage' | 'filtered'} FilterBucket */
+
+const NONE_SENTINELS = new Set(['', '(none)', 'none', 'null', 'undefined'])
+
+/**
+ * True when the raw persona-tag string from a fragment should be treated as
+ * "no tag" (and therefore routed to triage with reason `no-persona-tag`).
+ * Mirrors `NONE_SENTINELS` so callers — notably `compile.mjs`'s triage-reason
+ * labeller — stay in lockstep with the classifier. Case-insensitive.
+ *
+ * @param {string | null | undefined} raw
+ * @returns {boolean}
+ */
+export function isNoneSentinel(raw) {
+	const normalized = (raw ?? '').trim().toLowerCase()
+	return NONE_SENTINELS.has(normalized)
+}
+
+/**
+ * Read tier + name out of a persona envelope row (the shape personas.mjs
+ * persists). Tier lives inside `ui_json` (a JSON string). Returns null
+ * when the row is unusable.
+ *
+ * @param {{ ui_json?: unknown }} row
+ * @returns {{ name: string, tier: PersonaTier } | null}
+ */
+export function extractPersonaIdentity(row) {
+	if (!row || typeof row !== 'object') return null
+	if (typeof row.ui_json !== 'string') return null
+	let parsed
+	try {
+		parsed = JSON.parse(row.ui_json)
+	} catch {
+		return null
+	}
+	if (!parsed || typeof parsed !== 'object') return null
+	const name = typeof parsed.name === 'string' ? parsed.name.trim() : ''
+	const tierRaw = typeof parsed.tier === 'string' ? parsed.tier.trim().toLowerCase() : ''
+	if (name.length === 0) return null
+	/** @type {PersonaTier} */
+	const tier =
+		tierRaw === 'primary' || tierRaw === 'secondary' || tierRaw === 'tertiary' ? tierRaw : 'unknown'
+	return { name, tier }
+}
+
+/**
+ * Build a name → tier map from a personas envelope.
+ *
+ * @param {{ personas?: Array<{ ui_json?: unknown }> } | null | undefined} envelope
+ * @returns {Map<string, PersonaTier>}
+ */
+export function buildPersonaTierMap(envelope) {
+	/** @type {Map<string, PersonaTier>} */
+	const map = new Map()
+	if (!envelope || !Array.isArray(envelope.personas)) return map
+	for (const row of envelope.personas) {
+		const identity = extractPersonaIdentity(row)
+		if (!identity) continue
+		map.set(identity.name.toLowerCase(), identity.tier)
+	}
+	return map
+}
+
+/**
+ * Classify a fragment's persona tag against the roster + filter mode.
+ *
+ * @param {string | null | undefined} personaTag   The raw tag from the fragment.
+ * @param {Map<string, PersonaTier>} tierMap        From `buildPersonaTierMap`.
+ * @param {'primary' | 'primary+secondary' | 'all'} mode
+ * @returns {{ bucket: FilterBucket, resolvedName: string | null, resolvedTier: PersonaTier | null }}
+ */
+export function classifyFragment(personaTag, tierMap, mode) {
+	const normalized = (personaTag ?? '').trim().toLowerCase()
+	if (normalized.length === 0 || NONE_SENTINELS.has(normalized)) {
+		return { bucket: 'triage', resolvedName: null, resolvedTier: null }
+	}
+	const tier = tierMap.get(normalized)
+	if (tier === undefined) {
+		// Tag was set but the roster doesn't recognize it — never silent-drop.
+		return { bucket: 'triage', resolvedName: personaTag ?? null, resolvedTier: null }
+	}
+	if (mode === 'all') {
+		return { bucket: 'body', resolvedName: personaTag ?? null, resolvedTier: tier }
+	}
+	if (mode === 'primary' && tier !== 'primary') {
+		return { bucket: 'filtered', resolvedName: personaTag ?? null, resolvedTier: tier }
+	}
+	if (mode === 'primary+secondary' && tier !== 'primary' && tier !== 'secondary') {
+		return { bucket: 'filtered', resolvedName: personaTag ?? null, resolvedTier: tier }
+	}
+	return { bucket: 'body', resolvedName: personaTag ?? null, resolvedTier: tier }
+}

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

@@ -0,0 +1,128 @@
+/**
+ * release-notes/publish.mjs — `gh release create/edit` shell.
+ *
+ * Reads `<output_dir>/<tag>.md` and shells `gh release create <tag>
+ * --notes-file <path>` (or `gh release edit` if a release already exists
+ * for that tag). When `gh` is unavailable on the host, returns a graceful
+ * `{status: 'skipped', reason: 'gh-not-found'}` envelope rather than
+ * crashing — AC4.
+ *
+ * Tests inject a custom shell via the GH_BIN env var (mocked to a no-op
+ * shell script) so the publish branch of TD-5 can run without making a
+ * real network call.
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { resolveOutputDir, validateTag } from './output-dir.mjs'
+
+/**
+ * @typedef {Object} PublishInput
+ * @property {string} projectDir
+ * @property {string} tag
+ * @property {string | null} outputDir
+ * @property {boolean} dryRun
+ */
+
+/**
+ * @typedef {{
+ *   status: 'ok',
+ *   mode: 'created' | 'edited' | 'dry-run',
+ *   notesPath: string,
+ * } | {
+ *   status: 'skipped',
+ *   reason: 'gh-not-found' | 'notes-not-found' | 'gh-failed',
+ *   notesPath?: string,
+ *   exit_code?: number | null,
+ *   stderr?: string | null,
+ * }} PublishResult
+ */
+
+/**
+ * Resolve which `gh` binary to use. Defaults to `gh` on PATH; tests
+ * override via the GH_BIN env var (only honored in NODE_ENV=test).
+ *
+ * @returns {string}
+ */
+function ghBin() {
+	if (process.env.NODE_ENV === 'test') {
+		const override = process.env.GH_BIN
+		if (override && override.length > 0) return override
+	}
+	return 'gh'
+}
+
+/**
+ * Detect whether `gh` is available on the host. Uses `which` semantics:
+ * `gh --version` exit-0 → available. Any error path → unavailable.
+ *
+ * @returns {boolean}
+ */
+function ghAvailable() {
+	try {
+		const result = spawnSync(ghBin(), ['--version'], { stdio: ['ignore', 'ignore', 'ignore'] })
+		return result.status === 0
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Check whether a release already exists for the given tag.
+ *
+ * @param {string} projectDir
+ * @param {string} tag
+ * @returns {boolean}
+ */
+function releaseExists(projectDir, tag) {
+	try {
+		const result = spawnSync(ghBin(), ['release', 'view', tag, '--json', 'tagName'], {
+			cwd: projectDir,
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+		return result.status === 0
+	} catch {
+		return false
+	}
+}
+
+/**
+ * @param {PublishInput} input
+ * @returns {PublishResult}
+ */
+export function publishTag(input) {
+	validateTag(input.tag)
+	const outputDir = resolveOutputDir(input.projectDir, input.outputDir)
+	const notesPath = join(outputDir, `${input.tag}.md`)
+	if (!existsSync(notesPath)) {
+		return { status: 'skipped', reason: 'notes-not-found', notesPath }
+	}
+	if (input.dryRun) {
+		return { status: 'ok', mode: 'dry-run', notesPath }
+	}
+	if (!ghAvailable()) {
+		return { status: 'skipped', reason: 'gh-not-found', notesPath }
+	}
+	const exists = releaseExists(input.projectDir, input.tag)
+	const verb = exists ? 'edit' : 'create'
+	const args = ['release', verb, input.tag, '--notes-file', notesPath]
+	// `gh release edit` only takes --notes-file; `gh release create` takes
+	// --notes-file too and a positional tag — same argv order works.
+	try {
+		execFileSync(ghBin(), args, {
+			cwd: input.projectDir,
+			stdio: ['ignore', 'pipe', 'pipe'],
+		})
+	} catch (err) {
+		return {
+			status: 'skipped',
+			reason: 'gh-failed',
+			notesPath,
+			exit_code: err.status ?? null,
+			stderr: err.stderr?.toString() ?? null,
+		}
+	}
+	return { status: 'ok', mode: exists ? 'edited' : 'created', notesPath }
+}

package/src/cli/release-notes/ship-autodraft.mjs

@@ -0,0 +1,106 @@
+/**
+ * release-notes/ship-autodraft.mjs — apt-ship Section 2.6 helper.
+ *
+ * Deterministic, unit-testable shape: given a feature-registry diff +
+ * personas envelope + persona_filter mode, decide whether the PR body
+ * should grow a `Release note: …` line OR ship should block.
+ *
+ * This module is intentionally pure — the apt-ship SKILL.md body shells
+ * `apt-tools features-audit . --diff-since <base> --json` and feeds the
+ * envelope here. Keeping the decision pure makes TD-4 trivial: fixture in,
+ * decision out, no I/O.
+ */
+
+import { buildPersonaTierMap, classifyFragment } from './persona-filter.mjs'
+
+/**
+ * @typedef {Object} FeatureDiffEntry
+ * @property {string} feature_id
+ * @property {string} [area]
+ * @property {string[]} [personas]
+ */
+
+/**
+ * @typedef {Object} AutodraftInput
+ * @property {FeatureDiffEntry[]} featureDiff
+ * @property {{ personas?: Array<{ ui_json?: unknown }> } | null} personasEnvelope
+ * @property {'primary' | 'primary+secondary' | 'all'} personaFilter
+ * @property {boolean} requirePrField
+ */
+
+/**
+ * @typedef {{
+ *   status: 'draft',
+ *   line: string,
+ *   persona: string,
+ *   matchedFeatures: string[],
+ * } | {
+ *   status: 'block',
+ *   reason: 'no-feature-match' | 'no-persona-signal',
+ *   message: string,
+ * } | {
+ *   status: 'warn',
+ *   reason: 'no-feature-match' | 'no-persona-signal',
+ *   message: string,
+ * }} AutodraftResult
+ */
+
+const BLOCK_MESSAGE =
+	'[APT] No release-note signal found — author manual note in PR body or label PR no-notes'
+
+/**
+ * Compute the autodraft decision.
+ *
+ * @param {AutodraftInput} input
+ * @returns {AutodraftResult}
+ */
+export function decideAutodraft(input) {
+	const tierMap = buildPersonaTierMap(input.personasEnvelope)
+
+	if (!Array.isArray(input.featureDiff) || input.featureDiff.length === 0) {
+		return failClassify(input, 'no-feature-match')
+	}
+
+	// Walk the diff; the first feature whose persona resolves into the
+	// filter mode wins. (Multi-persona dispatch is intentionally out of
+	// scope here — host LLM-side narrative can refine per persona; the
+	// CLI just picks a clean signal so ship is decisive.)
+	for (const feature of input.featureDiff) {
+		if (!Array.isArray(feature.personas) || feature.personas.length === 0) continue
+		for (const personaTag of feature.personas) {
+			const decision = classifyFragment(personaTag, tierMap, input.personaFilter)
+			if (decision.bucket === 'body' && decision.resolvedTier) {
+				return {
+					status: 'draft',
+					line: `Release note: ${feature.feature_id} — ships for ${personaTag}.`,
+					persona: personaTag,
+					matchedFeatures: [feature.feature_id],
+				}
+			}
+		}
+	}
+
+	// No persona signal anywhere — features exist but none carry a tag
+	// that the roster + filter accept.
+	return failClassify(input, 'no-persona-signal')
+}
+
+/**
+ * Translate a failure reason into the right envelope shape based on
+ * `require_pr_field`. require=true → block; require=false → warn (skill
+ * proceeds without the line).
+ *
+ * @param {AutodraftInput} input
+ * @param {'no-feature-match' | 'no-persona-signal'} reason
+ * @returns {AutodraftResult}
+ */
+function failClassify(input, reason) {
+	if (input.requirePrField) {
+		return { status: 'block', reason, message: BLOCK_MESSAGE }
+	}
+	return {
+		status: 'warn',
+		reason,
+		message: `[APT] auto-draft skipped (${reason}) — release_notes.require_pr_field is false; proceeding without a Release note line.`,
+	}
+}

package/src/cli/route/drift-detect.mjs

@@ -0,0 +1,107 @@
+/**
+ * route/drift-detect.mjs — FRAMEWORK-BUG-017 (rung 1 of 3).
+ *
+ * In-band detection of the "installed kernel drifts behind source
+ * workspace" failure mode. When an Aperant contributor self-hosts the
+ * framework out of a monorepo checkout, the kernel at
+ * `.aperant/deps/node_modules/@aperant/framework/` lags behind the
+ * source at `packages/framework/` after every same-PR framework fix.
+ * The SessionStart worker only knows about npm — it cannot tell that
+ * the workspace is ahead of the install.
+ *
+ * This module walks up from `targetDir`, looking for a sibling
+ * `packages/framework/package.json`. When found AND its `version`
+ * differs from the installed kernel's `version`, it returns a synthetic
+ * `update_check`-shaped object so `route.mjs` can surface the chip
+ * immediately — without waiting for the SessionStart hook to fire.
+ *
+ * Safe for the route hot path: synchronous, file-existence checks
+ * only, bounded walk (6 segments max), no network, no spawn.
+ *
+ * Security (Codex review edit 2): the workspace `package.json:version`
+ * is validated against the same semver-shape regex `update-chips.mjs`
+ * uses on the cache. A poisoned workspace `package.json` cannot
+ * propagate a non-semver `latest_version` into the synthesized
+ * `update_check` block.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { compareVersions, SEMVER_RE } from '../util/semver.mjs'
+
+/** Max directory frames to walk before giving up. */
+const MAX_WALK_DEPTH = 6
+
+/**
+ * Walk up from `start`, returning every directory frame including
+ * `start` itself. Stops at the filesystem root or at a depth of
+ * `MAX_WALK_DEPTH` (whichever comes first). The hard cap keeps this
+ * cheap on the route hot path and contains accidental scans on deeply
+ * nested input paths.
+ *
+ * @param {string} start
+ * @returns {string[]}
+ */
+function walkUp(start) {
+	const frames = []
+	let cur = start
+	for (let i = 0; i < MAX_WALK_DEPTH; i++) {
+		frames.push(cur)
+		const parent = dirname(cur)
+		if (parent === cur) break
+		cur = parent
+	}
+	return frames
+}
+
+/**
+ * Detect whether the workspace source for `@aperant/framework` is ahead
+ * of the installed kernel.
+ *
+ * @param {string} targetDir  Absolute path the route was invoked against.
+ * @param {string|null} installedVersion  The installed kernel's version (semver string), or null when unknown.
+ * @returns {null | {
+ *   source_path: string,
+ *   source_version: string,
+ *   installed_version: string,
+ *   drift: true,
+ * }}
+ */
+export function detectSourceWorkspaceDrift(targetDir, installedVersion) {
+	if (!targetDir || typeof targetDir !== 'string') return null
+	if (!installedVersion || typeof installedVersion !== 'string') return null
+	if (!SEMVER_RE.test(installedVersion)) return null
+
+	for (const dir of walkUp(targetDir)) {
+		const candidate = join(dir, 'packages', 'framework', 'package.json')
+		if (!existsSync(candidate)) continue
+
+		let pkg
+		try {
+			pkg = JSON.parse(readFileSync(candidate, 'utf-8'))
+		} catch {
+			return null
+		}
+
+		// Validate the workspace package is actually @aperant/framework —
+		// guard against false matches on unrelated monorepos that happen
+		// to have a `packages/framework/` directory.
+		if (pkg?.name !== '@aperant/framework') continue
+
+		const sourceVersion = pkg?.version
+		if (typeof sourceVersion !== 'string' || !SEMVER_RE.test(sourceVersion)) return null
+		// Only report drift when workspace source is strictly ahead of the installed
+		// kernel. Equal (already up-to-date) and behind (installed is newer) both
+		// return null — only source-ahead is a drift worth surfacing.
+		if (compareVersions(sourceVersion, installedVersion) <= 0) return null
+
+		return {
+			source_path: candidate,
+			source_version: sourceVersion,
+			installed_version: installedVersion,
+			drift: true,
+		}
+	}
+
+	return null
+}