@crvouga/dev-fleet 0.7.0 → 0.8.0

package/src/cli/fleet-validate.ts

@@ -0,0 +1,239 @@
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  DefinitionError,
+  parseDefinition,
+  type DefinitionProblem,
+  type FleetDefinition,
+} from '../definition';
+import { FleetUsageError } from '../errors';
+import { PACKAGE_ROOT } from '../package-info';
+import { ansibleCommand } from '../platform/ansible';
+import { runCommand } from '../runner';
+import type { Check, Runner } from '../types';
+import type { CommandOutcome } from './contracts';
+
+export interface FleetValidateOptions {
+  file?: string;
+  ansible?: boolean;
+  json?: boolean;
+}
+
+export interface FleetValidateServices {
+  run: Runner;
+  env: NodeJS.ProcessEnv;
+  platform: NodeJS.Platform;
+  /** The package's Ansible playbooks, relative to `root`. */
+  root: string;
+}
+
+const SERVICES: FleetValidateServices = {
+  run: runCommand,
+  env: process.env,
+  platform: process.platform,
+  root: PACKAGE_ROOT,
+};
+
+/** The playbooks a definition must be able to drive, in the package. */
+const PLAYBOOK_DIRECTORIES = ['ansible/ubuntu', 'ansible/macos'];
+
+/** The Ansible inventory a definition describes: the manager, and every
+ * worker in the `workers` group in the order it is declared. Host names are
+ * the fleet ids; a machine is reached as fleet-sync reaches it.
+ */
+export function fleetInventory(definition: FleetDefinition): unknown {
+  const workers = Object.fromEntries(
+    definition.workers.map((worker) => [
+      worker.id,
+      {
+        ansible_host: worker.ssh,
+        ...(worker.network
+          ? {
+              ansible_user: worker.network.user,
+              ansible_port: worker.network.sshPort,
+            }
+          : {}),
+      },
+    ])
+  );
+  return {
+    all: {
+      children: {
+        manager: {
+          hosts: {
+            [definition.manager.id]: {
+              ansible_connection: 'local',
+              ansible_user: definition.manager.network.user,
+            },
+          },
+        },
+        workers: { hosts: workers },
+      },
+    },
+  };
+}
+
+/** Reads and judges one fleet.json. Nothing is contacted: with `--ansible`
+ * the pinned Ansible renders the inventory and checks the playbooks' syntax
+ * on this machine.
+ */
+export async function fleetValidate(
+  options: FleetValidateOptions,
+  services: FleetValidateServices = SERVICES
+): Promise<CommandOutcome> {
+  const path = options.file ?? services.env['DEVFLEET_CONFIG'];
+  if (!path)
+    throw new FleetUsageError(
+      'No fleet configuration to validate. Run devfleet from the project that holds your fleet.json, or pass --file PATH.'
+    );
+  let definition: FleetDefinition;
+  try {
+    definition = parseDefinition(await readJson(path));
+  } catch (error) {
+    if (error instanceof DefinitionError) return invalid(path, error.problem);
+    throw error;
+  }
+  const checks: Check[] = [
+    {
+      id: 'definition:schema',
+      status: 'pass',
+      summary: `${path} is a valid fleet definition: a manager and ${definition.workers.length} worker(s).`,
+    },
+  ];
+  if (options.ansible)
+    checks.push(...(await ansibleChecks(definition, services)));
+  const ok = checks.every((check) => check.status !== 'fail');
+  return {
+    exitCode: ok ? 0 : 1,
+    data: { version: 1, command: 'fleet-validate', ok, path, checks },
+    text: checks
+      .map(
+        (check) => `${check.status.toUpperCase()} ${check.id}: ${check.summary}`
+      )
+      .join('\n'),
+  };
+}
+
+async function readJson(path: string): Promise<unknown> {
+  let text: string;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch {
+    throw new DefinitionError({
+      code: 'DEFINITION_UNREADABLE',
+      path: '$',
+      expected: 'a readable file',
+      actual: 'no file',
+    });
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new DefinitionError({
+      code: 'DEFINITION_UNREADABLE',
+      path: '$',
+      expected: 'JSON',
+      actual: 'text that is not JSON',
+    });
+  }
+}
+
+function invalid(path: string, problem: DefinitionProblem): CommandOutcome {
+  const data = {
+    version: 1,
+    command: 'fleet-validate',
+    ok: false,
+    path,
+    problem,
+  };
+  return {
+    exitCode: 1,
+    data,
+    text: `${problem.code} at ${problem.path}: expected ${problem.expected}, found ${problem.actual}.`,
+  };
+}
+
+/** Renders the inventory, lists it with `ansible-inventory` and checks the
+ * syntax of every playbook against it.
+ */
+async function ansibleChecks(
+  definition: FleetDefinition,
+  services: FleetValidateServices
+): Promise<Check[]> {
+  const directory = await mkdtemp(join(tmpdir(), 'devfleet-validate-'));
+  const inventory = join(directory, 'inventory.json');
+  try {
+    await writeFile(inventory, JSON.stringify(fleetInventory(definition)), {
+      mode: 0o600,
+    });
+    const playbook = ansibleCommand(services.platform, services.root);
+    const tool = (name: string) => [...playbook.slice(0, -1), name];
+    const listed = await services.run(
+      [...tool('ansible-inventory'), '-i', inventory, '--list'],
+      { timeoutMs: 120_000 }
+    );
+    const checks: Check[] = [
+      listed.ok
+        ? {
+            id: 'definition:inventory',
+            status: 'pass',
+            summary: 'Ansible reads the inventory the definition describes.',
+          }
+        : {
+            id: 'definition:inventory',
+            status: 'fail',
+            summary: 'DEFINITION_INVENTORY_REJECTED',
+            remedy: {
+              action:
+                'Run devfleet fleet-validate --ansible on the manager after fleet-sync installed the pinned Ansible; report the failure as an issue if it persists.',
+            },
+          },
+    ];
+    const failed: string[] = [];
+    for (const file of await playbooks(services.root)) {
+      const result = await services.run(
+        [
+          ...playbook,
+          '-i',
+          inventory,
+          '--syntax-check',
+          join(services.root, file),
+        ],
+        { timeoutMs: 120_000 }
+      );
+      if (!result.ok) failed.push(file);
+    }
+    checks.push(
+      failed.length
+        ? {
+            id: 'definition:playbooks',
+            status: 'fail',
+            summary: `DEFINITION_PLAYBOOK_SYNTAX: ${failed.join(', ')}`,
+            remedy: {
+              action:
+                'The installed dev-fleet package carries a playbook Ansible cannot parse; report it as an issue.',
+            },
+          }
+        : {
+            id: 'definition:playbooks',
+            status: 'pass',
+            summary: 'Every playbook passes ansible-playbook --syntax-check.',
+          }
+    );
+    return checks;
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+/** Every top-level playbook the fleet applies, sorted. */
+async function playbooks(root: string): Promise<string[]> {
+  const found: string[] = [];
+  for (const directory of PLAYBOOK_DIRECTORIES) {
+    const entries = await readdir(join(root, directory)).catch(() => []);
+    for (const entry of entries)
+      if (entry.endsWith('.yml')) found.push(join(directory, entry));
+  }
+  return found.sort();
+}

package/src/cli/register-fleet.ts

@@ -13,6 +13,23 @@ import { fleetWatch, watchServices } from './fleet-watch';
 import type { NodeReport } from '../types';
 import { registerGithubVerify } from './github-verify';
 import { fleetRestore, type FleetRestoreOptions } from './fleet-restore';
+import { fleetValidate, type FleetValidateOptions } from './fleet-validate';
+import {
+  fleetManifest,
+  manifestServices,
+  type FleetManifestOptions,
+} from './fleet-manifest';
+import {
+  fleetNodeSeed,
+  seedServices,
+  type NodeSeedOptions,
+} from './fleet-node-seed';
+import {
+  fleetNodeReplace,
+  fleetNodeRetire,
+  lifecycleServices,
+  type NodeLifecycleOptions,
+} from './fleet-node-lifecycle';
 
 type Complete = (outcome: CommandOutcome) => void;
 
@@ -187,6 +204,14 @@ function registerSync({ program, defaults, complete }: Registration) {
       collect,
       []
     )
+    .option(
+      '--vault-password-login',
+      'Opt-in: log a worker without a token of its own in with the shared Vault user, on its own terminal'
+    )
+    .option(
+      '--canary <id>',
+      'The worker that proves a new revision first when it is reachable; defaults to canary in fleet.json, then the first worker'
+    )
     .option(
       '--all',
       'Explicit spelling of the default enrolled fleet scope; never discovered peers'
@@ -362,6 +387,114 @@ function registerRestore({ program, complete }: Registration) {
     });
 }
 
+function registerValidate({ program, complete }: Registration) {
+  program
+    .command('fleet-validate')
+    .description(
+      'Validate fleet.json and name the field that breaks a rule; contacts nothing'
+    )
+    .option(
+      '--file <path>',
+      'The fleet.json to validate; defaults to the project’s'
+    )
+    .option(
+      '--ansible',
+      'Also render the Ansible inventory and syntax-check every playbook with the pinned Ansible'
+    )
+    .action(async (_options, command: Command) => {
+      complete(
+        await fleetValidate(command.optsWithGlobals<FleetValidateOptions>())
+      );
+    });
+}
+
+function registerLifecycle({ program, defaults, complete }: Registration) {
+  const action =
+    (name: 'replace' | 'retire') =>
+    async (_options: unknown, command: Command) => {
+      const options = command.optsWithGlobals<
+        NodeLifecycleOptions & CliOptions
+      >();
+      const settings = await withSettings(defaults, options);
+      const services = lifecycleServices(settings.config);
+      complete(
+        name === 'replace'
+          ? await fleetNodeReplace(options, services)
+          : await fleetNodeRetire(options, services)
+      );
+    };
+  program
+    .command('fleet-node-replace')
+    .description(
+      'Put a fresh machine in place of a worker under the same id; writes need --apply --yes'
+    )
+    .requiredOption('--id <name>', 'The declared worker being replaced')
+    .option(
+      '--host-key <key>',
+      'The new machine’s SSH host key, "TYPE BASE64", verified out of band or printed by fleet-node-seed'
+    )
+    .option('--apply', 'Change the manager and Vault; requires --yes')
+    .option('--yes', 'Confirm an explicitly requested --apply operation')
+    .action(action('replace'));
+  program
+    .command('fleet-node-retire')
+    .description(
+      'Take a worker out of the fleet: revoke its token, forget its host key and roster entry; writes need --apply --yes'
+    )
+    .requiredOption('--id <name>', 'The declared worker to retire')
+    .option(
+      '--apply',
+      'Change the manager, Vault and the fleet state; requires --yes'
+    )
+    .option('--yes', 'Confirm an explicitly requested --apply operation')
+    .action(action('retire'));
+  program
+    .command('fleet-node-seed')
+    .description(
+      'Write cloud-init (or autoinstall) user data a new worker joins the fleet with by itself'
+    )
+    .requiredOption('--id <name>', 'The declared worker to seed')
+    .requiredOption(
+      '--output <path>',
+      'Where to write the seed (mode 600); it holds a single-use auth key and is never printed'
+    )
+    .option(
+      '--public-key <path>',
+      'The manager public key to authorize; default ~/.ssh/id_ed25519.pub'
+    )
+    .option('--autoinstall', 'An Ubuntu autoinstall file, for bare metal')
+    .option(
+      '--apply',
+      'Also pin the seed host key on this manager; requires --yes'
+    )
+    .option('--yes', 'Confirm an explicitly requested --apply operation')
+    .action(async (_options: unknown, command: Command) => {
+      const options = command.optsWithGlobals<NodeSeedOptions & CliOptions>();
+      const settings = await withSettings(defaults, options);
+      complete(await fleetNodeSeed(options, seedServices(settings.config)));
+    });
+}
+
+function registerManifest({ program, defaults, complete }: Registration) {
+  program
+    .command('fleet-manifest')
+    .description(
+      'Measure what a worker is made of and check it against the pins and a fresh build'
+    )
+    .requiredOption('--id <name>', 'The enrolled worker to measure')
+    .option(
+      '--reference <path>',
+      'A fleet-manifest --json of a fresh build of the same revision'
+    )
+    .action(async (_options: unknown, command: Command) => {
+      const options = command.optsWithGlobals<
+        FleetManifestOptions & CliOptions
+      >();
+      const settings = await withSettings(defaults, options);
+      complete(await fleetManifest(options, manifestServices(settings.config)));
+    });
+}
+
 export function registerFleet(
   program: Command,
   defaults: Settings,
@@ -379,6 +512,9 @@ export function registerFleet(
   registerReport(registration);
   registerWatch(registration);
   registerRestore(registration);
+  registerValidate(registration);
+  registerLifecycle(registration);
+  registerManifest(registration);
   registerRepair(registration);
   registerNodes(registration);
   registerAccounts(registration);

package/src/cli/registry.ts

@@ -116,6 +116,18 @@ export const COMMANDS: CommandSpec[] = [
       ['manager', 'restore', 'replace', 'lost', 'recovery'],
       true,
     ],
+    [
+      'fleet-validate',
+      'Validate the fleet configuration',
+      'Read-only: judge fleet.json without contacting anything. An invalid file names the first rule it breaks as {code, path, expected, actual}. --ansible also renders the Ansible inventory and syntax-checks every playbook with the pinned Ansible.',
+      ['validate', 'lint', 'schema', 'fleet.json', 'configuration', 'ansible'],
+    ],
+    [
+      'fleet-manifest',
+      'Measure a worker and compare it with a fresh build',
+      'Read-only over verified SSH: every installed package, the active mise tools and the state of each always-on service, with a digest that is the same for two workers built from the same revision. The check worker:manifest reports every difference from the declared pins and, with --reference, from a fresh build.',
+      ['manifest', 'drift', 'reproducible', 'rebuild', 'packages', 'audit'],
+    ],
     [
       'fleet-node-sync',
       'Sync this node',
@@ -181,6 +193,27 @@ export const COMMANDS: CommandSpec[] = [
       ['github', 'verify', 'pull request', 'push', 'permissions', 'workflow'],
       true,
     ],
+    [
+      'fleet-node-replace',
+      'Replace a worker with a fresh machine',
+      'Preview, or with --apply --yes carry out, putting a fresh machine in place of a declared worker under the same id: verify the new device on the tailnet, pin its host key (--host-key), bind the roster entry to it and issue it a Vault token of its own, revoking the old one. Then fleet-sync --node ID converges it. Running it again changes nothing.',
+      ['replace', 'rebuild', 'reinstall', 'host key', 'token', 'device'],
+      true,
+    ],
+    [
+      'fleet-node-seed',
+      'Seed a new worker that joins by itself',
+      'Write cloud-init user data (or an Ubuntu autoinstall file with --autoinstall) for a declared worker to a private file: its account with the manager key, the privilege rule, a host key generated for it, the pinned Tailscale and a short-lived single-use auth key from the secrets provider (tailnet-auth-key). --apply --yes also pins that host key on the manager, so there is no trust on first use.',
+      ['seed', 'cloud-init', 'autoinstall', 'new', 'bootstrap', 'provision'],
+      true,
+    ],
+    [
+      'fleet-node-retire',
+      'Retire a worker',
+      'Preview, or with --apply --yes carry out, taking a worker out of the fleet: revoke its Vault token, forget its pinned host key, remove its roster entry and record a tombstone in the fleet state. Then remove it from fleet.json.',
+      ['retire', 'remove', 'decommission', 'revoke', 'delete'],
+      true,
+    ],
   ]),
   ...group('T3', [
     [