@mondaydotcomorg/z2h-cli 0.25.4 → 0.25.8

package/dist/auth.d.ts

@@ -1,3 +1,4 @@
 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';
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,KAAK,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACtG,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,KAAK,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACtG,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAClF,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}

package/dist/auth.js

@@ -2,10 +2,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const commands_generateZ2hToken = require('./commands/generate-z2h-token.js');
 const util_auth_authStore = require('./util/auth/auth-store.js');
+const util_errors = require('./util/errors.js');
 
 
 
 exports.generateZ2HTokenCommand = commands_generateZ2hToken.generateZ2HTokenCommand;
 exports.Z2H_AUTH_FILE = util_auth_authStore.Z2H_AUTH_FILE;
-exports.Z2hAuthMissingError = util_auth_authStore.Z2hAuthMissingError;
 exports.readZthAuth = util_auth_authStore.readZthAuth;
+exports.Z2hAuthMissingError = util_errors.Z2hAuthMissingError;

package/dist/commands/__tests__/build.test.d.ts

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

package/dist/commands/__tests__/build.test.d.ts.map

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

package/dist/commands/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/commands/backend.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAmCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAKpB;AAED,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5G"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/commands/backend.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAmCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASpB;AAED,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5G"}

package/dist/commands/backend.js

@@ -10,6 +10,7 @@ const backend_detectIntegrations = require('../backend/detect-integrations.js');
 const util_s3_client = require('../util/s3/client.js');
 const constants = require('../constants.js');
 const backend_client = require('../backend/client.js');
+const util_errors = require('../util/errors.js');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
@@ -75,7 +76,12 @@ 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 util_errors.tagDeployError('deploy_backend_error', err);
+    }
 }
 async function backendInvokeCommand(handlerName, opts = {}) {
     const appName = currentAppName();

package/dist/commands/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,iBAAiB,CAAC;CAClC;AAGD,wBAAsB,YAAY,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAyChF"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,iBAAiB,CAAC;CAClC;AAGD,wBAAsB,YAAY,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAOhF"}

package/dist/commands/build.js

@@ -5,6 +5,7 @@ const fs = require('fs-extra');
 const execa = require('execa');
 const util_logger = require('../util/logger.js');
 const shadow_prepare = require('../shadow/prepare.js');
+const util_errors = require('../util/errors.js');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
@@ -12,6 +13,15 @@ const path__default = /*#__PURE__*/_interopDefault(path);
 
 // Should be run from the consumer app directory — uses process.cwd() to locate it.
 async function buildCommand(opts = {}) {
+    try {
+        return await runBuild(opts);
+    }
+    catch (err) {
+        const signal = err instanceof Error ? err.signal : undefined;
+        throw new util_errors.DeployError(signal ? 'interrupted' : 'build_error', util_errors.messageOf(err));
+    }
+}
+async function runBuild(opts) {
     const ctx = await shadow_prepare.prepareShadow();
     // Typecheck against the shadow's tsconfig (the consumer dir has none).
     // Errors fail the build before we waste time on the Trident pipeline.

package/dist/commands/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAiBtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAkBtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3E"}

package/dist/commands/deploy.js

@@ -18,6 +18,7 @@ const util_machineIdentity = require('../util/machine-identity.js');
 const util_broker_app = require('../util/broker/app.js');
 const util_openBrowser = require('../util/open-browser.js');
 const shadow_prepare = require('../shadow/prepare.js');
+const util_errors = require('../util/errors.js');
 const commands_backend = require('./backend.js');
 const commands_build = require('./build.js');
 const commands_tag = require('./tag.js');
@@ -41,7 +42,13 @@ async function deployCommand(opts = {}) {
     const appName = util_appName.mfAppName(consumerPkg.name);
     // 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 util_auth_authStore.readZthAuth();
+    let token;
+    try {
+        ({ token } = await util_auth_authStore.readZthAuth());
+    }
+    catch (err) {
+        throw util_errors.tagDeployError('read_auth_token', err);
+    }
     const ctx = { paths, consumerName: consumerPkg.name, appName, token, opts };
     if (opts.preview) {
         await deployPreview(ctx);
@@ -98,6 +105,8 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
     // Full CDN URL, not a relative path — trident-skeleton uses a manifest
     // entry's `url` verbatim as the asset base, never joined with its own mfUrl.
     const url = `${constants.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 util_auth_brokerCredentialProvider.fetchDeployVersion(previewAppName)) + 1;
     util_logger.info('building');
     const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote: '' });
@@ -140,10 +149,10 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
     else {
         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).`);
         }
         util_git_remoteOptions.validateRemoteOptions(opts);
         // Pass the raw consumer name (not the mf-prefixed appName) so defaultS3Remote
@@ -160,9 +169,14 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
     // The skill commits the working tree (with an LLM-authored message) before
     // invoking deploy, so the tree should be clean here.
     if (gitRemote) {
-        await util_git_repo.guardCleanTree(process.cwd());
-        util_logger.info('syncing with git remote');
-        await util_git_repo.pullAndResolve(process.cwd(), gitEnv);
+        try {
+            await util_git_repo.guardCleanTree(process.cwd());
+            util_logger.info('syncing with git remote');
+            await util_git_repo.pullAndResolve(process.cwd(), gitEnv);
+        }
+        catch (err) {
+            throw util_errors.tagDeployError('git_error', err);
+        }
     }
     util_logger.info('reading current Z2H manifest');
     const keyPrefix = `${appName}/${nextVersion}`;
@@ -182,7 +196,6 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
         });
         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.
