feat: add executable code fence support

Add ability to execute code fences with shebangs inline. Code fences
that start with a shebang (#!/usr/bin/env bun, #!/bin/bash, etc.) are
written to a temp file, made executable, and run during import expansion.

Changes:
- Add ExecutableCodeFenceAction type to imports-types.ts
- Update parser to handle variable-length fences (3+ backticks/tildes)
- Add EXECUTABLE_FENCE_PATTERN regex for shebang detection
- Implement processExecutableCodeFence in imports.ts
- Integrate with parallel execution dashboard
- Support dry-run mode for code fences
- Add comprehensive parser and integration tests

Author: johnlindquist

src/imports-parser.test.ts

@@ -647,6 +647,97 @@ describe('parseSymbolExtraction', () => {
   });
 });
 
+describe('executable code fence imports', () => {
+  it('parses executable code fence with shebang', () => {
+    const content = '```ts\n#!/usr/bin/env bun\nconsole.log("hello")\n```';
+    const actions = parseImports(content);
+    expect(actions).toHaveLength(1);
+    expect(actions[0]!.type).toBe('executable_code_fence');
+    const action = actions[0] as any;
+    expect(action.shebang).toBe('#!/usr/bin/env bun');
+    expect(action.language).toBe('ts');
+    expect(action.code).toBe('console.log("hello")');
+  });
+
+  it('parses executable code fence with sh shebang', () => {
+    const content = '```sh\n#!/bin/bash\necho "hello"\n```';
+    const actions = parseImports(content);
+    expect(actions).toHaveLength(1);
+    expect(actions[0]!.type).toBe('executable_code_fence');
+    const action = actions[0] as any;
+    expect(action.shebang).toBe('#!/bin/bash');
+    expect(action.language).toBe('sh');
+    expect(action.code).toBe('echo "hello"');
+  });
+
+  it('parses executable code fence with python shebang', () => {
+    const content = '```python\n#!/usr/bin/env python3\nprint("hello")\n```';
+    const actions = parseImports(content);
+    expect(actions).toHaveLength(1);
+    expect(actions[0]!.type).toBe('executable_code_fence');
+    const action = actions[0] as any;
+    expect(action.shebang).toBe('#!/usr/bin/env python3');
+    expect(action.language).toBe('python');
+  });
+
+  it('does NOT parse code fence without shebang', () => {
+    const content = '```ts\nconsole.log("hello")\n```';
+    const actions = parseImports(content);
+    // No shebang means it's just a regular code block, not executable
+    expect(actions).toHaveLength(0);
+  });
+
+  it('does NOT parse shebang that is not on first line of code', () => {
+    const content = '```ts\n// comment\n#!/usr/bin/env bun\nconsole.log("hello")\n```';
+    const actions = parseImports(content);
+    // Shebang must be on the first line after the fence
+    expect(actions).toHaveLength(0);
+  });
+
+  it('parses multiline code in executable fence', () => {
+    const content = '```ts\n#!/usr/bin/env bun\nconst x = 1;\nconsole.log(x);\nprocess.exit(0);\n```';
+    const actions = parseImports(content);
+    expect(actions).toHaveLength(1);
+    const action = actions[0] as any;
+    expect(action.code).toContain('const x = 1;');
+    expect(action.code).toContain('console.log(x);');
+    expect(action.code).toContain('process.exit(0);');
+  });
+
+  it('handles variable-length fences (4+ backticks)', () => {
+    const content = '````ts\n#!/usr/bin/env bun\nconsole.log("hello")\n````';
+    const actions = parseImports(content);
+    expect(actions).toHaveLength(1);
+    expect(actions[0]!.type).toBe('executable_code_fence');
+  });
+
+  it('preserves original match for replacement', () => {
+    const content = 'before\n```ts\n#!/usr/bin/env bun\nconsole.log("hello")\n```\nafter';
+    const actions = parseImports(content);
+    expect(actions).toHaveLength(1);
+    const action = actions[0] as any;
+    expect(action.original).toBe('```ts\n#!/usr/bin/env bun\nconsole.log("hello")\n```');
+    expect(action.index).toBe(7); // Position after "before\n"
+  });
+
+  it('parses multiple executable fences', () => {
+    const content = '```sh\n#!/bin/bash\necho 1\n```\n\n```ts\n#!/usr/bin/env bun\nconsole.log(2)\n```';
+    const actions = parseImports(content);
+    expect(actions).toHaveLength(2);
+    expect(actions[0]!.type).toBe('executable_code_fence');
+    expect(actions[1]!.type).toBe('executable_code_fence');
+  });
+
+  it('mixes executable fences with file imports', () => {
+    const content = '@./config.md\n\n```ts\n#!/usr/bin/env bun\nconsole.log("hello")\n```\n\n@./footer.md';
+    const actions = parseImports(content);
+    expect(actions).toHaveLength(3);
+    expect(actions[0]!.type).toBe('file');
+    expect(actions[1]!.type).toBe('executable_code_fence');
+    expect(actions[2]!.type).toBe('file');
+  });
+});
+
 describe('findSafeRanges', () => {
   it('returns full range for plain text', () => {
     const content = 'plain text content';

src/imports-parser.ts

@@ -13,6 +13,7 @@ import type {
   UrlImportAction,
   CommandImportAction,
   SymbolImportAction,
+  ExecutableCodeFenceAction,
 } from './imports-types';
 
 /**
@@ -32,27 +33,36 @@ export function findSafeRanges(content: string): Array<{ start: number; end: num
   let context: ScanContext = 'normal';
   let rangeStart = 0;
   let i = 0;
+  let fenceChar = '';
+  let fenceLen = 0;
 
   while (i < content.length) {
     if (context === 'normal') {
-      // Check for fenced code block start (``` or ~~~)
-      if (
-        (content[i] === '`' && content.slice(i, i + 3) === '```') ||
-        (content[i] === '~' && content.slice(i, i + 3) === '~~~')
-      ) {
-        // End current safe range before the fence
-        if (i > rangeStart) {
-          safeRanges.push({ start: rangeStart, end: i });
+      // Check for fenced code block start (3+ backticks or tildes)
+      if (content[i] === '`' || content[i] === '~') {
+        const char = content[i];
+        let len = 0;
+        let j = i;
+        while (j < content.length && content[j] === char) {
+          len++;
+          j++;
         }
-        context = 'fenced_code';
-        // Skip the opening fence and any language identifier on the same line
-        const fenceChar = content[i];
-        i += 3;
-        // Skip to end of line (the info string after ```)
-        while (i < content.length && content[i] !== '\n') {
-          i++;
+
+        if (len >= 3) {
+          // It's a fence
+          if (i > rangeStart) {
+            safeRanges.push({ start: rangeStart, end: i });
+          }
+          context = 'fenced_code';
+          fenceChar = char;
+          fenceLen = len;
+          i += len;
+          // Skip info string
+          while (i < content.length && content[i] !== '\n') {
+            i++;
+          }
+          continue;
         }
-        continue;
       }
 
       // Check for inline code start (single backtick, not followed by another)
@@ -68,26 +78,30 @@ export function findSafeRanges(content: string): Array<{ start: number; end: num
 
       i++;
     } else if (context === 'fenced_code') {
-      // Look for closing fence (``` or ~~~)
-      // Must be at start of line (after newline or at start of content)
+      // Look for closing fence
       const atLineStart = i === 0 || content[i - 1] === '\n';
-      if (
-        atLineStart &&
-        ((content[i] === '`' && content.slice(i, i + 3) === '```') ||
-          (content[i] === '~' && content.slice(i, i + 3) === '~~~'))
-      ) {
-        // Skip the closing fence
-        i += 3;
-        // Skip to end of line
-        while (i < content.length && content[i] !== '\n') {
-          i++;
+      if (atLineStart && content[i] === fenceChar) {
+        let len = 0;
+        let j = i;
+        while (j < content.length && content[j] === fenceChar) {
+          len++;
+          j++;
         }
-        if (i < content.length) {
-          i++; // Skip the newline
+
+        if (len >= fenceLen) {
+          // Close it
+          i += len;
+          // Skip to end of line
+          while (i < content.length && content[i] !== '\n') {
+            i++;
+          }
+          if (i < content.length) {
+            i++; // Skip the newline
+          }
+          context = 'normal';
+          rangeStart = i;
+          continue;
         }
-        context = 'normal';
-        rangeStart = i;
-        continue;
       }
       i++;
     } else if (context === 'inline_code') {
@@ -152,6 +166,13 @@ const COMMAND_INLINE_PATTERN = /!(`+)([\s\S]+?)\1/g;
  */
 const URL_IMPORT_PATTERN = /@(https?:\/\/[^\s]+)/g;
 
+/**
+ * Pattern to match executable code fences
+ * Matches: ```lang\n#!shebang\ncode\n```
+ * Supports variable length fences.
+ */
+const EXECUTABLE_FENCE_PATTERN = /(`{3,})(.*?)\n(#![^\n]+)\n([\s\S]*?)\1/g;
+
 /**
  * Check if a path contains glob characters
  */
@@ -258,6 +279,22 @@ export function parseImports(content: string): ImportAction[] {
   // Find safe ranges where imports should be parsed (outside code blocks)
   const safeRanges = findSafeRanges(content);
 
+  // Identify starts of unsafe blocks (gaps between safe ranges)
+  // These are the only valid positions for executable code fences.
+  // This prevents execution of fences nested inside documentation blocks.
+  const unsafeStarts = new Set<number>();
+  if (safeRanges.length > 0) {
+    if (safeRanges[0].start > 0) unsafeStarts.add(0);
+    for (const range of safeRanges) {
+      if (range.end < content.length) {
+        unsafeStarts.add(range.end);
+      }
+    }
+  } else if (content.length > 0) {
+    // If content exists but no safe ranges, the whole thing is unsafe (a code block)
+    unsafeStarts.add(0);
+  }
+
   // Parse file imports (includes globs, line ranges, symbols)
   FILE_IMPORT_PATTERN.lastIndex = 0;
   let match;
@@ -302,6 +339,29 @@ export function parseImports(content: string): ImportAction[] {
     }
   }
 
+  // Parse executable code fences
+  // Must match a top-level code block (start of an unsafe gap)
+  EXECUTABLE_FENCE_PATTERN.lastIndex = 0;
+  while ((match = EXECUTABLE_FENCE_PATTERN.exec(content)) !== null) {
+    // Only process if the match aligns exactly with a known code block start
+    if (unsafeStarts.has(match.index)) {
+      const [fullMatch, fence, infoString, shebang, code] = match;
+      const language = infoString.trim().split(/\s+/)[0]; // Extract first word as language
+
+      if (shebang && code !== undefined) {
+        const action: ExecutableCodeFenceAction = {
+          type: 'executable_code_fence',
+          language: language || 'txt',
+          shebang,
+          code: code.trim(),
+          original: fullMatch,
+          index: match.index,
+        };
+        actions.push(action);
+      }
+    }
+  }
+
   // Sort by index to maintain order
   actions.sort((a, b) => a.index - b.index);
 

src/imports-types.ts

@@ -57,13 +57,24 @@ export interface SymbolImportAction {
   index: number;
 }
 
+/** Executable Code Fence Action */
+export interface ExecutableCodeFenceAction {
+  type: 'executable_code_fence';
+  shebang: string;      // "#!/usr/bin/env bun"
+  language: string;     // "ts", "js", "python"
+  code: string;         // Code content (without shebang)
+  original: string;     // Full match including fence markers
+  index: number;
+}
+
 /** Union of all import action types */
 export type ImportAction =
   | FileImportAction
   | GlobImportAction
   | UrlImportAction
   | CommandImportAction
-  | SymbolImportAction;
+  | SymbolImportAction
+  | ExecutableCodeFenceAction;
 
 /**
  * Resolved Import - Output of the resolver (Phase 2)

src/imports.test.ts

@@ -644,3 +644,62 @@ describe("parallel import resolution", () => {
     expect(result).toBe("Parent1 Child end1 Parent2 Child end2");
   });
 });
+
+// Executable code fence tests
+describe("executable code fences", () => {
+  test("executes bash code fence with shebang", async () => {
+    const content = '```sh\n#!/bin/bash\necho "hello from bash"\n```';
+    const result = await expandImports(content, testDir);
+    expect(result).toContain("hello from bash");
+    expect(result).toContain("{% raw %}");
+  });
+
+  test("executes bun/typescript code fence with shebang", async () => {
+    const content = '```ts\n#!/usr/bin/env bun\nconsole.log("hello from bun")\n```';
+    const result = await expandImports(content, testDir);
+    expect(result).toContain("hello from bun");
+  });
+
+  test("does NOT execute code fence without shebang", async () => {
+    const content = '```ts\nconsole.log("should not run")\n```';
+    const result = await expandImports(content, testDir);
+    // The code fence should remain as-is since it has no shebang
+    expect(result).toBe('```ts\nconsole.log("should not run")\n```');
+  });
+
+  test("handles code fence failure gracefully", async () => {
+    const content = '```sh\n#!/bin/bash\nexit 1\n```';
+    await expect(expandImports(content, testDir)).rejects.toThrow("Code fence failed");
+  });
+
+  test("code fence output is wrapped in raw block", async () => {
+    const content = '```sh\n#!/bin/bash\necho "{{ template syntax }}"\n```';
+    const result = await expandImports(content, testDir);
+    // Output should be protected from LiquidJS interpretation
+    expect(result).toContain("{% raw %}");
+    expect(result).toContain("{% endraw %}");
+    expect(result).toContain("{{ template syntax }}");
+  });
+
+  test("respects dry-run mode for code fences", async () => {
+    const content = '```sh\n#!/bin/bash\necho "should not run"\n```';
+    const result = await expandImports(content, testDir, new Set(), false, {
+      dryRun: true,
+    });
+    expect(result).toContain("Dry Run");
+    expect(result).toContain("Code fence not executed");
+  });
+
+  test("mixes code fence with file imports", async () => {
+    await Bun.write(join(testDir, "fence-file.md"), "File content");
+
+    const content = '@./fence-file.md\n\n```sh\n#!/bin/bash\necho "Command output"\n```';
+    const result = await expandImports(content, testDir);
+    expect(result).toContain("File content");
+    expect(result).toContain("Command output");
+  });
+
+  test("hasImports detects executable code fences", () => {
+    expect(hasImports('```sh\n#!/bin/bash\necho hi\n```')).toBe(true);
+  });
+});