From 09e9b9e706d14fa3a32be052cb819bf810342042 Mon Sep 17 00:00:00 2001
From: Josh Ribakoff <josh.ribakoff@gmail.com>
Date: Mon, 15 Dec 2025 18:37:14 -0800
Subject: [PATCH 1/5] Add @sailkit/scribe package for testing code fences
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Extracts TypeScript/JavaScript code blocks from markdown
- Executes code and checks exit codes for pass/fail
- Parallel execution with configurable concurrency
- TTY detection for interactive vs CI output
- Vitest-style progress display with spinners

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 packages/scribe/README.md     |  30 +++++
 packages/scribe/package.json  |  28 +++++
 packages/scribe/src/cli.ts    | 220 ++++++++++++++++++++++++++++++++++
 packages/scribe/src/index.ts  |  10 ++
 packages/scribe/src/parser.ts |  40 +++++++
 packages/scribe/src/runner.ts |  87 ++++++++++++++
 packages/scribe/tsconfig.json |  14 +++
 7 files changed, 429 insertions(+)
 create mode 100644 packages/scribe/README.md
 create mode 100644 packages/scribe/package.json
 create mode 100644 packages/scribe/src/cli.ts
 create mode 100644 packages/scribe/src/index.ts
 create mode 100644 packages/scribe/src/parser.ts
 create mode 100644 packages/scribe/src/runner.ts
 create mode 100644 packages/scribe/tsconfig.json

