How simonw/showboat works
1. Showboat is a single Go CLI that centers everything around one artifact: a Markdown document that is both human-readable documentation and a replayable execution log. The document contains commentary, executable code blocks, captured output blocks, and image references.
2. The command surface lives in main.go plus cmd/. The subcommands are init, note, exec, image, pop, verify, and extract, with a shared --workdir option. The CLI is the top-level boundary between the user and all other subsystems.
3. The Markdown document layer is in markdown/. It is responsible for parsing an existing showboat document into structured blocks, and writing those blocks back out. This layer is the core data model boundary: all command logic works by transforming document blocks rather than editing raw text ad hoc.
4. init, note, exec, image, and pop are document mutation commands. They read the current Markdown file, modify the block sequence, and write the file back. init creates the initial title/timestamp/id scaffold; note appends prose; exec appends a code block plus its output; image appends an image block and copies the file; pop removes the last logical entry, which may span multiple blocks.
5. Execution is isolated in exec/. runner.go runs shell/interpreter commands in the chosen working directory and captures output, while image.go handles image file copy and naming concerns. This subsystem is the main runtime boundary where external processes are invoked and their stdout/stderr become document content.
6. showboat exec is special because it has two outputs: it prints the captured output to stdout for the operator, and it also appends that output into the Markdown file. The CLI exit code mirrors the executed command’s exit code, so agents can react immediately to failures while still preserving the failed attempt in the document.
7. verify replays the document as an executable spec. It parses the Markdown, re-runs each code block, skips image blocks, and diffs the new output against the recorded output. This creates a validation boundary between stored evidence and actual current behavior, and optionally writes an updated copy when outputs drift.
8. extract is the inverse transformation: it parses a finished document and emits the sequence of Showboat CLI commands that could recreate it. It intentionally omits output blocks because those are derived from exec runs, making extract a provenance/debugging tool for the document history.
9. Remote streaming is an optional side effect controlled by SHOWBOAT_REMOTE_URL. When enabled, mutating commands POST their content to a remote receiver, keyed by a UUID stored in the document as an HTML comment. note, exec, init, and pop use form-encoded posts; image uses multipart upload. This is a separate integration boundary and never blocks the main local command on remote failures.
10. Filesystem behavior matters to the architecture: markdown docs are the primary store, and images are copied into the same directory as the document so the file can remain self-contained. The generated filenames and preserved alt text are part of the document-writing contract.
11. The test layout mirrors the subsystems: unit tests exist for Markdown parsing/writing, execution, image handling, and each CLI command, plus an integration test. That suggests the main architectural risk is consistency between parsing, mutation, replay, and round-tripping.
12. CI/release automation is present in GitHub Actions workflows. The repo is built and tested as a Go tool, and the README also shows a Python wheel publishing path via go-to-wheel, which affects distribution but not the runtime architecture.
Main entry points: build.go dispatch · parser.go parse · writer.go write · remote.go remote
Components 17
CLI
User-facing command surface and subcommands
- main · Program entry and command wiring
main.go - dispatch · Shared CLI setup and subcommand routing
cmd/build.go - init · Creates the initial showboat document scaffold
cmd/init.go - note · Appends prose blocks to the document
- exec · Runs a command and appends code plus output
- image · Appends an image block and copies the file
- pop · Removes the last logical document entry
cmd/pop.go - verify · Replays code blocks and compares recorded output
cmd/verify.go - extract · Emits CLI commands that recreate a document
cmd/extract.go
Document
Markdown document model and block transformations
Runtime
Execution and image handling
Integration
Optional remote streaming and release automation
- remote · Optional remote streaming and upload handling
cmd/remote.go - remote receiver · Optional server receiving streamed mutations
Connections 34
- main → dispatch: starts · Main delegates CLI setup and command selection
- dispatch → init: routes · Dispatches init subcommand
- dispatch → note: routes · Dispatches note subcommand
- dispatch → exec: routes · Dispatches exec subcommand
- dispatch → image: routes · Dispatches image subcommand
- dispatch → pop: routes · Dispatches pop subcommand
- dispatch → verify: routes · Dispatches verify subcommand
- dispatch → extract: routes · Dispatches extract subcommand
- init → parse: reads/writes · Creates or updates the document through the markdown layer
- note → parse: reads · Loads current blocks before appending prose
- exec → parse: reads · Loads current blocks before adding code/output
- image → parse: reads · Loads current blocks before adding image entry
- pop → parse: reads · Loads current blocks before removing the last entry
- verify → parse: parses · Replays an existing document from structured blocks
- extract → parse: parses · Reads the document structure for command reconstruction
- parse → blocks: produces · Parser converts Markdown into block structures
- blocks → write: serializes · Writer turns blocks back into Markdown text
- init → write: writes · Writes the initial scaffold to disk
- note → write: writes · Persists updated block sequence
- exec → write: writes · Persists code block and captured output
- image → write: writes · Persists image block and alt text
- pop → write: writes · Persists the shortened document
- verify → runner: replays · Re-executes code blocks for comparison
- exec → runner: executes · Runs the requested command in the workdir
- exec → showboat doc: appends output · Captured stdout/stderr becomes stored evidence
- exec → remote: streams · Mutating command can publish content remotely
- note → remote: streams · Optional remote post of appended prose
- init → remote: streams · Optional remote post of new document metadata
- pop → remote: streams · Optional remote post of removal event
- image → image: copies · Copies image into the document directory
- image → showboat doc: references · Image entry is stored alongside the Markdown log
- remote → remote receiver: posts · Sends form or multipart updates when enabled
- verify → showboat doc: compares · Checks recorded output against current behavior
- extract → showboat doc: reconstructs · Derives CLI history from the saved document