@celilo/cli 0.2.1 → 0.3.0

package/src/cli/index.ts

@@ -10,6 +10,21 @@ import { COMMANDS, type CommandDef } from './command-registry';
 import { handleCapabilityInfo } from './commands/capability-info';
 import { handleCapabilityList } from './commands/capability-list';
 import { handleCompletion } from './commands/completion';
+import {
+  handleEventsAck,
+  handleEventsDrain,
+  handleEventsEmit,
+  handleEventsFail,
+  handleEventsInstallDaemon,
+  handleEventsListPending,
+  handleEventsListSubscribers,
+  handleEventsRepair,
+  handleEventsRun,
+  handleEventsShowDaemon,
+  handleEventsStatus,
+  handleEventsTail,
+  handleEventsUninstallDaemon,
+} from './commands/events';
 import { handleHookRun } from './commands/hook-run';
 import {
   handleIpamIpListReservations,
@@ -212,6 +227,45 @@ Related Commands:
 /**
  * Display capability command help
  */
+function displayEventsHelp(): CommandResult {
+  const helpText = `
+Celilo - SQLite Event Bus
+
+Usage:
+  celilo events <subcommand> [args...]
+
+Subcommands:
+  status                       Print bus health as JSON
+  tail [--type T] [--limit N]  Recent events as JSON
+  list-subscribers             List persistent bus subscribers
+  list-pending [--subscriber]  List pending deliveries
+  drain [--concurrency N]      Process pending deliveries once and return
+  run [--poll-ms N]            Run the long-running dispatcher (foreground)
+  emit <type> [<payload>]      Emit an event (operator/test path)
+  ack <event_id>               Mark a running delivery succeeded
+  fail <event_id> --error MSG  Mark a running delivery failed
+  repair                       Crash-recovery sweep without starting the dispatcher
+  resume                       Alias for repair (acknowledges halt-on-recovery)
+  install-daemon               Write a systemd/launchd user unit for the dispatcher
+  uninstall-daemon             Remove the installed supervisor unit
+  show-daemon                  Print the currently installed unit file
+
+Description:
+  The event bus is a SQLite-backed pub/sub layer for celilo modules.
+  Modules declare \`subscriptions:\` in their manifests; \`celilo module deploy\`
+  emits lifecycle events that subscribers react to.
+
+  See infra/design/SQLITE_EVENT_BUS.md for the full design.
+
+Examples:
+  celilo events run                                      # foreground dispatcher
+  celilo events status                                   # is anything stuck?
+  celilo events tail --type deploy.completed.lunacycle   # filter by type
+  celilo events emit deploy.completed.lunacycle '{}'     # operator-fired event
+`;
+  return { success: true, message: helpText.trim() };
+}
+
 function displayCapabilityHelp(): CommandResult {
   const helpText = `
 Celilo - Capability Management
@@ -918,6 +972,55 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     };
   }
 
+  if (parsed.command === 'events') {
+    if (parsed.flags.help || parsed.flags.h) {
+      return displayEventsHelp();
+    }
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'Events subcommand required\n\nRun "celilo events --help" for usage',
+      };
+    }
+    const evFlagError = checkFlags('events', parsed.subcommand, parsed.flags, parsed.args);
+    if (evFlagError) return evFlagError;
+
+    switch (parsed.subcommand) {
+      case 'status':
+        return handleEventsStatus();
+      case 'tail':
+        return handleEventsTail(parsed.args, parsed.flags);
+      case 'list-subscribers':
+        return handleEventsListSubscribers();
+      case 'list-pending':
+        return handleEventsListPending(parsed.args, parsed.flags);
+      case 'drain':
+        return handleEventsDrain(parsed.args, parsed.flags);
+      case 'run':
+        return handleEventsRun(parsed.args, parsed.flags);
+      case 'emit':
+        return handleEventsEmit(parsed.args, parsed.flags);
+      case 'ack':
+        return handleEventsAck(parsed.args, parsed.flags);
+      case 'fail':
+        return handleEventsFail(parsed.args, parsed.flags);
+      case 'repair':
+      case 'resume':
+        return handleEventsRepair();
+      case 'install-daemon':
+        return handleEventsInstallDaemon(parsed.args, parsed.flags);
+      case 'uninstall-daemon':
+        return handleEventsUninstallDaemon();
+      case 'show-daemon':
+        return handleEventsShowDaemon();
+      default:
+        return {
+          success: false,
+          error: `Unknown events subcommand: ${parsed.subcommand}\n\nRun "celilo events --help" for usage`,
+        };
+    }
+  }
+
   if (parsed.command === 'module') {
     // Handle module --help
     if (parsed.flags.help || parsed.flags.h) {

package/src/config/paths.ts

@@ -92,6 +92,25 @@ export function getDbPath(): string {
   return join(getDataDir(), 'celilo.db');
 }
 
+/**
+ * Get the SQLite event-bus database file path.
+ *
+ * Priority:
+ * 1. CELILO_EVENT_BUS_PATH environment variable (explicit override)
+ * 2. <data-dir>/events.db (platform-specific)
+ *
+ * Kept separate from the main celilo.db so the bus library remains
+ * standalone — the bus owns its own schema and migrations.
+ *
+ * @returns Absolute path to event-bus database
+ */
+export function getEventBusPath(): string {
+  if (process.env.CELILO_EVENT_BUS_PATH) {
+    return process.env.CELILO_EVENT_BUS_PATH;
+  }
+  return join(getDataDir(), 'events.db');
+}
+
 /**
  * Shorten a path by replacing the celilo data directory with $CELILO_DATA
  * For display purposes in CLI output.

package/src/manifest/schema.ts

@@ -260,6 +260,32 @@ export const AnsibleCollectionSchema = z.object({
   reason: z.string().optional(),
 });
 
+/**
+ * Event-bus subscription declaration in a module manifest.
+ *
+ * Each entry becomes a row in the bus's `subscribers` table when the
+ * module is imported, and is removed when the module is removed.
+ *
+ * Substitutions resolved at subscribe time:
+ *   - `$self` in `pattern` → the module's id
+ *   - `${MODULE_PATH}` in `handler` → the module's installed path
+ */
+export const ModuleSubscriptionSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .regex(
+      /^[a-z][a-z0-9_-]*$/,
+      'Subscription name must be kebab/snake_case (lowercase, alphanumeric, dash/underscore)',
+    ),
+  pattern: z.string().min(1),
+  handler: z.string().min(1),
+  max_attempts: z.number().int().positive().optional(),
+  timeout_ms: z.number().int().positive().optional(),
+});
+
+export type ModuleSubscription = z.infer<typeof ModuleSubscriptionSchema>;
+
 /**
  * Module manifest schema (v2 shape).
  *
@@ -424,6 +450,14 @@ export const ModuleManifestSchema = z
         tests_dir: z.string().min(1),
       })
       .optional(),
+
+    /**
+     * Event-bus subscriptions this module wants registered. See
+     * `infra/design/SQLITE_EVENT_BUS.md`. Truly optional so existing
+     * test fixtures and manifests don't need a churn-pass; readers
+     * use `manifest.subscriptions ?? []`.
+     */
+    subscriptions: z.array(ModuleSubscriptionSchema).optional(),
   })
   .strict();
 

package/src/manifest/validate.test.ts

@@ -1246,3 +1246,78 @@ secrets:
     expect(result.success).toBe(false);
   });
 });
+
+describe('subscriptions field', () => {
+  test('manifests without subscriptions still validate', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: test
+name: Test
+version: 1.0.0
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.subscriptions).toBeUndefined();
+    }
+  });
+
+  test('parses a valid subscriptions block', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: test
+name: Test
+version: 1.0.0
+
+subscriptions:
+  - name: smoke-after-deploy
+    pattern: deploy.completed.$self
+    handler: bun \${MODULE_PATH}/celilo/scripts/smoke.ts
+    timeout_ms: 120000
+  - name: cert-rotated
+    pattern: cert.rotated
+    handler: echo
+    max_attempts: 5
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.subscriptions).toHaveLength(2);
+      expect(result.data.subscriptions?.[0].name).toBe('smoke-after-deploy');
+      expect(result.data.subscriptions?.[0].timeout_ms).toBe(120000);
+      expect(result.data.subscriptions?.[1].max_attempts).toBe(5);
+    }
+  });
+
+  test('rejects subscription names with invalid characters', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: test
+name: Test
+version: 1.0.0
+
+subscriptions:
+  - name: SmokeAfterDeploy
+    pattern: deploy.$self
+    handler: echo
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(false);
+  });
+
+  test('requires pattern and handler to be non-empty', () => {
+    const yaml = `
+${CONTRACT_LINE}
+id: test
+name: Test
+version: 1.0.0
+
+subscriptions:
+  - name: smoke
+    pattern: ""
+    handler: echo
+`;
+    const result = validateManifest(yaml);
+    expect(result.success).toBe(false);
+  });
+});

package/src/module/import.ts

@@ -599,6 +599,21 @@ export async function importModule(options: ModuleImportOptions): Promise<Module
       }
     }
 
+    // Execution: Register event-bus subscriptions declared in the manifest.
+    // Best-effort: a bus problem shouldn't wedge an import — the operator
+    // can re-run the import after fixing the bus, and bus.subscribe is
+    // idempotent.
+    try {
+      const { registerModuleSubscriptions } = await import('../services/module-subscriptions');
+      registerModuleSubscriptions(manifest, targetPath);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      log.warn(`Failed to register event-bus subscriptions: ${msg}`);
+      log.warn(
+        'Module imported, but reactive flows on the event bus will not fire until this is fixed.',
+      );
+    }
+
     // Execution: Store integrity data
     // For .netapp packages: store checksums + signature
     // For directory imports: calculate and store checksums (no signature)

package/src/services/celilo-events.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { defineEvents, openBus } from '@celilo/event-bus';
+import {
+  emitDeployCompleted,
+  emitDeployFailed,
+  emitDeployStarted,
+  emitHealthCheckFailed,
+} from './celilo-events';
+
+describe('celilo lifecycle events', () => {
+  let dir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-events-test-'));
+    dbPath = join(dir, 'events.db');
+    process.env.CELILO_EVENT_BUS_PATH = dbPath;
+  });
+  afterEach(() => {
+    process.env.CELILO_EVENT_BUS_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  function recentEvents() {
+    const bus = openBus({ dbPath, events: defineEvents({}) });
+    try {
+      return bus.recentEvents({ limit: 100 });
+    } finally {
+      bus.close();
+    }
+  }
+
+  it('emits deploy.started.<module> with expected payload', () => {
+    emitDeployStarted({ module: 'lunacycle', startedAt: 1234 });
+    const events = recentEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe('deploy.started.lunacycle');
+    expect(events[0].payload).toEqual({ module: 'lunacycle', startedAt: 1234 });
+  });
+
+  it('emits deploy.completed.<module> with duration', () => {
+    emitDeployCompleted({ module: 'authentik', startedAt: 1000, durationMs: 5500 });
+    const events = recentEvents();
+    expect(events[0].type).toBe('deploy.completed.authentik');
+    expect((events[0].payload as { durationMs: number }).durationMs).toBe(5500);
+  });
+
+  it('emits deploy.failed.<module> with error', () => {
+    emitDeployFailed({
+      module: 'authentik',
+      startedAt: 1000,
+      durationMs: 200,
+      error: 'oops',
+    });
+    const events = recentEvents();
+    expect(events[0].type).toBe('deploy.failed.authentik');
+    expect((events[0].payload as { error: string }).error).toBe('oops');
+  });
+
+  it('emits health-check.failed.<module>', () => {
+    emitHealthCheckFailed({ module: 'lunacycle', reason: 'http 503' });
+    const events = recentEvents();
+    expect(events[0].type).toBe('health-check.failed.lunacycle');
+  });
+
+  it('triggers persistent subscribers and creates deliveries', () => {
+    // Pre-register a subscriber that targets all completed deploys.
+    const setupBus = openBus({ dbPath, events: defineEvents({}) });
+    setupBus.subscribe({
+      name: 'test-watcher',
+      pattern: 'deploy.completed.*',
+      handler: 'unused',
+    });
+    setupBus.close();
+
+    emitDeployCompleted({ module: 'lunacycle', startedAt: 1, durationMs: 2 });
+
+    const bus = openBus({ dbPath, events: defineEvents({}) });
+    try {
+      const pending = bus.pendingDeliveries();
+      expect(pending).toHaveLength(1);
+    } finally {
+      bus.close();
+    }
+  });
+
+  it('does not throw when the bus path is unwritable', () => {
+    process.env.CELILO_EVENT_BUS_PATH = '/proc/no/such/place/events.db';
+    expect(() => emitDeployStarted({ module: 'x', startedAt: 0 })).not.toThrow();
+  });
+});

package/src/services/celilo-events.ts

@@ -0,0 +1,104 @@
+/**
+ * Celilo's own lifecycle events. Emitted on every `module deploy`
+ * (started / completed / failed) so subscribers can react — production
+ * smoke tests, alerting, dashboards, etc.
+ *
+ * The event types are dot-segmented with the module id as the last
+ * segment: `deploy.started.lunacycle`, `deploy.completed.lunacycle`.
+ * This lets subscribers target one module (`deploy.completed.lunacycle`)
+ * or fan out (`deploy.completed.*`).
+ *
+ * Bus errors are best-effort: a sick bus shouldn't break a deploy. Each
+ * helper opens-emits-closes; per-event overhead is a few ms.
+ */
+
+import { defineEvents, openBus } from '@celilo/event-bus';
+import { z } from 'zod';
+import { getEventBusPath } from '../config/paths';
+
+const NO_SCHEMAS = defineEvents({});
+
+export interface DeployStartedPayload {
+  module: string;
+  startedAt: number;
+}
+
+export interface DeployCompletedPayload {
+  module: string;
+  startedAt: number;
+  durationMs: number;
+}
+
+export interface DeployFailedPayload {
+  module: string;
+  startedAt: number;
+  durationMs: number;
+  error: string;
+}
+
+export interface HealthCheckFailedPayload {
+  module: string;
+  reason: string;
+}
+
+const DeployStartedSchema = z.object({
+  module: z.string().min(1),
+  startedAt: z.number().int().nonnegative(),
+});
+
+const DeployCompletedSchema = z.object({
+  module: z.string().min(1),
+  startedAt: z.number().int().nonnegative(),
+  durationMs: z.number().int().nonnegative(),
+});
+
+const DeployFailedSchema = z.object({
+  module: z.string().min(1),
+  startedAt: z.number().int().nonnegative(),
+  durationMs: z.number().int().nonnegative(),
+  error: z.string(),
+});
+
+const HealthCheckFailedSchema = z.object({
+  module: z.string().min(1),
+  reason: z.string(),
+});
+
+export function emitDeployStarted(payload: DeployStartedPayload): void {
+  DeployStartedSchema.parse(payload);
+  emitBest(`deploy.started.${payload.module}`, payload);
+}
+
+export function emitDeployCompleted(payload: DeployCompletedPayload): void {
+  DeployCompletedSchema.parse(payload);
+  emitBest(`deploy.completed.${payload.module}`, payload);
+}
+
+export function emitDeployFailed(payload: DeployFailedPayload): void {
+  DeployFailedSchema.parse(payload);
+  emitBest(`deploy.failed.${payload.module}`, payload);
+}
+
+export function emitHealthCheckFailed(payload: HealthCheckFailedPayload): void {
+  HealthCheckFailedSchema.parse(payload);
+  emitBest(`health-check.failed.${payload.module}`, payload);
+}
+
+/**
+ * Open the bus, emit, close. Errors are caught and logged so a
+ * misbehaving bus never wedges the caller. The empty-registry mode
+ * skips bus-side payload validation; we validate above with our own
+ * schemas before calling.
+ */
+function emitBest(type: string, payload: unknown): void {
+  let bus: ReturnType<typeof openBus> | undefined;
+  try {
+    bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+    bus.emitRaw(type, payload);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[celilo] failed to emit ${type}: ${msg}`);
+  } finally {
+    bus?.close();
+  }
+}

