@celilo/cli 0.13.3 → 0.14.1

package/src/cli/commands/notify-config.ts

@@ -0,0 +1,453 @@
+/**
+ * `celilo person` / `route` / `escalation-policy` — who celilo can reach.
+ *
+ * One file because the three are a single concept split across three tables,
+ * and splitting the CLI too would mean three copies of the same lookup-by-name
+ * and table-printing code.
+ *
+ * Everything is addressed by name. A UUID never reaches the operator
+ * (CLAUDE.md), and a route is identified by `<person>/<transport>` rather than
+ * by an id, because that is what someone actually knows about it.
+ */
+
+import { defineEvents, openBus } from '@celilo/event-bus';
+import { eq } from 'drizzle-orm';
+import { getEventBusPath } from '../../config/paths';
+import { getDb } from '../../db/client';
+import { type AlertSeverity, modules, monitors } from '../../db/schema';
+import { ensureInboundSubscriber, findMonitorByTarget } from '../../services/alerting/monitors';
+import {
+  addPolicyStep,
+  createPerson,
+  createPolicy,
+  createRoute,
+  deletePerson,
+  deletePolicy,
+  deleteRoute,
+  findPerson,
+  findPolicy,
+  findRoute,
+  listPeople,
+  listPolicies,
+  listPolicySteps,
+  listRoutes,
+} from '../../services/alerting/people';
+import { parseClockTime } from '../../services/alerting/quiet-hours';
+import type { CommandResult } from '../types';
+
+const NO_SCHEMAS = defineEvents({});
+
+function table(headers: string[], rows: string[][]): string {
+  if (rows.length === 0) return '';
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+  const line = (cells: string[]) =>
+    cells
+      .map((c, i) => (i === cells.length - 1 ? c : c.padEnd(widths[i])))
+      .join('  ')
+      .trimEnd();
+  return [line(headers), ...rows.map(line)].join('\n');
+}
+
+const flagString = (flags: Record<string, boolean | string>, name: string): string | undefined =>
+  typeof flags[name] === 'string' ? (flags[name] as string) : undefined;
+
+/**
+ * Whether a module declares the `notification` capability.
+ *
+ * Read from the manifest rather than the capabilities table: a module can be
+ * imported but not yet deployed, and configuring a route ahead of deploying
+ * the transport is a reasonable order to work in.
+ */
+function providesNotification(db: ReturnType<typeof getDb>, moduleId: string): boolean {
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) return false;
+  const manifest = module.manifestData as {
+    provides?: { capabilities?: { name?: string }[] };
+  };
+  return Boolean(manifest.provides?.capabilities?.some((c) => c.name === 'notification'));
+}
+
+// ── celilo person ───────────────────────────────────────────────────────────
+
+function personAdd(args: string[], flags: Record<string, boolean | string>): CommandResult {
+  const name = args[0];
+  if (!name) {
+    return {
+      success: false,
+      error: 'Usage: celilo person add <name> --timezone <IANA> [--quiet-hours 22:00-07:00]',
+    };
+  }
+
+  const db = getDb();
+  if (findPerson(db, name)) return { success: false, error: `Person "${name}" already exists.` };
+
+  const timezone = flagString(flags, 'timezone');
+  if (!timezone) {
+    return {
+      success: false,
+      error: 'A --timezone is required (e.g. America/Los_Angeles) — quiet hours are local to it.',
+    };
+  }
+
+  let quietStart: string | null = null;
+  let quietEnd: string | null = null;
+  const quiet = flagString(flags, 'quiet-hours');
+  if (quiet) {
+    const [start, end] = quiet.split('-');
+    if (!start || !end || parseClockTime(start) === null || parseClockTime(end) === null) {
+      return {
+        success: false,
+        error: `Invalid --quiet-hours "${quiet}". Use HH:MM-HH:MM, e.g. 22:00-07:00.`,
+      };
+    }
+    quietStart = start;
+    quietEnd = end;
+  }
+
+  createPerson(db, { name, timezone, quietHoursStart: quietStart, quietHoursEnd: quietEnd });
+  const quietNote = quiet ? `, quiet ${quiet}` : ', always reachable';
+  return { success: true, message: `Added ${name} (${timezone}${quietNote})` };
+}
+
+function personList(): CommandResult {
+  const people = listPeople(getDb());
+  if (people.length === 0) {
+    console.log('\nNobody configured.\n');
+    console.log(
+      '  celilo person add peter --timezone America/Los_Angeles --quiet-hours 22:00-07:00\n',
+    );
+    return { success: true, message: 'No people configured' };
+  }
+
+  console.log('');
+  console.log(
+    table(
+      ['NAME', 'TIMEZONE', 'QUIET HOURS'],
+      people.map((p) => [
+        p.name,
+        p.timezone,
+        p.quietHoursStart && p.quietHoursEnd
+          ? `${p.quietHoursStart}-${p.quietHoursEnd}`
+          : 'always reachable',
+      ]),
+    ),
+  );
+  console.log('');
+  return { success: true, message: `${people.length} person(s)` };
+}
+
+function personRemove(args: string[]): CommandResult {
+  const name = args[0];
+  if (!name) return { success: false, error: 'Usage: celilo person remove <name>' };
+
+  const db = getDb();
+  const person = findPerson(db, name);
+  if (!person) return { success: false, error: `No person named "${name}".` };
+
+  // Routes cascade, and so do the escalation steps pointing at them — a step
+  // aimed at a deleted route would otherwise skip silently at page time.
+  deletePerson(db, person.id);
+  return { success: true, message: `Removed ${name} and their routes` };
+}
+
+export async function handlePerson(
+  subcommand: string | undefined,
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  switch (subcommand) {
+    case undefined:
+    case 'list':
+      return personList();
+    case 'add':
+      return personAdd(args, flags);
+    case 'remove':
+      return personRemove(args);
+    default:
+      return {
+        success: false,
+        error: `Unknown person subcommand: ${subcommand}\n\nUse: list, add, remove`,
+      };
+  }
+}
+
+// ── celilo route ────────────────────────────────────────────────────────────
+
+function routeAdd(args: string[], flags: Record<string, boolean | string>): CommandResult {
+  const [personName, transport] = args;
+  const address = flagString(flags, 'address');
+  if (!personName || !transport || !address) {
+    return {
+      success: false,
+      error:
+        'Usage: celilo route add <person> <transport-module> --address <addr> [--severity-floor warning|critical]',
+    };
+  }
+
+  const db = getDb();
+  const person = findPerson(db, personName);
+  if (!person) return { success: false, error: `No person named "${personName}".` };
+
+  // Check the transport BEFORE inserting. The routes table has a foreign key
+  // to modules, so a typo would otherwise surface as a raw
+  // SQLITE_CONSTRAINT_FOREIGNKEY stack trace — which tells an operator
+  // nothing about what they got wrong.
+  const module = db.select().from(modules).where(eq(modules.id, transport)).get();
+  if (!module) {
+    const available = db.select({ id: modules.id }).from(modules).all();
+    const providers = available.filter((m) => providesNotification(db, m.id)).map((m) => m.id);
+    const hint = providers.length
+      ? `Available notification transports: ${providers.join(', ')}`
+      : 'No module providing the `notification` capability is installed yet.';
+    return { success: false, error: `No module "${transport}" is installed.\n\n${hint}` };
+  }
+
+  // A route to a module that cannot send is a route that silently never pages.
+  if (!providesNotification(db, transport)) {
+    return {
+      success: false,
+      error: `Module "${transport}" does not provide the \`notification\` capability, so it cannot page anyone.`,
+    };
+  }
+
+  if (findRoute(db, person.id, transport)) {
+    return { success: false, error: `${personName} already has a ${transport} route.` };
+  }
+
+  const floor = flagString(flags, 'severity-floor') ?? 'warning';
+  if (floor !== 'warning' && floor !== 'critical') {
+    return { success: false, error: `--severity-floor must be "warning" or "critical".` };
+  }
+
+  // A transport that can receive is one whose module is deployed AND provides
+  // a receive path. Until the inbound poller lands we record the operator's
+  // intent; a route that cannot ack simply never stops escalation.
+  const canAck = flags['can-ack'] === true;
+
+  createRoute(db, {
+    personId: person.id,
+    transportModuleId: transport,
+    address,
+    severityFloor: floor as AlertSeverity,
+    canAck,
+  });
+  // A route that can receive is what makes inbound polling worth doing, so
+  // that is when the subscriber is registered.
+  if (canAck) {
+    const bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+    try {
+      ensureInboundSubscriber(bus);
+    } finally {
+      bus.close();
+    }
+  }
+
+  return {
+    success: true,
+    message: `Reaching ${personName} via ${transport} at ${address} (floor: ${floor})`,
+  };
+}
+
+function routeList(): CommandResult {
+  const db = getDb();
+  const routes = listRoutes(db);
+  if (routes.length === 0) {
+    console.log('\nNo routes configured — nothing can be paged.\n');
+    console.log('  celilo route add peter signal --address +15551234567 --can-ack\n');
+    return { success: true, message: 'No routes configured' };
+  }
+
+  const people = new Map(listPeople(db).map((p) => [p.id, p.name]));
+  console.log('');
+  console.log(
+    table(
+      ['PERSON', 'TRANSPORT', 'ADDRESS', 'FLOOR', 'ACK', 'STATE'],
+      routes.map((r) => [
+        people.get(r.personId) ?? '(unknown)',
+        r.transportModuleId,
+        r.address,
+        r.severityFloor,
+        r.canAck ? 'yes' : 'no',
+        r.enabled ? 'enabled' : 'disabled',
+      ]),
+    ),
+  );
+  console.log('');
+  return { success: true, message: `${routes.length} route(s)` };
+}
+
+function routeRemove(args: string[]): CommandResult {
+  const [personName, transport] = args;
+  if (!personName || !transport) {
+    return { success: false, error: 'Usage: celilo route remove <person> <transport-module>' };
+  }
+
+  const db = getDb();
+  const person = findPerson(db, personName);
+  if (!person) return { success: false, error: `No person named "${personName}".` };
+  const route = findRoute(db, person.id, transport);
+  if (!route) return { success: false, error: `${personName} has no ${transport} route.` };
+
+  deleteRoute(db, route.id);
+  return { success: true, message: `Removed ${personName}'s ${transport} route` };
+}
+
+export async function handleRoute(
+  subcommand: string | undefined,
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  switch (subcommand) {
+    case undefined:
+    case 'list':
+      return routeList();
+    case 'add':
+      return routeAdd(args, flags);
+    case 'remove':
+      return routeRemove(args);
+    default:
+      return {
+        success: false,
+        error: `Unknown route subcommand: ${subcommand}\n\nUse: list, add, remove`,
+      };
+  }
+}
+
+// ── celilo escalation-policy ────────────────────────────────────────────────
+
+function policyAdd(args: string[]): CommandResult {
+  const name = args[0];
+  if (!name) return { success: false, error: 'Usage: celilo escalation-policy add <name>' };
+
+  const db = getDb();
+  if (findPolicy(db, name)) return { success: false, error: `Policy "${name}" already exists.` };
+
+  createPolicy(db, name);
+  return {
+    success: true,
+    message: `Created policy "${name}" — add steps with: celilo escalation-policy step ${name} <person> <transport> --after 0m`,
+  };
+}
+
+function policyStep(args: string[], flags: Record<string, boolean | string>): CommandResult {
+  const [policyName, personName, transport] = args;
+  if (!policyName || !personName || !transport) {
+    return {
+      success: false,
+      error:
+        'Usage: celilo escalation-policy step <policy> <person> <transport-module> --after <minutes>',
+    };
+  }
+
+  const db = getDb();
+  const policy = findPolicy(db, policyName);
+  if (!policy) return { success: false, error: `No policy named "${policyName}".` };
+  const person = findPerson(db, personName);
+  if (!person) return { success: false, error: `No person named "${personName}".` };
+  const route = findRoute(db, person.id, transport);
+  if (!route) {
+    return {
+      success: false,
+      error: `${personName} has no ${transport} route. Add one first:\n  celilo route add ${personName} ${transport} --address <addr>`,
+    };
+  }
+
+  const after = flagString(flags, 'after') ?? '0';
+  const delayMinutes = Number.parseInt(after.replace(/m$/, ''), 10);
+  if (!Number.isFinite(delayMinutes) || delayMinutes < 0) {
+    return { success: false, error: `Invalid --after "${after}". Use minutes, e.g. 0, 10, 30.` };
+  }
+
+  const step = addPolicyStep(db, policy.id, route.id, delayMinutes);
+  return {
+    success: true,
+    message: `Step ${step.stepIndex}: ${personName} via ${transport} after ${delayMinutes}m`,
+  };
+}
+
+function policyList(): CommandResult {
+  const db = getDb();
+  const policies = listPolicies(db);
+  if (policies.length === 0) {
+    console.log('\nNo escalation policies.\n');
+    console.log('  celilo escalation-policy add default\n');
+    return { success: true, message: 'No policies configured' };
+  }
+
+  const people = new Map(listPeople(db).map((p) => [p.id, p.name]));
+  const routes = new Map(listRoutes(db).map((r) => [r.id, r]));
+
+  console.log('');
+  for (const policy of policies) {
+    const steps = listPolicySteps(db, policy.id);
+    console.log(`${policy.name}${policy.bypassQuietHours ? '  (bypasses quiet hours)' : ''}`);
+    if (steps.length === 0) {
+      console.log('  (no steps — nothing will be paged)');
+    }
+    for (const step of steps) {
+      const route = routes.get(step.routeId);
+      const who = route ? (people.get(route.personId) ?? '(unknown)') : '(deleted route)';
+      const via = route ? route.transportModuleId : '?';
+      console.log(`  ${step.stepIndex}. ${who} via ${via} after ${step.delayMinutes}m`);
+    }
+    console.log('');
+  }
+  return { success: true, message: `${policies.length} polic(ies)` };
+}
+
+function policyRemove(args: string[]): CommandResult {
+  const name = args[0];
+  if (!name) return { success: false, error: 'Usage: celilo escalation-policy remove <name>' };
+
+  const db = getDb();
+  const policy = findPolicy(db, name);
+  if (!policy) return { success: false, error: `No policy named "${name}".` };
+
+  deletePolicy(db, policy.id);
+  return { success: true, message: `Removed policy "${name}"` };
+}
+
+function policyAssign(args: string[]): CommandResult {
+  const [policyName, target] = args;
+  if (!policyName || !target) {
+    return { success: false, error: 'Usage: celilo escalation-policy assign <policy> <monitor>' };
+  }
+
+  const db = getDb();
+  const policy = findPolicy(db, policyName);
+  if (!policy) return { success: false, error: `No policy named "${policyName}".` };
+  const monitor = findMonitorByTarget(db, target);
+  if (!monitor) return { success: false, error: `No monitor for "${target}".` };
+
+  db.update(monitors)
+    .set({ escalationPolicyId: policy.id })
+    .where(eq(monitors.id, monitor.id))
+    .run();
+
+  return { success: true, message: `${target} now escalates via "${policyName}"` };
+}
+
+export async function handleEscalationPolicy(
+  subcommand: string | undefined,
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  switch (subcommand) {
+    case undefined:
+    case 'list':
+      return policyList();
+    case 'add':
+      return policyAdd(args);
+    case 'step':
+      return policyStep(args, flags);
+    case 'assign':
+      return policyAssign(args);
+    case 'remove':
+      return policyRemove(args);
+    default:
+      return {
+        success: false,
+        error: `Unknown escalation-policy subcommand: ${subcommand}\n\nUse: list, add, step, assign, remove`,
+      };
+  }
+}

