@capacms/mcp 0.2.0

package/lib/graphql/names.mjs

@@ -0,0 +1,131 @@
+/**
+ * names.mjs — how REST's `select`, `sort` and `where` write a field
+ * namespace, and how they read one back (spec 17, amendment 121).
+ *
+ * A namespace is whatever the admin saved, so any character can be in one:
+ * `am/pm_indicator`, `price.usd`, `a,b`. All three grammars write it the same
+ * way:
+ * - BARE when none of its characters means something in any of them and it
+ *   starts with neither `$` (a system key) nor `-` (a descending sort):
+ *   `title`, `open-time`, `am/pm_indicator`.
+ * - QUOTED otherwise, a quote inside doubled: `"price.usd"`, `"a,b"`,
+ *   `"say ""hi"""`. A quoted name is always a field, never a system key, a
+ *   relation hop or a modifier.
+ *
+ * A namespace that starts with `$` cannot be named at all, since `$tags` is
+ * the system key; `select=*` still returns it.
+ *
+ * The API's writer is `writeName` in `@capa/shared`, and `@capacms/sdk` has
+ * the same rule in src/next/field-names.ts. This package has no
+ * dependencies, so it keeps its own copy, and all three are tested against
+ * packages/sdk/test/fixtures/field-names.json.
+ */
+
+export const NAME_QUOTE = '"';
+
+/** The sigil REST writes a system key with where a field shadows it (`$tags`). */
+const SYSTEM_KEY_SIGIL = "$";
+
+/** Characters that mean something in `select`, `sort` or a filter path. */
+const MEANINGFUL = new Set([",", "(", ")", ":", ".", NAME_QUOTE, "*", "[", "]"]);
+
+/** Whether a character can stand in a bare name. */
+const isNameChar = (ch) => !MEANINGFUL.has(ch) && !/\s/.test(ch);
+
+/** Whether REST can name a field namespace at all: every one but an empty one or one starting with `$`. */
+export const isNameable = (namespace) => namespace !== "" && !namespace.startsWith(SYSTEM_KEY_SIGIL);
+
+/** A namespace as every REST grammar writes it: bare where it can be, quoted otherwise. */
+export function writeName(namespace) {
+  const bare = isNameable(namespace) && !namespace.startsWith("-") && [...namespace].every(isNameChar);
+  if (bare) return namespace;
+  return `${NAME_QUOTE}${namespace.split(NAME_QUOTE).join(NAME_QUOTE + NAME_QUOTE)}${NAME_QUOTE}`;
+}
+
+/** One segment of a sort or filter path: a system key (`$id`) keeps its sigil, a namespace is written by `writeName`. */
+export const writePathSegment = (segment) => (segment.startsWith(SYSTEM_KEY_SIGIL) ? segment : writeName(segment));
+
+/** A path (`["at.place", "zip.code"]`) as sort and where write it: `"at.place"."zip.code"`. */
+export const writePath = (path) => path.map(writePathSegment).join(".");
+
+/** The quoted name opening at `text[pos]`, and the index just past its closing quote; null when it never closes. */
+export function readQuoted(text, pos) {
+  let name = "";
+  let i = pos + 1;
+  while (i < text.length) {
+    if (text[i] === NAME_QUOTE) {
+      if (text[i + 1] !== NAME_QUOTE) return { name, end: i + 1 };
+      name += NAME_QUOTE;
+      i += 2;
+      continue;
+    }
+    name += text[i];
+    i += 1;
+  }
+  return null;
+}
+
+/** A name as written, read back: `"price.usd"` is `price.usd`, a bare name is itself. Null for a quote that does not close the name. */
+export function readName(text) {
+  if (!text.startsWith(NAME_QUOTE)) return text;
+  const quoted = readQuoted(text, 0);
+  return quoted && quoted.end === text.length ? quoted.name : null;
+}
+
+/**
+ * `text` split on `separator` wherever it stands outside a quoted name and,
+ * unless `nested` is false, outside parentheses: a select level is split on
+ * its commas outside both, a list of names on its commas outside quotes.
+ * Null when a quote never closes.
+ */
+export function splitOutside(text, separator, { nested = true } = {}) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === NAME_QUOTE) {
+      const quoted = readQuoted(text, i);
+      if (!quoted) return null;
+      i = quoted.end;
+      continue;
+    }
+    if (nested && ch === "(") depth += 1;
+    else if (nested && ch === ")") depth -= 1;
+    else if (ch === separator && depth === 0) {
+      parts.push(text.slice(start, i));
+      start = i + 1;
+    }
+    i += 1;
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
+/**
+ * A sort or filter path's segments, split on the dots outside quotes, each
+ * read back as `{ name, quoted }` (`"at.place"."zip.code"` is `at.place` then
+ * `zip.code`); a quoted segment is always a field. A bare segment is
+ * everything up to the next dot, as the API reads it. Null when a quote never
+ * closes or runs into something other than a dot.
+ */
+export function readPath(text) {
+  const segments = [];
+  let i = 0;
+  for (;;) {
+    if (text[i] === NAME_QUOTE) {
+      const quoted = readQuoted(text, i);
+      if (!quoted || (quoted.end < text.length && text[quoted.end] !== ".")) return null;
+      segments.push({ name: quoted.name, quoted: true });
+      i = quoted.end;
+    } else {
+      const dot = text.indexOf(".", i);
+      const end = dot === -1 ? text.length : dot;
+      segments.push({ name: text.slice(i, end), quoted: false });
+      i = end;
+    }
+    if (i >= text.length) return segments;
+    i += 1;
+  }
+}

