@bendyline/docblocks-cli 2.6.2 → 2.7.0

package/dist/index.js

@@ -1,13 +1,13 @@
 // src/commands/build.ts
 import { Command } from "commander";
 import { mkdir, opendir, readFile, stat as stat2, writeFile } from "fs/promises";
-import path4 from "path";
+import path5 from "path";
 
 // src/render-html.ts
 import { realpath, stat } from "fs/promises";
 import path3 from "path";
 import { markdownToDoc } from "@bendyline/squisq/doc";
-import { parseMarkdown } from "@bendyline/squisq/markdown";
+import { parseMarkdown, readFrontmatterThemeId } from "@bendyline/squisq/markdown";
 import { collectImagePaths, docToHtml } from "@bendyline/squisq-formats/html";
 import { PLAYER_BUNDLE } from "@bendyline/squisq-react/standalone-source";
 
@@ -123,25 +123,35 @@ var DEFAULT_MAX_ASSET_BYTES = 50 * 1024 * 1024;
 var MAX_SINGLE_ASSET_BYTES = 20 * 1024 * 1024;
 async function renderMarkdownHtml(markdown, options) {
   await assertKnownThemeId(options.themeId);
+  const warn = options.onWarning ?? ((message) => console.warn(message));
   const markdownDoc = parseMarkdown(markdown);
   const doc = markdownToDoc(markdownDoc);
+  const themeId = options.themeId ?? (readFrontmatterThemeId(markdownDoc.frontmatter) ? void 0 : await usableFallbackThemeId(options.fallbackThemeId, warn));
   const images = options.sourcePath && options.assetRoot ? await readReferencedImages(
     doc,
     options.sourcePath,
     options.assetRoot,
     options.maxAssetBytes ?? DEFAULT_MAX_ASSET_BYTES,
     options.allowReferencedAsset,
-    options.onWarning ?? ((message) => console.warn(message))
+    warn
   ) : void 0;
   return docToHtml(doc, {
     playerScript: PLAYER_BUNDLE,
     images,
     title: options.title,
     mode: options.mode ?? "static",
-    themeId: options.themeId,
+    themeId,
     showCodeCopyButton: true
   });
 }
