tryscript 0.0.1 → 0.1.1

package/dist/src-CxUUK92Q.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"src-CxUUK92Q.cjs","names":["DEFAULT_COVERAGE_CONFIG: Required<CoverageConfig>","module","config: TestConfig","blocks: TestBlock[]","match: RegExpExecArray | null","commandLines: string[]","outputLines: string[]","stderrLines: string[]","expectedStderr: string | undefined","cwd: string","combinedChunks: { data: Buffer; type: 'stdout' | 'stderr' }[]","stdoutChunks: Buffer[]","stderrChunks: Buffer[]","VERSION: string"],"sources":["../src/lib/config.ts","../src/lib/parser.ts","../src/lib/runner.ts","../src/lib/matcher.ts","../src/index.ts"],"sourcesContent":["import { pathToFileURL } from 'node:url';\nimport { existsSync } from 'node:fs';\nimport { resolve } from 'node:path';\nimport type { TestConfig, CoverageConfig } from './types.js';\n\n/** Fixture configuration for copying files to sandbox directory */\nexport interface Fixture {\n  /** Source path (resolved relative to test file) */\n  source: string;\n  /** Destination path (resolved relative to sandbox dir) */\n  dest?: string;\n}\n\nexport interface TryscriptConfig {\n  /** Working directory for commands (default: test file directory) */\n  cwd?: string;\n  /** Run in isolated sandbox: true = empty temp, path = copy to temp */\n  sandbox?: boolean | string;\n  /** Fixtures to copy to sandbox directory before tests */\n  fixtures?: (string | Fixture)[];\n  /** Script to run before first test block */\n  before?: string;\n  /** Script to run after all test blocks */\n  after?: string;\n  env?: Record<string, string>;\n  timeout?: number;\n  patterns?: Record<string, RegExp | string>;\n  tests?: string[];\n  /** Coverage configuration (used with --coverage flag) */\n  coverage?: CoverageConfig;\n}\n\n/** Default coverage configuration values. */\nexport const DEFAULT_COVERAGE_CONFIG: Required<CoverageConfig> = {\n  reportsDir: 'coverage-tryscript',\n  reporters: ['text', 'html'],\n  include: ['dist/**'],\n  src: 'src',\n};\n\n/**\n * Resolve coverage options by merging user config with defaults.\n */\nexport function resolveCoverageConfig(config?: CoverageConfig): Required<CoverageConfig> {\n  return {\n    reportsDir: config?.reportsDir ?? DEFAULT_COVERAGE_CONFIG.reportsDir,\n    reporters: config?.reporters ?? DEFAULT_COVERAGE_CONFIG.reporters,\n    include: config?.include ?? DEFAULT_COVERAGE_CONFIG.include,\n    src: config?.src ?? DEFAULT_COVERAGE_CONFIG.src,\n  };\n}\n\nconst CONFIG_FILES = ['tryscript.config.ts', 'tryscript.config.js', 'tryscript.config.mjs'];\n\n/**\n * Load config file using dynamic import.\n * Supports both TypeScript (via tsx/ts-node) and JavaScript configs.\n */\nexport async function loadConfig(baseDir: string): Promise<TryscriptConfig> {\n  for (const filename of CONFIG_FILES) {\n    const configPath = resolve(baseDir, filename);\n    if (existsSync(configPath)) {\n      const configUrl = pathToFileURL(configPath).href;\n      const module = (await import(configUrl)) as { default?: TryscriptConfig } | TryscriptConfig;\n      return (module as { default?: TryscriptConfig }).default ?? (module as TryscriptConfig);\n    }\n  }\n  return {};\n}\n\n/**\n * Merge config with frontmatter overrides.\n * Frontmatter takes precedence over config file.\n */\nexport function mergeConfig(base: TryscriptConfig, frontmatter: TestConfig): TryscriptConfig {\n  return {\n    ...base,\n    ...frontmatter,\n    env: { ...base.env, ...frontmatter.env },\n    patterns: { ...base.patterns, ...frontmatter.patterns },\n    fixtures: [...(base.fixtures ?? []), ...(frontmatter.fixtures ?? [])],\n  };\n}\n\n/**\n * Helper for typed config files.\n */\nexport function defineConfig(config: TryscriptConfig): TryscriptConfig {\n  return config;\n}\n","import { parse as parseYaml } from 'yaml';\nimport type { TestConfig, TestBlock, TestFile } from './types.js';\n\n/** Regex to match YAML frontmatter at the start of a file */\nconst FRONTMATTER_REGEX = /^---\\r?\\n([\\s\\S]*?)\\r?\\n---\\r?\\n/;\n\n/** Regex to match fenced code blocks with console/bash info string */\nconst CODE_BLOCK_REGEX = /```(console|bash)\\r?\\n([\\s\\S]*?)```/g;\n\n/** Regex to match markdown headings (for test names) */\nconst HEADING_REGEX = /^#+\\s+(?:Test:\\s*)?(.+)$/m;\n\n/** Regex to match skip annotation in heading or nearby HTML comment */\nconst SKIP_ANNOTATION_REGEX = /<!--\\s*skip\\s*-->/i;\n\n/** Regex to match only annotation in heading or nearby HTML comment */\nconst ONLY_ANNOTATION_REGEX = /<!--\\s*only\\s*-->/i;\n\n/**\n * Parse a .tryscript.md file into structured test data.\n */\nexport function parseTestFile(content: string, filePath: string): TestFile {\n  const rawContent = content;\n  let config: TestConfig = {};\n  let body = content;\n\n  // Extract frontmatter if present\n  const frontmatterMatch = FRONTMATTER_REGEX.exec(content);\n  if (frontmatterMatch) {\n    const yamlContent = frontmatterMatch[1] ?? '';\n    config = parseYaml(yamlContent) as TestConfig;\n    body = content.slice(frontmatterMatch[0].length);\n  }\n\n  // Parse all console blocks\n  const blocks: TestBlock[] = [];\n\n  // Reset regex lastIndex\n  CODE_BLOCK_REGEX.lastIndex = 0;\n\n  let match: RegExpExecArray | null;\n  while ((match = CODE_BLOCK_REGEX.exec(body)) !== null) {\n    const blockContent = match[2] ?? '';\n    const blockStart = match.index;\n\n    // Find the line number (1-indexed)\n    const precedingContent = content.slice(0, content.indexOf(match[0]));\n    const lineNumber = precedingContent.split('\\n').length;\n\n    // Look for a heading before this block (for test name)\n    const contentBefore = body.slice(0, blockStart);\n    const lastHeadingMatch = [\n      ...contentBefore.matchAll(new RegExp(HEADING_REGEX.source, 'gm')),\n    ].pop();\n    const name = lastHeadingMatch?.[1]?.trim();\n\n    // Check for skip/only annotations in the heading line or nearby comments\n    const headingContext = lastHeadingMatch\n      ? contentBefore.slice(contentBefore.lastIndexOf(lastHeadingMatch[0]))\n      : '';\n    const skip = SKIP_ANNOTATION_REGEX.test(headingContext);\n    const only = ONLY_ANNOTATION_REGEX.test(headingContext);\n\n    // Parse the block content\n    const parsed = parseBlockContent(blockContent);\n    if (parsed) {\n      blocks.push({\n        name,\n        command: parsed.command,\n        expectedOutput: parsed.expectedOutput,\n        expectedStderr: parsed.expectedStderr,\n        expectedExitCode: parsed.expectedExitCode,\n        lineNumber,\n        rawContent: match[0],\n        skip,\n        only,\n      });\n    }\n  }\n\n  return { path: filePath, config, blocks, rawContent };\n}\n\n/**\n * Parse the content of a single console block.\n */\nfunction parseBlockContent(content: string): {\n  command: string;\n  expectedOutput: string;\n  expectedStderr?: string;\n  expectedExitCode: number;\n} | null {\n  const lines = content.split('\\n');\n  const commandLines: string[] = [];\n  const outputLines: string[] = [];\n  const stderrLines: string[] = [];\n  let expectedExitCode = 0;\n  let inCommand = false;\n\n  for (const line of lines) {\n    if (line.startsWith('$ ')) {\n      // Start of a command\n      inCommand = true;\n      commandLines.push(line.slice(2));\n    } else if (line.startsWith('> ') && inCommand) {\n      // Continuation of a multi-line command\n      commandLines.push(line.slice(2));\n    } else if (line.startsWith('? ')) {\n      // Exit code specification\n      inCommand = false;\n      expectedExitCode = parseInt(line.slice(2).trim(), 10);\n    } else if (line.startsWith('! ')) {\n      // Stderr line (prefixed with !)\n      inCommand = false;\n      stderrLines.push(line.slice(2));\n    } else {\n      // Output line (stdout or combined)\n      inCommand = false;\n      outputLines.push(line);\n    }\n  }\n\n  if (commandLines.length === 0) {\n    return null;\n  }\n\n  // Join command lines, handling shell continuations\n  let command = '';\n  for (let i = 0; i < commandLines.length; i++) {\n    const line = commandLines[i] ?? '';\n    if (line.endsWith('\\\\')) {\n      command += line.slice(0, -1) + ' ';\n    } else {\n      command += line;\n      if (i < commandLines.length - 1) {\n        command += ' ';\n      }\n    }\n  }\n\n  // Join output lines, preserving blank lines but trimming trailing empty lines\n  let expectedOutput = outputLines.join('\\n');\n  expectedOutput = expectedOutput.replace(/\\n+$/, '');\n  if (expectedOutput) {\n    expectedOutput += '\\n';\n  }\n\n  // Join stderr lines if any\n  let expectedStderr: string | undefined;\n  if (stderrLines.length > 0) {\n    expectedStderr = stderrLines.join('\\n');\n    expectedStderr = expectedStderr.replace(/\\n+$/, '');\n    if (expectedStderr) {\n      expectedStderr += '\\n';\n    }\n  }\n\n  return { command: command.trim(), expectedOutput, expectedStderr, expectedExitCode };\n}\n","import { spawn } from 'node:child_process';\nimport { mkdtemp, realpath, rm, cp } from 'node:fs/promises';\nimport { tmpdir } from 'node:os';\nimport { join, dirname, resolve, basename } from 'node:path';\nimport treeKill from 'tree-kill';\nimport type { TestBlock, TestBlockResult } from './types.js';\nimport type { TryscriptConfig, Fixture } from './config.js';\n\n/** Default timeout in milliseconds */\nconst DEFAULT_TIMEOUT = 30_000;\n\n/**\n * Execution context for a test file.\n * Created once per file, contains directory paths and config.\n */\nexport interface ExecutionContext {\n  /** Temporary directory for this test file (resolved, no symlinks) */\n  tempDir: string;\n  /** Directory containing the test file */\n  testDir: string;\n  /** Working directory for command execution */\n  cwd: string;\n  /** Whether running in sandbox mode */\n  sandbox: boolean;\n  /** Environment variables */\n  env: Record<string, string>;\n  /** Timeout per command */\n  timeout: number;\n  /** Before hook script */\n  before?: string;\n  /** After hook script */\n  after?: string;\n  /** Whether before hook has been run */\n  beforeRan?: boolean;\n}\n\n/**\n * Normalize fixture config to Fixture object.\n */\nfunction normalizeFixture(fixture: string | Fixture): Fixture {\n  if (typeof fixture === 'string') {\n    return { source: fixture };\n  }\n  return fixture;\n}\n\n/**\n * Setup fixtures by copying files to sandbox directory.\n */\nasync function setupFixtures(\n  fixtures: (string | Fixture)[] | undefined,\n  testDir: string,\n  sandboxDir: string,\n): Promise<void> {\n  if (!fixtures || fixtures.length === 0) {\n    return;\n  }\n\n  for (const f of fixtures) {\n    const fixture = normalizeFixture(f);\n    const src = resolve(testDir, fixture.source);\n    const destName = fixture.dest ?? basename(fixture.source);\n    const dst = resolve(sandboxDir, destName);\n    await cp(src, dst, { recursive: true });\n  }\n}\n\n/**\n * Create an execution context for a test file.\n * @param config - Test configuration\n * @param testFilePath - Path to the test file\n * @param coverageEnv - Optional coverage environment variables (e.g., NODE_V8_COVERAGE)\n */\nexport async function createExecutionContext(\n  config: TryscriptConfig,\n  testFilePath: string,\n  coverageEnv?: Record<string, string>,\n): Promise<ExecutionContext> {\n  // Create temp directory and resolve symlinks (e.g., /var -> /private/var on macOS)\n  // This ensures [CWD] and [ROOT] patterns match pwd output\n  const rawTempDir = await mkdtemp(join(tmpdir(), 'tryscript-'));\n  const tempDir = await realpath(rawTempDir);\n\n  // Resolve test file directory for portable test commands\n  const testDir = resolve(dirname(testFilePath));\n\n  // Determine working directory based on sandbox config\n  let cwd: string;\n  let sandbox = false;\n\n  if (config.sandbox === true) {\n    // Empty sandbox: run in temp directory\n    cwd = tempDir;\n    sandbox = true;\n  } else if (typeof config.sandbox === 'string') {\n    // Copy directory to sandbox: copy source to temp, run in temp\n    const srcPath = resolve(testDir, config.sandbox);\n    await cp(srcPath, tempDir, { recursive: true });\n    cwd = tempDir;\n    sandbox = true;\n  } else if (config.cwd) {\n    // Run in specified directory (relative to test file)\n    cwd = resolve(testDir, config.cwd);\n  } else {\n    // Default: run in test file directory\n    cwd = testDir;\n  }\n\n  // Copy additional fixtures to sandbox (only if sandbox enabled)\n  if (sandbox && config.fixtures) {\n    await setupFixtures(config.fixtures, testDir, tempDir);\n  }\n\n  const ctx: ExecutionContext = {\n    tempDir,\n    testDir,\n    cwd,\n    sandbox,\n    env: {\n      ...process.env,\n      ...config.env,\n      ...coverageEnv,\n      // Disable colors by default for deterministic output\n      NO_COLOR: config.env?.NO_COLOR ?? '1',\n      FORCE_COLOR: '0',\n      // Provide test directory for portable test commands\n      TRYSCRIPT_TEST_DIR: testDir,\n    } as Record<string, string>,\n    timeout: config.timeout ?? DEFAULT_TIMEOUT,\n    before: config.before,\n    after: config.after,\n  };\n\n  return ctx;\n}\n\n/**\n * Clean up execution context (remove temp directory).\n */\nexport async function cleanupExecutionContext(ctx: ExecutionContext): Promise<void> {\n  await rm(ctx.tempDir, { recursive: true, force: true });\n}\n\n/**\n * Run the before hook if it hasn't run yet.\n */\nexport async function runBeforeHook(ctx: ExecutionContext): Promise<void> {\n  if (ctx.before && !ctx.beforeRan) {\n    ctx.beforeRan = true;\n    await executeCommand(ctx.before, ctx);\n  }\n}\n\n/**\n * Run the after hook.\n */\nexport async function runAfterHook(ctx: ExecutionContext): Promise<void> {\n  if (ctx.after) {\n    await executeCommand(ctx.after, ctx);\n  }\n}\n\n/**\n * Run a single test block and return the result.\n */\nexport async function runBlock(block: TestBlock, ctx: ExecutionContext): Promise<TestBlockResult> {\n  const startTime = Date.now();\n\n  // Handle skip annotation\n  if (block.skip) {\n    return {\n      block,\n      passed: true,\n      actualOutput: '',\n      actualExitCode: 0,\n      duration: 0,\n      skipped: true,\n    };\n  }\n\n  try {\n    // Run before hook if this is the first test\n    await runBeforeHook(ctx);\n\n    // Execute command directly (shell handles $VAR expansion)\n    const { output, stdout, stderr, exitCode } = await executeCommand(block.command, ctx);\n\n    const duration = Date.now() - startTime;\n\n    return {\n      block,\n      passed: true, // Matching handled separately\n      actualOutput: output,\n      actualStdout: stdout,\n      actualStderr: stderr,\n      actualExitCode: exitCode,\n      duration,\n    };\n  } catch (error) {\n    const duration = Date.now() - startTime;\n    const message = error instanceof Error ? error.message : String(error);\n\n    return {\n      block,\n      passed: false,\n      actualOutput: '',\n      actualExitCode: -1,\n      duration,\n      error: message,\n    };\n  }\n}\n\n/** Command execution result with separate stdout/stderr */\ninterface CommandResult {\n  output: string;\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n}\n\n/**\n * Execute a command and capture output.\n */\nasync function executeCommand(command: string, ctx: ExecutionContext): Promise<CommandResult> {\n  return new Promise((resolve, reject) => {\n    const proc = spawn(command, {\n      shell: true,\n      cwd: ctx.cwd,\n      env: ctx.env as NodeJS.ProcessEnv,\n      // Pipe both to capture\n      stdio: ['ignore', 'pipe', 'pipe'],\n    });\n\n    const combinedChunks: { data: Buffer; type: 'stdout' | 'stderr' }[] = [];\n    const stdoutChunks: Buffer[] = [];\n    const stderrChunks: Buffer[] = [];\n\n    // Capture data as it comes in to preserve order\n    proc.stdout.on('data', (data: Buffer) => {\n      combinedChunks.push({ data, type: 'stdout' });\n      stdoutChunks.push(data);\n    });\n    proc.stderr.on('data', (data: Buffer) => {\n      combinedChunks.push({ data, type: 'stderr' });\n      stderrChunks.push(data);\n    });\n\n    const timeoutId = setTimeout(() => {\n      if (proc.pid) {\n        treeKill(proc.pid, 'SIGKILL');\n      }\n      reject(new Error(`Command timed out after ${ctx.timeout}ms`));\n    }, ctx.timeout);\n\n    proc.on('close', (code) => {\n      clearTimeout(timeoutId);\n      const output = Buffer.concat(combinedChunks.map((c) => c.data)).toString('utf-8');\n      const stdout = Buffer.concat(stdoutChunks).toString('utf-8');\n      const stderr = Buffer.concat(stderrChunks).toString('utf-8');\n      resolve({\n        output,\n        stdout,\n        stderr,\n        exitCode: code ?? 0,\n      });\n    });\n\n    proc.on('error', (err) => {\n      clearTimeout(timeoutId);\n      reject(err);\n    });\n  });\n}\n","import stripAnsi from 'strip-ansi';\n\n/**\n * Escape special regex characters in a string.\n */\nfunction escapeRegex(str: string): string {\n  return str.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n// Marker prefix for patterns (uses Unicode private use chars that won't appear in normal output)\nconst MARKER = '\\uE000';\n\n/**\n * Convert expected output with elision patterns to a regex.\n *\n * Handles (matching trycmd):\n * - [..] — matches any characters on the same line (trycmd: [^\\n]*?)\n * - ... — matches zero or more complete lines (trycmd: \\n(([^\\n]*\\n)*)?)\n * - [EXE] — matches .exe on Windows, empty otherwise\n * - [ROOT] — replaced with test root directory (pre-processed)\n * - [CWD] — replaced with current working directory (pre-processed)\n * - Custom [NAME] patterns from config (trycmd: TestCases::insert_var)\n */\nfunction patternToRegex(\n  expected: string,\n  customPatterns: Record<string, string | RegExp> = {},\n): RegExp {\n  // Build a map of markers to their regex replacements\n  const replacements = new Map<string, string>();\n  let markerIndex = 0;\n\n  const getMarker = (): string => {\n    return `${MARKER}${markerIndex++}${MARKER}`;\n  };\n\n  let processed = expected;\n\n  // Replace [..] with marker\n  const dotdotMarker = getMarker();\n  replacements.set(dotdotMarker, '[^\\\\n]*');\n  processed = processed.replaceAll('[..]', dotdotMarker);\n\n  // Replace ... (followed by newline) with marker\n  const ellipsisMarker = getMarker();\n  replacements.set(ellipsisMarker, '(?:[^\\\\n]*\\\\n)*');\n  processed = processed.replace(/\\.\\.\\.\\n/g, ellipsisMarker);\n\n  // Replace [EXE] with marker\n  const exeMarker = getMarker();\n  const exe = process.platform === 'win32' ? '\\\\.exe' : '';\n  replacements.set(exeMarker, exe);\n  processed = processed.replaceAll('[EXE]', exeMarker);\n\n  // Replace custom patterns with markers\n  for (const [name, pattern] of Object.entries(customPatterns)) {\n    const placeholder = `[${name}]`;\n    const patternStr = pattern instanceof RegExp ? pattern.source : pattern;\n    const marker = getMarker();\n    replacements.set(marker, `(${patternStr})`);\n    processed = processed.replaceAll(placeholder, marker);\n  }\n\n  // Escape special regex characters\n  let regex = escapeRegex(processed);\n\n  // Restore markers to their regex replacements\n  for (const [marker, replacement] of replacements) {\n    regex = regex.replaceAll(escapeRegex(marker), replacement);\n  }\n\n  // Match the entire string (dotall mode for . to match newlines if needed)\n  return new RegExp(`^${regex}$`, 's');\n}\n\n/**\n * Pre-process expected output to replace path placeholders with actual paths.\n * This happens BEFORE pattern matching.\n */\nfunction preprocessPaths(expected: string, context: { root: string; cwd: string }): string {\n  let result = expected;\n  // Normalize paths for comparison (use forward slashes)\n  const normalizedRoot = context.root.replace(/\\\\/g, '/');\n  const normalizedCwd = context.cwd.replace(/\\\\/g, '/');\n  result = result.replaceAll('[ROOT]', normalizedRoot);\n  result = result.replaceAll('[CWD]', normalizedCwd);\n  return result;\n}\n\n/**\n * Normalize actual output for comparison.\n * - Remove ANSI escape codes (colors, etc.)\n * - Normalize line endings to \\n\n * - Normalize paths (Windows backslashes to forward slashes)\n * - Trim trailing whitespace from lines\n * - Ensure single trailing newline\n */\nexport function normalizeOutput(output: string): string {\n  // Remove ANSI escape codes first\n  let normalized = stripAnsi(output);\n\n  normalized = normalized\n    .replace(/\\r\\n/g, '\\n')\n    .replace(/\\r/g, '\\n')\n    .split('\\n')\n    .map((line) => line.trimEnd())\n    .join('\\n')\n    .replace(/\\n+$/, '\\n');\n\n  // Handle empty output\n  if (normalized === '\\n') {\n    normalized = '';\n  }\n\n  return normalized;\n}\n\n/**\n * Check if actual output matches expected pattern.\n */\nexport function matchOutput(\n  actual: string,\n  expected: string,\n  context: { root: string; cwd: string },\n  customPatterns: Record<string, string | RegExp> = {},\n): boolean {\n  const normalizedActual = normalizeOutput(actual);\n  const normalizedExpected = normalizeOutput(expected);\n\n  // Empty expected matches empty actual\n  if (normalizedExpected === '' && normalizedActual === '') {\n    return true;\n  }\n\n  const preprocessed = preprocessPaths(normalizedExpected, context);\n  const regex = patternToRegex(preprocessed, customPatterns);\n  return regex.test(normalizedActual);\n}\n","// Public API exports\n\n// Version constant (injected at build time)\ndeclare const __VERSION__: string;\nexport const VERSION: string = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'development';\n\n// Config helper\nexport { defineConfig } from './lib/config.js';\nexport type { TryscriptConfig } from './lib/config.js';\n\n// Types\nexport type {\n  TestConfig,\n  TestBlock,\n  TestFile,\n  TestBlockResult,\n  TestFileResult,\n  TestRunSummary,\n  CoverageConfig,\n  CoverageContext,\n} from './lib/types.js';\n\n// Core functions (for programmatic use)\nexport { parseTestFile } from './lib/parser.js';\nexport { runBlock, createExecutionContext, cleanupExecutionContext } from './lib/runner.js';\nexport type { ExecutionContext } from './lib/runner.js';\nexport { matchOutput, normalizeOutput } from './lib/matcher.js';\n"],"mappings":"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"}

