@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/src/remote-bootstrap.ts

@@ -0,0 +1,212 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile, unlink, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { prepareSource } from './machine/source';
+import { isRevision } from './machine/state';
+import { sshArgs, shellQuote, sshFailure } from './ssh';
+import type { FleetNode, NodeReport, Runner, Check } from './types';
+import { record } from './config';
+import type { FleetDefinition } from './definition';
+import { cleanCheck, validCheck } from './protocol';
+
+export interface BootstrapPayload {
+  revision: string;
+  script: string;
+  bundle: string;
+  digest: string;
+  authorizeSudo?: string;
+  /** The fleet configuration every node keeps at ~/.config/dev-fleet/fleet.json. */
+  config?: string;
+}
+/** No manager tool installation; Git/source preparation is part of apply approval. */
+export async function prepareBootstrap(
+  root: string,
+  revision: string,
+  run: Runner,
+  options: { definition?: FleetDefinition; checkout?: string } = {}
+): Promise<BootstrapPayload | null> {
+  if (!isRevision(revision)) return null;
+  const source = await prepareSource(root, revision, run, options.checkout);
+  if (!source) return null;
+  const script = await trackedScript(
+    source,
+    revision,
+    'bootstrap/fleet-remote-bootstrap.sh',
+    run
+  );
+  const sudoScript = await trackedScript(
+    source,
+    revision,
+    'ansible/ubuntu/authorize-sudo.sh',
+    run
+  );
+  if (!script || !sudoScript) return null;
+  const payload = await bundleRevision(
+    { root, source, revision },
+    { script, authorizeSudo: sudoScript },
+    run
+  );
+  // The fleet configuration is data, not source: it travels beside the code.
+  return payload && options.definition
+    ? { ...payload, config: JSON.stringify(options.definition, null, 2) + '\n' }
+    : payload;
+}
+
+/** Installs the approved fleet configuration where every launcher and job on
+ * the node reads it. It holds no secret.
+ */
+const INSTALL_CONFIG =
+  'umask 077; d="$HOME/.config/dev-fleet"; mkdir -p "$d" && cat >"$d/fleet.json.new" && mv "$d/fleet.json.new" "$d/fleet.json"';
+
+/** Workers run one revision and never need history: the bundle holds only the
+ * approved commit and its files (about a quarter of the full history), and the
+ * receiving checkout is marked shallow at that commit. `git bundle create`
+ * cannot cut history, so the v2 bundle is written directly: a header naming
+ * the commit, then a pack of exactly its objects.
+ */
+const SNAPSHOT_BUNDLE = [
+  'objects=$(git rev-list --objects --no-walk "$1") || exit 1',
+  '{ printf \'# v2 git bundle\\n%s refs/personal-fleet/%s\\n\\n\' "$1" "$1"',
+  'printf \'%s\\n\' "$objects" | git pack-objects --stdout -q; } >"$2"',
+].join('\n');
+
+async function bundleRevision(
+  {
+    root,
+    source,
+    revision,
+  }: { root: string; source: string; revision: string },
+  scripts: { script: string; authorizeSudo: string },
+  run: Runner
+): Promise<BootstrapPayload | null> {
+  const path = join(root, `transfer-${randomUUID()}.bundle`);
+  try {
+    const bundled = await run(
+      ['sh', '-c', SNAPSHOT_BUNDLE, 'bundle', revision, path],
+      { cwd: source, timeoutMs: 120_000 }
+    );
+    if (!bundled.ok || (await stat(path)).size > 512 * 1024 * 1024) return null;
+    const bundle = await readFile(path);
+    return {
+      revision,
+      ...scripts,
+      bundle: bundle.toString('base64'),
+      digest: createHash('sha256').update(bundle).digest('hex'),
+    };
+  } finally {
+    await unlink(path).catch(() => undefined);
+  }
+}
+export async function bootstrapRemote(
+  node: FleetNode,
+  payload: BootstrapPayload,
+  run: Runner
+): Promise<NodeReport> {
+  const cached = await cachedRevision(node, payload.revision, run);
+  if (typeof cached !== 'boolean') return { node: node.id, checks: [cached] };
+  if (payload.config) {
+    const installed = await run([...sshArgs(node), INSTALL_CONFIG], {
+      input: payload.config,
+      timeoutMs: 20_000,
+    });
+    if (!installed.ok)
+      return { node: node.id, checks: [sshFailure(installed)] };
+  }
+  const transfer = cached
+    ? { mode: 'cached', input: '' }
+    : { mode: 'transfer', input: payload.bundle };
+  const command = [
+    'sh',
+    '-c',
+    payload.script,
+    'fleet-bootstrap',
+    payload.revision,
+    payload.digest,
+    node.id,
+    transfer.mode,
+  ]
+    .map(shellQuote)
+    .join(' ');
+  const result = await run([...sshArgs(node), command], {
+    input: transfer.input,
+    timeoutMs: 5_400_000,
+  });
+  const evidence = parseEvidence(result);
+  if (evidence) return { node: node.id, checks: evidence };
+  if (!result.ok) return { node: node.id, checks: [sshFailure(result)] };
+  return {
+    node: node.id,
+    checks: [
+      {
+        id: 'bootstrap:protocol',
+        status: 'fail',
+        summary: 'REMOTE_BOOTSTRAP_EVIDENCE_INVALID',
+        remedy: {
+          action:
+            'Inspect the source-owned remote operation and lock. Do not assume a manager disconnect stopped installation.',
+        },
+      },
+    ],
+  };
+}
+
+async function cachedRevision(
+  node: FleetNode,
+  revision: string,
+  run: Runner
+): Promise<boolean | Check> {
+  const command = `d="$HOME/.local/share/personal/fleet/revisions/${revision}"; test ! -L "$d" && test -d "$d/.git" && test "$(git -C "$d" rev-parse HEAD 2>/dev/null)" = '${revision}' && test "$(git -C "$d" rev-parse --show-toplevel 2>/dev/null)" = "$d" && clean=$(git -C "$d" status --porcelain 2>/dev/null) && test -z "$clean" && printf ready`;
+  const result = await run([...sshArgs(node), command], { timeoutMs: 20_000 });
+  if (!result.ok) {
+    const failure = sshFailure(result);
+    if (result.reason !== 'exit' || failure.id !== 'ssh:probe') return failure;
+  }
+  return result.ok && result.stdout === 'ready';
+}
+
+function parseEvidence(result: {
+  stdout: string;
+  ok: boolean;
+}): Check[] | null {
+  try {
+    const value: unknown = JSON.parse(result.stdout);
+    if (
+      record(value) &&
+      value['version'] === 1 &&
+      Array.isArray(value['checks']) &&
+      value['checks'].length > 0 &&
+      value['checks'].length <= 200 &&
+      value['checks'].every(validCheck)
+    ) {
+      const checks = value['checks'].map(cleanCheck);
+      if (!result.ok && !checks.some((check) => check.status === 'fail'))
+        checks.push({
+          id: 'bootstrap:exit',
+          status: 'fail',
+          summary: 'REMOTE_BOOTSTRAP_EXIT_FAILED',
+          remedy: {
+            action:
+              'The remote process failed despite partial evidence. Inspect its operation state before retry; no success receipt may advance.',
+          },
+        });
+      return checks;
+    }
+  } catch {
+    /* Raw SSH output is never included in reports. */
+  }
+  return null;
+}
+
+export async function trackedScript(
+  source: string,
+  revision: string,
+  path: string,
+  run: Runner
+): Promise<string | null> {
+  const result = await run(['git', 'show', revision + ':' + path], {
+    cwd: source,
+  });
+  return result.ok && result.stdout.startsWith('#!/bin/sh\n')
+    ? result.stdout
+    : null;
+}

