Skip to content

feat(cli): consumer ./elf entry + npm-static JSDoc contract - #49

Merged
espetro merged 5 commits into
mainfrom
feat/cli-elf-export
Nov 10, 2026
Merged

espetro merged 5 commits into
mainfrom
feat/cli-elf-export

Conversation

@espetro

@espetro espetro commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

What

Make scriptc build work for an app importing @cutils/cli from its npm tarball:

  1. ./elf export (3616e8e): add "./elf": "./dist/esm/index.js" to the exports map, and carry the type contract in the shipped JS itself (the .d.ts surface is hidden under --npm-static), mirroring @cutils/postgres:
    • JSDoc twins (ValidatorTwin/SchemaInputTwin/BuiltinOptsTwin) on str/num/int/bool, mergeExtra, command, normalizeOptions, normalizeArgs, normalizeSchema — fixes SC9001 field is nullT on the OptionDef/ArgDef record literals.
    • Inline literal object types for the record shapes (interfaces cannot be named without .d.ts).
    • args: unknown[] in the command() handler twin so variadic positional reads infer string[] (SC2003 union-layout error).
  2. Consumer smoke (9a6c8be + fix): packages/cli/test/consumer-elf.test.sh mirrors 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 package test script.
  3. Triage (docs commit): the remaining SC6001 copy warnings consumer builds report at factory extra merges are recorded-acceptable in packages/cli/AGENTS.md — mergeExtra only reads extra, never writes or identity-compares, so a copy is unobservable.

Verification

  • scriptc coverage gate.ts: 100% static, zero dynamic slots
  • node --test test/*.test.js test/*.test.mjs: 93 pass, 0 fail
  • bash test/elf.test.sh: OK
  • bash test/consumer-elf.test.sh: OK (zero errors, zero SC9001/SC2020/SC6104; 2-4 SC6001 copy warnings, triaged in AGENTS.md)
  • oxfmt --check / oxlint: clean
  • pnpm change @cutils/cli --bump minor intent recorded (.changeset/slow-cooks-nail.md)

@cloudflare-workers-and-pages

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

Copy link
Copy Markdown

Deploying cutilsjs with  Cloudflare Pages  Cloudflare Pages

Latest commit: ec1f24f
Status:⚡️  Build in progress...

View logs

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
espetro force-pushed the feat/cli-elf-export branch from 6ffe9e7 to ec1f24f Compare November 10, 2026 01:21
@espetro
espetro merged commit bb8e84c into main Nov 10, 2026
2 of 3 checks passed
@espetro
espetro deleted the feat/cli-elf-export branch November 10, 2026 01:24
@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