@celilo/cli 0.20.0 → 0.22.0

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

@@ -33,6 +33,12 @@ export interface RunNamedHookOptions {
   debug?: boolean;
   /** Hook inputs (key=value pairs from the CLI, etc.). Default: empty. */
   inputs?: Record<string, unknown>;
+  /**
+   * Total timeout for this invocation (ms). A bus delivery passes the
+   * subscription's declared `timeout_ms` (celilo#622); omitted, the manifest
+   * hook's own `timeout` or the executor default applies.
+   */
+  timeoutMs?: number;
 }
 
 export interface RunNamedHookResult extends HookResult {
@@ -138,7 +144,6 @@ export async function runNamedHook(
   if (hookName === 'refresh_registrations') {
     const registrations = listDnsRegistrations(db, { providerModuleId: moduleId }).map((r) => ({
       fqdn: r.fqdn,
-      ip: r.ip,
     }));
     inputs = { ...inputs, registrations };
   }
@@ -157,6 +162,7 @@ export async function runNamedHook(
       capabilities: capabilityFunctions,
       requiredCapabilities,
       systems: getModuleSystems(moduleId, db),
+      timeoutMs: options.timeoutMs,
     },
   );
 

package/src/hooks/test-fixtures/silent-hook.ts

@@ -0,0 +1,20 @@
+/**
+ * Test fixture: a hook that logs once and then works in silence, the shape
+ * that celilo#622 is about (namecheap's ddns refresh logs per name, so one
+ * slow upstream response is a long gap between log lines).
+ *
+ * Sleeps `ctx.config.silent_ms` so a test can put the silence on either side
+ * of an idle bound.
+ */
+
+import { defineHook } from '@celilo/capabilities';
+
+export default defineHook({
+  hook: 'container_created',
+  requires: [],
+  handler: async (ctx) => {
+    ctx.logger.info('Starting, then going quiet');
+    await new Promise((r) => setTimeout(r, Number(ctx.config.silent_ms ?? 0)));
+    return {};
+  },
+});

package/src/module/packaging/build.ts

@@ -210,6 +210,20 @@ export async function buildModule(options: ModuleBuildOptions): Promise<ModuleBu
       console.log('Staging source for build (no package.json, using file copy)...');
       cpSync(sourceDir, buildDir, {
         recursive: true,
+        // MATERIALISE symlinks. `modules/*/scripts` depends on
+        // `@celilo/capabilities` by `file:` path so an in-repo module builds
+        // against the LIVE workspace rather than the last published tarball —
+        // without which a module cannot consume a capability added in the same
+        // PR, and `check:modules` typechecks every module against a version
+        // that no longer matches the source it ships beside.
+        //
+        // bun installs a `file:` dep as a tree of symlinks into the monorepo.
+        // Copied as symlinks they would point at a path that does not exist on
+        // the target, and because `scripts/node_modules` would still LOOK
+        // present, `installScriptDependencies` skips its `bun install` and the
+        // hooks fail at runtime with unresolvable imports. Dereferencing here
+        // is what keeps the shipped closure a real, self-contained tree.
+        dereference: true,
         filter: (src) => !shouldExclude(relative(sourceDir, src)),
       });
     }

package/src/services/alerting/builtin-monitors.ts

