feat: add connector mode resolution helpers for gateway (draft)

[mdheller]

Summary

This draft PR starts EF-0001 from the engineering fix backlog: make runtime connector mode selection explicit and fail-fast.

What is included now:

• cmd/gateway/connector_mode.go
  • resolves CONNECTOR_MODE
  • supports stub and k8s
  • loads Kubernetes REST config from:
    1. KUBECONFIG, if set
    2. in-cluster config otherwise
  • fails on unsupported mode or invalid k8s config
• cmd/gateway/connector_mode_test.go
  • default mode = stub
  • whitespace/case normalization
  • unknown-mode pass-through for validation

Why this PR exists

The reviewed gateway entrypoint still wires the stub connector unconditionally, even though the repository already contains a real Kubernetes connector backend. This PR captures the first implementation slice needed to close that gap.

Still TODO before merge

• wire cmd/gateway/main.go to call buildConnector(logger) instead of unconditionally instantiating the stub connector
• verify and document the intended k8s credential model in deployment docs/manifests
• optionally add startup-path tests around connector selection once main.go is updated

Related repository-native planning artifacts

• docs/meta/engineering-fix-backlog-v0.md
• docs/meta/spec-code-conformance-v1.md
• docs/spec/state-machine-v0.md
• docs/spec/openapi/control-api.v1.yaml

Notes

This PR is intentionally draft because the gateway entrypoint is not yet hooked up to the new helper.

[mdheller]

EF-0001 follow-up: main.go hookup patch

The branch already contains the connector-mode helper and tests. The only remaining code change is wiring cmd/gateway/main.go to use buildConnector(logger).

A precise patch is committed in:

• docs/meta/ef-0001-main-go-hookup.md

Minimal diff:

- var conn connector.Connector
- conn = connector.NewStubConnector()
- logger.Info("using stub connector (set USE_K8S=1 and provide kubeconfig for k8s)")
+ conn, _, err := buildConnector(logger)
+ if err != nil {
+     return fmt.Errorf("build connector: %w", err)
+ }

After this change:

• CONNECTOR_MODE=stub → stub connector (default)
• CONNECTOR_MODE=k8s → Kubernetes connector (kubeconfig or in-cluster)
• invalid k8s config fails fast at startup

Once this line is wired, EF-0001 is functionally complete.

[mdheller]

@copilot fix failed checks and conflicts

[Copilot]

EF-0001 follow-up: main.go hookup patch

The branch already contains the connector-mode helper and tests. The only remaining code change is wiring cmd/gateway/main.go to use `buildConnector(lo...

Done. cmd/gateway/main.go is now wired to buildConnector(logger) in commit 0ee7c89. The stub connector is no longer hardcoded — CONNECTOR_MODE=stub (default) uses the stub and CONNECTOR_MODE=k8s uses the Kubernetes connector with kubeconfig or in-cluster config. Invalid modes/configs fail fast at startup.

@copilot fix failed checks and conflicts

Fixed. Ran go mod tidy (commit 29eb5c3) to resolve the build failure, and wired main.go to buildConnector (commit 0ee7c89). Build and tests pass cleanly.