@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/src/agents/verify-cache.ts

@@ -0,0 +1,103 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { receiptDirectory } from '../platform/ansible-receipt';
+import type { Check } from '../types';
+
+/** A verified inference or agent session is re-proven at least this often. */
+export const VERIFY_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+
+export interface VerifyCache {
+  directory?: string;
+  now?: number;
+  /** Ignore cached results (a live probe failed, or a full check was asked). */
+  bypass?: boolean;
+}
+
+/** Digest of everything a result depends on (never secrets). */
+export function cacheKey(...parts: (string | object)[]): string {
+  const hash = createHash('sha256');
+  for (const part of parts)
+    hash
+      .update(typeof part === 'string' ? part : JSON.stringify(part))
+      .update('\0');
+  return hash.digest('hex');
+}
+
+/** Digest of source files, so a code change re-verifies. */
+export async function sourceKey(paths: string[]): Promise<string> {
+  const hash = createHash('sha256');
+  for (const path of [...paths].sort())
+    hash
+      .update(path)
+      .update('\0')
+      .update(await readFile(path).catch(() => ''));
+  return hash.digest('hex');
+}
+
+/** Warm verification: a passing check with an unchanged key is reused until it
+ * ages out. Only clean passes are stored; a failure, a skip or a quota-limited
+ * pass (`reuse` false) clears the entry so the next sync checks it again.
+ */
+export async function cachedCheck(
+  name: string,
+  key: string,
+  compute: () => Promise<Check>,
+  options: VerifyCache & { reuse?: (check: Check) => boolean } = {}
+): Promise<Check> {
+  const directory = options.directory ?? join(receiptDirectory(), 'verify');
+  const path = join(directory, `${name.replace(/[^a-z0-9-]/gi, '_')}.json`);
+  const now = options.now ?? Date.now();
+  if (!options.bypass) {
+    const hit = await fresh(path, key, now);
+    if (hit) return hit;
+  }
+  const check = await compute();
+  const reusable =
+    check.status === 'pass' && (options.reuse ? options.reuse(check) : true);
+  try {
+    if (!reusable) await rm(path, { force: true });
+    else {
+      await mkdir(directory, { recursive: true, mode: 0o700 });
+      await writeFile(
+        path,
+        JSON.stringify({ version: 1, key, checkedAt: now, check }) + '\n',
+        { mode: 0o600 }
+      );
+    }
+  } catch {
+    /* A missing cache entry only means the next sync verifies again. */
+  }
+  return check;
+}
+
+async function fresh(
+  path: string,
+  key: string,
+  now: number
+): Promise<Check | null> {
+  try {
+    const entry = JSON.parse(await readFile(path, 'utf8')) as {
+      version?: unknown;
+      key?: unknown;
+      checkedAt?: unknown;
+      check?: Check;
+    };
+    if (
+      entry.version !== 1 ||
+      entry.key !== key ||
+      typeof entry.checkedAt !== 'number' ||
+      now - entry.checkedAt < 0 ||
+      now - entry.checkedAt >= VERIFY_MAX_AGE_MS ||
+      entry.check?.status !== 'pass'
+    )
+      return null;
+    const minutes = Math.round((now - entry.checkedAt) / 60_000);
+    return {
+      ...entry.check,
+      summary: `${entry.check.summary} (verified ${minutes}m ago; re-proven every 6h or on any change)`,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/agents/verify.ts

@@ -0,0 +1,127 @@
+import {
+  ProviderVerificationError,
+  providerHttpFailure,
+} from './provider-errors';
+import { registry, type Selection } from './registry';
+import { proxyKey } from './secrets';
+import { VERIFY_OUTPUT_TOKENS } from './round-trip';
+
+export async function verifyProvider(
+  selection: Selection,
+  smoke: boolean,
+  credential?: string
+) {
+  if (selection.profile !== 'proxy')
+    return {
+      static: 'pass',
+      reachability: 'unverified',
+      authenticatedModels: 'unverified',
+      inference: 'unverified',
+      streaming: 'unverified',
+      toolCalls: 'unverified',
+      t3EndToEnd: 'unverified',
+    };
+  const key = credential ?? (await proxyKey());
+  const headers = {
+    Authorization: `Bearer ${key}`,
+    'Content-Type': 'application/json',
+  };
+  const response = await fetch(registry.proxy.endpoint + '/v1/models', {
+    headers,
+    redirect: 'error',
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!response.ok) throw providerHttpFailure(response.status);
+  const data = (await response.json()) as { data?: Array<{ id: string }> };
+  if (!data.data?.some((model) => model.id === selection.model))
+    throw new ProviderVerificationError(
+      'PROVIDER_MODEL_UNAVAILABLE',
+      'Approved model is unavailable; review registry model selection.'
+    );
+  let inference = 'unverified';
+  if (smoke) {
+    const { path, body } = inferenceRequest(selection);
+    const result = await fetch(registry.proxy.endpoint + path, {
+      method: 'POST',
+      headers: {
+        ...headers,
+        'anthropic-version': '2023-06-01',
+        'x-goog-api-key': key,
+      },
+      body: JSON.stringify(body),
+      redirect: 'error',
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (!result.ok) throw providerHttpFailure(result.status);
+    await validateOutput(result, selection.tool);
+    inference = 'pass';
+  }
+  return {
+    static: 'pass',
+    reachability: 'pass',
+    authenticatedModels: 'pass',
+    inference,
+    streaming: 'unverified',
+    toolCalls: 'unverified',
+    t3EndToEnd: 'unverified',
+  };
+}
+
+async function validateOutput(
+  result: Response,
+  tool: Selection['tool']
+): Promise<void> {
+  const payload = (await result.json()) as {
+    content?: unknown[];
+    output?: unknown[];
+    error?: unknown;
+    candidates?: unknown[];
+  };
+  const output =
+    tool === 'gemini' || tool === 'antigravity'
+      ? payload.candidates
+      : tool === 'claude'
+        ? payload.content
+        : payload.output;
+  if (payload.error || !Array.isArray(output) || output.length === 0)
+    throw new ProviderVerificationError(
+      'PROVIDER_OUTPUT_UNVERIFIED',
+      'Inference returned no output; inspect the provider locally.'
+    );
+}
+
+/** Exact pinned clients use different wire protocols; model discovery is not inference.
+ * Output uses the same ceiling as the round trip: reasoning models (Muse) spend
+ * dozens of tokens before any text, so a tiny cap returns an empty output.
+ */
+export function inferenceRequest(selection: Selection): {
+  path: string;
+  body: object;
+} {
+  // Antigravity's CLI speaks the same Gemini generateContent protocol.
+  if (selection.tool === 'gemini' || selection.tool === 'antigravity')
+    return {
+      path: `/v1beta/models/${encodeURIComponent(selection.model)}:generateContent`,
+      body: {
+        contents: [{ role: 'user', parts: [{ text: 'Reply OK.' }] }],
+        generationConfig: { maxOutputTokens: VERIFY_OUTPUT_TOKENS },
+      },
+    };
+  if (selection.tool === 'claude')
+    return {
+      path: '/v1/messages',
+      body: {
+        model: selection.model,
+        max_tokens: VERIFY_OUTPUT_TOKENS,
+        messages: [{ role: 'user', content: 'Reply OK.' }],
+      },
+    };
+  return {
+    path: '/v1/responses',
+    body: {
+      model: selection.model,
+      max_output_tokens: VERIFY_OUTPUT_TOKENS,
+      input: 'Reply OK.',
+    },
+  };
+}

package/src/auth-checks.ts

@@ -0,0 +1,163 @@
+import { resolveVaultConfig, usesVault } from './vault-config';
+import { fleet as definition } from './fleet-config';
+import { workerReadiness } from './worker-readiness';
+import { record } from './config';
+import { codingAuth, serviceAuth } from './service-auth';
+import { workstationChecks } from './workstation-checks';
+import { toolchainChecks } from './toolchain-checks';
+import type { Capability, Check, Runner, CommandResult } from './types';
+
+export async function authCheck(
+  capability: Capability,
+  run: Runner,
+  root: string,
+  nodeId?: string
+): Promise<Check[]> {
+  if (capability === 'worker') return workerReadiness(run, nodeId, root);
+  if (capability === 't3') return t3Checks(run, nodeId !== undefined);
+  if (capability === 'codex' || capability === 'claude')
+    return codingAuth(capability, run);
+  if (capability === 'services') return serviceAuth(run);
+  if (capability === 'workstation') return workstationChecks(root, run);
+  if (capability === 'toolchain')
+    return toolchainChecks(
+      root,
+      run,
+      definition.workers.some((node) => node.id === nodeId)
+    );
+  return basicAuth(capability, run, root);
+}
+
+async function basicAuth(
+  capability: 'github' | 'vault' | 'vscode',
+  run: Runner,
+  root: string
+): Promise<Check[]> {
+  const spec = {
+    github: {
+      command: ['gh', 'auth', 'status', '--active'],
+      action:
+        'Authenticate on this node with gh auth login, then gh auth setup-git.',
+    },
+    vault: {
+      command: [
+        'vault',
+        'token',
+        'lookup',
+        '-format=json',
+        `-address=${usesVault() ? resolveVaultConfig().addr : ''}`,
+      ],
+      action:
+        'Authenticate to the configured Vault on this node. Do not copy a token from another computer.',
+    },
+    vscode: {
+      command: ['code', '--list-extensions'],
+      action:
+        'Install the VS Code CLI on PATH and ms-vscode-remote.remote-ssh in the local editor profile.',
+    },
+  }[capability];
+  const result = await run(spec.command, {
+    cwd: root,
+    timeoutMs: 15_000,
+  });
+  const extensions = result.stdout.toLowerCase().split(/\s+/);
+  const ok =
+    result.ok &&
+    (capability !== 'vscode' ||
+      extensions.includes('ms-vscode-remote.remote-ssh'));
+  return [
+    {
+      id: `auth:${capability}`,
+      status: ok ? 'pass' : 'fail',
+      summary: ok
+        ? `${capability} check succeeded in this process context.`
+        : `${capability} check failed (${result.reason}); no credential output retained.`,
+      ...(ok ? {} : { remedy: { action: spec.action } }),
+    },
+  ];
+}
+
+async function t3Checks(
+  run: Runner,
+  managerChecksLinks = false
+): Promise<Check[]> {
+  const t3 = await t3Executable(run);
+  const config = await run([t3, 'status', '--json']);
+  const checks: Check[] = [t3Settings(config)];
+  const live = await run([t3, 'environment', 'list', '--json']);
+  checks.push({
+    id: 't3:api',
+    status: live.ok ? 'pass' : 'fail',
+    summary: live.ok
+      ? 'Local T3 API answered a read-only environment listing; peer connectivity is not inferred.'
+      : 'Local T3 API did not answer the environment listing.',
+    ...(!live.ok
+      ? {
+          remedy: {
+            action:
+              'Check t3 service status and t3 status. Inspect linked peers in T3 Settings → Connections; relink only with operator approval.',
+          },
+        }
+      : {}),
+  });
+  if (!managerChecksLinks)
+    checks.push({
+      id: 't3:end-to-end',
+      status: 'skip',
+      summary:
+        'Relay traversal and remote peer authorization require an operator connection test; local settings are not proof.',
+    });
+  return checks;
+}
+
+/** Workers run only the T3 desktop app, so no `t3` launcher need be on PATH.
+ * Fall back to the newest pinned native CLI the shared installer verified.
+ */
+async function t3Executable(run: Runner): Promise<string> {
+  const found = await run(
+    [
+      'sh',
+      '-c',
+      'command -v t3 || ls -d "$HOME"/.local/share/personal/tools/t3-*/t3 2>/dev/null | sort -V | tail -n 1',
+    ],
+    { timeoutMs: 5000 }
+  );
+  const path = found.ok ? (found.stdout.trim().split('\n').pop() ?? '') : '';
+  return /^\/[\x21-\x7e]+$/.test(path) ? path : 't3';
+}
+
+function t3Settings(config: CommandResult): Check {
+  const fallback: Check = {
+    id: 't3:settings',
+    status: 'fail',
+    summary: 'T3 settings unavailable or unsupported CLI response.',
+    remedy: {
+      action:
+        'Run t3 status --json on this node. Complete t3 up --connect as its operator if needed.',
+    },
+  };
+  try {
+    const data: unknown = JSON.parse(config.stdout);
+    if (config.ok && record(data) && record(data['connect'])) {
+      const enabled =
+        data['connect']['enabled'] === true &&
+        data['connect']['revoked'] === false;
+      return {
+        id: 't3:settings',
+        status: enabled ? 'pass' : 'fail',
+        summary: enabled
+          ? 'T3 Connect enabled and not marked revoked (settings only).'
+          : 'T3 Connect disabled, revoked, or unknown.',
+        ...(!enabled
+          ? {
+              remedy: {
+                action:
+                  'Review t3 status, then complete t3 up --connect as the operator. Never share pairing tokens.',
+              },
+            }
+          : {}),
+      };
+    }
+  } catch {}
+  return fallback;
+}

package/src/cli/agent-guide.ts

@@ -0,0 +1,95 @@
+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.',
+  '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 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',
+];
+
+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',
+    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-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:
+        '--workspace PATH, PERSONAL_WORKSPACE, closest ancestor mise.toml, then current directory',
+      roster:
+        '--config PATH, PERSONAL_FLEET_CONFIG, closest ancestor .fleet.local.json, then ~/.config/personal/fleet.json',
+    },
+    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,
+    fleetSync: {
+      command: 'devfleet fleet-sync',
+      preview: 'devfleet fleet-sync --dry-run --json',
+      approval: 'Applies on invocation without a prompt; --dry-run previews',
+      scope:
+        'Whole enrolled Ubuntu fleet over verified SSH; --node filters diagnostics/rollout',
+      state: '~/.local/share/personal/fleet/manager/enrollment.json',
+      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,115 @@
+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 manifest from '../../package.json';
+
+/** The manifest carries `0.0.0-development` in the repository; the release
+ * workflow stamps the tag's version into the package it publishes.
+ */
+export const VERSION = manifest.version;
+const RELEASE = { version: VERSION, releasedAt: null };
+
+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,21 @@
+#!/usr/bin/env node
+import { main } from './app';
+
+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,50 @@
+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 (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' };
+}