@paneui/cli 0.0.9 → 0.0.11

package/dist/commands/participant.js

@@ -1,9 +1,9 @@
-// `pane surface participant <new|revoke>` — mint or invalidate one
-// participant URL on an existing surface. Recovery + leak-containment
-// primitives that together replace the destructive `pane surface delete +
-// pane surface create` workaround for the lost-URL case.
+// `pane participant <new|revoke>` — mint or invalidate one
+// participant URL on an existing pane. Recovery + leak-containment
+// primitives that together replace the destructive `pane delete +
+// pane create` workaround for the lost-URL case.
 //
-// This file is a sub-noun dispatcher under `pane surface`. The surface
+// This file is a sub-noun dispatcher under `pane pane`. The pane
 // dispatcher hands us a ParsedArgs whose positionals[0] is "participant"
 // (our sub-noun marker), so we read the verb from positionals[1] and the
 // args from positionals[2..]. This mirrors the way every other sub-verb
@@ -14,32 +14,32 @@ import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
 const NO_FLAGS = [];
 const NO_BOOLS = [];
-export const participantHelp = `pane surface participant — manage one surface's participant URLs
+export const participantHelp = `pane participant — manage one pane's participant URLs
 
 Participant tokens are stored hashed on the relay and CANNOT be recovered.
 If you lost the create-response (and the URL with it), use 'new' to mint a
-fresh URL — the surface keeps its event log, template pin, and created_at.
-Use 'revoke' to invalidate a single URL while keeping the surface alive.
+fresh URL — the pane keeps its event log, template pin, and created_at.
+Use 'revoke' to invalidate a single URL while keeping the pane alive.
 
 Usage:
-  pane surface participant <verb> <args>
+  pane participant <verb> <args>
 
 Verbs:
-  list <surface-id>           List the participants on one surface, including
+  list <pane-id>           List the participants on one pane, including
                               revoked rows (for audit). Returns
-                              { surface_id, items: [...] } where each item
+                              { pane_id, items: [...] } where each item
                               carries { participant_id, kind, token_prefix,
                               joined_at, revoked_at }. Use this to find the
                               participant_id you need to pass to 'revoke'.
 
-  new <surface-id>            Mint a fresh human URL on an existing surface.
+  new <pane-id>            Mint a fresh human URL on an existing pane.
                               Returns { participant_id, kind, token, url,
                               created_at } — ONCE. The plaintext token is
                               never recoverable; save the response (pipe to
                               a JSONL log) before delivering the URL.
 
-  revoke <surface-id> <participant-id>
-                              Invalidate one participant URL. The surface's
+  revoke <pane-id> <participant-id>
+                              Invalidate one participant URL. The pane's
                               other participants (and the agent's own
                               websocket) are untouched. Idempotent: running
                               revoke twice still returns success.
@@ -54,24 +54,24 @@ Options:
   -h, --help                  Show this help.
 
 Recovery recipe:
-  pane surface list                                       # find surface_id
-  pane surface participant list <surface-id>              # find participant
+  pane list                                       # find pane_id
+  pane participant list <pane-id>              # find participant
                                                           #   ids on that
