@markdstage/markdstage 0.1.1

package/shared/scripts/markdown-blocks.mjs

@@ -0,0 +1,182 @@
+// Small utilities for replacing ```architecture fences in slide Markdown.
+//
+// Architecture diagram editing **rewrites the source DSL in place** rather than
+// maintaining a diff against rendered output. The new DSL produced by the editing
+// UI must therefore be restored precisely to the nth ```architecture fence in the source slide.
+//
+// Imported by both production `extension.mjs` and the test harness
+// (`test/harness/server.mjs`). Keep this free of runtime npm dependencies because
+// the extension is distributed as a ZIP.
+
+// Opening fence: three or more ` or ~ characters, as in marked; inspect only one info word.
+const FENCE_OPEN = /^([ \t]{0,3})(`{3,}|~{3,})[ \t]*([^\s`~]*)[ \t]*$/;
+
+/**
+ * Split Markdown into lines. Normalize CRLF / CR to LF for scanning.
+ */
+function toLines(markdown) {
+  return String(markdown).replace(/\r\n?/g, "\n").split("\n");
+}
+
+/**
+ * Split Markdown into body text plus the line's newline sequence. This preserves
+ * every byte of newline data outside the fence during replacement.
+ *
+ * Uses the same boundaries as toLines, so line numbers match findArchitectureBlocks results.
+ */
+function splitLinesWithEol(markdown) {
+  const text = String(markdown);
+  const out = [];
+  const re = /\r\n|\r|\n/g;
+  let last = 0;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    out.push({ text: text.slice(last, m.index), eol: m[0] });
+    last = re.lastIndex;
+  }
+  out.push({ text: text.slice(last), eol: "" });
+  return out;
+}
+
+/** Newline sequence for inserted lines; use the document's dominant sequence. */
+function dominantEol(lines) {
+  let crlf = 0;
+  let lf = 0;
+  for (const line of lines) {
+    if (line.eol === "\r\n") crlf += 1;
+    else if (line.eol === "\n") lf += 1;
+  }
+  return crlf > lf ? "\r\n" : "\n";
+}
+
+/**
+ * Find the closing fence line corresponding to an opening fence.
+ * Return the end of the document (lines.length) when absent, indicating an unclosed fence.
+ */
+function findFenceEnd(lines, start, marker) {
+  const close = new RegExp(`^[ \\t]{0,3}[${marker[0]}]{${marker.length},}[ \\t]*$`);
+  for (let i = start; i < lines.length; i += 1) {
+    if (close.test(lines[i])) return i;
+  }
+  return lines.length;
+}
+
+/**
+ * Scan ```architecture fences in Markdown.
+ * Each item contains { index, open, end, indent, body }.
+ * - index: zero-based sequence among architecture fences only (matching the
+ *   renderer's `code.language-architecture` occurrence order)
+ * - open / end: opening and closing fence line numbers (end is lines.length when unclosed)
+ * - body: raw text inside the fence
+ */
+export function findArchitectureBlocks(markdown) {
+  const lines = toLines(markdown);
+  const blocks = [];
+  let i = 0;
+  let seen = 0;
+  while (i < lines.length) {
+    const open = FENCE_OPEN.exec(lines[i]);
+    if (!open) {
+      i += 1;
+      continue;
+    }
+    const [, indent, marker, info] = open;
+    const end = findFenceEnd(lines, i + 1, marker);
+    if (info.toLowerCase() === "architecture") {
+      blocks.push({
+        index: seen,
+        open: i,
+        end,
+        indent,
+        body: lines.slice(i + 1, end).join("\n"),
+      });
+      seen += 1;
+    }
+    i = end + 1;
+  }
+  return blocks;
+}
+
+/**
+ * Return Markdown with the contents of the nth ```architecture fence replaced.
+ * Return null rather than throwing when the target is absent so the caller can return 404.
+ *
+ * Preserve the fence lines themselves (` ``` ` and ` ``` `) and replace only the
+ * contents. Apply the opening fence's indentation to the new body.
+ *
+ * Preserve all lines outside the fence, including newline sequences. This prevents
+ * saving CRLF Markdown from converting the entire file to LF and changing every line in git diff.
+ */
+export function replaceArchitectureBlock(markdown, blockIndex, source) {
+  const blocks = findArchitectureBlocks(markdown);
+  const target = blocks.find((b) => b.index === blockIndex);
+  if (!target) return null;
+  const lines = splitLinesWithEol(markdown);
+  // Match inserted newlines to the opening fence line. If that line has no newline,
+  // as with an unclosed fence at EOF, use the document's dominant sequence.
+  const eol = lines[target.open]?.eol || dominantEol(lines);
+  // Remove trailing blank lines before insertion so a final JSON newline does not add blank lines.
+  const body = String(source).replace(/\r\n?/g, "\n").replace(/\s+$/, "");
+  const inserted = body.length
+    ? body
+        .split("\n")
+        .map((line) => ({ text: target.indent && line ? target.indent + line : line, eol }))
+    : [];
+  const head = lines.slice(0, target.open + 1);
+  const tail = lines.slice(target.end);
+  // For an unclosed fence (empty tail), preserve the source's lack of a final newline.
+  if (!tail.length && inserted.length) inserted[inserted.length - 1].eol = "";
+  return [...head, ...inserted, ...tail].map((line) => line.text + line.eol).join("");
+}
+
+/**
+ * Convert a slide-local architecture block index to its index in the complete imported Markdown.
+ * Return null for appended slides absent from the source file, such as an automatically added back cover.
+ */
+export function importedArchitectureBlockIndex(slides, slideIndex, blockIndex) {
+  if (
+    !Array.isArray(slides) ||
+    !Number.isInteger(slideIndex) ||
+    !Number.isInteger(blockIndex) ||
+    slideIndex < 0 ||
+    slideIndex >= slides.length ||
+    blockIndex < 0
+  ) {
+    return null;
+  }
+  const localBlocks = findArchitectureBlocks(slides[slideIndex]);
+  if (blockIndex >= localBlocks.length) return null;
+  let globalIndex = blockIndex;
+  for (let i = 0; i < slideIndex; i += 1) {
+    globalIndex += findArchitectureBlocks(slides[i]).length;
+  }
+  return globalIndex;
+}
+
+/**
+ * Replace the target fence in imported Markdown only when it matches the current deck.
+ * Fail closed with source_changed if external edits moved or changed the target.
+ */
+export function replaceImportedArchitectureBlock(
+  markdown,
+  slides,
+  slideIndex,
+  blockIndex,
+  source,
+  expectedMarkdown = null,
+) {
+  if (typeof expectedMarkdown === "string" && markdown !== expectedMarkdown) {
+    return { ok: false, reason: "source_changed" };
+  }
+  const globalIndex = importedArchitectureBlockIndex(slides, slideIndex, blockIndex);
+  if (globalIndex === null) return { ok: false, reason: "block_not_found" };
+
+  const expected = findArchitectureBlocks(slides[slideIndex])[blockIndex];
+  const actual = findArchitectureBlocks(markdown)[globalIndex];
+  if (!actual) return { ok: false, reason: "source_changed" };
+  if (actual.body !== expected.body) return { ok: false, reason: "source_changed" };
+
+  const next = replaceArchitectureBlock(markdown, globalIndex, source);
+  if (next === null) return { ok: false, reason: "block_not_found" };
+  return { ok: true, markdown: next, globalIndex };
+}

