@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/src/cli/node-deployment.ts

@@ -0,0 +1,34 @@
+import { join } from 'node:path';
+import { read, object, write } from '../t3/files';
+import { FleetUsageError } from '../errors';
+
+export async function deployment(root: string) {
+  const raw = await read(join(root, 'node_modules/.personal-node.json'));
+  if (raw === null) return null;
+  const data = object(raw);
+  if (
+    data['version'] !== 1 ||
+    typeof data['revision'] !== 'string' ||
+    !/^[a-f0-9]{40}$/.test(data['revision']) ||
+    typeof data['node'] !== 'string' ||
+    !/^[a-z0-9][a-z0-9-]{0,62}$/.test(data['node'])
+  )
+    throw new FleetUsageError(
+      'Invalid local node receipt. Restore it before reconciling.'
+    );
+  return {
+    workspace: join(root, 'node_modules/.fleet-revisions', data['revision']),
+    node: data['node'],
+    revision: data['revision'],
+  };
+}
+
+export async function recordDeployment(
+  root: string,
+  node: string,
+  revision: string
+) {
+  const path = join(root, 'node_modules/.personal-node.json');
+  const content = JSON.stringify({ version: 1, node, revision }) + '\n';
+  if ((await read(path)) !== content) await write(path, content);
+}

package/src/cli/node-sync.ts

@@ -0,0 +1,114 @@
+import { join } from 'node:path';
+import { configureWorkspace } from '../configure';
+import { runCommand } from '../runner';
+import { FleetUsageError } from '../errors';
+import type { Runner } from '../types';
+import type { Settings } from './settings';
+import type { CommandOutcome } from './contracts';
+import { syncT3 } from './node-t3';
+import { nodeId, type T3Options } from '../t3/desired';
+import { recordDeployment } from './node-deployment';
+
+export interface NodeSyncOptions extends T3Options {
+  revision?: string;
+}
+
+/** One local convergence: locked tools, public launcher, profiles, then T3. */
+export async function syncNode(
+  options: NodeSyncOptions,
+  settings: Settings,
+  run: Runner = runCommand
+): Promise<CommandOutcome> {
+  if (process.platform === 'win32' && !options.dryRun)
+    throw new FleetUsageError(
+      'Codex proxy node sync requires macOS/Linux/WSL. Use dev-fleet commands for native Windows configuration.'
+    );
+  const node = nodeId(options.id);
+  const head = await run(['git', 'rev-parse', '--verify', 'HEAD'], {
+    cwd: settings.workspace,
+  });
+  const revision = options.revision ?? head.stdout.trim();
+  if (!head.ok || !/^[a-f0-9]{40}$/.test(revision))
+    throw new FleetUsageError(
+      'An existing personal checkout is required; set --workspace PATH.'
+    );
+  const request = { node, revision, tool: 'codex', profile: 'proxy' };
+  if (options.dryRun)
+    return {
+      exitCode: 0,
+      data: {
+        version: 1,
+        command: 'fleet-node-sync',
+        ok: true,
+        applied: false,
+        ...request,
+        steps: [
+          'Reconcile locked tools',
+          'Install personal and retire owned ws launcher',
+          'Upsert Codex proxy profile',
+          'Reconcile declared T3 instances and remove stale owned entries',
+        ],
+      },
+    };
+  const checks = await configureWorkspace(settings.workspace, request, run);
+  if (checks.some((check) => check.status !== 'pass'))
+    return {
+      exitCode: 1,
+      data: { version: 1, command: 'fleet-node-sync', ok: false, checks },
+    };
+  return finishSync(options, settings, { request, checks }, run);
+}
+
+async function finishSync(
+  options: NodeSyncOptions,
+  settings: Settings,
+  input: {
+    request: { node: string; revision: string; tool: string; profile: string };
+    checks: Awaited<ReturnType<typeof configureWorkspace>>;
+  },
+  run: Runner
+): Promise<CommandOutcome> {
+  const { request, checks } = input;
+  const { node, revision } = request;
+  const workspace = join(
+    settings.workspace,
+    'node_modules/.fleet-revisions',
+    revision
+  );
+  const installed = await run(['sh', 'bootstrap/install-launcher.sh'], {
+    cwd: workspace,
+    timeoutMs: 30_000,
+  });
+  if (!installed.ok)
+    return {
+      exitCode: 1,
+      data: {
+        version: 1,
+        ok: false,
+        checks,
+        error:
+          'Launcher installation failed; profile changes may already have applied.',
+      },
+    };
+  const t3 = await syncT3({ ...options, id: node }, { ...settings, workspace });
+  if (t3.exitCode !== 0) return t3;
+  await recordDeployment(settings.workspace, node, revision);
+  return {
+    exitCode: 0,
+    data: {
+      version: 1,
+      command: 'fleet-node-sync',
+      ok: true,
+      applied: true,
+      ...request,
+      checks,
+      t3: t3.data,
+      readiness: {
+        authentication: 'unverified',
+        inference: 'unverified',
+        pairing: 'unverified',
+      },
+      next: 'Use devfleet t3-status for configuration drift and devfleet fleet-status for machine health.',
+    },
+  };
+}

