peaks-loop 4.1.2 → 4.1.3

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/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);
+    });
+}

package/dist/cli/commands/request-command-options.d.ts

@@ -0,0 +1,49 @@
+import type { RequestArtifactRole, RequestArtifactState, RequestType } from '../../services/artifacts/request-artifact-service.js';
+export type RequestInitOptions = {
+    role: string;
+    id: string;
+    project: string;
+    sessionId?: string;
+    apply?: boolean;
+    type?: RequestType;
+    callerId?: string;
+    json?: boolean;
+};
+export type RequestListOptions = {
+    project: string;
+    sessionId?: string;
+    role?: RequestArtifactRole;
+    summary?: boolean;
+    json?: boolean;
+};
+export type RequestShowOptions = {
+    role: RequestArtifactRole;
+    project: string;
+    sessionId?: string;
+    json?: boolean;
+    pretty?: boolean;
+    compact?: boolean;
+};
+export type RequestTransitionOptions = {
+    role: RequestArtifactRole;
+    project: string;
+    state: RequestArtifactState;
+    sessionId?: string;
+    reason?: string;
+    allowIncomplete?: boolean;
+    confirm?: boolean;
+    forceConfirm?: boolean;
+    json?: boolean;
+};
+export type RequestLintOptions = {
+    role: RequestArtifactRole;
+    project: string;
+    sessionId?: string;
+    json?: boolean;
+};
+export type RequestRepairStatusOptions = {
+    project: string;
+    sessionId?: string;
+    maxCycles?: string;
+    json?: boolean;
+};

package/dist/cli/commands/request-command-options.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,10 +1,4 @@
-import { Command } from 'commander';
-import { type RequestArtifactSummary } from '../../services/artifacts/request-artifact-service.js';
-import { type ProgramIO } from '../cli-helpers.js';
-/**
- * `request list`. `count` is the true total; `names` carries
- * `role/requestId (state)` labels for the first N entries. The full `items`
- * array (with paths + timestamps) is one flag away — omit `--summary`.
- */
-export declare function buildRequestListSummary(items: readonly RequestArtifactSummary[]): Record<string, unknown>;
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export { buildRequestListSummary } from './request-list-command.js';
 export declare function registerRequestCommands(program: Command, io: ProgramIO): void;