@crvouga/dev-fleet 0.4.0 → 0.5.0

package/schema/fleet.schema.json

@@ -253,13 +253,17 @@
       "required": ["release", "architectures"],
       "properties": {
         "release": {
-          "const": "26.04"
+          "type": "string",
+          "pattern": "^[0-9]{2}\\.[0-9]{2}$",
+          "description": "An Ubuntu release ansible/ubuntu/policy.json accepts (docs/support-matrix.md)."
         },
         "architectures": {
-          "const": ["amd64", "arm64"]
+          "type": "array",
+          "items": { "enum": ["amd64", "arm64"] },
+          "description": "Exactly the architectures the policy names for that release."
         }
       },
-      "description": "The supported worker release and architectures (fixed)."
+      "description": "The worker release and its architectures, as the Ubuntu policy of the pinned dev-fleet names them."
     },
     "worker": {
       "type": "object",

package/src/cli/fleet-sync-remote.ts

@@ -203,7 +203,7 @@ function deployWithMonitoring(
     );
     // Workers are Linux by definition.
     ui.progress.step(node.id, 'Verifying SSH, OS and T3');
-    result.checks.push(...(await inspectBootstrap(node, run, 'linux')));
+    result.checks.push(...(await inspectBootstrap(node, run)));
     result.checks.push(
       ...(await workerChecks(enabled(idesOf(canonical), IDES), node, {
         run,

package/src/definition.ts

@@ -17,11 +17,12 @@ import {
   type T3Definition,
 } from './ide/definition';
 import { parseNotify, type NotifyConfig } from './notify';
+import { ubuntuRelease } from './platform/ubuntu-release';
 
 export interface MachineDefinition {
   id: string;
   ssh: string;
-  os: 'linux' | 'macOS' | 'windows';
+  os: 'linux';
   /** Tool profiles this worker adds to the fleet-wide ones. */
   toolProfiles?: ToolProfile[];
   network?: {
@@ -78,7 +79,9 @@ export interface FleetDefinition {
   git?: GitIdentity;
   /** Where fleet-watch sends notifications; absent, nobody is notified. */
   notify?: NotifyConfig;
-  ubuntu: { release: '26.04'; architectures: ['amd64', 'arm64'] };
+  /** An Ubuntu release ansible/ubuntu/policy.json accepts, with exactly the
+   * architectures the policy names for it. */
+  ubuntu: { release: string; architectures: string[] };
 }
 /** How provider accounts are watched and chosen (src/accounts/). */
 export interface AccountPolicy {
@@ -449,14 +452,22 @@ function source(value: unknown): FleetDefinition['source'] {
   return { repository: value['repository'] };
 }
 function baseline(ubuntu: unknown): FleetDefinition['ubuntu'] {
+  if (!record(ubuntu) || !keys(ubuntu, ['release', 'architectures']))
+    return fail();
+  const accepted =
+    typeof ubuntu['release'] === 'string'
+      ? ubuntuRelease(ubuntu['release'])
+      : undefined;
   if (
-    !record(ubuntu) ||
-    !keys(ubuntu, ['release', 'architectures']) ||
-    ubuntu['release'] !== '26.04' ||
-    JSON.stringify(ubuntu['architectures']) !== '["amd64","arm64"]'
+    !accepted ||
+    JSON.stringify(ubuntu['architectures']) !==
+      JSON.stringify(accepted.architectures)
   )
     return fail();
-  return ubuntu as FleetDefinition['ubuntu'];
+  return {
+    release: accepted.release,
+    architectures: [...accepted.architectures],
+  };
 }
 
 /** The configuration as every machine keeps it at

package/src/machine/platform.ts

@@ -1,44 +1,64 @@
-import type { MachineDefinition } from '../definition';
+import platforms from '../../ansible/platforms.json';
+import { kernelArchitectures, ubuntuRelease } from '../platform/ubuntu-release';
 
-export type MachinePlatform = MachineDefinition['os'];
-
-/** One POSIX probe for every supported machine: family, release and CPU. */
-export const PLATFORM_PROBE =
-  'sh -c \'if [ "$(uname -s)" = Darwin ]; then printf "macos\\n%s\\n%s\\n" "$(sw_vers -productVersion)" "$(uname -m)"; else . /etc/os-release && printf "%s\\n%s\\n%s\\n" "$ID" "$VERSION_ID" "$(uname -m)"; fi\'';
+/** One POSIX probe for every worker, four lines: family, release, CPU and
+ * the environment it runs in (`wsl`, `container` or `machine`, a physical
+ * or virtual machine of its own). Read-only, and it needs nothing installed.
+ * `root` moves the files it reads, for a stand-in; workers use `/`.
+ */
+export function platformProbe(root = ''): string {
+  return `sh -c '${[
+    `if [ -r ${root}/etc/os-release ]; then . ${root}/etc/os-release; printf "%s\\n%s\\n" "$ID" "$VERSION_ID"; else printf "%s\\n\\n" "$(uname -s)"; fi`,
+    'uname -m',
+    `if grep -qiE "microsoft|wsl" ${root}/proc/sys/kernel/osrelease 2>/dev/null; then echo wsl`,
+    `elif [ -e ${root}/.dockerenv ] || [ -e ${root}/run/.containerenv ] || systemd-detect-virt --container --quiet 2>/dev/null; then echo container`,
+    'else echo machine; fi',
+  ].join('; ')}'`;
+}
+export const PLATFORM_PROBE = platformProbe();
 
 export interface PlatformBaseline {
-  id: 'ubuntu:release' | 'macos:release';
+  id: 'ubuntu:release' | 'platform:environment';
   supported: boolean;
   summary: string;
 }
 
-/** Ubuntu is the fully accepted worker platform; macOS is best effort. */
-export function evaluatePlatform(
-  os: MachinePlatform,
-  probe: string
-): PlatformBaseline {
-  if (os === 'macOS') {
-    const supported =
-      /^macos\n(1[4-9]|[2-9][0-9])(\.[0-9]+)*\n(arm64|x86_64)\s*$/.test(probe);
-    return {
-      id: 'macos:release',
-      supported,
-      summary: supported
-        ? 'macOS 14 or newer and a supported CPU architecture observed; macOS policy is best effort.'
-        : 'MACOS_BASELINE_MISMATCH',
-    };
-  }
-  const supported = /^ubuntu\n26\.04\n(x86_64|aarch64)\s*$/.test(probe);
+/** A worker is an accepted Ubuntu release on one of that release's CPUs. */
+export function evaluatePlatform(probe: string): PlatformBaseline {
+  const [family, version, cpu] = probe.split('\n').map((line) => line.trim());
+  const release = family === 'ubuntu' ? ubuntuRelease(version) : undefined;
+  const supported =
+    release !== undefined && kernelArchitectures(release).includes(cpu ?? '');
   return {
     id: 'ubuntu:release',
     supported,
     summary: supported
-      ? 'Ubuntu 26.04 and supported CPU architecture observed.'
+      ? `Ubuntu ${release.release} and supported CPU architecture observed.`
       : 'UBUNTU_BASELINE_MISMATCH',
   };
 }
 
-/** Windows machines stay declared but never receive manager convergence. */
-export function convergeable(node: MachineDefinition): boolean {
-  return node.os !== 'windows';
+/** Environments the support matrix (ansible/platforms.json) refuses, by the
+ * word the probe prints for them. */
+const REFUSED = new Map(
+  platforms.rows.flatMap((row) =>
+    'environment' in row && row.status === 'refused'
+      ? [[row.environment, row.platform] as const]
+      : []
+  )
+);
+
+/** WSL2 and containers run an Ubuntu userland without systemd, a display
+ * manager or a power policy of their own; they are refused by name. */
+export function evaluateEnvironment(probe: string): PlatformBaseline {
+  const environment = probe.split('\n')[3]?.trim() ?? '';
+  const refused = REFUSED.get(environment);
+  const supported = environment === 'machine';
+  return {
+    id: 'platform:environment',
+    supported,
+    summary: supported
+      ? 'A machine of its own observed: not WSL2 and not a container.'
+      : `WORKER_ENVIRONMENT_UNSUPPORTED: ${refused ?? 'unknown environment'}`,
+  };
 }

package/src/machine/support-matrix.ts

@@ -0,0 +1,76 @@
+import macos from '../../ansible/macos/policy.json';
+import platforms from '../../ansible/platforms.json';
+import { UBUNTU_RELEASES } from '../platform/ubuntu-release';
+
+export type SupportStatus = 'supported' | 'best effort' | 'refused';
+export interface SupportRow {
+  role: string;
+  platform: string;
+  versions: string;
+  architectures: string;
+  status: SupportStatus;
+  note: string;
+}
+
+/** Every platform and what dev-fleet does with it, from the policies the code
+ * reads: the supported rows from the macOS and Ubuntu policies, the rest from
+ * ansible/platforms.json. docs/support-matrix.md is this table. */
+export function supportMatrix(): SupportRow[] {
+  return [
+    {
+      role: 'manager',
+      platform: 'macOS',
+      versions: `${macos.minimumMajorVersion} or newer`,
+      architectures: macos.architectures.join(', '),
+      status: 'supported',
+      note: 'ansible/macos/policy.json',
+    },
+    ...UBUNTU_RELEASES.map((entry): SupportRow => ({
+      role: 'worker',
+      platform: 'Ubuntu',
+      versions: `${entry.release} (${entry.codename})`,
+      architectures: entry.architectures.join(', '),
+      status: 'supported',
+      note: 'ansible/ubuntu/policy.json; a machine of its own, physical or virtual',
+    })),
+    ...platforms.rows.map((row): SupportRow => ({
+      role: row.role,
+      platform: row.platform,
+      versions: row.versions,
+      architectures: row.architectures,
+      status: row.status as SupportStatus,
+      note: row.note,
+    })),
+  ];
+}
+
+export function renderSupportMatrix(rows = supportMatrix()): string {
+  const header = [
+    'Role',
+    'Platform',
+    'Versions',
+    'Architectures',
+    'Status',
+    'Note',
+  ];
+  const cells = rows.map((row) => [
+    row.role,
+    row.platform,
+    row.versions,
+    row.architectures,
+    row.status,
+    row.note,
+  ]);
+  const widths = header.map((title, index) =>
+    Math.max(title.length, ...cells.map((line) => line[index]!.length))
+  );
+  const line = (values: string[]) =>
+    `| ${values.map((value, index) => value.padEnd(widths[index]!)).join(' | ')} |`;
+  return [
+    line(header),
+    `| ${widths.map((width) => '-'.repeat(width)).join(' | ')} |`,
+    ...cells.map(line),
+  ].join('\n');
+}
+
+if (import.meta.main) process.stdout.write(`${renderSupportMatrix()}\n`);

package/src/manager-sync.ts

@@ -16,10 +16,9 @@ import { sshArgs, sshFailure } from './ssh';
 import type { FleetDefinition, MachineDefinition } from './definition';
 import { publicHubUrl } from './monitoring/beszel';
 import {
-  convergeable,
+  evaluateEnvironment,
   evaluatePlatform,
   PLATFORM_PROBE,
-  type MachinePlatform,
 } from './machine/platform';
 
 export interface ManagerNode extends NodeReport {
@@ -51,14 +50,14 @@ export type DeployNode = (
 /** Minimal read-only POSIX inspection requires no workspace, Node, Bun or Git. */
 export async function inspectBootstrap(
   node: FleetNode,
-  run: Runner,
-  os: MachinePlatform = 'linux'
+  run: Runner
 ): Promise<Check[]> {
   const result = await run([...sshArgs(node), PLATFORM_PROBE], {
     timeoutMs: 20_000,
   });
   if (!result.ok) return [sshFailure(result)];
-  const baseline = evaluatePlatform(os, result.stdout);
+  const baseline = evaluatePlatform(result.stdout);
+  const environment = evaluateEnvironment(result.stdout);
   return [
     {
       id: 'ssh:fresh-session',
@@ -75,6 +74,15 @@ export async function inspectBootstrap(
           'Review the release/architecture migration in source. No operating-system upgrade or downgrade is performed.',
       },
     },
+    {
+      id: environment.id,
+      status: environment.supported ? 'pass' : 'fail',
+      summary: environment.summary,
+      remedy: {
+        action:
+          'Run the worker on a physical or virtual machine of its own; docs/support-matrix.md lists what is supported.',
+      },
+    },
   ];
 }
 
@@ -124,7 +132,7 @@ export async function synchronizeManager(
   // worker is then verified against.
   if (managerRun) await managerRun;
   const workers = await Promise.all(
-    input.definition.workers.filter(convergeable).map((machine) => {
+    input.definition.workers.map((machine) => {
       input.progress?.(
         machine.id,
         'Inspecting enrolled identity and fresh SSH access'
@@ -329,7 +337,7 @@ async function inspectManagerNode(
       },
     });
   else {
-    checks.push(...(await inspectBootstrap(node, run, machine.os)));
+    checks.push(...(await inspectBootstrap(node, run)));
     checks.push(...identityChecks(node, peer));
     if (peer) checks.push(keyExpiryCheck(peer));
   }

package/src/network-definition.ts

@@ -8,7 +8,7 @@ export interface NetworkHost {
   sshPort: number;
   user: string;
   identityFile: string;
-  os: 'linux' | 'macOS' | 'windows';
+  os: 'linux';
   t3Port: number;
 }
 export function networkProjection(

package/src/node-converge.ts

@@ -23,7 +23,7 @@ async function main(): Promise<Check[]> {
       summary: 'PLATFORM_UNSUPPORTED',
       remedy: {
         action:
-          'Workers are Ubuntu 26.04. The macOS manager converges itself locally in fleet-sync.',
+          'Workers run an Ubuntu release docs/support-matrix.md lists. The macOS manager converges itself locally in fleet-sync.',
       },
     },
   ];

package/src/platform/debian-version.ts

@@ -0,0 +1,62 @@
+/** Debian version ordering, as `dpkg --compare-versions` applies it:
+ * epoch, then upstream version, then revision. Negative when `a` sorts
+ * before `b`, zero when they are the same version, positive after. */
+export function compareDebianVersions(a: string, b: string): number {
+  const [epochA, upstreamA, revisionA] = split(a);
+  const [epochB, upstreamB, revisionB] = split(b);
+  return (
+    epochA - epochB ||
+    comparePart(upstreamA, upstreamB) ||
+    comparePart(revisionA, revisionB)
+  );
+}
+
+function split(version: string): [number, string, string] {
+  const colon = version.indexOf(':');
+  const epoch = colon > 0 ? Number(version.slice(0, colon)) || 0 : 0;
+  const rest = colon > 0 ? version.slice(colon + 1) : version;
+  const dash = rest.lastIndexOf('-');
+  return dash > 0
+    ? [epoch, rest.slice(0, dash), rest.slice(dash + 1)]
+    : [epoch, rest, '0'];
+}
+
+/** `~` sorts before everything, even the end of the string; letters sort
+ * before every other character. */
+function order(char: string | undefined): number {
+  if (char === undefined) return 0;
+  if (char === '~') return -1;
+  if (/[A-Za-z]/.test(char)) return char.charCodeAt(0);
+  return char.charCodeAt(0) + 256;
+}
+
+/** Alternating runs: text, then digits, then text again, starting with text. */
+function runs(part: string): string[] {
+  return part
+    .match(/\D*\d*/g)!
+    .filter(Boolean)
+    .flatMap((run) => {
+      const digits = /\d*$/.exec(run)![0];
+      return [run.slice(0, run.length - digits.length), digits];
+    });
+}
+
+function compareText(a: string, b: string): number {
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    const difference = order(a[i]) - order(b[i]);
+    if (difference) return difference;
+  }
+  return 0;
+}
+
+function comparePart(a: string, b: string): number {
+  const left = runs(a);
+  const right = runs(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 2) {
+    const difference =
+      compareText(left[i] ?? '', right[i] ?? '') ||
+      Number(left[i + 1] || 0) - Number(right[i + 1] || 0);
+    if (difference) return difference;
+  }
+  return 0;
+}

package/src/platform/ubuntu-audit.ts

@@ -1,5 +1,5 @@
-import policy from '../../ansible/ubuntu/policy.json';
 import type { Runner } from '../types';
+import { packagePins, UBUNTU_RELEASES, ubuntuRelease } from './ubuntu-release';
 
 export interface UbuntuAudit {
   supported: boolean;
@@ -11,7 +11,13 @@ export interface UbuntuAudit {
   passwordlessSudo: boolean;
   rebootPending: boolean;
 }
-const PACKAGES = [...Object.keys(policy.packages), 'tailscale'];
+// Every package any accepted release pins, so one audit serves them all.
+const PACKAGES = [
+  ...new Set([
+    ...UBUNTU_RELEASES.flatMap((release) => Object.keys(packagePins(release))),
+    'tailscale',
+  ]),
+];
 
 /** Read-only audit: never emit package sources, environment, accounts or raw errors. */
 export async function auditUbuntu(run: Runner): Promise<UbuntuAudit> {
@@ -32,14 +38,15 @@ export async function auditUbuntu(run: Runner): Promise<UbuntuAudit> {
   const version =
     /^VERSION_ID="?([0-9]+\.[0-9]+)"?$/m.exec(release.stdout)?.[1] ?? null;
   const reported = arch.stdout.trim();
-  const architecture = policy.architectures.includes(reported)
+  const accepted = ubuntuRelease(version);
+  const architecture = accepted?.architectures.includes(reported)
     ? reported
     : null;
   return {
     supported:
       release.ok &&
       /^ID=ubuntu$/m.test(release.stdout) &&
-      version === policy.release &&
+      accepted !== undefined &&
       architecture !== null,
     release: version,
     architecture,

package/src/platform/ubuntu-release.ts

@@ -0,0 +1,41 @@
+import policy from '../../ansible/ubuntu/policy.json';
+
+/** One Ubuntu release workers may run. The accepted releases are named once,
+ * in ansible/ubuntu/policy.json; nothing else spells a release or codename. */
+export interface UbuntuRelease {
+  release: string;
+  codename: string;
+  /** Debian architecture names, as `dpkg --print-architecture` reports them. */
+  architectures: string[];
+  /** Pins of this release that differ from the policy's `packages`. */
+  packages?: Record<string, string>;
+}
+
+export const UBUNTU_RELEASES: readonly UbuntuRelease[] = policy.releases;
+
+/** The package pins of one release: the policy's, with the release's own
+ * pins over them (as tasks/release.yml combines them for Ansible). */
+export function packagePins(
+  release: UbuntuRelease | undefined
+): Record<string, string> {
+  return { ...policy.packages, ...release?.packages };
+}
+
+/** `uname -m` for each Debian architecture name. */
+const KERNEL_ARCHITECTURES: Record<string, string> = {
+  amd64: 'x86_64',
+  arm64: 'aarch64',
+};
+
+export function ubuntuRelease(
+  version: string | null | undefined
+): UbuntuRelease | undefined {
+  return UBUNTU_RELEASES.find((entry) => entry.release === version);
+}
+
+/** The `uname -m` names one release runs on. */
+export function kernelArchitectures(release: UbuntuRelease): string[] {
+  return release.architectures.map(
+    (name) => KERNEL_ARCHITECTURES[name] ?? name
+  );
+}

package/src/remote-bootstrap.ts

@@ -23,6 +23,7 @@ import {
 import { record } from './config';
 import { installedDefinition, type FleetDefinition } from './definition';
 import { cleanCheck, validCheck } from './protocol';
+import { UBUNTU_RELEASES } from './platform/ubuntu-release';
 
 export interface BootstrapPayload {
   revision: string;
@@ -127,6 +128,7 @@ export async function bootstrapRemote(
     payload.digest,
     node.id,
     transfer.mode,
+    UBUNTU_RELEASES.map((entry) => entry.release).join(' '),
   ]
     .map(shellQuote)
     .join(' ');

package/src/worker-host-checks.ts

@@ -5,6 +5,8 @@ import { verifyResourceSafety } from './platform/resource-verify';
 import policy from '../ansible/ubuntu/policy.json';
 import { userInfo } from 'node:os';
 import { T3_HEALTH_SCRIPT, runningVersionCheck } from './platform/t3-service';
+import { compareDebianVersions } from './platform/debian-version';
+import { packagePins, ubuntuRelease } from './platform/ubuntu-release';
 import type { Check, Runner } from './types';
 
 function check(id: string, ok: boolean, summary: string): Check {
@@ -22,6 +24,34 @@ function check(id: string, ok: boolean, summary: string): Check {
       : {}),
   };
 }
+/** A pin is a minimum (docs/worker-contract.md): Ubuntu's security updates
+ * may move a package past it, which is reported but never undone. */
+export function pinnedPackage(
+  name: string,
+  pinned: string,
+  installed: string | undefined
+): Check {
+  const order =
+    installed === undefined ? -1 : compareDebianVersions(installed, pinned);
+  if (order <= 0)
+    return check(
+      `package:${name}`,
+      order === 0,
+      order === 0
+        ? 'Installed at the version the policy pins.'
+        : `PACKAGE_BELOW_PIN ${name} ${installed ?? 'missing'}, pinned ${pinned}`
+    );
+  return {
+    id: `worker:package:${name}`,
+    status: 'warn',
+    summary: `PACKAGE_NEWER_THAN_PIN ${name} ${installed}, pinned ${pinned}`,
+    remedy: {
+      action:
+        'An unattended security update moved this package past its pin, and it is kept. Raise the pin in the Ubuntu policy when the snapshot moves.',
+    },
+  };
+}
+
 /** Observed unit state for a failed service check, e.g.
  * `SERVICE_NOT_INSTALLED beszel-agent.service (inactive)`. */
 export function serviceState(name: string, show: string): string {
@@ -56,17 +86,13 @@ export async function workerHostChecks(
       audit.passwordlessSudo,
       'Designated worker user has noninteractive sudo.'
     ),
-    ...Object.entries(policy.packages).map(([name, version]) =>
-      check(
-        `package:${name}`,
-        audit.packages[name] === version,
-        'Exact declarative Ubuntu package version.'
-      )
+    ...Object.entries(packagePins(ubuntuRelease(audit.release))).map(
+      ([name, version]) => pinnedPackage(name, version, audit.packages[name])
     ),
-    check(
-      'package:tailscale',
-      audit.packages['tailscale'] === policy.tailscale.version,
-      'Exact declarative Tailscale version.'
+    pinnedPackage(
+      'tailscale',
+      policy.tailscale.version,
+      audit.packages['tailscale']
     ),
   ];
   for (const name of policy.alwaysOnServices) {