@mondaydotcomorg/z2h-cli 0.27.1 → 0.29.0

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);
+  });
+});

package/src/backend/ast.ts

@@ -0,0 +1,204 @@
+import type { AnyNode, Expression, Node, Pattern, Program, VariableDeclaration } from 'acorn';
+import { full as walkFull, simple as walkSimple } from 'acorn-walk';
+
+/** 1-based line a node starts on; requires the program to be parsed with `locations: true`. */
+export const lineOf = (node: Node): number | undefined => node.loc?.start.line;
+
+// ─────────── Bindings ───────────
+
+export interface Declaration {
+  kind: VariableDeclaration['kind'];
+  init: Expression | null | undefined;
+  /**
+   * Property path from `init` to this binding: `[]` for `const x = init`,
+   * `['a', 'b']` for `const { a: { b: x } } = init`, `undefined` when the value
+   * is not a plain property read (array/rest/default patterns).
+   */
+  path: string[] | undefined;
+}
+
+export interface Bindings {
+  /** Every `var|let|const <name> = …` in the file, by name. */
+  declarations: Map<string, Declaration[]>;
+  /** Names whose value cannot be pinned: reassigned, updated, or bound as parameters. */
+  unpinnable: Set<string>;
+}
+
+interface PatternBinding {
+  name: string;
+  path: string[] | undefined;
+}
+
+/**
+ * Every identifier a binding pattern introduces, with its property path from the
+ * pattern's value. `path` is deliberately not defaulted: callers pass `[]` for
+ * the root and `undefined` once the pattern stops being a plain property read.
+ */
+function patternBindings(pattern: Pattern, path: string[] | undefined): PatternBinding[] {
+  switch (pattern.type) {
+    case 'Identifier':
+      return [{ name: pattern.name, path }];
+    case 'ObjectPattern':
+      return pattern.properties.flatMap(p => {
+        if (p.type === 'RestElement') {
+          return patternBindings(p.argument, undefined);
+        }
+        const key = propertyKey(p.key, p.computed);
+        return patternBindings(p.value, path && key !== undefined ? [...path, key] : undefined);
+      });
+    case 'ArrayPattern':
+      return pattern.elements.flatMap(e => (e ? patternBindings(e, undefined) : []));
+    case 'AssignmentPattern':
+      return patternBindings(pattern.left, undefined);
+    case 'RestElement':
+      return patternBindings(pattern.argument, undefined);
+    default:
+      // MemberExpression targets (`obj.x = …`) bind no names.
+      return [];
+  }
+}
+
+function propertyKey(key: AnyNode, computed: boolean): string | undefined {
+  if (key.type === 'Literal' && typeof key.value === 'string') {
+    return key.value;
+  }
+  if (!computed && key.type === 'Identifier') {
+    return key.name;
+  }
+  return undefined;
+}
+
+/** Every identifier a binding pattern introduces (`{ a, b: [c] } = …` → a, c). */
+export const patternNames = (pattern: Pattern): string[] => patternBindings(pattern, []).map(b => b.name);
+
+export function collectBindings(program: Program): Bindings {
+  const declarations = new Map<string, Declaration[]>();
+  const unpinnable = new Set<string>();
+  const markUnpinnable = (pattern: Pattern) => patternNames(pattern).forEach(n => unpinnable.add(n));
+
+  walkFull(program, node => {
+    switch (node.type) {
+      case 'VariableDeclaration':
+        for (const declarator of node.declarations) {
+          for (const { name, path } of patternBindings(declarator.id, [])) {
+            const list = declarations.get(name) ?? [];
+            list.push({ kind: node.kind, init: declarator.init, path });
+            declarations.set(name, list);
+          }
+        }
+        break;
+      case 'AssignmentExpression':
+        markUnpinnable(node.left);
+        break;
+      case 'UpdateExpression':
+        if (node.argument.type === 'Identifier') {
+          unpinnable.add(node.argument.name);
+        }
+        break;
+      case 'ForInStatement':
+      case 'ForOfStatement':
+        if (node.left.type !== 'VariableDeclaration') {
+          markUnpinnable(node.left);
+        }
+        break;
+      case 'FunctionDeclaration':
+      case 'FunctionExpression':
+      case 'ArrowFunctionExpression':
+        node.params.forEach(markUnpinnable);
+        break;
+      case 'CatchClause':
+        if (node.param) {
+          markUnpinnable(node.param);
+        }
+        break;
+    }
+  });
+
+  return { declarations, unpinnable };
+}
+
+// ─────────── Member paths ───────────
+
+interface MemberChain {
+  root: string;
+  parts: string[];
+}
+
+/** `a.b.c` / `a['b'].c` → root `a`, parts `[b, c]`; `undefined` if any link is dynamic or the root is not an identifier. */
+function memberChain(node: AnyNode): MemberChain | undefined {
+  if (node.type === 'ChainExpression') {
+    return memberChain(node.expression);
+  }
+  const parts: string[] = [];
+  let cur: AnyNode = node;
+  while (cur.type === 'MemberExpression') {
+    const key = propertyKey(cur.property, cur.computed);
+    if (key === undefined) {
+      return undefined;
+    }
+    parts.unshift(key);
+    cur = cur.object;
+  }
+  return cur.type === 'Identifier' ? { root: cur.name, parts } : undefined;
+}
+
+export interface PathResolver {
+  /**
+   * Dotted path of a member chain, following `const` aliases back to their
+   * source: with `const sf = ctx.api.v1.snowflake`, `sf.query` resolves to
+   * `ctx.api.v1.snowflake.query`. Destructuring counts too
+   * (`const { snowflake: sf } = ctx.api.v1`). `undefined` if any link is dynamic.
+   *
+   * Only single, never-reassigned, never-shadowed `const` bindings are followed —
+   * anything else is left as written, so a `let` alias or a parameter of the same
+   * name is never mistaken for the channel. The handler's first parameter is
+   * treated as `ctx` even when renamed (`handler(context)` → `context.api.v1.db`
+   * resolves as `ctx.api.v1.db`).
+   */
+  pathOf(node: AnyNode): string | undefined;
+}
+
+export function createPathResolver(bindings: Bindings, contextParam?: string): PathResolver {
+  function resolveChain(node: AnyNode, resolving: ReadonlySet<string>): string | undefined {
+    const chain = memberChain(node);
+    if (!chain) {
+      return undefined;
+    }
+    return [resolveRoot(chain.root, resolving), ...chain.parts].join('.');
+  }
+
+  function resolveRoot(name: string, resolving: ReadonlySet<string>): string {
+    if (contextParam !== undefined && name === contextParam) {
+      return 'ctx';
+    }
+    if (bindings.unpinnable.has(name) || resolving.has(name)) {
+      return name;
+    }
+    const decls = bindings.declarations.get(name);
+    if (!decls || decls.length !== 1) {
+      return name;
+    }
+    const [{ kind, init, path }] = decls;
+    if (kind !== 'const' || !init || !path) {
+      return name;
+    }
+    const base = resolveChain(init, new Set(resolving).add(name));
+    return base ? [base, ...path].join('.') : name;
+  }
+
+  return { pathOf: node => resolveChain(node, new Set()) };
+}
+
+/** Every `ctx.api.v1.<domain>` the program touches (known or not), through `paths`. */
+export function collectApiDomains(program: Program, paths: PathResolver): Set<string> {
+  const apiDomains = new Set<string>();
+  walkSimple(program, {
+    MemberExpression(node) {
+      const [obj, api, version, domain] = paths.pathOf(node)?.split('.') ?? [];
+      if (obj === 'ctx' && api === 'api' && version === 'v1' && domain) {
+        apiDomains.add(domain);
+      }
+    },
+  });
+  return apiDomains;
+}

