@compaction/cli 0.1.4 → 0.3.0

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

package/dist/cli/commands/import.js

@@ -5,8 +5,10 @@ function printSupportedSources() {
     console.log(chalk.cyan("compaction import sources"));
     for (const adapter of listTraceAdapters()) {
         console.log(`- ${adapter.id}: ${adapter.displayName}`);
+        console.log(`    readiness: ${adapter.readiness}`);
     }
-    console.log("Live provider/runtime integrations remain future work; codex-exec-jsonl reads only local export files.");
+    console.log("All sources are local file import (no live integration). Readiness above is an honest integration-readiness " +
+        "label (AGENTS.md Level 0–6) + validation status — not a stronger integration claim than the evidence supports.");
 }
 export function registerImportCommand(program) {
     program