@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/src/cli/managed-health.ts

@@ -0,0 +1,219 @@
+import { verifyT3Linked } from '../t3-linked-check';
+import { verifyT3Endpoint } from '../t3-endpoint';
+import type { Check, NodeReport, Runner } from '../types';
+import { fleet as definition } from '../fleet-config';
+import { enrolledRoster } from '../definition';
+import type { Tailnet } from '../tailscale';
+import type { FleetNode } from '../types';
+import {
+  publicHubUrl,
+  verifyBeszel,
+  type BeszelRequest,
+} from '../monitoring/beszel';
+import { hubAccess } from '../monitoring/hub-access';
+import { hubUrl } from '../topology';
+
+export interface DashboardAccess {
+  (hub: string): Promise<{ request: BeszelRequest }>;
+}
+
+/** The hub always runs on the manager, reached by its MagicDNS name. */
+export function dashboardUrl(tailnet: Tailnet): string | null {
+  const canonical = definition;
+  const visible = tailnet.computers.some(
+    (computer) =>
+      computer.dns.replace(/\.$/, '') ===
+      canonical.manager.network.tailscaleName
+  );
+  return visible ? hubUrl(canonical) : null;
+}
+
+/** Centralized dashboard evidence for every canonical worker: the hub must answer
+ * privately, and each node must be registered, connected and reporting fresh
+ * samples. A missing manager Vault session is reported, never silently passed.
+ */
+export async function appendDashboardEvidence(
+  reports: NodeReport[],
+  tailnet: Tailnet,
+  options: { access?: DashboardAccess; fetcher?: typeof fetch } = {}
+): Promise<string | null> {
+  const hub = dashboardUrl(tailnet);
+  const dashboard: NodeReport = { node: 'dashboard', checks: [] };
+  reports.push(dashboard);
+  if (!hub) {
+    dashboard.checks.push(
+      fail(
+        'beszel:hub',
+        'BESZEL_HUB_SELECTION_REQUIRED',
+        'The hub runs on the manager, which is not visible in Tailscale. Wake the manager and reconnect it to the tailnet.'
+      )
+    );
+    return null;
+  }
+  const fetcher = options.fetcher ?? fetch;
+  dashboard.checks.push(await hubReachable(hub, fetcher));
+  dashboard.checks.push(await publicEndpoint(fetcher));
+  await nodeEvidence(reports, dashboard, hub, options.access ?? hubAccess);
+  return hub;
+}
+
+async function nodeEvidence(
+  reports: NodeReport[],
+  dashboard: NodeReport,
+  hub: string,
+  access: DashboardAccess
+): Promise<void> {
+  const canonical = definition;
+  try {
+    const { request } = await access(hub);
+    for (const machine of canonical.workers) {
+      const evidence = await verifyBeszel(hub, machine.id, request);
+      const report =
+        reports.find(
+          (entry) =>
+            entry.node === machine.network?.tailscaleName ||
+            entry.node === machine.id
+        ) ?? dashboard;
+      report.checks.push(...evidence.checks);
+    }
+  } catch (error) {
+    dashboard.checks.push({
+      id: 'beszel:access',
+      status: 'skip',
+      summary:
+        error instanceof Error && error.message.startsWith('BESZEL_')
+          ? error.message
+          : 'BESZEL_ACCOUNT_REQUIRED',
+      remedy: {
+        action:
+          'Authenticate this manager to Vault so BESZEL_FLEET_AUTH can be read, then rerun fleet-status --workers. Node registration and metric freshness are unverified until then.',
+      },
+    });
+  }
+}
+
+async function hubReachable(
+  hub: string,
+  fetcher: typeof fetch
+): Promise<Check> {
+  try {
+    const response = await fetcher(`${hub}/api/health`, {
+      redirect: 'error',
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (response.ok)
+      return {
+        id: 'beszel:hub',
+        status: 'pass',
+        summary: `Dashboard answers privately at ${hub}.`,
+      };
+  } catch {
+    /* Connection details are not evidence; fall through. */
+  }
+  return fail(
+    'beszel:hub',
+    'BESZEL_HUB_UNREACHABLE',
+    `The private dashboard did not answer at ${hub}/api/health. The hub runs on the manager: keep it awake with Docker Desktop running, then run devfleet fleet-sync there.`
+  );
+}
+
+/** The Cloudflare hostname is convenience access; the private hub stays canonical,
+ * so an offline connector warns instead of failing the audit.
+ */
+async function publicEndpoint(fetcher: typeof fetch): Promise<Check> {
+  try {
+    const response = await fetcher(`${publicHubUrl()}/api/health`, {
+      redirect: 'error',
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (response.ok)
+      return {
+        id: 'beszel:public-endpoint',
+        status: 'pass',
+        summary: `Dashboard answers publicly at ${publicHubUrl()}.`,
+      };
+  } catch {
+    /* Connection details are not evidence; fall through. */
+  }
+  return {
+    id: 'beszel:public-endpoint',
+    status: 'warn',
+    summary: 'BESZEL_PUBLIC_ENDPOINT_OFFLINE',
+    remedy: {
+      action: `${publicHubUrl()} did not answer. Create the Cloudflare tunnel and store its token in the fleet's secrets, then run fleet-sync on the manager so the hub starts its Cloudflare connector. The private dashboard is unaffected.`,
+    },
+  };
+}
+
+function fail(id: string, summary: string, action: string): Check {
+  return { id, status: 'fail', summary, remedy: { action } };
+}
+
+/** Explicit developer scope; the ordinary health command still audits all peers. */
+export function managedHealthScope(
+  tailnet: Tailnet,
+  roster: FleetNode[],
+  includeManager = true
+) {
+  const canonical = definition;
+  const declared = roster.filter((node) =>
+    canonical.workers.some((entry) => entry.id === node.id)
+  );
+  const nodes = declared.length
+    ? enrolledRoster(canonical, { version: 1, nodes: declared }).nodes
+    : [];
+  const computers = tailnet.computers.filter(
+    (peer) =>
+      (includeManager && peer.self) ||
+      canonical.workers.some(
+        (node) =>
+          peer.dns === node.network?.tailscaleName ||
+          peer.dns.split('.')[0] === node.ssh ||
+          nodes.some(
+            (entry) => entry.id === node.id && entry.tailscaleId === peer.id
+          )
+      )
+  );
+  const missing = canonical.workers.filter(
+    (node) => !nodes.some((entry) => entry.id === node.id)
+  );
+  return {
+    nodes,
+    tailnet: {
+      ...tailnet,
+      computers,
+      checks: [
+        ...tailnet.checks,
+        ...missing.map((node) => ({
+          id: `fleet:enrollment:${node.id}`,
+          status: 'fail' as const,
+          summary:
+            'Canonical developer node lacks a verified SSH/check-out registration.',
+          remedy: {
+            action: `Enroll ${node.id} with devfleet fleet-node-add, or use interactive fleet-sync enrollment.`,
+          },
+        })),
+      ],
+    },
+    excluded: tailnet.computers
+      .filter((peer) => !computers.includes(peer))
+      .map((peer) => peer.dns),
+  };
+}
+
+export async function appendManagerLinks(
+  reports: NodeReport[],
+  registered: FleetNode[],
+  run: Runner
+): Promise<void> {
+  for (const node of registered) {
+    const machine = definition.workers.find((entry) => entry.id === node.id);
+    const report = reports.find(
+      (entry) =>
+        entry.node === machine?.network?.tailscaleName || entry.node === node.id
+    );
+    if (!report) continue;
+    report.checks.push(...(await verifyT3Endpoint(node, run)));
+    report.checks.push(await verifyT3Linked(node, run));
+  }
+}

package/src/cli/node-deployment.ts

@@ -0,0 +1,34 @@
+import { join } from 'node:path';
+import { read, object, write } from '../t3/files';
+import { FleetUsageError } from '../errors';
+
+export async function deployment(root: string) {
+  const raw = await read(join(root, 'node_modules/.personal-node.json'));
+  if (raw === null) return null;
+  const data = object(raw);
+  if (
+    data['version'] !== 1 ||
+    typeof data['revision'] !== 'string' ||
+    !/^[a-f0-9]{40}$/.test(data['revision']) ||
+    typeof data['node'] !== 'string' ||
+    !/^[a-z0-9][a-z0-9-]{0,62}$/.test(data['node'])
+  )
+    throw new FleetUsageError(
+      'Invalid local node receipt. Restore it before reconciling.'
+    );
+  return {
+    workspace: join(root, 'node_modules/.fleet-revisions', data['revision']),
+    node: data['node'],
+    revision: data['revision'],
+  };
+}
+
+export async function recordDeployment(
+  root: string,
+  node: string,
+  revision: string
+) {
+  const path = join(root, 'node_modules/.personal-node.json');
+  const content = JSON.stringify({ version: 1, node, revision }) + '\n';
+  if ((await read(path)) !== content) await write(path, content);
+}

package/src/cli/node-sync.ts

@@ -0,0 +1,121 @@
+import { join } from 'node:path';
+import { configureWorkspace } from '../configure';
+import { runCommand } from '../runner';
+import { FleetUsageError } from '../errors';
+import { packageInfo } from '../package-info';
+import type { Runner } from '../types';
+import type { Settings } from './settings';
+import type { CommandOutcome } from './contracts';
+import { syncT3 } from './node-t3';
+import { nodeId, type T3Options } from '../t3/desired';
+import { recordDeployment } from './node-deployment';
+
+export interface NodeSyncOptions extends T3Options {
+  revision?: string;
+}
+
+/** One local convergence: locked tools, public launcher, profiles, then T3. */
+export async function syncNode(
+  options: NodeSyncOptions,
+  settings: Settings,
+  run: Runner = runCommand
+): Promise<CommandOutcome> {
+  if (process.platform === 'win32' && !options.dryRun)
+    throw new FleetUsageError(
+      'Codex proxy node sync requires macOS/Linux/WSL. Use dev-fleet commands for native Windows configuration.'
+    );
+  const node = nodeId(options.id);
+  // An installed package is not a checkout, and the Git repository around it
+  // is the operator's own project: its HEAD is not a dev-fleet revision.
+  if (packageInfo().revision)
+    throw new FleetUsageError(
+      'fleet-node-sync works on a checkout of dev-fleet. Run fleet-sync instead: it converges this machine from a checkout it owns.'
+    );
+  const head = await run(['git', 'rev-parse', '--verify', 'HEAD'], {
+    cwd: settings.workspace,
+  });
+  const revision = options.revision ?? head.stdout.trim();
+  if (!head.ok || !/^[a-f0-9]{40}$/.test(revision))
+    throw new FleetUsageError(
+      'An existing personal checkout is required; set --workspace PATH.'
+    );
+  const request = { node, revision, tool: 'codex', profile: 'proxy' };
+  if (options.dryRun)
+    return {
+      exitCode: 0,
+      data: {
+        version: 1,
+        command: 'fleet-node-sync',
+        ok: true,
+        applied: false,
+        ...request,
+        steps: [
+          'Reconcile locked tools',
+          'Install personal and retire owned ws launcher',
+          'Upsert Codex proxy profile',
+          'Reconcile declared T3 instances and remove stale owned entries',
+        ],
+      },
+    };
+  const checks = await configureWorkspace(settings.workspace, request, run);
+  if (checks.some((check) => check.status !== 'pass'))
+    return {
+      exitCode: 1,
+      data: { version: 1, command: 'fleet-node-sync', ok: false, checks },
+    };
+  return finishSync(options, settings, { request, checks }, run);
+}
+
+async function finishSync(
+  options: NodeSyncOptions,
+  settings: Settings,
+  input: {
+    request: { node: string; revision: string; tool: string; profile: string };
+    checks: Awaited<ReturnType<typeof configureWorkspace>>;
+  },
+  run: Runner
+): Promise<CommandOutcome> {
+  const { request, checks } = input;
+  const { node, revision } = request;
+  const workspace = join(
+    settings.workspace,
+    'node_modules/.fleet-revisions',
+    revision
+  );
+  const installed = await run(['sh', 'bootstrap/install-launcher.sh'], {
+    cwd: workspace,
+    timeoutMs: 30_000,
+  });
+  if (!installed.ok)
+    return {
+      exitCode: 1,
+      data: {
+        version: 1,
+        ok: false,
+        checks,
+        error:
+          'Launcher installation failed; profile changes may already have applied.',
+      },
+    };
+  const t3 = await syncT3({ ...options, id: node }, { ...settings, workspace });
+  if (t3.exitCode !== 0) return t3;
+  await recordDeployment(settings.workspace, node, revision);
+  return {
+    exitCode: 0,
+    data: {
+      version: 1,
+      command: 'fleet-node-sync',
+      ok: true,
+      applied: true,
+      ...request,
+      checks,
+      t3: t3.data,
+      readiness: {
+        authentication: 'unverified',
+        inference: 'unverified',
+        pairing: 'unverified',
+      },
+      next: 'Use devfleet t3-status for configuration drift and devfleet fleet-status for machine health.',
+    },
+  };
+}

package/src/cli/node-t3.ts

@@ -0,0 +1,31 @@
+import { FleetUsageError } from '../errors';
+import type { Settings } from './settings';
+import type { CommandOutcome } from './contracts';
+import { t3Command } from './t3/command';
+import type { T3Options } from '../t3/desired';
+
+export async function syncT3(
+  options: T3Options,
+  settings: Settings
+): Promise<CommandOutcome> {
+  try {
+    return await t3Command('t3-apply', options, settings);
+  } catch (error) {
+    return {
+      exitCode: 1,
+      data: {
+        version: 1,
+        command: 'fleet-node-sync',
+        ok: false,
+        applied: true,
+        stage: 't3',
+        error:
+          error instanceof FleetUsageError
+            ? error.message
+            : 'T3 reconciliation failed; inspect local configuration and ownership state.',
+        progress:
+          'Tools, launcher and profile steps completed. Node receipt was not advanced. Fix the T3 conflict and repeat fleet-node-sync.',
+      },
+    };
+  }
+}

package/src/cli/options.ts

@@ -0,0 +1,141 @@
+import { CAPABILITIES } from '../config';
+import { FleetUsageError } from '../errors';
+import type { Capability } from '../types';
+import type { Settings } from './settings';
+
+export interface CliOptions extends Partial<Settings> {
+  managed?: boolean;
+  workers?: boolean;
+  tailnet?: boolean;
+  list?: boolean;
+  onboard?: boolean;
+  schema?: boolean;
+  json?: boolean;
+  nonInteractive?: boolean;
+  interactive?: boolean;
+  local?: boolean;
+  all?: boolean;
+  node?: string[];
+  require?: string;
+  timeout?: string;
+  strict?: boolean;
+  repair?: string;
+  script?: boolean;
+  planHash?: string;
+  apply?: boolean;
+  yes?: boolean;
+  id?: string;
+  ssh?: string;
+  path?: string;
+  runtime?: string;
+  search?: string;
+  group?: string;
+}
+
+export function capabilities(value?: string): Capability[] {
+  const values =
+    value === 'none'
+      ? []
+      : (value?.split(',') ??
+        CAPABILITIES.filter((entry) => entry !== 'worker'));
+  if (values.some((entry) => !CAPABILITIES.includes(entry as Capability)))
+    throw new FleetUsageError(
+      `--require expects ${CAPABILITIES.join(',')} or none.`
+    );
+  return [...new Set(values)] as Capability[];
+}
+
+export function timeout(options: CliOptions): number {
+  const value = Number(
+    options.timeout ?? (options.apply ? 1_500_000 : 120_000)
+  );
+  if (!Number.isInteger(value) || value < 1000 || value > 1_800_000)
+    throw new FleetUsageError('--timeout must be 1000–1800000 milliseconds.');
+  return value;
+}
+
+/** Validation runs on the internal action selected by fleet-* flags. */
+export function validateOptions(command: string, options: CliOptions): void {
+  if (options.tailnet && options.workers)
+    throw new FleetUsageError('Choose --tailnet or --workers, not both.');
+  if (options.onboard && options.schema)
+    throw new FleetUsageError('Choose --onboard or --schema, not both.');
+  validateMutation(command, options);
+  validateRepair(command, options);
+  validateScope(command, options);
+  if (
+    (['discover', 'health'].includes(command) ||
+      (command === 'repair' && !options.local)) &&
+    options.require !== undefined
+  )
+    throw new FleetUsageError(
+      '--require is supported for roster status and local repair only; tailnet checks use declared roster requirements.'
+    );
+  if (options.timeout !== undefined) timeout(options);
+}
+
+function validateMutation(command: string, options: CliOptions): void {
+  if (options.apply && !['add', 'repair'].includes(command))
+    throw new FleetUsageError(
+      '--apply is only valid for fleet-node-add and fleet-repair.'
+    );
+  if (options.apply && !options.yes)
+    throw new FleetUsageError('Mutation requires both --apply and --yes.');
+}
+
+function validateScope(command: string, options: CliOptions): void {
+  const selected = [options.local, options.all, options.node?.length].filter(
+    Boolean
+  );
+  if (['discover', 'health'].includes(command) && selected.length)
+    throw new FleetUsageError(
+      'Tailscale discovery, --tailnet and --workers always cover all visible computers; --local, --all and --node are not supported.'
+    );
+  if (selected.length > 1)
+    throw new FleetUsageError(
+      'Choose --local, --all, or --node, not a combination.'
+    );
+  validateRosterScope(command, options);
+}
+
+function validateRosterScope(command: string, options: CliOptions): void {
+  if ((options.local || options.all) && !['doctor', 'repair'].includes(command))
+    throw new FleetUsageError(
+      '--local and --all are only valid for fleet-status and fleet-repair.'
+    );
+}
+
+function validateRepair(command: string, options: CliOptions): void {
+  if (
+    options.planHash !== undefined &&
+    !/^[a-f0-9]{64}$/.test(options.planHash)
+  )
+    throw new FleetUsageError(
+      '--plan-hash expects the SHA-256 value from a repair preview.'
+    );
+  const repairFlags =
+    options.repair !== undefined ||
+    options.script === true ||
+    options.planHash !== undefined;
+  if (repairFlags && command !== 'repair')
+    throw new FleetUsageError(
+      '--repair, --script and --plan-hash are only valid for fleet-repair without --list.'
+    );
+  if (options.script && options.apply)
+    throw new FleetUsageError(
+      '--script only generates a preview; run a reviewed repair separately with --apply --yes.'
+    );
+  validateCatalog(command, options);
+}
+
+function validateCatalog(command: string, options: CliOptions): void {
+  const filtered =
+    options.local ||
+    options.all ||
+    Boolean(options.node?.length) ||
+    options.require !== undefined;
+  if (command === 'repairs' && filtered)
+    throw new FleetUsageError(
+      'fleet-repair --list is a static catalog and does not accept target or capability filters.'
+    );
+}

package/src/cli/probe-source.ts

@@ -0,0 +1,7 @@
+import { readFile } from 'node:fs/promises';
+import { bundleProbe } from '../transport';
+
+export async function probeSource(): Promise<string> {
+  if (typeof Bun !== 'undefined') return bundleProbe();
+  return readFile(new URL('./probe.mjs', import.meta.url), 'utf8');
+}