-                                                          #   surface
-  pane surface participant new <surface-id>               # mint a new URL
-  pane surface participant revoke <surface-id> <p-id>     # invalidate the
+                                                          #   pane
+  pane participant new <pane-id>               # mint a new URL
+  pane participant revoke <pane-id> <p-id>     # invalidate the
                                                           #   old URL
 
 Output: stdout is machine-readable JSON.`;
 async function runParticipantList(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane surface participant list");
-    const surfaceId = args.positionals[1];
-    if (!surfaceId) {
-        fail("missing <surface-id> — usage: pane surface participant list <surface-id>", "invalid_args");
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane participant list");
+    const paneId = args.positionals[1];
+    if (!paneId) {
+        fail("missing <pane-id> — usage: pane participant list <pane-id>", "invalid_args");
     }
     const client = makeClient(args);
     try {
-        const res = await client.listParticipants(surfaceId);
+        const res = await client.listParticipants(paneId);
         printJson(res);
     }
     catch (e) {
@@ -79,14 +79,14 @@ async function runParticipantList(args) {
     }
 }
 async function runParticipantNew(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane surface participant new");
-    const surfaceId = args.positionals[1];
-    if (!surfaceId) {
-        fail("missing <surface-id> — usage: pane surface participant new <surface-id>", "invalid_args");
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane participant new");
+    const paneId = args.positionals[1];
+    if (!paneId) {
+        fail("missing <pane-id> — usage: pane participant new <pane-id>", "invalid_args");
     }
     const client = makeClient(args);
     try {
-        const res = await client.mintParticipant(surfaceId);
+        const res = await client.mintParticipant(paneId);
         printJson(res);
     }
     catch (e) {
@@ -94,17 +94,17 @@ async function runParticipantNew(args) {
     }
 }
 async function runParticipantRevoke(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane surface participant revoke");
-    const surfaceId = args.positionals[1];
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane participant revoke");
+    const paneId = args.positionals[1];
     const participantId = args.positionals[2];
-    if (!surfaceId || !participantId) {
-        fail("missing arguments — usage: pane surface participant revoke <surface-id> <participant-id>", "invalid_args");
+    if (!paneId || !participantId) {
+        fail("missing arguments — usage: pane participant revoke <pane-id> <participant-id>", "invalid_args");
     }
     const client = makeClient(args);
     try {
-        await client.revokeParticipant(surfaceId, participantId);
+        await client.revokeParticipant(paneId, participantId);
         printJson({
-            surface_id: surfaceId,
+            pane_id: paneId,
             participant_id: participantId,
             revoked: true,
         });
@@ -115,7 +115,7 @@ async function runParticipantRevoke(args) {
 }
 export async function runParticipant(args) {
     // positionals[0] is the verb (list | new | revoke), positionals[1..] are
-    // the verb's args. (The surface.ts dispatcher already shifted off the
+    // the verb's args. (The pane.ts dispatcher already shifted off the
     // "participant" marker before calling us.)
     const verb = args.positionals[0];
     switch (verb) {
@@ -129,9 +129,9 @@ export async function runParticipant(args) {
             await runParticipantRevoke(args);
             break;
         case undefined:
-            fail("missing verb — usage: pane surface participant <list|new|revoke> (run 'pane surface participant --help')", "invalid_args");
+            fail("missing verb — usage: pane participant <list|new|revoke> (run 'pane participant --help')", "invalid_args");
             break;
         default:
-            fail(`unknown participant verb '${verb}' — expected list|new|revoke (run 'pane surface participant --help')`, "invalid_args");
+            fail(`unknown participant verb '${verb}' — expected list|new|revoke (run 'pane participant --help')`, "invalid_args");
     }
 }

package/dist/commands/query.js

@@ -0,0 +1,204 @@
+// `pane query` — read-only SQL over the calling agent's scoped data (#355).
+//
+// The whole feature lives on the relay (POST /v1/query). The CLI is a thin
+// shell over @paneui/core's `client.query(sql)`:
+//   1. Read the SQL from args (positional), stdin, or --file.
+//   2. Send it to the relay.
+//   3. Format the result for human or pipe (json | csv | tsv | table),
+//      auto-detecting TTY when --format isn't passed.
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+import { readFileSync } from "node:fs";
+const KNOWN_FLAGS = new Set(["file", "format", "pane", "url", "api-key"]);
+const KNOWN_BOOLS = new Set(["help"]);
+const VALID_FORMATS = new Set(["json", "csv", "tsv", "table"]);
+export const queryHelp = `pane query — run read-only SQL over your scoped data (#355)
+
+Available tables (all rows already scoped to panes you own):
+
+  panes     id, title, template_id, template_version, status,
+            created_at, expires_at, deleted_at, metadata, input_data
+  records   id, pane_id, collection, key, data, version, seq,
+            author_kind, author_id, created_at, updated_at, deleted_at
+  events    id, pane_id, type, ts, author_kind, author_id, data,
+            template_version_id
+
+\`data\` is a JSON column — project with Postgres-style operators:
+  data->>'title'                  text
+  (data->>'done')::boolean        cast
+  data->'nested'->>'inner_field'  deep
+
+Usage:
+  pane query "<SQL>"                    SQL as positional argument
+  pane query --file ./report.sql        read from a file
+  echo "SELECT ..." | pane query        read from stdin
+
+Options:
+  --file <path>       read SQL from a file instead of an argument / stdin
+  --format <fmt>      json | csv | tsv | table  (default: table for TTYs,
+                      json otherwise)
+  --pane <id>         scope the query to a single pane (resolves Phase 2
+                      view_conflict when two of your panes have the same
+                      collection name with different schemas)
+  --url <url>         relay base URL  (overrides PANE_URL)
+  --api-key <key>     agent API key   (overrides PANE_API_KEY)
+  -h, --help          show this help
+
+Limits:
+  - Result is capped at 10,000 rows (response.truncated = true if hit).
+  - Statement timeout: 10 seconds.
+  - SQL: SELECT / WITH / SHOW / DESCRIBE / EXPLAIN / PRAGMA only.
+
+Examples:
+  pane query "SELECT title FROM panes ORDER BY created_at DESC LIMIT 10"
+  pane query "SELECT type, COUNT(*) AS n FROM events GROUP BY 1 ORDER BY n DESC"
+  pane query "SELECT data->>'title' AS title, version
+              FROM records WHERE collection = 'todos' AND deleted_at IS NULL"
+`;
+export async function runQuery(args) {
+    if (args.bools.has("help")) {
+        process.stdout.write(queryHelp + "\n");
+        return;
+    }
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane query");
+    // Decide format. Default depends on TTY-ness of stdout so piping is
+    // never broken by accidentally getting a column-aligned table.
+    let format = args.flags.get("format");
+    if (format === undefined || format === "") {
+        format = process.stdout.isTTY ? "table" : "json";
+    }
+    if (!VALID_FORMATS.has(format)) {
+        fail(`--format must be one of ${[...VALID_FORMATS].join("|")} (got '${format}')`, "invalid_args");
+    }
+    // Source the SQL: --file > positional > stdin (in that order).
+    let sql = null;
+    const file = args.flags.get("file");
+    if (file !== undefined && file !== "") {
+        try {
+            sql = readFileSync(file, "utf8");
+        }
+        catch (e) {
+            fail(`--file '${file}' could not be read: ${e.message}`, "invalid_args");
+        }
+    }
+    else if (args.positionals.length > 0) {
+        sql = args.positionals.join(" ");
+    }
+    else if (!process.stdin.isTTY) {
+        sql = await readAllStdin();
+    }
+    if (sql == null || sql.trim().length === 0) {
+        fail("missing SQL — pass it as the positional argument, --file <path>, or pipe it to stdin", "invalid_args");
+    }
+    const paneId = args.flags.get("pane");
+    if (paneId !== undefined && paneId !== "" && !paneId.startsWith("pan_")) {
+        fail(`--pane must be a pane id (starts with 'pan_'); got '${paneId}'`, "invalid_args");
+    }
+    const client = makeClient(args);
+    let result;
+    try {
+        result = await client.query(sql, paneId !== undefined && paneId !== "" ? { paneId } : {});
+    }
+    catch (e) {
+        failFromError(e);
+        return; // unreachable; failFromError exits
+    }
+    switch (format) {
+        case "json":
+            printJson(result);
+            break;
+        case "csv":
+            writeDelimited(result, ",");
+            break;
+        case "tsv":
+            writeDelimited(result, "\t");
+            break;
+        case "table":
+            writeTable(result);
+            break;
+    }
+}
+async function readAllStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+// --------------------------------------------------------------------------
+// Formatters
+// --------------------------------------------------------------------------
+function writeDelimited(result, sep) {
+    process.stdout.write(result.columns.map((c) => escapeDelimited(sep, c)).join(sep) + "\n");
+    for (const row of result.rows) {
+        process.stdout.write(row
+            .map((c) => escapeDelimited(sep, formatCellForText(c)))
+            .join(sep) + "\n");
+    }
+    if (result.truncated) {
+        process.stderr.write(`[truncated: result capped at ${result.rows.length} rows]\n`);
+    }
+}
+function escapeDelimited(sep, value) {
+    // RFC-4180-ish: quote when the cell contains the delimiter, a quote, or a newline.
+    if (value.includes(sep) ||
+        value.includes('"') ||
+        value.includes("\n") ||
+        value.includes("\r")) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+function writeTable(result) {
+    if (result.columns.length === 0) {
+        process.stdout.write("(no columns)\n");
+        return;
+    }
+    const cells = [];
+    cells.push(result.columns.slice());
+    for (const row of result.rows) {
+        cells.push(row.map((c) => formatCellForText(c)));
+    }
+    // Compute column widths (cap at 80 to keep the table sane for wide JSON).
+    const COL_MAX = 80;
+    const widths = result.columns.map((_, ci) => Math.min(COL_MAX, Math.max(...cells.map((r) => visualWidth(r[ci] ?? "")))));
+    const rule = "─".repeat(widths.reduce((a, b) => a + b, 0) + (widths.length - 1) * 3);
+    // Header
+    process.stdout.write(formatRow(cells[0], widths) + "\n");
+    process.stdout.write(rule + "\n");
+    for (let i = 1; i < cells.length; i++) {
+        process.stdout.write(formatRow(cells[i], widths) + "\n");
+    }
+    process.stderr.write(`\n${result.rows.length} row${result.rows.length === 1 ? "" : "s"}${result.truncated ? " (truncated; cap = 10000)" : ""} · scope: ${result.scope.kind} (${result.scope.pane_count} panes) · ${result.elapsed_ms}ms\n`);
+}
+function formatRow(cells, widths) {
+    return cells
+        .map((c, i) => truncate(c, widths[i] ?? 0).padEnd(widths[i] ?? 0))
+        .join(" │ ");
+}
+function truncate(s, w) {
+    if (visualWidth(s) <= w)
+        return s;
+    return s.slice(0, Math.max(0, w - 1)) + "…";
+}
+function visualWidth(s) {
+    // Strip ANSI / treat as raw text — agents won't be styling SQL output.
+    return s.length;
+}
+function formatCellForText(v) {
+    if (v === null || v === undefined)
+        return "";
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    if (typeof v === "bigint")
+        return v.toString();
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}

package/dist/commands/records.js

@@ -0,0 +1,285 @@
+// `pane records` — CRUD + watch for per-pane mutable record collections
+// (#297). Thin wrapper over the @paneui/core PaneClient + openStream APIs.
+import { assertKnownFlags } from "../argv.js";
+import { makeClient, resolveConfig } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+import { resolveJson } from "../input.js";
+import { openStream } from "@paneui/core";
+// ---------------------------------------------------------------------------
+// Help text
+// ---------------------------------------------------------------------------
+export const recordsHelp = `pane records — CRUD + watch for per-pane record collections
+
+A record is a row in a mutable per-pane collection (posts, comments,
+reactions, etc.) declared by the template's recordSchema. The deep design is
+at https://github.com/aerolalit/paneui/issues/287.
+
+Usage:
+  pane records <verb> [options]
+
+Verbs:
+  list <pane-id> <collection>
+       [--since <seq>] [--limit <n>] [--include-tombstones]
+  get  <pane-id> <collection> <record-key>
+  upsert <pane-id> <collection>
+       --data <path|json> [--key <record-key>]
+  update <pane-id> <collection> <record-key>
+       --data <path|json> [--if-match <version>]
+  delete <pane-id> <collection> <record-key>
+       [--if-match <version>] [--yes]
+  watch  <pane-id>
+       [--collection <name>]... [--since-seq <name>=<n>]...
+
+Output (stdout, JSON-per-line for watch, single JSON for others).
+Errors on stderr: {"error":{"code","message"}} with non-zero exit.`;
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+export async function runRecords(args) {
+    const verb = args.positionals[0];
+    // `pane records --help` (top-level, no verb)
+    if ((verb === undefined || verb === "help") && args.bools.has("help")) {
+        process.stdout.write(recordsHelp + "\n");
+        return;
+    }
+    if (verb === undefined) {
+        fail("missing verb — pane records <list|get|upsert|update|delete|watch>", "invalid_args");
+    }
+    const sub = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (verb) {
+        case "list":
+            return runList(sub);
+        case "get":
+            return runGet(sub);
+        case "upsert":
+            return runUpsert(sub);
+        case "update":
+            return runUpdate(sub);
+        case "delete":
+            return runDelete(sub);
+        case "watch":
+            return runWatch(sub);
+        default:
+            fail(`unknown verb '${verb}' — pane records <list|get|upsert|update|delete|watch>`, "invalid_args");
+    }
+}
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+async function runList(args) {
+    assertKnownFlags(args, ["since", "limit", "url", "api-key"], ["include-tombstones", "help"], "pane records list");
+    const paneId = args.positionals[0];
+    const collection = args.positionals[1];
+    if (!paneId || !collection) {
+        fail("usage: pane records list <pane-id> <collection>", "invalid_args");
+    }
+    const since = parseIntFlag(args, "since", 0);
+    const limit = parseIntFlag(args, "limit", undefined, { min: 1, max: 200 });
+    const includeTombstones = args.bools.has("include-tombstones");
+    const client = makeClient(args);
+    try {
+        const page = await client.listRecords(paneId, collection, {
+            since,
+            ...(limit !== undefined ? { limit } : {}),
+        });
+        const records = includeTombstones
+            ? page.records
+            : page.records.filter((r) => r.deleted_at === null);
+        printJson({
+            records,
+            next_since: page.next_since,
+            has_more: page.has_more,
+        });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// get — client-side scan via listRecords (no dedicated route today)
+// ---------------------------------------------------------------------------
+async function runGet(args) {
+    assertKnownFlags(args, ["url", "api-key"], ["help"], "pane records get");
+    const [paneId, collection, recordKey] = args.positionals;
+    if (!paneId || !collection || !recordKey) {
+        fail("usage: pane records get <pane-id> <collection> <record-key>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const row = await client.getRecord(paneId, collection, recordKey);
+        if (!row) {
+            fail(`no record at key '${recordKey}' in collection '${collection}'`, "record_not_found");
+        }
+        printJson({ record: row });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// upsert — create-or-return-existing
+// ---------------------------------------------------------------------------
+async function runUpsert(args) {
+    assertKnownFlags(args, ["data", "key", "url", "api-key"], ["help"], "pane records upsert");
+    const [paneId, collection] = args.positionals;
+    if (!paneId || !collection) {
+        fail("usage: pane records upsert <pane-id> <collection> --data <path|json>", "invalid_args");
+    }
+    const dataRaw = args.flags.get("data");
+    if (dataRaw === undefined) {
+        fail("--data is required (path to JSON file, or inline JSON)", "invalid_args");
+    }
+    const data = resolveJson(dataRaw, "--data");
+    const key = args.flags.get("key");
+    const client = makeClient(args);
+    try {
+        const body = { data };
+        if (key !== undefined)
+            body.record_key = key;
+        const out = await client.upsertRecord(paneId, collection, body);
+        printJson(out);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// update — optimistic-lock mutate
+// ---------------------------------------------------------------------------
+async function runUpdate(args) {
+    assertKnownFlags(args, ["data", "if-match", "url", "api-key"], ["help"], "pane records update");
+    const [paneId, collection, recordKey] = args.positionals;
+    if (!paneId || !collection || !recordKey) {
+        fail("usage: pane records update <pane-id> <collection> <record-key> --data <path|json>", "invalid_args");
+    }
+    const dataRaw = args.flags.get("data");
+    if (dataRaw === undefined) {
+        fail("--data is required (path to JSON file, or inline JSON)", "invalid_args");
+    }
+    const data = resolveJson(dataRaw, "--data");
+    const ifMatch = parseIntFlag(args, "if-match", undefined, { min: 0 });
+    const client = makeClient(args);
+    try {
+        const body = { data };
+        if (ifMatch !== undefined)
+            body.if_match = ifMatch;
+        const out = await client.updateRecord(paneId, collection, recordKey, body);
+        printJson(out);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// delete — soft-delete
+// ---------------------------------------------------------------------------
+async function runDelete(args) {
+    assertKnownFlags(args, ["if-match", "url", "api-key"], ["yes", "help"], "pane records delete");
+    const [paneId, collection, recordKey] = args.positionals;
+    if (!paneId || !collection || !recordKey) {
+        fail("usage: pane records delete <pane-id> <collection> <record-key>", "invalid_args");
+    }
+    const ifMatch = parseIntFlag(args, "if-match", undefined, { min: 0 });
+    const client = makeClient(args);
+    try {
+        await client.deleteRecord(paneId, collection, recordKey, {
+            ...(ifMatch !== undefined ? { ifMatch } : {}),
+        });
+        printJson({ deleted: true, key: recordKey });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// watch — stream record deltas as JSON-lines
+// ---------------------------------------------------------------------------
+async function runWatch(args) {
+    // --collection is repeated-value; collected via danglingValueFlags + flags
+    assertKnownFlags(args, ["collection", "since-seq", "url", "api-key"], ["help"], "pane records watch");
+    const [paneId] = args.positionals;
+    if (!paneId) {
+        fail("usage: pane records watch <pane-id>", "invalid_args");
+    }
+    // --collection a,b,c (single comma list) OR repeated --collection foo flags.
+    // The shared argv parser uses a Map<string,string> for flags so a repeated
+    // flag last-write-wins. To support repeats here would need a parser
+    // extension; for now we accept a single comma list — the common case.
+    const collectionsRaw = args.flags.get("collection");
+    const subscribeRecords = collectionsRaw && collectionsRaw.length > 0 ? collectionsRaw : "*";
+    // --since-seq is a single comma list "name=N,name=M" for the same reason.
+    const sinceRaw = args.flags.get("since-seq");
+    const sinceRecordSeq = {};
+    if (sinceRaw) {
+        for (const part of sinceRaw.split(",")) {
+            const [name, vRaw] = part.split("=");
+            if (!name || vRaw === undefined) {
+                fail("--since-seq must be a comma list of name=N pairs", "invalid_args");
+            }
+            const n = Number(vRaw);
+            if (!Number.isInteger(n) || n < 0) {
+                fail(`--since-seq ${name}: value must be a non-negative integer`, "invalid_args");
+            }
+            sinceRecordSeq[name] = n;
+        }
+    }
+    const cfg = resolveConfig(args);
+    const handle = openStream({
+        wsBaseUrl: cfg.url.replace(/^http/, "ws"),
+        paneId: paneId,
+        token: cfg.apiKey,
+        subscribeRecords,
+        sinceRecordSeq,
+    }, {
+        onRecord: (msg) => {
+            process.stdout.write(JSON.stringify(msg) + "\n");
+        },
+        onRelayError: (err) => {
+            process.stderr.write(JSON.stringify({ error: err }) + "\n");
+        },
+        onError: (err) => {
+            process.stderr.write(JSON.stringify({
+                error: { code: "ws_error", message: err.message },
+            }) + "\n");
+        },
+        onClose: () => {
+            // Clean exit on close (e.g. SIGINT closed the socket). Emit nothing —
+            // the JSON-line stream is the contract; a trailing summary would
+            // confuse pipe readers.
+        },
+    });
+    // Hold the process open until SIGINT closes the stream.
+    process.on("SIGINT", () => {
+        handle.close();
+        process.exit(0);
+    });
+    await new Promise(() => {
+        /* never resolves — SIGINT exits */
+    });
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function parseIntFlag(args, name, defaultValue, bounds = {}) {
+    const raw = args.flags.get(name);
+    if (raw === undefined)
+        return defaultValue;
+    const n = Number(raw);
+    if (!Number.isInteger(n)) {
+        fail(`--${name} must be an integer`, "invalid_args");
+    }
+    if (bounds.min !== undefined && n < bounds.min) {
+        fail(`--${name} must be >= ${bounds.min}`, "invalid_args");
+    }
+    if (bounds.max !== undefined && n > bounds.max) {
+        fail(`--${name} must be <= ${bounds.max}`, "invalid_args");
+    }
+    return n;
+}