orchestr8 2.8.0 → 3.1.0

package/src/interactive.js

@@ -0,0 +1,338 @@
+const fs = require('fs');
+const path = require('path');
+
+const SESSION_STATES = {
+  IDLE: 'idle',
+  GATHERING: 'gathering',
+  QUESTIONING: 'questioning',
+  DRAFTING: 'drafting',
+  FINALIZING: 'finalizing'
+};
+
+const SECTION_ORDER = ['intent', 'scope', 'actors', 'behaviour', 'dependencies'];
+
+const MIN_REQUIRED_SECTIONS = ['intent', 'scope', 'actors'];
+
+const SYSTEM_SPEC_QUESTIONS = ['purpose', 'actors', 'boundaries', 'rules'];
+
+function parseFlags(args) {
+  return {
+    interactive: args.includes('--interactive'),
+    pauseAfter: args.find(a => a.startsWith('--pause-after='))?.split('=')[1] || null
+  };
+}
+
+function shouldEnterInteractiveMode(flags, hasSystemSpec, hasFeatureSpec) {
+  if (flags.interactive) return { interactive: true, target: 'feature' };
+  if (!hasSystemSpec) return { interactive: true, target: 'system' };
+  if (!hasFeatureSpec) return { interactive: true, target: 'feature' };
+  return { interactive: false, target: null };
+}
+
+function createSession(target) {
+  const sections = target === 'system'
+    ? { purpose: null, actors: null, boundaries: null, rules: null }
+    : { intent: null, scope: null, actors: null, behaviour: null, dependencies: null };
+
+  return {
+    target,
+    state: SESSION_STATES.IDLE,
+    sections,
+    current: target === 'system' ? 'purpose' : 'intent',
+    revisionCount: 0,
+    questionCount: 0,
+    startedAt: new Date().toISOString(),
+    aborted: false,
+    specWritten: false,
+    context: {},
+    feedback: []
+  };
+}
+
+function getSessionProgress(session) {
+  const sectionList = Object.keys(session.sections);
+  const complete = Object.values(session.sections).filter(
+    s => s === 'complete' || s === 'TBD'
+  ).length;
+  const remaining = sectionList.length - complete;
+  return { complete, remaining, total: sectionList.length };
+}
+
+function handleCommand(session, command) {
+  const cmd = command.trim().toLowerCase();
+  const parts = command.trim().split(/\s+/);
+  const baseCmd = parts[0].toLowerCase();
+
+  if (baseCmd === '/approve' || baseCmd === 'yes') {
+    session.sections[session.current] = 'complete';
+    const nextSection = getNextSection(session);
+    if (nextSection) {
+      session.current = nextSection;
+      return { action: 'next', section: nextSection };
+    }
+    return { action: 'finalize' };
+  }
+
+  if (baseCmd === '/change') {
+    const feedback = parts.slice(1).join(' ');
+    session.revisionCount++;
+    session.feedback.push({ section: session.current, feedback });
+    return { action: 'revise', feedback };
+  }
+
+  if (baseCmd === '/skip') {
+    session.sections[session.current] = 'TBD';
+    const nextSection = getNextSection(session);
+    if (nextSection) {
+      session.current = nextSection;
+      return { action: 'next', section: nextSection };
+    }
+    return { action: 'finalize' };
+  }
+
+  if (baseCmd === '/restart') {
+    session.sections[session.current] = null;
+    return { action: 'restart', section: session.current };
+  }
+
+  if (baseCmd === '/abort') {
+    session.aborted = true;
+    return { action: 'abort' };
+  }
+
+  if (baseCmd === '/done') {
+    if (canFinalize(session)) {
+      return { action: 'finalize' };
+    }
+    return { action: 'incomplete', missing: getMissingSections(session) };
+  }
+
+  return { action: 'unknown', command: baseCmd };
+}
+
+function getNextSection(session) {
+  const order = session.target === 'system'
+    ? SYSTEM_SPEC_QUESTIONS
+    : SECTION_ORDER;
+
+  for (const section of order) {
+    const status = session.sections[section];
+    if (status !== 'complete' && status !== 'TBD') {
+      return section;
+    }
+  }
+  return null;
+}
+
+function markSectionComplete(session, section) {
+  if (section in session.sections) {
+    session.sections[section] = 'complete';
+    return true;
+  }
+  return false;
+}
+
+function markSectionTBD(session, section) {
+  if (section in session.sections) {
+    session.sections[section] = 'TBD';
+    return true;
+  }
+  return false;
+}
+
+function gatherContext(basePath = '.') {
+  const context = {
+    systemSpec: null,
+    businessContext: [],
+    templates: []
+  };
+
+  const systemSpecPath = path.join(basePath, '.blueprint/system_specification/SYSTEM_SPEC.md');
+  if (fs.existsSync(systemSpecPath)) {
+    context.systemSpec = fs.readFileSync(systemSpecPath, 'utf8');
+  }
+
+  const businessContextDir = path.join(basePath, '.business_context');
+  if (fs.existsSync(businessContextDir)) {
+    const files = fs.readdirSync(businessContextDir);
+    for (const file of files) {
+      if (file.endsWith('.md')) {
+        const content = fs.readFileSync(path.join(businessContextDir, file), 'utf8');
+        context.businessContext.push({ file, content });
+      }
+    }
+  }
+
+  const templatesDir = path.join(basePath, '.blueprint/templates');
+  if (fs.existsSync(templatesDir)) {
+    const files = fs.readdirSync(templatesDir);
+    for (const file of files) {
+      if (file.endsWith('.md')) {
+        const content = fs.readFileSync(path.join(templatesDir, file), 'utf8');
+        context.templates.push({ file, content });
+      }
+    }
+  }
+
+  return context;
+}
+
+function identifyGaps(session, userDescription) {
+  const gaps = [];
+  const sectionKeys = session.target === 'system'
+    ? SYSTEM_SPEC_QUESTIONS
+    : SECTION_ORDER;
+
+  for (const section of sectionKeys) {
+    const hasKey = `has${section.charAt(0).toUpperCase() + section.slice(1)}`;
+    if (!userDescription[hasKey]) {
+      gaps.push(section);
+    }
+  }
+
+  return gaps.slice(0, 4);
+}
+
+function generateQuestions(gaps) {
+  const questionTemplates = {
+    intent: 'What is the primary goal or purpose of this feature?',
+    scope: 'What boundaries define what is in scope vs out of scope?',
+    actors: 'Who are the users or systems that will interact with this?',
+    behaviour: 'What are the key behaviours or flows to support?',
+    dependencies: 'What does this depend on or what depends on it?',
+    purpose: 'What is the overall purpose of this system?',
+    boundaries: 'What are the system boundaries and integration points?',
+    rules: 'What business rules or constraints apply?'
+  };
+
+  return gaps.slice(0, 4).map(gap => ({
+    section: gap,
+    question: questionTemplates[gap] || `What information is needed for ${gap}?`
+  }));
+}
+
+function getMissingSections(session) {
+  const required = session.target === 'system'
+    ? ['purpose', 'actors', 'boundaries']
+    : MIN_REQUIRED_SECTIONS;
+
+  return required.filter(section => {
+    const status = session.sections[section];
+    return status !== 'complete' && status !== 'TBD';
+  });
+}
+
+function canFinalize(session) {
+  const required = session.target === 'system'
+    ? ['purpose', 'actors', 'boundaries']
+    : MIN_REQUIRED_SECTIONS;
+
+  return required.every(section => {
+    const status = session.sections[section];
+    return status === 'complete' || status === 'TBD';
+  });
+}
+
+function generateSpec(session) {
+  const sections = [];
+  const sectionOrder = session.target === 'system'
+    ? SYSTEM_SPEC_QUESTIONS
+    : SECTION_ORDER;
+
+  const title = session.target === 'system' ? 'System Spec' : 'Feature Spec';
+  sections.push(`# ${title}`);
+
+  for (const sectionName of sectionOrder) {
+    const status = session.sections[sectionName];
+    const heading = sectionName.charAt(0).toUpperCase() + sectionName.slice(1);
+    sections.push(`## ${heading}`);
+
+    if (status === 'TBD') {
+      sections.push('TBD');
+    } else if (status === 'complete') {
+      sections.push(`[Content for ${sectionName}]`);
+    } else {
+      sections.push('TBD');
+    }
+  }
+
+  sections.push('');
+  sections.push('_Created via interactive session_');
+
+  return sections.join('\n');
+}
+
+function writeSpec(session, outputPath) {
+  const content = generateSpec(session);
+  const dir = path.dirname(outputPath);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  fs.writeFileSync(outputPath, content);
+  session.specWritten = true;
+  return outputPath;
+}
+
+function generateHandoff(session, slug) {
+  const progress = getSessionProgress(session);
+  const endedAt = new Date().toISOString();
+  const startedAt = new Date(session.startedAt);
+  const durationMs = new Date(endedAt) - startedAt;
+
+  const lines = [
+    '## Handoff Summary',
+    '**For:** Cass',
+    `**Feature:** ${slug}`,
+    '',
+    '### Key Decisions',
+    `- Interactive mode used for ${session.target} spec creation`,
+    `- ${progress.complete}/${progress.total} sections completed`,
+    session.revisionCount > 0 ? `- ${session.revisionCount} revision(s) made` : null,
+    '',
+    '### Files Created',
+    session.target === 'system'
+      ? '- .blueprint/system_specification/SYSTEM_SPEC.md'
+      : `- .blueprint/features/feature_${slug}/FEATURE_SPEC.md`,
+    '',
+    '### Open Questions',
+    progress.remaining > 0 ? `- ${progress.remaining} section(s) marked TBD` : '- None',
+    '',
+    '### Critical Context',
+    `Session duration: ${Math.round(durationMs / 1000)}s, Questions asked: ${session.questionCount}, Revisions: ${session.revisionCount}`
+  ].filter(line => line !== null);
+
+  return lines.join('\n');
+}
+
+function getOutputPath(session, slug, basePath = '.') {
+  if (session.target === 'system') {
+    return path.join(basePath, '.blueprint/system_specification/SYSTEM_SPEC.md');
+  }
+  return path.join(basePath, `.blueprint/features/feature_${slug}/FEATURE_SPEC.md`);
+}
+
+module.exports = {
+  SESSION_STATES,
+  SECTION_ORDER,
+  MIN_REQUIRED_SECTIONS,
+  SYSTEM_SPEC_QUESTIONS,
+  parseFlags,
+  shouldEnterInteractiveMode,
+  createSession,
+  getSessionProgress,
+  handleCommand,
+  getNextSection,
+  markSectionComplete,
+  markSectionTBD,
+  gatherContext,
+  identifyGaps,
+  generateQuestions,
+  getMissingSections,
+  canFinalize,
+  generateSpec,
+  writeSpec,
+  generateHandoff,
+  getOutputPath
+};

