@sponson/adapters 0.0.0-stage → 0.5.0

package/recipes/auth0.yaml

@@ -0,0 +1,178 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Auth0 Management API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: auth0
+title: Auth0
+category: auth
+verified_on: "2026-10-11"
+docs:
+  - title: Get Management API access tokens for production
+    url: https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production
+  - title: Management API v2, get a client
+    url: https://auth0.com/docs/api/management/v2/clients/get-clients-by-id
+  - title: Management API v2, update a client
+    url: https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id
+  - title: Auth0 Terraform provider, configuration (conventional variable names)
+    url: https://raw.githubusercontent.com/auth0/terraform-provider-auth0/main/docs/index.md
+api:
+  base_url_env: AUTH0_API_URL
+  auth:
+    oauth2_client_credentials:
+      token_url: /oauth/token
+      token_url_env: AUTH0_TOKEN_URL
+      client_id_env: AUTH0_CLIENT_ID
+      client_secret_env: AUTH0_CLIENT_SECRET
+      audience: /api/v2/
+base_url_example: https://acme.eu.auth0.com/api/v2
+detect:
+  deps: [auth0, "@auth0/"]
+  env: ["AUTH0_*"]
+  starter:
+    - op: callback_url
+    - op: logout_url
+      preview_url: url
+  where:
+    base_url: "`https://<tenant>.<region>.auth0.com/api/v2`: Auth0 Dashboard → Settings → General → Domain (the canonical domain, not a custom one)"
+    client_id: "Auth0 Dashboard → Applications → your application → Settings → Client ID"
+    url: "the exact callback URL the app sends as `redirect_uri` on a preview: its URL plus the callback path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: AU1
+    verified: true
+    text: "A machine-to-machine application gets a Management API token from `POST https://<tenant>/oauth/token` (form-encoded `grant_type=client_credentials`, `client_id`, `client_secret`, `audience`); the audience is the Management API's identifier `https://<tenant>/api/v2/`. The answer has `access_token`, `expires_in` (86400 in the example) and `token_type: Bearer`. The recipe writes both as paths, so a plan's `base_url: https://<tenant>/api/v2` names the tenant once."
+    source: https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production
+  - id: AU2
+    verified: true
+    text: "`GET /api/v2/clients/{id}` answers the application with its `callbacks`, `allowed_logout_urls`, `web_origins` and `allowed_origins` arrays, which only a token with `read:clients` (or `read:client_keys`) receives. `fields` with `include_fields=true` limits the answer to the listed fields, so the recipe never reads the client secret."
+    source: https://auth0.com/docs/api/management/v2/clients/get-clients-by-id
+  - id: AU3
+    verified: true
+    text: "`PATCH /api/v2/clients/{id}` (scope `update:clients`) updates an application; `callbacks`, `allowed_logout_urls`, `web_origins` and `allowed_origins` are arrays of strings, and the body needs at least one property, so a write sends the one array alone."
+    source: https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id
+  - id: AU4
+    verified: false
+    text: "An array sent in a PATCH replaces the stored array whole (it is not merged), so the recipe sends the full list read just before with one URL added or removed. The reference does not say so for these fields."
+  - id: AU5
+    verified: false
+    text: "Updates have no precondition (no ETag or version): the line locks the application (`lockOn`, one lock per tenant and client id, shared by the four ops) against other Sponson runs, and a console edit made between the read and the write can still be lost (the next apply then reports it as drift)."
+  - id: AU6
+    verified: false
+    text: "URLs are stored and read back exactly as written (no trailing slash added or case changed), so a URL identifies its entry."
+  - id: AU7
+    verified: true
+    text: "`AUTH0_CLIENT_ID` and `AUTH0_CLIENT_SECRET` are the variables the Auth0 Terraform provider reads for a machine-to-machine client."
+    source: https://raw.githubusercontent.com/auth0/terraform-provider-auth0/main/docs/index.md
+  - id: AU8
+    verified: false
+    text: "The audience stays the tenant's canonical domain when the tenant has a custom domain, so `base_url` names the canonical domain (`<tenant>.<region>.auth0.com`), not the custom one."
+ops:
+  callback_url:
+    kind: list_item
+    title: Application callback URL
+    summary: "One URL in an Auth0 application's Allowed Callback URLs (`callbacks`), such as the preview's `/callback`; usually `{ from: <deploy line>.preview_url }` joined with the path in the app. Added by read-modify-write of the list under a lock on the application, removed on destroy; every other URL is left as it is. A URL removed in the Dashboard is drift (`missing`) that the next apply puts back."
+    covers: [auth0-callbacks]
+    params:
+      client_id:
+        type: string
+        required: true
+        description: The application's Client ID.
+        example: AbC123dEf456GhI789jKl012MnO345pQ
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: "The callback URL, exactly as the application sends it as `redirect_uri`."
+        example: "https://${ctx.scope}.preview.example.app/callback"
+    http:
+      parent:
+        path: "/clients/{client_id}"
+        read_path: "/clients/{client_id}?fields=callbacks,allowed_logout_urls,web_origins,allowed_origins&include_fields=true"
+      list_path: /callbacks
+      item: { param: url }
+    sim:
+      objects:
+        "/clients/{client_id}": { callbacks: [https://app.example.com/callback], allowed_logout_urls: [https://app.example.com], web_origins: [https://app.example.com], allowed_origins: [] }
+    live:
+      params: { client_id: SPONSON_LIVE_AUTH0_APP_CLIENT_ID }
+  logout_url:
+    kind: list_item
+    title: Application allowed logout URL
+    summary: "One URL in an Auth0 application's Allowed Logout URLs (`allowed_logout_urls`), where `/v2/logout` may return the user, such as the preview's home page. Read-modify-write of the list under the application's lock; removed on destroy; every other URL is left as it is."
+    covers: [auth0-callbacks]
+    params:
+      client_id:
+        type: string
+        required: true
+        description: The application's Client ID.
+        example: AbC123dEf456GhI789jKl012MnO345pQ
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: "The URL the application passes as `returnTo` on logout."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/clients/{client_id}"
+        read_path: "/clients/{client_id}?fields=callbacks,allowed_logout_urls,web_origins,allowed_origins&include_fields=true"
+      list_path: /allowed_logout_urls
+      item: { param: url }
+    sim:
+      objects:
+        "/clients/{client_id}": { callbacks: [https://app.example.com/callback], allowed_logout_urls: [https://app.example.com], web_origins: [https://app.example.com], allowed_origins: [] }
+    live:
+      params: { client_id: SPONSON_LIVE_AUTH0_APP_CLIENT_ID }
+  web_origin:
+    kind: list_item
+    title: Application allowed web origin
+    summary: "One origin in an Auth0 application's Allowed Web Origins (`web_origins`), which silent authentication and the SPA SDKs' token refresh need for the preview's origin. Read-modify-write of the list under the application's lock; removed on destroy; every other origin is left as it is."
+    covers: [auth0-callbacks]
+    params:
+      client_id:
+        type: string
+        required: true
+        description: The application's Client ID.
+        example: AbC123dEf456GhI789jKl012MnO345pQ
+      origin:
+        type: string
+        required: true
+        pattern: "^https?://[^/\\s]+$"
+        description: "The origin, scheme and host without a path (`https://pr-42.preview.example.app`)."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/clients/{client_id}"
+        read_path: "/clients/{client_id}?fields=callbacks,allowed_logout_urls,web_origins,allowed_origins&include_fields=true"
+      list_path: /web_origins
+      item: { param: origin }
+    sim:
+      objects:
+        "/clients/{client_id}": { callbacks: [https://app.example.com/callback], allowed_logout_urls: [https://app.example.com], web_origins: [https://app.example.com], allowed_origins: [] }
+    live:
+      params: { client_id: SPONSON_LIVE_AUTH0_APP_CLIENT_ID }
+  allowed_origin:
+    kind: list_item
+    title: Application allowed origin (CORS)
+    summary: "One origin in an Auth0 application's Allowed Origins (CORS, `allowed_origins`), for a preview that calls Auth0 from the browser across origins (embedded login, cross-origin authentication). Read-modify-write of the list under the application's lock; removed on destroy; every other origin is left as it is."
+    covers: [auth0-callbacks]
+    params:
+      client_id:
+        type: string
+        required: true
+        description: The application's Client ID.
+        example: AbC123dEf456GhI789jKl012MnO345pQ
+      origin:
+        type: string
+        required: true
+        pattern: "^https?://[^/\\s]+$"
+        description: "The origin, scheme and host without a path (`https://pr-42.preview.example.app`)."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/clients/{client_id}"
+        read_path: "/clients/{client_id}?fields=callbacks,allowed_logout_urls,web_origins,allowed_origins&include_fields=true"
+      list_path: /allowed_origins
+      item: { param: origin }
+    sim:
+      objects:
+        "/clients/{client_id}": { callbacks: [https://app.example.com/callback], allowed_logout_urls: [https://app.example.com], web_origins: [https://app.example.com], allowed_origins: [] }
+    live:
+      params: { client_id: SPONSON_LIVE_AUTH0_APP_CLIENT_ID }

package/recipes/azure_swa.yaml

@@ -0,0 +1,116 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Azure Static Web Apps (Azure Resource Manager) recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: azure_swa
+title: Azure Static Web Apps
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: Static Sites - Create Or Update Static Site Build App Settings
+    url: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/create-or-update-static-site-build-app-settings?view=rest-appservice-2024-04-01
+  - title: Static Sites - List Static Site Build App Settings
+    url: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/list-static-site-build-app-settings?view=rest-appservice-2024-04-01
+  - title: Static Sites - Get Static Site Builds
+    url: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/get-static-site-builds?view=rest-appservice-2024-04-01
+  - title: Preview environments in Azure Static Web Apps
+    url: https://learn.microsoft.com/en-us/azure/static-web-apps/preview-environments
+  - title: Configure application settings for Azure Static Web Apps
+    url: https://learn.microsoft.com/en-us/azure/static-web-apps/application-settings
+  - title: az account get-access-token
+    url: https://learn.microsoft.com/en-us/cli/azure/account#az-account-get-access-token
+api:
+  base_url: https://management.azure.com
+  base_url_env: AZURE_SWA_API_URL
+  auth: { command: [az, account, get-access-token, --query, accessToken, -o, tsv] }
+detect:
+  files: [staticwebapp.config.json]
+  env: ["AZURE_STATIC_WEB_APPS_*"]
+  starter:
+    - op: build_app_setting
+      values: { environment: "${ctx.pr.number}" }
+  where:
+    subscription_id: "`az account show --query id -o tsv`"
+    resource_group: "`az staticwebapp show --name <site> --query resourceGroup -o tsv`"
+    site: "`az staticwebapp list --query '[].name'`"
+assumptions:
+  - id: AZ1
+    verified: true
+    text: "`PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/staticSites/{name}/builds/{environmentName}/config/appsettings?api-version=2024-04-01` with `{ properties: { <name>: <value>, … } }` sets the app settings of one environment (build) and answers 200 with the same `properties`."
+    source: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/create-or-update-static-site-build-app-settings?view=rest-appservice-2024-04-01
+  - id: AZ2
+    verified: true
+    text: "The settings are read with `POST …/builds/{environmentName}/listAppSettings?api-version=2024-04-01` (no body), which answers a StringDictionary `{ id, properties }`; there is no GET, so the recipe reads with `parent.read_method: POST`."
+    source: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/list-static-site-build-app-settings?view=rest-appservice-2024-04-01
+  - id: AZ3
+    verified: true
+    text: "Each environment is a `builds/{environmentName}` resource: production is `default`, a pull request's preview environment is named by the pull request's number (`builds/12`)."
+    source: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/get-static-site-builds?view=rest-appservice-2024-04-01
+  - id: AZ4
+    verified: true
+    text: "A preview environment exists from the pull request's first deployment and is deleted, with its settings, when the pull request is closed; app settings reach the app's managed API (Functions), not the front-end build."
+    source: https://learn.microsoft.com/en-us/azure/static-web-apps/preview-environments
+  - id: AZ5
+    verified: true
+    text: "`az account get-access-token --query accessToken -o tsv` prints an Azure Resource Manager access token for the signed-in account (the default resource is `https://management.azure.com/`), sent as a bearer token."
+    source: https://learn.microsoft.com/en-us/cli/azure/account#az-account-get-access-token
+  - id: AZ6
+    verified: false
+    text: "The PUT replaces the whole settings map (a setting it is not sent is removed), so the recipe sends the map as read with the one entry changed (`send: collection`); there is no ETag on this resource, so only Sponson's own writers are serialised (the parent lock), and a setting added in the portal between the read and the write is lost."
+  - id: AZ7
+    verified: false
+    text: "Listing the settings of an environment that does not exist (not deployed yet, or deleted with its pull request) answers 404, which the recipe reads as no settings (`if_missing: empty`): plan shows a create before the first deploy, and destroy after the pull request closed is a no-op. A write before the first deploy fails with that 404; order the line after the deploy."
+ops:
+  build_app_setting:
+    kind: list_item
+    title: App setting of a preview environment
+    summary: "One app setting of a Static Web App environment (a pull request's preview environment is named by its number), by read-modify-write of the environment's settings: read with `listAppSettings`, written whole with a PUT. Other settings are left alone and the environment is locked while Sponson writes it. Settings reach the app's managed API, not the front-end build (AZ4); the environment exists only after the PR's first deploy (AZ7)."
+    covers: [azure-swa-settings]
+    params:
+      subscription_id:
+        type: string
+        required: true
+        description: The Azure subscription id.
+        example: 00000000-0000-0000-0000-000000000000
+      resource_group:
+        type: string
+        required: true
+        description: The resource group of the static web app.
+        example: rg-web
+      site:
+        type: string
+        required: true
+        description: The static web app's name.
+        example: web
+      environment:
+        type: string
+        required: true
+        pattern: "^[a-zA-Z0-9]+$"
+        description: The environment's name (the pull request's number for its preview environment; `default` is production).
+        example: "42"
+      name:
+        type: string
+        required: true
+        description: The setting's name.
+        example: API_URL
+      value:
+        type: string
+        required: true
+        description: The setting's value.
+        example: "https://api-${ctx.scope}.example.app"
+    http:
+      parent:
+        path: "/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.Web/staticSites/{site}/builds/{environment}/config/appsettings?api-version=2024-04-01"
+        read_path: "/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.Web/staticSites/{site}/builds/{environment}/listAppSettings?api-version=2024-04-01"
+        read_method: POST
+        method: PUT
+        send: collection
+        if_missing: empty
+      list_path: /properties
+      shape: map
+      item: { param: name }
+      value: { param: value }
+    sim:
+      objects:
+        "/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.Web/staticSites/{site}/builds/{environment}/config/appsettings":
+          properties: { SHARED_SETTING: from-the-portal }
+    live:
+      params: { subscription_id: SPONSON_LIVE_AZURE_SUBSCRIPTION_ID, resource_group: SPONSON_LIVE_AZURE_RESOURCE_GROUP, site: SPONSON_LIVE_AZURE_SWA_SITE, environment: SPONSON_LIVE_AZURE_SWA_ENVIRONMENT }

package/recipes/cloud_run.yaml

@@ -0,0 +1,97 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Google Cloud Run Admin API v2 recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: cloud_run
+title: Google Cloud Run
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: "REST Resource: projects.locations.services (Service, TrafficTarget)"
+    url: https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.services
+  - title: "Method: projects.locations.services.patch"
+    url: https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.services/patch
+  - title: "Method: projects.locations.services.get"
+    url: https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.services/get
+  - title: Rollbacks, gradual rollouts, and traffic migration (tags)
+    url: https://cloud.google.com/run/docs/rollouts-rollbacks-traffic-migration
+  - title: gcloud auth print-access-token
+    url: https://cloud.google.com/sdk/gcloud/reference/auth/print-access-token
+api:
+  base_url: https://run.googleapis.com/v2
+  base_url_env: CLOUD_RUN_API_URL
+  auth: { command: [gcloud, auth, print-access-token] }
+assumptions:
+  - id: CR1
+    verified: true
+    text: "`GET https://run.googleapis.com/v2/projects/{project}/locations/{location}/services/{service}` answers the Service with its `traffic` list and an `etag`, 'a system-generated fingerprint for this version of the resource' that 'may be used to detect modification conflict during updates'."
+    source: https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.services
+  - id: CR2
+    verified: true
+    text: "`PATCH https://run.googleapis.com/v2/{service.name}` takes a Service and an optional `updateMask` (fields to update), answers a long-running Operation, and needs the `cloud-platform` scope; the recipe sends `?updateMask=traffic` with `{ traffic, etag }` only, so the revision template is never written."
+    source: https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.services/patch
+  - id: CR3
+    verified: true
+    text: "A TrafficTarget is `{ type, revision, percent, tag }`; `type: TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION` sends traffic to the named `revision`, `percent` defaults to zero, and `tag` is 'a string to be part of the URI to exclusively reference this target', which is the per-PR URL."
+    source: https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.services
+  - id: CR4
+    verified: true
+    text: "`gcloud auth print-access-token` prints an OAuth access token for the active account, sent as a bearer token."
+    source: https://cloud.google.com/sdk/gcloud/reference/auth/print-access-token
+  - id: CR5
+    verified: false
+    text: "A patch whose `etag` no longer matches (a deploy changed the service after the read) is refused (409 ABORTED or 412) rather than applied: the line fails and the next apply reads again, so a concurrent `gcloud run deploy` is never overwritten. Sponson's own writers are serialised by the parent lock."
+  - id: CR6
+    verified: false
+    text: "The Service answered right after the patch's Operation is accepted already shows the new `traffic` (the desired state), so the re-read that confirms the write sees the tag; `percent` 0 is left out of the answer and `type` and `revision` are answered as sent."
+  - id: CR7
+    verified: false
+    text: "The revision a tag points to exists before the line applies: the PR's deploy creates it (`gcloud run deploy --no-traffic --revision-suffix <scope>` gives `<service>-<scope>`). Its environment variables are part of that revision, set by the deploy, not by this recipe; a deploy that tags (`--tag`) itself conflicts with this line's tag."
+ops:
+  traffic_tag:
+    kind: list_item
+    title: Traffic tag of a revision
+    summary: "A tag (`pr-42`) in a service's `traffic` list pointing at the PR's revision with no traffic share, which gives the revision its own URL (`https://pr-42---<service>-<hash>.a.run.app`). Read-modify-write of `traffic` only (`updateMask=traffic`), sent with the service's `etag` so a concurrent deploy makes the write fail instead of being overwritten (CR5); other tags and the traffic split are left alone, and destroy removes only this tag. The revision itself, and its environment variables, are the deploy's (CR7)."
+    covers: []
+    params:
+      project:
+        type: string
+        required: true
+        description: The Google Cloud project id.
+        example: demo-project
+      region:
+        type: string
+        required: true
+        description: The service's region.
+        example: us-central1
+      service:
+        type: string
+        required: true
+        description: The Cloud Run service's name.
+        example: web
+      tag:
+        type: string
+        required: true
+        pattern: "^[a-z][a-z0-9-]*$"
+        description: The tag, the prefix of the revision's own URL.
+        example: "${ctx.scope}"
+      revision:
+        type: string
+        required: true
+        description: The revision the tag points to (made by the PR's deploy).
+        example: "web-${ctx.scope}"
+    http:
+      parent:
+        path: "/projects/{project}/locations/{region}/services/{service}?updateMask=traffic"
+        read_path: "/projects/{project}/locations/{region}/services/{service}"
+        method: PATCH
+        send: [etag]
+      list_path: /traffic
+      key_field: tag
+      item: { tag: { param: tag }, revision: { param: revision }, type: TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION }
+    sim:
+      objects:
+        "/projects/{project}/locations/{region}/services/{service}":
+          name: projects/demo-project/locations/us-central1/services/web
+          etag: '"sim-etag-1"'
+          traffic: [{ type: TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST, percent: 100 }]
+    live:
+      params: { project: SPONSON_LIVE_GCP_PROJECT, region: SPONSON_LIVE_CLOUD_RUN_REGION, service: SPONSON_LIVE_CLOUD_RUN_SERVICE, revision: SPONSON_LIVE_CLOUD_RUN_REVISION }

package/recipes/cloudflare.yaml

@@ -0,0 +1,108 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Cloudflare API v4 recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: cloudflare
+title: Cloudflare
+category: dns
+verified_on: "2026-10-11"
+docs:
+  - title: Create DNS record
+    url: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/create/
+  - title: List DNS records
+    url: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/list/
+  - title: DNS record details
+    url: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/get/
+  - title: Update DNS record (PATCH)
+    url: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/edit/
+  - title: Delete DNS record
+    url: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/delete/
+api:
+  base_url: https://api.cloudflare.com/client/v4
+  base_url_env: CLOUDFLARE_API_URL
+  auth: { bearer_env: CLOUDFLARE_API_TOKEN }
+assumptions:
+  - id: CF1
+    verified: true
+    text: "Records are created with `POST /zones/{zone_id}/dns_records` (`type`, `name`, `content`, `ttl`, `proxied`, `comment`), authenticated with an API token as `Authorization: Bearer` that has DNS Write on the zone."
+    source: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/create/
+  - id: CF2
+    verified: true
+    text: "`GET /zones/{zone_id}/dns_records` answers `{ result: [...] }` and filters by `type` and `name.exact` (names compare case-insensitively)."
+    source: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/list/
+  - id: CF3
+    verified: true
+    text: "Single-record answers (create, details, update) carry the record under `result`, with its `id`."
+    source: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/get/
+  - id: CF4
+    verified: true
+    text: "`PATCH /zones/{zone_id}/dns_records/{id}` updates a record; `DELETE` on the same path removes it permanently."
+    source: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/delete/
+  - id: CF5
+    verified: false
+    text: "A PATCH needs `name` and `type` alongside the changed fields (the edit schema does not mark them optional), so every update sends both."
+    source: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/edit/
+  - id: CF6
+    verified: false
+    text: "The API returns `name` lower-cased as the full name and `content` as written, so `name` must be given lower-case and fully qualified, or every plan finds no record and tries to create one."
+  - id: CF7
+    verified: false
+    text: "A proxied record reports `ttl: 1` (automatic) whatever was sent, so `ttl` other than 1 with `proxied: true` shows as drift on every plan."
+  - id: CF8
+    verified: true
+    text: A CNAME cannot share its name with another record, so name and type identify it within the zone and a filtered list holds at most one, on its first page.
+    source: https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/create/
+ops:
+  dns_cname:
+    kind: resource
+    title: DNS CNAME record
+    summary: A CNAME record in a zone, such as `pr-42.preview.example.com` pointing at the preview deployment's host. Located by name and type; a console edit of its target, proxying, TTL or comment is drift.
+    covers: [cloudflare-dns]
+    params:
+      zone_id:
+        type: string
+        required: true
+        pattern: "^[0-9a-f]{32}$"
+        description: The zone's id (32 hex characters, on the zone's Overview page).
+        example: 023e105f4ecef8ad9ca31a8372d0c353
+      name:
+        type: string
+        required: true
+        pattern: "^[a-z0-9*_.-]+$"
+        description: The record's full name, lower-case, zone included.
+        example: "${ctx.scope}.preview.example.com"
+      target:
+        type: string
+        required: true
+        description: The host the name points at (the record's `content`).
+        example: preview-host.example.net
+      proxied:
+        type: boolean
+        default: false
+        description: Whether Cloudflare proxies the traffic.
+      ttl:
+        type: integer
+        default: 1
+        description: TTL in seconds (60–86400), or 1 for automatic.
+      comment:
+        type: string
+        description: A note on the record; no effect on DNS.
+        example: Managed by Sponson
+    http:
+      find:
+        path: "/zones/{zone_id}/dns_records?type=CNAME&name.exact={name}"
+        list_path: /result
+        match: { type: CNAME, name: { param: name } }
+      create: { path: "/zones/{zone_id}/dns_records" }
+      update:
+        method: PATCH
+        path: "/zones/{zone_id}/dns_records/{id}"
+        body: { type: CNAME, name: { param: name } }
+      delete: { path: "/zones/{zone_id}/dns_records/{id}" }
+      item_path: /result
+      fields:
+        content: { param: target }
+        proxied: { param: proxied }
+        ttl: { param: ttl }
+        comment: { param: comment }
+      outputs: { hostname: /name }
+    live:
+      params: { zone_id: SPONSON_LIVE_CLOUDFLARE_ZONE_ID, name: SPONSON_LIVE_CLOUDFLARE_NAME }

package/recipes/cockroachdb.yaml

@@ -0,0 +1,132 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# CockroachDB Cloud API recipes (service account API key, bearer). Format and checklist: docs/adr/0020-recipes.md,
+# CONTRIBUTING.md "Adding a recipe".
+provider: cockroachdb
+title: CockroachDB Cloud
+category: databases
+verified_on: "2026-10-11"
+docs:
+  - title: Cloud API OpenAPI document (version 2026-09-15)
+    url: https://cockroachlabs.cloud/assets/docs/api/latest/openapi.json
+  - title: Use the CockroachDB Cloud API
+    url: https://docs.cockroachlabs.com/docs/cockroachcloud/cloud-api
+api:
+  base_url: https://cockroachlabs.cloud/api/v1
+  base_url_env: COCKROACH_API_URL
+  auth: { bearer_env: COCKROACH_API_KEY }
+  headers: { Cc-Version: "2024-09-16" }
+detect:
+  env: ["COCKROACH_*"]
+  db_hosts: [.cockroachlabs.cloud]
+  starter:
+    - op: database
+      values: { name: "app_${ctx.scope}" }
+  where:
+    cluster_id: "CockroachDB Cloud Console → your cluster (the UUID in its URL), or `ccloud cluster list`"
+assumptions:
+  - id: CR1
+    verified: true
+    text: "The Cloud API authenticates with a service account's secret key as `Authorization: Bearer`; the key has the service account's roles."
+    source: https://docs.cockroachlabs.com/docs/cockroachcloud/cloud-api
+  - id: CR2
+    verified: true
+    text: "`Cc-Version` pins the API version (`YYYY-MM-DD`); without it the latest version answers, which may change under a client. The guide documents `2024-09-16`."
+    source: https://docs.cockroachlabs.com/docs/cockroachcloud/cloud-api
+  - id: CR3
+    verified: true
+    text: "`POST /clusters/{cluster_id}/databases` with `{ name }` creates a database and answers `{ name, table_count }`; `GET` on the same path lists `{ databases: [{ name, table_count }], pagination: { next_page } }`, paged with `pagination.page`; `DELETE /clusters/{cluster_id}/databases/{name}` deletes one. There is no GET of a single database."
+    source: https://cockroachlabs.cloud/assets/docs/api/latest/openapi.json
+  - id: CR4
+    verified: true
+    text: "`POST /clusters/{cluster_id}/sql-users` with `{ name, password }` (both required) creates a SQL user; `GET` on the same path lists `{ users: [{ name }], pagination: { next_page } }`; `DELETE /clusters/{cluster_id}/sql-users/{name}` deletes one. The password cannot be read back; `PUT …/sql-users/{name}/password` changes it."
+    source: https://cockroachlabs.cloud/assets/docs/api/latest/openapi.json
+  - id: CR5
+    verified: true
+    text: "A SQL user created through the API gets the SQL `admin` role by default, which the guide advises against for anything but administration."
+    source: https://docs.cockroachlabs.com/docs/cockroachcloud/cloud-api
+  - id: CR6
+    verified: true
+    text: "Creating or deleting databases and SQL users needs a cluster-level role of the service account (Cluster Admin, Cluster Operator or Cluster Data Accessor for databases; Cluster Admin for SQL users)."
+    source: https://cockroachlabs.cloud/assets/docs/api/latest/openapi.json
+  - id: CR7
+    verified: false
+    text: "`COCKROACH_API_KEY` is the variable the CockroachDB Terraform provider and `ccloud` read the key from."
+  - id: CR8
+    verified: false
+    text: "A second create of an existing database or SQL user is refused with 409 (ALREADY_EXISTS), and deleting one that is gone answers 404."
+  - id: CR9
+    verified: false
+    text: "Deleting a database drops it with its tables (CASCADE); the API offers no way to refuse when it holds data."
+  - id: CR10
+    verified: false
+    text: "The API takes database and user names that need quoting in SQL (`app_pr-42`, from a scope with `-`) and quotes them itself."
+ops:
+  database:
+    kind: resource
+    title: Database in a cluster
+    summary: "A database per scope in a shared CockroachDB Cloud cluster, such as `app_pr_42`, instead of a cluster per preview. Located by its name in the cluster's list; only its existence is compared (the API exposes nothing else to set); destroy drops it with its data (CR9)."
+    covers: [cockroachdb-database]
+    params:
+      cluster_id:
+        type: string
+        required: true
+        description: The cluster's id (a UUID, shown in the Cloud Console's URL).
+        example: 9e3f1a52-63d1-4a4c-9b8f-2c8b7a0e5d11
+      name:
+        type: string
+        required: true
+        pattern: "^[A-Za-z_][A-Za-z0-9_.-]{0,62}$"
+        description: "The database's name; its identity. A name with `-` (a scope such as `pr-42`) needs quoting in SQL (CR10)."
+        example: "app_${ctx.scope}"
+    http:
+      find:
+        path: "/clusters/{cluster_id}/databases"
+        list_path: /databases
+        match: { name: { param: name } }
+        next: /pagination/next_page
+        cursor_param: pagination.page
+      create: { path: "/clusters/{cluster_id}/databases" }
+      delete: { path: "/clusters/{cluster_id}/databases/{id}" }
+      id_path: /name
+    sim:
+      id_from: name
+    live:
+      params: { cluster_id: SPONSON_LIVE_COCKROACH_CLUSTER_ID }
+  sql_user:
+    kind: resource
+    title: SQL user in a cluster
+    summary: "A SQL user per scope in a shared CockroachDB Cloud cluster, such as `app_pr_42`, with its password as an input (`{ secret: … }`, or a sensitive output of another line), sent on create only and never compared. It gets the SQL `admin` role (CR5): grant narrower privileges in SQL if previews must not administer the cluster. Located by its name; destroy deletes the user."
+    covers: []
+    params:
+      cluster_id:
+        type: string
+        required: true
+        description: The cluster's id (a UUID, shown in the Cloud Console's URL).
+        example: 9e3f1a52-63d1-4a4c-9b8f-2c8b7a0e5d11
+      name:
+        type: string
+        required: true
+        pattern: "^[A-Za-z_][A-Za-z0-9_.-]{0,62}$"
+        description: The user's name; its identity.
+        example: "app_${ctx.scope}"
+      password:
+        type: string
+        required: true
+        description: "The user's password, as a reference (`{ secret: env://… }`, or `{ from: <line>.<output> }` of a sensitive output); sent on create only (CR4)."
+        example: { secret: "env://PREVIEW_DB_PASSWORD" }
+    http:
+      find:
+        path: "/clusters/{cluster_id}/sql-users"
+        list_path: /users
+        match: { name: { param: name } }
+        next: /pagination/next_page
+        cursor_param: pagination.page
+      create:
+        path: "/clusters/{cluster_id}/sql-users"
+        body: { password: { param: password } }
+      delete: { path: "/clusters/{cluster_id}/sql-users/{id}" }
+      id_path: /name
+    sim:
+      id_from: name
+    live:
+      params: { cluster_id: SPONSON_LIVE_COCKROACH_CLUSTER_ID }