@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/src/proxy-converge.ts

@@ -0,0 +1,85 @@
+import { record } from './config';
+import { configPath } from './fleet-config';
+import type { Check, Runner } from './types';
+
+/** The proxy runs only on the manager, which performs singleton/state/provenance
+ * checks before starting a stopped install; on a worker this verifies the
+ * client-only role. Routine sync cannot upgrade or restore it.
+ */
+export async function convergeProxy(
+  node: string,
+  revision: string,
+  run: Runner,
+  options: { apply?: boolean; cwd?: string } = {}
+): Promise<Check[]> {
+  const result = await run(
+    [
+      'python3',
+      '-B',
+      'cliproxy/scripts/fleet_sync.py',
+      '--definition',
+      configPath(),
+      '--node',
+      node,
+      '--revision',
+      revision,
+      ...(options.apply === false ? [] : ['--apply']),
+    ],
+    {
+      timeoutMs: 180_000,
+      ...(options.cwd ? { cwd: options.cwd } : {}),
+    }
+  );
+  try {
+    const data: unknown = JSON.parse(result.stdout);
+    if (
+      !record(data) ||
+      data['version'] !== 1 ||
+      !Array.isArray(data['phases']) ||
+      !data['phases'].length
+    )
+      throw new Error();
+    return data['phases'].map((phase): Check => {
+      if (
+        !record(phase) ||
+        typeof phase['code'] !== 'string' ||
+        !/^PROXY_[A-Z0-9_]+$/.test(phase['code'])
+      )
+        throw new Error();
+      return {
+        id: `proxy:${phase['code'].slice(6).toLowerCase().replaceAll('_', '-')}`,
+        status: phase['status'] === 'unchanged' ? 'pass' : 'fail',
+        summary: phase['code'],
+        remedy: { action: phaseAction(phase['remedy']) },
+      };
+    });
+  } catch {
+    return [
+      {
+        id: 'proxy:configuration',
+        status: 'fail',
+        summary: 'PROXY_RECONCILE_UNVERIFIED',
+        remedy: {
+          action:
+            'Inspect the CLIProxyAPI install on the manager and its deployment manifest; runtime data and credentials were not copied.',
+        },
+      },
+    ];
+  }
+}
+
+const GENERIC_ACTION =
+  'The proxy runs only on the manager. Inspect it there with its audit/recovery runbook; missing state requires fencing and encrypted recovery, never a second identity.';
+
+/** The proxy's own remedies are authored text from tracked source (never
+ * subprocess output); anything else falls back to the generic runbook.
+ */
+function phaseAction(remedy: unknown): string {
+  const action = record(remedy) ? remedy['action'] : undefined;
+  return typeof action === 'string' &&
+    action.length > 0 &&
+    action.length <= 400 &&
+    !/[\u0000-\u001f]/.test(action)
+    ? action
+    : GENERIC_ACTION;
+}

package/src/remote-bootstrap.ts

@@ -0,0 +1,210 @@
+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 { installedDefinition, 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: installedDefinition(options.definition) }
+    : payload;
+}
+
+/** 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] };
+  const transfer = cached
+    ? { mode: 'cached', bundle: '' }
+    : { mode: 'transfer', bundle: 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: bootstrapInput(payload.config, transfer.bundle),
+    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.',
+        },
+      },
+    ],
+  };
+}
+
+/** What the bootstrap reads on stdin: one line with the fleet configuration
+ * (installed under the remote lock, so overlapping runs never both write it),
+ * then the bundle when the worker lacks the revision.
+ */
+export function bootstrapInput(
+  config: string | undefined,
+  bundle: string
+): string {
+  const line = config ? Buffer.from(config).toString('base64') : '';
+  return `${line}\n${bundle}`;
+}
+
+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 of dev-fleet (refused for an installed package, which is not one). 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
+    )
+  );
+}