actradeck 0.5.2 → 0.7.0

package/README.md

@@ -1,8 +1,10 @@
 # actradeck
 
-> Bootstrap CLI for **ActraDeck** — a local-first control plane for coding agents (Claude
-> Code, Codex, …): observe them, redact secrets before they're stored, gate high-risk actions
-> behind approvals, and keep a tamper-evident audit trail.
+> Put risky Claude Code and Codex actions back in front of a human.
+
+ActraDeck is a local approval and audit cockpit for coding agents. This package gives you
+a zero-side-effect product preview, diagnoses the machine, and verifies the full product
+before handing off to its quickstart.
 
 This package is a **thin, dependency-free bootstrapper**. It does not contain the product —
 the full four-tier stack ships as a **signed GitHub Release** and a **signed GHCR image**.
@@ -14,19 +16,28 @@ The CLI helps you _get to_ a running cockpit and verify what you download.
 - **Fail-closed verification.** `install` checks the release's sha256 checksum _and_ its
   SLSA build provenance before extracting a single file.
 
+## See the safety story first
+
+```sh
+npx actradeck@latest demo
+```
+
+`demo` prints a five-second **synthetic preview** of detect → hold → deny → redact →
+record. It executes no command, writes no file, starts no subprocess, and makes no network
+request. The output then points to the cockpit's 30-second demo, which exercises the real
+ingestion, redaction, projection, and audit pipeline.
+
 ## Usage
 
 ```sh
+npx actradeck@latest demo          # safe synthetic preview; no side effects or network
 npx actradeck@latest doctor        # diagnose: platform / Node / pnpm / git / Docker (offline-safe)
 npx actradeck@latest install       # verify + fetch the latest signed release, then quickstart
 npx actradeck@latest up            # print the Docker cockpit command (prints only; runs nothing)
 npx actradeck@latest version       # your CLI version + whether a newer stable release exists
+npx actradeck@latest conformance < events.jsonl   # check an adapter's stream vs the contract
 ```
 
-> **Not published yet.** The first npm publish is planned for **v0.5** (see the project's ADR
-> 0013). Until then the commands above describe the intended flow; the canonical, already-signed
-> way to get ActraDeck is the GitHub Release / GHCR image or `scripts/install.sh` from the repo.
-
 ### `install`
 
 Resolves the latest stable GitHub Release (or `--version vX.Y.Z`), downloads the source
@@ -35,7 +46,7 @@ provenance (`gh attestation verify`), then extracts and hands off to the repo's
 `scripts/quickstart`.
 
 ```sh
-npx actradeck@latest install --version v0.4.0     # a specific tag
+npx actradeck@latest install --version v0.7.0     # a specific tag
 npx actradeck@latest install --dry-run            # resolve + verify only; change nothing
 npx actradeck@latest install --skip-provenance    # explicit opt-out (checksum still enforced)
 ```
@@ -45,12 +56,39 @@ and provenance is verified unless you pass `--skip-provenance` (which requires y
 the reduced guarantee). `--skip-provenance` exists only for machines that cannot install the
 GitHub CLI.
 
+### `conformance`
+
+Validate that a third-party ingestion adapter's event stream satisfies the ActraDeck ingestion
+contract — **without cloning the monorepo**. Capture your adapter's emitted NormalizedEvents as
+**JSONL** (one JSON object per line, in emission order) and pipe them in:
+
+```sh
+npx actradeck@latest conformance < events.jsonl      # read JSONL from stdin
+npx actradeck@latest conformance events.jsonl        # or from a file
+npx actradeck@latest conformance events.jsonl --json # machine-readable JSON report
+```
+
+It checks the stream-level and cross-field invariants a single-event schema parse cannot see:
+every event parses as a NormalizedEvent; `payload.kind === event_type`; per-session `timestamp` is
+non-decreasing; and per-session `seq`, when present, is a dense 0-based counter (so the backend can
+detect silent mid-stream drops — a session that emits no `seq` is a **warning**, not an error). A
+repeated `event_id` or `seq` is a **warning**, not an error — an at-least-once retry is legitimate
+and the backend dedupes it (§3.3 / §4.4). Redaction is **not** checked: the backend ingress
+redaction floor is the sole redaction point, so an adapter cannot and need not prove it.
+
+**Exit codes:** `0` = conformant (warnings allowed) · `1` = one or more errors · `2` = usage /
+input error. The checker core is ActraDeck's canonical `checkConformance`, bundled into this CLI at
+build time — the published package still has **zero runtime dependencies**. It is the same check as
+the in-repo `scripts/check-conformance.mjs` (see `docs/ingestion-contract.md` §8); for piped output
+it is byte-identical (an interactive TTY differs only in ANSI color). The input is read fully into
+memory, which suits adapter sample streams rather than an unbounded live feed.
+
 ## Environment
 
