peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/release-commands.js

@@ -18,308 +18,35 @@
  *
  * Real deployment (k8s rollout, LB config, monitoring integration) is
  * OUT OF SCOPE for this slice.
+ *
+ * The verb implementations live beside this file, one module per verb:
+ * `release-plan-command.ts`, `release-canary-command.ts`,
+ * `release-promote-command.ts`, `release-watch-command.ts`,
+ * `release-done-command.ts`, `release-rollback-command.ts`,
+ * `release-hotfix-command.ts`, `release-precheck-command.ts`, with their shared
+ * project-root / canary-percent vocabulary in `release-command-shared.ts`.
  */
-import { findProjectRoot } from '../../services/config/config-safety.js';
-import { hotfixRelease, isReleaseStage, planRelease, readReleaseState, rollbackRelease, transitionRelease, watchWindow, writeReleaseState } from '../../services/release/release-state.js';
-import { runAllLayers } from '../../services/release/version-precheck-service.js';
-import { runChangesetHardGate } from '../../services/changeset/changeset-check-service.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-import { addJsonOption, printResult } from '../cli-helpers.js';
-const CANARY_PERCENTS = {
-    10: 'canary-10',
-    50: 'canary-50'
-};
-// precheck-guard via direct function call (not via program.parseAsync with a
-// mocked service). Returns the result envelope for the caller to print.
-export function executeCanaryAction(opts, io, projectRoot) {
-    // this function is called (step 0 short-circuits with CHANGESET_BLOCKED).
-    // Layers C/D default warning → do not block canary; --strict upgrade would
-    // Layers C/D default warning → do not block canary; --strict upgrade would
-    const precheck = runAllLayers({ projectRoot, strict: false });
-    const blockerEntry = Object.entries(precheck.layers).find(([, l]) => l.status === 'blocker');
-    if (blockerEntry !== undefined) {
-        const [name, result] = blockerEntry;
-        return {
-            ok: false,
-            status: 'PRECHECK_BLOCKER',
-            blockerLayer: { name, result },
-            payload: {
-                projectRoot,
-                precheckSnapshotAt: precheck.snapshotAt,
-                layer: name,
-                message: result.message,
-                remediation: result.remediation
-            }
-        };
-    }
-    const percent = Number.parseInt(opts.percent, 10);
-    if (percent !== 10 && percent !== 50) {
-        return {
-            ok: false,
-            status: 'INVALID_PERCENT',
-            payload: { projectRoot, got: opts.percent }
-        };
-    }
-    const state = readReleaseState(projectRoot);
-    const targetStage = CANARY_PERCENTS[percent];
-    const result = transitionRelease(state, targetStage, opts.note);
-    if ('error' in result) {
-        return {
-            ok: false,
-            status: 'INVALID_TRANSITION',
-            payload: { projectRoot, error: result.error }
-        };
-    }
-    writeReleaseState(projectRoot, result.state);
-    return {
-        ok: true,
-        status: 'OK',
-        payload: {
-            projectRoot,
-            percent,
-            currentStage: targetStage,
-            nextAction: percent === 10 ? 'peaks release canary --percent 50' : 'peaks release promote'
-        }
-    };
-}
+import { registerReleaseCanaryCommand } from './release-canary-command.js';
+import { registerReleasePrecheckCommand } from './release-precheck-command.js';
+import { registerReleaseDoneCommand } from './release-done-command.js';
+import { registerReleaseHotfixCommand } from './release-hotfix-command.js';
+import { registerReleasePlanCommand } from './release-plan-command.js';
+import { registerReleasePromoteCommand } from './release-promote-command.js';
+import { registerReleaseRollbackCommand } from './release-rollback-command.js';
+import { registerReleaseWatchCommand } from './release-watch-command.js';
 export function registerReleaseCommands(program, io) {
     const release = program
         .command('release')
         .description('v2.15.0 follow-up G15: canary → promote → watch → done / hotfix state machine.');
-    // 1. plan
-    addJsonOption(release
-        .command('plan <version>')
-        .description('Start a new release. Stores the version in the canary pipeline state. ' +
-        'Fails when there is already an active release in any non-terminal stage.')
-        .option('--project <path>', 'project root (default: cwd)')).action((version, opts) => {
-        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const state = readReleaseState(projectRoot);
-        const result = planRelease(state, version);
-        if ('error' in result) {
-            printResult(io, fail('release.plan', 'CONFLICT', result.error, { projectRoot }, [
-                'Run `peaks release rollback` or `peaks release hotfix` to clear the active release.'
-            ]), opts.json ?? false);
-            return;
-        }
-        writeReleaseState(projectRoot, result.state);
-        printResult(io, ok('release.plan', {
-            projectRoot,
-            version: result.record.version,
-            currentStage: result.record.currentStage
-        }, [], ['Run `peaks release canary --percent 10` to begin the canary phase.']), opts.json ?? false);
-    });
-    addJsonOption(release
-        .command('canary')
-        .description('Advance the active release to a canary stage. Two percent values supported: ' +
-        '10 (first canary, requires stage=planned) and 50 (second canary, requires ' +
-        'stage=canary-10). Runs `peaks release precheck` first and refuses with ' +
-        'PRECHECK_BLOCKER if any blocker layer (rootVsShared or tagCollision) fails.')
-        .requiredOption('--percent <10|50>', 'canary percent (10 or 50)')
-        .option('--note <text>', 'optional note for the stage transition')
-        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
-        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const gate = runChangesetHardGate(projectRoot);
-        if (gate.state === 'staged-present') {
-            process.exitCode = 1;
-            printResult(io, fail('release.canary', 'CHANGESET_BLOCKED', `${gate.stagedFiles.length} staged .changeset/*.md file(s) — refusing canary`, {
-                projectRoot,
-                state: gate.state,
-                stagedFiles: [...gate.stagedFiles],
-                snapshotAt: gate.snapshotAt
-            }, [
-                `Drain pending changesets (coordinating LLM: drain via the standard changeset consumption path), then re-run \`peaks changeset check --project ${projectRoot}\` to confirm clean state.`
-            ]), opts.json ?? false);
-            return;
-        }
-        const result = executeCanaryAction(opts, io, projectRoot);
-        if (result.status === 'PRECHECK_BLOCKER') {
-            const layer = result.blockerLayer;
-            printResult(io, fail('release.canary', 'PRECHECK_BLOCKER', `precheck blocker on layer '${layer?.name ?? 'unknown'}': ${layer?.result.message ?? ''}`, result.payload, [
-                `Run 'peaks release precheck --project ${projectRoot}' for the full 4-layer envelope.`,
-                `Run 'peaks release precheck --strict' to also surface warning-layer issues.`,
-                `Remediation: ${layer?.result.remediation ?? ''}`
-            ]), opts.json ?? false);
-            return;
-        }
-        if (result.status === 'INVALID_PERCENT') {
-            printResult(io, fail('release.canary', 'INVALID_PERCENT', `--percent must be 10 or 50 (got "${opts.percent}")`, result.payload, []), opts.json ?? false);
-            return;
-        }
-        if (result.status === 'INVALID_TRANSITION') {
-            printResult(io, fail('release.canary', 'INVALID_TRANSITION', String(result.payload['error'] ?? ''), result.payload, []), opts.json ?? false);
-            return;
-        }
-        printResult(io, ok('release.canary', result.payload, [], []), opts.json ?? false);
-    });
-    // 3. promote
-    addJsonOption(release
-        .command('promote')
-        .description('Promote the canary to 100% (full release). Requires stage=canary-50. ' +
-        'Records the promoted-at timestamp and starts the 24h watch window.')
-        .option('--note <text>', 'optional note')
-        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
-        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const state = readReleaseState(projectRoot);
-        const result = transitionRelease(state, 'promoted', opts.note);
-        if ('error' in result) {
-            printResult(io, fail('release.promote', 'INVALID_TRANSITION', result.error, { projectRoot }, []), opts.json ?? false);
-            return;
-        }
-        writeReleaseState(projectRoot, result.state);
-        printResult(io, ok('release.promote', {
-            projectRoot,
-            currentStage: 'promoted',
-            promotedAt: result.state.active?.promotedAt
-        }, [], [
-            'Watch window started. Run `peaks release watch` to check progress; `peaks release rollback` for emergency.'
-        ]), opts.json ?? false);
-    });
-    // 4. watch
-    addJsonOption(release
-        .command('watch')
-        .description('Show the watch window status for the current promoted release. ' +
-        '24h window from promoted-at. After the window, run `peaks release done` ' +
-        'to mark the release complete.')
-        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
-        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const state = readReleaseState(projectRoot);
-        if (state.active === null) {
-            printResult(io, fail('release.watch', 'NO_ACTIVE', 'no active release to watch', { projectRoot }, [
-                'Run `peaks release plan <version>` to start one.'
-            ]), opts.json ?? false);
-            return;
-        }
-        const win = watchWindow(state.active);
-        const readyForDone = win.percentComplete >= 1.0;
-        printResult(io, ok('release.watch', {
-            projectRoot,
-            version: state.active.version,
-            currentStage: state.active.currentStage,
-            window: {
-                elapsedMs: win.elapsedMs,
-                remainingMs: win.remainingMs,
-                windowMs: win.windowMs,
-                percentComplete: Math.round(win.percentComplete * 100) / 100
-            },
-            readyForDone
-        }, readyForDone
-            ? ['Watch window complete. Run `peaks release done` to mark the release done.']
-            : []), opts.json ?? false);
-    });
-    // 5. done (implicit helper; not in original spec but useful)
-    addJsonOption(release
-        .command('done')
-        .description('Mark the active release as done. Requires the watch window to be ' +
-        'complete (24h after promoted-at).')
-        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
-        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const state = readReleaseState(projectRoot);
-        if (state.active === null) {
-            printResult(io, fail('release.done', 'NO_ACTIVE', 'no active release', { projectRoot }, []), opts.json ?? false);
-            return;
-        }
-        // No stage guard here: `watching` is unreachable (nothing ever calls
-        // transitionRelease(state, 'watching')), so the real precondition is the
-        // watch window itself — the same thing this command's description
-        // documents ("Requires the watch window to be complete"). The stage
-        // table (`promoted → watching → done`) stays as the declared design, but
-        // `promoted` may now reach `done` directly.
-        const win = watchWindow(state.active);
-        if (win.percentComplete < 1.0) {
-            printResult(io, fail('release.done', 'WATCH_INCOMPLETE', `watch window not yet complete (${Math.round(win.percentComplete * 100)}% elapsed)`, { projectRoot }, []), opts.json ?? false);
-            return;
-        }
-        const result = transitionRelease(state, 'done');
-        if ('error' in result) {
-            printResult(io, fail('release.done', 'INVALID_TRANSITION', result.error, { projectRoot }, []), opts.json ?? false);
-            return;
-        }
-        // Move to history.
-        const finalRecord = result.state.active;
-        const newState = {
-            version: 1,
-            active: null,
-            history: [...result.state.history, finalRecord]
-        };
-        writeReleaseState(projectRoot, newState);
-        printResult(io, ok('release.done', {
-            projectRoot,
-            version: finalRecord.version,
-            doneAt: finalRecord.doneAt
-        }, [], []), opts.json ?? false);
-    });
-    // 6. rollback
-    addJsonOption(release
-        .command('rollback')
-        .description('Emergency rollback of the active release. Moves the active release to ' +
-        'the history with currentStage=rolled-back. Available from any ' +
-        'pre-done stage.')
-        .option('--note <text>', 'optional rollback reason')
-        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
-        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const state = readReleaseState(projectRoot);
-        const result = rollbackRelease(state, opts.note);
-        if ('error' in result) {
-            printResult(io, fail('release.rollback', 'INVALID_TRANSITION', result.error, { projectRoot }, []), opts.json ?? false);
-            return;
-        }
-        writeReleaseState(projectRoot, result.state);
-        printResult(io, ok('release.rollback', {
-            projectRoot,
-            rolledBack: result.record.version,
-            finalStage: result.record.currentStage
-        }, [], ['Run `peaks release hotfix <version>` to start a hotfix on the previous release.']), opts.json ?? false);
-    });
-    // 7. hotfix
-    addJsonOption(release
-        .command('hotfix <version>')
-        .description('Start a hotfix release. Forces a rollback of any active release, ' +
-        'skips the `planned` stage, and starts the new release at canary-10. ' +
-        'Use this for紧急修复 — minimal ceremony, no full prd ceremony.')
-        .option('--note <text>', 'optional hotfix note')
-        .option('--project <path>', 'project root (default: cwd)')).action((version, opts) => {
-        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const changesetGate = runChangesetHardGate(projectRoot);
-        if (changesetGate.state === 'staged-present') {
-            process.exitCode = 1;
-            printResult(io, fail('release.hotfix', 'CHANGESET_BLOCKED', `${changesetGate.stagedFiles.length} staged .changeset/*.md file(s) — refusing to start hotfix`, {
-                projectRoot,
-                stagedFiles: [...changesetGate.stagedFiles],
-                snapshotAt: changesetGate.snapshotAt
-            }, [
-                `Drain pending changesets (coordinating LLM: drain via the standard changeset consumption path), then re-run \`peaks changeset check --project ${projectRoot}\` to confirm clean state.`
-            ]), opts.json ?? false);
-            return;
-        }
-        const state = readReleaseState(projectRoot);
-        const result = hotfixRelease(state, version, opts.note);
-        if ('error' in result) {
-            printResult(io, fail('release.hotfix', 'HOTFIX_FAILED', result.error, { projectRoot }, []), opts.json ?? false);
-            return;
-        }
-        writeReleaseState(projectRoot, result.state);
-        printResult(io, ok('release.hotfix', {
-            projectRoot,
-            version: result.record.version,
-            currentStage: result.record.currentStage
-        }, [], ['Hotfix started at canary-10. Run `peaks release canary --percent 50` to advance.']), opts.json ?? false);
-    });
-    addJsonOption(release
-        .command('precheck')
-        .description('Run the 4-layer version precheck (rootVsShared / tagCollision / ' +
-        'changesetStaged / workspaceLockstep). Layer A+B are blockers by default; ' +
-        'Layer C+D are warnings unless --strict is passed (CI parity mode). ' +
-        'Shared with publish.yml gate-cli-version step §(A).')
-        .option('--strict', 'treat warnings as blockers (CI parity mode)')
-        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
-        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const envelope = runAllLayers({ projectRoot, strict: opts.strict === true });
-        process.exitCode = envelope.ok ? 0 : 1;
-        const warningLines = envelope.overall === 'warning'
-            ? ['Warning layers reported but did not block. Re-run with --strict to upgrade.']
-            : [];
-        printResult(io, ok('release.precheck', envelope, [], warningLines), opts.json ?? false);
-    });
+    registerReleasePlanCommand(release, io);
+    registerReleaseCanaryCommand(release, io);
+    registerReleasePromoteCommand(release, io);
+    registerReleaseWatchCommand(release, io);
+    registerReleaseDoneCommand(release, io);
+    registerReleaseRollbackCommand(release, io);
+    registerReleaseHotfixCommand(release, io);
+    registerReleasePrecheckCommand(release, io);
 }
 // Re-export for tests / external consumers.
