@mondaydotcomorg/z2h-cli 0.27.0 → 0.28.0

package/dist/esm/constants.mjs

@@ -1,3 +1,5 @@
+export { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS } from '@mondaydotcomorg/z2h-shared-utils';
+
 /**
  * Cross-file constants. Narrowly-used literals (templates, prefixes used in
  * one place) stay local to their file to keep this index small.
@@ -55,11 +57,6 @@ const DATAVIZ_SKILLS_PREFIX = 'dataviz/';
 // upfront for friendlier errors.
 const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{1,49}$/;
 const PREVIEW_APP_NAME_PREFIX = 'zth-preview-';
-// ─────────── Declared (OAuth-gated) backend integrations ─────
-// Closed set the CLI detects from handler sources and the broker validates on
-// register/update. Always-on channels (`db`, `llm`, `snowflake`) are not listed —
-// the runner builds those regardless. Shared via `@mondaydotcomorg/z2h-cli/constants`.
-const DECLARED_INTEGRATIONS = ['monday'];
 // ─────────── Broker origin + npm registry (shared §3 contract) ─────
 // The bigbrain-zth broker fronts both the STS credential route and the npm
 // proxy. `Z2H_BROKER_BASE_URL` overrides the origin for tests/staging.
@@ -101,4 +98,4 @@ function brokerNpmRegistryUrl() {
     return `${brokerBaseUrl()}${NPM_BROKER_PATH}`;
 }
 
-export { APP_NAME_PATTERN, BROKER_NPM_SCOPE, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, DATAVIZ_SKILLS_PREFIX, DECLARED_INTEGRATIONS, DEFAULT_BROKER_BASE_URL, GITIGNORE_ENTRIES, MANIFEST_KEY, MANIFEST_READ_URL, MAX_PORT, MIN_PORT, NPM_BROKER_PATH, PREVIEW_APP_NAME_PREFIX, PUBLIC_NPM_REGISTRY_URL, REGION, S3_PREVIEWS_FOLDER, S3_SKILLS_BUCKET_NAME, SHADOW_DEV_DEPS, SHADOW_DIR_NAME, SHADOW_SCRIPTS, Z2H_NPM_TOKEN_ENV, brokerBaseUrl, brokerNpmRegistryUrl, routingHeaders };
+export { APP_NAME_PATTERN, BROKER_NPM_SCOPE, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, DATAVIZ_SKILLS_PREFIX, DEFAULT_BROKER_BASE_URL, GITIGNORE_ENTRIES, MANIFEST_KEY, MANIFEST_READ_URL, MAX_PORT, MIN_PORT, NPM_BROKER_PATH, PREVIEW_APP_NAME_PREFIX, PUBLIC_NPM_REGISTRY_URL, REGION, S3_PREVIEWS_FOLDER, S3_SKILLS_BUCKET_NAME, SHADOW_DEV_DEPS, SHADOW_DIR_NAME, SHADOW_SCRIPTS, Z2H_NPM_TOKEN_ENV, brokerBaseUrl, brokerNpmRegistryUrl, routingHeaders };

package/dist/esm/index.mjs

@@ -17,7 +17,7 @@ import { generateZ2HTokenCommand } from './commands/generate-z2h-token.mjs';
 import { migrateCommand } from './commands/migrate.mjs';
 import { tagCommand } from './commands/tag.mjs';
 import { editCommand } from './commands/edit.mjs';
-import { backendInvokeCommand } from './commands/backend.mjs';
+import { backendValidateCommand, backendInvokeCommand } from './commands/backend.mjs';
 import { doctorCommand } from './commands/doctor.mjs';
 import { fail, errorLog, setOutputMode, getOutputMode } from './util/logger.mjs';
 import { runCommand } from './util/run-command.mjs';
@@ -170,7 +170,11 @@ async function main() {
         .action(runCommand({ data: cwdApp }, (opts) => deleteCommand(opts)));
     const backend = program
         .command('backend')
-        .description("Inspect the app's backend: invoke a deployed handler by name");
+        .description("Inspect the app's backend: validate handler sources or invoke a deployed handler by name");
+    backend
+        .command('validate')
+        .description('Validate backend/handlers/*.js exactly as deploy would (syntax, isolate rules, integrations) without uploading')
+        .action(runCommand({ data: cwdApp }, () => backendValidateCommand()));
     backend
         .command('invoke <handlerName>')
         .description('Invoke a deployed backend handler by name (the filename without .ts) — mainly for testing a handler without going through the frontend')

package/dist/index.js

@@ -176,7 +176,11 @@ async function main() {
         .action(util_runCommand.runCommand({ data: cwdApp }, (opts) => commands_delete.deleteCommand(opts)));
     const backend = program
         .command('backend')
-        .description("Inspect the app's backend: invoke a deployed handler by name");
+        .description("Inspect the app's backend: validate handler sources or invoke a deployed handler by name");
+    backend
+        .command('validate')
+        .description('Validate backend/handlers/*.js exactly as deploy would (syntax, isolate rules, integrations) without uploading')
+        .action(util_runCommand.runCommand({ data: cwdApp }, () => commands_backend.backendValidateCommand()));
     backend
         .command('invoke <handlerName>')
         .description('Invoke a deployed backend handler by name (the filename without .ts) — mainly for testing a handler without going through the frontend')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -51,8 +51,10 @@
   ],
   "dependencies": {
     "@aws-sdk/client-s3": "^3.706.0",
-    "@mondaydotcomorg/z2h-dashboard-templates": "^0.3.3",
-    "@mondaydotcomorg/z2h-shared-utils": "^0.5.0",
+    "@mondaydotcomorg/z2h-dashboard-templates": "^0.3.4",
+    "@mondaydotcomorg/z2h-shared-utils": "^0.6.0",
+    "acorn": "^8.14.0",
+    "acorn-walk": "^8.3.4",
     "chokidar": "^3.6.0",
     "commander": "^12.1.0",
     "cors": "^2.8.6",

package/src/backend/__tests__/ast.test.ts

@@ -0,0 +1,53 @@
+import { parse, type ExpressionStatement, type Program } from 'acorn';
+import { describe, expect, it } from 'vitest';
+import { collectBindings, createPathResolver } from '../ast';
+
+const program = (source: string): Program => parse(source, { ecmaVersion: 'latest', sourceType: 'script' });
+
+/** Resolves the expression in the program's last statement. */
+const resolveLast = (source: string, contextParam?: string) => {
+  const p = program(source);
+  const last = p.body[p.body.length - 1] as ExpressionStatement;
+  return createPathResolver(collectBindings(p), contextParam).pathOf(last.expression);
+};
+
+describe('createPathResolver', () => {
+  it('returns the literal chain when nothing is aliased', () => {
+    expect(resolveLast('ctx.api.v1.db.get;')).toBe('ctx.api.v1.db.get');
+  });
+
+  it('treats computed string literals as static keys', () => {
+    expect(resolveLast('ctx.api.v1["db"].get;')).toBe('ctx.api.v1.db.get');
+    expect(resolveLast("const { ['db']: store } = ctx.api.v1; store.get;")).toBe('ctx.api.v1.db.get');
+  });
+
+  it('returns undefined for dynamic links and non-identifier roots', () => {
+    expect(resolveLast('ctx.api.v1[db].get;')).toBeUndefined();
+    expect(resolveLast('fn().db;')).toBeUndefined();
+    expect(resolveLast('"x";')).toBeUndefined();
+  });
+
+  it('rewrites the handler context parameter to ctx', () => {
+    expect(resolveLast('context.api.v1.db.get;', 'context')).toBe('ctx.api.v1.db.get');
+    expect(resolveLast('const sf = context.api.v1.snowflake; sf.query;', 'context')).toBe('ctx.api.v1.snowflake.query');
+  });
+
+  it('follows const aliases, including destructuring and chains', () => {
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; sf.query;')).toBe('ctx.api.v1.snowflake.query');
+    expect(resolveLast('const { v1 } = ctx.api; v1.db;')).toBe('ctx.api.v1.db');
+    expect(resolveLast('const { v1: { db: store } } = ctx.api; store.get;')).toBe('ctx.api.v1.db.get');
+    expect(resolveLast('const a = ctx.api; const b = a.v1; const c = b.db; c;')).toBe('ctx.api.v1.db');
+  });
+
+  it('leaves unpinnable names as written', () => {
+    expect(resolveLast('let sf = ctx.api.v1.snowflake; sf.query;')).toBe('sf.query');
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; sf = 1; sf.query;')).toBe('sf.query');
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; function f(sf) {} sf.query;')).toBe('sf.query');
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; { const sf = 1; } sf.query;')).toBe('sf.query');
+    expect(resolveLast('const [sf] = ctx.api; sf.query;')).toBe('sf.query');
+  });
+
+  it('does not loop on circular aliases', () => {
+    expect(resolveLast('const a = b.x; const b = a.y; a.z;')).toBe('a.y.x.z');
+  });
+});

