claude-slim 2.7.1 → 2.7.2

package/README.md

@@ -211,6 +211,20 @@ From a real cleanup session:
 
 ---
 
+## v2.7.1 — What's new
+
+Correctness patch cleaning up seven bugs found in post-2.7 review. No new features; no breaking changes.
+
+- **`unused_plugin` savings always showed 0.** The detector emitted `tokens: 0` for every flagged plugin, so both the dry-run summary and the final report box under-counted savings for what is typically the largest cleanup target. Cost is now threaded through `DetectorContext` and the detector uses the real per-plugin value.
+- **`duplicate` detector could disable namespaced local skills.** A `baseName` fallback flagged `org/ship` as a duplicate of a bare plugin `ship`, even though namespaced local skills are addressable independently. Only exact-name matches are flagged now.
+- **`stale_project` restore was scoped to all of `~/.claude/`.** A tampered manifest could redirect a project-memory backup into `~/.claude/skills/` and clobber an unrelated asset. Restores are now type-scoped — `stale_project` targets must live under `~/.claude/projects/`, skill restores under `~/.claude/skills/`.
+- **Non-interactive `claude-slim clean` refuses to auto-apply.** Prior behavior silently auto-selected Tier 1 in non-TTY without `--auto`/`--dry-run`, surprising users running from scripts. It now prints a warning and exits with status 1; opt in explicitly with `--auto` or `--dry-run`.
+- **`--lookback-days 0` / `--sessions-per-day 0` are respected.** `parseInt(x, 10) || N` was silently upgrading explicit `0` to the default. Replaced with a `parseNonNegativeInt` helper.
+- **`claude-slim report` recognizes zero-token cleanups.** Runs that only removed `broken_symlink` or `temp_cache` entries were being reported as "no previous cleanup"; every manifest entry now counts.
+- **Session parser regex hardened.** `extractCommandsFromTranscript` uses `String.matchAll` instead of a manual `lastIndex`-resetting loop — one fewer footgun for future refactors.
+
+Tests: 188 → 190 (+2 regression cases for the token-propagation fix).
+
 ## v2.7 — What's new
 
 - **Unused-plugin detection** — claude-slim now reads your session transcripts for MCP tool calls (`mcp__plugin_<plugin>_<server>__*`) and slash commands, and flags plugins whose surfaces you've never touched in the last 60 days. Tier 3 (Optional, never auto-selected). When you choose to clean one, `claude plugin disable <name>` runs automatically; `/claude-slim restore` re-enables it.

package/dist/cleaner.d.ts

@@ -6,6 +6,12 @@ export interface CleanResult {
         name: string;
         error: string;
     }>;
+    /**
+     * Populated when one or more `unused_plugin` items were requested but the
+     * `claude` CLI is missing from PATH. The CLI surfaces this once at the top of
+     * the error block instead of N repeat rows.
+     */
+    claudeCliMissing?: boolean;
 }
 export declare function cleanIssues(issues: Issue[]): Promise<CleanResult>;
 export declare function restoreItem(entry: ManifestEntry | DisabledPluginEntry): Promise<void>;

package/dist/cleaner.js

@@ -2,7 +2,7 @@ import { rename, readdir, rmdir, rm, unlink, lstat, mkdir } from 'node:fs/promis
 import { join, dirname, resolve, sep } from 'node:path';
 import { appendManifest, ensureDisabledDir, getDisabledDir, removeEntry, recordDisabledPlugin, removeDisabledPlugin } from './manifest.js';
 import { assertInsideClaudeDir, getSkillsDir, getProjectsDir } from './paths.js';
-import { disablePlugin, enablePlugin } from './plugin-runtime.js';
+import { disablePlugin, enablePlugin, isClaudeCliAvailable, ClaudeCliMissingError } from './plugin-runtime.js';
 // Restrict a restore target to a specific subtree of ~/.claude/. Complements
 // assertInsideClaudeDir: a tampered manifest could still name a legal
 // ~/.claude/ path that belongs to a different type of asset (e.g. redirect a
