@mondaydotcomorg/z2h-cli 0.33.0 → 0.33.2

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 {
@@ -42,10 +45,12 @@ async function writeUsageJson(appDir: string, patch: Record<string, unknown>): P
   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.
- */
+export interface ReadDetectAndUploadResult {
+  integrations: string[];
+  handlerNames: string[];
+  apiUsages: Record<string, unknown>;
+}
+
 async function readDetectAndUpload(
   appDir: string,
   prefix: string,
@@ -53,17 +58,19 @@ async function readDetectAndUpload(
   version: number,
   deployedBy: string,
   logLabel: string
-): Promise<string[]> {
+): Promise<ReadDetectAndUploadResult> {
   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: string, body: string, contentType: string) =>
@@ -72,14 +79,10 @@ async function readDetectAndUpload(
     ...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
@@ -93,7 +96,7 @@ export async function deployBackend(opts: {
   version: number;
   deployedBy: string;
   isPreview: boolean;
-}): Promise<string[]> {
+}): Promise<ReadDetectAndUploadResult> {
   const { appDir, appName, mfKeyPrefix, version, deployedBy, isPreview } = opts;
   const prefix = isPreview ? `${mfKeyPrefix.replace(/\/MF$/, '')}/MS` : `${appName}/backend-${version}`;
   const logLabel = isPreview ? 'for preview' : `for "${appName}"`;
@@ -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/deploy.ts

@@ -131,13 +131,9 @@ 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,
@@ -146,16 +142,34 @@ async function uploadAndRegister(opts: {
     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 }: DeployContext): Promise<void> {

package/src/index.ts

@@ -279,7 +279,7 @@ async function main(): Promise<void> {
 
   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')
@@ -291,15 +291,21 @@ async function main(): Promise<void> {
   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'
+      "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'
     )
-    .option('--input <json>', 'JSON payload passed as ctx.input')
     .action(
       runCommand(
         {
           data: ([handlerName]: [string, unknown]) => ({ app_name: getCwdAppName(), handler: handlerName }),
         },
-        (handlerName: string, opts: { input?: string }) => backendInvokeCommand(handlerName, opts)
+        (handlerName: string, opts: { input?: string; code?: string }) => backendInvokeCommand(handlerName, opts)
       )
     );
 
@@ -330,7 +336,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: unknown) => {
     const errorMsg = err instanceof Error ? err.message : String(err);

package/src/util/broker/app.ts

@@ -64,21 +64,52 @@ export async function claimApp(appName: string, gitRemote: string): Promise<void
   }
 }
 
-async function registerApp(
-  appName: string,
-  token: string,
-  version: number,
-  entry: ManifestEntry,
-  visibility: 'public' | 'private',
-  gitRemote: string,
-  integrations?: string[],
-  description?: string,
-  masterAppName?: string
-): Promise<void> {
+export interface RegisterOrUpdateOptions {
+  appName: string;
+  token: string;
+  nextVersion: number;
+  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
+   * is set once and is immutable thereafter, so a later update doesn't need it.
+   */
+  masterAppName?: string;
+}
+
+async function registerApp(params: RegisterOrUpdateOptions & { visibility: 'public' | 'private' }): Promise<void> {
+  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();
@@ -87,19 +118,22 @@ async function registerApp(
 }
 
 /** Releases a new version onto an app that already exists. */
-async function updateApp(
-  appName: string,
-  token: string,
-  version: number,
-  entry: ManifestEntry,
-  gitRemote: string,
-  integrations?: string[],
-  description?: string
-): Promise<void> {
+async function updateApp(params: RegisterOrUpdateOptions): Promise<void> {
+  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();
@@ -107,21 +141,6 @@ async function updateApp(
   }
 }
 
-export interface RegisterOrUpdateOptions {
-  appName: string;
-  token: string;
-  nextVersion: number;
-  entry: ManifestEntry;
-  gitRemote: string;
-  integrations?: string[];
-  description?: string;
-  /**
-   * The base app a preview is for, sent only on first registration — the link
-   * is set once and is immutable thereafter, so a later update doesn't need it.
-   */
-  masterAppName?: string;
-}
-
 /**
  * v1 creates the app row (+ owner grant, prompting for visibility); later
  * versions release onto it via update instead — the two are separate
@@ -129,26 +148,16 @@ export interface RegisterOrUpdateOptions {
  * deploy and preview so this branching logic lives in exactly one place.
  */
 export async function registerOrUpdateApp(opts: RegisterOrUpdateOptions): Promise<void> {
-  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) {
     // registerApp/updateApp already tag the non-ok-response case; this catches anything