@bendyline/docblocks-cli 2.0.0 → 2.1.1

package/dist/index.js

@@ -1,27 +1,1328 @@
-import { Command } from 'commander';
-import { initCommand } from './commands/init.js';
-import { buildCommand } from './commands/build.js';
-import { serveCommand } from './commands/serve.js';
-import { convertCommand } from './commands/convert.js';
-import { videoCommand } from './commands/video.js';
-import { mcpCommand } from './commands/mcp.js';
-import { themesCommand } from './commands/themes.js';
-import { transformsCommand } from './commands/transforms.js';
-import { parseCommand } from './commands/parse.js';
-import { getPackageVersion } from './version.js';
-const program = new Command();
-program
-    .name('docblocks')
-    .description('Build, preview, convert, render, inspect, and automate documents')
-    .version(getPackageVersion());
-program.addCommand(initCommand);
-program.addCommand(buildCommand);
-program.addCommand(serveCommand);
-program.addCommand(convertCommand);
-program.addCommand(videoCommand);
-program.addCommand(mcpCommand);
-program.addCommand(themesCommand);
-program.addCommand(transformsCommand);
-program.addCommand(parseCommand);
-program.parse();
-//# sourceMappingURL=index.js.map
+// src/commands/build.ts
+import { Command } from "commander";
+import { mkdir, opendir, readFile, stat as stat2, writeFile } from "fs/promises";
+import path4 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 { collectImagePaths, docToHtml } from "@bendyline/squisq-formats/html";
+import { PLAYER_BUNDLE } from "@bendyline/squisq-react/standalone-source";
+
+// src/contained-file.ts
+import fs from "fs/promises";
+import path2 from "path";
+
+// src/internal/file-stat.ts
+import { open } from "fs/promises";
+async function statFileThroughDescriptor(filePath) {
+  const handle = await open(filePath, "r");
+  try {
+    return await handle.stat();
+  } finally {
+    await handle.close();
+  }
+}
+
+// src/internal/paths.ts
+import path from "path";
+function isPathInside(root, candidate) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === "" || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
+}
+
+// src/contained-file.ts
+var CONTAINED_READ_CHUNK_BYTES = 64 * 1024;
+async function readContainedFile(rootPath, candidatePath, maximumBytes, options = {}) {
+  const { signal, afterReadChunk } = options;
+  signal?.throwIfAborted();
+  const physicalRoot = await fs.realpath(path2.resolve(rootPath));
+  signal?.throwIfAborted();
+  const physicalCandidate = await fs.realpath(path2.resolve(candidatePath));
+  signal?.throwIfAborted();
+  if (!isPathInside(physicalRoot, physicalCandidate)) {
+    throw new Error("File is outside the authorized root");
+  }
+  const handle = await fs.open(physicalCandidate, "r");
+  try {
+    signal?.throwIfAborted();
+    const before = await handle.stat();
+    signal?.throwIfAborted();
+    if (!before.isFile() || before.size > maximumBytes) {
+      throw new Error("File exceeds the configured size limit");
+    }
+    await assertIdentity(physicalRoot, physicalCandidate, before, signal);
+    signal?.throwIfAborted();
+    const result = Buffer.alloc(before.size);
+    let offset = 0;
+    while (offset < result.length) {
+      signal?.throwIfAborted();
+      const length = Math.min(CONTAINED_READ_CHUNK_BYTES, result.length - offset);
+      const { bytesRead } = await handle.read(result, offset, length, offset);
+      if (bytesRead === 0) break;
+      offset += bytesRead;
+      await afterReadChunk?.(offset, result.length);
+      signal?.throwIfAborted();
+    }
+    signal?.throwIfAborted();
+    const extra = Buffer.alloc(1);
+    if ((await handle.read(extra, 0, 1, offset)).bytesRead > 0) {
+      throw new Error("File grew beyond the configured size limit");
+    }
+    signal?.throwIfAborted();
+    const after = await handle.stat();
+    signal?.throwIfAborted();
+    if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
+      throw new Error("File changed while it was being read");
+    }
+    await assertIdentity(physicalRoot, physicalCandidate, after, signal);
+    signal?.throwIfAborted();
+    return result.subarray(0, offset);
+  } finally {
+    await handle.close();
+  }
+}
+async function assertIdentity(physicalRoot, candidatePath, descriptorStat, signal) {
+  signal?.throwIfAborted();
+  const physicalCandidate = await fs.realpath(candidatePath);
+  signal?.throwIfAborted();
+  if (!isPathInside(physicalRoot, physicalCandidate)) {
+    throw new Error("File escaped the authorized root while it was being read");
+  }
+  const pathStat = await statFileThroughDescriptor(physicalCandidate);
+  signal?.throwIfAborted();
+  if (descriptorStat.dev !== pathStat.dev || descriptorStat.ino !== pathStat.ino) {
+    throw new Error("File changed physical identity while it was being read");
+  }
+}
+
+// src/internal/node-error.ts
+function isNodeErrorCode(error, codes) {
+  if (!(error instanceof Error) || !("code" in error)) return false;
+  const code = String(error.code);
+  return typeof codes === "string" ? code === codes : codes.includes(code);
+}
+
+// src/internal/theme.ts
+async function getAvailableThemeIds() {
+  const { getAvailableThemes } = await import("@bendyline/squisq/schemas");
+  return getAvailableThemes();
+}
+async function assertKnownThemeId(themeId, customThemeIds = []) {
+  if (!themeId) return;
+  const builtInThemeIds = await getAvailableThemeIds();
+  if (builtInThemeIds.includes(themeId) || customThemeIds.includes(themeId)) return;
+  throw new Error(`Unknown theme "${themeId}". Available: ${builtInThemeIds.join(", ")}`);
+}
+
+// src/render-html.ts
+var MAX_REFERENCED_IMAGES = 100;
+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 markdownDoc = parseMarkdown(markdown);
+  const doc = markdownToDoc(markdownDoc);
+  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))
+  ) : void 0;
+  return docToHtml(doc, {
+    playerScript: PLAYER_BUNDLE,
+    images,
+    title: options.title,
+    mode: options.mode ?? "static",
+    themeId: options.themeId
+  });
+}
+async function readReferencedImages(doc, sourcePath, assetRoot, maxAssetBytes, allowReferencedAsset, warn) {
+  const images = /* @__PURE__ */ new Map();
+  const root = await realpathIfPresent(path3.resolve(assetRoot));
+  const baseDir = await realpathIfPresent(path3.dirname(path3.resolve(sourcePath)));
+  if (!root || !baseDir || !isPathInside(root, baseDir)) return images;
+  let totalBytes = 0;
+  const referenced = [...collectImagePaths(doc)];
+  const embeddable = referenced.slice(0, MAX_REFERENCED_IMAGES);
+  const dropped = referenced.slice(MAX_REFERENCED_IMAGES);
+  if (dropped.length > 0) {
+    warn(
+      `Skipped ${dropped.length} of ${referenced.length} referenced images: the render embeds at most ${MAX_REFERENCED_IMAGES}. Not embedded: ${describeList(dropped)}`
+    );
+  }
+  for (const imagePath of embeddable) {
+    if (!isLocalRelativePath(imagePath)) continue;
+    const normalizedPath = stripUrlSuffix(imagePath);
+    const absolutePath = path3.resolve(baseDir, normalizedPath);
+    if (!isPathInside(root, absolutePath)) continue;
+    try {
+      const physicalPath = await realpath(absolutePath);
+      if (!isPathInside(root, physicalPath)) continue;
+      if (allowReferencedAsset && !allowReferencedAsset({
+        assetRoot: root,
+        requestedPath: absolutePath,
+        physicalPath
+      })) {
+        continue;
+      }
+      const info = await stat(physicalPath);
+      if (!info.isFile()) {
+        warn(`Skipped referenced image "${imagePath}": it is not a regular file.`);
+        continue;
+      }
+      if (info.size > MAX_SINGLE_ASSET_BYTES) {
+        warn(
+          `Skipped referenced image "${imagePath}": ${info.size} bytes exceeds the ${MAX_SINGLE_ASSET_BYTES}-byte per-image embed limit.`
+        );
+        continue;
+      }
+      if (totalBytes + info.size > maxAssetBytes) {
+        warn(
+          `Skipped referenced image "${imagePath}": embedding ${info.size} more bytes would exceed the ${maxAssetBytes}-byte total image budget (${totalBytes} bytes already embedded).`
+        );
+        continue;
+      }
+      const data = await readContainedFile(root, physicalPath, MAX_SINGLE_ASSET_BYTES);
+      totalBytes += data.byteLength;
+      images.set(imagePath, toExactArrayBuffer(data));
+    } catch (error) {
+      if (isMissingPathError(error)) continue;
+      const contextualError = new Error(`Failed to embed referenced image "${imagePath}".`);
+      contextualError.cause = error;
+      throw contextualError;
+    }
+  }
+  return images;
+}
+async function realpathIfPresent(candidate) {
+  try {
+    return await realpath(candidate);
+  } catch (error) {
+    if (isMissingPathError(error)) return null;
+    throw error;
+  }
+}
+function isMissingPathError(error) {
+  return isNodeErrorCode(error, ["ENOENT", "ENOTDIR"]);
+}
+function describeList(values, shown = 5) {
+  const head = values.slice(0, shown).map((value) => `"${value}"`);
+  const remaining = values.length - head.length;
+  return remaining > 0 ? `${head.join(", ")} (and ${remaining} more)` : head.join(", ");
+}
+function isLocalRelativePath(candidate) {
+  return !path3.isAbsolute(candidate) && !candidate.startsWith("/") && !/^(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(candidate) && !candidate.startsWith("data:");
+}
+function stripUrlSuffix(candidate) {
+  return candidate.split(/[?#]/, 1)[0] ?? candidate;
+}
+function toExactArrayBuffer(data) {
+  const copy = new Uint8Array(data.byteLength);
+  copy.set(data);
+  return copy.buffer;
+}
+
+// src/internal/limits.ts
+function positiveLimit(value, fallback, label) {
+  const selected = value ?? fallback;
+  if (!Number.isSafeInteger(selected) || selected < 1) {
+    throw new Error(`Invalid ${label} limit.`);
+  }
+  return selected;
+}
+
+// src/commands/build.ts
+import { decodeUtf8Text } 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;
+var DEFAULT_MAX_BUILD_TOTAL_INPUT_BYTES = 512 * 1024 * 1024;
+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);
+  let inputStat;
+  try {
+    inputStat = await stat2(inputDir);
+  } catch (error) {
+    if (!isNodeErrorCode(error, "ENOENT")) throw error;
+    throw new Error(`Input directory not found: ${inputDir}`);
+  }
+  if (!inputStat.isDirectory()) throw new Error(`Input is not a directory: ${inputDir}`);
+  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")
+  });
+  if (markdownFiles.length === 0) {
+    throw new Error(`No markdown files found in ${inputDir}.`);
+  }
+  const byteLimits = resolveBuildByteLimits(opts);
+  await assertBuildInputSizes(markdownFiles, byteLimits);
+  await mkdir(outputDir, { recursive: true });
+  const builtFiles = [];
+  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 sourceBytes = await readFile(sourcePath);
+    if (sourceBytes.byteLength > byteLimits.maxInputBytes) {
+      throw new Error(
+        `Build input ${sourcePath} exceeds the ${byteLimits.maxInputBytes}-byte per-file limit.`
+      );
+    }
+    totalInputBytes += sourceBytes.byteLength;
+    if (totalInputBytes > byteLimits.maxTotalInputBytes) {
+      throw new Error(
+        `Build inputs exceed the ${byteLimits.maxTotalInputBytes}-byte aggregate limit.`
+      );
+    }
+    const source = decodeUtf8Text(sourceBytes, { label: "Build input", path: sourcePath });
+    const html = await renderMarkdownHtml(source, {
+      title: titleFromPath(relativePath),
+      sourcePath,
+      assetRoot: inputDir,
+      themeId: opts.theme,
+      mode: "static"
+    });
+    const outputBytes = Buffer.byteLength(html, "utf8");
+    if (outputBytes > byteLimits.maxOutputBytes) {
+      throw new Error(
+        `Build output ${outputPath} exceeds the ${byteLimits.maxOutputBytes}-byte per-file limit.`
+      );
+    }
+    totalOutputBytes += outputBytes;
+    if (totalOutputBytes > byteLimits.maxTotalOutputBytes) {
+      throw new Error(
+        `Build outputs exceed the ${byteLimits.maxTotalOutputBytes}-byte aggregate limit.`
+      );
+    }
+    await mkdir(path4.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) => {
+  try {
+    const result = await runBuild({
+      input: opts.input,
+      output: opts.output,
+      theme: opts.theme,
+      maxInputBytes: parseOptionalByteLimit("--max-input-bytes", opts.maxInputBytes),
+      maxTotalInputBytes: parseOptionalByteLimit(
+        "--max-total-input-bytes",
+        opts.maxTotalInputBytes
+      ),
+      maxOutputBytes: parseOptionalByteLimit("--max-output-bytes", opts.maxOutputBytes),
+      maxTotalOutputBytes: parseOptionalByteLimit(
+        "--max-total-output-bytes",
+        opts.maxTotalOutputBytes
+      ),
+      allowLargeBuild: opts.allowLargeBuild
+    });
+    for (const outFile of result.builtFiles) {
+      console.error(`Built: ${outFile}`);
+    }
+    console.error(`Done. ${result.builtFiles.length} file(s) built to ${result.outputDir}`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${message}`);
+    process.exitCode = 1;
+  }
+});
+function resolveBuildByteLimits(options) {
+  const unlimitedDefault = options.allowLargeBuild === true ? Number.MAX_SAFE_INTEGER : void 0;
+  return {
+    maxInputBytes: positiveLimit(
+      options.maxInputBytes,
+      unlimitedDefault ?? DEFAULT_MAX_BUILD_INPUT_BYTES,
+      "build input byte"
+    ),
+    maxTotalInputBytes: positiveLimit(
+      options.maxTotalInputBytes,
+      unlimitedDefault ?? DEFAULT_MAX_BUILD_TOTAL_INPUT_BYTES,
+      "build aggregate input byte"
+    ),
+    maxOutputBytes: positiveLimit(
+      options.maxOutputBytes,
+      unlimitedDefault ?? DEFAULT_MAX_BUILD_OUTPUT_BYTES,
+      "build output byte"
+    ),
+    maxTotalOutputBytes: positiveLimit(
+      options.maxTotalOutputBytes,
+      unlimitedDefault ?? DEFAULT_MAX_BUILD_TOTAL_OUTPUT_BYTES,
+      "build aggregate output byte"
+    )
+  };
+}
+async function assertBuildInputSizes(markdownFiles, limits) {
+  let totalBytes = 0;
+  for (const sourcePath of markdownFiles) {
+    const info = await stat2(sourcePath);
+    if (!info.isFile()) throw new Error(`Build input is not a file: ${sourcePath}`);
+    if (info.size > limits.maxInputBytes) {
+      throw new Error(
+        `Build input ${sourcePath} exceeds the ${limits.maxInputBytes}-byte per-file limit.`
+      );
+    }
+    totalBytes += info.size;
+    if (totalBytes > limits.maxTotalInputBytes) {
+      throw new Error(`Build inputs exceed the ${limits.maxTotalInputBytes}-byte aggregate limit.`);
+    }
+  }
+}
+function parseOptionalByteLimit(name, value) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new Error(`${name} must be a positive safe integer`);
+  }
+  return parsed;
+}
+async function listMarkdownFiles(root, limits) {
+  const files = [];
+  const pending = [{ directory: root, depth: 0 }];
+  let entryCount = 0;
+  while (pending.length > 0) {
+    const current = pending.pop();
+    const entries = await opendir(current.directory);
+    for await (const entry of entries) {
+      entryCount += 1;
+      if (entryCount > limits.maxEntries) {
+        throw new Error(`Build traversal exceeded ${limits.maxEntries} filesystem entries.`);
+      }
+      const absolutePath = path4.join(current.directory, entry.name);
+      if (entry.isDirectory()) {
+        if (current.depth >= limits.maxDepth) {
+          throw new Error(`Build traversal exceeded a depth of ${limits.maxDepth}.`);
+        }
+        pending.push({ directory: absolutePath, depth: current.depth + 1 });
+      } else if (entry.isFile() && isMarkdownFile(entry.name)) {
+        files.push(absolutePath);
+      }
+    }
+  }
+  return files.sort((a, b) => a.localeCompare(b));
+}
+function isMarkdownFile(fileName) {
+  return /\.(md|markdown)$/i.test(fileName);
+}
+function replaceMarkdownExtension(filePath) {
+  return filePath.replace(/\.(md|markdown)$/i, ".html");
+}
+function titleFromPath(filePath) {
+  const baseName = path4.basename(filePath).replace(/\.(md|markdown)$/i, "");
+  return baseName || "DocBlocks Document";
+}
+
+// src/commands/convert.ts
+import {
+  link,
+  lstat,
+  mkdir as mkdir2,
+  mkdtemp,
+  open as open2,
+  opendir as opendir2,
+  realpath as realpath2,
+  rename,
+  rm,
+  stat as stat3
+} from "fs/promises";
+import { randomUUID } from "crypto";
+import { dirname, basename, 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);
+  error.name = "AbortError";
+  return error;
+}
+function throwIfAborted(signal, message) {
+  if (!signal?.aborted) return;
+  throw signal.reason ?? cancellationError(message);
+}
+
+// src/commands/convert.ts
+var DEFAULT_FORMATS = ["docx", "pptx", "pdf", "html", "dbk"];
+var DEFAULT_MAX_CONVERT_INPUT_BYTES = 1024 * 1024 * 1024;
+var DEFAULT_MAX_CONVERT_INPUT_ENTRIES = 2e4;
+var DEFAULT_MAX_CONVERT_OUTPUT_BYTES = 512 * 1024 * 1024;
+var DEFAULT_MAX_CONVERT_TOTAL_OUTPUT_BYTES = 1024 * 1024 * 1024;
+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 inputExt = extname(inputBasename);
+  const baseName = inputExt ? inputBasename.slice(0, -inputExt.length) : inputBasename;
+  const maxInputBytes = positiveLimit(
+    opts.maxInputBytes,
+    DEFAULT_MAX_CONVERT_INPUT_BYTES,
+    "conversion input byte"
+  );
+  const maxInputEntries = positiveLimit(
+    opts.maxInputEntries,
+    DEFAULT_MAX_CONVERT_INPUT_ENTRIES,
+    "conversion input entry"
+  );
+  const maxOutputBytes = positiveLimit(
+    opts.maxOutputBytes,
+    DEFAULT_MAX_CONVERT_OUTPUT_BYTES,
+    "conversion output byte"
+  );
+  const maxTotalOutputBytes = positiveLimit(
+    opts.maxTotalOutputBytes,
+    DEFAULT_MAX_CONVERT_TOTAL_OUTPUT_BYTES,
+    "conversion aggregate output byte"
+  );
+  await assertInputWithinBudget(resolvedInput, maxInputBytes, maxInputEntries, opts.signal);
+  const squisq = await import("@bendyline/squisq-cli/api");
+  throwIfAborted2(opts.signal);
+  const registry = opts.registry ?? squisq.createCliRegistry();
+  const exportableIds = registry.list().filter((definition) => definition.exportDoc !== void 0).map((definition) => definition.id);
+  const exportable = new Set(exportableIds);
+  const registryHint = "Choose a format reported by the linked Squisq CLI registry.";
+  const requestedList = opts.formats;
+  const explicitFormats = requestedList !== void 0;
+  const requested = explicitFormats ? requestedList.split(",").map((format) => format.trim().toLowerCase()).filter(Boolean) : [...DEFAULT_FORMATS];
+  if (explicitFormats) {
+    const duplicate = firstDuplicate(requested);
+    if (duplicate) {
+      throw new squisq.ConversionError(
+        "unknown-format",
+        `Duplicate conversion target: ${duplicate}. List each requested format once.`,
+        { format: duplicate, hint: registryHint }
+      );
+    }
+  }
+  const unknown = requested.filter((format) => !exportable.has(format));
+  if (unknown.length > 0 && explicitFormats) {
+    throw new squisq.ConversionError(
+      "unknown-format",
+      `Unknown or non-exportable format${unknown.length === 1 ? "" : "s"} "${unknown.join(", ")}". Valid: ${exportableIds.join(", ")}`,
+      { format: unknown[0], hint: registryHint }
+    );
+  }
+  if (unknown.length > 0) {
+    console.warn(
+      `Unknown or non-exportable default format${unknown.length === 1 ? "" : "s"} "${unknown.join(", ")}" \u2014 skipping. Valid: ${exportableIds.join(", ")}`
+    );
+  }
+  const formats = requested.filter((format) => exportable.has(format));
+  if (formats.length === 0) {
+    throw new squisq.ConversionError(
+      "unknown-format",
+      `No valid formats specified. Valid: ${exportableIds.join(", ")}`,
+      { format: requested[0], hint: registryHint }
+    );
+  }
+  if (opts.transform) {
+    const { getTransformStyleIds } = await import("@bendyline/squisq/transform");
+    throwIfAborted2(opts.signal);
+    const styles = getTransformStyleIds();
+    if (!styles.includes(opts.transform)) {
+      throw new Error(
+        `Unknown transform style "${opts.transform}". Available: ${styles.join(", ")}`
+      );
+    }
+  }
+  const allowOverwrite = opts.allowOverwrite === true;
+  if (!allowOverwrite) {
+    await assertOutputsAvailable(
+      formats.map((format) => plannedOutputPath(outputDir, baseName, format, registry)),
+      opts.signal
+    );
+  }
+  console.error(`Reading: ${resolvedInput}`);
+  const result = await squisq.readInput(resolvedInput, { signal: opts.signal });
+  throwIfAborted2(opts.signal);
+  const { container } = result;
+  await assertKnownThemeId(
+    opts.theme,
+    result.doc.customThemes?.map((theme) => theme.id)
+  );
+  throwIfAborted2(opts.signal);
+  let exportMarkdownDoc = result.markdownDoc;
+  if (opts.transform && exportMarkdownDoc) {
+    exportMarkdownDoc = await applyTransformToMarkdown(
+      exportMarkdownDoc,
+      container,
+      opts.transform,
+      opts.theme
+    );
+    throwIfAborted2(opts.signal);
+    console.error(`  Applied transform: ${opts.transform}`);
+  }
+  const source = exportMarkdownDoc ? { kind: "markdown", markdown: exportMarkdownDoc, container, baseName } : { kind: "doc", doc: result.doc, container, baseName };
+  const preparedOutputs = [];
+  const outputPathKeys = /* @__PURE__ */ new Set();
+  let totalOutputBytes = 0;
+  for (const format of formats) {
+    throwIfAborted2(opts.signal);
+    const conversion = await squisq.convert(source, format, {
+      signal: opts.signal,
+      registry,
+      title: baseName,
+      themeId: opts.theme,
+      ...!exportMarkdownDoc && opts.transform ? { transformStyle: opts.transform } : {}
+    });
+    throwIfAborted2(opts.signal);
+    if (conversion.bytes.byteLength > maxOutputBytes) {
+      throw new Error(`${format} output exceeds the ${maxOutputBytes}-byte conversion limit.`);
+    }
+    totalOutputBytes += conversion.bytes.byteLength;
+    if (totalOutputBytes > maxTotalOutputBytes) {
+      throw new Error(`Conversion outputs exceed the ${maxTotalOutputBytes}-byte aggregate limit.`);
+    }
+    const suggestedFilename = basename(conversion.suggestedFilename);
+    const outPath = join(outputDir, suggestedFilename);
+    const outputPathKey = process.platform === "win32" ? outPath.toLowerCase() : outPath;
+    if (outputPathKeys.has(outputPathKey)) {
+      throw new Error(`Multiple conversion targets resolve to the same output: ${outPath}`);
+    }
+    outputPathKeys.add(outputPathKey);
+    preparedOutputs.push({
+      path: outPath,
+      format,
+      bytes: conversion.bytes,
+      size: conversion.bytes.byteLength,
+      mimeType: conversion.mimeType,
+      suggestedFilename: conversion.suggestedFilename,
+      warnings: [...conversion.warnings]
+    });
+  }
+  await publishConversionBatch(preparedOutputs, outputDir, allowOverwrite, opts.signal);
+  const outputFiles = preparedOutputs.map(
+    ({ bytes: _bytes, ...output }) => output
+  );
+  for (const output of outputFiles) {
+    for (const warning of output.warnings) {
+      console.error(`  Warning [${output.format}]: ${warning}`);
+    }
+    console.error(`  \u2713 ${output.path}`);
+  }
+  console.error("Done.");
+  return { outputFiles };
+}
+async function assertInputWithinBudget(inputPath, maxBytes, maxEntries, signal) {
+  let rootInfo;
+  try {
+    rootInfo = await stat3(inputPath);
+  } catch (error) {
+    if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) {
+      throw new Error(`Conversion input not found: ${inputPath}`);
+    }
+    throw error;
+  }
+  if (rootInfo.isFile()) {
+    if (rootInfo.size > maxBytes) {
+      throw new Error(`Conversion input exceeds the ${maxBytes}-byte limit.`);
+    }
+    return;
+  }
+  if (!rootInfo.isDirectory()) throw new Error(`Unsupported conversion input: ${inputPath}`);
+  const pending = [inputPath];
+  const visitedDirectories = /* @__PURE__ */ new Set();
+  let entryCount = 0;
+  let totalBytes = 0;
+  while (pending.length > 0) {
+    throwIfAborted2(signal);
+    const directory = pending.pop();
+    const physicalDirectory = await realpath2(directory);
+    if (visitedDirectories.has(physicalDirectory)) continue;
+    visitedDirectories.add(physicalDirectory);
+    const entries = await opendir2(directory);
+    for await (const entry of entries) {
+      throwIfAborted2(signal);
+      entryCount += 1;
+      if (entryCount > maxEntries) {
+        throw new Error(`Conversion input exceeds the ${maxEntries}-entry limit.`);
+      }
+      const entryPath = join(directory, entry.name);
+      const info = await stat3(entryPath);
+      if (info.isDirectory()) pending.push(entryPath);
+      else if (info.isFile()) {
+        totalBytes += info.size;
+        if (totalBytes > maxBytes) {
+          throw new Error(`Conversion input exceeds the ${maxBytes}-byte limit.`);
+        }
+      }
+    }
+  }
+}
+function plannedOutputPath(outputDir, baseName, format, registry) {
+  const extension = registry.get(format)?.extensions[0]?.replace(/^\.+/u, "") ?? format;
+  return join(outputDir, `${baseName}.${extension}`);
+}
+async function assertOutputsAvailable(outputPaths, signal) {
+  const conflicts = [];
+  for (const outputPath of outputPaths) {
+    throwIfAborted2(signal);
+    if (await lstatIfPresent(outputPath)) conflicts.push(outputPath);
+  }
+  throwIfAborted2(signal);
+  if (conflicts.length > 0) throw new Error(overwriteConflictMessage(conflicts));
+}
+function overwriteConflictMessage(conflicts) {
+  const noun = conflicts.length === 1 ? "file" : "files";
+  const pronoun = conflicts.length === 1 ? "it" : "them";
+  return [
+    `Refusing to overwrite ${conflicts.length} existing ${noun}:`,
+    ...conflicts.map((conflict) => `  ${conflict}`),
+    `Pass --allow-overwrite to replace ${pronoun}, or use --output-dir to write elsewhere.`
+  ].join("\n");
+}
+var ConversionRollbackError = class extends Error {
+  constructor(message, publicationError, rollbackErrors) {
+    super(message);
+    this.name = "ConversionRollbackError";
+    this.publicationError = publicationError;
+    this.rollbackErrors = rollbackErrors;
+  }
+};
+async function publishConversionBatch(outputs, outputDir, allowOverwrite, signal, afterPublishForTest) {
+  await mkdir2(outputDir, { recursive: true });
+  const stagingDirectory = await mkdtemp(join(outputDir, ".docblocks-convert-"));
+  let preserveRecoveryDirectory = false;
+  try {
+    const stagedOutputs = [];
+    for (let index = 0; index < outputs.length; index += 1) {
+      throwIfAborted2(signal);
+      const output = outputs[index];
+      if (!output) continue;
+      const stagedPath = join(stagingDirectory, `${index}-${randomUUID()}.stage`);
+      await writePrivateFile(stagedPath, output.bytes);
+      stagedOutputs.push({ outputPath: output.path, stagedPath, bytes: output.bytes });
+    }
+    if (!allowOverwrite) {
+      await assertOutputsAvailable(
+        stagedOutputs.map((output) => output.outputPath),
+        signal
+      );
+    } else {
+      await assertReplaceableOutputs(stagedOutputs.map((output) => output.outputPath));
+    }
+    const committed = [];
+    try {
+      for (let index = 0; index < stagedOutputs.length; index += 1) {
+        throwIfAborted2(signal);
+        const output = stagedOutputs[index];
+        if (!output) continue;
+        const state = {
+          outputPath: output.outputPath,
+          backupPath: null,
+          published: false
+        };
+        committed.push(state);
+        if (allowOverwrite) {
+          const existing = await lstatIfPresent(output.outputPath);
+          if (existing && !existing.isFile() && !existing.isSymbolicLink()) {
+            throw new Error(`Refusing to replace a non-file destination: ${output.outputPath}`);
+          }
+          if (existing) {
+            state.backupPath = join(stagingDirectory, `${index}-${randomUUID()}.backup`);
+            await rename(output.outputPath, state.backupPath);
+          }
+          await rename(output.stagedPath, output.outputPath);
+        } else {
+          await publishStagedFileNoReplace(output);
+        }
+        state.published = true;
+        await afterPublishForTest?.(committed.length);
+      }
+    } catch (error) {
+      const rollbackErrors = await rollbackConversionBatch(committed);
+      if (rollbackErrors.length > 0) {
+        preserveRecoveryDirectory = true;
+        throw new ConversionRollbackError(
+          `Conversion publication failed and automatic rollback was incomplete. Recovery files remain in ${stagingDirectory}.`,
+          error,
+          rollbackErrors
+        );
+      }
+      throw error;
+    }
+  } finally {
+    if (!preserveRecoveryDirectory) {
+      await rm(stagingDirectory, { recursive: true, force: true }).catch(() => void 0);
+    }
+  }
+}
+async function writePrivateFile(path6, bytes) {
+  const handle = await open2(path6, "wx", 384);
+  try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+async function publishStagedFileNoReplace(output) {
+  try {
+    await link(output.stagedPath, output.outputPath);
+    return;
+  } catch (error) {
+    if (isNodeErrorCode(error, "EEXIST")) {
+      throw new Error(overwriteConflictMessage([output.outputPath]));
+    }
+    if (!isLinkUnsupportedError(error)) throw error;
+  }
+  let published;
+  try {
+    published = await open2(output.outputPath, "wx", 384);
+  } catch (error) {
+    if (isNodeErrorCode(error, "EEXIST")) {
+      throw new Error(overwriteConflictMessage([output.outputPath]));
+    }
+    throw error;
+  }
+  try {
+    await published.writeFile(output.bytes);
+    await published.sync();
+    await published.close();
+  } catch (error) {
+    await published.close().catch(() => void 0);
+    await rm(output.outputPath, { force: true }).catch(() => void 0);
+    throw error;
+  }
+}
+async function rollbackConversionBatch(committed) {
+  const rollbackErrors = [];
+  for (let index = committed.length - 1; index >= 0; index -= 1) {
+    const state = committed[index];
+    if (!state) continue;
+    try {
+      if (state.published) await rm(state.outputPath, { force: true });
+      if (state.backupPath) await rename(state.backupPath, state.outputPath);
+    } catch (error) {
+      rollbackErrors.push(error);
+    }
+  }
+  return rollbackErrors;
+}
+async function assertReplaceableOutputs(outputPaths) {
+  for (const outputPath of outputPaths) {
+    const existing = await lstatIfPresent(outputPath);
+    if (existing && !existing.isFile() && !existing.isSymbolicLink()) {
+      throw new Error(`Refusing to replace a non-file destination: ${outputPath}`);
+    }
+  }
+}
+async function lstatIfPresent(path6) {
+  try {
+    return await lstat(path6);
+  } catch (error) {
+    if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) return null;
+    throw error;
+  }
+}
+function firstDuplicate(values) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    if (seen.has(value)) return value;
+    seen.add(value);
+  }
+  return void 0;
+}
+function throwIfAborted2(signal) {
+  throwIfAborted(signal, "Document conversion was cancelled");
+}
+async function applyTransformToMarkdown(markdownDoc, container, transformStyle, themeId) {
+  const { markdownToDoc: markdownToDoc2, docToMarkdown } = await import("@bendyline/squisq/doc");
+  const { readFrontmatterThemeId } = 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 result = applyTransform(doc, transformStyle, { themeId: effectiveTheme, images });
+  const projected = projectTransformOntoMarkdownSource(doc, result.doc);
+  const transformedMarkdown = docToMarkdown(projected);
+  const resolvedTheme = effectiveTheme ?? result.doc.themeId ?? doc.themeId;
+  if (!resolvedTheme) return transformedMarkdown;
+  return {
+    ...transformedMarkdown,
+    frontmatter: {
+      ...transformedMarkdown.frontmatter ?? {},
+      "squisq-theme": resolvedTheme
+    }
+  };
+}
+function projectTransformOntoMarkdownSource(source, transformed) {
+  const candidatesBySource = /* @__PURE__ */ new Map();
+  const timedSourceBlocks = collectTransformSourceBlocks(source.blocks).sort(
+    (left, right) => left.startTime - right.startTime
+  );
+  const collectCandidates = (blocks) => {
+    for (const block of blocks) {
+      const provenance = block;
+      const sourceBlockId = provenance.sourceBlockId ?? findSourceBlockAtTime(timedSourceBlocks, provenance.sourceStartTime)?.id;
+      if (sourceBlockId && block.template) {
+        const candidates = candidatesBySource.get(sourceBlockId) ?? [];
+        candidates.push(block);
+        candidatesBySource.set(sourceBlockId, candidates);
+      }
+      if (block.children) collectCandidates(block.children);
+    }
+  };
+  collectCandidates(transformed.blocks);
+  const projectBlock = (block) => {
+    const children = block.children?.map(projectBlock);
+    const visual = selectVisualCandidate(candidatesBySource.get(block.id));
+    if (!visual || !block.sourceHeading) {
+      return { ...block, ...children ? { children } : {} };
+    }
+    const { autoTemplate: _autoTemplate, ...sourceBlock } = block;
+    void _autoTemplate;
+    const templateOverrides = {
+      ...visual.overrides,
+      ...block.sourceHeading.templateAnnotation?.params ?? {},
+      ...block.templateOverrides ?? {}
+    };
+    const sourceHeading = {
+      ...block.sourceHeading,
+      templateAnnotation: {
+        ...block.sourceHeading.templateAnnotation ?? {},
+        template: visual.block.template,
+        ...Object.keys(templateOverrides).length > 0 ? { params: templateOverrides } : {}
+      }
+    };
+    return {
+      ...sourceBlock,
+      ...children ? { children } : {},
+      template: visual.block.template,
+      templateOverrides,
+      sourceHeading,
+      ...block.transition || visual.block.transition ? { transition: block.transition ?? visual.block.transition } : {}
+    };
+  };
+  return {
+    ...source,
+    blocks: source.blocks.map(projectBlock),
+    themeId: transformed.themeId ?? source.themeId
+  };
+}
+function collectTransformSourceBlocks(blocks) {
+  const sourceBlocks = [];
+  for (const block of blocks) {
+    if (block.children && block.children.length > 0) {
+      if (!block.contents || block.contents.length === 0) sourceBlocks.push(block);
+      sourceBlocks.push(...collectTransformSourceBlocks(block.children));
+    } else {
+      sourceBlocks.push(block);
+    }
+  }
+  return sourceBlocks;
+}
+function findSourceBlockAtTime(sourceBlocks, sourceStartTime) {
+  if (sourceStartTime === void 0) return void 0;
+  let match;
+  for (const block of sourceBlocks) {
+    if (block.startTime > sourceStartTime) break;
+    match = block;
+  }
+  return match;
+}
+function selectVisualCandidate(candidates) {
+  if (!candidates || candidates.length === 0) return void 0;
+  for (const candidate of candidates) {
+    if (candidate.id.startsWith("transform-header-") || candidate.id.startsWith("transform-img-") || candidate.template === "sectionHeader") {
+      continue;
+    }
+    const overrides = serializeVisualInputs(candidate);
+    if (overrides) return { block: candidate, overrides };
+  }
+  return void 0;
+}
+function serializeVisualInputs(block) {
+  const input = block;
+  switch (block.template) {
+    case "title":
+      return serializeStringInputs(input, ["title"], ["subtitle", "backgroundColor"]);
+    case "statHighlight":
+      return serializeStringInputs(input, ["stat", "description"], ["detail", "colorScheme"]);
+    case "quote":
+      return serializeStringInputs(input, ["quote"], ["attribution"]);
+    case "fullBleedQuote":
+      return serializeStringInputs(input, ["text"], ["colorScheme"]);
+    case "factCard":
+      return serializeStringInputs(input, ["fact", "explanation"], ["source"]);
+    case "definitionCard":
+      return serializeStringInputs(input, ["term", "definition"], ["origin", "colorScheme"]);
+    case "dateEvent":
+      return serializeStringInputs(input, ["date", "description"], ["footer", "mood"]);
+    case "twoColumn": {
+      const left = serializeLabeledPair(input.left);
+      const right = serializeLabeledPair(input.right);
+      if (!left || !right) return void 0;
+      return {
+        left,
+        right,
+        ...serializeStringInputs(input, [], ["header", "leftColor", "rightColor"]) ?? {}
+      };
+    }
+    default:
+      return void 0;
+  }
+}
+function serializeStringInputs(input, required, optional) {
+  const serialized = {};
+  for (const key of required) {
+    const value = input[key];
+    if (typeof value !== "string") return void 0;
+    serialized[key] = value;
+  }
+  for (const key of optional) {
+    const value = input[key];
+    if (typeof value === "string") serialized[key] = value;
+  }
+  return serialized;
+}
+function serializeLabeledPair(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const pair = value;
+  if (typeof pair.label !== "string") return void 0;
+  return typeof pair.sublabel === "string" && pair.sublabel ? `${pair.label}|${pair.sublabel}` : pair.label;
+}
+var convertCommand = new Command2("convert").description("Convert a document through the linked Squisq format registry").argument("<input>", "Path to a supported document, .zip/.dbk container, or folder").option("-o, --output-dir <dir>", "Output directory (default: same as input)").option(
+  "-f, --formats <list>",
+  `Comma-separated linked Squisq export formats (default: ${DEFAULT_FORMATS.join(", ")})`
+).option("-t, --theme <id>", "Squisq theme ID to apply (e.g., documentary, cinematic, bold)").option(
+  "--transform <style>",
+  "Transform style to apply before export (e.g., documentary, magazine, minimal)"
+).option("--allow-overwrite", "replace existing output files instead of refusing the run").action(async (inputPath, opts) => {
+  try {
+    await runConvert(inputPath, opts);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${message}`);
+    if (isConversionErrorMetadata(err)) {
+      console.error(`  Code: ${err.code}${err.format ? ` (${err.format})` : ""}`);
+      if (err.hint) console.error(`  Hint: ${err.hint}`);
+    }
+    process.exitCode = 1;
+  }
+});
+function isConversionErrorMetadata(error) {
+  if (!(error instanceof Error)) return false;
+  const candidate = error;
+  if (typeof candidate.code !== "string") return false;
+  if (candidate.format !== void 0 && typeof candidate.format !== "string") {
+    return false;
+  }
+  return candidate.hint === void 0 || typeof candidate.hint === "string";
+}
+
+// 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 { Command as Command3 } from "commander";
+import {
+  resolveDimensions,
+  validateVideoExportOptions
+} from "@bendyline/squisq-video";
+var VALID_QUALITIES = ["draft", "normal", "high"];
+var VALID_ORIENTATIONS = ["landscape", "portrait"];
+var VALID_CAPTIONS = ["off", "standard", "social"];
+var CLI_VIDEO_RENDER_LIMITS = Object.freeze({
+  maximumDimension: 3840,
+  maximumPixelsPerFrame: 8294400
+});
+async function runVideo(inputPath, opts, onProgress, dependencies = {}) {
+  throwIfAborted3(opts.signal);
+  const resolvedInput = resolve2(inputPath);
+  const fps = opts.fps ?? 30;
+  if (!Number.isFinite(fps) || fps < 1 || fps > 120) {
+    throw new Error("FPS must be a number between 1 and 120");
+  }
+  const quality = opts.quality ?? "normal";
+  if (!VALID_QUALITIES.includes(quality)) {
+    throw new Error(`Invalid quality "${quality}". Valid: ${VALID_QUALITIES.join(", ")}`);
+  }
+  const orientation = opts.orientation ?? "landscape";
+  if (!VALID_ORIENTATIONS.includes(orientation)) {
+    throw new Error(
+      `Invalid orientation "${orientation}". Valid: ${VALID_ORIENTATIONS.join(", ")}`
+    );
+  }
+  const captions = opts.captions ?? "off";
+  if (!VALID_CAPTIONS.includes(captions)) {
+    throw new Error(`Invalid captions "${captions}". Valid: ${VALID_CAPTIONS.join(", ")}`);
+  }
+  const captionStyle = captions === "off" ? void 0 : captions;
+  assertCliVideoRenderBudget({
+    fps,
+    quality,
+    orientation,
+    width: opts.width,
+    height: opts.height
+  });
+  const inputBasename = basename2(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`);
+  if (opts.allowOverwrite !== true && await lstat2(outputPath).catch(() => null)) {
+    throw new Error(
+      [
+        "Refusing to overwrite an existing file:",
+        `  ${outputPath}`,
+        "Pass --allow-overwrite to replace it, or use --output to write elsewhere."
+      ].join("\n")
+    );
+  }
+  throwIfAborted3(opts.signal);
+  await mkdir3(dirname2(outputPath), { recursive: true });
+  throwIfAborted3(opts.signal);
+  console.error(`Reading: ${resolvedInput}`);
+  const squisq = await import("@bendyline/squisq-cli/api");
+  throwIfAborted3(opts.signal);
+  const renderDocToMp4 = dependencies.renderDocToMp4 ?? squisq.renderDocToMp4;
+  const { readInput } = squisq;
+  const result = await readInput(resolvedInput, { signal: opts.signal });
+  throwIfAborted3(opts.signal);
+  const { container, doc } = result;
+  console.error(`Using normalized ${result.sourceFormat} document`);
+  console.error(
+    `Rendering: ${fps} fps, quality: ${quality}, orientation: ${orientation}, captions: ${captions}`
+  );
+  let latestProgress = 0;
+  const renderResult = await renderDocToMp4(doc, container, {
+    signal: opts.signal,
+    outputPath,
+    fps,
+    quality,
+    orientation,
+    width: opts.width,
+    height: opts.height,
+    captionStyle,
+    onProgress: (phase, percent) => {
+      throwIfAborted3(opts.signal);
+      const boundedPercent = Math.max(0, Math.min(100, percent));
+      if (boundedPercent < latestProgress) return;
+      latestProgress = boundedPercent;
+      if (onProgress) onProgress(phase, boundedPercent);
+      else process.stderr.write(`\r  ${phase}: ${boundedPercent}%  `);
+      throwIfAborted3(opts.signal);
+    }
+  });
+  throwIfAborted3(opts.signal);
+  process.stderr.write("\r" + " ".repeat(60) + "\r");
+  console.error(`  \u2713 ${outputPath}`);
+  console.error(
+    `  Duration: ${renderResult.duration.toFixed(1)}s, ${renderResult.frameCount} frames`
+  );
+  console.error("Done.");
+  return {
+    outputPath: renderResult.outputPath,
+    duration: renderResult.duration,
+    frameCount: renderResult.frameCount
+  };
+}
+function assertCliVideoRenderBudget(options) {
+  validateVideoExportOptions(options);
+  const { width, height } = resolveDimensions(options);
+  for (const [label, value] of [
+    ["width", width],
+    ["height", height]
+  ]) {
+    if (value % 2 !== 0) {
+      throw new RangeError(
+        `Video ${label} must be an even number of pixels (got ${value}); H.264 yuv420p cannot encode odd dimensions.`
+      );
+    }
+  }
+  const pixelsPerFrame = width * height;
+  const violations = [];
+  if (width > CLI_VIDEO_RENDER_LIMITS.maximumDimension || height > CLI_VIDEO_RENDER_LIMITS.maximumDimension) {
+    violations.push(
+      `${width}x${height} exceeds the ${CLI_VIDEO_RENDER_LIMITS.maximumDimension}-pixel dimension limit`
+    );
+  }
+  if (pixelsPerFrame > CLI_VIDEO_RENDER_LIMITS.maximumPixelsPerFrame) {
+    violations.push(
+      `${pixelsPerFrame} pixels per frame exceeds the ${CLI_VIDEO_RENDER_LIMITS.maximumPixelsPerFrame}-pixel limit`
+    );
+  }
+  if (violations.length > 0) {
+    throw new RangeError(`Video render exceeds the CLI resource budget: ${violations.join("; ")}.`);
+  }
+}
+function throwIfAborted3(signal) {
+  throwIfAborted(signal, "Video rendering was cancelled");
+}
+var videoCommand = new Command3("video").description("Render a squisq document to MP4 video").argument("<input>", "Path to a supported document, .zip/.dbk container, or folder").argument("[output]", "Output MP4 path (default: <input>.mp4)").option("-o, --output <path>", "Output MP4 path (default: <input>.mp4)").option("--fps <number>", "Frames per second", "30").option("--quality <level>", `Encoding quality: ${VALID_QUALITIES.join(", ")}`, "normal").option(
+  "--orientation <orient>",
+  `Video orientation: ${VALID_ORIENTATIONS.join(", ")}`,
+  "landscape"
+).option("--captions <style>", `Caption style: ${VALID_CAPTIONS.join(", ")}`, "off").option("--width <pixels>", "Override video width").option("--height <pixels>", "Override video height").option("--allow-overwrite", "replace an existing output MP4 instead of refusing the run").action(async (inputPath, outputArg, opts) => {
+  try {
+    await runVideo(inputPath, {
+      output: selectVideoOutput(outputArg, opts.output),
+      fps: parseNumberOption("--fps", opts.fps ?? "30"),
+      quality: opts.quality,
+      orientation: opts.orientation,
+      captions: opts.captions,
+      width: opts.width ? parseNumberOption("--width", opts.width) : void 0,
+      height: opts.height ? parseNumberOption("--height", opts.height) : void 0,
+      allowOverwrite: opts.allowOverwrite
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${message}`);
+    process.exitCode = 1;
+  }
+});
+function parseNumberOption(name, value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) throw new Error(`${name} must be a finite number`);
+  return parsed;
+}
+function selectVideoOutput(positional, option) {
+  if (positional !== void 0 && option !== void 0) {
+    throw new Error(
+      [
+        "Two output paths were requested:",
+        `  positional  ${positional}`,
+        `  --output    ${option}`,
+        "Pass the output path exactly once."
+      ].join("\n")
+    );
+  }
+  return option ?? positional;
+}
+
+// src/commands/parse.ts
+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";
+var DEFAULT_MAX_PARSE_INPUT_BYTES = 20 * 1024 * 1024;
+var DEFAULT_MAX_PARSE_OUTPUT_BYTES = 128 * 1024 * 1024;
+async function runParse(inputPath, options = {}) {
+  const resolvedInput = resolve3(inputPath);
+  const maxInputBytes = positiveLimit(
+    options.maxInputBytes,
+    DEFAULT_MAX_PARSE_INPUT_BYTES,
+    "parse input byte"
+  );
+  const maxOutputBytes = positiveLimit(
+    options.maxOutputBytes,
+    DEFAULT_MAX_PARSE_OUTPUT_BYTES,
+    "parse output byte"
+  );
+  const bytes = await readBoundedFile(resolvedInput, maxInputBytes);
+  const content = decodeUtf8Text2(bytes, { label: "Parse input", path: resolvedInput });
+  const { parseMarkdown: parseMarkdown2 } = await import("@bendyline/squisq/markdown");
+  const markdownDoc = parseMarkdown2(content);
+  const stats = {
+    headingCount: 0,
+    paragraphCount: 0,
+    blockCount: markdownDoc.children?.length ?? 0
+  };
+  if (markdownDoc.children) {
+    for (const node of markdownDoc.children) {
+      if (node.type === "heading") stats.headingCount += 1;
+      if (node.type === "paragraph") stats.paragraphCount += 1;
+    }
+  }
+  const serialized = `${JSON.stringify({ stats, document: markdownDoc }, null, 2)}
+`;
+  const outputBytes = Buffer.byteLength(serialized, "utf8");
+  if (outputBytes > maxOutputBytes) {
+    throw new Error(`Parse output exceeds the ${maxOutputBytes}-byte limit.`);
+  }
+  return serialized;
+}
+async function readBoundedFile(inputPath, maxBytes) {
+  let handle;
+  try {
+    handle = await open3(inputPath, "r");
+  } catch (error) {
+    if (isNodeErrorCode(error, ["ENOENT", "ENOTDIR"])) {
+      throw new Error(`Parse input not found: ${inputPath}`);
+    }
+    throw error;
+  }
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) throw new Error(`Parse input is not a file: ${inputPath}`);
+    if (info.size > maxBytes) throw new Error(`Parse input exceeds the ${maxBytes}-byte limit.`);
+    const chunks = [];
+    let totalBytes = 0;
+    while (true) {
+      const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1 - totalBytes));
+      const { bytesRead } = await handle.read(chunk, 0, chunk.byteLength, null);
+      if (bytesRead === 0) break;
+      totalBytes += bytesRead;
+      if (totalBytes > maxBytes) {
+        throw new Error(`Parse input exceeds the ${maxBytes}-byte limit.`);
+      }
+      chunks.push(chunk.subarray(0, bytesRead));
+    }
+    return Buffer.concat(chunks, totalBytes);
+  } finally {
+    await handle.close();
+  }
+}
+var parseCommand = new Command4("parse").description("Parse a markdown file and print its structure as JSON").argument("<input>", "Path to UTF-8 Markdown content").action(async (inputPath) => {
+  try {
+    process.stdout.write(await runParse(inputPath));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${message}`);
+    process.exitCode = 1;
+  }
+});
+
+// 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";
+var require2 = createRequire(import.meta.url);
+function getPackageVersion() {
+  const pkg = readPackageJson();
+  if (typeof pkg?.version === "string" && pkg.version.length > 0) {
+    return pkg.version;
+  }
+  return "0.0.0";
+}
+function readPackageJson() {
+  try {
+    const raw = readFileSync(new URL("../package.json", import.meta.url), "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+export {
+  applyTransformToMarkdown,
+  assertCliVideoRenderBudget,
+  getPackageVersion,
+  runBuild,
+  runConvert,
+  runParse,
+  runVideo
+};