scene-capability-engine 3.0.0

package/lib/workspace/multi/path-utils.js

@@ -0,0 +1,173 @@
+/**
+ * PathUtils - Cross-platform path handling utilities
+ * 
+ * Provides utilities for normalizing and converting paths across platforms.
+ * Implements the data atomicity principle by ensuring paths are stored
+ * in a consistent format and converted at runtime.
+ */
+
+const path = require('path');
+const os = require('os');
+
+class PathUtils {
+  /**
+   * Normalize path to use forward slashes for storage
+   * 
+   * All paths are stored with forward slashes for cross-platform compatibility.
+   * This ensures the configuration files are portable across Windows, Linux, and Mac.
+   * 
+   * @param {string} inputPath - Path to normalize
+   * @returns {string} Normalized path with forward slashes
+   */
+  static normalize(inputPath) {
+    if (!inputPath || typeof inputPath !== 'string' || inputPath.trim().length === 0) {
+      throw new Error('Path must be a non-empty string');
+    }
+
+    // Expand home directory first
+    const expandedPath = this.expandHome(inputPath);
+
+    // Convert to absolute path if not already
+    const absolutePath = path.isAbsolute(expandedPath) 
+      ? expandedPath 
+      : path.resolve(expandedPath);
+    
+    // Replace backslashes with forward slashes for storage
+    return absolutePath.replace(/\\/g, '/');
+  }
+
+  /**
+   * Convert stored path to platform-specific format for runtime use
+   * 
+   * @param {string} storedPath - Path with forward slashes (from storage)
+   * @returns {string} Platform-specific path
+   */
+  static toPlatform(storedPath) {
+    if (storedPath === null) {
+      return null;
+    }
+    
+    if (!storedPath) {
+      return '';
+    }
+
+    // Convert forward slashes to platform-specific separators
+    return storedPath.split('/').join(path.sep);
+  }
+
+  /**
+   * Expand home directory (~) to absolute path
+   * 
+   * @param {string} inputPath - Path that may contain ~
+   * @returns {string} Expanded absolute path
+   */
+  static expandHome(inputPath) {
+    if (inputPath === null) {
+      return null;
+    }
+    
+    if (inputPath === undefined) {
+      return undefined;
+    }
+    
+    if (!inputPath) {
+      return '';
+    }
+
+    if (inputPath.startsWith('~/') || inputPath.startsWith('~\\') || inputPath === '~') {
+      return path.join(os.homedir(), inputPath.slice(2));
+    }
+
+    return inputPath;
+  }
+
+  /**
+   * Get the default kse configuration directory
+   * 
+   * @returns {string} Path to ~/.kse directory
+   */
+  static getConfigDir() {
+    return path.join(os.homedir(), '.kse');
+  }
+
+  /**
+   * Get the default workspace state file path
+   * 
+   * @returns {string} Path to ~/.kse/workspace-state.json
+   */
+  static getWorkspaceStatePath() {
+    return path.join(this.getConfigDir(), 'workspace-state.json');
+  }
+
+  /**
+   * Check if a path is within another path
+   * 
+   * @param {string} childPath - Path to check
+   * @param {string} parentPath - Parent path
+   * @returns {boolean} True if childPath is within parentPath
+   */
+  static isWithin(childPath, parentPath) {
+    const normalizedChild = this.normalize(childPath);
+    const normalizedParent = this.normalize(parentPath);
+    
+    return normalizedChild === normalizedParent || 
+           normalizedChild.startsWith(normalizedParent + '/');
+  }
+
+  /**
+   * Get relative path from parent to child
+   * 
+   * @param {string} from - Parent path
+   * @param {string} to - Child path
+   * @returns {string} Relative path with forward slashes
+   */
+  static relative(from, to) {
+    const relativePath = path.relative(from, to);
+    return relativePath.replace(/\\/g, '/');
+  }
+
+  /**
+   * Join path segments
+   * 
+   * @param {...string} segments - Path segments to join
+   * @returns {string} Joined path with forward slashes
+   */
+  static join(...segments) {
+    const joinedPath = path.join(...segments);
+    return joinedPath.replace(/\\/g, '/');
+  }
+
+  /**
+   * Get directory name from path
+   * 
+   * @param {string} filePath - File path
+   * @returns {string} Directory name with forward slashes
+   */
+  static dirname(filePath) {
+    const dirPath = path.dirname(filePath);
+    return dirPath.replace(/\\/g, '/');
+  }
+
+  /**
+   * Get base name from path
+   * 
+   * @param {string} filePath - File path
+   * @param {string} ext - Optional extension to remove
+   * @returns {string} Base name
+   */
+  static basename(filePath, ext) {
+    return path.basename(filePath, ext);
+  }
+
+  /**
+   * Get file extension from path
+   * 
+   * @param {string} filePath - File path
+   * @returns {string} File extension (including the dot)
+   */
+  static extname(filePath) {
+    return path.extname(filePath);
+  }
+}
+
+module.exports = PathUtils;