package/shared/scripts/markdown-files.mjs

@@ -0,0 +1,63 @@
+// Utilities for finding Markdown files in the workspace.
+//
+// Used by the canvas 📂 button (Markdown import). These are pure functions with
+// no SDK or canvas-state dependencies so both extension.mjs and the test
+// harness can import them.
+
+import { readdir } from "node:fs/promises";
+import { extname, join, relative, resolve, sep } from "node:path";
+
+export const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown"]);
+export const MARKDOWN_SCAN_MAX_FILES = 500;
+export const MARKDOWN_SCAN_MAX_DEPTH = 6;
+export const MARKDOWN_MAX_BYTES = 2 * 1024 * 1024;
+
+// Directories that commonly accumulate generated output and rarely contain slide sources.
+// Dot-prefixed names such as .git are excluded as a group and are not listed here.
+const SKIP_DIRS = new Set(["node_modules", "vendor", "out", "dist", "build"]);
+
+export function isMarkdownPath(path) {
+  return MARKDOWN_EXTENSIONS.has(extname(path).toLowerCase());
+}
+
+/**
+ * Recursively collect Markdown files under rootDir and return `/`-separated relative paths.
+ * Limit the result count and depth so traversal cannot run indefinitely in a large repository.
+ *
+ * @returns {Promise<{ files: string[], truncated: boolean }>}
+ */
+export async function listMarkdownFiles(rootDir) {
+  const root = resolve(rootDir);
+  const files = [];
+  let truncated = false;
+
+  const walk = async (dir, depth) => {
+    if (truncated || depth > MARKDOWN_SCAN_MAX_DEPTH) return;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (_) {
+      return;
+    }
+    for (const entry of entries) {
+      if (truncated) return;
+      if (entry.name.startsWith(".")) continue;
+      const abs = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await walk(abs, depth + 1);
+        continue;
+      }
+      if (!entry.isFile() || !isMarkdownPath(entry.name)) continue;
+      if (files.length >= MARKDOWN_SCAN_MAX_FILES) {
+        truncated = true;
+        return;
+      }
+      files.push(relative(root, abs).split(sep).join("/"));
+    }
+  };
+
+  await walk(root, 0);
+  files.sort((a, b) => a.localeCompare(b));
+  return { files, truncated };
+}

