smartcli/readme.hints.md

## Cross-Runtime Compatibility

### CLI Argument Parsing
The module uses a robust cross-runtime approach for parsing command-line arguments:

**Key Implementation:**
- `getUserArgs()` utility (in `ts/smartcli.helpers.ts`) handles process.argv differences across Node.js, Deno, and Bun
- Uses `process.execPath` basename detection instead of content-based heuristics
- Prefers `Deno.args` when available (for Deno run/compiled), unless argv is explicitly provided

**Runtime Differences:**
- **Node.js**: `process.argv = ["/path/to/node", "/path/to/script.js", ...userArgs]`
- **Deno (run)**: `process.argv = ["deno", "/path/to/script.ts", ...userArgs]` (but `Deno.args` is preferred)
- **Deno (compiled)**: `process.argv = ["/path/to/executable", ...userArgs]` (custom executable name)
- **Bun**: `process.argv = ["/path/to/bun", "/path/to/script.ts", ...userArgs]`

**How it works:**
1. If `Deno.args` exists and no custom argv provided, use it directly
2. Otherwise, detect runtime by checking `process.execPath` basename
3. If basename is a known launcher (node, deno, bun, tsx, ts-node), skip 2 args
4. If basename is unknown (compiled executable), skip only 1 arg
5. Safety check: if offset would skip everything, don't skip anything (handles test edge cases)

This approach works correctly with:
- Standard runtime execution
- Compiled executables (Deno compile, Node pkg, etc.)
- Custom-named executables
- Test environments with unusual argv setups