Document comprehensive signal handling for SIGTERM, CTRL+C, and other signals

[konard]

📋 Summary

This PR provides comprehensive documentation for signal handling in command-stream, specifically addressing issue #15 by documenting how to send SIGTERM, CTRL+C (SIGINT), and other signals to executed commands.

Fixes #15

🚀 What's Added

Enhanced README Documentation

• Comprehensive Signal Handling Section: Expanded the existing signal handling documentation to cover all Unix signals, not just CTRL+C
• Signal Reference Table: Complete table of all standard Unix signals with descriptions and use cases
• Signal Exit Codes: Detailed explanation of the 128 + N formula for signal exit codes
• Programmatic Signal Control: Examples showing how to use runner.kill() with different signal types
• Graceful Shutdown Patterns: Production-ready SIGTERM → SIGKILL escalation examples
• Interactive Command Examples: How to handle commands like ping that ignore stdin but respond to signals

New Example Files

1. examples/signal-handling-demo.mjs - Comprehensive demonstration of all signal types with exit code validation
2. examples/sigterm-sigkill-escalation.mjs - Production-ready graceful shutdown patterns with configurable timeouts
3. examples/ctrl-c-vs-sigterm.mjs - Detailed comparison explaining the semantic differences between SIGINT and SIGTERM

📚 Documentation Coverage

Signal Types Documented

Signal	Number	Exit Code	Description
SIGINT	2	130	Interrupt (CTRL+C)
SIGTERM	15	143	Graceful termination (default)
SIGKILL	9	137	Force termination
SIGUSR1	10	138	User-defined signal 1
SIGUSR2	12	140	User-defined signal 2
SIGHUP	1	129	Hang up / reload
SIGQUIT	3	131	Quit with core dump

Usage Patterns Covered

// Basic signal sending
runner.kill();              // Default SIGTERM → Exit code 143
runner.kill('SIGINT');      // CTRL+C equivalent → Exit code 130  
runner.kill('SIGKILL');     // Force kill → Exit code 137

// Graceful shutdown with escalation
async function gracefulShutdown(runner, timeout = 5000) {
  runner.kill('SIGTERM');   // Try graceful first
  setTimeout(() => {
    runner.kill('SIGKILL'); // Force if timeout exceeded  
  }, timeout);
}

// Interactive command termination
const pingRunner = $`ping 8.8.8.8`;
setTimeout(() => pingRunner.kill('SIGINT'), 3000); // Stop after 3s

🧪 Testing

• ✅ All existing signal handling tests pass (13 tests)
• ✅ New examples execute successfully and demonstrate expected behavior
• ✅ Documentation examples validated against actual library behavior
• ✅ Exit codes verified to match Unix signal conventions (128 + signal number)

🎯 Addresses Issue #15

This PR directly addresses the request in issue #15 to "Document how to send SIGTERM (CTRL+C) and other signals to executed command" by:

1. Expanding beyond CTRL+C: Documents SIGTERM, SIGKILL, SIGUSR1/2, and all standard Unix signals
2. Providing practical examples: Shows real-world usage patterns for different scenarios
3. Explaining semantics: Clarifies when to use SIGINT vs SIGTERM vs SIGKILL
4. Production-ready patterns: Includes graceful shutdown with escalation examples
5. Interactive command handling: Addresses commands that ignore stdin but respond to signals

📖 Key Learning Points

• SIGINT (CTRL+C): User interruption → Use when user wants to cancel
• SIGTERM: Graceful termination → Use for clean shutdown requests
• SIGKILL: Force termination → Last resort, cannot be caught
• Exit codes: Follow 128 + signal_number formula
• Graceful patterns: Always try SIGTERM before SIGKILL
• Interactive commands: Use signals, not stdin, for commands like ping

The documentation now provides complete guidance on signal handling, making it easy for users to implement proper process lifecycle management in their applications.

🤖 Generated with Claude Code