package/docs/tryscript-reference.md

@@ -1,163 +1,481 @@
-# tryscript Quick Reference
+# tryscript Reference
 
-Concise syntax reference for writing tryscript test files.
+Complete reference for writing tryscript golden tests. This document covers all syntax,
+configuration, and patterns needed to write accurate CLI tests on the first try.
 
-## Test File Format
+## Overview
 
-Test files use `.tryscript.md` extension. Each file contains Markdown with console code blocks:
+Tryscript is a markdown-based CLI golden testing format. Test files are markdown documents
+with embedded console code blocks specifying commands and expected output.
 
-```markdown
-# Test: Description
+**Design Philosophy:**
+- **Shell delegation**: Commands run in a real shell with full shell features
+- **Markdown-first**: Test files are valid markdown, readable as documentation
+- **Output matching**: Patterns like `[..]` match variable output; they're not for commands
 
-\`\`\`console
-$ command
-expected output
-? exit_code
-\`\`\`
-```
+## Quick Start Example
 
-## Basic Example
+````markdown
+---
+sandbox: true
+env:
+  NO_COLOR: "1"
+---
 
-```markdown
-# Test: Echo command
+# Test: Basic echo
 
-\`\`\`console
+```console
 $ echo "hello world"
 hello world
 ? 0
