@mondaydotcomorg/z2h-cli 0.33.2 → 0.33.3-feature-chezki-templates-poc-93101e2

package/dist/backend/parser/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../src/backend/parser/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8D,KAAK,OAAO,EAAkB,MAAM,OAAO,CAAC;AAkDjH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAuBhE"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../src/backend/parser/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8D,KAAK,OAAO,EAAkB,MAAM,OAAO,CAAC;AAmDjH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAuBhE"}

package/dist/backend/parser/parse.js

@@ -2,6 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const acorn = require('acorn');
 const zod = require('zod');
+const observability = require('@mondaydotcomorg/z2h-shared-utils/observability');
 const util_tracker = require('../../util/tracker.js');
 const backend_parser_handlerDeclaration = require('./handler-declaration.js');
 const backend_parser_messages = require('./messages.js');
@@ -29,7 +30,7 @@ const isImportLike = (node) => node.type === 'ImportDeclaration' ||
 const isExport = (node) => node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration';
 /** Reports the failure, then returns the error for the caller to throw. */
 function parseError(message) {
-    void util_tracker.trackEvent('z2h_cli_handler_parse_error', { error: message });
+    void util_tracker.trackEvent(observability.Z2hCliEvents.handlerParseError, { error: message });
     return new Error(message);
 }
 /**

package/dist/dashboard-templates.d.ts

@@ -0,0 +1,2 @@
+export { loadDashboardTemplatesCatalog, findTemplate, type DashboardTemplateEntry, } from './util/dashboard-templates/load-catalog';
+//# sourceMappingURL=dashboard-templates.d.ts.map

package/dist/dashboard-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-templates.d.ts","sourceRoot":"","sources":["../src/dashboard-templates.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,YAAY,EACZ,KAAK,sBAAsB,GAC5B,MAAM,yCAAyC,CAAC"}

package/dist/dashboard-templates.js

@@ -0,0 +1,8 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const util_dashboardTemplates_loadCatalog = require('./util/dashboard-templates/load-catalog.js');
+
+
+
+exports.findTemplate = util_dashboardTemplates_loadCatalog.findTemplate;
+exports.loadDashboardTemplatesCatalog = util_dashboardTemplates_loadCatalog.loadDashboardTemplatesCatalog;

package/dist/esm/backend/parser/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8D,KAAK,OAAO,EAAkB,MAAM,OAAO,CAAC;AAkDjH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAuBhE"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/backend/parser/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8D,KAAK,OAAO,EAAkB,MAAM,OAAO,CAAC;AAmDjH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAuBhE"}

package/dist/esm/backend/parser/parse.mjs

@@ -1,5 +1,6 @@
 import { parse } from 'acorn';
 import { z } from 'zod';
+import { Z2hCliEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
 import { trackEvent } from '../../util/tracker.mjs';
 import { exportsHandler } from './handler-declaration.mjs';
 import { messages } from './messages.mjs';
@@ -27,7 +28,7 @@ const isImportLike = (node) => node.type === 'ImportDeclaration' ||
 const isExport = (node) => node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration';
 /** Reports the failure, then returns the error for the caller to throw. */
 function parseError(message) {
-    void trackEvent('z2h_cli_handler_parse_error', { error: message });
+    void trackEvent(Z2hCliEvents.handlerParseError, { error: message });
     return new Error(message);
 }
 /**

package/dist/esm/dashboard-templates.d.ts

@@ -0,0 +1,2 @@
+export { loadDashboardTemplatesCatalog, findTemplate, type DashboardTemplateEntry, } from './util/dashboard-templates/load-catalog';
+//# sourceMappingURL=dashboard-templates.d.ts.map

package/dist/esm/dashboard-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-templates.d.ts","sourceRoot":"","sources":["../../src/dashboard-templates.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,YAAY,EACZ,KAAK,sBAAsB,GAC5B,MAAM,yCAAyC,CAAC"}

package/dist/esm/dashboard-templates.mjs

@@ -0,0 +1 @@
+export { findTemplate, loadDashboardTemplatesCatalog } from './util/dashboard-templates/load-catalog.mjs';

package/dist/esm/index.mjs

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { Command } from 'commander';
 import { execa } from 'execa';
+import { Z2hCliEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
 import { getWorkspaceHome } from './util/workspace.mjs';
 import { buildCommand } from './commands/build.mjs';
 import { cleanCommand } from './commands/clean.mjs';
@@ -23,7 +24,6 @@ import { backendValidateCommand, backendInvokeCommand } from './commands/backend
 import { doctorCommand } from './commands/doctor.mjs';
 import { fail, errorLog, setOutputMode, getOutputMode } from './util/logger.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)('@mondaydotcomorg/z2h-cli/package.json');
@@ -77,14 +77,14 @@ async function main() {
     program
         .command('build')
         .description('Build the consumer into its .zth/ shadow and copy artifacts to ./build/')
-        // 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()));
+        // A standalone build failure is the consumer's own code, not a CLI/infra problem — runCommand
+        // skips the error event for failures tagged `build_error` (buildCommand tags it on its thrown
+        // error). Any other failure here is still reported.
+        .action(runCommand({ event: Z2hCliEvents.buildSuccess, data: cwdApp, exitCode: 2 }, () => buildCommand()));
     program
         .command('clean')
         .description('Delete <consumer>/.zth/ and <consumer>/build/')
-        .action(runCommand({ track: false, exitCode: 2 }, () => cleanCommand()));
+        .action(runCommand({ exitCode: 2 }, () => cleanCommand()));
     program
         .command('deploy')
         .description('Build, upload to S3, and register the app with the Z2H backend')
@@ -96,9 +96,7 @@ async function main() {
         .option('--description <text>', 'short (<=200 char) description of the app')
         .option('--prebuilt-dir <path>', 'internal — used by `generate-app-template`: skip the build step and deploy this already-built directory as-is')
         .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'),
+        event: ([opts]) => opts.preview ? Z2hCliEvents.previewSuccess : Z2hCliEvents.deploySuccess,
         label: ([opts]) => (opts.preview ? 'preview' : 'deploy'),
         data: cwdApp,
         exitCode: 2,
@@ -113,7 +111,7 @@ async function main() {
     program
         .command('create-workspace')
         .description(`Bootstrap the ${getWorkspaceHome()}/ yarn workspace (one-time setup)`)
-        .action(runCommand({ track: false }, () => createWorkspaceCommand()));
+        .action(runCommand({}, () => 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')
@@ -128,6 +126,7 @@ async function main() {
         .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(runCommand({
+        event: Z2hCliEvents.createSuccess,
         data: ([appName, opts]) => ({
             app_name: appName,
             template: opts.template ?? 'default',
@@ -136,20 +135,21 @@ async function main() {
     }, (appName, opts) => createCommand(appName, opts)));
     program
         .command('templates')
-        .description("List the BigBrain Studio (Z2H) template catalog — id, title, description, and each template's widget schema")
-        .action(runCommand({}, () => templatesCommand()));
+        .description("List the BigBrain Studio (Z2H) template catalog — id, title, description, and each template's config schema")
+        .action(runCommand({ event: Z2hCliEvents.templatesSuccess }, () => templatesCommand()));
     program
         .command('generate-app-template <app-name>')
         .description(`Scaffold + preview a Z2H app/dashboard from a templates catalog entry inside ${getWorkspaceHome()}/ — copies a prebuilt template, patches in real widget data, and deploys a preview. No build, no yarn install, no live deploy — run \`z2h-cli deploy\` yourself from the app dir once you're happy with it.`)
         .requiredOption('--template <id>', 'catalog template id — see `z2h-cli templates --json`')
         .requiredOption('--input <json>', "JSON string — shape is template-defined, validated wholesale against the template's configSchema (see `z2h-cli templates --json`)")
         .action(runCommand({
+        event: Z2hCliEvents.generateAppTemplateSuccess,
         data: ([appName, opts]) => ({ app_name: appName, template: opts.template }),
     }, (appName, opts) => generateCommand(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(runCommand({ data: ([appName]) => ({ app_name: appName }) }, (appName) => editCommand(appName)));
+        .action(runCommand({ event: Z2hCliEvents.editSuccess, data: ([appName]) => ({ app_name: appName }) }, (appName) => editCommand(appName)));
     program
         .command('grant [email]')
         .description('Grant access to the current app (email, --public, or both)')
@@ -177,7 +177,7 @@ async function main() {
         .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(runCommand({ data: cwdApp }, (opts) => deleteCommand(opts)));
+        .action(runCommand({ event: Z2hCliEvents.deleteSuccess, data: cwdApp }, (opts) => deleteCommand(opts)));
     const backend = program
         .command('backend')
         .description("Inspect the app's backend: validate handler sources or run a handler from the working tree");
@@ -208,7 +208,7 @@ async function main() {
     program
         .command('doctor')
         .description('Check that all Z2H tools, auth, workspace, and plugins are correctly set up')
-        .action(runCommand({ track: false }, () => doctorCommand()));
+        .action(runCommand({}, () => doctorCommand()));
     await program.parseAsync(process.argv);
 }
 void main()

package/dist/esm/types.d.ts

@@ -2,6 +2,7 @@
  * Shared domain types for the Z2H CLI. Command-scoped option types live
  * with their command; narrow single-use types stay local to their file.
  */