-export { isReleaseStage };
+export { executeCanaryAction } from './release-canary-command.js';
+export { isReleaseStage } from '../../services/release/release-state.js';

package/dist/cli/commands/release-done-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerReleaseDoneCommand(release: Command, io: ProgramIO): void;

package/dist/cli/commands/release-done-command.js

@@ -0,0 +1,64 @@
+// src/cli/commands/release-done-command.ts
+//
+// `peaks release done` — close the active release once the watch window is
+// complete. Split out of `release-commands.ts`; the verb name, its options, the
+// "no stage guard, the window is the precondition" ruling and the envelope
+// shape are unchanged.
+import { readReleaseState, transitionRelease, watchWindow, writeReleaseState } from '../../services/release/release-state.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { resolveReleaseProjectRoot } from './release-command-shared.js';
+function noActiveRelease(projectRoot) {
+    return fail('release.done', 'NO_ACTIVE', 'no active release', { projectRoot }, []);
+}
+function watchIncomplete(projectRoot, percentComplete) {
+    return fail('release.done', 'WATCH_INCOMPLETE', `watch window not yet complete (${Math.round(percentComplete * 100)}% elapsed)`, { projectRoot }, []);
+}
+function doneTransitionFailed(projectRoot, error) {
+    return fail('release.done', 'INVALID_TRANSITION', error, { projectRoot }, []);
+}
+function runReleaseDone(io, opts) {
+    const projectRoot = resolveReleaseProjectRoot(opts.project);
+    const state = readReleaseState(projectRoot);
+    if (state.active === null) {
+        printResult(io, noActiveRelease(projectRoot), opts.json ?? false);
+        return;
+    }
+    // No stage guard here: `watching` is unreachable (nothing ever calls
+    // transitionRelease(state, 'watching')), so the real precondition is the
+    // watch window itself — the same thing this command's description
+    // documents ("Requires the watch window to be complete"). The stage
+    // table (`promoted → watching → done`) stays as the declared design, but
+    // `promoted` may now reach `done` directly.
+    const win = watchWindow(state.active);
+    if (win.percentComplete < 1.0) {
+        printResult(io, watchIncomplete(projectRoot, win.percentComplete), opts.json ?? false);
+        return;
+    }
+    const result = transitionRelease(state, 'done');
+    if ('error' in result) {
+        printResult(io, doneTransitionFailed(projectRoot, result.error), opts.json ?? false);
+        return;
+    }
+    // Move to history. `transitionRelease` never clears `active`; the fallback
+    // is what keeps this read type-safe without asserting non-nullness.
+    const finalRecord = result.state.active ?? state.active;
+    const newState = {
+        version: 1,
+        active: null,
+        history: [...result.state.history, finalRecord]
+    };
+    writeReleaseState(projectRoot, newState);
+    printResult(io, ok('release.done', {
+        projectRoot,
+        version: finalRecord.version,
+        doneAt: finalRecord.doneAt
+    }, [], []), opts.json ?? false);
+}
+export function registerReleaseDoneCommand(release, io) {
+    addJsonOption(release
+        .command('done')
+        .description('Mark the active release as done. Requires the watch window to be ' +
+        'complete (24h after promoted-at).')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => runReleaseDone(io, opts));
+}

