@mondaydotcomorg/z2h-cli 0.22.0 → 0.23.1-feat-z2h-beta-poc-35890fa

package/dist/auth.d.ts

@@ -0,0 +1,3 @@
+export { generateZ2HTokenCommand, type GenerateZ2HTokenOptions } from './commands/generate-z2h-token';
+export { readZthAuth, Z2hAuthMissingError, Z2H_AUTH_FILE, type ZthAuth } from './util/auth/auth-store';
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,KAAK,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACtG,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/auth.js

@@ -0,0 +1,11 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const commands_generateZ2hToken = require('./commands/generate-z2h-token.js');
+const util_auth_authStore = require('./util/auth/auth-store.js');
+
+
+
+exports.generateZ2HTokenCommand = commands_generateZ2hToken.generateZ2HTokenCommand;
+exports.Z2H_AUTH_FILE = util_auth_authStore.Z2H_AUTH_FILE;
+exports.Z2hAuthMissingError = util_auth_authStore.Z2hAuthMissingError;
+exports.readZthAuth = util_auth_authStore.readZthAuth;

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

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

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

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

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

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

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

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

package/dist/commands/beta.d.ts

@@ -0,0 +1,4 @@
+export declare function betaStatusCommand(): Promise<void>;
+export declare function enterBetaCommand(): Promise<void>;
+export declare function exitBetaCommand(): Promise<void>;
+//# sourceMappingURL=beta.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"beta.d.ts","sourceRoot":"","sources":["../../src/commands/beta.ts"],"names":[],"mappings":"AAuBA,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CA0BvD;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CA0BtD;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAgBrD"}

package/dist/commands/beta.js

@@ -0,0 +1,82 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const fs = require('fs-extra');
+const execa = require('execa');
+const util_logger = require('../util/logger.js');
+const util_beta_betaClient = require('../util/beta/beta-client.js');
+const util_beta_betaStore = require('../util/beta/beta-store.js');
+const util_updateScript = require('../util/update-script.js');
+
+async function converge() {
+    if (!(await fs.pathExists(util_updateScript.UPDATE_SCRIPT_PATH))) {
+        util_logger.warn(`update script not found at ${util_updateScript.UPDATE_SCRIPT_PATH} — skipping convergence`);
+        return;
+    }
+    try {
+        await execa.execa('bash', [util_updateScript.UPDATE_SCRIPT_PATH], { stdio: 'inherit' });
+    }
+    catch (err) {
+        util_logger.warn(`convergence failed: ${err.message}\nYour beta choice is saved — run 'bash ${util_updateScript.UPDATE_SCRIPT_PATH}' to retry.`);
+    }
+}
+async function betaStatusCommand() {
+    const active = await util_beta_betaStore.readBetaState();
+    if (!active) {
+        util_logger.output("[z2h-cli] you're not on a beta — run 'z2h-cli beta enter' to check for one and join", {
+            published: null,
+            active: null,
+        });
+        return;
+    }
+    const published = await util_beta_betaClient.fetchPublishedBeta();
+    if (!published) {
+        util_logger.output(`[z2h-cli] beta "${active.id}" is no longer published — converging back to stable in the background now`, {
+            published: null,
+            active: active.id,
+        });
+        return;
+    }
+    const inIt = active.id === published.id;
+    util_logger.output(`[z2h-cli] beta "${published.id}" — ${published.description} (${inIt ? "you're in it" : 'not in it'})`, {
+        published: published.id,
+        active: active.id,
+    });
+}
+async function enterBetaCommand() {
+    const active = await util_beta_betaStore.readBetaState();
+    if (active) {
+        throw new Error(`already on beta "${active.id}" — run 'z2h-cli beta exit' first`);
+    }
+    const beta = await util_beta_betaClient.fetchPublishedBeta();
+    if (!beta) {
+        throw new Error('no beta published right now');
+    }
+    await util_beta_betaStore.writeBetaState({
+        id: beta.id,
+        description: beta.description,
+        cliVersion: beta.cliVersion,
+        skillsBranch: beta.skillsBranch,
+        hostMfVersion: beta.hostMfVersion,
+    });
+    util_logger.info(`entering beta "${beta.id}" — ${beta.description}`);
+    await converge();
+    util_logger.output(`[z2h-cli] you're on beta "${beta.id}". Start a new Claude Code / Cursor session to pick up any skills change.`, { ok: true, beta: beta.id });
+}
+async function exitBetaCommand() {
+    const active = await util_beta_betaStore.readBetaState();
+    await util_beta_betaStore.clearBetaState();
+    if (!active) {
+        util_logger.output("[z2h-cli] no beta was active — you're already on stable", { ok: true, beta: null });
+        return;
+    }
+    util_logger.info(`leaving beta "${active.id}"`);
+    await converge();
+    util_logger.output("[z2h-cli] you're back on stable. Start a new Claude Code / Cursor session to pick up the change.", {
+        ok: true,
+        beta: null,
+    });
+}
+
+exports.betaStatusCommand = betaStatusCommand;
+exports.enterBetaCommand = enterBetaCommand;
+exports.exitBetaCommand = exitBetaCommand;

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

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

