at-builder 1.2.9 → 1.3.3

package/src/services/doctor.ts

@@ -1,6 +1,25 @@
 import path from "path";
 import fs from "fs";
 import logger from "./logger";
+import { GITIGNORE_TEMPLATE } from "../constants/config";
+
+// lib/install-checks.js is hand-written runtime JS (not TS-compiled). The
+// relative path resolves correctly from both src/services/doctor.ts (source)
+// and bin/services/doctor.js (compiled output) because src/ and bin/ have
+// parallel structure. Typed inline since the module isn't part of the TS graph.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installChecks = require("../../lib/install-checks") as {
+    checkInstallEnvironment: (opts?: { localBinScript?: string; fixPermissions?: boolean }) => {
+        ok: boolean;
+        problems: string[];
+        globalBin: string;
+        shimPath: string;
+        shimExecutable: boolean;
+        isWin: boolean;
+        isGlobalInstall: boolean;
+        nodeMajor: number;
+    };
+};
 
 export interface DiagnosticIssue {
     id: string;
@@ -23,15 +42,24 @@ export const runDiagnostics = async (projectPath: string, verbose: boolean = fal
     await checkEnvFile(projectPath, issues);
     await checkAdobeConfig(projectPath, issues);
     await checkWatchConfig(projectPath, issues);
+    await checkGitignore(projectPath, issues);
     await checkPackageJson(projectPath, issues);
     await checkActivitiesFolder(projectPath, issues);
-    
+
     // Check environment variables
     await checkEnvVariables(projectPath, issues);
-    
+
     // Check dependencies
     await checkDependencies(projectPath, issues);
-    
+
+    // Check build.config.json content for every activity
+    await checkBuildConfigs(projectPath, issues);
+
+    // Check install environment (PATH, atb shim, exec bit). Mirrors the
+    // postinstall validator so users who installed with --ignore-scripts
+    // (or who dismissed the postinstall warning) can still self-diagnose.
+    await checkInstallEnv(issues);
+
     return issues;
 };
 
@@ -71,8 +99,10 @@ const fixIssue = async (issue: DiagnosticIssue, projectPath: string, verbose: bo
             return await createEnvFile(projectPath);
         case 'missing-adobe-config':
             return await createAdobeConfig(projectPath);
-        case 'missing-watch-config':
-            return await createWatchConfig(projectPath);
+        case 'legacy-watch-config':
+            return await migrateWatchConfig(projectPath);
+        case 'missing-gitignore':
+            return await createGitignore(projectPath);
         case 'missing-activities-folder':
             return await createActivitiesFolder(projectPath);
         case 'missing-package-json':
@@ -142,19 +172,42 @@ const checkAdobeConfig = async (projectPath: string, issues: DiagnosticIssue[]):
 };
 
 /**
- * Check if watch-config.json exists
+ * Flag a legacy watch-config.json. As of this release VARIATION/PAGE live in
+ * .env; watch-config.json is supported as a fallback (puppeteer.js prefers it
+ * if present with a deprecation warning) but new projects don't get one.
+ *
+ * The fix migrates VARIATION/PAGE into .env and deletes watch-config.json.
  */
 const checkWatchConfig = async (projectPath: string, issues: DiagnosticIssue[]): Promise<void> => {
     const configPath = path.join(projectPath, 'watch-config.json');
-    
-    if (!fs.existsSync(configPath)) {
+    if (!fs.existsSync(configPath)) return;
+
+    issues.push({
+        id: 'legacy-watch-config',
+        severity: 'warning',
+        message: 'watch-config.json is deprecated — VARIATION/PAGE now live in .env',
+        suggestion: 'Run "atb doctor --fix" to migrate values into .env and delete watch-config.json',
+        fixable: true,
+        file: 'watch-config.json'
+    });
+};
+
+/**
+ * Check if .gitignore exists. Flags as a warning (not blocking) but fixable —
+ * `atb doctor --fix` writes the default template covering .env, .deploy-lock,
+ * dist/, etc. Does not modify an existing .gitignore.
+ */
+const checkGitignore = async (projectPath: string, issues: DiagnosticIssue[]): Promise<void> => {
+    const gitignorePath = path.join(projectPath, '.gitignore');
+
+    if (!fs.existsSync(gitignorePath)) {
         issues.push({
-            id: 'missing-watch-config',
+            id: 'missing-gitignore',
             severity: 'warning',
-            message: 'watch-config.json file is missing',
-            suggestion: 'Create build configuration file',
+            message: '.gitignore file is missing',
+            suggestion: 'Create .gitignore with at-builder defaults (.env, .deploy-lock, dist/, etc.)',
             fixable: true,
-            file: 'watch-config.json'
+            file: '.gitignore'
         });
     }
 };
@@ -177,24 +230,26 @@ const checkPackageJson = async (projectPath: string, issues: DiagnosticIssue[]):
     }
 };
 
