@celilo/cli 0.5.0-alpha.0 → 0.5.0-alpha.2

package/src/cli/index.ts

@@ -10,6 +10,7 @@ import { COMMANDS, type CommandDef } from './command-registry';
 import { handleCapabilityInfo } from './commands/capability-info';
 import { handleCapabilityList } from './commands/capability-list';
 import { handleCompletion } from './commands/completion';
+import { handleDnsRegistrations } from './commands/dns';
 import {
   handleEventsAck,
   handleEventsDrain,
@@ -162,6 +163,7 @@ Commands:
   audit                    Top-level alias for 'system audit'
   events                   SQLite event-bus operations (status, tail, run dispatcher, etc.)
   capability               View registered module capabilities
+  dns                      View DNS bookkeeping (registrations ledger)
   package                  Create distributable .netapp packages from module source
   module                   Manage modules (import, list, configure, build, generate)
   service                  Manage container services (Proxmox, Digital Ocean)
@@ -265,9 +267,9 @@ Subcommands:
   repair                       Crash-recovery sweep without starting the dispatcher
   resume                       Alias for repair (acknowledges halt-on-recovery)
   respond                      Run the terminal responder; answer deploy prompts from another shell
-  install-daemon               Write a systemd/launchd user unit for the dispatcher
-  uninstall-daemon             Remove the installed supervisor unit
-  show-daemon                  Print the currently installed unit file
+  install-daemon [--system]    Write a systemd/launchd unit for the dispatcher (--system: management-plane scope)
+  uninstall-daemon [--system]  Remove the installed supervisor unit
+  show-daemon [--system]       Print the currently installed unit file
 
 Description:
   The event bus is a SQLite-backed pub/sub layer for celilo modules.
@@ -380,6 +382,32 @@ Related Commands:
   };
 }
 
