@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/src/cli/registry.ts

@@ -0,0 +1,185 @@
+import { SOURCE_OPERATIONS } from './source-operations';
+import type { CommandSpec } from './contracts';
+import { searchCommands } from './search';
+
+type Entry = [
+  id: string,
+  title: string,
+  description: string,
+  keywords: string[],
+  mutation?: boolean,
+];
+
+function group(name: string, entries: Entry[]): CommandSpec[] {
+  return entries.map(([id, title, description, keywords, mutation]) => ({
+    id,
+    title,
+    description,
+    group: name,
+    keywords,
+    args: id.split(' '),
+    examples: [`devfleet ${id} --json`],
+    mutation: mutation === true,
+  }));
+}
+
+/** One flat, prefixed command surface shared by help, the palette and agents. */
+export const COMMANDS: CommandSpec[] = [
+  ...group('Fleet', [
+    [
+      'fleet-status',
+      'Check this computer and registered nodes',
+      'Read-only SSH, authentication, T3, VS Code and dependency checks for this manager and every roster node. --tailnet covers every visible Tailscale computer; --workers audits the canonical worker fleet.',
+      ['health', 'doctor', 'ssh', 'auth', 'github', 'vscode', 't3', 'diagnose'],
+    ],
+    [
+      'fleet-status --local',
+      'Check this computer only',
+      'Diagnose this process context without a roster or remote connections.',
+      ['local', 'manager', 'health'],
+    ],
+    [
+      'fleet-status --tailnet',
+      'Check all Tailscale computers',
+      'Discover every visible non-mobile Tailscale computer, then test reachability, pinned tools, configuration and service logins. Offline, unregistered and unverified computers fail coverage.',
+      ['tailscale', 'tailnet', 'all', 'versions', 'codex', 'claude', 'login'],
+    ],
+    [
+      'fleet-status --workers',
+      'Check the canonical worker fleet',
+      'Read-only canonical worker readiness, dependencies, services and authentication; lists every remaining gap.',
+      ['workers', 'readiness', 'health', 'canonical'],
+    ],
+    [
+      'fleet-discover',
+      'Discover Tailscale computers',
+      'List all computers visible to this Tailscale account, including offline devices. Excludes iOS, Android and tvOS; never writes a roster.',
+      ['tailscale', 'tailnet', 'computers', 'machines'],
+    ],
+    [
+      'fleet-sync',
+      'Synchronize the enrolled Ubuntu fleet',
+      'Manager push to all enrolled Ubuntu nodes at one approved revision over verified SSH: the commit the dev-fleet package was published from, with the fleet.json of the project it is run from. Interactive confirmation or --apply --yes. Readiness is verified separately.',
+      ['ubuntu', 'enrollment', 'converge', 'sync'],
+      true,
+    ],
+    [
+      'fleet-state',
+      'Check the fleet state and its bucket',
+      'Read-only: where the fleet configuration, the roster and the approved revision are kept on this manager, and whether the bucket holds the same version. --example prints a fleet.json to start a project from; --export prints the configuration fleet-sync last applied; --import PATH stores one.',
+      ['state', 'bucket', 's3', 'backup', 'litestream', 'configuration'],
+    ],
+    [
+      'fleet-state --init',
+      'Connect the bucket and restore or seed the fleet state',
+      'Restore the fleet state from the bucket fleet.json names under "state" (or the one given with --bucket/--endpoint or --directory), or seed an empty bucket from this machine, and save the bucket and its credentials on this machine for runs it starts by itself. Credentials come from the environment or a terminal prompt.',
+      ['state', 'bucket', 's3', 'setup', 'restore', 'new manager'],
+      true,
+    ],
+    [
+      'fleet-state --push',
+      'Upload fleet state changes to the bucket',
+      'Upload changes this manager made while the bucket was unreachable. Refuses when the bucket has changed since.',
+      ['state', 'bucket', 'upload', 'replicate'],
+      true,
+    ],
+    [
+      'fleet-state --restore',
+      'Replace the local fleet state with the bucket’s',
+      'Discard this manager’s copy of the fleet state and download the bucket’s version. Needs --yes when this machine has changes the bucket does not hold.',
+      ['state', 'bucket', 'restore', 'recover', 'disposable'],
+      true,
+    ],
+    [
+      'fleet-node-sync',
+      'Sync this node',
+      'Reconcile locked tools, the personal launcher, Codex proxy profile and owned T3 instances on this machine. Applies by default; --dry-run previews.',
+      ['node', 'sync', 'proxy', 'tools'],
+      true,
+    ],
+    [
+      'fleet-repair',
+      'Repair tools and configuration',
+      'Inspect visible Tailscale computers and preview owner-managed repairs. --apply --yes executes eligible tools/config repairs and reruns diagnostics. Logins and host trust remain explicit operator steps.',
+      ['fix', 'repair', 'sync', 'setup', 'versions', 'config', 'login'],
+      true,
+    ],
+    [
+      'fleet-repair --list',
+      'Explore repairs and login commands',
+      'List existing tool owners, automated repairs, native per-machine login commands and shared Vault access guidance. No roster or credentials required.',
+      ['fix', 'repair', 'login', 'credentials', 'vault', 'catalog'],
+    ],
+    [
+      'fleet-nodes',
+      'Explore fleet nodes',
+      'List and validate registered developer computers without contacting them. --onboard adds per-node setup instructions; --schema prints the roster JSON schema.',
+      ['roster', 'list', 'machines', 'validate', 'schema'],
+    ],
+    [
+      'fleet-nodes --onboard',
+      'Explore onboarding instructions',
+      'Get per-node SSH templates, VS Code guidance, authentication steps and safe verification commands.',
+      ['setup', 'guide', 'instructions', 'vscode', 'connect'],
+    ],
+    [
+      'fleet-nodes --schema',
+      'Explore the fleet JSON schema',
+      'Read the versioned roster schema for editors and agents.',
+      ['agent', 'config', 'json', 'schema'],
+    ],
+    [
+      'fleet-node-add',
+      'Register a developer computer',
+      'Preview or explicitly save an existing SSH alias, checkout path and per-machine capabilities. No SSH or cloud setup.',
+      ['onboarding', 'register', 'new', 'setup', 'add'],
+      true,
+    ],
+  ]),
+  ...group('T3', [
+    [
+      't3-status',
+      'Check T3 configuration drift',
+      'Compare declared T3 provider instances with the configuration on this machine; exit 1 on drift.',
+      ['t3', 'drift', 'status'],
+    ],
+    [
+      't3-apply',
+      'Reconcile T3 provider instances',
+      'Create and update declared instances and remove previously owned instances absent from the definition. --dry-run plans; --plan-hash rejects stale plans; --import ID adopts an existing instance.',
+      ['t3', 'apply', 'plan', 'import', 'reconcile'],
+      true,
+    ],
+    [
+      't3-cleanup',
+      'Remove owned T3 instances',
+      'Remove only provider instances recorded in personal ownership state. --dry-run previews.',
+      ['t3', 'cleanup', 'remove'],
+      true,
+    ],
+  ]),
+  ...group(
+    'Services',
+    Object.entries(SOURCE_OPERATIONS).map(([id, operation]) => [
+      id,
+      operation.title,
+      `${operation.description} Inspect devfleet ${id} help.`,
+      operation.keywords,
+      operation.mutation,
+    ])
+  ),
+  ...group('Reference', [
+    [
+      'commands',
+      'Explore the command catalog and agent contract',
+      'Search the command index; the JSON document also carries the agent usage/safety contract, release metadata and exit codes.',
+      ['search', 'help', 'llm', 'agent', 'api', 'index'],
+    ],
+  ]),
+];
+
+export function commandCatalog(search = '', group?: string): CommandSpec[] {
+  return searchCommands(COMMANDS, search).filter(
+    (command) => !group || command.group.toLowerCase() === group.toLowerCase()
+  );
+}

