@myapihq/cli 1.3.2 → 1.3.4

package/dist/commands/doctor.js

@@ -4,15 +4,29 @@
 // checks across slots and returns a structured report. The CLI's job is:
 //   1. fetch the report,
 //   2. augment with *customer-perspective* probes the backend structurally
-//      can't run (today: DNS resolution from the user's network),
+//      can't run from its own egress: DNS resolution and HTTP reachability
+//      from the user's network,
 //   3. render with section grouping, color, and exit codes for CI.
+//
+// Division of labour (a contract, not an accident): the backend owns
+// configuration / reference-integrity / orphan checks; the client owns
+// liveness probes (DNS, HTTP). The backend must NOT HTTP-probe — it has no
+// customer-vantage egress — and the client must not re-derive config state.
+// Augmented sections are therefore appended *last*: client-observed checks
+// are a distinct epistemic class (observed now, from here) and shouldn't
+// interleave with the backend's findings.
 import { promises as dns } from 'node:dns';
-import { hq as sdkHq } from '@myapihq/sdk';
+import { createHash } from 'node:crypto';
+import { hq as sdkHq, container as sdkContainer, funnel as sdkFunnel } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { info, error, printJson } from '../output.js';
 import { requireOrg } from '../helpers.js';
 export const EXPOSES = [
     'GET /hq/orgs/{org_id}/doctor',
+    // Read-only enumeration for the HTTP reachability augmentation pass.
+    'GET /container/orgs/{org_id}/containers',
+    'GET /funnel/orgs/{org_id}/funnels',
+    'GET /funnel/orgs/{org_id}/funnels/{funnel_id}/pages',
 ];
 export const SCHEMA = {};
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
@@ -28,8 +42,20 @@ const MARK = {
 function rule(width = 60) {
     return `${C.dim}${'─'.repeat(width)}${C.reset}`;
 }
+// Stable, dedupable id for a client-generated issue, matching the backend's
+// opaque `kind/<hash>` shape. The human-readable form lives in scope/message;
+// the id stays a single-slash key so consumers can split it the same way
+// they split backend ids (a raw URL in the id would break that).
+function localIssueId(kind, key) {
+    return `${kind}/${createHash('sha256').update(key).digest('hex').slice(0, 16)}`;
+}
 function fmtIssue(i) {
-    const head = `  ${MARK[i.severity] ?? '·'} ${i.message}`;
+    // Prefix the entity name so sibling issues with identical messages
+    // (e.g. four "domain is active" rows) are distinguishable. Skip it when
+    // the message already names the entity — the local DNS section does.
+    const name = i.entity?.name;
+    const label = name && !i.message.includes(name) ? `${C.bold}${name}${C.reset} — ` : '';
+    const head = `  ${MARK[i.severity] ?? '·'} ${label}${i.message}`;
     return i.hint ? `${head}\n    ${C.dim}→ ${i.hint}${C.reset}` : head;
 }
 // Local DNS-resolution probe for every distinct domain the report names.
@@ -51,7 +77,7 @@ async function dnsProbeSection(report) {
         try {
             const ips = await dns.resolve4(name);
             issues.push({
-                id: `dns_local_ok/${name}`,
+                id: localIssueId('dns_local_ok', name),
                 severity: 'ok',
                 scope: `local/${name}`,
                 entity: { slot: 'domain', id: '', name },
@@ -61,7 +87,7 @@ async function dnsProbeSection(report) {
         }
         catch (e) {
             issues.push({
-                id: `dns_local_fail/${name}`,
+                id: localIssueId('dns_local_fail', name),
                 severity: 'warn',
                 scope: `local/${name}`,
                 entity: { slot: 'domain', id: '', name },
@@ -78,6 +104,91 @@ async function dnsProbeSection(report) {
         issues,
     };
 }
+// One HTTP GET with an 8s ceiling. Returns the final status code (after
+// redirects) or, on a network/timeout failure, a null status + error string.
+async function fetchStatus(url) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 8000);
+    try {
+        const res = await fetch(url, { method: 'GET', redirect: 'follow', signal: ctrl.signal });
+        // Drain the body so the socket can be released — we only want the status.
+        await res.body?.cancel().catch(() => { });
+        return { status: res.status };
+    }
+    catch (e) {
+        const error = e?.name === 'AbortError'
+            ? 'timed out after 8s'
+            : (e?.cause?.code || e?.code || e?.message || String(e));
+        return { status: null, error };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// Customer-perspective HTTP reachability probe. The backend reports whether a
+// funnel/container is *configured* consistently; it can't tell from its own
+// egress whether the published URL actually answers. This fetches every
+// container URL and funnel page the org exposes and surfaces the status.
+//
+// Like the DNS probe, a failed fetch is `warn`, never `crit`: a single
+// request from one machine at one instant isn't authoritative enough to fail
+// CI — it's a signal to act on, layered over the backend's config view.
+async function httpProbeSection(apiKey, orgId) {
+    const targets = [];
+    // Containers: probe the bound custom domain when set (what customers hit),
+    // else the Cloud Run URL. An undeployed container has neither — skip it.
+    try {
+        const containers = await sdkContainer.listContainers(apiKey, orgId);
+        for (const c of containers) {
+            const url = c.custom_domain ? `https://${c.custom_domain}` : c.url;
+            if (url)
+                targets.push({ url, entity: { slot: 'container', id: c.id, name: c.name } });
+        }
+    }
+    catch { /* augmentation is best-effort — skip the slot if enumeration fails */ }
+    // Funnels: probe every published page URL.
+    try {
+        const funnels = await sdkFunnel.listFunnels(apiKey, orgId);
+        await Promise.all(funnels.map(async (f) => {
+            try {
+                const pages = await sdkFunnel.listFunnelPages(apiKey, orgId, f.id);
+                for (const p of pages) {
+                    if (p.url)
+                        targets.push({ url: p.url, entity: { slot: 'funnel', id: f.id, name: f.name || f.id } });
+                }
+            }
+            catch { /* skip this funnel */ }
+        }));
+    }
+    catch { /* skip the slot */ }
+    if (targets.length === 0)
+        return null;
+    const issues = [];
+    await Promise.all(targets.map(async ({ url, entity }) => {
+        const probe = await fetchStatus(url);
+        // 2xx/3xx = reachable. 4xx, 5xx and network failures are all `warn`.
+        const ok = probe.status != null && probe.status < 400;
+        issues.push({
+            id: localIssueId(ok ? 'http_ok' : 'http_unreachable', `${entity.slot}/${entity.id}/${url}`),
+            severity: ok ? 'ok' : 'warn',
+            scope: `local/${url}`,
+            entity,
+            category: 'network',
+            message: ok
+                ? `${url} responded ${probe.status}`
+                : `${url} ${probe.status != null ? `returned ${probe.status}` : 'is unreachable'}`,
+            hint: ok ? undefined : (probe.error || `customers may not be able to reach ${entity.slot} "${entity.name}"`),
+        });
+    }));
+    const warns = issues.filter(i => i.severity === 'warn').length;
+    return {
+        name: 'reachability',
+        summary: warns
+            ? `${warns} of ${issues.length} URL${issues.length === 1 ? '' : 's'} unreachable`
+            : `${issues.length} URL${issues.length === 1 ? '' : 's'} reachable`,
+        issues,
+    };
+}
 export async function run(_subcommand, _args, flags) {
     if (flags.help) {
         info(HELP);
@@ -95,14 +206,28 @@ export async function run(_subcommand, _args, flags) {
     catch (e) {
         error(`doctor endpoint failed: ${e?.message ?? String(e)}`);
     }
+    // Local augmentation, appended after the backend's sections by design —
+    // see the file header on why client-observed checks stay grouped at the end.
     const localSection = await dnsProbeSection(report);
     if (localSection)
         report.sections.push(localSection);
+    const reachSection = await httpProbeSection(apiKey, orgId);
+    if (reachSection)
+        report.sections.push(reachSection);
     // Re-tally totals after local augmentation.
     const totals = { ok: 0, warn: 0, crit: 0 };
-    for (const s of report.sections)
-        for (const i of s.issues)
-            totals[i.severity]++;
+    for (const s of report.sections) {
+        for (const i of s.issues) {
+            // Ignore any severity the backend invents that we don't model — better
+            // a missed count than a NaN poisoning the whole tally.
+            if (i.severity in totals)
+                totals[i.severity]++;
+        }
+    }
+    // Set the exit code before any output branch — CI relies on it in both
+    // the human and the --json path.
+    if (totals.crit)
+        process.exitCode = 1;
     if (wantJson) {
         printJson({ ...report, totals });
         return;
@@ -121,7 +246,6 @@ export async function run(_subcommand, _args, flags) {
     info(rule(60));
     if (totals.crit) {
         info(`${MARK.crit} ${totals.crit} critical, ${MARK.warn} ${totals.warn} warning${totals.warn === 1 ? '' : 's'}`);
-        process.exitCode = 1;
     }
     else if (totals.warn) {
         info(`${MARK.warn} ${totals.warn} warning${totals.warn === 1 ? '' : 's'}, no critical issues`);
@@ -136,13 +260,16 @@ const HELP = `Usage: myapi doctor [--verbose] [--json] [--org <id>]
 
 Org-wide consistency check. Fetches the structured report from the backend
 (GET /hq/orgs/{org_id}/doctor) and augments it with customer-perspective
-probes (DNS resolution from this machine's network).
+probes run from this machine's network.
 
 Sections returned by the backend today:
   funnels, webhooks, workflows, domains, containers, emails, payments
 
 Local additions:
-  network    — DNS resolution from your egress for each domain mentioned.
+  local network — DNS resolution from your egress for each domain mentioned.
+  reachability  — HTTP GET to every container URL and funnel page; surfaces
+                  the status code. Failures are warnings, never critical —
+                  a single fetch isn't authoritative enough to fail CI.
 
 Exit codes:
   0  no critical issues (warnings allowed)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myapihq/cli",
   "license": "Apache-2.0",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "MyAPI command-line interface",
   "type": "module",
   "files": [
@@ -29,7 +29,7 @@
     "lint:changelog": "node ../../scripts/lint-changelog.js"
   },
   "dependencies": {
-    "@myapihq/sdk": "^1.3.2"
+    "@myapihq/sdk": "^1.3.4"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",