@adobe/aem-cli 16.11.3 → 16.13.0

package/packages/browser-injectables/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@adobe/aem-cli-browser-injectables",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Browser injectable scripts for AEM CLI development server",
+  "scripts": {
+    "lint": "eslint .",
+    "test": "web-test-runner",
+    "test:watch": "web-test-runner --watch",
+    "postinstall": "npm run copy-vendor && npx playwright install",
+    "copy-vendor": "node scripts/copy-vendor.js"
+  },
+  "devDependencies": {
+    "@adobe/eslint-config-helix": "^3.0.9",
+    "@eslint/config-helpers": "0.3.0",
+    "@esm-bundle/chai": "4.3.4-fix.0",
+    "@web/test-runner": "0.20.2",
+    "@web/test-runner-playwright": "0.11.1",
+    "@web/test-runner-junit-reporter": "0.8.0",
+    "@web/test-runner-mocha": "0.9.0"
+  },
+  "dependencies": {
+    "livereload-js": "4.0.2"
+  }
+}

package/packages/browser-injectables/scripts/copy-vendor.js

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Copy livereload.js from node_modules to vendor directory
+const source = path.join(__dirname, '../node_modules/livereload-js/dist/livereload.js');
+const dest = path.join(__dirname, '../vendor/livereload.js');
+
+// Create vendor directory if it doesn't exist
+fs.mkdirSync(path.dirname(dest), { recursive: true });
+
+// Copy the file
+fs.copyFileSync(source, dest);
+console.log('Copied livereload.js to vendor/');

package/packages/browser-injectables/src/console-interceptor.js

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * Browser Console Interceptor
+ * Intercepts console methods and forwards them via WebSocket to the server
+ * This script is self-contained and browser-compatible (no module system)
+ */
+(function iife() {
+  // Wait for LiveReload connection
+  var checkInterval = setInterval(function checkLiveReload() {
+    if (window.LiveReload && window.LiveReload.connector && window.LiveReload.connector.socket) {
+      clearInterval(checkInterval);
+
+      // Store original console methods
+      var originalConsole = {
+        log: console.log,
+        error: console.error,
+        warn: console.warn,
+        info: console.info,
+      };
+
+      // Helper to safely serialize arguments
+      function serializeArgs(args) {
+        return Array.from(args).map(function mapArg(arg) {
+          try {
+            if (arg instanceof Error) {
+              return { type: 'Error', message: arg.message, stack: arg.stack };
+            }
+            return JSON.parse(JSON.stringify(arg));
+          } catch (e) {
+            return String(arg);
+          }
+        });
+      }
+
+      // Get current file location
+      function getLocation() {
+        try {
+          var stack = new Error().stack;
+          var match = stack.match(/at.*?((https?:\/\/[^\s]+?):(\d+):(\d+))/);
+          if (match) {
+            return { url: match[2], line: match[3] };
+          }
+        } catch (e) {
+          // Ignore error when getting stack
+        }
+        return { url: window.location.href, line: 0 };
+      }
+
+      // Intercept console methods
+      ['log', 'error', 'warn', 'info'].forEach(function interceptLevel(level) {
+        console[level] = function interceptedConsole() {
+          // Call original method
+          originalConsole[level].apply(console, arguments);
+
+          // Forward to server if connected
+          if (window.LiveReload.connector.socket.readyState === 1) {
+            var location = getLocation();
+            window.LiveReload.connector.socket.send(JSON.stringify({
+              command: 'log',
+              level: level,
+              args: serializeArgs(arguments),
+              url: location.url,
+              line: location.line,
+            }));
+          }
+        };
+      });
+    }
+  }, 100);
+}());

