scene-capability-engine 3.0.0

package/lib/commands/spec-bootstrap.js

@@ -0,0 +1,147 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { runOrchestration } = require('./orchestrate');
+const {
+  parseSpecTargets,
+  runMultiSpecViaOrchestrate
+} = require('../spec/multi-spec-orchestrate');
+
+const { ContextCollector } = require('../spec/bootstrap/context-collector');
+const { QuestionnaireEngine } = require('../spec/bootstrap/questionnaire-engine');
+const { DraftGenerator } = require('../spec/bootstrap/draft-generator');
+const { TraceEmitter } = require('../spec/bootstrap/trace-emitter');
+
+async function runSpecBootstrap(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+
+  const specTargets = parseSpecTargets({
+    spec: options.spec || options.name,
+    specs: options.specs
+  });
+
+  if (specTargets.length > 1) {
+    const executeOrchestration = dependencies.runOrchestration || runOrchestration;
+    return runMultiSpecViaOrchestrate({
+      specTargets,
+      projectPath,
+      commandOptions: options,
+      runOrchestration: executeOrchestration,
+      commandLabel: 'Multi-spec bootstrap',
+      nextActionLabel: 'Multi-spec bootstrap defaulted to orchestrate mode.'
+    });
+  }
+
+  const contextCollector = dependencies.contextCollector || new ContextCollector(projectPath);
+  const questionnaireEngine = dependencies.questionnaireEngine || new QuestionnaireEngine({
+    prompt: dependencies.prompt,
+    maxQuestions: dependencies.maxQuestions
+  });
+  const draftGenerator = dependencies.draftGenerator || new DraftGenerator();
+  const traceEmitter = dependencies.traceEmitter || new TraceEmitter();
+
+  if (options.nonInteractive && specTargets.length === 0) {
+    throw new Error('--name is required in non-interactive mode');
+  }
+
+  const context = await contextCollector.collect();
+  const answers = await questionnaireEngine.collect({
+    nonInteractive: options.nonInteractive,
+    specName: specTargets[0] || options.name,
+    profile: options.profile,
+    template: options.template
+  });
+
+  const specName = (specTargets[0] || options.name || answers.specName || '').trim();
+  if (!specName) {
+    throw new Error('Spec name is required');
+  }
+
+  const draft = draftGenerator.generate({
+    specName,
+    profile: options.profile || 'general',
+    template: options.template || 'default',
+    context,
+    answers
+  });
+
+  const specPath = path.join(projectPath, '.kiro', 'specs', specName);
+  const files = {
+    requirements: path.join(specPath, 'requirements.md'),
+    design: path.join(specPath, 'design.md'),
+    tasks: path.join(specPath, 'tasks.md')
+  };
+
+  if (!options.dryRun) {
+    await fs.ensureDir(specPath);
+    await fs.writeFile(files.requirements, draft.requirements, 'utf8');
+    await fs.writeFile(files.design, draft.design, 'utf8');
+    await fs.writeFile(files.tasks, draft.tasks, 'utf8');
+  }
+
+  const result = {
+    success: true,
+    specName,
+    specPath: path.relative(projectPath, specPath),
+    dryRun: !!options.dryRun,
+    files: {
+      requirements: path.relative(projectPath, files.requirements),
+      design: path.relative(projectPath, files.design),
+      tasks: path.relative(projectPath, files.tasks)
+    },
+    trace: {
+      template: options.template || 'default',
+      profile: options.profile || 'general',
+      parameters: {
+        nonInteractive: !!options.nonInteractive,
+        dryRun: !!options.dryRun,
+        json: !!options.json
+      },
+      context: {
+        totalSpecs: context.totalSpecs,
+        preferredLanguage: context.preferredLanguage
+      },
+      mapping: draft.metadata.mapping
+    },
+    preview: {
+      requirements: draft.requirements,
+      design: draft.design,
+      tasks: draft.tasks
+    }
+  };
+
+  traceEmitter.emit(result, { json: options.json });
+  return result;
+}
+
+function registerSpecBootstrapCommand(program) {
+  program
+    .command('spec-bootstrap')
+    .description('Bootstrap requirements/design/tasks draft (use: kse spec bootstrap)')
+    .option('--name <spec-name>', 'Spec name to generate')
+    .option('--spec <name>', 'Alias of --name')
+    .option('--specs <names>', 'Comma-separated Spec identifiers (multi-spec defaults to orchestrate mode)')
+    .option('--template <template-id>', 'Template hint for draft generation')
+    .option('--profile <profile-id>', 'Profile for default generation strategy')
+    .option('--non-interactive', 'Disable prompts and use arguments/defaults only')
+    .option('--dry-run', 'Preview generation result without writing files')
+    .option('--json', 'Output machine-readable JSON')
+    .option('--max-parallel <n>', 'Maximum parallel agents when orchestrate mode is used', parseInt)
+    .action(async (options) => {
+      try {
+        await runSpecBootstrap(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ Spec bootstrap failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  registerSpecBootstrapCommand,
+  runSpecBootstrap
+};

package/lib/commands/spec-gate.js

@@ -0,0 +1,157 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { runOrchestration } = require('./orchestrate');
+const {
+  parseSpecTargets,
+  runMultiSpecViaOrchestrate
+} = require('../spec/multi-spec-orchestrate');
+
+const { PolicyLoader } = require('../spec-gate/policy/policy-loader');
+const { RuleRegistry } = require('../spec-gate/rules/rule-registry');
+const { createDefaultRules } = require('../spec-gate/rules/default-rules');
+const { GateEngine } = require('../spec-gate/engine/gate-engine');
+const { ResultEmitter } = require('../spec-gate/result-emitter');
+
+async function runSpecGate(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const specTargets = parseSpecTargets(options);
+
+  if (specTargets.length === 0) {
+    throw new Error('Either --spec or --specs is required');
+  }
+
+  if (specTargets.length > 1) {
+    const executeOrchestration = dependencies.runOrchestration || runOrchestration;
+    return runMultiSpecViaOrchestrate({
+      specTargets,
+      projectPath,
+      commandOptions: options,
+      runOrchestration: executeOrchestration,
+      commandLabel: 'Multi-spec gate',
+      nextActionLabel: 'Multi-spec gate execution defaulted to orchestrate mode.'
+    });
+  }
+
+  const specId = specTargets[0];
+
+  const specPath = path.join(projectPath, '.kiro', 'specs', specId);
+  if (!await fs.pathExists(specPath)) {
+    throw new Error(`Spec not found: ${specId}`);
+  }
+
+  const policyLoader = dependencies.policyLoader || new PolicyLoader(projectPath);
+  const policy = dependencies.policy || await policyLoader.load({
+    policy: options.policy,
+    strict: options.strict
+  });
+
+  const registry = dependencies.registry || new RuleRegistry(createDefaultRules(projectPath));
+  const engine = dependencies.engine || new GateEngine({
+    registry,
+    policy
+  });
+
+  const result = await engine.evaluate({ specId });
+  const emitter = dependencies.emitter || new ResultEmitter(projectPath);
+  const emitted = await emitter.emit(result, {
+    json: options.json,
+    out: options.out,
+    silent: options.silent
+  });
+
+  return {
+    ...result,
+    report_path: emitted.outputPath
+  };
+}
+
+async function generateSpecGatePolicyTemplate(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const loader = dependencies.policyLoader || new PolicyLoader(projectPath);
+  const template = loader.getTemplate();
+
+  const outputPath = options.out
+    ? (path.isAbsolute(options.out) ? options.out : path.join(projectPath, options.out))
+    : path.join(projectPath, '.kiro', 'config', 'spec-gate-policy.template.json');
+
+  await fs.ensureDir(path.dirname(outputPath));
+  await fs.writeJson(outputPath, template, { spaces: 2 });
+
+  if (!options.silent) {
+    console.log(chalk.green('✅ Spec gate policy template generated:'));
+    console.log(`  ${outputPath}`);
+  }
+
+  return {
+    success: true,
+    outputPath
+  };
+}
+
+function registerSpecGateCommand(program) {
+  const specGate = program
+    .command('spec-gate')
+    .description('Run standardized Spec gate checks (use: kse spec gate)');
+
+  specGate
+    .command('run')
+    .description('Execute gate checks for one or more Specs')
+    .option('--spec <name>', 'Single Spec identifier')
+    .option('--specs <names>', 'Comma-separated Spec identifiers (multi-spec defaults to orchestrate mode)')
+    .option('--policy <path>', 'Policy JSON path')
+    .option('--strict', 'Enable strict mode override')
+    .option('--json', 'Output machine-readable JSON')
+    .option('--out <path>', 'Write JSON result to file')
+    .option('--max-parallel <n>', 'Maximum parallel agents when orchestrate mode is used', parseInt)
+    .action(async options => {
+      try {
+        await runSpecGate(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ Spec gate failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+
+  specGate
+    .command('policy-template')
+    .description('Generate policy template JSON for Spec gate')
+    .option('--out <path>', 'Template output path')
+    .action(async options => {
+      try {
+        await generateSpecGatePolicyTemplate(options);
+      } catch (error) {
+        console.error(chalk.red('❌ Failed to generate policy template:'), error.message);
+        process.exit(1);
+      }
+    });
+}
+
+async function _runGateInOrchestrateMode(specTargets, options, dependencies) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const executeOrchestration = dependencies.runOrchestration || runOrchestration;
+
+  return runMultiSpecViaOrchestrate({
+    specTargets,
+    projectPath,
+    commandOptions: options,
+    runOrchestration: executeOrchestration,
+    commandLabel: 'Multi-spec gate',
+    nextActionLabel: 'Multi-spec gate execution defaulted to orchestrate mode.'
+  });
+}
+
+function _parseSpecTargets(options = {}) {
+  return parseSpecTargets(options);
+}
+
+module.exports = {
+  registerSpecGateCommand,
+  runSpecGate,
+  generateSpecGatePolicyTemplate,
+  _parseSpecTargets
+};

package/lib/commands/spec-pipeline.js

@@ -0,0 +1,205 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { runOrchestration } = require('./orchestrate');
+const {
+  parseSpecTargets,
+  runMultiSpecViaOrchestrate
+} = require('../spec/multi-spec-orchestrate');
+
+const { PipelineStateStore } = require('../spec/pipeline/state-store');
+const { StageRunner } = require('../spec/pipeline/stage-runner');
+const { createDefaultStageAdapters } = require('../spec/pipeline/stage-adapters');
+
+async function runSpecPipeline(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const specTargets = parseSpecTargets(options);
+  if (specTargets.length === 0) {
+    throw new Error('Either --spec or --specs is required');
+  }
+
+  if (specTargets.length > 1) {
+    const executeOrchestration = dependencies.runOrchestration || runOrchestration;
+    return runMultiSpecViaOrchestrate({
+      specTargets,
+      projectPath,
+      commandOptions: options,
+      runOrchestration: executeOrchestration,
+      commandLabel: 'Multi-spec pipeline',
+      nextActionLabel: 'Multi-spec execution defaulted to orchestrate mode.'
+    });
+  }
+
+  const specId = specTargets[0];
+
+  const specPath = path.join(projectPath, '.kiro', 'specs', specId);
+  if (!await fs.pathExists(specPath)) {
+    throw new Error(`Spec not found: ${specId}`);
+  }
+
+  const stateStore = dependencies.stateStore || new PipelineStateStore(projectPath);
+  const adapters = dependencies.adapters || createDefaultStageAdapters(projectPath);
+  const stageRunner = dependencies.stageRunner || new StageRunner({
+    stateStore,
+    adapters
+  });
+
+  let state;
+  if (options.resume) {
+    state = await stateStore.loadLatest(specId);
+  }
+
+  if (!state) {
+    state = await stateStore.create(specId, {
+      failFast: options.failFast !== false,
+      continueOnWarning: !!options.continueOnWarning
+    });
+  }
+
+  const runContext = {
+    specId,
+    runId: state.run_id,
+    fromStage: options.fromStage,
+    toStage: options.toStage,
+    dryRun: !!options.dryRun,
+    resume: !!options.resume,
+    failFast: options.failFast !== false,
+    continueOnWarning: !!options.continueOnWarning,
+    strict: !!options.strict,
+    gateOut: options.gateOut,
+    state
+  };
+
+  const execution = await stageRunner.run(runContext);
+  await stateStore.markFinished(state, execution.status);
+
+  const result = {
+    spec_id: specId,
+    run_id: state.run_id,
+    status: execution.status,
+    stage_results: execution.stageResults,
+    failure: execution.failure,
+    next_actions: buildNextActions(execution),
+    state_file: path.relative(projectPath, stateStore.getRunPath(specId, state.run_id))
+  };
+
+  if (options.out) {
+    const outPath = path.isAbsolute(options.out)
+      ? options.out
+      : path.join(projectPath, options.out);
+    await fs.ensureDir(path.dirname(outPath));
+    await fs.writeJson(outPath, result, { spaces: 2 });
+    result.output_file = outPath;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printResult(result);
+  }
+
+  return result;
+}
+
+function registerSpecPipelineCommand(program) {
+  const pipeline = program
+    .command('spec-pipeline')
+    .description('Run Spec workflow pipeline (use: kse spec pipeline run)');
+
+  pipeline
+    .command('run')
+    .description('Execute pipeline stages for one or more Specs')
+    .option('--spec <name>', 'Single Spec identifier')
+    .option('--specs <names>', 'Comma-separated Spec identifiers (multi-spec defaults to orchestrate mode)')
+    .option('--from-stage <stage>', 'Start stage (requirements/design/tasks/gate)')
+    .option('--to-stage <stage>', 'End stage (requirements/design/tasks/gate)')
+    .option('--resume', 'Resume from latest unfinished stage state')
+    .option('--dry-run', 'Preview pipeline execution without writing stage outputs')
+    .option('--json', 'Output machine-readable JSON')
+    .option('--out <path>', 'Write pipeline result JSON to file')
+    .option('--max-parallel <n>', 'Maximum parallel agents when orchestrate mode is used', parseInt)
+    .option('--continue-on-warning', 'Continue when stage returns warnings')
+    .option('--no-fail-fast', 'Do not stop immediately on failed stage')
+    .option('--strict', 'Enable strict mode for downstream gate stage')
+    .option('--gate-out <path>', 'Output path for nested gate stage report')
+    .action(async options => {
+      try {
+        await runSpecPipeline(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ Spec pipeline failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+}
+
+function printResult(result) {
+  const statusColor = result.status === 'completed' ? chalk.green : chalk.red;
+
+  console.log(chalk.red('🔥') + ' Spec Workflow Pipeline');
+  console.log();
+  console.log(`${chalk.gray('Spec:')} ${result.spec_id}`);
+  console.log(`${chalk.gray('Run:')} ${result.run_id}`);
+  console.log(`${chalk.gray('Status:')} ${statusColor(result.status)}`);
+  console.log();
+
+  console.log(chalk.bold('Stage Results'));
+  result.stage_results.forEach(stage => {
+    const icon = stage.status === 'completed'
+      ? chalk.green('✓')
+      : stage.status === 'warning'
+        ? chalk.yellow('!')
+        : stage.status === 'skipped'
+          ? chalk.gray('→')
+          : chalk.red('✗');
+    console.log(`  ${icon} ${stage.name}: ${stage.status}`);
+  });
+
+  if (result.next_actions.length > 0) {
+    console.log();
+    console.log(chalk.bold('Next Actions'));
+    result.next_actions.forEach(action => console.log(`  - ${action}`));
+  }
+}
+
+function buildNextActions(execution) {
+  if (execution.status === 'completed') {
+    return ['Review pipeline output and continue implementation on completed Spec stages.'];
+  }
+
+  if (execution.failure && execution.failure.stage) {
+    return [
+      `Resolve failure at stage: ${execution.failure.stage}`,
+      'Use --resume to continue from the last unfinished stage after remediation.'
+    ];
+  }
+
+  return ['Inspect stage_results for failure details and re-run pipeline.'];
+}
+
+async function _runPipelineInOrchestrateMode(specTargets, options, dependencies) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const executeOrchestration = dependencies.runOrchestration || runOrchestration;
+
+  return runMultiSpecViaOrchestrate({
+    specTargets,
+    projectPath,
+    commandOptions: options,
+    runOrchestration: executeOrchestration,
+    commandLabel: 'Multi-spec pipeline',
+    nextActionLabel: 'Multi-spec execution defaulted to orchestrate mode.'
+  });
+}
+
+function _parseSpecTargets(options = {}) {
+  return parseSpecTargets(options);
+}
+
+module.exports = {
+  registerSpecPipelineCommand,
+  runSpecPipeline,
+  _parseSpecTargets
+};