feat: add stdin/stdout pipelining support for all CLI commands (#151)

* feat: add stdin support and fix stdout/stderr separation for Unix pipelining

Enable reading OpenAPI specs from stdin using '-' as the file argument across
all CLI commands. This allows standard Unix piping patterns like:

  cat spec.yaml | openapi spec validate -
  cat spec.yaml | openapi spec inline - | openapi spec clean -
  curl -s https://api.example.com/spec | openapi spec lint -f json -

Changes:
- Add IsStdin() helper and ReadFromStdin field to OpenAPIProcessor
- Support '-' as stdin indicator in all commands: validate, lint, inline,
  bundle, upgrade, clean, sanitize, optimize, snip, explore, localize,
  arazzo validate
- Move all status/info/warning messages to stderr so stdout is reserved
  for data output (document content, lint results) - enables clean piping
- Guard incompatible flags with stdin: --write, --fix, --fix-interactive,
  interactive snip mode
- Add comprehensive unit and integration tests for stdin/pipelining
- Update all command help text to document stdin usage

Closes #67

https://claude.ai/code/session_01E9drkMjTuKTfQsLhTLdZxX

* feat: auto-detect piped stdin so '-' argument is optional

When stdin is connected to a pipe (not a terminal), all commands now
automatically read from stdin without requiring the '-' argument.
The explicit '-' still works as an override.

This means you can now write:
  cat spec.yaml | openapi spec validate
  cat spec.yaml | openapi spec inline | openapi spec clean
  curl -s https://api.example.com/spec | openapi spec lint -f json

Instead of requiring:
  cat spec.yaml | openapi spec validate -

Implementation:
- Add StdinIsPiped() helper using os.Stdin.Stat() to detect pipe mode
- Add stdinOrFileArgs() custom cobra validator that allows 0 args when
  stdin is piped, with clear error messages otherwise
- Add inputFileFromArgs() that returns '-' when no args given
- Update all commands (validate, lint, inline, bundle, upgrade, clean,
  sanitize, optimize, snip, explore, arazzo validate) to use the new
  helpers
- When stdin is not piped and no file given, shows helpful error:
  "requires at least 1 arg(s), or pipe data to stdin"
- Add tests for inputFileFromArgs and stdinOrFileArgs

https://claude.ai/code/session_01E9drkMjTuKTfQsLhTLdZxX

* feat: add stdin/pipelining support for swagger, overlay commands and deduplicate shared CLI utilities

* fix

* fix: address PR review feedback and add missing test coverage

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: TristanSpeakEasy

cmd/openapi/commands/arazzo/validate.go

@@ -4,10 +4,12 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 
 	"github.com/speakeasy-api/openapi/arazzo"
+	"github.com/speakeasy-api/openapi/cmd/openapi/commands/cmdutil"
 	"github.com/spf13/cobra"
 )
 
@@ -21,14 +23,18 @@ This command will parse and validate the provided Arazzo document, checking for:
 - Required fields and proper data types
 - Workflow step dependencies and consistency
 - Runtime expression validation
