@superkou/openspec 1.4.1

package/dist/core/update.js

@@ -0,0 +1,557 @@
+/**
+ * Update Command
+ *
+ * Refreshes OpenSpec skills and commands for configured tools.
+ * Supports profile-aware updates, delivery changes, migration, and smart update detection.
+ */
+import path from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import * as fs from 'fs';
+import { createRequire } from 'module';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { transformToHyphenCommands } from '../utils/command-references.js';
+import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
+import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
+import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, } from './shared/index.js';
+import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatCleanupSummary, formatDetectionSummary, getToolsFromLegacyArtifacts, } from './legacy-cleanup.js';
+import { isInteractive } from '../utils/interactive.js';
+import { getGlobalConfig } from './global-config.js';
+import { getProfileWorkflows, ALL_WORKFLOWS } from './profiles.js';
+import { getAvailableTools } from './available-tools.js';
+import { WORKFLOW_TO_SKILL_DIR, getCommandConfiguredTools, getConfiguredToolsForProfileSync, getToolsNeedingProfileSync, } from './profile-sync-drift.js';
+import { scanInstalledWorkflows as scanInstalledWorkflowsShared, migrateIfNeeded as migrateIfNeededShared, } from './migration.js';
+const require = createRequire(import.meta.url);
+const { version: OPENSPEC_VERSION } = require('../../package.json');
+const OLD_CORE_WORKFLOWS = ['propose', 'explore', 'apply', 'archive'];
+/**
+ * Scans installed workflow artifacts (skills and managed commands) across all configured tools.
+ * Returns the union of detected workflow IDs that match ALL_WORKFLOWS.
+ *
+ * Wrapper around the shared migration module's scanInstalledWorkflows that accepts tool IDs.
+ */
+export function scanInstalledWorkflows(projectPath, toolIds) {
+    const tools = toolIds
+        .map((id) => AI_TOOLS.find((t) => t.value === id))
+        .filter((t) => t != null);
+    return scanInstalledWorkflowsShared(projectPath, tools);
+}
+export class UpdateCommand {
+    force;
+    constructor(options = {}) {
+        this.force = options.force ?? false;
+    }
+    async execute(projectPath) {
+        const resolvedProjectPath = path.resolve(projectPath);
+        const openspecPath = path.join(resolvedProjectPath, OPENSPEC_DIR_NAME);
+        // 1. Check openspec directory exists
+        if (!await FileSystemUtils.directoryExists(openspecPath)) {
+            throw new Error(`No OpenSpec directory found. Run 'openspec init' first.`);
+        }
+        // 2. Perform one-time migration if needed before any legacy upgrade generation.
+        // Use detected tool directories to preserve existing opsx skills/commands.
+        const detectedTools = getAvailableTools(resolvedProjectPath);
+        migrateIfNeededShared(resolvedProjectPath, detectedTools);
+        // 3. Read global config for profile/delivery
+        const globalConfig = getGlobalConfig();
+        const profile = globalConfig.profile ?? 'core';
+        const delivery = globalConfig.delivery ?? 'both';
+        const profileWorkflows = getProfileWorkflows(profile, globalConfig.workflows);
+        const desiredWorkflows = profileWorkflows.filter((workflow) => ALL_WORKFLOWS.includes(workflow));
+        const shouldGenerateSkills = delivery !== 'commands';
+        const shouldGenerateCommands = delivery !== 'skills';
+        // 4. Detect and handle legacy artifacts + upgrade legacy tools using effective config
+        const newlyConfiguredTools = await this.handleLegacyCleanup(resolvedProjectPath, desiredWorkflows, delivery);
+        // 5. Find configured tools
+        const configuredTools = getConfiguredToolsForProfileSync(resolvedProjectPath);
+        if (configuredTools.length === 0 && newlyConfiguredTools.length === 0) {
+            console.log(chalk.yellow('未发现已配置的工具。'));
+            console.log(chalk.dim('运行 "openspec init" 来设置工具。'));
+            return;
+        }
+        // 6. Check version status for all configured tools
+        const commandConfiguredTools = getCommandConfiguredTools(resolvedProjectPath);
+        const commandConfiguredSet = new Set(commandConfiguredTools);
+        const toolStatuses = configuredTools.map((toolId) => {
+            const status = getToolVersionStatus(resolvedProjectPath, toolId, OPENSPEC_VERSION);
+            if (!status.configured && commandConfiguredSet.has(toolId)) {
+                return { ...status, configured: true };
+            }
+            return status;
+        });
+        const statusByTool = new Map(toolStatuses.map((status) => [status.toolId, status]));
+        // 7. Smart update detection
+        const toolsNeedingVersionUpdate = toolStatuses
+            .filter((s) => s.needsUpdate)
+            .map((s) => s.toolId);
+        const toolsNeedingConfigSync = getToolsNeedingProfileSync(resolvedProjectPath, desiredWorkflows, delivery, configuredTools);
+        const toolsToUpdateSet = new Set([
+            ...toolsNeedingVersionUpdate,
+            ...toolsNeedingConfigSync,
+        ]);
+        const toolsUpToDate = toolStatuses.filter((s) => !toolsToUpdateSet.has(s.toolId));
+        if (!this.force && toolsToUpdateSet.size === 0) {
+            // All tools are up to date
+            this.displayUpToDateMessage(toolStatuses);
+            // Still check for new tool directories and extra workflows
+            this.detectNewTools(resolvedProjectPath, configuredTools);
+            this.displayExtraWorkflowsNote(resolvedProjectPath, configuredTools, desiredWorkflows);
+            this.displayOldCoreCustomProfileNote(profile, globalConfig.workflows);
+            return;
+        }
+        // 8. Display update plan
+        if (this.force) {
+            console.log(`正在强制更新 ${configuredTools.length} 个工具：${configuredTools.join(', ')}`);
+        }
+        else {
+            this.displayUpdatePlan([...toolsToUpdateSet], statusByTool, toolsUpToDate);
+        }
+        console.log();
+        // 9. Determine what to generate based on delivery
+        const skillTemplates = shouldGenerateSkills ? getSkillTemplates(desiredWorkflows) : [];
+        const commandContents = shouldGenerateCommands ? getCommandContents(desiredWorkflows) : [];
+        // 10. Update tools (all if force, otherwise only those needing update)
+        const toolsToUpdate = this.force ? configuredTools : [...toolsToUpdateSet];
+        const updatedTools = [];
+        const failedTools = [];
+        let removedCommandCount = 0;
+        let removedSkillCount = 0;
+        let removedDeselectedCommandCount = 0;
+        let removedDeselectedSkillCount = 0;
+        for (const toolId of toolsToUpdate) {
+            const tool = AI_TOOLS.find((t) => t.value === toolId);
+            if (!tool?.skillsDir)
+                continue;
+            const spinner = ora(`正在更新 ${tool.name}...`).start();
+            try {
+                const skillsDir = path.join(resolvedProjectPath, tool.skillsDir, 'skills');
+                // Generate skill files if delivery includes skills
+                if (shouldGenerateSkills) {
+                    for (const { template, dirName } of skillTemplates) {
+                        const skillDir = path.join(skillsDir, dirName);
+                        const skillFile = path.join(skillDir, 'SKILL.md');
+                        // Use hyphen-based command references for OpenCode
+                        const transformer = (tool.value === 'opencode' || tool.value === 'pi') ? transformToHyphenCommands : undefined;
+                        const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
+                        await FileSystemUtils.writeFile(skillFile, skillContent);
+                    }
+                    removedDeselectedSkillCount += await this.removeUnselectedSkillDirs(skillsDir, desiredWorkflows);
+                }
+                // Delete skill directories if delivery is commands-only
+                if (!shouldGenerateSkills) {
+                    removedSkillCount += await this.removeSkillDirs(skillsDir);
+                }
+                // Generate commands if delivery includes commands
+                if (shouldGenerateCommands) {
+                    const adapter = CommandAdapterRegistry.get(tool.value);
+                    if (adapter) {
+                        const generatedCommands = generateCommands(commandContents, adapter);
+                        for (const cmd of generatedCommands) {
+                            const commandFile = path.isAbsolute(cmd.path) ? cmd.path : path.join(resolvedProjectPath, cmd.path);
+                            await FileSystemUtils.writeFile(commandFile, cmd.fileContent);
+                        }
+                        removedDeselectedCommandCount += await this.removeUnselectedCommandFiles(resolvedProjectPath, toolId, desiredWorkflows);
+                    }
+                }
+                // Delete command files if delivery is skills-only
+                if (!shouldGenerateCommands) {
+                    removedCommandCount += await this.removeCommandFiles(resolvedProjectPath, toolId);
+                }
+                spinner.succeed(`已更新 ${tool.name}`);
+                updatedTools.push(tool.name);
+            }
+            catch (error) {
+                spinner.fail(`更新 ${tool.name} 失败`);
+                failedTools.push({
+                    name: tool.name,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+        // 11. Summary
+        console.log();
+        if (updatedTools.length > 0) {
+            console.log(chalk.green(`✓ 已更新：${updatedTools.join(', ')}（v${OPENSPEC_VERSION}）`));
+        }
+        if (failedTools.length > 0) {
+            console.log(chalk.red(`✗ 失败：${failedTools.map(f => `${f.name}（${f.error}）`).join(', ')}`));
+        }
+        if (removedCommandCount > 0) {
+            console.log(chalk.dim(`已移除：${removedCommandCount} 个命令文件（delivery 为 skills）`));
+        }
+        if (removedSkillCount > 0) {
+            console.log(chalk.dim(`已移除：${removedSkillCount} 个技能目录（delivery 为 commands）`));
+        }
+        if (removedDeselectedCommandCount > 0) {
+            console.log(chalk.dim(`已移除：${removedDeselectedCommandCount} 个命令文件（未选中的 workflows）`));
+        }
+        if (removedDeselectedSkillCount > 0) {
+            console.log(chalk.dim(`已移除：${removedDeselectedSkillCount} 个技能目录（未选中的 workflows）`));
+        }
+        // 12. Show onboarding message for newly configured tools from legacy upgrade
+        if (newlyConfiguredTools.length > 0) {
+            console.log();
+            console.log(chalk.bold('快速上手：'));
+            console.log('  /opsx:new       开始新变更');
+            console.log('  /opsx:continue  创建下一个 artifact');
+            console.log('  /opsx:apply     实现任务');
+            console.log();
+            console.log(`了解更多：${chalk.cyan('https://github.com/Fission-AI/OpenSpec')}`);
+        }
+        const configuredAndNewTools = [...new Set([...configuredTools, ...newlyConfiguredTools])];
+        // 13. Detect new tool directories not currently configured
+        this.detectNewTools(resolvedProjectPath, configuredAndNewTools);
+        // 14. Display note about extra workflows not in profile
+        this.displayExtraWorkflowsNote(resolvedProjectPath, configuredAndNewTools, desiredWorkflows);
+        this.displayOldCoreCustomProfileNote(profile, globalConfig.workflows);
+        // 15. List affected tools
+        if (updatedTools.length > 0) {
+            const toolDisplayNames = updatedTools;
+            console.log(chalk.dim(`工具：${toolDisplayNames.join(', ')}`));
+        }
+        console.log();
+        console.log(chalk.dim('重启你的 IDE 以使更改生效。'));
+    }
+    /**
+     * Display message when all tools are up to date.
+     */
+    displayUpToDateMessage(toolStatuses) {
+        const toolNames = toolStatuses.map((s) => s.toolId);
+        console.log(chalk.green(`✓ 所有 ${toolStatuses.length} 个工具已是最新（v${OPENSPEC_VERSION}）`));
+        console.log(chalk.dim(`  工具：${toolNames.join(', ')}`));
+        console.log();
+        console.log(chalk.dim('使用 --force 强制刷新文件。'));
+    }
+    /**
+     * Display the update plan showing which tools need updating.
+     */
+    displayUpdatePlan(toolsToUpdate, statusByTool, upToDate) {
+        const updates = toolsToUpdate.map((toolId) => {
+            const status = statusByTool.get(toolId);
+            if (status?.needsUpdate) {
+                const fromVersion = status.generatedByVersion ?? '未知版本';
+                return `${status.toolId} (${fromVersion} → ${OPENSPEC_VERSION})`;
+            }
+            return `${toolId}（配置同步）`;
+        });
+        console.log(`正在更新 ${toolsToUpdate.length} 个工具：${updates.join(', ')}`);
+        if (upToDate.length > 0) {
+            const upToDateNames = upToDate.map((s) => s.toolId);
+            console.log(chalk.dim(`已是最新：${upToDateNames.join(', ')}`));
+        }
+    }
+    /**
+     * Detects new tool directories that aren't currently configured and displays a hint.
+     */
+    detectNewTools(projectPath, configuredTools) {
+        const availableTools = getAvailableTools(projectPath);
+        const configuredSet = new Set(configuredTools);
+        const newTools = availableTools.filter((t) => !configuredSet.has(t.value));
+        if (newTools.length > 0) {
+            const newToolNames = newTools.map((tool) => tool.name);
+            const isSingleTool = newToolNames.length === 1;
+            const toolNoun = isSingleTool ? 'tool' : 'tools';
+            const pronoun = isSingleTool ? 'it' : 'them';
+            console.log();
+            console.log(chalk.yellow(`检测到新的工具：${newToolNames.join(', ')}。运行 'openspec init' 添加。`));
+        }
+    }
+    /**
+     * Displays a note about extra workflows installed that aren't in the current profile.
+     */
+    displayExtraWorkflowsNote(projectPath, configuredTools, profileWorkflows) {
+        const installedWorkflows = scanInstalledWorkflows(projectPath, configuredTools);
+        const profileSet = new Set(profileWorkflows);
+        const extraWorkflows = installedWorkflows.filter((w) => !profileSet.has(w));
+        if (extraWorkflows.length > 0) {
+            console.log(chalk.dim(`提示：${extraWorkflows.length} 个额外 workflows 不在当前 profile 中（使用 \`openspec config profile\` 管理）`));
+        }
+    }
+    /**
+     * Suggest opting back into core when a custom profile still matches the old
+     * pre-sync core set. Keep custom profiles user-owned; do not mutate them.
+     */
+    displayOldCoreCustomProfileNote(profile, workflows) {
+        if (profile !== 'custom' || !workflows) {
+            return;
+        }
+        const workflowSet = new Set(workflows);
+        const matchesOldCore = workflowSet.size === OLD_CORE_WORKFLOWS.length &&
+            OLD_CORE_WORKFLOWS.every((workflow) => workflowSet.has(workflow));
+        if (!matchesOldCore) {
+            return;
+        }
+        console.log(chalk.dim('提示：核心 profile 现已包含 sync。你的自定义 profile 保留的是旧的核心 workflow 集合。'));
+        console.log(chalk.dim('运行 `openspec config profile core` 再执行 `openspec update` 以添加 sync。'));
+    }
+    /**
+     * Removes skill directories for workflows when delivery changed to commands-only.
+     * Returns the number of directories removed.
+     */
+    async removeSkillDirs(skillsDir) {
+        let removed = 0;
+        for (const workflow of ALL_WORKFLOWS) {
+            const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
+            if (!dirName)
+                continue;
+            const skillDir = path.join(skillsDir, dirName);
+            try {
+                if (fs.existsSync(skillDir)) {
+                    await fs.promises.rm(skillDir, { recursive: true, force: true });
+                    removed++;
+                }
+            }
+            catch {
+                // Ignore errors
+            }
+        }
+        return removed;
+    }
+    /**
+     * Removes skill directories for workflows that are no longer selected in the active profile.
+     * Returns the number of directories removed.
+     */
+    async removeUnselectedSkillDirs(skillsDir, desiredWorkflows) {
+        const desiredSet = new Set(desiredWorkflows);
+        let removed = 0;
+        for (const workflow of ALL_WORKFLOWS) {
+            if (desiredSet.has(workflow))
+                continue;
+            const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
+            if (!dirName)
+                continue;
+            const skillDir = path.join(skillsDir, dirName);
+            try {
+                if (fs.existsSync(skillDir)) {
+                    await fs.promises.rm(skillDir, { recursive: true, force: true });
+                    removed++;
+                }
+            }
+            catch {
+                // Ignore errors
+            }
+        }
+        return removed;
+    }
+    /**
+     * Removes command files for workflows when delivery changed to skills-only.
+     * Returns the number of files removed.
+     */
+    async removeCommandFiles(projectPath, toolId) {
+        let removed = 0;
+        const adapter = CommandAdapterRegistry.get(toolId);
+        if (!adapter)
+            return 0;
+        for (const workflow of ALL_WORKFLOWS) {
+            const cmdPath = adapter.getFilePath(workflow);
+            const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+            try {
+                if (fs.existsSync(fullPath)) {
+                    await fs.promises.unlink(fullPath);
+                    removed++;
+                }
+            }
+            catch {
+                // Ignore errors
+            }
+        }
+        return removed;
+    }
+    /**
+     * Removes command files for workflows that are no longer selected in the active profile.
+     * Returns the number of files removed.
+     */
+    async removeUnselectedCommandFiles(projectPath, toolId, desiredWorkflows) {
+        let removed = 0;
+        const adapter = CommandAdapterRegistry.get(toolId);
+        if (!adapter)
+            return 0;
+        const desiredSet = new Set(desiredWorkflows);
+        for (const workflow of ALL_WORKFLOWS) {
+            if (desiredSet.has(workflow))
+                continue;
+            const cmdPath = adapter.getFilePath(workflow);
+            const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+            try {
+                if (fs.existsSync(fullPath)) {
+                    await fs.promises.unlink(fullPath);
+                    removed++;
+                }
+            }
+            catch {
+                // Ignore errors
+            }
+        }
+        return removed;
+    }
+    /**
+     * Detect and handle legacy OpenSpec artifacts.
+     * Unlike init, update warns but continues if legacy files found in non-interactive mode.
+     * Returns array of tool IDs that were newly configured during legacy upgrade.
+     */
+    async handleLegacyCleanup(projectPath, desiredWorkflows, delivery) {
+        // Detect legacy artifacts
+        const detection = await detectLegacyArtifacts(projectPath);
+        if (!detection.hasLegacyArtifacts) {
+            return []; // No legacy artifacts found
+        }
+        // Show what was detected
+        console.log();
+        console.log(formatDetectionSummary(detection));
+        console.log();
+        const canPrompt = isInteractive();
+        if (this.force) {
+            // --force flag: proceed with cleanup automatically
+            await this.performLegacyCleanup(projectPath, detection);
+            // Then upgrade legacy tools to new skills
+            return this.upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery);
+        }
+        if (!canPrompt) {
+            // Non-interactive mode without --force: warn and continue
+            // (Unlike init, update doesn't abort - user may just want to update skills)
+            console.log(chalk.yellow('⚠ 使用 --force 自动清理旧版文件，或者以交互模式运行。'));
+            console.log();
+            return [];
+        }
+        // Interactive mode: prompt for confirmation
+        const { confirm } = await import('@inquirer/prompts');
+        const shouldCleanup = await confirm({
+            message: '升级并清理旧版文件？',
+            default: true,
+        });
+        if (shouldCleanup) {
+            await this.performLegacyCleanup(projectPath, detection);
+            // Then upgrade legacy tools to new skills
+            return this.upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery);
+        }
+        else {
+            console.log(chalk.dim('跳过旧版清理。继续更新技能...'));
+            console.log();
+            return [];
+        }
+    }
+    /**
+     * Perform cleanup of legacy artifacts.
+     */
+    async performLegacyCleanup(projectPath, detection) {
+        const spinner = ora('正在清理旧版文件...').start();
+        const result = await cleanupLegacyArtifacts(projectPath, detection);
+        spinner.succeed('旧版文件已清理');
+        const summary = formatCleanupSummary(result);
+        if (summary) {
+            console.log();
+            console.log(summary);
+        }
+        console.log();
+    }
+    /**
+     * Upgrade legacy tools to new skills system.
+     * Returns array of tool IDs that were newly configured.
+     */
+    async upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery) {
+        // Get tools that had legacy artifacts
+        const legacyTools = getToolsFromLegacyArtifacts(detection);
+        if (legacyTools.length === 0) {
+            return [];
+        }
+        // Get currently configured tools
+        const configuredTools = getConfiguredToolsForProfileSync(projectPath);
+        const configuredSet = new Set(configuredTools);
+        // Filter to tools that aren't already configured
+        const unconfiguredLegacyTools = legacyTools.filter((t) => !configuredSet.has(t));
+        if (unconfiguredLegacyTools.length === 0) {
+            return [];
+        }
+        // Get valid tools (those with skillsDir)
+        const validToolIds = new Set(getToolsWithSkillsDir());
+        const validUnconfiguredTools = unconfiguredLegacyTools.filter((t) => validToolIds.has(t));
+        if (validUnconfiguredTools.length === 0) {
+            return [];
+        }
+        // Show what tools were detected from legacy artifacts
+        console.log(chalk.bold('从旧版 artifact 检测到以下工具：'));
+        for (const toolId of validUnconfiguredTools) {
+            const tool = AI_TOOLS.find((t) => t.value === toolId);
+            console.log(`  • ${tool?.name || toolId}`);
+        }
+        console.log();
+        let selectedTools;
+        if (this.force || !canPrompt) {
+            // Non-interactive with --force: auto-select detected tools
+            selectedTools = validUnconfiguredTools;
+            console.log(`正在为以下工具设置技能：${selectedTools.join(', ')}`);
+        }
+        else {
+            // Interactive mode: prompt for tool selection with detected tools pre-selected
+            const { searchableMultiSelect } = await import('../prompts/searchable-multi-select.js');
+            const sortedChoices = validUnconfiguredTools.map((toolId) => {
+                const tool = AI_TOOLS.find((t) => t.value === toolId);
+                return {
+                    name: tool?.name || toolId,
+                    value: toolId,
+                    configured: false,
+                    preSelected: true, // Pre-select all detected legacy tools
+                };
+            });
+            selectedTools = await searchableMultiSelect({
+                message: '选择要使用新技能系统设置的工具：',
+                pageSize: 15,
+                choices: sortedChoices,
+                validate: (_selected) => true, // Allow empty selection (user can skip)
+            });
+            if (selectedTools.length === 0) {
+                console.log(chalk.dim('跳过工具设置。'));
+                console.log();
+                return [];
+            }
+        }
+        // Create skills/commands for selected tools using effective profile+delivery.
+        const newlyConfigured = [];
+        const shouldGenerateSkills = delivery !== 'commands';
+        const shouldGenerateCommands = delivery !== 'skills';
+        const skillTemplates = shouldGenerateSkills ? getSkillTemplates(desiredWorkflows) : [];
+        const commandContents = shouldGenerateCommands ? getCommandContents(desiredWorkflows) : [];
+        for (const toolId of selectedTools) {
+            const tool = AI_TOOLS.find((t) => t.value === toolId);
+            if (!tool?.skillsDir)
+                continue;
+            const spinner = ora(`正在设置 ${tool.name}...`).start();
+            try {
+                const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
+                // Create skill files when delivery includes skills
+                if (shouldGenerateSkills) {
+                    for (const { template, dirName } of skillTemplates) {
+                        const skillDir = path.join(skillsDir, dirName);
+                        const skillFile = path.join(skillDir, 'SKILL.md');
+                        // Use hyphen-based command references for OpenCode
+                        const transformer = (tool.value === 'opencode' || tool.value === 'pi') ? transformToHyphenCommands : undefined;
+                        const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
+                        await FileSystemUtils.writeFile(skillFile, skillContent);
+                    }
+                }
+                // Create commands when delivery includes commands
+                if (shouldGenerateCommands) {
+                    const adapter = CommandAdapterRegistry.get(tool.value);
+                    if (adapter) {
+                        const generatedCommands = generateCommands(commandContents, adapter);
+                        for (const cmd of generatedCommands) {
+                            const commandFile = path.isAbsolute(cmd.path) ? cmd.path : path.join(projectPath, cmd.path);
+                            await FileSystemUtils.writeFile(commandFile, cmd.fileContent);
+                        }
+                    }
+                }
+                spinner.succeed(`${tool.name} 设置完成`);
+                newlyConfigured.push(toolId);
+            }
+            catch (error) {
+                spinner.fail(`${tool.name} 设置失败`);
+                console.log(chalk.red(`  ${error instanceof Error ? error.message : String(error)}`));
+            }
+        }
+        if (newlyConfigured.length > 0) {
+            console.log();
+        }
+        return newlyConfigured;
+    }
+}
+//# sourceMappingURL=update.js.map

package/dist/core/validation/constants.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Validation threshold constants
+ */
+export declare const MIN_WHY_SECTION_LENGTH = 50;
+export declare const MIN_PURPOSE_LENGTH = 50;
+export declare const MAX_WHY_SECTION_LENGTH = 1000;
+export declare const MAX_REQUIREMENT_TEXT_LENGTH = 500;
+export declare const MAX_DELTAS_PER_CHANGE = 10;
+export declare const VALIDATION_MESSAGES: {
+    readonly SCENARIO_EMPTY: "场景描述不能为空";
+    readonly REQUIREMENT_EMPTY: "需求描述不能为空";
+    readonly REQUIREMENT_NO_SHALL: "需求必须包含 SHALL、MUST、必须 或 应当";
+    readonly REQUIREMENT_NO_SCENARIOS: "每个需求至少需要一个场景";
+    readonly SPEC_NAME_EMPTY: "Spec 名称不能为空";
+    readonly SPEC_PURPOSE_EMPTY: "Purpose 段落不能为空";
+    readonly SPEC_NO_REQUIREMENTS: "Spec 至少需要一个需求";
+    readonly CHANGE_NAME_EMPTY: "变更名称不能为空";
+    readonly CHANGE_WHY_TOO_SHORT: "Why 段落至少需要 50 个字符";
+    readonly CHANGE_WHY_TOO_LONG: "Why 段落不应超过 1000 个字符";
+    readonly CHANGE_WHAT_EMPTY: "What Changes 段落不能为空";
+    readonly CHANGE_NO_DELTAS: "变更必须至少包含一个 delta";
+    readonly CHANGE_TOO_MANY_DELTAS: "建议将超过 10 个 delta 的变更拆分";
+    readonly DELTA_SPEC_EMPTY: "Spec 名称不能为空";
+    readonly DELTA_DESCRIPTION_EMPTY: "Delta 描述不能为空";
+    readonly PURPOSE_TOO_BRIEF: "Purpose 段落过短（不足 50 个字符）";
+    readonly REQUIREMENT_TOO_LONG: "需求文本过长（超过 500 个字符），建议拆分";
+    readonly DELTA_DESCRIPTION_TOO_BRIEF: "Delta 描述过短";
+    readonly DELTA_MISSING_REQUIREMENTS: "Delta 应包含需求描述";
+    readonly GUIDE_NO_DELTAS: "未找到 delta。请确保变更的 specs/ 目录下有能力子目录（如 specs/http-server/spec.md），其中的 .md 文件使用了 delta 标题（## ADDED/MODIFIED/REMOVED/RENAMED Requirements），且每个需求至少包含一个 \"#### Scenario:\" 块。提示：运行 \"openspec change show <change-id> --json --deltas-only\" 可检查解析结果。";
+    readonly GUIDE_MISSING_SPEC_SECTIONS: "缺少必需段落。预期标题： \"## Purpose\" 和 \"## Requirements\"。示例：\n## Purpose\n[简述目的]\n\n## Requirements\n### Requirement: 明确的需求描述\n系统 SHALL ...\n\n#### Scenario: 场景名称\n- **WHEN** ...\n- **THEN** ...";
+    readonly GUIDE_MISSING_CHANGE_SECTIONS: "缺少必需段落。预期标题： \"## Why\" 和 \"## What Changes\"。请确保变更在 specs/ 中使用 delta 标题记录了变更。";
+    readonly GUIDE_SCENARIO_FORMAT: "场景必须使用四级标题。请将列表转换为：\n#### Scenario: 简短名称\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/core/validation/constants.js

@@ -0,0 +1,40 @@
+/**
+ * Validation threshold constants
+ */
+// Minimum character lengths
+export const MIN_WHY_SECTION_LENGTH = 50;
+export const MIN_PURPOSE_LENGTH = 50;
+// Maximum character/item limits
+export const MAX_WHY_SECTION_LENGTH = 1000;
+export const MAX_REQUIREMENT_TEXT_LENGTH = 500;
+export const MAX_DELTAS_PER_CHANGE = 10;
+// Validation messages
+export const VALIDATION_MESSAGES = {
+    // Required content
+    SCENARIO_EMPTY: '场景描述不能为空',
+    REQUIREMENT_EMPTY: '需求描述不能为空',
+    REQUIREMENT_NO_SHALL: '需求必须包含 SHALL、MUST、必须 或 应当',
+    REQUIREMENT_NO_SCENARIOS: '每个需求至少需要一个场景',
+    SPEC_NAME_EMPTY: 'Spec 名称不能为空',
+    SPEC_PURPOSE_EMPTY: 'Purpose 段落不能为空',
+    SPEC_NO_REQUIREMENTS: 'Spec 至少需要一个需求',
+    CHANGE_NAME_EMPTY: '变更名称不能为空',
+    CHANGE_WHY_TOO_SHORT: `Why 段落至少需要 ${MIN_WHY_SECTION_LENGTH} 个字符`,
+    CHANGE_WHY_TOO_LONG: `Why 段落不应超过 ${MAX_WHY_SECTION_LENGTH} 个字符`,
+    CHANGE_WHAT_EMPTY: 'What Changes 段落不能为空',
+    CHANGE_NO_DELTAS: '变更必须至少包含一个 delta',
+    CHANGE_TOO_MANY_DELTAS: `建议将超过 ${MAX_DELTAS_PER_CHANGE} 个 delta 的变更拆分`,
+    DELTA_SPEC_EMPTY: 'Spec 名称不能为空',
+    DELTA_DESCRIPTION_EMPTY: 'Delta 描述不能为空',
+    // Warnings
+    PURPOSE_TOO_BRIEF: `Purpose 段落过短（不足 ${MIN_PURPOSE_LENGTH} 个字符）`,
+    REQUIREMENT_TOO_LONG: `需求文本过长（超过 ${MAX_REQUIREMENT_TEXT_LENGTH} 个字符），建议拆分`,
+    DELTA_DESCRIPTION_TOO_BRIEF: 'Delta 描述过短',
+    DELTA_MISSING_REQUIREMENTS: 'Delta 应包含需求描述',
+    // Guidance snippets (appended to primary messages for remediation)
+    GUIDE_NO_DELTAS: '未找到 delta。请确保变更的 specs/ 目录下有能力子目录（如 specs/http-server/spec.md），其中的 .md 文件使用了 delta 标题（## ADDED/MODIFIED/REMOVED/RENAMED Requirements），且每个需求至少包含一个 "#### Scenario:" 块。提示：运行 "openspec change show <change-id> --json --deltas-only" 可检查解析结果。',
+    GUIDE_MISSING_SPEC_SECTIONS: '缺少必需段落。预期标题： "## Purpose" 和 "## Requirements"。示例：\n## Purpose\n[简述目的]\n\n## Requirements\n### Requirement: 明确的需求描述\n系统 SHALL ...\n\n#### Scenario: 场景名称\n- **WHEN** ...\n- **THEN** ...',
+    GUIDE_MISSING_CHANGE_SECTIONS: '缺少必需段落。预期标题： "## Why" 和 "## What Changes"。请确保变更在 specs/ 中使用 delta 标题记录了变更。',
+    GUIDE_SCENARIO_FORMAT: '场景必须使用四级标题。请将列表转换为：\n#### Scenario: 简短名称\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...',
+};
+//# sourceMappingURL=constants.js.map

package/dist/core/validation/types.d.ts

@@ -0,0 +1,18 @@
+export type ValidationLevel = 'ERROR' | 'WARNING' | 'INFO';
+export interface ValidationIssue {
+    level: ValidationLevel;
+    path: string;
+    message: string;
+    line?: number;
+    column?: number;
+}
+export interface ValidationReport {
+    valid: boolean;
+    issues: ValidationIssue[];
+    summary: {
+        errors: number;
+        warnings: number;
+        info: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/validation/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map