@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/src/diagnostics.ts

@@ -0,0 +1,92 @@
+import type { Check } from './types';
+
+export interface Diagnostic {
+  node: string;
+  phase: string;
+  checkId: string;
+  status: Check['status'];
+  code: string;
+  summary: string;
+  expected: string;
+  observed: string;
+  scope: 'manager' | 'node' | 'unverified';
+  durationMs: number | null;
+  retryable: boolean;
+  actionRequired: boolean;
+  remedy: { owner: string; action: string };
+}
+const EXPECTED: Record<string, string> = {
+  ssh: 'Fresh noninteractive SSH session with the enrolled host key and designated user.',
+  tailscale:
+    'The enrolled device identity is connected and reachable through the intended tailnet.',
+  ubuntu:
+    'Observed Ubuntu configuration matches the reviewed baseline without a distribution upgrade.',
+  t3: 'Pinned native T3 service and the specifically named runtime acceptance check pass.',
+  provider:
+    'The declared gateway model passes authenticated inference, completed streaming and a bounded tool round trip.',
+  proxy:
+    'One declared gateway owner preserves runtime identities and serves authorized clients.',
+  beszel:
+    'Pinned monitoring artifacts, canonical registration and fresh authenticated metrics are independently verified.',
+  rollout: 'Required prerequisites and canary gates pass before promotion.',
+  manager:
+    'Manager enrollment, approval and exclusive operation ownership are valid.',
+  source:
+    'The approved full commit and packaged canonical definition match verified source.',
+  configuration:
+    'The existing Workstation owner applies and verifies the selected source configuration.',
+};
+
+/** Derived only from already-redacted checks. No raw subprocess errors, journal
+ * contents, auth payloads or environment fields enter the diagnostic contract.
+ */
+export function diagnostic(node: string, check: Check): Diagnostic {
+  const phase = check.id.split(':')[0]!;
+  const failed = check.status !== 'pass';
+  const code = /^[A-Z][A-Z0-9_]{2,100}$/.test(check.summary)
+    ? check.summary
+    : `${check.id.replaceAll(/[^a-z0-9]/g, '_').toUpperCase()}_${failed ? 'UNVERIFIED' : 'VERIFIED'}`;
+  return {
+    node,
+    phase,
+    checkId: check.id,
+    status: check.status,
+    code,
+    summary: check.summary,
+    expected:
+      EXPECTED[phase] ??
+      'The named required check has independent verification evidence.',
+    observed: check.summary,
+    scope: scope(check.id),
+    durationMs: check.phaseDurationMs ?? null,
+    retryable: failed && /OFFLINE|UNREACHABLE|METRICS_STALE|TIMEOUT/.test(code),
+    actionRequired: failed,
+    remedy: {
+      owner: owner(phase),
+      action:
+        check.remedy?.action ??
+        'Inspect this named check in the Fleet runbook; preserve runtime identity and repair persistent configuration in source.',
+    },
+  };
+}
+function scope(id: string): Diagnostic['scope'] {
+  if (
+    /^(t3:manager-endpoint|ssh:|manager:|rollout:|source:|tailscale:(reachability|identity|enrolled-identity))/.test(
+      id
+    )
+  )
+    return 'manager';
+  if (
+    /^(provider:|proxy:|configuration:|ubuntu:baseline|t3:(service|policy)|tailscale:configuration)/.test(
+      id
+    )
+  )
+    return 'node';
+  if (/^beszel:(version|registration|connection|freshness|api)/.test(id))
+    return 'manager';
+  return 'unverified';
+}
+function owner(phase: string): string {
+  if (phase === 'proxy') return 'cliproxy';
+  return 'dev-fleet';
+}

package/src/doctor-check.ts

@@ -0,0 +1,10 @@
+export type CheckSeverity = 'pass' | 'warn' | 'fail';
+
+/** One human-readable health finding, with an optional fix to run. */
+export type DoctorCheck = {
+  id: string;
+  label: string;
+  severity: CheckSeverity;
+  detail: string;
+  fix?: string | undefined;
+};

package/src/errors.ts

@@ -0,0 +1 @@
+export class FleetUsageError extends Error {}

package/src/fingerprint.ts