package/lib/workspace/multi/workspace-context-resolver.js

@@ -0,0 +1,244 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * WorkspaceContextResolver - Determines the active workspace for command execution
+ * 
+ * Implements workspace resolution priority logic:
+ * 1. Explicit --workspace parameter (highest priority)
+ * 2. Current directory matches a registered workspace path
+ * 3. Active workspace from global config
+ * 4. Error: No workspace context available (lowest priority)
+ * 
+ * This class is the central component for workspace context detection and resolution.
+ */
+class WorkspaceContextResolver {
+  /**
+   * Create a new WorkspaceContextResolver instance
+   * 
+   * @param {WorkspaceRegistry} registry - Workspace registry instance
+   * @param {GlobalConfig} config - Global configuration instance
+   */
+  constructor(registry, config) {
+    this.registry = registry;
+    this.config = config;
+  }
+
+  /**
+   * Resolve workspace using priority rules
+   * 
+   * Priority order:
+   * 1. Explicit workspace parameter
+   * 2. Current directory match
+   * 3. Active workspace from config
+   * 4. Error if no context available
+   * 
+   * @param {string|null} explicitWorkspace - Explicit --workspace parameter value
+   * @param {string|null} currentDir - Current directory (defaults to process.cwd())
+   * @returns {Promise<Workspace|null>} Resolved workspace or null
+   * @throws {Error} If explicit workspace doesn't exist or no context available
+   */
+  async resolveWorkspace(explicitWorkspace = null, currentDir = null) {
+    // Priority 1: Explicit --workspace parameter
+    if (explicitWorkspace) {
+      const workspace = await this.registry.getWorkspace(explicitWorkspace);
+      if (!workspace) {
+        const available = await this.getAvailableWorkspaceNames();
+        throw new Error(
+          `Workspace "${explicitWorkspace}" does not exist.\n` +
+          `Available workspaces: ${available.join(', ') || 'none'}`
+        );
+      }
+      return workspace;
+    }
+
+    // Priority 2: Current directory matches a registered workspace
+    const targetDir = currentDir || process.cwd();
+    const workspaceFromPath = await this.detectWorkspaceFromPath(targetDir);
+    if (workspaceFromPath) {
+      return workspaceFromPath;
+    }
+
+    // Priority 3: Active workspace from config
+    const activeWorkspaceName = await this.config.getActiveWorkspace();
+    if (activeWorkspaceName) {
+      const activeWorkspace = await this.registry.getWorkspace(activeWorkspaceName);
+      if (activeWorkspace) {
+        return activeWorkspace;
+      }
+      // Active workspace no longer exists, clear it
+      await this.config.clearActiveWorkspace();
+    }
+
+    // Priority 4: No workspace context available
+    return null;
+  }
+
+  /**
+   * Detect workspace from a given path
+   * 
+   * Searches the registry for a workspace that contains the given path.
+   * 
+   * @param {string} targetPath - Path to search for
+   * @returns {Promise<Workspace|null>} Workspace containing the path, or null
+   */
+  async detectWorkspaceFromPath(targetPath) {
+    return await this.registry.findWorkspaceByPath(targetPath);
+  }
+
+  /**
+   * Check if a directory is a valid kse project directory
+   * 
+   * @param {string} dirPath - Directory path to check
+   * @returns {Promise<boolean>} True if directory contains .kiro/ structure
+   */
+  async isValidKseDirectory(dirPath) {
+    try {
+      const kiroPath = path.join(dirPath, '.kiro');
+      const exists = await fs.pathExists(kiroPath);
+      
+      if (!exists) {
+        return false;
+      }
+
+      const stats = await fs.stat(kiroPath);
+      return stats.isDirectory();
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Get the currently active workspace from config
+   * 
+   * @returns {Promise<Workspace|null>} Active workspace or null
+   */
+  async getActiveWorkspace() {
+    const activeWorkspaceName = await this.config.getActiveWorkspace();
+    if (!activeWorkspaceName) {
+      return null;
+    }
+
+    const workspace = await this.registry.getWorkspace(activeWorkspaceName);
+    if (!workspace) {
+      // Active workspace no longer exists, clear it
+      await this.config.clearActiveWorkspace();
+      return null;
+    }
+
+    return workspace;
+  }
+
+  /**
+   * Set the active workspace in config
+   * 
+   * @param {string} name - Workspace name
+   * @returns {Promise<void>}
+   * @throws {Error} If workspace doesn't exist
+   */
+  async setActiveWorkspace(name) {
+    const workspace = await this.registry.getWorkspace(name);
+    if (!workspace) {
+      const available = await this.getAvailableWorkspaceNames();
+      throw new Error(
+        `Workspace "${name}" does not exist.\n` +
+        `Available workspaces: ${available.join(', ') || 'none'}`
+      );
+    }
+
+    await this.config.setActiveWorkspace(name);
+    await this.registry.updateLastAccessed(name);
+  }
+
+  /**
+   * Clear the active workspace
+   * 
+   * @returns {Promise<void>}
+   */
+  async clearActiveWorkspace() {
+    await this.config.clearActiveWorkspace();
+  }
+
+  /**
+   * Get list of available workspace names
+   * 
+   * @private
+   * @returns {Promise<Array<string>>} Array of workspace names
+   */
+  async getAvailableWorkspaceNames() {
+    const workspaces = await this.registry.listWorkspaces();
+    return workspaces.map(ws => ws.name);
+  }
+
+  /**
+   * Check if current directory should prompt for workspace registration
+   * 
+   * Returns true if:
+   * - Current directory is a valid kse project
+   * - Current directory is not within any registered workspace
+   * 
+   * @param {string|null} currentDir - Current directory (defaults to process.cwd())
+   * @returns {Promise<boolean>} True if should prompt for registration
+   */
+  async shouldPromptForRegistration(currentDir = null) {
+    const targetDir = currentDir || process.cwd();
+
+    // Check if it's a valid kse directory
+    const isValid = await this.isValidKseDirectory(targetDir);
+    if (!isValid) {
+      return false;
+    }
+
+    // Check if it's already registered
+    const workspace = await this.detectWorkspaceFromPath(targetDir);
+    return workspace === null;
+  }
+
+  /**
+   * Resolve workspace with error handling for commands that require a workspace
+   * 
+   * This is a convenience method that throws a helpful error if no workspace
+   * context can be resolved.
+   * 
+   * @param {string|null} explicitWorkspace - Explicit --workspace parameter value
+   * @param {string|null} currentDir - Current directory (defaults to process.cwd())
+   * @returns {Promise<Workspace>} Resolved workspace
+   * @throws {Error} If no workspace context available
+   */
+  async resolveWorkspaceOrError(explicitWorkspace = null, currentDir = null) {
+    const workspace = await this.resolveWorkspace(explicitWorkspace, currentDir);
+    
+    if (!workspace) {
+      const targetDir = currentDir || process.cwd();
+      const isValid = await this.isValidKseDirectory(targetDir);
+      
+      if (isValid) {
+        throw new Error(
+          'No workspace context available.\n' +
+          'The current directory is a valid kse project but not registered as a workspace.\n' +
+          'Action Required: Run "kse workspace create <name>" to register this directory.'
+        );
+      } else {
+        const available = await this.getAvailableWorkspaceNames();
+        if (available.length > 0) {
+          throw new Error(
+            'No workspace context available.\n' +
+            'The current directory is not a kse project and no active workspace is set.\n' +
+            `Action Required: Run "kse workspace switch <name>" or use --workspace parameter.\n` +
+            `Available workspaces: ${available.join(', ')}`
+          );
+        } else {
+          throw new Error(
+            'No workspace context available.\n' +
+            'No workspaces are registered and the current directory is not a kse project.\n' +
+            'Action Required: Run "kse workspace create <name>" to register a workspace.'
+          );
+        }
+      }
+    }
+
+    return workspace;
+  }
+}
+
+module.exports = WorkspaceContextResolver;

package/lib/workspace/multi/workspace-registry.js

@@ -0,0 +1,196 @@
+const WorkspaceStateManager = require('./workspace-state-manager');
+
+/**
+ * WorkspaceRegistry - Facade for WorkspaceStateManager
+ * 
+ * Provides backward-compatible API for workspace registry operations.
+ * All operations are delegated to WorkspaceStateManager which implements
+ * the Data Atomicity Principle (single source of truth).
+ * 
+ * @deprecated This class is a compatibility layer. New code should use
+ *             WorkspaceStateManager directly.
+ */
+class WorkspaceRegistry {
+  /**
+   * Create a new WorkspaceRegistry instance
+   * 
+   * @param {string} configPath - Path to workspace-state.json (optional)
+   */
+  constructor(configPath = null) {
+    // Delegate to WorkspaceStateManager
+    this.stateManager = new WorkspaceStateManager(configPath);
+    // Expose configPath for backward compatibility
+    this.configPath = this.stateManager.statePath;
+  }
+
+  /**
+   * Get the default configuration file path
+   * 
+   * @returns {string} Path to ~/.kse/workspace-state.json
+   * @deprecated Use WorkspaceStateManager.getDefaultStatePath() instead
+   */
+  getDefaultConfigPath() {
+    return this.stateManager.getDefaultStatePath();
+  }
+
+  /**
+   * Load workspace registry from disk
+   * 
+   * @returns {Promise<boolean>} True if loaded successfully
+   */
+  async load() {
+    return await this.stateManager.load();
+  }
+
+  /**
+   * Save workspace registry to disk
+   * 
+   * @returns {Promise<boolean>} True if saved successfully
+   */
+  async save() {
+    return await this.stateManager.save();
+  }
+
+  /**
+   * Ensure registry is loaded before operations
+   * 
+   * @private
+   */
+  async ensureLoaded() {
+    await this.stateManager.ensureLoaded();
+  }
+
+  /**
+   * Validate that a path is a valid kse project directory
+   * 
+   * @param {string} workspacePath - Path to validate
+   * @returns {Promise<boolean>} True if valid kse project
+   */
+  async validateWorkspacePath(workspacePath) {
+    const fs = require('fs-extra');
+    const path = require('path');
+    
+    try {
+      // Check if path exists
+      const exists = await fs.pathExists(workspacePath);
+      if (!exists) {
+        return false;
+      }
+
+      // Check if it's a directory
+      const stats = await fs.stat(workspacePath);
+      if (!stats.isDirectory()) {
+        return false;
+      }
+
+      // Check if .kiro directory exists
+      const kiroPath = path.join(workspacePath, '.kiro');
+      const kiroExists = await fs.pathExists(kiroPath);
+      
+      return kiroExists;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Create a new workspace entry
+   * 
+   * @param {string} name - Unique workspace name
+   * @param {string} workspacePath - Path to workspace directory
+   * @returns {Promise<Workspace>} Created workspace
+   * @throws {Error} If name already exists or path is invalid
+   */
+  async createWorkspace(name, workspacePath) {
+    return await this.stateManager.createWorkspace(name, workspacePath);
+  }
+
+  /**
+   * Get a workspace by name
+   * 
+   * @param {string} name - Workspace name
+   * @returns {Promise<Workspace|null>} Workspace or null if not found
+   */
+  async getWorkspace(name) {
+    return await this.stateManager.getWorkspace(name);
+  }
+
+  /**
+   * List all registered workspaces
+   * 
+   * @returns {Promise<Array<Workspace>>} Array of workspaces
+   */
+  async listWorkspaces() {
+    return await this.stateManager.listWorkspaces();
+  }
+
+  /**
+   * Remove a workspace from the registry
+   * 
+   * @param {string} name - Workspace name
+   * @returns {Promise<boolean>} True if removed, false if not found
+   */
+  async removeWorkspace(name) {
+    return await this.stateManager.removeWorkspace(name);
+  }
+
+  /**
+   * Update the last accessed timestamp for a workspace
+   * 
+   * @param {string} name - Workspace name
+   * @returns {Promise<boolean>} True if updated, false if not found
+   */
+  async updateLastAccessed(name) {
+    await this.ensureLoaded();
+    
+    const workspace = await this.stateManager.getWorkspace(name);
+    if (!workspace) {
+      return false;
+    }
+
+    workspace.updateLastAccessed();
+    await this.stateManager.save();
+
+    return true;
+  }
+
+  /**
+   * Find workspace that contains the given path
+   * 
+   * @param {string} targetPath - Path to search for
+   * @returns {Promise<Workspace|null>} Workspace containing the path, or null
+   */
+  async findWorkspaceByPath(targetPath) {
+    return await this.stateManager.findWorkspaceByPath(targetPath);
+  }
+
+  /**
+   * Check if a workspace name exists
+   * 
+   * @param {string} name - Workspace name
+   * @returns {Promise<boolean>} True if exists
+   */
+  async hasWorkspace(name) {
+    return await this.stateManager.hasWorkspace(name);
+  }
+
+  /**
+   * Get count of registered workspaces
+   * 
+   * @returns {Promise<number>} Number of workspaces
+   */
+  async count() {
+    return await this.stateManager.count();
+  }
+
+  /**
+   * Clear all workspaces (for testing purposes)
+   * 
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    await this.stateManager.clear();
+  }
+}
+
+module.exports = WorkspaceRegistry;