Finish auto-generated TypeScript bindings (ts feature)

[helix-nine]

Finishes the WIP feature/new-ts so the ts feature compiles and emits serde-accurate TypeScript. Driven by an adversarial review of both this branch and visit-rs (the review found 38 confirmed issues).

Companion PR (required): dr-bonez/visit-rs#1 — the metadata/rename fixes this depends on. This branch points visit-rs at that fork branch with features = ["meta"]; flip it back to a published crates.io release once visit-rs#1 merges + publishes (marked with a TODO in Cargo.toml).

Was broken

feature/new-ts did not compile: src/ts.rs's SerdeTag parsed serde attributes with syn at runtime (not a dependency), and enum serde-tagging was a // TODO stub. Even ignoring that, the enum path never emitted variant names, Option had no TS impl, u64 mapped to bigint, map keys used numeric/bigint index signatures (the latter is illegal TS), and a no_ts() child emitted bare unknown that poisoned inference for the whole tree.

Changes

• Serde enum tagging, metadata-driven. Replaced the runtime-syn SerdeTag with enum_repr, which reads the representation from visit-rs's runtime AttributeMeta. Variant::visit now emits the correct shape for all four representations and every variant kind:
  • external (default): {"V": payload}, and "V" for unit variants
  • internal #[serde(tag)]: {"tag":"V"} & payload
  • adjacent #[serde(tag, content)]: {"tag":"V"; "content": payload} (no content key for unit)
  • untagged: bare payload (null for unit)
• impl_ts_enum! macro so enums opt in (parallel to impl_ts_struct!).
• Option<T> → T | null, plus field-metadata handling in Named::visit: serde skip/skip_serializing fields are dropped, and skip_serializing_if/default make the key optional (field?:).
• Primitives: all integer widths → number (serde_json emits JSON numbers, never bigint). Maps: {[key: string]: V} regardless of key type (JSON object keys are always strings; also removes the illegal bigint index signature).
• no_ts() children emit {_PARAMS:unknown;_RETURN:unknown} instead of bare unknown, so one opted-out child no longer fails the RpcHandler constraint and poison sibling inference.
• insert_definition uses debug_assert_eq! instead of a release-mode panic! on name clashes (library code).
• --no-default-features builds: gated the impl_ts_struct! import and Empty invocation behind cfg(feature = "ts").
• Output assembly (was missing entirely): TSVisitor::into_module(root_name) renders a full module (helpers + export type for each DEFINE + the root alias), and handler_bindings(&handler, name) builds it straight from a handler tree. New examples/generate_ts.rs.

Tests

tests/ts_bindings.rs asserts the exact TS for: a renamed struct with Option/skip/skip_if/u64/Vec, all four enum representations (incl. unit/newtype/tuple/struct variants), maps, named DEFINE references + module assembly, and a full handler tree (including a no_ts child). Verified end-to-end with tsc --strict: the generated module type-checks, RpcParamType/RpcReturnType resolve correctly, mistyped payloads are rejected, and a no_ts child does not poison siblings. All build configs green (default, --no-default-features [--features cbor]).

Verified-but-deferred (from the review; not blockers for the feature)

• #[serde(flatten)] (needs hoisting inner fields via intersection) and #[serde(transparent)].
• Flat<A, B>: TS — only needed if a handler's own Params is a Flat (inherited params are represented through the parent chain in type-helpers.ts, so the common nested case works).
• ParentHandler root-handler (a directly-callable parent) is not yet surfaced in _CHILDREN.
• On the visit-rs side: generic/lifetime-enum impl generics and enum-variant-field skip in the derive (variant-field skip is handled here consumer-side via metadata).

Note: enums used with impl_ts_enum! currently need use visit_rs::{Visit, EnumInfo}; in scope (the VisitVariants derive uses method-call syntax). Worth making the derive import-free in a visit-rs follow-up.

[helix-nine]

Rebased onto master (PR base changed from feature/new-ts → master). The branch is now two clean commits on top of current master:

1. feat(ts): replace ts-rs with visit-rs-based TS bindings (WIP) — the squashed feature/new-ts work, attributed to @dr-bonez.
2. feat(ts): finish auto-generated TypeScript bindings — the finishing work.

Master's changes since the old branch point were preserved through the rebase: #[group(skip)] on Empty/Never, GenericRpcMethod over InternedString, the cli.rs additions (dyn methods / call_remote metadata / CliApp API / mutate_command), server/http.rs, and remove ts-rs default feature.

