@fission-ai/openspec 0.15.0 → 0.17.0

package/dist/core/configurators/slash/toml-base.js

@@ -0,0 +1,53 @@
+import { FileSystemUtils } from '../../../utils/file-system.js';
+import { SlashCommandConfigurator } from './base.js';
+import { OPENSPEC_MARKERS } from '../../config.js';
+export class TomlSlashCommandConfigurator extends SlashCommandConfigurator {
+    getFrontmatter(_id) {
+        // TOML doesn't use separate frontmatter - it's all in one structure
+        return undefined;
+    }
+    // Override to generate TOML format with markers inside the prompt field
+    async generateAll(projectPath, _openspecDir) {
+        const createdOrUpdated = [];
+        for (const target of this.getTargets()) {
+            const body = this.getBody(target.id);
+            const filePath = FileSystemUtils.joinPath(projectPath, target.path);
+            if (await FileSystemUtils.fileExists(filePath)) {
+                await this.updateBody(filePath, body);
+            }
+            else {
+                const tomlContent = this.generateTOML(target.id, body);
+                await FileSystemUtils.writeFile(filePath, tomlContent);
+            }
+            createdOrUpdated.push(target.path);
+        }
+        return createdOrUpdated;
+    }
+    generateTOML(id, body) {
+        const description = this.getDescription(id);
+        // TOML format with triple-quoted string for multi-line prompt
+        // Markers are inside the prompt value
+        return `description = "${description}"
+
+prompt = """
+${OPENSPEC_MARKERS.start}
+${body}
+${OPENSPEC_MARKERS.end}
+"""
+`;
+    }
+    // Override updateBody to handle TOML format
+    async updateBody(filePath, body) {
+        const content = await FileSystemUtils.readFile(filePath);
+        const startIndex = content.indexOf(OPENSPEC_MARKERS.start);
+        const endIndex = content.indexOf(OPENSPEC_MARKERS.end);
+        if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) {
+            throw new Error(`Missing OpenSpec markers in ${filePath}`);
+        }
+        const before = content.slice(0, startIndex + OPENSPEC_MARKERS.start.length);
+        const after = content.slice(endIndex);
+        const updatedContent = `${before}\n${body}\n${after}`;
+        await FileSystemUtils.writeFile(filePath, updatedContent);
+    }
+}
+//# sourceMappingURL=toml-base.js.map

package/dist/core/global-config.d.ts

@@ -0,0 +1,29 @@
+export declare const GLOBAL_CONFIG_DIR_NAME = "openspec";
+export declare const GLOBAL_CONFIG_FILE_NAME = "config.json";
+export interface GlobalConfig {
+    featureFlags?: Record<string, boolean>;
+}
+/**
+ * Gets the global configuration directory path following XDG Base Directory Specification.
+ *
+ * - All platforms: $XDG_CONFIG_HOME/openspec/ if XDG_CONFIG_HOME is set
+ * - Unix/macOS fallback: ~/.config/openspec/
+ * - Windows fallback: %APPDATA%/openspec/
+ */
+export declare function getGlobalConfigDir(): string;
+/**
+ * Gets the path to the global config file.
+ */
+export declare function getGlobalConfigPath(): string;
+/**
+ * Loads the global configuration from disk.
+ * Returns default configuration if file doesn't exist or is invalid.
+ * Merges loaded config with defaults to ensure new fields are available.
+ */
+export declare function getGlobalConfig(): GlobalConfig;
+/**
+ * Saves the global configuration to disk.
+ * Creates the config directory if it doesn't exist.
+ */
+export declare function saveGlobalConfig(config: GlobalConfig): void;
+//# sourceMappingURL=global-config.d.ts.map

package/dist/core/global-config.js

