wicked-bus 1.0.0

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "wicked-bus",
+  "version": "1.0.0",
+  "description": "Lightweight, local-first SQLite event bus for AI agents and developer tools",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./lib/index.js",
+      "require": "./lib/index.cjs"
+    },
+    "./cli": "./commands/cli.js"
+  },
+  "main": "./lib/index.cjs",
+  "module": "./lib/index.js",
+  "bin": {
+    "wicked-bus": "./commands/cli.js",
+    "wicked-bus-install": "./install.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "uuid": "^9.0.0"
+  },
+  "peerDependencies": {
+    "better-sqlite3": ">=9.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.4",
+    "better-sqlite3": "^11.0.0",
+    "vitest": "^4.1.4"
+  },
+  "files": [
+    "lib/",
+    "commands/",
+    "scripts/",
+    "skills/",
+    "install.mjs"
+  ],
+  "keywords": [
+    "event-bus",
+    "sqlite",
+    "local-first",
+    "ai-agents",
+    "developer-tools",
+    "cursor-poll",
+    "at-least-once"
+  ],
+  "license": "MIT"
+}

package/scripts/postinstall.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script -- auto-create data directory on npm install.
+ * Must not fail -- all errors are swallowed.
+ */
+
+import { ensureDataDir } from '../lib/paths.js';
+
+try {
+  ensureDataDir();
+} catch (_) {
+  // Swallow: postinstall must not fail npm install
+}

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

@@ -0,0 +1,147 @@
+---
+description: Emit events to the wicked-bus. Use when publishing events from a plugin, logging activity to the bus, or integrating a new system with the event bridge. Covers both programmatic (Node.js) and CLI usage.
+---
+
+# wicked-bus:emit
+
+Guide for publishing events to the wicked-bus.
+
+## When to use
+
+- User wants to emit an event from their code
+- User asks "how do I publish to the bus"
+- Integrating a plugin with wicked-bus for the first time
+- User wants to fire-and-forget an event
+
+## Prerequisites
+
+Check that wicked-bus is initialized. If not, trigger `wicked-bus-init`.
+
+```bash
+npx wicked-bus status 2>/dev/null
+```
+
+## Programmatic Usage (Node.js)
+
+### Basic emit
+
+```javascript
+import { emit } 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);
+
+const result = emit(db, config, {
+  event_type: 'wicked.task.completed',
+  domain: 'my-plugin',
+  subdomain: 'workflow.task',
+  payload: { taskId: 'abc-123', status: 'done' },
+});
+
+console.log(result);
+// { event_id: 42, idempotency_key: '550e8400-...' }
+
+db.close();
+```
+
+### Fire-and-forget pattern (recommended for integrations)
+
+Plugins should never block on the bus. Use this pattern:
+
+```javascript
+let _busEmit = null;
+let _busChecked = false;
+
+async function emitToBus(event) {
+  if (!_busChecked) {
+    _busChecked = true;
+    try {
+      const mod = await import('wicked-bus');
+      const { loadConfig } = await import('wicked-bus/lib/config.js');
+      const { openDb } = await import('wicked-bus/lib/db.js');
+      const config = loadConfig();
+      const db = openDb(config);
+      _busEmit = (evt) => mod.emit(db, config, evt);
+    } catch (_) {
+      _busEmit = null; // Bus not installed — degrade gracefully
+    }
+  }
+  if (!_busEmit) return null;
+  try {
+    return _busEmit(event);
+  } catch (_) {
+    return null; // Never throw from fire-and-forget
+  }
+}
+```
+
+### With custom TTL
+
+```javascript
+emit(db, config, {
+  event_type: 'wicked.cache.invalidated',
+  domain: 'my-plugin',
+  payload: { keys: ['user:123'] },
+  ttl_hours: 4, // Override default 72h TTL
+});
+```
+
+### With explicit idempotency key
+
+```javascript
+emit(db, config, {
+  event_type: 'wicked.job.completed',
+  domain: 'my-plugin',
+  subdomain: 'jobs.batch',
+  payload: { jobId: 'job-42' },
+  idempotency_key: 'job-42-completed', // Prevents duplicate events
+});
+```
+
+## CLI Usage
+
+### Basic emit
+
+```bash
+npx wicked-bus emit \
+  --type wicked.task.completed \
+  --domain my-plugin \
+  --subdomain workflow.task \
+  --payload '{"taskId": "abc-123", "status": "done"}'
+```
+
+### Payload from file
+
+```bash
+npx wicked-bus emit \
+  --type wicked.report.generated \
+  --domain my-plugin \
+  --payload @./report-data.json
+```
+
+### With metadata
+
+```bash
+npx wicked-bus emit \
+  --type wicked.deploy.completed \
+  --domain my-deploy \
+  --subdomain deploy.production \
+  --payload '{"version": "2.0.0"}' \
+  --metadata '{"host": "prod-01"}'
+```
+
+## Error Handling
+
+| Error | Code | Meaning |
+|-------|------|---------|
+| WB-001 | INVALID_EVENT_SCHEMA | Event failed validation (bad type, missing fields, payload too large) |
+| WB-002 | DUPLICATE_EVENT | Idempotency key already exists |
+| WB-004 | DISK_FULL | SQLite database disk is full |
+| WB-005 | SCHEMA_VERSION_UNSUPPORTED | schema_version > 1.x |
+
+## Event Naming
+
+For help choosing event_type, domain, and subdomain values, use the
+`wicked-bus-naming` skill.

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

