wicked-bus 1.0.0

package/commands/cmd-subscribe.js

@@ -0,0 +1,102 @@
+/**
+ * wicked-bus subscribe command -- streaming NDJSON poll.
+ */
+
+import { loadConfig } from '../lib/config.js';
+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';
+
+export async function cmdSubscribe(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 plugin = args.plugin;
+  const filter = args.filter;
+  const pollIntervalMs = Number(args['poll-interval-ms']) || 1000;
+  const batchSize = Number(args['batch-size']) || 100;
+  const noAck = args['no-ack'] === true;
+
+  let cursorId = args['cursor-id'] || null;
+
+  // If no cursor-id, try implicit cursor lookup or register
+  if (!cursorId) {
+    // Look for an existing active subscription matching plugin + filter
+    const existing = db.prepare(`
+      SELECT s.subscription_id, c.cursor_id
+      FROM subscriptions s
+      JOIN cursors c ON c.subscription_id = s.subscription_id
+      WHERE s.plugin = ? AND s.event_type_filter = ?
+        AND s.role = 'subscriber'
+        AND s.deregistered_at IS NULL
+        AND c.deregistered_at IS NULL
+    `).all(plugin, filter);
+
+    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.'
+      );
+    } else {
+      // Auto-register
+      const cursorInit = args['cursor-init'] || 'latest';
+      const reg = register(db, { plugin, role: 'subscriber', filter, cursor_init: cursorInit });
+      cursorId = reg.cursor_id;
+    }
+  }
+
+  // Start background sweep
+  const sweepHandle = startSweep(db, config);
+
+  // Graceful shutdown
+  let running = true;
+  const shutdown = () => {
+    running = false;
+    if (sweepHandle) clearInterval(sweepHandle);
+    db.close();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  // Poll loop
+  while (running) {
+    try {
+      const events = poll(db, cursorId, { batchSize });
+      for (const event of events) {
+        // Output NDJSON
+        process.stdout.write(JSON.stringify(event) + '\n');
+
+        // Auto-ack unless --no-ack
+        if (!noAck) {
+          ack(db, cursorId, event.event_id);
+        }
+      }
+    } catch (err) {
+      // Output error but continue polling if possible
+      process.stderr.write(JSON.stringify({
+        error: err.error || 'UNKNOWN',
+        code: err.code || 'POLL_ERROR',
+        message: err.message,
+      }) + '\n');
+
+      // Fatal errors: WB-003, WB-006
+      if (err.error === 'WB-003' || err.error === 'WB-006') {
+        if (sweepHandle) clearInterval(sweepHandle);
+        db.close();
+        throw err;
+      }
+    }
+
+    // Wait before next poll
+    await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+  }
+}

