vibecarbon 0.1.0

package/src/diagnose.js

@@ -0,0 +1,735 @@
+/**
+ * `vibecarbon diagnose [env] [section]`
+ *
+ * One-command full cluster state dump. Writes a timestamped report to
+ * ~/.vibecarbon/diag-<env>-<ts>.txt and tees a summary to stdout. Companion
+ * to `vibecarbon shell` — when something is wrong, this is the single
+ * command that gathers every signal that's
+ * helped diagnose past failures (node IPs, CoreDNS config, Flux state,
+ * pod-level DNS probes, hcloud resource state).
+ *
+ * Sections:
+ *   nodes    — kubectl get nodes -o wide + ssh systemctl status k3s
+ *              + journalctl -u k3s + ip addr + dmesg via SSH
+ *   pods     — kubectl get pods -A, describe non-Running pods, logs for
+ *              crashlooping pods
+ *   network  — CoreDNS configmap + logs, Flannel + kube-proxy logs,
+ *              hcloud-ccm + hcloud-csi logs, in-cluster busybox DNS probe
+ *   flux     — kubectl -n flux-system get gitrepository,kustomization,
+ *              helmrelease + describe + controller logs
+ *   hcloud   — server/network/firewall/floating-ip/PG/SSH-key list
+ *   all      — every section (default)
+ *
+ * Each probe is wrapped so a failure in one section doesn't prevent the
+ * others from running — partial output is far more useful than nothing.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { renderHelp } from './lib/cli/help.js';
+import { parseFlags } from './lib/cli/parse-flags.js';
+import { c } from './lib/colors.js';
+import { loadProjectConfig } from './lib/config.js';
+import { ensureOperatorIpAccess } from './lib/operator-ip.js';
+import { assertInProjectDir } from './lib/project-guard.js';
+
+// Sections that run as part of `diagnose all`. Egress is intentionally
+// excluded — its netshoot image pull + multi-probe battery can take 30-60s,
+// which is fine for an explicit `diagnose <env> egress` invocation but
+// disproportionate for the default sweep.
+const SECTIONS = ['nodes', 'pods', 'network', 'flux', 'hcloud'];
+const OPTIONAL_SECTIONS = ['egress'];
+const ALL_VALID_SECTIONS = [...SECTIONS, ...OPTIONAL_SECTIONS];
+
+/** @type {import('./lib/cli/parse-flags.js').CommandSpec & { summary?: string, description?: string, examples?: Array<{ command: string, description?: string }> }} */
+const SPEC = {
+  name: 'diagnose',
+  summary: 'Dump full cluster state for an environment',
+  description: [
+    'Streams sections to stdout AND writes the full report to:',
+    '  ~/.vibecarbon/diag-<env>-<timestamp>.txt',
+  ].join('\n'),
+  positional: [
+    {
+      name: 'env',
+      optional: true,
+      description: 'Environment to inspect (default: prod)',
+    },
+    {
+      name: 'section',
+      optional: true,
+      description: `One of: ${ALL_VALID_SECTIONS.join(', ')}, all (default: all — excludes egress)`,
+    },
+  ],
+  flags: [{ name: 'h', boolean: true, description: 'Show this help' }],
+  examples: [
+    { command: 'vibecarbon diagnose e3', description: 'full dump (excludes heavy egress probe)' },
+    { command: 'vibecarbon diagnose e3 network', description: 'CoreDNS + CCM + DNS probe' },
+    {
+      command: 'vibecarbon diagnose e3 egress',
+      description: 'netshoot DNS + MTU + route battery',
+    },
+    { command: 'vibecarbon diagnose e3 flux', description: 'just Flux state' },
+  ],
+};
+
+function loadHcloudToken() {
+  const credPath = join(homedir(), '.vibecarbon', 'credentials.json');
+  if (!existsSync(credPath)) return null;
+  try {
+    const data = JSON.parse(readFileSync(credPath, 'utf-8'));
+    return data?.hetzner?.apiToken ?? data?.hetznerApiToken ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run a command, returning { ok, stdout, stderr }. Never throws —
+ * failures get captured into stderr/exitCode so a single broken command
+ * doesn't break the whole report.
+ */
+function safeRun(cmd, args, env) {
+  try {
+    const out = execFileSync(cmd, args, {
+      env,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 60_000,
+    });
+    return { ok: true, stdout: out, stderr: '' };
+  } catch (err) {
+    return {
+      ok: false,
+      stdout: err?.stdout?.toString() ?? '',
+      stderr: err?.stderr?.toString() ?? err?.message ?? String(err),
+    };
+  }
+}
+
+class Report {
+  constructor() {
+    this.lines = [];
+  }
+  section(title) {
+    const banner = `\n${'='.repeat(72)}\n  ${title}\n${'='.repeat(72)}\n`;
+    this.lines.push(banner);
+    console.log(banner);
+  }
+  subsection(title) {
+    const banner = `\n--- ${title} ---`;
+    this.lines.push(banner);
+    console.log(banner);
+  }
+  command(label, cmd, args) {
+    this.lines.push(`\n# $ ${cmd} ${args.join(' ')}  (${label})`);
+    console.log(c.dim(`# $ ${cmd} ${args.join(' ')}`));
+  }
+  output(text) {
+    if (!text) return;
+    this.lines.push(text.trimEnd());
+    process.stdout.write(text);
+    if (!text.endsWith('\n')) process.stdout.write('\n');
+  }
+  warn(text) {
+    const line = `${c.warning('!')} ${text}`;
+    this.lines.push(`! ${text}`);
+    console.log(line);
+  }
+  toString() {
+    return this.lines.join('\n');
+  }
+}
+
+/**
+ * Run a command, push it to the report with a label, and dump output.
+ */
+function probe(report, label, cmd, args, env) {
+  report.command(label, cmd, args);
+  const r = safeRun(cmd, args, env);
+  if (r.ok) {
+    report.output(r.stdout);
+  } else {
+    report.output(r.stdout);
+    report.warn(`${cmd} ${args.join(' ')} failed: ${r.stderr.split('\n')[0]}`);
+  }
+}
+
+function diagnoseHcloud(report, env) {
+  report.section('HCLOUD RESOURCES');
+  for (const kind of [
+    'server',
+    'network',
+    'firewall',
+    'floating-ip',
+    'placement-group',
+    'ssh-key',
+  ]) {
+    probe(report, kind, 'hcloud', [kind, 'list'], env);
+  }
+}
+
+function diagnoseNodes(report, env, kubeconfig, sshKey, controlplaneIp) {
+  report.section('NODES');
+  probe(
+    report,
+    'nodes wide',
+    'kubectl',
+    ['--kubeconfig', kubeconfig, 'get', 'nodes', '-o', 'wide'],
+    env,
+  );
+  probe(report, 'node describe', 'kubectl', ['--kubeconfig', kubeconfig, 'describe', 'nodes'], env);
+  if (existsSync(sshKey) && controlplaneIp) {
+    const sshArgs = (cmd) => [
+      '-i',
+      sshKey,
+      '-o',
+      'StrictHostKeyChecking=accept-new',
+      '-o',
+      'BatchMode=yes',
+      '-o',
+      'ConnectTimeout=10',
+      `root@${controlplaneIp}`,
+      cmd,
+    ];
+    probe(report, 'k3s service status', 'ssh', sshArgs('systemctl status k3s --no-pager'), env);
+    probe(
+      report,
+      'k3s journal (last 50)',
+      'ssh',
+      sshArgs('journalctl -u k3s --no-pager -n 50'),
+      env,
+    );
+    probe(
+      report,
+      'containerd containers',
+      'ssh',
+      sshArgs('k3s ctr containers ls 2>&1 | head -20'),
+      env,
+    );
+    probe(report, 'host addresses', 'ssh', sshArgs('ip addr show'), env);
+    probe(report, 'host dmesg (tail)', 'ssh', sshArgs('dmesg | tail -30'), env);
+  } else {
+    report.warn(
+      `ssh skipped — sshKey=${sshKey} (${existsSync(sshKey) ? 'found' : 'MISSING'}) controlplaneIp=${controlplaneIp ?? '(none)'}`,
+    );
+  }
+}
+
+function diagnosePods(report, env, kubeconfig) {
+  report.section('PODS');
+  probe(
+    report,
+    'pods all-ns wide',
+    'kubectl',
+    ['--kubeconfig', kubeconfig, 'get', 'pods', '-A', '-o', 'wide'],
+    env,
+  );
+  probe(
+    report,
+    'non-running pods',
+    'kubectl',
+    [
+      '--kubeconfig',
+      kubeconfig,
+      'get',
+      'pods',
+      '-A',
+      '--field-selector=status.phase!=Running,status.phase!=Succeeded',
+    ],
+    env,
+  );
+  // Describe pods in non-running state
+  const listResult = safeRun(
+    'kubectl',
+    [
+      '--kubeconfig',
+      kubeconfig,
+      'get',
+      'pods',
+      '-A',
+      '--field-selector=status.phase!=Running,status.phase!=Succeeded',
+      '-o',
+      'jsonpath={range .items[*]}{.metadata.namespace} {.metadata.name}{"\\n"}{end}',
+    ],
+    env,
+  );
+  if (listResult.ok) {
+    const pairs = listResult.stdout
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map((l) => l.split(' '));
+    for (const [ns, name] of pairs) {
+      if (!ns || !name) continue;
+      report.subsection(`${ns}/${name}`);
+      probe(
+        report,
+        'describe',
+        'kubectl',
+        ['--kubeconfig', kubeconfig, '-n', ns, 'describe', `pod/${name}`],
+        env,
+      );
+      probe(
+        report,
+        'logs (current)',
+        'kubectl',
+        ['--kubeconfig', kubeconfig, '-n', ns, 'logs', name, '--tail=40'],
+        env,
+      );
+      probe(
+        report,
+        'logs (previous)',
+        'kubectl',
+        ['--kubeconfig', kubeconfig, '-n', ns, 'logs', name, '--previous', '--tail=40'],
+        env,
+      );
+    }
+  }
+}
+
+function diagnoseNetwork(report, env, kubeconfig) {
+  report.section('NETWORK');
+  probe(
+    report,
+    'CoreDNS configmap',
+    'kubectl',
+    ['--kubeconfig', kubeconfig, '-n', 'kube-system', 'get', 'cm', 'coredns', '-o', 'yaml'],
+    env,
+  );
+  probe(
+    report,
+    'kube-system pods',
+    'kubectl',
+    ['--kubeconfig', kubeconfig, '-n', 'kube-system', 'get', 'pods', '-o', 'wide'],
+    env,
+  );
+  for (const labelSel of [
+    { name: 'CoreDNS', sel: 'k8s-app=kube-dns' },
+    { name: 'Flannel', sel: 'app=flannel' },
+    { name: 'kube-proxy', sel: 'k8s-app=kube-proxy' },
+    { name: 'hcloud-CCM', sel: 'app.kubernetes.io/name=hcloud-cloud-controller-manager' },
+    {
+      name: 'hcloud-CSI controller',
+      sel: 'app.kubernetes.io/component=controller,app.kubernetes.io/name=hcloud-csi',
+    },
+  ]) {
+    report.subsection(`${labelSel.name} logs`);
+    const list = safeRun(
+      'kubectl',
+      [
+        '--kubeconfig',
+        kubeconfig,
+        '-n',
+        'kube-system',
+        'get',
+        'pods',
+        '-l',
+        labelSel.sel,
+        '-o',
+        'jsonpath={.items[*].metadata.name}',
+      ],
+      env,
+    );
+    if (list.ok && list.stdout.trim()) {
+      for (const pod of list.stdout.trim().split(/\s+/)) {
+        probe(
+          report,
+          pod,
+          'kubectl',
+          ['--kubeconfig', kubeconfig, '-n', 'kube-system', 'logs', pod, '--tail=30'],
+          env,
+        );
+      }
+    } else {
+      report.warn(`No pods found matching ${labelSel.sel}`);
+    }
+  }
+  // In-cluster DNS + egress probe
+  report.subsection('busybox in-cluster probe (nslookup + wget)');
+  const probeName = `vc-diag-${Math.random().toString(36).slice(2, 8)}`;
+  probe(
+    report,
+    'pod probe',
+    'kubectl',
+    [
+      '--kubeconfig',
+      kubeconfig,
+      '-n',
+      'kube-system',
+      'run',
+      probeName,
+      '--image=busybox:1.36',
+      '--restart=Never',
+      '--rm',
+      '--attach',
+      '--timeout=60s',
+      '--command',
+      '--',
+      'sh',
+      '-c',
+      'echo "--- /etc/resolv.conf ---"; cat /etc/resolv.conf; echo; echo "--- nslookup github.com (cluster DNS) ---"; nslookup github.com 2>&1 | head -10; echo; echo "--- nslookup github.com @1.1.1.1 ---"; nslookup github.com 1.1.1.1 2>&1 | head -10; echo; echo "--- wget https://github.com (5s) ---"; wget -qO- --timeout=5 https://github.com 2>&1 | head -3 || echo wget-failed',
+    ],
+    env,
+  );
+}
+
+/**
+ * Deep DNS + pod-network egress battery. Runs a netshoot pod with sleep,
+ * execs a multi-layered probe script, then deletes the pod. Distinguishes
+ * between "DNS broken", "pod-network broken", "MTU mismatch", and "external
+ * egress broken" — the four classes of bug that masquerade as the same
+ * "i/o timeout to github.com" symptom that bit us 2026-04-24.
+ *
+ * Heavy enough (~30s netshoot pull, ~60s battery) that it's excluded from
+ * `diagnose all`. Run explicitly when network is suspect:
+ *   vibecarbon diagnose <env> egress
+ */
+function diagnoseEgress(report, env, kubeconfig, sshKey, controlplaneIp) {
+  report.section('EGRESS (DNS + pod-network battery)');
+
+  // CCM env vars: HCLOUD_NETWORK should resolve via secretKeyRef:hcloud/network.
+  // If it's empty here the route-controller is silently disabled — see
+  // hcloud-cloud-controller-manager #115/#630.
+  report.subsection('CCM env vars (HCLOUD_NETWORK present?)');
+  probe(
+    report,
+    'CCM deploy env',
+    'kubectl',
+    [
+      '--kubeconfig',
+      kubeconfig,
+      '-n',
+      'kube-system',
+      'get',
+      'deploy',
+      'hcloud-cloud-controller-manager',
+      '-o',
+      'jsonpath={range .spec.template.spec.containers[*].env[*]}{.name}\t{.value}\t{.valueFrom.secretKeyRef.name}/{.valueFrom.secretKeyRef.key}{"\\n"}{end}',
+    ],
+    env,
+  );
+
+  // CoreDNS Corefile — forwarders are the upstream resolver pod-DNS depends on.
+  report.subsection('CoreDNS Corefile');
+  probe(
+    report,
+    'coredns Corefile',
+    'kubectl',
+    [
+      '--kubeconfig',
+      kubeconfig,
+      '-n',
+      'kube-system',
+      'get',
+      'cm',
+      'coredns',
+      '-o',
+      'jsonpath={.data.Corefile}',
+    ],
+    env,
+  );
+
+  // Node-level state: routes, addresses, links, resolv.conf. If the host
+  // can't egress, no pod can either.
+  if (existsSync(sshKey) && controlplaneIp) {
+    report.subsection('node-level routes / addresses / links / resolv.conf');
+    const sshArgs = (cmd) => [
+      '-i',
+      sshKey,
+      '-o',
+      'StrictHostKeyChecking=accept-new',
+      '-o',
+      'BatchMode=yes',
+      '-o',
+      'ConnectTimeout=10',
+      `root@${controlplaneIp}`,
+      cmd,
+    ];
+    probe(report, 'host routes', 'ssh', sshArgs('ip route'), env);
+    probe(report, 'host addresses', 'ssh', sshArgs('ip addr'), env);
+    probe(report, 'host links', 'ssh', sshArgs('ip link'), env);
+    probe(report, 'host /etc/resolv.conf', 'ssh', sshArgs('cat /etc/resolv.conf'), env);
+  } else {
+    report.warn(
+      `host node probes skipped — sshKey=${existsSync(sshKey) ? 'found' : 'MISSING'} controlplaneIp=${controlplaneIp ?? '(none)'}`,
+    );
+  }
+
+  // Pod-level battery — the part that actually distinguishes failure modes.
+  // Each line is labeled so a failed step localizes the layer:
+  //   A fails  → cluster DNS (CoreDNS) broken
+  //   B fails  → external DNS reachability (node→1.1.1.1) broken
+  //   C fails  → public-IP egress broken (CNI masquerade / default route)
+  //   D fails  → github.com unreachable by IP (egress to that AS broken)
+  //   E fails  → DNS-driven egress broken specifically (combo of A or B)
+  //   I fails  → MTU clamp not applied (vxlan-on-Hetzner=1450); fragments dropped
+  //
+  // We can't use `kubectl run --rm --attach` with a one-shot script — it
+  // truncates stdout when the container exits quickly (validated against a
+  // live cluster). Use the create+wait+exec+delete pattern: create with a
+  // long sleep, wait for Ready, exec the battery (stdout is captured cleanly),
+  // delete in finally-ish fashion (probe() never throws so cleanup always runs).
+  report.subsection('netshoot pod battery (DNS + curl + MTU)');
+  const podName = `vc-egress-${Math.random().toString(36).slice(2, 8)}`;
+  const battery = [
+    'set +e',
+    'echo "## /etc/resolv.conf"; cat /etc/resolv.conf; echo',
+    'echo "## A. dig @cluster-DNS (10.96.0.10) github.com"; dig +time=3 +tries=1 @10.96.0.10 github.com +short; echo "exit=$?"; echo',
+    'echo "## B. dig @1.1.1.1 github.com"; dig +time=3 +tries=1 @1.1.1.1 github.com +short; echo "exit=$?"; echo',
+    'echo "## C. curl https://1.1.1.1 (public IP)"; curl -m5 -sI https://1.1.1.1 -o /dev/null -w "http=%{http_code} t=%{time_total}s\\n" || echo FAIL_PUBLIC; echo',
+    'echo "## D. curl github.com via direct IP (bypass DNS)"; curl -m5 -skI --resolve github.com:443:140.82.121.4 https://github.com/ -o /dev/null -w "http=%{http_code} t=%{time_total}s\\n" || echo FAIL_GITHUB_IP; echo',
+    'echo "## E. curl https://github.com (DNS-driven)"; curl -m5 -sI https://github.com -o /dev/null -w "http=%{http_code} t=%{time_total}s\\n" || echo FAIL_GITHUB_DNS; echo',
+    'echo "## F. curl https://raw.githubusercontent.com (Flux source target)"; curl -m5 -sI https://raw.githubusercontent.com -o /dev/null -w "http=%{http_code} t=%{time_total}s\\n" || echo FAIL_RAWGH; echo',
+    'echo "## G. ip route"; ip route; echo',
+    'echo "## H. ip -br link (MTU on each iface)"; ip -br link; echo',
+    'echo "## I. ping -M do -s 1372 1.1.1.1 (vxlan-MTU 1400 OK)"; ping -M do -s 1372 -c1 -W2 1.1.1.1 2>&1 | tail -2; echo',
+    'echo "## J. ping -M do -s 1444 1.1.1.1 (full-MTU 1472 — expect FAIL on Hetzner private)"; ping -M do -s 1444 -c1 -W2 1.1.1.1 2>&1 | tail -2; echo',
+  ].join('; ');
+  probe(
+    report,
+    'create pod',
+    'kubectl',
+    [
+      '--kubeconfig',
+      kubeconfig,
+      '-n',
+      'default',
+      'run',
+      podName,
+      '--image=nicolaka/netshoot',
+      '--restart=Never',
+      '--command',
+      '--',
+      'sleep',
+      '300',
+    ],
+    env,
+  );
+  probe(
+    report,
+    'wait pod ready',
+    'kubectl',
+    [
+      '--kubeconfig',
+      kubeconfig,
+      '-n',
+      'default',
+      'wait',
+      `pod/${podName}`,
+      '--for=condition=Ready',
+      '--timeout=180s',
+    ],
+    env,
+  );
+  probe(
+    report,
+    'exec battery',
+    'kubectl',
+    ['--kubeconfig', kubeconfig, '-n', 'default', 'exec', podName, '--', 'sh', '-c', battery],
+    env,
+  );
+  probe(
+    report,
+    'cleanup pod',
+    'kubectl',
+    [
+      '--kubeconfig',
+      kubeconfig,
+      '-n',
+      'default',
+      'delete',
+      'pod',
+      podName,
+      '--wait=false',
+      '--grace-period=1',
+    ],
+    env,
+  );
+}
+
+function diagnoseFlux(report, env, kubeconfig) {
+  report.section('FLUX');
+  probe(
+    report,
+    'flux resources',
+    'kubectl',
+    [
+      '--kubeconfig',
+      kubeconfig,
+      '-n',
+      'flux-system',
+      'get',
+      'gitrepository,kustomization,helmrelease',
+    ],
+    env,
+  );
+  probe(
+    report,
+    'flux events',
+    'kubectl',
+    ['--kubeconfig', kubeconfig, '-n', 'flux-system', 'get', 'events', '--sort-by=.lastTimestamp'],
+    env,
+  );
+  for (const controller of [
+    'source-controller',
+    'kustomize-controller',
+    'helm-controller',
+    'notification-controller',
+  ]) {
+    report.subsection(`${controller} logs`);
+    probe(
+      report,
+      controller,
+      'kubectl',
+      [
+        '--kubeconfig',
+        kubeconfig,
+        '-n',
+        'flux-system',
+        'logs',
+        `deployment/${controller}`,
+        '--tail=40',
+      ],
+      env,
+    );
+  }
+  // Describe the GitRepository — this is where stale-URL / auth errors appear
+  probe(
+    report,
+    'GitRepository describe',
+    'kubectl',
+    ['--kubeconfig', kubeconfig, '-n', 'flux-system', 'describe', 'gitrepository'],
+    env,
+  );
+}
+
+function readControlplaneIp(envName) {
+  const projConfigPath = join(process.cwd(), '.vibecarbon.json');
+  if (!existsSync(projConfigPath)) return null;
+  try {
+    const data = JSON.parse(readFileSync(projConfigPath, 'utf-8'));
+    const envCfg = data?.environments?.[envName];
+    if (!envCfg) return null;
+    const masterServer = envCfg.servers?.find((s) => s.name === 'master' || s.name === 'primary');
+    return masterServer?.ip ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export async function run(args) {
+  const { values, positional, errors } = parseFlags(args, SPEC);
+
+  if (errors.length > 0) {
+    for (const e of errors) {
+      process.stderr.write(`${c.error('✗')} ${e}\n`);
+    }
+    process.stderr.write(`Run ${c.info('vibecarbon diagnose -h')} for usage.\n`);
+    process.exit(1);
+  }
+
+  if (values.h) {
+    process.stdout.write(renderHelp(SPEC));
+    process.exit(0);
+  }
+
+  // Project guard runs first so an accidental `vibecarbon diagnose` from
+  // a parent directory emits the canonical message instead of stumbling
+  // through kubectl probes against a missing kubeconfig.
+  assertInProjectDir();
+
+  const envName = /** @type {string|undefined} */ (positional.env) ?? 'prod';
+  const requested = /** @type {string|undefined} */ (positional.section) ?? 'all';
+  if (!ALL_VALID_SECTIONS.includes(requested) && requested !== 'all') {
+    console.error(
+      c.error(`Unknown section "${requested}". Valid: ${ALL_VALID_SECTIONS.join(', ')}, all.`),
+    );
+    process.exit(1);
+  }
+  const sectionsToRun = requested === 'all' ? SECTIONS : [requested];
+
+  const cwd = process.cwd();
+  const kubeconfig = join(cwd, '.vibecarbon', `kubeconfig-${envName}`);
+  const sshKey = join(cwd, '.vibecarbon', `ssh-${envName}`);
+  const controlplaneIp = readControlplaneIp(envName);
+
+  const hcloudToken = loadHcloudToken();
+  const env = { ...process.env };
+  if (hcloudToken) env.HCLOUD_TOKEN = hcloudToken;
+
+  // Auto-detect operator IP and ensure firewall lets us in. Diagnose runs
+  // many kubectl + ssh probes; if the firewall blocks our IP every probe
+  // hangs to its timeout. Refresh lastUsedAt and apply on first miss.
+  const projectConfig = loadProjectConfig();
+  if (projectConfig && hcloudToken) {
+    try {
+      const isHA = !!projectConfig.environments?.[envName]?.ha?.enabled;
+      const result = await ensureOperatorIpAccess({
+        projectConfig,
+        environment: envName,
+        isHA,
+        apiToken: hcloudToken,
+        yes: false,
+        onMessage: (msg) => console.error(`${c.info('i')} ${msg}`),
+      });
+      if (result.added) {
+        console.error(`${c.success('✓')} Firewall updated: SSH/k8s API now allow ${result.cidr}`);
+      }
+    } catch (err) {
+      console.error(`${c.warning('!')} Operator-IP check failed: ${err.message}`);
+      console.error(
+        '  Continuing — kubectl/SSH probes may time out if your IP is not allowlisted.',
+      );
+    }
+  }
+
+  const report = new Report();
+
+  // Header so the saved report is self-describing
+  const ts = new Date().toISOString();
+  const header = [
+    '# vibecarbon diagnose',
+    `# env:        ${envName}`,
+    `# sections:   ${sectionsToRun.join(', ')}`,
+    `# timestamp:  ${ts}`,
+    `# cwd:        ${cwd}`,
+    `# kubeconfig: ${kubeconfig} ${existsSync(kubeconfig) ? '(found)' : '(MISSING)'}`,
+    `# sshKey:     ${sshKey} ${existsSync(sshKey) ? '(found)' : '(MISSING)'}`,
+    `# masterIP:   ${controlplaneIp ?? '(unknown)'}`,
+    `# hcloud:     ${hcloudToken ? 'authenticated' : 'NOT AUTHENTICATED'}`,
+  ].join('\n');
+  console.log(header);
+  report.lines.push(header);
+
+  const includesHcloud = sectionsToRun.includes('hcloud');
+  const needsKubectl = sectionsToRun.some((s) =>
+    ['nodes', 'pods', 'network', 'flux', 'egress'].includes(s),
+  );
+
+  if (includesHcloud) diagnoseHcloud(report, env);
+  if (needsKubectl) {
+    if (!existsSync(kubeconfig)) {
+      report.warn(
+        `Skipping kubectl-based sections: kubeconfig not found at ${kubeconfig}. Run a deploy first.`,
+      );
+    } else {
+      if (sectionsToRun.includes('nodes'))
+        diagnoseNodes(report, env, kubeconfig, sshKey, controlplaneIp);
+      if (sectionsToRun.includes('pods')) diagnosePods(report, env, kubeconfig);
+      if (sectionsToRun.includes('network')) diagnoseNetwork(report, env, kubeconfig);
+      if (sectionsToRun.includes('egress'))
+        diagnoseEgress(report, env, kubeconfig, sshKey, controlplaneIp);
+      if (sectionsToRun.includes('flux')) diagnoseFlux(report, env, kubeconfig);
+    }
+  }
+
+  // Persist
+  const diagDir = join(homedir(), '.vibecarbon');
+  if (!existsSync(diagDir)) mkdirSync(diagDir, { recursive: true });
+  const outFile = join(diagDir, `diag-${envName}-${ts.replace(/[:.]/g, '-')}.txt`);
+  writeFileSync(outFile, report.toString());
+  console.log(`\n${c.success('✓')} Report saved: ${outFile}`);
+}