@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/src/cli/tailnet.ts

@@ -0,0 +1,127 @@
+import { workerHealthText } from './worker-health-output';
+import { fleetReference } from './fleet-reference';
+import {
+  managedHealthScope,
+  appendManagerLinks,
+  appendDashboardEvidence,
+} from './managed-health';
+import { discoverTailnet } from '../tailscale';
+import { tailnetHealth } from '../tailnet-health';
+import { makeReport, renderReport, reportExitCode } from '../report';
+import { readRoster } from './roster';
+import { PUBLIC_HUB_URL } from '../monitoring/beszel';
+import { stableUrls } from './fleet-sync-output';
+import { timeout } from './options';
+import type { FleetServices } from './fleet';
+import type { Settings } from './settings';
+import type { CliOptions } from './options';
+import type { CommandOutcome } from './contracts';
+
+export async function executeTailnet(
+  command: string,
+  options: CliOptions,
+  settings: Settings,
+  services: FleetServices
+): Promise<CommandOutcome> {
+  const { tailnet, discovered, registered, coverage } = await healthContext(
+    command,
+    options,
+    settings,
+    services
+  );
+  if (command === 'discover') {
+    const ok = tailnet.checks.every((check) => check.status === 'pass');
+    return {
+      exitCode: ok ? 0 : 1,
+      data: {
+        version: 1,
+        command,
+        ok,
+        coverage,
+        computers: tailnet.computers,
+        checks: tailnet.checks,
+      },
+    };
+  }
+  const nodes = await tailnetHealth(
+    tailnet,
+    registered,
+    {
+      ...(options.workers ? { reference: fleetReference() } : {}),
+      includeManagerReport: options.workers !== true,
+      root: settings.workspace,
+      timeoutMs: timeout({ ...options, timeout: options.timeout ?? '300000' }),
+      source: services.source,
+    },
+    services.run
+  );
+  if (options.managed)
+    await appendManagerLinks(nodes, registered, services.run);
+  // The hub runs on the manager, which worker scope deliberately filters out of
+  // `tailnet`; its visibility comes from the unfiltered discovery.
+  const dashboard = options.workers
+    ? await appendDashboardEvidence(nodes, discovered)
+    : null;
+  const report = makeReport('health', nodes);
+  const exitCode = reportExitCode(report, true);
+  const verified = exitCode === 0;
+  return {
+    exitCode,
+    data: {
+      ...report,
+      ok: verified,
+      ...(options.workers ? { dashboardUrl: publicDashboard(dashboard) } : {}),
+      coverage: {
+        ...coverage,
+        verified,
+        inspected: nodes.filter((node) => node.snapshot).length,
+      },
+    },
+    text: options.workers
+      ? workerHealthText(
+          { ...report, ok: verified },
+          coverage,
+          publicDashboard(dashboard)
+        )
+      : `${stableUrls(renderReport({ ...report, ok: verified }))}\nCoverage: ${coverage.computers} visible computers; ${coverage.excludedMobile} mobile devices excluded.\n${coverage.limitation}`,
+  };
+}
+
+/** Shown to people: the stable public name, never the tailnet address. */
+function publicDashboard(privateHub: string | null): string | null {
+  return privateHub ? PUBLIC_HUB_URL : null;
+}
+
+async function healthContext(
+  command: string,
+  options: CliOptions,
+  settings: Settings,
+  services: FleetServices
+) {
+  const discovered = await discoverTailnet(services.run);
+  const roster =
+    command === 'health' ? await readRoster(settings.config) : null;
+  const registered = roster === null ? [] : roster.nodes;
+  const managed = options.managed
+    ? managedHealthScope(discovered, registered, options.workers !== true)
+    : null;
+  const tailnet = managed === null ? discovered : managed.tailnet;
+  const coverage = {
+    scope: options.workers
+      ? 'canonical-workers'
+      : options.managed
+        ? 'canonical-fleet-and-manager'
+        : 'tailscale-visible-computers',
+    excludedUnmanaged: managed === null ? [] : managed.excluded,
+    computers: tailnet.computers.length,
+    excludedMobile: tailnet.excludedMobile,
+    limitation:
+      'This manager can inspect only devices visible to its Tailscale account/ACLs. Other tailnets, hidden devices and all-pairs connectivity are not verified.',
+  };
+  return {
+    tailnet,
+    discovered,
+    registered: managed === null ? registered : managed.nodes,
+    coverage,
+  };
+}

