Add binary output detection and file reference handling

- Implement automatic binary detection using null bytes and 10% unprintable character threshold
- Add file reference opcodes (1<, 2<) for external file content
- Support file reference preservation during transcript updates
- Integrate commandBufferingHandler into Updater type for better cohesion
- Add comprehensive test coverage for binary detection and file handling
- Update documentation with binary output section and file reference opcodes

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

Co-Authored-By: Claude <[email protected]>

Author: brandonbloom

CLAUDE.md

@@ -1,3 +1,5 @@
 - Build with `./build.sh` instead of using `go build` directly.
 
-- .cmdt files use the Command Transcript language implemented by this project. Consult @README.md for the syntax and @tests/*.cmdt for example usages.
+- .cmdt files use the Command Transcript language implemented by this project. Consult @README.md for the syntax and @tests/*.cmdt for example usages.
+
+- Always test using ./test.sh from the root directory.

README.md

@@ -147,6 +147,15 @@ Operations with the following opcodes are supported:
     </p>
   </dd>
 
+  <dt><code>1&lt;</code>, <code>2&lt;</code> &mdash; file output</dt>
+  <dd>
+    <p>
+      Like <code>1</code> and <code>2</code>, but reference a file containing
+      the expected output instead of including it inline. File paths respect
+      the current working directory.
+    </p>
+  </dd>
+
   <dt><code>?</code> &mdash; exit-code</dt>
   <dd>
     <p>Exit code of the previously run command.</p>
@@ -192,6 +201,14 @@ Transcript inherits the working directory from the process that launches it.
 Directory changes (such as `cd` commands) persist throughout the transcript
 session, allowing tests to navigate and use relative paths consistently.
 
+## Binary Output
+
+Transcript automatically detects binary output using heuristics. Lines of plain
+text are recorded inline using the standard `1` and `2` opcodes, while spans of
+binary data are written to incrementally numbered files (`001.bin`, `002.bin`,
+etc.) and referenced using `1<` and `2<` opcodes. This applies to both shell
+recording and automatic updating.
+
 # Go API
 
 In addition to the `transcript` CLI, there is a Go API for users who wish to

internal/core/binary.go

@@ -0,0 +1,53 @@
+package core
+
+import (
+	"unicode"
+	"unicode/utf8"
+)
+
+// isUnprintable returns true if the rune should be considered unprintable
+// for binary detection purposes. This includes invalid UTF-8 sequences
+// and control characters, but excludes whitespace.
+func isUnprintable(r rune) bool {
+	return r == utf8.RuneError || (!unicode.IsPrint(r) && !unicode.IsSpace(r))
+}
+
+// isBinary determines if data should be treated as binary output.
+// Returns true if the data contains null bytes or >10% unprintable characters.
+// Properly handles UTF-8 encoded text.
+//
+// Uses byte-based threshold approximation for performance: we compare unprintable
+// rune count against 10% of total byte count. This enables early termination
+// when processing large inputs, though it may be slightly inaccurate for text
+// with many multi-byte UTF-8 characters (acceptable trade-off for performance).
+func isBinary(data []byte) bool {
+	if len(data) == 0 {
+		return false
+	}
+
+	// Calculate 10% threshold based on byte count approximation.
+	// This enables early termination for performance.
+	threshold := len(data) / 10
+	unprintable := 0
+
+	for len(data) > 0 {
+		r, size := utf8.DecodeRune(data)
+		data = data[size:]
+
+		// Check for null bytes - instant binary classification.
+		if r == 0 {
+			return true
+		}
+
+		// Check if rune is unprintable for binary detection.
+		if isUnprintable(r) {
+			unprintable++
+			// Early exit if we've exceeded the threshold (>10% of bytes).
+			if unprintable > threshold {
+				return true
+			}
+		}
+	}
+
+	return false
+}

internal/core/binary_test.go

@@ -0,0 +1,91 @@
+package core
+
+import "testing"
+
+func TestIsBinary(t *testing.T) {
+	tests := []struct {
+		name string
+		data []byte
+		want bool
+	}{
+		{
+			name: "empty data",
+			data: []byte{},
+			want: false,
+		},
+		{
+			name: "normal text",
+			data: []byte("hello world"),
+			want: false,
+		},
+		{
+			name: "text with newlines",
+			data: []byte("hello\nworld\n"),
+			want: false,
+		},
+		{
+			name: "text with null byte",
+			data: []byte("hello\x00world"),
+			want: true,
+		},
+		{
+			name: "text with multiple null bytes",
+			data: []byte("\x00\x00\x00"),
+			want: true,
+		},
+		{
+			name: "text with high unprintable ratio",
+			data: []byte("a\x01\x02\x03\x04\x05\x06\x07\x08\x09"), // 9 unprintable out of 10 = 90%
+			want: true,
+		},
+		{
+			name: "text with low unprintable ratio",
+			data: []byte("hello world\x01"), // 1 unprintable out of 12 = 8.3%
+			want: false,
+		},
+		{
+			name: "text exactly at 10% threshold",
+			data: []byte("abcdefghi\x01"), // 1 unprintable out of 10 = 10%
+			want: false,
+		},
+		{
+			name: "text just over 10% threshold",
+			data: []byte("abcdefgh\x01\x02"), // 2 unprintable out of 10 = 20%
+			want: true,
+		},
+		{
+			name: "single byte printable",
+			data: []byte("a"),
+			want: false,
+		},
+		{
+			name: "single byte unprintable",
+			data: []byte{0x01},
+			want: true,
+		},
+		{
+			name: "unicode text",
+			data: []byte("hello 世界"),
+			want: false,
+		},
+		{
+			name: "invalid utf8",
+			data: []byte{0x80, 0x81, 0x82},
+			want: true,
+		},
+		{
+			name: "tab and space characters",
+			data: []byte("hello\tworld\n"),
+			want: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isBinary(tt.data)
+			if got != tt.want {
+				t.Errorf("isBinary(%q) = %v, want %v", tt.data, got, tt.want)
+			}
+		})
+	}
+}

internal/core/checker.go

@@ -5,6 +5,8 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"os"
+	"strings"
 )
 
 type Checker struct {
@@ -55,6 +57,36 @@ func (ckr *checkHandler) HandleOutput(ctx context.Context, fd int, line string)
 	return ckr.expectOutput(fmt.Sprintf("%d%s%s", fd, sep, line))
 }
 
+func (ckr *checkHandler) HandleFileOutput(ctx context.Context, fd int, filepath string) error {
+	// Read the expected file content.
+	expectedData, err := os.ReadFile(filepath)
+	if err != nil {
+		return fmt.Errorf("reading expected file %s: %w", filepath, err)
+	}
+
+	// Build the expected output string that would be generated if this was inline.
+	if isBinary(expectedData) {
+		// For binary files, we expect the file reference format.
+		expectedOutput := fmt.Sprintf("%d< %s", fd, filepath)
+		return ckr.expectOutput(expectedOutput)
+	} else {
+		// For text files, we expect the inline format.
+		var builder strings.Builder
+		for line := range bytes.Lines(expectedData) {
+			if len(line) == 1 && line[0] == '\n' {
+				fmt.Fprintf(&builder, "%d\n", fd)
+			} else {
+				fmt.Fprintf(&builder, "%d %s", fd, line)
+			}
+		}
+		// Handle case where original didn't end with newline.
+		if len(expectedData) > 0 && expectedData[len(expectedData)-1] != '\n' {
+			builder.WriteString("\n% no-newline\n")
+		}
+		return ckr.expectOutput(builder.String())
+	}
+}
+
 func (ckr *checkHandler) HandleNoNewline(ctx context.Context, fd int) error {
 	// Assumes the previous line contains an already written newline.
 	// This is also why we can ignore the fd parameter, as it's assumed to

internal/core/errors.go

@@ -57,4 +57,3 @@ var yellow = color.New(color.FgYellow)
 var cyan = color.New(color.FgCyan)
 var green = color.New(color.FgGreen)
 var red = color.New(color.FgRed)
-

internal/core/interp.go

@@ -40,6 +40,12 @@ type Handler interface {
 	// Corresponds to cmdt syntax: "1 stdout line" or "2 stderr line".
 	HandleOutput(ctx context.Context, fd int, line string) error
 
+	// HandleFileOutput processes expected output that references an external file.
+	// The fd parameter indicates the file descriptor: 1 for stdout, 2 for stderr.
+	// The filepath parameter specifies the file containing the expected output.
+	// Corresponds to cmdt syntax: "1< filename" or "2< filename".
+	HandleFileOutput(ctx context.Context, fd int, filepath string) error
+
 	// HandleNoNewline indicates that the last output line did not end with a newline.
 	// The fd parameter indicates which stream (stdout=1, stderr=2) lacks the newline.
 	// Corresponds to cmdt syntax: "% no-newline".
@@ -99,6 +105,14 @@ func (t *Interpreter) ExecLine(ctx context.Context, text string) error {
 		t.prevFD = fd
 		return hdlr.HandleOutput(ctx, fd, payload)
 
+	case "1<", "2<":
+		if !t.acceptResults {
+			return t.syntaxErrorf("unexpected file output check")
+		}
+		fd := int(opcode[0]) - '1' + 1
+		t.prevFD = fd
+		return hdlr.HandleFileOutput(ctx, fd, payload)
+
 	case "?":
 		if !t.acceptResults {
 			return t.syntaxErrorf("unexpected exit status check")

internal/core/recorder.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"os"
 	"strings"
 
 	"mvdan.cc/sh/v3/interp"
@@ -21,10 +22,13 @@ type Recorder struct {
 	// Transcript captures the recorded output in cmdt format.
 	Transcript bytes.Buffer
 
-	needsBlank bool
-	runner     *interp.Runner
-	stdoutBuf  bytes.Buffer
-	stderrBuf  bytes.Buffer
+	needsBlank     bool
+	runner         *interp.Runner
+	stdoutBuf      bytes.Buffer
+	stderrBuf      bytes.Buffer
+	fileCount      int      // Counter for auto-generated binary file names
+	preferredFiles []string // List of preferred filenames in order (stderr first, then stdout)
+	fileIndex      int      // Current position in preferredFiles slice
 }
 
 func (rec *Recorder) Init() error {
@@ -34,6 +38,8 @@ func (rec *Recorder) Init() error {
 			io.MultiWriter(&rec.stdoutBuf, orDiscard(rec.Stdout)),
 			io.MultiWriter(&rec.stderrBuf, orDiscard(rec.Stderr)),
 		))
+	rec.preferredFiles = make([]string, 0)
+	rec.fileIndex = 0
 	return err
 }
 
@@ -44,42 +50,78 @@ func orDiscard(w io.Writer) io.Writer {
 	return w
 }
 
+// SetPreferredFiles sets the list of preferred filenames in order.
+// Files should be provided in deterministic order (stderr first, then stdout).
+func (rec *Recorder) SetPreferredFiles(files []string) {
+	rec.preferredFiles = make([]string, len(files))
+	copy(rec.preferredFiles, files)
+	rec.fileIndex = 0
+}
+
+// generateBinaryFilename creates a filename, preferring existing names when available.
+// Uses deterministic ordering (stderr first, then stdout) to consume preferred filenames.
+func (rec *Recorder) generateBinaryFilename() string {
+	// Check if we have a preferred filename available.
+	if rec.fileIndex < len(rec.preferredFiles) {
+		filename := rec.preferredFiles[rec.fileIndex]
+		rec.fileIndex++
+		return filename
+	}
+
+	// Fall back to auto-generated filename.
+	rec.fileCount++
+	return fmt.Sprintf("%03d.bin", rec.fileCount)
+}
+
 func (rec *Recorder) flush() error {
 	// Write stderr first (usually empty, text-only, important not to miss).
-	if err := rec.flushBuffer(&rec.stderrBuf, "2"); err != nil {
+	if err := rec.flushBuffer(&rec.stderrBuf, 2); err != nil {
 		return err
 	}
 	// Then write stdout.
-	if err := rec.flushBuffer(&rec.stdoutBuf, "1"); err != nil {
+	if err := rec.flushBuffer(&rec.stdoutBuf, 1); err != nil {
 		return err
 	}
 	return nil
 }
 
-func (rec *Recorder) flushBuffer(buf *bytes.Buffer, prefix string) error {
+// flushBuffer processes output from a command and writes it to the transcript.
+// Individual command outputs are expected to be reasonably small (not streaming large files).
+func (rec *Recorder) flushBuffer(buf *bytes.Buffer, fd int) error {
 	if buf.Len() == 0 {
 		return nil
 	}
-	
+
 	data := buf.Bytes()
 	buf.Reset()
-	
-	// Add prefix to each line and write to transcript.
+
+	// Check if data is binary.
+	if isBinary(data) {
+		// Write binary data to file and reference it.
+		filename := rec.generateBinaryFilename()
+		if err := os.WriteFile(filename, data, 0644); err != nil {
+			return fmt.Errorf("writing binary file %q: %w", filename, err)
+		}
+		fmt.Fprintf(&rec.Transcript, "%d< %s\n", fd, filename)
+		return nil
+	}
+
+	// Handle text output - add prefix to each line and write to transcript.
 	for line := range bytes.Lines(data) {
 		if len(line) == 1 && line[0] == '\n' {
 			// Empty line - just prefix.
-			fmt.Fprintf(&rec.Transcript, "%s\n", prefix)
+			fmt.Fprintf(&rec.Transcript, "%d\n", fd)
 		} else {
 			// Non-empty line - prefix + space + line.
-			fmt.Fprintf(&rec.Transcript, "%s %s", prefix, line)
+			fmt.Fprintf(&rec.Transcript, "%d %s", fd, line)
 		}
 	}
-	
+
 	// Handle case where original didn't end with newline.
 	if len(data) > 0 && data[len(data)-1] != '\n' {
 		io.WriteString(&rec.Transcript, "\n% no-newline\n")
 	}
-	
+
 	return nil
 }