@celilo/cli 0.3.30 → 0.4.0-alpha.1

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

@@ -0,0 +1,213 @@
+/**
+ * Delivery-history aggregator for `celilo subscribers status`
+ * ([[v2/BUILD_BUS.md]] Phase 6).
+ *
+ * Reads recent `webhook.delivered` + `webhook.failed` events from
+ * the local event bus, groups by subscriber URL, and produces a
+ * per-subscriber summary the CLI can render directly. Subscribers
+ * that exist in the static-config store but have no delivery
+ * history yet are still listed (with "no deliveries recorded").
+ *
+ * The aggregation function is pure — takes already-fetched event
+ * payloads + the subscriber config, returns the summary. The disk
+ * wrapper reads from the bus and delegates.
+ */
+
+import { defineEvents, openBus } from '@celilo/event-bus';
+import type { Subscriber } from '@celilo/event-bus/build-bus';
+import { getEventBusPath } from '../../config/paths';
+import {
+  WEBHOOK_DELIVERED_EVENT,
+  WEBHOOK_FAILED_EVENT,
+  type WebhookDeliveryPayload,
+} from './delivery-events';
+import { loadSubscribers } from './subscriber-store';
+
+const NO_SCHEMAS = defineEvents({});
+
+const DEFAULT_HISTORY_LIMIT = 100;
+
+/**
+ * Per-bus-event record the aggregator works with. Decoupled from
+ * BusEvent shape so the pure aggregator doesn't import bus types.
+ */
+export interface DeliveryRecord {
+  type: typeof WEBHOOK_DELIVERED_EVENT | typeof WEBHOOK_FAILED_EVENT;
+  emittedAt: number;
+  payload: WebhookDeliveryPayload;
+}
+
+export interface FailureSnapshot {
+  emittedAt: number;
+  eventId: string;
+  packageName: string;
+  packageVersion: string;
+  attempts: number;
+  /** Truncated to keep the status output readable. */
+  error: string;
+}
+
+export interface SubscriberStatus {
+  url: string;
+  label: string;
+  /** Configured match rule, for the operator to compare against actual deliveries. */
+  match: Subscriber['match'];
+  totals: { delivered: number; failed: number };
+  successRatePct: number | null; // null when no deliveries yet
+  /** Most recent delivery (success or failure) — undefined when none. */
+  lastDelivery?: {
+    emittedAt: number;
+    ok: boolean;
+    eventId: string;
+    packageName: string;
+    packageVersion: string;
+  };
+  /** Most recent N failures, newest first. Capped at 5. */
+  recentFailures: FailureSnapshot[];
+}
+
+const RECENT_FAILURES_LIMIT = 5;
+const ERROR_TRUNCATE = 200;
+
+/**
+ * Pure: combine the subscriber config with the bus's delivery
+ * history into a per-subscriber status list. The returned array is
+ * ordered the same way the subscriber config is (no implicit
+ * sorting — operator sees them in the order they were added).
+ */
+export function aggregateSubscriberStatus(
+  subscribers: Subscriber[],
+  records: DeliveryRecord[],
+): SubscriberStatus[] {
+  // Group records by subscriber URL. Each subscriber gets its own
+  // chronologically-sorted-newest-first array.
+  const byUrl = new Map<string, DeliveryRecord[]>();
+  for (const r of records) {
+    const list = byUrl.get(r.payload.subscriberUrl) ?? [];
+    list.push(r);
+    byUrl.set(r.payload.subscriberUrl, list);
+  }
+  for (const list of byUrl.values()) {
+    list.sort((a, b) => b.emittedAt - a.emittedAt);
+  }
+
+  return subscribers.map((sub) => {
+    const records = byUrl.get(sub.url) ?? [];
+    const delivered = records.filter((r) => r.type === WEBHOOK_DELIVERED_EVENT).length;
+    const failed = records.filter((r) => r.type === WEBHOOK_FAILED_EVENT).length;
+    const total = delivered + failed;
+    const successRatePct = total === 0 ? null : Math.round((delivered / total) * 100);
+    const lastRecord = records[0];
+    const recentFailures: FailureSnapshot[] = records
+      .filter((r) => r.type === WEBHOOK_FAILED_EVENT)
+      .slice(0, RECENT_FAILURES_LIMIT)
+      .map((r) => ({
+        emittedAt: r.emittedAt,
+        eventId: r.payload.eventId,
+        packageName: r.payload.packageName,
+        packageVersion: r.payload.packageVersion,
+        attempts: r.payload.attempts,
+        error: (r.payload.error ?? '<no error message>').slice(0, ERROR_TRUNCATE),
+      }));
+
+    return {
+      url: sub.url,
+      label: sub.name ?? sub.url,
+      match: sub.match,
+      totals: { delivered, failed },
+      successRatePct,
+      lastDelivery: lastRecord
+        ? {
+            emittedAt: lastRecord.emittedAt,
+            ok: lastRecord.type === WEBHOOK_DELIVERED_EVENT,
+            eventId: lastRecord.payload.eventId,
+            packageName: lastRecord.payload.packageName,
+            packageVersion: lastRecord.payload.packageVersion,
+          }
+        : undefined,
+      recentFailures,
+    };
+  });
+}
+
+/**
+ * Disk wrapper: read recent delivery events from the bus, then
+ * delegate to the pure aggregator.
+ */
+export function loadSubscriberStatus(opts: { limit?: number } = {}): SubscriberStatus[] {
+  const subscribers = loadSubscribers();
+  if (subscribers.length === 0) return [];
+
+  const limit = opts.limit ?? DEFAULT_HISTORY_LIMIT;
+  const bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+  let records: DeliveryRecord[];
+  try {
+    const delivered = bus.recentEvents({ type: WEBHOOK_DELIVERED_EVENT, limit });
+    const failed = bus.recentEvents({ type: WEBHOOK_FAILED_EVENT, limit });
+    records = [...delivered, ...failed].map((e) => ({
+      type: e.type as DeliveryRecord['type'],
+      emittedAt: e.emittedAt,
+      payload: e.payload as WebhookDeliveryPayload,
+    }));
+  } finally {
+    bus.close();
+  }
+
+  return aggregateSubscriberStatus(subscribers, records);
+}
+
+/**
+ * Render a SubscriberStatus list as multi-line text for the CLI.
+ * Pure — operates on the data the aggregator produces.
+ */
+export function formatStatus(items: SubscriberStatus[], now: number = Date.now()): string {
+  if (items.length === 0) {
+    return 'No subscribers configured.';
+  }
+  const lines: string[] = [];
+  for (const s of items) {
+    lines.push(`  ${s.label}`);
+    lines.push(`    url: ${s.url}`);
+    const matchParts: string[] = [];
+    if (s.match.registry) matchParts.push(`registry=${s.match.registry}`);
+    if (s.match.tag) matchParts.push(`tag=${s.match.tag}`);
+    if (s.match.packagePattern) matchParts.push(`pkg=${s.match.packagePattern}`);
+    lines.push(`    match: ${matchParts.length > 0 ? matchParts.join(', ') : '(any event)'}`);
+    if (s.successRatePct === null) {
+      lines.push('    deliveries: none yet');
+    } else {
+      lines.push(
+        `    deliveries: ${s.totals.delivered}/${s.totals.delivered + s.totals.failed} ok (${s.successRatePct}%)`,
+      );
+    }
+    if (s.lastDelivery) {
+      const ago = describeAgo(now - s.lastDelivery.emittedAt);
+      const marker = s.lastDelivery.ok ? '✓' : '✗';
+      lines.push(
+        `    last delivery: ${marker} ${s.lastDelivery.packageName}@${s.lastDelivery.packageVersion} (${ago})`,
+      );
+    }
+    if (s.recentFailures.length > 0) {
+      lines.push(`    recent failures (${s.recentFailures.length}):`);
+      for (const f of s.recentFailures) {
+        lines.push(
+          `      ${describeAgo(now - f.emittedAt)} — ${f.packageName}@${f.packageVersion}: ${f.error}`,
+        );
+      }
+    }
+    lines.push('');
+  }
+  return lines.join('\n').trimEnd();
+}
+
+/**
+ * Render a millisecond delta as a human-readable "Xm ago" /
+ * "Xh ago" / "Xd ago". Pure.
+ */
+export function describeAgo(deltaMs: number): string {
+  if (deltaMs < 0) return 'in the future';
+  if (deltaMs < 60_000) return `${Math.floor(deltaMs / 1000)}s ago`;
+  if (deltaMs < 60 * 60_000) return `${Math.floor(deltaMs / 60_000)}m ago`;
+  if (deltaMs < 24 * 60 * 60_000) return `${Math.floor(deltaMs / (60 * 60_000))}h ago`;
+  return `${Math.floor(deltaMs / (24 * 60 * 60_000))}d ago`;
+}

