@cuewright/skills 0.2.1 → 0.2.3

package/package.json

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

package/src/commands/doctor.js

@@ -76,8 +76,8 @@ export async function doctor() {
     }
   }
 
-  // 4b. Inventory skills directory — detect legacy and orphaned entries
-  const { legacy: legacyFound, orphaned: orphanedFound } = await inventorySkillsDir(skillsDir, skills);
+  // 4b. Inventory skills directory — detect legacy, dead framework, and orphaned entries
+  const { legacy: legacyFound, deadFramework: deadFound, orphaned: orphanedFound } = await inventorySkillsDir(skillsDir, skills);
 
   if (legacyFound.length > 0) {
     allPassed = false;
@@ -90,6 +90,17 @@ export async function doctor() {
     }
   }
 
+  if (deadFound.length > 0) {
+    allPassed = false;
+    checks.push(fail(
+      `${deadFound.length} broken framework symlink${deadFound.length === 1 ? '' : 's'} found (retired skills with no target)`,
+      'Run `cuewright update` to clean up automatically.'
+    ));
+    for (const name of deadFound) {
+      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)`

package/src/utils/symlink.js

@@ -1,4 +1,4 @@
-import { symlink, mkdir, access, lstat, readFile, writeFile, readdir, unlink, rename } from 'fs/promises';
+import { symlink, mkdir, access, lstat, readFile, writeFile, readdir, unlink, rename, readlink } from 'fs/promises';
 import { join } from 'path';
 
 /**
@@ -190,7 +190,7 @@ export async function cleanupLegacyDirectories(skillsDir, manifestSkillNames, pr
     const referenceFiles = entries.filter(e => e !== 'SKILL.md');
 
     if (referenceFiles.length > 0 && !dryRun) {
-      const refDir = join(projectRoot, '.claude', 'skills', 'arch', 'references', unprefixed);
+      const refDir = join(projectRoot, '.claude', 'skills', 'arch', 'references', cwName);
       try {
         await mkdir(refDir, { recursive: true });
         for (const file of referenceFiles) {
@@ -220,6 +220,61 @@ export async function cleanupLegacyDirectories(skillsDir, manifestSkillNames, pr
     cleaned.push(unprefixed);
   }
 
+  // Second pass: remove broken symlinks pointing into _framework/ with no manifest match.
+  // These are retired framework skills whose target directory no longer exists.
+  const { join: pathJoin } = await import('path');
+  const RESERVED = new Set(['_framework', '_baseline', 'arch', 'worktrees']);
+  const cwNameSet = new Set(manifestSkillNames);
+  const unprefixedSet = new Set(
+    manifestSkillNames.filter(n => n.startsWith('cw-')).map(n => n.slice(3))
+  );
+
+  let allEntries;
+  try {
+    allEntries = await readdir(skillsDir, { withFileTypes: true });
+  } catch {
+    return { cleaned, errors };
+  }
+
+  for (const entry of allEntries) {
+    const name = entry.name;
+    if (RESERVED.has(name)) continue;
+    if (cwNameSet.has(name)) continue; // active framework skill
+    if (unprefixedSet.has(name)) continue; // already handled in first pass
+    if (!entry.isSymbolicLink()) continue;
+
+    const linkPath = pathJoin(skillsDir, name);
+    let target;
+    try {
+      target = await readlink(linkPath);
+    } catch {
+      continue;
+    }
+
+    // Only touch symlinks whose target is inside _framework/skills/
+    if (!target.includes('_framework/skills/') && !target.includes('_framework\\skills\\')) continue;
+
+    // Check if the target resolves — if not, it's dead
+    let broken = false;
+    try {
+      await access(linkPath);
+    } catch {
+      broken = true;
+    }
+
+    if (!broken) continue;
+
+    if (!dryRun) {
+      try {
+        await unlink(linkPath);
+      } catch (err) {
+        errors.push(`${name}: could not remove broken framework symlink — ${err.message}`);
+        continue;
+      }
+    }
+    cleaned.push(name);
+  }
+
   return { cleaned, errors };
 }
 
@@ -239,6 +294,7 @@ export async function cleanupLegacyDirectories(skillsDir, manifestSkillNames, pr
 export async function inventorySkillsDir(skillsDir, manifestSkillNames) {
   const { join } = await import('path');
   const legacy = [];
+  const deadFramework = [];
   const orphaned = [];
 
   const RESERVED = new Set(['_framework', '_baseline', 'arch', 'worktrees']);
@@ -251,7 +307,7 @@ export async function inventorySkillsDir(skillsDir, manifestSkillNames) {
   try {
     entries = await readdir(skillsDir, { withFileTypes: true });
   } catch {
-    return { legacy, orphaned };
+    return { legacy, deadFramework, orphaned };
   }
 
   for (const entry of entries) {
@@ -262,10 +318,35 @@ export async function inventorySkillsDir(skillsDir, manifestSkillNames) {
 
     if (unprefixedNames.has(name)) {
       legacy.push(name);
-    } else {
-      orphaned.push(name);
+      continue;
+    }
+
+    if (entry.isSymbolicLink()) {
+      // Check if this is a broken symlink into _framework/
+      let target;
+      try {
+        target = await readlink(join(skillsDir, name));
+      } catch {
+        orphaned.push(name);
+        continue;
+      }
+
+      if (target.includes('_framework/skills/') || target.includes('_framework\\skills\\')) {
+        let broken = false;
+        try {
+          await access(join(skillsDir, name));
+        } catch {
+          broken = true;
+        }
+        if (broken) {
+          deadFramework.push(name);
+          continue;
+        }
+      }
     }
+
+    orphaned.push(name);
   }
 
-  return { legacy, orphaned };
+  return { legacy, deadFramework, orphaned };
 }