@celilo/cli 1.1.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