@mondaydotcomorg/z2h-cli 0.27.1 → 0.28.0

package/dist/esm/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/esm/backend/handler-declaration.mjs

@@ -0,0 +1,78 @@
+/** 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',
+]);
+
+export { NEVER_A_FUNCTION, exportsHandler, findHandlerDeclaration, handlerContextParamName };

package/dist/esm/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/esm/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/esm/backend/handlers.mjs

@@ -1,31 +1,9 @@
 import path from 'node:path';
 import { readdir, readFile } from 'node:fs/promises';
 import { pathExists } from 'fs-extra';
+import { validateHandlerSource } from './validate.mjs';
 
 const HANDLERS_DIR = path.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 —
@@ -34,7 +12,7 @@ function hasImports(source) {
 async function readHandlers(consumerDir) {
     const handlersDir = path.join(consumerDir, HANDLERS_DIR);
     if (!(await pathExists(handlersDir))) {
-        return { handlers: {} };
+        return { handlers: {}, apiDomains: [] };
     }
     const entries = await readdir(handlersDir);
     const tsFiles = entries.filter(f => f.endsWith('.ts'));
@@ -43,25 +21,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.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() };
 }
 
 export { readHandlers };

package/dist/esm/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/esm/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/esm/backend/messages.mjs

@@ -0,0 +1,12 @@
+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}`,
+};
+
+export { messages };

package/dist/esm/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/esm/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/esm/backend/parse.mjs

@@ -0,0 +1,64 @@
+import { parse } from 'acorn';
+import { z } from 'zod';
+import { trackEvent } from '../util/tracker.mjs';
+import { exportsHandler } from './handler-declaration.mjs';
+import { messages } from './messages.mjs';
+
+const acornLocSchema = z.object({ line: z.number(), column: z.number() });
+function isAcornSyntaxError(err) {
+    return err instanceof SyntaxError && acornLocSchema.safeParse(err.loc).success;
+}
+function tryParse(code, sourceType) {
+    try {
+        return { ok: true, program: 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 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(exportsHandler)) {
+            throw parseError(messages.mustNotExportHandler(file));
+        }
+        if (body.some(isImportLike)) {
+            throw parseError(messages.mustNotImport(file));
+        }
+        if (body.some(isExport)) {
+            throw parseError(messages.mustNotExport(file));
+        }
+        throw parseError(messages.moduleOnlySyntax(file, stripPosition(asScript.error.message)));
+    }
+    const { line, column } = asScript.error.loc;
+    throw parseError(messages.syntaxError(file, line, column, stripPosition(asScript.error.message)));
+}
+
+export { parseOrThrow };

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

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

package/dist/esm/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/esm/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/esm/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/esm/backend/rules/index.mjs

@@ -0,0 +1,6 @@
+import { SnowflakeStaticSqlRule } from './snowflake-static-sql.mjs';
+
+/** Every rule the validator runs, in order. Add new capability rules here. */
+const HANDLER_RULES = [new SnowflakeStaticSqlRule()];
+
+export { HANDLER_RULES };

package/dist/esm/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

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

@@ -0,0 +1 @@
+{"version":3,"file":"snowflake-static-sql.d.ts","sourceRoot":"","sources":["../../../../src/backend/rules/snowflake-static-sql.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAgDxD;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,YAAW,WAAW;IACxD,QAAQ,CAAC,IAAI,0BAA0B;IAEvC,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,WAAW,GAAG,MAAM,EAAE;CAcjE"}

package/dist/esm/backend/rules/snowflake-static-sql.mjs

@@ -0,0 +1,73 @@
+import { simple } from 'acorn-walk';
+import { lineOf } from '../ast.mjs';
+
+const SNOWFLAKE_QUERY = 'ctx.api.v1.snowflake.query';
+const message = (file, line) => `${file}${line ? `:${line}` : ''}: ${SNOWFLAKE_QUERY} must receive SQL written in the handler — a string literal, ` +
+    `or a variable bound to one. Client-supplied values go through params (\`:name\` bindings) and options, never into the SQL text.`;
+/**
+ * True when every possible value of `node` is text authored in this file:
+ * string literals, templates whose holes are themselves static, `+`
+ * concatenation, either branch of a conditional, and identifiers that resolve
+ * (within the file) to such values. Anything reaching outside the file —
+ * `ctx.input`, calls, member reads, destructuring — is not static.
+ */
+function isStaticSql(node, bindings, resolving) {
+    if (!node) {
+        return false;
+    }
+    const staticChild = (child) => isStaticSql(child, bindings, resolving);
+    switch (node.type) {
+        case 'Literal':
+            return typeof node.value === 'string';
+        case 'TemplateLiteral':
+            return node.expressions.every(staticChild);
+        case 'BinaryExpression':
+            return node.operator === '+' && staticChild(node.left) && staticChild(node.right);
+        case 'ConditionalExpression':
+            return staticChild(node.consequent) && staticChild(node.alternate);
+        case 'LogicalExpression':
+            return staticChild(node.left) && staticChild(node.right);
+        case 'Identifier': {
+            const { name } = node;
+            if (bindings.unpinnable.has(name) || resolving.has(name)) {
+                return false;
+            }
+            const decls = bindings.declarations.get(name);
+            if (!decls || decls.length === 0) {
+                return false;
+            }
+            const next = new Set(resolving).add(name);
+            return decls.every(d => d.path?.length === 0 && isStaticSql(d.init, bindings, next));
+        }
+        default:
+            return false;
+    }
+}
+/**
+ * `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`.
+ */
+class SnowflakeStaticSqlRule {
+    name = 'snowflake/static-sql';
+    check({ file, program, bindings, paths }) {
+        const violations = [];
+        simple(program, {
+            CallExpression(node) {
+                if (paths.pathOf(node.callee) !== SNOWFLAKE_QUERY) {
+                    return;
+                }
+                if (!isStaticSql(node.arguments[0], bindings, new Set())) {
+                    violations.push(message(file, lineOf(node)));
+                }
+            },
+        });
+        return violations;
+    }
+}
+
+export { SnowflakeStaticSqlRule };

package/dist/esm/backend/rules/types.d.ts

@@ -0,0 +1,29 @@
+import type { Program } from 'acorn';
+import type { Bindings, PathResolver } from '../ast';
+export interface RuleContext {
+    /** Handler file name, used to prefix messages. */
+    file: string;
+    /** Parsed with `locations: true`, so rules can point at a line. */
+    program: Program;
+    /** Every variable binding in the file — see `collectBindings`. */
+    bindings: Bindings;
+    /** Resolves member chains through `const` aliases — see `createPathResolver`. */
+    paths: PathResolver;
+}
+/**
+ * A capability-specific check that runs once the handler is structurally valid
+ * (parses as a script, defines `handler`, imports nothing).
+ *
+ * Rules return human-readable violations rather than throwing so the validator
+ * can report every problem in one pass — agent-generated handlers are fixed in
+ * a loop, and one round-trip per violation is slow.
+ *
+ * Implement as a class (see `SnowflakeStaticSqlRule`) and add an instance to
+ * `HANDLER_RULES` in `./index.ts` — keeps every rule the same shape to read.
+ */
+export interface HandlerRule {
+    /** Stable identifier, e.g. `snowflake/static-sql`. */
+    name: string;
+    check(ctx: RuleContext): string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/backend/rules/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/backend/rules/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAErD,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,QAAQ,EAAE,QAAQ,CAAC;IACnB,iFAAiF;IACjF,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,EAAE,CAAC;CACnC"}

package/dist/esm/backend/rules/types.mjs

@@ -0,0 +1 @@
+

package/dist/esm/backend/validate.d.ts

@@ -0,0 +1,23 @@
+export interface HandlerValidation {
+    /** Every `ctx.api.v1.<domain>` the handler touches (known or not), sorted and unique. */
+    apiDomains: string[];
+}
+/**
+ * Validates a handler's source before upload: real parsing (via acorn) catches
+ * syntax errors at build time instead of an opaque failure inside the isolate.
+ * Handlers run with no module system and no bundler — `handler` must be a plain
+ * top-level global, and imports/requires (which would resolve to nothing at
+ * runtime) are rejected.
+ *
+ * Once the handler is structurally sound, capability-specific rules from
+ * `./rules` run and every violation is reported at once.
+ *
+ * Unknown `ctx.api.v1.<domain>` usage is a warning, not a failure: this pass is
+ * build-time DX feedback for agent-generated code, never a security boundary —
+ * the isolate has no ambient capabilities regardless of what a handler contains.
+ *
+ * Returns the `ctx.api.v1.*` domains the handler touches so callers (integration
+ * detection) can reuse the parse instead of re-scanning the source.
+ */
+export declare function validateHandlerSource(file: string, source: string): HandlerValidation;
+//# sourceMappingURL=validate.d.ts.map

package/dist/esm/backend/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/backend/validate.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAuCrF"}

package/dist/esm/backend/validate.mjs

@@ -0,0 +1,62 @@
+import { simple } from 'acorn-walk';
+import { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS } from '@mondaydotcomorg/z2h-shared-utils';
+import { warn } from '../util/logger.mjs';
+import { collectBindings, createPathResolver, collectApiDomains } from './ast.mjs';
+import { findHandlerDeclaration, NEVER_A_FUNCTION, handlerContextParamName } from './handler-declaration.mjs';
+import { messages } from './messages.mjs';
+import { parseOrThrow } from './parse.mjs';
+import { HANDLER_RULES } from './rules/index.mjs';
+
+const KNOWN_API_DOMAINS = [...ALWAYS_ON_CHANNELS, ...DECLARED_INTEGRATIONS];
+/**
+ * Validates a handler's source before upload: real parsing (via acorn) catches
+ * syntax errors at build time instead of an opaque failure inside the isolate.
+ * Handlers run with no module system and no bundler — `handler` must be a plain
+ * top-level global, and imports/requires (which would resolve to nothing at
+ * runtime) are rejected.
+ *
+ * Once the handler is structurally sound, capability-specific rules from
+ * `./rules` run and every violation is reported at once.
+ *
+ * Unknown `ctx.api.v1.<domain>` usage is a warning, not a failure: this pass is
+ * build-time DX feedback for agent-generated code, never a security boundary —
+ * the isolate has no ambient capabilities regardless of what a handler contains.
+ *
+ * Returns the `ctx.api.v1.*` domains the handler touches so callers (integration
+ * detection) can reuse the parse instead of re-scanning the source.
+ */
+function validateHandlerSource(file, source) {
+    const program = parseOrThrow(file, source);
+    const bindings = collectBindings(program);
+    simple(program, {
+        CallExpression(node) {
+            if (node.callee.type === 'Identifier' && node.callee.name === 'require') {
+                throw new Error(messages.mustNotImport(file));
+            }
+        },
+        ImportExpression() {
+            throw new Error(messages.mustNotImport(file));
+        },
+    });
+    const declaration = findHandlerDeclaration(program.body);
+    if (!declaration) {
+        throw new Error(messages.mustDefine(file));
+    }
+    if (declaration.kind === 'variable' && (!declaration.init || NEVER_A_FUNCTION.has(declaration.init.type))) {
+        throw new Error(messages.notAFunction(file));
+    }
+    const paths = createPathResolver(bindings, handlerContextParamName(declaration));
+    const apiDomains = collectApiDomains(program, paths);
+    const violations = HANDLER_RULES.flatMap(rule => rule.check({ file, program, bindings, paths }));
+    if (violations.length > 0) {
+        throw new Error(violations.join('\n'));
+    }
+    for (const domain of apiDomains) {
+        if (!KNOWN_API_DOMAINS.includes(domain)) {
+            warn(`${file}: ctx.api.v1.${domain} is not a known capability (available: ${KNOWN_API_DOMAINS.join(', ')})`);
+        }
+    }
+    return { apiDomains: [...apiDomains].sort() };
+}
+
+export { validateHandlerSource };

package/dist/esm/commands/__tests__/backend-validate.test.d.ts

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

package/dist/esm/commands/__tests__/backend-validate.test.d.ts.map

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

package/dist/esm/commands/backend.d.ts

@@ -28,6 +28,12 @@ export declare function deployBackend(opts: {
     deployedBy: string;
     isPreview: boolean;
 }): Promise<string[]>;
+/**
+ * Run the same handler validation deploy runs (syntax, isolate constraints,
+ * handler rules, integration detection) against the working tree — without
+ * uploading anything. Throws on the first invalid handler.
+ */
+export declare function backendValidateCommand(appDir?: string): Promise<void>;
 export declare function backendInvokeCommand(handlerName: string, opts?: {
     input?: string;
 }): Promise<void>;

package/dist/esm/commands/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/commands/backend.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAmCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASpB;AAED,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5G"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/commands/backend.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAmCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASpB;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAa1F;AAED,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5G"}

package/dist/esm/commands/backend.mjs

@@ -4,7 +4,7 @@ import { PutObjectCommand } from '@aws-sdk/client-s3';
 import { output, info } from '../util/logger.mjs';
 import { getCwdAppName, mfAppName } from '../util/app-name.mjs';
 import { readHandlers } from '../backend/handlers.mjs';
-import { detectIntegrationsFromHandlers } from '../backend/detect-integrations.mjs';
+import { detectIntegrations } from '../backend/detect-integrations.mjs';
 import { getS3Client } from '../util/s3/client.mjs';
 import { BUCKET_WRITE_NAME } from '../constants.mjs';
 import { invokeBackend } from '../backend/client.mjs';
@@ -36,8 +36,8 @@ async function readDetectAndUpload(appDir, prefix, version, deployedBy, logLabel
         return [];
     }
     info(`reading backend handlers ${logLabel}`);
-    const { handlers } = await readHandlers(appDir);
-    const integrations = detectIntegrationsFromHandlers(handlers);
+    const { handlers, apiDomains } = await readHandlers(appDir);
+    const integrations = detectIntegrations(apiDomains);
     if (Object.keys(handlers).length === 0) {
         return integrations;
     }
@@ -77,6 +77,25 @@ async function deployBackend(opts) {
         throw tagDeployError('deploy_backend_error', err);
     }
 }
