@mondaydotcomorg/z2h-cli 0.15.2 → 0.17.0

package/dist/esm/commands/deploy.mjs

@@ -1,22 +1,23 @@
-import path from 'node:path';
 import os from 'node:os';
-import { createInterface } from 'node:readline';
-import { readJson, pathExists } from 'fs-extra';
+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';
 import { fetchAppTags, fetchTagCatalog, setAppTags } from '../util/tags.mjs';
 import { uploadDir } from '../util/s3/upload.mjs';
-import { BUCKET_WRITE_NAME, brokerBaseUrl, routingHeaders, BUCKET_READ_DNS_URL } from '../constants.mjs';
+import { BUCKET_WRITE_NAME, brokerBaseUrl, routingHeaders, S3_PREVIEWS_FOLDER, BUCKET_READ_DNS_URL } from '../constants.mjs';
 import { fetchDeployVersion, brokerCredentialProvider } from '../util/auth/broker-credential-provider.mjs';
 import { readZthAuth } from '../util/auth/auth-store.mjs';
-import { mfAppName, cleanAppName } from '../util/app-name.mjs';
-import { getMachineAppName } from '../util/machine-identity.mjs';
+import { validateAppName, cleanAppName, mfAppName, buildPreviewSlug } from '../util/app-name.mjs';
 import { getRemoteUrl, initRepo, guardCleanTree, pullAndResolve, pushToRemote } from '../util/git/repo.mjs';
 import { resolveGitEnv } from '../util/git/git-env.mjs';
 import { validateRemoteOptions, resolveRemoteUrl } from '../util/git/remote-options.mjs';
 import { setupS3Client } from '../util/s3/client.mjs';
-import { promptForTags } from './tag.mjs';
+import { getMachineAppName } from '../util/machine-identity.mjs';
+import { registerOrUpdateApp } from '../util/broker/app.mjs';
+import { openInBrowser } from '../util/open-browser.mjs';
 import { buildCommand } from './build.mjs';
