@compaction/cli 0.2.0 → 0.3.0

package/dist/cli/commands/gateway.js

@@ -0,0 +1,312 @@
+/**
+ * `compaction gateway start|status|stop` — the local Compaction Gateway (PUBLIC CLI). Charter run-15
+ * (record mode) + run-17 (lifecycle + guided onboarding).
+ *
+ * RECORD MODE only: a byte-safe, OpenAI-compatible local reverse proxy. Point your OpenAI client's base
+ * URL at the gateway; it forwards the request + response to the real provider BYTE-FOR-BYTE and records
+ * ONE content-free token/cache/cost receipt per call. No mutation, no cache optimization, no apply, no
+ * LCM. The client's API key rides straight through to the provider and is NEVER read, stored, or logged.
+ *
+ * `runGatewayStart` is exported so the guided onboarding TUI (`GatewayTui` → `init`) can start the same
+ * gateway with a config picked interactively — no duplicate server, no new behavior.
+ */
+import { URL } from "node:url";
+import path from "node:path";
+import { writeFileSync } from "node:fs";
+import { startGatewayServer } from "../../core/gateway/server.js";
+import { DEFAULT_GATEWAY_RECEIPTS_DIR, GATEWAY_RECEIPTS_FILE, formatFreshBilledInputReduction } from "../../core/gateway/receipt.js";
+import { writeGatewayPid, removeGatewayPid, readGatewayPid, getGatewayStatus, isProcessAlive } from "../../core/gateway/status.js";
+import { planGatewayConfigure, applyGatewayConfigure, formatConfigurePlan } from "../../core/gateway/configure.js";
+import { DEDUPE_POLICY } from "../../core/gateway/apply-policy.js";
+import { GATEWAY_RECOVERY_DIR, readRecovery } from "../../core/gateway/recovery.js";
+import { runThroughGateway } from "./dev.js";
+/** Parse `--listen http://127.0.0.1:8787` (or `127.0.0.1:8787`) into host + port. */
+export function parseListen(listen) {
+    const raw = listen.includes("://") ? listen : `http://${listen}`;
+    const u = new URL(raw);
+    const port = u.port ? Number.parseInt(u.port, 10) : 8787;
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error(`invalid --listen port in '${listen}'`);
+    }
+    return { host: u.hostname || "127.0.0.1", port };
+}
+/**
+ * Start the gateway from a validated config: bind the server, write the content-free pidfile (so
+ * `status`/`stop` work), print the honest banner, and install shutdown handlers that remove the pidfile.
+ * Reused by both `gateway start` and the guided onboarding. Throws on bind failure (the caller reports it).
+ */
+export async function runGatewayStart(config) {
+    if (config.mode !== "record" && config.mode !== "apply" && config.mode !== "dry-run") {
+        throw new Error(`gateway mode '${config.mode}' is not implemented (record | apply | dry-run)`);
+    }
+    const mutating = config.mode === "apply" || config.mode === "dry-run";
+    if (mutating && config.policy !== DEDUPE_POLICY) {
+        throw new Error(`gateway --mode ${config.mode} requires --policy ${DEDUPE_POLICY} (the only deterministic policy implemented)`);
+    }
+    const cwd = config.cwd ?? process.cwd();
+    const log = config.log ?? ((line) => console.log(line));
+    const started = await startGatewayServer({
+        provider: config.provider,
+        upstream: config.upstream,
+        mode: config.mode,
+        ...(config.policy ? { policy: config.policy } : {}),
+        cwd,
+        log,
+        host: config.host,
+        port: config.port
+    });
+    const base = `http://${started.address.host}:${started.address.port}`;
+    writeGatewayPid({
+        pid: process.pid,
+        host: started.address.host,
+        port: started.address.port,
+        upstream: config.upstream,
+        provider: config.provider,
+        mode: config.mode,
+        startedAt: new Date().toISOString()
+    }, cwd);
+    const receiptsPath = path.join(cwd, DEFAULT_GATEWAY_RECEIPTS_DIR, GATEWAY_RECEIPTS_FILE);
+    if (config.mode === "record") {
+        log("compaction gateway — RECORD mode (byte-safe; no mutation; content-free receipts)");
+    }
+    else if (config.mode === "dry-run") {
+        log(`compaction gateway — DRY-RUN mode (policy ${config.policy}; computes a candidate but forwards the ORIGINAL request unchanged)`);
+    }
+    else {
+        log(`compaction gateway — APPLY mode · EXPERIMENTAL (policy ${config.policy}; DETERMINISTIC only)`);
+        log("  Apply changes model-visible input for KNOWN-SAFE shapes only; the original is retained locally;");
+        log("  unknown/complex shapes FAIL CLOSED (forwarded unchanged). System/developer instructions & tool schemas are never touched.");
+    }
+    log(`  provider:  ${config.provider}  →  upstream ${config.upstream}`);
+    log(`  receipts:  ${receiptsPath}   (local-only, gitignored; token/cache counts only — no prompt/response content)`);
+    if (mutating)
+        log(`  recovery:  ${path.join(cwd, GATEWAY_RECOVERY_DIR)}   (local-only; the ORIGINAL request body when apply changes it — recover with 'compaction gateway recover <id>')`);
+    log("");
+    log(`Gateway running at ${base}`);
+    log("");
+    log("Run one command through Compaction:");
+    log("  compaction gateway run -- npm run dev");
+    log("");
+    log("Inspect traffic:");
+    log("  compaction gateway status");
+    log("");
+    log("If manual setup is needed:");
+    log(`  compaction gateway configure    (or point your OpenAI client at  baseURL = ${base}/v1  — keep your key on the client; the gateway never stores it)`);
+    log("");
+    log("  Stop from another terminal:  compaction gateway stop   ·   or press Ctrl-C here.");
+    const close = async () => {
+        removeGatewayPid(cwd);
+        await started.close();
+    };
+    if (config.installSignals !== false) {
+        const shutdown = async () => {
+            await close();
+            process.exit(0);
+        };
+        process.on("SIGINT", () => void shutdown());
+        process.on("SIGTERM", () => void shutdown());
+    }
+    return { base, close };
+}
+export function registerGatewayCommand(program) {
+    const gateway = program
+        .command("gateway")
+        .description("Local Compaction Gateway — a byte-safe, OpenAI-compatible reverse proxy that records a content-free " +
+        "token/cache/cost receipt per call. Default RECORD mode (no mutation); EXPERIMENTAL deterministic " +
+        "apply/dry-run modes are explicit opt-in (no cache-opt, no LCM, no semantic compaction).");
+    gateway
+        .command("start")
+        .description("Start the local gateway. Point your OpenAI client's base URL at --listen. RECORD forwards byte-for-byte; APPLY (experimental, explicit) deterministically dedupes known-safe shapes and retains the original locally.")
+        .option("--provider <name>", "Provider (OpenAI-compatible only).", "openai")
+        .option("--upstream <url>", "Upstream provider base URL (the request path is forwarded to its origin).", "https://api.openai.com/v1")
+        .option("--listen <url>", "Local address to listen on (e.g. http://127.0.0.1:8787).", "http://127.0.0.1:8787")
+        .option("--mode <mode>", "Gateway mode: record (default, byte-safe) | apply (experimental, deterministic) | dry-run (preview, forwards original).", "record")
+        .option("--policy <name>", `Deterministic apply policy (required for apply/dry-run). Only '${DEDUPE_POLICY}' is implemented.`)
+        .option("--approval <mode>", "Apply approval model (informational in run-17.2: starting apply mode IS the explicit approval; per-request interactive approval is deferred).", "ask")
+        .action(async (options) => {
+        const mode = (options.mode ?? "record");
+        if (mode !== "record" && mode !== "apply" && mode !== "dry-run") {
+            console.error(`error: gateway mode '${mode}' is not implemented (record | apply | dry-run).`);
+            process.exitCode = 1;
+            return;
+        }
+        if ((mode === "apply" || mode === "dry-run") && options.policy !== DEDUPE_POLICY) {
+            console.error(`error: --mode ${mode} requires --policy ${DEDUPE_POLICY} (the only deterministic policy implemented). ` +
+                `Apply is deterministic-only — no semantic compaction, no LCM.`);
+            process.exitCode = 1;
+            return;
+        }
+        const provider = options.provider ?? "openai";
+        const upstream = options.upstream ?? "https://api.openai.com/v1";
+        try {
+            new URL(upstream);
+        }
+        catch {
+            console.error(`error: --upstream '${upstream}' is not a valid URL.`);
+            process.exitCode = 1;
+            return;
+        }
+        let listen;
+        try {
+            listen = parseListen(options.listen ?? "http://127.0.0.1:8787");
+        }
+        catch (err) {
+            console.error(`error: ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            await runGatewayStart({ provider, upstream, mode, ...(options.policy ? { policy: options.policy } : {}), host: listen.host, port: listen.port });
+        }
+        catch (err) {
+            console.error(`error: could not start the gateway on ${listen.host}:${listen.port} — ${err.message}`);
+            process.exitCode = 1;
+        }
+    });
+    gateway
+        .command("status")
+        .description("Show whether the local gateway is running + a content-free rollup of its receipts (token/cache; no content).")
+        .option("--json", "Print the content-free status as JSON.")
+        .action(async (options) => {
+        const status = await getGatewayStatus(process.cwd());
+        if (options.json) {
+            console.log(JSON.stringify(status, null, 2));
+            return;
+        }
+        console.log("compaction gateway status");
+        if (status.running) {
+            console.log(`  gateway running:      yes  ${status.base ?? ""}  (pid ${status.pid})`);
+            console.log(`  provider / mode:      ${status.provider} / ${status.mode}`);
+            console.log(`  listen URL:           ${status.base ?? "(unknown)"}`);
+        }
+        else if (status.pid) {
+            console.log(`  gateway running:      no  (stale pidfile for pid ${status.pid} — run 'compaction gateway stop' to clear it)`);
+        }
+        else {
+            console.log("  gateway running:      no  (start it with 'compaction gateway start', or 'compaction' → Gateway setup)");
+        }
+        console.log(`  requests observed:    ${status.receiptsCount}  (local-only, content-free)`);
+        console.log(`  last request:         ${status.lastRequestAt ?? "none observed yet"}`);
+        console.log(`  cached input seen:    ${status.receiptsCount > 0 ? (status.cachedObserved ? "yes" : "no") : "unknown (no requests yet)"}`);
+        if (status.receiptsCount > 0) {
+            console.log(`  best fresh/billed input reduction:  ${formatFreshBilledInputReduction(status.summary.bestReduction)}`);
+            console.log(`  ${status.summary.modelVisibleBytesUnchanged ? "model-visible bytes unchanged" : "model-visible bytes: mixed — check receipts"}`);
+        }
+    });
+    gateway
+        .command("run")
+        .description("Run a command through the local Compaction Gateway. Usage: compaction gateway run -- <command>. Starts/reuses the gateway, injects the endpoint into the child (never a key), streams its output unchanged, preserves its exit code, and prints a content-free traffic summary.")
+        .option("--provider <name>", "Provider (OpenAI-compatible only).", "openai")
+        .option("--upstream <url>", "Upstream provider base URL.", "https://api.openai.com/v1")
+        .option("--listen <url>", "Local listen address when starting a gateway (default: an ephemeral local port).")
+        .argument("[command...]", "The command to run through the gateway (after --), e.g. -- npm run dev")
+        .allowUnknownOption(true)
+        .action(async (command, options) => {
+        await runThroughGateway(command, options, "compaction gateway run");
+    });
+    gateway
+        .command("activate")
+        .description("Print shell export lines that point THIS shell's OpenAI base URL at the local gateway. Use:  eval \"$(compaction gateway activate)\". It only PRINTS — it never edits files or mutates your shell, and it never attaches to a running process.")
+        .option("--listen <url>", "Gateway listen address to point at (default: the running gateway, else http://127.0.0.1:8787).")
+        .action(async (options) => {
+        const status = await getGatewayStatus(process.cwd());
+        let base;
+        if (options.listen) {
+            const l = parseListen(options.listen);
+            base = `http://${l.host}:${l.port}`;
+        }
+        else if (status.running && status.base) {
+            base = status.base;
+        }
+        else {
+            base = "http://127.0.0.1:8787";
+        }
+        const v1 = `${base}/v1`;
+        // Guidance to STDERR (not captured by eval); the exports go to STDOUT (captured by eval).
+        console.error('# compaction gateway activate — apply to this shell with:  eval "$(compaction gateway activate)"');
+        if (!(status.running && status.base) && !options.listen) {
+            console.error("# note: no running gateway detected; start one with 'compaction gateway start' (these exports point at the default local address).");
+        }
+        console.error("# your provider API key stays in your shell — the gateway never reads or stores it.");
+        console.log(`export OPENAI_BASE_URL=${v1}`);
+        console.log(`export OPENAI_API_BASE=${v1}`);
+    });
+    gateway
+        .command("configure")
+        .description("Propose pointing this project's OpenAI base URL at the local gateway (approval-gated: shows a diff; writes nothing without --apply; backs up first; never overwrites an existing base URL without --force).")
+        .option("--listen <url>", "Gateway listen address to route to (default: http://127.0.0.1:8787).", "http://127.0.0.1:8787")
+        .option("--apply", "Actually write the change (creates a .bak backup first).")
+        .option("--force", "Overwrite an existing provider base URL (only with --apply).")
+        .action((options) => {
+        let listen;
+        try {
+            listen = parseListen(options.listen ?? "http://127.0.0.1:8787");
+        }
+        catch (err) {
+            console.error(`error: ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        const baseUrl = `http://${listen.host}:${listen.port}/v1`;
+        const cwd = process.cwd();
+        const plan = planGatewayConfigure(cwd, baseUrl);
+        for (const line of formatConfigurePlan(plan))
+            console.log(line);
+        if (!options.apply)
+            return;
+        const result = applyGatewayConfigure(cwd, plan, options.force ?? false);
+        console.log("");
+        if (result.wrote) {
+            console.log(`compaction gateway configure: wrote ${result.targetFile}${result.backupFile ? ` (backup: ${result.backupFile})` : ""}.`);
+            console.log("  restart your app so it picks up the new base URL, or run:  compaction gateway run -- <command>");
+        }
+        else {
+            console.log(`compaction gateway configure: not written — ${result.reason}`);
+            process.exitCode = 1;
+        }
+    });
+    gateway
+        .command("recover")
+        .description("Recover the ORIGINAL request body that apply mode changed (retained locally under .compaction/gateway/recovery). Prints to stdout or writes to --out.")
+        .argument("<recovery_id>", "The recovery_id shown on the apply receipt.")
+        .option("--out <file>", "Write the original body to this file instead of stdout.")
+        .action((recoveryId, options) => {
+        const rec = readRecovery(process.cwd(), recoveryId);
+        if (!rec) {
+            console.error(`compaction gateway recover: no retained original found for id '${recoveryId}' under ${GATEWAY_RECOVERY_DIR}.`);
+            process.exitCode = 1;
+            return;
+        }
+        if (options.out) {
+            writeFileSync(options.out, rec.original_body, "utf8");
+            console.error(`compaction gateway recover: wrote the original request body (${rec.endpoint}, policy ${rec.policy}, captured ${rec.captured_at}) to ${options.out}.`);
+            return;
+        }
+        // The original body IS request content — it prints to stdout only on explicit recovery, never stored in a receipt.
+        process.stdout.write(rec.original_body.endsWith("\n") ? rec.original_body : `${rec.original_body}\n`);
+    });
+    gateway
+        .command("stop")
+        .description("Stop a running local gateway (started in another terminal) via its pidfile.")
+        .action(() => {
+        const rec = readGatewayPid(process.cwd());
+        if (!rec) {
+            console.log("compaction gateway stop: no gateway pidfile found — nothing to stop.");
+            return;
+        }
+        if (!isProcessAlive(rec.pid)) {
+            removeGatewayPid(process.cwd());
+            console.log(`compaction gateway stop: pid ${rec.pid} is not running — cleared the stale pidfile.`);
+            return;
+        }
+        try {
+            process.kill(rec.pid, "SIGTERM");
+            console.log(`compaction gateway stop: sent SIGTERM to pid ${rec.pid} (${rec.host}:${rec.port}). It removes its own pidfile on exit.`);
+        }
+        catch (err) {
+            console.error(`compaction gateway stop: could not signal pid ${rec.pid} — ${err.message}`);
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=gateway.js.map

package/dist/cli/commands/hooks.d.ts

@@ -0,0 +1,5 @@
+import { Command } from "commander";
+import { type HookUsageAggregate } from "../../core/hook-usage-aggregate.js";
+export declare function registerHooksCommand(program: Command): void;
+/** Render the content-free source-status aggregate as a readable block (provider-reported vs unavailable). */
+export declare function printHookUsageAggregate(aggregate: HookUsageAggregate): string;

package/dist/cli/commands/hooks.js

@@ -0,0 +1,181 @@
+/**
+ * `compaction hooks install|uninstall|status` — consented Claude Code Stop-hook management + a content-free
+ * source-status view of the records the hook produces (PUBLIC CLI).
+ * Installs a Stop hook that runs `compaction capture claude-code --from-hook` (content-free usage capture).
+ *
+ * Consent + safety: running this command IS the consent — it prints exactly what it will write and where,
+ * MERGES (never replaces) existing settings, is idempotent, supports `--dry-run` (writes nothing), and only
+ * ever removes Compaction's own hook on uninstall. `init` may suggest this command but must never write
+ * settings silently. `status` is read-only, local-first, content-free.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import { CLAUDE_CODE_HOOK_COMMAND, CLAUDE_CODE_BEFORE_CALL_HOOK_COMMAND, installStopHook, installBeforeCallHook, uninstallStopHook, uninstallBeforeCallHook } from "../../core/claude-code-hooks.js";
+import { aggregateHookUsageRecords, loadHookUsageRecords } from "../../core/hook-usage-aggregate.js";
+/** Resolve the target settings file from the scope flags. Default: project `.claude/settings.json`. */
+function resolveSettingsPath(options) {
+    if (options.settings)
+        return options.settings;
+    if (options.user)
+        return path.join(homedir(), ".claude", "settings.json");
+    if (options.local)
+        return path.join(process.cwd(), ".claude", "settings.local.json");
+    return path.join(process.cwd(), ".claude", "settings.json");
+}
+async function readSettings(file) {
+    try {
+        const raw = await readFile(file, "utf8");
+        const parsed = JSON.parse(raw);
+        return { settings: parsed && typeof parsed === "object" ? parsed : {}, existed: true };
+    }
+    catch {
+        return { settings: {}, existed: false };
+    }
+}
+async function writeSettings(file, settings) {
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}
+export function registerHooksCommand(program) {
+    const hooks = program
+        .command("hooks")
+        .description("Manage the Claude Code Stop hook that records CONTENT-FREE usage via `capture claude-code --from-hook`. " +
+        "Consented, merge-not-replace, idempotent, dry-run supported. Never writes settings without you running it.");
+    hooks
+        .command("install")
+        .description("Install the Compaction Stop (measurement) hook into Claude Code settings (merge-not-replace, idempotent). " +
+        "Add --before-call to ALSO install the UserPromptSubmit before-call RECOMMENDATION hook (run-13).")
+        .option("--settings <path>", "Explicit settings file to edit (overrides --local/--user).")
+        .option("--local", "Target project .claude/settings.local.json (personal, untracked).")
+        .option("--user", "Target ~/.claude/settings.json (all your projects).")
+        .option("--before-call", "ALSO install the UserPromptSubmit before-call RECOMMENDATION hook (a genuine pre-call event; content-free, fail-open, silent; recommendation-only — apply is a proven blocker on Claude Code hooks).")
+        .option("--dry-run", "Print the resulting settings without writing anything.")
+        .action(async (options) => {
+        console.log(chalk.cyan("compaction hooks install"));
+        const file = resolveSettingsPath(options);
+        const { settings, existed } = await readSettings(file);
+        let result;
+        try {
+            result = installStopHook(settings);
+            // The before-call hook merges on TOP of the Stop result (both merge-not-replace, both idempotent).
+            if (options.beforeCall)
+                result = installBeforeCallHook(result.settings);
+        }
+        catch (error) {
+            console.error(chalk.red(`  Not installed: ${error instanceof Error ? error.message : String(error)}`));
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`  target settings: ${file}${existed ? "" : " (will be created)"}`);
+        console.log(`  Stop hook:       ${CLAUDE_CODE_HOOK_COMMAND}  (measurement, content-free, post-session)`);
+        if (options.beforeCall) {
+            console.log(`  before-call:     ${CLAUDE_CODE_BEFORE_CALL_HOOK_COMMAND}  (UserPromptSubmit; recommendation-only, content-free, silent)`);
+        }
+        console.log("  posture:         content-free; fail-open (never breaks Claude Code); merge-not-replace; nothing is applied to your prompts.");
+        // `result.settings` reflects the FULL merge; `changed` reflects whether the last merge changed
+        // anything. Recompute "did anything change" honestly across both hooks by comparing to the read.
+        const changed = JSON.stringify(result.settings) !== JSON.stringify(settings);
+        if (!changed) {
+            console.log(chalk.green("  Already installed — no change (idempotent)."));
+            return;
+        }
+        if (options.dryRun) {
+            console.log(chalk.yellow("  --dry-run: NOT written. Resulting settings would be:"));
+            console.log(JSON.stringify(result.settings, null, 2));
+            return;
+        }
+        await writeSettings(file, result.settings);
+        console.log(chalk.green(`  Installed. Open Claude Code's /hooks once (or restart) to load it.`));
+        console.log(chalk.gray("  Uninstall anytime: compaction hooks uninstall" + (options.settings ? ` --settings ${file}` : options.user ? " --user" : options.local ? " --local" : "")));
+    });
+    hooks
+        .command("uninstall")
+        .description("Remove ONLY Compaction's hooks (Stop measurement + UserPromptSubmit before-call) from Claude Code settings (preserves all other settings/hooks).")
+        .option("--settings <path>", "Explicit settings file to edit (overrides --local/--user).")
+        .option("--local", "Target project .claude/settings.local.json.")
+        .option("--user", "Target ~/.claude/settings.json.")
+        .option("--dry-run", "Print the resulting settings without writing anything.")
+        .action(async (options) => {
+        console.log(chalk.cyan("compaction hooks uninstall"));
+        const file = resolveSettingsPath(options);
+        const { settings, existed } = await readSettings(file);
+        if (!existed) {
+            console.log(`  No settings file at ${file} — nothing to uninstall.`);
+            return;
+        }
+        // Remove BOTH Compaction hooks (only ours; each is scoped to its own event + command identity).
+        const stop = uninstallStopHook(settings);
+        const beforeCall = uninstallBeforeCallHook(stop.settings);
+        const removedCount = stop.removedCount + beforeCall.removedCount;
+        const finalSettings = beforeCall.settings;
+        console.log(`  target settings: ${file}`);
+        if (removedCount === 0) {
+            console.log("  No Compaction hooks present — no change.");
+            return;
+        }
+        if (options.dryRun) {
+            console.log(chalk.yellow(`  --dry-run: NOT written. Would remove ${removedCount} hook entr(y/ies). Resulting settings:`));
+            console.log(JSON.stringify(finalSettings, null, 2));
+            return;
+        }
+        await writeSettings(file, finalSettings);
+        console.log(chalk.green(`  Removed ${removedCount} Compaction hook entr(y/ies) (Stop + before-call). Other settings preserved.`));
+    });
+    hooks
+        .command("status")
+        .description("Source-status view of the CONTENT-FREE usage records produced by `capture claude-code --from-hook`. " +
+        "Aggregates by tool over your local records (by source/session/time). Read-only, local-first, no network. " +
+        "Distinguishes provider-reported usage from unavailable; makes NO savings claim.")
+        .option("--records-dir <dir>", "Base directory holding hook records", ".compaction/hooks")
+        .option("--since <iso>", "Only include records recorded at or after this ISO timestamp (time window).")
+        .option("--json", "Print the raw content-free aggregate JSON instead of the table.")
+        .action(async (options) => {
+        const records = await loadHookUsageRecords(options.recordsDir ?? ".compaction/hooks");
+        const aggregate = aggregateHookUsageRecords(records, options.since ? { since: options.since } : {});
+        if (options.json) {
+            console.log(JSON.stringify(aggregate, null, 2));
+            return;
+        }
+        console.log(chalk.cyan("compaction hooks status"));
+        console.log("  Local, content-free source status from Claude Code Stop-hook records. No content; no savings claim.");
+        console.log(printHookUsageAggregate(aggregate));
+    });
+}
+const dash = chalk.gray("—");
+function tok(value) {
+    return value === null ? chalk.gray("unavailable") : String(value);
+}
+/** Render the content-free source-status aggregate as a readable block (provider-reported vs unavailable). */
+export function printHookUsageAggregate(aggregate) {
+    const lines = [];
+    lines.push(`  records: ${aggregate.dedupedRecords} (deduped from ${aggregate.totalRecords})${aggregate.since ? ` · since ${aggregate.since}` : ""}`);
+    if (aggregate.tools.length === 0) {
+        lines.push(chalk.gray("  No hook records yet. Install the hook and let a Claude Code turn finish:"));
+        lines.push(chalk.gray("    compaction hooks install   →   (run Claude Code)   →   compaction hooks status"));
+        return lines.join("\n");
+    }
+    for (const t of aggregate.tools) {
+        // Headline never overstates: full provider-reported only when EVERY event is; mixed says "partial".
+        const status = t.providerReportedEvents === t.events && t.events > 0
+            ? chalk.green("live · provider-reported")
+            : t.providerReportedEvents > 0
+                ? chalk.yellow("live · provider-reported (partial)")
+                : t.unavailableEvents === t.events
+                    ? chalk.gray("usage unavailable")
+                    : chalk.yellow(t.tokenSources.join(" / ") || "recorded");
+        lines.push("");
+        lines.push(`  ${chalk.bold(t.tool)} — ${status}`);
+        lines.push(`    events:        ${t.events}   sessions: ${t.sessions}`);
+        lines.push(`    input tokens:  ${tok(t.inputTokens)}`);
+        lines.push(`    output tokens: ${tok(t.outputTokens)}${t.outputRecorded < t.events ? chalk.gray(`  (${t.events - t.outputRecorded} record(s) without output)`) : ""}`);
+        lines.push(`    reasoning:     ${chalk.gray("unavailable (Claude Code session usage does not report it separately)")}`);
+        lines.push(`    token source:  ${t.tokenSources.length ? t.tokenSources.join(" / ") : dash}`);
+        lines.push(`    provider/model:${t.providers.length || t.models.length ? ` ${[t.providers.join(", "), t.models.join(", ")].filter(Boolean).join(" · ")}` : ` ${dash}`}`);
+        lines.push(`    provider-reported / unavailable: ${t.providerReportedEvents} / ${t.unavailableEvents}`);
+        lines.push(`    window:        ${t.firstRecordedAt ?? dash} → ${t.lastRecordedAt ?? dash}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=hooks.js.map