@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/core/update.js

@@ -0,0 +1,723 @@
+/**
+ * Update Command
+ *
+ * Refreshes FreeSpec 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 { createRequire } from 'module';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { getTransformerForTool } from '../utils/command-references.js';
+import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
+import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
+import { getToolSkillStatus, getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, copySkillExtras, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, formatIdeRestart, } from './shared/index.js';
+import { isInteractive } from '../utils/interactive.js';
+import { getGlobalConfig, getGlobalConfigPath, serializeGlobalConfig } from './global-config.js';
+import { getProfileWorkflows, ALL_WORKFLOWS, CORE_WORKFLOWS } from './profiles.js';
+import { getAvailableTools } from './available-tools.js';
+import { WORKFLOW_TO_SKILL_DIR, getConfiguredToolsForProfileSync, getToolsNeedingProfileSync, } from './profile-sync-drift.js';
+import { scanInstalledWorkflows as scanInstalledWorkflowsShared, migrateIfNeeded as migrateIfNeededShared, computeProfileMigration, applyProfileMigration, findLegacyToolMigrations, planLegacyToolMigrations, migrateLegacyToolDirs, describeLegacyMigration, legacyMigrationNotice, keptInPlaceNotice, hasMovableContent, } from './migration.js';
+import { resolveCommandSurfaceCapability, resolveCommandInvocation, shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
+import { resolveSharedSkillWriters, sharedSkillTargetMarkerPath, } from './shared-skill-target.js';
+import { DISK_VIEW } from './file-view.js';
+import { realFileOps, UpdatePlanRecorder, } from './update-plan.js';
+const require = createRequire(import.meta.url);
+const { version: OPENSPEC_VERSION } = require('../../package.json');
+function throwIfUpdateFailed(failedTools) {
+    if (failedTools.length > 0) {
+        throw new Error(`FreeSpec update failed for: ${failedTools.map((tool) => tool.name).join(', ')}`);
+    }
+}
+/**
+ * Checkout artifacts that are not real content drift: a UTF-8 BOM and the CRLF
+ * line endings a Windows clone with `core.autocrlf` reintroduces on every
+ * checkout of committed generated files.
+ */
+function normalizeGeneratedFile(content) {
+    return content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+}
+/**
+ * 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, view) {
+    const tools = toolIds
+        .map((id) => AI_TOOLS.find((t) => t.value === id))
+        .filter((t) => t != null);
+    return scanInstalledWorkflowsShared(projectPath, tools, view);
+}
+export class UpdateCommand {
+    force;
+    dryRun;
+    recorder = null;
+    ops = realFileOps;
+    constructor(options = {}) {
+        this.force = options.force ?? false;
+        this.dryRun = options.dryRun ?? false;
+    }
+    /**
+     * Reports what `execute` would add, change or delete, writing nothing.
+     *
+     * Same code path as the real update: the plan is recorded by the write seam
+     * the generation loop already goes through, so it cannot drift from it.
+     */
+    async plan(projectPath) {
+        if (!this.dryRun) {
+            throw new Error('plan() requires the update command to be constructed with dryRun: true');
+        }
+        await this.execute(projectPath);
+        return this.recorder?.getPlan() ?? { changes: [], notes: [], failures: [] };
+    }
+    /** Prints progress on a real run, stays quiet while planning. */
+    log(...args) {
+        if (this.dryRun)
+            return;
+        console.log(...args);
+    }
+    /** A spinner on a real run, a no-op while planning. */
+    startSpinner(text) {
+        if (this.dryRun) {
+            return { succeed: () => { }, fail: () => { }, info: () => { } };
+        }
+        return ora(text).start();
+    }
+    /**
+     * Refreshes FreeSpec skills and commands for all configured tools,
+     * regenerating artifacts according to the effective profile and delivery mode.
+     *
+     * @param projectPath - Path to the project root containing the freespec directory
+     */
+    async execute(projectPath) {
+        const resolvedProjectPath = path.resolve(projectPath);
+        const freespecPath = path.join(resolvedProjectPath, OPENSPEC_DIR_NAME);
+        if (this.dryRun) {
+            this.recorder = new UpdatePlanRecorder(resolvedProjectPath);
+            this.ops = this.recorder;
+        }
+        // 1. Check freespec directory exists
+        if (!await FileSystemUtils.directoryExists(freespecPath)) {
+            throw new Error(`No FreeSpec directory found. Run 'freespec init' first.`);
+        }
+        // 2. Migrate FreeSpec-managed skills left in renamed tool directories
+        // (e.g. .kimi -> .kimi-code) so they stay detected and get refreshed,
+        // then perform the one-time profile migration if needed before any
+        // legacy upgrade generation.
+        if (!this.dryRun) {
+            for (const migration of migrateLegacyToolDirs(resolvedProjectPath)) {
+                if (hasMovableContent(migration)) {
+                    this.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+                }
+                this.reportKeptInPlace(migration);
+            }
+        }
+        // A dry run plans the same moves. Every later step reads `this.view` -
+        // the disk in a real run, the tree as planned in a dry run - so it sees
+        // the moved files exactly as the real update would.
+        if (this.dryRun) {
+            await this.planLegacyToolMoves(resolvedProjectPath, 'before-generation');
+        }
+        const declinedMigrations = this.dryRun
+            ? []
+            : await this.offerConsentedLegacyMigrations(resolvedProjectPath);
+        // Use detected tool directories to preserve existing freespec skills/commands.
+        const detectedTools = getAvailableTools(resolvedProjectPath, this.view);
+        if (!this.dryRun) {
+            migrateIfNeededShared(resolvedProjectPath, detectedTools);
+        }
+        // 3. Read global config for profile/delivery. A dry run plans the one-time
+        //    profile migration's save instead of making it, and resolves against
+        //    the config that save would leave — otherwise the preview would plan
+        //    for a different profile than the real update acts on.
+        let globalConfig = getGlobalConfig();
+        if (this.recorder) {
+            const migration = computeProfileMigration(resolvedProjectPath, detectedTools, this.view);
+            if (migration) {
+                globalConfig = applyProfileMigration(migration);
+                await this.recorder.writeFile(getGlobalConfigPath(), serializeGlobalConfig(globalConfig), 'freespec');
+            }
+        }
+        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));
+        // 5. Find configured tools
+        const configuredTools = getConfiguredToolsForProfileSync(resolvedProjectPath, this.view);
+        if (configuredTools.length === 0) {
+            if (declinedMigrations.length > 0) {
+                // Not an unconfigured project — a configured one the user chose to
+                // leave in its former directory. Saying "run init" would be wrong.
+                for (const migration of declinedMigrations) {
+                    this.log(chalk.yellow(`Nothing to update: this project's FreeSpec files are still in ${migration.from}/, ` +
+                        `which FreeSpec no longer writes.`));
+                    this.log(chalk.dim(`Re-run "freespec update" and accept the move to ${migration.to}/ to resume updates.`));
+                }
+                return;
+            }
+            this.log(chalk.yellow('No configured tools found.'));
+            this.log(chalk.dim('Run "freespec init" to set up tools.'));
+            return;
+        }
+        // 6. Check version status for all configured tools, against the same workflow set
+        //    the generation loop below writes — otherwise a legacy-upgraded tool would be
+        //    fingerprinted against commands it was never given.
+        const toolStatuses = configuredTools.map((toolId) => getToolVersionStatus(resolvedProjectPath, toolId, OPENSPEC_VERSION, {
+            workflows: desiredWorkflows,
+            delivery,
+            view: this.view,
+        }));
+        const statusByTool = new Map(toolStatuses.map((status) => [status.toolId, status]));
+        // 7. Smart update detection
+        const toolsNeedingVersionUpdate = toolStatuses
+            .filter((s) => {
+            if (!s.needsUpdate || delivery !== 'commands') {
+                return s.needsUpdate;
+            }
+            const tool = AI_TOOLS.find((candidate) => candidate.value === s.toolId);
+            return !tool || !hasGlobalSkillTarget(tool);
+        })
+            .map((s) => s.toolId);
+        const toolsNeedingConfigSync = getToolsNeedingProfileSync(resolvedProjectPath, desiredWorkflows, delivery, configuredTools, this.view);
+        const toolsWithDriftedSkills = this.findToolsWithDriftedSkills(resolvedProjectPath, configuredTools, delivery, (toolId) => desiredWorkflows);
+        const toolsToUpdateSet = new Set([
+            ...toolsNeedingVersionUpdate,
+            ...toolsNeedingConfigSync,
+            ...toolsWithDriftedSkills,
+        ]);
+        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.displayProfileNotes(resolvedProjectPath, configuredTools, desiredWorkflows, profile, delivery);
+            this.displaySetupNotes(configuredTools);
+            return;
+        }
+        // 8. Display update plan
+        if (this.force) {
+            this.log(`Force updating ${configuredTools.length} tool(s): ${configuredTools.join(', ')}`);
+        }
+        else {
+            this.displayUpdatePlan([...toolsToUpdateSet], statusByTool, toolsUpToDate, new Set(toolsWithDriftedSkills));
+        }
+        this.log();
+        // 9. Determine what to generate based on delivery
+        const deliveryIncludesCommands = delivery !== 'skills';
+        // 10. Update tools (all if force, otherwise only those needing update)
+        const toolsToUpdate = this.force ? configuredTools : [...toolsToUpdateSet];
+        const sharedSkillWriters = resolveSharedSkillWriters(resolvedProjectPath, configuredTools
+            .map((toolId) => AI_TOOLS.find((tool) => tool.value === toolId))
+            .filter((tool) => tool !== undefined), this.view);
+        const updatedTools = [];
+        const updatedToolIds = [];
+        const failedTools = [];
+        const skillsInvocableCommandSkips = [];
+        const zeroArtifactTools = [];
+        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 || !toolSupportsSkills(tool))
+                continue;
+            const spinner = this.startSpinner(`Updating ${tool.name}...`);
+            try {
+                const skillsDir = resolveToolSkillsDir(resolvedProjectPath, tool);
+                const skillsRoot = hasGlobalSkillTarget(tool) ? skillsDir : resolvedProjectPath;
+                const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
+                const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
+                const writesSkills = !tool.skillsDir || sharedSkillWriters.has(tool.value);
+                const toolWorkflows = desiredWorkflows;
+                const skillTemplates = getSkillTemplates(toolWorkflows);
+                const commandContents = getCommandContents(toolWorkflows);
+                // Generate skill files if delivery includes skills
+                if (shouldGenerateSkills && writesSkills) {
+                    for (const { template, dirName } of skillTemplates) {
+                        const skillDir = path.join(skillsDir, dirName);
+                        const skillFile = path.join(skillDir, 'SKILL.md');
+                        const transformer = getTransformerForTool(tool.value, delivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
+                        const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
+                        FileSystemUtils.assertPathWithin(skillsRoot, skillFile);
+                        await this.ops.writeFile(skillFile, skillContent, tool.value);
+                        await copySkillExtras(skillDir, template.name);
+                    }
+                    await this.writeSharedSkillTarget(resolvedProjectPath, tool.value);
+                    removedDeselectedSkillCount += await this.removeUnselectedSkillDirs(skillsRoot, skillsDir, toolWorkflows, tool.value);
+                }
+                // Delete skill directories if delivery is commands-only
+                if (shouldRemoveSkillsForTool(tool.value, delivery) &&
+                    writesSkills &&
+                    !hasGlobalSkillTarget(tool)) {
+                    removedSkillCount += await this.removeSkillDirs(skillsRoot, skillsDir, tool.value);
+                    // Persist the selected owner even when commands-only delivery leaves
+                    // this target with no generated skills.
+                    await this.writeSharedSkillTarget(resolvedProjectPath, tool.value);
+                    // A tool with no command adapter now has zero FreeSpec artifacts;
+                    // say so like init does, rather than deleting its skills silently
+                    // and letting tool detection re-suggest an init that would also
+                    // generate nothing under this delivery setting.
+                    if (!shouldGenerateCommandsForTool(tool.value, delivery)) {
+                        zeroArtifactTools.push(tool.name);
+                    }
+                }
+                // 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(resolvedProjectPath, cmd.path);
+                            await this.ops.writeFile(commandFile, cmd.fileContent, tool.value);
+                        }
+                        removedDeselectedCommandCount += await this.removeUnselectedCommandFiles(resolvedProjectPath, toolId, toolWorkflows);
+                    }
+                }
+                else if (deliveryIncludesCommands && resolveCommandSurfaceCapability(tool.value) === 'skills-invocable') {
+                    skillsInvocableCommandSkips.push(tool.value);
+                }
+                // Delete command files if delivery is skills-only
+                if (shouldReconcileCommandFilesForTool(tool.value, delivery)) {
+                    removedCommandCount += await this.removeCommandFiles(resolvedProjectPath, toolId);
+                }
+                spinner.succeed(`Updated ${tool.name}`);
+                updatedTools.push(tool.name);
+                updatedToolIds.push(tool.value);
+                if (!this.dryRun) {
+                    for (const migration of migrateLegacyToolDirs(resolvedProjectPath, [tool.value], 'after-generation')) {
+                        if (hasMovableContent(migration)) {
+                            this.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+                        }
+                        this.reportKeptInPlace(migration);
+                    }
+                }
+                else {
+                    await this.planLegacyToolMoves(resolvedProjectPath, 'after-generation', [tool.value]);
+                }
+            }
+            catch (error) {
+                spinner.fail(`Failed to update ${tool.name}`);
+                const message = error instanceof Error ? error.message : String(error);
+                failedTools.push({ name: tool.name, error: message });
+                // A dry run reports the failure in the plan rather than throwing it:
+                // one broken tool must not cost the caller the other tools' changes.
+                this.recorder?.addFailure(tool.value, message);
+            }
+        }
+        // 11. Summary
+        this.log();
+        if (updatedTools.length > 0) {
+            this.log(chalk.green(`✓ Updated: ${updatedTools.join(', ')} (v${OPENSPEC_VERSION})`));
+        }
+        if (failedTools.length > 0) {
+            this.log(chalk.red(`✗ Failed: ${failedTools.map(f => `${f.name} (${f.error})`).join(', ')}`));
+        }
+        if (skillsInvocableCommandSkips.length > 0) {
+            this.log(chalk.dim(`Commands skipped for: ${skillsInvocableCommandSkips.join(', ')} (uses skills)`));
+        }
+        if (removedCommandCount > 0) {
+            this.log(chalk.dim(`Removed: ${removedCommandCount} command files (delivery: skills)`));
+        }
+        if (removedSkillCount > 0) {
+            this.log(chalk.dim(`Removed: ${removedSkillCount} skill directories (delivery: commands)`));
+        }
+        if (zeroArtifactTools.length > 0) {
+            const names = zeroArtifactTools.join(', ');
+            this.log(chalk.yellow(`No skills or commands remain 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 (removedDeselectedCommandCount > 0) {
+            this.log(chalk.dim(`Removed: ${removedDeselectedCommandCount} command files (deselected workflows)`));
+        }
+        if (removedDeselectedSkillCount > 0) {
+            this.log(chalk.dim(`Removed: ${removedDeselectedSkillCount} skill directories (deselected workflows)`));
+        }
+        // 13. Detect new tool directories not currently configured
+        this.detectNewTools(resolvedProjectPath, configuredTools);
+        // 14. Display the profile notes
+        this.displayProfileNotes(resolvedProjectPath, configuredTools, desiredWorkflows, profile, delivery);
+        this.displaySetupNotes(configuredTools);
+        // 15. List affected tools
+        if (updatedTools.length > 0) {
+            const toolDisplayNames = updatedTools;
+            this.log(chalk.dim(`Tools: ${toolDisplayNames.join(', ')}`));
+        }
+        this.log();
+        const affectedToolIds = updatedToolIds;
+        const restartHint = formatIdeRestart(affectedToolIds, delivery);
+        if (restartHint) {
+            this.log(chalk.dim(restartHint));
+        }
+        this.stopIfUpdateFailed(failedTools);
+    }
+    /**
+     * Records the shared-skills-root owner through the write seam, so a dry run
+     * lists the marker file a real update would write.
+     */
+    async writeSharedSkillTarget(projectPath, toolId) {
+        const marker = sharedSkillTargetMarkerPath(projectPath, toolId);
+        if (!marker)
+            return;
+        FileSystemUtils.assertProjectArtifactPath(projectPath, marker);
+        await this.ops.writeFile(marker, `${toolId}\n`, toolId);
+    }
+    /**
+     * Where a real update throws for failed tools, it also stops. A dry run
+     * stops at the same point - so it plans nothing the real update would not
+     * reach - but returns instead of throwing: the failures are already in the
+     * plan, and the caller still gets every change planned before them.
+     *
+     * @returns whether the update stops here.
+     */
+    stopIfUpdateFailed(failedTools) {
+        if (!this.dryRun)
+            throwIfUpdateFailed(failedTools);
+        return failedTools.length > 0;
+    }
+    /** The tree as the real update would see it at this point. */
+    get view() {
+        return this.recorder?.view ?? DISK_VIEW;
+    }
+    /**
+     * Plans the moves out of former tool roots that a non-interactive update
+     * makes, against the tree as planned so far.
+     */
+    async planLegacyToolMoves(projectPath, timing, toolIds) {
+        const recorder = this.recorder;
+        if (!recorder)
+            return;
+        for (const op of planLegacyToolMigrations(projectPath, timing, toolIds, recorder.view)) {
+            try {
+                if (op.disposition === 'move') {
+                    await recorder.moveFile(op.source, op.destination, op.toolId);
+                }
+                else {
+                    await recorder.removeFile(op.source, op.toolId);
+                }
+            }
+            catch {
+                // The real migration leaves a file it cannot move where it is, and
+                // says nothing; so does the plan.
+                continue;
+            }
+            if (op.needsConsent) {
+                recorder.addNote('legacy-tool-directories', 'Moves out of a renamed tool directory are listed as a non-interactive update makes them. At a terminal, update asks first, and declining leaves those files where they are.');
+            }
+        }
+    }
+    /**
+     * Tools whose SKILL.md bodies no longer match what this CLI generates.
+     *
+     * Skill freshness was decided solely by the `generatedBy:` line, so a body
+     * edited after generation — a "helpful" PR touching `.claude/skills/**`, a
+     * dotfile sync, another agent — left `update` reporting the install healthy.
+     * Command files never had that gap: `areCommandFilesUpToDate` content-
+     * compares them, and the same comparison belongs on the higher-authority
+     * surface. A missing skill file is left to the profile-sync check, which
+     * already knows what a partial install means.
+     */
+    findToolsWithDriftedSkills(projectPath, toolIds, delivery, workflowsForTool) {
+        return toolIds.filter((toolId) => {
+            const tool = AI_TOOLS.find((t) => t.value === toolId);
+            if (!tool || !toolSupportsSkills(tool))
+                return false;
+            if (!shouldGenerateSkillsForTool(tool.value, delivery))
+                return false;
+            // A shared skills root is generated with its owner's transformer, so
+            // only the owner may compare it. getToolSkillStatus settles ownership.
+            if (!getToolSkillStatus(projectPath, tool.value, this.view).configured)
+                return false;
+            const skillsDir = resolveToolSkillsDir(projectPath, tool);
+            const transformer = getTransformerForTool(tool.value, delivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
+            return getSkillTemplates(workflowsForTool(toolId)).some(({ template, dirName }) => {
+                const skillFile = path.join(skillsDir, dirName, 'SKILL.md');
+                if (!this.view.exists(skillFile))
+                    return false;
+                try {
+                    const existing = this.view.read(skillFile);
+                    const generated = generateSkillContent(template, OPENSPEC_VERSION, transformer);
+                    return normalizeGeneratedFile(existing) !== normalizeGeneratedFile(generated);
+                }
+                catch {
+                    return true;
+                }
+            });
+        });
+    }
+    /**
+     * Display message when all tools are up to date.
+     */
+    displayUpToDateMessage(toolStatuses) {
+        const toolNames = toolStatuses.map((s) => s.toolId);
+        this.log(chalk.green(`✓ All ${toolStatuses.length} tool(s) up to date (v${OPENSPEC_VERSION})`));
+        this.log(chalk.dim(`  Tools: ${toolNames.join(', ')}`));
+        this.log();
+        this.log(chalk.dim('Use --force to refresh files anyway.'));
+    }
+    /**
+     * Display the update plan showing which tools need updating.
+     */
+    displayUpdatePlan(toolsToUpdate, statusByTool, upToDate, driftedSkills = new Set()) {
+        const updates = toolsToUpdate.map((toolId) => {
+            const status = statusByTool.get(toolId);
+            if (status?.needsUpdate) {
+                const fromVersion = status.generatedByVersion ?? 'unknown';
+                return `${status.toolId} (${fromVersion} → ${OPENSPEC_VERSION})`;
+            }
+            // Say why: a user who edited a SKILL.md on purpose is owed the reason
+            // their edit is about to be overwritten.
+            if (driftedSkills.has(toolId)) {
+                return `${toolId} (skill files differ from the generated content)`;
+            }
+            return `${toolId} (config sync)`;
+        });
+        this.log(`Updating ${toolsToUpdate.length} tool(s): ${updates.join(', ')}`);
+        if (upToDate.length > 0) {
+            const upToDateNames = upToDate.map((s) => s.toolId);
+            this.log(chalk.dim(`Already up to date: ${upToDateNames.join(', ')}`));
+        }
+    }
+    /**
+     * Shows manual setup notes for configured tools that need extra
+     * configuration before they pick up generated files.
+     */
+    displaySetupNotes(toolIds) {
+        for (const toolId of toolIds) {
+            const tool = AI_TOOLS.find((t) => t.value === toolId);
+            if (tool?.setupNote) {
+                this.log(chalk.yellow(`Setup required for ${tool.name}: ${tool.setupNote}`));
+            }
+        }
+    }
+    /**
+     * 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';
+            this.log();
+            this.log(chalk.yellow(`Detected new ${toolNoun}: ${newToolNames.join(', ')}. Run 'freespec init' to add ${pronoun}.`));
+        }
+    }
+    /**
+     * Prints the profile notes, in order, with one pointer at
+     * `freespec config profile` rather than three.
+     *
+     * Every note is evaluated: reading them as one short-circuited `||` chain
+     * would swallow whichever ran second.
+     */
+    displayProfileNotes(projectPath, configuredTools, desiredWorkflows, profile, _delivery) {
+        this.displayExtraWorkflowsNote(projectPath, configuredTools, desiredWorkflows ?? []);
+        this.displayMissingCoreWorkflowsNote(profile, desiredWorkflows);
+    }
+    /**
+     * 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) {
+            this.log(chalk.dim(`Note: ${extraWorkflows.length} extra workflows not in profile (use \`freespec config profile\` to manage)`));
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Point out core workflows a custom profile is missing, so releases that
+     * grow CORE_WORKFLOWS stay discoverable. Keep custom profiles user-owned;
+     * do not mutate them.
+     */
+    displayMissingCoreWorkflowsNote(profile, workflows) {
+        if (profile !== 'custom' || !workflows) {
+            return false;
+        }
+        const workflowSet = new Set(workflows);
+        const missing = CORE_WORKFLOWS.filter((workflow) => !workflowSet.has(workflow));
+        if (missing.length === 0) {
+            return false;
+        }
+        const label = missing.length === 1 ? 'workflow' : 'workflows';
+        const pronoun = missing.length === 1 ? 'it' : 'them';
+        this.log(chalk.dim(`Note: Your custom profile is missing ${missing.length} core ${label}: ${missing.join(', ')}`));
+        this.log(chalk.dim(`Run \`freespec config profile\` to add ${pronoun}, or \`freespec config profile core\` to use the core set.`));
+        return true;
+    }
+    /**
+     * Removes skill directories for workflows when delivery changed to commands-only.
+     * Returns the number of directories removed.
+     */
+    async removeSkillDirs(skillsRoot, skillsDir, toolId) {
+        let removed = 0;
+        for (const dirName of Object.values(WORKFLOW_TO_SKILL_DIR)) {
+            const skillDir = path.join(skillsDir, dirName);
+            if (!this.view.exists(skillDir))
+                continue;
+            FileSystemUtils.assertPathWithin(skillsRoot, skillDir);
+            try {
+                await this.ops.removeDirectory(skillDir, toolId);
+                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(skillsRoot, skillsDir, desiredWorkflows, toolId) {
+        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);
+            if (!this.view.exists(skillDir))
+                continue;
+            FileSystemUtils.assertPathWithin(skillsRoot, skillDir);
+            try {
+                await this.ops.removeDirectory(skillDir, toolId);
+                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 = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmdPath);
+            try {
+                if (this.view.exists(fullPath)) {
+                    await this.ops.removeFile(fullPath, toolId);
+                    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 = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmdPath);
+            try {
+                if (this.view.exists(fullPath)) {
+                    await this.ops.removeFile(fullPath, toolId);
+                    removed++;
+                }
+            }
+            catch {
+                // Ignore errors
+            }
+        }
+        return removed;
+    }
+    /**
+     * Offers to move FreeSpec content out of a renamed tool's former directory
+     * when the old location might still be the live one — today, Windsurf's
+     * `.windsurf/` after the Devin Desktop rebrand.
+     *
+     * Interactive runs are asked, because nothing on disk distinguishes a user
+     * who took the rebrand from one still on a pre-rebrand Windsurf build that
+     * reads only `.windsurf/`. `--force` and non-interactive runs migrate, which
+     * is what an unattended upgrade wants.
+     */
+    /** Surfaces files the move left behind rather than overwriting. */
+    reportKeptInPlace(migration) {
+        const notice = keptInPlaceNotice(migration);
+        if (notice)
+            this.log(chalk.dim(notice));
+    }
+    async offerConsentedLegacyMigrations(projectPath) {
+        const pending = findLegacyToolMigrations(projectPath).filter((m) => m.needsConsent);
+        const declined = [];
+        if (pending.length === 0)
+            return declined;
+        for (const migration of pending) {
+            // Nothing movable: every legacy file differs from its counterpart, so
+            // there is no move to offer. Still say so — silence would leave two
+            // divergent copies the user never hears about.
+            if (!hasMovableContent(migration)) {
+                this.reportKeptInPlace(migration);
+                this.log();
+                continue;
+            }
+            this.log(chalk.yellow(legacyMigrationNotice(migration)));
+            if (!this.force && isInteractive()) {
+                const { confirm } = await import('@inquirer/prompts');
+                let shouldMigrate;
+                try {
+                    shouldMigrate = await confirm({
+                        message: `Move ${describeLegacyMigration(migration)} from ${migration.from}/ to ${migration.to}/?`,
+                        default: true,
+                    });
+                }
+                catch {
+                    // Closed stdin is not consent, and it must not abort the update.
+                    shouldMigrate = false;
+                }
+                if (!shouldMigrate) {
+                    // Say what declining costs. FreeSpec writes the current root now, so
+                    // the files keep working where they are, but FreeSpec stops managing
+                    // them — it no longer looks in the former directory.
+                    this.log(chalk.dim(`Left in place. FreeSpec writes ${migration.to}/ now and will not manage ` +
+                        `${migration.from}/, so those files stay as they are until you move them. ` +
+                        `You will be asked again next run.`));
+                    this.log();
+                    declined.push(migration);
+                    continue;
+                }
+            }
+            for (const applied of migrateLegacyToolDirs(projectPath, [migration.toolId])) {
+                if (hasMovableContent(applied)) {
+                    this.log(chalk.dim(`Migrated ${describeLegacyMigration(applied)}: ${applied.from} → ${applied.to}`));
+                }
+                this.reportKeptInPlace(applied);
+            }
+            this.log();
+        }
+        return declined;
+    }
+}
+//# sourceMappingURL=update.js.map