package/src/services/build-bus/subscriber-store.ts

@@ -0,0 +1,113 @@
+/**
+ * Static-config subscriber store for the build bus
+ * ([[v2/BUILD_BUS.md]] Phase 2-lite).
+ *
+ * The first cut of cross-machine event distribution skips the
+ * registry-server switchboard described in §6 of the spec — instead
+ * the operator maintains a JSON file under their celilo data dir
+ * that lists each subscriber URL + secret + match rule. This file
+ * is the single source of truth for publishes that originate on
+ * this machine.
+ *
+ * File layout (default `~/Library/Application Support/celilo/build-bus-subscribers.json`
+ * on macOS, similar XDG path on Linux — see config/paths.ts):
+ *
+ *   {
+ *     "subscribers": [
+ *       {
+ *         "name": "lunacycle build box",
+ *         "url": "https://lunacycle.lab/build-bus",
+ *         "secret": "<hmac-secret>",
+ *         "match": { "registry": "npm", "packagePattern": "@celilo/*" }
+ *       }
+ *     ]
+ *   }
+ *
+ * Override the file path with the CELILO_BUILD_BUS_SUBSCRIBERS_PATH
+ * env var (used by integration tests).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { Subscriber } from '@celilo/event-bus/build-bus';
+import { getDataDir } from '../../config/paths';
+
+const FILE_NAME = 'build-bus-subscribers.json';
+
+interface StoreFile {
+  subscribers: Subscriber[];
+}
+
+/**
+ * Resolve the subscriber-store path. Respects
+ * CELILO_BUILD_BUS_SUBSCRIBERS_PATH for testability; otherwise
+ * lives alongside the rest of celilo's per-machine state under
+ * getDataDir().
+ */
+export function subscriberStorePath(): string {
+  return process.env.CELILO_BUILD_BUS_SUBSCRIBERS_PATH ?? join(getDataDir(), FILE_NAME);
+}
+
+/**
+ * Load the subscriber list. Missing file → empty list (treat as
+ * "no subscribers configured"; this is the silent-no-op path that
+ * keeps the build-bus opt-in). Malformed JSON throws so the operator
+ * notices.
+ */
+export function loadSubscribers(): Subscriber[] {
+  const path = subscriberStorePath();
+  if (!existsSync(path)) return [];
+  const content = readFileSync(path, 'utf-8');
+  let parsed: StoreFile;
+  try {
+    parsed = JSON.parse(content) as StoreFile;
+  } catch (err) {
+    throw new Error(`Could not parse ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!Array.isArray(parsed.subscribers)) {
+    throw new Error(`${path} has no "subscribers" array at the top level.`);
+  }
+  return parsed.subscribers;
+}
+
+/**
+ * Replace the subscriber list. Creates the parent dir if needed,
+ * writes atomically (temp file + rename) so a failed write doesn't
+ * leave a corrupt store.
+ */
+export function saveSubscribers(subscribers: Subscriber[]): void {
+  const path = subscriberStorePath();
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify({ subscribers }, null, 2)}\n`);
+  // Bun supports rename via the standard Node fs API; this fails fast
+  // on EXDEV but the temp + path live in the same dir so cross-FS
+  // isn't a concern.
+  const { renameSync } = require('node:fs') as typeof import('node:fs');
+  renameSync(tmp, path);
+}
+
+/**
+ * Add a subscriber. If one with the same URL exists, replace it
+ * (idempotent re-adds with updated secret/match are common when an
+ * operator rotates credentials). Returns the prior subscriber, if any.
+ */
+export function addSubscriber(subscriber: Subscriber): { replaced?: Subscriber } {
+  const existing = loadSubscribers();
+  const prior = existing.find((s) => s.url === subscriber.url);
+  const next = existing.filter((s) => s.url !== subscriber.url);
+  next.push(subscriber);
+  saveSubscribers(next);
+  return prior ? { replaced: prior } : {};
+}
+
+/**
+ * Remove a subscriber by URL. Returns the removed entry, if any.
+ */
+export function removeSubscriberByUrl(url: string): Subscriber | undefined {
+  const existing = loadSubscribers();
+  const prior = existing.find((s) => s.url === url);
+  if (!prior) return undefined;
+  saveSubscribers(existing.filter((s) => s.url !== url));
+  return prior;
+}

package/src/services/celilo-events.test.ts

@@ -8,6 +8,11 @@ import {
   emitDeployFailed,
   emitDeployStarted,
   emitHealthCheckFailed,
+  emitSystemCreated,
+  emitSystemDestroyed,
+  emitUninstallCompleted,
+  emitUninstallFailed,
+  emitUninstallStarted,
 } from './celilo-events';
 
 describe('celilo lifecycle events', () => {
@@ -70,6 +75,71 @@ describe('celilo lifecycle events', () => {
     expect(events[0].type).toBe('health-check.failed.lunacycle');
   });
 
+  it('emits uninstall.started.<module>', () => {
+    emitUninstallStarted({ module: 'caddy', startedAt: 2000 });
+    const events = recentEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe('uninstall.started.caddy');
+    expect(events[0].payload).toEqual({ module: 'caddy', startedAt: 2000 });
+  });
+
+  it('emits uninstall.completed.<module> with duration', () => {
+    emitUninstallCompleted({ module: 'caddy', startedAt: 2000, durationMs: 1500 });
+    const events = recentEvents();
+    expect(events[0].type).toBe('uninstall.completed.caddy');
+    expect((events[0].payload as { durationMs: number }).durationMs).toBe(1500);
+  });
+
+  it('emits uninstall.failed.<module> with error', () => {
+    emitUninstallFailed({
+      module: 'caddy',
+      startedAt: 2000,
+      durationMs: 300,
+      error: 'terraform destroy failed',
+    });
+    const events = recentEvents();
+    expect(events[0].type).toBe('uninstall.failed.caddy');
+    expect((events[0].payload as { error: string }).error).toBe('terraform destroy failed');
+  });
+
+  it('emits system.created.<module> with host identity', () => {
+    emitSystemCreated({ module: 'technitium', hostname: 'dns-int', targetIp: '192.168.0.53' });
+    const events = recentEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe('system.created.technitium');
+    expect(events[0].payload).toEqual({
+      module: 'technitium',
+      hostname: 'dns-int',
+      targetIp: '192.168.0.53',
+    });
+  });
+
+  it('emits system.destroyed.<module> with host identity', () => {
+    emitSystemDestroyed({ module: 'caddy', hostname: 'www', targetIp: '10.0.10.10' });
+    const events = recentEvents();
+    expect(events[0].type).toBe('system.destroyed.caddy');
+    expect((events[0].payload as { hostname: string }).hostname).toBe('www');
+  });
+
+  it('system.created.* subscriber receives a delivery (the D5 fan-out path)', () => {
+    const setupBus = openBus({ dbPath, events: defineEvents({}) });
+    setupBus.subscribe({
+      name: 'dns-internal.auto-register',
+      pattern: 'system.created.*',
+      handler: 'unused',
+    });
+    setupBus.close();
+
+    emitSystemCreated({ module: 'lunacycle', hostname: 'lunacycle', targetIp: '10.0.20.11' });
+
+    const bus = openBus({ dbPath, events: defineEvents({}) });
+    try {
+      expect(bus.pendingDeliveries()).toHaveLength(1);
+    } finally {
+      bus.close();
+    }
+  });
+
   it('triggers persistent subscribers and creates deliveries', () => {
     // Pre-register a subscriber that targets all completed deploys.
     const setupBus = openBus({ dbPath, events: defineEvents({}) });

package/src/services/celilo-events.ts

@@ -41,6 +41,42 @@ export interface HealthCheckFailedPayload {
   reason: string;
 }
 
+export interface UninstallStartedPayload {
+  module: string;
+  startedAt: number;
+}
+
+export interface UninstallCompletedPayload {
+  module: string;
+  startedAt: number;
+  durationMs: number;
+}
+
+export interface UninstallFailedPayload {
+  module: string;
+  startedAt: number;
+  durationMs: number;
+  error: string;
+}
+
+/**
+ * A deployed system (a machine or container-service instance hosting a
+ * module) has come up / been torn down. Carries the system's identity so a
+ * subscriber (e.g. a dns_internal provider) can register/deregister internal
+ * DNS records without re-querying the deploying module's config.
+ * v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md D5.
+ */
+export interface SystemCreatedPayload {
+  /** The module whose deploy produced this system (lets handlers resolve zones, etc.). */
+  module: string;
+  /** Bare hostname (e.g. "dns-int"), no domain. */
+  hostname: string;
+  /** IPv4 address, CIDR stripped (e.g. "192.168.0.53"). */
+  targetIp: string;
+}
+
+export type SystemDestroyedPayload = SystemCreatedPayload;
+
 const DeployStartedSchema = z.object({
   module: z.string().min(1),
   startedAt: z.number().int().nonnegative(),
@@ -64,6 +100,32 @@ const HealthCheckFailedSchema = z.object({
   reason: z.string(),
 });
 
+const UninstallStartedSchema = z.object({
+  module: z.string().min(1),
+  startedAt: z.number().int().nonnegative(),
+});
+
+const UninstallCompletedSchema = z.object({
+  module: z.string().min(1),
+  startedAt: z.number().int().nonnegative(),
+  durationMs: z.number().int().nonnegative(),
+});
+
+const UninstallFailedSchema = z.object({
+  module: z.string().min(1),
+  startedAt: z.number().int().nonnegative(),
+  durationMs: z.number().int().nonnegative(),
+  error: z.string(),
+});
+
+const SystemCreatedSchema = z.object({
+  module: z.string().min(1),
+  hostname: z.string().min(1),
+  targetIp: z.string().min(1),
+});
+
+const SystemDestroyedSchema = SystemCreatedSchema;
+
 export function emitDeployStarted(payload: DeployStartedPayload): void {
   DeployStartedSchema.parse(payload);
   emitBest(`deploy.started.${payload.module}`, payload);
@@ -84,6 +146,36 @@ export function emitHealthCheckFailed(payload: HealthCheckFailedPayload): void {
   emitBest(`health-check.failed.${payload.module}`, payload);
 }
 
+export function emitUninstallStarted(payload: UninstallStartedPayload): void {
+  UninstallStartedSchema.parse(payload);
+  emitBest(`uninstall.started.${payload.module}`, payload);
+}
+
+export function emitUninstallCompleted(payload: UninstallCompletedPayload): void {
+  UninstallCompletedSchema.parse(payload);
+  emitBest(`uninstall.completed.${payload.module}`, payload);
+}
+
+export function emitUninstallFailed(payload: UninstallFailedPayload): void {
+  UninstallFailedSchema.parse(payload);
+  emitBest(`uninstall.failed.${payload.module}`, payload);
+}
+
+/**
+ * Emit `system.created.<module>` (D5). Last segment is the module id so
+ * subscribers can fan out (`system.created.*`) or target one.
+ */
+export function emitSystemCreated(payload: SystemCreatedPayload): void {
+  SystemCreatedSchema.parse(payload);
+  emitBest(`system.created.${payload.module}`, payload);
+}
+
+/** Emit `system.destroyed.<module>` (D5). */
+export function emitSystemDestroyed(payload: SystemDestroyedPayload): void {
+  SystemDestroyedSchema.parse(payload);
+  emitBest(`system.destroyed.${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