@fission-ai/openspec 1.6.0 → 1.7.0

package/dist/core/legacy-cleanup.js

@@ -2,6 +2,8 @@
  * Legacy cleanup module for detecting and removing OpenSpec artifacts
  * from previous init versions during the migration to the skill-based workflow.
  */
+import path from 'path';
+import os from 'os';
 import { promises as fs } from 'fs';
 import chalk from 'chalk';
 import { FileSystemUtils, removeMarkerBlock as removeMarkerBlockUtil } from '../utils/file-system.js';
@@ -36,7 +38,10 @@ export const LEGACY_SLASH_COMMAND_PATHS = {
     'costrict': { type: 'directory', path: '.cospec/openspec/commands' },
     // File-based: individual openspec-*.md files in a commands/workflows/prompts folder
     'cursor': { type: 'files', pattern: '.cursor/commands/openspec-*.md' },
-    'windsurf': { type: 'files', pattern: '.windsurf/workflows/openspec-*.md' },
+    // Keyed by the tool id these map back to, so the pre-opsx Windsurf files
+    // belong to `devin` — the id Windsurf became. Only `.windsurf/` is listed:
+    // `.devin/` postdates the opsx rename and never held `openspec-*` files.
+    'devin': { type: 'files', pattern: '.windsurf/workflows/openspec-*.md' },
     'kilocode': { type: 'files', pattern: '.kilocode/workflows/openspec-*.md' },
     'kiro': { type: 'files', pattern: '.kiro/prompts/openspec-*.prompt.md' },
     'github-copilot': { type: 'files', pattern: '.github/prompts/openspec-*.prompt.md' },
@@ -50,9 +55,83 @@ export const LEGACY_SLASH_COMMAND_PATHS = {
     'antigravity': { type: 'files', pattern: '.agent/workflows/openspec-*.md' },
     'iflow': { type: 'files', pattern: '.iflow/commands/openspec-*.md' },
     'junie': { type: 'files', pattern: ['.junie/commands/opsx-*.md', '.junie/commands/openspec-*.md'] },
-    'qwen': { type: 'files', pattern: '.qwen/commands/openspec-*.toml' },
+    'qwen': { type: 'files', pattern: ['.qwen/commands/opsx-*.toml', '.qwen/commands/openspec-*.toml'] },
     'codex': { type: 'files', pattern: '.codex/prompts/openspec-*.md' },
 };
+/**
+ * Final OpenSpec-managed global Codex prompt filenames mapped to the workflows
+ * they represented before Codex moved to skills-only delivery.
+ */
+const LEGACY_GLOBAL_CODEX_WORKFLOWS = {
+    'opsx-propose.md': ['propose'],
+    'opsx-explore.md': ['explore'],
+    'opsx-new.md': ['new'],
+    'opsx-continue.md': ['continue'],
+    'opsx-apply.md': ['apply'],
+    'opsx-update.md': ['update'],
+    'opsx-ff.md': ['ff'],
+    'opsx-sync.md': ['sync'],
+    'opsx-archive.md': ['archive'],
+    'opsx-bulk-archive.md': ['bulk-archive'],
+    'opsx-verify.md': ['verify'],
+    'opsx-onboard.md': ['onboard'],
+};
+/**
+ * Global legacy prompt locations that live outside the project tree and require
+ * allowlisted matching instead of broad glob-based cleanup.
+ */
+export const LEGACY_GLOBAL_SLASH_COMMAND_PATHS = {
+    'codex': {
+        managedFileNames: Object.keys(LEGACY_GLOBAL_CODEX_WORKFLOWS),
+        workflowIdsByFileName: LEGACY_GLOBAL_CODEX_WORKFLOWS,
+        resolvePromptDir: getCodexPromptDir,
+        replacementLabel: 'Codex skills',
+    },
+};
+// Resolve the Codex global prompts directory, respecting CODEX_HOME if set.
+export function getCodexPromptDir() {
+    const envHome = process.env.CODEX_HOME?.trim();
+    const codexHome = envHome ? envHome : path.join(os.homedir(), '.codex');
+    return path.join(path.resolve(codexHome), 'prompts');
+}
+// Convert a simple glob pattern (only * wildcards) into an anchored RegExp.
+function globToRegex(pattern) {
+    const regexPattern = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '.*');
+    return new RegExp(`^${regexPattern}$`);
+}
+// Normalize Windows backslashes to forward slashes for cross-platform path matching.
+function normalizePathForMatch(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+/**
+ * Classifies a global Codex prompt path as OpenSpec-managed only when it matches
+ * the explicit legacy allowlist for the resolved prompt home.
+ */
+function getManagedGlobalLegacyPromptMetadata(filePath) {
+    if (!path.isAbsolute(filePath)) {
+        return undefined;
+    }
+    const resolvedPath = path.resolve(filePath);
+    for (const [toolId, pattern] of Object.entries(LEGACY_GLOBAL_SLASH_COMMAND_PATHS)) {
+        const promptDir = path.resolve(pattern.resolvePromptDir());
+        if (path.dirname(resolvedPath) !== promptDir) {
+            continue;
+        }
+        const managedFileName = path.basename(resolvedPath);
+        if (pattern.managedFileNames.includes(managedFileName)) {
+            return {
+                path: resolvedPath,
+                toolId,
+                managedFileName,
+                workflowIds: pattern.workflowIdsByFileName?.[managedFileName] ?? [],
+                replacementLabel: pattern.replacementLabel,
+            };
+        }
+    }
+    return undefined;
+}
 /**
  * Detects all legacy OpenSpec artifacts in a project.
  *
@@ -65,6 +144,8 @@ export async function detectLegacyArtifacts(projectPath) {
         configFilesToUpdate: [],
         slashCommandDirs: [],
         slashCommandFiles: [],
+        globalSlashCommandFiles: [],
+        globalSlashCommandDetails: [],
         hasOpenspecAgents: false,
         hasProjectMd: false,
         hasRootAgentsWithMarkers: false,
@@ -77,7 +158,10 @@ export async function detectLegacyArtifacts(projectPath) {
     // Detect legacy slash commands
     const slashResult = await detectLegacySlashCommands(projectPath);
     result.slashCommandDirs = slashResult.directories;
-    result.slashCommandFiles = slashResult.files;
+    result.slashCommandFiles = [...new Set(slashResult.files)];
+    // Detect legacy global slash commands
+    result.globalSlashCommandDetails = await detectLegacyGlobalPromptFiles();
+    result.globalSlashCommandFiles = result.globalSlashCommandDetails.map((detail) => detail.path);
     // Detect legacy structure files
     const structureResult = await detectLegacyStructureFiles(projectPath);
     result.hasOpenspecAgents = structureResult.hasOpenspecAgents;
@@ -88,6 +172,7 @@ export async function detectLegacyArtifacts(projectPath) {
         result.configFiles.length > 0 ||
             result.slashCommandDirs.length > 0 ||
             result.slashCommandFiles.length > 0 ||
+            result.globalSlashCommandFiles.length > 0 ||
             result.hasOpenspecAgents ||
             result.hasRootAgentsWithMarkers ||
             result.hasProjectMd;
@@ -125,7 +210,7 @@ export async function detectLegacyConfigFiles(projectPath) {
 export async function detectLegacySlashCommands(projectPath) {
     const directories = [];
     const files = [];
-    for (const [toolId, pattern] of Object.entries(LEGACY_SLASH_COMMAND_PATHS)) {
+    for (const pattern of Object.values(LEGACY_SLASH_COMMAND_PATHS)) {
         if (pattern.type === 'directory' && pattern.path) {
             const dirPath = FileSystemUtils.joinPath(projectPath, pattern.path);
             if (await FileSystemUtils.directoryExists(dirPath)) {
@@ -133,7 +218,6 @@ export async function detectLegacySlashCommands(projectPath) {
             }
         }
         else if (pattern.type === 'files' && pattern.pattern) {
-            // For file-based patterns, check for individual files
             const patterns = Array.isArray(pattern.pattern) ? pattern.pattern : [pattern.pattern];
             for (const p of patterns) {
                 const foundFiles = await findLegacySlashCommandFiles(projectPath, p);
@@ -143,6 +227,37 @@ export async function detectLegacySlashCommands(projectPath) {
     }
     return { directories, files };
 }
+/**
+ * Detects legacy global slash command files.
+ *
+ * @returns Object with individual files found
+ */
+/**
+ * Scans the resolved global Codex prompt directories and returns only the
+ * allowlisted OpenSpec-managed legacy prompt files.
+ */
+async function detectLegacyGlobalPromptFiles() {
+    const foundFiles = [];
+    for (const pattern of Object.values(LEGACY_GLOBAL_SLASH_COMMAND_PATHS)) {
+        const promptDir = pattern.resolvePromptDir();
+        try {
+            const entries = await fs.readdir(promptDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isFile() && pattern.managedFileNames.includes(entry.name)) {
+                    const fullPath = path.join(promptDir, entry.name);
+                    const match = getManagedGlobalLegacyPromptMetadata(fullPath);
+                    if (match) {
+                        foundFiles.push(match);
+                    }
+                }
+            }
+        }
+        catch {
+            // Directory does not exist or cannot be read.
+        }
+    }
+    return foundFiles;
+}
 /**
  * Finds legacy slash command files matching a glob pattern.
  *
@@ -165,14 +280,7 @@ async function findLegacySlashCommandFiles(projectPath, pattern) {
     }
     try {
         const entries = await fs.readdir(dirPath);
-        // Convert glob pattern to regex
-        // openspec-*.md -> /^openspec-.*\.md$/
-        // openspec-*.prompt.md -> /^openspec-.*\.prompt\.md$/
-        // openspec-*.toml -> /^openspec-.*\.toml$/
-        const regexPattern = filePart
-            .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape regex special chars except *
-            .replace(/\*/g, '.*'); // Replace * with .*
-        const regex = new RegExp(`^${regexPattern}$`);
+        const regex = globToRegex(filePart);
         for (const entry of entries) {
             if (regex.test(entry)) {
                 // Use forward slashes for consistency in relative paths (cross-platform)
@@ -257,6 +365,7 @@ export function removeMarkerBlock(content) {
 export async function cleanupLegacyArtifacts(projectPath, detection) {
     const result = {
         deletedFiles: [],
+        deletedFileReplacementLabels: {},
         modifiedFiles: [],
         deletedDirs: [],
         projectMdNeedsMigration: detection.hasProjectMd,
@@ -299,6 +408,25 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
             result.errors.push(`Failed to delete ${filePath}: ${error.message}`);
         }
     }
+    // Delete managed global slash command files (these are 100% OpenSpec-managed)
+    const globalPromptMatchesByPath = new Map(getLegacyGlobalPromptMatches(detection).map((prompt) => [prompt.path, prompt]));
+    for (const filePath of detection.globalSlashCommandFiles) {
+        if (!getManagedGlobalLegacyPromptMetadata(filePath)) {
+            result.errors.push(`Skipped unmanaged global prompt ${filePath}`);
+            continue;
+        }
+        try {
+            await fs.unlink(filePath);
+            result.deletedFiles.push(filePath);
+            const promptMatch = globalPromptMatchesByPath.get(filePath);
+            if (promptMatch?.replacementLabel) {
+                result.deletedFileReplacementLabels[filePath] = promptMatch.replacementLabel;
+            }
+        }
+        catch (error) {
+            result.errors.push(`Failed to delete ${filePath}: ${error.message}`);
+        }
+    }
     // Delete openspec/AGENTS.md (this is inside openspec/, it's OpenSpec-managed)
     if (detection.hasOpenspecAgents) {
         const agentsPath = FileSystemUtils.joinPath(projectPath, 'openspec', 'AGENTS.md');
@@ -328,10 +456,15 @@ export function formatCleanupSummary(result) {
     if (result.deletedFiles.length > 0 || result.deletedDirs.length > 0 || result.modifiedFiles.length > 0) {
         lines.push('Cleaned up legacy files:');
         for (const file of result.deletedFiles) {
-            lines.push(`  ✓ Removed ${file}`);
+            const replacementLabel = result.deletedFileReplacementLabels?.[file]
+                ?? getManagedGlobalLegacyPromptMetadata(file)?.replacementLabel;
+            const replacement = replacementLabel
+                ? ` (replaced by ${replacementLabel})`
+                : '';
+            lines.push(`  ✓ Removed ${file}${replacement}`);
         }
         for (const dir of result.deletedDirs) {
-            lines.push(`  ✓ Removed ${dir}/ (replaced by /opsx:*)`);
+            lines.push(`  ✓ Removed ${dir}/ (replaced by OpenSpec skills and commands)`);
         }
         for (const file of result.modifiedFiles) {
             lines.push(`  ✓ Removed OpenSpec markers from ${file}`);
@@ -374,6 +507,13 @@ function buildRemovalsList(detection) {
     for (const file of detection.slashCommandFiles) {
         removals.push({ path: file, explanation: 'replaced by skills/' });
     }
+    // Managed global slash command files
+    for (const prompt of getLegacyGlobalPromptMatches(detection)) {
+        const explanation = prompt.toolId
+            ? `replaced by .${prompt.toolId}/skills/`
+            : 'replaced by skills/';
+        removals.push({ path: prompt.path, explanation });
+    }
     // openspec/AGENTS.md (inside openspec/, it's OpenSpec-managed)
     if (detection.hasOpenspecAgents) {
         removals.push({ path: 'openspec/AGENTS.md', explanation: 'obsolete workflow file' });
@@ -445,6 +585,24 @@ export function formatDetectionSummary(detection) {
     }
     return lines.join('\n');
 }
+/**
+ * Generates a summary for managed global prompt files whose cleanup must wait
+ * until replacement skills are installed.
+ */
+export function formatDeferredGlobalPromptSummary(detection) {
+    const deferredPrompts = getLegacyGlobalPromptMatches(detection);
+    if (deferredPrompts.length === 0) {
+        return '';
+    }
+    const lines = [];
+    lines.push(chalk.bold('Deferred global prompts cleanup'));
+    lines.push(chalk.dim('These global prompts will only be removed after matching replacement skills are installed.'));
+    for (const prompt of deferredPrompts) {
+        const toolLabel = prompt.toolId ? `${prompt.toolId}: ` : '';
+        lines.push(`  • ${toolLabel}${prompt.path}`);
+    }
+    return lines.join('\n');
+}
 /**
  * Extract tool IDs from detected legacy artifacts.
  * Uses LEGACY_SLASH_COMMAND_PATHS to map paths back to tool IDs.
@@ -466,18 +624,13 @@ export function getToolsFromLegacyArtifacts(detection) {
     // Match files to tool IDs using glob patterns
     for (const file of detection.slashCommandFiles) {
         // Normalize file path to use forward slashes for consistent matching (Windows compatibility)
-        const normalizedFile = file.replace(/\\/g, '/');
+        const normalizedFile = normalizePathForMatch(file);
         for (const [toolId, pattern] of Object.entries(LEGACY_SLASH_COMMAND_PATHS)) {
             if (pattern.type === 'files' && pattern.pattern) {
-                // Convert glob pattern to regex for matching
-                // e.g., '.cursor/commands/openspec-*.md' -> /^\.cursor\/commands\/openspec-.*\.md$/
                 const patterns = Array.isArray(pattern.pattern) ? pattern.pattern : [pattern.pattern];
                 let matched = false;
                 for (const p of patterns) {
-                    const regexPattern = p
-                        .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape regex special chars except *
-                        .replace(/\*/g, '.*'); // Replace * with .*
-                    const regex = new RegExp(`^${regexPattern}$`);
+                    const regex = globToRegex(p);
                     if (regex.test(normalizedFile)) {
                         tools.add(toolId);
                         matched = true;
@@ -489,8 +642,82 @@ export function getToolsFromLegacyArtifacts(detection) {
             }
         }
     }
+    for (const prompt of getLegacyGlobalPromptMatches(detection)) {
+        tools.add(prompt.toolId);
+    }
     return Array.from(tools);
 }
+/**
+ * Normalizes global Codex prompt matches so callers can rely on workflow-aware
+ * metadata even when older detection results only carry file paths.
+ */
+export function getLegacyGlobalPromptMatches(detection) {
+    if (detection.globalSlashCommandDetails && detection.globalSlashCommandDetails.length > 0) {
+        return detection.globalSlashCommandDetails;
+    }
+    return detection.globalSlashCommandFiles
+        .map((filePath) => getManagedGlobalLegacyPromptMetadata(filePath))
+        .filter((match) => match !== undefined);
+}
+/**
+ * Collects workflow IDs inferred from detected legacy global prompts for a
+ * specific tool.
+ */
+export function getLegacyWorkflowIdsForTool(detection, toolId) {
+    const workflows = new Set();
+    for (const prompt of getLegacyGlobalPromptMatches(detection)) {
+        if (prompt.toolId !== toolId) {
+            continue;
+        }
+        for (const workflowId of prompt.workflowIds) {
+            workflows.add(workflowId);
+        }
+    }
+    return Array.from(workflows);
+}
+function hasLegacyArtifacts(detection) {
+    return (detection.configFiles.length > 0 ||
+        detection.slashCommandDirs.length > 0 ||
+        detection.slashCommandFiles.length > 0 ||
+        detection.globalSlashCommandFiles.length > 0 ||
+        detection.hasOpenspecAgents ||
+        detection.hasRootAgentsWithMarkers ||
+        detection.hasProjectMd);
+}
+/**
+ * Returns a detection snapshot with global Codex prompt cleanup removed so
+ * callers can safely perform the immediate, non-deferred cleanup pass.
+ */
+export function omitGlobalLegacyPromptFiles(detection) {
+    const nextDetection = {
+        ...detection,
+        globalSlashCommandFiles: [],
+        globalSlashCommandDetails: [],
+    };
+    nextDetection.hasLegacyArtifacts = hasLegacyArtifacts(nextDetection);
+    return nextDetection;
+}
+/**
+ * Builds a detection snapshot containing only the selected global Codex prompt
+ * matches for replacement-gated cleanup.
+ */
+export function pickGlobalLegacyPromptFiles(detection, filePaths) {
+    const selectedPaths = new Set(filePaths.map((filePath) => path.resolve(filePath)));
+    const details = getLegacyGlobalPromptMatches(detection)
+        .filter((detail) => selectedPaths.has(path.resolve(detail.path)));
+    return {
+        configFiles: [],
+        configFilesToUpdate: [],
+        slashCommandDirs: [],
+        slashCommandFiles: [],
+        globalSlashCommandFiles: details.map((detail) => detail.path),
+        globalSlashCommandDetails: details,
+        hasOpenspecAgents: false,
+        hasProjectMd: false,
+        hasRootAgentsWithMarkers: false,
+        hasLegacyArtifacts: details.length > 0,
+    };
+}
 /**
  * Generates a migration hint message for project.md.
  * This is shown when project.md exists and needs manual migration to config.yaml.

package/dist/core/list.js

@@ -2,8 +2,8 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progress.js';
 import { readFileSync } from 'fs';
-import { join } from 'path';
 import { MarkdownParser } from './parsers/markdown-parser.js';
+import { discoverSpecFiles } from '../utils/spec-discovery.js';
 function isMissingPathError(error) {
     return (typeof error === 'object' &&
         error !== null &&
@@ -152,9 +152,8 @@ export class ListCommand {
             }
             return;
         }
-        const entries = await fs.readdir(specsDir, { withFileTypes: true });
-        const specDirs = entries.filter(e => e.isDirectory()).map(e => e.name);
-        if (specDirs.length === 0) {
+        const discovered = await discoverSpecFiles(specsDir);
+        if (discovered.length === 0) {
             if (json) {
                 console.log(JSON.stringify({ specs: [], ...(root ? { root } : {}) }, null, 2));
             }
@@ -164,10 +163,9 @@ export class ListCommand {
             return;
         }
         const specs = [];
-        for (const id of specDirs) {
-            const specPath = join(specsDir, id, 'spec.md');
+        for (const { id, specFile } of discovered) {
             try {
-                const content = readFileSync(specPath, 'utf-8');
+                const content = readFileSync(specFile, 'utf-8');
                 const parser = new MarkdownParser(content);
                 const spec = parser.parseSpec(id);
                 specs.push({ id, requirementCount: spec.requirements.length });

package/dist/core/migration.d.ts

@@ -4,7 +4,77 @@
  * One-time migration logic for existing projects when profile system is introduced.
  * Called by both init and update commands before profile resolution.
  */
-import type { AIToolOption } from './config.js';
+import { type AIToolOption } from './config.js';
+export interface LegacyToolRoot {
+    /** Former tool root, e.g. '.kimi' */
+    root: string;
+    /**
+     * Whether leaving this root requires the user's say-so. False when the old
+     * product is gone and its directory is certainly dead. True when the old
+     * location may still be the live one for somebody.
+     */
+    needsConsent: boolean;
+}
+/**
+ * Former tool roots whose OpenSpec-managed content belongs under the tool's
+ * current skillsDir. User files are never touched.
+ */
+export declare const LEGACY_TOOL_ROOTS: Record<string, LegacyToolRoot[]>;
+export interface LegacyToolMigration {
+    toolId: string;
+    /** Legacy tool root, e.g. '.windsurf' */
+    from: string;
+    /** Current tool root, e.g. '.devin' */
+    to: string;
+    /** Skill directories that moved, or would move */
+    skillDirs: number;
+    /** Command files that moved, or would move */
+    commandFiles: number;
+    /**
+     * OpenSpec-managed files left under the legacy root because the copy there
+     * differs from the one that survives — the user edited it, so it is reported
+     * rather than dropped.
+     */
+    keptInPlace: number;
+    /** Whether this move needs the user's consent first */
+    needsConsent: boolean;
+}
+/**
+ * Reports the OpenSpec content sitting under each tool's legacy root, without
+ * moving anything. Callers use this to ask before a move that needs consent.
+ */
+export declare function findLegacyToolMigrations(projectPath: string): LegacyToolMigration[];
+/**
+ * Moves OpenSpec-managed skill directories (openspec-*) and command files
+ * (opsx-*) from a tool's legacy root to its current one. When the destination
+ * already exists the legacy copy is removed instead. Legacy directories are
+ * deleted only when left empty, so user files under the old location — a
+ * hand-written Cascade workflow next to the generated ones — are preserved.
+ *
+ * @param projectPath - Project root
+ * @param toolIds - Restrict the move to these tools; omit to move every tool
+ *        whose legacy root needs no consent
+ */
+export declare function migrateLegacyToolDirs(projectPath: string, toolIds?: string[]): LegacyToolMigration[];
+/**
+ * Summarizes what a migration moved, e.g. "6 skills and 6 commands".
+ */
+export declare function describeLegacyMigration(migration: LegacyToolMigration): string;
+/**
+ * Names OpenSpec-managed files the move deliberately left behind, so a user
+ * who customized one knows there are now two copies to reconcile.
+ */
+export declare function keptInPlaceNotice(migration: LegacyToolMigration): string | undefined;
+/**
+ * Whether a migration has anything to move, as opposed to only files left in
+ * place. Callers use this to avoid offering a move of nothing.
+ */
+export declare function hasMovableContent(migration: LegacyToolMigration): boolean;
+/**
+ * Explains why a consent-gated move is being offered, in the user's terms.
+ * Keyed by tool so the reason is specific rather than a generic "files moved".
+ */
+export declare function legacyMigrationNotice(migration: LegacyToolMigration): string;
 /**
  * Scans installed workflow files across all detected tools and returns
  * the union of installed workflow IDs.