@aperant/framework 0.6.6 → 0.6.7

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/templates/config.json

@@ -1,5 +1,5 @@
 {
-	"version": 4,
+	"version": 5,
 	"project_type": "unknown",
 	"share": {
 		"$comment": "Artifact-sharing policy (C35). Source of truth: packages/framework/src/cli/config/share-policy.mjs. visibility = 'solo' | 'team' | 'oss' preset; individual share.* toggles override it. share.digests = null inherits from config.digests.enabled.",
@@ -107,12 +107,37 @@
 		"debate_mode": "auto"
 	},
 	"diagram": {
-		"mode": "file",
-		"mcpConsent": null
+		"mode": "file"
 	},
 	"docs_policy": {
 		"$comment": "C33 docs-coherence policy. Override via /apt:setup Batch 7. Keys are globs/paths; values are 'auto-update' | 'flag-drift' | 'skip'. Missing block → defaults from packages/framework/templates/docs-policy-defaults.json apply."
 	},
+	"changelog": {
+		"$comment": "v5 — persona-aware changelog + release-notes system. Two surfaces: dev changelog (CHANGELOG.md from commits, default ON) and user-facing release notes (docs/releases, default OFF). Opt in per project via /apt:setup Batch 9. See packages/framework/skills/apt-release-notes/SKILL.md.",
+		"dev": {
+			"enabled": true,
+			"file": "CHANGELOG.md",
+			"format": "keep-a-changelog",
+			"source": "commits"
+		},
+		"release_notes": {
+			"enabled": false,
+			"audience": null,
+			"output_dir": "docs/releases",
+			"persona_filter": "primary+secondary",
+			"require_pr_field": true,
+			"draft": {
+				"on_pr_merge": true,
+				"fragments_dir": "docs/releases/_unreleased"
+			},
+			"compile": {
+				"on_tag": true
+			},
+			"publish": {
+				"targets": ["github-release"]
+			}
+		}
+	},
 	"router": {
 		"llm": {
 			"enabled": true,

package/workflows/docs.md

@@ -90,6 +90,18 @@ Gather facts from the actual codebase. The depth depends on doc type:
 - Conventional commit messages to categorize changes
 - Breaking changes (commits with `BREAKING CHANGE` or `!:`)
 
+> **Two-skill split (v0.7.0+).** `/apt:docs changelog` owns the
+> dev-flavored `CHANGELOG.md` surface — internal task IDs, file paths,
+> schema-bump notes, process trivia. For the user-facing complement,
+> projects can opt in to `/apt:release-notes` via `/apt:setup` →
+> Batch 9. That skill produces persona-voice-tuned release notes
+> (towncrier-style fragments at PR-merge time, compiled per tag, pushed
+> to GitHub Releases). The two skills coexist intentionally: a single
+> `--audience` flag inside `/apt:docs changelog` drifts to a
+> lowest-common-denominator artifact that satisfies neither audience.
+> See `packages/framework/skills/apt-release-notes/SKILL.md` for the
+> opt-in surface and the three modes (draft / compile / publish).
+
 ### For Contributing
 - Development setup steps (verified by checking file existence)
 - Test commands (verified by running them)