@myapihq/cli 1.3.1 → 1.3.4

package/dist/commands/doctor.d.ts

@@ -0,0 +1,6 @@
+import type { FlagSchema } from '../flags.js';
+import { type Flags } from '../helpers.js';
+import type { Exposes } from '../exposes.js';
+export declare const EXPOSES: Exposes;
+export declare const SCHEMA: FlagSchema;
+export declare function run(_subcommand: string | undefined, _args: string[], flags: Flags): Promise<void>;

package/dist/commands/doctor.js

@@ -0,0 +1,281 @@
+// `myapi doctor` — thin client over the backend's GET /hq/orgs/{org_id}/doctor.
+//
+// The backend computes the heavy reference-integrity / orphan / activity
+// 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 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 { 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;
+const C = useColor ? {
+    ok: '\x1b[32m', warn: '\x1b[33m', err: '\x1b[31m',
+    dim: '\x1b[2m', bold: '\x1b[1m', reset: '\x1b[0m',
+} : { ok: '', warn: '', err: '', dim: '', bold: '', reset: '' };
+const MARK = {
+    ok: `${C.ok}✓${C.reset}`,
+    warn: `${C.warn}⚠${C.reset}`,
+    crit: `${C.err}✗${C.reset}`,
+};
+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) {
+    // 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.
+// The backend can verify domain provisioning state from its own egress;
+// this checks whether the operator's network reaches them today — a
+// different epistemic signal worth surfacing on top of the backend's view.
+async function dnsProbeSection(report) {
+    const names = new Set();
+    for (const s of report.sections) {
+        for (const i of s.issues) {
+            if (i.entity?.slot === 'domain' && i.entity.name)
+                names.add(i.entity.name);
+        }
+    }
+    if (names.size === 0)
+        return null;
+    const issues = [];
+    await Promise.all([...names].map(async (name) => {
+        try {
+            const ips = await dns.resolve4(name);
+            issues.push({
+                id: localIssueId('dns_local_ok', name),
+                severity: 'ok',
+                scope: `local/${name}`,
+                entity: { slot: 'domain', id: '', name },
+                category: 'network',
+                message: `${name} resolves from your network${ips.length ? ` (${ips[0]}${ips.length > 1 ? ` +${ips.length - 1}` : ''})` : ''}`,
+            });
+        }
+        catch (e) {
+            issues.push({
+                id: localIssueId('dns_local_fail', name),
+                severity: 'warn',
+                scope: `local/${name}`,
+                entity: { slot: 'domain', id: '', name },
+                category: 'network',
+                message: `${name} did not resolve from your network`,
+                hint: e?.code || e?.message || String(e),
+            });
+        }
+    }));
+    const warns = issues.filter(i => i.severity === 'warn').length;
+    return {
+        name: 'local network',
+        summary: warns ? `${warns} resolution failure${warns === 1 ? '' : 's'}` : `${issues.length} domain${issues.length === 1 ? '' : 's'} resolved`,
+        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);
+        return;
+    }
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi doctor [--json] [--verbose]');
+    const apiKey = config.api_key;
+    const verbose = !!flags.verbose;
+    const wantJson = !!flags.json;
+    let report;
+    try {
+        report = await sdkHq.getDoctor(apiKey, orgId);
+    }
+    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) {
+            // 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;
+    }
+    info(`${C.bold}Org doctor${C.reset}  ${C.dim}· org ${report.org_id}${C.reset}  ${C.dim}· ${report.generated_at}${C.reset}`);
+    for (const s of report.sections) {
+        info('');
+        info(`${C.bold}# ${s.name}${C.reset}  ${C.dim}· ${s.summary}${C.reset}`);
+        for (const i of s.issues) {
+            if (!verbose && i.severity === 'ok')
+                continue;
+            info(fmtIssue(i));
+        }
+    }
+    info('');
+    info(rule(60));
+    if (totals.crit) {
+        info(`${MARK.crit} ${totals.crit} critical, ${MARK.warn} ${totals.warn} warning${totals.warn === 1 ? '' : 's'}`);
+    }
+    else if (totals.warn) {
+        info(`${MARK.warn} ${totals.warn} warning${totals.warn === 1 ? '' : 's'}, no critical issues`);
+    }
+    else {
+        info(`${MARK.ok} ${totals.ok} check${totals.ok === 1 ? '' : 's'} passed`);
+    }
+    if (!verbose)
+        info(`${C.dim}(--verbose to show passing checks · --json for machine-readable)${C.reset}`);
+}
+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 run from this machine's network.
+
+Sections returned by the backend today:
+  funnels, webhooks, workflows, domains, containers, emails, payments
+
+Local additions:
+  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)
+  1  one or more critical issues
+
+Options:
+  --verbose    Show passing checks too.
+  --json       Machine-readable output.
+  --org <id>   Override the default org.`;

package/dist/completion.js

@@ -28,7 +28,7 @@ const BLOCK_END = `# end ${PROGRAM} completion`;
 export const COMMANDS = [
     'audience', 'auth', 'billing', 'company', 'completion', 'config', 'container',
     'crm', 'database', 'domain', 'email', 'fn', 'funnel', 'git', 'help', 'image',
-    'install-skills', 'keys', 'llm', 'org', 'payments', 'people', 'pixel', 'queue',
+    'doctor', 'install-skills', 'keys', 'llm', 'org', 'payments', 'people', 'pixel', 'queue',
     'setup', 'status', 'storage', 'task', 'update', 'url', 'webhook', 'whoami',
     'workflow',
 ];

