@celilo/cli 1.5.0 → 1.7.0

package/src/services/provider-arrival.ts

@@ -0,0 +1,213 @@
+/**
+ * Re-running a provider's consumers when that provider arrives
+ * (openspec/changes/capability-owned-tables, stage 1).
+ *
+ * celilo handled one side of the capability relationship generically and the
+ * other by hand. A consumer leaving goes through `consumer-cleanup.ts`, which
+ * finds every provider it used and calls each one's `on_consumer_removed` with
+ * no capability names in the dispatch. A provider ARRIVING had three
+ * hand-written pieces covering two capabilities, and `firewall` — which three
+ * modules provide — had none at all (celilo#1011).
+ *
+ * This is the mirror of `consumer-cleanup.ts`, and it is deliberately built the
+ * same way, down to sharing that file's `PRE_DEPLOY_STATES`.
+ *
+ * PULL, NOT PUSH (design D7). When a provider arrives, celilo re-runs the
+ * CONSUMERS' `on_install` and lets each consumer re-register through the path
+ * that worked the first time. It does NOT replay history into the provider by
+ * calling the provider's own hooks on a consumer's behalf. Two of the three
+ * pieces this replaces pushed, and one of them had already drifted:
+ * `backfillWebRouteDns` cannot go through `on_system_event`, because that hook
+ * concatenates `<hostname>.<zone>` and would corrupt an already-qualified name,
+ * so it reaches past the hook into `registerRecord` and now differs from the
+ * live path in ways nothing checks.
+ *
+ * Split plan/execute (Rule 10.4): which consumers, and why one is skipped, is
+ * pure and worth testing on its own. The rest is "run each hook and record what
+ * happened".
+ */
+
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { capabilities, modules } from '../db/schema';
+import { createConsoleLogger } from '../hooks/logger';
+import { type RunNamedHookResult, runNamedHook } from '../hooks/run-named-hook';
+import type { HookLogger } from '../hooks/types';
+import { type ModuleManifest, ModuleManifestSchema } from '../manifest/schema';
+import { PRE_DEPLOY_STATES } from './consumer-cleanup';
+
+export type BackfillSkipReason = 'paused' | 'not-deployed';
+
+export interface BackfillTarget {
+  /** The consumer module to re-run. */
+  consumerId: string;
+  /** Which of the arriving provider's capabilities it consumes — for the log line. */
+  capabilityNames: string[];
+  /** Set when the consumer will NOT be re-run. */
+  skip?: BackfillSkipReason;
+}
+
+export interface ConsumerCandidate {
+  moduleId: string;
+  manifest: ModuleManifest;
+  state: string;
+}
+
+/**
+ * Which consumers must be re-run now that `provider` is here.
+ *
+ * Pure. Sorted by consumer id so dispatch order is deterministic and a failure
+ * is reproducible.
+ *
+ * `requires` AND `optional`, which is the edge `remove-guard.ts` already counts
+ * and the one `optional` was added to express — "this hook will use monitoring
+ * if it is there" describes a module that has something to gain the moment the
+ * provider appears.
+ *
+ * The provider is never its own consumer. A module that both provides and
+ * requires a capability would otherwise have its `on_install` run a second time
+ * inside its own deploy, which just finished running it.
+ */
+export function planProviderBackfill(
+  provider: string,
+  providedCapabilities: Iterable<string>,
+  candidates: ConsumerCandidate[],
+): BackfillTarget[] {
+  const provided = new Set(providedCapabilities);
+  if (provided.size === 0) return [];
+
+  const targets: BackfillTarget[] = [];
+  for (const candidate of candidates) {
+    if (candidate.moduleId === provider) continue;
+
+    const consumed = new Set([
+      ...(candidate.manifest.requires?.capabilities ?? []).map((c) => c.name),
+      ...(candidate.manifest.optional?.capabilities ?? []).map((c) => c.name),
+    ]);
+    const capabilityNames = [...consumed].filter((name) => provided.has(name)).sort();
+    if (capabilityNames.length === 0) continue;
+
+    if (candidate.state === 'PAUSED') {
+      targets.push({ consumerId: candidate.moduleId, capabilityNames, skip: 'paused' });
+      continue;
+    }
+    if (PRE_DEPLOY_STATES.has(candidate.state)) {
+      targets.push({ consumerId: candidate.moduleId, capabilityNames, skip: 'not-deployed' });
+      continue;
+    }
+    targets.push({ consumerId: candidate.moduleId, capabilityNames });
+  }
+
+  return targets.sort((a, b) => a.consumerId.localeCompare(b.consumerId));
+}
+
+/**
+ * Read the plan's inputs out of the DB.
+ *
+ * A module's manifest lives in `modules.manifestData`; a manifest that no
+ * longer parses is skipped rather than fatal, matching `module-remove.ts`'s
+ * dependency scan — a provider deploy must not die on some unrelated module's
+ * bad row.
+ */
+export function loadProviderBackfillPlan(provider: string, db: DbClient): BackfillTarget[] {
+  const provided = db
+    .select({ capabilityName: capabilities.capabilityName })
+    .from(capabilities)
+    .where(eq(capabilities.moduleId, provider))
+    .all()
+    .map((row) => row.capabilityName);
+  if (provided.length === 0) return [];
+
+  const candidates: ConsumerCandidate[] = [];
+  for (const row of db.select().from(modules).all()) {
+    const parsed = ModuleManifestSchema.safeParse(row.manifestData);
+    if (!parsed.success) continue;
+    candidates.push({ moduleId: row.id, manifest: parsed.data, state: row.state });
+  }
+
+  return planProviderBackfill(provider, provided, candidates);
+}
+
+export interface BackfillFailure {
+  consumerId: string;
+  error: string;
+}
+
+export interface ProviderBackfillResult {
+  /** Consumers whose `on_install` was re-run successfully. */
+  rerun: string[];
+  skipped: Array<{ consumerId: string; reason: BackfillSkipReason }>;
+  failures: BackfillFailure[];
+}
+
+/**
+ * Run the plan. Sequential, deterministic, and it CONTINUES PAST A FAILURE:
+ * every consumer is attempted even if an earlier one threw, because stopping
+ * early would leave the remaining consumers unregistered against a provider
+ * that is now live, which is the gap this exists to close.
+ *
+ * A failure never fails the provider's own deploy. The provider deployed fine;
+ * what failed is one consumer's re-registration, and the honest report is a
+ * named consumer with its error and the command that retries it. The caller
+ * surfaces that — silence here would report a clean deploy over a fleet where
+ * some consumers never re-registered.
+ */
+export async function runProviderBackfill(
+  provider: string,
+  plan: BackfillTarget[],
+  db: DbClient,
+  logger: HookLogger,
+  /** Injectable hook runner — tests drive the failure paths through it. */
+  runHook: (consumerId: string) => Promise<RunNamedHookResult> = (consumerId) =>
+    runNamedHook(consumerId, 'on_install', db, createConsoleLogger(consumerId, 'on_install'), {}),
+): Promise<ProviderBackfillResult> {
+  const result: ProviderBackfillResult = { rerun: [], skipped: [], failures: [] };
+
+  for (const target of plan) {
+    if (target.skip) {
+      result.skipped.push({ consumerId: target.consumerId, reason: target.skip });
+      // Reported, not silent. A paused consumer rebinds on its next deploy, so
+      // it is genuinely fine — but the operator should know which modules are
+      // NOT yet talking to the provider that just arrived.
+      if (target.skip === 'paused') {
+        logger.warn(
+          `${target.consumerId} is paused, so it was not re-run against the new '${provider}' — it consumes ${target.capabilityNames.join(', ')} and will rebind on its next deploy.`,
+        );
+      }
+      continue;
+    }
+
+    const hookResult = await runHook(target.consumerId);
+
+    // A module paused BETWEEN the plan and this dispatch. `runNamedHook`
+    // reports that as success, so taking it at face value would log a
+    // re-registration that never happened.
+    if (hookResult.skippedPaused) {
+      result.skipped.push({ consumerId: target.consumerId, reason: 'paused' });
+      logger.warn(
+        `${target.consumerId} was paused while '${provider}' was arriving, so it was not re-run — it will rebind on its next deploy.`,
+      );
+      continue;
+    }
+
+    if (hookResult.success) {
+      // `notDefined` means the consumer declares no `on_install` — there is
+      // nothing to re-run, and the dispatch succeeding is the right answer.
+      if (!hookResult.notDefined) {
+        result.rerun.push(target.consumerId);
+        logger.info(
+          `${target.consumerId} re-registered with '${provider}' (${target.capabilityNames.join(', ')})`,
+        );
+      }
+      continue;
+    }
+
+    const error = hookResult.error ?? 'unknown error';
+    result.failures.push({ consumerId: target.consumerId, error });
+    logger.warn(
+      `${target.consumerId} failed to re-register with '${provider}': ${error}. Run \`celilo module deploy ${target.consumerId}\` to retry.`,
+    );
+  }
+
+  return result;
+}

