@mondaydotcomorg/z2h-cli 0.6.0 → 0.6.1

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,7 +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,6 +1,6 @@
 import { createRequire } from 'node:module';
-import { Command } from 'commander';
 import { readFileSync } from 'node:fs';
+import { Command } from 'commander';
 import { devCommand } from './commands/dev';
 import { buildCommand } from './commands/build';
 import { cleanCommand } from './commands/clean';

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/shadow/sync.ts

@@ -1,6 +1,6 @@
 import { pathExists, readFile, writeFile } from 'fs-extra';
-import { execa } from 'execa';
 import { info } from '../util/logger';
+import { runYarnInstall } from '../util/npm/install';
 import { buildShadowPkg, hashConsumerDeps, writeShadowPkg } from './merge-package-json';
 import type { ConsumerPaths, ConsumerPkg } from '../types';
 
@@ -20,11 +20,9 @@ export async function syncShadow(paths: ConsumerPaths, consumerPkg: ConsumerPkg)
   if (oldHash !== newHash) {
     info(oldHash ? 'consumer deps changed — yarn install' : 'first run — yarn install');
     // Yarn 4 is cache-first and non-interactive by default in non-TTY
-    // contexts, so plain `yarn install` is all we need.
-    await execa('yarn', ['install'], {
-      cwd: paths.consumerDir,
-      stdio: 'inherit',
-    });
+    // contexts, so plain `yarn install` is all we need. runYarnInstall injects
+    // the npm-broker token, preflights auth, and re-auths on a broker 401.
+    await runYarnInstall({ cwd: paths.consumerDir });
     await writeFile(paths.shadowDepsHash, newHash);
   }
 }

package/src/templates/workspace/npmrc

@@ -1,3 +1,4 @@
-always-auth=true
-//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+@mondaydotcomorg:registry=https://bigbrain-zth.bigbrain.me/z2h-cli/npm/
+//bigbrain-zth.bigbrain.me/z2h-cli/npm/:_authToken=${Z2H_NPM_TOKEN}
 registry=https://registry.npmjs.org/
+always-auth=true

package/src/templates/workspace/yarnrc.yml

@@ -1,7 +1,11 @@
 nodeLinker: node-modules
 
-npmAuthToken: '${NPM_TOKEN}'
+npmScopes:
+  mondaydotcomorg:
+    npmRegistryServer: "https://bigbrain-zth.bigbrain.me/z2h-cli/npm"
+    npmAuthToken: "${Z2H_NPM_TOKEN}"
+    npmAlwaysAuth: true
 
-npmRegistryServer: 'https://registry.npmjs.org/'
+npmRegistryServer: "https://registry.npmjs.org/"
 
 yarnPath: .yarn/releases/yarn-4.5.1.cjs

package/src/util/__tests__/workspace-templates-shipped.test.ts

@@ -33,4 +33,23 @@ describe('workspace templates ship with the package', () => {
     const raw = await readFile(path.join(getTemplatesDir(), 'workspace', 'yarnrc.yml'), 'utf8');
     expect(raw).toMatch(/yarnPath:\s*\.yarn\/releases\/yarn-4\.5\.1\.cjs/);
   });