One decision to confirm: I kept ts opt-in (default = ["cbor"], matching master's remove ts-rs default feature) rather than re-adding it to default. The main reason: visit-rs is currently a git dependency (the fork branch), so having ts on by default would force every downstream consumer (e.g. start-os) to pull the git dep. Once dr-bonez/visit-rs#1 is merged + published and the dep becomes a normal crates.io dependency, flipping ts back into default is a one-liner if you'd prefer that. (The tests/test.rs and tests/ts_bindings.rs integration tests and the example are gated with required-features = ["ts"] accordingly.)

Verified after rebase: cargo build / cargo test (default, no ts) clean; cargo test --features ts → 10 passing; cargo build --no-default-features --features cbor clean; example regenerates byte-identical bindings; tsc --strict round-trip still green.

[helix-nine]

Added two more of the deferred gaps (commit 8a4ff57):

• #[serde(flatten)] → emitted as a TS intersection: {...own fields} & Inner (captures the flattened field's inner type and intersects it once the object body closes), matching serde's field-splicing.
• #[serde(transparent)] → emits the single field's type directly, no object wrapper.

Both covered by new assertions in tests/ts_bindings.rs (11 ts tests now); cargo test --features ts green.

Still deferred (documented for follow-up):

• Generic/lifetime enums (visit-rs): I attempted the impl<__visit_rs__V, …> splice fix, but it's only part of the problem — the VisitVariants derive also uses a non-hygienic 'a (collides with enum lifetimes) and omits the T: 'a / Send / Sync bounds the trait signatures require, so generic enums still won't compile. It needs the enum derive to mirror the struct derive's make_impl (hygienic '__visit_rs__a + proper bounds). Reverted the partial fix rather than ship something that doesn't actually compile for generic enums.
• Import-free VisitVariants derive (visit-rs): enums currently need use visit_rs::{Visit, EnumInfo}; in scope. DX nicety; needs the derive's method bodies to use fully-qualified calls (the struct derive already does).
• #[serde(skip)] on enum-variant fields in the derive: for the TS output, named variant fields are already skipped consumer-side via metadata; the derive-level fix (and field_count) is a rarer concern.
• Flat<A, B>: TS: only needed if a handler's own Params is a Flat (inherited params are represented through the parent chain), so not hit in the common case.

One open design question for the callable-parent gap (ParentHandler root handler) — see the thread.

[helix-nine]

Closed two more gaps (commit 4addade):

• Callable parents (your choice (b)). A ParentHandler with a root_handler is now callable at the empty method path: the parent node carries the root handler's _RETURN (its _PARAMS already equal the parent's, enforced by root_handler's Params = Params bound), and type-helpers.ts now resolves an empty method to the node's own _PARAMS/_RETURN. Single segments recurse into the child with an empty method, which unifies leaf children and directly-callable parent children. examples/generate_ts.rs now has a root_handler, and the tsc --strict round-trip confirms RpcReturnType<Api, "jobs"> resolves to the root handler's return while jobs.run still resolves as a leaf.
• Flat<A, B>: TS as a TS object intersection (A & B), matching serde's merged-object wire format for inherited params.

Also dropped the use visit_rs::{Visit, EnumInfo} imports now that the VisitVariants derive is import-free (visit-rs PR #1), and bumped the visit-rs git pin. 14 ts tests pass; default / --features ts / --no-default-features --features cbor all build warning-free.

Still deferred (one item): generic/lifetime enums in the derive. Digging in, this isn't a quick gap — it's a derive-wide rework: lifetime params fail for structs too, and the enum methods need hygienic '__visit_rs__a (done in a spike) plus per-generic-parameter bounds (T: '__a, and Send/Sync for the async stream methods) and RPITIT lifetime alignment with the trait. I reverted the partial fix rather than ship something that compiles for plain enums but still not for generic/lifetime ones. Happy to take it on as its own focused PR if you want generic enums supported — it'd touch both the struct (make_impl) and enum derives. (enum variant-field #[serde(skip)] in the derive is also still deferred — low value since named variant fields are already dropped consumer-side via metadata.)

[helix-nine]

Bumped the visit-rs pin to pick up generic enum support and added a generic-enum TS test (commit 82e8213): a generic RPC enum Resp<T> renders to TS via impl_ts_enum!(Resp<u32>) -> |{"Ok":number}|{"Err":string}. 14 ts tests pass; default / --features ts / --no-default-features --features cbor all build warning-free; tsc round-trip still green.

With this, all the previously-deferred gaps are closed (flatten, transparent, callable parents, Flat<A,B>, import-free derive, and generic enums). See dr-bonez/visit-rs#1 for the generic-enum derive work this depends on.