@sponson/adapters 0.0.0-stage → 0.5.0

package/dist/recipes.js

@@ -0,0 +1,246 @@
+/**
+ * Recipes: verified `http` specs for one provider's operations, shipped as YAML in `packages/adapters/recipes/`
+ * (one file per provider), so that a plan line names an operation and fills in its typed params instead of writing
+ * request templates (ADR 0020, docs/recipes.md).
+ *
+ *   providers: { http: { cloudflare: { recipe: cloudflare } } }       # optional: the recipe's API defaults
+ *   - { id: dns, adapter: http, op: resource, recipe: cloudflare.dns_cname, zone_id: …, name: …, target: … }
+ *
+ * A recipe line expands, before anything else reads it, into the `http.resource`, `http.list_item` or `http.action` params the
+ * recipe declares, with `{ param: <name> }` values and `{<name>}` path placeholders filled from the line. Identity
+ * is never the recipe's text: the ledger records the resolved API block (base URL, credential variable names,
+ * headers, encoding) and the keys and record ids the expanded requests produce, exactly as for a hand-written
+ * line. Pure apart from reading the shipped files once.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { SponsonError, markerKind } from "@sponson/core";
+import { paramError } from "./common.js";
+import { isObject } from "./http.js";
+/** Where the shipped recipe files are, in the source tree and in the published package alike. */
+export const RECIPES_DIR = fileURLToPath(new URL("../recipes/", import.meta.url));
+/**
+ * The environment variables a recipe's API block reads its credential from, in the order the block names them.
+ * Empty for a recipe without an API block and for a token a command prints (`az`, `gcloud`: their own login).
+ */
+export function recipeCredentialEnv(recipe) {
+    const auth = recipe.api?.auth;
+    if (!isObject(auth))
+        return [];
+    const names = (o, keys) => (isObject(o) ? keys.flatMap((k) => (typeof o[k] === "string" ? [o[k]] : [])) : []);
+    if (Array.isArray(auth.headers))
+        return auth.headers.flatMap((h) => names(h, ["value_env"]));
+    return [
+        ...names(auth, ["bearer_env", "value_env"]),
+        ...names(auth.oauth2_client_credentials, ["client_id_env", "client_secret_env"]),
+        ...names(auth.aws_sigv4, ["access_key_id_env", "secret_access_key_env"]),
+        ...names(auth.digest, ["user_env", "password_env"]),
+        ...names(auth.basic, ["user_env", "password_env"]),
+    ];
+}
+const ADAPTER = "http";
+const cache = new Map();
+/** Recipes made known without a file (`useRecipe`), by provider. */
+const unshipped = new Map();
+/** The providers that have a recipe, sorted. */
+export function recipeNames() {
+    const files = readdirSync(RECIPES_DIR)
+        .filter((f) => f.endsWith(".yaml"))
+        .map((f) => f.slice(0, -".yaml".length));
+    return [...new Set([...files, ...unshipped.keys()])].sort();
+}
+/**
+ * Make a recipe known for this process as if it were shipped, until the returned function is called. For tests of
+ * code that recipes drive (the adapter's own tests use it for a list item recipe); not exported by the package.
+ */
+export function useRecipe(recipe) {
+    unshipped.set(recipe.provider, recipe);
+    cache.set(recipe.provider, recipe);
+    return () => {
+        unshipped.delete(recipe.provider);
+        cache.delete(recipe.provider);
+    };
+}
+/** A provider's recipe; PARAM_INVALID naming the known ones when there is none. */
+export function loadRecipe(provider, param = "recipe") {
+    const cached = cache.get(provider);
+    if (cached)
+        return cached;
+    const known = recipeNames();
+    if (!known.includes(provider))
+        throw paramError(ADAPTER, `no recipe for \`${provider}\` (known: ${known.join(", ") || "none"})`, param);
+    const recipe = parseYaml(readFileSync(`${RECIPES_DIR}${provider}.yaml`, "utf8"));
+    // A malformed shipped file is a bug of this package (packages/adapters/src/recipes.test.ts checks every one).
+    if (!isObject(recipe) || recipe.provider !== provider || !isObject(recipe.ops) || (recipe.api !== undefined && !isObject(recipe.api))) {
+        throw new SponsonError("INTERNAL", `${ADAPTER}: recipes/${provider}.yaml is malformed`, { adapter: ADAPTER, recipe: provider });
+    }
+    cache.set(provider, recipe);
+    return recipe;
+}
+/** Every shipped recipe. */
+export function loadRecipes() {
+    return recipeNames().map((p) => loadRecipe(p));
+}
+/** A line's `recipe: <provider>.<op>`, located. */
+export function recipeOp(ref) {
+    if (typeof ref !== "string" || !/^[a-z0-9][a-z0-9_-]*\.[a-z0-9_]+$/.test(ref)) {
+        throw paramError(ADAPTER, "`recipe` must be `<provider>.<op>`, e.g. `cloudflare.dns_cname` (see docs/recipes.md)", "recipe");
+    }
+    const [provider, name] = ref.split(".");
+    const recipe = loadRecipe(provider);
+    const op = recipe.ops[name];
+    if (!op)
+        throw paramError(ADAPTER, `recipe \`${provider}\` has no op \`${name}\` (known: ${Object.keys(recipe.ops).join(", ")})`, "recipe");
+    return { recipe, name, op };
+}
+/** The API a line uses: its `api`, or for a recipe line without one, the recipe's provider. */
+export function lineApi(params) {
+    if (params.api !== undefined || typeof params.recipe !== "string")
+        return params.api;
+    return params.recipe.split(".")[0];
+}
+/** Params of a recipe line that are the line's own, not the recipe's. */
+const LINE_PARAMS = ["api", "recipe", "destroy", "credential"];
+/** A value the engine fills in later or keeps as it is: a reference, a marker, an uninterpolated `${…}`. */
+function isDeferred(v) {
+    if (markerKind(v) !== null)
+        return true;
+    if (typeof v === "string")
+        return v.includes("${");
+    if (!isObject(v))
+        return false;
+    const keys = Object.keys(v);
+    return keys.length === 1 && ["from", "secret", "keep"].includes(keys[0]);
+}
+const TYPE_CHECK = {
+    string: (v) => typeof v === "string",
+    integer: (v) => Number.isInteger(v),
+    number: (v) => typeof v === "number" && Number.isFinite(v),
+    boolean: (v) => typeof v === "boolean",
+    list: (v) => Array.isArray(v),
+    map: (v) => isObject(v),
+};
+function checkValue(where, name, p, v) {
+    if (isDeferred(v))
+        return;
+    const fail = (why) => paramError(ADAPTER, `${where}: \`${name}\` ${why}`, name);
+    if (!TYPE_CHECK[p.type](v))
+        throw fail(`must be ${p.type === "integer" ? "an" : "a"} ${p.type} (${p.description})`);
+    if (p.enum && !p.enum.some((e) => e === v))
+        throw fail(`must be one of ${p.enum.map((e) => JSON.stringify(e)).join(", ")}`);
+    if (p.pattern && typeof v === "string" && !new RegExp(p.pattern).test(v))
+        throw fail(`must match ${p.pattern} (${p.description})`);
+}
+/** The value of every param the line sets or the recipe defaults, checked; PARAM_INVALID naming the param otherwise. */
+export function recipeValues(params) {
+    const { recipe, name, op } = recipeOp(params.recipe);
+    const where = `recipe ${recipe.provider}.${name}`;
+    const declared = Object.keys(op.params);
+    const extra = Object.keys(params).find((k) => !LINE_PARAMS.includes(k) && !declared.includes(k));
+    if (extra)
+        throw paramError(ADAPTER, `${where}: \`${extra}\` is not one of its params (known: ${declared.join(", ")})`, extra);
+    const values = {};
+    for (const [p, spec] of Object.entries(op.params)) {
+        const v = params[p] ?? spec.default;
+        if (v === undefined || v === null) {
+            if (spec.required)
+                throw paramError(ADAPTER, `${where}: \`${p}\` is required: ${spec.description}`, p);
+            continue;
+        }
+        checkValue(where, p, spec, v);
+        values[p] = v;
+    }
+    return values;
+}
+/** `{ param: <name> }`, the one template form of a recipe's http spec. */
+function paramRef(v) {
+    return isObject(v) && Object.keys(v).length === 1 && typeof v.param === "string" ? v.param : undefined;
+}
+/** `{ join: [ … ] }`'s parts, when `v` is one: the other template form, concatenating whole values. */
+function joinParts(v) {
+    return isObject(v) && Object.keys(v).length === 1 && Array.isArray(v.join) ? v.join : undefined;
+}
+/**
+ * `{ join: [<part>, …] }`: the parts (literal strings, numbers, or `{ param: <name> }`) as one string, such as a
+ * preview URL and a path. A part that is not known yet (a reference, a marker) stands for the whole value, so a
+ * pending URL makes the joined value pending; a param without a value removes the value. Never anything richer:
+ * a recipe stays data (ADR 0020, "Amendment").
+ */
+function join(parts, values) {
+    const filled = parts.map((p) => substitute(p, values));
+    if (filled.some((p) => p === undefined))
+        return undefined;
+    // `${ctx.*}` inside a string joins like any text; a marker or a `{ from }` the engine has not resolved does not.
+    const deferred = filled.find((p) => markerKind(p) !== null || isObject(p));
+    if (deferred !== undefined)
+        return deferred;
+    return filled.map((p) => String(p)).join("");
+}
+/**
+ * `tpl` with every `{ param: <name> }` replaced by its value (a param without one removes its map key or list
+ * item) and every `{ join: [...] }` by its parts joined.
+ */
+export function substitute(tpl, values) {
+    const ref = paramRef(tpl);
+    if (ref !== undefined)
+        return values[ref];
+    const parts = joinParts(tpl);
+    if (parts !== undefined)
+        return join(parts, values);
+    if (Array.isArray(tpl))
+        return tpl.map((x) => substitute(x, values)).filter((x) => x !== undefined);
+    if (!isObject(tpl))
+        return tpl;
+    const out = {};
+    for (const [k, v] of Object.entries(tpl)) {
+        const s = substitute(v, values);
+        if (s !== undefined)
+            out[k] = s;
+    }
+    return out;
+}
+/**
+ * A line's params as the `http.<kind>` op reads them: unchanged without `recipe`, else the recipe's spec with the
+ * line's values filled in (`vars` holds every value, for the `{<name>}` path placeholders).
+ */
+export function expandRecipe(params, kind) {
+    if (params.recipe === undefined)
+        return params;
+    const { recipe, name, op } = recipeOp(params.recipe);
+    if (op.kind !== kind)
+        throw paramError(ADAPTER, `recipe ${recipe.provider}.${name} is an \`http.${op.kind}\` recipe: write \`op: ${op.kind}\``, "recipe");
+    const values = recipeValues(params);
+    const spec = substitute(op.http, values);
+    const destroy = recipeDestroy(`recipe ${recipe.provider}.${name}`, op, params.destroy);
+    // A recipe without an API block (only `url` actions) gives the line no `api` unless it writes one.
+    const api = recipe.api ? lineApi(params) : params.api;
+    const credential = params.credential !== undefined ? { credential: params.credential } : {};
+    return { ...spec, ...(api !== undefined ? { api } : {}), vars: values, ...(destroy !== undefined ? { destroy } : {}), ...credential };
+}
+/** The line's `destroy`, or the op's default; `delete` of an op the provider cannot delete is PARAM_INVALID. */
+function recipeDestroy(where, op, line) {
+    if (op.destroy === "never" && line !== undefined && line !== "keep") {
+        throw paramError(ADAPTER, `${where}: the provider offers no way to delete what it makes, so it is always left in place: remove \`destroy\` or write \`destroy: keep\``, "destroy");
+    }
+    return line ?? (op.destroy === undefined ? undefined : "keep");
+}
+/**
+ * A `providers.http.<api>` block with `recipe:`, resolved: the recipe's API defaults, then the block's own keys
+ * over them. Blocks without `recipe:` are returned as they are. The result never names the recipe, so it (and with
+ * it the ledger identity) is the same as a hand-written block with the same values.
+ */
+export function resolveRecipeApi(block, where) {
+    if (block.recipe === undefined)
+        return block;
+    const known = recipeNames();
+    const { recipe: provider, ...overrides } = block;
+    if (typeof provider !== "string" || !known.includes(provider)) {
+        throw new SponsonError("PLAN_INVALID", `${ADAPTER}: ${where}.recipe: no recipe \`${String(provider)}\` (known: ${known.join(", ")})`, { adapter: ADAPTER, key: `${where}.recipe` });
+    }
+    const api = loadRecipe(provider).api;
+    if (!api)
+        throw new SponsonError("PLAN_INVALID", `${ADAPTER}: ${where}.recipe: recipe \`${provider}\` has no API block (its ops call the app's own URL)`, { adapter: ADAPTER, key: `${where}.recipe` });
+    return { ...api, ...overrides };
+}
+//# sourceMappingURL=recipes.js.map