+
+  it('workspace yarnrc scope-splits @mondaydotcomorg to the broker with the Z2H placeholder, no legacy token', async () => {
+    const raw = await readFile(path.join(getTemplatesDir(), 'workspace', 'yarnrc.yml'), 'utf8');
+    expect(raw).not.toContain('${NPM_TOKEN}');
+    expect(raw).toContain('npmScopes:');
+    expect(raw).toContain('mondaydotcomorg:');
+    expect(raw).toContain('npmRegistryServer: "https://bigbrain-zth.bigbrain.me/z2h-cli/npm"');
+    expect(raw).toContain('npmAuthToken: "${Z2H_NPM_TOKEN}"');
+    // Default registry stays public/direct.
+    expect(raw).toContain('npmRegistryServer: "https://registry.npmjs.org/"');
+  });
+
+  it('workspace npmrc routes the broker scope + keeps a public default registry, no legacy token', async () => {
+    const raw = await readFile(path.join(getTemplatesDir(), 'workspace', 'npmrc'), 'utf8');
+    expect(raw).not.toContain('${NPM_TOKEN}');
+    expect(raw).toContain('@mondaydotcomorg:registry=https://bigbrain-zth.bigbrain.me/z2h-cli/npm/');
+    expect(raw).toContain('//bigbrain-zth.bigbrain.me/z2h-cli/npm/:_authToken=${Z2H_NPM_TOKEN}');
+    expect(raw).toContain('registry=https://registry.npmjs.org/');
+  });
 });

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

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { brokerCredentialProvider, DEFAULT_BROKER_BASE_URL, STS_BROKER_PATH } from '../broker-credential-provider';
+import { brokerCredentialProvider, STS_BROKER_PATH } from '../broker-credential-provider';
+import { DEFAULT_BROKER_BASE_URL } from '../../../constants';
 import * as authStore from '../auth-store';
 
 const STUB_CREDS = {

package/src/util/auth/auth-store.ts

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import os from 'node:os';
-import { pathExists, readJson } from 'fs-extra';
+import { pathExists, readJson, readJsonSync } from 'fs-extra';
 
 // npm-style convention: per-user config under ~/.zth (mirrors ~/.npmrc, ~/.aws/).
 // Kept out of the workspace dir so accidental `git init` in ~/zth-projects can't
@@ -29,3 +29,21 @@ export async function readZthAuth(): Promise<ZthAuth> {
   }
   return { token: parsed.token };
 }
+
+/**
+ * Synchronous, never-throws read of the z2h JWT from `~/.zth/auth.json`.
+ * Returns the token string, or `null` when the file is absent, unreadable,
+ * malformed, or missing the `token` field.
+ *
+ * Used when building the env for a spawned package-manager process, where a
+ * missing token must degrade gracefully (best-effort self-update) rather than
+ * blow up — and where an inline sync read keeps the spawn call site simple.
+ */
+export function tryReadAuthTokenSync(): string | null {
+  try {
+    const parsed = readJsonSync(Z2H_AUTH_FILE) as Partial<ZthAuth> | null;
+    return parsed?.token ?? null;
+  } catch {
+    return null;
+  }
+}

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

@@ -1,7 +1,7 @@
+import { brokerBaseUrl } from '../../constants';
 import { readZthAuth } from './auth-store';
 import type { AwsCredentialIdentity, AwsCredentialIdentityProvider } from '@aws-sdk/types';
 
-export const DEFAULT_BROKER_BASE_URL = 'https://bigbrain-zth.bigbrain.me';
 export const STS_BROKER_PATH = '/z2h-cli/sts/credentials';
 
 // Refresh the cached credentials this many ms before they expire so the next
@@ -15,10 +15,6 @@ interface BrokerResponse {
   expiration?: string;
 }
 
