@celilo/cli 2.2.1 → 3.0.0

package/src/services/build-bus/hook-dispatcher.ts

@@ -1,10 +1,16 @@
 /**
  * Build-bus hook dispatcher service.
  *
- * Stateful wrapper around `planHookDispatch` + `runHookDispatch`:
+ * Stateful wrapper around `planHookDispatch` + `runUpstreamHook`:
  * loads installed-module manifests from the celilo DB, dispatches
  * matching `on_upstream_publish` hooks when a verified PublishEvent
- * arrives, logs outcomes.
+ * arrives, and records every run durably in the `build_bus_hook_runs`
+ * ledger (celilo#1304) — without which a failed run exists only as
+ * daemon console output, which no surface reads. Since
+ * module-orchestrator-primitives slice 7 it also performs the FRAMEWORK
+ * self-update on the same events (tasks.md 7.2): celilo replacing its
+ * own binaries on the management host is class H work that stopped
+ * being a module hook (design D6).
  *
  * Started by the `celilo subscribers serve` daemon (in-process,
  * sharing the same lifetime); the receiver-server calls
@@ -18,62 +24,167 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { PublishEvent } from '@celilo/event-bus/build-bus';
+import { eq } from 'drizzle-orm';
 import { parse as parseYaml } from 'yaml';
 import { getDb } from '../../db/client';
-import { modules } from '../../db/schema';
+import { buildBusHookRuns, modules } from '../../db/schema';
+import { CONTROL_PLANE_MODULE_ID } from '../deployed-systems';
 import {
-  type HookRunResult,
+  type HookDispatchPlan,
   type ModuleHookContext,
   type UpstreamHookEntry,
+  type UpstreamHookResult,
+  defaultUpstreamHookDeps,
   planHookDispatch,
-  runHookDispatch,
+  runUpstreamHook,
 } from './hook-dispatch';
+import { type SelfUpdatePlan, planSelfUpdate, runSelfUpdate } from './self-update';
 
 export interface HookDispatcher {
   /** Run the matching hooks for a single event. Returns the per-hook results. */