+function displayDnsHelp(): CommandResult {
+  const helpText = `
+Celilo - DNS Bookkeeping
+
+Usage:
+  celilo dns <subcommand> [options]
+
+Subcommands:
+  registrations           List the DNS registration ledger
+
+Description:
+  Every successful dns_registrar.registerHost (e.g. a deploy registering
+  its public hostname with namecheap) is recorded in the registration
+  ledger. The provider's refresh_registrations hook re-asserts these on
+  a timer; REFRESHED shows when that last succeeded.
+
+Options:
+  --provider <module-id>  Only show registrations owned by one provider
+
+Examples:
+  celilo dns registrations
+  celilo dns registrations --provider namecheap
+`;
+  return { success: true, message: helpText };
+}
+
 function displayCapabilityHelp(): CommandResult {
   const helpText = `
 Celilo - Capability Management
@@ -1075,6 +1103,28 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     };
   }
 
+  if (parsed.command === 'dns') {
+    if (parsed.flags.help || parsed.flags.h) {
+      return displayDnsHelp();
+    }
+
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'DNS subcommand required\n\nRun "celilo dns --help" for usage',
+      };
+    }
+
+    if (parsed.subcommand === 'registrations') {
+      return handleDnsRegistrations(parsed.args, parsed.flags);
+    }
+
+    return {
+      success: false,
+      error: `Unknown dns subcommand: ${parsed.subcommand}\n\nRun "celilo dns --help" for usage`,
+    };
+  }
+
   if (parsed.command === 'capability') {
     if (parsed.flags.help || parsed.flags.h) {
       return displayCapabilityHelp();
@@ -1168,9 +1218,9 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       case 'install-daemon':
         return handleEventsInstallDaemon(parsed.args, parsed.flags);
       case 'uninstall-daemon':
-        return handleEventsUninstallDaemon();
+        return handleEventsUninstallDaemon(parsed.args, parsed.flags);
       case 'show-daemon':
-        return handleEventsShowDaemon();
+        return handleEventsShowDaemon(parsed.args, parsed.flags);
       default:
         return {
           success: false,

package/src/db/schema.ts

@@ -432,6 +432,42 @@ export const webRoutes = sqliteTable(
   }),
 );
 
+/**
+ * DNS registration ledger — one row per (provider, fqdn) the framework
+ * has successfully registered via dns_registrar.registerHost. Written
+ * framework-side by the capability loader (the only layer that knows
+ * both consumer and provider), read back to drive the provider's
+ * periodic refresh_registrations hook and the `celilo dns
+ * registrations` view. Rows die with either module via FK cascade; the
+ * remote DNS record itself stays (Namecheap DDNS has no delete API).
+ * See designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md (B2).
+ */
+export const dnsRegistrations = sqliteTable(
+  'dns_registrations',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    providerModuleId: text('provider_module_id')
+      .notNull()
+      .references(() => modules.id, { onDelete: 'cascade' }),
+    consumerModuleId: text('consumer_module_id')
+      .notNull()
+      .references(() => modules.id, { onDelete: 'cascade' }),
+    fqdn: text('fqdn').notNull(),
+    /** null = provider auto-detected the request's source IP (Namecheap-style). */
+    ip: text('ip'),
+    registeredAt: integer('registered_at', { mode: 'timestamp' })
+      .notNull()
+      .default(sql`(unixepoch())`),
+    refreshedAt: integer('refreshed_at', { mode: 'timestamp' }),
+  },
+  (table) => ({
+    providerFqdnUnique: uniqueIndex('dns_registrations_provider_fqdn_idx').on(
+      table.providerModuleId,
+      table.fqdn,
+    ),
+  }),
+);
+
 /**
  * Backup storage providers - destinations for backup archives
  * Supports local filesystem and S3-compatible storage (AWS S3, MinIO, Backblaze B2, Wasabi)

package/src/hooks/capability-loader.ts

@@ -19,6 +19,7 @@ import {
 } from '@celilo/capabilities';
 import type {
   DnsInternalCapability,
+  DnsRegistrarCapability,
   HookLogger,
   RouteOps,
   RouteReadView,
@@ -30,6 +31,7 @@ import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { emitWebRoutesChangedAndWait } from '../services/celilo-events';
 import { getModuleSystems } from '../services/deployed-systems';
+import { withDnsRegistrationLedger } from '../services/dns-registrations';
 import { loadHookConfigMap } from './load-hook-config';
 
 /**
@@ -194,6 +196,20 @@ export async function loadCapabilityFunctions(
     const providerConfig = await loadModuleConfig(capability.moduleId, db);
     const providerSecrets = await loadModuleSecrets(capability.moduleId, masterKey, db);
 
+    // dns_registrar interfaces get the registration-ledger wrapper:
+    // every successful registerHost is recorded in dns_registrations so
+    // the provider's refresh_registrations hook can re-assert it later
+    // (designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md B2). The loader is
+    // the one layer that knows both provider and consumer.
+    const withLedgerIfDnsRegistrar = (iface: unknown): unknown =>
+      capName === 'dns_registrar'
+        ? withDnsRegistrationLedger(iface as DnsRegistrarCapability, {
+            db,
+            providerModuleId: capability.moduleId,
+            consumerModuleId: consumingModuleId,
+          })
+        : iface;
+
     try {
       // Dynamically import the capability module. Try the default export
       // first (the HOOK_API_V2 Phase 8 pattern), fall back to the legacy
@@ -217,7 +233,7 @@ export async function loadCapabilityFunctions(
           systems: getModuleSystems(capability.moduleId, db),
           logger,
         });
-        result[capName] = capabilityInterface;
+        result[capName] = withLedgerIfDnsRegistrar(capabilityInterface);
         debugLog(`${capName}: loaded via defineCapabilityFunction`);
         continue;
       }
@@ -233,7 +249,9 @@ export async function loadCapabilityFunctions(
       );
 
       if (capabilityInterface) {
-        result[capName] = wrapWithLogging(capabilityInterface as object, logger, capName);
+        result[capName] = withLedgerIfDnsRegistrar(
+          wrapWithLogging(capabilityInterface as object, logger, capName),
+        );
         debugLog(`${capName}: loaded via legacy factory`);
       }
     } catch (error) {
@@ -388,6 +406,16 @@ export async function loadCapabilityFunctions(
               `public_web reconcile for ${consumingModuleId}: ${reconcile.failed} delivery(ies) failed — caddy could not apply the route, so the hostname is not served.`,
             );
           }
+          // ISS-0087: a route WAS registered and the dispatcher IS alive, yet ZERO
+          // providers reconciled it (no subscriber consumed routes_changed). That
+          // registers a route nobody applied and would otherwise report success.
+          // `events === 0` means no routes changed (benign); `events > 0 &&
+          // succeeded === 0` means the route changed but nobody served it — a failure.
+          if (reconcile.events > 0 && reconcile.succeeded === 0) {
+            throw new Error(
+              `public_web route for ${consumingModuleId} changed (${reconcile.events} event(s)) but NO provider reconciled it — caddy has no reconcile_routes subscription on the bus, so the route is persisted yet never served (no site block, no cert). Ensure a public_web provider (caddy) is deployed and subscribed.`,
+            );
+          }
         },
       });
       debugLog(`public_web: loaded via framework implementation for ${consumingModuleId}`);

package/src/hooks/run-named-hook.ts