diff --git a/packages/scribe/README.md b/packages/scribe/README.md
new file mode 100644
index 0000000..7e09674
--- /dev/null
+++ b/packages/scribe/README.md
@@ -0,0 +1,30 @@
+# @sailkit/scribe
+
+Extract and test code fences from markdown documentation.
+
+## Usage
+
+```bash
+npx scribe [directory]
+```
+
+Scribe scans markdown files for TypeScript/JavaScript code fences and executes them, reporting pass/fail based on exit codes.
+
+## Inline Assertions
+
+Use simple assertions in your code blocks:
+
+```typescript
+const result = add(1, 2)
+if (result !== 3) throw new Error('Expected 3')
+```
+
+## API
+
+```typescript
+import { parseMarkdown, filterTestableBlocks, runBlocks } from '@sailkit/scribe'
+
+const blocks = parseMarkdown(content, 'file.md')
+const testable = filterTestableBlocks(blocks)
+const results = await runBlocks(testable)
+```
diff --git a/packages/scribe/package.json b/packages/scribe/package.json
new file mode 100644
index 0000000..d5862c2
--- /dev/null
+++ b/packages/scribe/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@sailkit/scribe",
+  "version": "0.0.1",
+  "description": "Extract and test code fences from markdown documentation",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "scribe": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node dist/cli.js"
+  },
+  "keywords": [
+    "documentation",
+    "testing",
+    "markdown",
+    "code-fence"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "log-update": "^7.0.2"
+  }
+}
diff --git a/packages/scribe/src/cli.ts b/packages/scribe/src/cli.ts
new file mode 100644
index 0000000..893fa30
--- /dev/null
+++ b/packages/scribe/src/cli.ts
@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * Scribe CLI - test code fences from markdown files
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { join, extname } from 'node:path'
+import { cpus } from 'node:os'
+import logUpdate from 'log-update'
+import { parseMarkdown, filterTestableBlocks, type CodeBlock } from './parser.js'
+import { runBlock, type RunResult } from './runner.js'
+
+// Detect interactive TTY vs CI/piped output
+const isTTY = process.stdout.isTTY ?? false
+const isCI = process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true'
+const useInteractiveOutput = isTTY && !isCI
+
+// Spinner frames
+const spinnerFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+let spinnerIndex = 0
+
+interface RunningTest {
+  label: string
+  index: number
+}
+
+async function findMarkdownFiles(dir: string): Promise<string[]> {
+  const files: string[] = []
+
+  async function walk(currentDir: string) {
+    const entries = await readdir(currentDir)
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry)
+      const info = await stat(fullPath)
+
+      if (info.isDirectory() && !entry.startsWith('.') && entry !== 'node_modules') {
+        await walk(fullPath)
+      } else if (info.isFile() && ['.md', '.mdx'].includes(extname(entry))) {
+        files.push(fullPath)
+      }
+    }
+  }
+
+  await walk(dir)
+  return files
+}
+
+function parseArgs(): { targetDir: string; concurrency: number } {
+  const args = process.argv.slice(2)
+  let targetDir = process.cwd()
+  let concurrency = cpus().length
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--runInBand' || arg === '-i') {
+      concurrency = 1
+    } else if (arg === '--parallel' || arg === '-j') {
+      const next = args[i + 1]
+      if (next && !next.startsWith('-')) {
+        concurrency = parseInt(next, 10) || cpus().length
+        i++
+      }
+    } else if (!arg.startsWith('-')) {
+      targetDir = arg
+    }
+  }
+
+  return { targetDir, concurrency }
+}
+
+function cleanErrorMessage(error: string): string {
+  return error
+    .replace(/file:\/\/[^\s]+\[eval\d*\]:\d+/g, '')
+    .replace(/\[stdin\]:\d+/g, '')
+    .split('\n')
+    .filter(line => !line.includes('node:internal') && !line.includes('file://'))
+    .map(line => line.trim())
+    .filter(Boolean)
+    .slice(0, 1)
+    .join('')
+}
+
+function renderRunningTests(running: RunningTest[]): string {
+  if (running.length === 0) return ''
+
+  const spinner = spinnerFrames[spinnerIndex % spinnerFrames.length]
+  const lines = running.map(t => `  \x1b[33m${spinner}\x1b[0m ${t.label}`)
+  return lines.join('\n')
+}
+
+async function main() {
+  const { targetDir, concurrency } = parseArgs()
+
+  console.log('Scanning for markdown files...')
+  const mdFiles = await findMarkdownFiles(targetDir)
+  console.log(`Found ${mdFiles.length} markdown file(s) (${concurrency} workers)\n`)
+
+  // Collect all blocks
+  const allBlocks: { block: CodeBlock; shortFile: string }[] = []
+
+  for (const file of mdFiles) {
+    const content = await readFile(file, 'utf-8')
+    const blocks = filterTestableBlocks(parseMarkdown(content, file))
+    const shortFile = file.replace(targetDir, '').replace(/^\//, '')
+
+    for (const block of blocks) {
+      allBlocks.push({ block, shortFile })
+    }
+  }
+
+  if (allBlocks.length === 0) {
+    console.log('No testable code blocks found.')
+    return
+  }
+
+  // Track state
+  const runningTests: Map<number, RunningTest> = new Map()
+  let passed = 0
+  let failed = 0
+
+  // Spinner animation interval (only updates the bottom running section)
+  let animationInterval: ReturnType<typeof setInterval> | undefined
+  if (useInteractiveOutput) {
+    animationInterval = setInterval(() => {
+      spinnerIndex++
+      const running = Array.from(runningTests.values())
+      if (running.length > 0) {
+        logUpdate(renderRunningTests(running))
+      }
+    }, 80)
+  }
+
+  // Helper to print a completed test (goes into scrollback)
+  function printCompleted(label: string, success: boolean, error?: string) {
+    if (useInteractiveOutput) {
+      // Clear the running section, print result, then redraw running section
+      logUpdate.clear()
+    }
+
+    if (success) {
+      console.log(`\x1b[32m✓\x1b[0m ${label}`)
+    } else {
+      console.log(`\x1b[31m✗\x1b[0m ${label}`)
+      if (error) {
+        console.log(`  \x1b[90m${error}\x1b[0m`)
+      }
+    }
+
+    if (useInteractiveOutput) {
+      // Redraw running tests at bottom
+      const running = Array.from(runningTests.values())
+      if (running.length > 0) {
+        logUpdate(renderRunningTests(running))
+      }
+    }
+  }
+
+  // Run with concurrency
+  const results: RunResult[] = new Array(allBlocks.length)
+  let nextIndex = 0
+
+  async function worker() {
+    while (nextIndex < allBlocks.length) {
+      const index = nextIndex++
+      const { shortFile, block } = allBlocks[index]
+      const label = `${shortFile}:${block.line}`
+
+      // Mark as running
+      runningTests.set(index, { label, index })
+
+      if (useInteractiveOutput) {
+        logUpdate(renderRunningTests(Array.from(runningTests.values())))
+      }
+
+      const result = await runBlock(block)
+      results[index] = result
+
+      // Remove from running
+      runningTests.delete(index)
+
+      const cleanError = result.error ? cleanErrorMessage(result.error) : undefined
+
+      if (result.success) {
+        passed++
+        printCompleted(label, true)
+      } else {
+        failed++
+        printCompleted(label, false, cleanError)
+      }
+    }
+  }
+
+  const workers = Array.from(
+    { length: Math.min(concurrency, allBlocks.length) },
+    () => worker()
+  )
+  await Promise.all(workers)
+
+  // Cleanup
+  if (animationInterval) {
+    clearInterval(animationInterval)
+  }
+
+  if (useInteractiveOutput) {
+    logUpdate.clear()
+  }
+
+  console.log()
+  const color = failed > 0 ? '\x1b[31m' : '\x1b[32m'
+  console.log(`${color}Results: ${passed}/${allBlocks.length} passed\x1b[0m`)
+
+  if (failed > 0) {
+    process.exit(1)
+  }
+}
+
+main().catch((err) => {
+  console.error('Scribe error:', err.message)
+  process.exit(1)
+})
diff --git a/packages/scribe/src/index.ts b/packages/scribe/src/index.ts
new file mode 100644
index 0000000..cb7c57d
--- /dev/null
+++ b/packages/scribe/src/index.ts
@@ -0,0 +1,10 @@
+/**
+ * @sailkit/scribe
+ * Extract and test code fences from markdown documentation
+ */
+
+export { parseMarkdown, filterTestableBlocks } from './parser.js'
+export type { CodeBlock } from './parser.js'
+
+export { runBlock, runBlocks } from './runner.js'
+export type { RunResult } from './runner.js'
diff --git a/packages/scribe/src/parser.ts b/packages/scribe/src/parser.ts
new file mode 100644
index 0000000..b330b0f
--- /dev/null
+++ b/packages/scribe/src/parser.ts
@@ -0,0 +1,40 @@
+/**
+ * Code fence parser - extracts fenced code blocks from markdown
+ */
+
+export interface CodeBlock {
+  language: string
+  code: string
+  file: string
+  line: number
+}
+
+const CODE_FENCE_REGEX = /^```(\w*)\n([\s\S]*?)^```/gm
+
+export function parseMarkdown(content: string, filePath: string): CodeBlock[] {
+  const blocks: CodeBlock[] = []
+  let match: RegExpExecArray | null
+
+  while ((match = CODE_FENCE_REGEX.exec(content)) !== null) {
+    const language = match[1] || 'text'
+    const code = match[2]
+
+    // Calculate line number
+    const beforeMatch = content.slice(0, match.index)
+    const line = beforeMatch.split('\n').length
+
+    blocks.push({
+      language,
+      code,
+      file: filePath,
+      line
+    })
+  }
+
+  return blocks
+}
+
+export function filterTestableBlocks(blocks: CodeBlock[]): CodeBlock[] {
+  const testableLanguages = ['typescript', 'ts', 'javascript', 'js']
+  return blocks.filter(block => testableLanguages.includes(block.language.toLowerCase()))
+}
diff --git a/packages/scribe/src/runner.ts b/packages/scribe/src/runner.ts
new file mode 100644
index 0000000..20602a9
--- /dev/null
+++ b/packages/scribe/src/runner.ts
@@ -0,0 +1,87 @@
+/**
+ * Simple runner - executes code blocks via stdin (no temp files)
+ */
+
+import { spawn } from 'node:child_process'
+import type { CodeBlock } from './parser.js'
+
+export interface RunResult {
+  block: CodeBlock
+  success: boolean
+  output: string
+  error?: string
+}
+
+export async function runBlock(block: CodeBlock): Promise<RunResult> {
+  const isTypeScript = block.language === 'typescript' || block.language === 'ts'
+
+  try {
+    const result = await executeCode(block.code, isTypeScript)
+
+    return {
+      block,
+      success: result.exitCode === 0,
+      output: result.stdout,
+      error: result.stderr || undefined
+    }
+  } catch (err) {
+    return {
+      block,
+      success: false,
+      output: '',
+      error: err instanceof Error ? err.message : String(err)
+    }
+  }
+}
+
+async function executeCode(code: string, isTypeScript: boolean): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  return new Promise((resolve) => {
+    // Use tsx for TypeScript, node for JavaScript - both read from stdin
+    const cmd = isTypeScript ? 'npx' : 'node'
+    const args = isTypeScript ? ['tsx', '--input-type=module'] : ['--input-type=module']
+
+    const proc = spawn(cmd, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 30000
+    })
+
+    let stdout = ''
+    let stderr = ''
+
+    proc.stdout.on('data', (data) => {
+      stdout += data.toString()
+    })
+
+    proc.stderr.on('data', (data) => {
+      stderr += data.toString()
+    })
+
+    proc.on('close', (code) => {
+      resolve({
+        exitCode: code ?? 1,
+        stdout,
+        stderr
+      })
+    })
+
+    proc.on('error', (err) => {
+      resolve({
+        exitCode: 1,
+        stdout,
+        stderr: err.message
+      })
+    })
+
+    // Write code to stdin and close
+    proc.stdin.write(code)
+    proc.stdin.end()
+  })
+}
+
+export async function runBlocks(blocks: CodeBlock[]): Promise<RunResult[]> {
+  const results: RunResult[] = []
+  for (const block of blocks) {
+    results.push(await runBlock(block))
+  }
+  return results
+}
diff --git a/packages/scribe/tsconfig.json b/packages/scribe/tsconfig.json
new file mode 100644
index 0000000..f0423d6
--- /dev/null
+++ b/packages/scribe/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