package/src/cli/ui-actions.ts

@@ -0,0 +1,133 @@
+import type { CommandOutcome, CommandSpec } from './contracts';
+import { execute, showOutcome, successful } from './ui-execute';
+import { clean, reportChecks, reproduction, record } from './ui-data';
+import { inspectChecks, inspectDetails } from './ui-reports';
+import { chooseTargets } from './ui-targets';
+import type { Choice, Session } from './ui-types';
+
+export async function runCommand(
+  session: Session,
+  command: CommandSpec
+): Promise<void> {
+  session.display.panel(clean(command.title), clean(command.description));
+  const args = await actionArgs(session, command);
+  if (!args) return;
+  const preview = isRepair(args);
+  const mutation = !preview && (command.mutation || args.includes('--apply'));
+  if (mutation && !(await confirmMutation(session, args))) return;
+  await runWithResults(session, args, command.title, { preview, mutation });
+}
+
+function isRepair(args: string[]): boolean {
+  return args[0] === 'fleet-repair' && !args.includes('--list');
+}
+
+/** Palette entries with flags are fixed scopes; bare roster commands ask for targets. */
+function targetAction(args: string[]): string | undefined {
+  if (isRepair(args)) return 'repair';
+  if (args[0] === 'fleet-status' && args.length === 1) return 'doctor';
+  if (args[0] === 'fleet-nodes' && args.includes('--onboard')) return 'onboard';
+  return undefined;
+}
+
+async function actionArgs(
+  session: Session,
+  command: CommandSpec
+): Promise<string[] | undefined> {
+  const args = [...command.args];
+  const action = targetAction(args);
+  if (!action) return args;
+  const targets = await chooseTargets(session, action);
+  return targets ? [...args, ...targets] : undefined;
+}
+
+export async function runWithResults(
+  session: Session,
+  initialArgs: string[],
+  title: string,
+  settings: { preview?: boolean; mutation?: boolean } = {}
+): Promise<void> {
+  let args = initialArgs;
+  let outcome = await execute(session, args, title);
+  let preview = settings.preview === true;
+  let mutation = settings.mutation === true;
+  while (true) {
+    showOutcome(session, outcome);
+    const selection = await session.prompts.select(
+      'Next step',
+      resultChoices(outcome, preview)
+    );
+    if (selection === 'back') return;
+    await inspectSelection(session, outcome, selection);
+    if (selection === 'apply') {
+      const appliedArgs = applyArgs(args, outcome);
+      if (!(await confirmMutation(session, appliedArgs))) continue;
+      args = appliedArgs;
+      preview = false;
+      mutation = true;
+      outcome = await execute(session, args, title);
+    }
+    if (selection === 'retry') {
+      if (mutation && !(await confirmMutation(session, args))) continue;
+      outcome = await execute(session, args, title);
+    }
+  }
+}
+
+async function inspectSelection(
+  session: Session,
+  outcome: CommandOutcome,
+  selection: string
+): Promise<void> {
+  if (selection === 'checks') await inspectChecks(session, outcome.data);
+  if (selection === 'details') await inspectDetails(session, outcome.data);
+}
+
+function resultChoices(outcome: CommandOutcome, preview: boolean): Choice[] {
+  return [
+    { name: 'Back to commands', value: 'back' },
+    ...(reportChecks(outcome.data).length
+      ? [{ name: 'Explore checks and remedies…', value: 'checks' }]
+      : []),
+    { name: 'Inspect structured details / plan…', value: 'details' },
+    ...(preview && successful(outcome)
+      ? [{ name: 'Review and explicitly apply…', value: 'apply' }]
+      : []),
+    ...(!successful(outcome)
+      ? [{ name: 'Retry command…', value: 'retry' }]
+      : []),
+  ];
+}
+
+export async function confirmMutation(
+  session: Session,
+  args: string[]
+): Promise<boolean> {
+  const action = args[0];
+  const warning =
+    action === 'fleet-repair'
+      ? 'Repair runs the eligible owner actions in the displayed plan, including trusted setup/install scripts. Workstation actions may read this machine’s Vault session and write managed 0600 provider configuration. No login session is transferred between computers. Failures can leave partial changes; fresh diagnostics follow.'
+      : action === 'fleet-node-add'
+        ? 'This writes the local roster only. No cloud resources, SSH configuration, credentials or host keys are changed.'
+        : 'This command applies changes on invocation as documented in its --help. Failure can leave partial changes; inspect before retrying. No credentials are copied between computers.';
+  session.display.panel(
+    'Explicit approval required',
+    [
+      warning,
+      `Workspace: ${clean(session.workspace ?? session.options.workspace)}`,
+      `Config: ${clean(session.config ?? session.options.config)}`,
+      `$ ${reproduction(session, args)}`,
+    ].join('\n')
+  );
+  return session.prompts.confirm('Apply this exact command? (default: no)');
+}
+
+function applyArgs(args: string[], outcome: CommandOutcome): string[] {
+  const guard =
+    isRepair(args) &&
+    record(outcome.data) &&
+    typeof outcome.data['planHash'] === 'string'
+      ? ['--plan-hash', outcome.data['planHash']]
+      : [];
+  return [...args, ...guard, '--apply', '--yes'];
+}

