peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/loop-eval-spec-lint-command.js

@@ -0,0 +1,42 @@
+import { lintSpecFile } from '../../services/loop/spec-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { loopSpecParent } from './loop-eval-parents.js';
+export function registerLoopSpecLintCommand(program, io) {
+    const spec = loopSpecParent(program);
+    addJsonOption(spec
+        .command('lint')
+        .description('Slice E.2: schema-validate a spec.yaml file (path required).')
+        .argument('<file>', 'path to spec.yaml')
+        .option('--rid <rid>', 'override the rid embedded in the spec (default: inferred from path)')).action((file, options) => runLoopSpecLint(file, options, io));
+}
+function reportLoopSpecLintFailure(io, error, file, asJson) {
+    printResult(io, fail('loop.spec.lint', 'LOOP_SPEC_LINT_FAILED', getErrorMessage(error), { file }, [
+        'Verify the file path and rid flag.'
+    ]), asJson);
+    process.exitCode = 1;
+}
+function runLoopSpecLint(file, options, io) {
+    try {
+        const result = lintSpecFile(file, options.rid);
+        if (result.spec === null) {
+            printResult(io, fail('loop.spec.lint', 'SPEC_LINT_FAILED', result.report.errors.join('; '), { file, raw: result.raw.slice(0, 200) }, ['Verify the file path and YAML syntax.']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('loop.spec.lint', {
+            file,
+            spec: result.spec,
+            lint: {
+                ok: result.report.ok,
+                errors: result.report.errors,
+                warnings: result.report.warnings
+            }
+        }, [], []), options.json);
+        if (!result.report.ok)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        reportLoopSpecLintFailure(io, error, file, options.json);
+    }
+}

package/dist/cli/commands/loop-eval-workflow-commands.d.ts

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

package/dist/cli/commands/loop-eval-workflow-commands.js

@@ -0,0 +1,141 @@
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { resolveWorkflow, planWorkflow, planWorkflowRun } from '../../services/workflow/workflow-loader.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { workflowCommandParent } from './loop-eval-parents.js';
+export function registerWorkflowEvalWorkflowCommands(program, io) {
+    const workflow = workflowCommandParent(program);
+    // peaks workflow run <id>
+    addJsonOption(workflow
+        .command('run')
+        .description('Slice A.3: replay a captured workflow (.peaks/workflows/<id>.yaml) deterministically. Returns the run-plan order + per-phase status without re-deriving the phase plan.')
+        .argument('<id>', 'workflow id (matches .peaks/workflows/<id>.yaml)')
+        .requiredOption('--session <sid>', 'session id (from peaks workspace init)')
+        .option('--project <path>', 'project root (default: cwd)')).action((id, options) => runWorkflowRun(id, options, io));
+    // peaks workflow graph <id>  (dry-run graph render)
+    // Renamed from `plan` to `graph` to avoid collision with the existing
+    // `peaks workflow plan <read|refresh|detect-trigger>` family registered
+    // Reuse the existing `graph` parent if `registerWorkflowLifecycleCommand`
+    // already created one (it owns `peaks workflow graph show|list`).
+    const existingGraph = workflow.commands.find((c) => c.name() === 'graph');
+    const graphParent = existingGraph ??
+        workflow
+            .command('graph')
+            .description('workflow graph read commands (slice A.3 dry-run + slice 4.0.8 lifecycle)');
+    addJsonOption(graphParent
+        .description('Slice A.3 dry-run: render the workflow graph (phases + parallel groups + evaluators + budget). No phase is executed.')
+        .argument('<id>', 'workflow id')
+        .requiredOption('--session <sid>', 'session id')
+        .option('--project <path>', 'project root (default: cwd)')).action((id, options) => runWorkflowGraph(id, options, io));
+    // peaks workflow lint <id>
+    addJsonOption(workflow
+        .command('lint')
+        .description('Slice A.3: validate a workflow spec (phases / gates / evaluators / parallel groups / budget).')
+        .argument('<id>', 'workflow id')
+        .requiredOption('--session <sid>', 'session id')
+        .option('--project <path>', 'project root (default: cwd)')).action((id, options) => runWorkflowLint(id, options, io));
+}
+function reportWorkflowRunFailure(io, error, sessionId, asJson) {
+    printResult(io, fail('workflow.run', 'WORKFLOW_RUN_FAILED', getErrorMessage(error), { sessionId }, [
+        'Verify the workflow id and session binding.'
+    ]), asJson);
+    process.exitCode = 1;
+}
+function reportWorkflowGraphFailure(io, error, sessionId, asJson) {
+    printResult(io, fail('workflow.graph', 'WORKFLOW_GRAPH_FAILED', getErrorMessage(error), { sessionId }, [
+        'Verify the workflow id and session binding.'
+    ]), asJson);
+    process.exitCode = 1;
+}
+function reportWorkflowLintFailure(io, error, sessionId, asJson) {
+    printResult(io, fail('workflow.lint', 'WORKFLOW_LINT_FAILED', getErrorMessage(error), { sessionId }, [
+        'Verify the workflow file syntax.'
+    ]), asJson);
+    process.exitCode = 1;
+}
+function workflowRunData(sessionId, resolved, runPlan) {
+    return {
+        sessionId,
+        workflow: { id: resolved.spec.id, label: resolved.spec.label, source: resolved.source },
+        runPlan,
+        lintWarnings: resolved.lint.warnings
+    };
+}
+function workflowGraphData(sessionId, graph, resolved) {
+    return {
+        sessionId,
+        graph,
+        lintWarnings: resolved.lint.warnings
+    };
+}
+function runWorkflowRun(id, options, io) {
+    try {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const resolved = resolveWorkflow(projectRoot, id);
+        if (resolved.source.kind === 'missing') {
+            printResult(io, fail('workflow.run', 'WORKFLOW_NOT_FOUND', `workflow "${id}" not found`, { sessionId: options.session }, [`peaks workflow lint ${id} --session ${options.session} --json`]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        if (!resolved.lint.ok) {
+            printResult(io, fail('workflow.run', 'WORKFLOW_LINT_FAILED', `workflow "${id}" has ${resolved.lint.errors.length} lint error(s): ${resolved.lint.errors.join('; ')}`, resolved.lint, [`peaks workflow lint ${id} --session ${options.session} --json`]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const runPlan = planWorkflowRun(resolved.spec);
+        const data = workflowRunData(options.session, resolved, runPlan);
+        const actions = [
+            `Run \`peaks workflow plan ${id} --session ${options.session} --json\` to preview the graph.`
+        ];
+        printResult(io, ok('workflow.run', data, [], actions), options.json);
+    }
+    catch (error) {
+        reportWorkflowRunFailure(io, error, options.session, options.json);
+    }
+}
+function runWorkflowGraph(id, options, io) {
+    try {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const resolved = resolveWorkflow(projectRoot, id);
+        if (resolved.source.kind === 'missing') {
+            printResult(io, fail('workflow.graph', 'WORKFLOW_NOT_FOUND', `workflow "${id}" not found`, { sessionId: options.session }, [`Create .peaks/workflows/${id}.yaml or use the bundled default-fullauto-md.`]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        if (!resolved.lint.ok) {
+            printResult(io, fail('workflow.graph', 'WORKFLOW_LINT_FAILED', `workflow "${id}" has ${resolved.lint.errors.length} lint error(s): ${resolved.lint.errors.join('; ')}`, resolved.lint, [`peaks workflow lint ${id} --session ${options.session} --json`]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const graph = planWorkflow(resolved.spec, resolved.source);
+        const data = workflowGraphData(options.session, graph, resolved);
+        const actions = [
+            `Run \`peaks workflow run ${id} --session ${options.session} --json\` to materialize the run-plan order.`
+        ];
+        printResult(io, ok('workflow.graph', data, [], actions), options.json);
+    }
+    catch (error) {
+        reportWorkflowGraphFailure(io, error, options.session, options.json);
+    }
+}
+function runWorkflowLint(id, options, io) {
+    try {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const resolved = resolveWorkflow(projectRoot, id);
+        if (resolved.source.kind === 'missing') {
+            printResult(io, fail('workflow.lint', 'WORKFLOW_NOT_FOUND', `workflow "${id}" not found`, { sessionId: options.session }, [`Create .peaks/workflows/${id}.yaml`]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('workflow.lint', {
+            sessionId: options.session,
+            source: resolved.source,
+            lint: resolved.lint
+        }, [], []), options.json);
+        if (!resolved.lint.ok)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        reportWorkflowLintFailure(io, error, options.session, options.json);
+    }
+}

package/dist/cli/commands/loop-export-command.d.ts

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

package/dist/cli/commands/loop-export-command.js

@@ -0,0 +1,73 @@
+// src/cli/commands/loop-export-command.ts
+//
+// `peaks loop export` (M7, spec §7A.2) — export a loop_release as a
+// `peaks.bundle/1` tarball, hard-blocked when the source has `shareable=false`.
+// Extracted from `loop-commands.ts`; the registered name, description, options,
+// refusal codes and envelope are unchanged.
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { openStateDb } from '../../services/skillhub/sqlite-store.js';
+import { BundleAssetNotFoundError, BundleNotShareableError, writeBundle } from '../../services/share/bundle-writer.js';
+import { printResult } from '../cli-helpers.js';
+import { LOOP_EXPORT_IMPORT_OPTS, resolveLoopProjectRoot } from './loop-command-shared.js';
+export function registerLoopExportCommand(loop, io) {
+    LOOP_EXPORT_IMPORT_OPTS(loop
+        .command('export')
+        .description('M7: export a loop_release as a peaks.bundle/1 tarball (spec §7A.2 / §10 RL-9). Refuses to export when shareable=false.')
+        .requiredOption('--loop <id>', 'loop_release id (kebab-case)')
+        .requiredOption('--out <path>', 'output .tar.gz path')).action((options) => {
+        const asJson = options.json === true;
+        try {
+            const result = exportLoopBundle(options);
+            printResult(io, ok('loop.export', {
+                outPath: result.outPath,
+                kind: result.kind,
+                assetId: result.assetId,
+                importedAs: 'candidate'
+            }, [], [
+                `Receiver must run \`peaks loop import --in ${result.outPath}\` to land this bundle, then run an independent evolution_evaluation before any promote.`
+            ]), asJson);
+        }
+        catch (error) {
+            const refusal = exportRefusal(error, options.loop) ??
+                fail('loop.export', 'LOOP_EXPORT_FAILED', getErrorMessage(error), { ok: false, loop: options.loop }, ['Verify --loop id and --out path.']);
+            printResult(io, refusal, asJson);
+            process.exitCode = 1;
+        }
+    });
+}
+/** Open `<projectRoot>/.peaks/state.db` (creating `.peaks/`) and write the bundle. */
+function exportLoopBundle(options) {
+    const projectRoot = resolveLoopProjectRoot(options.project);
+    if (!existsSync(join(projectRoot, '.peaks'))) {
+        mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
+    }
+    const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
+    try {
+        return writeBundle({
+            db,
+            blobsDir: join(projectRoot, '.peaks', 'blobs'),
+            kind: 'loop',
+            id: options.loop,
+            outPath: options.out
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+/** The two named refusals `writeBundle` raises, or `null` for anything else. */
+function exportRefusal(error, loop) {
+    if (error instanceof BundleNotShareableError) {
+        return fail('loop.export', error.code, error.message, { ok: false, loop }, [
+            'Set shareable=true on the loop_release row, or share via desktop_visible=false.'
+        ]);
+    }
+    if (error instanceof BundleAssetNotFoundError) {
+        return fail('loop.export', error.code, error.message, { ok: false, loop }, [
+            'Verify the loop id with `peaks asset status --loop <id>`.'
+        ]);
+    }
+    return null;
+}

package/dist/cli/commands/loop-goal-compose-command.d.ts

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

package/dist/cli/commands/loop-goal-compose-command.js

@@ -0,0 +1,36 @@
+// src/cli/commands/loop-goal-compose-command.ts
+//
+// `peaks goal compose` — registered as a TOP-LEVEL command (not under
+// `peaks loop`) because IDE adapters expose it as `goalCommand` and the
+// sub-agent dispatch path consumes it. Extracted from `loop-commands.ts`; the
+// registered name, description, options and envelope are unchanged.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const GOAL_COMPOSE_SUMMARY = 'goal.compose is a thin facade; the LLM-side UX layer decomposes the goal into sub-agent tasks.';
+export function registerLoopGoalComposeCommand(program, io) {
+    addJsonOption(program
+        .command('goal')
+        .description('14.5: compose an autonomous goal (returns the goal envelope that the LLM-side UX layer feeds to peaks sub-agent dispatch)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--goal <text>', 'the high-level goal to compose')).action((options) => {
+        try {
+            printResult(io, ok('goal.compose', goalComposePayload(options), [], [GOAL_COMPOSE_SUMMARY]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('goal.compose', 'GOAL_COMPOSE_FAILED', getErrorMessage(error), { project: options.project, goal: options.goal }, ['Verify the project path and --goal value']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+/** The placeholder body; the LLM-side UX layer decomposes `goal` into tasks. */
+function goalComposePayload(options) {
+    return {
+        project: options.project,
+        goal: options.goal,
+        status: 'placeholder',
+        nextSteps: [
+            'The composed goal is consumed by peaks sub-agent dispatch.',
+            'The hermes + openclaw IDE adapters (Slice #0.7) surface this as a goalCommand.'
+        ]
+    };
+}

package/dist/cli/commands/loop-import-command.d.ts

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

package/dist/cli/commands/loop-import-command.js

@@ -0,0 +1,86 @@
+// src/cli/commands/loop-import-command.ts
+//
+// `peaks loop import` (M7, spec §7A.2) — extract a `peaks.bundle/1` tarball and
+// land it as `candidate` only; promotion needs an evolution_evaluation row.
+// Extracted from `loop-commands.ts`; the registered name, description, options,
+// refusal codes and envelope are unchanged.
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { openStateDb } from '../../services/skillhub/sqlite-store.js';
+import { BundleImportToStableForbiddenError, BundleMajorVersionMismatchError, BundleMalformedError, BundleSchemaVersionsMismatchError, readBundle } from '../../services/share/bundle-reader.js';
+import { printResult } from '../cli-helpers.js';
+import { LOOP_EXPORT_IMPORT_OPTS, resolveLoopProjectRoot } from './loop-command-shared.js';
+export function registerLoopImportCommand(loop, io) {
+    LOOP_EXPORT_IMPORT_OPTS(loop
+        .command('import')
+        .description('M7: import a peaks.bundle/1 tarball. Lands as candidate only — promotion requires an evolution_evaluation row (spec §7A.2 / §10 RL-9 / AC-25 / AC-26).')
+        .requiredOption('--in <path>', 'input .tar.gz path')
+        .option('--as <id>', 'optional rename for the loop id when landing')).action((options) => {
+        const asJson = options.json === true;
+        try {
+            const result = importLoopBundle(options);
+            printResult(io, ok('loop.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 loop promote refuses without an evolution_evaluation row.'
+            ]), asJson);
+        }
+        catch (error) {
+            const refusal = importRefusal(error, options.in) ??
+                fail('loop.import', 'LOOP_IMPORT_FAILED', getErrorMessage(error), { ok: false, inPath: options.in }, ['Verify the bundle path and integrity.']);
+            printResult(io, refusal, asJson);
+            process.exitCode = 1;
+        }
+    });
+}
+/** Open `<projectRoot>/.peaks/state.db` (creating `.peaks/`) and read the bundle in. */
+function importLoopBundle(options) {
+    const projectRoot = resolveLoopProjectRoot(options.project);
+    if (!existsSync(join(projectRoot, '.peaks'))) {
+        mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
+    }
+    const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
+    try {
+        return readBundle({
+            db,
+            blobsDir: join(projectRoot, '.peaks', 'blobs'),
+            inPath: options.in,
+            ...(options.as !== undefined ? { asName: options.as } : {})
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * The four named bundle refusals, each with the action its reader earned, or
+ * `null` for anything else. The `data` each carries differs (`receivedMajor` on
+ * a version mismatch, `inPath` on a malformed bundle), so the branches are a
+ * flat guard chain rather than a table with a `data` callback.
+ */
+function importRefusal(error, inPath) {
+    if (error instanceof BundleMajorVersionMismatchError) {
+        return fail('loop.import', error.code, error.message, { ok: false, receivedMajor: error.receivedMajor }, ['Use the matching peaks.bundle/<major> reader; this peaks build only supports major=1.']);
+    }
+    if (error instanceof BundleSchemaVersionsMismatchError) {
+        return fail('loop.import', error.code, error.message, { ok: false }, [
+            'Source bundle did not declare the canonical schema versions; refuse the bundle.'
+        ]);
+    }
+    if (error instanceof BundleImportToStableForbiddenError) {
+        return fail('loop.import', error.code, error.message, { ok: false }, [
+            'Bundles always land as candidate; promotion to stable requires an evolution_evaluation row (AC-26).'
+        ]);
+    }
+    if (error instanceof BundleMalformedError) {
+        return fail('loop.import', error.code, error.message, { ok: false, inPath }, [
+            'Re-export from the source via `peaks loop export`.'
+        ]);
+    }
+    return null;
+}

package/dist/cli/commands/loop-placeholder-commands.d.ts

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

package/dist/cli/commands/loop-placeholder-commands.js

@@ -0,0 +1,52 @@
+// src/cli/commands/loop-placeholder-commands.ts
+//
+// `peaks loop preflight|detect-pattern|check-consistency` — the three 14.x
+// placeholder facades. They differ only in their verb, the list of things the
+// LLM-side UX layer should run instead, and the one-line note on the envelope;
+// three copies of the same builder is what pushed `registerLoopCommands` past
+// the per-function line cap. Extracted from `loop-commands.ts` as one table;
+// every registered name, description, option and envelope is unchanged.
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+const PLACEHOLDERS = [
+    {
+        verb: 'preflight',
+        command: 'loop.preflight',
+        description: '14.2: pre-run sanity checks (placeholder; future slice runs peaks doctor + peaks audit before each loop iter)',
+        nextSteps: [
+            'For each L4 loop iteration, call peaks doctor + peaks audit to surface regressions.',
+            'A future slice will inline the preflight checks (not just placeholder).'
+        ],
+        summary: 'loop.preflight is a thin facade; the LLM-side UX layer composes peaks doctor + peaks audit.'
+    },
+    {
+        verb: 'detect-pattern',
+        command: 'loop.detect-pattern',
+        description: '14.3: detect repeating patterns across past sessions (placeholder; future slice uses peaks retrospective search)',
+        nextSteps: [
+            'Run peaks retrospective search --limit 50 to surface high-frequency patterns.',
+            'A future slice will rank by frequency + LLM confidence.'
+        ],
+        summary: 'loop.detect-pattern is a thin facade; the LLM-side UX layer composes peaks retrospective search.'
+    },
+    {
+        verb: 'check-consistency',
+        command: 'loop.check-consistency',
+        description: '14.4: verify state consistency (placeholder; future slice compares .peaks/_runtime across sessions)',
+        nextSteps: [
+            'Compare .peaks/_runtime/<sid>/session.json across recent sessions for drift.',
+            'A future slice will report drift with severity (warn / fail).'
+        ],
+        summary: 'loop.check-consistency is a thin facade; the LLM-side UX layer composes the drift scan.'
+    }
+];
+export function registerLoopPlaceholderCommands(loop, io) {
+    for (const spec of PLACEHOLDERS) {
+        addJsonOption(loop
+            .command(spec.verb)
+            .description(spec.description)
+            .requiredOption('--project <path>', 'target project root')).action((options) => {
+            printResult(io, ok(spec.command, { project: options.project, status: 'placeholder', nextSteps: [...spec.nextSteps] }, [], [spec.summary]), options.json);
+        });
+    }
+}

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

@@ -0,0 +1,10 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+/** Absolute path of the MCP server's process entry. */
+export declare function mcpServerEntryPath(): string;
+/** The exact command this launcher will spawn, resolved without spawning it. */
+export declare function mcpServeInvocation(entry?: string): {
+    command: string;
+    args: string[];
+};
+export declare function registerMcpCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,157 @@
+// src/cli/commands/mcp-commands.ts
+//
+// `peaks mcp` — the command family around the read-only MCP surface. This slice
+// delivers `serve`; `install` / `uninstall` / `status` are the distribution
+// slice's (spec §12, segment ③).
+//
+// WHY THIS FILE DOES NOT IMPORT THE SERVER. The design's load-bearing invariant
+// is that `src/services/mcp/` is a DELETABLE PIPE (spec §1): remove it and the
+// CLI is unchanged, the interceptor is unchanged, and a harness that used MCP
+// simply falls back to Bash. That invariant is an assertion about import edges,
+// and it is enforced by `tests/unit/standards/no-mcp-source-import.test.ts` —
+// which reports an edge from any module outside the MCP root, this file
+// included. So the server is reached the way the design says a server is
+// reached: as a PROCESS, by path.
+//
+// The path is computed here rather than asked for, because asking would be the
+// import. `SOURCE_TREE` / `TREE_DIR` are the same two facts every other
+// self-spawn in this tree derives the same way (see `daemon-supervisor.ts`):
+// this file's own extension says which tree it was loaded from, and its own
+// directory says where that tree is.
+import { spawn } from 'node:child_process';
+import { dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { installMcpForAdapter, resolveMcpServerArgv, spawnMcpInstallRunner, uninstallMcpForAdapter } from '../../services/distribution/mcp-install.js';
+import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
+import { resolveIdeOptionHelp, tryGetAdapter } from '../../services/ide/ide-registry.js';
+import { interpreterArgs } from '../../services/web/daemon-supervisor.js';
+import { printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+/** This file's directory — `<root>/src/cli/commands` or `<root>/dist/cli/commands`. */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+/** `<root>/src` or `<root>/dist`. */
+const TREE_DIR = resolve(MODULE_DIR, '..', '..');
+/** Compiled trees run `.js` under node; the source tree is TypeScript. */
+const SOURCE_TREE = extname(fileURLToPath(import.meta.url)) === '.ts';
+/** Absolute path of the MCP server's process entry. */
+export function mcpServerEntryPath() {
+    return join(TREE_DIR, 'services', 'mcp', SOURCE_TREE ? 'server-main.ts' : 'server-main.js');
+}
+/** The exact command this launcher will spawn, resolved without spawning it. */
+export function mcpServeInvocation(entry = mcpServerEntryPath()) {
+    return { command: process.execPath, args: interpreterArgs(entry) };
+}
+/**
+ * Hand the process over to the MCP server: the child inherits all three standard
+ * streams, so the harness's stdin/stdout pipe IS the server's pipe and this
+ * process adds a frame of indirection and nothing else.
+ */
+function runMcpServe(io, options) {
+    const invocation = mcpServeInvocation();
+    const child = spawn(invocation.command, invocation.args, {
+        stdio: 'inherit',
+        cwd: options.project ?? process.cwd(),
+        // Windows contract: a spawned child must not allocate a console window.
+        windowsHide: true
+    });
+    child.on('error', (error) => {
+        printResult(io, fail('mcp.serve', 'MCP_SERVE_SPAWN_FAILED', `Could not start the MCP server: ${error.message}`, {
+            entry: invocation.args.at(-1) ?? ''
+        }, ['Check that the build is present, or run `pnpm build`']), options.json === true);
+        process.exitCode = 1;
+    });
+    child.on('exit', (code, signal) => {
+        // The child's status IS this command's status — an MCP client reads the
+        // server's exit, so masking it would be the only lie this launcher told.
+        if (signal !== null) {
+            process.exitCode = 1;
+            return;
+        }
+        process.exitCode = code ?? 0;
+    });
+}
+export function registerMcpCommands(program, io) {
+    const mcp = program
+        .command('mcp')
+        .description('Serve peaks-loop read-only capabilities over MCP (stdio)');
+    mcp
+        .command('serve')
+        .description('Run the read-only MCP server on stdio until the caller closes it')
+        .option('--project <path>', 'project the server runs the CLI in (default: current directory)')
+        .action((options) => {
+        runMcpServe(io, options);
+    });
+    registerMcpRegistrationCommands(mcp, io);
+}
+function resolveTargetAdapter(options) {
+    const ide = options.ide !== undefined && options.ide.length > 0
+        ? options.ide
+        : detectIdeFromContext({ env: process.env, cwd: process.cwd(), parsedStdin: null });
+    const adapter = tryGetAdapter(ide);
+    return adapter === undefined ? { kind: 'unsupported', ide } : { kind: 'adapter', adapter };
+}
+/** One envelope line per adapter: what was registered, or why nothing was. */
+function reportRegistration(result, verb) {
+    if (result.skipped) {
+        return `${result.ideId}: skipped — ${result.reason}`;
+    }
+    const { report } = result;
+    return `${result.ideId}: ${verb} ${report.ok ? 'ok' : 'FAILED'} — ${report.detail}`;
+}
+/** The `data` BOTH envelopes carry, so the failure path is never a thinner shape. */
+function registrationEnvelopeData(result, verb) {
+    return {
+        ide: result.ideId,
+        skipped: result.skipped,
+        summary: reportRegistration(result, verb),
+        registration: result
+    };
+}
+function runMcpRegistration(io, verb, options) {
+    const target = resolveTargetAdapter(options);
+    if (target.kind === 'unsupported') {
+        printResult(io, fail(`mcp.${verb}`, 'MCP_HARNESS_UNSUPPORTED', `No adapter is registered for harness '${target.ide}'.`, { ide: target.ide }, ['Pass --ide with a registered adapter id']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    const { adapter } = target;
+    const serverArgv = resolveMcpServerArgv();
+    const result = verb === 'install'
+        ? installMcpForAdapter(adapter, serverArgv, spawnMcpInstallRunner)
+        : uninstallMcpForAdapter(adapter, serverArgv, spawnMcpInstallRunner);
+    const report = result.skipped ? undefined : result.report;
+    if (report !== undefined && !report.ok) {
+        printResult(io, fail(`mcp.${verb}`, 'MCP_REGISTRATION_FAILED', report.detail, registrationEnvelopeData(result, verb), ['Run the harness command by hand to see its own error']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    printResult(io, ok(`mcp.${verb}`, registrationEnvelopeData(result, verb)), options.json === true);
+}
+/**
+ * `peaks mcp install` / `peaks mcp uninstall` — the distribution half of the MCP
+ * surface, and an explicit pair on purpose (spec §8.3 Q19): an uninstall that
+ * only ran from a package manager's hook is skipped whenever the manager decides
+ * to skip it, and the leftover registration then makes the NEXT install fail on
+ * a duplicate. Neither command starts a process; they register one.
+ */
+function registerMcpRegistrationCommands(mcp, io) {
+    mcp
+        .command('install')
+        .description('Register the peaks MCP server with the detected harness. Removes the name ' +
+        'from every declared scope first, because the harness registers non-idempotently. ' +
+        'A harness whose adapter declares no registration entry is skipped, not failed.')
+        .option('--ide <id>', resolveIdeOptionHelp())
+        .option('--json', 'JSON envelope output')
+        .action((options) => {
+        runMcpRegistration(io, 'install', options);
+    });
+    mcp
+        .command('uninstall')
+        .description('Remove the peaks MCP registration from the harness, sweeping every scope it ' +
+        'may hold. Explicit, because no package-manager hook is relied on.')
+        .option('--ide <id>', resolveIdeOptionHelp())
+        .option('--json', 'JSON envelope output')
+        .action((options) => {
+        runMcpRegistration(io, 'uninstall', options);
+    });
+}