@fission-ai/openspec 0.16.0 → 0.17.0

package/dist/core/config-schema.js

@@ -0,0 +1,200 @@
+import { z } from 'zod';
+/**
+ * Zod schema for global OpenSpec configuration.
+ * Uses passthrough() to preserve unknown fields for forward compatibility.
+ */
+export const GlobalConfigSchema = z
+    .object({
+    featureFlags: z
+        .record(z.string(), z.boolean())
+        .optional()
+        .default({}),
+})
+    .passthrough();
+/**
+ * Default configuration values.
+ */
+export const DEFAULT_CONFIG = {
+    featureFlags: {},
+};
+const KNOWN_TOP_LEVEL_KEYS = new Set(Object.keys(DEFAULT_CONFIG));
+/**
+ * Validate a config key path for CLI set operations.
+ * Unknown top-level keys are rejected unless explicitly allowed by the caller.
+ */
+export function validateConfigKeyPath(path) {
+    const rawKeys = path.split('.');
+    if (rawKeys.length === 0 || rawKeys.some((key) => key.trim() === '')) {
+        return { valid: false, reason: 'Key path must not be empty' };
+    }
+    const rootKey = rawKeys[0];
+    if (!KNOWN_TOP_LEVEL_KEYS.has(rootKey)) {
+        return { valid: false, reason: `Unknown top-level key "${rootKey}"` };
+    }
+    if (rootKey === 'featureFlags') {
+        if (rawKeys.length > 2) {
+            return { valid: false, reason: 'featureFlags values are booleans and do not support nested keys' };
+        }
+        return { valid: true };
+    }
+    if (rawKeys.length > 1) {
+        return { valid: false, reason: `"${rootKey}" does not support nested keys` };
+    }
+    return { valid: true };
+}
+/**
+ * Get a nested value from an object using dot notation.
+ *
+ * @param obj - The object to access
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @returns The value at the path, or undefined if not found
+ */
+export function getNestedValue(obj, path) {
+    const keys = path.split('.');
+    let current = obj;
+    for (const key of keys) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Set a nested value in an object using dot notation.
+ * Creates intermediate objects as needed.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @param value - The value to set
+ */
+export function setNestedValue(obj, path, value) {
+    const keys = path.split('.');
+    let current = obj;
+    for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i];
+        if (current[key] === undefined || current[key] === null || typeof current[key] !== 'object') {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    const lastKey = keys[keys.length - 1];
+    current[lastKey] = value;
+}
+/**
+ * Delete a nested value from an object using dot notation.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @returns true if the key existed and was deleted, false otherwise
+ */
+export function deleteNestedValue(obj, path) {
+    const keys = path.split('.');
+    let current = obj;
+    for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i];
+        if (current[key] === undefined || current[key] === null || typeof current[key] !== 'object') {
+            return false;
+        }
+        current = current[key];
+    }
+    const lastKey = keys[keys.length - 1];
+    if (lastKey in current) {
+        delete current[lastKey];
+        return true;
+    }
+    return false;
+}
+/**
+ * Coerce a string value to its appropriate type.
+ * - "true" / "false" -> boolean
+ * - Numeric strings -> number
+ * - Everything else -> string
+ *
+ * @param value - The string value to coerce
+ * @param forceString - If true, always return the value as a string
+ * @returns The coerced value
+ */
+export function coerceValue(value, forceString = false) {
+    if (forceString) {
+        return value;
+    }
+    // Boolean coercion
+    if (value === 'true') {
+        return true;
+    }
+    if (value === 'false') {
+        return false;
+    }
+    // Number coercion - must be a valid finite number
+    const num = Number(value);
+    if (!isNaN(num) && isFinite(num) && value.trim() !== '') {
+        return num;
+    }
+    return value;
+}
+/**
+ * Format a value for YAML-like display.
+ *
+ * @param value - The value to format
+ * @param indent - Current indentation level
+ * @returns Formatted string
+ */
+export function formatValueYaml(value, indent = 0) {
+    const indentStr = '  '.repeat(indent);
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+    if (typeof value === 'boolean' || typeof value === 'number') {
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return '[]';
+        }
+        return value.map((item) => `${indentStr}- ${formatValueYaml(item, indent + 1)}`).join('\n');
+    }
+    if (typeof value === 'object') {
+        const entries = Object.entries(value);
+        if (entries.length === 0) {
+            return '{}';
+        }
+        return entries
+            .map(([key, val]) => {
+            const formattedVal = formatValueYaml(val, indent + 1);
+            if (typeof val === 'object' && val !== null && Object.keys(val).length > 0) {
+                return `${indentStr}${key}:\n${formattedVal}`;
+            }
+            return `${indentStr}${key}: ${formattedVal}`;
+        })
+            .join('\n');
+    }
+    return String(value);
+}
+/**
+ * Validate a configuration object against the schema.
+ *
+ * @param config - The configuration to validate
+ * @returns Validation result with success status and optional error message
+ */
+export function validateConfig(config) {
+    try {
+        GlobalConfigSchema.parse(config);
+        return { success: true };
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const zodError = error;
+            const messages = zodError.issues.map((e) => `${e.path.join('.')}: ${e.message}`);
+            return { success: false, error: messages.join('; ') };
+        }
+        return { success: false, error: 'Unknown validation error' };
+    }
+}
+//# sourceMappingURL=config-schema.js.map

package/dist/core/configurators/slash/opencode.js

@@ -8,7 +8,6 @@ const FILE_PATHS = {
 };
 const FRONTMATTER = {
     proposal: `---
-agent: build
 description: Scaffold a new OpenSpec change and validate strictly.
 ---
 The user has requested the following change proposal. Use the openspec instructions to create their change proposal.
@@ -17,7 +16,6 @@ The user has requested the following change proposal. Use the openspec instructi
 </UserRequest>
 `,
     apply: `---
-agent: build
 description: Implement an approved OpenSpec change and keep tasks in sync.
 ---
 The user has requested to implement the following change proposal. Find the change proposal and follow the instructions below. If you're not sure or if ambiguous, ask for clarification from the user.
@@ -26,7 +24,6 @@ The user has requested to implement the following change proposal. Find the chan
 </UserRequest>
 `,
     archive: `---
-agent: build
 description: Archive a deployed OpenSpec change and update specs.
 ---
 <ChangeId>

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/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.16.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);
+});