packlight-cli 0.0.0-stage → 0.1.1

package/dist/archive/paths.js

@@ -0,0 +1,61 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function packlightPaths(home, root = join(home, '.packlight')) {
+    return {
+        home,
+        root,
+        scans: join(root, 'scans'),
+        archive: join(root, 'archive'),
+        journal: join(root, 'journal.json'),
+        lock: join(root, 'lock'),
+        keeps: join(root, 'keeps.json'),
+        log: join(root, 'packlight.log'),
+    };
+}
+export function readScan(paths, scanId) {
+    if (!/^[\w.-]+$/.test(scanId))
+        return undefined;
+    const file = join(paths.scans, scanId, 'inventory.json');
+    if (!existsSync(file))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Newest scan for one agent and project scope (eng X6 correction to F3). */
+export function newestScan(paths, agent, projectScope) {
+    let ids;
+    try {
+        ids = readdirSync(paths.scans).sort().reverse();
+    }
+    catch {
+        return undefined;
+    }
+    for (const id of ids) {
+        const inv = readScan(paths, id);
+        if (inv && inv.agent === agent && inv.projectScope === projectScope)
+            return inv;
+    }
+    return undefined;
+}
+/** The browser download folder per OS (eng SC1); undefined when it cannot be found. */
+export function downloadsDir(home = homedir(), platform = process.platform) {
+    if (platform === 'linux') {
+        try {
+            const dirs = readFileSync(join(home, '.config', 'user-dirs.dirs'), 'utf8');
+            const m = /^XDG_DOWNLOAD_DIR="?([^"\n]+)"?/m.exec(dirs);
+            if (m?.[1]) {
+                const p = m[1].replace(/^\$HOME/, home);
+                if (existsSync(p))
+                    return p;
+            }
+        }
+        catch { /* fall through to ~/Downloads */ }
+    }
+    const p = join(home, 'Downloads');
+    return existsSync(p) ? p : undefined;
+}

package/dist/archive/restore.d.ts

@@ -0,0 +1,30 @@
+import type { Manifest } from './manifest.js';
+export interface RestoreOptions {
+    home: string;
+    packlightRoot?: string;
+    /** Operation ids or item ids; ignored when `all` is set. */
+    ids: string[];
+    all: boolean;
+    out: (line: string) => void;
+    now?: () => Date;
+    crash?: (point: string) => void;
+}
+export interface RestoreResult {
+    exitCode: number;
+    restored: Manifest[];
+    refused: {
+        manifest: Manifest;
+        reason: string;
+    }[];
+    notFound: string[];
+}
+/**
+ * Puts archived items back, newest first, so several edits to one settings file unwind in order (D12).
+ * One refusal never stops the rest; the exit code is non-zero if any item was refused.
+ */
+export declare function restore(opts: RestoreOptions): RestoreResult;
+export declare function archiveList(opts: {
+    home: string;
+    packlightRoot?: string;
+    out: (line: string) => void;
+}): void;

package/dist/archive/restore.js

