@fission-ai/openspec 1.14.3 → 1.16.0

package/dist/core/update.js

@@ -7,7 +7,6 @@
 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 { getSkillReferenceTransformer, getTransformerForTool, transformToSkillReferences } from '../utils/command-references.js';
@@ -16,14 +15,16 @@ import { generateCommands, CommandAdapterRegistry, } from './command-generation/
 import { getToolSkillStatus, getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, formatIdeRestart, } from './shared/index.js';
 import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatDeferredGlobalPromptSummary, formatCleanupSummary, formatDetectionSummary, getLegacyGlobalPromptMatches, getLegacyWorkflowIdsForTool, getToolsFromLegacyArtifacts, omitGlobalLegacyPromptFiles, omitToolLegacyArtifacts, pickGlobalLegacyPromptFiles, } from './legacy-cleanup.js';
 import { isInteractive } from '../utils/interactive.js';
-import { getGlobalConfig } from './global-config.js';
+import { getGlobalConfig, getGlobalConfigPath, serializeGlobalConfig } from './global-config.js';
 import { getProfileWorkflows, ALL_WORKFLOWS, CORE_WORKFLOWS } from './profiles.js';
 import { formatOptionalWorkflowsNote, getOnboardingCommands } from './onboarding-commands.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, findLegacyToolMigrations, migrateLegacyToolDirs, describeLegacyMigration, legacyMigrationNotice, keptInPlaceNotice, hasMovableContent, } from './migration.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, writeSharedSkillTarget, } from './shared-skill-target.js';
+import { resolveSharedSkillWriters, sharedSkillTargetMarkerPath, } from './shared-skill-target.js';
+import { DISK_VIEW } from './file-view.js';
+import { realFileOps, UpdatePlanRecorder, } from './update-plan.js';
 import { includesGitHubCopilot, writeCopilotCloudFiles, removeCopilotCloudFiles, isCopilotCloudEnabled, readCopilotCloudOptIn, findUnmanagedCloudFiles } from './github-copilot/cloud-agent.js';
 const require = createRequire(import.meta.url);
 const { version: OPENSPEC_VERSION } = require('../../package.json');
@@ -46,16 +47,46 @@ function normalizeGeneratedFile(content) {
  *
  * Wrapper around the shared migration module's scanInstalledWorkflows that accepts tool IDs.
  */
-export function scanInstalledWorkflows(projectPath, toolIds) {
+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);
+    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 OpenSpec skills and commands for all configured tools,
@@ -66,6 +97,10 @@ export class UpdateCommand {
     async execute(projectPath) {
         const resolvedProjectPath = path.resolve(projectPath);
         const openspecPath = path.join(resolvedProjectPath, OPENSPEC_DIR_NAME);
+        if (this.dryRun) {
+            this.recorder = new UpdatePlanRecorder(resolvedProjectPath);
+            this.ops = this.recorder;
+        }
         // 1. Check openspec directory exists
         if (!await FileSystemUtils.directoryExists(openspecPath)) {
             throw new Error(`No OpenSpec directory found. Run 'openspec init' first.`);
@@ -74,18 +109,40 @@ export class UpdateCommand {
         // (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.
-        for (const migration of migrateLegacyToolDirs(resolvedProjectPath)) {
-            if (hasMovableContent(migration)) {
-                console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+        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);
             }
-            this.reportKeptInPlace(migration);
         }
-        const declinedMigrations = await this.offerConsentedLegacyMigrations(resolvedProjectPath);
+        // 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 opsx skills/commands.
-        const detectedTools = getAvailableTools(resolvedProjectPath);
-        migrateIfNeededShared(resolvedProjectPath, detectedTools);
-        // 3. Read global config for profile/delivery
-        const globalConfig = getGlobalConfig();
+        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), 'openspec');
+            }
+        }
         const profile = globalConfig.profile ?? 'core';
         const delivery = globalConfig.delivery ?? 'both';
         const profileWorkflows = getProfileWorkflows(profile, globalConfig.workflows);
