@mondaydotcomorg/z2h-cli 0.25.4 → 0.25.8

package/handler-api/backend-runner/channels/snowflake-channel/snowflake.channel.ts

@@ -33,7 +33,11 @@ export function makeSnowflakeChannel(appName: string) {
      *
      * @param sql - A SELECT statement. Non-SELECT is rejected with `400`.
      * @param params - Optional map of `:name` → `string | number | boolean | null` bindings.
-     * @param options - Optional `{ timeoutMs?: number }` — clamped to 5 min (`MAX_TIMEOUT_MS`); effective ceiling is ~5.5 min including the host backstop.
+     * @param options - Optional `{ timeoutMs?: number, identifier?: string }`. `timeoutMs` is
+     *   clamped to 5 min (`MAX_TIMEOUT_MS`); effective ceiling is ~5.5 min including the host
+     *   backstop. `identifier` names this query in logs/metrics and the Snowflake pool identifier
+     *   (e.g. a widget name) instead of the default query-shape hash — sanitized to `[a-z0-9-_]`,
+     *   max 64 chars.
      * @returns Array of row objects with **camelCase keys** — SQL aliases are normalized
      *   to camelCase regardless of their casing in the query
      *   (e.g. `AS current_user` → `rows[0].currentUser`, `AS total_count` → `rows[0].totalCount`).
@@ -63,6 +67,14 @@ export function makeSnowflakeChannel(appName: string) {
      *   { timeoutMs: 25_000 },
      * );
      *
+     * @example
+     * // Name this query in logs/metrics instead of the default hash
+     * const rows = await ctx.api.v1.snowflake.query(
+     *   `SELECT COUNT(*) AS total FROM monday_items`,
+     *   undefined,
+     *   { identifier: 'total-items-kpi' },
+     * );
+     *
      * @throws `400` `snowflake_invalid_argument` — `sql` was not a non-empty string.
      * @throws `400` `snowflake_not_read_only` — the statement is not a SELECT.
      * @throws `400` `snowflake_invalid_sql` — the statement could not be parsed.
@@ -96,8 +108,8 @@ export function makeSnowflakeChannel(appName: string) {
       }
       return runSnowflakeQuery(
         query,
-        params as Record<string, SnowflakeParamValue> | null | undefined,
         appName,
+        params as Record<string, SnowflakeParamValue> | null | undefined,
         options as RunQueryOptions | null | undefined,
       );
     },

package/handler-api/backend-runner/channels/snowflake-channel/stateless-part-b.ts

@@ -23,10 +23,7 @@ export interface SnowflakeConnectionDetails {
   defaultDatabase?: string;
 }
 