package/src/cli/node-t3.ts

@@ -0,0 +1,31 @@
+import { FleetUsageError } from '../errors';
+import type { Settings } from './settings';
+import type { CommandOutcome } from './contracts';
+import { t3Command } from './t3/command';
+import type { T3Options } from '../t3/desired';
+
+export async function syncT3(
+  options: T3Options,
+  settings: Settings
+): Promise<CommandOutcome> {
+  try {
+    return await t3Command('t3-apply', options, settings);
+  } catch (error) {
+    return {
+      exitCode: 1,
+      data: {
+        version: 1,
+        command: 'fleet-node-sync',
+        ok: false,
+        applied: true,
+        stage: 't3',
+        error:
+          error instanceof FleetUsageError
+            ? error.message
+            : 'T3 reconciliation failed; inspect local configuration and ownership state.',
+        progress:
+          'Tools, launcher and profile steps completed. Node receipt was not advanced. Fix the T3 conflict and repeat fleet-node-sync.',
+      },
+    };
+  }
+}

package/src/cli/options.ts

@@ -0,0 +1,141 @@
+import { CAPABILITIES } from '../config';
+import { FleetUsageError } from '../errors';
+import type { Capability } from '../types';
+import type { Settings } from './settings';
+
+export interface CliOptions extends Partial<Settings> {
+  managed?: boolean;
+  workers?: boolean;
+  tailnet?: boolean;
+  list?: boolean;
+  onboard?: boolean;
+  schema?: boolean;
+  json?: boolean;
+  nonInteractive?: boolean;
+  interactive?: boolean;
+  local?: boolean;
+  all?: boolean;
+  node?: string[];
+  require?: string;
+  timeout?: string;
+  strict?: boolean;
+  repair?: string;
+  script?: boolean;
+  planHash?: string;
+  apply?: boolean;
+  yes?: boolean;
+  id?: string;
+  ssh?: string;
+  path?: string;
+  runtime?: string;
+  search?: string;
+  group?: string;
+}
+
+export function capabilities(value?: string): Capability[] {
+  const values =
+    value === 'none'
+      ? []
+      : (value?.split(',') ??
+        CAPABILITIES.filter((entry) => entry !== 'worker'));
+  if (values.some((entry) => !CAPABILITIES.includes(entry as Capability)))
+    throw new FleetUsageError(
+      `--require expects ${CAPABILITIES.join(',')} or none.`
+    );
+  return [...new Set(values)] as Capability[];
+}
+
+export function timeout(options: CliOptions): number {
+  const value = Number(
+    options.timeout ?? (options.apply ? 1_500_000 : 120_000)
+  );
+  if (!Number.isInteger(value) || value < 1000 || value > 1_800_000)
+    throw new FleetUsageError('--timeout must be 1000–1800000 milliseconds.');
+  return value;
+}
+
+/** Validation runs on the internal action selected by fleet-* flags. */
+export function validateOptions(command: string, options: CliOptions): void {
+  if (options.tailnet && options.workers)
+    throw new FleetUsageError('Choose --tailnet or --workers, not both.');
+  if (options.onboard && options.schema)
+    throw new FleetUsageError('Choose --onboard or --schema, not both.');
+  validateMutation(command, options);
+  validateRepair(command, options);
+  validateScope(command, options);
+  if (
+    (['discover', 'health'].includes(command) ||
+      (command === 'repair' && !options.local)) &&
+    options.require !== undefined
+  )
+    throw new FleetUsageError(
+      '--require is supported for roster status and local repair only; tailnet checks use declared roster requirements.'
+    );
+  if (options.timeout !== undefined) timeout(options);
+}
+
+function validateMutation(command: string, options: CliOptions): void {
+  if (options.apply && !['add', 'repair'].includes(command))
+    throw new FleetUsageError(
+      '--apply is only valid for fleet-node-add and fleet-repair.'
+    );
+  if (options.apply && !options.yes)
+    throw new FleetUsageError('Mutation requires both --apply and --yes.');
+}
+
+function validateScope(command: string, options: CliOptions): void {
+  const selected = [options.local, options.all, options.node?.length].filter(
+    Boolean
+  );
+  if (['discover', 'health'].includes(command) && selected.length)
+    throw new FleetUsageError(
+      'Tailscale discovery, --tailnet and --workers always cover all visible computers; --local, --all and --node are not supported.'
+    );
+  if (selected.length > 1)
+    throw new FleetUsageError(
+      'Choose --local, --all, or --node, not a combination.'
+    );
+  validateRosterScope(command, options);
+}
+
+function validateRosterScope(command: string, options: CliOptions): void {
+  if ((options.local || options.all) && !['doctor', 'repair'].includes(command))
+    throw new FleetUsageError(
+      '--local and --all are only valid for fleet-status and fleet-repair.'
+    );
+}
+
+function validateRepair(command: string, options: CliOptions): void {
+  if (
+    options.planHash !== undefined &&
+    !/^[a-f0-9]{64}$/.test(options.planHash)
+  )
+    throw new FleetUsageError(
+      '--plan-hash expects the SHA-256 value from a repair preview.'
+    );
+  const repairFlags =
+    options.repair !== undefined ||
+    options.script === true ||
+    options.planHash !== undefined;
+  if (repairFlags && command !== 'repair')
+    throw new FleetUsageError(
+      '--repair, --script and --plan-hash are only valid for fleet-repair without --list.'
+    );
+  if (options.script && options.apply)
+    throw new FleetUsageError(
+      '--script only generates a preview; run a reviewed repair separately with --apply --yes.'
+    );
+  validateCatalog(command, options);
+}
+
+function validateCatalog(command: string, options: CliOptions): void {
+  const filtered =
+    options.local ||
+    options.all ||
+    Boolean(options.node?.length) ||
+    options.require !== undefined;
+  if (command === 'repairs' && filtered)
+    throw new FleetUsageError(
+      'fleet-repair --list is a static catalog and does not accept target or capability filters.'
+    );
+}

package/src/cli/probe-source.ts

@@ -0,0 +1,7 @@
+import { readFile } from 'node:fs/promises';
+import { bundleProbe } from '../transport';
+
+export async function probeSource(): Promise<string> {
+  if (typeof Bun !== 'undefined') return bundleProbe();
+  return readFile(new URL('./probe.mjs', import.meta.url), 'utf8');
+}

package/src/cli/program.ts

@@ -0,0 +1,169 @@
+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;
+}
+
+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: 'Existing manager checkout; 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})`;
+  return release.version === SOURCE_VERSION
+    ? `${release.version} (unreleased source build)`
+    : 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 confirms interactively or with --apply --yes.',
+      'Preview until --apply --yes: fleet-repair, fleet-node-add. --json does not make a command read-only.',
+      'Agents: devfleet commands --json. Menu: devfleet --interactive.',
+    ].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.',
+    },
+  };
+}