+import type { Z2hCliEventName } from '@mondaydotcomorg/z2h-shared-utils/observability';
 export interface ConsumerPkg {
     name: string;
     version?: string;
@@ -60,12 +61,10 @@ export type GrantFailureReason = 'validation' | 'auth' | 'forbidden' | 'not_foun
 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.
+     * Success-event name from `Z2hCliEvents` (a function when it depends on args, e.g. `deploy --preview`).
+     * Omit it to send no success event. Failures are reported either way.
      */
-    track?: PerArgs<A, boolean>;
-    /** Success-event name when it depends on args (e.g. `deploy --preview`); defaults to `successEvent(<command>)`. */
-    event?: PerArgs<A, string>;
+    event?: PerArgs<A, Z2hCliEventName>;
     /** 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. */

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

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

@@ -18,8 +18,8 @@ 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.
+ * `track: false` skips the telemetry event but still prints and exits. runCommand passes it
+ * for failures that aren't a CLI/infra problem (a consumer's own broken build).
  */
 export declare function fail(message: string, payload: Record<string, unknown>, exitCode?: number, track?: boolean): Promise<never>;
 //# sourceMappingURL=logger.d.ts.map

package/dist/esm/util/logger.mjs

@@ -45,8 +45,8 @@ 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.
+ * `track: false` skips the telemetry event but still prints and exits. runCommand passes it
+ * for failures that aren't a CLI/infra problem (a consumer's own broken build).
  */
 async function fail(message, payload, exitCode = 1, track = true) {
     // Canonical fields go last so a payload key can never shadow `error`/`action`.

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

@@ -1 +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"}
+{"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;AAKrD;;;;;;;;;;;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,CAwB7C"}

package/dist/esm/util/run-command.mjs

@@ -1,14 +1,8 @@
 import { fail } from './logger.mjs';
-import { successEvent, trackDuration } from './tracker.mjs';
+import { trackDuration } from './tracker.mjs';
 import { reasonOf, Z2hError, dataOf, messageOf } from './errors.mjs';
 
-/** 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;
-};
+const pick = (field, args) => 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
@@ -25,20 +19,19 @@ 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, successEvent(name));
+        // Top-level commands hang off the root program (`z2h-cli`), which has no parent itself and isn't
+        // part of a command's name. Only a nested command (`backend invoke`) has a non-root parent to prefix.
+        const name = cmd.parent?.parent ? `${cmd.parent.name()} ${cmd.name()}` : cmd.name();
+        const label = spec.label ? pick(spec.label, args) : name;
+        const event = spec.event ? pick(spec.event, args) : null;
         const data = spec.data?.(args) ?? {};
         try {
-            await (track ? trackDuration(event, () => fn(...args), data) : fn(...args));
+            await (event ? trackDuration(event, () => fn(...args), data) : fn(...args));
         }
         catch (err) {
             const reason = 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';
+            // A consumer's own broken build isn't a CLI/infra problem — don't report it at all, not even as `unknown`.
+            const shouldTrack = reason !== 'build_error';
             await fail(`${label} failed: ${messageOf(err)}`, { command: label, reason, ...data, ...dataOf(err) }, spec.exitCode ?? (err instanceof Z2hError ? err.exitCode : 1), shouldTrack);
         }
     };

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

@@ -1,10 +1,2 @@
 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/esm/util/tracker.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../../src/util/tracker.ts"],"names":[],"mappings":"AAcA,eAAO,MAAQ,UAAU,kEAAE,aAAa,uFAItC,CAAC"}

package/dist/esm/util/tracker.mjs

@@ -12,15 +12,5 @@ const { trackEvent, trackDuration } = createHttpTracker({
     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`;
-}
 
-export { successEvent, trackDuration, trackEvent };
+export { trackDuration, trackEvent };

package/dist/index.js

@@ -3,6 +3,7 @@ const os = require('node:os');
 const path = require('node:path');
 const commander = require('commander');
 const execa = require('execa');
+const observability = require('@mondaydotcomorg/z2h-shared-utils/observability');
 const util_workspace = require('./util/workspace.js');
 const commands_build = require('./commands/build.js');
 const commands_clean = require('./commands/clean.js');
@@ -23,7 +24,6 @@ const commands_backend = require('./commands/backend.js');
 const commands_doctor = require('./commands/doctor.js');
 const util_logger = require('./util/logger.js');
 const util_runCommand = require('./util/run-command.js');
-const util_tracker = require('./util/tracker.js');
 const util_appName = require('./util/app-name.js');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -83,14 +83,14 @@ async function main() {
     program
         .command('build')
         .description('Build the consumer into its .zth/ shadow and copy artifacts to ./build/')
-        // 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(util_runCommand.runCommand({ track: false, data: cwdApp, exitCode: 2 }, () => commands_build.buildCommand()));
+        // A standalone build failure is the consumer's own code, not a CLI/infra problem — runCommand
+        // skips the error event for failures tagged `build_error` (buildCommand tags it on its thrown
+        // error). Any other failure here is still reported.
+        .action(util_runCommand.runCommand({ event: observability.Z2hCliEvents.buildSuccess, data: cwdApp, exitCode: 2 }, () => commands_build.buildCommand()));
     program
         .command('clean')
         .description('Delete <consumer>/.zth/ and <consumer>/build/')
-        .action(util_runCommand.runCommand({ track: false, exitCode: 2 }, () => commands_clean.cleanCommand()));
+        .action(util_runCommand.runCommand({ exitCode: 2 }, () => commands_clean.cleanCommand()));
     program
         .command('deploy')
         .description('Build, upload to S3, and register the app with the Z2H backend')
@@ -102,9 +102,7 @@ async function main() {
         .option('--description <text>', 'short (<=200 char) description of the app')
         .option('--prebuilt-dir <path>', 'internal — used by `generate-app-template`: skip the build step and deploy this already-built directory as-is')
         .action(util_runCommand.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]) => util_tracker.successEvent(opts.preview ? 'preview' : 'deploy'),
+        event: ([opts]) => opts.preview ? observability.Z2hCliEvents.previewSuccess : observability.Z2hCliEvents.deploySuccess,
         label: ([opts]) => (opts.preview ? 'preview' : 'deploy'),
         data: cwdApp,
         exitCode: 2,
@@ -119,7 +117,7 @@ async function main() {
     program
         .command('create-workspace')
         .description(`Bootstrap the ${util_workspace.getWorkspaceHome()}/ yarn workspace (one-time setup)`)
-        .action(util_runCommand.runCommand({ track: false }, () => commands_createWorkspace.createWorkspaceCommand()));
+        .action(util_runCommand.runCommand({}, () => commands_createWorkspace.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')
@@ -134,6 +132,7 @@ async function main() {
         .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(util_runCommand.runCommand({
+        event: observability.Z2hCliEvents.createSuccess,
         data: ([appName, opts]) => ({
             app_name: appName,
             template: opts.template ?? 'default',
@@ -142,20 +141,21 @@ async function main() {
     }, (appName, opts) => commands_create.createCommand(appName, opts)));
     program
         .command('templates')
-        .description("List the BigBrain Studio (Z2H) template catalog — id, title, description, and each template's widget schema")
-        .action(util_runCommand.runCommand({}, () => commands_templates.templatesCommand()));
+        .description("List the BigBrain Studio (Z2H) template catalog — id, title, description, and each template's config schema")
+        .action(util_runCommand.runCommand({ event: observability.Z2hCliEvents.templatesSuccess }, () => commands_templates.templatesCommand()));
     program
         .command('generate-app-template <app-name>')
         .description(`Scaffold + preview a Z2H app/dashboard from a templates catalog entry inside ${util_workspace.getWorkspaceHome()}/ — copies a prebuilt template, patches in real widget data, and deploys a preview. No build, no yarn install, no live deploy — run \`z2h-cli deploy\` yourself from the app dir once you're happy with it.`)
         .requiredOption('--template <id>', 'catalog template id — see `z2h-cli templates --json`')
         .requiredOption('--input <json>', "JSON string — shape is template-defined, validated wholesale against the template's configSchema (see `z2h-cli templates --json`)")
         .action(util_runCommand.runCommand({
+        event: observability.Z2hCliEvents.generateAppTemplateSuccess,
         data: ([appName, opts]) => ({ app_name: appName, template: opts.template }),
     }, (appName, opts) => commands_generate.generateCommand(appName, opts)));
     program
         .command('edit <app-name>')
         .description(`Pull the latest version of an app into ${util_workspace.getWorkspaceHome()}/<app-name>, cloning it first if needed`)
-        .action(util_runCommand.runCommand({ data: ([appName]) => ({ app_name: appName }) }, (appName) => commands_edit.editCommand(appName)));
+        .action(util_runCommand.runCommand({ event: observability.Z2hCliEvents.editSuccess, data: ([appName]) => ({ app_name: appName }) }, (appName) => commands_edit.editCommand(appName)));
     program
         .command('grant [email]')
         .description('Grant access to the current app (email, --public, or both)')
@@ -183,7 +183,7 @@ async function main() {
         .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(util_runCommand.runCommand({ data: cwdApp }, (opts) => commands_delete.deleteCommand(opts)));
+        .action(util_runCommand.runCommand({ event: observability.Z2hCliEvents.deleteSuccess, data: cwdApp }, (opts) => commands_delete.deleteCommand(opts)));
     const backend = program
         .command('backend')
         .description("Inspect the app's backend: validate handler sources or run a handler from the working tree");
@@ -214,7 +214,7 @@ async function main() {
     program
         .command('doctor')
         .description('Check that all Z2H tools, auth, workspace, and plugins are correctly set up')
-        .action(util_runCommand.runCommand({ track: false }, () => commands_doctor.doctorCommand()));
+        .action(util_runCommand.runCommand({}, () => commands_doctor.doctorCommand()));
     await program.parseAsync(process.argv);
 }
 void main()

package/dist/types.d.ts

@@ -2,6 +2,7 @@
  * Shared domain types for the Z2H CLI. Command-scoped option types live
  * with their command; narrow single-use types stay local to their file.
  */
+import type { Z2hCliEventName } from '@mondaydotcomorg/z2h-shared-utils/observability';
 export interface ConsumerPkg {
     name: string;
     version?: string;
@@ -60,12 +61,10 @@ export type GrantFailureReason = 'validation' | 'auth' | 'forbidden' | 'not_foun
 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.
+     * Success-event name from `Z2hCliEvents` (a function when it depends on args, e.g. `deploy --preview`).
+     * Omit it to send no success event. Failures are reported either way.
      */
-    track?: PerArgs<A, boolean>;
-    /** Success-event name when it depends on args (e.g. `deploy --preview`); defaults to `successEvent(<command>)`. */
-    event?: PerArgs<A, string>;
+    event?: PerArgs<A, Z2hCliEventName>;
     /** 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. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/util/logger.d.ts

@@ -18,8 +18,8 @@ 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.
+ * `track: false` skips the telemetry event but still prints and exits. runCommand passes it
+ * for failures that aren't a CLI/infra problem (a consumer's own broken build).
  */
 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.js

@@ -51,8 +51,8 @@ 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.
+ * `track: false` skips the telemetry event but still prints and exits. runCommand passes it
+ * for failures that aren't a CLI/infra problem (a consumer's own broken build).
  */
 async function fail(message, payload, exitCode = 1, track = true) {
     // Canonical fields go last so a payload key can never shadow `error`/`action`.

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

@@ -1 +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"}
+{"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;AAKrD;;;;;;;;;;;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,CAwB7C"}

package/dist/util/run-command.js

@@ -4,13 +4,7 @@ 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;
-};
+const pick = (field, args) => 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
@@ -27,20 +21,19 @@ 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));
+        // Top-level commands hang off the root program (`z2h-cli`), which has no parent itself and isn't
+        // part of a command's name. Only a nested command (`backend invoke`) has a non-root parent to prefix.
+        const name = cmd.parent?.parent ? `${cmd.parent.name()} ${cmd.name()}` : cmd.name();
+        const label = spec.label ? pick(spec.label, args) : name;
+        const event = spec.event ? pick(spec.event, args) : null;
         const data = spec.data?.(args) ?? {};
         try {
-            await (track ? util_tracker.trackDuration(event, () => fn(...args), data) : fn(...args));
+            await (event ? 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';
+            // A consumer's own broken build isn't a CLI/infra problem — don't report it at all, not even as `unknown`.
+            const shouldTrack = 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);
         }
     };

