@crvouga/dev-fleet 0.6.0 → 0.8.0

package/src/cli/register-fleet.ts

@@ -12,6 +12,24 @@ import { fleetReport, type FleetReportOptions } from './fleet-report';
 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;
 
@@ -186,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'
@@ -199,6 +225,10 @@ function registerSync({ program, defaults, complete }: Registration) {
       'Accepted for compatibility; fleet-sync applies by default (schedule writes still need --apply --yes)'
     )
     .option('--yes', 'Accepted for compatibility with --apply')
+    .option(
+      '--take-over',
+      'Make this machine the manager while another one still holds the manager lease'
+    )
     .option(
       '--schedule <action>',
       'Manager-only schedule: enable, pause, resume, disable, status'
@@ -277,6 +307,14 @@ function registerState({ program, complete }: Registration) {
       'Replace this machine’s copy with the bucket’s version'
     )
     .option('--yes', 'With --restore: discard changes the bucket does not hold')
+    .option(
+      '--timestamp <time>',
+      'With --restore: the version the bucket held at this time, uploaded again as the current one (a damaged replica)'
+    )
+    .option(
+      '--take-over',
+      'With --init or --import: change the fleet state while another manager still holds the manager lease'
+    )
     .addHelpText(
       'after',
       '\nRead-only without a flag. The bucket is the one named under "state" in fleet.json. Every command reads its credentials from DEVFLEET_BUCKET_ACCESS_KEY_ID and DEVFLEET_BUCKET_SECRET_ACCESS_KEY; --init also asks on the terminal. They are never taken from arguments.'
@@ -332,6 +370,131 @@ function registerWatch({ program, defaults, complete }: Registration) {
     });
 }
 
+function registerRestore({ program, complete }: Registration) {
+  program
+    .command('fleet-restore')
+    .description(
+      'Bring a replacement manager back from the bucket (docs/manager-recovery.md)'
+    )
+    .option(
+      '--dry-run',
+      'Verify every prerequisite and list what would be restored; change nothing'
+    )
+    .action(async (_options, command: Command) => {
+      complete(
+        await fleetRestore(command.optsWithGlobals<FleetRestoreOptions>())
+      );
+    });
+}
+
+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,
@@ -348,6 +511,10 @@ export function registerFleet(
   registerState(registration);
   registerReport(registration);
   registerWatch(registration);
+  registerRestore(registration);
+  registerValidate(registration);
+  registerLifecycle(registration);
+  registerManifest(registration);
   registerRepair(registration);
   registerNodes(registration);
   registerAccounts(registration);

package/src/cli/registry.ts

@@ -93,7 +93,7 @@ export const COMMANDS: CommandSpec[] = [
     [
       '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.',
+      '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. --timestamp TIME --yes restores the version the bucket held then and uploads it again: the remedy for a corrupt replica.',
       ['state', 'bucket', 'restore', 'recover', 'disposable'],
       true,
     ],
@@ -103,6 +103,31 @@ export const COMMANDS: CommandSpec[] = [
       'Read-only: success rate, mean duration, the most frequent failing check IDs and how long each machine was not ready, from the history of fleet-sync runs kept in the fleet state. --since 30d (default), 12h or 90m.',
       ['history', 'reliability', 'report', 'failures', 'sync'],
     ],
+    [
+      'fleet-restore --dry-run',
+      'Check that a replacement manager can be restored',
+      'Read-only: verifies every prerequisite of a manager restore (fleet.json, the bucket and the state in it, the local host name, Git, Tailscale, the container engine) and lists what would be restored, in order. docs/manager-recovery.md is the runbook.',
+      ['manager', 'restore', 'replace', 'lost', 'recovery', 'runbook'],
+    ],
+    [
+      'fleet-restore',
+      'Restore a replacement manager from the bucket',
+      'Runs the same checks, then takes the fleet state from the bucket. fleet-sync rebuilds the rest.',
+      ['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',
@@ -168,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', [
     [