feat(config): @btravstack/config — one-value Config(id)(shape, options?), used by the examples

[btravers]

Summary

Adds @btravstack/config to the monorepo and uses it, closing #20's copy-pasted env-to-exit boot tail. Supersedes #34, which held the same move behind an earlier API.

One value, not two. Config(id)(shape, options?) returns a single value that is both a di port token and the module serving it from the environment, so imports: [amqpConfig] and ctx.get(amqpConfig) name the same thing. The signature mirrors @btravstack/entity's Entity(tag)(fields, options?): curried on the identity, then the field map, then an optional { prefix }. Omitted, the prefix is the screaming-snake of the identity ("AmqpConfig" → AMQP_CONFIG_URL); given, it is used verbatim. Either way the resolved prefix is validated as upper-snake at declaration.

export const amqpConfig = Config("AmqpConfig")(
  { url: z.string().min(1).default("amqp://127.0.0.1:5672"), prefetch: wholeNumber(10, 1, 1_000) },
  { prefix: "AMQP" },
);

Being one value costs nothing in adaptability, because it is a token first: its module statics are consulted only when it appears in a module's imports:. A test can hand it a literal Provider(amqpConfig)({ value }) without importing it and with no environment involved — there is a test asserting exactly that.

The examples use it

examples/order-config is deleted. It was a hand-rolled prototype of this package — the same wholeNumber, port, and describeEnvIssues — now @btravstack/config/zod and describeIssues. All three deployables traded env.ts/env.spec.ts for a config.ts.

Config no longer travels through main. RuntimeHost<Needs> already hands a runtime a Context, so runtimes declare their configs in needs and read them directly: orderAmqpRuntime() and orderApiRuntime() take no arguments at all, temporalWorkerRuntime no longer takes a namespace, and start's UNSATISFIED RUNTIME NEEDS gate proves the graph supplies them. main.ts is only the one-report boot:

Config.parse(Config.collect(OrderAmqpModule), process.env).match({
  ok: () => runMain(start(OrderAmqpModule, { runtime: orderAmqpRuntime(), probes })),
  errCases: (matcher) => matcher.with(P.tag("ConfigInvalid"), (e) => abort(describeIssues(e.issues))),
  defect: (cause) => abort(`the configuration could not be validated: ${String(cause)}`),
});

Two things fall out. ConfigInvalid is a TaggedError, so the matcher enumerates it and every oxlint-disable unthrown/no-catch-all-pattern is deleted — the P._ only existed because SchemaIssues is a single type with no discriminant. And the report aggregates every config in the graph, so three typo'd variables across two packages come back from one failed boot.

Decisions worth your attention

• PORT → HTTP_PORT in order-api. Every other variable name is unchanged. A config variable is PREFIX_KEY with a mandatory underscore, so no prefix-and-key pair joins to a bare PORT. It only bites single-word names, but PORT is the one most PaaS hosts inject. Alternatives (empty prefix, per-key name override) are discussed in the comments.
• probes.port stays a direct read. start needs it before the graph exists, and phase 1 has no API for reading one config outside a graph. It is still declared as a config so it is validated and reported with everything else; the constraint is commented at the line and belongs to phase 2.

Blocked on btravstack/di#12

Config's return type needs ConcretePortClass and PortInstance, neither published yet. They fix opposite shapes — a factory returning a data-built port needs the class name, a module exporting one needs the instance name — so neither closes the hole alone.

Built and typechecked here against a local, uncommitted pnpm-workspace.yaml override. That override is not in this diff and must not land. Merge order: di#12 merges and publishes → bump this repo's catalog off the pinned 0.1.0 → merge this.

Test plan

• build / typecheck / lint — 20/20 tasks green
• tests — 30/31; the one failure is start-core's "binds 9000 when no probe port is given", which fails on this host because something else holds 9000 (untouched code)
• @btravstack/config at 100% line and function coverage, the repo's gate for packages
• Declaration emit checked, not disabled — the examples briefly turned declaration off to dodge TS4023; reverted in d25ce6c and fixed properly in di
• Lockfile regenerated so --frozen-lockfile matches the deleted package (82377eb)
• Blocked on feat(di): export ConcretePortClass for ports built from data di#12 publishing

🤖 Generated with Claude Code

[btravers]

Two decisions for you, and one correction to what I said earlier.

1. PORT → HTTP_PORT in order-api — needs your call

Every other variable name survived unchanged. This one could not: a config variable is PREFIX_KEY with a mandatory underscore, and there is no prefix-and-key pair whose join is a bare PORT. The prefix rule rejects an empty prefix by design, so this is a real expressiveness limit, not an oversight in the example.

It only bites single-word names — DATABASE_URL, NODE_ENV, AMQP_URL all decompose fine. But PORT is the one single-word name that matters, because it is what most PaaS hosts inject. Three ways out:

1. Keep HTTP_PORT (what I did). Honest, and arguably clearer in a multi-process example where three deployables each have a port.
2. Allow { prefix: "" } so a config can own unprefixed names. Cheap, but it makes PORT and URL collide across two configs with no way to tell.
3. Per-key name override (port: { schema, name: "PORT" }). Most expressive, most surface.

I would keep 1 and revisit if a real deployment target forces it. Say the word and I will change it.

2. declaration: false — I fixed this properly instead

The examples briefly turned off declaration checking, because a composition root that exports a config emits Module<InstanceType<typeof cfg>>, which reduces to di's unexported PortInstance and raises TS4023.

That was the wrong fix and I have reverted it (d25ce6c). These packages are noEmit, so it silenced the check without saving any output — and di's own emit-guards.ts exists precisely because its examples once did this, leaving the repo green while no consumer could build. Repeating it downstream would have been the same bug wearing the same disguise.

The real fix is in btravstack/di#12: export PortInstance as well as ConcretePortClass. They fix opposite shapes, which is why neither closed the hole alone — a factory returning a data-built port needs the class name, a module exporting one needs the instance name. My earlier note in index.ts claiming "annotating the factory's return is enough" was measured on only the first shape.

Verified rather than assumed: ModuleExportingDataBuiltPort in emit-guards.ts reports TS4023 on ID and SERVICE with the export removed and rebuilt, and passes with it. The brands stay unexported, so the forgery directives still hold.

3. Correction: the order-api failure was mine, not pre-existing

I reported earlier that order-api's typecheck failed for reasons unrelated to this branch. That was wrong. order-api is green on feat/config-package with no override, and the failure came from a node_modules tree left inconsistent by an earlier unthrown override — the lockfile said 5.5.0 while the peer-resolved directories still pointed at 5.1.0, giving tsc two nominally distinct Result types.

After a clean reinstall: build/typecheck/lint 20/20, tests 30/31. The single failure is start-core's "binds 9000 when no probe port is given", which fails on this host because something else holds 9000 — untouched code, unrelated to this branch.

[btravers]

we have config