@mondaydotcomorg/z2h-cli 0.5.2 → 0.6.1

package/dist/util/npm/ensure-token.d.ts

@@ -0,0 +1,19 @@
+export interface EnsureZ2hTokenOptions {
+    /**
+     * Re-run the token flow even if a token already exists on disk. Used after a
+     * broker 401, where the stored token is present but expired/invalid.
+     */
+    forceRefresh?: boolean;
+}
+/**
+ * Ensure a z2h JWT exists at `~/.zth/auth.json` before an install-bearing
+ * command runs. If none is present (or `forceRefresh` is set), drive the
+ * existing `generate-z2h-token` flow — loopback capture with manual-paste
+ * fallback — which writes the token. No-ops when a token already exists and no
+ * refresh was requested.
+ *
+ * This is the install preflight: it keeps a friendly auth prompt in front of
+ * the raw npm error a non-technical user would otherwise hit.
+ */
+export declare function ensureZ2hToken(opts?: EnsureZ2hTokenOptions): Promise<void>;
+//# sourceMappingURL=ensure-token.d.ts.map

package/dist/util/npm/ensure-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-token.d.ts","sourceRoot":"","sources":["../../../src/util/npm/ensure-token.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAKpF"}

package/dist/util/npm/ensure-token.js

@@ -0,0 +1,24 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const util_auth_authStore = require('../auth/auth-store.js');
+const util_logger = require('../logger.js');
+const commands_generateZ2hToken = require('../../commands/generate-z2h-token.js');
+
+/**
+ * Ensure a z2h JWT exists at `~/.zth/auth.json` before an install-bearing
+ * command runs. If none is present (or `forceRefresh` is set), drive the
+ * existing `generate-z2h-token` flow — loopback capture with manual-paste
+ * fallback — which writes the token. No-ops when a token already exists and no
+ * refresh was requested.
+ *
+ * This is the install preflight: it keeps a friendly auth prompt in front of
+ * the raw npm error a non-technical user would otherwise hit.
+ */
+async function ensureZ2hToken(opts = {}) {
+    if (opts.forceRefresh || !util_auth_authStore.tryReadAuthTokenSync()) {
+        util_logger.info('you need to sign in to install monday packages — opening the sign-in page');
+        await commands_generateZ2hToken.generateZ2HTokenCommand();
+    }
+}
+
+exports.ensureZ2hToken = ensureZ2hToken;

package/dist/util/npm/install.d.ts

@@ -0,0 +1,18 @@
+export interface RunYarnInstallOptions {
+    /** Directory to run `yarn install` in. */
+    cwd: string;
+    /** Extra env to merge on top of `process.env` + the broker token. */
+    extraEnv?: NodeJS.ProcessEnv;
+}
+/**
+ * Run `yarn install` for an install-bearing command:
+ *   1. Preflight — ensure a z2h token exists (prompt `generate-z2h-token` if not).
+ *   2. Install through the broker.
+ *   3. On a broker 401, surface a friendly "your access expired — refreshing it"
+ *      message, re-auth, and retry the install exactly once.
+ *
+ * A non-auth failure (real dependency error, network, etc.) propagates as-is so
+ * the command's normal error path reports it.
+ */
+export declare function runYarnInstall(opts: RunYarnInstallOptions): Promise<void>;
+//# sourceMappingURL=install.d.ts.map

package/dist/util/npm/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/util/npm/install.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAC9B;AAqCD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAc/E"}

package/dist/util/npm/install.js

