chore: import upstream snapshot with attribution

scripts/doc-tests/__tests__/extract.test.ts

@@ -0,0 +1,229 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { parseMeta, extractFromMdx, writeExtractedBlocks } from "../extract";
+
+// ---------------------------------------------------------------------------
+// parseMeta
+// ---------------------------------------------------------------------------
+
+describe("parseMeta", () => {
+  it("extracts key=value pairs from meta string", () => {
+    const meta = 'title="main.py" doctest="server"';
+    expect(parseMeta(meta)).toEqual({ title: "main.py", doctest: "server" });
+  });
+
+  it("handles single quotes", () => {
+    const meta = "title='server.ts' doctest='component'";
+    expect(parseMeta(meta)).toEqual({
+      title: "server.ts",
+      doctest: "component",
+    });
+  });
+
+  it("returns empty object for empty meta", () => {
+    expect(parseMeta("")).toEqual({});
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extractFromMdx
+// ---------------------------------------------------------------------------
+
+describe("extractFromMdx", () => {
+  it("extracts a doctest='server' block from simple MDX", () => {
+    const mdx = `
+# My Page
+
+Some text.
+
+\`\`\`python title="main.py" doctest="server"
+import os
+print("hello")
+\`\`\`
+`;
+
+    const blocks = extractFromMdx(
+      mdx,
+      "/showcase/shell-docs/src/content/test.mdx",
+    );
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0].lang).toBe("python");
+    expect(blocks[0].title).toBe("main.py");
+    expect(blocks[0].doctest).toBe("server");
+    expect(blocks[0].code).toContain('print("hello")');
+  });
+
+  it("extracts multiple blocks from one file", () => {
+    const mdx = `
+\`\`\`python title="a.py" doctest="script"
+print("a")
+\`\`\`
+
+\`\`\`typescript title="b.ts" doctest="component"
+const x = 1;
+\`\`\`
+`;
+
+    const blocks = extractFromMdx(
+      mdx,
+      "/showcase/shell-docs/src/content/multi.mdx",
+    );
+    expect(blocks).toHaveLength(2);
+    expect(blocks[0].doctest).toBe("script");
+    expect(blocks[1].doctest).toBe("component");
+  });
+
+  it("ignores blocks without doctest attribute", () => {
+    const mdx = `
+\`\`\`python title="main.py"
+print("no doctest")
+\`\`\`
+
+\`\`\`bash
+echo "also no doctest"
+\`\`\`
+
+\`\`\`python title="tested.py" doctest="script"
+print("has doctest")
+\`\`\`
+`;
+
+    const blocks = extractFromMdx(
+      mdx,
+      "/showcase/shell-docs/src/content/mixed.mdx",
+    );
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0].title).toBe("tested.py");
+  });
+
+  it("handles indented blocks inside JSX (Tab component)", () => {
+    const mdx = `
+import { Tab, Tabs } from "fumadocs-ui/components/tabs";
+
+<Tabs items={["Python", "TypeScript"]}>
+  <Tab value="Python">
+    \`\`\`python title="main.py" doctest="server"
+    import fastapi
+    app = fastapi.FastAPI()
+    \`\`\`
+  </Tab>
+</Tabs>
+`;
+
+    const blocks = extractFromMdx(
+      mdx,
+      "/showcase/shell-docs/src/content/tabbed.mdx",
+    );
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0].lang).toBe("python");
+    expect(blocks[0].doctest).toBe("server");
+    expect(blocks[0].code).toContain("fastapi");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// writeExtractedBlocks
+// ---------------------------------------------------------------------------
+
+describe("writeExtractedBlocks", () => {
+  let tmpDir: string;
+  let outputDir: string;
+  let docsDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "doctest-"));
+    outputDir = path.join(tmpDir, "output");
+    docsDir = path.join(tmpDir, "docs");
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.mkdirSync(docsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it("groups blocks with the same title into one file", () => {
+    const blocks = [
+      {
+        lang: "python",
+        title: "main.py",
+        doctest: "server",
+        code: "# part 1",
+        line: 10,
+        sourceFile: path.join(docsDir, "guide.mdx"),
+      },
+      {
+        lang: "python",
+        title: "main.py",
+        doctest: "server",
+        code: "# part 2",
+        line: 30,
+        sourceFile: path.join(docsDir, "guide.mdx"),
+      },
+    ];
+
+    const manifest = writeExtractedBlocks(blocks, outputDir, docsDir);
+
+    expect(manifest).toHaveLength(1);
+    expect(manifest[0].file).toBe("guide/main.py");
+
+    const written = fs.readFileSync(
+      path.join(outputDir, "guide", "main.py"),
+      "utf-8",
+    );
+    expect(written).toContain("# part 1");
+    expect(written).toContain("# part 2");
+  });
+
+  it("writes correct manifest.json structure", () => {
+    const blocks = [
+      {
+        lang: "python",
+        title: "server.py",
+        doctest: "server",
+        code: "print('hello')",
+        line: 5,
+        sourceFile: path.join(docsDir, "integrations", "test.mdx"),
+      },
+    ];
+
+    // Create the nested dir so the relative path works
+    fs.mkdirSync(path.join(docsDir, "integrations"), { recursive: true });
+
+    const manifest = writeExtractedBlocks(blocks, outputDir, docsDir);
+
+    expect(manifest).toHaveLength(1);
+    expect(manifest[0].lang).toBe("python");
+    expect(manifest[0].category).toBe("server");
+    expect(manifest[0].source).toContain(":5");
+    expect(manifest[0].id).toContain("integrations-test");
+  });
+
+  it("copies doctest.json sidecar when present", () => {
+    const sidecar = { python: { deps: ["flask"] } };
+    fs.writeFileSync(
+      path.join(docsDir, "doctest.json"),
+      JSON.stringify(sidecar),
+    );
+
+    const blocks = [
+      {
+        lang: "python",
+        title: "app.py",
+        doctest: "server",
+        code: "from flask import Flask",
+        line: 1,
+        sourceFile: path.join(docsDir, "page.mdx"),
+      },
+    ];
+
+    writeExtractedBlocks(blocks, outputDir, docsDir);
+
+    const copied = JSON.parse(
+      fs.readFileSync(path.join(outputDir, "page", "doctest.json"), "utf-8"),
+    );
+    expect(copied.python.deps).toContain("flask");
+  });
+});

scripts/doc-tests/extract.ts

@@ -0,0 +1,336 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkMdx from "remark-mdx";
+import { visit } from "unist-util-visit";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface CodeBlock {
+  lang: string;
+  title: string;
+  doctest: string;
+  code: string;
+  line: number;
+  sourceFile: string;
+}
+
+interface ManifestEntry {
+  id: string;
+  file: string;
+  lang: string;
+  category: string;
+  source: string;
+}
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const DOCS_DIR = path.resolve(
+  __dirname,
+  "../../showcase/shell-docs/src/content",
+);
+const OUTPUT_DIR = path.resolve(__dirname, "../../.doctest-output");
+
+// ---------------------------------------------------------------------------
+// AST Extraction
+// ---------------------------------------------------------------------------
+
+const parser = unified().use(remarkParse).use(remarkMdx);
+
+/**
+ * Strip common leading whitespace from all lines of a code block.
+ * Handles indented code blocks inside JSX (Tabs, If, etc.) that
+ * preserve the JSX indentation in the extracted code.
+ */
+function stripCommonIndent(code: string): string {
+  const lines = code.split("\n");
+  const nonEmptyLines = lines.filter((l) => l.trim().length > 0);
+  if (nonEmptyLines.length === 0) return code;
+
+  const minIndent = Math.min(
+    ...nonEmptyLines.map((l) => l.match(/^(\s*)/)![1].length),
+  );
+  if (minIndent === 0) return code;
+
+  return lines.map((l) => l.slice(minIndent)).join("\n");
+}
+
+/**
+ * Parse the meta string from a code fence to extract key-value attributes.
+ *
+ * Handles formats like:
+ *   python title="main.py" doctest="server"
+ *   typescript title="server.ts" doctest="component"
+ */
+export function parseMeta(meta: string): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  // Match key="value" or key='value'
+  const regex = /(\w+)=["']([^"']+)["']/g;
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(meta)) !== null) {
+    attrs[match[1]] = match[2];
+  }
+  return attrs;
+}
+
+/**
+ * Extract all code blocks with a doctest attribute from an MDX file.
+ */
+export function extractFromMdx(
+  content: string,
+  sourceFile: string,
+): CodeBlock[] {
+  const blocks: CodeBlock[] = [];
+
+  let tree: ReturnType<typeof parser.parse>;
+  try {
+    tree = parser.parse(content);
+  } catch {
+    // Some MDX files have JSX constructs that trip the parser.
+    // Fall back to a regex-based extraction for resilience.
+    return extractFromMdxFallback(content, sourceFile);
+  }
+
+  visit(tree, "code", (node: any) => {
+    const lang = node.lang || "";
+    const meta = node.meta || "";
+    const attrs = parseMeta(meta);
+
+    if (!attrs.doctest) return;
+
+    const line =
+      node.position && node.position.start ? node.position.start.line : 0;
+
+    blocks.push({
+      lang,
+      title: attrs.title || `snippet.${langToExt(lang)}`,
+      doctest: attrs.doctest,
+      code: stripCommonIndent(node.value),
+      line,
+      sourceFile,
+    });
+  });
+
+  return blocks;
+}
+
+/**
+ * Regex-based fallback for MDX files that trip the remark-mdx parser.
+ * Only extracts code blocks with doctest attributes — less precise on
+ * position, but sufficient for our purposes.
+ */
+function extractFromMdxFallback(
+  content: string,
+  sourceFile: string,
+): CodeBlock[] {
+  const blocks: CodeBlock[] = [];
+  const lines = content.split("\n");
+
+  let inBlock = false;
+  let blockLang = "";
+  let blockMeta = "";
+  let blockLines: string[] = [];
+  let blockStart = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trimStart();
+
+    if (!inBlock && /^```(\w+)(.*)$/.test(trimmed)) {
+      const match = trimmed.match(/^```(\w+)(.*)$/);
+      if (match) {
+        blockLang = match[1];
+        blockMeta = match[2];
+        blockLines = [];
+        blockStart = i + 1;
+        inBlock = true;
+      }
+    } else if (inBlock && /^```\s*$/.test(trimmed)) {
+      const attrs = parseMeta(blockMeta);
+      if (attrs.doctest) {
+        blocks.push({
+          lang: blockLang,
+          title: attrs.title || `snippet.${langToExt(blockLang)}`,
+          doctest: attrs.doctest,
+          code: stripCommonIndent(blockLines.join("\n")),
+          line: blockStart,
+          sourceFile,
+        });
+      }
+      inBlock = false;
+    } else if (inBlock) {
+      blockLines.push(lines[i]);
+    }
+  }
+
+  return blocks;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function langToExt(lang: string): string {
+  switch (lang) {
+    case "python":
+      return "py";
+    case "typescript":
+    case "tsx":
+      return "ts";
+    case "javascript":
+    case "jsx":
+      return "js";
+    default:
+      return lang || "txt";
+  }
+}
+
+function slugify(filePath: string): string {
+  return filePath
+    .replace(/\.mdx$/, "")
+    .replace(/[/\\]/g, "-")
+    .replace(/[^a-zA-Z0-9-]/g, "");
+}
+
+/**
+ * Walk a directory tree and return all .mdx files.
+ */
+function findMdxFiles(dir: string): string[] {
+  const results: string[] = [];
+
+  function walk(current: string) {
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules")
+          continue;
+        walk(full);
+      } else if (entry.name.endsWith(".mdx")) {
+        results.push(full);
+      }
+    }
+  }
+
+  walk(dir);
+  return results.sort();
+}
+
+// ---------------------------------------------------------------------------
+// Output generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Group extracted blocks by page slug and title, then write to output dir.
+ * Blocks sharing the same title within a page are concatenated into one file.
+ */
+export function writeExtractedBlocks(
+  blocks: CodeBlock[],
+  outputDir: string,
+  docsDir: string,
+): ManifestEntry[] {
+  const manifest: ManifestEntry[] = [];
+
+  // Group by (page slug, title)
+  const grouped = new Map<string, CodeBlock[]>();
+  for (const block of blocks) {
+    const rel = path.relative(docsDir, block.sourceFile);
+    const slug = slugify(rel);
+    const key = `${slug}/${block.title}`;
+    const existing = grouped.get(key) || [];
+    existing.push(block);
+    grouped.set(key, existing);
+  }
+
+  for (const [key, groupBlocks] of grouped) {
+    const slug = key.split("/")[0];
+    const title = groupBlocks[0].title;
+    const dir = path.join(outputDir, slug);
+
+    fs.mkdirSync(dir, { recursive: true });
+
+    // Concatenate code from all blocks sharing this title
+    const code = groupBlocks.map((b) => b.code).join("\n\n");
+    const filePath = path.join(dir, title);
+    fs.writeFileSync(filePath, code, "utf-8");
+
+    // Copy doctest.json sidecar if it exists
+    const sidecarPath = path.join(
+      path.dirname(groupBlocks[0].sourceFile),
+      "doctest.json",
+    );
+    const destSidecar = path.join(dir, "doctest.json");
+    if (fs.existsSync(sidecarPath) && !fs.existsSync(destSidecar)) {
+      fs.copyFileSync(sidecarPath, destSidecar);
+    }
+
+    const firstBlock = groupBlocks[0];
+    const relSource = path.relative(
+      path.resolve(docsDir, ".."),
+      firstBlock.sourceFile,
+    );
+
+    const id = `${slug}-${title.replace(/[^a-zA-Z0-9]/g, "-")}`;
+
+    manifest.push({
+      id,
+      file: `${slug}/${title}`,
+      lang: firstBlock.lang,
+      category: firstBlock.doctest,
+      source: `${relSource}:${firstBlock.line}`,
+    });
+  }
+
+  return manifest;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+export function extract(
+  docsDir: string = DOCS_DIR,
+  outputDir: string = OUTPUT_DIR,
+): ManifestEntry[] {
+  // Clean output dir
+  if (fs.existsSync(outputDir)) {
+    fs.rmSync(outputDir, { recursive: true });
+  }
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const files = findMdxFiles(docsDir);
+  const allBlocks: CodeBlock[] = [];
+
+  for (const file of files) {
+    const content = fs.readFileSync(file, "utf-8");
+    const blocks = extractFromMdx(content, file);
+    allBlocks.push(...blocks);
+  }
+
+  const manifest = writeExtractedBlocks(allBlocks, outputDir, docsDir);
+
+  // Write manifest
+  const manifestPath = path.join(outputDir, "manifest.json");
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+
+  console.log(`Extracted ${manifest.length} doctest snippet(s):`);
+  for (const entry of manifest) {
+    console.log(`  ${entry.id} [${entry.category}] ${entry.source}`);
+  }
+
+  return manifest;
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+const isDirectRun = typeof require !== "undefined" && require.main === module;
+
+if (isDirectRun) {
+  extract();
+}

scripts/doc-tests/fixtures/default.json

@@ -0,0 +1,10 @@
+{
+  "fixtures": [
+    {
+      "match": {},
+      "response": {
+        "content": "Hello! I'm an AI assistant."
+      }
+    }
+  ]
+}

scripts/doc-tests/run.ts

@@ -0,0 +1,486 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execSync, spawn } from "node:child_process";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface ManifestEntry {
+  id: string;
+  file: string;
+  lang: string;
+  category: string;
+  source: string;
+}
+
+interface DoctestConfig {
+  python?: { deps: string[] };
+  typescript?: { deps: string[] };
+  node?: { deps: string[] };
+}
+
+interface Result {
+  id: string;
+  category: string;
+  status: "pass" | "fail";
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const OUTPUT_DIR = path.resolve(__dirname, "../../.doctest-output");
+const MANIFEST_PATH = path.join(OUTPUT_DIR, "manifest.json");
+
+const DEFAULT_ENV: Record<string, string> = {
+  OPENAI_API_KEY: "test-key",
+  OPENAI_BASE_URL: "http://localhost:4010",
+};
+
+const SERVER_TIMEOUT_MS = 30_000;
+const SERVER_POLL_MS = 500;
+const SCRIPT_TIMEOUT_MS = 30_000;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function validateDepName(dep: string): string {
+  if (!/^[@\w][\w./-]*(?:@[\w.^~>=<*-]+)?$/.test(dep)) {
+    throw new Error(`Invalid dependency name: ${dep}`);
+  }
+  return dep;
+}
+
+function loadDoctestConfig(snippetDir: string): DoctestConfig {
+  const configPath = path.join(snippetDir, "doctest.json");
+  if (fs.existsSync(configPath)) {
+    return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+  }
+  return {};
+}
+
+function mergeEnv(extra?: Record<string, string>): Record<string, string> {
+  return { ...process.env, ...DEFAULT_ENV, ...extra } as Record<string, string>;
+}
+
+async function waitForPort(
+  port: number,
+  timeoutMs: number,
+  pollMs: number,
+  shouldContinue: () => boolean = () => true,
+): Promise<boolean> {
+  const start = Date.now();
+  while (shouldContinue() && Date.now() - start < timeoutMs) {
+    try {
+      const resp = await fetch(`http://localhost:${port}/`).catch(() => null);
+      if (resp) return true;
+    } catch {
+      // Server not ready yet
+    }
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+  return false;
+}
+
+function collectProcessOutput(proc: ReturnType<typeof spawn>): {
+  isRunning: () => boolean;
+  output: () => string;
+} {
+  let exited = false;
+  let output = "";
+
+  proc.stdout?.on("data", (chunk) => {
+    output += chunk.toString();
+  });
+  proc.stderr?.on("data", (chunk) => {
+    output += chunk.toString();
+  });
+  proc.on("exit", (code, signal) => {
+    exited = true;
+    output += `\n[process exited with ${signal ? `signal ${signal}` : `code ${code}`}]`;
+  });
+
+  return {
+    isRunning: () => !exited,
+    output: () => output.trim(),
+  };
+}
+
+function serverStartError(
+  port: number,
+  proc: ReturnType<typeof collectProcessOutput>,
+): string {
+  const output = proc.output();
+  if (output) {
+    return `Server did not bind to port ${port}. Process output:\n${output}`;
+  }
+  return `Server did not bind to port ${port} within ${SERVER_TIMEOUT_MS}ms`;
+}
+
+function detectPort(code: string): number {
+  // Look for port=NNNN or PORT=NNNN or --port NNNN
+  const match = code.match(/\bport[=\s:]+(\d{4,5})/i);
+  return match ? parseInt(match[1], 10) : 8000;
+}
+
+// ---------------------------------------------------------------------------
+// Runners
+// ---------------------------------------------------------------------------
+
+async function runPythonServer(
+  snippetDir: string,
+  entryFile: string,
+  config: DoctestConfig,
+): Promise<Result> {
+  const id = path.basename(snippetDir);
+  const venvDir = path.join(snippetDir, ".venv");
+
+  try {
+    // Create virtualenv
+    execSync(`python3 -m venv ${venvDir}`, { cwd: snippetDir, stdio: "pipe" });
+
+    const pip = path.join(venvDir, "bin", "pip");
+    const python = path.join(venvDir, "bin", "python");
+
+    // Install deps
+    const deps = config.python?.deps || [];
+    if (deps.length > 0) {
+      const safeDeps = deps.map(validateDepName);
+      execSync(`${pip} install ${safeDeps.join(" ")}`, {
+        cwd: snippetDir,
+        stdio: "pipe",
+        timeout: 120_000,
+      });
+    }
+
+    const code = fs.readFileSync(path.join(snippetDir, entryFile), "utf-8");
+    const port = detectPort(code);
+
+    // Start server
+    const proc = spawn(python, [entryFile], {
+      cwd: snippetDir,
+      env: mergeEnv(),
+      stdio: "pipe",
+    });
+    const serverProcess = collectProcessOutput(proc);
+
+    try {
+      const ready = await waitForPort(
+        port,
+        SERVER_TIMEOUT_MS,
+        SERVER_POLL_MS,
+        serverProcess.isRunning,
+      );
+
+      if (!ready) {
+        return {
+          id,
+          category: "server",
+          status: "fail",
+          error: serverStartError(port, serverProcess),
+        };
+      }
+
+      return { id, category: "server", status: "pass" };
+    } finally {
+      try {
+        proc.kill("SIGTERM");
+      } catch {}
+    }
+  } catch (e: any) {
+    return {
+      id,
+      category: "server",
+      status: "fail",
+      error: e.message || String(e),
+    };
+  }
+}
+
+async function runTypeScriptServer(
+  snippetDir: string,
+  entryFile: string,
+  config: DoctestConfig,
+): Promise<Result> {
+  const id = path.basename(snippetDir);
+
+  try {
+    // Init and install deps
+    execSync("npm init -y", { cwd: snippetDir, stdio: "pipe" });
+
+    const deps = config.typescript?.deps || config.node?.deps || [];
+    if (deps.length > 0) {
+      const safeDeps = deps.map(validateDepName);
+      execSync(`npm install ${safeDeps.join(" ")}`, {
+        cwd: snippetDir,
+        stdio: "pipe",
+        timeout: 120_000,
+      });
+    }
+
+    const code = fs.readFileSync(path.join(snippetDir, entryFile), "utf-8");
+    const port = detectPort(code);
+
+    // Determine runner
+    const runner = entryFile.endsWith(".ts") ? "npx tsx" : "node";
+    const proc = spawn(
+      runner.split(" ")[0],
+      [...runner.split(" ").slice(1), entryFile],
+      {
+        cwd: snippetDir,
+        env: mergeEnv(),
+        stdio: "pipe",
+      },
+    );
+    const serverProcess = collectProcessOutput(proc);
+
+    try {
+      const ready = await waitForPort(
+        port,
+        SERVER_TIMEOUT_MS,
+        SERVER_POLL_MS,
+        serverProcess.isRunning,
+      );
+
+      if (!ready) {
+        return {
+          id,
+          category: "server",
+          status: "fail",
+          error: serverStartError(port, serverProcess),
+        };
+      }
+
+      return { id, category: "server", status: "pass" };
+    } finally {
+      try {
+        proc.kill("SIGTERM");
+      } catch {}
+    }
+  } catch (e: any) {
+    return {
+      id,
+      category: "server",
+      status: "fail",
+      error: e.message || String(e),
+    };
+  }
+}
+
+async function runScript(
+  snippetDir: string,
+  entryFile: string,
+  lang: string,
+  config: DoctestConfig,
+): Promise<Result> {
+  const id = path.basename(snippetDir);
+
+  try {
+    if (lang === "python") {
+      const venvDir = path.join(snippetDir, ".venv");
+      execSync(`python3 -m venv ${venvDir}`, {
+        cwd: snippetDir,
+        stdio: "pipe",
+      });
+      const pip = path.join(venvDir, "bin", "pip");
+      const python = path.join(venvDir, "bin", "python");
+
+      const deps = config.python?.deps || [];
+      if (deps.length > 0) {
+        const safeDeps = deps.map(validateDepName);
+        execSync(`${pip} install ${safeDeps.join(" ")}`, {
+          cwd: snippetDir,
+          stdio: "pipe",
+          timeout: 120_000,
+        });
+      }
+
+      execSync(`${python} ${entryFile}`, {
+        cwd: snippetDir,
+        env: mergeEnv(),
+        stdio: "pipe",
+        timeout: SCRIPT_TIMEOUT_MS,
+      });
+    } else {
+      execSync("npm init -y", { cwd: snippetDir, stdio: "pipe" });
+      const deps = config.typescript?.deps || config.node?.deps || [];
+      if (deps.length > 0) {
+        const safeDeps = deps.map(validateDepName);
+        execSync(`npm install ${safeDeps.join(" ")}`, {
+          cwd: snippetDir,
+          stdio: "pipe",
+          timeout: 120_000,
+        });
+      }
+
+      const runner = entryFile.endsWith(".ts") ? "npx tsx" : "node";
+      execSync(`${runner} ${entryFile}`, {
+        cwd: snippetDir,
+        env: mergeEnv(),
+        stdio: "pipe",
+        timeout: SCRIPT_TIMEOUT_MS,
+      });
+    }
+
+    return { id, category: "script", status: "pass" };
+  } catch (e: any) {
+    return {
+      id,
+      category: "script",
+      status: "fail",
+      error: e.message || String(e),
+    };
+  }
+}
+
+async function runComponent(
+  snippetDir: string,
+  entryFile: string,
+  config: DoctestConfig,
+): Promise<Result> {
+  const id = path.basename(snippetDir);
+
+  try {
+    execSync("npm init -y", { cwd: snippetDir, stdio: "pipe" });
+
+    const deps = config.typescript?.deps || [];
+    const baseDeps = ["typescript", "@types/react", "@types/node"];
+    const allDeps = [...new Set([...baseDeps, ...deps])];
+    const safeAllDeps = allDeps.map(validateDepName);
+
+    execSync(`npm install ${safeAllDeps.join(" ")}`, {
+      cwd: snippetDir,
+      stdio: "pipe",
+      timeout: 120_000,
+    });
+
+    // Write minimal tsconfig if none exists
+    const tsconfigPath = path.join(snippetDir, "tsconfig.json");
+    if (!fs.existsSync(tsconfigPath)) {
+      fs.writeFileSync(
+        tsconfigPath,
+        JSON.stringify(
+          {
+            compilerOptions: {
+              target: "ES2020",
+              module: "ESNext",
+              moduleResolution: "bundler",
+              jsx: "react-jsx",
+              strict: true,
+              noEmit: true,
+              esModuleInterop: true,
+              skipLibCheck: true,
+            },
+            include: [entryFile],
+          },
+          null,
+          2,
+        ),
+        "utf-8",
+      );
+    }
+
+    execSync("npx tsc --noEmit", {
+      cwd: snippetDir,
+      stdio: "pipe",
+      timeout: SCRIPT_TIMEOUT_MS,
+    });
+
+    return { id, category: "component", status: "pass" };
+  } catch (e: any) {
+    return {
+      id,
+      category: "component",
+      status: "fail",
+      error: e.message || String(e),
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  if (!fs.existsSync(MANIFEST_PATH)) {
+    console.error(
+      `Manifest not found at ${MANIFEST_PATH}. Run extract.ts first.`,
+    );
+    process.exit(1);
+  }
+
+  const manifest: ManifestEntry[] = JSON.parse(
+    fs.readFileSync(MANIFEST_PATH, "utf-8"),
+  );
+
+  if (manifest.length === 0) {
+    console.log("No doctest snippets found in manifest.");
+    process.exit(0);
+  }
+
+  console.log(`Running ${manifest.length} doctest snippet(s)...\n`);
+
+  const results: Result[] = [];
+
+  for (const entry of manifest) {
+    const snippetDir = path.join(OUTPUT_DIR, path.dirname(entry.file));
+    const entryFile = path.basename(entry.file);
+    const config = loadDoctestConfig(snippetDir);
+
+    console.log(`  Running: ${entry.id} [${entry.category}/${entry.lang}]`);
+
+    let result: Result;
+
+    if (entry.category === "server") {
+      if (entry.lang === "python") {
+        result = await runPythonServer(snippetDir, entryFile, config);
+      } else {
+        result = await runTypeScriptServer(snippetDir, entryFile, config);
+      }
+    } else if (entry.category === "script") {
+      result = await runScript(snippetDir, entryFile, entry.lang, config);
+    } else if (entry.category === "component") {
+      result = await runComponent(snippetDir, entryFile, config);
+    } else {
+      result = {
+        id: entry.id,
+        category: entry.category,
+        status: "fail",
+        error: `Unknown category: ${entry.category}`,
+      };
+    }
+
+    results.push(result);
+
+    const icon = result.status === "pass" ? "PASS" : "FAIL";
+    console.log(
+      `  ${icon}: ${entry.id}${result.error ? ` — ${result.error}` : ""}\n`,
+    );
+  }
+
+  // Summary
+  const passed = results.filter((r) => r.status === "pass").length;
+  const failed = results.filter((r) => r.status === "fail").length;
+
+  console.log("─".repeat(60));
+  console.log(
+    `Results: ${passed} passed, ${failed} failed, ${results.length} total`,
+  );
+  console.log("─".repeat(60));
+
+  if (failed > 0) {
+    console.log("\nFailed snippets:");
+    for (const r of results.filter((r) => r.status === "fail")) {
+      console.log(`  ${r.id}: ${r.error}`);
+    }
+    process.exit(1);
+  }
+}
+
+main().catch((e) => {
+  console.error("Unexpected error:", e);
+  process.exit(1);
+});