-export function isStatelessPartBApp(appName: string | undefined): boolean {
-  if (!appName) {
-    return false;
-  }
+export function isStatelessPartBApp(appName: string): boolean {
   const { allowed } = getConfiguration(ConfigurationKey.Z2H_STATELESS_PART_B_APPS);
   return Array.isArray(allowed) && allowed.includes(appName);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.25.4",
+  "version": "0.25.8",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -51,7 +51,7 @@
   ],
   "dependencies": {
     "@aws-sdk/client-s3": "^3.706.0",
-    "@mondaydotcomorg/z2h-shared-utils": "^0.3.4",
+    "@mondaydotcomorg/z2h-shared-utils": "^0.4.2",
     "chokidar": "^3.6.0",
     "commander": "^12.1.0",
     "cors": "^2.8.6",

package/src/auth.ts

@@ -1,2 +1,3 @@
 export { generateZ2HTokenCommand, type GenerateZ2HTokenOptions } from './commands/generate-z2h-token';
-export { readZthAuth, Z2hAuthMissingError, Z2H_AUTH_FILE, type ZthAuth } from './util/auth/auth-store';
+export { readZthAuth, Z2H_AUTH_FILE, type ZthAuth } from './util/auth/auth-store';
+export { Z2hAuthMissingError } from './util/errors';

package/src/commands/__tests__/backend-deploy.test.ts

@@ -5,6 +5,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { deployBackend, hasHandlers } from '../backend';
 import { readHandlers } from '../../backend/handlers';
+import { DeployError } from '../../util/errors';
 
 vi.mock('../../backend/handlers', () => ({
   readHandlers: vi.fn(),
@@ -96,6 +97,23 @@ describe('deployBackend (live)', () => {
     const keys: string[] = mockSend.mock.calls.map((c: unknown[]) => (c[0] as { input: { Key: string } }).input.Key);
     expect(keys.some(k => k.includes('/backend-1/'))).toBe(true);
   });
+
+  it('tags a handler upload failure as deploy_backend_error, not register_error', async () => {
+    await ensureDir(path.join(tmp, 'backend', 'handlers'));
+    mockSend.mockRejectedValueOnce(new Error('AccessDenied'));
+
+    const err = await deployBackend({
+      appDir: tmp,
+      appName: 'mf-my-app',
+      mfKeyPrefix: 'mf-my-app/1',
+      version: 1,
+      deployedBy: 'test-user',
+      isPreview: false,
+    }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).reason).toBe('deploy_backend_error');
+    expect((err as DeployError).message).toBe('AccessDenied');
+  });
 });
 
 describe('deployBackend (preview)', () => {

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

@@ -0,0 +1,83 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { execa } from 'execa';
+import { pathExists } from 'fs-extra';
+import { buildCommand } from '../build';
+import { DeployError } from '../../util/errors';
+import type { PreparedShadow } from '../../types';
+
+vi.mock('execa', () => ({ execa: vi.fn() }));
+vi.mock('fs-extra', () => ({ pathExists: vi.fn(), readJson: vi.fn() }));
+vi.mock('../../shadow/prepare', () => ({ prepareShadow: vi.fn() }));
+
+const { prepareShadow } = await import('../../shadow/prepare');
+const mockExeca = vi.mocked(execa);
+const mockPathExists = vi.mocked(pathExists);
+
+const STUB_SHADOW: PreparedShadow = {
+  appName: 'my-app',
+  port: 13000,
+  paths: {
+    consumerDir: '/tmp/my-app',
+    consumerPkg: '/tmp/my-app/package.json',
+    consumerSrc: '/tmp/my-app/src',
+    consumerSrcEntry: '/tmp/my-app/src/index.tsx',
+    shadowDir: '/tmp/my-app/.zth',
+    shadowPkg: '/tmp/my-app/.zth/package.json',
+    shadowSrc: '/tmp/my-app/.zth/src',
+    shadowWrapper: '/tmp/my-app/.zth/src/wrapper.tsx',
+    shadowTridentrc: '/tmp/my-app/.zth/.tridentrc.js',
+    shadowNvmrc: '/tmp/my-app/.zth/.nvmrc',
+    shadowDts: '/tmp/my-app/.zth/global.d.ts',
+    shadowTsconfig: '/tmp/my-app/.zth/tsconfig.json',
+    shadowBuild: '/tmp/my-app/.zth/build',
+    shadowDepsHash: '/tmp/my-app/.zth/.deps-hash',
+    shadowMetadata: '/tmp/my-app/.zth/metadata.json',
+  },
+};
+
+beforeEach(() => {
+  vi.mocked(prepareShadow).mockReset().mockResolvedValue(STUB_SHADOW);
+  mockExeca.mockReset();
+  mockPathExists.mockReset();
+});
+
+// Both execa calls (typecheck, then build) can fail for the same reasons — cover the
+// tagging once against the typecheck call rather than duplicating it for both. buildCommand
+// itself doesn't report to telemetry (the standalone `build` command opts out in index.ts) —
+// it just needs to be informative, and to carry a reason for when it surfaces through `deploy`.
+describe('buildCommand failure tagging', () => {
+  it('tags a compile/bundle failure as build_error', async () => {
+    mockExeca.mockRejectedValueOnce(new Error('tsc exploded'));
+
+    const err = await buildCommand().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).reason).toBe('build_error');
+    expect((err as DeployError).message).toBe('tsc exploded');
+  });
+
+  it('tags a signal-killed build as interrupted, not build_error', async () => {
+    mockExeca.mockRejectedValueOnce(Object.assign(new Error('killed'), { signal: 'SIGINT' }));
+
+    const err = await buildCommand().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).reason).toBe('interrupted');
+  });
+
+  it('survives a non-Error throw instead of masking it with a TypeError', async () => {
+    mockExeca.mockRejectedValueOnce('boom');
+
+    const err = await buildCommand().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).reason).toBe('build_error');
+    expect((err as DeployError).message).toBe('boom');
+  });
+
+  it('tags missing build output as build_error', async () => {
+    mockExeca.mockResolvedValue({ stdout: '' } as never);
+    mockPathExists.mockResolvedValue(false as never);
+
+    const err = await buildCommand().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    expect((err as DeployError).reason).toBe('build_error');
+  });
+});

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

