@celilo/cli 0.2.1 → 0.3.0

package/src/services/events-daemon.ts

@@ -0,0 +1,244 @@
+/**
+ * Generate and install / uninstall a per-user supervisor unit for the
+ * SQLite event-bus dispatcher. Linux gets a systemd user unit; macOS
+ * gets a launchd plist. The command WRITES the unit file but never
+ * touches the supervisor state — the operator runs `systemctl --user
+ * enable --now celilo-events` (or `launchctl load`) themselves so the
+ * effect is visible.
+ *
+ * Why split write-vs-enable: a celilo command silently flipping
+ * systemd state would be hard to reason about during incidents. Pure
+ * file-on-disk + printed next-steps keeps the operational surface
+ * predictable.
+ */
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir, platform as nodePlatform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { getEventBusPath } from '../config/paths';
+
+export type SupervisorPlatform = 'linux' | 'darwin';
+
+export interface InstallDaemonOptions {
+  celiloPath?: string;
+  pollMs?: number;
+  concurrency?: number;
+  /** Override platform detection. Mainly for tests. */
+  platform?: SupervisorPlatform;
+  /** Override the bus DB path. Defaults to celilo's getEventBusPath(). */
+  busDbPath?: string;
+  /** Override the home directory used to compute install paths. */
+  home?: string;
+}
+
+export interface InstallDaemonResult {
+  platform: SupervisorPlatform;
+  unitPath: string;
+  unitContent: string;
+  celiloPath: string;
+  busDbPath: string;
+  nextSteps: string[];
+}
+
+export interface UninstallDaemonResult {
+  platform: SupervisorPlatform;
+  unitPath: string;
+  removed: boolean;
+  nextSteps: string[];
+}
+
+const SYSTEMD_UNIT_NAME = 'celilo-events.service';
+const LAUNCHD_LABEL = 'com.celilo.events';
+
+/**
+ * Map a node `process.platform` to one of the supported supervisor
+ * platforms. We don't ship Windows or BSD support for v1.
+ */
+export function detectPlatform(): SupervisorPlatform {
+  const p = nodePlatform();
+  if (p === 'linux') return 'linux';
+  if (p === 'darwin') return 'darwin';
+  throw new Error(
+    `celilo events daemon: unsupported platform "${p}". Only linux (systemd user) and darwin (launchd) are supported in v1.`,
+  );
+}
+
+/**
+ * Resolve where to write the unit file for a given platform + user.
+ * User-mode locations only; system-wide is opt-in for a future phase.
+ */
+export function getDaemonUnitPath(platform: SupervisorPlatform, home: string): string {
+  if (platform === 'linux') {
+    return join(home, '.config', 'systemd', 'user', SYSTEMD_UNIT_NAME);
+  }
+  return join(home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
+}
+
+/**
+ * Find the celilo executable. Priority:
+ *   1. Explicit override
+ *   2. Bun.which('celilo')
+ *   3. error
+ *
+ * The unit file needs an absolute path because systemd does not resolve
+ * PATH for ExecStart and launchd is similarly literal.
+ */
+export function resolveCeliloPath(override?: string): string {
+  if (override) {
+    if (!existsSync(override)) {
+      throw new Error(`celilo events daemon: --celilo-path "${override}" does not exist`);
+    }
+    return override;
+  }
+  // Bun.which returns null when not found.
+  const found = (Bun as unknown as { which: (cmd: string) => string | null }).which('celilo');
+  if (!found) {
+    throw new Error(
+      'celilo events daemon: could not find `celilo` on PATH. Install it globally (`bun add -g @celilo/cli`) or pass --celilo-path <path>.',
+    );
+  }
+  return found;
+}
+
+interface UnitInputs {
+  celiloPath: string;
+  busDbPath: string;
+  pollMs: number;
+  concurrency: number;
+  home: string;
+}
+
+export function renderSystemdUnit(input: UnitInputs): string {
+  return `[Unit]
+Description=Celilo SQLite Event Bus Dispatcher
+Documentation=https://github.com/psbanka/infra/blob/main/design/SQLITE_EVENT_BUS.md
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${input.celiloPath} events run --poll-ms ${input.pollMs} --concurrency ${input.concurrency}
+Restart=on-failure
+RestartSec=10s
+Environment=CELILO_EVENT_BUS_PATH=${input.busDbPath}
+# stdout/stderr are captured by journalctl --user -u celilo-events.service.
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export function renderLaunchdPlist(input: UnitInputs): string {
+  const logDir = join(input.home, 'Library', 'Logs');
+  // Indentation matters very little to launchd but we want it readable
+  // when an operator opens the file manually to debug.
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${input.celiloPath}</string>
+    <string>events</string>
+    <string>run</string>
+    <string>--poll-ms</string>
+    <string>${input.pollMs}</string>
+    <string>--concurrency</string>
+    <string>${input.concurrency}</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>CELILO_EVENT_BUS_PATH</key>
+    <string>${input.busDbPath}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${join(logDir, 'celilo-events.out.log')}</string>
+  <key>StandardErrorPath</key>
+  <string>${join(logDir, 'celilo-events.err.log')}</string>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * Write the supervisor unit file. Idempotent: rewrites if present.
+ * Returns the path written + the operator-facing next steps.
+ */
+export function installDaemon(opts: InstallDaemonOptions = {}): InstallDaemonResult {
+  const platform = opts.platform ?? detectPlatform();
+  const home = opts.home ?? homedir();
+  const celiloPath = resolveCeliloPath(opts.celiloPath);
+  const busDbPath = opts.busDbPath ?? getEventBusPath();
+  const pollMs = opts.pollMs ?? 1000;
+  const concurrency = opts.concurrency ?? 4;
+
+  const unitPath = getDaemonUnitPath(platform, home);
+  const unitInputs: UnitInputs = { celiloPath, busDbPath, pollMs, concurrency, home };
+  const unitContent =
+    platform === 'linux' ? renderSystemdUnit(unitInputs) : renderLaunchdPlist(unitInputs);
+
+  mkdirSync(dirname(unitPath), { recursive: true });
+  writeFileSync(unitPath, unitContent, { mode: 0o644 });
+
+  const nextSteps =
+    platform === 'linux'
+      ? [
+          'Reload systemd:  systemctl --user daemon-reload',
+          `Enable + start:  systemctl --user enable --now ${SYSTEMD_UNIT_NAME}`,
+          `Tail logs:       journalctl --user -u ${SYSTEMD_UNIT_NAME} -f`,
+          `Status:          systemctl --user status ${SYSTEMD_UNIT_NAME}`,
+        ]
+      : [
+          `Load + start:    launchctl load -w ${unitPath}`,
+          'Tail stdout:     tail -f ~/Library/Logs/celilo-events.out.log',
+          'Tail stderr:     tail -f ~/Library/Logs/celilo-events.err.log',
+          `Status:          launchctl list | grep ${LAUNCHD_LABEL}`,
+        ];
+
+  return { platform, unitPath, unitContent, celiloPath, busDbPath, nextSteps };
+}
+
+export function uninstallDaemon(
+  opts: { platform?: SupervisorPlatform; home?: string } = {},
+): UninstallDaemonResult {
+  const platform = opts.platform ?? detectPlatform();
+  const home = opts.home ?? homedir();
+  const unitPath = getDaemonUnitPath(platform, home);
+
+  let removed = false;
+  if (existsSync(unitPath)) {
+    unlinkSync(unitPath);
+    removed = true;
+  }
+
+  const nextSteps =
+    platform === 'linux'
+      ? removed
+        ? [
+            `Disable + stop:  systemctl --user disable --now ${SYSTEMD_UNIT_NAME}`,
+            'Reload systemd:  systemctl --user daemon-reload',
+          ]
+        : ['No unit file present; nothing to clean up.']
+      : removed
+        ? [`Unload:          launchctl unload ${unitPath}`]
+        : ['No plist present; nothing to clean up.'];
+
+  return { platform, unitPath, removed, nextSteps };
+}
+
+export function readInstalledUnit(
+  opts: { platform?: SupervisorPlatform; home?: string } = {},
+): { exists: true; path: string; content: string } | { exists: false; path: string } {
+  const platform = opts.platform ?? detectPlatform();
+  const home = opts.home ?? homedir();
+  const unitPath = getDaemonUnitPath(platform, home);
+  if (!existsSync(unitPath)) return { exists: false, path: unitPath };
+  return { exists: true, path: unitPath, content: readFileSync(unitPath, 'utf-8') };
+}

package/src/services/module-deploy.ts

@@ -244,10 +244,61 @@ async function invokeHookWithEnsureRetry(
  * @param options - Deployment options
  * @returns Deployment result with phase tracking
  */
+/**
+ * Public entry point. Wraps the core deploy work with event-bus
+ * lifecycle emits (`deploy.started.<id>`, `deploy.completed.<id>`,
+ * `deploy.failed.<id>`) so subscribers — production smoke tests,
+ * alerting, etc. — can react. Bus emit failures are best-effort and
+ * never affect the deploy outcome.
+ */
 export async function deployModule(
   moduleId: string,
   db: DbClient,
   options: DeployOptions = {},
+): Promise<DeployResult> {
+  const startedAt = Date.now();
+  const { emitDeployCompleted, emitDeployFailed, emitDeployStarted, emitHealthCheckFailed } =
+    await import('./celilo-events');
+
+  emitDeployStarted({ module: moduleId, startedAt });
+
+  let result: DeployResult;
+  try {
+    result = await deployModuleImpl(moduleId, db, options);
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    emitDeployFailed({
+      module: moduleId,
+      startedAt,
+      durationMs: Date.now() - startedAt,
+      error,
+    });
+    throw err;
+  }
+
+  const durationMs = Date.now() - startedAt;
+  if (result.success) {
+    emitDeployCompleted({ module: moduleId, startedAt, durationMs });
+  } else {
+    emitDeployFailed({
+      module: moduleId,
+      startedAt,
+      durationMs,
+      error: result.error ?? 'unknown error',
+    });
+    // Health-check failures are a sub-class worth surfacing on their own
+    // channel so subscribers can target them without parsing error strings.
+    if (result.error?.toLowerCase().includes('health check')) {
+      emitHealthCheckFailed({ module: moduleId, reason: result.error });
+    }
+  }
+  return result;
+}
+
+async function deployModuleImpl(
+  moduleId: string,
+  db: DbClient,
+  options: DeployOptions = {},
 ): Promise<DeployResult> {
   const phases: DeployResult['phases'] = {};
 

package/src/services/module-subscriptions.test.ts

@@ -0,0 +1,197 @@
+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 type { ModuleManifest } from '../manifest/schema';
+import {
+  registerModuleSubscriptions,
+  resolveSubscription,
+  unregisterModuleSubscriptions,
+} from './module-subscriptions';
+
+const baseManifest = (overrides: Partial<ModuleManifest> = {}): ModuleManifest => ({
+  celilo_contract: '1.0',
+  id: 'lunacycle',
+  name: 'Lunacycle',
+  version: '1.0.0',
+  requires: { capabilities: [] },
+  provides: { capabilities: [] },
+  variables: { owns: [], imports: [] },
+  ...overrides,
+});
+
+describe('resolveSubscription', () => {
+  it('substitutes $self in pattern and ${MODULE_PATH} in handler', () => {
+    const resolved = resolveSubscription(
+      {
+        name: 'smoke-after-deploy',
+        pattern: 'deploy.completed.$self',
+        handler: 'bun ${MODULE_PATH}/celilo/scripts/smoke.ts',
+      },
+      'lunacycle',
+      '/var/lib/celilo/modules/lunacycle',
+    );
+
+    expect(resolved.name).toBe('lunacycle.smoke-after-deploy');
+    expect(resolved.pattern).toBe('deploy.completed.lunacycle');
+    expect(resolved.handler).toBe('bun /var/lib/celilo/modules/lunacycle/celilo/scripts/smoke.ts');
+    expect(resolved.registeredBy).toBe('lunacycle');
+  });
+
+  it('only substitutes $self when followed by . or end-of-string', () => {
+    // `$selfish` would not be a real pattern but we want to ensure the
+    // substitution doesn't accidentally rewrite identifier-like names.
+    const resolved = resolveSubscription(
+      {
+        name: 'a',
+        pattern: '$self.x.$selfish',
+        handler: 'echo',
+      },
+      'foo',
+      '/p',
+    );
+    expect(resolved.pattern).toBe('foo.x.$selfish');
+  });
+
+  it('passes through max_attempts and timeout_ms when set', () => {
+    const resolved = resolveSubscription(
+      {
+        name: 'a',
+        pattern: 'x',
+        handler: 'echo',
+        max_attempts: 5,
+        timeout_ms: 90000,
+      },
+      'foo',
+      '/p',
+    );
+    expect(resolved.maxAttempts).toBe(5);
+    expect(resolved.timeoutMs).toBe(90000);
+  });
+});
+
+describe('register / unregister roundtrip', () => {
+  let dir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'modsubs-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 */
+    }
+  });
+
+  it('manifest with no subscriptions is a no-op', () => {
+    const result = registerModuleSubscriptions(baseManifest(), '/p');
+    expect(result.registered).toBe(0);
+  });
+
+  it('registers each subscription as a row, names scoped to module id', () => {
+    const result = registerModuleSubscriptions(
+      baseManifest({
+        subscriptions: [
+          {
+            name: 'smoke',
+            pattern: 'deploy.completed.$self',
+            handler: 'bun ${MODULE_PATH}/x.ts',
+          },
+          {
+            name: 'on-cert-rotated',
+            pattern: 'cert.rotated',
+            handler: 'echo',
+          },
+        ],
+      }),
+      '/var/lib/celilo/modules/lunacycle',
+    );
+    expect(result.registered).toBe(2);
+
+    const bus = openBus({ dbPath, events: defineEvents({}) });
+    try {
+      const rows = bus.db
+        .query<{ name: string; pattern: string; handler: string }, []>(
+          'SELECT name, pattern, handler FROM subscribers ORDER BY name',
+        )
+        .all();
+      expect(rows).toEqual([
+        {
+          name: 'lunacycle.on-cert-rotated',
+          pattern: 'cert.rotated',
+          handler: 'echo',
+        },
+        {
+          name: 'lunacycle.smoke',
+          pattern: 'deploy.completed.lunacycle',
+          handler: 'bun /var/lib/celilo/modules/lunacycle/x.ts',
+        },
+      ]);
+    } finally {
+      bus.close();
+    }
+  });
+
+  it('re-registering the same manifest is idempotent (updates rows in place)', () => {
+    const m = baseManifest({
+      subscriptions: [{ name: 's', pattern: 'a', handler: 'echo first' }],
+    });
+    registerModuleSubscriptions(m, '/p');
+    // Edit the in-memory manifest and re-register; same name, new handler.
+    if (!m.subscriptions) throw new Error('subscriptions missing');
+    m.subscriptions[0].handler = 'echo second';
+    registerModuleSubscriptions(m, '/p');
+
+    const bus = openBus({ dbPath, events: defineEvents({}) });
+    try {
+      const rows = bus.db
+        .query<{ count: number }, []>('SELECT COUNT(*) AS count FROM subscribers')
+        .get();
+      expect(rows?.count).toBe(1);
+      const row = bus.db.query<{ handler: string }, []>('SELECT handler FROM subscribers').get();
+      expect(row?.handler).toBe('echo second');
+    } finally {
+      bus.close();
+    }
+  });
+
+  it('unregister removes all subscriptions for the module, scoped by name prefix', () => {
+    registerModuleSubscriptions(
+      baseManifest({
+        id: 'lunacycle',
+        subscriptions: [
+          { name: 'a', pattern: 'x.$self', handler: 'echo' },
+          { name: 'b', pattern: 'y.$self', handler: 'echo' },
+        ],
+      }),
+      '/p',
+    );
+    // Another module's subs should NOT be touched.
+    registerModuleSubscriptions(
+      baseManifest({
+        id: 'authentik',
+        subscriptions: [{ name: 'a', pattern: 'z.$self', handler: 'echo' }],
+      }),
+      '/p',
+    );
+
+    const result = unregisterModuleSubscriptions('lunacycle');
+    expect(result.unregistered).toBe(2);
+
+    const bus = openBus({ dbPath, events: defineEvents({}) });
+    try {
+      const rows = bus.db
+        .query<{ name: string }, []>('SELECT name FROM subscribers ORDER BY name')
+        .all();
+      expect(rows).toEqual([{ name: 'authentik.a' }]);
+    } finally {
+      bus.close();
+    }
+  });
+});

package/src/services/module-subscriptions.ts

@@ -0,0 +1,120 @@
+/**
+ * Wire a module's manifest `subscriptions:` block into the SQLite event
+ * bus. Called from `module/import.ts` on install and from
+ * `cli/commands/module-remove.ts` on remove.
+ *
+ * Substitutions performed at subscribe time:
+ *   - `$self` in `pattern`    → the module's id
+ *   - `${MODULE_PATH}` in `handler` → the module's installed targetPath
+ *
+ * The bus subscriber's name is namespaced as `<module-id>.<sub-name>`
+ * so two modules can declare a subscription named `smoke` without
+ * colliding.
+ */
+
+import { defineEvents, openBus } from '@celilo/event-bus';
+import { getEventBusPath } from '../config/paths';
+import type { ModuleManifest, ModuleSubscription } from '../manifest/schema';
+
+/**
+ * The bus is opened by the celilo CLI without an event registry — the
+ * CLI doesn't know the schemas of every module's events. The bus's
+ * empty-registry path skips payload validation, leaving that to the
+ * linked handlers (which open the bus *with* their own registry).
+ */
+const NO_SCHEMAS = defineEvents({});
+
+/**
+ * Resolve the per-module substitutions on a single subscription. Pure
+ * function: takes a parsed manifest entry, returns the bus-shaped
+ * subscribe options.
+ */
+export function resolveSubscription(
+  sub: ModuleSubscription,
+  moduleId: string,
+  modulePath: string,
+): {
+  name: string;
+  pattern: string;
+  handler: string;
+  maxAttempts?: number;
+  timeoutMs?: number;
+  registeredBy: string;
+} {
+  return {
+    name: scopedName(moduleId, sub.name),
+    pattern: substituteSelf(sub.pattern, moduleId),
+    handler: substituteModulePath(sub.handler, modulePath),
+    maxAttempts: sub.max_attempts,
+    timeoutMs: sub.timeout_ms,
+    registeredBy: moduleId,
+  };
+}
+
+/**
+ * Register all of a module's subscriptions on the bus. Idempotent —
+ * re-running with the same manifest updates existing rows in place.
+ *
+ * If the module's manifest declares no subscriptions, this is a
+ * cheap no-op (the bus DB isn't even touched).
+ */
+export function registerModuleSubscriptions(
+  manifest: ModuleManifest,
+  modulePath: string,
+): { registered: number } {
+  const subs = manifest.subscriptions ?? [];
+  if (subs.length === 0) return { registered: 0 };
+
+  const bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+  try {
+    for (const sub of subs) {
+      const resolved = resolveSubscription(sub, manifest.id, modulePath);
+      bus.subscribe(resolved);
+    }
+    return { registered: subs.length };
+  } finally {
+    bus.close();
+  }
+}
+
+/**
+ * Tear down every bus subscription that belongs to this module. Looks
+ * up rows by name prefix `<module-id>.` rather than rereading the
+ * old manifest, so a stale subscription left behind by a manifest
+ * change still gets cleaned up.
+ *
+ * Best-effort: if the bus DB doesn't exist (never opened), returns 0.
+ */
+export function unregisterModuleSubscriptions(moduleId: string): {
+  unregistered: number;
+} {
+  const bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+  try {
+    const likePattern = `${moduleId}.%`;
+    const rows = bus.db
+      .query<{ name: string }, [string]>('SELECT name FROM subscribers WHERE name LIKE ?')
+      .all(likePattern);
+    for (const row of rows) {
+      bus.unsubscribe(row.name);
+    }
+    return { unregistered: rows.length };
+  } finally {
+    bus.close();
+  }
+}
+
+function scopedName(moduleId: string, subName: string): string {
+  return `${moduleId}.${subName}`;
+}
+
+function substituteSelf(pattern: string, moduleId: string): string {
+  // `$self` matches when followed by a dot or end-of-string, so a
+  // pattern like `deploy.$self.foo` substitutes correctly without
+  // confusing `$selfish` if anyone wrote that. (No real reason they
+  // would, but be precise.)
+  return pattern.replace(/\$self(?=\.|$)/g, moduleId);
+}
+
+function substituteModulePath(handler: string, modulePath: string): string {
+  return handler.replace(/\$\{MODULE_PATH\}/g, modulePath);
+}