package/lib/graphql/schema.mjs

@@ -0,0 +1,237 @@
+/**
+ * schema.mjs — the key's GraphQL schema: fetched once, cached, compacted.
+ *
+ * One POST of the introspection query (with the `version` root field beside
+ * it) answers every schema question the tools ask. It is cached per process
+ * for 60 seconds per API version: long enough that an agent's burst of calls
+ * costs one request, short enough that a model edited in the admin shows up
+ * within a minute.
+ *
+ * THE SAME COMPACTION AS `@capacms/sdk`'s `summarizeIntrospection`, written
+ * again here because this package has no dependencies. Both are tested
+ * against the same fixture and vector file (`packages/sdk/test/fixtures/`), so
+ * a change to one that the other does not share fails a test. Names are READ
+ * from introspection and never derived: the API owns the naming rules.
+ */
+import { apiNextPost } from "../client.mjs";
+import { readName, splitOutside } from "./names.mjs";
+import { whenNotServed } from "./served.mjs";
+
+export const INTROSPECTION_QUERY = `query CapaIntrospection {
+  version
+  __schema {
+    queryType { name }
+    types { ...FullType }
+  }
+}
+
+fragment FullType on __Type {
+  kind
+  name
+  description
+  fields(includeDeprecated: true) {
+    name
+    description
+    args(includeDeprecated: true) { ...InputValue }
+    type { ...TypeRef }
+    isDeprecated
+    deprecationReason
+  }
+  inputFields(includeDeprecated: true) { ...InputValue }
+  interfaces { ...TypeRef }
+  enumValues(includeDeprecated: true) { name description isDeprecated deprecationReason }
+  possibleTypes { ...TypeRef }
+}
+
+fragment InputValue on __InputValue {
+  name
+  description
+  type { ...TypeRef }
+  defaultValue
+  isDeprecated
+  deprecationReason
+}
+
+fragment TypeRef on __Type {
+  kind
+  name
+  ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } }
+}`;
+
+export const SCHEMA_TTL_MS = 60_000;
+
+const cache = new Map();
+
+export function __resetGraphQLSchemaCacheForTests() {
+  cache.clear();
+}
+
+/** The named type under any NON_NULL and LIST wrappers. */
+export function namedType(ref) {
+  let current = ref;
+  while (current && current.name == null) current = current.ofType;
+  return current?.name ?? "";
+}
+
+/** The type as SDL writes it: `[Authors!]!`. */
+export function printTypeRef(ref) {
+  if (ref.kind === "NON_NULL" && ref.ofType) return `${printTypeRef(ref.ofType)}!`;
+  if (ref.kind === "LIST" && ref.ofType) return `[${printTypeRef(ref.ofType)}]`;
+  return ref.name ?? "";
+}
+
+function isListType(ref) {
+  for (let current = ref; current; current = current.ofType) if (current.kind === "LIST") return true;
+  return false;
+}
+
+const MODEL_DESCRIPTION = /\(model ([^()\s]+)\)$/;
+/**
+ * N9's field tag, on the description's last line. The lines above it are the
+ * field's label and an enum's options, for people (spec 17, amendment 49).
+ * The namespace is written as REST writes it, quoted when it holds a
+ * character REST's grammars use (`"price.usd"`, amendment 121), so it is read
+ * back before use.
+ */
+const FIELD_DESCRIPTION = /(?:^|\n)Capa field ("(?:[^"]|"")*"|[^,\s]+), type (\S+)(?: of (\S+))?(?:, model ([^,\s]+))?$/;
+/** N9: the second line of a model type's description, when N5 left fields out. */
+const NOT_EXPOSED = /^Not exposed: (.+)$/m;
+/** N9: the Query description's list of the models N1 leaves out of GraphQL. */
+const MODELS_NOT_EXPOSED = /Models not exposed in GraphQL: ([^\n]+?)\.?$/m;
+
+/** The namespaces of an N9 list line, each bare or quoted as REST writes it. */
+function namespaceList(line) {
+  if (!line) return [];
+  const items = splitOutside(line[1], ",", { nested: false }) ?? line[1].split(",");
+  return items.map((item) => item.trim()).filter(Boolean).map((item) => readName(item) ?? item);
+}
+
+/** The namespaces a model type's description lists as not exposed. */
+const notExposedFields = (description) => namespaceList(NOT_EXPOSED.exec(description ?? ""));
+
+/** N9's field tag read: its namespace unquoted, its types and target; null when the field has no tag. */
+function parseFieldDescription(description) {
+  const match = FIELD_DESCRIPTION.exec(description ?? "");
+  const namespace = match ? readName(match[1]) : null;
+  if (!match || namespace === null) return null;
+  return { namespace, capaType: match[2], arrayType: match[3] ?? null, target: match[4] ?? null };
+}
+
+function kindOf(field, types, modelTypes) {
+  const named = namedType(field.type);
+  const list = isListType(field.type);
+  if (named === "ID") return list ? "idList" : "id";
+  if (named === "Media") return "media";
+  if (named === "JSON") return "json";
+  if (modelTypes.has(named)) return "relation";
+  if (named.endsWith("RelationConnection") && types.get(named)?.kind === "OBJECT") return "relationList";
+  return "scalar";
+}
+
+/** Why a field is deprecated, or null when it is not (GraphQL's default reason when none was given). */
+export function deprecationOf(field) {
+  return field.isDeprecated ? field.deprecationReason ?? "No longer supported" : null;
+}
+
+/** The keys of a `<Type>Filter` that combine conditions rather than name a field. */
+const FILTER_LOGIC = new Set(["and", "or", "not"]);
+
+/** Compact a `CapaIntrospection` answer: see GraphQLSchemaSummary in @capacms/sdk. */
+export function summarizeIntrospection(introspection) {
+  const types = new Map(introspection.__schema.types.map((type) => [type.name, type]));
+  const roots = types.get(introspection.__schema.queryType.name)?.fields ?? [];
+  const namespaceByType = new Map();
+  for (const type of introspection.__schema.types) {
+    if (type.kind !== "OBJECT") continue;
+    const namespace = MODEL_DESCRIPTION.exec((type.description ?? "").split("\n")[0])?.[1];
+    if (namespace) namespaceByType.set(type.name, namespace);
+  }
+  const modelTypes = new Set(namespaceByType.keys());
+
+  const models = [];
+  for (const [typeName, namespace] of namespaceByType) {
+    const list = roots.find((r) => namedType(r.type) === `${typeName}Connection` && r.args.some((a) => a.name === "first"));
+    const single = roots.find((r) => namedType(r.type) === typeName && r.args.some((a) => a.name === "id"));
+    if (!list || !single) continue;
+    const argType = (name) => namedType(list.args.find((a) => a.name === name)?.type ?? {});
+    const filterType = argType("filter");
+    const sortType = argType("sort");
+    const sortValues = (types.get(sortType)?.enumValues ?? []).map((v) => v.name);
+    const filterFields = new Map((types.get(filterType)?.inputFields ?? []).map((input) => [input.name, input]));
+    const operandsOf = (name) => {
+      const input = filterFields.get(name);
+      const operands = input ? (types.get(namedType(input.type))?.inputFields ?? []) : [];
+      return {
+        filterOps: operands.map((operand) => operand.name),
+        filterInputs: Object.fromEntries(operands.map((operand) => [operand.name, namedType(operand.type)])),
+      };
+    };
+    const type = types.get(typeName);
+    const fields = [];
+    for (const field of type.fields ?? []) {
+      const parsed = parseFieldDescription(field.description);
+      if (!parsed) continue;
+      fields.push({
+        name: field.name,
+        namespace: parsed.namespace,
+        capaType: parsed.capaType,
+        arrayType: parsed.arrayType,
+        graphqlType: printTypeRef(field.type),
+        kind: kindOf(field, types, modelTypes),
+        target: parsed.target,
+        sortable: sortValues.includes(`${field.name}_ASC`),
+        ...operandsOf(field.name),
+        deprecationReason: deprecationOf(field),
+      });
+    }
+    const fieldNames = new Set(fields.map((field) => field.name));
+    models.push({
+      namespace,
+      typeName,
+      description: type.description ?? "",
+      listField: list.name,
+      singleField: single.name,
+      filterType,
+      // The system fields the filter takes, as it declares them (spec 17, amendment 56 adds _tags).
+      systemFilters: [...filterFields.keys()]
+        .filter((name) => !FILTER_LOGIC.has(name) && !fieldNames.has(name))
+        .map((name) => ({ name, ...operandsOf(name) })),
+      sortType,
+      sortValues,
+      fields,
+      notExposed: notExposedFields(type.description),
+    });
+  }
+  models.sort((a, b) => (a.namespace < b.namespace ? -1 : a.namespace > b.namespace ? 1 : 0));
+  // The models the key reads that GraphQL leaves out (N1: their type names collide), which REST still serves.
+  const omitted = MODELS_NOT_EXPOSED.exec(types.get(introspection.__schema.queryType.name)?.description ?? "");
+  const restOnly = namespaceList(omitted);
+  return { version: introspection.version ?? "", models, restOnly };
+}
+
+/**
+ * `{ introspection, summary }` for this key, from the cache when it is fresh.
+ * A failed introspection throws: every schema tool needs it, and the error
+ * already carries the API's code and hint.
+ */
+export async function loadSchema(config, { now = Date.now() } = {}) {
+  const key = `${config.baseUrl}|${config.apiKey}|${config.apiVersion}`;
+  const hit = cache.get(key);
+  if (hit && now - hit.at < SCHEMA_TTL_MS) return hit.value;
+  let body;
+  try {
+    body = await apiNextPost(config, "/api/graphql", { query: INTROSPECTION_QUERY });
+  } catch (error) {
+    throw whenNotServed(config, error);
+  }
+  if (!body.data?.__schema) {
+    const first = body.errors?.[0];
+    throw new Error(
+      `Introspection returned no schema${first ? `: ${first.extensions?.code ?? "error"}: ${first.message}` : ""}. ` +
+        "Check that this deployment serves /api/graphql (CAPA_API_GRAPHQL is not off).",
+    );
+  }
+  const value = { introspection: body.data, summary: summarizeIntrospection(body.data) };
+  cache.set(key, { at: now, value });
+  return value;
+}

