@mondaydotcomorg/z2h-cli 0.25.4 → 0.25.7

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

@@ -6,6 +6,7 @@ import {
   STS_BROKER_PATH,
 } from '../broker-credential-provider';
 import { DEFAULT_BROKER_BASE_URL } from '../../../constants';
+import { DeployError } from '../../errors';
 import * as authStore from '../auth-store';
 
 const STUB_CREDS = {
@@ -58,15 +59,22 @@ describe('fetchDeployVersion', () => {
     await expect(fetchDeployVersion('my-app')).resolves.toBe(0);
   });
 
-  it('surfaces a remediation hint on 401', async () => {
+  it('surfaces a remediation hint on 401, tagged broker_auth', async () => {
     mockFetchOnce({}, { status: 401, text: 'Unauthorized' });
     await expect(fetchDeployVersion('my-app')).rejects.toThrow(/token rejected by the broker/);
+    mockFetchOnce({}, { status: 401, text: 'Unauthorized' });
+    const err = await fetchDeployVersion('my-app').catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).reason).toBe('broker_auth');
   });
 
-  it('surfaces an access-denied hint on 403', async () => {
+  it('surfaces an access-denied hint on 403, tagged broker_auth', async () => {
     mockFetchOnce({}, { status: 403, text: 'Forbidden' });
     await expect(fetchDeployVersion('my-app')).rejects.toThrow(/Access denied/);
-    await expect(fetchDeployVersion('my-app')).rejects.toThrow(/z2h-cli grant/);
+    mockFetchOnce({}, { status: 403, text: 'Forbidden' });
+    const err = await fetchDeployVersion('my-app').catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).reason).toBe('broker_auth');
   });
 });
 
@@ -131,18 +139,28 @@ describe('brokerCredentialProvider', () => {
     expect(fetchMock).toHaveBeenCalledTimes(2);
   });
 
-  it('surfaces a remediation hint on 401', async () => {
+  it('surfaces a remediation hint on 401, tagged broker_auth', async () => {
     mockFetchOnce({}, { status: 401, text: 'Unauthorized' });
     const provider = brokerCredentialProvider({ appName: 'my-app' });
     await expect(provider()).rejects.toThrow(/token rejected by the broker/);
     await expect(provider()).rejects.toThrow(/generate-z2h-token/);
+
+    mockFetchOnce({}, { status: 401, text: 'Unauthorized' });
+    const err = await brokerCredentialProvider({ appName: 'my-app2' })().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).reason).toBe('broker_auth');
   });
 