+async function usableFallbackThemeId(fallbackThemeId, warn) {
+  if (!fallbackThemeId) return void 0;
+  if ((await getAvailableThemeIds()).includes(fallbackThemeId)) return fallbackThemeId;
+  warn(
+    `Ignoring unknown fallback theme "${fallbackThemeId}"; the document's default theme applies.`
+  );
+  return void 0;
+}
 async function readReferencedImages(doc, sourcePath, assetRoot, maxAssetBytes, allowReferencedAsset, warn) {
   const images = /* @__PURE__ */ new Map();
   const root = await realpathIfPresent(path3.resolve(assetRoot));
@@ -237,8 +247,575 @@ function positiveLimit(value, fallback, label) {
   return selected;
 }
 
+// src/internal/workspace-settings.ts
+import { decodeUtf8Text, parseWorkspacePath as parseWorkspacePath2 } from "@bendyline/docblocks/filesystem";
+import {
+  WORKSPACE_SETTINGS_LIMITS,
+  WORKSPACE_SETTINGS_PATH,
+  parseWorkspaceSettingsText,
+  resolveWorkspaceDefaultThemeId
+} from "@bendyline/docblocks/workspace-settings";
+
+// src/internal/workspace-io.ts
+import { constants as fsConstants } from "fs";
+import fs2 from "fs/promises";
+import { randomUUID } from "crypto";
+import path4 from "path";
+import {
+  FsError,
+  mapNodeErrorCodeToFsErrorCode,
+  parseFileSystemVersion,
+  parseWorkspacePath,
+  tryParseWorkspacePath
+} from "@bendyline/docblocks/filesystem";
+
+// src/internal/link-support.ts
+var LINK_UNSUPPORTED_CODES = [
+  "EPERM",
+  "ENOSYS",
+  "ENOTSUP",
+  "EOPNOTSUPP",
+  "EXDEV",
+  "EMLINK"
+];
+function isLinkUnsupportedError(error) {
+  return isNodeErrorCode(error, LINK_UNSUPPORTED_CODES);
+}
+
+// src/internal/workspace-io.ts
+var NODE_WORKSPACE_IO_LIMITS = {
+  maxFileBytes: 256 * 1024 * 1024,
+  maxDirectoryEntries: 1e5
+};
+var LISTING_STAT_CONCURRENCY = 16;
+var TEMPORARY_PREFIX = ".docblocks-tmp-";
+async function createNodeWorkspaceIO(rootDir, options = {}) {
+  const requested = path4.resolve(rootDir);
+  let root;
+  try {
+    root = await fs2.realpath(requested);
+  } catch (error) {
+    if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) {
+      throw new FsError("not-found", `Workspace folder not found: ${requested}`, {
+        operation: "stat"
+      });
+    }
+    throw toFsError(error, "stat", "");
+  }
+  let info;
+  try {
+    info = await fs2.stat(root);
+  } catch (error) {
+    throw toFsError(error, "stat", "");
+  }
+  if (!info.isDirectory()) {
+    throw new FsError("type-mismatch", `Workspace root is not a folder: ${requested}`, {
+      operation: "stat"
+    });
+  }
+  return new NodeWorkspaceIO(root, {
+    maxFileBytes: positiveLimit(
+      options.maxFileBytes,
+      NODE_WORKSPACE_IO_LIMITS.maxFileBytes,
+      "workspace file byte"
+    ),
+    maxDirectoryEntries: positiveLimit(
+      options.maxDirectoryEntries,
+      NODE_WORKSPACE_IO_LIMITS.maxDirectoryEntries,
+      "workspace folder entry"
+    )
+  });
+}
+var NodeWorkspaceIO = class {
+  constructor(root, limits) {
+    this.root = root;
+    this.limits = limits;
+  }
+  async stat(input) {
+    const workspacePath = canonical(input, "stat");
+    try {
+      const located = await this.locate(workspacePath, "stat");
+      if (!located) return null;
+      const info = await lstatOrNull(located);
+      if (!info) return null;
+      return snapshotFor(workspacePath, assertSupportedKind(info, workspacePath, "stat"), info);
+    } catch (error) {
+      throw toFsError(error, "stat", workspacePath);
+    }
+  }
+  async readFile(input) {
+    const workspacePath = canonical(input, "read");
+    try {
+      const located = await this.locate(workspacePath, "read");
+      if (!located) return null;
+      const before = await lstatOrNull(located);
+      if (!before) return null;
+      if (assertSupportedKind(before, workspacePath, "read") !== "file") {
+        throw new FsError("type-mismatch", `"${workspacePath}" is a folder, not a file.`, {
+          operation: "read",
+          path: workspacePath
+        });
+      }
+      this.assertFileSize(before.size, workspacePath, "read");
+      return await this.readLocatedFile(located, before, workspacePath);
+    } catch (error) {
+      if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) return null;
+      throw toFsError(error, "read", workspacePath);
+    }
+  }
+  async readDirectory(input) {
+    const workspacePath = canonical(input, "list");
+    try {
+      let directory = this.root;
+      if (workspacePath) {
+        const located = await this.locate(workspacePath, "list");
+        const info = located ? await lstatOrNull(located) : null;
+        if (!located || !info) {
+          throw new FsError("not-found", `Folder "${workspacePath}" does not exist.`, {
+            operation: "list",
+            path: workspacePath
+          });
+        }
+        if (assertSupportedKind(info, workspacePath, "list") !== "directory") {
+          throw new FsError("type-mismatch", `"${workspacePath}" is a file, not a folder.`, {
+            operation: "list",
+            path: workspacePath
+          });
+        }
+        directory = located;
+      }
+      const names = await this.listNames(directory, workspacePath);
+      const entries = [];
+      for (let index = 0; index < names.length; index += LISTING_STAT_CONCURRENCY) {
+        const batch = names.slice(index, index + LISTING_STAT_CONCURRENCY);
+        const snapshots = await Promise.all(
+          batch.map(async (name) => {
+            const info = await lstatOrNull(path4.join(directory, name));
+            if (!info || info.isSymbolicLink()) return null;
+            const kind = info.isFile() ? "file" : info.isDirectory() ? "directory" : null;
+            if (!kind) return null;
+            const childPath = parseWorkspacePath(workspacePath ? `${workspacePath}/${name}` : name);
+            return snapshotFor(childPath, kind, info);
+          })
+        );
+        for (const snapshot of snapshots) if (snapshot) entries.push(snapshot);
+      }
+      return Object.freeze(entries.sort(compareSnapshots));
+    } catch (error) {
+      throw toFsError(error, "list", workspacePath);
+    }
+  }
+  async writeFile(input, data, options = {}) {
+    const workspacePath = canonical(input, "write");
+    if (!workspacePath) {
+      throw new FsError("invalid-path", "The workspace root cannot be written.", {
+        operation: "write",
+        path: workspacePath
+      });
+    }
+    const bytes = ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : new Uint8Array(data);
+    const mode = options.mode ?? "upsert";
+    const expectedVersion = options.expectedVersion;
+    let temporary = null;
+    try {
+      this.assertFileSize(BigInt(bytes.byteLength), workspacePath, "write");
+      const parent = await this.ensureParent(workspacePath, options.createParents === true);
+      const target = path4.join(parent, basename(workspacePath));
+      let current = await lstatOrNull(target);
+      assertWritable(current, workspacePath, mode, expectedVersion);
+      temporary = path4.join(parent, `${TEMPORARY_PREFIX}${randomUUID()}`);
+      const handle = await fs2.open(temporary, "wx", 438);
+      try {
+        await handle.writeFile(bytes);
+        if (current?.isFile()) await handle.chmod(Number(current.mode & 0o7777n));
+      } finally {
+        await handle.close();
+      }
+      current = await lstatOrNull(target);
+      assertWritable(current, workspacePath, mode, expectedVersion);
+      if (!current && (mode === "create" || expectedVersion === null)) {
+        await publishExclusive(temporary, target, bytes, workspacePath, mode);
+      } else {
+        await fs2.rename(temporary, target);
+        temporary = null;
+      }
+      const written = await fs2.lstat(target, { bigint: true });
+      const snapshot = snapshotFor(workspacePath, "file", written);
+      if (snapshot.kind !== "file") throw new Error("Unreachable: wrote a non-file entry.");
+      return snapshot;
+    } catch (error) {
+      throw toFsError(error, "write", workspacePath);
+    } finally {
+      if (temporary) await fs2.rm(temporary, { force: true }).catch(() => void 0);
+    }
+  }
+  /**
+   * Physical absolute path for `workspacePath`, with its parent proven to be
+   * inside the root, or null when a parent is missing or is a file.
+   */
+  async locate(workspacePath, operation) {
+    if (!workspacePath) return this.root;
+    const segments = workspacePath.split("/");
+    const name = segments.pop();
+    let parent;
+    try {
+      parent = await fs2.realpath(path4.join(this.root, ...segments));
+    } catch (error) {
+      if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) return null;
+      throw error;
+    }
+    if (!isPathInside(this.root, parent)) throw escapeError(workspacePath, operation);
+    return path4.join(parent, name);
+  }
+  /** Resolve (and optionally create) the physical parent folder of a write. */
+  async ensureParent(workspacePath, createParents) {
+    const segments = workspacePath.split("/").slice(0, -1);
+    let current = this.root;
+    let walked = "";
+    for (const segment of segments) {
+      walked = walked ? `${walked}/${segment}` : segment;
+      const next = path4.join(current, segment);
+      let info = await lstatOrNull(next);
+      if (!info) {
+        if (!createParents) {
+          throw new FsError("not-found", `Parent folder "${walked}" does not exist.`, {
+            operation: "write",
+            path: workspacePath
+          });
+        }
+        try {
+          await fs2.mkdir(next);
+        } catch (error) {
+          if (!isNodeErrorCode(error, "EEXIST")) throw error;
+        }
+        info = await fs2.lstat(next, { bigint: true });
+      }
+      if (info.isSymbolicLink()) {
+        const physical = await fs2.realpath(next);
+        if (!isPathInside(this.root, physical)) throw escapeError(workspacePath, "write");
+        if (!(await fs2.stat(physical)).isDirectory()) throw parentFileError(walked, workspacePath);
+        current = physical;
+      } else if (info.isDirectory()) {
+        current = next;
+      } else {
+        throw parentFileError(walked, workspacePath);
+      }
+    }
+    const physicalParent = await fs2.realpath(current);
+    if (!isPathInside(this.root, physicalParent)) throw escapeError(workspacePath, "write");
+    return physicalParent;
+  }
+  async listNames(directory, workspacePath) {
+    const names = [];
+    let seen = 0;
+    const handle = await fs2.opendir(directory);
+    for await (const dirent of handle) {
+      seen += 1;
+      if (seen > this.limits.maxDirectoryEntries) {
+        throw new FsError(
+          "not-supported",
+          `Folder "${workspacePath || "."}" has more than ${this.limits.maxDirectoryEntries} entries.`,
+          { operation: "list", path: workspacePath }
+        );
+      }
+      if (dirent.isSymbolicLink()) continue;
+      if (tryParseWorkspacePath(dirent.name) !== dirent.name) continue;
+      names.push(dirent.name);
+    }
+    return names;
+  }
+  async readLocatedFile(located, before, workspacePath) {
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const handle = await fs2.open(located, fsConstants.O_RDONLY | noFollow);
+    try {
+      const opened = await handle.stat({ bigint: true });
+      if (!opened.isFile() || opened.ino !== before.ino) throw changedError(workspacePath);
+      const physical = await fs2.realpath(located);
+      if (!isPathInside(this.root, physical)) throw escapeError(workspacePath, "read");
+      this.assertFileSize(opened.size, workspacePath, "read");
+      const size = Number(opened.size);
+      const buffer = new Uint8Array(size);
+      let offset = 0;
+      while (offset < size) {
+        const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
+        if (bytesRead === 0) break;
+        offset += bytesRead;
+      }
+      const probe = new Uint8Array(1);
+      const grew = (await handle.read(probe, 0, 1, offset)).bytesRead > 0;
+      const after = await handle.stat({ bigint: true });
+      if (grew || offset !== size || !sameFileState(opened, after)) {
+        throw changedError(workspacePath);
+      }
+      const entry = snapshotFor(workspacePath, "file", opened);
+      if (entry.kind !== "file") throw new Error("Unreachable: read a non-file entry.");
+      return Object.freeze({ entry, data: buffer.buffer });
+    } finally {
+      await handle.close();
+    }
+  }
+  assertFileSize(size, workspacePath, operation) {
+    if (size > BigInt(this.limits.maxFileBytes)) {
+      throw new FsError(
+        "not-supported",
+        `"${workspacePath}" is larger than the ${this.limits.maxFileBytes}-byte workspace file limit.`,
+        { operation, path: workspacePath }
+      );
+    }
+  }
+};
+function canonical(input, operation) {
+  try {
+    return parseWorkspacePath(input);
+  } catch (error) {
+    throw toFsError(error, operation, input);
+  }
+}
+function basename(workspacePath) {
+  const slash = workspacePath.lastIndexOf("/");
+  return slash < 0 ? workspacePath : workspacePath.slice(slash + 1);
+}
+async function lstatOrNull(absolutePath) {
+  try {
+    return await fs2.lstat(absolutePath, { bigint: true });
+  } catch (error) {
+    if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) return null;
+    throw error;
+  }
+}
+function assertSupportedKind(info, workspacePath, operation) {
+  if (info.isSymbolicLink()) {
+    throw new FsError(
+      "not-supported",
+      `"${workspacePath}" is a symbolic link; workspace outputs never follow links.`,
+      { operation, path: workspacePath }
+    );
+  }
+  if (info.isFile()) return "file";
+  if (info.isDirectory()) return "directory";
+  throw new FsError("not-supported", `"${workspacePath}" is not a regular file or folder.`, {
+    operation,
+    path: workspacePath
+  });
+}
+function versionFor(kind, info) {
+  return parseFileSystemVersion(
+    `node-v1:${kind}:ino=${info.ino}:size=${kind === "file" ? info.size : 0n}:mtime-ns=${info.mtimeNs}`
+  );
+}
+function snapshotFor(workspacePath, kind, info) {
+  const base = {
+    path: workspacePath,
+    name: basename(workspacePath),
+    version: versionFor(kind, info),
+    lastModified: info.mtime.toISOString()
+  };
+  if (kind === "directory") return Object.freeze({ ...base, kind, size: null });
+  const size = Number(info.size);
+  if (!Number.isSafeInteger(size)) {
+    throw new FsError("not-supported", `"${workspacePath}" is too large to describe.`, {
+      path: workspacePath
+    });
+  }
+  return Object.freeze({ ...base, kind, size });
+}
+function sameFileState(left, right) {
+  return left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs;
+}
+function assertWritable(current, workspacePath, mode, expectedVersion) {
+  if (current) {
+    const kind = assertSupportedKind(current, workspacePath, "write");
+    if (kind === "directory") {
+      throw new FsError("type-mismatch", `"${workspacePath}" is a folder; it cannot be replaced.`, {
+        operation: "write",
+        path: workspacePath
+      });
+    }
+    if (mode === "create") {
+      throw new FsError("already-exists", `"${workspacePath}" already exists.`, {
+        operation: "write",
+        path: workspacePath
+      });
+    }
+  } else if (mode === "replace") {
+    throw new FsError("not-found", `"${workspacePath}" does not exist.`, {
+      operation: "write",
+      path: workspacePath
+    });
+  }
+  if (expectedVersion === void 0) return;
+  const matches = expectedVersion === null ? !current : !!current && versionFor("file", current) === expectedVersion;
+  if (!matches) {
+    throw new FsError("conflict", `"${workspacePath}" changed since it was read.`, {
+      operation: "write",
+      path: workspacePath,
+      retryable: true
+    });
+  }
+}
+async function publishExclusive(temporary, target, bytes, workspacePath, mode) {
+  try {
+    await fs2.link(temporary, target);
+    return;
+  } catch (error) {
+    if (isNodeErrorCode(error, "EEXIST")) throw existsRaceError(workspacePath, mode);
+    if (!isLinkUnsupportedError(error)) throw error;
+  }
+  let handle;
+  try {
+    handle = await fs2.open(target, "wx", 438);
+  } catch (error) {
+    if (isNodeErrorCode(error, "EEXIST")) throw existsRaceError(workspacePath, mode);
+    throw error;
+  }
+  try {
+    await handle.writeFile(bytes);
+  } finally {
+    await handle.close();
+  }
+}
+function existsRaceError(workspacePath, mode) {
+  return mode === "create" ? new FsError("already-exists", `"${workspacePath}" already exists.`, {
+    operation: "write",
+    path: workspacePath
+  }) : new FsError("conflict", `"${workspacePath}" was created by another writer.`, {
+    operation: "write",
+    path: workspacePath,
+    retryable: true
+  });
+}
+function escapeError(workspacePath, operation) {
+  return new FsError(
+    "path-escape",
+    `"${workspacePath}" resolves outside the workspace folder through a symbolic link.`,
+    { operation, path: workspacePath }
+  );
+}
+function parentFileError(parent, workspacePath) {
+  return new FsError("type-mismatch", `"${parent}" is a file, not a folder.`, {
+    operation: "write",
+    path: workspacePath
+  });
+}
+function changedError(workspacePath) {
+  return new FsError("conflict", `"${workspacePath}" changed while it was being read.`, {
+    operation: "read",
+    path: workspacePath,
+    retryable: true
+  });
+}
+function compareSnapshots(left, right) {
+  if (left.kind !== right.kind) return left.kind === "directory" ? -1 : 1;
+  return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
+}
+function toFsError(error, operation, workspacePath) {
+  if (error instanceof FsError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  const code = nodeErrorCode(error);
+  if (code === "ELOOP") {
+    return new FsError(
+      "not-supported",
+      `"${workspacePath}" is a symbolic link; workspace outputs never follow links.`,
+      { operation, path: workspacePath }
+    );
+  }
+  if (code) {
+    return new FsError(
+      mapNodeErrorCodeToFsErrorCode(code),
+      `Could not ${OPERATION_VERBS[operation]} "${workspacePath || "."}": ${message}`,
+      { operation, path: workspacePath }
+    );
+  }
+  return new FsError("io", message, { operation, path: workspacePath });
+}
+function nodeErrorCode(error) {
+  if (!(error instanceof Error) || !("code" in error)) return null;
+  const { code } = error;
+  return typeof code === "string" ? code : null;
+}
+var OPERATION_VERBS = {
+  "parse-path": "parse",
+  read: "read",
+  stat: "inspect",
+  list: "list",
+  write: "write",
+  "create-directory": "create",
+  remove: "remove",
+  move: "move",
+  snapshot: "snapshot",
+  watch: "watch",
+  dispose: "close"
+};
+
+// src/internal/workspace-settings.ts
+var MAX_SETTINGS_FILE_BYTES = WORKSPACE_SETTINGS_LIMITS.maxFileBytes + 3;
+async function readWorkspaceSettings(io) {
+  const settingsPath = parseWorkspacePath2(WORKSPACE_SETTINGS_PATH);
+  const info = await io.stat(settingsPath);
+  if (!info) return { status: "missing" };
+  if (info.kind !== "file") {
+    return { status: "invalid", message: `${WORKSPACE_SETTINGS_PATH} is a folder, not a file.` };
+  }
+  if (info.size > MAX_SETTINGS_FILE_BYTES) return tooLarge();
+  const read = await io.readFile(settingsPath);
+  if (!read) return { status: "missing" };
+  if (read.data.byteLength > MAX_SETTINGS_FILE_BYTES) return tooLarge();
+  let text;
+  try {
+    text = decodeUtf8Text(read.data, {
+      label: "Workspace settings",
+      path: WORKSPACE_SETTINGS_PATH
+    });
+  } catch (error) {
+    return {
+      status: "invalid",
+      message: error instanceof Error ? error.message : `${WORKSPACE_SETTINGS_PATH} is not UTF-8.`
+    };
+  }
+  return parseWorkspaceSettingsText(text);
+}
+function describeWorkspaceSettingsProblem(message) {
+  return message.includes(WORKSPACE_SETTINGS_PATH) ? message : `${WORKSPACE_SETTINGS_PATH}: ${message}`;
+}
+function tooLarge() {
+  return {
+    status: "invalid",
+    message: `${WORKSPACE_SETTINGS_PATH} is larger than ${WORKSPACE_SETTINGS_LIMITS.maxFileBytes / 1024} KiB.`
+  };
+}
+async function createWorkspaceThemeFallback(rootDir, warn) {
+  const io = await createNodeWorkspaceIO(rootDir);
+  let lastWarning = null;
+  const report = (message) => {
+    if (message !== null && message !== lastWarning) warn(message);
+    lastWarning = message;
+  };
+  return {
+    async resolve() {
+      const result = await readWorkspaceSettings(io);
+      if (result.status === "missing") {
+        report(null);
+        return void 0;
+      }
+      if (result.status !== "ok") {
+        report(`Ignoring workspace settings. ${describeWorkspaceSettingsProblem(result.message)}`);
+        return void 0;
+      }
+      const themeId = resolveWorkspaceDefaultThemeId(result.settings);
+      if (themeId && !(await getAvailableThemeIds()).includes(themeId)) {
+        report(
+          `Ignoring workspace default theme "${themeId}" from ${WORKSPACE_SETTINGS_PATH}: it is not a known theme.`
+        );
+        return void 0;
+      }
+      report(null);
+      return themeId;
+    }
+  };
+}
+
 // src/commands/build.ts
-import { decodeUtf8Text } from "@bendyline/docblocks/filesystem";
+import { decodeUtf8Text as decodeUtf8Text2 } from "@bendyline/docblocks/filesystem";
 var DEFAULT_MAX_BUILD_ENTRIES = 1e5;
 var DEFAULT_MAX_BUILD_DEPTH = 64;
 var DEFAULT_MAX_BUILD_INPUT_BYTES = 20 * 1024 * 1024;
@@ -247,8 +824,8 @@ var DEFAULT_MAX_BUILD_OUTPUT_BYTES = 128 * 1024 * 1024;
 var DEFAULT_MAX_BUILD_TOTAL_OUTPUT_BYTES = 1024 * 1024 * 1024;
 async function runBuild(opts) {
   await assertKnownThemeId(opts.theme);
-  const inputDir = path4.resolve(opts.input);
-  const outputDir = path4.resolve(opts.output);
+  const inputDir = path5.resolve(opts.input);
+  const outputDir = path5.resolve(opts.output);
   let inputStat;
   try {
     inputStat = await stat2(inputDir);
@@ -257,6 +834,8 @@ async function runBuild(opts) {
     throw new Error(`Input directory not found: ${inputDir}`);
   }
   if (!inputStat.isDirectory()) throw new Error(`Input is not a directory: ${inputDir}`);
+  const warn = opts.onWarning ?? ((message) => console.warn(message));
+  const fallbackThemeId = opts.theme || opts.ignoreWorkspaceSettings ? void 0 : await (await createWorkspaceThemeFallback(inputDir, warn)).resolve();
   const markdownFiles = await listMarkdownFiles(inputDir, {
     maxEntries: positiveLimit(opts.maxEntries, DEFAULT_MAX_BUILD_ENTRIES, "build entry"),
     maxDepth: positiveLimit(opts.maxDepth, DEFAULT_MAX_BUILD_DEPTH, "build depth")
@@ -271,8 +850,8 @@ async function runBuild(opts) {
   let totalInputBytes = 0;
   let totalOutputBytes = 0;
   for (const sourcePath of markdownFiles) {
-    const relativePath = path4.relative(inputDir, sourcePath);
-    const outputPath = path4.join(outputDir, replaceMarkdownExtension(relativePath));
+    const relativePath = path5.relative(inputDir, sourcePath);
+    const outputPath = path5.join(outputDir, replaceMarkdownExtension(relativePath));
     const sourceBytes = await readFile(sourcePath);
     if (sourceBytes.byteLength > byteLimits.maxInputBytes) {
       throw new Error(
@@ -285,13 +864,15 @@ async function runBuild(opts) {
         `Build inputs exceed the ${byteLimits.maxTotalInputBytes}-byte aggregate limit.`
       );
     }
-    const source = decodeUtf8Text(sourceBytes, { label: "Build input", path: sourcePath });
+    const source = decodeUtf8Text2(sourceBytes, { label: "Build input", path: sourcePath });
     const html = await renderMarkdownHtml(source, {
       title: titleFromPath(relativePath),
       sourcePath,
       assetRoot: inputDir,
       themeId: opts.theme,
-      mode: "static"
+      fallbackThemeId,
+      mode: "static",
+      onWarning: warn
     });
     const outputBytes = Buffer.byteLength(html, "utf8");
     if (outputBytes > byteLimits.maxOutputBytes) {
@@ -305,18 +886,22 @@ async function runBuild(opts) {
         `Build outputs exceed the ${byteLimits.maxTotalOutputBytes}-byte aggregate limit.`
       );
     }
-    await mkdir(path4.dirname(outputPath), { recursive: true });
+    await mkdir(path5.dirname(outputPath), { recursive: true });
     await writeFile(outputPath, html, "utf-8");
     builtFiles.push(outputPath);
   }
   return { inputDir, outputDir, builtFiles };
 }
-var buildCommand = new Command("build").description("Build markdown files into HTML output").option("-i, --input <dir>", "input directory", ".").option("-o, --output <dir>", "output directory", "dist").option("-t, --theme <id>", "Squisq theme ID to apply").option("--max-input-bytes <bytes>", "maximum bytes in one Markdown input").option("--max-total-input-bytes <bytes>", "maximum aggregate Markdown input bytes").option("--max-output-bytes <bytes>", "maximum bytes in one generated HTML file").option("--max-total-output-bytes <bytes>", "maximum aggregate generated HTML bytes").option("--allow-large-build", "disable default byte budgets for a trusted bulk build").action(async (opts) => {
+var buildCommand = new Command("build").description("Build markdown files into HTML output").option("-i, --input <dir>", "input directory", ".").option("-o, --output <dir>", "output directory", "dist").option("-t, --theme <id>", "Squisq theme ID to apply").option(
+  "--ignore-workspace-settings",
+  "do not apply the default theme from <input>/.docblocks/workspace.json"
+).option("--max-input-bytes <bytes>", "maximum bytes in one Markdown input").option("--max-total-input-bytes <bytes>", "maximum aggregate Markdown input bytes").option("--max-output-bytes <bytes>", "maximum bytes in one generated HTML file").option("--max-total-output-bytes <bytes>", "maximum aggregate generated HTML bytes").option("--allow-large-build", "disable default byte budgets for a trusted bulk build").action(async (opts) => {
   try {
     const result = await runBuild({
       input: opts.input,
       output: opts.output,
       theme: opts.theme,
+      ignoreWorkspaceSettings: opts.ignoreWorkspaceSettings,
       maxInputBytes: parseOptionalByteLimit("--max-input-bytes", opts.maxInputBytes),
       maxTotalInputBytes: parseOptionalByteLimit(
         "--max-total-input-bytes",
@@ -400,7 +985,7 @@ async function listMarkdownFiles(root, limits) {
       if (entryCount > limits.maxEntries) {
         throw new Error(`Build traversal exceeded ${limits.maxEntries} filesystem entries.`);
       }
-      const absolutePath = path4.join(current.directory, entry.name);
+      const absolutePath = path5.join(current.directory, entry.name);
       if (entry.isDirectory()) {
         if (current.depth >= limits.maxDepth) {
           throw new Error(`Build traversal exceeded a depth of ${limits.maxDepth}.`);
@@ -420,7 +1005,7 @@ function replaceMarkdownExtension(filePath) {
   return filePath.replace(/\.(md|markdown)$/i, ".html");
 }
 function titleFromPath(filePath) {
-  const baseName = path4.basename(filePath).replace(/\.(md|markdown)$/i, "");
+  const baseName = path5.basename(filePath).replace(/\.(md|markdown)$/i, "");
   return baseName || "DocBlocks Document";
 }
 
@@ -437,23 +1022,10 @@ import {
   rm,
   stat as stat3
 } from "fs/promises";
-import { randomUUID } from "crypto";
-import { dirname, basename, extname, join, resolve } from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+import { dirname, basename as basename2, extname, join, resolve } from "path";
 import { Command as Command2 } from "commander";
 
-// src/internal/link-support.ts
-var LINK_UNSUPPORTED_CODES = [
-  "EPERM",
-  "ENOSYS",
-  "ENOTSUP",
-  "EOPNOTSUPP",
-  "EXDEV",
-  "EMLINK"
-];
-function isLinkUnsupportedError(error) {
-  return isNodeErrorCode(error, LINK_UNSUPPORTED_CODES);
-}
-
 // src/internal/cancellation.ts
 function cancellationError(message) {
   const error = new Error(message);
@@ -536,7 +1108,7 @@ async function runConvert(inputPath, opts) {
   throwIfAborted2(opts.signal);
   const resolvedInput = resolve(inputPath);
   const outputDir = opts.outputDir ? resolve(opts.outputDir) : dirname(resolvedInput);
-  const inputBasename = basename(resolvedInput);
+  const inputBasename = basename2(resolvedInput);
   const inputExt = extname(inputBasename);
   const baseName = inputExt ? inputBasename.slice(0, -inputExt.length) : inputBasename;
   const maxInputBytes = positiveLimit(
@@ -678,7 +1250,7 @@ async function runConvert(inputPath, opts) {
     if (totalOutputBytes > maxTotalOutputBytes) {
       throw new Error(`Conversion outputs exceed the ${maxTotalOutputBytes}-byte aggregate limit.`);
     }
-    const suggestedFilename = basename(conversion.suggestedFilename);
+    const suggestedFilename = basename2(conversion.suggestedFilename);
     const outPath = join(outputDir, suggestedFilename);
     const outputPathKey = process.platform === "win32" ? outPath.toLowerCase() : outPath;
     if (outputPathKeys.has(outputPathKey)) {
@@ -794,7 +1366,7 @@ async function publishConversionBatch(outputs, outputDir, allowOverwrite, signal
       throwIfAborted2(signal);
       const output = outputs[index];
       if (!output) continue;
-      const stagedPath = join(stagingDirectory, `${index}-${randomUUID()}.stage`);
+      const stagedPath = join(stagingDirectory, `${index}-${randomUUID2()}.stage`);
       await writePrivateFile(stagedPath, output.bytes);
       stagedOutputs.push({ outputPath: output.path, stagedPath, bytes: output.bytes });
     }
@@ -824,7 +1396,7 @@ async function publishConversionBatch(outputs, outputDir, allowOverwrite, signal
             throw new Error(`Refusing to replace a non-file destination: ${output.outputPath}`);
           }
           if (existing) {
-            state.backupPath = join(stagingDirectory, `${index}-${randomUUID()}.backup`);
+            state.backupPath = join(stagingDirectory, `${index}-${randomUUID2()}.backup`);
             await rename(output.outputPath, state.backupPath);
           }
           await rename(output.stagedPath, output.outputPath);
@@ -852,8 +1424,8 @@ async function publishConversionBatch(outputs, outputDir, allowOverwrite, signal
     }
   }
 }
-async function writePrivateFile(path6, bytes) {
-  const handle = await open2(path6, "wx", 384);
+async function writePrivateFile(path7, bytes) {
+  const handle = await open2(path7, "wx", 384);
   try {
     await handle.writeFile(bytes);
     await handle.sync();
@@ -912,9 +1484,9 @@ async function assertReplaceableOutputs(outputPaths) {
     }
   }
 }
-async function lstatIfPresent(path6) {
+async function lstatIfPresent(path7) {
   try {
-    return await lstat(path6);
+    return await lstat(path7);
   } catch (error) {
     if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) return null;
     throw error;
@@ -933,11 +1505,11 @@ function throwIfAborted2(signal) {
 }
 async function applyTransformToMarkdown(markdownDoc, container, transformStyle, themeId) {
   const { markdownToDoc: markdownToDoc2, docToMarkdown } = await import("@bendyline/squisq/doc");
-  const { readFrontmatterThemeId } = await import("@bendyline/squisq/markdown");
+  const { readFrontmatterThemeId: readFrontmatterThemeId2 } = await import("@bendyline/squisq/markdown");
   const { applyTransform, extractDocImages } = await import("@bendyline/squisq/transform");
   const doc = markdownToDoc2(markdownDoc);
   const images = extractDocImages(doc.blocks);
-  const effectiveTheme = themeId ?? readFrontmatterThemeId(markdownDoc.frontmatter);
+  const effectiveTheme = themeId ?? readFrontmatterThemeId2(markdownDoc.frontmatter);
   const result = applyTransform(doc, transformStyle, { themeId: effectiveTheme, images });
   const projected = projectTransformOntoMarkdownSource(doc, result.doc);
   const transformedMarkdown = docToMarkdown(projected);
@@ -1127,7 +1699,7 @@ function isConversionErrorMetadata(error) {
 
 // src/commands/video.ts
 import { lstat as lstat2, mkdir as mkdir3 } from "fs/promises";
-import { dirname as dirname2, basename as basename2, extname as extname2, resolve as resolve2 } from "path";
+import { dirname as dirname2, basename as basename3, extname as extname2, resolve as resolve2 } from "path";
 import { Command as Command3 } from "commander";
 import {
   resolveDimensions,
@@ -1169,7 +1741,7 @@ async function runVideo(inputPath, opts, onProgress, dependencies = {}) {
     width: opts.width,
     height: opts.height
   });
-  const inputBasename = basename2(resolvedInput);
+  const inputBasename = basename3(resolvedInput);
   const inputExt = extname2(inputBasename);
   const baseName = inputExt ? inputBasename.slice(0, -inputExt.length) : inputBasename;
   const outputPath = opts.output ? resolve2(opts.output) : resolve2(dirname2(resolvedInput), `${baseName}.mp4`);
@@ -1307,7 +1879,7 @@ function selectVideoOutput(positional, option) {
 import { open as open3 } from "fs/promises";
 import { resolve as resolve3 } from "path";
 import { Command as Command4 } from "commander";
-import { decodeUtf8Text as decodeUtf8Text2 } from "@bendyline/docblocks/filesystem";
+import { decodeUtf8Text as decodeUtf8Text3 } from "@bendyline/docblocks/filesystem";
 var DEFAULT_MAX_PARSE_INPUT_BYTES = 20 * 1024 * 1024;
 var DEFAULT_MAX_PARSE_OUTPUT_BYTES = 128 * 1024 * 1024;
 async function runParse(inputPath, options = {}) {
@@ -1323,7 +1895,7 @@ async function runParse(inputPath, options = {}) {
     "parse output byte"
   );
   const bytes = await readBoundedFile(resolvedInput, maxInputBytes);
-  const content = decodeUtf8Text2(bytes, { label: "Parse input", path: resolvedInput });
+  const content = decodeUtf8Text3(bytes, { label: "Parse input", path: resolvedInput });
   const { parseMarkdown: parseMarkdown2 } = await import("@bendyline/squisq/markdown");
   const markdownDoc = parseMarkdown2(content);
   const stats = {
@@ -1386,12 +1958,98 @@ var parseCommand = new Command4("parse").description("Parse a markdown file and
   }
 });
 
+// src/commands/workspace.ts
+import { Command as Command5 } from "commander";
+import { FsError as FsError2 } from "@bendyline/docblocks/filesystem";
+import {
+  WORKSPACE_SETTINGS_PATH as WORKSPACE_SETTINGS_PATH2,
+  refreshWorkspaceOutputs,
+  resolveCatalogOutputs
+} from "@bendyline/docblocks/workspace-settings";
+import { htmlToMarkdownDocSync, markdownDocToPlainHtml } from "@bendyline/squisq-formats/html";
+async function runWorkspaceRefresh(options = {}) {
+  const io = await createNodeWorkspaceIO(options.dir ?? ".");
+  const dryRun = options.dryRun === true;
+  const settingsRead = await readWorkspaceSettings(io);
+  if (settingsRead.status === "missing") {
+    return { root: io.root, status: "missing", documentCount: 0, outputs: [], dryRun };
+  }
+  if (settingsRead.status !== "ok") {
+    throw new Error(describeWorkspaceSettingsProblem(settingsRead.message));
+  }
+  const settings = settingsRead.settings;
+  const resolved = resolveCatalogOutputs(settings);
+  if (!resolved) {
+    return { root: io.root, status: "disabled", documentCount: 0, outputs: [], dryRun };
+  }
+  const warn = options.onWarning ?? ((message) => console.warn(message));
+  const catalogThemeId = resolved.html?.themeId;
+  if (catalogThemeId && !(await getAvailableThemeIds()).includes(catalogThemeId)) {
+    warn(
+      `Catalog theme "${catalogThemeId}" from ${WORKSPACE_SETTINGS_PATH2} is not a known theme; the page renders with the standard theme.`
+    );
+  }
+  const refresh = () => refreshWorkspaceOutputs(io, settings, renderer, {
+    signal: options.signal,
+    force: options.force === true,
+    dryRun,
+    limits: options.limits
+  });
+  let result;
+  try {
+    result = await refresh();
+  } catch (error) {
+    if (!(error instanceof FsError2) || error.code !== "conflict") throw error;
+    result = await refresh();
+  }
+  return {
+    root: io.root,
+    status: "refreshed",
+    documentCount: result.documentCount,
+    outputs: result.outputs,
+    dryRun
+  };
+}
+var renderer = {
+  renderCatalogHtml: (document, { title, themeId }) => markdownDocToPlainHtml(document, { title, themeId }),
+  importHtml: (html) => htmlToMarkdownDocSync(html)
+};
+function describeWorkspaceOutput(output) {
+  const status = output.status === "would-write" ? "would write" : output.status;
+  return output.message ? `${status} ${output.path}: ${output.message}` : `${status} ${output.path}`;
+}
+var refreshCommand = new Command5("refresh").description(`Regenerate the catalog outputs enabled in <dir>/${WORKSPACE_SETTINGS_PATH2}`).argument("[dir]", "workspace root", ".").option("--force", "rewrite the catalog page even when its inputs are unchanged").option("--dry-run", "report what would change without writing anything").action(async (dir, opts) => {
+  try {
+    const result = await runWorkspaceRefresh({ dir, force: opts.force, dryRun: opts.dryRun });
+    if (result.status === "missing") {
+      console.error(
+        `No workspace settings found at ${WORKSPACE_SETTINGS_PATH2} in ${result.root}; no outputs are enabled.`
+      );
+      return;
+    }
+    if (result.status === "disabled") {
+      console.error(`${WORKSPACE_SETTINGS_PATH2} enables no catalog outputs; nothing to refresh.`);
+      return;
+    }
+    for (const output of result.outputs) console.error(describeWorkspaceOutput(output));
+    console.error(
+      `${result.dryRun ? "Dry run: " : ""}${result.documentCount} document(s) cataloged in ${result.root}.`
+    );
+    if (result.outputs.some((output) => output.status === "blocked")) process.exitCode = 1;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${message}`);
+    process.exitCode = 1;
+  }
+});
+var workspaceCommand = new Command5("workspace").description(`Maintain workspace outputs configured in ${WORKSPACE_SETTINGS_PATH2}`).addCommand(refreshCommand);
+
 // src/version.ts
 import { createHash } from "crypto";
 import { createRequire } from "module";
 import { readFileSync } from "fs";
 import { readdir, readFile as readFile2, stat as stat4 } from "fs/promises";
-import path5 from "path";
+import path6 from "path";
 var require2 = createRequire(import.meta.url);
 function getPackageVersion() {
   const pkg = readPackageJson();
@@ -1411,9 +2069,11 @@ function readPackageJson() {
 export {
   applyTransformToMarkdown,
   assertCliVideoRenderBudget,
+  describeWorkspaceOutput,
   getPackageVersion,
   runBuild,
   runConvert,
   runParse,
-  runVideo
+  runVideo,
+  runWorkspaceRefresh
 };