at-builder 1.2.9 → 1.4.0

package/puppeteer.js

@@ -4,15 +4,93 @@ import path from 'path';
 import puppeteer from 'puppeteer';
 import fs from 'fs';
 import chokidar from 'chokidar';
+
 const executionPath = process.env.executionPath || process.cwd();
-dotenv.config({ path: path.join(executionPath, ".env") });
+const envPath = path.join(executionPath, ".env");
+dotenv.config({ path: envPath });
+
+// Honor consumer's ACTIVITIES_BASE_FOLDER (falls back to "Activities" to
+// match webpack/at-deploy/at-sync/plop). Hardcoding it here previously caused
+// `atb dev --browser` to silently read from the wrong path when users
+// customized this in their .env.
+const ACTIVITIES_BASE_FOLDER = process.env.ACTIVITIES_BASE_FOLDER || "Activities";
+
+// Legacy watch-config.json path. Kept as a fallback source for VARIATION/PAGE
+// so existing projects keep working. New projects (atb init) only get .env;
+// `atb doctor --fix` migrates any existing watch-config.json into .env.
+const watchConfig = path.join(executionPath, "watch-config.json");
+
+let legacyWarningShown = false;
+
+/**
+ * Resolve the active dev-server selection (VARIATION + PAGE).
+ *
+ * Precedence:
+ *   1. watch-config.json (if it exists) — preserves existing user behavior
+ *      where this file was the canonical override. A one-time deprecation
+ *      warning nudges the user to migrate via `atb doctor --fix`.
+ *   2. process.env (loaded from .env) — the new canonical source.
+ *
+ * Returns { VARIATION, PAGE } as plain strings (PAGE may be empty for
+ * single-page activities).
+ */
+function readDevSelection() {
+    if (fs.existsSync(watchConfig)) {
+        try {
+            const cfg = JSON.parse(fs.readFileSync(watchConfig, 'utf-8'));
+            if (!legacyWarningShown) {
+                console.warn(
+                    '\x1b[33m⚠️  watch-config.json is deprecated — VARIATION/PAGE now live in .env.\x1b[0m\n' +
+                    '\x1b[33m   Run "atb doctor --fix" to migrate values into .env and remove this file.\x1b[0m'
+                );
+                legacyWarningShown = true;
+            }
+            return {
+                VARIATION: cfg.VARIATION || process.env.VARIATION || '',
+                PAGE: (cfg.PAGE || process.env.PAGE || '').trim()
+            };
+        } catch (err) {
+            console.error(`Failed to read watch-config.json (${err.message}); falling back to .env.`);
+        }
+    }
+    return {
+        VARIATION: process.env.VARIATION || '',
+        PAGE: (process.env.PAGE || '').trim()
+    };
+}
 
