@mondaydotcomorg/z2h-cli 0.28.0 → 0.29.0

package/dist/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/commands/create.js

@@ -58,11 +58,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 util_broker_app.fetchApp(util_appName.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 = util_git_remoteOptions.resolveRemoteUrl(opts.remote, appName, opts.repoUrl);
+    if (!existing) {
+        await util_broker_app.claimApp(util_appName.mfAppName(appName), gitRemote);
+    }
     // Compute substitutions.
     const vars = {
         __APP_NAME__: appName,
@@ -87,7 +95,6 @@ async function createCommand(appName, opts = {}) {
         await fs.copy(opts.htmlFile, path__default.default.join(appDir, 'src', 'page.html'));
     }
     util_logger.info(`initializing git repo for ${appName}...`);
-    const gitRemote = util_git_remoteOptions.resolveRemoteUrl(opts.remote, appName, opts.repoUrl);
     await util_git_repo.initRepo(appDir, gitRemote);
     util_logger.info(`installing dependencies for ${appName}...`);
     await util_npm_install.runYarnInstall({ cwd: workspace });

package/dist/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/commands/generate.js

@@ -136,8 +136,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 util_broker_app.fetchApp(util_appName.mfAppName(appName));
-    if (existing) {
+    if (existing?.deployed) {
         throw new Error(`An app named "${appName}" already exists in the Z2H registry. Pick a different name.`);
     }
     util_logger.info(`copying template "${template.id}" → ${appDir}`);

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/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/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.28.0",
+  "version": "0.29.0",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

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

@@ -6,6 +6,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { runYarnInstall } from '../../util/npm/install';
 import { initRepo, defaultS3Remote } from '../../util/git/repo';
 import { prepareShadow } from '../../shadow/prepare';
+import { fetchApp, claimApp } from '../../util/broker/app';
 import { createCommand } from '../create';
 
 // Mock the install helper so `yarn install` (with its broker preflight) doesn't
@@ -28,6 +29,7 @@ vi.mock('../../shadow/prepare', () => ({
 // Mock broker app lookup — no token needed in tests; default to null (app does not exist).
 vi.mock('../../util/broker/app', () => ({
   fetchApp: vi.fn().mockResolvedValue(null),
+  claimApp: vi.fn().mockResolvedValue(undefined),
 }));
 
 async function makeWorkspace(tmp: string): Promise<void> {
@@ -50,6 +52,8 @@ describe('create', () => {
     vi.mocked(initRepo).mockClear();
     vi.mocked(defaultS3Remote).mockClear();
     vi.mocked(prepareShadow).mockClear();
+    vi.mocked(fetchApp).mockReset().mockResolvedValue(null);
+    vi.mocked(claimApp).mockReset().mockResolvedValue(undefined);
   });
 
   afterEach(async () => {
@@ -162,4 +166,46 @@ describe('create', () => {
     await createCommand('gh-app', { remote: 'github', repoUrl: 'https://github.com/acme/gh-app' });
     expect(vi.mocked(initRepo)).toHaveBeenCalledWith(path.join(tmp, 'gh-app'), 'https://github.com/acme/gh-app');
   });
+
+  it('claims the app name with the resolved gitRemote when the name is genuinely free', async () => {
+    await makeWorkspace(tmp);
+    await createCommand('my-app', { remote: 's3' });
+    expect(vi.mocked(claimApp)).toHaveBeenCalledWith(
+      'mf-my-app',
+      's3://prod-use1-bigbrain-zth-mf-assets/mf-my-app/git'
+    );
+  });
+
+  it('throws when the app already has a real release', async () => {
+    await makeWorkspace(tmp);
+    vi.mocked(fetchApp).mockResolvedValue({
+      appName: 'mf-demo-app',
+      version: 1,
+      entry: { version: 1, url: 'https://cdn/demo-app/1/' },
+      deployed: true,
+      deployedBy: 'x@x.com',
+      gitRemote: 's3://bucket/demo-app/git',
+      createdBy: 'x@x.com',
+    });
+    await expect(createCommand('demo-app', { remote: 's3' })).rejects.toThrow(/already exists/);
+    expect(claimApp).not.toHaveBeenCalled();
+  });
+
+  it('proceeds without re-claiming when the app was already claimed but never published', async () => {
+    await makeWorkspace(tmp);
+    vi.mocked(fetchApp).mockResolvedValue({
+      appName: 'mf-demo-app',
+      version: 0,
+      entry: null,
+      deployed: false,
+      deployedBy: 'x@x.com',
+      gitRemote: 's3://bucket/demo-app/git-claim',
+      createdBy: 'x@x.com',
+    });
+
+    await createCommand('demo-app', { remote: 's3' });
+
+    expect(claimApp).not.toHaveBeenCalled();
+    expect(await pathExists(path.join(tmp, 'demo-app', 'package.json'))).toBe(true);
+  });
 });

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

@@ -78,6 +78,7 @@ describe('edit', () => {
       version: 3,
       gitRemote: S3_REMOTE,
       entry: {},
+      deployed: true,
       deployedBy: 'u@x.com',
       createdBy: 'u@x.com',
     });
@@ -100,6 +101,7 @@ describe('edit', () => {
       version: 3,
       gitRemote: S3_REMOTE,
       entry: {},
+      deployed: true,
       deployedBy: 'u@x.com',
       createdBy: 'u@x.com',
     });
@@ -117,6 +119,7 @@ describe('edit', () => {
       version: 3,
       gitRemote: S3_REMOTE,
       entry: {},
+      deployed: true,
       deployedBy: 'u@x.com',
       createdBy: 'u@x.com',
     });
@@ -134,6 +137,7 @@ describe('edit', () => {
       version: 3,
       gitRemote: GITHUB_REMOTE,
       entry: {},
+      deployed: true,
       deployedBy: 'u@x.com',
       createdBy: 'u@x.com',
     });
@@ -151,6 +155,7 @@ describe('edit', () => {
       version: 3,
       gitRemote: S3_REMOTE,
       entry: {},
+      deployed: true,
       deployedBy: 'u@x.com',
       createdBy: 'u@x.com',
     });
@@ -172,6 +177,7 @@ describe('edit', () => {
       version: 3,
       gitRemote: S3_REMOTE,
       entry: {},
+      deployed: true,
       deployedBy: 'u@x.com',
       createdBy: 'u@x.com',
     });

package/src/commands/create.ts

@@ -7,7 +7,7 @@ import { getTemplatesDir, renderTemplate, APP_TEMPLATES, type AppTemplate } from
 import { runYarnInstall } from '../util/npm/install';
 import { initRepo } from '../util/git/repo';
 import { REMOTE_TYPES, type RemoteType, validateRemoteOptions, resolveRemoteUrl } from '../util/git/remote-options';
-import { fetchApp } from '../util/broker/app';
+import { fetchApp, claimApp } from '../util/broker/app';
 import { mfAppName, validateAppName } from '../util/app-name';
 import { prepareShadow } from '../shadow/prepare';
 
@@ -69,12 +69,22 @@ export async function createCommand(appName: string, opts: CreateOptions = {}):
     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 as RemoteType, appName, opts.repoUrl);
+
+  if (!existing) {
+    await claimApp(mfAppName(appName), gitRemote);
+  }
+
   // Compute substitutions.
   const vars = {
     __APP_NAME__: appName,
@@ -105,7 +115,6 @@ export async function createCommand(appName: string, opts: CreateOptions = {}):
   }
 
   info(`initializing git repo for ${appName}...`);
-  const gitRemote = resolveRemoteUrl(opts.remote as RemoteType, appName, opts.repoUrl);
   await initRepo(appDir, gitRemote);
 
   info(`installing dependencies for ${appName}...`);

package/src/commands/generate.ts

@@ -157,8 +157,9 @@ export async function generateCommand(appName: string, opts: GenerateOptions): P
     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.`);
   }
 

package/src/util/broker/__tests__/app.test.ts

@@ -1,9 +1,12 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { registerOrUpdateApp } from '../app';
+import { registerOrUpdateApp, claimApp } from '../app';
 import * as promptVisibility from '../../prompt-visibility';
 import { DeployError } from '../../errors';
+import * as authStore from '../../auth/auth-store';
 import type { ManifestEntry } from '../../manifest';
 
+vi.spyOn(authStore, 'readZthAuth').mockResolvedValue({ token: 'jwt-stub' });
+
 vi.mock('../../prompt-visibility', () => ({
   resolveAppVisibility: vi.fn(),
 }));
@@ -105,3 +108,28 @@ describe('registerOrUpdateApp', () => {
     expect((err as DeployError).reason).toBe('register_error');
   });
 });
+
+describe('claimApp', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('posts the app name and gitRemote to the claim endpoint', async () => {
+    const fetchMock = mockFetchOnce(204);
+
+    await claimApp('mf-my-app', 's3://bucket/mf-my-app/git');
+
+    const [calledUrl, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(calledUrl).toContain('/z2h-cli/apps/claim');
+    expect(JSON.parse(init.body as string)).toEqual({
+      appName: 'mf-my-app',
+      gitRemote: 's3://bucket/mf-my-app/git',
+    });
+  });
+
+  it('propagates a claim failure', async () => {
+    mockFetchOnce(409);
+
+    await expect(claimApp('mf-my-app', 's3://bucket/mf-my-app/git')).rejects.toThrow(/Claiming app name failed/);
+  });
+});

package/src/util/broker/app.ts

@@ -8,7 +8,10 @@ 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;
@@ -16,7 +19,7 @@ export interface AppInfo {
 
 /**
  * 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 async function fetchApp(appName: string): Promise<AppInfo | null> {
   const { token } = await readZthAuth();
@@ -42,6 +45,25 @@ export async function fetchApp(appName: string): Promise<AppInfo | null> {
   return res.json() as Promise<AppInfo>;
 }
 
+/**
+ * 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 async function claimApp(appName: string, gitRemote: string): Promise<void> {
+  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: string,
   token: string,