packlight-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cooper Kao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+<p>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/brand/packlight-mark-light.svg">
+    <img src="docs/brand/packlight-mark.svg" width="72" height="72" alt="">
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# packlight
+
+See what your coding agent carries, keep what you use, archive the rest.
+
+Claude Code loads every skill, agent, hook and MCP server you have installed into every session, used or not. packlight scans your setup and your local session logs, then writes one self-contained report. The report shows:
+
+- how many tokens each session starts with, by source: MCP tool names, the skill listing, hook text, agent descriptions
+- which skills are pushed out of Claude Code's skill listing
+- how much text each hook injects
+- which items were not used in any session since they were installed
+
+Works with **Claude Code** and **Codex**. packlight picks Claude Code when `~/.claude` exists; for Codex, add `--agent codex` (`packlight --agent codex`, `packlight fix --agent codex`). Each tool gets its own report: `~/.packlight/report-claude-code.html` for Claude Code, `~/.packlight/report-codex.html` for Codex. For Codex the headline is measured: Codex logs the input tokens of each session's first request, and packlight reports the median. Codex plugins and MCP servers are switched off in `~/.codex/config.toml`, so packlight lists them with the exact line to change rather than editing that file.
+
+**[See a sample report →](https://cooperism-lab.github.io/packlight/sample/)** (an invented setup, so you can click around before installing).
+
+You mark what to archive. `packlight apply` moves it out reversibly, and `packlight restore` brings it back.
+
+Everything runs locally: no telemetry, and no network calls from the CLI or the report.
+
+## Status
+
+Issues 1 to 3 are built (v0.1 scope). `packlight` scans your setup and opens a report: what every session starts with (MCP tool names per server, the skill listing, MCP instructions, hook text), which skills Claude Code dropped from its listing, what each hook injects, and what was not observed in your sessions. Mark what to archive and press Save my picks; `packlight apply` archives it and `packlight restore` puts it back byte for byte, with a crash-safe journal.
+
+Or skip the marking: `packlight fix` scans again, shows a plan that archives every unused item (none used since it was installed, over at least 20 sessions and 14 days, nothing you kept) with its projected gain, and asks once. It also lists the unused items only you can remove, such as claude.ai synced skills and the Claude app's own plugins.
+
+Needs Node 20 or later. Run it without installing:
+
+```bash
+npx packlight-cli                  # Claude Code: scan, write the report and open it
+npx packlight-cli --agent codex    # Codex
+```
+
+Or install it once, then use the short command:
+
+```bash
+npm install -g packlight-cli
+packlight
+packlight fix
+packlight restore --all
+```
+
+`npx` always runs the newest version; a global install updates with `npm update -g packlight-cli`.
+
+The spec has been through strategy, design and engineering review.
+
+- [docs/spec.md](docs/spec.md) is the full spec, including every review decision and the implementation tasks.
+- [docs/design.md](docs/design.md) is the approved design doc: problem, premises and approach.
+- [docs/report-design.md](docs/report-design.md) is the visual system for the report.
+
+Planned releases:
+
+- **v0.1:** scanner for Claude Code, the report, and reversible archive and restore.
+- **v0.2:** overlap detection, plus a packlight skill that rates items and writes "which one" cards. This is the public launch.
+- **v0.3:** Codex adapter.
+
+## Who made it
+
+Built by Cooper Kao ([cooperism-lab](https://github.com/cooperism-lab)). Issues and pull requests are welcome.
+
+## Licence
+
+MIT © 2026 Cooper Kao

package/dist/adapters/claude-code/inventory.d.ts

@@ -0,0 +1,48 @@
+import { dirname } from 'node:path';
+import type { Declaration, Item, Kind } from '../../core/types.js';
+export interface ClaudePaths {
+    home: string;
+    claude: string;
+    claudeJson: string;
+    projectsLogDir: string;
+    desktopExtensions: string;
+    /** Claude desktop app folder holding claude.ai organisation plugins (macOS). */
+    appSessions: string;
+}
+export declare function claudePaths(home: string): ClaudePaths;
+export declare const readText: (p: string) => string;
+export declare const dirs: (p: string) => string[];
+export declare const files: (p: string, ext: string) => string[];
+export declare function firstSeenOf(path: string): {
+    firstSeen: string | null;
+    firstSeenSource: Item['firstSeenSource'];
+};
+export interface ItemInput {
+    agent?: Item['agent'];
+    kind: Kind;
+    name: string;
+    source: string;
+    path: string | null;
+    projectRoot?: string | null;
+    enabled?: boolean;
+    description?: string;
+    standingChars?: number;
+    fingerprint: string;
+    firstSeen?: string | null;
+    firstSeenSource?: Item['firstSeenSource'];
+    logKeys?: string[];
+    plugin?: string;
+    hook?: Item['hook'];
+    members?: Item['members'];
+    declarations?: Declaration[];
+    removal: Item['removal'];
+    pointer?: string;
+}
+export declare function makeItem(i: ItemInput): Item;
+export declare function collectInventory(paths: ClaudePaths, projectRoots: string[]): Item[];
+/** Skills Claude Code counts as used in ~/.claude.json: their descriptions go into the listing first. */
+export declare function skillUsageNames(paths: ClaudePaths): string[];
+/** Project roots Claude Code itself registered in ~/.claude.json. */
+export declare function registeredProjects(paths: ClaudePaths): string[];
+export declare const isDir: (p: string) => boolean;
+export { dirname };

package/dist/adapters/claude-code/inventory.js

@@ -0,0 +1,449 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, join, sep } from 'node:path';
+import { frontmatter } from '../../core/frontmatter.js';
+import { itemId, pathFingerprint, sha256, valueFingerprint } from '../../core/hash.js';
+const AGENT = 'claude-code';
+export function claudePaths(home) {
+    const claude = join(home, '.claude');
+    return {
+        home,
+        claude,
+        claudeJson: join(home, '.claude.json'),
+        projectsLogDir: join(claude, 'projects'),
+        desktopExtensions: join(home, 'Library', 'Application Support', 'Claude', 'Claude Extensions'),
+        appSessions: join(home, 'Library', 'Application Support', 'Claude', 'local-agent-mode-sessions'),
+    };
+}
+const readJson = (p) => {
+    try {
+        return JSON.parse(readFileSync(p, 'utf8').replace(/^/, ''));
+    }
+    catch {
+        return undefined;
+    }
+};
+export const readText = (p) => { try {
+    return readFileSync(p, 'utf8');
+}
+catch {
+    return '';
+} };
+export const dirs = (p) => {
+    try {
+        return readdirSync(p, { withFileTypes: true }).filter(d => d.isDirectory() || d.isSymbolicLink()).map(d => d.name).sort();
+    }
+    catch {
+        return [];
+    }
+};
+export const files = (p, ext) => {
+    try {
+        return readdirSync(p, { withFileTypes: true }).filter(d => !d.isDirectory() && d.name.endsWith(ext)).map(d => d.name).sort();
+    }
+    catch {
+        return [];
+    }
+};
+/** Pointer segment escaping per RFC 6901. */
+const ptr = (...parts) => '/' + parts.map(p => String(p).replace(/~/g, '~0').replace(/\//g, '~1')).join('/');
+export function firstSeenOf(path) {
+    const st = lstatSync(path, { throwIfNoEntry: false });
+    if (!st)
+        return { firstSeen: null, firstSeenSource: null };
+    if (st.birthtimeMs > 0)
+        return { firstSeen: new Date(st.birthtimeMs).toISOString(), firstSeenSource: 'birthtime' };
+    return { firstSeen: new Date(st.mtimeMs).toISOString(), firstSeenSource: 'mtime' };
+}
+export function makeItem(i) {
+    const description = i.description ?? '';
+    const agent = i.agent ?? AGENT;
+    return {
+        id: itemId({ agent, kind: i.kind, source: i.source, name: i.name, path: i.path, pointer: i.pointer }),
+        agent,
+        kind: i.kind,
+        name: i.name,
+        source: i.source,
+        path: i.path,
+        projectRoot: i.projectRoot ?? null,
+        enabled: i.enabled ?? true,
+        description,
+        descHash: sha256(`${i.name}\u0000${description}`),
+        standingChars: i.standingChars ?? 0,
+        targetFingerprint: i.fingerprint,
+        firstSeen: i.firstSeen ?? null,
+        firstSeenSource: i.firstSeenSource ?? null,
+        logKeys: i.logKeys ?? [],
+        ...(i.plugin ? { plugin: i.plugin } : {}),
+        ...(i.hook ? { hook: i.hook } : {}),
+        ...(i.members ? { members: i.members } : {}),
+        declarations: i.declarations ?? (i.path ? [{ file: i.path, scope: 'user' }] : []),
+        removal: i.removal,
+        usage: { total: 0, last30: 0, lastUsed: null, byProject: {}, ambiguous: false, uncertain: false },
+    };
+}
+/** What an item contributes to every session: its line in the skill or agent listing. */
+const listingChars = (name, description) => `- ${name}: ${description}\n`.length;
+// ---------------------------------------------------------------- skills, commands, agents
+function skillsIn(root, opts) {
+    const out = [];
+    for (const d of dirs(root)) {
+        if (d === 'synced' && !opts.plugin && !opts.projectRoot)
+            continue;
+        const dir = join(root, d);
+        const file = join(dir, 'SKILL.md');
+        if (!existsSync(file))
+            continue;
+        const fm = frontmatter(readText(file));
+        const name = opts.plugin ? `${pluginShortName(opts.plugin)}:${d}` : d;
+        const description = fm.description ?? '';
+        const seen = opts.firstSeen !== undefined ? { firstSeen: opts.firstSeen, firstSeenSource: opts.firstSeen ? 'installedAt' : null } : firstSeenOf(dir);
+        // A folder that holds other skills or shared scripts is a suite (gstack is one): moving it would break the
+        // skills that depend on it, so it is only removable through the suite's own uninstaller.
+        const suite = !opts.plugin && (existsSync(join(dir, 'bin')) || dirs(dir).some(c => existsSync(join(dir, c, 'SKILL.md'))));
+        out.push(makeItem({
+            kind: 'skill', name, source: opts.source, path: dir, projectRoot: opts.projectRoot, enabled: opts.enabled,
+            description, standingChars: opts.enabled ? listingChars(name, description) : 0,
+            fingerprint: suite ? valueFingerprint({ dir, description }) : pathFingerprint(dir), ...seen, logKeys: [name], plugin: opts.plugin,
+            removal: suite ? { method: 'manual', where: `the ${name} suite's own uninstaller (other skills depend on ${dir})`, suite: true } : { method: opts.method, where: opts.where },
+        }));
+    }
+    // Skills a suite installed belong to it too: removing one by hand would leave the suite half-installed, and
+    // its own updater would put it back. A skill is a member when a file in it links into a suite folder, a suite
+    // has a folder of the same name, or its description ends with "(<suite name>)" as gstack writes them.
+    const suites = out.filter(i => i.removal.suite && i.path);
+    for (const it of out) {
+        if (it.removal.suite || !it.path || !suites.length)
+            continue;
+        const owner = suites.find(su => linksInto(it.path, su.path) || existsSync(join(su.path, basename(it.path), 'SKILL.md'))
+            || new RegExp(`\\(${su.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\)\\s*$`).test(it.description));
+        if (owner)
+            it.removal = { method: 'manual', where: `the ${owner.name} suite's own uninstaller (installed with ${owner.name})`, suite: true };
+    }
+    return out;
+}
+/** Whether any file directly in `dir` is a symlink that resolves inside `target`. */
+function linksInto(dir, target) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return false;
+    }
+    const real = (() => { try {
+        return realpathSync(target);
+    }
+    catch {
+        return target;
+    } })();
+    return names.some(n => {
+        try {
+            if (!lstatSync(join(dir, n)).isSymbolicLink())
+                return false;
+            const r = realpathSync(join(dir, n));
+            return r === real || r.startsWith(real + sep);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function commandsIn(root, opts, prefix = '') {
+    const out = [];
+    for (const f of files(root, '.md')) {
+        const path = join(root, f);
+        const fm = frontmatter(readText(path));
+        const base = prefix + f.slice(0, -3);
+        const name = opts.plugin ? `${pluginShortName(opts.plugin)}:${base}` : base;
+        const description = fm.description ?? '';
+        const seen = opts.firstSeen !== undefined ? { firstSeen: opts.firstSeen, firstSeenSource: opts.firstSeen ? 'installedAt' : null } : firstSeenOf(path);
+        out.push(makeItem({
+            kind: 'command', name, source: opts.source, path, projectRoot: opts.projectRoot, enabled: opts.enabled,
+            description, standingChars: opts.enabled ? listingChars(name, description) : 0,
+            fingerprint: pathFingerprint(path), ...seen, logKeys: [name], plugin: opts.plugin,
+            removal: { method: opts.method, where: opts.where },
+        }));
+    }
+    // Commands in subfolders are invoked as "folder:name".
+    for (const d of dirs(root))
+        out.push(...commandsIn(join(root, d), opts, `${prefix}${d}:`));
+    return out;
+}
+function agentsIn(root, opts) {
+    const out = [];
+    for (const f of files(root, '.md')) {
+        const path = join(root, f);
+        const fm = frontmatter(readText(path));
+        const base = fm.name || f.slice(0, -3);
+        const name = opts.plugin ? `${pluginShortName(opts.plugin)}:${base}` : base;
+        const description = fm.description ?? '';
+        const seen = opts.firstSeen !== undefined ? { firstSeen: opts.firstSeen, firstSeenSource: opts.firstSeen ? 'installedAt' : null } : firstSeenOf(path);
+        out.push(makeItem({
+            kind: 'agent', name, source: opts.source, path, projectRoot: opts.projectRoot, enabled: opts.enabled,
+            description, standingChars: opts.enabled ? listingChars(name, description) : 0,
+            fingerprint: pathFingerprint(path), ...seen, logKeys: [name], plugin: opts.plugin,
+            removal: { method: opts.method, where: opts.where },
+        }));
+    }
+    return out;
+}
+function hooksFrom(config, ctx) {
+    const out = [];
+    if (!config || typeof config !== 'object')
+        return out;
+    for (const [event, groups] of Object.entries(config)) {
+        if (!Array.isArray(groups))
+            continue;
+        groups.forEach((g, gi) => {
+            (g?.hooks ?? []).forEach((h, hi) => {
+                const command = typeof h?.command === 'string' ? h.command : '';
+                if (!command)
+                    return;
+                const pointer = ptr('hooks', event, gi, 'hooks', hi);
+                const label = hookLabel(command, ctx.plugin);
+                const matcher = g?.matcher ?? null;
+                out.push(makeItem({
+                    kind: 'hook', name: `${label} · ${event}${matcher ? ` (${matcher})` : ''}`, source: ctx.source, path: ctx.file,
+                    projectRoot: ctx.projectRoot, enabled: ctx.enabled, fingerprint: valueFingerprint({ event, matcher, command }),
+                    firstSeen: ctx.firstSeen ?? null, firstSeenSource: ctx.firstSeen ? 'installedAt' : null,
+                    plugin: ctx.plugin, hook: { event, matcher, command },
+                    declarations: [{ file: ctx.file, scope: ctx.scope, pointer }], pointer,
+                    removal: { method: ctx.method, where: ctx.where ?? ctx.file },
+                }));
+            });
+        });
+    }
+    return out;
+}
+function hookLabel(command, plugin) {
+    if (plugin) {
+        // Name a plugin hook by its script so two hooks on one event stay distinguishable.
+        const script = /([\w.-]+\.(?:m?js|cjs|ts|sh|py|cmd))\b/.exec(command)?.[1];
+        const arg = command.trim().split(/\s+/).slice(1).find(w => /^[a-z][\w-]*$/.test(w));
+        return [pluginShortName(plugin), script, script ? undefined : arg].filter(Boolean).join(' ');
+    }
+    const first = command.trim().split(/\s+/)[0] ?? command;
+    const tool = basename(first.replace(/^["']|["']$/g, ''));
+    const rest = command.trim().split(/\s+/).slice(1, 3).join(' ');
+    return (tool + (rest && !rest.startsWith('-c') ? ` ${rest}` : '')).slice(0, 60);
+}
+function mcpFrom(servers, ctx) {
+    const out = [];
+    if (!servers || typeof servers !== 'object')
+        return out;
+    for (const [name, config] of Object.entries(servers)) {
+        const pointer = ptr(...ctx.pointerBase, name);
+        const logKey = ctx.plugin ? `plugin_${pluginShortName(ctx.plugin)}_${name}` : name;
+        out.push(makeItem({
+            kind: 'mcp', name, source: ctx.source, path: ctx.file, projectRoot: ctx.projectRoot, enabled: ctx.enabled,
+            fingerprint: valueFingerprint(config), firstSeen: ctx.firstSeen ?? null, firstSeenSource: ctx.firstSeen ? 'installedAt' : null,
+            logKeys: [logKey], plugin: ctx.plugin, declarations: [{ file: ctx.file, scope: ctx.scope, pointer }], pointer,
+            removal: { method: ctx.method, where: ctx.where ?? ctx.file },
+        }));
+    }
+    return out;
+}
+// ---------------------------------------------------------------- plugins
+const pluginShortName = (key) => key.split('@')[0] ?? key;
+function settingsFiles(paths, projectRoots) {
+    const out = [];
+    const add = (file, scope, projectRoot) => {
+        const json = readJson(file);
+        if (json && typeof json === 'object')
+            out.push({ file, scope, projectRoot, json });
+    };
+    add(join(paths.claude, 'settings.json'), 'user', null);
+    add(join(paths.claude, 'settings.local.json'), 'local', null);
+    for (const root of projectRoots) {
+        add(join(root, '.claude', 'settings.json'), 'project', root);
+        add(join(root, '.claude', 'settings.local.json'), 'project-local', root);
+    }
+    return out;
+}
+function pluginItems(paths, settings) {
+    const installed = readJson(join(paths.claude, 'plugins', 'installed_plugins.json'))?.plugins ?? {};
+    const out = [];
+    for (const [key, installs] of Object.entries(installed)) {
+        const install = Array.isArray(installs) ? installs[0] : undefined;
+        const root = install?.installPath;
+        if (!root || !existsSync(root))
+            continue;
+        const declarations = settings
+            .filter(s => s.json?.enabledPlugins && key in s.json.enabledPlugins)
+            .map(s => ({ file: s.file, scope: s.scope, pointer: ptr('enabledPlugins', key), enabled: s.json.enabledPlugins[key] !== false }));
+        // Effective state outside any project: local settings beat user settings; undeclared means enabled.
+        const enabled = (declarations.find(d => d.scope === 'local') ?? declarations.find(d => d.scope === 'user'))?.enabled ?? true;
+        const firstSeen = install?.installedAt ?? null;
+        const childOpts = { source: `plugin:${pluginShortName(key)}`, projectRoot: null, plugin: key, enabled, method: 'plugin-disable', where: key, firstSeen };
+        const children = [
+            ...skillsIn(join(root, 'skills'), childOpts),
+            ...commandsIn(join(root, 'commands'), childOpts),
+            ...agentsIn(join(root, 'agents'), childOpts),
+            ...hooksFrom(readJson(join(root, 'hooks', 'hooks.json'))?.hooks, { ...childOpts, file: join(root, 'hooks', 'hooks.json'), scope: 'plugin' }),
+            ...(() => { const m = mcpFile(join(root, '.mcp.json')); return mcpFrom(m.servers, { ...childOpts, file: join(root, '.mcp.json'), scope: 'plugin', pointerBase: m.pointerBase }); })(),
+        ];
+        const members = {};
+        for (const c of children)
+            members[c.kind] = (members[c.kind] ?? 0) + 1;
+        const manifest = readJson(join(root, '.claude-plugin', 'plugin.json')) ?? readJson(join(root, 'package.json')) ?? {};
+        out.push(makeItem({
+            kind: 'plugin', name: pluginShortName(key), source: key.includes('@') ? `marketplace:${key.split('@')[1]}` : 'plugin', path: root,
+            enabled, description: typeof manifest.description === 'string' ? manifest.description : '',
+            fingerprint: valueFingerprint({ key, version: install?.version, members: children.map(c => c.id).sort() }),
+            firstSeen, firstSeenSource: firstSeen ? 'installedAt' : null, plugin: key, members,
+            declarations: declarations.length ? declarations : [{ file: join(paths.claude, 'plugins', 'installed_plugins.json'), scope: 'user', pointer: ptr('plugins', key), enabled: true }],
+            removal: { method: 'plugin-disable', where: key },
+        }));
+        out.push(...children);
+    }
+    return out;
+}
+const mcpServersOf = (json) => json && typeof json === 'object' ? (json.mcpServers && typeof json.mcpServers === 'object' ? json.mcpServers : undefined) : undefined;
+/** A .mcp.json may list servers under "mcpServers" or, as some plugins ship it, at the top level. */
+function mcpFile(path) {
+    const json = readJson(path);
+    const wrapped = mcpServersOf(json);
+    if (wrapped)
+        return { servers: wrapped, pointerBase: ['mcpServers'] };
+    const isServer = (v) => !!v && typeof v === 'object' && (typeof v.command === 'string' || typeof v.url === 'string' || typeof v.type === 'string');
+    if (json && typeof json === 'object' && Object.values(json).length && Object.values(json).every(isServer))
+        return { servers: json, pointerBase: [] };
+    return { servers: undefined, pointerBase: ['mcpServers'] };
+}
+/** claude.ai organisation plugins the desktop app syncs: their skills load into Claude Code, removable only in the app. */
+function desktopPlugins(paths) {
+    const out = [];
+    for (const account of dirs(paths.appSessions)) {
+        for (const org of dirs(join(paths.appSessions, account))) {
+            const rpm = join(paths.appSessions, account, org, 'rpm');
+            const manifest = readJson(join(rpm, 'manifest.json'));
+            const entries = Array.isArray(manifest?.plugins) ? manifest.plugins : [];
+            for (const entry of entries) {
+                const root = join(rpm, String(entry.id ?? ''));
+                const name = readJson(join(root, '.claude-plugin', 'plugin.json'))?.name ?? entry.name;
+                if (!name || !existsSync(root))
+                    continue;
+                const key = `${name}@claude.ai`;
+                const where = 'Claude desktop app › Customize › Plugins';
+                const opts = { source: `plugin:${name}`, projectRoot: null, plugin: key, enabled: true, method: 'manual', where };
+                const children = [
+                    ...skillsIn(join(root, 'skills'), opts),
+                    ...commandsIn(join(root, 'commands'), opts),
+                    ...agentsIn(join(root, 'agents'), opts),
+                    ...(() => { const m = mcpFile(join(root, '.mcp.json')); return mcpFrom(m.servers, { ...opts, file: join(root, '.mcp.json'), scope: 'app', pointerBase: m.pointerBase }); })(),
+                ];
+                const members = {};
+                for (const c of children)
+                    members[c.kind] = (members[c.kind] ?? 0) + 1;
+                out.push(makeItem({
+                    kind: 'plugin', name, source: 'claude.ai plugin', path: root, description: entry.displayName ?? '',
+                    fingerprint: valueFingerprint({ key, updatedAt: entry.updatedAt, members: children.map(c => c.id).sort() }),
+                    ...firstSeenOf(root), plugin: key, members, declarations: [{ file: join(rpm, 'manifest.json'), scope: 'app' }],
+                    removal: { method: 'manual', where },
+                }));
+                out.push(...children);
+            }
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------- always-loaded instructions
+function instructionItem(path, source, projectRoot) {
+    if (!existsSync(path))
+        return null;
+    const text = readText(path);
+    return makeItem({
+        kind: 'instructions', name: projectRoot ? `${basename(projectRoot)}/${path.slice(projectRoot.length + 1)}` : basename(path),
+        source, path, projectRoot, standingChars: text.length, fingerprint: pathFingerprint(path), ...firstSeenOf(path),
+        removal: { method: 'manual', where: path },
+    });
+}
+// ---------------------------------------------------------------- entry point
+export function collectInventory(paths, projectRoots) {
+    const items = [];
+    const claudeJson = readJson(paths.claudeJson) ?? {};
+    const settings = settingsFiles(paths, projectRoots);
+    // Personal skills, commands, agents.
+    const personal = { source: 'personal', projectRoot: null, enabled: true, method: 'move' };
+    items.push(...skillsIn(join(paths.claude, 'skills'), personal));
+    items.push(...commandsIn(join(paths.claude, 'commands'), personal));
+    items.push(...agentsIn(join(paths.claude, 'agents'), personal));
+    // claude.ai skills synced into Claude Code: removable only on claude.ai.
+    for (const org of dirs(join(paths.claude, 'skills', 'synced'))) {
+        for (const s of dirs(join(paths.claude, 'skills', 'synced', org))) {
+            const dir = join(paths.claude, 'skills', 'synced', org, s);
+            const file = join(dir, 'SKILL.md');
+            if (!existsSync(file))
+                continue;
+            const description = frontmatter(readText(file)).description ?? '';
+            const name = `anthropic-skills:${s}`;
+            items.push(makeItem({
+                kind: 'skill', name, source: 'claude.ai synced', path: dir, description, standingChars: listingChars(name, description),
+                fingerprint: pathFingerprint(dir), ...firstSeenOf(dir), logKeys: [name],
+                removal: { method: 'manual', where: 'claude.ai › Settings › Capabilities › Skills' },
+            }));
+        }
+    }
+    items.push(...pluginItems(paths, settings));
+    items.push(...desktopPlugins(paths));
+    // Hooks declared in user and project settings files.
+    for (const s of settings) {
+        items.push(...hooksFrom(s.json.hooks, {
+            file: s.file, scope: s.scope, projectRoot: s.projectRoot, enabled: true, method: 'hook-extract',
+            source: s.projectRoot ? `project:${basename(s.projectRoot)}` : s.scope === 'local' ? 'user local settings' : 'user settings',
+        }));
+    }
+    // MCP servers: user scope in ~/.claude.json, local scope per project there, project scope in .mcp.json.
+    items.push(...mcpFrom(mcpServersOf(claudeJson), { file: paths.claudeJson, scope: 'user', source: 'user config', projectRoot: null, pointerBase: ['mcpServers'], enabled: true, method: 'mcp-extract' }));
+    for (const root of projectRoots) {
+        const local = claudeJson.projects?.[root];
+        items.push(...mcpFrom(mcpServersOf(local), { file: paths.claudeJson, scope: 'project-local', source: `project:${basename(root)}`, projectRoot: root, pointerBase: ['projects', root, 'mcpServers'], enabled: true, method: 'mcp-extract' }));
+        const projMcp = mcpFile(join(root, '.mcp.json'));
+        items.push(...mcpFrom(projMcp.servers, { file: join(root, '.mcp.json'), scope: 'project', source: `project:${basename(root)}`, projectRoot: root, pointerBase: projMcp.pointerBase, enabled: true, method: 'mcp-extract' }));
+        // Project skills, commands, agents and instructions.
+        const proj = { source: `project:${basename(root)}`, projectRoot: root, enabled: true, method: 'move' };
+        items.push(...skillsIn(join(root, '.claude', 'skills'), proj));
+        items.push(...commandsIn(join(root, '.claude', 'commands'), proj));
+        items.push(...agentsIn(join(root, '.claude', 'agents'), proj));
+        for (const f of ['CLAUDE.md', join('.claude', 'CLAUDE.md'), 'CLAUDE.local.md']) {
+            const it = instructionItem(join(root, f), `project:${basename(root)}`, root);
+            if (it)
+                items.push(it);
+        }
+    }
+    const userInstructions = instructionItem(join(paths.claude, 'CLAUDE.md'), 'personal', null);
+    if (userInstructions)
+        items.push(userInstructions);
+    // Desktop app extensions (macOS app folder): removable only in the app.
+    for (const d of dirs(paths.desktopExtensions)) {
+        const manifest = readJson(join(paths.desktopExtensions, d, 'manifest.json'));
+        if (!manifest)
+            continue;
+        const name = manifest.display_name || manifest.name || d;
+        items.push(makeItem({
+            kind: 'mcp', name, source: 'desktop extension', path: join(paths.desktopExtensions, d),
+            description: typeof manifest.description === 'string' ? manifest.description : '',
+            fingerprint: valueFingerprint(manifest), ...firstSeenOf(join(paths.desktopExtensions, d)),
+            logKeys: [name.replace(/[^A-Za-z0-9]+/g, '_')],
+            removal: { method: 'manual', where: 'Claude desktop app › Settings › Extensions' },
+        }));
+    }
+    return items;
+}
+/** Skills Claude Code counts as used in ~/.claude.json: their descriptions go into the listing first. */
+export function skillUsageNames(paths) {
+    const usage = readJson(paths.claudeJson)?.skillUsage;
+    return usage && typeof usage === 'object' ? Object.keys(usage) : [];
+}
+/** Project roots Claude Code itself registered in ~/.claude.json. */
+export function registeredProjects(paths) {
+    const projects = readJson(paths.claudeJson)?.projects;
+    return projects && typeof projects === 'object' ? Object.keys(projects) : [];
+}
+export const isDir = (p) => { try {
+    return statSync(p).isDirectory();
+}
+catch {
+    return false;
+} };
+export { dirname };

package/dist/adapters/claude-code/logs.d.ts

@@ -0,0 +1,54 @@
+import type { BudgetObservation, SessionRecord, ToolListing } from '../../core/types.js';
+/** Top-level line types seen in Claude Code logs up to 2.1.293 (eng A2). Anything else is counted as an unknown shape. */
+export declare const KNOWN_LINE_TYPES: Set<string>;
+export interface Use {
+    ts: string | null;
+    project: string | null;
+}
+export interface HookFiring {
+    event: string;
+    command: string;
+    ts: string | null;
+    project: string | null;
+    durationMs: number | null;
+    /** Output Claude Code recorded on the success line (used when no separate context line follows). */
+    ownChars: number;
+    /** Characters from additional-context/system-message lines linked to this firing. */
+    linkedChars: number;
+    /** Linked text was shared with other hooks on the same tool call and could not be split. */
+    shared: boolean;
+}
+export interface LogScan {
+    sessions: SessionRecord[];
+    skillUses: Map<string, Use[]>;
+    agentUses: Map<string, Use[]>;
+    mcpUses: Map<string, Use[]>;
+    hookFirings: HookFiring[];
+    /** Initial skill listings, oldest first. */
+    listings: BudgetObservation[];
+    /** One per main session file that logged a tool list, oldest first. */
+    toolListings: ToolListing[];
+    unattributedHookChars: number;
+    linesTotal: number;
+    linesUnknownShape: number;
+    /** Unknown-shape lines that looked like usage evidence (tool calls, hooks, listings). */
+    linesUnknownRelevant: number;
+    linesUnreadable: number;
+    unknownByVersion: Record<string, number>;
+    versions: string[];
+}
+export interface LogOptions {
+    /** Maps a working directory to its project root, or null when it belongs to no known project. */
+    projectOf: (cwd: string) => string | null;
+    since?: string;
+}
+/** Every .jsonl under the projects folder; subagent transcripts belong to their parent session. */
+export declare function logFiles(projectsDir: string): {
+    file: string;
+    sessionId: string;
+    isSubagent: boolean;
+}[];
+export declare function scanLogs(projectsDir: string, opts: LogOptions): Promise<LogScan>;
+/** A server name in the form tool names use: "plugin:x:y" and "My Server" become "plugin_x_y" and "My_Server". */
+export declare const toolKey: (name: string) => string;
+export declare function compareVersions(a: string, b: string): number;