@@ -0,0 +1,76 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const execa = require('execa');
+const util_logger = require('../logger.js');
+const util_auth_authStore = require('../auth/auth-store.js');
+const constants = require('../../constants.js');
+const util_npm_ensureToken = require('./ensure-token.js');
+
+// Substrings that, in a failed install's output, indicate the broker rejected
+// the z2h JWT (expired/invalid). npm surfaces `E401`/`code E401`; yarn berry
+// surfaces an HTTP 401 line. We re-auth on any of these rather than dumping a
+// raw npm error on a non-technical user.
+const AUTH_FAILURE_MARKERS = ['401', 'e401', 'unauthorized', 'authentication'];
+function looksLikeAuthFailure(text) {
+    const haystack = text.toLowerCase();
+    return AUTH_FAILURE_MARKERS.some(marker => haystack.includes(marker));
+}
+/**
+ * Spawn `yarn install` in `cwd` with the npm-broker credential injected, while
+ * streaming yarn's output live to the user. stdout is inherited; stderr is
+ * piped so we can both echo it and inspect it for a broker auth failure.
+ *
+ * Returns the captured stderr on success; throws an Error tagged
+ * `isAuthFailure` when the failure output looks like a broker 401 so the
+ * caller can re-auth, or rethrows the raw execa error otherwise.
+ */
+async function spawnYarnInstall(opts) {
+    const token = util_auth_authStore.tryReadAuthTokenSync();
+    const env = { ...process.env, ...(token && { [constants.Z2H_NPM_TOKEN_ENV]: token }), ...opts.extraEnv };
+    const child = execa.execa('yarn', ['install'], {
+        cwd: opts.cwd,
+        stdout: 'inherit',
+        stderr: ['inherit', 'pipe'],
+        env,
+    });
+    try {
+        await child;
+    }
+    catch (err) {
+        const e = err;
+        const combined = `${e.stderr}\n${e.message ?? ''}`;
+        if (looksLikeAuthFailure(combined)) {
+            const authErr = new Error('broker rejected the z2h token during install');
+            authErr.isAuthFailure = true;
+            throw authErr;
+        }
+        throw err;
+    }
+}
+/**
+ * Run `yarn install` for an install-bearing command:
+ *   1. Preflight — ensure a z2h token exists (prompt `generate-z2h-token` if not).
+ *   2. Install through the broker.
+ *   3. On a broker 401, surface a friendly "your access expired — refreshing it"
+ *      message, re-auth, and retry the install exactly once.
+ *
+ * A non-auth failure (real dependency error, network, etc.) propagates as-is so
+ * the command's normal error path reports it.
+ */
+async function runYarnInstall(opts) {
+    await util_npm_ensureToken.ensureZ2hToken();
+    try {
+        await spawnYarnInstall(opts);
+    }
+    catch (err) {
+        if (!err.isAuthFailure) {
+            throw err;
+        }
+        util_logger.warn('your access expired — refreshing it now…');
+        await util_npm_ensureToken.ensureZ2hToken({ forceRefresh: true });
+        util_logger.info('access refreshed — retrying install');
+        await spawnYarnInstall(opts);
+    }
+}
+
+exports.runYarnInstall = runYarnInstall;

package/dist/util/tracker.d.ts

@@ -0,0 +1,3 @@
+export declare function trackEvent(name: string, data: Record<string, unknown>): void;
+export declare function trackDuration<T>(eventName: string, fn: () => Promise<T>, data?: Record<string, unknown>): Promise<T>;
+//# sourceMappingURL=tracker.d.ts.map

package/dist/util/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/util/tracker.ts"],"names":[],"mappings":"AAMA,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAO5E;AAED,wBAAsB,aAAa,CAAC,CAAC,EACnC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAKZ"}

package/dist/util/tracker.js

@@ -0,0 +1,27 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const os = require('node:os');
+
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const os__default = /*#__PURE__*/_interopDefault(os);
+
+const DOORMAN_URL = 'https://track.bigbrain.me/prod/event';
+const username = os__default.default.userInfo().username;
+function trackEvent(name, data) {
+    void fetch(DOORMAN_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name, source: 'z2h-cli', data: { username, ...data } }),
+        signal: AbortSignal.timeout(5000),
+    }).catch(() => { });
+}
+async function trackDuration(eventName, fn, data) {
+    const start = Date.now();
+    const result = await fn();
+    trackEvent(eventName, { ...data, duration_ms: Date.now() - start });
+    return result;
+}
+
+exports.trackDuration = trackDuration;
+exports.trackEvent = trackEvent;

