packlight-cli 0.0.0-stage → 0.1.1

package/dist/core/scan.d.ts

@@ -0,0 +1,16 @@
+import { type Inventory } from './types.js';
+export interface ScanOptions {
+    home: string;
+    /** Working directory the scan runs from; sets projectScope when it is inside a known project. */
+    cwd: string;
+    now?: Date;
+    since?: string;
+}
+/**
+ * Maps working directories to project roots: Claude Code's own project registry first, then the nearest git root.
+ * A folder neither claims belongs to no project, and the home folder is never a project (its .claude is the user's).
+ */
+export declare function projectResolver(registered: string[], home: string): (cwd: string) => string | null;
+export declare function scan(opts: ScanOptions): Promise<Inventory>;
+/** Codex: the same inventory contract, read from ~/.codex. Usage comes from SKILL.md reads and MCP tool calls. */
+export declare function scanCodex(opts: ScanOptions): Promise<Inventory>;

package/dist/core/scan.js

@@ -0,0 +1,345 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+import { claudePaths, collectInventory, registeredProjects, skillUsageNames } from '../adapters/claude-code/inventory.js';
+import { codexPaths, codexProjects, collectCodexInventory } from '../adapters/codex/inventory.js';
+import { scanCodexLogs } from '../adapters/codex/logs.js';
+import { compareVersions, scanLogs } from '../adapters/claude-code/logs.js';
+import { itemId, valueFingerprint } from './hash.js';
+import { SCHEMA_VERSION } from './types.js';
+const DAY = 86_400_000;
+/** A session with more than this share of unrecognised usage lines makes all usage "uncertain" (eng A2). */
+const UNKNOWN_SHARE_LIMIT = 0.01;
+const isUnder = (path, root) => path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
+/**
+ * Maps working directories to project roots: Claude Code's own project registry first, then the nearest git root.
+ * A folder neither claims belongs to no project, and the home folder is never a project (its .claude is the user's).
+ */
+export function projectResolver(registered, home) {
+    const roots = registered.filter(r => r !== home).sort((a, b) => b.length - a.length);
+    const cache = new Map();
+    return (cwd) => {
+        const hit = cache.get(cwd);
+        if (hit !== undefined)
+            return hit;
+        let root = roots.find(r => isUnder(cwd, r)) ?? null;
+        if (!root) {
+            for (let d = cwd; d !== home; d = dirname(d)) {
+                if (existsSync(join(d, '.git'))) {
+                    root = d;
+                    break;
+                }
+                if (dirname(d) === d)
+                    break;
+            }
+        }
+        cache.set(cwd, root);
+        return root;
+    };
+}
+function addUse(u, use, now) {
+    u.total++;
+    if (use.ts && now - Date.parse(use.ts) < 30 * DAY)
+        u.last30++;
+    if (use.ts && (!u.lastUsed || use.ts > u.lastUsed))
+        u.lastUsed = use.ts;
+    const key = use.project ?? 'global';
+    const p = (u.byProject[key] ??= { total: 0, lastUsed: null });
+    p.total++;
+    if (use.ts && (!p.lastUsed || use.ts > p.lastUsed))
+        p.lastUsed = use.ts;
+}
+/** Items a use could belong to: global ones plus the ones scoped to the project the use happened in. */
+const visibleIn = (items, project) => items.filter(i => i.projectRoot === null || i.projectRoot === project);
+function creditUses(index, uses, now, onUnmatched) {
+    for (const [key, list] of uses) {
+        const owners = index.get(key);
+        if (!owners) {
+            onUnmatched?.(key, list);
+            continue;
+        }
+        for (const use of list) {
+            const candidates = visibleIn(owners, use.project);
+            // Shared names cannot be split: every candidate gets the use and is marked ambiguous (CEO O2).
+            if (candidates.length > 1)
+                for (const c of candidates)
+                    c.usage.ambiguous = true;
+            for (const c of candidates)
+                addUse(c.usage, use, now);
+        }
+    }
+}
+function indexBy(items, kinds) {
+    const idx = new Map();
+    for (const it of items) {
+        if (!kinds.includes(it.kind))
+            continue;
+        for (const k of it.logKeys) {
+            const list = idx.get(k);
+            if (list)
+                list.push(it);
+            else
+                idx.set(k, [it]);
+        }
+    }
+    return idx;
+}
+const INJECTING_EVENTS = new Set(['SessionStart', 'UserPromptSubmit']);
+function creditHooks(items, firings, now) {
+    const hooks = items.filter(i => i.kind === 'hook' && i.hook);
+    const byKey = new Map();
+    for (const h of hooks) {
+        const k = `${h.hook.event}\u0000${h.hook.command}`;
+        const list = byKey.get(k);
+        if (list)
+            list.push(h);
+        else
+            byKey.set(k, [h]);
+    }
+    const durations = new Map();
+    for (const f of firings) {
+        const owners = byKey.get(`${f.event}\u0000${f.command}`);
+        if (!owners)
+            continue;
+        const candidates = visibleIn(owners, f.project);
+        if (!candidates.length)
+            continue;
+        if (candidates.length > 1)
+            for (const c of candidates)
+                c.usage.ambiguous = true;
+        // Text from a linked context line was injected; otherwise only session-start and prompt hooks inject their output.
+        const injected = f.linkedChars > 0 ? f.linkedChars : INJECTING_EVENTS.has(f.event) ? f.ownChars : 0;
+        for (const c of candidates) {
+            addUse(c.usage, { ts: f.ts, project: f.project }, now);
+            const h = (c.usage.hook ??= { firings: 0, injectedChars: 0, avgDurationMs: 0, p95DurationMs: 0, injectionShared: false });
+            h.firings++;
+            h.injectedChars += Math.round(injected / candidates.length);
+            if (f.shared)
+                h.injectionShared = true;
+            if (f.durationMs !== null) {
+                const d = durations.get(c);
+                if (d)
+                    d.push(f.durationMs);
+                else
+                    durations.set(c, [f.durationMs]);
+            }
+        }
+    }
+    for (const [item, ds] of durations) {
+        ds.sort((a, b) => a - b);
+        item.usage.hook.avgDurationMs = Math.round(ds.reduce((a, b) => a + b, 0) / ds.length);
+        item.usage.hook.p95DurationMs = ds[Math.min(ds.length - 1, Math.ceil(ds.length * 0.95) - 1)] ?? 0;
+    }
+}
+/** A plugin's usage is its parts' usage. */
+function rollUpPlugins(items) {
+    for (const p of items.filter(i => i.kind === 'plugin')) {
+        for (const c of items.filter(i => i.plugin === p.plugin && i.kind !== 'plugin')) {
+            p.usage.total += c.usage.total;
+            p.usage.last30 += c.usage.last30;
+            if (c.usage.lastUsed && (!p.usage.lastUsed || c.usage.lastUsed > p.usage.lastUsed))
+                p.usage.lastUsed = c.usage.lastUsed;
+            for (const [proj, v] of Object.entries(c.usage.byProject)) {
+                const t = (p.usage.byProject[proj] ??= { total: 0, lastUsed: null });
+                t.total += v.total;
+                if (v.lastUsed && (!t.lastUsed || v.lastUsed > t.lastUsed))
+                    t.lastUsed = v.lastUsed;
+            }
+        }
+    }
+}
+function coverage(logs) {
+    const reasons = [];
+    const over = logs.sessions.filter(s => s.lines > 0 && s.unknownShapeLines / s.lines > UNKNOWN_SHARE_LIMIT);
+    if (over.length)
+        reasons.push(`${over.length} session(s) have more than 1% unrecognised usage lines`);
+    const newest = logs.versions[logs.versions.length - 1];
+    if (newest && (logs.unknownByVersion[newest] ?? 0) > 0)
+        reasons.push(`Claude Code ${newest} wrote ${logs.unknownByVersion[newest]} unrecognised usage line(s)`);
+    if (!logs.sessions.length)
+        reasons.push('no session logs found');
+    return { uncertain: reasons.length > 0, reasons };
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export async function scan(opts) {
+    const now = opts.now ?? new Date();
+    const paths = claudePaths(opts.home);
+    const registered = registeredProjects(paths);
+    const projectOf = projectResolver(registered, opts.home);
+    const logs = await scanLogs(paths.projectsLogDir, { projectOf, since: opts.since });
+    const sessionsByRoot = new Map();
+    for (const s of logs.sessions)
+        if (s.projectRoot)
+            sessionsByRoot.set(s.projectRoot, (sessionsByRoot.get(s.projectRoot) ?? 0) + 1);
+    const roots = [...new Set([...registered, ...sessionsByRoot.keys()])].filter(r => r !== opts.home).sort();
+    const existing = roots.filter(r => existsSync(r));
+    const items = collectInventory(paths, existing);
+    const t = now.getTime();
+    creditUses(indexBy(items, ['skill', 'command']), logs.skillUses, t);
+    creditUses(indexBy(items, ['agent']), logs.agentUses, t);
+    creditUses(indexBy(items, ['mcp']), logs.mcpUses, t, (key, list) => {
+        // claude.ai connectors appear only as opaque ids in the logs; they are listed, and removable only on claude.ai.
+        if (!UUID.test(key))
+            return;
+        const it = {
+            id: itemId({ agent: 'claude-code', kind: 'mcp', source: 'claude.ai connector', name: key, path: null }),
+            agent: 'claude-code', kind: 'mcp', name: key, source: 'claude.ai connector', path: null, projectRoot: null, enabled: true,
+            description: '', descHash: '', standingChars: 0, targetFingerprint: valueFingerprint(key), firstSeen: null, firstSeenSource: null,
+            logKeys: [key], declarations: [], removal: { method: 'manual', where: 'claude.ai › Settings › Connectors' },
+            usage: { total: 0, last30: 0, lastUsed: null, byProject: {}, ambiguous: false, uncertain: false },
+        };
+        for (const use of list)
+            addUse(it.usage, use, t);
+        items.push(it);
+    });
+    creditHooks(items, logs.hookFirings, t);
+    rollUpPlugins(items);
+    const cov = coverage(logs);
+    if (cov.uncertain)
+        for (const it of items)
+            it.usage.uncertain = true;
+    // Ids must be unique; a collision means two declarations hash alike and packlight cannot act safely (eng A1).
+    const seen = new Map();
+    for (const it of items) {
+        const prev = seen.get(it.id);
+        if (prev)
+            throw new Error(`Two items share the id ${it.id}: ${prev.path ?? prev.name} and ${it.path ?? it.name}`);
+        seen.set(it.id, it);
+    }
+    const budget = {};
+    for (const l of logs.listings)
+        budget[l.projectRoot ?? 'global'] = l;
+    const starts = logs.sessions.map(s => s.start).filter((x) => !!x).sort();
+    const scope = projectOf(opts.cwd);
+    const projectScope = scope && roots.includes(scope) ? scope : 'global';
+    // Each MCP server's tool names and instructions, from the scope's newest tool list, load every session.
+    const toolListing = {};
+    for (const l of logs.toolListings)
+        toolListing[l.projectRoot ?? 'global'] = l;
+    const tl = toolListing[projectScope] ?? logs.toolListings.at(-1);
+    if (tl) {
+        const norm = (k) => k.toLowerCase().replace(/[^a-z0-9]+/g, '_');
+        const byKey = new Map();
+        for (const it of items.filter(i => i.kind === 'mcp'))
+            for (const k of it.logKeys)
+                byKey.set(norm(k), [...(byKey.get(norm(k)) ?? []), it]);
+        for (const [key, load] of Object.entries(tl.servers)) {
+            let owners = byKey.get(norm(key));
+            if (!owners && UUID.test(key)) {
+                // A claude.ai connector no session called: listed all the same, and removable only on claude.ai.
+                const it = {
+                    id: itemId({ agent: 'claude-code', kind: 'mcp', source: 'claude.ai connector', name: key, path: null }),
+                    agent: 'claude-code', kind: 'mcp', name: key, source: 'claude.ai connector', path: null, projectRoot: null, enabled: true,
+                    description: '', descHash: '', standingChars: 0, targetFingerprint: valueFingerprint(key), firstSeen: null, firstSeenSource: null,
+                    logKeys: [key], declarations: [], removal: { method: 'manual', where: 'claude.ai › Settings › Connectors' },
+                    usage: { total: 0, last30: 0, lastUsed: null, byProject: {}, ambiguous: false, uncertain: false },
+                };
+                items.push(it);
+                owners = [it];
+            }
+            for (const it of owners ?? []) {
+                if (!it.enabled)
+                    continue;
+                it.standingChars = load.chars + load.instructionChars;
+                if (it.source === 'claude.ai connector' && !it.description)
+                    it.description = load.label ?? (load.sample?.length ? `Tools: ${load.sample.join(', ')}${load.tools > load.sample.length ? `, and ${load.tools - load.sample.length} more` : ''}` : '');
+            }
+        }
+    }
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        scanId: now.toISOString().replace(/[:.]/g, '-'),
+        agent: 'claude-code',
+        createdAt: now.toISOString(),
+        home: opts.home,
+        projectScope,
+        window: { from: opts.since ?? starts[0] ?? null, to: now.toISOString() },
+        sessionsInWindow: logs.sessions.filter(s => s.start).length,
+        linesTotal: logs.linesTotal,
+        linesUnknownShape: logs.linesUnknownShape,
+        linesUnreadable: logs.linesUnreadable,
+        claudeCodeVersions: logs.versions.sort(compareVersions),
+        coverage: cov,
+        projects: roots.map(root => ({ root, sessions: sessionsByRoot.get(root) ?? 0, exists: existing.includes(root) })),
+        sessions: logs.sessions,
+        budget,
+        toolListing,
+        listingPriority: skillUsageNames(paths),
+        unattributedHookChars: Math.round(logs.unattributedHookChars),
+        items,
+    };
+}
+/** Codex: the same inventory contract, read from ~/.codex. Usage comes from SKILL.md reads and MCP tool calls. */
+export async function scanCodex(opts) {
+    const now = opts.now ?? new Date();
+    const paths = codexPaths(opts.home);
+    const registered = codexProjects(paths);
+    const projectOf = projectResolver(registered, opts.home);
+    const logs = await scanCodexLogs(paths.sessions, { projectOf, since: opts.since });
+    const sessionsByRoot = new Map();
+    for (const s of logs.sessions)
+        if (s.projectRoot)
+            sessionsByRoot.set(s.projectRoot, (sessionsByRoot.get(s.projectRoot) ?? 0) + 1);
+    const roots = [...new Set([...registered, ...sessionsByRoot.keys()])].filter(r => r !== opts.home).sort();
+    const existing = roots.filter(r => existsSync(r));
+    const items = collectCodexInventory(paths, existing);
+    const t = now.getTime();
+    creditUses(indexBy(items, ['skill', 'command']), logs.skillUses, t);
+    creditUses(indexBy(items, ['mcp']), logs.mcpUses, t);
+    rollUpPlugins(items);
+    const reasons = [];
+    if (!logs.sessions.length)
+        reasons.push('no session logs found');
+    const newest = logs.versions.at(-1);
+    if (newest && (logs.unknownByVersion[newest] ?? 0) > 0)
+        reasons.push(`Codex ${newest} wrote ${logs.unknownByVersion[newest]} unrecognised log line(s)`);
+    const cov = { uncertain: reasons.length > 0, reasons };
+    if (cov.uncertain)
+        for (const it of items)
+            it.usage.uncertain = true;
+    const seen = new Map();
+    for (const it of items) {
+        const prev = seen.get(it.id);
+        if (prev)
+            throw new Error(`Two items share the id ${it.id}: ${prev.path ?? prev.name} and ${it.path ?? it.name}`);
+        seen.set(it.id, it);
+    }
+    const scope = projectOf(opts.cwd);
+    const projectScope = scope && roots.includes(scope) ? scope : 'global';
+    // What a session starts with: the scope's newest world_state, and first-request tokens from every scoped session.
+    const scoped = logs.starts.filter(s => projectScope === 'global' || s.projectRoot === projectScope);
+    const newestStart = scoped.at(-1) ?? logs.starts.at(-1);
+    const codexStart = newestStart ? { ...newestStart, firstRequestTokens: (scoped.length ? scoped : logs.starts).flatMap(s => s.firstRequestTokens) } : undefined;
+    // Only skills in the logged listing load; the rest sit on disk (a plugin the app has not switched on, say).
+    // An empty listing counts too: Codex runs started with skills off (codex exec from another agent, say) load none.
+    const listed = codexStart?.listedSkills;
+    if (listed) {
+        const names = new Set(listed);
+        for (const it of items)
+            if ((it.kind === 'skill') && !names.has(it.name))
+                it.standingChars = 0;
+        for (const p of items.filter(i => i.kind === 'plugin'))
+            p.standingChars = 0;
+    }
+    const starts = logs.sessions.map(s => s.start).filter((x) => !!x).sort();
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        scanId: now.toISOString().replace(/[:.]/g, '-'),
+        agent: 'codex',
+        createdAt: now.toISOString(),
+        home: opts.home,
+        projectScope,
+        window: { from: opts.since ?? starts[0] ?? null, to: now.toISOString() },
+        sessionsInWindow: logs.sessions.length,
+        linesTotal: logs.linesTotal,
+        linesUnknownShape: logs.linesUnknownShape,
+        linesUnreadable: logs.linesUnreadable,
+        claudeCodeVersions: logs.versions,
+        coverage: cov,
+        projects: roots.map(root => ({ root, sessions: sessionsByRoot.get(root) ?? 0, exists: existing.includes(root) })),
+        sessions: logs.sessions,
+        budget: {},
+        ...(codexStart ? { codexStart } : {}),
+        unattributedHookChars: 0,
+        items,
+    };
+}