package/src/services/restore-from-file.ts

@@ -401,8 +401,12 @@ export function applyStagedSystemFiles(systemStagingDir: string): StagedSystemAp
     mkdirSync(moduleStorageBase, { recursive: true });
     for (const entry of readdirSync(stagedModuleSrc, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
+      // `force` explicit: this merges over an EXISTING module dir and the
+      // restored bytes must win. bun does not honour the documented default
+      // on every cp path (see generator.ts#copyAnsibleRoleFilesDirs).
       cpSync(join(stagedModuleSrc, entry.name), join(moduleStorageBase, entry.name), {
         recursive: true,
+        force: true,
       });
       moduleSourcesApplied += 1;
     }

package/src/services/update/orchestrator.test.ts

@@ -76,6 +76,8 @@ const cleanAudit: AuditDeps = {
   terraformPlan: { modules: [], run: async () => ({ exitCode: 0, stdout: '', stderr: '' }) },
   moduleVersions: { installed: [], fetcher: async () => ({ latest: null }) },
   moduleConfigs: { modules: [] },
+  moduleIntegrity: { results: [] },
+  detectWithoutConverge: { modules: [] },
   health: { results: [] },
   backups: { modules: [] },
   abandonedOperations: { records: [] },

package/src/templates/generator.test.ts

@@ -13,6 +13,7 @@ import {
   getOutputFilename,
   injectProxmoxDns,
   isTemplateFile,
+  omitUntaggedProxmoxVlan,
   readTemplateFiles,
   storageFromTfState,
   targetNodeFromTfState,
@@ -770,6 +771,40 @@ resource "proxmox_lxc" "container" {
       );
     });
   });
