wicked-bus 1.0.0

package/README.md

@@ -0,0 +1,153 @@
+```
+ ██╗    ██╗██╗ ██████╗██╗  ██╗███████╗██████╗     ██████╗ ██╗   ██╗███████╗
+ ██║    ██║██║██╔════╝██║ ██╔╝██╔════╝██╔══██╗    ██╔══██╗██║   ██║██╔════╝
+ ██║ █╗ ██║██║██║     █████╔╝ █████╗  ██║  ██║    ██████╔╝██║   ██║███████╗
+ ██║███╗██║██║██║     ██╔═██╗ ██╔══╝  ██║  ██║    ██╔══██╗██║   ██║╚════██║
+ ╚███╔███╔╝██║╚██████╗██║  ██╗███████╗██████╔╝    ██████╔╝╚██████╔╝███████║
+  ╚══╝╚══╝ ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝╚═════╝     ╚═════╝  ╚═════╝ ╚══════╝
+```
+
+A lightweight, local-first event bus for AI agents and developer tools.
+
+SQLite-backed, single-host, poll-based delivery with at-least-once semantics. No servers, no network transport, no infrastructure. Events stay on your machine.
+
+Built for agent ecosystems where multiple tools need to communicate without coupling to each other — AI coding assistants, test runners, knowledge systems, deployment tools, or anything that benefits from local event-driven architecture.
+
+## Quick Start
+
+### Install
+
+```bash
+npm install wicked-bus
+```
+
+`better-sqlite3` is a required peer dependency (compiles a native addon).
+
+### Initialize
+
+```bash
+wicked-bus init
+```
+
+Creates `~/.something-wicked/wicked-bus/` with a WAL-mode SQLite database.
+
+### Emit an event
+
+```bash
+wicked-bus emit \
+  --type wicked.task.completed \
+  --domain my-plugin \
+  --payload '{"taskId": "abc", "status": "done"}'
+```
+
+### Subscribe to events
+
+```bash
+wicked-bus subscribe --filter 'wicked.task.*'
+```
+
+Streams events as NDJSON. Use `--filter` with wildcards and `@domain` scoping.
+
+## Programmatic API
+
+```javascript
+import { emit, poll, ack, register } from 'wicked-bus';
+import { loadConfig } from 'wicked-bus/lib/config.js';
+import { openDb } from 'wicked-bus/lib/db.js';
+
+const config = loadConfig();
+const db = openDb(config);
+
+// Emit
+const result = emit(db, config, {
+  event_type: 'wicked.deploy.completed',
+  domain: 'my-deploy',
+  subdomain: 'deploy.production',
+  payload: { version: '2.0.0' },
+});
+
+// Subscribe
+const sub = register(db, {
+  plugin: 'my-consumer',
+  role: 'subscriber',
+  event_type_filter: 'wicked.deploy.*',
+  cursor_init: 'latest',
+});
+
+// Poll
+const events = poll(db, config, {
+  cursor_id: sub.cursor_id,
+  filter: 'wicked.deploy.*',
+});
+
+// Acknowledge
+if (events.events.length > 0) {
+  const lastId = events.events.at(-1).event_id;
+  ack(db, { cursor_id: sub.cursor_id, event_id: lastId });
+}
+
+db.close();
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Create data directory and database |
+| `emit` | Publish an event |
+| `subscribe` | Stream events matching a filter |
+| `status` | Show bus health and stats |
+| `register` | Register as provider or subscriber |
+| `deregister` | Soft-delete a registration |
+| `list` | List registrations |
+| `ack` | Acknowledge events (advance cursor) |
+| `replay` | Reset a cursor to a specific position |
+| `cleanup` | Run TTL sweep (delete expired events) |
+
+All commands output structured JSON. Errors go to stderr with error codes (WB-001 through WB-006).
+
+## AI CLI Skills
+
+wicked-bus ships skills for AI coding assistants (Claude, Gemini, Copilot, Codex, Cursor).
+
+### Install skills
+
+```bash
+npx wicked-bus-install
+```
+
+Auto-detects installed CLIs and copies skills. Available skills:
+
+| Skill | Purpose |
+|-------|---------|
+| `wicked-bus/init` | Initialize or connect to the bus |
+| `wicked-bus/emit` | Publish events |
+| `wicked-bus/subscribe` | Consume events |
+| `wicked-bus/naming` | Event naming conventions |
+| `wicked-bus/query` | Query and debug |
+
+## Why wicked-bus?
+
+Agent ecosystems have a communication problem. Tools that should work together — test runners, code reviewers, knowledge systems, deployment pipelines — end up tightly coupled or completely siloed. wicked-bus solves this with a dead-simple local event bridge.
+
+- **Local-first**: everything lives in a single SQLite file. No servers to run, no ports to manage, no infrastructure.
+- **At-least-once delivery**: cursors persist across restarts. Unacked events are re-delivered. No lost events.
+- **Fire-and-forget**: producers are non-blocking. The bus never slows the caller. If it's not installed, callers degrade gracefully.
+- **Agent-native**: designed for AI coding assistants and the tools around them. Ships with skills for Claude, Gemini, Copilot, Codex, and Cursor.
+- **Two-timer TTL**: events auto-expire. No manual cleanup, no unbounded growth.
+
+## Documentation
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) -- system design and module structure
+- [USERS_GUIDE.md](./USERS_GUIDE.md) -- event naming, payload conventions, integration patterns
+- [reqs/SPEC.md](./reqs/SPEC.md) -- full specification
+
+## Requirements
+
+- Node.js >= 18.0.0
+- `better-sqlite3` >= 9.0.0 (peer dependency)
+- macOS, Linux, or Windows
+
+## License
+
+MIT

package/commands/cli.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+/**
+ * wicked-bus CLI entry point.
+ */
+
+import { WBError, EXIT_CODES } from '../lib/errors.js';
+
+// Argument parser
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      if (i + 1 >= argv.length || argv[i + 1].startsWith('--')) {
+        args[key] = true;
+      } else {
+        args[key] = argv[++i];
+      }
+    }
+  }
+  return args;
+}
+
+function printUsage() {
+  const usage = {
+    usage: 'wicked-bus <command> [options]',
+    commands: [
+      'init', 'emit', 'subscribe', 'status', 'replay',
+      'cleanup', 'register', 'deregister', 'list', 'ack',
+    ],
+    global_flags: ['--db-path <path>', '--json', '--log-level <level>'],
+  };
+  process.stdout.write(JSON.stringify(usage, null, 2) + '\n');
+}
+
+function handleError(err) {
+  if (err instanceof WBError) {
+    process.stderr.write(JSON.stringify(err.toJSON()) + '\n');
+    process.exit(EXIT_CODES[err.error] || 1);
+  }
+  process.stderr.write(JSON.stringify({
+    error: 'UNKNOWN',
+    code: 'INTERNAL_ERROR',
+    message: err.message,
+  }) + '\n');
+  process.exit(1);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const command = argv[0];
+  const flagArgv = argv.slice(1);
+  const args = parseArgs(flagArgv);
+
+  // Extract global flags
+  const globals = {
+    db_path: args['db-path'] || null,
+    json: args.json !== false,
+    log_level: args['log-level'] || null,
+  };
+
+  // Remove global flags from args
+  delete args['db-path'];
+  delete args.json;
+  delete args['log-level'];
+
+  try {
+    switch (command) {
+      case 'init': {
+        const { cmdInit } = await import('./cmd-init.js');
+        await cmdInit(args, globals);
+        break;
+      }
+      case 'emit': {
+        const { cmdEmit } = await import('./cmd-emit.js');
+        await cmdEmit(args, globals);
+        break;
+      }
+      case 'subscribe': {
+        const { cmdSubscribe } = await import('./cmd-subscribe.js');
+        await cmdSubscribe(args, globals);
+        break;
+      }
+      case 'status': {
+        const { cmdStatus } = await import('./cmd-status.js');
+        await cmdStatus(args, globals);
+        break;
+      }
+      case 'replay': {
+        const { cmdReplay } = await import('./cmd-replay.js');
+        await cmdReplay(args, globals);
+        break;
+      }
+      case 'cleanup': {
+        const { cmdCleanup } = await import('./cmd-cleanup.js');
+        await cmdCleanup(args, globals);
+        break;
+      }
+      case 'register': {
+        const { cmdRegister } = await import('./cmd-register.js');
+        await cmdRegister(args, globals);
+        break;
+      }
+      case 'deregister': {
+        const { cmdDeregister } = await import('./cmd-deregister.js');
+        await cmdDeregister(args, globals);
+        break;
+      }
+      case 'list': {
+        const { cmdList } = await import('./cmd-list.js');
+        await cmdList(args, globals);
+        break;
+      }
+      case 'ack': {
+        const { cmdAck } = await import('./cmd-ack.js');
+        await cmdAck(args, globals);
+        break;
+      }
+      default:
+        printUsage();
+        process.exit(command ? 1 : 0);
+    }
+  } catch (err) {
+    handleError(err);
+  }
+}
+
+main();

package/commands/cmd-ack.js

@@ -0,0 +1,31 @@
+/**
+ * wicked-bus ack command.
+ */
+
+import { loadConfig } from '../lib/config.js';
+import { openDb } from '../lib/db.js';
+import { ack } from '../lib/poll.js';
+
+export async function cmdAck(args, globals) {
+  const configOverrides = {};
+  if (globals.db_path) configOverrides.db_path = globals.db_path;
+  if (globals.log_level) configOverrides.log_level = globals.log_level;
+
+  const config = loadConfig(configOverrides);
+  const db = openDb(config);
+
+  const cursorId = args['cursor-id'];
+  const lastEventId = Number(args['last-event-id']);
+
+  if (!cursorId) {
+    throw new Error('--cursor-id is required');
+  }
+  if (isNaN(lastEventId)) {
+    throw new Error('--last-event-id must be a number');
+  }
+
+  const result = ack(db, cursorId, lastEventId);
+  db.close();
+
+  process.stdout.write(JSON.stringify(result) + '\n');
+}

package/commands/cmd-cleanup.js

@@ -0,0 +1,44 @@
+/**
+ * wicked-bus cleanup command -- sweep expired events.
+ */
+
+import { loadConfig } from '../lib/config.js';
+import { openDb } from '../lib/db.js';
+import { runSweep } from '../lib/sweep.js';
+
+export async function cmdCleanup(args, globals) {
+  const configOverrides = {};
+  if (globals.db_path) configOverrides.db_path = globals.db_path;
+  if (globals.log_level) configOverrides.log_level = globals.log_level;
+
+  const config = loadConfig(configOverrides);
+
+  // --archive flag overrides config
+  if (args.archive === true) {
+    config.archive_mode = true;
+  }
+
+  const db = openDb(config);
+  const dryRun = args['dry-run'] === true;
+
+  if (dryRun) {
+    const now = Date.now();
+    const count = db.prepare(
+      'SELECT COUNT(*) as count FROM events WHERE dedup_expires_at < ?'
+    ).get(now);
+
+    const result = {
+      events_deleted: count.count,
+      dry_run: true,
+    };
+    db.close();
+    process.stdout.write(JSON.stringify(result) + '\n');
+    return;
+  }
+
+  const result = runSweep(db, config);
+  result.dry_run = false;
+
+  db.close();
+  process.stdout.write(JSON.stringify(result) + '\n');
+}

package/commands/cmd-deregister.js

@@ -0,0 +1,26 @@
+/**
+ * wicked-bus deregister command.
+ */
+
+import { loadConfig } from '../lib/config.js';
+import { openDb } from '../lib/db.js';
+import { deregister } from '../lib/register.js';
+
+export async function cmdDeregister(args, globals) {
+  const configOverrides = {};
+  if (globals.db_path) configOverrides.db_path = globals.db_path;
+  if (globals.log_level) configOverrides.log_level = globals.log_level;
+
+  const config = loadConfig(configOverrides);
+  const db = openDb(config);
+
+  const subscriptionId = args['subscription-id'];
+  if (!subscriptionId) {
+    throw new Error('--subscription-id is required');
+  }
+
+  const result = deregister(db, subscriptionId);
+  db.close();
+
+  process.stdout.write(JSON.stringify(result) + '\n');
+}

package/commands/cmd-emit.js

@@ -0,0 +1,52 @@
+/**
+ * wicked-bus emit command.
+ */
+
+import { readFileSync } from 'node:fs';
+import { loadConfig } from '../lib/config.js';
+import { openDb } from '../lib/db.js';
+import { emit } from '../lib/emit.js';
+
+export async function cmdEmit(args, globals) {
+  const configOverrides = {};
+  if (globals.db_path) configOverrides.db_path = globals.db_path;
+  if (globals.log_level) configOverrides.log_level = globals.log_level;
+
+  const config = loadConfig(configOverrides);
+  const db = openDb(config);
+
+  // Parse payload -- support @file syntax
+  let payload = args.payload;
+  if (typeof payload === 'string' && payload.startsWith('@')) {
+    const filePath = payload.slice(1);
+    payload = readFileSync(filePath, 'utf8');
+  }
+
+  // Parse payload as JSON if it's a string
+  if (typeof payload === 'string') {
+    try {
+      payload = JSON.parse(payload);
+    } catch (_) {
+      // Will be caught by validation
+    }
+  }
+
+  const event = {
+    event_type: args.type,
+    domain: args.domain,
+    subdomain: args.subdomain || '',
+    payload,
+    schema_version: args['schema-version'] || undefined,
+    idempotency_key: args['idempotency-key'] || undefined,
+    metadata: args.metadata ? JSON.parse(args.metadata) : undefined,
+  };
+
+  if (args['ttl-hours'] != null) {
+    event.ttl_hours = Number(args['ttl-hours']);
+  }
+
+  const result = emit(db, config, event);
+  db.close();
+
+  process.stdout.write(JSON.stringify(result) + '\n');
+}

package/commands/cmd-init.js

@@ -0,0 +1,30 @@
+/**
+ * wicked-bus init command.
+ */
+
+import { ensureDataDir, resolveDbPath } from '../lib/paths.js';
+import { loadConfig, writeDefaultConfig } from '../lib/config.js';
+import { openDb } from '../lib/db.js';
+
+export async function cmdInit(args, globals) {
+  const dataDir = ensureDataDir();
+  const configOverrides = {};
+  if (globals.db_path) configOverrides.db_path = globals.db_path;
+  if (globals.log_level) configOverrides.log_level = globals.log_level;
+
+  // Write default config (won't overwrite unless --force)
+  writeDefaultConfig(dataDir, args.force === true);
+
+  const config = loadConfig(configOverrides);
+  const db = openDb(config);
+  const dbPath = resolveDbPath(config);
+  db.close();
+
+  const result = {
+    initialized: true,
+    data_dir: dataDir,
+    db_path: dbPath,
+  };
+
+  process.stdout.write(JSON.stringify(result) + '\n');
+}

package/commands/cmd-list.js

@@ -0,0 +1,39 @@
+/**
+ * wicked-bus list command.
+ */
+
+import { loadConfig } from '../lib/config.js';
+import { openDb } from '../lib/db.js';
+
+export async function cmdList(args, globals) {
+  const configOverrides = {};
+  if (globals.db_path) configOverrides.db_path = globals.db_path;
+  if (globals.log_level) configOverrides.log_level = globals.log_level;
+
+  const config = loadConfig(configOverrides);
+  const db = openDb(config);
+
+  let sql = 'SELECT * FROM subscriptions';
+  const conditions = [];
+  const params = {};
+
+  if (args.role) {
+    conditions.push('role = :role');
+    params.role = args.role;
+  }
+
+  if (!args['include-deregistered']) {
+    conditions.push('deregistered_at IS NULL');
+  }
+
+  if (conditions.length > 0) {
+    sql += ' WHERE ' + conditions.join(' AND ');
+  }
+
+  sql += ' ORDER BY registered_at DESC';
+
+  const rows = db.prepare(sql).all(params);
+  db.close();
+
+  process.stdout.write(JSON.stringify(rows) + '\n');
+}

package/commands/cmd-register.js

@@ -0,0 +1,29 @@
+/**
+ * wicked-bus register command.
+ */
+
+import { loadConfig } from '../lib/config.js';
+import { openDb } from '../lib/db.js';
+import { register } from '../lib/register.js';
+
+export async function cmdRegister(args, globals) {
+  const configOverrides = {};
+  if (globals.db_path) configOverrides.db_path = globals.db_path;
+  if (globals.log_level) configOverrides.log_level = globals.log_level;
+
+  const config = loadConfig(configOverrides);
+  const db = openDb(config);
+
+  const opts = {
+    plugin: args.plugin,
+    role: args.role,
+    filter: args.events || args.filter || '',
+    schema_version: args['schema-version'] || undefined,
+    cursor_init: args['cursor-init'] || 'latest',
+  };
+
+  const result = register(db, opts);
+  db.close();
+
+  process.stdout.write(JSON.stringify(result) + '\n');
+}

package/commands/cmd-replay.js

@@ -0,0 +1,65 @@
+/**
+ * wicked-bus replay command -- reset cursor to a specific event ID.
+ */
+
+import { loadConfig } from '../lib/config.js';
+import { openDb } from '../lib/db.js';
+import { WBError } from '../lib/errors.js';
+
+export async function cmdReplay(args, globals) {
+  const configOverrides = {};
+  if (globals.db_path) configOverrides.db_path = globals.db_path;
+  if (globals.log_level) configOverrides.log_level = globals.log_level;
+
+  const config = loadConfig(configOverrides);
+  const db = openDb(config);
+
+  const cursorId = args['cursor-id'];
+  const fromEventId = Number(args['from-event-id']);
+
+  if (!cursorId) {
+    throw new Error('--cursor-id is required');
+  }
+  if (isNaN(fromEventId)) {
+    throw new Error('--from-event-id must be a number');
+  }
+
+  // Verify cursor exists
+  const cursor = db.prepare(
+    'SELECT * FROM cursors WHERE cursor_id = ? AND deregistered_at IS NULL'
+  ).get(cursorId);
+
+  if (!cursor) {
+    throw new WBError('WB-006', 'CURSOR_NOT_FOUND', {
+      message: `Cursor not found: ${cursorId}`,
+      cursor_id: cursorId,
+      reason: 'cursor not found or deregistered',
+    });
+  }
+
+  // Check that from_event_id is not below the oldest available event
+  const oldest = db.prepare('SELECT MIN(event_id) as min_id FROM events').get();
+  if (oldest && oldest.min_id != null && fromEventId < oldest.min_id) {
+    throw new WBError('WB-003', 'CURSOR_BEHIND_TTL_WINDOW', {
+      message: `from_event_id ${fromEventId} is below the oldest available event (${oldest.min_id})`,
+      cursor_last_event_id: cursor.last_event_id,
+      oldest_available_event_id: oldest.min_id,
+    });
+  }
+
+  // Reset cursor to from_event_id - 1
+  const resetTo = fromEventId - 1;
+  db.prepare(
+    'UPDATE cursors SET last_event_id = ? WHERE cursor_id = ?'
+  ).run(resetTo, cursorId);
+
+  const result = {
+    replayed: true,
+    cursor_id: cursorId,
+    reset_to: resetTo,
+    from_event_id: fromEventId,
+  };
+
+  db.close();
+  process.stdout.write(JSON.stringify(result) + '\n');
+}

package/commands/cmd-status.js

@@ -0,0 +1,70 @@
+/**
+ * wicked-bus status command.
+ */
+
+import { loadConfig } from '../lib/config.js';
+import { openDb } from '../lib/db.js';
+import { resolveDbPath } from '../lib/paths.js';
+
+export async function cmdStatus(args, globals) {
+  const configOverrides = {};
+  if (globals.db_path) configOverrides.db_path = globals.db_path;
+  if (globals.log_level) configOverrides.log_level = globals.log_level;
+
+  const config = loadConfig(configOverrides);
+  const db = openDb(config);
+  const dbPath = resolveDbPath(config);
+
+  const totalEvents = db.prepare('SELECT COUNT(*) as count FROM events').get().count;
+  const oldest = db.prepare('SELECT MIN(event_id) as min_id FROM events').get();
+  const newest = db.prepare('SELECT MAX(event_id) as max_id FROM events').get();
+
+  // Events by type
+  const byType = db.prepare(
+    'SELECT event_type, COUNT(*) as count FROM events GROUP BY event_type'
+  ).all();
+  const eventsByType = {};
+  for (const row of byType) {
+    eventsByType[row.event_type] = row.count;
+  }
+
+  // Subscribers with lag
+  const subscribers = db.prepare(`
+    SELECT s.subscription_id, s.plugin, s.event_type_filter,
+           c.cursor_id, c.last_event_id, c.acked_at
+    FROM subscriptions s
+    JOIN cursors c ON c.subscription_id = s.subscription_id
+    WHERE s.role = 'subscriber' AND s.deregistered_at IS NULL AND c.deregistered_at IS NULL
+  `).all();
+
+  const newestId = newest.max_id || 0;
+  const subscriberList = subscribers.map(s => ({
+    subscription_id: s.subscription_id,
+    plugin: s.plugin,
+    filter: s.event_type_filter,
+    cursor_id: s.cursor_id,
+    last_event_id: s.last_event_id,
+    lag: newestId - s.last_event_id,
+    acked_at: s.acked_at,
+  }));
+
+  // Providers
+  const providers = db.prepare(`
+    SELECT subscription_id, plugin, event_type_filter, schema_version
+    FROM subscriptions
+    WHERE role = 'provider' AND deregistered_at IS NULL
+  `).all();
+
+  const result = {
+    db_path: dbPath,
+    total_events: totalEvents,
+    oldest_event_id: oldest.min_id || null,
+    newest_event_id: newest.max_id || null,
+    events_by_type: eventsByType,
+    subscribers: subscriberList,
+    providers,
+  };
+
+  db.close();
+  process.stdout.write(JSON.stringify(result) + '\n');
+}