@celilo/cli 1.0.0 → 1.2.0

package/src/system/prereqs.ts

@@ -11,13 +11,19 @@
  * runtime invokers (ansible/terraform shell-outs) all consume it from
  * here.
  *
- * All entries are universally required — no required-vs-recommended
+ * All entries are universally DECLARED — no required-vs-recommended
  * distinction. The platform is the platform; an operator who currently
- * doesn't use Terraform still installs Terraform, on the theory that
- * predictability beats marginal install-friction savings.
+ * doesn't use Terraform still sees a terraform row, on the theory that
+ * predictability beats marginal install-friction savings. Declaring is not
+ * the same as installing: terraform and the browser are both installed by
+ * `celilo-mgmt` only on request, and both report here either way, which is
+ * how an operator finds out a host is missing one.
  */
 
 import { spawnSync } from 'node:child_process';
+import { constants, accessSync, statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { BROWSER_EXECUTABLE_PATH } from '@celilo/capabilities';
 
 // ── Types ─────────────────────────────────────────────────────────────
 
@@ -33,15 +39,22 @@ export type PackageManager = 'apt' | 'dnf' | 'yum' | 'pacman' | 'apk' | 'brew' |
  * table below; consumers don't construct these themselves.
  */
 export interface PrerequisiteSpec {
-  /** Binary name as invoked on the command line (e.g. 'ansible'). */
+  /** Row label in doctor output, and the binary name when `command` is
+   *  absent (e.g. 'ansible'). */
   name: string;
   /** One-line "what this is for" text used in doctor output. */
   description: string;
-  /** Flag that prints the version (`--version` for most; `version`
-   *  for terraform; `-V` for ssh; `-v` for unzip). */
+  /** What to execute, when that differs from `name`. An ABSOLUTE path
+   *  switches the presence check from `command -v` to "this exact file
+   *  exists and is executable" — the celilo-provisioned browser lives at
+   *  a known path and is never on PATH. */
+  command?: string;
+  /** Argument that makes the tool report what the row displays
+   *  (`--version` for most; `version` for terraform; `-V` for ssh;
+   *  `-v` for unzip; a font pattern for fc-match). */
   versionFlag: string;
-  /** Captures the version string from the tool's version output.
-   *  First capture group must be the bare version (e.g. `2.16.3`). */
+  /** Captures the displayed string from that output. First capture group
+   *  must be the bare value (e.g. `2.16.3`). */
   versionRegex: RegExp;
   /** Minimum semver. `null` means presence-only — any version OK. */
   minVersion: string | null;
@@ -54,9 +67,9 @@ export interface PrerequisiteSpec {
 export interface PrereqCheck {
   name: string;
   description: string;
-  /** `command -v <name>` succeeded. */
+  /** The tool was found — on PATH, or at its declared absolute path. */
   present: boolean;
-  /** Resolved path on PATH (or null when absent). */
+  /** Resolved executable (or null when absent). */
   binaryPath: string | null;
   /** Version captured from `--version` output, or null on
    *  parse-fail / not-present. */
@@ -139,6 +152,42 @@ export const PREREQUISITES: PrerequisiteSpec[] = [
     versionRegex: /UnZip\s+(\d+\.\d+)/,
     minVersion: null,
   },
+  // Declared unconditionally even though installation is opt-in — same as
+  // terraform above. `system doctor` is the ONLY place an operator learns
+  // this host has no browser, because a not-provisioned browser is
+  // deliberately not a check failure.
+  //
+  // The check probes the PROVISIONED PATH and must never ask Playwright
+  // which executable it would use: `chromium.executablePath()` reports the
+  // FULL browser while a headless launch opens the SHELL — measured
+  // disagreeing on one machine in one run. On a shell-only host that would
+  // validate a path which does not exist while the binary that actually
+  // runs is fine. Running it is also what separates a real install from a
+  // build directory with no binary in it, which satisfies a path test and
+  // then fails at launch.
+  {
+    name: 'browser',
+    description: 'Runs browser-driven module health checks',
+    command: BROWSER_EXECUTABLE_PATH,
+    versionFlag: '--version',
+    // e.g. "Chromium 148.0.7778.0"
+    versionRegex: /(\d+\.\d+\.\d+(?:\.\d+)?)/,
+    minVersion: null,
+  },
+  // Fonts belong here rather than in the record consumers read: the party
+  // who needs to know a retained screenshot has legible glyphs is the
+  // operator looking at it. `fc-match sans-serif` resolves an actual face,
+  // so it answers "is there a text font" rather than "is fontconfig
+  // installed", and the family name is what the row displays.
+  {
+    name: 'fonts',
+    description: 'Legible text in browser screenshots',
+    command: 'fc-match',
+    versionFlag: 'sans-serif',
+    // e.g. 'DejaVuSans.ttf: "DejaVu Sans" "Book"'
+    versionRegex: /"([^"]+)"/,
+    minVersion: null,
+  },
 ];
 
 // ── Per-OS install hints ──────────────────────────────────────────────
@@ -210,6 +259,14 @@ const INSTALL_HINTS: Record<string, Partial<Record<PackageManager, string>>> = {
     apk: 'sudo apk add curl',
     // macOS ships /usr/bin/curl built-in.
   },
+  fonts: {
+    apt: 'sudo apt-get install fontconfig fonts-dejavu-core',
+    dnf: 'sudo dnf install fontconfig dejavu-sans-fonts',
+    yum: 'sudo yum install fontconfig dejavu-sans-fonts',
+    pacman: 'sudo pacman -S fontconfig ttf-dejavu',
+    apk: 'sudo apk add fontconfig font-dejavu',
+    brew: 'brew install fontconfig',
+  },
   unzip: {
     apt: 'sudo apt-get install unzip',
     dnf: 'sudo dnf install unzip',
@@ -227,6 +284,9 @@ const INSTALL_HINTS: Record<string, Partial<Record<PackageManager, string>>> = {
 const FALLBACK_HINTS: Record<string, string> = {
   bun: 'See https://bun.sh/install',
   terraform: 'See https://developer.hashicorp.com/terraform/install',
+  // Not a package: celilo installs it itself, on request.
+  browser:
+    'celilo module config set celilo-mgmt install_browser true && celilo module deploy celilo-mgmt',
 };
 
 // ── Detection ─────────────────────────────────────────────────────────
@@ -301,13 +361,30 @@ export function compareVersions(a: string, b: string): number {
  * is a misbehaving binary or a stuck PATH lookup; either way we
  * shouldn't wedge the doctor command waiting on it.
  */
+/**
+ * Resolve an absolute-path prerequisite. Returns the path only when it is
+ * a real file that is executable — a symlink pointing at nothing, or a
+ * build directory with no binary in it, resolves to null.
+ */
+function executableAt(path: string): string | null {
+  try {
+    // statSync follows symlinks, so a dangling link throws here.
+    if (!statSync(path).isFile()) return null;
+    accessSync(path, constants.X_OK);
+    return path;
+  } catch {
+    return null;
+  }
+}
+
 export function checkPrerequisite(
   spec: PrerequisiteSpec,
   pm: PackageManager = detectPackageManager(),
 ): PrereqCheck {
   const installHint = getInstallHint(spec.name, pm);
 
-  const binaryPath = Bun.which(spec.name);
+  const command = spec.command ?? spec.name;
+  const binaryPath = isAbsolute(command) ? executableAt(command) : Bun.which(command);
   if (!binaryPath) {
     return {
       name: spec.name,
@@ -322,7 +399,7 @@ export function checkPrerequisite(
 
   let version: string | null = null;
   try {
-    const result = spawnSync(spec.name, [spec.versionFlag], {
+    const result = spawnSync(binaryPath, [spec.versionFlag], {
       encoding: 'utf-8',
       timeout: 5000,
       // Some tools (notably git on macOS) refuse to run with a

package/src/templates/generator.ts

@@ -654,38 +654,58 @@ celilo module import modules/${moduleId}
  * @returns Generation result
  */
 /** Narrower than `GenerateResult`: this step produces no files, only an outcome. */
-export type DnsIngressResult = { success: true } | { success: false; error: string };
+export type IngressIpResult = { success: true } | { success: false; error: string };
 
 /**
- * Allocate-and-reserve the module's dedicated DNS-ingress IP, ONCE (ISS-0156).
+ * Allocate-and-reserve a module's dedicated `internal`-subnet ingress IPs, ONCE
+ * (ISS-0156, celilo#879).
  *
- * A `dns_internal` provider deploys into a PROTECTED zone (dmz) so it can see
- * protected-zone query sources for split-horizon views. `internal` devices have
- * no route into the 10-net, so they reach the resolver through a firewall DNAT
- * on a dedicated `internal`-subnet address. A module opts in by declaring a
- * `dns_ingress_ip` infrastructure variable.
+ * A service can need to live in a PROTECTED zone — the `dns_internal` resolver
+ * sits in `dmz` so it can see protected-zone query sources for split-horizon,
+ * and `caddy-internal` sits there so systems in the segmented zones can reach
+ * it. `internal` devices have no route into the 10-net, so they reach such a
+ * service through a firewall DNAT on a dedicated `internal`-subnet address.
+ * That DNAT is internal-side only: it is NOT a public port-forward, and the two
+ * are routinely confused.
+ *
+ * A module opts in by declaring an infrastructure variable whose name ends in
+ * `ingress_ip` — `dns_ingress_ip` for the resolver's `:53`, `ingress_ip` for a
+ * private web ingress's `:80/:443`. The hook then passes the stored value to
+ * `firewall.exposeService({ ingressIp })`.
  *
  * **Idempotence is the whole point, and it is load-bearing.** `module generate`
  * runs repeatedly over a module's life. Re-allocating here on the second run
- * would move the address internal clients use to reach DNS, every time — while
- * every command still reports success. That is why the stored value is reused
- * rather than re-derived, and why this is a named function instead of a branch
- * buried in `generateTemplates`: an invariant nothing can call is an invariant
- * nothing can test, and this one had no test at all.
+ * would move the address internal clients use to reach the service, every time
+ * — while every command still reports success. That is why the stored value is
+ * reused rather than re-derived, and why this is a named function instead of a
+ * branch buried in `generateTemplates`: an invariant nothing can call is an
+ * invariant nothing can test, and this one had no test at all.
  */
-export async function ensureDnsIngressIp(
+export async function ensureIngressIps(
   moduleId: string,
   manifest: ModuleManifest,
   db: DbClient,
-): Promise<DnsIngressResult> {
-  const wantsDnsIngress = manifest.variables?.owns?.some(
-    (v) => v.name === 'dns_ingress_ip' && v.source === 'infrastructure',
+): Promise<IngressIpResult> {
+  const wanted = (manifest.variables?.owns ?? []).filter(
+    (v) => v.name.endsWith('ingress_ip') && v.source === 'infrastructure',
   );
-  if (!wantsDnsIngress) return { success: true };
+  if (wanted.length === 0) return { success: true };
+
+  for (const variable of wanted) {
+    const result = await allocateIngressIp(moduleId, variable.name, db);
+    if (!result.success) return result;
+  }
+  return { success: true };
+}
 
-  const existing = getModuleConfigValue(moduleId, 'dns_ingress_ip', db)?.value;
+async function allocateIngressIp(
+  moduleId: string,
+  variableName: string,
+  db: DbClient,
+): Promise<IngressIpResult> {
+  const existing = getModuleConfigValue(moduleId, variableName, db)?.value;
   if (typeof existing === 'string' && existing.length > 0) {
-    log.success(`Using existing DNS-ingress IP ${existing} for ${moduleId}`);
+    log.success(`Using existing ingress IP ${existing} (${variableName}) for ${moduleId}`);
     return { success: true };
   }
 
@@ -695,9 +715,7 @@ export async function ensureDnsIngressIp(
   if (!subnetRow?.value) {
     return {
       success: false,
-      error:
-        'network.internal.subnet is not configured — required to allocate the ' +
-        'dns_internal DNS-ingress IP (ISS-0156). Ensure the internal network is set up first.',
+      error: `network.internal.subnet is not configured — required to allocate the ${variableName} ingress IP (ISS-0156). Ensure the internal network is set up first.`,
     };
   }
 
@@ -705,14 +723,14 @@ export async function ensureDnsIngressIp(
   const { stripCIDR } = await import('../ipam/subnet-parser');
   try {
     const ip = stripCIDR(await allocateIPFromSubnet(subnetRow.value, 'internal', db));
-    await reserveIP(ip, 'internal', `dns-ingress:${moduleId}`, null, db);
-    upsertModuleConfig(db, moduleId, 'dns_ingress_ip', ip);
-    log.success(`Allocated DNS-ingress IP ${ip} (internal subnet) for ${moduleId}`);
+    await reserveIP(ip, 'internal', `ingress:${moduleId}:${variableName}`, null, db);
+    upsertModuleConfig(db, moduleId, variableName, ip);
+    log.success(`Allocated ingress IP ${ip} (internal subnet, ${variableName}) for ${moduleId}`);
     return { success: true };
   } catch (error) {
     return {
       success: false,
-      error: `DNS-ingress IP allocation failed: ${error instanceof Error ? error.message : String(error)}`,
+      error: `Ingress IP allocation failed for ${variableName}: ${error instanceof Error ? error.message : String(error)}`,
     };
   }
 }
@@ -879,8 +897,8 @@ export async function generateTemplates(options: GenerateOptions): Promise<Gener
     }
   }
 
-  const dnsIngress = await ensureDnsIngressIp(moduleId, manifest, db);
-  if (!dnsIngress.success) return dnsIngress;
+  const ingress = await ensureIngressIps(moduleId, manifest, db);
+  if (!ingress.success) return ingress;
 
   // Infrastructure Properties Resolution (Proxmox provider config)
   // For Proxmox services, extract provider config and store as temporary values

package/src/templates/{dns-ingress-ip.test.ts → ingress-ip.test.ts}

@@ -1,11 +1,11 @@
 /**
- * The DNS-ingress allocate-and-reserve guard (ISS-0156).
+ * The ingress-IP allocate-and-reserve guard (ISS-0156, celilo#879).
  *
  * This invariant had NO test. Losing it is not a crash: `module generate`
  * re-allocates a different address on every run, silently moving the address
- * internal clients use to reach DNS, while every command still reports success.
- * `module generate` runs repeatedly over a module's life, so "on the second
- * run" is the normal case, not an edge one.
+ * internal clients use to reach the service, while every command still reports
+ * success. `module generate` runs repeatedly over a module's life, so "on the
+ * second run" is the normal case, not an edge one.
  */
 
 import { beforeEach, describe, expect, test } from 'bun:test';
@@ -13,7 +13,7 @@ import type { DbClient } from '../db/client';
 import type { ModuleManifest } from '../manifest/schema';
 import { getModuleConfigValue } from '../services/module-config';
 import { setupTestDatabase } from '../test-utils/database';
-import { ensureDnsIngressIp } from './generator';
+import { ensureIngressIps } from './generator';
 
 let db: DbClient;
 
@@ -27,12 +27,17 @@ const operatorSupplied = {
   variables: { owns: [{ name: 'dns_ingress_ip', source: 'user_input' }] },
 } as unknown as ModuleManifest;
 
+/** How `caddy-internal` opts in — a web ingress rather than a DNS one. */
+const wantsWebIngress = {
+  variables: { owns: [{ name: 'ingress_ip', source: 'infrastructure' }] },
+} as unknown as ModuleManifest;
+
 /**
  * Typed as `string | undefined` rather than `unknown`: every assertion here is
  * about an address, and an untyped read pushes a cast onto each one.
  */
-const storedIp = (moduleId: string): string | undefined => {
-  const value = getModuleConfigValue(moduleId, 'dns_ingress_ip', db)?.value;
+const storedIp = (moduleId: string, variable = 'dns_ingress_ip'): string | undefined => {
+  const value = getModuleConfigValue(moduleId, variable, db)?.value;
   return typeof value === 'string' ? value : undefined;
 };
 
@@ -43,9 +48,9 @@ beforeEach(async () => {
     .run('network.internal.subnet', '10.226.1.0/24');
 });
 
-describe('ensureDnsIngressIp', () => {
+describe('ensureIngressIps', () => {
   test('allocates an address from the internal subnet on first generate', async () => {
-    const result = await ensureDnsIngressIp('technitium', wantsIngress, db);
+    const result = await ensureIngressIps('technitium', wantsIngress, db);
 
     expect(result.success).toBe(true);
     expect(storedIp('technitium')).toMatch(/^10\.226\.1\.\d+$/);
@@ -54,21 +59,21 @@ describe('ensureDnsIngressIp', () => {
   test('REUSES the same address on a second generate', async () => {
     // The guard itself. Re-allocating here moves the resolver's DNAT ingress
     // every time the module is regenerated, and nothing reports a problem.
-    await ensureDnsIngressIp('technitium', wantsIngress, db);
+    await ensureIngressIps('technitium', wantsIngress, db);
     const first = storedIp('technitium');
 
-    await ensureDnsIngressIp('technitium', wantsIngress, db);
+    await ensureIngressIps('technitium', wantsIngress, db);
     const second = storedIp('technitium');
 
     expect(second).toBe(first);
   });
 
   test('stays stable across many generates, not just two', async () => {
-    await ensureDnsIngressIp('technitium', wantsIngress, db);
+    await ensureIngressIps('technitium', wantsIngress, db);
     const first = storedIp('technitium');
 
     for (let i = 0; i < 5; i++) {
-      await ensureDnsIngressIp('technitium', wantsIngress, db);
+      await ensureIngressIps('technitium', wantsIngress, db);
     }
 
     expect(storedIp('technitium')).toBe(first);
@@ -77,7 +82,7 @@ describe('ensureDnsIngressIp', () => {
   test('RESERVES the address, so it is never handed out to something else', async () => {
     // Allocation without reservation is the same bug one step later: a
     // container gets the resolver's ingress address and DNS goes dark.
-    await ensureDnsIngressIp('technitium', wantsIngress, db);
+    await ensureIngressIps('technitium', wantsIngress, db);
     const ip = storedIp('technitium');
 
     const reserved = db.$client
@@ -85,20 +90,20 @@ describe('ensureDnsIngressIp', () => {
       .get(ip ?? '') as { ip_start: string; reason: string } | undefined;
 
     expect(reserved?.ip_start).toBe(ip);
-    // The reason names the owner, so an operator reading the table can tell
-    // what an otherwise anonymous held address is for.
-    expect(reserved?.reason).toBe('dns-ingress:technitium');
+    // The reason names the owner AND the variable, so an operator reading the
+    // table can tell what an otherwise anonymous held address is for.
+    expect(reserved?.reason).toBe('ingress:technitium:dns_ingress_ip');
   });
 
   test('two modules get two different addresses', async () => {
-    await ensureDnsIngressIp('technitium', wantsIngress, db);
-    await ensureDnsIngressIp('knot-unbound-internal', wantsIngress, db);
+    await ensureIngressIps('technitium', wantsIngress, db);
+    await ensureIngressIps('knot-unbound-internal', wantsIngress, db);
 
     expect(storedIp('knot-unbound-internal')).not.toBe(storedIp('technitium'));
   });
 
   test('does nothing for a module that never asked for one', async () => {
-    const result = await ensureDnsIngressIp('caddy', {} as ModuleManifest, db);
+    const result = await ensureIngressIps('caddy', {} as ModuleManifest, db);
 
     expect(result.success).toBe(true);
     expect(storedIp('caddy')).toBeUndefined();
@@ -107,7 +112,7 @@ describe('ensureDnsIngressIp', () => {
   test('only `source: infrastructure` opts in', async () => {
     // A same-named variable the operator supplies is theirs to set; allocating
     // over it would overwrite an operator's deliberate choice.
-    await ensureDnsIngressIp('technitium', operatorSupplied, db);
+    await ensureIngressIps('technitium', operatorSupplied, db);
 
     expect(storedIp('technitium')).toBeUndefined();
   });
@@ -115,9 +120,20 @@ describe('ensureDnsIngressIp', () => {
   test('fails with an actionable message when the internal subnet is unset', async () => {
     db.$client.prepare('DELETE FROM system_config WHERE key = ?').run('network.internal.subnet');
 
-    const result = await ensureDnsIngressIp('technitium', wantsIngress, db);
+    const result = await ensureIngressIps('technitium', wantsIngress, db);
 
     expect(result.success).toBe(false);
     expect(result.success === false && result.error).toContain('network.internal.subnet');
   });
+
+  // celilo#879. The opt-in used to be the literal name `dns_ingress_ip`, so a
+  // dmz-resident WEB ingress had no way to ask for the same treatment — which
+  // is how `caddy-internal` came to be pinned into the `internal` zone with a
+  // manifest comment claiming a dmz ingress could not be reached from a LAN.
+  test('a `ingress_ip` variable opts in the same way, for a non-DNS ingress', async () => {
+    const result = await ensureIngressIps('caddy-internal', wantsWebIngress, db);
+
+    expect(result.success).toBe(true);
+    expect(storedIp('caddy-internal', 'ingress_ip')).toMatch(/^10\.226\.1\.\d+$/);
+  });
 });