+import { promptForTags } from './tag.mjs';
 
 // Should be run from the consumer app directory — uses process.cwd() to locate it.
 async function deployCommand(opts = {}) {
@@ -25,10 +26,68 @@ async function deployCommand(opts = {}) {
     if (!consumerPkg.name) {
         throw new Error('Consumer package.json must have a "name" field');
     }
+    validateAppName(cleanAppName(consumerPkg.name));
     const 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 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 buildCommand({ publicUrl: opts.publicUrl });
+    const deployedBy = getMachineAppName() ?? os.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 ?? randomUUID().slice(0, 8);
+    const previewSlug = buildPreviewSlug(consumerName, previewId);
+    const previewAppName = mfAppName(previewSlug);
+    const keyPrefix = `${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 = `${BUCKET_READ_DNS_URL}/${keyPrefix}`;
+    const nextVersion = (await fetchDeployVersion(previewAppName)) + 1;
+    info('building');
+    const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote: '' });
+    const creds = await brokerCredentialProvider({ appName, previewId })();
+    setupS3Client(creds);
+    info(`uploading preview build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
+    await uploadDir(paths.shadowBuild, keyPrefix);
+    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}`, {
+        ok: true,
+        appName,
+        previewId,
+        previewAppName,
+        bucket: BUCKET_WRITE_NAME,
+        keyPrefix,
+        url,
+        previewUrl,
+    });
+    if (opts.open) {
+        void openInBrowser(previewUrl);
+    }
+}
+async function deployLive({ paths, consumerName, appName, token, opts }) {
     let gitRemote = await getRemoteUrl(process.cwd());
     if (gitRemote) {
         if (opts.remote || opts.repoUrl) {
@@ -47,7 +106,7 @@ async function deployCommand(opts = {}) {
         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 = resolveRemoteUrl(opts.remote, consumerPkg.name, opts.repoUrl);
+        const remote = resolveRemoteUrl(opts.remote, consumerName, opts.repoUrl);
         info(`initializing git repo with ${opts.remote} remote...`);
         await initRepo(process.cwd(), remote);
         gitRemote = remote;
@@ -67,24 +126,7 @@ async function deployCommand(opts = {}) {
     const keyPrefix = `${appName}/${nextVersion}`;
     const url = `${BUCKET_READ_DNS_URL}/${keyPrefix}`;
     info('building');
-    await buildCommand({ publicUrl: url });
-    if (!(await 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.join(paths.shadowBuild, 'asset-manifest.json');
-    if (!(await pathExists(assetManifestPath))) {
-        throw new Error(`Missing asset-manifest.json at ${assetManifestPath}.`);
-    }
-    const assetManifest = (await readJson(assetManifestPath));
-    const deployedBy = getMachineAppName() ?? os.userInfo().username;
-    const entry = {
-        ...assetManifest,
-        version: nextVersion,
-        url,
-        deployedBy,
-        gitRemote,
-    };
+    const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote });
     if (opts.dryRun) {
         output(`[z2h-cli] dry-run: would upload to s3://${BUCKET_WRITE_NAME}/${keyPrefix}/ as v${version}`, {
             ok: true,
@@ -114,18 +156,7 @@ async function deployCommand(opts = {}) {
         }
         info(`uploading build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
         await 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);
-            info(`registering app "${appName}" → v${nextVersion} (${visibility})`);
-            await registerApp(appName, token, nextVersion, entry, visibility, gitRemote);
-        }
-        else {
-            info(`releasing "${appName}" → v${nextVersion}`);
-            await updateApp(appName, token, nextVersion, entry, gitRemote);
-        }
+        await registerOrUpdateApp({ appName, token, nextVersion, entry, gitRemote });
     }
     finally {
         await releaseLockBestEffort(appName, token);
@@ -136,7 +167,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/${cleanAppName(consumerPkg.name)}`;
+    const liveUrl = `https://bigbrain.me/bigbrain-vibe/${cleanAppName(consumerName)}`;
     output(`[z2h-cli] deployed ✅\n  app:     ${appName}\n  version: ${nextVersion}\n  open:    ${liveUrl}`, {
         ok: true,
         appName,
@@ -147,16 +178,8 @@ async function deployCommand(opts = {}) {
         liveUrl,
         entry,
     });
-}
-async function registerApp(appName, token, version, entry, visibility, gitRemote) {
-    const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/register`, {
-        method: 'POST',
-        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
-        body: JSON.stringify({ appName, version, entry, visibility, gitRemote }),
-    });
-    if (!res.ok) {
-        const text = await res.text();
-        throw new Error(`App registration failed (${res.status}): ${text.slice(0, 1024)}`);
+    if (opts.open) {
+        void openInBrowser(liveUrl);
     }
 }
 const TAG_NUDGE = "run 'z2h-cli tag' to categorize this app (app type & team)";
@@ -197,31 +220,6 @@ async function acquireDeployLock(appName, token) {
     }
     info(`deploy lock acquired for ${appName}`);
 }
-async function updateApp(appName, token, version, entry, gitRemote) {
-    const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/update`, {
-        method: 'POST',
-        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
-        body: JSON.stringify({ appName, version, entry, gitRemote }),
-    });
-    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 (getOutputMode() === 'json' || !process.stdout.isTTY) {
-        return 'private';
-    }
-    const rl = 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/esm/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/esm/commands/doctor.mjs

@@ -16,7 +16,6 @@ const Z2H_REPO_ROOT = path.join(HOME, 'Development', 'bigbrain-z2h');
 const BOOTSTRAP_CMD = `bash ${path.join(Z2H_REPO_ROOT, 'z2h/setup/bootstrap.sh')}`;
 const UPDATE_CMD = `bash ${path.join(Z2H_REPO_ROOT, 'z2h/setup/update.sh')}`;
 const CLAUDE_PLUGINS_JSON = path.join(HOME, '.claude', 'plugins', 'installed_plugins.json');
-const SSL_CERT_PATH = path.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;
@@ -210,15 +209,6 @@ async function checkReactVersion() {
         detail: reactVersion,
     };
 }
-async function checkSslCert() {
-    const ok = await 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) {
@@ -265,7 +255,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/esm/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/esm/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/esm/constants.mjs

@@ -6,7 +6,6 @@
 const SHADOW_DIR_NAME = '.zth';
 // ─────────── Shadow scripts ───────
 const SHADOW_SCRIPTS = {
-    start: 'trident start',
     build: 'trident build',
 };
 // ─────────── Shadow dev deps ───────
@@ -15,10 +14,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 ────
@@ -33,6 +32,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.
@@ -43,6 +45,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.
@@ -84,4 +87,4 @@ function brokerNpmRegistryUrl() {
     return `${brokerBaseUrl()}${NPM_BROKER_PATH}`;
 }
 
-export { APP_NAME_PATTERN, BROKER_NPM_SCOPE, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, DEFAULT_BROKER_BASE_URL, GITIGNORE_ENTRIES, MANIFEST_KEY, MANIFEST_READ_URL, MAX_PORT, MIN_PORT, NPM_BROKER_PATH, PUBLIC_NPM_REGISTRY_URL, REGION, SHADOW_DEV_DEPS, SHADOW_DIR_NAME, SHADOW_SCRIPTS, Z2H_NPM_TOKEN_ENV, brokerBaseUrl, brokerNpmRegistryUrl, routingHeaders };
+export { APP_NAME_PATTERN, BROKER_NPM_SCOPE, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, DEFAULT_BROKER_BASE_URL, GITIGNORE_ENTRIES, MANIFEST_KEY, MANIFEST_READ_URL, MAX_PORT, MIN_PORT, NPM_BROKER_PATH, PREVIEW_APP_NAME_PREFIX, PUBLIC_NPM_REGISTRY_URL, REGION, S3_PREVIEWS_FOLDER, SHADOW_DEV_DEPS, SHADOW_DIR_NAME, SHADOW_SCRIPTS, Z2H_NPM_TOKEN_ENV, brokerBaseUrl, brokerNpmRegistryUrl, routingHeaders };

package/dist/esm/index.mjs

@@ -4,7 +4,6 @@ import path from 'node:path';
 import { Command } from 'commander';
 import { execa } from 'execa';
 import { getWorkspaceHome } from './util/workspace.mjs';
-import { devCommand } from './commands/dev.mjs';
 import { buildCommand } from './commands/build.mjs';
 import { cleanCommand } from './commands/clean.mjs';
 import { deployCommand } from './commands/deploy.mjs';
@@ -79,18 +78,6 @@ async function main() {
             await fail(`build failed: ${err.message}`, { command: 'build' }, 2);
         }
     });
