@celilo/cli 0.2.0 → 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/cli/prompts.ts

@@ -122,7 +122,7 @@ export function showNote(message: string, title?: string): void {
 export const log = {
   success: (message: string) => {
     const d = getActiveDisplay();
-    if (d) return d.subEvent(`\x1b[32m✓\x1b[0m ${message}`);
+    if (d) return d.subEvent(`\x1b[32m✔\x1b[0m ${message}`);
     p.log.success(message);
   },
   error: (message: string) => {

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/hooks/define-hook.test.ts

@@ -91,6 +91,9 @@ const fakeIdp: IdpCapability = {
   async create_user() {
     return { user_id: 1, created: true };
   },
+  async create_token() {
+    return { token: 'fake-token', created: true };
+  },
 };
 
 describe('defineHook', () => {
@@ -253,6 +256,9 @@ describe('defineCapabilityFunction', () => {
         async create_user() {
           return { user_id: 1, created: true };
         },
+        async create_token() {
+          return { token: 'fake-token', created: true };
+        },
       }),
     });
 
@@ -313,6 +319,9 @@ describe('defineCapabilityFunction', () => {
           async create_user(_request: CreateUserRequest): Promise<CreateUserResult> {
             return { user_id: 1, created: true };
           },
+          async create_token(): Promise<{ token: string; created: boolean }> {
+            return { token: 'tok', created: true };
+          },
         };
       },
     });
@@ -443,6 +452,9 @@ void defineCapabilityFunction({
     async create_user() {
       return { user_id: 1, created: true };
     },
+    async create_token() {
+      return { token: 'x', created: true };
+    },
   }),
 });
 

package/src/hooks/executor.ts

@@ -7,6 +7,15 @@
  * - Output validation
  * - Structured logging
  *
+ * **Execution model:** hook scripts run *in-process* on the celilo CLI host.
+ * `runScript` dynamically `import()`s the hook module and awaits its default
+ * export. They do NOT execute on the target machine. A hook that needs to
+ * touch the target initiates SSH outbound itself (see e.g.
+ * modules/lunacycle/celilo/scripts/health-check.ts's `ssh()` helper). This
+ * means hook scripts can freely use npm packages, make HTTP calls, read
+ * local files, etc. — and conversely, anything they depend on (chromium,
+ * system binaries, credentials) must be available on the celilo CLI host.
+ *
  * Execution function (Rule 10.1) - performs side effects (script execution)
  */
 

package/src/hooks/logger.ts

@@ -66,6 +66,44 @@ export function createGaugeLogger(
     warn: (message: string) => emit('warn', message),
     error: (message: string) => emit('error', message),
     success: (message: string) => emit('success', message),
+    beginStep: (name: string) => {
+      const display = getActiveDisplay();
+      if (display) {
+        // pushStep nests under the FuelGauge step that wraps the hook,
+        // so inner log calls (logger.info within the capability impl)
+        // are sub-events of this nested step.
+        display.pushStep(`→ ${name}`, `✓ ${name}`);
+      } else {
+        // Without a display, fall back to a plain info-style marker so
+        // the line still appears in raw log output.
+        gauge.addOutput(`${prefix} → ${name}`);
+        if (nonInteractive) {
+          process.stdout.write(`${prefix} → ${name}\n`);
+        }
+      }
+    },
+    endStep: (_name: string) => {
+      const display = getActiveDisplay();
+      if (display) {
+        display.doneStep();
+      } else {
+        gauge.addOutput(`${prefix} ✓ ${_name}`);
+        if (nonInteractive) {
+          process.stdout.write(`${prefix} ✓ ${_name}\n`);
+        }
+      }
+    },
+    failStep: (name: string, error: string) => {
+      const display = getActiveDisplay();
+      if (display) {
+        display.failStep(`${name}: ${error}`);
+      } else {
+        gauge.addOutput(`${prefix} ✗ ${name}: ${error}`);
+        if (nonInteractive) {
+          process.stdout.write(`${prefix} ✗ ${name}: ${error}\n`);
+        }
+      }
+    },
   };
 }
 

package/src/hooks/types.ts