package/src/cli/repair-apply.ts

@@ -0,0 +1,67 @@
+import { automaticRepairs } from '../repair-plan';
+import { mapBounded } from '../report';
+import { repairWorkspace } from '../repair-runner';
+import { inspectRemote } from '../transport';
+import { timeout } from './options';
+import type { AutomatedRepair } from '../repair-catalog';
+import type { RepairTarget, RepairStep } from '../repair-plan';
+import type { NodeReport } from '../types';
+import type { CliOptions } from './options';
+import type { FleetServices } from './fleet';
+
+export async function applyRepairs(
+  targets: RepairTarget[],
+  steps: RepairStep[],
+  options: CliOptions,
+  services: FleetServices
+): Promise<NodeReport[]> {
+  let source: Promise<string> | undefined;
+  return mapBounded(
+    targets,
+    async (target) => {
+      const actions = automaticRepairs(steps, target.name);
+      const checks: NodeReport['checks'] = [];
+      for (const step of actions) {
+        try {
+          if (!target.fingerprint)
+            throw new Error('No verified checkout fingerprint');
+          const repairs = [step.id as AutomatedRepair];
+          const result = target.node
+            ? (
+                await inspectRemote(
+                  target.node,
+                  {
+                    action: 'repair',
+                    repairs,
+                    expected: target.fingerprint,
+                    source: await (source ??= Promise.resolve().then(
+                      services.source
+                    )),
+                    timeoutMs: timeout(options),
+                  },
+                  services.run
+                )
+              ).checks
+            : await repairWorkspace(
+                target.root,
+                repairs,
+                services.run,
+                target.fingerprint
+              );
+          checks.push(...result);
+          if (result.some((check) => check.status !== 'pass')) break;
+        } catch {
+          checks.push({
+            id: 'repair:operation',
+            status: 'fail',
+            summary:
+              'Repair could not be prepared or completed. Later actions on this computer were stopped; inspect partial changes locally. Raw errors are withheld.',
+          });
+          break;
+        }
+      }
+      return { node: target.name, checks };
+    },
+    1
+  );
+}

