@adobe/aem-cli 16.17.1 → 16.18.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [16.18.0](https://github.com/adobe/helix-cli/compare/v16.17.1...v16.18.0) (2026-04-16)
+
+
+### Features
+
+* aem content ([#2689](https://github.com/adobe/helix-cli/issues/2689)) ([5524b6d](https://github.com/adobe/helix-cli/commit/5524b6d63949a1d45efe35479a31ab55e62f78ef))
+
 ## [16.17.1](https://github.com/adobe/helix-cli/compare/v16.17.0...v16.17.1) (2026-04-08)
 
 

package/README.md

@@ -80,7 +80,7 @@ The `--html-folder` option enables serving HTML files without extensions, useful
 
 ```
 $ aem up --html-folder drafts                      # serves at /drafts/*
-$ aem up --html-folder content --html-mount /       # serves at /* (root)
+$ aem up --html-folder html --html-mount /       # serves at /* (root)
 $ aem up --html-folder drafts --html-mount /preview # serves at /preview/*
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/aem-cli",
-  "version": "16.17.1",
+  "version": "16.18.0",
   "description": "AEM CLI",
   "main": "index.js",
   "type": "module",
@@ -48,12 +48,14 @@
     "@adobe/helix-shared-config": "11.1.20",
     "@adobe/helix-shared-git": "3.0.23",
     "@adobe/helix-shared-indexer": "2.2.7",
+    "@adobe/helix-shared-process-queue": "3.1.6",
     "camelcase": "9.0.0",
     "chalk-template": "1.1.2",
     "chokidar": "5.0.0",
     "compression": "1.8.1",
     "cookie": "1.1.1",
     "cookie-parser": "1.4.7",
+    "diff": "8.0.3",
     "dotenv": "17.3.1",
     "express": "5.2.1",
     "faye-websocket": "0.11.4",
@@ -61,13 +63,16 @@
     "glob": "13.0.6",
     "glob-to-regexp": "0.4.1",
     "hast-util-select": "6.0.4",
+    "hast-util-to-html": "9.0.5",
     "http-proxy-agent": "8.0.0",
     "https-proxy-agent": "8.0.0",
     "ignore": "7.0.5",
     "ini": "6.0.0",
     "isomorphic-git": "1.37.4",
     "jose": "6.2.2",
+    "mime": "4.1.0",
     "livereload-js": "4.0.2",
+    "node-diff3": "3.2.0",
     "node-fetch": "3.3.2",
     "open": "11.0.0",
     "progress": "2.0.3",

package/src/cli.js

@@ -112,6 +112,9 @@ export default class CLI {
           this._commands[cmd] = (await import(`./${cmd}.js`)).default();
         }
       }
+      if (!this._commands.content) {
+        this._commands.content = (await import('./content/content.js')).default();
+      }
     }
     return this;
   }

package/src/content/add.cmd.js

@@ -0,0 +1,133 @@
+/*
+ * Copyright 2026 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 fse from 'fs-extra';
+import git from 'isomorphic-git';
+import { CONTENT_DIR, CONFIG_FILE } from './content-shared.js';
+
+/**
+ * Paths for git add are relative to the content repo root. Accept optional
+ * `content/…` (or `{CONTENT_DIR}/…`) so shells can tab-complete from the project root.
+ * @param {string} raw
+ * @returns {string}
+ */
+export function normalizePathForContentAdd(raw) {
+  let s = String(raw).trim().replace(/\\/g, '/');
+  while (s.startsWith('./')) {
+    s = s.slice(2);
+  }
+  const prefix = `${CONTENT_DIR}/`;
+  if (s === CONTENT_DIR || s === `${CONTENT_DIR}/`) {
+    return '.';
+  }
+  if (s.startsWith(prefix)) {
+    const rest = s.slice(prefix.length);
+    return rest.length > 0 ? rest : '.';
+  }
+  return s.length > 0 ? s : '.';
+}
+
+/**
+ * Whether a repo-relative path is covered by an `aem content add` path (`.` = whole tree).
+ * @param {string} filepath
+ * @param {string} scope normalized path from {@link normalizePathForContentAdd}
+ */
+export function filepathInContentAddScope(filepath, scope) {
+  if (scope === '.' || scope === '') {
+    return true;
+  }
+  const s = scope.replace(/\/$/, '');
+  return filepath === s || filepath.startsWith(`${s}/`);
+}
+
+/**
+ * isomorphic-git `add` only walks paths that exist on disk, so deletions are never staged.
+ * Stage removals for tracked files missing from the workdir (same idea as `git add -u` for
+ * those scopes).
+ * @param {import('isomorphic-git').FsClient} fsClient
+ * @param {string} dir content repo root
+ * @param {string[]} scopes normalized add paths
+ * @returns {Promise<number>} number of index entries removed
+ */
+export async function stageDeletionsForContentAddScopes(fsClient, dir, scopes) {
+  const matrix = await git.statusMatrix({ fs: fsClient, dir });
+  let n = 0;
+  for (const [filepath, head, workdir, stage] of matrix) {
+    const unstagedDelete = head === 1 && workdir === 0 && stage !== 0;
+    const inScope = scopes.some((sc) => filepathInContentAddScope(filepath, sc));
+    if (unstagedDelete && inScope) {
+      // eslint-disable-next-line no-await-in-loop
+      await git.remove({ fs: fsClient, dir, filepath });
+      n += 1;
+    }
+  }
+  return n;
+}
+
+function isNotFoundError(err) {
+  return err?.code === 'NotFoundError' || err?.name === 'NotFoundError';
+}
+
+export default class AddCommand {
+  constructor(logger) {
+    this.log = logger;
+    this._dir = process.cwd();
+    /** @type {string[]} */
+    this._paths = ['.'];
+  }
+
+  withDirectory(dir) {
+    this._dir = dir;
+    return this;
+  }
+
+  /**
+   * @param {string[]} paths paths relative to content/ (default ["."])
+   */
+  withPaths(paths) {
+    this._paths = paths && paths.length > 0 ? paths : ['.'];
+    return this;
+  }
+
+  async run() {
+    const { log } = this;
+    const contentDir = path.resolve(this._dir, CONTENT_DIR);
+    const configPath = path.join(contentDir, CONFIG_FILE);
+
+    if (!await fse.pathExists(configPath)) {
+      throw new Error(`No config found at ${configPath}. Run 'aem content clone' first.`);
+    }
+
+    const normalized = this._paths.map((p) => normalizePathForContentAdd(p));
+
+    for (const fp of normalized) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await git.add({ fs, dir: contentDir, filepath: fp });
+      } catch (err) {
+        if (!isNotFoundError(err)) {
+          throw err;
+        }
+        // Deleted directory/file: `add` cannot lstat the path; stage removal if it was tracked.
+        // eslint-disable-next-line no-await-in-loop
+        const staged = await stageDeletionsForContentAddScopes(fs, contentDir, [fp]);
+        if (staged === 0) {
+          throw err;
+        }
+      }
+    }
+    // `git add .` never visits missing files — stage tracked deletions under the requested paths.
+    await stageDeletionsForContentAddScopes(fs, contentDir, normalized);
+    log.info(`Staged: ${normalized.join(', ')}`);
+  }
+}

package/src/content/add.js

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2026 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 { getOrCreateLogger } from '../log-common.js';
+
+export default function add() {
+  let executor;
+  return {
+    set executor(value) {
+      executor = value;
+    },
+    command: 'add [files..]',
+    description: 'Stage changes in content/ (like git add)',
+    builder: (yargs) => {
+      yargs
+        .positional('files', {
+          describe:
+            'Paths under content/ to stage, or the same with a content/ prefix for tab completion (default: all)',
+          type: 'string',
+          array: true,
+        })
+        .help();
+    },
+    handler: async (argv) => {
+      if (!executor) {
+        const AddCommand = (await import('./add.cmd.js')).default;
+        executor = new AddCommand(getOrCreateLogger(argv));
+      }
+      const { files } = argv;
+      let paths = [];
+      if (Array.isArray(files)) {
+        paths = files;
+      } else if (files) {
+        paths = [files];
+      }
+      await executor.withPaths(paths).run();
+    },
+  };
+}

package/src/content/clone.cmd.js

@@ -0,0 +1,214 @@
+/*
+ * Copyright 2026 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 readline from 'readline';
+import path from 'path';
+import fse from 'fs-extra';
+import git from 'isomorphic-git';
+import processQueue from '@adobe/helix-shared-process-queue';
+import GitUtils from '../git-utils.js';
+import { prompt } from '../cli-util.js';
+import { DaClient } from './da-api.js';
+import { getValidToken } from './da-auth.js';
+import {
+  CONTENT_DIR,
+  CONFIG_FILE,
+  GIT_AUTHOR,
+  LARGE_CLONE_FILE_THRESHOLD,
+  CONTENT_IO_CONCURRENCY,
+} from './content-shared.js';
+import { writeSyncedRef, ensureGitIgnored } from './content-git.js';
+
+/**
+ * @param {*} log logger with .warn
+ * @param {number} fileCount
+ * @param {boolean} assumeYes
+ */
+async function confirmLargeCloneIfNeeded(log, fileCount, assumeYes) {
+  if (fileCount <= LARGE_CLONE_FILE_THRESHOLD) {
+    return;
+  }
+  log.warn(
+    `This clone lists ${fileCount} files (more than ${LARGE_CLONE_FILE_THRESHOLD.toLocaleString()}). `
+    + 'Downloading may take a long time and use substantial disk space.',
+  );
+  if (assumeYes) {
+    return;
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      `Large clone (${fileCount} files) needs confirmation. Re-run with --yes, or clone a smaller path with --path.`,
+    );
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await prompt(rl, 'Do you really want to proceed? [y/N] ');
+    if (!/^y(es)?$/i.test(String(answer).trim())) {
+      throw new Error('Clone cancelled.');
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+export default class CloneCommand {
+  constructor(logger) {
+    this.log = logger;
+    this._dir = process.cwd();
+    this._force = false;
+    this._assumeYes = false;
+    this._rootPath = null;
+  }
+
+  withDirectory(dir) {
+    this._dir = dir;
+    return this;
+  }
+
+  withToken(token) {
+    this._token = token;
+    return this;
+  }
+
+  withForce(force) {
+    this._force = force;
+    return this;
+  }
+
+  withAssumeYes(yes) {
+    this._assumeYes = !!yes;
+    return this;
+  }
+
+  withRootPath(daPath) {
+    this._rootPath = daPath;
+    return this;
+  }
+
+  async run() {
+    const { log } = this;
+
+    if (this._rootPath == null) {
+      throw new Error('Clone root path was not set (internal error).');
+    }
+
+    // 1. Resolve org/repo from git remote
+    const originUrl = await GitUtils.getOriginURL(this._dir);
+    if (!originUrl) {
+      throw new Error('No git remote found. Run `aem content clone` inside an AEM project directory.');
+    }
+    const org = originUrl.owner;
+    const { repo } = originUrl;
+    log.info(`Cloning content from da.live: ${org}/${repo}${this._rootPath === '/' ? '' : ` @ ${this._rootPath}`}`);
+
+    // 2. Ensure target path is available (do not create content/ until after file count is known)
+    const contentDir = path.resolve(this._dir, CONTENT_DIR);
+    if (await fse.pathExists(contentDir)) {
+      if (!this._force) {
+        throw new Error(`'${CONTENT_DIR}' already exists. Use --force to overwrite.`);
+      }
+      await fse.remove(contentDir);
+    }
+
+    // 3. Resolve token
+    const token = await getValidToken(log, this._token, this._dir);
+
+    // 4. Fetch file list (no local content dir required yet)
+    const client = new DaClient(token);
+    log.info('Fetching file list...');
+    const showDiscoveryProgress = process.stdout.isTTY;
+    const files = await client.listAll(org, repo, this._rootPath, showDiscoveryProgress
+      ? (n) => {
+        process.stdout.write(`\r  ${n} file(s) discovered so far...`);
+      }
+      : undefined);
+    if (showDiscoveryProgress) {
+      process.stdout.write('\n');
+    }
+    log.info(`Found ${files.length} file(s).`);
+
+    await confirmLargeCloneIfNeeded(log, files.length, this._assumeYes);
+
+    // 5. Prepare content directory and project .gitignore
+    await fse.ensureDir(contentDir);
+    await ensureGitIgnored(this._dir, CONTENT_DIR);
+
+    log.info('Downloading...');
+
+    // 6. Download files (bounded concurrency)
+    const downloadResults = await processQueue(
+      files,
+      async (file) => {
+        const prefix = `/${org}/${repo}`;
+        if (!file.path.startsWith(prefix)) {
+          log.warn(`  skip (unexpected path, missing org/repo prefix): ${file.path}`);
+          return { status: 404 };
+        }
+        const daPath = file.path.slice(prefix.length) || '/';
+        const localPath = path.join(contentDir, ...daPath.split('/').filter(Boolean));
+        try {
+          const res = await client.getSource(org, repo, daPath);
+          if (!res) {
+            log.warn(`  skip (not found): ${daPath}`);
+            return { status: 404 };
+          }
+          const buffer = await res.buffer();
+          await fse.ensureDir(path.dirname(localPath));
+          await fse.writeFile(localPath, buffer);
+          log.info(`  ✓ ${daPath}`);
+          return { status: 200, daPath };
+        } catch (err) {
+          log.warn(`  ✗ ${daPath}: ${err.message}`);
+          return { status: err.status || 500 };
+        }
+      },
+      CONTENT_IO_CONCURRENCY,
+    );
+
+    const downloaded = [];
+    let errors = 0;
+    for (const r of downloadResults) {
+      if (r.status === 200) {
+        downloaded.push(r.daPath);
+      } else if (r.status !== 404) {
+        errors += 1;
+      }
+    }
+
+    // 7. Init git repo and commit as baseline
+    await git.init({ fs, dir: contentDir, defaultBranch: 'main' });
+    await fse.writeFile(path.join(contentDir, '.gitignore'), `${CONFIG_FILE}\n`);
+    for (const daPath of downloaded) {
+      // eslint-disable-next-line no-await-in-loop
+      await git.add({ fs, dir: contentDir, filepath: daPath.replace(/^\//, '') });
+    }
+    await git.add({ fs, dir: contentDir, filepath: '.gitignore' });
+    await git.commit({
+      fs,
+      dir: contentDir,
+      message: `clone: ${org}/${repo}${this._rootPath === '/' ? '' : ` (${this._rootPath})`}`,
+      author: GIT_AUTHOR,
+    });
+    const headOid = await git.resolveRef({ fs, dir: contentDir, ref: 'HEAD' });
+    await writeSyncedRef(fs, contentDir, headOid);
+
+    // 8. Write config (not tracked by git)
+    await fse.writeJson(path.join(contentDir, CONFIG_FILE), {
+      org,
+      repo,
+      rootPath: this._rootPath,
+    }, { spaces: 2 });
+
+    log.info(`\nDone. ${downloaded.length} file(s) downloaded${errors > 0 ? `, ${errors} error(s)` : ''}.`);
+    log.info(`Content saved to ./${CONTENT_DIR}/`);
+  }
+}

package/src/content/clone.js

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2026 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 { getOrCreateLogger } from '../log-common.js';
+import { normalizeDaPath, LARGE_CLONE_FILE_THRESHOLD } from './content-shared.js';
+
+export default function clone() {
+  let executor;
+  return {
+    set executor(value) {
+      executor = value;
+    },
+    command: 'clone',
+    description: 'Clone da.live content locally into content/',
+    builder: (yargs) => {
+      yargs
+        .option('path', {
+          describe: 'da.live folder to clone (e.g. /ca/fr_ca). Omit only when using --all.',
+          type: 'string',
+        })
+        .option('all', {
+          describe: 'Clone the entire site content (large). Use instead of --path.',
+          type: 'boolean',
+          default: false,
+        })
+        .option('token', {
+          describe: 'IMS Bearer token for da.live authentication',
+          type: 'string',
+        })
+        .option('force', {
+          describe: 'Overwrite existing content/ without prompting',
+          type: 'boolean',
+          default: false,
+        })
+        .option('yes', {
+          alias: 'y',
+          describe: `Proceed without prompting when the clone has more than ${LARGE_CLONE_FILE_THRESHOLD.toLocaleString()} files`,
+          type: 'boolean',
+          default: false,
+        })
+        .check((argv) => {
+          if (argv.all && argv.path !== undefined && argv.path !== '') {
+            return 'Do not use --path together with --all.';
+          }
+          if (!argv.all && (argv.path === undefined || argv.path === '')) {
+            return 'Missing --path. Example: aem content clone --path /ca/fr_ca. Use --all to clone all the content.';
+          }
+          return true;
+        })
+        .help();
+    },
+    handler: async (argv) => {
+      if (!executor) {
+        const CloneCommand = (await import('./clone.cmd.js')).default;
+        executor = new CloneCommand(getOrCreateLogger(argv));
+      }
+      const rootPath = argv.all ? '/' : normalizeDaPath(argv.path);
+      await executor
+        .withToken(argv.token)
+        .withForce(argv.force)
+        .withAssumeYes(argv.yes)
+        .withRootPath(rootPath)
+        .run();
+    },
+  };
+}

package/src/content/commit.cmd.js

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2026 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 fse from 'fs-extra';
+import git from 'isomorphic-git';
+import { CONTENT_DIR, CONFIG_FILE, GIT_AUTHOR } from './content-shared.js';
+
+export default class CommitCommand {
+  constructor(logger) {
+    this.log = logger;
+    this._dir = process.cwd();
+    this._message = '';
+  }
+
+  withDirectory(dir) {
+    this._dir = dir;
+    return this;
+  }
+
+  withMessage(message) {
+    this._message = message || '';
+    return this;
+  }
+
+  async run() {
+    const { log } = this;
+    const contentDir = path.resolve(this._dir, CONTENT_DIR);
+    const configPath = path.join(contentDir, CONFIG_FILE);
+
+    if (!await fse.pathExists(configPath)) {
+      throw new Error(`No config found at ${configPath}. Run 'aem content clone' first.`);
+    }
+
+    const msg = String(this._message).trim();
+    if (!msg) {
+      throw new Error('Commit message is required. Use -m "your message".');
+    }
+
+    const oid = await git.commit({
+      fs,
+      dir: contentDir,
+      message: msg,
+      author: GIT_AUTHOR,
+    });
+    log.info(`Committed ${oid.slice(0, 7)}`);
+  }
+}

package/src/content/commit.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2026 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 { getOrCreateLogger } from '../log-common.js';
+
+export default function commit() {
+  let executor;
+  return {
+    set executor(value) {
+      executor = value;
+    },
+    command: 'commit',
+    description: 'Commit staged changes in content/ (like git commit)',
+    builder: (yargs) => {
+      yargs
+        .option('m', {
+          alias: 'message',
+          describe: 'Commit message',
+          type: 'string',
+          demandOption: true,
+        })
+        .help();
+    },
+    handler: async (argv) => {
+      if (!executor) {
+        const CommitCommand = (await import('./commit.cmd.js')).default;
+        executor = new CommitCommand(getOrCreateLogger(argv));
+      }
+      await executor.withMessage(argv.m).run();
+    },
+  };
+}