package/src/backend/detect-integrations.ts

@@ -1,22 +1,20 @@
-import { DECLARED_INTEGRATIONS } from '../constants';
+import { DECLARED_INTEGRATIONS, type DeclaredIntegration } from '@mondaydotcomorg/z2h-shared-utils';
+
+const declared: ReadonlySet<string> = new Set(DECLARED_INTEGRATIONS);
+const isDeclaredIntegration = (domain: string): domain is DeclaredIntegration => declared.has(domain);
 
 /**
- * Integrations inferred from handler source at deploy time — whatever
+ * Integrations inferred from handler sources at deploy time — whatever
  * `ctx.api.v1.<name>` the handlers touch (from `DECLARED_INTEGRATIONS`) is
  * registered with the platform. There is no `integrations.json` and no declare
  * CLI step.
  *
- * Only OAuth-gated integrations belong in that set. `db`, `llm`, and `snowflake`
- * are always-on channels and are never declared.
+ * `apiDomains` comes from the handler parse in `validateHandlerSource`, so a
+ * domain mentioned only in a comment or string does not count as usage.
+ *
+ * Only OAuth-gated integrations belong in the result. `db`, `llm`, and
+ * `snowflake` are always-on channels and are never declared.
  */
-export function detectIntegrationsFromHandlers(handlers: Record<string, string>): string[] {
-  const found = new Set<string>();
-  for (const source of Object.values(handlers)) {
-    for (const name of DECLARED_INTEGRATIONS) {
-      if (new RegExp(`\\bctx\\.api\\.v1\\.${name}\\b`).test(source)) {
-        found.add(name);
-      }
-    }
-  }
-  return [...found].sort();
+export function detectIntegrations(apiDomains: Iterable<string>): DeclaredIntegration[] {
+  return [...new Set(apiDomains)].filter(isDeclaredIntegration).sort();
 }

package/src/backend/handler-declaration.ts

@@ -0,0 +1,104 @@
+import type {
+  AnyNode,
+  ArrowFunctionExpression,
+  Expression,
+  FunctionDeclaration,
+  FunctionExpression,
+  ModuleDeclaration,
+  Pattern,
+  Statement,
+} from 'acorn';
+
+/** True for the `handler` identifier specifically — used everywhere a node might name the binding. */
+const isHandlerIdentifier = (candidate: AnyNode | null | undefined): boolean =>
+  candidate?.type === 'Identifier' && candidate.name === 'handler';
+
+export type HandlerDeclaration =
+  | { kind: 'function'; params: FunctionDeclaration['params'] }
+  | { kind: 'variable'; init: Expression | null | undefined };
+
+/** The top-level declaration that binds `handler`, if any. */
+export function findHandlerDeclaration(
+  body: readonly (Statement | ModuleDeclaration)[]
+): HandlerDeclaration | undefined {
+  for (const node of body) {
+    if (node.type === 'FunctionDeclaration' && isHandlerIdentifier(node.id)) {
+      return { kind: 'function', params: node.params };
+    }
+    if (node.type === 'VariableDeclaration') {
+      const declarator = node.declarations.find(d => isHandlerIdentifier(d.id));
+      if (declarator) {
+        return { kind: 'variable', init: declarator.init };
+      }
+    }
+  }
+  return undefined;
+}
+
+/** `export function handler`, `export const handler`, `export { handler }`, `export default handler`. */
+export function exportsHandler(node: Statement | ModuleDeclaration): boolean {
+  if (node.type === 'ExportNamedDeclaration') {
+    return (
+      (node.declaration != null && findHandlerDeclaration([node.declaration]) !== undefined) ||
+      node.specifiers.some(s => isHandlerIdentifier(s.local) || isHandlerIdentifier(s.exported))
+    );
+  }
+  if (node.type === 'ExportDefaultDeclaration') {
+    const { declaration } = node;
+    return (
+      (declaration.type === 'FunctionDeclaration' && isHandlerIdentifier(declaration.id)) ||
+      isHandlerIdentifier(declaration)
+    );
+  }
+  return false;
+}
+
+/** Peel `wrap(fn)`, `(0, fn)`, and the like until a function expression remains. */
+function asFunction(expr: Expression | null | undefined): FunctionExpression | ArrowFunctionExpression | undefined {
+  if (!expr) {
+    return undefined;
+  }
+  switch (expr.type) {
+    case 'FunctionExpression':
+    case 'ArrowFunctionExpression':
+      return expr;
+    case 'SequenceExpression':
+      return asFunction(expr.expressions.at(-1));
+    case 'CallExpression': {
+      for (const arg of expr.arguments) {
+        if (arg.type === 'SpreadElement') {
+          continue;
+        }
+        const fn = asFunction(arg);
+        if (fn) {
+          return fn;
+        }
+      }
+      return undefined;
+    }
+    default:
+      return undefined;
+  }
+}
+
+function firstParamName(params: readonly Pattern[]): string | undefined {
+  let first: Pattern | undefined = params[0];
+  if (first?.type === 'AssignmentPattern') {
+    first = first.left;
+  }
+  return first?.type === 'Identifier' ? first.name : undefined;
+}
+
+/** First positional parameter of `handler`, when it's a plain identifier (`ctx`, `context`, …). */
+export function handlerContextParamName(declaration: HandlerDeclaration): string | undefined {
+  const params = declaration.kind === 'function' ? declaration.params : asFunction(declaration.init)?.params;
+  return params ? firstParamName(params) : undefined;
+}
+
+/** Values that can never be a function, so `const handler = <this>` is caught at build time. */
+export const NEVER_A_FUNCTION: ReadonlySet<string> = new Set([
+  'Literal',
+  'ObjectExpression',
+  'ArrayExpression',
+  'TemplateLiteral',
+]);

package/src/backend/handlers.ts

@@ -1,38 +1,15 @@
 import path from 'node:path';
 import { readdir, readFile } from 'node:fs/promises';
 import { pathExists } from 'fs-extra';
+import { validateHandlerSource } from './validate';
 
 const HANDLERS_DIR = path.join('backend', 'handlers');
 
 export interface ReadHandlersResult {
   /** handler name (filename without .js) → JS source */
   handlers: Record<string, string>;
-}
-
-/**
- * True if the source defines a `handler` function or variable at the top level.
- * Handlers run in a V8 isolate with no module system — `handler` must be a plain
- * global, not an export.
- */
-function definesHandler(source: string): boolean {
-  return /\bfunction\s+handler\b/.test(source) || /\b(const|let|var)\s+handler\b/.test(source);
-}
-
-/**
- * True if `handler` is declared with an `export` prefix. It reads as valid source but
- * the isolate has no module system, so an exported handler is simply invisible to the
- * runner — caught here rather than failing opaquely at invoke time.
- */
-function exportsHandler(source: string): boolean {
-  return /\bexport\s+(default\s+)?(async\s+)?(function\s+handler\b|(?:const|let|var)\s+handler\b)/.test(source);
-}
-
-/**
- * True if the source contains any `import` or `require` call. Neither works in
- * the V8 isolate — reach the outside world through `ctx` capabilities instead.
- */
-function hasImports(source: string): boolean {
-  return /^\s*import\b/m.test(source) || /\brequire\s*\(/.test(source);
+  /** Every `ctx.api.v1.<domain>` any handler touches, sorted and unique. */
+  apiDomains: string[];
 }
 
 /**
@@ -43,7 +20,7 @@ function hasImports(source: string): boolean {
 export async function readHandlers(consumerDir: string): Promise<ReadHandlersResult> {
   const handlersDir = path.join(consumerDir, HANDLERS_DIR);
   if (!(await pathExists(handlersDir))) {
-    return { handlers: {} };
+    return { handlers: {}, apiDomains: [] };
   }
 
   const entries = await readdir(handlersDir);
@@ -53,30 +30,18 @@ export async function readHandlers(consumerDir: string): Promise<ReadHandlersRes
   }
   const jsFiles = entries.filter(f => f.endsWith('.js'));
   if (jsFiles.length === 0) {
-    return { handlers: {} };
+    return { handlers: {}, apiDomains: [] };
   }
 
   const handlers: Record<string, string> = {};
+  const apiDomains = new Set<string>();
   for (const file of jsFiles) {
     const handlerName = path.parse(file).name;
     const source = await readFile(path.join(handlersDir, file), 'utf8');
 
-    // Before the definesHandler check: `export const handler` satisfies that one too.
-    if (exportsHandler(source)) {
-      throw new Error(
-        `${file} must not export handler — the isolate has no module system; declare it as a plain global, e.g. async function handler(ctx) { ... }`
-      );
-    }
-    if (!definesHandler(source)) {
-      throw new Error(`${file} must define a handler — e.g. async function handler(ctx) { ... }`);
-    }
-    if (hasImports(source)) {
-      throw new Error(
-        `${file} must not import other files or packages — handlers are self-contained; reach the outside world through ctx capabilities`
-      );
-    }
-
+    const validation = validateHandlerSource(file, source);
+    validation.apiDomains.forEach(d => apiDomains.add(d));
     handlers[handlerName] = source;
   }
-  return { handlers };
+  return { handlers, apiDomains: [...apiDomains].sort() };
 }