@myapihq/cli 2.6.0 → 2.6.1

package/dist/commands/doctor-findings.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/doctor-findings.test.js

@@ -0,0 +1,100 @@
+// Regression cover for three doctor findings reported from a live production
+// org, where two of four warnings described healthy things as broken.
+//
+// The shared defect: the check reported a CONCLUSION ("customers may not be
+// able to reach this", "no email inbox configured") where it only had an
+// OBSERVATION ("it answered 401", "the platform's counter said zero"). Each
+// test below pins the observation and refuses the conclusion.
+import { describe, it, expect } from 'vitest';
+import { classifyReachability, _setupSection } from './doctor.js';
+const ENTITY = { slot: 'container', name: 'skout-engine-prod' };
+describe('classifyReachability', () => {
+    // The finding: two containers behind an auth boundary were reported as
+    // "customers may not be able to reach" them. Both were up. A 401 to an
+    // anonymous probe is the designed answer and proves liveness.
+    it('treats 401 as reachable, not as a warning', () => {
+        const v = classifyReachability({ status: 401 }, ENTITY);
+        expect(v.severity).toBe('ok');
+        expect(v.message).toMatch(/reachable, authentication required/);
+    });
+    it('treats 403 the same way', () => {
+        expect(classifyReachability({ status: 403 }, ENTITY).severity).toBe('ok');
+    });
+    it('never tells the user customers cannot reach a URL that answered', () => {
+        for (const status of [200, 301, 401, 403, 404, 418, 500, 503]) {
+            const v = classifyReachability({ status }, ENTITY);
+            expect(v.hint ?? '').not.toMatch(/may not be able to reach/);
+        }
+    });
+    // Only a probe that got no answer at all is unreachable. That is the one
+    // case where the old wording was right.
+    it('reports a network failure as unreachable, and says why', () => {
+        const v = classifyReachability({ status: null, error: 'ETIMEDOUT' }, ENTITY);
+        expect(v.severity).toBe('warn');
+        expect(v.message).toMatch(/unreachable/);
+        expect(v.hint).toBe('ETIMEDOUT');
+    });
+    it('falls back to a customer-facing hint when there is no error string', () => {
+        const v = classifyReachability({ status: null }, ENTITY);
+        expect(v.hint).toMatch(/nothing answered/);
+    });
+    // Still warns, but distinguishes "the host answered and served nothing"
+    // from "the host is down" — a different problem with a different fix.
+    it('warns on 404 while stating the host answered', () => {
+        const v = classifyReachability({ status: 404 }, ENTITY);
+        expect(v.severity).toBe('warn');
+        expect(v.message).toMatch(/reachable, but nothing is served/);
+    });
+    it('warns on 5xx as an application error, not an outage', () => {
+        const v = classifyReachability({ status: 503 }, ENTITY);
+        expect(v.severity).toBe('warn');
+        expect(v.message).toMatch(/the application is erroring/);
+        expect(v.hint).toMatch(/logs/);
+    });
+    it('handles an entity with no name without printing undefined', () => {
+        const v = classifyReachability({ status: null }, { slot: 'funnel' });
+        expect(v.hint ?? '').not.toMatch(/undefined/);
+    });
+});
+// ── setup gaps ──────────────────────────────────────────────────────────────
+function report(sections) {
+    return {
+        org_id: '11111111-1111-4111-8111-111111111111',
+        sections: sections.map(s => ({ name: '', summary: '', issues: [], ...s })),
+    };
+}
+const ZERO_EMAILS = report([{ name: 'emails', resource_count: 0, issues: [] }]);
+function setupMessages(r, ctx) {
+    return (_setupSection(r, ctx)?.issues ?? []).map(i => ({ message: i.message, hint: i.hint ?? '' }));
+}
+describe('setup gaps are confirmed before they become instructions', () => {
+    // The finding: the platform reported resource_count 0 for an org with two
+    // active mailboxes, one of which had received mail 14 hours earlier. The
+    // doctor turned that into "Create one with: myapi email mailbox create …".
+    it('does not tell you to create a mailbox when we counted some', () => {
+        const [issue] = setupMessages(ZERO_EMAILS, { mailboxCount: 2 });
+        expect(issue.message).toMatch(/but 2 are configured/);
+        expect(issue.hint).toMatch(/Do not create another/);
+        expect(issue.hint).not.toMatch(/mailbox create/);
+    });
+    it('still reports a real gap when our own count agrees', () => {
+        const [issue] = setupMessages(ZERO_EMAILS, { mailboxCount: 0 });
+        expect(issue.message).toBe('No email inbox configured');
+        expect(issue.hint).toMatch(/mailbox create/);
+    });
+    // A failed enumeration is not evidence of absence OR presence, so the
+    // backend's view stands rather than us inventing a disagreement.
+    it('defers to the platform when we could not count', () => {
+        const [issue] = setupMessages(ZERO_EMAILS, {});
+        expect(issue.message).toBe('No email inbox configured');
+    });
+    it('gets the singular right', () => {
+        const [issue] = setupMessages(ZERO_EMAILS, { mailboxCount: 1 });
+        expect(issue.message).toMatch(/but 1 is configured/);
+    });
+    it('applies the same rule to domains', () => {
+        const r = report([{ name: 'domains', resource_count: 0, issues: [] }]);
+        expect(setupMessages(r, { domainCount: 3 })[0].message).toMatch(/but 3 are configured/);
+        expect(setupMessages(r, { domainCount: 0 })[0].hint).toMatch(/domain register/);
+    });
+});

