@celilo/cli 0.22.0 → 0.24.0

package/src/services/update/dep-graph.test.ts

@@ -80,13 +80,42 @@ describe('buildModuleGraph', () => {
     expect(g.edges.get('weird')?.size).toBe(0);
   });
 
-  test('first declared provider wins when multiple modules provide the same capability', () => {
+  // Previously asserted "first declared provider wins". That was the behaviour,
+  // and it was a defect: `capability-loader.ts` resolves a `firewall` consumer
+  // through `buildFirewallChain()`, which wires a chain across EVERY provider —
+  // the edge device that owns egress plus the downstream layers. First-wins made
+  // the others invisible, so `module pause --cascade greenwave` omitted `caddy`
+  // even though caddy requires `firewall` and greenwave provides it, and the
+  // remove guard (which reads all providers) then refused the removal the
+  // cascade was supposed to enable.
+  test('a consumer depends on EVERY provider of a capability, not just the first', () => {
     const g = buildModuleGraph([
-      makeManifest('a', { provides: ['firewall'] }),
-      makeManifest('b', { provides: ['firewall'] }),
+      makeManifest('iptables', { provides: ['firewall'] }),
+      makeManifest('greenwave', { provides: ['firewall'] }),
+      makeManifest('caddy', { requires: ['firewall'] }),
+    ]);
+    expect([...(g.edges.get('caddy') ?? [])].sort()).toEqual(['greenwave', 'iptables']);
+  });
+
+  test('and every provider sees that consumer in its reverse index', () => {
+    // This is the half `transitiveConsumers` walks, so it is what decides
+    // whether a cascade reaches the module at all.
+    const g = buildModuleGraph([
+      makeManifest('iptables', { provides: ['firewall'] }),
+      makeManifest('greenwave', { provides: ['firewall'] }),
       makeManifest('caddy', { requires: ['firewall'] }),
     ]);
-    expect([...(g.edges.get('caddy') ?? [])]).toEqual(['a']);
+    expect([...(g.reverseEdges.get('greenwave') ?? [])]).toEqual(['caddy']);
+    expect([...(g.reverseEdges.get('iptables') ?? [])]).toEqual(['caddy']);
+  });
+
+  test('an optional consumer also edges to every provider', () => {
+    const g = buildModuleGraph([
+      makeManifest('greenwave', { provides: ['dhcp_server'] }),
+      makeManifest('router2', { provides: ['dhcp_server'] }),
+      makeManifest('technitium', { optional: ['dhcp_server'] }),
+    ]);
+    expect([...(g.edges.get('technitium') ?? [])].sort()).toEqual(['greenwave', 'router2']);
   });
 });
 

package/src/services/update/dep-graph.ts

@@ -45,15 +45,36 @@ export interface ModuleGraph {
   reverseEdges: Map<ModuleId, Set<ModuleId>>;
 }
 
