blobatar-cli — the terminal surface (CLI-only subset of #4) - #5

What this is

The CLI slice of #4, standing on its own: packages/cli (publishes as blobatar-cli, bin blobatar) plus the private packages/render-core param table. No service, nothing touching apps/ — zero overlap with apps/site/worker.

Opened separately so the two contributions can be judged independently: if you take #4, close this one; if you'd rather keep your worker as the only URL surface, this PR has the piece that doesn't compete with it.

The CLI

blobatar <name>                      # SVG to stdout
blobatar <name> -o alain.png --size 512
blobatar --stdin -d ./blobatars/    # batch: one name per line

• Flags speak the same vocabulary as a URL surface (--size, --background, --hue, --tone, --expression, --no-normalize) through render-core — one validation table, one set of error messages.
• SVG to stdout by default; PNG never lands on a TTY (-o, or pipe + --format png); with -o the extension decides the format and a contradicting --format errors.
• Batch: deterministic filenames (the render's own normalization, then [^A-Za-z0-9._-] → _, capped at 200 chars); every filename is precomputed and a collision aborts the whole batch listing the conflicting names — nothing partially written. Exact duplicate lines are deduped.
• Errors to stderr only, stdout carries only image bytes; exit codes 0/1.
• Plain-Node portable source (#!/usr/bin/env node, Node ≥ 18) — a deliberate, documented exception to the repo's Bun-first rule, because npx is where the non-JS-project audience lives. bunx works too.
• Published as plain JS with render-core inlined at build; runtime deps are exactly blobatar + @resvg/resvg-js (napi prebuilds, no postinstall).
• Determinism promise, stated honestly in the README: SVG byte-identical per visual-contract major; PNG bytes tied to the resvg version in the lockfile. The documented CI pattern: generate the team's blobatars in the build, commit them, diffs stay clean until a visual major.

render-core

Private (private: true, never published), bundled into the CLI's dist at build time. Contains only parseParams (strings → BlobatarOptions) and the expression string→value map — no raster, no I/O. CONTEXT.md gains the one-line glossary exception for it. The param table currently mirrors the roster this branch was written against (happy|sad|mad|idle); extending to the 9 new expressions is a two-line change if this lands. The expression lookup is guarded with Object.hasOwn — a plain-object roster answers truthily to __proto__/constructor (details in the #4 thread; your worker's oneOf has the same exposure via in).

Testing

• 46 tests across the two members: the full param table in render-core, and the CLI's whole flag/output/batch matrix in-process through an injected process seam (argv, stdin, TTY-ness, file writes) — no spawning in unit tests.
• One smoke script spawns the built bin under Node to produce a real SVG and a real PNG (napi prebuild) — same pattern as the library package's own smoke.mjs.
• Everything is wired into the member check scripts, so bun --filter '*' check covers both like every other member. Full workspace on this branch: 222 pass, 0 fail.

Open questions

• Is blobatar-cli the name you want? The npm name is free, and the @blobatar scope is unclaimed if you'd rather have an org.
• Release wiring is deliberately untouched: release.yml validates tags against the library only. Happy to extend it for the CLI once the name is confirmed — your tag convention, your call.