peaks-loop 4.1.3 → 4.1.4

package/dist/cli/commands/qa-run-slice.js

@@ -0,0 +1,145 @@
+// src/cli/commands/qa-run-slice.ts
+//
+// The pure `peaks qa run` slice: the gate list, the restart detector wiring and
+// the MUT.sig gate, with no commander and no I/O. Extracted from
+// `qa-commands.ts`; the exported names, the gate order and every envelope field
+// are unchanged.
+//
+// The browser-E2E gate is what the restart-loop detector guards, so the slice
+// wires it here: it constructs a `BrowserRestartDetector` (configurable via
+// `--max-browser-restarts` / `--no-restart-detector`) and a `BrowserEventLogger`
+// that writes the per-slice JSONL log to
+// `.peaks/_runtime/<session-id>/qa/browser-events.jsonl`.
+import { join } from 'node:path';
+import { BrowserRestartDetector } from '../../services/qa/browser-restart-detector.js';
+import { BrowserEventLogger } from '../../services/qa/browser-event-logger.js';
+import { BROWSER_REUSE_HINT } from '../../services/qa/browser-reuse-hint.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+export const DEFAULT_MAX_BROWSER_RESTARTS = 3;
+export function runQaSlice(input) {
+    // Sid axis: this is the join for `qa/browser-events.jsonl`. The `qa gate run`
+    // action guards before calling in, but the function is exported for tests and
+    // states its own contract at the join.
+    if (isUnsafePathInput(input.sessionId)) {
+        throw new Error(`Invalid session id: ${input.sessionId} (must be a single path segment)`);
+    }
+    const detector = new BrowserRestartDetector({
+        maxRestarts: input.maxRestarts,
+        enabled: input.detectorEnabled
+    });
+    const logPath = join(input.project, '.peaks', '_runtime', input.sessionId, 'qa', 'browser-events.jsonl');
+    const logger = new BrowserEventLogger({ filePath: logPath });
+    // PRD AC4 + P1: when browser E2E is off, the detector must NOT record events
+    // at all (otherwise a user passing both --no-browser AND a hot detector would
+    // see spurious detectorTriggered=true and exit code 2).
+    if (input.browserEnabled) {
+        recordBrowserEvents(detector, logger, input.events, input.sessionId);
+    }
+    const gates = [
+        { name: 'functional', status: 'passed' },
+        { name: 'security', status: 'passed' },
+        browserGateStatus(input.browserEnabled, detector),
+        mutationGateStatus(input)
+    ];
+    const halt = detector.shouldHalt();
+    return {
+        sessionId: input.sessionId,
+        project: input.project,
+        browserEnabled: input.browserEnabled,
+        gates,
+        detectorTriggered: halt,
+        ...(halt ? { diagnostic: detector.diagnostic() } : {}),
+        subAgentPromptHint: BROWSER_REUSE_HINT,
+        // Surface MUT.sig ONLY when the gate is actually evaluated
+        // (mutation enabled AND a report was loaded). --no-mutation or
+        // missing report -> undefined, so downstream consumers cannot
+        // mistake a skipped gate for a chain-trail anchor.
+        ...(input.mutationEnabled && input.mutationReport !== null
+            ? { mutSig: input.mutationReport.sha256 }
+            : {})
+    };
+}
+/**
+ * Feed one slice's events to the detector, logging a close→navigate pair as a
+ * spurious restart. The pairing state is local to the run: a close with no
+ * following navigate logs nothing, and a second navigate in a row clears it.
+ */
+function recordBrowserEvents(detector, logger, events, sessionId) {
+    let pendingCloseTs = null;
+    for (const ev of events) {
+        detector.record(ev);
+        if (ev.tool === 'browser_close') {
+            pendingCloseTs = ev.ts;
+        }
+        else if (ev.tool === 'browser_navigate' && pendingCloseTs !== null) {
+            const deltaMs = Date.parse(ev.ts) - Date.parse(pendingCloseTs);
+            logger.append({
+                kind: 'spurious_restart',
+                ts: ev.ts,
+                sessionId,
+                closeTs: pendingCloseTs,
+                navigateTs: ev.ts,
+                deltaMs
+            });
+            pendingCloseTs = null;
+        }
+        else if (ev.tool === 'browser_navigate') {
+            pendingCloseTs = null;
+        }
+    }
+}
+function browserGateStatus(browserEnabled, detector) {
+    if (!browserEnabled) {
+        return { name: 'browser-e2e', status: 'skipped', reason: '--no-browser' };
+    }
+    return detector.shouldHalt()
+        ? { name: 'browser-e2e', status: 'failed', reason: detector.diagnostic() }
+        : { name: 'browser-e2e', status: 'passed' };
+}
+/**
+ * Plan 2 / Task 8 — MUT.sig gate.
+ * Gate semantics (per spec lines 1292-1341):
+ *   - `skipped` when peaks-mut was not run (no report) OR --no-mutation
+ *   - `passed`  when the report's `thresholds.passed` is true
+ *   - `failed`  when the report's `thresholds.passed` is false
+ * "Skipped" is NOT a failure — the gate is a no-op so existing sessions that
+ * have not yet adopted peaks-mut keep passing.
+ */
+function mutationGateStatus(input) {
+    if (!input.mutationEnabled) {
+        return { name: 'mutation', status: 'skipped', reason: '--no-mutation' };
+    }
+    const report = input.mutationReport;
+    if (report === null) {
+        return { name: 'mutation', status: 'skipped', reason: 'peaks mut not run' };
+    }
+    return report.thresholds.passed
+        ? { name: 'mutation', status: 'passed', mutSig: report.sha256 }
+        : {
+            name: 'mutation',
+            status: 'failed',
+            reason: deriveMutationFailureReason(report),
+            mutSig: report.sha256
+        };
+}
+/**
+ * Plan 2 / Task 8 — pure helper that explains WHY the mutation gate
+ * failed. Used only when the report's `thresholds.passed` is false.
+ * Reads the threshold block from the report itself (already
+ * CLI-computed by `buildMutReport`) so the message matches what
+ * peaks-mut's CLI surface prints.
+ */
+function deriveMutationFailureReason(report) {
+    const t = report.thresholds;
+    const fragments = [];
+    if (report.mutation.killRate < t.mutationKillRateMin) {
+        fragments.push(`mutation kill rate ${report.mutation.killRate.toFixed(2)} < ${t.mutationKillRateMin.toFixed(2)}`);
+    }
+    if (report.assertions.weakRate > t.weakAssertionRateMax) {
+        fragments.push(`weak assertion rate ${report.assertions.weakRate.toFixed(2)} > ${t.weakAssertionRateMax.toFixed(2)}`);
+    }
+    if (fragments.length === 0) {
+        return `mutation thresholds failed (MUT.sig=${report.sha256})`;
+    }
+    return `${fragments.join('; ')} (MUT.sig=${report.sha256})`;
+}

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