-    program
-        .command('dev')
-        .description('Start the Trident dev server against .zth/ with native Vite HMR')
-        .option('--open', 'open the browser automatically when the dev server is ready')
-        .action(async (opts) => {
-        try {
-            await devCommand(opts);
-        }
-        catch (err) {
-            await fail(`dev failed: ${err.message}`, { command: 'dev' }, 2);
-        }
-    });
     program
         .command('clean')
         .description('Delete <consumer>/.zth/ and <consumer>/build/')
@@ -106,16 +93,23 @@ 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('--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('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(),
             });
         }
         catch (err) {
-            await fail(`deploy failed: ${err.message}`, { command: 'deploy' }, 2);
+            const label = opts.preview ? 'preview' : 'deploy';
+            await fail(`${label} failed: ${err.message}`, { command: label }, 2);
         }
     });
     program

package/dist/esm/migrations/006-remove-start-script.d.ts

@@ -0,0 +1,3 @@
+import type { Tree } from '@nx/devkit';
+export default function removeStartScript(tree: Tree): void;
+//# sourceMappingURL=006-remove-start-script.d.ts.map

package/dist/esm/migrations/006-remove-start-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"006-remove-start-script.d.ts","sourceRoot":"","sources":["../../../src/migrations/006-remove-start-script.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAMvC,MAAM,CAAC,OAAO,UAAU,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAiB1D"}