@@ -0,0 +1,94 @@
+---
+description: Initialize wicked-bus or connect to an existing instance. Use when setting up the bus for the first time, checking if it's running, or configuring a project to use it. Auto-triggered when any wicked-bus skill detects no config.
+---
+
+# wicked-bus:init
+
+Set up wicked-bus for the current project. Detects an existing running instance
+before creating a new one.
+
+## When to use
+
+- First time using wicked-bus in a project
+- Another wicked-bus skill detected no config and redirected here
+- User asks to "set up the bus", "init wicked-bus", or "connect to the bus"
+
+## Process
+
+### Step 1: Check for existing instance
+
+Before creating anything, check if wicked-bus is already initialized:
+
+```bash
+# Check if the data directory exists
+ls ~/.something-wicked/wicked-bus/bus.db 2>/dev/null
+```
+
+If the data dir and DB exist, wicked-bus is already running. Skip to Step 4.
+
+Also check if another agent or process already initialized it this session:
+
+```bash
+# Check if the CLI is available
+npx wicked-bus status 2>/dev/null
+```
+
+If status returns valid JSON, the bus is live. Report to the user and skip init.
+
+### Step 2: Check if wicked-bus is installed
+
+```bash
+# Check if the package is available
+node -e "require.resolve('wicked-bus')" 2>/dev/null || \
+  node -e "import('wicked-bus').then(() => console.log('found'))" 2>/dev/null
+```
+
+If not installed:
+```
+wicked-bus is not installed. Install it:
+  npm install wicked-bus
+```
+
+### Step 3: Initialize
+
+Run the init command:
+
+```bash
+npx wicked-bus init
+```
+
+This creates:
+- `~/.something-wicked/wicked-bus/` data directory
+- `bus.db` SQLite database with WAL mode
+- `config.json` with defaults
+
+Verify success by checking the JSON output for `"initialized": true`.
+
+### Step 4: Register the current project (optional)
+
+If the user wants this project to emit events, register as a provider:
+
+Ask: "What domain name should this project use?" (default: directory name)
+
+```bash
+npx wicked-bus register \
+  --role provider \
+  --plugin {domain} \
+  --filter 'wicked.*'
+```
+
+### Step 5: Confirm
+
+Report:
+```
+wicked-bus is ready.
+  Data dir: ~/.something-wicked/wicked-bus/
+  DB: bus.db (WAL mode)
+  Status: {event count} events, {subscriber count} subscribers
+```
+
+If the bus was already running, say so:
+```
+wicked-bus is already initialized and running.
+  {status output}
+```

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

