@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/src/cli/program.ts

@@ -0,0 +1,185 @@
+import { Command, CommanderError } from 'commander';
+import { FleetUsageError } from '../errors';
+import { indexedCommands } from './command-index';
+import { registerT3 } from './t3/register';
+import { registerSourceOperations } from './source-operations';
+import { registerFleet } from './register-fleet';
+import { agentGuide } from './agent-guide';
+import type { Settings } from './settings';
+import type { CliOptions } from './options';
+import type { CommandOutcome } from './contracts';
+
+export interface Release {
+  version: string;
+  /** ISO timestamp recorded when this distribution was built; null for source runs. */
+  releasedAt: string | null;
+  /** The commit a published package was built from: what fleet-sync run from
+   * it converges every machine to. Absent for source runs.
+   */
+  revision?: string | null;
+  /** The issue tracker of the package: where its users report a defect or
+   * ask for a feature.
+   */
+  issues?: string | null;
+}
+
+export const GLOBAL_OPTIONS = [
+  {
+    flag: '--json',
+    description: 'One versioned JSON document on stdout; never prompt',
+  },
+  { flag: '--non-interactive', description: 'Never open interactive prompts' },
+  {
+    flag: '--workspace <path>',
+    description:
+      'A dev-fleet checkout to run from instead of this package (development); does not clone or change it',
+  },
+  { flag: '--config <path>', description: 'Local, secret-free fleet roster' },
+];
+
+/** The version a checkout carries; a published package has a real one. */
+export const SOURCE_VERSION = '0.0.0-development';
+
+export function releaseLabel(release: Release): string {
+  if (release.releasedAt)
+    return `${release.version} (released ${release.releasedAt})`;
+  if (release.version === SOURCE_VERSION)
+    return `${release.version} (unreleased source build)`;
+  return release.revision
+    ? `${release.version} (commit ${release.revision})`
+    : release.version;
+}
+
+function createProgram(
+  release: Release,
+  output: (text: string) => void
+): Command {
+  const program = new Command()
+    .name('devfleet')
+    .description('Developer fleet, T3 and platform operations')
+    .version(releaseLabel(release))
+    .exitOverride()
+    .configureOutput({ writeOut: output, writeErr: () => undefined })
+    .showSuggestionAfterError(false)
+    .addHelpCommand('help [command]', 'Show help for a command')
+    .option(
+      '--interactive',
+      'Open the interactive terminal application (TTY required)'
+    );
+  for (const option of GLOBAL_OPTIONS)
+    program.option(option.flag, option.description);
+  program.addHelpText(
+    'after',
+    [
+      '',
+      `Release: ${releaseLabel(release)}`,
+      'Groups: fleet-* developer computers · t3-* T3 provider instances · cliproxy the CLI proxy service.',
+      'Apply on invocation (--dry-run previews): fleet-node-sync, t3-apply, t3-cleanup. fleet-sync applies on invocation too; --apply --yes is still accepted.',
+      'Preview until --apply --yes: fleet-repair, fleet-node-add. --json does not make a command read-only.',
+      'Agents: devfleet commands --json. Menu: devfleet --interactive.',
+      ...(release.issues
+        ? [
+            `Bugs and feature requests: ${release.issues}. Report them there; never patch the installed package.`,
+          ]
+        : []),
+    ].join('\n')
+  );
+  return program;
+}
+
+function catalog(options: CliOptions, release: Release): CommandOutcome {
+  const commands = indexedCommands(options.search, options.group);
+  return {
+    exitCode: 0,
+    data: {
+      version: 1,
+      cliVersion: release.version,
+      releasedAt: release.releasedAt,
+      command: 'commands',
+      ok: true,
+      commands,
+      globalOptions: GLOBAL_OPTIONS,
+      defaultCommand: 'help',
+      schema: 'devfleet fleet-nodes --schema --json',
+      agent: agentGuide(release),
+    },
+    text: [
+      `Personal command catalog · ${releaseLabel(release)}`,
+      ...commands.map((entry) => `\n  ${entry.id}\n    ${entry.description}`),
+      '\nUse personal <command> --help for options; personal --interactive opens the menu.',
+    ].join('\n'),
+  };
+}
+
+export async function execute(
+  args: string[],
+  defaults: Settings,
+  version: string | Release
+): Promise<CommandOutcome> {
+  const release: Release =
+    typeof version === 'string' ? { version, releasedAt: null } : version;
+  let outcome: CommandOutcome | undefined;
+  let output = '';
+  const program = createProgram(release, (text) => {
+    output += text;
+  });
+  const complete = (result: CommandOutcome) => {
+    outcome = result;
+  };
+  registerFleet(program, defaults, complete);
+  registerT3(program, defaults, complete);
+  registerSourceOperations(program, defaults, complete);
+  program
+    .command('commands')
+    .description('Search the command catalog and agent contract')
+    .option('--search <text>', 'Filter names, descriptions and keywords')
+    .option(
+      '--group <name>',
+      'Filter group: Fleet, T3, Infra, Workstation, Reference'
+    )
+    .action((_options, command: Command) => {
+      outcome = catalog(command.optsWithGlobals<CliOptions>(), release);
+    });
+  program.action(() => {
+    if (program.opts<CliOptions>().json)
+      outcome = catalog(program.opts<CliOptions>(), release);
+    else program.help();
+  });
+  try {
+    await program.parseAsync(args, { from: 'user' });
+    return (
+      outcome ?? {
+        exitCode: 0,
+        data: { version: 1, help: output.trim() },
+        text: output.trim(),
+      }
+    );
+  } catch (error) {
+    return commandError(error, output);
+  }
+}
+
+function commandError(error: unknown, output: string): CommandOutcome {
+  if (error instanceof CommanderError && error.exitCode === 0)
+    return {
+      exitCode: 0,
+      data: { version: 1, help: output.trim() },
+      text: output.trim(),
+    };
+  const usage =
+    error instanceof CommanderError || error instanceof FleetUsageError;
+  return {
+    exitCode: usage ? 2 : 1,
+    data: {
+      version: 1,
+      ok: false,
+      code: usage ? 'invalid_usage' : 'operation_failed',
+      error:
+        error instanceof FleetUsageError
+          ? error.message
+          : usage
+            ? 'Invalid command or option. Run personal --help or personal commands --json.'
+            : 'Operation failed. Inspect configuration and permissions locally; raw errors are withheld to protect credentials.',
+    },
+  };
+}