package/dist/cli/commands/release-hotfix-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerReleaseHotfixCommand(release: Command, io: ProgramIO): void;

package/dist/cli/commands/release-hotfix-command.js

@@ -0,0 +1,50 @@
+// src/cli/commands/release-hotfix-command.ts
+//
+// `peaks release hotfix <version>` — start a hotfix, forcing any active release
+// back. Split out of `release-commands.ts`; the verb name, its options, the
+// changeset gate and the envelope shape are unchanged.
+import { hotfixRelease, readReleaseState, writeReleaseState } from '../../services/release/release-state.js';
+import { runChangesetHardGate } from '../../services/changeset/changeset-check-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { resolveReleaseProjectRoot } from './release-command-shared.js';
+/** The refusal a staged changeset triggers before a hotfix may start. */
+function changesetBlockedOutcome(gate, projectRoot) {
+    return fail('release.hotfix', 'CHANGESET_BLOCKED', `${gate.stagedFiles.length} staged .changeset/*.md file(s) — refusing to start hotfix`, {
+        projectRoot,
+        stagedFiles: [...gate.stagedFiles],
+        snapshotAt: gate.snapshotAt
+    }, [
+        `Drain pending changesets (coordinating LLM: drain via the standard changeset consumption path), then re-run \`peaks changeset check --project ${projectRoot}\` to confirm clean state.`
+    ]);
+}
+function runReleaseHotfix(io, version, opts) {
+    const projectRoot = resolveReleaseProjectRoot(opts.project);
+    const gate = runChangesetHardGate(projectRoot);
+    if (gate.state === 'staged-present') {
+        process.exitCode = 1;
+        printResult(io, changesetBlockedOutcome(gate, projectRoot), opts.json ?? false);
+        return;
+    }
+    const state = readReleaseState(projectRoot);
+    const result = hotfixRelease(state, version, opts.note);
+    if ('error' in result) {
+        printResult(io, fail('release.hotfix', 'HOTFIX_FAILED', result.error, { projectRoot }, []), opts.json ?? false);
+        return;
+    }
+    writeReleaseState(projectRoot, result.state);
+    printResult(io, ok('release.hotfix', {
+        projectRoot,
+        version: result.record.version,
+        currentStage: result.record.currentStage
+    }, [], ['Hotfix started at canary-10. Run `peaks release canary --percent 50` to advance.']), opts.json ?? false);
+}
+export function registerReleaseHotfixCommand(release, io) {
+    addJsonOption(release
+        .command('hotfix <version>')
+        .description('Start a hotfix release. Forces a rollback of any active release, ' +
+        'skips the `planned` stage, and starts the new release at canary-10. ' +
+        'Use this for紧急修复 — minimal ceremony, no full prd ceremony.')
+        .option('--note <text>', 'optional hotfix note')
+        .option('--project <path>', 'project root (default: cwd)')).action((version, opts) => runReleaseHotfix(io, version, opts));
+}

