@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/core/init.js

@@ -0,0 +1,836 @@
+/**
+ * Init Command
+ *
+ * Sets up FreeSpec with Agent Skills and /freespec:* slash commands.
+ * This is the unified setup command that replaces both the old init and experimental commands.
+ */
+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 { MAX_CONTEXT_SIZE, readProjectConfig, } from './project-config.js';
+import { ANCHORED_OPENSPEC_DIRS, ensureDirectoryAnchor } from './openspec-root.js';
+import { getSkillReferenceTransformer, getTransformerForTool, usesNaturalLanguageSkillReferences } from '../utils/command-references.js';
+import { AI_TOOLS, getUniversalTool, universalToolFallbackHint, OPENSPEC_DIR_NAME, resolveToolIdAlias, } from './config.js';
+import { PALETTE } from './styles/palette.js';
+import { isInteractive } from '../utils/interactive.js';
+import { serializeConfig } from './config-prompts.js';
+import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
+import { getToolsWithSkillsDir, getToolStates, getSkillTemplates, getCommandContents, generateSkillContent, copySkillExtras, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, formatIdeRestart, } from './shared/index.js';
+import { getGlobalConfig } from './global-config.js';
+import { getProfileWorkflows, ALL_WORKFLOWS } from './profiles.js';
+import { DEFAULT_SCHEMA } from './change-layout.js';
+import { getAvailableTools } from './available-tools.js';
+import { resolveSharedSkillWriters, sharedSkillRootOwner, writeSharedSkillTarget, } from './shared-skill-target.js';
+import { migrateIfNeeded, migrateLegacyToolDirs, describeLegacyMigration, keptInPlaceNotice, hasMovableContent } from './migration.js';
+import { resolveCommandSurfaceCapability, resolveCommandInvocation, shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
+const require = createRequire(import.meta.url);
+const { version: OPENSPEC_VERSION } = require('../../package.json');
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+function formatLanguageContext(language) {
+    return [
+        `Language: ${language}`,
+        `All artifacts must be written in ${language}.`,
+    ].join('\n');
+}
+const PROGRESS_SPINNER = {
+    interval: 80,
+    frames: ['░░░', '▒░░', '▒▒░', '▒▒▒', '▓▒▒', '▓▓▒', '▓▓▓', '▒▓▓', '░▒▓'],
+};
+const WORKFLOW_TO_SKILL_DIR = {
+    '新建': 'freespec-新建',
+    '深思': 'freespec-深思',
+    '需求': 'freespec-需求',
+    '设计': 'freespec-设计',
+    '任务': 'freespec-任务',
+    '审文档': 'freespec-审文档',
+    '用例': 'freespec-用例',
+    '验收': 'freespec-验收',
+    '写Java': 'freespec-写Java',
+    '审Java': 'freespec-审Java',
+};
+// -----------------------------------------------------------------------------
+// Init Command Class
+// -----------------------------------------------------------------------------
+export class InitCommand {
+    toolsArg;
+    language;
+    force;
+    interactiveOption;
+    profileOverride;
+    animation;
+    constructor(options = {}) {
+        this.toolsArg = options.tools;
+        this.language = this.normalizeLanguage(options.language);
+        this.force = options.force ?? false;
+        this.interactiveOption = options.interactive;
+        this.profileOverride = options.profile;
+        this.animation = options.animation ?? true;
+    }
+    async execute(targetPath) {
+        const projectPath = FileSystemUtils.canonicalizeExistingPath(targetPath);
+        const freespecDir = OPENSPEC_DIR_NAME;
+        const freespecPath = path.join(projectPath, freespecDir);
+        // Validation happens silently in the background
+        const extendMode = await this.validate(projectPath, freespecPath);
+        await this.assertLanguageCanBeApplied(projectPath, freespecPath);
+        // Migrate FreeSpec-managed skills left in renamed tool directories
+        // (e.g. .kimi -> .kimi-code) before detection so they stay recognized.
+        migrateLegacyToolDirs(projectPath);
+        // Detect available tools in the project (task 7.1)
+        const detectedTools = getAvailableTools(projectPath);
+        // Migration check: migrate existing projects to profile system (task 7.3)
+        if (extendMode) {
+            migrateIfNeeded(projectPath, detectedTools);
+        }
+        // Validate profile override early so invalid values fail before tool setup.
+        // The resolved value is consumed later when generation reads effective config.
+        // This runs ahead of the welcome screen so an invalid --profile does not make
+        // the user press Enter before seeing the error.
+        this.resolveProfileOverride();
+        // Show animated welcome screen (interactive mode only)
+        const canPrompt = this.canPromptInteractively();
+        if (canPrompt) {
+            const { showWelcomeScreen } = await import('../ui/welcome-screen.js');
+            await showWelcomeScreen(this.getActiveWorkflows(), { animate: this.animation });
+        }
+        // Get tool states before processing
+        const toolStates = getToolStates(projectPath);
+        // Get tool selection (pass detected tools for pre-selection)
+        const selectedToolIds = await this.getSelectedTools(toolStates, extendMode, detectedTools, projectPath);
+        // Validate selected tools
+        const validatedTools = this.validateTools(selectedToolIds, toolStates, projectPath);
+        // Selecting a renamed tool is consent to leave its former directory:
+        // init is about to write the current one, and leaving FreeSpec content
+        // behind would give the user two installs of the same tool.
+        for (const migration of migrateLegacyToolDirs(projectPath, validatedTools.map((tool) => tool.value))) {
+            if (hasMovableContent(migration)) {
+                console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+            }
+            const kept = keptInPlaceNotice(migration);
+            if (kept)
+                console.log(chalk.dim(kept));
+        }
+        await this.createDirectoryStructure(freespecPath, extendMode);
+        const results = await this.generateSkillsAndCommands(projectPath, validatedTools);
+        const configStatus = await this.createConfig(freespecPath, extendMode);
+        this.displaySuccessMessage(projectPath, validatedTools, results, configStatus);
+        if (results.failedTools.length > 0) {
+            throw new Error(`FreeSpec setup failed for: ${results.failedTools.map((tool) => tool.name).join(', ')}`);
+        }
+    }
+    // ═══════════════════════════════════════════════════════════
+    // VALIDATION & SETUP
+    // ═══════════════════════════════════════════════════════════
+    async validate(projectPath, freespecPath) {
+        const extendMode = await FileSystemUtils.directoryExists(freespecPath);
+        // Check write permissions
+        if (!(await FileSystemUtils.ensureWritePermissions(projectPath))) {
+            throw new Error(`Insufficient permissions to write to ${projectPath}`);
+        }
+        return extendMode;
+    }
+    canPromptInteractively() {
+        if (this.interactiveOption === false)
+            return false;
+        if (this.toolsArg !== undefined)
+            return false;
+        return isInteractive({ interactive: this.interactiveOption });
+    }
+    resolveProfileOverride() {
+        if (this.profileOverride === undefined) {
+            return undefined;
+        }
+        if (this.profileOverride === 'core' || this.profileOverride === 'custom') {
+            return this.profileOverride;
+        }
+        throw new Error(`Invalid profile "${this.profileOverride}". Available profiles: core, custom`);
+    }
+    /**
+     * Resolves the workflows the effective profile installs, so onboarding output
+     * only mentions commands that will actually exist.
+     */
+    getActiveWorkflows() {
+        const globalCfg = getGlobalConfig();
+        const activeProfile = this.resolveProfileOverride() ?? globalCfg.profile ?? 'core';
+        return [...getProfileWorkflows(activeProfile, globalCfg.workflows)];
+    }
+    // ═══════════════════════════════════════════════════════════
+    // TOOL SELECTION
+    // ═══════════════════════════════════════════════════════════
+    async getSelectedTools(toolStates, extendMode, detectedTools, projectPath) {
+        // Check for --tools flag first
+        const nonInteractiveSelection = this.resolveToolsArg();
+        if (nonInteractiveSelection !== null) {
+            return nonInteractiveSelection;
+        }
+        const validTools = getToolsWithSkillsDir();
+        const detectedToolIds = new Set(detectedTools.map((t) => t.value));
+        const configuredToolIds = new Set([...toolStates.entries()]
+            .filter(([, status]) => status.configured)
+            .map(([toolId]) => toolId));
+        const shouldPreselectDetected = !extendMode && configuredToolIds.size === 0;
+        const canPrompt = this.canPromptInteractively();
+        // Non-interactive mode: use detected tools as fallback (task 7.8)
+        if (!canPrompt) {
+            if (detectedToolIds.size > 0) {
+                return [...detectedToolIds];
+            }
+            const fallbackHint = universalToolFallbackHint(validTools);
+            throw new Error(`No tools detected and no --tools flag provided. Valid tools:\n  ${validTools.join('\n  ')}\n\nUse --tools all, --tools none, or --tools claude,cursor,...${fallbackHint ? `\n${fallbackHint}` : ''}`);
+        }
+        if (validTools.length === 0) {
+            throw new Error(`No tools available for skill generation.`);
+        }
+        // Interactive mode: show searchable multi-select
+        const { searchableMultiSelect } = await import('../prompts/searchable-multi-select.js');
+        // Build choices: pre-select configured tools; keep detected tools visible but unselected.
+        const sortedChoices = validTools
+            .map((toolId) => {
+            const tool = AI_TOOLS.find((t) => t.value === toolId);
+            const status = toolStates.get(toolId);
+            const configured = status?.configured ?? false;
+            const detected = detectedToolIds.has(toolId);
+            return {
+                name: tool?.name || toolId,
+                value: toolId,
+                searchAliases: tool?.searchAliases,
+                configured,
+                detected: detected && !configured,
+                preSelected: configured || (shouldPreselectDetected && detected && !configured),
+            };
+        })
+            .sort((a, b) => {
+            // Configured tools first, then detected (not configured), then everything else.
+            if (a.configured && !b.configured)
+                return -1;
+            if (!a.configured && b.configured)
+                return 1;
+            if (a.detected && !b.detected)
+                return -1;
+            if (!a.detected && b.detected)
+                return 1;
+            return 0;
+        });
+        const configuredNames = validTools
+            .filter((toolId) => configuredToolIds.has(toolId))
+            .map((toolId) => AI_TOOLS.find((t) => t.value === toolId)?.name || toolId);
+        if (configuredNames.length > 0) {
+            console.log(`FreeSpec configured: ${configuredNames.join(', ')} (pre-selected)`);
+        }
+        const detectedOnlyNames = detectedTools
+            .filter((tool) => !configuredToolIds.has(tool.value))
+            .map((tool) => tool.name);
+        if (detectedOnlyNames.length > 0) {
+            const detectionLabel = shouldPreselectDetected
+                ? 'pre-selected for first-time setup'
+                : 'not pre-selected';
+            console.log(`Detected tool directories: ${detectedOnlyNames.join(', ')} (${detectionLabel})`);
+        }
+        // A search that matches nothing is where someone whose assistant is not on
+        // the list gives up (#653), so name the vendor-neutral entry right there.
+        const universalTool = getUniversalTool();
+        const universalHint = universalTool && validTools.includes(universalTool.value)
+            ? `Tool not listed? Clear the search and pick "${universalTool.name}".`
+            : undefined;
+        const selectedTools = await searchableMultiSelect({
+            message: `Select tools to set up (${validTools.length} available)`,
+            pageSize: 15,
+            choices: sortedChoices,
+            emptyHint: universalHint,
+            validate: (selected) => selected.length > 0 || 'Select at least one tool',
+        });
+        if (selectedTools.length === 0) {
+            throw new Error('At least one tool must be selected');
+        }
+        return selectedTools;
+    }
+    resolveToolsArg() {
+        if (typeof this.toolsArg === 'undefined') {
+            return null;
+        }
+        const raw = this.toolsArg.trim();
+        if (raw.length === 0) {
+            throw new Error('The --tools option requires a value. Use "all", "none", or a comma-separated list of tool IDs.');
+        }
+        const availableTools = getToolsWithSkillsDir();
+        const availableSet = new Set(availableTools);
+        const availableList = ['all', 'none', ...availableTools].join(', ');
+        const lowerRaw = raw.toLowerCase();
+        if (lowerRaw === 'all') {
+            return availableTools;
+        }
+        if (lowerRaw === 'none') {
+            return [];
+        }
+        const tokens = raw
+            .split(',')
+            .map((token) => token.trim())
+            .filter((token) => token.length > 0);
+        if (tokens.length === 0) {
+            throw new Error('The --tools option requires at least one tool ID when not using "all" or "none".');
+        }
+        // Retired ids resolve to their current tool, so a rebrand does not break
+        // an existing `--tools windsurf` in someone's setup script.
+        const normalizedTokens = tokens.map((token) => resolveToolIdAlias(token.toLowerCase()));
+        if (normalizedTokens.some((token) => token === 'all' || token === 'none')) {
+            throw new Error('Cannot combine reserved values "all" or "none" with specific tool IDs.');
+        }
+        const invalidTokens = tokens.filter((_token, index) => !availableSet.has(normalizedTokens[index]));
+        if (invalidTokens.length > 0) {
+            const fallbackHint = universalToolFallbackHint([...availableSet]);
+            throw new Error(`Invalid tool(s): ${invalidTokens.join(', ')}. Available values: ${availableList}${fallbackHint ? `\n${fallbackHint}` : ''}`);
+        }
+        // Deduplicate while preserving order
+        const deduped = [];
+        for (const token of normalizedTokens) {
+            if (!deduped.includes(token)) {
+                deduped.push(token);
+            }
+        }
+        return deduped;
+    }
+    validateTools(toolIds, toolStates, projectPath) {
+        const selectedTools = [];
+        for (const toolId of toolIds) {
+            const tool = AI_TOOLS.find((t) => t.value === toolId);
+            if (!tool) {
+                const validToolIds = getToolsWithSkillsDir();
+                throw new Error(`Unknown tool '${toolId}'. Valid tools:\n  ${validToolIds.join('\n  ')}`);
+            }
+            if (!toolSupportsSkills(tool)) {
+                const validToolsWithSkills = getToolsWithSkillsDir();
+                throw new Error(`Tool '${toolId}' does not support skill generation.\nTools with skill generation support:\n  ${validToolsWithSkills.join('\n  ')}`);
+            }
+            selectedTools.push(tool);
+        }
+        // A selected tool may share its physical skills root with an already
+        // configured owner. Include that owner in the refresh without dropping the
+        // selected tool: it may still have an independent command surface.
+        const generationTools = [...selectedTools];
+        const delivery = getGlobalConfig().delivery ?? 'both';
+        for (const selected of selectedTools) {
+            if (!selected.skillsDir)
+                continue;
+            const selectedOwner = selected.value === 'codex' ||
+                !shouldGenerateSkillsForTool(selected.value, delivery)
+                ? undefined
+                : sharedSkillRootOwner(projectPath, selected.value);
+            for (const candidate of AI_TOOLS) {
+                if (candidate.skillsDir === selected.skillsDir &&
+                    toolStates.get(candidate.value)?.configured &&
+                    candidate.value === selectedOwner &&
+                    !generationTools.includes(candidate)) {
+                    generationTools.push(candidate);
+                }
+            }
+        }
+        const skillWriters = resolveSharedSkillWriters(projectPath, generationTools);
+        const sharedRoots = new Map();
+        for (const tool of generationTools) {
+            if (!tool.skillsDir)
+                continue;
+            const group = sharedRoots.get(tool.skillsDir) ?? [];
+            group.push(tool);
+            sharedRoots.set(tool.skillsDir, group);
+        }
+        for (const [root, group] of sharedRoots) {
+            if (group.length < 2)
+                continue;
+            const owner = group.find((tool) => skillWriters.has(tool.value));
+            console.log(chalk.dim(`${group.map((tool) => tool.name).join(', ')} share ${root}/skills; writing one tree for ${owner?.value}.`));
+        }
+        const validatedTools = [];
+        for (const tool of generationTools) {
+            if (!toolSupportsSkills(tool))
+                continue;
+            const preState = toolStates.get(tool.value);
+            const skillsPath = resolveToolSkillsDir(projectPath, tool);
+            const isGlobalSkillTarget = hasGlobalSkillTarget(tool);
+            validatedTools.push({
+                value: tool.value,
+                name: tool.name,
+                skillsDir: tool.skillsDir,
+                skillsPath,
+                skillsRoot: isGlobalSkillTarget ? skillsPath : projectPath,
+                isGlobalSkillTarget,
+                wasConfigured: preState?.configured ?? false,
+                writesSkills: !tool.skillsDir || skillWriters.has(tool.value),
+            });
+        }
+        return validatedTools;
+    }
+    // ═══════════════════════════════════════════════════════════
+    // DIRECTORY STRUCTURE
+    // ═══════════════════════════════════════════════════════════
+    async createDirectoryStructure(freespecPath, extendMode) {
+        const directories = [freespecPath];
+        if (extendMode) {
+            // In extend mode, just ensure directories exist without spinner
+            for (const dir of directories) {
+                FileSystemUtils.assertProjectArtifactPath(path.dirname(freespecPath), dir);
+                await FileSystemUtils.createDirectory(dir);
+            }
+            await this.writeGitkeepFiles(freespecPath);
+            return;
+        }
+        const spinner = this.startSpinner('Creating FreeSpec structure...');
+        for (const dir of directories) {
+            FileSystemUtils.assertProjectArtifactPath(path.dirname(freespecPath), dir);
+            await FileSystemUtils.createDirectory(dir);
+        }
+        await this.writeGitkeepFiles(freespecPath);
+        spinner.stopAndPersist({
+            symbol: PALETTE.white('▌'),
+            text: PALETTE.white('FreeSpec structure created'),
+        });
+    }
+    async writeGitkeepFiles(freespecPath) {
+        for (const relativeDir of ANCHORED_OPENSPEC_DIRS) {
+            await ensureDirectoryAnchor(path.dirname(freespecPath), relativeDir);
+        }
+    }
+    // ═══════════════════════════════════════════════════════════
+    // SKILL & COMMAND GENERATION
+    // ═══════════════════════════════════════════════════════════
+    /**
+     * Generates skill files and slash commands for each selected tool,
+     * honoring the configured delivery mode (skills, commands, or both).
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param tools - Selected tools with their skill directory metadata
+     * @returns Created, refreshed, and failed tools plus removed artifact counts
+     */
+    async generateSkillsAndCommands(projectPath, tools) {
+        const createdTools = [];
+        const refreshedTools = [];
+        const failedTools = [];
+        const commandsSkipped = [];
+        const skillsInvocableCommandSkips = [];
+        let removedCommandCount = 0;
+        let removedSkillCount = 0;
+        // Read global config for profile and delivery settings (use --profile override if set)
+        const globalConfig = getGlobalConfig();
+        const profile = this.resolveProfileOverride() ?? globalConfig.profile ?? 'core';
+        const delivery = globalConfig.delivery ?? 'both';
+        const workflows = getProfileWorkflows(profile, globalConfig.workflows);
+        // Get skill and command templates filtered by profile workflows
+        const deliveryIncludesCommands = delivery !== 'skills';
+        const skillTemplates = getSkillTemplates(workflows);
+        const commandContents = getCommandContents(workflows);
+        // Process each tool
+        for (const tool of tools) {
+            const spinner = ora(`Setting up ${tool.name}...`).start();
+            try {
+                const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
+                const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
+                // Generate skill files if the selected delivery and tool capability allow skills
+                if (shouldGenerateSkills && tool.writesSkills) {
+                    // Create skill directories and SKILL.md files
+                    for (const { template, dirName } of skillTemplates) {
+                        const skillDir = path.join(tool.skillsPath, dirName);
+                        const skillFile = path.join(skillDir, 'SKILL.md');
+                        // Generate SKILL.md content with YAML frontmatter including generatedBy
+                        const transformer = getTransformerForTool(tool.value, delivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
+                        const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
+                        // Write the skill file
+                        FileSystemUtils.assertPathWithin(tool.skillsRoot, skillFile);
+                        await FileSystemUtils.writeFile(skillFile, skillContent);
+                        await copySkillExtras(skillDir, template.name);
+                    }
+                    writeSharedSkillTarget(projectPath, tool.value);
+                }
+                if (shouldRemoveSkillsForTool(tool.value, delivery) &&
+                    tool.writesSkills &&
+                    !tool.isGlobalSkillTarget) {
+                    removedSkillCount += await this.removeSkillDirs(tool.skillsRoot, tool.skillsPath);
+                    // Retain an explicit selection even when this delivery mode produces
+                    // no skills, so a divergent legacy sibling cannot reclaim ownership.
+                    writeSharedSkillTarget(projectPath, tool.value);
+                }
+                // 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 = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmd.path);
+                            await FileSystemUtils.writeFile(commandFile, cmd.fileContent);
+                        }
+                    }
+                }
+                else if (deliveryIncludesCommands) {
+                    if (resolveCommandSurfaceCapability(tool.value) === 'skills-invocable') {
+                        skillsInvocableCommandSkips.push(tool.value);
+                    }
+                    else {
+                        commandsSkipped.push(tool.value);
+                    }
+                }
+                if (shouldReconcileCommandFilesForTool(tool.value, delivery)) {
+                    removedCommandCount += await this.removeCommandFiles(projectPath, tool.value);
+                }
+                spinner.succeed(`Setup complete for ${tool.name}`);
+                if (tool.wasConfigured) {
+                    refreshedTools.push(tool);
+                }
+                else {
+                    createdTools.push(tool);
+                }
+            }
+            catch (error) {
+                spinner.fail(`Failed for ${tool.name}`);
+                failedTools.push({ name: tool.name, error: error });
+            }
+        }
+        for (const tool of [...createdTools, ...refreshedTools]) {
+            for (const migration of migrateLegacyToolDirs(projectPath, [tool.value], 'after-generation')) {
+                if (hasMovableContent(migration)) {
+                    console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+                }
+                const kept = keptInPlaceNotice(migration);
+                if (kept)
+                    console.log(chalk.dim(kept));
+            }
+        }
+        return {
+            createdTools,
+            refreshedTools,
+            failedTools,
+            commandsSkipped,
+            skillsInvocableCommandSkips,
+            removedCommandCount,
+            removedSkillCount,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════
+    // CONFIG FILE
+    // ═══════════════════════════════════════════════════════════
+    normalizeLanguage(language) {
+        if (language === undefined)
+            return undefined;
+        const normalized = language.trim();
+        if (!normalized) {
+            throw new Error('The --language option requires a non-empty value.');
+        }
+        if (/\p{Cc}|\p{Bidi_Control}|[\u200B\u2028\u2029\uFEFF]/u.test(normalized)) {
+            throw new Error('The --language option must be a single line without control or invisible formatting characters.');
+        }
+        const serializedContext = `${formatLanguageContext(normalized)}\n`;
+        if (Buffer.byteLength(serializedContext, 'utf8') > MAX_CONTEXT_SIZE) {
+            throw new Error(`The --language option is too long for FreeSpec's ${MAX_CONTEXT_SIZE / 1024}KB project context limit.`);
+        }
+        return normalized;
+    }
+    languageContext() {
+        if (!this.language)
+            return undefined;
+        return formatLanguageContext(this.language);
+    }
+    async assertLanguageCanBeApplied(projectPath, freespecPath) {
+        const languageContext = this.languageContext();
+        if (!languageContext)
+            return;
+        const configPath = path.join(freespecPath, 'config.yaml');
+        const hasConfig = fs.existsSync(configPath) ||
+            fs.existsSync(path.join(freespecPath, 'config.yml'));
+        if (!hasConfig) {
+            try {
+                FileSystemUtils.assertProjectArtifactPath(projectPath, configPath);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? `: ${error.message}` : '';
+                throw new Error(`Cannot create freespec/config.yaml for --language${reason}`);
+            }
+            if (!(await FileSystemUtils.canWriteFile(configPath))) {
+                throw new Error('Cannot create freespec/config.yaml for --language: the destination is not writable.');
+            }
+            return;
+        }
+        const existingContext = readProjectConfig(projectPath)?.context;
+        if (existingContext?.includes(languageContext))
+            return;
+        throw new Error('--language does not overwrite an existing FreeSpec config. ' +
+            'Add the language instruction to its context field instead.');
+    }
+    async createConfig(freespecPath, extendMode) {
+        const configPath = path.join(freespecPath, 'config.yaml');
+        const configYmlPath = path.join(freespecPath, 'config.yml');
+        const configYamlExists = fs.existsSync(configPath);
+        const configYmlExists = fs.existsSync(configYmlPath);
+        if (configYamlExists || configYmlExists) {
+            return 'exists';
+        }
+        try {
+            const yamlContent = serializeConfig({
+                schema: DEFAULT_SCHEMA,
+                context: this.languageContext(),
+            });
+            FileSystemUtils.assertProjectArtifactPath(path.dirname(freespecPath), configPath);
+            await FileSystemUtils.writeFile(configPath, yamlContent);
+            return 'created';
+        }
+        catch (error) {
+            if (this.language) {
+                const reason = error instanceof Error ? `: ${error.message}` : '';
+                throw new Error(`Failed to create freespec/config.yaml for --language${reason}`);
+            }
+            return 'skipped';
+        }
+    }
+    // ═══════════════════════════════════════════════════════════
+    // UI & OUTPUT
+    // ═══════════════════════════════════════════════════════════
+    displaySuccessMessage(projectPath, tools, results, configStatus) {
+        console.log();
+        console.log(chalk.bold(results.failedTools.length > 0 ? 'FreeSpec Setup Incomplete' : 'FreeSpec Setup Complete'));
+        console.log();
+        // Show created vs refreshed tools
+        if (results.createdTools.length > 0) {
+            console.log(`Created: ${results.createdTools.map((t) => t.name).join(', ')}`);
+        }
+        if (results.refreshedTools.length > 0) {
+            console.log(`Refreshed: ${results.refreshedTools.map((t) => t.name).join(', ')}`);
+        }
+        // Show counts (respecting profile filter)
+        const successfulTools = [...results.createdTools, ...results.refreshedTools];
+        if (successfulTools.length > 0) {
+            const globalConfig = getGlobalConfig();
+            const profile = this.profileOverride ?? globalConfig.profile ?? 'core';
+            const delivery = globalConfig.delivery ?? 'both';
+            const workflows = getProfileWorkflows(profile, globalConfig.workflows);
+            const usesGlobalSkillTarget = successfulTools.some((tool) => tool.isGlobalSkillTarget);
+            if (!usesGlobalSkillTarget) {
+                const toolDirs = [
+                    ...new Set(successfulTools
+                        .map((tool) => tool.skillsDir)
+                        .filter((skillsDir) => Boolean(skillsDir))),
+                ].join(', ');
+                const skillCount = successfulTools.some((tool) => shouldGenerateSkillsForTool(tool.value, delivery))
+                    ? getSkillTemplates(workflows).length
+                    : 0;
+                const commandCount = successfulTools.some((tool) => shouldGenerateCommandsForTool(tool.value, delivery))
+                    ? getCommandContents(workflows).length
+                    : 0;
+                if (skillCount > 0 && commandCount > 0) {
+                    console.log(`${skillCount} skills and ${commandCount} commands in ${toolDirs}/`);
+                }
+                else if (skillCount > 0) {
+                    console.log(`${skillCount} skills in ${toolDirs}/`);
+                }
+                else if (commandCount > 0) {
+                    console.log(`${commandCount} commands in ${toolDirs}/`);
+                }
+            }
+            else {
+                const skillTools = successfulTools.filter((tool) => shouldGenerateSkillsForTool(tool.value, delivery));
+                const skillCount = skillTools.length * getSkillTemplates(workflows).length;
+                if (skillCount > 0) {
+                    const skillDirs = [...new Set(skillTools.map((tool) => tool.skillsPath))];
+                    console.log(`${skillCount} skills in ${skillDirs.join(', ')}`);
+                }
+                const commandContents = getCommandContents(workflows);
+                const commandTools = successfulTools.filter((tool) => shouldGenerateCommandsForTool(tool.value, delivery));
+                const commandCount = commandTools.length * commandContents.length;
+                if (commandCount > 0) {
+                    const commandDirs = [
+                        ...new Set(commandTools.flatMap((tool) => {
+                            const adapter = CommandAdapterRegistry.get(tool.value);
+                            if (!adapter)
+                                return [];
+                            return commandContents.map((command) => {
+                                const commandPath = adapter.getFilePath(command.id);
+                                const absolutePath = path.isAbsolute(commandPath)
+                                    ? commandPath
+                                    : path.join(projectPath, commandPath);
+                                return path.dirname(absolutePath);
+                            });
+                        })),
+                    ];
+                    console.log(`${commandCount} commands in ${commandDirs.join(', ')}`);
+                }
+            }
+        }
+        // Show failures
+        if (results.failedTools.length > 0) {
+            console.log(chalk.red(`Failed: ${results.failedTools.map((f) => `${f.name} (${f.error.message})`).join(', ')}`));
+        }
+        // Show skipped commands
+        if (results.commandsSkipped.length > 0) {
+            console.log(chalk.dim(`Commands skipped for: ${results.commandsSkipped.join(', ')} (no adapter)`));
+        }
+        if (results.skillsInvocableCommandSkips.length > 0) {
+            console.log(chalk.dim(`Commands skipped for: ${results.skillsInvocableCommandSkips.join(', ')} (uses skills)`));
+        }
+        if (results.removedCommandCount > 0) {
+            console.log(chalk.dim(`Removed: ${results.removedCommandCount} command files (delivery: skills)`));
+        }
+        if (results.removedSkillCount > 0) {
+            console.log(chalk.dim(`Removed: ${results.removedSkillCount} skill directories (delivery: commands)`));
+        }
+        // Show manual setup notes for tools that need extra configuration
+        for (const tool of successfulTools) {
+            const setupNote = AI_TOOLS.find((t) => t.value === tool.value)?.setupNote;
+            if (setupNote) {
+                console.log(chalk.yellow(`Setup required for ${tool.name}: ${setupNote}`));
+            }
+        }
+        // Config status
+        if (configStatus === 'created') {
+            console.log(`Config: freespec/config.yaml (schema: ${DEFAULT_SCHEMA})`);
+        }
+        else if (configStatus === 'exists') {
+            // Show actual filename (config.yaml or config.yml)
+            const configYaml = path.join(projectPath, OPENSPEC_DIR_NAME, 'config.yaml');
+            const configYml = path.join(projectPath, OPENSPEC_DIR_NAME, 'config.yml');
+            const configName = fs.existsSync(configYaml) ? 'config.yaml' : fs.existsSync(configYml) ? 'config.yml' : 'config.yaml';
+            console.log(`Config: freespec/${configName} (exists)`);
+        }
+        else {
+            console.log(chalk.dim(`Config: skipped (non-interactive mode)`));
+        }
+        // Getting started (task 7.6: show propose if in profile)
+        const activeWorkflows = this.getActiveWorkflows();
+        // When no tool got /freespec:* commands, point at the skill instead of a
+        // command that does not exist.
+        const activeDelivery = getGlobalConfig().delivery ?? 'both';
+        const commandsGenerated = successfulTools.some((tool) => shouldGenerateCommandsForTool(tool.value, activeDelivery));
+        const skillsGenerated = successfulTools.some((tool) => shouldGenerateSkillsForTool(tool.value, activeDelivery));
+        // Each hint line must be a usable instruction for the tool it serves.
+        // Tools that generated commands are told the command name their files
+        // answer to (/freespec:* when namespaced under freespec/, /freespec-* when the
+        // filename is the command); tools that only got skills are told their
+        // documented skill invocation (Kimi Code: /skill:freespec-*; Codex CLI:
+        // $freespec-*; others: /freespec-*). Tools that got no artifacts are
+        // covered by the configuration correction instead. When the selection
+        // disagrees, print one line per distinct instruction, labeled with the
+        // tools it applies to.
+        const startHintLines = (command) => {
+            const hintToTools = new Map();
+            for (const tool of successfulTools) {
+                let hint;
+                if (shouldGenerateCommandsForTool(tool.value, activeDelivery)) {
+                    const transformer = getTransformerForTool(tool.value, activeDelivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
+                    hint = `Start your first change: ${transformer ? transformer(command) : command} "your idea"`;
+                }
+                else if (shouldGenerateSkillsForTool(tool.value, activeDelivery)) {
+                    const skillReference = getSkillReferenceTransformer(tool.value)(command);
+                    // Tools with no slash surface (e.g. Rovo Dev) reference skills as
+                    // prose ("the freespec-propose skill"); phrase the hint so it reads
+                    // as an instruction rather than a dead command with an argument.
+                    if (usesNaturalLanguageSkillReferences(tool.value)) {
+                        hint = `Start your first change: ask ${tool.name} to use ${skillReference} with "your idea"`;
+                    }
+                    else if (tool.value === 'codex') {
+                        hint = `Start your first change: ${skillReference} "your idea" (Codex CLI or IDE); in the Codex desktop app, select ${skillReference.slice(1)} from Skills in the sidebar`;
+                    }
+                    else {
+                        hint = `Start your first change: ${skillReference} "your idea"`;
+                    }
+                }
+                else {
+                    continue;
+                }
+                hintToTools.set(hint, [...(hintToTools.get(hint) ?? []), tool.name]);
+            }
+            if (hintToTools.size === 0) {
+                // No successful tools: keep the generic command hint
+                return [`Start your first change: ${command} "your idea"`];
+            }
+            if (hintToTools.size === 1) {
+                return [[...hintToTools.keys()][0]];
+            }
+            return [...hintToTools.entries()].map(([hint, toolNames]) => `${hint} (${toolNames.join(', ')})`);
+        };
+        const printStartHints = (command) => {
+            console.log(chalk.bold('Getting started:'));
+            for (const line of startHintLines(command)) {
+                console.log(`  ${line}`);
+            }
+        };
+        console.log();
+        // delivery=commands with tools that only support skills: those tools get
+        // no artifacts at all, so print a per-tool configuration correction
+        // rather than leave them with a dead (or missing) instruction — even
+        // when other selected tools did get commands or skills.
+        const zeroArtifactTools = successfulTools.filter((tool) => !shouldGenerateSkillsForTool(tool.value, activeDelivery) &&
+            !shouldGenerateCommandsForTool(tool.value, activeDelivery));
+        if (zeroArtifactTools.length > 0) {
+            const names = zeroArtifactTools.map((tool) => tool.name).join(', ');
+            console.log(chalk.yellow(`No skills or commands were generated for ${names}: delivery is set to 'commands' but ` +
+                `${zeroArtifactTools.length === 1 ? 'it supports' : 'they support'} only skills. ` +
+                `Run 'freespec config set delivery both' to generate skills.`));
+        }
+        if (!(successfulTools.length > 0 && !commandsGenerated && !skillsGenerated)) {
+            if (activeWorkflows.includes('新建')) {
+                printStartHints('/freespec:新建');
+            }
+            else {
+                console.log("Done. Run 'freespec config profile' to configure your workflows.");
+            }
+        }
+        // Links
+        console.log();
+        console.log(`Learn more: ${chalk.cyan('https://gitee.com/niu_jiajie/openspec.git')}`);
+        console.log(`Feedback:   ${chalk.cyan('https://gitee.com/niu_jiajie/openspec/issues')}`);
+        // Restart instruction for successfully configured IDE/editor-resident tools
+        // with a supported surface under the active delivery. The rule and wording live in
+        // formatIdeRestart so `update` says the same thing for the same event.
+        const restartHint = formatIdeRestart(successfulTools.map((tool) => tool.value), activeDelivery);
+        if (restartHint) {
+            console.log();
+            console.log(chalk.white(restartHint));
+        }
+        console.log();
+    }
+    startSpinner(text) {
+        return ora({
+            text,
+            stream: process.stdout,
+            color: 'gray',
+            spinner: PROGRESS_SPINNER,
+        }).start();
+    }
+    async removeSkillDirs(skillsRoot, skillsDir) {
+        let removed = 0;
+        for (const dirName of Object.values(WORKFLOW_TO_SKILL_DIR)) {
+            const skillDir = path.join(skillsDir, dirName);
+            if (!fs.existsSync(skillDir))
+                continue;
+            FileSystemUtils.assertPathWithin(skillsRoot, skillDir);
+            try {
+                await fs.promises.rm(skillDir, { recursive: true, force: true });
+                removed++;
+            }
+            catch {
+                // Ignore errors
+            }
+        }
+        return 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 = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmdPath);
+            try {
+                if (fs.existsSync(fullPath)) {
+                    await fs.promises.unlink(fullPath);
+                    removed++;
+                }
+            }
+            catch {
+                // Ignore errors
+            }
+        }
+        return removed;
+    }
+}
+//# sourceMappingURL=init.js.map