wicked-bus 2.0.1 → 2.1.0

package/commands/cmd-subscribe.js

@@ -7,8 +7,84 @@ import { openDb } from '../lib/db.js';
 import { poll, ack } from '../lib/poll.js';
 import { register } from '../lib/register.js';
 import { startSweep } from '../lib/sweep.js';
+import { WBError } from '../lib/errors.js';
+
+const SUBSCRIBE_USAGE = {
+  usage: 'wicked-bus subscribe --plugin <name> [options]',
+  description:
+    'Stream events matching a filter as newline-delimited JSON (NDJSON) to stdout. ' +
+    'Runs until SIGINT/SIGTERM.',
+  required: {
+    '--plugin <name>':
+      'Subscriber identity. The durable cursor is keyed on (plugin, filter).',
+  },
+  options: {
+    '--filter <pattern>':
+      "Event type filter, e.g. 'wicked.test.run.*' or '*@wicked-testing'. Default: all events.",
+    '--cursor-id <id>':
+      'Resume an explicit cursor instead of resolving one by (plugin, filter).',
+    '--cursor-init <oldest|latest>':
+      'Where a NEWLY registered subscription starts. Default: latest.',
+    '--poll-interval-ms <ms>': 'Poll cadence. Default: 1000.',
+    '--batch-size <n>': 'Maximum events delivered per poll. Default: 100.',
+    '--no-ack':
+      'Do not advance the cursor after delivering. Events re-deliver on the next run.',
+    '--once, --drain':
+      'Drain mode: deliver all events pending past the cursor, then exit 0 (does ' +
+      'not stream). Process completion is the wake signal for completion-driven ' +
+      'agent harnesses.',
+    '--idle-timeout <ms>':
+      'Drain mode only: after the queue empties, block up to <ms> for new events ' +
+      '(the timer resets on each delivery) before exiting 0. Without it, drain ' +
+      'exits as soon as the queue is empty.',
+    '-h, --help': 'Show this help and exit.',
+  },
+  notes: [
+    'Default (streaming) mode runs until SIGINT/SIGTERM.',
+    'Drain mode (--once/--drain) enables a clean drain -> handle -> re-arm loop.',
+    "Drain writes events to stdout as NDJSON and a one-line summary to stderr.",
+  ],
+};
+
+/**
+ * True when the user asked for help. `--help` is captured by the arg parser as
+ * `args.help`; the short `-h` form is not a `--flag`, so it lands in positionals.
+ */
+function wantsHelp(args) {
+  return args.help === true || (args._positional || []).includes('-h');
+}
 
 export async function cmdSubscribe(args, globals) {
+  // Help and argument validation happen BEFORE any DB access so `--help`
+  // never falls through to a confusing SQLite error, and a missing required
+  // arg fails fast with a structured, non-zero-exit WBError.
+  if (wantsHelp(args)) {
+    process.stdout.write(JSON.stringify(SUBSCRIBE_USAGE, null, 2) + '\n');
+    return;
+  }
+
+  const plugin = args.plugin;
+  if (!plugin || plugin === true) {
+    throw new WBError('WB-001', 'INVALID_EVENT_SCHEMA', {
+      message: '--plugin <name> is required (run `wicked-bus subscribe --help`)',
+      reason: 'missing --plugin',
+    });
+  }
+
+  // Drain mode (--once / --drain): deliver pending events, then exit instead of
+  // streaming forever. Validated pre-DB so a bad --idle-timeout fails fast.
+  const drainMode = args.once === true || args.drain === true;
+  let idleTimeoutMs = null;
+  if (args['idle-timeout'] != null && args['idle-timeout'] !== true) {
+    idleTimeoutMs = Number(args['idle-timeout']);
+    if (!Number.isFinite(idleTimeoutMs) || idleTimeoutMs < 0) {
+      throw new WBError('WB-001', 'INVALID_EVENT_SCHEMA', {
+        message: `--idle-timeout must be a non-negative number of milliseconds, got: ${args['idle-timeout']}`,
+        reason: 'invalid --idle-timeout',
+      });
+    }
+  }
+
   const configOverrides = {};
   if (globals.db_path) configOverrides.db_path = globals.db_path;
   if (globals.log_level) configOverrides.log_level = globals.log_level;
@@ -16,8 +92,9 @@ export async function cmdSubscribe(args, globals) {
   const config = loadConfig(configOverrides);
   const db = openDb(config);
 
-  const plugin = args.plugin;
-  const filter = args.filter;
+  // event_type_filter is NOT NULL; default an absent (or value-less) --filter
+  // to the catch-all '*' so subscribe does not fall through to a DB error.
+  const filter = typeof args.filter === 'string' ? args.filter : '*';
   const pollIntervalMs = Number(args['poll-interval-ms']) || 1000;
   const batchSize = Number(args['batch-size']) || 100;
   const noAck = args['no-ack'] === true;
@@ -40,10 +117,14 @@ export async function cmdSubscribe(args, globals) {
     if (existing.length === 1) {
       cursorId = existing[0].cursor_id;
     } else if (existing.length > 1) {
-      throw new Error(
-        'Multiple active subscriptions match plugin + filter. ' +
-        'Provide --cursor-id to disambiguate.'
-      );
+      throw new WBError('WB-001', 'INVALID_EVENT_SCHEMA', {
+        message:
+          'Multiple active subscriptions match plugin + filter. ' +
+          'Provide --cursor-id to disambiguate.',
+        reason: 'ambiguous subscription',
+        plugin,
+        filter,
+      });
     } else {
       // Auto-register
       const cursorInit = args['cursor-init'] || 'latest';
@@ -52,6 +133,14 @@ export async function cmdSubscribe(args, globals) {
     }
   }
 
+  // Drain mode: short-lived, no background sweep, exits when the queue is
+  // drained (optionally after an idle window). Process exit is the wake signal.
+  if (drainMode) {
+    await runDrain(db, cursorId, { batchSize, noAck, pollIntervalMs, idleTimeoutMs });
+    db.close();
+    return;
+  }
+
   // Start background sweep
   const sweepHandle = startSweep(db, config);
 
@@ -100,3 +189,71 @@ export async function cmdSubscribe(args, globals) {
     await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
   }
 }
+
+/**
+ * Drain mode: deliver every event pending past the cursor, then return.
+ *
+ * Pages through the backlog with an in-memory floor so that `--no-ack` works
+ * correctly even when the backlog exceeds one batch: the durable cursor never
+ * moves, but the floor still advances so the next poll returns the next page
+ * rather than re-reading the same one. In ack mode both advance together.
+ *
+ * With `idleTimeoutMs`, the loop blocks for new events after the queue empties
+ * (the timer resets on each delivery) and exits once the window elapses idle.
+ * Without it, the loop exits the moment the queue is empty.
+ *
+ * stdout stays a pure NDJSON event stream; a one-line summary goes to stderr.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} cursorId
+ * @param {{ batchSize: number, noAck: boolean, pollIntervalMs: number, idleTimeoutMs: number|null }} opts
+ */
+async function runDrain(db, cursorId, opts) {
+  const { batchSize, noAck, pollIntervalMs, idleTimeoutMs } = opts;
+
+  const cursor = db.prepare(
+    'SELECT last_event_id FROM cursors WHERE cursor_id = ?'
+  ).get(cursorId);
+  let floor = cursor ? cursor.last_event_id : 0;
+
+  let delivered = 0;
+  let stopping = false;
+  const onSignal = () => { stopping = true; };
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+
+  try {
+    let idleDeadline = idleTimeoutMs != null ? Date.now() + idleTimeoutMs : null;
+    while (!stopping) {
+      const events = poll(db, cursorId, { batchSize, afterEventId: floor });
+
+      if (events.length > 0) {
+        for (const event of events) {
+          process.stdout.write(JSON.stringify(event) + '\n');
+          floor = event.event_id;
+          if (!noAck) ack(db, cursorId, event.event_id);
+          delivered++;
+        }
+        // Activity resets the idle window.
+        if (idleTimeoutMs != null) idleDeadline = Date.now() + idleTimeoutMs;
+        // Re-poll immediately to drain a backlog larger than one batch.
+        continue;
+      }
+
+      // Queue empty.
+      if (idleTimeoutMs == null) break;          // plain drain — done
+      if (Date.now() >= idleDeadline) break;      // idle window elapsed
+      const remaining = idleDeadline - Date.now();
+      await new Promise(r => setTimeout(r, Math.min(pollIntervalMs, remaining)));
+    }
+  } finally {
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+  }
+
+  process.stderr.write(JSON.stringify({
+    drained: delivered,
+    acked: !noAck,
+    last_event_id: floor,
+  }) + '\n');
+}

package/lib/index.js

@@ -13,3 +13,41 @@ export { startSweep, runSweep } from './sweep.js';
 export { listDeadLetters, replayDeadLetter, dropDeadLetter } from './dlq.js';
 export { subscribe } from './subscribe.js';
 export { WBError, ERROR_CODES, EXIT_CODES } from './errors.js';
+
+// ── v2 surface (#10) ────────────────────────────────────────────────────────
+// Opt-in features that previously could only be exercised through the CLI
+// binary. Each re-export is additive — the 1.x surface above is unchanged — and
+// safe to import even when the underlying feature is disabled: importing does
+// not start a daemon, open a socket, or enforce a schema. Names match the real
+// module exports (the original proposal referenced a few that never shipped:
+// `applyRegistryPolicy` is `applyOnEmit`; CAS is exposed as a namespace rather
+// than flat `casRead`/`casWrite`/`gcCas` to avoid generic names at the root).
+
+// Push-or-poll subscriber: prefers the daemon's push delivery, falls back to
+// polling when no daemon is reachable.
+export { subscribePushOrPoll } from './subscribe-push-or-poll.js';
+
+// Daemon client: probe for a running daemon and connect as a push subscriber.
+export { probeDaemon, connectAsSubscriber } from './daemon-client.js';
+
+// Lower-level daemon integration: notify the daemon of a freshly emitted row.
+export { notifyEmit } from './daemon-notify.js';
+
+// Causality propagation (AsyncLocalStorage): run work within a correlation
+// context and read the active context.
+export { withContext, currentContext } from './causality.js';
+
+// JSON Schema registry: look up a registered schema and apply registry policy
+// (validate / coerce) to a payload at emit time.
+export { getSchema, applyOnEmit } from './schema-registry.js';
+
+// Tiered-storage sweep with monthly archive buckets.
+export { runSweepV2 } from './sweep-v2.js';
+
+// Cross-tier resolving poll (live + archived buckets).
+export { pollResolve } from './query.js';
+
+// Content-addressable store for large payloads. Namespaced because the module
+// uses intentionally generic verbs (`put`, `get`, `gc`); reach them as
+// `cas.put(...)`, `cas.get(...)`, `cas.gc(...)`, etc.
+export * as cas from './cas.js';

package/lib/poll.js

@@ -96,6 +96,12 @@ function buildFilterSql(filterStr) {
  * @param {string} cursorId
  * @param {object} [options]
  * @param {number} [options.batchSize=100]
+ * @param {number} [options.afterEventId] - Read-only floor override. When set,
+ *   events are returned with `event_id > afterEventId` instead of the cursor's
+ *   persisted `last_event_id`. The cursor is NOT mutated. Lets a caller page
+ *   through events without acking (e.g. a `--drain --no-ack` consumer that
+ *   advances an in-memory floor). The WB-003 staleness check still uses the
+ *   persisted cursor position.
  * @returns {object[]} Array of event rows
  */
 export function poll(db, cursorId, options = {}) {
@@ -143,6 +149,12 @@ export function poll(db, cursorId, options = {}) {
   const { where, params } = buildFilterSql(filter);
   const now = Date.now();
 
+  // afterEventId is a read-only floor override (does not persist). Fall back to
+  // the cursor's durable position when not supplied.
+  const lastEventId = options.afterEventId != null
+    ? options.afterEventId
+    : cursor.last_event_id;
+
   const sql = `
     SELECT * FROM events
     WHERE event_id > :last_event_id
@@ -154,7 +166,7 @@ export function poll(db, cursorId, options = {}) {
 
   const allParams = {
     ...params,
-    last_event_id: cursor.last_event_id,
+    last_event_id: lastEventId,
     now,
     batch_size: batchSize,
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-bus",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Lightweight, local-first SQLite event bus for AI agents and developer tools",
   "type": "module",
   "exports": {
@@ -17,7 +17,7 @@
     "wicked-bus-install": "./install.mjs"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
@@ -33,7 +33,7 @@
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.4",
-    "better-sqlite3": "^11.0.0",
+    "better-sqlite3": "^12.0.0",
     "vitest": "^4.1.4"
   },
   "files": [