package/src/stack.js

@@ -0,0 +1,320 @@
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG_FILE = '.claude/stack-config.json';
+
+/**
+ * Returns the default (empty) stack configuration.
+ */
+function getDefaultStackConfig() {
+  return {
+    language: '',
+    runtime: '',
+    packageManager: '',
+    frameworks: [],
+    testRunner: '',
+    testCommand: '',
+    linter: '',
+    tools: []
+  };
+}
+
+/**
+ * Ensures the .claude directory exists.
+ */
+function ensureConfigDir() {
+  const dir = path.dirname(CONFIG_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Reads the stack config from file.
+ * Returns defaults if file is missing or corrupted.
+ */
+function readStackConfig() {
+  ensureConfigDir();
+  if (!fs.existsSync(CONFIG_FILE)) {
+    return getDefaultStackConfig();
+  }
+  try {
+    const content = fs.readFileSync(CONFIG_FILE, 'utf8');
+    return JSON.parse(content);
+  } catch (err) {
+    return getDefaultStackConfig();
+  }
+}
+
+/**
+ * Writes the stack config to file.
+ */
+function writeStackConfig(config) {
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+/**
+ * Resets stack config to defaults by writing empty config to file.
+ */
+function resetStackConfig() {
+  writeStackConfig(getDefaultStackConfig());
+}
+
+const VALID_KEYS = [
+  'language', 'runtime', 'packageManager',
+  'frameworks', 'testRunner', 'testCommand',
+  'linter', 'tools'
+];
+
+const ARRAY_KEYS = ['frameworks', 'tools'];
+
+/**
+ * Sets a config value by key.
+ * Array keys (frameworks, tools) accept JSON array strings.
+ * @param {string} key - Config key
+ * @param {string} value - New value (string or JSON array string)
+ */
+function setStackConfigValue(key, value) {
+  if (!VALID_KEYS.includes(key)) {
+    throw new Error(
+      `Unknown config key: ${key}. Valid keys: ${VALID_KEYS.join(', ')}`
+    );
+  }
+
+  const config = readStackConfig();
+
+  if (ARRAY_KEYS.includes(key)) {
+    // Try parsing as JSON array
+    try {
+      const parsed = JSON.parse(value);
+      if (!Array.isArray(parsed)) {
+        throw new Error(`${key} must be a JSON array, e.g. '["express","react"]'`);
+      }
+      config[key] = parsed;
+    } catch (err) {
+      if (err.message.includes('must be a JSON array')) throw err;
+      throw new Error(`${key} must be a valid JSON array, e.g. '["express","react"]'`);
+    }
+  } else {
+    config[key] = value;
+  }
+
+  writeStackConfig(config);
+  const display = Array.isArray(config[key]) ? JSON.stringify(config[key]) : config[key];
+  console.log(`Set ${key} = ${display}`);
+}
+
+/**
+ * Auto-detect tech stack from project files.
+ * Scans for manifest files and infers configuration.
+ * @param {string} projectDir - Directory to scan (defaults to cwd)
+ * @returns {object} Detected stack config
+ */
+function detectStackConfig(projectDir) {
+  const dir = projectDir || process.cwd();
+  const config = getDefaultStackConfig();
+
+  const exists = (file) => fs.existsSync(path.join(dir, file));
+  const readJSON = (file) => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+    } catch {
+      return null;
+    }
+  };
+  const readText = (file) => {
+    try {
+      return fs.readFileSync(path.join(dir, file), 'utf8');
+    } catch {
+      return null;
+    }
+  };
+
+  // Node.js / JavaScript detection
+  if (exists('package.json')) {
+    config.language = 'JavaScript';
+    config.runtime = 'Node.js';
+
+    const pkg = readJSON('package.json');
+    if (pkg) {
+      // Runtime version from engines
+      if (pkg.engines && pkg.engines.node) {
+        config.runtime = `Node.js ${pkg.engines.node}`;
+      }
+
+      const deps = pkg.dependencies || {};
+      const devDeps = pkg.devDependencies || {};
+      const allDeps = { ...deps, ...devDeps };
+
+      // Frameworks
+      const frameworkNames = [
+        'express', 'fastify', 'koa', 'react', 'next',
+        'vue', 'angular', 'hapi', 'nest', '@hapi/hapi', '@nestjs/core'
+      ];
+      const detected = [];
+      for (const fw of frameworkNames) {
+        if (fw in deps || fw in devDeps) {
+          // Normalize package names to friendly names
+          if (fw === '@hapi/hapi') detected.push('hapi');
+          else if (fw === '@nestjs/core') detected.push('nest');
+          else detected.push(fw);
+        }
+      }
+      if (detected.length > 0) config.frameworks = detected;
+
+      // Test runner
+      const testRunners = ['jest', 'mocha', 'vitest', 'ava'];
+      for (const tr of testRunners) {
+        if (tr in devDeps || tr in deps) {
+          config.testRunner = tr;
+          break;
+        }
+      }
+
+      // Test command from scripts
+      if (pkg.scripts && pkg.scripts.test) {
+        config.testCommand = pkg.scripts.test;
+        // Also try to detect test runner from test script if not found in deps
+        if (!config.testRunner) {
+          for (const tr of testRunners) {
+            if (pkg.scripts.test.includes(tr)) {
+              config.testRunner = tr;
+              break;
+            }
+          }
+        }
+      }
+      if (!config.testCommand) {
+        config.testCommand = 'npm test';
+      }
+
+      // Linter
+      const linters = ['eslint', 'biome', 'oxlint', '@biomejs/biome'];
+      for (const l of linters) {
+        if (l in devDeps || l in deps) {
+          if (l === '@biomejs/biome') config.linter = 'biome';
+          else config.linter = l;
+          break;
+        }
+      }
+
+      // Tools
+      const toolNames = ['nodemon', 'supertest', 'prettier', 'typescript'];
+      const detectedTools = [];
+      for (const t of toolNames) {
+        if (t in devDeps || t in deps) {
+          detectedTools.push(t);
+        }
+      }
+      if (detectedTools.length > 0) config.tools = detectedTools;
+
+      // Package manager from lockfiles
+      if (exists('yarn.lock')) {
+        config.packageManager = 'yarn';
+      } else if (exists('pnpm-lock.yaml')) {
+        config.packageManager = 'pnpm';
+      } else {
+        config.packageManager = 'npm';
+      }
+    }
+  }
+
+  // TypeScript overrides JavaScript
+  if (exists('tsconfig.json')) {
+    config.language = 'TypeScript';
+    if (!config.runtime) config.runtime = 'Node.js';
+  }
+
+  // Python detection
+  if (exists('pyproject.toml') || exists('requirements.txt')) {
+    config.language = 'Python';
+    config.runtime = 'Python 3.x';
+
+    const pyproject = readText('pyproject.toml');
+    if (pyproject) {
+      // Test runner
+      if (pyproject.includes('pytest')) config.testRunner = 'pytest';
+      else if (pyproject.includes('unittest')) config.testRunner = 'unittest';
+
+      // Linter/tools
+      if (pyproject.includes('ruff')) config.linter = 'ruff';
+      else if (pyproject.includes('flake8')) config.linter = 'flake8';
+
+      const pyTools = [];
+      if (pyproject.includes('black')) pyTools.push('black');
+      if (pyproject.includes('mypy')) pyTools.push('mypy');
+      if (pyTools.length > 0) config.tools = pyTools;
+
+      // Frameworks
+      const pyFrameworks = [];
+      if (pyproject.includes('django')) pyFrameworks.push('django');
+      if (pyproject.includes('flask')) pyFrameworks.push('flask');
+      if (pyproject.includes('fastapi')) pyFrameworks.push('fastapi');
+      if (pyFrameworks.length > 0) config.frameworks = pyFrameworks;
+    }
+
+    // Package manager
+    if (exists('poetry.lock')) config.packageManager = 'poetry';
+    else if (exists('Pipfile.lock') || exists('Pipfile')) config.packageManager = 'pipenv';
+    else config.packageManager = 'pip';
+
+    if (!config.testCommand && config.testRunner) {
+      config.testCommand = config.testRunner === 'pytest' ? 'pytest' : 'python -m unittest';
+    }
+  }
+
+  // Go detection
+  if (exists('go.mod')) {
+    config.language = 'Go';
+    config.runtime = 'Go';
+    config.testRunner = 'go test';
+    config.testCommand = 'go test ./...';
+  }
+
+  // Rust detection
+  if (exists('Cargo.toml')) {
+    config.language = 'Rust';
+    config.runtime = 'Rust';
+    config.packageManager = 'cargo';
+    config.testRunner = 'cargo test';
+    config.testCommand = 'cargo test';
+  }
+
+  // Ruby detection
+  if (exists('Gemfile')) {
+    config.language = 'Ruby';
+    config.runtime = 'Ruby';
+    config.packageManager = 'bundler';
+  }
+
+  return config;
+}
+
+/**
+ * Displays the current stack configuration.
+ */
+function displayStackConfig() {
+  const config = readStackConfig();
+  console.log('\nStack Configuration\n');
+  console.log(`  language:       ${config.language || '(not set)'}`);
+  console.log(`  runtime:        ${config.runtime || '(not set)'}`);
+  console.log(`  packageManager: ${config.packageManager || '(not set)'}`);
+  console.log(`  frameworks:     ${config.frameworks.length > 0 ? config.frameworks.join(', ') : '(not set)'}`);
+  console.log(`  testRunner:     ${config.testRunner || '(not set)'}`);
+  console.log(`  testCommand:    ${config.testCommand || '(not set)'}`);
+  console.log(`  linter:         ${config.linter || '(not set)'}`);
+  console.log(`  tools:          ${config.tools.length > 0 ? config.tools.join(', ') : '(not set)'}`);
+  console.log('\nTo change: orchestr8 stack-config set <key> <value>');
+}
+
+module.exports = {
+  CONFIG_FILE,
+  getDefaultStackConfig,
+  readStackConfig,
+  writeStackConfig,
+  resetStackConfig,
+  setStackConfigValue,
+  detectStackConfig,
+  displayStackConfig
+};