package/dist/commands/doctor.d.ts

@@ -14,6 +14,19 @@ export declare function _tallyTotals(sections: sdkHq.DoctorSection[]): DoctorTot
 export declare function sanitizeHint(hint: string | undefined): string | undefined;
 export interface SetupContext {
     mailingAddress?: string | null;
+    mailboxCount?: number;
+    domainCount?: number;
 }
 export declare function _setupSection(report: sdkHq.DoctorReport, ctx?: SetupContext): sdkHq.DoctorSection | null;
+export declare function classifyReachability(probe: {
+    status: number | null;
+    error?: string;
+}, entity: {
+    slot: string;
+    name?: string;
+}): {
+    severity: 'ok' | 'warn';
+    message: string;
+    hint?: string;
+};
 export declare function run(_subcommand: string | undefined, _args: string[], flags: Flags): Promise<void>;

package/dist/commands/doctor.js

@@ -17,7 +17,7 @@
 // interleave with the backend's findings.
 import { promises as dns } from 'node:dns';
 import { createHash } from 'node:crypto';
-import { hq as sdkHq, container as sdkContainer, funnel as sdkFunnel } from '@myapihq/sdk';
+import { hq as sdkHq, container as sdkContainer, funnel as sdkFunnel, domain as sdkDomain, email as sdkEmail } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { info, error, printJson } from '../output.js';
 import { requireOrg } from '../helpers.js';
@@ -116,6 +116,32 @@ function isZeroState(section) {
         return section.resource_count === 0;
     return section.issues.length === 0;
 }
