Skip to content

feat(cli): v1 spec surface — ArgSpec, option upgrades, subcommand trees, runAsync - #47

Merged
espetro merged 6 commits into
mainfrom
feat/cli-v1-commander-parity
Nov 10, 2026
Merged

espetro merged 6 commits into
mainfrom
feat/cli-v1-commander-parity

Conversation

@espetro

@espetro espetro commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

Summary

Closes the commander-parity gaps called out after the 0.6.0 release, all probe-verified under scriptc 0.4.7 (942 statements, 100% static, zero dynamic slots):

  • ArgSpec positionals: {optional, variadic, default, description, schema} — optional absent → default else null (never undefined); variadic (last only) collects into an array slot; schemas validate per element. ArgsFromSpec maps the args literal to a typed tuple via const generics; plain string[] annotations keep the legacy shape.
  • Option upgrades: optionalValue (--opt bare → true, --opt=v → "v"), variadic (--tag a b and --tag a --tag b → per-element schema → O[]), negatable (--no-x → false), env (process.env fallback through validate()), hidden, and kebab-case → camelCase opts keys ("template-engine" → opts.templateEngine, commander parity).
  • Subcommand trees: commands nests inside command() specs — recursive runtime descent (not type-encoded, per the plan doc's rationale). Options before a subcommand token bind the parent; parent opts/args/schema validate before descent. alias (shown as name|alias), hidden, prog help <path…>.
  • Program-level node: ProgramSpec carries the same args/options/schema/handler/commands — single-command CLIs need no wrapper command, and programs can mix root options with dispatch.
  • runAsync: awaits Promise-returning handlers AND Promise-returning Standard-Schema validators; run keeps both as clean errors. handler: (opts, args) => unknown avoids the void | Promise<void> union's dynamic slots.

Benchmarks (bench/apps — new workspace, bench/* glob + scriptc-gates)

cell ops/sec (Node 24)
@cutils/cli options ~840k
commander options ~460k
node:util.parseArgs ~527k
@cutils/cli subtree ~1.25M
commander subtree ~627k

ELF sizes: argv-baseline 375,888 B → cli-basic 793,640 (+418 KB) → cli-full 980,216 (+604 KB).

Test plan

  • 93/93 node --test (new: args/specs/tree/async suites)
  • scriptc coverage gate.ts 942/942 (100%), zero dynamic slots
  • bench/apps/*.ts 100% static (argv-baseline, cli-basic, cli-full)
  • elf.test.sh extended matrix green (variadic, optionalValue, negatable, env, descent, alias, help walk, async handler)
  • pnpm fmt / lint / change check
  • docs: README migration table, docs/cli.md, package AGENTS.md traps + measurements, plan doc on disk

Notes

  • Migration framing per direction: ## Migrating from commander replaces ## Divergences.
  • New subset trap recorded: as T[] on a record-read array copies under scriptc — mutate-then-store (pushVar), never cast-and-mutate. Caught by ELF smoke, invisible to coverage.
  • SC9001 nullT when scriptc consumes the dist JS — in-repo apps import src/index.ts; the npm ./elf consumer entry is a documented TODO (mirror packages/sqlite).
  • Pre-existing local env failures unchanged (ffi .a, sqlite -Bsymbolic — green in CI).

Generated with Devin

…bcommand trees, runAsync

ArgSpec positionals (optional/variadic/schema'd, ArgsFromSpec tuple
typing via const generics), OptionSpec gains optionalValue/variadic/
negatable/env/hidden + camelCase opts keys, commands nest recursively
with aliases and a help pseudo-command, ProgramSpec is a root command
node (program-level args/options/handler), runAsync awaits Promise-
returning handlers and validators. One descent loop drives all levels;
the program IS a command node.
Reframe 'Divergences from commander' as 'Migrating from commander',
document the v1 surface (arg/option specs, trees, runAsync), record
the measured bench numbers and the new subset traps (cast-copy on
record-read arrays, ProgramSpec dynamic-slot casts, SC9001 dist-JS
nullT, in-repo src imports).
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

Deploying cutilsjs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 9dfa6f2
Status: ✅  Deploy successful!
Preview URL: https://b8e4d259.cutilsjs.pages.dev
Branch Preview URL: https://feat-cli-v1-commander-parity.cutilsjs.pages.dev

View logs

Perf + build-speed release: callback signature-adapter elimination,
typed-array conversion, typed Error ctor (smaller exes), non-ASCII
regex/slice fast paths, startup layout, Math.random, capture-by-value;
build-side: cached frontend, emit-lowered/from-lowered, npm-static
diagnostics off. New lowerings incl. named process.* imports, fs Dir +
dispose, enum runtime objects, Object.freeze partial views, workspace-
pkg bare-import JS compile. All gates 100%, cli ELF smoke green (18 new
checked-dynamic warnings to triage later).
scriptc 0.4.10's smaller typed-Error lowering leaves Error.toString
undeclared on the %dyn.class.protocol dispatch path, so calling
ins.toString() through the Stmt<TRow> interface hits SC9001 in the
ELF build. Upcasting to InstanceType<typeof Stmt> (= StmtCore) gives
static dispatch; the gate keeps its toString coverage.
@espetro
espetro merged commit bd1413e into main Nov 10, 2026
3 checks passed
@espetro
espetro deleted the feat/cli-v1-commander-parity branch November 10, 2026 01:21
@espetro espetro mentioned this pull request Nov 10, 2026
3 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant