@mondaydotcomorg/z2h-cli 0.21.1 → 0.21.2

package/dist/commands/deploy.d.ts

@@ -4,7 +4,6 @@ export interface DeployOptions {
     remote?: RemoteType;
     repoUrl?: string;
     preview?: boolean;
-    previewId?: string;
     open?: boolean;
     description?: string;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAUtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAWtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E"}

package/dist/commands/deploy.js

@@ -1,7 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const os = require('node:os');
-const crypto = require('node:crypto');
 const fs = require('fs-extra');
 const util_logger = require('../util/logger.js');
 const shadow_paths = require('../shadow/paths.js');
@@ -18,6 +17,7 @@ const util_s3_client = require('../util/s3/client.js');
 const util_machineIdentity = require('../util/machine-identity.js');
 const util_broker_app = require('../util/broker/app.js');
 const util_openBrowser = require('../util/open-browser.js');
+const shadow_prepare = require('../shadow/prepare.js');
 const commands_build = require('./build.js');
 const commands_tag = require('./tag.js');
 
@@ -63,7 +63,8 @@ async function buildAndStamp(opts) {
     };
 }
 async function deployPreview({ paths, consumerName, appName, token, opts }) {
-    const previewId = opts.previewId ?? crypto.randomUUID().slice(0, 8);
+    await fs.ensureDir(paths.shadowDir);
+    const { previewId } = await shadow_prepare.resolvePortAndMetadata(paths, util_appName.cleanAppName(consumerName));
     const previewSlug = util_appName.buildPreviewSlug(consumerName, previewId);
     const previewAppName = util_appName.mfAppName(previewSlug);
     const keyPrefix = `${constants.S3_PREVIEWS_FOLDER}/${previewAppName}/MF`;
@@ -73,10 +74,12 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
     const nextVersion = (await util_auth_brokerCredentialProvider.fetchDeployVersion(previewAppName)) + 1;
     util_logger.info('building');
     const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote: '' });
+    util_logger.info('getting sts credentials');
     const creds = await util_auth_brokerCredentialProvider.brokerCredentialProvider({ appName: previewAppName, previewId })();
     util_s3_client.setupS3Client(creds);
     util_logger.info(`uploading preview build → s3://${constants.BUCKET_WRITE_NAME}/${keyPrefix}/`);
     await util_s3_upload.uploadDir(paths.shadowBuild, keyPrefix);
+    util_logger.info('updating manifest');
     await util_broker_app.registerOrUpdateApp({ appName: previewAppName, token, nextVersion, entry, gitRemote: '' });
     const previewUrl = `https://bigbrain.me/bigbrain-vibe/${previewSlug}`;
     util_logger.output(`[z2h-cli] preview ready ✅\n  app:            ${appName}\n  previewAppName: ${previewAppName}\n  open:           ${previewUrl}`, {
@@ -151,8 +154,10 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
         // Acquire the deploy lock explicitly. Done after the build
         // so the lock hold stays tiny — it wraps only push → upload → manifest.
         // A 409 here means someone else is mid-deploy;
+        util_logger.info('getting sts credentials');
         const creds = await util_auth_brokerCredentialProvider.brokerCredentialProvider({ appName })();
         util_s3_client.setupS3Client(creds);
+        util_logger.info('acquiring deploy lock');
         await acquireDeployLock(appName, token);
         // Push before any S3 write so a rejected push (someone deployed during our
         // build) stops the deploy before the bundle/manifest go live
@@ -162,9 +167,11 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
         }
         util_logger.info(`uploading build → s3://${constants.BUCKET_WRITE_NAME}/${keyPrefix}/`);
         await util_s3_upload.uploadDir(paths.shadowBuild, keyPrefix);
+        util_logger.info('updating manifest');
         await util_broker_app.registerOrUpdateApp({ appName, token, nextVersion, entry, gitRemote, description: opts.description });
     }
     finally {
+        util_logger.info('releasing deploy lock');
         await releaseLockBestEffort(appName, token);
     }
     // Tags are a post-deploy concern: the S3 upload has already succeeded, so a

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

