@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/src/repair-runner.ts

@@ -0,0 +1,84 @@
+import { fingerprint } from './fingerprint';
+import { AUTOMATED_REPAIRS, recipe } from './repair-catalog';
+import { syncWorkspace } from './sync';
+import type { AutomatedRepair } from './repair-catalog';
+import type { Check, Runner, Fingerprint } from './types';
+
+export function validRepairs(value: unknown): value is AutomatedRepair[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.length <= 3 &&
+    new Set(value).size === value.length &&
+    value.every((id) => AUTOMATED_REPAIRS.includes(id as AutomatedRepair))
+  );
+}
+
+/** Commands come exclusively from the allowlist, never from probe output or a roster. */
+export async function repairWorkspace(
+  root: string,
+  repairs: AutomatedRepair[],
+  run: Runner,
+  expected?: Fingerprint
+): Promise<Check[]> {
+  if (!validRepairs(repairs)) throw new Error('Unsupported repairs');
+  const before = await fingerprint(root, run);
+  if (!before.head || !Object.values(before.files).every(Boolean))
+    return [
+      {
+        id: 'repair:workspace',
+        status: 'fail',
+        summary:
+          'Repairs require a complete existing checkout. Register/bootstrap it first.',
+      },
+    ];
+  if (expected && JSON.stringify(before) !== JSON.stringify(expected))
+    return [
+      {
+        id: 'repair:inputs',
+        status: 'fail',
+        summary:
+          'Checkout inputs changed since diagnostics. Generate a fresh repair plan before applying.',
+      },
+    ];
+  const checks: Check[] = [];
+  for (const id of AUTOMATED_REPAIRS.filter((entry) =>
+    repairs.includes(entry)
+  )) {
+    const result =
+      id === 'workspace'
+        ? await syncWorkspace(root, false, run)
+        : await ownerCommand(root, id, run);
+    checks.push(...result);
+    if (result.some((check) => check.status !== 'pass')) break;
+  }
+  const after = await fingerprint(root, run);
+  if (JSON.stringify(before) !== JSON.stringify(after))
+    checks.push({
+      id: 'repair:inputs',
+      status: 'fail',
+      summary:
+        'Checkout inputs changed during repair. Stop and review the checkout before retrying.',
+    });
+  return checks;
+}
+
+async function ownerCommand(
+  root: string,
+  id: AutomatedRepair,
+  run: Runner
+): Promise<Check[]> {
+  const result = await run(recipe(id).commands[0]!, {
+    cwd: root,
+    timeoutMs: 1_200_000,
+  });
+  return [
+    {
+      id: `repair:${id}`,
+      status: result.ok ? 'pass' : 'fail',
+      summary: result.ok
+        ? 'The existing owner command completed. Fresh diagnostics determine whether configuration and authorization now pass.'
+        : `The owner command failed (${result.reason}); partial changes are possible. Raw output and credentials are withheld. Later repairs on this computer were stopped.`,
+    },
+  ];
+}

package/src/report.ts

@@ -0,0 +1,71 @@
+import type { NodeReport, Report, Status } from './types';
+
+export function makeReport(command: string, nodes: NodeReport[]): Report {
+  const summary: Record<Status, number> = {
+    pass: 0,
+    warn: 0,
+    fail: 0,
+    skip: 0,
+  };
+  for (const node of nodes)
+    for (const check of node.checks) summary[check.status] += 1;
+  return {
+    version: 1,
+    command,
+    ok: summary.fail === 0,
+    generatedAt: new Date().toISOString(),
+    nodes,
+    summary,
+  };
+}
+
+export function reportExitCode(report: Report, strict: boolean): number {
+  return !report.ok ||
+    (strict &&
+      report.nodes.some((node) =>
+        node.checks.some(
+          (check) =>
+            check.required !== false && ['warn', 'skip'].includes(check.status)
+        )
+      ))
+    ? 1
+    : 0;
+}
+
+export function renderReport(report: Report): string {
+  const lines = [
+    `Fleet ${report.command}: ${report.ok ? 'no failing checks' : 'attention needed'}`,
+  ];
+  for (const node of report.nodes) {
+    lines.push(`\n${node.node}`);
+    for (const check of node.checks) {
+      lines.push(
+        `  ${check.status.toUpperCase()} ${check.id}: ${check.summary}`
+      );
+      if (check.remedy) lines.push(`    Next: ${check.remedy.action}`);
+    }
+  }
+  lines.push(
+    `\n${report.summary.pass} pass, ${report.summary.warn} warn, ${report.summary.fail} fail, ${report.summary.skip} skip`
+  );
+  return lines.join('\n');
+}
+
+export async function mapBounded<Input, Output>(
+  items: Input[],
+  worker: (input: Input) => Promise<Output>,
+  concurrency = 4
+): Promise<Output[]> {
+  const results = new Array<Output>(items.length);
+  let cursor = 0;
+  const consume = async (): Promise<void> => {
+    while (cursor < items.length) {
+      const index = cursor++;
+      results[index] = await worker(items[index]!);
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, consume)
+  );
+  return results;
+}

