@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/src/cli/register-fleet.ts

@@ -0,0 +1,246 @@
+import type { Command } from 'commander';
+import type { CliOptions } from './options';
+import type { CommandOutcome } from './contracts';
+import type { Settings } from './settings';
+import { resolveSettings } from './settings';
+import { executeFleet } from './fleet';
+import { fleetSync, type FleetSyncOptions } from './fleet-sync';
+import { syncNode, type NodeSyncOptions } from './node-sync';
+
+type Complete = (outcome: CommandOutcome) => void;
+
+interface Registration {
+  program: Command;
+  defaults: Settings;
+  complete: Complete;
+}
+
+function collect(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
+
+function targetOptions(command: Command): Command {
+  return command
+    .option('--node <id>', 'Select a registered node; repeatable', collect, [])
+    .option('--local', 'This manager only; no roster or SSH required')
+    .option('--timeout <ms>', 'Per-node deadline, 1000–1800000 milliseconds');
+}
+
+function withSettings(defaults: Settings, options: CliOptions) {
+  return resolveSettings({
+    ...defaults,
+    ...(options.workspace ? { workspace: options.workspace } : {}),
+    ...(options.config ? { config: options.config } : {}),
+  });
+}
+
+/** Internal fleet actions are selected by flags; the public surface stays flat. */
+function fleetAction(name: string, options: CliOptions): string {
+  if (name === 'fleet-status')
+    return options.tailnet || options.workers ? 'health' : 'doctor';
+  if (name === 'fleet-repair') return options.list ? 'repairs' : 'repair';
+  if (name === 'fleet-nodes')
+    return options.onboard ? 'onboard' : options.schema ? 'schema' : 'nodes';
+  if (name === 'fleet-node-add') return 'add';
+  return 'discover';
+}
+
+function register(
+  { program, defaults, complete }: Registration,
+  name: string,
+  description: string
+): Command {
+  return program
+    .command(name)
+    .description(description)
+    .action(async (_options, command: Command) => {
+      const options = command.optsWithGlobals<CliOptions>();
+      const settings = await withSettings(defaults, options);
+      complete(
+        await executeFleet(
+          fleetAction(name, options),
+          { ...options, ...(options.workers ? { managed: true } : {}) },
+          settings
+        )
+      );
+    });
+}
+
+function registerStatus(registration: Registration) {
+  targetOptions(
+    register(
+      registration,
+      'fleet-status',
+      'Check this computer and registered nodes without changing them'
+    )
+  )
+    .option('--all', 'Explicit spelling of the default roster scope')
+    .option(
+      '--tailnet',
+      'Check every visible Tailscale computer instead of the roster'
+    )
+    .option(
+      '--workers',
+      'Audit the canonical worker fleet against the published reference'
+    )
+    .option(
+      '--require <capabilities>',
+      'Manager capabilities, comma separated, or none'
+    )
+    .option('--strict', 'Warnings and skipped checks also produce exit 1')
+    .addHelpText(
+      'after',
+      '\nRead-only. --local, --node and --all select roster scope; --tailnet and --workers check Tailscale computers and never take a roster scope.'
+    );
+}
+
+function registerRepair(registration: Registration) {
+  targetOptions(
+    register(
+      registration,
+      'fleet-repair',
+      'Preview owner-managed repairs; --apply --yes executes them'
+    )
+  )
+    .option('--list', 'Print the static repair and login catalog instead')
+    .option('--all', 'Every visible Tailscale computer (default)')
+    .option(
+      '--require <capabilities>',
+      'Local only: manager capabilities, comma separated, or none'
+    )
+    .option(
+      '--repair <ids>',
+      'workspace,workstation,providers; comma separated'
+    )
+    .option(
+      '--plan-hash <sha256>',
+      'Require the reviewed plan to match current diagnostics'
+    )
+    .option(
+      '--script',
+      'Generate a reviewable POSIX script without executing it'
+    )
+    .option('--strict', 'Warnings and skipped checks also produce exit 1')
+    .option('--apply', 'Authorize the displayed repair plan; requires --yes')
+    .option('--yes', 'Confirm an explicitly requested --apply operation')
+    .addHelpText(
+      'after',
+      '\nExample: devfleet fleet-repair --local --repair workspace --plan-hash REVIEWED_SHA256 --apply --yes --json'
+    );
+}
+
+function registerNodes(registration: Registration) {
+  register(
+    registration,
+    'fleet-nodes',
+    'List registered developer computers; --onboard and --schema add guidance'
+  )
+    .option('--node <id>', 'Select a registered node; repeatable', collect, [])
+    .option(
+      '--onboard',
+      'Per-node SSH, VS Code and authentication instructions'
+    )
+    .option('--schema', 'Print the versioned roster JSON schema');
+  register(
+    registration,
+    'fleet-node-add',
+    'Register an existing computer in the local roster; writes need --apply --yes'
+  )
+    .requiredOption('--id <name>', 'Unique lowercase node ID')
+    .requiredOption(
+      '--ssh <alias>',
+      'Existing OpenSSH alias; never writes SSH configuration'
+    )
+    .requiredOption('--path <path>', 'Absolute POSIX checkout path on the node')
+    .option(
+      '--runtime <path>',
+      'Optional absolute Node/Bun runtime; defaults to node on SSH PATH'
+    )
+    .option(
+      '--require <capabilities>',
+      'Required capabilities, comma separated, or none'
+    )
+    .option('--apply', 'Write the roster; requires --yes')
+    .option('--yes', 'Confirm an explicitly requested --apply operation');
+}
+
+function registerSync({ program, defaults, complete }: Registration) {
+  program
+    .command('fleet-sync')
+    .description(
+      'Synchronize the enrolled Ubuntu fleet from this manager over verified SSH'
+    )
+    .option(
+      '--revision <sha>',
+      'Approve an exact source commit; defaults to published release or current canonical checkout'
+    )
+    .option(
+      '--node <id>',
+      'Explicit enrolled remote target; repeatable',
+      collect,
+      []
+    )
+    .option(
+      '--all',
+      'Explicit spelling of the default enrolled fleet scope; never discovered peers'
+    )
+    .option(
+      '--dry-run',
+      'Read-only plan; no authentication, enrollment, installation or scheduling'
+    )
+    .option(
+      '--apply',
+      'Accepted for compatibility; fleet-sync applies by default (schedule writes still need --apply --yes)'
+    )
+    .option('--yes', 'Accepted for compatibility with --apply')
+    .option(
+      '--schedule <action>',
+      'Manager-only schedule: enable, pause, resume, disable, status'
+    )
+    .action(async (_options, command: Command) => {
+      const options = command.optsWithGlobals<
+        FleetSyncOptions & Partial<Settings>
+      >();
+      complete(
+        await fleetSync(options, {
+          ...defaults,
+          ...(options.config ? { config: options.config } : {}),
+        })
+      );
+    });
+  program
+    .command('fleet-node-sync')
+    .description(
+      'Reconcile this node’s locked tools, launcher, Codex proxy profile and T3 instances; applies by default'
+    )
+    .option(
+      '--id <name>',
+      'Stable node name; defaults to this machine hostname'
+    )
+    .option('--revision <sha>', 'Reviewed commit; defaults to checkout HEAD')
+    .option('--dry-run', 'Preview without changing this node')
+    .option('--t3-home <path>', 'T3 base directory')
+    .action(async (_options, command: Command) => {
+      const options = command.optsWithGlobals<
+        NodeSyncOptions & Partial<Settings>
+      >();
+      complete(await syncNode(options, await withSettings(defaults, options)));
+    });
+}
+
+export function registerFleet(
+  program: Command,
+  defaults: Settings,
+  complete: Complete
+): void {
+  const registration = { program, defaults, complete };
+  registerStatus(registration);
+  register(
+    registration,
+    'fleet-discover',
+    'List computers visible through Tailscale, including offline devices'
+  );
+  registerSync(registration);
+  registerRepair(registration);
+  registerNodes(registration);
+}

package/src/cli/registry.ts

@@ -0,0 +1,158 @@
+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; interactive confirmation or --apply --yes. Readiness is verified separately.',
+      ['ubuntu', 'enrollment', 'converge', 'sync'],
+      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 } : {}),
+  };
+}