peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,169 @@
+/**
+ * peaks bee * CLI — M7 (spec §7A.2 / §10 RL-9 / AC-24 / AC-25 / AC-26).
+ *
+ * Adds:
+ *   peaks bee export --bee <id> --out <path.tar.gz>
+ *   peaks bee import --in <path.tar.gz> [--as <bee-name>]
+ *
+ * The bee-side counterparts of the loop-side `peaks loop export /
+ * import`. Same hard rules:
+ *
+ *   - source `shareable=false` blocks export at the CLI layer.
+ *   - bundle lands as `candidate`; promotion to `stable` requires
+ *     an `evolution_evaluation` row with an independent
+ *     `evaluator_id` (see `peaks evolution evaluate`).
+ *
+ * The bee bundle captures the bee's inline manifest/segment/file/change
+ * rows so the receiver can re-materialize the full bee + any
+ * loop↔bee relations that referenced it + any evidence briefs that
+ * touched it.
+ *
+ * The `peaks skill sediment export / import` alias lives in
+ * `src/cli/commands/skill-sediment.ts` for one release cycle.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { openStateDb } from '../../services/skillhub/sqlite-store.js';
+import { writeBundle, BundleNotShareableError, BundleAssetNotFoundError, } from '../../services/share/bundle-writer.js';
+import { readBundle, BundleMajorVersionMismatchError, BundleSchemaVersionsMismatchError, BundleImportToStableForbiddenError, BundleMalformedError, } from '../../services/share/bundle-reader.js';
+export function registerBeeCommands(program, io) {
+    // Reuse the existing `bee` parent if one is registered; the
+    // add-a-new-subcommand-check-for-existing-top-level-first rule.
+    const existing = program.commands.find((c) => c.name() === 'bee');
+    const bee = existing ?? program
+        .command('bee')
+        .description('M7: peaks bee export / import (spec §7A.2 / §10 RL-9)');
+    // ---------- peaks bee export ----------
+    addJsonOption(bee
+        .command('export')
+        .description("M7: export a bee_release as a peaks.bundle/1 tarball (spec §7A.2). Refuses to export when shareable=false.")
+        .requiredOption('--bee <id>', 'bee_release numeric id (use `peaks asset status --bee <name>` to find the id)')
+        .requiredOption('--out <path>', 'output .tar.gz path')
+        .option('--project <path>', 'target project root (defaults to cwd)')).action((options) => {
+        const asJson = options.json === true;
+        const beeId = Number(options.bee);
+        if (!Number.isInteger(beeId) || beeId <= 0) {
+            printResult(io, fail('bee.export', 'INVALID_BEE_ID', `--bee must be a positive integer (got '${options.bee}')`, { bee: options.bee }, [
+                'Re-run with --bee <numeric-id>.',
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            if (!existsSync(join(projectRoot, '.peaks'))) {
+                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
+            }
+            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
+            try {
+                const result = writeBundle({
+                    db,
+                    blobsDir: join(projectRoot, '.peaks', 'blobs'),
+                    kind: 'bee',
+                    id: beeId,
+                    outPath: options.out,
+                });
+                printResult(io, ok('bee.export', {
+                    outPath: result.outPath,
+                    kind: result.kind,
+                    assetId: result.assetId,
+                    importedAs: 'candidate',
+                }, [], [
+                    `Receiver must run \`peaks bee import --in ${result.outPath}\` to land this bundle, then run an independent evolution_evaluation before any promote.`,
+                ]), asJson);
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (error) {
+            if (error instanceof BundleNotShareableError) {
+                printResult(io, fail('bee.export', error.code, error.message, { bee: options.bee }, [
+                    'Set shareable=true on the bee_release row, or stop sharing.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof BundleAssetNotFoundError) {
+                printResult(io, fail('bee.export', error.code, error.message, { bee: options.bee }, [
+                    'Verify the bee id with `peaks asset status --bee <name>`.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('bee.export', 'BEE_EXPORT_FAILED', getErrorMessage(error), { bee: options.bee }, ['Verify --bee id and --out path.']), asJson);
+            process.exitCode = 1;
+        }
+    });
+    // ---------- peaks bee import ----------
+    addJsonOption(bee
+        .command('import')
+        .description('M7: import a peaks.bundle/1 tarball. Lands as candidate only — promotion requires an evolution_evaluation row (spec §7A.2 / AC-25 / AC-26).')
+        .requiredOption('--in <path>', 'input .tar.gz path')
+        .option('--as <name>', 'optional rename for the bee name when landing')
+        .option('--project <path>', 'target project root (defaults to cwd)')).action((options) => {
+        const asJson = options.json === true;
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            if (!existsSync(join(projectRoot, '.peaks'))) {
+                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
+            }
+            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
+            try {
+                const result = readBundle({
+                    db,
+                    blobsDir: join(projectRoot, '.peaks', 'blobs'),
+                    inPath: options.in,
+                    ...(options.as !== undefined ? { asName: options.as } : {}),
+                });
+                printResult(io, ok('bee.import', {
+                    assetId: result.assetId,
+                    kind: result.kind,
+                    importedAs: result.importedAs,
+                    warnings: result.warnings,
+                    evidenceBriefCount: result.evidenceBriefCount,
+                }, result.warnings, [
+                    `Run an independent evaluation against this release before promoting; peaks bee promote refuses without an evolution_evaluation row.`,
+                ]), asJson);
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (error) {
+            if (error instanceof BundleMajorVersionMismatchError) {
+                printResult(io, fail('bee.import', error.code, error.message, { receivedMajor: error.receivedMajor }, [
+                    'Use the matching peaks.bundle/<major> reader; this peaks build only supports major=1.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof BundleSchemaVersionsMismatchError) {
+                printResult(io, fail('bee.import', error.code, error.message, {}, [
+                    'Source bundle did not declare the canonical schema versions; refuse the bundle.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof BundleImportToStableForbiddenError) {
+                printResult(io, fail('bee.import', error.code, error.message, {}, [
+                    'Bundles always land as candidate; promotion to stable requires an evolution_evaluation row (AC-26).',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof BundleMalformedError) {
+                printResult(io, fail('bee.import', error.code, error.message, { inPath: options.in }, [
+                    'Re-export from the source via `peaks bee export`.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('bee.import', 'BEE_IMPORT_FAILED', getErrorMessage(error), { inPath: options.in }, ['Verify the bundle path and integrity.']), asJson);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import type { PeaksConfig } from '../../services/config/config-types.js';
+import type { CapabilityMapSourceFilter } from '../../services/recommendations/recommendation-types.js';
+import { type ProgramIO } from '../cli-helpers.js';
+type CapabilityMapOptions = {
+    json?: boolean;
+    source: string;
+};
+export declare function registerCapabilityCommands(program: Command, io: ProgramIO): void;
+export declare function runCapabilityStatus(io: ProgramIO, options: {
+    json?: boolean;
+}): void;
+export declare function runCapabilityMap(io: ProgramIO, options: CapabilityMapOptions): void;
+export declare function getInstalledCapabilityIds(_config: PeaksConfig): string[];
+export declare function parseCapabilityMapSource(source: string): CapabilityMapSourceFilter | null;
+export {};

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

@@ -0,0 +1,45 @@
+import { readConfig } from '../../services/config/config-service.js';
+import { resolveCapabilityAvailability } from '../../services/recommendations/capability-availability.js';
+import { createCapabilityMapPlan } from '../../services/recommendations/capability-map-service.js';
+import { seedCapabilityItems, seedCapabilitySources } from '../../services/recommendations/seed-capability-catalog.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+const CAPABILITY_SOURCE_FILTERS = new Set(['all', 'access-repo', 'mcp-server']);
+export function registerCapabilityCommands(program, io) {
+    const capability = program.command('capability').description('Inspect Peaks capability catalog and runtime availability');
+    addJsonOption(capability.command("status").description("Show seed capability availability")).action((options) => runCapabilityStatus(io, options));
+    addCapabilityMapOptions(capability.command('map').description('Show dry-run external capability landing map')).action((options) => runCapabilityMap(io, options));
+    addCapabilityMapOptions(program.command('capabilities').description('Show dry-run external capability landing map')).action((options) => runCapabilityMap(io, options));
+}
+export function runCapabilityStatus(io, options) {
+    const availability = resolveCapabilityAvailability(seedCapabilityItems);
+    printResult(io, ok("capability.status", { sources: seedCapabilitySources, items: seedCapabilityItems, availability }), options.json);
+}
+function addCapabilityMapOptions(command) {
+    return addJsonOption(command.option('--source <source>', 'Filter source group: all, access-repo, or mcp-server', 'all'));
+}
+export function runCapabilityMap(io, options) {
+    const source = parseCapabilityMapSource(options.source);
+    if (!source) {
+        printResult(io, fail('capabilities.map', 'UNSUPPORTED_CAPABILITY_SOURCE', 'Supported capability sources are all, access-repo, and mcp-server', { source: options.source }, ['Rerun with --source all, --source access-repo, or --source mcp-server']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    const config = readConfig();
+    const installedCapabilityIds = getInstalledCapabilityIds(config);
+    const httpProxy = config.proxy?.httpProxy;
+    printResult(io, ok('capabilities.map', createCapabilityMapPlan({
+        source,
+        installedCapabilityIds,
+        ...(httpProxy === undefined ? {} : { httpProxy })
+    })), options.json);
+}
+export function getInstalledCapabilityIds(_config) {
+    return [];
+}
+export function parseCapabilityMapSource(source) {
+    if (CAPABILITY_SOURCE_FILTERS.has(source)) {
+        return source;
+    }
+    return null;
+}

package/dist/cli/commands/capability-worker-config-sc-commands.d.ts

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

package/dist/cli/commands/capability-worker-config-sc-commands.js

@@ -0,0 +1,8 @@
+import { registerCapabilityCommands } from './capability-commands.js';
+import { registerConfigCommands } from './config-commands.js';
+import { registerSCCommands } from './sc-commands.js';
+export function registerCapabilityWorkerConfigAndSCCommands(program, io) {
+    registerCapabilityCommands(program, io);
+    registerConfigCommands(program, io);
+    registerSCCommands(program, io);
+}

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

@@ -0,0 +1,13 @@
+/**
+ * rid-011 — peaks changeset check (Phase 4 slice 2).
+ *
+ *   - `peaks changeset check` — hard gate, exit non-zero if any staged
+ *     .changeset/*.md exists. No warning mode, no --strict, no
+ *     --skip-changeset-check.
+ *
+ * Wired into `_register.ts` via the rid-007 auto-registration barrel;
+ * do NOT add a second registration call in `program.ts`.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerChangesetCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,46 @@
+/**
+ * rid-011 — peaks changeset check (Phase 4 slice 2).
+ *
+ *   - `peaks changeset check` — hard gate, exit non-zero if any staged
+ *     .changeset/*.md exists. No warning mode, no --strict, no
+ *     --skip-changeset-check.
+ *
+ * Wired into `_register.ts` via the rid-007 auto-registration barrel;
+ * do NOT add a second registration call in `program.ts`.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.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';
+export function registerChangesetCommands(program, io) {
+    const changeset = program
+        .command('changeset')
+        .description('rid-011 — changeset hard gate (no warning mode, no skip).');
+    addJsonOption(changeset
+        .command('check')
+        .description('Hard-gate check: exit non-zero if any .changeset/*.md file is staged ' +
+        '(excluding README.md). Mirrors publish.yml gate-changeset step.')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const gate = runChangesetHardGate(projectRoot);
+        if (gate.ok) {
+            printResult(io, ok('changeset.check', {
+                root: gate.root,
+                state: gate.state,
+                stagedFiles: gate.stagedFiles,
+                snapshotAt: gate.snapshotAt
+            }, [], []), opts.json ?? false);
+            return;
+        }
+        process.exitCode = 1;
+        printResult(io, fail('changeset.check', 'CHANGESET_BLOCKED', `${gate.stagedFiles.length} staged .changeset/*.md file(s) — refusing to proceed`, {
+            root: gate.root,
+            state: gate.state,
+            stagedFiles: gate.stagedFiles,
+            snapshotAt: gate.snapshotAt
+        }, [
+            `Drain pending changesets before proceeding: drain `.concat(gate.stagedFiles.join(', '), ' via the coordinating LLM (e.g. `pnpm changeset version` or `peaks changeset publish` if installed).'),
+            'Then re-run `peaks changeset check` to confirm a clean state.'
+        ]), opts.json ?? false);
+    });
+}

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

@@ -0,0 +1,90 @@
+/**
+ * Slice 2 — `peaks code [--fast] <change-id>` (peaks-code fast mode).
+ *
+ * The `peaks-code` SKILL orchestrates an LLM-side workflow:
+ *   load-memory -> standards-preflight -> rd-cycle -> qa-cycle -> emit-txt
+ *
+ * The CLI surface here is intentionally narrow: it builds a CodePlan and
+ * runs it via `runCodeFast`. Fast mode skips memory full-load, standards
+ * preflight, and the QA repair loop. Round-trip KPI: ≤ 30s.
+ *
+ * No new service layer — the orchestrator is the in-file `runCodeFast`
+ * function. Hooks are injected so tests can mock at the boundary.
+ *
+ * v2.11.0 Group F (Tier 9) — D5 / D7 additions:
+ *   - `peaks code should-pause --step <step> --mode <mode>` (D5)
+ *   - `peaks code post-compact-detect --project <path>` (D7)
+ *
+ * rid-024: 7 sub-commands extracted into 3 sibling files:
+ *   - code-mode-gate-commands.ts (plan + should-pause)
+ *   - code-job-shape-commands.ts (detect-job + read-job-shape)
+ *   - code-runtime-commands.ts (post-compact-detect + auto-compact + context-now + gate-step-08 + emit-handoff)
+ * This file keeps the public API: types, buildCodePlan, runCodeFast,
+ * registerCodeCommands (now a thin orchestrator).
+ */
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export type CodeStepKind = 'memory' | 'preflight' | 'rd' | 'qa' | 'emit';
+export interface CodeStep {
+    readonly id: 'load-memory' | 'standards-preflight' | 'rd-cycle' | 'qa-cycle' | 'emit-txt';
+    readonly kind: CodeStepKind;
+    readonly skipped: boolean;
+    /** QA-only: when true, qa hook retries on failure up to N rounds. */
+    readonly repairLoop?: boolean;
+}
+export interface CodePlan {
+    readonly sessionId: string;
+    readonly steps: readonly CodeStep[];
+}
+export interface CodeHooks {
+    readonly memory: (ctx: {
+        sessionId: string;
+    }) => Promise<unknown>;
+    readonly preflight: (ctx: {
+        sessionId: string;
+    }) => Promise<unknown>;
+    readonly rd: (ctx: {
+        sessionId: string;
+    }) => Promise<unknown>;
+    readonly qa: (ctx: {
+        sessionId: string;
+        repairLoop: boolean;
+    }) => Promise<unknown>;
+    readonly emit: (ctx: {
+        sessionId: string;
+    }) => Promise<unknown>;
+}
+export interface CodeRunResult {
+    readonly sessionId: string;
+    readonly ok: boolean;
+    readonly steps: readonly CodeStep[];
+    readonly skipped: readonly string[];
+    readonly elapsedMs: number;
+}
+/**
+ * Build a CodePlan. `fast=true` marks memory + preflight as skipped and
+ * disables the QA repair loop. Step order is fixed; emit-txt always last.
+ */
+export declare function buildCodePlan(opts: {
+    sessionId: string;
+    fast: boolean;
+}): CodePlan;
+/**
+ * Run the CodePlan. Skipped steps do NOT invoke their hook; emit-txt is
+ * always invoked last. Returns timing + skipped ids for KPI measurement.
+ */
+export declare function runCodeFast(opts: {
+    sessionId: string;
+    plan: CodePlan;
+    hooks: CodeHooks;
+}): Promise<CodeRunResult>;
+/**
+ * Register the `peaks code [--fast] <change-id>` command. The actual
+ * LLM-side orchestration is driven by the SKILL.md (LLM-side), so this
+ * CLI command is a thin surface that builds the plan and emits a JSON
+ * envelope for downstream tooling.
+ *
+ * rid-024: this function is now a thin orchestrator that delegates to 3
+ * sibling register functions + the rid-020b run register.
+ */
+export declare function registerCodeCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,118 @@
+/**
+ * Slice 2 — `peaks code [--fast] <change-id>` (peaks-code fast mode).
+ *
+ * The `peaks-code` SKILL orchestrates an LLM-side workflow:
+ *   load-memory -> standards-preflight -> rd-cycle -> qa-cycle -> emit-txt
+ *
+ * The CLI surface here is intentionally narrow: it builds a CodePlan and
+ * runs it via `runCodeFast`. Fast mode skips memory full-load, standards
+ * preflight, and the QA repair loop. Round-trip KPI: ≤ 30s.
+ *
+ * No new service layer — the orchestrator is the in-file `runCodeFast`
+ * function. Hooks are injected so tests can mock at the boundary.
+ *
+ * v2.11.0 Group F (Tier 9) — D5 / D7 additions:
+ *   - `peaks code should-pause --step <step> --mode <mode>` (D5)
+ *   - `peaks code post-compact-detect --project <path>` (D7)
+ *
+ * rid-024: 7 sub-commands extracted into 3 sibling files:
+ *   - code-mode-gate-commands.ts (plan + should-pause)
+ *   - code-job-shape-commands.ts (detect-job + read-job-shape)
+ *   - code-runtime-commands.ts (post-compact-detect + auto-compact + context-now + gate-step-08 + emit-handoff)
+ * This file keeps the public API: types, buildCodePlan, runCodeFast,
+ * registerCodeCommands (now a thin orchestrator).
+ */
+import { registerCodeRunCommand } from './code-run-command.js';
+import { registerCodeModeGateCommands } from './code-mode-gate-commands.js';
+import { registerCodeJobShapeCommands } from './code-job-shape-commands.js';
+import { registerCodeRuntimeCommands } from './code-runtime-commands.js';
+const STEP_ORDER = [
+    'load-memory',
+    'standards-preflight',
+    'rd-cycle',
+    'qa-cycle',
+    'emit-txt'
+];
+const STEP_KIND = {
+    'load-memory': 'memory',
+    'standards-preflight': 'preflight',
+    'rd-cycle': 'rd',
+    'qa-cycle': 'qa',
+    'emit-txt': 'emit'
+};
+/**
+ * Build a CodePlan. `fast=true` marks memory + preflight as skipped and
+ * disables the QA repair loop. Step order is fixed; emit-txt always last.
+ */
+export function buildCodePlan(opts) {
+    const steps = STEP_ORDER.map((id) => {
+        const isSkippable = id === 'load-memory' || id === 'standards-preflight';
+        const step = {
+            id,
+            kind: STEP_KIND[id],
+            skipped: opts.fast && isSkippable
+        };
+        if (id === 'qa-cycle') {
+            return { ...step, repairLoop: !opts.fast };
+        }
+        return step;
+    });
+    return { sessionId: opts.sessionId, steps };
+}
+/**
+ * Run the CodePlan. Skipped steps do NOT invoke their hook; emit-txt is
+ * always invoked last. Returns timing + skipped ids for KPI measurement.
+ */
+export async function runCodeFast(opts) {
+    const start = Date.now();
+    const skipped = [];
+    const { sessionId, plan, hooks } = opts;
+    for (const step of plan.steps) {
+        if (step.skipped) {
+            skipped.push(step.id);
+            continue;
+        }
+        switch (step.id) {
+            case 'load-memory':
+                await hooks.memory({ sessionId });
+                break;
+            case 'standards-preflight':
+                await hooks.preflight({ sessionId });
+                break;
+            case 'rd-cycle':
+                await hooks.rd({ sessionId });
+                break;
+            case 'qa-cycle':
+                await hooks.qa({ sessionId, repairLoop: step.repairLoop === true });
+                break;
+            case 'emit-txt':
+                await hooks.emit({ sessionId });
+                break;
+        }
+    }
+    return {
+        sessionId,
+        ok: true,
+        steps: plan.steps,
+        skipped,
+        elapsedMs: Date.now() - start
+    };
+}
+/**
+ * Register the `peaks code [--fast] <change-id>` command. The actual
+ * LLM-side orchestration is driven by the SKILL.md (LLM-side), so this
+ * CLI command is a thin surface that builds the plan and emits a JSON
+ * envelope for downstream tooling.
+ *
+ * rid-024: this function is now a thin orchestrator that delegates to 3
+ * sibling register functions + the rid-020b run register.
+ */
+export function registerCodeCommands(program, io) {
+    const code = program
+        .command('code', { hidden: true })
+        .description('peaks-code LLM-side workflow planner (slice 2 fast mode)');
+    registerCodeModeGateCommands(code, io);
+    registerCodeJobShapeCommands(code, io);
+    registerCodeRuntimeCommands(code, io);
+    registerCodeRunCommand(code, io);
+}

package/dist/cli/commands/code-job-shape-commands.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Slice rid-024 — `peaks code detect-job` + `peaks code read-job-shape`.
+ *
+ * Extracted from code-commands.ts (rid-024 split).
+ * Owns: detect-job (write JobShapeDecision), read-job-shape (read+print).
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodeJobShapeCommands(code: Command, io: ProgramIO): void;