+/**
+ * Resolve the configured activities folder name. Reads ACTIVITIES_BASE_FOLDER
+ * from the consumer .env (matching webpack/at-deploy/at-sync resolution), falls
+ * back to the default "Activities".
+ */
+const resolveActivitiesFolderName = (projectPath: string): string => {
+    const envPath = path.join(projectPath, '.env');
+    if (!fs.existsSync(envPath)) return 'Activities';
+    const envContent = fs.readFileSync(envPath, 'utf8');
+    const match = envContent.match(/ACTIVITIES_BASE_FOLDER=["']?([^"'\n\r]+)["']?/);
+    return match ? match[1] : 'Activities';
+};
+
 /**
  * Check if Activities folder exists
  */
 const checkActivitiesFolder = async (projectPath: string, issues: DiagnosticIssue[]): Promise<void> => {
-    // Try to read ACTIVITIES_BASE_FOLDER from .env, fallback to default
-    let activitiesFolder = 'Activities';
-    const envPath = path.join(projectPath, '.env');
-    
-    if (fs.existsSync(envPath)) {
-        const envContent = fs.readFileSync(envPath, 'utf8');
-        const match = envContent.match(/ACTIVITIES_BASE_FOLDER=["']?([^"'\n\r]+)["']?/);
-        if (match) {
-            activitiesFolder = match[1];
-        }
-    }
-    
+    const activitiesFolder = resolveActivitiesFolderName(projectPath);
     const activitiesPath = path.join(projectPath, activitiesFolder);
-    
+
     if (!fs.existsSync(activitiesPath)) {
         issues.push({
             id: 'missing-activities-folder',
@@ -207,6 +262,172 @@ const checkActivitiesFolder = async (projectPath: string, issues: DiagnosticIssu
     }
 };
 
+/**
+ * Validate every shared/build.config.json under the activities folder.
+ *
+ * Catches the deploy-time errors before deploy:
+ *   - missing or invalid activityType (must be "ab" or "xt")
+ *   - null id (deploy will fail when it tries to GET the activity)
+ *   - multi-page variation values without an activityInfo.pages map
+ *   - variation/page folders referenced in config but absent on disk
+ *
+ * Issues are not auto-fixable (they're content problems requiring human
+ * judgment), so each one is reported with a clear suggestion.
+ */
+const checkBuildConfigs = async (projectPath: string, issues: DiagnosticIssue[]): Promise<void> => {
+    const activitiesFolder = resolveActivitiesFolderName(projectPath);
+    const activitiesPath = path.join(projectPath, activitiesFolder);
+    if (!fs.existsSync(activitiesPath)) return; // already flagged elsewhere
+
+    const activityDirs = fs.readdirSync(activitiesPath, { withFileTypes: true })
+        .filter(d => d.isDirectory() && !d.name.startsWith('.'));
+
+    for (const activityDir of activityDirs) {
+        const activityRoot = path.join(activitiesPath, activityDir.name);
+        const configCandidates = [
+            path.join(activityRoot, 'shared', 'build.config.json'),
+            path.join(activityRoot, 'Shared', 'build.config.json')
+        ];
+        const configPath = configCandidates.find(p => fs.existsSync(p));
+        if (!configPath) continue; // missing build.config is its own concern
+
+        const relConfig = path.relative(projectPath, configPath);
+
+        let parsed: { activityInfo?: Record<string, unknown> };
+        try {
+            parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        } catch (err) {
+            issues.push({
+                id: `invalid-build-config-json:${activityDir.name}`,
+                severity: 'error',
+                message: `${relConfig} is not valid JSON`,
+                suggestion: `Open ${relConfig} and fix the JSON syntax. Error: ${(err as Error).message}`,
+                fixable: false,
+                file: relConfig
+            });
+            continue;
+        }
+
+        const activityInfo = (parsed && parsed.activityInfo) as Record<string, unknown> | undefined;
+        if (!activityInfo || typeof activityInfo !== 'object') {
+            issues.push({
+                id: `missing-activity-info:${activityDir.name}`,
+                severity: 'error',
+                message: `${relConfig} is missing activityInfo`,
+                suggestion: 'Re-run "atb new" or restore activityInfo manually',
+                fixable: false,
+                file: relConfig
+            });
+            continue;
+        }
+
+        // activityType validation
+        const activityType = activityInfo.activityType as string | undefined;
+        if (!activityType) {
+            issues.push({
+                id: `missing-activity-type:${activityDir.name}`,
+                severity: 'warning',
+                message: `${relConfig} is missing activityType`,
+                suggestion: 'Add `"activityType": "ab"` (or "xt") to activityInfo',
+                fixable: false,
+                file: relConfig
+            });
+        } else if (!['ab', 'xt'].includes(String(activityType).toLowerCase())) {
+            issues.push({
+                id: `invalid-activity-type:${activityDir.name}`,
+                severity: 'error',
+                message: `${relConfig} has invalid activityType "${activityType}"`,
+                suggestion: 'activityType must be "ab" or "xt"',
+                fixable: false,
+                file: relConfig
+            });
+        }
+
+        // id check (warning only — null is fine until first deploy)
+        if (activityInfo.id === null || activityInfo.id === undefined) {
+            issues.push({
+                id: `unset-activity-id:${activityDir.name}`,
+                severity: 'warning',
+                message: `${relConfig} has no activity id (deploy will fail until set)`,
+                suggestion: 'Set activityInfo.id once the activity exists in Adobe Target, or run "atb sync"',
+                fixable: false,
+                file: relConfig
+            });
+        }
+
+        // Variations validation
+        const variations = activityInfo.variations as Record<string, unknown> | unknown[] | undefined;
+        if (!variations || (Array.isArray(variations) && variations.length === 0) || (typeof variations === 'object' && !Array.isArray(variations) && Object.keys(variations).length === 0)) {
+            issues.push({
+                id: `missing-variations:${activityDir.name}`,
+                severity: 'error',
+                message: `${relConfig} has no variations`,
+                suggestion: 'Add at least one variation to activityInfo.variations',
+                fixable: false,
+                file: relConfig
+            });
+            continue;
+        }
+
+        // Multi-page detection: any variation value is an object with a `pages` key
+        const variationEntries = Array.isArray(variations)
+            ? []
+            : Object.entries(variations);
+        const isMultiPage = variationEntries.some(([, v]) =>
+            typeof v === 'object' && v !== null && 'pages' in (v as object)
+        );
+
+        if (isMultiPage) {
+            const pages = activityInfo.pages as Record<string, unknown> | undefined;
+            if (!pages || typeof pages !== 'object' || Object.keys(pages).length === 0) {
+                issues.push({
+                    id: `multi-page-missing-pages:${activityDir.name}`,
+                    severity: 'error',
+                    message: `${relConfig} uses multi-page variations but has no activityInfo.pages map`,
+                    suggestion: 'Add `"pages": { "<pageName>": <locationLocalId>, ... }` or run "atb sync" to populate it from Adobe Target',
+                    fixable: false,
+                    file: relConfig
+                });
+            }
+
+            // Each multi-page variation: pages.<page> should map to a folder that exists
+            for (const [variationKey, variationValue] of variationEntries) {
+                if (typeof variationValue !== 'object' || variationValue === null || !('pages' in (variationValue as object))) continue;
+                const pagesMap = (variationValue as { pages?: Record<string, unknown> }).pages || {};
+                for (const [pageName, subPath] of Object.entries(pagesMap)) {
+                    if (typeof subPath !== 'string') continue;
+                    const folderAbs = path.join(activityRoot, subPath);
+                    if (!fs.existsSync(folderAbs)) {
+                        issues.push({
+                            id: `missing-page-folder:${activityDir.name}:${variationKey}:${pageName}`,
+                            severity: 'warning',
+                            message: `${relConfig}: variation "${variationKey}" → page "${pageName}" expects folder "${subPath}" but it doesn't exist`,
+                            suggestion: 'Run "atb sync --scaffold" to auto-create missing variation folders, or create them manually',
+                            fixable: false,
+                            file: relConfig
+                        });
+                    }
+                }
+            }
+        } else {
+            // Single-page: each variation key should map to a folder under the activity root
+            for (const [variationKey] of variationEntries) {
+                const folderAbs = path.join(activityRoot, variationKey);
+                if (!fs.existsSync(folderAbs)) {
+                    issues.push({
+                        id: `missing-variation-folder:${activityDir.name}:${variationKey}`,
+                        severity: 'warning',
+                        message: `${relConfig}: variation "${variationKey}" has no folder at ${path.relative(projectPath, folderAbs)}`,
+                        suggestion: 'Create the folder, run "atb new" to scaffold variations, or remove the entry from build.config.json',
+                        fixable: false,
+                        file: relConfig
+                    });
+                }
+            }
+        }
+    }
+};
+
 /**
  * Check environment variables content
  */
@@ -247,6 +468,20 @@ const checkEnvVariables = async (projectPath: string, issues: DiagnosticIssue[])
             fixable: false
         });
     }
