@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/src/cli/repair.ts

@@ -0,0 +1,209 @@
+import { AUTOMATED_REPAIRS, REPAIR_RECIPES, recipe } from '../repair-catalog';
+import { repairPlan } from '../repair-plan';
+import { makeReport, reportExitCode } from '../report';
+import { FleetUsageError } from '../errors';
+import { inspectRepair } from './repair-inspect';
+import { applyRepairs } from './repair-apply';
+import { repairScript } from './repair-script';
+import { repairPlanHash } from './repair-guard';
+import type { AutomatedRepair } from '../repair-catalog';
+import type { RepairStep } from '../repair-plan';
+import type { FleetServices } from './fleet';
+import type { CliOptions } from './options';
+import type { Settings } from './settings';
+import type { CommandOutcome } from './contracts';
+
+export function requestedRepairs(
+  value?: string
+): AutomatedRepair[] | undefined {
+  if (value === undefined) return undefined;
+  const ids = value.split(',');
+  if (
+    !ids.length ||
+    ids.some((id) => !AUTOMATED_REPAIRS.includes(id as AutomatedRepair))
+  )
+    throw new FleetUsageError(
+      '--repair expects workspace,workstation,providers. Native logins require operator approval; inspect fleet-repair --list.'
+    );
+  return [...new Set(ids)] as AutomatedRepair[];
+}
+export function repairCatalog(): CommandOutcome {
+  return {
+    exitCode: 0,
+    data: {
+      version: 1,
+      command: 'repairs',
+      ok: true,
+      recipes: REPAIR_RECIPES,
+      credentials: [
+        'Authenticate each computer independently with the intended identity. Never clone OAuth caches, browser cookies, keychains, SSH private keys or Vault sessions.',
+        "Shared secrets come from the fleet's secrets provider with this machine's own access (see `secrets` in the fleet configuration).",
+        'A login does not grant every account, team or resource permission.',
+      ],
+    },
+  };
+}
+
+export async function executeRepairCommand(
+  command: string,
+  options: CliOptions,
+  settings: Settings,
+  services: FleetServices
+): Promise<CommandOutcome> {
+  return command === 'repairs'
+    ? repairCatalog()
+    : executeRepair(options, settings, services);
+}
+
+export async function executeRepair(
+  options: CliOptions,
+  settings: Settings,
+  services: FleetServices
+): Promise<CommandOutcome> {
+  const selected = requestedRepairs(options.repair);
+  const before = await inspectRepair(options, settings, services);
+  const steps = selectRepairs(
+    repairPlan(before.reports, before.targets),
+    before,
+    selected
+  );
+  const planHash = repairPlanHash(steps, before.targets);
+  if (options.planHash && options.planHash !== planHash)
+    throw new FleetUsageError(
+      'Repair plan changed since review. Generate and review a fresh preview; nothing was applied.'
+    );
+  const initial = makeReport('repair', before.reports);
+  const healthOk = reportExitCode(initial, true) === 0;
+  const script = options.script
+    ? repairScript(steps, before.targets)
+    : undefined;
+  if (!options.apply)
+    return {
+      exitCode: 0,
+      data: {
+        ...initial,
+        ok: true,
+        applied: false,
+        planHash,
+        healthOk,
+        coverage: before.coverage,
+        steps,
+        ...(script ? { script } : {}),
+        authorize:
+          'Preview only. Review effects, then repeat with --apply --yes. Only eligible automatic steps execute. Native logins and manual steps remain operator work.',
+      },
+      text: script ?? renderSteps(steps),
+    };
+  return appliedOutcome(steps, before, { options, settings, services });
+}
+
+async function appliedOutcome(
+  steps: RepairStep[],
+  before: Awaited<ReturnType<typeof inspectRepair>>,
+  context: {
+    options: CliOptions;
+    settings: Settings;
+    services: FleetServices;
+  }
+): Promise<CommandOutcome> {
+  const { options, settings, services } = context;
+  const executions = await applyRepairs(
+    before.targets,
+    steps,
+    options,
+    services
+  );
+  const after = await recheckRepair(before, options, settings, services);
+  const checked = makeReport('repair', after.reports);
+  const executionOk = executions.every((node) =>
+    node.checks.every((check) => check.status === 'pass')
+  );
+  const verified = reportExitCode(checked, true) === 0;
+  const ok = executionOk && verified;
+  return {
+    exitCode: ok ? 0 : 1,
+    data: {
+      ...checked,
+      ok,
+      applied: true,
+      executionOk,
+      healthOk: verified,
+      coverage: after.coverage,
+      steps,
+      executions,
+      remaining: repairPlan(after.reports, after.targets),
+      completed: executions
+        .flatMap((node) => node.checks)
+        .filter((check) => check.status === 'pass').length,
+    },
+    text: `Repair commands ${executionOk ? 'completed' : 'need attention'}; fresh health ${verified ? 'verified' : 'still has failing or unverified checks'}.\n${renderSteps(repairPlan(after.reports, after.targets))}`,
+  };
+}
+
+function selectRepairs(
+  steps: RepairStep[],
+  inspection: Awaited<ReturnType<typeof inspectRepair>>,
+  selected?: AutomatedRepair[]
+): RepairStep[] {
+  if (!selected) return steps;
+  const filtered = steps.filter(
+    (step) => !step.automatic || selected.includes(step.id as AutomatedRepair)
+  );
+  for (const target of inspection.targets) {
+    const report = inspection.reports.find(
+      (entry) => entry.node === target.name
+    );
+    if (!report?.snapshot) continue;
+    for (const id of selected)
+      if (!filtered.some((step) => step.node === target.name && step.id === id))
+        filtered.push({
+          ...recipe(id),
+          node: target.name,
+          eligible: true,
+          checks: ['explicit:request'],
+          next: [
+            'Explicitly requested owner action; fresh diagnostics still follow.',
+          ],
+        });
+  }
+  return filtered;
+}
+function renderSteps(steps: RepairStep[]): string {
+  return steps
+    .map(
+      (step) =>
+        `${step.node} / ${step.id}: ${step.automatic && step.eligible ? 'automatic after --apply --yes' : 'operator action'}\n  ${step.action}`
+    )
+    .join('\n');
+}
+
+async function recheckRepair(
+  before: Awaited<ReturnType<typeof inspectRepair>>,
+  options: CliOptions,
+  settings: Settings,
+  services: FleetServices
+): Promise<Awaited<ReturnType<typeof inspectRepair>>> {
+  try {
+    return await inspectRepair(options, settings, services);
+  } catch {
+    return {
+      reports: before.reports.map((report) => ({
+        node: report.node,
+        checks: [
+          {
+            id: 'repair:recheck',
+            status: 'fail',
+            summary:
+              'Fresh diagnostics could not complete after repair. Earlier diagnostics are not being treated as fresh; inspect this computer and rerun health.',
+          },
+        ],
+      })),
+      targets: [],
+      coverage: {
+        ...before.coverage,
+        limitation:
+          'Post-repair diagnostics failed. Execution results are retained; machine health remains unverified.',
+      },
+    };
+  }
+}

