@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/src/cli/agent-guide.ts

@@ -0,0 +1,129 @@
+import type { Release } from './program';
+
+const SAFETY = [
+  'No arguments prints help, including on a TTY. --json returns this document. The menu requires --interactive; --json and --non-interactive never prompt.',
+  'Diagnostics, onboarding instructions, schema, catalogs, scripts and repair previews are read-only.',
+  'fleet-sync, fleet-node-sync, t3-apply and t3-cleanup apply by invocation; --dry-run previews. t3-apply --import ID explicitly adopts ownership. --json never implies a dry run. fleet-node-add and fleet-repair require --apply --yes.',
+  'fleet-state alone is read-only; --init, --import, --push and --restore each act on invocation. Bucket credentials come from DEVFLEET_BUCKET_ACCESS_KEY_ID and DEVFLEET_BUCKET_SECRET_ACCESS_KEY or a terminal prompt, never from arguments.',
+  'Do not copy credentials, forward SSH agents, bypass host keys, provision infrastructure or execute unreviewed remedies.',
+  'A healthy manager does not prove another machine can connect to it. Run fleet-status from each intended manager.',
+  'fleet-repair executes only allowlisted owner actions, then reruns diagnostics. Native logins, host trust and resource permissions remain explicit operator steps. Pass the reviewed planHash as --plan-hash to reject a changed plan.',
+  'Shared provider keys are fetched through each machine’s existing Vault authorization by workstation tooling. Never copy machine-local login caches.',
+  'Use exact npm versions for automation. The application never self-updates.',
+];
+
+const EXAMPLES = [
+  'devfleet fleet-node-sync',
+  'devfleet fleet-status',
+  'devfleet fleet-state --json',
+  'devfleet t3-status',
+  'devfleet fleet-status --local --workspace /path/to/personal --json',
+  'devfleet fleet-status --json --strict --timeout 120000',
+  'devfleet fleet-status --tailnet --json',
+  'devfleet fleet-status --workers --json',
+  'devfleet fleet-node-add --id dev-linux --ssh dev-linux --path /home/dev/workspace --require github,t3,toolchain --json',
+  'devfleet fleet-node-add --id dev-linux --ssh dev-linux --path /home/dev/workspace --apply --yes --json',
+  'devfleet fleet-status --node dev-linux --json',
+  'devfleet fleet-repair --list --json',
+  'devfleet fleet-repair --json',
+  'devfleet fleet-repair --local --repair workspace --json',
+  'devfleet fleet-repair --local --repair workspace --plan-hash <reviewed-sha256> --apply --yes --json',
+];
+
+/** For an agent working in another project, which is every project that uses
+ * dev-fleet: a change to dev-fleet is asked for, never made in place.
+ */
+function support(release: Release) {
+  return {
+    issues: release.issues ?? null,
+    report:
+      'A defect in dev-fleet, or something it cannot do yet, is raised as an issue in the dev-fleet repository: one issue per bug or feature request, after searching the open ones. From any other project that is the only way to change dev-fleet. Tell the operator what is blocked and link the issue.',
+    never:
+      'Do not edit the installed package, a checkout fleet-sync owns or a file dev-fleet manages on a machine: the next install or fleet-sync replaces each of them. Do not clone dev-fleet to patch it, vendor a modified copy, or hide the defect behind a workaround in the project that holds fleet.json.',
+    include:
+      'devfleet --version, the command and its flags, the error code or the failing check IDs from --json, what happened and what was expected.',
+    withhold:
+      'The issue tracker is public. Leave out credentials, the fleet configuration, hostnames, accounts, domains, tailnet names, paths under a home directory and raw subprocess output.',
+  };
+}
+
+export function agentGuide(release: Release) {
+  return {
+    version: 1,
+    name: 'dev-fleet',
+    release: release.version,
+    releasedAt: release.releasedAt,
+    invocation: 'devfleet <command> --json --non-interactive',
+    discovery: 'devfleet commands --json',
+    setup:
+      'Setting up a fleet from a project: llms.txt and docs/consumer-setup.md in this package (node_modules/@crvouga/dev-fleet/), also at https://github.com/crvouga/dev-fleet/blob/main/docs/consumer-setup.md',
+    defaultCommand: 'help',
+    help: 'devfleet <command> --help',
+    interactive:
+      'devfleet --interactive (explicit opt-in; TTY required, disabled in CI)',
+    groups: {
+      'fleet-*':
+        'Developer computers: fleet-status, fleet-discover, fleet-sync, fleet-state, fleet-node-sync, fleet-repair, fleet-nodes, fleet-node-add',
+      't3-*': 'Declared T3 provider instances: t3-status, t3-apply, t3-cleanup',
+      cliproxy: 'The CLI proxy service on the manager; arguments are forwarded',
+    },
+    configuration: {
+      workspace:
+        'The published package itself. Run from a checkout (development): --workspace PATH, PERSONAL_WORKSPACE, then the dev-fleet checkout the command is started in',
+      roster:
+        '--config PATH, PERSONAL_FLEET_CONFIG, closest ancestor .fleet.local.json, then the roster in the fleet state',
+      definition:
+        'DEVFLEET_CONFIG, then the closest fleet.json in the working directory or above it (the operator’s project), then the configuration fleet-sync last applied from the fleet state (the devfleet CLI on the manager), then the copy fleet-sync installed at ~/.config/dev-fleet/fleet.json',
+      state:
+        'DEVFLEET_STATE or ~/.local/share/dev-fleet/state: a local copy of the roster, the approved revision and the configuration last applied. The bucket named under "state" in the fleet configuration is the source of truth; its credentials are passed in DEVFLEET_BUCKET_ACCESS_KEY_ID and DEVFLEET_BUCKET_SECRET_ACCESS_KEY, or saved by devfleet fleet-state --init in ~/.config/dev-fleet/bucket.json for unattended runs. devfleet fleet-state --json compares the copies',
+      revision:
+        'The commit the published package names (devfleet --version). fleet-sync converges every machine to it; --revision SHA selects another',
+    },
+    output: {
+      stdout:
+        'Public diagnostics emit one versioned JSON document with --json. cliproxy retains its owner output contract; native agent launch commands stream native output.',
+      exitCodes: {
+        '0': 'Success or preview',
+        '1': 'Failed check or operation; strict also rejects warnings/skips',
+        '2': 'Invalid usage or configuration',
+        '130': 'Cancelled',
+      },
+      errors:
+        '{version:1,ok:false,code,error}; raw subprocess output and exception details are withheld',
+      reports:
+        '{version:1,command,ok,generatedAt,nodes:[{node,checks:[{id,status,summary,remedy?}]}],summary,coverage}',
+      statuses: ['pass', 'warn', 'fail', 'skip'],
+      coverage:
+        'Default fleet-status tests the manager and all configured nodes. --local tests only this manager; --tailnet and --workers cover Tailscale computers. A missing roster fails explicitly. T3/VS Code end-to-end checks remain manual.',
+    },
+    safety: SAFETY,
+    support: support(release),
+    toolchain:
+      'On a fleet machine the global mise configuration belongs to dev-fleet: fleet-sync publishes it, and fleet-status fails tool:global-mise-config when anything replaced it. A project pins its own tools in a project mise.toml (mise install --locked in its checkout) and never publishes a global one.',
+    library:
+      'None. The package is the devfleet command: it declares no main or exports, and nothing under src/ is a supported import; any release may change it. Ask for a command in an issue instead.',
+    fleetSync: {
+      command: 'devfleet fleet-sync',
+      preview: 'devfleet fleet-sync --dry-run --json',
+      approval:
+        'Applies on invocation without a prompt; --dry-run previews and changes no machine: on the manager it only checks the release out into dev-fleet’s cache and installs the Bun it pins, never the toolchain, the global mise configuration or shell profiles',
+      scope:
+        'Whole enrolled Ubuntu fleet over verified SSH; --node filters diagnostics/rollout',
+      state:
+        'The approved and applied revision are kept in the fleet state and uploaded to its bucket after every run; the report carries the state:replica check',
+      readiness:
+        'Full Ubuntu acceptance is incomplete and fails closed; do not override it or claim deployment success.',
+    },
+    reconciliation: {
+      plan: 'devfleet t3-apply --dry-run --json',
+      apply: 'devfleet t3-apply --plan-hash HASH',
+      cleanup: 'devfleet t3-cleanup --dry-run',
+      import: 'devfleet t3-apply --import ID',
+      ownership:
+        'Only declared or explicitly imported T3 instances. Pairing, credentials, threads and unrelated settings are preserved.',
+      concurrency:
+        'Exclusive personal lock with optimistic external T3 file updates; avoid concurrent Settings edits.',
+    },
+    examples: EXAMPLES,
+  };
+}

