@mondaydotcomorg/z2h-cli 0.25.4 → 0.25.8

package/dist/util/errors.js

@@ -0,0 +1,102 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+/**
+ * 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.
+ */
+class Z2hError extends Error {
+    reason;
+    data;
+    exitCode;
+    constructor(message, reason, data, exitCode = 1) {
+        super(message);
+        this.reason = reason;
+        this.data = data;
+        this.exitCode = exitCode;
+        this.name = new.target.name;
+    }
+}
+/** Tags a deploy/preview stage failure with a bounded reason code instead of a freeform message. */
+class DeployError extends Z2hError {
+    reason;
+    constructor(reason, message, data) {
+        super(message, reason, data);
+        this.reason = reason;
+    }
+}
+/**
+ * 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.
+ */
+class GrantError extends Z2hError {
+    constructor(reason, message, data) {
+        super(message, typeof reason === 'number' ? grantReasonForStatus(reason) : reason, data);
+    }
+}
+/** No z2h JWT found — see auth-store.ts for the discovery order (env var, then ~/.zth/auth.json). */
+class Z2hAuthMissingError extends Z2hError {
+    authFilePath;
+    constructor(authFilePath) {
+        super(`No Z2H deploy token found at ${authFilePath}. Please run 'z2h-cli generate-z2h-token' command.`, 'read_auth_token');
+        this.authFilePath = authFilePath;
+    }
+}
+/** A git pull diverged or a push was rejected; `reason` distinguishes which stage hit it. */
+class GitConflictError extends Z2hError {
+    constructor(message, reason = 'git_error') {
+        super(message, reason);
+    }
+}
+/** Maps an HTTP status to a bounded grant/revoke/transfer-owner failure reason. */
+function grantReasonForStatus(status) {
+    // 401 is an expired/invalid token (re-auth fixes it); 403 is a real permission denial.
+    if (status === 401) {
+        return 'auth';
+    }
+    if (status === 403) {
+        return 'forbidden';
+    }
+    if (status === 404) {
+        return 'not_found';
+    }
+    if (status >= 500) {
+        return 'server_error';
+    }
+    return 'unknown';
+}
+/** Tags a failure with `reason`, unless `err` is already classified; `signal` overrides `reason` for a killed child process. */
+function tagDeployError(reason, err) {
+    if (err instanceof Z2hError) {
+        return err;
+    }
+    const signal = err instanceof Error ? err.signal : undefined;
+    return new DeployError(signal ? 'interrupted' : reason, messageOf(err));
+}
+/** Reads the bounded reason off a classified error; anything unclassified is `unknown`. */
+function reasonOf(err) {
+    return err instanceof Z2hError ? err.reason : 'unknown';
+}
+/** Extra telemetry dimensions the throw site attached, if any. */
+function dataOf(err) {
+    return err instanceof Z2hError ? err.data ?? {} : {};
+}
+/** Safe message for any thrown value. A non-Error throw must not break the error path. */
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+
+exports.DeployError = DeployError;
+exports.GitConflictError = GitConflictError;
+exports.GrantError = GrantError;
+exports.Z2hAuthMissingError = Z2hAuthMissingError;
+exports.Z2hError = Z2hError;
+exports.dataOf = dataOf;
+exports.grantReasonForStatus = grantReasonForStatus;
+exports.messageOf = messageOf;
+exports.reasonOf = reasonOf;
+exports.tagDeployError = tagDeployError;

package/dist/util/git/repo.d.ts

