@celilo/cli 1.2.0 → 1.4.0

package/src/ipam/allocator.test.ts

@@ -25,6 +25,7 @@ import {
   reserveVMID,
   unreserveIP,
   unreserveVMID,
+  updateReservationReason,
 } from './allocator';
 
 describe('IPAM Allocator', () => {
@@ -295,6 +296,43 @@ describe('IPAM Allocator', () => {
       const reservations = await listReservations(db);
       expect(reservations).toHaveLength(2);
     });
+
+    // Editing in place, rather than include-then-exclude: that dance drops the
+    // row for a moment and can race an allocation into the held address.
+    test('should edit a reservation reason in place', async () => {
+      await reserveIP('10.0.10.50', 'dmz', 'LB', null, db);
+
+      const updated = await updateReservationReason('10.0.10.50', 'dmz', 'Retired LB', db);
+
+      expect(updated).toBe(true);
+      const reservations = await db.select().from(ipReservations).all();
+      expect(reservations).toHaveLength(1);
+      expect(reservations[0].reason).toBe('Retired LB');
+    });
+
+    test('should leave the address held while editing', async () => {
+      await reserveIP('10.0.10.50', 'dmz', 'LB', null, db);
+
+      await updateReservationReason('10.0.10.50', 'dmz', 'Retired LB', db);
+
+      expect(await isIPAvailable('10.0.10.50', 'dmz', db)).toBe(false);
+    });
+
+    test('should edit only the addressed row', async () => {
+      await reserveIP('10.0.10.50', 'dmz', 'LB', null, db);
+      await reserveIP('10.0.10.51', 'dmz', 'LB', null, db);
+
+      await updateReservationReason('10.0.10.50', 'dmz', 'Retired LB', db);
+
+      const reasons = (await listReservations(db)).map((r) => r.reason);
+      expect(reasons.sort()).toEqual(['LB', 'Retired LB']);
+    });
+
+    test('should report when no reservation exists to edit', async () => {
+      const updated = await updateReservationReason('10.0.10.99', 'dmz', 'Nothing there', db);
+
+      expect(updated).toBe(false);
+    });
   });
 
   describe('getAllocatedIPsInSubnet', () => {

package/src/ipam/allocator.ts

@@ -4,7 +4,7 @@
  * Prevents conflicts and tracks allocations
  */
 
-import { and, eq } from 'drizzle-orm';
+import { and, eq, like, or } from 'drizzle-orm';
 import type { BunSQLiteDatabase } from 'drizzle-orm/bun-sqlite';
 import type { DbClient } from '../db/client';
 import { ipAllocations, ipReservations, systemConfig, vmidReservations } from '../db/schema';
@@ -246,6 +246,68 @@ export async function unreserveIP(
     .where(and(eq(ipReservations.ipStart, ip), eq(ipReservations.zone, zone)));
 }
 
+/**
+ * Release every ingress-IP reservation a module holds (celilo#892).
+ *
+ * `ensureIngressIps` reserves an `internal`-subnet address at generate time and
+ * nothing released it at removal, so each install/remove cycle permanently
+ * burned one address from the static range — with no error and no way to tell
+ * the dead row from the live one, since both carry the same reason string.
+ *
+ * TWO reason formats exist in live databases and both must go: the current
+ * `ingress:<module>:<variable>` (since celilo#879) and the pre-879
+ * `dns-ingress:<module>`, which celilo-mgr still holds. Matching only the
+ * current one would leave the installed base leaking.
+ *
+ * Deletion is by REASON, not by the stored config value: a module can hold an
+ * ingress reservation with no `ip_allocations` row (it deploys onto a machine
+ * rather than a container), and the config rows are about to be cascade-deleted
+ * anyway. The reason string is the only thing that names the owner.
+ *
+ * @returns The addresses released, for reporting.
+ */
+export async function releaseIngressReservations(
+  moduleId: string,
+  db: DbOrTransaction,
+): Promise<string[]> {
+  // Module IDs are validated kebab-case, so they carry no LIKE wildcards.
+  const ownedByModule = or(
+    like(ipReservations.reason, `ingress:${moduleId}:%`),
+    eq(ipReservations.reason, `dns-ingress:${moduleId}`),
+  );
+
+  const held = await db.select().from(ipReservations).where(ownedByModule).all();
+  if (held.length === 0) return [];
+
+  await db.delete(ipReservations).where(ownedByModule);
+
+  return held.map((r: typeof ipReservations.$inferSelect) => r.ipStart);
+}
+
+/**
+ * Change an existing reservation's reason in place.
+ *
+ * The alternative — include then re-exclude — drops the row for a moment and
+ * can race an allocation into the address it was holding.
+ *
+ * @returns False when no reservation exists for that IP in that zone.
+ */
+export async function updateReservationReason(
+  ipStart: string,
+  zone: IpamZone,
+  reason: string,
+  db: DbOrTransaction,
+): Promise<boolean> {
+  const ip = stripCIDR(ipStart);
+  const match = and(eq(ipReservations.ipStart, ip), eq(ipReservations.zone, zone));
+
+  const existing = await db.select().from(ipReservations).where(match).all();
+  if (existing.length === 0) return false;
+
+  await db.update(ipReservations).set({ reason }).where(match);
+  return true;
+}
+
 /**
  * List all IP reservations
  */

package/src/ipam/auto-allocator.ts

@@ -10,6 +10,7 @@
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { ipAllocations } from '../db/schema';
+import { releaseIngressReservations } from './allocator';
 
 export interface IpamAllocation {
   moduleId: string;
@@ -258,6 +259,12 @@ export async function allocateForModule(
  * @returns True if allocation was removed, false if none existed
  */
 export async function deallocateForModule(moduleId: string, db: DbClient): Promise<boolean> {
+  // Ingress reservations are released FIRST and unconditionally (celilo#892).
+  // A module can hold one with no `ip_allocations` row at all — it deploys onto
+  // a machine rather than a celilo-provisioned container — so releasing it
+  // after the early return below would skip exactly the modules that leak.
+  await releaseIngressReservations(moduleId, db);
+
   // Check if allocation exists before deleting
   const existing = getAllocation(moduleId, db);
   if (!existing) {

package/src/manifest/contracts/v1.ts

@@ -261,6 +261,41 @@ export const V1_HOOKS: ContractHooks = {
     inputs: {},
     outputs: {},
   },
+  /**
+   * Report what a tunnel/interface is ACTUALLY carrying, diffed against what
+   * celilo's config says it should carry.
+   *
+   * Deliberately a read of the live thing rather than of celilo's own record.
+   * celilo#928 was exactly a divergence between the two — a device present in
+   * config, rendered as active by a UI, and absent from the interface — and
+   * diagnosing it needed a screenshot and a root SSH because nothing celilo
+   * offered could tell the two apart. A hook that reported the record would
+   * have reproduced the misleading signal rather than exposing it.
+   *
+   * No structured outputs: it reports through the logger, so an operator and an
+   * agent read the same thing.
+   */
+  list_peers: {
+    inputs: {},
+    outputs: {},
+  },
+  /**
+   * Re-assert a module's desired peer set onto the thing carrying it, on a
+   * timer, without an operator.
+   *
+   * The counterpart to applying on change: apply-on-change bounds latency, this
+   * bounds how long ANY divergence can persist — including drift nobody
+   * predicted (a hand-edit on the box, an apply that failed, a record written
+   * before the applying code existed). celilo#934, where the module could
+   * already SEE the drift in `health_check` and had nowhere to act on it.
+   *
+   * A converge that changes nothing must be silent, so the log stays a record
+   * of things happening.
+   */
+  reconcile_peers: {
+    inputs: {},
+    outputs: {},
+  },
   /**
    * Build-bus upstream publish hook. The executor passes the
    * PublishEvent fields as env vars (CELILO_EVENT_PAYLOAD,

package/src/manifest/schema.ts

@@ -364,6 +364,8 @@ const LIFECYCLE_HOOK_SCHEMAS = {
   refresh_registrations: LifecycleHookSchema.optional(),
   reassert_dhcp_dns: LifecycleHookSchema.optional(),
   reconcile_clients: LifecycleHookSchema.optional(),
+  list_peers: LifecycleHookSchema.optional(),
+  reconcile_peers: LifecycleHookSchema.optional(),
 } satisfies Record<HookName, z.ZodTypeAny>;
 
 /**

package/src/policy/module-business-baseline.ts

@@ -11,6 +11,19 @@
  * refer to that document's sections 1-4 — read the row before changing a line
  * here.
  *
+ * **Every debt entry names the issue tracking its removal.** The audit is a
+ * ruling; the issues are the work. If you are here because the gate went red,
+ * the issue in the entry's `why` is where the fix belongs:
+ *
+ *   #937  the hardcoded well-known registry + its duplicate zone table
+ *   #938  the loader's capName branches, CAPABILITY_MODULE_MAP, isFirewallModule
+ *   #939  the four provider-domain tables
+ *   #940  the Caddyfile generator + interface classification in the shared package
+ *   #941  core shelling iptables-save
+ *   #943  the three capability-named CLI verbs
+ *   #944  core shelling wg pubkey
+ *   #945  three core primitives gated on one capability (generalise, don't move)
+ *
  * Two kinds of entry live here and they must not be confused:
  *
  *   - **Debt** — the default. It is here because it is wrong and not yet fixed.
@@ -25,6 +38,9 @@
  * each belongs to. Scan A asserts the tagged set EQUALS this map — not that it
  * is empty. These four exist today (audit T1, T2, T3, T6) and Phase 1 migrates
  * nothing; an assertion that core holds none would be red the day it landed.
+ *
+ * Tracked by #939. Migrating them keeps the ownership CLAIM in core — dropping
+ * it is the mistake that made `dns_registration_consumers` necessary (#626).
  */
 export const CAPABILITY_OWNED_TABLES: Readonly<Record<string, string>> = {
   web_routes: 'public_web',
@@ -68,25 +84,25 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     file: 'apps/celilo/src/capabilities/well-known.ts',
     capability: 'dhcp_server',
     count: 1,
-    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2',
+    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2 (#937)',
   },
   {
     file: 'apps/celilo/src/capabilities/well-known.ts',
     capability: 'dns_internal',
     count: 1,
-    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2',
+    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2 (#937)',
   },
   {
     file: 'apps/celilo/src/capabilities/well-known.ts',
     capability: 'dns_registrar',
     count: 1,
-    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2',
+    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2 (#937)',
   },
   {
     file: 'apps/celilo/src/capabilities/well-known.ts',
     capability: 'public_web',
     count: 1,
-    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2',
+    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2 (#937)',
   },
   {
     file: 'apps/celilo/src/cli/commands/notify-config.ts',
@@ -98,91 +114,91 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     file: 'apps/celilo/src/cli/commands/token.ts',
     capability: 'idp',
     count: 1,
-    why: 'X7 — a top-level CLI verb backed by the idp capability; Phase 5',
+    why: 'X7 — a top-level CLI verb backed by the idp capability; Phase 5 (#943)',
   },
   {
     file: 'apps/celilo/src/cli/completion.ts',
     capability: 'firewall',
     count: 3,
-    why: 'X6 — tab completion for the capability-named CLI verbs; falls out with X6',
+    why: 'X6 — tab completion for the capability-named CLI verbs; falls out with X6 (#943)',
   },
   {
     file: 'apps/celilo/src/cli/index.ts',
     capability: 'firewall',
     count: 2,
-    why: 'X5/X6/X7 — the command tree wiring the capability-named CLI verbs; Phase 5',
+    why: 'X5/X6/X7 — the command tree wiring the capability-named CLI verbs; Phase 5 (#943)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'control_plane_vpn',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'dhcp_server',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'dns_internal',
     count: 3,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'dns_registrar',
     count: 4,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'external_web',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'firewall',
     count: 12,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'idp',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'notification',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'private_web',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'public_web',
     count: 8,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'registry_publish',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'source_forge',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/manifest/validate.ts',
@@ -212,49 +228,49 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     file: 'apps/celilo/src/services/dns-provider-backfill.ts',
     capability: 'dns_internal',
     count: 2,
-    why: 'S3 — the generic event-replay half is core; the dns_internal gate is not',
+    why: 'S3 — the generic event-replay half is core; the dns_internal gate is not (#945)',
   },
   {
     file: 'apps/celilo/src/services/firewall-reach.ts',
     capability: 'firewall',
     count: 1,
-    why: 'S8 — core shells iptables-save at a remote box and parses the output',
+    why: 'S8 — core shells iptables-save at a remote box and parses the output (#941)',
   },
   {
     file: 'apps/celilo/src/services/infrastructure-selector.ts',
     capability: 'firewall',
     count: 1,
-    why: 'S15 — isFirewallModule hardcodes a placement rule the manifest should declare',
+    why: 'S15 — isFirewallModule hardcodes a placement rule the manifest should declare (#938)',
   },
   {
     file: 'apps/celilo/src/services/module-deploy.ts',
     capability: 'firewall',
     count: 2,
-    why: "S16 — two more copies of S15's decision; fixing S15 removes all three",
+    why: "S16 — two more copies of S15's decision; fixing S15 removes all three (#938)",
   },
   {
     file: 'apps/celilo/src/services/public-web-republish.ts',
     capability: 'public_web',
     count: 1,
-    why: "S2 — encodes caddy's redeploy behaviour; generalise to a provider-declared re-assert signal",
+    why: "S2 — encodes caddy's redeploy behaviour; generalise to a provider-declared re-assert signal (#945)",
   },
   {
     file: 'apps/celilo/src/services/zone-policy.ts',
     capability: 'public_web',
     count: 1,
-    why: 'S13 — ZONE_REQUIREMENTS, a second hand-maintained copy of well-known.ts; Phase 2',
+    why: 'S13 — ZONE_REQUIREMENTS, a second hand-maintained copy of well-known.ts; Phase 2 (#937)',
   },
   {
     file: 'apps/celilo/src/templates/generator.ts',
     capability: 'dns_internal',
     count: 1,
-    why: 'X4 — declaration-driven and the model for the rest; only the error string names the capability',
+    why: 'X4 — declaration-driven and the model for the rest; only the error string names the capability (#945)',
   },
   {
     file: 'apps/celilo/src/variables/context.ts',
     capability: 'dns_internal',
     count: 1,
-    why: 'X3 — reaches capabilitiesMap.dns_internal by name; should read a declared field (X4 is the model)',
+    why: 'X3 — reaches capabilitiesMap.dns_internal by name; should read a declared field (X4 is the model) (#945)',
   },
   {
     file: 'packages/capabilities/src/capability-contract.ts',
@@ -344,13 +360,13 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     file: 'packages/capabilities/src/public-web.ts',
     capability: 'public_web',
     count: 1,
-    why: "X8 — generateCaddyfile renders caddy's complete config from the shared package; Phase 5",
+    why: "X8 — generateCaddyfile renders caddy's complete config from the shared package; Phase 5 (#940)",
   },
   {
     file: 'packages/capabilities/src/utils.ts',
     capability: 'public_web',
     count: 3,
-    why: 'X8 — shared helpers that name the capability they serve; moves with X8 in Phase 5',
+    why: 'X8 — shared helpers that name the capability they serve; moves with X8 in Phase 5 (#940)',
   },
 ];
 
@@ -368,17 +384,17 @@ export const SERVICE_FILENAME_BASELINE: readonly ServiceFilenameRow[] = [
   {
     file: 'apps/celilo/src/services/dns-internal-records.ts',
     capability: 'dns_internal',
-    why: 'S5 — the store for T6; moves with the table in Phase 4',
+    why: 'S5 — the store for T6; moves with the table in Phase 4 (#939)',
   },
   {
     file: 'apps/celilo/src/services/firewall-reach.ts',
     capability: 'firewall',
-    why: 'S8 — core reaching into one provider implementation',
+    why: 'S8 — core reaching into one provider implementation (#941)',
   },
   {
     file: 'apps/celilo/src/services/public-web-republish.ts',
     capability: 'public_web',
-    why: "S2 — named for one provider's redeploy behaviour",
+    why: "S2 — named for one provider's redeploy behaviour (#945)",
   },
 ];
 
@@ -387,18 +403,18 @@ export const PROVIDER_LITERAL_BASELINE: readonly ProviderLiteralRow[] = [
     file: 'apps/celilo/src/secrets/generators.ts',
     literal: 'wg pubkey',
     count: 1,
-    why: 'X11 — core shells `wg pubkey` to derive a key, and tells the operator to brew install wireguard-tools',
+    why: 'X11 — core shells `wg pubkey` to derive a key, and tells the operator to brew install wireguard-tools (#944)',
   },
   {
     file: 'apps/celilo/src/services/firewall-reach.ts',
     literal: 'iptables-save',
     count: 1,
-    why: "S8 — core parses a firewall's live ruleset; implementation-specific, not merely capability-specific",
+    why: "S8 — core parses a firewall's live ruleset; implementation-specific, not merely capability-specific (#941)",
   },
   {
     file: 'packages/capabilities/src/public-web.ts',
     literal: '/srv/www',
     count: 4,
-    why: "X8 — the Caddyfile generator knows caddy's on-disk asset layout",
+    why: "X8 — the Caddyfile generator knows caddy's on-disk asset layout (#940)",
   },
 ];