From 406c62e2f0e7781aca38b704107ef3a50441f1ac Mon Sep 17 00:00:00 2001
From: Josh Ribakoff <josh.ribakoff@gmail.com>
Date: Mon, 15 Dec 2025 18:41:25 -0800
Subject: [PATCH 2/5] perf: use esbuild + vm for ~240x faster code execution
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace child process spawning with in-process execution:
- Use esbuild transform for TypeScript transpilation
- Execute code in vm sandbox with captured console output
- Reduces test time from ~62s to ~0.26s

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 packages/scribe/package.json  |  1 +
 packages/scribe/src/runner.ts | 96 +++++++++++++++++------------------
 2 files changed, 47 insertions(+), 50 deletions(-)

diff --git a/packages/scribe/package.json b/packages/scribe/package.json
index d5862c2..0b2a647 100644
--- a/packages/scribe/package.json
+++ b/packages/scribe/package.json
@@ -23,6 +23,7 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
+    "esbuild": "^0.27.1",
     "log-update": "^7.0.2"
   }
 }
diff --git a/packages/scribe/src/runner.ts b/packages/scribe/src/runner.ts
index 20602a9..d36681c 100644
--- a/packages/scribe/src/runner.ts
+++ b/packages/scribe/src/runner.ts
@@ -1,8 +1,10 @@
 /**
- * Simple runner - executes code blocks via stdin (no temp files)
+ * In-process runner using esbuild transform + vm module
+ * Much faster than spawning child processes (~240x speedup)
  */
 