package/src/cli/app.ts

@@ -0,0 +1,122 @@
+import { sourceOperation, forwardSourceOperation } from './source-operations';
+import { resolveSettings, type Settings } from './settings';
+import { COMMANDS } from './registry';
+import { execute } from './program';
+import { parseArgs } from 'node:util';
+import { packageInfo } from '../package-info';
+
+/** The manifest carries `0.0.0-development` in the repository; the release
+ * workflow stamps the tag's version, and the commit, into the package it
+ * publishes.
+ */
+const PACKAGE = packageInfo();
+export const VERSION = PACKAGE.version;
+const RELEASE = {
+  version: VERSION,
+  releasedAt: null,
+  revision: PACKAGE.revision,
+  issues: PACKAGE.issues,
+};
+
+export function wantsInteractive(
+  args: string[],
+  terminal: boolean,
+  ci: boolean
+): boolean {
+  if (args.includes('--json') || args.includes('--non-interactive'))
+    return false;
+  return terminal && !ci && args.includes('--interactive') && contextOnly(args);
+}
+
+function startup(args: string[]) {
+  return parseArgs({
+    args,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      workspace: { type: 'string' },
+      config: { type: 'string' },
+      interactive: { type: 'boolean' },
+      json: { type: 'boolean' },
+      'non-interactive': { type: 'boolean' },
+    },
+  });
+}
+
+function contextOnly(args: string[]): boolean {
+  const parsed = startup(args);
+  return (
+    parsed.positionals.length === 0 &&
+    Object.keys(parsed.values).every((key) =>
+      ['workspace', 'config', 'interactive'].includes(key)
+    )
+  );
+}
+
+export async function main(args = process.argv.slice(2)): Promise<number> {
+  const { values } = startup(args);
+  const settings = await resolveSettings({
+    ...(typeof values.workspace === 'string'
+      ? { workspace: values.workspace }
+      : {}),
+    ...(typeof values.config === 'string' ? { config: values.config } : {}),
+  });
+  const forwarded = forwardOwner(args, settings);
+  if (forwarded) return forwarded;
+  const terminal = interactiveTerminal();
+  if (args.includes('--interactive') && !terminal) {
+    process.stdout.write(
+      `${JSON.stringify({ version: 1, ok: false, code: 'tty_required', error: 'Interactive mode needs a terminal. Use personal commands --json or fleet-status --local --json.' })}\n`
+    );
+    return 2;
+  }
+  if (wantsInteractive(args, terminal, Boolean(process.env['CI']))) {
+    const { startInteractive } = await import('./ui');
+    await startInteractive({
+      ...settings,
+      ...RELEASE,
+      commands: COMMANDS,
+      execute: (command) => execute(command, settings, RELEASE),
+    });
+    return 0;
+  }
+  const outcome = await execute(
+    args.filter((arg) => arg !== '--interactive'),
+    settings,
+    RELEASE
+  );
+  const text = args.includes('--json')
+    ? JSON.stringify(outcome.data, null, 2)
+    : (outcome.text ?? JSON.stringify(outcome.data, null, 2));
+  process.stdout.write(`${text}\n`);
+  return outcome.exitCode;
+}
+
+function interactiveTerminal(): boolean {
+  return process.stdin.isTTY === true && process.stderr.isTTY === true;
+}
+
+function forwardOwner(
+  args: string[],
+  settings: Settings
+): Promise<number> | undefined {
+  const ownerArgs = stripOwnerWorkspace(args);
+  if (sourceOperation(ownerArgs))
+    return forwardSourceOperation(ownerArgs, settings);
+  return undefined;
+}
+
+export function stripOwnerWorkspace(args: string[]): string[] {
+  const forwarded: string[] = [];
+  let child = false;
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]!;
+    if (arg === '--') child = true;
+    if (!child && arg === '--workspace') {
+      index++;
+      continue;
+    }
+    forwarded.push(arg);
+  }
+  return forwarded;
+}

