@mondaydotcomorg/z2h-cli 0.33.0 → 0.33.2

package/dist/backend/__tests__/format-sandbox-run.test.d.ts

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

package/dist/backend/__tests__/format-sandbox-run.test.d.ts.map

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

package/dist/backend/client.d.ts

@@ -1,10 +1,40 @@
 /** `Z2H_BACKEND_URL` overrides for staging or a locally-run runner. */
 export declare function backendBaseUrl(): string;
-export interface InvokeResponse {
+export interface SandboxRunRequest {
+    code: string;
+    input: unknown;
+    handlerName?: string;
+}
+/** One channel call the handler made, as the runner traced it. */
+export interface SandboxCall {
+    method: string;
+    args: unknown[];
+    durationMs: number;
+    ok: boolean;
+    error?: {
+        status: number;
+        code?: string;
+        message: string;
+    };
+    result?: unknown;
+}
+export interface SandboxRunResponse {
+    ok: boolean;
+    error?: {
+        status: number;
+        code?: string;
+        message: string;
+    };
+    calls: SandboxCall[];
     result: unknown;
     durationMs: number;
 }
-export declare function invokeBackend(appName: string, handlerName: string, input: unknown): Promise<InvokeResponse>;
+/**
+ * Runs handler source from the working tree on the runner's sandbox route —
+ * against the app's real channels, without deploying it. A handler failure
+ * comes back as `ok: false` with the trace; only a refused request throws.
+ */
+export declare function runSandbox(appName: string, body: SandboxRunRequest): Promise<SandboxRunResponse>;
 export interface AppIntegrationsResponse {
     integrations: string[];
 }

package/dist/backend/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/backend/client.ts"],"names":[],"mappings":"AAWA,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AA+CD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAS3G;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAErF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/backend/client.ts"],"names":[],"mappings":"AAWA,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AA+CD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAEhG;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAErF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrF"}

package/dist/backend/client.js

@@ -56,10 +56,13 @@ async function request(method, baseUrl, path, body) {
     }
     return (parsed ?? {});
 }