package/src/cli/roster.ts

@@ -0,0 +1,105 @@
+import { mkdir, open, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { parseConfig } from '../config';
+import { FleetUsageError } from '../errors';
+import type { FleetConfig, FleetNode } from '../types';
+import { capabilities } from './options';
+import type { CliOptions } from './options';
+import { STATE_ROSTER, readRosterText, writeRosterText } from '../state/roster';
+import {
+  mutateState,
+  stateContext,
+  type Standing,
+  type StateContext,
+} from '../state/sync';
+
+export async function readRoster(path: string): Promise<FleetConfig | null> {
+  try {
+    const text = await readRosterText(path);
+    return text === null ? null : parseConfig(JSON.parse(text) as unknown);
+  } catch (error) {
+    if (error instanceof FleetUsageError) throw error;
+    throw new FleetUsageError(
+      'Cannot read a valid roster. Use fleet-nodes --schema or choose --config PATH.'
+    );
+  }
+}
+
+/** The roster a fleet-sync needs: a missing one is an error, not an empty fleet. */
+export async function loadRoster(path: string): Promise<FleetConfig> {
+  let value: unknown;
+  try {
+    const text = await readRosterText(path);
+    if (text === null) throw new Error();
+    value = JSON.parse(text);
+  } catch {
+    throw new FleetUsageError(
+      'Cannot read fleet config. Run devfleet fleet-node-add or use --config PATH.'
+    );
+  }
+  return parseConfig(value);
+}
+
+export function nodeFromOptions(options: CliOptions): FleetNode {
+  if (!options.id || !options.ssh || !options.path)
+    throw new FleetUsageError(
+      'fleet-node-add requires --id NAME --ssh ALIAS --path /absolute/checkout.'
+    );
+  const node = {
+    id: options.id,
+    ssh: options.ssh,
+    workspace: options.path,
+    ...(options.runtime ? { runtime: options.runtime } : {}),
+    required: capabilities(options.require ?? 'github,vault,t3,toolchain'),
+  };
+  return parseConfig({ version: 1, nodes: [node] }).nodes[0]!;
+}
+
+function appendNode(
+  existing: FleetConfig | null,
+  node: FleetNode
+): FleetConfig {
+  return parseConfig({ version: 1, nodes: [...(existing?.nodes ?? []), node] });
+}
+
+export interface AddedNode {
+  roster: FleetConfig;
+  /** How the fleet state stands with the bucket; absent for a roster file. */
+  standing?: Standing;
+}
+
+export async function addNode(
+  path: string,
+  node: FleetNode,
+  apply: boolean,
+  context: () => StateContext = stateContext
+): Promise<AddedNode> {
+  const save = async (): Promise<FleetConfig> => {
+    const roster = appendNode(await readRoster(path), node);
+    await writeRosterText(path, `${JSON.stringify(roster, null, 2)}\n`);
+    return roster;
+  };
+  if (!apply) return { roster: appendNode(await readRoster(path), node) };
+  if (path === STATE_ROSTER) {
+    const { value, standing } = await mutateState(context(), save);
+    return { roster: value, standing };
+  }
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const lock = await acquireLock(path);
+  try {
+    return { roster: await save() };
+  } finally {
+    await lock.close();
+    await unlink(`${path}.lock`);
+  }
+}
+
+async function acquireLock(path: string) {
+  try {
+    return await open(`${path}.lock`, 'wx', 0o600);
+  } catch {
+    throw new FleetUsageError(
+      'Roster is locked or unwritable. Check permissions and concurrent writers; remove a stale .lock only after verifying no operation is running.'
+    );
+  }
+}

package/src/cli/search.ts

@@ -0,0 +1,35 @@
+import Fuse from 'fuse.js';
+import type { CommandSpec } from './contracts';
+
+export function searchCommands(
+  commands: CommandSpec[],
+  term: string
+): CommandSpec[] {
+  const query = term.trim().toLowerCase();
+  if (!query) return commands;
+  const words = query.split(/\s+/);
+  const exact = commands.filter((command) => {
+    const text = [
+      command.id,
+      command.title,
+      command.description,
+      command.group,
+      ...command.keywords,
+    ]
+      .join(' ')
+      .toLowerCase();
+    return words.every((word) => text.includes(word));
+  });
+  const fuzzy = new Fuse(commands, {
+    keys: ['id', 'title', 'keywords', 'description'],
+    threshold: 0.35,
+    ignoreLocation: true,
+  })
+    .search(query)
+    .map((result) => result.item);
+  return [
+    ...new Map(
+      [...exact, ...fuzzy].map((command) => [command.id, command])
+    ).values(),
+  ];
+}

package/src/cli/settings.ts

@@ -0,0 +1,67 @@
+import { access } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { PACKAGE_ROOT, packageInfo } from '../package-info';
+import { STATE_ROSTER } from '../state/roster';
+
+export interface Settings {
+  workspace: string;
+  /** A roster file, or `state:roster` for the roster in the fleet state. */
+  config: string;
+}
+
+export async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findUp(start: string, name: string): Promise<string | null> {
+  let current = resolve(start);
+  while (true) {
+    if (await exists(join(current, name))) return join(current, name);
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/** A dev-fleet checkout, as opposed to any other project that has a mise.toml. */
+const CHECKOUT_MARKER = 'bootstrap/fleet-manager-run.sh';
+
+/** Where the CLI runs from. A published package is its own workspace, whatever
+ * project it is run in; code run from a checkout uses the dev-fleet checkout
+ * the command is started in (development).
+ */
+async function findCheckout(start: string): Promise<string> {
+  if (packageInfo().revision) return PACKAGE_ROOT;
+  let current = resolve(start);
+  while (true) {
+    if (await exists(join(current, CHECKOUT_MARKER))) return current;
+    const parent = dirname(current);
+    if (parent === current) return PACKAGE_ROOT;
+    current = parent;
+  }
+}
+
+export async function resolveSettings(
+  overrides: Partial<Settings> = {},
+  cwd = process.cwd(),
+  env = process.env
+): Promise<Settings> {
+  const workspace = resolve(
+    overrides.workspace ??
+      env['PERSONAL_WORKSPACE'] ??
+      (await findCheckout(cwd))
+  );
+  // A roster file is named explicitly; otherwise it is kept in the fleet state.
+  const named =
+    overrides.config ??
+    env['PERSONAL_FLEET_CONFIG'] ??
+    (await findUp(cwd, '.fleet.local.json'));
+  const config =
+    !named || named === STATE_ROSTER ? STATE_ROSTER : resolve(named);
+  return { workspace, config };
+}

package/src/cli/source-operations.ts

@@ -0,0 +1,102 @@
+import type { Command } from 'commander';
+import type { CommandOutcome } from './contracts';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { Settings } from './settings';
+
+interface SourceOperation {
+  title: string;
+  description: string;
+  keywords: string[];
+  mutation: boolean;
+  command: string[];
+}
+
+/** Commands implemented by another owner in this checkout and streamed through. */
+export const SOURCE_OPERATIONS: Record<string, SourceOperation> = {
+  cliproxy: {
+    title: 'CLIProxyAPI service',
+    description:
+      'Install, inspect, back up, recover and validate model health (model-health, model-suite) of the CLIProxyAPI service.',
+    keywords: ['cliproxy', 'codex', 'proxy', 'compose', 'backup', 'models'],
+    mutation: true,
+    command: ['python3', '-B', 'cliproxy/scripts/cli.py'],
+  },
+};
+
+export function sourceOperation(args: string[]): string | undefined {
+  return args[0] && Object.hasOwn(SOURCE_OPERATIONS, args[0])
+    ? args[0]
+    : undefined;
+}
+
+/** These owners install from Git (a service keeps the commit it runs), so
+ * they run from a checkout: the one this CLI is in, or, for an installed
+ * package, the fleet-owned checkout of the revision fleet-sync applied on
+ * this machine. Null before the first fleet-sync.
+ */
+export function ownerCheckout(
+  workspace: string,
+  home = homedir()
+): string | null {
+  if (existsSync(join(workspace, '.git'))) return workspace;
+  const applied = join(home, '.local/share/personal/fleet/current');
+  return existsSync(join(applied, '.git')) ? applied : null;
+}
+
+const CHECKOUT_REQUIRED =
+  'This command runs from the revision fleet-sync applied on this machine, and none is applied yet. Run devfleet fleet-sync first.\n';
+
+export async function forwardSourceOperation(
+  args: string[],
+  settings: Settings
+): Promise<number> {
+  const operation = SOURCE_OPERATIONS[args[0]!]!;
+  const [runtime, ...ownerArgs] = operation.command;
+  const checkout = ownerCheckout(settings.workspace);
+  if (!checkout) {
+    process.stderr.write(CHECKOUT_REQUIRED);
+    return 1;
+  }
+  const resolved = ownerArgs.map((arg) =>
+    arg.includes('/') ? join(checkout, arg) : arg
+  );
+  return new Promise((resolve) => {
+    const child = spawn(runtime!, [...resolved, ...args.slice(1)], {
+      cwd: checkout,
+      stdio: 'inherit',
+    });
+    child.on('error', () => {
+      process.stderr.write(
+        'This command requires python3 and the toolchain fleet-sync installs.\n'
+      );
+      resolve(1);
+    });
+    child.on('exit', (code) => resolve(code ?? 1));
+  });
+}
+
+export function registerSourceOperations(
+  program: Command,
+  defaults: Settings,
+  complete: (result: CommandOutcome) => void
+): void {
+  for (const [name, operation] of Object.entries(SOURCE_OPERATIONS))
+    program
+      .command(`${name} [args...]`)
+      .description(operation.title)
+      .allowUnknownOption()
+      .addHelpText(
+        'after',
+        `\n${operation.description}\nArguments are forwarded to the owning implementation; run devfleet ${name} help for its usage.`
+      )
+      .action(async (args: string[]) => {
+        const exitCode = await forwardSourceOperation(
+          [name, ...args],
+          defaults
+        );
+        complete({ exitCode, data: { version: 1, ok: exitCode === 0 } });
+      });
+}

package/src/cli/t3/command.ts

@@ -0,0 +1,90 @@
+import { deployment } from '../node-deployment';
+import type { CommandOutcome } from '../contracts';
+import type { Settings } from '../settings';
+import { FleetUsageError } from '../../errors';
+import { desired, nodeId, paths, type T3Options } from '../../t3/desired';
+import { importT3, reconcileT3 } from '../../t3/reconcile';
+
+export async function t3Command(
+  command: string,
+  options: T3Options,
+  settings: Settings
+): Promise<CommandOutcome> {
+  const deployed = options.definition
+    ? null
+    : await deployment(settings.workspace);
+  const workspace = deployed?.workspace ?? settings.workspace;
+  const target = paths(options, workspace);
+  if (command === 't3-apply' && options.import !== undefined)
+    return importCommand(target, options);
+  const instances = await declared(command, target.definition, workspace, {
+    ...options,
+    id: nodeId(options.id ?? deployed?.node),
+  });
+  const apply = shouldApply(command, options);
+  if (apply) requireSupportedPlatform(instances);
+  const data = await reconcileT3(
+    target,
+    instances,
+    reconcileOptions(apply, options)
+  );
+  return {
+    exitCode: outcomeCode(command, data),
+    data: { command, ...data },
+  };
+}
+
+function declared(
+  command: string,
+  definition: string,
+  workspace: string,
+  options: T3Options & { id: string }
+): Promise<Record<string, unknown>> {
+  if (command === 't3-cleanup') return Promise.resolve({});
+  // An explicit definition is the complete instance set.
+  const roster =
+    options.roster ?? (options.definition ? async () => [] : undefined);
+  return desired(definition, workspace, options.id, roster);
+}
+
+async function importCommand(
+  target: ReturnType<typeof paths>,
+  options: T3Options
+): Promise<CommandOutcome> {
+  if (options.dryRun)
+    throw new FleetUsageError(
+      't3-apply --import adopts ownership and cannot be combined with --dry-run; inspect t3-apply --dry-run first.'
+    );
+  if (!options.import || !/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(options.import))
+    throw new FleetUsageError(
+      't3-apply --import expects an instance ID. Import authorizes management of that entire provider instance.'
+    );
+  return {
+    exitCode: 0,
+    data: { command: 't3-import', ...(await importT3(target, options.import)) },
+  };
+}
+
+function reconcileOptions(apply: boolean, options: T3Options) {
+  return {
+    apply,
+    ...(options.planHash ? { planHash: options.planHash } : {}),
+  };
+}
+
+function shouldApply(command: string, options: T3Options): boolean {
+  return ['t3-apply', 't3-cleanup'].includes(command) && !options.dryRun;
+}
+function outcomeCode(
+  command: string,
+  data: { ok: boolean; changed: boolean }
+): number {
+  return !data.ok || (command === 't3-status' && data.changed) ? 1 : 0;
+}
+
+function requireSupportedPlatform(instances: Record<string, unknown>): void {
+  if (process.platform === 'win32' && Object.keys(instances).length)
+    throw new FleetUsageError(
+      'Managed Codex proxy execution requires macOS/Linux/WSL; native Windows settings were preserved.'
+    );
+}

package/src/cli/t3/register.ts

@@ -0,0 +1,55 @@
+import type { Command } from 'commander';
+import type { CommandOutcome } from '../contracts';
+import { resolveSettings, type Settings } from '../settings';
+import { t3Command } from './command';
+import type { T3Options } from '../../t3/desired';
+
+export const T3_COMMANDS = [
+  ['t3-status', 'Check managed T3 configuration for drift'],
+  [
+    't3-apply',
+    'Reconcile declared T3 provider instances; --dry-run plans, --import adopts',
+  ],
+  [
+    't3-cleanup',
+    'Remove only provider instances recorded in personal ownership state',
+  ],
+] as const;
+
+export function registerT3(
+  program: Command,
+  defaults: Settings,
+  complete: (outcome: CommandOutcome) => void
+): void {
+  for (const [name, description] of T3_COMMANDS) {
+    const command = program
+      .command(name)
+      .description(description)
+      .option('--id <name>', 'Node ID; defaults to hostname')
+      .option(
+        '--t3-home <path>',
+        'T3 base directory; defaults to T3CODE_HOME or ~/.t3'
+      )
+      .option(
+        '--definition <path>',
+        'Version 1 declarative T3 provider definition'
+      );
+    if (name !== 't3-status')
+      command
+        .option(
+          '--plan-hash <sha256>',
+          'Reject any changes since the reviewed plan'
+        )
+        .option('--dry-run', 'Preview without writing configuration or state');
+    if (name === 't3-apply')
+      command.option(
+        '--import <id>',
+        'Adopt an existing instance into personal ownership instead of reconciling'
+      );
+    command.action(async (_options, command: Command) => {
+      const options = command.optsWithGlobals<T3Options & Partial<Settings>>();
+      const settings = await resolveSettings({ ...defaults, ...options });
+      complete(await t3Command(name, options, settings));
+    });
+  }
+}