@@ -211,6 +224,8 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
         });
     }
     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.
         util_logger.info('releasing deploy lock');
         await releaseLockBestEffort(appName, token);
     }
@@ -256,31 +271,39 @@ async function handleDeployTags(appSlug) {
         util_logger.warn(`could not update tags: ${err.message}`);
     }
 }
-// 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, token) {
-    const res = await fetch(`${constants.brokerBaseUrl()}/z2h-cli/lock/acquire`, {
+function postToLockEndpoint(path, appName, token) {
+    return fetch(`${constants.brokerBaseUrl()}${path}`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...constants.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, token) {
+    let res;
+    try {
+        res = await postToLockEndpoint('/z2h-cli/lock/acquire', appName, token);
+    }
+    catch (err) {
+        throw util_errors.tagDeployError('broker_error', err);
+    }
     if (res.status === 409) {
-        throw new Error(`Someone is deploying "${appName}" right now — try again in a moment.`);
+        throw new util_errors.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 = util_errors.grantReasonForStatus(res.status);
+        const reason = grantReason === 'auth' || grantReason === 'forbidden' ? 'broker_auth' : 'broker_error';
+        throw new util_errors.DeployError(reason, `Failed to acquire deploy lock (${res.status}): ${text.slice(0, 512)}`);
     }
     util_logger.info(`deploy lock acquired for ${appName}`);
 }
 // best-effort — the 2-min TTL backstop handles failures
 async function releaseLockBestEffort(appName, token) {
     try {
-        const res = await fetch(`${constants.brokerBaseUrl()}/z2h-cli/lock/release`, {
-            method: 'POST',
-            headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...constants.routingHeaders() },
-            body: JSON.stringify({ appName }),
-        });
+        const res = await postToLockEndpoint('/z2h-cli/lock/release', appName, token);
         if (!res.ok) {
             util_logger.warn(`failed to release lock for ${appName} (${res.status})`);
             return;

package/dist/commands/grant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grant.d.ts","sourceRoot":"","sources":["../../src/commands/grant.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACvC;AAkBD,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B/F;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhG;AAED,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBnF"}
+{"version":3,"file":"grant.d.ts","sourceRoot":"","sources":["../../src/commands/grant.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACvC;AAkBD,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B/F;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhG;AAED,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBnF"}

package/dist/commands/grant.js

@@ -4,6 +4,7 @@ const util_logger = require('../util/logger.js');
 const util_appName = require('../util/app-name.js');
 const constants = require('../constants.js');
 const util_auth_authStore = require('../util/auth/auth-store.js');
+const util_errors = require('../util/errors.js');
 
 async function postGrant(appName, token, body) {
     const res = await fetch(`${constants.brokerBaseUrl()}/z2h-apps/${appName}/grants`, {
@@ -13,16 +14,16 @@ async function postGrant(appName, token, body) {
     });
     if (!res.ok) {
         const text = await res.text();
-        throw new Error(`Grant failed (${res.status}): ${text.slice(0, 1024)}`);
+        throw new util_errors.GrantError(res.status, `Grant failed (${res.status}): ${text.slice(0, 1024)}`);
     }
 }
 async function grantCommand(email, opts) {
     if (!opts.public && !email) {
-        throw new Error('Specify what to grant — e.g. --public or provide an email');
+        throw new util_errors.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 util_errors.GrantError('validation', `Invalid --level "${level}". Must be owner, editor, or viewer`);
     }
     const appName = util_appName.mfAppName(util_appName.getCwdAppName());
     const { token } = await util_auth_authStore.readZthAuth();
@@ -43,7 +44,7 @@ async function grantCommand(email, opts) {
 }
 async function revokeCommand(email, opts) {
     if (!opts.public && !email) {
-        throw new Error('Specify what to revoke — e.g. --public or provide an email');
+        throw new util_errors.GrantError('validation', 'Specify what to revoke — e.g. --public or provide an email');
     }
     const appName = util_appName.mfAppName(util_appName.getCwdAppName());
     const { token } = await util_auth_authStore.readZthAuth();
@@ -54,7 +55,7 @@ async function revokeCommand(email, opts) {
     });
     if (!res.ok) {
         const text = await res.text();
-        throw new Error(`Revoke failed (${res.status}): ${text.slice(0, 1024)}`);
+        throw new util_errors.GrantError(res.status, `Revoke failed (${res.status}): ${text.slice(0, 1024)}`);
     }
     const revoked = email ?? 'public';
     const msg = email
@@ -64,7 +65,7 @@ async function revokeCommand(email, opts) {
 }
 async function transferOwnerCommand(email) {
     if (!email) {
-        throw new Error('Specify the new owner — e.g. z2h-cli transfer-owner someone@monday.com');
+        throw new util_errors.GrantError('validation', 'Specify the new owner — e.g. z2h-cli transfer-owner someone@monday.com');
     }
     const appName = util_appName.mfAppName(util_appName.getCwdAppName());
     const { token } = await util_auth_authStore.readZthAuth();
@@ -75,7 +76,7 @@ async function transferOwnerCommand(email) {
     });
     if (!res.ok) {
         const text = await res.text();
-        throw new Error(`Transfer owner failed (${res.status}): ${text.slice(0, 1024)}`);
+        throw new util_errors.GrantError(res.status, `Transfer owner failed (${res.status}): ${text.slice(0, 1024)}`);
     }
     util_logger.output(`[z2h-cli] "${appName}" ownership transferred to ${email}`, { ok: true, appName, newOwner: email });
 }

package/dist/esm/auth.d.ts

@@ -1,3 +1,4 @@
 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';
 //# sourceMappingURL=auth.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,KAAK,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACtG,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,KAAK,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACtG,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAClF,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}

package/dist/esm/auth.mjs

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

package/dist/esm/commands/__tests__/build.test.d.ts

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

package/dist/esm/commands/__tests__/build.test.d.ts.map

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

package/dist/esm/commands/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/commands/backend.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAmCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAKpB;AAED,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5G"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/commands/backend.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAmCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASpB;AAED,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5G"}

package/dist/esm/commands/backend.mjs

@@ -8,6 +8,7 @@ import { detectIntegrationsFromHandlers } from '../backend/detect-integrations.m
 import { getS3Client } from '../util/s3/client.mjs';
 import { BUCKET_WRITE_NAME } from '../constants.mjs';
 import { invokeBackend } from '../backend/client.mjs';
+import { tagDeployError } from '../util/errors.mjs';
 
 function currentAppName() {
     const raw = getCwdAppName();
@@ -69,7 +70,12 @@ 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);
+    }
 }
 async function backendInvokeCommand(handlerName, opts = {}) {
     const appName = currentAppName();

package/dist/esm/commands/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/commands/build.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,iBAAiB,CAAC;CAClC;AAGD,wBAAsB,YAAY,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAyChF"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/commands/build.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,iBAAiB,CAAC;CAClC;AAGD,wBAAsB,YAAY,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAOhF"}

package/dist/esm/commands/build.mjs

@@ -3,9 +3,19 @@ import { pathExists, readJson } from 'fs-extra';
 import { execa } from 'execa';
 import { info, output } from '../util/logger.mjs';
 import { prepareShadow } from '../shadow/prepare.mjs';
+import { DeployError, messageOf } from '../util/errors.mjs';
 
 // Should be run from the consumer app directory — uses process.cwd() to locate it.
 async function buildCommand(opts = {}) {
+    try {
+        return await runBuild(opts);
+    }
+    catch (err) {
+        const signal = err instanceof Error ? err.signal : undefined;
+        throw new DeployError(signal ? 'interrupted' : 'build_error', messageOf(err));
+    }
+}
+async function runBuild(opts) {
     const ctx = await prepareShadow();
     // Typecheck against the shadow's tsconfig (the consumer dir has none).
     // Errors fail the build before we waste time on the Trident pipeline.

package/dist/esm/commands/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAiBtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAkBtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3E"}

package/dist/esm/commands/deploy.mjs

@@ -4,7 +4,7 @@ import { info, output, getOutputMode, warn } from '../util/logger.mjs';
 import { resolveConsumerPaths } from '../shadow/paths.mjs';
 import { fetchAppTags, fetchTagCatalog, setAppTags } from '../util/tags.mjs';
 import { uploadDir } from '../util/s3/upload.mjs';
-import { BUCKET_WRITE_NAME, brokerBaseUrl, routingHeaders, S3_PREVIEWS_FOLDER, BUCKET_READ_DNS_URL } from '../constants.mjs';
+import { BUCKET_WRITE_NAME, S3_PREVIEWS_FOLDER, BUCKET_READ_DNS_URL, brokerBaseUrl, routingHeaders } from '../constants.mjs';
 import { fetchDeployVersion, brokerCredentialProvider } from '../util/auth/broker-credential-provider.mjs';
 import { readZthAuth } from '../util/auth/auth-store.mjs';
 import { validateAppName, cleanAppName, mfAppName, buildPreviewSlug } from '../util/app-name.mjs';
@@ -16,6 +16,7 @@ import { getMachineAppName } from '../util/machine-identity.mjs';
 import { registerOrUpdateApp } from '../util/broker/app.mjs';
 import { openInBrowser } from '../util/open-browser.mjs';
 import { resolvePortAndMetadata } from '../shadow/prepare.mjs';
+import { tagDeployError, DeployError, grantReasonForStatus } from '../util/errors.mjs';
 import { deployBackend } from './backend.mjs';
 import { buildCommand } from './build.mjs';
 import { promptForTags } from './tag.mjs';
@@ -35,7 +36,13 @@ async function deployCommand(opts = {}) {
     const appName = mfAppName(consumerPkg.name);
     // 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;
+    try {
+        ({ token } = await readZthAuth());
+    }
+    catch (err) {
+        throw tagDeployError('read_auth_token', err);
+    }
     const ctx = { paths, consumerName: consumerPkg.name, appName, token, opts };
     if (opts.preview) {
         await deployPreview(ctx);
@@ -92,6 +99,8 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
     // Full CDN URL, not a relative path — trident-skeleton uses a manifest
     // 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');
     const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote: '' });
@@ -134,10 +143,10 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
     else {
         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);
         // Pass the raw consumer name (not the mf-prefixed appName) so defaultS3Remote
@@ -154,9 +163,14 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
     // 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');
     const keyPrefix = `${appName}/${nextVersion}`;
@@ -176,7 +190,6 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
         });
         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.
@@ -205,6 +218,8 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
         });
     }
     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);
     }
