@celilo/cli 1.1.0 → 1.3.0

package/src/system/prereqs.test.ts

@@ -14,6 +14,8 @@
  */
 
 import { describe, expect, test } from 'bun:test';
+import { unlinkSync, writeFileSync } from 'node:fs';
+import { BROWSER_EXECUTABLE_PATH } from '@celilo/capabilities';
 import {
   PREREQUISITES,
   checkPrerequisite,
@@ -52,6 +54,8 @@ describe('PREREQUISITES table', () => {
     expect(names).toContain('git');
     expect(names).toContain('curl');
     expect(names).toContain('unzip');
+    expect(names).toContain('browser');
+    expect(names).toContain('fonts');
   });
 });
 
@@ -313,6 +317,75 @@ describe('checkPrerequisite', () => {
   });
 });
 
+// ── Absolute-path prerequisites (the browser) ─────────────────────────
+
+describe('absolute-path prerequisites', () => {
+  test('a real executable at an absolute path is present, with its version', () => {
+    // `bun --version` prints a bare semver, and Bun.which finds a real path
+    // for it — so this exercises the absolute-path branch end to end.
+    const bunPath = Bun.which('bun');
+    if (!bunPath) throw new Error('bun is not on PATH');
+    const result = checkPrerequisite({
+      name: 'browser',
+      description: 'stand-in for the provisioned browser',
+      command: bunPath,
+      versionFlag: '--version',
+      versionRegex: /(\d+\.\d+\.\d+)/,
+      minVersion: null,
+    });
+    expect(result.present).toBe(true);
+    expect(result.binaryPath).toBe(bunPath);
+    expect(result.version).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+
+  test('a DIRECTORY at the declared path is not present', () => {
+    // The case that motivates the whole check: a build directory with no
+    // binary in it satisfies a path test and then fails at launch.
+    const result = checkPrerequisite({
+      name: 'browser',
+      description: 'stand-in for the provisioned browser',
+      command: '/tmp',
+      versionFlag: '--version',
+      versionRegex: /(\d+\.\d+\.\d+)/,
+      minVersion: null,
+    });
+    expect(result.present).toBe(false);
+    expect(result.binaryPath).toBeNull();
+  });
+
+  test('a non-executable file at the declared path is not present', () => {
+    const path = `/tmp/celilo-prereq-not-executable-${process.pid}`;
+    writeFileSync(path, 'not a browser', { mode: 0o644 });
+    try {
+      const result = checkPrerequisite({
+        name: 'browser',
+        description: 'stand-in for the provisioned browser',
+        command: path,
+        versionFlag: '--version',
+        versionRegex: /(\d+\.\d+\.\d+)/,
+        minVersion: null,
+      });
+      expect(result.present).toBe(false);
+    } finally {
+      unlinkSync(path);
+    }
+  });
+
+  test('the browser row names install_browser as its remedy', () => {
+    const spec = PREREQUISITES.find((p) => p.name === 'browser');
+    if (!spec) throw new Error('browser spec missing');
+    expect(spec.command).toBe(BROWSER_EXECUTABLE_PATH);
+    expect(getInstallHint('browser', 'apt')).toContain('install_browser');
+  });
+
+  test('fc-match output yields the resolved font family', () => {
+    const spec = PREREQUISITES.find((p) => p.name === 'fonts');
+    if (!spec) throw new Error('fonts spec missing');
+    const sample = 'DejaVuSans.ttf: "DejaVu Sans" "Book"';
+    expect(sample.match(spec.versionRegex)?.[1]).toBe('DejaVu Sans');
+  });
+});
+
 // ── failingPrerequisites ──────────────────────────────────────────────
 
 describe('failingPrerequisites', () => {

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/ingress-ip.test.ts

@@ -10,6 +10,7 @@
 
 import { beforeEach, describe, expect, test } from 'bun:test';
 import type { DbClient } from '../db/client';
+import { deallocateForModule } from '../ipam/auto-allocator';
 import type { ModuleManifest } from '../manifest/schema';
 import { getModuleConfigValue } from '../services/module-config';
 import { setupTestDatabase } from '../test-utils/database';
@@ -41,6 +42,22 @@ const storedIp = (moduleId: string, variable = 'dns_ingress_ip'): string | undef
   return typeof value === 'string' ? value : undefined;
 };
 
+/** Reservation reasons currently held, so a test can assert one is GONE. */
+const reservedReasons = (): string[] =>
+  (db.$client.prepare('SELECT reason FROM ip_reservations').all() as Array<{ reason: string }>).map(
+    (r) => r.reason,
+  );
+
+/**
+ * What `module remove` does to a module's IPAM state. Removal also drops the
+ * module row, which cascades the stored config value away — the tests below
+ * clear it by hand so a "reinstall" starts from the same state a real one does.
+ */
+const removeModule = async (moduleId: string): Promise<void> => {
+  await deallocateForModule(moduleId, db);
+  db.$client.prepare('DELETE FROM module_configs WHERE module_id = ?').run(moduleId);
+};
+
 beforeEach(async () => {
   db = await setupTestDatabase();
   db.$client
@@ -137,3 +154,94 @@ describe('ensureIngressIps', () => {
     expect(storedIp('caddy-internal', 'ingress_ip')).toMatch(/^10\.226\.1\.\d+$/);
   });
 });
+
+/**
+ * The release half (celilo#892). `ensureIngressIps` reserved the address and
+ * nothing ever gave it back, so every install/remove cycle permanently burned
+ * one address from the internal static range — silently, and with no way to
+ * tell the dead row from the live one, since both carry the same reason.
+ *
+ * On celilo-mgr this left 192.168.0.153 and .154 both reading
+ * `ingress:caddy-internal:ingress_ip`, only one of them real.
+ */
+describe('releasing ingress IPs on module removal', () => {
+  test('removing a module releases its ingress reservation', async () => {
+    await ensureIngressIps('technitium', wantsIngress, db);
+    expect(reservedReasons()).toContain('ingress:technitium:dns_ingress_ip');
+
+    await removeModule('technitium');
+
+    expect(reservedReasons()).not.toContain('ingress:technitium:dns_ingress_ip');
+  });
+
+  test('a reinstall REUSES the address instead of advancing to the next one', async () => {
+    // The user-visible symptom: without the release, the range walks forward
+    // one address per install/remove cycle until it runs out.
+    await ensureIngressIps('technitium', wantsIngress, db);
+    const first = storedIp('technitium');
+
+    await removeModule('technitium');
+    await ensureIngressIps('technitium', wantsIngress, db);
+
+    expect(storedIp('technitium')).toBe(first);
+  });
+
+  test('the exclusion count returns to its pre-install value', async () => {
+    const before = reservedReasons().length;
+
+    await ensureIngressIps('caddy-internal', wantsWebIngress, db);
+    expect(reservedReasons().length).toBe(before + 1);
+
+    await removeModule('caddy-internal');
+
+    expect(reservedReasons().length).toBe(before);
+  });
+
+  test('releases the LEGACY `dns-ingress:<module>` reason too', async () => {
+    // Written before celilo#879 generalized the reason format. celilo-mgr holds
+    // one of these right now, so a fix matching only the current format leaves
+    // the installed base leaking.
+    db.$client
+      .prepare('INSERT INTO ip_reservations (ip_start, zone, reason) VALUES (?, ?, ?)')
+      .run('10.226.1.42', 'internal', 'dns-ingress:technitium');
+
+    await removeModule('technitium');
+
+    expect(reservedReasons()).not.toContain('dns-ingress:technitium');
+  });
+
+  test('releases a module holding BOTH formats at once', async () => {
+    // An upgraded installation: the legacy row from before celilo#879 plus a
+    // current one written since. Releasing only one still leaks.
+    await ensureIngressIps('technitium', wantsIngress, db);
+    db.$client
+      .prepare('INSERT INTO ip_reservations (ip_start, zone, reason) VALUES (?, ?, ?)')
+      .run('10.226.1.42', 'internal', 'dns-ingress:technitium');
+
+    await removeModule('technitium');
+
+    expect(reservedReasons()).toEqual([]);
+  });
+
+  test("leaves OTHER modules' reservations alone", async () => {
+    await ensureIngressIps('technitium', wantsIngress, db);
+    await ensureIngressIps('knot-unbound-internal', wantsIngress, db);
+
+    await removeModule('technitium');
+
+    expect(reservedReasons()).toEqual(['ingress:knot-unbound-internal:dns_ingress_ip']);
+  });
+
+  test('releases even when the module has no zone-IP allocation', async () => {
+    // `deallocateForModule` returns early when there is no `ip_allocations`
+    // row, which is the normal case for a module deployed onto a machine
+    // rather than a celilo-provisioned container. Releasing after that early
+    // return would skip exactly the modules that leak.
+    await ensureIngressIps('caddy-internal', wantsWebIngress, db);
+
+    const hadAllocation = await deallocateForModule('caddy-internal', db);
+
+    expect(hadAllocation).toBe(false);
+    expect(reservedReasons()).toEqual([]);
+  });
+});