+
+  describe('omitUntaggedProxmoxVlan', () => {
+    const LXC = [
+      'resource "proxmox_lxc" "dns" {',
+      '  target_node = "$self:target_node"',
+      '  network {',
+      '    bridge = "$self:bridge"',
+      '    tag = $self:vlan',
+      '    ip = "$self:target_ip"',
+      '  }',
+      '}',
+    ].join('\n');
+
+    test('omits the optional VLAN tag for an untagged zone', () => {
+      const out = omitUntaggedProxmoxVlan(LXC, false);
+      expect(out).not.toContain('$self:vlan');
+      expect(out).toContain('    bridge = "$self:bridge"');
+      expect(out).toContain('    ip = "$self:target_ip"');
+    });
+
+    test('retains the VLAN tag when the zone has a VLAN ID', () => {
+      expect(omitUntaggedProxmoxVlan(LXC, true)).toBe(LXC);
+    });
+
+    test('preserves literal and non-self VLAN tag expressions', () => {
+      const authored = ['tag = 30', 'tag = var.vlan', 'tag = $system:network.dmz.vlan'].join('\n');
+      expect(omitUntaggedProxmoxVlan(authored, false)).toBe(authored);
+    });
+
+    test('removes an indented tag line with a trailing comment', () => {
+      const content = '    tag = $self:vlan # optional VLAN\r\n    ip = "dhcp"\r\n';
+      expect(omitUntaggedProxmoxVlan(content, false)).toBe('    ip = "dhcp"\r\n');
+    });
+  });
 });
 
 describe("targetNodeFromTfState (ISS-0090 — terraform state is celilo's placement record)", () => {

package/src/templates/generator.ts

@@ -219,6 +219,31 @@ export function injectProxmoxDns(content: string, hasNameserver: boolean): strin
   });
 }
 
