@compaction/cli 0.1.4 → 0.3.0

package/dist/cli/cursor-live-preflight.js

@@ -0,0 +1,46 @@
+/**
+ * CLI glue for the Cursor live-prep preflight. Surfaced before a LIVE `run cursor` / `capture cursor`
+ * (no `--export`) so the operator gets a content-free readiness check + exact guidance instead of an
+ * opaque "Authentication required" / missing-CLI failure.
+ *
+ * SAFETY (inherited from the core module): CLI-presence + capability probes ONLY (`--help`), never a
+ * real `-p` prompt, never `cursor agent login`, never a CURSOR_API_KEY read. Fail-friendly.
+ *
+ * The gate is advisory-by-readiness: if the CLI is missing or not capable, the live run cannot succeed,
+ * so we print guidance and DECLINE to spawn (returns false). If CLI+capability are present, auth is the
+ * only remaining unknown — we cannot detect it safely, so we print a short auth reminder and PROCEED
+ * (returns true); if the real run then fails auth, the wrapper's post-run guidance points back here.
+ */
+import chalk from "chalk";
+import { runCursorPreflight } from "../core/cursor-preflight.js";
+import { createSafeCursorProbe } from "../core/cursor-preflight-probe.js";
+/**
+ * Run the preflight (safe probes) and return the report. Never throws.
+ *
+ * `COMPACTION_CURSOR_BIN` (optional): when set to a non-empty path, it is used as the SOLE candidate the
+ * safe probe checks — instead of the default PATH names + the hardcoded macOS app path. This is (a) a real
+ * operator override for a non-standard Cursor CLI location, and (b) what makes this path deterministic in
+ * tests: pointing it at a non-existent binary makes the probe fail fast (ENOENT) so the CLI never spawns
+ * the real, possibly-hanging Cursor binary. Still a `--help`/`-v` capability probe only — never `-p`,
+ * never `login`, never a key read.
+ */
+export async function cursorLivePreflight() {
+    const override = process.env.COMPACTION_CURSOR_BIN?.trim();
+    return runCursorPreflight(createSafeCursorProbe(), override ? [override] : undefined);
+}
+/**
+ * Print the preflight guidance and decide whether the live run may proceed.
+ * - CLI not resolvable OR capability absent → print guidance, return false (do NOT spawn a live run).
+ * - CLI present + capable → print the auth reminder, return true (proceed; auth verified only by a real
+ *   run the operator has authorized).
+ */
+export async function gateCursorLiveRun() {
+    const report = await cursorLivePreflight();
+    for (const line of report.guidance)
+        console.log(report.ready ? line : chalk.yellow(line));
+    if (!report.ready) {
+        console.log(chalk.yellow("  Live Cursor run not started: fix the above, then retry. (Or use --export <saved output> to process a saved run offline.)"));
+    }
+    return report.ready;
+}
+//# sourceMappingURL=cursor-live-preflight.js.map

package/dist/cli/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { registerAnalyzeCommand } from "./commands/analyze.js";
+import { registerActivityCommand } from "./commands/activity.js";
 import { registerAdapterCommand } from "./commands/adapter.js";
 import { registerAggregateCommand } from "./commands/aggregate.js";
 import { registerAuditCommand } from "./commands/audit.js";
@@ -11,23 +12,43 @@ import { registerBillingDeltaCommand } from "./commands/billing-delta.js";
 import { registerInitCommand } from "./commands/init.js";
 import { registerCaptureCommand } from "./commands/capture.js";
 import { registerCompactCommand } from "./commands/compact.js";
+import { registerContextCommand } from "./commands/context.js";
 import { registerEvalCommand } from "./commands/eval.js";
+import { registerDevCommand } from "./commands/dev.js";
 import { registerExportSessionSeedCommand } from "./commands/export-session-seed.js";
 import { registerFeedbackCommand } from "./commands/feedback.js";
+import { registerGatewayCommand } from "./commands/gateway.js";
+import { registerHooksCommand } from "./commands/hooks.js";
 import { registerImportCommand } from "./commands/import.js";
