@mondaydotcomorg/z2h-cli 0.30.0 → 0.32.0

package/dist/backend/parser/utils.js

@@ -0,0 +1,97 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+// ─────────── Source text ───────────
+const sourceTextOf = (node, source) => source.slice(node.start, node.end);
+function displayText(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+function resolveOrSourceText(node, source, resolve, fallbackText = n => sourceTextOf(n, source)) {
+    const resolved = resolve(node);
+    return resolved !== undefined ? resolved.value : fallbackText(node);
+}
+// ─────────── Keys and member chains ───────────
+/** Static property key of `obj.key` / `obj['key']` / `{ key: … }`; `undefined` when computed from a non-literal. */
+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;
+}
+/** `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;
+}
+// ─────────── Binding patterns ───────────
+/**
+ * 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 [];
+    }
+}
+const patternNames = (pattern) => patternBindings(pattern, []).map(b => b.name);
+// ─────────── Scopes ───────────
+const SCOPE_TYPES = new Set([
+    'Program',
+    'BlockStatement',
+    'StaticBlock',
+    'SwitchStatement',
+    'ForStatement',
+    'ForInStatement',
+    'ForOfStatement',
+]);
+/** Nearest scope enclosing the last node of `ancestors` (which `fullAncestor` includes in the list). */
+function enclosingScope(ancestors) {
+    for (let i = ancestors.length - 2; i > 0; i--) {
+        if (SCOPE_TYPES.has(ancestors[i].type)) {
+            return ancestors[i];
+        }
+    }
+    return ancestors[0];
+}
+
+exports.displayText = displayText;
+exports.enclosingScope = enclosingScope;
+exports.memberChain = memberChain;
+exports.patternBindings = patternBindings;
+exports.patternNames = patternNames;
+exports.propertyKey = propertyKey;
+exports.resolveOrSourceText = resolveOrSourceText;
+exports.sourceTextOf = sourceTextOf;

package/dist/backend/validate.d.ts

