@cuewright/skills 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuewright/skills",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "CLI installer for the Cuewright skills framework",
   "type": "module",
   "engines": {

package/src/commands/doctor.js

@@ -1,8 +1,9 @@
 import chalk from 'chalk';
-import { access, readFile, lstat } from 'fs/promises';
+import { access, readFile, lstat } from 'fs/promises'; // lstat used in checks 3-4
 import { join } from 'path';
 import { cwd } from 'process';
 import { readManifest, listSkills, getVersion } from '../utils/manifest.js';
+import { inventorySkillsDir } from '../utils/symlink.js';
 import { getSkillsDir, getFrameworkDir } from '../adapters/claude.js';
 
 export async function doctor() {
@@ -75,32 +76,29 @@ export async function doctor() {
     }
   }
 
-  // 4b. Check for legacy unprefixed skill directories (old install, needs migration)
-  const legacySkillNames = skills.map(s => s.replace(/^cw-/, ''));
-  const legacyFound = [];
-  for (const name of legacySkillNames) {
-    const legacyPath = join(skillsDir, name);
-    try {
-      const stat = await lstat(legacyPath);
-      if (stat.isDirectory()) {
-        legacyFound.push(name);
-      }
-    } catch {
-      // Not present — good
-    }
-  }
+  // 4b. Inventory skills directory — detect legacy and orphaned entries
+  const { legacy: legacyFound, orphaned: orphanedFound } = await inventorySkillsDir(skillsDir, skills);
 
   if (legacyFound.length > 0) {
     allPassed = false;
     checks.push(fail(
       `${legacyFound.length} legacy skill director${legacyFound.length === 1 ? 'y' : 'ies'} found (pre-v0.15.0 install)`,
-      'Run `cuewright update` to migrate to cw- prefix and move reference files to arch/references/.'
+      'Run `cuewright update` to clean up automatically.'
     ));
     for (const name of legacyFound) {
       checks.push(fail(`  .claude/skills/${name}/`, null));
     }
   }
 
+  if (orphanedFound.length > 0) {
+    checks.push(warn(
+      `${orphanedFound.length} unknown director${orphanedFound.length === 1 ? 'y' : 'ies'} in .claude/skills/ (third-party or project-local — no action needed)`
+    ));
+    for (const name of orphanedFound) {
+      checks.push(warn(`  .claude/skills/${name}/`));
+    }
+  }
+
   // 5. arch/project-config.md exists
   const configPath = join(projectRoot, '.claude', 'skills', 'arch', 'project-config.md');
   if (!await exists(configPath)) {

package/src/commands/update.js

@@ -1,9 +1,9 @@
 import chalk from 'chalk';
-import { access, readFile, unlink, readdir, rename, mkdir } from 'fs/promises';
+import { access, readFile, unlink, mkdir } from 'fs/promises';
 import { join } from 'path';
 import { cwd } from 'process';
 import { readManifest, listSkills, getVersion } from '../utils/manifest.js';
-import { syncSymlinks, syncCopies, platformSupportsSymlinks, buildHeader } from '../utils/symlink.js';
+import { syncSymlinks, syncCopies, platformSupportsSymlinks, cleanupLegacyDirectories } from '../utils/symlink.js';
 import { updateSubmodule, fetchTags, getLatestTag, getLatestTagFromRemote, configureSparseCheckout } from '../storage/submodule.js';
 import { cloneFramework } from '../storage/copy.js';
 import { getSkillsDir, getFrameworkDir } from '../adapters/claude.js';
@@ -43,7 +43,8 @@ export async function update(options) {
   const targetVersion = (options.to || await resolveLatestTag(frameworkDir, isSubmodule)).replace(/^v/, '');
 
   if (targetVersion === oldVersion) {
-    console.log(chalk.cyan(`Already at v${oldVersion} (latest). Nothing to update.`));
+    console.log(chalk.cyan(`Already at v${oldVersion} (latest).`));
+    await runCleanup(skillsDir, listSkills(oldManifest), projectRoot, dryRun);
     return;
   }
 
@@ -74,11 +75,10 @@ export async function update(options) {
     console.log(`New skills: ${added.join(', ')}`);
     if (!dryRun) {
       const useCopies = !platformSupportsSymlinks();
-      if (useCopies) {
-        await syncCopies(frameworkDir, skillsDir, added, targetVersion);
-      } else {
-        await syncSymlinks(frameworkDir, skillsDir, added);
-      }
+      const { errors: syncErrors } = useCopies
+        ? await syncCopies(frameworkDir, skillsDir, added, targetVersion)
+        : await syncSymlinks(frameworkDir, skillsDir, added);
+      for (const e of syncErrors) console.log(chalk.yellow(`  warning: ${e}`));
     }
   }
 
@@ -87,29 +87,22 @@ export async function update(options) {
       const skillPath = join(skillsDir, name);
       if (await exists(skillPath)) {
         const isRealDir = await isRealDirectory(skillPath);
-        if (isRealDir) {
-          // Check if this is a cw- rename migration (old unprefixed name → cw-name)
-          const isMigrationRename = newSkills.has(`cw-${name}`);
-          if (isMigrationRename) {
-            if (!dryRun) {
-              await migrateSkillDirectory(skillPath, name, skillsDir, projectRoot);
-            } else {
-              console.log(chalk.yellow(`  migrate: ${name}/ → arch/references/${name}/ (reference files) + remove SKILL.md`));
-            }
-          } else {
-            console.log(chalk.yellow(`  warning: '${name}' removed from framework. Local directory at .claude/skills/${name}/ left in place.`));
-          }
-        } else {
+        if (!isRealDir) {
           // Symlink to now-missing target — clean it up
           if (!dryRun) {
             await unlink(skillPath);
           }
           console.log(`  Removed stale symlink: ${name}`);
+        } else {
+          console.log(chalk.yellow(`  warning: '${name}' removed from framework. Local directory at .claude/skills/${name}/ left in place.`));
         }
       }
     }
   }
 
+  // Always run legacy cleanup — catches dirs that survived the diff-based migration
+  await runCleanup(skillsDir, [...newSkills], projectRoot, dryRun);
+
   // Scaffold arch/references/ and arch/templates/ if missing
   if (!dryRun) {
     const archDir = join(projectRoot, '.claude', 'skills', 'arch');
@@ -143,48 +136,12 @@ export async function update(options) {
   }
 }
 
-/**
- * Migrate an old skill directory during the cw- rename:
- * - Move any non-SKILL.md files to arch/references/<name>/
- * - Remove the SKILL.md (it was a framework copy, overrides are gone)
- * - Remove the now-empty directory
- */
-async function migrateSkillDirectory(skillPath, name, skillsDir, projectRoot) {
-  const archReferencesDir = join(projectRoot, '.claude', 'skills', 'arch', 'references', name);
-
-  let entries;
-  try {
-    entries = await readdir(skillPath);
-  } catch {
-    return;
-  }
-
-  const referenceFiles = entries.filter(e => e !== 'SKILL.md');
-
-  if (referenceFiles.length > 0) {
-    await mkdir(archReferencesDir, { recursive: true });
-    for (const file of referenceFiles) {
-      const src = join(skillPath, file);
-      const dest = join(archReferencesDir, file);
-      await rename(src, dest);
-    }
-    console.log(`  Moved ${referenceFiles.length} reference file(s) to arch/references/${name}/`);
-  }
-
-  // Remove SKILL.md and the directory
-  try {
-    await unlink(join(skillPath, 'SKILL.md'));
-  } catch {
-    // Already gone or never existed
-  }
-
-  try {
-    const { rmdir } = await import('fs/promises');
-    await rmdir(skillPath);
-    console.log(`  Removed legacy skill directory: ${name}/`);
-  } catch {
-    console.log(chalk.yellow(`  warning: Could not remove .claude/skills/${name}/ — remove it manually.`));
+async function runCleanup(skillsDir, manifestSkillNames, projectRoot, dryRun) {
+  const { cleaned, errors } = await cleanupLegacyDirectories(skillsDir, manifestSkillNames, projectRoot, { dryRun });
+  if (cleaned.length > 0) {
+    console.log(chalk.green(`  Cleaned up ${cleaned.length} legacy director${cleaned.length === 1 ? 'y' : 'ies'}: ${cleaned.join(', ')}`));
   }
+  for (const e of errors) console.log(chalk.yellow(`  warning: ${e}`));
 }
 
 /**

package/src/utils/symlink.js

@@ -1,4 +1,4 @@
-import { symlink, mkdir, access, lstat, readFile, writeFile } from 'fs/promises';
+import { symlink, mkdir, access, lstat, readFile, writeFile, readdir, unlink, rename } from 'fs/promises';
 import { join } from 'path';
 
 /**
@@ -129,3 +129,143 @@ export function buildHeader(skillName, version) {
 export function platformSupportsSymlinks() {
   return process.platform !== 'win32';
 }
+
+/**
+ * Remove old unprefixed skill directories that correspond to cw-* framework skills.
+ *
+ * This runs independently of the manifest diff, so it catches directories that
+ * survived the initial migration (e.g., rmdir failed due to non-empty content)
+ * as well as directories from even older installs that were never in a manifest.
+ *
+ * For each cw-* skill in manifestSkillNames, checks for a real directory or
+ * symlink at skillsDir/<unprefixed-name>/ and cleans it up:
+ * - Symlink: unlinked (was an old framework pointer)
+ * - Real directory: reference files moved to arch/references/<name>/, SKILL.md
+ *   removed, directory rmdir'd
+ *
+ * Returns { cleaned: string[], errors: string[] }
+ */
+export async function cleanupLegacyDirectories(skillsDir, manifestSkillNames, projectRoot, { dryRun = false } = {}) {
+  const cleaned = [];
+  const errors = [];
+  const { join } = await import('path');
+  const { rmdir } = await import('fs/promises');
+
+  for (const cwName of manifestSkillNames) {
+    if (!cwName.startsWith('cw-')) continue;
+    const unprefixed = cwName.slice(3);
+    const legacyPath = join(skillsDir, unprefixed);
+
+    let stat;
+    try {
+      stat = await lstat(legacyPath);
+    } catch {
+      continue; // Does not exist — nothing to do
+    }
+
+    if (stat.isSymbolicLink()) {
+      if (!dryRun) {
+        try {
+          await unlink(legacyPath);
+        } catch (err) {
+          errors.push(`${unprefixed}: could not remove symlink — ${err.message}`);
+          continue;
+        }
+      }
+      cleaned.push(unprefixed);
+      continue;
+    }
+
+    if (!stat.isDirectory()) continue;
+
+    // Real directory — migrate reference files, then remove
+    let entries;
+    try {
+      entries = await readdir(legacyPath);
+    } catch (err) {
+      errors.push(`${unprefixed}: could not read directory — ${err.message}`);
+      continue;
+    }
+
+    const referenceFiles = entries.filter(e => e !== 'SKILL.md');
+
+    if (referenceFiles.length > 0 && !dryRun) {
+      const refDir = join(projectRoot, '.claude', 'skills', 'arch', 'references', unprefixed);
+      try {
+        await mkdir(refDir, { recursive: true });
+        for (const file of referenceFiles) {
+          await rename(join(legacyPath, file), join(refDir, file));
+        }
+      } catch (err) {
+        errors.push(`${unprefixed}: could not migrate reference files — ${err.message}`);
+        continue;
+      }
+    }
+
+    if (!dryRun) {
+      try {
+        await unlink(join(legacyPath, 'SKILL.md'));
+      } catch {
+        // Already gone or never existed — fine
+      }
+
+      try {
+        await rmdir(legacyPath);
+      } catch {
+        errors.push(`${unprefixed}: directory not empty after migration — remove .claude/skills/${unprefixed}/ manually`);
+        continue;
+      }
+    }
+
+    cleaned.push(unprefixed);
+  }
+
+  return { cleaned, errors };
+}
+
+/**
+ * Scan skillsDir and categorize every entry.
+ *
+ * Returns:
+ * {
+ *   legacy: string[],    // unprefixed dirs matching a cw-* manifest skill
+ *   orphaned: string[],  // dirs that don't match any manifest skill or reserved name
+ * }
+ *
+ * Reserved names (skipped): _framework, _baseline, arch, worktrees
+ * Framework skills (cw-*) are not included in the return — they're already
+ * checked by the main doctor health checks.
+ */
+export async function inventorySkillsDir(skillsDir, manifestSkillNames) {
+  const { join } = await import('path');
+  const legacy = [];
+  const orphaned = [];
+
+  const RESERVED = new Set(['_framework', '_baseline', 'arch', 'worktrees']);
+  const unprefixedNames = new Set(
+    manifestSkillNames.filter(n => n.startsWith('cw-')).map(n => n.slice(3))
+  );
+  const cwNames = new Set(manifestSkillNames);
+
+  let entries;
+  try {
+    entries = await readdir(skillsDir, { withFileTypes: true });
+  } catch {
+    return { legacy, orphaned };
+  }
+
+  for (const entry of entries) {
+    const name = entry.name;
+    if (RESERVED.has(name)) continue;
+    if (cwNames.has(name)) continue; // framework skill — handled by main checks
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+
+    if (unprefixedNames.has(name)) {
+      legacy.push(name);
+    } else {
+      orphaned.push(name);
+    }
+  }
+
+  return { legacy, orphaned };
+}