package/install.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// wicked-bus installer — detects CLIs and installs skills
+
+import { existsSync, mkdirSync, cpSync, readdirSync } from "node:fs";
+import { join, resolve, basename } from "node:path";
+import { homedir } from "node:os";
+import { argv } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const skillsSource = join(__dirname, "skills");
+const home = homedir();
+
+const CLI_TARGETS = [
+  { name: "claude",      dir: join(home, ".claude", "skills"),      platform: "claude" },
+  { name: "gemini",      dir: join(home, ".gemini", "skills"),      platform: "gemini" },
+  { name: "copilot",     dir: join(home, ".github", "skills"),      platform: "copilot" },
+  { name: "codex",       dir: join(home, ".codex", "skills"),       platform: "codex" },
+  { name: "cursor",      dir: join(home, ".cursor", "skills"),      platform: "cursor" },
+  { name: "kiro",        dir: join(home, ".kiro", "skills"),        platform: "kiro" },
+  { name: "antigravity", dir: join(home, ".antigravity", "skills"), platform: "antigravity" },
+];
+
+console.log("wicked-bus installer\n");
+
+const args = argv.slice(2);
+const argValue = (a) => a.split("=")[1];
+const cliArg = args.find((a) => a.startsWith("--cli="));
+const pathArg = args.find((a) => a.startsWith("--path="));
+
+let targets;
+
+if (pathArg) {
+  const rawPath = argValue(pathArg);
+  if (!rawPath) {
+    console.error("Error: --path requires a value (e.g. --path=~/.claude)");
+    process.exit(1);
+  }
+  const customPath = resolve(rawPath.replace(/^~/, home));
+  const dirName = basename(customPath).replace(/^\./, "");
+  targets = [{
+    name: dirName,
+    dir: join(customPath, "skills"),
+    platform: dirName,
+  }];
+  console.log(`Custom path: ${customPath}\n`);
+} else {
+  const detected = CLI_TARGETS.filter((t) => existsSync(resolve(t.dir, "..")));
+
+  if (detected.length === 0) {
+    console.log("No supported AI CLIs detected. Supported: claude, gemini, copilot, codex, cursor, kiro, antigravity");
+    console.log("Install skills manually by copying the skills/ directory.");
+    process.exit(1);
+  }
+
+  console.log(`Detected CLIs: ${detected.map((d) => d.name).join(", ")}\n`);
+
+  const cliFilter = cliArg ? argValue(cliArg).split(",") : null;
+  targets = cliFilter ? detected.filter((d) => cliFilter.includes(d.name)) : detected;
+}
+
+// Copy skills to each target CLI
+const skillDirs = readdirSync(skillsSource).filter((d) => !d.startsWith("."));
+
+for (const target of targets) {
+  console.log(`Installing to ${target.name} (${target.dir})...`);
+  mkdirSync(target.dir, { recursive: true });
+
+  for (const skill of skillDirs) {
+    const src = join(skillsSource, skill);
+    const dest = join(target.dir, skill);
+    cpSync(src, dest, { recursive: true });
+  }
+
+  console.log(`  ${skillDirs.length} skills installed`);
+}
+
+console.log(`\nwicked-bus skills installed! Available skills:`);
+console.log(`  wicked-bus/init      — Initialize or connect to the bus`);
+console.log(`  wicked-bus/emit      — Publish events`);
+console.log(`  wicked-bus/subscribe — Consume events`);
+console.log(`  wicked-bus/naming    — Event naming conventions`);
+console.log(`  wicked-bus/query     — Query and debug the bus`);

package/lib/config.js

@@ -0,0 +1,87 @@
+/**
+ * Configuration loading and validation.
+ * @module lib/config
+ */
+
+import { join } from 'node:path';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolveDataDir } from './paths.js';
+
+export const DEFAULTS = {
+  ttl_hours: 72,
+  dedup_ttl_hours: 24,
+  sweep_interval_minutes: 15,
+  archive_mode: false,
+  log_level: 'warn',
+  db_path: null,
+  max_payload_bytes: 1048576,
+};
+
+const VALID_LOG_LEVELS = ['debug', 'info', 'warn', 'error'];
+
+/**
+ * Load config from <dataDir>/config.json, merged with defaults.
+ * Malformed JSON is silently ignored (defaults used).
+ * @param {object} [overrides] - CLI flag overrides (e.g. { db_path, log_level })
+ * @returns {object}
+ */
+export function loadConfig(overrides = {}) {
+  let userConfig = {};
+  try {
+    const dataDir = resolveDataDir();
+    const configPath = join(dataDir, 'config.json');
+    const raw = readFileSync(configPath, 'utf8');
+    userConfig = JSON.parse(raw);
+  } catch (_) {
+    // File missing or malformed JSON -- use defaults
+  }
+
+  const config = { ...DEFAULTS, ...userConfig, ...overrides };
+
+  // Remove null/undefined overrides so defaults aren't clobbered
+  for (const key of Object.keys(overrides)) {
+    if (overrides[key] == null) delete config[key];
+    if (overrides[key] == null && DEFAULTS[key] != null) {
+      config[key] = userConfig[key] != null ? userConfig[key] : DEFAULTS[key];
+    }
+  }
+
+  // Validate
+  if (config.dedup_ttl_hours > config.ttl_hours) {
+    throw new Error(
+      `Invalid config: dedup_ttl_hours (${config.dedup_ttl_hours}) must be <= ttl_hours (${config.ttl_hours})`
+    );
+  }
+  if (config.sweep_interval_minutes < 0) {
+    throw new Error('Invalid config: sweep_interval_minutes must be >= 0');
+  }
+  if (config.max_payload_bytes < 1) {
+    throw new Error('Invalid config: max_payload_bytes must be >= 1');
+  }
+  if (!VALID_LOG_LEVELS.includes(config.log_level)) {
+    throw new Error(
+      `Invalid config: log_level must be one of ${VALID_LOG_LEVELS.join(', ')}`
+    );
+  }
+
+  return config;
+}
+
+/**
+ * Write the default config to <dataDir>/config.json.
+ * Does not overwrite if file already exists unless force=true.
+ * @param {string} dataDir
+ * @param {boolean} [force=false]
+ */
+export function writeDefaultConfig(dataDir, force = false) {
+  const configPath = join(dataDir, 'config.json');
+  if (!force) {
+    try {
+      readFileSync(configPath);
+      return; // Already exists
+    } catch (_) {
+      // File doesn't exist, write it
+    }
+  }
+  writeFileSync(configPath, JSON.stringify(DEFAULTS, null, 2) + '\n', 'utf8');
+}

