wicked-bus 2.1.1 → 2.2.1

package/README.md

@@ -146,7 +146,7 @@ Agent ecosystems have a communication problem. Tools that should work together
 
 ## Requirements
 
-- Node.js >= 18.0.0
+- Node.js >= 20.0.0
 - `better-sqlite3` >= 9.0.0 (peer dependency)
 - macOS, Linux, or Windows
 

package/commands/cli.js

@@ -4,8 +4,22 @@
  * wicked-bus CLI entry point.
  */
 
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import { WBError, EXIT_CODES } from '../lib/errors.js';
 
+// Resolve the package version from package.json (single source of truth).
+function readVersion() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch (_e) {
+    return '0.0.0';
+  }
+}
+
 // Argument parser. Returns flags + positional args (anything that isn't --flag
 // or its value). Positional args are needed for subcommands like `dlq list`.
 function parseArgs(argv) {
@@ -56,6 +70,15 @@ function handleError(err) {
 async function main() {
   const argv = process.argv.slice(2);
   const command = argv[0];
+
+  // `--version` / `-v` prints the package version and exits 0. Handled before
+  // command dispatch so health probes (e.g. wicked-loom's doctor) get a clean
+  // version string instead of the usage/help JSON.
+  if (command === '--version' || command === '-v') {
+    process.stdout.write(readVersion() + '\n');
+    process.exit(0);
+  }
+
   const flagArgv = argv.slice(1);
   const args = parseArgs(flagArgv);
 

package/lib/atomic.js

@@ -0,0 +1,90 @@
+/**
+ * Cross-platform atomic file placement helpers.
+ *
+ * POSIX `rename(2)` atomically replaces an existing destination. Windows
+ * `MoveFileEx`-backed `fs.rename` REJECTS a rename onto an existing file with
+ * `EPERM` / `EEXIST` / `EACCES`, and may transiently fail with `EBUSY` when the
+ * destination (or a directory entry) is briefly held open by AV/indexer/another
+ * handle. POSIX never sees these for an overwrite.
+ *
+ * This module centralizes the cross-platform fallback so every "write to a temp
+ * file, then rename it into final position" site behaves identically and can't
+ * regress independently.
+ *
+ * @module lib/atomic
+ */
+
+import fs from 'node:fs';
+
+// Number of times we retry a transient EBUSY on win32 before giving up, and the
+// backoff between attempts. Kept tiny — EBUSY here is from a momentary handle
+// (AV scan / indexer), not sustained contention. Synchronous spin-wait so the
+// helper stays drop-in for the existing synchronous CAS/fs codepaths.
+const WIN32_EBUSY_RETRIES = 5;
+const WIN32_EBUSY_BACKOFF_MS = 20;
+
+function sleepSync(ms) {
+  // Busy-ish wait without pulling in a dependency. Used only on the win32 EBUSY
+  // retry path, which is rare and short.
+  const end = Date.now() + ms;
+  while (Date.now() < end) { /* spin */ }
+}
+
+/**
+ * Rename `tmp` onto `target`, overwriting any existing `target` atomically.
+ *
+ * On POSIX a single `renameSync` already overwrites atomically. On win32, if the
+ * rename is rejected because `target` exists (EPERM/EEXIST/EACCES) we unlink the
+ * destination then retry the rename; a transient EBUSY is retried with a short
+ * backoff. On any unrecoverable failure the `tmp` file is cleaned up before the
+ * error is rethrown so we never leak partial temp files.
+ *
+ * @param {string} tmp     path to the fully-written temp file
+ * @param {string} target  final destination path
+ * @param {object} [opts]
+ * @param {string[]} [opts.swallowCodes]  on POSIX-or-win32, rethrow is skipped
+ *                                         for these error codes (e.g. ['EEXIST']
+ *                                         for content-addressed no-op races). The
+ *                                         tmp file is still cleaned up.
+ */
+export function atomicRename(tmp, target, opts = {}) {
+  const swallow = new Set(opts.swallowCodes ?? []);
+  const isWin = process.platform === 'win32';
+
+  try {
+    fs.renameSync(tmp, target);
+    return;
+  } catch (e) {
+    // win32: rename-over-existing is rejected. Unlink the destination and retry.
+    if (isWin && (e.code === 'EPERM' || e.code === 'EEXIST' || e.code === 'EACCES' || e.code === 'EBUSY')) {
+      let lastErr = e;
+      for (let attempt = 0; attempt <= WIN32_EBUSY_RETRIES; attempt++) {
+        try {
+          // Remove the destination so the rename has a clear path. The
+          // destination may legitimately not exist (pure EBUSY on the source),
+          // so a failing unlink is non-fatal.
+          try { fs.unlinkSync(target); } catch (_e) { /* may not exist */ }
+          fs.renameSync(tmp, target);
+          return;
+        } catch (retryErr) {
+          lastErr = retryErr;
+          // Only EBUSY is worth retrying — it's the transient AV/indexer hold.
+          if (retryErr.code === 'EBUSY' && attempt < WIN32_EBUSY_RETRIES) {
+            sleepSync(WIN32_EBUSY_BACKOFF_MS);
+            continue;
+          }
+          break;
+        }
+      }
+      // Exhausted retries (or a non-EBUSY error on the fallback path).
+      try { fs.unlinkSync(tmp); } catch (_e) { /* avoid leaking the temp file */ }
+      if (swallow.has(lastErr.code)) return;
+      throw lastErr;
+    }
+
+    // POSIX (or a win32 error we don't special-case). Clean up the temp file.
+    try { fs.unlinkSync(tmp); } catch (_e) { /* avoid leaking the temp file */ }
+    if (swallow.has(e.code)) return;
+    throw e;
+  }
+}

package/lib/cas.js

@@ -23,6 +23,7 @@ import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { WBError } from './errors.js';
 import { archiveDir, listBuckets } from './archive.js';
+import { atomicRename } from './atomic.js';
 
 const require = createRequire(import.meta.url);
 
@@ -102,14 +103,11 @@ export function put(dataDir, content, opts = {}) {
     }
   }
 
-  try {
-    fs.renameSync(tmp, target);
-  } catch (e) {
-    // Race: another writer just moved their copy into place. Same SHA →
-    // identical content → safe to drop ours.
-    try { fs.unlinkSync(tmp); } catch (_e) { /* ignore */ }
-    if (e.code !== 'EEXIST') throw e;
-  }
+  // Cross-platform atomic placement. POSIX rename overwrites atomically;
+  // Windows rejects rename-over-existing (EPERM/EEXIST/EACCES) and may hit a
+  // transient EBUSY — atomicRename() handles both. EEXIST is swallowed because
+  // a concurrent writer placing identical content (same SHA) is a safe no-op.
+  atomicRename(tmp, target, { swallowCodes: ['EEXIST'] });
 
   return sha;
 }

package/lib/poll.js

@@ -7,6 +7,20 @@ import { WBError } from './errors.js';
 
 /**
  * Match an event against a filter string.
+ *
+ * Wildcard semantics (trailing only):
+ * - `prefix.*`  — SINGLE-level: matches `prefix.<one-segment>` and nothing
+ *   deeper. `wicked.test.*` matches `wicked.test.run` but NOT
+ *   `wicked.test.run.completed`. Unchanged from v1; existing subscribers keep
+ *   their exact behavior.
+ * - `prefix.**` — MULTI-level: matches `prefix.<one-or-more-segments>`.
+ *   `wicked.**` matches `wicked.fact.extracted` AND `wicked.test.run.completed`.
+ *   This is the "everything under a prefix" filter the naming convention
+ *   implies (every event is `wicked.<noun>.<verb>`, i.e. 3+ segments, so a
+ *   single-level `wicked.*` would match nothing). At least one trailing
+ *   segment is required — `**` does not match the bare prefix itself.
+ * - `*`         — CATCH-ALL (typically `*@domain`): matches every type.
+ *
  * @param {string} eventType - The event_type to test
  * @param {string} domain - The domain of the event
  * @param {string} filterStr - Filter pattern, e.g. 'wicked.test.run.*@wicked-testing'
@@ -32,18 +46,40 @@ export function matchesFilter(eventType, domain, filterStr) {
   // Exact match
   if (typePattern === eventType) return true;
 
+  // Multi-level wildcard (prefix.**) — one or more remaining segments.
+  // Checked before the single-level case so the `.**` suffix is not
+  // mis-parsed as `.*` with a trailing `*` segment.
+  if (typePattern.endsWith('.**')) {
+    const prefix = typePattern.slice(0, -3);
+    if (eventType.startsWith(prefix + '.')) {
+      const remainder = eventType.slice(prefix.length + 1);
+      return remainder.length > 0; // at least one trailing segment
+    }
+    return false;
+  }
+
   // Single-level wildcard (prefix.*)
   if (typePattern.endsWith('.*')) {
     const prefix = typePattern.slice(0, -2);
     if (eventType.startsWith(prefix + '.')) {
       const remainder = eventType.slice(prefix.length + 1);
-      return !remainder.includes('.'); // single-level only
+      return remainder.length > 0 && !remainder.includes('.'); // single-level only
     }
   }
 
   return false;
 }
 
+/**
+ * Escape characters that are special to SQLite's LIKE operator so a filter
+ * prefix is matched literally. Pairs with `ESCAPE '\\'` in the query.
+ * @param {string} s
+ * @returns {string}
+ */
+function escapeLike(s) {
+  return s.replace(/[\\%_]/g, (ch) => '\\' + ch);
+}
+
 /**
  * Build SQL WHERE clauses from a filter string for optimized queries.
  * @param {string} filterStr
@@ -69,15 +105,25 @@ function buildFilterSql(filterStr) {
     params.domain_filter = domainFilter;
   }
 
-  // Type filter
+  // Type filter — must mirror matchesFilter() exactly.
+  // LIKE escaping note: SQLite LIKE treats `%` and `_` as wildcards. Event
+  // types use only `[a-z0-9._-]`, so `_` could theoretically appear and
+  // over-match a single char. We add an ESCAPE clause and escape `_`/`%`/`\`
+  // in the prefix to keep SQL matching faithful to matchesFilter().
   if (typePattern === '*') {
     // Catch-all: no type filter
+  } else if (typePattern.endsWith('.**')) {
+    // Multi-level: prefix.<one-or-more-segments>
+    const prefix = typePattern.slice(0, -3);
+    conditions.push("event_type LIKE :prefix_like ESCAPE '\\'");
+    params.prefix_like = escapeLike(prefix) + '.%';
   } else if (typePattern.endsWith('.*')) {
+    // Single-level: prefix.<exactly-one-segment>
     const prefix = typePattern.slice(0, -2);
-    conditions.push("event_type LIKE :prefix_like");
-    conditions.push("event_type NOT LIKE :prefix_multi");
-    params.prefix_like = prefix + '.%';
-    params.prefix_multi = prefix + '.%.%';
+    conditions.push("event_type LIKE :prefix_like ESCAPE '\\'");
+    conditions.push("event_type NOT LIKE :prefix_multi ESCAPE '\\'");
+    params.prefix_like = escapeLike(prefix) + '.%';
+    params.prefix_multi = escapeLike(prefix) + '.%.%';
   } else {
     // Exact match
     conditions.push('event_type = :exact_type');

package/lib/subscribe-push-or-poll.js

@@ -35,6 +35,24 @@ export const DEFAULT_REPROBE_INTERVAL_MS = 5000;
 export const DEFAULT_PROBE_TIMEOUT_MS    = 100;
 
 /**
+ * ── DELIVERY GUARANTEE: AT-MOST-ONCE (per consumer) ────────────────────────
+ * Each frame is ACK'd (the v1 cursor is durably advanced) BEFORE it is yielded
+ * to the caller's `for await` loop. If the loop body throws or the process
+ * crashes AFTER receiving an event but BEFORE finishing its work, the cursor
+ * has already moved past that event — it will NOT be re-delivered. The cursor
+ * here means "events handed off to the consumer", not "events the consumer
+ * finished processing".
+ *
+ * This is the OPPOSITE guarantee from {@link import('./subscribe.js').subscribe},
+ * the managed `subscribe()` helper, which acks AFTER the handler succeeds
+ * (at-least-once, with retry + DLQ). Pick this push-or-poll iterable only when
+ * duplicate processing is unacceptable and dropping an event on a mid-stream
+ * failure is tolerable. If you need at-least-once + retry + dead-lettering, use
+ * `subscribe()` instead.
+ *
+ * WARNING: do not assume "I received it" == "it is safe". A throw inside the
+ * `for await` body silently loses the in-flight event.
+ *
  * @param {object} opts
  * @param {import('better-sqlite3').Database} opts.db          - live DB connection (poll fallback + pointer resolution)
  * @param {string}  opts.cursor_id

package/lib/subscribe.js

@@ -214,6 +214,21 @@ function computeLag(db, cursorId) {
 /**
  * Subscribe to events with a managed loop, retry, DLQ, and lifecycle.
  *
+ * ── DELIVERY GUARANTEE: AT-LEAST-ONCE ──────────────────────────────────────
+ * The handler is invoked BEFORE the cursor is acked. If the handler throws,
+ * the event is retried (up to `maxRetries`) and only dead-lettered + acked
+ * once the retry budget is exhausted. A crash between "handler succeeded" and
+ * "ack persisted" re-delivers the event on the next poll. Therefore the
+ * handler MAY see the same logical event more than once and MUST be idempotent
+ * (the bus already enforces emit-side idempotency via the `idempotency_key`
+ * UNIQUE constraint; consumers must enforce their own on the consume side).
+ *
+ * This is the OPPOSITE guarantee from {@link subscribePushOrPoll}, which acks
+ * BEFORE yielding (at-most-once). Choose `subscribe()` when losing an event is
+ * worse than processing it twice (the common case); choose
+ * `subscribePushOrPoll()` only when re-processing is unacceptable and dropping
+ * an event on a mid-stream failure is tolerable.
+ *
  * @param {object} opts
  * @param {import('better-sqlite3').Database} opts.db - Open DB handle (required)
  * @param {string} opts.plugin - Subscriber plugin identity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-bus",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "description": "Lightweight, local-first SQLite event bus for AI agents and developer tools",
   "type": "module",
   "exports": {

package/skills/wicked-bus/subscribe/SKILL.md

@@ -138,16 +138,22 @@ async function checkBusEvents() {
 | Pattern | Matches |
 |---------|---------|
 | `wicked.run.completed` | Exact match only |
-| `wicked.run.*` | All `wicked.run.` events (single-level wildcard) |
+| `wicked.run.*` | `wicked.run.<one-segment>` — single-level wildcard |
+| `wicked.run.**` | `wicked.run.<one-or-more-segments>` — multi-level wildcard |
+| `wicked.**` | Everything under `wicked.` (every `wicked.<noun>.<verb>` event) |
 | `*@wicked-brain` | All events from the `wicked-brain` domain |
-| `wicked.memory.*@wicked-brain` | Memory events from brain only |
+| `wicked.memory.*@wicked-brain` | Memory events (single-level) from brain only |
 
 ### Filter rules
 
 1. `*` matches exactly one segment (single-level wildcard)
-2. `@domain` suffix scopes by the `domain` column
-3. Wildcards and `@domain` can combine: `wicked.run.*@my-plugin`
-4. `*` alone (catch-all) is valid but noisy
+2. `**` matches one or more segments (multi-level wildcard). Event types are
+   `wicked.<noun>.<verb>` (3+ segments), so to subscribe to "everything under
+   `wicked`" use `wicked.**`, not `wicked.*` (which would match nothing).
+3. A trailing `**` requires at least one segment after the prefix.
+4. `@domain` suffix scopes by the `domain` column
+5. Wildcards and `@domain` can combine: `wicked.run.*@my-plugin` or `wicked.run.**@my-plugin`
+6. `*` alone (catch-all) is valid but noisy
 
 ## Delivery Semantics