@tdk-landscape/tdk-cli-core 1.3.45 → 1.3.49

package/cli/src/utils/doctor-runtime.ts

@@ -0,0 +1,604 @@
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { CheckResult } from "../types/index.js";
+import { formatCount } from "./formatting.js";
+import { findProjectRoot } from "./paths.js";
+import { getProjectName } from "./service-urls.js";
+
+const EXEC_TIMEOUT_MS = 10_000;
+const REGISTRY_PROBE_TIMEOUT_MS = 3_000;
+const DEFAULT_VERDACCIO_URL = "http://localhost:4873";
+
+/** Host ports Traefik publishes for local ingress. Without these, app routes never come up. */
+export const INGRESS_PORTS = [80, 443] as const;
+
+export function toComposeProjectPrefix(projectName: string): string {
+  return projectName.replace(/-/g, "_");
+}
+
+export interface PublishedPortHolder {
+  name: string;
+  ports: string;
+  publishedPorts: number[];
+}
+
+/**
+ * Parse `docker ps --format '{{.Names}}\t{{.Ports}}'` lines into containers that
+ * publish specific host ports (e.g. 0.0.0.0:80->80/tcp).
+ */
+export function parsePublishedPortHolders(
+  dockerPsOutput: string,
+  ports: readonly number[],
+): PublishedPortHolder[] {
+  const wanted = new Set(ports);
+  const holders: PublishedPortHolder[] = [];
+
+  for (const line of dockerPsOutput.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const tab = trimmed.indexOf("\t");
+    const name = tab >= 0 ? trimmed.slice(0, tab) : trimmed;
+    const portsField = tab >= 0 ? trimmed.slice(tab + 1) : "";
+    const publishedPorts: number[] = [];
+
+    for (const port of wanted) {
+      // Matches 0.0.0.0:80->, :::80->, 127.0.0.1:80->
+      const pattern = new RegExp(`(?:^|[\\s,])(?:\\d[\\d.]*:|\\[::\\]:|::)?${port}->`);
+      if (pattern.test(portsField) || portsField.includes(`:${port}->`)) {
+        publishedPorts.push(port);
+      }
+    }
+
+    if (publishedPorts.length > 0) {
+      holders.push({ name, ports: portsField, publishedPorts });
+    }
+  }
+
+  return holders;
+}
+
+export function isOwnIngressContainer(containerName: string, projectPrefix: string): boolean {
+  const name = containerName.toLowerCase();
+  const prefix = projectPrefix.toLowerCase();
+  // beauty_crm_traefik, beauty_crm-traefik-1, etc.
+  return name === `${prefix}_traefik` || name.startsWith(`${prefix}_traefik`);
+}
+
+export function findForeignIngressHolders(
+  holders: PublishedPortHolder[],
+  projectPrefix: string,
+): PublishedPortHolder[] {
+  return holders.filter((holder) => !isOwnIngressContainer(holder.name, projectPrefix));
+}
+
+export interface TiltResourceFailure {
+  name: string;
+  updateStatus: string;
+  runtimeStatus: string;
+  error: string;
+}
+
+interface TiltUiResourceItem {
+  metadata?: { name?: string };
+  status?: {
+    updateStatus?: string;
+    runtimeStatus?: string;
+    buildHistory?: Array<{ error?: string }>;
+  };
+}
+
+/**
+ * Extract failing UIResources from `tilt get uiresources -o json`.
+ */
+export function parseTiltResourceFailures(jsonText: string): {
+  failures: TiltResourceFailure[];
+  pendingCount: number;
+  okCount: number;
+  total: number;
+} {
+  const parsed = JSON.parse(jsonText) as { items?: TiltUiResourceItem[] };
+  const items = parsed.items ?? [];
+  const failures: TiltResourceFailure[] = [];
+  let pendingCount = 0;
+  let okCount = 0;
+
+  for (const item of items) {
+    const name = item.metadata?.name ?? "unknown";
+    const updateStatus = item.status?.updateStatus ?? "";
+    const runtimeStatus = item.status?.runtimeStatus ?? "";
+    const error = (item.status?.buildHistory?.[0]?.error ?? "").trim();
+
+    if (updateStatus === "error" || runtimeStatus === "error") {
+      failures.push({
+        name,
+        updateStatus,
+        runtimeStatus,
+        // Keep enough of the raw Tilt error for summarizers; display uses
+        // summarizeTiltBuildError() which extracts the actionable root cause.
+        error: error.replace(/\s+/g, " ").slice(0, 800),
+      });
+      continue;
+    }
+
+    if (updateStatus === "ok" && (runtimeStatus === "ok" || runtimeStatus === "not_applicable")) {
+      okCount += 1;
+      continue;
+    }
+
+    if (
+      name !== "(Tiltfile)" &&
+      (updateStatus === "pending" ||
+        runtimeStatus === "pending" ||
+        updateStatus === "none" ||
+        runtimeStatus === "none")
+    ) {
+      pendingCount += 1;
+    }
+  }
+
+  return { failures, pendingCount, okCount, total: items.length };
+}
+
+/**
+ * Turn noisy Tilt/Docker build errors into an actionable one-liner.
+ * Prefer registry/network root causes over truncated ImageBuild exit lines.
+ */
+export function summarizeTiltBuildError(error: string): string {
+  const normalized = error.replace(/\s+/g, " ").trim();
+
+  const bindMatch = normalized.match(/Bind for [^ ]+:(\d+) failed: port is already allocated/i);
+  if (bindMatch) {
+    return `host port ${bindMatch[1]} is already allocated`;
+  }
+  if (/port is already allocated/i.test(normalized)) {
+    return "a required host port is already allocated";
+  }
+
+  const refusedPackages = [
+    ...normalized.matchAll(
+      /ConnectionRefused downloading package manifest (@[A-Za-z0-9._/-]+)/gi,
+    ),
+  ].map((match) => match[1]);
+  if (refusedPackages.length > 0) {
+    const unique = [...new Set(refusedPackages)];
+    const shown = unique.slice(0, 4).join(", ");
+    const more = unique.length > 4 ? ` (+${unique.length - 4} more)` : "";
+    return `private registry ConnectionRefused for ${shown}${more} — Verdaccio (:4873) is down or unreachable from the build`;
+  }
+
+  if (/failed to resolve source metadata for docker\.io\/library\/(beauty-crm-[^:\s]+)/i.test(normalized)) {
+    const image = normalized.match(
+      /failed to resolve source metadata for docker\.io\/library\/(beauty-crm-[^:\s]+)/i,
+    )?.[1];
+    return `base image ${image ?? "beauty-crm-*"} missing locally (golden-layer build not finished or failed)`;
+  }
+
+  if (
+    /install-deps\.sh/i.test(normalized) ||
+    /bun install(?: --production)?/i.test(normalized) ||
+    /npm (?:ci|install)/i.test(normalized)
+  ) {
+    return "dependency install failed during ImageBuild — usually Verdaccio (:4873) unreachable or missing @scoped packages (ConnectionRefused downloading package manifest)";
+  }
+
+  const missingImage =
+    normalized.match(/No such image:\s*([^\s]+)/i)?.[1] ??
+    normalized.match(/pull access denied for ([^,:\s]+)/i)?.[1] ??
+    undefined;
+  const composeService = normalized.match(
+    /\bup\s+-d\s+--no-build\s+([A-Za-z0-9._-]+)/i,
+  )?.[1];
+  if (missingImage || composeService || /docker compose .*\bup\s+-d\s+--no-build\b/i.test(normalized)) {
+    const imageLabel = missingImage ?? `${composeService ?? "service"}:dev`;
+    const serviceHint = composeService ? ` for ${composeService}` : "";
+    return `compose run failed because image is missing (${imageLabel})${serviceHint} — wait for the ImageBuild resource to finish, then re-trigger the *-run-only resource`;
+  }
+
+  if (/bun run build/i.test(normalized)) {
+    return "ImageBuild failed during `bun run build` (compile/typecheck) — open the resource logs in Tilt for the TypeScript/build error";
+  }
+
+  if (/ImageBuild:/i.test(normalized) || /^Command "/i.test(normalized)) {
+    return normalized.slice(0, 220);
+  }
+
+  return normalized.slice(0, 220);
+}
+
+export function isRegistryRelatedBuildError(error: string): boolean {
+  return /ConnectionRefused downloading package manifest|Verdaccio|private registry|dependency install failed during ImageBuild|install-deps\.sh|bun install/i.test(
+    error,
+  );
+}
+
+export function projectExpectsVerdaccio(projectRoot: string = findProjectRoot() ?? process.cwd()): boolean {
+  const projectJsonPath = join(projectRoot, ".tdk", "project.json");
+  if (existsSync(projectJsonPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(projectJsonPath, "utf-8")) as {
+        optional_infra?: { verdaccio?: boolean };
+        phases?: Record<string, { enabledStacks?: string[] }>;
+      };
+      if (parsed.optional_infra?.verdaccio === true) {
+        return true;
+      }
+      if (
+        Object.values(parsed.phases ?? {}).some((phase) =>
+          (phase.enabledStacks ?? []).includes("verdaccio"),
+        )
+      ) {
+        return true;
+      }
+    } catch {
+      // Fall through to npmrc heuristics.
+    }
+  }
+
+  // Heuristic: scoped private registry pointed at :4873
+  for (const candidate of [
+    join(projectRoot, ".npmrc"),
+    join(projectRoot, "package.json"),
+  ]) {
+    if (!existsSync(candidate)) continue;
+    try {
+      const text = readFileSync(candidate, "utf-8");
+      if (/:4873\b/.test(text) || /verdaccio/i.test(text)) {
+        return true;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  return false;
+}
+
+/**
+ * When the project uses a local Verdaccio registry, fail early with a clear
+ * fix instead of only showing truncated ImageBuild exit codes later.
+ */
+export function checkPrivateNpmRegistry(
+  exec: typeof execSync = execSync,
+  projectRoot: string = findProjectRoot() ?? process.cwd(),
+  registryUrl: string = process.env.VERDACCIO_URL ??
+    process.env.NPM_REGISTRY_URL ??
+    DEFAULT_VERDACCIO_URL,
+): CheckResult {
+  if (!projectExpectsVerdaccio(projectRoot)) {
+    return {
+      name: "Private npm registry",
+      didPass: true,
+      isSkipped: true,
+      message: "Private npm registry (Verdaccio) not enabled for this project - skipped",
+    };
+  }
+
+  let containerRunning = false;
+  try {
+    const names = exec("docker ps --format '{{.Names}}'", {
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: EXEC_TIMEOUT_MS,
+    });
+    containerRunning = /verdaccio/i.test(names);
+  } catch {
+    // Docker may be down; other doctor checks cover that.
+  }
+
+  let httpOk = false;
+  let httpDetail = "";
+  try {
+    // curl is more reliable than fetch in the compiled CLI binary environments.
+    const probe = exec(
+      `curl -fsS -o /dev/null -w '%{http_code}' --max-time 2 ${JSON.stringify(registryUrl)}`,
+      {
+        stdio: "pipe",
+        encoding: "utf-8",
+        timeout: REGISTRY_PROBE_TIMEOUT_MS + 1_000,
+      },
+    ).trim();
+    httpOk = /^[23]\d\d$/.test(probe);
+    httpDetail = `HTTP ${probe}`;
+  } catch (error) {
+    httpDetail = error instanceof Error ? error.message.slice(0, 120) : "request failed";
+  }
+
+  if (httpOk) {
+    return {
+      name: "Private npm registry",
+      didPass: true,
+      message: `Private npm registry reachable at ${registryUrl}${
+        containerRunning ? " (verdaccio container running)" : ""
+      }`,
+    };
+  }
+
+  if (containerRunning) {
+    return {
+      name: "Private npm registry",
+      didPass: false,
+      message: `Verdaccio container is running but ${registryUrl} is not responding (${httpDetail}). ImageBuilds that install @scoped packages will fail with ConnectionRefused downloading package manifest.`,
+      fix: "Check `docker logs` for the verdaccio container, confirm port 4873 is published, then re-run `tdk doctor`.",
+    };
+  }
+
+  return {
+    name: "Private npm registry",
+    didPass: false,
+    message: `Private npm registry (Verdaccio) is not reachable at ${registryUrl}. Docker ImageBuilds will fail with ConnectionRefused downloading package manifests for @beauty-crm/* and @tdk-landscape/* packages.`,
+    fix: "Start the registry with `bun run verdaccio:start` (or `docker compose -f docker-compose.verdaccio.yml up -d`), publish packages with `bun run publish:all` / `scripts/build/publish-to-verdaccio.sh`, then `tilt trigger` failed resources or re-run `tdk up`.",
+  };
+}
+
+/**
+ * Fail when another container already owns Traefik's host ports (80/443).
+ * This is the exact failure mode that leaves apps never scheduled while doctor
+ * previously reported "Environment ready".
+ */
+export function checkIngressPorts(
+  exec: typeof execSync = execSync,
+  projectName: string = getProjectName(),
+): CheckResult {
+  const projectPrefix = toComposeProjectPrefix(projectName);
+  let dockerPs = "";
+
+  try {
+    dockerPs = exec("docker ps --format '{{.Names}}\\t{{.Ports}}'", {
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: EXEC_TIMEOUT_MS,
+    });
+  } catch {
+    return {
+      name: "Ingress Ports",
+      didPass: true,
+      isSkipped: true,
+      message: "Docker not available - skipped ingress port check",
+    };
+  }
+
+  const holders = parsePublishedPortHolders(dockerPs, INGRESS_PORTS);
+  const foreign = findForeignIngressHolders(holders, projectPrefix);
+
+  if (foreign.length === 0) {
+    const own = holders.filter((holder) => isOwnIngressContainer(holder.name, projectPrefix));
+    if (own.length > 0) {
+      return {
+        name: "Ingress Ports",
+        didPass: true,
+        message: `Ingress ports ${INGRESS_PORTS.join("/")} held by this project's Traefik (${own
+          .map((h) => h.name)
+          .join(", ")})`,
+      };
+    }
+    return {
+      name: "Ingress Ports",
+      didPass: true,
+      message: `Ingress ports ${INGRESS_PORTS.join("/")} are free for Traefik`,
+    };
+  }
+
+  const details = foreign
+    .map((holder) => {
+      const ports = holder.publishedPorts.join(", ");
+      return `${holder.name} (host ports ${ports})`;
+    })
+    .join("\n    ");
+
+  return {
+    name: "Ingress Ports",
+    didPass: false,
+    message: `Traefik cannot bind ingress ports because another container already owns them:\n    ${details}`,
+    fix: `Stop the foreign container(s), e.g. \`docker stop ${foreign[0]?.name}\`, or shut down the other TDK/Tilt project using that Traefik. Then re-run \`tdk up\`.`,
+  };
+}
+
+/**
+ * When a Tilt session is active, surface resource update errors (Traefik port
+ * binds, image builds, etc.) instead of claiming the environment is ready
+ * while apps sit forever in pending/none.
+ */
+export function checkTiltResourceHealth(exec: typeof execSync = execSync): CheckResult {
+  let jsonText = "";
+  try {
+    jsonText = exec("tilt get uiresources -o json", {
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: EXEC_TIMEOUT_MS,
+    });
+  } catch {
+    return {
+      name: "Tilt Resources",
+      didPass: true,
+      isSkipped: true,
+      message: "Tilt is not running - skipped resource status check",
+      fix: "Start them with: tdk up",
+    };
+  }
+
+  let parsed: ReturnType<typeof parseTiltResourceFailures>;
+  try {
+    parsed = parseTiltResourceFailures(jsonText);
+  } catch {
+    return {
+      name: "Tilt Resources",
+      didPass: true,
+      isSkipped: true,
+      message: "Could not parse Tilt resource status - skipped",
+    };
+  }
+
+  if (parsed.total === 0) {
+    return {
+      name: "Tilt Resources",
+      didPass: true,
+      isSkipped: true,
+      message: "No Tilt UIResources found",
+    };
+  }
+
+  if (parsed.failures.length === 0) {
+    return {
+      name: "Tilt Resources",
+      didPass: true,
+      message: `Tilt resources healthy (${parsed.okCount} ok, ${parsed.pendingCount} pending)`,
+    };
+  }
+
+  // Always list every failed resource. Earlier logic showed only "critical"
+  // infra matches (e.g. nats-http-bridge) and hid the other ImageBuild/run-only
+  // failures, so doctor said "7 failed" while printing a single line.
+  const ordered = orderTiltFailures(parsed.failures);
+  const maxListed = 20;
+  const listed = ordered.slice(0, maxListed);
+  const omitted = ordered.length - listed.length;
+
+  const described = listed.map((failure) => ({
+    failure,
+    why: describeTiltFailure(failure, exec),
+  }));
+  const details = described
+    .map(({ failure, why }) => `${failure.name}: ${why}`)
+    .join("\n    ");
+  const omittedNote =
+    omitted > 0 ? `\n    …and ${formatCount(omitted, "more failed resource")}` : "";
+
+  const pendingNote =
+    parsed.pendingCount > 0
+      ? `\n    ${formatCount(parsed.pendingCount, "resource")} still pending/not started — often blocked by the failures above.`
+      : "";
+
+  const hasPortConflict = ordered.some((failure) =>
+    /port is already allocated/i.test(failure.error),
+  );
+  const hasRegistryFailure = ordered.some(
+    (failure) =>
+      isRegistryRelatedBuildError(failure.error) ||
+      isRegistryRelatedBuildError(summarizeTiltBuildError(failure.error)),
+  );
+  const hasKafkaRuntimeFailure = described.some(({ why }) =>
+    /Kafka broker unreachable|kafka:9092/i.test(why),
+  );
+
+  let fix =
+    "Open http://localhost:10350, inspect the red resources, fix the listed errors, then `tilt trigger <resource>` or re-run `tdk up`.";
+  if (hasPortConflict) {
+    fix =
+      "Free the conflicting host port (usually 80/443): `docker ps --filter publish=80` then `docker stop <other-traefik>`. Re-trigger Traefik in the Tilt UI or run `tdk up` again.";
+  } else if (hasRegistryFailure) {
+    fix =
+      "Start Verdaccio (`bun run verdaccio:start`), ensure packages are published (`bun run publish:all` or `bash scripts/build/publish-to-verdaccio.sh`), confirm `curl http://localhost:4873` works, then `tilt trigger` the failed resources.";
+  } else if (hasKafkaRuntimeFailure) {
+    fix =
+      "Kafka is not running (optional infra). Start it, point the bridge at a real broker, or disable Kafka-dependent resources until Kafka is enabled.";
+  }
+
+  return {
+    name: "Tilt Resources",
+    didPass: false,
+    message: `Tilt reports ${formatCount(parsed.failures.length, "failed resource")}:\n    ${details}${omittedNote}${pendingNote}`,
+    fix,
+  };
+}
+
+const INFRA_FAILURE_NAME =
+  /^(traefik|postgres|nats|infisical|verdaccio|proxy)([.-]|$)/i;
+
+export function isInfraTiltFailure(name: string): boolean {
+  return INFRA_FAILURE_NAME.test(name);
+}
+
+/** Critical infra first, then everything else — never drop failures. */
+export function orderTiltFailures(failures: TiltResourceFailure[]): TiltResourceFailure[] {
+  return [...failures].sort((a, b) => {
+    const aInfra = isInfraTiltFailure(a.name) ? 0 : 1;
+    const bInfra = isInfraTiltFailure(b.name) ? 0 : 1;
+    if (aInfra !== bInfra) return aInfra - bInfra;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+/**
+ * Best-effort root cause for runtime crashes when buildHistory has no error.
+ * Reads recent docker logs for the matching container name.
+ */
+export function probeContainerRuntimeError(
+  resourceName: string,
+  exec: typeof execSync = execSync,
+): string | null {
+  try {
+    const names = exec("docker ps -a --format '{{.Names}}'", {
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: EXEC_TIMEOUT_MS,
+    })
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+
+    const match =
+      names.find((name) => name === resourceName) ??
+      names.find((name) => name.includes(resourceName));
+    if (!match) return null;
+
+    const logs = exec(`docker logs --tail 120 ${JSON.stringify(match)} 2>&1`, {
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: EXEC_TIMEOUT_MS,
+    });
+
+    if (/getaddrinfo ENOTFOUND/i.test(logs) && /kafka:9092/i.test(logs)) {
+      return "runtime crash: Kafka broker unreachable (getaddrinfo ENOTFOUND kafka:9092)";
+    }
+    if (/ECONNREFUSED/i.test(logs) && /kafka/i.test(logs)) {
+      return "runtime crash: Kafka connection refused";
+    }
+    const refusedPkg = logs.match(
+      /ConnectionRefused downloading package manifest (@[A-Za-z0-9._/-]+)/i,
+    );
+    if (refusedPkg?.[1]) {
+      return `runtime/build log: private registry ConnectionRefused for ${refusedPkg[1]}`;
+    }
+
+    // Zod env/config validation: pull required field paths from the dump.
+    if (/ZodError/i.test(logs)) {
+      const requiredPaths = [
+        ...logs.matchAll(/"path"\s*:\s*\[\s*"([^"]+)"\s*\]/g),
+      ].map((match) => match[1]);
+      const uniquePaths = [...new Set(requiredPaths)].slice(0, 6);
+      if (uniquePaths.length > 0) {
+        return `runtime crash: ZodError missing required config/env: ${uniquePaths.join(", ")}`;
+      }
+      return "runtime crash: ZodError during config/env validation";
+    }
+
+    // Prefer structured app failures over random source lines that contain "error =".
+    const structured =
+      logs.match(/error:\s+Failed to [^:\n]+[^\n]{0,120}/i)?.[0] ??
+      logs.match(/Failed to (?:start|initialize) [^\n]{0,120}/i)?.[0] ??
+      logs.match(/^\s*error:\s+[^\n]{0,160}/im)?.[0];
+    if (structured) {
+      return `runtime crash: ${structured.replace(/\s+/g, " ").trim().slice(0, 180)}`;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+export function describeTiltFailure(
+  failure: TiltResourceFailure,
+  exec: typeof execSync = execSync,
+): string {
+  if (failure.error) {
+    return summarizeTiltBuildError(failure.error);
+  }
+  if (failure.runtimeStatus === "error") {
+    return (
+      probeContainerRuntimeError(failure.name, exec) ??
+      "runtime error (container crashed or unhealthy — check Tilt/docker logs)"
+    );
+  }
+  return failure.updateStatus || failure.runtimeStatus || "unknown error";
+}