@mondaydotcomorg/z2h-cli 0.4.1 → 0.5.1

package/dist/migrations/auto-migrate.js

@@ -0,0 +1,174 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const path = require('node:path');
+const node_module = require('node:module');
+const node_url = require('node:url');
+const fsExtra = require('fs-extra');
+const execa = require('execa');
+const semver = require('semver');
+const util_logger = require('../util/logger.js');
+const util_workspace = require('../util/workspace.js');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+const semver__default = /*#__PURE__*/_interopDefault(semver);
+
+const STATE_FILE = '.z2h-migrations-state.json';
+const NX_JSON_CONTENT = '{\n  "extends": "@mondaydotcomorg/trident-monorepo/presets/nx.json"\n}\n';
+// ─── Helpers ───
+async function readState(workspaceHome) {
+    const statePath = path__default.default.join(workspaceHome, STATE_FILE);
+    if (!(await fsExtra.pathExists(statePath))) {
+        return null;
+    }
+    try {
+        return (await fsExtra.readJson(statePath));
+    }
+    catch {
+        return null;
+    }
+}
+async function writeState(workspaceHome, state) {
+    const statePath = path__default.default.join(workspaceHome, STATE_FILE);
+    await fsExtra.writeJson(statePath, state, { spaces: 2 });
+}
+async function yarnInstall(workspaceHome, context) {
+    util_logger.info(`${context} — running yarn install...`);
+    try {
+        await execa.execa('yarn', ['install'], { cwd: workspaceHome, stdio: 'pipe' });
+        return true;
+    }
+    catch (err) {
+        const stderr = err.stderr || err.message;
+        util_logger.warn(`yarn install failed: ${stderr}`);
+        return false;
+    }
+}
+async function getLatestTrientMonorepoVersion() {
+    try {
+        const { stdout } = await execa.execa('npm', ['view', '@mondaydotcomorg/trident-monorepo', 'version']);
+        return `^${stdout.trim()}`;
+    }
+    catch {
+        return '*';
+    }
+}
+// ─── Workspace bootstrap ───
+function isNxAvailable(workspaceHome) {
+    try {
+        const wsRequire = node_module.createRequire(path__default.default.join(workspaceHome, 'package.json'));
+        wsRequire.resolve('nx/src/generators/tree');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureWorkspaceNx(workspaceHome) {
+    const nxJsonPath = path__default.default.join(workspaceHome, 'nx.json');
+    const pkgPath = path__default.default.join(workspaceHome, 'package.json');
+    if (!(await fsExtra.pathExists(nxJsonPath))) {
+        await fsExtra.writeFile(nxJsonPath, NX_JSON_CONTENT);
+        util_logger.info('added nx.json to workspace');
+    }
+    const pkg = (await fsExtra.readJson(pkgPath));
+    if (!pkg.devDependencies?.['@mondaydotcomorg/trident-monorepo']) {
+        pkg.devDependencies = pkg.devDependencies ?? {};
+        pkg.devDependencies['@mondaydotcomorg/trident-monorepo'] = await getLatestTrientMonorepoVersion();
+    }
+    if (!pkg.scripts?.nx) {
+        pkg.scripts = pkg.scripts ?? {};
+        pkg.scripts.nx = 'nx';
+    }
+    await fsExtra.writeJson(pkgPath, pkg, { spaces: 2 });
+    // Only install if NX isn't already importable from the workspace
+    if (!isNxAvailable(workspaceHome)) {
+        const ok = await yarnInstall(workspaceHome, 'NX not found, installing');
+        if (!ok) {
+            util_logger.warn('workspace migrations require NX. Fix the install error and run "z2h-cli migrate" to retry.');
+            return false;
+        }
+    }
+    return true;
+}
+// ─── Main ───
+async function autoMigrate(cliVersion, dryRun = false) {
+    const workspaceHome = util_workspace.getWorkspaceHome();
+    if (!(await util_workspace.isZ2hWorkspace(workspaceHome))) {
+        util_logger.warn('no Z2H workspace found');
+        return;
+    }
+    const state = await readState(workspaceHome);
+    const lastVersion = state?.lastMigratedVersion ?? '0.0.0';
+    if (!semver__default.default.gt(cliVersion, lastVersion)) {
+        util_logger.info('workspace is up to date — no migrations pending');
+        return;
+    }
+    util_logger.info(`migrating workspace from v${lastVersion} → v${cliVersion}...`);
+    // 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('migrations/auto-migrate.js', document.baseURI).href))));
+    const migrationsJsonPath = path__default.default.resolve(thisDir, '..', '..', 'migrations.json');
+    if (!(await fsExtra.pathExists(migrationsJsonPath))) {
+        util_logger.warn('migrations.json not found — skipping migrations');
+        return;
+    }
+    const migrationsJson = (await fsExtra.readJson(migrationsJsonPath));
+    // Filter to pending migrations (version > lastVersion AND <= cliVersion)
+    const pending = Object.entries(migrationsJson.migrations)
+        .filter(([, entry]) => semver__default.default.gt(entry.version, lastVersion) && semver__default.default.lte(entry.version, cliVersion))
+        .sort(([, a], [, b]) => semver__default.default.compare(a.version, b.version));
+    if (dryRun) {
+        util_logger.info(`${pending.length} pending migration(s) (dry-run — no changes will be applied):`);
+        for (const [, entry] of pending) {
+            util_logger.info(`  - ${entry.description} (v${entry.version})`);
+        }
+        return;
+    }
+    if (pending.length === 0) {
+        await writeState(workspaceHome, { lastMigratedVersion: cliVersion });
+        return;
+    }
+    const nxReady = await ensureWorkspaceNx(workspaceHome);
+    if (!nxReady) {
+        return;
+    }
+    util_logger.info(`applying ${pending.length} workspace migration(s)...`);
+    // Resolve NX from the workspace's node_modules (not from CLI's own deps)
+    const wsRequire = node_module.createRequire(path__default.default.join(workspaceHome, 'package.json'));
+    const { FsTree, flushChanges } = wsRequire('nx/src/generators/tree');
+    let needsInstall = false;
+    for (const [name, entry] of pending) {
+        const tree = new FsTree(workspaceHome, false);
+        try {
+            const factoryPath = path__default.default.resolve(path__default.default.dirname(migrationsJsonPath), entry.migrate);
+            const mod = require(factoryPath);
+            const fn = mod.default || mod;
+            fn(tree);
+            const changes = tree.listChanges();
+            if (changes.length > 0) {
+                if (changes.some(c => c.path.endsWith('package.json'))) {
+                    needsInstall = true;
+                }
+                flushChanges(workspaceHome, changes);
+                util_logger.info(`  ✓ ${entry.description}`);
+            }
+            else {
+                util_logger.info(`  ○ ${entry.description} (no changes needed)`);
+            }
+        }
+        catch (err) {
+            util_logger.warn(`  ✗ migration "${name}" failed: ${err.message}`);
+            util_logger.warn('    skipping remaining migrations. Run "z2h-cli migrate" to retry.');
+            return;
+        }
+    }
+    if (needsInstall) {
+        await yarnInstall(workspaceHome, 'package.json changed');
+    }
+    await writeState(workspaceHome, { lastMigratedVersion: cliVersion });
+    util_logger.info('workspace migrations complete.');
+}
+
+exports.autoMigrate = autoMigrate;

package/dist/templates/workspace/nx.js

@@ -0,0 +1,7 @@
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+
+const nx = {
+	"extends": "@mondaydotcomorg/trident-monorepo/presets/nx.json"
+};
+
+exports.default = nx;

package/migrations.json

@@ -0,0 +1,14 @@
+{
+  "migrations": {
+    "remove-per-consumer-yarnrc": {
+      "version": "0.4.1",
+      "description": "Remove per-consumer .yarnrc.yml files (workspace root provides config)",
+      "migrate": "./dist/migrations/001-remove-per-consumer-yarnrc"
+    },
+    "remove-z2h-cli-from-workspace-deps": {
+      "version": "0.4.1",
+      "description": "Remove z2h-cli from workspace and consumer devDependencies (managed globally)",
+      "migrate": "./dist/migrations/002-remove-z2h-cli-from-workspace-deps"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -34,7 +34,8 @@
   "files": [
     "bin/",
     "dist/",
-    "src/"
+    "src/",
+    "migrations.json"
   ],
   "dependencies": {
     "@aws-sdk/client-s3": "^3.706.0",
@@ -47,18 +48,24 @@
     "mime-types": "^2.1.35",
     "p-map": "^7.0.2",
     "picocolors": "^1.1.1",
+    "semver": "^7.6.0",
     "tsx": "^4.19.2"
   },
   "devDependencies": {
     "@mondaydotcomorg/trident-library": "^1.2.7",
+    "@nx/devkit": "^21.6.0",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
     "@types/fs-extra": "^11.0.4",
     "@types/mime-types": "^2.1.4",
     "@types/node": "^22.19.0",
+    "@types/semver": "^7.5.0",
     "typescript": "^5.7.2",
     "vitest": "^2.1.4"
   },
+  "engines": {
+    "node": ">=24"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/DaPulse/bigbrain-z2h.git",

package/src/commands/__tests__/create-workspace.test.ts

@@ -61,13 +61,11 @@ describe('create-workspace', () => {
     expect(execa).not.toHaveBeenCalled();
   });
 
-  it('substitutes the current z2h-cli version into the workspace template', async () => {
+  it('does not include z2h-cli in workspace devDeps (managed globally)', async () => {
     await createWorkspaceCommand({});
 
     const pkg = await readJson(path.join(tmp, 'package.json'));
-    const cliDep = pkg.devDependencies['@mondaydotcomorg/z2h-cli'];
-    expect(cliDep).toBeTruthy();
-    expect(cliDep).not.toBe('__Z2H_CLI_VERSION__'); // should be substituted
+    expect(pkg.devDependencies['@mondaydotcomorg/z2h-cli']).toBeUndefined();
   });
 
   it('ships the yarn berry release inline so any `yarn` invocation runs 4.x without corepack', async () => {

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

@@ -70,7 +70,6 @@ describe('create', () => {
     const pkg = await readJson(path.join(appDir, 'package.json'));
     expect(pkg.name).toBe('demo-app');
     expect(pkg.private).toBe(true);
-    expect(pkg.scripts.start).toBe('z2h-cli dev');
 
     const indexSrc = (await import('node:fs/promises')).readFile;
     const content = await indexSrc(path.join(appDir, 'src', 'index.tsx'), 'utf8');

package/src/commands/create-workspace.ts

@@ -1,30 +1,15 @@
 import path from 'node:path';
 import { readFile } from 'node:fs/promises';
-import { ensureDir, readJson, writeFile, pathExists, readdir, copy } from 'fs-extra';
+import { ensureDir, writeFile, pathExists, readdir, copy } from 'fs-extra';
 import { execa } from 'execa';
 import { info, output, setOutputMode } from '../util/logger';
 import { getWorkspaceHome } from '../util/workspace';
-import { getTemplatesDir, renderTemplate } from '../util/templates';
+import { getTemplatesDir } from '../util/templates';
 
 export interface CreateWorkspaceOptions {
   json?: boolean;
 }
 
-/**
- * Read the current z2h-cli version from its own package.json — the version
- * that gets pinned into the workspace's devDependencies. That way the
- * workspace's `@mondaydotcomorg/z2h-cli` always matches the version that
- * bootstrapped it.
- */
-async function readCurrentCliVersion(): Promise<string> {
-  // util/templates.ts already locates `<package-root>/src/templates`. The
-  // package's own package.json sits two levels above templates/.
-  const templatesDir = getTemplatesDir();
-  const pkgPath = path.resolve(templatesDir, '..', '..', 'package.json');
-  const pkg = (await readJson(pkgPath)) as { version: string };
-  return `^${pkg.version}`;
-}
-
 export async function createWorkspaceCommand(opts: CreateWorkspaceOptions): Promise<void> {
   if (opts.json) {
     setOutputMode('json');
@@ -34,7 +19,6 @@ export async function createWorkspaceCommand(opts: CreateWorkspaceOptions): Prom
   const templatesDir = getTemplatesDir();
   const wsTemplatesDir = path.join(templatesDir, 'workspace');
 
-  // Refuse non-empty target.
   if (await pathExists(home)) {
     const entries = await readdir(home);
     if (entries.length > 0) {
@@ -44,24 +28,13 @@ export async function createWorkspaceCommand(opts: CreateWorkspaceOptions): Prom
     await ensureDir(home);
   }
 
-  const [cliVersion, pkgRaw] = await Promise.all([
-    readCurrentCliVersion(),
-    readFile(path.join(wsTemplatesDir, 'package.json.tmpl'), 'utf8'),
-  ]);
+  const pkgRaw = await readFile(path.join(wsTemplatesDir, 'package.json.tmpl'), 'utf8');
 
-  // Sources have plain names (gitignore, yarnrc.yml, nvmrc, npmrc) so they
-  // aren't interpreted as the active config files of *this* package; we
-  // rename to dotfiles at the destination.
-  //
-  // Yarn berry ships inline at .yarn/releases/. The workspace's .yarnrc.yml
-  // sets `yarnPath` to point here, so any `yarn` invocation (system classic
-  // or otherwise) reads the rc, delegates to this binary, and runs as 4.5.1
-  // — no corepack, no global pin needed. Mirrors how bigbrain-z2h ships its
-  // own yarn release.
   await Promise.all([
-    writeFile(path.join(home, 'package.json'), renderTemplate(pkgRaw, { __Z2H_CLI_VERSION__: cliVersion })),
+    writeFile(path.join(home, 'package.json'), pkgRaw),
     copy(path.join(wsTemplatesDir, 'gitignore'), path.join(home, '.gitignore')),
     copy(path.join(wsTemplatesDir, 'yarnrc.yml'), path.join(home, '.yarnrc.yml')),
+    copy(path.join(wsTemplatesDir, 'nx.json'), path.join(home, 'nx.json')),
     copy(path.join(wsTemplatesDir, 'yarnlock'), path.join(home, 'yarn.lock')),
     copy(path.join(wsTemplatesDir, 'nvmrc'), path.join(home, '.nvmrc')),
     copy(path.join(wsTemplatesDir, 'npmrc'), path.join(home, '.npmrc')),
@@ -81,6 +54,5 @@ export async function createWorkspaceCommand(opts: CreateWorkspaceOptions): Prom
   output(`Your workspace is ready! 🚀 Apps will live at ${home}`, {
     ok: true,
     workspace: home,
-    z2hCliVersion: cliVersion,
   });
 }

package/src/commands/migrate.ts

@@ -0,0 +1,15 @@
+import { setOutputMode } from '../util/logger';
+import { autoMigrate } from '../migrations/auto-migrate';
+
+export interface MigrateOptions {
+  dryRun?: boolean;
+  json?: boolean;
+}
+
+export async function migrateCommand(cliVersion: string, opts: MigrateOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+
+  await autoMigrate(cliVersion, opts.dryRun);
+}

package/src/index.ts

@@ -7,6 +7,7 @@ import { deployCommand } from './commands/deploy';
 import { createWorkspaceCommand } from './commands/create-workspace';
 import { createCommand } from './commands/create';
 import { generateZ2HTokenCommand } from './commands/generate-z2h-token';
+import { migrateCommand } from './commands/migrate';
 import { errorLog, fail } from './util/logger';
 
 const { version } = createRequire(import.meta.url)('../package.json') as { version: string };
@@ -125,6 +126,19 @@ async function main(): Promise<void> {
       }
     });
 
+  program
+    .command('migrate')
+    .description('Run pending workspace migrations')
+    .option('--dry-run', 'show pending migrations without applying any changes')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (opts: { dryRun?: boolean; json?: boolean }) => {
+      try {
+        await migrateCommand(version, opts);
+      } catch (err) {
+        fail(`migrate failed: ${(err as Error).message}`, { command: 'migrate' }, 1);
+      }
+    });
+
   await program.parseAsync(process.argv);
 }
 

package/src/migrations/001-remove-per-consumer-yarnrc.ts

@@ -0,0 +1,15 @@
+import type { Tree } from '@nx/devkit';
+
+export default function removePerConsumerYarnrc(tree: Tree): void {
+  for (const entry of tree.children('.')) {
+    if (entry.startsWith('.')) {
+      continue;
+    }
+    const pkgPath = `${entry}/package.json`;
+    const yarnrcPath = `${entry}/.yarnrc.yml`;
+    if (!tree.exists(pkgPath) || !tree.exists(yarnrcPath)) {
+      continue;
+    }
+    tree.delete(yarnrcPath);
+  }
+}

package/src/migrations/002-remove-z2h-cli-from-workspace-deps.ts

@@ -0,0 +1,47 @@
+import type { Tree } from '@nx/devkit';
+
+export default function removeZ2hCliFromWorkspaceDeps(tree: Tree): void {
+  // Clean workspace root package.json
+  if (tree.exists('package.json')) {
+    const pkg = JSON.parse(tree.read('package.json', 'utf-8')!);
+    let changed = false;
+
+    if (pkg.devDependencies?.['@mondaydotcomorg/z2h-cli']) {
+      delete pkg.devDependencies['@mondaydotcomorg/z2h-cli'];
+      changed = true;
+    }
+
+    if (pkg.resolutions?.['@mondaydotcomorg/z2h-cli']) {
+      delete pkg.resolutions['@mondaydotcomorg/z2h-cli'];
+      if (Object.keys(pkg.resolutions).length === 0) {
+        delete pkg.resolutions;
+      }
+      changed = true;
+    }
+
+    if (changed) {
+      tree.write('package.json', JSON.stringify(pkg, null, 2) + '\n');
+    }
+  }
+
+  // Clean each consumer app's package.json (remove devDep, keep scripts)
+  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.devDependencies?.['@mondaydotcomorg/z2h-cli']) {
+      delete pkg.devDependencies['@mondaydotcomorg/z2h-cli'];
+      if (Object.keys(pkg.devDependencies).length === 0) {
+        delete pkg.devDependencies;
+      }
+      tree.write(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    }
+  }
+}

package/src/migrations/auto-migrate.ts

@@ -0,0 +1,214 @@
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { pathExists, readJson, writeJson, writeFile } from 'fs-extra';
+import { execa } from 'execa';
+import semver from 'semver';
+import { info, warn } from '../util/logger';
+import { getWorkspaceHome, isZ2hWorkspace } from '../util/workspace';
+
+const STATE_FILE = '.z2h-migrations-state.json';
+const NX_JSON_CONTENT = '{\n  "extends": "@mondaydotcomorg/trident-monorepo/presets/nx.json"\n}\n';
+
+interface MigrationState {
+  lastMigratedVersion: string;
+}
+
+interface MigrationEntry {
+  version: string;
+  description: string;
+  migrate: string;
+}
+
+interface MigrationsJson {
+  migrations: Record<string, MigrationEntry>;
+}
+
+// ─── Helpers ───
+
+async function readState(workspaceHome: string): Promise<MigrationState | null> {
+  const statePath = path.join(workspaceHome, STATE_FILE);
+  if (!(await pathExists(statePath))) {
+    return null;
+  }
+  try {
+    return (await readJson(statePath)) as MigrationState;
+  } catch {
+    return null;
+  }
+}
+
+async function writeState(workspaceHome: string, state: MigrationState): Promise<void> {
+  const statePath = path.join(workspaceHome, STATE_FILE);
+  await writeJson(statePath, state, { spaces: 2 });
+}
+
+async function yarnInstall(workspaceHome: string, context: string): Promise<boolean> {
+  info(`${context} — running yarn install...`);
+  try {
+    await execa('yarn', ['install'], { cwd: workspaceHome, stdio: 'pipe' });
+    return true;
+  } catch (err) {
+    const stderr = (err as { stderr?: string }).stderr || (err as Error).message;
+    warn(`yarn install failed: ${stderr}`);
+    return false;
+  }
+}
+
+async function getLatestTrientMonorepoVersion(): Promise<string> {
+  try {
+    const { stdout } = await execa('npm', ['view', '@mondaydotcomorg/trident-monorepo', 'version']);
+    return `^${stdout.trim()}`;
+  } catch {
+    return '*';
+  }
+}
+
+// ─── Workspace bootstrap ───
+
+function isNxAvailable(workspaceHome: string): boolean {
+  try {
+    const wsRequire = createRequire(path.join(workspaceHome, 'package.json'));
+    wsRequire.resolve('nx/src/generators/tree');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureWorkspaceNx(workspaceHome: string): Promise<boolean> {
+  const nxJsonPath = path.join(workspaceHome, 'nx.json');
+  const pkgPath = path.join(workspaceHome, 'package.json');
+
+  if (!(await pathExists(nxJsonPath))) {
+    await writeFile(nxJsonPath, NX_JSON_CONTENT);
+    info('added nx.json to workspace');
+  }
+
+  const pkg = (await readJson(pkgPath)) as {
+    devDependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+  };
+
+  if (!pkg.devDependencies?.['@mondaydotcomorg/trident-monorepo']) {
+    pkg.devDependencies = pkg.devDependencies ?? {};
+    pkg.devDependencies['@mondaydotcomorg/trident-monorepo'] = await getLatestTrientMonorepoVersion();
+  }
+
+  if (!pkg.scripts?.nx) {
+    pkg.scripts = pkg.scripts ?? {};
+    pkg.scripts.nx = 'nx';
+  }
+
+  await writeJson(pkgPath, pkg, { spaces: 2 });
+
+  // Only install if NX isn't already importable from the workspace
+  if (!isNxAvailable(workspaceHome)) {
+    const ok = await yarnInstall(workspaceHome, 'NX not found, installing');
+    if (!ok) {
+      warn('workspace migrations require NX. Fix the install error and run "z2h-cli migrate" to retry.');
+      return false;
+    }
+  }
+
+  return true;
+}
+
+// ─── Main ───
+
+export async function autoMigrate(cliVersion: string, dryRun = false): Promise<void> {
+  const workspaceHome = getWorkspaceHome();
+  if (!(await isZ2hWorkspace(workspaceHome))) {
+    warn('no Z2H workspace found');
+    return;
+  }
+
+  const state = await readState(workspaceHome);
+  const lastVersion = state?.lastMigratedVersion ?? '0.0.0';
+
+  if (!semver.gt(cliVersion, lastVersion)) {
+    info('workspace is up to date — no migrations pending');
+    return;
+  }
+
+  info(`migrating workspace from v${lastVersion} → v${cliVersion}...`);
+
+  // migrations.json is at the package root — two dirs up from dist/migrations/
+  const thisDir = path.dirname(fileURLToPath(import.meta.url));
+  const migrationsJsonPath = path.resolve(thisDir, '..', '..', 'migrations.json');
+
+  if (!(await pathExists(migrationsJsonPath))) {
+    warn('migrations.json not found — skipping migrations');
+    return;
+  }
+
+  const migrationsJson = (await readJson(migrationsJsonPath)) as MigrationsJson;
+
+  // Filter to pending migrations (version > lastVersion AND <= cliVersion)
+  const pending = Object.entries(migrationsJson.migrations)
+    .filter(([, entry]) => semver.gt(entry.version, lastVersion) && semver.lte(entry.version, cliVersion))
+    .sort(([, a], [, b]) => semver.compare(a.version, b.version));
+
+  if (dryRun) {
+    info(`${pending.length} pending migration(s) (dry-run — no changes will be applied):`);
+    for (const [, entry] of pending) {
+      info(`  - ${entry.description} (v${entry.version})`);
+    }
+    return;
+  }
+
+  if (pending.length === 0) {
+    await writeState(workspaceHome, { lastMigratedVersion: cliVersion });
+    return;
+  }
+
+  const nxReady = await ensureWorkspaceNx(workspaceHome);
+  if (!nxReady) {
+    return;
+  }
+
+  info(`applying ${pending.length} workspace migration(s)...`);
+
+  // Resolve NX from the workspace's node_modules (not from CLI's own deps)
+  const wsRequire = createRequire(path.join(workspaceHome, 'package.json'));
+  const { FsTree, flushChanges } = wsRequire('nx/src/generators/tree') as {
+    FsTree: new (root: string, isVerbose: boolean) => import('@nx/devkit').Tree & {
+      listChanges(): { type: string; path: string }[];
+    };
+    flushChanges: (root: string, changes: { type: string; path: string; content?: Buffer | null }[]) => void;
+  };
+
+  let needsInstall = false;
+
+  for (const [name, entry] of pending) {
+    const tree = new FsTree(workspaceHome, false);
+    try {
+      const factoryPath = path.resolve(path.dirname(migrationsJsonPath), entry.migrate);
+      const mod = require(factoryPath);
+      const fn = mod.default || mod;
+      fn(tree);
+
+      const changes = tree.listChanges();
+      if (changes.length > 0) {
+        if (changes.some(c => c.path.endsWith('package.json'))) {
+          needsInstall = true;
+        }
+        flushChanges(workspaceHome, changes);
+        info(`  ✓ ${entry.description}`);
+      } else {
+        info(`  ○ ${entry.description} (no changes needed)`);
+      }
+    } catch (err) {
+      warn(`  ✗ migration "${name}" failed: ${(err as Error).message}`);
+      warn('    skipping remaining migrations. Run "z2h-cli migrate" to retry.');
+      return;
+    }
+  }
+
+  if (needsInstall) {
+    await yarnInstall(workspaceHome, 'package.json changed');
+  }
+
+  await writeState(workspaceHome, { lastMigratedVersion: cliVersion });
+  info('workspace migrations complete.');
+}

package/src/templates/app/CLAUDE.md

@@ -27,7 +27,7 @@ The orchestrator routes to `z2h:feature-development`, which handles the typechec
 
 ## 🌟 Data-Fetching Hierarchy
 
-When a request needs data, follow `z2h:coding-standards-mf` §0: write a `runQuery` helper for Snowflake data (TS module using `getBigBrainAPI()` for React apps; vanilla `<script>` using `window.location.origin` for html-embed apps), write a client-side fetch for other browser-accessible sources, or tell the user to reach out at `#zero-to-hero` if the data needs an API key or server-side access. Backend changes to `bigbrain-zth` are not in scope.
+When a request needs data, follow `z2h:coding-standards-mf` §0: write a `runQuery` helper for Snowflake data (TS module using `getBigBrainAPI()` for React apps; vanilla `<script>` using `window.location.origin` for html-embed apps), write a client-side fetch for other browser-accessible sources, or tell the user to reach out at `#ask-zero-to-hero` if the data needs an API key or server-side access. Backend changes to `bigbrain-zth` are not in scope.
 
 ---