@mondaydotcomorg/z2h-cli 0.19.0-feat-arielle-fixed-preview-id-d22bd88 → 0.19.0

package/dist/commands/deploy.d.ts

@@ -4,7 +4,7 @@ export interface DeployOptions {
     remote?: RemoteType;
     repoUrl?: string;
     preview?: boolean;
-    snapshot?: boolean;
+    previewId?: string;
     open?: boolean;
 }
 export declare function deployCommand(opts?: DeployOptions): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAYtG,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,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;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":"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;CAChB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E"}

package/dist/commands/deploy.js

@@ -1,6 +1,7 @@
 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');
@@ -17,8 +18,6 @@ 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_metadata = require('../shadow/metadata.js');
-const shadow_prepare = require('../shadow/prepare.js');
 const commands_build = require('./build.js');
 const commands_tag = require('./tag.js');
 
@@ -64,13 +63,7 @@ async function buildAndStamp(opts) {
     };
 }
 async function deployPreview({ paths, consumerName, appName, token, opts }) {
-    const meta = await shadow_metadata.readMetadata(paths);
-    const previewId = opts.snapshot ? shadow_prepare.generatePreviewId() : (meta?.previewId ?? shadow_prepare.generatePreviewId());
-    // Pre-stamp so prepareShadow (called inside buildAndStamp) preserves our previewId.
-    // Only possible when metadata already exists — otherwise prepareShadow creates it fresh.
-    if (!opts.snapshot && meta && meta.previewId !== previewId) {
-        await shadow_metadata.writeMetadata(paths, { ...meta, previewId });
-    }
+    const previewId = opts.previewId ?? crypto.randomUUID().slice(0, 8);
     const previewSlug = util_appName.buildPreviewSlug(consumerName, previewId);
     const previewAppName = util_appName.mfAppName(previewSlug);
     const keyPrefix = `${constants.S3_PREVIEWS_FOLDER}/${previewAppName}/MF`;
@@ -80,14 +73,6 @@ 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: '' });
-    // Post-stamp: if metadata didn't exist before build, prepareShadow created it with
-    // its own previewId. Overwrite with ours so subsequent runs reuse the same URL.
-    if (!opts.snapshot) {
-        const freshMeta = await shadow_metadata.readMetadata(paths);
-        if (freshMeta && freshMeta.previewId !== previewId) {
-            await shadow_metadata.writeMetadata(paths, { ...freshMeta, previewId });
-        }
-    }
     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}/`);

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

@@ -4,7 +4,7 @@ export interface DeployOptions {
     remote?: RemoteType;
     repoUrl?: string;
     preview?: boolean;
-    snapshot?: boolean;
+    previewId?: string;
     open?: boolean;
 }
 export declare function deployCommand(opts?: DeployOptions): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAYtG,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,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;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":"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;CAChB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E"}

package/dist/esm/commands/deploy.mjs

@@ -1,4 +1,5 @@
 import os from 'node:os';
+import { randomUUID } from 'node:crypto';
 import { readJson } from 'fs-extra';
 import { info, output, getOutputMode, warn } from '../util/logger.mjs';
 import { resolveConsumerPaths } from '../shadow/paths.mjs';
@@ -15,8 +16,6 @@ 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 { readMetadata, writeMetadata } from '../shadow/metadata.mjs';
-import { generatePreviewId } from '../shadow/prepare.mjs';
 import { buildCommand } from './build.mjs';
 import { promptForTags } from './tag.mjs';
 
@@ -58,13 +57,7 @@ async function buildAndStamp(opts) {
     };
 }
 async function deployPreview({ paths, consumerName, appName, token, opts }) {
-    const meta = await readMetadata(paths);
-    const previewId = opts.snapshot ? generatePreviewId() : (meta?.previewId ?? generatePreviewId());
-    // Pre-stamp so prepareShadow (called inside buildAndStamp) preserves our previewId.
-    // Only possible when metadata already exists — otherwise prepareShadow creates it fresh.
-    if (!opts.snapshot && meta && meta.previewId !== previewId) {
-        await writeMetadata(paths, { ...meta, previewId });
-    }
+    const previewId = opts.previewId ?? randomUUID().slice(0, 8);
     const previewSlug = buildPreviewSlug(consumerName, previewId);
     const previewAppName = mfAppName(previewSlug);
     const keyPrefix = `${S3_PREVIEWS_FOLDER}/${previewAppName}/MF`;
@@ -74,14 +67,6 @@ 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: '' });
-    // Post-stamp: if metadata didn't exist before build, prepareShadow created it with
-    // its own previewId. Overwrite with ours so subsequent runs reuse the same URL.
-    if (!opts.snapshot) {
-        const freshMeta = await readMetadata(paths);
-        if (freshMeta && freshMeta.previewId !== previewId) {
-            await writeMetadata(paths, { ...freshMeta, previewId });
-        }
-    }
     const creds = await brokerCredentialProvider({ appName: previewAppName, previewId })();
     setupS3Client(creds);
     info(`uploading preview build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);