package/dist/core/summary.d.ts

@@ -0,0 +1,4 @@
+import type { Inventory } from './types.js';
+export declare const chars: (n: number) => string;
+/** The text summary `packlight scan` prints: counts, the listing budget and the heaviest hooks. */
+export declare function summarize(inv: Inventory, ms: number): string;

package/dist/core/summary.js

@@ -0,0 +1,63 @@
+const KIND_ORDER = ['skill', 'command', 'agent', 'hook', 'plugin', 'mcp', 'instructions'];
+const KIND_LABEL = { skill: 'skills', command: 'commands', agent: 'agents', hook: 'hooks', plugin: 'plugins', mcp: 'MCP servers', instructions: 'instruction files' };
+export const chars = (n) => n >= 1e6 ? `${(n / 1e6).toFixed(1).replace(/\.0$/, '')}M` : n >= 1000 ? `${(n / 1000).toFixed(1).replace(/\.0$/, '')}k` : String(Math.round(n));
+/** The text summary `packlight scan` prints: counts, the listing budget and the heaviest hooks. */
+export function summarize(inv, ms) {
+    const out = [];
+    const from = inv.window.from ? inv.window.from.slice(0, 10) : 'the start';
+    out.push(`Scanned ${inv.sessionsInWindow} sessions from ${from} to ${inv.window.to.slice(0, 10)} in ${(ms / 1000).toFixed(1)} s.`);
+    out.push(`Scope: ${inv.projectScope}`);
+    out.push('');
+    const counts = KIND_ORDER.map(k => [k, inv.items.filter(i => i.kind === k)]).filter(([, l]) => l.length);
+    for (const [k, list] of counts) {
+        const detail = k === 'instructions'
+            ? `${chars(list.reduce((n, i) => n + i.standingChars, 0))} chars loaded in their projects`
+            : `${list.filter(i => i.usage.total === 0).length} not observed`;
+        out.push(`  ${String(list.length).padStart(4)} ${KIND_LABEL[k].padEnd(18)} ${detail}`);
+    }
+    if (inv.agent === 'codex') {
+        out.push('');
+        const s = inv.codexStart;
+        if (s) {
+            const t = [...s.firstRequestTokens].sort((a, b) => a - b);
+            const median = t[Math.floor(t.length / 2)];
+            out.push(`Session start (${s.timestamp?.slice(0, 10) ?? 'latest'}, Codex ${s.version ?? '?'}): ${median !== undefined ? `about ${chars(median)} tokens in the first request (median of ${t.length} sessions, measured by Codex); ` : ''}${s.listedSkills && !s.listedSkills.length ? 'no skills listed (these sessions started with skills off)' : `skill listing ${chars(s.skillListingChars)} chars`}, AGENTS.md ${chars(s.agentsMdChars)}${s.pluginInstructionChars ? `, plugin instructions ${chars(s.pluginInstructionChars)}` : ''}${s.appInstructionChars ? `, app instructions ${chars(s.appInstructionChars)}` : ''}.`);
+        }
+        else
+            out.push('Session start: no Codex session recorded what it started with.');
+        if (inv.coverage.uncertain)
+            out.push(`\nUsage may be incomplete: ${inv.coverage.reasons.join('; ')}.`);
+        return out.join('\n');
+    }
+    // A project scan reads that project's listing; a global scan reads the newest listing from any session.
+    const newest = Object.values(inv.budget).sort((a, b) => (a.timestamp ?? '').localeCompare(b.timestamp ?? '')).at(-1);
+    const budget = inv.projectScope !== 'global' ? inv.budget[inv.projectScope] ?? newest : newest;
+    out.push('');
+    if (budget) {
+        out.push(`Skill listing (${budget.timestamp?.slice(0, 10) ?? 'latest'}, Claude Code ${budget.version ?? '?'}): ${budget.dropped.length} of ${budget.skillCount} skills listed without their description (${chars(budget.listingChars)} chars).`);
+    }
+    else {
+        out.push('Skill listing: no listing found in these logs.');
+    }
+    const tl = inv.toolListing?.[inv.projectScope] ?? Object.values(inv.toolListing ?? {}).sort((a, b) => (a.timestamp ?? '').localeCompare(b.timestamp ?? '')).at(-1);
+    if (tl) {
+        const servers = Object.values(tl.servers);
+        const top = Object.entries(tl.servers).sort((a, b) => b[1].chars + b[1].instructionChars - a[1].chars - a[1].instructionChars).slice(0, 3)
+            .map(([k, s]) => `${s.label ?? (inv.items.find(i => i.kind === 'mcp' && i.logKeys.includes(k))?.description?.startsWith('Tools:') ? `${k.slice(0, 8)}… (${s.sample?.slice(0, 2).join(', ')})` : k)} ${chars(s.chars + s.instructionChars)}`);
+        out.push(`MCP tool list (${tl.timestamp?.slice(0, 10) ?? 'latest'}): ${servers.reduce((n, s) => n + s.tools, 0)} tools from ${servers.length} servers, ${chars(servers.reduce((n, s) => n + s.chars, 0))} chars of tool names and ${chars(servers.reduce((n, s) => n + s.instructionChars, 0))} of instructions every session. Largest: ${top.join(', ')}.`);
+    }
+    const hooks = inv.items.filter(i => i.usage.hook && i.usage.hook.firings > 0)
+        .sort((a, b) => b.usage.hook.injectedChars - a.usage.hook.injectedChars).slice(0, 5);
+    if (hooks.length) {
+        out.push('Hooks by injected text:');
+        for (const h of hooks) {
+            const u = h.usage.hook;
+            out.push(`  ${h.name}  ${u.firings} firings, ${chars(u.injectedChars / u.firings)} chars per firing, p95 ${u.p95DurationMs} ms${u.injectionShared ? ' (shared)' : ''}${h.usage.ambiguous ? ' (ambiguous)' : ''}`);
+        }
+    }
+    if (inv.coverage.uncertain)
+        out.push(`\nUsage may be incomplete: ${inv.coverage.reasons.join('; ')}.`);
+    if (inv.linesUnreadable)
+        out.push(`${inv.linesUnreadable} log lines could not be read.`);
+    return out.join('\n');
+}

