@mondaydotcomorg/z2h-cli 0.25.3 → 0.25.7

package/dist/esm/index.mjs

@@ -18,10 +18,11 @@ import { editCommand } from './commands/edit.mjs';
 import { backendInvokeCommand } from './commands/backend.mjs';
 import { doctorCommand } from './commands/doctor.mjs';
 import { fail, errorLog, setOutputMode, getOutputMode } from './util/logger.mjs';
-import { trackDuration } from './util/tracker.mjs';
+import { runCommand } from './util/run-command.mjs';
+import { successEvent } from './util/tracker.mjs';
 import { getCwdAppName } from './util/app-name.mjs';
 
-const { version } = createRequire(import.meta.url)('../package.json');
+const { version } = createRequire(import.meta.url)('@mondaydotcomorg/z2h-cli/package.json');
 const UPDATE_SCRIPT = path.join(os.homedir(), 'Development', 'bigbrain-z2h', 'z2h', 'setup', 'update.sh');
 function selfUpdate() {
     try {
@@ -44,6 +45,7 @@ function stripConflictingEnvVars() {
 function collectTag(value, previous) {
     return previous.concat(value);
 }
+const cwdApp = () => ({ app_name: getCwdAppName() });
 async function main() {
     stripConflictingEnvVars();
     const program = new Command();
@@ -71,165 +73,86 @@ async function main() {
     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.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.message}`, { command: 'clean' }, 2);
-        }
-    });
+        .action(runCommand({ track: false, exitCode: 2 }, () => cleanCommand()));
     program
         .command('deploy')
         .description('Build, upload to S3, and register the app with the Z2H backend')
         .option('--dry-run', 'print what would happen without uploading anything')
         .option('--preview', 'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; reuses the same preview URL across runs (stable link)')
         .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.')
+        .option('--remote <type>', '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>', 'First deploy only: GitHub repo URL — required when --remote=github. Error if the app already has a git remote.')
         .option('--description <text>', 'short (<=200 char) description of the app')
-        .action(async (opts) => {
-        try {
-            await trackDuration(opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success', () => deployCommand(opts), {
-                app_name: getCwdAppName(),
-            });
-        }
-        catch (err) {
-            const label = opts.preview ? 'preview' : 'deploy';
-            await fail(`${label} failed: ${err.message}`, { command: label }, 2);
-        }
-    });
+        .action(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]) => successEvent(opts.preview ? 'preview' : 'deploy'),
+        label: ([opts]) => (opts.preview ? 'preview' : 'deploy'),
+        data: cwdApp,
+        exitCode: 2,
+    }, (opts) => deployCommand(opts)));
     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, opts) => {
-        try {
-            await trackDuration('z2h_app_tag_success', () => tagCommand(appName, opts), {
-                app_name: appName ?? getCwdAppName(),
-            });
-        }
-        catch (err) {
-            await fail(`tag failed: ${err.message}`, { command: 'tag' }, 1);
-        }
-    });
+        .action(runCommand({
+        data: ([appName]) => ({ app_name: appName ?? getCwdAppName() }),
+    }, (appName, opts) => 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.message}`, { command: 'create-workspace' }, 1);
-        }
-    });
+        .action(runCommand({ track: false }, () => createWorkspaceCommand()));
     program
         .command('generate-z2h-token')
         .description('Open the bigbrain.me token page, capture the token via a loopback callback, and persist it to ~/.zth/auth.json')
         .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) => {
-        try {
-            await generateZ2HTokenCommand(opts);
-        }
-        catch (err) {
-            await fail(`generate-z2h-token failed: ${err.message}`, { command: 'generate-z2h-token' }, 1);
-        }
-    });
+        .action(runCommand({}, (opts) => 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, opts) => {
-        try {
-            await trackDuration('z2h_app_created', () => createCommand(appName, opts), {
-                app_name: appName,
-                template: opts.template ?? 'default',
-                remote: opts.remote ?? 'unknown',
-            });
-        }
-        catch (err) {
-            await fail(`create failed: ${err.message}`, { command: 'create' }, 1);
-        }
-    });
+        .action(runCommand({
+        data: ([appName, opts]) => ({
+            app_name: appName,
+            template: opts.template ?? 'default',
+            remote: opts.remote ?? 'unknown',
+        }),
+    }, (appName, opts) => createCommand(appName, opts)));
     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) => {
-        try {
-            await trackDuration('z2h_app_edit_pulled', () => editCommand(appName), {
-                app_name: appName,
-            });
-        }
-        catch (err) {
-            await fail(`edit failed: ${err.message}`, { command: 'edit' }, 1);
-        }
-    });
+        .action(runCommand({ data: ([appName]) => ({ app_name: appName }) }, (appName) => 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, opts) => {
-        try {
-            await grantCommand(email, opts);
-        }
-        catch (err) {
-            await fail(`grant failed: ${err.message}`, { command: 'grant' }, 1);
-        }
-    });
+        .action(runCommand({}, (email, opts) => grantCommand(email, opts)));
     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, opts) => {
-        try {
-            await revokeCommand(email, opts);
-        }
-        catch (err) {
-            await fail(`revoke failed: ${err.message}`, { command: 'revoke' }, 1);
-        }
-    });
+        .action(runCommand({}, (email, opts) => revokeCommand(email, opts)));
     program
         .command('transfer-owner [email]')
         .description('Transfer ownership of the current app to another monday.com user')
