peaks-cli 1.0.12 → 1.0.13

package/dist/src/cli/commands/config-commands.js

@@ -1,5 +1,4 @@
-import { getLocalArtifactPath } from '../../services/artifacts/workspace-service.js';
-import { addWorkspace, ensureWorkspaceConfigForPath, getConfig, getMiniMaxProviderConfig, getMiniMaxProviderStatus, isSensitiveConfigPath, readConfig, redactConfigSecrets, removeWorkspace, setConfig, setCurrentWorkspace, setMiniMaxProviderConfig } from '../../services/config/config-service.js';
+import { addWorkspace, getConfig, getMiniMaxProviderConfig, getMiniMaxProviderStatus, isSensitiveConfigPath, readConfig, redactConfigSecrets, removeWorkspace, setConfig, setCurrentWorkspace, setMiniMaxProviderConfig } from '../../services/config/config-service.js';
 import { testMiniMaxProvider } from '../../services/providers/minimax-provider-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, isArtifactProvider, isArtifactRepoSegment, isMiniMaxHttpsUrl, parseConfigLayer, printInvalidConfigLayer, printResult, redactSensitiveErrorMessage, summarizeMiniMaxSmokeResult } from '../cli-helpers.js';
@@ -136,21 +135,6 @@ function registerWorkspaceCommands(config, io) {
         const cfg = readConfig();
         printResult(io, ok('config.workspace.list', { currentWorkspace: cfg.currentWorkspace, workspaces: cfg.workspaces }), options.json);
     });
