peaks-cli 1.0.12 → 1.0.13

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

@@ -0,0 +1,78 @@
+import { InvalidArgumentError } from 'commander';
+import { scanUnderstandAnything, summarizeKnowledgeGraph } from '../../services/understand/understand-scan-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, 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;
+}
+const INSTALL_HINT = 'Install Understand Anything in Claude Code: `/plugin marketplace add Lum1104/Understand-Anything` then `/plugin install understand-anything`, then run `/understand` in the target project to generate .understand-anything/knowledge-graph.json.';
+export function registerUnderstandCommands(program, io) {
+    const understand = program.command('understand').description('Inspect Understand Anything artifacts inside a project (read-only)');
+    addJsonOption(understand
+        .command('status')
+        .description('Report whether Understand Anything has produced a knowledge graph in the target project')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--artifact-dir <path>', 'override the default .understand-anything directory')).action(async (options) => {
+        try {
+            const scanOptions = { projectRoot: options.project };
+            if (options.artifactDir !== undefined) {
+                scanOptions.artifactDir = options.artifactDir;
+            }
+            const report = await scanUnderstandAnything(scanOptions);
+            const nextActions = [];
+            if (!report.exists) {
+                nextActions.push(INSTALL_HINT);
+            }
+            else if (!report.graph.exists) {
+                nextActions.push('Run `/understand` inside Claude Code on this project to generate .understand-anything/knowledge-graph.json.');
+            }
+            else if (report.graph.parseError !== undefined) {
+                nextActions.push('Re-run `/understand` to regenerate the knowledge graph; the current file is not valid JSON.');
+            }
+            printResult(io, ok('understand.status', report, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('understand.status', 'UNDERSTAND_STATUS_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .understand-anything directory before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(understand
+        .command('show')
+        .description('Summarize the Understand Anything knowledge graph (counts, layers, tours, sample nodes) for RD/TXT consumption')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--artifact-dir <path>', 'override the default .understand-anything directory')
+        .option('--sample <n>', 'maximum number of sample node ids to return (default 5)', parsePositiveInteger)).action(async (options) => {
+        try {
+            const summaryOptions = { projectRoot: options.project };
+            if (options.artifactDir !== undefined) {
+                summaryOptions.artifactDir = options.artifactDir;
+            }
+            if (options.sample !== undefined) {
+                summaryOptions.sampleSize = options.sample;
+            }
+            const summary = await summarizeKnowledgeGraph(summaryOptions);
+            if (!summary.exists) {
+                printResult(io, fail('understand.show', 'UNDERSTAND_GRAPH_MISSING', `No knowledge graph found at ${summary.path}`, summary, [INSTALL_HINT]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (summary.parseError !== undefined) {
+                printResult(io, fail('understand.show', 'UNDERSTAND_GRAPH_PARSE_ERROR', `Knowledge graph at ${summary.path} is not valid JSON: ${summary.parseError}`, summary, ['Re-run `/understand` to regenerate the knowledge graph']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('understand.show', summary), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('understand.show', 'UNDERSTAND_SHOW_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .understand-anything directory before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -11,20 +11,21 @@ import { getLocalArtifactPath } from '../../services/artifacts/workspace-service
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, isRecommendationWorkflow, printResult } from '../cli-helpers.js';
 function getCurrentWorkspaceContext() {
-    const workspace = ensureWorkspaceConfigForCurrentPath() ?? getCurrentWorkspaceConfig();
+    const workspace = getCurrentWorkspaceConfig();
     if (!workspace)
         return {};
     return { workspace, artifactWorkspacePath: getLocalArtifactPath(workspace) };
 }
 function getWorkflowWorkspaceContext() {
-    const workspace = ensureWorkspaceConfigForCurrentPath() ?? getCurrentWorkspaceConfig();
-    if (!workspace)
+    try {
+        const workspace = ensureWorkspaceConfigForCurrentPath() ?? getCurrentWorkspaceConfig();
+        if (!workspace)
+            return {};
+        return { workspace, artifactWorkspacePath: getLocalArtifactPath(workspace) };
+    }
+    catch {
         return {};
-    return { workspace, artifactWorkspacePath: getLocalArtifactPath(workspace) };
-}
-function failWorkflowWorkspaceContext(io, command, error, asJson) {
-    printResult(io, fail(command, 'WORKSPACE_CONTEXT_FAILED', getErrorMessage(error), {}, ['Run peaks config workspace ensure --path <project> --json and resolve the reported workspace issue']), asJson);
-    process.exitCode = 1;
+    }
 }
 function parseMaxWorkers(io, command, value, asJson) {
     const maxWorkers = Number(value);
@@ -64,39 +65,24 @@ function runTechPlan(io, options) {
     }
     try {
         validatePlanningInput(options.changeId, options.goal);
+        const workspaceContext = getCurrentWorkspaceContext();
+        const plan = createTechPlan({
+            changeId: options.changeId,
+            goal: options.goal,
+            swarm: options.swarm ?? false,
+            dryRun: true,
+            ...workspaceContext
+        });
+        printResult(io, ok('tech.plan', plan), options.json);
     }
     catch (error) {
         printResult(io, fail('tech.plan', 'INVALID_CHANGE_ID_OR_GOAL', getErrorMessage(error), {}, ['Use a safe change id and a non-empty goal']), options.json);
         process.exitCode = 1;
-        return;
-    }
-    let workspaceContext;
-    try {
-        workspaceContext = getCurrentWorkspaceContext();
-    }
-    catch (error) {
-        failWorkflowWorkspaceContext(io, 'tech.plan', error, options.json);
-        return;
     }
-    const plan = createTechPlan({
-        changeId: options.changeId,
-        goal: options.goal,
-        swarm: options.swarm ?? false,
-        dryRun: true,
-        ...workspaceContext
-    });
-    printResult(io, ok('tech.plan', plan), options.json);
 }
 function runTechStatus(io, options) {
-    let workspaceContext;
-    try {
-        workspaceContext = getCurrentWorkspaceContext();
-    }
-    catch (error) {
-        failWorkflowWorkspaceContext(io, 'tech.status', error, options.json);
-        return;
-    }
     try {
+        const workspaceContext = getCurrentWorkspaceContext();
         printResult(io, ok('tech.status', getTechStatus({ changeId: options.changeId, ...workspaceContext })), options.json);
     }
     catch (error) {
@@ -122,31 +108,23 @@ function runWorkflowRoute(io, options) {
         return;
     try {
         validatePlanningInput(options.changeId, options.goal);
+        const workspaceContext = getWorkflowWorkspaceContext();
+        const plan = createWorkflowRouterPlan({
+            changeId: options.changeId,
+            goal: options.goal,
+            mode: options.mode,
+            ...(soloMode ? { soloMode } : {}),
+            maxWorkers,
+            dryRun: true,
+            config: readConfig(),
+            ...workspaceContext
+        });
+        printResult(io, ok('workflow.route', plan), options.json);
     }
     catch (error) {
         printResult(io, fail('workflow.route', 'INVALID_CHANGE_ID_OR_GOAL', getErrorMessage(error), {}, ['Use a safe change id and a non-empty goal']), options.json);
         process.exitCode = 1;
-        return;
     }
-    let workspaceContext;
-    try {
-        workspaceContext = getWorkflowWorkspaceContext();
-    }
-    catch (error) {
-        failWorkflowWorkspaceContext(io, 'workflow.route', error, options.json);
-        return;
-    }
-    const plan = createWorkflowRouterPlan({
-        changeId: options.changeId,
-        goal: options.goal,
-        mode: options.mode,
-        ...(soloMode ? { soloMode } : {}),
-        maxWorkers,
-        dryRun: true,
-        config: readConfig(),
-        ...workspaceContext
-    });
-    printResult(io, ok('workflow.route', plan), options.json);
 }
 function runAutonomousWorkflow(io, options) {
     if (options.dryRun === false) {
@@ -166,31 +144,23 @@ function runAutonomousWorkflow(io, options) {
         return;
     try {
         validatePlanningInput(options.changeId, options.goal);
+        const workspaceContext = getWorkflowWorkspaceContext();
+        const plan = createAutonomousWorkflowPlan({
+            changeId: options.changeId,
+            goal: options.goal,
+            mode: options.mode,
+            ...(soloMode ? { soloMode } : {}),
+            maxWorkers,
+            dryRun: true,
+            config: readConfig(),
+            ...workspaceContext
+        });
+        printResult(io, ok('workflow.autonomous', plan), options.json);
     }
     catch (error) {
         printResult(io, fail('workflow.autonomous', 'INVALID_CHANGE_ID_OR_GOAL', getErrorMessage(error), {}, ['Use a safe change id and a non-empty goal']), options.json);
         process.exitCode = 1;
-        return;
-    }
-    let workspaceContext;
-    try {
-        workspaceContext = getWorkflowWorkspaceContext();
     }
-    catch (error) {
-        failWorkflowWorkspaceContext(io, 'workflow.autonomous', error, options.json);
-        return;
-    }
-    const plan = createAutonomousWorkflowPlan({
-        changeId: options.changeId,
-        goal: options.goal,
-        mode: options.mode,
-        ...(soloMode ? { soloMode } : {}),
-        maxWorkers,
-        dryRun: true,
-        config: readConfig(),
-        ...workspaceContext
-    });
-    printResult(io, ok('workflow.autonomous', plan), options.json);
 }
 function runSwarmPlan(io, options) {
     if ((options.skill ?? 'rd') !== 'rd') {
@@ -207,32 +177,24 @@ function runSwarmPlan(io, options) {
         return;
     try {
         validatePlanningInput(options.changeId, options.goal);
+        const workspaceContext = getWorkflowWorkspaceContext();
+        const config = readConfig();
+        const plan = createRdSwarmPlan({
+            skill: 'rd',
+            changeId: options.changeId,
+            goal: options.goal,
+            maxWorkers,
+            dryRun: true,
+            swarmMode: config.swarmMode,
+            executionModelId: getEconomyAwareExecutionModelId(config),
+            ...workspaceContext
+        });
+        printResult(io, ok('swarm.plan', plan), options.json);
     }
     catch (error) {
         printResult(io, fail('swarm.plan', 'INVALID_CHANGE_ID_OR_GOAL', getErrorMessage(error), {}, ['Use a safe change id and a non-empty goal']), options.json);
         process.exitCode = 1;
-        return;
-    }
-    let workspaceContext;
-    try {
-        workspaceContext = getWorkflowWorkspaceContext();
     }
-    catch (error) {
-        failWorkflowWorkspaceContext(io, 'swarm.plan', error, options.json);
-        return;
-    }
-    const config = readConfig();
-    const plan = createRdSwarmPlan({
-        skill: 'rd',
-        changeId: options.changeId,
-        goal: options.goal,
-        maxWorkers,
-        dryRun: true,
-        swarmMode: config.swarmMode,
-        executionModelId: getEconomyAwareExecutionModelId(config),
-        ...workspaceContext
-    });
-    printResult(io, ok('swarm.plan', plan), options.json);
 }
 function addTechPlanOptions(command) {
     return addJsonOption(command

package/dist/src/cli/program.js

@@ -4,7 +4,12 @@ import { registerCoreAndArtifactCommands } from './commands/core-artifact-comman
 import { registerWorkflowCommands } from './commands/workflow-commands.js';
 import { registerCapabilityWorkerConfigAndSCCommands } from './commands/capability-worker-config-sc-commands.js';
 import { registerCodegraphCommands } from './commands/codegraph-commands.js';
+import { registerMcpCommands } from './commands/mcp-commands.js';
+import { registerOpenSpecCommands } from './commands/openspec-commands.js';
+import { registerProjectCommands } from './commands/project-commands.js';
+import { registerRequestCommands } from './commands/request-commands.js';
 import { registerShadcnCommands } from './commands/shadcn-commands.js';
+import { registerUnderstandCommands } from './commands/understand-commands.js';
 export { printResult } from './cli-helpers.js';
 export function createProgram(io = { stdout: (text) => console.log(text), stderr: (text) => console.error(text) }) {
     const program = new Command();
@@ -27,6 +32,11 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
     registerWorkflowCommands(program, io);
     registerCapabilityWorkerConfigAndSCCommands(program, io);
     registerCodegraphCommands(program, io);
+    registerMcpCommands(program, io);
+    registerOpenSpecCommands(program, io);
+    registerProjectCommands(program, io);
+    registerRequestCommands(program, io);
     registerShadcnCommands(program, io);
+    registerUnderstandCommands(program, io);
     return program;
 }

package/dist/src/services/artifacts/request-artifact-service.d.ts

@@ -0,0 +1,58 @@
+export type RequestArtifactRole = 'prd' | 'ui' | 'rd' | 'qa';
+export type CreateRequestArtifactOptions = {
+    role: RequestArtifactRole;
+    requestId: string;
+    projectRoot: string;
+    sessionId?: string;
+    apply?: boolean;
+    clock?: () => string;
+};
+export type CreateRequestArtifactResult = {
+    role: RequestArtifactRole;
+    requestId: string;
+    sessionId: string;
+    path: string;
+    content: string;
+    applied: boolean;
+};
+export declare function createRequestArtifact(options: CreateRequestArtifactOptions): Promise<CreateRequestArtifactResult>;
+export type RequestArtifactSummary = {
+    role: RequestArtifactRole;
+    sessionId: string;
+    requestId: string;
+    path: string;
+    state: string;
+    createdAt?: string;
+};
+export type ListRequestArtifactsOptions = {
+    projectRoot: string;
+    sessionId?: string;
+    role?: RequestArtifactRole;
+};
+export type ShowRequestArtifactOptions = {
+    projectRoot: string;
+    role: RequestArtifactRole;
+    requestId: string;
+    sessionId?: string;
+};
+export type ShowRequestArtifactResult = RequestArtifactSummary & {
+    content: string;
+};
+export declare function listRequestArtifacts(options: ListRequestArtifactsOptions): Promise<RequestArtifactSummary[]>;
+export declare function showRequestArtifact(options: ShowRequestArtifactOptions): Promise<ShowRequestArtifactResult | null>;
+export type RequestArtifactState = 'draft' | 'confirmed-by-user' | 'direction-locked' | 'spec-locked' | 'implemented' | 'qa-handoff' | 'running' | 'verdict-issued' | 'handed-off' | 'blocked';
+export declare function allowedStatesForRole(role: RequestArtifactRole): ReadonlyArray<RequestArtifactState>;
+export type TransitionRequestArtifactOptions = {
+    role: RequestArtifactRole;
+    requestId: string;
+    projectRoot: string;
+    newState: RequestArtifactState;
+    sessionId?: string;
+    reason?: string;
+    clock?: () => string;
+};
+export type TransitionRequestArtifactResult = RequestArtifactSummary & {
+    previousState: string;
+    content: string;
+};
+export declare function transitionRequestArtifact(options: TransitionRequestArtifactOptions): Promise<TransitionRequestArtifactResult | null>;