package/dist/recipes.js.map

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

package/dist/secrets.d.ts

@@ -0,0 +1,72 @@
+import { type SecretSource } from "@sponson/core";
+/** Runs a CLI and returns its stdout. Injected in tests so no real `doppler`/`op`/`aws` is needed. */
+export type Exec = (file: string, args: string[], env: NodeJS.ProcessEnv) => Promise<string>;
+/**
+ * Runs the real binary from PATH; rejects with its stderr when it fails. A binary that cannot be started keeps the
+ * system error's `code` (`ENOENT`, `EACCES`), so the caller can say what is wrong instead of echoing it.
+ */
+export declare const defaultExec: Exec;
+/** `env://NAME` → process environment. Zero configuration; the CI default. */
+export declare const envSecretSource: SecretSource;
+/** `doppler://project/config/NAME` → `doppler secrets get`. Uses the CLI's login or DOPPLER_TOKEN from the env. */
+export declare function dopplerSecretSource(exec?: Exec): SecretSource;
+/** `op://vault/item/field` → `op read`, which accepts the reference as-is. */
+export declare function opSecretSource(exec?: Exec): SecretSource;
+/**
+ * `aws-sm://<secret-id>` → `aws secretsmanager get-secret-value`, through the `aws` CLI so the AWS SDK stays out of
+ * the dependency tree. The secret id is a name or an ARN; region, profile and credentials come from the CLI's own
+ * conventions (`AWS_REGION`, `AWS_PROFILE`, ...). `aws-sm://<secret-id>#<key>` picks one key of a JSON secret, the
+ * shape the AWS console creates for key/value secrets.
+ */
+export declare function awsSecretsManagerSource(exec?: Exec): SecretSource;
+/**
+ * `gcp-sm://<project>/<secret>[/<version>]` → `gcloud secrets versions access`, through the `gcloud` CLI so the Google
+ * SDK stays out of the dependency tree. The version defaults to `latest`; credentials come from the CLI's own
+ * conventions (`gcloud auth`, `CLOUDSDK_*`, `GOOGLE_APPLICATION_CREDENTIALS`). The project is part of the reference
+ * so a plan never depends on whichever project the runner's gcloud happens to have configured.
+ */
+export declare function gcpSecretManagerSource(exec?: Exec): SecretSource;
+/**
+ * `infisical://<projectId>/<env>/[<folder>/…/]<NAME>` → `infisical secrets get`, through the Infisical CLI
+ * (https://infisical.com/docs/cli/commands/secrets). The folders become `--path` (default `/`). Credentials come
+ * from the CLI's own conventions: `INFISICAL_TOKEN` (or `INFISICAL_UNIVERSAL_AUTH_ACCESS_TOKEN`) for a machine
+ * identity, else the CLI's login; `INFISICAL_DOMAIN` for EU Cloud or a self-hosted instance. The project id is part of
+ * the reference because a machine identity has no `.infisical.json` to take it from.
+ *
+ * JSON output, not `--plain`: with `--plain` an unknown name prints nothing at all (exit 0), indistinguishable from
+ * an empty secret; with `--output json` it prints the entry with the value `*not found*`, which is refused here.
+ */
+export declare function infisicalSecretSource(exec?: Exec): SecretSource;
+/**
+ * `azure-kv://<vault>/<name>[/<version>]` → `az keyvault secret show`, through the Azure CLI so neither the Azure SDK
+ * nor an Entra ID token flow enters the dependency tree. The CLI rather than `GET {vault}/secrets/{name}` with a token
+ * from `az account get-access-token`: one process instead of two, and the CLI already knows the vault DNS suffix of
+ * the signed-in cloud (`vault.azure.net`, `vault.azure.cn`, `vault.usgovcloudapi.net`) and every way to sign in
+ * (`az login`, a service principal, a managed identity, federated CI credentials).
+ * https://learn.microsoft.com/en-us/cli/azure/keyvault/secret#az-keyvault-secret-show
+ */
+export declare function azureKeyVaultSource(exec?: Exec): SecretSource;
+/**
+ * `bws://<secret-id>` → `bws secret get`, through the Bitwarden Secrets Manager CLI
+ * (https://bitwarden.com/help/secrets-manager-cli/). The machine account's access token comes from
+ * `BWS_ACCESS_TOKEN`, a self-hosted server from `BWS_SERVER_URL` (both read by the CLI itself: crates/bws/src/cli.rs
+ * in bitwarden/sdk-sm). `--color no`: the CLI colours its JSON whenever it believes the terminal supports colour,
+ * which `FORCE_COLOR` in CI makes it believe.
+ */
+export declare function bitwardenSecretsManagerSource(exec?: Exec): SecretSource;
+/**
+ * `vault://<mount>/<path>#<key>` → HashiCorp Vault's KV v2 "read secret version", `GET /v1/<mount>/data/<path>`
+ * (https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2), over the adapters' HTTP client, no SDK. The
+ * address is `VAULT_ADDR`, the token `VAULT_TOKEN` (sent as `X-Vault-Token`), and `VAULT_NAMESPACE`, when set, is
+ * sent as `X-Vault-Namespace` (Vault Enterprise, HCP Vault Dedicated: https://developer.hashicorp.com/vault/api-docs).
+ * The mount is the first segment; the latest version is read. `#key` picks one key of the secret's map.
+ */
+export declare const vaultSecretSource: SecretSource;
+/**
+ * `op-connect://<vault>/<item>/[<section>/]<field>` → a 1Password Connect server's REST API
+ * (https://www.1password.dev/connect/api-reference/): `GET /v1/vaults/{vault}/items/{item}`, bearer
+ * `OP_CONNECT_TOKEN`, at `OP_CONNECT_HOST` (the variables 1Password's own Connect SDKs and `op` read). Vaults and
+ * items are named by id or by name / title (looked up with `GET /v1/vaults?filter=name eq "…"` and
+ * `GET /v1/vaults/{vault}/items?filter=title eq "…"`; a name must be unique); fields by id or label.
+ */
+export declare const opConnectSecretSource: SecretSource;