-/** Internal: build an index of capability name → providing module id. */
-function indexProviders(modules: ModuleNode[]): Map<string, ModuleId> {
-  const index = new Map<string, ModuleId>();
+/**
+ * Internal: index capability name → EVERY module providing it.
+ *
+ * This used to keep only the first provider, on the reasoning that "one edge per
+ * capability is enough for graph-walking". It is not, and the discrepancy is
+ * not theoretical: `firewall` is provided by BOTH `iptables` and `greenwave`,
+ * and `capability-loader.ts` resolves a consumer's `requires: firewall` through
+ * `buildFirewallChain()`, which wires a chain across ALL providers — the edge
+ * device that owns egress plus the downstream layers. So a consumer genuinely
+ * depends on every one of them.
+ *
+ * With first-wins, whichever provider happened to be inserted first absorbed the
+ * edge and the others became invisible to the graph. `module pause --cascade
+ * greenwave` therefore omitted `caddy` entirely, even though caddy requires
+ * `firewall` and greenwave provides it — so the operator paused an incomplete
+ * set and `module remove` then refused, because the remove guard reads the
+ * capabilities table (all providers) and disagreed. That disagreement is exactly
+ * what openspec/changes/module-pause-lifecycle design D3 forbids.
+ *
+ * Keeping all providers makes the graph agree with how capabilities actually
+ * resolve. For `topologicalOrder` it means a consumer sorts after every provider
+ * of what it consumes, which is strictly more correct for `system update`.
+ */
+function indexProviders(modules: ModuleNode[]): Map<string, ModuleId[]> {
+  const index = new Map<string, ModuleId[]>();
   for (const m of modules) {
     for (const cap of m.provides) {
-      // First provider wins. The capability-loader's chain logic handles
-      // multi-provider scenarios at deploy time; for graph-walking
-      // purposes one edge per capability is enough.
-      if (!index.has(cap)) index.set(cap, m.id);
+      const existing = index.get(cap);
+      if (existing) existing.push(m.id);
+      else index.set(cap, [m.id]);
     }
   }
   return index;
@@ -82,16 +103,17 @@ export function buildModuleGraph(manifests: ModuleManifest[]): ModuleGraph {
     reverseEdges.set(node.id, reverseEdges.get(node.id) ?? new Set());
 
     for (const cap of node.consumes) {
-      const providerId = providerIndex.get(cap);
-      // Skip self-edges (a module that consumes its own capability —
-      // unusual but legal) and missing providers (deploy preflight
-      // handles those; graph just routes around them).
-      if (!providerId || providerId === node.id) continue;
-
-      edges.get(node.id)?.add(providerId);
-      const rev = reverseEdges.get(providerId) ?? new Set();
-      rev.add(node.id);
-      reverseEdges.set(providerId, rev);
+      for (const providerId of providerIndex.get(cap) ?? []) {
+        // Skip self-edges (a module that consumes its own capability —
+        // unusual but legal) and missing providers (deploy preflight
+        // handles those; graph just routes around them).
+        if (providerId === node.id) continue;
+
+        edges.get(node.id)?.add(providerId);
+        const rev = reverseEdges.get(providerId) ?? new Set();
+        rev.add(node.id);
+        reverseEdges.set(providerId, rev);
+      }
     }
   }
 

package/src/services/zone-detector.test.ts

@@ -70,9 +70,14 @@ describe('zone-detector', () => {
       expect(zone).toBe('secure');
     });
 
-    it('returns external for non-matching IP', async () => {
+    it("returns 'unknown' for a PUBLIC address in no declared subnet", async () => {
+      // This asserted `external` before. It is now `'unknown'` because that is
+      // the question this function answers: containment. Whether 167.99.123.45
+      // is an external EDGE is `isPubliclyRoutable`'s question, and the caller
+      // resolves the two — see machine-add. Conflating them is the defect this
+      // change exists to remove (design D1).
       const zone = await detectZoneFromIp('167.99.123.45');
-      expect(zone).toBe('external');
+      expect(zone).toBe('unknown');
     });
 
     it('matches first IP in subnet', async () => {
@@ -87,7 +92,33 @@ describe('zone-detector', () => {
 
     it('does not match IP outside subnet', async () => {
       const zone = await detectZoneFromIp('192.168.1.100');
-      expect(zone).toBe('external');
+      expect(zone).toBe('unknown');
+    });
+
+    it("a PRIVATE address in no declared subnet is 'unknown', never 'external'", async () => {
+      // The heart of it. 172.16.5.5 is RFC 1918 — the internet cannot route to
+      // it under any circumstances — and it matched no declared subnet. Calling
+      // that `external` is the claim that broke `machine add`.
+      const zone = await detectZoneFromIp('172.16.5.5');
+      expect(zone).toBe('unknown');
+    });
+
+    /**
+     * §5.7 — PROOF THE OLD BEHAVIOUR IS GONE.
+     *
+     * The proposal's opening example, against the real subnet declarations in
+     * this fixture. Three RFC1918 gateway legs that no declared subnet contains.
+     * Pre-change, `detectZoneFromIp` returned `'external'` for every one of
+     * them, so `machine add` printed three private addresses as facing the
+     * internet. This test fails against that code and passes against this.
+     */
+    it('§5.7: three RFC1918 legs in no declared subnet are NOT external', async () => {
+      const undeclaredPrivateLegs = ['172.16.5.1', '10.99.0.1', '192.168.77.1'];
+      const zones = await Promise.all(undeclaredPrivateLegs.map((ip) => detectZoneFromIp(ip)));
+
+      expect(zones).toEqual(['unknown', 'unknown', 'unknown']);
+      // Stated separately so a failure says WHICH property broke.
+      expect(zones.filter((z) => z === 'external')).toEqual([]);
     });
   });
 

package/src/services/zone-detector.ts

@@ -3,47 +3,27 @@
  * Auto-detects network zone from IP address by matching against system subnets
  */
 
+import { subnetContains } from '@celilo/capabilities';
 import { eq } from 'drizzle-orm';
 import { getDb } from '../db/client';
-import { type NetworkZone, systemConfig } from '../db/schema';
+import { NETWORK_ZONES, type NetworkZone, systemConfig } from '../db/schema';
 
 /**
- * Parse CIDR notation to get network address and prefix length
- */
-function parseCIDR(cidr: string): { network: string; prefixLength: number } {
-  const [ip, prefix] = cidr.split('/');
-  return {
-    network: ip,
-    prefixLength: Number.parseInt(prefix, 10),
-  };
-}
-
-/**
- * Convert IP address string to 32-bit integer
- */
-function ipToInt(ip: string): number {
-  const parts = ip.split('.').map((part) => Number.parseInt(part, 10));
-  return (parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3];
-}
-
-/**
- * Check if an IP address is in a CIDR subnet
+ * The zones a subnet can be declared for — every `NetworkZone` except
+ * `external`.
+ *
+ * `external` is deliberately absent and must stay absent: it has no
+ * `network.external.subnet` and must never be given one. It is not a segment
+ * celilo manages, it is whatever the ISP handed you, so it is the RESIDUAL —
+ * decided by `isPubliclyRoutable`, not by containment (design D1, amended).
+ *
+ * Derived from NETWORK_ZONES rather than listed by hand. The hand-written list
+ * that used to be here had already dropped `control-plane-vpn`, which is the
+ * third instance of that bug class in this repo.
  */
-function ipInSubnet(ip: string, cidr: string): boolean {
-  try {
-    const { network, prefixLength } = parseCIDR(cidr);
-    const ipInt = ipToInt(ip);
-    const networkInt = ipToInt(network);
-
-    // Create subnet mask
-    const mask = ~((1 << (32 - prefixLength)) - 1);
-
-    // Check if IP is in subnet
-    return (ipInt & mask) === (networkInt & mask);
-  } catch {
-    return false;
-  }
-}
+const SUBNET_BACKED_ZONES: readonly NetworkZone[] = NETWORK_ZONES.filter(
+  (zone) => zone !== 'external',
+);
 
 /**
  * Get system network configuration for a zone
@@ -65,25 +45,28 @@ async function getZoneSubnet(zone: NetworkZone): Promise<string | null> {
 }
 
 /**
- * Detect network zone from IP address
- * Matches IP against system network configuration
+ * Which zone an address belongs to, or `'unknown'` when celilo cannot say.
+ *
+ * **`'unknown'` is the honest answer, and it used to be unreachable.** This
+ * returned `'external'` on no-match — so on a firewall with five RFC1918 legs
+ * and three declared zones, private gateway addresses were each reported as
+ * facing the internet. `NetworkInterface.zone` was already typed
+ * `NetworkZone | 'unknown'` and nothing could produce it, because this claimed
+ * `external` instead. The slot for the honest answer existed and was
+ * unreachable.
  *
- * @param ip - IP address to check
- * @returns Detected network zone, or 'external' if no match
+ * This answers ONLY the containment question. Whether an unmatched address is
+ * an external edge is a different question, answered by `isPubliclyRoutable` —
+ * see design D1 on why conflating the two was the defect.
  */
-export async function detectZoneFromIp(ip: string): Promise<NetworkZone> {
-  // Check each zone's subnet
-  const zones: NetworkZone[] = ['internal', 'dmz', 'app', 'secure', 'secure-mgmt'];
-
-  for (const zone of zones) {
+export async function detectZoneFromIp(ip: string): Promise<NetworkZone | 'unknown'> {
+  for (const zone of SUBNET_BACKED_ZONES) {
     const subnet = await getZoneSubnet(zone);
-    if (subnet && ipInSubnet(ip, subnet)) {
+    if (subnet && subnetContains(subnet, ip)) {
       return zone;
     }
   }
-
-  // No match found - must be external
-  return 'external';
+  return 'unknown';
 }
 
 /**

package/src/test-utils/cli.ts

@@ -6,13 +6,17 @@ import { execSync } from 'node:child_process';
  * Disconnects stdin to ensure CLI cannot prompt for user input.
  * Any attempt to read from stdin will immediately fail, preventing hanging tests.
  *
- * When command fails, throws error with stderr included in message for test assertions.
+ * When command fails, throws an error carrying stderr — where the CLI writes
+ * its diagnostics. Both helpers used to concatenate stdout and stderr because
+ * `@clack/prompts` put error messages on stdout, which left no way to tell a
+ * result from a complaint about producing one (celilo#699). The streams are
+ * separate now and this reads only the one that carries diagnostics.
  *
  * @param cli - CLI command prefix (includes env vars and path)
  * @param command - Command to execute (e.g., "system config get")
  * @param options - Additional exec options
- * @returns Command output as string
- * @throws Error with stderr message when command fails
+ * @returns Command stdout as string
+ * @throws Error with the stderr message when command fails
  */
 export function runCli(cli: string, command: string, options: { encoding?: 'utf-8' } = {}): string {
   try {
@@ -22,34 +26,31 @@ export function runCli(cli: string, command: string, options: { encoding?: 'utf-
       timeout: 30000, // 30 second timeout to prevent tests hanging indefinitely
     });
   } catch (error: unknown) {
-    // CLI writes errors to stdout (via @clack/prompts), so capture both
-    const stdout = (error as { stdout?: Buffer }).stdout?.toString() || '';
     const stderr = (error as { stderr?: Buffer }).stderr?.toString() || '';
-    // Combine both stdout and stderr (some commands write to both)
-    const output = [stdout, stderr].filter(Boolean).join('\n') || (error as Error).message;
-    throw new Error(output);
+    throw new Error(stderr.trim() || (error as Error).message);
   }
 }
 
 /**
  * Execute CLI command expecting failure
- * Returns combined stdout + stderr for assertion
+ * Returns stderr for assertion — that is where the CLI writes diagnostics.
  *
  * Disconnects stdin to ensure CLI cannot prompt for user input.
  *
  * @param cli - CLI command prefix
  * @param command - Command to execute
- * @returns combined output as string
+ * @returns stderr as string
  * @throws Error if command succeeds (when it should fail)
  */
 export function runCliExpectingFailure(cli: string, command: string): string {
   try {
     execSync(`${cli} ${command}`, { stdio: ['ignore', 'pipe', 'pipe'] });
-    throw new Error('Expected command to fail but it succeeded');
   } catch (error: unknown) {
-    // CLI writes errors to stdout (via @clack/prompts), so capture both
-    const stdout = (error as { stdout?: Buffer }).stdout?.toString() || '';
     const stderr = (error as { stderr?: Buffer }).stderr?.toString() || '';
-    return [stdout, stderr].filter(Boolean).join('\n') || (error as Error).message;
+    return stderr.trim() || (error as Error).message;
   }
+  // Previously thrown from inside the `try`, where the catch below swallowed it
+  // and RETURNED the message — so a command that wrongly succeeded read as a
+  // passing assertion about its own failure.
+  throw new Error('Expected command to fail but it succeeded');
 }

package/src/test-utils/integration-guard.ts

@@ -31,3 +31,29 @@ export function skipIntegration(
   if (req.platform && process.platform !== req.platform) return true;
   return false;
 }
+
+/**
+ * Quarantine a test that FAILS ON THE CI RUNNER for a reason we have not yet
+ * explained, while keeping it running for developers locally.
+ *
+ * This is the `cele2e-ci-unsafe` device (see `--ci-safe` in the cele2e runner)
+ * applied to the integration suite, and it is deliberately uncomfortable to
+ * use: the caller must pass the tracking issue, and the whole point is that the
+ * skip is legible in the log rather than silent.
+ *
+ * Use this ONLY when the failure is not explained by a missing tool — reach for
+ * `skipIntegration({ tools: [...] })` first, because "which tool" is a real
+ * diagnosis and "quarantined" is an admission that we do not have one yet.
+ *
+ * The alternative is worse in both directions: leaving the test in makes a gate
+ * permanently red, which trains everyone to ignore it — the same disease as a
+ * gate that cannot fail. Deleting it loses the coverage and the evidence.
+ *
+ * Keyed on `GITHUB_ACTIONS`, which the Forgejo runner sets (it is what makes
+ * `bun test` emit `::error` annotations there).
+ *
+ * Usage:  test.skipIf(quarantinedInCi('celilo#713'))('...', ...)
+ */
+export function quarantinedInCi(_trackingIssue: string): boolean {
+  return process.env.GITHUB_ACTIONS === 'true';
+}

package/src/test-utils/setup-test-db.ts

@@ -1,30 +1,20 @@
 import { existsSync } from 'node:fs';
 import { unlink } from 'node:fs/promises';
-import { join } from 'node:path';
 import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
-import { type DbClient, createDbClient } from '../db/client';
+import { type DbClient, createDbClient, findMigrationsFolder } from '../db/client';
 
-/**
- * Find migrations folder relative to current working directory
- */
-function findMigrationsFolder(): string {
-  // Try common locations
-  const candidates = [
-    './drizzle', // Running from backend directory
-    './backend/drizzle', // Running from celilo directory
-    join(process.cwd(), 'drizzle'), // Absolute from backend
-    join(process.cwd(), 'backend', 'drizzle'), // Absolute from celilo
-  ];
-
-  for (const candidate of candidates) {
-    const metaPath = join(candidate, 'meta', '_journal.json');
-    if (existsSync(metaPath)) {
-      return candidate;
-    }
-  }
-
-  throw new Error(`Could not find drizzle migrations folder. Tried: ${candidates.join(', ')}`);
-}
+// `findMigrationsFolder` is imported from db/client rather than redefined here.
+// This file used to carry its own copy, and the copy had drifted: it listed
+// only CWD-RELATIVE candidates (`./drizzle`, `process.cwd()/drizzle`, …) and was
+// missing the `join(currentDir, '../../drizzle')` fallback that resolves
+// relative to the source file.
+//
+// The effect was invisible from `apps/celilo` and total from the repo root —
+// which is where CLAUDE.md says to run the gate. Every suite using
+// setupTestDatabase threw here, left `db` unassigned, and then failed again in
+// its own afterEach on `db.$client`, so one missing path candidate presented as
+// hundreds of unrelated-looking assertion failures (celilo: 668 across the
+// repo, 341 in apps/celilo/src alone).
 
 /**
  * Setup test database with real migrations