feat: add stdin/stdout pipeline support (closes #65)

Implement comprehensive stdin/stdout pipeline support for all CLI commands
(validate, format, analyze, parse) with Unix pipeline conventions and
cross-platform compatibility.

Features:
- Auto-detection: Commands automatically detect piped input
- Explicit stdin: Support "-" as stdin marker for all commands
- Input redirection: Full support for "< file.sql" syntax
- Broken pipe handling: Graceful handling of Unix EPIPE errors
- Security: 10MB input limit to prevent DoS attacks
- Cross-platform: Works on Unix/Linux/macOS and Windows PowerShell

Implementation:
- Created stdin_utils.go with pipeline utilities:
  - IsStdinPipe(): Detects piped input using golang.org/x/term
  - ReadFromStdin(): Reads from stdin with size limits
  - GetInputSource(): Unified input detection (stdin/file/direct SQL)
  - WriteOutput(): Handles stdout and file output with broken pipe detection
  - DetectInputMode(): Determines input mode based on args and stdin state
  - ValidateStdinInput(): Security validation for stdin content

- Updated all commands with stdin support:
  - validate.go: Stdin validation with temp file approach
  - format.go: Stdin formatting (blocks -i flag appropriately)
  - analyze.go: Stdin analysis with direct content processing
  - parse.go: Stdin parsing with direct content processing

- Dependencies:
  - Added golang.org/x/term for stdin detection

- Testing:
  - Unit tests: stdin_utils_test.go with comprehensive coverage
  - Integration tests: pipeline_integration_test.go for real pipeline testing
  - Manual testing: Validated echo, cat, and redirect operations

- Documentation:
  - Updated README.md with comprehensive pipeline examples
  - Unix/Linux/macOS and Windows PowerShell examples
  - Git hooks integration examples

Usage Examples:
  echo "SELECT * FROM users" | gosqlx validate
  cat query.sql | gosqlx format
  gosqlx validate -
  gosqlx format < query.sql
  cat query.sql | gosqlx format | gosqlx validate

Cross-platform:
  # Unix/Linux/macOS
  cat query.sql | gosqlx format | tee formatted.sql | gosqlx validate

  # Windows PowerShell
  Get-Content query.sql | gosqlx format | Set-Content formatted.sql
  "SELECT * FROM users" | gosqlx validate

Security:
- 10MB stdin size limit (MaxStdinSize constant)
- Binary data detection (null byte check)
- Input validation before processing
- Temporary file cleanup in validate command

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

Co-Authored-By: Claude <noreply@anthropic.com>

Author: 2 people

README.md

@@ -105,6 +105,8 @@ go build -o gosqlx ./cmd/gosqlx
 ## 🚀 Quick Start
 
 ### CLI Usage
+
+**Standard Usage:**
 ```bash
 # Validate SQL syntax
 gosqlx validate "SELECT * FROM users WHERE active = true"
@@ -119,6 +121,46 @@ gosqlx analyze "SELECT COUNT(*) FROM orders GROUP BY status"
 gosqlx parse -f json complex_query.sql
 ```
 
+**Pipeline/Stdin Support** (New in v1.6.0):
+```bash
+# Auto-detect piped input
+echo "SELECT * FROM users" | gosqlx validate
+cat query.sql | gosqlx format
+cat complex.sql | gosqlx analyze --security
+
+# Explicit stdin marker
+gosqlx validate -
+gosqlx format - < query.sql
+
+# Input redirection
+gosqlx validate < query.sql
+gosqlx parse < complex_query.sql
+
+# Full pipeline chains
+cat query.sql | gosqlx format | gosqlx validate
+echo "select * from users" | gosqlx format > formatted.sql
+find . -name "*.sql" -exec cat {} \; | gosqlx validate
+
+# Works on Windows PowerShell too!
+Get-Content query.sql | gosqlx format
+"SELECT * FROM users" | gosqlx validate
+```
+
+**Cross-Platform Pipeline Examples:**
+```bash
+# Unix/Linux/macOS
+cat query.sql | gosqlx format | tee formatted.sql | gosqlx validate
+echo "SELECT 1" | gosqlx validate && echo "Valid!"
+
+# Windows PowerShell
+Get-Content query.sql | gosqlx format | Set-Content formatted.sql
+"SELECT * FROM users" | gosqlx validate
+
+# Git hooks (pre-commit)
+git diff --cached --name-only --diff-filter=ACM "*.sql" | \
+  xargs cat | gosqlx validate --quiet
+```
+
 ### Library Usage - Simple API
 
 GoSQLX provides a simple, high-level API that handles all complexity for you:

cmd/gosqlx/cmd/analyze.go

@@ -1,6 +1,8 @@
 package cmd
 
 import (
+	"fmt"
+
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 
@@ -28,20 +30,34 @@ Examples:
   gosqlx analyze --all query.sql                  # Comprehensive analysis
   gosqlx analyze "SELECT * FROM users"            # Analyze query directly
 
+Pipeline/Stdin Examples:
+  echo "SELECT * FROM users" | gosqlx analyze     # Analyze from stdin (auto-detect)
+  cat query.sql | gosqlx analyze                  # Pipe file contents
+  gosqlx analyze -                                # Explicit stdin marker
+  gosqlx analyze < query.sql                      # Input redirection
+
 Analysis capabilities:
 • SQL injection pattern detection
 • Performance optimization suggestions
-• Query complexity scoring  
+• Query complexity scoring
 • Best practices validation
 • Multi-dialect compatibility checks
 
 Note: Advanced analysis features are implemented in Phase 4 of the roadmap.
 This is a basic implementation for CLI foundation.`,
-	Args: cobra.ExactArgs(1),
+	Args: cobra.MaximumNArgs(1), // Changed to allow stdin with no args
 	RunE: analyzeRun,
 }
 
 func analyzeRun(cmd *cobra.Command, args []string) error {
+	// Handle stdin input
+	if len(args) == 0 || (len(args) == 1 && args[0] == "-") {
+		if ShouldReadFromStdin(args) {
+			return analyzeFromStdin(cmd)
+		}
+		return fmt.Errorf("no input provided: specify file path, SQL query, or pipe via stdin")
+	}
+
 	// Load configuration with CLI flag overrides
 	cfg, err := config.LoadDefault()
 	if err != nil {
@@ -83,6 +99,59 @@ func analyzeRun(cmd *cobra.Command, args []string) error {
 	return analyzer.DisplayReport(result.Report)
 }
 
+// analyzeFromStdin handles analysis from stdin input
+func analyzeFromStdin(cmd *cobra.Command) error {
+	// Read from stdin
+	content, err := ReadFromStdin()
+	if err != nil {
+		return fmt.Errorf("failed to read from stdin: %w", err)
+	}
+
+	// Validate stdin content
+	if err := ValidateStdinInput(content); err != nil {
+		return fmt.Errorf("stdin validation failed: %w", err)
+	}
+
+	// Load configuration
+	cfg, err := config.LoadDefault()
+	if err != nil {
+		cfg = config.DefaultConfig()
+	}
+
+	// Track which flags were explicitly set
+	flagsChanged := make(map[string]bool)
+	cmd.Flags().Visit(func(f *pflag.Flag) {
+		flagsChanged[f.Name] = true
+	})
+	if cmd.Parent() != nil && cmd.Parent().PersistentFlags() != nil {
+		cmd.Parent().PersistentFlags().Visit(func(f *pflag.Flag) {
+			flagsChanged[f.Name] = true
+		})
+	}
+
+	// Create analyzer options
+	opts := AnalyzerOptionsFromConfig(cfg, flagsChanged, AnalyzerFlags{
+		Security:    analyzeSecurity,
+		Performance: analyzePerformance,
+		Complexity:  analyzeComplexity,
+		All:         analyzeAll,
+		Format:      format,
+		Verbose:     verbose,
+	})
+
+	// Create analyzer
+	analyzer := NewAnalyzer(cmd.OutOrStdout(), cmd.ErrOrStderr(), opts)
+
+	// Analyze the stdin content (Analyze accepts string input directly)
+	result, err := analyzer.Analyze(string(content))
+	if err != nil {
+		return err
+	}
+
+	// Display the report
+	return analyzer.DisplayReport(result.Report)
+}
+
 func init() {
 	rootCmd.AddCommand(analyzeCmd)
 

cmd/gosqlx/cmd/format.go

@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"fmt"
 	"os"
 
 	"github.com/spf13/cobra"
@@ -34,12 +35,29 @@ Examples:
   gosqlx format "*.sql"                      # Format all SQL files
   gosqlx format -o formatted.sql query.sql   # Save to specific file
 
+Pipeline/Stdin Examples:
+  echo "SELECT * FROM users" | gosqlx format    # Format from stdin (auto-detect)
+  cat query.sql | gosqlx format                 # Pipe file contents
+  gosqlx format -                               # Explicit stdin marker
+  gosqlx format < query.sql                     # Input redirection
+  cat query.sql | gosqlx format > formatted.sql # Full pipeline
+
 Performance: 100x faster than SQLFluff for equivalent operations`,
-	Args: cobra.MinimumNArgs(1),
+	Args: cobra.MinimumNArgs(0), // Changed to allow stdin with no args
 	RunE: formatRun,
 }
 
 func formatRun(cmd *cobra.Command, args []string) error {
+	// Handle stdin input
+	if ShouldReadFromStdin(args) {
+		return formatFromStdin(cmd)
+	}
+
+	// Validate that we have file arguments if not using stdin
+	if len(args) == 0 {
+		return fmt.Errorf("no input provided: specify file paths or pipe SQL via stdin")
+	}
+
 	// Load configuration with CLI flag overrides
 	cfg, err := config.LoadDefault()
 	if err != nil {
@@ -87,6 +105,83 @@ func formatRun(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+// formatFromStdin handles formatting from stdin input
+func formatFromStdin(cmd *cobra.Command) error {
+	// Read from stdin
+	content, err := ReadFromStdin()
+	if err != nil {
+		return fmt.Errorf("failed to read from stdin: %w", err)
+	}
+
+	// Validate stdin content
+	if err := ValidateStdinInput(content); err != nil {
+		return fmt.Errorf("stdin validation failed: %w", err)
+	}
+
+	// Note: in-place mode is not supported for stdin (would be no-op)
+	if formatInPlace {
+		return fmt.Errorf("in-place mode (-i) is not supported with stdin input")
+	}
+
+	// Load configuration
+	cfg, err := config.LoadDefault()
+	if err != nil {
+		cfg = config.DefaultConfig()
+	}
+
+	// Track which flags were explicitly set
+	flagsChanged := make(map[string]bool)
+	cmd.Flags().Visit(func(f *pflag.Flag) {
+		flagsChanged[f.Name] = true
+	})
+	if cmd.Parent() != nil && cmd.Parent().PersistentFlags() != nil {
+		cmd.Parent().PersistentFlags().Visit(func(f *pflag.Flag) {
+			flagsChanged[f.Name] = true
+		})
+	}
+
+	// Create formatter options
+	opts := FormatterOptionsFromConfig(cfg, flagsChanged, FormatterFlags{
+		InPlace:    false, // always false for stdin
+		IndentSize: formatIndentSize,
+		Uppercase:  formatUppercase,
+		Compact:    formatCompact,
+		Check:      formatCheck,
+		MaxLine:    formatMaxLine,
+		Verbose:    verbose,
+		Output:     outputFile,
+	})
+
+	// Create formatter
+	formatter := NewFormatter(cmd.OutOrStdout(), cmd.ErrOrStderr(), opts)
+
+	// Format the SQL content using the internal formatSQL method
+	formattedSQL, err := formatter.formatSQL(string(content))
+	if err != nil {
+		return fmt.Errorf("formatting failed: %w", err)
+	}
+
+	// In check mode, compare original and formatted
+	if formatCheck {
+		if string(content) != formattedSQL {
+			fmt.Fprintf(cmd.ErrOrStderr(), "stdin needs formatting\n")
+			os.Exit(1)
+		} else {
+			if verbose {
+				fmt.Fprintf(cmd.OutOrStdout(), "stdin is properly formatted\n")
+			}
+		}
+		return nil
+	}
+
+	// Write formatted output
+	if err := WriteOutput([]byte(formattedSQL), outputFile, cmd.OutOrStdout()); err != nil {
+		return err
+	}
+
+	return nil
+}
+
 func init() {
 	rootCmd.AddCommand(formatCmd)
 

cmd/gosqlx/cmd/parse.go

@@ -1,6 +1,8 @@
 package cmd
 
 import (
+	"fmt"
+
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 
@@ -29,13 +31,27 @@ Examples:
   gosqlx parse -f yaml query.sql                  # YAML output format
   gosqlx parse "SELECT * FROM users WHERE id=1"   # Parse query directly
 
+Pipeline/Stdin Examples:
+  echo "SELECT * FROM users" | gosqlx parse       # Parse from stdin (auto-detect)
+  cat query.sql | gosqlx parse                    # Pipe file contents
+  gosqlx parse -                                  # Explicit stdin marker
+  gosqlx parse < query.sql                        # Input redirection
+
 Output formats: json, yaml, table, tree
 Performance: Direct AST inspection without intermediate representations`,
-	Args: cobra.ExactArgs(1),
+	Args: cobra.MaximumNArgs(1), // Changed to allow stdin with no args
 	RunE: parseRun,
 }
 
 func parseRun(cmd *cobra.Command, args []string) error {
+	// Handle stdin input
+	if len(args) == 0 || (len(args) == 1 && args[0] == "-") {
+		if ShouldReadFromStdin(args) {
+			return parseFromStdin(cmd)
+		}
+		return fmt.Errorf("no input provided: specify file path, SQL query, or pipe via stdin")
+	}
+
 	// Load configuration with CLI flag overrides
 	cfg, err := config.LoadDefault()
 	if err != nil {
@@ -81,6 +97,63 @@ func parseRun(cmd *cobra.Command, args []string) error {
 	return parser.Display(result)
 }
 
+// parseFromStdin handles parsing from stdin input
+func parseFromStdin(cmd *cobra.Command) error {
+	// Read from stdin
+	content, err := ReadFromStdin()
+	if err != nil {
+		return fmt.Errorf("failed to read from stdin: %w", err)
+	}
+
+	// Validate stdin content
+	if err := ValidateStdinInput(content); err != nil {
+		return fmt.Errorf("stdin validation failed: %w", err)
+	}
+
+	// Load configuration
+	cfg, err := config.LoadDefault()
+	if err != nil {
+		cfg = config.DefaultConfig()
+	}
+
+	// Track which flags were explicitly set
+	flagsChanged := make(map[string]bool)
+	cmd.Flags().Visit(func(f *pflag.Flag) {
+		flagsChanged[f.Name] = true
+	})
+	if cmd.Parent() != nil && cmd.Parent().PersistentFlags() != nil {
+		cmd.Parent().PersistentFlags().Visit(func(f *pflag.Flag) {
+			flagsChanged[f.Name] = true
+		})
+	}
+
+	// Create parser options
+	opts := ParserOptionsFromConfig(cfg, flagsChanged, ParserFlags{
+		ShowAST:    parseShowAST,
+		ShowTokens: parseShowTokens,
+		TreeView:   parseTreeView,
+		Format:     format,
+		Verbose:    verbose,
+	})
+
+	// Create parser
+	parser := NewParser(cmd.OutOrStdout(), cmd.ErrOrStderr(), opts)
+
+	// Parse the stdin content (Parse accepts string input directly)
+	result, err := parser.Parse(string(content))
+	if err != nil {
+		return err
+	}
+
+	// CRITICAL: Always release AST if it was created
+	if result.AST != nil {
+		defer ast.ReleaseAST(result.AST)
+	}
+
+	// Display the result
+	return parser.Display(result)
+}
+
 func init() {
 	rootCmd.AddCommand(parseCmd)