@celilo/cli 0.2.0 → 0.3.0

package/src/services/celilo-events.ts

@@ -0,0 +1,104 @@
+/**
+ * Celilo's own lifecycle events. Emitted on every `module deploy`
+ * (started / completed / failed) so subscribers can react — production
+ * smoke tests, alerting, dashboards, etc.
+ *
+ * The event types are dot-segmented with the module id as the last
+ * segment: `deploy.started.lunacycle`, `deploy.completed.lunacycle`.
+ * This lets subscribers target one module (`deploy.completed.lunacycle`)
+ * or fan out (`deploy.completed.*`).
+ *
+ * Bus errors are best-effort: a sick bus shouldn't break a deploy. Each
+ * helper opens-emits-closes; per-event overhead is a few ms.
+ */
+
+import { defineEvents, openBus } from '@celilo/event-bus';
+import { z } from 'zod';
+import { getEventBusPath } from '../config/paths';
+
+const NO_SCHEMAS = defineEvents({});
+
+export interface DeployStartedPayload {
+  module: string;
+  startedAt: number;
+}
+
+export interface DeployCompletedPayload {
+  module: string;
+  startedAt: number;
+  durationMs: number;
+}
+
+export interface DeployFailedPayload {
+  module: string;
+  startedAt: number;
+  durationMs: number;
+  error: string;
+}
+
+export interface HealthCheckFailedPayload {
+  module: string;
+  reason: string;
+}
+
+const DeployStartedSchema = z.object({
+  module: z.string().min(1),
+  startedAt: z.number().int().nonnegative(),
+});
+
+const DeployCompletedSchema = z.object({
+  module: z.string().min(1),
+  startedAt: z.number().int().nonnegative(),
+  durationMs: z.number().int().nonnegative(),
+});
+
+const DeployFailedSchema = z.object({
+  module: z.string().min(1),
+  startedAt: z.number().int().nonnegative(),
+  durationMs: z.number().int().nonnegative(),
+  error: z.string(),
+});
+
+const HealthCheckFailedSchema = z.object({
+  module: z.string().min(1),
+  reason: z.string(),
+});
+
+export function emitDeployStarted(payload: DeployStartedPayload): void {
+  DeployStartedSchema.parse(payload);
+  emitBest(`deploy.started.${payload.module}`, payload);
+}
+
+export function emitDeployCompleted(payload: DeployCompletedPayload): void {
+  DeployCompletedSchema.parse(payload);
+  emitBest(`deploy.completed.${payload.module}`, payload);
+}
+
+export function emitDeployFailed(payload: DeployFailedPayload): void {
+  DeployFailedSchema.parse(payload);
+  emitBest(`deploy.failed.${payload.module}`, payload);
+}
+
+export function emitHealthCheckFailed(payload: HealthCheckFailedPayload): void {
+  HealthCheckFailedSchema.parse(payload);
+  emitBest(`health-check.failed.${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
+ * skips bus-side payload validation; we validate above with our own
+ * schemas before calling.
+ */
+function emitBest(type: string, payload: unknown): void {
+  let bus: ReturnType<typeof openBus> | undefined;
+  try {
+    bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+    bus.emitRaw(type, payload);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[celilo] failed to emit ${type}: ${msg}`);
+  } finally {
+    bus?.close();
+  }
+}

package/src/services/config-interview.ts

