@sponson/adapters 0.0.0-stage → 0.5.0

package/dist/xata.js

@@ -0,0 +1,142 @@
+/**
+ * Xata adapter (the Postgres platform): a copy-on-write branch per scope, child of a parent branch. A new branch
+ * takes a moment to come up, so `apply` waits for it to be healthy, then reads its credentials: the wait and the
+ * second request are why this is an adapter and not an `http` recipe (ADR 0017, "No polling"). The API assumptions
+ * it relies on are numbered XA1… at the top of packages/sim/src/routes/xata.ts.
+ *
+ * - Key: `branch:<name>`. Id: Xata's branch id. The organization and project are the provider block.
+ * - Hash: the name only. The parent is used when the branch is created; a branch cannot be moved to another
+ *   parent, so changing `parent_id` later changes nothing, and a deleted branch is `missing` (re-created by the
+ *   next apply, from the parent as it is then).
+ * - Outputs: the branch id, and its connection string (sensitive), read from the credentials endpoint on every run
+ *   (XA6), so dependents in later runs get it too.
+ */
+import { setTimeout as sleep } from "node:timers/promises";
+import { SponsonError, canonicalJson, markerKind, sha256 } from "@sponson/core";
+// Only the stable authoring API exported from `@sponson/adapters` (listed in CONTRIBUTING.md).
+import { assertNoPending, clientFor, deleteIgnoringNotFound, optionalEnv, paramError, requireEnv, requireProvider, stringParam } from "./common.js";
+import { ShapeError, isObject, records } from "./http.js";
+const ADAPTER = "xata";
+/** The environment Xata reads; declared once, used by the code below and by the generated docs (`about`). */
+const ABOUT = { credentialEnv: "XATA_API_KEY", baseUrlEnv: "XATA_API_URL", title: "Xata", category: "databases", detect: { deps: ["@xata.io/"], env: ["XATA_*"], files: [".xatarc"] } };
+/** Xata's API base URL (XA1). `XATA_API_URL` overrides it; tests and scenarios point that at the sim. */
+export const XATA_DEFAULT_API_URL = "https://api.xata.tech";
+/** How often a new branch is polled, and for how long (milliseconds; overridable for tests). */
+const POLL_MS = { env: "SPONSON_XATA_POLL_MS", fallback: 2000 };
+const READY_TIMEOUT_MS = { env: "SPONSON_XATA_READY_TIMEOUT_MS", fallback: 10 * 60 * 1000 };
+function msFromEnv(env, s) {
+    const raw = optionalEnv(env, s.env);
+    const n = Number(raw);
+    return raw !== undefined && Number.isFinite(n) && n >= 0 ? n : s.fallback;
+}
+function client(actx) {
+    const token = requireEnv(actx.env, ABOUT.credentialEnv, ADAPTER);
+    const org = requireProvider(actx, "organization", ADAPTER);
+    const project = requireProvider(actx, "project", ADAPTER);
+    const api = clientFor(actx, ADAPTER, { baseUrl: optionalEnv(actx.env, ABOUT.baseUrlEnv) ?? XATA_DEFAULT_API_URL, token });
+    return { api, base: `/organizations/${enc(org)}/projects/${enc(project)}/branches` };
+}
+function enc(s) {
+    return encodeURIComponent(s);
+}
+const PREFIX = "branch:";
+function branchRecord(b) {
+    return { key: `${PREFIX}${b.name}`, id: b.id, hash: sha256(canonicalJson({ name: b.name })), label: `Xata branch ${b.name}` };
+}
+/** The branch named `name`, or null (XA3: names are not unique, so more than one is refused, never guessed). */
+async function findBranch(c, name) {
+    const list = await c.api.get(c.base, (b) => {
+        if (!isObject(b))
+            throw new ShapeError("expected `{ branches }`");
+        return records(b.branches, "`branches`", ["id", "name"]);
+    });
+    const hits = list.filter((b) => b.name === name);
+    if (hits.length > 1)
+        throw paramError(ADAPTER, `${hits.length} branches are named ${name} in the project; rename one or give this line another name`, "name");
+    return hits[0] ? { id: hits[0].id, name: hits[0].name } : null;
+}
+/** The connection string from the credentials endpoint (XA6). */
+async function connectionString(c, id) {
+    return c.api.get(`${c.base}/${enc(id)}/credentials?username=xata`, (b) => {
+        if (!isObject(b) || typeof b.connectionString !== "string" || b.connectionString === "")
+            throw new ShapeError("expected `{ connectionString }`");
+        return b.connectionString;
+    });
+}
+async function outputsOf(c, b) {
+    return { branch_id: b.id, connection_string: await connectionString(c, b.id) };
+}
+/** `status.statusType` of a branch (XA5), or "" when the answer has none yet. */
+function statusType(body) {
+    const status = isObject(body) ? body.status : undefined;
+    return isObject(status) && typeof status.statusType === "string" ? status.statusType : "";
+}
+/** Poll the branch until it is healthy (XA5); FAULT fails, a timeout is WAIT_TIMEOUT that the next run resumes. */
+async function waitHealthy(actx, c, b) {
+    const deadline = Date.now() + msFromEnv(actx.env, READY_TIMEOUT_MS);
+    for (;;) {
+        const type = statusType(await c.api.get(`${c.base}/${enc(b.id)}`));
+        if (/HEALTHY$/.test(type))
+            return;
+        if (/FAULT$/.test(type))
+            throw new SponsonError("PROVIDER_INVALID", `xata: branch ${b.name} reports ${type} while coming up`, { adapter: ADAPTER, branch: b.name });
+        if (Date.now() > deadline) {
+            throw new SponsonError("WAIT_TIMEOUT", `xata: branch ${b.name} is not healthy after ${msFromEnv(actx.env, READY_TIMEOUT_MS)}ms (${READY_TIMEOUT_MS.env}); run again to keep waiting`, { adapter: ADAPTER, branch: b.name });
+        }
+        actx.log(`branch ${b.name} not healthy yet (${type || "no status"})`);
+        await sleep(msFromEnv(actx.env, POLL_MS));
+    }
+}
+const branch = {
+    outputs: { branch_id: { available: "immediate" }, connection_string: { available: "immediate", sensitive: true } },
+    async read(actx, params) {
+        if (markerKind(params.name) !== null)
+            return null;
+        const c = client(actx);
+        const found = await findBranch(c, stringParam(params, "name", ADAPTER));
+        if (!found)
+            return null;
+        return { resources: [branchRecord(found)], outputs: await outputsOf(c, found) };
+    },
+    diff(live, params) {
+        const name = params.name;
+        const key = markerKind(name) !== null ? `${PREFIX}(pending)` : `${PREFIX}${String(name)}`;
+        const label = `Xata branch ${String(name)}`;
+        if (live?.resources.some((r) => r.key === key))
+            return [{ key, kind: "unchanged", label }];
+        const parent = params.parent_id;
+        const after = markerKind(parent) !== null ? { state: "pending", ref: String(parent) } : { state: "literal", value: `child of ${String(parent)}` };
+        return [{ key, kind: "create", label, before: { state: "absent" }, after }];
+    },
+    async apply(actx, params, live) {
+        assertNoPending(params, ADAPTER);
+        const name = stringParam(params, "name", ADAPTER);
+        const parent = stringParam(params, "parent_id", ADAPTER);
+        const key = `${PREFIX}${name}`;
+        if (live?.resources.some((r) => r.key === key))
+            return { resources: live.resources, outputs: live.outputs, created: [] };
+        const c = client(actx);
+        // Announce the create before sending it; a create whose answer was lost is found by name next time (XA3).
+        await actx.intend([key]);
+        actx.log(`create branch ${name} from ${parent}`);
+        const created = await c.api.post(c.base, { mode: "inherit", parentID: parent, name }, (b) => {
+            const [r] = records([b], "the branch", ["id", "name"]);
+            return { id: r.id, name: r.name };
+        });
+        await waitHealthy(actx, c, created);
+        return { resources: [branchRecord(created)], outputs: await outputsOf(c, created), created: [key] };
+    },
+    async destroy(actx, resources) {
+        const c = client(actx);
+        // An intent the engine could not locate has no id: nothing is deleted on a guess (names are not unique, XA3).
+        for (const r of resources)
+            if (r.id !== "")
+                await deleteIgnoringNotFound(c.api, `${c.base}/${enc(r.id)}`);
+    },
+};
+/**
+ * The Xata adapter (`adapter: xata` in a plan). Registered in `createRegistry()`; needs `XATA_API_KEY` and
+ * `providers.xata.organization` and `.project`.
+ */
+export const xataAdapter = { name: ADAPTER, ops: { branch }, about: ABOUT };
+//# sourceMappingURL=xata.js.map