-| Variable                | Default              | Meaning                                             |
-| ----------------------- | -------------------- | --------------------------------------------------- |
-| `ACTRADECK_REPO`        | `actradeck/actradeck`| `owner/name` (or git URL) to resolve releases from  |
-| `ACTRADECK_INSTALL_DIR` | `~/actradeck`        | where `install` extracts the verified source        |
+| Variable                | Default               | Meaning                                            |
+| ----------------------- | --------------------- | -------------------------------------------------- |
+| `ACTRADECK_REPO`        | `actradeck/actradeck` | `owner/name` (or git URL) to resolve releases from |
+| `ACTRADECK_INSTALL_DIR` | `~/actradeck`         | where `install` extracts the verified source       |
 
 ## License
 

package/dist/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,41 @@
+ActraDeck CLI — third-party notices for code bundled into dist/lib/conformance-core.js.
+The `conformance` command inlines the checker's dependency closure at build time; the
+licenses of those bundled packages follow.
+
+==============================================================================
+uuid@11.1.1  (MIT)
+==============================================================================
+The MIT License (MIT)
+
+Copyright (c) 2010-2020 Robert Kieffer and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+==============================================================================
+zod@4.4.3  (MIT)
+==============================================================================
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.d.ts

@@ -1,4 +1,6 @@
 import type { Deps } from "./lib/types.js";
 import { type InstallOpts } from "./commands/install.js";
+import { type ConformanceOpts } from "./commands/conformance.js";
 export declare function parseInstallOpts(args: string[]): InstallOpts;
+export declare function parseConformanceOpts(args: string[]): ConformanceOpts;
 export declare function run(deps: Deps, argv: string[]): Promise<number>;

package/dist/cli.js

@@ -2,12 +2,15 @@ import { cmdDoctor } from "./commands/doctor.js";
 import { cmdUp } from "./commands/up.js";
 import { cmdVersion } from "./commands/version.js";
 import { cmdInstall } from "./commands/install.js";
-const USAGE = `actradeck — bootstrap CLI for ActraDeck (local-first control plane for coding agents)
+import { cmdConformance } from "./commands/conformance.js";
+import { cmdDemo } from "./commands/demo.js";
+const USAGE = `actradeck — put risky coding-agent actions back in front of a human
 
 Usage:
   actradeck <command> [options]
 
 Commands:
+  demo        Show a 5-second safety preview. No install, files, subprocesses, or network.
   doctor      Diagnose this machine (platform / Node / pnpm / git / Docker). Offline-safe.
   install     Fetch + VERIFY a signed release (checksum + provenance), then hand off to quickstart.
               --version vX.Y.Z   install a specific release tag (default: latest stable)
@@ -15,6 +18,10 @@ Commands:
               --skip-provenance  checksum-only (explicit opt-out; not recommended)
   up          Print the Docker cockpit bring-up command (prints only — does not run it).
   version     Print this CLI's version and whether a newer stable release is available.
+  conformance Validate an adapter's JSONL event stream against the ingestion contract.
+              [file]   read JSONL from a file (default: stdin)
+              --json   emit a machine-readable JSON report instead of the summary
+              Exit: 0 = conformant · 1 = one or more errors · 2 = usage/setup error.
 
 Global:
   -h, --help      show this help
@@ -53,6 +60,11 @@ export function parseInstallOpts(args) {
     }
     return { version, dryRun, skipProvenance };
 }