-\`\`\`
 ```
 
-## Exit Codes
+# Test: Command with variable output
+
+```console
+$ date +%Y
+[..]
+? 0
+```
+````
+
+## Test File Structure
+
+```
+┌──────────────────────────────────────┐
+│ ---                                  │  YAML Frontmatter (optional)
+│ env:                                 │  - Configuration
+│   MY_VAR: value                      │  - Environment variables
+│ sandbox: true                        │  - Patterns
+│ ---                                  │
+├──────────────────────────────────────┤
+│ # Test: Description                  │  Test heading (# or ##)
+│                                      │
+│ ```console                           │  Test block
+│ $ command --flag                     │  - Command starts with $
+│ expected output                      │  - Expected stdout follows
+│ ? 0                                  │  - Exit code (optional, default 0)
+│ ```                                  │
+└──────────────────────────────────────┘
+```
+
+## Command Block Syntax
+
+```
+$ command [arguments...]     # Command to execute (required)
+> continuation line          # Multi-line command continuation
+expected output              # Expected stdout (line by line)
+! stderr line                # Expected stderr (when separating streams)
+? exit_code                  # Expected exit code (default: 0)
+```
 
-Use `? N` to specify expected exit code:
+### Examples
 
+**Simple command:**
+```console
+$ echo "hello"
+hello
+? 0
+```
+
+**Non-zero exit code:**
 ```console
 $ exit 42
 ? 42
 ```
 
