@celilo/cli 2.3.0 → 3.0.0

package/src/services/build-bus/receiver-daemon.ts

@@ -0,0 +1,355 @@
+/**
+ * Supervisor-unit installer for the build-bus webhook receiver —
+ * the `celilo subscribers serve` daemon. Linux gets a systemd unit;
+ * macOS gets a launchd plist. Mirrors `events-daemon.ts` (the
+ * dispatcher's installer) shape-for-shape so the two daemons read as
+ * one family: render via `planReceiverInstall` (the CLI's `--print`
+ * mode and the celilo-mgmt Ansible role), write via
+ * `installReceiverDaemon`, remove via `uninstallReceiverDaemon`.
+ *
+ * Why this exists: celilo#1304. The receiver shipped as a hand-run
+ * daemon — nothing in any deploy installed it, so on a management
+ * host the dispatcher ran while the receiver did not, and
+ * `celilo system doctor` could only say "start the receiver under a
+ * supervisor unit". The dispatcher got an installer (ISS-0086); this
+ * is the receiver's.
+ *
+ * Two differences from the dispatcher unit, both deliberate:
+ *
+ * 1. `--no-dispatch` is the DEFAULT. On the management plane the
+ *    standing dispatcher (`celilo-events.service`) owns dispatch; a
+ *    second dispatcher polling the same SQLite bus is the exact
+ *    two-daemons-one-bus shape that produced celilo#580/#610. Boxes
+ *    with no events daemon can render a combined unit with
+ *    `--dispatch` instead.
+ *
+ * 2. The unit file carries a secret (the shared HMAC secret the
+ *    publisher signs webhooks with), so it is written mode 0600 and
+ *    the secret goes in an `Environment=` line / EnvironmentVariables
+ *    dict rather than ExecStart — process args are readable in `ps`,
+ *    unit environments are not.
+ */
+
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { getEventBusPath } from '../../config/paths';
+import {
+  type SupervisorPlatform,
+  type SupervisorScope,
+  detectPlatform,
+  resolveCeliloPath,
+  resolveRunAsUser,
+} from '../events-daemon';
+
+export const RECEIVER_UNIT_NAME = 'celilo-build-bus-receiver.service';
+export const RECEIVER_LAUNCHD_LABEL = 'com.celilo.build-bus-receiver';
+export const DEFAULT_RECEIVER_PORT = 8123;
+
+export interface ReceiverInstallOptions {
+  /** Shared HMAC secret publishers sign webhooks with. Required. */
+  secret?: string;
+  /** TCP port the receiver listens on. Default 8123. */
+  port?: number;
+  /** Unit scope. Defaults to `user`. */
+  scope?: SupervisorScope;
+  /**
+   * Render the COMBINED daemon (receiver + in-process dispatcher).
+   * Default false — see the module comment for why the standing
+   * dispatcher must own dispatch on the management plane.
+   */
+  dispatch?: boolean;
+  celiloPath?: string;
+  /** Override platform detection. Mainly for tests. */
+  platform?: SupervisorPlatform;
+  /** Override the home directory used to compute install paths. */
+  home?: string;
+  /** Run-as user for system-scope units; defaults to the state-dir owner. */
+  runAsUser?: string;
+  /** Prefix for system-scope paths. Test seam — see getReceiverUnitPath. */
+  systemRoot?: string;
+}
+
+export interface ReceiverInstallPlan {
+  platform: SupervisorPlatform;
+  scope: SupervisorScope;
+  unitPath: string;
+  unitContent: string;
+  celiloPath: string;
+  port: number;
+  dispatch: boolean;
+  /** Set for system scope: the user the unit runs as. */
+  runAsUser?: string;
+  /** True when the OTHER scope already has a receiver unit installed. */
+  conflict?: { scope: SupervisorScope; unitPath: string };
+  nextSteps: string[];
+}
+
+export interface ReceiverUninstallResult {
+  platform: SupervisorPlatform;
+  scope: SupervisorScope;
+  unitPath: string;
+  removed: boolean;
+  nextSteps: string[];
+}
+
+interface UnitInputs {
+  celiloPath: string;
+  port: number;
+  secret: string;
+  scope: SupervisorScope;
+  dispatch: boolean;
+  /** Optional: only the launchd user-scope log paths read it. */
+  home?: string;
+  /** Required for system scope; ignored for user scope. */
+  runAsUser?: string;
+}
+
+export function getReceiverUnitPath(
+  platform: SupervisorPlatform,
+  home: string,
+  scope: SupervisorScope = 'user',
+  systemRoot = '/',
+): string {
+  if (platform === 'linux') {
+    return scope === 'system'
+      ? join(systemRoot, 'etc/systemd/system', RECEIVER_UNIT_NAME)
+      : join(home, '.config', 'systemd', 'user', RECEIVER_UNIT_NAME);
+  }
+  return scope === 'system'
+    ? join(systemRoot, 'Library/LaunchDaemons', `${RECEIVER_LAUNCHD_LABEL}.plist`)
+    : join(home, 'Library', 'LaunchAgents', `${RECEIVER_LAUNCHD_LABEL}.plist`);
+}
+
+export function renderReceiverSystemdUnit(input: UnitInputs): string {
+  const userLine = input.scope === 'system' && input.runAsUser ? `User=${input.runAsUser}\n` : '';
+  const dispatchFlag = input.dispatch ? '' : ' --no-dispatch';
+  const journalHint =
+    input.scope === 'system'
+      ? `journalctl -u ${RECEIVER_UNIT_NAME}`
+      : `journalctl --user -u ${RECEIVER_UNIT_NAME}`;
+  return `[Unit]
+Description=Celilo Build-Bus Webhook Receiver
+Documentation=https://github.com/psbanka/infra/blob/main/openspec/changes/build-bus-poll-cd/proposal.md
+After=network.target
+
+[Service]
+Type=simple
+${userLine}ExecStart=${input.celiloPath} subscribers serve --port ${input.port}${dispatchFlag}
+Restart=on-failure
+RestartSec=10s
+Environment=CELILO_BUS_SECRET=${input.secret}
+# stdout/stderr are captured by ${journalHint}.
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=${input.scope === 'system' ? 'multi-user.target' : 'default.target'}
+`;
+}
+
+export function renderReceiverLaunchdPlist(input: UnitInputs): string {
+  const home = input.home ?? homedir();
+  const logDir = input.scope === 'system' ? '/Library/Logs' : join(home, 'Library', 'Logs');
+  const userNameBlock =
+    input.scope === 'system' && input.runAsUser
+      ? `  <key>UserName</key>\n  <string>${input.runAsUser}</string>\n`
+      : '';
+  const dispatchFlag = input.dispatch ? '' : '\n    <string>--no-dispatch</string>';
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${RECEIVER_LAUNCHD_LABEL}</string>
+${userNameBlock}  <key>ProgramArguments</key>
+  <array>
+    <string>${input.celiloPath}</string>
+    <string>subscribers</string>
+    <string>serve</string>
+    <string>--port</string>
+    <string>${input.port}</string>${dispatchFlag}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>CELILO_BUS_SECRET</key>
+    <string>${input.secret}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${join(logDir, 'celilo-build-bus-receiver.out.log')}</string>
+  <key>StandardErrorPath</key>
+  <string>${join(logDir, 'celilo-build-bus-receiver.err.log')}</string>
+</dict>
+</plist>
+`;
+}
+
+function otherScopeReceiverUnit(
+  platform: SupervisorPlatform,
+  home: string,
+  scope: SupervisorScope,
+  systemRoot?: string,
+): { scope: SupervisorScope; unitPath: string } | undefined {
+  const other = scope === 'user' ? 'system' : 'user';
+  const path = getReceiverUnitPath(platform, home, other, systemRoot);
+  return existsSync(path) ? { scope: other, unitPath: path } : undefined;
+}
+
+function nextStepsFor(
+  platform: SupervisorPlatform,
+  scope: SupervisorScope,
+  unitPath: string,
+): string[] {
+  if (platform === 'linux') {
+    return scope === 'system'
+      ? [
+          'Reload systemd:  sudo systemctl daemon-reload',
+          `Enable + start:  sudo systemctl enable --now ${RECEIVER_UNIT_NAME}`,
+          `Tail logs:       journalctl -u ${RECEIVER_UNIT_NAME} -f`,
+          `Status:          systemctl status ${RECEIVER_UNIT_NAME}`,
+        ]
+      : [
+          'Reload systemd:  systemctl --user daemon-reload',
+          `Enable + start:  systemctl --user enable --now ${RECEIVER_UNIT_NAME}`,
+          `Tail logs:       journalctl --user -u ${RECEIVER_UNIT_NAME} -f`,
+          `Status:          systemctl --user status ${RECEIVER_UNIT_NAME}`,
+        ];
+  }
+  return scope === 'system'
+    ? [
+        `Load + start:    sudo launchctl bootstrap system ${unitPath}`,
+        'Tail stdout:     tail -f /Library/Logs/celilo-build-bus-receiver.out.log',
+        'Tail stderr:     tail -f /Library/Logs/celilo-build-bus-receiver.err.log',
+        `Status:          sudo launchctl print system/${RECEIVER_LAUNCHD_LABEL}`,
+      ]
+    : [
+        `Load + start:    launchctl load -w ${unitPath}`,
+        'Tail stdout:     tail -f ~/Library/Logs/celilo-build-bus-receiver.out.log',
+        'Tail stderr:     tail -f ~/Library/Logs/celilo-build-bus-receiver.err.log',
+        `Status:          launchctl list | grep ${RECEIVER_LAUNCHD_LABEL}`,
+      ];
+}
+
+/**
+ * Resolve everything an install would do — platform, paths, run-as
+ * user, rendered unit content — WITHOUT writing anything. This is the
+ * single renderer behind the CLI's `--print` mode, which the
+ * celilo-mgmt Ansible role uses (the deb wrapper runs celilo as the
+ * unprivileged celilo user, so the role performs the root-owned write).
+ *
+ * The secret is REQUIRED and never defaulted: there is no safe
+ * invented value for a shared HMAC secret, and a receiver that starts
+ * with a secret the publisher does not know silently 401s every
+ * delivery. Render-only calls (`--print`) refuse on a missing secret
+ * rather than wedge the deploy that is trying to recover.
+ */
+export function planReceiverInstall(opts: ReceiverInstallOptions = {}): ReceiverInstallPlan {
+  const platform = opts.platform ?? detectPlatform();
+  const scope = opts.scope ?? 'user';
+  const home = opts.home ?? homedir();
+  const secret = opts.secret;
+  if (typeof secret !== 'string' || !secret) {
+    throw new Error(
+      'celilo subscribers install-daemon: a shared secret is required (--secret <hex> or CELILO_BUS_SECRET). The publisher signs webhooks with this same value — there is no safe default.',
+    );
+  }
+  const celiloPath = resolveCeliloPath(opts.celiloPath);
+  const port = opts.port ?? DEFAULT_RECEIVER_PORT;
+  const dispatch = opts.dispatch ?? false;
+  const runAsUser =
+    scope === 'system' ? resolveRunAsUser(getEventBusPath(), opts.runAsUser) : undefined;
+
+  const unitPath = getReceiverUnitPath(platform, home, scope, opts.systemRoot);
+  const unitInputs: UnitInputs = { celiloPath, port, secret, scope, dispatch, home, runAsUser };
+  const unitContent =
+    platform === 'linux'
+      ? renderReceiverSystemdUnit(unitInputs)
+      : renderReceiverLaunchdPlist(unitInputs);
+
+  return {
+    platform,
+    scope,
+    unitPath,
+    unitContent,
+    celiloPath,
+    port,
+    dispatch,
+    runAsUser,
+    conflict: otherScopeReceiverUnit(platform, home, scope, opts.systemRoot),
+    nextSteps: nextStepsFor(platform, scope, unitPath),
+  };
+}
+
+/**
+ * Write the supervisor unit file. Idempotent: rewrites if present.
+ * Mode 0600 — the file carries the shared HMAC secret.
+ *
+ * System scope writes root-owned paths (/etc/systemd/system,
+ * /Library/LaunchDaemons) — run as root or the write fails loudly.
+ */
+export function installReceiverDaemon(opts: ReceiverInstallOptions = {}): ReceiverInstallPlan {
+  const plan = planReceiverInstall(opts);
+  if (plan.conflict) {
+    throw new Error(
+      [
+        `celilo subscribers daemon: a ${plan.conflict.scope}-scope receiver unit is already installed at ${plan.conflict.unitPath}.`,
+        'Both scopes use the same unit name, so installing this one would create a SECOND receiver.',
+        `Remove the other first: \`celilo subscribers uninstall-daemon${plan.conflict.scope === 'system' ? ' --system' : ''}\`,`,
+        'or keep the existing one.',
+      ].join(' '),
+    );
+  }
+  mkdirSync(dirname(plan.unitPath), { recursive: true });
+  writeFileSync(plan.unitPath, plan.unitContent, { mode: 0o600 });
+  return plan;
+}
+
+export function uninstallReceiverDaemon(
+  opts: {
+    platform?: SupervisorPlatform;
+    scope?: SupervisorScope;
+    home?: string;
+    systemRoot?: string;
+  } = {},
+): ReceiverUninstallResult {
+  const platform = opts.platform ?? detectPlatform();
+  const scope = opts.scope ?? 'user';
+  const home = opts.home ?? homedir();
+  const unitPath = getReceiverUnitPath(platform, home, scope, opts.systemRoot);
+
+  let removed = false;
+  if (existsSync(unitPath)) {
+    unlinkSync(unitPath);
+    removed = true;
+  }
+
+  let nextSteps: string[];
+  if (!removed) {
+    nextSteps =
+      platform === 'linux'
+        ? ['No unit file present; nothing to clean up.']
+        : ['No plist present; nothing to clean up.'];
+  } else if (platform === 'linux') {
+    nextSteps =
+      scope === 'system'
+        ? [
+            `Disable + stop:  sudo systemctl disable --now ${RECEIVER_UNIT_NAME}`,
+            'Reload systemd:  sudo systemctl daemon-reload',
+          ]
+        : [
+            `Disable + stop:  systemctl --user disable --now ${RECEIVER_UNIT_NAME}`,
+            'Reload systemd:  systemctl --user daemon-reload',
+          ];
+  } else {
+    nextSteps =
+      scope === 'system'
+        ? [`Unload:          sudo launchctl bootout system/${RECEIVER_LAUNCHD_LABEL}`]
+        : [`Unload:          launchctl unload ${unitPath}`];
+  }
+
+  return { platform, scope, unitPath, removed, nextSteps };
+}

