onbuzz 3.3.0

package/src/utilities/toolConstants.js

@@ -0,0 +1,415 @@
+/**
+ * Tool Command Constants
+ * 
+ * Centralized constants for tool command recognition and parsing
+ * This ensures consistent tool identification across the system
+ */
+
+/**
+ * Tool IDs - The canonical identifiers for each tool
+ */
+export const TOOL_IDS = {
+  AGENT_COMMUNICATION: 'agentcommunication',
+  TERMINAL: 'terminal',
+  FILESYSTEM: 'filesystem',
+  // BROWSER: 'browser', // DEPRECATED - use WEB instead
+  AGENT_DELAY: 'agentdelay',
+  JOB_DONE: 'jobdone',
+  TASK_MANAGER: 'taskmanager',
+  IMPORT_ANALYZER: 'import-analyzer',
+  DEPENDENCY_RESOLVER: 'dependency-resolver',
+  IMAGE_GEN: 'image-gen',
+  VIDEO_GEN: 'video-gen',
+  CLONE_DETECTION: 'clonedetection',
+  FILE_TREE: 'file-tree',
+  FILE_CONTENT_REPLACE: 'file-content-replace',
+  SEEK: 'seek',
+  WEB: 'web',
+  STATIC_ANALYSIS: 'staticanalysis',
+  HELP: 'help',
+  PDF: 'pdf',
+  DOC: 'doc',
+  SPREADSHEET: 'spreadsheet',
+  SKILLS: 'skills',
+  VISION: 'vision'
+};
+
+/**
+ * Agent Communication Tool Actions
+ * These are the valid action types for the agent communication tool
+ */
+export const AGENT_COMM_ACTIONS = {
+  GET_AVAILABLE: 'get-available-agents',
+  SEND_MESSAGE: 'send-message',
+  REPLY_MESSAGE: 'reply-to-message',
+  GET_UNREPLIED: 'get-unreplied-messages',
+  MARK_ENDED: 'mark-conversation-ended'
+};
+
+/**
+ * Terminal Tool Actions
+ */
+export const TERMINAL_ACTIONS = {
+  RUN_COMMAND: 'run-command',
+  CHANGE_DIR: 'change-directory',
+  LIST_DIR: 'list-directory',
+  CREATE_DIR: 'create-directory',
+  GET_CWD: 'get-working-directory'
+};
+
+/**
+ * Filesystem Tool Actions
+ */
+export const FILESYSTEM_ACTIONS = {
+  READ_FILE: 'read-file',
+  WRITE_FILE: 'write-file',
+  APPEND_FILE: 'append-file',
+  DELETE_FILE: 'delete-file',
+  LIST_FILES: 'list-files',
+  CREATE_DIR: 'fs-create-directory',  // Prefixed to avoid conflict with terminal
+  DELETE_DIR: 'fs-delete-directory',  // Prefixed for consistency
+  MOVE_FILE: 'move-file',
+  COPY_FILE: 'copy-file',
+  GET_INFO: 'get-file-info'
+};
+
+/**
+ * Browser Tool Actions
+ * @deprecated Use WEB tool instead - Browser tool is deprecated as of December 2024
+ */
+export const BROWSER_ACTIONS = {
+  NAVIGATE: 'navigate',
+  CLICK: 'click',
+  TYPE: 'type',
+  SCREENSHOT: 'screenshot',
+  GET_TEXT: 'get-text',
+  WAIT: 'wait-for-element',
+  SCROLL: 'scroll',
+  CLOSE: 'close-browser'
+};
+
+/**
+ * Job Done Tool Actions
+ */
+export const JOBDONE_ACTIONS = {
+  COMPLETE: 'complete',
+  COMPLETE_WITH_RESULT: 'complete-with-result',
+  FAIL: 'fail-with-error'
+};
+
+/**
+ * Agent Delay Tool Actions
+ */
+export const DELAY_ACTIONS = {
+  DELAY: 'delay',
+  PAUSE: 'pause'
+};
+
+/**
+ * TaskManager Tool Actions
+ */
+export const TASK_MANAGER_ACTIONS = {
+  CREATE: 'create',
+  UPDATE: 'update',
+  LIST: 'list',
+  COMPLETE: 'complete',
+  CANCEL: 'cancel',
+  CLEAR: 'clear',
+  DEPEND: 'depend',
+  RELATE: 'relate',
+  SUBTASK: 'subtask',
+  PRIORITIZE: 'prioritize',
+  TEMPLATE: 'template',
+  PROGRESS: 'progress',
+  ANALYTICS: 'analytics'
+};
+
+/**
+ * Clone Detection Tool Actions
+ */
+export const CLONE_DETECTION_ACTIONS = {
+  DETECT_CLONES: 'detect-clones'
+};
+
+/**
+ * Help Tool Actions
+ */
+export const HELP_ACTIONS = {
+  GET_DESCRIPTION: 'get-description',
+  LIST_TOOLS: 'list-tools'
+};
+
+/**
+ * PDF Tool Actions
+ */
+export const PDF_ACTIONS = {
+  GET_INFO: 'get-info',
+  READ_PAGES: 'read-pages',
+  CREATE_PDF: 'create-pdf'
+};
+
+/**
+ * Document (DOCX) Tool Actions
+ */
+export const DOC_ACTIONS = {
+  GET_INFO: 'get-info',
+  READ: 'read',
+  CREATE: 'create'
+};
+
+/**
+ * Spreadsheet (Excel) Tool Actions
+ */
+export const SPREADSHEET_ACTIONS = {
+  GET_INFO: 'get-info',
+  READ: 'read',
+  CREATE: 'create'
+};
+
+/**
+ * Skills Tool Actions
+ */
+export const SKILLS_ACTIONS = {
+  LIST: 'list',
+  DESCRIBE: 'describe',
+  READ: 'read',
+  READ_SECTION: 'read-section',
+  READ_FILE: 'read-file',
+  CREATE: 'create',
+  UPDATE: 'update',
+  DELETE: 'delete',
+  IMPORT: 'import'
+};
+
+/**
+ * Tool Command Formats
+ * JSON is the LLM industry standard format (preferred)
+ * XML and bracket notation are supported for backward compatibility
+ */
+export const COMMAND_FORMATS = {
+  JSON: 'json',           // Standard format: ```json {...} ```
+  JSON_PLAIN: 'json-plain', // Plain JSON (fallback, not recommended)
+  XML: 'xml',             // Legacy: <toolname>...</toolname>
+  BRACKET: 'bracket',     // Legacy: [tool id="..."]...[/tool]
+  REDIRECT: 'redirect'    // Agent redirects
+};
+
+/**
+ * Tool Recognition Map
+ * Maps action types to their corresponding tool IDs
+ * This is the single source of truth for tool identification
+ */
+export const TOOL_ACTION_MAP = {
+  // Agent Communication Tool
+  [AGENT_COMM_ACTIONS.GET_AVAILABLE]: TOOL_IDS.AGENT_COMMUNICATION,
+  [AGENT_COMM_ACTIONS.SEND_MESSAGE]: TOOL_IDS.AGENT_COMMUNICATION,
+  [AGENT_COMM_ACTIONS.REPLY_MESSAGE]: TOOL_IDS.AGENT_COMMUNICATION,
+  [AGENT_COMM_ACTIONS.GET_UNREPLIED]: TOOL_IDS.AGENT_COMMUNICATION,
+  [AGENT_COMM_ACTIONS.MARK_ENDED]: TOOL_IDS.AGENT_COMMUNICATION,
+  
+  // Terminal Tool
+  [TERMINAL_ACTIONS.RUN_COMMAND]: TOOL_IDS.TERMINAL,
+  [TERMINAL_ACTIONS.CHANGE_DIR]: TOOL_IDS.TERMINAL,
+  [TERMINAL_ACTIONS.LIST_DIR]: TOOL_IDS.TERMINAL,
+  [TERMINAL_ACTIONS.CREATE_DIR]: TOOL_IDS.TERMINAL,
+  [TERMINAL_ACTIONS.GET_CWD]: TOOL_IDS.TERMINAL,
+  
+  // Filesystem Tool
+  [FILESYSTEM_ACTIONS.READ_FILE]: TOOL_IDS.FILESYSTEM,
+  [FILESYSTEM_ACTIONS.WRITE_FILE]: TOOL_IDS.FILESYSTEM,
+  [FILESYSTEM_ACTIONS.APPEND_FILE]: TOOL_IDS.FILESYSTEM,
+  [FILESYSTEM_ACTIONS.DELETE_FILE]: TOOL_IDS.FILESYSTEM,
+  [FILESYSTEM_ACTIONS.LIST_FILES]: TOOL_IDS.FILESYSTEM,
+  [FILESYSTEM_ACTIONS.CREATE_DIR]: TOOL_IDS.FILESYSTEM,
+  [FILESYSTEM_ACTIONS.DELETE_DIR]: TOOL_IDS.FILESYSTEM,
+  [FILESYSTEM_ACTIONS.MOVE_FILE]: TOOL_IDS.FILESYSTEM,
+  [FILESYSTEM_ACTIONS.COPY_FILE]: TOOL_IDS.FILESYSTEM,
+  [FILESYSTEM_ACTIONS.GET_INFO]: TOOL_IDS.FILESYSTEM,
+  
+  // Browser Tool - DEPRECATED, use WEB tool instead
+  // [BROWSER_ACTIONS.NAVIGATE]: TOOL_IDS.BROWSER,
+  // [BROWSER_ACTIONS.CLICK]: TOOL_IDS.BROWSER,
+  // [BROWSER_ACTIONS.TYPE]: TOOL_IDS.BROWSER,
+  // [BROWSER_ACTIONS.SCREENSHOT]: TOOL_IDS.BROWSER,
+  // [BROWSER_ACTIONS.GET_TEXT]: TOOL_IDS.BROWSER,
+  // [BROWSER_ACTIONS.WAIT]: TOOL_IDS.BROWSER,
+  // [BROWSER_ACTIONS.SCROLL]: TOOL_IDS.BROWSER,
+  // [BROWSER_ACTIONS.CLOSE]: TOOL_IDS.BROWSER,
+  
+  // Job Done Tool
+  [JOBDONE_ACTIONS.COMPLETE]: TOOL_IDS.JOB_DONE,
+  [JOBDONE_ACTIONS.COMPLETE_WITH_RESULT]: TOOL_IDS.JOB_DONE,
+  [JOBDONE_ACTIONS.FAIL]: TOOL_IDS.JOB_DONE,
+  
+  // Delay Tool
+  [DELAY_ACTIONS.DELAY]: TOOL_IDS.AGENT_DELAY,
+  [DELAY_ACTIONS.PAUSE]: TOOL_IDS.AGENT_DELAY,
+  
+  // TaskManager Tool
+  [TASK_MANAGER_ACTIONS.CREATE]: TOOL_IDS.TASK_MANAGER,
+  [TASK_MANAGER_ACTIONS.UPDATE]: TOOL_IDS.TASK_MANAGER,
+  [TASK_MANAGER_ACTIONS.LIST]: TOOL_IDS.TASK_MANAGER,
+  [TASK_MANAGER_ACTIONS.COMPLETE]: TOOL_IDS.TASK_MANAGER,
+  [TASK_MANAGER_ACTIONS.CANCEL]: TOOL_IDS.TASK_MANAGER,
+  [TASK_MANAGER_ACTIONS.CLEAR]: TOOL_IDS.TASK_MANAGER,
+  [TASK_MANAGER_ACTIONS.DEPEND]: TOOL_IDS.TASK_MANAGER,
+  [TASK_MANAGER_ACTIONS.RELATE]: TOOL_IDS.TASK_MANAGER,
+  [TASK_MANAGER_ACTIONS.SUBTASK]: TOOL_IDS.TASK_MANAGER,
+  [TASK_MANAGER_ACTIONS.PRIORITIZE]: TOOL_IDS.TASK_MANAGER,
+  [TASK_MANAGER_ACTIONS.TEMPLATE]: TOOL_IDS.TASK_MANAGER,
+  [TASK_MANAGER_ACTIONS.PROGRESS]: TOOL_IDS.TASK_MANAGER,
+  [TASK_MANAGER_ACTIONS.ANALYTICS]: TOOL_IDS.TASK_MANAGER,
+
+  // Clone Detection Tool
+  [CLONE_DETECTION_ACTIONS.DETECT_CLONES]: TOOL_IDS.CLONE_DETECTION,
+
+  // Help Tool
+  [HELP_ACTIONS.GET_DESCRIPTION]: TOOL_IDS.HELP,
+  [HELP_ACTIONS.LIST_TOOLS]: TOOL_IDS.HELP,
+
+  // PDF Tool
+  [PDF_ACTIONS.GET_INFO]: TOOL_IDS.PDF,
+  [PDF_ACTIONS.READ_PAGES]: TOOL_IDS.PDF,
+  [PDF_ACTIONS.CREATE_PDF]: TOOL_IDS.PDF,
+
+  // Document (DOCX) Tool
+  [DOC_ACTIONS.GET_INFO]: TOOL_IDS.DOC,
+  [DOC_ACTIONS.READ]: TOOL_IDS.DOC,
+  [DOC_ACTIONS.CREATE]: TOOL_IDS.DOC,
+
+  // Spreadsheet (Excel) Tool
+  [SPREADSHEET_ACTIONS.GET_INFO]: TOOL_IDS.SPREADSHEET,
+  [SPREADSHEET_ACTIONS.READ]: TOOL_IDS.SPREADSHEET,
+  [SPREADSHEET_ACTIONS.CREATE]: TOOL_IDS.SPREADSHEET,
+
+  // Skills Tool
+  [SKILLS_ACTIONS.LIST]: TOOL_IDS.SKILLS,
+  [SKILLS_ACTIONS.DESCRIBE]: TOOL_IDS.SKILLS,
+  [SKILLS_ACTIONS.READ]: TOOL_IDS.SKILLS,
+  [SKILLS_ACTIONS.READ_SECTION]: TOOL_IDS.SKILLS,
+  [SKILLS_ACTIONS.READ_FILE]: TOOL_IDS.SKILLS,
+  [SKILLS_ACTIONS.CREATE]: TOOL_IDS.SKILLS,
+  [SKILLS_ACTIONS.UPDATE]: TOOL_IDS.SKILLS,
+  [SKILLS_ACTIONS.DELETE]: TOOL_IDS.SKILLS,
+  [SKILLS_ACTIONS.IMPORT]: TOOL_IDS.SKILLS
+};
+
+/**
+ * JSON Command Structure Types
+ * Different JSON structures we support
+ */
+export const JSON_STRUCTURES = {
+  // Standard format: {"toolId": "...", "parameters": {...}}
+  STANDARD: 'standard',
+  
+  // Actions format: {"actions": [{"type": "...", ...}]}
+  ACTIONS_ARRAY: 'actions-array',
+  
+  // Tool commands format: {"toolCommands": [{...}]}
+  TOOL_COMMANDS: 'tool-commands',
+  
+  // Direct action format: {"type": "...", ...}
+  DIRECT_ACTION: 'direct-action'
+};
+
+/**
+ * Identify which JSON structure is being used
+ */
+export function identifyJsonStructure(jsonData) {
+  if (!jsonData || typeof jsonData !== 'object') {
+    return null;
+  }
+  
+  if (jsonData.toolId && (jsonData.parameters || jsonData.actions)) {
+    return JSON_STRUCTURES.STANDARD;
+  }
+  
+  if (jsonData.actions && Array.isArray(jsonData.actions)) {
+    return JSON_STRUCTURES.ACTIONS_ARRAY;
+  }
+  
+  if (jsonData.toolCommands && Array.isArray(jsonData.toolCommands)) {
+    return JSON_STRUCTURES.TOOL_COMMANDS;
+  }
+  
+  if (jsonData.type && typeof jsonData.type === 'string') {
+    return JSON_STRUCTURES.DIRECT_ACTION;
+  }
+  
+  return null;
+}
+
+/**
+ * Get tool ID from action type
+ * This is the primary method for determining which tool to use
+ */
+export function getToolIdFromAction(actionType) {
+  if (!actionType) return null;
+  
+  // Normalize the action type to handle case variations
+  const normalizedAction = actionType.trim();
+  
+  // Direct lookup first (most efficient)
+  if (TOOL_ACTION_MAP[normalizedAction]) {
+    return TOOL_ACTION_MAP[normalizedAction];
+  }
+  
+  // Case-insensitive lookup as fallback
+  const lowerAction = normalizedAction.toLowerCase();
+  for (const [action, toolId] of Object.entries(TOOL_ACTION_MAP)) {
+    if (action.toLowerCase() === lowerAction) {
+      return toolId;
+    }
+  }
+  
+  // Log unrecognized actions for debugging
+  console.warn(`Unrecognized action type: "${actionType}"`);
+  
+  return null;
+}
+
+/**
+ * Validate if a tool ID is valid
+ */
+export function isValidToolId(toolId) {
+  return Object.values(TOOL_IDS).includes(toolId);
+}
+
+/**
+ * Get all valid actions for a specific tool
+ */
+export function getToolActions(toolId) {
+  const actions = [];
+  for (const [action, tool] of Object.entries(TOOL_ACTION_MAP)) {
+    if (tool === toolId) {
+      actions.push(action);
+    }
+  }
+  return actions;
+}
+
+/**
+ * Export all constants for easy access
+ */
+export default {
+  TOOL_IDS,
+  AGENT_COMM_ACTIONS,
+  TERMINAL_ACTIONS,
+  FILESYSTEM_ACTIONS,
+  BROWSER_ACTIONS,
+  JOBDONE_ACTIONS,
+  DELAY_ACTIONS,
+  TASK_MANAGER_ACTIONS,
+  CLONE_DETECTION_ACTIONS,
+  HELP_ACTIONS,
+  PDF_ACTIONS,
+  DOC_ACTIONS,
+  SPREADSHEET_ACTIONS,
+  COMMAND_FORMATS,
+  TOOL_ACTION_MAP,
+  JSON_STRUCTURES,
+  identifyJsonStructure,
+  getToolIdFromAction,
+  isValidToolId,
+  getToolActions
+};

