at-builder 1.4.4 → 1.5.0

package/README.md

@@ -270,6 +270,44 @@ console.log(getHelpInfo());
 
 ---
 
+## **🔒 Telemetry & Privacy**
+
+`atb` sends anonymous usage telemetry to help improve the tool. The following is collected on each command invocation:
+
+- **User**: git `user.email`, git `user.name`, OS username (read from your local environment)
+- **Project**: project folder name, absolute project path, `ADOBE_TENANT` (if set)
+- **Command**: command name and sanitized arguments (values for any arg containing `secret` / `token` / `key` / `password` are redacted)
+- **Execution**: status (`started` / `success` / `failed`), duration, error message
+- **System**: platform, Node.js version, CLI version
+- **Identifier**: a persistent random `clientId` stored at `~/.atb-builder/client_id`
+
+Events are appended to a local log at `~/.atb-builder/telemetry.jsonl` and sent to Google Analytics 4. Every event has a 500–800 ms timeout, so telemetry never blocks CLI execution.
+
+### How to disable
+
+Set either of these to `false`:
+
+```bash
+# In your project .env
+TELEMETRY_ENABLED=false
+
+# Or as a shell environment variable
+export TELEMETRY_ENABLED=false
+```
+
+### Redirect to your own endpoint
+
+To collect telemetry to your own server instead of (or in addition to) the default GA4 destination:
+
+```bash
+TELEMETRY_URL="https://your-endpoint.example.com/events"
+TELEMETRY_USER="custom-user-id"          # override the identifier
+GA_MEASUREMENT_ID="G-XXXXXXX"             # override GA4 destination
+GA_API_SECRET="your-api-secret"
+```
+
+---
+
 ## **📄 License**
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/bin/constants/config.js