package/src/cli/cli.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { main } from './app';
+import { useProjectConfig } from './project';
+import { actAsOperator } from '../state/operator';
+import { databasePath } from '../state/paths';
+import { readDocument } from '../state/store';
+
+actAsOperator((root) => readDocument(databasePath(root), 'definition'));
+useProjectConfig();
+
+try {
+  process.exitCode = await main();
+} catch (error) {
+  const cancelled =
+    error instanceof Error &&
+    ['ExitPromptError', 'AbortPromptError'].includes(error.name);
+  process.stdout.write(
+    `${JSON.stringify({
+      version: 1,
+      ok: false,
+      code: cancelled ? 'cancelled' : 'operation_failed',
+      error: cancelled
+        ? 'Cancelled; no further actions will run.'
+        : 'Command failed. Inspect the local setup; raw errors are withheld to protect credentials.',
+    })}\n`
+  );
+  process.exitCode = cancelled ? 130 : 1;
+}

package/src/cli/command-index.ts

@@ -0,0 +1,57 @@
+import { SOURCE_OPERATIONS } from './source-operations';
+import { commandCatalog } from './registry';
+import type { CommandSpec } from './contracts';
+
+const APPLIES = new Set(['fleet-node-sync', 't3-apply', 't3-cleanup']);
+
+/** Additive machine-readable discovery; the registry also drives the menu. */
+export function indexedCommands(search = '', group?: string) {
+  return commandCatalog(search, group).map((entry) => ({
+    ...entry,
+    help: `devfleet ${entry.args.join(' ')} --help`,
+    execution: execution(entry),
+  }));
+}
+
+function execution(entry: CommandSpec) {
+  if (Object.hasOwn(SOURCE_OPERATIONS, entry.id))
+    return {
+      default: 'depends-on-subcommand',
+      authorization: 'owner-specific; inspect leaf help before invocation',
+      requirements: ['dev-fleet checkout and its toolchain'],
+      note: 'Streams the owner protocol. JSON and mutation flags depend on the leaf operation.',
+    };
+  if (entry.id === 'fleet-sync')
+    return {
+      default: 'interactive-confirmation-or-action-required',
+      authorization: 'interactive-confirmation or --apply --yes',
+      preview: 'devfleet fleet-sync --dry-run --json',
+      scope:
+        'enrolled Ubuntu fleet over verified SSH; manager is not an implicit target',
+      note: 'JSON/noninteractive never prompt. Full Ubuntu acceptance is not yet implemented.',
+    };
+  if (entry.mutation && entry.id.startsWith('fleet-state '))
+    return {
+      default: 'apply',
+      authorization: 'command-invocation',
+      preview: 'devfleet fleet-state --json',
+      note: 'Each flag is one explicit action on this manager’s fleet state. JSON selects output format; it does not prevent writes.',
+    };
+  if (APPLIES.has(entry.id))
+    return {
+      default: 'apply',
+      authorization: 'command-invocation',
+      preview: `devfleet ${entry.id} --dry-run --json`,
+      note:
+        entry.id === 't3-apply'
+          ? '--import ID adopts an existing instance without reconciling. JSON selects output format; it does not prevent writes.'
+          : 'JSON selects output format; it does not prevent writes.',
+    };
+  if (entry.mutation)
+    return {
+      default: 'preview',
+      authorization: '--apply --yes',
+      note: 'Supply required options shown by command --help. A preview does not apply changes.',
+    };
+  return { default: 'read-only', authorization: 'none' };
+}

