@mondaydotcomorg/z2h-cli 0.15.2 → 0.16.0

package/src/constants.ts

@@ -8,7 +8,6 @@ export const SHADOW_DIR_NAME = '.zth';
 
 // ─────────── Shadow scripts ───────
 export const SHADOW_SCRIPTS: Record<string, string> = {
-  start: 'trident start',
   build: 'trident build',
 };
 
@@ -19,10 +18,10 @@ export const SHADOW_DEV_DEPS: Record<string, string> = {
   '@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.
 export const MIN_PORT = 13000;
 export const MAX_PORT = 19999;
 
@@ -42,6 +41,10 @@ export const BUCKET_WRITE_URL = `https://${BUCKET_WRITE_NAME}.s3.${REGION}.amazo
 export const BUCKET_READ_DNS_NAME = 'bigbrain-zth-mf-assets';
 export 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).
+export 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.
@@ -54,6 +57,8 @@ export const MANIFEST_READ_URL = `${BUCKET_READ_DNS_URL}/${MANIFEST_KEY}`;
 // upfront for friendlier errors.
 export const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{1,49}$/;
 
+export 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.

package/src/index.ts

@@ -4,7 +4,6 @@ import path from 'node:path';
 import { Command } from 'commander';
 import { execa } from 'execa';
 import { getWorkspaceHome } from './util/workspace';
-import { devCommand } from './commands/dev';
 import { buildCommand } from './commands/build';
 import { cleanCommand } from './commands/clean';
 import { deployCommand } from './commands/deploy';
@@ -88,18 +87,6 @@ async function main(): Promise<void> {
       }
     });
 
-  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: { open?: boolean }) => {
-      try {
-        await devCommand(opts);
-      } catch (err) {
-        await fail(`dev failed: ${(err as Error).message}`, { command: 'dev' }, 2);
-      }
-    });
-
   program
     .command('clean')
     .description('Delete <consumer>/.zth/ and <consumer>/build/')
@@ -115,6 +102,11 @@ async function main(): Promise<void> {
     .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.'
@@ -123,19 +115,33 @@ async function main(): Promise<void> {
       '--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: { dryRun?: boolean; remote?: string; repoUrl?: string }) => {
-      try {
-        await trackDuration(
-          'z2h_app_deploy_success',
-          () => deployCommand(opts as Parameters<typeof deployCommand>[0]),
-          {
-            app_name: getCwdAppName(),
-          }
-        );
-      } catch (err) {
-        await fail(`deploy failed: ${(err as Error).message}`, { command: 'deploy' }, 2);
+    .action(
+      async (opts: {
+        dryRun?: boolean;
+        preview?: boolean | string;
+        open?: boolean;
+        remote?: string;
+        repoUrl?: string;
+      }) => {
+        try {
+          await trackDuration(
+            opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success',
+            () =>
+              deployCommand({
+                ...opts,
+                preview: Boolean(opts.preview),
+                previewId: typeof opts.preview === 'string' ? opts.preview : undefined,
+              } as Parameters<typeof deployCommand>[0]),
+            {
+              app_name: getCwdAppName(),
+            }
+          );
+        } catch (err) {
+          const label = opts.preview ? 'preview' : 'deploy';
+          await fail(`${label} failed: ${(err as Error).message}`, { command: label }, 2);
+        }
       }
-    });
+    );
 
   program
     .command('tag [app-name]')

package/src/migrations/006-remove-start-script.ts

@@ -0,0 +1,24 @@
+import type { Tree } from '@nx/devkit';
+
+// `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.
+export default function removeStartScript(tree: Tree): void {
+  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');
+    }
+  }
+}

package/src/shadow/__tests__/merge-package-json.test.ts