package/src/runner.ts

@@ -0,0 +1,104 @@
+import { spawn } from 'node:child_process';
+import type { CommandOptions, CommandResult, Runner } from './types';
+import type {
+  ChildProcess,
+  ChildProcessWithoutNullStreams,
+  StdioOptions,
+} from 'node:child_process';
+
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+
+function terminate(child: ChildProcess): void {
+  try {
+    if (process.platform !== 'win32' && child.pid)
+      process.kill(-child.pid, 'SIGKILL');
+    else child.kill('SIGKILL');
+  } catch {}
+}
+
+export function runCommand(
+  command: string[],
+  options: CommandOptions = {}
+): Promise<CommandResult> {
+  return new Promise((resolve) => {
+    const child = spawn(command[0]!, command.slice(1), {
+      cwd: options.cwd,
+      env: {
+        ...(options.isolatedEnv ? {} : process.env),
+        ...options.env,
+        GIT_TERMINAL_PROMPT: '0',
+        CI: '1',
+      },
+      stdio: childStdio(options.preserveOperationLock),
+      windowsHide: true,
+      detached: process.platform !== 'win32',
+    }) as ChildProcessWithoutNullStreams;
+    let stdout = '';
+    let stderr = '';
+    let bytes = 0;
+    let finished = false;
+    let reason: CommandResult['reason'] = 'exit';
+    const finish = (ok: boolean): void => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      child.stdin.destroy();
+      child.stdout.destroy();
+      child.stderr.destroy();
+      resolve({ ok, stdout, stderr, reason });
+    };
+    const abort = (cause: CommandResult['reason']): void => {
+      reason = cause;
+      terminate(child);
+      finish(false);
+    };
+    const timer = setTimeout(() => {
+      abort('timeout');
+    }, options.timeoutMs ?? 15_000);
+    const capture = (stream: 'stdout' | 'stderr', chunk: string): void => {
+      if (finished) return;
+      bytes += Buffer.byteLength(chunk);
+      if (bytes > MAX_OUTPUT_BYTES) {
+        abort('overflow');
+        return;
+      }
+      if (stream === 'stdout') stdout += chunk;
+      else stderr += chunk;
+    };
+    child.stdout
+      .setEncoding('utf8')
+      .on('data', (chunk: string) => capture('stdout', chunk));
+    child.stderr
+      .setEncoding('utf8')
+      .on('data', (chunk: string) => capture('stderr', chunk));
+    child.stdin.on('error', () => undefined);
+    child.on('error', () => {
+      abort('missing');
+    });
+    child.on('close', (code) => {
+      finish(code === 0 && reason === 'exit');
+    });
+    child.stdin.end(options.input);
+  });
+}
+
+/** Keep the shell-owned flock in descendants if their JS parent dies. */
+export const runLockedCommand: Runner = (command, options = {}) =>
+  runCommand(command, { ...options, preserveOperationLock: true });
+
+function childStdio(preserveLock: boolean | undefined): StdioOptions {
+  return preserveLock
+    ? [
+        'pipe',
+        'pipe',
+        'pipe',
+        'ignore',
+        'ignore',
+        'ignore',
+        'ignore',
+        'ignore',
+        'ignore',
+        9,
+      ]
+    : ['pipe', 'pipe', 'pipe'];
+}

package/src/secrets.ts