-  handleEvent(event: PublishEvent): Promise<HookRunResult[]>;
+  handleEvent(event: PublishEvent): Promise<UpstreamHookResult[]>;
   /** Clean up (currently a no-op; included for symmetry with the receiver). */
   stop(): Promise<void>;
 }
 
 export interface HookDispatcherOptions {
+  /**
+   * Database for the default executor hop. Production omits it and the
+   * process database opens lazily; tests inject an isolated client.
+   */
+  db?: Parameters<typeof defaultUpstreamHookDeps>[0];
   /**
    * Override the module-loading step. Tests inject a fixture; in
    * production we omit and the dispatcher reads from the celilo
    * modules table.
    */
   loadModules?: () => ModuleHookContext[];
+  /**
+   * Override the executor hop for one matched upstream-publish entry.
+   * Production omits it; `runUpstreamHook` over the process database runs.
+   */
+  runUpstreamHook?: (plan: HookDispatchPlan, event: PublishEvent) => Promise<UpstreamHookResult>;
+  /**
+   * Override the durable outcome record. The production default writes one
+   * `build_bus_hook_runs` row per run — without it a failed hook run or
+   * self-update exists only as daemon console output, which no surface
+   * reads (celilo#1304). Tests inject a capture to stay DB-free. The plan
+   * is passed because the jailed executor result does not carry the
+   * script path; the ledger's `script_path` column is NOT NULL.
+   */
+  recordRun?: (event: PublishEvent, plan: HookDispatchPlan, result: UpstreamHookResult) => void;
+  /**
+   * Override "is the control-plane module installed", the gate for the
+   * framework self-update. Production reads the modules table; tests
+   * inject the answer.
+   */
+  controlPlaneInstalled?: () => boolean;
+  /** Override the self-update runner. Production: `runSelfUpdate`. */
+  selfUpdate?: (plan: SelfUpdatePlan) => ReturnType<typeof runSelfUpdate>;
+}
+
+/** Bound on error tails so one chatty hook cannot bloat the ledger. */
+const TAIL_CHARS = 2000;
+
+function tail(s: string): string {
+  return s.length > TAIL_CHARS ? s.slice(-TAIL_CHARS) : s;
+}
+
+/**
+ * The production outcome record: one `build_bus_hook_runs` row per run.
+ * Throwing here would 500 nothing (the webhook already succeeded) but
+ * would kill dispatch of later plans, so a record failure is logged and
+ * swallowed — the console outcome lines below remain the fallback signal.
+ *
+ * The jailed executor path (slice 7) does not expose exit codes or
+ * captured stdio, so `exit_code` is always null — the column's "the
+ * script never reached an exit" semantics now hold of the path itself —
+ * and the executor's error text lands in `stderr_tail`.
+ */
+function recordHookRun(
+  event: PublishEvent,
+  plan: HookDispatchPlan,
+  result: UpstreamHookResult,
+): void {
+  try {
+    getDb()
+      .insert(buildBusHookRuns)
+      .values({
+        eventId: event.eventId,
+        packageName: event.package.name,
+        packageVersion: event.package.version,
+        tag: event.tag,
+        moduleId: result.module,
+        hookName: result.hookName,
+        scriptPath: plan.hook.script,
+        exitCode: null,
+        timedOut: false,
+        durationMs: result.durationMs,
+        stdoutTail: null,
+        stderrTail: result.error ? tail(result.error) : null,
+      })
+      .run();
+  } catch (err) {
+    console.warn(
+      `[build-bus] could not record hook run outcome: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
 }
 
 export async function startHookDispatcher(
   opts: HookDispatcherOptions = {},
 ): Promise<HookDispatcher> {
   const loadModules = opts.loadModules ?? loadInstalledModulesWithHooks;
+  const runEntry =
+    opts.runUpstreamHook ??
+    ((plan, event) => runUpstreamHook(plan, event, defaultUpstreamHookDeps(opts.db)));
+  const recordRun = opts.recordRun ?? recordHookRun;
+  const isControlPlaneInstalled = opts.controlPlaneInstalled ?? defaultControlPlaneInstalled;
+  const selfUpdateRunner = opts.selfUpdate ?? ((plan) => runSelfUpdate(plan));
 
   return {
     async handleEvent(event) {
+      // Framework self-update first (design D6): celilo replacing celilo's
+      // own binaries is not a module hook, and the dispatcher is the
+      // component that already receives the publish event.
+      const update = planSelfUpdate(event);
+      if (update && isControlPlaneInstalled()) {
+        console.log(
+          `[build-bus] self-update: ${update.packageName}@${update.version} (@${event.tag})`,
+        );
+        const result = selfUpdateRunner(update);
+        if (result.updated && result.verified) {
+          console.log(
+            `  ✓ ${update.binary} reports ${result.version} (was ${result.beforeVersion ?? 'not installed'})`,
+          );
+        } else {
+          console.warn(`  ✗ self-update did not complete: ${result.error ?? 'unknown error'}`);
+        }
+      }
+
       const moduleContexts = loadModules();
       const plans = planHookDispatch(event, moduleContexts);
       if (plans.length === 0) {
-        console.log(
-          `[build-bus] ${event.package.name}@${event.package.version} (${event.tag}) — no module hooks match`,
-        );
+        if (!update) {
+          console.log(
+            `[build-bus] ${event.package.name}@${event.package.version} (${event.tag}) — no module hooks match`,
+          );
+        }
         return [];
       }
-      const results: HookRunResult[] = [];
+      const results: UpstreamHookResult[] = [];
       for (const plan of plans) {
         console.log(
           `[build-bus] ${event.package.name}@${event.package.version} → ${plan.module.moduleId} (${plan.hook.name ?? plan.hook.script})`,
         );
-        const result = await runHookDispatch(plan);
+        const result = await runEntry(plan, event);
+        recordRun(event, plan, result);
         results.push(result);
-        if (result.exitCode === 0) {
-          console.log(`  ✓ exit 0 in ${result.durationMs}ms`);
-        } else if (result.timedOut) {
-          console.warn(`  ✗ timed out after ${result.durationMs}ms`);
+        if (result.success) {
+          console.log(`  ✓ success in ${result.durationMs}ms`);
         } else {
-          console.warn(`  ✗ exit ${result.exitCode} in ${result.durationMs}ms`);
-          if (result.stderr) console.warn(`    stderr: ${result.stderr.trim().slice(0, 500)}`);
+          console.warn(`  ✗ failed in ${result.durationMs}ms`);
+          if (result.error) console.warn(`    ${result.error.trim().slice(0, 500)}`);
         }
       }
       return results;
@@ -85,6 +196,21 @@ export async function startHookDispatcher(
   };
 }
 
+/**
+ * The framework self-update runs only where the control-plane module is
+ * deployed — the same population celilo-mgmt's hook covered, since the
+ * module is installed on the management host and nowhere else.
+ */
+function defaultControlPlaneInstalled(): boolean {
+  const db = getDb();
+  const row = db
+    .select({ id: modules.id })
+    .from(modules)
+    .where(eq(modules.id, CONTROL_PLANE_MODULE_ID))
+    .get();
+  return row != null;
+}
+
 /**
  * Load every installed module's `on_upstream_publish` hooks from the
  * celilo DB + each module's manifest.yml. Modules without the hook

package/src/services/build-bus/receiver-daemon.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, it } from 'bun:test';
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  getReceiverUnitPath,
+  installReceiverDaemon,
+  planReceiverInstall,
+  renderReceiverLaunchdPlist,
+  renderReceiverSystemdUnit,
+  uninstallReceiverDaemon,
+} from './receiver-daemon';
+
+const SECRET = 'a1b2c3d4e5f6secret';
+
+// resolveCeliloPath existence-checks explicit overrides, so plan tests need
+// a path that exists — a fake binary in a temp dir.
+const FAKE_CELOLILO = join(mkdtempSync(join(tmpdir(), 'celilo-fake-bin-')), 'celilo');
+writeFileSync(FAKE_CELOLILO, '#!/bin/sh\n', { mode: 0o755 });
+
+describe('renderReceiverSystemdUnit', () => {
+  it('runs `subscribers serve` with --no-dispatch and the secret as an Environment line', () => {
+    const out = renderReceiverSystemdUnit({
+      celiloPath: FAKE_CELOLILO,
+      port: 8123,
+      secret: SECRET,
+      scope: 'user',
+      dispatch: false,
+    });
+    expect(out).toContain('subscribers serve --port 8123 --no-dispatch');
+    expect(out).toContain(`Environment=CELILO_BUS_SECRET=${SECRET}`);
+    expect(out).toContain('Restart=on-failure');
+    expect(out).toContain('WantedBy=default.target');
+    expect(out).not.toContain('User=');
+  });
+
+  it('honors the port and a --dispatch render for boxes without the events daemon', () => {
+    const out = renderReceiverSystemdUnit({
+      celiloPath: '/c',
+      port: 9999,
+      secret: SECRET,
+      scope: 'user',
+      dispatch: true,
+    });
+    expect(out).toContain('ExecStart=/c subscribers serve --port 9999');
+    expect(out).not.toContain('--no-dispatch');
+  });
+
+  it('system scope sets an explicit User= and multi-user.target', () => {
+    const out = renderReceiverSystemdUnit({
+      celiloPath: FAKE_CELOLILO,
+      port: 8123,
+      secret: SECRET,
+      scope: 'system',
+      runAsUser: 'celilo',
+      dispatch: false,
+    });
+    expect(out).toContain('User=celilo');
+    expect(out).toContain('WantedBy=multi-user.target');
+    expect(out).toContain('journalctl -u celilo-build-bus-receiver.service');
+    expect(out).not.toContain('journalctl --user');
+  });
+});
+
+describe('renderReceiverLaunchdPlist', () => {
+  it('carries the secret under EnvironmentVariables and --no-dispatch by default', () => {
+    const out = renderReceiverLaunchdPlist({
+      celiloPath: FAKE_CELOLILO,
+      port: 8123,
+      secret: SECRET,
+      scope: 'system',
+      home: '/root',
+      dispatch: false,
+    });
+    expect(out).toContain('<key>Label</key>');
+    expect(out).toContain('com.celilo.build-bus-receiver');
+    expect(out).toContain('<key>CELILO_BUS_SECRET</key>');
+    expect(out).toContain(`<string>${SECRET}</string>`);
+    expect(out).toContain('<string>--no-dispatch</string>');
+    expect(out).toContain('<string>subscribers</string>');
+  });
+});
+
+describe('getReceiverUnitPath', () => {
+  it('names the unit distinctly from the dispatcher unit in every platform/scope', () => {
+    expect(getReceiverUnitPath('linux', '/home/op', 'user')).toBe(
+      join('/home/op/.config/systemd/user', 'celilo-build-bus-receiver.service'),
+    );
+    expect(getReceiverUnitPath('linux', '/root', 'system')).toBe(
+      '/etc/systemd/system/celilo-build-bus-receiver.service',
+    );
+    expect(getReceiverUnitPath('darwin', '/root', 'system')).toBe(
+      '/Library/LaunchDaemons/com.celilo.build-bus-receiver.plist',
+    );
+    expect(getReceiverUnitPath('darwin', '/home/op', 'user')).toBe(
+      '/home/op/Library/LaunchAgents/com.celilo.build-bus-receiver.plist',
+    );
+  });
+});
+
+describe('planReceiverInstall', () => {
+  it('requires a secret and refuses to invent one', () => {
+    expect(() => planReceiverInstall({ secret: undefined, home: '/h' })).toThrow(/secret/i);
+    expect(() => planReceiverInstall({ secret: '', home: '/h' })).toThrow(/secret/i);
+  });
+
+  it('plans a user-scope unit that runs the receiver receiver-only by default', () => {
+    const plan = planReceiverInstall({
+      secret: SECRET,
+      home: '/home/op',
+      platform: 'linux',
+      celiloPath: FAKE_CELOLILO,
+    });
+    expect(plan.platform).toBe('linux');
+    expect(plan.scope).toBe('user');
+    expect(plan.unitContent).toContain('--no-dispatch');
+    expect(plan.unitContent).toContain(`CELILO_BUS_SECRET=${SECRET}`);
+  });
+
+  it('plans a system-scope unit with an explicit run-as user', () => {
+    const plan = planReceiverInstall({
+      secret: SECRET,
+      platform: 'linux',
+      scope: 'system',
+      home: '/root',
+      runAsUser: 'celilo',
+      celiloPath: FAKE_CELOLILO,
+    });
+    expect(plan.unitContent).toContain('User=celilo');
+  });
+
+  it('system scope falls back to the bus-dir owner when no run-as user is given', () => {
+    // events-daemon's resolveRunAsUser is the shared seam; here we only pin
+    // that the receiver unit passes a runAsUser through rather than dropping it.
+    const plan = planReceiverInstall({
+      secret: SECRET,
+      platform: 'linux',
+      scope: 'system',
+      home: '/root',
+      runAsUser: 'celilo',
+      celiloPath: FAKE_CELOLILO,
+    });
+    expect(plan.runAsUser).toBe('celilo');
+  });
+});
+
+describe('installReceiverDaemon / uninstallReceiverDaemon', () => {
+  const home = mkdtempSync(join(tmpdir(), 'celilo-receiver-daemon-'));
+
+  it('writes the unit file mode 0600 (it carries a secret) and idempotently rewrites', () => {
+    // celiloPath is passed explicitly: the unit under test must not
+    // consult the ambient PATH (resolveCeliloPath throws where no global
+    // celilo is installed — forge runners). Every planReceiverInstall test
+    // above injects FAKE_CELOLILO; the install path resolves the same way.
+    const first = installReceiverDaemon({
+      secret: SECRET,
+      platform: 'linux',
+      scope: 'user',
+      home,
+      celiloPath: FAKE_CELOLILO,
+    });
+    expect(existsSync(first.unitPath)).toBe(true);
+    expect(statSync(first.unitPath).mode & 0o777).toBe(0o600);
+    const content = readFileSync(first.unitPath, 'utf-8');
+    expect(content).toContain('--no-dispatch');
+    expect(content).toContain(`CELILO_BUS_SECRET=${SECRET}`);
+
+    // Idempotent second install.
+    const second = installReceiverDaemon({
+      secret: SECRET,
+      platform: 'linux',
+      scope: 'user',
+      home,
+      celiloPath: FAKE_CELOLILO,
+    });
+    expect(second.unitPath).toBe(first.unitPath);
+
+    const removed = uninstallReceiverDaemon({ platform: 'linux', scope: 'user', home });
+    expect(removed.removed).toBe(true);
+    expect(existsSync(first.unitPath)).toBe(false);
+  });
+
+  it('uninstall of a missing unit reports removed=false', () => {
+    const empty = mkdtempSync(join(tmpdir(), 'celilo-receiver-daemon-'));
+    const result = uninstallReceiverDaemon({ platform: 'linux', scope: 'user', home: empty });
+    expect(result.removed).toBe(false);
+    rmSync(empty, { recursive: true, force: true });
+  });
+});