-        .action(async (email) => {
-        try {
-            await transferOwnerCommand(email);
-        }
-        catch (err) {
-            await fail(`transfer-owner failed: ${err.message}`, { command: 'transfer-owner' }, 1);
-        }
-    });
+        .action(runCommand({}, (email) => 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) => {
-        try {
-            await trackDuration('z2h_app_delete_success', () => deleteCommand(opts), {
-                app_name: getCwdAppName(),
-            });
-        }
-        catch (err) {
-            await fail(`delete failed: ${err.message}`, { command: 'delete' }, 1);
-        }
-    });
+        .action(runCommand({ data: cwdApp }, (opts) => deleteCommand(opts)));
     const backend = program
         .command('backend')
         .description("Inspect the app's backend: invoke a deployed handler by name");
@@ -237,40 +160,18 @@ async function main() {
         .command('invoke <handlerName>')
         .description('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, opts) => {
-        try {
-            await trackDuration('z2h_backend_invoke_success', () => backendInvokeCommand(handlerName, opts), {
-                app_name: getCwdAppName(),
-                handler: handlerName,
-            });
-        }
-        catch (err) {
-            await fail(`backend invoke failed: ${err.message}`, { command: 'backend invoke' }, 1);
-        }
-    });
+        .action(runCommand({
+        data: ([handlerName]) => ({ app_name: getCwdAppName(), handler: handlerName }),
+    }, (handlerName, opts) => backendInvokeCommand(handlerName, opts)));
     program
         .command('migrate')
         .description('Run pending workspace migrations')
         .option('--dry-run', 'show pending migrations without applying any changes')
