@mondaydotcomorg/z2h-cli 0.33.1 → 0.33.2

package/dist/commands/backend.d.ts

@@ -1,9 +1,10 @@
 export declare function hasHandlers(appDir: string): boolean;
+export interface ReadDetectAndUploadResult {
+    integrations: string[];
+    handlerNames: string[];
+    apiUsages: Record<string, unknown>;
+}
 /**
- * Deploy the app's backend handlers to S3 and return the integrations detected
- * from their sources. Each `.js` handler is uploaded as its own flat file — no
- * compilation, no bundling, no npm deps.
- *
  * Integration sync note: the returned set is re-derived from the CURRENT backend
  * sources on every deploy, and the platform set is reconciled to exactly match
  * it (there is no stored declaration to fall back on). A deploy therefore always
@@ -17,7 +18,7 @@ export declare function deployBackend(opts: {
     version: number;
     deployedBy: string;
     isPreview: boolean;
-}): Promise<string[]>;
+}): Promise<ReadDetectAndUploadResult>;
 /**
  * Runs the same checks deploy does against the working tree, refreshing the
  * local `usage.json` — no upload to S3. Throws on the first invalid handler.

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

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

package/dist/commands/backend.js

@@ -48,21 +48,19 @@ async function writeUsageJson(appDir, patch) {
     const existing = await readExistingUsage(appDir);
     await fs$1.writeJson(path__default.default.join(appDir, 'usage.json'), { ...existing, ...patch }, { spaces: 2 });
 }
-/**
- * Returns `[]` when there is no `backend/handlers/` dir (or it is empty of sources)
- * so callers can always pass the result to `registerOrUpdateApp` without a separate gate.
- */
 async function readDetectAndUpload(appDir, prefix, appName, version, deployedBy, logLabel) {
     if (!hasHandlers(appDir)) {
-        return [];
+        await writeUsageJson(appDir, { appName, deployedBy, apiUsages: {} });
+        return { integrations: [], handlerNames: [], apiUsages: {} };
     }
     util_logger.info(`reading backend handlers ${logLabel}`);
     const { handlers, apiDomains, apiUsages } = await backend_handlers.readHandlers(appDir);
     const integrations = backend_detectIntegrations.detectIntegrations(apiDomains);
+    const handlerNames = Object.keys(handlers);
+    await writeUsageJson(appDir, { appName, deployedBy, apiUsages });
     if (Object.keys(handlers).length === 0) {
-        return integrations;
+        return { integrations, handlerNames, apiUsages };
     }
-    await writeUsageJson(appDir, { appName, deployedBy, apiUsages });
     const s3 = util_s3_client.getS3Client();
     const meta = JSON.stringify({ version, deployedBy, handlers: Object.keys(handlers) });
     const put = (key, body, contentType) => s3.send(new clientS3.PutObjectCommand({ Bucket: constants.BUCKET_WRITE_NAME, Key: key, Body: body, ContentType: contentType }));
@@ -70,13 +68,9 @@ async function readDetectAndUpload(appDir, prefix, appName, version, deployedBy,
         ...Object.entries(handlers).map(([name, code]) => put(`${prefix}/${name}.js`, code, 'application/javascript')),
         put(`${prefix}/meta.json`, meta, 'application/json'),
     ]);
