pantheon-opencode 2.0.0-beta.3 → 2.0.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,14 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- import { mkdirSync, writeFileSync } from 'node:fs'
4
- import { join } from 'node:path'
5
3
  import * as clack from '@clack/prompts'
6
- import {
7
- createDecisionRouterConfig,
8
- DECISION_ROUTER_PROVIDERS,
9
- DEFAULT_DECISION_ROUTER_CONFIG,
10
- migrateDecisionRouterConfig,
11
- } from './decision-router-config.mjs'
12
4
  import { PROMPT_CANCELED } from './prompt-result.mjs'
13
5
  import { strings } from './strings.mjs'
14
6
 
@@ -54,250 +46,9 @@ export async function promptReview(
54
46
  }
55
47
 
56
48
  /**
57
- * Collect interactive setup choices before the installer begins any writes.
58
- *
59
- * @param {{ components?: string[], defaultComponents?: string[], noMcp?: boolean, prompts?: typeof clack, isTTY?: boolean, env?: Record<string, string | undefined>, getDecisionRouterConfig?: (target: string) => unknown }} [options]
60
- * @returns {Promise<{ components?: Set<string>, target?: string, decisionRouterConfig?: object, decisionModelActivation?: object | null, decisionModelDeferredSetup?: object | null, canceled?: boolean, cancelPoint?: string }>}
61
- *
62
- * `cancelPoint` names the setup choice where the user stopped (`components` or
63
- * `target`), so the caller can print one explainable line and persist the same
64
- * stable key in the run record.
49
+ * Historical note (beta.5): `runInteractiveInstall` — the component/target/
50
+ * decision-model wizard — was removed. `init` is now defaults + the plan
51
+ * preview + ONE authorization (`promptReview`); everything the wizard used to
52
+ * ask lives in `/pantheon-settings` (gates, decision router, preset) or in
53
+ * explicit flags (`--components`, `--project`, `--decision-model`).
65
54
  */