@@ -0,0 +1,120 @@
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { record } from './config';
+import {
+  fileHash,
+  manifestHash,
+  sidecarHash,
+  INPUT_FILES,
+  FINGERPRINT_FILES,
+} from './input-hashes';
+import type { Fingerprint, Runner, Check } from './types';
+
+const RECEIPT = 'node_modules/.fleet-sync.json';
+
+export async function fingerprint(
+  root: string,
+  run: Runner
+): Promise<Fingerprint> {
+  const files: Fingerprint['files'] = {};
+  for (const name of INPUT_FILES)
+    files[name] = await fileHash(join(root, name));
+  files['workspace-manifests'] = await manifestHash(root);
+  files['mise-sidecars'] = await sidecarHash(root);
+  const head = await run(['git', 'rev-parse', 'HEAD'], { cwd: root });
+  return {
+    head:
+      head.ok && /^[a-f0-9]{40,64}\s*$/.test(head.stdout)
+        ? head.stdout.trim()
+        : null,
+    files,
+  };
+}
+
+export async function dependencyCheck(
+  root: string,
+  current: Fingerprint
+): Promise<Check> {
+  const remedy = {
+    action:
+      'Review devfleet fleet-repair --repair workspace, then explicitly apply a frozen toolchain/dependency sync.',
+  };
+  try {
+    const receipt: unknown = JSON.parse(
+      await readFile(join(root, RECEIPT), 'utf8')
+    );
+    const matches =
+      record(receipt) &&
+      receipt['version'] === 1 &&
+      JSON.stringify(receipt['files']) === JSON.stringify(current.files);
+    return {
+      id: 'dependencies',
+      status: matches ? 'pass' : 'fail',
+      summary: matches
+        ? 'Last successful frozen sync matches input hashes; not a full integrity audit.'
+        : 'Dependency sync receipt is stale or invalid.',
+      ...(matches ? {} : { remedy }),
+    };
+  } catch {
+    return {
+      id: 'dependencies',
+      status: 'warn',
+      summary: 'No frozen-sync receipt; installed dependencies are unverified.',
+      remedy,
+    };
+  }
+}
+
+export async function writeReceipt(
+  root: string,
+  current: Fingerprint
+): Promise<void> {
+  await mkdir(join(root, 'node_modules'), { recursive: true });
+  await writeFile(
+    join(root, RECEIPT),
+    JSON.stringify({ version: 1, files: current.files }),
+    { mode: 0o600 }
+  );
+}
+
+export function compareFingerprints(
+  expected: Fingerprint,
+  actual: Fingerprint
+): Check[] {
+  return [
+    compare('revision', expected.head, actual.head),
+    ...FINGERPRINT_FILES.map((name) =>
+      compare(
+        `sync:${name}`,
+        expected.files[name] ?? null,
+        actual.files[name] ?? null
+      )
+    ),
+  ];
+}
+
+function compare(
+  id: string,
+  expected: string | null,
+  actual: string | null
+): Check {
+  const known = expected !== null && actual !== null;
+  const matches = known && expected === actual;
+  return {
+    id,
+    status: matches ? 'pass' : 'fail',
+    summary: matches
+      ? 'Matches the manager checkout.'
+      : known
+        ? 'Differs from the manager checkout.'
+        : 'Cannot verify; reference or node input is missing.',
+    ...(matches
+      ? {}
+      : {
+          remedy: {
+            action:
+              'Reconcile branches/lockfiles; review devfleet fleet-sync for the approved revision. Never reset a working tree.',
+          },
+        }),
+  };
+}

package/src/fleet-config.ts