package/src/cli/commands/system-audit.ts

@@ -50,6 +50,7 @@ import type { ServiceCredentialsResult } from '../../services/audit/services-cre
 import type { ServiceReachableResult } from '../../services/audit/services-reachable';
 import type { TerraformPlanRunner } from '../../services/audit/terraform-plan';
 import { getServiceCredentials, listContainerServices } from '../../services/container-service';
+import { collectFirewallReach } from '../../services/firewall-reach';
 import { runAllHealthChecks } from '../../services/health-runner';
 import { listMachines } from '../../services/machine-pool';
 import { parseStoredConfigValue } from '../../services/module-config';
@@ -436,6 +437,7 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
     secretsDecryptable: { results: secretResults },
     servicesReachable: { results: serviceReachableResults },
     machinesReachable: { results: machineReachableResults },
+    trustedSources: { firewalls: collectFirewallReach(db) },
   };
 }
 

package/src/cli/commands/system-update.ts

@@ -585,6 +585,7 @@ export async function handleSystemUpdate(
     secretsDecryptable: { results: [] },
     servicesReachable: { results: [] },
     machinesReachable: { results: [] },
+    trustedSources: { firewalls: [] },
   };
 
   if (dryRun) {

package/src/cli/completion.ts

@@ -37,16 +37,21 @@ export async function getCompletions(words: string[], current: number): Promise<
       'commands',
       'dns',
       'completion',
+      'alerts',
+      'escalation-policy',
       'events',
       'help',
       'hook',
       'ipam',
       'machine',
       'module',
+      'monitor',
       'package',
+      'person',
       'proxmox',
       'publish',
       'registry',
+      'route',
       'restore',
       'service',
       'status',
@@ -449,6 +454,27 @@ export async function getCompletions(words: string[], current: number): Promise<
     return filterSuggestions(subcommands, args[1] || '');
   }
 