+// Emits the "you have not set this up" warning ONLY when our own count agrees
+// with the backend's. When we counted resources the backend says do not
+// exist, the disagreement replaces the advice — it is both true and more
+// useful, and it never sends anyone to recreate something that already
+// exists. When we did not count (`counted` undefined), the backend's view
+// stands, since a missing check is not evidence either way.
+function confirmedGap(o) {
+    if (typeof o.counted === 'number' && o.counted > 0) {
+        return {
+            id: localIssueId(`${o.idKey}_disagreement`, o.orgId),
+            severity: 'warn',
+            scope: o.scope,
+            category: 'setup',
+            message: `Platform reports no ${o.noun} for this org, but ${o.counted} ${o.counted === 1 ? 'is' : 'are'} configured`,
+            hint: `This is a reporting bug, not a setup gap — your ${o.noun}${o.counted === 1 ? '' : 'es'} ${o.counted === 1 ? 'is' : 'are'} fine. Do not create another.`,
+        };
+    }
+    return {
+        id: localIssueId(o.idKey, o.orgId),
+        severity: 'warn',
+        scope: o.scope,
+        category: 'setup',
+        message: o.absent,
+        hint: o.hint,
+    };
+}
 export function _setupSection(report, ctx = {}) {
     const byName = new Map();
     for (const s of report.sections)
@@ -123,25 +149,27 @@ export function _setupSection(report, ctx = {}) {
     const issues = [];
     const dom = byName.get('domains');
     if (dom && isZeroState(dom)) {
-        issues.push({
-            id: localIssueId('setup_no_domain', report.org_id),
-            severity: 'warn',
+        issues.push(confirmedGap({
+            orgId: report.org_id,
+            idKey: 'setup_no_domain',
             scope: 'setup/domain',
-            category: 'setup',
-            message: 'No domain registered for this org',
+            counted: ctx.domainCount,
+            noun: 'domain',
+            absent: 'No domain registered for this org',
             hint: 'Register one with: myapi domain register <domain> && myapi domain assign <domain>',
-        });
+        }));
     }
     const em = byName.get('emails');
     if (em && isZeroState(em)) {
-        issues.push({
-            id: localIssueId('setup_no_mailbox', report.org_id),
-            severity: 'warn',
+        issues.push(confirmedGap({
+            orgId: report.org_id,
+            idKey: 'setup_no_mailbox',
             scope: 'setup/email-inbox',
-            category: 'setup',
-            message: 'No email inbox configured',
+            counted: ctx.mailboxCount,
+            noun: 'email inbox',
+            absent: 'No email inbox configured',
             hint: 'Create one with: myapi email mailbox create <username>@<your-domain>',
-        });
+        }));
     }
     // Account-scoped (so use report.org_id only for the dedup id, not as
     // entity scope). Hard-gates every transactional `email send` —
@@ -253,17 +281,30 @@ async function httpProbeSection(apiKey, orgId) {
     }
     catch { /* augmentation is best-effort — skip the slot if enumeration fails */ }
     // Funnels: probe every published page URL.
+    //
+    // And probe the funnel's own subdomain when the page list comes back empty.
+    // A funnel serving a live site can report an empty inventory — verified
+    // 2026-07-28 on a funnel answering 200 with real content on both its
+    // subdomain and a bound custom domain while `GET .../pages` returned
+    // `{"pages":[]}`. Trusting that list meant the org's public landing page,
+    // the single most customer-visible URL it has, was silently dropped from
+    // the probe. A check that quietly narrows its own scope is worse than one
+    // that fails, so fall back rather than skip.
     try {
         const funnels = await sdkFunnel.listFunnels(apiKey, orgId);
         await Promise.all(funnels.map(async (f) => {
+            const name = f.name || f.id;
+            let pageUrls = [];
             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 } });
-                }
+                pageUrls = pages.map(p => p.url).filter((u) => !!u);
+            }
+            catch { /* fall through to the subdomain */ }
+            if (pageUrls.length === 0 && f.subdomain_url)
+                pageUrls = [f.subdomain_url];
+            for (const url of pageUrls) {
+                targets.push({ url, entity: { slot: 'funnel', id: f.id, name } });
             }
-            catch { /* skip this funnel */ }
         }));
     }
     catch { /* skip the slot */ }
@@ -272,29 +313,84 @@ async function httpProbeSection(apiKey, orgId) {
     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;
+        const verdict = classifyReachability(probe, entity);
         issues.push({
-            id: localIssueId(ok ? 'http_ok' : 'http_unreachable', `${entity.slot}/${entity.id}/${url}`),
-            severity: ok ? 'ok' : 'warn',
+            id: localIssueId(verdict.severity === 'ok' ? 'http_ok' : 'http_unreachable', `${entity.slot}/${entity.id}/${url}`),
+            severity: verdict.severity,
             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}"`),
+            message: `${url} ${verdict.message}`,
+            hint: verdict.hint,
         });
     }));
-    const warns = issues.filter(i => i.severity === 'warn').length;
+    // Only a probe that got NO response means unreachable. Everything else
+    // answered, so the summary must not call it unreachable — see
+    // classifyReachability.
+    const unreachable = issues.filter(i => i.severity === 'warn').length;
     return {
         name: 'reachability',
-        summary: warns
-            ? `${warns} of ${issues.length} URL${issues.length === 1 ? '' : 's'} unreachable`
+        summary: unreachable
+            ? `${unreachable} of ${issues.length} URL${issues.length === 1 ? '' : 's'} need attention`
             : `${issues.length} URL${issues.length === 1 ? '' : 's'} reachable`,
         issues,
     };
 }