@@ -0,0 +1,87 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+// Constants
+export const GLOBAL_CONFIG_DIR_NAME = 'openspec';
+export const GLOBAL_CONFIG_FILE_NAME = 'config.json';
+const DEFAULT_CONFIG = {
+    featureFlags: {}
+};
+/**
+ * Gets the global configuration directory path following XDG Base Directory Specification.
+ *
+ * - All platforms: $XDG_CONFIG_HOME/openspec/ if XDG_CONFIG_HOME is set
+ * - Unix/macOS fallback: ~/.config/openspec/
+ * - Windows fallback: %APPDATA%/openspec/
+ */
+export function getGlobalConfigDir() {
+    // XDG_CONFIG_HOME takes precedence on all platforms when explicitly set
+    const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+    if (xdgConfigHome) {
+        return path.join(xdgConfigHome, GLOBAL_CONFIG_DIR_NAME);
+    }
+    const platform = os.platform();
+    if (platform === 'win32') {
+        // Windows: use %APPDATA%
+        const appData = process.env.APPDATA;
+        if (appData) {
+            return path.join(appData, GLOBAL_CONFIG_DIR_NAME);
+        }
+        // Fallback for Windows if APPDATA is not set
+        return path.join(os.homedir(), 'AppData', 'Roaming', GLOBAL_CONFIG_DIR_NAME);
+    }
+    // Unix/macOS fallback: ~/.config
+    return path.join(os.homedir(), '.config', GLOBAL_CONFIG_DIR_NAME);
+}
+/**
+ * Gets the path to the global config file.
+ */
+export function getGlobalConfigPath() {
+    return path.join(getGlobalConfigDir(), GLOBAL_CONFIG_FILE_NAME);
+}
+/**
+ * Loads the global configuration from disk.
+ * Returns default configuration if file doesn't exist or is invalid.
+ * Merges loaded config with defaults to ensure new fields are available.
+ */
+export function getGlobalConfig() {
+    const configPath = getGlobalConfigPath();
+    try {
+        if (!fs.existsSync(configPath)) {
+            return { ...DEFAULT_CONFIG };
+        }
+        const content = fs.readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        // Merge with defaults (loaded values take precedence)
+        return {
+            ...DEFAULT_CONFIG,
+            ...parsed,
+            // Deep merge featureFlags
+            featureFlags: {
+                ...DEFAULT_CONFIG.featureFlags,
+                ...(parsed.featureFlags || {})
+            }
+        };
+    }
+    catch (error) {
+        // Log warning for parse errors, but not for missing files
+        if (error instanceof SyntaxError) {
+            console.error(`Warning: Invalid JSON in ${configPath}, using defaults`);
+        }
+        return { ...DEFAULT_CONFIG };
+    }
+}
+/**
+ * Saves the global configuration to disk.
+ * Creates the config directory if it doesn't exist.
+ */
+export function saveGlobalConfig(config) {
+    const configDir = getGlobalConfigDir();
+    const configPath = getGlobalConfigPath();
+    // Create directory if it doesn't exist
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+//# sourceMappingURL=global-config.js.map

package/dist/core/index.d.ts

@@ -1,2 +1,2 @@
-export {};
+export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, type GlobalConfig, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig } from './global-config.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -1,2 +1,3 @@
-export {};
+// Core OpenSpec logic will be implemented here
+export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig } from './global-config.js';
 //# sourceMappingURL=index.js.map

package/dist/core/init.js

@@ -567,6 +567,13 @@ export class InitCommand {
         }
         console.log();
         console.log(PALETTE.midGray('Use `openspec update` to refresh shared OpenSpec instructions in the future.'));
+        // Show restart instruction if any tools were configured
+        if (created.length > 0 || refreshed.length > 0) {
+            console.log();
+            console.log(PALETTE.white('Important: Restart your IDE'));
+            console.log(PALETTE.midGray('Slash commands are loaded at startup. Please restart your coding assistant'));
+            console.log(PALETTE.midGray('to ensure the new /openspec commands appear in your command palette.'));
+        }
         // Get the selected tool name(s) for display
         const toolName = this.formatToolNames(selectedTools);
         console.log();

package/dist/core/templates/slash-command-templates.js

@@ -2,7 +2,8 @@ const baseGuardrails = `**Guardrails**
 - Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
 - Keep changes tightly scoped to the requested outcome.
 - Refer to \`openspec/AGENTS.md\` (located inside the \`openspec/\` directory—run \`ls openspec\` or \`openspec update\` if you don't see it) if you need additional OpenSpec conventions or clarifications.`;
