devex 0.3.5

data/docs/ref/agent-mode.md

@@ -0,0 +1,46 @@
+## AI Agent Considerations
+
+### Auto-Detection of Agent Mode
+Trigger agent mode when:
+- Non-interactive terminal (`!isatty()`)
+- CI environment variable set
+- Streams are merged (stdout==stderr)
+- `MYTOOL_AGENT_MODE=1` environment variable
+- `--format=json` or other structured format requested
+
+### Agent Mode Behavior
+- No progress indicators or spinners
+- No colors or text formatting
+- Structured output preferred
+- No interactive prompts (fail instead)
+- Deterministic output ordering
+- Include metadata in structured output
+
+### Recommended Agent Invocation
+```bash
+# Explicit agent-friendly invocation
+mytool [command] \
+  --format=json \
+  --no-progress \
+  --no-color \
+  --batch
+
+# Or via environment
+export MYTOOL_AGENT_MODE=1
+mytool [command]
+```
+
+### Help for Agents
+```bash
+# Machine-readable help
+mytool --help --format=json
+
+# List available commands/flags
+mytool --list-commands
+mytool --list-flags
+mytool subcommand --list-flags
+
+# Generate shell completions
+mytool --generate-completion bash|zsh|fish
+```
+

data/docs/ref/cli-interface.md

@@ -0,0 +1,60 @@
+## Command-Line Interface
+
+### Universal Flags
+Every tool should support:
+```bash
+-h, --help                    # Show help
+-v, --verbose                 # Increase verbosity (stackable: -vvv)
+-q, --quiet                   # Suppress non-error output
+--version                     # Show version and exit
+--format=FORMAT               # Output format (json|text|csv|tsv|yaml)
+--no-color                    # Disable colored output
+--color=auto|always|never     # Color output control
+--dry-run                     # Preview what would be done
+--debug                       # Maximum verbosity for debugging
+```
+
+### Flag Conventions
+```bash
+# Short flags (single dash, single letter)
+-v              # Boolean flag
+-f filename     # With argument (space)
+-ffilename      # With argument (no space)
+-abc            # Combined boolean flags (equals -a -b -c)
+
+# Long flags (double dash, descriptive)
+--verbose                     # Boolean flag
+--file=filename              # With argument (equals)
+--file filename              # With argument (space)
+
+# Special conventions
+--                          # Stop processing flags
+-                           # Stdin/stdout placeholder
+@filename                   # Read arguments from file
+```
+
+### Exit Codes
+```bash
+0     Success
+1     General errors
+2     Misuse of shell command (invalid options, missing arguments)
+64    Command line usage error (EX_USAGE)
+65    Data format error (EX_DATAERR)
+66    Cannot open input (EX_NOINPUT)
+67    Addressee unknown (EX_NOUSER)
+68    Host name unknown (EX_NOHOST)
+69    Service unavailable (EX_UNAVAILABLE)
+70    Internal software error (EX_SOFTWARE)
+71    System error (EX_OSERR)
+72    Critical OS file missing (EX_OSFILE)
+73    Can't create output file (EX_CANTCREAT)
+74    I/O error (EX_IOERR)
+75    Temporary failure (EX_TEMPFAIL)
+76    Remote error in protocol (EX_PROTOCOL)
+77    Permission denied (EX_NOPERM)
+78    Configuration error (EX_CONFIG)
+126   Command found but not executable
+127   Command not found
+128+n Fatal signal n (e.g., 130 = 128+2 = SIGINT)
+```
+

data/docs/ref/configuration.md

@@ -0,0 +1,46 @@
+## Configuration Management
+
+### Precedence Order (highest to lowest)
+1. Command-line flags
+2. Environment variables (`MYTOOL_*` prefix)
+3. Local config file (`./.mytoolrc` or `./mytool.{json,yaml,toml}`)
+4. User config file (`~/.config/mytool/config`)
+5. System config (`/etc/mytool/config`)
+6. Built-in defaults
+
+### Configuration File Locations
+```bash
+# Standard locations (XDG Base Directory Specification)
+~/.config/mytool/           # User config directory
+~/.local/share/mytool/      # User data directory
+~/.cache/mytool/            # User cache directory
+/etc/mytool/                # System config directory
+
+# Legacy support (if needed)
+~/.mytool                   # Old-style dotfile
+~/.mytool.conf              # Old-style config
+```
+
+### Environment Variables
+```bash
+# Naming convention
+MYTOOL_CONFIG_FILE=/path/to/config
+MYTOOL_LOG_LEVEL=debug
+MYTOOL_FORMAT=json
+MYTOOL_NO_COLOR=1
+
+# Special variables
+MYTOOL_HOME              # Override base directory
+MYTOOL_DISABLE_UPDATE    # Disable auto-update checks
+MYTOOL_AGENT_MODE=1      # Force agent mode
+```
+
+### Working Directory Behavior
+1. Explicit paths in arguments are relative to CWD
+2. Config files search order:
+   - Relative to CWD first (project-specific)
+   - Relative to script location (bundled configs)
+   - Standard system locations
+3. Use `--config=PATH` to override
+4. Document this behavior clearly
+

