@aperant/framework 0.6.6 → 0.6.7

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

@@ -0,0 +1,120 @@
+/**
+ * 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' };
+}
+//# sourceMappingURL=draft.mjs.map

package/dist/cli/release-notes/draft.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.mjs","sourceRoot":"","sources":["../../../src/cli/release-notes/draft.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAEnD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAAC,KAAK;IACnC,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAA;IACnF,MAAM,WAAW,GAChB,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,YAAY,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;IACxF,OAAO;QACN,QAAQ,KAAK,CAAC,EAAE,EAAE;QAClB,EAAE;QACF,SAAS,KAAK,CAAC,IAAI,EAAE;QACrB,OAAO,KAAK,CAAC,EAAE,EAAE;QACjB,WAAW;QACX,WAAW;QACX,EAAE;QACF,iBAAiB;QACjB,EAAE;QACF,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE;QACjB,EAAE;KACF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,oBAAoB,CAAC,UAAU,EAAE,EAAE;IAC3C,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,YAAY,CACvB,KAAK,EACL,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,CAAC,EAC3E,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAC1D,CAAA;QACD,OAAO,GAAG;aACR,KAAK,CAAC,IAAI,CAAC;aACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;aAC3B,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;IACjC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAA;IACV,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AAEH;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAK;IAC/B,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;IACrE,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAA;IACpD,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,MAAM,KAAK,CAAC,EAAE,KAAK,CAAC,CAAA;IAEvD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAChE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,oBAAoB,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,CAAA;IAEjF,MAAM,IAAI,GAAG,cAAc,CAAC;QAC3B,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,IAAI;QACJ,OAAO;KACP,CAAC,CAAA;IAEF,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC9C,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACvB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;QAC7D,CAAC;QACD,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAC7B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;IAC1D,CAAC;IACD,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAC7B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;AAC1D,CAAC"}

package/dist/cli/release-notes/output-dir.d.mts

@@ -0,0 +1,20 @@
+/**
+ * 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: string): void;
+/**
+ * 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: string, flagOverride: string | null): string;
+//# sourceMappingURL=output-dir.d.mts.map

package/dist/cli/release-notes/output-dir.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-dir.d.mts","sourceRoot":"","sources":["../../../src/cli/release-notes/output-dir.mjs"],"names":[],"mappings":"AAgBA;;;;;;;;GAQG;AACH,iCAHW,MAAM,GACJ,IAAI,CAWhB;AAED;;;;;;;GAOG;AACH,6CAJW,MAAM,gBACN,MAAM,GAAG,IAAI,GACX,MAAM,CASlB"}

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

@@ -0,0 +1,42 @@
+/**
+ * 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));
+}
+//# sourceMappingURL=output-dir.mjs.map

package/dist/cli/release-notes/output-dir.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-dir.mjs","sourceRoot":"","sources":["../../../src/cli/release-notes/output-dir.mjs"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAEtD,MAAM,kBAAkB,GAAG,eAAe,CAAA;AAE1C,mEAAmE;AACnE,MAAM,WAAW,GAAG,mBAAmB,CAAA;AAEvC;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,GAAG;IAC9B,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,+CAA+C,CAAC,CAAA;IACvF,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACd,mBAAmB,GAAG,oEAAoE,CAC1F,CAAA;IACF,CAAC;AACF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAU,EAAE,YAAY;IACxD,MAAM,MAAM,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAA;IAC5C,MAAM,UAAU,GAAG,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,CAAA;IAC/D,OAAO,OAAO,CACb,UAAU,EACV,YAAY,IAAI,CAAC,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAClF,CAAA;AACF,CAAC"}

package/dist/cli/release-notes/persona-filter.d.mts

@@ -0,0 +1,51 @@
+/**
+ * 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: string | null | undefined): boolean;
+/**
+ * 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: {
+    ui_json?: unknown;
+}): {
+    name: string;
+    tier: PersonaTier;
+} | null;
+/**
+ * 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: {
+    personas?: Array<{
+        ui_json?: unknown;
+    }>;
+} | null | undefined): Map<string, PersonaTier>;
+/**
+ * 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: string | null | undefined, tierMap: Map<string, PersonaTier>, mode: "primary" | "primary+secondary" | "all"): {
+    bucket: FilterBucket;
+    resolvedName: string | null;
+    resolvedTier: PersonaTier | null;
+};
+export type PersonaTier = "primary" | "secondary" | "tertiary" | "unknown";
+export type FilterBucket = "body" | "triage" | "filtered";
+//# sourceMappingURL=persona-filter.d.mts.map

package/dist/cli/release-notes/persona-filter.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persona-filter.d.mts","sourceRoot":"","sources":["../../../src/cli/release-notes/persona-filter.mjs"],"names":[],"mappings":"AAsCA;;;;;;;;GAQG;AACH,oCAHW,MAAM,GAAG,IAAI,GAAG,SAAS,GACvB,OAAO,CAKnB;AAED;;;;;;;GAOG;AACH,4CAHW;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAAG,IAAI,CAmBtD;AAED;;;;;GAKG;AACH,8CAHW;IAAE,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAC5D,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAYpC;AAED;;;;;;;GAOG;AACH,6CALW,MAAM,GAAG,IAAI,GAAG,SAAS,WACzB,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,QACxB,SAAS,GAAG,mBAAmB,GAAG,KAAK,GACrC;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,YAAY,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAsBnG;0BA5Fa,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS;2BAChD,MAAM,GAAG,QAAQ,GAAG,UAAU"}

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

@@ -0,0 +1,127 @@
+/**
+ * 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 };
+}
+//# sourceMappingURL=persona-filter.mjs.map

package/dist/cli/release-notes/persona-filter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"persona-filter.mjs","sourceRoot":"","sources":["../../../src/cli/release-notes/persona-filter.mjs"],"names":[],"mappings":"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"}

package/dist/cli/release-notes/publish.d.mts

@@ -0,0 +1,23 @@
+/**
+ * @param {PublishInput} input
+ * @returns {PublishResult}
+ */
+export function publishTag(input: PublishInput): PublishResult;
+export type PublishInput = {
+    projectDir: string;
+    tag: string;
+    outputDir: string | null;
+    dryRun: boolean;
+};
+export type PublishResult = {
+    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;
+};
+//# sourceMappingURL=publish.d.mts.map