@@ -0,0 +1,169 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** The secrets fleet code needs, by what they are for. Where each one is kept
+ * is the fleet's own choice, declared under `secrets` in its configuration.
+ */
+export const SECRET_NAMES = [
+  'proxy-client-key',
+  'monitoring-account-password',
+  'monitoring-tunnel-token',
+  'proxy-tunnel-token',
+] as const;
+export type SecretName = (typeof SECRET_NAMES)[number];
+
+/** A secret's location in a Vault KV v2 mount. */
+export type VaultLocation = { path: string; field: string };
+export type SecretsConfig =
+  | { provider: 'env' }
+  | { provider: 'file'; directory?: string }
+  | { provider: 'sops'; file: string }
+  | {
+      provider: 'vault';
+      address: string;
+      mount: string;
+      locations: Record<SecretName, VaultLocation>;
+    };
+
+/** Runs a command and returns its stdout, or null when it fails. */
+export type SecretCommand = (
+  argv: string[],
+  env?: Record<string, string>
+) => Promise<string | null>;
+
+/** One read of one secret for this node. Null when it is not available; the
+ * value is never logged, printed or placed in argv.
+ */
+export type SecretsProvider = (name: SecretName) => Promise<string | null>;
+
+const present = (value: string | null | undefined): string | null =>
+  value?.trim() ? value.trim() : null;
+
+/** `proxy-client-key` is read from `DEVFLEET_SECRET_PROXY_CLIENT_KEY`. */
+export const envName = (name: SecretName): string =>
+  `DEVFLEET_SECRET_${name.toUpperCase().replaceAll('-', '_')}`;
+
+export function secretsProvider(
+  config: SecretsConfig,
+  options: {
+    env?: NodeJS.ProcessEnv;
+    run?: SecretCommand;
+    home?: string;
+  } = {}
+): SecretsProvider {
+  const env = options.env ?? process.env;
+  const run = options.run ?? execute;
+  if (config.provider === 'env')
+    return async (name) => present(env[envName(name)]);
+  if (config.provider === 'file') {
+    // One private file per secret, named after it.
+    const directory =
+      config.directory ??
+      join(options.home ?? homedir(), '.config/dev-fleet/secrets');
+    return async (name) =>
+      present(await readFile(join(directory, name), 'utf8').catch(() => null));
+  }
+  if (config.provider === 'sops')
+    // An age- (or KMS-) encrypted document with one top-level key per secret.
+    return async (name) =>
+      present(
+        await run([
+          'sops',
+          '--decrypt',
+          '--extract',
+          `["${name}"]`,
+          config.file,
+        ])
+      );
+  return async (name) => {
+    const location = config.locations[name];
+    return present(
+      await run([
+        'vault',
+        'kv',
+        'get',
+        `-address=${config.address}`,
+        `-mount=${config.mount}`,
+        `-field=${location.field}`,
+        location.path,
+      ])
+    );
+  };
+}
+
+const execute: SecretCommand = (argv) =>
+  new Promise((resolve) => {
+    const child = spawn(argv[0]!, argv.slice(1), {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 20_000,
+    });
+    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));
+  });
+
+type Fields = Record<string, unknown>;
+const text = (value: unknown): value is string =>
+  typeof value === 'string' && value.length > 0 && value.length <= 512;
+const only = (value: Fields, allowed: string[]) =>
+  Object.keys(value).every((key) => allowed.includes(key));
+
+const PARSERS: Record<string, (value: Fields) => SecretsConfig | null> = {
+  env: (value) => (only(value, ['provider']) ? { provider: 'env' } : null),
+  file: (value) =>
+    only(value, ['provider', 'directory']) &&
+    (value['directory'] === undefined || text(value['directory']))
+      ? {
+          provider: 'file',
+          ...(text(value['directory'])
+            ? { directory: value['directory'] }
+            : {}),
+        }
+      : null,
+  sops: (value) =>
+    only(value, ['provider', 'file']) && text(value['file'])
+      ? { provider: 'sops', file: value['file'] }
+      : null,
+  vault: (value) => {
+    const { address, mount } = value;
+    const locations = vaultLocations(value['locations']);
+    return only(value, ['provider', 'address', 'mount', 'locations']) &&
+      text(address) &&
+      /^https:\/\/[A-Za-z0-9.-]{1,253}$/.test(address) &&
+      text(mount) &&
+      locations
+      ? { provider: 'vault', address, mount, locations }
+      : null;
+  },
+};
+
+function vaultLocations(
+  value: unknown
+): Record<SecretName, VaultLocation> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const fields = value as Fields;
+  if (!only(fields, [...SECRET_NAMES])) return null;
+  const valid = SECRET_NAMES.every((name) => {
+    const location = fields[name] as Fields | undefined;
+    return (
+      location !== null &&
+      typeof location === 'object' &&
+      only(location, ['path', 'field']) &&
+      text(location['path']) &&
+      text(location['field'])
+    );
+  });
+  return valid ? (fields as Record<SecretName, VaultLocation>) : null;
+}
+
+/** The `secrets` block of a fleet configuration, or null when it is invalid. */
+export function parseSecretsConfig(value: unknown): SecretsConfig | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const fields = value as Fields;
+  return PARSERS[String(fields['provider'])]?.(fields) ?? null;
+}

package/src/service-auth.ts

