@fission-ai/openspec 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# OpenSpec
+
+A specification-driven development system for maintaining living documentation alongside your code.
+
+## Installation
+
+```bash
+npm install -g openspec
+```
+
+## Quick Start
+
+```bash
+# Initialize OpenSpec in your project
+openspec init
+
+# Update existing OpenSpec instructions (team-friendly)
+openspec update
+
+# List specs or changes
+openspec spec list        # specs (IDs by default; use --long for details)
+openspec change list      # changes (IDs by default; use --long for details)
+
+# Show differences between specs and proposed changes
+openspec diff [change-name]
+
+# Archive completed changes
+openspec archive [change-name]
+```
+
+## Commands
+
+### `openspec init`
+
+Initializes OpenSpec in your project by creating:
+- `openspec/` directory structure
+- `openspec/README.md` with OpenSpec instructions
+- AI tool configuration files (based on your selection)
+
+### `openspec update`
+
+Updates OpenSpec instructions to the latest version. This command is **team-friendly** and only updates files that already exist:
+
+- Always updates `openspec/README.md` with the latest OpenSpec instructions
+- **Only updates existing AI tool configuration files** (e.g., CLAUDE.md, CURSOR.md)
+- **Never creates new AI tool configuration files**
+- Preserves content outside of OpenSpec markers in AI tool files
+
+This allows team members to use different AI tools without conflicts. Each developer can maintain their preferred AI tool configuration file, and `openspec update` will respect their choice.
+
+### `openspec spec`
+
+Manage and view specifications.
+
+Examples:
+- `openspec spec show <spec-id>`
+  - Text mode: prints raw `spec.md` content
+  - JSON mode (`--json`): returns minimal, stable shape
+    - Filters are JSON-only: `--requirements`, `--no-scenarios`, `-r/--requirement <1-based>`
+- `openspec spec list`
+  - Prints IDs only by default
+  - Use `--long` to include `title` and `[requirements N]`
+- `openspec spec validate <spec-id>`
+  - Text: human-readable summary to stdout/stderr
+  - `--json` for structured report
+
+### `openspec change`
+
+Manage and view change proposals.
+
+Examples:
+- `openspec change show <change-id>`
+  - Text mode: prints raw `proposal.md` content
+  - JSON mode (`--json`): `{ id, title, deltaCount, deltas }`
+  - Filtering is JSON-only: `--deltas-only` (alias: `--requirements-only`, deprecated)
+- `openspec change list`
+  - Prints IDs only by default
+  - Use `--long` to include `title` and counts `[deltas N] [tasks x/y]`
+- `openspec change validate <change-id>`
+  - Text: human-readable result
+  - `--json` for structured report
+
+### `openspec diff [change-name]`
+
+Shows the differences between current specs and proposed changes:
+- Displays a unified diff format
+- Helps review what will change before implementation
+- Useful for pull request reviews
+
+### `openspec archive [change-name]`
+
+Archives a completed change:
+- Moves change from `openspec/changes/` to `openspec/changes/archive/`
+- Adds a date prefix to the archived change
+- Updates specs to reflect the new state
+- Use `--skip-specs` to archive without updating specs (for abandoned changes)
+
+## Team Collaboration
+
+OpenSpec is designed for team collaboration:
+
+1. **AI Tool Flexibility**: Each team member can use their preferred AI assistant (Claude, Cursor, etc.)
+2. **Non-Invasive Updates**: The `update` command only modifies existing files, never forcing tools on team members
+3. **Specification Sharing**: The `openspec/` directory contains shared specifications that all team members work from
+4. **Change Tracking**: Proposed changes are visible to all team members for review before implementation
+
+## Contributing
+
+See `openspec/specs/` for the current system specifications and `openspec/changes/` for pending improvements.
+
+## Notes
+
+- The legacy `openspec list` command is deprecated. Use `openspec spec list` and `openspec change list`.
+- Text output is raw-first (no formatting or filtering). Prefer `--json` for tooling-friendly output.
+- Global `--no-color` disables ANSI colors and respects `NO_COLOR`.
+
+## License
+
+MIT

package/bin/openspec.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/cli/index.js';

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -0,0 +1,240 @@
+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 { UpdateCommand } from '../core/update.js';
+import { DiffCommand } from '../core/diff.js';
+import { ListCommand } from '../core/list.js';
+import { ArchiveCommand } from '../core/archive.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';
+    }
+});
+program
+    .command('init [path]')
+    .description('Initialize OpenSpec in your project')
+    .action(async (targetPath = '.') => {
+    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) {
+            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();
+        await initCommand.execute(targetPath);
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${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.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command('diff [change-name]')
+    .description('Show differences between proposed spec changes and current specs (includes validation warnings)')
+    .action(async (changeName) => {
+    try {
+        const diffCommand = new DiffCommand();
+        await diffCommand.execute(changeName);
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${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) => {
+    try {
+        const listCommand = new ListCommand();
+        const mode = options?.specs ? 'specs' : 'changes';
+        await listCommand.execute('.', mode);
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${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, options) => {
+    try {
+        const changeCommand = new ChangeCommand();
+        await changeCommand.show(changeName, options);
+    }
+    catch (error) {
+        console.error(`Error: ${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) => {
+    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.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, options) => {
+    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.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, options) => {
+    try {
+        const archiveCommand = new ArchiveCommand();
+        await archiveCommand.execute(changeName, options);
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${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, options) => {
+    try {
+        const validateCommand = new ValidateCommand();
+        await validateCommand.execute(itemName, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${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, options) => {
+    try {
+        const showCommand = new ShowCommand();
+        await showCommand.execute(itemName, options ?? {});
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/commands/change.d.ts

@@ -0,0 +1,35 @@
+export declare class ChangeCommand {
+    private converter;
+    constructor();
+    /**
+     * 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
+     */
+    show(changeName?: string, options?: {
+        json?: boolean;
+        requirementsOnly?: boolean;
+        deltasOnly?: boolean;
+        noInteractive?: boolean;
+    }): Promise<void>;
+    /**
+     * List active changes.
+     * - Text default: IDs only; --long prints minimal details (title, counts)
+     * - JSON: array of { id, title, deltaCount, taskStatus }, sorted by id
+     */
+    list(options?: {
+        json?: boolean;
+        long?: boolean;
+    }): Promise<void>;
+    validate(changeName?: string, options?: {
+        strict?: boolean;
+        json?: boolean;
+        noInteractive?: boolean;
+    }): Promise<void>;
+    private getActiveChanges;
+    private extractTitle;
+    private countTasks;
+    private printNextSteps;
+}
+//# sourceMappingURL=change.d.ts.map

package/dist/commands/change.js

@@ -0,0 +1,276 @@
+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 { 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 {
+    converter;
+    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, options) {
+        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 = JSON.parse(jsonOutput);
+            const contentForTitle = await fs.readFile(proposalPath, 'utf-8');
+            const title = this.extractTitle(contentForTitle);
+            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) {
+        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),
+                        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);
+                    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, options) {
+        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;
+                }
+            }
+        }
+    }
+    async getActiveChanges(changesPath) {
+        try {
+            const entries = await fs.readdir(changesPath, { withFileTypes: true });
+            const result = [];
+            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 [];
+        }
+    }
+    extractTitle(content) {
+        const match = content.match(/^#\s+(?:Change:\s+)?(.+)$/m);
+        return match ? match[1].trim() : 'Untitled Change';
+    }
+    countTasks(content) {
+        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 };
+    }
+    printNextSteps() {
+        const bullets = [];
+        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}`));
+    }
+}
+//# sourceMappingURL=change.js.map