package/src/remote-entry.ts

@@ -0,0 +1,89 @@
+import { configureWorkspace, validConfiguration } from './configure';
+import { parseConfig, record } from './config';
+import { probe } from './probe';
+import { runCommand } from './runner';
+import { syncWorkspace } from './sync';
+import { repairWorkspace, validRepairs } from './repair-runner';
+import { validSnapshot } from './protocol';
+import type { Fingerprint } from './types';
+
+async function main(): Promise<void> {
+  const raw: unknown = JSON.parse(
+    Buffer.from(process.argv.at(-1) ?? '', 'base64').toString()
+  );
+  if (!validRequest(raw)) throw new Error('Invalid request.');
+  const node = parseConfig({ version: 1, nodes: [raw['node']] }).nodes[0]!;
+  if (raw['action'] === 'configure') {
+    await configureRequest(raw, node);
+  } else if (raw['action'] === 'repair') {
+    if (
+      raw['apply'] !== true ||
+      !validRepairs(raw['repairs']) ||
+      !validSnapshot({
+        version: 1,
+        platform: 'request',
+        checks: [],
+        fingerprint: raw['expected'],
+      })
+    )
+      throw new Error(
+        'Repair requires explicit authorization and supported actions.'
+      );
+    const checks = await repairWorkspace(
+      node.workspace,
+      raw['repairs'],
+      runCommand,
+      raw['expected'] as Fingerprint
+    );
+    process.stdout.write(JSON.stringify({ version: 1, checks }));
+  } else if (raw['action'] === 'sync') {
+    if (raw['apply'] !== true)
+      throw new Error('Sync requires explicit authorization.');
+    const checks = await syncWorkspace(
+      node.workspace,
+      raw['pull'] === true,
+      runCommand
+    );
+    process.stdout.write(JSON.stringify({ version: 1, checks }));
+  } else
+    process.stdout.write(
+      JSON.stringify(
+        await probe(node.workspace, node.required, runCommand, node.id)
+      )
+    );
+}
+
+await main().catch(() => {
+  process.stdout.write(
+    JSON.stringify({
+      version: 1,
+      error: 'Remote operation failed; inspect node locally.',
+    })
+  );
+  process.exitCode = 1;
+});
+
+async function configureRequest(
+  raw: Record<string, unknown>,
+  node: { id: string; workspace: string }
+): Promise<void> {
+  if (
+    raw['apply'] !== true ||
+    !validConfiguration(raw['configuration']) ||
+    raw['configuration'].node !== node.id
+  )
+    throw new Error('Invalid configuration request.');
+  const checks = await configureWorkspace(
+    node.workspace,
+    raw['configuration'],
+    runCommand
+  );
+  process.stdout.write(JSON.stringify({ version: 1, checks }));
+}
+
+function validRequest(raw: unknown): raw is Record<string, unknown> {
+  return (
+    record(raw) &&
+    ['probe', 'sync', 'repair', 'configure'].includes(String(raw['action']))
+  );
+}

