@celilo/cli 1.1.0 → 1.3.0

package/src/services/audit/browser-pin.ts

@@ -0,0 +1,185 @@
+/**
+ * Browser pin-drift check (managed-browser-runtime D9).
+ *
+ * A module bundles its own `playwright-core`, and celilo provisions the
+ * browser binary. Under D2 the consumer passes an explicit
+ * `executablePath`, so a client bump can no longer move the browser out
+ * from under it — the hard failure that started that change cannot recur.
+ * What remains is softer: a client several minor versions from the binary's
+ * build drives it over a protocol the two were versioned together. Usually
+ * fine; not guaranteed.
+ *
+ * So this WARNS and never blocks (D9 / task 4.2).
+ *
+ * **It compares REVISIONS, not version strings.** The revision is what
+ * actually has to match a build, and each `playwright-core` states its own
+ * in the `browsers.json` inside the package — which is where 1193 and 1223
+ * came from. Reading it out of the bundle is what keeps this honest and
+ * means nobody maintains a version→revision table that will rot.
+ *
+ * Like `system doctor` (D4), it reads the bundle and the descriptor and
+ * never asks Playwright which executable it would use: that reports the
+ * full browser regardless of what a headless launch would open.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { resolveBrowser } from '@celilo/capabilities';
+import type { ModuleManifest } from '../../manifest/schema';
+import type { DriftFinding } from './types';
+
+/** What a module bundles, already read off disk. */
+export interface BundledBrowserClient {
+  moduleId: string;
+  /** The bundled `playwright-core` version, e.g. `1.60.0`. */
+  clientVersion: string;
+  /** The chromium-headless-shell revision that client expects, e.g. `1223`. */
+  expectedRevision: string;
+}
+
+export interface BrowserPinAuditDeps {
+  /**
+   * Modules that bundle a browser client. A module with none contributes
+   * nothing — most modules never launch a browser.
+   */
+  consumers: BundledBrowserClient[];
+  /**
+   * The provisioned browser, or `null` when this host has none.
+   *
+   * Null means silence, not a finding: installation is opt-in, so a host
+   * without a browser is the normal case and `system doctor` is already
+   * the place that reports its absence.
+   */
+  provisioned: { revision: string; playwrightVersion: string } | null;
+}
+
+export async function auditBrowserPin(deps: BrowserPinAuditDeps): Promise<DriftFinding[]> {
+  const { provisioned } = deps;
+  if (!provisioned) return [];
+
+  const findings: DriftFinding[] = [];
+  for (const consumer of deps.consumers) {
+    if (consumer.expectedRevision === provisioned.revision) continue;
+
+    // Any difference is reported. A "how far apart is too far" threshold
+    // would be a tuning knob with no evidence behind it — the revision is
+    // the thing that has to match a build, so it either does or it does not.
+    findings.push({
+      category: 'browser_pin',
+      severity: 'drift',
+      code: 'browser_client_revision_drift',
+      subject: consumer.moduleId,
+      message:
+        `${consumer.moduleId} bundles playwright-core ${consumer.clientVersion}, which expects ` +
+        `chromium revision ${consumer.expectedRevision}, but this host has revision ` +
+        `${provisioned.revision} (installed for playwright ${provisioned.playwrightVersion}).`,
+      details:
+        'Not a failure: the module passes an explicit executablePath, so it launches the ' +
+        'installed browser regardless of which revision its client expects. The risk is ' +
+        'protocol skew — a client far from its browser build drives it over a protocol the ' +
+        'two were versioned together.',
+      remediation:
+        `Align them: either republish ${consumer.moduleId} against playwright-core ` +
+        `${provisioned.playwrightVersion}, or set celilo-mgmt's playwright_version to ` +
+        `${consumer.clientVersion} and redeploy it.`,
+      actionable: false,
+    });
+  }
+  return findings;
+}
+
+/**
+ * Read the browser client a module bundles, or `null` when it bundles none.
+ *
+ * Searches beside each hook script rather than walking the module tree:
+ * `scripts/node_modules` is where a module's hook runtime is bundled, and
+ * the manifest's own hook list is the authoritative statement of where its
+ * hook code lives. A module laying its hooks out differently
+ * (`celilo/scripts/…`, as the one real browser consumer does) is therefore
+ * found without hardcoding either layout.
+ */
+export function readBundledBrowserClient(
+  moduleId: string,
+  sourcePath: string,
+  hookScripts: string[],
+): BundledBrowserClient | null {
+  const searched = new Set<string>([join(sourcePath, 'scripts')]);
+  for (const script of hookScripts) {
+    searched.add(dirname(join(sourcePath, script)));
+  }
+
+  for (const dir of searched) {
+    const pkgRoot = join(dir, 'node_modules', 'playwright-core');
+    const browsers = join(pkgRoot, 'browsers.json');
+    if (!existsSync(browsers)) continue;
+
+    const expectedRevision = revisionFor(browsers, 'chromium-headless-shell');
+    if (!expectedRevision) continue;
+
+    return {
+      moduleId,
+      clientVersion: packageVersion(join(pkgRoot, 'package.json')) ?? 'unknown',
+      expectedRevision,
+    };
+  }
+  return null;
+}
+
+/**
+ * The revision a `playwright-core` states for a browser, from the
+ * `browsers.json` inside the package. Never a lookup table — the package
+ * is the only thing that knows, and a table would rot silently.
+ */
+function revisionFor(browsersJsonPath: string, browserName: string): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(browsersJsonPath, 'utf-8')) as {
+      browsers?: Array<{ name?: string; revision?: string | number }>;
+    };
+    const entry = parsed.browsers?.find((b) => b.name === browserName);
+    return entry?.revision === undefined ? null : String(entry.revision);
+  } catch {
+    return null;
+  }
+}
+
+function packageVersion(packageJsonPath: string): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as { version?: string };
+    return parsed.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Gather this check's inputs from the module store and the provisioned
+ * browser's descriptor.
+ *
+ * Lives here rather than in the CLI so the two `AuditDeps` builders stay
+ * one line each and cannot drift apart — they already each carry their own
+ * copy of every other category's wiring.
+ */
+export function collectBrowserPinDeps(
+  modules: Array<{ id: string; sourcePath: string; manifestData: unknown }>,
+): BrowserPinAuditDeps {
+  const consumers: BundledBrowserClient[] = [];
+  for (const module of modules) {
+    const manifest = module.manifestData as ModuleManifest | undefined;
+    const hookScripts = Object.values(manifest?.hooks ?? {})
+      .map((hook) => (hook as { script?: string } | undefined)?.script)
+      .filter((script): script is string => typeof script === 'string');
+    const bundled = readBundledBrowserClient(module.id, module.sourcePath, hookScripts);
+    if (bundled) consumers.push(bundled);
+  }
+
+  let provisioned: BrowserPinAuditDeps['provisioned'] = null;
+  try {
+    const browser = resolveBrowser();
+    provisioned = { revision: browser.revision, playwrightVersion: browser.playwrightVersion };
+  } catch {
+    // No browser on this host — the check stays silent. `system doctor`
+    // is where an absent browser is reported, not here.
+  }
+
+  return { consumers, provisioned };
+}