-  it('surfaces an access-denied hint on 403', async () => {
+  it('surfaces an access-denied hint on 403, tagged broker_auth', async () => {
     mockFetchOnce({}, { status: 403, text: 'Forbidden' });
     const provider = brokerCredentialProvider({ appName: 'my-app' });
     await expect(provider()).rejects.toThrow(/Access denied/);
     await expect(provider()).rejects.toThrow(/z2h-cli grant/);
+
+    mockFetchOnce({}, { status: 403, text: 'Forbidden' });
+    const err = await brokerCredentialProvider({ appName: 'my-app3' })().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).reason).toBe('broker_auth');
   });
 
   it('honors Z2H_BROKER_BASE_URL override', async () => {
@@ -153,10 +171,28 @@ describe('brokerCredentialProvider', () => {
     expect(fetchMock).toHaveBeenCalledWith(`https://staging.example.com${STS_BROKER_PATH}`, expect.anything());
   });
 
-  it('rejects responses missing required credential fields', async () => {
+  it('rejects responses missing required credential fields, tagged broker_error', async () => {
     mockFetchOnce({ accessKeyId: 'AKIA-stub' });
-    const provider = brokerCredentialProvider({ appName: 'my-app' });
-    await expect(provider()).rejects.toThrow(/missing required credential fields/);
+    const err = await brokerCredentialProvider({ appName: 'my-app' })().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).message).toMatch(/missing required credential fields/);
+    expect((err as DeployError).reason).toBe('broker_error');
+  });
+
+  it('tags a non-auth broker status as broker_error, not broker_auth or unknown', async () => {
+    mockFetchOnce({}, { status: 502, text: 'Bad Gateway' });
+    const err = await brokerCredentialProvider({ appName: 'my-app' })().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).message).toMatch(/broker returned 502: Bad Gateway/);
+    expect((err as DeployError).reason).toBe('broker_error');
+  });
+
+  it('tags a network failure reaching the broker as broker_error', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new TypeError('fetch failed')));
+    const err = await brokerCredentialProvider({ appName: 'my-app' })().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).message).toMatch(/broker request failed: fetch failed/);
+    expect((err as DeployError).reason).toBe('broker_error');
   });
 
   describe('with previewId', () => {

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

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import os from 'node:os';
 import { pathExists, readJson, readJsonSync } from 'fs-extra';
+import { Z2hAuthMissingError } from '../errors';
 
 // 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
@@ -12,13 +13,6 @@ export interface ZthAuth {
   token: string;
 }
 
-export class Z2hAuthMissingError extends Error {
-  constructor(public readonly authFilePath: string) {
-    super(`No Z2H deploy token found at ${authFilePath}. Please run 'z2h-cli generate-z2h-token' command.`);
-    this.name = 'Z2hAuthMissingError';
-  }
-}
-
 export async function readZthAuth(): Promise<ZthAuth> {
   if (process.env.Z2H_AUTH_TOKEN) {
     const token = process.env.Z2H_AUTH_TOKEN;

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

@@ -1,4 +1,5 @@
 import { brokerBaseUrl, routingHeaders } from '../../constants';
+import { DeployError, messageOf } from '../errors';
 import { readZthAuth } from './auth-store';
 import type { AwsCredentialIdentity, AwsCredentialIdentityProvider } from '@aws-sdk/types';
 
@@ -34,22 +35,31 @@ async function postToBroker(path: string, body: unknown): Promise<Response> {
       body: JSON.stringify(body),
     });
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    throw new Error(`Z2H deploy broker request failed: ${message}`);
+    throw new DeployError('broker_error', `Z2H deploy broker request failed: ${messageOf(err)}`);
   }
 }
 
-function assertBrokerOk(res: Response): void {
+/**
+ * Classifies a broker response: 401/403 are `broker_auth` (the user can fix them), any
+ * other non-ok status is `broker_error` (the broker or the network, not the user).
+ */
+async function assertBrokerOk(res: Response, errorLabel: string): Promise<void> {
   if (res.status === 401) {
-    throw new Error(
+    throw new DeployError(
+      'broker_auth',
       `Z2H deploy token rejected by the broker (401). Refresh user token by running 'z2h-cli generate-z2h-token'.`
     );
   }
   if (res.status === 403) {
-    throw new Error(
+    throw new DeployError(
+      'broker_auth',
       `Access denied (403). You do not have editor access to this app. Ask the app owner to grant you access via 'z2h-cli grant'.`
     );
   }
+  if (!res.ok) {
+    const text = await res.text();
+    throw new DeployError('broker_error', `Z2H ${errorLabel} broker returned ${res.status}: ${text.slice(0, 1024)}`);
+  }
 }
 
 /**
@@ -59,11 +69,7 @@ function assertBrokerOk(res: Response): void {
  */
 export async function fetchDeployVersion(appName: string): Promise<number> {
   const res = await postToBroker(DEPLOY_VERSION_PATH, { appName });
-  assertBrokerOk(res);
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`Z2H deploy broker returned ${res.status}: ${text.slice(0, 1024)}`);
-  }
+  await assertBrokerOk(res, 'deploy');
   const body = (await res.json()) as VersionResponse;
 
   return body.version ?? 0;
@@ -71,11 +77,7 @@ export async function fetchDeployVersion(appName: string): Promise<number> {
 
 async function requestSts(path: string, body: unknown, errorLabel: string): Promise<AwsCredentialIdentity> {
   const res = await postToBroker(path, body);
-  assertBrokerOk(res);
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`Z2H ${errorLabel} broker returned ${res.status}: ${text.slice(0, 1024)}`);
-  }
+  await assertBrokerOk(res, errorLabel);
 
   const responseBody = (await res.json()) as CredentialsResponse;
   if (
@@ -84,7 +86,7 @@ async function requestSts(path: string, body: unknown, errorLabel: string): Prom
     !responseBody.sessionToken ||
     !responseBody.expiration
   ) {
-    throw new Error(`Z2H ${errorLabel} broker response missing required credential fields`);
+    throw new DeployError('broker_error', `Z2H ${errorLabel} broker response missing required credential fields`);
   }
 
   return {

package/src/util/broker/__tests__/app.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { registerOrUpdateApp } from '../app';
 import * as promptVisibility from '../../prompt-visibility';
+import { DeployError } from '../../errors';
 import type { ManifestEntry } from '../../manifest';
 
 vi.mock('../../prompt-visibility', () => ({
@@ -74,31 +75,33 @@ describe('registerOrUpdateApp', () => {
     expect(JSON.parse(init.body as string)).toMatchObject({ appName: 'mf-my-app', version: 3 });
   });
 
-  it('propagates a registration failure', async () => {
+  it('propagates a registration failure, tagged register_error', async () => {
     mockFetchOnce(409);
 
-    await expect(
-      registerOrUpdateApp({
-        appName: 'mf-my-app',
-        token: 'jwt',
-        nextVersion: 1,
-        entry: ENTRY,
-        gitRemote: '',
-      })
-    ).rejects.toThrow(/App registration failed/);
+    const err = await registerOrUpdateApp({
+      appName: 'mf-my-app',
+      token: 'jwt',
+      nextVersion: 1,
+      entry: ENTRY,
+      gitRemote: '',
+    }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).message).toMatch(/App registration failed/);
+    expect((err as DeployError).reason).toBe('register_error');
   });
 
-  it('propagates an update failure', async () => {
+  it('propagates an update failure, tagged register_error', async () => {
     mockFetchOnce(500);
 
-    await expect(
-      registerOrUpdateApp({
-        appName: 'mf-my-app',
-        token: 'jwt',
-        nextVersion: 2,
-        entry: ENTRY,
-        gitRemote: '',
-      })
-    ).rejects.toThrow(/App update failed/);
+    const err = await registerOrUpdateApp({
+      appName: 'mf-my-app',
+      token: 'jwt',
+      nextVersion: 2,
+      entry: ENTRY,
+      gitRemote: '',
+    }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).message).toMatch(/App update failed/);
+    expect((err as DeployError).reason).toBe('register_error');
   });
 });

package/src/util/broker/app.ts

@@ -2,6 +2,7 @@ import { brokerBaseUrl, routingHeaders } from '../../constants';
 import { readZthAuth } from '../auth/auth-store';
 import { info } from '../logger';
 import { resolveAppVisibility } from '../prompt-visibility';
+import { DeployError, tagDeployError } from '../errors';
 import type { ManifestEntry } from '../manifest';
 
 export interface AppInfo {
@@ -58,7 +59,7 @@ async function registerApp(
   });
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`App registration failed (${res.status}): ${text.slice(0, 1024)}`);
+    throw new DeployError('register_error', `App registration failed (${res.status}): ${text.slice(0, 1024)}`);
   }
 }
 
@@ -79,7 +80,7 @@ async function updateApp(
   });
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`App update failed (${res.status}): ${text.slice(0, 1024)}`);
+    throw new DeployError('register_error', `App update failed (${res.status}): ${text.slice(0, 1024)}`);
   }
 }
 