data/docs/ref/design-philosophy.md

@@ -0,0 +1,17 @@
+## Core Design Philosophy
+
+### Unix Philosophy Foundations
+- **Do one thing well** - Each utility should have a single, clear purpose
+- **Composability** - Design for chaining with other tools via pipes
+- **Text streams as universal interface** - With structured output options for machines
+- **Silence is golden** - No output on success unless explicitly requested
+- **Fail fast and explicitly** - Clear, immediate errors with proper exit codes
+- **Idempotency** - Operations should be idempotent where possible
+
+### AI Agent Design Principles
+- **Predictable, deterministic behavior** - Same inputs always produce same outputs
+- **Structured output modes** - JSON/TSV/CSV options via flags
+- **Machine-readable errors** - Parseable error formats, not just human prose
+- **Explicit verbosity control** - Clear separation of operational output vs diagnostic info
+- **No interactive prompts in non-interactive mode** - Fail fast instead
+

data/docs/ref/error-handling.md

@@ -0,0 +1,38 @@
+## Error Handling
+
+### Error Message Format
+
+#### Human-Readable (default)
+```
+Error: Failed to parse configuration file
+  File: /home/user/.config/mytool/config.yaml
+  Line: 42
+  Reason: Unexpected token ':'
+  
+Try 'mytool --help' for more information.
+```
+
+#### Machine-Readable (--format=json)
+```json
+{
+  "error": {
+    "code": "CONFIG_PARSE_ERROR",
+    "message": "Failed to parse configuration file",
+    "details": {
+      "file": "/home/user/.config/mytool/config.yaml",
+      "line": 42,
+      "column": 15,
+      "token": ":"
+    },
+    "help": "https://docs.example.com/errors/CONFIG_PARSE_ERROR"
+  }
+}
+```
+
+### Error Categories
+- **Usage Errors**: Invalid flags, missing arguments
+- **Input Errors**: Malformed data, missing files
+- **Runtime Errors**: Network failures, resource exhaustion
+- **Configuration Errors**: Invalid config, missing required settings
+- **Permission Errors**: Insufficient privileges
+

data/docs/ref/io-handling.md

@@ -0,0 +1,88 @@
+## Input/Output Handling
+
+### Stream Usage
+- **stdin**: Primary input data (when no file specified)
+- **stdout**: Primary output, pipeable data only
+- **stderr**: Errors, warnings, progress indicators, diagnostics
+
+### Core Principle
+`stdout` should be immediately pipeable - never mix status messages with data output.
+
+### Stream Behavior Examples
+```bash
+# Good - clean separation
+$ mytool process data.txt > output.txt
+Processing 1000 records...    # to stderr
+[progress bar]                # to stderr
+Done!                         # to stderr
+# output.txt contains only data
+
+# Bad - mixed output
+$ mytool process data.txt > output.txt
+Processing 1000 records...    # to stdout (contaminating)
+{"data": "actual output"}     # to stdout
+Done!                         # to stdout (contaminating)
+```
+
+### Handling Merged Streams (2>&1)
+
+#### Detection
+```python
+import os
+import sys
+
+streams_merged = os.fstat(sys.stdout.fileno()) == os.fstat(sys.stderr.fileno())
+```
+
+#### Adaptation Strategies
+
+1. **Automatic Mode Switching**
+   ```bash
+   # When streams merged detected:
+   - Suppress all progress/status to stderr
+   - Switch to structured output if available
+   - Use line prefixes for critical messages
+   ```
+
+2. **Prefixed Output Pattern**
+   ```
+   ERROR: Failed to process record 5
+   WARNING: Using deprecated format
+   DATA: {"actual": "data", "here": true}
+   PROGRESS: 50/100 records processed
+   ```
+
+3. **Structured Output Mode**
+   ```json
+   {"type":"progress","current":0,"total":1000}
+   {"type":"data","content":{"id":1,"value":"foo"}}
+   {"type":"warning","message":"Deprecated field 'bar'"}
+   {"type":"data","content":{"id":2,"value":"baz"}}
+   {"type":"result","status":"success","records":1000}
+   ```
+
+### Interactive vs Non-Interactive
+
+```bash
+# Detection
+if [ -t 0 ] && [ -t 1 ]; then
+    # Interactive: colors, prompts, progress bars OK
+else
+    # Non-interactive: plain output, no prompts
+fi
+
+# Override flags
+--interactive     # Force interactive mode
+--batch          # Force non-interactive mode
+--no-tty         # Assume no terminal
+```
+
+### Pipeline Safety
+```bash
+# Guarantee clean stdout for pipelines
+--pipe           # Equivalent to: --quiet --format=text --no-progress
+
+# Usage
+mytool process --pipe < input.txt | next-tool
+```
+

