@orderful/droid 0.18.0 → 0.19.0

package/src/lib/migrations.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { getToolMigrations } from './migrations';
+
+describe('migrations', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = join(tmpdir(), `droid-migration-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(testDir)) {
+      rmSync(testDir, { recursive: true });
+    }
+  });
+
+  describe('getToolMigrations', () => {
+    it('should return migrations for known tools', () => {
+      const brainMigrations = getToolMigrations('brain');
+      expect(brainMigrations.length).toBeGreaterThan(0);
+      expect(brainMigrations[0].version).toBe('0.2.3');
+    });
+
+    it('should return empty array for unknown tools', () => {
+      const migrations = getToolMigrations('unknown-tool');
+      expect(migrations).toEqual([]);
+    });
+
+    it('should have migrations for all renamed tools', () => {
+      const tools = ['brain', 'comments', 'project', 'coach'];
+      for (const tool of tools) {
+        const migrations = getToolMigrations(tool);
+        expect(migrations.length).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  describe('config directory migration', () => {
+    it('should move old prefixed directory to unprefixed', () => {
+      // Setup: create old prefixed directory with config
+      const skillsDir = join(testDir, 'skills');
+      const oldDir = join(skillsDir, 'droid-brain');
+      const newDir = join(skillsDir, 'brain');
+
+      mkdirSync(oldDir, { recursive: true });
+      writeFileSync(join(oldDir, 'overrides.yaml'), 'brain_dir: /test/path\n');
+
+      // Get the migration and run it
+      const migrations = getToolMigrations('brain');
+      const migration = migrations[0];
+      migration.up(testDir);
+
+      // Verify
+      expect(existsSync(oldDir)).toBe(false);
+      expect(existsSync(newDir)).toBe(true);
+      expect(readFileSync(join(newDir, 'overrides.yaml'), 'utf-8')).toBe('brain_dir: /test/path\n');
+    });
+
+    it('should be idempotent - no error if old directory already moved', () => {
+      // Setup: only new directory exists (already migrated)
+      const skillsDir = join(testDir, 'skills');
+      const newDir = join(skillsDir, 'brain');
+
+      mkdirSync(newDir, { recursive: true });
+      writeFileSync(join(newDir, 'overrides.yaml'), 'brain_dir: /test/path\n');
+
+      // Get the migration and run it - should not throw
+      const migrations = getToolMigrations('brain');
+      const migration = migrations[0];
+
+      expect(() => migration.up(testDir)).not.toThrow();
+      expect(existsSync(newDir)).toBe(true);
+    });
+
+    it('should handle collision by removing old directory', () => {
+      // Setup: both old and new directories exist
+      const skillsDir = join(testDir, 'skills');
+      const oldDir = join(skillsDir, 'droid-brain');
+      const newDir = join(skillsDir, 'brain');
+
+      mkdirSync(oldDir, { recursive: true });
+      mkdirSync(newDir, { recursive: true });
+      writeFileSync(join(oldDir, 'overrides.yaml'), 'old: true\n');
+      writeFileSync(join(newDir, 'overrides.yaml'), 'new: true\n');
+
+      // Run migration
+      const migrations = getToolMigrations('brain');
+      const migration = migrations[0];
+      migration.up(testDir);
+
+      // Old should be removed, new should be preserved
+      expect(existsSync(oldDir)).toBe(false);
+      expect(existsSync(newDir)).toBe(true);
+      expect(readFileSync(join(newDir, 'overrides.yaml'), 'utf-8')).toBe('new: true\n');
+    });
+
+    it('should do nothing if neither directory exists', () => {
+      // Setup: empty skills directory
+      const skillsDir = join(testDir, 'skills');
+      mkdirSync(skillsDir, { recursive: true });
+
+      // Run migration - should not throw
+      const migrations = getToolMigrations('brain');
+      const migration = migrations[0];
+
+      expect(() => migration.up(testDir)).not.toThrow();
+    });
+
+    it('should create parent directory if needed', () => {
+      // Setup: old directory exists but skills/ parent doesn't exist for new
+      const oldDir = join(testDir, 'skills', 'droid-brain');
+      mkdirSync(oldDir, { recursive: true });
+      writeFileSync(join(oldDir, 'overrides.yaml'), 'test: true\n');
+
+      // Run migration
+      const migrations = getToolMigrations('brain');
+      const migration = migrations[0];
+      migration.up(testDir);
+
+      // Should have moved successfully
+      const newDir = join(testDir, 'skills', 'brain');
+      expect(existsSync(newDir)).toBe(true);
+      expect(existsSync(oldDir)).toBe(false);
+    });
+  });
+
+  describe('migration versions', () => {
+    it('brain migration should be version 0.2.3', () => {
+      const migrations = getToolMigrations('brain');
+      expect(migrations[0].version).toBe('0.2.3');
+    });
+
+    it('comments migration should be version 0.2.6', () => {
+      const migrations = getToolMigrations('comments');
+      expect(migrations[0].version).toBe('0.2.6');
+    });
+
+    it('project migration should be version 0.1.5', () => {
+      const migrations = getToolMigrations('project');
+      expect(migrations[0].version).toBe('0.1.5');
+    });
+
+    it('coach migration should be version 0.1.3', () => {
+      const migrations = getToolMigrations('coach');
+      expect(migrations[0].version).toBe('0.1.3');
+    });
+  });
+
+  describe('migration descriptions', () => {
+    it('should have descriptive migration descriptions', () => {
+      const tools = ['brain', 'comments', 'project', 'coach'];
+      for (const tool of tools) {
+        const migrations = getToolMigrations(tool);
+        expect(migrations[0].description).toContain('config');
+        expect(migrations[0].description).toContain('unprefixed');
+      }
+    });
+  });
+});

package/src/lib/migrations.ts

@@ -0,0 +1,182 @@
+import { existsSync, appendFileSync, mkdirSync, renameSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { loadConfig, saveConfig, getConfigDir } from './config';
+import { type Migration } from './types';
+import { compareSemver } from './version';
+
+const MIGRATIONS_LOG_FILE = '.migrations.log';
+
+/**
+ * Get the path to the migrations log file
+ */
+function getMigrationsLogPath(): string {
+  return join(getConfigDir(), MIGRATIONS_LOG_FILE);
+}
+
+/**
+ * Log a migration event to the hidden log file
+ */
+function logMigration(
+  toolName: string,
+  fromVersion: string,
+  toVersion: string,
+  status: 'OK' | 'FAILED',
+  error?: string
+): void {
+  const timestamp = new Date().toISOString();
+  const logEntry = error
+    ? `${timestamp} ${toolName} ${fromVersion} → ${toVersion} ${status}: ${error}\n`
+    : `${timestamp} ${toolName} ${fromVersion} → ${toVersion} ${status}\n`;
+
+  const logPath = getMigrationsLogPath();
+  const logDir = dirname(logPath);
+
+  if (!existsSync(logDir)) {
+    mkdirSync(logDir, { recursive: true });
+  }
+
+  appendFileSync(logPath, logEntry);
+}
+
+// ============================================================================
+// Tool Migrations Registry
+// Define migrations here, keyed by tool name
+// ============================================================================
+
+/**
+ * Migration: Move droid-prefixed config directories to unprefixed names
+ * e.g., ~/.droid/skills/droid-brain/ → ~/.droid/skills/brain/
+ *
+ * This fixes a bug where config was saved to prefixed paths but SKILL.md
+ * tells Claude to read from unprefixed paths.
+ */
+function createConfigDirMigration(skillName: string, version: string): Migration {
+  const unprefixedName = skillName.replace(/^droid-/, '');
+  return {
+    version,
+    description: `Move ${skillName} config to unprefixed location`,
+    up: (configDir: string) => {
+      const oldDir = join(configDir, 'skills', skillName);
+      const newDir = join(configDir, 'skills', unprefixedName);
+
+      // Only migrate if old exists and new doesn't
+      if (existsSync(oldDir) && !existsSync(newDir)) {
+        // Ensure parent directory exists
+        const parentDir = dirname(newDir);
+        if (!existsSync(parentDir)) {
+          mkdirSync(parentDir, { recursive: true });
+        }
+        renameSync(oldDir, newDir);
+      } else if (existsSync(oldDir) && existsSync(newDir)) {
+        // Both exist - remove the old one (new takes precedence)
+        rmSync(oldDir, { recursive: true });
+      }
+    },
+  };
+}
+
+/**
+ * Registry of all tool migrations
+ * Key: tool name (e.g., "brain", "comments")
+ * Value: array of migrations sorted by version
+ *
+ * Migration versions are set to the next version after each tool's current version:
+ * - brain: 0.2.2 → 0.2.3
+ * - comments: 0.2.5 → 0.2.6
+ * - project: 0.1.4 → 0.1.5
+ * - coach: 0.1.2 → 0.1.3
+ */
+const TOOL_MIGRATIONS: Record<string, Migration[]> = {
+  brain: [createConfigDirMigration('droid-brain', '0.2.3')],
+  comments: [createConfigDirMigration('droid-comments', '0.2.6')],
+  project: [createConfigDirMigration('droid-project', '0.1.5')],
+  coach: [createConfigDirMigration('droid-coach', '0.1.3')],
+};
+
+/**
+ * Get migrations for a tool
+ */
+export function getToolMigrations(toolName: string): Migration[] {
+  return TOOL_MIGRATIONS[toolName] ?? [];
+}
+
+/**
+ * Get the last migrated version for a tool
+ */
+export function getLastMigratedVersion(toolName: string): string {
+  const config = loadConfig();
+  return config.migrations?.[toolName] ?? '0.0.0';
+}
+
+/**
+ * Update the last migrated version for a tool
+ */
+export function setLastMigratedVersion(toolName: string, version: string): void {
+  const config = loadConfig();
+  if (!config.migrations) {
+    config.migrations = {};
+  }
+  config.migrations[toolName] = version;
+  saveConfig(config);
+}
+
+/**
+ * Run migrations for a tool between two versions
+ * Returns true if all migrations succeeded, false otherwise
+ */
+export function runMigrations(
+  toolName: string,
+  fromVersion: string,
+  toVersion: string
+): { success: boolean; error?: string } {
+  const migrations = getToolMigrations(toolName);
+
+  // Filter migrations that need to run (version > fromVersion && version <= toVersion)
+  const pendingMigrations = migrations.filter((m) => {
+    const afterFrom = compareSemver(m.version, fromVersion) > 0;
+    const beforeOrAtTo = compareSemver(m.version, toVersion) <= 0;
+    return afterFrom && beforeOrAtTo;
+  });
+
+  if (pendingMigrations.length === 0) {
+    // No migrations to run, but still update the version marker
+    setLastMigratedVersion(toolName, toVersion);
+    return { success: true };
+  }
+
+  const configDir = getConfigDir();
+
+  for (const migration of pendingMigrations) {
+    try {
+      migration.up(configDir);
+      logMigration(toolName, fromVersion, migration.version, 'OK');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logMigration(toolName, fromVersion, migration.version, 'FAILED', errorMessage);
+      // Don't update version marker on failure - will retry next time
+      return { success: false, error: `Migration ${migration.version} failed: ${errorMessage}` };
+    }
+  }
+
+  // All migrations succeeded, update version marker
+  setLastMigratedVersion(toolName, toVersion);
+  return { success: true };
+}
+
+/**
+ * Run migrations for a tool after install/update
+ * Call this after installSkill() completes
+ */
+export function runToolMigrations(
+  toolName: string,
+  installedVersion: string
+): { success: boolean; error?: string } {
+  const lastMigrated = getLastMigratedVersion(toolName);
+
+  // Only run if the installed version is newer than last migrated
+  if (compareSemver(installedVersion, lastMigrated) <= 0) {
+    return { success: true };
+  }
+
+  return runMigrations(toolName, lastMigrated, installedVersion);
+}

package/src/lib/skill-config.ts

@@ -86,7 +86,9 @@ export async function promptForSkillConfig(
 
   if (Object.keys(overrides).length > 0) {
     saveSkillOverrides(skillName, overrides);
-    console.log(chalk.green(`\n✓ Configuration saved to ~/.droid/skills/${skillName}/overrides.yaml`));
+    // Strip droid- prefix for display since that's where the file actually goes
+    const displayName = skillName.replace(/^droid-/, '');
+    console.log(chalk.green(`\n✓ Configuration saved to ~/.droid/skills/${displayName}/overrides.yaml`));
   } else {
     console.log(chalk.gray('\nNo custom configuration set (using defaults).'));
   }

package/src/lib/skills.ts

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, rmSync } from 'fs';
-import { join, dirname } from 'path';
+import { join, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
 import YAML from 'yaml';
 import { loadConfig, saveConfig } from './config';
@@ -7,6 +7,7 @@ import { Platform, SkillStatus, type SkillManifest, type InstalledSkill, getPlat
 import { getInstalledAgentsDir, installAgentFromPath, uninstallAgent, isAgentInstalled } from './agents';
 import { getSkillsPath, getCommandsPath, getConfigPath } from './platforms';
 import { loadToolManifest } from './tools';
+import { runToolMigrations } from './migrations';
 
 // Marker comments for CLAUDE.md skill registration
 const DROID_SKILLS_START = '<!-- droid-skills-start -->';
@@ -542,6 +543,14 @@ export function installSkill(skillName: string): { success: boolean; message: st
   const installedSkillNames = Object.keys(updatedTools);
   updatePlatformConfigSkills(config.platform, installedSkillNames);
 
+  // Run tool migrations (keyed by tool name, not skill name)
+  const toolName = basename(toolDir);
+  const migrationResult = runToolMigrations(toolName, manifest.version);
+  if (!migrationResult.success) {
+    // Log warning but don't fail the install - migration will retry next time
+    console.warn(`Warning: Migration failed for ${toolName}: ${migrationResult.error}`);
+  }
+
   return { success: true, message: `Installed ${skillName} v${manifest.version}` };
 }
 

package/src/lib/types.ts

@@ -54,6 +54,7 @@ export interface DroidConfig {
   git_username: string;
   platforms: Record<string, PlatformConfig>;
   auto_update?: AutoUpdateConfig;
+  migrations?: Record<string, string>; // tool name -> last migrated version
 }
 
 // Legacy config structure for migration
@@ -120,6 +121,16 @@ export interface SkillOverrides {
   [key: string]: string | boolean | number;
 }
 
+/**
+ * Tool migration function
+ * Should be idempotent - safe to run multiple times
+ */
+export interface Migration {
+  version: string;
+  description: string;
+  up: (configDir: string) => Promise<void> | void;
+}
+
 /**
  * Tool manifest structure (TOOL.yaml)
  */

package/src/tools/brain/TOOL.yaml

@@ -1,6 +1,6 @@
 name: brain
 description: "Your scratchpad (or brain) - a collaborative space for planning and research. Create docs with /brain plan, /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions."
-version: 0.2.2
+version: 0.2.3
 status: beta
 
 includes:

package/src/tools/coach/TOOL.yaml

@@ -1,6 +1,6 @@
 name: coach
 description: "Learning-mode AI assistance - AI as coach, not crutch. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions."
-version: 0.1.2
+version: 0.1.3
 status: beta
 
 includes:

package/src/tools/comments/TOOL.yaml

@@ -1,6 +1,6 @@
 name: comments
 description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
-version: 0.2.5
+version: 0.2.6
 status: beta
 
 includes:

package/src/tools/project/TOOL.yaml

@@ -1,6 +1,6 @@
 name: project
 description: "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features."
-version: 0.1.4
+version: 0.1.5
 status: beta
 
 includes: