@mondaydotcomorg/z2h-cli 0.34.1 → 0.34.2

package/dist/commands/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAatG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IAIrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAatG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IAIrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3E"}

package/dist/commands/deploy.js

@@ -12,6 +12,7 @@ const util_auth_authStore = require('../util/auth/auth-store.js');
 const util_appName = require('../util/app-name.js');
 const util_git_repo = require('../util/git/repo.js');
 const util_usageJson = require('../util/usage-json.js');
+const util_usageUpload = require('../util/usage-upload.js');
 const util_git_gitEnv = require('../util/git/git-env.js');
 const util_git_remoteOptions = require('../util/git/remote-options.js');
 const util_s3_client = require('../util/s3/client.js');
@@ -89,7 +90,7 @@ async function uploadAndRegister(opts) {
     const { paths, keyPrefix, appName, token, nextVersion, entry, gitRemote, isPreview, description, masterAppName } = opts;
     // Runs before the frontend upload so a `deployBackend` failure can't leave a
     // preview's unversioned `MF` dir overwritten with no rollback.
-    const { integrations, handlerNames, apiUsages } = await commands_backend.deployBackend({
+    const { integrations, handlerNames } = await commands_backend.deployBackend({
         appDir: process.cwd(),
         appName,
         mfKeyPrefix: keyPrefix,
@@ -108,7 +109,6 @@ async function uploadAndRegister(opts) {
             gitRemote,
             integrations,
             handlerNames,
-            apiUsages,
             description,
             masterAppName,
         });
@@ -142,7 +142,7 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
     const url = `${z2hSharedUtils.BUCKET_READ_DNS_URL}/${keyPrefix}`;
     // No catch-all: every stage below tags its own DeployError reason at the throw site,
     // and anything unclassified reports as `unknown` via reasonOf() in runCommand.
-    const nextVersion = (await util_auth_brokerCredentialProvider.fetchDeployVersion(previewAppName)) + 1;
+    const nextVersion = (await util_auth_brokerCredentialProvider.fetchDeployVersion(previewAppName)).version + 1;
     util_logger.info('building');
     const entry = await buildAndStamp({
         paths,
@@ -207,9 +207,10 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
         await util_git_repo.initRepo(process.cwd(), remote);
         gitRemote = remote;
     }
-    const version = await util_auth_brokerCredentialProvider.fetchDeployVersion(appName);
+    const { version, id: appId } = await util_auth_brokerCredentialProvider.fetchDeployVersion(appName);
     const nextVersion = version + 1;
     const gitEnv = await util_git_gitEnv.resolveGitEnv(appName, gitRemote);
+    let usage = {};
     // Sync git first so a divergence (GitConflictError) stops us.
     // The skill commits the working tree (with an LLM-authored message) before
     // invoking deploy, so the tree should be clean here.
@@ -218,7 +219,7 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
             await util_git_repo.guardCleanTree(process.cwd());
             util_logger.info('syncing with git remote');
             await util_git_repo.pullAndResolve(process.cwd(), gitEnv);
-            await util_usageJson.updateOrCreateUsageJson(process.cwd(), appName, util_machineIdentity.whoAmI());
+            usage = await util_usageJson.updateOrCreateUsageJson(process.cwd(), appName, util_machineIdentity.whoAmI());
         }
         catch (err) {
             throw util_errors.tagDeployError('git_error', err);
@@ -275,6 +276,7 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
         util_logger.info('releasing deploy lock');
         await releaseLockBestEffort(appName, token);
     }
+    await util_usageUpload.putAppUsage(appName, appId, usage, nextVersion);
     // Tags are a post-deploy concern: the S3 upload has already succeeded, so a
     // tag failure never fails the deploy (handled inside).
     await handleDeployTags(appName);

package/dist/constants.d.ts

@@ -8,7 +8,7 @@ export declare const SHADOW_DEV_DEPS: Record<string, string>;
 export declare const MIN_PORT = 13000;
 export declare const MAX_PORT = 19999;
 export declare const GITIGNORE_ENTRIES: string[];
-export { ALWAYS_ON_CHANNELS, APP_NAME_PATTERN, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, DATAVIZ_SKILLS_PREFIX, DECLARED_INTEGRATIONS, MANIFEST_KEY, MANIFEST_READ_URL, PREVIEW_APP_NAME_PREFIX, REGION, S3_PREVIEWS_FOLDER, S3_SKILLS_BUCKET_NAME, type DeclaredIntegration, } from '@mondaydotcomorg/z2h-shared-utils';
+export { ALWAYS_ON_CHANNELS, APP_USAGE_BUCKET_NAME, appUsageFolder, APP_NAME_PATTERN, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, DATAVIZ_SKILLS_PREFIX, DECLARED_INTEGRATIONS, MANIFEST_KEY, MANIFEST_READ_URL, PREVIEW_APP_NAME_PREFIX, REGION, S3_PREVIEWS_FOLDER, S3_SKILLS_BUCKET_NAME, 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
@@ -16,6 +16,7 @@ export declare const DEFAULT_BROKER_BASE_URL = "https://bigbrain-zth.bigbrain.me
  * STS credential provider and the npm-broker registry URL.
  */
 export declare function brokerBaseUrl(): string;
+export declare function isProdBroker(): boolean;
 export declare function routingHeaders(): Record<string, string>;
 export declare const NPM_BROKER_PATH = "/z2h-cli/npm";
 export declare const BROKER_NPM_SCOPE = "@mondaydotcomorg";

package/dist/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;AAI3C,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,EACvB,MAAM,EACN,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,mBAAmB,GACzB,MAAM,mCAAmC,CAAC;AAK3C,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;AAI3C,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,EACvB,MAAM,EACN,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,mBAAmB,GACzB,MAAM,mCAAmC,CAAC;AAK3C,eAAO,MAAM,uBAAuB,qCAAqC,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,YAAY,IAAI,OAAO,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"}

package/dist/constants.js

@@ -38,6 +38,9 @@ const DEFAULT_BROKER_BASE_URL = 'https://bigbrain-zth.bigbrain.me';
 function brokerBaseUrl() {
     return process.env.Z2H_BROKER_BASE_URL || DEFAULT_BROKER_BASE_URL;
 }
+function isProdBroker() {
+    return brokerBaseUrl() === DEFAULT_BROKER_BASE_URL;
+}
 // Returns Baggage header for monday-mirror routing when Z2H_ROUTING_KEY is set.
 // No-op in production (returns {}) — only activates when the env var is set.
 function routingHeaders() {
@@ -75,6 +78,10 @@ Object.defineProperty(exports, 'APP_NAME_PATTERN', {
 enumerable: true,
 get: () => z2hSharedUtils.APP_NAME_PATTERN
 });
+Object.defineProperty(exports, 'APP_USAGE_BUCKET_NAME', {
+enumerable: true,
+get: () => z2hSharedUtils.APP_USAGE_BUCKET_NAME
+});
 Object.defineProperty(exports, 'BUCKET_READ_DNS_NAME', {
 enumerable: true,
 get: () => z2hSharedUtils.BUCKET_READ_DNS_NAME
@@ -123,6 +130,10 @@ Object.defineProperty(exports, 'S3_SKILLS_BUCKET_NAME', {
 enumerable: true,
 get: () => z2hSharedUtils.S3_SKILLS_BUCKET_NAME
 });
+Object.defineProperty(exports, 'appUsageFolder', {
+enumerable: true,
+get: () => z2hSharedUtils.appUsageFolder
+});
 exports.BROKER_NPM_SCOPE = BROKER_NPM_SCOPE;
 exports.DEFAULT_BROKER_BASE_URL = DEFAULT_BROKER_BASE_URL;
 exports.GITIGNORE_ENTRIES = GITIGNORE_ENTRIES;
@@ -136,4 +147,5 @@ exports.SHADOW_SCRIPTS = SHADOW_SCRIPTS;
 exports.Z2H_NPM_TOKEN_ENV = Z2H_NPM_TOKEN_ENV;
 exports.brokerBaseUrl = brokerBaseUrl;
 exports.brokerNpmRegistryUrl = brokerNpmRegistryUrl;
+exports.isProdBroker = isProdBroker;
 exports.routingHeaders = routingHeaders;

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

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

package/dist/esm/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/esm/backend/__tests__/parse.test.d.ts

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

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

@@ -0,0 +1,146 @@
+import { full, simple } from '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));
+    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();
+    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;
+}
+
+export { collectApiDomains, collectBindings, createPathResolver, lineOf, patternNames };

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