package/src/backend/__tests__/detect-integrations.test.ts

@@ -1,42 +1,24 @@
 import { describe, expect, it } from 'vitest';
-import { detectIntegrationsFromHandlers } from '../detect-integrations';
+import { detectIntegrations } from '../detect-integrations';
 
-describe('detectIntegrationsFromHandlers', () => {
-  it('returns [] when handlers are empty', () => {
-    expect(detectIntegrationsFromHandlers({})).toEqual([]);
+describe('detectIntegrations', () => {
+  it('returns [] when no domains are touched', () => {
+    expect(detectIntegrations([])).toEqual([]);
   });
 
-  it('returns [] when sources never touch ctx.api.v1.monday', () => {
-    expect(
-      detectIntegrationsFromHandlers({
-        ping: 'async function handler(ctx) { return ctx.db.get("x"); }',
-        q: 'async function handler(ctx) { return ctx.api.v1.snowflake.runQuery("select 1"); }',
-      })
-    ).toEqual([]);
+  it('ignores always-on channels', () => {
+    expect(detectIntegrations(['db', 'llm', 'snowflake'])).toEqual([]);
   });
 
-  it('detects monday from ctx.api.v1.monday', () => {
-    expect(
-      detectIntegrationsFromHandlers({
-        boards: 'async function handler(ctx) {\n  return ctx.api.v1.monday.query("{ boards { id } }");\n}',
-      })
-    ).toEqual(['monday']);
+  it('ignores unknown domains', () => {
+    expect(detectIntegrations(['totallyMadeUp'])).toEqual([]);
   });
 
-  it('dedupes across handlers', () => {
-    expect(
-      detectIntegrationsFromHandlers({
-        a: 'ctx.api.v1.monday.query("x")',
-        b: 'ctx.api.v1.monday.query("y"); ctx.api.v1.snowflake.runQuery("z")',
-      })
-    ).toEqual(['monday']);
+  it('keeps declared integrations', () => {
+    expect(detectIntegrations(['snowflake', 'monday', 'db'])).toEqual(['monday']);
   });
 
-  it('ignores lookalike identifiers that are not ctx.api.v1.monday', () => {
-    expect(
-      detectIntegrationsFromHandlers({
-        a: 'const monday = 1; api.v1.monday; ctx.api.v2.monday',
-      })
-    ).toEqual([]);
+  it('dedupes', () => {
+    expect(detectIntegrations(['monday', 'monday'])).toEqual(['monday']);
   });
 });

package/src/backend/__tests__/handlers.test.ts

@@ -1,10 +1,15 @@
 import path from 'node:path';
 import os from 'node:os';
 import { mkdtemp, rm, ensureDir, writeFile } from 'fs-extra';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { readHandlers } from '../handlers';
 
+vi.mock('../../util/tracker', () => ({
+  trackEvent: vi.fn().mockResolvedValue(undefined),
+  trackDuration: vi.fn(),
+}));
+
 let appDir: string;
 
 const writeHandler = (name: string, source: string) =>
@@ -23,16 +28,14 @@ describe('readHandlers — discovery', () => {
   it('returns empty handlers when backend/handlers does not exist', async () => {
     const dir = await mkdtemp(path.join(os.tmpdir(), 'z2h-empty-'));
     try {
-      const result = await readHandlers(dir);
-      expect(result.handlers).toEqual({});
+      await expect(readHandlers(dir)).resolves.toEqual({ handlers: {}, apiDomains: [] });
     } finally {
       await rm(dir, { recursive: true, force: true });
     }
   });
 
   it('returns empty handlers when the directory is empty', async () => {
-    const result = await readHandlers(appDir);
-    expect(result.handlers).toEqual({});
+    await expect(readHandlers(appDir)).resolves.toEqual({ handlers: {}, apiDomains: [] });
   });
 
   it('uses the filename (without .js) as the handler name', async () => {
@@ -57,43 +60,27 @@ describe('readHandlers — output contract', () => {
     expect(handlers['my_handler']).toBe(source);
   });
 
-  it.each([
-    ['a function declaration', 'async function handler(ctx) { return 1; }'],
-    ['a const arrow', 'const handler = async (ctx) => 1;'],
-    ['a var assignment', 'var handler = async function(ctx) { return 1; };'],
-  ])('accepts %s', async (_label, source) => {
-    await writeHandler('h.js', source);
-    await expect(readHandlers(appDir)).resolves.toMatchObject({ handlers: { h: expect.any(String) } });
+  it('merges the ctx.api.v1 domains touched across all handlers, sorted and unique', async () => {
+    await writeHandler('a.js', 'async function handler(ctx) { return ctx.api.v1.monday.query("x"); }');
+    await writeHandler(
+      'b.js',
+      'async function handler(ctx) { ctx.api.v1.db.get("k"); return ctx.api.v1.monday.query("y"); }'
+    );
+    const { apiDomains } = await readHandlers(appDir);
+    expect(apiDomains).toEqual(['db', 'monday']);
   });
 });
 
+// Per-shape validation rules are covered in validate.test.ts; here we only prove
+// that readHandlers runs the validator and names the offending file.
 describe('readHandlers — validation', () => {
-  it('rejects a file that does not define handler', async () => {
-    await writeHandler('bad.js', 'async function main(ctx) { return 1; }');
-    await expect(readHandlers(appDir)).rejects.toThrow(/must define a handler/);
-  });
-
-  it('rejects import statements', async () => {
-    await writeHandler('bad.js', "import { foo } from './utils';\nasync function handler(ctx) { return foo; }");
-    await expect(readHandlers(appDir)).rejects.toThrow(/must not import/);
-  });
-
-  it('rejects require calls', async () => {
-    await writeHandler('bad.js', "const foo = require('./utils');\nasync function handler(ctx) { return foo; }");
-    await expect(readHandlers(appDir)).rejects.toThrow(/must not import/);
-  });
-
   it('rejects .ts handler files with a clear message', async () => {
     await writeHandler('call_snowflake.ts', 'async function handler(ctx) { return 1; }');
     await expect(readHandlers(appDir)).rejects.toThrow(/TypeScript handlers are not yet supported/);
   });
 
-  it.each([
-    ['an exported function declaration', 'export async function handler(ctx) { return 1; }'],
-    ['an exported const', 'export const handler = async (ctx) => 1;'],
-    ['a default-exported function', 'export default async function handler(ctx) { return 1; }'],
-  ])('rejects %s — the isolate has no module system', async (_label, source) => {
-    await writeHandler('bad.js', source);
-    await expect(readHandlers(appDir)).rejects.toThrow(/must not export handler/);
+  it('surfaces validation errors with the filename', async () => {
+    await writeHandler('bad.js', 'async function handler(ctx) {\n  return ctx.input.(;\n}');
+    await expect(readHandlers(appDir)).rejects.toThrow(/^bad\.js:2:19: not valid JavaScript/);
   });
 });

package/src/backend/__tests__/parse.test.ts

@@ -0,0 +1,25 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { trackEvent } from '../../util/tracker';
+import { parseOrThrow } from '../parse';
+
+vi.mock('../../util/tracker', () => ({
+  trackEvent: vi.fn().mockResolvedValue(undefined),
+  trackDuration: vi.fn(),
+}));
+
+const track = vi.mocked(trackEvent);
+
+describe('parseOrThrow — telemetry', () => {
+  afterEach(() => {
+    track.mockClear();
+  });
+
+  it('tracks the same message it throws', () => {
+    expect(() => parseOrThrow('h.js', 'async function handler(ctx) {\n  return ctx.input.(;\n}')).toThrow(
+      'h.js:2:19: not valid JavaScript — Unexpected token'
+    );
+    expect(track).toHaveBeenCalledWith('z2h_cli_handler_parse_error', {
+      error: 'h.js:2:19: not valid JavaScript — Unexpected token',
+    });
+  });
+});

package/src/backend/__tests__/validate.test.ts

@@ -0,0 +1,246 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { warn } from '../../util/logger';
+import { validateHandlerSource } from '../validate';
+
+vi.mock('../../util/logger');
+vi.mock('../../util/tracker', () => ({
+  trackEvent: vi.fn().mockResolvedValue(undefined),
+  trackDuration: vi.fn(),
+}));
+const warnMock = vi.mocked(warn);
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+const validate = (source: string) => validateHandlerSource('h.js', source);
+
+describe('validateHandlerSource — accepted shapes', () => {
+  it.each([
+    ['a function declaration', 'async function handler(ctx) { return 1; }'],
+    ['a const arrow', 'const handler = async (ctx) => 1;'],
+    ['a let function expression', 'let handler = async function (ctx) { return 1; };'],
+    ['a var assignment', 'var handler = async function(ctx) { return 1; };'],
+    ['a handler wrapped by a call', 'const handler = wrap(async (ctx) => 1); function wrap(f) { return f; }'],
+  ])('accepts %s', (_label, source) => {
+    expect(() => validate(source)).not.toThrow();
+  });
+
+  it('does not reject require() mentioned in a comment', () => {
+    expect(() => validate('// never call require() in here\nasync function handler(ctx) { return 1; }')).not.toThrow();
+  });
+
+  it('does not reject "import" at the start of a line inside a string', () => {
+    expect(() =>
+      validate('const help = `\nimport nothing here\n`;\nasync function handler(ctx) { return help; }')
+    ).not.toThrow();
+  });
+
+  it('accepts sloppy-mode-only syntax, because the isolate runs sloppy scripts', () => {
+    expect(() => validate('function handler(ctx) { with (ctx) { return input; } }')).not.toThrow();
+  });
+});
+
+describe('validateHandlerSource — handler declaration', () => {
+  it('rejects a file that does not define handler', () => {
+    expect(() => validate('async function main(ctx) { return 1; }')).toThrow(/must define a handler/);
+  });
+
+  it('rejects a handler declared only inside another function', () => {
+    expect(() => validate('function outer() { async function handler(ctx) { return 1; } }')).toThrow(
+      /must define a handler/
+    );
+  });
+
+  it.each([
+    ['a number', 'const handler = 42;'],
+    ['an object', 'const handler = { run() {} };'],
+    ['an array', 'const handler = [];'],
+    ['a template literal', 'const handler = `x`;'],
+    ['nothing (uninitialized)', 'let handler;'],
+  ])('rejects handler bound to %s', (_label, source) => {
+    expect(() => validate(source)).toThrow(/declares handler but it is not a function/);
+  });
+});
+
+describe('validateHandlerSource — module syntax (the isolate compiles plain scripts)', () => {
+  it.each([
+    ['an exported function declaration', 'export async function handler(ctx) { return 1; }'],
+    ['an exported const', 'export const handler = async (ctx) => 1;'],
+    ['a default-exported function', 'export default async function handler(ctx) { return 1; }'],
+    ['an export specifier', 'async function handler(ctx) { return 1; }\nexport { handler };'],
+    ['a default-exported identifier', 'async function handler(ctx) { return 1; }\nexport default handler;'],
+  ])('rejects %s', (_label, source) => {
+    expect(() => validate(source)).toThrow(/must not export handler/);
+  });
+
+  it.each([
+    ['an import statement', "import { foo } from './utils';\nasync function handler(ctx) { return foo; }"],
+    ['export * from', "export * from './utils';\nasync function handler(ctx) { return 1; }"],
+    ['export { x } from', "export { foo } from './utils';\nasync function handler(ctx) { return 1; }"],
+    ['a top-level require call', "const foo = require('./utils');\nasync function handler(ctx) { return foo; }"],
+    ['a nested require call', "async function handler(ctx) { const foo = require('./utils'); return foo; }"],
+    ['a dynamic import()', "async function handler(ctx) { const m = await import('./x'); return m; }"],
+  ])('rejects %s', (_label, source) => {
+    expect(() => validate(source)).toThrow(/must not import/);
+  });
+
+  it.each([
+    ['an export of a non-handler name', 'export const helper = 1;\nasync function handler(ctx) { return helper; }'],
+    ['an anonymous default export', 'export default async (ctx) => 1;'],
+  ])('rejects %s', (_label, source) => {
+    expect(() => validate(source)).toThrow(/must not use export/);
+  });
+
+  it.each([
+    ['top-level await', 'const cfg = await Promise.resolve(1);\nasync function handler(ctx) { return cfg; }'],
+    ['import.meta', 'async function handler(ctx) { return import.meta.url; }'],
+  ])('rejects %s', (_label, source) => {
+    expect(() => validate(source)).toThrow(/uses module-only syntax/);
+  });
+});
+
+describe('validateHandlerSource — syntax errors', () => {
+  it('reports file, line and column', () => {
+    expect(() => validate('async function handler(ctx) {\n  return ctx.input.(;\n}')).toThrow(
+      /^h\.js:2:19: not valid JavaScript — Unexpected token$/
+    );
+  });
+
+  it('rejects a top-level return, which V8 rejects in scripts', () => {
+    expect(() => validate('return 1;\nasync function handler(ctx) { return 1; }')).toThrow(/not valid JavaScript/);
+  });
+});
+
+describe('validateHandlerSource — capability rules', () => {
+  it('runs the rule set once the handler is structurally valid', () => {
+    expect(() => validate('async function handler(ctx) { return ctx.api.v1.snowflake.query(ctx.input.sql); }')).toThrow(
+      /snowflake\.query must receive SQL written in the handler/
+    );
+  });
+
+  it('runs snowflake SQL rules through a renamed handler parameter', () => {
+    expect(() =>
+      validate('async function handler(context) { return context.api.v1.snowflake.query(context.input.sql); }')
+    ).toThrow(/snowflake\.query must receive SQL written in the handler/);
+  });
+
+  it('runs snowflake SQL rules through computed channel access', () => {
+    expect(() =>
+      validate('async function handler(ctx) { return ctx.api.v1["snowflake"].query(ctx.input.sql); }')
+    ).toThrow(/snowflake\.query must receive SQL written in the handler/);
+  });
+
+  it('runs snowflake SQL rules through a wrapped handler with a renamed parameter', () => {
+    expect(() =>
+      validate(
+        'const handler = wrap(async (context) => context.api.v1.snowflake.query(context.input.sql)); function wrap(f) { return f; }'
+      )
+    ).toThrow(/snowflake\.query must receive SQL written in the handler/);
+  });
+
+  it('reports structural problems before rule violations', () => {
+    expect(() => validate('async function main(ctx) { return ctx.api.v1.snowflake.query(ctx.input.sql); }')).toThrow(
+      /must define a handler/
+    );
+  });
+
+  it('still returns api domains when every rule passes', () => {
+    expect(
+      validate('async function handler(ctx) { return ctx.api.v1.snowflake.query("select 1", { id: ctx.input.id }); }')
+        .apiDomains
+    ).toEqual(['snowflake']);
+  });
+});
+
+describe('validateHandlerSource — ctx.api.v1 domains', () => {
+  it('returns every domain touched, sorted and unique', () => {
+    const { apiDomains } = validate(
+      'async function handler(ctx) { await ctx.api.v1.db.put("k", 1); ctx.api.v1.monday.query("x"); return ctx.api.v1.db.get("k"); }'
+    );
+    expect(apiDomains).toEqual(['db', 'monday']);
+  });
+
+  it('sees through optional chaining', () => {
+    expect(validate('async function handler(ctx) { return ctx?.api?.v1?.monday?.query("x"); }').apiDomains).toEqual([
+      'monday',
+    ]);
+  });
+
+  it('ignores domains mentioned only in comments or strings', () => {
+    const { apiDomains } = validate(
+      '// TODO: use ctx.api.v1.monday later\nasync function handler(ctx) { return "ctx.api.v1.monday"; }'
+    );
+    expect(apiDomains).toEqual([]);
+  });
+
+  it('follows const aliases of the api object', () => {
+    expect(
+      validate('async function handler(ctx) { const { v1 } = ctx.api; return v1.monday.query("x"); }').apiDomains
+    ).toEqual(['monday']);
+    expect(
+      validate('const api = ctx.api.v1;\nasync function handler(ctx) { const m = api.monday; return m.query("x"); }')
+        .apiDomains
+    ).toEqual(['monday']);
+  });
+
+  it('sees string-literal computed access', () => {
+    expect(
+      validate("async function handler(ctx) { return ctx.api.v1['snowflake'].query('select 1'); }").apiDomains
+    ).toEqual(['snowflake']);
+    expect(validate('async function handler(ctx) { return ctx.api.v1["monday"].query("x"); }').apiDomains).toEqual([
+      'monday',
+    ]);
+  });
+
+  it('sees domains through a renamed handler parameter', () => {
+    expect(validate('async function handler(context) { return context.api.v1.db.list(); }').apiDomains).toEqual(['db']);
+    expect(validate('const handler = async (context) => context.api.v1.monday.query("x");').apiDomains).toEqual([
+      'monday',
+    ]);
+    expect(
+      validate('const handler = async function (context) { return context.api.v1.db.list(); };').apiDomains
+    ).toEqual(['db']);
+    expect(validate('async function* handler(context) { yield context.api.v1.db.list(); }').apiDomains).toEqual(['db']);
+    expect(
+      validate('const handler = async function* (context) { yield context.api.v1.db.list(); };').apiDomains
+    ).toEqual(['db']);
+  });
+
+  it('sees domains when the handler function is wrapped or has a default argument', () => {
+    expect(
+      validate('const handler = wrap(async (context) => context.api.v1.db.list()); function wrap(f) { return f; }')
+        .apiDomains
+    ).toEqual(['db']);
+    expect(validate('const handler = (0, async (context) => context.api.v1.monday.query("x"));').apiDomains).toEqual([
+      'monday',
+    ]);
+    expect(validate('async function handler(context = {}) { return context.api.v1.db.list(); }').apiDomains).toEqual([
+      'db',
+    ]);
+  });
+
+  it('ignores lookalikes that are not ctx.api.v1.<domain>', () => {
+    const { apiDomains } = validate(
+      'async function handler(ctx) { const monday = 1; api.v1.monday; ctx.api.v2.monday; ctx.api.v1[monday]; return monday; }'
+    );
+    expect(apiDomains).toEqual([]);
+  });
+
+  it('does not warn for known domains', () => {
+    validate('async function handler(ctx) { return ctx.api.v1.snowflake.query("select 1"); }');
+    expect(warnMock).not.toHaveBeenCalled();
+  });
+
+  it('warns, but does not throw, for an unknown domain — this is DX feedback, not a security boundary', () => {
+    expect(() => validate('async function handler(ctx) { return ctx.api.v1.totallyMadeUp.get(); }')).not.toThrow();
+    expect(warnMock).toHaveBeenCalledWith(
+      expect.stringMatching(/ctx\.api\.v1\.totallyMadeUp is not a known capability/)
+    );
+  });
+
+  it('warns once per unknown domain, not once per usage', () => {
+    validate('async function handler(ctx) { ctx.api.v1.madeUp.get(); return ctx.api.v1.madeUp.post(); }');
+    expect(warnMock).toHaveBeenCalledTimes(1);
+  });
+});