package/src/cli/repair-guard.ts

@@ -0,0 +1,11 @@
+import { createHash } from 'node:crypto';
+import type { RepairStep, RepairTarget } from '../repair-plan';
+
+export function repairPlanHash(
+  steps: RepairStep[],
+  targets: RepairTarget[]
+): string {
+  return createHash('sha256')
+    .update(JSON.stringify({ steps, targets }))
+    .digest('hex');
+}

package/src/cli/repair-inspect.ts

@@ -0,0 +1,150 @@
+import { selectNodes } from '../config';
+import { probe } from '../probe';
+import { mapBounded } from '../report';
+import { discoverTailnet } from '../tailscale';
+import {
+  HEALTH_CAPABILITIES,
+  tailnetHealth,
+  uniqueMapping,
+} from '../tailnet-health';
+import { matchComputers } from '../tailnet-matching';
+import { inspectRemote } from '../transport';
+import { FleetUsageError } from '../errors';
+import { readRoster } from './roster';
+import { capabilities, timeout } from './options';
+import type { NodeReport, FleetConfig } from '../types';
+import type { RepairTarget } from '../repair-plan';
+import type { FleetServices } from './fleet';
+import type { CliOptions } from './options';
+import type { Settings } from './settings';
+
+export interface RepairInspection {
+  reports: NodeReport[];
+  targets: RepairTarget[];
+  coverage: { scope: string; limitation: string };
+}
+export async function inspectRepair(
+  options: CliOptions,
+  settings: Settings,
+  services: FleetServices
+): Promise<RepairInspection> {
+  if (options.local) return inspectLocal(settings, services, options);
+  const roster = await readRoster(settings.config);
+  if (options.node?.length) return inspectSelected(options, roster, services);
+  return inspectTailnet(options, settings, roster, services);
+}
+
+async function inspectLocal(
+  settings: Settings,
+  services: FleetServices,
+  options: CliOptions
+): Promise<RepairInspection> {
+  const snapshot = await probe(
+    settings.workspace,
+    options.require === undefined
+      ? HEALTH_CAPABILITIES
+      : capabilities(options.require),
+    services.run
+  );
+  return {
+    reports: [{ node: 'local', snapshot, checks: snapshot.checks }],
+    targets: [
+      {
+        name: 'local',
+        root: settings.workspace,
+        fingerprint: snapshot.fingerprint,
+      },
+    ],
+    coverage: {
+      scope: 'local',
+      limitation: 'Only this process context was tested.',
+    },
+  };
+}
+
+async function inspectSelected(
+  options: CliOptions,
+  roster: FleetConfig | null,
+  services: FleetServices
+): Promise<RepairInspection> {
+  if (!roster)
+    throw new FleetUsageError(
+      'Register real SSH aliases and checkout paths before selecting remote repairs.'
+    );
+  const nodes = selectNodes(roster, options.node ?? []);
+  const source = await services.source();
+  const reports = await mapBounded(nodes, (node) =>
+    inspectRemote(
+      node,
+      { action: 'probe', source, timeoutMs: timeout(options) },
+      services.run
+    )
+  );
+  return {
+    reports,
+    targets: nodes.map((node) =>
+      attachFingerprint({ name: node.id, root: node.workspace, node }, reports)
+    ),
+    coverage: {
+      scope: 'selected',
+      limitation:
+        'Only selected roster computers were tested; other devices are unverified.',
+    },
+  };
+}
+
+async function inspectTailnet(
+  options: CliOptions,
+  settings: Settings,
+  roster: FleetConfig | null,
+  services: FleetServices
+): Promise<RepairInspection> {
+  const tailnet = await discoverTailnet(services.run);
+  const reports = await tailnetHealth(
+    tailnet,
+    roster?.nodes ?? [],
+    {
+      root: settings.workspace,
+      timeoutMs: timeout(options),
+      source: services.source,
+    },
+    services.run
+  );
+  const matches = await matchComputers(
+    roster?.nodes ?? [],
+    tailnet.computers,
+    services.run
+  );
+  const targets: RepairTarget[] = [];
+  for (const peer of tailnet.computers) {
+    if (peer.self) targets.push({ name: peer.dns, root: settings.workspace });
+    else if (peer.online && uniqueMapping(matches.get(peer.id)!, matches)) {
+      const node = matches.get(peer.id)![0]!;
+      targets.push({ name: peer.dns, root: node.workspace, node });
+    }
+  }
+  if (!tailnet.computers.some((peer) => peer.self))
+    targets.push({ name: 'manager', root: settings.workspace });
+  return {
+    reports,
+    targets: targets.map((target) => attachFingerprint(target, reports)),
+    coverage: {
+      scope: 'tailscale-visible-computers',
+      limitation:
+        'Only devices visible to this Tailscale account/ACLs. Offline, unregistered or ambiguous computers cannot be repaired. No credentials, host keys or resources are cloned.',
+    },
+  };
+}
+
+function attachFingerprint(
+  target: RepairTarget,
+  reports: NodeReport[]
+): RepairTarget {
+  const snapshot = reports.find(
+    (report) => report.node === target.name
+  )?.snapshot;
+  return {
+    ...target,
+    ...(snapshot ? { fingerprint: snapshot.fingerprint } : {}),
+  };
+}