+import { registerInputCompactionAbCommand } from "./commands/input-compaction-ab.js";
 import { registerIntegrationsCommand } from "./commands/integrations.js";
 import { registerLaunchTreatmentSessionCommand } from "./commands/launch-treatment-session.js";
 import { registerOptimizeCommand } from "./commands/optimize.js";
 import { registerRecommendCommand } from "./commands/recommend.js";
 import { registerReviewCommand } from "./commands/review.js";
+import { registerOutputShapingCommand } from "./commands/output-shaping.js";
+import { registerOutputShapingAbCommand } from "./commands/output-shaping-ab.js";
+import { registerPoliciesCommand } from "./commands/policies.js";
+import { registerPrecallCommand } from "./commands/precall.js";
 import { registerRunCommand } from "./commands/run.js";
 import { registerSpendCommand } from "./commands/spend.js";
 import { registerSummaryCommand } from "./commands/summary.js";
+import { registerUpgradeCommand, registerStatusCommand } from "./commands/upgrade-status.js";
+import { compactMarkFor } from "./terminal-logo.js";
 const program = new Command();
 program
     .name("compaction")
     .description("CLI-first trace compaction tools for AI agent workflows.")
-    .version("0.1.4");
+    .version("0.3.0");
+// Brand mark above the TOP-LEVEL help only (compaction --help / bare `compaction`).
+// Derived rendering of apps/web/src/assets/compaction-mark.svg — see
+// docs/brand/terminal-logo.md. Colored only on a TTY with NO_COLOR unset; plain
+// glyphs otherwise. Adds three lines before "Usage:"; no command output,
+// subcommand help, exit code, or --version behavior changes.
+program.addHelpText("before", ({ error }) => {
+    return `${compactMarkFor(error ? process.stderr : process.stdout)}\n`;
+});
+registerActivityCommand(program);
 registerAnalyzeCommand(program);
 registerAdapterCommand(program);
 registerAggregateCommand(program);
@@ -39,18 +60,29 @@ registerBillingDeltaCommand(program);
 registerInitCommand(program);
 registerCaptureCommand(program);
 registerCompactCommand(program);
+registerContextCommand(program);
 registerEvalCommand(program);
+registerDevCommand(program);
 registerExportSessionSeedCommand(program);
 registerFeedbackCommand(program);
+registerGatewayCommand(program);
+registerHooksCommand(program);
 registerImportCommand(program);
+registerInputCompactionAbCommand(program);
 registerIntegrationsCommand(program);
 registerLaunchTreatmentSessionCommand(program);
 registerOptimizeCommand(program);
+registerOutputShapingCommand(program);
+registerOutputShapingAbCommand(program);
+registerPoliciesCommand(program);
+registerPrecallCommand(program);
 registerRecommendCommand(program);
 registerReviewCommand(program);
 registerRunCommand(program);
 registerSpendCommand(program);
 registerSummaryCommand(program);
+registerUpgradeCommand(program);
+registerStatusCommand(program);
 // Clean default `--help` surface (v0.1.2): show ONLY the free, local-first commands
 // that work without the private engine / Compaction API. Everything else (engine-gated,
 // API-adjacent, and internal/operator commands) is HIDDEN from the top-level command