@@ -1,6 +1,3 @@
-export declare class GitConflictError extends Error {
-    constructor(message: string);
-}
 export interface ConflictInfo {
     localCommits: string[];
     remoteCommits: string[];

package/dist/util/git/repo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../../src/util/git/repo.ts"],"names":[],"mappings":"AAkBA,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAKD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOzE;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI3E;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK/D;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5G;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAclE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA2B7F;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB3F;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO7D;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5D"}
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../../src/util/git/repo.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAKD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOzE;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI3E;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK/D;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5G;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAclE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA2B7F;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB3F;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO7D;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5D"}

package/dist/util/git/repo.js

@@ -5,6 +5,7 @@ const fs = require('fs-extra');
 const execa = require('execa');
 const constants = require('../../constants.js');
 const util_appName = require('../app-name.js');
+const util_errors = require('../errors.js');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
@@ -19,12 +20,6 @@ async function execGitLines(args, dir, env) {
         .then(r => r.stdout.split('\n').filter(Boolean))
         .catch(() => []);
 }
-class GitConflictError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'GitConflictError';
-    }
-}
 const REQUIRED_GITIGNORE_ENTRIES = ['node_modules/', '.zth/', 'build/'];
 const LOCAL_HOOKS_DIR = '.zth/hooks';
 function defaultS3Remote(app) {
@@ -98,7 +93,7 @@ async function pullAndResolve(dir, env) {
         }
         await safeBackupIfDirty(dir);
         const info = await gatherConflictInfo(dir, gitEnv);
-        throw new GitConflictError(`Pull rejected: Git conflict detected: ${JSON.stringify(info)}`);
+        throw new util_errors.GitConflictError(`Pull rejected: Git conflict detected: ${JSON.stringify(info)}`);
     }
 }
 /**
@@ -126,9 +121,9 @@ async function pushToRemote(dir, env) {
         }
         if (isRejected) {
             const info = await gatherConflictInfo(dir, gitEnv);
-            throw new GitConflictError(`Push rejected: Git conflict detected: ${JSON.stringify(info)}`);
+            throw new util_errors.GitConflictError(`Push rejected: Git conflict detected: ${JSON.stringify(info)}`, 'push_error');
         }
-        throw err;
+        throw new util_errors.DeployError('push_error', util_errors.messageOf(err));
     }
 }
 async function remoteHead(dir) {
@@ -183,7 +178,6 @@ async function ensureGitignore(dir) {
     await fs__default.default.outputFile(gitignorePath, content + separator + missing.join('\n') + '\n');
 }
 
-exports.GitConflictError = GitConflictError;
 exports.cloneRepo = cloneRepo;
 exports.defaultS3Remote = defaultS3Remote;
 exports.getRemoteUrl = getRemoteUrl;

package/dist/util/logger.d.ts

@@ -17,6 +17,9 @@ export declare function output(human: string, data: unknown): void;
 /**
  * Emit a structured failure payload (JSON mode) or a red error line (human mode),
  * then exit with the given code.
+ *
+ * `track: false` skips the telemetry event but still prints and exits. Commands with no
+ * success event pass it, so their failures don't skew per-command error rates.
  */
-export declare function fail(message: string, payload: Record<string, unknown>, exitCode?: number): Promise<never>;
+export declare function fail(message: string, payload: Record<string, unknown>, exitCode?: number, track?: boolean): Promise<never>;
 //# sourceMappingURL=logger.d.ts.map

package/dist/util/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/util/logger.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAI1C,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAEpD;AAED,wBAAgB,aAAa,IAAI,UAAU,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAItC;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAItC;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI1C;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAMzD;AAED;;;GAGG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,SAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAW1G"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/util/logger.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAI1C,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAEpD;AAED,wBAAgB,aAAa,IAAI,UAAU,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAItC;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAItC;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI1C;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAMzD;AAED;;;;;;GAMG;AACH,wBAAsB,IAAI,CACxB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,SAAI,EACZ,KAAK,UAAO,GACX,OAAO,CAAC,KAAK,CAAC,CAehB"}

package/dist/util/logger.js

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const pc = require('picocolors');
+const observability = require('@mondaydotcomorg/z2h-shared-utils/observability');
 const util_tracker = require('./tracker.js');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