package/dist/cli/commands/release-plan-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerReleasePlanCommand(release: Command, io: ProgramIO): void;

package/dist/cli/commands/release-plan-command.js

@@ -0,0 +1,33 @@
+// src/cli/commands/release-plan-command.ts
+//
+// `peaks release plan <version>` — start a new release. Split out of
+// `release-commands.ts`; the verb name, its options and the envelope shape are
+// unchanged.
+import { planRelease, readReleaseState, writeReleaseState } from '../../services/release/release-state.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { resolveReleaseProjectRoot } from './release-command-shared.js';
+function runReleasePlan(io, version, opts) {
+    const projectRoot = resolveReleaseProjectRoot(opts.project);
+    const state = readReleaseState(projectRoot);
+    const result = planRelease(state, version);
+    if ('error' in result) {
+        printResult(io, fail('release.plan', 'CONFLICT', result.error, { projectRoot }, [
+            'Run `peaks release rollback` or `peaks release hotfix` to clear the active release.'
+        ]), opts.json ?? false);
+        return;
+    }
+    writeReleaseState(projectRoot, result.state);
+    printResult(io, ok('release.plan', {
+        projectRoot,
+        version: result.record.version,
+        currentStage: result.record.currentStage
+    }, [], ['Run `peaks release canary --percent 10` to begin the canary phase.']), opts.json ?? false);
+}
+export function registerReleasePlanCommand(release, io) {
+    addJsonOption(release
+        .command('plan <version>')
+        .description('Start a new release. Stores the version in the canary pipeline state. ' +
+        'Fails when there is already an active release in any non-terminal stage.')
+        .option('--project <path>', 'project root (default: cwd)')).action((version, opts) => runReleasePlan(io, version, opts));
+}

