wicked-bus 2.2.0 → 2.2.2

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/package.json

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

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

@@ -150,3 +150,105 @@ into event_type forces subscribers to enumerate every producer.
 **Why subdomain is a column (not in event_type):**
 `wicked.phase.started` is semantic. Whether it's `crew.phase` or `deploy.phase`
 is identity, not semantics. Columns enable index-based filtering.
+
+## Worked example: lifecycle & gate events
+
+> **This is an illustrative pattern, not a mandate.** wicked-bus does not ship,
+> register, or enforce a lifecycle catalog — skills teach conventions, they do
+> **not** hardcode other plugins' event catalogs. Treat the names below as an
+> example that a multi-stage pipeline tool **MAY** adopt to stay consistent with the
+> `wicked.<noun>.<past-tense-verb>` convention. Pick the nouns/verbs that fit
+> your domain; nothing here is reserved.
+
+Many ecosystem tools run a **staged, gated pipeline** — an engine that moves work
+through ordered stages, with governance gates between them (for example a
+migration pipeline with stages like *discover → knowledge-base → spec → plan →
+transform → validate → deliver/cutover*, each guarded by an approval gate). Such a
+tool needs a consistent way to signal "a stage was entered/completed" and "a gate
+cleared/blocked" so other tools can observe progress.
+
+Here is one internally-consistent way to name those events under the existing
+convention.
+
+### Suggested event types
+
+| Event type | Emitted when | Notes |
+|------------|--------------|-------|
+| `wicked.stage.entered` | A pipeline stage begins | noun=`stage`, verb=`entered` |
+| `wicked.stage.completed` | A stage finishes successfully | mirror of `entered` |
+| `wicked.gate.cleared` | A governance gate passes | the "go" signal |
+| `wicked.gate.blocked` | A gate fails / withholds approval | the "stop" signal |
+| `wicked.pipeline.completed` | The whole pipeline reaches its terminal milestone (e.g. delivery/cutover) | terminal milestone — stage carried in `subdomain` |
+
+All five satisfy the rules: `wicked.` prefix, three segments, past-tense verb,
+no domain or subdomain baked in. They are **semantic** — any pipeline engine
+emitting "a stage was entered" shares `wicked.stage.entered`, regardless of which
+tool it is.
+
+### Suggested domain & subdomain
+
+- **`domain`** = the engine/orchestrator's identity (its package or tool name),
+  e.g. `domain = "engine"` (or `migration-factory`, `anti-legacy`, …). One domain
+  per engine — don't subdivide here.
+- **`subdomain`** = `lifecycle.<stage>` — the functional area plus the specific
+  stage the event concerns, e.g. `lifecycle.transform`, `lifecycle.validate`,
+  `lifecycle.cutover`. *Which* stage is identity, not semantics, so it belongs in
+  the column, never in the event_type.
+
+### How a multi-stage pipeline names its transitions
+
+A 7-stage pipeline does **not** invent a new event_type per stage. It reuses the
+five semantic types above and distinguishes the stage via `subdomain`:
+
+```javascript
+import { emit } from 'wicked-bus';
+
+// Entering the "transform" stage
+emit(db, config, {
+  event_type: 'wicked.stage.entered',
+  domain: 'engine',
+  subdomain: 'lifecycle.transform',
+  payload: { stage: 'transform', stage_number: 5, ref: '<authoritative-state-id>' },
+});
+
+// The gate guarding the transform→validate transition clears
+emit(db, config, {
+  event_type: 'wicked.gate.cleared',
+  domain: 'engine',
+  subdomain: 'lifecycle.transform',
+  payload: { gate: 'transform', approver: 'architect', spec_version: '3.2.0' },
+});
+
+// A later gate withholds approval
+emit(db, config, {
+  event_type: 'wicked.gate.blocked',
+  domain: 'engine',
+  subdomain: 'lifecycle.validate',
+  payload: { gate: 'validate', reason: 'acceptance criteria not green' },
+});
+```
+
+### Why this shape filters well
+
+Because the stage lives in `subdomain` and the engine in `domain`, subscribers
+get expressive filters for free:
+
+```bash
+# Every gate outcome from any engine, any stage
+wicked-bus subscribe --filter 'wicked.gate.*'
+
+# Every stage transition from any engine, any stage
+wicked-bus subscribe --filter 'wicked.stage.*'
+
+# Everything a specific engine emits across its whole lifecycle
+wicked-bus subscribe --filter '*@engine'
+```
+
+### The bus is transport, not the system of record
+
+These events **announce** transitions; they do not **store** lifecycle state. The
+bus is fire-and-forget transport and TTL-sweeps payloads — authoritative lifecycle
+state (which stage you're in, who signed which gate) lives in the pipeline tool's
+own durable store (its spec headers, DB, or audit log), not on the bus. Put a
+reference (an id) in the payload and resolve details from the system of record;
+never treat a polled event as the source of truth for current state.