package/migrations.json

@@ -9,6 +9,11 @@
       "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"
+    },
+    "npm-broker-scope-split": {
+      "version": "0.6.0",
+      "description": "Rewrite workspace .yarnrc.yml/.npmrc from ${NPM_TOKEN} to the @mondaydotcomorg broker scope-split",
+      "migrate": "./dist/migrations/003-npm-broker-scope-split"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

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

@@ -3,12 +3,14 @@ import os from 'node:os';
 import { mkdtemp, rm, writeJson, readJson, ensureDir, pathExists } from 'fs-extra';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { execa } from 'execa';
+import { runYarnInstall } from '../../util/npm/install';
 import { createWorkspaceCommand } from '../create-workspace';
 
-// Mock execa so `yarn install` doesn't actually run.
-vi.mock('execa', () => ({
-  execa: vi.fn().mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 }),
+// Mock the install helper so `yarn install` (with its broker preflight) doesn't
+// actually run. The token-injection + 401 re-auth behavior is covered in
+// util/npm/__tests__/install.test.ts.
+vi.mock('../../util/npm/install', () => ({
+  runYarnInstall: vi.fn().mockResolvedValue(undefined),
 }));
 
 describe('create-workspace', () => {
@@ -17,7 +19,7 @@ describe('create-workspace', () => {
   beforeEach(async () => {
     tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-cw-'));
     process.env.Z2H_WORKSPACE_HOME = tmp;
-    vi.mocked(execa).mockClear();
+    vi.mocked(runYarnInstall).mockClear();
     // After mkdtemp the dir exists and is empty; we want absent for the
     // "happy path" tests, so remove it.
     await rm(tmp, { recursive: true, force: true });
@@ -46,11 +48,7 @@ describe('create-workspace', () => {
     expect(await pathExists(path.join(tmp, '.npmrc'))).toBe(true);
     expect(await pathExists(path.join(tmp, 'README.md'))).toBe(true);
 
-    expect(execa).toHaveBeenCalledWith(
-      'yarn',
-      expect.arrayContaining(['install']),
-      expect.objectContaining({ cwd: tmp })
-    );
+    expect(runYarnInstall).toHaveBeenCalledWith(expect.objectContaining({ cwd: tmp }));
   });
 
   it('refuses if the target dir is non-empty', async () => {
@@ -58,7 +56,7 @@ describe('create-workspace', () => {
     await writeJson(path.join(tmp, 'somefile.json'), { hello: 'world' });
 
     await expect(createWorkspaceCommand({})).rejects.toThrow(/Workspace already exists/);
-    expect(execa).not.toHaveBeenCalled();
+    expect(runYarnInstall).not.toHaveBeenCalled();
   });
 
   it('does not include z2h-cli in workspace devDeps (managed globally)', async () => {

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

@@ -3,12 +3,15 @@ import os from 'node:os';
 import { mkdtemp, rm, writeJson, readJson, ensureDir, pathExists, writeFile } from 'fs-extra';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { execa } from 'execa';
+import { runYarnInstall } from '../../util/npm/install';
 import { createCommand } from '../create';
 import * as manifest from '../../util/manifest';
 
-vi.mock('execa', () => ({
-  execa: vi.fn().mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 }),
+// Mock the install helper so `yarn install` (with its broker preflight) doesn't
+// actually run. Token-injection + 401 re-auth is covered in
+// util/npm/__tests__/install.test.ts.
+vi.mock('../../util/npm/install', () => ({
+  runYarnInstall: vi.fn().mockResolvedValue(undefined),
 }));
 
 vi.spyOn(manifest, 'readManifest').mockResolvedValue({});
@@ -29,7 +32,7 @@ describe('create', () => {
   beforeEach(async () => {
     tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-c-'));
     process.env.Z2H_WORKSPACE_HOME = tmp;
-    vi.mocked(execa).mockClear();
+    vi.mocked(runYarnInstall).mockClear();
   });
 
   afterEach(async () => {
@@ -39,7 +42,7 @@ describe('create', () => {
 
   it('refuses when there is no workspace marker', async () => {
     await expect(createCommand('demo-app', {})).rejects.toThrow(/create-workspace/);
-    expect(execa).not.toHaveBeenCalled();
+    expect(runYarnInstall).not.toHaveBeenCalled();
   });
 
   it('rejects invalid app names', async () => {
@@ -76,7 +79,7 @@ describe('create', () => {
     expect(content).toContain('export default function DemoApp()');
     expect(content).not.toContain('__APP_COMPONENT__');
 
-    expect(execa).toHaveBeenCalledWith('yarn', ['install'], expect.any(Object));
+    expect(runYarnInstall).toHaveBeenCalledWith(expect.objectContaining({ cwd: tmp }));
   });
 
   it('scaffolds an html-embed app and copies the html file', async () => {

package/src/commands/create-workspace.ts

@@ -1,10 +1,10 @@
 import path from 'node:path';
 import { readFile } from 'node:fs/promises';
 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 } from '../util/templates';
+import { runYarnInstall } from '../util/npm/install';
 
 export interface CreateWorkspaceOptions {
   json?: boolean;
@@ -46,10 +46,7 @@ export async function createWorkspaceCommand(opts: CreateWorkspaceOptions): Prom
   ]);
 
   info(`setting up your Z2H workspace — this may take a minute...`);
-  await execa('yarn', ['install'], {
-    cwd: home,
-    stdio: 'inherit',
-  });
+  await runYarnInstall({ cwd: home });
 
   output(`Your workspace is ready! 🚀 Apps will live at ${home}`, {
     ok: true,

package/src/commands/create.ts

@@ -1,13 +1,13 @@
 import path from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { ensureDir, pathExists, readdir, writeFile, copy } from 'fs-extra';
-import { execa } from 'execa';
 import { info, output, setOutputMode } from '../util/logger';
 import { assertWorkspace } from '../util/workspace';
 import { getTemplatesDir, renderTemplate, APP_TEMPLATES, type AppTemplate } from '../util/templates';
 import { readManifest } from '../util/manifest';
 import { mfAppName } from '../util/app-name';
 import { APP_NAME_PATTERN } from '../constants';
+import { runYarnInstall } from '../util/npm/install';
 
 export interface CreateOptions {
   template?: string;
@@ -116,10 +116,7 @@ export async function createCommand(appName: string, opts: CreateOptions): Promi
   }
 
   info(`installing dependencies for ${appName}...`);
-  await execa('yarn', ['install'], {
-    cwd: workspace,
-    stdio: 'inherit',
-  });
+  await runYarnInstall({ cwd: workspace });
 
   output(`[z2h-cli] app ready at ${appDir}`, {
     ok: true,

package/src/constants.ts

@@ -56,3 +56,44 @@ export 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.
 export const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{1,49}$/;
+
+// ─────────── 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.
+export const DEFAULT_BROKER_BASE_URL = 'https://bigbrain-zth.bigbrain.me';
+
+/**
+ * Resolves the broker origin (no trailing slash). Honors
+ * `Z2H_BROKER_BASE_URL` (tests/staging), else the prod default. Shared by the
+ * STS credential provider and the npm-broker registry URL.
+ */
+export function brokerBaseUrl(): string {
+  return process.env.Z2H_BROKER_BASE_URL || DEFAULT_BROKER_BASE_URL;
+}
+
+// The authenticated npm reverse-proxy is mounted here on the broker. Only the
+// `@mondaydotcomorg` scope is served; everything else resolves from npmjs
+// directly. See docs/superpowers/specs/2026-06-03-npm-brokering-design.md §3.
+export const NPM_BROKER_PATH = '/z2h-cli/npm';
+
+// The scope brokered through the proxy — the ONLY scope it serves.
+export const BROKER_NPM_SCOPE = '@mondaydotcomorg';
+
+// Public registry for everything outside the brokered scope (unchanged speed).
+export const PUBLIC_NPM_REGISTRY_URL = 'https://registry.npmjs.org/';
+
+// Env var the client config (`~/.npmrc`, `.yarnrc.yml`) interpolates at
+// invocation time; its value is the z2h JWT, injected per-spawn by the CLI.
+// Deliberately NOT `NPM_TOKEN` — avoids colliding with the monorepo's own dev
+// token and makes clear it is the z2h JWT, not a real npm token.
+export const Z2H_NPM_TOKEN_ENV = 'Z2H_NPM_TOKEN' as const;
+
+/**
+ * Broker npm registry URL (no trailing slash), e.g. prod
+ * `https://bigbrain-zth.bigbrain.me/z2h-cli/npm`. Built on `brokerBaseUrl()`
+ * so the staging override flows through. The trailing-slash forms required by
+ * the `.npmrc`/`.yarnrc.yml` configs are added where those files are written.
+ */
+export function brokerNpmRegistryUrl(): string {
+  return `${brokerBaseUrl()}${NPM_BROKER_PATH}`;
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
 import { Command } from 'commander';
 import { devCommand } from './commands/dev';
 import { buildCommand } from './commands/build';
@@ -9,9 +10,18 @@ import { createCommand } from './commands/create';
 import { generateZ2HTokenCommand } from './commands/generate-z2h-token';
 import { migrateCommand } from './commands/migrate';
 import { errorLog, fail } from './util/logger';
+import { trackDuration } from './util/tracker';
 
 const { version } = createRequire(import.meta.url)('../package.json') as { version: string };
 
+function getCwdAppName(): string | undefined {
+  try {
+    return (JSON.parse(readFileSync('package.json', 'utf8')) as { name?: string }).name;
+  } catch {
+    return undefined;
+  }
+}
+
 async function main(): Promise<void> {
   const program = new Command();
   program
@@ -38,11 +48,8 @@ async function main(): Promise<void> {
     .option('--json', 'emit structured JSON on stdout')
     .action(async (opts: { json?: boolean }) => {
       try {
-        await buildCommand(opts);
+        await trackDuration('z2h_app_build_success', () => buildCommand(opts), { app_name: getCwdAppName() });
       } catch (err) {
-        // fail() emits a structured JSON error on stdout in --json mode and
-        // a red line on stderr in human mode, then exits. errorLog alone is
-        // silent in JSON mode, which leaves machine consumers with no signal.
         fail(`build failed: ${(err as Error).message}`, { command: 'build' }, 2);
       }
     });
@@ -78,7 +85,9 @@ async function main(): Promise<void> {
     .option('--json', 'emit structured JSON on stdout')
     .action(async (opts: { dryRun?: boolean; json?: boolean }) => {
       try {
-        await deployCommand(opts);
+        await trackDuration('z2h_app_deploy_success', () => deployCommand(opts), {
+          app_name: getCwdAppName(),
+        });
       } catch (err) {
         fail(`deploy failed: ${(err as Error).message}`, { command: 'deploy' }, 2);
       }
@@ -120,7 +129,10 @@ async function main(): Promise<void> {
     .option('--json', 'emit structured JSON on stdout')
     .action(async (appName: string, opts: { template?: string; htmlFile?: string; json?: boolean }) => {
       try {
-        await createCommand(appName, opts);
+        await trackDuration('z2h_app_created', () => createCommand(appName, opts), {
+          app_name: appName,
+          template: opts.template ?? 'default',
+        });
       } catch (err) {
         fail(`create failed: ${(err as Error).message}`, { command: 'create' }, 1);
       }

package/src/migrations/003-npm-broker-scope-split.ts

@@ -0,0 +1,52 @@
+import { workspaceYarnrcContents, workspaceNpmrcContents } from '../util/npm/broker-config';
+import type { Tree } from '@nx/devkit';
+
+// Legacy marker: the old configs interpolated a real npm token via
+// `${NPM_TOKEN}`. Its presence means the file predates npm brokering and must
+// be rewritten to the scope-split. Once rewritten (placeholder is now
+// `${Z2H_NPM_TOKEN}`) this no longer matches, so the migration is idempotent.
+const LEGACY_TOKEN_PLACEHOLDER = '${NPM_TOKEN}';
+
+/**
+ * Rewrite a single rc file to `contents` iff it exists and still carries the
+ * legacy `${NPM_TOKEN}` placeholder. Returns nothing; mutates the Tree.
+ */
+function rewriteIfLegacy(tree: Tree, filePath: string, contents: string): void {
+  if (!tree.exists(filePath)) {
+    return;
+  }
+  const current = tree.read(filePath, 'utf-8') ?? '';
+  if (!current.includes(LEGACY_TOKEN_PLACEHOLDER)) {
+    return; // already migrated (or never legacy) — leave untouched
+  }
+  tree.write(filePath, contents);
+}
+
+/**
+ * Migrate the workspace npm/yarn config from the legacy single-registry
+ * `${NPM_TOKEN}` form to the `@mondaydotcomorg`→broker scope-split
+ * (`${Z2H_NPM_TOKEN}` placeholder). Rewrites the workspace-root `.yarnrc.yml`
+ * and `.npmrc`, plus any consumer-app copies that still carry the legacy
+ * placeholder (migration 001 normally removes per-consumer `.yarnrc.yml`, so
+ * this is just defensive cleanup).
+ *
+ * The global `~/.npmrc` broker block is written separately by `migrateCommand`
+ * (it lives outside the workspace Tree).
+ */
+export default function npmBrokerScopeSplit(tree: Tree): void {
+  const yarnrc = workspaceYarnrcContents();
+  const npmrc = workspaceNpmrcContents();
+
+  // Workspace root.
+  rewriteIfLegacy(tree, '.yarnrc.yml', yarnrc);
+  rewriteIfLegacy(tree, '.npmrc', npmrc);
+
+  // Any consumer apps that still carry their own legacy rc files.
+  for (const entry of tree.children('.')) {
+    if (entry.startsWith('.')) {
+      continue;
+    }
+    rewriteIfLegacy(tree, `${entry}/.yarnrc.yml`, yarnrc);
+    rewriteIfLegacy(tree, `${entry}/.npmrc`, npmrc);
+  }
+}

package/src/migrations/__tests__/003-npm-broker-scope-split.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest';
+import { createTree } from '@nx/devkit/testing';
+import npmBrokerScopeSplit from '../003-npm-broker-scope-split';
+import type { Tree } from '@nx/devkit';
+
+// The legacy workspace files brokering replaces.
+const LEGACY_YARNRC = [
+  'nodeLinker: node-modules',
+  '',
+  "npmAuthToken: '${NPM_TOKEN}'",
+  '',
+  "npmRegistryServer: 'https://registry.npmjs.org/'",
+  '',
+  'yarnPath: .yarn/releases/yarn-4.5.1.cjs',
+  '',
+].join('\n');
+
+const LEGACY_NPMRC = [
+  'always-auth=true',
+  '//registry.npmjs.org/:_authToken=${NPM_TOKEN}',
+  'registry=https://registry.npmjs.org/',
+  '',
+].join('\n');
+
+function makeTree(): Tree {
+  return createTree();
+}
+
+describe('migration 003 — npm broker scope split', () => {
+  it('rewrites a legacy ${NPM_TOKEN} workspace .yarnrc.yml to the scope-split', () => {
+    const tree = makeTree();
+    tree.write('.yarnrc.yml', LEGACY_YARNRC);
+
+    npmBrokerScopeSplit(tree);
+
+    const out = tree.read('.yarnrc.yml', 'utf-8')!;
+    expect(out).not.toContain('${NPM_TOKEN}');
+    expect(out).toContain('  mondaydotcomorg:');
+    expect(out).toContain('    npmRegistryServer: "https://bigbrain-zth.bigbrain.me/z2h-cli/npm"');
+    expect(out).toContain('    npmAuthToken: "${Z2H_NPM_TOKEN}"');
+    expect(out).toContain('npmRegistryServer: "https://registry.npmjs.org/"');
+  });
+
+  it('rewrites a legacy ${NPM_TOKEN} workspace .npmrc to the scope-split', () => {
+    const tree = makeTree();
+    tree.write('.npmrc', LEGACY_NPMRC);
+
+    npmBrokerScopeSplit(tree);
+
+    const out = tree.read('.npmrc', 'utf-8')!;
+    expect(out).not.toContain('${NPM_TOKEN}');
+    expect(out).toContain('@mondaydotcomorg:registry=https://bigbrain-zth.bigbrain.me/z2h-cli/npm/');
+    expect(out).toContain('//bigbrain-zth.bigbrain.me/z2h-cli/npm/:_authToken=${Z2H_NPM_TOKEN}');
+    expect(out).toContain('registry=https://registry.npmjs.org/');
+  });
+
+  it('is idempotent — a second run on already-migrated files is a no-op', () => {
+    const tree = makeTree();
+    tree.write('.yarnrc.yml', LEGACY_YARNRC);
+    tree.write('.npmrc', LEGACY_NPMRC);
+
+    npmBrokerScopeSplit(tree);
+    const yarnrcAfterFirst = tree.read('.yarnrc.yml', 'utf-8')!;
+    const npmrcAfterFirst = tree.read('.npmrc', 'utf-8')!;
+
+    npmBrokerScopeSplit(tree);
+    expect(tree.read('.yarnrc.yml', 'utf-8')!).toBe(yarnrcAfterFirst);
+    expect(tree.read('.npmrc', 'utf-8')!).toBe(npmrcAfterFirst);
+  });
+
+  it('leaves non-legacy files untouched (no ${NPM_TOKEN} marker)', () => {
+    const tree = makeTree();
+    const custom = 'nodeLinker: node-modules\nnpmRegistryServer: "https://my.custom/"\n';
+    tree.write('.yarnrc.yml', custom);
+
+    npmBrokerScopeSplit(tree);
+
+    expect(tree.read('.yarnrc.yml', 'utf-8')!).toBe(custom);
+  });
+
+  it('rewrites a consumer-app legacy .yarnrc.yml it finds', () => {
+    const tree = makeTree();
+    tree.write('my-app/package.json', '{"name":"my-app"}');
+    tree.write('my-app/.yarnrc.yml', LEGACY_YARNRC);
+
+    npmBrokerScopeSplit(tree);
+
+    const out = tree.read('my-app/.yarnrc.yml', 'utf-8')!;
+    expect(out).not.toContain('${NPM_TOKEN}');
+    expect(out).toContain('    npmAuthToken: "${Z2H_NPM_TOKEN}"');
+  });
+
+  it('does nothing when no rc files exist', () => {
+    const tree = makeTree();
+    expect(() => npmBrokerScopeSplit(tree)).not.toThrow();
+    expect(tree.exists('.yarnrc.yml')).toBe(false);
+    expect(tree.exists('.npmrc')).toBe(false);
+  });
+});

package/src/migrations/auto-migrate.ts

@@ -4,7 +4,7 @@ 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 { info, warn, errorLog } from '../util/logger';
 import { getWorkspaceHome, isZ2hWorkspace } from '../util/workspace';
 
 const STATE_FILE = '.z2h-migrations-state.json';
@@ -199,9 +199,9 @@ export async function autoMigrate(cliVersion: string, dryRun = false): Promise<v
         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;
+      const errorMessage = `migration "${name}" failed: ${(err as Error).message}`;
+      errorLog(`${errorMessage}\nSkipping remaining migrations — run "z2h-cli migrate" to retry.`);
+      throw new Error(errorMessage);
     }
   }