Repository navigation
feat(cli): add @cutils/cli, a Standard-Schema-first declarative CLI builder - #45
Merged
Merged
Conversation
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.
Deploying cutilsjs with
|
| Latest commit: |
43ccdf8
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://c477a4be.cutilsjs.pages.dev |
| Branch Preview URL: | https://feat-cutils-cli.cutilsjs.pages.dev |
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.
espetro
force-pushed
the
feat/cutils-cli
branch
from
November 8, 2026 20:29
6cee27e to
c216c6c
Compare
… 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 viascriptc build.validateboundary →{opts, args}→ dispatch, generated help/version, labelled errors, exit code. Notypefield —flagis the only parser-owned fact.types.output:OptsFromOptionsreads 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.defaultruns throughvalidate()atcommand()time (issues →E_BAD_OPTION, morph output becomes the default). One error channel — no library-owned "bad number".OptionSpec, a whole schema object (arktypeType, zod schema —"~standard"unwrapped automatically), or a bare(v) => resultfunction. Async validators rejected cleanly, never awaited.scriptc coverage gate.ts451/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/50scriptc coverage packages/cli/gate.ts— 100% staticbash packages/cli/test/elf.test.sh— full argv matrix on the native binarypnpm fmt/pnpm lint/pnpm change checkcleanGenerated with Devin