@@ -94,26 +151,27 @@ export class UpdateCommand {
         const legacyUpgrade = await this.handleLegacyCleanup(resolvedProjectPath, desiredWorkflows, delivery);
         const { newlyConfiguredTools, workflowOverrides: legacyWorkflowOverrides, deferredGlobalCleanup, failedTools: legacyUpgradeFailures = [], } = legacyUpgrade;
         // 5. Find configured tools
-        const configuredTools = getConfiguredToolsForProfileSync(resolvedProjectPath);
+        const configuredTools = getConfiguredToolsForProfileSync(resolvedProjectPath, this.view);
         const configuredAndNewTools = [...new Set([...configuredTools, ...newlyConfiguredTools])];
         if (configuredTools.length === 0 && newlyConfiguredTools.length === 0) {
             if (deferredGlobalCleanup) {
                 await this.performDeferredGlobalPromptCleanup(resolvedProjectPath, deferredGlobalCleanup);
             }
-            throwIfUpdateFailed(legacyUpgradeFailures);
+            if (this.stopIfUpdateFailed(legacyUpgradeFailures))
+                return;
             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) {
-                    console.log(chalk.yellow(`Nothing to update: this project's OpenSpec files are still in ${migration.from}/, ` +
+                    this.log(chalk.yellow(`Nothing to update: this project's OpenSpec files are still in ${migration.from}/, ` +
                         `which OpenSpec no longer writes.`));
-                    console.log(chalk.dim(`Re-run "openspec update" and accept the move to ${migration.to}/ to resume updates.`));
+                    this.log(chalk.dim(`Re-run "openspec update" and accept the move to ${migration.to}/ to resume updates.`));
                 }
                 return;
             }
             await this.syncCopilotCloudFiles(resolvedProjectPath, configuredAndNewTools);
-            console.log(chalk.yellow('No configured tools found.'));
-            console.log(chalk.dim('Run "openspec init" to set up tools.'));
+            this.log(chalk.yellow('No configured tools found.'));
+            this.log(chalk.dim('Run "openspec init" to set up tools.'));
             return;
         }
         // 6. Check version status for all configured tools, against the same workflow set
@@ -121,6 +179,8 @@ export class UpdateCommand {
         //    fingerprinted against commands it was never given.
         const toolStatuses = configuredTools.map((toolId) => getToolVersionStatus(resolvedProjectPath, toolId, OPENSPEC_VERSION, {
             workflows: legacyWorkflowOverrides[toolId] ?? desiredWorkflows,
+            delivery,
+            view: this.view,
         }));
         const statusByTool = new Map(toolStatuses.map((status) => [status.toolId, status]));
         // 7. Smart update detection
@@ -133,7 +193,7 @@ export class UpdateCommand {
             return !tool || !hasGlobalSkillTarget(tool);
         })
             .map((s) => s.toolId);
-        const toolsNeedingConfigSync = getToolsNeedingProfileSync(resolvedProjectPath, desiredWorkflows, delivery, configuredTools);
+        const toolsNeedingConfigSync = getToolsNeedingProfileSync(resolvedProjectPath, desiredWorkflows, delivery, configuredTools, this.view);
         const toolsWithDriftedSkills = this.findToolsWithDriftedSkills(resolvedProjectPath, configuredTools, delivery, (toolId) => legacyWorkflowOverrides[toolId] ?? desiredWorkflows);
         const toolsToUpdateSet = new Set([
             ...toolsNeedingVersionUpdate,
@@ -152,27 +212,29 @@ export class UpdateCommand {
             this.detectNewTools(resolvedProjectPath, configuredTools);
             this.displayProfileNotes(resolvedProjectPath, configuredTools, desiredWorkflows, profile, delivery);
             this.displaySetupNotes(configuredTools);
-            throwIfUpdateFailed(legacyUpgradeFailures);
+            this.stopIfUpdateFailed(legacyUpgradeFailures);
             return;
         }
         // 8. Display update plan
         if (this.force) {
-            console.log(`Force updating ${configuredTools.length} tool(s): ${configuredTools.join(', ')}`);
+            this.log(`Force updating ${configuredTools.length} tool(s): ${configuredTools.join(', ')}`);
         }
         else if (toolsToUpdateSet.size === 0) {
-            console.log('No additional refresh needed after legacy migration.');
+            this.log('No additional refresh needed after legacy migration.');
         }
         else {
             this.displayUpdatePlan([...toolsToUpdateSet], statusByTool, toolsUpToDate, new Set(toolsWithDriftedSkills));
         }
-        console.log();
+        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, configuredAndNewTools
             .map((toolId) => AI_TOOLS.find((tool) => tool.value === toolId))
-            .filter((tool) => tool !== undefined));
+            .filter((tool) => tool !== undefined), 
+        // A legacy upgrade earlier in this run may have claimed the root.
+        this.view);
         const updatedTools = [];
         const updatedToolIds = [];
         const failedTools = [...legacyUpgradeFailures];
@@ -186,7 +248,7 @@ export class UpdateCommand {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
             if (!tool || !toolSupportsSkills(tool))
                 continue;
-            const spinner = ora(`Updating ${tool.name}...`).start();
+            const spinner = this.startSpinner(`Updating ${tool.name}...`);
             try {
                 const skillsDir = resolveToolSkillsDir(resolvedProjectPath, tool);
                 const skillsRoot = hasGlobalSkillTarget(tool) ? skillsDir : resolvedProjectPath;
@@ -204,19 +266,19 @@ export class UpdateCommand {
                         const transformer = getTransformerForTool(tool.value, delivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         FileSystemUtils.assertPathWithin(skillsRoot, skillFile);
-                        await FileSystemUtils.writeFile(skillFile, skillContent);
+                        await this.ops.writeFile(skillFile, skillContent, tool.value);
                     }
-                    writeSharedSkillTarget(resolvedProjectPath, tool.value);
-                    removedDeselectedSkillCount += await this.removeUnselectedSkillDirs(skillsRoot, skillsDir, toolWorkflows);
+                    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);
+                    removedSkillCount += await this.removeSkillDirs(skillsRoot, skillsDir, tool.value);
                     // Persist the selected owner even when commands-only delivery leaves
                     // this target with no generated skills.
-                    writeSharedSkillTarget(resolvedProjectPath, tool.value);
+                    await this.writeSharedSkillTarget(resolvedProjectPath, tool.value);
                     // A tool with no command adapter now has zero OpenSpec artifacts;
                     // say so like init does, rather than deleting its skills silently
                     // and letting tool detection re-suggest an init that would also
@@ -232,7 +294,7 @@ export class UpdateCommand {
                         const generatedCommands = generateCommands(commandContents, adapter);
                         for (const cmd of generatedCommands) {
                             const commandFile = FileSystemUtils.resolveProjectArtifactPath(resolvedProjectPath, cmd.path);
-                            await FileSystemUtils.writeFile(commandFile, cmd.fileContent);
+                            await this.ops.writeFile(commandFile, cmd.fileContent, tool.value);
                         }
                         removedDeselectedCommandCount += await this.removeUnselectedCommandFiles(resolvedProjectPath, toolId, toolWorkflows);
                     }
@@ -247,52 +309,58 @@ export class UpdateCommand {
                 spinner.succeed(`Updated ${tool.name}`);
                 updatedTools.push(tool.name);
                 updatedToolIds.push(tool.value);
-                for (const migration of migrateLegacyToolDirs(resolvedProjectPath, [tool.value], 'after-generation')) {
-                    if (hasMovableContent(migration)) {
-                        console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+                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);
                     }
-                    this.reportKeptInPlace(migration);
+                }
+                else {
+                    await this.planLegacyToolMoves(resolvedProjectPath, 'after-generation', [tool.value]);
                 }
             }
             catch (error) {
                 spinner.fail(`Failed to update ${tool.name}`);
-                failedTools.push({
-                    name: tool.name,
-                    error: error instanceof Error ? error.message : String(error)
-                });
+                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);
             }
         }
         if (deferredGlobalCleanup) {
             await this.performDeferredGlobalPromptCleanup(resolvedProjectPath, deferredGlobalCleanup);
         }
         // 11. Summary