@@ -4,6 +4,7 @@ import { mkdtemp, rm, ensureDir, writeJson } from 'fs-extra';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { deployCommand } from '../deploy';
+import { DeployError, reasonOf } from '../../util/errors';
 import { buildPreviewSlug } from '../../util/app-name';
 import { setOutputMode } from '../../util/logger';
 import { buildCommand } from '../build';
@@ -201,6 +202,24 @@ describe('deploy --preview', () => {
     expect(openInBrowser).not.toHaveBeenCalled();
   });
 
+  it('propagates an unclassified failure as-is; runCommand reports it as unknown', async () => {
+    vi.mocked(brokerProvider.fetchDeployVersion).mockRejectedValue(new Error('something nobody tagged'));
+
+    const err = await deployCommand({ preview: true }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect(err).not.toBeInstanceOf(DeployError);
+    expect(reasonOf(err)).toBe('unknown');
+  });
+
+  it('propagates a stage-tagged reason untouched', async () => {
+    vi.mocked(brokerApp.registerOrUpdateApp).mockRejectedValue(
+      new DeployError('register_error', 'App registration failed')
+    );
+
+    const err = await deployCommand({ preview: true }).catch((e: unknown) => e);
+    expect((err as DeployError).reason).toBe('register_error');
+  });
+
   it('rejects deploying a preview for an app already named with the preview prefix', async () => {
     await writeJson(path.join(tmp, 'package.json'), { name: 'zth-preview-abc123-my-app' });
     await expect(deployCommand({ preview: true })).rejects.toThrow(/reserved for the ephemeral preview mechanism/);
@@ -228,3 +247,91 @@ describe('deploy --preview', () => {
     writeSpy.mockRestore();
   });
 });
+
+describe('deploy failure reasons', () => {
+  let tmp: string;
+  let cwd: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-reason-'));
+    cwd = process.cwd();
+    process.chdir(tmp);
+    tmp = process.cwd();
+    await writeJson(path.join(tmp, 'package.json'), { name: '@mondaydotcomorg/my-app' });
+    await ensureDir(path.join(tmp, '.zth', 'build'));
+
+    vi.spyOn(authStore, 'readZthAuth').mockResolvedValue({ token: 'jwt-stub' });
+    vi.mocked(brokerProvider.fetchDeployVersion).mockReset().mockResolvedValue(0);
+    vi.mocked(gitRepo.getRemoteUrl).mockReset().mockResolvedValue('https://github.com/org/repo.git');
+    vi.mocked(gitRepo.guardCleanTree).mockReset().mockResolvedValue(undefined);
+    vi.mocked(gitRepo.pullAndResolve).mockReset().mockResolvedValue(undefined);
+    vi.mocked(buildCommand)
+      .mockReset()
+      .mockResolvedValue({
+        appName: 'my-app',
+        port: 13000,
+        buildDir: path.join(tmp, '.zth', 'build'),
+        assetManifest: ASSET_MANIFEST,
+      });
+  });
+
+  afterEach(async () => {
+    process.chdir(cwd);
+    vi.unstubAllGlobals();
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  /** Runs a live deploy expected to fail, and returns the tagged error. */
+  const failedDeploy = async (): Promise<DeployError> => {
+    const err = await deployCommand().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeployError);
+    return err as DeployError;
+  };
+
+  it('tags a missing local token as read_auth_token', async () => {
+    vi.mocked(authStore.readZthAuth).mockRejectedValue(new Error('no auth.json'));
+    expect((await failedDeploy()).reason).toBe('read_auth_token');
+  });
+
+  it('tags a dirty working tree as git_error, not unknown', async () => {
+    vi.mocked(gitRepo.guardCleanTree).mockRejectedValue(new Error('working tree has uncommitted changes'));
+    expect((await failedDeploy()).reason).toBe('git_error');
+  });
+
+  it('tags a divergence during sync as git_error', async () => {
+    vi.mocked(gitRepo.pullAndResolve).mockRejectedValue(new Error('conflict'));
+    expect((await failedDeploy()).reason).toBe('git_error');
+  });
+
+  /** Stubs the lock endpoint (raw `fetch`) to answer `status`; the release call is best-effort and ignored. */
+  const stubLockResponse = (status: number) =>
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: status < 400, status, text: async () => `lock ${status}` }));
+
+  it('tags lock contention (409) as lock_timeout', async () => {
+    stubLockResponse(409);
+    expect((await failedDeploy()).reason).toBe('lock_timeout');
+  });
+
+  it('tags a lock-endpoint outage as broker_error, not lock contention or unknown', async () => {
+    stubLockResponse(503);
+    const err = await failedDeploy();
+    expect(err.reason).toBe('broker_error');
+    expect(err.message).toMatch(/Failed to acquire deploy lock \(503\)/);
+  });
+
+  it('tags a network failure reaching the lock endpoint as broker_error', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new TypeError('fetch failed')));
+    expect((await failedDeploy()).reason).toBe('broker_error');
+  });
+
+  // buildCommand throws plain errors (see commands/__tests__/build.test.ts), so a build
+  // failure surfaces as untagged here — see the propagation test below. The STS 401/403 →
+  // auth tagging lives in broker-credential-provider.ts — see its own test file.
+
+  it('a preview propagates its build failure the same way a live deploy does', async () => {
+    vi.mocked(buildCommand).mockRejectedValue(new Error('tsc exploded'));
+    const err = await deployCommand({ preview: true }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toMatch(/tsc exploded/);
+  });
+});