@@ -62,10 +94,15 @@ const PUBLIC_COMMANDS = new Set([
     "capture",
     "import",
     "analyze",
+    "context",
     "spend",
     "summary",
     "aggregate",
-    "feedback"
+    "feedback",
+    "activity",
+    "policies",
+    "upgrade",
+    "status"
 ]);
 for (const cmd of program.commands) {
     if (cmd.name() === "help" || PUBLIC_COMMANDS.has(cmd.name()))

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

@@ -0,0 +1,33 @@
+import React from "react";
+/** The deterministic apply policy the TUI can arm (run-17.2). Deterministic only — no LCM, no semantics. */
+export declare const GATEWAY_APPLY_POLICY = "deterministic-dedupe";
+export interface GatewayTuiConfig {
+    provider: string;
+    upstream: string;
+    listen: string;
+    /** record is the byte-safe default; `apply` is the EXPERIMENTAL deterministic mode (explicit opt-in only). */
+    mode: "record" | "apply";
+    /** Present only when mode is `apply`. */
+    policy?: string;
+}
+export type GatewayTuiResult = {
+    action: "dev";
+    config: GatewayTuiConfig;
+} | {
+    action: "configure";
+    config: GatewayTuiConfig;
+} | {
+    action: "start";
+    config: GatewayTuiConfig;
+} | {
+    action: "back";
+} | {
+    action: "quit";
+};
+interface GatewayAppProps {
+    onDone: (result: GatewayTuiResult) => void;
+}
+export declare function GatewayApp({ onDone }: GatewayAppProps): React.ReactElement;
+/** Render the gateway setup TUI and resolve with the user's choice (same alt-screen pattern as runInitTui). */
+export declare function runGatewayTui(): Promise<GatewayTuiResult>;
+export {};

package/dist/cli/onboarding/GatewayTui.js

@@ -0,0 +1,113 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Box, Text, useApp, useInput, render } from "ink";
+import { BRAND_HEX, GATEWAY_PROVIDERS, GATEWAY_MODES, GATEWAY_DEFAULT_LISTEN } from "./model.js";
+/**
+ * Guided Gateway setup TUI (charter run-17) — a SIBLING of the init chooser (`InitTui`), reusing the
+ * same Ink/React stack (no new dependency). Selecting the "Gateway setup" card in `compaction` (or
+ * `compaction init`) opens this. Preferred flow: Provider (OpenAI) → Mode (Record) → Start local gateway
+ * → the caller starts the gateway (foreground) and its receipts show live.
+ *
+ * Invariants (same spirit as InitTui): no text input, no network call here, no credential read. It is a
+ * configurator that resolves a validated config; the caller starts the real gateway. Raw flags (custom
+ * upstream / listen address / manual baseURL) live under "Advanced" — copy-and-run, never typed here.
+ */
+const BLUE = BRAND_HEX;
+const DIM = "gray";
+/** The deterministic apply policy the TUI can arm (run-17.2). Deterministic only — no LCM, no semantics. */
+export const GATEWAY_APPLY_POLICY = "deterministic-dedupe";
+// The routing step (charter run-17.1): after Provider + Mode, "How do you want to route traffic?".
+// Option 1 (run a command through Compaction) is the preferred, no-copy path.
+const MENU = [
+    { key: "dev", label: "Run a command through the Gateway  (preferred — no baseURL copy)" },
+    { key: "configure", label: "Configure this project  (approval-gated; shows a diff first)" },
+    { key: "start", label: "Start the gateway now  (I'll point my client at it)" },
+    { key: "advanced", label: "Show manual / advanced setup" },
+    { key: "back", label: "Back to workflows" }
+];
+export function GatewayApp({ onDone }) {
+    const [index, setIndex] = useState(0);
+    const [showAdvanced, setShowAdvanced] = useState(false);
+    // Experimental deterministic APPLY. Off by default. Arming ('x') shows the risk boundary; apply only
+    // engages after an EXPLICIT confirm ('y'). Without the confirm, the started gateway stays in record mode.
+    const [applyArmed, setApplyArmed] = useState(false);
+    const [applyConfirmed, setApplyConfirmed] = useState(false);
+    const { exit } = useApp();
+    const provider = GATEWAY_PROVIDERS[0]; // OpenAI (the only available provider today)
+    const applyOn = applyArmed && applyConfirmed;
+    const config = {
+        provider: provider.key,
+        upstream: provider.upstream,
+        listen: GATEWAY_DEFAULT_LISTEN,
+        mode: applyOn ? "apply" : "record",
+        ...(applyOn ? { policy: GATEWAY_APPLY_POLICY } : {})
+    };
+    const choose = (key) => {
+        if (key === "dev")
+            onDone({ action: "dev", config });
+        else if (key === "configure")
+            onDone({ action: "configure", config });
+        else if (key === "start")
+            onDone({ action: "start", config });
+        else if (key === "back")
+            onDone({ action: "back" });
+        else {
+            setShowAdvanced((a) => !a);
+            return; // Advanced toggles in place; it does not exit
+        }
+        exit();
+    };
+    useInput((input, key) => {
+        if (key.upArrow || input === "k")
+            setIndex((i) => (i - 1 + MENU.length) % MENU.length);
+        else if (key.downArrow || input === "j")
+            setIndex((i) => (i + 1) % MENU.length);
+        else if (key.return)
+            choose(MENU[index].key);
+        else if (input === "a")
+            choose("advanced");
+        else if (input === "x") {
+            // Toggle the experimental apply arm; disarming always clears the confirmation (fail safe).
+            setApplyArmed((a) => {
+                if (a)
+                    setApplyConfirmed(false);
+                return !a;
+            });
+        }
+        else if (input === "y") {
+            // Explicit confirmation ONLY matters while armed; it never silently enables apply otherwise.
+            setApplyConfirmed((c) => (applyArmed ? true : c));
+        }
+        else if (input === "q") {
+            onDone({ action: "quit" });
+            exit();
+        }
+        else if (key.escape) {
+            onDone({ action: "back" });
+            exit();
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", paddingLeft: 1, paddingTop: 1, children: [_jsx(Text, { color: BLUE, bold: true, children: "\u258C GATEWAY SETUP" }), _jsx(Text, { color: DIM, children: "A local, byte-safe proxy for your model traffic. Content-free receipts; your key never leaves the client." }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: DIM, children: "  Provider   " }), _jsx(Text, { color: "white", children: provider.label }), _jsx(Text, { color: BLUE, children: "  ✓" })] }), _jsx(Box, { flexDirection: "column", children: GATEWAY_MODES.map((m, i) => (_jsxs(Box, { children: [_jsx(Text, { color: DIM, children: i === 0 ? "  Mode       " : "             " }), m.available ? (_jsxs(Text, { color: "white", children: [m.label, _jsx(Text, { color: BLUE, children: "  ✓" })] })) : (_jsx(Text, { color: DIM, children: m.label }))] }, m.key))) }), _jsxs(Box, { children: [_jsx(Text, { color: DIM, children: "  Listen     " }), _jsx(Text, { color: "white", children: GATEWAY_DEFAULT_LISTEN })] }), _jsxs(Box, { children: [_jsx(Text, { color: DIM, children: "  Active     " }), applyOn ? (_jsx(Text, { color: "yellow", children: "APPLY \u00B7 experimental \u00B7 deterministic-dedupe (original retained locally)" })) : (_jsx(Text, { color: "white", children: "RECORD \u00B7 byte-safe, no mutation" }))] })] }), _jsx(Box, { marginTop: 1, flexDirection: "column", children: !applyArmed ? (_jsx(Text, { color: DIM, children: "  x  arm experimental deterministic apply (off by default; explicit confirm required)" })) : (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "yellow", bold: true, children: "  ⚠ Experimental: deterministic APPLY" }), _jsx(Text, { color: DIM, children: "  Changes model-visible input for KNOWN-SAFE shapes only (removes exact-duplicate large blocks)." }), _jsx(Text, { color: DIM, children: "  Deterministic only \u2014 no summarization, no LCM. The ORIGINAL request is retained locally." }), _jsx(Text, { color: DIM, children: "  Unknown/complex shapes FAIL CLOSED (forwarded unchanged). System/developer & tool schemas are never touched." }), applyConfirmed ? (_jsx(Text, { color: "yellow", children: "  ✓ apply confirmed — 'Start the gateway now' will run APPLY mode.   (x to disarm)" })) : (_jsx(Text, { color: "yellow", children: "  press y to CONFIRM apply mode, or x to cancel   (without confirmation the gateway starts in RECORD mode)" }))] })) }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "white", children: "How do you want to route traffic?" }) }), _jsx(Box, { flexDirection: "column", children: MENU.map((m, i) => (_jsxs(Box, { children: [_jsx(Text, { color: i === index ? BLUE : DIM, children: i === index ? "  ▌ " : "  ○ " }), _jsx(Text, { color: i === index ? "white" : DIM, children: m.label })] }, m.key))) }), showAdvanced ? (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: DIM, children: "Advanced \u2014 for a custom provider, upstream, or port, start the gateway directly:" }), _jsx(Text, { color: BLUE, children: `  compaction gateway start --provider openai --upstream ${provider.upstream} --listen ${GATEWAY_DEFAULT_LISTEN}` }), _jsx(Text, { color: DIM, children: "Then point your OpenAI client's baseURL at the listen address + /v1." }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: DIM, children: "Already running an app? Compaction cannot safely attach to an already-running process" }), _jsx(Text, { color: DIM, children: "unless it already points at the gateway. Restart it through Compaction to route future calls:" }), _jsx(Text, { color: BLUE, children: "  compaction gateway run -- <your command>" })] })] })) : null, _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: DIM, children: "↑/↓ move   ·   Enter select   ·   a advanced   ·   x/y experimental apply   ·   Esc back   ·   q quit" }) })] }));
+}
+const ALT_SCREEN_ENTER = "[?1049h[H[2J";
+const ALT_SCREEN_LEAVE = "[?1049l";
+/** Render the gateway setup TUI and resolve with the user's choice (same alt-screen pattern as runInitTui). */
+export async function runGatewayTui() {
+    const out = process.stdout;
+    const useAlt = Boolean(out.isTTY);
+    if (useAlt)
+        out.write(ALT_SCREEN_ENTER);
+    let result = { action: "quit" };
+    try {
+        const app = render(_jsx(GatewayApp, { onDone: (r) => {
+                result = r;
+            } }));
+        await app.waitUntilExit();
+    }
+    finally {
+        if (useAlt)
+            out.write(ALT_SCREEN_LEAVE);
+    }
+    return result;
+}
+//# sourceMappingURL=GatewayTui.js.map

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

@@ -26,7 +26,38 @@ export interface WorkflowCard {
 }
 export declare const PRIMARY: WorkflowCard;
 export declare const SECONDARY: WorkflowCard[];
-/** All workflow cards, primary first — the order shown in the TUI chooser. */
+/**
+ * The Gateway setup card (charter run-17). SPECIAL: selecting it opens the guided gateway setup flow
+ * (`GatewayTui`) rather than printing a copy-paste command — the caller routes on `key === "gateway"`.
+ * It is a FREE, local-first workflow (a localhost byte-safe proxy; no Compaction server sees content;
+ * the provider key rides through to the provider and is never stored). Kept in the shared model so both
+ * onboarding surfaces list it.
+ */
+export declare const GATEWAY_CARD: WorkflowCard;
+/** Gateway providers offered in the guided flow. OpenAI-compatible only today (record mode). */
+export declare const GATEWAY_PROVIDERS: readonly [{
+    readonly key: "openai";
+    readonly label: "OpenAI (openai-compatible)";
+    readonly upstream: "https://api.openai.com/v1";
+    readonly available: true;
+}];
+/** Gateway modes. Run-15/16 ship RECORD only; cache/apply are later, separately-gated runs (shown disabled). */
+export declare const GATEWAY_MODES: readonly [{
+    readonly key: "record";
+    readonly label: "Record — byte-safe; content-free receipts";
+    readonly available: true;
+}, {
+    readonly key: "cache";
+    readonly label: "Cache — coming soon";
+    readonly available: false;
+}, {
+    readonly key: "apply";
+    readonly label: "Apply — coming soon";
+    readonly available: false;
+}];
+/** The default local listen address surfaced by the guided flow (editable only via Advanced CLI flags). */
+export declare const GATEWAY_DEFAULT_LISTEN = "http://127.0.0.1:8787";
+/** All workflow cards, primary first — the order shown in the TUI chooser. Gateway is featured second. */
 export declare const WORKFLOW_CARDS: WorkflowCard[];
 /** Lookup a card by key (used by `--path` focus and TUI selection). */
 export declare function findWorkflow(key: string): WorkflowCard | undefined;

package/dist/cli/onboarding/model.js

@@ -47,8 +47,33 @@ export const SECONDARY = [
         blurb: "Import any local trace / JSONL you already have."
     }
 ];
-/** All workflow cards, primary first — the order shown in the TUI chooser. */
-export const WORKFLOW_CARDS = [PRIMARY, ...SECONDARY];
+/**
+ * The Gateway setup card (charter run-17). SPECIAL: selecting it opens the guided gateway setup flow
+ * (`GatewayTui`) rather than printing a copy-paste command — the caller routes on `key === "gateway"`.
+ * It is a FREE, local-first workflow (a localhost byte-safe proxy; no Compaction server sees content;
+ * the provider key rides through to the provider and is never stored). Kept in the shared model so both
+ * onboarding surfaces list it.
+ */
+export const GATEWAY_CARD = {
+    key: "gateway",
+    title: "Gateway setup",
+    command: "compaction gateway start",
+    blurb: "Run the local Compaction Gateway — byte-safe proxy; content-free token/cache receipts."
+};
+/** Gateway providers offered in the guided flow. OpenAI-compatible only today (record mode). */
+export const GATEWAY_PROVIDERS = [
+    { key: "openai", label: "OpenAI (openai-compatible)", upstream: "https://api.openai.com/v1", available: true }
+];
+/** Gateway modes. Run-15/16 ship RECORD only; cache/apply are later, separately-gated runs (shown disabled). */
+export const GATEWAY_MODES = [
+    { key: "record", label: "Record — byte-safe; content-free receipts", available: true },
+    { key: "cache", label: "Cache — coming soon", available: false },
+    { key: "apply", label: "Apply — coming soon", available: false }
+];
+/** The default local listen address surfaced by the guided flow (editable only via Advanced CLI flags). */
+export const GATEWAY_DEFAULT_LISTEN = "http://127.0.0.1:8787";
+/** All workflow cards, primary first — the order shown in the TUI chooser. Gateway is featured second. */
+export const WORKFLOW_CARDS = [PRIMARY, GATEWAY_CARD, ...SECONDARY];
 /** Lookup a card by key (used by `--path` focus and TUI selection). */
 export function findWorkflow(key) {
     return WORKFLOW_CARDS.find((c) => c.key === key);

package/dist/cli/terminal-logo.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Compact terminal brand mark for CLI headers.
+ *
+ * MIRROR of the canonical strings in `scripts/render-terminal-logo.mjs` (the
+ * single design source for the terminal mark). This mirror exists because
+ * TypeScript cannot import from scripts/ (tsconfig rootDir is src/) and
+ * scripts/ is not packaged into dist/. `tests/cli/terminal-logo.test.ts`
+ * enforces byte-equality between this module and the script, so the two
+ * cannot drift — change the script first, then this mirror.
+ *
+ * Derivation (see docs/brand/terminal-logo.md): the mark is a derived
+ * rendering of `apps/web/src/assets/compaction-mark.svg` — three compression
+ * bars (16u / 10u / 16u, middle inset 3u) at 1 SVG unit = 1 column, one
+ * U+2580 UPPER HALF BLOCK row per bar. The canonical SVG is unchanged.
+ */
+/** Compact lockup, plain (no escape codes). Must byte-match the script's COMPACT_PLAIN. */
+export declare const COMPACT_PLAIN: string;
+/** Brand-blue ramp, identical to src/cli/onboarding/wordmark.ts BLUE_RAMP. */
+export declare const BLUE_RAMP: readonly ["#6d6bff", "#4f46e5", "#3231cd"];
+/** Compact lockup, colored. Must byte-match the script's COMPACT_COLOR. */
+export declare const COMPACT_COLOR: string;
+/**
+ * The compact mark for a help banner on the given stream: colored only when
+ * the stream is a TTY and NO_COLOR is unset (degrades to plain glyphs in
+ * pipes, files, CI, and color-hostile terminals).
+ */
+export declare function compactMarkFor(stream: NodeJS.WriteStream): string;

package/dist/cli/terminal-logo.js

@@ -0,0 +1,49 @@
+/**
+ * Compact terminal brand mark for CLI headers.
+ *
+ * MIRROR of the canonical strings in `scripts/render-terminal-logo.mjs` (the
+ * single design source for the terminal mark). This mirror exists because
+ * TypeScript cannot import from scripts/ (tsconfig rootDir is src/) and
+ * scripts/ is not packaged into dist/. `tests/cli/terminal-logo.test.ts`
+ * enforces byte-equality between this module and the script, so the two
+ * cannot drift — change the script first, then this mirror.
+ *
+ * Derivation (see docs/brand/terminal-logo.md): the mark is a derived
+ * rendering of `apps/web/src/assets/compaction-mark.svg` — three compression
+ * bars (16u / 10u / 16u, middle inset 3u) at 1 SVG unit = 1 column, one
+ * U+2580 UPPER HALF BLOCK row per bar. The canonical SVG is unchanged.
+ */
+const BAR = "▀";
+/** Compact lockup, plain (no escape codes). Must byte-match the script's COMPACT_PLAIN. */
+export const COMPACT_PLAIN = [
+    `${BAR.repeat(16)}`,
+    `   ${BAR.repeat(10)}      compaction`,
+    `${BAR.repeat(16)}`
+].join("\n");
+/** Brand-blue ramp, identical to src/cli/onboarding/wordmark.ts BLUE_RAMP. */
+export const BLUE_RAMP = ["#6d6bff", "#4f46e5", "#3231cd"];
+const RESET = "\u001b[0m";
+const BOLD = "\u001b[1m";
+function fg(hex) {
+    const n = parseInt(hex.slice(1), 16);
+    return `\u001b[38;2;${(n >> 16) & 0xff};${(n >> 8) & 0xff};${n & 0xff}m`;
+}
+/** Compact lockup, colored. Must byte-match the script's COMPACT_COLOR. */
+export const COMPACT_COLOR = COMPACT_PLAIN.split("\n")
+    .map((line, i) => {
+    let out = line.replace(new RegExp(`${BAR}+`), (run) => `${fg(BLUE_RAMP[i])}${run}${RESET}`);
+    if (out.includes("compaction"))
+        out = out.replace("compaction", `${BOLD}compaction${RESET}`);
+    return out;
+})
+    .join("\n");
+/**
+ * The compact mark for a help banner on the given stream: colored only when
+ * the stream is a TTY and NO_COLOR is unset (degrades to plain glyphs in
+ * pipes, files, CI, and color-hostile terminals).
+ */
+export function compactMarkFor(stream) {
+    const useColor = stream.isTTY === true && process.env.NO_COLOR === undefined;
+    return useColor ? COMPACT_COLOR : COMPACT_PLAIN;
+}
+//# sourceMappingURL=terminal-logo.js.map

package/dist/core/activity-event.d.ts

@@ -0,0 +1,107 @@
+import { type CrossSurfaceEvent } from "./cross-surface-event.js";
+/** Founder D-list: whether/how the user approved what Compaction did on this run (exact values). */
+export declare const ACTIVITY_APPROVAL_STATUSES: readonly ["not-required", "asked-approved", "asked-declined", "auto-applied-by-policy", "not-asked"];
+export type ActivityApprovalStatus = (typeof ACTIVITY_APPROVAL_STATUSES)[number];
+/**
+ * The binary auto-apply preference (founder product model: after a first approval, ONE binary
+ * question — default no). `"ask-each-time"` IS the default; `"auto-when-gates-pass"` is only ever
+ * an explicit prior user opt-in. Preference STORAGE is a named residual (no storage exists here).
+ */
+export declare const AUTO_APPLY_PREFERENCES: readonly ["ask-each-time", "auto-when-gates-pass"];
+export type AutoApplyPreference = (typeof AUTO_APPLY_PREFERENCES)[number];
+/** Founder D-list sync status. `local-only` is the default: nothing syncs without explicit config. */
+export declare const ACTIVITY_SYNC_STATUSES: readonly ["local-only", "metrics-synced", "hosted-private"];
+export type ActivitySyncStatus = (typeof ACTIVITY_SYNC_STATUSES)[number];
+export declare const DEFAULT_ACTIVITY_SYNC_STATUS: ActivitySyncStatus;
+/**
+ * The NOT-applied arm — the only arm most events will ever carry. Any preference, any
+ * eligibility, but `applied_automatically` is the LITERAL `false`.
+ */
+export interface AutoApplyNotApplied {
+    /** Whether this run's change would even be a candidate for auto-apply (capability, not consent). */
+    eligible: boolean;
+    /** The user's stored binary preference. Default (and only honest value without stored opt-in): "ask-each-time". */
+    preference: AutoApplyPreference;
+    applied_automatically: false;
+    /** Content-free gate identifiers (e.g. "recoverability-pass"), when gates were evaluated. */
+    gates_passed?: string[];
+    gates_failed?: string[];
+}
+/**
+ * The applied arm. STRUCTURALLY opt-in only: `applied_automatically: true` requires the explicit
+ * `"auto-when-gates-pass"` preference, `eligible: true`, and a NON-EMPTY `gates_passed` tuple.
+ * NOTE: no code in this repo can construct this arm from real behavior — no auto-apply logic
+ * exists; the arm exists so the OFF-by-default rule is a type-system fact, not a convention.
+ */
+export interface AutoApplyApplied {
+    eligible: true;
+    preference: "auto-when-gates-pass";
+    applied_automatically: true;
+    /** Non-empty BY TYPE: an auto-apply with zero passed gates is unrepresentable. */
+    gates_passed: [string, ...string[]];
+    gates_failed?: string[];
+}
+export type ActivityAutoApply = AutoApplyNotApplied | AutoApplyApplied;
+/** Founder D-list recovery: whether the original was retained, and where (path/pointer, NEVER content). */
+export interface ActivityRecovery {
+    original_retained: boolean;
+    /** Content-free location of the retained original (a filesystem path or artifact pointer). */
+    location?: string;
+}
+/** The additive activity fields. ALL optional on the event type (the STORE requires id + sync). */
+export interface ActivityExtension {
+    /** Deterministic content-free id — `act-` + 24 hex chars of sha-256 over the canonical event. */
+    activity_event_id?: string;
+    approval_status?: ActivityApprovalStatus;
+    auto_apply?: ActivityAutoApply;
+    recovery?: ActivityRecovery;
+    /** Default: "local-only" (applied by the store when absent). */
+    sync_status?: ActivitySyncStatus;
+}
+/**
+ * ONE metrics-only activity event = the existing cross-surface event (same arms, same D5/D6
+ * guardrails — the intersection distributes over the union) + the activity fields.
+ */
+export type ActivityEvent = CrossSurfaceEvent & ActivityExtension;
+type Assert<T extends true> = T;
+type AutoApplyAppliedArm = Extract<ActivityAutoApply, {
+    applied_automatically: true;
+}>;
+/** The applied arm exists (so the guards below can never pass vacuously via `never`). */
+export type StructuralGuard_AppliedArmExists = Assert<[AutoApplyAppliedArm] extends [never] ? false : true>;
+/** Auto-apply is opt-in ONLY: the applied arm can only carry the explicit opt-in preference. */
+export type StructuralGuard_AppliedRequiresOptInPreference = Assert<AutoApplyAppliedArm["preference"] extends "auto-when-gates-pass" ? true : false>;
+/** The applied arm requires eligibility. */
+export type StructuralGuard_AppliedRequiresEligible = Assert<AutoApplyAppliedArm["eligible"] extends true ? true : false>;
+/** The applied arm requires a NON-EMPTY gates_passed (an empty tuple is unrepresentable). */
+export type StructuralGuard_AppliedRequiresNonEmptyGates = Assert<AutoApplyAppliedArm["gates_passed"] extends [string, ...string[]] ? true : false>;
+/** "Applied automatically under ask-each-time" is not a representable state at all. */
+export type StructuralGuard_NoAutoApplyUnderAskEachTime = Assert<[
+    Extract<ActivityAutoApply, {
+        applied_automatically: true;
+        preference: "ask-each-time";
+    }>
+] extends [never] ? true : false>;
+export declare const ACTIVITY_EVENT_ID_PATTERN: RegExp;
+/**
+ * Compute the deterministic content-free id: sha-256 over the canonicalized event EXCLUDING any
+ * existing `activity_event_id` (so recomputing on a stored event reproduces the same id). The id
+ * is derived only from the metrics-only fields the event already carries — no randomness, no
+ * clock, no content.
+ */
+export declare function computeActivityEventId(event: CrossSurfaceEvent & ActivityExtension): string;
+export interface ActivityEventValidation {
+    problems: string[];
+}
+/**
+ * Validate one parsed/unknown activity event. Runs the EXISTING cross-surface validator first
+ * (all D5/D6/tier/silent-zero rules stay binding), then the activity rules:
+ * 1. exact enums for approval_status / sync_status / auto_apply.preference;
+ * 2. auto-apply OFF-by-default: applied_automatically=true requires the explicit opt-in
+ *    preference AND eligible=true AND non-empty gates_passed;
+ * 3. recovery.location is a single-line content-free pointer;
+ * 4. activity_event_id matches the deterministic `act-<24 hex>` shape.
+ */
+export declare function validateActivityEvent(value: unknown): ActivityEventValidation;
+export declare function buildMeasureOnlyActivityEvent(event: CrossSurfaceEvent, recovery: ActivityRecovery): ActivityEvent;
+export {};