@celilo/cli 0.3.30 → 0.4.0-alpha.1

package/src/services/build-bus/hook-dispatch.test.ts

@@ -0,0 +1,207 @@
+/**
+ * Hook-dispatch tests. The planner is pure (no I/O); the runner
+ * spawns bash. We test:
+ *
+ *   - planHookDispatch: rule matching, env construction, scriptPath
+ *     resolution.
+ *   - runHookDispatch: real bash spawn with a fixture script.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { PublishEvent } from '@celilo/event-bus/build-bus';
+import { type ModuleHookContext, planHookDispatch, runHookDispatch } from './hook-dispatch';
+
+function buildEvent(overrides: Partial<PublishEvent> = {}): PublishEvent {
+  return {
+    eventId: 'evt-1',
+    timestamp: new Date().toISOString(),
+    registry: 'npm',
+    tag: 'latest',
+    package: { name: '@celilo/cli', version: '0.4.0' },
+    ...overrides,
+  };
+}
+
+describe('planHookDispatch', () => {
+  test('empty module list → empty plan', () => {
+    expect(planHookDispatch(buildEvent(), [])).toEqual([]);
+  });
+
+  test('module with no matching hooks → empty plan', () => {
+    const modules: ModuleHookContext[] = [
+      {
+        moduleId: 'lunacycle',
+        sourcePath: '/modules/lunacycle',
+        hooks: [{ match: { registry: 'celilo-registry' }, script: './reload.sh' }],
+      },
+    ];
+    expect(planHookDispatch(buildEvent({ registry: 'npm' }), modules)).toEqual([]);
+  });
+
+  test('matching hook → plan with resolved scriptPath + env', () => {
+    const modules: ModuleHookContext[] = [
+      {
+        moduleId: 'lunacycle',
+        sourcePath: '/modules/lunacycle',
+        hooks: [
+          {
+            name: 'rerun-e2e',
+            match: { registry: 'npm', package_pattern: '@celilo/*' },
+            script: './hooks/rerun.sh',
+          },
+        ],
+      },
+    ];
+    const plan = planHookDispatch(buildEvent(), modules);
+    expect(plan).toHaveLength(1);
+    expect(plan[0].scriptPath).toBe('/modules/lunacycle/hooks/rerun.sh');
+    expect(plan[0].env.CELILO_EVENT_REGISTRY).toBe('npm');
+    expect(plan[0].env.CELILO_EVENT_TAG).toBe('latest');
+    expect(plan[0].env.CELILO_EVENT_PACKAGE_NAME).toBe('@celilo/cli');
+    expect(plan[0].env.CELILO_EVENT_PACKAGE_VERSION).toBe('0.4.0');
+    const payload = JSON.parse(plan[0].env.CELILO_EVENT_PAYLOAD) as PublishEvent;
+    expect(payload.package.name).toBe('@celilo/cli');
+  });
+
+  test('multiple modules + hooks → one plan entry per match', () => {
+    const modules: ModuleHookContext[] = [
+      {
+        moduleId: 'lunacycle',
+        sourcePath: '/modules/lunacycle',
+        hooks: [
+          { match: { registry: 'npm', package_pattern: '@celilo/cli' }, script: './a.sh' },
+          { match: { registry: 'npm', package_pattern: '@celilo/e2e' }, script: './b.sh' },
+        ],
+      },
+      {
+        moduleId: 'mgmt',
+        sourcePath: '/modules/mgmt',
+        hooks: [{ match: { registry: 'celilo-registry' }, script: './c.sh' }],
+      },
+    ];
+    const plan = planHookDispatch(
+      buildEvent({ package: { name: '@celilo/cli', version: '0.4.0' } }),
+      modules,
+    );
+    expect(plan).toHaveLength(1);
+    expect(plan[0].module.moduleId).toBe('lunacycle');
+    expect(plan[0].hook.script).toBe('./a.sh');
+  });
+
+  test('snake_case package_pattern in manifest maps to camelCase packagePattern in matcher', () => {
+    // Documents the YAML↔JS naming bridge.
+    const modules: ModuleHookContext[] = [
+      {
+        moduleId: 'x',
+        sourcePath: '/m',
+        hooks: [{ match: { package_pattern: '@celilo/*' }, script: './h.sh' }],
+      },
+    ];
+    expect(planHookDispatch(buildEvent(), modules)).toHaveLength(1);
+    expect(
+      planHookDispatch(buildEvent({ package: { name: '@other/x', version: '1.0.0' } }), modules),
+    ).toHaveLength(0);
+  });
+});
+
+describe('runHookDispatch', () => {
+  let scriptDir: string;
+
+  beforeEach(() => {
+    scriptDir = mkdtempSync(join(tmpdir(), 'celilo-hook-dispatch-'));
+  });
+
+  afterEach(() => {
+    rmSync(scriptDir, { recursive: true, force: true });
+  });
+
+  function writeScript(name: string, body: string): string {
+    const path = join(scriptDir, name);
+    writeFileSync(path, body);
+    chmodSync(path, 0o755);
+    return path;
+  }
+
+  test('runs a script and captures exit 0 + stdout', async () => {
+    const scriptPath = writeScript(
+      'h.sh',
+      '#!/bin/bash\necho "hello $CELILO_EVENT_PACKAGE_NAME"\n',
+    );
+    const result = await runHookDispatch({
+      module: { moduleId: 'm', sourcePath: scriptDir, hooks: [] },
+      hook: { match: {}, script: 'h.sh' },
+      scriptPath,
+      env: {
+        CELILO_EVENT_PAYLOAD: '{}',
+        CELILO_EVENT_REGISTRY: 'npm',
+        CELILO_EVENT_TAG: 'latest',
+        CELILO_EVENT_PACKAGE_NAME: '@celilo/cli',
+        CELILO_EVENT_PACKAGE_VERSION: '0.4.0',
+      },
+    });
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toBe('hello @celilo/cli');
+    expect(result.timedOut).toBe(false);
+  });
+
+  test('captures non-zero exit + stderr', async () => {
+    const scriptPath = writeScript('fail.sh', '#!/bin/bash\necho "boom" >&2\nexit 17\n');
+    const result = await runHookDispatch({
+      module: { moduleId: 'm', sourcePath: scriptDir, hooks: [] },
+      hook: { match: {}, script: 'fail.sh' },
+      scriptPath,
+      env: {
+        CELILO_EVENT_PAYLOAD: '{}',
+        CELILO_EVENT_REGISTRY: 'npm',
+        CELILO_EVENT_TAG: 'latest',
+        CELILO_EVENT_PACKAGE_NAME: '@celilo/cli',
+        CELILO_EVENT_PACKAGE_VERSION: '0.4.0',
+      },
+    });
+    expect(result.exitCode).toBe(17);
+    expect(result.stderr.trim()).toBe('boom');
+  });
+
+  test('respects timeout (kills the script and reports timedOut=true)', async () => {
+    const scriptPath = writeScript('slow.sh', '#!/bin/bash\nsleep 5\n');
+    const result = await runHookDispatch({
+      module: { moduleId: 'm', sourcePath: scriptDir, hooks: [] },
+      hook: { match: {}, script: 'slow.sh', timeout: 1 },
+      scriptPath,
+      env: {
+        CELILO_EVENT_PAYLOAD: '{}',
+        CELILO_EVENT_REGISTRY: 'npm',
+        CELILO_EVENT_TAG: 'latest',
+        CELILO_EVENT_PACKAGE_NAME: '@celilo/cli',
+        CELILO_EVENT_PACKAGE_VERSION: '0.4.0',
+      },
+    });
+    expect(result.timedOut).toBe(true);
+    // SIGTERM + 500ms grace → SIGKILL means the inner `sleep` should
+    // be reaped within ~2s of the 1-second timeout firing. Give a
+    // generous 4s ceiling so we're not flaky on slow CI hosts.
+    expect(result.durationMs).toBeLessThan(4000);
+  }, 10000);
+
+  test('records spawn error when the script does not exist', async () => {
+    const result = await runHookDispatch({
+      module: { moduleId: 'm', sourcePath: scriptDir, hooks: [] },
+      hook: { match: {}, script: 'does-not-exist.sh' },
+      scriptPath: join(scriptDir, 'does-not-exist.sh'),
+      env: {
+        CELILO_EVENT_PAYLOAD: '{}',
+        CELILO_EVENT_REGISTRY: 'npm',
+        CELILO_EVENT_TAG: 'latest',
+        CELILO_EVENT_PACKAGE_NAME: '@celilo/cli',
+        CELILO_EVENT_PACKAGE_VERSION: '0.4.0',
+      },
+    });
+    // bash exits with non-zero when the script file doesn't exist
+    // (status 127). Either non-zero exit or a null/spawn-error is
+    // acceptable here; we just want NOT-success.
+    expect(result.exitCode === 0).toBe(false);
+  });
+});

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

@@ -0,0 +1,198 @@
+/**
+ * Hook-dispatch planning + execution for the build bus
+ * ([[v2/BUILD_BUS.md]] Phase 4).
+ *
+ * Pure: planHookDispatch(event, modules) → HookDispatchPlan[].
+ * Decides which module hooks match the event without spawning
+ * anything; the executor (runHookDispatch) takes a plan and
+ * spawns the actual scripts.
+ *
+ * The hook script gets the event in its environment:
+ *   CELILO_EVENT_PAYLOAD          — full PublishEvent as JSON
+ *   CELILO_EVENT_REGISTRY         — convenience (also in payload)
+ *   CELILO_EVENT_TAG              — convenience
+ *   CELILO_EVENT_PACKAGE_NAME     — convenience
+ *   CELILO_EVENT_PACKAGE_VERSION  — convenience
+ *
+ * Non-zero exit is logged but doesn't gate the receiver — failures
+ * are operational signal for the operator, not a publish blocker.
+ */
+
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { type PublishEvent, matchesRule } from '@celilo/event-bus/build-bus';
+
+/** Mirrors UpstreamPublishHookSchema in the manifest schema. */
+export interface UpstreamHookEntry {
+  name?: string;
+  match: { registry?: string; tag?: string; package_pattern?: string };
+  script: string;
+  timeout?: number;
+}
+
+/**
+ * What the dispatcher knows about a single installed module that
+ * declares on_upstream_publish hooks. Built by the dispatcher's
+ * loader (which reads the celilo modules table + each module's
+ * manifest.yml); injected as a list into planHookDispatch.
+ */
+export interface ModuleHookContext {
+  moduleId: string;
+  sourcePath: string;
+  hooks: UpstreamHookEntry[];
+}
+
+export interface HookDispatchPlan {
+  module: ModuleHookContext;
+  hook: UpstreamHookEntry;
+  /** Absolute path the executor will spawn. */
+  scriptPath: string;
+  /** Env vars to pass to the script. */
+  env: Record<string, string>;
+}
+
+/**
+ * Pure: walk every (module, hook) combination, keep the ones whose
+ * match rule fires for this event. Same world → same plan; injects
+ * nothing.
+ *
+ * The manifest's match uses snake_case (`package_pattern`) to match
+ * YAML conventions, but the @celilo/event-bus/build-bus matcher
+ * uses camelCase (`packagePattern`). Bridge that here so the
+ * manifest stays YAML-idiomatic and the typed-API stays JS-idiomatic.
+ */
+export function planHookDispatch(
+  event: PublishEvent,
+  modules: ModuleHookContext[],
+): HookDispatchPlan[] {
+  const plans: HookDispatchPlan[] = [];
+  const env = buildHookEnv(event);
+  for (const module of modules) {
+    for (const hook of module.hooks) {
+      const rule = {
+        registry: hook.match.registry,
+        tag: hook.match.tag,
+        packagePattern: hook.match.package_pattern,
+      };
+      if (!matchesRule(event, rule)) continue;
+      plans.push({
+        module,
+        hook,
+        scriptPath: join(module.sourcePath, hook.script),
+        env,
+      });
+    }
+  }
+  return plans;
+}
+
+function buildHookEnv(event: PublishEvent): Record<string, string> {
+  return {
+    CELILO_EVENT_PAYLOAD: JSON.stringify(event),
+    CELILO_EVENT_REGISTRY: event.registry,
+    CELILO_EVENT_TAG: event.tag,
+    CELILO_EVENT_PACKAGE_NAME: event.package.name,
+    CELILO_EVENT_PACKAGE_VERSION: event.package.version,
+  };
+}
+
+const DEFAULT_TIMEOUT_SEC = 600;
+
+export interface HookRunResult {
+  module: string;
+  hookName: string;
+  scriptPath: string;
+  exitCode: number | null;
+  durationMs: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+
+/**
+ * Run one plan entry. Spawns `bash -c <scriptPath>` so shell features
+ * (pipe, redirect, env-var expansion) work inside the hook. Captures
+ * stdout/stderr for the operator log; kills the process on timeout.
+ *
+ * Doesn't throw — the result carries the outcome. Caller (dispatcher)
+ * logs failures and keeps going to the next plan entry.
+ */
+export async function runHookDispatch(plan: HookDispatchPlan): Promise<HookRunResult> {
+  const timeoutSec = plan.hook.timeout ?? DEFAULT_TIMEOUT_SEC;
+  const hookName = plan.hook.name ?? plan.hook.script;
+  const startedAt = Date.now();
+
+  return new Promise((resolve) => {
+    // `detached: true` puts bash + its children in their own
+    // process group so the timeout can kill the whole subtree (not
+    // just the bash parent, which would otherwise leave a `sleep`
+    // running). `process.kill(-pid, …)` signals the group.
+    const child = spawn('bash', [plan.scriptPath], {
+      env: { ...process.env, ...plan.env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: true,
+    });
+    const pgid = child.pid; // process group leader == its own PID
+
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    let killTimer: ReturnType<typeof setTimeout> | undefined;
+    const killGroup = (signal: NodeJS.Signals) => {
+      if (pgid == null) return;
+      try {
+        process.kill(-pgid, signal);
+      } catch {
+        // Group already gone — fall back to direct child signal.
+        try {
+          child.kill(signal);
+        } catch {
+          // ignore
+        }
+      }
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killGroup('SIGTERM');
+      // SIGTERM may not be honored by long-running children
+      // (`sleep`, network waits). Follow up with SIGKILL after a
+      // brief grace period.
+      killTimer = setTimeout(() => killGroup('SIGKILL'), 200);
+    }, timeoutSec * 1000);
+
+    child.stdout?.on('data', (chunk: Buffer) => {
+      stdout += chunk.toString('utf-8');
+    });
+    child.stderr?.on('data', (chunk: Buffer) => {
+      stderr += chunk.toString('utf-8');
+    });
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      resolve({
+        module: plan.module.moduleId,
+        hookName,
+        scriptPath: plan.scriptPath,
+        exitCode: null,
+        durationMs: Date.now() - startedAt,
+        stdout,
+        stderr: `${stderr}\nspawn error: ${err.message}`,
+        timedOut: false,
+      });
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      resolve({
+        module: plan.module.moduleId,
+        hookName,
+        scriptPath: plan.scriptPath,
+        exitCode: code,
+        durationMs: Date.now() - startedAt,
+        stdout,
+        stderr,
+        timedOut,
+      });
+    });
+  });
+}

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