package/src/cli/contracts.ts

@@ -0,0 +1,25 @@
+export interface CommandSpec {
+  id: string;
+  title: string;
+  description: string;
+  group: string;
+  keywords: string[];
+  args: string[];
+  examples: string[];
+  mutation: boolean;
+}
+
+export interface CommandOutcome {
+  exitCode: number;
+  data: unknown;
+  text?: string;
+}
+
+export interface InteractiveOptions {
+  version: string;
+  releasedAt: string | null;
+  workspace: string;
+  config: string;
+  commands: CommandSpec[];
+  execute: (args: string[]) => Promise<CommandOutcome>;
+}

package/src/cli/fleet-reference.ts

@@ -0,0 +1,17 @@
+import type { Fingerprint, Snapshot } from '../types';
+
+declare const PERSONAL_FLEET_REFERENCE: Fingerprint | null | undefined;
+/** Published health carries safe input hashes; it needs no manager checkout or Bun. */
+export function fleetReference(): Snapshot | undefined {
+  if (
+    typeof PERSONAL_FLEET_REFERENCE === 'undefined' ||
+    !PERSONAL_FLEET_REFERENCE?.head
+  )
+    return undefined;
+  return {
+    version: 1,
+    platform: 'declared-worker-policy',
+    fingerprint: PERSONAL_FLEET_REFERENCE,
+    checks: [],
+  };
+}