+**Multi-line command:**
+```console
+$ ls -la | \
+> grep ".md" | \
+> wc -l
+5
+```
+
+**Stderr handling:**
+```console
+$ cat nonexistent 2>&1
+cat: nonexistent: No such file or directory
+? 1
+```
+
+**Separate stderr assertion:**
+```console
+$ ./script.sh
+stdout line
+! stderr line
+? 0
+```
+
 ## Elision Patterns
 
-| Pattern  | Matches                          | Example               |
-| -------- | -------------------------------- | --------------------- |
-| `[..]`   | Any characters on current line   | `Built in [..]ms`     |
-| `...`    | Zero or more complete lines      | `...\nDone`           |
-| `[EXE]`  | `.exe` on Windows, empty on Unix | `my-cli[EXE]`         |
-| `[ROOT]` | Test root directory              | `[ROOT]/output.txt`   |
-| `[CWD]`  | Current working directory        | `[CWD]/file.txt`      |
+Patterns in expected output match variable content:
+
+| Pattern | Matches | Example |
+|---------|---------|---------|
+| `[..]` | Any text on a single line | `Built in [..]ms` |
+| `...` | Zero or more complete lines | `...\nDone` |
+| `[CWD]` | Current working directory | `[CWD]/output.txt` |
+| `[ROOT]` | Test file directory | `[ROOT]/fixtures/` |
+| `[EXE]` | `.exe` on Windows, empty otherwise | `my-cli[EXE]` |
+| `[PATTERN]` | Custom pattern from config | User-defined regex |
+
+### Pattern Examples
+
+**Single-line wildcard:**
+```console
+$ date
+[..]
+? 0
+```
+
+**Multi-line wildcard:**
+```console
+$ ls -la
+total [..]
+...
+-rw-r--r-- 1 user user [..] README.md
+```
+
+**Custom pattern:**
+```yaml
+patterns:
+  VERSION: '\d+\.\d+\.\d+'
+```
+```console
+$ my-cli --version
+my-cli version [VERSION]
+```
 
