@celilo/cli 0.5.0-alpha.1 → 0.5.0-alpha.3

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;
+    },
+  };
+}

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

@@ -8,6 +8,7 @@ import {
   readInstalledUnit,
   renderLaunchdPlist,
   renderSystemdUnit,
+  resolveRunAsUser,
   uninstallDaemon,
 } from './events-daemon';
 
@@ -19,6 +20,7 @@ describe('renderSystemdUnit', () => {
       pollMs: 1000,
       concurrency: 4,
       home: '/home/op',
+      scope: 'user',
     });
     expect(out).toContain(
       'ExecStart=/usr/local/bin/celilo events run --poll-ms 1000 --concurrency 4',
@@ -26,6 +28,7 @@ describe('renderSystemdUnit', () => {
     expect(out).toContain('Environment=EVENT_BUS_DB=/var/lib/celilo/events.db');
     expect(out).toContain('Restart=on-failure');
     expect(out).toContain('WantedBy=default.target');
+    expect(out).not.toContain('User=');
   });
 
   it('honors --poll-ms and --concurrency overrides', () => {
@@ -35,9 +38,26 @@ describe('renderSystemdUnit', () => {
       pollMs: 250,
       concurrency: 8,
       home: '/h',
+      scope: 'user',
     });
     expect(out).toContain('--poll-ms 250 --concurrency 8');
   });
+
+  it('system scope sets explicit User= and multi-user.target', () => {
+    const out = renderSystemdUnit({
+      celiloPath: '/usr/local/bin/celilo',
+      busDbPath: '/var/celilo/events.db',
+      pollMs: 1000,
+      concurrency: 4,
+      home: '/root',
+      scope: 'system',
+      runAsUser: 'celilo',
+    });
+    expect(out).toContain('User=celilo');
+    expect(out).toContain('WantedBy=multi-user.target');
+    expect(out).toContain('journalctl -u celilo-events.service');
+    expect(out).not.toContain('journalctl --user');
+  });
 });
 
 describe('renderLaunchdPlist', () => {
@@ -48,6 +68,7 @@ describe('renderLaunchdPlist', () => {
       pollMs: 1000,
       concurrency: 4,
       home: '/Users/op',
+      scope: 'user',
     });
     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>');
@@ -55,6 +76,24 @@ describe('renderLaunchdPlist', () => {
     expect(out).toContain('<string>com.celilo.events</string>');
     expect(out).toContain('<key>RunAtLoad</key>');
     expect(out).toContain('<key>KeepAlive</key>');
+    expect(out).not.toContain('<key>UserName</key>');
+  });
+
+  it('system scope sets UserName and logs under /Library/Logs', () => {
+    const out = renderLaunchdPlist({
+      celiloPath: '/c',
+      busDbPath: '/db',
+      pollMs: 1000,
+      concurrency: 4,
+      home: '/Users/op',
+      scope: 'system',
+      runAsUser: 'celilo',
+    });
+    expect(out).toContain('<key>UserName</key>');
+    expect(out).toContain('<string>celilo</string>');
+    expect(out).toContain('<string>/Library/Logs/celilo-events.out.log</string>');
+    expect(out).toContain('<string>/Library/Logs/celilo-events.err.log</string>');
+    expect(out).not.toContain('/Users/op/Library/Logs');
   });
 });
 
@@ -69,6 +108,24 @@ describe('getDaemonUnitPath', () => {
       '/Users/op/Library/LaunchAgents/com.celilo.events.plist',
     );
   });
+  it('returns the system paths for system scope', () => {
+    expect(getDaemonUnitPath('linux', '/home/op', 'system')).toBe(
+      '/etc/systemd/system/celilo-events.service',
+    );
+    expect(getDaemonUnitPath('darwin', '/Users/op', 'system')).toBe(
+      '/Library/LaunchDaemons/com.celilo.events.plist',
+    );
+  });
+});
+
+describe('resolveRunAsUser', () => {
+  it('honors an explicit override', () => {
+    expect(resolveRunAsUser('/var/celilo/events.db', 'celilo')).toBe('celilo');
+  });
+  it('falls back to the current user when the state dir is missing', () => {
+    const me = resolveRunAsUser('/no/such/dir/events.db');
+    expect(me.length).toBeGreaterThan(0);
+  });
 });
 
 describe('installDaemon / uninstallDaemon roundtrip', () => {
@@ -99,6 +156,8 @@ describe('installDaemon / uninstallDaemon roundtrip', () => {
       busDbPath: '/var/lib/celilo/events.db',
     });
     expect(existsSync(installed.unitPath)).toBe(true);
+    expect(installed.scope).toBe('user');
+    expect(installed.runAsUser).toBeUndefined();
     expect(installed.unitPath).toBe(join(home, '.config/systemd/user/celilo-events.service'));
     expect(installed.nextSteps[0]).toContain('systemctl --user daemon-reload');