@@ -0,0 +1,115 @@
+import { record } from './config';
+import type { Check, CommandResult, Runner } from './types';
+
+interface Service {
+  id: string;
+  command: string[];
+  action: string;
+  valid: (result: CommandResult) => boolean;
+}
+function json(result: CommandResult): Record<string, unknown> | null {
+  try {
+    const data: unknown = JSON.parse(result.stdout);
+    return record(data) ? data : null;
+  } catch {
+    return null;
+  }
+}
+export async function codingAuth(
+  id: 'codex' | 'claude',
+  run: Runner
+): Promise<Check[]> {
+  return [
+    await serviceCheck(
+      id === 'codex'
+        ? {
+            id,
+            command: ['codex', 'login', 'status'],
+            action: 'Run codex login on this computer as its operator.',
+            valid: (result) =>
+              /^Logged in using (ChatGPT|an API key|API key)\b/im.test(
+                `${result.stdout}\n${result.stderr}`
+              ),
+          }
+        : {
+            id,
+            command: ['claude', 'auth', 'status', '--json'],
+            action: 'Run claude auth login on this computer as its operator.',
+            valid: (result) => json(result)?.['loggedIn'] === true,
+          },
+      run
+    ),
+  ];
+}
+
+export async function serviceAuth(run: Runner): Promise<Check[]> {
+  const services: Service[] = [
+    {
+      id: 'railway',
+      command: ['railway', 'whoami', '--json'],
+      action: 'Run railway login on this computer.',
+      valid: (result) => typeof json(result)?.['id'] === 'string',
+    },
+    {
+      id: 'vercel',
+      command: ['vercel', 'whoami'],
+      action: 'Run vercel login on this computer.',
+      valid: (result) =>
+        /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,100}$/.test(result.stdout.trim()),
+    },
+    {
+      id: 'cloudflare',
+      command: ['wrangler', 'whoami', '--json'],
+      action: 'Run wrangler login on this computer.',
+      valid: (result) => json(result)?.['loggedIn'] === true,
+    },
+    {
+      id: 'aws',
+      command: [
+        'aws',
+        'sts',
+        'get-caller-identity',
+        '--output',
+        'json',
+        '--no-cli-pager',
+      ],
+      action:
+        'Select and authenticate the intended AWS profile on this computer.',
+      valid: (result) =>
+        typeof json(result)?.['Account'] === 'string' &&
+        typeof json(result)?.['Arn'] === 'string',
+    },
+    {
+      id: 'npm',
+      command: ['npm', 'whoami', '--registry=https://registry.npmjs.org/'],
+      action: 'Run npm login only if this computer should publish packages.',
+      valid: (result) =>
+        /^[a-z0-9][a-z0-9._-]{0,213}$/.test(result.stdout.trim()),
+    },
+  ];
+  const checks: Check[] = [];
+  for (const service of services) checks.push(await serviceCheck(service, run));
+  for (const id of ['gemini', 'copilot', 'opencode'])
+    checks.push({
+      id: `auth:${id}`,
+      status: 'skip',
+      summary: `${id} provider authorization has no verified noninteractive status adapter in this CLI. Installed binaries or saved keys are not proof of access.`,
+      remedy: {
+        action: `Verify ${id} provider access locally using its supported account diagnostics. No prompt or billable request was made.`,
+      },
+    });
+  return checks;
+}
+
+async function serviceCheck(service: Service, run: Runner): Promise<Check> {
+  const result = await run(service.command, { timeoutMs: 15_000 });
+  const ok = result.ok && service.valid(result);
+  return {
+    id: `auth:${service.id}`,
+    status: ok ? 'pass' : 'fail',
+    summary: ok
+      ? `${service.id} reports an authenticated session in this process context; no credential or account output retained.`
+      : `${service.id} login is missing or could not be verified (${result.reason}); no credential output retained.`,
+    ...(!ok ? { remedy: { action: service.action } } : {}),
+  };
+}

package/src/ssh.ts

