spec-agent 2.0.2 → 2.0.4

package/src/commands/round.ts

@@ -0,0 +1,189 @@
+import * as path from 'path';
+import { Command } from 'commander';
+import { Logger } from '../utils/logger';
+import { writeJson } from '../utils/file';
+import { pipelineCommand } from './pipeline';
+import { handoffCommand } from './handoff';
+import { executeCommand } from './execute';
+import { buildOrchestratorContext } from './orchestrate';
+
+interface RoundOptions {
+  workspace: string;
+  input: string;
+  target: string;
+  maxParallel: string;
+  retry?: string;
+  complete?: string;
+  fail?: string;
+  error?: string;
+  dryRun?: boolean;
+}
+
+export async function roundCommand(options: RoundOptions, command: Command): Promise<void> {
+  const logger = new Logger();
+  try {
+    const workspaceArg = options.workspace || './output';
+    const inputArg = options.input || './docs';
+    const target = (options.target || 'cursor').toLowerCase();
+    const maxParallel = Math.max(1, parseInt(options.maxParallel || '4', 10) || 4);
+    const retry = String(Math.max(0, parseInt(options.retry || '1', 10) || 1));
+    const hasFeedback = Boolean((options.complete || '').trim() || (options.fail || '').trim());
+    const workspacePath = path.resolve(workspaceArg);
+    const contextPath = path.join(workspacePath, 'orchestrator_context.json');
+
+    const before = await buildOrchestratorContext({
+      workspaceArg,
+      inputArg,
+      target,
+      maxParallel,
+    });
+
+    let executedAction = 'none';
+    if (!options.dryRun) {
+      if (hasFeedback && before.checks.runState) {
+        executedAction = 'execute_feedback';
+        await executeCommand({
+          workspace: workspaceArg,
+          maxParallel: String(maxParallel),
+          retry,
+          complete: options.complete,
+          fail: options.fail,
+          error: options.error,
+          dryRun: false,
+        }, {} as Command);
+
+        const afterFeedback = await buildOrchestratorContext({
+          workspaceArg,
+          inputArg,
+          target,
+          maxParallel,
+        });
+
+        if (afterFeedback.metrics.pending > 0 && afterFeedback.metrics.running === 0) {
+          executedAction = 'execute_feedback_and_schedule';
+          await executeCommand({
+            workspace: workspaceArg,
+            maxParallel: String(maxParallel),
+            retry,
+            dryRun: false,
+          }, {} as Command);
+        }
+      } else if (!before.checks.dispatchPlan) {
+        executedAction = 'pipeline';
+        await pipelineCommand({
+          input: inputArg,
+          output: workspaceArg,
+          agents: 'auto',
+          chunkSize: '200kb',
+          minChunkSize: '10kb',
+          analyzeRetries: '1',
+          analyzeBudgetTokens: '0',
+          framework: 'vue3',
+          dryRun: false,
+        }, {} as Command);
+      } else if (!before.checks.handoffBundle) {
+        executedAction = 'handoff';
+        await handoffCommand({
+          workspace: workspaceArg,
+          output: 'handoff',
+          target,
+          includeSummaries: true,
+          dryRun: false,
+        }, {} as Command);
+      } else if (!before.checks.runState || (before.metrics.pending > 0 && before.metrics.running === 0)) {
+        executedAction = 'execute';
+        await executeCommand({
+          workspace: workspaceArg,
+          maxParallel: String(maxParallel),
+          retry,
+          dryRun: false,
+        }, {} as Command);
+      } else {
+        executedAction = 'wait_feedback';
+      }
+    }
+
+    const after = await buildOrchestratorContext({
+      workspaceArg,
+      inputArg,
+      target,
+      maxParallel,
+    });
+
+    if (!options.dryRun) {
+      await writeJson(contextPath, after);
+    }
+
+    logger.info(`Round action: ${executedAction}`);
+    logger.info(`State: ${after.state}`);
+    logger.info(`Next action: ${after.nextAction}`);
+    logger.info(
+      `Metrics: pending=${after.metrics.pending}, running=${after.metrics.running}, succeeded=${after.metrics.succeeded}, failed=${after.metrics.failed}, blocked=${after.metrics.blocked}`
+    );
+    logger.info('Recommended commands:');
+    for (const cmdLine of after.recommendedCommands) {
+      logger.info(`  ${cmdLine}`);
+    }
+    if (options.dryRun) {
+      logger.warn('Dry run mode - no command execution performed');
+    }
+    logger.json({
+      status: 'success',
+      executedAction,
+      state: after.state,
+      nextAction: after.nextAction,
+      metrics: after.metrics,
+      contextPath,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(`Round failed: ${message}`);
+    const recovery = inferRecoveryCommands(message, options);
+    if (recovery.length > 0) {
+      logger.info('Suggested recovery commands:');
+      for (const item of recovery) {
+        logger.info(`  ${item}`);
+      }
+    }
+    process.exit(1);
+  }
+}
+
+function inferRecoveryCommands(message: string, options: RoundOptions): string[] {
+  const workspaceArg = options.workspace || './output';
+  const inputArg = options.input || './docs';
+  const lower = message.toLowerCase();
+
+  if (lower.includes('not recognized') || lower.includes('command not found')) {
+    return [
+      'npm install -g spec-agent --registry=https://registry.npmjs.org/',
+      'spec-agent --version',
+    ];
+  }
+
+  if (lower.includes('eneedauth') || lower.includes('e403') || lower.includes('2fa')) {
+    return [
+      'npm login --registry=https://registry.npmjs.org/',
+      'npm profile get "two-factor auth" --registry=https://registry.npmjs.org/',
+    ];
+  }
+
+  if (lower.includes('api key') || lower.includes('llm') || lower.includes('configuration')) {
+    return [
+      `spec-agent doctor --workspace ${workspaceArg} --check-llm`,
+      '# set LLM_API_KEY / LLM_BASE_URL / LLM_MODEL then retry',
+    ];
+  }
+
+  if (lower.includes('manifest not found') || lower.includes('task plan not found') || lower.includes('dispatch_plan')) {
+    return [
+      `spec-agent pipeline --input ${inputArg} --output ${workspaceArg}`,
+      `spec-agent handoff --workspace ${workspaceArg} --target cursor --include-summaries`,
+    ];
+  }
+
+  return [
+    `spec-agent orchestrate --workspace ${workspaceArg} --input ${inputArg}`,
+    `spec-agent round --workspace ${workspaceArg} --input ${inputArg} --target ${(options.target || 'cursor')}`,
+  ];
+}

package/src/index.ts

@@ -14,6 +14,8 @@ import { cleanCommand } from './commands/clean';
 import { doctorCommand } from './commands/doctor';
 import { handoffCommand } from './commands/handoff';
 import { executeCommand } from './commands/execute';
+import { orchestrateCommand } from './commands/orchestrate';
+import { roundCommand } from './commands/round';
 
 const program = new Command();
 const pkgVersion = (() => {
@@ -173,4 +175,29 @@ program
   .option('--dry-run', 'Preview execution transitions without writing state')
   .action(executeCommand);
 
+program
+  .command('orchestrate')
+  .description('Generate orchestrator context and next-step decisions from artifacts')
+  .option('-w, --workspace <dir>', 'Workspace directory', './output')
+  .option('-i, --input <path>', 'Input docs path used for pipeline', './docs')
+  .option('-t, --target <name>', 'Execution target: cursor, qcoder, codebuddy, generic', 'cursor')
+  .option('-p, --max-parallel <count>', 'Max parallel tasks for execute suggestion', '4')
+  .option('--format <format>', 'Output format: text, json', 'text')
+  .option('--dry-run', 'Preview decisions without writing orchestrator_context.json')
+  .action(orchestrateCommand);
+
+program
+  .command('round')
+  .description('Run one orchestrated round (pipeline/handoff/execute decision)')
+  .option('-w, --workspace <dir>', 'Workspace directory', './output')
+  .option('-i, --input <path>', 'Input docs path used for pipeline', './docs')
+  .option('-t, --target <name>', 'Execution target: cursor, qcoder, codebuddy, generic', 'cursor')
+  .option('-p, --max-parallel <count>', 'Max parallel tasks for execute', '4')
+  .option('-r, --retry <count>', 'Retry times per task after failure', '1')
+  .option('--complete <ids>', 'Mark task IDs as completed, comma-separated')
+  .option('--fail <ids>', 'Mark task IDs as failed, comma-separated')
+  .option('--error <message>', 'Failure reason when using --fail')
+  .option('--dry-run', 'Preview one-round decision without running commands')
+  .action(roundCommand);
+
 program.parse();

package/src/services/llm.ts

@@ -28,8 +28,8 @@ export interface ImageUnderstandingInput {
 
 export function getLLMConfig(): LLMConfig {
   return {
-    apiKey: process.env.OPENAI_API_KEY || process.env.LLM_API_KEY || '',
-    baseUrl: process.env.OPENAI_BASE_URL || process.env.LLM_BASE_URL || 'https://api.openai.com/v1',
+    apiKey: process.env.LLM_API_KEY || process.env.OPENAI_API_KEY || '',
+    baseUrl: process.env.LLM_BASE_URL || process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1',
     model: process.env.LLM_MODEL || 'gpt-4o-mini',
     maxTokens: parseInt(process.env.LLM_MAX_TOKENS || '4000', 10),
     temperature: parseFloat(process.env.LLM_TEMPERATURE || '0.3'),
@@ -54,7 +54,7 @@ export function getLLMConfigForPurpose(purpose: 'scan' | 'analyze' | 'vision' |
 export function validateLLMConfig(config: LLMConfig): void {
   if (!config.apiKey) {
     throw new Error(
-      'LLM API key not found. Please set one of:\n  - OPENAI_API_KEY\n  - LLM_API_KEY'
+      'LLM API key not found. Please set one of:\n  - LLM_API_KEY (recommended)\n  - OPENAI_API_KEY (compatibility alias)'
     );
   }
 }