package/dist/esm/migrations/006-remove-start-script.mjs

@@ -0,0 +1,22 @@
+// `dev` is gone from the CLI (superseded by `deploy --preview`), so any
+// consumer's `start` script still pointing at it is now a dangling command.
+// Only removes the exact value the template ever wrote — leaves a
+// consumer-customized `start` script alone.
+function removeStartScript(tree) {
+    for (const entry of tree.children('.')) {
+        if (entry.startsWith('.')) {
+            continue;
+        }
+        const pkgPath = `${entry}/package.json`;
+        if (!tree.exists(pkgPath)) {
+            continue;
+        }
+        const pkg = JSON.parse(tree.read(pkgPath, 'utf-8'));
+        if (pkg.scripts?.start === 'z2h-cli dev') {
+            delete pkg.scripts.start;
+            tree.write(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+        }
+    }
+}
+
+export { removeStartScript as default };

package/dist/esm/util/__tests__/app-name.test.d.ts

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

package/dist/esm/util/__tests__/app-name.test.d.ts.map

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

package/dist/esm/util/app-name.d.ts

@@ -10,4 +10,21 @@ export declare function getCwdAppName(): string | undefined;
  * emitted bundle is `MF-mf-<app>`).
  */
 export declare function mfAppName(name: string): string;
+/**
+ * Validates a de-scoped, kebab-case app name against every rule shared by
+ * `create` and `deploy` (incl. `deploy --preview`) — pattern, reserved
+ * platform names, and the preview-prefix reservation. Throws with a
+ * friendly message on the first violation.
+ */
+export declare function validateAppName(appName: string): void;
+/**
+ * Builds the slug for a preview's synthetic RDS app row:
+ * `zth-preview-<shortid>-<realAppName>`, pre-`mf-`-prefixing. Uniqueness
+ * comes entirely from `shortId` (derived from the previewId, already a
+ * randomUUID() — 32 bits of entropy); truncating the human-readable tail to
+ * fit the cap is safe on its own, a shortId collision is astronomically
+ * unlikely at POC scale and would just 409 on registerApp for a retry.
+ */
+export declare function buildPreviewSlug(appName: string, previewId: string): string;
+export declare function isPreviewAppName(appName: string): boolean;
 //# sourceMappingURL=app-name.d.ts.map

