@pharaoh-so/mcp 0.3.16 → 0.3.17

package/dist/install-skills.js

@@ -31,6 +31,15 @@ const BUNDLED_COMMANDS_DIR = join(PKG_ROOT, "commands");
  * get collision-safe distinctive names on this install path.
  */
 const SKILL_PREFIX = "pharaoh-";
+/**
+ * Filename of the install manifest written alongside the installed skills.
+ * Records which skills we installed in the previous run so the next run can
+ * diff against current source and remove skills that were cut or renamed
+ * between versions. See `cleanupRemovedSkills` for the diff logic.
+ */
+const MANIFEST_FILENAME = ".pharaoh-manifest.json";
+/** Current manifest format version. Bump on breaking shape changes. */
+const MANIFEST_VERSION = 1;
 // ── Detection ───────────────────────────────────────────────────────
 /**
  * Detect whether Claude Code is installed by checking for ~/.claude/.
@@ -83,12 +92,25 @@ function installClaudeCodePlugin(home = homedir()) {
     }
     // Install skills under the pharaoh- prefix for collision-safe names.
     const skillsDst = join(pluginDir, "skills");
+    // Read the previous install's manifest BEFORE copying fresh skills so
+    // the diff logic below sees the old state. Missing/corrupt manifest
+    // returns null → cleanupRemovedSkills becomes a no-op (first-run fallback).
+    const oldManifest = readPharaohManifest(skillsDst);
     const skillCount = installPrefixedSkills(BUNDLED_SKILLS_DIR, skillsDst, SKILL_PREFIX);
-    // Migrate: delete any bare-name skill dirs left from prior installs
-    // that used the dual bare+prefixed layout. Without this, users who
-    // upgrade keep both copies and Claude Code's prompt-name dedupe picks
-    // the wrong one.
+    // Legacy dual-layout cleanup: delete bare-name dirs matching CURRENT
+    // source skills. Still runs on every install because the manifest path
+    // doesn't know about bare-name stragglers for skills that are still in
+    // source — only about cuts.
     cleanupBareNameSkills(BUNDLED_SKILLS_DIR, skillsDst);
+    // Manifest-based cut cleanup: for any skill that was in the previous
+    // install's manifest but is no longer in current source, remove both
+    // its bare-name and pharaoh-prefixed variants. Heals the token-burn
+    // from cut/renamed skills between versions (see #788).
+    cleanupRemovedSkills(BUNDLED_SKILLS_DIR, skillsDst, oldManifest);
+    // Stamp a fresh manifest reflecting exactly what's in current source.
+    // Written AFTER install + cleanup so it always matches on-disk state,
+    // even if a corrupt old manifest caused the diff step to skip.
+    writePharaohManifest(skillsDst, getSourceSkillNames(BUNDLED_SKILLS_DIR));
     // Copy .mcp.json
     const mcpSrc = join(PKG_ROOT, ".mcp.json");
     if (existsSync(mcpSrc)) {
@@ -150,6 +172,10 @@ function installPrefixedSkills(srcDir, dstDir, prefix) {
  * skills from other sources that happen to share the `pharaoh/skills/`
  * install path).
  *
+ * This is the LEGACY cleanup — it only heals the bare+prefixed dual
+ * layout for skills that are STILL in source. Skills cut between
+ * versions are handled by `cleanupRemovedSkills` via the manifest.
+ *
  * @param srcDir - Bundled source skills directory.
  * @param dstDir - Installed skills directory.
  * @returns Number of stale directories removed.
@@ -171,6 +197,123 @@ function cleanupBareNameSkills(srcDir, dstDir) {
     }
     return removed;
 }
+/**
+ * Enumerate the bare source skill names by listing the source skills dir.
+ * Returns the names that `installPrefixedSkills` would copy (directory
+ * entries that contain a `SKILL.md`). Used by both the manifest writer
+ * and the cleanup diff logic so the two stay in lockstep.
+ *
+ * @param srcDir - Bundled source skills directory.
+ * @returns Sorted array of bare skill dir names.
+ */
+function getSourceSkillNames(srcDir) {
+    if (!existsSync(srcDir))
+        return [];
+    const names = [];
+    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        if (!existsSync(join(srcDir, entry.name, "SKILL.md")))
+            continue;
+        names.push(entry.name);
+    }
+    return names.sort();
+}
+/**
+ * Read `.pharaoh-manifest.json` from the installed skills directory.
+ *
+ * Returns `null` when:
+ * - The file does not exist (first run after this fix shipped)
+ * - The file is corrupted or not valid JSON (treated as missing, caller
+ *   will write a fresh one on the next install cycle)
+ *
+ * Corrupted-manifest handling is silent-but-logged: we don't want a bad
+ * manifest to crash the install, but we do want a warning on stderr so
+ * operators can spot persistent corruption.
+ *
+ * @param skillsDir - Installed skills directory.
+ * @returns The parsed manifest, or `null` if missing/invalid.
+ */
+function readPharaohManifest(skillsDir) {
+    const manifestPath = join(skillsDir, MANIFEST_FILENAME);
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        const raw = readFileSync(manifestPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        // Defensive shape check — a valid-JSON manifest with the wrong
+        // shape is as useful as no manifest, so we reject it and let the
+        // caller write a fresh one.
+        if (typeof parsed.version !== "number" ||
+            typeof parsed.installedAt !== "string" ||
+            !Array.isArray(parsed.skills) ||
+            !parsed.skills.every((s) => typeof s === "string")) {
+            process.stderr.write(`Pharaoh: ${MANIFEST_FILENAME} has unexpected shape — treating as missing and writing a fresh one.\n`);
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        process.stderr.write(`Pharaoh: ${MANIFEST_FILENAME} is not valid JSON — treating as missing and writing a fresh one.\n`);
+        return null;
+    }
+}
+/**
+ * Write a fresh manifest file listing the current install's bare skill
+ * names. Overwrites any existing manifest. The caller is responsible for
+ * ensuring the parent directory exists — `installPrefixedSkills` already
+ * does that as part of its own run, so writing the manifest after the
+ * install copy completes is safe.
+ *
+ * @param skillsDir - Installed skills directory.
+ * @param skills    - Bare skill names present in the current source.
+ */
+function writePharaohManifest(skillsDir, skills) {
+    const manifest = {
+        version: MANIFEST_VERSION,
+        installedAt: new Date().toISOString(),
+        skills: [...skills],
+    };
+    writeFileSync(join(skillsDir, MANIFEST_FILENAME), JSON.stringify(manifest, null, "\t"));
+}
+/**
+ * Diff-based cleanup of skills removed between versions.
+ *
+ * Reads the old manifest's skill list and removes any entry that's no
+ * longer in the current source. For each removed name, we delete BOTH
+ * the bare-name and `pharaoh-` prefixed variants — the dual-layout from
+ * the pre-prefix era means both can exist on the same machine for the
+ * same skill, and leaving either behind burns context on every session.
+ *
+ * The flagship `pharaoh` skill is exempt from deletion even if a corrupt
+ * manifest lists it as removed. Losing the flagship would break every
+ * skill slash command, and the exempt-name guard is the only thing
+ * preventing an accidental self-destruct.
+ *
+ * @param srcDir      - Bundled source skills directory.
+ * @param dstDir      - Installed skills directory.
+ * @param oldManifest - Manifest from the previous install, or `null` for
+ *   first-run-after-fix (in which case this is a no-op).
+ * @returns Number of directories removed.
+ */
+function cleanupRemovedSkills(srcDir, dstDir, oldManifest) {
+    if (!oldManifest || !existsSync(dstDir))
+        return 0;
+    const exemptName = SKILL_PREFIX.replace(/-$/, "");
+    const currentSkills = new Set(getSourceSkillNames(srcDir));
+    const removed = oldManifest.skills.filter((name) => !currentSkills.has(name) && name !== exemptName);
+    let deleted = 0;
+    for (const name of removed) {
+        for (const variant of [name, `${SKILL_PREFIX}${name}`]) {
+            const dir = join(dstDir, variant);
+            if (existsSync(dir)) {
+                rmSync(dir, { recursive: true, force: true });
+                deleted++;
+            }
+        }
+    }
+    return deleted;
+}
 /**
  * Copy bundled slash command templates (`.md` files in the package's
  * `commands/` directory) to `~/.claude/commands/`, unconditionally
@@ -275,10 +418,18 @@ export function installSkills(home = homedir()) {
     if (!existsSync(targetDir)) {
         mkdirSync(targetDir, { recursive: true });
     }
+    // Read previous manifest before copying fresh skills (same rationale as
+    // the Claude Code path — diff the old state against current source so
+    // cut/renamed skills get cleaned up instead of lingering forever).
+    const oldManifest = readPharaohManifest(targetDir);
     // Prefix skills for collision safety (same rationale as Claude Code path).
     const count = installPrefixedSkills(BUNDLED_SKILLS_DIR, targetDir, SKILL_PREFIX);
-    // Also clean up any bare-name leftovers from prior installs.
+    // Legacy dual-layout cleanup for bare-name stragglers of current skills.
     cleanupBareNameSkills(BUNDLED_SKILLS_DIR, targetDir);
+    // Manifest-based cut cleanup for skills removed between versions.
+    cleanupRemovedSkills(BUNDLED_SKILLS_DIR, targetDir, oldManifest);
+    // Stamp a fresh manifest reflecting current source.
+    writePharaohManifest(targetDir, getSourceSkillNames(BUNDLED_SKILLS_DIR));
     return count;
 }
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for AI agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
   "type": "module",
   "main": "dist/index.js",