+/**
+ * Run the same handler validation deploy runs (syntax, isolate constraints,
+ * handler rules, integration detection) against the working tree — without
+ * uploading anything. Throws on the first invalid handler.
+ */
+async function backendValidateCommand(appDir = process.cwd()) {
+    if (!hasHandlers(appDir)) {
+        output('[z2h-cli] no backend/handlers/ directory — nothing to validate', { handlers: [], integrations: [] });
+        return;
+    }
+    const { handlers, apiDomains } = await readHandlers(appDir);
+    const names = Object.keys(handlers).sort();
+    const integrations = detectIntegrations(apiDomains);
+    const list = (xs) => (xs.length ? xs.join(', ') : 'none');
+    output(`[z2h-cli] ${names.length} handler(s) valid: ${list(names)}\n[z2h-cli] integrations: ${list(integrations)}`, {
+        handlers: names,
+        integrations,
+    });
+}
 async function backendInvokeCommand(handlerName, opts = {}) {
     const appName = currentAppName();
     let input = null;
@@ -92,4 +111,4 @@ async function backendInvokeCommand(handlerName, opts = {}) {
     output(`[z2h-cli] result (${Math.round(res.durationMs)}ms):\n${JSON.stringify(res.result, null, 2)}`, res);
 }
 
-export { backendInvokeCommand, deployBackend, hasHandlers };
+export { backendInvokeCommand, backendValidateCommand, deployBackend, hasHandlers };

package/dist/esm/constants.d.ts

@@ -20,8 +20,7 @@ export declare const S3_SKILLS_BUCKET_NAME = "prod-use1-bigbrain-zth-skills";
 export declare const DATAVIZ_SKILLS_PREFIX = "dataviz/";
 export declare const APP_NAME_PATTERN: RegExp;
 export declare const PREVIEW_APP_NAME_PREFIX = "zth-preview-";
-export declare const DECLARED_INTEGRATIONS: readonly ["monday"];
-export type DeclaredIntegration = (typeof DECLARED_INTEGRATIONS)[number];
+export { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS, type DeclaredIntegration } from '@mondaydotcomorg/z2h-shared-utils';
 export declare const DEFAULT_BROKER_BASE_URL = "https://bigbrain-zth.bigbrain.me";
 /**
  * Resolves the broker origin (no trailing slash). Honors

package/dist/esm/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,eAAO,MAAM,eAAe,SAAS,CAAC;AAGtC,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEjD,CAAC;AAKF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAElD,CAAC;AAMF,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAC9B,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAG9B,eAAO,MAAM,iBAAiB,UAAY,CAAC;AAQ3C,eAAO,MAAM,iBAAiB,qCAAqC,CAAC;AACpE,eAAO,MAAM,MAAM,cAAc,CAAC;AAClC,eAAO,MAAM,gBAAgB,wEAA4D,CAAC;AAE1F,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAC7D,eAAO,MAAM,mBAAmB,+CAAgD,CAAC;AAKjF,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAK7C,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,iBAAiB,yDAA2C,CAAC;AAM1E,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AAIrE,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAMhD,eAAO,MAAM,gBAAgB,QAA2B,CAAC;AAEzD,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAMtD,eAAO,MAAM,qBAAqB,qBAAsB,CAAC;AACzD,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAKzE,eAAO,MAAM,uBAAuB,qCAAqC,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAID,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGvD;AAKD,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAG9C,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAGnD,eAAO,MAAM,uBAAuB,gCAAgC,CAAC;AAMrE,eAAO,MAAM,iBAAiB,EAAG,eAAwB,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,eAAO,MAAM,eAAe,SAAS,CAAC;AAGtC,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEjD,CAAC;AAKF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAElD,CAAC;AAMF,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAC9B,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAG9B,eAAO,MAAM,iBAAiB,UAAY,CAAC;AAQ3C,eAAO,MAAM,iBAAiB,qCAAqC,CAAC;AACpE,eAAO,MAAM,MAAM,cAAc,CAAC;AAClC,eAAO,MAAM,gBAAgB,wEAA4D,CAAC;AAE1F,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAC7D,eAAO,MAAM,mBAAmB,+CAAgD,CAAC;AAKjF,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAK7C,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,iBAAiB,yDAA2C,CAAC;AAM1E,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AAIrE,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAMhD,eAAO,MAAM,gBAAgB,QAA2B,CAAC;AAEzD,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAMtD,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAKxH,eAAO,MAAM,uBAAuB,qCAAqC,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAID,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGvD;AAKD,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAG9C,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAGnD,eAAO,MAAM,uBAAuB,gCAAgC,CAAC;AAMrE,eAAO,MAAM,iBAAiB,EAAG,eAAwB,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}