Add format command for .cmdt files

Implements formatting functionality that normalizes:
- Comments (ensures proper ''# comment'' spacing)
- Commands (removes trailing whitespace)
- File output references (standardizes spacing)
- Directives (standardizes syntax)
- File endings (ensures single trailing newline)

Similar to the updater but preserves existing expectations
rather than recording new ones.

Includes test cases covering basic formatting scenarios.

Co-authored-by: Brandon Bloom <[email protected]>

Author: claude[bot]

internal/cli/format.go

@@ -0,0 +1,61 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/deref/transcript/internal/core"
+	"github.com/natefinch/atomic"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	formatCmd.Flags().BoolVarP(&formatFlags.DryRun, "dry-run", "n", false, "dry run")
+	rootCmd.AddCommand(formatCmd)
+}
+
+var formatFlags struct {
+	DryRun bool
+}
+
+var formatCmd = &cobra.Command{
+	Use:   "format <transcripts...>",
+	Short: "Formats transcript files",
+	Long: `Formats transcript files by normalizing comments, blank lines,
+trailing whitespace (except in command output), trailing newline,
+and special directive syntax.
+
+Transcript files are formatted in-place, unless --dry-run is specified. In a dry
+run, the formatted output is printed to stdout instead.
+`,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		ctx := cmd.Context()
+		for _, filename := range args {
+			if err := formatFile(ctx, filename); err != nil {
+				return fmt.Errorf("formatting %q: %w", filename, err)
+			}
+		}
+		return nil
+	},
+}
+
+func formatFile(ctx context.Context, filename string) error {
+	f, err := os.Open(filename)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	formatter := &core.Formatter{}
+	transcript, err := formatter.FormatTranscript(ctx, f)
+	if err != nil {
+		return err
+	}
+	if formatFlags.DryRun {
+		_, err := io.Copy(os.Stdout, transcript)
+		return err
+	}
+	return atomic.WriteFile(filename, transcript)
+}

internal/core/formatter.go

@@ -0,0 +1,108 @@
+package core
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"strconv"
+	"strings"
+)
+
+type Formatter struct {
+	buf    *bytes.Buffer
+	lineno int
+}
+
+func (f *Formatter) FormatTranscript(ctx context.Context, r io.Reader) (transcript *bytes.Buffer, err error) {
+	f.buf = &bytes.Buffer{}
+	
+	// Use the regular interpreter with the formatter as handler.
+	interp := &Interpreter{
+		Handler: f,
+	}
+	if err := interp.ExecTranscript(ctx, r); err != nil {
+		return nil, err
+	}
+	
+	// Ensure file ends with exactly one newline
+	content := f.buf.Bytes()
+	content = bytes.TrimRight(content, "\n")
+	if len(content) > 0 {
+		content = append(content, '\n')
+	}
+	
+	return bytes.NewBuffer(content), nil
+}
+
+func (f *Formatter) HandleComment(ctx context.Context, text string) error {
+	f.lineno++
+	
+	// Normalize comments and blank lines
+	trimmed := strings.TrimSpace(text)
+	if trimmed == "" {
+		// Blank line
+		f.buf.WriteString("\n")
+	} else if strings.HasPrefix(trimmed, "#") {
+		// Normalize comment formatting
+		comment := strings.TrimPrefix(trimmed, "#")
+		comment = strings.TrimSpace(comment)
+		if comment == "" {
+			f.buf.WriteString("#\n")
+		} else {
+			f.buf.WriteString("# " + comment + "\n")
+		}
+	}
+	
+	return nil
+}
+
+func (f *Formatter) HandleRun(ctx context.Context, command string) error {
+	f.lineno++
+	
+	// Write the command with normalized formatting
+	f.buf.WriteString("$ " + strings.TrimSpace(command) + "\n")
+	
+	return nil
+}
+
+func (f *Formatter) HandleOutput(ctx context.Context, fd int, line string) error {
+	f.lineno++
+	
+	// Output lines preserve their exact content (including whitespace)
+	f.buf.WriteString(strconv.Itoa(fd) + " " + line + "\n")
+	
+	return nil
+}
+
+func (f *Formatter) HandleFileOutput(ctx context.Context, fd int, filepath string) error {
+	f.lineno++
+	
+	// File output references with normalized formatting
+	f.buf.WriteString(strconv.Itoa(fd) + "< " + strings.TrimSpace(filepath) + "\n")
+	
+	return nil
+}
+
+func (f *Formatter) HandleNoNewline(ctx context.Context, fd int) error {
+	f.lineno++
+	
+	// No-newline directive with normalized formatting
+	f.buf.WriteString("% no-newline\n")
+	
+	return nil
+}
+
+func (f *Formatter) HandleExitCode(ctx context.Context, exitCode int) error {
+	f.lineno++
+	
+	// Exit code with normalized formatting
+	f.buf.WriteString("? " + strconv.Itoa(exitCode) + "\n")
+	
+	return nil
+}
+
+func (f *Formatter) HandleEnd(ctx context.Context) error {
+	// No special handling needed for end
+	return nil
+}

tests/format-basic.cmdt

@@ -0,0 +1,14 @@
+# Test basic formatting
+
+$ echo hello
+1 hello
+
+# Multiple blank lines should be normalized
+
+
+$ echo world 
+1 world
+
+   # Comment with irregular spacing
+$ false
+? 1

tests/format-basic.cmdt.expected

@@ -0,0 +1,12 @@
+# Test basic formatting
+
+$ echo hello
+1 hello
+
+
+$ echo world
+1 world
+
+# Comment with irregular spacing
+$ false
+? 1

tests/format-command.cmdt

@@ -0,0 +1,42 @@
+# Test format command functionality
+
+# Create a file with formatting issues
+$ cat > unformatted.cmdt <<'EOF'
+#comment without space
+
+
+$ echo hello 
+1 hello
+
+   # irregular comment spacing
+$ false   
+? 1  
+EOF
+
+# Test dry-run format
+$ transcript format --dry-run unformatted.cmdt
+1 # comment without space
+1 
+1 $ echo hello
+1 1 hello
+1 
+1 # irregular comment spacing
+1 $ false
+1 ? 1
+
+# Test actual formatting (in-place)
+$ transcript format unformatted.cmdt
+
+# Verify the file was formatted correctly
+$ cat unformatted.cmdt
+1 # comment without space
+1 
+1 $ echo hello
+1 1 hello
+1 
+1 # irregular comment spacing
+1 $ false
+1 ? 1
+
+# Clean up
+$ rm unformatted.cmdt

tests/format-simple.cmdt

@@ -0,0 +1,21 @@
+# Test simple format command
+
+# Create a file with whitespace and formatting issues
+$ cat > test.cmdt <<'EOF'
+#comment
+$ echo test   
+1 test
+   #another comment   
+? 0
+EOF
+
+# Format it and show the result
+$ transcript format --dry-run test.cmdt
+1 # comment
+1 $ echo test
+1 1 test
+1 # another comment
+1 ? 0
+
+# Clean up
+$ rm test.cmdt