@fission-ai/openspec 1.14.3 → 1.15.0

package/dist/core/migration.js

@@ -14,6 +14,7 @@ import { ALL_WORKFLOWS } from './profiles.js';
 import { getSkillReferenceTransformer, getTransformerForTool } from '../utils/command-references.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { isSharedSkillTargetActive } from './shared-skill-target.js';
+import { DISK_VIEW } from './file-view.js';
 import { isLegacyCodexSkillEquivalentToCurrent } from './shared/skill-content-equivalence.js';
 import path from 'path';
 import * as fs from 'fs';
@@ -41,14 +42,14 @@ export const LEGACY_TOOL_ROOTS = {
     // reported and kept rather than overwritten.
     antigravity: [{ root: '.agent', needsConsent: false, timing: 'after-generation' }],
 };
-function classifyManagedFile(source, destination) {
+function classifyManagedFile(source, destination, view = DISK_VIEW) {
     if (isSamePath(source, destination))
         return 'skip';
-    if (!fs.existsSync(destination))
+    if (!view.exists(destination))
         return 'move';
     try {
         const sourceContent = fs.readFileSync(source, 'utf-8');
-        const destinationContent = fs.readFileSync(destination, 'utf-8');
+        const destinationContent = view.read(destination);
         const equivalentGeneratedSkills = path.basename(source) === 'SKILL.md' &&
             path.basename(destination) === 'SKILL.md' &&
             isLegacyCodexSkillEquivalentToCurrent(sourceContent, destinationContent);
@@ -85,6 +86,17 @@ function legacyCommandPath(commandPath, currentRoot, legacyRoot) {
 export function findLegacyToolMigrations(projectPath, timing = 'before-generation') {
     return collectLegacyToolMigrations(projectPath, false, undefined, timing);
 }
+/**
+ * Lists, file by file, what `migrateLegacyToolDirs` would move or drop, without
+ * touching anything. Consent-gated roots are included: a non-interactive run
+ * moves them without asking. `view` decides what already sits at each
+ * destination, so a dry run can plan against files it has not written.
+ */
+export function planLegacyToolMigrations(projectPath, timing, toolIds, view) {
+    const ops = [];
+    collectLegacyToolMigrations(projectPath, false, toolIds, timing, { view, ops });
+    return ops;
+}
 /**
  * Moves OpenSpec-managed skill directories (openspec-*) and command files
  * (opsx-*) from a tool's legacy root to its current one. When the destination
@@ -99,7 +111,7 @@ export function findLegacyToolMigrations(projectPath, timing = 'before-generatio
 export function migrateLegacyToolDirs(projectPath, toolIds, timing = 'before-generation') {
     return collectLegacyToolMigrations(projectPath, true, toolIds, timing);
 }
-function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'before-generation') {
+function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'before-generation', plan) {
     const migrations = [];
     for (const tool of AI_TOOLS) {
         if (!tool.skillsDir)
@@ -126,8 +138,11 @@ function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'befo
                 console.warn(`Skipping legacy ${legacy.root}/ migration because the directory resolves outside this project.`);
                 continue;
             }
-            const skills = migrateSkillDirs(projectPath, tool.skillsDir, legacy.root, apply, legacyTiming === 'after-generation');
-            const commands = migrateCommandFiles(projectPath, tool, legacy.root, apply, legacyTiming === 'after-generation');
+            const sink = plan
+                ? { ...plan, toolId: tool.value, needsConsent: legacy.needsConsent }
+                : undefined;
+            const skills = migrateSkillDirs(projectPath, tool.skillsDir, legacy.root, apply, legacyTiming === 'after-generation', sink);
+            const commands = migrateCommandFiles(projectPath, tool, legacy.root, apply, legacyTiming === 'after-generation', sink);
             if (apply) {
                 removeDirIfEmpty(path.join(legacyRootPath, 'skills'));
                 removeDirIfEmpty(path.join(legacyRootPath, 'workflows'));
@@ -152,7 +167,8 @@ function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'befo
     }
     return migrations;
 }
-function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDestination = false) {
+function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDestination = false, sink) {
+    const view = sink?.view ?? DISK_VIEW;
     const legacySkillsDir = path.join(projectPath, legacyRoot, 'skills');
     if (!fs.existsSync(legacySkillsDir))
         return { moved: 0, kept: 0 };
@@ -167,13 +183,13 @@ function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDe
             continue;
         const destination = path.join(currentSkillsDir, dirName);
         const destinationSkill = path.join(destination, 'SKILL.md');
-        if (requireDestination && !fs.existsSync(destinationSkill))
+        if (requireDestination && !view.exists(destinationSkill))
             continue;
         if (!areProjectArtifacts(projectPath, sourceSkill, destinationSkill)) {
             console.warn(`Skipping legacy ${legacyRoot}/skills/${dirName} migration because it resolves outside this project.`);
             continue;
         }
-        const disposition = classifyManagedFile(sourceSkill, destinationSkill);
+        const disposition = classifyManagedFile(sourceSkill, destinationSkill, view);
         if (disposition === 'skip')
             continue;
         if (disposition === 'keep') {
@@ -181,6 +197,13 @@ function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDe
             continue;
         }
         if (!apply) {
+            sink?.ops.push({
+                toolId: sink.toolId,
+                source: sourceSkill,
+                destination: destinationSkill,
+                disposition,
+                needsConsent: sink.needsConsent,
+            });
             moved++;
             continue;
         }
@@ -207,7 +230,8 @@ function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDe
     }
     return { moved, kept };
 }
-function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestination = false) {
+function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestination = false, sink) {
+    const view = sink?.view ?? DISK_VIEW;
     const adapter = CommandAdapterRegistry.get(tool.value);
     if (!adapter || !tool.skillsDir)
         return { moved: 0, kept: 0 };
@@ -226,13 +250,13 @@ function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestin
         // No replacement means this command is not one OpenSpec installs now — a
         // skills-only delivery or a deselected workflow — so relocating the legacy
         // file would resurrect it under the current root.
-        if (requireDestination && !fs.existsSync(destination))
+        if (requireDestination && !view.exists(destination))
             continue;
         if (!areProjectArtifacts(projectPath, source, destination)) {
             console.warn(`Skipping legacy ${legacyPath} migration because it resolves outside this project.`);
             continue;
         }
-        const disposition = classifyManagedFile(source, destination);
+        const disposition = classifyManagedFile(source, destination, view);
         if (disposition === 'skip')
             continue;
         if (disposition === 'keep') {
@@ -240,6 +264,13 @@ function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestin
             continue;
         }
         if (!apply) {
+            sink?.ops.push({
+                toolId: sink.toolId,
+                source,
+                destination,
+                disposition,
+                needsConsent: sink.needsConsent,
+            });
             moved++;
             continue;
         }
@@ -344,7 +375,7 @@ function removeDirIfEmpty(dirPath) {
         // Missing or non-empty directory — nothing to do
     }
 }
-function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots = false) {
+function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots = false, view = DISK_VIEW) {
     const installed = new Set();
     let hasSkills = false;
     let hasCommands = false;
@@ -355,7 +386,7 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots =
         if (tool.globalSkillsDir) {
             skillsDirs.push(resolveToolSkillsDir(projectPath, tool));
         }
-        else if (isSharedSkillTargetActive(projectPath, tool.value)) {
+        else if (isSharedSkillTargetActive(projectPath, tool.value, view)) {
             skillsDirs.push(resolveToolSkillsDir(projectPath, tool));
             if (includeLegacyRoots) {
                 skillsDirs.push(...(tool.legacySkillsDirs ?? []).map((root) => path.join(projectPath, root, 'skills')));
@@ -365,7 +396,7 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots =
             for (const workflowId of ALL_WORKFLOWS) {
                 const skillDirName = WORKFLOW_TO_SKILL_DIR[workflowId];
                 const skillFile = path.join(skillsDir, skillDirName, 'SKILL.md');
-                if (fs.existsSync(skillFile)) {
+                if (view.exists(skillFile)) {
                     installed.add(workflowId);
                     hasSkills = true;
                 }
@@ -395,7 +426,7 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots =
                 const fullPath = path.isAbsolute(candidate)
                     ? candidate
                     : path.join(projectPath, candidate);
-                if (fs.existsSync(fullPath)) {
+                if (view.exists(fullPath)) {
                     installed.add(workflowId);
                     hasCommands = true;
                     break;
@@ -413,8 +444,8 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots =
  * Scans installed workflow files across all detected tools and returns
  * the union of installed workflow IDs.
  */
-export function scanInstalledWorkflows(projectPath, tools) {
-    return scanInstalledWorkflowArtifacts(projectPath, tools).workflows;
+export function scanInstalledWorkflows(projectPath, tools, view = DISK_VIEW) {
+    return scanInstalledWorkflowArtifacts(projectPath, tools, false, view).workflows;
 }
 function inferDelivery(artifacts) {
     if (artifacts.hasSkills && artifacts.hasCommands) {
@@ -434,13 +465,12 @@ function inferDelivery(artifacts) {
  * - If no profile field exists and no workflows are installed: no-op (defaults apply).
  * - If profile field already exists: no-op.
  */
-export function migrateIfNeeded(projectPath, tools) {
+export function computeProfileMigration(projectPath, tools, view = DISK_VIEW) {
     // A config that cannot be parsed, or is not a JSON object, is never saved
     // over; skip migration rather than fail init or update on it.
     if (isGlobalConfigUnreadable()) {
-        return;
+        return null;
     }
-    const config = getGlobalConfig();
     // Check raw config file for profile field presence
     const configPath = getGlobalConfigPath();
     let rawConfig = {};
@@ -450,25 +480,43 @@ export function migrateIfNeeded(projectPath, tools) {
         }
     }
     catch {
-        return; // Can't read config, skip migration
+        return null; // Can't read config, skip migration
     }
     // If profile is already explicitly set, no migration needed
     if (rawConfig.profile !== undefined) {
-        return;
+        return null;
     }
     // Scan for installed workflows
-    const artifacts = scanInstalledWorkflowArtifacts(projectPath, tools, true);
+    const artifacts = scanInstalledWorkflowArtifacts(projectPath, tools, true, view);
     const installedWorkflows = artifacts.workflows;
     if (installedWorkflows.length === 0) {
         // No workflows installed, new user — defaults will apply
-        return;
+        return null;
     }
+    return {
+        profile: 'custom',
+        workflows: installedWorkflows,
+        ...(rawConfig.delivery === undefined ? { delivery: inferDelivery(artifacts) } : {}),
+    };
+}
+/** The global config the one-time profile migration saves. */
+export function applyProfileMigration(migration) {
+    const config = getGlobalConfig();
     // Migrate: set profile to custom with detected workflows
-    config.profile = 'custom';
-    config.workflows = installedWorkflows;
-    if (rawConfig.delivery === undefined) {
-        config.delivery = inferDelivery(artifacts);
+    config.profile = migration.profile;
+    config.workflows = migration.workflows;
+    if (migration.delivery !== undefined) {
+        config.delivery = migration.delivery;
+    }
+    return config;
+}
+export function migrateIfNeeded(projectPath, tools) {
+    const migration = computeProfileMigration(projectPath, tools);
+    if (!migration) {
+        return;
     }
+    const config = applyProfileMigration(migration);
+    const installedWorkflows = migration.workflows;
     saveGlobalConfig(config);
     console.log(`Migrated: custom profile with ${installedWorkflows.length} workflows`);
     // Each detected tool resolves to a propose reference for its surface: the

package/dist/core/profile-sync-drift.d.ts

@@ -1,5 +1,6 @@
 import type { Delivery } from './global-config.js';
 import { ALL_WORKFLOWS } from './profiles.js';
+import { type FileView } from './file-view.js';
 type WorkflowId = (typeof ALL_WORKFLOWS)[number];
 /**
  * Maps workflow IDs to their skill directory names.
@@ -8,7 +9,7 @@ export declare const WORKFLOW_TO_SKILL_DIR: Record<WorkflowId, string>;
 /**
  * Returns tools that are configured via either skills or commands.
  */
-export declare function getConfiguredToolsForProfileSync(projectPath: string): string[];
+export declare function getConfiguredToolsForProfileSync(projectPath: string, view?: FileView): string[];
 /**
  * Detects if a single tool has profile/delivery drift against the desired state.
  *
@@ -17,11 +18,11 @@ export declare function getConfiguredToolsForProfileSync(projectPath: string): s
  * - artifacts that should not exist for the selected delivery mode
  * - artifacts for workflows that were deselected from the current profile
  */
-export declare function hasToolProfileOrDeliveryDrift(projectPath: string, toolId: string, desiredWorkflows: readonly string[], delivery: Delivery): boolean;
+export declare function hasToolProfileOrDeliveryDrift(projectPath: string, toolId: string, desiredWorkflows: readonly string[], delivery: Delivery, view?: FileView): boolean;
 /**
  * Returns configured tools that currently need a profile/delivery sync.
  */
-export declare function getToolsNeedingProfileSync(projectPath: string, desiredWorkflows: readonly string[], delivery: Delivery, configuredTools?: readonly string[]): string[];
+export declare function getToolsNeedingProfileSync(projectPath: string, desiredWorkflows: readonly string[], delivery: Delivery, configuredTools?: readonly string[], view?: FileView): string[];
 /**
  * Detects whether the current project has any profile/delivery drift.
  */

package/dist/core/profile-sync-drift.js

@@ -7,6 +7,7 @@ import { getConfiguredTools } from './shared/index.js';
 import { shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
 import { readSharedSkillTarget } from './shared-skill-target.js';
 import { FileSystemUtils } from '../utils/file-system.js';
+import { DISK_VIEW } from './file-view.js';
 import { isLegacyCodexSkillEquivalentToCurrent } from './shared/skill-content-equivalence.js';
 import { hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, } from './shared/skill-paths.js';
 /**
@@ -32,8 +33,8 @@ function toKnownWorkflows(workflows) {
 /**
  * Returns tools that are configured via either skills or commands.
  */
-export function getConfiguredToolsForProfileSync(projectPath) {
-    return getConfiguredTools(projectPath);
+export function getConfiguredToolsForProfileSync(projectPath, view = DISK_VIEW) {
+    return getConfiguredTools(projectPath, view);
 }
 /**
  * Detects if a single tool has profile/delivery drift against the desired state.
@@ -43,7 +44,7 @@ export function getConfiguredToolsForProfileSync(projectPath) {
  * - artifacts that should not exist for the selected delivery mode
  * - artifacts for workflows that were deselected from the current profile
  */
-export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkflows, delivery) {
+export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkflows, delivery, view = DISK_VIEW) {
     const tool = AI_TOOLS.find((t) => t.value === toolId);
     if (!tool || !toolSupportsSkills(tool))
         return false;
@@ -54,16 +55,16 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
     const shouldGenerateSkills = shouldGenerateSkillsForTool(toolId, delivery);
     const shouldGenerateCommands = shouldGenerateCommandsForTool(toolId, delivery);
     const sharedTarget = tool.skillsDir
-        ? readSharedSkillTarget(projectPath, tool.skillsDir)
+        ? readSharedSkillTarget(projectPath, tool.skillsDir, view)
         : undefined;
     for (const root of tool.legacySkillsDirs ?? []) {
         for (const workflow of knownDesiredWorkflows) {
             const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
             const legacySkill = path.join(projectPath, root, 'skills', dirName, 'SKILL.md');
-            if (!fs.existsSync(legacySkill))
+            if (!view.exists(legacySkill))
                 continue;
             const currentSkill = path.join(skillsDir, dirName, 'SKILL.md');
-            if (!fs.existsSync(currentSkill) || sharedTarget !== toolId) {
+            if (!view.exists(currentSkill) || sharedTarget !== toolId) {
                 return true;
             }
             try {
@@ -75,7 +76,7 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
                 // remove the redundant legacy file even when version, line endings,
                 // or supported invocation syntax changed. Materially divergent copies
                 // stay in place without forcing an update on every run.
-                if (isLegacyCodexSkillEquivalentToCurrent(fs.readFileSync(legacySkill, 'utf-8'), fs.readFileSync(currentSkill, 'utf-8'))) {
+                if (isLegacyCodexSkillEquivalentToCurrent(view.read(legacySkill), view.read(currentSkill))) {
                     return true;
                 }
             }
@@ -88,7 +89,7 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
         for (const workflow of knownDesiredWorkflows) {
             const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
             const skillFile = path.join(skillsDir, dirName, 'SKILL.md');
-            if (!fs.existsSync(skillFile)) {
+            if (!view.exists(skillFile)) {
                 return true;
             }
         }
@@ -98,7 +99,7 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
                 continue;
             const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
             const skillDir = path.join(skillsDir, dirName);
-            if (fs.existsSync(skillDir)) {
+            if (view.exists(skillDir)) {
                 return true;
             }
         }
@@ -107,7 +108,7 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
         for (const workflow of ALL_WORKFLOWS) {
             const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
             const skillDir = path.join(skillsDir, dirName);
-            if (fs.existsSync(skillDir)) {
+            if (view.exists(skillDir)) {
                 return true;
             }
         }
@@ -116,7 +117,7 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
         for (const workflow of knownDesiredWorkflows) {
             const cmdPath = adapter.getFilePath(workflow);
             const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
-            if (!fs.existsSync(fullPath)) {
+            if (!view.exists(fullPath)) {
                 return true;
             }
         }
@@ -126,7 +127,7 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
                 continue;
             const cmdPath = adapter.getFilePath(workflow);
             const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
-            if (fs.existsSync(fullPath)) {
+            if (view.exists(fullPath)) {
                 return true;
             }
         }
@@ -135,7 +136,7 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
         for (const workflow of ALL_WORKFLOWS) {
             const cmdPath = adapter.getFilePath(workflow);
             const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
-            if (fs.existsSync(fullPath)) {
+            if (view.exists(fullPath)) {
                 return true;
             }
         }
@@ -145,9 +146,11 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
 /**
  * Returns configured tools that currently need a profile/delivery sync.
  */
-export function getToolsNeedingProfileSync(projectPath, desiredWorkflows, delivery, configuredTools) {
-    const tools = configuredTools ? [...new Set(configuredTools)] : getConfiguredToolsForProfileSync(projectPath);
-    return tools.filter((toolId) => hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkflows, delivery));
+export function getToolsNeedingProfileSync(projectPath, desiredWorkflows, delivery, configuredTools, view = DISK_VIEW) {
+    const tools = configuredTools
+        ? [...new Set(configuredTools)]
+        : getConfiguredToolsForProfileSync(projectPath, view);
+    return tools.filter((toolId) => hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkflows, delivery, view));
 }
 function getInstalledWorkflowsForTool(projectPath, toolId, options) {
     const tool = AI_TOOLS.find((t) => t.value === toolId);

package/dist/core/shared/tool-detection.d.ts

@@ -3,6 +3,8 @@
  *
  * Shared utilities for detecting tool configurations and version status.
  */
+import { type Delivery } from '../global-config.js';
+import { type FileView } from '../file-view.js';
 /**
  * Names of skill directories created by openspec init.
  */
@@ -50,11 +52,11 @@ export declare function getToolsWithSkillsDir(): string[];
 /**
  * Checks which skill files exist for a tool.
  */
-export declare function getToolSkillStatus(projectRoot: string, toolId: string): ToolSkillStatus;
+export declare function getToolSkillStatus(projectRoot: string, toolId: string, view?: FileView): ToolSkillStatus;
 /**
  * Checks whether a tool has at least one generated OpenSpec command file.
  */
-export declare function toolHasAnyConfiguredCommand(projectPath: string, toolId: string): boolean;
+export declare function toolHasAnyConfiguredCommand(projectPath: string, toolId: string, view?: FileView): boolean;
 /**
  * Checks whether command files for a tool on disk match current generated command contents.
  *
@@ -63,6 +65,8 @@ export declare function toolHasAnyConfiguredCommand(projectPath: string, toolId:
  */
 export declare function areCommandFilesUpToDate(projectRoot: string, toolId: string, options?: {
     workflows?: readonly string[];
+    /** The tree to read; the disk unless an update is planning. */
+    view?: FileView;
 }): boolean;
 /**
  * Gets the skill status for all tools with skillsDir configured.
@@ -72,18 +76,22 @@ export declare function getToolStates(projectRoot: string): Map<string, ToolSkil
  * Extracts the generatedBy version from a skill file's YAML frontmatter.
  * Returns null if the field is not found or the file doesn't exist.
  */
-export declare function extractGeneratedByVersion(skillFilePath: string): string | null;
+export declare function extractGeneratedByVersion(skillFilePath: string, view?: FileView): string | null;
 /**
  * Gets version status for a tool by reading its skill files, falling back to a
  * command-content fingerprint for installs that have commands but no skills.
  */
 export declare function getToolVersionStatus(projectRoot: string, toolId: string, currentVersion: string, options?: {
     workflows?: readonly string[];
+    /** The tree to read; the disk unless an update is planning. */
+    view?: FileView;
+    /** Effective delivery; read from the global config when omitted. */
+    delivery?: Delivery;
 }): ToolVersionStatus;
 /**
  * Gets all configured tools in the project (configured via skills or commands).
  */
-export declare function getConfiguredTools(projectRoot: string): string[];
+export declare function getConfiguredTools(projectRoot: string, view?: FileView): string[];
 /**
  * Gets version status for all configured tools.
  */

package/dist/core/shared/tool-detection.js

@@ -4,7 +4,6 @@
  * Shared utilities for detecting tool configurations and version status.
  */
 import path from 'path';
-import * as fs from 'fs';
 import { AI_TOOLS, OPENSPEC_SKILL_NAMES } from '../config.js';
 import { CommandAdapterRegistry, generateCommands } from '../command-generation/index.js';
 import { getCommandContents } from './skill-generation.js';
@@ -13,6 +12,7 @@ import { getProfileWorkflows, ALL_WORKFLOWS } from '../profiles.js';
 import { isSharedSkillTargetActive, hasLegacySkills, readSharedSkillTarget, reconcileSharedSkillTargets, } from '../shared-skill-target.js';
 import { shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, resolveCommandSurfaceCapability, } from '../command-surface.js';
 import { getSkillCapableTools, resolveToolSkillsDir, toolSupportsSkills, } from './skill-paths.js';
+import { DISK_VIEW } from '../file-view.js';
 /**
  * Names of skill directories created by openspec init.
  */
@@ -43,12 +43,12 @@ export function getToolsWithSkillsDir() {
 /**
  * Checks which skill files exist for a tool.
  */
-export function getToolSkillStatus(projectRoot, toolId) {
+export function getToolSkillStatus(projectRoot, toolId, view = DISK_VIEW) {
     const tool = AI_TOOLS.find((t) => t.value === toolId);
     if (!tool || !toolSupportsSkills(tool)) {
         return { configured: false, fullyConfigured: false, skillCount: 0 };
     }
-    if (tool.skillsDir && !isSharedSkillTargetActive(projectRoot, toolId)) {
+    if (tool.skillsDir && !isSharedSkillTargetActive(projectRoot, toolId, view)) {
         return { configured: false, fullyConfigured: false, skillCount: 0 };
     }
     const skillsDirs = [
@@ -57,7 +57,7 @@ export function getToolSkillStatus(projectRoot, toolId) {
     ];
     let skillCount = 0;
     for (const skillName of SKILL_NAMES) {
-        if (skillsDirs.some((skillsDir) => fs.existsSync(path.join(skillsDir, skillName, 'SKILL.md')))) {
+        if (skillsDirs.some((skillsDir) => view.exists(path.join(skillsDir, skillName, 'SKILL.md')))) {
             skillCount++;
         }
     }
@@ -70,14 +70,14 @@ export function getToolSkillStatus(projectRoot, toolId) {
 /**
  * Checks whether a tool has at least one generated OpenSpec command file.
  */
-export function toolHasAnyConfiguredCommand(projectPath, toolId) {
+export function toolHasAnyConfiguredCommand(projectPath, toolId, view = DISK_VIEW) {
     const adapter = CommandAdapterRegistry.get(toolId);
     if (!adapter)
         return false;
     for (const commandId of COMMAND_IDS) {
         const cmdPath = adapter.getFilePath(commandId);
         const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
-        if (fs.existsSync(fullPath)) {
+        if (view.exists(fullPath)) {
             return true;
         }
     }
@@ -101,6 +101,7 @@ export function areCommandFilesUpToDate(projectRoot, toolId, options) {
     const adapter = CommandAdapterRegistry.get(toolId);
     if (!adapter)
         return false;
+    const view = options?.view ?? DISK_VIEW;
     let workflows;
     if (options?.workflows) {
         workflows = options.workflows;
@@ -123,11 +124,11 @@ export function areCommandFilesUpToDate(projectRoot, toolId, options) {
     }
     for (const cmd of generatedCommands) {
         const cmdPath = path.isAbsolute(cmd.path) ? cmd.path : path.join(projectRoot, cmd.path);
-        if (!fs.existsSync(cmdPath)) {
+        if (!view.exists(cmdPath)) {
             return false;
         }
         try {
-            const existingContent = fs.readFileSync(cmdPath, 'utf-8');
+            const existingContent = view.read(cmdPath);
             if (normalizeCommandContent(existingContent) !== normalizeCommandContent(cmd.fileContent)) {
                 return false;
             }
@@ -143,7 +144,7 @@ export function areCommandFilesUpToDate(projectRoot, toolId, options) {
             continue;
         const cmdPath = adapter.getFilePath(workflow);
         const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectRoot, cmdPath);
-        if (fs.existsSync(fullPath)) {
+        if (view.exists(fullPath)) {
             return false;
         }
     }
@@ -176,12 +177,12 @@ export function getToolStates(projectRoot) {
  * Extracts the generatedBy version from a skill file's YAML frontmatter.
  * Returns null if the field is not found or the file doesn't exist.
  */
-export function extractGeneratedByVersion(skillFilePath) {
+export function extractGeneratedByVersion(skillFilePath, view = DISK_VIEW) {
     try {
-        if (!fs.existsSync(skillFilePath)) {
+        if (!view.exists(skillFilePath)) {
             return null;
         }
-        const content = fs.readFileSync(skillFilePath, 'utf-8');
+        const content = view.read(skillFilePath);
         // Look for generatedBy in the YAML frontmatter
         // The file format is:
         // ---
@@ -212,6 +213,7 @@ export function extractGeneratedByVersion(skillFilePath) {
  * command-content fingerprint for installs that have commands but no skills.
  */
 export function getToolVersionStatus(projectRoot, toolId, currentVersion, options) {
+    const view = options?.view ?? DISK_VIEW;
     const tool = AI_TOOLS.find((t) => t.value === toolId);
     if (!tool || !toolSupportsSkills(tool)) {
         return {
@@ -232,8 +234,8 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion, option
     for (const skillName of SKILL_NAMES) {
         for (const skillsDir of skillsDirs) {
             const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
-            if (fs.existsSync(skillFile)) {
-                generatedByVersion = extractGeneratedByVersion(skillFile);
+            if (view.exists(skillFile)) {
+                generatedByVersion = extractGeneratedByVersion(skillFile, view);
                 foundSkill = true;
                 break;
             }
@@ -241,10 +243,10 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion, option
         if (foundSkill)
             break;
     }
-    const skillConfigured = getToolSkillStatus(projectRoot, toolId).configured;
-    const commandConfigured = toolHasAnyConfiguredCommand(projectRoot, toolId);
+    const skillConfigured = getToolSkillStatus(projectRoot, toolId, view).configured;
+    const commandConfigured = toolHasAnyConfiguredCommand(projectRoot, toolId, view);
     const markerConfigured = Boolean(tool.skillsDir) &&
-        readSharedSkillTarget(projectRoot, tool.skillsDir) === toolId;
+        readSharedSkillTarget(projectRoot, tool.skillsDir, view) === toolId;
     const configured = skillConfigured || commandConfigured || markerConfigured;
     // 2. Commands-only installs have no skill file to read a version from, so fall
     //    back to comparing the generated command content. Deliberately skipped when
@@ -253,7 +255,7 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion, option
         generatedByVersion = currentVersion;
     }
     if (!skillConfigured && !commandConfigured && markerConfigured) {
-        const delivery = getGlobalConfig().delivery ?? 'both';
+        const delivery = options?.delivery ?? getGlobalConfig().delivery ?? 'both';
         if (!shouldGenerateSkillsForTool(toolId, delivery) &&
             !shouldGenerateCommandsForTool(toolId, delivery)) {
             generatedByVersion = currentVersion;
@@ -275,7 +277,7 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion, option
     if (skillConfigured && commandConfigured) {
         let generatesCommands = true;
         try {
-            generatesCommands = shouldGenerateCommandsForTool(toolId, getGlobalConfig().delivery ?? 'both');
+            generatesCommands = shouldGenerateCommandsForTool(toolId, options?.delivery ?? getGlobalConfig().delivery ?? 'both');
         }
         catch {
             generatesCommands = true;
@@ -298,24 +300,24 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion, option
 /**
  * Gets all configured tools in the project (configured via skills or commands).
  */
-export function getConfiguredTools(projectRoot) {
+export function getConfiguredTools(projectRoot, view = DISK_VIEW) {
     const configured = AI_TOOLS
         .filter((t) => {
         if (!toolSupportsSkills(t))
             return false;
-        return (getToolSkillStatus(projectRoot, t.value).configured ||
-            toolHasAnyConfiguredCommand(projectRoot, t.value) ||
+        return (getToolSkillStatus(projectRoot, t.value, view).configured ||
+            toolHasAnyConfiguredCommand(projectRoot, t.value, view) ||
             (resolveCommandSurfaceCapability(t.value) === 'adapter-backed' &&
-                hasLegacySkills(projectRoot, t)) ||
+                hasLegacySkills(projectRoot, t, view)) ||
             (Boolean(t.skillsDir) &&
-                readSharedSkillTarget(projectRoot, t.skillsDir) === t.value));
+                readSharedSkillTarget(projectRoot, t.skillsDir, view) === t.value));
     });
-    const activeProjectTools = new Set(reconcileSharedSkillTargets(projectRoot, configured.filter((tool) => tool.skillsDir)).map((tool) => tool.value));
+    const activeProjectTools = new Set(reconcileSharedSkillTargets(projectRoot, configured.filter((tool) => tool.skillsDir), view).map((tool) => tool.value));
     return configured
         .filter((tool) => tool.globalSkillsDir ||
-        toolHasAnyConfiguredCommand(projectRoot, tool.value) ||
+        toolHasAnyConfiguredCommand(projectRoot, tool.value, view) ||
         (resolveCommandSurfaceCapability(tool.value) === 'adapter-backed' &&
-            hasLegacySkills(projectRoot, tool)) ||
+            hasLegacySkills(projectRoot, tool, view)) ||
         activeProjectTools.has(tool.value))
         .map((tool) => tool.value);
 }