Stage 2: TerdutTeam (create, mint team credential, rename/oidc-groups, delete)

Implements ROADMAP.md Stage 2 against terdut-server's now-real
GET /api/teams?name= (TEAM-LOOKUP.md, landed in terdut-server just
before this commit) -- without it, the adopt-on-409 pattern this
controller depends on for team creation had no server-side lookup to
call, the same gap TerdutServer's own bootstrap flow hit and fixed in
Stage 1.

- api/v1alpha1: TerdutTeamSpec per DESIGN.md §4.2 (serverRef, displayName,
  oidc). status.credentialsSecretRef drops namespace for key, matching
  the fix already applied to TerdutServer's.
- internal/controller:
  - terdutteam_controller.go: resolves serverRef (same-namespace by
    default; cross-namespace gated by the target TerdutServer's
    spec.allowedTeams, DESIGN.md §4.6), waits for that TerdutServer to be
    Bootstrapped (no cross-controller RPC -- reads its
    status.credentialsSecretRef directly, DESIGN.md §5), creates the team
    and mints its team-scoped credential using the TerdutServer's
    instance-scoped one, then applies rename/oidc-groups with the
    team-scoped credential every reconcile (both are idempotent PUTs of
    the whole resource -- applied unconditionally rather than diffed
    against a stored last-applied value, same "cheap because it's small"
    reasoning §5 already gives the escalation policy's whole-policy PUT).
  - terdutteam_allowedteams.go: the §4.6 consent check in isolation from
    any client, unit-tested directly against hand-built inputs.
  - terdutteam_bootstrap.go: create-or-adopt-on-409 for the team itself
    (via TEAM-LOOKUP.md) and for its team-scoped service account (via the
    same GET-by-name+mint-new-key pattern Stage 1 already uses for the
    instance account).
  - secrets.go: extracted TerdutServer's write/read-credential-Secret
    helpers into free functions, now shared by both controllers rather
    than duplicated.
  - Finalizer deletes the team server-side (owner-gated, needs the
    team-scoped credential -- confirmed against source that an
    instance-scoped one does not satisfy requireTeamOwner, same finding
    as TEAM-LOOKUP.md's) and cleans up its credentials Secret. A team
    created but never fully reconciled to Ready (no team-scoped
    credential ever minted) is left orphaned server-side on delete -- a
    known, documented limitation (terdut-server has no delete path that
    doesn't require owner-equivalent access), not a silent gap.
- internal/tdclient: Team type, CreateTeam, GetTeamByName, RenameTeam,
  DeleteTeam, SetTeamOIDCGroups, CreateTeamServiceAccount -- matching
  terdut-server's real handlers' shapes field-for-field, same as Stage
  1's client additions.
- Tests: envtest covering the happy path, both not-ready reasons
  (ServerRefNotFound, WaitingForServer), cross-namespace allow/deny
  (default-closed and explicit All), both adopt-on-409 paths (team
  itself, team-scoped service account), and deletion. Extended the shared
  fakeTerdutServer (Stage 1) with team endpoints rather than writing a
  second, separately-drifting fake. 72.8%/30.6% coverage, 0 lint issues.

Verified locally: make fmt lint test build all clean.

internal/tdclient/client.go

@@ -19,6 +19,10 @@ import (
 // Client talks to one terdut-server install, optionally as a service
 // account. A zero-value token works for endpoints that don't need one
 // (Version, Bootstrap).
+
+// fieldName is the JSON key every create/rename request body below shares.
+const fieldName = "name"
+
 type Client struct {
 	baseURL    string
 	httpClient *http.Client
@@ -199,8 +203,32 @@ type CreateServiceAccountResult struct {
 // this as a hard failure.
 func (c *Client) CreateInstanceServiceAccount(ctx context.Context, name string) (*CreateServiceAccountResult, error) {
 	req, err := c.newRequest(ctx, http.MethodPost, "/api/service-accounts", map[string]string{
-		"name":  name,
-		"scope": "instance",
+		fieldName: name,
+		"scope":   "instance",
+	})
+	if err != nil {
+		return nil, err
+	}
+	var result CreateServiceAccountResult
+	if err := c.do(req, &result); err != nil {
+		return nil, err
+	}
+	return &result, nil
+}
+
+// CreateTeamServiceAccount calls POST /api/service-accounts with scope
+// "team" for teamID, authenticated with c's current token -- the
+// TerdutServer's instance-scoped credential, per DESIGN.md §6 point 3: an
+// instance-scoped caller may mint a team-scoped account against any team
+// (internal/api/service_accounts.go's handleCreateServiceAccount,
+// confirmed against source), which is what lets TerdutTeam's own
+// controller do this without ever touching a human credential. Same
+// adopt-on-409 contract as CreateInstanceServiceAccount.
+func (c *Client) CreateTeamServiceAccount(ctx context.Context, name string, teamID int64) (*CreateServiceAccountResult, error) {
+	req, err := c.newRequest(ctx, http.MethodPost, "/api/service-accounts", map[string]any{
+		fieldName: name,
+		"scope":   "team",
+		"team_id": teamID,
 	})
 	if err != nil {
 		return nil, err
@@ -239,7 +267,7 @@ func (c *Client) GetServiceAccountByName(ctx context.Context, name string) (*Ser
 func (c *Client) CreateServiceAccountKey(ctx context.Context, serviceAccountID int64, name string) (*APIKey, error) {
 	req, err := c.newRequest(ctx, http.MethodPost,
 		fmt.Sprintf("/api/service-accounts/%d/keys", serviceAccountID),
-		map[string]string{"name": name})
+		map[string]string{fieldName: name})
 	if err != nil {
 		return nil, err
 	}
@@ -249,3 +277,83 @@ func (c *Client) CreateServiceAccountKey(ctx context.Context, serviceAccountID i
 	}
 	return &key, nil
 }
+
+// Team mirrors terdut-server's models.Team (internal/models/team.go), minus
+// Role/Source, which are only ever populated for a human caller's own
+// membership and never apply to a service account's view of a team.
+type Team struct {
+	ID   int64  `json:"id"`
+	Name string `json:"name"`
+}
+
+// CreateTeam calls POST /api/teams, authenticated with c's current token --
+// the TerdutServer's instance-scoped credential (DESIGN.md §6 point 3). A
+// StatusError with Code 409 means a prior, interrupted attempt already
+// created this name — GetTeamByName (TEAM-LOOKUP.md) is the adopt-rather-
+// than-error recovery, the same contract CreateInstanceServiceAccount has.
+func (c *Client) CreateTeam(ctx context.Context, name string) (*Team, error) {
+	req, err := c.newRequest(ctx, http.MethodPost, "/api/teams", map[string]string{fieldName: name})
+	if err != nil {
+		return nil, err
+	}
+	var team Team
+	if err := c.do(req, &team); err != nil {
+		return nil, err
+	}
+	return &team, nil
+}
+
+// GetTeamByName calls GET /api/teams?name=... (TEAM-LOOKUP.md) — open to
+// any authenticated caller, not just the team's own members. Returns nil,
+// nil on no match, not an error.
+func (c *Client) GetTeamByName(ctx context.Context, name string) (*Team, error) {
+	req, err := c.newRequest(ctx, http.MethodGet, "/api/teams?name="+name, nil)
+	if err != nil {
+		return nil, err
+	}
+	var teams []Team
+	if err := c.do(req, &teams); err != nil {
+		return nil, err
+	}
+	if len(teams) == 0 {
+		return nil, nil
+	}
+	return &teams[0], nil
+}
+
+// RenameTeam calls PUT /api/teams/{teamID} — owner-gated server-side
+// (requireTeamOwner), so c must hold this team's own team-scoped
+// credential, not the instance-scoped one CreateTeam used.
+func (c *Client) RenameTeam(ctx context.Context, teamID int64, name string) error {
+	req, err := c.newRequest(ctx, http.MethodPut,
+		fmt.Sprintf("/api/teams/%d", teamID), map[string]string{fieldName: name})
+	if err != nil {
+		return err
+	}
+	return c.do(req, nil)
+}
+
+// DeleteTeam calls DELETE /api/teams/{teamID} — owner-gated, same
+// credential requirement as RenameTeam. terdut-server refuses this while
+// the team has open incidents (409) — surfaced to the caller as a
+// StatusError, not retried specially here.
+func (c *Client) DeleteTeam(ctx context.Context, teamID int64) error {
+	req, err := c.newRequest(ctx, http.MethodDelete, fmt.Sprintf("/api/teams/%d", teamID), nil)
+	if err != nil {
+		return err
+	}
+	return c.do(req, nil)
+}
+
+// SetTeamOIDCGroups calls PUT /api/teams/{teamID}/oidc-groups — owner-gated,
+// same credential requirement as RenameTeam. An empty group string clears
+// that binding server-side (terdut-server's own NULLIF handling).
+func (c *Client) SetTeamOIDCGroups(ctx context.Context, teamID int64, memberGroup, ownerGroup string) error {
+	req, err := c.newRequest(ctx, http.MethodPut,
+		fmt.Sprintf("/api/teams/%d/oidc-groups", teamID),
+		map[string]string{"member_group": memberGroup, "owner_group": ownerGroup})
+	if err != nil {
+		return err
+	}
+	return c.do(req, nil)
+}