Repository navigation
feat(cli): consumer ./elf entry + npm-static JSDoc contract - #49
Merged
Merged
Conversation
espetro
force-pushed
the
feat/cli-elf-export
branch
from
November 10, 2026 01:18
f133db8 to
6ffe9e7
Compare
Add "./elf": "./dist/esm/index.js" to the exports map so an app importing @cutils/cli/elf from the tarball compiles under scriptc build --npm-static. The .d.ts surface is hidden in that mode, so the shipped JS carries the type contract itself, mirroring @cutils/postgres: - ValidatorTwin/SchemaInputTwin/BuiltinOptsTwin JSDoc twins on the factory/mergeExtra/normalize* signatures and command() (SC9001 nullT on the OptionDef/ArgDef record literals without them) - inline literal object types for OptionDef/ArgDef/CommandDef shapes (interfaces cannot be named without .d.ts) - args typed unknown[] in the command() handler twin so variadic positional reads infer string[] (SC2003 union-layout error) Verified: scriptc coverage gate.ts still 100% static with zero dynamic slots; node --test 93 pass; bash test/elf.test.sh green; scratch consumer builds of gate.ts and test/elf-app.ts against the packed tarball compile error-free and run the full matrix.
Mirror packages/postgres/test/consumer-elf.test.sh: pack the package, install the tarball into a scratch app under build/consumer-smoke, compile gate.ts with --npm-static @cutils/cli, then run a CLI matrix against the resulting ELF (short/long flags, repeated + attached values, variadic option + variadic positional, subcommand descent and alias, group/root/command help, unknown command, missing argument, validator rejection). Wired into the package test script after test/elf.test.sh.
Record the SC9001 fix (JSDoc twins on the shipped JS) and triage the remaining SC6001 copy warnings from consumer builds of elf-app/gate: all are factory extra-merge sites where mergeExtra only reads the source record, so a hypothetical copy is unobservable. The consumer bar is zero errors / zero SC9001 SC2020 SC6104; SC6001 at factory call sites is documented-acceptable.
gate.ts runs the matrix in-process via run(), so every invocation exits 0 and prints error text on stdout: assert on the error strings instead of exit codes, use the tree deploy group for help descent (root help belongs to the demo program), and reuse gate's actual variadic case (two files, --dry-run, --tag a b).
espetro
force-pushed
the
feat/cli-elf-export
branch
from
November 10, 2026 01:21
6ffe9e7 to
ec1f24f
Compare
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.
What
Make
scriptc buildwork for an app importing@cutils/clifrom its npm tarball:./elfexport (3616e8e): add"./elf": "./dist/esm/index.js"to the exports map, and carry the type contract in the shipped JS itself (the.d.tssurface is hidden under--npm-static), mirroring@cutils/postgres:ValidatorTwin/SchemaInputTwin/BuiltinOptsTwin) onstr/num/int/bool,mergeExtra,command,normalizeOptions,normalizeArgs,normalizeSchema— fixes SC9001field is nullTon the OptionDef/ArgDef record literals..d.ts).args: unknown[]in thecommand()handler twin so variadic positional reads inferstring[](SC2003 union-layout error).9a6c8be+ fix):packages/cli/test/consumer-elf.test.shmirrors the postgres one — packs the tarball, installs it into a scratch app, compiles gate.ts with--npm-static @cutils/cli, runs a CLI matrix against the ELF (short/long flags, attached/repeated values, variadic option + positional, subcommand descent + alias, group help, unknown command, missing arg, validator rejection). Wired into the packagetestscript.docscommit): the remaining SC6001 copy warnings consumer builds report at factoryextramerges are recorded-acceptable inpackages/cli/AGENTS.md—mergeExtraonly readsextra, never writes or identity-compares, so a copy is unobservable.Verification
scriptc coverage gate.ts: 100% static, zero dynamic slotsnode --test test/*.test.js test/*.test.mjs: 93 pass, 0 failbash test/elf.test.sh: OKbash test/consumer-elf.test.sh: OK (zero errors, zero SC9001/SC2020/SC6104; 2-4 SC6001 copy warnings, triaged in AGENTS.md)oxfmt --check/oxlint: cleanpnpm change @cutils/cli --bump minorintent recorded (.changeset/slow-cooks-nail.md)