package/dist/xata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xata.js","sourceRoot":"","sources":["../src/xata.ts"],"names":[],"mappings":"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"}

package/dist/xml.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A minimal XML codec for the generic `http` adapter's `encoding: xml` (S3-style configuration documents such as a
+ * bucket's `CORSConfiguration`), mapping XML to the JSON shapes the adapter already works with:
+ *
+ *   - an element with child elements is a map of child name → value; a child that repeats is a list of values;
+ *   - an element with only text is that text, as a string (XML has no numbers or booleans); an empty element is "";
+ *   - attributes are `@name` keys (`@xmlns`), and the text of an element that also has attributes is `#text`.
+ *
+ * Encoding is the inverse: the body is a map with one key (the root element), lists become repeated elements,
+ * `null` leaves an element out. A single repeated element therefore reads back as a value, not a list of one.
+ *
+ * Safe by construction: no DTDs (a `<!DOCTYPE` or `<!ENTITY` is refused, so no external entities and no entity
+ * expansion), only the five predefined entities and numeric character references, a depth limit, and no
+ * namespace processing (prefixed names are kept as written).
+ */
+/** Nesting deeper than this is refused rather than recursed into. */
+export declare const XML_MAX_DEPTH = 64;
+/** Thrown for a document (or a body) this codec does not handle. */
+export declare class XmlError extends Error {
+    constructor(message: string);
+}
+/** A body as an XML document: a map with exactly one key, the root element. */
+export declare function xmlEncode(body: unknown): string;
+/** An XML document as `{ <root>: <value> }`. */
+export declare function xmlDecode(xml: string): Record<string, unknown>;

