scene-capability-engine 3.0.0

package/lib/utils/fs-utils.js

@@ -0,0 +1,274 @@
+/**
+ * File System Utilities
+ * 
+ * Provides safe, atomic file operations for the adoption/upgrade system.
+ * Implements path validation, atomic writes, and error handling.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Validates that a file path is within the project directory
+ * Prevents path traversal attacks
+ * 
+ * @param {string} projectPath - Absolute path to project root
+ * @param {string} filePath - Relative or absolute file path to validate
+ * @returns {string} - Validated absolute path
+ * @throws {Error} - If path traversal is detected
+ */
+function validatePath(projectPath, filePath) {
+  const resolvedProject = path.resolve(projectPath);
+  const resolvedFile = path.resolve(projectPath, filePath);
+  
+  if (!resolvedFile.startsWith(resolvedProject)) {
+    throw new Error(`Path traversal detected: ${filePath} is outside project directory`);
+  }
+  
+  return resolvedFile;
+}
+
+/**
+ * Atomically writes content to a file
+ * Uses temp file + rename for atomicity
+ * 
+ * @param {string} filePath - Absolute path to target file
+ * @param {string} content - Content to write
+ * @returns {Promise<void>}
+ */
+async function atomicWrite(filePath, content) {
+  const tempPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).substr(2, 9)}`;
+  
+  try {
+    // Write to temp file
+    await fs.writeFile(tempPath, content, 'utf8');
+    
+    // Atomic rename (on most systems)
+    await fs.rename(tempPath, filePath);
+  } catch (error) {
+    // Clean up temp file if it exists
+    try {
+      await fs.unlink(tempPath);
+    } catch (cleanupError) {
+      // Ignore cleanup errors
+    }
+    
+    throw new Error(`Failed to write file atomically: ${error.message}`);
+  }
+}
+
+/**
+ * Safely copies a file with error handling
+ * Creates parent directories if needed
+ * 
+ * @param {string} sourcePath - Absolute path to source file
+ * @param {string} destPath - Absolute path to destination file
+ * @param {Object} options - Copy options
+ * @param {boolean} options.overwrite - Whether to overwrite existing file (default: false)
+ * @returns {Promise<void>}
+ */
+async function safeCopy(sourcePath, destPath, options = {}) {
+  const { overwrite = false } = options;
+  
+  try {
+    // Check if source exists
+    const sourceExists = await fs.pathExists(sourcePath);
+    if (!sourceExists) {
+      throw new Error(`Source file does not exist: ${sourcePath}`);
+    }
+    
+    // Check if destination exists
+    const destExists = await fs.pathExists(destPath);
+    if (destExists && !overwrite) {
+      throw new Error(`Destination file already exists: ${destPath}`);
+    }
+    
+    // Ensure parent directory exists
+    const parentDir = path.dirname(destPath);
+    await fs.ensureDir(parentDir);
+    
+    // Copy file
+    await fs.copy(sourcePath, destPath, { overwrite });
+  } catch (error) {
+    throw new Error(`Failed to copy file: ${error.message}`);
+  }
+}
+
+/**
+ * Recursively creates a directory
+ * Safe to call even if directory already exists
+ * 
+ * @param {string} dirPath - Absolute path to directory
+ * @returns {Promise<void>}
+ */
+async function ensureDirectory(dirPath) {
+  try {
+    await fs.ensureDir(dirPath);
+  } catch (error) {
+    throw new Error(`Failed to create directory: ${error.message}`);
+  }
+}
+
+/**
+ * Recursively copies a directory
+ * 
+ * @param {string} sourceDir - Absolute path to source directory
+ * @param {string} destDir - Absolute path to destination directory
+ * @param {Object} options - Copy options
+ * @param {boolean} options.overwrite - Whether to overwrite existing files (default: false)
+ * @param {Function} options.filter - Filter function (path) => boolean
+ * @returns {Promise<void>}
+ */
+async function copyDirectory(sourceDir, destDir, options = {}) {
+  const { overwrite = false, filter = null } = options;
+  
+  try {
+    await fs.copy(sourceDir, destDir, {
+      overwrite,
+      filter: filter || (() => true)
+    });
+  } catch (error) {
+    throw new Error(`Failed to copy directory: ${error.message}`);
+  }
+}
+
+/**
+ * Checks if a path exists
+ * 
+ * @param {string} filePath - Path to check
+ * @returns {Promise<boolean>}
+ */
+async function pathExists(filePath) {
+  return fs.pathExists(filePath);
+}
+
+/**
+ * Reads a JSON file safely
+ * 
+ * @param {string} filePath - Absolute path to JSON file
+ * @returns {Promise<Object>} - Parsed JSON object
+ * @throws {Error} - If file doesn't exist or JSON is invalid
+ */
+async function readJSON(filePath) {
+  try {
+    return await fs.readJSON(filePath);
+  } catch (error) {
+    throw new Error(`Failed to read JSON file: ${error.message}`);
+  }
+}
+
+/**
+ * Writes a JSON file atomically
+ * 
+ * @param {string} filePath - Absolute path to JSON file
+ * @param {Object} data - Data to write
+ * @param {Object} options - Write options
+ * @param {number} options.spaces - Number of spaces for indentation (default: 2)
+ * @returns {Promise<void>}
+ */
+async function writeJSON(filePath, data, options = {}) {
+  const { spaces = 2 } = options;
+  const content = JSON.stringify(data, null, spaces);
+  await atomicWrite(filePath, content);
+}
+
+/**
+ * Removes a file or directory
+ * 
+ * @param {string} targetPath - Path to remove
+ * @returns {Promise<void>}
+ */
+async function remove(targetPath) {
+  try {
+    await fs.remove(targetPath);
+  } catch (error) {
+    throw new Error(`Failed to remove path: ${error.message}`);
+  }
+}
+
+/**
+ * Gets file stats
+ * 
+ * @param {string} filePath - Path to file
+ * @returns {Promise<fs.Stats>}
+ */
+async function getStats(filePath) {
+  try {
+    return await fs.stat(filePath);
+  } catch (error) {
+    throw new Error(`Failed to get file stats: ${error.message}`);
+  }
+}
+
+/**
+ * Lists files in a directory
+ * 
+ * @param {string} dirPath - Path to directory
+ * @returns {Promise<string[]>} - Array of file names
+ */
+async function listFiles(dirPath) {
+  try {
+    return await fs.readdir(dirPath);
+  } catch (error) {
+    throw new Error(`Failed to list directory: ${error.message}`);
+  }
+}
+
+/**
+ * Recursively lists all files in a directory
+ * 
+ * @param {string} dirPath - Path to directory
+ * @param {string[]} fileList - Accumulator for recursive calls
+ * @returns {Promise<string[]>} - Array of absolute file paths
+ */
+async function listFilesRecursive(dirPath, fileList = []) {
+  const files = await fs.readdir(dirPath);
+  
+  for (const file of files) {
+    const filePath = path.join(dirPath, file);
+    const stat = await fs.stat(filePath);
+    
+    if (stat.isDirectory()) {
+      await listFilesRecursive(filePath, fileList);
+    } else {
+      fileList.push(filePath);
+    }
+  }
+  
+  return fileList;
+}
+
+/**
+ * Calculates total size of a directory
+ * 
+ * @param {string} dirPath - Path to directory
+ * @returns {Promise<number>} - Total size in bytes
+ */
+async function getDirectorySize(dirPath) {
+  const files = await listFilesRecursive(dirPath);
+  let totalSize = 0;
+  
+  for (const file of files) {
+    const stats = await fs.stat(file);
+    totalSize += stats.size;
+  }
+  
+  return totalSize;
+}
+
+module.exports = {
+  validatePath,
+  atomicWrite,
+  safeCopy,
+  ensureDirectory,
+  copyDirectory,
+  pathExists,
+  readJSON,
+  writeJSON,
+  remove,
+  getStats,
+  listFiles,
+  listFilesRecursive,
+  getDirectorySize
+};

package/lib/utils/tool-detector.js

@@ -0,0 +1,383 @@
+/**
+ * Tool Detector
+ * 
+ * Detects which IDE/editor the user is using
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Detect the current IDE/editor environment
+ * 
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Detection result
+ */
+async function detectTool(projectPath) {
+  const detections = {
+    kiro: await detectKiroIDE(projectPath),
+    vscode: await detectVSCode(projectPath),
+    cursor: await detectCursor(projectPath),
+    other: null
+  };
+
+  // Determine primary tool
+  let primaryTool = 'unknown';
+  let confidence = 'low';
+
+  if (detections.kiro.detected) {
+    primaryTool = 'kiro';
+    confidence = detections.kiro.confidence;
+  } else if (detections.cursor.detected && detections.cursor.confidence === 'high') {
+    // Only use Cursor if we have high confidence (Cursor-specific indicators)
+    primaryTool = 'cursor';
+    confidence = detections.cursor.confidence;
+  } else if (detections.vscode.detected) {
+    primaryTool = 'vscode';
+    confidence = detections.vscode.confidence;
+  } else if (detections.cursor.detected) {
+    // Fallback to Cursor if VS Code not detected
+    primaryTool = 'cursor';
+    confidence = detections.cursor.confidence;
+  } else {
+    primaryTool = 'other';
+    confidence = 'low';
+  }
+
+  return {
+    primaryTool,
+    confidence,
+    detections,
+    recommendations: getRecommendations(primaryTool, detections)
+  };
+}
+
+/**
+ * Detect Kiro IDE
+ * 
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Detection result
+ */
+async function detectKiroIDE(projectPath) {
+  const indicators = [];
+  let detected = false;
+  let confidence = 'low';
+
+  // Check for .kiro directory
+  const kiroDir = path.join(projectPath, '.kiro');
+  if (await fs.pathExists(kiroDir)) {
+    indicators.push('.kiro directory exists');
+    detected = true;
+    confidence = 'medium';
+  }
+
+  // Check for Kiro-specific files
+  const kiroFiles = [
+    '.kiro/steering',
+    '.kiro/specs',
+    '.kiro/tools'
+  ];
+
+  for (const file of kiroFiles) {
+    const filePath = path.join(projectPath, file);
+    if (await fs.pathExists(filePath)) {
+      indicators.push(`${file} exists`);
+      confidence = 'high';
+    }
+  }
+
+  // Check for environment variables (if running in Kiro)
+  if (process.env.KIRO_IDE === 'true' || process.env.KIRO_VERSION) {
+    indicators.push('Kiro environment variables detected');
+    detected = true;
+    confidence = 'high';
+  }
+
+  return {
+    detected,
+    confidence,
+    indicators,
+    features: detected ? ['agent-hooks', 'native-integration'] : []
+  };
+}
+
+/**
+ * Detect VS Code
+ * 
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Detection result
+ */
+async function detectVSCode(projectPath) {
+  const indicators = [];
+  let detected = false;
+  let confidence = 'low';
+
+  // Check for .vscode directory
+  const vscodeDir = path.join(projectPath, '.vscode');
+  if (await fs.pathExists(vscodeDir)) {
+    indicators.push('.vscode directory exists');
+    detected = true;
+    confidence = 'medium';
+  }
+
+  // Check for VS Code specific files
+  const vscodeFiles = [
+    '.vscode/settings.json',
+    '.vscode/launch.json',
+    '.vscode/tasks.json'
+  ];
+
+  for (const file of vscodeFiles) {
+    const filePath = path.join(projectPath, file);
+    if (await fs.pathExists(filePath)) {
+      indicators.push(`${file} exists`);
+      confidence = 'high';
+    }
+  }
+
+  // Check for environment variables
+  if (process.env.VSCODE_PID || process.env.TERM_PROGRAM === 'vscode') {
+    indicators.push('VS Code environment detected');
+    detected = true;
+    confidence = 'high';
+  }
+
+  return {
+    detected,
+    confidence,
+    indicators,
+    features: detected ? ['watch-mode', 'manual-workflows'] : []
+  };
+}
+
+/**
+ * Detect Cursor
+ * 
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Detection result
+ */
+async function detectCursor(projectPath) {
+  const indicators = [];
+  let detected = false;
+  let confidence = 'low';
+
+  // Cursor uses similar structure to VS Code
+  const vscodeDir = path.join(projectPath, '.vscode');
+  if (await fs.pathExists(vscodeDir)) {
+    indicators.push('.vscode directory exists (Cursor compatible)');
+    detected = true;
+    confidence = 'low'; // Could be VS Code or Cursor
+  }
+
+  // Check for Cursor-specific indicators
+  if (process.env.CURSOR_VERSION || process.env.TERM_PROGRAM === 'cursor') {
+    indicators.push('Cursor environment detected');
+    detected = true;
+    confidence = 'high';
+  }
+
+  // Check for Cursor-specific settings
+  const settingsPath = path.join(projectPath, '.vscode/settings.json');
+  if (await fs.pathExists(settingsPath)) {
+    try {
+      const settings = await fs.readJson(settingsPath);
+      if (settings['cursor.aiEnabled'] !== undefined || 
+          settings['cursor.chat'] !== undefined) {
+        indicators.push('Cursor-specific settings found');
+        confidence = 'high';
+      }
+    } catch (error) {
+      // Ignore JSON parse errors
+    }
+  }
+
+  return {
+    detected,
+    confidence,
+    indicators,
+    features: detected ? ['watch-mode', 'manual-workflows', 'ai-integration'] : []
+  };
+}
+
+/**
+ * Get recommendations based on detected tool
+ * 
+ * @param {string} primaryTool - Primary tool name
+ * @param {Object} detections - All detections
+ * @returns {Array} Recommendations
+ */
+function getRecommendations(primaryTool, detections) {
+  const recommendations = [];
+
+  switch (primaryTool) {
+    case 'kiro':
+      recommendations.push({
+        type: 'native',
+        title: 'Use Kiro Agent Hooks',
+        description: 'You can use native Kiro agent hooks for seamless automation',
+        action: 'Configure hooks in .kiro/hooks/'
+      });
+      recommendations.push({
+        type: 'optional',
+        title: 'Watch Mode Available',
+        description: 'Watch mode is also available as a fallback option',
+        action: 'Run: kse watch init'
+      });
+      break;
+
+    case 'vscode':
+    case 'cursor':
+      recommendations.push({
+        type: 'primary',
+        title: 'Use Watch Mode',
+        description: 'Watch mode provides automated file monitoring for your IDE',
+        action: 'Run: kse watch init && kse watch install auto-sync'
+      });
+      recommendations.push({
+        type: 'preset',
+        title: 'Install Presets',
+        description: 'Pre-configured automation patterns for common workflows',
+        action: 'Run: kse watch presets'
+      });
+      break;
+
+    case 'other':
+    default:
+      recommendations.push({
+        type: 'manual',
+        title: 'Manual Workflows',
+        description: 'Follow documented manual workflows for your tool',
+        action: 'See: docs/cross-tool-guide.md'
+      });
+      recommendations.push({
+        type: 'watch',
+        title: 'Try Watch Mode',
+        description: 'Watch mode works with most editors and IDEs',
+        action: 'Run: kse watch init'
+      });
+      break;
+  }
+
+  return recommendations;
+}
+
+/**
+ * Get automation suggestions based on tool
+ * 
+ * @param {string} tool - Tool name
+ * @returns {Array} Suggestions
+ */
+function getAutomationSuggestions(tool) {
+  const suggestions = {
+    kiro: [
+      'Configure agent hooks for automatic task sync',
+      'Set up prompt regeneration on spec changes',
+      'Enable context export on task completion'
+    ],
+    vscode: [
+      'Install auto-sync preset for task synchronization',
+      'Use watch mode for automated workflows',
+      'Configure VS Code tasks for manual triggers'
+    ],
+    cursor: [
+      'Install auto-sync preset for task synchronization',
+      'Use watch mode for automated workflows',
+      'Leverage Cursor AI for enhanced productivity'
+    ],
+    other: [
+      'Follow manual workflow documentation',
+      'Consider using watch mode for automation',
+      'Set up shell aliases for common commands'
+    ]
+  };
+
+  return suggestions[tool] || suggestions.other;
+}
+
+/**
+ * Generate auto-configuration for detected tool
+ * 
+ * @param {Object} detection - Detection result from detectTool
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Auto-configuration result
+ */
+async function generateAutoConfig(detection, projectPath) {
+  const { primaryTool, confidence } = detection;
+  
+  const config = {
+    tool: primaryTool,
+    confidence,
+    suggestedPresets: [],
+    suggestedCommands: [],
+    configPath: null,
+    notes: []
+  };
+
+  switch (primaryTool) {
+    case 'kiro':
+      config.suggestedPresets = [];
+      config.suggestedCommands = [
+        'Use native Kiro agent hooks (see .kiro/hooks/)',
+        'Optional: kse watch init (for watch mode fallback)'
+      ];
+      config.notes.push('Kiro IDE detected - native hooks are recommended');
+      config.notes.push('Watch mode available as fallback option');
+      break;
+
+    case 'vscode':
+    case 'cursor':
+      config.suggestedPresets = ['auto-sync', 'prompt-regen', 'context-export'];
+      config.suggestedCommands = [
+        'kse watch init',
+        'kse watch install auto-sync',
+        'kse watch start'
+      ];
+      config.configPath = path.join(projectPath, '.kiro/watch-config.json');
+      config.notes.push(`${primaryTool === 'vscode' ? 'VS Code' : 'Cursor'} detected - watch mode recommended`);
+      config.notes.push('Run suggested commands to set up automation');
+      break;
+
+    case 'other':
+    default:
+      config.suggestedPresets = ['auto-sync'];
+      config.suggestedCommands = [
+        'kse watch init',
+        'kse watch install auto-sync',
+        'See: docs/cross-tool-guide.md for manual workflows'
+      ];
+      config.notes.push('No specific IDE detected');
+      config.notes.push('Watch mode available for basic automation');
+      config.notes.push('Manual workflows documented in docs/');
+      break;
+  }
+
+  return config;
+}
+
+/**
+ * Offer to install presets interactively
+ * 
+ * @param {Object} detection - Detection result from detectTool
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Installation result
+ */
+async function offerPresetInstallation(detection, projectPath) {
+  const config = await generateAutoConfig(detection, projectPath);
+  
+  return {
+    success: true,
+    config,
+    message: 'Auto-configuration generated successfully'
+  };
+}
+
+module.exports = {
+  detectTool,
+  detectKiroIDE,
+  detectVSCode,
+  detectCursor,
+  getRecommendations,
+  getAutomationSuggestions,
+  generateAutoConfig,
+  offerPresetInstallation
+};