@@ -1,6 +1,9 @@
+import type { ApiUsage } from './parser/types';
+export type { ApiCall, ApiUsage } from './parser/types';
 export interface HandlerValidation {
     /** Every `ctx.api.v1.<domain>` the handler touches (known or not), sorted and unique. */
     apiDomains: string[];
+    apiUsages: ApiUsage;
 }
 /**
  * Validates a handler's source before upload: real parsing (via acorn) catches
@@ -12,9 +15,6 @@ export interface HandlerValidation {
  * 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/backend/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/backend/validate.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAkCrF"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/backend/validate.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAIxD,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAmCrF"}

package/dist/backend/validate.js

@@ -3,10 +3,12 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const acornWalk = require('acorn-walk');
 const z2hSharedUtils = require('@mondaydotcomorg/z2h-shared-utils');
 const util_logger = require('../util/logger.js');
-const backend_ast = require('./ast.js');
-const backend_handlerDeclaration = require('./handler-declaration.js');
-const backend_messages = require('./messages.js');
-const backend_parse = require('./parse.js');
+const backend_parser_apiUsage = require('./parser/api-usage.js');
+const backend_parser_bindings = require('./parser/bindings.js');
+const backend_parser_handlerDeclaration = require('./parser/handler-declaration.js');
+const backend_parser_memberPath = require('./parser/member-path.js');
+const backend_parser_messages = require('./parser/messages.js');
+const backend_parser_parse = require('./parser/parse.js');
 
 const KNOWN_API_DOMAINS = [...z2hSharedUtils.ALWAYS_ON_CHANNELS, ...z2hSharedUtils.DECLARED_INTEGRATIONS];
 /**
@@ -19,38 +21,36 @@ const KNOWN_API_DOMAINS = [...z2hSharedUtils.ALWAYS_ON_CHANNELS, ...z2hSharedUti
  * 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 = backend_parse.parseOrThrow(file, source);
-    const bindings = backend_ast.collectBindings(program);
+    const program = backend_parser_parse.parseOrThrow(file, source);
+    const bindings = backend_parser_bindings.collectBindings(program);
     acornWalk.simple(program, {
         CallExpression(node) {
             if (node.callee.type === 'Identifier' && node.callee.name === 'require') {
-                throw new Error(backend_messages.messages.mustNotImport(file));
+                throw new Error(backend_parser_messages.messages.mustNotImport(file));
             }
         },
         ImportExpression() {
-            throw new Error(backend_messages.messages.mustNotImport(file));
+            throw new Error(backend_parser_messages.messages.mustNotImport(file));
         },
     });
-    const declaration = backend_handlerDeclaration.findHandlerDeclaration(program.body);
+    const declaration = backend_parser_handlerDeclaration.findHandlerDeclaration(program.body);
     if (!declaration) {
-        throw new Error(backend_messages.messages.mustDefine(file));
+        throw new Error(backend_parser_messages.messages.mustDefine(file));
     }
-    if (declaration.kind === 'variable' && (!declaration.init || backend_handlerDeclaration.NEVER_A_FUNCTION.has(declaration.init.type))) {
-        throw new Error(backend_messages.messages.notAFunction(file));
+    if (declaration.kind === 'variable' && (!declaration.init || backend_parser_handlerDeclaration.NEVER_A_FUNCTION.has(declaration.init.type))) {
+        throw new Error(backend_parser_messages.messages.notAFunction(file));
     }
-    const paths = backend_ast.createPathResolver(bindings, backend_handlerDeclaration.handlerContextParamName(declaration));
-    const apiDomains = backend_ast.collectApiDomains(program, paths);
+    const paths = backend_parser_memberPath.createPathResolver(bindings, backend_parser_handlerDeclaration.handlerContextParamName(declaration));
+    const apiDomains = backend_parser_apiUsage.collectApiDomains(program, paths);
+    const apiUsages = backend_parser_apiUsage.collectApiUsages(program, bindings, paths, source);
     for (const domain of apiDomains) {
         if (!KNOWN_API_DOMAINS.includes(domain)) {
             util_logger.warn(`${file}: ctx.api.v1.${domain} is not a known capability (available: ${KNOWN_API_DOMAINS.join(', ')})`);
         }
     }
-    return { apiDomains: [...apiDomains].sort() };
+    return { apiDomains: [...apiDomains].sort(), apiUsages };
 }
 
 exports.validateHandlerSource = validateHandlerSource;

package/dist/commands/__tests__/llm-migration.test.d.ts

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

package/dist/commands/__tests__/llm-migration.test.d.ts.map

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

package/dist/commands/backend.d.ts

@@ -1,19 +1,9 @@
-/**
- * True if the app ships an app-level backend — a `backend/handlers/` directory.
- * Callers gate on this so the deploy path is explicit about whether a backend is in
- * play.
- */
 export declare function hasHandlers(appDir: string): boolean;
 /**
  * Deploy the app's backend handlers to S3 and return the integrations detected
  * from their sources. Each `.js` handler is uploaded as its own flat file — no
  * compilation, no bundling, no npm deps.
  *
- * Live and preview differ only in where the handlers land, so that is the only
- * thing `isPreview` switches:
- * - live:    `<appName>/backend-<version>` — the app's immutable per-version slot.
- * - preview: `<mfKeyPrefix without /MF>/MS` — beside the preview's `/MF` frontend.
- *
  * Integration sync note: the returned set is re-derived from the CURRENT backend
  * sources on every deploy, and the platform set is reconciled to exactly match
  * it (there is no stored declaration to fall back on). A deploy therefore always
@@ -29,9 +19,8 @@ export declare function deployBackend(opts: {
     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.
+ * Runs the same checks deploy does against the working tree, refreshing the
+ * local `usage.json` — no upload to S3. Throws on the first invalid handler.
  */
 export declare function backendValidateCommand(appDir?: string): Promise<void>;
 export declare function backendInvokeCommand(handlerName: string, opts?: {

package/dist/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;;;;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"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/commands/backend.ts"],"names":[],"mappings":"AAsBA,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAqDD;;;;;;;;;;GAUG;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;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe1F;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/commands/backend.js

@@ -2,9 +2,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const path = require('node:path');
 const fs = require('node:fs');
+const fs$1 = require('fs-extra');
 const clientS3 = require('@aws-sdk/client-s3');
 const util_logger = require('../util/logger.js');
 const util_appName = require('../util/app-name.js');
+const util_machineIdentity = require('../util/machine-identity.js');
 const backend_handlers = require('../backend/handlers.js');
 const backend_detectIntegrations = require('../backend/detect-integrations.js');
 const util_s3_client = require('../util/s3/client.js');
@@ -23,30 +25,41 @@ function currentAppName() {
     }
     return util_appName.mfAppName(raw);
 }