@@ -0,0 +1,151 @@
+---
+description: Guide for naming wicked-bus events — helps choose event_type, domain, and subdomain when emitting events. Use when creating new events, integrating a plugin with the bus, or reviewing event naming for consistency.
+---
+
+# wicked-bus Event Naming
+
+Interactive guide for naming events in the wicked-bus ecosystem. Helps users
+choose correct event_type, domain, and subdomain values.
+
+## When to use
+
+- User is adding wicked-bus integration to a plugin
+- User asks "how do I name this event" or "what event_type should I use"
+- User is emitting events and needs to pick domain/subdomain
+- Reviewing event names for consistency with the catalog
+- User asks about the event naming convention
+
+## The Three Fields
+
+Every event has three identity fields:
+
+| Field | Purpose | Rule |
+|-------|---------|------|
+| `event_type` | **What happened** — semantic, shared across producers | `wicked.<noun>.<past-tense-verb>` |
+| `domain` | **Who did it** — the publishing plugin's package name | Your npm package name (e.g., `wicked-testing`) |
+| `subdomain` | **Where in the system** — functional area within the plugin | Dot-separated hierarchy (e.g., `crew.phase`, `test.run`) |
+
+## event_type Rules
+
+Pattern: `wicked.<noun>.<past-tense-verb>`
+
+1. Always starts with `wicked.`
+2. Second segment = **noun** (the thing that changed): `run`, `phase`, `memory`, `project`, `gate`
+3. Third segment = **past-tense verb** (what happened): `completed`, `started`, `stored`, `failed`, `created`
+4. Lowercase, `[a-z0-9_]` only, dot-separated
+5. Max 128 characters
+6. **Semantic, not source-specific** — two plugins emitting the same kind of event share the type
+
+### Common mistakes to catch
+
+| Wrong | Problem | Correct |
+|-------|---------|---------|
+| `wicked-testing.run.completed` | Domain leaked into type | `wicked.run.completed` + domain=`wicked-testing` |
+| `wicked.test_run_completed` | Underscores instead of dots | `wicked.run.completed` |
+| `wicked.run.complete` | Not past tense | `wicked.run.completed` |
+| `wicked.crew.phase.started` | Subdomain leaked into type (4 segments) | `wicked.phase.started` + subdomain=`crew.phase` |
+| `run.completed` | Missing `wicked.` prefix | `wicked.run.completed` |
+
+## domain Rules
+
+1. A unique identifier for the publishing system — package name, service name, or tool name
+2. Max 64 characters
+3. One domain per system — don't subdivide at this level
+4. This is what subscribers use in `@domain` filters
+
+## subdomain Rules
+
+1. Dot-separated hierarchy: `<area>.<entity>` (e.g., `deploy.staging`)
+2. First segment = top-level area within your plugin
+3. Second segment = specific entity or concern
+4. Defaults to `''` if not provided
+5. Max 64 characters
+6. Can be arbitrarily deep if needed
+
+## Process
+
+When a user needs to name an event:
+
+### Step 1: Identify what happened
+
+Ask: "What changed and what happened to it?"
+
+Map to: `wicked.<noun>.<past-tense-verb>`
+
+- Thing created → `wicked.<thing>.created`
+- Thing completed → `wicked.<thing>.completed`
+- Thing failed → `wicked.<thing>.failed`
+- Thing updated → `wicked.<thing>.updated`
+- Thing deleted/removed → `wicked.<thing>.deleted`
+- Thing started → `wicked.<thing>.started`
+
+### Step 2: Identify the publisher
+
+Ask: "What plugin is emitting this?"
+
+Map to `domain` = their package name.
+
+### Step 3: Identify the functional area
+
+Ask: "What part of the system does this come from?"
+
+Map to `subdomain` using the pattern `<area>.<entity>`. Examples:
+- A deployment subsystem → `deploy.staging`
+- An auth module → `auth.session`
+- A build pipeline → `build.artifact`
+
+### Step 4: Validate
+
+Check that your event follows the rules:
+
+1. event_type starts with `wicked.` and has exactly 3 dot-separated segments
+2. Third segment is past tense (`created`, not `create`)
+3. Domain doesn't appear in the event_type
+4. Subdomain doesn't appear in the event_type
+5. If another plugin emits the same semantic event, you should share the event_type
+
+**Example validation:**
+
+| Proposed | Valid? | Issue |
+|----------|--------|-------|
+| `wicked.deployment.started` + domain=`my-deploy` | Yes | |
+| `my-deploy.deployment.started` | No | Domain in type |
+| `wicked.deploy.staging.started` | No | 4 segments — subdomain leaked in |
+| `wicked.deployment.start` | No | Not past tense |
+
+### Step 5: Generate the emit call
+
+```javascript
+import { emit } from 'wicked-bus';
+
+emit(db, config, {
+  event_type: '{event_type}',
+  domain: '{domain}',
+  subdomain: '{subdomain}',
+  payload: { /* event-specific data */ },
+});
+```
+
+### Step 6: Show the subscriber filter
+
+```bash
+# All events of this type from any source
+wicked-bus subscribe --filter '{event_type}'
+
+# Only from this domain
+wicked-bus subscribe --filter '{event_type}@{domain}'
+
+# All events from this domain
+wicked-bus subscribe --filter '*@{domain}'
+```
+
+## Design Decisions
+
+**Why event_type is semantic (not source-specific):**
+Same `wicked.project.created` from `wicked-garden` and `wicked-testing`.
+A subscriber wanting "all project creations" uses one filter. Baking domain
+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.

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

