@fission-ai/openspec 1.8.0 → 1.10.0

package/dist/core/completion-tip.js

@@ -0,0 +1,133 @@
+/**
+ * First-run hint pointing users at opt-in shell completions.
+ *
+ * This hint used to be an npm `postinstall` script. Printing it from the CLI
+ * instead lets the package ship with no install scripts at all, so `npm install`
+ * no longer emits an `allow-scripts` warning. Completions stay opt-in: the tip
+ * only names the command, it never installs anything.
+ *
+ * The tip goes to stderr, never stdout, so it cannot contaminate piped command
+ * output.
+ *
+ * The tip is suppressed when:
+ * - CI is set (any value npm/telemetry would treat as CI)
+ * - OPENSPEC_NO_COMPLETIONS=1
+ * - completions are already installed, or the shell is one the installer would
+ *   reject
+ * - the caller passes `silent` — JSON runs, `openspec completion ...`, and
+ *   non-TTY runs, which are deferred rather than consumed (see `silent`)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getGlobalConfigPath } from './global-config.js';
+import { isCiEnvironment } from '../utils/ci.js';
+import { detectShell } from '../utils/shell-detection.js';
+import { CompletionFactory } from './completions/factory.js';
+export const COMPLETION_TIP_MESSAGE = "Tip: Run 'openspec completion install' for shell completions";
+function isSuppressedByEnv() {
+    // isCiEnvironment, not a CI==='true' string check: providers set CI to "True",
+    // "yes", "on", and the tip should be as quiet in those builds as telemetry is.
+    return isCiEnvironment() || process.env.OPENSPEC_NO_COMPLETIONS === '1';
+}
+/**
+ * Whether the tip is worth showing, once we know it is owed and readable.
+ *
+ * "retire" consumes the tip without printing: the user either already has
+ * completions, or is on a shell `openspec completion install` would refuse.
+ *
+ * Without the installed check the tip tells people to install completions they
+ * installed long ago — including on the run right after `completion install`,
+ * whose own run only defers the tip. An undetected or unsupported shell retires
+ * it too: `completion install` exits 1 for those users, so pointing them at it
+ * is a dead end, and this tip is the only message about completions they would
+ * ever get.
+ *
+ * Not free: detectShell() forks `ps` to read the parent process (except on
+ * Windows), so this costs a spawn plus a stat. It runs only on interactive runs
+ * that still owe the tip, which is normally exactly one — but a config that
+ * cannot be written never records the flag, and then every interactive run pays
+ * it. On any unexpected error we show the tip rather than swallow it.
+ */
+async function decideTip() {
+    try {
+        const { shell } = detectShell();
+        if (!shell) {
+            return 'retire';
+        }
+        return (await CompletionFactory.createInstaller(shell).isInstalled())
+            ? 'retire'
+            : 'show';
+    }
+    catch {
+        return 'show';
+    }
+}
+/**
+ * Read the global config exactly as it sits on disk.
+ *
+ * Deliberately NOT `getGlobalConfig()`: that merges in defaults, and writing the
+ * merged result back would stamp `profile`/`delivery` into a file the user never
+ * set them in. `migrateIfNeeded` treats a raw `profile` as "already migrated",
+ * so that stamp would permanently suppress the one-time profile migration and
+ * cost users their installed workflow skills.
+ *
+ * Returns null when the file exists but cannot be read or parsed — a config we
+ * cannot understand is left strictly alone rather than overwritten.
+ */
+function readRawConfig() {
+    const configPath = getGlobalConfigPath();
+    if (!fs.existsSync(configPath)) {
+        return {};
+    }
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    return parsed;
+}
+/**
+ * Record the flag, re-reading the config first and replacing the file by rename.
+ *
+ * Deciding whether to show the tip costs a `ps` spawn and a stat, and a sibling
+ * `openspec` process can write the same file in that window — on a first run
+ * that is exactly when telemetry mints `anonymousId`. Re-reading here keeps the
+ * write down to this one key, and the rename keeps a reader from ever seeing a
+ * half-written config.
+ */
+function markTipSeen() {
+    const configPath = getGlobalConfigPath();
+    const current = readRawConfig() ?? {};
+    const tempPath = `${configPath}.${process.pid}.tmp`;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(tempPath, JSON.stringify({ ...current, completionTipSeen: true }, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tempPath, configPath);
+}
+/**
+ * Print the completion tip once, the first time the CLI runs.
+ * Never throws — a hint must not break a command.
+ */
+export async function maybeShowCompletionTip(options = {}) {
+    if (isSuppressedByEnv()) {
+        return;
+    }
+    try {
+        const raw = readRawConfig();
+        if (raw === null || raw.completionTipSeen === true) {
+            return;
+        }
+        if (options.silent) {
+            return;
+        }
+        const decision = await decideTip();
+        // Record before printing: if the flag cannot be persisted, staying quiet
+        // beats reprinting the tip on every future run.
+        markTipSeen();
+        if (decision === 'show') {
+            console.error(`\n${COMPLETION_TIP_MESSAGE}`);
+        }
+    }
+    catch {
+        // Silent failure - a hint should never break the CLI.
+    }
+}
+//# sourceMappingURL=completion-tip.js.map

package/dist/core/completions/command-registry.js

@@ -12,6 +12,11 @@ export const COMMAND_REGISTRY = [
                 description: 'Configure AI tools non-interactively (e.g., "all", "none", or comma-separated tool IDs)',
                 takesValue: true,
             },
+            {
+                name: 'language',
+                description: 'Write new OpenSpec artifacts in this language',
+                takesValue: true,
+            },
             {
                 name: 'force',
                 description: 'Auto-cleanup legacy files without prompting',
@@ -97,6 +102,10 @@ export const COMMAND_REGISTRY = [
                 name: 'specs',
                 description: 'Validate all specs',
             },
+            {
+                name: 'archived',
+                description: 'Validate that archived changes have all tasks completed (for pre-commit linting)',
+            },
             COMMON_FLAGS.type,
             COMMON_FLAGS.strict,
             COMMON_FLAGS.jsonValidation,
@@ -226,6 +235,7 @@ export const COMMAND_REGISTRY = [
         description: 'List available workflow schemas with descriptions',
         flags: [
             COMMON_FLAGS.json,
+            COMMON_FLAGS.store,
         ],
     },
     {

package/dist/core/completions/factory.d.ts

@@ -24,6 +24,17 @@ export interface CompletionInstaller {
         success: boolean;
         message: string;
     }>;
+    /**
+     * True when a completion script file is present at the install path.
+     *
+     * Deliberately just the script: bash and PowerShell also need a sourcing
+     * line in the user's profile, and `install()` adds that on a best-effort
+     * basis (it is skipped by OPENSPEC_NO_AUTO_CONFIG=1 or an unwritable
+     * profile, printing manual instructions instead). Someone in that state has
+     * already met the installer, so callers that use this to decide whether to
+     * *advertise* completions should not advertise again.
+     */
+    isInstalled(): Promise<boolean>;
 }
 /**
  * Factory for creating completion generators and installers

package/dist/core/completions/installers/bash-installer.d.ts

@@ -22,6 +22,13 @@ export declare class BashInstaller {
      * @returns Installation path
      */
     getInstallationPath(): Promise<string>;
+    /**
+     * Check if a completion script is currently installed.
+     * Mirrors ZshInstaller.isInstalled so callers can ask any installer.
+     *
+     * @returns true if the completion script exists
+     */
+    isInstalled(): Promise<boolean>;
     /**
      * Backup an existing completion file if it exists
      *

package/dist/core/completions/installers/bash-installer.js

@@ -55,6 +55,21 @@ export class BashInstaller {
         // For user installation, use local directory
         return path.join(localCompletionDir, 'openspec');
     }
+    /**
+     * Check if a completion script is currently installed.
+     * Mirrors ZshInstaller.isInstalled so callers can ask any installer.
+     *
+     * @returns true if the completion script exists
+     */
+    async isInstalled() {
+        try {
+            // stat, not access: a directory at the install path is not a script.
+            return (await fs.stat(await this.getInstallationPath())).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Backup an existing completion file if it exists
      *

package/dist/core/completions/installers/fish-installer.d.ts

@@ -12,6 +12,13 @@ export declare class FishInstaller {
      * @returns Installation path
      */
     getInstallationPath(): string;
+    /**
+     * Check if a completion script is currently installed.
+     * Mirrors ZshInstaller.isInstalled so callers can ask any installer.
+     *
+     * @returns true if the completion script exists
+     */
+    isInstalled(): Promise<boolean>;
     /**
      * Backup an existing completion file if it exists
      *

package/dist/core/completions/installers/fish-installer.js

@@ -19,6 +19,21 @@ export class FishInstaller {
     getInstallationPath() {
         return path.join(this.homeDir, '.config', 'fish', 'completions', 'openspec.fish');
     }
+    /**
+     * Check if a completion script is currently installed.
+     * Mirrors ZshInstaller.isInstalled so callers can ask any installer.
+     *
+     * @returns true if the completion script exists
+     */
+    async isInstalled() {
+        try {
+            // stat, not access: a directory at the install path is not a script.
+            return (await fs.stat(this.getInstallationPath())).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Backup an existing completion file if it exists
      *

package/dist/core/completions/installers/powershell-installer.d.ts

@@ -43,6 +43,13 @@ export declare class PowerShellInstaller {
      * @returns Installation path
      */
     getInstallationPath(): string;
+    /**
+     * Check if a completion script is currently installed.
+     * Mirrors ZshInstaller.isInstalled so callers can ask any installer.
+     *
+     * @returns true if the completion script exists
+     */
+    isInstalled(): Promise<boolean>;
     /**
      * Backup an existing completion file if it exists
      *

package/dist/core/completions/installers/powershell-installer.js

@@ -110,6 +110,21 @@ export class PowerShellInstaller {
         const profileDir = path.dirname(profilePath);
         return path.join(profileDir, 'OpenSpecCompletion.ps1');
     }
+    /**
+     * Check if a completion script is currently installed.
+     * Mirrors ZshInstaller.isInstalled so callers can ask any installer.
+     *
+     * @returns true if the completion script exists
+     */
+    async isInstalled() {
+        try {
+            // stat, not access: a directory at the install path is not a script.
+            return (await fs.stat(this.getInstallationPath())).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Backup an existing completion file if it exists
      *

package/dist/core/config-prompts.js

@@ -9,16 +9,25 @@ export function serializeConfig(config) {
     // Schema (required)
     lines.push(`schema: ${config.schema}`);
     lines.push('');
-    // Context section with comments
-    lines.push('# Project context (optional)');
-    lines.push('# This is shown to AI when creating artifacts.');
-    lines.push('# Add your tech stack, conventions, style guides, domain knowledge, etc.');
-    lines.push('# Example:');
-    lines.push('#   context: |');
-    lines.push('#     Tech stack: TypeScript, React, Node.js');
-    lines.push('#     We use conventional commits');
-    lines.push('#     Domain: e-commerce platform');
-    lines.push('');
+    if (config.context !== undefined) {
+        lines.push('context: |');
+        for (const line of config.context.split('\n')) {
+            lines.push(`  ${line}`);
+        }
+        lines.push('');
+    }
+    else {
+        // Context section with comments
+        lines.push('# Project context (optional)');
+        lines.push('# This is shown to AI when creating artifacts.');
+        lines.push('# Add your tech stack, conventions, style guides, domain knowledge, etc.');
+        lines.push('# Example:');
+        lines.push('#   context: |');
+        lines.push('#     Tech stack: TypeScript, React, Node.js');
+        lines.push('#     We use conventional commits');
+        lines.push('#     Domain: e-commerce platform');
+        lines.push('');
+    }
     // Rules section with comments
     lines.push('# Per-artifact rules (optional)');
     lines.push('# Add custom rules for specific artifacts.');

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

@@ -19,6 +19,7 @@ export declare const GlobalConfigSchema: z.ZodObject<{
     telemetry: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
+    completionTipSeen: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$loose>;
 export type GlobalConfigType = z.infer<typeof GlobalConfigSchema>;
 /**

package/dist/core/config-schema.js

@@ -32,6 +32,8 @@ export const GlobalConfigSchema = z
     })
         .passthrough()
         .optional(),
+    // Runtime-managed (like telemetry.noticeSeen); not user-settable via CLI set.
+    completionTipSeen: z.boolean().optional(),
 })
     .passthrough();
 /**

package/dist/core/config.d.ts

@@ -17,6 +17,7 @@ export interface AIToolOption {
     globalSkillsDir?: string;
     detectionPaths?: string[];
     setupNote?: string;
+    requiresIdeRestart?: boolean;
 }
 export declare const AI_TOOLS: AIToolOption[];
 /**

package/dist/core/config.js

@@ -18,41 +18,43 @@ export const OPENSPEC_MARKERS = {
     end: '<!-- OPENSPEC:END -->'
 };
 export const AI_TOOLS = [
-    { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq' },
-    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agent' },
+    { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq', requiresIdeRestart: true },
+    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agent', requiresIdeRestart: true },
     { name: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie', skillsDir: '.augment' },
     { name: 'Bob Shell', value: 'bob', available: true, successLabel: 'Bob Shell', skillsDir: '.bob' },
     { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code', skillsDir: '.claude' },
-    { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline', skillsDir: '.cline' },
+    { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline', skillsDir: '.cline', requiresIdeRestart: true },
+    { name: 'Command Code', value: 'command-code', available: true, successLabel: 'Command Code', skillsDir: '.commandcode' },
     { name: 'CodeArts', value: 'codeartsagent', available: true, successLabel: 'CodeArts', skillsDir: '.codeartsdoer' },
     { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex', skillsDir: '.agents', legacySkillsDirs: ['.codex'], detectionPaths: ['.agents/skills', '.codex/skills'] },
-    { name: 'Devin Desktop (formerly Windsurf)', value: 'devin', available: true, successLabel: 'Devin Desktop', skillsDir: '.devin', detectionPaths: ['.devin', '.windsurf'] },
+    { name: 'Devin Desktop (formerly Windsurf)', value: 'devin', available: true, successLabel: 'Devin Desktop', skillsDir: '.devin', detectionPaths: ['.devin', '.windsurf'], requiresIdeRestart: true },
     { name: 'ForgeCode', value: 'forgecode', available: true, successLabel: 'ForgeCode', skillsDir: '.forge' },
     { name: 'CodeBuddy Code (CLI)', value: 'codebuddy', available: true, successLabel: 'CodeBuddy Code', skillsDir: '.codebuddy' },
-    { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)', skillsDir: '.continue' },
-    { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict', skillsDir: '.cospec' },
+    { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)', skillsDir: '.continue', requiresIdeRestart: true },
+    { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict', skillsDir: '.cospec', requiresIdeRestart: true },
     { name: 'Crush', value: 'crush', available: true, successLabel: 'Crush', skillsDir: '.crush' },
-    { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor', skillsDir: '.cursor' },
+    { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor', skillsDir: '.cursor', requiresIdeRestart: true },
     { name: 'Factory Droid', value: 'factory', available: true, successLabel: 'Factory Droid', skillsDir: '.factory' },
     { name: 'Gemini CLI', value: 'gemini', available: true, successLabel: 'Gemini CLI', skillsDir: '.gemini' },
-    { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot', skillsDir: '.github', detectionPaths: ['.github/copilot-instructions.md', '.github/instructions', '.github/workflows/copilot-setup-steps.yml', '.github/prompts', '.github/agents', '.github/skills', '.github/.mcp.json'] },
+    { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot', skillsDir: '.github', detectionPaths: ['.github/copilot-instructions.md', '.github/instructions', '.github/workflows/copilot-setup-steps.yml', '.github/prompts', '.github/agents', '.github/skills', '.github/.mcp.json'], requiresIdeRestart: true },
     { name: 'Hermes Agent', value: 'hermes', available: true, successLabel: 'Hermes Agent', skillsDir: '.hermes', detectionPaths: ['.hermes', 'HERMES.md', '.hermes.md'], setupNote: "Hermes only loads skills from ~/.hermes/skills by default. Add this project's .hermes/skills directory to skills.external_dirs in ~/.hermes/config.yaml so Hermes picks up the generated OpenSpec skills." },
     { name: 'iFlow', value: 'iflow', available: true, successLabel: 'iFlow', skillsDir: '.iflow' },
-    { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie', skillsDir: '.junie' },
-    { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code', skillsDir: '.kilocode' },
+    { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie', skillsDir: '.junie', requiresIdeRestart: true },
+    { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code', skillsDir: '.kilocode', requiresIdeRestart: true },
     { name: 'Kimi Code', value: 'kimi', available: true, successLabel: 'Kimi Code', skillsDir: '.kimi-code', detectionPaths: ['.kimi-code', '.kimi'] },
-    { name: 'Kiro', value: 'kiro', available: true, successLabel: 'Kiro', skillsDir: '.kiro' },
-    { name: 'Lingma', value: 'lingma', available: true, successLabel: 'Lingma', skillsDir: '.lingma' },
+    { name: 'Kiro', value: 'kiro', available: true, successLabel: 'Kiro', skillsDir: '.kiro', requiresIdeRestart: true },
+    { name: 'Lingma', value: 'lingma', available: true, successLabel: 'Lingma', skillsDir: '.lingma', requiresIdeRestart: true },
     { name: 'MiniMax Code', value: 'minimax-code', available: true, successLabel: 'MiniMax Code', globalSkillsDir: '.minimax' },
     { name: 'Mistral Vibe', value: 'vibe', available: true, successLabel: 'Mistral Vibe', skillsDir: '.vibe' },
     { name: 'Oh My Pi', value: 'oh-my-pi', available: true, successLabel: 'Oh My Pi', skillsDir: '.omp' },
     { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode', skillsDir: '.opencode' },
     { name: 'Pi', value: 'pi', available: true, successLabel: 'Pi', skillsDir: '.pi' },
-    { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder', skillsDir: '.qoder' },
+    { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder', skillsDir: '.qoder', requiresIdeRestart: true },
     { name: 'Qwen Code', value: 'qwen', available: true, successLabel: 'Qwen Code', skillsDir: '.qwen' },
     { name: 'Rovo Dev CLI', value: 'rovodev', available: true, successLabel: 'Rovo Dev CLI', skillsDir: '.rovodev', detectionPaths: ['.rovodev/skills', '.rovodev'] },
-    { name: 'Zoo Code', value: 'roocode', available: true, successLabel: 'Zoo Code', skillsDir: '.roo' },
-    { name: 'Trae', value: 'trae', available: true, successLabel: 'Trae', skillsDir: '.trae' },
+    { name: 'Zoo Code', value: 'roocode', available: true, successLabel: 'Zoo Code', skillsDir: '.roo', requiresIdeRestart: true },
+    { name: 'Trae', value: 'trae', available: true, successLabel: 'Trae', skillsDir: '.trae', requiresIdeRestart: true },
+    { name: 'Zed Agent', value: 'zed', available: true, successLabel: 'Zed Agent', skillsDir: '.agents', detectionPaths: ['.zed', '.agents/skills'] },
     { name: 'ZCode', value: 'zcode', available: true, successLabel: 'ZCode', skillsDir: '.zcode' },
     // Vendor-neutral target for assistants that read the shared `.agents` root.
     // Detection keys off `.agents/skills` rather than the bare root: frameworks use

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

@@ -26,6 +26,8 @@ export interface GlobalConfig {
     openers?: unknown;
     /** Anonymous usage analytics settings and identity. */
     telemetry?: TelemetryConfig;
+    /** Whether the first-run shell-completions tip has been shown. */
+    completionTipSeen?: boolean;
 }
 /**
  * Gets the global configuration directory path following XDG Base Directory Specification.

package/dist/core/init.d.ts

@@ -6,6 +6,7 @@
  */
 type InitCommandOptions = {
     tools?: string;
+    language?: string;
     force?: boolean;
     interactive?: boolean;
     profile?: string;
@@ -20,6 +21,7 @@ type InitCommandOptions = {
 };
 export declare class InitCommand {
     private readonly toolsArg?;
+    private readonly language?;
     private readonly force;
     private readonly interactiveOption?;
     private readonly profileOverride?;
@@ -85,6 +87,9 @@ export declare class InitCommand {
      * @returns Created, refreshed, and failed tools plus removed artifact counts
      */
     private generateSkillsAndCommands;
+    private normalizeLanguage;
+    private languageContext;
+    private assertLanguageCanBeApplied;
     private createConfig;
     private displaySuccessMessage;
     private startSpinner;