-/**
- * True if the app ships an app-level backend — a `backend/handlers/` directory.
- * Callers gate on this so the deploy path is explicit about whether a backend is in
- * play.
- */
 function hasHandlers(appDir) {
     return fs.existsSync(path__default.default.join(appDir, 'backend', 'handlers'));
 }
+/** Other features may add top-level fields, so writes below merge into this copy instead of replacing it. */
+async function readExistingUsage(appDir) {
+    try {
+        return (await fs$1.readJson(path__default.default.join(appDir, 'usage.json')));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return {};
+        }
+        throw err;
+    }
+}
+/** Keeps the app's git-tracked `usage.json` current with every handler parse (validate or deploy). */
+async function writeUsageJson(appDir, patch) {
+    const existing = await readExistingUsage(appDir);
+    await fs$1.writeJson(path__default.default.join(appDir, 'usage.json'), { ...existing, ...patch }, { spaces: 2 });
+}
 /**
- * Read handlers, detect declared integrations, and upload to `prefix` when there
- * is anything to upload. Returns `[]` when there is no `backend/handlers/` dir
- * (or it is empty of sources) so callers can always pass the result to
- * `registerOrUpdateApp` without a separate gate.
+ * Returns `[]` when there is no `backend/handlers/` dir (or it is empty of sources)
+ * so callers can always pass the result to `registerOrUpdateApp` without a separate gate.
  */
