Add comprehensive PID access documentation and examples

[konard]

Summary

Resolves #18 by adding comprehensive documentation and examples for accessing process IDs (PIDs) of started commands.

Changes Made

📁 New Files

• examples/process-pid-access.mjs - Complete example file with 7 different scenarios demonstrating PID access

📚 Documentation Updates

• README.md - Added new "Process ID (PID) Access" section with practical examples and best practices
• README.md - Updated API reference to document command.child.pid property
• examples/README.md - Added Process Management section and usage examples

Key Features Demonstrated

✅ Multiple Access Methods:

• Via command.streams.stdout (recommended)
• Via command.start()
• Via command.stream() for streaming

✅ Comprehensive Examples:

1. Basic PID access with auto-start via streams
2. PID access with explicit start
3. Multiple commands PID tracking
4. PID access with streaming
5. Event-based processing with PID
6. PID availability timeline
7. Error handling and best practices

✅ Best Practices:

• Safe PID access with error handling
• Understanding PID availability lifecycle
• Proper process initialization
• Documentation of edge cases with fast commands

Example Usage

import { $ } from 'command-stream';

// Method 1: Access PID after starting via streams (recommended)
const command = $`ping -c 5 google.com`;
const stdout = await command.streams.stdout;

if (command.child && command.child.pid) {
  console.log(`Command PID: ${command.child.pid}`);
}

Testing

• ✅ Example file is executable and runs successfully
• ✅ Demonstrates all documented methods work correctly
• ✅ Shows proper error handling for edge cases
• ✅ Includes educational output explaining when PIDs are/aren't available

Files Changed

• examples/process-pid-access.mjs (new)
• README.md
• examples/README.md

🤖 Generated with Claude Code