+// What an HTTP status actually tells you about reachability.
+//
+// This check used to treat any status >= 400 as "unreachable" with the hint
+// "customers may not be able to reach <name>". A user ran it against a
+// healthy production org and got two such warnings, both for containers
+// behind an auth boundary that were answering 401 exactly as designed.
+//
+// The advice was backwards. A 401 is positive evidence: something answered,
+// and its auth boundary works. As they put it, if one of those URLs ever
+// answered 200 to an unauthenticated probe, THAT would be the emergency —
+// and the old check would have called it healthy.
+//
+// The cost of a false warning is not neutral. Two of them in one run teaches
+// the reader to skim past warnings, which is where the real ones live.
+//
+// So: reachability is about whether anything answered. Only a network
+// failure or timeout is unreachable. Statuses that answered but suggest a
+// problem are still reported — as what was observed, not as a conclusion
+// about customers.
+export function classifyReachability(probe, entity) {
+    const { status } = probe;
+    if (status == null) {
+        return {
+            severity: 'warn',
+            message: 'is unreachable',
+            hint: probe.error || `nothing answered — customers may not be able to reach ${entity.slot} "${entity.name ?? '(unnamed)'}"`,
+        };
+    }
+    // Answered and served.
+    if (status < 400)
+        return { severity: 'ok', message: `responded ${status}` };
+    // Answered and refused the anonymous probe. This is the designed behaviour
+    // of anything sitting behind auth, and it proves both liveness and that the
+    // boundary holds.
+    if (status === 401 || status === 403) {
+        return { severity: 'ok', message: `responded ${status} — reachable, authentication required` };
+    }
+    // Answered, but nothing is published at that path.
+    if (status === 404 || status === 410) {
+        return {
+            severity: 'warn',
+            message: `returned ${status} — reachable, but nothing is served at this URL`,
+            hint: `the host answers, so this is a routing or publish problem rather than an outage`,
+        };
+    }
+    if (status >= 500) {
+        return {
+            severity: 'warn',
+            message: `returned ${status} — reachable, but the application is erroring`,
+            hint: `check \`myapi ${entity.slot} logs\``,
+        };
+    }
+    // Any other 4xx: report the fact, draw no conclusion.
+    return { severity: 'warn', message: `returned ${status} — reachable` };
+}
 export async function run(_subcommand, _args, flags) {
     if (flags.help) {
         info(HELP);
@@ -330,7 +426,38 @@ export async function run(_subcommand, _args, flags) {
     catch {
         mailingAddress = undefined;
     }
-    const setup = _setupSection(report, { mailingAddress });
+    // Count mailboxes and domains ourselves before any "you have not set this
+    // up" advice goes out. Both are cheap list calls, and both are the
+    // difference between a true finding and an instruction to duplicate live
+    // infrastructure. `undefined` on failure means "not checked" — the backend
+    // view then stands, because a failed check is not evidence.
+    //
+    // Mailboxes are scoped per registered domain, so this walks the org's
+    // domains rather than asking for a bare list.
+    let mailboxCount;
+    let domainCount;
+    try {
+        // NOT filter:'all' — that is account-wide and spans every org, which
+        // would count another org's mailboxes against this one. The default
+        // filter is org-scoped, which is the only correct basis for a claim
+        // about "this org".
+        const domains = await sdkDomain.listDomains(apiKey, orgId);
+        domainCount = domains.length;
+        const perDomain = await Promise.all(domains.map(async (d) => {
+            try {
+                return (await sdkEmail.listMailboxes(apiKey, { domain: d.domain })).length;
+            }
+            catch {
+                return 0;
+            }
+        }));
+        mailboxCount = perDomain.reduce((a, b) => a + b, 0);
+    }
+    catch {
+        mailboxCount = undefined;
+        domainCount = undefined;
+    }
+    const setup = _setupSection(report, { mailingAddress, mailboxCount, domainCount });
     if (setup)
         report.sections.push(setup);
     const localSection = await dnsProbeSection(report);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myapihq/cli",
   "license": "Apache-2.0",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "description": "MyAPI command-line interface",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
     "lint:skills:strict": "node scripts/copy-skills.js && node scripts/lint-skills.js --strict"
   },
   "dependencies": {
-    "@myapihq/sdk": "^2.6.0"
+    "@myapihq/sdk": "^2.6.1"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",