-    addJsonOption(configWorkspace.command('ensure').description('Ensure a user workspace exists for a project path and make it current').option('--path <path>', 'project path to ensure, defaults to cwd')).action((options) => {
-        try {
-            const workspace = ensureWorkspaceConfigForPath(options.path ?? process.cwd());
-            if (!workspace) {
-                printResult(io, fail('config.workspace.ensure', 'WORKSPACE_ENSURE_FAILED', 'Could not resolve a workspace for the provided path', {}, ['Run from inside a project or pass --path <project>']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, ok('config.workspace.ensure', { workspace, currentWorkspace: workspace.workspaceId, artifactWorkspacePath: getLocalArtifactPath(workspace) }), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('config.workspace.ensure', 'WORKSPACE_ENSURE_FAILED', getErrorMessage(error), {}, ['Check that the project path exists and artifact workspace markers are safe']), options.json);
-            process.exitCode = 1;
-        }
-    });
     addJsonOption(configWorkspace.command('add').description('Add a workspace').requiredOption('--id <id>', 'workspace identifier').requiredOption('--name <name>', 'workspace display name').requiredOption('--path <path>', 'workspace root path').option('--provider <provider>', 'artifact repo provider: github or gitlab').option('--repo-owner <owner>', 'artifact repo owner').option('--repo-name <name>', 'artifact repo name').option('--layer <layer>', 'user or project')).action((options) => {
         const layer = parseConfigLayer(options.layer);
         if (layer === null) {

package/dist/src/cli/commands/core-artifact-commands.js

@@ -6,6 +6,7 @@ import { listProfiles } from '../../services/profiles/profile-service.js';
 import { planProxyTest } from '../../services/proxy/proxy-service.js';
 import { runDoctor } from '../../services/doctor/doctor-service.js';
 import { listSkills } from '../../services/skills/skill-registry.js';
+import { inspectSkillRunbook } from '../../services/skills/skill-runbook-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, isArtifactProvider, isArtifactSetupStep, printResult } from '../cli-helpers.js';
 export function registerCoreAndArtifactCommands(program, io) {
@@ -33,6 +34,28 @@ export function registerCoreAndArtifactCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(skill
+        .command('runbook <name>')
+        .description('Inspect a skill Default runbook section and its --apply authorization-note status')).action(async (name, options) => {
+        try {
+            const inspection = await inspectSkillRunbook(name);
+            const result = inspection.ok
+                ? ok('skill.runbook', inspection)
+                : fail('skill.runbook', inspection.hasRunbook ? 'SKILL_RUNBOOK_APPLY_UNGATED' : 'SKILL_RUNBOOK_MISSING', inspection.hasRunbook
+                    ? `Skill ${inspection.name} has ${inspection.destructiveApplyLines.length} destructive --apply command(s) without an authorization/dry-run note`
+                    : `Skill ${inspection.name} is missing a ## Default runbook section`, inspection, inspection.hasRunbook
+                    ? ['Add an authorization or --dry-run note next to destructive --apply lines in the runbook section']
+                    : ['Add a `## Default runbook` section to the skill SKILL.md']);
+            printResult(io, result, options.json);
+            if (!inspection.ok) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('skill.runbook', 'SKILL_NOT_FOUND', getErrorMessage(error), { name }), options.json);
+            process.exitCode = 1;
+        }
+    });
     const profile = program.command('profile').description('Manage runtime profiles');
     addJsonOption(profile.command('list').description('List available profiles')).action((options) => {
         printResult(io, ok('profile.list', { profiles: listProfiles() }), options.json);

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

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

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

@@ -0,0 +1,144 @@
+import { InvalidArgumentError } from 'commander';
+import { readFile } from 'node:fs/promises';
+import { scanMcpServers } from '../../services/mcp/mcp-scan-service.js';
+import { planMcpInstall } from '../../services/mcp/mcp-plan-service.js';
+import { applyMcpInstall, rollbackMcpInstall } from '../../services/mcp/mcp-apply-service.js';
+import { callMcpTool } from '../../services/mcp/mcp-call-service.js';
+import { createStdioTransportFromSpec } from '../../services/mcp/mcp-stdio-transport.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, printResult } from '../cli-helpers.js';
+function parsePositiveInteger(value) {
+    if (!/^\d+$/.test(value)) {
+        throw new InvalidArgumentError('must be a positive integer');
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        throw new InvalidArgumentError('must be a positive integer');
+    }
+    return parsed;
+}
+async function resolveCallArgs(options) {
+    if (options.argsJson !== undefined && options.args !== undefined) {
+        throw new Error('Pass either --args-json or --args, not both');
+    }
+    const raw = options.argsJson !== undefined
+        ? options.argsJson
+        : options.args !== undefined ? await readFile(options.args, 'utf8') : '{}';
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('MCP tool arguments must be a JSON object');
+    }
+    return parsed;
+}
+export function registerMcpCommands(program, io) {
+    const mcp = program.command('mcp').description('Manage Claude Code MCP servers');
+    addJsonOption(mcp
+        .command('list')
+        .alias('scan')
+        .description('Scan Claude Code settings for configured MCP servers')
+        .option('--project <path>', 'project root to also scan project-level .claude/settings.json')).action(async (options) => {
+        try {
+            const report = await scanMcpServers(options.project !== undefined ? { projectRoot: options.project } : {});
+            printResult(io, ok('mcp.list', report), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('mcp.list', 'MCP_LIST_FAILED', getErrorMessage(error), {}, ['Check Claude settings path and permissions before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(mcp
+        .command('plan')
+        .description('Plan an MCP server install diff for a capability (dry-run only)')
+        .requiredOption('--capability <id>', 'capability id from the MCP install registry')
+        .option('--project <path>', 'project root for scoped scan')
+        .option('--dry-run', 'preview the install diff (always true)', true)
+        .option('--no-dry-run', 'unsupported: peaks mcp plan never writes settings')).action(async (options) => {
+        if (options.dryRun === false) {
+            failUnsupportedNonDryRun(io, 'mcp.plan', options.json);
+            return;
+        }
+        try {
+            const planOptions = options.project !== undefined ? { projectRoot: options.project } : {};
+            const plan = await planMcpInstall(options.capability, planOptions);
+            if (plan.action === 'unknown-capability') {
+                printResult(io, fail('mcp.plan', 'MCP_UNKNOWN_CAPABILITY', `No MCP install spec registered for capability ${options.capability}`, plan, plan.nextActions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('mcp.plan', plan, [], plan.nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('mcp.plan', 'MCP_PLAN_FAILED', getErrorMessage(error), { capabilityId: options.capability }, ['Check Claude settings path and the capability id before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(mcp
+        .command('apply')
+        .description('Apply an MCP server install for a capability (writes .claude/settings.json with backup)')
+        .requiredOption('--capability <id>', 'capability id from the MCP install registry')
+        .option('--yes', 'confirm the write — required for any real side effect')
+        .option('--claim', 'take ownership of an existing non-peaks-managed server entry')
+        .option('--project <path>', 'project root for scoped scan')).action(async (options) => {
+        if (options.yes !== true) {
+            printResult(io, fail('mcp.apply', 'MCP_APPLY_REQUIRES_YES', 'Refusing to apply without --yes', { capabilityId: options.capability }, ['Re-run with --yes to confirm the write']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const applyOptions = {};
+            if (options.project !== undefined) {
+                applyOptions.projectRoot = options.project;
+            }
+            if (options.claim === true) {
+                applyOptions.claim = true;
+            }
+            const result = await applyMcpInstall(options.capability, applyOptions);
+            printResult(io, ok('mcp.apply', result), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('mcp.apply', 'MCP_APPLY_FAILED', getErrorMessage(error), { capabilityId: options.capability }, ['Check the plan first with peaks mcp plan, then re-run apply']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(mcp
+        .command('rollback')
+        .description('Restore Claude Code settings.json from a peaks-managed MCP backup file')
+        .requiredOption('--backup <path>', 'path to a previously created backup settings.json')).action(async (options) => {
+        try {
+            const result = await rollbackMcpInstall({ backupPath: options.backup });
+            printResult(io, ok('mcp.rollback', result), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('mcp.rollback', 'MCP_ROLLBACK_FAILED', getErrorMessage(error), { backupPath: options.backup }, ['Verify the backup path and rerun']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(mcp
+        .command('call')
+        .description('Invoke a tool on an installed MCP server via stdio (spawns the server, calls tools/call, closes)')
+        .requiredOption('--capability <id>', 'capability id from the MCP install registry')
+        .requiredOption('--tool <name>', 'MCP tool name to invoke')
+        .option('--args <path>', 'path to a JSON file describing the tool arguments object')
+        .option('--args-json <jsonString>', 'inline JSON object describing the tool arguments')
+        .option('--timeout <ms>', 'per-request timeout in milliseconds', parsePositiveInteger)).action(async (options) => {
+        try {
+            const args = await resolveCallArgs(options);
+            const factory = createStdioTransportFromSpec;
+            const callOptions = {
+                capabilityId: options.capability,
+                toolName: options.tool,
+                args,
+                transportFactory: factory
+            };
+            if (options.timeout !== undefined) {
+                callOptions.timeoutMs = Number(options.timeout);
+            }
+            const result = await callMcpTool(callOptions);
+            printResult(io, ok('mcp.call', result), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('mcp.call', 'MCP_CALL_FAILED', getErrorMessage(error), { capabilityId: options.capability, toolName: options.tool }, ['Check the capability id, tool name, args JSON, and required env vars before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/commands/openspec-commands.d.ts

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

package/dist/src/cli/commands/openspec-commands.js

@@ -0,0 +1,169 @@
+import { readFile } from 'node:fs/promises';
+import { loadOpenSpecChange, scanOpenSpec } from '../../services/openspec/openspec-scan-service.js';
+import { projectOpenSpecToRdInput } from '../../services/openspec/openspec-bridge-service.js';
+import { renderOpenSpecChange } from '../../services/openspec/openspec-render-service.js';
+import { validateOpenSpecChange } from '../../services/openspec/openspec-validate-service.js';
+import { archiveOpenSpecChange } from '../../services/openspec/openspec-archive-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+function resolveScanOptions(project) {
+    if (project === undefined) {
+        return {};
+    }
+    return { openspecRoot: `${project.replace(/\\/g, '/').replace(/\/$/, '')}/openspec` };
+}
+async function loadRenderRequest(requestPath) {
+    const raw = await readFile(requestPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Render request file must contain a JSON object');
+    }
+    return parsed;
+}
+export function registerOpenSpecCommands(program, io) {
+    const openspec = program.command('openspec').description('Inspect OpenSpec changes inside the target project');
+    addJsonOption(openspec
+        .command('list')
+        .description('List OpenSpec changes detected under <project>/openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')).action(async (options) => {
+        try {
+            const report = await scanOpenSpec(resolveScanOptions(options.project));
+            printResult(io, ok('openspec.list', report), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.list', 'OPENSPEC_LIST_FAILED', getErrorMessage(error), {}, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('show')
+        .description('Show parsed proposal and tasks progress for a single OpenSpec change')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')).action(async (changeId, options) => {
+        try {
+            const detail = await loadOpenSpecChange(changeId, resolveScanOptions(options.project));
+            if (detail === null) {
+                printResult(io, fail('openspec.show', 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('openspec.show', detail), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.show', 'OPENSPEC_SHOW_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('to-rd')
+        .description('Project an OpenSpec change into an RD/SC input shape (acceptance, what-changes, commit boundaries)')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')).action(async (changeId, options) => {
+        try {
+            const projection = await projectOpenSpecToRdInput(changeId, resolveScanOptions(options.project));
+            if (projection === null) {
+                printResult(io, fail('openspec.to-rd', 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('openspec.to-rd', projection), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.to-rd', 'OPENSPEC_TO_RD_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('render')
+        .description('Render an OpenSpec change pack from a JSON request file (dry-run by default)')
+        .requiredOption('--request <path>', 'path to a JSON file describing the render request')
+        .option('--project <path>', 'project root containing an openspec/ directory')
+        .option('--apply', 'write the rendered files into openspec/changes/<id>/')
+        .option('--overwrite', 'overwrite an existing change directory when --apply is set')).action(async (options) => {
+        try {
+            const request = await loadRenderRequest(options.request);
+            const scan = resolveScanOptions(options.project);
+            const renderOptions = {};
+            if (scan.openspecRoot !== undefined) {
+                renderOptions.openspecRoot = scan.openspecRoot;
+            }
+            if (options.apply === true) {
+                renderOptions.apply = true;
+            }
+            if (options.overwrite === true) {
+                renderOptions.overwrite = true;
+            }
+            const result = await renderOpenSpecChange(request, renderOptions);
+            printResult(io, ok('openspec.render', result), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.render', 'OPENSPEC_RENDER_FAILED', getErrorMessage(error), { requestPath: options.request }, ['Check the request JSON shape and the openspec root before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('validate')
+        .description('Validate an OpenSpec change against internal lint rules (and optionally the external openspec CLI)')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')
+        .option('--prefer-external', 'use the external openspec CLI when available, fall back to internal lint')).action(async (changeId, options) => {
+        try {
+            const scan = resolveScanOptions(options.project);
+            const validateOptions = {};
+            if (scan.openspecRoot !== undefined) {
+                validateOptions.openspecRoot = scan.openspecRoot;
+            }
+            if (options.preferExternal === true) {
+                validateOptions.preferExternal = true;
+            }
+            const result = await validateOpenSpecChange(changeId, validateOptions);
+            if (result === null) {
+                printResult(io, fail('openspec.validate', 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!result.valid) {
+                printResult(io, fail('openspec.validate', 'OPENSPEC_VALIDATE_INVALID', `OpenSpec change ${changeId} failed validation`, result, result.issues.map((issue) => `${issue.level}: ${issue.rule}: ${issue.message}`)), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('openspec.validate', result, result.issues.filter((issue) => issue.level === 'warning').map((issue) => `${issue.rule}: ${issue.message}`)), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.validate', 'OPENSPEC_VALIDATE_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('archive')
+        .description('Move an OpenSpec change under openspec/changes/<archiveDir>/<id>/ (dry-run by default)')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')
+        .option('--apply', 'actually move the change directory')
+        .option('--archive-dir <name>', 'archive subdirectory name (default: archive)')).action(async (changeId, options) => {
+        try {
+            const scan = resolveScanOptions(options.project);
+            const archiveOptions = {};
+            if (scan.openspecRoot !== undefined) {
+                archiveOptions.openspecRoot = scan.openspecRoot;
+            }
+            if (options.apply === true) {
+                archiveOptions.apply = true;
+            }
+            if (options.archiveDir !== undefined) {
+                archiveOptions.archiveDirName = options.archiveDir;
+            }
+            const result = await archiveOpenSpecChange(changeId, archiveOptions);
+            if (result === null) {
+                printResult(io, fail('openspec.archive', 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('openspec.archive', result, [], result.applied ? [] : [`Re-run with --apply to move ${result.from} → ${result.to}`]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.archive', 'OPENSPEC_ARCHIVE_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/commands/project-commands.d.ts

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

package/dist/src/cli/commands/project-commands.js

@@ -0,0 +1,37 @@
+import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerProjectCommands(program, io) {
+    const project = program.command('project').description('Aggregate Peaks state for a target project (read-only)');
+    addJsonOption(project
+        .command('dashboard')
+        .description('One-call snapshot of doctor / MCP / OpenSpec / requests / Understand Anything / capabilities for a project')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        try {
+            const dashboard = await loadProjectDashboard({ projectRoot: options.project });
+            if (!dashboard.runbookHealth.ok) {
+                const suggestions = [
+                    dashboard.runbookHealth.missingRunbook.length > 0
+                        ? `Add a ## Default runbook section to: ${dashboard.runbookHealth.missingRunbook.join(', ')}`
+                        : null,
+                    dashboard.runbookHealth.applyNoteFailed.length > 0
+                        ? `Add authorization/--dry-run notes next to destructive --apply lines in: ${dashboard.runbookHealth.applyNoteFailed.join(', ')}`
+                        : null
+                ].filter((line) => line !== null);
+                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_RUNBOOK_UNHEALTHY', `Skill runbook health failing: ${dashboard.runbookHealth.healthy}/${dashboard.runbookHealth.required} healthy`, dashboard, suggestions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!dashboard.doctor.ok) {
+                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_DOCTOR_FAILED', `Doctor reports ${dashboard.doctor.failed} failed check(s) (${dashboard.doctor.passed} passed)`, dashboard, ['Run `peaks doctor --json` and resolve the failing checks before re-running the dashboard']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('project.dashboard', dashboard), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

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

package/dist/src/cli/commands/request-commands.js

@@ -0,0 +1,140 @@
+import { InvalidArgumentError } from 'commander';
+import { allowedStatesForRole, createRequestArtifact, listRequestArtifacts, showRequestArtifact, transitionRequestArtifact } from '../../services/artifacts/request-artifact-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const VALID_ROLES = ['prd', 'ui', 'rd', 'qa'];
+function parseRole(value) {
+    if (!VALID_ROLES.includes(value)) {
+        throw new InvalidArgumentError(`must be one of ${VALID_ROLES.join(', ')}`);
+    }
+    return value;
+}
+function parseStateForRole(role, value) {
+    const allowed = allowedStatesForRole(role);
+    if (!allowed.includes(value)) {
+        throw new InvalidArgumentError(`must be one of ${allowed.join(', ')} for role ${role}`);
+    }
+    return value;
+}
+export function registerRequestCommands(program, io) {
+    const request = program.command('request').description('Manage per-request Peaks role artifacts (PRD / UI / RD / QA)');
+    addJsonOption(request
+        .command('init')
+        .description('Create the per-request artifact template for a Peaks role (dry-run by default)')
+        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
+        .requiredOption('--id <request-id>', 'request id, e.g. 2026-05-23-add-foo')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <session>', 'override the default date-stamped session id')
+        .option('--apply', 'write the artifact file (default: preview only)')).action(async (options) => {
+        try {
+            const serviceOptions = {
+                role: options.role,
+                requestId: options.id,
+                projectRoot: options.project
+            };
+            if (options.sessionId !== undefined) {
+                serviceOptions.sessionId = options.sessionId;
+            }
+            if (options.apply === true) {
+                serviceOptions.apply = true;
+            }
+            const result = await createRequestArtifact(serviceOptions);
+            printResult(io, ok('request.init', result, [], result.applied ? [] : [`Re-run with --apply to write ${result.path}`]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('request.init', 'REQUEST_INIT_FAILED', getErrorMessage(error), { role: options.role, requestId: options.id }, ['Check role, request id, and project path before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(request
+        .command('list')
+        .description('List per-request artifacts under a project workspace')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <session>', 'limit to a specific session id')
+        .option('--role <role>', `limit to a single role (${VALID_ROLES.join(' | ')})`, parseRole)).action(async (options) => {
+        try {
+            const listOptions = { projectRoot: options.project };
+            if (options.sessionId !== undefined) {
+                listOptions.sessionId = options.sessionId;
+            }
+            if (options.role !== undefined) {
+                listOptions.role = options.role;
+            }
+            const items = await listRequestArtifacts(listOptions);
+            printResult(io, ok('request.list', { count: items.length, items }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('request.list', 'REQUEST_LIST_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check project path before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(request
+        .command('show')
+        .description('Show a single per-request artifact, optionally scoped to a session')
+        .argument('<request-id>', 'request id, e.g. 2026-05-23-add-foo')
+        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <session>', 'restrict to a specific session id')).action(async (requestId, options) => {
+        try {
+            const showOptions = {
+                projectRoot: options.project,
+                role: options.role,
+                requestId
+            };
+            if (options.sessionId !== undefined) {
+                showOptions.sessionId = options.sessionId;
+            }
+            const result = await showRequestArtifact(showOptions);
+            if (result === null) {
+                printResult(io, fail('request.show', 'REQUEST_NOT_FOUND', `No artifact found for role=${options.role} requestId=${requestId}`, { role: options.role, requestId }, ['Verify the request id, role, and session id']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('request.show', result), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('request.show', 'REQUEST_SHOW_FAILED', getErrorMessage(error), { role: options.role, requestId }, ['Check role, request id, and project path before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(request
+        .command('transition')
+        .description('Move a per-request artifact to a new state defined by its role state machine')
+        .argument('<request-id>', 'request id, e.g. 2026-05-23-add-foo')
+        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
+        .requiredOption('--state <state>', 'new state name; allowed values depend on role')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <session>', 'restrict to a specific session id')
+        .option('--reason <text>', 'optional reason appended as a transition note')).action(async (requestId, options) => {
+        try {
+            const role = options.role;
+            const newState = parseStateForRole(role, options.state);
+            const transitionOptions = {
+                role,
+                requestId,
+                projectRoot: options.project,
+                newState
+            };
+            if (options.sessionId !== undefined) {
+                transitionOptions.sessionId = options.sessionId;
+            }
+            if (options.reason !== undefined) {
+                transitionOptions.reason = options.reason;
+            }
+            const result = await transitionRequestArtifact(transitionOptions);
+            if (result === null) {
+                printResult(io, fail('request.transition', 'REQUEST_NOT_FOUND', `No artifact found for role=${role} requestId=${requestId}`, { role, requestId }, ['Verify the request id, role, and session id']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('request.transition', result), options.json);
+        }
+        catch (error) {
+            if (error instanceof InvalidArgumentError) {
+                throw error;
+            }
+            printResult(io, fail('request.transition', 'REQUEST_TRANSITION_FAILED', getErrorMessage(error), { role: options.role, requestId }, ['Check role, request id, state, and project path before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/commands/understand-commands.d.ts

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