@capacms/sdk 1.0.0-next.0 → 1.0.0-next.10

package/bin/capa-codegen.js

@@ -2,9 +2,29 @@
 /**
  * capa-codegen — write a tenant's generated types to disk.
  *
- *   CAPA_BASE_URL=... CAPA_API_KEY=... CAPA_TENANT_ID=... \
+ *   CAPA_API_URL=... CAPA_KEY=... CAPA_TENANT_ID=... \
  *     capa-codegen --out src/capa-types.ts
  *
+ * CAPA_API_URL and CAPA_KEY are the names every Capa tool reads;
+ * CAPA_BASE_URL and CAPA_API_KEY still work as aliases. A legacy key reads the
+ * /v2 schema with CAPA_TENANT_ID. A cap_ key, which /v2 does not take, reads
+ * the same interfaces from the key's GraphQL schema, with no tenant id; so
+ * does `--schema <file>`, a schema `--save-schema` wrote.
+ *
+ * GraphQL: the key's schema as types plus one TypedDocument per operation
+ * found in the project's .graphql files and gql`` templates. Needs the
+ * `graphql` package installed; no tenant id, since /api/ reads it from the key.
+ *
+ *   CAPA_API_URL=... CAPA_KEY=... \
+ *     capa-codegen --graphql --out src/capa-graphql.ts [--documents src] [--schema introspection.json]
+ *
+ * The variables are read from the shell first, then from the project's .env
+ * files as `next dev` reads them (.env.local, .env), so a Next.js site needs
+ * nothing more. `--watch` stays running and writes the module again whenever
+ * a document changes, and when the key's schema does (read again every
+ * minute). `--save-schema <file>` writes the schema it read, for a later
+ * `--schema <file>` run with no key, as in CI.
+ *
  * Exit codes: 0 wrote or already current, 1 failed, 2 --check found a diff.
  * `--check` is the CI mode: it fails when the committed file is out of date
  * with the tenant's schema, which is the whole point of committing it.
@@ -12,20 +32,187 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { generate } = require("../dist/codegen.js");
+const { loadProjectEnv } = require("./project-env.js");
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
 
 function arg(name, fallback) {
   const i = process.argv.indexOf(name);
   return i === -1 ? fallback : process.argv[i + 1];
 }
 
+/** How often --watch looks at the documents, and reads the key's schema again. */
+const WATCH_FILES_MS = 500;
+const WATCH_SCHEMA_MS = 60_000;
+
+/** One run of --graphql over `introspection`: the module written, or why not. 0, 1 or 2 as the exit codes above. */
+function writeModule(introspection, { out, roots, check }) {
+  const { generateGraphQLModule } = require("../dist/graphql-codegen.js");
+  const { findDocuments, printProblems } = require("./graphql-project.js");
+  const { documents, skipped } = findDocuments(roots);
+  const result = generateGraphQLModule(introspection, documents);
+  for (const s of [...skipped, ...result.skipped].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)) {
+    console.error(`capa-codegen: skipped ${s.file}:${s.line}: ${s.reason}.`);
+  }
+  if (result.warnings.length) {
+    console.error(`capa-codegen: ${plural(result.warnings.length, "use")} of a deprecated field, argument or value, which a later Capa-Version removes:`);
+    printProblems(result.warnings);
+  }
+  if (!result.source) {
+    console.error(`capa-codegen: ${result.problems.length} problem(s) in your GraphQL documents:`);
+    printProblems(result.problems);
+    return 1;
+  }
+  const target = path.resolve(process.cwd(), out);
+  const existing = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : null;
+  if (existing === result.source) {
+    console.log(`capa-codegen: ${out} is up to date (${plural(result.operations.length, "operation")}).`);
+    return 0;
+  }
+  if (check) {
+    console.error(`capa-codegen: ${out} is OUT OF DATE with the key's schema or your documents.\n  Run: capa-codegen --graphql --out ${out}`);
+    return 2;
+  }
+  fs.writeFileSync(target, result.source, "utf8");
+  console.log(`capa-codegen: wrote ${out}: the schema's types and ${plural(result.operations.length, "typed document")}.`);
+  return 0;
+}
+
+/** What the document files under `roots` are now, but for the module codegen writes: a change to any is a new run. */
+function documentsSignature(roots, out) {
+  const { listDocumentFiles } = require("./graphql-project.js");
+  const skip = path.resolve(process.cwd(), out);
+  return listDocumentFiles(roots)
+    .filter((file) => file !== skip)
+    .map((file) => {
+      const stat = fs.statSync(file, { throwIfNoEntry: false });
+      return stat ? `${file}:${stat.mtimeMs}:${stat.size}` : file;
+    })
+    .join("\n");
+}
+
+/**
+ * --watch: the module is written again whenever a document changes, and when
+ * the key's schema does. A problem is printed and the last good module stays
+ * in place, so `next dev` keeps running on it; Ctrl-C stops the watch.
+ */
+async function watchModule(options, readSchema) {
+  let introspection = await readSchema();
+  let signature = documentsSignature(options.roots, options.out);
+  writeModule(introspection, options);
+  console.log(`capa-codegen: watching ${options.roots} for changes to your GraphQL documents. Stop with Ctrl-C.`);
+  let schemaReadAt = Date.now();
+  let busy = false;
+  const tick = async () => {
+    if (busy) return;
+    busy = true;
+    try {
+      let changed = false;
+      const now = documentsSignature(options.roots, options.out);
+      if (now !== signature) {
+        signature = now;
+        changed = true;
+      }
+      if (Date.now() - schemaReadAt >= WATCH_SCHEMA_MS) {
+        schemaReadAt = Date.now();
+        const fresh = await readSchema();
+        if (JSON.stringify(fresh) !== JSON.stringify(introspection)) {
+          console.log("capa-codegen: the key's schema changed.");
+          introspection = fresh;
+          changed = true;
+        }
+      }
+      if (changed) writeModule(introspection, options);
+    } catch (error) {
+      console.error(`capa-codegen: ${error.message}`);
+    } finally {
+      busy = false;
+    }
+  };
+  const timer = setInterval(tick, WATCH_FILES_MS);
+  return new Promise((resolve) => {
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+      process.once(signal, () => {
+        clearInterval(timer);
+        resolve(0);
+      });
+    }
+  });
+}
+
+async function graphqlMain(check) {
+  const { defaultDocuments, loadIntrospection } = require("./graphql-project.js");
+  const options = { out: arg("--out", "capa-graphql.ts"), roots: arg("--documents", defaultDocuments()), check };
+  const schemaFile = arg("--schema");
+  const saveTo = arg("--save-schema");
+  const readSchema = async () => {
+    const introspection = await loadIntrospection(schemaFile);
+    if (saveTo) {
+      fs.writeFileSync(path.resolve(process.cwd(), saveTo), JSON.stringify({ data: introspection }, null, 1) + "\n", "utf8");
+      console.log(`capa-codegen: saved the key's schema to ${saveTo}.`);
+    }
+    return introspection;
+  };
+  if (process.argv.includes("--watch")) return watchModule(options, readSchema);
+  return writeModule(await readSchema(), options);
+}
+
+/**
+ * The REST types from the key's GraphQL schema, or from `--schema <file>`:
+ * the interfaces the /v2 schema gives a legacy key, for a cap_ key, which /v2
+ * refuses. Needs GraphQL on the API, and says so when it is off.
+ */
+async function restFromGraphQLMain(out, check) {
+  const { restTypesFromIntrospection } = require("../dist/codegen.js");
+  const { loadIntrospection } = require("./graphql-project.js");
+  let introspection;
+  try {
+    introspection = await loadIntrospection(arg("--schema"));
+  } catch (error) {
+    // 404 or 405: this API does not serve GraphQL (CAPA_API_GRAPHQL=off).
+    if (error.status !== 404 && error.status !== 405) throw error;
+    throw new Error(
+      `${error.message} capa-codegen reads a cap_ key's models from its GraphQL schema: ` +
+        "set CAPA_KEY to a pk_ key and CAPA_TENANT_ID to read the /v2 schema instead.",
+    );
+  }
+  const result = restTypesFromIntrospection(introspection);
+  const omitted = result.restOnly;
+  if (omitted.length) {
+    const names = omitted.length === 1 ? omitted[0] : `${omitted.slice(0, -1).join(", ")} and ${omitted[omitted.length - 1]}`;
+    console.error(
+      `capa-codegen: ${names} ${omitted.length === 1 ? "is" : "are"} not in the key's GraphQL schema, ` +
+        "since their type names would collide, so no type is written for them. entries.list reads them untyped.",
+    );
+  }
+  const target = path.resolve(process.cwd(), out);
+  const existing = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : null;
+  if (existing === result.source) {
+    console.log(`capa-codegen: ${out} is up to date with the key's GraphQL schema.`);
+    return 0;
+  }
+  if (check) {
+    console.error(`capa-codegen: ${out} is OUT OF DATE with the key's GraphQL schema.\n  Run: capa-codegen --out ${out}`);
+    return 2;
+  }
+  fs.writeFileSync(target, result.source, "utf8");
+  console.log(`capa-codegen: wrote ${out}: ${result.types.length} types, from the key's GraphQL schema.`);
+  return 0;
+}
+
 async function main() {
-  const out = arg("--out", "capa-types.ts");
+  loadProjectEnv();
   const check = process.argv.includes("--check");
+  if (process.argv.includes("--graphql")) return graphqlMain(check);
+
+  const out = arg("--out", "capa-types.ts");
   const config = {
-    baseUrl: process.env.CAPA_BASE_URL || "",
-    apiKey: process.env.CAPA_API_KEY || "",
+    baseUrl: process.env.CAPA_API_URL || process.env.CAPA_BASE_URL || "",
+    apiKey: process.env.CAPA_KEY || process.env.CAPA_API_KEY || "",
     tenantId: process.env.CAPA_TENANT_ID || "",
   };
+  // /v2 reads legacy keys only: a cap_ key reads the same models over GraphQL.
+  if (config.apiKey.startsWith("cap_") || arg("--schema")) return restFromGraphQLMain(out, check);
   const target = path.resolve(process.cwd(), out);
   const existing = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : null;
 
@@ -44,7 +231,7 @@ async function main() {
     return 2;
   }
   fs.writeFileSync(target, result.source, "utf8");
-  console.log(`capa-codegen: wrote ${out} — ${result.types.length} types (schema ${result.checksum}).`);
+  console.log(`capa-codegen: wrote ${out}: ${result.types.length} types (schema ${result.checksum}).`);
   return 0;
 }
 