package/dist/xml.js

@@ -0,0 +1,211 @@
+/**
+ * A minimal XML codec for the generic `http` adapter's `encoding: xml` (S3-style configuration documents such as a
+ * bucket's `CORSConfiguration`), mapping XML to the JSON shapes the adapter already works with:
+ *
+ *   - an element with child elements is a map of child name → value; a child that repeats is a list of values;
+ *   - an element with only text is that text, as a string (XML has no numbers or booleans); an empty element is "";
+ *   - attributes are `@name` keys (`@xmlns`), and the text of an element that also has attributes is `#text`.
+ *
+ * Encoding is the inverse: the body is a map with one key (the root element), lists become repeated elements,
+ * `null` leaves an element out. A single repeated element therefore reads back as a value, not a list of one.
+ *
+ * Safe by construction: no DTDs (a `<!DOCTYPE` or `<!ENTITY` is refused, so no external entities and no entity
+ * expansion), only the five predefined entities and numeric character references, a depth limit, and no
+ * namespace processing (prefixed names are kept as written).
+ */
+/** Nesting deeper than this is refused rather than recursed into. */
+export const XML_MAX_DEPTH = 64;
+const NAME = /^[A-Za-z_][A-Za-z0-9_.-]*(?::[A-Za-z_][A-Za-z0-9_.-]*)?$/;
+/** Thrown for a document (or a body) this codec does not handle. */
+export class XmlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "XmlError";
+    }
+}
+function escapeText(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeAttr(s) {
+    return escapeText(s).replace(/"/g, "&quot;");
+}
+function scalar(v, name) {
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    throw new XmlError(`\`${name}\` must be a map, a list, a string, a number or a boolean`);
+}
+function checkName(name) {
+    if (!NAME.test(name))
+        throw new XmlError(`\`${name}\` is not an XML element name`);
+}
+function element(name, v, depth) {
+    if (depth > XML_MAX_DEPTH)
+        throw new XmlError(`nested deeper than ${XML_MAX_DEPTH} elements`);
+    if (v === null || v === undefined)
+        return "";
+    if (Array.isArray(v))
+        return v.map((x) => element(name, x, depth)).join("");
+    checkName(name);
+    if (typeof v !== "object")
+        return `<${name}>${escapeText(scalar(v, name))}</${name}>`;
+    let attrs = "";
+    let inner = "";
+    for (const [k, x] of Object.entries(v)) {
+        if (k.startsWith("@")) {
+            checkName(k.slice(1));
+            attrs += ` ${k.slice(1)}="${escapeAttr(scalar(x, k))}"`;
+        }
+        else if (k === "#text")
+            inner += escapeText(scalar(x, k));
+        else
+            inner += element(k, x, depth + 1);
+    }
+    return `<${name}${attrs}>${inner}</${name}>`;
+}
+/** A body as an XML document: a map with exactly one key, the root element. */
+export function xmlEncode(body) {
+    if (typeof body !== "object" || body === null || Array.isArray(body) || Object.keys(body).length !== 1) {
+        throw new XmlError("an XML body must be a map with exactly one key: the root element, e.g. { CORSConfiguration: { … } }");
+    }
+    const [root, value] = Object.entries(body)[0];
+    return `<?xml version="1.0" encoding="UTF-8"?>${element(root, value ?? "", 0)}`;
+}
+const ENTITIES = { lt: "<", gt: ">", amp: "&", quot: '"', apos: "'" };
+/** Text with its entity and character references replaced. */
+function decodeEntities(s) {
+    return s.replace(/&(#x[0-9A-Fa-f]+|#[0-9]+|[A-Za-z]+);/g, (_m, ref) => {
+        if (ref.startsWith("#x"))
+            return String.fromCodePoint(parseInt(ref.slice(2), 16));
+        if (ref.startsWith("#"))
+            return String.fromCodePoint(parseInt(ref.slice(1), 10));
+        const v = ENTITIES[ref];
+        if (v === undefined)
+            throw new XmlError(`unknown entity &${ref};`);
+        return v;
+    });
+}
+function valueOf(e) {
+    if (e.children.length === 0) {
+        if (Object.keys(e.attrs).length === 0)
+            return e.text;
+        return { ...prefixed(e.attrs), ...(e.text.trim() !== "" ? { "#text": e.text } : {}) };
+    }
+    const groups = new Map();
+    for (const [name, v] of e.children) {
+        const list = groups.get(name);
+        if (list)
+            list.push(v);
+        else
+            groups.set(name, [v]);
+    }
+    const out = prefixed(e.attrs);
+    for (const [name, values] of groups)
+        out[name] = values.length === 1 ? values[0] : values;
+    return out;
+}
+function prefixed(attrs) {
+    return Object.fromEntries(Object.entries(attrs).map(([k, v]) => [`@${k}`, v]));
+}
+const ATTR = /([A-Za-z_][\w.:-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+function parseAttrs(s) {
+    const out = {};
+    for (const m of s.matchAll(ATTR))
+        out[m[1]] = decodeEntities(m[2] ?? m[3] ?? "");
+    return out;
+}
+/** Skip a construct starting at `i` that holds no data: declaration, processing instruction, comment. */
+function skipMarkup(xml, i) {
+    const ends = [
+        ["<?", "?>"],
+        ["<!--", "-->"],
+    ];
+    for (const [start, end] of ends) {
+        if (xml.startsWith(start, i)) {
+            const j = xml.indexOf(end, i + start.length);
+            if (j < 0)
+                throw new XmlError(`unterminated ${start}`);
+            return j + end.length;
+        }
+    }
+    return -1;
+}
+/** Handle a tag at `i` (`<…`); returns the index after it. */
+function tag(xml, i, stack, done) {
+    const skipped = skipMarkup(xml, i);
+    if (skipped >= 0)
+        return skipped;
+    if (xml.startsWith("<!DOCTYPE", i) || xml.startsWith("<!ENTITY", i))
+        throw new XmlError("DTDs and entity declarations are not accepted");
+    if (xml.startsWith("<![CDATA[", i))
+        return cdata(xml, i, stack);
+    const end = xml.indexOf(">", i);
+    if (end < 0)
+        throw new XmlError("unterminated tag");
+    const body = xml.slice(i + 1, end);
+    if (body.startsWith("/")) {
+        closingTag(body.slice(1).trim(), stack, done);
+        return end + 1;
+    }
+    const selfClosing = body.endsWith("/");
+    const inner = selfClosing ? body.slice(0, -1) : body;
+    const name = /^[^\s/>]+/.exec(inner)?.[0] ?? "";
+    if (!NAME.test(name))
+        throw new XmlError(`\`${name}\` is not an XML element name`);
+    if (stack.length >= XML_MAX_DEPTH)
+        throw new XmlError(`nested deeper than ${XML_MAX_DEPTH} elements`);
+    const open = { name, attrs: parseAttrs(inner.slice(name.length)), children: [], text: "" };
+    if (selfClosing)
+        close(open, stack, done);
+    else
+        stack.push(open);
+    return end + 1;
+}
+/** A CDATA section's text, appended to the element it is in; the index after it. */
+function cdata(xml, i, stack) {
+    const j = xml.indexOf("]]>", i);
+    if (j < 0 || stack.length === 0)
+        throw new XmlError("misplaced or unterminated CDATA section");
+    stack[stack.length - 1].text += xml.slice(i + 9, j);
+    return j + 3;
+}
+function closingTag(name, stack, done) {
+    const open = stack.pop();
+    if (!open || open.name !== name)
+        throw new XmlError(`unexpected closing tag </${name}>`);
+    close(open, stack, done);
+}
+function close(open, stack, done) {
+    const value = valueOf(open);
+    const parent = stack[stack.length - 1];
+    if (parent)
+        parent.children.push([open.name, value]);
+    else
+        done({ name: open.name, value });
+}
+/** An XML document as `{ <root>: <value> }`. */
+export function xmlDecode(xml) {
+    const stack = [];
+    let root;
+    let i = 0;
+    while (i < xml.length) {
+        const lt = xml.indexOf("<", i);
+        const text = xml.slice(i, lt < 0 ? xml.length : lt);
+        if (stack.length > 0)
+            stack[stack.length - 1].text += decodeEntities(text);
+        else if (text.trim() !== "")
+            throw new XmlError("text outside the root element");
+        if (lt < 0)
+            break;
+        if (root && skipMarkup(xml, lt) < 0)
+            throw new XmlError("more than one root element");
+        i = tag(xml, lt, stack, (r) => (root = r));
+    }
+    if (stack.length > 0)
+        throw new XmlError(`unclosed element <${stack[stack.length - 1].name}>`);
+    if (!root)
+        throw new XmlError("no root element");
+    return { [root.name]: root.value };
+}
+//# sourceMappingURL=xml.js.map

package/dist/xml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.js","sourceRoot":"","sources":["../src/xml.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@sponson/adapters",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.0",
+  "description": "The built-in resource adapters and secret sources for Sponson.",
+  "keywords": [
+    "sponson",
+    "release",
+    "preview-environments",
+    "deployment",
+    "ci",
+    "vercel",
+    "neon",
+    "clerk",
+    "adapters",
+    "secrets",
+    "recipes"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MishaBear94/Sponson.git",
+    "directory": "packages/adapters"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "yaml": "^2.8.1",
+    "@sponson/core": "0.5.0"
+  },
+  "devDependencies": {
+    "@sponson/sim": "0.5.0"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "recipes",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "homepage": "https://sponson.mintlify.site",
+  "bugs": {
+    "url": "https://github.com/MishaBear94/Sponson/issues"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
 }

package/recipes/amplify.yaml

@@ -0,0 +1,147 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# AWS Amplify Hosting API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: amplify
+title: AWS Amplify Hosting
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: CreateBranch
+    url: https://docs.aws.amazon.com/amplify/latest/APIReference/API_CreateBranch.html
+  - title: GetBranch
+    url: https://docs.aws.amazon.com/amplify/latest/APIReference/API_GetBranch.html
+  - title: UpdateBranch
+    url: https://docs.aws.amazon.com/amplify/latest/APIReference/API_UpdateBranch.html
+  - title: DeleteBranch
+    url: https://docs.aws.amazon.com/amplify/latest/APIReference/API_DeleteBranch.html
+  - title: Amplify endpoints and quotas
+    url: https://docs.aws.amazon.com/general/latest/gr/amplify.html
+  - title: Create a signed AWS API request (SigV4)
+    url: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html
+api:
+  base_url: https://amplify.us-east-1.amazonaws.com
+  base_url_env: AMPLIFY_API_URL
+  auth:
+    aws_sigv4: { region: us-east-1, service: amplify, access_key_id_env: AWS_ACCESS_KEY_ID, secret_access_key_env: AWS_SECRET_ACCESS_KEY }
+detect:
+  files: [amplify.yml]
+  starter:
+    - op: branch_variable
+      values: { branch_name: "${ctx.git.branch}" }
+  where:
+    app_id: "Amplify console → your app → App settings → General → App ID (`d…`), or `aws amplify list-apps --query 'apps[].appId'`"
+assumptions:
+  - id: AM1
+    verified: true
+    text: "The Amplify API is regional (`https://amplify.<region>.amazonaws.com`) and signed with SigV4 for the service `amplify`. The recipe defaults to `us-east-1`; an app in another region sets `base_url` and `auth` (with its `region`) in the provider block, and temporary credentials (a CI role) add `session_token_env: AWS_SESSION_TOKEN` there."
+    source: https://docs.aws.amazon.com/general/latest/gr/amplify.html
+  - id: AM2
+    verified: true
+    text: "`POST /apps/{appId}/branches` (CreateBranch) creates a branch from `branchName` (required) and optional `description`, `stage` (PRODUCTION, BETA, DEVELOPMENT, EXPERIMENTAL, PULL_REQUEST), `enableAutoBuild`, `environmentVariables`, …; it answers 200 with `{ branch }`."
+    source: https://docs.aws.amazon.com/amplify/latest/APIReference/API_CreateBranch.html
+  - id: AM3
+    verified: true
+    text: "`GET /apps/{appId}/branches/{branchName}` (GetBranch) answers `{ branch }` with `branchName`, `stage`, `description`, `enableAutoBuild` and `environmentVariables` (a map of string to string)."
+    source: https://docs.aws.amazon.com/amplify/latest/APIReference/API_GetBranch.html
+  - id: AM4
+    verified: true
+    text: "`POST /apps/{appId}/branches/{branchName}` (UpdateBranch) takes the same optional fields and answers `{ branch }`; `environmentVariables` is the branch's whole map of variables."
+    source: https://docs.aws.amazon.com/amplify/latest/APIReference/API_UpdateBranch.html
+  - id: AM5
+    verified: true
+    text: "`DELETE /apps/{appId}/branches/{branchName}` (DeleteBranch) deletes a branch; an unknown app or branch is 404 `NotFoundException`."
+    source: https://docs.aws.amazon.com/amplify/latest/APIReference/API_DeleteBranch.html
+  - id: AM6
+    verified: false
+    text: "UpdateBranch leaves the fields it is not sent as they are (so the branch op's update does not reset the variables, and the variable op's write does not reset the branch's settings), while an `environmentVariables` it is sent replaces the whole map, as the sim models it (assumption A4 of packages/sim/src/routes/aws.ts)."
+  - id: AM7
+    verified: false
+    text: "A build that ran before a variable was written does not see it: Sponson does not start a new job (StartJob), so order the variable lines before the branch's first build (`enable_auto_build: false` and a CI-started job, or the branch line, then the variables, then the push). The branches Amplify's own pull request previews make are not modelled; this recipe manages a branch the plan names."
+ops:
+  branch:
+    kind: resource
+    title: Branch
+    summary: "An Amplify branch named by the plan (the git branch of the pull request, `${ctx.git.branch}`), created with CreateBranch and deleted on destroy. Its `stage`, `description` and auto-build setting are compared: a console edit is drift. Variables on it are `amplify.branch_variable` lines."
+    covers: [amplify-branch]
+    params:
+      app_id:
+        type: string
+        required: true
+        pattern: "^d[a-z0-9]+$"
+        description: The Amplify app's id.
+        example: d1demo
+      branch_name:
+        type: string
+        required: true
+        description: The branch's name, as the repository names it.
+        example: "${ctx.scope}"
+      stage:
+        type: string
+        enum: [PRODUCTION, BETA, DEVELOPMENT, EXPERIMENTAL, PULL_REQUEST]
+        description: The branch's stage.
+        example: PULL_REQUEST
+      description:
+        type: string
+        description: The branch's description.
+        example: "Preview of ${ctx.scope}"
+      enable_auto_build:
+        type: boolean
+        description: Build automatically on every push (false lets CI start the build after the variables are written; AM7).
+    http:
+      read: { path: "/apps/{app_id}/branches/{branch_name}" }
+      create:
+        path: "/apps/{app_id}/branches"
+        body: { branchName: { param: branch_name } }
+      update: { method: POST }
+      item_path: /branch
+      id_path: /branchName
+      fields:
+        stage: { param: stage }
+        description: { param: description }
+        enableAutoBuild: { param: enable_auto_build }
+    sim:
+      id_from: branchName
+    live:
+      params: { app_id: SPONSON_LIVE_AMPLIFY_APP_ID }
+  branch_variable:
+    kind: list_item
+    title: Branch environment variable
+    summary: "One entry of a branch's `environmentVariables`, by read-modify-write of the whole map (UpdateBranch replaces the map it is sent); other variables are left alone, and the branch is locked while Sponson writes it. A branch that is not there yet reads as having no variables, so a plan that also creates the branch shows a create. Builds started before the write do not see it (AM7)."
+    covers: [amplify-branch]
+    params:
+      app_id:
+        type: string
+        required: true
+        pattern: "^d[a-z0-9]+$"
+        description: The Amplify app's id.
+        example: d1demo
+      branch_name:
+        type: string
+        required: true
+        description: The branch's name (a `{ from }` of the `amplify.branch` line orders the two).
+        example: "${ctx.scope}"
+      name:
+        type: string
+        required: true
+        description: The variable's name.
+        example: API_URL
+      value:
+        type: string
+        required: true
+        description: The variable's value.
+        example: "https://api-${ctx.scope}.example.app"
+    http:
+      parent: { path: "/apps/{app_id}/branches/{branch_name}", method: POST, send: collection, item_path: /branch, if_missing: empty }
+      list_path: /environmentVariables
+      shape: map
+      item: { param: name }
+      value: { param: value }
+    sim:
+      provider: aws
+      base_path: /aws/amplify
+      seed: { amplify: { d1demo: { branches: { pr-42: { environmentVariables: { NODE_ENV: production } } } } } }
+      present: /amplify/d1demo/branches/pr-42/environmentVariables/API_URL
+      drift:
+        changed: { amplify.d1demo.pr-42.API_URL: "https://somewhere-else.example" }
+        missing: { amplify.d1demo.pr-42.API_URL: delete }
+    live:
+      params: { app_id: SPONSON_LIVE_AMPLIFY_APP_ID, branch_name: SPONSON_LIVE_AMPLIFY_BRANCH }