@adobe/aem-cli 16.11.3 → 16.12.0

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+# [16.12.0](https://github.com/adobe/helix-cli/compare/v16.11.3...v16.12.0) (2025-09-16)
+
+
+### Bug Fixes
+
+* address PR review comments ([a14cabc](https://github.com/adobe/helix-cli/commit/a14cabc8aaa21525ded5bd9b4c021baf87da07f3))
+* address PR review comments for git worktree support ([4532cac](https://github.com/adobe/helix-cli/commit/4532cac0327e32b3aca045aa99e4279ba7b15d26)), closes [#2583](https://github.com/adobe/helix-cli/issues/2583)
+* comprehensive test setup improvements for git submodules and worktrees ([2715b95](https://github.com/adobe/helix-cli/commit/2715b9578831544ed0b42e93fdd87b2922f6d953))
+* ensure test directories exist before running git init ([c29542c](https://github.com/adobe/helix-cli/commit/c29542c5cd6c17e7a5e2691d7d4189c07a9d6914))
+* handle case where initGit is called from within target directory ([ad4ccde](https://github.com/adobe/helix-cli/commit/ad4ccde34e97afafdeac0c51b3c8e3ddefee7e3f))
+* handle Windows file locking in git worktree tests ([b271662](https://github.com/adobe/helix-cli/commit/b2716624e3fd28031d01b45cf86556d22e4e0f9f))
+* improve initGit error handling and ensure directory creation ([76514d0](https://github.com/adobe/helix-cli/commit/76514d088bc21bc51a379d292ca42bdde280d184))
+* increase Windows CI test timeout to 60 seconds ([149176a](https://github.com/adobe/helix-cli/commit/149176a2b642aee4efcb6e2d1de0a188cc789e12))
+* inline git init to avoid directory change issues ([72fe216](https://github.com/adobe/helix-cli/commit/72fe216f1355369eb2d82bc4356aa4a3aef07cb4))
+* prevent worktree name collisions in tests ([73b3cbf](https://github.com/adobe/helix-cli/commit/73b3cbfffcd6693163193f2031a344a2d2361d67))
+* properly configure Windows CI tests with increased timeout ([59f3a61](https://github.com/adobe/helix-cli/commit/59f3a6175af1c236c34ad1a54639cf7700fbd230))
+* resolve linting errors in test file ([ed31cca](https://github.com/adobe/helix-cli/commit/ed31cca0f82df047dca5e17b6ad6cba38f32f4c2))
+* revert to using initGit helper for consistent test setup ([b517cb3](https://github.com/adobe/helix-cli/commit/b517cb3e2487b180b4b3cdaf2e3949c3984e461f))
+* split statements to separate lines for linting ([068d91c](https://github.com/adobe/helix-cli/commit/068d91cfc36ef1cc6353ae9ad17b05de6e119734))
+* split test runs to identify hanging test ([8a7dd86](https://github.com/adobe/helix-cli/commit/8a7dd862ca4024a25daac0b37105d9f468a113c3))
+* use process.chdir instead of shell.cd for more reliable directory handling ([a31c327](https://github.com/adobe/helix-cli/commit/a31c327cb96add05d665ee9b00117d2be50150e4))
+
+
+### Features
+
+* add git worktree support with dynamic port selection ([cb763bd](https://github.com/adobe/helix-cli/commit/cb763bd004344d2a5361d675c8028efa2279ae1a))
+
 ## [16.11.3](https://github.com/adobe/helix-cli/compare/v16.11.2...v16.11.3) (2025-09-13)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/aem-cli",
-  "version": "16.11.3",
+  "version": "16.12.0",
   "description": "AEM CLI",
   "main": "index.js",
   "type": "module",
@@ -11,7 +11,7 @@
   "scripts": {
     "check": "npm run lint && npm run test",
     "test": "c8 mocha",
-    "test-ci-win": "npx mocha --reporter xunit test --reporter-options output=junit/test.xml -t 5000",
+    "test-ci-win": "mocha --reporter spec test -t 300000 --exit",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "semantic-release": "semantic-release",

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/up.cmd.js

@@ -64,7 +64,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,6 +81,15 @@ 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)
@@ -113,7 +130,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 +172,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,
     });