@celilo/cli 0.2.1 → 0.3.1

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,26 @@ export function getDbPath(): string {
   return join(getDataDir(), 'celilo.db');
 }
 
+/**
+ * Get the SQLite event-bus database file path.
+ *
+ * Priority:
+ * 1. EVENT_BUS_DB environment variable (the bus library's native name —
+ *    used by the event-bus CLI, defineHandler, and any standalone tool)
+ * 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.EVENT_BUS_DB) {
+    return process.env.EVENT_BUS_DB;
+  }
+  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

@@ -23,6 +23,25 @@ import {
 import { parseJsonWithValidation } from '../validation/schemas';
 import { cleanupTempDir, extractPackage, verifyPackageIntegrity } from './packaging/extract';
 
+/**
+ * Phase-timing helper for `celilo module import`. Set CELILO_IMPORT_DEBUG=1
+ * to get a phase-by-phase breakdown to stderr — useful when an import is
+ * inexplicably slow (e.g. a Docker bind-mount fsync amplification, a stale
+ * lockfile triggering a fresh bun install, etc.).
+ *
+ * Zero overhead when disabled: the wrapper just calls the inner fn.
+ */
+async function timedPhase<T>(label: string, fn: () => Promise<T> | T): Promise<T> {
+  if (!process.env.CELILO_IMPORT_DEBUG) return await fn();
+  const start = Date.now();
+  try {
+    return await fn();
+  } finally {
+    const ms = Date.now() - start;
+    process.stderr.write(`[import-timing] ${label.padEnd(36)} ${ms}ms\n`);
+  }
+}
+
 /**
  * Module import options
  */
@@ -547,7 +566,7 @@ export async function importModule(options: ModuleImportOptions): Promise<Module
 
     // Execution: Copy files
     try {
-      await copyModuleFiles(actualSourcePath, targetPath);
+      await timedPhase('copyModuleFiles', () => copyModuleFiles(actualSourcePath, targetPath));
     } catch (error) {
       if (tempDir) await cleanupTempDir(tempDir);
       return {
@@ -563,7 +582,9 @@ export async function importModule(options: ModuleImportOptions): Promise<Module
     // If no package.json exists but hook scripts do, auto-generate one with
     // just the framework dep — smooths migration for existing modules.
     try {
-      await installScriptDependencies(targetPath, manifest);
+      await timedPhase('installScriptDependencies', () =>
+        installScriptDependencies(targetPath, manifest),
+      );
     } catch (error) {
       // Non-fatal: the module is importable without deps, but hooks
       // will fail at runtime. Warn and continue.
@@ -574,7 +595,7 @@ export async function importModule(options: ModuleImportOptions): Promise<Module
 
     // Execution: Insert to database
     try {
-      await insertModuleToDb(manifest, targetPath, db);
+      await timedPhase('insertModuleToDb', () => insertModuleToDb(manifest, targetPath, db));
     } catch (error) {
       if (tempDir) await cleanupTempDir(tempDir);
       return {
@@ -586,8 +607,10 @@ export async function importModule(options: ModuleImportOptions): Promise<Module
 
     // Execution: Register capabilities if module provides them
     if (manifest.provides?.capabilities && manifest.provides.capabilities.length > 0) {
-      const { registerModuleCapabilities } = await import('../capabilities/registration');
-      const capResult = await registerModuleCapabilities(manifest.id, manifest, db.$client, flags);
+      const capResult = await timedPhase('registerModuleCapabilities', async () => {
+        const { registerModuleCapabilities } = await import('../capabilities/registration');
+        return registerModuleCapabilities(manifest.id, manifest, db.$client, flags);
+      });
 
       if (!capResult.success) {
         if (tempDir) await cleanupTempDir(tempDir);
@@ -599,6 +622,23 @@ 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 {
+      await timedPhase('registerModuleSubscriptions', async () => {
+        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.EVENT_BUS_DB = dbPath;
+  });
+  afterEach(() => {
+    process.env.EVENT_BUS_DB = 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.EVENT_BUS_DB = '/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();
+  }
+}