Add {server} block support for dev server startup

Adds a new `{server}` code block annotation that marks a block as a
long-running server process. When verify encounters a {server} block, it
starts the server in the background with an auto-assigned port (via $PORT
env var), waits for the port to become available, then runs subsequent
blocks with $PORT in their environment.

New features:
- `{server}` annotation in markdown fenced code blocks
- `showboat server <file>` command to start a server from a document
- `--wait-port <port>` flag for verify and server commands to pin a port
- $PORT env var auto-assigned and propagated to all blocks
- `showboat extract` emits `showboat server` for server blocks

New files: exec/server.go (FreePort, WaitForPort, RunServer),
exec/server_test.go, demos/dev-server-startup.md

https://claude.ai/code/session_01YZQJXZoLT9ZM6t1JL72bN6

Author: claude

README.md

@@ -66,6 +66,7 @@ Usage:
   showboat pop <file>                      Remove the most recent entry
   showboat verify <file> [--output <new>]  Re-run and diff all code blocks
   showboat extract <file> [--filename <name>]  Emit commands to recreate file
+  showboat server <file> [--wait-port <port>]  Start {server} block from doc
 
 Global Options:
   --workdir <dir>   Set working directory for code execution (default: current)
@@ -97,17 +98,46 @@ Pop:
   produces an error that shouldn't remain in the document.
 
 Verify:
-  Re-runs every code block (skipping image blocks) and compares actual output
-  against the recorded output. Prints diffs and exits with code 1 if any output
-  has changed; exits 0 if everything matches. Use --output <file> to write an
-  updated copy of the document with the new outputs without modifying the
-  original.
+  Re-runs every code block (skipping image and server blocks) and compares
+  actual output against the recorded output. Prints diffs and exits with code 1
+  if any output has changed; exits 0 if everything matches. Use --output <file>
+  to write an updated copy of the document with the new outputs without
+  modifying the original.
+
+  When a document contains a {server} block, verify automatically starts the
+  server before running subsequent code blocks. A free port is assigned and
+  made available as $PORT. Use --wait-port <port> to pin a specific port
+  instead of auto-assigning one.
 
 Extract:
   Parses a document and prints the sequence of showboat CLI commands (one per
   line) that would recreate it from scratch. Output blocks are omitted since
-  they are regenerated by "exec". Use --filename <name> to substitute a
-  different filename in the emitted commands.
+  they are regenerated by "exec". Server blocks emit "showboat server" commands.
+  Use --filename <name> to substitute a different filename in the emitted
+  commands.
+
+Server:
+  Starts the first {server} code block from a document as a foreground process.
+  A free port is auto-assigned and made available as $PORT in the server
+  command's environment. The assigned port is printed to stdout. The server
+  runs until interrupted (Ctrl-C).
+
+  Use --wait-port <port> to pin a specific port instead of auto-assigning one.
+  This is useful when the server command does not use $PORT.
+
+    $ showboat server demo.md
+    Server running on port 54321
+
+  In the markdown, a server block looks like:
+
+    ```bash {server}
+    python3 -m http.server $PORT
+    ```
+
+  The $PORT variable is optional. If the server command uses a hardcoded port,
+  pass --wait-port to tell showboat which port to wait for:
+
+    $ showboat server demo.md --wait-port 8080
 
 Stdin:
   Commands accept input from stdin when the text/code argument is omitted.
