@mondaydotcomorg/z2h-cli 0.27.1 → 0.28.0

package/dist/backend/__tests__/ast.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ast.test.d.ts.map

package/dist/backend/__tests__/ast.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.test.d.ts","sourceRoot":"","sources":["../../../src/backend/__tests__/ast.test.ts"],"names":[],"mappings":""}

package/dist/backend/__tests__/parse.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=parse.test.d.ts.map

package/dist/backend/__tests__/parse.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.test.d.ts","sourceRoot":"","sources":["../../../src/backend/__tests__/parse.test.ts"],"names":[],"mappings":""}

package/dist/backend/__tests__/validate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validate.test.d.ts.map

package/dist/backend/__tests__/validate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.test.d.ts","sourceRoot":"","sources":["../../../src/backend/__tests__/validate.test.ts"],"names":[],"mappings":""}

package/dist/backend/ast.d.ts

@@ -0,0 +1,41 @@
+import type { AnyNode, Expression, Node, Pattern, Program, VariableDeclaration } from 'acorn';
+/** 1-based line a node starts on; requires the program to be parsed with `locations: true`. */
+export declare const lineOf: (node: Node) => number | undefined;
+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>;
+}
+/** Every identifier a binding pattern introduces (`{ a, b: [c] } = …` → a, c). */
+export declare const patternNames: (pattern: Pattern) => string[];
+export declare function collectBindings(program: Program): Bindings;
+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 declare function createPathResolver(bindings: Bindings, contextParam?: string): PathResolver;
+/** Every `ctx.api.v1.<domain>` the program touches (known or not), through `paths`. */
+export declare function collectApiDomains(program: Program, paths: PathResolver): Set<string>;
+//# sourceMappingURL=ast.d.ts.map

package/dist/backend/ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/backend/ast.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAG9F,+FAA+F;AAC/F,eAAO,MAAM,MAAM,GAAI,MAAM,IAAI,KAAG,MAAM,GAAG,SAAiC,CAAC;AAI/E,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;IACpC;;;;OAIG;IACH,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,6DAA6D;IAC7D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;IACzC,uFAAuF;IACvF,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AA8CD,kFAAkF;AAClF,eAAO,MAAM,YAAY,GAAI,SAAS,OAAO,KAAG,MAAM,EAAmD,CAAC;AAE1G,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CA4C1D;AA2BD,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,CA6B1F;AAED,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,GAAG,GAAG,CAAC,MAAM,CAAC,CAWpF"}

package/dist/backend/ast.js