@@ -119,7 +119,7 @@ var setupEnv = function (basePath) { return __awaiter(void 0, void 0, void 0, fu
         envPath = path_1.default.join(basePath, '.env');
         // Check if the .env file exists
         if (!fs_1.default.existsSync(envPath)) {
-            envContent = "\nACTIVITIES_BASE_FOLDER=\"Activities\"\nACTIVITY_FOLDER_NAME=\"\"\nPUPPETEER_LANDING_PAGE=\"\"\nTARGET_URL=\"\"\nLOGIN_URL=\"\"\n\n# Dev-server selection (used by `atb dev --browser`).\n# Edit and save while puppeteer is running to hot-swap the previewed bundle.\n# PAGE is only meaningful for multi-page activities \u2014 leave empty otherwise.\nVARIATION=\"Variation-1\"\nPAGE=\"\"\n\nNODE_ENV=\"development\"\nVERBOSE=false\n\n# Build wrapper config.\n# TARGET_BUILD_PREFIX customizes the window flag baked into each build \u2014\n# rendered as window.${TARGET_BUILD_PREFIX}_${contentHash}_${hash}. Defaults\n# to \"TargetBuild\" when empty. Useful when multiple at-builder activities\n# end up loaded on the same page and you want each project's flag namespaced.\nTARGET_BUILD_PREFIX=\"\"\n\n# Adobe Target Deployment Configuration\n# ADOBE_TENANT is your AT tenant slug \u2014 find it in the AT URL after \"mc.adobe.io/\".\nADOBE_TENANT=\"\"\nADOBE_CLIENT_ID=\"\"\nADOBE_CLIENT_SECRET=\"\"\n    ";
+            envContent = "\nACTIVITIES_BASE_FOLDER=\"Activities\"\nACTIVITY_FOLDER_NAME=\"\"\nPUPPETEER_LANDING_PAGE=\"\"\nTARGET_URL=\"\"\nLOGIN_URL=\"\"\n\n# Dev-server selection (used by `atb dev --browser`).\n# Edit and save while puppeteer is running to hot-swap the previewed bundle.\n# PAGE is only meaningful for multi-page activities \u2014 leave empty otherwise.\nVARIATION=\"Variation-1\"\nPAGE=\"\"\n\nNODE_ENV=\"development\"\nVERBOSE=false\n\n# Build wrapper config.\n# TARGET_BUILD_PREFIX customizes the window flag baked into each build \u2014\n# rendered as window.${TARGET_BUILD_PREFIX}_${contentHash}_${hash}. Defaults\n# to \"TargetBuild\" when empty. Useful when multiple at-builder activities\n# end up loaded on the same page and you want each project's flag namespaced.\nTARGET_BUILD_PREFIX=\"\"\n\n# Adobe Target Deployment Configuration\n# ADOBE_TENANT is your AT tenant slug \u2014 find it in the AT URL after \"mc.adobe.io/\".\nADOBE_TENANT=\"\"\nADOBE_CLIENT_ID=\"\"\nADOBE_CLIENT_SECRET=\"\"\n\n# Telemetry / Usage Tracking\n# Set to false to disable CLI usage tracking\nTELEMETRY_ENABLED=true\n# Set to your analytics backend URL to POST telemetry events\nTELEMETRY_URL=\"\"\n# Google Analytics 4 configuration (falls back to hardcoded project values)\nGA_MEASUREMENT_ID=\"\"\nGA_API_SECRET=\"\"\n    ";
             // Write the content to the .env file
             fs_1.default.writeFileSync(envPath, envContent.trim(), 'utf8');
             console.log('.env file created successfully!');

package/bin/index.js

@@ -67,6 +67,7 @@ var commander_1 = require("commander");
 var config_1 = require("./constants/config");
 var doctor_1 = require("./services/doctor");
 var logger_1 = __importDefault(require("./services/logger"));
+var telemetry_1 = require("./services/telemetry");
 /**
  * Checks if the .env file exists at the current working directory
  *
@@ -89,6 +90,46 @@ var checkEnvFile = function () {
 };
 // Prepare environment for spawning processes
 var productionEnv = __assign(__assign({}, process.env), { executionPath: process.cwd() });
+/**
+ * Helper utility to wrap Commander subcommand actions with telemetry logging.
+ *
+ * Automatically tracks when a command starts, succeeds, or fails with an error.
+ */
+var wrapAction = function (commandName, actionFn) {
+    return function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return __awaiter(void 0, void 0, void 0, function () {
+            var error_1;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, (0, telemetry_1.trackTelemetry)(commandName, "started")];
+                    case 1:
+                        _a.sent();
+                        _a.label = 2;
+                    case 2:
+                        _a.trys.push([2, 5, , 7]);
+                        return [4 /*yield*/, actionFn.apply(void 0, args)];
+                    case 3:
+                        _a.sent();
+                        return [4 /*yield*/, (0, telemetry_1.trackTelemetry)(commandName, "success")];
+                    case 4:
+                        _a.sent();
+                        return [3 /*break*/, 7];
+                    case 5:
+                        error_1 = _a.sent();
+                        return [4 /*yield*/, (0, telemetry_1.trackTelemetry)(commandName, "failed", error_1 instanceof Error ? error_1 : new Error(String(error_1)))];
+                    case 6:
+                        _a.sent();
+                        throw error_1;
+                    case 7: return [2 /*return*/];
+                }
+            });
+        });
+    };
+};
 // Commander setup with proper subcommands
 var setupCommander = function () { return __awaiter(void 0, void 0, void 0, function () {
     var version, program;
@@ -109,7 +150,7 @@ var setupCommander = function () { return __awaiter(void 0, void 0, void 0, func
                 program
                     .command('init')
                     .description('Initialize project with .env configuration and templates')
-                    .action(function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
+                    .action(wrapAction('init', function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
                     var globalOpts;
                     return __generator(this, function (_a) {
                         switch (_a.label) {
@@ -121,11 +162,11 @@ var setupCommander = function () { return __awaiter(void 0, void 0, void 0, func
                                 return [2 /*return*/];
                         }
                     });
-                }); });
+                }); }));
                 program
                     .command('new')
                     .description('Create a new Adobe Target activity with variations')
-                    .action(function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
+                    .action(wrapAction('new', function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
                     var globalOpts;
                     return __generator(this, function (_a) {
                         switch (_a.label) {
@@ -137,12 +178,12 @@ var setupCommander = function () { return __awaiter(void 0, void 0, void 0, func
                                 return [2 /*return*/];
                         }
                     });
-                }); });
+                }); }));
                 program
                     .command('build')
                     .description('Build activity for development or production')
                     .option('--prod', 'Build for production deployment')
-                    .action(function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
+                    .action(wrapAction('build', function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
                     var globalOpts;
                     return __generator(this, function (_a) {
                         switch (_a.label) {
@@ -155,12 +196,12 @@ var setupCommander = function () { return __awaiter(void 0, void 0, void 0, func
                                 return [2 /*return*/];
                         }
                     });
-                }); });
+                }); }));
                 program
                     .command('dev')
                     .description('Start development server with file watching')
                     .option('--browser', 'Open in browser automatically')
