scene-capability-engine 3.0.0

package/lib/workspace/multi/workspace-state-manager.js

@@ -0,0 +1,537 @@
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const Workspace = require('./workspace');
+
+/**
+ * WorkspaceStateManager - Single Source of Truth for workspace state
+ * 
+ * Implements the Data Atomicity Principle by managing all workspace-related
+ * data in a single configuration file. This ensures atomic updates and
+ * eliminates data inconsistency risks.
+ * 
+ * Architecture: Single file (~/.kse/workspace-state.json) contains:
+ * - All workspace entries
+ * - Active workspace selection
+ * - User preferences
+ * 
+ * This replaces the previous dual-file approach (workspaces.json + config.json)
+ * which violated the Single Source of Truth principle.
+ */
+class WorkspaceStateManager {
+  /**
+   * Create a new WorkspaceStateManager instance
+   * 
+   * @param {string} statePath - Path to workspace-state.json (optional)
+   */
+  constructor(statePath = null) {
+    this.statePath = statePath || this.getDefaultStatePath();
+    this.state = {
+      version: '1.0',
+      activeWorkspace: null,
+      workspaces: new Map(),
+      preferences: {
+        autoDetectWorkspace: true,
+        confirmDestructiveOperations: true
+      }
+    };
+    this.loaded = false;
+  }
+
+  /**
+   * Get the default state file path
+   * 
+   * @returns {string} Path to ~/.kse/workspace-state.json
+   */
+  getDefaultStatePath() {
+    const homeDir = os.homedir();
+    return path.join(homeDir, '.kse', 'workspace-state.json');
+  }
+
+  /**
+   * Load workspace state from disk
+   * 
+   * Supports automatic migration from legacy format (workspaces.json + config.json)
+   * 
+   * @returns {Promise<boolean>} True if loaded successfully
+   */
+  async load() {
+    try {
+      // Try loading new format
+      const exists = await fs.pathExists(this.statePath);
+      
+      if (exists) {
+        await this.loadNewFormat();
+        this.loaded = true;
+        return true;
+      }
+
+      // Check for legacy format and migrate
+      if (await this.hasLegacyFiles()) {
+        console.log('Migrating workspace configuration to new format...');
+        await this.migrateFromLegacy();
+        this.loaded = true;
+        return true;
+      }
+
+      // Initialize empty state
+      this.state = {
+        version: '1.0',
+        activeWorkspace: null,
+        workspaces: new Map(),
+        preferences: {
+          autoDetectWorkspace: true,
+          confirmDestructiveOperations: true
+        }
+      };
+      this.loaded = true;
+      return true;
+
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw new Error(`Workspace state file is corrupted: ${this.statePath}. ` +
+                       `Please backup and delete the file, then try again.`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Load state from new format file
+   * 
+   * @private
+   */
+  async loadNewFormat() {
+    const content = await fs.readFile(this.statePath, 'utf8');
+    const data = JSON.parse(content);
+
+    // Validate version
+    if (data.version !== this.state.version) {
+      console.warn(`Warning: State version mismatch. Expected ${this.state.version}, got ${data.version}`);
+    }
+
+    // Load state
+    this.state.version = data.version;
+    this.state.activeWorkspace = data.activeWorkspace || null;
+    
+    // Load workspaces
+    this.state.workspaces = new Map();
+    if (data.workspaces && Array.isArray(data.workspaces)) {
+      for (const workspaceData of data.workspaces) {
+        const workspace = Workspace.fromDict(workspaceData);
+        this.state.workspaces.set(workspace.name, workspace);
+      }
+    }
+
+    // Load preferences
+    this.state.preferences = {
+      autoDetectWorkspace: data.preferences?.autoDetectWorkspace ?? true,
+      confirmDestructiveOperations: data.preferences?.confirmDestructiveOperations ?? true
+    };
+  }
+
+  /**
+   * Check if legacy configuration files exist
+   * 
+   * @private
+   * @returns {Promise<boolean>}
+   */
+  async hasLegacyFiles() {
+    const homeDir = os.homedir();
+    const legacyWorkspacesPath = path.join(homeDir, '.kse', 'workspaces.json');
+    const legacyConfigPath = path.join(homeDir, '.kse', 'config.json');
+    
+    const workspacesExists = await fs.pathExists(legacyWorkspacesPath);
+    const configExists = await fs.pathExists(legacyConfigPath);
+    
+    return workspacesExists || configExists;
+  }
+
+  /**
+   * Migrate from legacy format (workspaces.json + config.json)
+   * 
+   * @private
+   */
+  async migrateFromLegacy() {
+    const homeDir = os.homedir();
+    const legacyWorkspacesPath = path.join(homeDir, '.kse', 'workspaces.json');
+    const legacyConfigPath = path.join(homeDir, '.kse', 'config.json');
+
+    // Load legacy workspaces
+    let legacyWorkspaces = [];
+    if (await fs.pathExists(legacyWorkspacesPath)) {
+      const content = await fs.readFile(legacyWorkspacesPath, 'utf8');
+      const data = JSON.parse(content);
+      legacyWorkspaces = data.workspaces || [];
+    }
+
+    // Load legacy config
+    let legacyActiveWorkspace = null;
+    let legacyPreferences = {};
+    if (await fs.pathExists(legacyConfigPath)) {
+      const content = await fs.readFile(legacyConfigPath, 'utf8');
+      const data = JSON.parse(content);
+      legacyActiveWorkspace = data.active_workspace || null;
+      legacyPreferences = data.preferences || {};
+    }
+
+    // Merge into new format
+    this.state.activeWorkspace = legacyActiveWorkspace;
+    this.state.workspaces = new Map();
+    
+    for (const workspaceData of legacyWorkspaces) {
+      const workspace = Workspace.fromDict(workspaceData);
+      this.state.workspaces.set(workspace.name, workspace);
+    }
+
+    this.state.preferences = {
+      autoDetectWorkspace: legacyPreferences.auto_detect_workspace ?? true,
+      confirmDestructiveOperations: legacyPreferences.confirm_destructive_operations ?? true
+    };
+
+    // Save to new format
+    await this.save();
+
+    // Backup legacy files
+    await this.backupLegacyFiles();
+  }
+
+  /**
+   * Backup legacy configuration files
+   * 
+   * @private
+   */
+  async backupLegacyFiles() {
+    const homeDir = os.homedir();
+    const legacyWorkspacesPath = path.join(homeDir, '.kse', 'workspaces.json');
+    const legacyConfigPath = path.join(homeDir, '.kse', 'config.json');
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+
+    if (await fs.pathExists(legacyWorkspacesPath)) {
+      const backupPath = path.join(homeDir, '.kse', `workspaces.json.backup-${timestamp}`);
+      await fs.copy(legacyWorkspacesPath, backupPath);
+      await fs.remove(legacyWorkspacesPath);
+    }
+
+    if (await fs.pathExists(legacyConfigPath)) {
+      const backupPath = path.join(homeDir, '.kse', `config.json.backup-${timestamp}`);
+      await fs.copy(legacyConfigPath, backupPath);
+      await fs.remove(legacyConfigPath);
+    }
+  }
+
+  /**
+   * Save workspace state to disk (atomic operation)
+   * 
+   * Uses temp file + atomic rename to ensure consistency
+   * 
+   * @returns {Promise<boolean>} True if saved successfully
+   */
+  async save() {
+    try {
+      // Ensure directory exists
+      const stateDir = path.dirname(this.statePath);
+      await fs.ensureDir(stateDir);
+
+      // Serialize state
+      const workspacesArray = Array.from(this.state.workspaces.values()).map(ws => ws.toDict());
+
+      const data = {
+        version: this.state.version,
+        activeWorkspace: this.state.activeWorkspace,
+        workspaces: workspacesArray,
+        preferences: {
+          autoDetectWorkspace: this.state.preferences.autoDetectWorkspace,
+          confirmDestructiveOperations: this.state.preferences.confirmDestructiveOperations
+        }
+      };
+
+      // Write to temp file first
+      const tempPath = `${this.statePath}.tmp`;
+      await fs.writeFile(tempPath, JSON.stringify(data, null, 2), 'utf8');
+
+      // Atomic rename (ensures consistency)
+      await fs.rename(tempPath, this.statePath);
+
+      return true;
+    } catch (error) {
+      throw new Error(`Failed to save workspace state: ${error.message}`);
+    }
+  }
+
+  /**
+   * Ensure state is loaded before operations
+   * 
+   * @private
+   */
+  async ensureLoaded() {
+    if (!this.loaded) {
+      await this.load();
+    }
+  }
+
+  // ==================== Workspace Operations ====================
+
+  /**
+   * Create a new workspace (atomic operation)
+   * 
+   * @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) {
+    await this.ensureLoaded();
+
+    // Validate name
+    if (!name || typeof name !== 'string' || name.trim().length === 0) {
+      throw new Error('Workspace name cannot be empty');
+    }
+
+    // Check for duplicate name
+    if (this.state.workspaces.has(name)) {
+      throw new Error(`Workspace "${name}" already exists`);
+    }
+
+    // Validate path (check for .kiro directory)
+    const kiroPath = path.join(workspacePath, '.kiro');
+    const kiroExists = await fs.pathExists(kiroPath);
+    if (!kiroExists) {
+      throw new Error(`Path "${workspacePath}" is not a valid kse project directory. ` +
+                     `Ensure it exists and contains a .kiro/ directory.`);
+    }
+
+    // Create workspace
+    const workspace = new Workspace(name, workspacePath);
+    this.state.workspaces.set(name, workspace);
+
+    // Atomic save
+    await this.save();
+
+    return workspace;
+  }
+
+  /**
+   * Get a workspace by name
+   * 
+   * @param {string} name - Workspace name
+   * @returns {Promise<Workspace|null>} Workspace or null if not found
+   */
+  async getWorkspace(name) {
+    await this.ensureLoaded();
+    return this.state.workspaces.get(name) || null;
+  }
+
+  /**
+   * List all registered workspaces
+   * 
+   * @returns {Promise<Array<Workspace>>} Array of workspaces
+   */
+  async listWorkspaces() {
+    await this.ensureLoaded();
+    return Array.from(this.state.workspaces.values());
+  }
+
+  /**
+   * Remove a workspace from the registry (atomic operation)
+   * 
+   * @param {string} name - Workspace name
+   * @returns {Promise<boolean>} True if removed, false if not found
+   */
+  async removeWorkspace(name) {
+    await this.ensureLoaded();
+
+    if (!this.state.workspaces.has(name)) {
+      return false;
+    }
+
+    // Remove workspace
+    this.state.workspaces.delete(name);
+
+    // Clear active workspace if it was the removed one
+    if (this.state.activeWorkspace === name) {
+      this.state.activeWorkspace = null;
+    }
+
+    // Atomic save
+    await this.save();
+
+    return true;
+  }
+
+  /**
+   * Switch to a workspace (atomic operation)
+   * 
+   * Updates both active workspace and last accessed timestamp atomically
+   * 
+   * @param {string} name - Workspace name
+   * @returns {Promise<void>}
+   * @throws {Error} If workspace doesn't exist
+   */
+  async switchWorkspace(name) {
+    await this.ensureLoaded();
+
+    const workspace = this.state.workspaces.get(name);
+    if (!workspace) {
+      const available = Array.from(this.state.workspaces.keys());
+      throw new Error(
+        `Workspace "${name}" does not exist.\n` +
+        `Available workspaces: ${available.join(', ') || 'none'}`
+      );
+    }
+
+    // Update state atomically
+    this.state.activeWorkspace = name;
+    workspace.updateLastAccessed();
+
+    // Atomic save
+    await this.save();
+  }
+
+  /**
+   * Get the active workspace
+   * 
+   * @returns {Promise<Workspace|null>} Active workspace or null
+   */
+  async getActiveWorkspace() {
+    await this.ensureLoaded();
+
+    if (!this.state.activeWorkspace) {
+      return null;
+    }
+
+    const workspace = this.state.workspaces.get(this.state.activeWorkspace);
+    if (!workspace) {
+      // Active workspace no longer exists, clear it
+      this.state.activeWorkspace = null;
+      await this.save();
+      return null;
+    }
+
+    return workspace;
+  }
+
+  /**
+   * Clear the active workspace
+   * 
+   * @returns {Promise<void>}
+   */
+  async clearActiveWorkspace() {
+    await this.ensureLoaded();
+    this.state.activeWorkspace = null;
+    await this.save();
+  }
+
+  /**
+   * 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) {
+    await this.ensureLoaded();
+
+    const absolutePath = path.isAbsolute(targetPath) 
+      ? targetPath 
+      : path.resolve(targetPath);
+
+    for (const workspace of this.state.workspaces.values()) {
+      if (workspace.containsPath(absolutePath)) {
+        return workspace;
+      }
+    }
+
+    return null;
+  }
+
+  // ==================== Preference Operations ====================
+
+  /**
+   * Get a preference value
+   * 
+   * @param {string} key - Preference key
+   * @returns {Promise<any>} Preference value
+   */
+  async getPreference(key) {
+    await this.ensureLoaded();
+    return this.state.preferences[key];
+  }
+
+  /**
+   * Set a preference value
+   * 
+   * @param {string} key - Preference key
+   * @param {any} value - Preference value
+   * @returns {Promise<void>}
+   */
+  async setPreference(key, value) {
+    await this.ensureLoaded();
+    this.state.preferences[key] = value;
+    await this.save();
+  }
+
+  /**
+   * Get all preferences
+   * 
+   * @returns {Promise<Object>} All preferences
+   */
+  async getPreferences() {
+    await this.ensureLoaded();
+    return { ...this.state.preferences };
+  }
+
+  // ==================== Utility Methods ====================
+
+  /**
+   * Check if a workspace name exists
+   * 
+   * @param {string} name - Workspace name
+   * @returns {Promise<boolean>} True if exists
+   */
+  async hasWorkspace(name) {
+    await this.ensureLoaded();
+    return this.state.workspaces.has(name);
+  }
+
+  /**
+   * Get count of registered workspaces
+   * 
+   * @returns {Promise<number>} Number of workspaces
+   */
+  async count() {
+    await this.ensureLoaded();
+    return this.state.workspaces.size;
+  }
+
+  /**
+   * Clear all workspaces (for testing purposes)
+   * 
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    await this.ensureLoaded();
+    this.state.workspaces.clear();
+    this.state.activeWorkspace = null;
+    await this.save();
+  }
+
+  /**
+   * Reset to default state
+   * 
+   * @returns {Promise<void>}
+   */
+  async reset() {
+    this.state = {
+      version: '1.0',
+      activeWorkspace: null,
+      workspaces: new Map(),
+      preferences: {
+        autoDetectWorkspace: true,
+        confirmDestructiveOperations: true
+      }
+    };
+    await this.save();
+  }
+}
+
+module.exports = WorkspaceStateManager;

package/lib/workspace/multi/workspace.js

@@ -0,0 +1,90 @@
+const PathUtils = require('./path-utils');
+
+/**
+ * Workspace - Data model for a registered kse project workspace
+ * 
+ * Represents a single workspace entry in the workspace registry.
+ * Each workspace has a unique name, absolute path, and timestamps.
+ */
+class Workspace {
+  /**
+   * Create a new Workspace instance
+   * 
+   * @param {string} name - Unique workspace name
+   * @param {string} workspacePath - Absolute path to the workspace directory
+   * @param {Date|string} createdAt - Creation timestamp (optional, defaults to now)
+   * @param {Date|string} lastAccessed - Last accessed timestamp (optional, defaults to now)
+   */
+  constructor(name, workspacePath, createdAt = null, lastAccessed = null) {
+    this.name = name;
+    this.path = PathUtils.normalize(workspacePath);
+    this.createdAt = createdAt ? new Date(createdAt) : new Date();
+    this.lastAccessed = lastAccessed ? new Date(lastAccessed) : new Date();
+  }
+
+  /**
+   * Get platform-specific path for runtime use
+   * 
+   * @returns {string} Platform-specific path
+   */
+  getPlatformPath() {
+    return PathUtils.toPlatform(this.path);
+  }
+
+  /**
+   * Serialize workspace to JSON-compatible object
+   * 
+   * @returns {Object} Serialized workspace data
+   */
+  toDict() {
+    return {
+      name: this.name,
+      path: this.path,
+      createdAt: this.createdAt.toISOString(),
+      lastAccessed: this.lastAccessed.toISOString()
+    };
+  }
+
+  /**
+   * Deserialize workspace from JSON-compatible object
+   * 
+   * @param {Object} data - Serialized workspace data
+   * @returns {Workspace} Workspace instance
+   */
+  static fromDict(data) {
+    return new Workspace(
+      data.name,
+      data.path,
+      data.createdAt,
+      data.lastAccessed
+    );
+  }
+
+  /**
+   * Update last accessed timestamp to current time
+   */
+  updateLastAccessed() {
+    this.lastAccessed = new Date();
+  }
+
+  /**
+   * Check if this workspace path matches or contains the given path
+   * 
+   * @param {string} targetPath - Path to check
+   * @returns {boolean} True if targetPath is within this workspace
+   */
+  containsPath(targetPath) {
+    return PathUtils.isWithin(targetPath, this.path);
+  }
+
+  /**
+   * Get a string representation of the workspace
+   * 
+   * @returns {string} String representation
+   */
+  toString() {
+    return `Workspace(name="${this.name}", path="${this.path}")`;
+  }
+}
+
+module.exports = Workspace;