package/dist/esm/index.mjs

@@ -93,14 +93,17 @@ 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', '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('--snapshot', 'with --preview: deploy to a fresh previewId without touching the sticky URL — produces a permanent point-in-time link')
+        .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('--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.')
         .action(async (opts) => {
         try {
-            await trackDuration(opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success', () => deployCommand(opts), {
+            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,
+            }), {
                 app_name: getCwdAppName(),
             });
         }

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

@@ -1,4 +1,3 @@
 import type { PreparedShadow } from '../types';
 export declare function prepareShadow(consumerDir?: string): Promise<PreparedShadow>;
-export declare function generatePreviewId(): string;
 //# 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":"AAWA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,CAAC,WAAW,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChG;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}
+{"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"}

package/dist/esm/shadow/prepare.mjs

@@ -1,4 +1,3 @@
-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';
@@ -36,9 +35,6 @@ 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
@@ -47,20 +43,16 @@ function generatePreviewId() {
  */
 async function resolvePortAndMetadata(paths, appName) {
     const existing = await readMetadata(paths);
-    let port = existing?.port;
-    if (!port || !(await isPortFree(port))) {
-        port = await pickPort();
+    if (existing?.port && (await isPortFree(existing.port))) {
+        return existing;
     }
     const next = {
         createdAt: existing?.createdAt ?? new Date().toISOString(),
         appName,
-        port,
-        previewId: existing?.previewId ?? generatePreviewId(),
+        port: await pickPort(),
     };
-    if (JSON.stringify(next) !== JSON.stringify(existing)) {
-        await writeMetadata(paths, next);
-    }
+    await writeMetadata(paths, next);
     return next;
 }
 
-export { generatePreviewId, prepareShadow };
+export { prepareShadow };

package/dist/esm/types.d.ts

@@ -26,7 +26,6 @@ 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;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"}
+{"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"}

package/dist/index.js

@@ -99,14 +99,17 @@ 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', '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('--snapshot', 'with --preview: deploy to a fresh previewId without touching the sticky URL — produces a permanent point-in-time link')
+        .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('--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.')
         .action(async (opts) => {
         try {
-            await util_tracker.trackDuration(opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success', () => commands_deploy.deployCommand(opts), {
+            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,
+            }), {
                 app_name: util_appName.getCwdAppName(),
             });
         }

package/dist/shadow/prepare.d.ts

@@ -1,4 +1,3 @@
 import type { PreparedShadow } from '../types';
 export declare function prepareShadow(consumerDir?: string): Promise<PreparedShadow>;
-export declare function generatePreviewId(): string;
 //# 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":"AAWA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,CAAC,WAAW,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChG;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}
+{"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"}

package/dist/shadow/prepare.js

@@ -1,6 +1,5 @@
 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');
@@ -38,9 +37,6 @@ 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
@@ -49,21 +45,16 @@ function generatePreviewId() {
  */
 async function resolvePortAndMetadata(paths, appName) {
     const existing = await shadow_metadata.readMetadata(paths);
-    let port = existing?.port;
-    if (!port || !(await shadow_port.isPortFree(port))) {
-        port = await shadow_port.pickPort();
+    if (existing?.port && (await shadow_port.isPortFree(existing.port))) {
+        return existing;
     }
     const next = {
         createdAt: existing?.createdAt ?? new Date().toISOString(),
         appName,
-        port,
-        previewId: existing?.previewId ?? generatePreviewId(),
+        port: await shadow_port.pickPort(),
     };
-    if (JSON.stringify(next) !== JSON.stringify(existing)) {
-        await shadow_metadata.writeMetadata(paths, next);
-    }
+    await shadow_metadata.writeMetadata(paths, next);
     return next;
 }
 
-exports.generatePreviewId = generatePreviewId;
 exports.prepareShadow = prepareShadow;

package/dist/types.d.ts

@@ -26,7 +26,6 @@ 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;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"}
+{"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.19.0-feat-arielle-fixed-preview-id-d22bd88",
+  "version": "0.19.0",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

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

@@ -57,8 +57,6 @@ const ASSET_MANIFEST = {
   entrypoints: ['main.js'],
 };
 
-const STUB_PREVIEW_ID = 'existing-preview-id' as const;
-
 describe('deploy --preview', () => {
   let tmp: string;
   let cwd: string;
@@ -101,14 +99,6 @@ 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/);
@@ -128,58 +118,49 @@ describe('deploy --preview', () => {
     expect(uploadDir).toHaveBeenCalledWith(path.join(tmp, '.zth', 'build'), `previews/${previewAppName}/MF`);
   });
 
-  it('reuses the sticky previewId from metadata', async () => {
-    await writeMetadata(STUB_PREVIEW_ID);
-    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(2);
-
-    await deployCommand({ preview: true });
+  it('calls registerOrUpdateApp for a brand-new preview at version 1 with an empty gitRemote', async () => {
+    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(0);
 
-    const call = vi.mocked(brokerProvider.brokerCredentialProvider).mock.calls[0][0];
-    expect(call.previewId).toBe(STUB_PREVIEW_ID);
+    await deployCommand({ preview: true, previewId: 'existing-preview-id' });
 
-    const previewAppName = `mf-${buildPreviewSlug('my-app', STUB_PREVIEW_ID)}`;
-    expect(uploadDir).toHaveBeenCalledWith(path.join(tmp, '.zth', 'build'), `previews/${previewAppName}/MF`);
+    const previewSlug = buildPreviewSlug('my-app', 'existing-preview-id');
+    const previewAppName = `mf-${previewSlug}`;
 
     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('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);
+  it('reuses a supplied previewId and calls registerOrUpdateApp at version+1', async () => {
+    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(2);
 
-    await deployCommand({ preview: true });
+    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}`;
+
+    expect(uploadDir).toHaveBeenCalledWith(path.join(tmp, '.zth', 'build'), `previews/${previewAppName}/MF`);
 
-    const previewAppName = `mf-${buildPreviewSlug('my-app', STUB_PREVIEW_ID)}`;
     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('--snapshot mints a fresh previewId even when metadata has an existing one', async () => {
-    await writeMetadata(STUB_PREVIEW_ID);
-
-    await deployCommand({ preview: true, snapshot: true });
-
-    const call = vi.mocked(brokerProvider.brokerCredentialProvider).mock.calls[0][0];
-    expect(call.previewId).not.toBe(STUB_PREVIEW_ID);
-    expect(call.previewId).toMatch(/^[0-9a-f]{8}$/);
-  });
-
   it('passes a full CDN URL (not a relative path) as publicUrl to the build', async () => {
-    await writeMetadata(STUB_PREVIEW_ID);
-    await deployCommand({ preview: true });
+    await deployCommand({ preview: true, previewId: 'existing-preview-id' });
 
-    const previewAppName = `mf-${buildPreviewSlug('my-app', STUB_PREVIEW_ID)}`;
+    const previewAppName = `mf-${buildPreviewSlug('my-app', 'existing-preview-id')}`;
     expect(buildCommand).toHaveBeenCalledWith(
       expect.objectContaining({
         publicUrl: `https://bigbrain-zth-mf-assets.bigbrain.me/previews/${previewAppName}/MF`,
@@ -197,10 +178,9 @@ describe('deploy --preview', () => {
   });
 
   it('--open opens the previewUrl in the browser on success', async () => {
-    await writeMetadata(STUB_PREVIEW_ID);
-    await deployCommand({ preview: true, open: true });
+    await deployCommand({ preview: true, previewId: 'existing-preview-id', open: true });
 
-    const previewSlug = buildPreviewSlug('my-app', STUB_PREVIEW_ID);
+    const previewSlug = buildPreviewSlug('my-app', 'existing-preview-id');
     expect(openInBrowser).toHaveBeenCalledWith(`https://bigbrain.me/bigbrain-vibe/${previewSlug}`);
   });
 
@@ -215,20 +195,19 @@ 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 });
+    await deployCommand({ preview: true, previewId: 'existing-preview-id' });
 
     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', STUB_PREVIEW_ID);
+    const previewSlug = buildPreviewSlug('my-app', 'existing-preview-id');
     expect(payload).toMatchObject({
       ok: true,
       appName: 'mf-my-app',
-      previewId: STUB_PREVIEW_ID,
+      previewId: 'existing-preview-id',
       previewAppName: `mf-${previewSlug}`,
       previewUrl: `https://bigbrain.me/bigbrain-vibe/${previewSlug}`,
     });

package/src/commands/deploy.ts

@@ -1,4 +1,5 @@
 import os from 'node:os';
+import { randomUUID } from 'node:crypto';
 import { readJson } from 'fs-extra';
 import { info, warn, output, getOutputMode } from '../util/logger';
 import { resolveConsumerPaths } from '../shadow/paths';
@@ -21,8 +22,6 @@ 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 { readMetadata, writeMetadata } from '../shadow/metadata';
-import { generatePreviewId } from '../shadow/prepare';
 import { buildCommand } from './build';
 import { promptForTags } from './tag';
 import type { ConsumerPaths } from '../types';
@@ -35,8 +34,8 @@ export interface DeployOptions {
   // Registers a real, disposable `apps` row under a synthetic name instead of
   // deploying — no git, no deploy lock (each previewId's slug is unique).
   preview?: boolean;
-  // With --preview: deploy to a new previewId without touching metadata — the sticky --preview URL stays unchanged.
-  snapshot?: boolean;
+  // With --preview: update an existing preview instead of minting a new one.
+  previewId?: string;
   open?: boolean;
 }
 
@@ -96,15 +95,7 @@ async function buildAndStamp(opts: {
 }
 
 async function deployPreview({ paths, consumerName, appName, token, opts }: DeployContext): Promise<void> {
-  const meta = await readMetadata(paths);
-  const previewId = opts.snapshot ? generatePreviewId() : (meta?.previewId ?? generatePreviewId());
-
-  // Pre-stamp so prepareShadow (called inside buildAndStamp) preserves our previewId.
-  // Only possible when metadata already exists — otherwise prepareShadow creates it fresh.
-  if (!opts.snapshot && meta && meta.previewId !== previewId) {
-    await writeMetadata(paths, { ...meta, previewId });
-  }
-
+  const previewId = opts.previewId ?? randomUUID().slice(0, 8);
   const previewSlug = buildPreviewSlug(consumerName, previewId);
   const previewAppName = mfAppName(previewSlug);
   const keyPrefix = `${S3_PREVIEWS_FOLDER}/${previewAppName}/MF`;
@@ -117,15 +108,6 @@ async function deployPreview({ paths, consumerName, appName, token, opts }: Depl
   info('building');
   const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote: '' });
 
-  // Post-stamp: if metadata didn't exist before build, prepareShadow created it with
-  // its own previewId. Overwrite with ours so subsequent runs reuse the same URL.
-  if (!opts.snapshot) {
-    const freshMeta = await readMetadata(paths);
-    if (freshMeta && freshMeta.previewId !== previewId) {
-      await writeMetadata(paths, { ...freshMeta, previewId });
-    }
-  }
-
   const creds = await brokerCredentialProvider({ appName: previewAppName, previewId })();
   setupS3Client(creds);
 

package/src/index.ts

@@ -103,12 +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',
-      '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(
-      '--snapshot',
-      'with --preview: deploy to a fresh previewId without touching the sticky URL — produces a permanent point-in-time link'
+      '--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('--open', 'open the resulting app/preview URL in the browser on success')
     .option(
@@ -122,8 +118,7 @@ async function main(): Promise<void> {
     .action(
       async (opts: {
         dryRun?: boolean;
-        preview?: boolean;
-        snapshot?: boolean;
+        preview?: boolean | string;
         open?: boolean;
         remote?: string;
         repoUrl?: string;
@@ -131,7 +126,12 @@ async function main(): Promise<void> {
         try {
           await trackDuration(
             opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success',
-            () => deployCommand(opts as Parameters<typeof deployCommand>[0]),
+            () =>
+              deployCommand({
+                ...opts,
+                preview: Boolean(opts.preview),
+                previewId: typeof opts.preview === 'string' ? opts.preview : undefined,
+              } as Parameters<typeof deployCommand>[0]),
             {
               app_name: getCwdAppName(),
             }

package/src/shadow/prepare.ts

@@ -1,4 +1,3 @@
-import { randomUUID } from 'node:crypto';
 import { ensureDir, pathExists, readJson } from 'fs-extra';
 import { info } from '../util/logger';
 import { cleanAppName } from '../util/app-name';
@@ -45,10 +44,6 @@ export async function prepareShadow(consumerDir: string = process.cwd()): Promis
   return { appName, port, paths };
 }
 
-export 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
@@ -57,22 +52,15 @@ export function generatePreviewId(): string {
  */
 async function resolvePortAndMetadata(paths: ConsumerPaths, appName: string): Promise<ShadowMetadata> {
   const existing = await readMetadata(paths);
-
-  let port = existing?.port;
-  if (!port || !(await isPortFree(port))) {
-    port = await pickPort();
+  if (existing?.port && (await isPortFree(existing.port))) {
+    return existing;
   }
 
   const next: ShadowMetadata = {
     createdAt: existing?.createdAt ?? new Date().toISOString(),
     appName,
-    port,
-    previewId: existing?.previewId ?? generatePreviewId(),
+    port: await pickPort(),
   };
-
-  if (JSON.stringify(next) !== JSON.stringify(existing)) {
-    await writeMetadata(paths, next);
-  }
-
+  await writeMetadata(paths, next);
   return next;
 }

package/src/types.ts

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