@@ -102,12 +103,18 @@ export interface RegisterOrUpdateOptions {
 export async function registerOrUpdateApp(opts: RegisterOrUpdateOptions): Promise<void> {
   const { appName, token, nextVersion, entry, gitRemote, integrations, description } = opts;
 
-  if (nextVersion === 1) {
-    const visibility = await resolveAppVisibility(appName);
-    info(`registering "${appName}" → v${nextVersion} (${visibility})`);
-    await registerApp(appName, token, nextVersion, entry, visibility, gitRemote, integrations, description);
-  } else {
-    info(`updating "${appName}" → v${nextVersion}`);
-    await updateApp(appName, token, nextVersion, entry, gitRemote, integrations, description);
+  try {
+    if (nextVersion === 1) {
+      const visibility = await resolveAppVisibility(appName);
+      info(`registering "${appName}" → v${nextVersion} (${visibility})`);
+      await registerApp(appName, token, nextVersion, entry, visibility, gitRemote, integrations, description);
+    } else {
+      info(`updating "${appName}" → v${nextVersion}`);
+      await updateApp(appName, token, nextVersion, entry, gitRemote, integrations, description);
+    }
+  } catch (err) {
+    // registerApp/updateApp already tag the non-ok-response case; this catches anything
+    // else (a network throw, a resolveAppVisibility failure) under the same reason.
+    throw tagDeployError('register_error', err);
   }
 }

package/src/util/errors.ts

@@ -0,0 +1,98 @@
+import type { DeployFailureReason, GrantFailureReason } from '../types';
+
+/**
+ * Base for every error the CLI classifies. runCommand in ./run-command.ts reads `reason`
+ * and `data` straight off the error, so the throw site is the only place that needs to know
+ * why it failed. Nothing re-derives it from the error type at the top level.
+ *
+ * `exitCode` lets a throw site override the CLI's --help contract, 1 for user-resolvable
+ * and 2 for system failures, per error instead of per command. Nothing sets it yet. The
+ * command table still pins exit codes, which keeps today's behavior.
+ */
+export class Z2hError extends Error {
+  constructor(
+    message: string,
+    readonly reason: string,
+    readonly data?: Record<string, unknown>,
+    readonly exitCode: number = 1
+  ) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+/** Tags a deploy/preview stage failure with a bounded reason code instead of a freeform message. */
+export class DeployError extends Z2hError {
+  constructor(override readonly reason: DeployFailureReason, message: string, data?: Record<string, unknown>) {
+    super(message, reason, data);
+  }
+}
+
+/**
+ * Tags a grant/revoke/transfer-owner failure with a bounded reason code instead of a freeform message.
+ * `reason` also accepts a raw HTTP status, which gets mapped to a bounded reason internally.
+ */
+export class GrantError extends Z2hError {
+  constructor(reason: GrantFailureReason | number, message: string, data?: Record<string, unknown>) {
+    super(message, typeof reason === 'number' ? grantReasonForStatus(reason) : reason, data);
+  }
+}
+
+/** No z2h JWT found — see auth-store.ts for the discovery order (env var, then ~/.zth/auth.json). */
+export class Z2hAuthMissingError extends Z2hError {
+  constructor(public readonly authFilePath: string) {
+    super(
+      `No Z2H deploy token found at ${authFilePath}. Please run 'z2h-cli generate-z2h-token' command.`,
+      'read_auth_token'
+    );
+  }
+}
+
+/** A git pull diverged or a push was rejected; `reason` distinguishes which stage hit it. */
+export class GitConflictError extends Z2hError {
+  constructor(message: string, reason: DeployFailureReason = 'git_error') {
+    super(message, reason);
+  }
+}
+
+/** Maps an HTTP status to a bounded grant/revoke/transfer-owner failure reason. */
+export function grantReasonForStatus(status: number): GrantFailureReason {
+  // 401 is an expired/invalid token (re-auth fixes it); 403 is a real permission denial.
+  if (status === 401) {
+    return 'auth';
+  }
+  if (status === 403) {
+    return 'forbidden';
+  }
+  if (status === 404) {
+    return 'not_found';
+  }
+  if (status >= 500) {
+    return 'server_error';
+  }
+  return 'unknown';
+}
+
+/** Tags a failure with `reason`, unless `err` is already classified; `signal` overrides `reason` for a killed child process. */
+export function tagDeployError(reason: DeployFailureReason, err: unknown): Z2hError {
+  if (err instanceof Z2hError) {
+    return err;
+  }
+  const signal = err instanceof Error ? (err as Error & { signal?: string }).signal : undefined;
+  return new DeployError(signal ? 'interrupted' : reason, messageOf(err));
+}
+
+/** Reads the bounded reason off a classified error; anything unclassified is `unknown`. */
+export function reasonOf(err: unknown): string {
+  return err instanceof Z2hError ? err.reason : 'unknown';
+}
+
+/** Extra telemetry dimensions the throw site attached, if any. */
+export function dataOf(err: unknown): Record<string, unknown> {
+  return err instanceof Z2hError ? err.data ?? {} : {};
+}
+
+/** Safe message for any thrown value. A non-Error throw must not break the error path. */
+export function messageOf(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/util/git/__tests__/repo.test.ts

@@ -4,7 +4,6 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { execa } from 'execa';
 import fs from 'fs-extra';
 import {
-  GitConflictError,
   defaultS3Remote,
   initRepo,
   cloneRepo,
@@ -15,6 +14,7 @@ import {
   remoteHead,
   localHead,
 } from '../repo';
+import { GitConflictError } from '../../errors';
 
 vi.mock('execa', () => ({ execa: vi.fn() }));
 vi.mock('fs-extra', () => ({
@@ -236,7 +236,7 @@ describe('pushToRemote', () => {
     expect(mockExeca).toHaveBeenCalledWith('git', ['push', '-u', 'origin', 'master'], expect.objectContaining({}));
   });
 
-  it('throws GitConflictError with structured JSON when push is rejected', async () => {
+  it('throws GitConflictError tagged push_error (not git_error) with structured JSON when push is rejected', async () => {
     mockExeca
       .mockRejectedValueOnce(new Error('![rejected] master -> master (non-fast-forward)')) // git push
       .mockResolvedValueOnce(execaOk()) // gatherConflictInfo: git fetch origin
@@ -247,17 +247,19 @@ describe('pushToRemote', () => {
     const err = await pushToRemote(DIR).catch(e => e);
 
     expect(err).toBeInstanceOf(GitConflictError);
+    expect(err.reason).toBe('push_error');
     const info = JSON.parse(err.message.split('Git conflict detected: ')[1]);
     expect(info.localCommits).toEqual(['abc local']);
     expect(info.remoteCommits).toEqual(['def remote']);
     expect(info.conflictingFiles).toEqual(['file.ts']);
   });
 
-  it('re-throws non-rejection push errors as-is', async () => {
+  it('tags a non-rejection push error push_error, keeping the original message', async () => {
     mockExeca.mockRejectedValueOnce(new Error('Connection refused'));
 
     const err = await pushToRemote(DIR).catch(e => e);
     expect(err).not.toBeInstanceOf(GitConflictError);
+    expect(err.reason).toBe('push_error');
     expect(err.message).toMatch(/Connection refused/);
   });
 

package/src/util/git/repo.ts

@@ -3,6 +3,7 @@ import fs from 'fs-extra';
 import { execa } from 'execa';
 import { BUCKET_WRITE_NAME } from '../../constants';
 import { mfAppName } from '../app-name';
+import { DeployError, GitConflictError, messageOf } from '../errors';
 
 type GitEnv = Record<string, string | undefined>;
 
@@ -16,13 +17,6 @@ async function execGitLines(args: string[], dir: string, env?: GitEnv): Promise<
     .catch(() => []);
 }
 
-export class GitConflictError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'GitConflictError';
-  }
-}
-
 export interface ConflictInfo {
   localCommits: string[];
   remoteCommits: string[];
@@ -137,9 +131,9 @@ export async function pushToRemote(dir: string, env?: Record<string, string>): P
     }
     if (isRejected) {
       const info = await gatherConflictInfo(dir, gitEnv);
-      throw new GitConflictError(`Push rejected: Git conflict detected: ${JSON.stringify(info)}`);
+      throw new GitConflictError(`Push rejected: Git conflict detected: ${JSON.stringify(info)}`, 'push_error');
     }
-    throw err;
+    throw new DeployError('push_error', messageOf(err));
   }
 }
 

package/src/util/logger.ts

@@ -1,4 +1,5 @@
 import pc from 'picocolors';
+import { Z2hCliEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
 import { trackEvent } from './tracker';
 
 export type OutputMode = 'human' | 'json';
@@ -51,16 +52,28 @@ export function output(human: string, data: unknown): void {
 /**
  * Emit a structured failure payload (JSON mode) or a red error line (human mode),
  * then exit with the given code.
+ *
+ * `track: false` skips the telemetry event but still prints and exits. Commands with no
+ * success event pass it, so their failures don't skew per-command error rates.
  */
-export async function fail(message: string, payload: Record<string, unknown>, exitCode = 1): Promise<never> {
+export async function fail(
+  message: string,
+  payload: Record<string, unknown>,
+  exitCode = 1,
+  track = true
+): Promise<never> {
+  // Canonical fields go last so a payload key can never shadow `error`/`action`.
+  const { command, ...rest } = payload;
   if (mode === 'json') {
-    process.stdout.write(`${JSON.stringify({ ok: false, error: message, ...payload })}\n`);
+    process.stdout.write(`${JSON.stringify({ ok: false, ...payload, error: message })}\n`);
   } else {
     process.stderr.write(pc.red(`[z2h-cli] ${message}\n`));
     if (typeof payload.suggestedCommand === 'string') {
       process.stderr.write(pc.dim(`  → ${payload.suggestedCommand}\n`));
     }
   }
-  await trackEvent('z2h_cli_error', { action: payload.command ?? 'unknown', error: message });
+  if (track) {
+    await trackEvent(Z2hCliEvents.error, { ...rest, action: command ?? 'unknown', error: message });
+  }
   process.exit(exitCode);
 }

package/src/util/run-command.ts

@@ -0,0 +1,59 @@
+import { fail } from './logger';
+import { trackDuration, successEvent } from './tracker';
+import { Z2hError, reasonOf, dataOf, messageOf } from './errors';
+import type { Command } from 'commander';
+import type { CommandSpec, PerArgs } from '../types';
+
+type SpecFieldFn<A extends unknown[], T> = (args: A) => T;
+type SpecFieldResolver<A extends unknown[]> = <T>(field: PerArgs<A, T> | undefined, fallback: T) => T;
+type ResolveSpecField = <A extends unknown[], T>(field: PerArgs<A, T> | undefined, args: A, fallback: T) => T;
+
+/** A spec field is a constant, a callback over the args, or absent — in which case `fallback` applies. */
+const resolveSpecField: ResolveSpecField = (field, args, fallback) => {
+  if (field === undefined) {
+    return fallback;
+  }
+  return typeof field === 'function' ? (field as SpecFieldFn<typeof args, typeof fallback>)(args) : field;
+};
+
+/**
+ * Wraps a command body with the whole telemetry and failure contract so no command
+ * hand-rolls it. It times the happy path. On a throw it reads `reason` and `data` straight
+ * off the error, defined in ./errors, instead of re-deriving them per command.
+ *
+ * Returns a commander action handler, chainable straight off `.command(...)` — commander always
+ * appends the Command instance as the action handler's last argument, so this splits it back off
+ * to read the command's own name/parent instead of asking the caller to pass it in.
+ *
+ * NoInfer keeps the arg types coming from `fn` alone. A `data` or `label` callback that
+ * only needs the first arg must not narrow the handler's own signature.
+ */
+export function runCommand<A extends unknown[]>(
+  spec: CommandSpec<NoInfer<A>>,
+  fn: (...args: A) => Promise<unknown>
+): (...args: [...A, Command]) => Promise<void> {
+  return async (...allArgs: [...A, Command]): Promise<void> => {
+    const cmd = allArgs[allArgs.length - 1] as Command;
+    const args = allArgs.slice(0, -1) as A;
+    const name = cmd.parent ? `${cmd.parent.name()} ${cmd.name()}` : cmd.name();
+    const resolve: SpecFieldResolver<A> = (v, fallback) => resolveSpecField(v, args, fallback);
+    const track = resolve(spec.track, true);
+    const label = resolve(spec.label, name);
+    const event = resolve(spec.event, successEvent(name));
+    const data = spec.data?.(args) ?? {};
+    try {
+      await (track ? trackDuration(event, () => fn(...args), data) : fn(...args));
+    } catch (err) {
+      const reason = reasonOf(err);
+      // A deploy/preview that failed because the consumer's own build broke isn't a CLI/infra
+      // problem — don't report it at all, not even as `unknown`.
+      const shouldTrack = track && reason !== 'build_error';
+      await fail(
+        `${label} failed: ${messageOf(err)}`,
+        { command: label, reason, ...data, ...dataOf(err) },
+        spec.exitCode ?? (err instanceof Z2hError ? err.exitCode : 1),
+        shouldTrack
+      );
+    }
+  };
+}

package/src/util/s3/upload.ts

@@ -5,6 +5,7 @@ import { lookup as lookupMime } from 'mime-types';
 import pMap from 'p-map';
 import { PutObjectCommand } from '@aws-sdk/client-s3';
 import { BUCKET_WRITE_NAME } from '../../constants';
+import { tagDeployError } from '../errors';
 import { getS3Client } from './client';
 
 // Each deploy uploads to a version-prefixed path (<app>/<version>/...), so
@@ -18,29 +19,33 @@ export async function uploadDir(
   keyPrefix: string,
   bucket: string = BUCKET_WRITE_NAME
 ): Promise<string[]> {
-  const entries = await readdir(localDir, { recursive: true, withFileTypes: true });
-  const files = entries.filter(e => e.isFile()).map(e => path.relative(localDir, path.join(e.parentPath, e.name)));
+  try {
+    const entries = await readdir(localDir, { recursive: true, withFileTypes: true });
+    const files = entries.filter(e => e.isFile()).map(e => path.relative(localDir, path.join(e.parentPath, e.name)));
 
-  const s3 = getS3Client();
+    const s3 = getS3Client();
 
-  await pMap(
-    files,
-    async rel => {
-      const body = await readFile(path.join(localDir, rel));
-      const contentType = lookupMime(rel) || 'application/octet-stream';
-      const key = `${keyPrefix}/${rel.split(path.sep).join('/')}`;
-      await s3.send(
-        new PutObjectCommand({
-          Bucket: bucket,
-          Key: key,
-          Body: body,
-          ContentType: contentType,
-          CacheControl: FOREVER,
-        })
-      );
-    },
-    { concurrency: UPLOAD_CONCURRENCY }
-  );
+    await pMap(
+      files,
+      async rel => {
+        const body = await readFile(path.join(localDir, rel));
+        const contentType = lookupMime(rel) || 'application/octet-stream';
+        const key = `${keyPrefix}/${rel.split(path.sep).join('/')}`;
+        await s3.send(
+          new PutObjectCommand({
+            Bucket: bucket,
+            Key: key,
+            Body: body,
+            ContentType: contentType,
+            CacheControl: FOREVER,
+          })
+        );
+      },
+      { concurrency: UPLOAD_CONCURRENCY }
+    );
 
-  return files.map(f => f.split(path.sep).join('/'));
+    return files.map(f => f.split(path.sep).join('/'));
+  } catch (err) {
+    throw tagDeployError('s3_error', err);
+  }
 }