package/src/services/build-bus/self-update.ts

@@ -0,0 +1,156 @@
+/**
+ * Framework self-update on an upstream publish (module-orchestrator-primitives
+ * slice 7, tasks.md 7.2 / design D6).
+ *
+ * This was `modules/celilo-mgmt/scripts/on_upstream_publish.sh` — a
+ * module-declared bash hook spawned detached by the build-bus dispatcher with
+ * the whole of celilo's `process.env` (design D6's second execution path). The
+ * work is celilo replacing celilo's own binaries on the management host, which
+ * is class H one more time: none of it wanted to be a module hook, and the
+ * same publish event reaches this function in celilo's own process.
+ *
+ * The trigger survives; the execution path does not. The dispatcher calls
+ * `planSelfUpdate` on every verified PublishEvent and runs the update only
+ * where the control-plane module is installed — the same gate that decided
+ * whether celilo-mgmt's hook existed at all, since the module is deployed
+ * exactly once, on the management host.
+ *
+ * Pure planning (`planSelfUpdate`) is split from execution (`runSelfUpdate`)
+ * so a test can assert the match rules without spawning a package manager,
+ * and the package-manager calls are injectable (Rule 2.3) so no test touches
+ * the operator's real global install.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { PublishEvent } from '@celilo/event-bus/build-bus';
+
+/**
+ * The binary packages celilo keeps globally installed on the management host.
+ * Only these self-update: the other `@celilo/*` packages are transitive deps
+ * of the CLI's bundled install, have no standalone global binary, and a
+ * `bun add -g` of them would be a no-op. This was celilo-mgmt's manifest
+ * comment ("two entries instead of one packagePattern='@celilo/*'"); it moves
+ * here with the work.
+ */
+const BINARY_PACKAGES = {
+  '@celilo/cli': 'celilo',
+  '@celilo/e2e': 'cele2e',
+} as const satisfies Record<string, string>;
+
+export type BinaryPackage = keyof typeof BINARY_PACKAGES;
+
+/** What the update will do. Carries everything `runSelfUpdate` needs. */
+export interface SelfUpdatePlan {
+  packageName: BinaryPackage;
+  version: string;
+  /** The binary whose `--version` proves the update took. */
+  binary: (typeof BINARY_PACKAGES)[BinaryPackage];
+}
+
+/**
+ * Pure: does this publish event self-update the management host?
+ * The old manifest's match rules (registry npm, tag latest, package in the
+ * binary pair) are unchanged — they moved from YAML into the framework with
+ * the rest of the work.
+ */
+export function planSelfUpdate(event: PublishEvent): SelfUpdatePlan | null {
+  if (event.registry !== 'npm' || event.tag !== 'latest') return null;
+  const binary = BINARY_PACKAGES[event.package.name as BinaryPackage];
+  if (!binary) return null;
+  return {
+    packageName: event.package.name as BinaryPackage,
+    version: event.package.version,
+    binary,
+  };
+}
+
+export interface SelfUpdateResult {
+  packageName: BinaryPackage;
+  version: string;
+  /** Globally installed version before the update; null when not installed. */
+  beforeVersion: string | null;
+  /** False when the install step failed — the operator follows up. */
+  updated: boolean;
+  /** True when the binary answered `--version` after the update. */
+  verified: boolean;
+  error?: string;
+}
+
+/**
+ * The seams a test injects. Defaults do the real work against
+ * `$HOME/.bun/install/global/node_modules`.
+ */
+export interface SelfUpdateDeps {
+  /** Root of the bun global install. Default: `$HOME/.bun/install/global/node_modules`. */
+  globalRoot?: string;
+  install?: (packageName: BinaryPackage, version: string) => { ok: boolean; output: string };
+  verify?: (binary: string) => { ok: boolean; output: string };
+}
+
+function defaultGlobalRoot(): string {
+  return join(process.env.HOME ?? '', '.bun', 'install', 'global', 'node_modules');
+}
+
+function defaultInstall(packageName: BinaryPackage, version: string) {
+  const result = spawnSync('bun', ['add', '-g', `${packageName}@${version}`], {
+    encoding: 'utf-8',
+  });
+  return { ok: result.status === 0, output: `${result.stdout ?? ''}${result.stderr ?? ''}` };
+}
+
+function defaultVerify(binary: string) {
+  const result = spawnSync(binary, ['--version'], { encoding: 'utf-8' });
+  return { ok: result.status === 0, output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() };
+}
+
+/**
+ * Run one self-update plan. Never throws — the outcome is the operator's
+ * signal, not a publish blocker (the old hook's exit-code semantics, kept).
+ *
+ * Records the installed version first so a failed update leaves the operator
+ * a `bun add -g <pkg>@<beforeVersion>` rollback target, exactly as the bash
+ * hook printed it.
+ */
+export function runSelfUpdate(plan: SelfUpdatePlan, deps: SelfUpdateDeps = {}): SelfUpdateResult {
+  const globalRoot = deps.globalRoot ?? defaultGlobalRoot();
+  const install = deps.install ?? defaultInstall;
+  const verify = deps.verify ?? defaultVerify;
+
+  const base: SelfUpdateResult = {
+    packageName: plan.packageName,
+    version: plan.version,
+    beforeVersion: null,
+    updated: false,
+    verified: false,
+  };
+
+  const pkgJsonPath = join(globalRoot, plan.packageName, 'package.json');
+  if (existsSync(pkgJsonPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as { version?: string };
+      if (typeof parsed.version === 'string') base.beforeVersion = parsed.version;
+    } catch (error) {
+      // A global package.json that does not parse is unusual but must not
+      // block the update — record it and carry on (Rule 6.2: the swallow is
+      // surfaced in the result the dispatcher logs).
+      base.error = `could not read current version: ${(error as Error).message}`;
+    }
+  }
+
+  const installed = install(plan.packageName, plan.version);
+  if (!installed.ok) {
+    return { ...base, error: `bun add -g failed: ${installed.output.trim().slice(0, 500)}` };
+  }
+  base.updated = true;
+
+  const checked = verify(plan.binary);
+  if (!checked.ok) {
+    return {
+      ...base,
+      error: `${plan.binary} --version failed after update: ${checked.output.slice(0, 300)}`,
+    };
+  }
+  return { ...base, verified: true };
+}