@@ -0,0 +1,135 @@
+import type { CommandResult, FleetNode, Check } from './types';
+
+export function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+export function sshArgs(node: FleetNode): string[] {
+  return [
+    'ssh',
+    '-T',
+    '-a',
+    '-o',
+    'BatchMode=yes',
+    '-o',
+    'StrictHostKeyChecking=yes',
+    '-o',
+    'UpdateHostKeys=no',
+    '-o',
+    'ConnectTimeout=8',
+    '-o',
+    'ConnectionAttempts=1',
+    '-o',
+    'ServerAliveInterval=5',
+    '-o',
+    'ServerAliveCountMax=2',
+    '-o',
+    'ClearAllForwardings=yes',
+    '-o',
+    'PermitLocalCommand=no',
+    '-o',
+    'ControlMaster=no',
+    '-o',
+    'ControlPath=none',
+    node.ssh,
+  ];
+}
+
+export function remoteCommand(node: FleetNode, request: object): string[] {
+  const encoded = Buffer.from(JSON.stringify(request)).toString('base64');
+  const command = `cd -- ${shellQuote(node.workspace)} && export PATH="$HOME/.local/share/mise/shims:$HOME/.local/bin:$PATH" && exec ${shellQuote(node.runtime ?? 'node')} --input-type=module - ${shellQuote(encoded)}`;
+  return [...sshArgs(node), command];
+}
+
+const FAILURES = [
+  {
+    pattern:
+      /REMOTE HOST IDENTIFICATION HAS CHANGED|Host key verification failed|No .* host key is known/i,
+    id: 'ssh:host-key',
+    summary: 'SSH host key is unknown or changed.',
+    action:
+      'Verify the host fingerprint out of band, then update known_hosts manually. Never disable host-key checking.',
+  },
+  {
+    pattern:
+      /Could not resolve hostname|Name or service not known|nodename nor servname/i,
+    id: 'ssh:dns',
+    summary: 'SSH hostname or jump-host resolution failed.',
+    action:
+      'Check the alias in ~/.ssh/config, DNS/VPN/Tailscale connectivity, and ProxyJump host resolution.',
+  },
+  {
+    pattern:
+      /Permission denied|sign_and_send_pubkey|agent refused|Too many authentication failures/i,
+    id: 'ssh:auth',
+    summary: 'SSH key/agent authentication failed.',
+    action:
+      'Use ssh-add -l and ssh -vvv ALIAS locally; check User, IdentityFile, IdentitiesOnly, agent/keychain access and authorized_keys. Do not share debug logs without review.',
+  },
+  {
+    pattern: /Connection refused|No route to host|Network is unreachable/i,
+    id: 'ssh:network',
+    summary: 'SSH endpoint or jump host is unreachable/refused.',
+    action:
+      'Verify the node is awake, VPN is connected, sshd is enabled and the configured port is reachable. Do not open a public SSH port automatically.',
+  },
+  {
+    pattern:
+      /(?:bun|node).*not found|No such file or directory|cannot cd|can.t cd/i,
+    id: 'ssh:runtime',
+    summary:
+      'Remote workspace or Node/Bun runtime is missing from the non-login SSH environment.',
+    action:
+      'Follow fleet-nodes --onboard; configure absolute workspace/runtime paths. GUI terminals and SSH shells may have different PATHs.',
+  },
+];
+
+export function sshFailure(result: CommandResult): Check {
+  if (
+    /Tailscale SSH requires an additional check|To authenticate, visit: https:\/\/login\.tailscale\.com\//i.test(
+      result.stderr
+    )
+  )
+    return {
+      id: 'ssh:tailscale-check',
+      status: 'fail',
+      summary: 'TAILSCALE_INTERACTIVE_AUTHORIZATION_REQUIRED',
+      remedy: {
+        action:
+          'The current Tailscale SSH policy requires interactive reauthentication. Update the tailnet policy for the enrolled manager/worker scope, or enroll a separately verified OpenSSH key route. Fleet never bypasses trust or prompts for a password.',
+      },
+    };
+  if (result.reason === 'timeout')
+    return {
+      id: 'ssh:timeout',
+      status: 'fail',
+      summary: 'SSH or remote probe exceeded its deadline.',
+      remedy: {
+        action:
+          'Check sleeping nodes, VPN, ProxyJump, network reachability and noninteractive shell startup. Increase --timeout only after diagnosis.',
+      },
+    };
+  if (result.reason === 'missing')
+    return {
+      id: 'ssh:missing',
+      status: 'fail',
+      summary: 'Cannot launch the local SSH client.',
+      remedy: {
+        action:
+          'Install/enable the OS OpenSSH client and expose it to the terminal/editor PATH.',
+      },
+    };
+  const match = FAILURES.find((failure) => failure.pattern.test(result.stderr));
+  return {
+    id: match?.id ?? 'ssh:probe',
+    status: 'fail',
+    summary:
+      match?.summary ??
+      `Remote probe failed (${result.reason}); raw output withheld.`,
+    remedy: {
+      action:
+        match?.action ??
+        'Run ssh ALIAS manually; verify workspace/runtime, shell startup output and CLI compatibility. Never paste credentials or full logs into agent context.',
+    },
+  };
+}