@@ -49,10 +50,15 @@ function output(human, data) {
 /**
  * Emit a structured failure payload (JSON mode) or a red error line (human mode),
  * then exit with the given code.
+ *
+ * `track: false` skips the telemetry event but still prints and exits. Commands with no
+ * success event pass it, so their failures don't skew per-command error rates.
  */
-async function fail(message, payload, exitCode = 1) {
+async function fail(message, payload, exitCode = 1, track = true) {
+    // Canonical fields go last so a payload key can never shadow `error`/`action`.
+    const { command, ...rest } = payload;
     if (mode === 'json') {
-        process.stdout.write(`${JSON.stringify({ ok: false, error: message, ...payload })}\n`);
+        process.stdout.write(`${JSON.stringify({ ok: false, ...payload, error: message })}\n`);
     }
     else {
         process.stderr.write(pc__default.default.red(`[z2h-cli] ${message}\n`));
@@ -60,7 +66,9 @@ async function fail(message, payload, exitCode = 1) {
             process.stderr.write(pc__default.default.dim(`  → ${payload.suggestedCommand}\n`));
         }
     }
-    await util_tracker.trackEvent('z2h_cli_error', { action: payload.command ?? 'unknown', error: message });
+    if (track) {
+        await util_tracker.trackEvent(observability.Z2hCliEvents.error, { ...rest, action: command ?? 'unknown', error: message });
+    }
     process.exit(exitCode);
 }
 

package/dist/util/run-command.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from 'commander';
+import type { CommandSpec } from '../types';
+/**
+ * Wraps a command body with the whole telemetry and failure contract so no command
+ * hand-rolls it. It times the happy path. On a throw it reads `reason` and `data` straight
+ * off the error, defined in ./errors, instead of re-deriving them per command.
+ *
+ * Returns a commander action handler, chainable straight off `.command(...)` — commander always
+ * appends the Command instance as the action handler's last argument, so this splits it back off
+ * to read the command's own name/parent instead of asking the caller to pass it in.
+ *
+ * NoInfer keeps the arg types coming from `fn` alone. A `data` or `label` callback that
+ * only needs the first arg must not narrow the handler's own signature.
+ */
+export declare function runCommand<A extends unknown[]>(spec: CommandSpec<NoInfer<A>>, fn: (...args: A) => Promise<unknown>): (...args: [...A, Command]) => Promise<void>;
+//# sourceMappingURL=run-command.d.ts.map

package/dist/util/run-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-command.d.ts","sourceRoot":"","sources":["../../src/util/run-command.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,UAAU,CAAC;AAcrD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,OAAO,EAAE,EAC5C,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAC7B,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GACnC,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAyB7C"}

package/dist/util/run-command.js

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

package/dist/util/s3/upload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../../src/util/s3/upload.ts"],"names":[],"mappings":"AAeA,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,MAA0B,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CA0BnB"}
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../../src/util/s3/upload.ts"],"names":[],"mappings":"AAgBA,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,MAA0B,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CA8BnB"}

package/dist/util/s3/upload.js

@@ -7,6 +7,7 @@ const mimeTypes = require('mime-types');
 const pMap = require('p-map');
 const clientS3 = require('@aws-sdk/client-s3');
 const constants = require('../../constants.js');
+const util_errors = require('../errors.js');
 const util_s3_client = require('./client.js');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
@@ -19,22 +20,27 @@ const pMap__default = /*#__PURE__*/_interopDefault(pMap);
 const FOREVER = 'public, immutable';
 const UPLOAD_CONCURRENCY = 5;
 async function uploadDir(localDir, keyPrefix, bucket = constants.BUCKET_WRITE_NAME) {
-    const entries = await promises.readdir(localDir, { recursive: true, withFileTypes: true });
-    const files = entries.filter(e => e.isFile()).map(e => path__default.default.relative(localDir, path__default.default.join(e.parentPath, e.name)));
-    const s3 = util_s3_client.getS3Client();
-    await pMap__default.default(files, async (rel) => {
-        const body = await fs.readFile(path__default.default.join(localDir, rel));
-        const contentType = mimeTypes.lookup(rel) || 'application/octet-stream';
-        const key = `${keyPrefix}/${rel.split(path__default.default.sep).join('/')}`;
-        await s3.send(new clientS3.PutObjectCommand({
-            Bucket: bucket,
-            Key: key,
-            Body: body,
-            ContentType: contentType,
-            CacheControl: FOREVER,
-        }));
-    }, { concurrency: UPLOAD_CONCURRENCY });
-    return files.map(f => f.split(path__default.default.sep).join('/'));
+    try {
+        const entries = await promises.readdir(localDir, { recursive: true, withFileTypes: true });
+        const files = entries.filter(e => e.isFile()).map(e => path__default.default.relative(localDir, path__default.default.join(e.parentPath, e.name)));
+        const s3 = util_s3_client.getS3Client();
+        await pMap__default.default(files, async (rel) => {
+            const body = await fs.readFile(path__default.default.join(localDir, rel));
+            const contentType = mimeTypes.lookup(rel) || 'application/octet-stream';
+            const key = `${keyPrefix}/${rel.split(path__default.default.sep).join('/')}`;
+            await s3.send(new clientS3.PutObjectCommand({
+                Bucket: bucket,
+                Key: key,
+                Body: body,
+                ContentType: contentType,
+                CacheControl: FOREVER,
+            }));
+        }, { concurrency: UPLOAD_CONCURRENCY });
+        return files.map(f => f.split(path__default.default.sep).join('/'));
+    }
+    catch (err) {
+        throw util_errors.tagDeployError('s3_error', err);
+    }
 }
 
 exports.uploadDir = uploadDir;

package/dist/util/tracker.d.ts

@@ -1,3 +1,10 @@
-export declare function trackEvent(name: string, data: Record<string, unknown>): Promise<void>;
-export declare function trackDuration<T>(eventName: string, fn: () => Promise<T>, data?: Record<string, unknown>): Promise<T>;
+export declare const trackEvent: (name: string, data: Record<string, unknown>) => Promise<void>, trackDuration: <T>(name: string, fn: () => Promise<T>, data?: Record<string, unknown>) => Promise<T>;
+/**
+ * `z2h_cli_<command>_success` — the success-event name for every command, derived by
+ * util/run-command.ts's `runCommand()` so no command has to choose one. Nested commands join
+ * their path with `_` (`backend invoke` → `z2h_cli_backend_invoke_success`). The one place a
+ * command names its own event, `deploy --preview`, still goes through this function so the
+ * convention holds everywhere. See CommandSpec's `event` field in types.ts.
+ */
+export declare function successEvent(command: string): string;
 //# sourceMappingURL=tracker.d.ts.map

package/dist/util/tracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/util/tracker.ts"],"names":[],"mappings":"AASA,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAS3F;AAED,wBAAsB,aAAa,CAAC,CAAC,EACnC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAKZ"}
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/util/tracker.ts"],"names":[],"mappings":"AAcA,eAAO,MAAQ,UAAU,kEAAE,aAAa,uFAItC,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/util/tracker.js

@@ -1,7 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const os = require('node:os');
+const node_module = require('node:module');
+const observability = require('@mondaydotcomorg/z2h-shared-utils/observability');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
 const os__default = /*#__PURE__*/_interopDefault(os);
@@ -9,22 +12,24 @@ const os__default = /*#__PURE__*/_interopDefault(os);
 const DOORMAN_URL = 'https://track-int.bigbrain.me/prod/event';
 const DOORMAN_URL_STAGING = 'https://track-int.bigbrainstaging.me/stage/event';
 const username = os__default.default.userInfo().username;
+const { version: cliVersion } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('util/tracker.js', document.baseURI).href)))('@mondaydotcomorg/z2h-cli/package.json');
 const isStaging = process.env.NODE_ENV === 'staging';
