fix(connection): resolve --rule-transform-name as a name or ID

[leggetter]

--rule-transform-name said "Name or ID" but always sent the value as transformation.name. The API matches by name and creates a transformation when the name is new, even with no code. So passing an ID, or a mistyped name, returned 200 and attached a new, empty transformation. That transformation failed every event with TypeError: undefined requires parameter 1 to be a string.

The CLI now resolves the value before sending, on create, update and upsert:

--rule-transform-name	No --rule-transform-code	With --rule-transform-code
Existing ID or exact name	Attached by transformation_id	Attached by transformation_id; code/env update it
Unknown name	Error: not found	New transformation with that name (unchanged)
Unknown trs_… ID	Error: not found	Error: not found

• update and upsert now require --rule-transform-name when transform code or env is given, as create already did
• --rules / --rules-file are unchanged and sent as given
• Help text and REFERENCE.md now say that code and env replace an existing transformation's, since a transformation can be shared by several connections

Root cause in core

• processToPersistableRules calls TransformationController.create(…, create_or_update = true). That looks up {team_id, name} and creates on a miss.
• Request validation uses the transformation update schema, where code is optional.
• The code column is nullable: table.text('code').notNullable; in the migration is missing its ().
• So an unknown name with no code is persisted with empty code. This is the same symptom as hookdeck/core#5618 (fixed in hookdeck/core#5619 for /transformations/run). A core-side guard is being raised separately, so other clients (API, MCP, Terraform) are covered too.

Implementation

• New resolveRuleTransformation in pkg/cmd/connection_transform_rule.go, called after buildConnectionRules in all three commands. It sits outside the builder so it doesn't conflict with fix(connection): build rules in flag order #464.
• findTransformationID tries GET /transformations/{id} for trs_ values, then lists by name and requires an exact match, because the list filter can return near matches.
• When the transformation is found, the rule becomes {"type":"transform","transformation_id":…}. Code and env go in transformation without name, so an ID is never sent as a new name. Core treats that as an update of the referenced transformation (ProcessRule.ts, transformation_id branch).
• Costs one extra lookup per command that uses --rule-transform-name.

Tests

• Unit (connection_transform_rule_test.go), using a fake client:
  • attach by ID and by name
  • an ID with code and env (no name sent)
  • an unknown name without code, using a near-match name to prove exact matching
  • an unknown ID, even with code
  • an unknown name with code (create, unchanged)
  • code without a name
  • --rules untouched with no lookups
  • lookup errors propagated
• Acceptance TestConnectionTransformRuleNameOrID (connection tag):
  • attach an existing transformation by ID and by name, then check the stored transformation_id
  • an unknown ID or name fails with "not found", and no transformation is created with that name
• go vet and go test ./pkg/... pass. The acceptance test runs in CI.

🤖 Generated with Claude Code