package/src/cli/ui-controller.ts

@@ -0,0 +1,113 @@
+import type { InteractiveOptions } from './contracts';
+import { releaseLabel } from './program';
+import { runCommand } from './ui-actions';
+import { clean, commandChoices, isCancellation } from './ui-data';
+import { addNode } from './ui-wizard';
+import type { Choice, Display, Prompts, Session } from './ui-types';
+
+export async function runInteractive(
+  options: InteractiveOptions,
+  prompts: Prompts,
+  display: Display
+): Promise<void> {
+  const session: Session = { options, prompts, display };
+  showHeader(session);
+  let running = true;
+  while (running) {
+    try {
+      const choice = await prompts.search(
+        'Command palette · type to search · arrows + enter',
+        (term) => paletteChoices(session, term)
+      );
+      running = await dispatch(session, choice);
+    } catch (error) {
+      if (isCancellation(error)) {
+        display.write('\nGoodbye. No further actions will run.');
+        throw error;
+      }
+      display.write(
+        'The interactive session could not continue safely. Use personal commands --json for noninteractive help.'
+      );
+      throw new Error('Interactive session failed safely.');
+    }
+  }
+  display.write('Goodbye. Session context was not saved.');
+}
+
+function showHeader(session: Session): void {
+  session.display.panel(
+    `personal · ${clean(releaseLabel(session.options))}`,
+    [
+      'Your developer fleet, without the guesswork.',
+      `Workspace: ${clean(session.workspace ?? session.options.workspace)}`,
+      `Config: ${clean(session.config ?? session.options.config)}`,
+      'Read-only first · explicit writes · no automatic repairs',
+      'Search IDs, keywords or descriptions. Ctrl+C exits safely. Nothing is cleared.',
+    ].join('\n')
+  );
+}
+
+export function paletteChoices(session: Session, term: string): Choice[] {
+  const commands = commandChoices(session.options.commands, term);
+  const navigation = [
+    {
+      name: 'Session: Workspace / config…',
+      value: 'context',
+      description: 'Session-only overrides; no hidden configuration writes.',
+    },
+    { name: 'Exit', value: 'exit', description: 'Close the command palette.' },
+  ].filter((choice) =>
+    `${choice.name} ${choice.description}`
+      .toLowerCase()
+      .includes(term.toLowerCase().trim())
+  );
+  const choices = [...navigation, ...commands].sort((a, b) =>
+    a.name.localeCompare(b.name, 'en')
+  );
+  return choices.length
+    ? choices
+    : [{ name: 'No matching commands — change search', value: 'none' }];
+}
+
+async function dispatch(session: Session, choice: string): Promise<boolean> {
+  if (choice === 'exit') return false;
+  if (choice === 'context') await changeContext(session);
+  if (choice.startsWith('command:'))
+    await openCommand(session, choice.slice(8));
+  return true;
+}
+
+async function openCommand(session: Session, id: string): Promise<void> {
+  const command = session.options.commands.find((entry) => entry.id === id);
+  if (!command) return;
+  if (command.id === 'fleet-node-add') await addNode(session);
+  else await runCommand(session, command);
+}
+
+async function changeContext(session: Session): Promise<void> {
+  session.display.write(
+    'Session only. Blank inputs reset to startup defaults; no file is written.'
+  );
+  const workspace = await session.prompts.input(
+    'Workspace override',
+    session.workspace ?? '',
+    validContext
+  );
+  const config = await session.prompts.input(
+    'Config override',
+    session.config ?? '',
+    validContext
+  );
+  if (workspace) session.workspace = workspace;
+  else delete session.workspace;
+  if (config) session.config = config;
+  else delete session.config;
+  showHeader(session);
+}
+
+function validContext(value: string): boolean | string {
+  return (
+    !/[\x00-\x1f\x7f]/.test(value) ||
+    'Control characters are not allowed in paths.'
+  );
+}