package/lib/graphql/sdl.mjs

@@ -0,0 +1,144 @@
+/**
+ * sdl.mjs — the key's schema as SDL text, whole or narrowed to some models.
+ *
+ * Printed from the introspection answer rather than fetched, because this
+ * package has no GraphQL library and `/api/schema.graphql` is not built. The
+ * output is the SDL a person would write, as graphql-js's printSchema writes
+ * it: every description kept (a type's, a field's, an argument's, an input
+ * field's and an enum value's; they carry each model's namespace, each
+ * field's Capa type and each argument's range), `@deprecated(reason:)` where
+ * a later Capa-Version phases a field, argument, input field or enum value
+ * out, built-in scalars and introspection types left out.
+ *
+ * NARROWED means: the Query root fields of the models asked for, their own
+ * types (the model, its connection, edge, filter, sort and relation filters),
+ * and every shared type those reach (PageInfo, Media, the scalar filters). A
+ * model that is only REFERENCED (Articles.author points at Authors) is named
+ * in `alsoReferenced` rather than printed, so narrowing stays narrow.
+ *
+ * COMPACT is the form a tool answer carries, where every character is the
+ * agent's context: input fields and enum values print without their
+ * descriptions (an operator's name says what it does, and a sort value's
+ * description only spells the name out), and a narrowed schema leaves out
+ * `me` and its KeyInfo, which describe the key rather than the models. Types,
+ * fields and arguments keep theirs: they carry each model's namespace, each
+ * field's label and Capa type, and each argument's range. The resource
+ * capa://graphql/schema.graphql prints the full form.
+ */
+import { namedType, printTypeRef } from "./schema.mjs";
+
+const BUILT_IN = new Set(["String", "Int", "Float", "Boolean", "ID"]);
+const ALWAYS_ROOTS = new Set(["entry", "version", "me"]);
+const MODEL_SUFFIXES = ["", "Connection", "Edge", "RelationConnection", "Filter", "Sort", "RelationFilter", "RelationListFilter"];
+
+function description(text, indent) {
+  if (!text) return [];
+  if (!text.includes("\n") && !text.includes('"')) return [`${indent}"${text}"`];
+  return [`${indent}"""`, ...text.split("\n").map((line) => `${indent}${line.replace(/"""/g, '\\"""')}`), `${indent}"""`];
+}
+
+/** ` @deprecated(reason: "...")` for a deprecated field, argument, input field or enum value, else nothing. */
+function deprecated(item) {
+  if (!item.isDeprecated) return "";
+  const reason = item.deprecationReason ?? "No longer supported";
+  return ` @deprecated(reason: ${JSON.stringify(reason)})`;
+}
+
+/** An input value as SDL writes it: `first: Int = 25`, and `@deprecated` when it is. */
+const inputValue = (value) =>
+  `${value.name}: ${printTypeRef(value.type)}${value.defaultValue != null ? ` = ${value.defaultValue}` : ""}${deprecated(value)}`;
+
+/** Arguments on one line, or one per line under their descriptions when any has one (as printSchema does). */
+function printArgs(args, indent) {
+  if (!args?.length) return "";
+  if (!args.some((a) => a.description)) return `(${args.map(inputValue).join(", ")})`;
+  const lines = args.flatMap((a) => [...description(a.description, `${indent}  `), `${indent}  ${inputValue(a)}`]);
+  return `(\n${lines.join("\n")}\n${indent})`;
+}
+
+function printType(type, rootFilter, compact = false) {
+  const lines = [...description(type.description, "")];
+  const itemDescription = (text, indent) => (compact ? [] : description(text, indent));
+  switch (type.kind) {
+    case "SCALAR":
+      lines.push(`scalar ${type.name}`);
+      break;
+    case "ENUM":
+      lines.push(`enum ${type.name} {`);
+      for (const v of type.enumValues) lines.push(...itemDescription(v.description, "  "), `  ${v.name}${deprecated(v)}`);
+      lines.push("}");
+      break;
+    case "INPUT_OBJECT":
+      lines.push(`input ${type.name} {`);
+      for (const f of type.inputFields) lines.push(...itemDescription(f.description, "  "), `  ${inputValue(f)}`);
+      lines.push("}");
+      break;
+    default: {
+      const keyword = type.kind === "INTERFACE" ? "interface" : "type";
+      const implemented = (type.interfaces ?? []).map((i) => i.name);
+      lines.push(`${keyword} ${type.name}${implemented.length ? ` implements ${implemented.join(" & ")}` : ""} {`);
+      for (const f of type.fields ?? []) {
+        if (rootFilter && !rootFilter(f)) continue;
+        lines.push(...description(f.description, "  "), `  ${f.name}${printArgs(f.args, "  ")}: ${printTypeRef(f.type)}${deprecated(f)}`);
+      }
+      lines.push("}");
+    }
+  }
+  return lines.join("\n");
+}
+
+/** Every type name one type refers to: field, argument, input and interface types. */
+function references(type) {
+  const refs = [];
+  for (const f of type.fields ?? []) {
+    refs.push(namedType(f.type));
+    for (const a of f.args ?? []) refs.push(namedType(a.type));
+  }
+  for (const f of type.inputFields ?? []) refs.push(namedType(f.type));
+  for (const i of type.interfaces ?? []) refs.push(i.name);
+  return refs;
+}
+
+/**
+ * `{ sdl, types, alsoReferenced }`. `models` (namespaces or type names) narrows
+ * the output, to no model at all when empty; unknown names are the caller's to
+ * check against the summary. `compact` prints the form a tool answer carries.
+ */
+export function printSDL(introspection, summary, models, { compact = false } = {}) {
+  const types = new Map(introspection.__schema.types.filter((t) => !t.name.startsWith("__")).map((t) => [t.name, t]));
+  const queryName = introspection.__schema.queryType.name;
+
+  if (models === undefined) {
+    const ordered = [queryName, ...[...types.keys()].filter((n) => n !== queryName && !BUILT_IN.has(n)).sort()];
+    return { sdl: ordered.map((n) => printType(types.get(n), undefined, compact)).join("\n\n"), types: ordered.length, alsoReferenced: [] };
+  }
+
+  const chosen = summary.models.filter((m) => models.includes(m.namespace) || models.includes(m.typeName));
+  const modelTypeNames = new Set(summary.models.map((m) => m.typeName));
+  const chosenTypeNames = new Set(chosen.map((m) => m.typeName));
+  const alwaysRoots = [...ALWAYS_ROOTS].filter((name) => !(compact && name === "me"));
+  const rootNames = new Set([...alwaysRoots, ...chosen.flatMap((m) => [m.listField, m.singleField])]);
+
+  const include = new Set([queryName]);
+  const alsoReferenced = new Set();
+  const queue = chosen.flatMap((m) => MODEL_SUFFIXES.map((suffix) => `${m.typeName}${suffix}`)).filter((n) => types.has(n));
+  const rootTypes = compact ? ["Entry"] : ["KeyInfo", "Entry"];
+  queue.push(...references(types.get(queryName)).filter((n) => rootTypes.includes(n)));
+  while (queue.length) {
+    const name = queue.shift();
+    if (include.has(name) || BUILT_IN.has(name) || !types.has(name)) continue;
+    const owner = [...modelTypeNames].find((t) => name === t || MODEL_SUFFIXES.some((s) => s && name === `${t}${s}`));
+    if (owner && !chosenTypeNames.has(owner)) {
+      alsoReferenced.add(owner);
+      continue;
+    }
+    include.add(name);
+    queue.push(...references(types.get(name)));
+  }
+
+  const ordered = [queryName, ...[...include].filter((n) => n !== queryName).sort()];
+  const sdl = ordered
+    .map((n) => (n === queryName ? printType(types.get(n), (f) => rootNames.has(f.name), compact) : printType(types.get(n), undefined, compact)))
+    .join("\n\n");
+  return { sdl, types: ordered.length, alsoReferenced: [...alsoReferenced].sort() };
+}