@@ -0,0 +1,84 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { listManifests, recover } from './journal.js';
+import { acquireLock } from './lock.js';
+import { restoreManifest } from './methods.js';
+import { packlightPaths } from './paths.js';
+import { reportRecovery } from './apply.js';
+/**
+ * Puts archived items back, newest first, so several edits to one settings file unwind in order (D12).
+ * One refusal never stops the rest; the exit code is non-zero if any item was refused.
+ */
+export function restore(opts) {
+    const paths = packlightPaths(opts.home, opts.packlightRoot);
+    const result = { exitCode: 0, restored: [], refused: [], notFound: [] };
+    const release = acquireLock(paths.lock);
+    try {
+        return restoreLocked(opts, paths, result);
+    }
+    finally {
+        release();
+    }
+}
+function restoreLocked(opts, paths, result) {
+    const recovery = recover(paths);
+    reportRecovery(recovery, opts.out);
+    if (recovery.refused.length)
+        return { ...result, exitCode: 1 };
+    const manifests = listManifests(paths);
+    const open = manifests.filter(m => m.status !== 'restored');
+    let chosen;
+    // Items removed by hand cannot be put back by packlight; --all lists them instead of failing on them.
+    if (opts.all) {
+        chosen = open.filter(m => m.status === 'archived');
+        const waiting = open.filter(m => m.status === 'waiting');
+        if (waiting.length)
+            opts.out(`${waiting.length} item${waiting.length === 1 ? ' was' : 's were'} removed by hand; add ${waiting.length === 1 ? 'it' : 'them'} back where ${waiting.length === 1 ? 'it was' : 'they were'} removed: ${waiting.map(m => m.itemName).join(', ')}.`);
+    }
+    else {
+        chosen = [];
+        for (const id of opts.ids) {
+            // An operation id names one archive; an item id names every open archive of that item.
+            const hits = open.filter(m => m.opId === id || m.itemId === id);
+            if (hits.length)
+                chosen.push(...hits);
+            else
+                result.notFound.push(id);
+        }
+    }
+    chosen = [...new Map(chosen.map(m => [m.opId, m])).values()].sort((a, b) => b.opId.localeCompare(a.opId));
+    for (const id of result.notFound)
+        opts.out(`Nothing to restore for ${id}: no archive of it is open. Run \`packlight archive list\` to see what is archived.`);
+    const now = opts.now ?? (() => new Date());
+    {
+        const ctx = { paths, scanId: '', now, expectedHash: new Map(), crash: opts.crash ?? (() => { }) };
+        for (const m of chosen) {
+            const o = restoreManifest(ctx, m);
+            mkdirSync(paths.root, { recursive: true });
+            appendFileSync(paths.log, `${now().toISOString()} restore ${m.method} ${m.itemId} ${m.opId} ${o.ok ? 'ok' : `refused: ${o.reason}`}\n`);
+            if (o.ok) {
+                result.restored.push(m);
+                opts.out(`Restored ${m.itemName} (${m.opId}).`);
+                continue;
+            }
+            result.refused.push({ manifest: m, reason: o.reason });
+            opts.out(`Not restored: ${m.itemName} (${m.opId}). ${o.reason}`);
+            if (o.fragment !== undefined)
+                opts.out(JSON.stringify(o.fragment, null, 2).split('\n').map(l => `    ${l}`).join('\n'));
+        }
+    }
+    if (opts.all && !chosen.length)
+        opts.out('Nothing is archived.');
+    result.exitCode = result.refused.length || result.notFound.length ? 1 : 0;
+    return result;
+}
+export function archiveList(opts) {
+    const manifests = listManifests(packlightPaths(opts.home, opts.packlightRoot));
+    if (!manifests.length) {
+        opts.out('Nothing archived yet.');
+        return;
+    }
+    for (const m of manifests) {
+        const where = m.originalPath ?? (m.settingsFile ? `${m.settingsFile} ${m.jsonPointer}` : m.manualSteps ?? '');
+        opts.out(`${m.opId}  ${m.status.padEnd(8)}  ${m.method.padEnd(14)}  ${m.itemName}  ${where}`);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, sep } from 'node:path';
+import { execFileSync, spawn } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { apply, claudeCodeRunning, findPicksFile, readKeeps, STALE_PICKS } from './archive/apply.js';
+import { downloadsDir, newestScan, packlightPaths, readScan } from './archive/paths.js';
+import { archiveList, restore } from './archive/restore.js';
+import { scan, scanCodex } from './core/scan.js';
+import { codexPaths } from './adapters/codex/inventory.js';
+import { INVOKE, MESSAGES, PASTE_COMMAND } from './core/messages.js';
+import { summarize } from './core/summary.js';
+import { buildReport, CHARS_PER_TOKEN, loadTotal, sessionLoad } from './report/model.js';
+import { fixPlan } from './report/fix.js';
+import { renderReport } from './report/render.js';
+import { MIN_DAYS, MIN_SESSIONS, suggestions } from './report/suggest.js';
+const USAGE = `packlight: see what your coding agent carries
+
+Usage:
+  packlight                 scan, write the report and open it
+  packlight report [--scan <id>] [--no-open]
+  packlight scan [--home <dir>] [--since <YYYY-MM-DD>] [--out <dir>] [--json]
+  packlight fix [--yes]     archive everything suggested, after one question
+  packlight apply [picks.json | --paste] [--yes] [--home <dir>] [--out <dir>]
+  packlight restore <id…> | --all [--home <dir>] [--out <dir>]
+  packlight archive list [--home <dir>] [--out <dir>]
+
+  --agent  claude-code or codex (default: Claude Code when ~/.claude exists, else Codex)
+  --home   home folder to work on (default: your home folder)
+  --out    packlight's own folder (default: <home>/.packlight)
+  --since  only count sessions from this date
+  --json   print the inventory to stdout instead of a summary
+  --yes    apply without asking (it still prints the plan)
+  --no-open  write the report without opening it`;
+function arg(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+/** Positional arguments after the command, skipping flags and their values. */
+function positional(argv) {
+    const withValue = new Set(['--home', '--out', '--since', '--agent']);
+    const out = [];
+    for (let i = 1; i < argv.length; i++) {
+        const a = argv[i];
+        if (withValue.has(a)) {
+            i++;
+            continue;
+        }
+        if (!a.startsWith('--'))
+            out.push(a);
+    }
+    return out;
+}
+/** Test hook: PACKLIGHT_CRASH_AT=<point> stops the process there, as kill -9 would (eng X3). */
+const crash = (point) => {
+    if (process.env.PACKLIGHT_CRASH_AT === point)
+        process.exit(137);
+};
+async function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return /^y(es)?$/i.test((await rl.question(`${question} [y/N] `)).trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+/** The newest scan's scope: the current folder's project if it has a scan, else the newest scan of any scope. */
+const AGENT_NAME = { 'claude-code': 'Claude Code', codex: 'Codex' };
+const setupDir = (agent, home) => (agent === 'codex' ? codexPaths(home).root : join(home, '.claude'));
+/** --agent, else Claude Code when its folder exists, else Codex when its folder exists. */
+function pickAgent(argv, home) {
+    const a = arg(argv, '--agent');
+    if (a)
+        return a === 'codex' || a === 'claude-code' ? a : null;
+    return existsSync(join(home, '.claude')) || !existsSync(codexPaths(home).root) ? 'claude-code' : 'codex';
+}
+function noSetup(agent, home) {
+    console.error(`No ${AGENT_NAME[agent]} setup found: ${setupDir(agent, home)} does not exist. Pass --home to scan another folder${agent === 'codex' ? '' : ', or --agent codex for Codex'}.`);
+    return 1;
+}
+function scopeFor(paths, agent) {
+    try {
+        const ids = readdirSync(paths.scans).sort().reverse();
+        const scans = ids.map(i => readScan(paths, i)).filter((x) => !!x && x.agent === agent);
+        const here = scans.find(s => s.projectScope !== 'global' && (process.cwd() === s.projectScope || process.cwd().startsWith(s.projectScope + sep)));
+        return (here ?? scans[0])?.projectScope ?? 'global';
+    }
+    catch {
+        return 'global';
+    }
+}
+/** One report file per agent, so a Codex scan never replaces the Claude Code report (or the other way round). */
+const reportFile = (agent) => (agent === 'codex' ? 'report-codex.html' : 'report-claude-code.html');
+/** Writes the agent's report beside packlight's data and returns its path. */
+function writeReport(home, packlightRoot, inv) {
+    const paths = packlightPaths(home, packlightRoot);
+    const file = join(packlightRoot, reportFile(inv.agent));
+    mkdirSync(packlightRoot, { recursive: true });
+    writeFileSync(file, renderReport(buildReport(inv, paths)));
+    // Before 0.1, Claude Code's report was report.html: remove that copy so an old report is never opened by mistake.
+    // Only packlight's own file goes (it carries packlight's data block); anything else at that name is left alone.
+    const legacy = join(packlightRoot, 'report.html');
+    if (inv.agent === 'claude-code' && existsSync(legacy)) {
+        try {
+            if (readFileSync(legacy, 'utf8').includes('id="packlight-data"'))
+                unlinkSync(legacy);
+        }
+        catch { /* leave it */ }
+    }
+    return file;
+}
+function readClipboard() {
+    const [cmd, args] = process.platform === 'darwin' ? ['pbpaste', []] : process.platform === 'win32' ? ['powershell', ['-NoProfile', '-Command', 'Get-Clipboard -Raw']] : ['xclip', ['-selection', 'clipboard', '-o']];
+    try {
+        return execFileSync(cmd, args, { encoding: 'utf8', maxBuffer: 10 * 1024 * 1024 });
+    }
+    catch {
+        return undefined;
+    }
+}
+function openFile(file) {
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [file]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', file]] : ['xdg-open', [file]];
+    try {
+        spawn(cmd, args, { detached: true, stdio: 'ignore' }).on('error', () => { }).unref();
+    }
+    catch { /* the path is printed anyway */ }
+}
+async function scanAndSave(home, packlightRoot, since, agent) {
+    const started = Date.now();
+    const inventory = await (agent === 'codex' ? scanCodex : scan)({ home, cwd: process.cwd(), since });
+    const dir = join(packlightRoot, 'scans', inventory.scanId);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, 'inventory.json');
+    writeFileSync(file, JSON.stringify(inventory));
+    return { inventory, ms: Date.now() - started, file };
+}
+const KIND_WORD = { skill: ['skill', 'skills'], command: ['command', 'commands'], agent: ['agent', 'agents'], hook: ['hook', 'hooks'], plugin: ['plugin', 'plugins'], mcp: ['MCP server', 'MCP servers'] };
+const count = (n, kind) => `${n} ${KIND_WORD[kind]?.[n === 1 ? 0 : 1] ?? kind}`;
+/** "about 2k tokens less per session (10% of your setup; 7.9k characters)": tokens estimated at CHARS_PER_TOKEN. */
+const saving = (savedChars, setup) => {
+    const pct = setup ? Math.min(100, (savedChars / setup) * 100) : 0;
+    return `about ${kchars(savedChars / CHARS_PER_TOKEN)} tokens less per session (${setup ? `${pct > 0 && pct < 1 ? 'under 1' : Math.round(pct)}% of your setup; ` : ''}${kchars(savedChars)} characters)`;
+};
+const kchars = (n) => (n >= 1000 ? `${(n / 1000).toFixed(1).replace(/\.0$/, '')}k` : String(n));
+/** What the fix will do and buy, in the words the report uses for its Fix button. */
+function fixSummary(plan, sessions, setup) {
+    if (!plan.ids.length)
+        return ['Nothing to fix: no item passes the rules for archiving (unused since it was installed, over at least ' + `${MIN_SESSIONS} sessions and ${MIN_DAYS} days, not kept, not shared).`];
+    const kinds = Object.entries(plan.byKind).map(([k, n]) => count(n, k)).join(', ');
+    const gains = [
+        plan.descriptionsBack ? `${plan.descriptionsBack} skill${plan.descriptionsBack === 1 ? '' : 's'} get their description back in Claude's skill listing` : null,
+        plan.sessionCharsSaved > 0 ? saving(plan.sessionCharsSaved, setup) : null,
+    ].filter(Boolean);
+    return [
+        `\nFix: archive ${plan.ids.length} unused items (${kinds}${plan.turnsOff > plan.ids.length ? `; ${plan.turnsOff} items with plugin parts` : ''}).`,
+        `None was used in the ${sessions} sessions scanned since it was installed. Everything can be restored.`,
+        gains.length ? `Projected: ${gains.join('; ')}.` : 'Projected: little change in what Claude loads each session; this mostly clears unused items from your setup.',
+    ];
+}
+function printByHand(plan, out, setup) {
+    const h = plan.byHand;
+    if (!h?.items.length)
+        return;
+    const gains = [h.sessionCharsSaved > plan.sessionCharsSaved ? saving(h.sessionCharsSaved, setup) : null, h.descriptionsBack > plan.descriptionsBack ? `${h.descriptionsBack} skill descriptions back` : null].filter(Boolean);
+    out(`\nAlso unused, but only you can remove these.${gains.length ? ` Removing them${plan.ids.length ? ' too' : ''}: ${gains.join(', ')}${plan.ids.length ? ' in all' : ''}.` : ''}`);
+    const byWhere = new Map();
+    for (const i of h.items)
+        byWhere.set(i.where, [...(byWhere.get(i.where) ?? []), i]);
+    for (const [where, list] of byWhere)
+        out(`  ${where}: ${list.map(i => i.kind === 'plugin' ? `${i.name} (${i.turnsOff} parts)` : i.name).join(', ')}`);
+}
+async function main(argv) {
+    const [command] = argv;
+    if (command === '--help' || command === '-h' || command === 'help') {
+        console.log(USAGE);
+        return 0;
+    }
+    const home = arg(argv, '--home') ?? homedir();
+    const packlightRoot = arg(argv, '--out') ?? join(home, '.packlight');
+    const out = (line) => console.log(line);
+    const agent = pickAgent(argv, home);
+    if (!agent) {
+        console.error('--agent takes claude-code or codex.');
+        return 2;
+    }
+    if (!command || command.startsWith('--')) {
+        if (!existsSync(setupDir(agent, home)))
+            return noSetup(agent, home);
+        const { inventory, ms } = await scanAndSave(home, packlightRoot, arg(argv, '--since'), agent);
+        console.log(summarize(inventory, ms));
+        const report = writeReport(home, packlightRoot, inventory);
+        console.log(`\nReport: ${report}\n${MESSAGES.afterScan}`);
+        if (!argv.includes('--no-open'))
+            openFile(report);
+        return 0;
+    }
+    if (command === 'report') {
+        const id = arg(argv, '--scan');
+        const paths = packlightPaths(home, packlightRoot);
+        const inv = id ? readScan(paths, id) : newestScan(paths, agent, scopeFor(paths, agent));
+        if (!inv) {
+            console.error(id ? `No scan ${id} in ${paths.scans}.` : `No scan yet. Run \`${INVOKE}\` first.`);
+            return 1;
+        }
+        const report = writeReport(home, packlightRoot, inv);
+        console.log(`Report: ${report}`);
+        if (!argv.includes('--no-open'))
+            openFile(report);
+        return 0;
+    }
+    if (command === 'scan') {
+        const since = arg(argv, '--since');
+        if (since && !/^\d{4}-\d{2}-\d{2}/.test(since)) {
+            console.error('--since takes a date like 2026-08-01.');
+            return 2;
+        }
+        if (!existsSync(setupDir(agent, home)))
+            return noSetup(agent, home);
+        if (argv.includes('--json')) {
+            process.stdout.write(JSON.stringify(await (agent === 'codex' ? scanCodex : scan)({ home, cwd: process.cwd(), since }), null, 1) + '\n');
+            return 0;
+        }
+        const { inventory, ms, file } = await scanAndSave(home, packlightRoot, since, agent);
+        console.log(summarize(inventory, ms));
+        console.log(`\nInventory written to ${file}`);
+        return 0;
+    }
+    if (command === 'apply') {
+        let picksFile = positional(argv)[0] ?? (argv.includes('--paste') ? undefined : findPicksFile(downloadsDir(home)));
+        if (argv.includes('--paste')) {
+            // Picks copied from the report: written to packlight's own folder, then read like any picks file (still untrusted).
+            const text = readClipboard();
+            if (!text?.trim().startsWith('{')) {
+                console.error('The clipboard holds no picks. In the report, press Copy picks, then run this again.');
+                return 2;
+            }
+            mkdirSync(packlightRoot, { recursive: true });
+            picksFile = join(packlightRoot, 'pasted-picks.json');
+            writeFileSync(picksFile, text);
+        }
+        if (picksFile && !existsSync(picksFile)) {
+            console.error(`There is no file at ${picksFile}. Run \`${INVOKE} apply\` with no path to use the newest picks file in your downloads folder.`);
+            return 2;
+        }
+        if (!picksFile) {
+            console.error(`No picks file found in your downloads folder. Pass its path (packlight apply <file>), or press Copy picks in the report and run: ${PASTE_COMMAND}`);
+            return 2;
+        }
+        const yes = argv.includes('--yes');
+        if (!yes && !process.stdin.isTTY) {
+            console.error('apply asks before it changes anything. Run it in a terminal, or pass --yes.');
+            return 2;
+        }
+        out(`Picks: ${picksFile}`);
+        try {
+            const r = await apply({ home, packlightRoot, picksFile, yes, confirm, claudeRunning: claudeCodeRunning, out, crash });
+            if (r.archived.length || r.kept || r.unkept)
+                out(`\n${MESSAGES.stepReport}`);
+            return r.exitCode;
+        }
+        catch (err) {
+            console.error(err.message === STALE_PICKS ? STALE_PICKS : `packlight: ${err.message}`);
+            return 1;
+        }
+    }
+    if (command === 'fix') {
+        if (!existsSync(setupDir(agent, home)))
+            return noSetup(agent, home);
+        const yes = argv.includes('--yes');
+        if (!yes && !process.stdin.isTTY) {
+            console.error('fix asks before it changes anything. Run it in a terminal, or pass --yes.');
+            return 2;
+        }
+        // Always from a fresh scan: the plan never acts on an old picture of your setup.
+        const { inventory } = await scanAndSave(home, packlightRoot, arg(argv, '--since'), agent);
+        const paths = packlightPaths(home, packlightRoot);
+        const kept = new Set(Object.keys(readKeeps(paths).keeps));
+        const plan = fixPlan(inventory, suggestions(inventory, kept), kept);
+        writeReport(home, packlightRoot, inventory);
+        const load = sessionLoad(inventory);
+        const setup = load ? loadTotal(load) : 0;
+        if (load)
+            out(`Each session starts with about ${kchars(setup / CHARS_PER_TOKEN)} tokens of setup (${kchars(setup)} characters).`);
+        for (const line of fixSummary(plan, inventory.sessionsInWindow, setup))
+            out(line);
+        if (!plan.ids.length) {
+            printByHand(plan, out, setup);
+            return 0;
+        }
+        mkdirSync(packlightRoot, { recursive: true });
+        const picksFile = join(packlightRoot, `fix-picks-${inventory.scanId}.json`);
+        writeFileSync(picksFile, JSON.stringify({ scanId: inventory.scanId, picks: plan.ids.map(id => ({ id, action: 'archive' })) }, null, 1));
+        out('');
+        try {
+            const r = await apply({ home, packlightRoot, picksFile, yes, confirm, claudeRunning: claudeCodeRunning, out, crash, singleQuestion: `Archive these ${plan.ids.length} items?` });
+            if (r.archived.length) {
+                out(`\nDone. Undo everything with \`${INVOKE} restore --all\`, or one item with the restore command above.`);
+                out(`${AGENT_NAME[agent]} reads its setup when a session starts: start a new session, then run \`${INVOKE}${agent === 'codex' ? ' --agent codex' : ''}\` to measure the result.`);
+            }
+            printByHand(plan, out, setup);
+            return r.exitCode;
+        }
+        catch (err) {
+            console.error(`packlight: ${err.message}`);
+            return 1;
+        }
+    }
+    if (command === 'restore') {
+        const all = argv.includes('--all');
+        const ids = positional(argv);
+        if (!all && !ids.length) {
+            console.error('Name what to restore (an id from `packlight archive list`) or pass --all.');
+            return 2;
+        }
+        return restore({ home, packlightRoot, ids, all, out, crash }).exitCode;
+    }
+    if (command === 'archive' && positional(argv)[0] === 'list') {
+        archiveList({ home, packlightRoot, out });
+        return 0;
+    }
+    console.error(`Unknown command "${argv.join(' ')}".\n\n${USAGE}`);
+    return 2;
+}
+main(process.argv.slice(2)).then(code => { process.exitCode = code; }, err => {
+    console.error(`packlight: ${err instanceof Error ? err.message : String(err)}`);
+    process.exitCode = 1;
+});

package/dist/core/buckets.d.ts

@@ -0,0 +1,3 @@
+export type UsageBucket = 'unused' | 'rare' | 'regular';
+/** Usage bucket relative to the scan window (eng Q1): rare means at most one use per ten sessions. */
+export declare function usageBucket(uses: number, sessionsInWindow: number): UsageBucket;

package/dist/core/buckets.js

@@ -0,0 +1,6 @@
+/** Usage bucket relative to the scan window (eng Q1): rare means at most one use per ten sessions. */
+export function usageBucket(uses, sessionsInWindow) {
+    if (uses <= 0)
+        return 'unused';
+    return uses <= sessionsInWindow / 10 ? 'rare' : 'regular';
+}

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,6 @@
+/** Reads `name`, `description` and `model` from a markdown file's YAML frontmatter (simple scalars and folded blocks). */
+export declare function frontmatter(text: string): {
+    name?: string;
+    description?: string;
+    model?: string;
+};

package/dist/core/frontmatter.js

@@ -0,0 +1,31 @@
+/** Reads `name`, `description` and `model` from a markdown file's YAML frontmatter (simple scalars and folded blocks). */
+export function frontmatter(text) {
+    const m = /^?---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (!m?.[1])
+        return {};
+    const out = {};
+    const lines = m[1].split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const kv = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(lines[i] ?? '');
+        if (!kv?.[1])
+            continue;
+        const key = kv[1];
+        if (key !== 'name' && key !== 'description' && key !== 'model')
+            continue;
+        let value = kv[2] ?? '';
+        // Block scalar (| or >) or a value continued on indented lines.
+        if (/^[|>][+-]?$/.test(value))
+            value = '';
+        const cont = [];
+        while (i + 1 < lines.length && /^(\s+\S|\s*$)/.test(lines[i + 1] ?? '') && !/^[A-Za-z][\w-]*:/.test(lines[i + 1] ?? '')) {
+            cont.push((lines[++i] ?? '').trim());
+        }
+        value = [value, ...cont].join(' ').replace(/\s+/g, ' ').trim();
+        if (value.length >= 2 && value.startsWith('"') && value.endsWith('"'))
+            value = value.slice(1, -1).replace(/\\(["\\/])/g, '$1').replace(/\\n/g, ' ');
+        else if (value.length >= 2 && value.startsWith("'") && value.endsWith("'"))
+            value = value.slice(1, -1).replace(/''/g, "'");
+        out[key] = value;
+    }
+    return out;
+}

package/dist/core/hash.d.ts

@@ -0,0 +1,19 @@
+export declare const sha256: (data: string | Buffer) => string;
+/**
+ * Stable item id (eng A1, extended by X5): readable slug plus 8 hex of a hash over everything that
+ * identifies one declaration, including the JSON pointer for settings-file entries.
+ */
+export declare function itemId(parts: {
+    agent: string;
+    kind: string;
+    source: string;
+    name: string;
+    path: string | null;
+    pointer?: string;
+}): string;
+/**
+ * Content fingerprint (eng X1): a symlink hashes its target string (the link is what packlight moves),
+ * a file hashes its bytes, a folder hashes every entry's relative path and content in sorted order.
+ */
+export declare function pathFingerprint(path: string): string;
+export declare const valueFingerprint: (value: unknown) => string;

package/dist/core/hash.js

@@ -0,0 +1,42 @@
+import { createHash } from 'node:crypto';
+import { lstatSync, readdirSync, readFileSync, readlinkSync } from 'node:fs';
+import { join } from 'node:path';
+export const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'item';
+/**
+ * Stable item id (eng A1, extended by X5): readable slug plus 8 hex of a hash over everything that
+ * identifies one declaration, including the JSON pointer for settings-file entries.
+ */
+export function itemId(parts) {
+    const key = [parts.agent, parts.kind, parts.source, parts.name, parts.path ?? '', parts.pointer ?? ''].join('\u0000');
+    return `${slug(`${parts.kind}-${parts.name}`)}-${sha256(key).slice(0, 8)}`;
+}
+/**
+ * Content fingerprint (eng X1): a symlink hashes its target string (the link is what packlight moves),
+ * a file hashes its bytes, a folder hashes every entry's relative path and content in sorted order.
+ */
+export function pathFingerprint(path) {
+    const h = createHash('sha256');
+    const walk = (p, rel) => {
+        const st = lstatSync(p, { throwIfNoEntry: false });
+        if (!st) {
+            h.update(`missing:${rel}\n`);
+            return;
+        }
+        if (st.isSymbolicLink()) {
+            h.update(`link:${rel}:${readlinkSync(p)}\n`);
+            return;
+        }
+        if (st.isDirectory()) {
+            h.update(`dir:${rel}\n`);
+            for (const name of readdirSync(p).sort())
+                walk(join(p, name), rel ? `${rel}/${name}` : name);
+            return;
+        }
+        h.update(`file:${rel}:${st.size}\n`);
+        h.update(readFileSync(p));
+    };
+    walk(path, '');
+    return h.digest('hex');
+}
+export const valueFingerprint = (value) => sha256(JSON.stringify(value));

package/dist/core/messages.d.ts

@@ -0,0 +1,16 @@
+/**
+ * How to call packlight again: "npx packlight-cli" when this run came through npx, plain "packlight" when it is
+ * installed (npm link or a global install). Until packlight is on npm, npx can only find a local install.
+ */
+export declare const INVOKE: string;
+export declare const APPLY_COMMAND: string;
+export declare const REPORT_COMMAND: string;
+export declare const PASTE_COMMAND: string;
+export declare const FIX_COMMAND: string;
+export declare const MESSAGES: {
+    readonly picksSaved: "Your browser should now have packlight-picks.json in your downloads folder. Nothing has changed yet.";
+    readonly noFile: `No file in your downloads? Press Copy picks, then run \`${string}\`.`;
+    readonly stepApply: `Run \`${string}\` in your terminal: it shows the plan and asks before it changes anything.`;
+    readonly stepReport: `Then run \`${string}\` to see the result.`;
+    readonly afterScan: "Mark what to archive in the report, press Save my picks, then run the command it shows.";
+};

package/dist/core/messages.js

@@ -0,0 +1,17 @@
+// Lines the CLI and the report both show, word for word (design DR8): one source so they never drift.
+/**
+ * How to call packlight again: "npx packlight-cli" when this run came through npx, plain "packlight" when it is
+ * installed (npm link or a global install). Until packlight is on npm, npx can only find a local install.
+ */
+export const INVOKE = process.env.npm_command === 'exec' ? 'npx packlight-cli' : 'packlight';
+export const APPLY_COMMAND = `${INVOKE} apply`;
+export const REPORT_COMMAND = `${INVOKE} report`;
+export const PASTE_COMMAND = `${INVOKE} apply --paste`;
+export const FIX_COMMAND = `${INVOKE} fix`;
+export const MESSAGES = {
+    picksSaved: 'Your browser should now have packlight-picks.json in your downloads folder. Nothing has changed yet.',
+    noFile: `No file in your downloads? Press Copy picks, then run \`${PASTE_COMMAND}\`.`,
+    stepApply: `Run \`${APPLY_COMMAND}\` in your terminal: it shows the plan and asks before it changes anything.`,
+    stepReport: `Then run \`${REPORT_COMMAND}\` to see the result.`,
+    afterScan: 'Mark what to archive in the report, press Save my picks, then run the command it shows.',
+};