-## YAML Frontmatter
+## Configuration (Frontmatter)
 
-Configure test behavior at the top of the file:
+All options are optional. Place at the top of the file:
 
 ```yaml
 ---
-bin: ./my-cli
-env:
+cwd: ./subdir              # Working directory (relative to test file)
+sandbox: true              # Run in isolated temp directory
+env:                       # Environment variables
   NO_COLOR: "1"
-timeout: 5000
-patterns:
-  VERSION: "\\d+\\.\\d+\\.\\d+"
+  MY_VAR: value
+timeout: 5000              # Command timeout in milliseconds
+patterns:                  # Custom elision patterns
+  UUID: '[0-9a-f]{8}-...'
+fixtures:                  # Files to copy to sandbox
+  - data/input.txt
+before: npm run build      # Run before first test
+after: rm -rf ./cache      # Run after all tests
 ---
 ```
 
-### Config Options
+### Config Options Reference
 
-| Option     | Type     | Description                           |
-| ---------- | -------- | ------------------------------------- |
-| `bin`      | string   | Path to CLI binary                    |
-| `env`      | object   | Environment variables                 |
-| `timeout`  | number   | Command timeout in milliseconds       |
-| `patterns` | object   | Custom regex patterns for `[NAME]`    |
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cwd` | path | `"."` | Working directory (relative to test file) |
+| `sandbox` | `boolean \| path` | `false` | Run in isolated temp directory |
+| `env` | `object` | `{}` | Environment variables passed to shell |
+| `timeout` | `number` | `30000` | Command timeout in milliseconds |
+| `patterns` | `object` | `{}` | Custom regex patterns for `[NAME]` |
+| `fixtures` | `array` | `[]` | Files to copy to sandbox |
+| `before` | `string` | - | Shell command before first test |
+| `after` | `string` | - | Shell command after all tests |
 
-## Custom Patterns
+## Sandbox Mode
 
-Define reusable patterns in frontmatter:
+Sandbox provides test isolation by running commands in a temporary directory:
+
+| Configuration | Behavior |
+|--------------|----------|
+| `sandbox: false` (default) | Commands run in `cwd` (test file dir) |
+| `sandbox: true` | Creates empty temp dir, commands run there |
+| `sandbox: ./fixtures` | Copies `./fixtures/` to temp dir, runs there |
+
+**When sandbox is enabled:**
+- Fresh temp directory created for each test file
+- Fixtures are copied before tests run
+- `[CWD]` matches the sandbox directory
+- Files created by tests don't pollute source
+
+### Sandbox with Fixtures
 
 ```yaml
