@mondaydotcomorg/z2h-cli 0.33.0 → 0.33.2

package/dist/esm/commands/backend.mjs

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
 import { readJson, writeJson } from 'fs-extra';
 import { PutObjectCommand } from '@aws-sdk/client-s3';
 import { output, info } from '../util/logger.mjs';
@@ -9,7 +10,9 @@ import { readHandlers } from '../backend/handlers.mjs';
 import { detectIntegrations } from '../backend/detect-integrations.mjs';
 import { getS3Client } from '../util/s3/client.mjs';
 import { BUCKET_WRITE_NAME } from '../constants.mjs';
-import { invokeBackend } from '../backend/client.mjs';
+import { runSandbox } from '../backend/client.mjs';
+import { formatSandboxRun } from '../backend/format-sandbox-run.mjs';
+import { validateHandlerSource } from '../backend/validate.mjs';
 import { tagDeployError } from '../util/errors.mjs';
 
 function currentAppName() {
@@ -39,21 +42,19 @@ async function writeUsageJson(appDir, patch) {
     const existing = await readExistingUsage(appDir);
     await writeJson(path.join(appDir, 'usage.json'), { ...existing, ...patch }, { spaces: 2 });
 }
-/**
- * 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, appName, version, deployedBy, logLabel) {
     if (!hasHandlers(appDir)) {
-        return [];
+        await writeUsageJson(appDir, { appName, deployedBy, apiUsages: {} });
+        return { integrations: [], handlerNames: [], apiUsages: {} };
     }
     info(`reading backend handlers ${logLabel}`);
     const { handlers, apiDomains, apiUsages } = await readHandlers(appDir);
     const integrations = detectIntegrations(apiDomains);
+    const handlerNames = Object.keys(handlers);
+    await writeUsageJson(appDir, { appName, deployedBy, apiUsages });
     if (Object.keys(handlers).length === 0) {
-        return integrations;
+        return { integrations, handlerNames, apiUsages };
     }
-    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 }));
@@ -61,13 +62,9 @@ async function readDetectAndUpload(appDir, prefix, appName, version, deployedBy,
         ...Object.entries(handlers).map(([name, code]) => put(`${prefix}/${name}.js`, code, 'application/javascript')),
         put(`${prefix}/meta.json`, meta, 'application/json'),
     ]);
-    return integrations;
+    return { integrations, handlerNames, apiUsages };
 }
 /**
- * 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.
- *
  * 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
@@ -105,7 +102,29 @@ async function backendValidateCommand(appDir = process.cwd()) {
         integrations,
     });
 }
-async function backendInvokeCommand(handlerName, opts = {}) {
+async function readHandlerSource(appDir, handlerName) {
+    const dir = path.join(appDir, 'backend', 'handlers');
+    try {
+        return await readFile(path.join(dir, `${handlerName}.js`), 'utf8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+        const files = hasHandlers(appDir) ? await readdir(dir) : [];
+        const available = files
+            .filter(f => f.endsWith('.js'))
+            .map(f => path.parse(f).name)
+            .sort();
+        throw new Error(`no handler "${handlerName}" in backend/handlers/` +
+            (available.length ? ` (available: ${available.join(', ')})` : ' (no handlers found)'));
+    }
+}
+/**
+ * Runs a handler from the working tree (or `--code`) on the runner's sandbox and
+ * prints the trace. Validated locally first, like deploy; exits 1 when the handler fails.
+ */
+async function backendInvokeCommand(handlerName, opts = {}, appDir = process.cwd()) {
     const appName = currentAppName();
     let input = null;
     if (opts.input) {
@@ -116,8 +135,15 @@ async function backendInvokeCommand(handlerName, opts = {}) {
             throw new Error(`--input must be valid JSON (got: ${opts.input})`);
         }
     }
-    const res = await invokeBackend(appName, handlerName, input);
-    output(`[z2h-cli] result (${Math.round(res.durationMs)}ms):\n${JSON.stringify(res.result, null, 2)}`, res);
+    const file = `${handlerName}.js`;
+    const code = opts.code ?? (await readHandlerSource(appDir, handlerName));
+    validateHandlerSource(file, code);
+    info(`validated ${opts.code ? '--code' : file}`);
+    const res = await runSandbox(appName, { code, input, handlerName });
+    output(formatSandboxRun(res), res);
+    if (!res.ok) {
+        process.exitCode = 1;
+    }
 }
 
 export { backendInvokeCommand, backendValidateCommand, deployBackend, hasHandlers };

package/dist/esm/commands/deploy.mjs

@@ -79,12 +79,9 @@ async function buildAndStamp(opts) {
  */
 async function uploadAndRegister(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
-    // reconciled to exactly match on register — see `deployBackend` for why this
-    // depends on deploying from the app's latest merged state.
-    const integrations = await deployBackend({
+    // Runs before the frontend upload so a `deployBackend` failure can't leave a
+    // preview's unversioned `MF` dir overwritten with no rollback.
+    const { integrations, handlerNames, apiUsages } = await deployBackend({
         appDir: process.cwd(),
         appName,
         mfKeyPrefix: keyPrefix,
@@ -92,16 +89,32 @@ async function uploadAndRegister(opts) {
         deployedBy: whoAmI(),
         isPreview,
     });
-    await registerOrUpdateApp({
-        appName,
-        token,
-        nextVersion,
-        entry,
-        gitRemote,
-        integrations,
-        description,
-        masterAppName,
-    });
+    try {
+        info(`uploading ${isPreview ? 'preview ' : ''}build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
+        await uploadDir(paths.shadowBuild, keyPrefix);
+        await registerOrUpdateApp({
+            appName,
+            token,
+            nextVersion,
+            entry,
+            gitRemote,
+            integrations,
+            handlerNames,
+            apiUsages,
+            description,
+            masterAppName,
+        });
+    }
+    catch (err) {
+        // A live deploy is safe either way — RDS's version gates what's actually served, so
+        // an orphaned S3 object is harmless — but a preview is served straight from its
+        // unversioned prefix with no such gate, so only it needs the warning below.
+        if (isPreview) {
+            warn(`preview backend was already deployed before this failed — re-run "z2h-cli deploy --preview" to retry ` +
+                `(every step overwrites, so a retry fully repairs it)`);
+        }
+        throw err;
+    }
 }
 async function deployPreview({ paths, consumerName, appName, token, opts }) {
     // A preview inherits from the live app it previews, resolved by name server-side —

package/dist/esm/index.mjs

@@ -180,15 +180,18 @@ async function main() {
         .action(runCommand({ data: cwdApp }, (opts) => deleteCommand(opts)));
     const backend = program
         .command('backend')
-        .description("Inspect the app's backend: validate handler sources or invoke a deployed handler by name");
+        .description("Inspect the app's backend: validate handler sources or run a handler from the working tree");
     backend
         .command('validate')
         .description('Validate backend/handlers/*.js exactly as deploy would (syntax, isolate rules, integrations) without uploading')
         .action(runCommand({ data: cwdApp }, () => backendValidateCommand()));
     backend
         .command('invoke <handlerName>')
-        .description('Invoke a deployed backend handler by name (the filename without .ts) — mainly for testing a handler without going through the frontend')
-        .option('--input <json>', 'JSON payload passed as ctx.input')
+        .description("Run backend/handlers/<handlerName>.js from the working tree — not the deployed handler — against the app's real " +
+        'channels (real db data, real monday calls), and print a trace of every channel call and the ' +
+        'result. Nothing is deployed. Exits 1 when the handler fails.')
+        .option('--input <json>', 'JSON passed to the handler as ctx.input (what the frontend would send)')
+        .option('--code <source>', 'run this source instead of backend/handlers/<handlerName>.js — <handlerName> is then just a label')
         .action(runCommand({
         data: ([handlerName]) => ({ app_name: getCwdAppName(), handler: handlerName }),
     }, (handlerName, opts) => backendInvokeCommand(handlerName, opts)));
@@ -215,7 +218,9 @@ void main()
     if (getOutputMode() === 'human') {
         selfUpdate();
     }
-    process.exit(0);
+    // A command can finish normally and still report a non-zero code (e.g.
+    // `backend invoke` when the handler failed) via process.exitCode.
+    process.exit(process.exitCode ?? 0);
 })
     .catch(async (err) => {
     const errorMsg = err instanceof Error ? err.message : String(err);

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

@@ -29,6 +29,8 @@ export interface RegisterOrUpdateOptions {
     entry: ManifestEntry;
     gitRemote: string;
     integrations?: string[];
+    handlerNames?: string[];
+    apiUsages?: Record<string, unknown>;
     description?: string;
     /**
      * The base app a preview is for, sent only on first registration — the link

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;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;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BtF"}
+{"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;AAED,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,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA8DD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}

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

@@ -47,11 +47,23 @@ 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, masterAppName) {
+async function registerApp(params) {
+    const { appName, token, nextVersion: version, entry, visibility, gitRemote, integrations, handlerNames, apiUsages, description, masterAppName, } = params;
     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, masterAppName }),
+        body: JSON.stringify({
+            appName,
+            version,
+            entry,
+            visibility,
+            gitRemote,
+            integrations,
+            handlerNames,
+            apiUsages,
+            description,
+            masterAppName,
+        }),
     });
     if (!res.ok) {
         const text = await res.text();
@@ -59,11 +71,12 @@ async function registerApp(appName, token, version, entry, visibility, gitRemote
     }
 }
 /** Releases a new version onto an app that already exists. */
-async function updateApp(appName, token, version, entry, gitRemote, integrations, description) {
+async function updateApp(params) {
+    const { appName, token, nextVersion: version, entry, gitRemote, integrations, handlerNames, apiUsages, description, } = params;
     const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/update`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
-        body: JSON.stringify({ appName, version, entry, gitRemote, integrations, description }),
+        body: JSON.stringify({ appName, version, entry, gitRemote, integrations, handlerNames, apiUsages, description }),
     });
     if (!res.ok) {
         const text = await res.text();
@@ -77,16 +90,16 @@ 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, masterAppName } = opts;
+    const { appName, nextVersion } = 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, masterAppName);
+            await registerApp({ ...opts, visibility });
         }
         else {
             info(`updating "${appName}" → v${nextVersion}`);
-            await updateApp(appName, token, nextVersion, entry, gitRemote, integrations, description);
+            await updateApp(opts);
         }
     }
     catch (err) {

package/dist/index.js

@@ -186,15 +186,18 @@ async function main() {
         .action(util_runCommand.runCommand({ data: cwdApp }, (opts) => commands_delete.deleteCommand(opts)));
     const backend = program
         .command('backend')
-        .description("Inspect the app's backend: validate handler sources or invoke a deployed handler by name");
+        .description("Inspect the app's backend: validate handler sources or run a handler from the working tree");
     backend
         .command('validate')
         .description('Validate backend/handlers/*.js exactly as deploy would (syntax, isolate rules, integrations) without uploading')
         .action(util_runCommand.runCommand({ data: cwdApp }, () => commands_backend.backendValidateCommand()));
     backend
         .command('invoke <handlerName>')
-        .description('Invoke a deployed backend handler by name (the filename without .ts) — mainly for testing a handler without going through the frontend')
-        .option('--input <json>', 'JSON payload passed as ctx.input')
+        .description("Run backend/handlers/<handlerName>.js from the working tree — not the deployed handler — against the app's real " +
+        'channels (real db data, real monday calls), and print a trace of every channel call and the ' +
+        'result. Nothing is deployed. Exits 1 when the handler fails.')
+        .option('--input <json>', 'JSON passed to the handler as ctx.input (what the frontend would send)')
+        .option('--code <source>', 'run this source instead of backend/handlers/<handlerName>.js — <handlerName> is then just a label')
         .action(util_runCommand.runCommand({
         data: ([handlerName]) => ({ app_name: util_appName.getCwdAppName(), handler: handlerName }),
     }, (handlerName, opts) => commands_backend.backendInvokeCommand(handlerName, opts)));
@@ -221,7 +224,9 @@ void main()
     if (util_logger.getOutputMode() === 'human') {
         selfUpdate();
     }
-    process.exit(0);
+    // A command can finish normally and still report a non-zero code (e.g.
+    // `backend invoke` when the handler failed) via process.exitCode.
+    process.exit(process.exitCode ?? 0);
 })
     .catch(async (err) => {
     const errorMsg = err instanceof Error ? err.message : String(err);

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

@@ -29,6 +29,8 @@ export interface RegisterOrUpdateOptions {
     entry: ManifestEntry;
     gitRemote: string;
     integrations?: string[];
+    handlerNames?: string[];
+    apiUsages?: Record<string, unknown>;
     description?: string;
     /**
      * The base app a preview is for, sent only on first registration — the link

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;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;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BtF"}
+{"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;AAED,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,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA8DD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}

package/dist/util/broker/app.js

@@ -49,11 +49,23 @@ 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, masterAppName) {
+async function registerApp(params) {
+    const { appName, token, nextVersion: version, entry, visibility, gitRemote, integrations, handlerNames, apiUsages, description, masterAppName, } = params;
     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, masterAppName }),
+        body: JSON.stringify({
+            appName,
+            version,
+            entry,
+            visibility,
+            gitRemote,
+            integrations,
+            handlerNames,
+            apiUsages,
+            description,
+            masterAppName,
+        }),
     });
     if (!res.ok) {
         const text = await res.text();
@@ -61,11 +73,12 @@ async function registerApp(appName, token, version, entry, visibility, gitRemote
     }
 }
 /** Releases a new version onto an app that already exists. */
-async function updateApp(appName, token, version, entry, gitRemote, integrations, description) {
+async function updateApp(params) {
+    const { appName, token, nextVersion: version, entry, gitRemote, integrations, handlerNames, apiUsages, description, } = params;
     const res = await fetch(`${constants.brokerBaseUrl()}/z2h-cli/apps/update`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...constants.routingHeaders() },
-        body: JSON.stringify({ appName, version, entry, gitRemote, integrations, description }),
+        body: JSON.stringify({ appName, version, entry, gitRemote, integrations, handlerNames, apiUsages, description }),
     });
     if (!res.ok) {
         const text = await res.text();
@@ -79,16 +92,16 @@ 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, masterAppName } = opts;
+    const { appName, nextVersion } = 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, masterAppName);
+            await registerApp({ ...opts, visibility });
         }
         else {
             util_logger.info(`updating "${appName}" → v${nextVersion}`);
-            await updateApp(appName, token, nextVersion, entry, gitRemote, integrations, description);
+            await updateApp(opts);
         }
     }
     catch (err) {

package/handler-api/backend-runner/backend-runner.errors.ts

@@ -54,3 +54,15 @@ export class ChannelError extends BackendRunnerError {
     this.name = 'ChannelError';
   }
 }
+
+/**
+ * A sandbox run request the runner refuses before any code runs — the code is
+ * unusable or the app doesn't exist. Carries a `code` so
+ * the CLI can say exactly which, the same way a channel error does.
+ */
+export class SandboxRequestError extends BackendRunnerError {
+  constructor(statusCode: number, message: string, public readonly code: string) {
+    super(statusCode, message);
+    this.name = 'SandboxRequestError';
+  }
+}

package/handler-api/backend-runner/backend-runner.types.ts

@@ -34,6 +34,9 @@ export type ChannelHandler = (args: unknown[]) => Promise<unknown> | unknown;
  */
 export type ChannelMap = Record<string, ChannelHandler>;
 
+/** Which path built the channels — a deployed handler (`invoke`) or source sent to the sandbox. Tags channel telemetry. */
+export type RunMode = 'invoke' | 'sandbox';
+
 /**
  * A breakdown of where the isolate wall-clock went, in ms. Lets us see whether a
  * slow invoke is the V8 setup (create + compile) or the guest's own work + its

package/handler-api/backend-runner/channels/channel-map.ts

@@ -6,13 +6,19 @@ import { makeDbChannel } from './db-channel/db.channel';
 import { makeLlmChannel } from './llm-channel/llm.channel';
 import { makeMondayChannel } from './monday-channel/monday.channel';
 import { makeSnowflakeChannel } from './snowflake-channel/snowflake.channel';
-import type { Caller, ChannelMap } from '../backend-runner.types';
+import type { Caller, ChannelMap, RunMode } from '../backend-runner.types';
 import type { RunnerCustomIntegration } from '../runner-data.store';
 
 const OAUTH_CHANNELS: Record<string, (caller: Caller) => ChannelMap> = {
   monday: (caller) => makeMondayChannel(caller),
 };
 
+/**
+ * Every integration with a registered channel. Sandbox runs build all of them —
+ * safe because each fetches the caller's token only when a method is called.
+ */
+export const OAUTH_INTEGRATIONS = Object.keys(OAUTH_CHANNELS);
+
 /**
  * Builds the complete channel surface for one invocation — the only way out of
  * the isolate.
@@ -63,7 +69,7 @@ const OAUTH_CHANNELS: Record<string, (caller: Caller) => ChannelMap> = {
  * setup) is wrong and retrying won't help; `502` means the upstream failed.
  *
  * Each key emits a unified call counter, duration distribution, and BI event tagged
- * by app, channel, method, and outcome. Uncaught failures also reach BI at the
+ * by app, mode (`invoke` or `sandbox`), channel, method, and outcome. Uncaught failures also reach BI at the
  * invocation level — see `runner.service.ts`.
  */
 export function buildChannels(
@@ -71,6 +77,7 @@ export function buildChannels(
   caller: Caller,
   declaredIntegrations: string[],
   customIntegrations: RunnerCustomIntegration[],
+  mode: RunMode,
 ): ChannelMap {
   const channels: ChannelMap = {
     ...makeDbChannel(appName),
@@ -91,5 +98,7 @@ export function buildChannels(
     }
   }
 
-  return Object.fromEntries(Object.entries(channels).map(([key, fn]) => [key, withChannelTelemetry(appName, key, fn)]));
+  return Object.fromEntries(
+    Object.entries(channels).map(([key, fn]) => [key, withChannelTelemetry(appName, mode, key, fn)]),
+  );
 }

package/handler-api/backend-runner/channels/channel-telemetry.ts

@@ -4,7 +4,7 @@ import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability/trid
 
 import { ChannelError } from '../backend-runner.errors';
 import { BI_SOURCE } from '../constants';
-import type { ChannelHandler } from '../backend-runner.types';
+import type { ChannelHandler, RunMode } from '../backend-runner.types';
 
 type ChannelOutcome = 'success' | 'failure';
 
@@ -26,6 +26,7 @@ function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
 
 function recordChannelCall(
   appName: string,
+  mode: RunMode,
   channel: string,
   method: string,
   outcome: ChannelOutcome,
@@ -33,7 +34,7 @@ function recordChannelCall(
   error?: unknown,
 ): void {
   const durationMs = performance.now() - startedAt;
-  const dimensions = { appName, channel, method };
+  const dimensions = { appName, mode, channel, method };
 
   metric.increment(BackendRunnerEvents.channel.callMetric, { ...dimensions, outcome });
   metric.distribution(BackendRunnerEvents.channel.durationMetric, durationMs, dimensions);
@@ -49,7 +50,12 @@ function recordChannelCall(
   );
 }
 
-export function withChannelTelemetry(appName: string, key: string, handler: ChannelHandler): ChannelHandler {
+export function withChannelTelemetry(
+  appName: string,
+  mode: RunMode,
+  key: string,
+  handler: ChannelHandler,
+): ChannelHandler {
   const { channel, method } = parseChannelKey(key);
 
   return (args) => {
@@ -59,20 +65,20 @@ export function withChannelTelemetry(appName: string, key: string, handler: Chan
       if (isPromiseLike(result)) {
         return Promise.resolve(result).then(
           (value) => {
-            recordChannelCall(appName, channel, method, 'success', startedAt);
+            recordChannelCall(appName, mode, channel, method, 'success', startedAt);
             return value;
           },
           (error: unknown) => {
-            recordChannelCall(appName, channel, method, 'failure', startedAt, error);
+            recordChannelCall(appName, mode, channel, method, 'failure', startedAt, error);
             throw error;
           },
         );
       }
 
-      recordChannelCall(appName, channel, method, 'success', startedAt);
+      recordChannelCall(appName, mode, channel, method, 'success', startedAt);
       return result;
     } catch (error) {
-      recordChannelCall(appName, channel, method, 'failure', startedAt, error);
+      recordChannelCall(appName, mode, channel, method, 'failure', startedAt, error);
       throw error;
     }
   };

package/handler-api/backend-runner/channels/channel-trace.ts

@@ -0,0 +1,52 @@
+import { ChannelError } from '../backend-runner.errors';
+import type { ChannelHandler, ChannelMap } from '../backend-runner.types';
+
+/**
+ * One channel call as the sandbox reports it back to the author. Raw args are
+ * recorded — for `snowflake.query` that is the SQL text and its params, not the
+ * bound SQL the channel builds from them.
+ */
+export interface ChannelCallTrace {
+  method: string;
+  args: unknown[];
+  durationMs: number;
+  ok: boolean;
+  /** Why the call failed — same shape as the run's `error`. A non-`ChannelError` is a 500 with no code. */
+  error?: { status: number; code?: string; message: string };
+  /** What the channel returned to the handler, as-is — e.g. Snowflake rows or monday's GraphQL `data`. */
+  result?: unknown;
+}
+
+type CallOutcome = Pick<ChannelCallTrace, 'ok' | 'error' | 'result'>;
+
+function withChannelTrace(calls: ChannelCallTrace[], method: string, handler: ChannelHandler): ChannelHandler {
+  return async (args) => {
+    const startedAt = performance.now();
+    const record = (outcome: CallOutcome): void => {
+      calls.push({ method, args, durationMs: performance.now() - startedAt, ...outcome });
+    };
+
+    try {
+      const result = await handler(args);
+      record({ ok: true, result });
+      return result;
+    } catch (err) {
+      record({
+        ok: false,
+        error:
+          err instanceof ChannelError
+            ? { status: err.statusCode, code: err.code, message: err.message }
+            : { status: 500, message: err instanceof Error ? err.message : String(err) },
+      });
+      throw err;
+    }
+  };
+}
+
+/**
+ * Wraps every channel so each call is appended to `calls` in the order it
+ * finished. Sandbox-only: the deployed invoke path never records a trace.
+ */
+export function traceChannels(channels: ChannelMap, calls: ChannelCallTrace[]): ChannelMap {
+  return Object.fromEntries(Object.entries(channels).map(([key, fn]) => [key, withChannelTrace(calls, key, fn)]));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.33.0",
+  "version": "0.33.2",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -52,7 +52,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.706.0",
     "@mondaydotcomorg/z2h-dashboard-templates": "^0.4.0",
-    "@mondaydotcomorg/z2h-shared-utils": "^0.7.0",
+    "@mondaydotcomorg/z2h-shared-utils": "^0.7.1",
     "acorn": "^8.14.0",
     "acorn-walk": "^8.3.4",
     "chokidar": "^3.6.0",