@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/src/cli/fleet-sync.ts

@@ -0,0 +1,375 @@
+import { localCheckoutRevision } from '../machine/local-source';
+import {
+  definitionSource,
+  fleet as canonicalDefinition,
+  reloadFleet,
+} from '../fleet-config';
+import { managerFailure } from '../manager-failure';
+import { managerText, stdoutColor } from './fleet-sync-output';
+import { managerSchedule, type ScheduleAction } from './fleet-sync-schedule';
+import { enrollManager } from './fleet-sync-enrollment';
+import { authorizeManager } from './fleet-sync-vault';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, renameSync } from 'node:fs';
+import {
+  isRevision,
+  withMachineLock,
+  ensurePrivateRoot,
+  type Enrollment,
+} from '../machine/state';
+import { loadEnrollment } from '../state/enrollment';
+import { legacyHome } from '../state/paths';
+import {
+  DIVERGED_REMEDY,
+  refresh,
+  stateContext,
+  type Standing,
+} from '../state/sync';
+import { runRecord } from './fleet-sync-state';
+import { runCommand } from '../runner';
+import type { Runner } from '../types';
+import type { Settings } from './settings';
+import type { CommandOutcome } from './contracts';
+import { FleetUsageError } from '../errors';
+import { FleetLockError } from '../machine/lock-error';
+import { selected } from './fleet-sync-remote';
+import { managerIdentity } from './fleet-sync-manager';
+import { managerRunScript, rehome } from './fleet-sync-checkout';
+import { packageInfo } from '../package-info';
+import {
+  forwardingDisabled,
+  forwardToManager,
+  type ForwardSpawn,
+} from './fleet-sync-forward';
+
+export interface FleetSyncOptions {
+  revision?: string;
+  dryRun?: boolean;
+  apply?: boolean;
+  yes?: boolean;
+  json?: boolean;
+  nonInteractive?: boolean;
+  node?: string[];
+  all?: boolean;
+  schedule?: ScheduleAction;
+  /** Internal: this revision already converged the whole fleet, so no canary
+   * has to prove it first and every worker converges at once.
+   */
+  rolledOut?: boolean;
+  /** Internal: set for interactive terminal runs (sudo enrollment prompts). */
+  interactiveAuthorization?: boolean;
+  expectedPlanFingerprint?: string;
+}
+export function machineRoot(): string {
+  const root = join(homedir(), '.local/share/personal/fleet/manager');
+  // One-time move from the pre-topology name; keeps the approved revision.
+  const legacy = join(homedir(), '.local/share/personal/fleet/controller');
+  if (!existsSync(root) && existsSync(legacy)) renameSync(legacy, root);
+  return root;
+}
+
+/** Public contract v3: the manager converges itself, then every enrolled worker. */
+export async function fleetSync(
+  options: FleetSyncOptions,
+  settings: Settings,
+  run: Runner = runCommand,
+  forward?: ForwardSpawn
+): Promise<CommandOutcome> {
+  validate(options);
+  if (!(await onManager(run)))
+    return offManager(options, settings, run, forward);
+  if (options.schedule === 'status') return scheduleStatus(settings, run);
+  return managerSync(options, settings, {
+    run,
+    root: machineRoot(),
+    restart: () => fleetSync(options, settings, run, forward),
+  });
+}
+
+export interface ManagerSync {
+  run: Runner;
+  /** This machine's run lock and caches. */
+  root: string;
+  /** Starts the request over once the fleet state has been replaced. */
+  restart: () => Promise<CommandOutcome>;
+}
+
+/** fleet-sync on the machine already known to be the manager. */
+export async function managerSync(
+  options: FleetSyncOptions,
+  settings: Settings,
+  { run, root, restart }: ManagerSync
+): Promise<CommandOutcome> {
+  await ensurePrivateRoot(root);
+  const state = await loadEnrollment(legacyHome() ? root : null);
+  const revision = await selectedRevision(
+    options.revision,
+    state?.approvedRevision,
+    settings,
+    run
+  );
+  if (!isRevision(revision))
+    return actionRequired(
+      'FLEET_REVISION_REQUIRED',
+      'No revision to converge to. Run the published dev-fleet package (it names the commit it was built from), or select a full commit SHA with --revision.'
+    );
+  if (options.schedule)
+    return scheduleRequest(options, revision, settings, run);
+  const rehomed = await rehome(
+    options,
+    { revision, workspace: settings.workspace, root },
+    run
+  );
+  if (rehomed === 'unavailable')
+    return actionRequired(
+      'FLEET_SOURCE_UNAVAILABLE',
+      `Revision ${revision} could not be taken from ${canonicalDefinition.source.repository}, so nothing was changed. Check the network and Git access to it, and that the revision is pushed there; fleet-sync never converges from the package or working tree it was started in.`,
+      revision
+    );
+  if (rehomed !== 'here') return rehomed;
+  if (options.dryRun) return selected({ ...options, revision }, settings, run);
+  // The bucket is the source of truth: a run starts from its version of the
+  // configuration, the roster and the approval, not from a stale local copy.
+  const fresh = await refresh(stateContext(run));
+  if (fresh.standing === 'diverged')
+    return actionRequired('FLEET_STATE_DIVERGED', DIVERGED_REMEDY, revision);
+  if (fresh.replaced) {
+    // Everything read so far came from the stale copy, the manager's own
+    // identity included.
+    reloadFleet();
+    return restart();
+  }
+  return authorizeAndApply(root, state, options, {
+    settings,
+    run,
+    revision,
+    standing: fresh.standing,
+  });
+}
+
+interface ApplyContext {
+  settings: Settings;
+  run: Runner;
+  revision: string;
+  /** How the fleet state stood with the bucket when this run started. */
+  standing: Standing;
+}
+
+/** Applies without a confirmation prompt; --dry-run is the preview. */
+async function authorizeAndApply(
+  root: string,
+  state: Enrollment | null,
+  options: FleetSyncOptions,
+  context: ApplyContext
+): Promise<CommandOutcome> {
+  const { settings, run, revision } = context;
+  const request = { ...options, revision, apply: true, yes: true };
+  if (!interactive(options)) return applyLocked(root, state, request, context);
+  await enrollManager(settings.config, run);
+  // Needed to hand each node its own Vault token; nodes report any gap.
+  await authorizeManager({ interactive: true }, run);
+  return applyLocked(
+    root,
+    state,
+    { ...request, interactiveAuthorization: true },
+    context
+  );
+}
+
+/** Records the approved revision, converges, records what was applied, then
+ * uploads the fleet state: the report says whether the bucket holds it.
+ */
+function applyLocked(
+  root: string,
+  state: Enrollment | null,
+  request: FleetSyncOptions & { revision: string },
+  context: ApplyContext
+): Promise<CommandOutcome> {
+  const { settings, run, revision } = context;
+  const record = runRecord(state, revision, {
+    context: stateContext(run),
+    standing: context.standing,
+    ...(definitionSource().kind === 'file'
+      ? { definition: JSON.stringify(canonicalDefinition, null, 2) + '\n' }
+      : {}),
+  });
+  return withMachineLock(root, async () => {
+    record.approve();
+    try {
+      return await selected(
+        { ...request, rolledOut: state?.appliedRevision === revision },
+        settings,
+        run,
+        (report) => record.settle(report.ok)
+      );
+    } finally {
+      await record.abandon();
+    }
+  }).catch((error: unknown) => {
+    if (error instanceof FleetLockError)
+      return actionRequired(
+        'FLEET_MANAGER_LOCKED',
+        'Another manager run or interrupted lock exists. Inspect manager and remote processes before removing an abandoned sync.lock; never steal active package-manager locks.'
+      );
+    throw error;
+  });
+}
+/** Every run (previews and schedules too) happens on the manager: a worker can
+ * neither converge the manager's singletons nor observe its T3 links, so a
+ * partial run there only produces misleading failures.
+ */
+async function onManager(run: Runner): Promise<boolean> {
+  const { manager } = canonicalDefinition;
+  return (await managerIdentity(manager.id, run)).status === 'pass';
+}
+
+/** Hands the request to the manager; refuses (without touching any worker)
+ * when hand-off is disabled, e.g. on the manager side of a hand-off.
+ */
+async function offManager(
+  options: FleetSyncOptions,
+  settings: Settings,
+  run: Runner,
+  forward: ForwardSpawn | undefined
+): Promise<CommandOutcome> {
+  const definition = canonicalDefinition;
+  const revision =
+    options.revision ??
+    packageRevision() ??
+    (await localCheckoutRevision(settings.workspace, run));
+  if (forwardingDisabled())
+    return actionRequired(
+      'FLEET_NOT_MANAGER',
+      `fleet-sync runs only on the manager (${definition.manager.id}); nothing was changed. Run it there, or from a worker that can SSH to the manager.`,
+      revision ?? null
+    );
+  const runScript = revision
+    ? await managerRunScript(settings.workspace, revision, run)
+    : null;
+  return forwardToManager(definition, options, revision, {
+    spawn: forward,
+    script: runScript,
+  });
+}
+
+function scheduleStatus(
+  settings: Settings,
+  run: Runner
+): Promise<CommandOutcome> {
+  return managerSchedule(
+    {
+      action: 'status',
+      revision: '',
+      config: settings.config,
+      authorized: false,
+    },
+    run
+  );
+}
+
+function actionRequired(
+  code: string,
+  remedy: string,
+  revision: string | null = null
+): CommandOutcome {
+  const report = managerFailure(canonicalDefinition, revision, code, remedy);
+  return {
+    exitCode: 1,
+    data: report,
+    text: managerText(report, { color: stdoutColor() }),
+  };
+}
+
+function validate(options: FleetSyncOptions): void {
+  validateSchedule(options.schedule);
+  if (options.all && options.node?.length)
+    throw new FleetUsageError('Choose --all or --node, not both.');
+  if (options.revision !== undefined && !isRevision(options.revision))
+    throw new FleetUsageError(
+      '--revision requires an exact lowercase 40-character commit SHA.'
+    );
+  if (options.dryRun && (options.apply || options.yes))
+    throw new FleetUsageError(
+      '--dry-run cannot be combined with apply confirmation.'
+    );
+}
+function interactive(options: FleetSyncOptions): boolean {
+  return (
+    ![
+      options.dryRun,
+      options.apply,
+      options.yes,
+      options.json,
+      options.nonInteractive,
+      process.env['CI'],
+    ].some(Boolean) && Boolean(process.stdin.isTTY && process.stderr.isTTY)
+  );
+}
+
+/** The commit an installed package was published from: the version of
+ * dev-fleet you run is the revision the fleet moves to.
+ */
+function packageRevision(): string | undefined {
+  return packageInfo().revision ?? undefined;
+}
+
+async function scheduleRequest(
+  options: FleetSyncOptions,
+  revision: string,
+  settings: Settings,
+  run: Runner
+): Promise<CommandOutcome> {
+  const root = machineRoot();
+
+  if (options.dryRun)
+    return actionRequired(
+      'FLEET_SCHEDULE_PREVIEW',
+      'No schedule changed. Inspect --schedule status; scheduling writes require --apply --yes.'
+    );
+  if (!options.apply || !options.yes)
+    return managerSchedule(
+      {
+        action: options.schedule!,
+        revision,
+        config: settings.config,
+        authorized: false,
+      },
+      run
+    );
+  return withMachineLock(root, () =>
+    managerSchedule(
+      {
+        action: options.schedule!,
+        revision,
+        config: settings.config,
+        authorized: Boolean(options.apply && options.yes),
+      },
+      run
+    )
+  );
+}
+
+function validateSchedule(schedule: unknown): void {
+  if (
+    schedule !== undefined &&
+    !['enable', 'pause', 'resume', 'disable', 'status'].includes(
+      String(schedule)
+    )
+  )
+    throw new FleetUsageError('Unknown manager schedule action.');
+}
+
+async function selectedRevision(
+  explicit: string | undefined,
+  approved: string | undefined,
+  settings: Settings,
+  run: Runner
+): Promise<string | undefined> {
+  return (
+    explicit ??
+    packageRevision() ??
+    (await localCheckoutRevision(settings.workspace, run)) ??
+    approved
+  );
+}

