@sous-io/sous 0.1.0

package/src/lib/state.ts

@@ -0,0 +1,135 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import type { VarScope } from "./settings.js";
+
+// --- Types ---------------------------------------------------------------------------------------
+
+/** A single file entry tracked by the state file. */
+export type StateFileEntry = {
+  /** Absolute destination path of the output file. */
+  dest: string;
+  /** SHA-256 hex hash of the source content at build time. */
+  srcHash: string;
+  /** SHA-256 hex hash of the destination file content at build time. */
+  destHash: string;
+  /** File size in bytes. */
+  size: number;
+  /** ISO timestamp when this file was last written. */
+  builtAt: string;
+};
+
+/** The full state tracked for a project across builds. */
+export type StateFile = {
+  /** ISO timestamp of the last successful build. */
+  lastBuild: string;
+  /** The resolved variable scope used during the last build. */
+  resolvedVars: VarScope;
+  /** Absolute paths of directories that Sous created (not pre-existing). */
+  dirs: string[];
+  /** All output files written by Sous for this project. */
+  files: StateFileEntry[];
+};
+
+// --- StateService --------------------------------------------------------------------------------
+
+/**
+ * Manages reading and writing the project state file.
+ * The state file tracks all files and directories Sous has written,
+ * enabling xcv prune and xcv clear to clean up precisely.
+ */
+export class StateService {
+  /**
+   * Derives the state file path for a project.
+   *
+   * Precedence:
+   *   1. A `stateFilePath` variable in the PROJECT scope (explicit override).
+   *   2. `<sousDir>/sous.state.json` for a single-project config, or
+   *      `<sousDir>/<key>.sous.state.json` when the config defines several
+   *      projects (they must not share one state file).
+   *   3. `<cwd>/<key>.sous.state.json` as a last resort.
+   *
+   * @param projectKey - The project's key in the config's `projects` map.
+   * @param projectVars - The resolved PROJECT-scope variables. `sousDir` is
+   *   auto-injected by buildAutoVars when a config has been discovered.
+   * @param projectCount - How many projects the active config defines. Defaults
+   *   to 1 (the expected case: one `.sous/` per project).
+   */
+  getFilePath(projectKey: string, projectVars?: VarScope, projectCount = 1): string {
+    if (projectVars?.stateFilePath) {
+      return projectVars.stateFilePath;
+    }
+    if (projectVars?.sousDir) {
+      const fileName = projectCount > 1 ? `${projectKey}.sous.state.json` : "sous.state.json";
+      return path.join(projectVars.sousDir, fileName);
+    }
+    return path.join(process.cwd(), `${projectKey}.sous.state.json`);
+  }
+
+  /** Loads the state file for a project. Returns null if it does not exist. */
+  async load(filePath: string): Promise<StateFile | null> {
+    if (!fs.existsSync(filePath)) return null;
+    try {
+      const raw = fs.readFileSync(filePath, "utf8");
+      return JSON.parse(raw) as StateFile;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Deletes all tracked files and removes any now-empty tracked directories. */
+  deleteTrackedFiles(files: StateFileEntry[], dirs: string[]): void {
+    for (const entry of files) {
+      if (fs.existsSync(entry.dest)) fs.rmSync(entry.dest);
+    }
+    const sortedDirs = [...dirs].sort(
+      (a, b) => b.split(path.sep).length - a.split(path.sep).length
+    );
+    for (const dir of sortedDirs) {
+      if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
+        fs.rmdirSync(dir);
+      }
+    }
+  }
+
+  /** Saves the state file to disk, creating parent directories as needed. */
+  async save(filePath: string, state: StateFile): Promise<void> {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, JSON.stringify(state, null, 2), "utf8");
+  }
+}
+
+// --- Hash utilities ------------------------------------------------------------------------------
+
+/** Computes a SHA-256 hex hash of a file's contents. */
+export async function hashFile(filePath: string): Promise<string> {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+/** Computes a SHA-256 hex hash of an in-memory string. */
+export function hashContent(content: string): string {
+  return crypto.createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+// --- Directory tracking --------------------------------------------------------------------------
+
+/**
+ * Records that Sous created a directory.
+ * Only records if the directory is not already tracked.
+ */
+export function recordDirCreation(dir: string, state: StateFile): void {
+  if (!state.dirs.includes(dir)) {
+    state.dirs.push(dir);
+  }
+}
+
+/**
+ * Returns true if Sous created this directory (i.e., it is tracked in the state file).
+ */
+export function didSousCreateDir(dir: string, state: StateFile): boolean {
+  return state.dirs.includes(dir);
+}

package/src/lib/watch-service.ts

@@ -0,0 +1,115 @@
+import chokidar from "chokidar";
+import { minimatch } from "minimatch";
+import path from "node:path";
+import type { WatchConfig } from "./settings.js";
+import { log } from "../utils/formatting.js";
+
+/** Milliseconds to wait after a change before triggering a rebuild. */
+const DEBOUNCE_MS = 300;
+
+/** A partial rebuild triggered by a change to a specific source file. */
+export type PartialRebuildEvent = {
+  type: "partial";
+  filePath: string;
+};
+
+/** A full rebuild triggered by a change to a high-impact path (config, templating, etc.). */
+export type FullRebuildEvent = {
+  type: "full";
+  reason: string;
+  filePath: string;
+};
+
+export type WatchEvent = PartialRebuildEvent | FullRebuildEvent;
+
+/** A handle returned by WatchService.watch() that allows the caller to stop the watcher. */
+export type WatchHandle = {
+  stop(): Promise<void>;
+};
+
+/**
+ * Extracts the longest leading non-glob segment of a pattern as a watchable
+ * directory path. Chokidar v5 does not accept glob patterns directly.
+ *
+ * Examples:
+ *   "/foo/bar/**\/*"   → "/foo/bar"
+ *   "/foo/bar/*.md"   → "/foo/bar"
+ */
+function globBaseDir(pattern: string): string {
+  const starIndex = pattern.indexOf("*");
+  if (starIndex === -1) return path.dirname(pattern);
+  const prefix = pattern.slice(0, starIndex);
+  return prefix.endsWith("/") || prefix.endsWith(path.sep)
+    ? prefix.slice(0, -1)
+    : path.dirname(prefix);
+}
+
+/**
+ * Watches exact files, glob-backed directories, and full-rebuild paths,
+ * calling the provided callback (debounced) when a relevant change is detected.
+ *
+ * - Changes to `files` or `globs` entries fire a partial rebuild event.
+ * - Changes to `fullRebuildPaths` entries fire a full rebuild event.
+ *
+ * Returns a WatchHandle with a `stop()` method to close the watcher.
+ */
+export class WatchService {
+  watch(config: WatchConfig, onChange: (event: WatchEvent) => Promise<void>): WatchHandle {
+    const { files, globs, fullRebuildPaths = [] } = config;
+    const globBaseDirs = globs.map(globBaseDir);
+    const watchPaths = [...new Set([...files, ...globBaseDirs, ...fullRebuildPaths])];
+
+    const watcher = chokidar.watch(watchPaths, {
+      ignoreInitial: true,
+      persistent: true,
+      ignored: /sous\.state\.json$/,
+    });
+
+    let debounceTimer: NodeJS.Timeout | null = null;
+    let pendingEvent: WatchEvent | null = null;
+
+    const schedule = (event: WatchEvent) => {
+      pendingEvent = event;
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(async () => {
+        debounceTimer = null;
+        const evt = pendingEvent!;
+        pendingEvent = null;
+        try {
+          await onChange(evt);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          log(`  Watch error: ${message}`);
+        }
+      }, DEBOUNCE_MS);
+    };
+
+    watcher.on("all", (event, filePath) => {
+      if (!["add", "change", "unlink"].includes(event)) return;
+
+      // Full-rebuild paths take priority
+      const isFullRebuildPath = fullRebuildPaths.some(p =>
+        filePath === p || filePath.startsWith(p + path.sep) || filePath.startsWith(p + "/")
+      );
+
+      if (isFullRebuildPath) {
+        schedule({ type: "full", reason: filePath, filePath });
+        return;
+      }
+
+      const isExactFile = files.includes(filePath);
+      const matchesGlob = globs.some(g => minimatch(filePath, g));
+
+      if (isExactFile || matchesGlob) {
+        schedule({ type: "partial", filePath });
+      }
+    });
+
+    const totalPatterns = files.length + globs.length + fullRebuildPaths.length;
+    log(`\nWatching ${totalPatterns} pattern(s) for changes...\n`);
+
+    return {
+      stop: () => watcher.close(),
+    };
+  }
+}

package/src/templating/filters/bullet-list.ts

@@ -0,0 +1,9 @@
+import type { Liquid } from "liquidjs";
+
+/** Converts an array to a markdown bullet list. */
+export function registerBulletListFilter(engine: Liquid): void {
+  engine.registerFilter("bulletList", (items: unknown) => {
+    if (!Array.isArray(items)) return String(items);
+    return items.map(i => `- ${String(i)}`).join("\n");
+  });
+}

package/src/templating/filters/index.ts

@@ -0,0 +1,8 @@
+import type { Liquid } from "liquidjs";
+import { registerBulletListFilter } from "./bullet-list.js";
+
+const filterRegistrars: Array<(engine: Liquid) => void> = [
+  registerBulletListFilter,
+];
+
+export default filterRegistrars;

package/src/templating/init-liquid-engine.ts

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Liquid, type FS } from "liquidjs";
+import filterRegistrars from "./filters/index.js";
+import tagRegistrars from "./tags/index.js";
+import { resolveIncludeCandidates, type AliasMap } from "../lib/include-resolver.js";
+
+/** Options for alias-aware `{% render %}` path resolution. */
+export type EngineAliasOptions = {
+  /** Resolved alias map (name → ordered base dirs). */
+  aliases?: AliasMap;
+  /** Variable scope for `${var}` substitution in render paths. */
+  scope?: Record<string, string>;
+};
+
+/**
+ * A node-backed LiquidJS FS that additionally understands `@`-prefixed render
+ * paths — `{% render "@~sous-shared/x.md" %}`, `{% render "@docs/y.md" %}`, or
+ * `{% render "@${var}/z.md" %}` — resolving them through the same alias/var/
+ * relative candidate logic as `@include`. Non-`@` paths use standard root-based
+ * resolution.
+ *
+ * @param opts - Alias map and variable scope.
+ * @returns A LiquidJS FS implementation.
+ */
+function createAliasFS(opts: EngineAliasOptions): FS {
+  const aliases = opts.aliases ?? {};
+  const scope = opts.scope ?? {};
+
+  /** Resolve an `@`-path to its first existing candidate, or the first candidate. */
+  const resolveAt = (file: string, dir: string): string | null => {
+    if (!file.startsWith("@")) return null;
+    const candidates = resolveIncludeCandidates(file.slice(1), { aliases, scope, baseDir: dir });
+    return candidates.find((c) => fs.existsSync(c)) ?? candidates[0] ?? null;
+  };
+
+  return {
+    resolve(dir: string, file: string, ext: string): string {
+      const at = resolveAt(file, dir);
+      if (at) return at;
+      // Standard resolution: join against the root dir, applying ext if missing.
+      const joined = path.resolve(dir, file);
+      if (ext && !path.extname(joined)) return joined + ext;
+      return joined;
+    },
+    existsSync: (filepath: string) => fs.existsSync(filepath),
+    exists: async (filepath: string) => fs.existsSync(filepath),
+    readFileSync: (filepath: string) => fs.readFileSync(filepath, "utf8"),
+    readFile: async (filepath: string) => fs.promises.readFile(filepath, "utf8"),
+    dirname: (file: string) => path.dirname(file),
+    sep: path.sep,
+  };
+}
+
+/**
+ * Creates a configured LiquidJS engine instance for Sous template rendering.
+ * Registers built-in Sous filters and tags.
+ *
+ * @param roots - Filesystem root paths searched (in order) when resolving
+ *   `{% render %}` partials (relative paths resolve against these).
+ * @param aliasOpts - Optional alias map + scope enabling `@alias/...` and
+ *   `@${var}/...` paths in `{% render %}` (parity with `@include`).
+ */
+export function createLiquidEngine(roots: string[], aliasOpts: EngineAliasOptions = {}): Liquid {
+  const engine = new Liquid({
+    root: roots,
+    extname: "",
+    strictVariables: false,
+    strictFilters: false,
+    fs: createAliasFS(aliasOpts),
+  });
+
+  for (const register of filterRegistrars) {
+    register(engine);
+  }
+
+  for (const register of tagRegistrars) {
+    register(engine);
+  }
+
+  return engine;
+}

package/src/templating/lib/glob-files.ts

@@ -0,0 +1,74 @@
+import path from "node:path";
+import { glob } from "glob";
+
+/** A single file discovered by {@link globFiles}. */
+export interface GlobFile {
+  /** Absolute path to the file. */
+  path: string;
+  /** Absolute path to the file's directory. */
+  dir: string;
+  /** Path relative to the search root (POSIX separators). */
+  relPath: string;
+  /** File's basename (e.g. "get-thing.mjs"). */
+  name: string;
+}
+
+/** Options controlling a {@link globFiles} search. */
+export interface GlobFilesOptions {
+  /** Absolute directory to search within. */
+  root: string;
+  /** Glob patterns to include. Defaults to everything (`**\/*`). */
+  include?: string[];
+  /** Glob patterns to exclude. */
+  exclude?: string[];
+}
+
+/**
+ * Find files under a root directory matching include globs and not matching
+ * exclude globs. Patterns are matched relative to `root`. Results are files
+ * only (no directories), sorted by relative path for deterministic output.
+ *
+ * @param options - The search root and include/exclude glob patterns.
+ * @returns A sorted array of matched files.
+ */
+export async function globFiles(options: GlobFilesOptions): Promise<GlobFile[]> {
+  const { root } = options;
+  const include = options.include?.length ? options.include : ["**/*"];
+  const exclude = options.exclude ?? [];
+
+  const matches = await glob(include, {
+    cwd: root,
+    ignore: exclude,
+    nodir: true,
+    dot: true,
+    posix: true,
+  });
+
+  const unique = [...new Set(matches)].sort((a, b) => a.localeCompare(b));
+
+  return unique.map((relPath) => {
+    const absPath = path.resolve(root, relPath);
+    return {
+      path: absPath,
+      dir: path.dirname(absPath),
+      relPath,
+      name: path.basename(absPath),
+    };
+  });
+}
+
+/**
+ * Parse a comma-separated glob attribute (e.g. `"*.mjs, !x.mjs"`) into a
+ * trimmed list of non-empty patterns. Returns an empty array for
+ * undefined/blank input.
+ *
+ * @param value - The raw attribute string, or undefined.
+ * @returns The parsed pattern list.
+ */
+export function parseGlobList(value: string | undefined): string[] {
+  if (!value) return [];
+  return value
+    .split(",")
+    .map((p) => p.trim())
+    .filter((p) => p.length > 0);
+}

package/src/templating/lib/import-export.ts

@@ -0,0 +1,32 @@
+import { pathToFileURL } from "node:url";
+
+/**
+ * Dynamically import a single named export from a JavaScript/ESM file.
+ *
+ * Used to read declarative metadata (e.g. a script's `meta` export) at compile
+ * time. Files are expected to have NO top-level side effects — importing them
+ * runs module-level code.
+ *
+ * Failures are swallowed and reported as `undefined`: a file that fails to
+ * import, or that lacks the requested export, simply yields no value rather
+ * than aborting the whole template render. The optional `onError` callback
+ * receives the path and error for diagnostics.
+ *
+ * @param absPath - Absolute path to the file to import.
+ * @param exportName - The named export to read (e.g. "meta"). Use "default" for the default export.
+ * @param onError - Optional callback invoked when import or lookup fails.
+ * @returns The exported value, or undefined on any failure.
+ */
+export async function importNamedExport(
+  absPath: string,
+  exportName: string,
+  onError?: (path: string, error: unknown) => void
+): Promise<unknown> {
+  try {
+    const mod = await import(pathToFileURL(absPath).href);
+    return mod[exportName];
+  } catch (error) {
+    onError?.(absPath, error);
+    return undefined;
+  }
+}

package/src/templating/lib/tag-args.ts

@@ -0,0 +1,19 @@
+/**
+ * Split a tag's raw `args` string into an optional leading positional
+ * identifier and the remaining `key="value"` hash markup.
+ *
+ * A leading identifier is treated as the positional name ONLY when it is not
+ * immediately followed by `=` — so `getFiles tasks root="x"` yields
+ * `{ name: "tasks", rest: 'root="x"' }`, while `getFiles root="x"` yields
+ * `{ name: null, rest: 'root="x"' }` (the first token is the `root` attribute).
+ *
+ * @param args - The raw `TagToken.args` string.
+ * @returns The positional name (or null) and the remaining hash markup.
+ */
+export function splitPositionalName(args: string): { name: string | null; rest: string } {
+  const lead = args.match(/^\s*([a-zA-Z_][\w]*)(\s*=)?/);
+  if (lead && !lead[2]) {
+    return { name: lead[1], rest: args.slice(lead[0].length).trim() };
+  }
+  return { name: null, rest: args.trim() };
+}

package/src/templating/tags/exportScalarVarsJs.ts

@@ -0,0 +1,43 @@
+import type { Liquid } from "liquidjs";
+import type { Context } from "liquidjs/dist/context/context.js";
+import { sortObjectKeys } from "../../utils/formatting.js";
+
+/**
+ * A "scalar" for export purposes: the value types that can be safely embedded
+ * in a settings module and consumed at runtime without structural ambiguity.
+ */
+function isScalar(value: unknown): value is string | number | boolean {
+  return (
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  );
+}
+
+/**
+ * Dumps all in-scope scalar variables as an ES module default export.
+ *
+ * Iterates every variable currently in the LiquidJS scope, keeps only scalars
+ * (strings, finite numbers, booleans), sorts them by key, and emits a valid
+ * `export default { ... };` block. Objects, arrays, functions, null, undefined,
+ * and non-finite numbers are skipped.
+ *
+ * Intended for compiling a `settings.tpl.mjs` that downstream runtime code
+ * (e.g. browser automation scripts) imports for project configuration.
+ */
+export function registerExportScalarVarsJsTag(engine: Liquid): void {
+  engine.registerTag("exportScalarVarsJs", {
+    render(ctx: Context) {
+      const scope = ctx.getAll() as Record<string, unknown>;
+      const scalars: Record<string, string | number | boolean> = {};
+
+      for (const [key, value] of Object.entries(scope)) {
+        if (isScalar(value)) scalars[key] = value;
+      }
+
+      const sorted = sortObjectKeys(scalars);
+      const json = JSON.stringify(sorted, null, 2);
+      return `export default ${json};\n`;
+    },
+  });
+}

package/src/templating/tags/getFiles.ts

@@ -0,0 +1,89 @@
+import { Hash, type Liquid } from "liquidjs";
+import type { Context } from "liquidjs/dist/context/context.js";
+import type { TagToken } from "liquidjs/dist/tokens/tag-token.js";
+import { globFiles, parseGlobList, type GlobFile } from "../lib/glob-files.js";
+import { splitPositionalName } from "../lib/tag-args.js";
+import { importNamedExport } from "../lib/import-export.js";
+
+/**
+ * Registers the `{% getFiles <varName> root="..." include="..." exclude="..." import="..." %}`
+ * tag. It globs files under `root` and assigns the resulting array to `<varName>`
+ * in the template scope. It renders no output — use a `{% for %}` loop to present
+ * the results.
+ *
+ * Each result has `{ path, dir, relPath, name }`. When the optional `import`
+ * attribute names an export (e.g. `import="meta"`), each file is dynamically
+ * imported and that export is attached under the same key (e.g. `file.meta`);
+ * files that fail to import or lack the export are omitted from the results.
+ *
+ * Attribute values may be quoted strings or scope variables (e.g. `root=tasksDir`).
+ * `include`/`exclude` are comma-separated glob patterns matched relative to `root`.
+ */
+export function registerGetFilesTag(engine: Liquid): void {
+  engine.registerTag("getFiles", {
+    parse(token: TagToken) {
+      const { name, rest } = splitPositionalName(token.args);
+      this.varName = name;
+      this.hash = new Hash(rest, true);
+    },
+
+    *render(ctx: Context): Generator<unknown, string, Record<string, unknown>> {
+      const hash = yield this.hash.render(ctx);
+      const varName: string | null = this.varName;
+
+      const files = (yield resolveFiles(hash)) as unknown;
+
+      if (varName) {
+        (ctx.bottom() as Record<string, unknown>)[varName] = files;
+      }
+      return "";
+    },
+  });
+}
+
+/** A file record optionally carrying a dynamically-imported export. */
+type ResolvedFile = GlobFile & Record<string, unknown>;
+
+/**
+ * Resolve the glob attributes from a rendered hash into file records, applying
+ * the optional `import` export attachment.
+ *
+ * @param hash - The rendered tag attributes (`root`, `include`, `exclude`, `import`).
+ * @returns The matched files, each optionally carrying the imported export.
+ */
+async function resolveFiles(hash: Record<string, unknown>): Promise<ResolvedFile[]> {
+  const root = hash.root != null ? String(hash.root) : "";
+  if (!root) {
+    throw new Error('getFiles: a "root" attribute is required');
+  }
+
+  const files = await globFiles({
+    root,
+    include: parseGlobList(hash.include != null ? String(hash.include) : undefined),
+    exclude: parseGlobList(hash.exclude != null ? String(hash.exclude) : undefined),
+  });
+
+  const importName = hash.import != null ? String(hash.import).trim() : "";
+  if (!importName) return files as ResolvedFile[];
+
+  return attachImports(files, importName);
+}
+
+/**
+ * For each file, dynamically import `importName` and attach it under that key.
+ * Files whose import fails or lacks the export are dropped from the result.
+ *
+ * @param files - The globbed file records.
+ * @param importName - The export to read from each file.
+ * @returns Files that successfully yielded the export, with it attached.
+ */
+async function attachImports(files: GlobFile[], importName: string): Promise<ResolvedFile[]> {
+  const enriched = await Promise.all(
+    files.map(async (file) => {
+      const value = await importNamedExport(file.path, importName);
+      if (value === undefined) return null;
+      return { ...file, [importName]: value };
+    })
+  );
+  return enriched.filter((f): f is ResolvedFile => f !== null);
+}

package/src/templating/tags/index.ts

@@ -0,0 +1,14 @@
+import type { Liquid } from "liquidjs";
+import { registerShowVarsTag } from "./showVars.js";
+import { registerExportScalarVarsJsTag } from "./exportScalarVarsJs.js";
+import { registerGetFilesTag } from "./getFiles.js";
+import { registerListFilesTag } from "./listFiles.js";
+
+const tagRegistrars: Array<(engine: Liquid) => void> = [
+  registerShowVarsTag,
+  registerExportScalarVarsJsTag,
+  registerGetFilesTag,
+  registerListFilesTag,
+];
+
+export default tagRegistrars;

package/src/templating/tags/listFiles.ts

@@ -0,0 +1,54 @@
+import { Hash, type Liquid } from "liquidjs";
+import type { Context } from "liquidjs/dist/context/context.js";
+import type { TagToken } from "liquidjs/dist/tokens/tag-token.js";
+import { globFiles, parseGlobList, type GlobFile } from "../lib/glob-files.js";
+
+/**
+ * Registers the `{% listFiles root="..." include="..." exclude="..." %}` tag.
+ * It globs files under `root` and renders them directly as a simple markdown
+ * bullet list of file names — the convenience counterpart to `getFiles`.
+ *
+ * For custom presentation (or to read file metadata), use `getFiles` with a
+ * `{% for %}` loop instead. `listFiles` is intentionally glob-only and emits a
+ * fixed format.
+ *
+ * Attribute values may be quoted strings or scope variables. `include`/`exclude`
+ * are comma-separated glob patterns matched relative to `root`. An optional
+ * `relative="true"` renders relative paths instead of bare file names.
+ */
+export function registerListFilesTag(engine: Liquid): void {
+  engine.registerTag("listFiles", {
+    parse(token: TagToken) {
+      this.hash = new Hash(token.args, true);
+    },
+
+    *render(ctx: Context): Generator<unknown, string, Record<string, unknown>> {
+      const hash = yield this.hash.render(ctx);
+      const files = (yield resolveFiles(hash)) as unknown as GlobFile[];
+      const useRelative = String(hash.relative ?? "") === "true";
+
+      if (files.length === 0) return "";
+      return files
+        .map((f) => `- ${useRelative ? f.relPath : f.name}`)
+        .join("\n");
+    },
+  });
+}
+
+/**
+ * Resolve the glob attributes from a rendered hash into file records.
+ *
+ * @param hash - The rendered tag attributes (`root`, `include`, `exclude`).
+ * @returns The matched files.
+ */
+async function resolveFiles(hash: Record<string, unknown>): Promise<GlobFile[]> {
+  const root = hash.root != null ? String(hash.root) : "";
+  if (!root) {
+    throw new Error('listFiles: a "root" attribute is required');
+  }
+  return globFiles({
+    root,
+    include: parseGlobList(hash.include != null ? String(hash.include) : undefined),
+    exclude: parseGlobList(hash.exclude != null ? String(hash.exclude) : undefined),
+  });
+}