package/src/remote-lock.ts

@@ -0,0 +1,12 @@
+/** POSIX lock prelude shared by every remote operation. Linux uses flock(1);
+ * macOS lacks it, so the same descriptor is locked through Python's fcntl. The
+ * lock belongs to the shell's open descriptor and persists until that exits.
+ */
+export function remoteLockPrelude(
+  root = '"$HOME/.local/share/personal/fleet"'
+): string {
+  return [
+    `exec 9>${root}/remote-operation.lock`,
+    'if command -v flock >/dev/null 2>&1; then flock -n 9; else python3 -c "import fcntl; fcntl.flock(9, fcntl.LOCK_EX | fcntl.LOCK_NB)" 9>&9; fi',
+  ].join(' && ');
+}

package/src/repair-catalog.ts

@@ -0,0 +1,206 @@
+export type AutomatedRepair = 'workspace' | 'workstation' | 'providers';
+export interface RepairRecipe {
+  id: string;
+  title: string;
+  owner: string;
+  automatic: boolean;
+  action: string;
+  commands: string[][];
+}
+const login = (
+  id: string,
+  title: string,
+  commands: string[][],
+  action: string
+): RepairRecipe => ({
+  id: `login:${id}`,
+  title,
+  owner: `${id} native CLI`,
+  automatic: false,
+  action,
+  commands,
+});
+export const REPAIR_RECIPES: RepairRecipe[] = [
+  {
+    id: 'workspace',
+    title: 'Install locked tools and frozen dependencies',
+    owner: 'mise / bootstrap/setup.ts',
+    automatic: true,
+    action:
+      'Runs the existing shared setup and trusted checkout lifecycle scripts. Updates user mise/PATH configuration and writes a sync receipt. Does not pull or reset Git.',
+    commands: [
+      [
+        'mise',
+        'exec',
+        '--locked',
+        'bun',
+        '--',
+        'bun',
+        'bootstrap/setup.ts',
+        '--non-interactive',
+      ],
+    ],
+  },
+  {
+    id: 'workstation',
+    title: 'Install the devfleet launcher',
+    owner: 'dev-fleet',
+    automatic: true,
+    action:
+      'Links ~/.local/bin/devfleet to this checkout. Nothing is copied and no configuration is changed.',
+    commands: [['sh', 'bootstrap/install-launcher.sh']],
+  },
+  {
+    id: 'providers',
+    title: "Refresh this machine's own service credentials",
+    owner: 'dev-fleet',
+    automatic: true,
+    action:
+      "Renews this machine's own secrets-provider session and the service logins derived from it. No credentials are copied from another computer.",
+    commands: [['bun', 'bootstrap/worker-auth.ts']],
+  },
+  login(
+    'codex',
+    'Sign in to Codex on this machine',
+    [['codex', 'login', '--device-auth']],
+    'Approve the device flow in your browser. Run codex login status afterward; retain this machine’s own credential store.'
+  ),
+  login(
+    'claude',
+    'Sign in to Claude Code on this machine',
+    [['claude', 'auth', 'login']],
+    'Complete the native browser login, then run claude auth status --json. API-key and subscription contexts can differ.'
+  ),
+  login(
+    'github',
+    'Sign in to GitHub and configure Git',
+    [
+      [
+        'gh',
+        'auth',
+        'login',
+        '--hostname',
+        'github.com',
+        '--web',
+        '--git-protocol',
+        'https',
+      ],
+      ['gh', 'auth', 'setup-git'],
+    ],
+    'Approve GitHub in the browser on the intended account, then run gh auth status --active. Environment tokens can override stored login; inspect their source locally.'
+  ),
+  login(
+    'vault',
+    'Authorize this machine for the shared Vault',
+    [],
+    'Run vault login -method=userpass username=YOUR_USERNAME in your own terminal. The native CLI prompts privately for the password. Use the existing permitted project/config; never copy VAULT_TOKEN between computers.'
+  ),
+  login(
+    'railway',
+    'Sign in to Railway',
+    [['railway', 'login', '--browserless']],
+    'Complete the browserless native flow, then run railway whoami --json.'
+  ),
+  login(
+    'vercel',
+    'Sign in to Vercel',
+    [['vercel', 'login']],
+    'Complete native login, then run vercel whoami. Select the intended team/project separately; do not create resources as a login repair.'
+  ),
+  login(
+    'cloudflare',
+    'Sign in to Cloudflare',
+    [['wrangler', 'login', '--browser=false']],
+    'Complete native OAuth login, then run wrangler whoami --json. For headless SSH, prefer an existing scoped API token injected by the approved Vault config. --browser=false suppresses browser launch; it does not make a remote loopback callback reachable. Any OAuth callback tunnel needs explicit operator setup. Resource access still depends on account permissions.'
+  ),
+  login(
+    'aws',
+    'Refresh the selected AWS SSO session',
+    [['aws', 'sso', 'login']],
+    'Configure the intended profile with aws configure sso first if needed. Login and the health check use this shell’s current profile; no access keys are cloned.'
+  ),
+  login(
+    'npm',
+    'Sign in to npm on this machine',
+    [
+      [
+        'npm',
+        'login',
+        '--auth-type=web',
+        '--registry=https://registry.npmjs.org/',
+      ],
+    ],
+    'Complete the specific CLI approval and run npm whoami. Prefer the existing trusted-publisher CI workflow for releases.'
+  ),
+  login(
+    'opencode',
+    'Authorize an OpenCode provider',
+    [['opencode', 'auth', 'login']],
+    'Prefer the existing Vault-backed providers repair for managed API keys. Native auth login handles an operator-owned OAuth provider. Credential listing alone does not prove live provider access.'
+  ),
+  login(
+    'copilot',
+    'Sign in to Copilot',
+    [['copilot', 'login']],
+    'Complete native login; provider authorization still needs supported operator diagnostics. No model prompt is used for health checking.'
+  ),
+  login(
+    'gemini',
+    'Sign in to Gemini',
+    [],
+    'Open Gemini interactively and choose its supported sign-in flow. Provider authorization remains unverified without a supported read-only status adapter.'
+  ),
+  {
+    id: 't3',
+    title: 'Enable and authorize T3 Connect',
+    owner: 'T3',
+    automatic: false,
+    action:
+      'Run t3 up --connect in this machine’s terminal and approve the intended connection. Treat pairing material as private. Then check t3 status --json and perform an operator peer test.',
+    commands: [['t3', 'up', '--connect']],
+  },
+  {
+    id: 'docker',
+    title: 'Start the intended Docker runtime',
+    owner: 'OS / Docker',
+    automatic: false,
+    action:
+      'Start Docker Desktop on desktop systems, or the already-installed Docker service using the OS service manager on Linux. Confirm the intended context with docker context ls. This repair never installs a daemon, invokes sudo, changes contexts or exposes a TCP socket.',
+    commands: [
+      ['docker', 'context', 'ls'],
+      ['docker', 'info'],
+    ],
+  },
+  {
+    id: 'password-manager',
+    title: 'Review shared human login onboarding',
+    owner: 'password-manager / Bitwarden',
+    automatic: false,
+    action:
+      'Use the existing password-manager doctor and actions list on this computer. Its setup guides native consent and Bitwarden enrollment. Keep its private state and OS credential store local. Password vault access does not authorize native CLI OAuth sessions; imports and rotations remain separate reviewed workflows.',
+    commands: [
+      ['bun', 'run', 'password-manager', 'doctor'],
+      ['bun', 'run', 'password-manager', 'actions', 'list'],
+    ],
+  },
+  {
+    id: 'operator',
+    title: 'Resolve the check with its owning tool',
+    owner: 'operator / existing owner',
+    automatic: false,
+    action:
+      'Follow the check’s remedy on the affected machine. Verify host fingerprints, register real SSH aliases/checkouts, reconcile Git changes, or perform the named end-to-end test. Infrastructure changes remain OpenTofu-owned.',
+    commands: [],
+  },
+];
+export const AUTOMATED_REPAIRS: AutomatedRepair[] = [
+  'workspace',
+  'workstation',
+  'providers',
+];
+export function recipe(id: string): RepairRecipe {
+  return (
+    REPAIR_RECIPES.find((entry) => entry.id === id) ??
+    REPAIR_RECIPES.find((entry) => entry.id === 'operator')!
+  );
+}

