@mondaydotcomorg/z2h-cli 0.25.4 → 0.25.7

package/src/index.ts

@@ -18,10 +18,11 @@ import { editCommand } from './commands/edit';
 import { backendInvokeCommand } from './commands/backend';
 import { doctorCommand } from './commands/doctor';
 import { errorLog, fail, getOutputMode, setOutputMode } from './util/logger';
-import { trackDuration } from './util/tracker';
+import { runCommand } from './util/run-command';
+import { successEvent } from './util/tracker';
 import { getCwdAppName } from './util/app-name';
 
-const { version } = createRequire(import.meta.url)('../package.json') as { version: string };
+const { version } = createRequire(import.meta.url)('@mondaydotcomorg/z2h-cli/package.json') as { version: string };
 
 const UPDATE_SCRIPT = path.join(os.homedir(), 'Development', 'bigbrain-z2h', 'z2h', 'setup', 'update.sh');
 
@@ -49,6 +50,24 @@ function collectTag(value: string, previous: string[]): string[] {
   return previous.concat(value);
 }
 
+const cwdApp = () => ({ app_name: getCwdAppName() });
+
+interface CreateCliOptions {
+  template?: string;
+  htmlFile?: string;
+  remote?: string;
+  repoUrl?: string;
+}
+
+interface DeployCliOptions {
+  dryRun?: boolean;
+  preview?: boolean | string;
+  open?: boolean;
+  remote?: string;
+  repoUrl?: string;
+  description?: string;
+}
+
 async function main(): Promise<void> {
   stripConflictingEnvVars();
 
@@ -80,24 +99,15 @@ async function main(): Promise<void> {
   program
     .command('build')
     .description('Build the consumer into its .zth/ shadow and copy artifacts to ./build/')
-    .action(async () => {
-      try {
-        await trackDuration('z2h_app_build_success', () => buildCommand(), { app_name: getCwdAppName() });
-      } catch (err) {
-        await fail(`build failed: ${(err as Error).message}`, { command: 'build' }, 2);
-      }
-    });
+    // A standalone build failure is the consumer's own code, not a CLI/infra problem — don't
+    // track it. buildCommand still tags the reason on its thrown error, since deploy's own
+    // (tracked) failure event benefits from knowing when a build broke it.
+    .action(runCommand({ track: false, data: cwdApp, exitCode: 2 }, () => buildCommand()));
 
   program
     .command('clean')
     .description('Delete <consumer>/.zth/ and <consumer>/build/')
-    .action(async () => {
-      try {
-        await cleanCommand();
-      } catch (err) {
-        await fail(`clean failed: ${(err as Error).message}`, { command: 'clean' }, 2);
-      }
-    });
+    .action(runCommand({ track: false, exitCode: 2 }, () => cleanCommand()));
 
   program
     .command('deploy')
@@ -110,7 +120,7 @@ async function main(): Promise<void> {
     .option('--open', 'open the resulting app/preview URL in the browser on success')
     .option(
       '--remote <type>',
-      'First deploy only: source control remote to initialise — s3 (shared storage) or github (your repo). Error if the app already has a git remote.'
+      'First deploy only: source control remote to initialise — s3 (shared storage, recommended, auto-backed-up) or github (manage it yourself in your own repo). Error if the app already has a git remote.'
     )
     .option(
       '--repo-url <url>',
@@ -118,53 +128,36 @@ async function main(): Promise<void> {
     )
     .option('--description <text>', 'short (<=200 char) description of the app')
     .action(
-      async (opts: {
-        dryRun?: boolean;
-        preview?: boolean | string;
-        open?: boolean;
-        remote?: string;
-        repoUrl?: string;
-        description?: string;
-      }) => {
-        try {
-          await trackDuration(
-            opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success',
-            () => deployCommand(opts as Parameters<typeof deployCommand>[0]),
-            {
-              app_name: getCwdAppName(),
-            }
-          );
-        } catch (err) {
-          const label = opts.preview ? 'preview' : 'deploy';
-          await fail(`${label} failed: ${(err as Error).message}`, { command: label }, 2);
-        }
-      }
+      runCommand(
+        {
+          // A preview is a real deploy for observability, tracked as its own event since
+          // the command name alone (`deploy`) can't distinguish it from a live deploy.
+          event: ([opts]: [DeployCliOptions]) => successEvent(opts.preview ? 'preview' : 'deploy'),
+          label: ([opts]: [DeployCliOptions]) => (opts.preview ? 'preview' : 'deploy'),
+          data: cwdApp,
+          exitCode: 2,
+        },
+        (opts: DeployCliOptions) => deployCommand(opts as Parameters<typeof deployCommand>[0])
+      )
     );
 
   program
     .command('tag [app-name]')
     .description("Set an app's category tags — app type & team (interactive unless --tag or --json is given)")
     .option('--tag <tag>', 'set a tag (repeatable); full-replaces the tag set non-interactively', collectTag, [])
-    .action(async (appName: string | undefined, opts: { tag?: string[] }) => {
-      try {
-        await trackDuration('z2h_app_tag_success', () => tagCommand(appName, opts), {
-          app_name: appName ?? getCwdAppName(),
-        });
-      } catch (err) {
-        await fail(`tag failed: ${(err as Error).message}`, { command: 'tag' }, 1);
-      }
-    });
+    .action(
+      runCommand(
+        {
+          data: ([appName]: [string | undefined, unknown]) => ({ app_name: appName ?? getCwdAppName() }),
+        },
+        (appName: string | undefined, opts: { tag?: string[] }) => tagCommand(appName, opts)
+      )
+    );
 
   program
     .command('create-workspace')
     .description(`Bootstrap the ${getWorkspaceHome()}/ yarn workspace (one-time setup)`)
-    .action(async () => {
-      try {
-        await createWorkspaceCommand();
-      } catch (err) {
-        await fail(`create-workspace failed: ${(err as Error).message}`, { command: 'create-workspace' }, 1);
-      }
-    });
+    .action(runCommand({ track: false }, () => createWorkspaceCommand()));
 
   program
     .command('generate-z2h-token')
@@ -173,97 +166,69 @@ async function main(): Promise<void> {
     )
     .option('--no-browser', "don't auto-open the browser; print the URL and prompt for manual paste")
     .option('--url <url>', 'Override the token page URL (e.g. for staging)')
-    .action(async (opts: { noBrowser?: boolean; url?: string }) => {
-      try {
-        await generateZ2HTokenCommand(opts);
-      } catch (err) {
-        await fail(`generate-z2h-token failed: ${(err as Error).message}`, { command: 'generate-z2h-token' }, 1);
-      }
-    });
+    .action(runCommand({}, (opts: { noBrowser?: boolean; url?: string }) => generateZ2HTokenCommand(opts)));
 
   program
     .command('create <app-name>')
     .description(`Scaffold a new Z2H consumer app inside ${getWorkspaceHome()}/`)
     .option('--template <name>', 'Template name (default | html-embed)')
     .option('--html-file <path>', 'Path to an HTML file to embed (implies --template html-embed)')
-    .option('--remote <type>', 'Source control remote: s3 (shared storage) or github (your repo)')
+    .option(
+      '--remote <type>',
+      'Source control remote: s3 (shared storage, recommended, auto-backed-up) or github (manage it yourself in your own repo)'
+    )
     .option('--repo-url <url>', 'GitHub repo URL — required when --remote=github')
     .action(
-      async (appName: string, opts: { template?: string; htmlFile?: string; remote?: string; repoUrl?: string }) => {
-        try {
-          await trackDuration('z2h_app_created', () => createCommand(appName, opts as CreateOptions), {
+      runCommand(
+        {
+          data: ([appName, opts]: [string, CreateCliOptions]) => ({
             app_name: appName,
             template: opts.template ?? 'default',
             remote: opts.remote ?? 'unknown',
-          });
-        } catch (err) {
-          await fail(`create failed: ${(err as Error).message}`, { command: 'create' }, 1);
-        }
-      }
+          }),
+        },
+        (appName: string, opts: CreateCliOptions) => createCommand(appName, opts as CreateOptions)
+      )
     );
 
   program
     .command('edit <app-name>')
     .description(`Pull the latest version of an app into ${getWorkspaceHome()}/<app-name>, cloning it first if needed`)
-    .action(async (appName: string) => {
-      try {
-        await trackDuration('z2h_app_edit_pulled', () => editCommand(appName), {
-          app_name: appName,
-        });
-      } catch (err) {
-        await fail(`edit failed: ${(err as Error).message}`, { command: 'edit' }, 1);
-      }
-    });
+    .action(
+      runCommand({ data: ([appName]: [string]) => ({ app_name: appName }) }, (appName: string) => editCommand(appName))
+    );
 
   program
     .command('grant [email]')
     .description('Grant access to the current app (email, --public, or both)')
     .option('--public', 'make the app visible to all monday.com employees')
     .option('--level <level>', 'access level for user grants: owner, editor, or viewer (default: viewer)')
-    .action(async (email: string | undefined, opts: { public?: boolean; level?: string }) => {
-      try {
-        await grantCommand(email, opts as Parameters<typeof grantCommand>[1]);
-      } catch (err) {
-        await fail(`grant failed: ${(err as Error).message}`, { command: 'grant' }, 1);
-      }
-    });
+    .action(
+      runCommand({}, (email: string | undefined, opts: { public?: boolean; level?: string }) =>
+        grantCommand(email, opts as Parameters<typeof grantCommand>[1])
+      )
+    );
 
   program
     .command('revoke [email]')
     .description('Revoke access to the current app (email or --public; owners/admins only)')
     .option('--public', 'remove the public grant, making the app visible to owners/admins only')
-    .action(async (email: string | undefined, opts: { public?: boolean }) => {
-      try {
-        await revokeCommand(email, opts as Parameters<typeof revokeCommand>[1]);
-      } catch (err) {
-        await fail(`revoke failed: ${(err as Error).message}`, { command: 'revoke' }, 1);
-      }
-    });
+    .action(
+      runCommand({}, (email: string | undefined, opts: { public?: boolean }) =>
+        revokeCommand(email, opts as Parameters<typeof revokeCommand>[1])
+      )
+    );
 
   program
     .command('transfer-owner [email]')
     .description('Transfer ownership of the current app to another monday.com user')
-    .action(async (email: string | undefined) => {
-      try {
-        await transferOwnerCommand(email);
-      } catch (err) {
-        await fail(`transfer-owner failed: ${(err as Error).message}`, { command: 'transfer-owner' }, 1);
-      }
-    });
+    .action(runCommand({}, (email: string | undefined) => transferOwnerCommand(email)));
 
   program
     .command('delete')
     .description('Permanently delete the current app and take it offline (owners/admins only)')
     .option('--yes', 'skip the confirmation prompt (required for --json / non-interactive)')
-    .action(async (opts: { yes?: boolean }) => {
-      try {
-        await trackDuration('z2h_app_delete_success', () => deleteCommand(opts), {
-          app_name: getCwdAppName(),
-        });
-      } catch (err) {
-        await fail(`delete failed: ${(err as Error).message}`, { command: 'delete' }, 1);
-      }
-    });
+    .action(runCommand({ data: cwdApp }, (opts: { yes?: boolean }) => deleteCommand(opts)));
 
   const backend = program
     .command('backend')
@@ -275,39 +240,25 @@ async function main(): Promise<void> {
       'Invoke a deployed backend handler by name (the filename without .ts) — mainly for testing a handler without going through the frontend'
     )
     .option('--input <json>', 'JSON payload passed as ctx.input')
-    .action(async (handlerName: string, opts: { input?: string }) => {
-      try {
-        await trackDuration('z2h_backend_invoke_success', () => backendInvokeCommand(handlerName, opts), {
-          app_name: getCwdAppName(),
-          handler: handlerName,
-        });
-      } catch (err) {
-        await fail(`backend invoke failed: ${(err as Error).message}`, { command: 'backend invoke' }, 1);
-      }
-    });
+    .action(
+      runCommand(
+        {
+          data: ([handlerName]: [string, unknown]) => ({ app_name: getCwdAppName(), handler: handlerName }),
+        },
+        (handlerName: string, opts: { input?: string }) => backendInvokeCommand(handlerName, opts)
+      )
+    );
 
   program
     .command('migrate')
     .description('Run pending workspace migrations')
     .option('--dry-run', 'show pending migrations without applying any changes')
-    .action(async (opts: { dryRun?: boolean }) => {
-      try {
-        await migrateCommand(version, opts);
-      } catch (err) {
-        await fail(`migrate failed: ${(err as Error).message}`, { command: 'migrate' }, 1);
-      }
-    });
+    .action(runCommand({}, (opts: { dryRun?: boolean }) => migrateCommand(version, opts)));
 
   program
     .command('doctor')
     .description('Check that all Z2H tools, auth, workspace, and plugins are correctly set up')
-    .action(async () => {
-      try {
-        await doctorCommand();
-      } catch (err) {
-        await fail(`doctor failed: ${(err as Error).message}`, { command: 'doctor' }, 1);
-      }
-    });
+    .action(runCommand({ track: false }, () => doctorCommand()));
 
   await program.parseAsync(process.argv);
 }

package/src/types.ts

@@ -62,3 +62,50 @@ export interface PreparedShadow {
   port: number;
   paths: ConsumerPaths;
 }
+
+// ─────────── deploy failure reason ───────────
+// Bounded reason codes tagged onto deploy failures — see DeployError in commands/deploy.ts.
+export type DeployFailureReason =
+  | 'read_auth_token'
+  | 'broker_auth'
+  | 'broker_error'
+  | 'lock_timeout'
+  | 'build_error'
+  | 'git_error'
+  | 's3_error'
+  | 'deploy_backend_error'
+  | 'register_error'
+  | 'push_error'
+  | 'interrupted'
+  | 'unknown';
+
+// ─────────── grant/revoke/transfer-owner failure reason ───────────
+// Bounded reason codes tagged onto the shared z2h_cli_error event for these
+// commands — see GrantError in commands/grant.ts.
+export type GrantFailureReason = 'validation' | 'auth' | 'forbidden' | 'not_found' | 'server_error' | 'unknown';
+
+// ─────────── command telemetry contract ───────────
+// runCommand in util/run-command.ts reads these. It wraps every CLI command.
+
+/**
+ * A spec value that is either a constant or a function of the command's own arguments.
+ * Callbacks take the args as one tuple rather than a spread, so a callback that reads only
+ * the first arg still typechecks. Destructure what you need.
+ */
+export type PerArgs<A extends unknown[], T> = T | ((args: A) => T);
+
+export interface CommandSpec<A extends unknown[]> {
+  /**
+   * Opt out of telemetry entirely — both the success event and the error event. Default `true`.
+   * Set `false` for a purely local command with no product-usage signal worth a round-trip.
+   */
+  track?: PerArgs<A, boolean>;
+  /** Success-event name when it depends on args (e.g. `deploy --preview`); defaults to `successEvent(<command>)`. */
+  event?: PerArgs<A, string>;
+  /** Prefix in the error message and the `action` dimension. Defaults to the command's own name. */
+  label?: PerArgs<A, string>;
+  /** Extra dimensions sent with both the success and the error event. */
+  data?: (args: A) => Record<string, unknown>;
+  /** Overrides the failing error's own exitCode. */
+  exitCode?: number;
+}

package/src/util/__tests__/errors.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  Z2hError,
+  DeployError,
+  GrantError,
+  Z2hAuthMissingError,
+  GitConflictError,
+  reasonOf,
+  dataOf,
+  messageOf,
+} from '../errors';
+import { fail, setOutputMode } from '../logger';
+import { trackEvent } from '../tracker';
+
+vi.mock('../tracker', () => ({ trackEvent: vi.fn().mockResolvedValue(undefined) }));
+
+describe('reasonOf: every classified error carries its own reason', () => {
+  it.each([
+    ['DeployError', new DeployError('build_error', 'boom'), 'build_error'],
+    ['GrantError', new GrantError('forbidden', 'nope'), 'forbidden'],
+    ['Z2hAuthMissingError', new Z2hAuthMissingError('/tmp/auth.json'), 'read_auth_token'],
+    ['GitConflictError', new GitConflictError('diverged'), 'git_error'],
+  ])('%s → %s', (_name, err, expected) => {
+    expect(reasonOf(err)).toBe(expected);
+  });
+
+  it('falls back to unknown for a plain Error and a non-Error throw', () => {
+    expect(reasonOf(new Error('plain'))).toBe('unknown');
+    expect(reasonOf('a string')).toBe('unknown');
+  });
+
+  it('keeps the subclass name so telemetry and stack traces stay readable', () => {
+    expect(new DeployError('s3_error', 'x').name).toBe('DeployError');
+    expect(new GitConflictError('x').name).toBe('GitConflictError');
+  });
+});
+
+describe('dataOf / messageOf', () => {
+  it('surfaces extra dimensions the throw site attached', () => {
+    expect(dataOf(new Z2hError('x', 'unknown', { stage: 'upload', attempt: 2 }))).toEqual({
+      stage: 'upload',
+      attempt: 2,
+    });
+  });
+
+  it('returns an empty object when the error carries no data', () => {
+    expect(dataOf(new DeployError('read_auth_token', 'x'))).toEqual({});
+    expect(dataOf('not an error')).toEqual({});
+  });
+
+  it('stringifies a non-Error throw instead of yielding undefined', () => {
+    expect(messageOf('boom')).toBe('boom');
+    expect(messageOf(null)).toBe('null');
+    expect(messageOf(new Error('real'))).toBe('real');
+  });
+});
+
+describe('fail: telemetry is opt-out for unobserved commands', () => {
+  afterEach(() => {
+    vi.mocked(trackEvent).mockClear();
+    setOutputMode('human');
+  });
+
+  // process.exit would tear down the test run, so trap it as a throw.
+  const runFail = async (track: boolean) => {
+    const exit = vi.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('__exit__');
+    });
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    await expect(fail('doctor failed: x', { command: 'doctor', reason: 'unknown' }, 1, track)).rejects.toThrow(
+      '__exit__'
+    );
+    exit.mockRestore();
+    vi.mocked(process.stderr.write).mockRestore();
+  };
+
+  it('emits z2h_cli_error when the command is observed', async () => {
+    await runFail(true);
+    expect(trackEvent).toHaveBeenCalledWith(
+      'z2h_cli_error',
+      expect.objectContaining({ action: 'doctor', reason: 'unknown' })
+    );
+  });
+
+  it('stays silent when the command has no success event', async () => {
+    await runFail(false);
+    expect(trackEvent).not.toHaveBeenCalled();
+  });
+});

