Port Client Component

Port a Client Component to Sibling Clients

You are porting a component or feature that already works in one protocol client template to one or more sibling clients that are missing it, within packages/templates/clients/<protocol>/* (currently: websocket — javascript, python, dart, java/quarkus; kafka — java/quarkus). This is a recurring shape in this repo — a capability lands in one client and sibling clients for the same protocol never get the equivalent treatment.

Read AGENT.md sections 2.5 (release hygiene / changesets) and 4.7 (baked-in templates) before executing — this skill's closing steps depend on both.

Invocation

The user must name three things explicitly:

1. The feature/component, in words.
2. The reference client that already has it (language, and framework where applicable, e.g. java/quarkus).
3. One or more target clients missing it.

If any of the three is missing, ask via AskUserQuestion. Do not guess reference/target/feature from a bare GitHub issue number or URL: extracting them from free-form issue text requires interpretation and risks misidentifying which client is the reference on a vaguely-worded issue. The user names it; you don't guess it.

Preconditions (fast gate)

Check in order; stop and report on the first failure:

1. Protocol match

The reference and every target must live under the same packages/templates/clients/<protocol>/ directory. Cross-protocol porting (e.g. websocket → kafka) is out of scope — stop and tell the user.

2. Target-lacks-it

For each target, Grep for an equivalent construct using the feature's key terms from the user's description. If a target already has it, drop it from the target list and tell the user why — never overwrite working code to "match" a reference.

Research phase

Work through these in order — each produces an artifact the execution steps consume directly. Print each artifact back to the user as you produce it.

1. Locate the reference implementation

Grep the reference client's template/ and components/ directories and its committed runnable example at the template root (example.py / example.js / example.dart — hand-maintained mirror of the generated example, not build output) for the feature's key terms (from the user's description). List the matches as "the reference files." A hit in the root example file makes the target's root example file an injection point too — that file is what the client README's manual test actually runs, so omitting it ships a port the documented test never exercises. This step also proves the reference actually has the feature: if the matches are ambiguous, ask the user to point at the specific file(s) rather than guessing; if nothing plausible turns up and the user can't point at a file either, stop and report "feature not found in reference client."

2. Check sibling implementations for divergence

Grep the other sibling clients that already have this feature — not just the named reference. If a sibling's implementation behaviorally diverges from the reference (observable test: the reference only registers/stores something while a sibling also applies it in the runtime path, or their generated methods differ in what they do rather than how they say it), surface the divergence via AskUserQuestion and let the user pick which behavior to port — before any translation. Do not silently mirror the reference when a more complete sibling exists, and do not silently "improve" on the reference either; the choice is the user's, and it must be made before the golden snippet is written because the snippet encodes it.

3. Classify the mechanism

Check whether any reference file imports from @asyncapi/generator-components for this feature. This determines which execution branch applies:

• Branch A means the shared component already exists in packages/components/src/components/, built on a per-language config map (the QueryParamsVariables shape: a top-level object keyed by language, values either a function or a framework-keyed sub-object, e.g. java: { quarkus: (param) => … }). Deterministic — the shared component already knows how to render every language, it's just missing entries/wiring for the targets.
• Branch B requires cross-language translation, which is a judgment call rather than a mechanical copy.

Don't assume Branch A because a shared components package exists — confirm the specific reference files actually import from it. A reference client can have template-local logic even when unrelated shared components exist for other features.

A feature can span both branches — e.g. a local register method and constructor field (B) plus a shared example component missing the target's config entry (A). Classify each reference file separately: the branch applies per file, and a mixed feature runs both execution sections, each for its own files.

4. Map injection points

For each target client, find the file(s) structurally equivalent to the reference files — same relative path under that client's directory (the <framework> segment adds one directory level for stack-specific clients like java/quarkus). Record one row per (reference file × target) pair in a markdown table and print it back to the user:

Structural equivalence is by role, not always by filename — e.g. python declares instance fields in Constructor.js while dart declares them in ClientFields.js; the root example file's equivalent is the target's own root example file.

This table is the injection map — the execution steps edit exactly these target files and no others, with one exemption: Branch A additionally edits the shared component itself under packages/components/ (its config map and Language typedef in src/components/<Component>.js, and its test in test/components/<Component>.test.js). Those files are per-feature rather than per-target, so they are not rows in this table; the Branch A execution steps name them explicitly. If a target has no structurally equivalent file at all (Exists? = no — the feature would need an entirely new file, not an edit to an existing one), flag that row — that's a bigger change than this skill's mechanical scope assumes, and the user should confirm before you proceed.

Translation protocol (run for every target language, in both branches)

Any step that writes target-language code is a cross-language translation — the code strings inside a Branch A config-map entry just as much as Branch B's template-local logic. Translation is the one judgment call in this skill, so never translate freely from general language knowledge; anchor every choice to something checkable in this repo by running these two steps before writing any code. Their output is what the closing steps verify deterministically: the snapshot diff there must match the golden snippet produced here.

1. Build an idiom map from repo precedent

Break the reference logic into its constructs (env-var read, null/absence check, map assignment, string interpolation, error raise, …). For each construct, find how the target language already expresses it in this repo and record one row per construct — print the table back to the user:

Precedent sources, in priority order:

1. The target client's own template/ and components/ files (Grep them for the construct).
2. In Branch A, the sibling entries already in the shared component's config map — they show the exact shape and style the new entry must match.

Repo precedent wins over textbook syntax: it matches the style the generated client already uses, keeps snapshot churn minimal, and turns free-form translation into filling in a table. Only fall back to general language knowledge for a construct with no precedent anywhere in the repo — and mark that row (no precedent) so the user knows which lines rest on judgment alone.

2. Write the golden snippet before any template code

Using the idiom map, author the exact target-language code the generated client file should contain after the port, and print it to the user. The snippet must mirror the reference 1:1 — same structure, same order of operations, same variable roles; no "improvements," no restructuring. The goal is behavioral parity, not a better implementation. This is the expected answer the closing steps' snapshot diff is checked against — writing it first means that diff is compared to a committed intent, not eyeballed for plausibility.