package/packages/browser-injectables/web-test-runner.config.js

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { defaultReporter } from '@web/test-runner';
+import { junitReporter } from '@web/test-runner-junit-reporter';
+import { playwrightLauncher } from '@web/test-runner-playwright';
+
+export default {
+  nodeResolve: true,
+  coverage: true,
+  reporters: [
+    defaultReporter(),
+    junitReporter({
+      outputPath: 'junit/browser-test-results.xml',
+    }),
+  ],
+  testFramework: {
+    type: 'mocha',
+    config: {
+      timeout: 20000, // 20 seconds for browser tests
+    },
+  },
+  browsers: [
+    playwrightLauncher({ product: 'chromium' }),
+    playwrightLauncher({ product: 'firefox' }),
+    playwrightLauncher({ product: 'webkit' }),
+  ],
+  coverageConfig: {
+    report: true,
+    reportDir: 'coverage-browser',
+    exclude: [
+      'test/**',
+      'node_modules/**',
+      '**/*.test.js',
+      'scripts/**',
+    ],
+  },
+  files: [
+    'test/**/*.test.html',
+    'test/**/*.test.js',
+  ],
+  middleware: [
+    // Serve livereload.js from node_modules
+    async function serveLiveReload(context, next) {
+      if (context.url === '/__internal__/livereload.js') {
+        context.url = '/vendor/livereload.js';
+      }
+      await next();
+    },
+  ],
+};

package/src/git-utils.js