+
+    // ADOBE_TENANT — if missing or empty, BASE_URL in adobe.config.js will fall
+    // back to the literal "YOUR_TENANT" placeholder and every API call will 404.
+    const tenantMatch = envContent.match(/^ADOBE_TENANT=(.*)$/m);
+    const tenantValue = tenantMatch ? tenantMatch[1].trim().replace(/^["']|["']$/g, '') : '';
+    if (!tenantValue) {
+        issues.push({
+            id: 'empty-adobe-tenant',
+            severity: 'warning',
+            message: 'ADOBE_TENANT is missing or empty',
+            suggestion: 'Set ADOBE_TENANT to your AT tenant slug (the segment after mc.adobe.io/ in the AT URL)',
+            fixable: false
+        });
+    }
 };
 
 /**
@@ -255,9 +490,9 @@ const checkEnvVariables = async (projectPath: string, issues: DiagnosticIssue[])
 const checkDependencies = async (projectPath: string, issues: DiagnosticIssue[]): Promise<void> => {
     const packagePath = path.join(projectPath, 'package.json');
     if (!fs.existsSync(packagePath)) return;
-    
+
     const nodeModulesPath = path.join(projectPath, 'node_modules');
-    
+
     if (!fs.existsSync(nodeModulesPath)) {
         issues.push({
             id: 'missing-node-modules',
@@ -269,6 +504,41 @@ const checkDependencies = async (projectPath: string, issues: DiagnosticIssue[])
     }
 };
 
+/**
+ * Validate that the at-builder global install is healthy:
+ *   - global npm bin is on PATH
+ *   - the `atb` shim exists in the global bin
+ *   - on POSIX, the shim and the package's bin/index.js are executable
+ *     (auto-chmods 755 if missing the bit)
+ *
+ * Same checks as lib/postinstall.js, just surfaced through `atb doctor` for
+ * users who installed with --ignore-scripts or dismissed the postinstall
+ * warning. Issues are flagged but not auto-fixable here — the suggested
+ * commands need to run in the user's shell, not in this Node process.
+ */
+const checkInstallEnv = async (issues: DiagnosticIssue[]): Promise<void> => {
+    let result;
+    try {
+        result = installChecks.checkInstallEnvironment();
+    } catch (err) {
+        // Don't let a bug in install-checks block the rest of doctor.
+        logger.error("checkInstallEnv", `Skipped: ${(err as Error).message}`);
+        return;
+    }
+
+    for (const problem of result.problems) {
+        issues.push({
+            id: 'install-env',
+            severity: 'warning',
+            message: problem,
+            suggestion: result.isWin
+                ? `On Windows: ensure ${result.globalBin || 'your npm global bin (npm config get prefix)'} is on PATH, then reinstall: npm i -g at-builder`
+                : `On macOS/Linux: chmod +x "${result.shimPath || 'atb shim'}" and ensure ${result.globalBin || '$(npm config get prefix)/bin'} is on PATH; then run: hash -r`,
+            fixable: false
+        });
+    }
+};
+
 // Fix functions
 
 const createEnvFile = async (projectPath: string): Promise<boolean> => {
@@ -278,14 +548,22 @@ 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=""`;
-    
+
     try {
         fs.writeFileSync(envPath, envContent, 'utf8');
         return true;
@@ -298,14 +576,19 @@ const createAdobeConfig = async (projectPath: string): Promise<boolean> => {
     const configPath = path.join(projectPath, 'adobe.config.js');
     const configContent = `/**
  * 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'
 };`;
@@ -318,14 +601,69 @@ module.exports = {
     }
 };
 
-const createWatchConfig = async (projectPath: string): Promise<boolean> => {
+/**
+ * Migrate VARIATION/PAGE from a legacy watch-config.json into .env, then
+ * delete the watch-config.json. Idempotent: existing .env entries are
+ * overwritten so the migrated values win (matching puppeteer's runtime
+ * precedence — watch-config.json was the source of truth).
+ */
+const migrateWatchConfig = async (projectPath: string): Promise<boolean> => {
     const configPath = path.join(projectPath, 'watch-config.json');
-    const configContent = {
-        "VARIATION": "Variation-1"
-    };
-    
+    const envPath = path.join(projectPath, '.env');
+    if (!fs.existsSync(configPath)) return true; // nothing to migrate
+
+    let watchCfg: { VARIATION?: string; PAGE?: string };
+    try {
+        watchCfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (err) {
+        console.error(`Failed to parse watch-config.json: ${(err as Error).message}`);
+        return false;
+    }
+
+    const variation = (watchCfg.VARIATION || '').trim();
+    const page = (watchCfg.PAGE || '').trim();
+
+    if (!fs.existsSync(envPath)) {
+        // No .env yet — synthesize a minimal one with just the migrated keys.
+        // The user can add the rest via `atb init` or by editing manually.
+        fs.writeFileSync(envPath, `VARIATION="${variation}"\nPAGE="${page}"\n`, 'utf8');
+    } else {
+        let envContent = fs.readFileSync(envPath, 'utf8');
+        envContent = upsertEnvLine(envContent, 'VARIATION', variation);
+        envContent = upsertEnvLine(envContent, 'PAGE', page);
+        fs.writeFileSync(envPath, envContent, 'utf8');
+    }
+
+    try {
+        fs.unlinkSync(configPath);
+    } catch (err) {
+        console.error(`Migrated values into .env, but failed to delete watch-config.json: ${(err as Error).message}`);
+        return false;
+    }
+
+    console.log(`✓ Migrated VARIATION="${variation}" PAGE="${page}" from watch-config.json into .env`);
+    return true;
+};
+
+/**
+ * Insert or replace a `KEY="value"` line in a .env file body. Preserves
+ * surrounding lines; appends if the key wasn't present.
+ */
+const upsertEnvLine = (envContent: string, key: string, value: string): string => {
+    const line = `${key}="${value}"`;
+    const re = new RegExp(`^${key}=.*$`, 'm');
+    if (re.test(envContent)) {
+        return envContent.replace(re, line);
+    }
+    if (!envContent.endsWith('\n')) envContent += '\n';
+    return envContent + line + '\n';
+};
+
+const createGitignore = async (projectPath: string): Promise<boolean> => {
+    const gitignorePath = path.join(projectPath, '.gitignore');
+
     try {
-        fs.writeFileSync(configPath, JSON.stringify(configContent, null, 2), 'utf8');
+        fs.writeFileSync(gitignorePath, GITIGNORE_TEMPLATE, 'utf8');
         return true;
     } catch (error) {
         return false;