@mondaydotcomorg/z2h-cli 0.29.5 → 0.31.0

package/dist/esm/commands/backend.mjs

@@ -1,8 +1,10 @@
 import path from 'node:path';
 import { existsSync } from 'node:fs';
+import { readJson, writeJson } from 'fs-extra';
 import { PutObjectCommand } from '@aws-sdk/client-s3';
 import { output, info } from '../util/logger.mjs';
-import { getCwdAppName, mfAppName } from '../util/app-name.mjs';
+import { mfAppName, getCwdAppName } from '../util/app-name.mjs';
+import { whoAmI } from '../util/machine-identity.mjs';
 import { readHandlers } from '../backend/handlers.mjs';
 import { detectIntegrations } from '../backend/detect-integrations.mjs';
 import { getS3Client } from '../util/s3/client.mjs';
@@ -17,30 +19,41 @@ function currentAppName() {
     }
     return 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 existsSync(path.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 readJson(path.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 writeJson(path.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 [];
     }
     info(`reading backend handlers ${logLabel}`);
-    const { handlers, apiDomains } = await readHandlers(appDir);
+    const { handlers, apiDomains, apiUsages } = await readHandlers(appDir);
     const integrations = detectIntegrations(apiDomains);
     if (Object.keys(handlers).length === 0) {
         return integrations;
     }
+    await writeUsageJson(appDir, { appName, deployedBy, apiUsages });
     const s3 = getS3Client();
     const meta = JSON.stringify({ version, deployedBy, handlers: Object.keys(handlers) });
     const put = (key, body, contentType) => s3.send(new PutObjectCommand({ Bucket: BUCKET_WRITE_NAME, Key: key, Body: body, ContentType: contentType }));
@@ -55,11 +68,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
@@ -71,25 +79,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 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)) {
         output('[z2h-cli] no backend/handlers/ directory — nothing to validate', { handlers: [], integrations: [] });
         return;
     }
-    const { handlers, apiDomains } = await readHandlers(appDir);
+    const { handlers, apiDomains, apiUsages } = await readHandlers(appDir);
     const names = Object.keys(handlers).sort();
     const integrations = detectIntegrations(apiDomains);