@@ -0,0 +1,152 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const acornWalk = require('acorn-walk');
+
+/** 1-based line a node starts on; requires the program to be parsed with `locations: true`. */
+const lineOf = (node) => node.loc?.start.line;
+/**
+ * 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, path) {
+    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, computed) {
+    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). */
+const patternNames = (pattern) => patternBindings(pattern, []).map(b => b.name);
+function collectBindings(program) {
+    const declarations = new Map();
+    const unpinnable = new Set();
+    const markUnpinnable = (pattern) => patternNames(pattern).forEach(n => unpinnable.add(n));
+    acornWalk.full(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 };
+}
+/** `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) {
+    if (node.type === 'ChainExpression') {
+        return memberChain(node.expression);
+    }
+    const parts = [];
+    let cur = 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;
+}
+function createPathResolver(bindings, contextParam) {
+    function resolveChain(node, resolving) {
+        const chain = memberChain(node);
+        if (!chain) {
+            return undefined;
+        }
+        return [resolveRoot(chain.root, resolving), ...chain.parts].join('.');
+    }
+    function resolveRoot(name, resolving) {
+        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`. */
+function collectApiDomains(program, paths) {
+    const apiDomains = new Set();
+    acornWalk.simple(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;
+}
+
+exports.collectApiDomains = collectApiDomains;
+exports.collectBindings = collectBindings;
+exports.createPathResolver = createPathResolver;
+exports.lineOf = lineOf;
+exports.patternNames = patternNames;

package/dist/backend/detect-integrations.d.ts

@@ -1,11 +1,15 @@
+import { type DeclaredIntegration } from '@mondaydotcomorg/z2h-shared-utils';
 /**
- * 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 declare function detectIntegrationsFromHandlers(handlers: Record<string, string>): string[];
+export declare function detectIntegrations(apiDomains: Iterable<string>): DeclaredIntegration[];
 //# sourceMappingURL=detect-integrations.d.ts.map

package/dist/backend/detect-integrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect-integrations.d.ts","sourceRoot":"","sources":["../../src/backend/detect-integrations.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAUzF"}
+{"version":3,"file":"detect-integrations.d.ts","sourceRoot":"","sources":["../../src/backend/detect-integrations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAKpG;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,mBAAmB,EAAE,CAEtF"}

package/dist/backend/detect-integrations.js

@@ -1,26 +1,23 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-const constants = require('../constants.js');
+const z2hSharedUtils = require('@mondaydotcomorg/z2h-shared-utils');
 
+const declared = new Set(z2hSharedUtils.DECLARED_INTEGRATIONS);
+const isDeclaredIntegration = (domain) => 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.
  */
-function detectIntegrationsFromHandlers(handlers) {
-    const found = new Set();
-    for (const source of Object.values(handlers)) {
-        for (const name of constants.DECLARED_INTEGRATIONS) {
-            if (new RegExp(`\\bctx\\.api\\.v1\\.${name}\\b`).test(source)) {
-                found.add(name);
-            }
-        }
-    }
-    return [...found].sort();
+function detectIntegrations(apiDomains) {
+    return [...new Set(apiDomains)].filter(isDeclaredIntegration).sort();
 }
 
-exports.detectIntegrationsFromHandlers = detectIntegrationsFromHandlers;
+exports.detectIntegrations = detectIntegrations;

package/dist/backend/handler-declaration.d.ts

@@ -0,0 +1,17 @@
+import type { Expression, FunctionDeclaration, ModuleDeclaration, Statement } from 'acorn';
+export type HandlerDeclaration = {
+    kind: 'function';
+    params: FunctionDeclaration['params'];
+} | {
+    kind: 'variable';
+    init: Expression | null | undefined;
+};
+/** The top-level declaration that binds `handler`, if any. */
+export declare function findHandlerDeclaration(body: readonly (Statement | ModuleDeclaration)[]): HandlerDeclaration | undefined;
+/** `export function handler`, `export const handler`, `export { handler }`, `export default handler`. */
+export declare function exportsHandler(node: Statement | ModuleDeclaration): boolean;
+/** First positional parameter of `handler`, when it's a plain identifier (`ctx`, `context`, …). */
+export declare function handlerContextParamName(declaration: HandlerDeclaration): string | undefined;
+/** Values that can never be a function, so `const handler = <this>` is caught at build time. */
+export declare const NEVER_A_FUNCTION: ReadonlySet<string>;
+//# sourceMappingURL=handler-declaration.d.ts.map

package/dist/backend/handler-declaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-declaration.d.ts","sourceRoot":"","sources":["../../src/backend/handler-declaration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,UAAU,EACV,mBAAmB,EAEnB,iBAAiB,EAEjB,SAAS,EACV,MAAM,OAAO,CAAC;AAMf,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,CAAC;AAE9D,8DAA8D;AAC9D,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,SAAS,CAAC,SAAS,GAAG,iBAAiB,CAAC,EAAE,GAC/C,kBAAkB,GAAG,SAAS,CAahC;AAED,yGAAyG;AACzG,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,iBAAiB,GAAG,OAAO,CAe3E;AAsCD,mGAAmG;AACnG,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,kBAAkB,GAAG,MAAM,GAAG,SAAS,CAG3F;AAED,gGAAgG;AAChG,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAK/C,CAAC"}

package/dist/backend/handler-declaration.js

@@ -0,0 +1,83 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+/** True for the `handler` identifier specifically — used everywhere a node might name the binding. */
+const isHandlerIdentifier = (candidate) => candidate?.type === 'Identifier' && candidate.name === 'handler';
+/** The top-level declaration that binds `handler`, if any. */
+function findHandlerDeclaration(body) {
+    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`. */
+function exportsHandler(node) {
+    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) {
+    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) {
+    let first = 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`, …). */
+function handlerContextParamName(declaration) {
+    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. */
+const NEVER_A_FUNCTION = new Set([
+    'Literal',
+    'ObjectExpression',
+    'ArrayExpression',
+    'TemplateLiteral',
+]);
+
+exports.NEVER_A_FUNCTION = NEVER_A_FUNCTION;
+exports.exportsHandler = exportsHandler;
+exports.findHandlerDeclaration = findHandlerDeclaration;
+exports.handlerContextParamName = handlerContextParamName;

package/dist/backend/handlers.d.ts

@@ -1,6 +1,8 @@
 export interface ReadHandlersResult {
     /** handler name (filename without .js) → JS source */
     handlers: Record<string, string>;
+    /** Every `ctx.api.v1.<domain>` any handler touches, sorted and unique. */
+    apiDomains: string[];
 }
 /**
  * Reads every `backend/handlers/*.js` file inside `consumerDir` and returns a

package/dist/backend/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/backend/handlers.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AA4BD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAuCnF"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/backend/handlers.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,0EAA0E;IAC1E,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2BnF"}

package/dist/backend/handlers.js

@@ -3,35 +3,13 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const path = require('node:path');
 const promises = require('node:fs/promises');
 const fs = require('fs-extra');
+const backend_validate = require('./validate.js');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
 const path__default = /*#__PURE__*/_interopDefault(path);
 
 const HANDLERS_DIR = path__default.default.join('backend', 'handlers');
-/**
- * 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) {
-    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) {
-    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) {
-    return /^\s*import\b/m.test(source) || /\brequire\s*\(/.test(source);
-}
 /**
  * Reads every `backend/handlers/*.js` file inside `consumerDir` and returns a
  * map from handler name (filename without `.js`) to source. No compilation —
@@ -40,7 +18,7 @@ function hasImports(source) {
 async function readHandlers(consumerDir) {
     const handlersDir = path__default.default.join(consumerDir, HANDLERS_DIR);
     if (!(await fs.pathExists(handlersDir))) {
-        return { handlers: {} };
+        return { handlers: {}, apiDomains: [] };
     }
     const entries = await promises.readdir(handlersDir);
     const tsFiles = entries.filter(f => f.endsWith('.ts'));
@@ -49,25 +27,18 @@ async function readHandlers(consumerDir) {
     }
     const jsFiles = entries.filter(f => f.endsWith('.js'));
     if (jsFiles.length === 0) {
-        return { handlers: {} };
+        return { handlers: {}, apiDomains: [] };
     }
     const handlers = {};
+    const apiDomains = new Set();
     for (const file of jsFiles) {
         const handlerName = path__default.default.parse(file).name;
         const source = await promises.readFile(path__default.default.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 = backend_validate.validateHandlerSource(file, source);
+        validation.apiDomains.forEach(d => apiDomains.add(d));
         handlers[handlerName] = source;
     }
-    return { handlers };
+    return { handlers, apiDomains: [...apiDomains].sort() };
 }
 
 exports.readHandlers = readHandlers;

package/dist/backend/messages.d.ts

@@ -0,0 +1,10 @@
+export declare const messages: {
+    mustDefine: (file: string) => string;
+    notAFunction: (file: string) => string;
+    mustNotImport: (file: string) => string;
+    mustNotExportHandler: (file: string) => string;
+    mustNotExport: (file: string) => string;
+    moduleOnlySyntax: (file: string, detail: string) => string;
+    syntaxError: (file: string, line: number, column: number, detail: string) => string;
+};
+//# sourceMappingURL=messages.d.ts.map

package/dist/backend/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/backend/messages.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,QAAQ;uBACA,MAAM;yBACJ,MAAM;0BACL,MAAM;iCAEC,MAAM;0BAEb,MAAM;6BAEH,MAAM,UAAU,MAAM;wBAE3B,MAAM,QAAQ,MAAM,UAAU,MAAM,UAAU,MAAM;CAEzE,CAAC"}

package/dist/backend/messages.js

@@ -0,0 +1,14 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const EXAMPLE = 'async function handler(ctx) { ... }';
+const messages = {
+    mustDefine: (file) => `${file} must define a handler — e.g. ${EXAMPLE}`,
+    notAFunction: (file) => `${file} declares handler but it is not a function — e.g. ${EXAMPLE}`,
+    mustNotImport: (file) => `${file} must not import other files or packages — handlers are self-contained; reach the outside world through ctx capabilities`,
+    mustNotExportHandler: (file) => `${file} must not export handler — the isolate has no module system; declare it as a plain global, e.g. ${EXAMPLE}`,
+    mustNotExport: (file) => `${file} must not use export — the isolate has no module system; declare handler as a plain global, e.g. ${EXAMPLE}`,
+    moduleOnlySyntax: (file, detail) => `${file} uses module-only syntax (${detail}) — handlers run as plain scripts, so top-level await and import.meta are not available`,
+    syntaxError: (file, line, column, detail) => `${file}:${line}:${column}: not valid JavaScript — ${detail}`,
+};
+
+exports.messages = messages;

package/dist/backend/parse.d.ts

@@ -0,0 +1,11 @@
+import { type Program } from 'acorn';
+/**
+ * The runner compiles handlers with `isolate.compileScript`, i.e. the classic
+ * *script* grammar — so that is the grammar we validate against. `import`/`export`
+ * declarations and top-level `await`/`import.meta` are only legal under the
+ * *module* grammar, so a handler using any of them fails the script parse; we
+ * re-parse it as a module purely to name which of those four things it was,
+ * instead of surfacing V8's bare "Unexpected token 'export'".
+ */
+export declare function parseOrThrow(file: string, code: string): Program;
+//# sourceMappingURL=parse.d.ts.map

package/dist/backend/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/backend/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8D,KAAK,OAAO,EAAkB,MAAM,OAAO,CAAC;AAkDjH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAuBhE"}

package/dist/backend/parse.js

@@ -0,0 +1,66 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const acorn = require('acorn');
+const zod = require('zod');
+const util_tracker = require('../util/tracker.js');
+const backend_handlerDeclaration = require('./handler-declaration.js');
+const backend_messages = require('./messages.js');
+
+const acornLocSchema = zod.z.object({ line: zod.z.number(), column: zod.z.number() });
+function isAcornSyntaxError(err) {
+    return err instanceof SyntaxError && acornLocSchema.safeParse(err.loc).success;
+}
+function tryParse(code, sourceType) {
+    try {
+        return { ok: true, program: acorn.parse(code, { ecmaVersion: 'latest', sourceType, locations: true }) };
+    }
+    catch (err) {
+        if (isAcornSyntaxError(err)) {
+            return { ok: false, error: err };
+        }
+        throw err;
+    }
+}
+/** Acorn appends ` (line:col)` to its messages; we report the position ourselves. */
+const stripPosition = (message) => message.replace(/ \(\d+:\d+\)$/, '');
+const isImportLike = (node) => node.type === 'ImportDeclaration' ||
+    node.type === 'ExportAllDeclaration' ||
+    (node.type === 'ExportNamedDeclaration' && node.source != null);
+const isExport = (node) => node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration';
+/** Reports the failure, then returns the error for the caller to throw. */
+function parseError(message) {
+    void util_tracker.trackEvent('z2h_cli_handler_parse_error', { error: message });
+    return new Error(message);
+}
+/**
+ * The runner compiles handlers with `isolate.compileScript`, i.e. the classic
+ * *script* grammar — so that is the grammar we validate against. `import`/`export`
+ * declarations and top-level `await`/`import.meta` are only legal under the
+ * *module* grammar, so a handler using any of them fails the script parse; we
+ * re-parse it as a module purely to name which of those four things it was,
+ * instead of surfacing V8's bare "Unexpected token 'export'".
+ */
+function parseOrThrow(file, code) {
+    const asScript = tryParse(code, 'script');
+    if (asScript.ok) {
+        return asScript.program;
+    }
+    const asModule = tryParse(code, 'module');
+    if (asModule.ok) {
+        const { body } = asModule.program;
+        if (body.some(backend_handlerDeclaration.exportsHandler)) {
+            throw parseError(backend_messages.messages.mustNotExportHandler(file));
+        }
+        if (body.some(isImportLike)) {
+            throw parseError(backend_messages.messages.mustNotImport(file));
+        }
+        if (body.some(isExport)) {
+            throw parseError(backend_messages.messages.mustNotExport(file));
+        }
+        throw parseError(backend_messages.messages.moduleOnlySyntax(file, stripPosition(asScript.error.message)));
+    }
+    const { line, column } = asScript.error.loc;
+    throw parseError(backend_messages.messages.syntaxError(file, line, column, stripPosition(asScript.error.message)));
+}
+
+exports.parseOrThrow = parseOrThrow;

package/dist/backend/rules/__tests__/snowflake-static-sql.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=snowflake-static-sql.test.d.ts.map

package/dist/backend/rules/__tests__/snowflake-static-sql.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snowflake-static-sql.test.d.ts","sourceRoot":"","sources":["../../../../src/backend/rules/__tests__/snowflake-static-sql.test.ts"],"names":[],"mappings":""}

package/dist/backend/rules/index.d.ts

@@ -0,0 +1,5 @@
+import type { HandlerRule } from './types';
+export type { HandlerRule, RuleContext } from './types';
+/** Every rule the validator runs, in order. Add new capability rules here. */
+export declare const HANDLER_RULES: readonly HandlerRule[];
+//# sourceMappingURL=index.d.ts.map

package/dist/backend/rules/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/backend/rules/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAExD,8EAA8E;AAC9E,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAAmC,CAAC"}

package/dist/backend/rules/index.js

@@ -0,0 +1,8 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const backend_rules_snowflakeStaticSql = require('./snowflake-static-sql.js');
+
+/** Every rule the validator runs, in order. Add new capability rules here. */
+const HANDLER_RULES = [new backend_rules_snowflakeStaticSql.SnowflakeStaticSqlRule()];
+
+exports.HANDLER_RULES = HANDLER_RULES;

package/dist/backend/rules/snowflake-static-sql.d.ts

@@ -0,0 +1,15 @@
+import type { HandlerRule, RuleContext } from './types';
+/**
+ * `ctx.api.v1.snowflake.query(sql, params?, options?)` — the SQL text must live
+ * in the handler. The frontend chooses *which* handler to call and supplies
+ * `params` / `options`; it never ships SQL. Binding placeholders (`:name`) are
+ * how client values reach the query.
+ *
+ * The call is matched through `const` aliases of the channel
+ * (`const sf = ctx.api.v1.snowflake; sf.query(…)`), see `PathResolver`.
+ */
+export declare class SnowflakeStaticSqlRule implements HandlerRule {
+    readonly name = "snowflake/static-sql";
+    check({ file, program, bindings, paths }: RuleContext): string[];
+}
+//# sourceMappingURL=snowflake-static-sql.d.ts.map