@adobe/aem-cli 16.13.2 → 16.14.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+# [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/package.json

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

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 } 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
@@ -244,6 +331,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();
     },
   };