npm - @adobe/aem-cli - Versions diffs - 16.15.13 → 16.16.0 - Mend

@adobe/aem-cli 16.15.13 → 16.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md +7 -0
package/README.md +21 -0
package/package.json +1 -1
package/src/server/HelixServer.js +108 -44
package/src/server/utils.js +250 -0
package/src/up.js +1 -1

package/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,10 @@
+# [16.16.0](https://github.com/adobe/helix-cli/compare/v16.15.13...v16.16.0) (2025-11-13)
+### Features
+* add .plain.html support for HTML folder serving ([#2631](https://github.com/adobe/helix-cli/issues/2631)) ([2186d4c](https://github.com/adobe/helix-cli/commit/2186d4c330f97db86849b9388e119b7d599c9fc1))
 ## [16.15.13](https://github.com/adobe/helix-cli/compare/v16.15.12...v16.15.13) (2025-11-11)

package/README.md CHANGED Viewed

@@ -74,6 +74,26 @@ This feature is especially helpful when:
 - Monitoring client-side behavior during development
 - Working with AI coding assistants that need visibility into both server and client logs
+### html folder for content preview
+The `--html-folder` option enables serving HTML files without extensions, useful for previewing content changes when you don't have access to the authoring system.
+```
+$ aem up --html-folder content
+```
+This enables two features:
+1. **Extension-less URLs**: Access `/content/page` to serve `content/page.html`
+2. **Plain HTML with metadata**: Create `content/page.plain.html` files that are automatically wrapped with proper HTML structure and metadata processing
+#### Plain HTML files (.plain.html)
+Plain HTML files contain only the main content and an optional metadata block. The CLI automatically:
+- Wraps content in `<html><head><body><header><main><footer>` structure
+- Merges in `head.html` content
+- The metadata block is removed from the rendered content and converted to meta tags in the `<head>`.
 ### setting up a self-signed cert for using https
 1. create the certificate
@@ -161,6 +181,7 @@ If present, `ALL_PROXY` is used as fallback if there is no other match.
 | `--livereload`    | `AEM_LIVERELOAD`    | `true`      | Enable automatic reloading of modified sources in browser.  |
 | `--no-livereload` | `AEM_NO_LIVERELOAD` | `false`     | Disable live-reload.                                        |
 | `--forward-browser-logs` | `AEM_FORWARD_BROWSER_LOGS` | `false` | Forward browser console logs to terminal.            |
+| `--html-folder`   | `AEM_HTML_FOLDER`   | undefined   | Serve HTML files from folder without extensions. Supports .html and .plain.html files. |
 | `--open`          | `AEM_OPEN`          | `/`         | Open a browser window at specified path after server start. |
 | `--no-open`       | `AEM_NO_OPEN`       | `false`     | Disable automatic opening of browser window.                |
 | `--tls-key`       | `AEM_TLS_KEY`       | undefined   | Path to .key file (for enabling TLS)                        |

package/package.json CHANGED Viewed

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

package/src/server/HelixServer.js CHANGED Viewed

@@ -154,6 +154,90 @@ export class HelixServer extends BaseServer {
       .send('');
   }
+  /**
+   * Resolves which HTML file to serve from the HTML folder
+   * @param {string} relativePath path relative to HTML folder
+   * @returns {Promise<{file: string, isPlain: boolean}|null>} resolved file info or null
+   */
+  async resolveHtmlFolderFile(relativePath) {
+    // Security check: prevent path traversal with /../ anywhere in the path
+    if (relativePath.includes('/../')) {
+      return null;
+    }
+    // Don't process if it already has an extension
+    if (relativePath.includes('.')) {
+      return null;
+    }
+    // Try .html first
+    const htmlFile = path.resolve(
+      this._project.directory,
+      this._htmlFolder,
+      `${relativePath}.html`,
+    );
+    if (!utils.validatePathSecurity(htmlFile, this._project.directory)) {
+      return null;
+    }
+    try {
+      const stats = await lstat(htmlFile);
+      if (stats.isFile()) {
+        return { file: htmlFile, isPlain: false };
+      }
+    } catch (e) {
+      // .html not found, try .plain.html
+    }
+    // Try .plain.html
+    const plainHtmlFile = path.resolve(
+      this._project.directory,
+      this._htmlFolder,
+      `${relativePath}.plain.html`,
+    );
+    if (!utils.validatePathSecurity(plainHtmlFile, this._project.directory)) {
+      return null;
+    }
+    try {
+      const stats = await lstat(plainHtmlFile);
+      if (stats.isFile()) {
+        return { file: plainHtmlFile, isPlain: true };
+      }
+    } catch (e) {
+      // Neither exists
+    }
+    return null;
+  }
+  /**
+   * Transforms .plain.html content into complete HTML with head.html
+   * @param {string} plainHtmlFile path to .plain.html file
+   * @returns {Promise<string>} complete HTML document
+   */
+  async transformPlainHtml(plainHtmlFile) {
+    const plainContent = await readFile(plainHtmlFile, 'utf-8');
+    // Extract metadata and clean content
+    const { content, metadata } = utils.extractMetadataBlock(plainContent);
+    // Extract default metadata values from content
+    const defaults = utils.extractDefaultMetadata(content);
+    // Get head HTML using existing HeadHtmlSupport
+    await this._project.headHtml.update();
+    const headHtml = this._project.headHtml.localHtml || '';
+    // Generate meta tags from metadata with defaults
+    const metaTags = utils.generateMetaTags(metadata, defaults);
+    // Wrap in complete HTML structure
+    return utils.wrapPlainHtml(content, headHtml, metaTags);
+  }
   /**
    * HTML Folder handler - serves HTML files without extensions
    * @param {Express.Request} req request
@@ -177,41 +261,12 @@ export class HelixServer extends BaseServer {
     // 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('.')) {
+    // Resolve which file to serve (.html or .plain.html)
+    const resolvedFile = await this.resolveHtmlFolderFile(relativePath);
+    if (!resolvedFile) {
       return next();
     }
-    // Build the HTML file path - only support .html extension
-    const htmlFile = path.resolve(this._project.directory, this._htmlFolder, `${relativePath}.html`);
-    // Security check: ensure the file is within the project directory
-    // Use resolve to normalize both paths before comparing
-    const resolvedProjectDir = path.resolve(this._project.directory);
-    const relPath = path.relative(resolvedProjectDir, htmlFile);
-    // Only check for path traversal - remove the incorrect isAbsolute check
-    if (relPath.startsWith('..')) {
-      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;
@@ -220,24 +275,33 @@ export class HelixServer extends BaseServer {
       liveReload.startRequest(req.id, req.url);
     }
-    // Serve the file
-    // Use the root option to specify the base directory for sendFile
-    // This prevents issues with worktrees in subdirectories
-    await sendFile(path.basename(htmlFile), {
-      root: path.dirname(htmlFile),
-      dotfiles: 'deny',
-      headers: {
-        'access-control-allow-origin': '*',
-        'content-type': 'text/html; charset=utf-8',
-      },
+    // Load content (handle .plain.html transformation)
+    let htmlContent;
+    if (resolvedFile.isPlain) {
+      htmlContent = await this.transformPlainHtml(resolvedFile.file);
+    } else {
+      htmlContent = await readFile(resolvedFile.file, 'utf-8');
+    }
+    // Inject live reload script
+    if (liveReload) {
+      htmlContent = utils.injectLiveReloadScript(htmlContent, this);
+    }
+    // Send response
+    res.set({
+      'content-type': 'text/html; charset=utf-8',
+      'access-control-allow-origin': '*',
     });
+    res.send(htmlContent);
+    // Register with live reload
     if (liveReload) {
-      liveReload.registerFile(req.id, htmlFile);
+      liveReload.registerFile(req.id, resolvedFile.file);
       liveReload.endRequest(req.id);
     }
-    log.debug(`served HTML file ${htmlFile} for ${req.url}`);
+    log.debug(`served HTML file ${resolvedFile.file} for ${req.url}`);
     return undefined;
   }

package/src/server/utils.js CHANGED Viewed

@@ -17,6 +17,8 @@ import { PassThrough } from 'stream';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import cookie from 'cookie';
+import { unified } from 'unified';
+import rehypeParse from 'rehype-parse';
 import { getFetch } from '../fetch-utils.js';
 // Load console interceptor script at startup
@@ -525,6 +527,254 @@ window.LiveReloadOptions = {
     text = text.replaceAll(re, (match, arg, q1, value, q2) => (`${arg}=${q1}${value || '/'}${q2}`));
     return Buffer.from(text, 'utf-8');
   },
+  /**
+   * Escapes HTML entities for use in attributes
+   * @param {string} text text to escape
+   * @returns {string} escaped text
+   */
+  escapeHtml(text) {
+    return text
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#039;');
+  },
+  /**
+   * Extracts text content from HTML using proper HTML parsing
+   * @param {string} html HTML content to extract text from
+   * @returns {string} plain text content
+   */
+  extractTextFromHtml(html) {
+    // Helper to recursively extract text from AST nodes
+    function extractText(node) {
+      if (node.type === 'text') {
+        return node.value;
+      }
+      if (node.children) {
+        return node.children.map(extractText).join('');
+      }
+      return '';
+    }
+    try {
+      const ast = unified()
+        .use(rehypeParse, { fragment: true })
+        .parse(html);
+      return extractText(ast).trim();
+    } catch (e) {
+      // If parsing fails, return empty string to avoid XSS vulnerabilities
+      return '';
+    }
+  },
+  /**
+   * Validates that a file path is within a base directory (security check)
+   * @param {string} filePath absolute file path to validate
+   * @param {string} baseDirectory base directory path
+   * @returns {boolean} true if path is safe, false if it tries to escape base directory
+   */
+  validatePathSecurity(filePath, baseDirectory) {
+    const resolvedBaseDir = path.resolve(baseDirectory);
+    const relPath = path.relative(resolvedBaseDir, filePath);
+    return !relPath.startsWith('..');
+  },
+  /**
+   * Extracts metadata block from plain HTML content
+   * @param {string} html HTML content with potential metadata block
+   * @returns {{content: string, metadata: object}} cleaned content and metadata object
+   */
+  extractMetadataBlock(html) {
+    // The metadata block structure is:
+    // <div>
+    //   <div class="metadata">
+    //     <div><div>key</div><div>value</div></div>
+    //   </div>
+    // </div>
+    // Find the outer div containing the metadata div
+    const outerDivRegex = /<div>\s*<div class="metadata">/;
+    const outerMatch = html.match(outerDivRegex);
+    if (!outerMatch) {
+      return { content: html, metadata: {} };
+    }
+    // Find the matching closing </div></div> by counting nested divs
+    // Start after <div><div class="metadata">
+    const startIndex = outerMatch.index + outerMatch[0].length;
+    let depth = 2; // Already inside two divs
+    let endIndex = startIndex;
+    let closingDivCount = 0;
+    for (let i = startIndex; i < html.length && closingDivCount < 2; i += 1) {
+      if (html.substr(i, 5) === '<div>') {
+        depth += 1;
+      } else if (html.substr(i, 6) === '</div>') {
+        depth -= 1;
+        if (depth < 2) {
+          closingDivCount += 1;
+          if (closingDivCount === 2) {
+            endIndex = i + 6; // Include the last </div>
+          }
+        }
+      }
+    }
+    if (closingDivCount !== 2) {
+      // Malformed HTML, return as-is
+      return { content: html, metadata: {} };
+    }
+    // Extract the metadata block content and remove entire outer div from HTML
+    const fullMetadataBlock = html.substring(outerMatch.index, endIndex);
+    const metadataBlock = html.substring(startIndex, endIndex - 12); // -12 for </div></div>
+    const cleanedContent = html.replace(fullMetadataBlock, '').trim();
+    // Parse metadata block to extract key-value pairs
+    const pairRegex = /<div>\s*<div>([^<]+)<\/div>\s*<div>([\s\S]*?)<\/div>\s*<\/div>/g;
+    const metadata = {};
+    let pairMatch;
+    // eslint-disable-next-line no-cond-assign
+    while ((pairMatch = pairRegex.exec(metadataBlock)) !== null) {
+      const key = pairMatch[1].trim();
+      let value = pairMatch[2].trim();
+      // Handle <img> tags - extract src
+      const imgMatch = value.match(/<img[^>]+src="([^"]+)"/);
+      if (imgMatch) {
+        [, value] = imgMatch;
+      } else {
+        // Use proper HTML parsing to extract text content
+        value = utils.extractTextFromHtml(value);
+      }
+      metadata[key] = value;
+    }
+    return { content: cleanedContent, metadata };
+  },
+  /**
+   * Extracts default metadata values from HTML content
+   * @param {string} content HTML content to extract defaults from
+   * @returns {object} default metadata values
+   */
+  extractDefaultMetadata(content) {
+    const defaults = {};
+    // Extract title from first H1
+    const h1Match = content.match(/<h1[^>]*>(.*?)<\/h1>/i);
+    if (h1Match) {
+      // Use proper HTML parsing to extract text
+      defaults.title = utils.extractTextFromHtml(h1Match[1]);
+    }
+    // Extract description from first paragraph with 10+ words
+    const pMatch = content.match(/<p[^>]*>(.*?)<\/p>/i);
+    if (pMatch) {
+      // Use proper HTML parsing to extract text
+      const text = utils.extractTextFromHtml(pMatch[1]);
+      const wordCount = text.split(/\s+/).length;
+      if (wordCount >= 10) {
+        defaults.description = text;
+      }
+    }
+    // Extract image from first img tag
+    const imgMatch = content.match(/<img[^>]+src="([^"]+)"/i);
+    if (imgMatch) {
+      [, defaults.image] = imgMatch;
+    }
+    return defaults;
+  },
+  /**
+   * Generates meta tags from metadata object with AEM.live special property support
+   * @param {object} metadata key-value pairs of metadata
+   * @param {object} defaults default values extracted from content
+   * @returns {string} HTML string of meta tags
+   */
+  generateMetaTags(metadata, defaults = {}) {
+    // Handle title:suffix special property
+    let title = metadata.title || defaults.title || '';
+    const titleSuffix = metadata['title:suffix'];
+    if (titleSuffix && title) {
+      title = `${title} ${titleSuffix}`;
+    }
+    // Apply defaults for missing values
+    const description = metadata.description || defaults.description || '';
+    const image = metadata.image || defaults.image || '/default-meta-image.png';
+    // Build final metadata object with computed values
+    const finalMetadata = { ...metadata };
+    if (title) finalMetadata.title = title;
+    if (description) finalMetadata.description = description;
+    if (image) finalMetadata.image = image;
+    // Remove special properties that shouldn't become meta tags
+    delete finalMetadata['title:suffix'];
+    // Generate meta tags (both standard and OG format)
+    const ogFields = ['title', 'description', 'image', 'url'];
+    let metaTags = '';
+    // eslint-disable-next-line no-restricted-syntax
+    for (const [key, value] of Object.entries(finalMetadata)) {
+      // Skip empty values
+      if (!value) {
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+      // Handle 'tags' property specially - create article:tag for each
+      if (key === 'tags') {
+        // Split by comma or newline
+        const tagList = value.split(/[,\n]/).map((t) => t.trim()).filter((t) => t);
+        // eslint-disable-next-line no-restricted-syntax
+        for (const tag of tagList) {
+          metaTags += `<meta property="article:tag" content="${utils.escapeHtml(tag)}">`;
+        }
+        // Don't create standard name= tag for 'tags'
+      } else if (key === 'canonical') {
+        // Handle canonical specially
+        metaTags += `<link rel="canonical" href="${utils.escapeHtml(value)}">`;
+        metaTags += `<meta property="og:url" content="${utils.escapeHtml(value)}">`;
+        metaTags += `<meta name="twitter:url" content="${utils.escapeHtml(value)}">`;
+        // Don't create standard name= tag
+      } else {
+        // Standard meta tag
+        metaTags += `<meta name="${key}" content="${utils.escapeHtml(value)}">`;
+        // Open Graph meta tag for common fields
+        if (ogFields.includes(key.toLowerCase())) {
+          metaTags += `<meta property="og:${key}" content="${utils.escapeHtml(value)}">`;
+          // Add twitter card tags for common fields
+          metaTags += `<meta name="twitter:${key}" content="${utils.escapeHtml(value)}">`;
+        }
+      }
+    }
+    return metaTags;
+  },
+  /**
+   * Wraps plain HTML content in complete HTML structure
+   * @param {string} content plain HTML content
+   * @param {string} headHtml head.html content
+   * @param {string} metaTags generated meta tags
+   * @returns {string} complete HTML document
+   */
+  wrapPlainHtml(content, headHtml, metaTags) {
+    const fullHead = headHtml + metaTags;
+    return `<html><head>${fullHead}</head><body><header></header><main>${content}</main><footer></footer></body></html>`;
+  },
 };
 export default Object.freeze(utils);

package/src/up.js CHANGED Viewed

@@ -117,7 +117,7 @@ export default function up() {
         })
         .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',
+          describe: 'Serve HTML files from this folder without extensions (e.g., /folder/file serves folder/file.html or folder/file.plain.html) use this to preview content changes if you do not have access to the authoring system',
           type: 'string',
         })