@myapihq/cli 1.1.0-wip.4 → 1.2.0

package/dist/commands/storage.js

@@ -1,10 +1,20 @@
 import { readFile } from 'fs/promises';
 import { extname, basename } from 'path';
-import { storage as sdkStorage, STORAGE_BASE } from '@myapihq/sdk';
+import { storage as sdkStorage } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
+// Mirrors STORAGE_BASE in @myapihq/sdk's config (intentionally NOT
+// re-exported from the SDK barrel — see comment in sdk/src/index.ts).
+// Used here so `myapi storage get-url` is a pure local URL constructor.
+const STORAGE_BASE = process.env.MYAPI_STORAGE_URL ?? 'https://api.mystorageapi.com';
 import { success, error, printTable, info, printJson } from '../output.js';
 import { formatDate } from '../utils.js';
 import { requireOrg, requireArg } from '../helpers.js';
+export const EXPOSES = [
+    'POST /storage/orgs/{org_id}/assets/ingest',
+    'POST /storage/orgs/{org_id}/assets/upload',
+    'GET /storage/orgs/{org_id}/assets',
+    'DELETE /storage/orgs/{org_id}/assets/{asset_id}',
+];
 export const SCHEMA = {
     org: 'string',
     name: 'string',
@@ -16,6 +26,8 @@ const EXT_TO_CT = {
     '.jpeg': 'image/jpeg',
     '.gif': 'image/gif',
     '.webp': 'image/webp',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
 };
 function summarizeAsset(a) {
     return {
@@ -52,7 +64,7 @@ async function upload(filePath, flags) {
     const ext = extname(filePath).toLowerCase();
     const contentType = EXT_TO_CT[ext];
     if (!contentType) {
-        error(`Unsupported file extension "${ext}". Supported: ${Object.keys(EXT_TO_CT).join(', ')}.\n(SVG and non-image types — pdf/mp4/webm — go through "myapi storage ingest <url>" today.)`);
+        error(`Unsupported file extension "${ext}". Supported: ${Object.keys(EXT_TO_CT).join(', ')}.\n(SVG and PDF still go through "myapi storage ingest <url>" today.)`);
     }
     let data;
     try {

package/dist/commands/update.d.ts

@@ -1,4 +1,6 @@
 import type { Flags } from '../helpers.js';
+import type { Exposes } from '../exposes.js';
+export declare const EXPOSES: Exposes;
 export declare function checkForUpdate(currentVersion: string): Promise<void>;
 export declare function update(flags?: Flags): Promise<void>;
 export declare function latestVersion(): Promise<string | null>;

package/dist/commands/update.js

@@ -3,6 +3,9 @@ import { existsSync } from 'fs';
 import { loadConfig } from '../config.js';
 import { info, success, banner } from '../output.js';
 import { installSkills } from './setup.js';
+// `myapi update` only talks to the npm registry to check for new CLI versions
+// and to ./setup.ts for the skills install. No MyAPI backend endpoints.
+export const EXPOSES = [];
 const REGISTRY_URL = 'https://registry.npmjs.org/@myapihq/cli/latest';
 const PACKUMENT_URL = 'https://registry.npmjs.org/@myapihq/cli';
 // Verify the version is listed in the full packument — the same data source

package/dist/commands/url.d.ts

@@ -1,2 +1,7 @@
-export declare function shorten(targetUrl: string, flags: Record<string, string | boolean>): Promise<void>;
-export declare function run(subcommand: string | undefined, args: string[], flags: Record<string, string | boolean>): Promise<void>;
+import type { Exposes } from '../exposes.js';
+import type { Flags } from '../helpers.js';
+import type { FlagSchema } from '../flags.js';
+export declare const SCHEMA: FlagSchema;
+export declare const EXPOSES: Exposes;
+export declare function shorten(targetUrl: string, flags: Flags): Promise<void>;
+export declare function run(subcommand: string | undefined, args: string[], flags: Flags): Promise<void>;

package/dist/commands/url.js

@@ -1,6 +1,12 @@
 import { url as sdkUrl } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { success, error, info, printJson } from '../output.js';
+export const SCHEMA = {
+    org: 'string',
+};
+export const EXPOSES = [
+    'POST /url/orgs/{org_id}/shorten',
+];
 export async function shorten(targetUrl, flags) {
     const config = requireConfig();
     const orgId = flags.org || config.default_org;

package/dist/commands/verify.d.ts

@@ -0,0 +1,7 @@
+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 const VERIFY_HELP = "Usage: myapi verify <email> [--org <id>] [--json]\n\nSync single-address email verification. Cheap layer only: syntax + DNS +\nMicrosoft GetCredentialType. Returns a verdict in <1s for ~50% of inputs;\nthe rest get verdict='unknown' with smtp_recommended=true.\n\nVerdicts:\n  deliverable    high-confidence \u2014 the address accepts mail\n  undeliverable  high-confidence \u2014 syntax bad, DNS missing, or Microsoft rejects\n  unknown        not enough signal; consider an SMTP probe (not in this API)\n\nUse --json for the full check breakdown (syntax / DNS / Microsoft probes).\n";
+export declare function run(arg: string | undefined, _rest: string[], flags?: Flags): Promise<void>;

package/dist/commands/verify.js

@@ -0,0 +1,56 @@
+import { email as sdkEmail } from '@myapihq/sdk';
+import { requireConfig } from '../config.js';
+import { error, info, printJson } from '../output.js';
+import { requireOrg } from '../helpers.js';
+export const EXPOSES = [
+    'POST /email/orgs/{org_id}/verify',
+];
+export const SCHEMA = {
+    org: 'string',
+};
+export const VERIFY_HELP = `Usage: myapi verify <email> [--org <id>] [--json]
+
+Sync single-address email verification. Cheap layer only: syntax + DNS +
+Microsoft GetCredentialType. Returns a verdict in <1s for ~50% of inputs;
+the rest get verdict='unknown' with smtp_recommended=true.
+
+Verdicts:
+  deliverable    high-confidence — the address accepts mail
+  undeliverable  high-confidence — syntax bad, DNS missing, or Microsoft rejects
+  unknown        not enough signal; consider an SMTP probe (not in this API)
+
+Use --json for the full check breakdown (syntax / DNS / Microsoft probes).
+`;
+export async function run(arg, _rest, flags = {}) {
+    if (flags.help) {
+        info(VERIFY_HELP);
+        return;
+    }
+    if (!arg)
+        error('Missing required argument <email>.\nUsage: myapi verify <email> [--org <id>] [--json]');
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi verify <email> [--org <id>]');
+    const res = await sdkEmail.verifyEmail(config.api_key, orgId, arg);
+    if (flags.json) {
+        printJson(res);
+        return;
+    }
+    // Compact human render. The verdict + confidence is the headline; the
+    // checks block is verbose enough that we hide it behind --json.
+    const verdictLabel = res.verdict === 'deliverable' ? '✓ deliverable'
+        : res.verdict === 'undeliverable' ? '✗ undeliverable'
+            : '? unknown';
+    info(`Email:      ${res.email}`);
+    info(`Verdict:    ${verdictLabel}  (confidence ${res.confidence.toFixed(2)})`);
+    info(`SMTP next:  ${res.smtp_recommended ? 'yes — consider an SMTP probe' : 'no — verdict is definitive'}`);
+    info(`Took:       ${res.elapsed_ms}ms`);
+    if (res.checks.syntax.detail)
+        info(`Syntax:     ${res.checks.syntax.detail}`);
+    if (res.checks.dns && res.checks.dns.mx_records && res.checks.dns.mx_records.length > 0) {
+        const mx = res.checks.dns.mx_records.filter(Boolean);
+        if (mx.length > 0)
+            info(`MX:         ${mx.slice(0, 3).join(', ')}${mx.length > 3 ? ` (+${mx.length - 3} more)` : ''}`);
+    }
+    if (res.checks.microsoft)
+        info(`Microsoft:  ${res.checks.microsoft.verdict}`);
+}

package/dist/commands/webhook.d.ts

@@ -1,5 +1,7 @@
 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 list(flags: Flags): Promise<void>;
 export declare function create(nameArg: string | undefined, flags: Flags): Promise<void>;

package/dist/commands/webhook.js

@@ -2,10 +2,17 @@ import { webhook as sdkWebhook } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { success, error, printTable, info, printJson } from '../output.js';
 import { requireOrg } from '../helpers.js';
+export const EXPOSES = [
+    'POST /webhook/orgs/{org_id}/endpoints',
+    'GET /webhook/orgs/{org_id}/endpoints',
+    'DELETE /webhook/orgs/{org_id}/endpoints/{endpoint_id}',
+    'GET /webhook/orgs/{org_id}/deliveries/{delivery_id}',
+];
 export const SCHEMA = {
     org: 'string',
     name: 'string',
     description: 'string',
+    'crm-email-path': 'string',
 };
 export async function list(flags) {
     const config = requireConfig();
@@ -25,9 +32,17 @@ export async function create(nameArg, flags) {
     const orgId = requireOrg(flags, config, 'myapi webhook create <name> [--description <desc>] [--org <id>]');
     const name = nameArg || flags.name;
     if (!name)
-        error('Missing required arguments.\nUsage: myapi webhook create <name> [--description <desc>] [--org <id>]\n   or: myapi webhook create --name <name> [--description <desc>] [--org <id>]');
-    const description = flags.description;
-    const res = await sdkWebhook.createEndpoint(config.api_key, orgId, name, description);
+        error('Missing required arguments.\nUsage: myapi webhook create <name> [--description <desc>] [--crm-email-path <path>] [--org <id>]\n   or: myapi webhook create --name <name> [...]');
+    const opts = {};
+    if (typeof flags.description === 'string')
+        opts.description = flags.description;
+    if (typeof flags['crm-email-path'] === 'string')
+        opts.crm_email_path = flags['crm-email-path'];
+    const res = await sdkWebhook.createEndpoint(config.api_key, orgId, name, opts);
+    if (flags.json) {
+        printJson(res);
+        return;
+    }
     success(`Webhook created! ID: ${res.id}\nInbound URL: ${res.url}`);
 }
 export async function del(id, flags) {
@@ -49,10 +64,16 @@ export async function delivery(id, flags) {
 // ── Dispatcher ───────────────────────────────────────────────────────────────
 const SUBCOMMAND_USAGE = {
     'list': 'myapi webhook list [--org <id>] [--json]',
-    'create': `myapi webhook create <name> [--description <desc>] [--org <id>]
-       myapi webhook create --name <name> [--description <desc>] [--org <id>]
+    'create': `myapi webhook create <name> [--description <desc>] [--crm-email-path <path>] [--org <id>]
+       myapi webhook create --name <name> [...]
 
-Either form works; the positional name is the recommended shape.`,
+Either form works; the positional name is the recommended shape.
+
+CRM auto-ingest (optional):
+  --crm-email-path <dot-path>   Where to find the email in incoming payloads.
+                                Default 'email' (top-level). For Stripe:
+                                'data.object.customer_email'. For GitHub:
+                                'sender.email'. Empty string disables ingest.`,
     'delete': 'myapi webhook delete <id> [--org <id>]',
     'delivery': 'myapi webhook delivery <delivery_id> [--org <id>]',
 };
@@ -73,6 +94,10 @@ Payload contract:
   Whatever you POST is stored verbatim alongside headers + timestamp.
   Workflows reference fields with {{ payload.field }} templating.
 
+Discovering delivery IDs:
+  Each POST to an inbound URL responds with {"delivery_id":"<uuid>"}.
+  Capture it from the response, then pass to: myapi webhook delivery <id>
+
 Example — wire a contact form to email + Slack:
   WID=$(myapi webhook create "contact-form" --json | jq -r .id)
   myapi workflow create "Contact handler" --endpoint-id $WID --steps '[

package/dist/commands/workflow.d.ts

@@ -1,5 +1,7 @@
 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 list(flags: Flags): Promise<void>;
 export declare function get(id: string, flags: Flags): Promise<void>;

package/dist/commands/workflow.js

@@ -2,6 +2,17 @@ import { workflow as sdkWorkflow } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { success, error, printTable, info, printJson } from '../output.js';
 import { requireOrg } from '../helpers.js';
+export const EXPOSES = [
+    'POST /workflow/orgs/{org_id}/workflows',
+    'GET /workflow/orgs/{org_id}/workflows',
+    'GET /workflow/orgs/{org_id}/workflows/{workflow_id}',
+    'PATCH /workflow/orgs/{org_id}/workflows/{workflow_id}',
+    'DELETE /workflow/orgs/{org_id}/workflows/{workflow_id}',
+    'POST /workflow/orgs/{org_id}/workflows/{workflow_id}/enable',
+    'POST /workflow/orgs/{org_id}/workflows/{workflow_id}/disable',
+    'GET /workflow/orgs/{org_id}/workflows/{workflow_id}/runs',
+    'GET /workflow/orgs/{org_id}/runs/{run_id}',
+];
 export const SCHEMA = {
     org: 'string',
     name: 'string',
@@ -115,7 +126,7 @@ export async function create(nameArg, flags) {
     const name = nameArg || flags.name;
     const endpointId = flags['endpoint-id'];
     if (!name || !endpointId || !flags.steps) {
-        error('Missing required arguments.\nUsage: myapi workflow create <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]\n   or: myapi workflow create --name <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]');
+        error('Missing required arguments.\nUsage: myapi workflow create <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]\n   or: myapi workflow create --name <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]\n\n→ Step JSON shape is non-obvious. Run "myapi workflow create --help" or activate the my-workflow-api skill for examples.');
     }
     if (!UUID_RE.test(endpointId)) {
         error(`Invalid --endpoint-id "${endpointId}". Expected a webhook endpoint UUID.\nList your endpoints with: myapi webhook list`);
@@ -226,6 +237,8 @@ const SUBCOMMAND_USAGE = {
     'create': `myapi workflow create <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]
        myapi workflow create --name <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]
 
+→ For ready-to-use step recipes, activate the my-workflow-api skill.
+
 Either form works; the positional name is the recommended shape.
 
 --steps is a JSON array of step objects. Each step has a "type" field
@@ -284,6 +297,11 @@ export async function run(subcommand, args, flags) {
     if (!subcommand || (flags.help && !subcommand)) {
         info(`Usage: myapi workflow <subcommand>
 
+→ For ready-to-use examples and JSON step recipes, activate the my-workflow-api skill.
+  myapi workflow create requires --endpoint-id <webhook_id> and --steps <json_array>.
+  The step JSON shape is non-obvious — don't guess. Read the skill, or run:
+    myapi workflow create --help
+
 Subcommands:
   list                 List all workflows
   get <id>             Show a single workflow

package/dist/completion.d.ts

@@ -0,0 +1,3 @@
+export declare function initCompletion(): void;
+export declare function installCompletion(): void;
+export declare function uninstallCompletion(): void;

package/dist/completion.js

@@ -0,0 +1,78 @@
+// Shell autocomplete via omelette. Quietly active on every CLI run — when
+// the shell invokes us with the magic completion env vars, omelette's
+// init() handles the request and exits before we hit normal command
+// dispatch. On any other run, init() returns immediately.
+//
+// User installs the shell hook with `myapi completion install` (or
+// uninstalls with `myapi completion uninstall`). Supports bash, zsh, and
+// fish (handled internally by omelette).
+//
+// The tree below mirrors the dispatcher in index.ts and the per-command
+// switch statements. When you add a new top-level command or subcommand,
+// extend it here too — there's no automatic discovery.
+import omelette from 'omelette';
+const TREE = {
+    auth: ['link', 'switch', 'whoami', 'config', 'registrant'],
+    registrant: ['set', 'get', 'clear'],
+    org: ['create', 'delete', 'get', 'import', 'list', 'sync-brand', 'update'],
+    billing: ['balance', 'history', 'setup', 'topup'],
+    domain: ['assign', 'check', 'list', 'register', 'renew', 'settings', 'status', 'unassign', 'update-settings'],
+    funnel: ['create', 'delete', 'get', 'list', 'pages', 'push', 'verify'],
+    webhook: ['create', 'delete', 'delivery', 'list'],
+    workflow: ['create', 'delete', 'disable', 'enable', 'get', 'get-run', 'list', 'runs', 'update'],
+    email: ['mailbox', 'message', 'warmup', 'template', 'campaign', 'verify'],
+    image: ['delete', 'generate', 'get', 'get-url', 'list', 'models'],
+    storage: ['delete', 'get', 'get-url', 'ingest', 'list', 'upload'],
+    pixel: ['audience', 'events', 'identity', 'interactions', 'visits'],
+    people: ['search', 'get'],
+    company: ['search', 'get'],
+    audience: ['create', 'list', 'get', 'update', 'delete', 'members', 'refresh'],
+    llm: ['complete', 'embed', 'models'],
+    database: ['namespaces', 'create', 'delete-namespace', 'keys', 'get', 'set', 'del'],
+    crm: ['contacts', 'companies'],
+    contacts: ['list', 'search', 'create', 'get', 'update', 'delete', 'restore', 'promote', 'events'],
+    companies: ['list', 'search', 'create', 'get', 'update', 'delete', 'restore', 'promote'],
+    url: ['shorten'],
+    keys: ['create', 'list', 'revoke'],
+    'api-keys': ['create', 'list', 'revoke'],
+    config: ['view', 'set-org', 'set-funnel', 'set-domain'],
+    setup: [],
+    'import-key': [],
+    whoami: [],
+    status: [],
+    'install-skills': [],
+    update: [],
+    completion: ['install', 'uninstall'],
+    help: [],
+};
+const TOP_LEVEL = Object.keys(TREE).sort();
+const completion = omelette('myapi <command> <subcommand>');
+completion.on('command', ({ reply }) => reply(TOP_LEVEL));
+completion.on('subcommand', ({ before, reply, line }) => {
+    // omelette's `before` is the LAST word of the line, not the previous
+    // word. When the user has started typing a partial subcommand (e.g.
+    // "myapi audience l"), `before` is "l", not "audience" — so a naive
+    // `TREE[before]` returns undefined and tab completion silently fails.
+    // Detect the real parent command by checking whether the line ends in
+    // whitespace (no partial in flight → use `before`) vs. mid-word (partial
+    // in flight → use the previous word from the line).
+    const endsInSpace = /\s$/.test(line);
+    const parent = endsInSpace
+        ? before
+        : (line.trim().split(/\s+/).slice(-2, -1)[0] ?? before);
+    reply(TREE[parent] ?? []);
+});
+// Quiet no-op when shell isn't asking for completion. The first thing
+// index.ts should do is call this — omelette will short-circuit and
+// process.exit if a completion request is in flight.
+export function initCompletion() {
+    completion.init();
+}
+// Wire/unwire the shell rc snippet. Omelette writes a single eval line
+// into ~/.bashrc / ~/.zshrc / ~/.config/fish/config.fish.
+export function installCompletion() {
+    completion.setupShellInitFile();
+}
+export function uninstallCompletion() {
+    completion.cleanupShellInitFile();
+}

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { domain as sdkDomain } from '@myapihq/sdk';
 export interface AccountEntry {
     api_key: string;
     account_id: string;
@@ -5,6 +6,7 @@ export interface AccountEntry {
     default_org?: string;
     default_funnel?: string;
     default_domain?: string;
+    registrant?: sdkDomain.Registrant;
     is_anonymous?: boolean;
     skills_installed?: boolean;
 }

package/dist/exposes.d.ts

@@ -0,0 +1,2 @@
+export type Endpoint = `${'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'} /${string}`;
+export type Exposes = readonly Endpoint[];

package/dist/exposes.js

@@ -0,0 +1,13 @@
+// OpenAPI-templated endpoint declaration shared across CLI command modules.
+//
+// Each commands/<service>.ts file exports an `EXPOSES: Exposes` array listing
+// the backend endpoints that command (and its subcommands) cover. The
+// coverage check tool (S-102) walks these arrays and verifies every endpoint
+// in the published OpenAPI schema is reachable from at least one CLI command.
+//
+// Form: `<METHOD> <PATH>` where path uses `{name}` for variable segments
+// matching OpenAPI 3.x style. Examples:
+//   'POST /funnel/orgs/{org_id}/funnels'
+//   'GET /hq/billing/balance'
+//   'DELETE /domain/orgs/{org_id}/{domain}'
+export {};

package/dist/exposes.test.js

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as url from 'url';
+// Discover every command module the dispatcher imports. Each must export an
+// EXPOSES array so the coverage tool (S-102) can introspect the full CLI
+// surface.
+const COMMAND_MODULES = [
+    './commands/auth.js',
+    './commands/billing.js',
+    './commands/config.js',
+    './commands/crm/index.js',
+    './commands/crm/contacts.js',
+    './commands/crm/companies.js',
+    './commands/database.js',
+    './commands/domain.js',
+    './commands/email/index.js',
+    './commands/email/mailbox.js',
+    './commands/email/message.js',
+    './commands/email/template.js',
+    './commands/email/campaign.js',
+    './commands/email/warmup.js',
+    './commands/email/verify.js',
+    './commands/funnel.js',
+    './commands/image.js',
+    './commands/keys.js',
+    './commands/llm.js',
+    './commands/org.js',
+    './commands/pixel.js',
+    './commands/audience.js',
+    './commands/company.js',
+    './commands/people.js',
+    './commands/setup.js',
+    './commands/status.js',
+    './commands/storage.js',
+    './commands/update.js',
+    './commands/url.js',
+    './commands/webhook.js',
+    './commands/workflow.js',
+];
+const ENDPOINT_PATTERN = /^(GET|POST|PATCH|PUT|DELETE) \/[A-Za-z0-9_\-./{}]*$/;
+describe('every CLI command exports a typed EXPOSES array (S-101)', () => {
+    for (const modPath of COMMAND_MODULES) {
+        it(`${modPath} exports EXPOSES`, async () => {
+            const mod = await import(modPath);
+            expect(mod, `${modPath} did not import`).toBeDefined();
+            expect(mod.EXPOSES, `${modPath} missing EXPOSES export`).toBeDefined();
+            expect(Array.isArray(mod.EXPOSES), `${modPath} EXPOSES is not an array`).toBe(true);
+        });
+        it(`${modPath} EXPOSES entries are well-formed`, async () => {
+            const mod = await import(modPath);
+            const entries = mod.EXPOSES;
+            for (const entry of entries) {
+                expect(typeof entry, `${modPath}: non-string entry`).toBe('string');
+                expect(entry, `${modPath}: malformed entry "${entry}"`).toMatch(ENDPOINT_PATTERN);
+                // No double slashes, no trailing slash (except root), no whitespace
+                // beyond the single METHOD/PATH separator.
+                expect(entry.includes('//'), `${modPath}: double slash in "${entry}"`).toBe(false);
+            }
+        });
+    }
+});
+describe('EXPOSES coverage of CLI commands directory', () => {
+    it('every .ts file under commands/ is in COMMAND_MODULES (no orphans)', () => {
+        // Walk the source directory to catch any new command files that someone
+        // added without registering here. Keeps the test list in sync with reality.
+        const __filename = url.fileURLToPath(import.meta.url);
+        const commandsDir = path.resolve(path.dirname(__filename), 'commands');
+        const found = walkTs(commandsDir);
+        const declared = new Set(COMMAND_MODULES.map((m) => m.replace(/^\.\//, '').replace(/\.js$/, '.ts')));
+        for (const file of found) {
+            const rel = path.relative(path.dirname(__filename), file).replace(/\\/g, '/');
+            expect(declared.has(rel), `${rel} exists under commands/ but is not in COMMAND_MODULES — add it (and its EXPOSES) to keep coverage honest`).toBe(true);
+        }
+    });
+});
+function walkTs(dir) {
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const p = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...walkTs(p));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')) {
+            out.push(p);
+        }
+    }
+    return out;
+}
+// Compile-time check: ensure the Endpoint template literal type accepts
+// representative entries. If the type narrows in a way that breaks any of
+// these, the file won't compile.
+const _typeCheck = [
+    'GET /hq/billing/balance',
+    'POST /funnel/orgs/{org_id}/funnels',
+    'DELETE /domain/orgs/{org_id}/{domain}',
+    'PATCH /workflow/orgs/{org_id}/workflows/{id}',
+];
+void _typeCheck;

package/dist/flags.test.js

@@ -70,4 +70,88 @@ describe('parseFlags', () => {
         const { flags } = parseFlags(['--mystery=42'], SCHEMA);
         expect(flags.mystery).toBe('42');
     });
+    // ── S-405: Strict flag validation behavior ────────────────────────────────
+    //
+    // The CLI is intentionally LENIENT on unknown flags: they're tolerated as
+    // boolean/string values, with a stderr warning. This is by design — agents
+    // hallucinate flags occasionally, and breaking their script with a hard
+    // error on `--unknown-flag` is worse UX than warning + continuing.
+    //
+    // These tests lock in the documented behavior so it can't drift.
+    it('unknown flag with a following value-shaped token consumes that token', () => {
+        const { args, flags } = parseFlags(['funnel', 'create', '--on-error', 'simon@x.com'], SCHEMA);
+        expect(flags['on-error']).toBe('simon@x.com');
+        expect(args).toEqual(['funnel', 'create']);
+    });
+    it('unknown flag with no following token defaults to boolean true', () => {
+        const { flags } = parseFlags(['--mystery'], SCHEMA);
+        expect(flags.mystery).toBe(true);
+    });
+    it('unknown flag does not consume a token that looks like another flag', () => {
+        const { flags } = parseFlags(['--mystery', '--json'], SCHEMA);
+        expect(flags.mystery).toBe(true);
+        expect(flags.json).toBe(true);
+    });
+    it('emits a stderr warning when unknown flags are present', () => {
+        const stderrChunks = [];
+        const origWrite = process.stderr.write.bind(process.stderr);
+        process.stderr.write = (chunk) => { stderrChunks.push(String(chunk)); return true; };
+        try {
+            parseFlags(['--mystery', '--also-unknown'], SCHEMA);
+        }
+        finally {
+            process.stderr.write = origWrite;
+        }
+        const out = stderrChunks.join('');
+        expect(out).toMatch(/ignoring unknown flag/i);
+        expect(out).toMatch(/--mystery/);
+        expect(out).toMatch(/--also-unknown/);
+    });
+    it('respects MYAPI_QUIET_UNKNOWN_FLAGS to suppress the warning', () => {
+        const stderrChunks = [];
+        const origWrite = process.stderr.write.bind(process.stderr);
+        const origEnv = process.env.MYAPI_QUIET_UNKNOWN_FLAGS;
+        process.env.MYAPI_QUIET_UNKNOWN_FLAGS = '1';
+        process.stderr.write = (chunk) => { stderrChunks.push(String(chunk)); return true; };
+        try {
+            parseFlags(['--mystery'], SCHEMA);
+        }
+        finally {
+            process.stderr.write = origWrite;
+            if (origEnv === undefined)
+                delete process.env.MYAPI_QUIET_UNKNOWN_FLAGS;
+            else
+                process.env.MYAPI_QUIET_UNKNOWN_FLAGS = origEnv;
+        }
+        const out = stderrChunks.join('');
+        expect(out).not.toMatch(/ignoring unknown flag/);
+    });
+    it('emits no warning when there are no unknown flags', () => {
+        const stderrChunks = [];
+        const origWrite = process.stderr.write.bind(process.stderr);
+        process.stderr.write = (chunk) => { stderrChunks.push(String(chunk)); return true; };
+        try {
+            parseFlags(['--name', 'Acme', '--yes'], SCHEMA);
+        }
+        finally {
+            process.stderr.write = origWrite;
+        }
+        expect(stderrChunks.join('')).toBe('');
+    });
+    it('declared number flag with non-numeric value falls back to the raw string', () => {
+        const { flags } = parseFlags(['--years', 'not-a-number'], SCHEMA);
+        expect(flags.years).toBe('not-a-number');
+    });
+    it('declared boolean flag with --key=false sets it to false', () => {
+        const { flags } = parseFlags(['--no-enable=false'], SCHEMA);
+        expect(flags['no-enable']).toBe(false);
+    });
+    it('declared boolean flag with --key=0 sets it to false', () => {
+        const { flags } = parseFlags(['--no-enable=0'], SCHEMA);
+        expect(flags['no-enable']).toBe(false);
+    });
+    it('declared boolean flag with --key=true is truthy', () => {
+        const { flags } = parseFlags(['--no-enable=true'], SCHEMA);
+        expect(flags['no-enable']).toBe(true);
+    });
 });