package/dist/core/types.d.ts

@@ -0,0 +1,185 @@
+export declare const SCHEMA_VERSION = 1;
+export type Agent = 'claude-code' | 'codex';
+export type Kind = 'skill' | 'command' | 'agent' | 'hook' | 'plugin' | 'mcp' | 'instructions';
+export type RemovalMethod = 'move' | 'hook-extract' | 'mcp-extract' | 'plugin-disable' | 'manual';
+export type DeclScope = 'user' | 'local' | 'project' | 'project-local' | 'plugin' | 'app';
+/** One place an item is declared (eng X2): an item can be enabled in several settings files at once. */
+export interface Declaration {
+    file: string;
+    scope: DeclScope;
+    /** JSON pointer inside `file` for settings-file declarations (hooks, MCP servers, plugin flags). */
+    pointer?: string;
+    enabled?: boolean;
+}
+export interface HookUsage {
+    firings: number;
+    /** Characters the hook added to the context: linked additional-context text, else hook output. */
+    injectedChars: number;
+    avgDurationMs: number;
+    p95DurationMs: number;
+    /** Injected text could not be split between several hooks that fired on the same tool call. */
+    injectionShared: boolean;
+}
+export interface Usage {
+    total: number;
+    last30: number;
+    lastUsed: string | null;
+    /** Uses per project root (or "global" when the line had no project). */
+    byProject: Record<string, {
+        total: number;
+        lastUsed: string | null;
+    }>;
+    /** Another item shares the name or command the logs record, so the count cannot be split (CEO O2). */
+    ambiguous: boolean;
+    /** The logs held lines packlight could not recognise, so a zero may be wrong (eng A2). */
+    uncertain: boolean;
+    hook?: HookUsage;
+}
+export interface Item {
+    id: string;
+    agent: Agent;
+    kind: Kind;
+    name: string;
+    /** Human source label: "personal", "project", "plugin:<name>", "claude.ai synced", "user config", … */
+    source: string;
+    /** Absolute path of the item on disk, or null for items that only live in an app or web UI. */
+    path: string | null;
+    /** Project root for project-scoped items; null for items that load in every project. */
+    projectRoot: string | null;
+    enabled: boolean;
+    description: string;
+    /** sha256 of name + description (drives incremental rating). */
+    descHash: string;
+    /** Characters this item puts into every session's context (0 for hooks and on-demand items). */
+    standingChars: number;
+    /** Content fingerprint checked again before apply (eng X1). */
+    targetFingerprint: string;
+    /** Earliest known install time (design-delta DE5); null when unknown. */
+    firstSeen: string | null;
+    firstSeenSource: 'birthtime' | 'mtime' | 'installedAt' | null;
+    /** Keys the session logs use for this item (skill name, "plugin:skill", subagent type, MCP server …). */
+    logKeys: string[];
+    /** Parent plugin key ("name@marketplace") for plugin-bundled items; plugins are the removal unit (CEO O3). */
+    plugin?: string;
+    hook?: {
+        event: string;
+        matcher: string | null;
+        command: string;
+    };
+    members?: Partial<Record<Kind, number>>;
+    declarations: Declaration[];
+    /** suite: a folder other skills depend on (gstack); never moved, never offered by the fix. */
+    removal: {
+        method: RemovalMethod;
+        where?: string;
+        suite?: true;
+    };
+    usage: Usage;
+}
+export interface SessionRecord {
+    id: string;
+    file: string;
+    projectRoot: string | null;
+    start: string | null;
+    end: string | null;
+    lines: number;
+    unknownShapeLines: number;
+    unreadableLines: number;
+    versions: string[];
+}
+/** One skill listing as Claude Code logged it: which skills kept their description (eng X8). */
+export interface BudgetObservation {
+    sessionId: string;
+    timestamp: string | null;
+    version: string | null;
+    projectRoot: string | null;
+    skillCount: number;
+    listingChars: number;
+    withDescription: string[];
+    dropped: string[];
+    /** Every line in listing order, with its size as logged (multi-line descriptions included). */
+    entries?: ListingLine[];
+}
+export interface CodexStart {
+    sessionId: string;
+    timestamp: string | null;
+    version: string | null;
+    projectRoot: string | null;
+    skillListingChars: number;
+    /** Skill names in that listing: skills on disk but not listed do not load. */
+    listedSkills?: string[];
+    agentsMdChars: number;
+    pluginInstructionChars: number;
+    appInstructionChars: number;
+    /** Input tokens of each scoped session's first request, as Codex counted them (includes the first message). */
+    firstRequestTokens: number[];
+}
+export interface ListingLine {
+    name: string;
+    chars: number;
+    described: boolean;
+}
+/** One server's share of a session's tool list: its tool-name lines and its instructions block. */
+export interface ToolServerLoad {
+    tools: number;
+    chars: number;
+    instructionChars: number;
+    label?: string; /** A few tool names, to tell id-named connectors apart. */
+    sample?: string[];
+}
+/**
+ * The tool list one session was given: Claude Code names every deferred tool at session start, and MCP servers
+ * may add instructions. Logged as deltas; this is their sum for the session.
+ */
+export interface ToolListing {
+    sessionId: string;
+    timestamp: string | null;
+    version: string | null;
+    projectRoot: string | null;
+    /** By server key: the part of "mcp__<key>__<tool>", or the instructions' server name in the same form. */
+    servers: Record<string, ToolServerLoad>;
+    /** Claude Code's own deferred tools (no "mcp__" prefix). */
+    builtIn: {
+        tools: number;
+        chars: number;
+    };
+}
+export interface Inventory {
+    schemaVersion: number;
+    scanId: string;
+    agent: Agent;
+    createdAt: string;
+    home: string;
+    /** "global", or the project root the scan was run for (eng X6, CEO O1). */
+    projectScope: string;
+    window: {
+        from: string | null;
+        to: string;
+    };
+    sessionsInWindow: number;
+    linesTotal: number;
+    linesUnknownShape: number;
+    linesUnreadable: number;
+    claudeCodeVersions: string[];
+    coverage: {
+        uncertain: boolean;
+        reasons: string[];
+    };
+    projects: {
+        root: string;
+        sessions: number;
+        exists: boolean;
+    }[];
+    sessions: SessionRecord[];
+    /** Newest initial skill listing per project root ("global" key for no project). */
+    budget: Record<string, BudgetObservation>;
+    /** Codex only: what its newest session started with, and measured first-request tokens (median over the window). */
+    codexStart?: CodexStart;
+    /** Newest tool list per project root ("global" key for no project). */
+    toolListing?: Record<string, ToolListing>;
+    /** Skills Claude Code itself counts as used (~/.claude.json skillUsage): it keeps their descriptions first. */
+    listingPriority?: string[];
+    /** Hook context the logs recorded but no hook line could be matched to. */
+    unattributedHookChars: number;
+    items: Item[];
+}

package/dist/core/types.js

@@ -0,0 +1,3 @@
+// The inventory contract (eng X6). Every later part of packlight reads this shape;
+// change it only with a schemaVersion bump.
+export const SCHEMA_VERSION = 1;

package/dist/report/client.d.ts

@@ -0,0 +1 @@
+export declare function clientMain(): void;