Skip to content

feat(cli): add @cutils/cli, a Standard-Schema-first declarative CLI builder - #45

Merged
espetro merged 6 commits into
mainfrom
feat/cutils-cli
Nov 8, 2026
Merged

espetro merged 6 commits into
mainfrom
feat/cutils-cli

Conversation

@espetro

@espetro espetro commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • @cutils/cli — a declarative CLI builder authored inside the scriptc-compilable subset: plain records + functions, zero deps, compiles into the consumer's single static ELF via scriptc build.
  • Seam-only design (SRP): argv tokenize → flag-vs-value → effective value → Standard Schema validate boundary → {opts, args} → dispatch, generated help/version, labelled errors, exit code. No type field — flag is the only parser-owned fact.
  • opts typing is 100% types.output: OptsFromOptions reads Standard Schema's phantom channel per option — bare schema objects, {schema:} specs, str()/num()/int()/bool() builtins, {flag: true} → boolean, schema-less → string, untyped fn → unknown. Literal unions / brands / morphs from arktype/zod flow through unchanged.
  • All value semantics delegated: validators receive the raw argv string and own coercion, bounds, and error messages; default runs through validate() at command() time (issues → E_BAD_OPTION, morph output becomes the default). One error channel — no library-owned "bad number".
  • Option entries accept OptionSpec, a whole schema object (arktype Type, zod schema — "~standard" unwrapped automatically), or a bare (v) => result function. Async validators rejected cleanly, never awaited.
  • Verified: 50/50 node tests, scriptc coverage gate.ts 451/451 (100%) with zero dynamic slots, ELF smoke matrix green (+326 KB measured overhead vs argv baseline).

Test plan

  • pnpm --filter @cutils/cli build && node --test packages/cli/test/*.test.js — 50/50
  • scriptc coverage packages/cli/gate.ts — 100% static
  • bash packages/cli/test/elf.test.sh — full argv matrix on the native binary
  • pnpm fmt / pnpm lint / pnpm change check clean

Generated with Devin

The command spec is a plain record literal: command() normalizes options
into a flat dispatch record and run() parses argv, generates --help/
--version, and returns an exit code. A mapped type (OptsFromOptions)
carries the options literal into the handler's opts parameter, so parse
rules, types, and help all come from one static schema — no runtime
reflection.

Subset discipline per the minicli rulebook: every lookup walks
Object.entries() (dynamic record reads are SC1090; writes are fine), the
handler crosses an (opts: unknown, args: string[]) => void boundary via a
single upcast in command() (a generic-typed local would hold a dynamic
slot), and the schema seam is a structural StandardValidator — the
official StandardSchemaV1 type's computed "~standard" key poisons
Object.entries lowering.

Verified on scriptc 0.4.7 / darwin-arm64: gate.ts compiles statically
(340/340, 100%) with zero dynamic slots, 37 node --test cases pass, and
test/elf.test.sh drives the full matrix (flags, help, version, unknown
command + suggestion, missing arg, bad number, schema rejection) through
a compiled ELF. Binary size, measured not claimed: argv-only baseline
130,016 B vs one-command @cutils/cli demo 456,088 B (+326,072 B for the
whole library) — recorded in packages/cli/AGENTS.md.

Adds the package to the fixed version group and records the release
intent.
Package page, docmd nav entry, and the README/packages/quickstart/
ARCHITECTURE tables. The package README carries the API reference and
the commander divergence table; size numbers stay in the package
AGENTS.md until a bench cell exists.
@cloudflare-workers-and-pages

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

Copy link
Copy Markdown

Deploying cutilsjs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 43ccdf8
Status: ✅  Deploy successful!
Preview URL: https://c477a4be.cutilsjs.pages.dev
Branch Preview URL: https://feat-cutils-cli.cutilsjs.pages.dev

View logs

Standard Schema mandates `issues?: ReadonlyArray<Issue>`; every
compliant library (arktype, zod, valibot) returns a readonly array,
which was not assignable to the mutable `ValidationIssue[]` the seam
declared — so `schema["~standard"]` failed to typecheck against real
validators. Verified end-to-end: an arktype `type("number>0")["~standard"]
passed as an option schema validates under scriptc Node islands.
…ypes.output

schema now takes a bare validator, the "~standard" props object, or a
whole schema object carrying "~standard" — pass an arktype Type or zod
schema directly and command() unwraps to ~standard.validate (preferred
when both paths exist; E_BAD_OPTION when neither does). Verified
end-to-end under scriptc Node islands: arktype type("number>0") and
type("'dev'|'prod'") validate natively with the library's own messages.

OptsFromOptions reads the schema's declared types.output — Standard
Schema's phantom type channel — before falling back to the primitive
type, so schema libraries drive opts inference: literal unions come
through as literal unions, unknown outputs fall back to the type-derived
primitive. StandardResult.issues is readonly per the spec (previous
commit) so real validators typecheck.
… to Standard Schema

The library now owns only the seam: argv tokenize -> flag-vs-value ->
effective value -> validate() boundary -> dispatch. Every value
semantic (coercion, bounds, literal unions, morphs) belongs to the
schema; opts types derive entirely from Standard Schema's types.output
phantom channel.

- OptionSpec loses `type`; `flag` is the only parser-owned fact
- options entries: OptionSpec | bare schema object | bare (v)=>result fn
- SchemaInput = StandardSchemaInput | ValidateFn; async rejected cleanly
- validators receive raw argv strings; returned value lands in opts
- default runs through validate() at command() — morphs apply, schema
  issues become E_BAD_OPTION
- builtins str()/num()/int()/bool() are Standard-Schema-shaped
  validators with types.output declared; num/int take {min,max}
- metavar help hints (explicit > builtin > option name); flags show none
- 50/50 node tests, gate.ts 451/451 static (100%), ELF matrix green
@espetro espetro changed the title feat(cli): add @cutils/cli, a type-first declarative CLI builder feat(cli): add @cutils/cli, a Standard-Schema-first declarative CLI builder Nov 8, 2026
@espetro
espetro merged commit 4e35681 into main Nov 8, 2026
3 checks passed
@espetro
espetro deleted the feat/cutils-cli branch November 8, 2026 21:03
@espetro espetro mentioned this pull request Nov 8, 2026
5 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