@mondaydotcomorg/z2h-cli 0.5.2 → 0.6.1

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/logger.ts

@@ -1,4 +1,5 @@
 import pc from 'picocolors';
+import { trackEvent } from './tracker';
 
 export type OutputMode = 'human' | 'json';
 
@@ -60,5 +61,6 @@ export function fail(message: string, payload: Record<string, unknown>, exitCode
       process.stderr.write(pc.dim(`  → ${payload.suggestedCommand}\n`));
     }
   }
+  trackEvent('z2h_cli_error', { action: (payload.command as string) ?? 'unknown', error: message });
   process.exit(exitCode);
 }

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'
+  );
+}

package/src/util/npm/ensure-token.ts

@@ -0,0 +1,28 @@
+import { tryReadAuthTokenSync } from '../auth/auth-store';
+import { info } from '../logger';
+import { generateZ2HTokenCommand } from '../../commands/generate-z2h-token';
+
+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 async function ensureZ2hToken(opts: EnsureZ2hTokenOptions = {}): Promise<void> {
+  if (opts.forceRefresh || !tryReadAuthTokenSync()) {
+    info('you need to sign in to install monday packages — opening the sign-in page');
+    await generateZ2HTokenCommand();
+  }
+}

package/src/util/npm/install.ts

@@ -0,0 +1,84 @@
+import { execa, type Options as ExecaOptions } from 'execa';
+import { info, warn } from '../logger';
+import { tryReadAuthTokenSync } from '../auth/auth-store';
+import { Z2H_NPM_TOKEN_ENV } from '../../constants';
+import { ensureZ2hToken } from './ensure-token';
+
+// 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: string): boolean {
+  const haystack = text.toLowerCase();
+  return AUTH_FAILURE_MARKERS.some(marker => haystack.includes(marker));
+}
+
+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;
+}
+
+/**
+ * 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: RunYarnInstallOptions): Promise<void> {
+  const token = tryReadAuthTokenSync();
+  const env = { ...process.env, ...(token && { [Z2H_NPM_TOKEN_ENV]: token }), ...opts.extraEnv };
+  const child = execa('yarn', ['install'], {
+    cwd: opts.cwd,
+    stdout: 'inherit',
+    stderr: ['inherit', 'pipe'],
+    env,
+  } satisfies ExecaOptions);
+
+  try {
+    await child;
+  } catch (err) {
+    const e = err as Error & { stderr?: string };
+    const combined = `${e.stderr}\n${e.message ?? ''}`;
+    if (looksLikeAuthFailure(combined)) {
+      const authErr = new Error('broker rejected the z2h token during install') as Error & {
+        isAuthFailure: true;
+      };
+      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.
+ */
+export async function runYarnInstall(opts: RunYarnInstallOptions): Promise<void> {
+  await ensureZ2hToken();
+
+  try {
+    await spawnYarnInstall(opts);
+  } catch (err) {
+    if (!(err as { isAuthFailure?: boolean }).isAuthFailure) {
+      throw err;
+    }
+    warn('your access expired — refreshing it now…');
+    await ensureZ2hToken({ forceRefresh: true });
+    info('access refreshed — retrying install');
+    await spawnYarnInstall(opts);
+  }
+}

package/src/util/tracker.ts

@@ -0,0 +1,25 @@
+import os from 'node:os';
+
+const DOORMAN_URL = 'https://track.bigbrain.me/prod/event';
+
+const username = os.userInfo().username;
+
+export function trackEvent(name: string, data: Record<string, unknown>): void {
+  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(() => {});
+}
+
+export async function trackDuration<T>(
+  eventName: string,
+  fn: () => Promise<T>,
+  data?: Record<string, unknown>
+): Promise<T> {
+  const start = Date.now();
+  const result = await fn();
+  trackEvent(eventName, { ...data, duration_ms: Date.now() - start });
+  return result;
+}