-const proposalGuardrails = `${baseGuardrails}\n- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.`;
+const proposalGuardrails = `${baseGuardrails}\n- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.`;
 const proposalSteps = `**Steps**
 1. Review \`openspec/project.md\`, run \`openspec list\` and \`openspec list --specs\`, and inspect related code or docs (e.g., via \`rg\`/\`ls\`) to ground the proposal in current behaviour; note any gaps that require clarification.
 2. Choose a unique verb-led \`change-id\` and scaffold \`proposal.md\`, \`tasks.md\`, and \`design.md\` (when needed) under \`openspec/changes/<id>/\`.

package/dist/utils/file-system.js

@@ -1,4 +1,4 @@
-import { promises as fs } from 'fs';
+import { promises as fs, constants as fsConstants } from 'fs';
 import path from 'path';
 function isMarkerOnOwnLine(content, markerIndex, markerLength) {
     let leftIndex = markerIndex - 1;
@@ -72,11 +72,27 @@ export class FileSystemUtils {
             if (!stats.isFile()) {
                 return true;
             }
-            return (stats.mode & 0o222) !== 0;
+            // On Windows, stats.mode doesn't reliably indicate write permissions.
+            // Use fs.access with W_OK to check actual write permissions cross-platform.
+            try {
+                await fs.access(filePath, fsConstants.W_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
         }
         catch (error) {
             if (error.code === 'ENOENT') {
-                return true;
+                // File doesn't exist; check if we can write to the parent directory
+                const parentDir = path.dirname(filePath);
+                try {
+                    await fs.access(parentDir, fsConstants.W_OK);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
             }
             console.debug(`Unable to determine write permissions for ${filePath}: ${error.message}`);
             return false;

package/dist/utils/interactive.d.ts

@@ -1,2 +1,13 @@
-export declare function isInteractive(noInteractiveFlag?: boolean): boolean;
+type InteractiveOptions = {
+    /**
+     * Explicit "disable prompts" flag passed by internal callers.
+     */
+    noInteractive?: boolean;
+    /**
+     * Commander-style negated option: `--no-interactive` sets this to false.
+     */
+    interactive?: boolean;
+};
+export declare function isInteractive(value?: boolean | InteractiveOptions): boolean;
+export {};
 //# sourceMappingURL=interactive.d.ts.map

package/dist/utils/interactive.js

@@ -1,5 +1,10 @@
-export function isInteractive(noInteractiveFlag) {
-    if (noInteractiveFlag)
+function resolveNoInteractive(value) {
+    if (typeof value === 'boolean')
+        return value;
+    return value?.noInteractive === true || value?.interactive === false;
+}
+export function isInteractive(value) {
+    if (resolveNoInteractive(value))
         return false;
     if (process.env.OPEN_SPEC_INTERACTIVE === '0')
         return false;

package/dist/utils/item-discovery.d.ts

@@ -1,3 +1,4 @@
 export declare function getActiveChangeIds(root?: string): Promise<string[]>;
 export declare function getSpecIds(root?: string): Promise<string[]>;
+export declare function getArchivedChangeIds(root?: string): Promise<string[]>;
 //# sourceMappingURL=item-discovery.d.ts.map

package/dist/utils/item-discovery.js

@@ -46,4 +46,27 @@ export async function getSpecIds(root = process.cwd()) {
     }
     return result.sort();
 }
+export async function getArchivedChangeIds(root = process.cwd()) {
+    const archivePath = path.join(root, 'openspec', 'changes', 'archive');
+    try {
+        const entries = await fs.readdir(archivePath, { withFileTypes: true });
+        const result = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            const proposalPath = path.join(archivePath, entry.name, 'proposal.md');
+            try {
+                await fs.access(proposalPath);
+                result.push(entry.name);
+            }
+            catch {
+                // skip directories without proposal.md
+            }
+        }
+        return result.sort();
+    }
+    catch {
+        return [];
+    }
+}
 //# sourceMappingURL=item-discovery.js.map

package/dist/utils/shell-detection.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Supported shell types for completion generation
+ */
+export type SupportedShell = 'zsh' | 'bash' | 'fish' | 'powershell';
+/**
+ * Result of shell detection
+ */
+export interface ShellDetectionResult {
+    /** The detected shell if supported, otherwise undefined */
+    shell: SupportedShell | undefined;
+    /** The raw shell name detected (even if unsupported), or undefined if nothing detected */
+    detected: string | undefined;
+}
+/**
+ * Detects the current user's shell based on environment variables
+ *
+ * @returns Detection result with supported shell and raw detected name
+ */
+export declare function detectShell(): ShellDetectionResult;
+//# sourceMappingURL=shell-detection.d.ts.map

package/dist/utils/shell-detection.js

@@ -0,0 +1,41 @@
+/**
+ * Detects the current user's shell based on environment variables
+ *
+ * @returns Detection result with supported shell and raw detected name
+ */
+export function detectShell() {
+    // Try SHELL environment variable first (Unix-like systems)
+    const shellPath = process.env.SHELL;
+    if (shellPath) {
+        const shellName = shellPath.toLowerCase();
+        if (shellName.includes('zsh')) {
+            return { shell: 'zsh', detected: 'zsh' };
+        }
+        if (shellName.includes('bash')) {
+            return { shell: 'bash', detected: 'bash' };
+        }
+        if (shellName.includes('fish')) {
+            return { shell: 'fish', detected: 'fish' };
+        }
+        // Shell detected but not supported
+        // Extract shell name from path (e.g., /bin/tcsh -> tcsh)
+        const match = shellPath.match(/\/([^/]+)$/);
+        const detectedName = match ? match[1] : shellPath;
+        return { shell: undefined, detected: detectedName };
+    }
+    // Check for PowerShell on Windows
+    // PSModulePath is a reliable PowerShell-specific environment variable
+    if (process.env.PSModulePath || process.platform === 'win32') {
+        const comspec = process.env.COMSPEC?.toLowerCase();
+        // If PSModulePath exists, we're definitely in PowerShell
+        if (process.env.PSModulePath) {
+            return { shell: 'powershell', detected: 'powershell' };
+        }
+        // On Windows without PSModulePath, we might be in cmd.exe
+        if (comspec?.includes('cmd.exe')) {
+            return { shell: undefined, detected: 'cmd.exe' };
+        }
+    }
+    return { shell: undefined, detected: undefined };
+}
+//# sourceMappingURL=shell-detection.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -32,6 +32,7 @@
   "files": [
     "dist",
     "bin",
+    "scripts/postinstall.js",
     "!dist/**/*.test.js",
     "!dist/**/__tests__",
     "!dist/**/*.map"
@@ -62,6 +63,8 @@
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
+    "postinstall": "node scripts/postinstall.js",
     "check:pack-version": "node scripts/pack-version-check.mjs",
     "release": "pnpm run release:ci",
     "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",

package/scripts/postinstall.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script for auto-installing shell completions
+ *
+ * This script runs automatically after npm install unless:
+ * - CI=true environment variable is set
+ * - OPENSPEC_NO_COMPLETIONS=1 environment variable is set
+ * - dist/ directory doesn't exist (dev setup scenario)
+ *
+ * The script never fails npm install - all errors are caught and handled gracefully.
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Check if we should skip installation
+ */
+function shouldSkipInstallation() {
+  // Skip in CI environments
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    return { skip: true, reason: 'CI environment detected' };
+  }
+
+  // Skip if user opted out
+  if (process.env.OPENSPEC_NO_COMPLETIONS === '1') {
+    return { skip: true, reason: 'OPENSPEC_NO_COMPLETIONS=1 set' };
+  }
+
+  return { skip: false };
+}
+
+/**
+ * Check if dist/ directory exists
+ */
+async function distExists() {
+  const distPath = path.join(__dirname, '..', 'dist');
+  try {
+    const stat = await fs.stat(distPath);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect the user's shell
+ */
+async function detectShell() {
+  try {
+    const { detectShell } = await import('../dist/utils/shell-detection.js');
+    const result = detectShell();
+    return result.shell;
+  } catch (error) {
+    // Fail silently if detection module doesn't exist
+    return undefined;
+  }
+}
+
+/**
+ * Install completions for the detected shell
+ */
+async function installCompletions(shell) {
+  try {
+    const { CompletionFactory } = await import('../dist/core/completions/factory.js');
+    const { COMMAND_REGISTRY } = await import('../dist/core/completions/command-registry.js');
+
+    // Check if shell is supported
+    if (!CompletionFactory.isSupported(shell)) {
+      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+      return;
+    }
+
+    // Generate completion script
+    const generator = CompletionFactory.createGenerator(shell);
+    const script = generator.generate(COMMAND_REGISTRY);
+
+    // Install completion script
+    const installer = CompletionFactory.createInstaller(shell);
+    const result = await installer.install(script);
+
+    if (result.success) {
+      // Show success message based on installation type
+      if (result.isOhMyZsh) {
+        console.log(`✓ Shell completions installed`);
+        console.log(`  Restart shell: exec zsh`);
+      } else if (result.zshrcConfigured) {
+        console.log(`✓ Shell completions installed and configured`);
+        console.log(`  Restart shell: exec zsh`);
+      } else {
+        console.log(`✓ Shell completions installed to ~/.zsh/completions/`);
+        console.log(`  Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath)`);
+        console.log(`  Then: exec zsh`);
+      }
+    } else {
+      // Installation failed, show tip for manual install
+      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+    }
+  } catch (error) {
+    // Fail gracefully - show tip for manual install
+    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+  }
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  try {
+    // Check if we should skip
+    const skipCheck = shouldSkipInstallation();
+    if (skipCheck.skip) {
+      // Silent skip - no output
+      return;
+    }
+
+    // Check if dist/ exists (skip silently if not - expected during dev setup)
+    if (!(await distExists())) {
+      return;
+    }
+
+    // Detect shell
+    const shell = await detectShell();
+    if (!shell) {
+      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+      return;
+    }
+
+    // Install completions
+    await installCompletions(shell);
+  } catch (error) {
+    // Fail gracefully - never break npm install
+    // Show tip for manual install
+    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+  }
+}
+
+// Run main and handle any unhandled errors
+main().catch(() => {
+  // Silent failure - never break npm install
+  process.exit(0);
+});