package/lib/db.js

@@ -0,0 +1,72 @@
+/**
+ * Database connection manager.
+ * @module lib/db
+ */
+
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { resolveDbPath, ensureDataDir } from './paths.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const SCHEMA_SQL_PATH = join(__dirname, 'schema.sql');
+const MAX_SUPPORTED_SCHEMA_VERSION = 1;
+
+/**
+ * Open (or create) the SQLite database, apply PRAGMAs and schema.
+ * better-sqlite3 is synchronous, so this function is synchronous.
+ * @param {object} [config] - Merged config object
+ * @returns {import('better-sqlite3').Database}
+ */
+export function openDb(config = {}) {
+  const Database = require('better-sqlite3');
+
+  ensureDataDir();
+  const dbPath = resolveDbPath(config);
+
+  const db = new Database(dbPath);
+
+  // Apply PRAGMAs in order
+  db.pragma('journal_mode = WAL');
+  db.pragma('synchronous = NORMAL');
+  db.pragma('foreign_keys = ON');
+  db.pragma('busy_timeout = 5000');
+
+  // Execute schema DDL (idempotent)
+  const schemaSql = readFileSync(SCHEMA_SQL_PATH, 'utf8');
+  // Split by semicolons and execute each statement
+  // Filter out PRAGMA lines since we already applied them
+  const statements = schemaSql
+    .split(';')
+    .map(s => s.trim())
+    .filter(s => s.length > 0 && !s.toUpperCase().startsWith('PRAGMA'));
+
+  for (const stmt of statements) {
+    db.exec(stmt + ';');
+  }
+
+  // Schema version check
+  checkSchemaVersion(db);
+
+  return db;
+}
+
+/**
+ * Check that the DB schema version is supported.
+ * @param {import('better-sqlite3').Database} db
+ */
+function checkSchemaVersion(db) {
+  const row = db.prepare(
+    'SELECT MAX(version) as max_version FROM schema_migrations'
+  ).get();
+
+  if (row && row.max_version > MAX_SUPPORTED_SCHEMA_VERSION) {
+    process.stderr.write(JSON.stringify({
+      error: 'SCHEMA_VERSION_MISMATCH',
+      message: `Database schema version ${row.max_version} is newer than supported (${MAX_SUPPORTED_SCHEMA_VERSION}). Run: npm install -g wicked-bus`,
+    }) + '\n');
+    process.exit(1);
+  }
+}

package/lib/emit.js