+  // Person / route / escalation-policy subcommands
+  if (command === 'person' && currentIndex === 1) {
+    return filterSuggestions(['list', 'add', 'remove'], args[1] || '');
+  }
+  if (command === 'route' && currentIndex === 1) {
+    return filterSuggestions(['list', 'add', 'remove'], args[1] || '');
+  }
+  if (command === 'escalation-policy' && currentIndex === 1) {
+    return filterSuggestions(['list', 'add', 'step', 'assign', 'remove'], args[1] || '');
+  }
+
+  // Monitor subcommands
+  if (command === 'monitor' && currentIndex === 1) {
+    return filterSuggestions(['list', 'add', 'run', 'enable', 'disable'], args[1] || '');
+  }
+
+  // Alerts subcommands
+  if (command === 'alerts' && currentIndex === 1) {
+    return filterSuggestions(['list', 'ack', 'silence', 'resolve', 'sweep', 'poll'], args[1] || '');
+  }
+
   // Storage subcommands
   if (command === 'storage' && currentIndex === 1) {
     const subcommands = ['add', 'list', 'remove', 'verify', 'set-default'];

package/src/cli/generate-zsh-completion.ts

@@ -357,6 +357,8 @@ _celilo_system_config_keys() {
     'network.internal.gateway:Internal gateway IP'
     'network.secure-mgmt.subnet:Control-plane subnet (celilo-mgr own network)'
     'network.secure-mgmt.gateway:Control-plane gateway IP'
+    'network.vpn.subnet:VPN client subnet (WireGuard remote access)'
+    'firewall.trusted_subnets:Extra subnets that reach every managed zone (comma-separated CIDRs)'
     'dns.primary:Primary DNS server'
     'dns.fallback:Fallback DNS servers'
     'routing.internal_gateway:Internal gateway IP'

package/src/cli/index.ts

@@ -178,6 +178,11 @@ Usage:
 Commands:
   status                   Show system and module status
   audit                    Top-level alias for 'system audit'
+  alerts                   View alerts raised by monitors
+  monitor                  Manage what celilo watches (health checks on a schedule)
+  person                   Manage people celilo can reach
+  route                    Manage how each person is reached (transport + address)
+  escalation-policy        Manage who gets paged, and in what order
   events                   SQLite event-bus operations (status, tail, run dispatcher, etc.)
   capability               View registered module capabilities
   dns                      View DNS bookkeeping (registrations ledger)
@@ -1708,6 +1713,59 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     }
   }
 