66
- export async function runInteractiveInstall({
67
- components = [],
68
- defaultComponents = [],
69
- noMcp = false,
70
- env = process.env,
71
- getDecisionRouterConfig = () => DEFAULT_DECISION_ROUTER_CONFIG,
72
- prompts = clack,
73
- isTTY = isTerminal(),
74
- } = {}) {
75
- const isAllowed = (component) => !noMcp || component !== 'runtime'
76
- const defaults = (defaultComponents.length > 0 ? defaultComponents : components).filter(isAllowed)
77
- const defaultSet = new Set(defaults)
78
-
79
- // Preserve the same component and target defaults without asking a terminal
80
- // prompt library to access stdin. Apply authorization is handled once, after
81
- // the installer has built and displayed the complete plan. Re-read the
82
- // selected default target's preference so --interactive without a TTY does
83
- // not reset an existing provider choice or consent on update.
84
- if (!isTTY) {
85
- return {
86
- components: defaultSet,
87
- target: 'global',
88
- decisionRouterConfig: migrateDecisionRouterConfig(getDecisionRouterConfig('global')),
89
- }
90
- }
91
-
92
- prompts.intro?.('OpenCode Installer')
93
-
94
- const componentOptions = [
95
- { label: 'agents', value: 'agents', hint: 'Agent configurations and routing (14 agents)' },
96
- { label: 'skills', value: 'skills', hint: `Reusable skill workflows (${23} skills)` },
97
- { label: 'instructions', value: 'instructions', hint: 'AGENTS.md and instructional files' },
98
- { label: 'prompts', value: 'prompts', hint: 'Prompt templates for agents' },
99
- { label: 'commands', value: 'commands', hint: 'OpenCode command shortcuts' },
100
- { label: 'plugins', value: 'plugins', hint: 'TUI sidebar plugin' },
101
- { label: 'runtime', value: 'runtime', hint: 'Python venv + MCP server scripts' },
102
- ].filter((option) => isAllowed(option.value))
103
- const chosen = await prompts.multiselect({
104
- message: 'Select components to install:',
105
- options: componentOptions,
106
- initialValues: [...defaultSet],
107
- required: false,
108
- })
109
- if (cancelPrompt(prompts, chosen, 'components'))
110
- return { canceled: true, cancelPoint: 'components' }
111
-
112
- const selectedComponents = new Set(chosen.filter(isAllowed))
113
- if (selectedComponents.size === 0) {
114
- const S = strings()
115
- prompts.cancel?.(S.canceledAt(S.cancelPoints.components))
116
- return { canceled: true, cancelPoint: 'components' }
117
- }
118
-
119
- const target = await prompts.select({
120
- message: 'Install location:',
121
- options: [
122
- {
123
- label: 'Global directory',
124
- value: 'global',
125
- hint: '~/.config/opencode (shared across projects)',
126
- },
127
- { label: 'Current project', value: 'project', hint: './.opencode (scoped to this project)' },
128
- ],
129
- })
130
- if (cancelPrompt(prompts, target, 'target')) return { canceled: true, cancelPoint: 'target' }
131
-
132
- // The old four-option metadata prompt (Local/OpenAI/Jev/Auto) recorded an
133
- // installer preference that controlled nothing at runtime and confused
134
- // everyone. The interactive question is now the honest one: configure the
135
- // Jev decision model now (one write, explicit caps) or skip — the CLI
136
- // (`decision-router setup-model`) remains the later path either way. The
137
- // legacy installer-state record stays at its default (Local): metadata the
138
- // runtime never reads, while real consent lives in the user-level config
139
- // that setup-model writes.
140
- const jevActivation = await prompts.select({
141
- message:
142
- 'Configure the Jev decision model now? (Console, OpenRouter, and TypeSafe activate here; Cloudflare is provisioned after install)',
143
- options: [
144
- {
145
- label: 'Skip (default)',
146
- value: 'skip',
147
- hint: 'Configure later: decision-router setup-model',
148
- },
149
- {
150
- label: 'OpenCode Console Jev (stock)',
151
- value: 'opencode-console-jev/jev-1.13',
152
- hint: consoleJevHint(env),
153
- },
154
- {
155
- label: 'OpenRouter-hosted Jev',
156
- value: 'openrouter-jev/typesafe/jev-1.13',
157
- hint: openrouterJevHint(),
158
- },
159
- {
160
- label: 'TypeSafe Jev (direct)',
161
- value: 'typesafe-jev/jev-1.14.0',
162
- hint: typesafeJevHint(env),
163
- },
164
- {
165
- label: 'Cloudflare Clef (provision after install)',
166
- value: 'cloudflare-workers-jev/clef',
167
- hint: cloudflareJevHint(env),
168
- },
169
- ],
170
- initialValue: 'skip',
171
- })
172
- if (cancelPrompt(prompts, jevActivation, 'decisionRouter')) {
173
- return { canceled: true, cancelPoint: 'decisionRouter' }
174
- }
175
-
176
- // Decision-layer options: the shadow gates and the specialist-caller
177
- // allowlist are first-class setup choices. The installer writes a flags
178
- // file the user sources (the host reads these at plugin registration from
179
- // its own environment — the installer never edits shell profiles silently).
180
- const jevFlags = await prompts.multiselect({
181
- message:
182
- 'Decision layer extras (shadow gates are observe-only; specialist access is explicit):',
183
- options: [
184
- {
185
- label: 'J1 risk-score shadow gate',
186
- value: 'PANTHEON_J1_RISK_SCORE=on',
187
- hint: 'Records a Jev risk-score per exfil-capable tool call; observe-only',
188
- },
189
- {
190
- label: 'J3 escalation shadow classifier',
191
- value: 'PANTHEON_J3_ESCALATION=on',
192
- hint: 'Records cheap-vs-main per delegate dispatch; never applies overrides in shadow',
193
- },
194
- {
195
- label: 'Specialist callers: athena + themis (explicit questions)',
196
- value: 'PANTHEON_JEV_SPECIALIST_CALLERS=athena,themis',
197
- hint: 'Allowlisted specialists may ask bounded Jev questions mid-task; presets stay Zeus-only',
198
- },
199
- ],
200
- required: false,
201
- // Ship-enabled default (field beta.16→28: the owner's setup ships the
202
- // decision layer ON — J1/J3 in shadow are observe-only and safe; the
203
- // user can uncheck any of them before confirming).
204
- initialValues: [
205
- 'PANTHEON_J1_RISK_SCORE=on',
206
- 'PANTHEON_J3_ESCALATION=on',
207
- 'PANTHEON_JEV_SPECIALIST_CALLERS=athena,themis',
208
- ],
209
- })
210
- if (cancelPrompt(prompts, jevFlags, 'decisionFlags')) {
211
- return { canceled: true, cancelPoint: 'decisionFlags' }
212
- }
213
- // Cloudflare needs an account-specific host provider entry. It remains an
214
- // explicit deferred choice; setup-model must receive --account-id before any
215
- // route is enabled.
216
- const KNOWN_JEV_TARGETS = new Set([
217
- 'opencode-console-jev/jev-1.13',
218
- 'openrouter-jev/typesafe/jev-1.13',
219
- 'typesafe-jev/jev-1.14.0',
220
- ])
221
- const cloudflareDeferred = jevActivation === 'cloudflare-workers-jev/clef'
222
- const activationChoice =
223
- typeof jevActivation === 'string' && KNOWN_JEV_TARGETS.has(jevActivation)
224
- ? jevActivation
225
- : 'skip'
226
- let decisionModelActivation = null
227
- const decisionModelDeferredSetup = cloudflareDeferred
228
- ? { target: 'cloudflare-workers-jev/clef' }
229
- : null
230
- if (activationChoice !== 'skip') {
231
- // Caps prompts degrade to the recommended defaults when the prompt
232
- // implementation has no text input (stubbed tests, restricted TTYs).
233
- const askText = async (message, fallback) => {
234
- if (typeof prompts.text !== 'function') return fallback
235
- const answer = await prompts.text({ message, defaultValue: fallback, placeholder: fallback })
236
- if (cancelPrompt(prompts, answer, 'decisionRouter')) {
237
- return { canceled: true }
238
- }
239
- return String(answer || fallback)
240
- }
241
- const monthly = await askText('Monthly USD cap for decision calls (e.g. 5)', '5')
242
- if (monthly && typeof monthly === 'object') {
243
- return { canceled: true, cancelPoint: 'decisionRouter' }
244
- }
245
- const perDecision = await askText('Per-decision USD cap (e.g. 0.10)', '0.10')
246
- if (perDecision && typeof perDecision === 'object') {
247
- return { canceled: true, cancelPoint: 'decisionRouter' }
248
- }
249
- decisionModelActivation = {
250
- target: activationChoice,
251
- monthly: String(monthly || '5'),
252
- perDecision: String(perDecision || '0.10'),
253
- }
254
- }
255
-
256
- // Empty/absent caller allowlist is intentionally Zeus-only. Persist that
257
- // default too, so rerunning the wizard cannot leave a prior allowlist active.
258
- const selectedFlags = Array.isArray(jevFlags) ? jevFlags : []
259
- const hasCallerFlag = selectedFlags.some((flag) =>
260
- flag.startsWith('PANTHEON_JEV_SPECIALIST_CALLERS='),
261
- )
262
- const flagsDir = join(env.XDG_CONFIG_HOME || `${env.HOME}/.config`, 'pantheon')
263
- mkdirSync(flagsDir, { recursive: true, mode: 0o700 })
264
- const flagsPath = join(flagsDir, 'decision-flags.env')
265
- const lines = selectedFlags.map((flag) => `export ${flag}`)
266
- if (!hasCallerFlag) lines.push('export PANTHEON_JEV_SPECIALIST_CALLERS=')
267
- writeFileSync(
268
- flagsPath,
269
- `# Pantheon decision layer — source from your shell profile\n${lines.join('\n')}\n`,
270
- )
271
-
272
- return {
273
- components: selectedComponents,
274
- target,
275
- decisionRouterConfig: createDecisionRouterConfig(DECISION_ROUTER_PROVIDERS[0], false),
276
- decisionModelActivation,
277
- decisionModelDeferredSetup,
278
- }
279
- }
280
-
281
- /** Credential-state hints for the Jev wizard routes (set at prompt time). */
282
- function consoleJevHint(env = process.env) {
283
- return env.OPENCODE_API_KEY
284
- ? 'Zen credits via OPENCODE_API_KEY — ✓ detected in this shell'
285
- : 'Zen credits via OPENCODE_API_KEY — export it first (opencode.ai/console)'
286
- }
287
-
288
- function openrouterJevHint() {
289
- return 'Uses the host OpenRouter credential (opencode auth list); billed per decision'
290
- }
291
-
292
- function typesafeJevHint(env = process.env) {
293
- return env.TYPESAFE_API_KEY
294
- ? '✓ TYPESAFE_API_KEY detected — the installer merges the provider entry'
295
- : 'export TYPESAFE_API_KEY first; the installer merges the provider entry'
296
- }
297
-
298
- function cloudflareJevHint(env = process.env) {
299
- const tokenHint = env.CLOUDFLARE_API_TOKEN
300
- ? 'CLOUDFLARE_API_TOKEN detected'
301
- : 'requires a Workers AI-scoped CLOUDFLARE_API_TOKEN'
302
- return `${tokenHint}; not activated by this wizard. After install run: npx pantheon-opencode decision-router setup-model cloudflare-workers-jev/clef --account-id=<32-hex-id> --monthly-usd 5 --per-decision-usd 0.10`
303
- }
@@ -1617,13 +1617,13 @@ async function installPass(
1617
1617
  const componentSet = new Set(
1618
1618
  opts.noMcp ? components.filter((component) => component !== 'runtime') : components,
1619
1619
  )
1620
- let decisionRouterConfig = migrateDecisionRouterConfig(
1620
+ const decisionRouterConfig = migrateDecisionRouterConfig(
1621
1621
  opts.decisionRouterConfig ?? readState(target)?.decision_router,
1622
1622
  )
1623
1623
  /** Wizard-confirmed Jev activation (target + caps), surfaced on the result. */
1624
- let decisionModelActivation = null
1624
+ const decisionModelActivation = null
1625
1625
  /** Cloudflare needs a user-supplied account ID, so the wizard defers it. */
1626
- let decisionModelDeferredSetup = null
1626
+ const decisionModelDeferredSetup = null
1627
1627
  const stats = summary.opencode
1628
1628
  // Per-call baseline. `stats` is the module-level cumulative summary, so the
1629
1629
  // consistency guard must compare against THIS call's delta, not the total.
@@ -1752,64 +1752,6 @@ async function installPass(
1752
1752
  const autoYes = opts.yes === true
1753
1753
  const interactive = !autoYes && (forceInteractive || (stdinTTY && !forceHeadless))
1754
1754
 
1755
- if (interactive && !dryRun) {
1756
- const { runInteractiveInstall } = await import('./interactive.mjs')
1757
- const hasRequestedComponents = Array.isArray(opts.requestedComponents)
1758
- const promptComponents = hasRequestedComponents ? opts.requestedComponents : components
1759
- const promptDefaults = (hasRequestedComponents ? opts.requestedComponents : components).filter(
1760
- (component) => !opts.noMcp || component !== 'runtime',
1761
- )
1762
- const result = await runInteractiveInstall({
1763
- components: promptComponents,
1764
- defaultComponents: promptDefaults,
1765
- noMcp: opts.noMcp === true,
1766
- getDecisionRouterConfig: (selection) => {
1767
- const selectionTarget = selection === 'project' ? process.cwd() : target
1768
- return readState(selectionTarget)?.decision_router
1769
- },
1770
- prompts: opts.deps?.prompts,
1771
- isTTY: opts.deps?.isTTY,
1772
- env: opts.deps?.env ?? opts.env ?? process.env,
1773
- })
1774
-
1775
- // Resolve the location from the SELECTION before any cancel return: a
1776
- // cancel after the user picked "Current project" must record that
1777
- // directory, not the global default the caller would fall back to. The
1778
- // recorded target is where the user was installing, not where a file was
1779
- // written (nothing was written either way).
1780
- const selectedTarget = result.target === 'project' ? process.cwd() : target
1781
- opts.onTargetResolved?.(selectedTarget)
1782
-
1783
- if (result.canceled) {
1784
- // The named point is what makes the message explainable. The interactive
1785
- // module already printed the single cancel line through the prompt
1786
- // library's own cancel channel, so printing another one here was the
1787
- // duplicate the issue reports: the user saw the same sentence twice and
1788
- // learned nothing about WHERE it stopped.
1789
- return {
1790
- ...stats,
1791
- applied: false,
1792
- reason: 'canceled',
1793
- cancelPoint: result.cancelPoint ?? 'components',
1794
- target: selectedTarget,
1795
- }
1796
- }
1797
-
1798
- // Map target selection to actual path
1799
- const newComponents = [...result.components].filter(
1800
- (component) => !opts.noMcp || component !== 'runtime',
1801
- )
1802
- componentSet.clear()
1803
- for (const c of newComponents) componentSet.add(c)
1804
-
1805
- target = selectedTarget
1806
- decisionRouterConfig = migrateDecisionRouterConfig(result.decisionRouterConfig)
1807
- opts.decisionRouterConfig = decisionRouterConfig
1808
- decisionModelActivation = result.decisionModelActivation ?? null
1809
- decisionModelDeferredSetup = result.decisionModelDeferredSetup ?? null
1810
- if (!dryRun && _lastRun) _lastRun.target = target
1811
- }
1812
-
1813
1755
  // Reject invalid or newer persisted migration schemas before planning or
1814
1756
  // applying any target writes. The migration runner repeats this check at the
1815
1757
  // actual migration point to catch a marker changed during the install.
@@ -3263,21 +3205,10 @@ async function installPass(
3263
3205
  // -----------------------------------------------------------------------
3264
3206
 
3265
3207
  // -----------------------------------------------------------------------
3266
- // 5.5 Optional vision prompt (interactive TTY only). The default — automatic
3267
- // discovery — writes nothing, and non-interactive flows (no TTY, --yes,
3268
- // --headless, automated sandboxes) never reach this block, so no run
3269
- // blocks on stdin and the default behavior is unchanged. A failure here
3270
- // must never fail the install: vision stays optional.
3208
+ // 5.5 Vision setup moved out of the wizard (beta.5): the default — automatic
3209
+ // discovery — writes nothing, and pinning is `/pantheon-vision`. The
3210
+ // install never blocks on stdin here.
3271
3211
  // -----------------------------------------------------------------------
3272
- if (interactive && !dryRun && !autoYes && stats.errors === 0) {
3273
- const runVisionPrompt =
3274
- opts.deps?.runVisionPrompt ?? (await import('./vision-prompt.mjs')).runVisionPrompt
3275
- try {
3276
- await runVisionPrompt({ logger: console })
3277
- } catch (err) {
3278
- warning(`Vision setup skipped: ${err instanceof Error ? err.message : String(err)}`)
3279
- }
3280
- }
3281
3212
 
3282
3213
  // Record component state even on a degraded runtime result so doctor and a
3283
3214
  // later init can distinguish a failed runtime from an installed one. The
@@ -16,7 +16,8 @@
16
16
  * headlessly, driven through a live host, and compared file-by-file
17
17
  * against the checkout.
18
18
  * package The same .tgz re-hashed and inspected. No second `npm pack`.
19
- * changelog The committed `[version]` section exists and is non-empty.
19
+ * changelog The committed `[version]` section exists, is non-empty, and
20
+ * follows the canonical format (scripts/changelog-format.mjs).
20
21
  * metadata Version manifests and the Node engine policy agree.
21
22
  *
22
23
  * Usage:
@@ -28,7 +29,7 @@
28
29
  * --version <x.y.z> Candidate version (default: package.json version).
29
30
  * --target-sha <sha> Full 40-hex candidate SHA (default: TARGET_SHA).
30
31
  * --channel stable|beta Release channel (default: RELEASE_CHANNEL|stable).
31
- * --recovery Recovery dispatch: changelog is the static note.
32
+ * --recovery Recovery dispatch: changelog checks the recovery tag.
32
33
  *
33
34
  * Host evidence: PANTHEON_RELEASE_MATRIX overrides the built-in JSON array. The
34
35
  * override is still validated: rows must name a supported family and may not
@@ -51,6 +52,7 @@ import {
51
52
  import { tmpdir } from 'node:os'
52
53
  import { basename, dirname, join, resolve } from 'node:path'
53
54
  import { fileURLToPath, pathToFileURL } from 'node:url'
55
+ import { validateSection } from './changelog-format.mjs'
54
56
 
55
57
  const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
56
58
 
@@ -93,7 +95,7 @@ const REQUIRED_TARBALL_PAYLOAD = [
93
95
  function usage(message) {
94
96
  console.error(`release-gates: ${message}`)
95
97
  console.error(
96
- 'usage: node scripts/release-gates.mjs <gate> --evidence-dir <dir> [--artifact-dir <dir>] [--version <v>] [--target-sha <sha>] [--channel stable|beta] [--recovery]',
98
+ 'usage: node scripts/release-gates.mjs <gate> --evidence-dir <dir> [--artifact-dir <dir>] [--version <v>] [--target-sha <sha>] [--channel stable|beta] [--changelog-path <file>] [--recovery]',
97
99
  )
98
100
  process.exit(2)
99
101
  }
@@ -115,7 +117,14 @@ function parseArgs(argv) {
115
117
  continue
116
118
  }
117
119
  if (
118
- ['--evidence-dir', '--artifact-dir', '--version', '--target-sha', '--channel'].includes(arg)
120
+ [
121
+ '--evidence-dir',
122
+ '--artifact-dir',
123
+ '--version',
124
+ '--target-sha',
125
+ '--channel',
126
+ '--changelog-path',
127
+ ].includes(arg)
119
128
  ) {
120
129
  const value = argv[i + 1]
121
130
  if (value === undefined) usage(`${arg} requires a value`)
@@ -450,7 +459,13 @@ function packageGate(options) {
450
459
 
451
460
  // ── Gate (e): changelog ──────────────────────────────────────────────────────
452
461
 
453
- function changelogGate(options) {
462
+ /**
463
+ * The committed `[version]` section exists, is non-empty, and follows the
464
+ * canonical format (scripts/changelog-format.mjs). The section IS the release
465
+ * body — the workflow extracts it verbatim — so a format violation here is a
466
+ * malformed release, and the release fails before anything is tagged.
467
+ */
468
+ export function changelogGate(options) {
454
469
  if (options.recovery) {
455
470
  const tag = run('recovery-tag', 'git', ['tag', '-l', `v${options.version}`], { echo: false })
456
471
  if (tag.output.trim() !== `v${options.version}`) {
@@ -463,17 +478,21 @@ function changelogGate(options) {
463
478
  details: { mode: 'recovery-static', version: options.version },
464
479
  }
465
480
  }
466
- const extraction = run(
467
- 'changelog-section',
468
- 'node',
469
- ['scripts/changelog-extract.mjs', options.version],
470
- {
471
- echo: false,
472
- },
473
- )
481
+ const extractArgs = ['scripts/changelog-extract.mjs', options.version]
482
+ if (options.changelogPath) extractArgs.push('--changelog', options.changelogPath)
483
+ const extraction = run('changelog-section', 'node', extractArgs, {
484
+ echo: false,
485
+ })
474
486
  if (!extraction.output.trim()) {
475
487
  throw new Error(`CHANGELOG.md has no non-empty [${options.version}] section`)
476
488
  }
489
+ const violations = validateSection(extraction.output, { label: `v${options.version}` })
490
+ if (violations.length > 0) {
491
+ throw new Error(
492
+ `CHANGELOG section [${options.version}] violates the canonical format ` +
493
+ `(docs/RELEASING.md — the section IS the release body):\n- ${violations.join('\n- ')}`,
494
+ )
495
+ }
477
496
  writeFileSync(join(options.evidenceDir, 'changelog.md'), extraction.output)
478
497
  return {
479
498
  checks: [{ ...extraction, output: undefined, sha256: sha256(extraction.output) }],
@@ -481,6 +500,7 @@ function changelogGate(options) {
481
500
  mode: 'committed-section',
482
501
  version: options.version,
483
502
  bytes: extraction.output.length,
503
+ formatViolations: 0,
484
504
  },
485
505
  }
486
506
  }
@@ -5,26 +5,34 @@
5
5
  * Bridges the conventional-commit pipeline (commitlint: 12 types / 40 scopes)
6
6
  * to the CHANGELOG / release-body content. Reads `git log <lastTag>..HEAD`
7
7
  * (subject + body per commit), groups commits by type, and prints markdown
8
- * ready to paste into the [Unreleased] CHANGELOG section.
8
+ * in the canonical CHANGELOG format (docs/RELEASING.md), ready to paste into
9
+ * the [Unreleased] CHANGELOG section.
9
10
  *
10
- * Groups (section order — user-facing first):
11
- * 🆕 What's New feat | perf | docs
12
- * (docs are user-facing — no dedicated group)
13
- * 🐞 Fixed fix | security
14
- * ⚠️ Known Issues manual — CLI flag `--known-issues "text"` (repeatable);
15
- * the group is OMITTED when the flag is absent (never
16
- * emitted empty)
17
- * ✅ Closed Issues issue refs parsed from commit BODIES (%b):
18
- * `Closes #N` / `Fixes #N` / `Resolves #N` — one
19
- * bullet `- #N - <subject>` per referenced issue
20
- * (deduped); the group is OMITTED when no refs exist
11
+ * Sections (Keep a Changelog, canonical order — empty ones omitted):
12
+ * ### Added feat
13
+ * ### Changed perf | docs
14
+ * ### Fixed fix
15
+ * ### Security security
16
+ * ### ⚠️ Known Issues manual — CLI flag `--known-issues "text"`
17
+ * (repeatable); omitted when the flag is absent
18
+ * ### ✅ Closed Issues issue refs parsed from commit BODIES (%b):
19
+ * `Closes #N` / `Fixes #N` / `Resolves #N` — one
20
+ * bullet `- #N - <subject>` per referenced issue
21
+ * (deduped); omitted when no refs exist
22
+ *
23
+ * The curated `### 🆕 What's New` highlights block is NOT generated: it is
24
+ * authored by hand on top of the generated sections in the bump PR (≤6
25
+ * bullets, ≤140 chars — the TUI window contract).
26
+ *
27
+ * Deprecated / Removed have no commit type; their sections are authored by
28
+ * hand when the release needs them.
21
29
  *
22
30
  * Omitted (internal, never user-facing): release scope and chore | refactor |
23
31
  * test | ci | build | style | revert (unknown conventional types too).
24
32
  *
25
33
  * Breaking: `BREAKING CHANGE` footer or `type!:` / `type(scope)!:` — the
26
- * commit keeps its type bucket and the bullet is prefixed with 💥
27
- * (e.g. `- 💥 **scope** — subject`). No dedicated Breaking group.
34
+ * commit keeps its section and the bullet is prefixed with 💥
35
+ * (e.g. `- 💥 **scope** — subject`). No dedicated Breaking section.
28
36
  *
29
37
  * Skipped: merge commits ("Merge ..."), empty-subject commits (trivial
30
38
  * chores), and non-conventional subjects (grandfathered history only).
@@ -178,45 +186,48 @@ export function parseCommitLine(line) {
178
186
  }
179
187
 
180
188
  /**
181
- * Conventional type → final release-note group. Types missing from this map
182
- * (chore, refactor, test, ci, build, style, revert, unknown) are internal
189
+ * Conventional type → canonical CHANGELOG section. Types missing from this
190
+ * map (chore, refactor, test, ci, build, style, revert, unknown) are internal
183
191
  * and omitted from the notes. The maintainer-only `release` scope is also
184
192
  * omitted, including its issue references.
185
193
  */
186
- const TYPE_GROUPS = {
187
- feat: 'whatsNew',
188
- perf: 'whatsNew',
189
- docs: 'whatsNew',
194
+ const TYPE_SECTIONS = {
195
+ feat: 'added',
196
+ perf: 'changed',
197
+ docs: 'changed',
190
198
  fix: 'fixed',
191
- security: 'fixed',
199
+ security: 'security',
192
200
  }
193
201
 
194
202
  /**
195
- * Group parsed commits into the final release-note sections. Breaking
196
- * commits keep their type bucket (the 💥 marker is applied at render time);
197
- * internal types and the `release` scope are dropped; issue refs from remaining
198
- * commit bodies feed closedIssues (deduped, first occurrence wins). Entries
199
- * keep git log order.
203
+ * Group parsed commits into the canonical release-note sections. Breaking
204
+ * commits keep their section (the 💥 marker is applied at render time);
205
+ * internal types and the `release` scope are dropped; issue refs from
206
+ * remaining commit bodies feed closedIssues (deduped, first occurrence wins).
207
+ * Entries keep git log order.
200
208
  *
201
209
  * @param {Array<ReturnType<typeof parseCommitLine>>} entries
202
210
  * @param {{knownIssues?: string[]|string|null}} [options]
203
211
  * knownIssues — manual Known Issues entries (CLI --known-issues). Omitted
204
212
  * (empty array) when not provided.
205
- * @returns {{whatsNew: Array, fixed: Array, knownIssues: string[],
213
+ * @returns {{added: Array, changed: Array, fixed: Array, security: Array,
214
+ * knownIssues: string[],
206
215
  * closedIssues: Array<{ref: number, subject: string}>}}
207
216
  */
208
217
  export function groupCommits(entries, options = {}) {
209
218
  const { knownIssues = [] } = options
210
219
  const groups = {
211
- whatsNew: [],
220
+ added: [],
221
+ changed: [],
212
222
  fixed: [],
223
+ security: [],
213
224
  knownIssues: Array.isArray(knownIssues) ? [...knownIssues] : knownIssues ? [knownIssues] : [],
214
225
  closedIssues: [],
215
226
  }
216
227
  const seenRefs = new Set()
217
228
  for (const entry of entries) {
218
229
  if (!entry || entry.scope === 'release') continue
219
- const bucket = TYPE_GROUPS[entry.type]
230
+ const bucket = TYPE_SECTIONS[entry.type]
220
231
  if (bucket) groups[bucket].push(entry)
221
232
  for (const ref of entry.refs) {
222
233
  if (seenRefs.has(ref)) continue
@@ -245,10 +256,14 @@ function closedIssueBullet({ ref, subject }) {
245
256
  return subject ? `- #${ref} - ${subject}` : `- #${ref}`
246
257
  }
247
258
 
248
- /** Section order — user-facing first, Known Issues then Closed Issues. */
259
+ /** Section order — canonical (docs/RELEASING.md): KaC first, Known/Closed
260
+ * Issues last. Rendered as `### ` so the section stays inside the
261
+ * changelog-extract boundaries. */
249
262
  const MARKDOWN_SECTIONS = [
250
- ['whatsNew', "🆕 What's New"],
251
- ['fixed', '🐞 Fixed'],
263
+ ['added', 'Added'],
264
+ ['changed', 'Changed'],
265
+ ['fixed', 'Fixed'],
266
+ ['security', 'Security'],
252
267
  ['knownIssues', '⚠️ Known Issues'],
253
268
  ['closedIssues', '✅ Closed Issues'],
254
269
  ]
@@ -261,7 +276,7 @@ function renderEntry(key, entry) {
261
276
  }
262
277
 
263
278
  /**
264
- * Render grouped commits as emoji-sectioned markdown (the CLI stdout and the
279
+ * Render grouped commits as canonical markdown (the CLI stdout and the
265
280
  * CHANGELOG body). Returns '' when there is nothing to report.
266
281
  *
267
282
  * @param {ReturnType<typeof groupCommits>} groups
@@ -271,7 +286,7 @@ export function renderMarkdown(groups) {
271
286
  const blocks = []
272
287
  for (const [key, heading] of MARKDOWN_SECTIONS) {
273
288
  if (!groups[key]?.length) continue
274
- blocks.push(`## ${heading}\n${groups[key].map((entry) => renderEntry(key, entry)).join('\n')}`)
289
+ blocks.push(`### ${heading}\n${groups[key].map((entry) => renderEntry(key, entry)).join('\n')}`)
275
290
  }
276
291
  return blocks.join('\n\n')
277
292
  }
@@ -279,8 +294,8 @@ export function renderMarkdown(groups) {
279
294
  /**
280
295
  * Render grouped commits for a CHANGELOG version entry. Used by
281
296
  * `versioning.mjs apply --notes` to pre-fill the promoted [Unreleased] entry.
282
- * Emits the SAME final emoji groups as renderMarkdown — the CHANGELOG uses
283
- * the emoji format.
297
+ * Emits the SAME canonical sections as renderMarkdown — the curated
298
+ * `### 🆕 What's New` highlights block is authored by hand on top.
284
299
  *
285
300
  * @param {ReturnType<typeof groupCommits>} groups
286
301
  * @returns {string}