@@ -0,0 +1,177 @@
+---
+description: Query and debug the wicked-bus. Use when checking bus health, inspecting events, debugging delivery issues, tracing event flow, or investigating why a subscriber isn't receiving events. Covers status, replay, and direct SQLite queries.
+---
+
+# wicked-bus:query
+
+Tools for inspecting, debugging, and querying the wicked-bus.
+
+## When to use
+
+- User asks "what's in the bus" or "show me recent events"
+- Debugging why a subscriber isn't receiving events
+- Checking bus health or event counts
+- Investigating delivery lag or missed events
+- User asks about cursor positions or subscriber state
+
+## Quick Health Check
+
+```bash
+npx wicked-bus status
+```
+
+Returns JSON with:
+- Total event count
+- Active subscriber count
+- Provider list
+- Cursor lag per subscriber
+
+## Inspecting Events
+
+### Recent events via SQLite
+
+```bash
+# Last 10 events
+sqlite3 ~/.something-wicked/wicked-bus/bus.db \
+  "SELECT event_id, event_type, domain, subdomain, datetime(emitted_at/1000, 'unixepoch') as time FROM events ORDER BY event_id DESC LIMIT 10;"
+```
+
+### Events by type
+
+```bash
+sqlite3 ~/.something-wicked/wicked-bus/bus.db \
+  "SELECT event_id, domain, subdomain, datetime(emitted_at/1000, 'unixepoch') as time FROM events WHERE event_type = 'wicked.phase.completed' ORDER BY event_id DESC LIMIT 10;"
+```
+
+### Events by domain
+
+```bash
+sqlite3 ~/.something-wicked/wicked-bus/bus.db \
+  "SELECT event_id, event_type, subdomain, datetime(emitted_at/1000, 'unixepoch') as time FROM events WHERE domain = 'wicked-garden' ORDER BY event_id DESC LIMIT 10;"
+```
+
+### Event count by type
+
+```bash
+sqlite3 ~/.something-wicked/wicked-bus/bus.db \
+  "SELECT event_type, COUNT(*) as count FROM events GROUP BY event_type ORDER BY count DESC;"
+```
+
+### Full event payload
+
+```bash
+sqlite3 ~/.something-wicked/wicked-bus/bus.db \
+  "SELECT event_id, event_type, domain, payload FROM events WHERE event_id = {id};"
+```
+
+## Debugging Subscribers
+
+### Check cursor positions
+
+```bash
+sqlite3 ~/.something-wicked/wicked-bus/bus.db \
+  "SELECT c.cursor_id, s.plugin, s.event_type_filter, c.last_event_id, datetime(c.acked_at/1000, 'unixepoch') as last_ack FROM cursors c JOIN subscriptions s ON c.subscription_id = s.subscription_id WHERE c.deregistered_at IS NULL;"
+```
+
+### Find subscriber lag
+
+```bash
+# Compare cursor position to latest event
+sqlite3 ~/.something-wicked/wicked-bus/bus.db \
+  "SELECT s.plugin, c.last_event_id, (SELECT MAX(event_id) FROM events) - c.last_event_id as lag FROM cursors c JOIN subscriptions s ON c.subscription_id = s.subscription_id WHERE c.deregistered_at IS NULL;"
+```
+
+### Check if subscriber is registered
+
+```bash
+npx wicked-bus list --role subscriber --json
+```
+
+### Check active vs deregistered
+
+```bash
+npx wicked-bus list --include-deregistered --json
+```
+
+## Common Issues
+
+### "Subscriber isn't receiving events"
+
+1. **Check registration**: `npx wicked-bus list --role subscriber`
+2. **Check filter**: does the filter match the event_type?
+   - `wicked.run.*` matches `wicked.run.completed` but NOT `wicked.run.step.completed`
+   - `@domain` suffix must match the `domain` column exactly
+3. **Check cursor position**: is the cursor ahead of the events?
+4. **Check expiry**: events past `expires_at` (default 72h) are invisible
+5. **Check deregistration**: was the subscription soft-deleted?
+
+### "WB-003: Cursor behind oldest event"
+
+The subscriber's cursor is behind the oldest event in the table. Events
+between the cursor and the oldest event were swept (deleted after
+`dedup_expires_at`). These events are permanently lost for this subscriber.
+
+**Fix**: Reset the cursor to the current position:
+```bash
+npx wicked-bus replay --cursor-id {cursor_id} --event-id {latest_event_id}
+```
+
+### "Events seem to disappear"
+
+Events are deleted by the sweep process after `dedup_expires_at` (default 24h).
+Check your sweep configuration:
+
+```bash
+sqlite3 ~/.something-wicked/wicked-bus/bus.db \
+  "SELECT * FROM schema_migrations;"
+```
+
+Check config:
+```bash
+cat ~/.something-wicked/wicked-bus/config.json
+```
+
+### "Duplicate events"
+
+Events have a UNIQUE `idempotency_key`. If you're seeing duplicates, the
+emitter is generating different keys for logically identical events. Fix
+by using a deterministic key:
+
+```javascript
+emit(db, config, {
+  event_type: 'wicked.job.completed',
+  domain: 'my-plugin',
+  payload: { jobId: 'job-42' },
+  idempotency_key: `job-42-completed`, // Deterministic
+});
+```
+
+## Cleanup and Maintenance
+
+### Manual sweep
+
+```bash
+# Dry run — see what would be deleted
+npx wicked-bus cleanup --dry-run
+
+# Delete expired events
+npx wicked-bus cleanup
+
+# Delete and archive to events_archive table
+npx wicked-bus cleanup --archive
+```
+
+### Check database size
+
+```bash
+ls -lh ~/.something-wicked/wicked-bus/bus.db
+```
+
+### Check WAL size
+
+```bash
+ls -lh ~/.something-wicked/wicked-bus/bus.db-wal
+```
+
+Large WAL files indicate checkpointing isn't happening. This is normal
+for busy periods — SQLite auto-checkpoints at 1000 pages.