package/src/services/capability-compat.test.ts

@@ -0,0 +1,90 @@
+/**
+ * The registry-poll capability gate (celilo#1361): a consumer upgrade whose
+ * required capability no deployed provider serves must be DEFERRED before any
+ * state changes, not deployed into a provider that rejects its calls.
+ *
+ * celilo-website burned six release revisions (+1 through +6) on exactly
+ * this: every poll attempt updated the stored version, failed in the publish
+ * hook ("sourceDir is required" against an old caddy), recorded the new
+ * version beside the old VERIFIED state, and re-triggered on the next poll.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  type DeployedCapabilityProvider,
+  unservedCapabilityRequirements,
+} from './capability-compat';
+
+function provider(
+  capabilityName: string,
+  moduleId: string,
+  version: string,
+): DeployedCapabilityProvider {
+  return { capabilityName, moduleId, version };
+}
+
+describe('unservedCapabilityRequirements', () => {
+  test('a requirement any deployed provider serves is not a blocker', () => {
+    const providers = [provider('public_web', 'caddy', '4.0.0')];
+    expect(
+      unservedCapabilityRequirements([{ name: 'public_web', version: '4.0.0' }], providers),
+    ).toEqual([]);
+  });
+
+  test('a major the deployed provider has not reached is a blocker, naming it', () => {
+    const providers = [provider('public_web', 'caddy', '3.1.0')];
+    const result = unservedCapabilityRequirements(
+      [{ name: 'public_web', version: '4.0.0' }],
+      providers,
+    );
+    expect(result).toHaveLength(1);
+    expect(result[0].providerModuleId).toBe('caddy');
+    expect(result[0].providerVersion).toBe('3.1.0');
+    expect(result[0].reason).toBe('major_mismatch_higher');
+    expect(result[0].message).toContain('public_web@4.0.0');
+    expect(result[0].message).toContain('caddy');
+  });
+
+  test('no provider at all is a blocker with its own reason', () => {
+    const result = unservedCapabilityRequirements([{ name: 'public_web', version: '4.0.0' }], []);
+    expect(result).toHaveLength(1);
+    expect(result[0].reason).toBe('no_provider');
+    expect(result[0].providerModuleId).toBeNull();
+  });
+
+  test('ANY compatible provider serves the requirement (zone-scoped providers)', () => {
+    const providers = [
+      provider('dns_registrar', 'namecheap', '4.0.0'),
+      provider('dns_registrar', 'bind-internal', '3.0.0'),
+    ];
+    expect(
+      unservedCapabilityRequirements([{ name: 'dns_registrar', version: '4.0.0' }], providers),
+    ).toEqual([]);
+  });
+
+  test('a newer minor than the provider ships is caller_minor_too_old', () => {
+    const providers = [provider('public_web', 'caddy', '4.0.0')];
+    const result = unservedCapabilityRequirements(
+      [{ name: 'public_web', version: '4.1.0' }],
+      providers,
+    );
+    expect(result[0]?.reason).toBe('caller_minor_too_old');
+  });
+
+  test('a consumer behind the provider is compatible (framework back-compat)', () => {
+    const providers = [provider('public_web', 'caddy', '4.0.0')];
+    expect(
+      unservedCapabilityRequirements([{ name: 'public_web', version: '4.0.0' }], providers),
+    ).toEqual([]);
+  });
+
+  test('privileged capabilities are skipped (not provider-backed)', () => {
+    expect(
+      unservedCapabilityRequirements([{ name: 'cross_module_read', version: '9.9.9' }], []),
+    ).toEqual([]);
+  });
+
+  test('undefined requirements yield no blockers', () => {
+    expect(unservedCapabilityRequirements(undefined, [])).toEqual([]);
+  });
+});