-patterns:
-  VERSION: "\\d+\\.\\d+\\.\\d+"
-  UUID: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
+---
+sandbox: true
+fixtures:
+  - data/input.txt                 # Copies to sandbox/input.txt
+  - source: config/settings.json   # Copies to sandbox/custom.json
+    dest: custom.json
+---
 ```
 
-Use in output:
+## Environment Variables
+
+Use `env` to set variables. The **shell** handles `$VAR` expansion:
+
+```yaml
+env:
+  CLI: ./dist/cli.mjs
+  DEBUG: "true"
+```
 
 ```console
-$ my-cli --version
+$ $CLI --version
+1.0.0
+```
+
+**Important:** Variables are for the shell, not for output matching.
+
+## Test Annotations
+
+Control test execution with HTML comments:
+
+```markdown
+## This test is skipped <!-- skip -->
+
+## Only run this test <!-- only -->
+```
+
+| Annotation | Effect |
+|------------|--------|
+| `<!-- skip -->` | Test is skipped, marked as passed |
+| `<!-- only -->` | Only tests with this annotation run |
+
+## Complete Example
+
+Here's a complete test file demonstrating all features:
+
+````markdown
+---
+sandbox: true
+env:
+  NO_COLOR: "1"
+  CLI: ./dist/my-cli.mjs
+timeout: 5000
+patterns:
+  VERSION: '\d+\.\d+\.\d+'
+  TIMESTAMP: '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}'
+fixtures:
+  - test-data/config.json
+before: echo "Setup complete"
+---
+
+# CLI Golden Tests
+
+These tests validate the my-cli command-line tool.
+
+## Basic Commands
+
+# Test: Show version
+
+```console
+$ $CLI --version
 my-cli version [VERSION]
 ? 0
 ```
 
-## Multiple Commands
+# Test: Show help
 
-Multiple tests per file, each with its own heading:
+```console
+$ $CLI --help
+Usage: my-cli [options] [command]
 
