start-command 0.7.5 → 0.9.0

package/docs/PIPES.md

@@ -0,0 +1,243 @@
+# Piping with start-command (`$`)
+
+This document explains how to use pipes with the `$` command effectively.
+
+## Table of Contents
+
+- [Quick Summary](#quick-summary)
+- [The Preferred Way: Pipe TO `$`](#the-preferred-way-pipe-to-)
+- [Alternative: Quoting](#alternative-quoting)
+- [Why This Matters](#why-this-matters)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+
+## Quick Summary
+
+When piping data to a command wrapped with `$`, **put `$` on the receiving command**:
+
+```bash
+# Preferred - pipe TO the $-wrapped command
+echo "hi" | $ agent
+
+# Alternative - quote the entire pipeline (more verbose)
+$ 'echo "hi" | agent'
+```
+
+Both approaches work, but piping TO `$` is simpler and requires fewer quotes.
+
+## The Preferred Way: Pipe TO `$`
+
+The cleanest way to use pipes with `$` is to place `$` on the command that **receives** the piped input:
+
+```bash
+# Data flows: echo "hi" -> agent (wrapped with $)
+echo "hi" | $ agent
+```
+
+This works because:
+
+1. The shell creates a pipeline: `echo "hi"` piped to `$ agent`
+2. `$ agent` receives "hi" on stdin
+3. The `$` command wraps `agent`, which processes the input
+
+### Real-World Examples
+
+```bash
+# Pipe text to an AI agent
+echo "Explain this code" | $ agent
+
+# Pipe file contents to a processor
+cat file.txt | $ processor
+
+# Pipe command output to an analyzer
+ls -la | $ analyzer
+
+# Chain multiple commands, wrap the final one
+cat data.json | jq '.items[]' | $ handler
+```
+
+### When to Use This Approach
+
+Use `command | $ target` when:
+
+- You want to pipe data INTO a command that `$` wraps
+- You want the `$` logging and monitoring for the receiving command
+- You prefer minimal quoting
+
+## Alternative: Quoting
+
+You can also wrap the entire pipeline in quotes:
+
+```bash
+# Single quotes preserve the pipe literally
+$ 'echo "hi" | agent'
+
+# The $ command receives the whole pipeline as one argument
+$ 'cat file.txt | grep pattern | wc -l'
+```
+
+### When to Use Quoting
+
+Use quotes when:
+
+- You want `$` to wrap the ENTIRE pipeline (logging all commands)
+- You need the pipeline to run as a single tracked unit
+- You want a single log file for the whole operation
+
+### Quote Types
+
+| Quote Type | Behavior           | Example                |
+| ---------- | ------------------ | ---------------------- |
+| `'single'` | Everything literal | `$ 'echo $HOME \| wc'` |
+| `"double"` | Variables expand   | `$ "echo $HOME \| wc"` |
+
+## Why This Matters
+
+### Shell Parsing Order
+
+When you type a command, the shell parses it **before** any program runs:
+
+```
+Without quotes or positioning:
+    $ echo "hi" | agent
+    └───┬────┘   └──┬──┘
+        │           │
+   Command 1    Command 2
+   ($ echo "hi")   (agent)
+
+   Result: agent receives $ output, not "hi"
+```
+
+The pipe `|` is a shell operator, so the shell splits the command at that point.
+
+### Solution Comparison
+
+```
+Preferred - Pipe TO $:
+    echo "hi" | $ agent
+    └───┬────┘   └──┬──┘
+        │           │
+   Command 1    Command 2
+   (echo "hi")    ($ agent)
+
+   Result: $ agent receives "hi" - correct!
+
+Alternative - Quoting:
+    $ 'echo "hi" | agent'
+    └─────────┬──────────┘
+              │
+        Single command
+        (pipeline runs inside $)
+
+   Result: agent receives "hi" - correct!
+```
+
+## Examples
+
+### Basic Piping
+
+```bash
+# Pipe text to a command
+echo "hello world" | $ processor
+
+# Pipe file contents
+cat config.json | $ validator
+
+# Pipe command output
+git diff | $ reviewer
+```
+
+### Multiple Pipes
+
+```bash
+# $ wraps only the final command
+cat file.txt | grep "error" | $ reporter
+
+# $ wraps the entire pipeline (quoted)
+$ 'cat file.txt | grep "error" | wc -l'
+```
+
+### With Variables
+
+```bash
+# Variable expands before piping (shell handles it)
+echo "$HOME" | $ agent
+
+# Variable preserved literally (single quotes)
+$ 'echo $HOME | wc -c'
+```
+
+### Complex Commands
+
+```bash
+# Process JSON and pipe to handler
+curl -s https://api.example.com/data | jq '.items' | $ handler
+
+# Pipe to a command with arguments
+echo "analyze this" | $ agent --verbose --format json
+```
+
+## Troubleshooting
+
+### Problem: Output goes to wrong place
+
+**Symptom:** Running `$ cmd1 | cmd2` and cmd2 receives unexpected output.
+
+**Cause:** Shell parses `|` before `$` runs, so cmd2 gets `$` output.
+
+**Solutions:**
+
+1. Pipe TO $: `cmd1 | $ cmd2`
+2. Quote: `$ 'cmd1 | cmd2'`
+
+### Problem: Command not receiving stdin
+
+**Symptom:** `echo "data" | $ cmd` but cmd doesn't see the data.
+
+**Check:** Does `cmd` read from stdin? Not all commands do.
+
+**Test:** Try `echo "data" | cmd` without `$` first.
+
+### Problem: Quotes inside quotes
+
+**Symptom:** `$ 'echo "hello 'world'"'` causes errors.
+
+**Solutions:**
+
+```bash
+# Use double quotes with escaping
+$ "echo \"hello 'world'\""
+
+# Or mix quote styles
+echo "hello 'world'" | $ processor
+```
+
+### Problem: Variables not expanding
+
+**Symptom:** `$ 'echo $HOME'` prints literal "$HOME".
+
+**Cause:** Single quotes prevent expansion.
+
+**Solutions:**
+
+```bash
+# Use double quotes (escape the pipe)
+$ "echo $HOME | wc -c"
+
+# Or pipe TO $ (variable expands in source command)
+echo "$HOME" | $ wc -c
+```
+
+## Summary
+
+| Approach  | Syntax             | Best For                    |
+| --------- | ------------------ | --------------------------- |
+| Pipe TO $ | `cmd1 \| $ cmd2`   | Simple piping, less quoting |
+| Quoted    | `$ 'cmd1 \| cmd2'` | Logging entire pipeline     |
+
+The preferred approach is **piping TO `$`** - it's simpler and avoids quote complexity.
+
+## See Also
+
+- [USAGE.md](USAGE.md) - General usage guide
+- [Case Study: Issue #28](case-studies/issue-28/README.md) - Detailed analysis

package/docs/USAGE.md

@@ -0,0 +1,194 @@
+# start-command Usage Guide
+
+This document provides detailed guidance on using the `$` command effectively, including important information about shell quoting and special characters.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Using Pipes](#using-pipes)
+- [Shell Metacharacters](#shell-metacharacters)
+- [Quoting Reference](#quoting-reference)
+- [Command Examples](#command-examples)
+- [Troubleshooting](#troubleshooting)
+
+## Quick Start
+
+The `$` command wraps any shell command with automatic logging and failure reporting:
+
+```bash
+$ echo "Hello World"
+$ npm test
+$ git status
+```
+
+## Using Pipes
+
+When piping data to a command wrapped with `$`, there are two approaches. **The preferred way is to pipe TO the `$`-wrapped command**:
+
+```bash
+# Preferred - pipe TO the $-wrapped command
+echo "hi" | $ agent
+
+# Alternative - quote the entire pipeline
+$ 'echo "hi" | agent'
+```
+
+The first approach is simpler and requires fewer quotes. For detailed information about piping, see **[PIPES.md](PIPES.md)**.
+
+### Quick Examples
+
+```bash
+# Pipe text to an AI agent
+echo "Explain this code" | $ agent
+
+# Pipe file contents to a processor
+cat file.txt | $ processor
+
+# Chain commands, wrap the final one
+git diff | $ reviewer
+```
+
+## Shell Metacharacters
+
+The following characters are interpreted by the shell before reaching `$`:
+
+| Character | Name       | Purpose                               |
+| --------- | ---------- | ------------------------------------- |
+| `\|`      | Pipe       | Connects stdout to stdin              |
+| `&`       | Background | Runs command in background            |
+| `;`       | Semicolon  | Command separator                     |
+| `&&`      | AND        | Run next command if previous succeeds |
+| `\|\|`    | OR         | Run next command if previous fails    |
+| `>`       | Redirect   | Redirect stdout to file               |
+| `<`       | Input      | Read input from file                  |
+| `$`       | Variable   | Variable expansion                    |
+| `` ` ``   | Backtick   | Command substitution                  |
+| `*?[]`    | Globs      | Filename expansion                    |
+
+## Quoting Reference
+
+When you need to pass special characters literally to `$`, use quotes:
+
+| Quote Type  | Behavior                               | Use When                                |
+| ----------- | -------------------------------------- | --------------------------------------- |
+| `'single'`  | Everything is literal, no expansion    | Preserving pipes, special chars exactly |
+| `"double"`  | Variables expand, some escaping needed | Need variable expansion inside          |
+| `$'...'`    | ANSI-C quoting, escape sequences work  | Need escape sequences like `\n`, `\t`   |
+| `` `...` `` | Command substitution (old style)       | Capturing command output (prefer `$()`) |
+
+### Examples with Different Quote Styles
+
+```bash
+# Single quotes - everything literal
+$ 'echo "hello" | wc -c'
+
+# Double quotes - variables expand
+$ "echo $HOME | wc -c"      # $HOME expands first!
+
+# Double quotes with escaping
+$ "echo \$HOME | wc -c"     # \$ keeps it literal
+```
+
+## Command Examples
+
+### Simple Commands (No Quoting Needed)
+
+```bash
+$ ls -la
+$ npm test
+$ git status
+$ echo "hello world"
+```
+
+### Commands with Pipes
+
+```bash
+# Preferred: pipe TO the $-wrapped command
+echo "hello" | $ grep "h"
+cat file.txt | $ processor
+git log | $ reviewer
+
+# Alternative: quote the entire pipeline
+$ 'cat file.txt | grep pattern'
+$ 'ps aux | grep node'
+```
+
+### Commands with Redirection (Quoting Required)
+
+```bash
+$ 'echo "data" > output.txt'
+$ 'cat < input.txt'
+$ 'npm test 2>&1 | tee test.log'
+```
+
+### Commands with Logical Operators (Quoting Required)
+
+```bash
+$ 'npm install && npm test'
+$ 'command1 || command2'
+$ 'test -f file && cat file'
+```
+
+### Commands with Background Processes (Quoting Required)
+
+```bash
+$ 'npm start &'
+$ 'sleep 10 && echo "done" &'
+```
+
+### Commands with Variables
+
+```bash
+# Variable expands BEFORE $ sees it (usually what you want)
+$ echo "$HOME"
+
+# Variable is passed literally to $ (rare use case)
+$ 'echo $HOME'
+```
+
+## Troubleshooting
+
+### Problem: Pipe Output Goes to Wrong Place
+
+**Symptom:** Running `$ cmd1 | cmd2` and cmd2 receives unexpected output.
+
+**Solutions:**
+
+1. Pipe TO $: `cmd1 | $ cmd2` (preferred)
+2. Quote: `$ 'cmd1 | cmd2'`
+
+### Problem: Variables Not Expanding
+
+**Symptom:** `$ 'echo $HOME'` literally prints "$HOME"
+
+**Solution:** Use double quotes: `$ "echo $HOME"` or pipe: `echo "$HOME" | $ processor`
+
+### Problem: Special Characters Causing Errors
+
+**Symptom:** Commands with `*`, `?`, `[`, `]` behave unexpectedly
+
+**Solution:** Quote the command or escape the characters:
+
+```bash
+$ 'ls *.txt'           # Quotes prevent glob expansion by outer shell
+$ ls \*.txt            # Escape prevents expansion
+```
+
+### Problem: Command with Internal Quotes
+
+**Symptom:** `$ 'echo "hello 'world'"'` causes syntax errors
+
+**Solution:** Use different quote styles or escape:
+
+```bash
+$ "echo \"hello 'world'\""     # Use double quotes with escaping
+$ $'echo "hello \'world\'"'    # Use ANSI-C quoting
+```
+
+## Further Reading
+
+- [PIPES.md](PIPES.md) - Detailed guide on piping with `$`
+- [Bash Reference Manual - Quoting](https://www.gnu.org/software/bash/manual/html_node/Quoting.html)
+- [Bash Reference Manual - Pipelines](https://www.gnu.org/software/bash/manual/html_node/Pipelines.html)
+- [POSIX Shell Command Language](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html)
+- [Case Study: Issue #28 - Shell Quoting Analysis](case-studies/issue-28/README.md)