Skip to content

adding-a-domain.md

Latest commit

 

History

History
41 lines (25 loc) · 2.11 KB

adding-a-domain.md

File metadata and controls

41 lines (25 loc) · 2.11 KB
Raw

Adding a read domain

Use this checklist for a new Google API read surface. Keep the domain unavailable until its scope, client, commands, composition, and tests land together.

1. Add the scope

Add the narrowest adequate scope and description to internal/app/gro/identity.go. Add it to the non-destructive allowlist in internal/architecture/architecture_test.go. If grw will expose the domain too, add the same scope and description to internal/app/grw/identity.go; TestGrwScopesCoverGroPerService requires per-service coverage.

2. Add the API client

Create internal/api/<domain> with a concrete Client, NewClient(ctx context.Context), I/O methods taking context first, error wrapping, parsing helpers, and focused unit tests. API code must not import command packages.

3. Add the command package

Create internal/cmd/<domain> with:

  • An exported consumer-owned interface ending in Client.
  • ClientFactory, defaulting to the API package's NewClient.
  • An exported NewCommand() *cobra.Command that registers the domain leaves.
  • One file per substantial leaf and text output helpers.
  • No --json flag on resource leaves.

Use cmd.Context() in handlers and pass it to both ClientFactory and client methods.

4. Add tests

Add a function-field mock with a compile-time interface assertion, factory replacement via testutil.WithFactory, success and failure handler tests, and fixtures in internal/testutil only when multiple packages benefit. Add the domain to domainPackages and domainCommands() in internal/architecture/architecture_test.go.

5. Compose both binaries

Register the command with the gro root in internal/app/gro/root.go. Register it with grw in internal/app/grw/root.go as well so both binaries expose the read surface. If the domain also needs writes, compose its extended command there instead and follow adding a write surface.

6. Verify

make check
./bin/gro --help
./bin/grw --help

Confirm the new domain appears in both help trees, resource leaves reject --json, and the new scope descriptions appear during setup.