@@ -250,31 +265,39 @@ async function handleDeployTags(appSlug) {
         warn(`could not update tags: ${err.message}`);
     }
 }
-// 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, token) {
-    const res = await fetch(`${brokerBaseUrl()}/z2h-cli/lock/acquire`, {
+function postToLockEndpoint(path, appName, token) {
+    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, token) {
+    let res;
+    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 = 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}`);
 }
 // best-effort — the 2-min TTL backstop handles failures
 async function releaseLockBestEffort(appName, token) {
     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/dist/esm/commands/grant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grant.d.ts","sourceRoot":"","sources":["../../../src/commands/grant.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACvC;AAkBD,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B/F;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhG;AAED,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBnF"}
+{"version":3,"file":"grant.d.ts","sourceRoot":"","sources":["../../../src/commands/grant.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACvC;AAkBD,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B/F;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhG;AAED,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBnF"}

package/dist/esm/commands/grant.mjs

@@ -2,6 +2,7 @@ import { output } from '../util/logger.mjs';
 import { mfAppName, getCwdAppName } from '../util/app-name.mjs';
 import { brokerBaseUrl, routingHeaders } from '../constants.mjs';
 import { readZthAuth } from '../util/auth/auth-store.mjs';
+import { GrantError } from '../util/errors.mjs';
 
 async function postGrant(appName, token, body) {
     const res = await fetch(`${brokerBaseUrl()}/z2h-apps/${appName}/grants`, {
@@ -11,16 +12,16 @@ async function postGrant(appName, token, body) {
     });
     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)}`);
     }
 }
 async function grantCommand(email, opts) {
     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());
     const { token } = await readZthAuth();
@@ -41,7 +42,7 @@ async function grantCommand(email, opts) {
 }
 async function revokeCommand(email, opts) {
     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());
     const { token } = await readZthAuth();
@@ -52,7 +53,7 @@ async function revokeCommand(email, opts) {
     });
     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';
     const msg = email
@@ -62,7 +63,7 @@ async function revokeCommand(email, opts) {
 }
 async function transferOwnerCommand(email) {
     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());
     const { token } = await readZthAuth();
@@ -73,7 +74,7 @@ async function transferOwnerCommand(email) {
     });
     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 });
 }