@@ -4,7 +4,6 @@ export interface DeployOptions {
     remote?: RemoteType;
     repoUrl?: string;
     preview?: boolean;
-    previewId?: string;
     open?: boolean;
     description?: string;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAUtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAWtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E"}

package/dist/esm/commands/deploy.mjs

@@ -1,6 +1,5 @@
 import os from 'node:os';
-import { randomUUID } from 'node:crypto';
-import { readJson } from 'fs-extra';
+import { readJson, ensureDir } from 'fs-extra';
 import { info, output, getOutputMode, warn } from '../util/logger.mjs';
 import { resolveConsumerPaths } from '../shadow/paths.mjs';
 import { fetchAppTags, fetchTagCatalog, setAppTags } from '../util/tags.mjs';
@@ -16,6 +15,7 @@ import { setupS3Client } from '../util/s3/client.mjs';
 import { getMachineAppName } from '../util/machine-identity.mjs';
 import { registerOrUpdateApp } from '../util/broker/app.mjs';
 import { openInBrowser } from '../util/open-browser.mjs';
+import { resolvePortAndMetadata } from '../shadow/prepare.mjs';
 import { buildCommand } from './build.mjs';
 import { promptForTags } from './tag.mjs';
 
@@ -57,7 +57,8 @@ async function buildAndStamp(opts) {
     };
 }
 async function deployPreview({ paths, consumerName, appName, token, opts }) {
-    const previewId = opts.previewId ?? randomUUID().slice(0, 8);
+    await ensureDir(paths.shadowDir);
+    const { previewId } = await resolvePortAndMetadata(paths, cleanAppName(consumerName));
     const previewSlug = buildPreviewSlug(consumerName, previewId);
     const previewAppName = mfAppName(previewSlug);
     const keyPrefix = `${S3_PREVIEWS_FOLDER}/${previewAppName}/MF`;
@@ -67,10 +68,12 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
     const nextVersion = (await fetchDeployVersion(previewAppName)) + 1;
     info('building');
     const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote: '' });
