add-provider-adapter

Stars14

Forks0

UpdatedJuly 11, 2026 at 23:12

Use when adding a new cloud provider adapter, or extending an existing one with a new service, in internal/provider/<name>/. Covers the Store interface, SDK confinement, error mapping, version-spec parsing, CLI/registry wiring, and staging support.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

mpyw

mpyw/suve

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	add-provider-adapter
description	Use when adding a new cloud provider adapter, or extending an existing one with a new service, in internal/provider/<name>/. Covers the Store interface, SDK confinement, error mapping, version-spec parsing, CLI/registry wiring, and staging support.

Adding or extending a provider adapter

A provider adapter implements the neutral seam in internal/provider so the rest of suve never sees a cloud SDK. Google Cloud (PR #231), Azure Key Vault + App Configuration (PR #239), and the AWS re-implementation (PR #224) all follow the same shape.

Core adapter

Implement provider.Store — the composition of Reader, Writer, and Tagger (internal/provider/provider.go) — over a narrow in-package client wrapper. Keep the cloud SDK confined to internal/provider/<name>/**.
Hide SDK paginators and iterators behind a Wrap() adapter so the seam returns neutral domain types, never SDK types.
Map SDK errors to the neutral sentinels in internal/provider/errors.go: provider.ErrNotFound and provider.ErrAlreadyExists. Missed error mappings are a recurring defect source (#318, #481) — enumerate every not-found and already-exists SDK error shape and cover it in unit tests.
Do pagination and deterministic ordering from day one. List and history operations must page through all results and break timestamp ties with a stable secondary key. Skipping this produced #311, #312, and #314.

Version-spec parser

Add a parser package internal/version/<name>version (see the existing gcloudversion, azurekvversion, azureappconfigversion). It resolves #VERSION / ~SHIFT / :LABEL per the provider's capabilities and cleanly rejects unsupported specifiers before any API call. Google Cloud rejects labels with a dedicated error at parse time (ErrLabelUnsupported, #231); App Configuration is unversioned and rejects all specifiers.

Wiring

Wire a Factory (internal/provider/registry.go) that returns provider.ErrUnsupportedKind for services the provider does not offer.
Register the factory in the CLI registry and in internal/cli/commands/app.go.
Add the provider's scope flag plus its environment-variable fallback.

SDK confinement guards

Extend internal/architecture_test.go and the depguard block in .golangci.yaml to gate the new SDK module so it can only be imported from the provider directory. Confinement is enforced across all of internal/ (#488, #502) — keep that breadth.

Staging support (separate work)

Staging is a distinct increment on top of read/write (#247 → #261, #262):

Implement the provider ScopeResolver.
Add the provider's staging strategy.
Register the service spec in GlobalConfig (#261).

PR conventions

Record any friction with the neutral abstraction in a "Design feedback" section of the PR body (#231 — this feedback fed the seam epic #419).
Close against #231's acceptance checklist: every op works, unsupported specs are rejected before the API call, no foreign SDK appears outside the provider directory, and mise test + mise lint are green.

More from this repository

same repository

docs-site-pages

mpyw/suve

Use when restructuring the README or the GitHub Pages site generated from it — the left-nav/left-pane, section reorg, or per-provider command docs. Covers the build-docs-site.py split + literate-nav SUMMARY pipeline, its HTML-comment directives and site-only transforms (nav-group, site:skip, hero <h1>, asset ../ prefix, DOC_NAV grouping), the python-markdown gotchas GitHub hides, and the `mise docs-build` strict gate.

2026-07-1614

release-highlights

mpyw/suve

Use when authoring or backfilling the "## Highlights" section of a GitHub release — the human-written summary that prepends the auto-generated notes. Covers when a release earns highlights, the fixed format (bold lead + breaking-change note, `###` subsections, PR-referenced bullets), and the prepend-in-place mechanics.

2026-07-1514

refresh-demo-gifs

mpyw/suve

Use when re-recording the CLI, TUI, or GUI demo GIFs after a UI change or a user-visible output change. Covers the record scripts, robust Playwright selectors, output-drift triggers, frame verification, and Git LFS.

2026-07-1314

collection-idioms

mpyw/suve

Load when writing or reviewing Go that builds or transforms slices/maps. Prefer samber/lo, samber/lo/it, and stdlib slices/maps callback & iterator utilities over hand-rolled make + range + append; keep an explicit loop only where side effects or control flow are genuinely complex.

2026-07-1214

suve-cli-map

mpyw/suve

Load when you need the per-provider capability, versioning, and alias matrix for suve's CLI without reading the full docs/{aws,azure,gcloud}.md option tables. A one-page orientation; link out for per-command detail.

2026-07-1214

provider-seam-invariants

mpyw/suve

Load when adding or modifying a provider adapter, or when touching internal/provider/** or internal/domain/**. Captures the invariants that keep the provider-neutral seam honest: the neutral domain model, opaque version refs, the typed write/delete option pattern, interface segregation, and SDK confinement.

2026-07-1214

name	add-provider-adapter
description	Use when adding a new cloud provider adapter, or extending an existing one with a new service, in internal/provider/<name>/. Covers the Store interface, SDK confinement, error mapping, version-spec parsing, CLI/registry wiring, and staging support.

Adding or extending a provider adapter

Core adapter

Implement provider.Store — the composition of Reader, Writer, and Tagger (internal/provider/provider.go) — over a narrow in-package client wrapper. Keep the cloud SDK confined to internal/provider/<name>/**.
Hide SDK paginators and iterators behind a Wrap() adapter so the seam returns neutral domain types, never SDK types.
Map SDK errors to the neutral sentinels in internal/provider/errors.go: provider.ErrNotFound and provider.ErrAlreadyExists. Missed error mappings are a recurring defect source (#318, #481) — enumerate every not-found and already-exists SDK error shape and cover it in unit tests.
Do pagination and deterministic ordering from day one. List and history operations must page through all results and break timestamp ties with a stable secondary key. Skipping this produced #311, #312, and #314.

Version-spec parser

Add a parser package internal/version/<name>version (see the existing gcloudversion, azurekvversion, azureappconfigversion). It resolves #VERSION / ~SHIFT / :LABEL per the provider's capabilities and cleanly rejects unsupported specifiers before any API call. Google Cloud rejects labels with a dedicated error at parse time (ErrLabelUnsupported, #231); App Configuration is unversioned and rejects all specifiers.

Wiring

Wire a Factory (internal/provider/registry.go) that returns provider.ErrUnsupportedKind for services the provider does not offer.
Register the factory in the CLI registry and in internal/cli/commands/app.go.
Add the provider's scope flag plus its environment-variable fallback.

SDK confinement guards

Extend internal/architecture_test.go and the depguard block in .golangci.yaml to gate the new SDK module so it can only be imported from the provider directory. Confinement is enforced across all of internal/ (#488, #502) — keep that breadth.

Staging support (separate work)

Staging is a distinct increment on top of read/write (#247 → #261, #262):

Implement the provider ScopeResolver.
Add the provider's staging strategy.
Register the service spec in GlobalConfig (#261).

PR conventions

Record any friction with the neutral abstraction in a "Design feedback" section of the PR body (#231 — this feedback fed the seam epic #419).
Close against #231's acceptance checklist: every op works, unsupported specs are rejected before the API call, no foreign SDK appears outside the provider directory, and mise test + mise lint are green.