@mondaydotcomorg/z2h-cli 0.27.1 → 0.29.0

package/dist/esm/commands/backend.mjs

@@ -4,7 +4,7 @@ import { PutObjectCommand } from '@aws-sdk/client-s3';
 import { output, info } from '../util/logger.mjs';
 import { getCwdAppName, mfAppName } from '../util/app-name.mjs';
 import { readHandlers } from '../backend/handlers.mjs';
-import { detectIntegrationsFromHandlers } from '../backend/detect-integrations.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';
@@ -36,8 +36,8 @@ async function readDetectAndUpload(appDir, prefix, version, deployedBy, logLabel
         return [];
     }
     info(`reading backend handlers ${logLabel}`);
-    const { handlers } = await readHandlers(appDir);
-    const integrations = detectIntegrationsFromHandlers(handlers);
+    const { handlers, apiDomains } = await readHandlers(appDir);
+    const integrations = detectIntegrations(apiDomains);
     if (Object.keys(handlers).length === 0) {
         return integrations;
     }
@@ -77,6 +77,25 @@ async function deployBackend(opts) {
         throw tagDeployError('deploy_backend_error', err);
     }
 }
+/**
+ * Run the same handler validation deploy runs (syntax, isolate constraints,
+ * handler rules, integration detection) against the working tree — without
+ * uploading anything. Throws on the first invalid handler.
+ */
+async function backendValidateCommand(appDir = process.cwd()) {
+    if (!hasHandlers(appDir)) {
+        output('[z2h-cli] no backend/handlers/ directory — nothing to validate', { handlers: [], integrations: [] });
+        return;
+    }
+    const { handlers, apiDomains } = await readHandlers(appDir);
+    const names = Object.keys(handlers).sort();
+    const integrations = detectIntegrations(apiDomains);
+    const list = (xs) => (xs.length ? xs.join(', ') : 'none');
+    output(`[z2h-cli] ${names.length} handler(s) valid: ${list(names)}\n[z2h-cli] integrations: ${list(integrations)}`, {
+        handlers: names,
+        integrations,
+    });
+}
 async function backendInvokeCommand(handlerName, opts = {}) {
     const appName = currentAppName();
     let input = null;
@@ -92,4 +111,4 @@ async function backendInvokeCommand(handlerName, opts = {}) {
     output(`[z2h-cli] result (${Math.round(res.durationMs)}ms):\n${JSON.stringify(res.result, null, 2)}`, res);
 }
 
-export { backendInvokeCommand, deployBackend, hasHandlers };
+export { backendInvokeCommand, backendValidateCommand, deployBackend, hasHandlers };

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

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/commands/create.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAKpH,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwBD,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoF5F"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/commands/create.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAKpH,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwBD,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6F5F"}

package/dist/esm/commands/create.mjs

@@ -8,7 +8,7 @@ import { runYarnInstall } from '../util/npm/install.mjs';
 import { initRepo } from '../util/git/repo.mjs';
 import { validateRemoteOptions, resolveRemoteUrl } from '../util/git/remote-options.mjs';
 export { REMOTE_TYPES } from '../util/git/remote-options.mjs';
-import { fetchApp } from '../util/broker/app.mjs';
+import { fetchApp, claimApp } from '../util/broker/app.mjs';
 import { validateAppName, mfAppName } from '../util/app-name.mjs';
 import { prepareShadow } from '../shadow/prepare.mjs';
 