package/src/utilities/userDataDir.js

@@ -0,0 +1,300 @@
+/**
+ * User Data Directory Utility
+ *
+ * Determines the appropriate persistent storage location for user data
+ * that survives package updates (npm i -g).
+ *
+ * This solves the critical issue where user data (agents, conversations,
+ * settings, API keys) was lost when updating the globally installed package
+ * because data was stored relative to the package installation directory.
+ *
+ * Storage Locations by Platform:
+ * - Linux:   ~/.local/share/loxia-autopilot/
+ * - macOS:   ~/Library/Application Support/loxia-autopilot/
+ * - Windows: %LOCALAPPDATA%/loxia-autopilot/ (typically C:\Users\<user>\AppData\Local\loxia-autopilot)
+ *
+ * Environment Variable Override:
+ * - LOXIA_DATA_DIR: If set, uses this path instead of the platform default
+ */
+
+import os from 'os';
+import path from 'path';
+import { promises as fs } from 'fs';
+
+const APP_NAME = 'loxia-autopilot';
+
+/**
+ * Get the platform-appropriate user data directory
+ * @returns {string} Absolute path to user data directory
+ */
+export function getUserDataDir() {
+  // Allow override via environment variable
+  if (process.env.LOXIA_DATA_DIR) {
+    return path.resolve(process.env.LOXIA_DATA_DIR);
+  }
+
+  const platform = process.platform;
+  const homeDir = os.homedir();
+
+  switch (platform) {
+    case 'win32': {
+      // Windows: Use LOCALAPPDATA (persists locally, not roamed)
+      // Falls back to APPDATA, then to home directory
+      const localAppData = process.env.LOCALAPPDATA || process.env.APPDATA;
+      if (localAppData) {
+        return path.join(localAppData, APP_NAME);
+      }
+      return path.join(homeDir, 'AppData', 'Local', APP_NAME);
+    }
+
+    case 'darwin': {
+      // macOS: Use Application Support directory
+      return path.join(homeDir, 'Library', 'Application Support', APP_NAME);
+    }
+
+    case 'linux':
+    default: {
+      // Linux/Unix: Follow XDG Base Directory Specification
+      // Use XDG_DATA_HOME if set, otherwise ~/.local/share
+      const xdgDataHome = process.env.XDG_DATA_HOME;
+      if (xdgDataHome) {
+        return path.join(xdgDataHome, APP_NAME);
+      }
+      return path.join(homeDir, '.local', 'share', APP_NAME);
+    }
+  }
+}
+
+/**
+ * Get specific subdirectories within user data directory
+ */
+export function getUserDataPaths() {
+  const baseDir = getUserDataDir();
+
+  return {
+    base: baseDir,
+    state: path.join(baseDir, 'state'),           // Agent state, conversations
+    agents: path.join(baseDir, 'state', 'agents'), // Individual agent data
+    settings: path.join(baseDir, 'settings'),      // User settings, API keys
+    attachments: path.join(baseDir, 'attachments'), // File attachments
+    logs: path.join(baseDir, 'logs'),              // Application logs
+    cache: path.join(baseDir, 'cache'),            // Temporary cache data
+    operations: path.join(baseDir, 'state', 'operations'), // Async operations
+    models: path.join(baseDir, 'state', 'models'), // Model router cache
+    runtime: path.join(baseDir, 'runtime'),        // Runtime data (port registry, etc.)
+    skills: path.join(baseDir, 'state', 'skills'),  // Global skills library
+  };
+}
+
+/**
+ * Ensure user data directory structure exists
+ * @returns {Promise<Object>} Created paths
+ */
+export async function ensureUserDataDirs() {
+  const paths = getUserDataPaths();
+
+  const dirsToCreate = [
+    paths.base,
+    paths.state,
+    paths.agents,
+    paths.settings,
+    paths.attachments,
+    paths.logs,
+    paths.cache,
+    paths.operations,
+    paths.models,
+    paths.runtime,
+    paths.skills,
+  ];
+
+  for (const dir of dirsToCreate) {
+    try {
+      await fs.mkdir(dir, { recursive: true });
+    } catch (error) {
+      // Ignore if already exists
+      if (error.code !== 'EEXIST') {
+        throw error;
+      }
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Check if user data directory exists and is accessible
+ * @returns {Promise<boolean>}
+ */
+export async function userDataDirExists() {
+  try {
+    const baseDir = getUserDataDir();
+    const stats = await fs.stat(baseDir);
+    return stats.isDirectory();
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Migrate data from old location to new user data directory
+ * This helps users transition from the old storage location
+ *
+ * @param {string} oldDir - Old data directory path
+ * @param {Object} options - Migration options
+ * @returns {Promise<Object>} Migration result
+ */
+export async function migrateFromOldLocation(oldDir, options = {}) {
+  const { dryRun = false, logger = null } = options;
+  const newPaths = getUserDataPaths();
+
+  const result = {
+    migrated: [],
+    skipped: [],
+    errors: [],
+  };
+
+  try {
+    // Check if old directory exists
+    try {
+      await fs.access(oldDir);
+    } catch {
+      logger?.info('No old data directory found, skipping migration', { oldDir });
+      return result;
+    }
+
+    // Check if new directory already has data (don't overwrite)
+    const newHasData = await userDataDirExists();
+    if (newHasData) {
+      const newStateDir = newPaths.state;
+      try {
+        const files = await fs.readdir(newStateDir);
+        if (files.length > 0) {
+          logger?.info('New data directory already has data, skipping migration to prevent overwrite');
+          result.skipped.push({ reason: 'new_location_has_data', path: newStateDir });
+          return result;
+        }
+      } catch {
+        // Directory doesn't exist or is empty, continue with migration
+      }
+    }
+
+    // Ensure new directories exist
+    if (!dryRun) {
+      await ensureUserDataDirs();
+    }
+
+    // Migration mappings: oldSubPath -> newPath
+    const migrations = [
+      { old: 'agents', new: newPaths.agents },
+      { old: 'operations', new: newPaths.operations },
+      { old: 'models', new: newPaths.models },
+      { old: 'attachments', new: newPaths.attachments },
+      { old: 'terminal-settings.json', new: path.join(newPaths.settings, 'terminal-settings.json') },
+      { old: 'project-state.json', new: path.join(newPaths.state, 'project-state.json') },
+      { old: 'agent-index.json', new: path.join(newPaths.state, 'agent-index.json') },
+      { old: 'last-session.json', new: path.join(newPaths.state, 'last-session.json') },
+    ];
+
+    for (const migration of migrations) {
+      const oldPath = path.join(oldDir, migration.old);
+      const newPath = migration.new;
+
+      try {
+        await fs.access(oldPath);
+
+        if (dryRun) {
+          result.migrated.push({ from: oldPath, to: newPath, dryRun: true });
+          continue;
+        }
+
+        // Check if it's a directory or file
+        const stats = await fs.stat(oldPath);
+
+        if (stats.isDirectory()) {
+          // Copy directory contents recursively
+          await copyDir(oldPath, newPath);
+        } else {
+          // Copy single file
+          await fs.copyFile(oldPath, newPath);
+        }
+
+        result.migrated.push({ from: oldPath, to: newPath });
+        logger?.info('Migrated data', { from: oldPath, to: newPath });
+
+      } catch (error) {
+        if (error.code === 'ENOENT') {
+          // File/dir doesn't exist, skip silently
+          result.skipped.push({ path: oldPath, reason: 'not_found' });
+        } else {
+          result.errors.push({ path: oldPath, error: error.message });
+          logger?.warn('Migration error', { path: oldPath, error: error.message });
+        }
+      }
+    }
+
+    if (result.migrated.length > 0 && !dryRun) {
+      logger?.info('Data migration completed', {
+        migratedCount: result.migrated.length,
+        skippedCount: result.skipped.length,
+        errorCount: result.errors.length,
+      });
+    }
+
+  } catch (error) {
+    result.errors.push({ path: oldDir, error: error.message });
+    logger?.error('Migration failed', { error: error.message });
+  }
+
+  return result;
+}
+
+/**
+ * Recursively copy a directory
+ * @param {string} src - Source directory
+ * @param {string} dest - Destination directory
+ */
+async function copyDir(src, dest) {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Get legacy data directory paths for migration detection
+ * @returns {string[]} Array of potential old data locations
+ */
+export function getLegacyDataPaths() {
+  const paths = [];
+
+  // Old location: relative to package install (inside node_modules)
+  // This won't work after package update, but useful for first-run detection
+
+  // Old location: process.cwd() based
+  const cwdBased = path.join(process.cwd(), '.loxia-state');
+  paths.push(cwdBased);
+
+  // Alternative old location
+  const cwdBasedAlt = path.join(process.cwd(), 'loxia-state');
+  paths.push(cwdBasedAlt);
+
+  return paths;
+}
+
+export default {
+  getUserDataDir,
+  getUserDataPaths,
+  ensureUserDataDirs,
+  userDataDirExists,
+  migrateFromOldLocation,
+  getLegacyDataPaths,
+};