@fission-ai/openspec 0.20.0 → 0.22.0

package/README.md

@@ -140,6 +140,8 @@ These tools automatically read workflow instructions from `openspec/AGENTS.md`.
 
 #### Step 1: Install the CLI globally
 
+**Option A: Using npm**
+
 ```bash
 npm install -g @fission-ai/openspec@latest
 ```
@@ -149,6 +151,39 @@ Verify installation:
 openspec --version
 ```
 
+**Option B: Using Nix (NixOS and Nix package manager)**
+
+Run OpenSpec directly without installation:
+```bash
+nix run github:Fission-AI/OpenSpec -- init
+```
+
+Or install to your profile:
+```bash
+nix profile install github:Fission-AI/OpenSpec
+```
+
+Or add to your development environment in `flake.nix`:
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    openspec.url = "github:Fission-AI/OpenSpec";
+  };
+
+  outputs = { nixpkgs, openspec, ... }: {
+    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
+      buildInputs = [ openspec.packages.x86_64-linux.default ];
+    };
+  };
+}
+```
+
+Verify installation:
+```bash
+openspec --version
+```
+
 #### Step 2: Initialize OpenSpec in your project
 
 Navigate to your project directory:

package/dist/cli/index.js

@@ -13,8 +13,10 @@ import { ChangeCommand } from '../commands/change.js';
 import { ValidateCommand } from '../commands/validate.js';
 import { ShowCommand } from '../commands/show.js';
 import { CompletionCommand } from '../commands/completion.js';
+import { FeedbackCommand } from '../commands/feedback.js';
 import { registerConfigCommand } from '../commands/config.js';
 import { registerArtifactWorkflowCommands } from '../commands/artifact-workflow.js';
+import { registerSchemaCommand } from '../commands/schema.js';
 import { maybeShowTelemetryNotice, trackCommand, shutdown } from '../telemetry/index.js';
 const program = new Command();
 const require = createRequire(import.meta.url);
@@ -229,6 +231,7 @@ program
 });
 registerSpecCommand(program);
 registerConfigCommand(program);
+registerSchemaCommand(program);
 // Top-level validate command
 program
     .command('validate [item-name]')
@@ -279,6 +282,22 @@ program
         process.exit(1);
     }
 });