package/bin/capa.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/**
+ * capa — the SDK's command line.
+ *
+ *   capa codegen [...]     same as capa-codegen; add --graphql for GraphQL types
+ *   capa persist [...]     register the project's GraphQL documents as persisted queries
+ *   capa <anything else>   @capacms/cli's command, when the project has that package
+ *
+ * `capa persist` finds every named operation in the project's .graphql files
+ * and marked templates (`#graphql`, `/* capa *\/`, gql), checks it against the
+ * key's schema, and sends it once with its sha256 to the API, which stores it.
+ * After that, `client.graphql(doc, vars, { persisted: true })` sends only the
+ * hash. The hashes are those of the exact text `capa-codegen --graphql`
+ * writes, so run both from the same documents. A document written as a
+ * literal is sent as written, so its own text is stored too, as
+ * `<Name> (literal)`.
+ *
+ *   CAPA_API_URL=https://api.capacms.com CAPA_DRAFT_KEY=cap_test_... capa persist [--documents src] [--manifest persisted.json]
+ *
+ * Two things must hold for a document to be stored (spec 17, amendment 28).
+ * The POST reaches the host that stores documents: api.capacms.com sends
+ * every POST there, and a self-hosted stack whose read host stores nothing
+ * names the other host in CAPA_ADMIN_URL, which wins over CAPA_API_URL. And
+ * the key is a development key, since a production key ships in site
+ * bundles: the key is CAPA_DRAFT_KEY (CAPA_KEY when that is unset), and a
+ * production key is refused before anything is sent.
+ *
+ * Every registration asks for a pin (`Capa-Persist: pin`, amendment 69). The
+ * store drops unpinned documents before any pinned one, so the documents a
+ * developer registers in the Explorer or a draft preview cannot push a live
+ * site's out. A document stored without its pin is exposed to exactly that,
+ * so it counts as a failure, not as stored.
+ *
+ * A pin names its build when the build says what it is (amendment 134):
+ * `Capa-Persist: pin; release=<id>; env=<env>`. The store keeps the pins of
+ * the latest 3 production releases before anything else, so a run of preview
+ * builds cannot push production's documents out. The label comes from
+ * --release and --env, else CAPA_RELEASE and CAPA_RELEASE_ENV, else the host
+ * the build runs on: Vercel (VERCEL_GIT_COMMIT_SHA, VERCEL_ENV) or Netlify
+ * (COMMIT_REF, CONTEXT). Both or neither, checked before anything is sent.
+ * Exit codes: 0 every document stored and pinned, 1 failed, 3 some were not.
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+
+/** The API's rules for a pin's labels (apps/api graphql/apq.ts, amendment 134). */
+const RELEASE = /^[A-Za-z0-9._-]{1,64}$/;
+const RELEASE_ENV = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** Hosts whose builds say which commit they build and where it deploys. */
+const BUILD_HOSTS = [
+  { host: "Vercel", release: "VERCEL_GIT_COMMIT_SHA", env: "VERCEL_ENV" },
+  { host: "Netlify", release: "COMMIT_REF", env: "CONTEXT", when: "NETLIFY" },
+];
+
+/**
+ * The build a pin belongs to, `{ release, env, from }`, or none when nothing
+ * names one; `{ error }` for a label the API would refuse, so nothing is sent.
+ * A flag wins over CAPA_RELEASE and CAPA_RELEASE_ENV, which win over the host.
+ */
+function persistLabels(env, arg) {
+  const set = (value) => (typeof value === "string" && value !== "" ? value : undefined);
+  const host = BUILD_HOSTS.find((h) => set(env[h.env]) !== undefined && (!h.when || set(env[h.when]) !== undefined));
+  const pick = (flag, variable, hostVariable) => {
+    if (set(arg(flag)) !== undefined) return { value: arg(flag), from: flag };
+    if (set(env[variable]) !== undefined) return { value: env[variable], from: variable };
+    if (host && set(env[hostVariable]) !== undefined) return { value: env[hostVariable], from: hostVariable };
+    return null;
+  };
+  const release = pick("--release", "CAPA_RELEASE", host?.release);
+  const where = pick("--env", "CAPA_RELEASE_ENV", host?.env);
+  if (!release && !where) return {};
+  if (!release || !where) {
+    const [given, missing] = release ? [release, "--env (or CAPA_RELEASE_ENV)"] : [where, "--release (or CAPA_RELEASE)"];
+    return { error: `${given.from} names ${release ? "a release" : "an environment"} but nothing names ${release ? "where it deploys" : "the release"}: pass ${missing} too. Nothing was sent.` };
+  }
+  if (!RELEASE.test(release.value)) {
+    return { error: `${release.from} is ${JSON.stringify(release.value)}; a release is 1 to 64 letters, digits, dots, dashes or underscores, such as a commit or a deploy id. Nothing was sent.` };
+  }
+  if (!RELEASE_ENV.test(where.value)) {
+    return { error: `${where.from} is ${JSON.stringify(where.value)}; an environment is a lowercase name such as production or preview. Nothing was sent.` };
+  }
+  return { release: release.value, env: where.value, from: release.from === where.from ? release.from : `${release.from} and ${where.from}` };
+}
+
+async function persist() {
+  require("./project-env.js").loadProjectEnv();
+  const { generateGraphQLModule } = require("../dist/graphql-codegen.js");
+  const { apiFromEnv, arg, defaultDocuments, findDocuments, keyEnvironment, loadIntrospection, printProblems, REQUEST_TIMEOUT_MS } =
+    require("./graphql-project.js");
+  const labels = persistLabels(process.env, arg);
+  if (labels.error) {
+    console.error(`capa persist: ${labels.error}`);
+    return 1;
+  }
+  const api = apiFromEnv(process.env, { admin: true });
+  if ((await keyEnvironment(api)) === "production") {
+    console.error(
+      `capa persist: ${api.keyName} is a production key, and only a development key stores persisted documents. ` +
+        "Set CAPA_DRAFT_KEY to a development key (Developers > Keys in the Capa admin). Nothing was sent.",
+    );
+    return 1;
+  }
+  const introspection = await loadIntrospection(arg("--schema"), api);
+  const { documents } = findDocuments(arg("--documents", defaultDocuments()));
+  const result = generateGraphQLModule(introspection, documents);
+  if (result.problems.length) {
+    console.error(`capa persist: ${result.problems.length} problem(s) in your GraphQL documents, nothing sent:`);
+    printProblems(result.problems);
+    return 1;
+  }
+  const pin = labels.release ? `pin; release=${labels.release}; env=${labels.env}` : "pin";
+  console.log(
+    labels.release
+      ? `capa persist: pinning for release ${labels.release} in ${labels.env} (from ${labels.from}).`
+      : "capa persist: pinning with no release. On a deploy, pass --release <commit> --env production (or preview) so the API keeps production's documents first.",
+  );
+  let notStored = 0;
+  let unpinned = 0;
+  let declined = 0;
+  const rows = [];
+  const sends = result.operations.flatMap((operation) => [
+    operation,
+    ...(operation.literal && operation.literal.document !== operation.document
+      ? [{ name: operation.name, label: `${operation.name} (literal)`, ...operation.literal }]
+      : []),
+  ]);
+  for (const operation of sends) {
+    const response = await api.fetchImpl(`${api.baseUrl}/api/graphql`, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "x-api-key": api.apiKey,
+        "Capa-Version": api.version,
+        "Capa-Persist": pin,
+      },
+      body: JSON.stringify({
+        query: operation.document,
+        operationName: operation.name,
+        extensions: { persistedQuery: { version: 1, sha256Hash: operation.sha256 } },
+      }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const body = await response.json().catch(() => ({}));
+    const stored = body?.extensions?.persistedQuery?.registered === true;
+    const pinned = stored && body.extensions.persistedQuery.pinned === true;
+    // A body with errors and no data is a refusal of the document, whether it
+    // came as a 4xx or, as GraphQL over HTTP sends it on application/json, a 200.
+    const refusal = body && typeof body === "object" && !("data" in body) ? body.errors?.[0] : undefined;
+    if (!pinned) notStored++;
+    if (stored && !pinned) unpinned++;
+    if (!stored && !refusal && response.status === 200) declined++;
+    const code = body?.errors?.[0]?.extensions?.code;
+    const why = pinned
+      ? "stored, pinned"
+      : stored
+        ? `stored, not pinned (the API ignored Capa-Persist: ${pin}, so other registrations can push it out)`
+        : refusal
+          ? `not stored (refused, ${refusal.extensions?.code ?? "error"}: ${refusal.message})`
+          : `not stored (HTTP ${response.status}${code ? `, ${code}` : ""})`;
+    rows.push({ name: operation.label ?? operation.name, sha256: operation.sha256, stored, pinned });
+    console.log(`${operation.sha256}  ${operation.label ?? operation.name}  ${why}`);
+  }
+  const manifest = arg("--manifest");
+  if (manifest) {
+    const build = labels.release ? { release: labels.release, env: labels.env } : {};
+    fs.writeFileSync(path.resolve(process.cwd(), manifest), JSON.stringify({ ...build, operations: rows }, null, 2) + "\n");
+  }
+  console.log(`capa persist: ${rows.length - notStored} of ${rows.length} documents stored, pinned.`);
+  if (unpinned) {
+    console.error(
+      `capa persist: ${unpinned} document${unpinned === 1 ? " was" : "s were"} stored without a pin. ` +
+        `Upgrade the API at ${api.baseUrl} to one that pins build documents (Capa-Version ${api.version}).`,
+    );
+  }
+  if (declined === rows.length && rows.length) {
+    console.error(
+      `capa persist: ${api.baseUrl} stored nothing. A host that serves reads only runs documents but never stores one: ` +
+        "set CAPA_ADMIN_URL to the API host your Capa admin uses (https://api.capacms.com sends every POST there), " +
+        `and make ${api.keyName} a development key.`,
+    );
+  }
+  return notStored ? 3 : 0;
+}
+
+/**
+ * The `capa` bin of @capacms/cli, when the project has it, or null.
+ *
+ * Both packages ship a `capa` bin, and a package manager links one of them.
+ * So each hands over the other's commands: @capacms/cli runs this file for
+ * codegen and persist, and this file runs @capacms/cli for everything else
+ * (login, entries, init, mcp and the rest). Whichever `capa` is linked, every
+ * command does the same thing. Without @capacms/cli nothing changes.
+ */
+function cliBin() {
+  const { createRequire } = require("node:module");
+  try {
+    const manifest = createRequire(path.join(process.cwd(), "package.json")).resolve("@capacms/cli/package.json");
+    const bin = JSON.parse(fs.readFileSync(manifest, "utf8")).bin;
+    const file = typeof bin === "string" ? bin : bin && bin.capa;
+    return file ? path.join(path.dirname(manifest), file) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  const [command] = process.argv.slice(2);
+  if (command === "persist") return persist();
+  if (command === "codegen") {
+    process.argv.splice(2, 1);
+    require("./capa-codegen.js");
+    return null;
+  }
+  const cli = cliBin();
+  if (cli) {
+    const result = require("node:child_process").spawnSync(process.execPath, [cli, ...process.argv.slice(2)], { stdio: "inherit" });
+    return result.status === null ? 1 : result.status;
+  }
+  console.error(
+    "usage: capa codegen [--graphql] [--out file] | CAPA_API_URL=... CAPA_DRAFT_KEY=... capa persist [--documents src] [--manifest file] [--release id --env production]",
+  );
+  return 1;
+}
+
+main().then(
+  (code) => {
+    if (code !== null) process.exit(code);
+  },
+  (err) => {
+    console.error(`capa: ${err.message}`);
+    process.exit(1);
+  },
+);

package/bin/graphql-project.js

@@ -0,0 +1,142 @@
+/**
+ * The I/O half of `capa-codegen --graphql` and `capa persist`: find a
+ * project's GraphQL documents on disk, and read the key's schema from Capa (or
+ * from a saved introspection file, for CI without a key).
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const { extractDocuments } = require("../dist/graphql-codegen.js");
+const { INTROSPECTION_QUERY } = require("../dist/next/graphql/introspection.js");
+const { runGraphQL } = require("../dist/next/graphql/request.js");
+
+const SKIP = new Set(["node_modules", ".git", ".next", "dist", "build", "out", "coverage", ".turbo"]);
+const EXTENSIONS = /\.(graphql|gql|[cm]?[jt]sx?)$/i;
+
+function walk(dir, files) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, files);
+    else if (EXTENSIONS.test(entry.name)) files.push(full);
+  }
+  return files;
+}
+
+/** Every file under `roots` (a comma-separated list of files or folders) that may hold a document, as absolute paths. */
+function listDocumentFiles(roots, cwd = process.cwd()) {
+  const files = [];
+  for (const root of roots.split(",").map((r) => r.trim()).filter(Boolean)) {
+    const absolute = path.resolve(cwd, root);
+    if (!fs.existsSync(absolute)) throw new Error(`${root} does not exist.`);
+    files.push(...(fs.statSync(absolute).isDirectory() ? walk(absolute, []).sort() : [absolute]));
+  }
+  return files;
+}
+
+/** Every document under `roots` (a comma-separated list of files or folders). */
+function findDocuments(roots, cwd = process.cwd()) {
+  const documents = [];
+  const skipped = [];
+  for (const file of listDocumentFiles(roots, cwd)) {
+    const found = extractDocuments(path.relative(cwd, file), fs.readFileSync(file, "utf8"));
+    documents.push(...found.documents);
+    skipped.push(...found.skipped);
+  }
+  return { documents, skipped };
+}
+
+/** The first of `names` set in `env`, as `[name, value]`, or null. */
+function firstSet(env, names) {
+  const name = names.find((n) => env[n]);
+  return name ? [name, env[name]] : null;
+}
+
+/**
+ * The API settings from env: `CAPA_API_URL` and `CAPA_KEY`, the names every
+ * Capa tool reads, with `CAPA_BASE_URL` and `CAPA_API_KEY` as aliases.
+ *
+ * With `admin` (for `capa persist`): the host is `CAPA_ADMIN_URL` when it is
+ * set, else `CAPA_API_URL`. `https://api.capacms.com` sends every POST to the
+ * host that stores persisted documents, so a site's own URL registers them; a
+ * self-hosted stack whose read host stores nothing names its admin host in
+ * `CAPA_ADMIN_URL`. The key is the development key, `CAPA_DRAFT_KEY` as
+ * `/nextjs` names it, since only a development key registers a document (spec
+ * 17, amendment 28). `CAPA_KEY` is read when `CAPA_DRAFT_KEY` is unset, and
+ * `keyName` says which one was, so a refusal can name the variable to change.
+ */
+function apiFromEnv(env = process.env, { admin = false } = {}) {
+  const rawUrl = (admin && env.CAPA_ADMIN_URL) || env.CAPA_API_URL || env.CAPA_BASE_URL;
+  const baseUrl = (rawUrl || "").replace(/\/+$/, "");
+  const keyNames = admin ? ["CAPA_DRAFT_KEY", "CAPA_KEY", "CAPA_API_KEY"] : ["CAPA_KEY", "CAPA_API_KEY"];
+  const [keyName, apiKey] = firstSet(env, keyNames) ?? [keyNames[0], ""];
+  const version = env.CAPA_API_VERSION || "2026-10-01";
+  const missing = [!baseUrl && "CAPA_API_URL", !apiKey && keyNames[0]].filter(Boolean);
+  if (missing.length) {
+    const command = admin ? "capa persist" : "capa-codegen";
+    throw new Error(
+      `missing ${missing.join(" and ")}. Set ${missing.length > 1 ? "them" : "it"} in your shell or in .env.local, which ${command} reads as next dev does.`,
+    );
+  }
+  return { baseUrl, apiKey, keyName, version, fetchImpl: globalThis.fetch };
+}
+
+/** How long one request of these commands may take. */
+const REQUEST_TIMEOUT_MS = 30_000;
+
+/**
+ * The key's environment (`production` or `development`) from `GET /api/me`,
+ * or null when the API does not say (an older API, a proxy, no route).
+ */
+async function keyEnvironment(api) {
+  try {
+    const response = await api.fetchImpl(`${api.baseUrl}/api/me`, {
+      headers: { Accept: "application/json", "x-api-key": api.apiKey, "Capa-Version": api.version },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok) return null;
+    const body = await response.json();
+    return typeof body?.data?.environment === "string" ? body.data.environment : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The key's schema: from `--schema <file>` when given, else one introspection request. */
+async function loadIntrospection(schemaFile, api) {
+  if (schemaFile) {
+    const parsed = JSON.parse(fs.readFileSync(schemaFile, "utf8"));
+    return parsed.data ?? parsed;
+  }
+  // By POST: `capa persist` may read it from an admin host, which serves GraphQL by POST only.
+  const result = await runGraphQL(api ?? apiFromEnv(), INTROSPECTION_QUERY, undefined, { method: "POST" });
+  if (!result.data || result.errors.length) {
+    const first = result.errors[0];
+    throw new Error(`introspection failed: ${first ? `${first.code}: ${first.message}` : "no data"}`);
+  }
+  return result.data;
+}
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(name);
+  return i === -1 ? fallback : process.argv[i + 1];
+}
+
+function defaultDocuments(cwd = process.cwd()) {
+  return fs.existsSync(path.join(cwd, "src")) ? "src" : ".";
+}
+
+function printProblems(problems, log = console.error) {
+  for (const p of problems) log(`  ${p.file}:${p.line}:${p.column}  ${p.message}`);
+}
+
+module.exports = {
+  apiFromEnv,
+  arg,
+  defaultDocuments,
+  findDocuments,
+  keyEnvironment,
+  listDocumentFiles,
+  loadIntrospection,
+  printProblems,
+  REQUEST_TIMEOUT_MS,
+};

package/bin/project-env.js

@@ -0,0 +1,58 @@
+/**
+ * A project's .env files, read the way `next dev` reads them, so the
+ * commands find CAPA_API_URL and the keys where a Next.js site keeps them.
+ *
+ * Next's own loader (`@next/env`) is used when the project has Next
+ * installed, so `$VAR` expansion and every other rule match what the site
+ * sees. Without it, a small parser reads the same files in the same order:
+ * `.env.<mode>.local`, `.env.local`, `.env.<mode>`, `.env`, the first file
+ * that sets a name winning, where the mode is `production` when NODE_ENV says
+ * so and `development` otherwise. A variable already in the environment is
+ * never replaced, so the shell and CI always win.
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const { createRequire } = require("node:module");
+
+/** `@next/env`'s `loadEnvConfig`, resolved through the project's own `next`, or null. */
+function nextEnvLoader(cwd) {
+  try {
+    const fromProject = createRequire(path.join(cwd, "package.json"));
+    const nextDir = path.dirname(fromProject.resolve("next/package.json"));
+    return createRequire(path.join(nextDir, "package.json"))("@next/env").loadEnvConfig;
+  } catch {
+    return null;
+  }
+}
+
+/** `KEY=value` lines: `export ` allowed, quotes removed, `#` comments and blank lines skipped. */
+function parseEnvFile(text) {
+  const values = {};
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line);
+    if (!match) continue;
+    const [, name, raw] = match;
+    const quoted = /^(["'])([\s\S]*)\1$/.exec(raw);
+    values[name] = quoted ? (quoted[1] === '"' ? quoted[2].replace(/\\n/g, "\n") : quoted[2]) : raw.replace(/\s+#.*$/, "");
+  }
+  return values;
+}
+
+/** Fill `env` from the project's .env files without replacing a name it already has. */
+function loadProjectEnv(cwd = process.cwd(), env = process.env) {
+  const mode = env.NODE_ENV === "production" ? "production" : "development";
+  const loadEnvConfig = env === process.env ? nextEnvLoader(cwd) : null;
+  if (loadEnvConfig) {
+    loadEnvConfig(cwd, mode === "development", { info() {}, error: (message) => console.error(message) });
+    return;
+  }
+  for (const name of [`.env.${mode}.local`, ".env.local", `.env.${mode}`, ".env"]) {
+    const file = path.join(cwd, name);
+    if (!fs.existsSync(file)) continue;
+    for (const [key, value] of Object.entries(parseEnvFile(fs.readFileSync(file, "utf8")))) {
+      if (!(key in env)) env[key] = value;
+    }
+  }
+}
+
+module.exports = { loadProjectEnv, parseEnvFile };

package/dist/client.d.ts

@@ -410,4 +410,9 @@ export interface SearchHit {
  * shadowing model. `getContentById` cannot be reached for such a row.
  */
 export declare function instanceIdOf(row: unknown): string | null;
+/**
+ * The legacy `/v2/api` client, for a legacy key (`pk_`, `sk_` or unprefixed)
+ * and its tenant's id. For `/api/`, GraphQL and `cap_` keys, import
+ * `createClient` from `@capacms/sdk/next`.
+ */
 export declare function createClient(config: CapaConfig): CapaClient;