package/src/repair-plan.ts

@@ -0,0 +1,78 @@
+import { AUTOMATED_REPAIRS, recipe } from './repair-catalog';
+import type { RepairRecipe } from './repair-catalog';
+import type { Check, FleetNode, NodeReport, Fingerprint } from './types';
+
+export interface RepairTarget {
+  name: string;
+  root: string;
+  node?: FleetNode;
+  fingerprint?: Fingerprint;
+}
+export interface RepairStep extends RepairRecipe {
+  node: string;
+  checks: string[];
+  eligible: boolean;
+  next: string[];
+}
+
+export function repairId(check: Check): string {
+  if (check.id.startsWith('tool:docker-')) return 'docker';
+  if (check.id.startsWith('tool:github-auth')) return 'login:github';
+  if (['dependencies', 'auth:toolchain'].includes(check.id)) return 'workspace';
+  if (check.id.startsWith('tool:')) return 'workspace';
+  if (check.id.startsWith('workstation:')) return 'workstation';
+  if (
+    check.id.startsWith('auth:') &&
+    !['auth:vscode', 'auth:workstation'].includes(check.id)
+  )
+    return `login:${check.id.slice(5)}`;
+  if (check.id === 't3:settings' || check.id === 't3:api') return 't3';
+  return 'operator';
+}
+
+/** Every nonpassing check is accounted for; unknown checks remain operator work. */
+export function repairPlan(
+  reports: NodeReport[],
+  targets: RepairTarget[]
+): RepairStep[] {
+  const steps: RepairStep[] = [];
+  for (const report of reports) {
+    const groups = new Map<string, Check[]>();
+    for (const check of report.checks.filter(
+      (entry) => entry.status !== 'pass'
+    )) {
+      const repair = recipe(repairId(check)).id;
+      groups.set(repair, [...(groups.get(repair) ?? []), check]);
+    }
+    for (const [id, checks] of groups)
+      steps.push({
+        ...recipe(id),
+        node: report.node,
+        eligible:
+          targets.some((target) => target.name === report.node) &&
+          report.snapshot !== undefined,
+        checks: checks.map((check) => check.id),
+        next: [
+          ...new Set(
+            checks.flatMap((check) =>
+              check.remedy ? [check.remedy.action] : [check.summary]
+            )
+          ),
+        ],
+      });
+  }
+  return steps;
+}
+
+/** Prerequisite owners always run first, independent of check or selector order. */
+export function automaticRepairs(
+  steps: RepairStep[],
+  node: string
+): RepairStep[] {
+  return AUTOMATED_REPAIRS.flatMap((id) =>
+    steps.filter(
+      (step) =>
+        step.node === node && step.id === id && step.automatic && step.eligible
+    )
+  );
+}

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.`,
+    },
+  ];
+}