@radishbot/sdk 0.2.0 → 0.3.0

package/README.md

@@ -13,20 +13,20 @@ npm install @radishbot/sdk
 ## Quick Start
 
 ```ts
-import { RL, generateKey } from '@radishbot/sdk';
+import { RL, generateKey } from "@radishbot/sdk";
 
 const key = generateKey(); // save this — it's your dashboard login
 
-const root = await RL(key);
+const root = await RL(key, { release: "v1.0.0", retention: "30d" });
 
-await root.a('handle-request', async (req) => {
-  console.log('GET /api/users'); // automatically captured
+await root.a("handle-request", async (req) => {
+  console.log("GET /api/users"); // automatically captured
 
-  const users = await req.a('db-query', async () => {
-    return await db.query('SELECT * FROM users');
+  const users = await req.a("db-query", async () => {
+    return await db.query("SELECT * FROM users");
   });
 
-  console.log('Done', { count: users.length });
+  console.log("Done", { count: users.length });
 });
 
 await root.finish();
@@ -39,12 +39,12 @@ Open the dashboard, paste your key, see everything.
 Inside `.a()` callbacks, `console.log/warn/error/debug` are automatically captured as action logs. Output still prints to the terminal — but it also gets sent to the dashboard with full context.
 
 ```ts
-await root.a('migrate', async () => {
-  console.log('Starting migration');           // → info log
-  console.warn('Deprecated column found');     // → warn log
-  console.error('Failed to migrate users');    // → error log
-  console.debug('SQL: ALTER TABLE ...');       // → debug log
-  console.log('Done', { tables: 5 });          // → info log with data
+await root.a("migrate", async () => {
+  console.log("Starting migration"); // → info log
+  console.warn("Deprecated column found"); // → warn log
+  console.error("Failed to migrate users"); // → error log
+  console.debug("SQL: ALTER TABLE ..."); // → debug log
+  console.log("Done", { tables: 5 }); // → info log with data
 });
 ```
 
@@ -57,15 +57,15 @@ Actions are nested scopes. Every `RL()` call creates a root action at `/`. Sub-a
 ```ts
 const root = await RL(key);
 
-await root.a('request', async (req) => {
-  console.log('handling request');
+await root.a("request", async (req) => {
+  console.log("handling request");
 
-  await req.a('database', async () => {
-    console.log('querying users');
+  await req.a("database", async () => {
+    console.log("querying users");
   }); // auto-finished
 
-  await req.a('response', async () => {
-    console.log('sending 200');
+  await req.a("response", async () => {
+    console.log("sending 200");
   }); // auto-finished
 }); // auto-finished
 
@@ -75,16 +75,16 @@ await root.finish();
 If your function throws, the action is marked as errored and the exception propagates:
 
 ```ts
-await root.a('risky-op', async () => {
-  throw new Error('something broke');
+await root.a("risky-op", async () => {
+  throw new Error("something broke");
 }); // action → error, rethrows
 ```
 
 Return values pass through:
 
 ```ts
-const users = await flow.a('db-query', async () => {
-  return await db.query('SELECT * FROM users');
+const users = await flow.a("db-query", async () => {
+  return await db.query("SELECT * FROM users");
 });
 // users is the query result
 ```
@@ -92,9 +92,9 @@ const users = await flow.a('db-query', async () => {
 Duplicate names are allowed — the dashboard shows them as `request:1`, `request:2`, etc:
 
 ```ts
-await root.a('batch', async (batch) => {
+await root.a("batch", async (batch) => {
   for (const item of items) {
-    await batch.a('request', async () => {
+    await batch.a("request", async () => {
       await processItem(item);
     });
   }
@@ -104,10 +104,10 @@ await root.a('batch', async (batch) => {
 For long-lived actions (websockets, streams), use the manual API:
 
 ```ts
-const stream = root.action('websocket');
-stream.info('connected');
+const stream = root.action("websocket");
+stream.info("connected");
 // ... hours later ...
-stream.info('disconnected');
+stream.info("disconnected");
 await stream.finish();
 ```
 
@@ -116,10 +116,10 @@ await stream.finish();
 Outside of `.a()` callbacks, or when you want to log to a specific action:
 
 ```ts
-action.info('request received', { method: 'POST', path: '/api/users' });
-action.warn('rate limit approaching', { remaining: 3 });
-action.error('query failed', new Error('connection refused'));
-action.debug('cache hit', { key: 'user:123', ttl: 300 });
+action.info("request received", { method: "POST", path: "/api/users" });
+action.warn("rate limit approaching", { remaining: 3 });
+action.error("query failed", new Error("connection refused"));
+action.debug("cache hit", { key: "user:123", ttl: 300 });
 ```
 
 ## Cross-Context Actions
@@ -128,35 +128,74 @@ Export an action's handle to continue logging from another process, worker, or s
 
 ```ts
 // Service A
-const action = root.action('job');
+const action = root.action("job");
 const handle = await action.exportID();
 // pass handle to service B via queue, HTTP, etc.
 
 // Service B
-import { restoreFlow } from '@radishbot/sdk';
+import { restoreFlow } from "@radishbot/sdk";
 const action = await restoreFlow(key, handle);
-action.info('continuing from service B');
+action.info("continuing from service B");
 await action.finish();
 ```
 
+## Release Tracking
+
+Tag every flow with a version or commit SHA. Errors are tracked per-release, and regressions (errors reappearing after being resolved) are detected automatically.
+
+```ts
+const root = await RL(key, { release: "v1.2.3" });
+// or
+const root = await RL(key, { release: process.env.GIT_SHA });
+```
+
+Sub-flows inherit the release from the root automatically.
+
+## Retention & Garbage Collection
+
+Each key has a retention period. Flows older than the retention window are automatically deleted (along with their logs and actions) by a GC job that runs every 3 hours.
+
+```ts
+const root = await RL(key, { retention: "30d" }); // default
+const root = await RL(key, { retention: "7d" }); // keep 1 week
+const root = await RL(key, { retention: "90d" }); // keep 3 months
+```
+
+Calling `RL()` with a new retention value updates the stored retention for that key.
+
+## Error Grouping
+
+Errors are automatically deduplicated by normalizing the error message (stripping numbers, UUIDs) and combining it with the flow path. This means:
+
+- `"User 123 not found"` and `"User 456 not found"` at `/request/db-query` group together
+- Each group tracks: count, first/last seen, latest flow, and release
+- Resolving an error group and seeing it again marks it as **regressed**
+- Groups can be marked as `resolved` or `ignored` from the dashboard
+
 ## Configuration
 
 ```ts
 const root = await RL(key, {
-  host: 'wss://maincloud.spacetimedb.com', // default
-  dbName: 'radish-log',                     // default
-  defaultTimeout: 100,                       // seconds, default 100
+  host: "wss://maincloud.spacetimedb.com", // default
+  dbName: "radish-log", // default
+  defaultTimeout: 100, // seconds, default 100
+  release: "v1.0.0", // version or commit SHA
+  retention: "30d", // data retention period
 });
 ```
 
 Sub-actions can have their own timeout:
 
 ```ts
-await root.a('quick-task', async () => {
-  // ...
-}, 10); // 10 second timeout
-
-const slow = root.action('batch-job', 3600); // 1 hour
+await root.a(
+  "quick-task",
+  async () => {
+    // ...
+  },
+  10,
+); // 10 second timeout
+
+const slow = root.action("batch-job", 3600); // 1 hour
 ```
 
 Actions that exceed their timeout are automatically marked as timed out.
@@ -165,7 +204,7 @@ Actions that exceed their timeout are automatically marked as timed out.
 
 ### `RL(secretKey, options?) → Promise<Flow>`
 
-Connect and create a root action.
+Connect and create a root action. Options: `host`, `dbName`, `defaultTimeout`, `release`, `retention`.
 
 ### `generateKey() → string`
 
@@ -177,16 +216,16 @@ Restore an action from an exported handle string.
 
 ### Flow (Action)
 
-| Method | Description |
-|---|---|
-| `.a(name, fn, timeout?)` | Run a sub-action. Auto-finish, console capture. Returns fn result. |
-| `.action(name, timeout?)` | Create a sub-action manually. |
-| `.finish()` | Finish the action. |
-| `.finishWithError(err?)` | Finish the action as errored. |
-| `.info(msg, data?)` | Log at info level. |
-| `.warn(msg, data?)` | Log at warn level. |
-| `.error(msg, data?)` | Log at error level. |
-| `.debug(msg, data?)` | Log at debug level. |
-| `.log(msg, data?, level?)` | Log at any level. |
-| `.exportID()` | Export handle for cross-context restore. |
-| `.getId()` | Get server-assigned action ID. |
+| Method                     | Description                                                        |
+| -------------------------- | ------------------------------------------------------------------ |
+| `.a(name, fn, timeout?)`   | Run a sub-action. Auto-finish, console capture. Returns fn result. |
+| `.action(name, timeout?)`  | Create a sub-action manually.                                      |
+| `.finish()`                | Finish the action.                                                 |
+| `.finishWithError(err?)`   | Finish the action as errored.                                      |
+| `.info(msg, data?)`        | Log at info level.                                                 |
+| `.warn(msg, data?)`        | Log at warn level.                                                 |
+| `.error(msg, data?)`       | Log at error level.                                                |
+| `.debug(msg, data?)`       | Log at debug level.                                                |
+| `.log(msg, data?, level?)` | Log at any level.                                                  |
+| `.exportID()`              | Export handle for cross-context restore.                           |
+| `.getId()`                 | Get server-assigned action ID.                                     |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radishbot/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/cli.ts

@@ -3,59 +3,92 @@
  * Radish CLI — inspect flows and logs from the terminal.
  *
  * Usage:
- *   radish <key>                  List recent flows
- *   radish <key> <flowId>         Show flow detail + logs
- *   radish <key> tail             Live-tail all logs
- *   radish <key> tree <flowId>    Show flow tree
+ *   radish keygen                       Generate a new secret key
+ *   radish <key>                        List recent flows
+ *   radish <key> <flowId>               Show flow detail + logs
+ *   radish <key> tree <flowId>          Show flow tree
+ *   radish <key> tail                   Live-tail all logs
+ *   radish <key> errors                 Show error groups
+ *   radish <key> resolve <errorGroupId> Resolve an error group
+ *   radish <key> ignore <errorGroupId>  Ignore an error group
  */
-import { DbConnection } from './module_bindings';
+import { DbConnection } from "./module_bindings";
 
-const HOST = 'wss://maincloud.spacetimedb.com';
-const DB_NAME = 'radish-log';
+const HOST = "wss://maincloud.spacetimedb.com";
+const DB_NAME = "radish-log";
 
 // ── Colors ───────────────────────────────────────────────────
 
 const c = {
-  reset: '\x1b[0m',
-  dim: '\x1b[2m',
-  bold: '\x1b[1m',
-  red: '\x1b[31m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  magenta: '\x1b[35m',
-  cyan: '\x1b[36m',
-  gray: '\x1b[90m',
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  gray: "\x1b[90m",
 };
 
 function levelColor(level: string): string {
   switch (level) {
-    case 'info': return c.blue;
-    case 'warn': return c.yellow;
-    case 'error': return c.red;
-    case 'debug': return c.gray;
-    default: return c.dim;
+    case "info":
+      return c.blue;
+    case "warn":
+      return c.yellow;
+    case "error":
+      return c.red;
+    case "debug":
+      return c.gray;
+    default:
+      return c.dim;
   }
 }
 
 function statusColor(status: string): string {
   switch (status) {
-    case 'open': return c.blue;
-    case 'finished': return c.green;
-    case 'error': return c.red;
-    case 'timeout': return c.yellow;
-    default: return c.dim;
+    case "open":
+      return c.blue;
+    case "finished":
+      return c.green;
+    case "error":
+      return c.red;
+    case "timeout":
+      return c.yellow;
+    default:
+      return c.dim;
+  }
+}
+
+function errorStatusColor(status: string): string {
+  switch (status) {
+    case "open":
+      return c.red;
+    case "regressed":
+      return c.yellow;
+    case "resolved":
+      return c.green;
+    case "ignored":
+      return c.gray;
+    default:
+      return c.dim;
   }
 }
 
 // ── Helpers ──────────────────────────────────────────────────
 
 async function hashKey(key: string): Promise<string> {
-  const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(key));
-  return Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, '0')).join('');
+  const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(key));
+  return Array.from(new Uint8Array(buf))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
 }
 
-function tsMicros(ts: any): bigint { return ts.microsSinceUnixEpoch; }
+function tsMicros(ts: any): bigint {
+  return ts.microsSinceUnixEpoch;
+}
 
 function fmtTime(ts: any): string {
   return new Date(Number(tsMicros(ts) / 1000n)).toLocaleTimeString();
@@ -68,7 +101,7 @@ function fmtDateTime(ts: any): string {
 
 function fmtMs(us: number): string {
   const ms = us / 1000;
-  if (ms < 1) return '<1ms';
+  if (ms < 1) return "<1ms";
   if (ms < 1000) return `${Math.round(ms)}ms`;
   if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
   return `${(ms / 60000).toFixed(1)}m`;
@@ -79,24 +112,31 @@ function fmtDuration(startTs: any, endMicros: bigint): string {
 }
 
 function fmtData(data: string): string {
-  if (!data || data === '{}') return '';
+  if (!data || data === "{}") return "";
   try {
     const parsed = JSON.parse(data);
     const str = JSON.stringify(parsed, null, 2);
     // Indent continuation lines
-    return str.split('\n').map((line, i) => i === 0 ? ' ' + c.dim + line + c.reset : '                          ' + c.dim + line + c.reset).join('\n');
+    return str
+      .split("\n")
+      .map((line, i) =>
+        i === 0 ? " " + c.dim + line + c.reset : "                          " + c.dim + line + c.reset,
+      )
+      .join("\n");
   } catch {
-    return ' ' + c.dim + data + c.reset;
+    return " " + c.dim + data + c.reset;
   }
 }
 
 function padRight(s: string, n: number): string {
-  return s.length >= n ? s.slice(0, n) : s + ' '.repeat(n - s.length);
+  return s.length >= n ? s.slice(0, n) : s + " ".repeat(n - s.length);
 }
 
 // ── Connect ──────────────────────────────────────────────────
 
-function connect(keyHash: string): Promise<{ conn: DbConnection; flows: () => any[]; logs: () => any[] }> {
+function connect(
+  keyHash: string,
+): Promise<{ conn: DbConnection; flows: () => any[]; logs: () => any[]; errorGroups: () => any[] }> {
   return new Promise((resolve, reject) => {
     const conn = DbConnection.builder()
       .withUri(HOST)
@@ -114,7 +154,12 @@ function connect(keyHash: string): Promise<{ conn: DbConnection; flows: () => an
               for (const l of c.db.logEntry.iter()) result.push(l);
               return result;
             };
-            resolve({ conn: c, flows, logs });
+            const errorGroups = () => {
+              const result: any[] = [];
+              for (const g of c.db.errorGroup.iter()) if (g.keyHash === keyHash) result.push(g);
+              return result;
+            };
+            resolve({ conn: c, flows, logs, errorGroups });
           })
           .subscribeToAllTables();
       })
@@ -127,9 +172,10 @@ function connect(keyHash: string): Promise<{ conn: DbConnection; flows: () => an
 
 function cmdList(flows: any[]) {
   const roots = flows
-    .filter(f => f.parentFlowId === 0n)
+    .filter((f) => f.parentFlowId === 0n)
     .sort((a, b) => {
-      const am = tsMicros(a.createdAt), bm = tsMicros(b.createdAt);
+      const am = tsMicros(a.createdAt),
+        bm = tsMicros(b.createdAt);
       return am > bm ? -1 : am < bm ? 1 : 0;
     });
 
@@ -138,17 +184,29 @@ function cmdList(flows: any[]) {
     return;
   }
 
+  const hasRelease = roots.some((f) => f.release && f.release !== "");
+
   console.log(`${c.bold}Flows${c.reset} ${c.dim}(${roots.length} total)${c.reset}\n`);
-  console.log(`${c.dim}  ${'ID'.padEnd(8)} ${'STATUS'.padEnd(10)} ${'DURATION'.padEnd(10)} CREATED${c.reset}`);
-  console.log(`${c.dim}  ${'─'.repeat(8)} ${'─'.repeat(10)} ${'─'.repeat(10)} ${'─'.repeat(24)}${c.reset}`);
+  if (hasRelease) {
+    console.log(
+      `${c.dim}  ${"ID".padEnd(8)} ${"STATUS".padEnd(10)} ${"RELEASE".padEnd(10)} ${"DURATION".padEnd(10)} CREATED${c.reset}`,
+    );
+    console.log(
+      `${c.dim}  ${"─".repeat(8)} ${"─".repeat(10)} ${"─".repeat(10)} ${"─".repeat(10)} ${"─".repeat(24)}${c.reset}`,
+    );
+  } else {
+    console.log(`${c.dim}  ${"ID".padEnd(8)} ${"STATUS".padEnd(10)} ${"DURATION".padEnd(10)} CREATED${c.reset}`);
+    console.log(`${c.dim}  ${"─".repeat(8)} ${"─".repeat(10)} ${"─".repeat(10)} ${"─".repeat(24)}${c.reset}`);
+  }
 
   for (const f of roots.slice(0, 30)) {
     const id = f.id.toString().padEnd(8);
     const sc = statusColor(f.status);
     const status = padRight(f.status, 10);
-    const dur = f.finishedAt !== 0n ? padRight(fmtDuration(f.createdAt, f.finishedAt), 10) : padRight('—', 10);
+    const dur = f.finishedAt !== 0n ? padRight(fmtDuration(f.createdAt, f.finishedAt), 10) : padRight("—", 10);
     const time = fmtDateTime(f.createdAt);
-    console.log(`  ${c.dim}${id}${c.reset} ${sc}${status}${c.reset} ${dur} ${c.dim}${time}${c.reset}`);
+    const release = hasRelease ? padRight(f.release || "—", 10) + " " : "";
+    console.log(`  ${c.dim}${id}${c.reset} ${sc}${status}${c.reset} ${release}${dur} ${c.dim}${time}${c.reset}`);
   }
 
   if (roots.length > 30) {
@@ -157,7 +215,7 @@ function cmdList(flows: any[]) {
 }
 
 function cmdShow(flowId: bigint, allFlows: any[], allLogs: any[]) {
-  const flow = allFlows.find(f => f.id === flowId);
+  const flow = allFlows.find((f) => f.id === flowId);
   if (!flow) {
     console.error(`${c.red}Flow ${flowId} not found.${c.reset}`);
     process.exit(1);
@@ -165,18 +223,23 @@ function cmdShow(flowId: bigint, allFlows: any[], allLogs: any[]) {
 
   // Header
   const sc = statusColor(flow.status);
-  console.log(`${c.bold}Flow #${flow.id}${c.reset}  ${sc}${flow.status}${c.reset}`);
+  const releaseTag = flow.release ? `  ${c.dim}(${flow.release})${c.reset}` : "";
+  console.log(`${c.bold}Flow #${flow.id}${c.reset}  ${sc}${flow.status}${c.reset}${releaseTag}`);
   console.log(`${c.dim}Created: ${fmtDateTime(flow.createdAt)}${c.reset}`);
   if (flow.finishedAt !== 0n) {
     console.log(`${c.dim}Duration: ${fmtDuration(flow.createdAt, flow.finishedAt)}${c.reset}`);
   }
+  if (flow.release) {
+    console.log(`${c.dim}Release: ${flow.release}${c.reset}`);
+  }
   console.log();
 
   // Child flows
   const children = allFlows
-    .filter(f => f.parentFlowId === flowId)
+    .filter((f) => f.parentFlowId === flowId)
     .sort((a, b) => {
-      const am = tsMicros(a.createdAt), bm = tsMicros(b.createdAt);
+      const am = tsMicros(a.createdAt),
+        bm = tsMicros(b.createdAt);
       return am < bm ? -1 : am > bm ? 1 : 0;
     });
 
@@ -184,8 +247,10 @@ function cmdShow(flowId: bigint, allFlows: any[], allLogs: any[]) {
     console.log(`${c.bold}Actions${c.reset}\n`);
     for (const ch of children) {
       const sc = statusColor(ch.status);
-      const dur = ch.finishedAt !== 0n ? fmtDuration(ch.createdAt, ch.finishedAt) : '…';
-      console.log(`  ${sc}●${c.reset} ${c.bold}${ch.name}${c.reset} ${c.dim}#${ch.id}${c.reset}  ${sc}${ch.status}${c.reset}  ${c.dim}${dur}${c.reset}`);
+      const dur = ch.finishedAt !== 0n ? fmtDuration(ch.createdAt, ch.finishedAt) : "…";
+      console.log(
+        `  ${sc}●${c.reset} ${c.bold}${ch.name}${c.reset} ${c.dim}#${ch.id}${c.reset}  ${sc}${ch.status}${c.reset}  ${c.dim}${dur}${c.reset}`,
+      );
     }
     console.log();
   }
@@ -201,9 +266,10 @@ function cmdShow(flowId: bigint, allFlows: any[], allLogs: any[]) {
   collectIds(flowId);
 
   const logs = allLogs
-    .filter(l => flowIds.has(l.flowId) && l.level !== 'flow' && l.level !== 'action')
+    .filter((l) => flowIds.has(l.flowId) && l.level !== "flow" && l.level !== "action")
     .sort((a, b) => {
-      const am = tsMicros(a.createdAt), bm = tsMicros(b.createdAt);
+      const am = tsMicros(a.createdAt),
+        bm = tsMicros(b.createdAt);
       return am < bm ? -1 : am > bm ? 1 : 0;
     });
 
@@ -214,21 +280,21 @@ function cmdShow(flowId: bigint, allFlows: any[], allLogs: any[]) {
 
   // Find source flow name for each log
   const flowMap = new Map<bigint, string>();
-  for (const f of allFlows) flowMap.set(f.id, f.name === '/' ? 'root' : f.name);
+  for (const f of allFlows) flowMap.set(f.id, f.name === "/" ? "root" : f.name);
 
   console.log(`${c.bold}Logs${c.reset}\n`);
   for (const l of logs) {
     const time = fmtTime(l.createdAt);
     const lc = levelColor(l.level);
     const lvl = padRight(l.level, 5);
-    const source = l.flowId !== flowId ? ` ${c.cyan}[${flowMap.get(l.flowId) || '?'}]${c.reset}` : '';
+    const source = l.flowId !== flowId ? ` ${c.cyan}[${flowMap.get(l.flowId) || "?"}]${c.reset}` : "";
     const data = fmtData(l.data);
     console.log(`  ${c.dim}${time}${c.reset} ${lc}${lvl}${c.reset}${source} ${l.message}${data}`);
   }
 }
 
 function cmdTree(flowId: bigint, allFlows: any[]) {
-  const flow = allFlows.find(f => f.id === flowId);
+  const flow = allFlows.find((f) => f.id === flowId);
   if (!flow) {
     console.error(`${c.red}Flow ${flowId} not found.${c.reset}`);
     process.exit(1);
@@ -238,28 +304,31 @@ function cmdTree(flowId: bigint, allFlows: any[]) {
 
   function printNode(f: any, prefix: string, connector: string) {
     const sc = statusColor(f.status);
-    const name = f.name === '/' ? 'root' : f.name;
-    const dur = f.finishedAt !== 0n ? ` ${c.dim}${fmtDuration(f.createdAt, f.finishedAt)}${c.reset}` : '';
-    console.log(`${prefix}${connector}${sc}●${c.reset} ${c.bold}${name}${c.reset} ${c.dim}#${f.id}${c.reset} ${sc}${f.status}${c.reset}${dur}`);
+    const name = f.name === "/" ? "root" : f.name;
+    const dur = f.finishedAt !== 0n ? ` ${c.dim}${fmtDuration(f.createdAt, f.finishedAt)}${c.reset}` : "";
+    console.log(
+      `${prefix}${connector}${sc}●${c.reset} ${c.bold}${name}${c.reset} ${c.dim}#${f.id}${c.reset} ${sc}${f.status}${c.reset}${dur}`,
+    );
   }
 
   function printChildren(parentId: bigint, prefix: string) {
     const children = allFlows
-      .filter(ch => ch.parentFlowId === parentId)
+      .filter((ch) => ch.parentFlowId === parentId)
       .sort((a, b) => {
-        const am = tsMicros(a.createdAt), bm = tsMicros(b.createdAt);
+        const am = tsMicros(a.createdAt),
+          bm = tsMicros(b.createdAt);
         return am < bm ? -1 : am > bm ? 1 : 0;
       });
 
     for (let i = 0; i < children.length; i++) {
       const isLast = i === children.length - 1;
-      printNode(children[i], prefix, isLast ? '└─ ' : '├─ ');
-      printChildren(children[i].id, prefix + (isLast ? '   ' : '│  '));
+      printNode(children[i], prefix, isLast ? "└─ " : "├─ ");
+      printChildren(children[i].id, prefix + (isLast ? "   " : "│  "));
     }
   }
 
-  printNode(flow, '', '');
-  printChildren(flowId, '');
+  printNode(flow, "", "");
+  printChildren(flowId, "");
 }
 
 async function cmdTail(keyHash: string) {
@@ -277,7 +346,7 @@ async function cmdTail(keyHash: string) {
           .onApplied(() => {
             // Seed known flows and seen logs
             for (const f of c.db.flow.iter()) {
-              if (f.keyHash === keyHash) flowNames.set(f.id, f.name === '/' ? 'root' : f.name);
+              if (f.keyHash === keyHash) flowNames.set(f.id, f.name === "/" ? "root" : f.name);
             }
             for (const l of c.db.logEntry.iter()) seen.add(l.id);
             resolve(c);
@@ -293,13 +362,13 @@ async function cmdTail(keyHash: string) {
     // Update flow names
     for (const f of conn.db.flow.iter()) {
       if (f.keyHash === keyHash && !flowNames.has(f.id)) {
-        flowNames.set(f.id, f.name === '/' ? 'root' : f.name);
+        flowNames.set(f.id, f.name === "/" ? "root" : f.name);
       }
     }
 
     const newLogs: any[] = [];
     for (const l of conn.db.logEntry.iter()) {
-      if (!seen.has(l.id) && l.level !== 'flow' && l.level !== 'action') {
+      if (!seen.has(l.id) && l.level !== "flow" && l.level !== "action") {
         // Only show logs belonging to this key's flows
         if (flowNames.has(l.flowId)) {
           seen.add(l.id);
@@ -309,7 +378,8 @@ async function cmdTail(keyHash: string) {
     }
 
     newLogs.sort((a, b) => {
-      const am = tsMicros(a.createdAt), bm = tsMicros(b.createdAt);
+      const am = tsMicros(a.createdAt),
+        bm = tsMicros(b.createdAt);
       return am < bm ? -1 : am > bm ? 1 : 0;
     });
 
@@ -317,57 +387,139 @@ async function cmdTail(keyHash: string) {
       const time = fmtTime(l.createdAt);
       const lc = levelColor(l.level);
       const lvl = padRight(l.level, 5);
-      const source = `${c.cyan}[${flowNames.get(l.flowId) || '?'}]${c.reset}`;
+      const source = `${c.cyan}[${flowNames.get(l.flowId) || "?"}]${c.reset}`;
       const data = fmtData(l.data);
       console.log(`${c.dim}${time}${c.reset} ${lc}${lvl}${c.reset} ${source} ${l.message}${data}`);
     }
   }, 500);
 }
 
+function cmdErrors(errorGroups: any[]) {
+  const statusOrder: Record<string, number> = { open: 0, regressed: 1, resolved: 2, ignored: 3 };
+  const sorted = [...errorGroups].sort((a, b) => {
+    const ao = statusOrder[a.status] ?? 99,
+      bo = statusOrder[b.status] ?? 99;
+    if (ao !== bo) return ao - bo;
+    // Within same status priority, sort by count descending
+    return a.count > b.count ? -1 : a.count < b.count ? 1 : 0;
+  });
+
+  if (sorted.length === 0) {
+    console.log(`${c.dim}No error groups found for this key.${c.reset}`);
+    return;
+  }
+
+  console.log(`${c.bold}Errors${c.reset} ${c.dim}(${sorted.length} groups)${c.reset}\n`);
+  console.log(
+    `${c.dim}  ${"ID".padEnd(8)} ${"STATUS".padEnd(10)} ${"COUNT".padEnd(6)} ${"RELEASE".padEnd(10)} ${"PATH".padEnd(23)} MESSAGE${c.reset}`,
+  );
+  console.log(
+    `${c.dim}  ${"─".repeat(8)} ${"─".repeat(10)} ${"─".repeat(6)} ${"─".repeat(10)} ${"─".repeat(23)} ${"─".repeat(25)}${c.reset}`,
+  );
+
+  for (const g of sorted) {
+    const id = g.id.toString().padEnd(8);
+    const esc = errorStatusColor(g.status);
+    const status = padRight(g.status, 10);
+    const count = g.count.toString().padEnd(6);
+    const release = padRight(g.release || "—", 10);
+    const path = padRight(g.path || "—", 23);
+    const message = g.message.length > 50 ? g.message.slice(0, 47) + "..." : g.message;
+    console.log(
+      `  ${c.dim}${id}${c.reset} ${esc}${status}${c.reset} ${count} ${c.dim}${release}${c.reset} ${c.dim}${path}${c.reset} ${message}`,
+    );
+  }
+}
+
+async function cmdUpdateErrorGroupStatus(conn: DbConnection, keyHash: string, errorGroupId: string, status: string) {
+  conn.reducers.updateErrorGroupStatus({
+    keyHash,
+    errorGroupId: BigInt(errorGroupId),
+    status,
+  });
+  const label = status === "resolved" ? "Resolved" : "Ignored";
+  console.log(`${c.green}${label} error group #${errorGroupId}.${c.reset}`);
+}
+
 // ── Main ─────────────────────────────────────────────────────
 
 async function main() {
   const args = process.argv.slice(2);
 
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
     console.log(`
 ${c.bold}radish${c.reset} — inspect flows and logs
 
 ${c.bold}Usage:${c.reset}
-  radish <key>                  List recent flows
-  radish <key> <flowId>         Show flow detail + logs
-  radish <key> tree <flowId>    Show flow tree
-  radish <key> tail             Live-tail all logs
+  radish keygen                       Generate a new secret key
+  radish <key>                        List recent flows
+  radish <key> <flowId>               Show flow detail + logs
+  radish <key> tree <flowId>          Show flow tree
+  radish <key> tail                   Live-tail all logs
+  radish <key> errors                 Show error groups
+  radish <key> resolve <errorGroupId> Resolve an error group
+  radish <key> ignore <errorGroupId>  Ignore an error group
 `);
     process.exit(0);
   }
 
+  // keygen subcommand — no key required
+  if (args[0] === "keygen") {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    const key =
+      "rl_" +
+      Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+    console.log(`\n${c.bold}Generated key:${c.reset} ${key}\n`);
+    console.log(`Save this key — it's your dashboard login.`);
+    console.log(`Dashboard: ${c.cyan}https://radish-log.spacetimedb.com${c.reset}\n`);
+    process.exit(0);
+  }
+
   const secretKey = args[0];
   const keyHash = await hashKey(secretKey);
   const subcmd = args[1];
 
-  if (subcmd === 'tail') {
+  if (subcmd === "tail") {
     await cmdTail(keyHash);
     return; // stays alive
   }
 
   // Connect and fetch data
   process.stderr.write(`${c.dim}Connecting...${c.reset}`);
-  const { conn, flows, logs } = await connect(keyHash);
-  process.stderr.write(`\r${' '.repeat(20)}\r`);
+  const { conn, flows, logs, errorGroups } = await connect(keyHash);
+  process.stderr.write(`\r${" ".repeat(20)}\r`);
 
   const allFlows = flows();
   const allLogs = logs();
 
   if (!subcmd) {
     cmdList(allFlows);
-  } else if (subcmd === 'tree') {
-    const flowId = BigInt(args[2] || '0');
+  } else if (subcmd === "tree") {
+    const flowId = BigInt(args[2] || "0");
     if (flowId === 0n) {
       console.error(`${c.red}Usage: radish <key> tree <flowId>${c.reset}`);
       process.exit(1);
     }
     cmdTree(flowId, allFlows);
+  } else if (subcmd === "errors") {
+    cmdErrors(errorGroups());
+  } else if (subcmd === "resolve") {
+    const errorGroupId = args[2];
+    if (!errorGroupId) {
+      console.error(`${c.red}Usage: radish <key> resolve <errorGroupId>${c.reset}`);
+      process.exit(1);
+    }
+    await cmdUpdateErrorGroupStatus(conn, keyHash, errorGroupId, "resolved");
+  } else if (subcmd === "ignore") {
+    const errorGroupId = args[2];
+    if (!errorGroupId) {
+      console.error(`${c.red}Usage: radish <key> ignore <errorGroupId>${c.reset}`);
+      process.exit(1);
+    }
+    await cmdUpdateErrorGroupStatus(conn, keyHash, errorGroupId, "ignored");
   } else {
     const flowId = BigInt(subcmd);
     cmdShow(flowId, allFlows, allLogs);
@@ -377,7 +529,7 @@ ${c.bold}Usage:${c.reset}
   process.exit(0);
 }
 
-main().catch(err => {
+main().catch((err) => {
   console.error(`${c.red}${err.message}${c.reset}`);
   process.exit(1);
 });

package/src/index.ts

@@ -260,6 +260,19 @@ export class Flow {
     return this._id!;
   }
 
+  /** Disconnect the underlying SpacetimeDB connection */
+  disconnect(): void {
+    this._sdk.disconnect();
+  }
+
+  /** Finish the flow and disconnect */
+  async finishAndDisconnect(): Promise<void> {
+    await this.finish();
+    // Small delay to allow the finish reducer to be sent
+    await new Promise((r) => setTimeout(r, 100));
+    this.disconnect();
+  }
+
   /** Schedule a drain on the next microtask — batches sync logs with ~0ms delay */
   private _scheduleFlush() {
     if (this._flushScheduled) return;
@@ -345,7 +358,11 @@ export async function RL(secretKey: string, options: RLOptions = {}): Promise<Fl
   const keyHash = await hashKey(secretKey);
   const sdk = new SdkConnection(host, dbName);
   sdk.setKeyHash(keyHash);
-  await sdk.connect();
+  try {
+    await sdk.connect();
+  } catch (e) {
+    throw new Error(`Failed to connect to Radish (${host}/${dbName}): ${e instanceof Error ? e.message : e}`);
+  }
 
   // Register key (idempotent — updates retention if changed)
   try {