actradeck 0.5.1 → 0.6.0

package/README.md

@@ -1,8 +1,9 @@
 # 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.
+> Bootstrap CLI for **ActraDeck** — a local-first audit cockpit for coding agents (Claude
+> Code, Codex, …): observe them, redact secrets before they're stored, keep a tamper-evident
+> audit trail, and relay approvals where supported (Claude Code in Attach, Codex in Managed
+> Mode).
 
 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**.
@@ -21,11 +22,15 @@ npx actradeck@latest doctor        # diagnose: platform / Node / pnpm / git / Do
 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   # (next release) 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.
+> **`conformance` is not in the published CLI yet.** The four commands above ship in the current
+> published `actradeck`; `conformance` was added after the latest release and lands in the next
+> tagged one (npm publish is USER-GATED — see ADR 0013). To run the checker today, use the from-clone
+> path in the [ingestion contract §8](../../docs/ingestion-contract.md#8-verify-your-adapter-conformance-checker).
+> The canonical, already-signed way to get the full product is the GitHub Release / GHCR image or
+> `scripts/install.sh`.
 
 ### `install`
 
@@ -45,6 +50,36 @@ 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**. (Ships in the next release; the currently published
+CLI predates it — run the checker from a clone today, see the
+[ingestion contract §8](../../docs/ingestion-contract.md#8-verify-your-adapter-conformance-checker).)
+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                                             |

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,7 +2,8 @@ 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";
+const USAGE = `actradeck — bootstrap CLI for ActraDeck (local-first audit cockpit for coding agents)
 
 Usage:
   actradeck <command> [options]
@@ -15,6 +16,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 +58,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);
@@ -76,6 +86,8 @@ export async function run(deps, argv) {
                 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}`;
+}