-let watchConfig = '';
-try {
-    watchConfig = path.join(executionPath, "watch-config.json");
+/**
+ * Compose the dist folder for the currently-selected variation, page-aware.
+ *
+ *   Single-page (PAGE empty/missing): <Activities>/<activity>/<VARIATION>/dist
+ *   Multi-page  (PAGE set):           <Activities>/<activity>/<VARIATION>/<PAGE>/dist
+ *
+ * Editing .env (or the legacy watch-config.json, if still present) mid-session
+ * hot-swaps which variation/page is previewed without restarting the dev server.
+ */
+function variationDistFolder(sel) {
+    const segments = [
+        executionPath,
+        ACTIVITIES_BASE_FOLDER,
+        process.env.ACTIVITY_FOLDER_NAME,
+        sel.VARIATION
+    ];
+    if (sel.PAGE && sel.PAGE.trim()) {
+        segments.push(sel.PAGE.trim());
+    }
+    segments.push("dist");
+    return path.join(...segments);
 }
-catch (e) {
-    throw new Error(`Error : Couldn't find watch-config.json file at location ${executionPath}`);
+
+// Validate VARIATION up-front so we fail fast with a clear message instead of
+// reading from a nonsense path inside the puppeteer event loop.
+{
+    const initial = readDevSelection();
+    if (!initial.VARIATION) {
+        console.error('\x1b[31m❌ VARIATION is not set.\x1b[0m');
+        console.error('\x1b[33m💡 Add VARIATION="Variation-1" (and optional PAGE="Global" for multi-page) to .env, or run "atb doctor --fix".\x1b[0m');
+        process.exit(1);
+    }
 }
 
 
@@ -54,39 +132,64 @@ const watcher = chokidar.watch("file", {
             // inject script
             this.injectCodeSnippet();
 
-            watcher.add(watchConfig).on('change', async (event, path) => {
-                try {
-                    const distFolder = this.buildFolderPath;
-                    watcher.unwatch(distFolder);
+            // Tracks the dist folder we're currently watching so we can unwatch
+            // the *old* one when the user edits .env (or legacy watch-config.json).
+            this.currentWatchedFolder = null;
 
-                    // restart watch with another variation
-                    this.watchBuildFolder();
+            // Initial watches: build folder for the active variation/page,
+            // plus the config sources (.env always; watch-config.json if legacy).
+            this.watchBuildFolder();
+            watcher.add(envPath);
+            if (fs.existsSync(watchConfig)) {
+                watcher.add(watchConfig);
+            }
 
-                    await this.page.reload();
-                    this.injectCodeSnippet();
+            // Single change listener for the whole session. Branches on path:
+            //   .env or watch-config.json  → re-resolve VARIATION/PAGE, re-target
+            //   anything under currentWatchedFolder → reload (webpack rebuilt)
+            // Registered once (instead of inside .add(...).on(...)) so we don't
+            // accumulate listeners on every variation/page switch.
+            const envPathAbs = path.resolve(envPath);
+            const watchConfigAbs = path.resolve(watchConfig);
+            watcher.on('change', async (changedPath) => {
+                try {
+                    const changedAbs = path.resolve(changedPath);
+                    const isConfigChange = changedAbs === envPathAbs || changedAbs === watchConfigAbs;
+
+                    if (isConfigChange) {
+                        // .env change requires re-loading dotenv with override so
+                        // process.env actually reflects the edits. watch-config.json
+                        // is re-read each time via readDevSelection().
+                        if (changedAbs === envPathAbs) {
+                            dotenv.config({ path: envPath, override: true });
+                        }
+                        if (this.currentWatchedFolder) {
+                            watcher.unwatch(this.currentWatchedFolder);
+                        }
+                        this.watchBuildFolder();
+                        await this.page.reload();
+                        this.injectCodeSnippet();
+                    } else if (this.currentWatchedFolder && changedPath.startsWith(this.currentWatchedFolder)) {
+                        await this.page.reload();
+                        this.injectCodeSnippet();
+                    }
                     // eslint-disable-next-line @typescript-eslint/no-unused-vars
                 } catch (error) {
-
+                    // Swallow transient FS races; next change event will retry.
                 }
             });
 
-            this.watchBuildFolder();
             return this.trackNavigation();
         }
 
         get buildFolderPath() {
-            const env = this.getEnvConfig;
-            const distFolder = path.join(process.env.executionPath, "Activities", process.env.ACTIVITY_FOLDER_NAME, env.VARIATION, "dist");
-            return distFolder;
+            return variationDistFolder(readDevSelection());
         }
 
         watchBuildFolder() {
             const distFolder = this.buildFolderPath;
-            // Watch folder changes
-            watcher.add(distFolder).on('change', async (event, path) => {
-                await this.page.reload();
-                this.injectCodeSnippet();
-            });
+            watcher.add(distFolder);
+            this.currentWatchedFolder = distFolder;
         }
 
         async trackNavigation() {
@@ -102,15 +205,8 @@ const watcher = chokidar.watch("file", {
             this.trackNavigation();
         }
 
-        get getEnvConfig() {
-            const env = JSON.parse(fs.readFileSync(watchConfig));
-            return env;
-        }
-
         get getScript() {
-            const env = this.getEnvConfig;
-            // console.log("Env", env, "Process Env", process.env);
-            var filePath = path.join(process.env.executionPath, "Activities", process.env.ACTIVITY_FOLDER_NAME, env.VARIATION, "dist", "build.js");
+            const filePath = path.join(variationDistFolder(readDevSelection()), "build.js");
             const scriptContent = fs.readFileSync(filePath, 'utf-8');
             return scriptContent;
         }

package/src/constants/config.ts

@@ -71,8 +71,12 @@ ${formatText("COMMANDS", 'yellow', true)}
     ${formatText("dev --browser", 'cyan', true)}  Start development server and open in browser
     ${formatText("deploy", 'cyan', true)}         Deploy activity to Adobe Target
     ${formatText("deploy --dry-run", 'cyan', true)} Deploy in dry-run mode without actual deployment
+    ${formatText("deploy --force", 'cyan', true)}   Override the 60s post-deploy cooldown lock
+    ${formatText("sync", 'cyan', true)}           Sync build.config.json with the AT activity (pages, experiences, names)
+    ${formatText("sync --scaffold", 'cyan', true)}  Sync and auto-create any missing variation folders with boilerplate
     ${formatText("doctor", 'cyan', true)}         Diagnose and fix project configuration issues
     ${formatText("doctor --fix", 'cyan', true)}   Automatically fix detected configuration issues
+    ${formatText("install-extension", 'cyan', true)}  Install the at-builder VSCode extension from the Marketplace
     
 ${formatText("GLOBAL OPTIONS", 'yellow', true)}
     ${formatText("-v, --verbose", 'green')}       Enable detailed logging
@@ -100,7 +104,13 @@ ${formatText("EXAMPLES", 'yellow', true)}
     
     ${formatText("# Deploy in dry-run mode", 'gray')}
     ${formatText("atb deploy --dry-run", 'white')}
-    
+
+    ${formatText("# Sync build.config.json from Adobe Target", 'gray')}
+    ${formatText("atb sync", 'white')}
+
+    ${formatText("# Sync and scaffold missing variation folders", 'gray')}
+    ${formatText("atb sync --scaffold", 'white')}
+
     ${formatText("# Check project configuration", 'gray')}
     ${formatText("atb doctor", 'white')}
     
@@ -136,11 +146,19 @@ ACTIVITY_FOLDER_NAME=""
 PUPPETEER_LANDING_PAGE=""
 TARGET_URL=""
 LOGIN_URL=""
+
+# Dev-server selection (used by \`atb dev --browser\`).
+# Edit and save while puppeteer is running to hot-swap the previewed bundle.
+# PAGE is only meaningful for multi-page activities — leave empty otherwise.
 VARIATION="Variation-1"
+PAGE=""
+
 NODE_ENV="development"
 VERBOSE=false
 
 # Adobe Target Deployment Configuration
+# ADOBE_TENANT is your AT tenant slug — find it in the AT URL after "mc.adobe.io/".
+ADOBE_TENANT=""
 ADOBE_CLIENT_ID=""
 ADOBE_CLIENT_SECRET=""
     `;
@@ -150,8 +168,55 @@ ADOBE_CLIENT_SECRET=""
     } else {
         console.log('.env file already exists!');
     }
-    createWatchConfig(basePath);
+    // watch-config.json is no longer scaffolded by `atb init` — VARIATION/PAGE
+    // now live in .env. Existing projects with a watch-config.json keep working
+    // (puppeteer.js prefers it with a deprecation warning); `atb doctor --fix`
+    // migrates the values into .env and deletes the legacy file.
     createAdobeConfig(basePath);
+    createGitignore(basePath);
+}
+
+/**
+ * Default .gitignore content for at-builder consumer projects.
+ *
+ * Shared between `atb init` (via setupEnv) and `atb doctor --fix` so the two
+ * paths stay in lockstep. Covers secrets, deploy-runtime artifacts, build
+ * output, and OS noise. Does NOT ignore the Activities folder — those are the
+ * user's source files and should be committed.
+ */
+export const GITIGNORE_TEMPLATE = `# Dependencies
+node_modules/
+
+# Environment / secrets — never commit
+.env
+.env.local
+
+# Adobe Target deploy runtime (cooldown lock written by \`atb deploy\`)
+.deploy-lock
+
+# Build output (regenerated by \`atb build\`)
+dist/
+
+# OS noise
+.DS_Store
+
+# Editor / local-history
+.history/
+
+# Logs
+*.log
+npm-debug.log*
+`;
+
+const createGitignore = (basePath) => {
+    const gitignorePath = path.join(basePath, '.gitignore');
+
+    if (!fs.existsSync(gitignorePath)) {
+        fs.writeFileSync(gitignorePath, GITIGNORE_TEMPLATE, 'utf8');
+        console.log('.gitignore file created successfully!');
+    } else {
+        console.log('.gitignore file already exists!');
+    }
 }
 
 
@@ -160,9 +225,14 @@ const createWatchConfig = (basePath) => {
     // Path to the watch-config.json file
     const watchConfigPath = path.join(basePath, 'watch-config.json');
 
-    // Default content for watch-config.json
+    // Default content for watch-config.json.
+    //   VARIATION : which variation/experience to preview in `atb dev --browser`
+    //   PAGE      : leave empty for single-page activities; set to the page
+    //               subfolder name (e.g. "Global", "Cart") for multi-page.
+    //               Editing this file mid-session hot-swaps the preview.
     const watchConfigContent = {
-        "VARIATION": "Variation-1"
+        "VARIATION": "Variation-1",
+        "PAGE": ""
     };
 
     // Check if the watch-config.json file already exists
@@ -181,14 +251,19 @@ const createAdobeConfig = (basePath) => {
     // Default content for adobe.config.js
     const adobeConfigContent = `/**
  * Adobe Target API Configuration
- * 
- * Configuration constants for Adobe Target API integration.
- * These values are used by the deployment script to connect to Adobe Target.
+ *
+ * Used by at-sync.js and at-deploy.js. BASE_URL is the activities root —
+ * callers append \`\${activityType}/\${activityId}\` (e.g. ab/12345, xt/67890).
+ *
+ * ADOBE_TENANT comes from the consumer .env. Both at-sync and at-deploy load
+ * dotenv before requiring this file, so process.env is populated by the time
+ * BASE_URL is built.
  */
 
+const TENANT = process.env.ADOBE_TENANT || 'YOUR_TENANT';
+
 module.exports = {
-    BASE_URL_NEW: 'https://mc.adobe.io/ups/target/',
-    BASE_URL: 'https://mc.adobe.io/ups/target/activities/ab/',
+    BASE_URL: \`https://mc.adobe.io/\${TENANT}/target/activities/\`,
     IMS_TOKEN_URL: 'https://ims-na1.adobelogin.com/ims/token/v3',
     IMS_SCOPE: 'openid,AdobeID,target_sdk,additional_info.projectedProductContext'
 };`;

package/src/index.ts

@@ -85,10 +85,21 @@ const setupCommander = async () => {
         .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(async (options, command) => {
             const globalOpts = command.parent.opts();
             checkEnvFile();
-            await handleDeploy(options.dryRun, globalOpts.verbose);
+            await handleDeploy(options.dryRun, options.force, globalOpts.verbose);
+        });
+
+    program
+        .command('sync')
+        .description('Sync build.config.json with the Adobe Target activity definition')
+        .option('--scaffold', 'Auto-create missing variation folders with boilerplate')
+        .action(async (options, command) => {
+            const globalOpts = command.parent.opts();
+            checkEnvFile();
+            await handleSync(options.scaffold, globalOpts.verbose);
         });
 
     program
@@ -100,6 +111,15 @@ const setupCommander = async () => {
             await handleDoctor(options.fix, globalOpts.verbose);
         });
 
+    program
+        .command('install-extension')
+        .description('Install the at-builder VSCode extension from the Marketplace')
+        .option('--editor <bin>', 'Editor CLI to use (e.g. code, cursor, codium)', 'code')
+        .action(async (options, command) => {
+            const globalOpts = command.parent.opts();
+            await handleInstallExtension(options.editor, globalOpts.verbose);
+        });
+
     await program.parseAsync(process.argv);
     
     logger.info("setupCommander", "Commander setup complete");
@@ -110,16 +130,22 @@ const setupCommander = async () => {
 /**
  * Spawn a command using `npm` with the given command array and environment object.
  *
+ * Any entries in `scriptArgs` are forwarded to the underlying script via npm's
+ * `--` passthrough (e.g. `npm run foo -- --dry-run`).
+ *
  * @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.
  */
-const runCommand = (commandArr: string[], env: NodeJS.ProcessEnv): void => {
-    logger.info("runCommand", `Running npm command [${commandArr.join(", ")}]`);
+const runCommand = (commandArr: string[], env: NodeJS.ProcessEnv, scriptArgs: string[] = []): void => {
+    const fullArgs = scriptArgs.length > 0
+        ? [...commandArr, "--", ...scriptArgs]
+        : commandArr;
+
+    logger.info("runCommand", `Running npm command [${fullArgs.join(", ")}]`);
     logger.info("runCommand", `Current working directory: ${process.cwd()}`);
-    // logger.log(`Environment variables: ${JSON.stringify(env, null, 2)}`);
 
-    // Spawn the command using `npm` with the given environment and current working directory.
-    spawn("npm", commandArr, {
+    spawn("npm", fullArgs, {
         cwd: path.join(__dirname, "../"),
         env,
         shell: true,
@@ -191,12 +217,82 @@ const handleDev = async (browser: boolean, verbose: boolean): Promise<void> => {
 /**
  * Handles the deploy command
  */
-const handleDeploy = async (dryRun: boolean, verbose: boolean): Promise<void> => {
-    if (verbose) logger.info("verbose", `Deploying to Adobe Target with dry-run=${dryRun}`);
-    
+const handleDeploy = async (dryRun: boolean, force: boolean, verbose: boolean): Promise<void> => {
+    if (verbose) logger.info("verbose", `Deploying to Adobe Target with dry-run=${dryRun} force=${force}`);
+
     logger.info("handleDeploy", "Running Adobe Target deployment");
-    
-    runCommand(['run', 'atb:build:deploy'], productionEnv);
+
+    const scriptArgs: string[] = [];
+    if (dryRun) scriptArgs.push('--dry-run');
+    if (force) scriptArgs.push('--force');
+
+    runCommand(['run', 'atb:build:deploy'], productionEnv, scriptArgs);
+};
+
+/**
+ * Handles the sync command
+ */
+const handleSync = async (scaffold: boolean, verbose: boolean): Promise<void> => {
+    if (verbose) logger.info("verbose", `Syncing build.config.json with scaffold=${scaffold}`);
+
+    logger.info("handleSync", "Running Adobe Target sync");
+
+    const scriptArgs: string[] = [];
+    if (scaffold) scriptArgs.push('--scaffold');
+
+    runCommand(['run', 'atb:build:sync'], productionEnv, scriptArgs);
+};
+
+/**
+ * Handles the install-extension command.
+ *
+ * Installs the at-builder VSCode extension from the VS Code Marketplace
+ * using the editor's CLI. Defaults to `code`; users on Cursor/VSCodium
+ * can pass --editor.
+ */
+const handleInstallExtension = async (editor: string, verbose: boolean): Promise<void> => {
+    const extensionId = "UpendraSengar.at-builder";
+
+    if (verbose) logger.info("verbose", `Installing ${extensionId} via ${editor}`);
+
+    console.log(`📦 Installing ${extensionId} from the Marketplace via "${editor}"...`);
+
+    const result = spawn(editor, ["--install-extension", extensionId], {
+        stdio: "inherit",
+        shell: true
+    });
+
+    result.on("error", (err) => {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            console.error(`❌ "${editor}" CLI not found in PATH.`);
+            if (editor === "code") {
+                console.error("💡 Open VSCode and run Command Palette → \"Shell Command: Install 'code' command in PATH\".");
+            } else {
+                console.error(`💡 Make sure the "${editor}" CLI is installed and on your PATH, or pass a different --editor.`);
+            }
+        } else {
+            console.error(`❌ Failed to launch "${editor}": ${err.message}`);
+        }
+        process.exit(1);
+    });
+
+    result.on("exit", (code) => {
+        if (code === 0) {
+            console.log("✅ Extension installed. Reload your editor window to activate.");
+            return;
+        }
+        if (code === 127) {
+            console.error(`❌ "${editor}" CLI not found in PATH.`);
+            if (editor === "code") {
+                console.error("💡 Open VSCode and run Command Palette → \"Shell Command: Install 'code' command in PATH\".");
+            } else {
+                console.error(`💡 Make sure the "${editor}" CLI is installed and on your PATH, or pass a different --editor.`);
+            }
+            process.exit(1);
+        }
+        console.error(`❌ "${editor} --install-extension" exited with code ${code}.`);
+        process.exit(code ?? 1);
+    });
 };
 
 /**