kickload-watcher-mcp 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "kickload-watcher-mcp",
+  "version": "0.1.0",
+  "description": "Automated API performance testing for Claude Code teams via KickLoad",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "kickload-watcher-mcp": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "dev": "node --watch index.js",
+    "setup": "node setup.js"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "chokidar": "^3.6.0",
+    "nodemailer": "^6.9.0",
+    "node-fetch": "^3.3.0",
+    "form-data": "^4.0.0",
+    "dotenv": "^16.4.0",
+    "chalk": "^5.3.0",
+    "unzipper": "^0.10.14",
+    "tar": "^6.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "kickload",
+    "mcp",
+    "claude",
+    "testing",
+    "watcher",
+    "oneqa"
+  ],
+  "author": "NeeyatAI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KickLoad/kickload-watcher-mcp.git"
+  },
+  "homepage": "https://github.com/KickLoad/kickload-watcher-mcp",
+  "files": [
+   "**/*.js",
+   "users.json",
+   "README.md"
+ ],
+  "preferGlobal": true
+}

package/pipeline.js

@@ -0,0 +1,448 @@
+import { KickloadClient }                       from "./kickload-client.js";
+import { generateTestPrompt }                   from "./test-generator.js";
+import { sendResultEmail }                      from "./email-sender.js";
+import { findRunningServer, isServerReachable } from "./server-detector.js";
+import { isEmailAllowed, getCooldownRemaining,
+         recordEmailSent }                      from "./email-cooldown.js";
+import { createLogger, logPipelineSummary }     from "./logger.js";
+import { getEmailForUser }                      from "./identity-map.js";
+import { getPublicUrl }                         from "./ngrok-manager.js";
+import { config }                               from "./config.js";
+
+const logger = createLogger("pipeline");
+
+const DEDUP_WINDOW_MS  = 10_000;
+const MAX_RETRIES      = 2;
+const RETRY_DELAY_MS   = 3_000;
+const NGROK_MAX_RETRIES = 3;
+const NGROK_RETRY_DELAY = 5_000;
+
+let   pipelineRunning = false;
+// PROBLEM 4 — Single pending batch instead of a queue
+let   pendingBatch    = null;   // { endpoints: Set, events: [], devEmail, ... }
+const recentTriggers  = new Map();
+
+// ── Public event handlers ─────────────────────────────────────────────────────
+
+export async function handleFileEvent(fileEvent) {
+  const userId   = fileEvent.userId || config.identity.defaultUserId || null;
+  const devEmail = getEmailForUser(userId);
+  if (!devEmail) logger.warn("No developer email — notifications disabled");
+  enqueue({ ...fileEvent, userId, devEmail, originalPrompt: "Code saved via Claude Code" });
+}
+
+export async function handleComplianceSession(session) {
+  const { userId, generatedCode, prompt, sessionId, timestamp } = session;
+  const devEmail = getEmailForUser(userId);
+  if (!devEmail) {
+    logger.warn(`No email for user "${userId}" — skipping session ${sessionId}`);
+    return;
+  }
+  const detectedEndpoints = extractEndpointsFromText(generatedCode);
+  if (!detectedEndpoints.length) { logger.info(`No endpoints in session ${sessionId}`); return; }
+  enqueue({
+    filePath: `compliance-session-${sessionId}`, fileName: `session_${sessionId}.js`,
+    fileContent: generatedCode, detectedEndpoints, timestamp,
+    source: "compliance_api", userId, devEmail, originalPrompt: prompt,
+  });
+}
+
+export async function handleGithubEvent(prEvent) {
+  const { prNumber, prTitle, author, authorEmail, files, combinedPatch, repoFullName, source } = prEvent;
+  const devEmail = authorEmail || getEmailForUser(null);
+  if (!devEmail) logger.warn(`PR #${prNumber} — no email resolved`);
+
+  const allEndpoints = new Set();
+  for (const f of files) extractEndpointsFromText(f.patch || "").forEach(ep => allEndpoints.add(ep));
+  if (!allEndpoints.size) { logger.info(`PR #${prNumber} — no endpoints in diff`); return; }
+
+  enqueue({
+    filePath: `github-pr-${prNumber}`, fileName: files[0]?.filename || `PR #${prNumber}`,
+    fileContent: combinedPatch, detectedEndpoints: [...allEndpoints],
+    timestamp: prEvent.timestamp, source, userId: null, devEmail,
+    originalPrompt: `GitHub PR #${prNumber}: ${prTitle} by ${author} on ${repoFullName}`,
+  });
+}
+
+// ── PROBLEM 4 — Merged batch queue ───────────────────────────────────────────
+
+function enqueue(event) {
+  const key  = `${event.devEmail}:${event.detectedEndpoints?.[0] || "?"}`;
+  const last = recentTriggers.get(key);
+
+  if (last && Date.now() - last < DEDUP_WINDOW_MS) {
+    logger.info(`Duplicate suppressed (${DEDUP_WINDOW_MS / 1000}s window): ${key}`);
+    return;
+  }
+  recentTriggers.set(key, Date.now());
+  for (const [k, ts] of recentTriggers) {
+    if (Date.now() - ts > DEDUP_WINDOW_MS * 3) recentTriggers.delete(k);
+  }
+
+  if (pipelineRunning) {
+    // Merge into pending batch — no duplicates, no separate executions
+    if (!pendingBatch) {
+      pendingBatch = {
+        ...event,
+        detectedEndpoints: new Set(event.detectedEndpoints || []),
+        fileNames: [event.fileName],
+      };
+      logger.info(`Pipeline busy — created pending batch for: ${event.fileName}`);
+    } else {
+      // Merge endpoints using Set
+      (event.detectedEndpoints || []).forEach(ep => pendingBatch.detectedEndpoints.add(ep));
+      pendingBatch.fileNames.push(event.fileName);
+      // Use most recent prompt/content
+      pendingBatch.fileContent    = event.fileContent;
+      pendingBatch.originalPrompt = event.originalPrompt;
+      logger.info(`Pipeline busy — merged into batch: ${event.fileName} (${pendingBatch.detectedEndpoints.size} total endpoints)`);
+    }
+    return;
+  }
+
+  runNext(event);
+}
+
+async function runNext(event) {
+  pipelineRunning = true;
+  try {
+    // Normalize event: convert Set → Array if needed
+    const normalized = {
+      ...event,
+      detectedEndpoints: event.detectedEndpoints instanceof Set
+        ? [...event.detectedEndpoints]
+        : (event.detectedEndpoints || []),
+    };
+    await runPhase1Pipeline(normalized);
+  } finally {
+    pipelineRunning = false;
+    if (pendingBatch) {
+      const batch = {
+        ...pendingBatch,
+        detectedEndpoints: [...pendingBatch.detectedEndpoints],
+        fileName: pendingBatch.fileNames.join(", "),
+      };
+      pendingBatch = null;
+      logger.info(`Running merged batch: ${batch.detectedEndpoints.length} endpoints from ${batch.fileNames?.length || 1} file(s)`);
+      runNext(batch);
+    }
+  }
+}
+
+// ── Main pipeline ─────────────────────────────────────────────────────────────
+
+export async function runPhase1Pipeline(event) {
+  const { fileName, fileContent, detectedEndpoints, originalPrompt, devEmail, source, jmxFilePath } = event;
+  const primaryEndpoint = detectedEndpoints?.[0] || "unknown";
+
+  console.log(`\n${"═".repeat(60)}`);
+  console.log(`OneQA — Pipeline triggered`);
+  console.log(`  Source    : ${source}`);
+  console.log(`  File      : ${fileName}`);
+  console.log(`  Endpoints : ${detectedEndpoints?.join(", ") || "none"}`);
+  console.log(`  Developer : ${devEmail || "none"}`);
+  console.log(`${"═".repeat(60)}\n`);
+
+  const start = Date.now();
+
+  try {
+    // 1. Validate endpoints
+    const endpoints = validateEndpoints(detectedEndpoints);
+    if (!endpoints) {
+      logger.warn("No valid endpoints — skipping pipeline.");
+      return { success: false, skipped: true, reason: "invalid_endpoints" };
+    }
+
+    // 2. Detect backend
+    logger.step("Detecting backend");
+    let backendUrl = await resolveBackendUrl();
+
+    if (!backendUrl) {
+      logger.warn("No running backend detected.");
+      logger.warn("Start your server (e.g. npm start / python app.py / go run main.go) then save any API file.");
+      await safeNotify({ devEmail, endpoints, fileName, source, reason: "No backend server found on common ports (3000, 5000, 8000, 8080, 4000, 8888). Start your server and save an API file to trigger again." });
+      return { success: false, skipped: true, reason: "backend_not_running" };
+    }
+
+    logger.info(`✅ Backend detected: ${backendUrl}`);
+
+    // 3. PROBLEM 1 — Auto-ngrok: ALWAYS use ngrok for localhost, regardless of config flag
+    if (isLocalhost(backendUrl)) {
+      logger.info("🔗 Localhost detected → enabling ngrok automatically");
+
+      if (!config.ngrok.authToken) {
+        logger.warn("⚠️  NGROK_AUTHTOKEN not set — tunnel may fail to authenticate");
+        logger.warn("   Get a free token at: https://dashboard.ngrok.com");
+      }
+
+      // PROBLEM 5 — Retry ngrok with clear failure handling
+      logger.step("Starting ngrok tunnel (auto-mode)");
+      let tunnelUrl = null;
+      let ngrokErr  = null;
+
+      for (let attempt = 1; attempt <= NGROK_MAX_RETRIES; attempt++) {
+        try {
+          tunnelUrl = await getPublicUrl(backendUrl);
+          break;
+        } catch (err) {
+          ngrokErr = err;
+          if (attempt < NGROK_MAX_RETRIES) {
+            logger.warn(`ngrok attempt ${attempt}/${NGROK_MAX_RETRIES} failed — retrying in ${NGROK_RETRY_DELAY / 1000}s (${err.message})`);
+            await sleep(NGROK_RETRY_DELAY);
+          }
+        }
+      }
+
+      if (!tunnelUrl) {
+        // PROBLEM 5 — Log clearly, notify, continue watcher — do NOT crash
+        const reason = `ngrok failed after ${NGROK_MAX_RETRIES} attempts: ${ngrokErr?.message}`;
+        logger.error(`ngrok failed after retries — skipping test`);
+        logger.error(`  Reason  : ${ngrokErr?.message}`);
+        logger.error(`  Fix     : Add NGROK_AUTHTOKEN to .env (https://dashboard.ngrok.com)`);
+        await safeNotify({ devEmail, endpoints, fileName, source, reason });
+        // System stays alive — return without crashing
+        return { success: false, skipped: true, reason: "ngrok_failed" };
+      }
+
+      backendUrl = tunnelUrl;
+      logger.info(`✅ ngrok tunnel ready: ${backendUrl}`);
+    }
+
+    // Hard stop — localhost must never reach KickLoad
+    if (isLocalhost(backendUrl)) {
+      logger.error("HARD STOP: localhost URL still present after ngrok step. Aborting.");
+      return { success: false, skipped: true, reason: "localhost_not_allowed" };
+    }
+
+    logger.info(`🚀 Test target: ${backendUrl}`);
+
+    // 4. Generate test prompt
+    logger.step("Generating test prompt");
+    const testParams = await generateTestPrompt({
+      fileContent, detectedEndpoints: endpoints, originalPrompt, fileName, backendBaseUrl: backendUrl,
+    });
+
+    // 5. KickLoad pipeline
+    const client = new KickloadClient(config.kickload.baseUrl, config.kickload.apiToken);
+
+    logger.step("Generating test plan");
+    const { jmx_filename: jmxFilename } = await withRetry(
+      () => client.generateTestPlan({ prompt: testParams.testPrompt, jmxFilePath: jmxFilePath || null }),
+      "generate-test-plan"
+    );
+
+    logger.step("Running test");
+    const { task_id: taskId } = await withRetry(
+      () => client.runTest(jmxFilename, { numThreads: testParams.numThreads, loopCount: testParams.loopCount, rampTime: testParams.rampTime }),
+      "run-test"
+    );
+
+    logger.step("Waiting for results");
+    const taskResult = await client.pollUntilDone(taskId);
+
+    logger.step("Analyzing results");
+    let analysisResult = { filename: taskResult.pdf_file };
+    if (taskResult.result_file) {
+      try {
+        analysisResult = await withRetry(() => client.analyzeJtl(taskResult.result_file), "analyze-jtl");
+      } catch (err) {
+        logger.warn(`JTL analysis failed (non-fatal): ${err.message}`);
+      }
+    }
+
+    const pdfFilename = analysisResult.filename || taskResult.pdf_file;
+    const downloadUrl = await client.getDownloadUrl(pdfFilename);
+    const totalMs     = Date.now() - start;
+
+    const summary = parseSummary(taskResult.summary_output || taskResult.summary);
+
+    logPipelineSummary({
+      endpoint:    endpoints.join(", "),
+      passed:      summary.passed,
+      latency:     summary.averageLatency,
+      errorRate:   summary.errorPercentage,
+      throughput:  summary.throughput,
+      durationSec: Math.round(totalMs / 1000),
+      emailSent:   !!devEmail,
+      devEmail,
+    });
+
+    // 6. Send result email — never let email failure kill the pipeline
+    if (devEmail) {
+      await safeResultEmail({
+        toEmail: devEmail, endpoint: endpoints.join(", "), passed: summary.passed,
+        summary, downloadUrl, pdfFilename, durationMs: totalMs, testPrompt: testParams.testPrompt,
+      });
+    }
+
+    return { success: true, backendUrl, jmxFilename, taskId, jtlFilename: taskResult.result_file, pdfFilename, downloadUrl, summary };
+
+  } catch (err) {
+    logger.error(`Pipeline failed: ${err.message}`);
+
+    if (devEmail) {
+      await safeResultEmail({
+        toEmail: devEmail, endpoint: primaryEndpoint, passed: false,
+        summary: { averageLatency: null, errorPercentage: null, throughput: null },
+        downloadUrl: null, pdfFilename: null, durationMs: Date.now() - start, testPrompt: "Pipeline failed",
+      });
+    }
+
+    return { success: false, error: err.message };
+  }
+}
+
+// ── Safe email wrappers (never throw) ────────────────────────────────────────
+
+async function safeResultEmail(params) {
+  const id = params.endpoint || "result";
+  if (!isEmailAllowed(params.toEmail, id)) {
+    logger.info(`Email cooldown: ${getCooldownRemaining(params.toEmail, id)}s — skipping`);
+    return;
+  }
+  try {
+    await sendResultEmail(params);
+    recordEmailSent(params.toEmail, id);
+  } catch (err) {
+    logger.error(`Email failed (pipeline continues): ${err.message}`);
+  }
+}
+
+async function safeNotify({ devEmail, endpoints, fileName, source, reason }) {
+  if (!devEmail) return;
+  const id = "backend-not-running";
+  if (!isEmailAllowed(devEmail, id)) {
+    logger.info(`Notification cooldown: ${getCooldownRemaining(devEmail, id)}s — skipping`);
+    return;
+  }
+  try {
+    await sendSkippedEmail({ toEmail: devEmail, endpoints, fileName, source, reason });
+    recordEmailSent(devEmail, id);
+  } catch (err) {
+    logger.error(`Notification email failed (non-fatal): ${err.message}`);
+  }
+}
+
+async function sendSkippedEmail({ toEmail, endpoints, fileName, source, reason }) {
+  const rows = endpoints.map(ep =>
+    `<tr><td style="padding:10px 16px;font-size:13px;color:#374151;font-family:monospace;">${ep}</td></tr>`
+  ).join("");
+
+  const html = `<!DOCTYPE html><html><body style="margin:0;padding:0;background:#f9fafb;font-family:Arial,sans-serif;">
+<table width="100%" cellpadding="0" cellspacing="0" style="padding:40px 20px;"><tr><td align="center">
+<table width="560" cellpadding="0" cellspacing="0" style="background:#fff;border-radius:12px;overflow:hidden;box-shadow:0 1px 3px rgba(0,0,0,.1);">
+<tr><td style="background:linear-gradient(135deg,#1e202a,#303952);padding:28px 32px;">
+  <h1 style="margin:0;color:#fff;font-size:20px;font-weight:800;">KickLoad Watcher</h1>
+  <p style="margin:4px 0 0;color:#9ca3af;font-size:13px;">OneQA — Automated API Testing</p>
+</td></tr>
+<tr><td style="padding:28px 32px 0;">
+  <div style="background:#fefce8;border:1px solid #fde68a;border-radius:10px;padding:16px 20px;">
+    <div style="font-size:18px;font-weight:800;color:#b45309;">⚠️ Testing Skipped</div>
+    <div style="font-size:13px;color:#92400e;margin-top:4px;">Backend server not reachable</div>
+  </div>
+</td></tr>
+<tr><td style="padding:20px 32px 0;"><p style="margin:0;color:#374151;font-size:14px;line-height:1.7;">
+  API changes detected in <strong>${fileName}</strong> but no backend was found. <strong>No tests ran. No KickLoad credits used.</strong>
+</p></td></tr>
+<tr><td style="padding:12px 32px 0;"><p style="margin:0;color:#dc2626;font-size:13px;">${reason || ""}</p></td></tr>
+<tr><td style="padding:20px 32px 0;">
+  <table width="100%" cellpadding="0" cellspacing="0" style="border:1px solid #e5e7eb;border-radius:8px;overflow:hidden;">
+    <tr style="background:#f9fafb;"><td style="padding:10px 16px;font-size:12px;font-weight:700;color:#9ca3af;text-transform:uppercase;border-bottom:1px solid #e5e7eb;">Detected endpoints</td></tr>
+    ${rows}
+  </table>
+</td></tr>
+<tr><td style="padding:20px 32px;">
+  <div style="background:#f0fdf4;border:1px solid #86efac;border-radius:8px;padding:14px 18px;">
+    <div style="font-size:13px;color:#166534;line-height:1.8;">
+      <strong>To trigger a test:</strong><br>
+      1. Start your backend (e.g. <code>npm start</code> / <code>python app.py</code> / <code>go run main.go</code>)<br>
+      2. Save any API file — the watcher will detect and test it automatically.
+    </div>
+  </div>
+</td></tr>
+<tr><td style="padding:16px 32px;"><p style="margin:0;color:#9ca3af;font-size:12px;text-align:center;">KickLoad Watcher · <a href="https://kickload.neeyatai.com" style="color:#f47c20;text-decoration:none;">NeeyatAI</a></p></td></tr>
+</table></td></tr></table></body></html>`;
+
+  const text =
+    `Testing Skipped — backend not reachable\n` +
+    `File: ${fileName}\nSource: ${source}\n` +
+    `Reason: ${reason || "unknown"}\n` +
+    `Endpoints: ${endpoints.join(", ")}\n\n` +
+    `To trigger a test:\n` +
+    `  1. Start your backend (npm start / python app.py / go run main.go)\n` +
+    `  2. Save any API file — the watcher will detect and run automatically.\n`;
+
+  const { _getTransporter } = await import("./email-sender.js");
+  const transporter = _getTransporter();
+  if (!transporter) { logger.warn("Email transporter not ready — skipping notification"); return; }
+
+  await transporter.sendMail({
+    from:    `"KickLoad Watcher" <${config.email.fromAddress}>`,
+    to:      toEmail,
+    subject: "API Testing Skipped — Backend Not Running",
+    html,
+    text,
+  });
+  logger.info(`📧 Notification → ${toEmail}`);
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function isLocalhost(url) {
+  return url.includes("localhost") || url.includes("127.0.0.1") || url.includes("0.0.0.0");
+}
+
+function validateEndpoints(endpoints) {
+  if (!Array.isArray(endpoints) || !endpoints.length) return null;
+  const valid = endpoints.filter(ep => typeof ep === "string" && ep.startsWith("/") && ep.length > 1);
+  return valid.length ? valid : null;
+}
+
+async function resolveBackendUrl() {
+  if (config.targetApiBaseUrl) {
+    logger.info(`Checking TARGET_API_BASE_URL: ${config.targetApiBaseUrl}`);
+    if (await isServerReachable(config.targetApiBaseUrl)) return config.targetApiBaseUrl;
+    logger.warn("TARGET_API_BASE_URL not reachable — scanning localhost");
+  }
+  return findRunningServer();
+}
+
+async function withRetry(fn, label) {
+  let lastErr;
+  for (let attempt = 1; attempt <= MAX_RETRIES + 1; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      const status = err.status || 0;
+      if (status >= 400 && status < 500 && status !== 429) throw err;
+      if (attempt <= MAX_RETRIES) {
+        logger.warn(`[${label}] attempt ${attempt} failed — retrying in ${RETRY_DELAY_MS / 1000}s (${err.message})`);
+        await sleep(RETRY_DELAY_MS);
+      }
+    }
+  }
+  throw lastErr;
+}
+
+function parseSummary(raw = {}) {
+  const avgLatency = raw?.averageLatency  ?? raw?.average_latency ?? null;
+  const errorPct   = raw?.errorPercentage ?? raw?.error_rate      ?? null;
+  const throughput = raw?.throughput      ?? null;
+  const isFail     = (errorPct !== null && errorPct > 5) || (avgLatency !== null && avgLatency > 2000);
+  return { passed: !isFail, averageLatency: avgLatency, errorPercentage: errorPct, throughput };
+}
+
+function extractEndpointsFromText(content) {
+  if (!content) return [];
+  const endpoints = new Set();
+  const pattern   = /['"`](\/[a-z0-9/_:.-]{2,})['"`]/gi;
+  let m;
+  while ((m = pattern.exec(content)) !== null) {
+    const ep = m[1];
+    if (ep.startsWith("/api") || ep.includes("/v1") || ep.includes("/v2")) endpoints.add(ep);
+  }
+  return [...endpoints];
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }

package/server-detector.js

@@ -0,0 +1,109 @@
+import http  from "http";
+import https from "https";
+import { createLogger } from "./logger.js";
+
+const logger           = createLogger("server-detector");
+const CANDIDATE_PORTS  = [3000, 5000, 8000, 8080, 4000, 8888];
+const PROBE_TIMEOUT_MS = 2000;
+
+export async function findRunningServer() {
+  const envPort  = process.env.BACKEND_PORT ? [parseInt(process.env.BACKEND_PORT)] : [];
+  const allPorts = [...new Set([...envPort, ...CANDIDATE_PORTS])];
+
+  logger.info(`Probing ${allPorts.length} ports for a running backend...`);
+
+  for (const port of allPorts) {
+    const url    = `http://localhost:${port}`;
+    const result = await probeBackend(url);
+    if (result.confirmed) {
+      logger.info(`Backend confirmed at ${url} — ${result.detail}`);
+      return url;
+    }
+    logger.debug(`Port ${port}: ${result.detail}`);
+  }
+
+  logger.warn(`No backend found on ports: ${allPorts.join(", ")}`);
+  return null;
+}
+
+export async function isServerReachable(baseUrl) {
+  const result = await probeBackend(baseUrl.replace(/\/$/, ""));
+  if (result.confirmed) {
+    logger.info(`Server reachable: ${baseUrl}`);
+    return true;
+  }
+  logger.warn(`Server not reachable: ${baseUrl} — ${result.detail}`);
+  return false;
+}
+
+async function probeBackend(baseUrl) {
+  const health = await httpProbe(`${baseUrl}/health`);
+
+  if (health.error === "ECONNREFUSED" || health.error === "timeout") {
+    return { confirmed: false, detail: `port closed (${health.error})` };
+  }
+
+  if (health.statusCode === 200) {
+    return { confirmed: true, detail: `/health → 200` };
+  }
+
+  const root = await httpProbe(`${baseUrl}/`);
+
+  if (root.error === "ECONNREFUSED" || root.error === "timeout") {
+    return { confirmed: false, detail: `/ unreachable (${root.error})` };
+  }
+
+  if (root.statusCode !== null) {
+    if (root.isHtml) {
+      logger.debug(`${baseUrl}/ returned HTML — likely frontend dev server`);
+    } else if (root.statusCode >= 200 && root.statusCode < 500) {
+      return { confirmed: true, detail: `/ → ${root.statusCode}` };
+    } else if (root.statusCode >= 500) {
+      return { confirmed: true, detail: `/ → ${root.statusCode} (server error)` };
+    }
+  }
+
+  const api = await httpProbe(`${baseUrl}/api`);
+  if (api.statusCode !== null && !api.isHtml && api.statusCode < 500) {
+    return { confirmed: true, detail: `/api → ${api.statusCode}` };
+  }
+
+  return { confirmed: false, detail: "all responses were HTML or empty" };
+}
+
+function httpProbe(url) {
+  return new Promise((resolve) => {
+    const lib     = url.startsWith("https") ? https : http;
+    let   settled = false;
+
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+
+    const timer = setTimeout(() => {
+      req.destroy();
+      settle({ statusCode: null, isHtml: false, error: "timeout" });
+    }, PROBE_TIMEOUT_MS);
+
+    const req = lib.get(url, { timeout: PROBE_TIMEOUT_MS }, (res) => {
+      const isHtml = (res.headers["content-type"] || "").toLowerCase().includes("text/html");
+      res.resume();
+      settle({ statusCode: res.statusCode, isHtml, error: null });
+    });
+
+    req.on("error", (err) => {
+      const code = err.code === "ECONNREFUSED" ? "ECONNREFUSED"
+                 : err.code === "ENOTFOUND"    ? "ENOTFOUND"
+                 : err.code                    || "unknown";
+      settle({ statusCode: null, isHtml: false, error: code });
+    });
+
+    req.on("timeout", () => {
+      req.destroy();
+      settle({ statusCode: null, isHtml: false, error: "timeout" });
+    });
+  });
+}