package/src/util/__tests__/run-command.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Command } from 'commander';
+import { runCommand } from '../run-command';
+import { DeployError } from '../errors';
+import { setOutputMode } from '../logger';
+import { trackEvent, trackDuration } from '../tracker';
+
+vi.mock('../tracker', () => ({
+  trackEvent: vi.fn().mockResolvedValue(undefined),
+  trackDuration: vi.fn((_name: string, fn: () => Promise<unknown>) => fn()),
+  successEvent: (command: string) => `z2h_cli_${command.replace(/[\s-]+/g, '_')}_success`,
+}));
+
+describe('runCommand: build_error is never reported, other reasons still are', () => {
+  afterEach(() => {
+    vi.mocked(trackEvent).mockClear();
+    setOutputMode('human');
+  });
+
+  // process.exit would tear down the test run, so trap it as a throw.
+  const runFailing = async (err: unknown, cmd = new Command('deploy')) => {
+    const exit = vi.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('__exit__');
+    });
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const handler = runCommand({}, () => {
+      throw err;
+    });
+    await expect(handler(cmd)).rejects.toThrow('__exit__');
+    exit.mockRestore();
+    vi.mocked(process.stderr.write).mockRestore();
+  };
+
+  it('drops the error event entirely when the deploy failed because the build broke', async () => {
+    await runFailing(new DeployError('build_error', 'tsc exploded'));
+    expect(trackEvent).not.toHaveBeenCalled();
+  });
+
+  it('still reports a non-build failure reason', async () => {
+    await runFailing(new DeployError('s3_error', 'upload failed'));
+    expect(trackEvent).toHaveBeenCalledWith('z2h_cli_error', expect.objectContaining({ reason: 's3_error' }));
+  });
+});
+
+describe('runCommand: naming/tracking convention', () => {
+  afterEach(() => {
+    vi.mocked(trackEvent).mockClear();
+    vi.mocked(trackDuration).mockClear();
+    setOutputMode('human');
+  });
+
+  it('derives its name (and label) from the Command instance, no name param needed', async () => {
+    const cmd = new Command('migrate');
+    const handler = runCommand({}, () => Promise.resolve('ok'));
+    await handler(cmd);
+    expect(trackDuration).toHaveBeenCalledWith('z2h_cli_migrate_success', expect.any(Function), {});
+  });
+
+  it('composes a nested command\'s name from its parent, e.g. "backend invoke"', async () => {
+    const backend = new Command('backend');
+    const invoke = backend.command('invoke');
+    const handler = runCommand({}, () => Promise.resolve('ok'));
+    await handler(invoke);
+    expect(trackDuration).toHaveBeenCalledWith('z2h_cli_backend_invoke_success', expect.any(Function), {});
+  });
+
+  it('track: false skips telemetry entirely, success or failure', async () => {
+    const cmd = new Command('doctor');
+    await runCommand({ track: false }, () => Promise.resolve('ok'))(cmd);
+    expect(trackDuration).not.toHaveBeenCalled();
+    expect(trackEvent).not.toHaveBeenCalled();
+
+    const exit = vi.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('__exit__');
+    });
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const failing = runCommand({ track: false }, () => {
+      throw new Error('boom');
+    });
+    await expect(failing(cmd)).rejects.toThrow('__exit__');
+    expect(trackEvent).not.toHaveBeenCalled();
+    exit.mockRestore();
+    vi.mocked(process.stderr.write).mockRestore();
+  });
+
+  it('a per-args event override beats the derived name, e.g. deploy --preview', async () => {
+    const cmd = new Command('deploy');
+    const handler = runCommand(
+      {
+        event: ([opts]: [{ preview?: boolean }]) =>
+          opts.preview ? 'z2h_cli_preview_success' : 'z2h_cli_deploy_success',
+      },
+      (_opts: { preview?: boolean }) => Promise.resolve('ok')
+    );
+    await handler({ preview: true }, cmd);
+    expect(trackDuration).toHaveBeenCalledWith('z2h_cli_preview_success', expect.any(Function), {});
+  });
+});

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

@@ -2,6 +2,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { ensureDir, remove, writeJson } from 'fs-extra';
+import { Z2hAuthMissingError } from '../../errors';
 
 let scratchHome: string;
 let originalHome: string | undefined;
@@ -29,7 +30,7 @@ afterEach(async () => {
 
 describe('readZthAuth', () => {
   it('throws Z2hAuthMissingError with a remediation hint when the file is absent', async () => {
-    const { readZthAuth, Z2hAuthMissingError } = await reload();
+    const { readZthAuth } = await reload();
     await expect(readZthAuth()).rejects.toBeInstanceOf(Z2hAuthMissingError);
   });