@mondaydotcomorg/z2h-cli 0.29.5 → 0.31.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/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,
@@ -90,7 +84,7 @@ async function buildAndStamp(opts) {
  * register the release with the platform in one server-side transaction.
  */
 async function uploadAndRegister(opts) {
-    const { paths, keyPrefix, appName, token, nextVersion, entry, gitRemote, isPreview, description } = opts;
+    const { paths, keyPrefix, appName, token, nextVersion, entry, gitRemote, isPreview, description, masterAppName } = opts;
     util_logger.info(`uploading ${isPreview ? 'preview ' : ''}build → s3://${constants.BUCKET_WRITE_NAME}/${keyPrefix}/`);
     await util_s3_upload.uploadDir(paths.shadowBuild, keyPrefix);
     // `integrations` is inferred from the backend sources in the working tree and
@@ -101,12 +95,28 @@ async function uploadAndRegister(opts) {
         appName,
         mfKeyPrefix: keyPrefix,
         version: nextVersion,
-        deployedBy: whoDeployed(),
+        deployedBy: util_machineIdentity.whoAmI(),
         isPreview,
     });
-    await util_broker_app.registerOrUpdateApp({ appName, token, nextVersion, entry, gitRemote, integrations, description });
+    await util_broker_app.registerOrUpdateApp({
+        appName,
+        token,
+        nextVersion,
+        entry,
+        gitRemote,
+        integrations,
+        description,
+        masterAppName,
+    });
 }
 async function deployPreview({ paths, consumerName, appName, token, opts }) {
+    // A preview inherits from the live app it previews, resolved by name server-side —
+    // fail fast with an actionable message if that app was never claimed/deployed (e.g. a
+    // local checkout scaffolded before `create` started claiming names), rather than
+    // letting a deep backend 404 surface as a generic "App registration failed".
+    if (!(await util_broker_app.fetchApp(appName))) {
+        throw new util_errors.DeployError('register_error', `Cannot preview "${appName}": it has never been created or deployed. Run 'z2h-cli create ${consumerName}' (or deploy it once) first.`);
+    }
     await fs.ensureDir(paths.shadowDir);
     const { previewId } = await shadow_prepare.resolvePortAndMetadata(paths, util_appName.cleanAppName(consumerName));
     const previewSlug = util_appName.buildPreviewSlug(consumerName, previewId);
@@ -138,6 +148,7 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
         entry,
         gitRemote: '',
         isPreview: true,
+        masterAppName: appName,
     });
     const previewUrl = `https://bigbrain.me/bigbrain-vibe/${previewSlug}`;
     util_logger.output(`[z2h-cli] preview ready ✅\n  app:            ${appName}\n  previewAppName: ${previewAppName}\n  open:           ${previewUrl}`, {

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

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAwHD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA8E3F"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAwHD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAqF3F"}

package/dist/commands/generate.js

@@ -141,6 +141,12 @@ async function generateCommand(appName, opts) {
     if (existing?.deployed) {
         throw new Error(`An app named "${appName}" already exists in the Z2H registry. Pick a different name.`);
     }
+    // generate skips `create` entirely, but the preview it deploys below still resolves this
+    // app's own row by name server-side — claim it now so that lookup finds something, same as
+    // `create` does for the normal flow.
+    if (!existing) {
+        await util_broker_app.claimApp(util_appName.mfAppName(appName), util_git_repo.defaultS3Remote(appName));
+    }
     util_logger.info(`copying template "${template.id}" → ${appDir}`);
     // Excludes node_modules (installed into templateDir itself by build-templates.mjs, never
     // needed by the generated app), .build-shadow (a scratch dir that build-templates.mjs

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"}

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

@@ -0,0 +1,58 @@
+import { simple } from 'acorn-walk';
+import { resolveOrSourceText } from './utils.mjs';
+import { bestSourceText, staticValue } from './static-value.mjs';
+import { loadApiSignatures } from './api-signatures.mjs';
+
+// ctx.api.v1.<domain>.<method>(...) — the only API shape the runner exposes today
+const API_PREFIX = ['ctx', 'api', 'v1'];
+const API_CALL_MIN_PARTS = API_PREFIX.length + 2;
+function isApiPath(parts) {
+    return parts[0] === API_PREFIX[0] && parts[1] === API_PREFIX[1] && parts[2] === API_PREFIX[2];
+}
+function isApiCall(parts) {
+    return isApiPath(parts) && parts.length >= API_CALL_MIN_PARTS;
+}
+function collectApiDomains(program, paths) {
+    const apiDomains = new Set();
+    simple(program, {
+        MemberExpression(node) {
+            const parts = paths.pathOf(node)?.split('.') ?? [];
+            if (isApiPath(parts) && parts[3]) {
+                apiDomains.add(parts[3]);
+            }
+        },
+    });
+    return apiDomains;
+}
+function collectApiUsages(program, bindings, paths, source, signatures = loadApiSignatures()) {
+    const apiUsages = {};
+    simple(program, {
+        CallExpression(node) {
+            if (node.callee.type !== 'MemberExpression' && node.callee.type !== 'Identifier') {
+                return;
+            }
+            const parts = paths.pathOf(node.callee)?.split('.') ?? [];
+            if (!isApiCall(parts)) {
+                return;
+            }
+            const [, , , domain, ...methodParts] = parts;
+            const method = methodParts.join('.');
+            const sigKey = `${domain}.${method}`;
+            const names = signatures[sigKey];
+            if (!names) {
+                // eslint-disable-next-line no-console
+                console.warn(`[ast] no signature for ${sigKey} — argument names will be positional`);
+            }
+            const call = {};
+            node.arguments.forEach((arg, i) => {
+                call[names?.[i] ?? `arg${i}`] = resolveOrSourceText(arg, source, node => staticValue(node, bindings, source, new Set()), node => bestSourceText(node, source, bindings));
+            });
+            const methods = (apiUsages[domain] ??= {});
+            const calls = (methods[method] ??= []);
+            calls.push(call);
+        },
+    });
+    return apiUsages;
+}
+
+export { collectApiDomains, collectApiUsages };

package/dist/esm/backend/parser/bindings.d.ts

@@ -0,0 +1,5 @@
+import type { Program } from 'acorn';
+import type { Bindings, Declaration } from './types';
+export declare function collectBindings(program: Program): Bindings;
+export declare function declarationAt(bindings: Bindings, name: string, position: number): Declaration | undefined;
+//# sourceMappingURL=bindings.d.ts.map

package/dist/esm/backend/parser/bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/bindings.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA0B,OAAO,EAAE,MAAM,OAAO,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAcrD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CA2D1D;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAQzG"}