-function brokerBaseUrl(): string {
-  return process.env.Z2H_BROKER_BASE_URL || DEFAULT_BROKER_BASE_URL;
-}
-
 async function fetchCredentialsOnce(appName: string): Promise<AwsCredentialIdentity> {
   const { token } = await readZthAuth();
   const url = `${brokerBaseUrl()}${STS_BROKER_PATH}`;

package/src/util/npm/__tests__/broker-config.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { brokerNpmrcLines, workspaceNpmrcContents, workspaceYarnrcContents } from '../broker-config';
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe('broker-config (prod defaults)', () => {
+  it('npmrc lines route the brokered scope and supply the placeholder only', () => {
+    const lines = brokerNpmrcLines();
+    expect(lines).toEqual([
+      '@mondaydotcomorg:registry=https://bigbrain-zth.bigbrain.me/z2h-cli/npm/',
+      '//bigbrain-zth.bigbrain.me/z2h-cli/npm/:_authToken=${Z2H_NPM_TOKEN}',
+    ]);
+  });
+
+  it('workspace .npmrc keeps a public default registry + always-auth and no legacy token', () => {
+    const npmrc = workspaceNpmrcContents();
+    expect(npmrc).toContain('@mondaydotcomorg:registry=https://bigbrain-zth.bigbrain.me/z2h-cli/npm/');
+    expect(npmrc).toContain('registry=https://registry.npmjs.org/');
+    expect(npmrc).toContain('always-auth=true');
+    expect(npmrc).not.toContain('${NPM_TOKEN}');
+    expect(npmrc).toContain('${Z2H_NPM_TOKEN}');
+  });
+
+  it('workspace .yarnrc.yml scope-splits the brokered scope and leaves the default registry public', () => {
+    const yarnrc = workspaceYarnrcContents();
+    expect(yarnrc).toContain('npmScopes:');
+    expect(yarnrc).toContain('  mondaydotcomorg:');
+    expect(yarnrc).toContain('    npmRegistryServer: "https://bigbrain-zth.bigbrain.me/z2h-cli/npm"');
+    expect(yarnrc).toContain('    npmAuthToken: "${Z2H_NPM_TOKEN}"');
+    expect(yarnrc).toContain('    npmAlwaysAuth: true');
+    expect(yarnrc).toContain('npmRegistryServer: "https://registry.npmjs.org/"');
+    expect(yarnrc).toContain('yarnPath: .yarn/releases/yarn-4.5.1.cjs');
+    expect(yarnrc).not.toContain('${NPM_TOKEN}');
+  });
+});
+
+describe('broker-config (staging override)', () => {
+  it('honors Z2H_BROKER_BASE_URL for the registry host in every form', () => {
+    vi.stubEnv('Z2H_BROKER_BASE_URL', 'https://bigbrainstaging.me');
+    expect(brokerNpmrcLines()).toEqual([
+      '@mondaydotcomorg:registry=https://bigbrainstaging.me/z2h-cli/npm/',
+      '//bigbrainstaging.me/z2h-cli/npm/:_authToken=${Z2H_NPM_TOKEN}',
+    ]);
+    expect(workspaceYarnrcContents()).toContain('    npmRegistryServer: "https://bigbrainstaging.me/z2h-cli/npm"');
+  });
+});

package/src/util/npm/__tests__/install.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { execa } from 'execa';
+import { runYarnInstall } from '../install';
+import * as ensureToken from '../ensure-token';
+import * as authStore from '../../auth/auth-store';
+
+vi.mock('execa', () => ({
+  execa: vi.fn(),
+}));
+
+function makeChild({
+  rejectWith,
+  stderrChunks = [],
+}: {
+  rejectWith?: Error;
+  stderrChunks?: string[];
+} = {}) {
+  if (rejectWith) {
+    (rejectWith as Error & { stderr?: string }).stderr = stderrChunks.join('');
+  }
+  const promise = rejectWith ? Promise.reject(rejectWith) : Promise.resolve({ exitCode: 0 });
+  promise.catch(() => undefined);
+  return {
+    then: promise.then.bind(promise),
+    catch: promise.catch.bind(promise),
+    finally: promise.finally.bind(promise),
+  };
+}
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  vi.mocked(execa).mockReset();
+  vi.spyOn(ensureToken, 'ensureZ2hToken').mockResolvedValue();
+  vi.spyOn(authStore, 'tryReadAuthTokenSync').mockReturnValue('jwt-stub');
+});
+
+describe('runYarnInstall', () => {
+  it('preflights the token then spawns `yarn install` with Z2H_NPM_TOKEN in env', async () => {
+    vi.mocked(execa).mockReturnValueOnce(makeChild() as never);
+
+    await runYarnInstall({ cwd: '/ws' });
+
+    expect(ensureToken.ensureZ2hToken).toHaveBeenCalledTimes(1);
+    expect(execa).toHaveBeenCalledWith(
+      'yarn',
+      ['install'],
+      expect.objectContaining({
+        cwd: '/ws',
+        env: expect.objectContaining({ Z2H_NPM_TOKEN: 'jwt-stub' }),
+      })
+    );
+  });
+
+  it('merges extraEnv on top of the broker token', async () => {
+    vi.mocked(execa).mockReturnValueOnce(makeChild() as never);
+
+    await runYarnInstall({ cwd: '/ws', extraEnv: { PUBLIC_URL: 'https://x' } });
+
+    expect(execa).toHaveBeenCalledWith(
+      'yarn',
+      ['install'],
+      expect.objectContaining({
+        env: expect.objectContaining({ Z2H_NPM_TOKEN: 'jwt-stub', PUBLIC_URL: 'https://x' }),
+      })
+    );
+  });
+
+  it('on a broker 401, re-auths (forceRefresh) and retries the install once', async () => {
+    const e401 = new Error('Process exited with code 1');
+    vi.mocked(execa)
+      .mockReturnValueOnce(makeChild({ rejectWith: e401, stderrChunks: ['npm error code E401\n'] }) as never)
+      .mockReturnValueOnce(makeChild() as never);
+
+    await runYarnInstall({ cwd: '/ws' });
+
+    // Preflight + forced refresh after the 401.
+    expect(ensureToken.ensureZ2hToken).toHaveBeenCalledTimes(2);
+    expect(vi.mocked(ensureToken.ensureZ2hToken).mock.calls[1][0]).toEqual({ forceRefresh: true });
+    // Two install attempts.
+    expect(execa).toHaveBeenCalledTimes(2);
+  });
+
+  it('rethrows a non-auth failure without retrying', async () => {
+    const depErr = new Error('ENOTFOUND some-package');
+    vi.mocked(execa).mockReturnValueOnce(
+      makeChild({ rejectWith: depErr, stderrChunks: ["error Couldn't find package\n"] }) as never
+    );
+
+    await expect(runYarnInstall({ cwd: '/ws' })).rejects.toThrow(/ENOTFOUND/);
+    expect(execa).toHaveBeenCalledTimes(1);
+    // No forced re-auth on a non-auth error.
+    expect(ensureToken.ensureZ2hToken).toHaveBeenCalledTimes(1);
+  });
+});

