openspecui 0.0.0

package/references/openspec/scripts/pack-version-check.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Guard: Ensure the packed tarball's CLI `--version` matches package.json.
+//
+// Notes:
+// - We intentionally use `npm pack` (not pnpm) because `npm pack --json` is
+//   consistently supported and returns the tarball metadata we need. The
+//   project uses pnpm for install/publish, but this guard only needs to pack
+//   locally and verify the installed CLI output.
+// - `npm pack` triggers the package's `prepare` script (build), and
+//   `changeset publish` triggers `prepublishOnly` (also builds here). This
+//   means an explicit build is not strictly necessary for the guard.
+
+import { execFileSync } from 'child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import path from 'path';
+
+function log(msg) {
+  if (process.env.CI) return; // keep CI logs quiet by default
+  console.log(msg);
+}
+
+function run(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], ...opts });
+}
+
+function npmPack() {
+  try {
+    const jsonOut = run('npm', ['pack', '--json', '--silent']);
+    const arr = JSON.parse(jsonOut);
+    if (Array.isArray(arr) && arr.length > 0) {
+      const last = arr[arr.length - 1];
+      const file = (last && typeof last === 'object' && last.filename) || (typeof last === 'string' ? last : null);
+      if (file) return String(file).trim();
+    }
+    // Unexpected JSON shape or empty array; fallback to plain output
+    const out = run('npm', ['pack', '--silent']).trim();
+    const lines = out.split(/\r?\n/);
+    return lines[lines.length - 1].trim();
+  } catch (e) {
+    // Fallback for environments not supporting --json
+    const out = run('npm', ['pack', '--silent']).trim();
+    const lines = out.split(/\r?\n/);
+    return lines[lines.length - 1].trim();
+  }
+}
+
+function main() {
+  const pkg = JSON.parse(readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'));
+  const expected = pkg.version;
+
+  let work;
+  let tgzPath;
+
+  try {
+    log(`Packing @fission-ai/openspec@${expected}...`);
+    const filename = npmPack();
+    tgzPath = path.resolve(filename);
+    log(`Created: ${tgzPath}`);
+
+    work = mkdtempSync(path.join(tmpdir(), 'openspec-pack-check-'));
+    log(`Temp dir: ${work}`);
+
+    // Make a tiny project
+    writeFileSync(
+      path.join(work, 'package.json'),
+      JSON.stringify({ name: 'pack-check', private: true }, null, 2)
+    );
+
+    // Try to avoid noisy output and speed up
+    const env = {
+      ...process.env,
+      npm_config_loglevel: 'silent',
+      npm_config_audit: 'false',
+      npm_config_fund: 'false',
+      npm_config_progress: 'false',
+    };
+
+    // Install the tarball
+    run('npm', ['install', tgzPath, '--silent', '--no-audit', '--no-fund'], { cwd: work, env });
+
+    // Run the installed CLI via Node to avoid bin resolution/platform issues
+    const binRel = path.join('node_modules', '@fission-ai', 'openspec', 'bin', 'openspec.js');
+    const actual = run(process.execPath, [binRel, '--version'], { cwd: work }).trim();
+
+    if (actual !== expected) {
+      throw new Error(
+        `Packed CLI version mismatch: expected ${expected}, got ${actual}. ` +
+          'Ensure the dist is built and the CLI reads version from package.json.'
+      );
+    }
+
+    log('Version check passed.');
+  } finally {
+    // Always attempt cleanup
+    if (work) {
+      try { rmSync(work, { recursive: true, force: true }); } catch {}
+    }
+    if (tgzPath) {
+      try { rmSync(tgzPath, { force: true }); } catch {}
+    }
+  }
+}
+
+try {
+  main();
+  console.log('✅ pack-version-check: OK');
+} catch (err) {
+  console.error(`❌ pack-version-check: ${err.message}`);
+  process.exit(1);
+}

package/references/openspec/src/cli/index.ts

@@ -0,0 +1,253 @@
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import ora from 'ora';
+import path from 'path';
+import { promises as fs } from 'fs';
+import { InitCommand } from '../core/init.js';
+import { AI_TOOLS } from '../core/config.js';
+import { UpdateCommand } from '../core/update.js';
+import { ListCommand } from '../core/list.js';
+import { ArchiveCommand } from '../core/archive.js';
+import { ViewCommand } from '../core/view.js';
+import { registerSpecCommand } from '../commands/spec.js';
+import { ChangeCommand } from '../commands/change.js';
+import { ValidateCommand } from '../commands/validate.js';
+import { ShowCommand } from '../commands/show.js';
+
+const program = new Command();
+const require = createRequire(import.meta.url);
+const { version } = require('../../package.json');
+
+program
+  .name('openspec')
+  .description('AI-native system for spec-driven development')
+  .version(version);
+
+// Global options
+program.option('--no-color', 'Disable color output');
+
+// Apply global flags before any command runs
+program.hook('preAction', (thisCommand) => {
+  const opts = thisCommand.opts();
+  if (opts.noColor) {
+    process.env.NO_COLOR = '1';
+  }
+});
+
+const availableToolIds = AI_TOOLS.filter((tool) => tool.available).map((tool) => tool.value);
+const toolsOptionDescription = `Configure AI tools non-interactively. Use "all", "none", or a comma-separated list of: ${availableToolIds.join(', ')}`;
+
+program
+  .command('init [path]')
+  .description('Initialize OpenSpec in your project')
+  .option('--tools <tools>', toolsOptionDescription)
+  .action(async (targetPath = '.', options?: { tools?: string }) => {
+    try {
+      // Validate that the path is a valid directory
+      const resolvedPath = path.resolve(targetPath);
+      
+      try {
+        const stats = await fs.stat(resolvedPath);
+        if (!stats.isDirectory()) {
+          throw new Error(`Path "${targetPath}" is not a directory`);
+        }
+      } catch (error: any) {
+        if (error.code === 'ENOENT') {
+          // Directory doesn't exist, but we can create it
+          console.log(`Directory "${targetPath}" doesn't exist, it will be created.`);
+        } else if (error.message && error.message.includes('not a directory')) {
+          throw error;
+        } else {
+          throw new Error(`Cannot access path "${targetPath}": ${error.message}`);
+        }
+      }
+      
+      const initCommand = new InitCommand({
+        tools: options?.tools,
+      });
+      await initCommand.execute(targetPath);
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('update [path]')
+  .description('Update OpenSpec instruction files')
+  .action(async (targetPath = '.') => {
+    try {
+      const resolvedPath = path.resolve(targetPath);
+      const updateCommand = new UpdateCommand();
+      await updateCommand.execute(resolvedPath);
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('list')
+  .description('List items (changes by default). Use --specs to list specs.')
+  .option('--specs', 'List specs instead of changes')
+  .option('--changes', 'List changes explicitly (default)')
+  .action(async (options?: { specs?: boolean; changes?: boolean }) => {
+    try {
+      const listCommand = new ListCommand();
+      const mode: 'changes' | 'specs' = options?.specs ? 'specs' : 'changes';
+      await listCommand.execute('.', mode);
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('view')
+  .description('Display an interactive dashboard of specs and changes')
+  .action(async () => {
+    try {
+      const viewCommand = new ViewCommand();
+      await viewCommand.execute('.');
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+// Change command with subcommands
+const changeCmd = program
+  .command('change')
+  .description('Manage OpenSpec change proposals');
+
+// Deprecation notice for noun-based commands
+changeCmd.hook('preAction', () => {
+  console.error('Warning: The "openspec change ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec list", "openspec validate --changes").');
+});
+
+changeCmd
+  .command('show [change-name]')
+  .description('Show a change proposal in JSON or markdown format')
+  .option('--json', 'Output as JSON')
+  .option('--deltas-only', 'Show only deltas (JSON only)')
+  .option('--requirements-only', 'Alias for --deltas-only (deprecated)')
+  .option('--no-interactive', 'Disable interactive prompts')
+  .action(async (changeName?: string, options?: { json?: boolean; requirementsOnly?: boolean; deltasOnly?: boolean; noInteractive?: boolean }) => {
+    try {
+      const changeCommand = new ChangeCommand();
+      await changeCommand.show(changeName, options);
+    } catch (error) {
+      console.error(`Error: ${(error as Error).message}`);
+      process.exitCode = 1;
+    }
+  });
+
+changeCmd
+  .command('list')
+  .description('List all active changes (DEPRECATED: use "openspec list" instead)')
+  .option('--json', 'Output as JSON')
+  .option('--long', 'Show id and title with counts')
+  .action(async (options?: { json?: boolean; long?: boolean }) => {
+    try {
+      console.error('Warning: "openspec change list" is deprecated. Use "openspec list".');
+      const changeCommand = new ChangeCommand();
+      await changeCommand.list(options);
+    } catch (error) {
+      console.error(`Error: ${(error as Error).message}`);
+      process.exitCode = 1;
+    }
+  });
+
+changeCmd
+  .command('validate [change-name]')
+  .description('Validate a change proposal')
+  .option('--strict', 'Enable strict validation mode')
+  .option('--json', 'Output validation report as JSON')
+  .option('--no-interactive', 'Disable interactive prompts')
+  .action(async (changeName?: string, options?: { strict?: boolean; json?: boolean; noInteractive?: boolean }) => {
+    try {
+      const changeCommand = new ChangeCommand();
+      await changeCommand.validate(changeName, options);
+      if (typeof process.exitCode === 'number' && process.exitCode !== 0) {
+        process.exit(process.exitCode);
+      }
+    } catch (error) {
+      console.error(`Error: ${(error as Error).message}`);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command('archive [change-name]')
+  .description('Archive a completed change and update main specs')
+  .option('-y, --yes', 'Skip confirmation prompts')
+  .option('--skip-specs', 'Skip spec update operations (useful for infrastructure, tooling, or doc-only changes)')
+  .option('--no-validate', 'Skip validation (not recommended, requires confirmation)')
+  .action(async (changeName?: string, options?: { yes?: boolean; skipSpecs?: boolean; noValidate?: boolean; validate?: boolean }) => {
+    try {
+      const archiveCommand = new ArchiveCommand();
+      await archiveCommand.execute(changeName, options);
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+registerSpecCommand(program);
+
+// Top-level validate command
+program
+  .command('validate [item-name]')
+  .description('Validate changes and specs')
+  .option('--all', 'Validate all changes and specs')
+  .option('--changes', 'Validate all changes')
+  .option('--specs', 'Validate all specs')
+  .option('--type <type>', 'Specify item type when ambiguous: change|spec')
+  .option('--strict', 'Enable strict validation mode')
+  .option('--json', 'Output validation results as JSON')
+  .option('--concurrency <n>', 'Max concurrent validations (defaults to env OPENSPEC_CONCURRENCY or 6)')
+  .option('--no-interactive', 'Disable interactive prompts')
+  .action(async (itemName?: string, options?: { all?: boolean; changes?: boolean; specs?: boolean; type?: string; strict?: boolean; json?: boolean; noInteractive?: boolean; concurrency?: string }) => {
+    try {
+      const validateCommand = new ValidateCommand();
+      await validateCommand.execute(itemName, options);
+    } catch (error) {
+      console.log();
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+// Top-level show command
+program
+  .command('show [item-name]')
+  .description('Show a change or spec')
+  .option('--json', 'Output as JSON')
+  .option('--type <type>', 'Specify item type when ambiguous: change|spec')
+  .option('--no-interactive', 'Disable interactive prompts')
+  // change-only flags
+  .option('--deltas-only', 'Show only deltas (JSON only, change)')
+  .option('--requirements-only', 'Alias for --deltas-only (deprecated, change)')
+  // spec-only flags
+  .option('--requirements', 'JSON only: Show only requirements (exclude scenarios)')
+  .option('--no-scenarios', 'JSON only: Exclude scenario content')
+  .option('-r, --requirement <id>', 'JSON only: Show specific requirement by ID (1-based)')
+  // allow unknown options to pass-through to underlying command implementation
+  .allowUnknownOption(true)
+  .action(async (itemName?: string, options?: { json?: boolean; type?: string; noInteractive?: boolean; [k: string]: any }) => {
+    try {
+      const showCommand = new ShowCommand();
+      await showCommand.execute(itemName, options ?? {});
+    } catch (error) {
+      console.log();
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/references/openspec/src/commands/change.ts

@@ -0,0 +1,291 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { select } from '@inquirer/prompts';
+import { JsonConverter } from '../core/converters/json-converter.js';
+import { Validator } from '../core/validation/validator.js';
+import { ChangeParser } from '../core/parsers/change-parser.js';
+import { Change } from '../core/schemas/index.js';
+import { isInteractive } from '../utils/interactive.js';
+import { getActiveChangeIds } from '../utils/item-discovery.js';
+
+// Constants for better maintainability
+const ARCHIVE_DIR = 'archive';
+const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
+const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
+
+export class ChangeCommand {
+  private converter: JsonConverter;
+
+  constructor() {
+    this.converter = new JsonConverter();
+  }
+
+  /**
+   * Show a change proposal.
+   * - Text mode: raw markdown passthrough (no filters)
+   * - JSON mode: minimal object with deltas; --deltas-only returns same object with filtered deltas
+   *   Note: --requirements-only is deprecated alias for --deltas-only
+   */
+  async show(changeName?: string, options?: { json?: boolean; requirementsOnly?: boolean; deltasOnly?: boolean; noInteractive?: boolean }): Promise<void> {
+    const changesPath = path.join(process.cwd(), 'openspec', 'changes');
+
+    if (!changeName) {
+      const canPrompt = isInteractive(options?.noInteractive);
+      const changes = await this.getActiveChanges(changesPath);
+      if (canPrompt && changes.length > 0) {
+        const selected = await select({
+          message: 'Select a change to show',
+          choices: changes.map(id => ({ name: id, value: id })),
+        });
+        changeName = selected;
+      } else {
+        if (changes.length === 0) {
+          console.error('No change specified. No active changes found.');
+        } else {
+          console.error(`No change specified. Available IDs: ${changes.join(', ')}`);
+        }
+        console.error('Hint: use "openspec change list" to view available changes.');
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    const proposalPath = path.join(changesPath, changeName, 'proposal.md');
+
+    try {
+      await fs.access(proposalPath);
+    } catch {
+      throw new Error(`Change "${changeName}" not found at ${proposalPath}`);
+    }
+
+    if (options?.json) {
+      const jsonOutput = await this.converter.convertChangeToJson(proposalPath);
+
+      if (options.requirementsOnly) {
+        console.error('Flag --requirements-only is deprecated; use --deltas-only instead.');
+      }
+
+      const parsed: Change = JSON.parse(jsonOutput);
+      const contentForTitle = await fs.readFile(proposalPath, 'utf-8');
+      const title = this.extractTitle(contentForTitle, changeName);
+      const id = parsed.name;
+      const deltas = parsed.deltas || [];
+
+      if (options.requirementsOnly || options.deltasOnly) {
+        const output = { id, title, deltaCount: deltas.length, deltas };
+        console.log(JSON.stringify(output, null, 2));
+      } else {
+        const output = {
+          id,
+          title,
+          deltaCount: deltas.length,
+          deltas,
+        };
+        console.log(JSON.stringify(output, null, 2));
+      }
+    } else {
+      const content = await fs.readFile(proposalPath, 'utf-8');
+      console.log(content);
+    }
+  }
+
+  /**
+   * List active changes.
+   * - Text default: IDs only; --long prints minimal details (title, counts)
+   * - JSON: array of { id, title, deltaCount, taskStatus }, sorted by id
+   */
+  async list(options?: { json?: boolean; long?: boolean }): Promise<void> {
+    const changesPath = path.join(process.cwd(), 'openspec', 'changes');
+    
+    const changes = await this.getActiveChanges(changesPath);
+    
+    if (options?.json) {
+      const changeDetails = await Promise.all(
+        changes.map(async (changeName) => {
+          const proposalPath = path.join(changesPath, changeName, 'proposal.md');
+          const tasksPath = path.join(changesPath, changeName, 'tasks.md');
+          
+          try {
+            const content = await fs.readFile(proposalPath, 'utf-8');
+            const changeDir = path.join(changesPath, changeName);
+            const parser = new ChangeParser(content, changeDir);
+            const change = await parser.parseChangeWithDeltas(changeName);
+            
+            let taskStatus = { total: 0, completed: 0 };
+            try {
+              const tasksContent = await fs.readFile(tasksPath, 'utf-8');
+              taskStatus = this.countTasks(tasksContent);
+            } catch (error) {
+              // Tasks file may not exist, which is okay
+              if (process.env.DEBUG) {
+                console.error(`Failed to read tasks file at ${tasksPath}:`, error);
+              }
+            }
+            
+            return {
+              id: changeName,
+              title: this.extractTitle(content, changeName),
+              deltaCount: change.deltas.length,
+              taskStatus,
+            };
+          } catch (error) {
+            return {
+              id: changeName,
+              title: 'Unknown',
+              deltaCount: 0,
+              taskStatus: { total: 0, completed: 0 },
+            };
+          }
+        })
+      );
+      
+      const sorted = changeDetails.sort((a, b) => a.id.localeCompare(b.id));
+      console.log(JSON.stringify(sorted, null, 2));
+    } else {
+      if (changes.length === 0) {
+        console.log('No items found');
+        return;
+      }
+      const sorted = [...changes].sort();
+      if (!options?.long) {
+        // IDs only
+        sorted.forEach(id => console.log(id));
+        return;
+      }
+
+      // Long format: id: title and minimal counts
+      for (const changeName of sorted) {
+        const proposalPath = path.join(changesPath, changeName, 'proposal.md');
+        const tasksPath = path.join(changesPath, changeName, 'tasks.md');
+        try {
+          const content = await fs.readFile(proposalPath, 'utf-8');
+          const title = this.extractTitle(content, changeName);
+          let taskStatusText = '';
+          try {
+            const tasksContent = await fs.readFile(tasksPath, 'utf-8');
+            const { total, completed } = this.countTasks(tasksContent);
+            taskStatusText = ` [tasks ${completed}/${total}]`;
+          } catch (error) {
+            if (process.env.DEBUG) {
+              console.error(`Failed to read tasks file at ${tasksPath}:`, error);
+            }
+          }
+          const changeDir = path.join(changesPath, changeName);
+          const parser = new ChangeParser(await fs.readFile(proposalPath, 'utf-8'), changeDir);
+          const change = await parser.parseChangeWithDeltas(changeName);
+          const deltaCountText = ` [deltas ${change.deltas.length}]`;
+          console.log(`${changeName}: ${title}${deltaCountText}${taskStatusText}`);
+        } catch {
+          console.log(`${changeName}: (unable to read)`);
+        }
+      }
+    }
+  }
+
+  async validate(changeName?: string, options?: { strict?: boolean; json?: boolean; noInteractive?: boolean }): Promise<void> {
+    const changesPath = path.join(process.cwd(), 'openspec', 'changes');
+    
+    if (!changeName) {
+      const canPrompt = isInteractive(options?.noInteractive);
+      const changes = await getActiveChangeIds();
+      if (canPrompt && changes.length > 0) {
+        const selected = await select({
+          message: 'Select a change to validate',
+          choices: changes.map(id => ({ name: id, value: id })),
+        });
+        changeName = selected;
+      } else {
+        if (changes.length === 0) {
+          console.error('No change specified. No active changes found.');
+        } else {
+          console.error(`No change specified. Available IDs: ${changes.join(', ')}`);
+        }
+        console.error('Hint: use "openspec change list" to view available changes.');
+        process.exitCode = 1;
+        return;
+      }
+    }
+    
+    const changeDir = path.join(changesPath, changeName);
+    
+    try {
+      await fs.access(changeDir);
+    } catch {
+      throw new Error(`Change "${changeName}" not found at ${changeDir}`);
+    }
+    
+    const validator = new Validator(options?.strict || false);
+    const report = await validator.validateChangeDeltaSpecs(changeDir);
+    
+    if (options?.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      if (report.valid) {
+        console.log(`Change "${changeName}" is valid`);
+      } else {
+        console.error(`Change "${changeName}" has issues`);
+        report.issues.forEach(issue => {
+          const label = issue.level === 'ERROR' ? 'ERROR' : 'WARNING';
+          const prefix = issue.level === 'ERROR' ? '✗' : '⚠';
+          console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
+        });
+        // Next steps footer to guide fixing issues
+        this.printNextSteps();
+        if (!options?.json) {
+          process.exitCode = 1;
+        }
+      }
+    }
+  }
+
+  private async getActiveChanges(changesPath: string): Promise<string[]> {
+    try {
+      const entries = await fs.readdir(changesPath, { withFileTypes: true });
+      const result: string[] = [];
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === ARCHIVE_DIR) continue;
+        const proposalPath = path.join(changesPath, entry.name, 'proposal.md');
+        try {
+          await fs.access(proposalPath);
+          result.push(entry.name);
+        } catch {
+          // skip directories without proposal.md
+        }
+      }
+      return result.sort();
+    } catch {
+      return [];
+    }
+  }
+
+  private extractTitle(content: string, changeName: string): string {
+    const match = content.match(/^#\s+(?:Change:\s+)?(.+)$/im);
+    return match ? match[1].trim() : changeName;
+  }
+
+  private countTasks(content: string): { total: number; completed: number } {
+    const lines = content.split('\n');
+    let total = 0;
+    let completed = 0;
+    
+    for (const line of lines) {
+      if (line.match(TASK_PATTERN)) {
+        total++;
+        if (line.match(COMPLETED_TASK_PATTERN)) {
+          completed++;
+        }
+      }
+    }
+    
+    return { total, completed };
+  }
+
+  private printNextSteps(): void {
+    const bullets: string[] = [];
+    bullets.push('- Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements');
+    bullets.push('- Each requirement MUST include at least one #### Scenario: block');
+    bullets.push('- Debug parsed deltas: openspec change show <id> --json --deltas-only');
+    console.error('Next steps:');
+    bullets.forEach(b => console.error(`  ${b}`));
+  }
+}