package/lib/graphql/served.mjs

@@ -0,0 +1,82 @@
+/**
+ * served.mjs — telling "this deployment serves no GraphQL" from "this
+ * document was refused".
+ *
+ * `CAPA_API_GRAPHQL=off` unregisters `/api/graphql`, and the path then answers
+ * what any path the API does not serve answers: a POST is `405
+ * mutations_not_enabled`, a GET `404 route_not_found`, both in the REST
+ * envelope, `{ error: { ... } }`. The GraphQL handler never answers in that
+ * envelope: its refusals, a real mutation's included, are `{ errors: [...] }`.
+ * So the envelope, not the code, says which of the two happened, and a query
+ * is never told it tried to write.
+ */
+import { CapaApiError } from "../client.mjs";
+
+/** Whether `error`, from a request to `/api/graphql`, means the path is not served here. */
+export function graphqlNotServed(error) {
+  if (!(error instanceof CapaApiError) || (error.status !== 404 && error.status !== 405)) return false;
+  let body;
+  try {
+    body = JSON.parse(error.body);
+  } catch {
+    return false;
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body.errors)) return false;
+  return ["mutations_not_enabled", "route_not_found"].includes(body.error?.code);
+}
+
+/**
+ * The error every GraphQL tool answers on such a deployment. It names the
+ * switch and what can still read content: over REST with the same key, and
+ * for a legacy `pk_`/`sk_` key the legacy content tools it is also offered.
+ *
+ * Where `GET /api/me` found no `/api/` surface at all at startup
+ * (`config.apiMissing`), GraphQL being off is not the likely cause: the
+ * address is. That error names CAPA_API_URL instead.
+ */
+export class GraphQLNotServed extends Error {
+  constructor(config, error) {
+    super(config.apiMissing ? noApiAt(config, error) : graphqlOff(config, error));
+    this.name = "GraphQLNotServed";
+  }
+}
+
+function graphqlOff(config, error) {
+  return (
+    `This deployment does not serve GraphQL: POST /api/graphql answered ${error.status} ${error.code} as a path it does not serve, ` +
+    "which is what CAPA_API_GRAPHQL=off does. No GraphQL tool can answer until it is switched back on.\n" +
+    "Next: tell the person running Capa that GraphQL is off here. " +
+    (config.family === "legacy" ? "To read entries meanwhile, capa_list_content and capa_get_content use the legacy API. " : "") +
+    "Code can read the same content over REST with this key: GET /api/entries/<model>."
+  );
+}
+
+function noApiAt(config, error) {
+  return (
+    `${printable(config.baseUrl)} serves no /api/ route: GET /api/me answered 404 when this server started, and POST /api/graphql answered ${error.status}${error.code ? ` ${error.code}` : ""}. ` +
+    "Either CAPA_API_URL is not the Capa API's address, or this deployment does not serve /api/.\n" +
+    "Next: tell the person running this server to check that CAPA_API_URL is the API's address with no route after it, " +
+    "e.g. https://api.capacms.com, and restart it; if it is, /api/ is off on this deployment."
+  );
+}
+
+/** CAPA_API_URL as it may be printed: never a user name or password written into it. */
+function printable(baseUrl) {
+  try {
+    const url = new URL(baseUrl);
+    return `${url.origin}${url.pathname === "/" ? "" : url.pathname}`;
+  } catch {
+    return "CAPA_API_URL";
+  }
+}
+
+/** Whether `error`, from a request to `/api/graphql`, means no GraphQL tool can answer at this address. */
+function notAnswerable(config, error) {
+  if (graphqlNotServed(error)) return true;
+  return Boolean(config.apiMissing) && error instanceof CapaApiError && (error.status === 404 || error.status === 405);
+}
+
+/** `error` as `GraphQLNotServed` when no GraphQL tool can answer at this address, else unchanged. */
+export function whenNotServed(config, error) {
+  return notAnswerable(config, error) ? new GraphQLNotServed(config, error) : error;
+}