package/src/cli/repair-script.ts

@@ -0,0 +1,76 @@
+import { automaticRepairs } from '../repair-plan';
+import { recipe } from '../repair-catalog';
+import { shellQuote, sshArgs } from '../ssh';
+import type { RepairTarget, RepairStep } from '../repair-plan';
+
+export function targetCommand(
+  target: RepairTarget,
+  commands: string[][]
+): string {
+  const command = `cd -- ${shellQuote(target.root)} && ${commands.map((args) => args.map(shellQuote).join(' ')).join(' && ')}`;
+  if (!target.node) return command;
+  return [
+    ...sshArgs(target.node)
+      .map((arg) => (arg === '-T' ? '-t' : arg))
+      .map(shellQuote),
+    shellQuote(command),
+  ].join(' ');
+}
+
+/** Generates a reviewable operator script. It is never written or executed by this command. */
+export function repairScript(
+  steps: RepairStep[],
+  targets: RepairTarget[]
+): string {
+  const lines = [
+    '#!/bin/sh',
+    'set -eu',
+    '# Generated repair plan. Review before running in your own terminal.',
+    '# Automated steps use existing owners. Native login commands below are commented and require operator approval.',
+    '# POSIX shell required; Windows operators can use the personal commands directly.',
+  ];
+  for (const target of targets) {
+    const actions = automaticRepairs(steps, target.name);
+    if (!actions.length) continue;
+    const commands = actions.flatMap((step) =>
+      step.id === 'workspace'
+        ? [
+            [
+              'bun',
+              'src/cli/cli.ts',
+              'fleet-repair',
+              '--local',
+              '--repair',
+              'workspace',
+              '--apply',
+              '--yes',
+              '--json',
+            ],
+          ]
+        : recipe(step.id).commands
+    );
+    lines.push('', targetCommand(target, commands));
+  }
+
+  for (const step of steps.filter(
+    (entry) => !entry.automatic || !entry.eligible
+  )) {
+    lines.push(
+      '',
+      `# ${comment(step.node)} / ${comment(step.title)}`,
+      `# ${comment(step.action)}`
+    );
+    const target = targets.find((entry) => entry.name === step.node);
+    if (target && step.eligible && step.commands.length)
+      lines.push(`# ${targetCommand(target, step.commands)}`);
+    else for (const next of step.next) lines.push(`# ${comment(next)}`);
+  }
+  lines.push(
+    '',
+    '# Re-run devfleet fleet-status --tailnet --json for fresh whole-tailnet coverage.'
+  );
+  return `${lines.join('\n')}\n`;
+}
+function comment(value: string): string {
+  return value.replace(/[\r\n\x00-\x1f\x7f]/g, ' ');
+}