@mondaydotcomorg/z2h-cli 0.32.2 → 0.33.1

package/handler-api/signatures.json

@@ -1,4 +1,8 @@
 {
+  "customIntegration.request": [
+    "name",
+    "options"
+  ],
   "db.delete": [
     "key"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.32.2",
+  "version": "0.33.1",
   "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.6.2",
+    "@mondaydotcomorg/z2h-shared-utils": "^0.7.1",
     "acorn": "^8.14.0",
     "acorn-walk": "^8.3.4",
     "chokidar": "^3.6.0",

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

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from 'vitest';
 
-import { backendBaseUrl, declareIntegration, invokeBackend, listAppIntegrations, removeIntegration } from '../client';
+import { backendBaseUrl, declareIntegration, listAppIntegrations, removeIntegration, runSandbox } from '../client';
 
 vi.mock('../../util/auth/auth-store', () => ({
   readZthAuth: vi.fn().mockResolvedValue({ token: 'jwt-token' }),
@@ -21,6 +21,8 @@ const respond = (init: { ok?: boolean; status?: number; statusText?: string; bod
 
 const lastCall = () => (fetch as Mock).mock.calls[0];
 
+const SANDBOX_BODY = { code: 'function handler() {}', input: null };
+
 beforeEach(() => {
   vi.stubGlobal('fetch', respond({ body: '{"result":1,"durationMs":5}' }));
 });
@@ -42,13 +44,15 @@ describe('backendBaseUrl', () => {
 });
 
 describe('where each call goes', () => {
-  it('sends an invoke to the runner, authenticated', async () => {
-    await invokeBackend('mf-reports', 'get_items', { n: 1 });
+  it('sends a sandbox run to the runner, authenticated, with the code in the body', async () => {
+    const body = { code: 'function handler() {}', input: { n: 1 }, handlerName: 'get_items' };
+    await runSandbox('mf-reports', body);
 
     const [url, opts] = lastCall();
-    expect(url).toBe('https://zth-backend-runner.bigbrain.me/z2h-apps/mf-reports/invoke/get_items');
+    expect(url).toBe('https://zth-backend-runner.bigbrain.me/z2h-apps/mf-reports/sandbox/run');
+    expect(opts.method).toBe('POST');
     expect(opts.headers).toMatchObject({ Authorization: 'Bearer jwt-token', 'x-route': 'prod' });
-    expect(JSON.parse(opts.body)).toEqual({ input: { n: 1 } });
+    expect(JSON.parse(opts.body)).toEqual(body);
   });
 
   // Integrations live in the platform's registry, which the broker owns — not the runner.
@@ -72,9 +76,9 @@ describe('where each call goes', () => {
   });
 
   it('escapes an app name rather than letting it alter the path', async () => {
-    await invokeBackend('mf-a/../b', 'get_items', null);
+    await runSandbox('mf-a/../b', SANDBOX_BODY);
 
-    expect(lastCall()[0]).toContain('/z2h-apps/mf-a%2F..%2Fb/invoke/get_items');
+    expect(lastCall()[0]).toContain('/z2h-apps/mf-a%2F..%2Fb/sandbox/run');
   });
 });
 
@@ -85,27 +89,27 @@ describe('where each call goes', () => {
  */
 describe('what the author is told when it fails', () => {
   it('uses the server’s own message when there is one', async () => {
-    vi.stubGlobal('fetch', respond({ ok: false, status: 404, body: '{"message":"No backend deployed for \\"x\\""}' }));
+    vi.stubGlobal('fetch', respond({ ok: false, status: 404, body: '{"message":"app \\"x\\" is not registered"}' }));
 
-    await expect(invokeBackend('mf-x', 'get_items', null)).rejects.toThrow('No backend deployed for "x"');
+    await expect(runSandbox('mf-x', SANDBOX_BODY)).rejects.toThrow('app "x" is not registered');
   });
 
   it('falls back to the status plus a snippet when the body is HTML', async () => {
     vi.stubGlobal('fetch', respond({ ok: false, status: 502, statusText: 'Bad Gateway', body: '<html>nginx</html>' }));
 
-    await expect(invokeBackend('mf-x', 'get_items', null)).rejects.toThrow(/502 Bad Gateway.*nginx/s);
+    await expect(runSandbox('mf-x', SANDBOX_BODY)).rejects.toThrow(/502 Bad Gateway.*nginx/s);
   });
 
   it('collapses whitespace in that snippet so the message stays one line', async () => {
     vi.stubGlobal('fetch', respond({ ok: false, status: 500, body: '<html>\n  a\n\n  b\n</html>' }));
 
-    await expect(invokeBackend('mf-x', 'get_items', null)).rejects.toThrow(/<html> a b <\/html>/);
+    await expect(runSandbox('mf-x', SANDBOX_BODY)).rejects.toThrow(/<html> a b <\/html>/);
   });
 
   it('names the URL it could not reach when the request never lands', async () => {
     vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
 
-    await expect(invokeBackend('mf-x', 'get_items', null)).rejects.toThrow(
+    await expect(runSandbox('mf-x', SANDBOX_BODY)).rejects.toThrow(
       /cannot reach https:\/\/zth-backend-runner.*ECONNREFUSED/
     );
   });
@@ -113,7 +117,7 @@ describe('what the author is told when it fails', () => {
   it('reports a 200 whose body is not JSON rather than returning nothing', async () => {
     vi.stubGlobal('fetch', respond({ body: '<html>login</html>' }));
 
-    await expect(invokeBackend('mf-x', 'get_items', null)).rejects.toThrow(/non-JSON response/);
+    await expect(runSandbox('mf-x', SANDBOX_BODY)).rejects.toThrow(/non-JSON response/);
   });
 
   // DELETE returns 204 with no body, which is success, not a parse failure.

package/src/backend/__tests__/format-sandbox-run.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatSandboxRun } from '../format-sandbox-run';
+
+describe('formatSandboxRun', () => {
+  it('shows each call with its SQL on one line, params, and row count, then the result', () => {
+    const text = formatSandboxRun({
+      ok: true,
+      calls: [
+        {
+          method: 'snowflake.query',
+          args: ['SELECT region\n   FROM accounts\n  WHERE d >= :since', { since: '2026-01-01' }],
+          durationMs: 812.4,
+          ok: true,
+          result: [{ r: 1 }, { r: 2 }, { r: 3 }, { r: 4 }],
+        },
+      ],
+      result: { regions: [] },
+      durationMs: 1200,
+    });
+
+    expect(text).toContain('sandbox run ✓ 1.2s');
+    expect(text).toContain('✓ snowflake.query  812ms  4 rows');
+    expect(text).toContain('SELECT region FROM accounts WHERE d >= :since');
+    expect(text).toContain('params: {"since":"2026-01-01"}');
+    expect(text).toContain('result:\n{\n  "regions": []\n}');
+  });
+
+  it('ends with the error instead of a result on failure', () => {
+    const text = formatSandboxRun({
+      ok: false,
+      error: { status: 504, code: 'isolate_timeout', message: 'Script execution timed out.' },
+      calls: [],
+      result: null,
+      durationMs: 5000,
+    });
+
+    expect(text).toContain('sandbox run ✗ 5.0s');
+    expect(text).toContain('error: 504 isolate_timeout — Script execution timed out.');
+    expect(text).not.toContain('result:');
+  });
+});

package/src/backend/client.ts

@@ -59,20 +59,37 @@ async function request<T>(method: string, baseUrl: string, path: string, body?:
   return (parsed ?? ({} as T)) as T;
 }
 
-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 function invokeBackend(appName: string, handlerName: string, input: unknown): Promise<InvokeResponse> {
-  // 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.
+ */
+export function runSandbox(appName: string, body: SandboxRunRequest): Promise<SandboxRunResponse> {
+  return request('POST', backendBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/sandbox/run`, body);
 }
 
 export interface AppIntegrationsResponse {

package/src/backend/format-sandbox-run.ts

@@ -0,0 +1,51 @@
+import type { SandboxCall, SandboxRunResponse } from './client';
+
+const MAX_SQL_CHARS = 400;
+
+const seconds = (ms: number): string => `${(ms / 1000).toFixed(1)}s`;
+const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim();
+const clip = (text: string, max: number): string => (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: unknown[]): string[] {
+  const [first, ...rest] = args;
+  const lines: string[] = [];
+  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: SandboxCall): string[] {
+  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. */
+export function formatSandboxRun(res: SandboxRunResponse): string {
+  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');
+}

package/src/commands/__tests__/backend-invoke.test.ts

@@ -0,0 +1,125 @@
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm, ensureDir, writeFile } from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { backendInvokeCommand } from '../backend';
+import { runSandbox } from '../../backend/client';
+import { output } from '../../util/logger';
+
+vi.mock('../../util/logger', () => ({
+  info: vi.fn(),
+  warn: vi.fn(),
+  output: vi.fn(),
+}));
+vi.mock('../../util/tracker', () => ({
+  trackEvent: vi.fn().mockResolvedValue(undefined),
+  trackDuration: vi.fn(),
+}));
+vi.mock('../../util/s3/client', () => ({ getS3Client: vi.fn() }));
+vi.mock('../../backend/client', () => ({ runSandbox: vi.fn() }));
+vi.mock('../../util/app-name', async importOriginal => ({
+  ...(await importOriginal<typeof import('../../util/app-name')>()),
+  getCwdAppName: () => 'sales-kpis',
+}));
+
+const runSandboxMock = vi.mocked(runSandbox);
+const outputMock = vi.mocked(output);
+
+const OK = { ok: true, calls: [], result: { n: 1 }, durationMs: 12 };
+
+describe('backendInvokeCommand', () => {
+  let tmp: string;
+
+  const writeHandler = async (name: string, source: string) => {
+    const dir = path.join(tmp, 'backend', 'handlers');
+    await ensureDir(dir);
+    await writeFile(path.join(dir, `${name}.js`), source);
+  };
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-backend-invoke-'));
+    runSandboxMock.mockReset();
+    runSandboxMock.mockResolvedValue(OK);
+    outputMock.mockClear();
+    process.exitCode = undefined;
+  });
+
+  afterEach(async () => {
+    process.exitCode = undefined;
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('sends the handler file from the working tree', async () => {
+    const source = 'async function handler(ctx) { return ctx.api.v1.monday.query("query { me { id } }"); }';
+    await writeHandler('get_kpis', source);
+
+    await backendInvokeCommand('get_kpis', { input: '{"since":"2026-01-01"}' }, tmp);
+
+    expect(runSandboxMock).toHaveBeenCalledWith('mf-sales-kpis', {
+      code: source,
+      input: { since: '2026-01-01' },
+      handlerName: 'get_kpis',
+    });
+    expect(outputMock).toHaveBeenCalledWith(expect.stringContaining('sandbox run ✓'), OK);
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('runs --code instead of the file', async () => {
+    await backendInvokeCommand('scratch', { code: 'function handler() { return 1; }' }, tmp);
+
+    expect(runSandboxMock.mock.calls[0][1]).toMatchObject({ code: 'function handler() { return 1; }', input: null });
+  });
+
+  it('fails locally, without a request, when the source breaks an isolate rule', async () => {
+    await writeHandler('get_kpis', "import x from 'y';\nfunction handler() {}");
+
+    await expect(backendInvokeCommand('get_kpis', {}, tmp)).rejects.toThrow();
+    expect(runSandboxMock).not.toHaveBeenCalled();
+  });
+
+  it('names the available handlers when the one asked for does not exist', async () => {
+    await writeHandler('get_kpis', 'function handler() {}');
+    await writeHandler('list_items', 'function handler() {}');
+
+    await expect(backendInvokeCommand('get_kpi', {}, tmp)).rejects.toThrow(
+      'no handler "get_kpi" in backend/handlers/ (available: get_kpis, list_items)'
+    );
+  });
+
+  it('rejects --input that is not JSON', async () => {
+    await expect(backendInvokeCommand('get_kpis', { input: '{bad' }, tmp)).rejects.toThrow(
+      /--input must be valid JSON/
+    );
+  });
+
+  it('prints the trace and exits 1 when the handler fails', async () => {
+    await writeHandler('get_kpis', 'async function handler(ctx) { return ctx.api.v1.snowflake.query("SELECT ar"); }');
+    const failed = {
+      ok: false,
+      error: { status: 400, code: 'snowflake_query_error', message: "invalid identifier 'AR'" },
+      calls: [
+        {
+          method: 'snowflake.query',
+          args: ['SELECT ar'],
+          durationMs: 640,
+          ok: false,
+          error: { status: 400, code: 'snowflake_query_error', message: "invalid identifier 'AR'" },
+        },
+      ],
+      result: null,
+      durationMs: 900,
+    };
+    runSandboxMock.mockResolvedValue(failed);
+
+    await backendInvokeCommand('get_kpis', {}, tmp);
+
+    const [human, data] = outputMock.mock.calls[0];
+    expect(data).toBe(failed);
+    expect(human).toContain('✗ snowflake.query  640ms');
+    expect(human).toContain('SELECT ar');
+    expect(human).toContain("400 snowflake_query_error: invalid identifier 'AR'");
+    expect(human).toContain("error: 400 snowflake_query_error — invalid identifier 'AR'");
+    expect(process.exitCode).toBe(1);
+  });
+});

package/src/commands/__tests__/custom-integrations.test.ts

@@ -0,0 +1,62 @@
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm, remove, ensureDir, writeJson } from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { listCustomIntegrationsCommand, removeCustomIntegrationCommand } from '../custom-integrations';
+import * as authStore from '../../util/auth/auth-store';
+
+vi.spyOn(authStore, 'readZthAuth').mockResolvedValue({ token: 'jwt-stub' });
+
+function mockFetchOnce(status = 200, body: unknown = {}) {
+  const fetchMock = vi
+    .fn()
+    .mockResolvedValue({ ok: status < 400, status, text: async () => '', json: async () => body });
+  vi.stubGlobal('fetch', fetchMock);
+  return fetchMock;
+}
+
+describe('custom-integration commands — app-name resolution', () => {
+  let tmp: string;
+  let cwd: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-custom-integration-'));
+    cwd = process.cwd();
+    process.chdir(tmp);
+    tmp = process.cwd();
+    await writeJson(path.join(tmp, 'package.json'), { name: 'my-app' });
+  });
+
+  afterEach(async () => {
+    process.chdir(cwd);
+    vi.unstubAllGlobals();
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('throws a clear error instead of crashing when run outside a consumer app directory', async () => {
+    await remove(path.join(tmp, 'package.json'));
+
+    await expect(listCustomIntegrationsCommand()).rejects.toThrow(/consumer app directory/);
+    await expect(removeCustomIntegrationCommand('stripe')).rejects.toThrow(/consumer app directory/);
+  });
+
+  it('targets the base app', async () => {
+    const fetchMock = mockFetchOnce(200, { connections: [] });
+
+    await listCustomIntegrationsCommand();
+
+    const [url] = fetchMock.mock.calls[0] as [string];
+    expect(url).toContain('/z2h-apps/mf-my-app/custom-integrations');
+  });
+
+  it('remove targets the base app', async () => {
+    await ensureDir(path.join(tmp, '.zth'));
+    const fetchMock = mockFetchOnce(204);
+
+    await removeCustomIntegrationCommand('stripe');
+
+    const [url] = fetchMock.mock.calls[0] as [string];
+    expect(url).toContain('/z2h-apps/mf-my-app/custom-integrations/stripe');
+  });
+});

package/src/commands/backend.ts

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
 import { readJson, writeJson } from 'fs-extra';
 import { PutObjectCommand } from '@aws-sdk/client-s3';
 import { info, output } from '../util/logger';
@@ -9,7 +10,9 @@ import { readHandlers } from '../backend/handlers';
 import { detectIntegrations } from '../backend/detect-integrations';
 import { getS3Client } from '../util/s3/client';
 import { BUCKET_WRITE_NAME } from '../constants';
-import { invokeBackend } from '../backend/client';
+import { runSandbox } from '../backend/client';
+import { formatSandboxRun } from '../backend/format-sandbox-run';
+import { validateHandlerSource } from '../backend/validate';
 import { tagDeployError } from '../util/errors';
 
 function currentAppName(): string {
@@ -125,7 +128,35 @@ export async function backendValidateCommand(appDir: string = process.cwd()): Pr
   });
 }
 
-export async function backendInvokeCommand(handlerName: string, opts: { input?: string } = {}): Promise<void> {
+async function readHandlerSource(appDir: string, handlerName: string): Promise<string> {
+  const dir = path.join(appDir, 'backend', 'handlers');
+  try {
+    return await readFile(path.join(dir, `${handlerName}.js`), 'utf8');
+  } catch (err) {
+    if ((err as { code?: string }).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.
+ */
+export async function backendInvokeCommand(
+  handlerName: string,
+  opts: { input?: string; code?: string } = {},
+  appDir: string = process.cwd()
+): Promise<void> {
   const appName = currentAppName();
   let input: unknown = null;
   if (opts.input) {
@@ -136,6 +167,14 @@ export async function backendInvokeCommand(handlerName: string, 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;
+  }
 }

package/src/commands/custom-integrations.ts

@@ -0,0 +1,68 @@
+import { output } from '../util/logger';
+import { getCwdAppName, mfAppName } from '../util/app-name';
+import { brokerBaseUrl, routingHeaders } from '../constants';
+import { readZthAuth } from '../util/auth/auth-store';
+
+function getTargetAppName(): string {
+  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);
+}
+
+interface CustomIntegrationSummary {
+  name: string;
+  allowedHost: string;
+  authHeaderName: string;
+  authScheme: string;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+  /** True when this is a preview showing an entry inherited from its base app, not its own. */
+  inherited?: boolean;
+}
+
+export async function listCustomIntegrationsCommand(): Promise<void> {
+  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()) as { connections: CustomIntegrationSummary[] };
+  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 });
+}
+
+export async function removeCustomIntegrationCommand(name: string | undefined): Promise<void> {
+  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 });
+}

package/src/commands/deploy.ts

@@ -206,6 +206,9 @@ async function deployPreview({ paths, consumerName, appName, token, opts }: Depl
     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,
   });