package/dist/cli/commands/release-precheck-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerReleasePrecheckCommand(release: Command, io: ProgramIO): void;

package/dist/cli/commands/release-precheck-command.js

@@ -0,0 +1,28 @@
+// src/cli/commands/release-precheck-command.ts
+//
+// `peaks release precheck` — the 4-layer version precheck. Split out of
+// `release-commands.ts`; the verb name, its options, the `--strict` CI-parity
+// meaning and both the envelope and the exit code are unchanged.
+import { runAllLayers } from '../../services/release/version-precheck-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { resolveReleaseProjectRoot } from './release-command-shared.js';
+function runReleasePrecheck(io, opts) {
+    const projectRoot = resolveReleaseProjectRoot(opts.project);
+    const envelope = runAllLayers({ projectRoot, strict: opts.strict === true });
+    process.exitCode = envelope.ok ? 0 : 1;
+    const warningLines = envelope.overall === 'warning'
+        ? ['Warning layers reported but did not block. Re-run with --strict to upgrade.']
+        : [];
+    printResult(io, ok('release.precheck', envelope, [], warningLines), opts.json ?? false);
+}
+export function registerReleasePrecheckCommand(release, io) {
+    addJsonOption(release
+        .command('precheck')
+        .description('Run the 4-layer version precheck (rootVsShared / tagCollision / ' +
+        'changesetStaged / workspaceLockstep). Layer A+B are blockers by default; ' +
+        'Layer C+D are warnings unless --strict is passed (CI parity mode). ' +
+        'Shared with publish.yml gate-cli-version step §(A).')
+        .option('--strict', 'treat warnings as blockers (CI parity mode)')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => runReleasePrecheck(io, opts));
+}