-- Source description references`,
-	Args: cobra.ExactArgs(1),
+- Source description references
+
+Stdin is supported — either pipe data directly or use '-' explicitly:
+  cat workflow.yaml | openapi arazzo validate
+  cat workflow.yaml | openapi arazzo validate -`,
+	Args: cmdutil.StdinOrFileArgs(1, 1),
 	Run:  runValidate,
 }
 
 func runValidate(cmd *cobra.Command, args []string) {
 	ctx := cmd.Context()
-	file := args[0]
+	file := cmdutil.InputFileFromArgs(args)
 
 	if err := validateArazzo(ctx, file); err != nil {
 		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
@@ -37,29 +43,37 @@ func runValidate(cmd *cobra.Command, args []string) {
 }
 
 func validateArazzo(ctx context.Context, file string) error {
-	cleanFile := filepath.Clean(file)
-	fmt.Printf("Validating Arazzo document: %s\n", cleanFile)
+	var reader io.ReadCloser
 
-	f, err := os.Open(cleanFile)
-	if err != nil {
-		return fmt.Errorf("failed to open file: %w", err)
+	if cmdutil.IsStdin(file) {
+		fmt.Fprintf(os.Stderr, "Validating Arazzo document from stdin\n")
+		reader = io.NopCloser(os.Stdin)
+	} else {
+		cleanFile := filepath.Clean(file)
+		fmt.Fprintf(os.Stderr, "Validating Arazzo document: %s\n", cleanFile)
+
+		f, err := os.Open(cleanFile)
+		if err != nil {
+			return fmt.Errorf("failed to open file: %w", err)
+		}
+		reader = f
 	}
-	defer f.Close()
+	defer reader.Close()
 
-	_, validationErrors, err := arazzo.Unmarshal(ctx, f)
+	_, validationErrors, err := arazzo.Unmarshal(ctx, reader)
 	if err != nil {
 		return fmt.Errorf("failed to unmarshal file: %w", err)
 	}
 
 	if len(validationErrors) == 0 {
-		fmt.Printf("✅ Arazzo document is valid - 0 errors\n")
+		fmt.Fprintf(os.Stderr, "✅ Arazzo document is valid - 0 errors\n")
 		return nil
 	}
 
-	fmt.Printf("❌ Arazzo document is invalid - %d errors:\n\n", len(validationErrors))
+	fmt.Fprintf(os.Stderr, "❌ Arazzo document is invalid - %d errors:\n\n", len(validationErrors))
 
 	for i, validationErr := range validationErrors {
-		fmt.Printf("%d. %s\n", i+1, validationErr.Error())
+		fmt.Fprintf(os.Stderr, "%d. %s\n", i+1, validationErr.Error())
 	}
 
 	return errors.New("arazzo document validation failed")

cmd/openapi/commands/cmdutil/cmdutil.go

@@ -0,0 +1,73 @@
+// Package cmdutil provides shared CLI utilities for all command groups.
+package cmdutil
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/spf13/cobra"
+)
+
+// StdinIndicator is the conventional Unix indicator to read from stdin.
+const StdinIndicator = "-"
+
+// IsStdin returns true if the given path indicates stdin should be used.
+func IsStdin(path string) bool {
+	return path == StdinIndicator
+}
+
+// StdinIsPiped returns true when stdin is connected to a pipe (not a terminal),
+// meaning data is being piped in from another command or a file redirect.
+func StdinIsPiped() bool {
+	fi, err := os.Stdin.Stat()
+	if err != nil {
+		return false
+	}
+	return (fi.Mode() & os.ModeCharDevice) == 0
+}
+
+// InputFileFromArgs returns the first positional arg as the input file path,
+// or the stdin indicator "-" when no args are provided.
+func InputFileFromArgs(args []string) string {
+	if len(args) > 0 {
+		return args[0]
+	}
+	return StdinIndicator
+}
+
+// StdinOrFileArgs returns a cobra arg validator that accepts minArgs..maxArgs
+// when a file is given, but also allows zero args when stdin is piped.
+func StdinOrFileArgs(minArgs, maxArgs int) cobra.PositionalArgs {
+	return func(cmd *cobra.Command, args []string) error {
+		if len(args) < minArgs {
+			if len(args) == 0 && StdinIsPiped() {
+				return nil
+			}
+			return fmt.Errorf("requires at least %d arg(s), or pipe data to stdin", minArgs)
+		}
+		if maxArgs >= 0 && len(args) > maxArgs {
+			return fmt.Errorf("accepts at most %d arg(s), received %d", maxArgs, len(args))
+		}
+		return nil
+	}
+}
+
+// ArgAt returns args[index] if it exists, or defaultVal otherwise.
+func ArgAt(args []string, index int, defaultVal string) string {
+	if index >= 0 && index < len(args) {
+		return args[index]
+	}
+	return defaultVal
+}
+
+// Dief prints a formatted message to stderr and exits with code 1.
+func Dief(f string, args ...any) {
+	fmt.Fprintf(os.Stderr, f+"\n", args...)
+	os.Exit(1)
+}
+
+// Die prints an error to stderr and exits with code 1.
+func Die(err error) {
+	fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+	os.Exit(1)
+}

cmd/openapi/commands/cmdutil/cmdutil_test.go

@@ -0,0 +1,129 @@
+package cmdutil
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestIsStdin(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		path     string
+		expected bool
+	}{
+		{name: "dash is stdin", path: "-", expected: true},
+		{name: "empty is not stdin", path: "", expected: false},
+		{name: "file path is not stdin", path: "spec.yaml", expected: false},
+		{name: "dash prefix is not stdin", path: "-file", expected: false},
+		{name: "double dash is not stdin", path: "--", expected: false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			assert.Equal(t, tt.expected, IsStdin(tt.path))
+		})
+	}
+}
+
+func TestInputFileFromArgs(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		args     []string
+		expected string
+	}{
+		{name: "no args returns stdin indicator", args: []string{}, expected: StdinIndicator},
+		{name: "nil args returns stdin indicator", args: nil, expected: StdinIndicator},
+		{name: "single file arg", args: []string{"spec.yaml"}, expected: "spec.yaml"},
+		{name: "explicit dash", args: []string{"-"}, expected: "-"},
+		{name: "multiple args returns first", args: []string{"spec.yaml", "out.yaml"}, expected: "spec.yaml"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			assert.Equal(t, tt.expected, InputFileFromArgs(tt.args))
+		})
+	}
+}
+
+func TestArgAt(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name       string
+		args       []string
+		index      int
+		defaultVal string
+		expected   string
+	}{
+		{name: "returns value at index", args: []string{"a", "b", "c"}, index: 1, defaultVal: "", expected: "b"},
+		{name: "returns first element", args: []string{"a"}, index: 0, defaultVal: "x", expected: "a"},
+		{name: "returns default when out of range", args: []string{"a"}, index: 1, defaultVal: "default", expected: "default"},
+		{name: "returns default for empty args", args: []string{}, index: 0, defaultVal: "default", expected: "default"},
+		{name: "returns default for nil args", args: nil, index: 0, defaultVal: "default", expected: "default"},
+		{name: "returns empty default", args: []string{}, index: 0, defaultVal: "", expected: ""},
+		{name: "returns default for negative index", args: []string{"a", "b"}, index: -1, defaultVal: "default", expected: "default"},
+		{name: "returns default for large negative index", args: []string{"a"}, index: -100, defaultVal: "fallback", expected: "fallback"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			assert.Equal(t, tt.expected, ArgAt(tt.args, tt.index, tt.defaultVal))
+		})
+	}
+}
+
+func TestStdinOrFileArgs(t *testing.T) {
+	t.Parallel()
+
+	validator := StdinOrFileArgs(1, 2)
+
+	t.Run("accepts one arg", func(t *testing.T) {
+		t.Parallel()
+		err := validator(nil, []string{"spec.yaml"})
+		assert.NoError(t, err)
+	})
+
+	t.Run("accepts two args", func(t *testing.T) {
+		t.Parallel()
+		err := validator(nil, []string{"spec.yaml", "out.yaml"})
+		assert.NoError(t, err)
+	})
+
+	t.Run("rejects three args with max 2", func(t *testing.T) {
+		t.Parallel()
+		err := validator(nil, []string{"a", "b", "c"})
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "accepts at most 2 arg(s)")
+	})
+
+	t.Run("unbounded max accepts many args", func(t *testing.T) {
+		t.Parallel()
+		unbounded := StdinOrFileArgs(1, -1)
+		err := unbounded(nil, []string{"a", "b", "c", "d", "e"})
+		assert.NoError(t, err, "negative maxArgs should allow unlimited args")
+	})
+
+	t.Run("zero minArgs accepts any arg count", func(t *testing.T) {
+		t.Parallel()
+		noMin := StdinOrFileArgs(0, 2)
+		err := noMin(nil, []string{})
+		assert.NoError(t, err, "zero minArgs should accept empty args")
+	})
+
+	t.Run("error message includes min arg count", func(t *testing.T) {
+		t.Parallel()
+		min3 := StdinOrFileArgs(3, 5)
+		err := min3(nil, []string{"a", "b"})
+		if err != nil {
+			assert.Contains(t, err.Error(), "requires at least 3 arg(s)")
+		}
+	})
+}

