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]:

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)