+    const { name } = (await readJson(path.join(appDir, 'package.json')));
+    await writeUsageJson(appDir, { appName: name ? mfAppName(name) : undefined, deployedBy: whoAmI(), apiUsages });
     const list = (xs) => (xs.length ? xs.join(', ') : 'none');
     output(`[z2h-cli] ${names.length} handler(s) valid: ${list(names)}\n[z2h-cli] integrations: ${list(integrations)}`, {
         handlers: names,

package/dist/esm/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/esm/commands/create.mjs

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

package/dist/esm/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/esm/commands/deploy.mjs

@@ -1,4 +1,3 @@
-import os from 'node:os';
 import path from 'node:path';
 import { readJson, ensureDir, copy } from 'fs-extra';
 import { info, output, getOutputMode, warn } from '../util/logger.mjs';
@@ -13,8 +12,8 @@ import { getRemoteUrl, initRepo, guardCleanTree, pullAndResolve, pushToRemote }
 import { resolveGitEnv } from '../util/git/git-env.mjs';
 import { validateRemoteOptions, resolveRemoteUrl } from '../util/git/remote-options.mjs';
 import { setupS3Client } from '../util/s3/client.mjs';
-import { getMachineAppName } from '../util/machine-identity.mjs';
-import { registerOrUpdateApp } from '../util/broker/app.mjs';
+import { whoAmI } from '../util/machine-identity.mjs';
+import { fetchApp, registerOrUpdateApp } from '../util/broker/app.mjs';
 import { openInBrowser } from '../util/open-browser.mjs';
 import { resolvePortAndMetadata } from '../shadow/prepare.mjs';
 import { tagDeployError, DeployError, grantReasonForStatus } from '../util/errors.mjs';
@@ -22,10 +21,6 @@ import { deployBackend } from './backend.mjs';
 import { buildCommand } from './build.mjs';
 import { promptForTags } from './tag.mjs';
 
-/** Who is publishing this version — the machine identity, else the OS user. */
-function whoDeployed() {
-    return getMachineAppName() ?? os.userInfo().username;
-}
 // Should be run from the consumer app directory — uses process.cwd() to locate it.
 async function deployCommand(opts = {}) {
     const paths = resolveConsumerPaths(process.cwd());
@@ -68,7 +63,7 @@ async function buildAndStamp(opts) {
     else {
         ({ assetManifest } = await buildCommand({ publicUrl: opts.publicUrl }));
     }
-    const deployedBy = whoDeployed();
+    const deployedBy = whoAmI();
     return {
         ...assetManifest,
         version: opts.nextVersion,
@@ -83,7 +78,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;
     info(`uploading ${isPreview ? 'preview ' : ''}build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
     await uploadDir(paths.shadowBuild, keyPrefix);
     // `integrations` is inferred from the backend sources in the working tree and
@@ -94,12 +89,28 @@ async function uploadAndRegister(opts) {
         appName,
         mfKeyPrefix: keyPrefix,
         version: nextVersion,
-        deployedBy: whoDeployed(),
+        deployedBy: whoAmI(),
         isPreview,
     });
-    await registerOrUpdateApp({ appName, token, nextVersion, entry, gitRemote, integrations, description });
+    await 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 fetchApp(appName))) {
+        throw new DeployError('register_error', `Cannot preview "${appName}": it has never been created or deployed. Run 'z2h-cli create ${consumerName}' (or deploy it once) first.`);
+    }
     await ensureDir(paths.shadowDir);
     const { previewId } = await resolvePortAndMetadata(paths, cleanAppName(consumerName));
     const previewSlug = buildPreviewSlug(consumerName, previewId);
@@ -131,6 +142,7 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
         entry,
         gitRemote: '',
         isPreview: true,
+        masterAppName: appName,
     });
     const previewUrl = `https://bigbrain.me/bigbrain-vibe/${previewSlug}`;
     output(`[z2h-cli] preview ready ✅\n  app:            ${appName}\n  previewAppName: ${previewAppName}\n  open:           ${previewUrl}`, {

package/dist/esm/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/esm/commands/generate.mjs

@@ -5,10 +5,10 @@ import { execa } from 'execa';
 import { pathExists, readdir } from 'fs-extra';
 import { assertWorkspace } from '../util/workspace.mjs';
 import { validateAppName, mfAppName, cleanAppName } from '../util/app-name.mjs';
-import { fetchApp } from '../util/broker/app.mjs';
+import { fetchApp, claimApp } from '../util/broker/app.mjs';
 import { patchBuiltBundle, patchOneFile } from '../util/dashboard-templates/patch-bundle.mjs';
 import { findTemplate } from '../util/dashboard-templates/load-catalog.mjs';
-import { initRepo, defaultS3Remote } from '../util/git/repo.mjs';
+import { defaultS3Remote, initRepo } from '../util/git/repo.mjs';
 import { info, output } from '../util/logger.mjs';
 
 // Must match zth-backend-runner's route pattern — fail at generate time, not at first invocation.
@@ -133,6 +133,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 claimApp(mfAppName(appName), defaultS3Remote(appName));
+    }
     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/templates/app/usage.mjs

@@ -0,0 +1,5 @@
+const usage = {
+	
+};
+
+export { usage as default };

package/dist/esm/util/broker/app.d.ts

@@ -30,6 +30,8 @@ export interface RegisterOrUpdateOptions {
     gitRemote: string;
     integrations?: string[];
     description?: string;
+    /** For a preview app's first registration, the real app it previews. Ignored past v1. */
+    masterAppName?: string;
 }
 /**
  * v1 creates the app row (+ owner grant, prompting for visibility); later

package/dist/esm/util/broker/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,uGAAuG;IACvG,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhF;AA4CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,uGAAuG;IACvG,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhF;AA6CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BtF"}

package/dist/esm/util/broker/app.mjs

@@ -47,11 +47,11 @@ async function claimApp(appName, gitRemote) {
         throw new Error(`Claiming app name failed (${res.status}): ${text.slice(0, 1024)}`);
     }
 }
-async function registerApp(appName, token, version, entry, visibility, gitRemote, integrations, description) {
+async function registerApp(appName, token, version, entry, visibility, gitRemote, integrations, description, masterAppName) {
     const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/register`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
-        body: JSON.stringify({ appName, version, entry, visibility, gitRemote, integrations, description }),
+        body: JSON.stringify({ appName, version, entry, visibility, gitRemote, integrations, description, masterAppName }),
     });
     if (!res.ok) {
         const text = await res.text();
@@ -77,12 +77,12 @@ async function updateApp(appName, token, version, entry, gitRemote, integrations
  * deploy and preview so this branching logic lives in exactly one place.
  */
 async function registerOrUpdateApp(opts) {
-    const { appName, token, nextVersion, entry, gitRemote, integrations, description } = opts;
+    const { appName, token, nextVersion, entry, gitRemote, integrations, description, masterAppName } = opts;
     try {
         if (nextVersion === 1) {
             const visibility = await resolveAppVisibility(appName);
             info(`registering "${appName}" → v${nextVersion} (${visibility})`);
-            await registerApp(appName, token, nextVersion, entry, visibility, gitRemote, integrations, description);
+            await registerApp(appName, token, nextVersion, entry, visibility, gitRemote, integrations, description, masterAppName);
         }
         else {
             info(`updating "${appName}" → v${nextVersion}`);

package/dist/esm/util/machine-identity.d.ts

@@ -1,9 +1,8 @@
 /**
  * Returns the machine app name when running as a service (e.g. agent-runner).
  * Available when the process is a monday.com microservice with `APP_NAME` set
- * by the platform runtime.
- *
- * Returns `undefined` for interactive human users (fallback to os.userInfo).
+ * by the platform runtime. Returns `undefined` for interactive human users.
  */
 export declare function getMachineAppName(): string | undefined;
+export declare function whoAmI(): string;
 //# sourceMappingURL=machine-identity.d.ts.map

package/dist/esm/util/machine-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"machine-identity.d.ts","sourceRoot":"","sources":["../../../src/util/machine-identity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD"}
+{"version":3,"file":"machine-identity.d.ts","sourceRoot":"","sources":["../../../src/util/machine-identity.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD;AAED,wBAAgB,MAAM,IAAI,MAAM,CAE/B"}

package/dist/esm/util/machine-identity.mjs

@@ -1,12 +1,15 @@
+import os from 'node:os';
+
 /**
  * Returns the machine app name when running as a service (e.g. agent-runner).
  * Available when the process is a monday.com microservice with `APP_NAME` set
- * by the platform runtime.
- *
- * Returns `undefined` for interactive human users (fallback to os.userInfo).
+ * by the platform runtime. Returns `undefined` for interactive human users.
  */
 function getMachineAppName() {
     return process.env.APP_NAME || undefined;
 }
+function whoAmI() {
+    return getMachineAppName() ?? os.userInfo().username;
+}
 
-export { getMachineAppName };
+export { getMachineAppName, whoAmI };

package/dist/templates/app/usage.js

@@ -0,0 +1,7 @@
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+
+const usage = {
+	
+};
+
+exports.default = usage;

package/dist/util/broker/app.d.ts

@@ -30,6 +30,8 @@ export interface RegisterOrUpdateOptions {
     gitRemote: string;
     integrations?: string[];
     description?: string;
+    /** For a preview app's first registration, the real app it previews. Ignored past v1. */
+    masterAppName?: string;
 }
 /**
  * v1 creates the app row (+ owner grant, prompting for visibility); later

package/dist/util/broker/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,uGAAuG;IACvG,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhF;AA4CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,uGAAuG;IACvG,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhF;AA6CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BtF"}

package/dist/util/broker/app.js

@@ -49,11 +49,11 @@ async function claimApp(appName, gitRemote) {
         throw new Error(`Claiming app name failed (${res.status}): ${text.slice(0, 1024)}`);
     }
 }
-async function registerApp(appName, token, version, entry, visibility, gitRemote, integrations, description) {
+async function registerApp(appName, token, version, entry, visibility, gitRemote, integrations, description, masterAppName) {
     const res = await fetch(`${constants.brokerBaseUrl()}/z2h-cli/apps/register`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...constants.routingHeaders() },
-        body: JSON.stringify({ appName, version, entry, visibility, gitRemote, integrations, description }),
+        body: JSON.stringify({ appName, version, entry, visibility, gitRemote, integrations, description, masterAppName }),
     });
     if (!res.ok) {
         const text = await res.text();
@@ -79,12 +79,12 @@ async function updateApp(appName, token, version, entry, gitRemote, integrations
  * deploy and preview so this branching logic lives in exactly one place.
  */
 async function registerOrUpdateApp(opts) {
-    const { appName, token, nextVersion, entry, gitRemote, integrations, description } = opts;
+    const { appName, token, nextVersion, entry, gitRemote, integrations, description, masterAppName } = opts;
     try {
         if (nextVersion === 1) {
             const visibility = await util_promptVisibility.resolveAppVisibility(appName);
             util_logger.info(`registering "${appName}" → v${nextVersion} (${visibility})`);
-            await registerApp(appName, token, nextVersion, entry, visibility, gitRemote, integrations, description);
+            await registerApp(appName, token, nextVersion, entry, visibility, gitRemote, integrations, description, masterAppName);
         }
         else {
             util_logger.info(`updating "${appName}" → v${nextVersion}`);

package/dist/util/machine-identity.d.ts

@@ -1,9 +1,8 @@
 /**
  * Returns the machine app name when running as a service (e.g. agent-runner).
  * Available when the process is a monday.com microservice with `APP_NAME` set
- * by the platform runtime.
- *
- * Returns `undefined` for interactive human users (fallback to os.userInfo).
+ * by the platform runtime. Returns `undefined` for interactive human users.
  */
 export declare function getMachineAppName(): string | undefined;
+export declare function whoAmI(): string;
 //# sourceMappingURL=machine-identity.d.ts.map

package/dist/util/machine-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"machine-identity.d.ts","sourceRoot":"","sources":["../../src/util/machine-identity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD"}
+{"version":3,"file":"machine-identity.d.ts","sourceRoot":"","sources":["../../src/util/machine-identity.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD;AAED,wBAAgB,MAAM,IAAI,MAAM,CAE/B"}

package/dist/util/machine-identity.js

@@ -1,14 +1,22 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
+const os = require('node:os');
+
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const os__default = /*#__PURE__*/_interopDefault(os);
+
 /**
  * Returns the machine app name when running as a service (e.g. agent-runner).
  * Available when the process is a monday.com microservice with `APP_NAME` set
- * by the platform runtime.
- *
- * Returns `undefined` for interactive human users (fallback to os.userInfo).
+ * by the platform runtime. Returns `undefined` for interactive human users.
  */
 function getMachineAppName() {
     return process.env.APP_NAME || undefined;
 }
+function whoAmI() {
+    return getMachineAppName() ?? os__default.default.userInfo().username;
+}
 
 exports.getMachineAppName = getMachineAppName;
+exports.whoAmI = whoAmI;

package/handler-api/backend-runner/channels/snowflake-channel/run-query.ts

@@ -58,35 +58,32 @@ function hashQueryShape(rawSql: string): string {
 }
 
 /**
- * The permissions-aware pool returns different rows to different people, so the
- * cache key has to carry whatever decides that — the caller's roles and user
- * group, exactly as bigbrain-zth keys it. Get this wrong and one user is served
- * another's rows. The stateless pool reads as a fixed service account, so every
- * caller shares one entry there.
+ * The permissions-aware pool returns different rows to different people —
+ * including different rows to two people with the same roles/user_group, since
+ * Snowflake now enforces column/row-level grants per user. The cache key must
+ * therefore scope to the individual caller, exactly as bigbrain-zth keys it.
+ * The stateless pool reads as a fixed service account, so every caller shares
+ * one entry there.
  */
 /**
  * Returns the cache scope key for the current caller, or null when we must not
  * cache at all.
  *
- * On the permissions-aware path we hash the caller's roles + user_group, mirroring
+ * On the permissions-aware path we scope to the caller's user id, mirroring
  * bigbrain-zth exactly. If there is no execution context (e.g. the call arrived
  * outside a normal invoke flow) we fail **closed**: skipping both the cache read
  * and the write prevents an unauthenticated scope-collapse where every caller
- * would share one entry keyed by `hash('|')`.
+ * would share one entry.
  */
 function cacheScope(useStateless: boolean): string | null {
   if (useStateless) {
     return 'stateless';
   }
-  const user = context.execution.get()?.user as { roles?: string[]; user_group?: string } | undefined;
-  if (!user) {
+  const user = context.execution.get()?.user as { id?: number } | undefined;
+  if (!user?.id) {
     return null;
   }
-  const roles = [...(user.roles ?? [])].sort((a, b) => a.localeCompare(b)).join(',');
-  return createHash('sha256')
-    .update(`${roles}|${user.user_group ?? ''}`)
-    .digest('hex')
-    .slice(0, 16);
+  return `user:${user.id}`;
 }
 
 /**

package/handler-api/signatures.json

@@ -0,0 +1,26 @@
+{
+  "db.delete": [
+    "key"
+  ],
+  "db.get": [
+    "key"
+  ],
+  "db.list": [],
+  "db.put": [
+    "key",
+    "value"
+  ],
+  "llm.complete": [
+    "modelId",
+    "messages"
+  ],
+  "monday.query": [
+    "query",
+    "variables"
+  ],
+  "snowflake.query": [
+    "sql",
+    "params",
+    "options"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.29.5",
+  "version": "0.31.0",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/backend/__tests__/handlers.test.ts

@@ -5,6 +5,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { readHandlers } from '../handlers';
 
+vi.mock('../parser/api-signatures', () => ({
+  loadApiSignatures: () => ({ 'monday.query': ['query', 'variables'] }),
+}));
 vi.mock('../../util/tracker', () => ({
   trackEvent: vi.fn().mockResolvedValue(undefined),
   trackDuration: vi.fn(),
@@ -28,14 +31,14 @@ describe('readHandlers — discovery', () => {
   it('returns empty handlers when backend/handlers does not exist', async () => {
     const dir = await mkdtemp(path.join(os.tmpdir(), 'z2h-empty-'));
     try {
-      await expect(readHandlers(dir)).resolves.toEqual({ handlers: {}, apiDomains: [] });
+      await expect(readHandlers(dir)).resolves.toEqual({ handlers: {}, apiDomains: [], apiUsages: {} });
     } finally {
       await rm(dir, { recursive: true, force: true });
     }
   });
 
   it('returns empty handlers when the directory is empty', async () => {
-    await expect(readHandlers(appDir)).resolves.toEqual({ handlers: {}, apiDomains: [] });
+    await expect(readHandlers(appDir)).resolves.toEqual({ handlers: {}, apiDomains: [], apiUsages: {} });
   });
 
   it('uses the filename (without .js) as the handler name', async () => {
@@ -69,6 +72,14 @@ describe('readHandlers — output contract', () => {
     const { apiDomains } = await readHandlers(appDir);
     expect(apiDomains).toEqual(['db', 'monday']);
   });
+
+  it('attaches per-handler apiUsages keyed by handler name', async () => {
+    await writeHandler('a.js', 'async function handler(ctx) { return ctx.api.v1.monday.query("x"); }');
+    await writeHandler('c.js', 'async function handler(ctx) { return ctx.input; }');
+    const { apiUsages } = await readHandlers(appDir);
+    expect(apiUsages.a).toEqual({ monday: { query: [{ query: 'x' }] } });
+    expect(apiUsages.c).toEqual({});
+  });
 });
 
 // Per-shape validation rules are covered in validate.test.ts; here we only prove

package/src/backend/__tests__/validate.test.ts

@@ -3,6 +3,12 @@ import { warn } from '../../util/logger';
 import { validateHandlerSource } from '../validate';
 
 vi.mock('../../util/logger');
+vi.mock('../parser/api-signatures', () => ({
+  loadApiSignatures: () => ({
+    'snowflake.query': ['sql', 'params', 'options'],
+    'monday.query': ['query', 'variables'],
+  }),
+}));
 vi.mock('../../util/tracker', () => ({
   trackEvent: vi.fn().mockResolvedValue(undefined),
   trackDuration: vi.fn(),
@@ -203,3 +209,51 @@ describe('validateHandlerSource — ctx.api.v1 domains', () => {
     expect(warnMock).toHaveBeenCalledTimes(1);
   });
 });
+
+describe('validateHandlerSource — apiUsages (per-call domain/method/args)', () => {
+  it('records each call keyed by parameter name — static strings resolved, dynamic object values kept as source text', () => {
+    const { apiUsages } = validate(
+      'async function handler(ctx) { return ctx.api.v1.snowflake.query("SELECT 1", { userId: ctx.caller.id }); }'
+    );
+    expect(apiUsages).toEqual({ snowflake: { query: [{ sql: 'SELECT 1', params: { userId: 'ctx.caller.id' } }] } });
+  });
+
+  it('keeps multiple calls to the same method as separate entries', () => {
+    const { apiUsages } = validate(
+      'async function handler(ctx) { await ctx.api.v1.snowflake.query("SELECT 1"); return ctx.api.v1.snowflake.query("SELECT 2"); }'
+    );
+    expect(apiUsages.snowflake.query).toEqual([{ sql: 'SELECT 1' }, { sql: 'SELECT 2' }]);
+  });
+
+  it('falls back to source text for a dynamic argument and a dynamic array element', () => {
+    const { apiUsages } = validate(
+      'async function handler(ctx) { const q = ctx.input.q; return ctx.api.v1.monday.query(q, [ctx.input.id]); }'
+    );
+    expect(apiUsages.monday.query).toEqual([{ query: 'ctx.input.q', variables: ['ctx.input.id'] }]);
+  });
+
+  it('resolves a same-scope const alias back to its ctx.api.v1 chain', () => {
+    const { apiUsages } = validate(
+      'async function handler(ctx) { const d = ctx.api.v1.snowflake; return d.query("SELECT 1"); }'
+    );
+    expect(apiUsages).toEqual({ snowflake: { query: [{ sql: 'SELECT 1' }] } });
+  });
+
+  it('returns {} for a handler with no ctx.api.v1 calls', () => {
+    expect(validate('async function handler(ctx) { return ctx.input; }').apiUsages).toEqual({});
+  });
+
+  it('tracks a call reached through a computed string-literal member access', () => {
+    const { apiUsages } = validate(
+      'async function handler(ctx) { return ctx.api.v1.snowflake[\'query\']("SELECT 1"); }'
+    );
+    expect(apiUsages).toEqual({ snowflake: { query: [{ sql: 'SELECT 1' }] } });
+  });
+
+  it('does not track a call reached through a dynamic member access', () => {
+    const { apiUsages } = validate(
+      'async function handler(ctx) { const m = "query"; return ctx.api.v1.snowflake[m]("SELECT 1"); }'
+    );
+    expect(apiUsages).toEqual({});
+  });
+});