-    return integrations;
+    return { integrations, handlerNames, apiUsages };
 }
 /**
- * Deploy the app's backend handlers to S3 and return the integrations detected
- * from their sources. Each `.js` handler is uploaded as its own flat file — no
- * compilation, no bundling, no npm deps.
- *
  * Integration sync note: the returned set is re-derived from the CURRENT backend
  * sources on every deploy, and the platform set is reconciled to exactly match
  * it (there is no stored declaration to fall back on). A deploy therefore always

package/dist/commands/deploy.js

@@ -85,12 +85,9 @@ async function buildAndStamp(opts) {
  */
 async function uploadAndRegister(opts) {
     const { paths, keyPrefix, appName, token, nextVersion, entry, gitRemote, isPreview, description, masterAppName } = opts;
-    util_logger.info(`uploading ${isPreview ? 'preview ' : ''}build → s3://${constants.BUCKET_WRITE_NAME}/${keyPrefix}/`);
-    await util_s3_upload.uploadDir(paths.shadowBuild, keyPrefix);
-    // `integrations` is inferred from the backend sources in the working tree and
-    // reconciled to exactly match on register — see `deployBackend` for why this
-    // depends on deploying from the app's latest merged state.
-    const integrations = await commands_backend.deployBackend({
+    // Runs before the frontend upload so a `deployBackend` failure can't leave a
+    // preview's unversioned `MF` dir overwritten with no rollback.
+    const { integrations, handlerNames, apiUsages } = await commands_backend.deployBackend({
         appDir: process.cwd(),
         appName,
         mfKeyPrefix: keyPrefix,
@@ -98,16 +95,32 @@ async function uploadAndRegister(opts) {
         deployedBy: util_machineIdentity.whoAmI(),
         isPreview,
     });
-    await util_broker_app.registerOrUpdateApp({
-        appName,
-        token,
-        nextVersion,
-        entry,
-        gitRemote,
-        integrations,
-        description,
-        masterAppName,
-    });
+    try {
+        util_logger.info(`uploading ${isPreview ? 'preview ' : ''}build → s3://${constants.BUCKET_WRITE_NAME}/${keyPrefix}/`);
+        await util_s3_upload.uploadDir(paths.shadowBuild, keyPrefix);
+        await util_broker_app.registerOrUpdateApp({
+            appName,
+            token,
+            nextVersion,
+            entry,
+            gitRemote,
+            integrations,
+            handlerNames,
+            apiUsages,
+            description,
+            masterAppName,
+        });
+    }
+    catch (err) {
+        // A live deploy is safe either way — RDS's version gates what's actually served, so
+        // an orphaned S3 object is harmless — but a preview is served straight from its
+        // unversioned prefix with no such gate, so only it needs the warning below.
+        if (isPreview) {
+            util_logger.warn(`preview backend was already deployed before this failed — re-run "z2h-cli deploy --preview" to retry ` +
+                `(every step overwrites, so a retry fully repairs it)`);
+        }
+        throw err;
+    }
 }
 async function deployPreview({ paths, consumerName, appName, token, opts }) {
     // A preview inherits from the live app it previews, resolved by name server-side —

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

@@ -1,9 +1,10 @@
 export declare function hasHandlers(appDir: string): boolean;
+export interface ReadDetectAndUploadResult {
+    integrations: string[];
+    handlerNames: string[];
+    apiUsages: Record<string, unknown>;
+}
 /**
- * Deploy the app's backend handlers to S3 and return the integrations detected
- * from their sources. Each `.js` handler is uploaded as its own flat file — no
- * compilation, no bundling, no npm deps.
- *
  * Integration sync note: the returned set is re-derived from the CURRENT backend
  * sources on every deploy, and the platform set is reconciled to exactly match
  * it (there is no stored declaration to fall back on). A deploy therefore always
@@ -17,7 +18,7 @@ export declare function deployBackend(opts: {
     version: number;
     deployedBy: string;
     isPreview: boolean;
-}): Promise<string[]>;
+}): Promise<ReadDetectAndUploadResult>;
 /**
  * Runs the same checks deploy does against the working tree, refreshing the
  * local `usage.json` — no upload to S3. Throws on the first invalid handler.

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

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

package/dist/esm/commands/backend.mjs

@@ -42,21 +42,19 @@ async function writeUsageJson(appDir, patch) {
     const existing = await readExistingUsage(appDir);
     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.
- */
 async function readDetectAndUpload(appDir, prefix, appName, version, deployedBy, logLabel) {
     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, body, contentType) => s3.send(new PutObjectCommand({ Bucket: BUCKET_WRITE_NAME, Key: key, Body: body, ContentType: contentType }));
@@ -64,13 +62,9 @@ async function readDetectAndUpload(appDir, prefix, appName, version, deployedBy,
         ...Object.entries(handlers).map(([name, code]) => put(`${prefix}/${name}.js`, code, 'application/javascript')),
         put(`${prefix}/meta.json`, meta, 'application/json'),
     ]);
-    return integrations;
+    return { integrations, handlerNames, apiUsages };
 }
 /**
- * Deploy the app's backend handlers to S3 and return the integrations detected
- * from their sources. Each `.js` handler is uploaded as its own flat file — no
- * compilation, no bundling, no npm deps.
- *
  * Integration sync note: the returned set is re-derived from the CURRENT backend
  * sources on every deploy, and the platform set is reconciled to exactly match
  * it (there is no stored declaration to fall back on). A deploy therefore always

package/dist/esm/commands/deploy.mjs

@@ -79,12 +79,9 @@ async function buildAndStamp(opts) {
  */
 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,
@@ -92,16 +89,32 @@ async function uploadAndRegister(opts) {
         deployedBy: whoAmI(),
         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 }) {
     // A preview inherits from the live app it previews, resolved by name server-side —

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

@@ -29,6 +29,8 @@ export interface RegisterOrUpdateOptions {
     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

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,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;AA6CD,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;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BtF"}
+{"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;AAED,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,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA8DD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}

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

@@ -47,11 +47,23 @@ async function claimApp(appName, gitRemote) {
         throw new Error(`Claiming app name failed (${res.status}): ${text.slice(0, 1024)}`);
     }
 }
-async function registerApp(appName, token, version, entry, visibility, gitRemote, integrations, description, masterAppName) {
+async function registerApp(params) {
+    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();
@@ -59,11 +71,12 @@ async function registerApp(appName, token, version, entry, visibility, gitRemote
     }
 }
 /** Releases a new version onto an app that already exists. */
-async function updateApp(appName, token, version, entry, gitRemote, integrations, description) {
+async function updateApp(params) {
+    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();
@@ -77,16 +90,16 @@ async function updateApp(appName, token, version, entry, gitRemote, integrations
  * deploy and preview so this branching logic lives in exactly one place.
  */
 async function registerOrUpdateApp(opts) {
-    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) {

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

@@ -29,6 +29,8 @@ export interface RegisterOrUpdateOptions {
     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

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,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;AA6CD,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;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BtF"}
+{"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;AAED,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,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA8DD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}

package/dist/util/broker/app.js

@@ -49,11 +49,23 @@ async function claimApp(appName, gitRemote) {
         throw new Error(`Claiming app name failed (${res.status}): ${text.slice(0, 1024)}`);
     }
 }
-async function registerApp(appName, token, version, entry, visibility, gitRemote, integrations, description, masterAppName) {
+async function registerApp(params) {
+    const { appName, token, nextVersion: version, entry, visibility, gitRemote, integrations, handlerNames, apiUsages, description, masterAppName, } = params;
     const res = await fetch(`${constants.brokerBaseUrl()}/z2h-cli/apps/register`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...constants.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();
@@ -61,11 +73,12 @@ async function registerApp(appName, token, version, entry, visibility, gitRemote
     }
 }
 /** Releases a new version onto an app that already exists. */
-async function updateApp(appName, token, version, entry, gitRemote, integrations, description) {
+async function updateApp(params) {
+    const { appName, token, nextVersion: version, entry, gitRemote, integrations, handlerNames, apiUsages, description, } = params;
     const res = await fetch(`${constants.brokerBaseUrl()}/z2h-cli/apps/update`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...constants.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();
@@ -79,16 +92,16 @@ async function updateApp(appName, token, version, entry, gitRemote, integrations
  * deploy and preview so this branching logic lives in exactly one place.
  */
 async function registerOrUpdateApp(opts) {
-    const { appName, token, nextVersion, entry, gitRemote, integrations, description, masterAppName } = opts;
+    const { appName, nextVersion } = opts;
     try {
         if (nextVersion === 1) {
             const visibility = await util_promptVisibility.resolveAppVisibility(appName);
             util_logger.info(`registering "${appName}" → v${nextVersion} (${visibility})`);
-            await registerApp(appName, token, nextVersion, entry, visibility, gitRemote, integrations, description, masterAppName);
+            await registerApp({ ...opts, visibility });
         }
         else {
             util_logger.info(`updating "${appName}" → v${nextVersion}`);
-            await updateApp(appName, token, nextVersion, entry, gitRemote, integrations, description);
+            await updateApp(opts);
         }
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.33.1",
+  "version": "0.33.2",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

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

@@ -63,7 +63,29 @@ describe('deployBackend (live)', () => {
     await rm(tmp, { recursive: true, force: true });
   });
 
-  it('skips upload when the handlers directory holds nothing', async () => {
+  it('skips upload and resets usage.json when there is no handlers directory', async () => {
+    // hasHandlers is false here, so readHandlers is never reached — no mock needed.
+    await expect(
+      deployBackend({
+        appDir: tmp,
+        appName: 'mf-my-app',
+        mfKeyPrefix: 'mf-my-app/1',
+        version: 1,
+        deployedBy: 'test-user',
+        isPreview: false,
+      })
+    ).resolves.toEqual({ integrations: [], handlerNames: [], apiUsages: {} });
+    expect(mockSend).not.toHaveBeenCalled();
+    await expect(readJson(path.join(tmp, 'usage.json'))).resolves.toEqual({
+      appName: 'mf-my-app',
+      deployedBy: 'test-user',
+      apiUsages: {},
+    });
+  });
+
+  it('skips upload and resets usage.json when backend/handlers exists but has no handler sources', async () => {
+    await ensureDir(path.join(tmp, 'backend', 'handlers'));
+    await writeJson(path.join(tmp, 'usage.json'), { apiUsages: { deleted_handler: {} }, keepMe: 1 });
     readHandlersMock.mockResolvedValue({ handlers: {}, apiDomains: [], apiUsages: {} });
 
     await expect(
@@ -75,8 +97,14 @@ describe('deployBackend (live)', () => {
         deployedBy: 'test-user',
         isPreview: false,
       })
-    ).resolves.toEqual([]);
+    ).resolves.toEqual({ integrations: [], handlerNames: [], apiUsages: {} });
     expect(mockSend).not.toHaveBeenCalled();
+    await expect(readJson(path.join(tmp, 'usage.json'))).resolves.toEqual({
+      keepMe: 1,
+      appName: 'mf-my-app',
+      deployedBy: 'test-user',
+      apiUsages: {},
+    });
   });
 
   it('transpiles and uploads handlers when backend/handlers exists', async () => {
@@ -98,11 +126,16 @@ describe('deployBackend (live)', () => {
         deployedBy: 'test-user',
         isPreview: false,
       })
-    ).resolves.toEqual([]);
+    ).resolves.toEqual({
+      integrations: [],
+      handlerNames: ['call_snowflake'],
+      apiUsages: { call_snowflake: { snowflake: { query: [{ sql: 'x' }] } } },
+    });
     expect(mockSend).toHaveBeenCalled();
     const keys: string[] = mockSend.mock.calls.map((c: unknown[]) => (c[0] as { input: { Key: string } }).input.Key);
     expect(keys.some(k => k.includes('/backend-1/'))).toBe(true);
-    // usage.json stays local-only — the runner's S3 discovery still comes from meta.json.
+    // usage.json stays local-only. meta.json is still uploaded as the S3 fallback,
+    // used only for a row whose `apps.handler_names` column is still null.
     expect(keys.some(k => k.endsWith('/usage.json'))).toBe(false);
     expect(keys.some(k => k.endsWith('/meta.json'))).toBe(true);
 
@@ -191,22 +224,6 @@ describe('deployBackend (preview)', () => {
     await rm(tmp, { recursive: true, force: true });
   });
 
-  it('skips upload when the handlers directory holds nothing', async () => {
-    readHandlersMock.mockResolvedValue({ handlers: {}, apiDomains: [], apiUsages: {} });
-
-    await expect(
-      deployBackend({
-        appDir: tmp,
-        appName: 'mf-zth-preview-abc12345-my-app',
-        mfKeyPrefix: 'previews/mf-zth-preview-abc12345-my-app/MF',
-        version: 1,
-        deployedBy: 'test-user',
-        isPreview: true,
-      })
-    ).resolves.toEqual([]);
-    expect(mockSend).not.toHaveBeenCalled();
-  });
-
   it('uploads handlers under the MS prefix for preview', async () => {
     await ensureDir(path.join(tmp, 'backend', 'handlers'));
     await writeFile(path.join(tmp, 'backend', 'handlers', 'call_snowflake.ts'), '// placeholder');
@@ -225,7 +242,11 @@ describe('deployBackend (preview)', () => {
         deployedBy: 'test-user',
         isPreview: true,
       })
-    ).resolves.toEqual(['monday']);
+    ).resolves.toEqual({
+      integrations: ['monday'],
+      handlerNames: ['call_snowflake'],
+      apiUsages: { call_snowflake: { monday: { query: [{ query: 'x' }] } } },
+    });
     expect(mockSend).toHaveBeenCalled();
     const keys: string[] = mockSend.mock.calls.map((c: unknown[]) => (c[0] as { input: { Key: string } }).input.Key);
     expect(keys.some(k => k.includes('/MS/'))).toBe(true);

package/src/commands/__tests__/deploy.test.ts

@@ -7,7 +7,9 @@ import { deployCommand } from '../deploy';
 import { DeployError, reasonOf } from '../../util/errors';
 import { buildPreviewSlug } from '../../util/app-name';
 import { setOutputMode } from '../../util/logger';
+import * as loggerModule from '../../util/logger';
 import { buildCommand } from '../build';
+import * as backendCmd from '../backend';
 import { uploadDir } from '../../util/s3/upload';
 import { setupS3Client } from '../../util/s3/client';
 import { openInBrowser } from '../../util/open-browser';
@@ -20,6 +22,15 @@ vi.mock('../build', () => ({
   buildCommand: vi.fn(),
 }));
 
+// Wraps the real `deployBackend` so most tests exercise it unchanged (no
+// backend/handlers dir in the tmp fixture, so it resolves trivially), while
+// letting individual tests override it to prove the upload/register ordering
+// and passthrough of real handlerNames/apiUsages.
+vi.mock('../backend', async importOriginal => {
+  const actual = await importOriginal<typeof import('../backend')>();
+  return { ...actual, deployBackend: vi.fn(actual.deployBackend) };
+});
+
 vi.mock('../../util/s3/upload', () => ({
   uploadDir: vi.fn().mockResolvedValue([]),
 }));
@@ -97,6 +108,7 @@ describe('deploy --preview', () => {
         buildDir: path.join(tmp, '.zth', 'build'),
         assetManifest: ASSET_MANIFEST,
       });
+    vi.mocked(backendCmd.deployBackend).mockClear();
     vi.mocked(uploadDir).mockClear();
     vi.mocked(setupS3Client).mockClear();
     vi.mocked(openInBrowser).mockClear();
@@ -162,6 +174,8 @@ describe('deploy --preview', () => {
       entry: expect.objectContaining({ ...ASSET_MANIFEST, version: 3, gitRemote: '' }),
       gitRemote: '',
       integrations: [],
+      handlerNames: [],
+      apiUsages: {},
       masterAppName: 'mf-my-app',
     });
   });
@@ -180,6 +194,8 @@ describe('deploy --preview', () => {
       entry: expect.objectContaining({ ...ASSET_MANIFEST, version: 1, gitRemote: '' }),
       gitRemote: '',
       integrations: [],
+      handlerNames: [],
+      apiUsages: {},
       masterAppName: 'mf-my-app',
     });
   });
@@ -274,6 +290,43 @@ describe('deploy --preview', () => {
 
     writeSpy.mockRestore();
   });
+
+  it('never uploads the frontend or registers when deployBackend fails', async () => {
+    vi.mocked(backendCmd.deployBackend).mockRejectedValueOnce(new Error('backend upload exploded'));
+
+    await expect(deployCommand({ preview: true })).rejects.toThrow('backend upload exploded');
+
+    expect(uploadDir).not.toHaveBeenCalled();
+    expect(brokerApp.registerOrUpdateApp).not.toHaveBeenCalled();
+  });
+
+  it('warns that a retry will repair it when the frontend upload fails after the backend already deployed', async () => {
+    vi.mocked(uploadDir).mockRejectedValueOnce(new Error('S3 exploded'));
+    const warnSpy = vi.spyOn(loggerModule, 'warn').mockImplementation(() => {});
+
+    await expect(deployCommand({ preview: true })).rejects.toThrow('S3 exploded');
+
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('re-run "z2h-cli deploy --preview"'));
+    warnSpy.mockRestore();
+  });
+
+  it('forwards the real handlerNames and apiUsages deployBackend reports to registerOrUpdateApp', async () => {
+    vi.mocked(backendCmd.deployBackend).mockResolvedValueOnce({
+      integrations: ['snowflake'],
+      handlerNames: ['call_snowflake'],
+      apiUsages: { call_snowflake: { snowflake: { query: [{ sql: 'x' }] } } },
+    });
+
+    await deployCommand({ preview: true });
+
+    expect(brokerApp.registerOrUpdateApp).toHaveBeenCalledWith(
+      expect.objectContaining({
+        integrations: ['snowflake'],
+        handlerNames: ['call_snowflake'],
+        apiUsages: { call_snowflake: { snowflake: { query: [{ sql: 'x' }] } } },
+      })
+    );
+  });
 });
 
 describe('deploy failure reasons', () => {

package/src/commands/backend.ts

@@ -45,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,
@@ -56,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) =>
@@ -75,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
@@ -96,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}"`;

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/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