package/src/commands/backend.ts

@@ -8,6 +8,7 @@ import { detectIntegrationsFromHandlers } from '../backend/detect-integrations';
 import { getS3Client } from '../util/s3/client';
 import { BUCKET_WRITE_NAME } from '../constants';
 import { invokeBackend } from '../backend/client';
+import { tagDeployError } from '../util/errors';
 
 function currentAppName(): string {
   const raw = getCwdAppName();
@@ -86,7 +87,11 @@ export async function deployBackend(opts: {
   const { appDir, appName, mfKeyPrefix, version, deployedBy, isPreview } = opts;
   const prefix = isPreview ? `${mfKeyPrefix.replace(/\/MF$/, '')}/MS` : `${appName}/backend-${version}`;
   const logLabel = isPreview ? 'for preview' : `for "${appName}"`;
-  return readDetectAndUpload(appDir, prefix, version, deployedBy, logLabel);
+  try {
+    return await readDetectAndUpload(appDir, prefix, version, deployedBy, logLabel);
+  } catch (err) {
+    throw tagDeployError('deploy_backend_error', err);
+  }
 }
 
 export async function backendInvokeCommand(handlerName: string, opts: { input?: string } = {}): Promise<void> {

package/src/commands/build.ts

@@ -3,6 +3,7 @@ import { pathExists, readJson } from 'fs-extra';
 import { execa } from 'execa';
 import { info, output } from '../util/logger';
 import { prepareShadow } from '../shadow/prepare';
+import { DeployError, messageOf } from '../util/errors';
 import type { AssetManifestFile } from '../util/manifest';
 
 export interface BuildOptions {
@@ -18,6 +19,15 @@ export interface BuildResult {
 
 // Should be run from the consumer app directory — uses process.cwd() to locate it.
 export async function buildCommand(opts: BuildOptions = {}): Promise<BuildResult> {
+  try {
+    return await runBuild(opts);
+  } catch (err) {
+    const signal = err instanceof Error ? (err as Error & { signal?: string }).signal : undefined;
+    throw new DeployError(signal ? 'interrupted' : 'build_error', messageOf(err));
+  }
+}
+
+async function runBuild(opts: BuildOptions): Promise<BuildResult> {
   const ctx = await prepareShadow();
 
   // Typecheck against the shadow's tsconfig (the consumer dir has none).

package/src/commands/deploy.ts

@@ -22,10 +22,11 @@ import { getMachineAppName } from '../util/machine-identity';
 import { registerOrUpdateApp } from '../util/broker/app';
 import { openInBrowser } from '../util/open-browser';
 import { resolvePortAndMetadata } from '../shadow/prepare';
+import { DeployError, tagDeployError, grantReasonForStatus } from '../util/errors';
 import { deployBackend } from './backend';
 import { buildCommand } from './build';
 import { promptForTags } from './tag';
-import type { ConsumerPaths } from '../types';
+import type { ConsumerPaths, DeployFailureReason } from '../types';
 import type { ManifestEntry } from '../util/manifest';
 
 /** Who is publishing this version — the machine identity, else the OS user. */
@@ -63,7 +64,12 @@ export async function deployCommand(opts: DeployOptions = {}): Promise<void> {
 
   // Validate the user's deploy token is on disk before doing any expensive
   // work. Throws Z2hAuthMissingError with a remediation hint if not.
-  const { token } = await readZthAuth();
+  let token: string;
+  try {
+    ({ token } = await readZthAuth());
+  } catch (err) {
+    throw tagDeployError('read_auth_token', err);
+  }
 
   const ctx: DeployContext = { paths, consumerName: consumerPkg.name, appName, token, opts };
 
@@ -145,6 +151,8 @@ async function deployPreview({ paths, consumerName, appName, token, opts }: Depl
   // entry's `url` verbatim as the asset base, never joined with its own mfUrl.
   const url = `${BUCKET_READ_DNS_URL}/${keyPrefix}`;
 
+  // No catch-all: every stage below tags its own DeployError reason at the throw site,
+  // and anything unclassified reports as `unknown` via reasonOf() in runCommand.
   const nextVersion = (await fetchDeployVersion(previewAppName)) + 1;
 
   info('building');
@@ -199,10 +207,10 @@ async function deployLive({ paths, consumerName, appName, token, opts }: DeployC
     if (!opts.remote) {
       throw new Error(
         `This app has no git remote. On first deploy, tell Z2H how to track source:\n\n` +
-          `  z2h-cli deploy --remote s3 (default)\n` +
-          `      Stores source history in S3 alongside your app. No extra setup.\n\n` +
+          `  z2h-cli deploy --remote s3 (default, recommended)\n` +
+          `      We store and back up your code for you automatically. No extra setup.\n\n` +
           `  z2h-cli deploy --remote github --repo-url https://github.com/org/repo.git\n` +
-          `      Uses an existing GitHub repo (must exist before deploying).`
+          `      Manage it yourself in an existing GitHub repo (must exist before deploying).`
       );
     }
     validateRemoteOptions(opts);
@@ -223,9 +231,13 @@ async function deployLive({ paths, consumerName, appName, token, opts }: DeployC
   // The skill commits the working tree (with an LLM-authored message) before
   // invoking deploy, so the tree should be clean here.
   if (gitRemote) {
-    await guardCleanTree(process.cwd());
-    info('syncing with git remote');
-    await pullAndResolve(process.cwd(), gitEnv);
+    try {
+      await guardCleanTree(process.cwd());
+      info('syncing with git remote');
+      await pullAndResolve(process.cwd(), gitEnv);
+    } catch (err) {
+      throw tagDeployError('git_error', err);
+    }
   }
 
   info('reading current Z2H manifest');
@@ -249,7 +261,6 @@ async function deployLive({ paths, consumerName, appName, token, opts }: DeployC
     return;
   }
 
-  // lock → git push → bundle upload → manifest PUT (the manifest write is the single commit point).
   try {
     // Acquire the deploy lock explicitly. Done after the build
     // so the lock hold stays tiny — it wraps only push → upload → manifest.
@@ -279,6 +290,8 @@ async function deployLive({ paths, consumerName, appName, token, opts }: DeployC
       description: opts.description,
     });
   } finally {
+    // Same as preview: each stage tags its own reason, so no catch-all here — the try
+    // exists only so the lock is released on every exit path.
     info('releasing deploy lock');
     await releaseLockBestEffort(appName, token);
   }
@@ -331,20 +344,33 @@ async function handleDeployTags(appSlug: string): Promise<void> {
   }
 }
 
-// Acquire the per-app deploy lock. Throws a friendly error on 409 (someone else is deploying)
-// so the deploy stops and the caller can retry; the backend TTL backstops a crashed holder.
-async function acquireDeployLock(appName: string, token: string): Promise<void> {
-  const res = await fetch(`${brokerBaseUrl()}/z2h-cli/lock/acquire`, {
+function postToLockEndpoint(path: string, appName: string, token: string): Promise<Response> {
+  return fetch(`${brokerBaseUrl()}${path}`, {
     method: 'POST',
     headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
     body: JSON.stringify({ appName }),
   });
+}
+
+// Acquire the per-app deploy lock. Throws a friendly error on 409 (someone else is deploying)
+// so the deploy stops and the caller can retry; the backend TTL backstops a crashed holder.
+async function acquireDeployLock(appName: string, token: string): Promise<void> {
+  let res: Response;
+  try {
+    res = await postToLockEndpoint('/z2h-cli/lock/acquire', appName, token);
+  } catch (err) {
+    throw tagDeployError('broker_error', err);
+  }
   if (res.status === 409) {
-    throw new Error(`Someone is deploying "${appName}" right now — try again in a moment.`);
+    throw new DeployError('lock_timeout', `Someone is deploying "${appName}" right now — try again in a moment.`);
   }
   if (!res.ok) {
+    // Only 409 is contention — don't report a broker outage or a stale token as lock contention.
     const text = await res.text();
-    throw new Error(`Failed to acquire deploy lock (${res.status}): ${text.slice(0, 512)}`);
+    const grantReason = grantReasonForStatus(res.status);
+    const reason: DeployFailureReason =
+      grantReason === 'auth' || grantReason === 'forbidden' ? 'broker_auth' : 'broker_error';
+    throw new DeployError(reason, `Failed to acquire deploy lock (${res.status}): ${text.slice(0, 512)}`);
   }
   info(`deploy lock acquired for ${appName}`);
 }
@@ -352,11 +378,7 @@ async function acquireDeployLock(appName: string, token: string): Promise<void>
 // best-effort — the 2-min TTL backstop handles failures
 async function releaseLockBestEffort(appName: string, token: string): Promise<void> {
   try {
-    const res = await fetch(`${brokerBaseUrl()}/z2h-cli/lock/release`, {
-      method: 'POST',
-      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
-      body: JSON.stringify({ appName }),
-    });
+    const res = await postToLockEndpoint('/z2h-cli/lock/release', appName, token);
     if (!res.ok) {
       warn(`failed to release lock for ${appName} (${res.status})`);
       return;

package/src/commands/grant.ts

@@ -2,6 +2,7 @@ import { output } from '../util/logger';
 import { getCwdAppName, mfAppName } from '../util/app-name';
 import { brokerBaseUrl, routingHeaders } from '../constants';
 import { readZthAuth } from '../util/auth/auth-store';
+import { GrantError } from '../util/errors';
 
 export interface GrantOptions {
   public?: boolean;
@@ -20,18 +21,18 @@ async function postGrant(
   });
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Grant failed (${res.status}): ${text.slice(0, 1024)}`);
+    throw new GrantError(res.status, `Grant failed (${res.status}): ${text.slice(0, 1024)}`);
   }
 }
 
 export async function grantCommand(email: string | undefined, opts: GrantOptions): Promise<void> {
   if (!opts.public && !email) {
-    throw new Error('Specify what to grant — e.g. --public or provide an email');
+    throw new GrantError('validation', 'Specify what to grant — e.g. --public or provide an email');
   }
 
   const level = opts.level ?? 'viewer';
   if (!['owner', 'editor', 'viewer'].includes(level)) {
-    throw new Error(`Invalid --level "${level}". Must be owner, editor, or viewer`);
+    throw new GrantError('validation', `Invalid --level "${level}". Must be owner, editor, or viewer`);
   }
 
   const appName = mfAppName(getCwdAppName()!);
@@ -56,7 +57,7 @@ export async function grantCommand(email: string | undefined, opts: GrantOptions
 
 export async function revokeCommand(email: string | undefined, opts: GrantOptions): Promise<void> {
   if (!opts.public && !email) {
-    throw new Error('Specify what to revoke — e.g. --public or provide an email');
+    throw new GrantError('validation', 'Specify what to revoke — e.g. --public or provide an email');
   }
 
   const appName = mfAppName(getCwdAppName()!);
@@ -69,7 +70,7 @@ export async function revokeCommand(email: string | undefined, opts: GrantOption
   });
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Revoke failed (${res.status}): ${text.slice(0, 1024)}`);
+    throw new GrantError(res.status, `Revoke failed (${res.status}): ${text.slice(0, 1024)}`);
   }
 
   const revoked = email ?? 'public';
@@ -81,7 +82,7 @@ export async function revokeCommand(email: string | undefined, opts: GrantOption
 
 export async function transferOwnerCommand(email: string | undefined): Promise<void> {
   if (!email) {
-    throw new Error('Specify the new owner — e.g. z2h-cli transfer-owner someone@monday.com');
+    throw new GrantError('validation', 'Specify the new owner — e.g. z2h-cli transfer-owner someone@monday.com');
   }
 
   const appName = mfAppName(getCwdAppName()!);
@@ -94,7 +95,7 @@ export async function transferOwnerCommand(email: string | undefined): Promise<v
   });
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Transfer owner failed (${res.status}): ${text.slice(0, 1024)}`);
+    throw new GrantError(res.status, `Transfer owner failed (${res.status}): ${text.slice(0, 1024)}`);
   }
 
   output(`[z2h-cli] "${appName}" ownership transferred to ${email}`, { ok: true, appName, newOwner: email });