package/src/cli/fleet.ts

@@ -0,0 +1,165 @@
+import { selectNodes } from '../config';
+import { doctor } from '../manager';
+import { FleetUsageError } from '../errors';
+import { onboarding } from '../onboard';
+import { makeReport, renderReport, reportExitCode } from '../report';
+import { runCommand } from '../runner';
+import schema from '../../schema/roster.schema.json';
+import type { FleetConfig, FleetNode, NodeReport, Runner } from '../types';
+import type { CommandOutcome } from './contracts';
+import type { Settings } from './settings';
+import { capabilities, timeout, validateOptions } from './options';
+import type { CliOptions } from './options';
+import { addNode, nodeFromOptions, readRoster } from './roster';
+import { executeTailnet } from './tailnet';
+import { probeSource } from './probe-source';
+import { executeRepairCommand } from './repair';
+
+export interface FleetServices {
+  run: Runner;
+  source: () => Promise<string>;
+}
+
+const SERVICES: FleetServices = { run: runCommand, source: probeSource };
+
+export async function executeFleet(
+  command: string,
+  options: CliOptions,
+  settings: Settings,
+  services: FleetServices = SERVICES
+): Promise<CommandOutcome> {
+  validateOptions(command, options);
+  if (['repair', 'repairs'].includes(command))
+    return executeRepairCommand(command, options, settings, services);
+  if (['discover', 'health'].includes(command))
+    return executeTailnet(command, options, settings, services);
+  if (command === 'schema') return result(schema);
+  if (command === 'add') return register(settings, options);
+  const roster = options.local ? null : await readRoster(settings.config);
+  const nodes = resolveNodes(command, options, roster);
+  if (['nodes', 'onboard'].includes(command))
+    return rosterResult(command, nodes, roster !== null);
+  return diagnose(
+    nodes,
+    options,
+    { ...settings, missingRoster: !roster },
+    services
+  );
+}
+
+function rosterResult(
+  command: string,
+  nodes: FleetNode[],
+  configured: boolean
+): CommandOutcome {
+  return result({
+    version: 1,
+    command,
+    ok: true,
+    ...(command === 'nodes' ? { configured } : {}),
+    nodes:
+      command === 'onboard'
+        ? nodes.map((node) => onboarding(node, 'devfleet'))
+        : nodes,
+  });
+}
+
+function resolveNodes(
+  command: string,
+  options: CliOptions,
+  roster: FleetConfig | null
+): FleetNode[] {
+  if (!roster && !options.local && !['doctor', 'nodes'].includes(command))
+    throw new FleetUsageError(
+      'No fleet roster. Use fleet-node-add or the interactive Register action; use fleet-status --local for this machine.'
+    );
+  if (options.node?.length && !roster)
+    throw new FleetUsageError(
+      'Cannot select nodes without a roster. Use fleet-node-add first.'
+    );
+  return roster ? selectNodes(roster, options.node ?? []) : [];
+}
+
+function result(data: unknown, text?: string): CommandOutcome {
+  return { exitCode: 0, data, ...(text ? { text } : {}) };
+}
+
+async function register(
+  settings: Settings,
+  options: CliOptions
+): Promise<CommandOutcome> {
+  const node = nodeFromOptions(options);
+  const added = await addNode(settings.config, node, options.apply === true);
+  return result({
+    version: 1,
+    command: 'add',
+    ok: true,
+    applied: options.apply === true,
+    path: settings.config,
+    // How the fleet state stands with the bucket after this change.
+    ...(added.standing ? { state: added.standing } : {}),
+    node,
+    nodes: added.roster.nodes,
+    next: options.apply
+      ? 'Run fleet-nodes --onboard, then fleet-status --json.'
+      : 'Review this preview, then repeat with --apply --yes.',
+  });
+}
+
+async function diagnose(
+  nodes: FleetNode[],
+  options: CliOptions,
+  settings: Settings & { missingRoster: boolean },
+  services: FleetServices
+): Promise<CommandOutcome> {
+  const source = nodes.length ? await services.source() : undefined;
+  const reports = await doctor(
+    nodes,
+    {
+      root: settings.workspace,
+      local: options.local === true,
+      required: capabilities(options.require),
+      timeoutMs: timeout(options),
+      ...(source ? { source } : {}),
+    },
+    services.run
+  );
+  if (!options.local && settings.missingRoster) reports.push(missingRoster());
+  const report = {
+    ...makeReport('doctor', reports),
+    coverage: {
+      scope: options.local
+        ? 'local'
+        : options.node?.length
+          ? 'selected'
+          : 'all-configured',
+      manager: true,
+      configuredNodesTested: nodes.map((node) => node.id),
+      rosterAvailable: !settings.missingRoster,
+      note: 'Directed SSH checks from this manager only. T3 relay/peer and VS Code forwarding require operator tests.',
+    },
+  };
+  return {
+    exitCode: reportExitCode(report, options.strict === true),
+    data: report,
+    text: renderReport(report),
+  };
+}
+
+function missingRoster(): NodeReport {
+  return {
+    node: 'fleet',
+    checks: [
+      {
+        id: 'fleet:roster',
+        status: 'fail',
+        summary:
+          'No developer fleet roster is configured. Only this manager could be checked; fleet-wide health is unknown.',
+        remedy: {
+          action:
+            'Open personal --interactive and choose Register a developer computer, or run devfleet fleet-node-add --help. Then run fleet-status --json.',
+        },
+      },
+    ],
+  };
+}