Architecture

babyctl mirrors the architectural approach used by kubectl so that contributors can reuse familiar patterns while extending the CLI to Terraform-managed infrastructure.

High-level design

• Cobra everywhere – each command is a cobra.Command registered from pkg/cmd. Commands own their flags, examples, and validation logic.
• Passthrough-first implementation – most commands currently delegate to kubectl or Terraformer binaries. This keeps the UX compatible while leaving room for native implementations later.
• Composable packages – helper libraries (printers, Terraformer helpers, API discovery) live under pkg/ so they can be reused by new commands or external tooling.

Project structure

cmd/
  babyctl/        # main.go creates the root command
pkg/
  cmd/            # CLI command implementations
  apiresources/   # Aggregates discovery information from kubectl + Terraformer
  terraformer/    # Wrappers around the terraformer CLI
  printers/       # Output helpers (tables, YAML/HCL conversion)
examples/
  api-definitions # Sample discovery data served by the API server

Keep main.go minimal—bootstrap logging, create the root command, and hand off to Cobra.

Resource discovery pipeline

1. pkg/apiresources shells out to kubectl api-resources.
2. pkg/terraformer introspects Terraformer providers and resources.
3. Results are normalised into Kubernetes-style APIResource structs and merged.
4. Commands such as babyctl api-resources, babyctl api-versions, and the discovery API server use this merged list.

This pipeline enables familiar commands such as kubectl api-resources to show Terraform resources when pointed at the babyctl API server.

Adding a command

1. Create pkg/cmd/<name>.go returning a configured *cobra.Command.
2. Wire the command up in pkg/cmd/cmd.go (or the relevant parent command) by calling the constructor.
3. Keep business logic in helper packages so the command stays thin and testable.
4. Add tests under pkg/<area> or integration tests under test/ once they exist.

Follow the same conventions as kubectl: short/long descriptions, Examples blocks, and logical flag groups.

API server

babyctl api-server exposes Kubernetes discovery endpoints only—it does not implement CRUD. The server:

• Serves /api and /apis based on the merged discovery cache.
• Reads static definitions from ~/.babyctl/apis so you can layer in your own groups/versions.
• Enables kubectl to target Terraform resources via kubectl --server=http://localhost:8080 api-resources.

See kubectl integration for hands-on steps.

Formatting and output

Printers under pkg/printers take care of rendering tables, YAML, JSON, or HCL. The convert command leans on these utilities to round-trip between formats so teams can choose the representation that fits their workflow.

Testing strategy

• Unit tests live alongside packages (e.g. pkg/apiresources/apiresources_test.go).
• Integration tests use the test-api-server.sh helper or future suites under test/ to validate CLI interactions.
• Run make test locally and rely on GitHub Actions for CI coverage.

Key dependencies

• Cobra for command parsing.
• Terraformer for discovering Terraform resources.
• Standard Go libraries for HTTP, JSON, and file IO.

Consult ARCHITECTURE.md for a more exhaustive blueprint when contributing major features.