@@ -35,7 +35,6 @@ describe('buildShadowPkg', () => {
   it('uses plain trident scripts (no `-T`); bin resolves via the local devDep', () => {
     const shadow = buildShadowPkg({ name: 'demo' });
     expect(shadow.scripts).toEqual({
-      start: 'trident start',
       build: 'trident build',
     });
   });

package/src/templates/app/CLAUDE.md

@@ -37,9 +37,9 @@ When a request needs data, follow `z2h:coding-standards-mf` §0: write a `runQue
 
 - This folder is **standalone** — not part of any monorepo, no git initialized.
 - `src/index.tsx` default-exports the React component the host MF loads.
-- `package.json` wires the `z2h-cli` for `build` / `start` / `deploy`.
+- `package.json` wires the `z2h-cli` for `build` / `deploy`.
 - `.zth/` is an auto-generated shadow workspace — never edit it by hand; `z2h-cli clean` wipes it.
-- Local dev: `z2h-cli dev` → opens at `https://bigbrain.me/bigbrain-vibe/<app>?zth_local=<port>`.
+- Preview: `z2h-cli deploy --preview` → shareable, ephemeral link, no git, no live deploy.
 - Production: `z2h-cli deploy` → live at `https://bigbrain.me/bigbrain-vibe/<app>`.
 - There is no git, no PR, no CI. The gate is: lint pass → typecheck pass → user previews and approves.
 
@@ -78,6 +78,6 @@ Every step transition includes a time estimate. Transition pattern: what just fi
 
 ## Where the Skills Live
 
-The Z2H plugin is installed globally — every Claude session has access to `z2h:zero-to-hero`, `z2h:feature-development`, `z2h:run-mf-locally`, `z2h:plan`, etc. **Always go through `z2h:zero-to-hero`** for user requests; never invoke sub-skills directly.
+The Z2H plugin is installed globally — every Claude session has access to `z2h:zero-to-hero`, `z2h:feature-development`, `z2h:preview`, `z2h:plan`, etc. **Always go through `z2h:zero-to-hero`** for user requests; never invoke sub-skills directly.
 
 If `z2h:zero-to-hero` is not available in this session, the plugin isn't installed in the user's Claude config. Direct them to: `claude plugin marketplace add <bigbrain-z2h-path>` then `claude plugin install z2h`.

package/src/templates/app/package.json.tmpl

@@ -3,7 +3,6 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "start": "z2h-cli dev",
     "build": "z2h-cli build",
     "deploy": "z2h-cli deploy"
   }

package/src/templates/workspace/README.md

@@ -25,8 +25,8 @@ for the second flow.
 
 ```bash
 cd <app-name>
-z2h-cli dev      # local preview at https://bigbrain.me/bigbrain-vibe/<app>?zth_local=<port>
-z2h-cli deploy   # publishes to S3, live at https://bigbrain.me/bigbrain-vibe/<app>
+z2h-cli deploy --preview   # ephemeral, shareable link — no git, no live deploy
+z2h-cli deploy             # publishes to S3, live at https://bigbrain.me/bigbrain-vibe/<app>
 ```
 
 ## Reset

package/src/util/__tests__/app-name.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import { buildPreviewSlug, mfAppName, validateAppName } from '../app-name';
+import { APP_NAME_PATTERN } from '../../constants';
+
+const PREVIEW_ID = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
+
+describe('buildPreviewSlug', () => {
+  it('produces zth-preview-<8hex>-<realAppName>', () => {
+    const slug = buildPreviewSlug('my-app', PREVIEW_ID);
+    expect(slug).toBe('zth-preview-a1b2c3d4-my-app');
+  });
+
+  it('strips dashes from the previewId before taking the first 8 chars', () => {
+    const slug = buildPreviewSlug('my-app', PREVIEW_ID);
+    expect(slug.split('-').slice(0, 3).join('-')).toBe('zth-preview-a1b2c3d4');
+    expect(slug).not.toContain('a1b2-c3d4');
+  });
+
+  it('always yields an mf-prefixed appName that satisfies APP_NAME_PATTERN', () => {
+    const names = [
+      buildPreviewSlug('a', PREVIEW_ID),
+      buildPreviewSlug('my-app', PREVIEW_ID),
+      buildPreviewSlug('an-extremely-long-real-application-name-that-would-never-fit-on-its-own', PREVIEW_ID),
+    ];
+    for (const slug of names) {
+      const appName = mfAppName(slug);
+      expect(appName.length).toBeLessThanOrEqual(50);
+      expect(APP_NAME_PATTERN.test(appName)).toBe(true);
+    }
+  });
+
+  it('truncates a long real app name rather than exceeding the 50-char mf-prefixed cap', () => {
+    const longName = 'an-extremely-long-real-application-name-that-would-never-fit-on-its-own';
+    const slug = buildPreviewSlug(longName, PREVIEW_ID);
+    const appName = mfAppName(slug);
+    expect(appName.length).toBe(50);
+    expect(slug.startsWith('zth-preview-a1b2c3d4-')).toBe(true);
+  });
+
+  it('two different previewIds for the same real app name produce different slugs', () => {
+    const otherId = 'ffffffff-1111-2222-3333-444444444444';
+    expect(buildPreviewSlug('my-app', PREVIEW_ID)).not.toBe(buildPreviewSlug('my-app', otherId));
+  });
+
+  it('strips a scoped package name the same way mfAppName does, so the slug stays valid', () => {
+    const slug = buildPreviewSlug('@mondaydotcomorg/my-app', PREVIEW_ID);
+    expect(slug).toBe('zth-preview-a1b2c3d4-my-app');
+    expect(APP_NAME_PATTERN.test(mfAppName(slug))).toBe(true);
+  });
+
+  it('strips a trailing hyphen left dangling by the 47-char slice', () => {
+    // Prefix (12) + shortId (8) + '-' (1) = 21 chars before cleanRealAppName.
+    // A hyphen at cleanRealAppName[25] lands exactly on the 47-char cut.
+    const cleanRealAppName = `${'a'.repeat(25)}-${'z'.repeat(20)}`;
+    const slug = buildPreviewSlug(cleanRealAppName, PREVIEW_ID);
+    expect(slug.endsWith('-')).toBe(false);
+    expect(APP_NAME_PATTERN.test(mfAppName(slug))).toBe(true);
+  });
+});
+
+describe('validateAppName', () => {
+  it('accepts a valid kebab-case name', () => {
+    expect(() => validateAppName('my-app')).not.toThrow();
+  });
+
+  it('rejects names that fail APP_NAME_PATTERN', () => {
+    expect(() => validateAppName('My-App')).toThrow(/invalid/);
+    expect(() => validateAppName('-leading-dash')).toThrow(/invalid/);
+  });
+
+  it('rejects names reserved by the Z2H host', () => {
+    expect(() => validateAppName('generate-z2h-token')).toThrow(/reserved by the Z2H host/);
+  });
+
+  it('rejects names starting with the preview prefix', () => {
+    expect(() => validateAppName('zth-preview-abc123-foo')).toThrow(/reserved for the ephemeral preview mechanism/);
+  });
+});

package/src/util/app-name.ts

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { APP_NAME_PATTERN, PREVIEW_APP_NAME_PREFIX } from '../constants';
 
 /**
  * Strip any npm scope (`@scope/`) from a package name.
@@ -24,3 +25,57 @@ export function getCwdAppName(): string | undefined {
 export function mfAppName(name: string): string {
   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.
+ */
+export function validateAppName(appName: string): void {
+  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.
+ */
+export function buildPreviewSlug(appName: string, previewId: string): string {
+  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(/-+$/, '');
+}
+
+export function isPreviewAppName(appName: string): boolean {
+  return appName.startsWith(`mf-${PREVIEW_APP_NAME_PREFIX}`);
+}

package/src/util/auth/__tests__/broker-credential-provider.test.ts

@@ -65,7 +65,7 @@ describe('fetchDeployVersion', () => {
 });
 
 describe('brokerCredentialProvider', () => {
-  it('POSTs the appName + version to the broker with a Bearer token + parses the response', async () => {
+  it('POSTs the appName to the broker with a Bearer token + parses the response', async () => {
     const fetchMock = mockFetchOnce({ ...STUB_CREDS, expiration: FAR_FUTURE_EXPIRY });
     const provider = brokerCredentialProvider({ appName: 'my-app' });
     const creds = await provider();
@@ -145,4 +145,56 @@ describe('brokerCredentialProvider', () => {
     const provider = brokerCredentialProvider({ appName: 'my-app' });
     await expect(provider()).rejects.toThrow(/missing required credential fields/);
   });
+
+  describe('with previewId', () => {
+    it('POSTs appName + previewId to the same STS path with a Bearer token + parses the response', async () => {
+      const fetchMock = mockFetchOnce({ ...STUB_CREDS, expiration: FAR_FUTURE_EXPIRY });
+      const provider = brokerCredentialProvider({ appName: 'mf-my-app', previewId: 'preview-1' });
+      const creds = await provider();
+
+      expect(creds.accessKeyId).toBe('AKIA-stub');
+      expect(creds.secretAccessKey).toBe('secret-stub');
+      expect(creds.sessionToken).toBe('session-stub');
+      expect(creds.expiration?.toISOString()).toBe(FAR_FUTURE_EXPIRY);
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${DEFAULT_BROKER_BASE_URL}${STS_BROKER_PATH}`,
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({ appName: 'mf-my-app', previewId: 'preview-1' }),
+        })
+      );
+      const sent = (fetchMock.mock.calls[0][1] as RequestInit).headers as Record<string, string>;
+      expect(sent.Authorization).toBe('Bearer jwt-stub');
+    });
+
+    it('caches and coalesces calls when expiry is far away', async () => {
+      const fetchMock = mockFetchOnce({ ...STUB_CREDS, expiration: FAR_FUTURE_EXPIRY });
+      const provider = brokerCredentialProvider({ appName: 'mf-my-app', previewId: 'preview-1' });
+
+      const first = await provider();
+      await provider();
+      await provider();
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      const [a, b, c] = await Promise.all([provider(), provider(), provider()]);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      expect(a).toBe(first);
+      expect(b).toBe(first);
+      expect(c).toBe(first);
+    });
+
+    it('surfaces a remediation hint on 401', async () => {
+      mockFetchOnce({}, { status: 401, text: 'Unauthorized' });
+      const provider = brokerCredentialProvider({ appName: 'mf-my-app', previewId: 'preview-1' });
+      await expect(provider()).rejects.toThrow(/token rejected by the broker/);
+      await expect(provider()).rejects.toThrow(/generate-z2h-token/);
+    });
+
+    it('rejects responses missing required credential fields', async () => {
+      mockFetchOnce({ accessKeyId: 'AKIA-stub' });
+      const provider = brokerCredentialProvider({ appName: 'mf-my-app', previewId: 'preview-1' });
+      await expect(provider()).rejects.toThrow(/missing required credential fields/);
+    });
+  });
 });

package/src/util/auth/broker-credential-provider.ts

@@ -64,34 +64,40 @@ export async function fetchDeployVersion(appName: string): Promise<number> {
   return body.version ?? 0;
 }
 
-async function fetchStsOnce(appName: string): Promise<AwsCredentialIdentity> {
-  const res = await postToBroker(STS_BROKER_PATH, { appName });
+async function requestSts(path: string, body: unknown, errorLabel: string): Promise<AwsCredentialIdentity> {
+  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()) as CredentialsResponse;
-  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()) as CredentialsResponse;
+  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.
  */
-export function brokerCredentialProvider({ appName }: { appName: string }): AwsCredentialIdentityProvider {
+function createCachedCredentialProvider(
+  fetchOnce: () => Promise<AwsCredentialIdentity>
+): AwsCredentialIdentityProvider {
   let cached: AwsCredentialIdentity | undefined;
   let inflight: Promise<AwsCredentialIdentity> | undefined;
 
@@ -104,7 +110,7 @@ export function brokerCredentialProvider({ appName }: { appName: string }): AwsC
       return inflight;
     }
 
-    inflight = fetchStsOnce(appName)
+    inflight = fetchOnce()
       .then(credentials => {
         cached = credentials;
         return credentials;
@@ -115,3 +121,22 @@ export function brokerCredentialProvider({ appName }: { appName: string }): AwsC
     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.
+ */
+export function brokerCredentialProvider({
+  appName,
+  previewId,
+}: {
+  appName: string;
+  previewId?: string;
+}): AwsCredentialIdentityProvider {
+  return createCachedCredentialProvider(() =>
+    requestSts(STS_BROKER_PATH, { appName, previewId }, previewId ? 'preview' : 'deploy')
+  );
+}

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

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { registerOrUpdateApp } from '../app';
+import * as promptVisibility from '../../prompt-visibility';
+import type { ManifestEntry } from '../../manifest';
+
+vi.mock('../../prompt-visibility', () => ({
+  resolveAppVisibility: vi.fn(),
+}));
+
+function mockFetchOnce(status = 200) {
+  const fetchMock = vi.fn().mockResolvedValue({ ok: status < 400, status, text: async () => '' });
+  vi.stubGlobal('fetch', fetchMock);
+  return fetchMock;
+}
+
+const ENTRY: ManifestEntry = {
+  sameAsHost: false,
+  skipTranslationFetch: false,
+  shared: [],
+  entrypoints: ['main.js'],
+  version: 1,
+  url: 'https://cdn/x',
+  deployedBy: 'u@x.com',
+  gitRemote: '',
+};
+
+describe('registerOrUpdateApp', () => {
+  beforeEach(() => {
+    vi.mocked(promptVisibility.resolveAppVisibility).mockReset().mockResolvedValue('private');
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('registers (not updates) when nextVersion is 1, prompting for visibility', async () => {
+    const fetchMock = mockFetchOnce();
+
+    await registerOrUpdateApp({
+      appName: 'mf-my-app',
+      token: 'jwt',
+      nextVersion: 1,
+      entry: ENTRY,
+      gitRemote: '',
+    });
+
+    expect(promptVisibility.resolveAppVisibility).toHaveBeenCalledWith('mf-my-app');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [calledUrl, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(calledUrl).toContain('/z2h-cli/apps/register');
+    expect(JSON.parse(init.body as string)).toMatchObject({
+      appName: 'mf-my-app',
+      version: 1,
+      visibility: 'private',
+      gitRemote: '',
+    });
+  });
+
+  it('updates (not registers) when nextVersion > 1, without prompting for visibility', async () => {
+    const fetchMock = mockFetchOnce();
+
+    await registerOrUpdateApp({
+      appName: 'mf-my-app',
+      token: 'jwt',
+      nextVersion: 3,
+      entry: ENTRY,
+      gitRemote: '',
+    });
+
+    expect(promptVisibility.resolveAppVisibility).not.toHaveBeenCalled();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [calledUrl, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(calledUrl).toContain('/z2h-cli/apps/update');
+    expect(JSON.parse(init.body as string)).toMatchObject({ appName: 'mf-my-app', version: 3 });
+  });
+
+  it('propagates a registration failure', async () => {
+    mockFetchOnce(409);
+
+    await expect(
+      registerOrUpdateApp({
+        appName: 'mf-my-app',
+        token: 'jwt',
+        nextVersion: 1,
+        entry: ENTRY,
+        gitRemote: '',
+      })
+    ).rejects.toThrow(/App registration failed/);
+  });
+
+  it('propagates an update failure', async () => {
+    mockFetchOnce(500);
+
+    await expect(
+      registerOrUpdateApp({
+        appName: 'mf-my-app',
+        token: 'jwt',
+        nextVersion: 2,
+        entry: ENTRY,
+        gitRemote: '',
+      })
+    ).rejects.toThrow(/App update failed/);
+  });
+});