package/dist/cli/commands/release-promote-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerReleasePromoteCommand(release: Command, io: ProgramIO): void;

package/dist/cli/commands/release-promote-command.js

@@ -0,0 +1,34 @@
+// src/cli/commands/release-promote-command.ts
+//
+// `peaks release promote` — promote the canary to 100% and start the watch
+// window. Split out of `release-commands.ts`; the verb name, its options, the
+// `canary-50` precondition and the envelope shape are unchanged.
+import { readReleaseState, transitionRelease, writeReleaseState } from '../../services/release/release-state.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { resolveReleaseProjectRoot } from './release-command-shared.js';
+function runReleasePromote(io, opts) {
+    const projectRoot = resolveReleaseProjectRoot(opts.project);
+    const state = readReleaseState(projectRoot);
+    const result = transitionRelease(state, 'promoted', opts.note);
+    if ('error' in result) {
+        printResult(io, fail('release.promote', 'INVALID_TRANSITION', result.error, { projectRoot }, []), opts.json ?? false);
+        return;
+    }
+    writeReleaseState(projectRoot, result.state);
+    printResult(io, ok('release.promote', {
+        projectRoot,
+        currentStage: 'promoted',
+        promotedAt: result.state.active?.promotedAt
+    }, [], [
+        'Watch window started. Run `peaks release watch` to check progress; `peaks release rollback` for emergency.'
+    ]), opts.json ?? false);
+}
+export function registerReleasePromoteCommand(release, io) {
+    addJsonOption(release
+        .command('promote')
+        .description('Promote the canary to 100% (full release). Requires stage=canary-50. ' +
+        'Records the promoted-at timestamp and starts the 24h watch window.')
+        .option('--note <text>', 'optional note')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => runReleasePromote(io, opts));
+}

