implement-capability

# Implement a capability You are closing one row of the capability matrix. The deliverable is a draft PR the maintainer can merge without rework: a minimal, discoverable public API they approved up front, behavior that matches the capability's contract on every path, tests written first that cover and mutation-proof every changed line, and a passing gate. Standards, in force throughout — read the sections you touch and treat them as a checklist, not background: - `../_shared/references/CONVENTIONS.md` — how the code looks (v8 column for anything marked v9). - `../_shared/references/QUALITY_RUBRIC.md` — when it is done. - `references/sources.md` — where each area's contract, reference and C# home live. Several features at once → follow `references/parallel.md` instead of running the phases below yourself. ## Input A feature card: area, group, name, description, **key**, status, optional note. The key is the identity: everything else is looked up from it. A bare key is enough. ## 1. Locate Resolve the key to its sources (`references/sources.md`): 1. The canonical entry in `capabilities/<area>.yaml` — confirm the key exists and the name/description match the card. 2. The capability spec `specs/<area>/<group>/<method>.md`, **if one exists**. It is normative: it states the SDK-layer obligations (defaults, state changes, checks before the wire) and wins over everything else. 3. The service's API spec (OpenAPI) — the operations, request/response shapes, status codes and error codes. Present for most features even without a capability spec. 4. The supabase-js implementation — read it to learn the behavior, not the code. 5. The current C# surface: `grep -rn '"<key>"' packages` for an existing `[PartialCapability]`, the client interface that owns the group, neighbouring methods, the package's test `Support/` fixtures. 6. Open issues: `gh issue list --repo supabase/supabase-csharp --search "<name>" --state all`. 7. Whether the local stack serves the feature: the service's own configuration defaults (for auth, `internal/conf` in supabase/auth), then what `supabase/config.toml` overrides. The CLI sets only what `config.toml` exposes, so a missing CLI option does not mean the feature is off. Confirm against the running stack before calling a path untestable. If the capability cannot apply to a .NET SDK (browser-only API, platform storage), stop and report why instead of building it. ## 2. Contract Write the behavior contract — the single artifact every later phase reads. It ends up verbatim in the PR description. - **Operations**: method + path for each call, and the auth it needs (user JWT, service role, anon). - **Inputs**: required vs optional, defaults the SDK fills in, checks the SDK makes before the wire. - **Outputs**: what the caller gets back, and how an empty or absent body maps to it. - **Failures**: each server answer the caller can hit (status, `error_code`) and the typed exception/reason it becomes; argument misuse that throws `ArgumentException` before I/O. - **State**: anything the SDK stores, clears or emits (session, events). - **Reference deltas**: what supabase-js does that this SDK deliberately does differently, and why. The capability spec and the API spec are the contract; supabase-js fills gaps and shows the edges. **Never port, transliterate or adapt JS code.** JS idioms (untyped option bags, string unions, `{ data, error }` tuples, swallowed errors) do not carry over, and where the JS is loose the C# does better. Where the sources disagree, the capability spec wins, then the API spec, then supabase-js; note the disagreement in the PR. For a `partially_implemented` card, the contract is the gap the existing note describes; everything already shipped stays as is. ## 3. Propose the public API — stop for approval Present what a developer will see, and nothing else: ``` Placement: IGotrueAdminClient (Supabase.Gotrue) — next to <neighbour> Use case: Gotrue/CreateCustomProvider/ — <its types>; Common/: <types shared with other use cases, or "none"> Signature: Task DeleteOAuthClientAsync(string clientId, CancellationToken cancellationToken = default); New types: <public records/enums with their members, or "none"> Throws: GotrueException (Reason = FailureHint.Reason.X) when …; ArgumentException when … Example: var admin = new AdminClient(serviceRoleKey, options); await admin.DeleteOAuthClientAsync("my-client-id"); Deviations: <from supabase-js, with the reason, or "none"> ``` Design rules: v8 error model (throw the package's typed exception, no `Result`); `Async` suffix and a trailing `CancellationToken` that reaches the HTTP call; immutable `init`-only records for new request/response/options types; read-only collections; enums over strings; one optional `XxxOptions` record over a parameter list; names from .NET/Supabase vocabulary, not JS; consistent with the neighbouring members a caller already knows; nothing public that a caller does not need. **Wait for the maintainer's approval.** Do not write production code before it. Revise and re-present on feedback. ## 4. Branch From the repository root, on a fresh branch off the latest master — never on the maintainer's current checkout: ``` git fetch origin master git worktree add ../wt/<key> -b feat/<key> origin/master ``` Work only inside that worktree from here on. If the feature needs a service enabled on the local stack, change `supabase/config.toml` in the branch (CI starts the stack from it) and restart the local stack once. ## 5. Drive — double-loop TDD 1. **Outer loop: a failing E2E** (`[TestCategory("E2E")]`) proving the approved example works against the real stack. Self-isolating: unique names, guaranteed teardown. Reuse the package's E2E fixture. When the test needs state that another, unimplemented capability creates (a provider to delete, a client to update), seed it through the service's API from the test with a plain `HttpClient`, never through SDK code that does not exist yet. 2. **Inner loop**, red → green → refactor, through the public surface only: - **Contract** (`[TestCategory("Contract")]`): the package's WireMock server pins method, path, headers, query and the mapping of every failure in the contract to its exception. - **Wire-shape approval** (`Contract`, the package's `RequestApprovalFixture` + Verify): snapshot the exact request body. Review the `.verified` file: the approved bytes must match the API spec. - **Unit** (`[TestCategory("Unit")]`): pure logic, checks before the wire. 3. Every failure and edge in the contract has a test. A test that is awkward to write is design feedback: change the API, never expose an internal or add test-only production code. Test style: `Sut_ShouldConsequence_GivenScenario`; class named for the element under test, in the use-case folder that mirrors production (`Gotrue.Tests/CreateCustomProvider/`, CONVENTIONS §2); FluentAssertions fluent and inline; NSubstitute for collaborators; reason strings cite the spec; no magic numbers; no comments. Inner loop: `scripts/quality-gate/gate.sh packages/<Name> --fast`. ## 6. Refine - Orchestration reads as named intent; mechanics in named private helpers. No comments in code. - Use-case layout (CONVENTIONS §2): every new type sits in the folder of the one use case that uses it; the product's `Common/` holds only what two or more use cases share. When a later capability needs a type an earlier one created, the later PR moves it to `Common/`. - XML `<summary>` on every new public member, `<example>` on the entry point — on the interface; the implementation uses `<inheritdoc/>`. - `ConfigureAwait(false)` on every await; the token reaches the HTTP call. - New I/O participates in the package's instrumentation. - Annotate the entry point: `[ImplementedCapability("<key>")]` — or swap an existing `[PartialCapability]` for it. Supporting types are not annotated. Never edit `sdk-compliance.yaml`; it is generated after merge. - Declare the new public surface with the analyzer, not by hand: `dotnet format analyzers packages/<Name>/<Name>/<Name>.csproj --severity info --diagnostics RS0016 RS0017`. It writes the exact entries (enum ordinals included) to `PublicAPI.Unshipped.txt`. ## 7. Verify All three, in this order; each must pass before the next: 1. **Changed-line coverage — 100%.** `python3 -I .claude/skills/implement-capability/scripts/changed-lines-coverage.py packages/<Name>` exits 0. Each `UNCOVERED` line is either a missing test or dead code to delete. 2. **Mutation — zero survivors on changed lines, and every changed line tested.** In the worktree, `--since` finds no changes, so name each changed production file: ``` (cd packages/<Name>/<Name>.Tests && STRYKER_MUTATION=true dotnet stryker -m '**/<File>.cs' -m '**/<Other>.cs') scripts/quality-gate/gate.sh packages/<Name> --mutation ``` Then list the mutants on changed lines from `StrykerOutput/*/reports/mutation-report.json` with their status. A survivor is a missing assertion, or code that does nothing. A run that tested no mutant on the changed lines is not a pass, whatever the gate prints: find out why (compile errors, filters) and rerun. 3. **Full gate** — invoke `sdk-quality-gate` on `packages/<Name>`. PASS is required. If the local stack is unavailable or shared with parallel work, the local verdict is INCOMPLETE; then the CI run on the draft PR is the gate (step 8). Then walk QUALITY_RUBRIC §8 item by item, and re-read the diff as the reviewer: anything that would draw a comment is fixed now. ## 8. Ship 1. Commit with `feat(<product>): <what a caller can now do>` — product = `auth`, `storage`, `postgrest`, `realtime`, `functions`, `supabase`. No co-author trailer, no generated-by footer. 2. `git push -u origin feat/<key>`. 3. `gh pr create --draft --base master` with the body from `references/pr-template.md`. No generated-by footer. 4. `gh pr checks <number> --watch`. Every check green — `Build and Test` (full gate incl. E2E), `Mutation`, `Validate capability annotations`. Fix and push until they are. 5. Report: PR link, gate verdict, coverage and mutation results, deviations, anything left for the maintainer's judgment. ## Never - Copy, transliterate or adapt supabase-js code. - Write production code before the API is approved. - Introduce a `Result` type or any v9 construct on v8 surface. - Edit `sdk-compliance.yaml`, a `.gate-baseline.json`, or analyzer severities to get green. - Suppress a warning, skip/ignore/re-categorize a test, or retry a flaky E2E. - Commit on the maintainer's checkout, push to master, or mark a PR ready for review. - Stack a PR on another feature branch. Every PR branches off `master` (references/parallel.md). - Call another capability's SDK method from a test before that capability is in `master`. Seed and verify through the service's API with a plain `HttpClient`, or assert on the method under test's own result.