data/docs/ref/signals.md

@@ -0,0 +1,141 @@
+## Signal Handling
+
+### Standard Signal Behavior
+
+#### Core Signals
+```bash
+SIGINT (2)    # Ctrl-C: Graceful interruption
+SIGTERM (15)  # Graceful termination request
+SIGQUIT (3)   # Ctrl-\: Quit with core dump
+SIGHUP (1)    # Hangup: Reload configuration
+SIGUSR1 (10)  # User-defined: Often toggle debug
+SIGUSR2 (12)  # User-defined: Often rotate logs
+SIGPIPE (13)  # Broken pipe: Handle gracefully
+SIGALRM (14)  # Timer expired
+SIGCHLD (17)  # Child process status change
+```
+
+#### SIGINT (Ctrl-C) Handling
+```bash
+# Graceful interruption pattern
+handle_sigint() {
+    echo "Interrupt received, cleaning up..." >&2
+    cleanup_temp_files
+    save_progress
+    exit 130  # 128 + 2 (SIGINT)
+}
+trap handle_sigint INT
+
+# Progressive interruption
+First Ctrl-C:  "Gracefully stopping... (press again to force)"
+Second Ctrl-C: "Force stopping..."
+Third Ctrl-C:  Immediate termination
+```
+
+#### EOF (Ctrl-D) Handling
+```bash
+# Ctrl-D sends EOF, not a signal
+# Proper handling in interactive mode:
+while IFS= read -r line; do
+    process_line "$line"
+done
+# Ctrl-D here ends input gracefully
+
+# Detection and response
+if [ -t 0 ]; then  # Interactive terminal
+    echo "Press Ctrl-D or type 'exit' to quit"
+fi
+```
+
+#### SIGHUP Configuration Reload
+```bash
+# Standard SIGHUP behavior
+handle_sighup() {
+    echo "Reloading configuration..." >&2
+    reload_config
+    reopen_log_files  # Important for log rotation
+    reset_connections
+}
+trap handle_sighup HUP
+
+# Usage
+kill -HUP $(pidof mytool)  # Reload config
+```
+
+### Signal Safety
+
+#### Critical Section Protection
+```bash
+# Prevent interruption during critical operations
+critical_section_start() {
+    trap '' INT TERM  # Ignore signals
+    CRITICAL=1
+}
+
+critical_section_end() {
+    CRITICAL=0
+    trap handle_sigint INT
+    trap handle_sigterm TERM
+    # Process any pending signals
+    if [ -n "$PENDING_SIGNAL" ]; then
+        kill -s "$PENDING_SIGNAL" $$
+    fi
+}
+```
+
+#### Cleanup Guarantees
+```bash
+# Ensure cleanup happens
+cleanup() {
+    local exit_code=$?
+    set +e  # Don't exit on errors during cleanup
+    
+    # Remove temp files
+    rm -f "$TMPFILE"
+    
+    # Release locks
+    flock -u 9 2>/dev/null
+    
+    # Restore terminal settings
+    stty "$SAVED_STTY" 2>/dev/null
+    
+    # Kill child processes
+    jobs -p | xargs kill 2>/dev/null
+    
+    exit $exit_code
+}
+trap cleanup EXIT INT TERM
+```
+
+### Signal Propagation
+
+#### Child Process Management
+```bash
+# Propagate signals to children
+handle_signal() {
+    local signal=$1
+    # Send signal to process group
+    kill -$signal 0  # 0 means current process group
+    wait  # Wait for children to terminate
+}
+
+# Start processes in same group
+set -m  # Enable job control
+mytool &
+child_pid=$!
+```
+
+#### Background Job Handling
+```bash
+# Proper daemon signal handling
+--daemon
+--pidfile=/var/run/mytool.pid
+--signal-forward  # Forward signals to workers
+
+# Signal commands
+mytool signal reload    # Send SIGHUP
+mytool signal stop      # Send SIGTERM
+mytool signal kill      # Send SIGKILL
+mytool signal status    # Check if responding
+```
+