package/dist/exposes.test.js

@@ -43,6 +43,7 @@ const COMMAND_MODULES = [
     './commands/git.js',
     './commands/queue.js',
     './commands/task.js',
+    './commands/doctor.js',
 ];
 const ENDPOINT_PATTERN = /^(GET|POST|PATCH|PUT|DELETE) \/[A-Za-z0-9_\-./{}]*$/;
 describe('every CLI command exports a typed EXPOSES array (S-101)', () => {

package/dist/index.js

@@ -35,6 +35,7 @@ import * as containerCmd from './commands/container.js';
 import * as gitCmd from './commands/git.js';
 import * as queueCmd from './commands/queue.js';
 import * as taskCmd from './commands/task.js';
+import * as doctorCmd from './commands/doctor.js';
 // Each command file declares the value flags it understands. We union them
 // into a single schema for the upfront parse, so adding a new value flag in
 // one command means editing one file (its SCHEMA), not a global allowlist.
@@ -66,6 +67,7 @@ const COMBINED_SCHEMA = {
     ...gitCmd.SCHEMA,
     ...queueCmd.SCHEMA,
     ...taskCmd.SCHEMA,
+    ...doctorCmd.SCHEMA,
     // Top-level flags
     version: 'boolean',
     V: 'boolean',
@@ -234,6 +236,9 @@ async function main() {
             case 'task':
                 await taskCmd.run(subcommand, restArgs, flags);
                 break;
+            case 'doctor':
+                await doctorCmd.run(subcommand, restArgs, flags);
+                break;
             // Convenience aliases
             case 'setup':
                 await setupCmd.setup(flags);
@@ -360,6 +365,7 @@ const HELP_TARGETS = {
     git: f => gitCmd.run(undefined, [], f),
     queue: f => queueCmd.run(undefined, [], f),
     task: f => taskCmd.run(undefined, [], f),
+    doctor: f => doctorCmd.run(undefined, [], f),
     org: f => orgCmd.run(undefined, [], f),
     billing: f => billingCmd.run(undefined, [], f),
     keys: f => keysCmd.run(undefined, [], f),
@@ -406,6 +412,7 @@ Commands:
   git             Hosted git repositories — repos, commits, branches, history
   queue           Durable job queue — enqueue work, retried against an HTTP consumer
   task            Agent-task queue — file, claim, and resolve units of work
+  doctor          Org-wide consistency check — funnels, webhooks, domains, containers
   payments        Take payments with Stripe Checkout (connect, charge, refund)
   webhook         Manage inbound webhook endpoints and inspect deliveries
   email           Manage mailboxes, send/read email, templates, and campaigns

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myapihq/cli",
   "license": "Apache-2.0",
-  "version": "1.3.1",
+  "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.1"
+    "@myapihq/sdk": "^1.3.4"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",