@@ -0,0 +1,115 @@
+/**
+ * Build-bus hook dispatcher service.
+ *
+ * Stateful wrapper around `planHookDispatch` + `runHookDispatch`:
+ * loads installed-module manifests from the celilo DB, dispatches
+ * matching `on_upstream_publish` hooks when a verified PublishEvent
+ * arrives, logs outcomes.
+ *
+ * Started by the `celilo subscribers serve` daemon (in-process,
+ * sharing the same lifetime); the receiver-server calls
+ * `dispatcher.handleEvent(event)` on every verified webhook.
+ *
+ * Module loading is injectable so tests can drive the dispatcher
+ * with synthetic ModuleHookContext lists. Production loads from the
+ * DB + filesystem (manifest.yml under each module's source_path).
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { PublishEvent } from '@celilo/event-bus/build-bus';
+import { parse as parseYaml } from 'yaml';
+import { getDb } from '../../db/client';
+import { modules } from '../../db/schema';
+import {
+  type HookRunResult,
+  type ModuleHookContext,
+  type UpstreamHookEntry,
+  planHookDispatch,
+  runHookDispatch,
+} from './hook-dispatch';
+
+export interface HookDispatcher {
+  /** Run the matching hooks for a single event. Returns the per-hook results. */
+  handleEvent(event: PublishEvent): Promise<HookRunResult[]>;
+  /** Clean up (currently a no-op; included for symmetry with the receiver). */
+  stop(): Promise<void>;
+}
+
+export interface HookDispatcherOptions {
+  /**
+   * Override the module-loading step. Tests inject a fixture; in
+   * production we omit and the dispatcher reads from the celilo
+   * modules table.
+   */
+  loadModules?: () => ModuleHookContext[];
+}
+
+export async function startHookDispatcher(
+  opts: HookDispatcherOptions = {},
+): Promise<HookDispatcher> {
+  const loadModules = opts.loadModules ?? loadInstalledModulesWithHooks;
+
+  return {
+    async handleEvent(event) {
+      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`,
+        );
+        return [];
+      }
+      const results: HookRunResult[] = [];
+      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);
+        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`);
+        } else {
+          console.warn(`  ✗ exit ${result.exitCode} in ${result.durationMs}ms`);
+          if (result.stderr) console.warn(`    stderr: ${result.stderr.trim().slice(0, 500)}`);
+        }
+      }
+      return results;
+    },
+    async stop() {
+      // No long-running connections to clean up — modules are
+      // re-loaded per event so we can hot-pick up new installs.
+    },
+  };
+}
+
+/**
+ * Load every installed module's `on_upstream_publish` hooks from the
+ * celilo DB + each module's manifest.yml. Modules without the hook
+ * type are filtered out. Modules whose manifest fails to parse are
+ * silently skipped — the operator sees this when they next run
+ * `celilo module check`.
+ */
+function loadInstalledModulesWithHooks(): ModuleHookContext[] {
+  const db = getDb();
+  const rows = db.select({ id: modules.id, sourcePath: modules.sourcePath }).from(modules).all();
+  const out: ModuleHookContext[] = [];
+  for (const row of rows) {
+    if (!row.sourcePath) continue;
+    try {
+      const parsed = parseYaml(readFileSync(join(row.sourcePath, 'manifest.yml'), 'utf-8')) as {
+        hooks?: { on_upstream_publish?: UpstreamHookEntry[] };
+      };
+      const hooks = parsed.hooks?.on_upstream_publish ?? [];
+      if (hooks.length === 0) continue;
+      out.push({ moduleId: row.id, sourcePath: row.sourcePath, hooks });
+    } catch {
+      // Skip modules whose manifests can't be loaded — log when this
+      // turns out to be a real problem rather than during routine
+      // event dispatch.
+    }
+  }
+  return out;
+}