@@ -0,0 +1,28 @@
+import type { Command } from 'commander';
+import { type LayerResult } from '../../services/release/version-precheck-service.js';
+import { type ProgramIO } from '../cli-helpers.js';
+/**
+ * The payload an outcome carries. The `error` member is declared so the
+ * INVALID_TRANSITION message is read as a `string` rather than as `unknown`
+ * off the open index signature.
+ */
+type CanaryPayload = Readonly<Record<string, unknown>> & {
+    readonly error?: string;
+};
+type CanaryOutcome = {
+    ok: boolean;
+    payload: CanaryPayload;
+    status: 'PRECHECK_BLOCKER' | 'INVALID_PERCENT' | 'INVALID_TRANSITION' | 'OK';
+    blockerLayer?: {
+        name: string;
+        result: LayerResult;
+    };
+};
+export declare function executeCanaryAction(opts: {
+    percent: string;
+    note?: string;
+    project?: string;
+    json?: boolean;
+}, io: ProgramIO, projectRoot: string): CanaryOutcome;
+export declare function registerReleaseCanaryCommand(release: Command, io: ProgramIO): void;
+export {};

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

@@ -0,0 +1,129 @@
+// src/cli/commands/release-canary-command.ts
+//
+// `peaks release canary --percent <10|50>` — advance the active release to a
+// canary stage. Split out of `release-commands.ts`; the verb name, its options,
+// the canary percent vocabulary, the precheck gate and every envelope shape are
+// unchanged. `executeCanaryAction` keeps its name and signature (it is the
+// function the cross-cutting e2e harness names) and is re-exported by
+// `release-commands.ts`.
+import { readReleaseState, transitionRelease, 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';
+import { CANARY_PERCENT_FIRST, CANARY_PERCENT_SECOND, CANARY_PERCENTS, resolveReleaseProjectRoot } from './release-command-shared.js';
+function precheckBlockerOutcome(projectRoot, snapshotAt, name, result) {
+    return {
+        ok: false,
+        status: 'PRECHECK_BLOCKER',
+        blockerLayer: { name, result },
+        payload: {
+            projectRoot,
+            precheckSnapshotAt: snapshotAt,
+            layer: name,
+            message: result.message,
+            remediation: result.remediation
+        }
+    };
+}
+// 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
+    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 precheckBlockerOutcome(projectRoot, precheck.snapshotAt, name, result);
+    }
+    const percent = Number.parseInt(opts.percent, 10);
+    if (percent !== CANARY_PERCENT_FIRST && percent !== CANARY_PERCENT_SECOND) {
+        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 === CANARY_PERCENT_FIRST
+                ? 'peaks release canary --percent 50'
+                : 'peaks release promote'
+        }
+    };
+}
+/** The refusal a staged changeset triggers, before the precheck even runs. */
+function changesetBlockedOutcome(gate, projectRoot) {
+    return 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.`
+    ]);
+}
+/** The precheck refusal, with the layer that blocked and where to read the rest. */
+function precheckBlockerEnvelope(projectRoot, result) {
+    const layer = result.blockerLayer;
+    return 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 ?? ''}`
+    ]);
+}
+/** The outcome of the canary attempt, printed as the envelope its status selects. */
+function printCanaryOutcome(io, opts, projectRoot, result) {
+    const asJson = opts.json ?? false;
+    if (result.status === 'PRECHECK_BLOCKER') {
+        printResult(io, precheckBlockerEnvelope(projectRoot, result), asJson);
+        return;
+    }
+    if (result.status === 'INVALID_PERCENT') {
+        printResult(io, fail('release.canary', 'INVALID_PERCENT', `--percent must be 10 or 50 (got "${opts.percent}")`, result.payload, []), asJson);
+        return;
+    }
+    if (result.status === 'INVALID_TRANSITION') {
+        printResult(io, fail('release.canary', 'INVALID_TRANSITION', String(result.payload['error'] ?? ''), result.payload, []), asJson);
+        return;
+    }
+    printResult(io, ok('release.canary', result.payload, [], []), asJson);
+}
+function runReleaseCanary(io, 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;
+    }
+    printCanaryOutcome(io, opts, projectRoot, executeCanaryAction(opts, io, projectRoot));
+}
+export function registerReleaseCanaryCommand(release, io) {
+    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) => runReleaseCanary(io, opts));
+}

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