-function invokeBackend(appName, handlerName, input) {
-    // The runner resolves the caller from the request or 401s, so an anonymous
-    // invoke can never reach a handler.
-    return request('POST', backendBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/invoke/${encodeURIComponent(handlerName)}`, { input });
+/**
+ * Runs handler source from the working tree on the runner's sandbox route —
+ * against the app's real channels, without deploying it. A handler failure
+ * comes back as `ok: false` with the trace; only a refused request throws.
+ */
+function runSandbox(appName, body) {
+    return request('POST', backendBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/sandbox/run`, body);
 }
 function listAppIntegrations(appName) {
     return request('GET', constants.brokerBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/integrations`);
@@ -73,6 +76,6 @@ function removeIntegration(appName, integration) {
 
 exports.backendBaseUrl = backendBaseUrl;
 exports.declareIntegration = declareIntegration;
-exports.invokeBackend = invokeBackend;
 exports.listAppIntegrations = listAppIntegrations;
 exports.removeIntegration = removeIntegration;
+exports.runSandbox = runSandbox;

package/dist/backend/format-sandbox-run.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxRunResponse } from './client';
+/** Human-readable trace of a sandbox run; `--json` prints the raw response instead. */
+export declare function formatSandboxRun(res: SandboxRunResponse): string;
+//# sourceMappingURL=format-sandbox-run.d.ts.map

package/dist/backend/format-sandbox-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-sandbox-run.d.ts","sourceRoot":"","sources":["../../src/backend/format-sandbox-run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAmChE,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAchE"}

package/dist/backend/format-sandbox-run.js

@@ -0,0 +1,49 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const MAX_SQL_CHARS = 400;
+const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+const oneLine = (text) => text.replace(/\s+/g, ' ').trim();
+const clip = (text, max) => (text.length > max ? `${text.slice(0, max)}…` : text);
+/** The first arg is the SQL / GraphQL text for query channels — shown on its own line so it can be read. */
+function describeArgs(args) {
+    const [first, ...rest] = args;
+    const lines = [];
+    if (typeof first === 'string') {
+        lines.push(clip(oneLine(first), MAX_SQL_CHARS));
+    }
+    else if (first !== undefined) {
+        lines.push(clip(JSON.stringify(first), MAX_SQL_CHARS));
+    }
+    const params = rest.filter(arg => arg !== undefined && arg !== null);
+    if (params.length > 0) {
+        lines.push(`params: ${clip(params.map(p => JSON.stringify(p)).join(', '), MAX_SQL_CHARS)}`);
+    }
+    return lines;
+}
+function describeCall(call) {
+    const rows = Array.isArray(call.result) ? `  ${call.result.length} rows` : '';
+    const head = `  ${call.ok ? '✓' : '✗'} ${call.method}  ${Math.round(call.durationMs)}ms${rows}`;
+    const detail = describeArgs(call.args);
+    if (call.error) {
+        const code = call.error.code ? ` ${call.error.code}` : '';
+        detail.push(`${call.error.status}${code}: ${call.error.message}`);
+    }
+    return [head, ...detail.map(line => `      ${line}`)];
+}
+/** Human-readable trace of a sandbox run; `--json` prints the raw response instead. */
+function formatSandboxRun(res) {
+    const lines = [`[z2h-cli] sandbox run ${res.ok ? '✓' : '✗'} ${seconds(res.durationMs)}`, ''];
+    lines.push(res.calls.length > 0 ? 'calls:' : 'calls: none');
+    res.calls.forEach(call => lines.push(...describeCall(call)));
+    lines.push('');
+    if (res.ok) {
+        lines.push('result:', JSON.stringify(res.result, null, 2));
+    }
+    else if (res.error) {
+        const code = res.error.code ? ` ${res.error.code}` : '';
+        lines.push(`error: ${res.error.status}${code} — ${res.error.message}`);
+    }
+    return lines.join('\n');
+}
+
+exports.formatSandboxRun = formatSandboxRun;

package/dist/commands/__tests__/backend-invoke.test.d.ts

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

package/dist/commands/__tests__/backend-invoke.test.d.ts.map

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

package/dist/commands/backend.d.ts

@@ -1,9 +1,10 @@
 export declare function hasHandlers(appDir: string): boolean;
+export interface ReadDetectAndUploadResult {
+    integrations: string[];
+    handlerNames: string[];
+    apiUsages: Record<string, unknown>;
+}
 /**
- * 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
@@ -17,13 +18,18 @@ export declare function deployBackend(opts: {
     version: number;
     deployedBy: string;
     isPreview: boolean;
-}): Promise<string[]>;
+}): Promise<ReadDetectAndUploadResult>;
 /**
  * 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>;
+/**
+ * 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.
+ */
 export declare function backendInvokeCommand(handlerName: string, opts?: {
     input?: string;
-}): Promise<void>;
+    code?: string;
+}, appDir?: string): Promise<void>;
 //# sourceMappingURL=backend.d.ts.map

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/commands/backend.ts"],"names":[],"mappings":"AAyBA,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAoBD,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAiCD;;;;;;GAMG;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,yBAAyB,CAAC,CASrC;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe1F;AAsBD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,EAC5C,MAAM,GAAE,MAAsB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/commands/backend.js

@@ -2,6 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const path = require('node:path');
 const fs = require('node:fs');
+const promises = require('node:fs/promises');
 const fs$1 = require('fs-extra');
 const clientS3 = require('@aws-sdk/client-s3');
 const util_logger = require('../util/logger.js');
@@ -12,6 +13,8 @@ const backend_detectIntegrations = require('../backend/detect-integrations.js');
 const util_s3_client = require('../util/s3/client.js');
 const constants = require('../constants.js');
 const backend_client = require('../backend/client.js');
+const backend_formatSandboxRun = require('../backend/format-sandbox-run.js');
+const backend_validate = require('../backend/validate.js');
 const util_errors = require('../util/errors.js');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
@@ -45,21 +48,19 @@ 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 });
 }
-/**
- * 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: {} };
     }
     util_logger.info(`reading backend handlers ${logLabel}`);
     const { handlers, apiDomains, apiUsages } = await backend_handlers.readHandlers(appDir);
     const integrations = backend_detectIntegrations.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 = 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 }));
@@ -67,13 +68,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
@@ -111,7 +108,29 @@ async function backendValidateCommand(appDir = process.cwd()) {
         integrations,
     });
 }
-async function backendInvokeCommand(handlerName, opts = {}) {
+async function readHandlerSource(appDir, handlerName) {
+    const dir = path__default.default.join(appDir, 'backend', 'handlers');
+    try {
+        return await promises.readFile(path__default.default.join(dir, `${handlerName}.js`), 'utf8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+        const files = hasHandlers(appDir) ? await promises.readdir(dir) : [];
+        const available = files
+            .filter(f => f.endsWith('.js'))
+            .map(f => path__default.default.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) {
@@ -122,8 +141,15 @@ async function backendInvokeCommand(handlerName, opts = {}) {
             throw new Error(`--input must be valid JSON (got: ${opts.input})`);
         }
     }
-    const res = await backend_client.invokeBackend(appName, handlerName, input);
-    util_logger.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));
+    backend_validate.validateHandlerSource(file, code);
+    util_logger.info(`validated ${opts.code ? '--code' : file}`);
+    const res = await backend_client.runSandbox(appName, { code, input, handlerName });
+    util_logger.output(backend_formatSandboxRun.formatSandboxRun(res), res);
+    if (!res.ok) {
+        process.exitCode = 1;
+    }
 }
 
 exports.backendInvokeCommand = backendInvokeCommand;

package/dist/commands/deploy.js

@@ -85,12 +85,9 @@ async function buildAndStamp(opts) {
  */
 async function uploadAndRegister(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
-    // reconciled to exactly match on register — see `deployBackend` for why this
-    // depends on deploying from the app's latest merged state.
-    const integrations = await commands_backend.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 commands_backend.deployBackend({
         appDir: process.cwd(),
         appName,
         mfKeyPrefix: keyPrefix,
@@ -98,16 +95,32 @@ async function uploadAndRegister(opts) {
         deployedBy: util_machineIdentity.whoAmI(),
         isPreview,
     });
-    await util_broker_app.registerOrUpdateApp({
-        appName,
-        token,
-        nextVersion,
-        entry,
-        gitRemote,
-        integrations,
-        description,
-        masterAppName,
-    });
+    try {
+        util_logger.info(`uploading ${isPreview ? 'preview ' : ''}build → s3://${constants.BUCKET_WRITE_NAME}/${keyPrefix}/`);
+        await util_s3_upload.uploadDir(paths.shadowBuild, keyPrefix);
+        await util_broker_app.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) {
+            util_logger.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/backend/__tests__/format-sandbox-run.test.d.ts

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

package/dist/esm/backend/__tests__/format-sandbox-run.test.d.ts.map

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

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

@@ -1,10 +1,40 @@
 /** `Z2H_BACKEND_URL` overrides for staging or a locally-run runner. */
 export declare function backendBaseUrl(): string;
-export interface InvokeResponse {
+export interface SandboxRunRequest {
+    code: string;
+    input: unknown;
+    handlerName?: string;
+}
+/** One channel call the handler made, as the runner traced it. */
+export interface SandboxCall {
+    method: string;
+    args: unknown[];
+    durationMs: number;
+    ok: boolean;
+    error?: {
+        status: number;
+        code?: string;
+        message: string;
+    };
+    result?: unknown;
+}
+export interface SandboxRunResponse {
+    ok: boolean;
+    error?: {
+        status: number;
+        code?: string;
+        message: string;
+    };
+    calls: SandboxCall[];
     result: unknown;
     durationMs: number;
 }
-export declare function invokeBackend(appName: string, handlerName: string, input: unknown): Promise<InvokeResponse>;
+/**
+ * Runs handler source from the working tree on the runner's sandbox route —
+ * against the app's real channels, without deploying it. A handler failure
+ * comes back as `ok: false` with the trace; only a refused request throws.
+ */
+export declare function runSandbox(appName: string, body: SandboxRunRequest): Promise<SandboxRunResponse>;
 export interface AppIntegrationsResponse {
     integrations: string[];
 }

package/dist/esm/backend/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/backend/client.ts"],"names":[],"mappings":"AAWA,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AA+CD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAS3G;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAErF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/backend/client.ts"],"names":[],"mappings":"AAWA,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AA+CD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAEhG;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAErF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrF"}

package/dist/esm/backend/client.mjs

@@ -54,10 +54,13 @@ async function request(method, baseUrl, path, body) {
     }
     return (parsed ?? {});
 }
-function invokeBackend(appName, handlerName, input) {
-    // The runner resolves the caller from the request or 401s, so an anonymous
-    // invoke can never reach a handler.
-    return request('POST', backendBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/invoke/${encodeURIComponent(handlerName)}`, { input });
+/**
+ * Runs handler source from the working tree on the runner's sandbox route —
+ * against the app's real channels, without deploying it. A handler failure
+ * comes back as `ok: false` with the trace; only a refused request throws.
+ */
+function runSandbox(appName, body) {
+    return request('POST', backendBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/sandbox/run`, body);
 }
 function listAppIntegrations(appName) {
     return request('GET', brokerBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/integrations`);
@@ -69,4 +72,4 @@ function removeIntegration(appName, integration) {
     return request('DELETE', brokerBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/integrations/${encodeURIComponent(integration)}`);
 }
 
-export { backendBaseUrl, declareIntegration, invokeBackend, listAppIntegrations, removeIntegration };
+export { backendBaseUrl, declareIntegration, listAppIntegrations, removeIntegration, runSandbox };

package/dist/esm/backend/format-sandbox-run.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxRunResponse } from './client';
+/** Human-readable trace of a sandbox run; `--json` prints the raw response instead. */
+export declare function formatSandboxRun(res: SandboxRunResponse): string;
+//# sourceMappingURL=format-sandbox-run.d.ts.map

package/dist/esm/backend/format-sandbox-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-sandbox-run.d.ts","sourceRoot":"","sources":["../../../src/backend/format-sandbox-run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAmChE,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAchE"}

package/dist/esm/backend/format-sandbox-run.mjs

@@ -0,0 +1,47 @@
+const MAX_SQL_CHARS = 400;
+const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+const oneLine = (text) => text.replace(/\s+/g, ' ').trim();
+const clip = (text, max) => (text.length > max ? `${text.slice(0, max)}…` : text);
+/** The first arg is the SQL / GraphQL text for query channels — shown on its own line so it can be read. */
+function describeArgs(args) {
+    const [first, ...rest] = args;
+    const lines = [];
+    if (typeof first === 'string') {
+        lines.push(clip(oneLine(first), MAX_SQL_CHARS));
+    }
+    else if (first !== undefined) {
+        lines.push(clip(JSON.stringify(first), MAX_SQL_CHARS));
+    }
+    const params = rest.filter(arg => arg !== undefined && arg !== null);
+    if (params.length > 0) {
+        lines.push(`params: ${clip(params.map(p => JSON.stringify(p)).join(', '), MAX_SQL_CHARS)}`);
+    }
+    return lines;
+}
+function describeCall(call) {
+    const rows = Array.isArray(call.result) ? `  ${call.result.length} rows` : '';
+    const head = `  ${call.ok ? '✓' : '✗'} ${call.method}  ${Math.round(call.durationMs)}ms${rows}`;
+    const detail = describeArgs(call.args);
+    if (call.error) {
+        const code = call.error.code ? ` ${call.error.code}` : '';
+        detail.push(`${call.error.status}${code}: ${call.error.message}`);
+    }
+    return [head, ...detail.map(line => `      ${line}`)];
+}
+/** Human-readable trace of a sandbox run; `--json` prints the raw response instead. */
+function formatSandboxRun(res) {
+    const lines = [`[z2h-cli] sandbox run ${res.ok ? '✓' : '✗'} ${seconds(res.durationMs)}`, ''];
+    lines.push(res.calls.length > 0 ? 'calls:' : 'calls: none');
+    res.calls.forEach(call => lines.push(...describeCall(call)));
+    lines.push('');
+    if (res.ok) {
+        lines.push('result:', JSON.stringify(res.result, null, 2));
+    }
+    else if (res.error) {
+        const code = res.error.code ? ` ${res.error.code}` : '';
+        lines.push(`error: ${res.error.status}${code} — ${res.error.message}`);
+    }
+    return lines.join('\n');
+}
+
+export { formatSandboxRun };

package/dist/esm/commands/__tests__/backend-invoke.test.d.ts

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

package/dist/esm/commands/__tests__/backend-invoke.test.d.ts.map

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

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

@@ -1,9 +1,10 @@
 export declare function hasHandlers(appDir: string): boolean;
+export interface ReadDetectAndUploadResult {
+    integrations: string[];
+    handlerNames: string[];
+    apiUsages: Record<string, unknown>;
+}
 /**
- * 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
@@ -17,13 +18,18 @@ export declare function deployBackend(opts: {
     version: number;
     deployedBy: string;
     isPreview: boolean;
-}): Promise<string[]>;
+}): Promise<ReadDetectAndUploadResult>;
 /**
  * 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>;
+/**
+ * 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.
+ */
 export declare function backendInvokeCommand(handlerName: string, opts?: {
     input?: string;
-}): Promise<void>;
+    code?: string;
+}, appDir?: string): Promise<void>;
 //# sourceMappingURL=backend.d.ts.map

package/dist/esm/commands/backend.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/commands/backend.ts"],"names":[],"mappings":"AAyBA,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAoBD,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAiCD;;;;;;GAMG;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,yBAAyB,CAAC,CASrC;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe1F;AAsBD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,EAC5C,MAAM,GAAE,MAAsB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAqBf"}