@@ -0,0 +1,111 @@
+/**
+ * Event emission with idempotency and TTL computation.
+ * @module lib/emit
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { validateEvent } from './validate.js';
+import { WBError } from './errors.js';
+
+/**
+ * Emit an event to the bus.
+ * @param {import('better-sqlite3').Database} db
+ * @param {object} config - Merged config
+ * @param {object} event - Event data
+ * @param {string} event.event_type
+ * @param {string} event.domain
+ * @param {string} [event.subdomain]
+ * @param {object|string} event.payload
+ * @param {string} [event.schema_version]
+ * @param {string} [event.idempotency_key]
+ * @param {number} [event.ttl_hours] - Per-event TTL override
+ * @param {string|object} [event.metadata]
+ * @returns {{ event_id: number, idempotency_key: string }}
+ */
+export function emit(db, config, event) {
+  // Validate
+  validateEvent(event, config);
+
+  const idempotencyKey = event.idempotency_key || uuidv4();
+  const emittedAt = Date.now();
+  const ttlHours = event.ttl_hours != null ? event.ttl_hours : config.ttl_hours;
+  const expiresAt = emittedAt + (ttlHours * 3_600_000);
+  const dedupExpiresAt = emittedAt + (config.dedup_ttl_hours * 3_600_000);
+
+  const payloadStr = typeof event.payload === 'string'
+    ? event.payload
+    : JSON.stringify(event.payload);
+
+  const metadataStr = event.metadata != null
+    ? (typeof event.metadata === 'string' ? event.metadata : JSON.stringify(event.metadata))
+    : null;
+
+  const schemaVersion = event.schema_version || '1.0.0';
+
+  try {
+    const subdomain = event.subdomain || '';
+
+    const stmt = db.prepare(`
+      INSERT INTO events (
+        event_type, domain, subdomain, payload, schema_version,
+        idempotency_key, emitted_at, expires_at, dedup_expires_at, metadata
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const result = stmt.run(
+      event.event_type,
+      event.domain,
+      subdomain,
+      payloadStr,
+      schemaVersion,
+      idempotencyKey,
+      emittedAt,
+      expiresAt,
+      dedupExpiresAt,
+      metadataStr
+    );
+
+    return {
+      event_id: Number(result.lastInsertRowid),
+      idempotency_key: idempotencyKey,
+    };
+  } catch (err) {
+    // Duplicate idempotency_key
+    if (err.code === 'SQLITE_CONSTRAINT_UNIQUE') {
+      const existing = db.prepare(
+        'SELECT event_id FROM events WHERE idempotency_key = ?'
+      ).get(idempotencyKey);
+
+      throw new WBError('WB-002', 'DUPLICATE_EVENT', {
+        message: `Duplicate idempotency_key: ${idempotencyKey}`,
+        original_event_id: existing ? existing.event_id : null,
+        idempotency_key: idempotencyKey,
+      });
+    }
+
+    // Disk full
+    if (
+      (err.code && err.code.includes('SQLITE_FULL')) ||
+      (err.code === 'ENOSPC') ||
+      (err.message && err.message.includes('SQLITE_FULL'))
+    ) {
+      const dbPath = db.name;
+      try { db.close(); } catch (_) { /* ignore close errors */ }
+      // Re-open to verify integrity
+      try {
+        const Database = db.constructor;
+        const verifyDb = new Database(dbPath);
+        verifyDb.pragma('integrity_check');
+        verifyDb.close();
+      } catch (_) { /* ignore verification errors */ }
+
+      throw new WBError('WB-004', 'DISK_FULL', {
+        message: 'Database disk is full',
+        sqlite_error: err.code || 'SQLITE_FULL',
+        db_path: dbPath,
+      });
+    }
+
+    throw err;
+  }
+}

package/lib/errors.js

@@ -0,0 +1,45 @@
+/**
+ * wicked-bus error classes and error codes.
+ * @module lib/errors
+ */
+
+export const ERROR_CODES = {
+  'WB-001': 'INVALID_EVENT_SCHEMA',
+  'WB-002': 'DUPLICATE_EVENT',
+  'WB-003': 'CURSOR_BEHIND_TTL_WINDOW',
+  'WB-004': 'DISK_FULL',
+  'WB-005': 'SCHEMA_VERSION_UNSUPPORTED',
+  'WB-006': 'CURSOR_NOT_FOUND',
+};
+
+export const EXIT_CODES = {
+  'WB-001': 1,
+  'WB-002': 2,
+  'WB-003': 3,
+  'WB-004': 4,
+  'WB-005': 5,
+  'WB-006': 6,
+};
+
+export class WBError extends Error {
+  /**
+   * @param {string} error - Error code, e.g. 'WB-001'
+   * @param {string} code - Machine-readable name, e.g. 'INVALID_EVENT_SCHEMA'
+   * @param {object} context - Additional context
+   */
+  constructor(error, code, context = {}) {
+    super(context.message || code);
+    this.error = error;
+    this.code = code;
+    this.context = context;
+  }
+
+  toJSON() {
+    return {
+      error: this.error,
+      code: this.code,
+      message: this.message,
+      context: this.context,
+    };
+  }
+}

package/lib/index.cjs

@@ -0,0 +1,20 @@
+/**
+ * CJS shim for wicked-bus.
+ * Usage: const bus = await import('wicked-bus');
+ * Or: import('wicked-bus').then(bus => { ... });
+ */
+
+let _mod;
+module.exports = new Proxy({}, {
+  get(_, prop) {
+    if (!_mod) {
+      throw new Error(
+        'wicked-bus CJS shim: module not yet loaded. ' +
+        'Use: const bus = await import("wicked-bus")'
+      );
+    }
+    return _mod[prop];
+  }
+});
+
+import('./index.js').then(m => { _mod = m; });

package/lib/index.js

@@ -0,0 +1,13 @@
+/**
+ * wicked-bus public API.
+ * @module wicked-bus
+ */
+
+export { emit } from './emit.js';
+export { poll, ack, matchesFilter } from './poll.js';
+export { register, deregister } from './register.js';
+export { openDb } from './db.js';
+export { loadConfig } from './config.js';
+export { resolveDataDir, ensureDataDir, resolveDbPath } from './paths.js';
+export { startSweep, runSweep } from './sweep.js';
+export { WBError, ERROR_CODES, EXIT_CODES } from './errors.js';

package/lib/paths.js

@@ -0,0 +1,69 @@
+/**
+ * Cross-platform data directory resolution.
+ * @module lib/paths
+ */
+
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { mkdirSync } from 'node:fs';
+
+const SUBDIR = join('.something-wicked', 'wicked-bus');
+
+/**
+ * Resolve the wicked-bus data directory path (pure resolution, no side effects).
+ * Priority: WICKED_BUS_DATA_DIR env > platform-specific home.
+ * @returns {string}
+ */
+export function resolveDataDir() {
+  const envDir = process.env.WICKED_BUS_DATA_DIR;
+  if (envDir) return envDir;
+
+  let base;
+  if (process.platform === 'win32') {
+    base =
+      process.env.APPDATA ||
+      process.env.USERPROFILE ||
+      process.env.HOME ||
+      null;
+    if (!base) {
+      // Last resort on Windows
+      try { base = homedir(); } catch (_) { /* ignore */ }
+    }
+    if (!base) {
+      base = process.cwd();
+    }
+  } else {
+    base = process.env.HOME || null;
+    if (!base) {
+      try { base = homedir(); } catch (_) { /* ignore */ }
+    }
+    if (!base) {
+      throw new Error(
+        'Cannot resolve data directory: $HOME is not set. ' +
+        'Set WICKED_BUS_DATA_DIR or export HOME.'
+      );
+    }
+  }
+
+  return join(base, SUBDIR);
+}
+
+/**
+ * Ensure the data directory exists (creates recursively).
+ * @returns {string} The data directory path.
+ */
+export function ensureDataDir() {
+  const dir = resolveDataDir();
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Resolve the full database file path.
+ * @param {object} [config] - Config object; uses config.db_path if set.
+ * @returns {string}
+ */
+export function resolveDbPath(config) {
+  if (config && config.db_path) return config.db_path;
+  return join(resolveDataDir(), 'bus.db');
+}