-        .action(async (opts) => {
-        try {
-            await migrateCommand(version, opts);
-        }
-        catch (err) {
-            await fail(`migrate failed: ${err.message}`, { command: 'migrate' }, 1);
-        }
-    });
+        .action(runCommand({}, (opts) => 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.message}`, { command: 'doctor' }, 1);
-        }
-    });
+        .action(runCommand({ track: false }, () => doctorCommand()));
     await program.parseAsync(process.argv);
 }
 void main()

package/dist/esm/types.d.ts

@@ -50,4 +50,27 @@ export interface PreparedShadow {
     port: number;
     paths: ConsumerPaths;
 }
+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';
+export type GrantFailureReason = 'validation' | 'auth' | 'forbidden' | 'not_found' | 'server_error' | 'unknown';
+/**
+ * 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;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/esm/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAOD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAGD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAGD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/util/__tests__/errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.test.d.ts.map

package/dist/esm/util/__tests__/errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.d.ts","sourceRoot":"","sources":["../../../../src/util/__tests__/errors.test.ts"],"names":[],"mappings":""}

package/dist/esm/util/__tests__/run-command.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run-command.test.d.ts.map

package/dist/esm/util/__tests__/run-command.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-command.test.d.ts","sourceRoot":"","sources":["../../../../src/util/__tests__/run-command.test.ts"],"names":[],"mappings":""}

package/dist/esm/util/auth/auth-store.d.ts

@@ -3,10 +3,6 @@ export declare const Z2H_AUTH_FILE: string;
 export interface ZthAuth {
     token: string;
 }
-export declare class Z2hAuthMissingError extends Error {
-    readonly authFilePath: string;
-    constructor(authFilePath: string);
-}
 export declare function readZthAuth(): Promise<ZthAuth>;
 /**
  * Synchronous, never-throws read of the z2h JWT from `~/.zth/auth.json`.

package/dist/esm/util/auth/auth-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/auth-store.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,YAAY,QAAkC,CAAC;AAC5D,eAAO,MAAM,aAAa,QAAuC,CAAC;AAElE,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,YAAY,EAAE,MAAM;gBAApB,YAAY,EAAE,MAAM;CAIjD;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAkBpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,IAAI,CAUpD"}
+{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/auth-store.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,YAAY,QAAkC,CAAC;AAC5D,eAAO,MAAM,aAAa,QAAuC,CAAC;AAElE,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAkBpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,IAAI,CAUpD"}

package/dist/esm/util/auth/auth-store.mjs

@@ -1,20 +1,13 @@
 import path from 'node:path';
 import os from 'node:os';
 import { pathExists, readJson, readJsonSync } from 'fs-extra';
+import { Z2hAuthMissingError } from '../errors.mjs';
 
 // 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
 // stage it.
 const Z2H_AUTH_DIR = path.join(os.homedir(), '.zth');
 const Z2H_AUTH_FILE = path.join(Z2H_AUTH_DIR, 'auth.json');
-class Z2hAuthMissingError extends Error {
-    authFilePath;
-    constructor(authFilePath) {
-        super(`No Z2H deploy token found at ${authFilePath}. Please run 'z2h-cli generate-z2h-token' command.`);
-        this.authFilePath = authFilePath;
-        this.name = 'Z2hAuthMissingError';
-    }
-}
 async function readZthAuth() {
     if (process.env.Z2H_AUTH_TOKEN) {
         const token = process.env.Z2H_AUTH_TOKEN;
@@ -54,4 +47,4 @@ function tryReadAuthTokenSync() {
     }
 }
 
-export { Z2H_AUTH_DIR, Z2H_AUTH_FILE, Z2hAuthMissingError, readZthAuth, tryReadAuthTokenSync };
+export { Z2H_AUTH_DIR, Z2H_AUTH_FILE, readZthAuth, tryReadAuthTokenSync };

package/dist/esm/util/auth/broker-credential-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker-credential-provider.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/broker-credential-provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAyB,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAE3F,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAC1D,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAiD3D;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUzE;AA4DD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,OAAO,EACP,SAAS,GACV,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,6BAA6B,CAIhC"}
+{"version":3,"file":"broker-credential-provider.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/broker-credential-provider.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAyB,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAE3F,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAC1D,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AA0D3D;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAMzE;AAwDD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,OAAO,EACP,SAAS,GACV,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,6BAA6B,CAIhC"}

package/dist/esm/util/auth/broker-credential-provider.mjs

@@ -1,4 +1,5 @@
 import { brokerBaseUrl, routingHeaders } from '../../constants.mjs';
+import { DeployError, messageOf } from '../errors.mjs';
 import { readZthAuth } from './auth-store.mjs';
 
 const STS_BROKER_PATH = '/z2h-cli/sts/credentials';
@@ -21,16 +22,23 @@ async function postToBroker(path, 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) {
+/**
+ * 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, errorLabel) {
     if (res.status === 401) {
-        throw new Error(`Z2H deploy token rejected by the broker (401). Refresh user token by running 'z2h-cli generate-z2h-token'.`);
+        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(`Access denied (403). You do not have editor access to this app. Ask the app owner to grant you access via 'z2h-cli grant'.`);
+        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)}`);
     }
 }
 /**
@@ -40,27 +48,19 @@ function assertBrokerOk(res) {
  */
 async function fetchDeployVersion(appName) {
     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());
     return body.version ?? 0;
 }
 async function requestSts(path, body, errorLabel) {
     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());
     if (!responseBody.accessKeyId ||
         !responseBody.secretAccessKey ||
         !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 {
         accessKeyId: responseBody.accessKeyId,

package/dist/esm/util/broker/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/util/broker/app.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AA4CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWtF"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/util/broker/app.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBvE;AA4CD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}

package/dist/esm/util/broker/app.mjs

@@ -2,6 +2,7 @@ import { brokerBaseUrl, routingHeaders } from '../../constants.mjs';
 import { readZthAuth } from '../auth/auth-store.mjs';
 import { info } from '../logger.mjs';
 import { resolveAppVisibility } from '../prompt-visibility.mjs';
+import { tagDeployError, DeployError } from '../errors.mjs';
 
 /**
  * Fetches a single app's current state from the broker.
@@ -36,7 +37,7 @@ async function registerApp(appName, token, version, entry, visibility, gitRemote
     });
     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)}`);
     }
 }
 /** Releases a new version onto an app that already exists. */
@@ -48,7 +49,7 @@ async function updateApp(appName, token, version, entry, gitRemote, integrations
     });
     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)}`);
     }
 }
 /**
@@ -59,14 +60,21 @@ async function updateApp(appName, token, version, entry, gitRemote, integrations
  */
 async function registerOrUpdateApp(opts) {
     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);
+    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);
+        }
     }
-    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/dist/esm/util/errors.d.ts

@@ -0,0 +1,48 @@
+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 declare class Z2hError extends Error {
+    readonly reason: string;
+    readonly data?: Record<string, unknown> | undefined;
+    readonly exitCode: number;
+    constructor(message: string, reason: string, data?: Record<string, unknown> | undefined, exitCode?: number);
+}
+/** Tags a deploy/preview stage failure with a bounded reason code instead of a freeform message. */
+export declare class DeployError extends Z2hError {
+    readonly reason: DeployFailureReason;
+    constructor(reason: DeployFailureReason, message: string, data?: Record<string, unknown>);
+}
+/**
+ * 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 declare class GrantError extends Z2hError {
+    constructor(reason: GrantFailureReason | number, message: string, data?: Record<string, unknown>);
+}
+/** No z2h JWT found — see auth-store.ts for the discovery order (env var, then ~/.zth/auth.json). */
+export declare class Z2hAuthMissingError extends Z2hError {
+    readonly authFilePath: string;
+    constructor(authFilePath: string);
+}
+/** A git pull diverged or a push was rejected; `reason` distinguishes which stage hit it. */
+export declare class GitConflictError extends Z2hError {
+    constructor(message: string, reason?: DeployFailureReason);
+}
+/** Maps an HTTP status to a bounded grant/revoke/transfer-owner failure reason. */
+export declare function grantReasonForStatus(status: number): GrantFailureReason;
+/** Tags a failure with `reason`, unless `err` is already classified; `signal` overrides `reason` for a killed child process. */
+export declare function tagDeployError(reason: DeployFailureReason, err: unknown): Z2hError;
+/** Reads the bounded reason off a classified error; anything unclassified is `unknown`. */
+export declare function reasonOf(err: unknown): string;
+/** Extra telemetry dimensions the throw site attached, if any. */
+export declare function dataOf(err: unknown): Record<string, unknown>;
+/** Safe message for any thrown value. A non-Error throw must not break the error path. */
+export declare function messageOf(err: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/util/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/util/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAExE;;;;;;;;GAQG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAG/B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM;gBAHzB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA,EAC9B,QAAQ,GAAE,MAAU;CAKhC;AAED,oGAAoG;AACpG,qBAAa,WAAY,SAAQ,QAAQ;aACT,MAAM,EAAE,mBAAmB;gBAA3B,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG3G;AAED;;;GAGG;AACH,qBAAa,UAAW,SAAQ,QAAQ;gBAC1B,MAAM,EAAE,kBAAkB,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGjG;AAED,qGAAqG;AACrG,qBAAa,mBAAoB,SAAQ,QAAQ;aACnB,YAAY,EAAE,MAAM;gBAApB,YAAY,EAAE,MAAM;CAMjD;AAED,6FAA6F;AAC7F,qBAAa,gBAAiB,SAAQ,QAAQ;gBAChC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,mBAAiC;CAGvE;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAevE;AAED,gIAAgI;AAChI,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB,EAAE,GAAG,EAAE,OAAO,GAAG,QAAQ,CAMlF;AAED,2FAA2F;AAC3F,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAE7C;AAED,kEAAkE;AAClE,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE5D;AAED,0FAA0F;AAC1F,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAE9C"}