@mondaydotcomorg/z2h-cli 0.15.2 → 0.16.0

package/dist/commands/__tests__/deploy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=deploy.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.test.d.ts","sourceRoot":"","sources":["../../../src/commands/__tests__/deploy.test.ts"],"names":[],"mappings":""}

package/dist/commands/build.d.ts

@@ -1,5 +1,12 @@
+import type { AssetManifestFile } from '../util/manifest';
 export interface BuildOptions {
     publicUrl?: string;
 }
-export declare function buildCommand(opts?: BuildOptions): Promise<void>;
+export interface BuildResult {
+    appName: string;
+    port: number;
+    buildDir: string;
+    assetManifest: AssetManifestFile;
+}
+export declare function buildCommand(opts?: BuildOptions): Promise<BuildResult>;
 //# sourceMappingURL=build.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAGD,wBAAsB,YAAY,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCzE"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,iBAAiB,CAAC;CAClC;AAGD,wBAAsB,YAAY,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAyChF"}

package/dist/commands/build.js

@@ -1,10 +1,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
+const path = require('node:path');
 const fs = require('fs-extra');
 const execa = require('execa');
 const util_logger = require('../util/logger.js');
 const shadow_prepare = require('../shadow/prepare.js');
 
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+
 // Should be run from the consumer app directory — uses process.cwd() to locate it.
 async function buildCommand(opts = {}) {
     const ctx = await shadow_prepare.prepareShadow();
@@ -28,12 +33,19 @@ async function buildCommand(opts = {}) {
     if (!(await fs.pathExists(ctx.paths.shadowBuild))) {
         throw new Error(`Expected build output at ${ctx.paths.shadowBuild} — not found.`);
     }
+    // Trident emits the canonical per-MF manifest at build/asset-manifest.json.
+    const assetManifestPath = path__default.default.join(ctx.paths.shadowBuild, 'asset-manifest.json');
+    if (!(await fs.pathExists(assetManifestPath))) {
+        throw new Error(`Missing asset-manifest.json at ${assetManifestPath}.`);
+    }
+    const assetManifest = (await fs.readJson(assetManifestPath));
     util_logger.output(`[z2h-cli] build complete — artifacts at ${ctx.paths.shadowBuild}`, {
         ok: true,
         appName: ctx.appName,
         port: ctx.port,
         buildDir: ctx.paths.shadowBuild,
     });
+    return { appName: ctx.appName, port: ctx.port, buildDir: ctx.paths.shadowBuild, assetManifest };
 }
 
 exports.buildCommand = buildCommand;

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

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AASA,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;AA6BD,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8F5F"}
+{"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"}

package/dist/commands/create.js

@@ -6,7 +6,6 @@ const fs = require('fs-extra');
 const util_logger = require('../util/logger.js');
 const util_workspace = require('../util/workspace.js');
 const util_templates = require('../util/templates.js');
-const constants = require('../constants.js');
 const util_npm_install = require('../util/npm/install.js');
 const util_git_repo = require('../util/git/repo.js');
 const util_git_remoteOptions = require('../util/git/remote-options.js');
@@ -18,10 +17,6 @@ const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
 const path__default = /*#__PURE__*/_interopDefault(path);
 
-// Names reserved by the host MF (mf-bigbrain-zth) for platform pages under
-// /bigbrain-vibe/<name>. Creating an app with one of these would shadow the
-// platform page in the URL, so we refuse upfront.
-const RESERVED_APP_NAMES = new Set(['generate-z2h-token']);
 /**
  * Convert kebab-case to PascalCase. `demo-app` → `DemoApp`.
  */
@@ -46,13 +41,7 @@ async function createCommand(appName, opts = {}) {
     // Validate workspace.
     const workspace = await util_workspace.assertWorkspace();
     // Validate app name.
-    if (RESERVED_APP_NAMES.has(appName)) {
-        throw new Error(`App name "${appName}" is reserved by the Z2H host for a platform page under /bigbrain-vibe/${appName}. Pick a different name.`);
-    }
-    if (!constants.APP_NAME_PATTERN.test(appName)) {
-        throw new Error(`App name "${appName}" is invalid. Use lowercase kebab-case (a-z, 0-9, -), ` +
-            `2-50 chars, starting with a letter.`);
-    }
+    util_appName.validateAppName(appName);
     // Validate --remote up front before any file I/O.
     util_git_remoteOptions.validateRemoteOptions(opts, true);
     // Resolve template.

package/dist/commands/deploy.d.ts

@@ -3,6 +3,9 @@ export interface DeployOptions {
     dryRun?: boolean;
     remote?: RemoteType;
     repoUrl?: string;
+    preview?: boolean;
+    previewId?: string;
+    open?: boolean;
 }
 export declare function deployCommand(opts?: DeployOptions): Promise<void>;
 //# sourceMappingURL=deploy.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAKtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAGD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmJ3E"}
+{"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,8 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-const path = require('node:path');
 const os = require('node:os');
-const node_readline = require('node:readline');
+const crypto = require('node:crypto');
 const fs = require('fs-extra');
 const util_logger = require('../util/logger.js');
 const shadow_paths = require('../shadow/paths.js');
@@ -12,17 +11,18 @@ const constants = require('../constants.js');
 const util_auth_brokerCredentialProvider = require('../util/auth/broker-credential-provider.js');
 const util_auth_authStore = require('../util/auth/auth-store.js');
 const util_appName = require('../util/app-name.js');
-const util_machineIdentity = require('../util/machine-identity.js');
 const util_git_repo = require('../util/git/repo.js');
 const util_git_gitEnv = require('../util/git/git-env.js');
 const util_git_remoteOptions = require('../util/git/remote-options.js');
 const util_s3_client = require('../util/s3/client.js');
-const commands_tag = require('./tag.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 commands_build = require('./build.js');
+const commands_tag = require('./tag.js');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
-const path__default = /*#__PURE__*/_interopDefault(path);
 const os__default = /*#__PURE__*/_interopDefault(os);
 
 // Should be run from the consumer app directory — uses process.cwd() to locate it.
@@ -32,10 +32,68 @@ async function deployCommand(opts = {}) {
     if (!consumerPkg.name) {
         throw new Error('Consumer package.json must have a "name" field');
     }
+    util_appName.validateAppName(util_appName.cleanAppName(consumerPkg.name));
     const appName = util_appName.mfAppName(consumerPkg.name);
     // Validate the user's deploy token is on disk before doing any expensive
     // work. Throws Z2hAuthMissingError with a remediation hint if not.
     const { token } = await util_auth_authStore.readZthAuth();
+    const ctx = { paths, consumerName: consumerPkg.name, appName, token, opts };
+    if (opts.preview) {
+        await deployPreview(ctx);
+    }
+    else {
+        await deployLive(ctx);
+    }
+}
+/**
+ * Runs the build step and turns its output into a ManifestEntry ready to
+ * register/update — the one step a real deploy and a preview both need
+ * identically: build, then stamp version/url/deployedBy/gitRemote onto the
+ * asset manifest Trident emitted.
+ */
+async function buildAndStamp(opts) {
+    const { assetManifest } = await commands_build.buildCommand({ publicUrl: opts.publicUrl });
+    const deployedBy = util_machineIdentity.getMachineAppName() ?? os__default.default.userInfo().username;
+    return {
+        ...assetManifest,
+        version: opts.nextVersion,
+        url: opts.publicUrl,
+        deployedBy,
+        gitRemote: opts.gitRemote,
+    };
+}
+async function deployPreview({ paths, consumerName, appName, token, opts }) {
+    const previewId = opts.previewId ?? crypto.randomUUID();
+    const previewSlug = util_appName.buildPreviewSlug(consumerName, previewId);
+    const previewAppName = util_appName.mfAppName(previewSlug);
+    const keyPrefix = `${constants.S3_PREVIEWS_FOLDER}/${appName}/${previewId}/MF`;
+    // Full CDN URL, not a relative path — trident-skeleton uses a manifest
+    // entry's `url` verbatim as the asset base, never joined with its own mfUrl.
+    const url = `${constants.BUCKET_READ_DNS_URL}/${keyPrefix}`;
+    const nextVersion = (await util_auth_brokerCredentialProvider.fetchDeployVersion(previewAppName)) + 1;
+    util_logger.info('building');
+    const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote: '' });
+    const creds = await util_auth_brokerCredentialProvider.brokerCredentialProvider({ appName, 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);
+    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}`, {
+        ok: true,
+        appName,
+        previewId,
+        previewAppName,
+        bucket: constants.BUCKET_WRITE_NAME,
+        keyPrefix,
+        url,
+        previewUrl,
+    });
+    if (opts.open) {
+        void util_openBrowser.openInBrowser(previewUrl);
+    }
+}
+async function deployLive({ paths, consumerName, appName, token, opts }) {
     let gitRemote = await util_git_repo.getRemoteUrl(process.cwd());
     if (gitRemote) {
         if (opts.remote || opts.repoUrl) {
@@ -54,7 +112,7 @@ async function deployCommand(opts = {}) {
         util_git_remoteOptions.validateRemoteOptions(opts);
         // Pass the raw consumer name (not the mf-prefixed appName) so defaultS3Remote
         // produces the correct s3://bucket/mf-<name>/git path without double prefix.
-        const remote = util_git_remoteOptions.resolveRemoteUrl(opts.remote, consumerPkg.name, opts.repoUrl);
+        const remote = util_git_remoteOptions.resolveRemoteUrl(opts.remote, consumerName, opts.repoUrl);
         util_logger.info(`initializing git repo with ${opts.remote} remote...`);
         await util_git_repo.initRepo(process.cwd(), remote);
         gitRemote = remote;
@@ -74,24 +132,7 @@ async function deployCommand(opts = {}) {
     const keyPrefix = `${appName}/${nextVersion}`;
     const url = `${constants.BUCKET_READ_DNS_URL}/${keyPrefix}`;
     util_logger.info('building');
-    await commands_build.buildCommand({ publicUrl: url });
-    if (!(await fs.pathExists(paths.shadowBuild))) {
-        throw new Error(`No build output at ${paths.shadowBuild} after build step.`);
-    }
-    // Trident emits the canonical per-MF manifest at build/asset-manifest.json.
-    const assetManifestPath = path__default.default.join(paths.shadowBuild, 'asset-manifest.json');
-    if (!(await fs.pathExists(assetManifestPath))) {
-        throw new Error(`Missing asset-manifest.json at ${assetManifestPath}.`);
-    }
-    const assetManifest = (await fs.readJson(assetManifestPath));
-    const deployedBy = util_machineIdentity.getMachineAppName() ?? os__default.default.userInfo().username;
-    const entry = {
-        ...assetManifest,
-        version: nextVersion,
-        url,
-        deployedBy,
-        gitRemote,
-    };
+    const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote });
     if (opts.dryRun) {
         util_logger.output(`[z2h-cli] dry-run: would upload to s3://${constants.BUCKET_WRITE_NAME}/${keyPrefix}/ as v${version}`, {
             ok: true,
@@ -121,18 +162,7 @@ async function deployCommand(opts = {}) {
         }
         util_logger.info(`uploading build → s3://${constants.BUCKET_WRITE_NAME}/${keyPrefix}/`);
         await util_s3_upload.uploadDir(paths.shadowBuild, keyPrefix);
-        // v1 creates the app row (+ owner grant); later versions release onto it.
-        // The two are separate endpoints, so the CLI picks based on the version it
-        // was handed.
-        if (nextVersion === 1) {
-            const visibility = await resolveFirstDeployVisibility(appName);
-            util_logger.info(`registering app "${appName}" → v${nextVersion} (${visibility})`);
-            await registerApp(appName, token, nextVersion, entry, visibility, gitRemote);
-        }
-        else {
-            util_logger.info(`releasing "${appName}" → v${nextVersion}`);
-            await updateApp(appName, token, nextVersion, entry, gitRemote);
-        }
+        await util_broker_app.registerOrUpdateApp({ appName, token, nextVersion, entry, gitRemote });
     }
     finally {
         await releaseLockBestEffort(appName, token);
@@ -143,7 +173,7 @@ async function deployCommand(opts = {}) {
     // The host MF parses the app name from the URL and prepends `mf-` itself
     // before looking it up in the manifest. So the user-facing URL must use
     // the consumer's de-scoped package name (no `mf-` prefix, no `@scope/`).
-    const liveUrl = `https://bigbrain.me/bigbrain-vibe/${util_appName.cleanAppName(consumerPkg.name)}`;
+    const liveUrl = `https://bigbrain.me/bigbrain-vibe/${util_appName.cleanAppName(consumerName)}`;
     util_logger.output(`[z2h-cli] deployed ✅\n  app:     ${appName}\n  version: ${nextVersion}\n  open:    ${liveUrl}`, {
         ok: true,
         appName,
@@ -154,16 +184,8 @@ async function deployCommand(opts = {}) {
         liveUrl,
         entry,
     });
-}
-async function registerApp(appName, token, version, entry, visibility, gitRemote) {
-    const res = await fetch(`${constants.brokerBaseUrl()}/z2h-cli/apps/register`, {
-        method: 'POST',
-        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...constants.routingHeaders() },
-        body: JSON.stringify({ appName, version, entry, visibility, gitRemote }),
-    });
-    if (!res.ok) {
-        const text = await res.text();
-        throw new Error(`App registration failed (${res.status}): ${text.slice(0, 1024)}`);
+    if (opts.open) {
+        void util_openBrowser.openInBrowser(liveUrl);
     }
 }
 const TAG_NUDGE = "run 'z2h-cli tag' to categorize this app (app type & team)";
@@ -204,31 +226,6 @@ async function acquireDeployLock(appName, token) {
     }
     util_logger.info(`deploy lock acquired for ${appName}`);
 }
-async function updateApp(appName, token, version, entry, gitRemote) {
-    const res = await fetch(`${constants.brokerBaseUrl()}/z2h-cli/apps/update`, {
-        method: 'POST',
-        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...constants.routingHeaders() },
-        body: JSON.stringify({ appName, version, entry, gitRemote }),
-    });
-    if (!res.ok) {
-        const text = await res.text();
-        throw new Error(`App update failed (${res.status}): ${text.slice(0, 1024)}`);
-    }
-}
-// First deploy only: decide whether the app is born public or private. The
-// choice is passed to the register endpoint (default private). Non-interactive
-// runs (--json or no TTY) always default to private.
-async function resolveFirstDeployVisibility(appName) {
-    if (util_logger.getOutputMode() === 'json' || !process.stdout.isTTY) {
-        return 'private';
-    }
-    const rl = node_readline.createInterface({ input: process.stdin, output: process.stdout });
-    const answer = await new Promise(resolve => {
-        rl.question(`Make "${appName}" public to all monday.com employees? (y/N) `, resolve);
-    });
-    rl.close();
-    return answer.trim().toLowerCase() === 'y' ? 'public' : 'private';
-}
 // best-effort — the 2-min TTL backstop handles failures
 async function releaseLockBestEffort(appName, token) {
     try {

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AA2TA,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAqEnD"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAwSA,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAqEnD"}

package/dist/commands/doctor.js

@@ -26,7 +26,6 @@ const Z2H_REPO_ROOT = path__default.default.join(HOME, 'Development', 'bigbrain-
 const BOOTSTRAP_CMD = `bash ${path__default.default.join(Z2H_REPO_ROOT, 'z2h/setup/bootstrap.sh')}`;
 const UPDATE_CMD = `bash ${path__default.default.join(Z2H_REPO_ROOT, 'z2h/setup/update.sh')}`;
 const CLAUDE_PLUGINS_JSON = path__default.default.join(HOME, '.claude', 'plugins', 'installed_plugins.json');
-const SSL_CERT_PATH = path__default.default.join(HOME, 'Library', 'Application Support', 'devcert', 'domains', 'webpack.llama.fan', 'certificate.crt');
 // ── helpers ───────────────────────────────────────────────────────────────────
 async function checkTool(label, opts) {
     const { cmd, args, failStatus = 'fail', getVersion, fix } = opts;
@@ -220,15 +219,6 @@ async function checkReactVersion() {
         detail: reactVersion,
     };
 }
-async function checkSslCert() {
-    const ok = await fs.pathExists(SSL_CERT_PATH);
-    return {
-        label: 'SSL cert',
-        status: ok ? 'ok' : 'warn',
-        detail: ok ? 'webpack.llama.fan' : 'not found — auto-installs on first z2h-cli dev',
-        fix: ok ? undefined : 'z2h-cli dev',
-    };
-}
 async function checkPlugin(pluginKey, label, isMandatory, pluginsJson) {
     const missingStatus = isMandatory ? 'fail' : 'warn';
     if (!pluginsJson) {
@@ -275,7 +265,7 @@ async function doctorCommand() {
     }
     const systemChecks = await Promise.all([checkNvm(), checkNode(), checkYarn(), checkAws(), checkGitRemoteS3()]);
     const cliChecks = await Promise.all([checkZ2hCli(), checkAuthToken(), checkNpmTokenInProfile()]);
-    const workspaceChecks = await Promise.all([checkWorkspace(), checkReactVersion(), checkSslCert()]);
+    const workspaceChecks = await Promise.all([checkWorkspace(), checkReactVersion()]);
     const pluginChecks = await Promise.all([
         checkPlugin('z2h@bigbrain-z2h', 'z2h plugin', true, pluginsJson),
         checkPlugin('cf-external-claude-plugin@client-foundations-ai-tools', 'cf-external plugin', false, pluginsJson),

package/dist/constants.d.ts

@@ -13,9 +13,11 @@ export declare const REGION = "us-east-1";
 export declare const BUCKET_WRITE_URL = "https://prod-use1-bigbrain-zth-mf-assets.s3.us-east-1.amazonaws.com";
 export declare const BUCKET_READ_DNS_NAME = "bigbrain-zth-mf-assets";
 export declare const BUCKET_READ_DNS_URL = "https://bigbrain-zth-mf-assets.bigbrain.me";
+export declare const S3_PREVIEWS_FOLDER = "previews";
 export declare const MANIFEST_KEY = "mf-assets";
 export declare const MANIFEST_READ_URL = "https://bigbrain-zth-mf-assets.bigbrain.me/mf-assets";
 export declare const APP_NAME_PATTERN: RegExp;
+export declare const PREVIEW_APP_NAME_PREFIX = "zth-preview-";
 export declare const DEFAULT_BROKER_BASE_URL = "https://bigbrain-zth.bigbrain.me";
 /**
  * Resolves the broker origin (no trailing slash). Honors

package/dist/constants.d.ts.map

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

package/dist/constants.js

@@ -8,7 +8,6 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const SHADOW_DIR_NAME = '.zth';
 // ─────────── Shadow scripts ───────
 const SHADOW_SCRIPTS = {
-    start: 'trident start',
     build: 'trident build',
 };
 // ─────────── Shadow dev deps ───────
@@ -17,10 +16,10 @@ const SHADOW_SCRIPTS = {
 const SHADOW_DEV_DEPS = {
     '@mondaydotcomorg/trident-toolkit': '^2.9.25',
 };
-// ─────────── Auto-allocated dev port range ────
-// High enough to dodge common dev defaults (3000 Next, 5173 Vite, 8080).
-// Collisions within the 7k-port pool are rare for POC; if trident can't
-// bind, the user sees a clear bind error from the dev server and re-runs.
+// ─────────── Auto-allocated shadow port range ────
+// Baked into every shadow's .tridentrc.js regardless of whether a dev server
+// ever binds it. High enough to dodge common dev defaults (3000 Next, 5173
+// Vite, 8080). Collisions within the 7k-port pool are rare for POC.
 const MIN_PORT = 13000;
 const MAX_PORT = 19999;
 // ─────────── Gitignore entries auto-appended to the consumer's file ────
@@ -35,6 +34,9 @@ const REGION = 'us-east-1';
 const BUCKET_WRITE_URL = `https://${BUCKET_WRITE_NAME}.s3.${REGION}.amazonaws.com`;
 const BUCKET_READ_DNS_NAME = 'bigbrain-zth-mf-assets';
 const BUCKET_READ_DNS_URL = `https://${BUCKET_READ_DNS_NAME}.bigbrain.me`;
+// Root prefix for ephemeral preview uploads: `previews/<appName>/<previewId>/MF/...`.
+// Shared by the CLI (upload path) and bigbrain-zth (STS policy + manifest overlay).
+const S3_PREVIEWS_FOLDER = 'previews';
 // No `.json` extension — TridentSkeleton's `mfUrl` API appends `/mf-assets`
 // to the bucket base when fetching, so the manifest must live at this exact
 // key. See microfrontends/mf-bigbrain-zth/.../ZeroToHeroHost.tsx.
@@ -45,6 +47,7 @@ const MANIFEST_READ_URL = `${BUCKET_READ_DNS_URL}/${MANIFEST_KEY}`;
 // backend STS broker rejects anything else with 400; the CLI can validate
 // upfront for friendlier errors.
 const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{1,49}$/;
+const PREVIEW_APP_NAME_PREFIX = 'zth-preview-';
 // ─────────── Broker origin + npm registry (shared §3 contract) ─────
 // The bigbrain-zth broker fronts both the STS credential route and the npm
 // proxy. `Z2H_BROKER_BASE_URL` overrides the origin for tests/staging.
@@ -99,8 +102,10 @@ exports.MANIFEST_READ_URL = MANIFEST_READ_URL;
 exports.MAX_PORT = MAX_PORT;
 exports.MIN_PORT = MIN_PORT;
 exports.NPM_BROKER_PATH = NPM_BROKER_PATH;
+exports.PREVIEW_APP_NAME_PREFIX = PREVIEW_APP_NAME_PREFIX;
 exports.PUBLIC_NPM_REGISTRY_URL = PUBLIC_NPM_REGISTRY_URL;
 exports.REGION = REGION;
+exports.S3_PREVIEWS_FOLDER = S3_PREVIEWS_FOLDER;
 exports.SHADOW_DEV_DEPS = SHADOW_DEV_DEPS;
 exports.SHADOW_DIR_NAME = SHADOW_DIR_NAME;
 exports.SHADOW_SCRIPTS = SHADOW_SCRIPTS;

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=deploy.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.test.d.ts","sourceRoot":"","sources":["../../../../src/commands/__tests__/deploy.test.ts"],"names":[],"mappings":""}

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

@@ -1,5 +1,12 @@
+import type { AssetManifestFile } from '../util/manifest';
 export interface BuildOptions {
     publicUrl?: string;
 }
-export declare function buildCommand(opts?: BuildOptions): Promise<void>;
+export interface BuildResult {
+    appName: string;
+    port: number;
+    buildDir: string;
+    assetManifest: AssetManifestFile;
+}
+export declare function buildCommand(opts?: BuildOptions): Promise<BuildResult>;
 //# sourceMappingURL=build.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/commands/build.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAGD,wBAAsB,YAAY,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCzE"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/commands/build.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,iBAAiB,CAAC;CAClC;AAGD,wBAAsB,YAAY,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAyChF"}

package/dist/esm/commands/build.mjs

@@ -1,4 +1,5 @@
-import { pathExists } from 'fs-extra';
+import path from 'node:path';
+import { pathExists, readJson } from 'fs-extra';
 import { execa } from 'execa';
 import { info, output } from '../util/logger.mjs';
 import { prepareShadow } from '../shadow/prepare.mjs';
@@ -26,12 +27,19 @@ async function buildCommand(opts = {}) {
     if (!(await pathExists(ctx.paths.shadowBuild))) {
         throw new Error(`Expected build output at ${ctx.paths.shadowBuild} — not found.`);
     }
+    // Trident emits the canonical per-MF manifest at build/asset-manifest.json.
+    const assetManifestPath = path.join(ctx.paths.shadowBuild, 'asset-manifest.json');
+    if (!(await pathExists(assetManifestPath))) {
+        throw new Error(`Missing asset-manifest.json at ${assetManifestPath}.`);
+    }
+    const assetManifest = (await readJson(assetManifestPath));
     output(`[z2h-cli] build complete — artifacts at ${ctx.paths.shadowBuild}`, {
         ok: true,
         appName: ctx.appName,
         port: ctx.port,
         buildDir: ctx.paths.shadowBuild,
     });
+    return { appName: ctx.appName, port: ctx.port, buildDir: ctx.paths.shadowBuild, assetManifest };
 }
 
 export { buildCommand };

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

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/commands/create.ts"],"names":[],"mappings":"AASA,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;AA6BD,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8F5F"}
+{"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"}

package/dist/esm/commands/create.mjs

@@ -4,19 +4,14 @@ import { pathExists, ensureDir, writeFile, copy, readdir } from 'fs-extra';
 import { info, warn, output } from '../util/logger.mjs';
 import { assertWorkspace } from '../util/workspace.mjs';
 import { APP_TEMPLATES, getTemplatesDir, renderTemplate } from '../util/templates.mjs';
-import { APP_NAME_PATTERN } from '../constants.mjs';
 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 { mfAppName } from '../util/app-name.mjs';
+import { validateAppName, mfAppName } from '../util/app-name.mjs';
 import { prepareShadow } from '../shadow/prepare.mjs';
 
-// Names reserved by the host MF (mf-bigbrain-zth) for platform pages under
-// /bigbrain-vibe/<name>. Creating an app with one of these would shadow the
-// platform page in the URL, so we refuse upfront.
-const RESERVED_APP_NAMES = new Set(['generate-z2h-token']);
 /**
  * Convert kebab-case to PascalCase. `demo-app` → `DemoApp`.
  */
@@ -41,13 +36,7 @@ async function createCommand(appName, opts = {}) {
     // Validate workspace.
     const workspace = await assertWorkspace();
     // Validate app name.
-    if (RESERVED_APP_NAMES.has(appName)) {
-        throw new Error(`App name "${appName}" is reserved by the Z2H host for a platform page under /bigbrain-vibe/${appName}. Pick a different name.`);
-    }
-    if (!APP_NAME_PATTERN.test(appName)) {
-        throw new Error(`App name "${appName}" is invalid. Use lowercase kebab-case (a-z, 0-9, -), ` +
-            `2-50 chars, starting with a letter.`);
-    }
+    validateAppName(appName);
     // Validate --remote up front before any file I/O.
     validateRemoteOptions(opts, true);
     // Resolve template.

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

@@ -3,6 +3,9 @@ export interface DeployOptions {
     dryRun?: boolean;
     remote?: RemoteType;
     repoUrl?: string;
+    preview?: boolean;
+    previewId?: string;
+    open?: boolean;
 }
 export declare function deployCommand(opts?: DeployOptions): Promise<void>;
 //# sourceMappingURL=deploy.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAKtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAGD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmJ3E"}
+{"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"}