+// Feedback command
+program
+    .command('feedback <message>')
+    .description('Submit feedback about OpenSpec')
+    .option('--body <text>', 'Detailed description for the feedback')
+    .action(async (message, options) => {
+    try {
+        const feedbackCommand = new FeedbackCommand();
+        await feedbackCommand.execute(message, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
 // Completion command with subcommands
 const completionCmd = program
     .command('completion')

package/dist/commands/artifact-workflow.js

@@ -16,6 +16,7 @@ import { loadChangeContext, formatChangeStatus, generateInstructions, listSchema
 import { createChange, validateChangeName } from '../utils/change-utils.js';
 import { getExploreSkillTemplate, getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getVerifyChangeSkillTemplate, getOpsxExploreCommandTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate, getOpsxVerifyCommandTemplate } from '../core/templates/skill-templates.js';
 import { FileSystemUtils } from '../utils/file-system.js';
+import { promptForConfig, serializeConfig, isExitPromptError } from '../core/config-prompts.js';
 const DEFAULT_SCHEMA = 'spec-driven';
 /**
  * Checks if color output is disabled via NO_COLOR env or --no-color flag.
@@ -97,11 +98,14 @@ async function validateChangeExists(changeName, projectRoot) {
 }
 /**
  * Validates that a schema exists and returns available schemas if not.
+ *
+ * @param schemaName - The schema name to validate
+ * @param projectRoot - Optional project root for project-local schema resolution
  */
-function validateSchemaExists(schemaName) {
-    const schemaDir = getSchemaDir(schemaName);
+function validateSchemaExists(schemaName, projectRoot) {
+    const schemaDir = getSchemaDir(schemaName, projectRoot);
     if (!schemaDir) {
-        const availableSchemas = listSchemas();
+        const availableSchemas = listSchemas(projectRoot);
         throw new Error(`Schema '${schemaName}' not found. Available schemas:\n  ${availableSchemas.join('\n  ')}`);
     }
     return schemaName;
@@ -113,7 +117,7 @@ async function statusCommand(options) {
         const changeName = await validateChangeExists(options.change, projectRoot);
         // Validate schema if explicitly provided
         if (options.schema) {
-            validateSchemaExists(options.schema);
+            validateSchemaExists(options.schema, projectRoot);
         }
         // loadChangeContext will auto-detect schema from metadata if not provided
         const context = loadChangeContext(projectRoot, changeName, options.schema);
@@ -158,7 +162,7 @@ async function instructionsCommand(artifactId, options) {
         const changeName = await validateChangeExists(options.change, projectRoot);
         // Validate schema if explicitly provided
         if (options.schema) {
-            validateSchemaExists(options.schema);
+            validateSchemaExists(options.schema, projectRoot);
         }
         // loadChangeContext will auto-detect schema from metadata if not provided
         const context = loadChangeContext(projectRoot, changeName, options.schema);
@@ -173,7 +177,7 @@ async function instructionsCommand(artifactId, options) {
             const validIds = context.graph.getAllArtifacts().map((a) => a.id);
             throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'. Valid artifacts:\n  ${validIds.join('\n  ')}`);
         }
-        const instructions = generateInstructions(context, artifactId);
+        const instructions = generateInstructions(context, artifactId, projectRoot);
         const isBlocked = instructions.dependencies.some((d) => !d.done);
         spinner.stop();
         if (options.json) {
@@ -433,7 +437,7 @@ async function applyInstructionsCommand(options) {
         const changeName = await validateChangeExists(options.change, projectRoot);
         // Validate schema if explicitly provided
         if (options.schema) {
-            validateSchemaExists(options.schema);
+            validateSchemaExists(options.schema, projectRoot);
         }
         // generateApplyInstructions uses loadChangeContext which auto-detects schema
         const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema);
@@ -498,18 +502,29 @@ function printApplyInstructionsText(instructions) {
 async function templatesCommand(options) {
     const spinner = ora('Loading templates...').start();
     try {
-        const schemaName = validateSchemaExists(options.schema ?? DEFAULT_SCHEMA);
-        const schema = resolveSchema(schemaName);
+        const projectRoot = process.cwd();
+        const schemaName = validateSchemaExists(options.schema ?? DEFAULT_SCHEMA, projectRoot);
+        const schema = resolveSchema(schemaName, projectRoot);
         const graph = ArtifactGraph.fromSchema(schema);
-        const schemaDir = getSchemaDir(schemaName);
-        // Determine if this is a user override or package built-in
-        const { getUserSchemasDir } = await import('../core/artifact-graph/resolver.js');
+        const schemaDir = getSchemaDir(schemaName, projectRoot);
+        // Determine the source (project, user, or package)
+        const { getUserSchemasDir, getProjectSchemasDir, } = await import('../core/artifact-graph/resolver.js');
+        const projectSchemasDir = getProjectSchemasDir(projectRoot);
         const userSchemasDir = getUserSchemasDir();
-        const isUserOverride = schemaDir.startsWith(userSchemasDir);
+        let source;
+        if (schemaDir.startsWith(projectSchemasDir)) {
+            source = 'project';
+        }
+        else if (schemaDir.startsWith(userSchemasDir)) {
+            source = 'user';
+        }
+        else {
+            source = 'package';
+        }
         const templates = graph.getAllArtifacts().map((artifact) => ({
             artifactId: artifact.id,
             templatePath: path.join(schemaDir, 'templates', artifact.template),
-            source: isUserOverride ? 'user' : 'package',
+            source,
         }));
         spinner.stop();
         if (options.json) {
@@ -521,7 +536,7 @@ async function templatesCommand(options) {
             return;
         }
         console.log(`Schema: ${schemaName}`);
-        console.log(`Source: ${isUserOverride ? 'user override' : 'package built-in'}`);
+        console.log(`Source: ${source}`);
         console.log();
         for (const t of templates) {
             console.log(`${t.artifactId}:`);
@@ -541,15 +556,15 @@ async function newChangeCommand(name, options) {
     if (!validation.valid) {
         throw new Error(validation.error);
     }
+    const projectRoot = process.cwd();
     // Validate schema if provided
     if (options.schema) {
-        validateSchemaExists(options.schema);
+        validateSchemaExists(options.schema, projectRoot);
     }
     const schemaDisplay = options.schema ? ` with schema '${options.schema}'` : '';
     const spinner = ora(`Creating change '${name}'${schemaDisplay}...`).start();
     try {
-        const projectRoot = process.cwd();
-        await createChange(projectRoot, name, { schema: options.schema });
+        const result = await createChange(projectRoot, name, { schema: options.schema });
         // If description provided, create README.md with description
         if (options.description) {
             const { promises: fs } = await import('fs');
@@ -557,8 +572,7 @@ async function newChangeCommand(name, options) {
             const readmePath = path.join(changeDir, 'README.md');
             await fs.writeFile(readmePath, `# ${name}\n\n${options.description}\n`, 'utf-8');
         }
-        const schemaUsed = options.schema ?? DEFAULT_SCHEMA;
-        spinner.succeed(`Created change '${name}' at openspec/changes/${name}/ (schema: ${schemaUsed})`);
+        spinner.succeed(`Created change '${name}' at openspec/changes/${name}/ (schema: ${result.schema})`);
     }
     catch (error) {
         spinner.fail(`Failed to create change '${name}'`);
@@ -667,6 +681,118 @@ ${template.content}
             console.log(chalk.green('  ✓ ' + file));
         }
         console.log();
+        // Config creation section
+        console.log('━'.repeat(70));
+        console.log();
+        console.log(chalk.bold('📋 Project Configuration (Optional)'));
+        console.log();
+        console.log('Configure project defaults for OpenSpec workflows.');
+        console.log();
+        // Check if config already exists
+        const configPath = path.join(projectRoot, 'openspec', 'config.yaml');
+        const configYmlPath = path.join(projectRoot, 'openspec', 'config.yml');
+        const configExists = fs.existsSync(configPath) || fs.existsSync(configYmlPath);
+        if (configExists) {
+            // Config already exists, skip creation
+            console.log(chalk.blue('ℹ️  openspec/config.yaml already exists. Skipping config creation.'));
+            console.log();
+            console.log('   To update config, edit openspec/config.yaml manually or:');
+            console.log('   1. Delete openspec/config.yaml');
+            console.log('   2. Run openspec artifact-experimental-setup again');
+            console.log();
+        }
+        else if (!process.stdin.isTTY) {
+            // Non-interactive mode (CI, automation, piped input)
+            console.log(chalk.blue('ℹ️  Skipping config prompts (non-interactive mode)'));
+            console.log();
+            console.log('   To create config manually, add openspec/config.yaml with:');
+            console.log(chalk.dim('   schema: spec-driven'));
+            console.log();
+        }
+        else {
+            // Prompt for config creation
+            try {
+                const configResult = await promptForConfig(projectRoot);
+                if (configResult.createConfig && configResult.schema) {
+                    // Build config object
+                    const config = {
+                        schema: configResult.schema,
+                        context: configResult.context,
+                        rules: configResult.rules,
+                    };
+                    // Serialize to YAML
+                    const yamlContent = serializeConfig(config);
+                    // Write config file
+                    try {
+                        await FileSystemUtils.writeFile(configPath, yamlContent);
+                        console.log();
+                        console.log(chalk.green('✓ Created openspec/config.yaml'));
+                        console.log();
+                        console.log('━'.repeat(70));
+                        console.log();
+                        console.log(chalk.bold('📖 Config created at: openspec/config.yaml'));
+                        // Display summary
+                        const contextLines = config.context ? config.context.split('\n').length : 0;
+                        const rulesCount = config.rules ? Object.keys(config.rules).length : 0;
+                        console.log(`   • Default schema: ${chalk.cyan(config.schema)}`);
+                        if (contextLines > 0) {
+                            console.log(`   • Project context: ${chalk.cyan(`Added (${contextLines} lines)`)}`);
+                        }
+                        if (rulesCount > 0) {
+                            console.log(`   • Rules: ${chalk.cyan(`${rulesCount} artifact${rulesCount > 1 ? 's' : ''} configured`)}`);
+                        }
+                        console.log();
+                        // Usage examples
+                        console.log(chalk.bold('Usage:'));
+                        console.log('  • New changes automatically use this schema');
+                        console.log('  • Context injected into all artifact instructions');
+                        console.log('  • Rules applied to matching artifacts');
+                        console.log();
+                        // Git commit suggestion
+                        console.log(chalk.bold('To share with team:'));
+                        console.log(chalk.dim('  git add openspec/config.yaml .claude/'));
+                        console.log(chalk.dim('  git commit -m "Setup OpenSpec experimental workflow with project config"'));
+                        console.log();
+                    }
+                    catch (writeError) {
+                        // Handle file write errors
+                        console.error();
+                        console.error(chalk.red('✗ Failed to write openspec/config.yaml'));
+                        console.error(chalk.dim(`  ${writeError.message}`));
+                        console.error();
+                        console.error('Fallback: Create config manually:');
+                        console.error(chalk.dim('  1. Create openspec/config.yaml'));
+                        console.error(chalk.dim('  2. Copy the following content:'));
+                        console.error();
+                        console.error(chalk.dim(yamlContent));
+                        console.error();
+                    }
+                }
+                else {
+                    // User chose not to create config
+                    console.log();
+                    console.log(chalk.blue('ℹ️  Skipped config creation.'));
+                    console.log('   You can create openspec/config.yaml manually later.');
+                    console.log();
+                }
+            }
+            catch (promptError) {
+                if (isExitPromptError(promptError)) {
+                    // User cancelled (Ctrl+C)
+                    console.log();
+                    console.log(chalk.blue('ℹ️  Config creation cancelled'));
+                    console.log('   Skills and commands already created');
+                    console.log('   Run setup again to create config later');
+                    console.log();
+                }
+                else {
+                    // Unexpected error
+                    throw promptError;
+                }
+            }
+        }
+        console.log('━'.repeat(70));
+        console.log();
         console.log(chalk.bold('📖 Usage:'));
         console.log();
         console.log('  ' + chalk.cyan('Skills') + ' work automatically in compatible editors:');
@@ -699,7 +825,8 @@ ${template.content}
     }
 }
 async function schemasCommand(options) {
-    const schemas = listSchemasWithInfo();
+    const projectRoot = process.cwd();
+    const schemas = listSchemasWithInfo(projectRoot);
     if (options.json) {
         console.log(JSON.stringify(schemas, null, 2));
         return;
@@ -707,7 +834,13 @@ async function schemasCommand(options) {
     console.log('Available schemas:');
     console.log();
     for (const schema of schemas) {
-        const sourceLabel = schema.source === 'user' ? chalk.dim(' (user override)') : '';
+        let sourceLabel = '';
+        if (schema.source === 'project') {
+            sourceLabel = chalk.cyan(' (project)');
+        }
+        else if (schema.source === 'user') {
+            sourceLabel = chalk.dim(' (user override)');
+        }
         console.log(`  ${chalk.bold(schema.name)}${sourceLabel}`);
         console.log(`    ${schema.description}`);
         console.log(`    Artifacts: ${schema.artifacts.join(' → ')}`);

package/dist/commands/feedback.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Feedback command implementation
+ */
+export declare class FeedbackCommand {
+    execute(message: string, options?: {
+        body?: string;
+    }): Promise<void>;
+}
+//# sourceMappingURL=feedback.d.ts.map

package/dist/commands/feedback.js

@@ -0,0 +1,183 @@
+import { execSync, execFileSync } from 'child_process';
+import { createRequire } from 'module';
+import os from 'os';
+const require = createRequire(import.meta.url);
+/**
+ * Check if gh CLI is installed and available in PATH
+ * Uses platform-appropriate command: 'where' on Windows, 'which' on Unix/macOS
+ */
+function isGhInstalled() {
+    try {
+        const command = process.platform === 'win32' ? 'where gh' : 'which gh';
+        execSync(command, { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if gh CLI is authenticated
+ */
+function isGhAuthenticated() {
+    try {
+        execSync('gh auth status', { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get OpenSpec version from package.json
+ */
+function getVersion() {
+    try {
+        const { version } = require('../../package.json');
+        return version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Get platform name
+ */
+function getPlatform() {
+    return os.platform();
+}
+/**
+ * Get current timestamp in ISO format
+ */
+function getTimestamp() {
+    return new Date().toISOString();
+}
+/**
+ * Generate metadata footer for feedback
+ */
+function generateMetadata() {
+    const version = getVersion();
+    const platform = getPlatform();
+    const timestamp = getTimestamp();
+    return `---
+Submitted via OpenSpec CLI
+- Version: ${version}
+- Platform: ${platform}
+- Timestamp: ${timestamp}`;
+}
+/**
+ * Format the feedback title
+ */
+function formatTitle(message) {
+    return `Feedback: ${message}`;
+}
+/**
+ * Format the full feedback body
+ */
+function formatBody(bodyText) {
+    const parts = [];
+    if (bodyText) {
+        parts.push(bodyText);
+        parts.push(''); // Empty line before metadata
+    }
+    parts.push(generateMetadata());
+    return parts.join('\n');
+}
+/**
+ * Generate a pre-filled GitHub issue URL for manual submission
+ */
+function generateManualSubmissionUrl(title, body) {
+    const repo = 'Fission-AI/OpenSpec';
+    const encodedTitle = encodeURIComponent(title);
+    const encodedBody = encodeURIComponent(body);
+    const encodedLabels = encodeURIComponent('feedback');
+    return `https://github.com/${repo}/issues/new?title=${encodedTitle}&body=${encodedBody}&labels=${encodedLabels}`;
+}
+/**
+ * Display formatted feedback content for manual submission
+ */
+function displayFormattedFeedback(title, body) {
+    console.log('\n--- FORMATTED FEEDBACK ---');
+    console.log(`Title: ${title}`);
+    console.log(`Labels: feedback`);
+    console.log('\nBody:');
+    console.log(body);
+    console.log('--- END FEEDBACK ---\n');
+}
+/**
+ * Submit feedback via gh CLI
+ * Uses execFileSync to prevent shell injection vulnerabilities
+ */
+function submitViaGhCli(title, body) {
+    try {
+        const result = execFileSync('gh', [
+            'issue',
+            'create',
+            '--repo',
+            'Fission-AI/OpenSpec',
+            '--title',
+            title,
+            '--body',
+            body,
+            '--label',
+            'feedback',
+        ], { encoding: 'utf-8', stdio: 'pipe' });
+        const issueUrl = result.trim();
+        console.log(`\n✓ Feedback submitted successfully!`);
+        console.log(`Issue URL: ${issueUrl}\n`);
+    }
+    catch (error) {
+        // Display the error output from gh CLI
+        if (error.stderr) {
+            console.error(error.stderr.toString());
+        }
+        else if (error.message) {
+            console.error(error.message);
+        }
+        // Exit with the same code as gh CLI
+        process.exit(error.status ?? 1);
+    }
+}
+/**
+ * Handle fallback when gh CLI is not available or not authenticated
+ */
+function handleFallback(title, body, reason) {
+    if (reason === 'missing') {
+        console.log('⚠️  GitHub CLI not found. Manual submission required.');
+    }
+    else {
+        console.log('⚠️  GitHub authentication required. Manual submission required.');
+    }
+    displayFormattedFeedback(title, body);
+    const manualUrl = generateManualSubmissionUrl(title, body);
+    console.log('Please submit your feedback manually:');
+    console.log(manualUrl);
+    if (reason === 'unauthenticated') {
+        console.log('\nTo auto-submit in the future: gh auth login');
+    }
+    // Exit with success code (fallback is successful)
+    process.exit(0);
+}
+/**
+ * Feedback command implementation
+ */
+export class FeedbackCommand {
+    async execute(message, options) {
+        // Format title and body once for all code paths
+        const title = formatTitle(message);
+        const body = formatBody(options?.body);
+        // Check if gh CLI is installed
+        if (!isGhInstalled()) {
+            handleFallback(title, body, 'missing');
+            return;
+        }
+        // Check if gh CLI is authenticated
+        if (!isGhAuthenticated()) {
+            handleFallback(title, body, 'unauthenticated');
+            return;
+        }
+        // Submit via gh CLI
+        submitViaGhCli(title, body);
+    }
+}
+//# sourceMappingURL=feedback.js.map

package/dist/commands/schema.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+/**
+ * Register the schema command and all its subcommands.
+ */
+export declare function registerSchemaCommand(program: Command): void;
+//# sourceMappingURL=schema.d.ts.map