claude-slim 2.2.3 → 2.4.0

package/README.md

@@ -2,9 +2,13 @@
 
 # claude-slim
 
+[![npm](https://img.shields.io/npm/v/claude-slim.svg)](https://www.npmjs.com/package/claude-slim)
+[![CI](https://github.com/iops-leo/claude-slim/actions/workflows/ci.yml/badge.svg)](https://github.com/iops-leo/claude-slim/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/claude-slim.svg)](./LICENSE)
+
 **You're burning thousands of tokens before you even say "hello."**
 
-Every session loads *every* skill, memory file, and plugin instruction into the system prompt — even the ones you never use. claude-slim finds and removes that waste.
+Every Claude Code session auto-loads every skill, memory file, and plugin instruction into the system prompt — even the ones you never use. If you run OMC, marketplace plugins, or a custom skill stack, you're paying for context you'll never touch. claude-slim finds and removes that waste.
 
 ```
 /claude-slim
@@ -69,6 +73,7 @@ That's slower responses. Hitting your usage cap faster. Paying for context you'r
 | Duplicates | Same skill registered from multiple sources |
 | Empty templates | Placeholder skills with no content |
 | Oversized files | SKILL.md over 10KB |
+| **Unused skills** | **Local skills never invoked in your last N days of sessions (default 60d)** |
 | Stale memory | Large memory files loaded every session |
 | Disabled plugins | Installed but disabled plugins still in cache |
 | Stale projects | Project memory untouched for 90+ days |
@@ -115,41 +120,45 @@ That's slower responses. Hitting your usage cap faster. Paying for context you'r
 
 ---
 
-## Install (10 seconds)
+## Try it (10 seconds)
+
+No install needed — run once and see what's in your `~/.claude/`:
 
 ```bash
-claude plugin marketplace add iops-leo/claude-slim
-claude plugin install claude-slim
+npx claude-slim scan
 ```
 
-Then just type `/claude-slim` in any session.
-
-Or use the standalone CLI:
+Happy with what you see? Make it part of your Claude Code workflow:
 
 ```bash
-npx claude-slim scan
+claude plugin marketplace add iops-leo/claude-slim
+claude plugin install claude-slim
 ```
 
+Then just type `/claude-slim` in any session.
+
 ---
 
 ## Usage
 
 ```bash
-/claude-slim              # Full pipeline: scan → propose → clean → report
-/claude-slim scan         # Report only, no changes
-/claude-slim scan --json  # Machine-readable JSON output
-/claude-slim restore      # Bring back anything you disabled
+/claude-slim                          # Full pipeline: scan → propose → clean → report
+/claude-slim scan                     # Report only, no changes
+/claude-slim scan --json              # Machine-readable JSON output
+/claude-slim scan --lookback-days 30  # Treat skills idle for 30+ days as unused
+/claude-slim restore                  # Bring back anything you disabled
 ```
 
 CLI equivalents:
 
 ```bash
-npx claude-slim clean             # Full pipeline
-npx claude-slim clean --dry-run   # See what would happen (no changes)
-npx claude-slim clean --auto      # Non-interactive, Tier 1 only (CI/scripts)
-npx claude-slim scan              # Report only
-npx claude-slim restore           # Undo
-npx claude-slim report            # Show savings from last clean
+npx claude-slim clean                    # Full pipeline
+npx claude-slim clean --dry-run          # See what would happen (no changes)
+npx claude-slim clean --auto             # Non-interactive, Tier 1 only (CI/scripts)
+npx claude-slim clean --lookback-days N  # Tune the unused-skill detection window
+npx claude-slim scan                     # Report only
+npx claude-slim restore                  # Undo
+npx claude-slim report                   # Show savings from last clean
 ```
 
 ---
@@ -162,6 +171,17 @@ npx claude-slim report            # Show savings from last clean
 | **Reversible** | `/claude-slim restore` brings anything back, any time |
 | **User-controlled** | Always asks before making changes. `--dry-run` to preview. |
 | **Hands off** | Never touches CLAUDE.md, settings.json, or plugin configs |
+| **Scoped** | All operations are refused if the target path escapes `~/.claude/` |
+
+### What claude-slim never touches
+
+- **`~/.claude/CLAUDE.md`** — your system instructions, read-only.
+- **`~/.claude/settings.json`** — MCP server config, hooks, and any other settings. Read-only.
+- **Plugin internals** (`~/.claude/plugins/config.json`, individual `plugin.json` files) — left alone; use `claude plugin` to manage plugins.
+- **Git / project sources** — claude-slim only looks inside `~/.claude/`, never at your code.
+- **Anything outside `~/.claude/`** — a path-containment guard refuses destructive ops anywhere else, even if a tampered manifest asked it to.
+
+Only touched: entries under `~/.claude/skills/`, `~/.claude/plugins/cache/temp_local_*`, and `~/.claude/projects/*/memory/` — and even those are moved to `skills.disabled/`, not deleted (except `temp_local_*` failed-install caches, which are removed outright).
 
 ---
 
@@ -195,6 +215,20 @@ From a real cleanup session:
 
 ---
 
+## v2.4 — What's new
+
+- **Unused-skill detection** — claude-slim now reads your `~/.claude/projects/*/*.jsonl` session transcripts, finds every `Skill` tool invocation in the last 60 days, and flags local skills you've installed but never actually used. Tier 3 (Optional, never auto-selected) so you decide. Configurable lookback via `--lookback-days <n>`. Falls back silently if there's not enough session history (≥3 sessions required) — no false-flagging when the data source is unreliable.
+- **Plugin skills are intentionally out of scope** for this detector. They live inside `~/.claude/plugins/cache/` and are managed by the Claude Code plugin runtime; moving them would partially uninstall the plugin. Use `claude plugin disable <name>` for plugin-level cleanup.
+- **Per-file session-usage cache** at `~/.claude/.skill-usage-cache.json` keyed by mtime. Warm rescans only re-parse session logs that have changed.
+- **Node 20+** is now the engine floor (previously `>=18`, but Node 18 was already dropped from CI in v2.3.0).
+
+## v2.3 — What's new
+
+- **Detector registry refactor (v2.3.0)** — Scanner split from a 588-line module into focused detectors under `src/scanner/`. Adding a new heuristic is a one-function addition; see CONTRIBUTING.md. Public API unchanged.
+- **Path-containment guard (v2.2.3)** — Every destructive op refuses any target path that escapes `~/.claude/`. `runCommand` no longer goes through a shell. `temp_cache` cleanup is symlink-safe.
+- **Report sign fix (v2.2.3)** — The breakdown table's Saved column was inverted in earlier 2.2.x; cleanup now shows correct savings per row.
+- **85 tests (was 73)** — New round-trip coverage for path containment, restore guards, breakdown sign, restore-selection dedup, atomic tokenizer flush, and custom detector injection.
+
 ## v2.2 — What's new
 
 - **Atomic `stale_project` clean/restore** — Single directory `rename()` instead of per-file loop. No more partial-failure state if the operation is interrupted.
@@ -225,7 +259,7 @@ From a real cleanup session:
 
 ## Requirements
 
-- Node.js 18+
+- Node.js 20+
 - macOS or Linux
 - Claude Code CLI
 

package/dist/cleaner.js

@@ -51,7 +51,8 @@ export async function cleanIssues(issues) {
             else if (issue.type === 'template' ||
                 issue.type === 'duplicate' ||
                 issue.type === 'skill_dup' ||
-                issue.type === 'oversized_skill') {
+                issue.type === 'oversized_skill' ||
+                issue.type === 'unused_skill') {
                 // Move skill directory to disabled — use name (not basename) to avoid namespace collisions
                 const safeName = issue.name.replace(/\//g, '--');
                 const dest = join(disabledDir, safeName);

package/dist/cli.js

@@ -22,9 +22,10 @@ program
     .command('scan')
     .description('Scan environment and report issues')
     .option('--json', 'Output raw JSON')
+    .option('--lookback-days <n>', 'Days of session history for skill-usage analysis', '60')
     .action(async (opts) => {
     await initTokenizer();
-    const result = await scan();
+    const result = await scan({ lookbackDays: parseInt(opts.lookbackDays, 10) || 60 });
     await flushCache();
     if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
@@ -40,11 +41,13 @@ program
     .option('--dry-run', 'Show what would happen without making changes')
     .option('--auto', 'Non-interactive: auto-select Tier 1 items only')
     .option('--sessions-per-day <n>', 'Sessions per day for savings estimate', '2')
+    .option('--lookback-days <n>', 'Days of session history for skill-usage analysis', '60')
     .action(async (opts) => {
     await runCleanPipeline({
         dryRun: !!opts.dryRun,
         auto: !!opts.auto,
         sessionsPerDay: parseInt(opts.sessionsPerDay, 10) || 2,
+        lookbackDays: parseInt(opts.lookbackDays, 10) || 60,
     });
 });
 // --- restore ---
@@ -110,9 +113,10 @@ program
     .command('report')
     .description('Show savings report from last clean')
     .option('--sessions-per-day <n>', 'Sessions per day for savings estimate', '2')
+    .option('--lookback-days <n>', 'Days of session history for skill-usage analysis', '60')
     .action(async (opts) => {
     await initTokenizer();
-    const result = await scan();
+    const result = await scan({ lookbackDays: parseInt(opts.lookbackDays, 10) || 60 });
     const entries = await readManifest();
     const movedEntries = entries.filter((e) => e.tokenCount && e.tokenCount > 0);
     if (movedEntries.length === 0) {
@@ -125,7 +129,9 @@ program
     // Only skill-type entries contributed to the per-skill prompt overhead
     // (stale_project restores memory tokens separately; broken_symlink/
     // temp_cache never counted toward totalTokensBefore).
-    const SKILL_TYPES = new Set(['template', 'duplicate', 'skill_dup', 'oversized_skill']);
+    const SKILL_TYPES = new Set([
+        'template', 'duplicate', 'skill_dup', 'oversized_skill', 'unused_skill',
+    ]);
     const removedSkillEntries = movedEntries.filter((e) => SKILL_TYPES.has(e.type));
     const removedMemoryTokens = movedEntries
         .filter((e) => e.type === 'stale_project')
@@ -155,12 +161,12 @@ program
 });
 // --- default (no subcommand) → run clean ---
 program.action(async () => {
-    await runCleanPipeline({ dryRun: false, auto: false, sessionsPerDay: 2 });
+    await runCleanPipeline({ dryRun: false, auto: false, sessionsPerDay: 2, lookbackDays: 60 });
 });
 // --- shared clean pipeline ---
 async function runCleanPipeline(opts) {
     await initTokenizer();
-    const result = await scan();
+    const result = await scan({ lookbackDays: opts.lookbackDays });
     if (result.issues.length === 0) {
         console.log('\n  \x1b[32mAlready slim!\x1b[0m No issues found.\n');
         await flushCache();
@@ -207,7 +213,7 @@ async function runCleanPipeline(opts) {
     console.log('');
     const cleanResult = await cleanIssues(selectedIssues);
     // Re-scan after cleanup for accurate breakdown
-    const afterResult = await scan();
+    const afterResult = await scan({ lookbackDays: opts.lookbackDays });
     const reportData = calculateReport(result, afterResult, cleanResult.moved, opts.sessionsPerDay);
     console.log('');
     console.log(formatReportBox(reportData));

package/dist/scanner/claude-md.d.ts

@@ -0,0 +1,5 @@
+export declare function parseClaudeMdSections(content: string): Array<{
+    name: string;
+    sizeBytes: number;
+    tokens: number;
+}>;

package/dist/scanner/claude-md.js

@@ -0,0 +1,45 @@
+import { countTokensCached } from '../tokenizer.js';
+export function parseClaudeMdSections(content) {
+    const sections = [];
+    const lines = content.split('\n');
+    let currentName = null;
+    let currentContent = '';
+    for (const line of lines) {
+        if (line.startsWith('# ')) {
+            if (currentName !== null) {
+                sections.push({
+                    name: currentName,
+                    sizeBytes: Buffer.byteLength(currentContent),
+                    tokens: countTokensCached(currentContent, `claude-md-section:${currentName}`),
+                });
+            }
+            else if (currentContent.trim()) {
+                sections.push({
+                    name: '(preamble)',
+                    sizeBytes: Buffer.byteLength(currentContent),
+                    tokens: countTokensCached(currentContent, 'claude-md-section:preamble'),
+                });
+            }
+            currentName = line.slice(2).trim().slice(0, 60);
+            currentContent = line + '\n';
+        }
+        else {
+            currentContent += line + '\n';
+        }
+    }
+    if (currentName !== null) {
+        sections.push({
+            name: currentName,
+            sizeBytes: Buffer.byteLength(currentContent),
+            tokens: countTokensCached(currentContent, `claude-md-section:${currentName}`),
+        });
+    }
+    else if (currentContent.trim()) {
+        sections.push({
+            name: '(preamble)',
+            sizeBytes: Buffer.byteLength(currentContent),
+            tokens: countTokensCached(currentContent, 'claude-md-section:preamble'),
+        });
+    }
+    return sections;
+}

package/dist/scanner/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const STALE_DAYS = 90;
+export declare const OVERSIZED_SKILL_BYTES = 10240;
+export declare const OVERSIZED_MEMORY_BYTES = 5120;
+export declare const SKILL_PROMPT_OVERHEAD_TOKENS = 30;

package/dist/scanner/constants.js

@@ -0,0 +1,4 @@
+export const STALE_DAYS = 90;
+export const OVERSIZED_SKILL_BYTES = 10240;
+export const OVERSIZED_MEMORY_BYTES = 5120;
+export const SKILL_PROMPT_OVERHEAD_TOKENS = 30;

package/dist/scanner/detectors.d.ts

@@ -0,0 +1,23 @@
+import type { SkillInfo, BrokenSymlink, MemoryFile, PluginInfo, Issue } from '../types.js';
+import type { TempCache } from './plugin-skills.js';
+import type { StaleProject } from './memory.js';
+export interface DetectorContext {
+    localSkills: SkillInfo[];
+    pluginSkills: SkillInfo[];
+    brokenSymlinks: BrokenSymlink[];
+    memoryFiles: MemoryFile[];
+    tempCaches: TempCache[];
+    staleProjects: StaleProject[];
+    disabledPlugins: Set<string>;
+    plugins: PluginInfo[];
+    contents: Map<string, string>;
+    recentSkillInvocations: Set<string>;
+    sessionDataAvailable: boolean;
+    lookbackDays: number;
+}
+export interface Detector {
+    name: string;
+    detect(ctx: DetectorContext): Issue[];
+}
+export declare const detectors: Detector[];
+export declare function classifyIssues(ctx: DetectorContext, registry?: Detector[]): Issue[];

package/dist/scanner/detectors.js

@@ -0,0 +1,215 @@
+import { join } from 'node:path';
+import { getPluginsDir } from '../paths.js';
+import { OVERSIZED_SKILL_BYTES, OVERSIZED_MEMORY_BYTES, SKILL_PROMPT_OVERHEAD_TOKENS, } from './constants.js';
+const brokenSymlinkDetector = {
+    name: 'broken_symlink',
+    detect({ brokenSymlinks }) {
+        return brokenSymlinks.map((link) => ({
+            type: 'broken_symlink',
+            tier: 1,
+            name: link.name,
+            detail: link.target,
+            tokens: 0,
+            path: link.path,
+        }));
+    },
+};
+const templateDetector = {
+    name: 'template',
+    detect({ localSkills, contents }) {
+        const issues = [];
+        for (const skill of localSkills) {
+            const skillMdPath = join(skill.path, 'SKILL.md');
+            const content = contents.get(skillMdPath);
+            if (content && content.includes('Replace with description')) {
+                issues.push({
+                    type: 'template',
+                    tier: 1,
+                    name: skill.name,
+                    tokens: skill.tokens,
+                    path: skill.path,
+                });
+            }
+        }
+        return issues;
+    },
+};
+const duplicateDetector = {
+    name: 'duplicate',
+    detect({ localSkills, pluginSkills }) {
+        const pluginSkillNames = new Set(pluginSkills.map((s) => s.name));
+        const issues = [];
+        for (const skill of localSkills) {
+            // Check base name for nested skills (e.g. "org/ship" → "ship")
+            const baseName = skill.name.includes('/') ? skill.name.split('/').pop() : skill.name;
+            if (pluginSkillNames.has(baseName)) {
+                issues.push({
+                    type: 'duplicate',
+                    tier: 2,
+                    name: skill.name,
+                    detail: 'local+plugin',
+                    tokens: skill.tokens,
+                    path: skill.path,
+                });
+            }
+        }
+        return issues;
+    },
+};
+const oversizedSkillDetector = {
+    name: 'oversized_skill',
+    detect({ localSkills }) {
+        const issues = [];
+        for (const skill of localSkills) {
+            if (skill.sizeBytes > OVERSIZED_SKILL_BYTES) {
+                issues.push({
+                    type: 'oversized_skill',
+                    tier: 3,
+                    name: skill.name,
+                    detail: `${Math.round(skill.sizeBytes / 1024)}KB`,
+                    tokens: skill.tokens,
+                    path: skill.path,
+                });
+            }
+        }
+        return issues;
+    },
+};
+const skillDupDetector = {
+    name: 'skill_dup',
+    detect({ localSkills }) {
+        const issues = [];
+        for (const skill of localSkills) {
+            const dotSkillDir = skill.path + '.skill';
+            if (localSkills.some((s) => s.path === dotSkillDir)) {
+                issues.push({
+                    type: 'skill_dup',
+                    tier: 1,
+                    name: skill.name,
+                    tokens: 0,
+                    path: dotSkillDir,
+                });
+            }
+        }
+        return issues;
+    },
+};
+const tempCacheDetector = {
+    name: 'temp_cache',
+    detect({ tempCaches }) {
+        return tempCaches.map((temp) => ({
+            type: 'temp_cache',
+            tier: 1,
+            name: temp.name,
+            detail: `${temp.sizeKB}KB`,
+            tokens: 0,
+            path: temp.path,
+        }));
+    },
+};
+const oversizedMemoryDetector = {
+    name: 'oversized_memory',
+    detect({ memoryFiles }) {
+        const issues = [];
+        for (const mem of memoryFiles) {
+            if (mem.sizeBytes > OVERSIZED_MEMORY_BYTES) {
+                issues.push({
+                    type: 'oversized_memory',
+                    tier: 2,
+                    name: `${mem.project}/${mem.name}`,
+                    detail: `${Math.round(mem.sizeBytes / 1024)}KB`,
+                    tokens: mem.tokens,
+                    path: mem.path,
+                });
+            }
+        }
+        return issues;
+    },
+};
+const staleProjectDetector = {
+    name: 'stale_project',
+    detect({ staleProjects, memoryFiles }) {
+        return staleProjects.map((stale) => {
+            const memTokens = memoryFiles
+                .filter((m) => m.project === stale.project)
+                .reduce((sum, m) => sum + m.tokens, 0);
+            return {
+                type: 'stale_project',
+                tier: 2,
+                name: stale.project,
+                detail: `${stale.ageDays}d, ${stale.fileCount} files, ${Math.round(stale.totalBytes / 1024)}KB`,
+                tokens: memTokens,
+                path: stale.path,
+            };
+        });
+    },
+};
+const unusedSkillDetector = {
+    name: 'unused_skill',
+    detect({ localSkills, recentSkillInvocations, sessionDataAvailable, lookbackDays, }) {
+        // Suppress entirely when the data source is unreliable — better no signal
+        // than a wrong one that flags every skill as unused.
+        if (!sessionDataAvailable)
+            return [];
+        const issues = [];
+        for (const skill of localSkills) {
+            // Direct hit: invocation set contains the skill name as-is.
+            if (recentSkillInvocations.has(skill.name))
+                continue;
+            // Nested skill (e.g. "org/ship"): also check the bare leaf name, which
+            // is how it would appear in a Skill tool_use input.
+            if (skill.name.includes('/')) {
+                const leaf = skill.name.split('/').pop();
+                if (recentSkillInvocations.has(leaf))
+                    continue;
+            }
+            issues.push({
+                type: 'unused_skill',
+                tier: 3,
+                name: skill.name,
+                detail: `not invoked in ${lookbackDays}d`,
+                tokens: skill.tokens,
+                path: skill.path,
+            });
+        }
+        return issues;
+    },
+};
+const disabledPluginDetector = {
+    name: 'disabled_plugin',
+    detect({ plugins, disabledPlugins }) {
+        const issues = [];
+        for (const plugin of plugins) {
+            if (disabledPlugins.has(plugin.name)) {
+                issues.push({
+                    type: 'disabled_plugin',
+                    tier: 2,
+                    name: plugin.name,
+                    detail: `${plugin.skillCount} skills`,
+                    tokens: plugin.skillCount * SKILL_PROMPT_OVERHEAD_TOKENS,
+                    path: join(getPluginsDir(), plugin.name),
+                });
+            }
+        }
+        return issues;
+    },
+};
+// The full registry. Order only matters for ties in the tier sort.
+// New detectors: define above, add here, update CONTRIBUTING.md's issue-type table.
+export const detectors = [
+    brokenSymlinkDetector,
+    templateDetector,
+    duplicateDetector,
+    oversizedSkillDetector,
+    skillDupDetector,
+    tempCacheDetector,
+    oversizedMemoryDetector,
+    staleProjectDetector,
+    unusedSkillDetector,
+    disabledPluginDetector,
+];
+export function classifyIssues(ctx, registry = detectors) {
+    const issues = registry.flatMap((d) => d.detect(ctx));
+    issues.sort((a, b) => a.tier - b.tier);
+    return issues;
+}

package/dist/scanner/disabled-plugins.d.ts

@@ -0,0 +1,2 @@
+export declare function parseDisabledPlugins(output: string): Set<string>;
+export declare function getDisabledPlugins(): Promise<Set<string>>;

package/dist/scanner/disabled-plugins.js

@@ -0,0 +1,26 @@
+import { runCommand } from './fs-walk.js';
+export function parseDisabledPlugins(output) {
+    const disabled = new Set();
+    if (!output)
+        return disabled;
+    let currentName = null;
+    for (const line of output.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('❯')) {
+            const full = trimmed.split('❯')[1]?.trim() || '';
+            // Format: sub-plugin@marketplace — extract marketplace name for cache dir matching
+            currentName = full.includes('@') ? full.split('@')[1] : full;
+        }
+        else if (trimmed.toLowerCase().includes('disabled') && currentName) {
+            disabled.add(currentName);
+            currentName = null;
+        }
+        else if (trimmed.toLowerCase().includes('enabled')) {
+            currentName = null;
+        }
+    }
+    return disabled;
+}
+export async function getDisabledPlugins() {
+    return parseDisabledPlugins(await runCommand('claude', ['plugin', 'list']));
+}

package/dist/scanner/fs-walk.d.ts

@@ -0,0 +1,7 @@
+export declare function safeReadFile(p: string): Promise<string | null>;
+export declare function safeReaddir(p: string): Promise<string[]>;
+export declare function isDirectory(p: string): Promise<boolean>;
+export declare function isBrokenSymlink(p: string): Promise<boolean>;
+export declare function resolveRealPath(p: string): Promise<string>;
+export declare function getDirSize(dir: string): Promise<number>;
+export declare function runCommand(file: string, args: string[]): Promise<string>;

package/dist/scanner/fs-walk.js

@@ -0,0 +1,82 @@
+import { readFile, readdir, lstat, realpath, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function safeReadFile(p) {
+    try {
+        return await readFile(p, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+export async function safeReaddir(p) {
+    try {
+        return await readdir(p);
+    }
+    catch {
+        return [];
+    }
+}
+export async function isDirectory(p) {
+    try {
+        return (await stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function isBrokenSymlink(p) {
+    try {
+        const lstats = await lstat(p);
+        if (!lstats.isSymbolicLink())
+            return false;
+        await realpath(p);
+        return false;
+    }
+    catch {
+        try {
+            return (await lstat(p)).isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export async function resolveRealPath(p) {
+    try {
+        return await realpath(p);
+    }
+    catch {
+        return p;
+    }
+}
+export async function getDirSize(dir) {
+    let total = 0;
+    const entries = await safeReaddir(dir);
+    for (const entry of entries) {
+        const p = join(dir, entry);
+        try {
+            const s = await stat(p);
+            if (s.isFile())
+                total += s.size;
+            else if (s.isDirectory())
+                total += await getDirSize(p);
+        }
+        catch { /* skip */ }
+    }
+    return total;
+}
+// execFile (not exec) — never routes through a shell, so command arguments
+// cannot be interpreted as shell metacharacters regardless of caller inputs.
+export async function runCommand(file, args) {
+    try {
+        const { execFile } = await import('node:child_process');
+        return new Promise((resolve) => {
+            execFile(file, args, { timeout: 10000 }, (_err, stdout) => {
+                resolve(stdout || '');
+            });
+        });
+    }
+    catch {
+        return '';
+    }
+}

package/dist/scanner/index.d.ts

@@ -0,0 +1,5 @@
+import type { ScanResult } from '../types.js';
+export interface ScanOptions {
+    lookbackDays?: number;
+}
+export declare function scan(opts?: ScanOptions): Promise<ScanResult>;