package/src/cli/ui-data.ts

@@ -0,0 +1,106 @@
+import type { CommandSpec } from './contracts';
+import type { CheckRow, Choice, Session } from './ui-types';
+import { searchCommands } from './search';
+
+export function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function clean(value: string, limit = 2000): string {
+  return value
+    .replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, '')
+    .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ' ')
+    .slice(0, limit);
+}
+
+export function text(value: unknown, fallback = ''): string {
+  return typeof value === 'string' ? clean(value) : fallback;
+}
+
+export function quote(value: string): string {
+  return /^[a-zA-Z0-9_./:=,@-]+$/.test(value)
+    ? value
+    : `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+export function callArgs(session: Session, args: string[]): string[] {
+  return [
+    ...args,
+    ...(session.workspace ? ['--workspace', session.workspace] : []),
+    ...(session.config ? ['--config', session.config] : []),
+  ];
+}
+
+export function reproduction(session: Session, args: string[]): string {
+  return [
+    'personal',
+    ...args,
+    '--workspace',
+    session.workspace ?? session.options.workspace,
+    '--config',
+    session.config ?? session.options.config,
+    '--json',
+  ]
+    .map(quote)
+    .join(' ');
+}
+
+export function commandChoices(
+  commands: CommandSpec[],
+  term: string
+): Choice[] {
+  return searchCommands(commands, term).map((command) => ({
+    name: `${clean(command.group)}: ${clean(command.title)}`,
+    value: `command:${command.id}`,
+    description: `${clean(command.description)}${command.mutation ? ' · confirmation required' : ''}`,
+  }));
+}
+
+export function reportChecks(data: unknown): CheckRow[] {
+  if (!record(data)) return [];
+  const nodes = Array.isArray(data['nodes']) ? data['nodes'] : [];
+  return [
+    ...nodes.flatMap(nodeChecks),
+    ...nodeChecks({ node: 'tailscale', checks: data['checks'] }),
+  ];
+}
+
+function nodeChecks(value: unknown): CheckRow[] {
+  if (!record(value) || !Array.isArray(value['checks'])) return [];
+  const node = text(value['node'], 'manager');
+  return value['checks'].flatMap((check: unknown) => {
+    if (!record(check) || !isStatus(check['status'])) return [];
+    const remedy = record(check['remedy']) ? check['remedy'] : {};
+    return [
+      {
+        node,
+        id: text(check['id'], 'check'),
+        status: check['status'],
+        summary: text(check['summary']),
+        remedy: text(remedy['action']),
+        command: text(remedy['command']),
+      },
+    ];
+  });
+}
+
+export function isStatus(value: unknown): value is string {
+  return ['pass', 'warn', 'fail', 'skip'].includes(String(value));
+}
+
+export function isCancellation(error: unknown): boolean {
+  if (!record(error)) return false;
+  return ['ExitPromptError', 'AbortPromptError', 'AbortError'].includes(
+    text(error['name'])
+  );
+}
+
+export function absolutePath(value: string): boolean | string {
+  return (
+    (value.startsWith('/') &&
+      value.length <= 4096 &&
+      !/[\x00-\x1f\x7f]/.test(value)) ||
+    'Enter an absolute POSIX path (no ~ or control characters).'
+  );
+}

package/src/cli/ui-execute.ts

@@ -0,0 +1,163 @@
+import type { CommandOutcome } from './contracts';
+import { showRepairs } from './ui-repairs';
+import {
+  callArgs,
+  clean,
+  text,
+  isCancellation,
+  record,
+  reproduction,
+  reportChecks,
+} from './ui-data';
+import type { Session } from './ui-types';
+
+export async function execute(
+  session: Session,
+  args: string[],
+  title: string
+): Promise<CommandOutcome> {
+  session.display.write(`\n$ ${reproduction(session, args)}`);
+  const progress = session.display.progress(title);
+  try {
+    return await session.options.execute(callArgs(session, args));
+  } catch (error) {
+    if (isCancellation(error)) throw error;
+    return { exitCode: 1, data: { ok: false, code: 'operation_failed' } };
+  } finally {
+    progress.stop();
+  }
+}
+
+export function successful(outcome: CommandOutcome): boolean {
+  return (
+    outcome.exitCode === 0 &&
+    !(record(outcome.data) && outcome.data['ok'] === false)
+  );
+}
+
+export function showOutcome(session: Session, outcome: CommandOutcome): void {
+  const checks = reportChecks(outcome.data);
+  const incomplete = checks.filter((check) =>
+    ['warn', 'skip'].includes(check.status)
+  ).length;
+  const state = outcomeState(outcome, incomplete);
+  const counts = ['pass', 'warn', 'fail', 'skip'].map(
+    (status) =>
+      `${checks.filter((check) => check.status === status).length} ${status}`
+  );
+  session.display.panel(
+    state,
+    checks.length ? counts.join(' · ') : outcomeMessage(outcome)
+  );
+  showAttention(session, checks);
+  showData(session, outcome);
+  if (!successful(outcome))
+    session.display.write(
+      record(outcome.data) && outcome.data['applied'] === true
+        ? 'Actions were attempted. Review execution results, partial changes and fresh checks before retrying.'
+        : 'No automatic repair was attempted. Review the command, context and setup.'
+    );
+}
+
+function outcomeMessage(outcome: CommandOutcome): string {
+  if (!successful(outcome)) return failureMessage(outcome.data);
+  if (record(outcome.data) && outcome.data['applied'] === false) {
+    return 'Preview only — no changes applied. Review before explicitly authorizing a write.';
+  }
+  return 'Command completed. Warnings and skipped checks are not passes.';
+}
+
+function failureMessage(data: unknown): string {
+  if (!record(data))
+    return 'Operation failed. Raw errors and subprocess output are intentionally hidden.';
+  if (data['code'] === 'invalid_usage' && typeof data['error'] === 'string')
+    return clean(data['error']);
+  const messages: Record<string, string> = {
+    invalid_usage:
+      'Configuration or arguments need attention. Run fleet-nodes --schema to check the roster, or pass --config.',
+    config_missing:
+      'No roster found. Run fleet-node-add, or run manager-only diagnostics with fleet-status --local.',
+    operation_failed:
+      'Operation failed safely. Check connectivity and configuration before retrying.',
+  };
+  return (
+    messages[String(data['code'])] ??
+    'Operation did not complete. Review setup and the noninteractive command.'
+  );
+}
+
+function showNodes(session: Session, data: Record<string, unknown>): void {
+  const nodes = Array.isArray(data['nodes'])
+    ? data['nodes'].filter(record)
+    : [];
+  if (!nodes.length) {
+    session.display.write(
+      'No computers registered yet. Run fleet-node-add to add one, or fleet-discover to list Tailscale computers.'
+    );
+    return;
+  }
+  session.display.table(
+    ['Computer', 'SSH', 'Workspace'],
+    nodes.map((node) => [
+      text(node['id']),
+      text(node['ssh']),
+      text(node['workspace']),
+    ])
+  );
+}
+
+function showComputers(session: Session, data: Record<string, unknown>): void {
+  const computers = Array.isArray(data['computers'])
+    ? data['computers'].filter(record)
+    : [];
+  session.display.table(
+    ['Computer', 'OS', 'Online'],
+    computers.map((peer) => [
+      text(peer['dns']),
+      text(peer['os']),
+      peer['online'] === true ? 'yes' : 'no',
+    ])
+  );
+  session.display.write(
+    'Visible Tailscale computers only; mobile devices excluded. Register each remote computer with its existing SSH alias and checkout path before full health checks.'
+  );
+}
+
+function showAttention(
+  session: Session,
+  checks: ReturnType<typeof reportChecks>
+): void {
+  const attention = checks.filter((check) => check.status !== 'pass');
+  if (!attention.length) return;
+  session.display.table(
+    ['Computer', 'Check', 'Status / next step'],
+    attention
+      .slice(0, 15)
+      .map((check) => [
+        check.node,
+        check.id,
+        `${check.status}: ${check.remedy ?? check.summary}`,
+      ])
+  );
+  if (attention.length > 15)
+    session.display.write(
+      `Showing 15 of ${attention.length} checks needing attention. Explore checks and remedies for the complete report.`
+    );
+}
+
+function showData(session: Session, outcome: CommandOutcome): void {
+  if (!record(outcome.data)) return;
+  if (['repair', 'repairs'].includes(String(outcome.data['command'])))
+    showRepairs(session, outcome.data);
+  if (successful(outcome) && outcome.data['command'] === 'nodes')
+    showNodes(session, outcome.data);
+  if (outcome.data['command'] === 'discover')
+    showComputers(session, outcome.data);
+}
+
+function outcomeState(outcome: CommandOutcome, incomplete: number): string {
+  if (record(outcome.data) && outcome.data['applied'] === false)
+    return 'PREVIEW';
+  if (!successful(outcome)) return 'FAILED';
+  return incomplete ? 'WARNING' : 'SUCCESS';
+}

package/src/cli/ui-repairs.ts

@@ -0,0 +1,34 @@
+import { record, text } from './ui-data';
+import type { Session } from './ui-types';
+
+export function showRepairs(
+  session: Session,
+  data: Record<string, unknown>
+): void {
+  const catalog = data['command'] === 'repairs';
+  const entries = data[catalog ? 'recipes' : 'steps'];
+  if (!Array.isArray(entries)) return;
+  const steps = entries.filter(record);
+  session.display.table(
+    ['Computer / owner', 'Repair', 'Execution'],
+    steps
+      .slice(0, 15)
+      .map((step) => [
+        text(step[catalog ? 'owner' : 'node']),
+        text(step['title']),
+        step['automatic'] === true && (catalog || step['eligible'] === true)
+          ? 'Owner command after explicit apply'
+          : 'Operator action; inspect instructions',
+      ])
+  );
+  if (steps.length > 15)
+    session.display.write(
+      `Showing 15 of ${steps.length} repair entries. Inspect structured details for the complete plan and native login commands.`
+    );
+  if (!catalog)
+    session.display.write(
+      data['applied'] === true
+        ? `Owner commands completed: ${text(data['completed'])}. Fresh health verified: ${data['healthOk'] === true ? 'yes' : 'no; review remaining checks'}.`
+        : 'Preview only. Review the repair effects and native login instructions in structured details before applying.'
+    );
+}