package/src/util/npm/broker-config.ts

@@ -0,0 +1,63 @@
+import { BROKER_NPM_SCOPE, PUBLIC_NPM_REGISTRY_URL, Z2H_NPM_TOKEN_ENV, brokerNpmRegistryUrl } from '../../constants';
+
+/** `https://host/path/` (with trailing slash) for the registry= line. */
+function registryUrlWithSlash(): string {
+  const url = brokerNpmRegistryUrl();
+  return url.endsWith('/') ? url : `${url}/`;
+}
+
+/**
+ * The `//host/path/` prefix (scheme stripped, trailing slash kept) that npm
+ * requires the `:_authToken` key to be keyed under so it aligns with the
+ * registry path. Derived from the same registry URL so staging overrides flow
+ * through.
+ */
+function authKeyPrefix(): string {
+  return registryUrlWithSlash().replace(/^https?:/, '');
+}
+
+/**
+ * The two npm config lines (§3.1 / §3.3) that route the brokered scope to the
+ * proxy and supply the `${Z2H_NPM_TOKEN}` placeholder. No literal token — npm
+ * interpolates the placeholder from the env at invocation time.
+ */
+export function brokerNpmrcLines(): string[] {
+  return [
+    `${BROKER_NPM_SCOPE}:registry=${registryUrlWithSlash()}`,
+    `${authKeyPrefix()}:_authToken=\${${Z2H_NPM_TOKEN_ENV}}`,
+  ];
+}
+
+/**
+ * Full contents for a **workspace** `.npmrc` (§3.3): broker scope-split plus an
+ * explicit public default registry and always-auth. Used by the template and
+ * the migration so both stay byte-identical.
+ */
+export function workspaceNpmrcContents(): string {
+  return [...brokerNpmrcLines(), `registry=${PUBLIC_NPM_REGISTRY_URL}`, 'always-auth=true'].join('\n') + '\n';
+}
+
+/**
+ * Full contents for a **workspace** `.yarnrc.yml` (§3.2): the brokered scope
+ * points at the proxy with the `${Z2H_NPM_TOKEN}` placeholder + always-auth;
+ * the default `npmRegistryServer` stays the public registry (direct, unchanged
+ * speed). `yarnPath` keeps the bundled Berry release so any `yarn` runs 4.x.
+ */
+export function workspaceYarnrcContents(): string {
+  const scopeKey = BROKER_NPM_SCOPE.replace(/^@/, '');
+  return (
+    [
+      'nodeLinker: node-modules',
+      '',
+      'npmScopes:',
+      `  ${scopeKey}:`,
+      `    npmRegistryServer: "${brokerNpmRegistryUrl()}"`,
+      `    npmAuthToken: "\${${Z2H_NPM_TOKEN_ENV}}"`,
+      '    npmAlwaysAuth: true',
+      '',
+      `npmRegistryServer: "${PUBLIC_NPM_REGISTRY_URL}"`,
+      '',
+      'yarnPath: .yarn/releases/yarn-4.5.1.cjs',
+    ].join('\n') + '\n'
+  );
+}