@@ -0,0 +1,88 @@
+import { spawn } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parseDefinition, type FleetDefinition } from './definition';
+import { FleetUsageError } from './errors';
+import { pinnedPath } from './agents/toolchain';
+import type { Runner } from './types';
+import {
+  secretsProvider,
+  type SecretCommand,
+  type SecretsProvider,
+} from './secrets';
+
+/** Where every machine keeps the fleet configuration. fleet-sync installs the
+ * approved copy here, so launchers and scheduled jobs find it without any
+ * environment. `DEVFLEET_CONFIG` names another file (the manager's checkout of
+ * its configuration repository, or a test fixture).
+ */
+export function configPath(env = process.env, home = homedir()): string {
+  return env['DEVFLEET_CONFIG'] || join(home, '.config/dev-fleet/fleet.json');
+}
+
+/** Installs the configuration this process runs with as the machine's copy,
+ * so launchers and scheduled jobs (which get no environment) use the same one.
+ * Returns whether the file changed.
+ */
+export function installConfig(home = homedir()): boolean {
+  const target = join(home, '.config/dev-fleet/fleet.json');
+  const content = JSON.stringify(fleet, null, 2) + '\n';
+  if (existsSync(target) && readFileSync(target, 'utf8') === content)
+    return false;
+  mkdirSync(join(home, '.config/dev-fleet'), { recursive: true, mode: 0o700 });
+  writeFileSync(`${target}.new`, content, { mode: 0o600 });
+  renameSync(`${target}.new`, target);
+  return true;
+}
+
+function load(): FleetDefinition {
+  const path = configPath();
+  if (!existsSync(path))
+    throw new FleetUsageError(
+      `No fleet configuration at ${path}. Copy examples/fleet.json, edit it for your machines, and set DEVFLEET_CONFIG or place it there.`
+    );
+  return parseDefinition(JSON.parse(readFileSync(path, 'utf8')));
+}
+
+/** This fleet's own configuration: its machines, endpoints, accounts and source
+ * repository. Fleet code never names any of them; it reads them here, and this
+ * is the only module that loads the file.
+ */
+export const fleet = load();
+
+/** Reads one of this fleet's secrets for this node. Tools run from the pinned
+ * toolchain, whatever PATH the caller (T3, launchd, systemd) started with.
+ */
+export const secret: SecretsProvider = (name) =>
+  secretsProvider(fleet.secrets, { run: pinned })(name);
+
+/** The same, through an injected runner (fleet-sync phases and their tests). */
+export const secretVia = (run: Runner): SecretsProvider =>
+  secretsProvider(fleet.secrets, {
+    run: async (argv) => {
+      const result = await run(argv, { timeoutMs: 20_000 });
+      return result.ok ? result.stdout : null;
+    },
+  });
+
+const pinned: SecretCommand = (argv) =>
+  new Promise((resolve) => {
+    const child = spawn(argv[0]!, argv.slice(1), {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 20_000,
+      env: { ...process.env, PATH: pinnedPath() },
+    });
+    let output = '';
+    child.stdout.on('data', (chunk: Buffer) => {
+      if (output.length < 65_536) output += chunk.toString('utf8');
+    });
+    child.on('error', () => resolve(null));
+    child.on('close', (code) => resolve(code === 0 ? output : null));
+  });

package/src/index.ts

@@ -0,0 +1,6 @@
+export { parseConfig, loadConfig, selectNodes } from './config';
+export { doctor } from './manager';
+export { probe } from './probe';
+export { makeReport, reportExitCode, renderReport } from './report';
+export { syncPlan, syncWorkspace } from './sync';
+export type * from './types';

package/src/input-hashes.ts

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const INPUT_FILES = [
+  'package.json',
+  'bun.lock',
+  'mise.toml',
+  'mise.lock',
+];
+export const FINGERPRINT_FILES = [
+  ...INPUT_FILES,
+  'workspace-manifests',
+  'mise-sidecars',
+];
+
+export async function fileHash(path: string): Promise<string | null> {
+  try {
+    return digest(await readFile(path));
+  } catch {
+    return null;
+  }
+}
+
+export async function manifestHash(root: string): Promise<string | null> {
+  try {
+    const entries = await readdir(join(root, 'packages'), {
+      withFileTypes: true,
+    });
+    const hashes: string[] = [];
+    for (const entry of entries
+      .filter((item) => item.isDirectory())
+      .sort((left, right) => left.name.localeCompare(right.name, 'en'))) {
+      hashes.push(
+        `${entry.name}:${await fileHash(join(root, 'packages', entry.name, 'package.json'))}`
+      );
+    }
+    return digest(hashes.join('\n'));
+  } catch {
+    return null;
+  }
+}
+
+export async function sidecarHash(root: string): Promise<string | null> {
+  try {
+    const files = await readdir(join(root, '.mise/locks'), {
+      recursive: true,
+      withFileTypes: true,
+    });
+    if (files.length > 4096 || files.some((entry) => entry.isSymbolicLink()))
+      return null;
+    const hashes: string[] = [];
+    const paths = files
+      .filter((entry) => entry.isFile())
+      .map((entry) => join(entry.parentPath, entry.name))
+      .sort();
+    for (const path of paths) {
+      const hash = await fileHash(path);
+      if (hash === null) return null;
+      const relative = path
+        .slice(join(root, '.mise/locks').length)
+        .replaceAll('\\', '/');
+      hashes.push(`${relative}:${hash}`);
+    }
+    return digest(hashes.join('\n'));
+  } catch {
+    return null;
+  }
+}
+
+function digest(value: string | Buffer): string {
+  return createHash('sha256').update(value).digest('hex');
+}

package/src/machine/local-source.ts