package/dist/commands/deploy.js

@@ -9,6 +9,8 @@ const util_s3_upload = require('../util/s3/upload.js');
 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_beta_betaStore = require('../util/beta/beta-store.js');
+const util_beta_pinHostMfVersion = require('../util/beta/pin-host-mf-version.js');
 const util_appName = require('../util/app-name.js');
 const util_git_repo = require('../util/git/repo.js');
 const util_git_gitEnv = require('../util/git/git-env.js');
@@ -90,6 +92,7 @@ async function uploadAndRegister(opts) {
     await util_broker_app.registerOrUpdateApp({ appName, token, nextVersion, entry, gitRemote, integrations, description });
 }
 async function deployPreview({ paths, consumerName, appName, token, opts }) {
+    const activeBeta = await util_beta_betaStore.readBetaState();
     await fs.ensureDir(paths.shadowDir);
     const { previewId } = await shadow_prepare.resolvePortAndMetadata(paths, util_appName.cleanAppName(consumerName));
     const previewSlug = util_appName.buildPreviewSlug(consumerName, previewId);
@@ -114,7 +117,7 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
         gitRemote: '',
         isPreview: true,
     });
-    const previewUrl = `https://bigbrain.me/bigbrain-vibe/${previewSlug}`;
+    const previewUrl = util_beta_pinHostMfVersion.pinHostMfVersion(`https://bigbrain.me/bigbrain-vibe/${previewSlug}`, activeBeta?.hostMfVersion);
     util_logger.output(`[z2h-cli] preview ready ✅\n  app:            ${appName}\n  previewAppName: ${previewAppName}\n  open:           ${previewUrl}`, {
         ok: true,
         appName,
@@ -130,6 +133,7 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
     }
 }
 async function deployLive({ paths, consumerName, appName, token, opts }) {
+    const activeBeta = await util_beta_betaStore.readBetaState();
     let gitRemote = await util_git_repo.getRemoteUrl(process.cwd());
     if (gitRemote) {
         if (opts.remote || opts.repoUrl) {
@@ -220,7 +224,7 @@ async function deployLive({ paths, consumerName, appName, token, 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(consumerName)}`;
+    const liveUrl = util_beta_pinHostMfVersion.pinHostMfVersion(`https://bigbrain.me/bigbrain-vibe/${util_appName.cleanAppName(consumerName)}`, activeBeta?.hostMfVersion);
     util_logger.output(`[z2h-cli] deployed ✅\n  app:     ${appName}\n  version: ${nextVersion}\n  open:    ${liveUrl}`, {
         ok: true,
         appName,

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

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

package/dist/commands/doctor.js

@@ -11,6 +11,7 @@ const pc = require('picocolors');
 const util_logger = require('../util/logger.js');
 const util_workspace = require('../util/workspace.js');
 const util_auth_authStore = require('../util/auth/auth-store.js');
+const util_beta_betaStore = require('../util/beta/beta-store.js');
 const constants = require('../constants.js');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -102,7 +103,9 @@ function checkGitRemoteS3() {
 }
 async function checkZ2hCli() {
     const { version } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('commands/doctor.js', document.baseURI).href)))('../../package.json');
-    let latestVersion;
+    const activeBeta = await util_beta_betaStore.readBetaState();
+    const targetTag = activeBeta?.cliVersion ?? 'latest';
+    let targetVersion;
     try {
         const token = util_auth_authStore.tryReadAuthTokenSync();
         if (token) {
@@ -112,17 +115,40 @@ async function checkZ2hCli() {
             });
             if (res.ok) {
                 const data = (await res.json());
-                latestVersion = data['dist-tags']?.latest;
+                targetVersion = data['dist-tags']?.[targetTag];
             }
         }
     }
     catch {
         // version check is best-effort — no network / token not ready
     }
-    if (latestVersion && latestVersion !== version) {
-        return { label: 'z2h-cli', status: 'warn', detail: `${version} (latest: ${latestVersion})`, fix: UPDATE_CMD };
+    if (targetVersion && targetVersion !== version) {
+        return {
+            label: 'z2h-cli',
+            status: 'warn',
+            detail: `${version} (${targetTag}: ${targetVersion})`,
+            fix: UPDATE_CMD,
+        };
+    }
+    return {
+        label: 'z2h-cli',
+        status: 'ok',
+        detail: targetVersion ? `${version} (up to date on ${targetTag})` : version,
+    };
+}
+async function checkActiveBeta() {
+    const active = await util_beta_betaStore.readBetaState();
+    if (!active) {
+        return { label: 'beta', status: 'ok', detail: 'none — stable' };
     }
-    return { label: 'z2h-cli', status: 'ok', detail: latestVersion ? `${version} (up to date)` : version };
+    const pins = [
+        active.cliVersion && `cli@${active.cliVersion}`,
+        active.skillsBranch && `skills@${active.skillsBranch}`,
+        active.hostMfVersion && `hostMf@${active.hostMfVersion}`,
+    ]
+        .filter(Boolean)
+        .join(', ');
+    return { label: 'beta', status: 'ok', detail: pins ? `${active.id} (${pins})` : active.id };
 }
 async function checkAuthToken() {
     try {
@@ -264,7 +290,7 @@ async function doctorCommand() {
         // treat as missing
     }
     const systemChecks = await Promise.all([checkNvm(), checkNode(), checkYarn(), checkAws(), checkGitRemoteS3()]);
-    const cliChecks = await Promise.all([checkZ2hCli(), checkAuthToken(), checkNpmTokenInProfile()]);
+    const cliChecks = await Promise.all([checkZ2hCli(), checkAuthToken(), checkNpmTokenInProfile(), checkActiveBeta()]);
     const workspaceChecks = await Promise.all([checkWorkspace(), checkReactVersion()]);
     const pluginChecks = await Promise.all([
         checkPlugin('z2h@bigbrain-z2h', 'z2h plugin', true, pluginsJson),

package/dist/commands/migrate.d.ts

@@ -1,3 +1,4 @@
+export declare function baseVersion(version: string): string;
 export interface MigrateOptions {
     dryRun?: boolean;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AA6CA,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkGjG"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AA4BA,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnD;AAqBD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmGjG"}

package/dist/commands/migrate.js

@@ -16,6 +16,15 @@ const semver__default = /*#__PURE__*/_interopDefault(semver);
 
 const STATE_FILE = '.z2h-migrations-state.json';
 // ─── Helpers ───
+// A prerelease sorts BELOW its own release under plain semver ordering, so
+// comparing raw beta versions here would skip migrations the beta introduced.
+function baseVersion(version) {
+    const parsed = semver__default.default.parse(version);
+    if (!parsed) {
+        throw new Error(`invalid semver version: ${version}`);
+    }
+    return `${parsed.major}.${parsed.minor}.${parsed.patch}`;
+}
 async function readMigrationState(workspaceHome) {
     const statePath = path__default.default.join(workspaceHome, STATE_FILE);
     if (!(await fs.pathExists(statePath))) {
@@ -40,11 +49,12 @@ async function migrateCommand(cliVersion, opts = {}) {
     }
     const state = await readMigrationState(workspaceHome);
     const lastVersion = state?.lastMigratedVersion ?? '0.0.0';
-    if (!semver__default.default.gt(cliVersion, lastVersion)) {
+    const targetVersion = baseVersion(cliVersion);
+    if (!semver__default.default.gt(targetVersion, lastVersion)) {
         util_logger.info('workspace is up to date — no migrations pending');
         return;
     }
-    util_logger.info(`migrating workspace from v${lastVersion} → v${cliVersion}...`);
+    util_logger.info(`migrating workspace from v${lastVersion} → v${targetVersion}...`);
     // migrations.json is at the package root — two dirs up from dist/migrations/
     const thisDir = path__default.default.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('commands/migrate.js', document.baseURI).href))));
     const migrationsJsonPath = path__default.default.resolve(thisDir, '..', '..', 'migrations.json');
@@ -53,12 +63,12 @@ async function migrateCommand(cliVersion, opts = {}) {
         return;
     }
     const migrationsJson = (await fs.readJson(migrationsJsonPath));
-    // Filter to pending migrations (version > lastVersion AND <= cliVersion).
+    // Filter to pending migrations (version > lastVersion AND <= targetVersion).
     // CONVENTION: a migration's `version` field must equal the CLI release it
     // ships with (not the feature branch version). This ensures the `gt` check
     // always catches a migration on the exact upgrade that introduces it.
     const pending = Object.entries(migrationsJson.migrations)
-        .filter(([, entry]) => semver__default.default.gt(entry.version, lastVersion) && semver__default.default.lte(entry.version, cliVersion))
+        .filter(([, entry]) => semver__default.default.gt(entry.version, lastVersion) && semver__default.default.lte(entry.version, targetVersion))
         .sort(([, a], [, b]) => semver__default.default.compare(a.version, b.version));
     if (opts.dryRun) {
         util_logger.info(`${pending.length} pending migration(s) (dry-run — no changes will be applied):`);
@@ -68,7 +78,7 @@ async function migrateCommand(cliVersion, opts = {}) {
         return;
     }
     if (pending.length === 0) {
-        await writeMigrationState(workspaceHome, { lastMigratedVersion: cliVersion });
+        await writeMigrationState(workspaceHome, { lastMigratedVersion: targetVersion });
         return;
     }
     const nxReady = await util_workspace.ensureWorkspaceNx(workspaceHome);
@@ -108,8 +118,9 @@ async function migrateCommand(cliVersion, opts = {}) {
     if (needsInstall) {
         await util_workspace.runYarnInstall(workspaceHome, 'package.json changed');
     }
-    await writeMigrationState(workspaceHome, { lastMigratedVersion: cliVersion });
+    await writeMigrationState(workspaceHome, { lastMigratedVersion: targetVersion });
     util_logger.info('workspace migrations complete.');
 }
 
+exports.baseVersion = baseVersion;
 exports.migrateCommand = migrateCommand;

package/dist/esm/auth.d.ts

@@ -0,0 +1,3 @@
+export { generateZ2HTokenCommand, type GenerateZ2HTokenOptions } from './commands/generate-z2h-token';
+export { readZthAuth, Z2hAuthMissingError, Z2H_AUTH_FILE, type ZthAuth } from './util/auth/auth-store';
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,KAAK,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACtG,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/esm/auth.mjs

@@ -0,0 +1,2 @@
+export { generateZ2HTokenCommand } from './commands/generate-z2h-token.mjs';
+export { Z2H_AUTH_FILE, Z2hAuthMissingError, readZthAuth } from './util/auth/auth-store.mjs';

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,4 @@
+export declare function betaStatusCommand(): Promise<void>;
+export declare function enterBetaCommand(): Promise<void>;
+export declare function exitBetaCommand(): Promise<void>;
+//# sourceMappingURL=beta.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"beta.d.ts","sourceRoot":"","sources":["../../../src/commands/beta.ts"],"names":[],"mappings":"AAuBA,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CA0BvD;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CA0BtD;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAgBrD"}

package/dist/esm/commands/beta.mjs

@@ -0,0 +1,78 @@
+import { pathExists } from 'fs-extra';
+import { execa } from 'execa';
+import { output, info, warn } from '../util/logger.mjs';
+import { fetchPublishedBeta } from '../util/beta/beta-client.mjs';
+import { readBetaState, writeBetaState, clearBetaState } from '../util/beta/beta-store.mjs';
+import { UPDATE_SCRIPT_PATH } from '../util/update-script.mjs';
+
+async function converge() {
+    if (!(await pathExists(UPDATE_SCRIPT_PATH))) {
+        warn(`update script not found at ${UPDATE_SCRIPT_PATH} — skipping convergence`);
+        return;
+    }
+    try {
+        await execa('bash', [UPDATE_SCRIPT_PATH], { stdio: 'inherit' });
+    }
+    catch (err) {
+        warn(`convergence failed: ${err.message}\nYour beta choice is saved — run 'bash ${UPDATE_SCRIPT_PATH}' to retry.`);
+    }
+}
+async function betaStatusCommand() {
+    const active = await readBetaState();
+    if (!active) {
+        output("[z2h-cli] you're not on a beta — run 'z2h-cli beta enter' to check for one and join", {
+            published: null,
+            active: null,
+        });
+        return;
+    }
+    const published = await fetchPublishedBeta();
+    if (!published) {
+        output(`[z2h-cli] beta "${active.id}" is no longer published — converging back to stable in the background now`, {
+            published: null,
+            active: active.id,
+        });
+        return;
+    }
+    const inIt = active.id === published.id;
+    output(`[z2h-cli] beta "${published.id}" — ${published.description} (${inIt ? "you're in it" : 'not in it'})`, {
+        published: published.id,
+        active: active.id,
+    });
+}
+async function enterBetaCommand() {
+    const active = await readBetaState();
+    if (active) {
+        throw new Error(`already on beta "${active.id}" — run 'z2h-cli beta exit' first`);
+    }
+    const beta = await fetchPublishedBeta();
+    if (!beta) {
+        throw new Error('no beta published right now');
+    }
+    await writeBetaState({
+        id: beta.id,
+        description: beta.description,
+        cliVersion: beta.cliVersion,
+        skillsBranch: beta.skillsBranch,
+        hostMfVersion: beta.hostMfVersion,
+    });
+    info(`entering beta "${beta.id}" — ${beta.description}`);
+    await converge();
+    output(`[z2h-cli] you're on beta "${beta.id}". Start a new Claude Code / Cursor session to pick up any skills change.`, { ok: true, beta: beta.id });
+}
+async function exitBetaCommand() {
+    const active = await readBetaState();
+    await clearBetaState();
+    if (!active) {
+        output("[z2h-cli] no beta was active — you're already on stable", { ok: true, beta: null });
+        return;
+    }
+    info(`leaving beta "${active.id}"`);
+    await converge();
+    output("[z2h-cli] you're back on stable. Start a new Claude Code / Cursor session to pick up the change.", {
+        ok: true,
+        beta: null,
+    });
+}
+
+export { betaStatusCommand, enterBetaCommand, exitBetaCommand };

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

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

package/dist/esm/commands/deploy.mjs

@@ -7,6 +7,8 @@ import { uploadDir } from '../util/s3/upload.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 { readBetaState } from '../util/beta/beta-store.mjs';
+import { pinHostMfVersion } from '../util/beta/pin-host-mf-version.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';
@@ -84,6 +86,7 @@ async function uploadAndRegister(opts) {
     await registerOrUpdateApp({ appName, token, nextVersion, entry, gitRemote, integrations, description });
 }
 async function deployPreview({ paths, consumerName, appName, token, opts }) {
+    const activeBeta = await readBetaState();
     await ensureDir(paths.shadowDir);
     const { previewId } = await resolvePortAndMetadata(paths, cleanAppName(consumerName));
     const previewSlug = buildPreviewSlug(consumerName, previewId);
@@ -108,7 +111,7 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
         gitRemote: '',
         isPreview: true,
     });
-    const previewUrl = `https://bigbrain.me/bigbrain-vibe/${previewSlug}`;
+    const previewUrl = pinHostMfVersion(`https://bigbrain.me/bigbrain-vibe/${previewSlug}`, activeBeta?.hostMfVersion);
     output(`[z2h-cli] preview ready ✅\n  app:            ${appName}\n  previewAppName: ${previewAppName}\n  open:           ${previewUrl}`, {
         ok: true,
         appName,
@@ -124,6 +127,7 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
     }
 }
 async function deployLive({ paths, consumerName, appName, token, opts }) {
+    const activeBeta = await readBetaState();
     let gitRemote = await getRemoteUrl(process.cwd());
     if (gitRemote) {
         if (opts.remote || opts.repoUrl) {
@@ -214,7 +218,7 @@ async function deployLive({ paths, consumerName, appName, token, 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(consumerName)}`;
+    const liveUrl = pinHostMfVersion(`https://bigbrain.me/bigbrain-vibe/${cleanAppName(consumerName)}`, activeBeta?.hostMfVersion);
     output(`[z2h-cli] deployed ✅\n  app:     ${appName}\n  version: ${nextVersion}\n  open:    ${liveUrl}`, {
         ok: true,
         appName,

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

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

package/dist/esm/commands/doctor.mjs

@@ -9,6 +9,7 @@ import pc from 'picocolors';
 import { getOutputMode, output } from '../util/logger.mjs';
 import { getWorkspaceHome, isZ2hWorkspace } from '../util/workspace.mjs';
 import { tryReadAuthTokenSync, Z2H_AUTH_FILE } from '../util/auth/auth-store.mjs';
+import { readBetaState } from '../util/beta/beta-store.mjs';
 import { brokerNpmRegistryUrl, routingHeaders } from '../constants.mjs';
 
 const HOME = os.homedir();
@@ -92,7 +93,9 @@ function checkGitRemoteS3() {
 }
 async function checkZ2hCli() {
     const { version } = createRequire(import.meta.url)('../../package.json');
-    let latestVersion;
+    const activeBeta = await readBetaState();
+    const targetTag = activeBeta?.cliVersion ?? 'latest';
+    let targetVersion;
     try {
         const token = tryReadAuthTokenSync();
         if (token) {
@@ -102,17 +105,40 @@ async function checkZ2hCli() {
             });
             if (res.ok) {
                 const data = (await res.json());
-                latestVersion = data['dist-tags']?.latest;
+                targetVersion = data['dist-tags']?.[targetTag];
             }
         }
     }
     catch {
         // version check is best-effort — no network / token not ready
     }
-    if (latestVersion && latestVersion !== version) {
-        return { label: 'z2h-cli', status: 'warn', detail: `${version} (latest: ${latestVersion})`, fix: UPDATE_CMD };
+    if (targetVersion && targetVersion !== version) {
+        return {
+            label: 'z2h-cli',
+            status: 'warn',
+            detail: `${version} (${targetTag}: ${targetVersion})`,
+            fix: UPDATE_CMD,
+        };
+    }
+    return {
+        label: 'z2h-cli',
+        status: 'ok',
+        detail: targetVersion ? `${version} (up to date on ${targetTag})` : version,
+    };
+}
+async function checkActiveBeta() {
+    const active = await readBetaState();
+    if (!active) {
+        return { label: 'beta', status: 'ok', detail: 'none — stable' };
     }
-    return { label: 'z2h-cli', status: 'ok', detail: latestVersion ? `${version} (up to date)` : version };
+    const pins = [
+        active.cliVersion && `cli@${active.cliVersion}`,
+        active.skillsBranch && `skills@${active.skillsBranch}`,
+        active.hostMfVersion && `hostMf@${active.hostMfVersion}`,
+    ]
+        .filter(Boolean)
+        .join(', ');
+    return { label: 'beta', status: 'ok', detail: pins ? `${active.id} (${pins})` : active.id };
 }
 async function checkAuthToken() {
     try {
@@ -254,7 +280,7 @@ async function doctorCommand() {
         // treat as missing
     }
     const systemChecks = await Promise.all([checkNvm(), checkNode(), checkYarn(), checkAws(), checkGitRemoteS3()]);
-    const cliChecks = await Promise.all([checkZ2hCli(), checkAuthToken(), checkNpmTokenInProfile()]);
+    const cliChecks = await Promise.all([checkZ2hCli(), checkAuthToken(), checkNpmTokenInProfile(), checkActiveBeta()]);
     const workspaceChecks = await Promise.all([checkWorkspace(), checkReactVersion()]);
     const pluginChecks = await Promise.all([
         checkPlugin('z2h@bigbrain-z2h', 'z2h plugin', true, pluginsJson),

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

@@ -1,3 +1,4 @@
+export declare function baseVersion(version: string): string;
 export interface MigrateOptions {
     dryRun?: boolean;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../src/commands/migrate.ts"],"names":[],"mappings":"AA6CA,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkGjG"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../src/commands/migrate.ts"],"names":[],"mappings":"AA4BA,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnD;AAqBD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmGjG"}