-async function readDetectAndUpload(appDir, prefix, version, deployedBy, logLabel) {
+async function readDetectAndUpload(appDir, prefix, appName, version, deployedBy, logLabel) {
     if (!hasHandlers(appDir)) {
         return [];
     }
     util_logger.info(`reading backend handlers ${logLabel}`);
-    const { handlers, apiDomains } = await backend_handlers.readHandlers(appDir);
+    const { handlers, apiDomains, apiUsages } = await backend_handlers.readHandlers(appDir);
     const integrations = backend_detectIntegrations.detectIntegrations(apiDomains);
     if (Object.keys(handlers).length === 0) {
         return integrations;
     }
+    await writeUsageJson(appDir, { appName, deployedBy, apiUsages });
     const s3 = util_s3_client.getS3Client();
     const meta = JSON.stringify({ version, deployedBy, handlers: Object.keys(handlers) });
     const put = (key, body, contentType) => s3.send(new clientS3.PutObjectCommand({ Bucket: constants.BUCKET_WRITE_NAME, Key: key, Body: body, ContentType: contentType }));
@@ -61,11 +74,6 @@ async function readDetectAndUpload(appDir, prefix, version, deployedBy, logLabel
  * from their sources. Each `.js` handler is uploaded as its own flat file — no
  * compilation, no bundling, no npm deps.
  *
- * Live and preview differ only in where the handlers land, so that is the only
- * thing `isPreview` switches:
- * - live:    `<appName>/backend-<version>` — the app's immutable per-version slot.
- * - preview: `<mfKeyPrefix without /MF>/MS` — beside the preview's `/MF` frontend.
- *
  * Integration sync note: the returned set is re-derived from the CURRENT backend
  * sources on every deploy, and the platform set is reconciled to exactly match
  * it (there is no stored declaration to fall back on). A deploy therefore always
@@ -77,25 +85,26 @@ async function deployBackend(opts) {
     const prefix = isPreview ? `${mfKeyPrefix.replace(/\/MF$/, '')}/MS` : `${appName}/backend-${version}`;
     const logLabel = isPreview ? 'for preview' : `for "${appName}"`;
     try {
-        return await readDetectAndUpload(appDir, prefix, version, deployedBy, logLabel);
+        return await readDetectAndUpload(appDir, prefix, appName, version, deployedBy, logLabel);
     }
     catch (err) {
         throw util_errors.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.
+ * Runs the same checks deploy does against the working tree, refreshing the
+ * local `usage.json` — no upload to S3. Throws on the first invalid handler.
  */
 async function backendValidateCommand(appDir = process.cwd()) {
     if (!hasHandlers(appDir)) {
         util_logger.output('[z2h-cli] no backend/handlers/ directory — nothing to validate', { handlers: [], integrations: [] });
         return;
     }
-    const { handlers, apiDomains } = await backend_handlers.readHandlers(appDir);
+    const { handlers, apiDomains, apiUsages } = await backend_handlers.readHandlers(appDir);
     const names = Object.keys(handlers).sort();
     const integrations = backend_detectIntegrations.detectIntegrations(apiDomains);
+    const { name } = (await fs$1.readJson(path__default.default.join(appDir, 'package.json')));
+    await writeUsageJson(appDir, { appName: name ? util_appName.mfAppName(name) : undefined, deployedBy: util_machineIdentity.whoAmI(), apiUsages });
     const list = (xs) => (xs.length ? xs.join(', ') : 'none');
     util_logger.output(`[z2h-cli] ${names.length} handler(s) valid: ${list(names)}\n[z2h-cli] integrations: ${list(integrations)}`, {
         handlers: names,

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

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAKpH,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwBD,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6F5F"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAKpH,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwBD,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8F5F"}

package/dist/commands/create.js

@@ -90,6 +90,7 @@ async function createCommand(appName, opts = {}) {
     await fs.copy(path__default.default.join(appTemplatesDir, 'gitignore'), path__default.default.join(appDir, '.gitignore'));
     await fs.copy(path__default.default.join(appTemplatesDir, 'claude-settings.json'), path__default.default.join(appDir, '.claude', 'settings.json'));
     await fs.copy(path__default.default.join(appTemplatesDir, 'CLAUDE.md'), path__default.default.join(appDir, 'CLAUDE.md'));
+    await fs.copy(path__default.default.join(appTemplatesDir, 'usage.json'), path__default.default.join(appDir, 'usage.json'));
     // html-embed: also copy the source HTML.
     if (template === 'html-embed' && opts.htmlFile) {
         await fs.copy(opts.htmlFile, path__default.default.join(appDir, 'src', 'page.html'));

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;AAkBtG,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":"AAkBA,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

@@ -1,6 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-const os = require('node:os');
 const path = require('node:path');
 const fs = require('fs-extra');
 const util_logger = require('../util/logger.js');
@@ -26,13 +25,8 @@ const commands_tag = require('./tag.js');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
-const os__default = /*#__PURE__*/_interopDefault(os);
 const path__default = /*#__PURE__*/_interopDefault(path);
 
-/** Who is publishing this version — the machine identity, else the OS user. */
-function whoDeployed() {
-    return util_machineIdentity.getMachineAppName() ?? os__default.default.userInfo().username;
-}
 // Should be run from the consumer app directory — uses process.cwd() to locate it.
 async function deployCommand(opts = {}) {
     const paths = shadow_paths.resolveConsumerPaths(process.cwd());
@@ -75,7 +69,7 @@ async function buildAndStamp(opts) {
     else {
         ({ assetManifest } = await commands_build.buildCommand({ publicUrl: opts.publicUrl }));
     }
-    const deployedBy = whoDeployed();
+    const deployedBy = util_machineIdentity.whoAmI();
     return {
         ...assetManifest,
         version: opts.nextVersion,
@@ -101,7 +95,7 @@ async function uploadAndRegister(opts) {
         appName,
         mfKeyPrefix: keyPrefix,
         version: nextVersion,
-        deployedBy: whoDeployed(),
+        deployedBy: util_machineIdentity.whoAmI(),
         isPreview,
     });
     await util_broker_app.registerOrUpdateApp({

package/dist/commands/llm-migration.d.ts

@@ -0,0 +1,6 @@
+export interface LlmMigrationOptions {
+    /** Omit to list every LLM migration instead of printing one guide. */
+    migration?: string;
+}
+export declare function llmMigrationCommand(opts: LlmMigrationOptions): Promise<void>;
+//# sourceMappingURL=llm-migration.d.ts.map

package/dist/commands/llm-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-migration.d.ts","sourceRoot":"","sources":["../../src/commands/llm-migration.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBlF"}

package/dist/commands/llm-migration.js

@@ -0,0 +1,33 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const util_logger = require('../util/logger.js');
+const util_migrationsJson = require('../util/migrations-json.js');
+
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+
+async function llmMigrationCommand(opts) {
+    const resolved = await util_migrationsJson.resolveMigrationsJson();
+    if (!resolved) {
+        throw new Error('migrations.json not found');
+    }
+    const { migrationsJson, migrationsDir } = resolved;
+    if (!opts.migration) {
+        const migrations = Object.entries(migrationsJson.migrations)
+            .filter(([, entry]) => entry.type === util_migrationsJson.LLM_MIGRATION_TYPE)
+            .map(([name, entry]) => ({ name, description: entry.description }));
+        util_logger.output(migrations.map(m => `${m.name}\n  ${m.description}`).join('\n'), { ok: true, migrations });
+        return;
+    }
+    const entry = migrationsJson.migrations[opts.migration];
+    if (entry?.type !== util_migrationsJson.LLM_MIGRATION_TYPE) {
+        throw new Error(`no LLM migration named "${opts.migration}"`);
+    }
+    const guide = await fs.readFile(path__default.default.resolve(migrationsDir, entry.guide), 'utf8');
+    util_logger.output(guide, { ok: true, description: entry.description, guide });
+}
+
+exports.llmMigrationCommand = llmMigrationCommand;

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

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AA4BA,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnD;AAqBD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmGjG"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAiBA,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnD;AAqBD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4FjG"}

package/dist/commands/migrate.js

@@ -2,20 +2,18 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const node_module = require('node:module');
 const path = require('node:path');
-const node_url = require('node:url');
 const fs = require('fs-extra');
 const semver = require('semver');
 const util_logger = require('../util/logger.js');
 const util_workspace = require('../util/workspace.js');
+const util_migrationsJson = require('../util/migrations-json.js');
 
-var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
 const path__default = /*#__PURE__*/_interopDefault(path);
 const semver__default = /*#__PURE__*/_interopDefault(semver);
 
 const STATE_FILE = '.z2h-migrations-state.json';
-// ─── Helpers ───
 // A prerelease sorts BELOW its own release under plain semver ordering, so
 // comparing raw beta versions here would skip migrations the beta introduced.
 function baseVersion(version) {
@@ -55,19 +53,14 @@ async function migrateCommand(cliVersion, opts = {}) {
         return;
     }
     util_logger.info(`migrating workspace from v${lastVersion} → v${targetVersion}...`);
-    // migrations.json is at the package root — two dirs up from dist/migrations/
-    const thisDir = path__default.default.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('commands/migrate.js', document.baseURI).href))));
-    const migrationsJsonPath = path__default.default.resolve(thisDir, '..', '..', 'migrations.json');
-    if (!(await fs.pathExists(migrationsJsonPath))) {
+    const resolved = await util_migrationsJson.resolveMigrationsJson();
+    if (!resolved) {
         util_logger.warn('migrations.json not found — skipping migrations');
         return;
     }
-    const migrationsJson = (await fs.readJson(migrationsJsonPath));
-    // Filter to pending migrations (version > lastVersion AND <= targetVersion).
-    // CONVENTION: a migration's `version` field must equal the CLI release it
-    // ships with (not the feature branch version). This ensures the `gt` check
-    // always catches a migration on the exact upgrade that introduces it.
+    const { migrationsJson, migrationsDir } = resolved;
     const pending = Object.entries(migrationsJson.migrations)
+        .filter((pair) => pair[1].type !== util_migrationsJson.LLM_MIGRATION_TYPE)
         .filter(([, entry]) => semver__default.default.gt(entry.version, lastVersion) && semver__default.default.lte(entry.version, targetVersion))
         .sort(([, a], [, b]) => semver__default.default.compare(a.version, b.version));
     if (opts.dryRun) {
@@ -93,7 +86,7 @@ async function migrateCommand(cliVersion, opts = {}) {
     for (const [name, entry] of pending) {
         const tree = new FsTree(workspaceHome, false);
         try {
-            const factoryPath = path__default.default.resolve(path__default.default.dirname(migrationsJsonPath), entry.migrate);
+            const factoryPath = path__default.default.resolve(migrationsDir, entry.migrate);
             const mod = require(factoryPath);
             const fn = mod.default || mod;
             fn(tree);

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

@@ -1,8 +1,11 @@
+import { type ApiUsage } from './validate';
 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[];
+    /** handler name → per-call `ctx.api.v1` usage, for `usage.json`. */
+    apiUsages: Record<string, ApiUsage>;
 }
 /**
  * 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":"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"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/backend/handlers.ts"],"names":[],"mappings":"AAGA,OAAO,EAAyB,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIlE,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,0EAA0E;IAC1E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA8BnF"}

package/dist/esm/backend/handlers.mjs

@@ -12,27 +12,30 @@ const HANDLERS_DIR = path.join('backend', 'handlers');
 async function readHandlers(consumerDir) {
     const handlersDir = path.join(consumerDir, HANDLERS_DIR);
     if (!(await pathExists(handlersDir))) {
-        return { handlers: {}, apiDomains: [] };
+        return { handlers: {}, apiDomains: [], apiUsages: {} };
     }
     const entries = await readdir(handlersDir);
     const tsFiles = entries.filter(f => f.endsWith('.ts'));
     if (tsFiles.length > 0) {
         throw new Error(`TypeScript handlers are not yet supported (${tsFiles.join(', ')}). Compile to .js first.`);
     }
-    const jsFiles = entries.filter(f => f.endsWith('.js'));
+    // Sorted so usage.json's key order is deterministic across machines, not readdir()'s.
+    const jsFiles = entries.filter(f => f.endsWith('.js')).sort();
     if (jsFiles.length === 0) {
-        return { handlers: {}, apiDomains: [] };
+        return { handlers: {}, apiDomains: [], apiUsages: {} };
     }
     const handlers = {};
     const apiDomains = new Set();
+    const apiUsages = {};
     for (const file of jsFiles) {
         const handlerName = path.parse(file).name;
         const source = await readFile(path.join(handlersDir, file), 'utf8');
         const validation = validateHandlerSource(file, source);
         validation.apiDomains.forEach(d => apiDomains.add(d));
         handlers[handlerName] = source;
+        apiUsages[handlerName] = validation.apiUsages;
     }
-    return { handlers, apiDomains: [...apiDomains].sort() };
+    return { handlers, apiDomains: [...apiDomains].sort(), apiUsages };
 }
 
 export { readHandlers };

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

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

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

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

package/dist/esm/backend/parser/api-signatures.d.ts

@@ -0,0 +1,4 @@
+import type { ApiSignatures } from './types';
+/** Derived from the runner's channel docs by `scripts/generate-handler-api.mjs` at build time. */
+export declare function loadApiSignatures(): ApiSignatures;
+//# sourceMappingURL=api-signatures.d.ts.map

package/dist/esm/backend/parser/api-signatures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-signatures.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/api-signatures.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAI7C,kGAAkG;AAClG,wBAAgB,iBAAiB,IAAI,aAAa,CAcjD"}

package/dist/esm/backend/parser/api-signatures.mjs

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+let cached;
+/** Derived from the runner's channel docs by `scripts/generate-handler-api.mjs` at build time. */
+function loadApiSignatures() {
+    if (cached) {
+        return cached;
+    }
+    const root = path.dirname(createRequire(import.meta.url).resolve('@mondaydotcomorg/z2h-cli/package.json'));
+    try {
+        cached = JSON.parse(readFileSync(path.join(root, 'handler-api', 'signatures.json'), 'utf8'));
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+        cached = {};
+    }
+    return cached;
+}
+
+export { loadApiSignatures };

package/dist/esm/backend/parser/api-usage.d.ts

@@ -0,0 +1,5 @@
+import type { Program } from 'acorn';
+import type { ApiSignatures, ApiUsage, Bindings, PathResolver } from './types';
+export declare function collectApiDomains(program: Program, paths: PathResolver): Set<string>;
+export declare function collectApiUsages(program: Program, bindings: Bindings, paths: PathResolver, source: string, signatures?: ApiSignatures): ApiUsage;
+//# sourceMappingURL=api-usage.d.ts.map

package/dist/esm/backend/parser/api-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-usage.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/api-usage.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAW,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAcxF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,GAAG,GAAG,CAAC,MAAM,CAAC,CAWpF;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,aAAmC,GAC9C,QAAQ,CAkCV"}