@@ -0,0 +1,13 @@
+import type { ReleaseStage } from '../../services/release/release-state.js';
+/** The two canary stages the CLI supports, as the `--percent` values that select them. */
+export declare const CANARY_PERCENT_FIRST = 10;
+export declare const CANARY_PERCENT_SECOND = 50;
+export type CanaryPercent = typeof CANARY_PERCENT_FIRST | typeof CANARY_PERCENT_SECOND;
+export declare const CANARY_PERCENTS: Readonly<Record<CanaryPercent, ReleaseStage>>;
+/** `--project <path>`, else the nearest project root, else cwd — unchanged order. */
+export declare function resolveReleaseProjectRoot(project: string | undefined): string;
+/** `--project` + `--json`, the two options every verb in this family declares. */
+export type ReleaseProjectOptions = {
+    project?: string;
+    json?: boolean;
+};

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

@@ -0,0 +1,18 @@
+// src/cli/commands/release-command-shared.ts
+//
+// What every `peaks release *` verb shares: the project-root resolution and the
+// two canary percents, named so the state machine's vocabulary is not spelled
+// out as literals in each verb. Split out of `release-commands.ts`; the values
+// and the resolution order are unchanged.
+import { findProjectRoot } from '../../services/config/config-safety.js';
+/** The two canary stages the CLI supports, as the `--percent` values that select them. */
+export const CANARY_PERCENT_FIRST = 10;
+export const CANARY_PERCENT_SECOND = 50;
+export const CANARY_PERCENTS = {
+    [CANARY_PERCENT_FIRST]: 'canary-10',
+    [CANARY_PERCENT_SECOND]: 'canary-50'
+};
+/** `--project <path>`, else the nearest project root, else cwd — unchanged order. */
+export function resolveReleaseProjectRoot(project) {
+    return project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+}

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

@@ -18,24 +18,16 @@
  *
  * 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 type { Command } from 'commander';
-import { isReleaseStage } from '../../services/release/release-state.js';
-import { type LayerResult } from '../../services/release/version-precheck-service.js';
-import { type ProgramIO } from '../cli-helpers.js';
-export declare function executeCanaryAction(opts: {
-    percent: string;
-    note?: string;
-    project?: string;
-    json?: boolean;
-}, io: ProgramIO, projectRoot: string): {
-    ok: boolean;
-    payload: Readonly<Record<string, unknown>>;
-    status: 'PRECHECK_BLOCKER' | 'INVALID_PERCENT' | 'INVALID_TRANSITION' | 'OK';
-    blockerLayer?: {
-        name: string;
-        result: LayerResult;
-    };
-};
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerReleaseCommands(program: Command, io: ProgramIO): void;
-export { isReleaseStage };
+export { executeCanaryAction } from './release-canary-command.js';
+export { isReleaseStage } from '../../services/release/release-state.js';