-import { spawn } from 'node:child_process'
+import vm from 'node:vm'
+import { transform } from 'esbuild'
 import type { CodeBlock } from './parser.js'
 
 export interface RunResult {
@@ -16,13 +18,51 @@ export async function runBlock(block: CodeBlock): Promise<RunResult> {
   const isTypeScript = block.language === 'typescript' || block.language === 'ts'
 
   try {
-    const result = await executeCode(block.code, isTypeScript)
+    // Transpile TypeScript to JavaScript if needed
+    let code = block.code
+    if (isTypeScript) {
+      const result = await transform(code, {
+        loader: 'ts',
+        format: 'cjs', // vm.runInContext works better with CJS
+        target: 'node18'
+      })
+      code = result.code
+    }
+
+    // Capture console output
+    let stdout = ''
+    const mockConsole = {
+      log: (...args: unknown[]) => { stdout += args.map(String).join(' ') + '\n' },
+      error: (...args: unknown[]) => { stdout += args.map(String).join(' ') + '\n' },
+      warn: (...args: unknown[]) => { stdout += args.map(String).join(' ') + '\n' },
+      info: (...args: unknown[]) => { stdout += args.map(String).join(' ') + '\n' }
+    }
+
+    // Create sandbox with common globals
+    const sandbox = {
+      console: mockConsole,
+      setTimeout,
+      setInterval,
+      clearTimeout,
+      clearInterval,
+      Buffer,
+      process: { env: process.env },
+      Error,
+      TypeError,
+      ReferenceError,
+      SyntaxError
+    }
+
+    vm.createContext(sandbox)
+
+    // Execute with timeout
+    const script = new vm.Script(code, { filename: 'code-block.js' })
+    script.runInContext(sandbox, { timeout: 5000 })
 
     return {
       block,
-      success: result.exitCode === 0,
-      output: result.stdout,
-      error: result.stderr || undefined
+      success: true,
+      output: stdout
     }
   } catch (err) {
     return {
@@ -34,50 +74,6 @@ export async function runBlock(block: CodeBlock): Promise<RunResult> {
   }
 }
 
-async function executeCode(code: string, isTypeScript: boolean): Promise<{ exitCode: number; stdout: string; stderr: string }> {
-  return new Promise((resolve) => {
-    // Use tsx for TypeScript, node for JavaScript - both read from stdin
-    const cmd = isTypeScript ? 'npx' : 'node'
-    const args = isTypeScript ? ['tsx', '--input-type=module'] : ['--input-type=module']
-
-    const proc = spawn(cmd, args, {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      timeout: 30000
-    })
-
-    let stdout = ''
-    let stderr = ''
-
-    proc.stdout.on('data', (data) => {
-      stdout += data.toString()
-    })
-
-    proc.stderr.on('data', (data) => {
-      stderr += data.toString()
-    })
-
-    proc.on('close', (code) => {
-      resolve({
-        exitCode: code ?? 1,
-        stdout,
-        stderr
-      })
-    })
-
-    proc.on('error', (err) => {
-      resolve({
-        exitCode: 1,
-        stdout,
-        stderr: err.message
-      })
-    })
-
-    // Write code to stdin and close
-    proc.stdin.write(code)
-    proc.stdin.end()
-  })
-}
-
 export async function runBlocks(blocks: CodeBlock[]): Promise<RunResult[]> {
   const results: RunResult[] = []
   for (const block of blocks) {

From 6e048ae99abb3c3d34cff89d8ad0e163c9f4397a Mon Sep 17 00:00:00 2001
From: Josh Ribakoff <josh.ribakoff@gmail.com>
Date: Mon, 15 Dec 2025 18:51:12 -0800
Subject: [PATCH 3/5] feat: require path argument, add commander + vitest tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Use commander for CLI argument parsing
- Make path argument required (like ESLint/Prettier)
- Add IO interface for testability (mock stdout/stderr)
- Add vitest with 8 unit tests using mock IO
- Fix parser to handle info strings with 'scribe' marker

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 packages/scribe/package.json    |   6 +-
 packages/scribe/src/cli.test.ts | 160 ++++++++++++++++++++++++++++++++
 packages/scribe/src/cli.ts      | 129 ++++++++++++++++---------
 packages/scribe/src/parser.ts   |  16 +++-
 4 files changed, 260 insertions(+), 51 deletions(-)
 create mode 100644 packages/scribe/src/cli.test.ts

diff --git a/packages/scribe/package.json b/packages/scribe/package.json
index 0b2a647..865801e 100644
--- a/packages/scribe/package.json
+++ b/packages/scribe/package.json
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "node dist/cli.js"
+    "test": "vitest run"
   },
   "keywords": [
     "documentation",
@@ -20,9 +20,11 @@
   ],
   "license": "MIT",
   "devDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.15"
   },
   "dependencies": {
+    "commander": "^14.0.2",
     "esbuild": "^0.27.1",
     "log-update": "^7.0.2"
   }
diff --git a/packages/scribe/src/cli.test.ts b/packages/scribe/src/cli.test.ts
new file mode 100644
index 0000000..d6ce7e6
--- /dev/null
+++ b/packages/scribe/src/cli.test.ts
@@ -0,0 +1,160 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { run, type IO, type RunOptions } from './cli.js'
+import { writeFile, mkdir, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+// Mock IO that captures output
+function createMockIO(): IO & { stdout: string; stderr: string } {
+  const io = {
+    stdout: '',
+    stderr: '',
+    write(text: string) {
+      io.stdout += text
+    },
+    writeError(text: string) {
+      io.stderr += text
+    }
+  }
+  return io
+}
+
+describe('scribe CLI', () => {
+  let testDir: string
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `scribe-test-${Date.now()}`)
+    await mkdir(testDir, { recursive: true })
+  })
+
+  it('reports error for non-existent path', async () => {
+    const io = createMockIO()
+    const result = await run({ targetPath: '/nonexistent/path', concurrency: 1 }, io)
+
+    expect(result.failed).toBe(1)
+    expect(io.stderr).toContain('Error: Path not found')
+  })
+
+  it('reports no testable blocks for markdown without code fences', async () => {
+    const mdPath = join(testDir, 'empty.md')
+    await writeFile(mdPath, '# Hello\n\nNo code here.')
+
+    const io = createMockIO()
+    const result = await run({ targetPath: mdPath, concurrency: 1 }, io)
+
+    expect(result.passed).toBe(0)
+    expect(result.failed).toBe(0)
+    expect(io.stdout).toContain('No testable code blocks found')
+  })
+
+  it('runs passing JavaScript code blocks', async () => {
+    const mdPath = join(testDir, 'passing.md')
+    await writeFile(mdPath, `# Test
+
+\`\`\`javascript scribe
+console.log("hello")
+\`\`\`
+`)
+
+    const io = createMockIO()
+    const result = await run({ targetPath: mdPath, concurrency: 1 }, io)
+
+    expect(result.passed).toBe(1)
+    expect(result.failed).toBe(0)
+    expect(io.stdout).toContain('Results: 1/1 passed')
+  })
+
+  it('runs passing TypeScript code blocks', async () => {
+    const mdPath = join(testDir, 'typescript.md')
+    await writeFile(mdPath, `# TypeScript Test
+
+\`\`\`typescript scribe
+const x: number = 42
+console.log(x)
+\`\`\`
+`)
+
+    const io = createMockIO()
+    const result = await run({ targetPath: mdPath, concurrency: 1 }, io)
+
+    expect(result.passed).toBe(1)
+    expect(result.failed).toBe(0)
+  })
+
+  it('reports failing code blocks', async () => {
+    const mdPath = join(testDir, 'failing.md')
+    await writeFile(mdPath, `# Failing Test
+
+\`\`\`javascript scribe
+throw new Error("oops")
+\`\`\`
+`)
+
+    const io = createMockIO()
+    const result = await run({ targetPath: mdPath, concurrency: 1 }, io)
+
+    expect(result.passed).toBe(0)
+    expect(result.failed).toBe(1)
+    expect(io.stdout).toContain('Results: 0/1 passed')
+  })
+
+  it('scans directories for markdown files', async () => {
+    await writeFile(join(testDir, 'a.md'), `\`\`\`js scribe
+console.log(1)
+\`\`\``)
+    await writeFile(join(testDir, 'b.md'), `\`\`\`js scribe
+console.log(2)
+\`\`\``)
+
+    const io = createMockIO()
+    const result = await run({ targetPath: testDir, concurrency: 1 }, io)
+
+    expect(result.passed).toBe(2)
+    expect(result.failed).toBe(0)
+    expect(io.stdout).toContain('Found 2 markdown file(s)')
+  })
+
+  it('ignores code blocks without scribe marker', async () => {
+    const mdPath = join(testDir, 'unmarked.md')
+    await writeFile(mdPath, `# Test
+
+\`\`\`javascript
+// This should be ignored
+throw new Error("not run")
+\`\`\`
+
+\`\`\`javascript scribe
+console.log("this runs")
+\`\`\`
+`)
+
+    const io = createMockIO()
+    const result = await run({ targetPath: mdPath, concurrency: 1 }, io)
+
+    expect(result.passed).toBe(1)
+    expect(result.failed).toBe(0)
+  })
+
+  it('runs multiple blocks in parallel when concurrency > 1', async () => {
+    const mdPath = join(testDir, 'parallel.md')
+    await writeFile(mdPath, `
+\`\`\`js scribe
+console.log(1)
+\`\`\`
+
+\`\`\`js scribe
+console.log(2)
+\`\`\`
+
+\`\`\`js scribe
+console.log(3)
+\`\`\`
+`)
+
+    const io = createMockIO()
+    const result = await run({ targetPath: mdPath, concurrency: 3 }, io)
+
+    expect(result.passed).toBe(3)
+    expect(result.failed).toBe(0)
+  })
+})
diff --git a/packages/scribe/src/cli.ts b/packages/scribe/src/cli.ts
index 893fa30..abda40a 100644
--- a/packages/scribe/src/cli.ts
+++ b/packages/scribe/src/cli.ts
@@ -6,10 +6,23 @@
 import { readFile, readdir, stat } from 'node:fs/promises'
 import { join, extname } from 'node:path'
 import { cpus } from 'node:os'
+import { Command } from 'commander'
 import logUpdate from 'log-update'
 import { parseMarkdown, filterTestableBlocks, type CodeBlock } from './parser.js'
 import { runBlock, type RunResult } from './runner.js'
 
+// IO interface for testability
+export interface IO {
+  write(text: string): void
+  writeError(text: string): void
+}
+
+// Real IO implementation
+const realIO: IO = {
+  write: (text) => process.stdout.write(text),
+  writeError: (text) => process.stderr.write(text)
+}
+
 // Detect interactive TTY vs CI/piped output
 const isTTY = process.stdout.isTTY ?? false
 const isCI = process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true'
@@ -24,6 +37,11 @@ interface RunningTest {
   index: number
 }
 
+export interface RunOptions {
+  targetPath: string
+  concurrency: number
+}
+
 async function findMarkdownFiles(dir: string): Promise<string[]> {
   const files: string[] = []
 
@@ -45,29 +63,6 @@ async function findMarkdownFiles(dir: string): Promise<string[]> {
   return files
 }
 
-function parseArgs(): { targetDir: string; concurrency: number } {
-  const args = process.argv.slice(2)
-  let targetDir = process.cwd()
-  let concurrency = cpus().length
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i]
-    if (arg === '--runInBand' || arg === '-i') {
-      concurrency = 1
-    } else if (arg === '--parallel' || arg === '-j') {
-      const next = args[i + 1]
-      if (next && !next.startsWith('-')) {
-        concurrency = parseInt(next, 10) || cpus().length
-        i++
-      }
-    } else if (!arg.startsWith('-')) {
-      targetDir = arg
-    }
-  }
-
-  return { targetDir, concurrency }
-}
-
 function cleanErrorMessage(error: string): string {
   return error
     .replace(/file:\/\/[^\s]+\[eval\d*\]:\d+/g, '')
@@ -88,12 +83,29 @@ function renderRunningTests(running: RunningTest[]): string {
   return lines.join('\n')
 }
 
-async function main() {
-  const { targetDir, concurrency } = parseArgs()
+export async function run(options: RunOptions, io: IO = realIO): Promise<{ passed: number; failed: number }> {
+  const { targetPath, concurrency } = options
+
+  // Determine if target is file or directory
+  const targetStat = await stat(targetPath).catch(() => null)
+  if (!targetStat) {
+    io.writeError(`Error: Path not found: ${targetPath}\n`)
+    return { passed: 0, failed: 1 }
+  }
 
-  console.log('Scanning for markdown files...')
-  const mdFiles = await findMarkdownFiles(targetDir)
-  console.log(`Found ${mdFiles.length} markdown file(s) (${concurrency} workers)\n`)
+  let mdFiles: string[]
+  let baseDir: string
+
+  if (targetStat.isFile()) {
+    mdFiles = [targetPath]
+    baseDir = targetPath.includes('/') ? targetPath.substring(0, targetPath.lastIndexOf('/')) : '.'
+  } else {
+    io.write('Scanning for markdown files...\n')
+    mdFiles = await findMarkdownFiles(targetPath)
+    baseDir = targetPath
+  }
+
+  io.write(`Found ${mdFiles.length} markdown file(s) (${concurrency} workers)\n\n`)
 
   // Collect all blocks
   const allBlocks: { block: CodeBlock; shortFile: string }[] = []
@@ -101,7 +113,11 @@ async function main() {
   for (const file of mdFiles) {
     const content = await readFile(file, 'utf-8')
     const blocks = filterTestableBlocks(parseMarkdown(content, file))
-    const shortFile = file.replace(targetDir, '').replace(/^\//, '')
+    // Get relative path for display
+    let shortFile = file
+    if (baseDir !== '.' && file.startsWith(baseDir)) {
+      shortFile = file.slice(baseDir.length).replace(/^\//, '')
+    }
 
     for (const block of blocks) {
       allBlocks.push({ block, shortFile })
@@ -109,8 +125,8 @@ async function main() {
   }
 
   if (allBlocks.length === 0) {
-    console.log('No testable code blocks found.')
-    return
+    io.write('No testable code blocks found.\n')
+    return { passed: 0, failed: 0 }
   }
 
   // Track state
@@ -133,21 +149,19 @@ async function main() {
   // Helper to print a completed test (goes into scrollback)
   function printCompleted(label: string, success: boolean, error?: string) {
     if (useInteractiveOutput) {
-      // Clear the running section, print result, then redraw running section
       logUpdate.clear()
     }
 
     if (success) {
-      console.log(`\x1b[32m✓\x1b[0m ${label}`)
+      io.write(`\x1b[32m✓\x1b[0m ${label}\n`)
     } else {
-      console.log(`\x1b[31m✗\x1b[0m ${label}`)
+      io.write(`\x1b[31m✗\x1b[0m ${label}\n`)
       if (error) {
-        console.log(`  \x1b[90m${error}\x1b[0m`)
+        io.write(`  \x1b[90m${error}\x1b[0m\n`)
       }
     }
 
     if (useInteractiveOutput) {
-      // Redraw running tests at bottom
       const running = Array.from(runningTests.values())
       if (running.length > 0) {
         logUpdate(renderRunningTests(running))
@@ -165,7 +179,6 @@ async function main() {
       const { shortFile, block } = allBlocks[index]
       const label = `${shortFile}:${block.line}`
 
-      // Mark as running
       runningTests.set(index, { label, index })
 
       if (useInteractiveOutput) {
@@ -175,7 +188,6 @@ async function main() {
       const result = await runBlock(block)
       results[index] = result
 
-      // Remove from running
       runningTests.delete(index)
 
       const cleanError = result.error ? cleanErrorMessage(result.error) : undefined
@@ -196,7 +208,6 @@ async function main() {
   )
   await Promise.all(workers)
 
-  // Cleanup
   if (animationInterval) {
     clearInterval(animationInterval)
   }
@@ -205,16 +216,44 @@ async function main() {
     logUpdate.clear()
   }
 
-  console.log()
+  io.write('\n')
   const color = failed > 0 ? '\x1b[31m' : '\x1b[32m'
-  console.log(`${color}Results: ${passed}/${allBlocks.length} passed\x1b[0m`)
+  io.write(`${color}Results: ${passed}/${allBlocks.length} passed\x1b[0m\n`)
+
+  return { passed, failed }
+}
+
+// CLI entry point
+const program = new Command()
+  .name('scribe')
+  .description('Test code fences from markdown files')
+  .argument('<path>', 'File or directory to test')
+  .option('-i, --runInBand', 'Run tests sequentially (no parallelism)')
+  .option('-j, --parallel <n>', 'Set number of parallel workers', String(cpus().length))
+
+async function main() {
+  program.parse()
+
+  const targetPath = program.args[0]
+  const opts = program.opts()
+
+  let concurrency = parseInt(opts.parallel, 10) || cpus().length
+  if (opts.runInBand) {
+    concurrency = 1
+  }
+
+  const { failed } = await run({ targetPath, concurrency })
 
   if (failed > 0) {
     process.exit(1)
   }
 }
 
-main().catch((err) => {
-  console.error('Scribe error:', err.message)
-  process.exit(1)
-})
+// Only run when executed directly, not when imported for testing
+const isMainModule = import.meta.url === `file://${process.argv[1]}`
+if (isMainModule) {
+  main().catch((err) => {
+    console.error('Scribe error:', err.message)
+    process.exit(1)
+  })
+}
diff --git a/packages/scribe/src/parser.ts b/packages/scribe/src/parser.ts
index b330b0f..546d900 100644
--- a/packages/scribe/src/parser.ts
+++ b/packages/scribe/src/parser.ts
@@ -7,9 +7,12 @@ export interface CodeBlock {
   code: string
   file: string
   line: number
+  meta?: string
 }
 
-const CODE_FENCE_REGEX = /^```(\w*)\n([\s\S]*?)^```/gm
+// Matches code fences with optional info string (e.g., ```javascript scribe)
+// Captures: 1=language, 2=rest of info line (may contain "scribe" marker), 3=code
+const CODE_FENCE_REGEX = /^```(\w*)([^\n]*)\n([\s\S]*?)^```/gm
 
 export function parseMarkdown(content: string, filePath: string): CodeBlock[] {
   const blocks: CodeBlock[] = []
@@ -17,7 +20,8 @@ export function parseMarkdown(content: string, filePath: string): CodeBlock[] {
 
   while ((match = CODE_FENCE_REGEX.exec(content)) !== null) {
     const language = match[1] || 'text'
-    const code = match[2]
+    const infoString = match[2]?.trim() || ''
+    const code = match[3]
 
     // Calculate line number
     const beforeMatch = content.slice(0, match.index)
@@ -27,7 +31,8 @@ export function parseMarkdown(content: string, filePath: string): CodeBlock[] {
       language,
       code,
       file: filePath,
-      line
+      line,
+      meta: infoString
     })
   }
 
@@ -36,5 +41,8 @@ export function parseMarkdown(content: string, filePath: string): CodeBlock[] {
 
 export function filterTestableBlocks(blocks: CodeBlock[]): CodeBlock[] {
   const testableLanguages = ['typescript', 'ts', 'javascript', 'js']
-  return blocks.filter(block => testableLanguages.includes(block.language.toLowerCase()))
+  return blocks.filter(block =>
+    testableLanguages.includes(block.language.toLowerCase()) &&
+    block.meta?.includes('scribe')
+  )
 }

From b6347e72575622b2e4e2e0d062f8276d2e5651e7 Mon Sep 17 00:00:00 2001
From: Josh Ribakoff <josh.ribakoff@gmail.com>
Date: Mon, 15 Dec 2025 18:57:10 -0800
Subject: [PATCH 4/5] feat: test all JS/TS code blocks by default, opt-out with
 nocheck
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove scribe marker requirement - all JS/TS blocks tested by default
- Add nocheck marker to skip specific blocks (```ts nocheck)
- Add vitest.config.ts to exclude dist folder from tests

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 packages/scribe/src/cli.test.ts  | 24 ++++++++++++------------
 packages/scribe/src/parser.ts    |  2 +-
 packages/scribe/vitest.config.ts |  8 ++++++++
 3 files changed, 21 insertions(+), 13 deletions(-)
 create mode 100644 packages/scribe/vitest.config.ts

diff --git a/packages/scribe/src/cli.test.ts b/packages/scribe/src/cli.test.ts
index d6ce7e6..8167f03 100644
--- a/packages/scribe/src/cli.test.ts
+++ b/packages/scribe/src/cli.test.ts
@@ -51,7 +51,7 @@ describe('scribe CLI', () => {
     const mdPath = join(testDir, 'passing.md')
     await writeFile(mdPath, `# Test
 
-\`\`\`javascript scribe
+\`\`\`javascript
 console.log("hello")
 \`\`\`
 `)
@@ -68,7 +68,7 @@ console.log("hello")
     const mdPath = join(testDir, 'typescript.md')
     await writeFile(mdPath, `# TypeScript Test
 
-\`\`\`typescript scribe
+\`\`\`typescript
 const x: number = 42
 console.log(x)
 \`\`\`
@@ -85,7 +85,7 @@ console.log(x)
     const mdPath = join(testDir, 'failing.md')
     await writeFile(mdPath, `# Failing Test
 
-\`\`\`javascript scribe
+\`\`\`javascript
 throw new Error("oops")
 \`\`\`
 `)
@@ -99,10 +99,10 @@ throw new Error("oops")
   })
 
   it('scans directories for markdown files', async () => {
-    await writeFile(join(testDir, 'a.md'), `\`\`\`js scribe
+    await writeFile(join(testDir, 'a.md'), `\`\`\`js
 console.log(1)
 \`\`\``)
-    await writeFile(join(testDir, 'b.md'), `\`\`\`js scribe
+    await writeFile(join(testDir, 'b.md'), `\`\`\`js
 console.log(2)
 \`\`\``)
 
@@ -114,16 +114,16 @@ console.log(2)
     expect(io.stdout).toContain('Found 2 markdown file(s)')
   })
 
-  it('ignores code blocks without scribe marker', async () => {
-    const mdPath = join(testDir, 'unmarked.md')
+  it('ignores code blocks with nocheck marker', async () => {
+    const mdPath = join(testDir, 'nocheck.md')
     await writeFile(mdPath, `# Test
 
-\`\`\`javascript
+\`\`\`javascript nocheck
 // This should be ignored
 throw new Error("not run")
 \`\`\`
 
-\`\`\`javascript scribe
+\`\`\`javascript
 console.log("this runs")
 \`\`\`
 `)
@@ -138,15 +138,15 @@ console.log("this runs")
   it('runs multiple blocks in parallel when concurrency > 1', async () => {
     const mdPath = join(testDir, 'parallel.md')
     await writeFile(mdPath, `
-\`\`\`js scribe
+\`\`\`js
 console.log(1)
 \`\`\`
 
-\`\`\`js scribe
+\`\`\`js
 console.log(2)
 \`\`\`
 
-\`\`\`js scribe
+\`\`\`js
 console.log(3)
 \`\`\`
 `)
diff --git a/packages/scribe/src/parser.ts b/packages/scribe/src/parser.ts
index 546d900..32db45d 100644
--- a/packages/scribe/src/parser.ts
+++ b/packages/scribe/src/parser.ts
@@ -43,6 +43,6 @@ export function filterTestableBlocks(blocks: CodeBlock[]): CodeBlock[] {
   const testableLanguages = ['typescript', 'ts', 'javascript', 'js']
   return blocks.filter(block =>
     testableLanguages.includes(block.language.toLowerCase()) &&
-    block.meta?.includes('scribe')
+    !block.meta?.includes('nocheck') // opt-out with ```ts nocheck
   )
 }
diff --git a/packages/scribe/vitest.config.ts b/packages/scribe/vitest.config.ts
new file mode 100644
index 0000000..7aa4024
--- /dev/null
+++ b/packages/scribe/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+    exclude: ['dist/**', 'node_modules/**']
+  }
+})

From 564b5b1ed153b3f109d85bfda88730b09789bb9b Mon Sep 17 00:00:00 2001
From: Josh Ribakoff <josh.ribakoff@gmail.com>
Date: Mon, 15 Dec 2025 19:19:47 -0800
Subject: [PATCH 5/5] feat(scribe): bundle imports, inject assert globally,
 guarantee no disk writes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .gitignore                    |  1 +
 packages/scribe/README.md     | 41 +++++++++++++++++++++++++++++------
 packages/scribe/src/cli.ts    |  3 +++
 packages/scribe/src/index.ts  |  5 ++++-
 packages/scribe/src/parser.ts |  3 +++
 packages/scribe/src/runner.ts | 38 +++++++++++++++++++++-----------
 6 files changed, 70 insertions(+), 21 deletions(-)

diff --git a/.gitignore b/.gitignore
index cd8400f..49276f1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,7 @@ node_modules/
 
 # Build output
 dist/
+.astro/
 
 # Lock files (using npm)
 package-lock.json
diff --git a/packages/scribe/README.md b/packages/scribe/README.md
index 7e09674..0aea54d 100644
--- a/packages/scribe/README.md
+++ b/packages/scribe/README.md
@@ -1,24 +1,42 @@
 # @sailkit/scribe
 
-Extract and test code fences from markdown documentation.
+Test code fences from markdown documentation.
+
+**READ-ONLY FILESYSTEM SAFE** - No temp files, no disk writes. Everything stays in memory.
 
 ## Usage
 
 ```bash
-npx scribe [directory]
+scribe <path>        # Test a file or directory
+scribe docs/         # Scan all .md/.mdx files
+scribe README.md     # Test a single file
 ```
 
-Scribe scans markdown files for TypeScript/JavaScript code fences and executes them, reporting pass/fail based on exit codes.
+All JavaScript/TypeScript code blocks are tested by default. Use `nocheck` to skip:
+
+~~~markdown
+```typescript nocheck
+// This block won't be tested
+```
+~~~
 
-## Inline Assertions
+## Writing Testable Examples
 
-Use simple assertions in your code blocks:
+Code blocks should be self-contained and use assertions. Node's `assert` module is globally available:
 
 ```typescript
-const result = add(1, 2)
-if (result !== 3) throw new Error('Expected 3')
+const items = ['a', 'b', 'c']
+assert.strictEqual(items[0], 'a')
+assert.deepStrictEqual(items, ['a', 'b', 'c'])
 ```
 
+No import needed - `assert` is injected by scribe. Code remains copy-pasteable since `assert` is a standard Node module.
+
+## CLI Options
+
+- `-i, --runInBand` - Run tests sequentially (no parallelism)
+- `-j, --parallel <n>` - Set number of parallel workers (default: CPU count)
+
 ## API
 
 ```typescript
@@ -28,3 +46,12 @@ const blocks = parseMarkdown(content, 'file.md')
 const testable = filterTestableBlocks(blocks)
 const results = await runBlocks(testable)
 ```
+
+## Future
+
+Scribe will evolve beyond static analysis to enable interactive documentation:
+
+- **In-browser execution** - Run code blocks directly on the page
+- **Live verification** - See pass/fail results as you read
+- **Monaco Editor integration** - Edit and re-run examples inline
+- **Playground mode** - Experiment with code without leaving the docs
diff --git a/packages/scribe/src/cli.ts b/packages/scribe/src/cli.ts
index abda40a..dafdfd3 100644
--- a/packages/scribe/src/cli.ts
+++ b/packages/scribe/src/cli.ts
@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 /**
+ * IMPORTANT: THIS MODULE MUST BE READ-ONLY FILESYSTEM SAFE
+ * No temp files, no disk writes - everything stays in memory.
+ *
  * Scribe CLI - test code fences from markdown files
  */
 
diff --git a/packages/scribe/src/index.ts b/packages/scribe/src/index.ts
index cb7c57d..fbdf5d8 100644
--- a/packages/scribe/src/index.ts
+++ b/packages/scribe/src/index.ts
@@ -1,6 +1,9 @@
 /**
+ * IMPORTANT: THIS PACKAGE MUST BE READ-ONLY FILESYSTEM SAFE
+ * No temp files, no disk writes - everything stays in memory.
+ *
  * @sailkit/scribe
- * Extract and test code fences from markdown documentation
+ * Test code fences from markdown documentation
  */
 
 export { parseMarkdown, filterTestableBlocks } from './parser.js'
diff --git a/packages/scribe/src/parser.ts b/packages/scribe/src/parser.ts
index 32db45d..cd95b18 100644
--- a/packages/scribe/src/parser.ts
+++ b/packages/scribe/src/parser.ts
@@ -1,4 +1,7 @@
 /**
+ * IMPORTANT: THIS MODULE MUST BE READ-ONLY FILESYSTEM SAFE
+ * No temp files, no disk writes - everything stays in memory.
+ *
  * Code fence parser - extracts fenced code blocks from markdown
  */
 
diff --git a/packages/scribe/src/runner.ts b/packages/scribe/src/runner.ts
index d36681c..ae621d5 100644
--- a/packages/scribe/src/runner.ts
+++ b/packages/scribe/src/runner.ts
@@ -1,10 +1,15 @@
 /**
- * In-process runner using esbuild transform + vm module
- * Much faster than spawning child processes (~240x speedup)
+ * IMPORTANT: THIS MODULE MUST BE READ-ONLY FILESYSTEM SAFE
+ * No temp files, no disk writes - everything stays in memory.
+ *
+ * In-process runner using esbuild build + vm module
+ * Bundles imports so code blocks can use real packages
  */
 
 import vm from 'node:vm'
-import { transform } from 'esbuild'
+import assert from 'node:assert'
+import { build } from 'esbuild'
+import { dirname } from 'node:path'
 import type { CodeBlock } from './parser.js'
 
 export interface RunResult {
@@ -18,16 +23,21 @@ export async function runBlock(block: CodeBlock): Promise<RunResult> {
   const isTypeScript = block.language === 'typescript' || block.language === 'ts'
 
   try {
-    // Transpile TypeScript to JavaScript if needed
-    let code = block.code
-    if (isTypeScript) {
-      const result = await transform(code, {
-        loader: 'ts',
-        format: 'cjs', // vm.runInContext works better with CJS
-        target: 'node18'
-      })
-      code = result.code
-    }
+    // Bundle with esbuild using stdin - no temp files
+    const result = await build({
+      stdin: {
+        contents: block.code,
+        loader: isTypeScript ? 'ts' : 'js',
+        resolveDir: dirname(block.file), // resolve imports relative to markdown file
+      },
+      bundle: true,
+      write: false,
+      format: 'cjs',
+      platform: 'node',
+      target: 'node18',
+    })
+
+    const code = result.outputFiles[0].text
 
     // Capture console output
     let stdout = ''
@@ -39,8 +49,10 @@ export async function runBlock(block: CodeBlock): Promise<RunResult> {
     }
 
     // Create sandbox with common globals
+    // assert is provided globally so code blocks can use it without imports
     const sandbox = {
       console: mockConsole,
+      assert,
       setTimeout,
       setInterval,
       clearTimeout,