-                    .action(function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
+                    .action(wrapAction('dev', function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
                     var globalOpts;
                     return __generator(this, function (_a) {
                         switch (_a.label) {
@@ -173,13 +214,13 @@ var setupCommander = function () { return __awaiter(void 0, void 0, void 0, func
                                 return [2 /*return*/];
                         }
                     });
-                }); });
+                }); }));
                 program
                     .command('deploy')
                     .description('Deploy activity to Adobe Target using at-deploy.js')
                     .option('--dry-run', 'Run deployment in dry-run mode without actual deployment')
                     .option('--force', 'Override the 60s post-deploy cooldown lock')
-                    .action(function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
+                    .action(wrapAction('deploy', function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
                     var globalOpts;
                     return __generator(this, function (_a) {
                         switch (_a.label) {
@@ -192,12 +233,12 @@ var setupCommander = function () { return __awaiter(void 0, void 0, void 0, func
                                 return [2 /*return*/];
                         }
                     });
-                }); });
+                }); }));
                 program
                     .command('sync')
                     .description('Sync build.config.json with the Adobe Target activity definition')
                     .option('--scaffold', 'Auto-create missing variation folders with boilerplate')
-                    .action(function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
+                    .action(wrapAction('sync', function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
                     var globalOpts;
                     return __generator(this, function (_a) {
                         switch (_a.label) {
@@ -210,12 +251,12 @@ var setupCommander = function () { return __awaiter(void 0, void 0, void 0, func
                                 return [2 /*return*/];
                         }
                     });
-                }); });
+                }); }));
                 program
                     .command('doctor')
                     .description('Diagnose and fix project configuration issues')
                     .option('--fix', 'Automatically fix detected issues')
-                    .action(function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
+                    .action(wrapAction('doctor', function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
                     var globalOpts;
                     return __generator(this, function (_a) {
                         switch (_a.label) {
@@ -227,12 +268,12 @@ var setupCommander = function () { return __awaiter(void 0, void 0, void 0, func
                                 return [2 /*return*/];
                         }
                     });
-                }); });
+                }); }));
                 program
                     .command('install-extension')
                     .description('Install the at-builder VSCode extension from the Marketplace')
                     .option('--editor <bin>', 'Editor CLI to use (e.g. code, agy, cursor, codium)', 'code')
-                    .action(function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
+                    .action(wrapAction('install-extension', function (options, command) { return __awaiter(void 0, void 0, void 0, function () {
                     var globalOpts;
                     return __generator(this, function (_a) {
                         switch (_a.label) {
@@ -244,7 +285,7 @@ var setupCommander = function () { return __awaiter(void 0, void 0, void 0, func
                                 return [2 /*return*/];
                         }
                     });
-                }); });
+                }); }));
                 return [4 /*yield*/, program.parseAsync(process.argv)];
             case 2:
                 _a.sent();