package/dist/esm/util/app-name.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-name.d.ts","sourceRoot":"","sources":["../../../src/util/app-name.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAMlD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C"}
+{"version":3,"file":"app-name.d.ts","sourceRoot":"","sources":["../../../src/util/app-name.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAMlD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAOD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAiBrD;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAM3E;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD"}

package/dist/esm/util/app-name.mjs

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { APP_NAME_PATTERN, PREVIEW_APP_NAME_PREFIX } from '../constants.mjs';
 
 /**
  * Strip any npm scope (`@scope/`) from a package name.
@@ -23,5 +24,48 @@ function getCwdAppName() {
 function mfAppName(name) {
     return `mf-${cleanAppName(name)}`;
 }
+// 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']);
+/**
+ * Validates a de-scoped, kebab-case app name against every rule shared by
+ * `create` and `deploy` (incl. `deploy --preview`) — pattern, reserved
+ * platform names, and the preview-prefix reservation. Throws with a
+ * friendly message on the first violation.
+ */
+function validateAppName(appName) {
+    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.`);
+    }
+    if (appName.startsWith(PREVIEW_APP_NAME_PREFIX)) {
+        throw new Error(`App names starting with "${PREVIEW_APP_NAME_PREFIX}" are reserved for the ephemeral preview mechanism. Pick a different name.`);
+    }
+}
+// Preview slugs are capped here so the mf-prefixed name (`mf-` + slug) stays
+// within APP_NAME_PATTERN's 50-char limit (3 chars reserved for `mf-`).
+const PREVIEW_SLUG_MAX_LEN = 47;
+/**
+ * Builds the slug for a preview's synthetic RDS app row:
+ * `zth-preview-<shortid>-<realAppName>`, pre-`mf-`-prefixing. Uniqueness
+ * comes entirely from `shortId` (derived from the previewId, already a
+ * randomUUID() — 32 bits of entropy); truncating the human-readable tail to
+ * fit the cap is safe on its own, a shortId collision is astronomically
+ * unlikely at POC scale and would just 409 on registerApp for a retry.
+ */
+function buildPreviewSlug(appName, previewId) {
+    const shortId = previewId.replace(/-/g, '').slice(0, 8);
+    const base = `${PREVIEW_APP_NAME_PREFIX}${shortId}-${cleanAppName(appName)}`;
+    // Trailing hyphens are stripped post-slice — a cut that lands right after a
+    // hyphen in appName would otherwise leave one dangling.
+    return base.slice(0, PREVIEW_SLUG_MAX_LEN).replace(/-+$/, '');
+}
+function isPreviewAppName(appName) {
+    return appName.startsWith(`mf-${PREVIEW_APP_NAME_PREFIX}`);
+}
 
-export { cleanAppName, getCwdAppName, mfAppName };
+export { buildPreviewSlug, cleanAppName, getCwdAppName, isPreviewAppName, mfAppName, validateAppName };

package/dist/esm/util/auth/broker-credential-provider.d.ts

@@ -8,12 +8,14 @@ export declare const DEPLOY_VERSION_PATH = "/z2h-cli/apps/version";
  */
 export declare function fetchDeployVersion(appName: string): Promise<number>;
 /**
- * AWS SDK credential provider that fetches short-lived deploy credentials
- * from the bigbrain-zth STS broker for a specific version. Credentials are
- * cached in memory until 5 minutes before expiry; concurrent calls share a
- * single in-flight fetch.
+ * AWS SDK credential provider that fetches short-lived credentials from the
+ * bigbrain-zth STS broker, scoped to `appName` — or, when `previewId` is
+ * given, to a single `previews/<appName>/<previewId>/*` slot instead of the
+ * full deploy path. Credentials are cached in memory until 5 minutes before
+ * expiry; concurrent calls share a single in-flight fetch.
  */
-export declare function brokerCredentialProvider({ appName }: {
+export declare function brokerCredentialProvider({ appName, previewId, }: {
     appName: string;
+    previewId?: string;
 }): AwsCredentialIdentityProvider;
 //# sourceMappingURL=broker-credential-provider.d.ts.map

package/dist/esm/util/auth/broker-credential-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker-credential-provider.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/broker-credential-provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAyB,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAE3F,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAC1D,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AA4C3D;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUzE;AAuBD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,6BAA6B,CAuBxG"}
+{"version":3,"file":"broker-credential-provider.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/broker-credential-provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAyB,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAE3F,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAC1D,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AA4C3D;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUzE;AA4DD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,OAAO,EACP,SAAS,GACV,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,6BAA6B,CAIhC"}

package/dist/esm/util/auth/broker-credential-provider.mjs

@@ -45,31 +45,33 @@ async function fetchDeployVersion(appName) {
     const body = (await res.json());
     return body.version ?? 0;
 }
-async function fetchStsOnce(appName) {
-    const res = await postToBroker(STS_BROKER_PATH, { appName });
+async function requestSts(path, body, errorLabel) {
+    const res = await postToBroker(path, body);
     assertBrokerOk(res);
     if (!res.ok) {
         const text = await res.text();
-        throw new Error(`Z2H deploy broker returned ${res.status}: ${text.slice(0, 1024)}`);
+        throw new Error(`Z2H ${errorLabel} broker returned ${res.status}: ${text.slice(0, 1024)}`);
     }
-    const body = (await res.json());
-    if (!body.accessKeyId || !body.secretAccessKey || !body.sessionToken || !body.expiration) {
-        throw new Error('Z2H deploy broker response missing required credential fields');
+    const responseBody = (await res.json());
+    if (!responseBody.accessKeyId ||
+        !responseBody.secretAccessKey ||
+        !responseBody.sessionToken ||
+        !responseBody.expiration) {
+        throw new Error(`Z2H ${errorLabel} broker response missing required credential fields`);
     }
     return {
-        accessKeyId: body.accessKeyId,
-        secretAccessKey: body.secretAccessKey,
-        sessionToken: body.sessionToken,
-        expiration: new Date(body.expiration),
+        accessKeyId: responseBody.accessKeyId,
+        secretAccessKey: responseBody.secretAccessKey,
+        sessionToken: responseBody.sessionToken,
+        expiration: new Date(responseBody.expiration),
     };
 }
 /**
- * AWS SDK credential provider that fetches short-lived deploy credentials
- * from the bigbrain-zth STS broker for a specific version. Credentials are
- * cached in memory until 5 minutes before expiry; concurrent calls share a
- * single in-flight fetch.
+ * Wraps a raw STS fetch in the shared cache/coalescing state machine:
+ * credentials are cached in memory until 5 minutes before expiry, and
+ * concurrent calls share a single in-flight fetch.
  */
-function brokerCredentialProvider({ appName }) {
+function createCachedCredentialProvider(fetchOnce) {
     let cached;
     let inflight;
     return async () => {
@@ -80,7 +82,7 @@ function brokerCredentialProvider({ appName }) {
         if (inflight) {
             return inflight;
         }
-        inflight = fetchStsOnce(appName)
+        inflight = fetchOnce()
             .then(credentials => {
             cached = credentials;
             return credentials;
@@ -91,5 +93,15 @@ function brokerCredentialProvider({ appName }) {
         return inflight;
     };
 }
+/**
+ * AWS SDK credential provider that fetches short-lived credentials from the
+ * bigbrain-zth STS broker, scoped to `appName` — or, when `previewId` is
+ * given, to a single `previews/<appName>/<previewId>/*` slot instead of the
+ * full deploy path. Credentials are cached in memory until 5 minutes before
+ * expiry; concurrent calls share a single in-flight fetch.
+ */
+function brokerCredentialProvider({ appName, previewId, }) {
+    return createCachedCredentialProvider(() => requestSts(STS_BROKER_PATH, { appName, previewId }, previewId ? 'preview' : 'deploy'));
+}
 
 export { DEPLOY_VERSION_PATH, STS_BROKER_PATH, brokerCredentialProvider, fetchDeployVersion };

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

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

package/dist/esm/util/broker/__tests__/app.test.d.ts.map

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

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

@@ -1,3 +1,4 @@
+import type { ManifestEntry } from '../manifest';
 export interface AppInfo {
     appName: string;
     version: number;
@@ -11,4 +12,18 @@ export interface AppInfo {
  * Returns null if the app has never been deployed (404).
  */
 export declare function fetchApp(appName: string): Promise<AppInfo | null>;
+export interface RegisterOrUpdateOptions {
+    appName: string;
+    token: string;
+    nextVersion: number;
+    entry: ManifestEntry;
+    gitRemote: string;
+}
+/**
+ * v1 creates the app row (+ owner grant, prompting for visibility); later
+ * versions release onto it via update instead — the two are separate
+ * endpoints, so this picks based on the version it's handed. Shared by
+ * deploy and preview so this branching logic lives in exactly one place.
+ */
+export declare function registerOrUpdateApp(opts: RegisterOrUpdateOptions): Promise<void>;
 //# sourceMappingURL=app.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/util/broker/app.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAiBvE"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/util/broker/app.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAiBvE;AAwCD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWtF"}