@@ -25,6 +25,9 @@ import { type FailingKey, builtinAlertKey } from './keys';
 const TARGET_KIND_BY_CATEGORY: Partial<Record<DriftCategory, string>> = {
   machines_reachable: 'machine',
   disk_space: 'machine',
+  // Subject is an FQDN, which is neither a machine nor a module: a served
+  // name can outlive any single module that asked for it.
+  public_dns: 'hostname',
   transport_reads: 'module',
   services_reachable: 'service',
   services_credentials: 'service',

package/src/services/alerting/builtin-source.ts

@@ -18,9 +18,16 @@ import { loadBackupAuditInfo } from '../audit/backup-source';
 import { auditBackups } from '../audit/backups';
 import { auditDiskSpace } from '../audit/disk-space';
 import { auditMachinesReachable } from '../audit/machines-reachable';
+import { auditPublicDns } from '../audit/public-dns';
+import {
+  loadPublicDnsEvidence,
+  loadPublicDnsRecords,
+  savePublicDnsEvidence,
+} from '../audit/public-dns-source';
 import type { DriftCategory, DriftFinding } from '../audit/types';
 import { probeDiskUsage } from '../disk-probe';
 import { probeMachines } from '../machine-probe';
+import { createPublicDnsProbe, loadPublicDnsProbeSettings } from '../public-dns-probe';
 
 /** Categories a monitor can currently schedule. */
 export const SCHEDULABLE_BUILTIN_CHECKS: readonly DriftCategory[] = [
@@ -28,6 +35,7 @@ export const SCHEDULABLE_BUILTIN_CHECKS: readonly DriftCategory[] = [
   'backups',
   'disk_space',
   'abandoned_operations',
+  'public_dns',
 ];
 
 export function isSchedulableBuiltin(category: string): category is DriftCategory {
@@ -58,6 +66,21 @@ export async function runBuiltinCheckForMonitor(
     return auditAbandonedOperations({ records: loadAbandonedOperations(db) });
   }
 
+  // One DNS query per ledger name plus one HTTP echo, all bounded — cheap
+  // enough for a scheduled check, and the only one of these that looks at the
+  // fleet from OUTSIDE. It is the only place `undetermined` counters advance,
+  // which is why the check has to be scheduled and not merely available to
+  // `celilo system audit`: consecutive absence of evidence is a finding, and
+  // nothing is consecutive if it only runs when an operator asks.
+  if (category === 'public_dns') {
+    return auditPublicDns({
+      records: loadPublicDnsRecords(db),
+      probe: createPublicDnsProbe(loadPublicDnsProbeSettings(db)),
+      evidence: loadPublicDnsEvidence(db),
+      saveEvidence: (evidence) => savePublicDnsEvidence(db, evidence),
+    });
+  }
+
   throw new Error(
     `Built-in check "${category}" is not schedulable yet. Schedulable: ${SCHEDULABLE_BUILTIN_CHECKS.join(', ')}.`,
   );

package/src/services/audit/index.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from 'bun:test';
 import type { DbClient } from '../../db/client';
 import { runAudit } from './index';
+import { unusedPublicDnsProbe } from './public-dns';
 
 const fakeDb = {} as DbClient;
 
@@ -35,6 +36,7 @@ const emptyDeps = {
   machinesReachable: { results: [] },
   transportReads: { statuses: [], now: new Date(), staleAfterMs: 30 * 60_000 },
   trustedSources: { firewalls: [] },
+  publicDns: { records: [], probe: unusedPublicDnsProbe },
 };
 
 describe('runAudit', () => {

package/src/services/audit/index.ts

@@ -21,6 +21,7 @@ import { type HealthAuditDeps, auditHealth } from './health';
 import { type MachinesReachableAuditDeps, auditMachinesReachable } from './machines-reachable';
 import { type ModuleConfigsAuditDeps, auditModuleConfigs } from './module-configs';
 import { type ModuleVersionsAuditDeps, auditModuleVersions } from './module-versions';
+import { type PublicDnsAuditDeps, auditPublicDns } from './public-dns';
 import { type SchemaAuditDeps, auditSchema } from './schema';
 import { type SecretsDecryptableAuditDeps, auditSecretsDecryptable } from './secrets-decryptable';
 import {
@@ -59,6 +60,7 @@ export interface AuditDeps {
   secretsDecryptable: SecretsDecryptableAuditDeps;
   servicesReachable: ServicesReachableAuditDeps;
   machinesReachable: MachinesReachableAuditDeps;
+  publicDns: PublicDnsAuditDeps;
   transportReads: TransportReadsAuditDeps;
   trustedSources: TrustedSourcesAuditDeps;
   /** Defaults to `Date.now()`-based ISO string. */
@@ -114,6 +116,7 @@ export async function runAudit(
     wrap('secrets_decryptable', auditSecretsDecryptable(deps.secretsDecryptable)),
     wrap('services_reachable', auditServicesReachable(deps.servicesReachable)),
     wrap('machines_reachable', auditMachinesReachable(deps.machinesReachable)),
+    wrap('public_dns', auditPublicDns(deps.publicDns)),
     wrap('transport_reads', auditTransportReads(deps.transportReads)),
     wrap('trusted_sources', auditTrustedSources(deps.trustedSources)),
   ]);

package/src/services/audit/public-dns-source.ts

@@ -0,0 +1,55 @@
+/**
+ * DB-facing half of the `public_dns` check: the ledger names it watches and
+ * the consecutive-undetermined counters it carries between runs.
+ *
+ * Split from `public-dns.ts` so the audit itself stays a pure function over an
+ * injected probe — the counters are the only state it has, and a check that
+ * owned its own storage could not be tested without one.
+ */
+
+import type { DbClient } from '../../db/client';
+import { publicDnsEvidence } from '../../db/schema';
+import { listDnsRegistrations } from '../dns-registrations';
+import type { PublicDnsEvidence, PublicDnsRecord } from './public-dns';
+
+/**
+ * Every name celilo has asserted publicly. `lastAssertedAt` is when the fleet
+ * last told the registrar about it — the point the record's own TTL is
+ * measured from, so a divergence inside one TTL reads as propagation.
+ */
+export function loadPublicDnsRecords(db: DbClient): PublicDnsRecord[] {
+  return listDnsRegistrations(db).map((row) => ({
+    fqdn: row.fqdn,
+    companion: row.companion,
+    lastAssertedAt: row.refreshedAt ?? row.registeredAt,
+  }));
+}
+
+export function loadPublicDnsEvidence(db: DbClient): PublicDnsEvidence[] {
+  return db
+    .select({
+      subject: publicDnsEvidence.subject,
+      undeterminedRuns: publicDnsEvidence.undeterminedRuns,
+    })
+    .from(publicDnsEvidence)
+    .all();
+}
+
+/**
+ * Replace the whole set. A subject that produced evidence this run is absent
+ * from `evidence` and its counter goes with it — that is what makes the count
+ * consecutive rather than cumulative.
+ */
+export function savePublicDnsEvidence(db: DbClient, evidence: PublicDnsEvidence[]): void {
+  db.delete(publicDnsEvidence).run();
+  if (evidence.length === 0) return;
+  db.insert(publicDnsEvidence)
+    .values(
+      evidence.map((e) => ({
+        subject: e.subject,
+        undeterminedRuns: e.undeterminedRuns,
+        lastCheckedAt: new Date(),
+      })),
+    )
+    .run();
+}

package/src/services/audit/public-dns.test.ts

@@ -0,0 +1,209 @@
+/**
+ * The recurrence gate celilo#626 asks for, at the layer it can actually be
+ * asserted: feed the check a public record that diverges from where the fleet
+ * really is, and it must say so.
+ *
+ * Every check celilo had answered "healthy" for the nine days five public
+ * names were dark. This is the one that could not have.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  type IngressObservation,
+  type PublicDnsEvidence,
+  type PublicDnsProbe,
+  type PublicResolution,
+  auditPublicDns,
+} from './public-dns';
+
+const FLEET_INGRESS = '71.36.123.107';
+/** The address the fleet moved off, and kept publishing for nine days. */
+const DEAD_ADDRESS = '71.36.112.98';
+
+const LONG_AGO = new Date('2026-08-01T00:00:00Z');
+const NOW = new Date('2026-08-06T00:00:00Z');
+
+function probe(options: {
+  ingress?: IngressObservation;
+  answers?: Record<string, PublicResolution>;
+  fallback?: PublicResolution;
+}): PublicDnsProbe {
+  return {
+    resolver: '1.1.1.1',
+    echoService: 'https://echo.example',
+    async observeIngress() {
+      return options.ingress ?? { kind: 'observed', ip: FLEET_INGRESS };
+    },
+    async resolve(fqdn) {
+      return (
+        options.answers?.[fqdn] ??
+        options.fallback ?? { kind: 'answer', ip: FLEET_INGRESS, ttlSeconds: 180 }
+      );
+    },
+  };
+}
+
+function declared(fqdn: string, lastAssertedAt = LONG_AGO) {
+  return { fqdn, companion: false, lastAssertedAt };
+}
+
+describe('auditPublicDns', () => {
+  test('a record pointing at an address the fleet no longer holds is a finding', async () => {
+    const findings = await auditPublicDns({
+      records: [declared('apt.celilo.computer')],
+      probe: probe({
+        answers: {
+          'apt.celilo.computer': { kind: 'answer', ip: DEAD_ADDRESS, ttlSeconds: 180 },
+        },
+      }),
+      now: NOW,
+    });
+
+    expect(findings.length).toBe(1);
+    expect(findings[0].code).toBe('public_dns_stale');
+    expect(findings[0].subject).toBe('apt.celilo.computer');
+    // The finding has to name both addresses; "DNS is wrong" is not actionable.
+    expect(findings[0].message).toContain(DEAD_ADDRESS);
+    expect(findings[0].message).toContain(FLEET_INGRESS);
+  });
+
+  test('a record that agrees with the fleet is silent', async () => {
+    const findings = await auditPublicDns({
+      records: [declared('git.celilo.computer')],
+      probe: probe({}),
+      now: NOW,
+    });
+    expect(findings).toEqual([]);
+  });
+
+  // ── Hysteresis: propagation is not a fault ────────────────────────────────
+  test('divergence inside the record TTL is propagation, not a finding', async () => {
+    const assertedSecondsAgo = 60;
+    const findings = await auditPublicDns({
+      records: [
+        declared('git.celilo.computer', new Date(NOW.getTime() - assertedSecondsAgo * 1000)),
+      ],
+      probe: probe({
+        answers: {
+          'git.celilo.computer': { kind: 'answer', ip: DEAD_ADDRESS, ttlSeconds: 180 },
+        },
+      }),
+      now: NOW,
+    });
+    // An ISP re-lease produces exactly this for up to one TTL. Alerting here
+    // would page on every re-lease, and a check nobody trusts is not a check.
+    expect(findings).toEqual([]);
+  });
+
+  test('the same divergence once the TTL has elapsed IS a finding', async () => {
+    const findings = await auditPublicDns({
+      records: [declared('git.celilo.computer', new Date(NOW.getTime() - 181 * 1000))],
+      probe: probe({
+        answers: {
+          'git.celilo.computer': { kind: 'answer', ip: DEAD_ADDRESS, ttlSeconds: 180 },
+        },
+      }),
+      now: NOW,
+    });
+    expect(findings.map((f) => f.code)).toEqual(['public_dns_stale']);
+  });
+
+  // ── Missing evidence is louder than absent evidence ───────────────────────
+  test('one undetermined run stays quiet', async () => {
+    const findings = await auditPublicDns({
+      records: [declared('git.celilo.computer')],
+      probe: probe({ ingress: { kind: 'undetermined', reason: 'ECONNREFUSED' } }),
+      now: NOW,
+    });
+    expect(findings).toEqual([]);
+  });
+
+  test('consecutive undetermined runs become their own finding', async () => {
+    let evidence: PublicDnsEvidence[] = [];
+    const run = () =>
+      auditPublicDns({
+        records: [declared('git.celilo.computer')],
+        probe: probe({ ingress: { kind: 'undetermined', reason: 'ECONNREFUSED' } }),
+        evidence,
+        saveEvidence: (next) => {
+          evidence = next;
+        },
+        now: NOW,
+      });
+
+    expect(await run()).toEqual([]);
+    expect(await run()).toEqual([]);
+    const findings = await run();
+
+    expect(findings.map((f) => f.code)).toEqual(['public_dns_unverifiable']);
+    // Distinguishable from "the site is unreachable" — this says nothing is
+    // currently checking, which is the state the outage hid behind.
+    expect(findings[0].message).toContain('unverifiable');
+  });
+
+  test('a run that obtained evidence resets the count', async () => {
+    let evidence: PublicDnsEvidence[] = [];
+    const save = (next: PublicDnsEvidence[]) => {
+      evidence = next;
+    };
+    const args = (ingress?: IngressObservation) => ({
+      records: [declared('git.celilo.computer')],
+      probe: probe({ ingress }),
+      evidence,
+      saveEvidence: save,
+      now: NOW,
+    });
+
+    await auditPublicDns(args({ kind: 'undetermined', reason: 'ECONNREFUSED' }));
+    await auditPublicDns(args({ kind: 'undetermined', reason: 'ECONNREFUSED' }));
+    await auditPublicDns(args());
+    expect(evidence).toEqual([]);
+
+    expect(await auditPublicDns(args({ kind: 'undetermined', reason: 'ECONNREFUSED' }))).toEqual(
+      [],
+    );
+  });
+
+  // ── Companions: best effort must not mean silent ──────────────────────────
+  test('an unclaimed companion is reported with the manual registrar step', async () => {
+    const findings = await auditPublicDns({
+      records: [{ fqdn: 'www.peterbanka.org', companion: true, lastAssertedAt: LONG_AGO }],
+      probe: probe({
+        // The parked placeholder Namecheap keeps serving after reporting
+        // ErrCount 0 for an update it never applied (design.md D3).
+        answers: { 'www.peterbanka.org': { kind: 'answer', ip: '1.2.23.4', ttlSeconds: 1799 } },
+      }),
+      now: NOW,
+    });
+
+    expect(findings.map((f) => f.code)).toEqual(['public_dns_companion_unclaimed']);
+    expect(findings[0].remediation).toContain('Dynamic DNS');
+  });
+
+  test('a name with no public record at all is a finding', async () => {
+    const findings = await auditPublicDns({
+      records: [declared('nexus.lunacycle.net')],
+      probe: probe({ fallback: { kind: 'no_record' } }),
+      now: NOW,
+    });
+    expect(findings.map((f) => f.code)).toEqual(['public_dns_missing']);
+  });
+
+  test('an empty ledger never touches the network', async () => {
+    const findings = await auditPublicDns({
+      records: [],
+      probe: {
+        resolver: 'x',
+        echoService: 'y',
+        observeIngress() {
+          throw new Error('probed with nothing to check');
+        },
+        resolve() {
+          throw new Error('probed with nothing to check');
+        },
+      },
+      now: NOW,
+    });
+    expect(findings).toEqual([]);
+  });
+});