cmd/openapi/commands/openapi/bundle.go

@@ -20,6 +20,10 @@ var bundleCmd = &cobra.Command{
 	Long: `Bundle transforms an OpenAPI document by bringing all external references into the components section,
 creating a self-contained document that maintains the reference structure but doesn't depend on external files.
 
+Stdin is supported — either pipe data directly or use '-' explicitly:
+  cat spec.yaml | openapi spec bundle
+  cat spec.yaml | openapi spec bundle -
+
 This operation is useful when you want to:
 • Create portable documents that combine multiple OpenAPI files
 • Maintain reference structure for tooling that supports references
@@ -42,7 +46,7 @@ Examples:
 
   # Bundle with filepath naming (default)
   openapi spec bundle --naming filepath ./spec.yaml ./bundled.yaml`,
-	Args: cobra.RangeArgs(1, 2),
+	Args: stdinOrFileArgs(1, 2),
 	RunE: runBundleCommand,
 }
 
@@ -55,11 +59,8 @@ func runBundleCommand(cmd *cobra.Command, args []string) error {
 	ctx := context.Background()
 
 	// Parse arguments
-	inputFile := args[0]
-	var outputFile string
-	if len(args) > 1 {
-		outputFile = args[1]
-	}
+	inputFile := inputFileFromArgs(args)
+	outputFile := outputFileFromArgs(args)
 
 	// Validate naming strategy
 	var namingStrategy openapi.BundleNamingStrategy
@@ -88,10 +89,14 @@ func runBundleCommand(cmd *cobra.Command, args []string) error {
 	processor.ReportValidationErrors(validationErrors)
 
 	// Configure bundle options
+	targetLocation := inputFile
+	if processor.ReadFromStdin {
+		targetLocation = ""
+	}
 	opts := openapi.BundleOptions{
 		ResolveOptions: openapi.ResolveOptions{
 			RootDocument:   doc,
-			TargetLocation: inputFile,
+			TargetLocation: targetLocation,
 		},
 		NamingStrategy: namingStrategy,
 	}

cmd/openapi/commands/openapi/clean.go

@@ -15,6 +15,10 @@ var cleanCmd = &cobra.Command{
 	Short: "Remove unused components and unused top-level tags from an OpenAPI specification",
 	Long: `Remove unused components and unused top-level tags from an OpenAPI specification to create a cleaner, more focused document.
 
+Stdin is supported — either pipe data directly or use '-' explicitly:
+  cat spec.yaml | openapi spec clean
+  cat spec.yaml | openapi spec clean -
+
 This command uses reachability-based analysis to keep only what is actually used by the API surface:
 - Seeds reachability exclusively from API surface areas: entries under /paths and the top-level security section
 - Expands through $ref links across component sections until a fixed point is reached
@@ -52,7 +56,7 @@ Output options:
 - No output file specified: writes to stdout (pipe-friendly)
 - Output file specified: writes to the specified file
 - --write flag: writes in-place to the input file`,
-	Args: cobra.RangeArgs(1, 2),
+	Args: stdinOrFileArgs(1, 2),
 	Run:  runClean,
 }
 
@@ -64,12 +68,9 @@ func init() {
 
 func runClean(cmd *cobra.Command, args []string) {
 	ctx := cmd.Context()
-	inputFile := args[0]
+	inputFile := inputFileFromArgs(args)
 
-	var outputFile string
-	if len(args) > 1 {
-		outputFile = args[1]
-	}
+	outputFile := outputFileFromArgs(args)
 
 	processor, err := NewOpenAPIProcessor(inputFile, outputFile, cleanWriteInPlace)
 	if err != nil {