+export function parseConformanceOpts(args) {
+    const json = args.includes("--json");
+    const file = args.find((a) => !a.startsWith("--"));
+    return file !== undefined ? { file, json } : { json };
+}
 export async function run(deps, argv) {
     const cmd = argv[0];
     const rest = argv.slice(1);
@@ -70,12 +82,16 @@ export async function run(deps, argv) {
                 return 0;
             case "doctor":
                 return await cmdDoctor(deps);
+            case "demo":
+                return await cmdDemo(deps);
             case "up":
                 return await cmdUp(deps);
             case "version":
                 return await cmdVersion(deps);
             case "install":
                 return await cmdInstall(deps, parseInstallOpts(rest));
+            case "conformance":
+                return await cmdConformance(deps, parseConformanceOpts(rest));
             default:
                 deps.io.err(`Unknown command: ${cmd}`);
                 deps.io.out(USAGE);

package/dist/commands/conformance.d.ts

@@ -0,0 +1,8 @@
+import type { Deps } from "../lib/types.js";
+import type { ConformanceReport } from "../lib/conformance-types.js";
+export interface ConformanceOpts {
+    file?: string;
+    json: boolean;
+}
+export declare function cmdConformance(deps: Deps, opts: ConformanceOpts): Promise<number>;
+export declare function renderHuman(report: ConformanceReport, malformed: Map<number, string>): string[];

package/dist/commands/conformance.js

@@ -0,0 +1,57 @@
+export async function cmdConformance(deps, opts) {
+    let raw;
+    try {
+        raw = await deps.readInput(opts.file);
+    }
+    catch (err) {
+        const code = err.code ?? (err instanceof Error ? err.message : String(err));
+        deps.io.err(`conformance: could not read input (${code})`);
+        return 2;
+    }
+    const events = [];
+    const malformed = new Map();
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const index = events.length;
+        try {
+            events.push(JSON.parse(trimmed));
+        }
+        catch (err) {
+            malformed.set(index, err instanceof Error ? err.message : String(err));
+            events.push({});
+        }
+    }
+    const report = await deps.checkConformance(events);
+    if (opts.json) {
+        deps.io.out(JSON.stringify(report, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    for (const line of renderHuman(report, malformed))
+        deps.io.out(line);
+    return report.ok ? 0 : 1;
+}
+export function renderHuman(report, malformed) {
+    const lines = [];
+    lines.push(`conformance: ${report.total} events · ${report.schemaValid} schema-valid · ${report.sessions} session(s)`);
+    for (const f of report.findings)
+        lines.push(findingLine(f, malformed));
+    if (report.ok) {
+        const suffix = report.warnings > 0 ? ` (${report.warnings} warning(s))` : "";
+        lines.push(`PASS — the stream conforms to the ingestion contract${suffix}`);
+    }
+    else {
+        lines.push(`FAIL — ${report.errors} error(s), ${report.warnings} warning(s)`);
+    }
+    return lines;
+}
+function findingLine(f, malformed) {
+    const where = f.index >= 0 ? `event ${f.index}` : "stream";
+    const sess = f.sessionId ? ` [session ${f.sessionId}]` : "";
+    const message = f.rule === "schema" && malformed.has(f.index)
+        ? `not valid JSON: ${malformed.get(f.index)}`
+        : f.message;
+    const tag = f.severity === "error" ? "ERROR" : "WARN";
+    return `  ${tag} ${where}${sess} (${f.rule}): ${message}`;
+}

package/dist/commands/demo.d.ts

@@ -0,0 +1,2 @@
+import type { Deps } from "../lib/types.js";
+export declare function cmdDemo(deps: Deps): Promise<number>;

package/dist/commands/demo.js

@@ -0,0 +1,28 @@
+export async function cmdDemo(deps) {
+    deps.io.out(`ActraDeck safety preview
+
+SAFE SIMULATION — no command is executed, no file is changed, and no network call is made.
+
+Claude Code requests:
+  rm -rf ./important-directory
+
+[HIGH RISK] recursive filesystem delete detected
+[HELD]      waiting for a human decision
+[DENIED]    no approval received; safe-side timeout
+
+Agent output contains:
+  GITHUB_TOKEN=[REDACTED:github-token]
+
+[RECORDED]  decision + redacted event added to the replayable audit trail
+
+That is ActraDeck's first job: put risky coding-agent actions back in front of you.
+
+Try the real ingestion -> approval -> redaction -> audit pipeline:
+  docker run --rm -p 127.0.0.1:55400:55400 -v actradeck_pgdata:/data \\
+    ghcr.io/actradeck/actradeck:latest
+  then open http://localhost:55400 and click "Run the 30-second safety demo".
+
+Detection is best-effort, not a sandbox. Read the documented limits:
+  https://github.com/actradeck/actradeck/blob/main/SECURITY.md`);
+    return 0;
+}