@adobe/aem-cli 16.13.2 → 16.15.0

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+# [16.15.0](https://github.com/adobe/helix-cli/compare/v16.14.0...v16.15.0) (2025-09-22)
+
+
+### Features
+
+* enable auto-reload for static HTML resources (fixes [#2400](https://github.com/adobe/helix-cli/issues/2400)) ([0866ede](https://github.com/adobe/helix-cli/commit/0866edea1579d6e1c207d756e5ee9dbe266a5e6c))
+* **git-utils:** add DNS-valid tag filtering in getBranch ([fd367c4](https://github.com/adobe/helix-cli/commit/fd367c421187cf75263b32bdc5e83a886f29ef9a))
+* **git-utils:** enhance DNS name validation with stricter rules and length checks ([9702a63](https://github.com/adobe/helix-cli/commit/9702a63a26949d8dce135a17192b6801508d848c))
+
+# [16.14.0](https://github.com/adobe/helix-cli/compare/v16.13.2...v16.14.0) (2025-09-19)
+
+
+### Bug Fixes
+
+* address CodeQL security alert for HTML folder handler ([76450f2](https://github.com/adobe/helix-cli/commit/76450f25c33d0300adc53fe3b6e7696974e0e384))
+* address PR review comments for HTML folder feature ([c8ff512](https://github.com/adobe/helix-cli/commit/c8ff512d97227e94eb8890e083c533db92c4c663))
+* address PR review comments for HTML folder security ([842650e](https://github.com/adobe/helix-cli/commit/842650e96d421a32a276573b40dfa6b7a1b3b52c))
+* make HTML folder 404 test more robust for CI environment ([9f5c605](https://github.com/adobe/helix-cli/commit/9f5c60546ca22faf611eedbb3735557ebaa83c0f))
+* mock both URL patterns for HTML folder proxy test ([7be689a](https://github.com/adobe/helix-cli/commit/7be689a90c7d85b451ca6c1d00a1a67b53483d68))
+* update test to handle proxy behavior correctly in CI ([52f8afa](https://github.com/adobe/helix-cli/commit/52f8afa6823f4bbc2e45ade57790c2cce722cf59))
+
+
+### Features
+
+* add --html-folder flag to serve HTML files without extensions ([682e8a2](https://github.com/adobe/helix-cli/commit/682e8a2dea8d835281a8d41eb0ef05e6c07d04b1))
+
 ## [16.13.2](https://github.com/adobe/helix-cli/compare/v16.13.1...v16.13.2) (2025-09-17)
 
 

package/README.md

@@ -212,6 +212,8 @@ These proxies use a private certificate authority (CA) to sign the certificates
 servers they intercept. To make Node.js trust the server certificate, you need to add
 the CA certificate to the list of trusted CAs.
 
+### Option 1: Using IT-provided CA certificate
+
 The CA certificate is typically provided by your IT department. You can ask them for
 the CA certificate and save it to a file, e.g. `my-ca.crt`.
 
@@ -223,7 +225,29 @@ export NODE_EXTRA_CA_CERTS=my-ca.crt
 aem up
 ```
 
-This will make Node.js trust the server certificate and `aem up` should work.
+### Option 2: Extracting certificate from browser
+
+If you don't have access to the CA certificate from your IT department, you can extract it directly
+from your browser:
+
+1. Access the AEM admin URL in your browser (e.g., `https://admin.hlx.page/sidekick/owner-name/repo-name/github-branch-name/config.json`)
+2. Click on the padlock icon in the address bar and view the certificate details
+3. Export the certificate chain as a Base64 encoded `.pem` file
+4. Save it to a directory (e.g., `certs/hlx.page.pem`)
+5. Set the environment variable and run aem:
+
+```bash
+export NODE_EXTRA_CA_CERTS=./certs/hlx.page.pem
+aem up
+```
+
+On Windows, use `set` instead of `export`:
+```cmd
+set NODE_EXTRA_CA_CERTS=./certs/hlx.page.pem
+aem up
+```
+
+Either approach will make Node.js trust the server certificate and `aem up` should work.
 
 ## `npm install` fails with `File exists: /opt/homebrew/bin/hlx`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/aem-cli",
-  "version": "16.13.2",
+  "version": "16.15.0",
   "description": "AEM CLI",
   "main": "index.js",
   "type": "module",

package/src/git-utils.js

@@ -135,6 +135,28 @@ export default class GitUtils {
     return false;
   }
 
+  /**
+   * Checks if a name is valid for use in a DNS subdomain.
+   * DNS labels must:
+   * - Be between 1 and 63 characters long
+   * - Contain only alphanumeric characters and hyphens
+   * - Not start or end with a hyphen
+   * - Not contain dots or other special characters
+   * @param {string} name the name to validate
+   * @returns {boolean} true if valid for DNS
+   */
+  static isValidDNSName(name) {
+    // Check length (DNS labels must be 1-63 characters)
+    if (!name || name.length > 63) {
+      return false;
+    }
+
+    // DNS labels can only contain alphanumeric characters and hyphens
+    // They cannot start or end with hyphens
+    // They cannot contain dots or other special characters
+    return /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(name);
+  }
+
   /**
    * Returns the name of the current branch. If `HEAD` is at a tag, the name of the tag
    * will be returned instead, if head is at a commit, fallback will be returned.
@@ -178,7 +200,11 @@ export default class GitUtils {
         ? await git.resolveRef({ fs, dir, ref: obj.object.object }) // annotated tag
         : oid; // lightweight tag
       if (commitSha === rev) {
-        return tag;
+        // Only return tags that are valid for DNS names
+        // Skip tags containing dots or other invalid characters
+        if (GitUtils.isValidDNSName(tag)) {
+          return tag;
+        }
       }
     }
 

package/src/server/HelixProject.js

@@ -9,7 +9,7 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
-import { resolve } from 'path';
+import path, { resolve } from 'path';
 import { lstat } from 'fs/promises';
 import { HelixServer } from './HelixServer.js';
 import { BaseProject } from './BaseProject.js';
@@ -78,6 +78,22 @@ export class HelixProject extends BaseProject {
     return this;
   }
 
+  withHtmlFolder(value) {
+    if (value) {
+      // Security: reject any paths with traversal patterns or absolute paths
+      if (path.isAbsolute(value) || value.includes('..') || value.startsWith('/')) {
+        throw new Error(`Invalid HTML folder name: ${value} only folders within the current workspace are allowed`);
+      }
+
+      this._htmlFolder = value;
+      this._server.withHtmlFolder(value);
+    } else {
+      this._htmlFolder = value;
+      this._server.withHtmlFolder(value);
+    }
+    return this;
+  }
+
   get proxyUrl() {
     return this._proxyUrl;
   }
@@ -115,6 +131,10 @@ export class HelixProject extends BaseProject {
     return this._headHtml;
   }
 
+  get htmlFolder() {
+    return this._htmlFolder;
+  }
+
   async init() {
     await super.init();
     this._indexer = new Indexer()
@@ -161,11 +181,27 @@ export class HelixProject extends BaseProject {
     }
   }
 
+  async initHtmlFolder() {
+    if (this._htmlFolder && this.liveReload) {
+      const htmlFolderPath = resolve(this.directory, this._htmlFolder);
+      try {
+        await lstat(htmlFolderPath);
+        this.log.debug(`Registered HTML folder for live-reload: ${this._htmlFolder}`);
+        // Watch all HTML files in the folder - only .html extension
+        this.liveReload.registerFiles([`${htmlFolderPath}/**/*.html`], `/${this._htmlFolder}/`);
+      } catch (e) {
+        this.log.error(`HTML folder '${this._htmlFolder}' does not exist`);
+        throw new Error(`HTML folder '${this._htmlFolder}' does not exist`);
+      }
+    }
+  }
+
   async start() {
     this.log.debug('Launching AEM dev server...');
     await super.start();
     await this.initHeadHtml();
     await this.init404Html();
+    await this.initHtmlFolder();
     if (this._indexer) {
       await this._indexer.init();
     }

package/src/server/HelixServer.js

@@ -13,6 +13,7 @@ import crypto from 'crypto';
 import express from 'express';
 import { promisify } from 'util';
 import path from 'path';
+import { lstat, readFile } from 'fs/promises';
 import compression from 'compression';
 import utils from './utils.js';
 import RequestContext from './RequestContext.js';
@@ -62,6 +63,12 @@ export class HelixServer extends BaseServer {
     return this;
   }
 
+  withHtmlFolder(value) {
+    // It's now sanitized in HelixProject.withHtmlFolder
+    this._htmlFolder = value;
+    return this;
+  }
+
   async handleLogin(req, res) {
     // disable autologin if login was called at least once
     this._autoLogin = false;
@@ -147,6 +154,86 @@ export class HelixServer extends BaseServer {
       .send('');
   }
 
+  /**
+   * HTML Folder handler - serves HTML files without extensions
+   * @param {Express.Request} req request
+   * @param {Express.Response} res response
+   * @param {Function} next next middleware
+   */
+  async handleHtmlFolderRequest(req, res, next) {
+    if (!this._htmlFolder) {
+      return next();
+    }
+
+    // Use Express's req.path for pathname extraction
+    const pathname = req.path;
+    const folderPrefix = `/${this._htmlFolder}/`;
+
+    // Check if the request is for the HTML folder
+    if (!pathname.startsWith(folderPrefix)) {
+      return next();
+    }
+
+    // Extract the path within the HTML folder
+    const relativePath = pathname.slice(folderPrefix.length);
+
+    // Security check: prevent path traversal with /../ anywhere in the path
+    if (relativePath.includes('/../')) {
+      return next();
+    }
+
+    // Don't process if it already has an extension
+    if (relativePath.includes('.')) {
+      return next();
+    }
+
+    // Build the HTML file path - only support .html extension
+    const htmlFile = path.join(this._project.directory, this._htmlFolder, `${relativePath}.html`);
+
+    // Security check: ensure the file is within the project directory
+    const relPath = path.relative(this._project.directory, htmlFile);
+    if (relPath.startsWith('..') || path.isAbsolute(relPath)) {
+      return next();
+    }
+
+    // Check if the HTML file exists and is a file
+    try {
+      const stats = await lstat(htmlFile);
+      if (!stats.isFile()) {
+        return next();
+      }
+    } catch (e) {
+      // File doesn't exist, continue to next handler
+      return next();
+    }
+
+    const sendFile = promisify(res.sendFile).bind(res);
+    const { log } = this;
+    const liveReload = this._liveReload;
+
+    // Register for live reload if enabled
+    if (liveReload) {
+      liveReload.startRequest(req.id, req.url);
+    }
+
+    // Serve the file
+    await sendFile(htmlFile, {
+      dotfiles: 'deny',
+      headers: {
+        'access-control-allow-origin': '*',
+        'content-type': 'text/html; charset=utf-8',
+      },
+    });
+
+    if (liveReload) {
+      liveReload.registerFile(req.id, htmlFile);
+      liveReload.endRequest(req.id);
+    }
+
+    log.debug(`served HTML file ${htmlFile} for ${req.url}`);
+    return undefined;
+  }
+
   /**
    * Proxy Mode route handler
    * @param {Express.Request} req request
@@ -183,16 +270,32 @@ export class HelixServer extends BaseServer {
 
     // try to serve static
     try {
-      await sendFile(filePath, {
-        dotfiles: 'allow',
-        headers: {
+      // Check if it's an HTML file and live reload is enabled
+      if (liveReload && filePath.endsWith('.html')) {
+        // Read the HTML file and inject the livereload script
+        let htmlContent = await readFile(filePath, 'utf-8');
+        htmlContent = utils.injectLiveReloadScript(htmlContent, this);
+
+        res.set({
+          'content-type': 'text/html; charset=utf-8',
           'access-control-allow-origin': '*',
-        },
-      });
-      if (liveReload) {
+        });
+        res.send(htmlContent);
         liveReload.registerFile(ctx.requestId, filePath);
+        log.debug(`${pfx}served local HTML file with livereload: ${filePath}`);
+      } else {
+        // Serve other files normally
+        await sendFile(filePath, {
+          dotfiles: 'allow',
+          headers: {
+            'access-control-allow-origin': '*',
+          },
+        });
+        if (liveReload) {
+          liveReload.registerFile(ctx.requestId, filePath);
+        }
+        log.debug(`${pfx}served local file ${filePath}`);
       }
-      log.debug(`${pfx}served local file ${filePath}`);
       return;
     } catch (e) {
       log.debug(`${pfx}unable to deliver local file ${ctx.path} - ${e.stack || e}`);
@@ -244,6 +347,14 @@ export class HelixServer extends BaseServer {
     this.app.post(LOGIN_ACK_ROUTE, express.json(), asyncHandler(this.handleLoginAck.bind(this)));
     this.app.options(LOGIN_ACK_ROUTE, asyncHandler(this.handleLoginAck.bind(this)));
 
+    // Add HTML folder handler before the general proxy handler
+    if (this._htmlFolder) {
+      // Only handle GET requests for the HTML folder path
+      const htmlFolderPattern = new RegExp(`^/${this._htmlFolder}/.*`);
+      this.app.get(htmlFolderPattern, asyncHandler(this.handleHtmlFolderRequest.bind(this)));
+      this.log.info(`Serving HTML files from folder: ${this._htmlFolder}`);
+    }
+
     const handler = asyncHandler(this.handleProxyModeRequest.bind(this));
     this.app.get(/.*/, handler);
     this.app.post(/.*/, handler);

package/src/up.cmd.js

@@ -54,6 +54,12 @@ export default class UpCommand extends AbstractServerCommand {
     return this;
   }
 
+  withHtmlFolder(value) {
+    // Basic validation - detailed validation done in HelixProject
+    this._htmlFolder = value;
+    return this;
+  }
+
   async doStop() {
     await super.doStop();
     if (this._watcher) {
@@ -105,7 +111,8 @@ export default class UpCommand extends AbstractServerCommand {
       .withPrintIndex(this._printIndex)
       .withAllowInsecure(this._allowInsecure)
       .withSiteToken(this._siteToken)
-      .withCookies(this._cookies);
+      .withCookies(this._cookies)
+      .withHtmlFolder(this._htmlFolder);
 
     this.log.info(chalk`{yellow     ___    ________  ___                          __      __ v${pkgJson.version}}`);
     this.log.info(chalk`{yellow    /   |  / ____/  |/  /  _____(_)___ ___  __  __/ /___ _/ /_____  _____}`);

package/src/up.js

@@ -115,6 +115,11 @@ export default function up() {
           type: 'boolean',
           default: false,
         })
+        .option('html-folder', {
+          alias: 'htmlFolder',
+          describe: 'Serve HTML files from this folder without extensions (e.g., /folder/file serves folder/file.html) use this to preview content changes if you do not have access to the authoring system',
+          type: 'string',
+        })
 
         .help();
     },
@@ -141,6 +146,7 @@ export default function up() {
         .withKill(argv.stopOther)
         .withCache(argv.alphaCache)
         .withCookies(argv.cookies)
+        .withHtmlFolder(argv.htmlFolder)
         .run();
     },
   };