@compaction/cli 0.1.2 → 0.1.4

package/README.md

@@ -66,7 +66,7 @@ npx @compaction/cli --help       # no install at all
 ```
 
 The installed binary is `compaction`. After a global install, sanity-check with
-`compaction --version` (→ `0.1.2`) and `compaction --help`.
+`compaction --version` (→ `0.1.4`) and `compaction --help`.
 
 ### curl one-liner
 

package/dist/cli/commands/compact.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import chalk from "chalk";
 import { Option } from "commander";
 import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
+import { withTraceFingerprint } from "../../core/report-generator.js";
 import { describeTokenAccounting } from "../../core/token-accounting.js";
 import { parseTraceFile } from "../../core/trace-parser.js";
 import { buildRunLabelsFile, hasAnyLabel } from "../../core/run-labels.js";
@@ -123,6 +124,11 @@ export function registerCompactCommand(program) {
             // hand-assembled bundle — the eval consumes the identical PolicyMiddlewareResult.
             const policyResult = applyCompactionPolicy({ trace, compactSkillInjections: approveSkillInjectionPolicy });
             const artifacts = await writeCompactionArtifacts(trace, options.out, runId, policyResult, undefined, { reviewerType, reviewSummaryPresent, approveSkillInjectionPolicy });
+            // Attribution/integrity (V0.2 savings-evidence): re-persist report.json with the
+            // content-addressed trace fingerprint so `aggregate`/`summary` can attribute each saving to a
+            // verifiable run and de-duplicate the same captured run if it is rolled up twice. Additive,
+            // backward-compatible; does not change any existing report field/label.
+            await writeJsonArtifact(options.out, "report.json", withTraceFingerprint(artifacts.report, trace));
             console.log(chalk.cyan("compaction compact"));
             console.log(artifacts.consoleReport);
             // Operator-visible only when the approval gesture was given; default output is unchanged.

package/dist/cli/commands/init.js

@@ -1,216 +1,243 @@
 import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
 import chalk from "chalk";
 import { defaultProjectsDir, discoverClaudeCodeSessions } from "../../core/adapters/claude-code-discovery.js";
+import { BRAND_HEX, VALUE_PROMISE, STATUS_PILLS, PRIMARY, SECONDARY, FREE_FLOW, HONESTY_LINES, FOOTER_LINES, ALL_WORKFLOW_KEYS } from "../onboarding/model.js";
+import { decideInteractiveTuiFromProcess } from "../onboarding/should-use-tui.js";
 /**
  * `compaction init` — first-run, value-led terminal onboarding.
  *
- * Converts "I installed a CLI" into "I am one command away from seeing my own
- * workflow's context waste." It is guidance plus ONE read-only local detection
- * (does a Claude Code projects directory exist, and how many sessions are in it).
+ * In a real interactive terminal this launches a graphical Ink TUI (a workflow
+ * chooser). Everywhere else — pipes, CI, NO_COLOR, dumb terminals, the test
+ * runner, `--static`, or `--path <focus>` — it prints the byte-stable static
+ * screen. Both surfaces share ONE model (`../onboarding/model`) so they always
+ * feature the same workflows, the same free follow-ups, and the same honest
+ * claim labels.
  *
- * Invariants (non-negotiable, hold on every path):
+ * Invariants (non-negotiable, hold on EVERY path — static and TUI):
  *  - writes nothing
  *  - makes no network call
  *  - reads no provider credential
  *  - needs no repo access
- * A provider credential is ONLY ever used if the operator explicitly runs
- * `capture provider-usage` (or enters operator-run measurement records).
+ * The TUI is a chooser, not an agent: no text input, no model call, no upload.
  *
- * Proprietary boundary (per mvp-plan.md §13): output names high-level waste
- * CATEGORIES and policy-FAMILY names plus before/after deltas, risk, safety,
- * approval requirement, artifacts, and the next action — never the proprietary
- * scoring formulas, thresholds, hidden heuristics, future-policy internals, or
- * commercial / moat logic.
+ * Free-CLI scope: onboarding features ONLY the free, local-first commands
+ * (capture / import / analyze / spend / summary / feedback). The optimization &
+ * verification engine commands (recommend / compact / inspect / approve /
+ * apply-context) are the opt-in Compaction API — NOT in the free CLI — and so
+ * are deliberately NOT featured here.
  *
- * Presentation note: this is a calm, structured, minimal first-run surface.
- * Hierarchy comes from spacing, dim secondary text, and a few restrained
- * symbols — not from a wall of enumerated text.
+ * Honesty rails: token counts are provider-reported when usage metadata is
+ * present, otherwise a labeled local estimate (chars/4); cost is a price-table
+ * estimate; nothing is called a saving until it is measured. No billing-confirmed,
+ * no semantic-preservation, no hosted-API-live, no auto-apply, no demo-first.
  */
-// Clean one-line wordmark. The hand-drawn ASCII banner read busy at small
-// terminal sizes; a spaced, bold mark with a rule under it reads premium.
-const MARK = chalk.bold("compaction");
+// Brand accent. chalk.hex degrades gracefully: on a non-color / non-truecolor
+// terminal chalk down-samples or no-ops, so the text is never lost.
+const ACCENT = chalk.hex(BRAND_HEX);
+// Spaced wordmark reads as a premium brand mark at any terminal width.
+const WORDMARK = ACCENT.bold("C O M P A C T I O N");
 const RULE = chalk.dim("─".repeat(58));
-const HEADLINE = "Context optimization for AI agents";
-const VALUE_PROP = chalk.dim("Reduce avoidable input/output tokens while preserving task-critical\n  context. Local-first — nothing is applied without your approval.");
-// The value loop, compressed to one line per step. Each step earns its place.
-const LOOP = [
-    ["capture", "a real trace from your own agent workflow"],
-    ["analyze", "where token spend and avoidable context waste are"],
-    ["recommend", "a candidate policy family + estimated before/after delta"],
-    ["compact", "the before/after token delta, and which family produced it"],
-    ["inspect", "safety evidence — source pointers, hashes, recoverable originals"],
-    ["approve", "emit a compacted context for your next call. No auto-apply."]
-];
-// Real-workflow paths only. compaction operates on the user's OWN agent
-// workflow; there is no demo / synthetic first-value path here. Demo fixtures
-// exist solely for tests, package smoke, and explicitly-labeled docs.
-const PRIMARY = {
-    key: "claude-code",
-    title: "Claude Code",
-    command: "compaction capture claude-code --discover"
-};
-const SECONDARY = [
-    {
-        key: "codex",
-        title: "Codex",
-        command: "codex exec --json '<task>' > run.jsonl  &&  compaction import run.jsonl --source codex-exec-jsonl --out ./my-trace"
-    },
-    {
-        key: "openai-agents",
-        title: "OpenAI Agents",
-        command: "compaction capture openai-agents --out ./my-trace -- <your-command>"
-    },
-    {
-        key: "import",
-        title: "Local trace",
-        command: "compaction import --list-sources   # then: import <file> --source <source> --out ./my-trace"
+async function readPackageVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        // dist/cli/commands -> dist -> package root
+        const pkgPath = path.resolve(here, "..", "..", "..", "package.json");
+        const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "unknown";
     }
-];
-// The follow-up sequence is identical for every path once a trace exists.
-const FOLLOW_UP = [
-    "compaction analyze       ./my-trace/captured-trace.json",
-    "compaction recommend     ./my-trace/captured-trace.json",
-    "compaction compact       ./my-trace/captured-trace.json --out ./my-trace/compacted",
-    "compaction apply-context ./my-trace/captured-trace.json --out ./my-trace/apply"
-];
+    catch {
+        return "unknown";
+    }
+}
+async function detectClaudeCode(projectsDir) {
+    let claudeDetected = false;
+    let sessionCount = 0;
+    if (existsSync(projectsDir)) {
+        try {
+            const discovery = await discoverClaudeCodeSessions({ projectsDir });
+            sessionCount = discovery.sessions.length;
+            claudeDetected = sessionCount > 0;
+        }
+        catch {
+            claudeDetected = false; // detection is best-effort; onboarding never fails on it
+        }
+    }
+    return { claudeDetected, sessionCount, projectsDir };
+}
+// ---------------------------------------------------------------------------
+// Static screen (the universal fallback). Output is intentionally byte-stable:
+// scripts, snapshots, and smoke tests depend on it.
+// ---------------------------------------------------------------------------
 function header(text) {
     return chalk.bold(text);
 }
-function loopBlock() {
-    const width = Math.max(...LOOP.map(([verb]) => verb.length));
-    return LOOP.map(([verb, desc]) => `  ${chalk.cyan(verb.padEnd(width))}  ${chalk.dim(desc)}`);
-}
 function primaryBlock(sessionCount) {
-    const tag = chalk.green(`   ✓ ${sessionCount} session(s) found`);
+    const tag = chalk.green(`  ✓ ${sessionCount} session(s) found`);
     return [
-        `${chalk.bold("▸ " + PRIMARY.title)}${chalk.dim("  · recommended")}${tag}`,
-        `  ${chalk.cyan(PRIMARY.command)}`
+        `${chalk.bold("▸ " + PRIMARY.title)}${chalk.dim("  · recommended first run")}${tag}`,
+        `  ${ACCENT(PRIMARY.command)}`
     ];
 }
-function secondaryBlock() {
-    const lines = [chalk.dim("Other workflows")];
-    for (const p of SECONDARY) {
-        lines.push(`  ${chalk.dim(p.title)}`);
-        lines.push(`    ${chalk.cyan(p.command)}`);
-    }
-    return lines;
-}
 function emptyStateBlock(projectsDir) {
-    // Calm, premium no-sessions state: explain, show how to create one, and give
-    // the exact rerun command. The secondary real paths follow below.
     return [
-        `${chalk.bold("▸ " + PRIMARY.title)}${chalk.dim("  · recommended")}`,
+        `${chalk.bold("▸ " + PRIMARY.title)}${chalk.dim("  · recommended first run")}`,
         chalk.dim(`  No sessions found under ${projectsDir}.`),
         chalk.dim("  Start or run a Claude Code session in any project, then re-run:"),
-        `    ${chalk.cyan("compaction capture claude-code --discover")}`
+        `    ${ACCENT("compaction capture claude-code --discover")}`
     ];
 }
+function supportedBlock() {
+    const summary = "Claude Code · OpenAI Agents SDK · Codex / local import · local trace import";
+    const lines = [header("Supported workflows"), `  ${chalk.dim(summary)}`, ""];
+    for (const p of SECONDARY) {
+        lines.push(`  ${chalk.bold(p.title)}`);
+        lines.push(`    ${ACCENT(p.command)}`);
+    }
+    return lines;
+}
 function afterCaptureBlock() {
+    const width = Math.max(...FREE_FLOW.map((f) => f.command.length));
     return [
         header("Then, on the trace you captured"),
         "",
-        ...FOLLOW_UP.map((c) => `  ${chalk.cyan(c)}`),
+        ...FREE_FLOW.map((f) => `  ${ACCENT(f.command.padEnd(width))}  ${chalk.dim(f.desc)}`),
+        "",
+        chalk.dim(`  ${HONESTY_LINES[0]}`),
+        chalk.dim(`  ${HONESTY_LINES[1]}`),
+        chalk.dim(`  ${HONESTY_LINES[2]}`),
         "",
-        chalk.dim("  You'll see: waste pattern CATEGORY, high-level POLICY FAMILY,"),
-        chalk.dim("  before/after input/output tokens, the TOKEN-COUNT SOURCE"),
-        chalk.dim("  (provider-reported vs estimated — never an estimate as reported),"),
-        chalk.dim("  RISK LEVEL, safety + source_recoverability, the APPROVAL REQUIREMENT"),
-        chalk.dim("  (--approve-in-workflow-use; no auto-apply), and the next action.")
+        chalk.dim(`  ${HONESTY_LINES[3]}`),
+        chalk.dim(`  ${HONESTY_LINES[4]}`)
     ];
 }
 function footerBlock() {
-    return [
-        chalk.dim("Local-first: no network, no credentials, no repo access for any of the above."),
-        chalk.dim("A provider credential is only ever used if YOU explicitly run"),
-        chalk.dim("`compaction capture provider-usage` or enter operator-run records.")
+    return FOOTER_LINES.map((l) => chalk.dim(l));
+}
+function buildStaticScreen(version, focus, det) {
+    const lines = [];
+    // 1. Wordmark + status + value promise.
+    lines.push("");
+    lines.push(`  ${WORDMARK}`);
+    lines.push("");
+    lines.push(`  ${chalk.dim(`v${version} · ${STATUS_PILLS.join(" · ")}`)}`);
+    lines.push("");
+    lines.push(`  ${VALUE_PROMISE}`);
+    lines.push("");
+    lines.push(RULE);
+    lines.push("");
+    // 2. Start here — primary path (Claude Code) or a focused secondary path.
+    if (!focus || focus === "claude-code") {
+        lines.push(header("Start here"));
+        lines.push("");
+        if (det.claudeDetected) {
+            lines.push(...primaryBlock(det.sessionCount));
+        }
+        else {
+            lines.push(...emptyStateBlock(det.projectsDir));
+        }
+        lines.push("");
+        if (!focus) {
+            lines.push(...supportedBlock());
+            lines.push("");
+        }
+    }
+    else {
+        const p = SECONDARY.find((s) => s.key === focus);
+        lines.push(header("Start here"));
+        lines.push("");
+        lines.push(`  ${chalk.bold(p.title)}`);
+        lines.push(`    ${ACCENT(p.command)}`);
+        lines.push("");
+    }
+    lines.push(RULE);
+    lines.push("");
+    // 3. The free follow-up sequence + honest labeling + opt-in-API positioning.
+    lines.push(...afterCaptureBlock());
+    lines.push("");
+    lines.push(RULE);
+    lines.push("");
+    // 4. Local-first footer.
+    lines.push(...footerBlock());
+    lines.push("");
+    return lines.join("\n");
+}
+// After the TUI exits with a selection, print a clean, copy-ready next-command
+// block to the scrollback so the user can paste and run it.
+function printSelection(card) {
+    const out = [
+        "",
+        `${chalk.bold("▸ " + card.title)}`,
+        chalk.dim(`  ${card.blurb}`),
+        "",
+        chalk.dim("  Run this next:"),
+        `    ${ACCENT(card.command)}`,
+        "",
+        chalk.dim(`  Then: ${FREE_FLOW.map((f) => f.command.replace("compaction ", "")).join(" · ")}`),
+        chalk.dim("  Local-first: no network, no credentials, no upload. Nothing is called a"),
+        chalk.dim("  saving until it is measured."),
+        ""
     ];
+    console.log(out.join("\n"));
 }
 export function registerInitCommand(program) {
     program
         .command("init")
-        .description("First-run onboarding: the value loop, how to capture YOUR first real trace, and the exact next commands. " +
-        "Guidance + one read-only local detection only — writes nothing, no network, no credentials.")
-        .option("--path <path>", "Focus one input path: claude-code | codex | openai-agents | import")
+        .description("First-run onboarding: an interactive workflow chooser in a real terminal (TUI), or the " +
+        "value promise + exact next commands as a static screen elsewhere. Guidance + one read-only " +
+        "local detection only — writes nothing, no network, no credentials.")
+        .option("--path <path>", "Focus one input path: claude-code | openai-agents | codex | import")
         .option("--projects-dir <dir>", "Claude Code projects directory to detect against (default: the standard local location)")
+        .option("--interactive", "prefer the interactive TUI; if no TTY is available, show the static screen and why")
+        .option("--static", "always show the plain static screen (no TUI)")
         .action(async (options) => {
         // Validate --path early so the error stays a clean one-liner.
-        const allKeys = [PRIMARY.key, ...SECONDARY.map((p) => p.key)];
-        if (options.path && !allKeys.includes(options.path)) {
-            console.error(`unknown --path '${options.path}'. Valid: ${allKeys.join(" | ")}`);
+        if (options.path && !ALL_WORKFLOW_KEYS.includes(options.path)) {
+            console.error(`unknown --path '${options.path}'. Valid: ${ALL_WORKFLOW_KEYS.join(" | ")}`);
             process.exitCode = 1;
             return;
         }
+        // Version read at runtime so it always matches the installed package.
+        const version = await readPackageVersion();
         // Read-only local detection (no writes, no network).
         const projectsDir = options.projectsDir ?? defaultProjectsDir();
-        let claudeDetected = false;
-        let sessionCount = 0;
-        if (existsSync(projectsDir)) {
-            try {
-                const discovery = await discoverClaudeCodeSessions({ projectsDir });
-                sessionCount = discovery.sessions.length;
-                claudeDetected = sessionCount > 0;
-            }
-            catch {
-                claudeDetected = false; // detection is best-effort; onboarding never fails on it
-            }
-        }
+        const det = await detectClaudeCode(projectsDir);
+        // Decide static vs interactive. A focused path (--path) or --static always
+        // serves static; --interactive forces the TUI iff a TTY is present;
+        // otherwise auto-detect.
+        // Note: --interactive cannot conjure a TTY (raw-mode keyboard nav needs
+        // one), so it does not override the TTY check; it only documents intent.
+        // When asked for but unavailable, we fall back to static with a reason.
         const focus = options.path;
-        const lines = [];
-        // 1. Mark + value prop.
-        lines.push("");
-        lines.push(`${MARK}  ${chalk.dim("·")}  ${HEADLINE}`);
-        lines.push(`  ${VALUE_PROP}`);
-        lines.push("");
-        lines.push(RULE);
-        lines.push("");
-        // 2. The value loop — what the tool actually does, one line per step.
-        lines.push(header("How it works"));
-        lines.push("");
-        lines.push(...loopBlock());
-        lines.push("");
-        lines.push(chalk.dim("  Estimates are labeled as estimates; provider-reported as provider-reported."));
-        lines.push(chalk.dim("  Nothing is called a saving until it is measured."));
-        lines.push("");
-        lines.push(RULE);
-        lines.push("");
-        // 3. Start here — primary path (Claude Code) or a focused secondary path.
-        if (!focus || focus === "claude-code") {
-            lines.push(header("Start here"));
-            lines.push("");
-            if (claudeDetected) {
-                lines.push(...primaryBlock(sessionCount));
+        const ttyDecision = decideInteractiveTuiFromProcess();
+        const wantTui = !focus && !options.static && ttyDecision.useTui;
+        if (wantTui) {
+            // Dynamic import keeps Ink/React off every non-TTY code path.
+            const { runInitTui } = await import("../onboarding/InitTui.js");
+            const result = await runInitTui({
+                version,
+                detection: {
+                    detected: det.claudeDetected,
+                    sessionCount: det.sessionCount,
+                    projectsDir: det.projectsDir
+                }
+            });
+            if (result.action === "select") {
+                printSelection(result.card);
             }
             else {
-                lines.push(...emptyStateBlock(projectsDir));
-            }
-            lines.push("");
-            // 4. Secondary real-workflow paths (compact, secondary styling).
-            //    Only on the default (unfocused) view.
-            if (!focus) {
-                lines.push(...secondaryBlock());
-                lines.push("");
+                console.log(chalk.dim("\nNo workflow selected. Run `compaction init` anytime.\n"));
             }
+            return;
         }
-        else {
-            // Focused secondary path.
-            const p = SECONDARY.find((s) => s.key === focus);
-            lines.push(header("Start here"));
-            lines.push("");
-            lines.push(`  ${chalk.bold(p.title)}`);
-            lines.push(`    ${chalk.cyan(p.command)}`);
-            lines.push("");
+        // If the user explicitly asked for --interactive but we are not in a TTY,
+        // tell them why we fell back, then serve the static screen.
+        if (options.interactive && !ttyDecision.useTui) {
+            console.error(chalk.dim(`(interactive TUI unavailable here: ${ttyDecision.reason}; showing static screen)`));
         }
-        lines.push(RULE);
-        lines.push("");
-        // 5. The follow-up sequence + what to expect.
-        lines.push(...afterCaptureBlock());
-        lines.push("");
-        lines.push(RULE);
-        lines.push("");
-        // 6. Local-first footer.
-        lines.push(...footerBlock());
-        lines.push("");
-        console.log(lines.join("\n"));
+        console.log(buildStaticScreen(version, focus, det));
     });
 }
 //# sourceMappingURL=init.js.map

package/dist/cli/commands/run.js

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { parseRunCommand, executeLocalCommand, persistLocalCommandRun } from "../../core/command-runner.js";
 import { writeJsonArtifact } from "../../core/artifact-writer.js";
+import { withTraceFingerprint } from "../../core/report-generator.js";
 import { localCommandRunToAgentTrace } from "../../core/run-trace-converter.js";
 import { runEngineCommand } from "../engine-degrade.js";
 export function registerRunCommand(program) {
@@ -23,6 +24,10 @@ export function registerRunCommand(program) {
             const trace = localCommandRunToAgentTrace(run);
             const tracePath = await writeJsonArtifact(persistedRun.outputDirectory, "trace.json", trace);
             const artifacts = await writeCompactionArtifacts(trace, persistedRun.outputDirectory, run.runId);
+            // Attribution/integrity (V0.2 savings-evidence): re-persist report.json with the content-addressed
+            // trace fingerprint so `aggregate`/`summary` attribute each saving to a verifiable run and
+            // de-duplicate a re-counted run. Additive; no existing report field/label changes.
+            await writeJsonArtifact(persistedRun.outputDirectory, "report.json", withTraceFingerprint(artifacts.report, trace));
             console.log(`Exit code: ${run.exitCode ?? "none"}`);
             console.log(`Signal: ${run.signal ?? "none"}`);
             console.log(`Duration: ${run.durationMs} ms`);

package/dist/cli/index.js

@@ -27,7 +27,7 @@ const program = new Command();
 program
     .name("compaction")
     .description("CLI-first trace compaction tools for AI agent workflows.")
-    .version("0.1.2");
+    .version("0.1.4");
 registerAnalyzeCommand(program);
 registerAdapterCommand(program);
 registerAggregateCommand(program);

package/dist/cli/onboarding/InitTui.d.ts

@@ -0,0 +1,52 @@
+import React from "react";
+import { type WorkflowCard } from "./model.js";
+/**
+ * Interactive first-run TUI for `compaction init` (Ink/React) — a minimal,
+ * premium, left-aligned, dark-terminal-first workflow chooser.
+ *
+ * Progressive enhancement gated behind a real TTY (see `decideInteractiveTui`):
+ * it NEVER runs in pipes/CI/NO_COLOR/dumb terminals or the test runner — those
+ * get the static screen — so it may freely rely on color and Unicode.
+ *
+ * The big COMPACTION wordmark is the visual hero; everything below is quiet and
+ * compact. Palette is restrained Compaction-blue only (no teal/cyan). The full
+ * UI is short and rendered into the alternate screen buffer (see `runInitTui`)
+ * so resizing repaints in place and never duplicates the wordmark.
+ *
+ * Invariants (identical to the static path): writes nothing, no network call,
+ * no credential read, features ONLY the free local-first workflows. It is a
+ * chooser, not an agent: no text input, no model call, nothing uploaded.
+ */
+export interface InitTuiDetection {
+    detected: boolean;
+    sessionCount: number;
+    projectsDir: string;
+}
+export type InitTuiResult = {
+    action: "select";
+    card: WorkflowCard;
+} | {
+    action: "quit";
+};
+interface AppProps {
+    version: string;
+    detection: InitTuiDetection;
+    onDone: (result: InitTuiResult) => void;
+}
+export declare function App({ version, detection, onDone }: AppProps): React.ReactElement;
+/**
+ * Render the TUI and resolve with the user's choice. Resolves to `{action:"quit"}`
+ * if the user exits without selecting. The caller prints the chosen command to
+ * the scrollback after this resolves.
+ *
+ * Renders into the terminal's ALTERNATE SCREEN BUFFER (like vim/less/fzf): no
+ * scrollback, so a reflow can never push a stale frame up into history. Resize
+ * redraw is handled INSIDE the component (reactive terminal size → re-render),
+ * so Ink owns the clear/repaint and the screen stays visible across resizes. On
+ * exit the screen is restored and the selected next-command prints normally.
+ */
+export declare function runInitTui(props: {
+    version: string;
+    detection: InitTuiDetection;
+}): Promise<InitTuiResult>;
+export {};