@@ -53,11 +53,19 @@ async function createCommand(appName, opts = {}) {
     if (!(await isDirEmpty(appDir))) {
         throw new Error(`${appDir} is non-empty. Pick a different name or wipe it first.`);
     }
-    // Check the broker — fail fast if the app is already registered.
+    // Check the broker — fail fast if the app already has a real release.
+    // A claimed-but-unpublished stub (`entry: null`) is fine to proceed past:
+    // either it's this same name being re-created after a local wipe (we'd only
+    // see it at all if we still have access to it), or it genuinely doesn't
+    // exist yet and we claim it below.
     const existing = await fetchApp(mfAppName(appName));
-    if (existing) {
+    if (existing?.deployed) {
         throw new Error(`An app named "${appName}" already exists in the Z2H registry. Pick a different name.`);
     }
+    const gitRemote = resolveRemoteUrl(opts.remote, appName, opts.repoUrl);
+    if (!existing) {
+        await claimApp(mfAppName(appName), gitRemote);
+    }
     // Compute substitutions.
     const vars = {
         __APP_NAME__: appName,
@@ -82,7 +90,6 @@ async function createCommand(appName, opts = {}) {
         await copy(opts.htmlFile, path.join(appDir, 'src', 'page.html'));
     }
     info(`initializing git repo for ${appName}...`);
-    const gitRemote = resolveRemoteUrl(opts.remote, appName, opts.repoUrl);
     await initRepo(appDir, gitRemote);
     info(`installing dependencies for ${appName}...`);
     await runYarnInstall({ cwd: workspace });

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

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/generate.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAwHD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA6E3F"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/generate.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAwHD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA8E3F"}

package/dist/esm/commands/generate.mjs

@@ -128,8 +128,9 @@ async function generateCommand(appName, opts) {
     if (!(await isDirEmpty(appDir))) {
         throw new Error(`${appDir} is non-empty. Pick a different name or wipe it first.`);
     }
+    // A claimed-but-unpublished stub (`entry: null`) is fine to proceed past — only a real release blocks generate.
     const existing = await fetchApp(mfAppName(appName));
-    if (existing) {
+    if (existing?.deployed) {
         throw new Error(`An app named "${appName}" already exists in the Z2H registry. Pick a different name.`);
     }
     info(`copying template "${template.id}" → ${appDir}`);

package/dist/esm/constants.d.ts

@@ -20,8 +20,7 @@ export declare const S3_SKILLS_BUCKET_NAME = "prod-use1-bigbrain-zth-skills";
 export declare const DATAVIZ_SKILLS_PREFIX = "dataviz/";
 export declare const APP_NAME_PATTERN: RegExp;
 export declare const PREVIEW_APP_NAME_PREFIX = "zth-preview-";
-export declare const DECLARED_INTEGRATIONS: readonly ["monday"];
-export type DeclaredIntegration = (typeof DECLARED_INTEGRATIONS)[number];
+export { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS, type DeclaredIntegration } from '@mondaydotcomorg/z2h-shared-utils';
 export declare const DEFAULT_BROKER_BASE_URL = "https://bigbrain-zth.bigbrain.me";
 /**
  * Resolves the broker origin (no trailing slash). Honors

package/dist/esm/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,eAAO,MAAM,eAAe,SAAS,CAAC;AAGtC,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEjD,CAAC;AAKF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAElD,CAAC;AAMF,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAC9B,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAG9B,eAAO,MAAM,iBAAiB,UAAY,CAAC;AAQ3C,eAAO,MAAM,iBAAiB,qCAAqC,CAAC;AACpE,eAAO,MAAM,MAAM,cAAc,CAAC;AAClC,eAAO,MAAM,gBAAgB,wEAA4D,CAAC;AAE1F,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAC7D,eAAO,MAAM,mBAAmB,+CAAgD,CAAC;AAKjF,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAK7C,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,iBAAiB,yDAA2C,CAAC;AAM1E,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AAIrE,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAMhD,eAAO,MAAM,gBAAgB,QAA2B,CAAC;AAEzD,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAMtD,eAAO,MAAM,qBAAqB,qBAAsB,CAAC;AACzD,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAKzE,eAAO,MAAM,uBAAuB,qCAAqC,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAID,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGvD;AAKD,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAG9C,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAGnD,eAAO,MAAM,uBAAuB,gCAAgC,CAAC;AAMrE,eAAO,MAAM,iBAAiB,EAAG,eAAwB,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,eAAO,MAAM,eAAe,SAAS,CAAC;AAGtC,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEjD,CAAC;AAKF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAElD,CAAC;AAMF,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAC9B,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAG9B,eAAO,MAAM,iBAAiB,UAAY,CAAC;AAQ3C,eAAO,MAAM,iBAAiB,qCAAqC,CAAC;AACpE,eAAO,MAAM,MAAM,cAAc,CAAC;AAClC,eAAO,MAAM,gBAAgB,wEAA4D,CAAC;AAE1F,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAC7D,eAAO,MAAM,mBAAmB,+CAAgD,CAAC;AAKjF,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAK7C,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,iBAAiB,yDAA2C,CAAC;AAM1E,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AAIrE,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAMhD,eAAO,MAAM,gBAAgB,QAA2B,CAAC;AAEzD,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAMtD,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAKxH,eAAO,MAAM,uBAAuB,qCAAqC,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAID,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGvD;AAKD,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAG9C,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAGnD,eAAO,MAAM,uBAAuB,gCAAgC,CAAC;AAMrE,eAAO,MAAM,iBAAiB,EAAG,eAAwB,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/esm/constants.mjs

@@ -1,3 +1,5 @@
+export { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS } from '@mondaydotcomorg/z2h-shared-utils';
+
 /**
  * Cross-file constants. Narrowly-used literals (templates, prefixes used in
  * one place) stay local to their file to keep this index small.
@@ -55,11 +57,6 @@ const DATAVIZ_SKILLS_PREFIX = 'dataviz/';
 // upfront for friendlier errors.
 const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{1,49}$/;
 const PREVIEW_APP_NAME_PREFIX = 'zth-preview-';
-// ─────────── Declared (OAuth-gated) backend integrations ─────
-// Closed set the CLI detects from handler sources and the broker validates on
-// register/update. Always-on channels (`db`, `llm`, `snowflake`) are not listed —
-// the runner builds those regardless. Shared via `@mondaydotcomorg/z2h-cli/constants`.
-const DECLARED_INTEGRATIONS = ['monday'];
 // ─────────── Broker origin + npm registry (shared §3 contract) ─────
 // The bigbrain-zth broker fronts both the STS credential route and the npm
 // proxy. `Z2H_BROKER_BASE_URL` overrides the origin for tests/staging.
@@ -101,4 +98,4 @@ function brokerNpmRegistryUrl() {
     return `${brokerBaseUrl()}${NPM_BROKER_PATH}`;
 }
 
-export { APP_NAME_PATTERN, BROKER_NPM_SCOPE, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, DATAVIZ_SKILLS_PREFIX, DECLARED_INTEGRATIONS, DEFAULT_BROKER_BASE_URL, GITIGNORE_ENTRIES, MANIFEST_KEY, MANIFEST_READ_URL, MAX_PORT, MIN_PORT, NPM_BROKER_PATH, PREVIEW_APP_NAME_PREFIX, PUBLIC_NPM_REGISTRY_URL, REGION, S3_PREVIEWS_FOLDER, S3_SKILLS_BUCKET_NAME, SHADOW_DEV_DEPS, SHADOW_DIR_NAME, SHADOW_SCRIPTS, Z2H_NPM_TOKEN_ENV, brokerBaseUrl, brokerNpmRegistryUrl, routingHeaders };
+export { APP_NAME_PATTERN, BROKER_NPM_SCOPE, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, DATAVIZ_SKILLS_PREFIX, DEFAULT_BROKER_BASE_URL, GITIGNORE_ENTRIES, MANIFEST_KEY, MANIFEST_READ_URL, MAX_PORT, MIN_PORT, NPM_BROKER_PATH, PREVIEW_APP_NAME_PREFIX, PUBLIC_NPM_REGISTRY_URL, REGION, S3_PREVIEWS_FOLDER, S3_SKILLS_BUCKET_NAME, SHADOW_DEV_DEPS, SHADOW_DIR_NAME, SHADOW_SCRIPTS, Z2H_NPM_TOKEN_ENV, brokerBaseUrl, brokerNpmRegistryUrl, routingHeaders };

package/dist/esm/index.mjs

@@ -17,7 +17,7 @@ import { generateZ2HTokenCommand } from './commands/generate-z2h-token.mjs';
 import { migrateCommand } from './commands/migrate.mjs';
 import { tagCommand } from './commands/tag.mjs';
 import { editCommand } from './commands/edit.mjs';
-import { backendInvokeCommand } from './commands/backend.mjs';
+import { backendValidateCommand, backendInvokeCommand } from './commands/backend.mjs';
 import { doctorCommand } from './commands/doctor.mjs';
 import { fail, errorLog, setOutputMode, getOutputMode } from './util/logger.mjs';
 import { runCommand } from './util/run-command.mjs';
@@ -170,7 +170,11 @@ async function main() {
         .action(runCommand({ data: cwdApp }, (opts) => deleteCommand(opts)));
     const backend = program
         .command('backend')
-        .description("Inspect the app's backend: invoke a deployed handler by name");
+        .description("Inspect the app's backend: validate handler sources or invoke a deployed handler by name");
+    backend
+        .command('validate')
+        .description('Validate backend/handlers/*.js exactly as deploy would (syntax, isolate rules, integrations) without uploading')
+        .action(runCommand({ data: cwdApp }, () => backendValidateCommand()));
     backend
         .command('invoke <handlerName>')
         .description('Invoke a deployed backend handler by name (the filename without .ts) — mainly for testing a handler without going through the frontend')

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

@@ -2,16 +2,26 @@ import type { ManifestEntry } from '../manifest';
 export interface AppInfo {
     appName: string;
     version: number;
-    entry: Record<string, unknown>;
+    /** Null for a claimed-but-unpublished app — reserved via `create`, never deployed yet. */
+    entry: Record<string, unknown> | null;
+    /** True once a real release has landed (`entry` is set) — false for a claimed-but-unpublished stub. */
+    deployed: boolean;
     deployedBy: string;
     gitRemote: string;
     createdBy: string;
 }
 /**
  * Fetches a single app's current state from the broker.
- * Returns null if the app has never been deployed (404).
+ * Returns null if the app has never even been claimed (404).
  */
 export declare function fetchApp(appName: string): Promise<AppInfo | null>;
+/**
+ * Reserves an app name (+ owner grant) before any deploy — called once from
+ * `create`. Idempotent from the caller's perspective: `create` only calls this
+ * when {@link fetchApp} found nothing at all, so a 409 here means someone else
+ * claimed the exact same name in the gap between the two calls.
+ */
+export declare function claimApp(appName: string, gitRemote: string): Promise<void>;
 export interface RegisterOrUpdateOptions {
     appName: string;
     token: string;

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

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AA4CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,uGAAuG;IACvG,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhF;AA4CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}

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

@@ -6,7 +6,7 @@ import { tagDeployError, DeployError } from '../errors.mjs';
 
 /**
  * Fetches a single app's current state from the broker.
- * Returns null if the app has never been deployed (404).
+ * Returns null if the app has never even been claimed (404).
  */
 async function fetchApp(appName) {
     const { token } = await readZthAuth();
@@ -29,6 +29,24 @@ async function fetchApp(appName) {
     }
     return res.json();
 }
+/**
+ * Reserves an app name (+ owner grant) before any deploy — called once from
+ * `create`. Idempotent from the caller's perspective: `create` only calls this
+ * when {@link fetchApp} found nothing at all, so a 409 here means someone else
+ * claimed the exact same name in the gap between the two calls.
+ */
+async function claimApp(appName, gitRemote) {
+    const { token } = await readZthAuth();
+    const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/claim`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
+        body: JSON.stringify({ appName, gitRemote }),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Claiming app name failed (${res.status}): ${text.slice(0, 1024)}`);
+    }
+}
 async function registerApp(appName, token, version, entry, visibility, gitRemote, integrations, description) {
     const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/register`, {
         method: 'POST',
@@ -78,4 +96,4 @@ async function registerOrUpdateApp(opts) {
     }
 }
 
-export { fetchApp, registerOrUpdateApp };
+export { claimApp, fetchApp, registerOrUpdateApp };

package/dist/index.js

@@ -176,7 +176,11 @@ async function main() {
         .action(util_runCommand.runCommand({ data: cwdApp }, (opts) => commands_delete.deleteCommand(opts)));
     const backend = program
         .command('backend')
-        .description("Inspect the app's backend: invoke a deployed handler by name");
+        .description("Inspect the app's backend: validate handler sources or invoke a deployed handler by name");
+    backend
+        .command('validate')
+        .description('Validate backend/handlers/*.js exactly as deploy would (syntax, isolate rules, integrations) without uploading')
+        .action(util_runCommand.runCommand({ data: cwdApp }, () => commands_backend.backendValidateCommand()));
     backend
         .command('invoke <handlerName>')
         .description('Invoke a deployed backend handler by name (the filename without .ts) — mainly for testing a handler without going through the frontend')

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

@@ -2,16 +2,26 @@ import type { ManifestEntry } from '../manifest';
 export interface AppInfo {
     appName: string;
     version: number;
-    entry: Record<string, unknown>;
+    /** Null for a claimed-but-unpublished app — reserved via `create`, never deployed yet. */
+    entry: Record<string, unknown> | null;
+    /** True once a real release has landed (`entry` is set) — false for a claimed-but-unpublished stub. */
+    deployed: boolean;
     deployedBy: string;
     gitRemote: string;
     createdBy: string;
 }
 /**
  * Fetches a single app's current state from the broker.
- * Returns null if the app has never been deployed (404).
+ * Returns null if the app has never even been claimed (404).
  */
 export declare function fetchApp(appName: string): Promise<AppInfo | null>;
+/**
+ * Reserves an app name (+ owner grant) before any deploy — called once from
+ * `create`. Idempotent from the caller's perspective: `create` only calls this
+ * when {@link fetchApp} found nothing at all, so a 409 here means someone else
+ * claimed the exact same name in the gap between the two calls.
+ */
+export declare function claimApp(appName: string, gitRemote: string): Promise<void>;
 export interface RegisterOrUpdateOptions {
     appName: string;
     token: string;

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

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AA4CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,uGAAuG;IACvG,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhF;AA4CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}

package/dist/util/broker/app.js

@@ -8,7 +8,7 @@ const util_errors = require('../errors.js');
 
 /**
  * Fetches a single app's current state from the broker.
- * Returns null if the app has never been deployed (404).
+ * Returns null if the app has never even been claimed (404).
  */
 async function fetchApp(appName) {
     const { token } = await util_auth_authStore.readZthAuth();
@@ -31,6 +31,24 @@ async function fetchApp(appName) {
     }
     return res.json();
 }
+/**
+ * Reserves an app name (+ owner grant) before any deploy — called once from
+ * `create`. Idempotent from the caller's perspective: `create` only calls this
+ * when {@link fetchApp} found nothing at all, so a 409 here means someone else
+ * claimed the exact same name in the gap between the two calls.
+ */
+async function claimApp(appName, gitRemote) {
+    const { token } = await util_auth_authStore.readZthAuth();
+    const res = await fetch(`${constants.brokerBaseUrl()}/z2h-cli/apps/claim`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...constants.routingHeaders() },
+        body: JSON.stringify({ appName, gitRemote }),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Claiming app name failed (${res.status}): ${text.slice(0, 1024)}`);
+    }
+}
 async function registerApp(appName, token, version, entry, visibility, gitRemote, integrations, description) {
     const res = await fetch(`${constants.brokerBaseUrl()}/z2h-cli/apps/register`, {
         method: 'POST',
@@ -80,5 +98,6 @@ async function registerOrUpdateApp(opts) {
     }
 }
 
+exports.claimApp = claimApp;
 exports.fetchApp = fetchApp;
 exports.registerOrUpdateApp = registerOrUpdateApp;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.27.1",
+  "version": "0.29.0",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -52,7 +52,9 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.706.0",
     "@mondaydotcomorg/z2h-dashboard-templates": "^0.3.4",
-    "@mondaydotcomorg/z2h-shared-utils": "^0.5.0",
+    "@mondaydotcomorg/z2h-shared-utils": "^0.6.0",
+    "acorn": "^8.14.0",
+    "acorn-walk": "^8.3.4",
     "chokidar": "^3.6.0",
     "commander": "^12.1.0",
     "cors": "^2.8.6",

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

@@ -0,0 +1,53 @@
+import { parse, type ExpressionStatement, type Program } from 'acorn';
+import { describe, expect, it } from 'vitest';
+import { collectBindings, createPathResolver } from '../ast';
+
+const program = (source: string): Program => parse(source, { ecmaVersion: 'latest', sourceType: 'script' });
+
+/** Resolves the expression in the program's last statement. */
+const resolveLast = (source: string, contextParam?: string) => {
+  const p = program(source);
+  const last = p.body[p.body.length - 1] as ExpressionStatement;
+  return createPathResolver(collectBindings(p), contextParam).pathOf(last.expression);
+};
+
+describe('createPathResolver', () => {
+  it('returns the literal chain when nothing is aliased', () => {
+    expect(resolveLast('ctx.api.v1.db.get;')).toBe('ctx.api.v1.db.get');
+  });
+
+  it('treats computed string literals as static keys', () => {
+    expect(resolveLast('ctx.api.v1["db"].get;')).toBe('ctx.api.v1.db.get');
+    expect(resolveLast("const { ['db']: store } = ctx.api.v1; store.get;")).toBe('ctx.api.v1.db.get');
+  });
+
+  it('returns undefined for dynamic links and non-identifier roots', () => {
+    expect(resolveLast('ctx.api.v1[db].get;')).toBeUndefined();
+    expect(resolveLast('fn().db;')).toBeUndefined();
+    expect(resolveLast('"x";')).toBeUndefined();
+  });
+
+  it('rewrites the handler context parameter to ctx', () => {
+    expect(resolveLast('context.api.v1.db.get;', 'context')).toBe('ctx.api.v1.db.get');
+    expect(resolveLast('const sf = context.api.v1.snowflake; sf.query;', 'context')).toBe('ctx.api.v1.snowflake.query');
+  });
+
+  it('follows const aliases, including destructuring and chains', () => {
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; sf.query;')).toBe('ctx.api.v1.snowflake.query');
+    expect(resolveLast('const { v1 } = ctx.api; v1.db;')).toBe('ctx.api.v1.db');
+    expect(resolveLast('const { v1: { db: store } } = ctx.api; store.get;')).toBe('ctx.api.v1.db.get');
+    expect(resolveLast('const a = ctx.api; const b = a.v1; const c = b.db; c;')).toBe('ctx.api.v1.db');
+  });
+
+  it('leaves unpinnable names as written', () => {
+    expect(resolveLast('let sf = ctx.api.v1.snowflake; sf.query;')).toBe('sf.query');
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; sf = 1; sf.query;')).toBe('sf.query');
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; function f(sf) {} sf.query;')).toBe('sf.query');
+    expect(resolveLast('const sf = ctx.api.v1.snowflake; { const sf = 1; } sf.query;')).toBe('sf.query');
+    expect(resolveLast('const [sf] = ctx.api; sf.query;')).toBe('sf.query');
+  });
+
+  it('does not loop on circular aliases', () => {
+    expect(resolveLast('const a = b.x; const b = a.y; a.z;')).toBe('a.y.x.z');
+  });
+});

package/src/backend/__tests__/detect-integrations.test.ts

@@ -1,42 +1,24 @@
 import { describe, expect, it } from 'vitest';
-import { detectIntegrationsFromHandlers } from '../detect-integrations';
+import { detectIntegrations } from '../detect-integrations';
 
-describe('detectIntegrationsFromHandlers', () => {
-  it('returns [] when handlers are empty', () => {
-    expect(detectIntegrationsFromHandlers({})).toEqual([]);
+describe('detectIntegrations', () => {
+  it('returns [] when no domains are touched', () => {
+    expect(detectIntegrations([])).toEqual([]);
   });
 
-  it('returns [] when sources never touch ctx.api.v1.monday', () => {
-    expect(
-      detectIntegrationsFromHandlers({
-        ping: 'async function handler(ctx) { return ctx.db.get("x"); }',
-        q: 'async function handler(ctx) { return ctx.api.v1.snowflake.runQuery("select 1"); }',
-      })
-    ).toEqual([]);
+  it('ignores always-on channels', () => {
+    expect(detectIntegrations(['db', 'llm', 'snowflake'])).toEqual([]);
   });
 
-  it('detects monday from ctx.api.v1.monday', () => {
-    expect(
-      detectIntegrationsFromHandlers({
-        boards: 'async function handler(ctx) {\n  return ctx.api.v1.monday.query("{ boards { id } }");\n}',
-      })
-    ).toEqual(['monday']);
+  it('ignores unknown domains', () => {
+    expect(detectIntegrations(['totallyMadeUp'])).toEqual([]);
   });
 
-  it('dedupes across handlers', () => {
-    expect(
-      detectIntegrationsFromHandlers({
-        a: 'ctx.api.v1.monday.query("x")',
-        b: 'ctx.api.v1.monday.query("y"); ctx.api.v1.snowflake.runQuery("z")',
-      })
-    ).toEqual(['monday']);
+  it('keeps declared integrations', () => {
+    expect(detectIntegrations(['snowflake', 'monday', 'db'])).toEqual(['monday']);
   });
 
-  it('ignores lookalike identifiers that are not ctx.api.v1.monday', () => {
-    expect(
-      detectIntegrationsFromHandlers({
-        a: 'const monday = 1; api.v1.monday; ctx.api.v2.monday',
-      })
-    ).toEqual([]);
+  it('dedupes', () => {
+    expect(detectIntegrations(['monday', 'monday'])).toEqual(['monday']);
   });
 });

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

@@ -1,10 +1,15 @@
 import path from 'node:path';
 import os from 'node:os';
 import { mkdtemp, rm, ensureDir, writeFile } from 'fs-extra';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { readHandlers } from '../handlers';
 
+vi.mock('../../util/tracker', () => ({
+  trackEvent: vi.fn().mockResolvedValue(undefined),
+  trackDuration: vi.fn(),
+}));
+
 let appDir: string;
 
 const writeHandler = (name: string, source: string) =>
@@ -23,16 +28,14 @@ describe('readHandlers — discovery', () => {
   it('returns empty handlers when backend/handlers does not exist', async () => {
     const dir = await mkdtemp(path.join(os.tmpdir(), 'z2h-empty-'));
     try {
-      const result = await readHandlers(dir);
-      expect(result.handlers).toEqual({});
+      await expect(readHandlers(dir)).resolves.toEqual({ handlers: {}, apiDomains: [] });
     } finally {
       await rm(dir, { recursive: true, force: true });
     }
   });
 
   it('returns empty handlers when the directory is empty', async () => {
-    const result = await readHandlers(appDir);
-    expect(result.handlers).toEqual({});
+    await expect(readHandlers(appDir)).resolves.toEqual({ handlers: {}, apiDomains: [] });
   });
 
   it('uses the filename (without .js) as the handler name', async () => {
@@ -57,43 +60,27 @@ describe('readHandlers — output contract', () => {
     expect(handlers['my_handler']).toBe(source);
   });
 
-  it.each([
-    ['a function declaration', 'async function handler(ctx) { return 1; }'],
-    ['a const arrow', 'const handler = async (ctx) => 1;'],
-    ['a var assignment', 'var handler = async function(ctx) { return 1; };'],
-  ])('accepts %s', async (_label, source) => {
-    await writeHandler('h.js', source);
-    await expect(readHandlers(appDir)).resolves.toMatchObject({ handlers: { h: expect.any(String) } });
+  it('merges the ctx.api.v1 domains touched across all handlers, sorted and unique', async () => {
+    await writeHandler('a.js', 'async function handler(ctx) { return ctx.api.v1.monday.query("x"); }');
+    await writeHandler(
+      'b.js',
+      'async function handler(ctx) { ctx.api.v1.db.get("k"); return ctx.api.v1.monday.query("y"); }'
+    );
+    const { apiDomains } = await readHandlers(appDir);
+    expect(apiDomains).toEqual(['db', 'monday']);
   });
 });
 
+// Per-shape validation rules are covered in validate.test.ts; here we only prove
+// that readHandlers runs the validator and names the offending file.
 describe('readHandlers — validation', () => {
-  it('rejects a file that does not define handler', async () => {
-    await writeHandler('bad.js', 'async function main(ctx) { return 1; }');
-    await expect(readHandlers(appDir)).rejects.toThrow(/must define a handler/);
-  });
-
-  it('rejects import statements', async () => {
-    await writeHandler('bad.js', "import { foo } from './utils';\nasync function handler(ctx) { return foo; }");
-    await expect(readHandlers(appDir)).rejects.toThrow(/must not import/);
-  });
-
-  it('rejects require calls', async () => {
-    await writeHandler('bad.js', "const foo = require('./utils');\nasync function handler(ctx) { return foo; }");
-    await expect(readHandlers(appDir)).rejects.toThrow(/must not import/);
-  });
-
   it('rejects .ts handler files with a clear message', async () => {
     await writeHandler('call_snowflake.ts', 'async function handler(ctx) { return 1; }');
     await expect(readHandlers(appDir)).rejects.toThrow(/TypeScript handlers are not yet supported/);
   });
 
-  it.each([
-    ['an exported function declaration', 'export async function handler(ctx) { return 1; }'],
-    ['an exported const', 'export const handler = async (ctx) => 1;'],
-    ['a default-exported function', 'export default async function handler(ctx) { return 1; }'],
-  ])('rejects %s — the isolate has no module system', async (_label, source) => {
-    await writeHandler('bad.js', source);
-    await expect(readHandlers(appDir)).rejects.toThrow(/must not export handler/);
+  it('surfaces validation errors with the filename', async () => {
+    await writeHandler('bad.js', 'async function handler(ctx) {\n  return ctx.input.(;\n}');
+    await expect(readHandlers(appDir)).rejects.toThrow(/^bad\.js:2:19: not valid JavaScript/);
   });
 });

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

@@ -0,0 +1,25 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { trackEvent } from '../../util/tracker';
+import { parseOrThrow } from '../parse';
+
+vi.mock('../../util/tracker', () => ({
+  trackEvent: vi.fn().mockResolvedValue(undefined),
+  trackDuration: vi.fn(),
+}));
+
+const track = vi.mocked(trackEvent);
+
+describe('parseOrThrow — telemetry', () => {
+  afterEach(() => {
+    track.mockClear();
+  });
+
+  it('tracks the same message it throws', () => {
+    expect(() => parseOrThrow('h.js', 'async function handler(ctx) {\n  return ctx.input.(;\n}')).toThrow(
+      'h.js:2:19: not valid JavaScript — Unexpected token'
+    );
+    expect(track).toHaveBeenCalledWith('z2h_cli_handler_parse_error', {
+      error: 'h.js:2:19: not valid JavaScript — Unexpected token',
+    });
+  });
+});