package/dist/cli/commands/release-rollback-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerReleaseRollbackCommand(release: Command, io: ProgramIO): void;

package/dist/cli/commands/release-rollback-command.js

@@ -0,0 +1,33 @@
+// src/cli/commands/release-rollback-command.ts
+//
+// `peaks release rollback` — emergency rollback of the active release. Split
+// out of `release-commands.ts`; the verb name, its options and the envelope
+// shape are unchanged.
+import { readReleaseState, rollbackRelease, writeReleaseState } from '../../services/release/release-state.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { resolveReleaseProjectRoot } from './release-command-shared.js';
+function runReleaseRollback(io, opts) {
+    const projectRoot = resolveReleaseProjectRoot(opts.project);
+    const state = readReleaseState(projectRoot);
+    const result = rollbackRelease(state, opts.note);
+    if ('error' in result) {
+        printResult(io, fail('release.rollback', 'INVALID_TRANSITION', result.error, { projectRoot }, []), opts.json ?? false);
+        return;
+    }
+    writeReleaseState(projectRoot, result.state);
+    printResult(io, ok('release.rollback', {
+        projectRoot,
+        rolledBack: result.record.version,
+        finalStage: result.record.currentStage
+    }, [], ['Run `peaks release hotfix <version>` to start a hotfix on the previous release.']), opts.json ?? false);
+}
+export function registerReleaseRollbackCommand(release, io) {
+    addJsonOption(release
+        .command('rollback')
+        .description('Emergency rollback of the active release. Moves the active release to ' +
+        'the history with currentStage=rolled-back. Available from any ' +
+        'pre-done stage.')
+        .option('--note <text>', 'optional rollback reason')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => runReleaseRollback(io, opts));
+}

package/dist/cli/commands/release-watch-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerReleaseWatchCommand(release: Command, io: ProgramIO): void;