package/shared/scripts/markdown-save-coordinator.mjs

@@ -0,0 +1,18 @@
+import { resolve } from "node:path";
+
+const queues = new Map();
+
+function keyFor(path) {
+  const resolved = resolve(path);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+export function serializeMarkdownSave(path, operation) {
+  const key = keyFor(path);
+  const previous = queues.get(key) ?? Promise.resolve();
+  const current = previous.catch(() => {}).then(operation);
+  queues.set(key, current);
+  return current.finally(() => {
+    if (queues.get(key) === current) queues.delete(key);
+  });
+}

package/shared/scripts/markdown-watcher.mjs

@@ -0,0 +1,80 @@
+import { watch } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+
+export const MARKDOWN_WATCH_DEBOUNCE_MS = 120;
+
+function sameFilename(left, right) {
+  if (process.platform === "win32") {
+    return left.toLocaleLowerCase("en-US") === right.toLocaleLowerCase("en-US");
+  }
+  return left === right;
+}
+
+export function createMarkdownWatcher({
+  path,
+  onChange,
+  onError,
+  debounceMs = MARKDOWN_WATCH_DEBOUNCE_MS,
+  watchFactory = watch,
+} = {}) {
+  if (typeof path !== "string" || !path) throw new TypeError("path is required");
+  if (typeof onChange !== "function") throw new TypeError("onChange is required");
+
+  const target = resolve(path);
+  const targetName = basename(target);
+  let timer = null;
+  let running = false;
+  let queued = false;
+  let closed = false;
+
+  const reportError = (error) => {
+    if (!closed && typeof onError === "function") onError(error);
+  };
+
+  const run = async () => {
+    timer = null;
+    if (closed) return;
+    if (running) {
+      queued = true;
+      return;
+    }
+    running = true;
+    try {
+      await onChange();
+    } catch (error) {
+      reportError(error);
+    } finally {
+      running = false;
+      if (queued && !closed) {
+        queued = false;
+        schedule();
+      }
+    }
+  };
+
+  const schedule = () => {
+    if (closed) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(run, Math.max(0, debounceMs));
+  };
+
+  const watcher = watchFactory(dirname(target), { persistent: false }, (_eventType, filename) => {
+    const changedName = filename == null ? "" : String(filename);
+    if (changedName && !sameFilename(changedName, targetName)) return;
+    schedule();
+  });
+  watcher.on("error", reportError);
+
+  return {
+    refresh: schedule,
+    close() {
+      if (closed) return;
+      closed = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      watcher.close();
+    },
+  };
+}

package/shared/scripts/theme-paths.mjs

@@ -0,0 +1,108 @@
+import { realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+
+import { isPathInside } from "./asset-paths.mjs";
+
+function fail(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  throw error;
+}
+
+function pathKey(path) {
+  const normalized = normalize(resolve(path));
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function themeRootCandidates(workspaceRoot, sourcePath = "") {
+  const workspace = resolve(workspaceRoot);
+  const roots = [];
+  const seen = new Set();
+  const add = (path) => {
+    const root = resolve(path);
+    const key = pathKey(root);
+    if (seen.has(key)) return;
+    seen.add(key);
+    roots.push(root);
+  };
+
+  if (typeof sourcePath === "string" && sourcePath.trim()) {
+    const source = resolve(workspace, sourcePath.trim());
+    if (!isPathInside(workspace, source)) {
+      fail("theme_source_outside_workspace", "The theme source must stay inside the workspace.");
+    }
+    add(dirname(source));
+  }
+  add(workspace);
+  return roots;
+}
+
+function safeJoin(rootDir, rel) {
+  if (typeof rel !== "string" || !rel.trim() || isAbsolute(rel) || rel.includes("\0")) {
+    return null;
+  }
+  const root = resolve(rootDir);
+  const candidate = normalize(join(root, rel.trim()));
+  return isPathInside(root, candidate) ? candidate : null;
+}
+
+export function themeFileCandidates(workspaceRoot, sourcePath, themePath) {
+  const roots = themeRootCandidates(workspaceRoot, sourcePath);
+  return roots.map((root) => {
+    const candidate = safeJoin(root, themePath);
+    if (!candidate) {
+      fail(
+        "invalid_theme_path",
+        "The theme path must be relative and stay inside a theme search root.",
+      );
+    }
+    return candidate;
+  });
+}
+
+export async function resolveThemeFile(workspaceRoot, sourcePath, themePath) {
+  const roots = themeRootCandidates(workspaceRoot, sourcePath);
+  const candidates = themeFileCandidates(workspaceRoot, sourcePath, themePath);
+  let canonicalWorkspace;
+  try {
+    canonicalWorkspace = await realpath(resolve(workspaceRoot));
+  } catch (_) {
+    fail("workspace_not_found", "The workspace root is unavailable.");
+  }
+
+  for (let index = 0; index < roots.length; index += 1) {
+    let canonicalRoot;
+    try {
+      canonicalRoot = await realpath(roots[index]);
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      fail("theme_root_unavailable", "A theme search root is unavailable.");
+    }
+    if (!isPathInside(canonicalWorkspace, canonicalRoot)) {
+      fail("theme_root_outside_workspace", "Theme search roots must resolve inside the workspace.");
+    }
+
+    let canonicalTheme;
+    try {
+      canonicalTheme = await realpath(candidates[index]);
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      fail("theme_file_unavailable", "The requested theme file is unavailable.");
+    }
+    if (
+      !isPathInside(canonicalWorkspace, canonicalTheme) ||
+      !isPathInside(canonicalRoot, canonicalTheme)
+    ) {
+      fail(
+        "theme_file_outside_workspace",
+        "The requested theme file must resolve inside its theme search root.",
+      );
+    }
+    const info = await stat(canonicalTheme);
+    if (!info.isFile()) {
+      fail("theme_file_unavailable", "The requested theme path is not a file.");
+    }
+    return canonicalTheme;
+  }
+  return null;
+}

package/shared/scripts/vendor-assets.mjs

@@ -0,0 +1,132 @@
+import { createHash } from "node:crypto";
+import {
+  readFile,
+  writeFile,
+  mkdir,
+} from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_CHUNK_SIZE = 512 * 1024;
+export const MANIFEST_NAME = "vendor-assets.lock.json";
+
+function sha256(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+function chunkName(sourceName, index) {
+  return `${sourceName}.part-${String(index + 1).padStart(4, "0")}`;
+}
+
+export async function readManifest(manifestPath) {
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  if (!manifest || manifest.schemaVersion !== 1 || !manifest.assets) {
+    throw new Error(`Invalid vendor asset manifest: ${manifestPath}`);
+  }
+  return manifest;
+}
+
+export async function reconstructAsset(vendorDir, assetName, manifestPath) {
+  const manifest = await readManifest(manifestPath);
+  const asset = manifest.assets[assetName];
+  if (!asset || !Array.isArray(asset.chunks) || asset.chunks.length === 0) {
+    throw new Error(`Missing manifest entry for vendor asset: ${assetName}`);
+  }
+  const chunks = [];
+  let total = 0;
+  for (const [index, entry] of asset.chunks.entries()) {
+    if (entry.index !== index + 1 || typeof entry.file !== "string") {
+      throw new Error(`Invalid chunk ordering for ${assetName}`);
+    }
+    const data = await readFile(join(vendorDir, entry.file));
+    if (data.length !== entry.size || sha256(data) !== entry.sha256) {
+      throw new Error(`Integrity check failed for ${entry.file}`);
+    }
+    if (data.length > manifest.chunkSize) {
+      throw new Error(`Chunk exceeds configured size: ${entry.file}`);
+    }
+    chunks.push(data);
+    total += data.length;
+  }
+  const result = Buffer.concat(chunks);
+  if (total !== asset.size || result.length !== asset.size || sha256(result) !== asset.sha256) {
+    throw new Error(`Integrity check failed for reconstructed ${assetName}`);
+  }
+  return result;
+}
+
+async function splitAsset(sourcePath, vendorDir, manifestPath, assetName, upstreamVersion) {
+  const source = await readFile(sourcePath);
+  const chunkSize = DEFAULT_CHUNK_SIZE;
+  const chunks = [];
+  await mkdir(vendorDir, { recursive: true });
+  for (let offset = 0, index = 0; offset < source.length; offset += chunkSize, index += 1) {
+    const data = source.subarray(offset, Math.min(offset + chunkSize, source.length));
+    const file = chunkName(assetName, index);
+    await writeFile(join(vendorDir, file), data);
+    chunks.push({
+      index: index + 1,
+      file,
+      size: data.length,
+      sha256: sha256(data),
+    });
+  }
+  const manifest = {
+    schemaVersion: 1,
+    chunkSize,
+    assets: {
+      [assetName]: {
+        source: assetName,
+        size: source.length,
+        sha256: sha256(source),
+        upstream: {
+          name: "mermaid",
+          version: upstreamVersion,
+          source: "https://www.npmjs.com/package/mermaid",
+        },
+        chunks,
+      },
+    },
+  };
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+async function verifyManifest(vendorDir, manifestPath) {
+  const manifest = await readManifest(manifestPath);
+  for (const assetName of Object.keys(manifest.assets)) {
+    await reconstructAsset(vendorDir, assetName, manifestPath);
+  }
+  return manifest;
+}
+
+function usage() {
+  console.error(
+    "Usage: node vendor-assets.mjs split <source> <vendor-dir> <manifest> [upstream-version]\n" +
+      "       node vendor-assets.mjs verify <vendor-dir> <manifest>",
+  );
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const [, , command, ...args] = process.argv;
+  try {
+    if (command === "split" && args.length >= 3) {
+      await splitAsset(
+        resolve(args[0]),
+        resolve(args[1]),
+        resolve(args[2]),
+        "mermaid.min.js",
+        args[3] || "unknown",
+      );
+      console.log(`Split mermaid.min.js into ${DEFAULT_CHUNK_SIZE}-byte chunks.`);
+    } else if (command === "verify" && args.length === 2) {
+      const manifest = await verifyManifest(resolve(args[0]), resolve(args[1]));
+      console.log(`Verified ${Object.keys(manifest.assets).length} vendor asset(s).`);
+    } else {
+      usage();
+      process.exitCode = 2;
+    }
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/shared/scripts/workspace-root.mjs

@@ -0,0 +1,32 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+export function resolveWorkspaceRoot(workingDirectory, fallbackRoot) {
+  const fallback = resolve(fallbackRoot);
+  if (!workingDirectory) return fallback;
+
+  const workspace = resolve(workingDirectory);
+  if (!existsSync(workspace)) return fallback;
+
+  try {
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: workspace,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (root) return resolve(root);
+  } catch (_) {
+    /* not a Git repository / Git unavailable — inspect parent markers */
+  }
+
+  let directory = workspace;
+  for (;;) {
+    if (existsSync(join(directory, ".git"))) return directory;
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+
+  return workspace;
+}

package/shared/vendor/highlight.LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2006, Ivan Sagalaev.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.