package/dist/util/tracker.d.ts

@@ -1,10 +1,2 @@
 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":"AAcA,eAAO,MAAQ,UAAU,kEAAE,aAAa,uFAItC,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/util/tracker.ts"],"names":[],"mappings":"AAcA,eAAO,MAAQ,UAAU,kEAAE,aAAa,uFAItC,CAAC"}

package/dist/util/tracker.js

@@ -19,17 +19,6 @@ const { trackEvent, trackDuration } = observability.createHttpTracker({
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.33.2",
+  "version": "0.33.3-feature-chezki-templates-poc-93101e2",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,6 +25,11 @@
       "require": "./dist/s3.js",
       "types": "./dist/s3.d.ts"
     },
+    "./dashboard-templates": {
+      "import": "./dist/esm/dashboard-templates.mjs",
+      "require": "./dist/dashboard-templates.js",
+      "types": "./dist/dashboard-templates.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "nx": {
@@ -52,7 +57,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.706.0",
     "@mondaydotcomorg/z2h-dashboard-templates": "^0.4.0",
-    "@mondaydotcomorg/z2h-shared-utils": "^0.7.1",
+    "@mondaydotcomorg/z2h-shared-utils": "^0.7.2",
     "acorn": "^8.14.0",
     "acorn-walk": "^8.3.4",
     "chokidar": "^3.6.0",

package/src/backend/parser/parse.ts

@@ -1,5 +1,6 @@
 import { parse, type ExportNamedDeclaration, type ModuleDeclaration, type Program, type Statement } from 'acorn';
 import { z } from 'zod';
+import { Z2hCliEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
 import { trackEvent } from '../../util/tracker';
 import { exportsHandler } from './handler-declaration';
 import { messages } from './messages';
@@ -44,7 +45,7 @@ const isExport = (node: Statement | ModuleDeclaration): node is ExportLike =>
 
 /** Reports the failure, then returns the error for the caller to throw. */
 function parseError(message: string): Error {
-  void trackEvent('z2h_cli_handler_parse_error', { error: message });
+  void trackEvent(Z2hCliEvents.handlerParseError, { error: message });
   return new Error(message);
 }
 

package/src/dashboard-templates.ts

@@ -0,0 +1,5 @@
+export {
+  loadDashboardTemplatesCatalog,
+  findTemplate,
+  type DashboardTemplateEntry,
+} from './util/dashboard-templates/load-catalog';

package/src/index.ts

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { Command } from 'commander';
 import { execa } from 'execa';
+import { Z2hCliEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
 import { getWorkspaceHome } from './util/workspace';
 import { buildCommand } from './commands/build';
 import { cleanCommand } from './commands/clean';
@@ -23,7 +24,6 @@ import { backendInvokeCommand, backendValidateCommand } from './commands/backend
 import { doctorCommand } from './commands/doctor';
 import { errorLog, fail, getOutputMode, setOutputMode } from './util/logger';
 import { runCommand } from './util/run-command';
-import { successEvent } from './util/tracker';
 import { getCwdAppName } from './util/app-name';
 
 const { version } = createRequire(import.meta.url)('@mondaydotcomorg/z2h-cli/package.json') as { version: string };
@@ -104,15 +104,15 @@ async function main(): Promise<void> {
   program
     .command('build')
     .description('Build the consumer into its .zth/ shadow and copy artifacts to ./build/')
-    // 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()));
+    // A standalone build failure is the consumer's own code, not a CLI/infra problem — runCommand
+    // skips the error event for failures tagged `build_error` (buildCommand tags it on its thrown
+    // error). Any other failure here is still reported.
+    .action(runCommand({ event: Z2hCliEvents.buildSuccess, data: cwdApp, exitCode: 2 }, () => buildCommand()));
 
   program
     .command('clean')
     .description('Delete <consumer>/.zth/ and <consumer>/build/')
-    .action(runCommand({ track: false, exitCode: 2 }, () => cleanCommand()));
+    .action(runCommand({ exitCode: 2 }, () => cleanCommand()));
 
   program
     .command('deploy')
@@ -139,9 +139,8 @@ async function main(): Promise<void> {
     .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]: [DeployCliOptions]) => successEvent(opts.preview ? 'preview' : 'deploy'),
+          event: ([opts]: [DeployCliOptions]) =>
+            opts.preview ? Z2hCliEvents.previewSuccess : Z2hCliEvents.deploySuccess,
           label: ([opts]: [DeployCliOptions]) => (opts.preview ? 'preview' : 'deploy'),
           data: cwdApp,
           exitCode: 2,
@@ -166,7 +165,7 @@ async function main(): Promise<void> {
   program
     .command('create-workspace')
     .description(`Bootstrap the ${getWorkspaceHome()}/ yarn workspace (one-time setup)`)
-    .action(runCommand({ track: false }, () => createWorkspaceCommand()));
+    .action(runCommand({}, () => createWorkspaceCommand()));
 
   program
     .command('generate-z2h-token')
@@ -192,6 +191,7 @@ async function main(): Promise<void> {
     .action(
       runCommand(
         {
+          event: Z2hCliEvents.createSuccess,
           data: ([appName, opts]: [string, CreateCliOptions]) => ({
             app_name: appName,
             template: opts.template ?? 'default',
@@ -205,9 +205,9 @@ async function main(): Promise<void> {
   program
     .command('templates')
     .description(
-      "List the BigBrain Studio (Z2H) template catalog — id, title, description, and each template's widget schema"
+      "List the BigBrain Studio (Z2H) template catalog — id, title, description, and each template's config schema"
     )
-    .action(runCommand({}, () => templatesCommand()));
+    .action(runCommand({ event: Z2hCliEvents.templatesSuccess }, () => templatesCommand()));
 
   program
     .command('generate-app-template <app-name>')
@@ -222,6 +222,7 @@ async function main(): Promise<void> {
     .action(
       runCommand(
         {
+          event: Z2hCliEvents.generateAppTemplateSuccess,
           data: ([appName, opts]: [string, GenerateOptions]) => ({ app_name: appName, template: opts.template }),
         },
         (appName: string, opts: GenerateOptions) => generateCommand(appName, opts)
@@ -232,7 +233,10 @@ async function main(): Promise<void> {
     .command('edit <app-name>')
     .description(`Pull the latest version of an app into ${getWorkspaceHome()}/<app-name>, cloning it first if needed`)
     .action(
-      runCommand({ data: ([appName]: [string]) => ({ app_name: appName }) }, (appName: string) => editCommand(appName))
+      runCommand(
+        { event: Z2hCliEvents.editSuccess, data: ([appName]: [string]) => ({ app_name: appName }) },
+        (appName: string) => editCommand(appName)
+      )
     );
 
   program
@@ -275,7 +279,9 @@ async function main(): Promise<void> {
     .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(runCommand({ data: cwdApp }, (opts: { yes?: boolean }) => deleteCommand(opts)));
+    .action(
+      runCommand({ event: Z2hCliEvents.deleteSuccess, data: cwdApp }, (opts: { yes?: boolean }) => deleteCommand(opts))
+    );
 
   const backend = program
     .command('backend')
@@ -324,7 +330,7 @@ async function main(): Promise<void> {
   program
     .command('doctor')
     .description('Check that all Z2H tools, auth, workspace, and plugins are correctly set up')
-    .action(runCommand({ track: false }, () => doctorCommand()));
+    .action(runCommand({}, () => doctorCommand()));
 
   await program.parseAsync(process.argv);
 }

package/src/types.ts

@@ -2,6 +2,7 @@
  * Shared domain types for the Z2H CLI. Command-scoped option types live
  * with their command; narrow single-use types stay local to their file.
  */
+import type { Z2hCliEventName } from '@mondaydotcomorg/z2h-shared-utils/observability';
 
 // ─────────── Consumer pkg management ───────────
 export interface ConsumerPkg {
@@ -96,12 +97,10 @@ 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.
+   * Success-event name from `Z2hCliEvents` (a function when it depends on args, e.g. `deploy --preview`).
+   * Omit it to send no success event. Failures are reported either way.
    */
-  track?: PerArgs<A, boolean>;
-  /** Success-event name when it depends on args (e.g. `deploy --preview`); defaults to `successEvent(<command>)`. */
-  event?: PerArgs<A, string>;
+  event?: PerArgs<A, Z2hCliEventName>;
   /** 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. */

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

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { Command } from 'commander';
+import { Z2hCliEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
 import { runCommand } from '../run-command';
 import { DeployError } from '../errors';
 import { setOutputMode } from '../logger';
@@ -8,12 +9,12 @@ import { trackEvent, trackDuration } from '../tracker';
 vi.mock('../tracker', () => ({
   trackEvent: vi.fn().mockResolvedValue(undefined),
   trackDuration: vi.fn((_name: string, fn: () => Promise<unknown>) => fn()),
-  successEvent: (command: string) => `z2h_cli_${command.replace(/[\s-]+/g, '_')}_success`,
 }));
 
 describe('runCommand: build_error is never reported, other reasons still are', () => {
   afterEach(() => {
     vi.mocked(trackEvent).mockClear();
+    vi.mocked(trackDuration).mockClear();
     setOutputMode('human');
   });
 
@@ -23,7 +24,7 @@ describe('runCommand: build_error is never reported, other reasons still are', (
       throw new Error('__exit__');
     });
     vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-    const handler = runCommand({}, () => {
+    const handler = runCommand({ event: Z2hCliEvents.deploySuccess }, () => {
       throw err;
     });
     await expect(handler(cmd)).rejects.toThrow('__exit__');
@@ -49,24 +50,44 @@ describe('runCommand: naming/tracking convention', () => {
     setOutputMode('human');
   });
 
-  it('derives its name (and label) from the Command instance, no name param needed', async () => {
-    const cmd = new Command('migrate');
-    const handler = runCommand({}, () => Promise.resolve('ok'));
-    await handler(cmd);
-    expect(trackDuration).toHaveBeenCalledWith('z2h_cli_migrate_success', expect.any(Function), {});
+  // index.ts hangs every command off a root program named `z2h-cli`.
+  const program = new Command().name('z2h-cli');
+  const failWith = async (cmd: Command) => {
+    vi.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('__exit__');
+    });
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    await expect(
+      runCommand({ event: Z2hCliEvents.createSuccess }, () => {
+        throw new Error('boom');
+      })(cmd)
+    ).rejects.toThrow('__exit__');
+    vi.mocked(process.exit).mockRestore();
+    vi.mocked(process.stderr.write).mockRestore();
+  };
+
+  it('names a top-level command without the root program', async () => {
+    await failWith(program.command('create'));
+    expect(trackEvent).toHaveBeenCalledWith(
+      Z2hCliEvents.error,
+      expect.objectContaining({ action: 'create', error: 'create failed: boom' })
+    );
   });
 
   it('composes a nested command\'s name from its parent, e.g. "backend invoke"', async () => {
-    const backend = new Command('backend');
-    const invoke = backend.command('invoke');
-    const handler = runCommand({}, () => Promise.resolve('ok'));
-    await handler(invoke);
-    expect(trackDuration).toHaveBeenCalledWith('z2h_cli_backend_invoke_success', expect.any(Function), {});
+    await failWith(program.command('backend').command('invoke'));
+    expect(trackEvent).toHaveBeenCalledWith(Z2hCliEvents.error, expect.objectContaining({ action: 'backend invoke' }));
   });
 
-  it('track: false skips telemetry entirely, success or failure', async () => {
+  it('sends the given event when tracked', async () => {
+    const cmd = new Command('create');
+    await runCommand({ event: Z2hCliEvents.createSuccess }, () => Promise.resolve('ok'))(cmd);
+    expect(trackDuration).toHaveBeenCalledWith('z2h_app_created', expect.any(Function), {});
+  });
+
+  it('the success event is opt-in, but failures are reported either way', async () => {
     const cmd = new Command('doctor');
-    await runCommand({ track: false }, () => Promise.resolve('ok'))(cmd);
+    await runCommand({}, () => Promise.resolve('ok'))(cmd);
     expect(trackDuration).not.toHaveBeenCalled();
     expect(trackEvent).not.toHaveBeenCalled();
 
@@ -74,25 +95,25 @@ describe('runCommand: naming/tracking convention', () => {
       throw new Error('__exit__');
     });
     vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-    const failing = runCommand({ track: false }, () => {
+    const failing = runCommand({}, () => {
       throw new Error('boom');
     });
     await expect(failing(cmd)).rejects.toThrow('__exit__');
-    expect(trackEvent).not.toHaveBeenCalled();
+    expect(trackEvent).toHaveBeenCalledWith(Z2hCliEvents.error, expect.objectContaining({ action: 'doctor' }));
     exit.mockRestore();
     vi.mocked(process.stderr.write).mockRestore();
   });
 
-  it('a per-args event override beats the derived name, e.g. deploy --preview', async () => {
+  it('a per-args event picks the name, e.g. deploy --preview', async () => {
     const cmd = new Command('deploy');
     const handler = runCommand(
       {
         event: ([opts]: [{ preview?: boolean }]) =>
-          opts.preview ? 'z2h_cli_preview_success' : 'z2h_cli_deploy_success',
+          opts.preview ? Z2hCliEvents.previewSuccess : Z2hCliEvents.deploySuccess,
       },
       (_opts: { preview?: boolean }) => Promise.resolve('ok')
     );
     await handler({ preview: true }, cmd);
-    expect(trackDuration).toHaveBeenCalledWith('z2h_cli_preview_success', expect.any(Function), {});
+    expect(trackDuration).toHaveBeenCalledWith('z2h_app_preview_success', expect.any(Function), {});
   });
 });

package/src/util/logger.ts

@@ -53,8 +53,8 @@ export 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.
+ * `track: false` skips the telemetry event but still prints and exits. runCommand passes it
+ * for failures that aren't a CLI/infra problem (a consumer's own broken build).
  */
 export async function fail(
   message: string,

package/src/util/run-command.ts

@@ -1,20 +1,11 @@
 import { fail } from './logger';
-import { trackDuration, successEvent } from './tracker';
+import { trackDuration } from './tracker';
 import { Z2hError, reasonOf, dataOf, messageOf } from './errors';
 import type { Command } from 'commander';
 import type { CommandSpec, PerArgs } from '../types';
 
-type SpecFieldFn<A extends unknown[], T> = (args: A) => T;
-type SpecFieldResolver<A extends unknown[]> = <T>(field: PerArgs<A, T> | undefined, fallback: T) => T;
-type ResolveSpecField = <A extends unknown[], T>(field: PerArgs<A, T> | undefined, args: A, fallback: T) => T;
-
-/** A spec field is a constant, a callback over the args, or absent — in which case `fallback` applies. */
-const resolveSpecField: ResolveSpecField = (field, args, fallback) => {
-  if (field === undefined) {
-    return fallback;
-  }
-  return typeof field === 'function' ? (field as SpecFieldFn<typeof args, typeof fallback>)(args) : field;
-};
+const pick = <A extends unknown[], T>(field: PerArgs<A, T>, args: A): T =>
+  typeof field === 'function' ? (field as (args: A) => T)(args) : field;
 
 /**
  * Wraps a command body with the whole telemetry and failure contract so no command
@@ -35,19 +26,18 @@ export function runCommand<A extends unknown[]>(
   return async (...allArgs: [...A, Command]): Promise<void> => {
     const cmd = allArgs[allArgs.length - 1] as Command;
     const args = allArgs.slice(0, -1) as A;
-    const name = cmd.parent ? `${cmd.parent.name()} ${cmd.name()}` : cmd.name();
-    const resolve: SpecFieldResolver<A> = (v, fallback) => resolveSpecField(v, args, fallback);
-    const track = resolve(spec.track, true);
-    const label = resolve(spec.label, name);
-    const event = resolve(spec.event, successEvent(name));
+    // Top-level commands hang off the root program (`z2h-cli`), which has no parent itself and isn't
+    // part of a command's name. Only a nested command (`backend invoke`) has a non-root parent to prefix.
+    const name = cmd.parent?.parent ? `${cmd.parent.name()} ${cmd.name()}` : cmd.name();
+    const label = spec.label ? pick(spec.label, args) : name;
+    const event = spec.event ? pick(spec.event, args) : null;
     const data = spec.data?.(args) ?? {};
     try {
-      await (track ? trackDuration(event, () => fn(...args), data) : fn(...args));
+      await (event ? trackDuration(event, () => fn(...args), data) : fn(...args));
     } catch (err) {
       const reason = 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';
+      // A consumer's own broken build isn't a CLI/infra problem — don't report it at all, not even as `unknown`.
+      const shouldTrack = reason !== 'build_error';
       await fail(
         `${label} failed: ${messageOf(err)}`,
         { command: label, reason, ...data, ...dataOf(err) },

package/src/util/tracker.ts

@@ -17,14 +17,3 @@ export const { trackEvent, trackDuration } = createHttpTracker({
   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.
- */
-export function successEvent(command: string): string {
-  return `z2h_cli_${command.replace(/[\s-]+/g, '_')}_success`;
-}