@@ -19,6 +19,10 @@ import type { ModuleManifest } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { getModuleSystems } from '../services/deployed-systems';
+import {
+  listDnsRegistrations,
+  stampDnsRegistrationsRefreshed,
+} from '../services/dns-registrations';
 import { loadCapabilityFunctions } from './capability-loader';
 import { invokeHook } from './executor';
 import { loadHookConfigMap } from './load-hook-config';
@@ -125,12 +129,26 @@ export async function runNamedHook(
     : [];
   const capabilityFunctions = await loadCapabilityFunctions(moduleId, db, logger);
 
-  return invokeHook(
+  // refresh_registrations is fed by the framework: module scripts can't
+  // read the celilo DB, so the dns_registrations ledger rows for THIS
+  // provider are injected as the contract's `registrations` input
+  // (designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md B3). Authoritative —
+  // overrides any caller-supplied value.
+  let inputs = options.inputs ?? {};
+  if (hookName === 'refresh_registrations') {
+    const registrations = listDnsRegistrations(db, { providerModuleId: moduleId }).map((r) => ({
+      fqdn: r.fqdn,
+      ip: r.ip,
+    }));
+    inputs = { ...inputs, registrations };
+  }
+
+  const result = await invokeHook(
     module.sourcePath,
     hookName,
     manifest.celilo_contract,
     hookDef,
-    options.inputs ?? {},
+    inputs,
     configMap,
     secretMap,
     logger,
@@ -141,4 +159,12 @@ export async function runNamedHook(
       systems: getModuleSystems(moduleId, db),
     },
   );
+
+  // A fully successful refresh stamps the ledger so `celilo dns
+  // registrations` shows when each provider last re-asserted.
+  if (hookName === 'refresh_registrations' && result.success) {
+    stampDnsRegistrationsRefreshed(db, moduleId);
+  }
+
+  return result;
 }

package/src/hooks/types.ts

@@ -119,7 +119,8 @@ export type HookName =
   | 'on_backup'
   | 'on_backup_analyze'
   | 'on_restore'
-  | 'on_system_event';
+  | 'on_system_event'
+  | 'refresh_registrations';
 
 /**
  * Hook manifest section - maps hook names to definitions

package/src/manifest/contracts/v1.ts

@@ -178,6 +178,22 @@ export const V1_HOOKS: ContractHooks = {
     inputs: {},
     outputs: {},
   },
+  /**
+   * Periodic re-assertion of a dns_registrar provider's registered
+   * records (designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md B3). The
+   * framework populates `registrations` from the dns_registrations
+   * ledger (module scripts cannot read the celilo DB); the hook
+   * re-sends each {fqdn, ip} to the underlying DNS API and fails —
+   * loudly — if ANY record cannot be re-asserted. Typically driven by
+   * a `timer.tick.15m` subscription.
+   */
+  refresh_registrations: {
+    inputs: {
+      /** Array<{ fqdn: string; ip: string | null }>, framework-injected. */
+      registrations: { required: true },
+    },
+    outputs: {},
+  },
   /**
    * Build-bus upstream publish hook. The executor passes the
    * PublishEvent fields as env vars (CELILO_EVENT_PAYLOAD,

package/src/manifest/schema.ts

@@ -523,6 +523,16 @@ export const ModuleManifestSchema = z
          * [[v2/PUBLIC_WEB_PROVIDER_RECONCILE.md]].
          */
         reconcile_routes: LifecycleHookSchema.optional(),
+        /**
+         * Periodic re-assertion of a dns_registrar provider's registered
+         * records. The framework injects the provider's dns_registrations
+         * ledger rows as the `registrations` input; the hook re-sends each
+         * one to the underlying DNS API and fails loudly if any cannot be
+         * re-asserted. Providers subscribe it to a `timer.tick.*` event.
+         * Part of the dns_registrar capability contract — see
+         * designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md (B3).
+         */
+        refresh_registrations: LifecycleHookSchema.optional(),
         /**
          * Build-bus upstream publish hooks. Array (a module can react
          * to multiple upstream packages with different actions). See

package/src/services/dns-provider-backfill.ts

@@ -15,7 +15,7 @@
  */
 
 import type { DnsInternalCapability, HookLogger } from '@celilo/capabilities';
-import { and, eq } from 'drizzle-orm';
+import { and, eq, inArray, or } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { capabilities as capabilitiesTable, modules, webRoutes } from '../db/schema';
 import { loadCapabilityFunctions, resolveFirewallNatIp } from '../hooks/capability-loader';
@@ -54,7 +54,19 @@ export async function backfillProviderDns(
 ): Promise<void> {
   logger.info(`dns_internal provider '${moduleId}' deployed — backfilling DNS for all systems`);
 
-  const deployed = db.select().from(modules).all();
+  // ISS-0009: register only DEPLOYED systems, never IMPORTED-but-undeployed
+  // modules (those have a hostname/target_ip configured but nothing serving at
+  // that address — registering an A record for them is a phantom record). A
+  // deployed system is INSTALLED or VERIFIED. The provider itself is already
+  // INSTALLED by the time backfill runs (module-deploy transitions state before
+  // calling this), but we union its id explicitly so the provider's own
+  // self-record is registered even if that transition order ever changes —
+  // critical in daemonless contexts where no dispatcher delivers system.created.
+  const deployed = db
+    .select()
+    .from(modules)
+    .where(or(inArray(modules.state, ['INSTALLED', 'VERIFIED']), eq(modules.id, moduleId)))
+    .all();
   const failures: string[] = [];
 
   // One register per deployed system across all modules — a module with N

package/src/services/dns-registrations.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Unit tests for the DNS registration ledger
+ * (designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md B2): upsert semantics,
+ * the registerHost recording wrapper (success-only), refresh stamping,
+ * and FK-cascade cleanup when a module is removed.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { DnsRegistrarCapability } from '@celilo/capabilities';
+import { eq } from 'drizzle-orm';
+import { type DbClient, getDb } from '../db/client';
+import { modules } from '../db/schema';
+import {
+  listDnsRegistrations,
+  recordDnsRegistration,
+  stampDnsRegistrationsRefreshed,
+  withDnsRegistrationLedger,
+} from './dns-registrations';
+
+describe('dns_registrations ledger', () => {
+  let tempDir: string;
+  let db: DbClient;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'celilo-dnsreg-'));
+    process.env.CELILO_DB_PATH = join(tempDir, 'test.db');
+    db = getDb();
+    for (const id of ['namecheap', 'caddy']) {
+      db.insert(modules)
+        .values({
+          id,
+          name: id,
+          sourcePath: join(tempDir, id),
+          version: '1.0.0',
+          manifestData: { celilo_contract: '1.0', id, name: id, version: '1.0.0' },
+        })
+        .run();
+    }
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+    process.env.CELILO_DB_PATH = undefined;
+  });
+
+  test('record + list roundtrip; upsert replaces ip and consumer', () => {
+    recordDnsRegistration(db, {
+      providerModuleId: 'namecheap',
+      consumerModuleId: 'caddy',
+      fqdn: 'www.lunacycle.net',
+      ip: '198.51.100.7',
+    });
+    recordDnsRegistration(db, {
+      providerModuleId: 'namecheap',
+      consumerModuleId: 'caddy',
+      fqdn: 'www.lunacycle.net',
+      ip: '198.51.100.8',
+    });
+
+    const rows = listDnsRegistrations(db, { providerModuleId: 'namecheap' });
+    expect(rows.length).toBe(1);
+    expect(rows[0].fqdn).toBe('www.lunacycle.net');
+    expect(rows[0].ip).toBe('198.51.100.8');
+    expect(rows[0].consumerModuleId).toBe('caddy');
+    expect(rows[0].refreshedAt).toBeNull();
+  });
+
+  test('stampDnsRegistrationsRefreshed sets refreshedAt for the provider', () => {
+    recordDnsRegistration(db, {
+      providerModuleId: 'namecheap',
+      consumerModuleId: 'caddy',
+      fqdn: 'git.lunacycle.net',
+      ip: null,
+    });
+    stampDnsRegistrationsRefreshed(db, 'namecheap');
+    const [row] = listDnsRegistrations(db, { providerModuleId: 'namecheap' });
+    expect(row.refreshedAt).not.toBeNull();
+  });
+
+  test('rows die with the consumer module (FK cascade)', () => {
+    recordDnsRegistration(db, {
+      providerModuleId: 'namecheap',
+      consumerModuleId: 'caddy',
+      fqdn: 'www.lunacycle.net',
+      ip: '198.51.100.7',
+    });
+    db.delete(modules).where(eq(modules.id, 'caddy')).run();
+    expect(listDnsRegistrations(db).length).toBe(0);
+  });
+
+  test('withDnsRegistrationLedger records successes only', async () => {
+    const calls: string[] = [];
+    const fake: DnsRegistrarCapability = {
+      async registerHost(request) {
+        calls.push(request.fqdn);
+        const success = !request.fqdn.startsWith('fail.');
+        return { success, outputs: {}, duration: 1 };
+      },
+    };
+    const wrapped = withDnsRegistrationLedger(fake, {
+      db,
+      providerModuleId: 'namecheap',
+      consumerModuleId: 'caddy',
+    });
+
+    await wrapped.registerHost({ fqdn: 'www.lunacycle.net', ip: '198.51.100.7' });
+    await wrapped.registerHost({ fqdn: 'fail.lunacycle.net', ip: '198.51.100.7' });
+    await wrapped.registerHost({ fqdn: 'auto.lunacycle.net' });
+
+    expect(calls.length).toBe(3);
+    const rows = listDnsRegistrations(db);
+    const fqdns = rows.map((r) => r.fqdn).sort();
+    expect(fqdns).toEqual(['auto.lunacycle.net', 'www.lunacycle.net']);
+    const auto = rows.find((r) => r.fqdn === 'auto.lunacycle.net');
+    expect(auto?.ip).toBeNull();
+  });
+});