+/**
+ * Omit the optional Proxmox network VLAN tag when a zone is explicitly
+ * untagged.
+ *
+ * Celilo represents an untagged zone by leaving `network.<zone>.vlan` unset.
+ * Module templates historically rendered `tag = $self:vlan` unconditionally,
+ * which makes variable resolution fail even though the Proxmox provider treats
+ * an omitted `tag` attribute as the correct untagged configuration. Removing
+ * only that exact framework variable line preserves literal tags and other
+ * tag expressions authored by a module.
+ *
+ * Policy function (Rule 10.1) - pure string transformation, no I/O.
+ *
+ * @param content - Raw terraform template content (pre variable-resolution)
+ * @param hasVlan - Whether `$self:vlan` resolves to a configured VLAN ID
+ * @returns Content with the optional tag line omitted for an untagged zone
+ */
+export function omitUntaggedProxmoxVlan(content: string, hasVlan: boolean): string {
+  if (hasVlan) {
+    return content;
+  }
+
+  return content.replace(/^[ \t]*tag[ \t]*=[ \t]*\$self:vlan[ \t]*(?:#.*)?(?:\r?\n|$)/gm, '');
+}
+
 /**
  * Extract the node a Proxmox guest is deployed on from a parsed terraform state
  * object — an LXC (proxmox_lxc) or a VM (proxmox_vm_qemu). Pure logic (Rule 10),
@@ -1266,7 +1291,10 @@ export async function generateTemplates(options: GenerateOptions): Promise<Gener
       // every proxmox_lxc resource before resolution (terraform files only).
       const content =
         !isAnsibleTemplate && template.targetPath.endsWith('.tf')
-          ? injectProxmoxDns(template.content, Boolean(context.selfConfig.lxc_nameserver))
+          ? injectProxmoxDns(
+              omitUntaggedProxmoxVlan(template.content, context.selfConfig.vlan !== undefined),
+              Boolean(context.selfConfig.lxc_nameserver),
+            )
           : template.content;
       const result = isAnsibleTemplate
         ? await convertSecretsToJinja(content, context, db)

package/src/variables/context.test.ts

@@ -7,6 +7,7 @@ import {
   capabilities,
   containerServices,
   ipAllocations,
+  machines,
   moduleConfigs,
   moduleInfrastructure,
   moduleSystems,
@@ -193,6 +194,68 @@ describe('Variable Context', () => {
   });
 
   describe('buildResolutionContext', () => {
+    test('records a local machine by its interface identity instead of its transport sentinel', async () => {
+      db.insert(modules)
+        .values({
+          id: 'celilo-mgmt',
+          name: 'Celilo Management',
+          version: '1.0.0',
+          sourcePath: '/test/celilo-mgmt',
+          manifestData: {
+            id: 'celilo-mgmt',
+            name: 'Celilo Management',
+            version: '1.0.0',
+            requires: { system: { zone: 'internal' } },
+          },
+        })
+        .run();
+      db.insert(moduleConfigs)
+        .values({
+          moduleId: 'celilo-mgmt',
+          key: 'hostname',
+          value: 'celilo-mgr',
+          valueJson: '"celilo-mgr"',
+        })
+        .run();
+      db.insert(machines)
+        .values({
+          id: 'local-manager',
+          hostname: 'celilo-mgr',
+          ipAddress: '127.0.0.1',
+          sshUser: 'jem',
+          sshKeyEncrypted: JSON.stringify({ encryptedValue: '', iv: '', authTag: '' }),
+          hardware: { cpu_cores: 4, memory_mb: 8192, disk_gb: 64 },
+          zone: 'internal',
+          earmarkedModule: 'celilo-mgmt',
+          interfaces: [
+            { name: 'ens18', ipAddress: '10.77.20.32', zone: 'internal' },
+            { name: 'wlan0', ipAddress: '192.168.0.32', zone: 'upstream' },
+          ],
+        })
+        .run();
+      db.insert(moduleInfrastructure)
+        .values({
+          id: 'infra-celilo-mgmt',
+          moduleId: 'celilo-mgmt',
+          infrastructureType: 'machine',
+          machineId: 'local-manager',
+        })
+        .run();
+
+      await buildResolutionContext('celilo-mgmt', db);
+
+      const system = db
+        .select()
+        .from(moduleSystems)
+        .where(eq(moduleSystems.moduleId, 'celilo-mgmt'))
+        .get();
+      expect(system).toMatchObject({
+        hostname: 'celilo-mgr',
+        ipv4Address: '10.77.20.32',
+        zone: 'internal',
+      });
+    });
+
     test('should build context with module configs', async () => {
       // Insert module first (for foreign key)
       db.$client.run(

package/src/variables/context.ts

@@ -19,6 +19,7 @@ import { allocateResources, getAllocation } from '../ipam/allocator';
 import { type ModuleManifest, getDeclaredSystems, getSingularSystemSpec } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
+import { resolveMachineIdentityAddress } from '../services/deployed-systems';
 import { upsertModuleConfig } from '../services/module-config';
 import { resolveComputedFields } from './computed/evaluate';
 import { containsComputedMarker } from './computed/marker';
@@ -419,10 +420,17 @@ async function assembleResolutionContext(
             `Machine '${infraSelection.machineId}' for module '${moduleId}' has no ipAddress`,
           );
         }
+        const deployedZone = machineRow.zone ?? zone;
+        const machineIdentity = resolveMachineIdentityAddress(machineRow, deployedZone);
+        if (!machineIdentity) {
+          throw new Error(
+            `Machine '${infraSelection.machineId}' for module '${moduleId}' has no non-loopback interface in zone '${deployedZone}'`,
+          );
+        }
         upsertDeployedSystem(db, moduleId, {
           name: decl.name,
           hostname,
-          ipv4Address: machineRow.ipAddress,
+          ipv4Address: machineIdentity,
           // The machine's own zone, matching recordDeployedSystemForModule and
           // backfillModuleSystems. This is the THIRD place that decides a
           // deployed system's zone, and it ran last — so while the other two
@@ -430,7 +438,7 @@ async function assembleResolutionContext(
           // manifest's, and the control plane stayed recorded as `internal`.
           // `requires.system.zone` is the minimum used to SELECT a host; the
           // machine we selected is where the system actually is.
-          zone: machineRow.zone ?? zone,
+          zone: deployedZone,
           infraType: 'machine',
           machineId: infraSelection.machineId,
         });

package/src/variables/declarative-derivation.test.ts

@@ -691,7 +691,7 @@ describe('applyDeclarativeDerivations', () => {
       expect(context.selfConfig.primary_domain).toBeUndefined();
     });
 
-    test('skips non-string types (handled by config interview instead)', () => {
+    test('derives scalar numeric values from capability data', () => {
       const manifest: ModuleManifest = {
         celilo_contract: '1.0',
         id: 'test-module',
@@ -703,10 +703,10 @@ describe('applyDeclarativeDerivations', () => {
           owns: [
             {
               name: 'port',
-              type: 'number',
+              type: 'integer',
               required: false,
-              source: 'user',
-              derive_from: '$system:port',
+              source: 'capability',
+              derive_from: '$capability:dns_internal.dns.knot_port',
             },
           ],
           imports: [],
@@ -716,16 +716,55 @@ describe('applyDeclarativeDerivations', () => {
       const context: ResolutionContext = {
         moduleId: 'test-module',
         selfConfig: {},
-        systemConfig: { port: '8080' },
+        systemConfig: {},
         systemSecrets: {},
         secrets: {},
-        capabilities: {},
+        capabilities: {
+          dns_internal: { dns: { knot_port: 5353 } },
+        },
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      expect(context.selfConfig.port).toBe('5353');
+    });
+
+    test('continues to skip structured derivations', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'domains',
+              type: 'array',
+              required: false,
+              source: 'capability',
+              derive_from: '$capability:dns_internal.dns.managed_domains',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {
+          dns_internal: { dns: { managed_domains: ['home.arpa'] } },
+        },
       };
 
       applyDeclarativeDerivations(manifest, context);
 
-      // Non-string variable is skipped — port remains unset
-      expect(context.selfConfig.port).toBeUndefined();
+      expect(context.selfConfig.domains).toBeUndefined();
     });
   });
 

package/src/variables/declarative-derivation.ts

@@ -186,10 +186,12 @@ export function applyDeclarativeDerivations(
       continue;
     }
 
-    // Declarative derivation only resolves string template expressions.
-    // Non-string types (arrays, objects) with derive_from are handled by
-    // the config interview system instead.
-    if (variable.type !== 'string') {
+    // Declarative derivation resolves scalar template expressions. Numeric and
+    // boolean values flow through this resolution context as their string form
+    // and recover their declared type at the module-config / inventory boundary.
+    // Structured arrays and objects still belong to the typed config path: a
+    // template substitution would collapse them to a lossy string.
+    if (variable.type === 'array' || variable.type === 'object') {
       continue;
     }