@@ -259,6 +300,11 @@ var setupCommander = function () { return __awaiter(void 0, void 0, void 0, func
  * Any entries in `scriptArgs` are forwarded to the underlying script via npm's
  * `--` passthrough (e.g. `npm run foo -- --dry-run`).
  *
+ * Returns a Promise that resolves when the child process exits successfully,
+ * or rejects with an Error when it exits with a non-zero code. This allows
+ * callers (and the telemetry wrapAction) to accurately capture success/failure
+ * and measure real execution duration.
+ *
  * @param commandArr - The array of command strings to pass to `npm`.
  * @param env - The environment object to pass to the spawned process.
  * @param scriptArgs - Optional flags/args to forward to the npm script itself.
@@ -269,11 +315,25 @@ var runCommand = function (commandArr, env, scriptArgs) {
         ? __spreadArray(__spreadArray(__spreadArray([], commandArr, true), ["--"], false), scriptArgs, true) : commandArr;
     logger_1.default.info("runCommand", "Running npm command [".concat(fullArgs.join(", "), "]"));
     logger_1.default.info("runCommand", "Current working directory: ".concat(process.cwd()));
-    (0, child_process_1.spawn)("npm", fullArgs, {
-        cwd: path_1.default.join(__dirname, "../"),
-        env: env,
-        shell: true,
-        stdio: "inherit",
+    return new Promise(function (resolve, reject) {
+        var child = (0, child_process_1.spawn)("npm", fullArgs, {
+            cwd: path_1.default.join(__dirname, "../"),
+            env: env,
+            shell: true,
+            stdio: "inherit",
+        });
+        child.on("error", function (err) {
+            logger_1.default.error("runCommand", "Spawn error: ".concat(err.message));
+            reject(err);
+        });
+        child.on("exit", function (code) {
+            if (code === 0 || code === null) {
+                resolve();
+            }
+            else {
+                reject(new Error("Command [".concat(fullArgs.join(" "), "] exited with code ").concat(code)));
+            }
+        });
     });
 };
 /**
@@ -306,10 +366,15 @@ var handleInit = function (verbose) { return __awaiter(void 0, void 0, void 0, f
  */
 var handleNew = function (verbose) { return __awaiter(void 0, void 0, void 0, function () {
     return __generator(this, function (_a) {
-        if (verbose)
-            logger_1.default.info("verbose", "Creating new activity");
-        runCommand(["run", "atb:plop:new:activity"], productionEnv);
-        return [2 /*return*/];
+        switch (_a.label) {
+            case 0:
+                if (verbose)
+                    logger_1.default.info("verbose", "Creating new activity");
+                return [4 /*yield*/, runCommand(["run", "atb:plop:new:activity"], productionEnv)];
+            case 1:
+                _a.sent();
+                return [2 /*return*/];
+        }
     });
 }); };
 /**
@@ -317,18 +382,25 @@ var handleNew = function (verbose) { return __awaiter(void 0, void 0, void 0, fu
  */
 var handleBuild = function (prod, verbose) { return __awaiter(void 0, void 0, void 0, function () {
     return __generator(this, function (_a) {
-        if (verbose)
-            logger_1.default.info("verbose", "Building in ".concat(prod ? 'production' : 'development', " mode"));
-        if (prod) {
-            process.env['NODE_ENV'] = 'production';
-            logger_1.default.info("handleBuild", "Running build with production environment");
-            runCommand(['run', 'atb:build:prod'], productionEnv);
-        }
-        else {
-            logger_1.default.info("handleBuild", "Running build with development environment");
-            runCommand(['run', 'atb:build:dev'], productionEnv);
+        switch (_a.label) {
+            case 0:
+                if (verbose)
+                    logger_1.default.info("verbose", "Building in ".concat(prod ? 'production' : 'development', " mode"));
+                if (!prod) return [3 /*break*/, 2];
+                process.env['NODE_ENV'] = 'production';
+                logger_1.default.info("handleBuild", "Running build with production environment");
+                return [4 /*yield*/, runCommand(['run', 'atb:build:prod'], productionEnv)];
+            case 1:
+                _a.sent();
+                return [3 /*break*/, 4];
+            case 2:
+                logger_1.default.info("handleBuild", "Running build with development environment");
+                return [4 /*yield*/, runCommand(['run', 'atb:build:dev'], productionEnv)];
+            case 3:
+                _a.sent();
+                _a.label = 4;
+            case 4: return [2 /*return*/];
         }
-        return [2 /*return*/];
     });
 }); };
 /**
@@ -337,12 +409,17 @@ var handleBuild = function (prod, verbose) { return __awaiter(void 0, void 0, vo
 var handleDev = function (browser, verbose) { return __awaiter(void 0, void 0, void 0, function () {
     var commandArr;
     return __generator(this, function (_a) {
-        if (verbose)
-            logger_1.default.info("verbose", "Starting development server with browser=".concat(browser));
-        commandArr = ['run', browser ? 'atb:build:dev:puppeteer' : 'atb:build:dev'];
-        logger_1.default.info("handleDev", "Running command: ".concat(commandArr.join(', ')));
-        runCommand(commandArr, productionEnv);
-        return [2 /*return*/];
+        switch (_a.label) {
+            case 0:
+                if (verbose)
+                    logger_1.default.info("verbose", "Starting development server with browser=".concat(browser));
+                commandArr = ['run', browser ? 'atb:build:dev:puppeteer' : 'atb:build:dev'];
+                logger_1.default.info("handleDev", "Running command: ".concat(commandArr.join(', ')));
+                return [4 /*yield*/, runCommand(commandArr, productionEnv)];
+            case 1:
+                _a.sent();
+                return [2 /*return*/];
+        }
     });
 }); };
 /**
@@ -351,16 +428,21 @@ var handleDev = function (browser, verbose) { return __awaiter(void 0, void 0, v
 var handleDeploy = function (dryRun, force, verbose) { return __awaiter(void 0, void 0, void 0, function () {
     var scriptArgs;
     return __generator(this, function (_a) {
-        if (verbose)
-            logger_1.default.info("verbose", "Deploying to Adobe Target with dry-run=".concat(dryRun, " force=").concat(force));
-        logger_1.default.info("handleDeploy", "Running Adobe Target deployment");
-        scriptArgs = [];
-        if (dryRun)
-            scriptArgs.push('--dry-run');
-        if (force)
-            scriptArgs.push('--force');
-        runCommand(['run', 'atb:build:deploy'], productionEnv, scriptArgs);
-        return [2 /*return*/];
+        switch (_a.label) {
+            case 0:
+                if (verbose)
+                    logger_1.default.info("verbose", "Deploying to Adobe Target with dry-run=".concat(dryRun, " force=").concat(force));
+                logger_1.default.info("handleDeploy", "Running Adobe Target deployment");
+                scriptArgs = [];
+                if (dryRun)
+                    scriptArgs.push('--dry-run');
+                if (force)
+                    scriptArgs.push('--force');
+                return [4 /*yield*/, runCommand(['run', 'atb:build:deploy'], productionEnv, scriptArgs)];
+            case 1:
+                _a.sent();
+                return [2 /*return*/];
+        }
     });
 }); };
 /**
@@ -369,14 +451,19 @@ var handleDeploy = function (dryRun, force, verbose) { return __awaiter(void 0,
 var handleSync = function (scaffold, verbose) { return __awaiter(void 0, void 0, void 0, function () {
     var scriptArgs;
     return __generator(this, function (_a) {
-        if (verbose)
-            logger_1.default.info("verbose", "Syncing build.config.json with scaffold=".concat(scaffold));
-        logger_1.default.info("handleSync", "Running Adobe Target sync");
-        scriptArgs = [];
-        if (scaffold)
-            scriptArgs.push('--scaffold');
-        runCommand(['run', 'atb:build:sync'], productionEnv, scriptArgs);
-        return [2 /*return*/];
+        switch (_a.label) {
+            case 0:
+                if (verbose)
+                    logger_1.default.info("verbose", "Syncing build.config.json with scaffold=".concat(scaffold));
+                logger_1.default.info("handleSync", "Running Adobe Target sync");
+                scriptArgs = [];
+                if (scaffold)
+                    scriptArgs.push('--scaffold');
+                return [4 /*yield*/, runCommand(['run', 'atb:build:sync'], productionEnv, scriptArgs)];
+            case 1:
+                _a.sent();
+                return [2 /*return*/];
+        }
     });
 }); };
 /**
@@ -444,7 +531,7 @@ var handleInstallExtension = function (editor, verbose) { return __awaiter(void
  * Handles the doctor command
  */
 var handleDoctor = function (autoFix, verbose) { return __awaiter(void 0, void 0, void 0, function () {
-    var issues, fixed, error_1;
+    var issues, fixed, error_2;
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
@@ -484,8 +571,8 @@ var handleDoctor = function (autoFix, verbose) { return __awaiter(void 0, void 0
                 _a.label = 5;
             case 5: return [3 /*break*/, 7];
             case 6:
-                error_1 = _a.sent();
-                logger_1.default.error("handleDoctor", "Doctor command failed: ".concat(error_1.message));
+                error_2 = _a.sent();
+                logger_1.default.error("handleDoctor", "Doctor command failed: ".concat(error_2.message));
                 process.exit(1);
                 return [3 /*break*/, 7];
             case 7: return [2 /*return*/];
@@ -527,7 +614,7 @@ var printCommandHelp = function () { return __awaiter(void 0, void 0, void 0, fu
  * Main program flow
  */
 var main = function () { return __awaiter(void 0, void 0, void 0, function () {
-    var error_2;
+    var error_3;
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
@@ -537,8 +624,8 @@ var main = function () { return __awaiter(void 0, void 0, void 0, function () {
                 _a.sent();
                 return [3 /*break*/, 3];
             case 2:
-                error_2 = _a.sent();
-                logger_1.default.error("main", error_2.message);
+                error_3 = _a.sent();
+                logger_1.default.error("main", error_3.message);
                 process.exit(1);
                 return [3 /*break*/, 3];
             case 3: return [2 /*return*/];