-        console.log();
+        this.log();
         if (updatedTools.length > 0) {
-            console.log(chalk.green(`✓ Updated: ${updatedTools.join(', ')} (v${OPENSPEC_VERSION})`));
+            this.log(chalk.green(`✓ Updated: ${updatedTools.join(', ')} (v${OPENSPEC_VERSION})`));
         }
         if (failedTools.length > 0) {
-            console.log(chalk.red(`✗ Failed: ${failedTools.map(f => `${f.name} (${f.error})`).join(', ')}`));
+            this.log(chalk.red(`✗ Failed: ${failedTools.map(f => `${f.name} (${f.error})`).join(', ')}`));
         }
         if (skillsInvocableCommandSkips.length > 0) {
-            console.log(chalk.dim(`Commands skipped for: ${skillsInvocableCommandSkips.join(', ')} (uses skills)`));
+            this.log(chalk.dim(`Commands skipped for: ${skillsInvocableCommandSkips.join(', ')} (uses skills)`));
         }
         if (removedCommandCount > 0) {
-            console.log(chalk.dim(`Removed: ${removedCommandCount} command files (delivery: skills)`));
+            this.log(chalk.dim(`Removed: ${removedCommandCount} command files (delivery: skills)`));
         }
         if (removedSkillCount > 0) {
-            console.log(chalk.dim(`Removed: ${removedSkillCount} skill directories (delivery: commands)`));
+            this.log(chalk.dim(`Removed: ${removedSkillCount} skill directories (delivery: commands)`));
         }
         if (zeroArtifactTools.length > 0) {
             const names = zeroArtifactTools.join(', ');
-            console.log(chalk.yellow(`No skills or commands remain for ${names}: delivery is set to 'commands' but ` +
+            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 'openspec config set delivery both' to generate skills.`));
         }
         if (removedDeselectedCommandCount > 0) {
-            console.log(chalk.dim(`Removed: ${removedDeselectedCommandCount} command files (deselected workflows)`));
+            this.log(chalk.dim(`Removed: ${removedDeselectedCommandCount} command files (deselected workflows)`));
         }
         if (removedDeselectedSkillCount > 0) {
-            console.log(chalk.dim(`Removed: ${removedDeselectedSkillCount} skill directories (deselected workflows)`));
+            this.log(chalk.dim(`Removed: ${removedDeselectedSkillCount} skill directories (deselected workflows)`));
         }
         // 12. Show onboarding message for newly configured tools from legacy upgrade.
         // Command tools get the command name their files answer to, skill-only
@@ -318,16 +386,16 @@ export class UpdateCommand {
                 ...new Set(newlyConfiguredTools.flatMap((toolId) => legacyWorkflowOverrides[toolId] ?? desiredWorkflows)),
             ];
             const entries = getOnboardingCommands(installedWorkflows).map(({ command, description }) => [referenceFor(command), description]);
-            console.log();
+            this.log();
             if (entries.length > 0) {
                 const width = Math.max(...entries.map(([reference]) => reference.length));
-                console.log(chalk.bold('Getting started:'));
+                this.log(chalk.bold('Getting started:'));
                 for (const [reference, description] of entries) {
-                    console.log(`  ${reference.padEnd(width)}  ${description}`);
+                    this.log(`  ${reference.padEnd(width)}  ${description}`);
                 }
-                console.log();
+                this.log();
             }
-            console.log(`Learn more: ${chalk.cyan('https://github.com/Fission-AI/OpenSpec')}`);
+            this.log(`Learn more: ${chalk.cyan('https://github.com/Fission-AI/OpenSpec')}`);
         }
         await this.syncCopilotCloudFiles(resolvedProjectPath, configuredAndNewTools);
         // 13. Detect new tool directories not currently configured
@@ -338,17 +406,81 @@ export class UpdateCommand {
         // 15. List affected tools
         if (updatedTools.length > 0) {
             const toolDisplayNames = updatedTools;
-            console.log(chalk.dim(`Tools: ${toolDisplayNames.join(', ')}`));
+            this.log(chalk.dim(`Tools: ${toolDisplayNames.join(', ')}`));
         }
-        console.log();
+        this.log();
         const affectedToolIds = [...new Set([...newlyConfiguredTools, ...updatedToolIds])];
         const restartHint = formatIdeRestart(affectedToolIds, delivery);
         if (restartHint) {
-            console.log(chalk.dim(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;
+    }
+    /** The update's write seam, in the shape modules with their own writers take. */
+    fileOps(tool) {
+        return {
+            writeFile: (filePath, content) => this.ops.writeFile(filePath, content, tool),
+            removeFile: (filePath) => this.ops.removeFile(filePath, tool),
+            removeEmptyDirectory: (dirPath) => this.ops.removeEmptyDirectory(dirPath),
+        };
+    }
+    /**
+     * 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.');
+            }
         }
-        throwIfUpdateFailed(failedTools);
     }
     async syncCopilotCloudFiles(projectPath, configuredTools) {
+        const ops = this.fileOps('github-copilot');
         try {
             if (includesGitHubCopilot(configuredTools)) {
                 // Cloud files are opt-in (see cloud-agent.ts). `update` never prompts,
@@ -357,10 +489,10 @@ export class UpdateCommand {
                 // a pre-opt-in project already has. Opting in is a deliberate init/config
                 // step, never a silent side effect of running update.
                 if (await isCopilotCloudEnabled(projectPath)) {
-                    await writeCopilotCloudFiles(projectPath);
+                    await writeCopilotCloudFiles(projectPath, ops);
                     const collisions = await findUnmanagedCloudFiles(projectPath);
                     if (collisions.length > 0) {
-                        console.log(chalk.dim(`Left your existing ${collisions.join(' and ')} untouched — add the OpenSpec ` +
+                        this.log(chalk.dim(`Left your existing ${collisions.join(' and ')} untouched — add the OpenSpec ` +
                             `install step by hand so the Copilot cloud agent can run openspec.`));
                     }
                     return;
@@ -370,19 +502,19 @@ export class UpdateCommand {
                 // are preserved). If the user simply never decided, stay quiet unless
                 // we're at an interactive terminal, where a one-line hint aids discovery.
                 if (readCopilotCloudOptIn(projectPath) === false) {
-                    const removed = await removeCopilotCloudFiles(projectPath);
+                    const removed = await removeCopilotCloudFiles(projectPath, ops);
                     if (removed > 0) {
-                        console.log(chalk.dim(`Removed: ${removed} Copilot cloud agent file(s) (opted out of cloud files)`));
+                        this.log(chalk.dim(`Removed: ${removed} Copilot cloud agent file(s) (opted out of cloud files)`));
                     }
                 }
                 else if (isInteractive()) {
-                    console.log(chalk.dim("GitHub Copilot cloud coding-agent files are available (opt-in). Enable with 'openspec init --copilot-cloud'."));
+                    this.log(chalk.dim("GitHub Copilot cloud coding-agent files are available (opt-in). Enable with 'openspec init --copilot-cloud'."));
                 }
                 return;
             }
-            const removed = await removeCopilotCloudFiles(projectPath);
+            const removed = await removeCopilotCloudFiles(projectPath, ops);
             if (removed > 0) {
-                console.log(chalk.dim(`Removed: ${removed} Copilot cloud agent file(s) (github-copilot not configured)`));
+                this.log(chalk.dim(`Removed: ${removed} Copilot cloud agent file(s) (github-copilot not configured)`));
             }
         }
         catch (error) {
@@ -410,16 +542,16 @@ export class UpdateCommand {
                 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).configured)
+            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 (!fs.existsSync(skillFile))
+                if (!this.view.exists(skillFile))
                     return false;
                 try {
-                    const existing = fs.readFileSync(skillFile, 'utf-8');
+                    const existing = this.view.read(skillFile);
                     const generated = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                     return normalizeGeneratedFile(existing) !== normalizeGeneratedFile(generated);
                 }
@@ -434,10 +566,10 @@ export class UpdateCommand {
      */
     displayUpToDateMessage(toolStatuses) {
         const toolNames = toolStatuses.map((s) => s.toolId);
-        console.log(chalk.green(`✓ All ${toolStatuses.length} tool(s) up to date (v${OPENSPEC_VERSION})`));
-        console.log(chalk.dim(`  Tools: ${toolNames.join(', ')}`));
-        console.log();
-        console.log(chalk.dim('Use --force to refresh files anyway.'));
+        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.
@@ -456,10 +588,10 @@ export class UpdateCommand {
             }
             return `${toolId} (config sync)`;
         });
-        console.log(`Updating ${toolsToUpdate.length} tool(s): ${updates.join(', ')}`);
+        this.log(`Updating ${toolsToUpdate.length} tool(s): ${updates.join(', ')}`);
         if (upToDate.length > 0) {
             const upToDateNames = upToDate.map((s) => s.toolId);
-            console.log(chalk.dim(`Already up to date: ${upToDateNames.join(', ')}`));
+            this.log(chalk.dim(`Already up to date: ${upToDateNames.join(', ')}`));
         }
     }
     /**
@@ -470,7 +602,7 @@ export class UpdateCommand {
         for (const toolId of toolIds) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
             if (tool?.setupNote) {
-                console.log(chalk.yellow(`Setup required for ${tool.name}: ${tool.setupNote}`));
+                this.log(chalk.yellow(`Setup required for ${tool.name}: ${tool.setupNote}`));
             }
         }
     }
@@ -486,8 +618,8 @@ export class UpdateCommand {
             const isSingleTool = newToolNames.length === 1;
             const toolNoun = isSingleTool ? 'tool' : 'tools';
             const pronoun = isSingleTool ? 'it' : 'them';
-            console.log();
-            console.log(chalk.yellow(`Detected new ${toolNoun}: ${newToolNames.join(', ')}. Run 'openspec init' to add ${pronoun}.`));
+            this.log();
+            this.log(chalk.yellow(`Detected new ${toolNoun}: ${newToolNames.join(', ')}. Run 'openspec init' to add ${pronoun}.`));
         }
     }
     /**
@@ -510,7 +642,7 @@ export class UpdateCommand {
         const profileSet = new Set(profileWorkflows);
         const extraWorkflows = installedWorkflows.filter((w) => !profileSet.has(w));
         if (extraWorkflows.length > 0) {
-            console.log(chalk.dim(`Note: ${extraWorkflows.length} extra workflows not in profile (use \`openspec config profile\` to manage)`));
+            this.log(chalk.dim(`Note: ${extraWorkflows.length} extra workflows not in profile (use \`openspec config profile\` to manage)`));
             return true;
         }
         return false;
@@ -531,8 +663,8 @@ export class UpdateCommand {
         }
         const label = missing.length === 1 ? 'workflow' : 'workflows';
         const pronoun = missing.length === 1 ? 'it' : 'them';
-        console.log(chalk.dim(`Note: Your custom profile is missing ${missing.length} core ${label}: ${missing.join(', ')}`));
-        console.log(chalk.dim(`Run \`openspec config profile\` to add ${pronoun}, or \`openspec config profile core\` to use the core set.`));
+        this.log(chalk.dim(`Note: Your custom profile is missing ${missing.length} core ${label}: ${missing.join(', ')}`));
+        this.log(chalk.dim(`Run \`openspec config profile\` to add ${pronoun}, or \`openspec config profile core\` to use the core set.`));
         return true;
     }
     /**
@@ -562,25 +694,25 @@ export class UpdateCommand {
             return;
         }
         for (const line of note) {
-            console.log(chalk.dim(line));
+            this.log(chalk.dim(line));
         }
     }
     /**
      * Removes skill directories for workflows when delivery changed to commands-only.
      * Returns the number of directories removed.
      */