package/src/cli/project.ts

@@ -0,0 +1,51 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { record } from '../config';
+
+/** The file a project keeps its fleet configuration in. */
+export const PROJECT_CONFIG = 'fleet.json';
+
+/** Another tool's fleet.json is not this one: a fleet configuration is a JSON
+ * object that names a manager. Whether it is a valid one is said later, with
+ * the file's path, by whatever reads it.
+ */
+function fleetConfiguration(path: string): boolean {
+  try {
+    const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    return record(value) && record(value['manager']);
+  } catch {
+    return false;
+  }
+}
+
+/** The fleet.json of the project a command is run from: the closest one in
+ * the working directory or above it, or null.
+ */
+export function projectConfig(cwd: string): string | null {
+  let current = resolve(cwd);
+  while (true) {
+    const candidate = join(current, PROJECT_CONFIG);
+    if (fleetConfiguration(candidate)) return candidate;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/** A fleet is a project of your own: a fleet.json in Git, and the devfleet
+ * CLI run from inside it. This names that file for the whole command, and
+ * for everything the command starts in another directory (fleet-sync re-runs
+ * itself from a checkout of the revision). `DEVFLEET_CONFIG` names a file
+ * elsewhere and wins. Only the CLI does this: launchers and scheduled jobs
+ * run in directories that belong to other projects and read the copy
+ * fleet-sync installed.
+ */
+export function useProjectConfig(
+  env: NodeJS.ProcessEnv = process.env,
+  cwd = process.cwd()
+): string | null {
+  const named = env['DEVFLEET_CONFIG'];
+  const path = named ? resolve(cwd, named) : projectConfig(cwd);
+  if (path) env['DEVFLEET_CONFIG'] = path;
+  return path;
+}

package/src/cli/register-fleet.ts

@@ -0,0 +1,296 @@
+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';
+import { fleetState, type FleetStateOptions } from './fleet-state';
+
+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>',
+      'Converge to an exact source commit; defaults to the commit the dev-fleet package you run was published from'
+    )
+    .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)));
+    });
+}
+
+function registerState({ program, complete }: Registration) {
+  program
+    .command('fleet-state')
+    .description(
+      'Show where the fleet state is kept and whether the bucket holds it; flags connect, upload and restore'
+    )
+    .option(
+      '--init',
+      'Connect the bucket: restore the fleet state from it, or seed it from this machine, and save its credentials for runs this machine starts by itself'
+    )
+    .option(
+      '--bucket <name>',
+      'With --init, when no fleet.json names the bucket: S3-compatible bucket name'
+    )
+    .option(
+      '--endpoint <url>',
+      'With --init: https origin of the S3 service; omit for AWS S3'
+    )
+    .option('--region <name>', 'With --init: bucket region, such as auto')
+    .option('--prefix <prefix>', 'With --init: key prefix; default dev-fleet')
+    .option(
+      '--directory <path>',
+      'With --init: replicate to a directory instead of a bucket'
+    )
+    .option(
+      '--import <path>',
+      'Store a fleet configuration without running fleet-sync'
+    )
+    .option(
+      '--export',
+      'Print the stored fleet configuration: the one fleet-sync last applied'
+    )
+    .option('--example', 'Print an example fleet.json to start a project from')
+    .option('--push', 'Upload this machine’s changes to the bucket')
+    .option(
+      '--restore',
+      'Replace this machine’s copy with the bucket’s version'
+    )
+    .option('--yes', 'With --restore: discard changes the bucket does not hold')
+    .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.'
+    )
+    .action(async (_options, command: Command) => {
+      complete(await fleetState(command.optsWithGlobals<FleetStateOptions>()));
+    });
+}
+
+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);
+  registerState(registration);
+  registerRepair(registration);
+  registerNodes(registration);
+}