@@ -103,7 +103,7 @@ export async function autoDeriveMachineConfig(
     const derived = resolveMachineDerivation(variable.derive_from, machine);
     if (derived === null) continue;
 
-    log.info(`✓ ${variable.name} = ${derived} (auto-derived from ${machine.hostname})`);
+    log.success(`${variable.name} = ${derived} (auto-derived from ${machine.hostname})`);
 
     await db
       .insert(moduleConfigs)
@@ -132,7 +132,7 @@ export async function autoDeriveMachineConfig(
         }
 
         if (followUpValue !== null) {
-          log.info(`✓ ${followUpKey} = ${followUpValue} (auto-derived from ${machine.hostname})`);
+          log.success(`${followUpKey} = ${followUpValue} (auto-derived from ${machine.hostname})`);
           await db
             .insert(moduleConfigs)
             .values({
@@ -534,7 +534,7 @@ export async function interviewForMissingSecrets(
 ): Promise<InterviewResult> {
   const configured: string[] = [];
 
-  log.info(`Module '${moduleId}' requires secrets. Configuring:`);
+  log.message(`Module '${moduleId}' requires secrets. Configuring:`);
 
   const masterKey = await getOrCreateMasterKey();
 
@@ -635,7 +635,7 @@ export async function interviewForMissingSecrets(
           deriveMethod: metadata.deriveMethod,
         });
 
-        log.info(`🔗 Derived ${variable.name} from ${metadata.deriveFrom}`);
+        log.message(`Derived ${variable.name} from ${metadata.deriveFrom}`);
       } else if (source === 'generated') {
         // Auto-generate without prompting
         // Manifest generate field takes priority over schema metadata
@@ -644,7 +644,7 @@ export async function interviewForMissingSecrets(
 
         value = generateSecret({ format, length });
 
-        log.info(`🔑 Auto-generated ${format} secret: ${variable.name}`);
+        log.message(`Auto-generated ${format} secret: ${variable.name}`);
       } else if (source === 'user_provided') {
         // Always prompt, required
         // Check if we're in interactive mode
@@ -667,7 +667,7 @@ export async function interviewForMissingSecrets(
           },
         });
 
-        log.info(`✓ Saved ${variable.name}`);
+        log.success(`Saved ${variable.name}`);
       } else if (source === 'user_password') {
         // Password the user must remember — prompt twice to confirm
         if (!process.stdin.isTTY) {
@@ -706,7 +706,7 @@ export async function interviewForMissingSecrets(
           };
         }
 
-        log.info(`✓ Saved ${variable.name}`);
+        log.success(`Saved ${variable.name}`);
       } else if (source === 'generated_optional') {
         // Prompt with auto-generate option
         const message = variable.description
@@ -725,11 +725,11 @@ export async function interviewForMissingSecrets(
 
           value = generateSecret({ format, length });
 
-          log.info(`🔑 Auto-generated ${format} secret: ${variable.name}`);
+          log.message(`Auto-generated ${format} secret: ${variable.name}`);
         } else {
           // Use user-provided value
           value = userValue;
-          log.info(`✓ Saved ${variable.name}`);
+          log.success(`Saved ${variable.name}`);
         }
       } else {
         return {

package/src/services/deploy-ansible.ts

@@ -152,7 +152,7 @@ export async function executeAnsible(
   await writeFile(passwordPath, vaultPassword, { mode: 0o600 });
 
   const logPath = join(generatedPath, 'deploy.log');
-  log.info('Deploying software...');
+  log.success('Configuring host (ansible-playbook)');
 
   try {
     const result = await executeBuildWithProgress({

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

@@ -0,0 +1,184 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  getDaemonUnitPath,
+  installDaemon,
+  readInstalledUnit,
+  renderLaunchdPlist,
+  renderSystemdUnit,
+  uninstallDaemon,
+} from './events-daemon';
+
+describe('renderSystemdUnit', () => {
+  it('produces a unit with the expected ExecStart and Environment lines', () => {
+    const out = renderSystemdUnit({
+      celiloPath: '/usr/local/bin/celilo',
+      busDbPath: '/var/lib/celilo/events.db',
+      pollMs: 1000,
+      concurrency: 4,
+      home: '/home/op',
+    });
+    expect(out).toContain(
+      'ExecStart=/usr/local/bin/celilo events run --poll-ms 1000 --concurrency 4',
+    );
+    expect(out).toContain('Environment=CELILO_EVENT_BUS_PATH=/var/lib/celilo/events.db');
+    expect(out).toContain('Restart=on-failure');
+    expect(out).toContain('WantedBy=default.target');
+  });
+
+  it('honors --poll-ms and --concurrency overrides', () => {
+    const out = renderSystemdUnit({
+      celiloPath: '/c',
+      busDbPath: '/db',
+      pollMs: 250,
+      concurrency: 8,
+      home: '/h',
+    });
+    expect(out).toContain('--poll-ms 250 --concurrency 8');
+  });
+});
+
+describe('renderLaunchdPlist', () => {
+  it('puts log files under the user Library/Logs', () => {
+    const out = renderLaunchdPlist({
+      celiloPath: '/c',
+      busDbPath: '/db',
+      pollMs: 1000,
+      concurrency: 4,
+      home: '/Users/op',
+    });
+    expect(out).toContain('<string>/Users/op/Library/Logs/celilo-events.out.log</string>');
+    expect(out).toContain('<string>/Users/op/Library/Logs/celilo-events.err.log</string>');
+    expect(out).toContain('<key>Label</key>');
+    expect(out).toContain('<string>com.celilo.events</string>');
+    expect(out).toContain('<key>RunAtLoad</key>');
+    expect(out).toContain('<key>KeepAlive</key>');
+  });
+});
+
+describe('getDaemonUnitPath', () => {
+  it('returns the systemd user path on linux', () => {
+    expect(getDaemonUnitPath('linux', '/home/op')).toBe(
+      '/home/op/.config/systemd/user/celilo-events.service',
+    );
+  });
+  it('returns the LaunchAgents path on darwin', () => {
+    expect(getDaemonUnitPath('darwin', '/Users/op')).toBe(
+      '/Users/op/Library/LaunchAgents/com.celilo.events.plist',
+    );
+  });
+});
+
+describe('installDaemon / uninstallDaemon roundtrip', () => {
+  let dir: string;
+  let celiloPath: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'daemon-test-'));
+    celiloPath = join(dir, 'fake-celilo');
+    // Touch a fake celilo executable so resolveCeliloPath via override is happy.
+    writeFileSync(celiloPath, '#!/bin/sh\nexit 0\n');
+    chmodSync(celiloPath, 0o755);
+  });
+  afterEach(() => {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  it('writes a systemd unit and uninstall removes it', () => {
+    const home = join(dir, 'home');
+    const installed = installDaemon({
+      platform: 'linux',
+      home,
+      celiloPath,
+      busDbPath: '/var/lib/celilo/events.db',
+    });
+    expect(existsSync(installed.unitPath)).toBe(true);
+    expect(installed.unitPath).toBe(join(home, '.config/systemd/user/celilo-events.service'));
+    expect(installed.nextSteps[0]).toContain('systemctl --user daemon-reload');
+
+    const removed = uninstallDaemon({ platform: 'linux', home });
+    expect(removed.removed).toBe(true);
+    expect(existsSync(installed.unitPath)).toBe(false);
+  });
+
+  it('writes a launchd plist and uninstall removes it', () => {
+    const home = join(dir, 'home');
+    const installed = installDaemon({
+      platform: 'darwin',
+      home,
+      celiloPath,
+      busDbPath: '/Users/op/celilo/events.db',
+    });
+    expect(existsSync(installed.unitPath)).toBe(true);
+    expect(installed.unitPath).toBe(join(home, 'Library/LaunchAgents/com.celilo.events.plist'));
+    expect(readFileSync(installed.unitPath, 'utf-8')).toContain('com.celilo.events');
+    expect(installed.nextSteps[0]).toContain('launchctl load');
+
+    const removed = uninstallDaemon({ platform: 'darwin', home });
+    expect(removed.removed).toBe(true);
+  });
+
+  it('install is idempotent — second call overwrites with new content', () => {
+    const home = join(dir, 'home');
+    installDaemon({
+      platform: 'linux',
+      home,
+      celiloPath,
+      busDbPath: '/db1',
+      pollMs: 1000,
+    });
+    const second = installDaemon({
+      platform: 'linux',
+      home,
+      celiloPath,
+      busDbPath: '/db2',
+      pollMs: 500,
+    });
+    const written = readFileSync(second.unitPath, 'utf-8');
+    expect(written).toContain('CELILO_EVENT_BUS_PATH=/db2');
+    expect(written).toContain('--poll-ms 500');
+    expect(written).not.toContain('CELILO_EVENT_BUS_PATH=/db1');
+  });
+
+  it('uninstall on a missing unit reports not-removed', () => {
+    const home = join(dir, 'home');
+    const result = uninstallDaemon({ platform: 'linux', home });
+    expect(result.removed).toBe(false);
+    expect(result.nextSteps[0]).toContain('nothing to clean up');
+  });
+
+  it('readInstalledUnit returns content when present, exists:false when not', () => {
+    const home = join(dir, 'home');
+    const before = readInstalledUnit({ platform: 'linux', home });
+    expect(before.exists).toBe(false);
+
+    installDaemon({
+      platform: 'linux',
+      home,
+      celiloPath,
+      busDbPath: '/db',
+    });
+    const after = readInstalledUnit({ platform: 'linux', home });
+    expect(after.exists).toBe(true);
+    if (after.exists) {
+      expect(after.content).toContain('events run');
+    }
+  });
+
+  it('rejects --celilo-path overrides that do not exist', () => {
+    expect(() =>
+      installDaemon({
+        platform: 'linux',
+        home: join(dir, 'home'),
+        celiloPath: '/no/such/celilo',
+        busDbPath: '/db',
+      }),
+    ).toThrow(/does not exist/);
+  });
+});

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/health-runner.ts

@@ -117,7 +117,7 @@ export async function runModuleHealthCheck(
       { debug: false, capabilities: capabilityFunctions, requiredCapabilities },
     );
   } else {
-    const gauge = new FuelGauge(`Checking ${moduleId}`, {
+    const gauge = new FuelGauge('Testing app', {
       skipAnimation: options.noInteractive,
     });
     gauge.start();