package/src/services/dns-registrations.ts

@@ -0,0 +1,108 @@
+/**
+ * DNS registration ledger operations
+ * (designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md B2/B3).
+ *
+ * The capability loader records every successful
+ * dns_registrar.registerHost here; the run-hook path reads the ledger
+ * back to feed a provider's `refresh_registrations` hook, and `celilo
+ * dns registrations` lists it for the operator. Row lifecycle is FK
+ * cascade — registrations die with their provider or consumer module.
+ */
+
+import type { DnsRegistrarCapability, HookResult } from '@celilo/capabilities';
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { dnsRegistrations } from '../db/schema';
+
+export interface DnsRegistrationRow {
+  fqdn: string;
+  /** null = the provider auto-detected the request's source IP. */
+  ip: string | null;
+  providerModuleId: string;
+  consumerModuleId: string;
+  registeredAt: Date;
+  refreshedAt: Date | null;
+}
+
+export function listDnsRegistrations(
+  db: DbClient,
+  options: { providerModuleId?: string } = {},
+): DnsRegistrationRow[] {
+  const query = db
+    .select({
+      fqdn: dnsRegistrations.fqdn,
+      ip: dnsRegistrations.ip,
+      providerModuleId: dnsRegistrations.providerModuleId,
+      consumerModuleId: dnsRegistrations.consumerModuleId,
+      registeredAt: dnsRegistrations.registeredAt,
+      refreshedAt: dnsRegistrations.refreshedAt,
+    })
+    .from(dnsRegistrations);
+  const rows = options.providerModuleId
+    ? query.where(eq(dnsRegistrations.providerModuleId, options.providerModuleId)).all()
+    : query.all();
+  return rows;
+}
+
+export function recordDnsRegistration(
+  db: DbClient,
+  registration: {
+    providerModuleId: string;
+    consumerModuleId: string;
+    fqdn: string;
+    ip: string | null;
+  },
+): void {
+  db.insert(dnsRegistrations)
+    .values({
+      providerModuleId: registration.providerModuleId,
+      consumerModuleId: registration.consumerModuleId,
+      fqdn: registration.fqdn,
+      ip: registration.ip,
+      registeredAt: new Date(),
+    })
+    .onConflictDoUpdate({
+      target: [dnsRegistrations.providerModuleId, dnsRegistrations.fqdn],
+      set: {
+        consumerModuleId: registration.consumerModuleId,
+        ip: registration.ip,
+        registeredAt: new Date(),
+      },
+    })
+    .run();
+}
+
+/** Stamp every row of a provider as refreshed (successful refresh hook). */
+export function stampDnsRegistrationsRefreshed(db: DbClient, providerModuleId: string): void {
+  db.update(dnsRegistrations)
+    .set({ refreshedAt: new Date() })
+    .where(eq(dnsRegistrations.providerModuleId, providerModuleId))
+    .run();
+}
+
+/**
+ * Wrap a dns_registrar interface so successful registerHost calls are
+ * recorded in the ledger. Failures and MissingProviderInputError
+ * interview throws pass through untouched — only a confirmed
+ * registration earns a row.
+ */
+export function withDnsRegistrationLedger(
+  registrar: DnsRegistrarCapability,
+  ctx: { db: DbClient; providerModuleId: string; consumerModuleId: string },
+): DnsRegistrarCapability {
+  return {
+    ...registrar,
+    async registerHost(request): Promise<HookResult> {
+      const result = await registrar.registerHost(request);
+      if (result.success && request.fqdn) {
+        recordDnsRegistration(ctx.db, {
+          providerModuleId: ctx.providerModuleId,
+          consumerModuleId: ctx.consumerModuleId,
+          fqdn: request.fqdn,
+          ip: request.ip ?? null,
+        });
+      }
+      return result;
+    },
+  };
+}