package/src/services/events-daemon.test.ts

@@ -0,0 +1,184 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  getDaemonUnitPath,
+  installDaemon,
+  readInstalledUnit,
+  renderLaunchdPlist,
+  renderSystemdUnit,
+  uninstallDaemon,
+} from './events-daemon';
+
+describe('renderSystemdUnit', () => {
+  it('produces a unit with the expected ExecStart and Environment lines', () => {
+    const out = renderSystemdUnit({
+      celiloPath: '/usr/local/bin/celilo',
+      busDbPath: '/var/lib/celilo/events.db',
+      pollMs: 1000,
+      concurrency: 4,
+      home: '/home/op',
+    });
+    expect(out).toContain(
+      'ExecStart=/usr/local/bin/celilo events run --poll-ms 1000 --concurrency 4',
+    );
+    expect(out).toContain('Environment=CELILO_EVENT_BUS_PATH=/var/lib/celilo/events.db');
+    expect(out).toContain('Restart=on-failure');
+    expect(out).toContain('WantedBy=default.target');
+  });
+
+  it('honors --poll-ms and --concurrency overrides', () => {
+    const out = renderSystemdUnit({
+      celiloPath: '/c',
+      busDbPath: '/db',
+      pollMs: 250,
+      concurrency: 8,
+      home: '/h',
+    });
+    expect(out).toContain('--poll-ms 250 --concurrency 8');
+  });
+});
+
+describe('renderLaunchdPlist', () => {
+  it('puts log files under the user Library/Logs', () => {
+    const out = renderLaunchdPlist({
+      celiloPath: '/c',
+      busDbPath: '/db',
+      pollMs: 1000,
+      concurrency: 4,
+      home: '/Users/op',
+    });
+    expect(out).toContain('<string>/Users/op/Library/Logs/celilo-events.out.log</string>');
+    expect(out).toContain('<string>/Users/op/Library/Logs/celilo-events.err.log</string>');
+    expect(out).toContain('<key>Label</key>');
+    expect(out).toContain('<string>com.celilo.events</string>');
+    expect(out).toContain('<key>RunAtLoad</key>');
+    expect(out).toContain('<key>KeepAlive</key>');
+  });
+});
+
+describe('getDaemonUnitPath', () => {
+  it('returns the systemd user path on linux', () => {
+    expect(getDaemonUnitPath('linux', '/home/op')).toBe(
+      '/home/op/.config/systemd/user/celilo-events.service',
+    );
+  });
+  it('returns the LaunchAgents path on darwin', () => {
+    expect(getDaemonUnitPath('darwin', '/Users/op')).toBe(
+      '/Users/op/Library/LaunchAgents/com.celilo.events.plist',
+    );
+  });
+});
+
+describe('installDaemon / uninstallDaemon roundtrip', () => {
+  let dir: string;
+  let celiloPath: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'daemon-test-'));
+    celiloPath = join(dir, 'fake-celilo');
+    // Touch a fake celilo executable so resolveCeliloPath via override is happy.
+    writeFileSync(celiloPath, '#!/bin/sh\nexit 0\n');
+    chmodSync(celiloPath, 0o755);
+  });
+  afterEach(() => {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  it('writes a systemd unit and uninstall removes it', () => {
+    const home = join(dir, 'home');
+    const installed = installDaemon({
+      platform: 'linux',
+      home,
+      celiloPath,
+      busDbPath: '/var/lib/celilo/events.db',
+    });
+    expect(existsSync(installed.unitPath)).toBe(true);
+    expect(installed.unitPath).toBe(join(home, '.config/systemd/user/celilo-events.service'));
+    expect(installed.nextSteps[0]).toContain('systemctl --user daemon-reload');
+
+    const removed = uninstallDaemon({ platform: 'linux', home });
+    expect(removed.removed).toBe(true);
+    expect(existsSync(installed.unitPath)).toBe(false);
+  });
+
+  it('writes a launchd plist and uninstall removes it', () => {
+    const home = join(dir, 'home');
+    const installed = installDaemon({
+      platform: 'darwin',
+      home,
+      celiloPath,
+      busDbPath: '/Users/op/celilo/events.db',
+    });
+    expect(existsSync(installed.unitPath)).toBe(true);
+    expect(installed.unitPath).toBe(join(home, 'Library/LaunchAgents/com.celilo.events.plist'));
+    expect(readFileSync(installed.unitPath, 'utf-8')).toContain('com.celilo.events');
+    expect(installed.nextSteps[0]).toContain('launchctl load');
+
+    const removed = uninstallDaemon({ platform: 'darwin', home });
+    expect(removed.removed).toBe(true);
+  });
+
+  it('install is idempotent — second call overwrites with new content', () => {
+    const home = join(dir, 'home');
+    installDaemon({
+      platform: 'linux',
+      home,
+      celiloPath,
+      busDbPath: '/db1',
+      pollMs: 1000,
+    });
+    const second = installDaemon({
+      platform: 'linux',
+      home,
+      celiloPath,
+      busDbPath: '/db2',
+      pollMs: 500,
+    });
+    const written = readFileSync(second.unitPath, 'utf-8');
+    expect(written).toContain('CELILO_EVENT_BUS_PATH=/db2');
+    expect(written).toContain('--poll-ms 500');
+    expect(written).not.toContain('CELILO_EVENT_BUS_PATH=/db1');
+  });
+
+  it('uninstall on a missing unit reports not-removed', () => {
+    const home = join(dir, 'home');
+    const result = uninstallDaemon({ platform: 'linux', home });
+    expect(result.removed).toBe(false);
+    expect(result.nextSteps[0]).toContain('nothing to clean up');
+  });
+
+  it('readInstalledUnit returns content when present, exists:false when not', () => {
+    const home = join(dir, 'home');
+    const before = readInstalledUnit({ platform: 'linux', home });
+    expect(before.exists).toBe(false);
+
+    installDaemon({
+      platform: 'linux',
+      home,
+      celiloPath,
+      busDbPath: '/db',
+    });
+    const after = readInstalledUnit({ platform: 'linux', home });
+    expect(after.exists).toBe(true);
+    if (after.exists) {
+      expect(after.content).toContain('events run');
+    }
+  });
+
+  it('rejects --celilo-path overrides that do not exist', () => {
+    expect(() =>
+      installDaemon({
+        platform: 'linux',
+        home: join(dir, 'home'),
+        celiloPath: '/no/such/celilo',
+        busDbPath: '/db',
+      }),
+    ).toThrow(/does not exist/);
+  });
+});