-```markdown
-# Test: First test
+Options:
+  --version  Show version
+  --help     Show help
+...
+? 0
+```
+
+## Error Handling
+
+# Test: Missing required argument
 
-\`\`\`console
-$ echo one
-one
+```console
+$ $CLI process
+Error: missing required argument 'file'
+? 1
+```
+
+# Test: File not found
+
+```console
+$ $CLI process nonexistent.txt 2>&1
+Error: file not found: nonexistent.txt
+? 1
+```
+
+## Feature Tests
+
+# Test: Process config file
+
+```console
+$ $CLI process config.json
+Processing: config.json
+Done at [TIMESTAMP][..]
 ? 0
-\`\`\`
+```
 
-# Test: Second test
+# Test: Verbose output <!-- skip -->
 
-\`\`\`console
-$ echo two
-two
+```console
+$ $CLI --verbose process config.json
+[DEBUG] Loading config.json
+...
+Done
 ? 0
-\`\`\`
 ```
+````
 
 ## CLI Usage
 
 ```bash
-# Run all tests
-npx tryscript
+tryscript                    # Show help (same as --help)
+tryscript run [files...]     # Run golden tests
+tryscript docs               # Show this reference
+tryscript readme             # Show README
+```
+
+### Run Options
+
+| Option | Description |
+|--------|-------------|
+| `--update` | Update test files with actual output |
+| `--diff` / `--no-diff` | Show/hide diff on failure |
+| `--fail-fast` | Stop on first failure |
+| `--filter <pattern>` | Filter tests by name |
+| `--verbose` | Show detailed output |
+| `--quiet` | Suppress non-essential output |
+| `--coverage` | Enable code coverage collection (requires c8) |
+| `--coverage-dir <dir>` | Coverage output directory (default: coverage-tryscript) |
+| `--coverage-reporter <reporter...>` | Coverage reporters (default: text, html) |
+
+## Code Coverage
+
+Collect code coverage from subprocess execution using the `--coverage` flag:
+
+```bash
+# Basic coverage
+tryscript run --coverage tests/
+
+# Custom output directory
+tryscript run --coverage --coverage-dir my-coverage tests/
+
+# Custom reporters
+tryscript run --coverage --coverage-reporter text --coverage-reporter lcov tests/
+```
+
+Coverage uses [c8](https://github.com/bcoe/c8) and `NODE_V8_COVERAGE` to track code executed
+by spawned CLI processes. Install c8 as a dev dependency:
+
+```bash
+npm install -D c8
+```
 
-# Run specific files
-npx tryscript tests/foo.tryscript.md
+Configure coverage in `tryscript.config.ts`:
+
+```typescript
+import { defineConfig } from 'tryscript';
+
+export default defineConfig({
+  coverage: {
+    reportsDir: 'coverage-tryscript',
+    reporters: ['text', 'html'],
+    include: ['dist/**'],
+    src: 'src',
+  },
+});
+```
 
-# Update golden files
-npx tryscript --update
+## Best Practices
 
-# Filter tests by name
-npx tryscript --filter "pattern"
+### DO: Use shell features directly
 
-# Fail fast on first error
-npx tryscript --fail-fast
+```console
+$ echo "hello" | tr 'a-z' 'A-Z'
+HELLO
 
-# Verbose output
-npx tryscript --verbose
+$ cat file.txt 2>/dev/null || echo "not found"
+not found
 ```
 
-## Options
+### DO: Use env for CLI paths
+
+```yaml
+env:
+  BIN: ./dist/cli.mjs
+```
+```console
+$ $BIN --version
+1.0.0
+```
 
-| Option             | Description                              |
-| ------------------ | ---------------------------------------- |
-| `--update`         | Update golden files with actual output   |
-| `--diff`           | Show diff on failure (default: true)     |
-| `--no-diff`        | Hide diff on failure                     |
-| `--fail-fast`      | Stop on first failure                    |
-| `--filter <regex>` | Filter tests by name pattern             |
-| `--verbose`        | Show detailed output                     |
-| `--quiet`          | Suppress non-essential output            |
+### DO: Use sandbox for file operations
+
+```yaml
+sandbox: true
+```
+```console
+$ echo "test" > output.txt
+$ cat output.txt
+test
+```
+
+### DON'T: Use patterns in commands
+
+```console
+# ❌ WRONG: Patterns are for output matching only
+$ cat [CWD]/file.txt
+```
+
+### DON'T: Rely on exact timestamps or paths
+
+```console
+# ❌ WRONG: Exact match will fail
+$ date
+Mon Jan 3 12:34:56 UTC 2026
+
+# ✓ RIGHT: Use elision
+$ date
+[..]
+```
 
 ## Config File
 
-Create `tryscript.config.ts` in your project root:
+For project-wide settings, create `tryscript.config.ts`:
 
 ```typescript
 import { defineConfig } from 'tryscript';
 
 export default defineConfig({
-  bin: './dist/cli.js',
   env: { NO_COLOR: '1' },
   timeout: 30000,
   patterns: {
     VERSION: '\\d+\\.\\d+\\.\\d+',
+    UUID: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}',
   },
 });
 ```
+
+## Execution Model
+
+```
+Test File → Parse YAML + Blocks → Create Execution Context
+                                         │
+                    ┌────────────────────┴────────────────────┐
+                    │                                         │
+              sandbox: false                            sandbox: true
+              cwd = testDir/config.cwd                  cwd = /tmp/tryscript-xxx/
+                    │                                         │
+                    └────────────────────┬────────────────────┘
+                                         │
+                    spawn(command, { shell: true, cwd, env })
+                                         │
+                    Capture stdout + stderr → Match against expected
+```
+
+**Key points:**
+1. Commands run in a real shell (`shell: true`)
+2. Shell handles all variable expansion (`$VAR`)
+3. Patterns (`[..]`, `[CWD]`) only apply to output matching
+4. Sandbox creates isolated temp directory per test file