@@ -240,6 +270,33 @@ Hello from Python
 showboat verify demo.md
 ```
 
+## Server blocks
+
+Documents can include `{server}` code blocks for long-running server processes. When `showboat verify` encounters a server block, it starts the server in the background, waits for its port, and makes `$PORT` available to all subsequent blocks:
+
+````markdown
+```bash {server}
+python3 -m http.server $PORT
+```
+
+```bash
+curl -s http://localhost:$PORT/
+```
+````
+
+Use `showboat server` to start a server block standalone:
+
+```bash
+showboat server demo.md
+# Server running on port 54321
+```
+
+If the server command hardcodes a port instead of using `$PORT`, pass `--wait-port`:
+
+```bash
+showboat server demo.md --wait-port 8080
+```
+
 ## Extracting
 
 `showboat extract` emits the sequence of commands that would recreate a document from scratch:

cmd/extract.go

@@ -35,6 +35,8 @@ func Extract(file, outputFile string) ([]string, error) {
 		case markdown.CodeBlock:
 			if b.IsImage {
 				commands = append(commands, fmt.Sprintf("showboat image %s %s", quotedTarget, shellQuote(b.Code)))
+			} else if b.IsServer {
+				commands = append(commands, fmt.Sprintf("showboat server %s %s %s", quotedTarget, b.Lang, shellQuote(b.Code)))
 			} else {
 				commands = append(commands, fmt.Sprintf("showboat exec %s %s %s", quotedTarget, b.Lang, shellQuote(b.Code)))
 			}

cmd/extract_test.go

@@ -1,9 +1,12 @@
 package cmd
 
 import (
+	"os"
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/simonw/showboat/markdown"
 )
 
 func TestExtract(t *testing.T) {
@@ -68,6 +71,48 @@ func TestExtractOutputOverride(t *testing.T) {
 	}
 }
 
+func TestExtractServerBlock(t *testing.T) {
+	dir := t.TempDir()
+	file := filepath.Join(dir, "demo.md")
+
+	// Write a document with a server block
+	blocks := []markdown.Block{
+		markdown.TitleBlock{Title: "Server Demo", Timestamp: "2026-02-14T00:00:00Z", Version: "dev"},
+		markdown.CommentaryBlock{Text: "Start a server."},
+		markdown.CodeBlock{Lang: "bash", Code: "python3 -m http.server $PORT", IsServer: true},
+		markdown.CodeBlock{Lang: "bash", Code: "curl -s http://localhost:$PORT/"},
+	}
+
+	f, err := os.Create(file)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := markdown.Write(f, blocks); err != nil {
+		f.Close()
+		t.Fatal(err)
+	}
+	f.Close()
+
+	commands, err := Extract(file, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Should have: init, note, server, exec
+	found := false
+	for _, c := range commands {
+		if strings.Contains(c, "showboat server") {
+			found = true
+			if !strings.Contains(c, "python3 -m http.server $PORT") {
+				t.Errorf("expected server command to contain code, got: %s", c)
+			}
+		}
+	}
+	if !found {
+		t.Errorf("expected a 'showboat server' command, got: %v", commands)
+	}
+}
+
 func TestExtractShellQuote(t *testing.T) {
 	tests := []struct {
 		input    string

cmd/verify.go

@@ -2,7 +2,10 @@ package cmd
 
 import (
 	"fmt"
+	"os"
+	"strconv"
 	"strings"
+	"time"
 
 	execpkg "github.com/simonw/showboat/exec"
 	"github.com/simonw/showboat/markdown"
@@ -28,21 +31,55 @@ func (d Diff) String() string {
 // If outputFile is non-empty, an updated copy of the document is written there.
 // If workdir is non-empty, code blocks are executed in that directory.
 func Verify(file, outputFile, workdir string) ([]Diff, error) {
+	return VerifyWithPort(file, outputFile, workdir, 0)
+}
+
+// VerifyWithPort re-executes all code blocks and compares outputs.
+// Server blocks are started as background processes with the given waitPort
+// (or an auto-assigned port if waitPort is 0). The PORT environment variable
+// is set for all blocks.
+func VerifyWithPort(file, outputFile, workdir string, waitPort int) ([]Diff, error) {
 	blocks, err := readBlocks(file)
 	if err != nil {
 		return nil, err
 	}
 
 	var diffs []Diff
+	var servers []*execpkg.ServerProcess
+	defer func() {
+		for _, s := range servers {
+			s.Stop()
+		}
+	}()
+
+	// Port for $PORT env var — assigned when a server block is found
+	port := waitPort
 
 	for i := 0; i < len(blocks); i++ {
 		cb, ok := blocks[i].(markdown.CodeBlock)
 		if !ok || cb.IsImage {
 			continue
 		}
 
-		// Execute the code block
-		output, _, err := execpkg.Run(cb.Lang, cb.Code, workdir)
+		if cb.IsServer {
+			// Assign a port if not already set
+			if port == 0 {
+				p, err := execpkg.FreePort()
+				if err != nil {
+					return nil, fmt.Errorf("finding free port for server block %d: %w", i, err)
+				}
+				port = p
+			}
+			proc, err := execpkg.RunServer(cb.Lang, cb.Code, workdir, port, 10*time.Second)
+			if err != nil {
+				return nil, fmt.Errorf("starting server block %d: %w", i, err)
+			}
+			servers = append(servers, proc)
+			continue
+		}
+
+		// Execute normal code block, with PORT in the environment if set
+		output, _, err := runWithPort(cb.Lang, cb.Code, workdir, port)
 		if err != nil {
 			return nil, fmt.Errorf("executing block %d: %w", i, err)
 		}
@@ -71,3 +108,48 @@ func Verify(file, outputFile, workdir string) ([]Diff, error) {
 
 	return diffs, nil
 }
+
+// runWithPort executes code with the PORT environment variable set.
+func runWithPort(lang, code, workdir string, port int) (string, int, error) {
+	if port == 0 {
+		return execpkg.Run(lang, code, workdir)
+	}
+	return execpkg.RunWithEnv(lang, code, workdir, []string{"PORT=" + strconv.Itoa(port)})
+}
+
+// Server starts a server process from a showboat document. It finds the first
+// {server} code block, starts it, and prints the port. If waitPort is non-zero,
+// it uses that port; otherwise it auto-assigns one.
+func Server(file, workdir string, waitPort int) (*execpkg.ServerProcess, error) {
+	blocks, err := readBlocks(file)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, block := range blocks {
+		cb, ok := block.(markdown.CodeBlock)
+		if !ok || !cb.IsServer {
+			continue
+		}
+
+		port := waitPort
+		if port == 0 {
+			p, err := execpkg.FreePort()
+			if err != nil {
+				return nil, fmt.Errorf("finding free port: %w", err)
+			}
+			port = p
+		}
+
+		// Set PORT so subsequent commands can use it
+		os.Setenv("PORT", strconv.Itoa(port))
+
+		proc, err := execpkg.RunServer(cb.Lang, cb.Code, workdir, port, 10*time.Second)
+		if err != nil {
+			return nil, fmt.Errorf("starting server: %w", err)
+		}
+		return proc, nil
+	}
+
+	return nil, fmt.Errorf("no {server} block found in %s", file)
+}

cmd/verify_test.go

@@ -1,10 +1,14 @@
 package cmd
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
+
+	execpkg "github.com/simonw/showboat/exec"
+	"github.com/simonw/showboat/markdown"
 )
 
 func TestVerifyPasses(t *testing.T) {
@@ -120,3 +124,73 @@ func TestVerifyWritesOutput(t *testing.T) {
 		t.Errorf("output file should not contain tampered output, got: %s", updatedContent)
 	}
 }
+
+func TestVerifyWithServerBlock(t *testing.T) {
+	dir := t.TempDir()
+	file := filepath.Join(dir, "demo.md")
+
+	// Get a free port
+	port, err := execpkg.FreePort()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Build a document with a server block and a curl block
+	blocks := []markdown.Block{
+		markdown.TitleBlock{Title: "Server Test", Timestamp: "2026-02-14T00:00:00Z", Version: "dev"},
+		markdown.CodeBlock{Lang: "bash", Code: "python3 -m http.server $PORT", IsServer: true},
+		markdown.CodeBlock{Lang: "bash", Code: fmt.Sprintf("curl -s http://localhost:%d/", port)},
+	}
+
+	f, err := os.Create(file)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := markdown.Write(f, blocks); err != nil {
+		f.Close()
+		t.Fatal(err)
+	}
+	f.Close()
+
+	// Verify should start the server, run the curl, and not error
+	diffs, err := Verify(file, "", "")
+	if err != nil {
+		t.Fatalf("Verify failed: %v", err)
+	}
+
+	// We don't check diffs content since the curl output is dynamic,
+	// but there should be no error (server started and was reachable)
+	_ = diffs
+}
+
+func TestVerifySkipsServerBlockExecution(t *testing.T) {
+	dir := t.TempDir()
+	file := filepath.Join(dir, "demo.md")
+
+	// Build a document with a server block followed by a normal block
+	blocks := []markdown.Block{
+		markdown.TitleBlock{Title: "Test", Timestamp: "2026-02-14T00:00:00Z", Version: "dev"},
+		markdown.CodeBlock{Lang: "bash", Code: "python3 -m http.server $PORT", IsServer: true},
+		markdown.CodeBlock{Lang: "bash", Code: "echo hello"},
+		markdown.OutputBlock{Content: "hello\n"},
+	}
+
+	f, err := os.Create(file)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := markdown.Write(f, blocks); err != nil {
+		f.Close()
+		t.Fatal(err)
+	}
+	f.Close()
+
+	diffs, err := Verify(file, "", "")
+	if err != nil {
+		t.Fatalf("Verify failed: %v", err)
+	}
+
+	if len(diffs) != 0 {
+		t.Errorf("expected no diffs, got %d: %v", len(diffs), diffs)
+	}
+}