@@ -144,6 +144,24 @@ export default class GitUtils {
    * @returns {Promise<string>} current branch or tag
    */
   static async getBranch(dir, fallback = this.DEFAULT_BRANCH) {
+    // For worktrees, we need to get the actual git directory
+    const gitDir = await this.getGitDirectory(dir);
+
+    // If it's a worktree, try to get the branch from the worktree HEAD file
+    if (await this.isGitWorktree(dir)) {
+      try {
+        // Read the HEAD file in the worktree's git directory
+        const headPath = path.join(gitDir, 'HEAD');
+        const headContent = await fse.readFile(headPath, 'utf-8');
+        const match = headContent.match(/^ref: refs\/heads\/(.+)$/m);
+        if (match) {
+          return match[1].trim();
+        }
+      } catch (e) {
+        // Fall through to regular processing
+      }
+    }
+
     // current commit sha
     const rev = await git.resolveRef({ fs, dir, ref: 'HEAD' });
     // reverse-lookup tag from commit sha
@@ -194,7 +212,20 @@ export default class GitUtils {
    */
   static async getOrigin(dir) {
     try {
-      const rmt = (await git.listRemotes({ fs, dir })).find((entry) => entry.remote === 'origin');
+      // For worktrees, we need to use the main repository's config
+      let gitDir = dir;
+      if (await this.isGitWorktree(dir)) {
+        // Get the worktree's git directory
+        const worktreeGitDir = await this.getGitDirectory(dir);
+        // Extract the main repository path from the worktree git dir
+        // Worktree git dirs are like: /path/to/repo/.git/worktrees/worktree-name
+        const match = worktreeGitDir.match(/^(.+?)\/\.git\/worktrees\//);
+        if (match) {
+          [, gitDir] = match;
+        }
+      }
+
+      const rmt = (await git.listRemotes({ fs, dir: gitDir })).find((entry) => entry.remote === 'origin');
       return typeof rmt === 'object' ? rmt.url : '';
     } catch (e) {
       // don't fail if directory is not a git repository
@@ -264,4 +295,96 @@ export default class GitUtils {
       }))
       .then((obj) => obj.object);
   }
+
+  /**
+   * Checks if the given directory is a git worktree.
+   *
+   * @param {string} dir working tree directory path
+   * @returns {Promise<boolean>} `true` if the directory is a git worktree
+   */
+  static async isGitWorktree(dir) {
+    const gitPath = path.resolve(dir, '.git');
+    try {
+      // Read the file directly - if it's not a file, readFile will throw
+      const content = await fse.readFile(gitPath, 'utf-8');
+      return content.includes('/worktrees/');
+    } catch (e) {
+      // Either doesn't exist, is a directory, or can't be read
+      // ignore
+    }
+    return false;
+  }
+
+  /**
+   * Checks if the given directory is a git submodule.
+   *
+   * @param {string} dir working tree directory path
+   * @returns {Promise<boolean>} `true` if the directory is a git submodule
+   */
+  static async isGitSubmodule(dir) {
+    const gitPath = path.resolve(dir, '.git');
+    try {
+      // Read the file directly - if it's not a file, readFile will throw
+      const content = await fse.readFile(gitPath, 'utf-8');
+      // Submodules have relative paths to .git/modules
+      return content.includes('/.git/modules/') || content.includes('\\.git\\modules\\');
+    } catch (e) {
+      // Either doesn't exist, is a directory, or can't be read
+      // ignore
+    }
+    return false;
+  }
+
+  /**
+   * Gets the actual git directory, resolving through worktree/submodule redirection.
+   *
+   * @param {string} dir working tree directory path
+   * @returns {Promise<string>} path to the actual git directory
+   */
+  static async getGitDirectory(dir) {
+    const gitPath = path.resolve(dir, '.git');
+    try {
+      // Try to read as a file first (worktree/submodule case)
+      const content = await fse.readFile(gitPath, 'utf-8');
+      const match = content.match(/^gitdir: (.+)$/m);
+      if (match) {
+        const targetPath = match[1].trim();
+        // If it's a relative path, resolve it relative to the directory
+        if (!path.isAbsolute(targetPath)) {
+          return path.resolve(dir, targetPath);
+        }
+        return targetPath;
+      }
+    } catch (e) {
+      // If readFile fails, it's likely a directory - check if it exists
+      try {
+        const stat = await fse.lstat(gitPath);
+        if (stat.isDirectory()) {
+          return gitPath;
+        }
+      } catch (statErr) {
+        // ignore
+      }
+    }
+    return gitPath;
+  }
+
+  /**
+   * Generates a deterministic port number based on branch name.
+   *
+   * @param {string} branchName the branch name to hash
+   * @param {number} basePort base port number (default: 3000)
+   * @param {number} range range of ports to use (default: 1000)
+   * @returns {number} port number between basePort and basePort + range - 1
+   */
+  static hashBranchToPort(branchName, basePort = 3000, range = 1000) {
+    let hash = 0;
+    for (let i = 0; i < branchName.length; i += 1) {
+      // eslint-disable-next-line no-bitwise
+      hash = ((hash << 5) - hash) + branchName.charCodeAt(i);
+      // eslint-disable-next-line no-bitwise
+      hash &= hash; // Convert to 32bit integer
+    }
+    return basePort + (Math.abs(hash) % range);
+  }
 }

package/src/server/HelixProject.js

@@ -32,6 +32,11 @@ export class HelixProject extends BaseProject {
     return this;
   }
 
+  withForwardBrowserLogs(value) {
+    this._server.withForwardBrowserLogs(value);
+    return this;
+  }
+
   withSiteToken(value) {
     this.siteToken = value;
     this._server.withSiteToken(value);

package/src/server/HelixServer.js

@@ -32,6 +32,7 @@ export class HelixServer extends BaseServer {
     super(project);
     this._liveReload = null;
     this._enableLiveReload = false;
+    this._forwardBrowserLogs = false;
     this._app.use(compression());
     this._autoLogin = true;
     this._cookies = false;
@@ -42,6 +43,15 @@ export class HelixServer extends BaseServer {
     return this;
   }
 
+  withForwardBrowserLogs(value) {
+    this._forwardBrowserLogs = value;
+    return this;
+  }
+
+  get forwardBrowserLogs() {
+    return this._forwardBrowserLogs;
+  }
+
   withSiteToken(value) {
     this._siteToken = value;
     return this;
@@ -225,6 +235,7 @@ export class HelixServer extends BaseServer {
     await super.setupApp();
     if (this._enableLiveReload) {
       this._liveReload = new LiveReload(this.log);
+      this._liveReload.withForwardBrowserLogs(this._forwardBrowserLogs);
       await this._liveReload.init(this.app, this._server);
     }
 

package/src/server/LiveReload.js

@@ -11,10 +11,10 @@
  */
 // eslint-disable-next-line max-classes-per-file
 import fs from 'fs';
+import { createRequire } from 'module';
 import chokidar from 'chokidar';
 import WebSocket from 'faye-websocket';
 import { EventEmitter } from 'events';
-import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
 
@@ -27,9 +27,10 @@ class ClientConnection extends EventEmitter {
     return `ws${ClientConnection.counter}`;
   }
 
-  constructor(req, socket, head) {
+  constructor(req, socket, head, logger) {
     super();
     this.id = ClientConnection.nextId();
+    this.log = logger;
     this.ws = new WebSocket(req, socket, head);
     this.ws.onmessage = this._onMessage.bind(this);
     this.ws.onclose = this._onClose.bind(this);
@@ -47,6 +48,8 @@ class ClientConnection extends EventEmitter {
         return this._cmdHello(data);
       case 'info':
         return this._cmdInfo(data);
+      case 'log':
+        return this._cmdLog(data);
       default:
         return {};
     }
@@ -78,6 +81,30 @@ class ClientConnection extends EventEmitter {
     return { ...data || {}, id: this.id, url: this.url };
   }
 
+  _cmdLog(data) {
+    const {
+      level = 'log', args = [], url = 'unknown', line,
+    } = data;
+    const timestamp = new Date().toISOString();
+    const location = line ? `${url}:${line}` : url;
+
+    // Format browser logs distinctively
+    const prefix = `[Browser:${level}] ${timestamp} ${location}`;
+
+    // Serialize args safely
+    const message = args.map((arg) => {
+      try {
+        return typeof arg === 'object' ? JSON.stringify(arg, null, 2) : String(arg);
+      } catch (e) {
+        return '[Circular or Complex Object]';
+      }
+    }).join(' ');
+
+    // Use appropriate log level
+    const logMethod = this.log[level] || this.log.info;
+    logMethod(`${prefix} ${message}`);
+  }
+
   _send(data) {
     if (this.ws) {
       this.ws.send(JSON.stringify(data));
@@ -123,12 +150,22 @@ export default class LiveReload extends EventEmitter {
     // client connections
     this._connections = {};
     this._liveReloadJSPath = require.resolve('livereload-js/dist/livereload.js');
+    this._forwardBrowserLogs = false;
   }
 
   get log() {
     return this._logger;
   }
 
+  withForwardBrowserLogs(value) {
+    this._forwardBrowserLogs = value;
+    return this;
+  }
+
+  get forwardBrowserLogs() {
+    return this._forwardBrowserLogs;
+  }
+
   startRequest(requestId, pathname) {
     this._pending.set(requestId, {
       pathname,
@@ -211,7 +248,7 @@ export default class LiveReload extends EventEmitter {
   }
 
   _onSvrUpgrade(req, socket, head) {
-    const cx = new ClientConnection(req, socket, head);
+    const cx = new ClientConnection(req, socket, head, this.log);
     this._connections[cx.id] = cx;
 
     socket.on('error', (e) => {

package/src/server/utils.js

@@ -14,9 +14,19 @@ import crypto from 'crypto';
 import path from 'path';
 import { Socket } from 'net';
 import { PassThrough } from 'stream';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
 import cookie from 'cookie';
 import { getFetch } from '../fetch-utils.js';
 
+// Load console interceptor script at startup
+// eslint-disable-next-line no-underscore-dangle
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CONSOLE_INTERCEPTOR = readFileSync(
+  path.join(__dirname, '../../packages/browser-injectables/src/console-interceptor.js'),
+  'utf-8',
+);
+
 const utils = {
   status2level(status, debug3xx) {
     if (status < 300) {
@@ -104,6 +114,12 @@ window.LiveReloadOptions = {
         newbody += `<script${nonce}>window.LiveReloadOptions={port:${server.port},host:location.hostname,https:${server.scheme === 'https'}};</script>`;
       }
       newbody += `<script${nonce} src="/__internal__/livereload.js"></script>`;
+
+      // Inject console interceptor if browser log forwarding is enabled
+      if (server.forwardBrowserLogs) {
+        newbody += `<script${nonce}>${CONSOLE_INTERCEPTOR}</script>`;
+      }
+
       newbody += body.substring(index);
       return newbody;
     }

package/src/up.cmd.js

@@ -24,6 +24,11 @@ export default class UpCommand extends AbstractServerCommand {
     return this;
   }
 
+  withForwardBrowserLogs(value) {
+    this._forwardBrowserLogs = value;
+    return this;
+  }
+
   withUrl(value) {
     this._originalUrl = value;
     return this;
@@ -64,7 +69,15 @@ export default class UpCommand extends AbstractServerCommand {
     try {
       const stat = await fse.lstat(path.resolve(this.directory, '.git'));
       if (stat.isFile()) {
-        throw Error('git submodules are not supported.');
+        // Check if it's a submodule or a worktree
+        if (await GitUtils.isGitSubmodule(this.directory)) {
+          throw Error('git submodules are not supported.');
+        }
+        // Verify it's actually a worktree
+        if (!await GitUtils.isGitWorktree(this.directory)) {
+          throw Error('Unsupported git configuration: .git is a file but not a valid worktree or submodule.');
+        }
+        // It's a worktree - this is allowed
       }
     } catch (e) {
       if (e.code === 'ENOENT') {
@@ -73,10 +86,20 @@ export default class UpCommand extends AbstractServerCommand {
       throw e;
     }
 
+    // Check if we're in a worktree and need to adjust the port
+    const isWorktree = await GitUtils.isGitWorktree(this.directory);
+    if (isWorktree && this._httpPort === 3000) {
+      // Only adjust port if using default port
+      const branch = await GitUtils.getBranch(this.directory);
+      this._httpPort = GitUtils.hashBranchToPort(branch);
+      this.log.info(chalk`Git worktree detected. Using port {cyan ${this._httpPort}} for branch {cyan ${branch}}`);
+    }
+
     // init dev default file params
     this._project = new HelixProject()
       .withCwd(this.directory)
       .withLiveReload(this._liveReload)
+      .withForwardBrowserLogs(this._forwardBrowserLogs)
       .withLogger(this._logger)
       .withKill(this._kill)
       .withPrintIndex(this._printIndex)
@@ -113,7 +136,7 @@ export default class UpCommand extends AbstractServerCommand {
 
     try {
       await this._project.init();
-      this.watchGit();
+      await this.watchGit();
     } catch (e) {
       throw Error(`Unable to start AEM: ${e.message}`);
     }
@@ -155,10 +178,13 @@ export default class UpCommand extends AbstractServerCommand {
   /**
    * Watches the git repository for changes and restarts the server if necessary.
    */
-  watchGit() {
+  async watchGit() {
     let timer = null;
 
-    this._watcher = chokidar.watch(path.resolve(this._project.directory, '.git'), {
+    // Resolve the actual git directory for worktrees
+    const gitDir = await GitUtils.getGitDirectory(this._project.directory);
+
+    this._watcher = chokidar.watch(gitDir, {
       persistent: true,
       ignoreInitial: true,
     });

package/src/up.js

@@ -97,7 +97,7 @@ export default function up() {
           describe: 'Path to local folder to cache the responses (note: this is an alpha feature, it may be removed without notice)',
           type: 'string',
         })
-        .group(['url', 'livereload', 'no-livereload', 'open', 'no-open', 'print-index', 'cache'], 'AEM Options')
+        .group(['url', 'livereload', 'no-livereload', 'open', 'no-open', 'print-index', 'cache', 'forward-browser-logs'], 'AEM Options')
         .option('allow-insecure', {
           alias: 'allowInsecure',
           describe: 'Whether to allow insecure requests to the server',
@@ -109,6 +109,12 @@ export default function up() {
           type: 'boolean',
           default: false,
         })
+        .option('forward-browser-logs', {
+          alias: 'forwardBrowserLogs',
+          describe: 'Forward browser console logs to terminal',
+          type: 'boolean',
+          default: false,
+        })
 
         .help();
     },
@@ -127,6 +133,7 @@ export default function up() {
         .withOpen(path.basename(argv.$0) === 'aem' ? argv.open : false)
         .withTLS(argv.tlsKey, argv.tlsCert)
         .withLiveReload(argv.livereload)
+        .withForwardBrowserLogs(argv.forwardBrowserLogs)
         .withSiteToken(argv.siteToken || await getSiteTokenFromFile())
         .withUrl(argv.url)
         .withPrintIndex(argv.printIndex)