package/dist/cli/release-notes/publish.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.d.mts","sourceRoot":"","sources":["../../../src/cli/release-notes/publish.mjs"],"names":[],"mappings":"AA0FA;;;GAGG;AACH,kCAHW,YAAY,GACV,aAAa,CAmCzB;;gBAzGa,MAAM;SACN,MAAM;eACN,MAAM,GAAG,IAAI;YACb,OAAO;;4BAIR;IACR,MAAM,EAAE,IAAI,CAAC;IACb,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG;IACF,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,cAAc,GAAG,iBAAiB,GAAG,WAAW,CAAC;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB"}

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

@@ -0,0 +1,125 @@
+/**
+ * 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 };
+}
+//# sourceMappingURL=publish.mjs.map

package/dist/cli/release-notes/publish.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.mjs","sourceRoot":"","sources":["../../../src/cli/release-notes/publish.mjs"],"names":[],"mappings":"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"}

package/dist/cli/release-notes/ship-autodraft.d.mts

@@ -0,0 +1,37 @@
+/**
+ * Compute the autodraft decision.
+ *
+ * @param {AutodraftInput} input
+ * @returns {AutodraftResult}
+ */
+export function decideAutodraft(input: AutodraftInput): AutodraftResult;
+export type FeatureDiffEntry = {
+    feature_id: string;
+    area?: string | undefined;
+    personas?: string[] | undefined;
+};
+export type AutodraftInput = {
+    featureDiff: FeatureDiffEntry[];
+    personasEnvelope: {
+        personas?: Array<{
+            ui_json?: unknown;
+        }>;
+    } | null;
+    personaFilter: "primary" | "primary+secondary" | "all";
+    requirePrField: boolean;
+};
+export type AutodraftResult = {
+    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;
+};
+//# sourceMappingURL=ship-autodraft.d.mts.map

package/dist/cli/release-notes/ship-autodraft.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ship-autodraft.d.mts","sourceRoot":"","sources":["../../../src/cli/release-notes/ship-autodraft.mjs"],"names":[],"mappings":"AAkDA;;;;;GAKG;AACH,uCAHW,cAAc,GACZ,eAAe,CA+B3B;;gBApEa,MAAM;;;;;iBAON,gBAAgB,EAAE;sBAClB;QAAE,QAAQ,CAAC,EAAE,KAAK,CAAC;YAAE,OAAO,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC,CAAA;KAAE,GAAG,IAAI;mBAClD,SAAS,GAAG,mBAAmB,GAAG,KAAK;oBACvC,OAAO;;8BAIR;IACR,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,GAAG;IACF,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,kBAAkB,GAAG,mBAAmB,CAAC;IACjD,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG;IACF,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,kBAAkB,GAAG,mBAAmB,CAAC;IACjD,OAAO,EAAE,MAAM,CAAC;CACjB"}