+    info('getting sts credentials');
     const creds = await brokerCredentialProvider({ appName: previewAppName, previewId })();
     setupS3Client(creds);
     info(`uploading preview build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
     await uploadDir(paths.shadowBuild, keyPrefix);
+    info('updating manifest');
     await registerOrUpdateApp({ appName: previewAppName, token, nextVersion, entry, gitRemote: '' });
     const previewUrl = `https://bigbrain.me/bigbrain-vibe/${previewSlug}`;
     output(`[z2h-cli] preview ready ✅\n  app:            ${appName}\n  previewAppName: ${previewAppName}\n  open:           ${previewUrl}`, {
@@ -145,8 +148,10 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
         // Acquire the deploy lock explicitly. Done after the build
         // so the lock hold stays tiny — it wraps only push → upload → manifest.
         // A 409 here means someone else is mid-deploy;
+        info('getting sts credentials');
         const creds = await brokerCredentialProvider({ appName })();
         setupS3Client(creds);
+        info('acquiring deploy lock');
         await acquireDeployLock(appName, token);
         // Push before any S3 write so a rejected push (someone deployed during our
         // build) stops the deploy before the bundle/manifest go live
@@ -156,9 +161,11 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
         }
         info(`uploading build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
         await uploadDir(paths.shadowBuild, keyPrefix);
+        info('updating manifest');
         await registerOrUpdateApp({ appName, token, nextVersion, entry, gitRemote, description: opts.description });
     }
     finally {
+        info('releasing deploy lock');
         await releaseLockBestEffort(appName, token);
     }
     // Tags are a post-deploy concern: the S3 upload has already succeeded, so a

package/dist/esm/index.mjs

@@ -93,18 +93,14 @@ async function main() {
         .command('deploy')
         .description('Build, upload to S3, and register the app with the Z2H backend')
         .option('--dry-run', 'print what would happen without uploading anything')
-        .option('--preview [previewId]', 'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; pass an existing previewId to update it instead of minting a new one')
+        .option('--preview', 'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; reuses the same preview URL across runs (stable link)')
         .option('--open', 'open the resulting app/preview URL in the browser on success')
         .option('--remote <type>', 'First deploy only: source control remote to initialise — s3 (shared storage) or github (your repo). Error if the app already has a git remote.')
         .option('--repo-url <url>', 'First deploy only: GitHub repo URL — required when --remote=github. Error if the app already has a git remote.')
         .option('--description <text>', 'short (<=200 char) description of the app')
         .action(async (opts) => {
         try {
-            await trackDuration(opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success', () => deployCommand({
-                ...opts,
-                preview: Boolean(opts.preview),
-                previewId: typeof opts.preview === 'string' ? opts.preview : undefined,
-            }), {
+            await trackDuration(opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success', () => deployCommand(opts), {
                 app_name: getCwdAppName(),
             });
         }

package/dist/esm/shadow/prepare.d.ts

@@ -1,3 +1,10 @@
-import type { PreparedShadow } from '../types';
+import type { ConsumerPaths, PreparedShadow, ShadowMetadata } from '../types';
 export declare function prepareShadow(consumerDir?: string): Promise<PreparedShadow>;
+/**
+ * Resolve the dev server port. Prefer the persisted port if it's still free
+ * (URL stays stable across restarts). Otherwise pick a fresh one. The
+ * orphaned process — if there is one — keeps running on its old port,
+ * harmless. No process killing, no PID files.
+ */
+export declare function resolvePortAndMetadata(paths: ConsumerPaths, cleanAppName: string): Promise<ShadowMetadata>;
 //# sourceMappingURL=prepare.d.ts.map

package/dist/esm/shadow/prepare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../src/shadow/prepare.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,CAAC,WAAW,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChG"}
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../src/shadow/prepare.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAe,cAAc,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,CAAC,WAAW,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChG;AAMD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAoBhH"}

package/dist/esm/shadow/prepare.mjs

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { pathExists, readJson, ensureDir } from 'fs-extra';
 import { info } from '../util/logger.mjs';
 import { cleanAppName } from '../util/app-name.mjs';
@@ -35,24 +36,31 @@ async function prepareShadow(consumerDir = process.cwd()) {
     await syncShadow(paths, consumerPkg);
     return { appName, port, paths };
 }
+function generatePreviewId() {
+    return randomUUID().slice(0, 8);
+}
 /**
  * Resolve the dev server port. Prefer the persisted port if it's still free
  * (URL stays stable across restarts). Otherwise pick a fresh one. The
  * orphaned process — if there is one — keeps running on its old port,
  * harmless. No process killing, no PID files.
  */
-async function resolvePortAndMetadata(paths, appName) {
+async function resolvePortAndMetadata(paths, cleanAppName) {
     const existing = await readMetadata(paths);
-    if (existing?.port && (await isPortFree(existing.port))) {
-        return existing;
+    let port = existing?.port;
+    if (!port || !(await isPortFree(port))) {
+        port = await pickPort();
     }
     const next = {
         createdAt: existing?.createdAt ?? new Date().toISOString(),
-        appName,
-        port: await pickPort(),
+        appName: cleanAppName,
+        port,
+        previewId: existing?.previewId ?? generatePreviewId(),
     };
-    await writeMetadata(paths, next);
+    if (JSON.stringify(next) !== JSON.stringify(existing)) {
+        await writeMetadata(paths, next);
+    }
     return next;
 }
 
-export { prepareShadow };
+export { prepareShadow, resolvePortAndMetadata };

package/dist/esm/types.d.ts

@@ -26,6 +26,7 @@ export interface ShadowMetadata {
     createdAt: string;
     appName: string;
     port: number;
+    previewId: string;
 }
 export interface ConsumerPaths {
     consumerDir: string;

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAOD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAGD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAGD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAGD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAOD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAGD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAGD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;CACtB"}

package/dist/index.js

@@ -99,18 +99,14 @@ async function main() {
         .command('deploy')
         .description('Build, upload to S3, and register the app with the Z2H backend')
         .option('--dry-run', 'print what would happen without uploading anything')
-        .option('--preview [previewId]', 'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; pass an existing previewId to update it instead of minting a new one')
+        .option('--preview', 'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; reuses the same preview URL across runs (stable link)')
         .option('--open', 'open the resulting app/preview URL in the browser on success')
         .option('--remote <type>', 'First deploy only: source control remote to initialise — s3 (shared storage) or github (your repo). Error if the app already has a git remote.')
         .option('--repo-url <url>', 'First deploy only: GitHub repo URL — required when --remote=github. Error if the app already has a git remote.')
         .option('--description <text>', 'short (<=200 char) description of the app')
         .action(async (opts) => {
         try {
-            await util_tracker.trackDuration(opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success', () => commands_deploy.deployCommand({
-                ...opts,
-                preview: Boolean(opts.preview),
-                previewId: typeof opts.preview === 'string' ? opts.preview : undefined,
-            }), {
+            await util_tracker.trackDuration(opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success', () => commands_deploy.deployCommand(opts), {
                 app_name: util_appName.getCwdAppName(),
             });
         }

package/dist/shadow/prepare.d.ts

@@ -1,3 +1,10 @@
-import type { PreparedShadow } from '../types';
+import type { ConsumerPaths, PreparedShadow, ShadowMetadata } from '../types';
 export declare function prepareShadow(consumerDir?: string): Promise<PreparedShadow>;
+/**
+ * Resolve the dev server port. Prefer the persisted port if it's still free
+ * (URL stays stable across restarts). Otherwise pick a fresh one. The
+ * orphaned process — if there is one — keeps running on its old port,
+ * harmless. No process killing, no PID files.
+ */
+export declare function resolvePortAndMetadata(paths: ConsumerPaths, cleanAppName: string): Promise<ShadowMetadata>;
 //# sourceMappingURL=prepare.d.ts.map

package/dist/shadow/prepare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../src/shadow/prepare.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,CAAC,WAAW,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChG"}
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../src/shadow/prepare.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAe,cAAc,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,CAAC,WAAW,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChG;AAMD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAoBhH"}

package/dist/shadow/prepare.js

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
+const crypto = require('node:crypto');
 const fs = require('fs-extra');
 const util_logger = require('../util/logger.js');
 const util_appName = require('../util/app-name.js');
@@ -37,24 +38,32 @@ async function prepareShadow(consumerDir = process.cwd()) {
     await shadow_sync.syncShadow(paths, consumerPkg);
     return { appName, port, paths };
 }
+function generatePreviewId() {
+    return crypto.randomUUID().slice(0, 8);
+}
 /**
  * Resolve the dev server port. Prefer the persisted port if it's still free
  * (URL stays stable across restarts). Otherwise pick a fresh one. The
  * orphaned process — if there is one — keeps running on its old port,
  * harmless. No process killing, no PID files.
  */
-async function resolvePortAndMetadata(paths, appName) {
+async function resolvePortAndMetadata(paths, cleanAppName) {
     const existing = await shadow_metadata.readMetadata(paths);
-    if (existing?.port && (await shadow_port.isPortFree(existing.port))) {
-        return existing;
+    let port = existing?.port;
+    if (!port || !(await shadow_port.isPortFree(port))) {
+        port = await shadow_port.pickPort();
     }
     const next = {
         createdAt: existing?.createdAt ?? new Date().toISOString(),
-        appName,
-        port: await shadow_port.pickPort(),
+        appName: cleanAppName,
+        port,
+        previewId: existing?.previewId ?? generatePreviewId(),
     };
-    await shadow_metadata.writeMetadata(paths, next);
+    if (JSON.stringify(next) !== JSON.stringify(existing)) {
+        await shadow_metadata.writeMetadata(paths, next);
+    }
     return next;
 }
 
 exports.prepareShadow = prepareShadow;
+exports.resolvePortAndMetadata = resolvePortAndMetadata;

package/dist/types.d.ts

@@ -26,6 +26,7 @@ export interface ShadowMetadata {
     createdAt: string;
     appName: string;
     port: number;
+    previewId: string;
 }
 export interface ConsumerPaths {
     consumerDir: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAOD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAGD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAGD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAGD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAOD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAGD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAGD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;CACtB"}

package/package.json

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

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

@@ -57,6 +57,8 @@ const ASSET_MANIFEST = {
   entrypoints: ['main.js'],
 };
 
+const STUB_PREVIEW_ID = 'existing-preview-id' as const;
+
 describe('deploy --preview', () => {
   let tmp: string;
   let cwd: string;
@@ -99,6 +101,14 @@ describe('deploy --preview', () => {
     await rm(tmp, { recursive: true, force: true });
   });
 
+  const writeMetadata = (previewId: string) =>
+    writeJson(path.join(tmp, '.zth', 'metadata.json'), {
+      createdAt: '2026-01-01T00:00:00.000Z',
+      appName: 'my-app',
+      port: 13000,
+      previewId,
+    });
+
   it('throws when the consumer package.json has no name', async () => {
     await writeJson(path.join(tmp, 'package.json'), {});
     await expect(deployCommand({ preview: true })).rejects.toThrow(/must have a "name" field/);
@@ -118,49 +128,48 @@ describe('deploy --preview', () => {
     expect(uploadDir).toHaveBeenCalledWith(path.join(tmp, '.zth', 'build'), `previews/${previewAppName}/MF`);
   });
 
-  it('calls registerOrUpdateApp for a brand-new preview at version 1 with an empty gitRemote', async () => {
-    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(0);
+  it('reuses the sticky previewId from metadata', async () => {
+    await writeMetadata(STUB_PREVIEW_ID);
+    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(2);
 
-    await deployCommand({ preview: true, previewId: 'existing-preview-id' });
+    await deployCommand({ preview: true });
 
-    const previewSlug = buildPreviewSlug('my-app', 'existing-preview-id');
-    const previewAppName = `mf-${previewSlug}`;
+    const call = vi.mocked(brokerProvider.brokerCredentialProvider).mock.calls[0][0];
+    expect(call.previewId).toBe(STUB_PREVIEW_ID);
+
+    const previewAppName = `mf-${buildPreviewSlug('my-app', STUB_PREVIEW_ID)}`;
+    expect(uploadDir).toHaveBeenCalledWith(path.join(tmp, '.zth', 'build'), `previews/${previewAppName}/MF`);
 
     expect(brokerApp.registerOrUpdateApp).toHaveBeenCalledWith({
       appName: previewAppName,
       token: 'jwt-stub',
-      nextVersion: 1,
-      entry: expect.objectContaining({ ...ASSET_MANIFEST, version: 1, gitRemote: '' }),
+      nextVersion: 3,
+      entry: expect.objectContaining({ ...ASSET_MANIFEST, version: 3, gitRemote: '' }),
       gitRemote: '',
     });
   });
 
-  it('reuses a supplied previewId and calls registerOrUpdateApp at version+1', async () => {
-    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(2);
-
-    await deployCommand({ preview: true, previewId: 'existing-preview-id' });
-
-    const call = vi.mocked(brokerProvider.brokerCredentialProvider).mock.calls[0][0];
-    expect(call.previewId).toBe('existing-preview-id');
-
-    const previewSlug = buildPreviewSlug('my-app', 'existing-preview-id');
-    const previewAppName = `mf-${previewSlug}`;
+  it('calls registerOrUpdateApp for a brand-new preview at version 1 with an empty gitRemote', async () => {
+    await writeMetadata(STUB_PREVIEW_ID);
+    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(0);
 
-    expect(uploadDir).toHaveBeenCalledWith(path.join(tmp, '.zth', 'build'), `previews/${previewAppName}/MF`);
+    await deployCommand({ preview: true });
 
+    const previewAppName = `mf-${buildPreviewSlug('my-app', STUB_PREVIEW_ID)}`;
     expect(brokerApp.registerOrUpdateApp).toHaveBeenCalledWith({
       appName: previewAppName,
       token: 'jwt-stub',
-      nextVersion: 3,
-      entry: expect.objectContaining({ ...ASSET_MANIFEST, version: 3, gitRemote: '' }),
+      nextVersion: 1,
+      entry: expect.objectContaining({ ...ASSET_MANIFEST, version: 1, gitRemote: '' }),
       gitRemote: '',
     });
   });
 
   it('passes a full CDN URL (not a relative path) as publicUrl to the build', async () => {
-    await deployCommand({ preview: true, previewId: 'existing-preview-id' });
+    await writeMetadata(STUB_PREVIEW_ID);
+    await deployCommand({ preview: true });
 
-    const previewAppName = `mf-${buildPreviewSlug('my-app', 'existing-preview-id')}`;
+    const previewAppName = `mf-${buildPreviewSlug('my-app', STUB_PREVIEW_ID)}`;
     expect(buildCommand).toHaveBeenCalledWith(
       expect.objectContaining({
         publicUrl: `https://bigbrain-zth-mf-assets.bigbrain.me/previews/${previewAppName}/MF`,
@@ -178,9 +187,10 @@ describe('deploy --preview', () => {
   });
 
   it('--open opens the previewUrl in the browser on success', async () => {
-    await deployCommand({ preview: true, previewId: 'existing-preview-id', open: true });
+    await writeMetadata(STUB_PREVIEW_ID);
+    await deployCommand({ preview: true, open: true });
 
-    const previewSlug = buildPreviewSlug('my-app', 'existing-preview-id');
+    const previewSlug = buildPreviewSlug('my-app', STUB_PREVIEW_ID);
     expect(openInBrowser).toHaveBeenCalledWith(`https://bigbrain.me/bigbrain-vibe/${previewSlug}`);
   });
 
@@ -195,19 +205,20 @@ describe('deploy --preview', () => {
   });
 
   it('--json emits a machine-readable payload with an app-shaped previewUrl (not ?z2h_preview=)', async () => {
+    await writeMetadata(STUB_PREVIEW_ID);
     const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
     setOutputMode('json');
 
-    await deployCommand({ preview: true, previewId: 'existing-preview-id' });
+    await deployCommand({ preview: true });
 
     const jsonLine = writeSpy.mock.calls.map(c => c[0]).find(line => typeof line === 'string' && line.includes('"ok"'));
     expect(jsonLine).toBeDefined();
     const payload = JSON.parse(jsonLine as string);
-    const previewSlug = buildPreviewSlug('my-app', 'existing-preview-id');
+    const previewSlug = buildPreviewSlug('my-app', STUB_PREVIEW_ID);
     expect(payload).toMatchObject({
       ok: true,
       appName: 'mf-my-app',
-      previewId: 'existing-preview-id',
+      previewId: STUB_PREVIEW_ID,
       previewAppName: `mf-${previewSlug}`,
       previewUrl: `https://bigbrain.me/bigbrain-vibe/${previewSlug}`,
     });

package/src/commands/deploy.ts

@@ -1,6 +1,5 @@
 import os from 'node:os';
-import { randomUUID } from 'node:crypto';
-import { readJson } from 'fs-extra';
+import { ensureDir, readJson } from 'fs-extra';
 import { info, warn, output, getOutputMode } from '../util/logger';
 import { resolveConsumerPaths } from '../shadow/paths';
 import { fetchAppTags, fetchTagCatalog, setAppTags } from '../util/tags';
@@ -22,6 +21,7 @@ import { setupS3Client } from '../util/s3/client';
 import { getMachineAppName } from '../util/machine-identity';
 import { registerOrUpdateApp } from '../util/broker/app';
 import { openInBrowser } from '../util/open-browser';
+import { resolvePortAndMetadata } from '../shadow/prepare';
 import { buildCommand } from './build';
 import { promptForTags } from './tag';
 import type { ConsumerPaths } from '../types';
@@ -31,11 +31,8 @@ export interface DeployOptions {
   dryRun?: boolean;
   remote?: RemoteType;
   repoUrl?: string;
-  // Registers a real, disposable `apps` row under a synthetic name instead of
-  // deploying — no git, no deploy lock (each previewId's slug is unique).
+  // Registers a real, disposable `apps` row under a synthetic name instead of deploying as a live app
   preview?: boolean;
-  // With --preview: update an existing preview instead of minting a new one.
-  previewId?: string;
   open?: boolean;
   description?: string;
 }
@@ -96,7 +93,9 @@ async function buildAndStamp(opts: {
 }
 
 async function deployPreview({ paths, consumerName, appName, token, opts }: DeployContext): Promise<void> {
-  const previewId = opts.previewId ?? randomUUID().slice(0, 8);
+  await ensureDir(paths.shadowDir);
+  const { previewId } = await resolvePortAndMetadata(paths, cleanAppName(consumerName));
+
   const previewSlug = buildPreviewSlug(consumerName, previewId);
   const previewAppName = mfAppName(previewSlug);
   const keyPrefix = `${S3_PREVIEWS_FOLDER}/${previewAppName}/MF`;
@@ -109,12 +108,14 @@ async function deployPreview({ paths, consumerName, appName, token, opts }: Depl
   info('building');
   const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote: '' });
 
+  info('getting sts credentials');
   const creds = await brokerCredentialProvider({ appName: previewAppName, previewId })();
   setupS3Client(creds);
 
   info(`uploading preview build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
   await uploadDir(paths.shadowBuild, keyPrefix);
 
+  info('updating manifest');
   await registerOrUpdateApp({ appName: previewAppName, token, nextVersion, entry, gitRemote: '' });
 
   const previewUrl = `https://bigbrain.me/bigbrain-vibe/${previewSlug}`;
@@ -206,8 +207,10 @@ async function deployLive({ paths, consumerName, appName, token, opts }: DeployC
     // Acquire the deploy lock explicitly. Done after the build
     // so the lock hold stays tiny — it wraps only push → upload → manifest.
     // A 409 here means someone else is mid-deploy;
+    info('getting sts credentials');
     const creds = await brokerCredentialProvider({ appName })();
     setupS3Client(creds);
+    info('acquiring deploy lock');
     await acquireDeployLock(appName, token);
 
     // Push before any S3 write so a rejected push (someone deployed during our
@@ -220,8 +223,10 @@ async function deployLive({ paths, consumerName, appName, token, opts }: DeployC
     info(`uploading build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
     await uploadDir(paths.shadowBuild, keyPrefix);
 
+    info('updating manifest');
     await registerOrUpdateApp({ appName, token, nextVersion, entry, gitRemote, description: opts.description });
   } finally {
+    info('releasing deploy lock');
     await releaseLockBestEffort(appName, token);
   }
 

package/src/index.ts

@@ -103,8 +103,8 @@ async function main(): Promise<void> {
     .description('Build, upload to S3, and register the app with the Z2H backend')
     .option('--dry-run', 'print what would happen without uploading anything')
     .option(
-      '--preview [previewId]',
-      'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; pass an existing previewId to update it instead of minting a new one'
+      '--preview',
+      'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; reuses the same preview URL across runs (stable link)'
     )
     .option('--open', 'open the resulting app/preview URL in the browser on success')
     .option(
@@ -128,12 +128,7 @@ async function main(): Promise<void> {
         try {
           await trackDuration(
             opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success',
-            () =>
-              deployCommand({
-                ...opts,
-                preview: Boolean(opts.preview),
-                previewId: typeof opts.preview === 'string' ? opts.preview : undefined,
-              } as Parameters<typeof deployCommand>[0]),
+            () => deployCommand(opts as Parameters<typeof deployCommand>[0]),
             {
               app_name: getCwdAppName(),
             }

package/src/shadow/prepare.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { ensureDir, pathExists, readJson } from 'fs-extra';
 import { info } from '../util/logger';
 import { cleanAppName } from '../util/app-name';
@@ -44,23 +45,34 @@ export async function prepareShadow(consumerDir: string = process.cwd()): Promis
   return { appName, port, paths };
 }
 
+function generatePreviewId(): string {
+  return randomUUID().slice(0, 8);
+}
+
 /**
  * Resolve the dev server port. Prefer the persisted port if it's still free
  * (URL stays stable across restarts). Otherwise pick a fresh one. The
  * orphaned process — if there is one — keeps running on its old port,
  * harmless. No process killing, no PID files.
  */
-async function resolvePortAndMetadata(paths: ConsumerPaths, appName: string): Promise<ShadowMetadata> {
+export async function resolvePortAndMetadata(paths: ConsumerPaths, cleanAppName: string): Promise<ShadowMetadata> {
   const existing = await readMetadata(paths);
-  if (existing?.port && (await isPortFree(existing.port))) {
-    return existing;
+
+  let port = existing?.port;
+  if (!port || !(await isPortFree(port))) {
+    port = await pickPort();
   }
 
   const next: ShadowMetadata = {
     createdAt: existing?.createdAt ?? new Date().toISOString(),
-    appName,
-    port: await pickPort(),
+    appName: cleanAppName,
+    port,
+    previewId: existing?.previewId ?? generatePreviewId(),
   };
-  await writeMetadata(paths, next);
+
+  if (JSON.stringify(next) !== JSON.stringify(existing)) {
+    await writeMetadata(paths, next);
+  }
+
   return next;
 }

package/src/types.ts

@@ -34,6 +34,7 @@ export interface ShadowMetadata {
   createdAt: string;
   appName: string;
   port: number;
+  previewId: string;
 }
 
 // ─────────── Filesystem paths, resolved once per invocation ─────