@mondaydotcomorg/z2h-cli 0.32.2 → 0.33.1

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/__tests__/custom-integrations.test.d.ts

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

package/dist/commands/__tests__/custom-integrations.test.d.ts.map

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

package/dist/commands/backend.d.ts

@@ -23,7 +23,12 @@ export declare function deployBackend(opts: {
  * 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;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;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 };
@@ -111,7 +114,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 +147,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/custom-integrations.d.ts

@@ -0,0 +1,3 @@
+export declare function listCustomIntegrationsCommand(): Promise<void>;
+export declare function removeCustomIntegrationCommand(name: string | undefined): Promise<void>;
+//# sourceMappingURL=custom-integrations.d.ts.map

package/dist/commands/custom-integrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-integrations.d.ts","sourceRoot":"","sources":["../../src/commands/custom-integrations.ts"],"names":[],"mappings":"AAyBA,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,IAAI,CAAC,CAsBnE;AAED,wBAAsB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB5F"}

package/dist/commands/custom-integrations.js

@@ -0,0 +1,51 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const util_logger = require('../util/logger.js');
+const util_appName = require('../util/app-name.js');
+const constants = require('../constants.js');
+const util_auth_authStore = require('../util/auth/auth-store.js');
+
+function getTargetAppName() {
+    const consumerName = util_appName.getCwdAppName();
+    if (!consumerName) {
+        throw new Error('Run this from inside a consumer app directory (the one with your package.json).');
+    }
+    return util_appName.mfAppName(consumerName);
+}
+async function listCustomIntegrationsCommand() {
+    const appName = getTargetAppName();
+    const { token } = await util_auth_authStore.readZthAuth();
+    const res = await fetch(`${constants.brokerBaseUrl()}/z2h-apps/${appName}/custom-integrations`, {
+        headers: { Authorization: `Bearer ${token}`, ...constants.routingHeaders() },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Listing custom integrations failed (${res.status}): ${text.slice(0, 1024)}`);
+    }
+    const { connections } = (await res.json());
+    if (connections.length === 0) {
+        util_logger.output(`[z2h-cli] "${appName}" has no custom integrations registered`, { ok: true, appName, connections: [] });
+        return;
+    }
+    const lines = connections.map(c => `  ${c.name}  →  ${c.allowedHost}  (${c.authHeaderName})${c.inherited ? '  [inherited from base app]' : ''}`);
+    util_logger.output(`[z2h-cli] "${appName}" custom integrations:\n${lines.join('\n')}`, { ok: true, appName, connections });
+}
+async function removeCustomIntegrationCommand(name) {
+    if (!name) {
+        throw new Error('Specify the connection name to remove — e.g. z2h-cli custom-integration:remove stripe');
+    }
+    const appName = getTargetAppName();
+    const { token } = await util_auth_authStore.readZthAuth();
+    const res = await fetch(`${constants.brokerBaseUrl()}/z2h-apps/${appName}/custom-integrations/${encodeURIComponent(name)}`, {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${token}`, ...constants.routingHeaders() },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Removing custom integration failed (${res.status}): ${text.slice(0, 1024)}`);
+    }
+    util_logger.output(`[z2h-cli] custom integration "${name}" removed from "${appName}"`, { ok: true, appName, name });
+}
+
+exports.listCustomIntegrationsCommand = listCustomIntegrationsCommand;
+exports.removeCustomIntegrationCommand = removeCustomIntegrationCommand;

package/dist/commands/deploy.js

@@ -148,6 +148,9 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
         entry,
         gitRemote: '',
         isPreview: true,
+        // The base app this preview is for — bigbrain-zth links the preview's row
+        // to it (once the caller's EDITOR access on it is confirmed) so custom
+        // integrations set on the base app are inherited by the preview.
         masterAppName: appName,
     });
     const previewUrl = `https://bigbrain.me/bigbrain-vibe/${previewSlug}`;

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/__tests__/custom-integrations.test.d.ts

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

package/dist/esm/commands/__tests__/custom-integrations.test.d.ts.map

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

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

@@ -23,7 +23,12 @@ export declare function deployBackend(opts: {
  * 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;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;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/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() {
@@ -105,7 +108,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 +141,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/custom-integrations.d.ts

@@ -0,0 +1,3 @@
+export declare function listCustomIntegrationsCommand(): Promise<void>;
+export declare function removeCustomIntegrationCommand(name: string | undefined): Promise<void>;
+//# sourceMappingURL=custom-integrations.d.ts.map

package/dist/esm/commands/custom-integrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-integrations.d.ts","sourceRoot":"","sources":["../../../src/commands/custom-integrations.ts"],"names":[],"mappings":"AAyBA,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,IAAI,CAAC,CAsBnE;AAED,wBAAsB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB5F"}

package/dist/esm/commands/custom-integrations.mjs

@@ -0,0 +1,48 @@
+import { output } from '../util/logger.mjs';
+import { getCwdAppName, mfAppName } from '../util/app-name.mjs';
+import { brokerBaseUrl, routingHeaders } from '../constants.mjs';
+import { readZthAuth } from '../util/auth/auth-store.mjs';
+
+function getTargetAppName() {
+    const consumerName = getCwdAppName();
+    if (!consumerName) {
+        throw new Error('Run this from inside a consumer app directory (the one with your package.json).');
+    }
+    return mfAppName(consumerName);
+}
+async function listCustomIntegrationsCommand() {
+    const appName = getTargetAppName();
+    const { token } = await readZthAuth();
+    const res = await fetch(`${brokerBaseUrl()}/z2h-apps/${appName}/custom-integrations`, {
+        headers: { Authorization: `Bearer ${token}`, ...routingHeaders() },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Listing custom integrations failed (${res.status}): ${text.slice(0, 1024)}`);
+    }
+    const { connections } = (await res.json());
+    if (connections.length === 0) {
+        output(`[z2h-cli] "${appName}" has no custom integrations registered`, { ok: true, appName, connections: [] });
+        return;
+    }
+    const lines = connections.map(c => `  ${c.name}  →  ${c.allowedHost}  (${c.authHeaderName})${c.inherited ? '  [inherited from base app]' : ''}`);
+    output(`[z2h-cli] "${appName}" custom integrations:\n${lines.join('\n')}`, { ok: true, appName, connections });
+}
+async function removeCustomIntegrationCommand(name) {
+    if (!name) {
+        throw new Error('Specify the connection name to remove — e.g. z2h-cli custom-integration:remove stripe');
+    }
+    const appName = getTargetAppName();
+    const { token } = await readZthAuth();
+    const res = await fetch(`${brokerBaseUrl()}/z2h-apps/${appName}/custom-integrations/${encodeURIComponent(name)}`, {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${token}`, ...routingHeaders() },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Removing custom integration failed (${res.status}): ${text.slice(0, 1024)}`);
+    }
+    output(`[z2h-cli] custom integration "${name}" removed from "${appName}"`, { ok: true, appName, name });
+}
+
+export { listCustomIntegrationsCommand, removeCustomIntegrationCommand };