@@ -24,13 +24,24 @@ export interface HookDefinition {
 }
 
 /**
- * Logger interface provided to hook scripts
+ * Logger interface provided to hook scripts.
+ *
+ * Mirrors `HookLogger` in `@celilo/capabilities/types` — kept in sync so
+ * concrete loggers we build here (createGaugeLogger, createConsoleLogger,
+ * createCapturingLogger) satisfy both the in-process consumers and the
+ * cross-package contract used by `wrapWithLogging`.
  */
 export interface HookLogger {
   info(message: string): void;
   warn(message: string): void;
   error(message: string): void;
   success(message: string): void;
+  /** Begin a logical span. Subsequent log calls nest under it visually. */
+  beginStep?(name: string): void;
+  /** End the current span (success). */
+  endStep?(name: string): void;
+  /** End the current span (failure) with an error message. */
+  failStep?(name: string, error: string): void;
 }
 
 /**

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

@@ -993,6 +993,74 @@ describe('validateDeriveFromSources', () => {
     const result = validateDeriveFromSources(manifest);
     expect(result).toBeNull();
   });
+
+  test('should accept $self: references regardless of source', () => {
+    // $self: points at another variable in this same manifest, so it
+    // doesn't introduce the cross-context mismatch the validator exists
+    // to catch (e.g. authentik's auth_url derives from $self:domain).
+    const manifest = {
+      celilo_contract: '1.0' as const,
+      id: 'authentik',
+      name: 'Authentik',
+      version: '1.0.0',
+      requires: { capabilities: [] },
+      provides: { capabilities: [] },
+      variables: {
+        owns: [
+          {
+            name: 'domain',
+            type: 'string' as const,
+            required: true,
+            source: 'user' as const,
+          },
+          {
+            name: 'auth_url',
+            type: 'string' as const,
+            required: false,
+            source: 'capability' as const,
+            derive_from: 'https://auth.$self:domain',
+          },
+        ],
+        imports: [],
+      },
+    };
+
+    const result = validateDeriveFromSources(manifest);
+    expect(result).toBeNull();
+  });
+
+  test('should still reject mixed $self: and $system: when source is capability', () => {
+    // Self-refs are exempt, but other foreign sources still trigger the
+    // mismatch error. This guards against accidentally green-lighting
+    // "$self:foo and $system:bar" combos.
+    const manifest = {
+      celilo_contract: '1.0' as const,
+      id: 'test',
+      name: 'Test',
+      version: '1.0.0',
+      requires: { capabilities: [] },
+      provides: { capabilities: [] },
+      variables: {
+        owns: [
+          {
+            name: 'mixed',
+            type: 'string' as const,
+            required: false,
+            source: 'capability' as const,
+            derive_from: '$self:domain/$system:primary_domain',
+          },
+        ],
+        imports: [],
+      },
+    };
+
+    const result = validateDeriveFromSources(manifest);
+    expect(result).not.toBeNull();
+    if (result) {
+      expect(result.errors[0]?.message).toContain('$system:');
+      expect(result.errors[0]?.message).not.toContain('$self:');
+    }
+  });
 });
 
 describe('validateHookContract', () => {
@@ -1178,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/manifest/validate.ts

@@ -285,9 +285,13 @@ export function validateZoneRequirements(manifest: ModuleManifest): ValidationEr
  *
  * Rules:
  * - `source: capability` → `derive_from` must only reference `$capability:`
- *   tokens (and may also include `{var}` placeholders).
+ *   tokens (and may also include `{var}` and `$self:` placeholders).
  * - `source: system` → `derive_from` must only reference `$system:` tokens
- *   (and `{var}` placeholders).
+ *   (and `{var}` and `$self:` placeholders).
+ * - `$self:` references are allowed under *any* source. They point at
+ *   another variable owned by the same manifest, so they don't introduce
+ *   a cross-context mismatch — that's the bug class this validator was
+ *   built to catch.
  * - Other sources (`user`, `infrastructure`, `terraform`) — `derive_from` is
  *   optional and unconstrained; we don't check the prefix.
  */
@@ -306,7 +310,9 @@ export function validateDeriveFromSources(manifest: ModuleManifest): ValidationE
     if (!expected) continue;
 
     const tokens = [...variable.derive_from.matchAll(tokenPattern)].map((m) => m[1]);
-    const offending = tokens.filter((t) => t !== expected);
+    // `self` is always allowed: it references another variable in this
+    // same manifest, which is the same context as the declared source.
+    const offending = tokens.filter((t) => t !== expected && t !== 'self');
     if (offending.length > 0) {
       const unique = Array.from(new Set(offending)).join(', ');
       errors.push({

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();
+  });
+});