package/src/services/build-bus/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Build-bus service surface for the celilo app.
+ *
+ * `@celilo/event-bus/build-bus` carries the wire types + crypto;
+ * this layer adds the operator-side concerns:
+ *
+ *   - subscriber-store: read/write the static-config subscriber
+ *     list under getDataDir()
+ *   - fan-out: signed HTTP delivery with retry
+ *   - event-factory: build PublishEvents from the publish flow's
+ *     output
+ */
+
+export {
+  subscriberStorePath,
+  loadSubscribers,
+  saveSubscribers,
+  addSubscriber,
+  removeSubscriberByUrl,
+} from './subscriber-store';
+
+export { fanOut, formatDeliveryResult } from './fan-out';
+export type { FanOutOptions } from './fan-out';
+
+export { eventsForPublished } from './event-factory';
+export type { EventFactoryInput, PublishedItem } from './event-factory';
+
+export {
+  recordDeliveryOutcome,
+  WEBHOOK_DELIVERED_EVENT,
+  WEBHOOK_FAILED_EVENT,
+} from './delivery-events';
+export type { WebhookDeliveryPayload } from './delivery-events';
+
+export {
+  aggregateSubscriberStatus,
+  describeAgo,
+  formatStatus,
+  loadSubscriberStatus,
+} from './status';
+export type { DeliveryRecord, FailureSnapshot, SubscriberStatus } from './status';