+  if (parsed.command === 'person') {
+    const { handlePerson } = await import('./commands/notify-config');
+    return handlePerson(parsed.subcommand, parsed.args, parsed.flags);
+  }
+
+  if (parsed.command === 'route') {
+    const { handleRoute } = await import('./commands/notify-config');
+    return handleRoute(parsed.subcommand, parsed.args, parsed.flags);
+  }
+
+  if (parsed.command === 'escalation-policy') {
+    const { handleEscalationPolicy } = await import('./commands/notify-config');
+    return handleEscalationPolicy(parsed.subcommand, parsed.args, parsed.flags);
+  }
+
+  if (parsed.command === 'monitor') {
+    const { handleMonitor } = await import('./commands/monitor');
+    return handleMonitor(parsed.subcommand, parsed.args, parsed.flags);
+  }
+
+  if (parsed.command === 'alerts') {
+    if (parsed.subcommand === 'ack') {
+      const { handleAlertsAck } = await import('./commands/alerts-act');
+      return handleAlertsAck(parsed.args, parsed.flags);
+    }
+    if (parsed.subcommand === 'silence') {
+      const { handleAlertsSilence } = await import('./commands/alerts-act');
+      return handleAlertsSilence(parsed.args, parsed.flags);
+    }
+    if (parsed.subcommand === 'resolve') {
+      const { handleAlertsResolve } = await import('./commands/alerts-act');
+      return handleAlertsResolve(parsed.args);
+    }
+    if (parsed.subcommand === 'poll') {
+      const { handleAlertsPoll } = await import('./commands/alerts-poll');
+      return handleAlertsPoll(parsed.flags);
+    }
+    if (parsed.subcommand === 'sweep') {
+      const { handleAlertsSweep } = await import('./commands/alerts-sweep');
+      return handleAlertsSweep();
+    }
+    if (!parsed.subcommand || parsed.subcommand === 'list') {
+      const alertsFlagError = checkFlags('alerts', 'list', parsed.flags, parsed.args);
+      if (alertsFlagError) return alertsFlagError;
+      const { handleAlertsList } = await import('./commands/alerts-list');
+      return handleAlertsList(parsed.args, parsed.flags);
+    }
+    return {
+      success: false,
+      error: `Unknown alerts subcommand: ${parsed.subcommand}\n\nUse: list, ack, silence, resolve, sweep, poll`,
+    };
+  }
+
   if (parsed.command === 'storage') {
     if (parsed.flags.help || parsed.flags.h) {
       return displayStorageHelp();

package/src/cli/tui/audit-state.ts

@@ -83,6 +83,7 @@ export const ALL_CATEGORIES: readonly DriftCategory[] = [
   'secrets_decryptable',
   'services_reachable',
   'machines_reachable',
+  'trusted_sources',
 ];
 
 export const CATEGORY_LABELS: Record<DriftCategory, string> = {
@@ -100,6 +101,7 @@ export const CATEGORY_LABELS: Record<DriftCategory, string> = {
   secrets_decryptable: 'Secrets',
   services_reachable: 'Service reachability',
   machines_reachable: 'Machine reachability',
+  trusted_sources: 'Trusted networks',
 };
 
 /** Total lines we keep across the command log before evicting oldest. */