@@ -45,6 +45,14 @@ export async function cleanIssues(issues) {
     const moved = [];
     const skipped = [];
     const errors = [];
+    // Pre-check: if any unused_plugin items are selected, verify `claude` CLI is
+    // reachable before we start. Failing fast with a single friendly message
+    // beats N raw ENOENTs mid-run. Skip the probe if no plugin items were picked.
+    const wantsPluginOps = issues.some((i) => i.type === 'unused_plugin');
+    let claudeCliMissing = false;
+    if (wantsPluginOps && !(await isClaudeCliAvailable())) {
+        claudeCliMissing = true;
+    }
     for (const issue of issues) {
         try {
             // unused_plugin and report-only types don't touch filesystem paths directly
@@ -132,6 +140,12 @@ export async function cleanIssues(issues) {
                 moved.push(entry);
             }
             else if (issue.type === 'unused_plugin') {
+                // Pre-check flagged `claude` missing — skip silently; the CLI prints
+                // one grouped message after cleanIssues returns.
+                if (claudeCliMissing) {
+                    skipped.push(issue.name);
+                    continue;
+                }
                 await disablePlugin(issue.name);
                 // Record in manifest; if that fails, roll back the disable
                 try {
@@ -150,13 +164,21 @@ export async function cleanIssues(issues) {
             }
         }
         catch (err) {
+            // Race window: `claude` was on PATH at pre-check but gone by the time we
+            // shelled out. Convert to the same grouped skip path instead of a raw
+            // ENOENT row.
+            if (err instanceof ClaudeCliMissingError) {
+                claudeCliMissing = true;
+                skipped.push(issue.name);
+                continue;
+            }
             const message = err instanceof Error ? err.message : String(err);
             errors.push({ name: issue.name, error: message });
         }
     }
     // Clean empty directories in skills/
     await cleanEmptyDirs(getSkillsDir());
-    return { moved, skipped, errors };
+    return { moved, skipped, errors, claudeCliMissing };
 }
 async function cleanEmptyDirs(dir) {
     try {

package/dist/cli.js

@@ -275,6 +275,12 @@ async function runCleanPipeline(opts) {
     console.log('');
     console.log(formatReportBox(reportData));
     console.log('');
+    if (cleanResult.claudeCliMissing) {
+        const skippedPluginCount = selectedIssues.filter((i) => i.type === 'unused_plugin').length;
+        console.log(`  \x1b[33m⚠ \`claude\` CLI not found on PATH — skipped ${skippedPluginCount} plugin(s).\x1b[0m`);
+        console.log('    Install Claude Code and re-run to disable unused plugins,');
+        console.log('    or disable them manually via `claude plugin disable <name>`.\n');
+    }
     if (cleanResult.errors.length > 0) {
         console.log('  \x1b[31mErrors:\x1b[0m');
         for (const err of cleanResult.errors) {

package/dist/plugin-runtime.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Sentinel error class raised when the `claude` CLI is not on PATH.
+ * Callers (cleaner.ts) treat this as a "skip, don't error" condition so users
+ * running claude-slim outside a Claude Code install don't see a raw ENOENT
+ * mid-cleanup.
+ */
+export declare class ClaudeCliMissingError extends Error {
+    constructor();
+}
+/**
+ * Best-effort probe: is `claude` on PATH and answering `--version`?
+ * Never throws — a false result short-circuits `unused_plugin` cleanup with a
+ * friendly message rather than surfacing spawn ENOENT to end users.
+ */
+export declare function isClaudeCliAvailable(): Promise<boolean>;
 /** Validates plugin name then shells out to `claude plugin disable <name>`. */
 export declare function disablePlugin(name: string): Promise<void>;
 /** Validates plugin name then shells out to `claude plugin enable <name>`. */

package/dist/plugin-runtime.js

@@ -1,14 +1,43 @@
 import { execFile } from 'node:child_process';
 const PLUGIN_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Sentinel error class raised when the `claude` CLI is not on PATH.
+ * Callers (cleaner.ts) treat this as a "skip, don't error" condition so users
+ * running claude-slim outside a Claude Code install don't see a raw ENOENT
+ * mid-cleanup.
+ */
+export class ClaudeCliMissingError extends Error {
+    constructor() {
+        super("`claude` CLI not found on PATH. Install Claude Code (https://claude.com/product/claude-code) " +
+            'to enable/disable plugins, or run `claude-slim clean` without the unused-plugin items selected.');
+        this.name = 'ClaudeCliMissingError';
+    }
+}
 function validateName(name) {
     if (!PLUGIN_NAME_RE.test(name)) {
         throw new Error(`Refusing to operate on suspicious plugin name: ${name}`);
     }
 }
+/**
+ * Detects the classic "binary missing from PATH" shape of Node's execFile error.
+ * spawn ENOENT surfaces as an Error with { code: 'ENOENT', syscall: 'spawn claude' }.
+ * The exact-match on `spawn claude` avoids false positives for hypothetical
+ * sibling binaries (e.g. `claude-code`) that might be spawned by future code.
+ */
+function isClaudeMissing(err) {
+    if (!(err instanceof Error))
+        return false;
+    const e = err;
+    return e.code === 'ENOENT' && e.syscall === 'spawn claude';
+}
 function runPluginCommand(subcommand, name) {
     return new Promise((resolve, reject) => {
         execFile('claude', ['plugin', subcommand, name], { timeout: 30000 }, (err, _stdout, stderr) => {
             if (err) {
+                if (isClaudeMissing(err)) {
+                    reject(new ClaudeCliMissingError());
+                    return;
+                }
                 const detail = stderr?.trim() ? `: ${stderr.trim()}` : '';
                 reject(new Error(`${err.message}${detail}`));
                 return;
@@ -21,6 +50,18 @@ function runPluginCommand(subcommand, name) {
         });
     });
 }
+/**
+ * Best-effort probe: is `claude` on PATH and answering `--version`?
+ * Never throws — a false result short-circuits `unused_plugin` cleanup with a
+ * friendly message rather than surfacing spawn ENOENT to end users.
+ */
+export function isClaudeCliAvailable() {
+    return new Promise((resolve) => {
+        execFile('claude', ['--version'], { timeout: 5000 }, (err) => {
+            resolve(!err);
+        });
+    });
+}
 /** Validates plugin name then shells out to `claude plugin disable <name>`. */
 export async function disablePlugin(name) {
     validateName(name);

package/dist/scanner/index.js

@@ -1,3 +1,8 @@
+// INVARIANT: nothing in the scanner (this file or anything under scanner/**)
+// may write to stdout. The CLI pipes stdout of `scan --json` to jq/other
+// tools; a stray console.log would silently corrupt machine-readable output.
+// Route diagnostics through console.error. Enforced by
+// src/__tests__/scan-stdout-invariant.test.ts.
 import { join } from 'node:path';
 import { countTokensCached } from '../tokenizer.js';
 import { getClaudeDir } from '../paths.js';

package/dist/scanner/local-skills.js

@@ -20,24 +20,30 @@ export function dedupeBySymlink(candidates) {
     }
     return Array.from(seen.values());
 }
+// Max depth for the nested-skill walk. Depth 1 = ~/.claude/skills/<a>/SKILL.md,
+// depth 2 = ~/.claude/skills/<a>/<b>/SKILL.md, etc. Depth 3 covers the deepest
+// layouts seen in the wild (e.g. plugin-namespaced groups like
+// skills/<org>/<group>/<skill>/SKILL.md) while keeping the walk finite.
+// If a directory contains a SKILL.md we stop descending — nested SKILL.md
+// files under an already-declared skill would just create phantom duplicates.
+const MAX_SKILL_DEPTH = 3;
 export async function scanLocalSkills() {
     const skillsDir = getSkillsDir();
     const candidates = [];
     const brokenSymlinks = [];
     const contents = new Map();
-    const entries = await safeReaddir(skillsDir);
-    const scanPromises = entries.map(async (entry) => {
-        const dirPath = join(skillsDir, entry);
-        if (!(await isDirectory(dirPath)))
+    async function visit(dirPath, nameParts, depth) {
+        if (depth > MAX_SKILL_DEPTH)
             return;
         const skillMd = join(dirPath, 'SKILL.md');
+        const displayName = nameParts.join('/');
         if (await isBrokenSymlink(skillMd)) {
             let target = 'unknown';
             try {
                 target = await readlink(skillMd);
             }
             catch { /* */ }
-            brokenSymlinks.push({ name: entry, path: skillMd, target });
+            brokenSymlinks.push({ name: displayName, path: skillMd, target });
             return;
         }
         const content = await safeReadFile(skillMd);
@@ -47,7 +53,7 @@ export async function scanLocalSkills() {
             const realMdPath = await resolveRealPath(skillMd);
             candidates.push({
                 skill: {
-                    name: entry,
+                    name: displayName,
                     path: dirPath,
                     sizeBytes: Buffer.byteLength(content),
                     tokens,
@@ -55,43 +61,31 @@ export async function scanLocalSkills() {
                 },
                 realMdPath,
             });
+            // Stop descending: nested SKILL.md files under a declared skill are
+            // documentation/examples, not addressable skills.
+            return;
         }
-        // Nested skills (e.g., @internal-sys/commit-guide)
+        if (depth === MAX_SKILL_DEPTH)
+            return;
         const subEntries = await safeReaddir(dirPath);
-        for (const sub of subEntries) {
+        await Promise.all(subEntries.map(async (sub) => {
             const subDir = join(dirPath, sub);
+            // isDirectory() uses stat(), which follows symlinks — intentional so
+            // users can symlink shared skills into ~/.claude/skills/. A cycle
+            // through symlinks would be bounded by MAX_SKILL_DEPTH, not by us
+            // detecting the loop directly.
             if (!(await isDirectory(subDir)))
-                continue;
-            const subSkillMd = join(subDir, 'SKILL.md');
-            if (await isBrokenSymlink(subSkillMd)) {
-                let target = 'unknown';
-                try {
-                    target = await readlink(subSkillMd);
-                }
-                catch { /* */ }
-                brokenSymlinks.push({ name: `${entry}/${sub}`, path: subSkillMd, target });
-                continue;
-            }
-            const subContent = await safeReadFile(subSkillMd);
-            if (subContent !== null) {
-                const name = `${entry}/${sub}`;
-                contents.set(subSkillMd, subContent);
-                const tokens = countTokensCached(subContent, subSkillMd);
-                const realMdPath = await resolveRealPath(subSkillMd);
-                candidates.push({
-                    skill: {
-                        name,
-                        path: subDir,
-                        sizeBytes: Buffer.byteLength(subContent),
-                        tokens,
-                        source: 'local',
-                    },
-                    realMdPath,
-                });
-            }
-        }
-    });
-    await Promise.all(scanPromises);
+                return;
+            await visit(subDir, [...nameParts, sub], depth + 1);
+        }));
+    }
+    const topEntries = await safeReaddir(skillsDir);
+    await Promise.all(topEntries.map(async (entry) => {
+        const dirPath = join(skillsDir, entry);
+        if (!(await isDirectory(dirPath)))
+            return;
+        await visit(dirPath, [entry], 1);
+    }));
     const skills = dedupeBySymlink(candidates);
     return { skills, brokenSymlinks, contents };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-slim",
-  "version": "2.7.1",
-  "description": "Analyze and reduce Claude Code token overhead",
+  "version": "2.7.2",
+  "description": "Cut Claude Code startup token overhead — non-destructive scan, tiered proposals, one-command restore. Finds unused skills, duplicate registrations, stale memory, and heavyweight plugins in ~/.claude/.",
   "type": "module",
   "bin": {
     "claude-slim": "./dist/cli.js"
@@ -23,11 +23,19 @@
   "keywords": [
     "claude",
     "claude-code",
+    "anthropic",
     "token",
-    "optimization",
+    "token-optimization",
+    "context-bloat",
+    "prompt-optimization",
+    "system-prompt",
     "cleanup",
     "skills",
-    "plugin"
+    "skill-management",
+    "plugin",
+    "plugin-cleanup",
+    "cli",
+    "developer-experience"
   ],
   "author": "iops-leo",
   "license": "MIT",