@@ -0,0 +1,52 @@
+import { isRevision } from './state';
+import { resolve } from 'node:path';
+import type { Runner } from '../types';
+import { fleet } from '../fleet-config';
+
+/** `https://host/owner/repo.git` and `git@host:owner/repo` name one repository. */
+export function sameRepository(remote: string, declared: string): boolean {
+  const name = (url: string) =>
+    url
+      .replace(/^(https:\/\/|ssh:\/\/git@|git@)/, '')
+      .replace(':', '/')
+      .replace(/\.git$/, '')
+      .toLowerCase();
+  return name(remote) === name(declared);
+}
+
+/** Use committed objects, never working-tree files, for an approved local branch. */
+export async function approvedLocalSource(
+  checkout: string,
+  revision: string,
+  run: Runner
+): Promise<string | null> {
+  const options = { cwd: checkout, timeoutMs: 10_000 };
+  const top = await run(['git', 'rev-parse', '--show-toplevel'], options);
+  if (!top.ok || resolve(top.stdout.trim()) !== resolve(checkout)) return null;
+  const origin = await run(['git', 'remote', 'get-url', 'origin'], options);
+  if (
+    !origin.ok ||
+    !sameRepository(origin.stdout.trim(), fleet.source.repository)
+  )
+    return null;
+  const commit = await run(
+    ['git', 'rev-parse', '--verify', `${revision}^{commit}`],
+    options
+  );
+  return commit.ok && commit.stdout.trim() === revision ? checkout : null;
+}
+
+export async function localCheckoutRevision(
+  checkout: string,
+  run: Runner
+): Promise<string | undefined> {
+  const result = await run(['git', 'rev-parse', 'HEAD'], {
+    cwd: checkout,
+    timeoutMs: 10_000,
+  });
+  const revision = result.stdout.trim();
+  if (!result.ok || !isRevision(revision)) return undefined;
+  return (await approvedLocalSource(checkout, revision, run))
+    ? revision
+    : undefined;
+}

package/src/machine/lock-error.ts

@@ -0,0 +1,2 @@
+import { FleetUsageError } from '../errors';
+export class FleetLockError extends FleetUsageError {}

package/src/machine/platform.ts

@@ -0,0 +1,44 @@
+import type { MachineDefinition } from '../definition';
+
+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\'';
+
+export interface PlatformBaseline {
+  id: 'ubuntu:release' | 'macos:release';
+  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);
+  return {
+    id: 'ubuntu:release',
+    supported,
+    summary: supported
+      ? 'Ubuntu 26.04 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';
+}

package/src/machine/source.ts

@@ -0,0 +1,68 @@
+import { approvedLocalSource } from './local-source';
+import { join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import type { Runner } from '../types';
+import { ensurePrivateRoot } from './state';
+import { fleet } from '../fleet-config';
+
+const REPOSITORY = fleet.source.repository;
+
+/** Called after approval; local sources supply Git objects only, never dirty files. */
+export async function prepareSource(
+  root: string,
+  revision: string,
+  run: Runner,
+  checkout?: string
+): Promise<string | null> {
+  if (checkout) {
+    const local = await approvedLocalSource(checkout, revision, run);
+    if (local) return local;
+  }
+  return prepareRemoteSource(root, revision, run);
+}
+
+async function prepareRemoteSource(
+  root: string,
+  revision: string,
+  run: Runner
+): Promise<string | null> {
+  const source = join(root, 'source');
+  await ensurePrivateRoot(source);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  let origin = await run(['git', 'remote', 'get-url', 'origin'], {
+    cwd: source,
+  });
+  if (!origin.ok) {
+    const cloned = await run(
+      [
+        'git',
+        'clone',
+        '--no-checkout',
+        '--origin',
+        'origin',
+        REPOSITORY,
+        source,
+      ],
+      { timeoutMs: 120_000 }
+    );
+    if (!cloned.ok) return null;
+    origin = await run(['git', 'remote', 'get-url', 'origin'], { cwd: source });
+  }
+  if (!origin.ok || origin.stdout.trim() !== REPOSITORY) return null;
+  let found = await run(
+    ['git', 'rev-parse', '--verify', `${revision}^{commit}`],
+    { cwd: source }
+  );
+  if (!found.ok || found.stdout.trim() !== revision) {
+    const fetch = await run(['git', 'fetch', '--no-tags', 'origin', revision], {
+      cwd: source,
+      timeoutMs: 120_000,
+    });
+    if (!fetch.ok) return null;
+    found = await run(
+      ['git', 'rev-parse', '--verify', `${revision}^{commit}`],
+      { cwd: source }
+    );
+  }
+  return found.ok && found.stdout.trim() === revision ? source : null;
+}