-async function trackEvent(name, data) {
-    const doormanUrl = isStaging ? DOORMAN_URL_STAGING : DOORMAN_URL;
-    await fetch(doormanUrl, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ name, source: 'z2h-cli', data: { user_name: username, ...data } }),
-        signal: AbortSignal.timeout(5000),
-    }).catch(() => { });
-}
-async function trackDuration(eventName, fn, data) {
-    const start = Date.now();
-    const result = await fn();
-    await trackEvent(eventName, { ...data, duration_ms: Date.now() - start });
-    return result;
+const { trackEvent, trackDuration } = observability.createHttpTracker({
+    url: isStaging ? DOORMAN_URL_STAGING : DOORMAN_URL,
+    source: 'z2h-cli',
+    getContext: () => ({ user_name: username, cli_version: cliVersion }),
+});
+/**
+ * `z2h_cli_<command>_success` — the success-event name for every command, derived by
+ * util/run-command.ts's `runCommand()` so no command has to choose one. Nested commands join
+ * their path with `_` (`backend invoke` → `z2h_cli_backend_invoke_success`). The one place a
+ * command names its own event, `deploy --preview`, still goes through this function so the
+ * convention holds everywhere. See CommandSpec's `event` field in types.ts.
+ */
+function successEvent(command) {
+    return `z2h_cli_${command.replace(/[\s-]+/g, '_')}_success`;
 }
 
+exports.successEvent = successEvent;
 exports.trackDuration = trackDuration;
 exports.trackEvent = trackEvent;

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

@@ -1,5 +1,6 @@
-import { logger, metric } from '@mondaydotcomorg/trident-backend-runtime';
+import { logger } from '@mondaydotcomorg/trident-backend-runtime';
 
+import { withChannelTelemetry } from './channel-telemetry';
 import { makeDbChannel } from './db-channel/db.channel';
 import { makeLlmChannel } from './llm-channel/llm.channel';
 import { makeMondayChannel } from './monday-channel/monday.channel';
@@ -56,8 +57,9 @@ const OAUTH_CHANNELS: Record<string, (caller: Caller) => ChannelMap> = {
  * `monday_not_connected`, `monday_auth`, … A `4xx` means the handler (or the user's
  * setup) is wrong and retrying won't help; `502` means the upstream failed.
  *
- * Each key is wrapped with `z2h.channel.<key>` duration + error metrics, tagged by app.
- * Failures also reach BI generically at the invoke level — see `runner.service.ts`.
+ * Each key emits a unified call counter, duration distribution, and BI event tagged
+ * by app, channel, method, and outcome. Uncaught failures also reach BI at the
+ * invocation level — see `runner.service.ts`.
  */
 export function buildChannels(appName: string, caller: Caller, declaredIntegrations: string[]): ChannelMap {
   const channels: ChannelMap = {
@@ -78,13 +80,5 @@ export function buildChannels(appName: string, caller: Caller, declaredIntegrati
     }
   }
 
-  return Object.fromEntries(
-    Object.entries(channels).map(([key, fn]) => [
-      key,
-      metric.wrapFunctionWithMetrics(fn, {
-        customName: `z2h.channel.${key}`,
-        tags: { highCardinalityTags: { appName } },
-      }),
-    ]),
-  );
+  return Object.fromEntries(Object.entries(channels).map(([key, fn]) => [key, withChannelTelemetry(appName, key, fn)]));
 }

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

@@ -0,0 +1,79 @@
+import { metric } from '@mondaydotcomorg/trident-backend-runtime';
+import { BackendRunnerEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
+import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability/trident';
+
+import { ChannelError } from '../backend-runner.errors';
+import type { ChannelHandler } from '../backend-runner.types';
+import { BI_SOURCE } from '../constants';
+
+type ChannelOutcome = 'success' | 'failure';
+
+function parseChannelKey(key: string): { channel: string; method: string } {
+  const parts = key.split('.');
+  if (parts.length !== 2 || parts.some((part) => !part)) {
+    throw new Error(`channel key must use <channel>.<method>: ${key}`);
+  }
+  return { channel: parts[0], method: parts[1] };
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    (typeof value === 'object' || typeof value === 'function') &&
+    value !== null &&
+    typeof (value as PromiseLike<unknown>).then === 'function'
+  );
+}
+
+function recordChannelCall(
+  appName: string,
+  channel: string,
+  method: string,
+  outcome: ChannelOutcome,
+  startedAt: number,
+  error?: unknown,
+): void {
+  const durationMs = performance.now() - startedAt;
+  const dimensions = { appName, channel, method };
+
+  metric.increment(BackendRunnerEvents.channel.callMetric, { ...dimensions, outcome });
+  metric.distribution(BackendRunnerEvents.channel.durationMetric, durationMs, dimensions);
+  void trackEvent(
+    BackendRunnerEvents.channel.biEvent,
+    {
+      ...dimensions,
+      outcome,
+      duration_ms: durationMs,
+      ...(error instanceof ChannelError ? { error_code: error.code } : {}),
+    },
+    BI_SOURCE,
+  );
+}
+
+export function withChannelTelemetry(appName: string, key: string, handler: ChannelHandler): ChannelHandler {
+  const { channel, method } = parseChannelKey(key);
+
+  return (args) => {
+    const startedAt = performance.now();
+    try {
+      const result = handler(args);
+      if (isPromiseLike(result)) {
+        return Promise.resolve(result).then(
+          (value) => {
+            recordChannelCall(appName, channel, method, 'success', startedAt);
+            return value;
+          },
+          (error: unknown) => {
+            recordChannelCall(appName, channel, method, 'failure', startedAt, error);
+            throw error;
+          },
+        );
+      }
+
+      recordChannelCall(appName, channel, method, 'success', startedAt);
+      return result;
+    } catch (error) {
+      recordChannelCall(appName, channel, method, 'failure', startedAt, error);
+      throw error;
+    }
+  };
+}

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

@@ -1,6 +1,7 @@
 import { logger } from '@mondaydotcomorg/trident-backend-runtime';
 import { createMondayModel } from '@mondaydotcomorg/kong-ai-gateway-sdk/langchain';
-import { BackendRunnerEvents, trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability';
+import { BackendRunnerEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
+import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability/trident';
 
 import { ChannelError } from '../../backend-runner.errors';
 import { BI_SOURCE } from '../../constants';
@@ -209,7 +210,7 @@ export function makeLlmChannel(appName: string, caller: Caller) {
           LLM_TIMEOUT_MS,
           'LLM gateway',
         );
-        trackEvent(BackendRunnerEvents.llm.call, { appName, email: caller.email, modelId: model }, BI_SOURCE);
+        void trackEvent(BackendRunnerEvents.llm.call, { appName, email: caller.email, modelId: model }, BI_SOURCE);
         return { content: extractText(response.content) };
       } catch (err) {
         throw toLlmChannelError(err);

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

@@ -1,7 +1,8 @@
 import { createHash } from 'node:crypto';
 
 import { context, logger } from '@mondaydotcomorg/trident-backend-runtime';
-import { BackendRunnerEvents, trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability';
+import { BackendRunnerEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
+import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability/trident';
 import { getDefaultClient } from 'src/utils/elasticache';
 
 import { ChannelError } from '../../backend-runner.errors';
@@ -25,6 +26,18 @@ export interface SnowflakeRow {
 export interface RunQueryOptions {
   /** Clamped to MAX_TIMEOUT_MS. Defaults to DEFAULT_TIMEOUT_MS. */
   timeoutMs?: number;
+  /** Human-readable label for the pool identifier/logs, e.g. a widget name, instead of the default query-shape hash. Sanitized to `[a-z0-9-_]`, max 64 chars. */
+  identifier?: string;
+}
+
+const MAX_IDENTIFIER_LENGTH = 64;
+
+function sanitizeIdentifier(raw: string): string {
+  return raw
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, MAX_IDENTIFIER_LENGTH);
 }
 
 function hashQuery(boundSql: string, params: Record<string, SnowflakeParamValue>): string {
@@ -109,8 +122,8 @@ function resolveTimeout(timeoutMs: number | undefined): number {
  */
 export async function runSnowflakeQuery(
   sql: string,
+  appName: string,
   params?: Record<string, SnowflakeParamValue> | null,
-  appName?: string,
   options?: RunQueryOptions | null,
 ): Promise<SnowflakeRow[]> {
   const timeoutInMs = resolveTimeout(options?.timeoutMs);
@@ -132,13 +145,14 @@ export async function runSnowflakeQuery(
 
   // Cache key stays parameter-sensitive; the pool identifier deliberately is not.
   const queryCacheKey = hashQuery(boundSql, params ?? {});
-  const queryIdentifier = hashQueryShape(sql);
+  const sanitizedIdentifier = options?.identifier ? sanitizeIdentifier(options.identifier) : '';
+  const queryIdentifier = sanitizedIdentifier || hashQueryShape(sql);
   const scope = cacheScope(useStateless);
   const startMs = Date.now();
   const cached = scope ? await readCache(queryCacheKey, scope) : null;
   if (cached) {
     const duration_ms = Date.now() - startMs;
-    trackEvent(BackendRunnerEvents.snowflake.queryExecuted, { appName, duration_ms, cache_hit: true }, BI_SOURCE);
+    void trackEvent(BackendRunnerEvents.snowflake.queryExecuted, { appName, duration_ms, cache_hit: true }, BI_SOURCE);
     logger.info(
       {
         tag: LOG_TAG,
@@ -155,7 +169,7 @@ export async function runSnowflakeQuery(
 
   const queryOptions = {
     query: boundSql,
-    identifier: `z2h-query:${queryIdentifier}`,
+    identifier: `z2h-query:${appName}:${queryIdentifier}`,
     fallback: [] as SnowflakeRow[],
     timeoutInMs,
     convertToSingularResult: false,
@@ -182,7 +196,7 @@ export async function runSnowflakeQuery(
     );
   } catch (err) {
     // Failure BI tracking already happens generically at the invoke level
-    // (runner.service.ts's z2h_backend_invoke_failed, tagged with this
+    // (runner.service.ts's BackendRunnerEvents.invoke.biEvent, tagged with this
     // ChannelError's `code`) — this stays a log only, for the queryHash/
     // queryIdentifier that generic event can't know about.
     const duration_ms = Date.now() - startMs;
@@ -195,7 +209,7 @@ export async function runSnowflakeQuery(
     await writeCache(queryCacheKey, scope, rows);
   }
   const duration_ms = Date.now() - startMs;
-  trackEvent(BackendRunnerEvents.snowflake.queryExecuted, { appName, duration_ms, cache_hit: false }, BI_SOURCE);
+  void trackEvent(BackendRunnerEvents.snowflake.queryExecuted, { appName, duration_ms, cache_hit: false }, BI_SOURCE);
   logger.info(
     { tag: LOG_TAG, queryHash: queryCacheKey, queryIdentifier, duration_ms, rowCount: rows.length, cache_hit: false },
     'query executed',