smartcli/readme.hints.md

## Cross-Runtime Compatibility

### CLI Argument Parsing
The module uses a robust cross-runtime approach for parsing command-line arguments through the `getUserArgs()` utility in `ts/smartcli.helpers.ts`.

**Runtime-Specific Implementations:**

| Runtime | process.argv Structure | Preferred API | Reason |
|---------|------------------------|---------------|---------|
| **Node.js** | `["/path/to/node", "/path/to/script.js", ...userArgs]` | Manual parsing | No native user-args API |
| **Deno run** | `["deno", "/path/to/script.ts", ...userArgs]` | `Deno.args` ✅ | Pre-filtered by runtime |
| **Deno compiled** | `["/path/to/binary", "/tmp/deno-compile-.../mod.ts", ...userArgs]` | `Deno.args` ✅ | Filters internal bundle path |
| **Bun** | `["/path/to/bun", "/path/to/script.ts", ...userArgs]` | Manual parsing | Bun.argv not pre-filtered |

**Why Deno.args is Critical for Compiled Executables:**

Deno compiled executables insert an internal bundle path at `argv[1]`:
```javascript
process.argv = [
  "/usr/local/bin/moxytool",              // argv[0] - executable
  "/tmp/deno-compile-moxytool/mod.ts",    // argv[1] - INTERNAL bundle path
  "scripts",                               // argv[2] - actual user command
  "--option"                               // argv[3+] - user args
]

Deno.args = ["scripts", "--option"]  // ✓ Correctly filtered by Deno runtime
```

**getUserArgs() Logic:**

1. **Prefer Deno.args** when available (unless process.argv appears manipulated for testing)
2. **Fallback to manual parsing** for Node.js and Bun:
   - Check `process.execPath` basename
   - Known launchers (node, deno, bun, tsx, ts-node) → skip 2 args
   - Unknown (compiled executables) → skip 1 arg
3. **Test detection**: If `process.argv.length > 2` in Deno, use manual parsing (handles test manipulation)

**Key Benefits:**
- ✅ Works with custom-named compiled executables
- ✅ Handles Deno's internal bundle path automatically
- ✅ Compatible with test environments
- ✅ No heuristics needed for Deno (runtime does the work)