-    async removeSkillDirs(skillsRoot, skillsDir) {
+    async removeSkillDirs(skillsRoot, skillsDir, toolId) {
         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);
-            if (!fs.existsSync(skillDir))
+            if (!this.view.exists(skillDir))
                 continue;
             FileSystemUtils.assertPathWithin(skillsRoot, skillDir);
             try {
-                await fs.promises.rm(skillDir, { recursive: true, force: true });
+                await this.ops.removeDirectory(skillDir, toolId);
                 removed++;
             }
             catch {
@@ -593,7 +725,7 @@ export class UpdateCommand {
      * 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) {
+    async removeUnselectedSkillDirs(skillsRoot, skillsDir, desiredWorkflows, toolId) {
         const desiredSet = new Set(desiredWorkflows);
         let removed = 0;
         for (const workflow of ALL_WORKFLOWS) {
@@ -603,11 +735,11 @@ export class UpdateCommand {
             if (!dirName)
                 continue;
             const skillDir = path.join(skillsDir, dirName);
-            if (!fs.existsSync(skillDir))
+            if (!this.view.exists(skillDir))
                 continue;
             FileSystemUtils.assertPathWithin(skillsRoot, skillDir);
             try {
-                await fs.promises.rm(skillDir, { recursive: true, force: true });
+                await this.ops.removeDirectory(skillDir, toolId);
                 removed++;
             }
             catch {
@@ -629,8 +761,8 @@ export class UpdateCommand {
             const cmdPath = adapter.getFilePath(workflow);
             const fullPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmdPath);
             try {
-                if (fs.existsSync(fullPath)) {
-                    await fs.promises.unlink(fullPath);
+                if (this.view.exists(fullPath)) {
+                    await this.ops.removeFile(fullPath, toolId);
                     removed++;
                 }
             }
@@ -656,8 +788,8 @@ export class UpdateCommand {
             const cmdPath = adapter.getFilePath(workflow);
             const fullPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmdPath);
             try {
-                if (fs.existsSync(fullPath)) {
-                    await fs.promises.unlink(fullPath);
+                if (this.view.exists(fullPath)) {
+                    await this.ops.removeFile(fullPath, toolId);
                     removed++;
                 }
             }
@@ -681,7 +813,7 @@ export class UpdateCommand {
     reportKeptInPlace(migration) {
         const notice = keptInPlaceNotice(migration);
         if (notice)
-            console.log(chalk.dim(notice));
+            this.log(chalk.dim(notice));
     }
     async offerConsentedLegacyMigrations(projectPath) {
         const pending = findLegacyToolMigrations(projectPath).filter((m) => m.needsConsent);
@@ -694,10 +826,10 @@ export class UpdateCommand {
             // divergent copies the user never hears about.
             if (!hasMovableContent(migration)) {
                 this.reportKeptInPlace(migration);
-                console.log();
+                this.log();
                 continue;
             }
-            console.log(chalk.yellow(legacyMigrationNotice(migration)));
+            this.log(chalk.yellow(legacyMigrationNotice(migration)));
             if (!this.force && isInteractive()) {
                 const { confirm } = await import('@inquirer/prompts');
                 let shouldMigrate;
@@ -715,21 +847,21 @@ export class UpdateCommand {
                     // Say what declining costs. OpenSpec writes the current root now, so
                     // the files keep working where they are, but OpenSpec stops managing
                     // them — it no longer looks in the former directory.
-                    console.log(chalk.dim(`Left in place. OpenSpec writes ${migration.to}/ now and will not manage ` +
+                    this.log(chalk.dim(`Left in place. OpenSpec 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.`));
-                    console.log();
+                    this.log();
                     declined.push(migration);
                     continue;
                 }
             }
             for (const applied of migrateLegacyToolDirs(projectPath, [migration.toolId])) {
                 if (hasMovableContent(applied)) {
-                    console.log(chalk.dim(`Migrated ${describeLegacyMigration(applied)}: ${applied.from} → ${applied.to}`));
+                    this.log(chalk.dim(`Migrated ${describeLegacyMigration(applied)}: ${applied.from} → ${applied.to}`));
                 }
                 this.reportKeptInPlace(applied);
             }
-            console.log();
+            this.log();
         }
         return declined;
     }
@@ -748,17 +880,18 @@ export class UpdateCommand {
         const immediateSummary = formatDetectionSummary(omitGlobalLegacyPromptFiles(detection));
         const deferredSummary = formatDeferredGlobalPromptSummary(detection);
         if (immediateSummary || deferredSummary) {
-            console.log();
+            this.log();
             if (immediateSummary) {
-                console.log(immediateSummary);
-                console.log();
+                this.log(immediateSummary);
+                this.log();
             }
             if (deferredSummary) {
-                console.log(deferredSummary);
-                console.log();
+                this.log(deferredSummary);
+                this.log();
             }
         }
-        const canPrompt = isInteractive();
+        // A dry run plans a non-interactive update, so it never prompts.
+        const canPrompt = !this.dryRun && isInteractive();
         if (this.force) {
             const legacyUpgrade = await this.upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery);
             await this.performImmediateLegacyCleanup(projectPath, detection, legacyUpgrade.skippedSharedSkillTools);
@@ -770,8 +903,9 @@ export class UpdateCommand {
         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('⚠ Run with --force to auto-cleanup legacy files, or run interactively.'));
-            console.log();
+            this.log(chalk.yellow('⚠ Run with --force to auto-cleanup legacy files, or run interactively.'));
+            this.log();
+            this.recorder?.addNote('legacy-artifacts', 'Legacy OpenSpec artifacts were found. Update cleans them up only with --force or when you confirm at a terminal, so this plan leaves them alone; --dry-run --force lists that cleanup.');
             return { newlyConfiguredTools: [], workflowOverrides: {} };
         }
         // Interactive mode: prompt for confirmation
@@ -789,8 +923,8 @@ export class UpdateCommand {
             };
         }
         else {
-            console.log(chalk.dim('Skipping legacy cleanup. Continuing with skill update...'));
-            console.log();
+            this.log(chalk.dim('Skipping legacy cleanup. Continuing with skill update...'));
+            this.log();
             return { newlyConfiguredTools: [], workflowOverrides: {} };
         }
     }
@@ -810,7 +944,9 @@ export class UpdateCommand {
      * installed replacement skills can retire their prompts in the same run.
      */
     async performDeferredGlobalPromptCleanup(projectPath, detection) {
-        const availableCodexWorkflows = new Set(scanInstalledWorkflows(projectPath, ['codex']));
+        // Read the tree as planned: a dry run has not written the replacement
+        // skills this check looks for.
+        const availableCodexWorkflows = new Set(scanInstalledWorkflows(projectPath, ['codex'], this.view));
         const removableMatches = getLegacyGlobalPromptMatches(detection)
             .filter((prompt) => prompt.workflowIds.every((workflowId) => availableCodexWorkflows.has(workflowId)));
         if (removableMatches.length > 0) {
@@ -819,26 +955,26 @@ export class UpdateCommand {
         const blockedMatches = getLegacyGlobalPromptMatches(detection)
             .filter((prompt) => !removableMatches.some((match) => match.path === prompt.path));
         if (blockedMatches.length > 0) {
-            console.log(chalk.yellow('Preserved deferred global prompts without replacement skills:'));
+            this.log(chalk.yellow('Preserved deferred global prompts without replacement skills:'));
             for (const prompt of blockedMatches) {
-                console.log(chalk.dim(`  - ${prompt.toolId}: ${prompt.path}`));
+                this.log(chalk.dim(`  - ${prompt.toolId}: ${prompt.path}`));
             }
-            console.log();
+            this.log();
         }
     }
     /**
      * Perform cleanup of legacy artifacts.
      */
     async performLegacyCleanup(projectPath, detection) {
-        const spinner = ora('Cleaning up legacy files...').start();
-        const result = await cleanupLegacyArtifacts(projectPath, detection);
+        const spinner = this.startSpinner('Cleaning up legacy files...');
+        const result = await cleanupLegacyArtifacts(projectPath, detection, this.fileOps('openspec'));
         spinner.succeed('Legacy files cleaned up');
         const summary = formatCleanupSummary(result);
         if (summary) {
-            console.log();
-            console.log(summary);
+            this.log();
+            this.log(summary);
         }
-        console.log();
+        this.log();
     }
     /**
      * Upgrades unconfigured legacy tools into the skills-based setup and carries
@@ -851,7 +987,7 @@ export class UpdateCommand {
             return { newlyConfiguredTools: [], workflowOverrides: {} };
         }
         // Get currently configured tools
-        const configuredTools = getConfiguredToolsForProfileSync(projectPath);
+        const configuredTools = getConfiguredToolsForProfileSync(projectPath, this.view);
         const configuredSet = new Set(configuredTools);
         // Filter to tools that aren't already configured
         const unconfiguredLegacyTools = legacyTools.filter((t) => !configuredSet.has(t));
@@ -865,17 +1001,17 @@ export class UpdateCommand {
             return { newlyConfiguredTools: [], workflowOverrides: {} };
         }
         // Show what tools were detected from legacy artifacts
-        console.log(chalk.bold('Tools detected from legacy artifacts:'));
+        this.log(chalk.bold('Tools detected from legacy artifacts:'));
         for (const toolId of validUnconfiguredTools) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
-            console.log(`  • ${tool?.name || toolId}`);
+            this.log(`  • ${tool?.name || toolId}`);
         }
-        console.log();
+        this.log();
         let selectedTools;
         if (this.force || !canPrompt) {
             // Non-interactive with --force: auto-select detected tools
             selectedTools = validUnconfiguredTools;
-            console.log(`Setting up skills for: ${selectedTools.join(', ')}`);
+            this.log(`Setting up skills for: ${selectedTools.join(', ')}`);
         }
         else {
             // Interactive mode: prompt for tool selection with detected tools pre-selected
@@ -897,8 +1033,8 @@ export class UpdateCommand {
                 validate: (_selected) => true, // Allow empty selection (user can skip)
             });
             if (selectedTools.length === 0) {
-                console.log(chalk.dim('Skipping tool setup.'));
-                console.log();
+                this.log(chalk.dim('Skipping tool setup.'));
+                this.log();
                 return { newlyConfiguredTools: [], workflowOverrides: {} };
             }
         }
@@ -911,12 +1047,12 @@ export class UpdateCommand {
         const arbitrationTools = [...new Set([...configuredTools, ...selectedTools])]
             .map((toolId) => AI_TOOLS.find((tool) => tool.value === toolId))
             .filter((tool) => tool !== undefined);
-        const sharedSkillWriters = resolveSharedSkillWriters(projectPath, arbitrationTools);
+        const sharedSkillWriters = resolveSharedSkillWriters(projectPath, arbitrationTools, this.view);
         for (const toolId of selectedTools) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
             if (!tool || !toolSupportsSkills(tool))
                 continue;
-            const spinner = ora(`Setting up ${tool.name}...`).start();
+            const spinner = this.startSpinner(`Setting up ${tool.name}...`);
             try {
                 const skillsDir = resolveToolSkillsDir(projectPath, tool);
                 const skillsRoot = hasGlobalSkillTarget(tool) ? skillsDir : projectPath;
@@ -954,9 +1090,9 @@ export class UpdateCommand {
                         const transformer = getTransformerForTool(tool.value, delivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         FileSystemUtils.assertPathWithin(skillsRoot, skillFile);
-                        await FileSystemUtils.writeFile(skillFile, skillContent);
+                        await this.ops.writeFile(skillFile, skillContent, tool.value);
                     }
-                    writeSharedSkillTarget(projectPath, tool.value);
+                    await this.writeSharedSkillTarget(projectPath, tool.value);
                 }
                 // Create commands when delivery includes commands
                 if (shouldGenerateCommands) {
@@ -965,28 +1101,34 @@ export class UpdateCommand {
                         const generatedCommands = generateCommands(commandContents, adapter);
                         for (const cmd of generatedCommands) {
                             const commandFile = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmd.path);
-                            await FileSystemUtils.writeFile(commandFile, cmd.fileContent);
+                            await this.ops.writeFile(commandFile, cmd.fileContent, tool.value);
                         }
                     }
                 }
                 spinner.succeed(`Setup complete for ${tool.name}`);
                 newlyConfigured.push(toolId);
-                for (const migration of migrateLegacyToolDirs(projectPath, [tool.value], 'after-generation')) {
-                    if (hasMovableContent(migration)) {
-                        console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+                if (this.dryRun) {
+                    await this.planLegacyToolMoves(projectPath, 'after-generation', [tool.value]);
+                }
+                else {
+                    for (const migration of migrateLegacyToolDirs(projectPath, [tool.value], 'after-generation')) {
+                        if (hasMovableContent(migration)) {
+                            this.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+                        }
+                        this.reportKeptInPlace(migration);
                     }
-                    this.reportKeptInPlace(migration);
                 }
             }
             catch (error) {
                 spinner.fail(`Failed to set up ${tool.name}`);
                 const message = error instanceof Error ? error.message : String(error);
-                console.log(chalk.red(`  ${message}`));
+                this.log(chalk.red(`  ${message}`));
                 failedTools.push({ name: tool.name, error: message });
+                this.recorder?.addFailure(tool.value, message);
             }
         }
         if (newlyConfigured.length > 0) {
-            console.log();
+            this.log();
         }
         return {
             newlyConfiguredTools: newlyConfigured,