package/src/services/audit/index.test.ts

@@ -15,6 +15,7 @@ const emptyDeps = {
     applied: () => [],
     db: fakeDb,
   },
+  browserPin: { consumers: [], provisioned: null },
   capabilityAbi: { modules: [] },
   terraformPlan: {
     modules: [],

package/src/services/audit/index.ts

@@ -15,6 +15,7 @@ import {
   auditAbandonedOperations,
 } from './abandoned-operations';
 import { type BackupsAuditDeps, auditBackups } from './backups';
+import { type BrowserPinAuditDeps, auditBrowserPin } from './browser-pin';
 import { type CapabilityAbiAuditDeps, auditCapabilityAbi } from './capability-abi';
 import { type CliVersionAuditDeps, auditCliVersion } from './cli-version';
 import { type HealthAuditDeps, auditHealth } from './health';
@@ -48,6 +49,7 @@ export interface AuditDeps {
   cliVersion: CliVersionAuditDeps;
   schema: SchemaAuditDeps;
   capabilityAbi: CapabilityAbiAuditDeps;
+  browserPin: BrowserPinAuditDeps;
   terraformPlan: TerraformPlanAuditDeps;
   moduleVersions: ModuleVersionsAuditDeps;
   moduleConfigs: ModuleConfigsAuditDeps;
@@ -101,6 +103,7 @@ export async function runAudit(
     wrap('cli_version', auditCliVersion(deps.cliVersion)),
     wrap('schema', auditSchema(deps.schema)),
     wrap('capability_abi', auditCapabilityAbi(deps.capabilityAbi)),
+    wrap('browser_pin', auditBrowserPin(deps.browserPin)),
     wrap('terraform_plan', auditTerraformPlan(deps.terraformPlan)),
     wrap('module_versions', auditModuleVersions(deps.moduleVersions)),
     wrap('module_configs', auditModuleConfigs(deps.moduleConfigs)),

package/src/services/audit/types.ts

@@ -25,6 +25,7 @@ export type DriftCategory =
   | 'cli_version'
   | 'schema'
   | 'capability_abi'
+  | 'browser_pin'
   | 'terraform_plan'
   | 'module_versions'
   | 'module_configs'

package/src/services/deploy-ansible-recap.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Parsing Ansible's PLAY RECAP, and the one classification that must not be got
+ * wrong.
+ *
+ * `--check` is how `verifyAspectCoverage` asks a HOST whether an aspect is
+ * applied, instead of consulting a stored claim that it once ran (celilo#902
+ * design D6). The trap is that check mode does not evaluate a task it cannot
+ * support — it SKIPS it — so a role built from `command:` / `shell:` tasks can
+ * finish a check run reporting `changed=0` having never been applied at all.
+ *
+ * Read as a boolean ("no changes, therefore applied") that is a confidently
+ * clean answer about an unconverged host: the same failure shape as the stored
+ * verdict this approach exists to avoid, arriving by a different route. Hence
+ * three outcomes, and hence this file.
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { parseAnsibleRecap } from './deploy-ansible';
+
+const RECAP = `
+PLAY RECAP *********************************************************************
+caddy-int                  : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+vpn                        : ok=3    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+legacy-box                 : ok=1    changed=0    unreachable=0    failed=0    skipped=2    rescued=0    ignored=0
+dead-host                  : ok=0    changed=0    unreachable=1    failed=0    skipped=0    rescued=0    ignored=0
+`;
+
+describe('parseAnsibleRecap', () => {
+  it('reads every host line with its counters', () => {
+    const recaps = parseAnsibleRecap(RECAP);
+    expect(recaps.map((r) => r.host)).toEqual(['caddy-int', 'vpn', 'legacy-box', 'dead-host']);
+    expect(recaps[0]).toEqual({
+      host: 'caddy-int',
+      ok: 3,
+      changed: 0,
+      unreachable: 0,
+      failed: 0,
+      skipped: 0,
+    });
+  });
+
+  it('SKIPPED IS NOT UNCHANGED — the case that must never read as applied', () => {
+    // THE assertion this file exists for. `legacy-box` reports zero changes,
+    // which a two-state reading calls "applied". It is not: two of its tasks
+    // were never evaluated, so nothing about its convergence was measured.
+    // If this ever passes while a caller treats it as applied, celilo is once
+    // again confidently reporting a host it has not looked at.
+    const legacy = parseAnsibleRecap(RECAP).find((r) => r.host === 'legacy-box');
+    expect(legacy).toBeDefined();
+    expect(legacy?.changed).toBe(0);
+    expect(legacy?.skipped).toBeGreaterThan(0);
+  });
+
+  it('separates a host that could not be reached from one that was measured clean', () => {
+    const recaps = parseAnsibleRecap(RECAP);
+    expect(recaps.find((r) => r.host === 'dead-host')?.unreachable).toBe(1);
+    expect(recaps.find((r) => r.host === 'caddy-int')?.unreachable).toBe(0);
+  });
+
+  it('survives ANSI colour, which the progress filter leaves in', () => {
+    const coloured =
+      '\x1b[0;32mweb-01\x1b[0m                 : ok=5    changed=2    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0';
+    const [recap] = parseAnsibleRecap(coloured);
+    expect(recap.host).toBe('web-01');
+    expect(recap.changed).toBe(2);
+    expect(recap.skipped).toBe(1);
+  });
+
+  it('returns nothing for output with no recap, rather than inventing a clean one', () => {
+    // A run that produced no recap measured nothing. Callers must not read an
+    // empty array as "every host is fine" — verifyAspectCoverage classifies a
+    // host with no recap line as unknown for exactly this reason.
+    expect(parseAnsibleRecap('fatal: could not connect\n')).toEqual([]);
+    expect(parseAnsibleRecap('')).toEqual([]);
+  });
+});

package/src/services/deploy-ansible.ts

@@ -138,7 +138,7 @@ function parseAnsibleLine(line: string): string | null {
  */
 export async function executeAnsible(
   generatedPath: string,
-  options?: { noInteractive?: boolean },
+  options?: { noInteractive?: boolean; check?: boolean },
 ): Promise<AnsibleResult> {
   const ansibleDir = join(generatedPath, 'ansible');
   const inventoryPath = join(ansibleDir, 'inventory', 'hosts.ini');
@@ -161,6 +161,11 @@ export async function executeAnsible(
         shellEscape(inventoryPath),
         '--vault-password-file',
         shellEscape(passwordPath),
+        // `--check` evaluates the play without changing anything, so a caller
+        // can ask "is this already applied?" of the HOST rather than of a
+        // stored record of the host (celilo#902 design D6). One argument, not a
+        // second execution path — everything else about the run is identical.
+        ...(options?.check ? ['--check'] : []),
         shellEscape(playbookPath),
       ],
       cwd: ansibleDir,
@@ -200,3 +205,53 @@ export async function executeAnsible(
     await rm(tempDir, { recursive: true, force: true });
   }
 }
+
+/**
+ * One host's line from Ansible's `PLAY RECAP`.
+ *
+ *   web-01   : ok=5    changed=2    unreachable=0    failed=0    skipped=1  …
+ *
+ * `skipped` is the field that matters and the one it is easy not to look at. A
+ * task that does NOT support check mode is not evaluated — it is skipped, and
+ * reported as skipped rather than changed. So a role built from `command:` /
+ * `shell:` tasks finishes a `--check` run with `changed=0` having never been
+ * applied to the host at all. Read as a boolean that says "applied", which is a
+ * confidently clean answer about an unconverged system. Callers must treat
+ * `skipped > 0` as NOT MEASURED rather than as applied.
+ */
+export interface AnsibleHostRecap {
+  host: string;
+  ok: number;
+  changed: number;
+  unreachable: number;
+  failed: number;
+  skipped: number;
+}
+
+const RECAP_LINE =
+  /^(\S+)\s*:\s*ok=(\d+)\s+changed=(\d+)\s+unreachable=(\d+)\s+failed=(\d+)\s+skipped=(\d+)/;
+
+/**
+ * Parse every host line out of an Ansible run's `PLAY RECAP`.
+ *
+ * Tolerant of ANSI colour and of the recap appearing anywhere in the stream,
+ * because the output here has been through a progress filter. Lines that are
+ * not recap lines are ignored rather than throwing — a run that produced no
+ * recap at all returns an empty array, which callers must not read as success.
+ */
+export function parseAnsibleRecap(output: string): AnsibleHostRecap[] {
+  const recaps: AnsibleHostRecap[] = [];
+  for (const raw of output.split('\n')) {
+    const match = RECAP_LINE.exec(raw.replace(ANSI_ESCAPE, '').trim());
+    if (!match) continue;
+    recaps.push({
+      host: match[1],
+      ok: Number(match[2]),
+      changed: Number(match[3]),
+      unreachable: Number(match[4]),
+      failed: Number(match[5]),
+      skipped: Number(match[6]),
+    });
+  }
+  return recaps;
+}

package/src/services/health-runner.ts

@@ -31,6 +31,16 @@ export interface HealthCheckResult {
   status: 'healthy' | 'degraded' | 'unhealthy' | 'no-checks' | 'error';
   checks: HealthCheckItem[];
   error?: string;
+  /**
+   * Files the hook wrote to its per-run artifact directory.
+   *
+   * This path is the one that runs UNATTENDED every fifteen minutes, and
+   * it used to drop `HookResult`'s artifacts on the floor entirely — the
+   * on-demand paths (`module run-hook`, deploy) surfaced them and this one
+   * did not, so the artifacts were discarded exactly when nobody was
+   * watching to re-run the check by hand.
+   */
+  artifactPaths?: string[];
 }
 
 export interface HealthCheckOptions {
@@ -191,11 +201,15 @@ export async function runModuleHealthCheck(
   presentation.finish(hookResult.success);
 
   if (!hookResult.success) {
+    // Artifacts matter MOST here: the hook died, so there are no named
+    // checks to explain why, and whatever it managed to write is all the
+    // operator gets.
     return {
       moduleId,
       status: 'error',
       checks: [],
       error: hookResult.error,
+      artifactPaths: hookResult.artifactPaths,
     };
   }
 
@@ -220,7 +234,7 @@ export async function runModuleHealthCheck(
     db.update(modules).set({ state: nextState }).where(eq(modules.id, moduleId)).run();
   }
 
-  return { moduleId, status, checks };
+  return { moduleId, status, checks, artifactPaths: hookResult.artifactPaths };
 }
 
 /**

package/src/services/module-deploy.ts

@@ -15,6 +15,7 @@ import { capabilities, machines, modules } from '../db/schema';
 import { loadCapabilityFunctions } from '../hooks/capability-loader';
 import { invokeHook } from '../hooks/executor';
 import { createGaugeLogger } from '../hooks/logger';
+import { describeArtifacts } from '../hooks/types';
 import type { HookDefinition, HookLogger, HookResult } from '../hooks/types';
 import { type ModuleManifest, getSingularSystemSpec } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
@@ -624,10 +625,9 @@ async function deployModuleImpl(
 
         if (!hookResult.success) {
           gauge.stop(false);
-          let errorMsg = hookResult.error || 'Configuration validation failed';
-          if (hookResult.screenshotPath) {
-            errorMsg += `\n\nScreenshot saved: ${hookResult.screenshotPath}`;
-          }
+          const errorMsg =
+            (hookResult.error || 'Configuration validation failed') +
+            describeArtifacts(hookResult.artifactPaths);
           return {
             success: false,
             error: errorMsg,
@@ -932,19 +932,17 @@ async function deployModuleImpl(
     // provider type (machine / proxmox IPAM / DO outputs). This populates
     // ctx.systems for on_install and is the source of truth for system.created
     // and DNS (openspec/specs/module-systems-addressing/spec.md). API-only modules record none.
-    {
-      const { recordDeployedSystemForModule } = await import('./deployed-systems');
-      const recorded = await recordDeployedSystemForModule(
-        moduleId,
-        manifest,
-        plan.infrastructure,
-        db,
+    const { recordDeployedSystemForModule } = await import('./deployed-systems');
+    const recordedSystems = await recordDeployedSystemForModule(
+      moduleId,
+      manifest,
+      plan.infrastructure,
+      db,
+    );
+    if (recordedSystems.length > 0) {
+      log.success(
+        `Recorded ${recordedSystems.length} deployed system(s): ${recordedSystems.map((s) => `${s.hostname} (${s.ipv4_address})`).join(', ')}`,
       );
-      if (recorded.length > 0) {
-        log.success(
-          `Recorded ${recorded.length} deployed system(s): ${recorded.map((s) => `${s.hostname} (${s.ipv4_address})`).join(', ')}`,
-        );
-      }
     }
 
     if (Object.keys(resolution.resolved).length > 0) {
@@ -1152,6 +1150,62 @@ async function deployModuleImpl(
       phases.sshWait = true;
     }
 
+    // Apply the fleet's aspects to the systems THIS deploy just created, before
+    // the module's own playbook runs against them (celilo#902, design D3).
+    //
+    // A base-module aspect fans out to the systems that exist when its PROVIDER
+    // deploys and to nothing afterwards, so a host provisioned here would keep
+    // its boot-time /etc/resolv.conf and be unable to resolve any fleet-internal
+    // name — silently, with a green deploy on top. This is the inbound half.
+    //
+    // Placed here on purpose: after `waitForSSH`, so the host is proven
+    // reachable and the aspect's Ansible does not fail UNREACHABLE on a
+    // still-booting LXC; before `executeAnsible`, so the module's playbook and
+    // its `on_install` hook see a correctly configured host rather than
+    // configuring themselves on top of a broken one.
+    //
+    // FAILURE IS FATAL HERE, and that is DELIBERATELY the opposite of the
+    // outbound direction below, where a failed fan-out never fails the
+    // provider's own deploy (D4). The asymmetry is the point and is not an
+    // oversight to be tidied up: an inbound aspect is a PREREQUISITE of the host
+    // being configured right now, so continuing would configure a host celilo
+    // knows is misconfigured — exactly the outcome celilo#902 produced. Nothing
+    // is rolled back: the rows, the guest and the IPAM allocation all persist,
+    // and re-running this deploy after fixing the cause converges on the same
+    // system.
+    if (recordedSystems.length > 0) {
+      const { reconcileAspectsForSystems } = await import('./aspect-runner');
+      const reconcile = await reconcileAspectsForSystems({
+        systems: recordedSystems.map((sys) => ({ hostname: sys.hostname, zone: sys.zone })),
+        db,
+        // This module's own aspect is fanned out by `on_install` below, across
+        // the whole fleet rather than only these hosts.
+        excludeModuleIds: [moduleId],
+      });
+      if (reconcile.failures.length > 0) {
+        // Name the PROVIDING module, not the one being deployed — otherwise
+        // this reads as a defect in `moduleId` and the operator debugs the
+        // wrong thing.
+        const detail = reconcile.failures
+          .map(
+            (f) =>
+              `  ✗ '${f.providerModuleId}' aspect '${f.role}' on ${f.hostnames.join(', ')}: ${f.error ?? 'unknown error'}`,
+          )
+          .join('\n');
+        return {
+          success: false,
+          phases,
+          error: `Fleet aspects could not be applied to the system(s) this deploy created:\n${detail}\nThese are prerequisites, so '${moduleId}' was not configured on top of them. Fix the cause and re-run \`celilo module deploy ${moduleId}\` — the system is kept and will be reused.`,
+        };
+      }
+      const applied = reconcile.outcomes.filter((o) => o.ran);
+      if (applied.length > 0) {
+        log.success(
+          `Applied ${applied.length} fleet aspect(s) to the new system(s): ${applied.map((o) => `${o.providerModuleId}/${o.role}`).join(', ')}`,
+        );
+      }
+    }
+
     let machineId: string | undefined;
     if (plan.infrastructure?.type === 'machine' && plan.infrastructure.machineId) {
       // The management box deploys to ITSELF (registered in the machine pool as

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

@@ -72,6 +72,7 @@ const cleanAudit: AuditDeps = {
   cliVersion: { installedVersion: '0.1.5', fetcher: async () => '0.1.5' },
   schema: { journal: () => null, applied: () => [], db: fakeDb },
   capabilityAbi: { modules: [] },
+  browserPin: { consumers: [], provisioned: null },
   terraformPlan: { modules: [], run: async () => ({ exitCode: 0, stdout: '', stderr: '' }) },
   moduleVersions: { installed: [], fetcher: async () => ({ latest: null }) },
   moduleConfigs: { modules: [] },

package/src/system/browser-provisioning.test.ts

@@ -0,0 +1,67 @@
+/**
+ * The browser runtime is described in two languages: an Ansible role
+ * installs it, and TypeScript reads it back. Nothing in either language
+ * can see the other, so these are the assertions that keep them agreeing.
+ *
+ * Both facts here have already drifted in other pairs of files in this
+ * repo; neither drift is visible in a diff.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  BROWSER_DESCRIPTOR_PATH,
+  BROWSER_EXECUTABLE_PATH,
+  BROWSER_ROOT,
+} from '@celilo/capabilities';
+
+const MODULE_ROOT = join(import.meta.dir, '../../../../modules/celilo-mgmt');
+
+function read(relativePath: string): string {
+  return readFileSync(join(MODULE_ROOT, relativePath), 'utf-8');
+}
+
+describe('celilo-mgmt browser provisioning', () => {
+  test('the playbook stamps the module version the manifest declares', () => {
+    // The descriptor records which celilo-mgmt wrote it. No template prefix
+    // exposes a module's own version ($self: resolves module CONFIG), so
+    // the playbook carries a literal — and this is what stops it rotting.
+    const manifestVersion = read('manifest.yml').match(/^version:\s*(\S+)$/m)?.[1];
+    const playbookVersion = read('ansible/playbook.yml.tpl').match(
+      /celilo_mgmt_version:\s*"([^"]+)"/,
+    )?.[1];
+
+    expect(manifestVersion).toBeTruthy();
+    expect(playbookVersion).toBe(manifestVersion as string);
+  });
+
+  test('the role installs into the tree the resolver reads', () => {
+    const debian = read('ansible/roles/celilo-mgmt/tasks/debian.yml');
+
+    expect(BROWSER_EXECUTABLE_PATH).toBe(`${BROWSER_ROOT}/current/chrome`);
+    expect(debian).toContain(`PLAYWRIGHT_BROWSERS_PATH: ${BROWSER_ROOT}`);
+    expect(debian).toContain(`dest: ${BROWSER_EXECUTABLE_PATH}`);
+    expect(debian).toContain(`dest: ${BROWSER_DESCRIPTOR_PATH}`);
+  });
+
+  test('the install is gated, so a default host downloads nothing', () => {
+    const debian = read('ansible/roles/celilo-mgmt/tasks/debian.yml');
+    const manifest = read('manifest.yml');
+
+    expect(debian).toContain('when: celilo_install_browser | bool');
+    // The gate is worthless if the flag defaults on: the e2e topology has
+    // no real internet, and the browser comes from an external CDN.
+    expect(manifest).toMatch(/name: install_browser[\s\S]*?default: false/);
+  });
+
+  test('the role provisions the headless shell, not full Chromium', () => {
+    // Reversed after measuring celilo-mgr: both builds there are headless
+    // shells and chromium.launch() has been driving one in production all
+    // along. Provisioning the full browser would change what works.
+    const debian = read('ansible/roles/celilo-mgmt/tasks/debian.yml');
+
+    expect(debian).toContain('install chromium-headless-shell');
+    expect(debian).toContain("'flavor': 'headless-shell'");
+  });
+});