@capacms/mcp 0.2.0

package/lib/error-guide.mjs

@@ -0,0 +1,750 @@
+/**
+ * error-guide.mjs — what a Capa API error means and what to do next.
+ *
+ * Every `/api/` error carries a `code` and usually a `hint` written in the
+ * deployment's own values. This guide adds the two things an agent still has
+ * to work out: what the code means in general, and which tool to call next.
+ * It is offline on purpose, so an agent can explain an error it saw anywhere
+ * (a site's logs, a user's paste, another tool) without a key.
+ *
+ * The codes are the REST envelope's (apps/api/src/api-next/errors.ts) and the
+ * GraphQL table of the G plan (1.4).
+ */
+import { TIMEOUT_NEXT, UNREACHABLE_NEXT } from "./client.mjs";
+import { MAX_RELATION_DEPTH, RELATION_DEPTH_RULE } from "./graphql/build.mjs";
+
+const GUIDE = {
+  missing_key: {
+    meaning: "The request carried no x-api-key header.",
+    fix: "Send the key in x-api-key. For this server, set CAPA_KEY.",
+    next: null,
+  },
+  invalid_key: {
+    meaning: "The key is unknown, revoked or expired.",
+    fix: "Use a current key from Developers > Keys in the Capa admin.",
+    next: null,
+  },
+  subscription_required: {
+    meaning: "The project's plan does not include API access right now.",
+    fix: "The project owner has to renew or upgrade the plan. Nothing in the request can change this.",
+    next: null,
+  },
+  scope_missing: {
+    meaning: "The key is valid but lacks the scope this route needs.",
+    fix: "The hint names the scope. Use a key that holds it, or ask for one.",
+    next: "capa_graphql_schema",
+  },
+  origin_refused: {
+    meaning: "The key is restricted to other origins than the one this request came from.",
+    fix: "Call from an allowed origin, or use a key without an origin list for server-side reads.",
+    next: null,
+  },
+  edge_only: {
+    meaning: "The request reached the origin directly; this deployment only serves /api/ through its CDN.",
+    fix: "Use the public API host, not the origin's address.",
+    next: null,
+  },
+  invalid_version: {
+    meaning: "Capa-Version names a date this deployment does not serve.",
+    fix: "Use one of the dates in the hint, or set CAPA_API_VERSION to one.",
+    next: null,
+  },
+  contract_not_found: {
+    meaning: "Capa-Contract names a contract this project does not have. Only contract 1 exists today.",
+    fix: "Drop the Capa-Contract header or send 1.",
+    next: null,
+  },
+  model_not_found: {
+    meaning: "The model in the path does not exist, or this key cannot read it.",
+    fix: "Use a namespace from the model list.",
+    next: "capa_graphql_schema",
+  },
+  entry_not_found: {
+    meaning: "No entry with that id is visible to this key. A production key sees published entries only.",
+    fix: "Check the id, or use a development key to read drafts.",
+    next: "capa_graphql_query",
+  },
+  unknown_field: {
+    meaning: "A select, filter or sort names a field the model does not have.",
+    fix: "Use the field names the hint lists.",
+    next: "capa_graphql_schema",
+  },
+  invalid_filter_value: {
+    meaning: "A filter value does not fit the field's type, for example text for a number or a non-ISO date.",
+    fix: "Send numbers for number fields, true or false for true_false fields, and ISO 8601 dates.",
+    next: "capa_graphql_schema",
+  },
+  invalid_operator: {
+    meaning: "The filter or sort uses an operator this field type does not support.",
+    fix: "Use one of the operators the hint lists for that field.",
+    next: "capa_graphql_schema",
+  },
+  invalid_cursor: {
+    meaning: "The after or before cursor is malformed, was minted for another sort, or belongs to another parent entry.",
+    fix: "Pass a cursor from a page of the same query, unchanged, with the same sort: its endCursor as after, or its startCursor as before.",
+    next: "capa_graphql_query",
+  },
+  invalid_select: {
+    meaning: "The selection cannot be planned, for example a relation modifier where it does not apply.",
+    fix: `Follow the hint; nest ${RELATION_DEPTH_RULE}.`,
+    next: "capa_graphql_build",
+  },
+  invalid_parameter: {
+    meaning: "A request parameter is missing or out of range: first outside 1 to 200, more than 3 sort values, a non-UUID id, bad JSON in variables.",
+    fix: "Change the argument the message names to a value the hint allows.",
+    next: "capa_graphql_build",
+  },
+  query_too_complex: {
+    meaning:
+      "The query is over a budget, and the message says which, what it measured and the limit. The budgets: 5,000 entries " +
+      "(each totalCount and each filter or sort through a relation costs 500 more), " +
+      `10 root fields, 25 lists, 1,000 fields, depth 8, 32 KB documents, entries ${MAX_RELATION_DEPTH + 1} levels deep (${MAX_RELATION_DEPTH} relations below the root), ` +
+      "12 relations expanded per root field, 200 values per list operator, 50 filter conditions nested at most 8 deep.",
+    fix: "Ask for fewer fields, a smaller first, or fewer nested relations; split one query into several.",
+    next: "capa_graphql_build",
+  },
+  count_unavailable: {
+    meaning: "totalCount could not be computed cheaply for this filter (a relation filter matching over 50,000 entries).",
+    fix: "Drop totalCount, or narrow the filter.",
+    next: "capa_graphql_query",
+  },
+  query_timeout: {
+    meaning: "The database stopped the query at the statement timeout. Later root fields were not run.",
+    fix: "Ask for fewer entries or fewer nested relations, or filter on fewer relation hops.",
+    next: "capa_graphql_build",
+  },
+  graphql_parse_failed: {
+    meaning: "The GraphQL document has a syntax error.",
+    fix: "Fix the text at the line and column given. Let capa_graphql_build write the document instead.",
+    next: "capa_graphql_build",
+  },
+  graphql_validation_failed: {
+    meaning: "The document parses but asks for something the key's schema does not have: a field, an argument, a type or a missing variable.",
+    fix: "Use the names the message suggests; the schema only holds models this key can read.",
+    next: "capa_graphql_schema",
+  },
+  persisted_query_not_found: {
+    meaning: "No document is stored for that hash. Only a development key stores one; a production key never does.",
+    fix:
+      "Send the query text beside the same hash: it runs either way, and the SDK and Apollo do this for you. " +
+      "To stop the miss, register the documents at build time with a development key (capa persist).",
+    next: null,
+  },
+  persisted_query_hash_mismatch: {
+    meaning: "The sha256 sent does not match the query text sent.",
+    fix: "Hash the exact query string, UTF-8, lowercase hex.",
+    next: null,
+  },
+  mutations_not_enabled: {
+    meaning:
+      "The request tried to write. Capa's GraphQL API reads only, and /api/ writes are not enabled here. A POST to a path " +
+      "the API does not serve gets the same answer, so a query sent to /api/graphql where GraphQL is switched off " +
+      "(CAPA_API_GRAPHQL=off) gets it too, without a hint.",
+    // The GraphQL handler's own refusal of a mutation carries a hint; the
+    // answer of a path the API does not serve has none. Only without one can
+    // the request have been a query sent where GraphQL is off.
+    fix: (error) =>
+      "Send a query instead; nothing here can write. Content is edited in the Capa admin." +
+      (error.hint
+        ? ""
+        : " If it was already a query, GraphQL is off on this deployment: read over REST instead, GET /api/entries/<model>."),
+    next: null,
+  },
+  route_not_found: {
+    meaning:
+      "This deployment does not serve that path. GraphQL may be switched off (CAPA_API_GRAPHQL=off), pages may be off " +
+      "(CAPA_SITE_PREVIEW, off by default), or the path is mistyped.",
+    fix: "Check the path; use /api/entries for REST reads if GraphQL is off. Pages cannot be read where they are off.",
+    next: "capa_graphql_schema",
+  },
+  page_not_found: {
+    meaning: "No model declares that page and no read has reported it.",
+    fix: "Use a page from the page list.",
+    next: "capa_list_pages",
+  },
+  preview_token_invalid: {
+    meaning: "The preview token is forged, mangled or for another project.",
+    fix: "Open a fresh preview link from the Capa editor.",
+    next: null,
+  },
+  preview_token_expired: {
+    meaning: "The preview token was real but has expired.",
+    fix: "Open a fresh preview link from the Capa editor.",
+    next: null,
+  },
+  rate_limit_exceeded: {
+    meaning:
+      "Capa refused the request to protect the service, for one of two reasons the message names: too many reads running at " +
+      "once (the API's read gate, per client, per key or per project), or too many uncached requests from this key in a " +
+      "minute (the CDN's limit).",
+    // The API's read gate says "running at once" (read-gate.ts); the CDN's
+    // limiter counts origin requests "in a minute" (cutover/HAND_CHANGES.md).
+    fix: (error) => {
+      const message = String(error.message ?? "");
+      if (/across its keys/.test(message)) {
+        return "Send fewer reads at once across this project's keys, a few at a time rather than all together, then retry after the Retry-After seconds.";
+      }
+      if (/running at once/.test(message)) {
+        return "Send fewer reads at once with this key, one after another or a few at a time, then retry after the Retry-After seconds.";
+      }
+      if (/in a minute/.test(message)) {
+        return "Wait for the Retry-After seconds, then retry; cache GET responses where you can, since cached reads are not counted.";
+      }
+      return "Send fewer reads at once and retry after the Retry-After seconds; if the message counts requests in a minute, also cache GET responses, since cached reads are not counted.";
+    },
+    next: null,
+  },
+  internal: {
+    meaning: "Capa hit an unexpected error. The body has no details, by design.",
+    fix: "Retry once. If it repeats, report the requestId to Capa support.",
+    next: null,
+  },
+};
+
+export const KNOWN_CODES = Object.keys(GUIDE);
+
+/**
+ * Every budget refusal states what the request measured and the limit it
+ * passed (spec 17, amendments 32 and 44), on GraphQL and on REST:
+ * "bins: could read 40,200 entries, over the limit of 5,000.". GraphQL writes
+ * counts with thousands separators and REST's plain. Each row reads one kind
+ * of refusal and turns it into the fix for THAT budget, and the tool that
+ * helps: a smaller first is a job for capa_graphql_build, a document with too
+ * many root fields has to be split and run piece by piece with
+ * capa_graphql_query.
+ *
+ * `measure` names the budget. Named groups: `root` (the root field, when the
+ * message names one), `value` (what was measured), `atLeast` (the count
+ * stopped at the first item past the limit) and `limit`. A fix is handed each
+ * count as the API wrote it (`value`, `limit`, `measured`: "at least 1,001"),
+ * so an agent reads the numbers of the message it was sent, and the numbers
+ * (`valueCount`, `limitCount`) for arithmetic.
+ */
+/** A count as the API writes it, with or without thousands separators: `40,200` or `40200`. */
+const count = (text) => Number(String(text).replace(/,/g, ""));
+
+const BUDGETS = [
+  {
+    measure: "entries",
+    pattern: /^(?<root>[_A-Za-z][_0-9A-Za-z]*): could read (?<value>[\d,]+) entries, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `${b.root} could read ${b.value} entries, over the limit of ${b.limit}. Lower first on ${b.root} or on the relation lists inside it: every entry counts once, and every item of a relation list inside it once more.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "entries",
+    pattern: /^This document could read (?<value>[\d,]+) entries, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `The root fields together could read ${b.value} entries, over the limit of ${b.limit}. Lower first on them, or run them as separate queries.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "entries",
+    pattern:
+      /^This document costs (?<value>[\d,]+) entries, over the limit of (?<limit>[\d,]+): (?<returns>[\d,]+) it could return, plus (?<scans>\d+) (?:count|counts)/,
+    fix: (b) =>
+      `The query costs ${b.value} entries, over the limit of ${b.limit}: ${b.returns} it could return, plus 500 for each of its ${b.scans} totalCount fields and filters or sorts through a relation. ` +
+      "Drop totalCount, filter and sort on the model's own fields, or split the query.",
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "entries",
+    pattern: /^(?:(?<root>[_A-Za-z][_0-9A-Za-z]*): )?This request could return (?<value>[\d,]+) (?:entries|nodes), over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `The read could return ${b.value} entries, over the limit of ${b.limit}. Lower first on the list or on its relation lists.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "entries",
+    pattern: /^(?:(?<root>[_A-Za-z][_0-9A-Za-z]*): )?This request read (?<atLeast>at least )?(?<value>[\d,]+) (?:entries|nodes), over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `The read passed ${b.limit} entries before it finished. Lower first on the list or on its relation lists.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "sortedEntries",
+    pattern: /^(?:(?<root>[_A-Za-z][_0-9A-Za-z]*): )?(?<relation>\S+) references (?<value>[\d,]+) entries to order, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `Sorting ${b.relation} means ordering every entry it points at, ${b.value} here, over the limit of ${b.limit}. Drop its sort, or read fewer entries at a time (a smaller first).`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "rootFields",
+    pattern: /^This document has (?<value>[\d,]+) entry root fields, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `It has ${b.value} root fields and the limit is ${b.limit}. Split it into queries of at most ${b.limit} root fields and run each.`,
+    next: "capa_graphql_query",
+  },
+  {
+    measure: "connections",
+    pattern: /^This document selects (?<atLeast>at least )?(?<value>[\d,]+) connections, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `It selects ${b.measured} lists (list roots and relation lists) and the limit is ${b.limit}. Split it into several queries.`,
+    next: "capa_graphql_query",
+  },
+  {
+    measure: "entryDepth",
+    pattern: /^(?<root>[_A-Za-z][_0-9A-Za-z]*): reads related entries (?<value>[\d,]+) levels deep, the root entry counted, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `${b.root} reads entries ${b.value} levels deep and the limit is ${b.limit}, its own entries counted: nest at most ${b.limitCount - 1} relations below them. Read deeper entries with a second query by id.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "entryDepth",
+    pattern: /^(?:(?<root>[_A-Za-z][_0-9A-Za-z]*): )?select is (?<atLeast>at least )?(?<value>[\d,]+) levels deep, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `select nests ${b.measured} levels and the limit is ${b.limit}, the entry itself counted: nest at most ${b.limitCount - 1} relations. Read deeper entries with a second request by id.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "expansions",
+    pattern: /^(?<root>[_A-Za-z][_0-9A-Za-z]*): expands (?<value>[\d,]+) relations, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `${b.root} expands ${b.value} relations and the limit is ${b.limit}. Select the others without fields, for their ids, or read them with a second query.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "expansions",
+    pattern: /^(?:(?<root>[_A-Za-z][_0-9A-Za-z]*): )?select expands (?<atLeast>at least )?(?<value>[\d,]+) relations, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `select expands ${b.measured} relations and the limit is ${b.limit}. Name the others without parentheses, for their ids.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "listValues",
+    pattern: /^(?:(?<root>[_A-Za-z][_0-9A-Za-z]*): )?(?<field>.+) with (?<operator>\w+) was sent (?<value>[\d,]+) values, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `${b.operator} on ${b.field} was sent ${b.value} values and takes at most ${b.limit}. Split the values across queries.`,
+    next: "capa_graphql_query",
+  },
+  {
+    measure: "filterDepth",
+    pattern:
+      /^(?:(?<root>[_A-Za-z][_0-9A-Za-z]*): |Variable "\$[_A-Za-z][_0-9A-Za-z]*": )?(?:filter|where) nests (?<atLeast>at least )?(?<value>[\d,]+) levels deep, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `The filter nests ${b.measured} levels of and, or and not, and the limit is ${b.limit}. Flatten it: keys in one object already all have to match.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "filterConditions",
+    pattern: /^(?:(?<root>[_A-Za-z][_0-9A-Za-z]*): )?(?:filter|where) has (?<atLeast>at least )?(?<value>[\d,]+) conditions, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `The filter has ${b.measured} conditions and the limit is ${b.limit}. Merge them: in, nin, hasAny and hasAll take many values in one condition.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "documentBytes",
+    pattern: /^This document is (?<value>[\d,]+) bytes, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `It is ${b.value} bytes and the limit is ${b.limit}. Send only the operation you run, without unused fragments; capa_graphql_build writes a compact one.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "fields",
+    pattern: /^This document selects (?<atLeast>at least )?(?<value>[\d,]+) fields, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `It selects ${b.measured} fields, fragments expanded, and the limit is ${b.limit}. Select fewer fields.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "fields",
+    pattern: /^This document has (?<value>[\d,]+) fields across its operations and fragments, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `Every operation and fragment in a document counts: ${b.value} fields, and the limit is ${b.limit}. Send only the operation you run.`,
+    next: "capa_graphql_query",
+  },
+  {
+    measure: "depth",
+    pattern: /^This document is (?<atLeast>at least )?(?<value>[\d,]+) levels deep, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `It nests ${b.measured} levels and the limit is ${b.limit} (edges, node, nodes and pageInfo count zero). Nest fewer relations.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "depth",
+    pattern: /^This document nests brackets (?<value>[\d,]+) levels deep, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `It nests brackets ${b.value} levels deep and the limit is ${b.limit}, far deeper than any query the API can answer. Write the selection and the filter out flat; capa_graphql_build writes one.`,
+    next: "capa_graphql_build",
+  },
+  {
+    measure: "introspectionDepth",
+    pattern: /^This introspection query is (?<atLeast>at least )?(?<value>[\d,]+) levels deep, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `It nests ${b.measured} levels and introspection allows ${b.limit}, which the standard introspection query fits. capa_graphql_schema reads the schema for you.`,
+    next: "capa_graphql_schema",
+  },
+  {
+    measure: "sortKeys",
+    pattern: /^(?<root>[_A-Za-z][_0-9A-Za-z]*): sort has (?<value>[\d,]+) keys, over the limit of (?<limit>[\d,]+)\./,
+    fix: (b) => `${b.root} sorts by ${b.value} keys and takes at most ${b.limit}. Keep the ones that decide the order.`,
+    next: "capa_graphql_build",
+    code: "invalid_parameter",
+  },
+];
+
+/**
+ * The budget a refusal's message states, with its numbers and the fix and
+ * tool for it, or null for any other message. `measured` and `limit` are
+ * numbers an agent can compare; `written` and the fix quote them as the
+ * message wrote them.
+ *
+ *   budgetOf("bins: could read 40,200 entries, over the limit of 5,000.")
+ *   // { root: "bins", measure: "entries", measured: "40200", limit: 5000, written: { measured: "40,200", limit: "5,000" },
+ *   //   fix: "bins could read 40,200 entries, over the limit of 5,000. ...", next: "capa_graphql_build", code: "query_too_complex" }
+ */
+export function budgetOf(message) {
+  for (const budget of BUDGETS) {
+    const match = budget.pattern.exec(String(message ?? "").trim());
+    if (!match) continue;
+    const { atLeast, value, limit } = match.groups;
+    const valueCount = count(value);
+    const limitCount = count(limit);
+    const written = { ...match.groups, measured: `${atLeast ? "at least " : ""}${value}`, valueCount, limitCount };
+    const out = {
+      measure: budget.measure,
+      measured: `${atLeast ? "at least " : ""}${valueCount}`,
+      limit: limitCount,
+      written: { measured: written.measured, limit },
+      fix: budget.fix(written),
+      next: budget.next,
+      code: budget.code ?? "query_too_complex",
+    };
+    return match.groups.root ? { root: match.groups.root, ...out } : out;
+  }
+  return null;
+}
+
+/**
+ * The sentence of an entries-budget hint that names the change, as the API
+ * wrote it: "Pass coauthors(first: 24) to fit, or lower first elsewhere." or
+ * "No one first fits. Select fewer relation lists, or split the document into
+ * several requests." (apps/api node-budget.ts). Null when the hint has none.
+ * `field`, `argument` and `value` are the change the first form names.
+ */
+export function hintedFix(hint) {
+  const match =
+    /(Pass (?<field>[_A-Za-z][_0-9A-Za-z]*)\((?<argument>first|last): (?<value>\d[\d,]*)\) to fit[^.]*\.|No one first fits\.[^.]*\.)/.exec(String(hint ?? ""));
+  if (!match) return null;
+  const { field, argument, value } = match.groups;
+  return { sentence: match[1], ...(field ? { field, argument, value } : {}) };
+}
+
+/**
+ * The model type a derived type belongs to (N2): `ArticlesConnection`,
+ * `ArticlesEdge`, `AuthorsRelationConnection` and `ArticlesSort` all name
+ * their model's type, which capa_graphql_schema takes as `model`.
+ */
+const DERIVED = /^(.+?)(RelationConnection|Connection|Edge|Sort|RelationListFilter|RelationFilter|Filter)$/;
+const modelTypeOf = (type) => DERIVED.exec(type)?.[1] ?? type;
+
+/** What GraphQL calls the arguments an agent writes with REST's names. */
+const REST_ARGUMENTS = {
+  where: "filter",
+  limit: "first",
+  orderBy: "sort",
+  order: "sort",
+  offset: "after (a cursor from pageInfo.endCursor)",
+  skip: "after (a cursor from pageInfo.endCursor)",
+  page: "after (a cursor from pageInfo.endCursor)",
+};
+
+/** The fields of the shared types, which are the same on every schema (G plan N7, N10). */
+const SHARED_FIELDS = {
+  PageInfo: "hasNextPage, hasPreviousPage, startCursor and endCursor",
+  Media: "id, url, alt, type, width and height",
+};
+
+/** A field asked of a type that does not have it: where it goes instead, and which tool shows the names. */
+function misplacedField(field, type, suggested) {
+  if (/Connection$/.test(type)) {
+    return {
+      fix: `${type} is a list, not an entry: select ${field} inside nodes { ... }, e.g. { nodes { id ${field} } pageInfo { hasNextPage endCursor } }.`,
+      next: "capa_graphql_build",
+    };
+  }
+  if (/Edge$/.test(type)) return { fix: `${type} holds cursor and node: select ${field} inside node { ... }.`, next: "capa_graphql_build" };
+  // Quoted, as the message quotes it: the name is the caller's own, never one the schema offered.
+  if (type === "Query") {
+    return {
+      fix: `"${field}" is not a root field for this key. Each model it can read has a list root and a single root, and capa_graphql_schema lists them.`,
+      next: "capa_graphql_schema",
+    };
+  }
+  if (SHARED_FIELDS[type]) return { fix: `${type} has ${SHARED_FIELDS[type]}.`, next: null };
+  if (suggested) return { fix: `Field ${field} is not on ${type}: use the name the message suggests.`, next: "capa_graphql_query" };
+  return { fix: `Field ${field} is not on ${type}. Call capa_graphql_schema with model "${type}" for its fields.`, next: "capa_graphql_schema" };
+}
+
+/** The operator a bare filter value stands for, by the filter type that refused it. */
+const operatorOf = (filterType) => (/ListFilter$/.test(filterType) ? "has" : filterType === "MediaFilter" ? "id" : "eq");
+
+/** The place and the condition a filter hint gives: "and takes a list of conditions, such as and: [{ title: { eq: "text" } }]." */
+const CONDITION_EXAMPLE = /(\S+) takes a (?:list|set) of conditions, such as (.+?[}\]])\.(?:\s|$)/;
+
+/** The operation names a refusal's hint lists: "Operations in this document: A, B." */
+const operationsIn = (hint) => /Operations in this document: ([^.]+)\./.exec(String(hint ?? ""))?.[1] ?? null;
+
+/**
+ * Patterns in graphql-js validation and coercion messages, and in the API's
+ * own refusals of a document, each with the concrete fix and the tool for it.
+ * The names they quote are the message's own, or its hint's, which the API
+ * already sends to this key.
+ */
+const VALIDATION_PATTERNS = [
+  [
+    /operations, so operationName is required\.|has no operation named /,
+    (_m, error) => {
+      const names = operationsIn(error.hint);
+      return {
+        fix: names
+          ? `Pass operationName with the one to run: ${names}.`
+          : "Pass operationName with the name of the operation to run, or send one operation per request.",
+        next: "capa_graphql_query",
+      };
+    },
+  ],
+  [/Cannot query field "([^"]+)" on type "([^"]+)"\.( Did you mean)?/, (m) => misplacedField(m[1], m[2], Boolean(m[3]))],
+  [
+    /Unknown argument "([^"]+)" on field "(?:[^".]+\.)?([^"]+)"/,
+    (m) => ({
+      fix:
+        `${m[2]} takes no argument ${m[1]}.${REST_ARGUMENTS[m[1]] ? ` GraphQL calls it ${REST_ARGUMENTS[m[1]]}.` : ""} ` +
+        "A list root takes first, after, before, sort and filter; a relation list first, after and sort; a single root id.",
+      next: "capa_graphql_build",
+    }),
+  ],
+  [/Variable "\$([^"]+)" of required type "([^"]+)" was not provided/, (m) => ({ fix: `Pass variables.${m[1]} (${m[2]}).`, next: "capa_graphql_query" })],
+  [
+    /got invalid value (.+?) at "(?:[^"]*\.)?([^".]+)"; Expected type "([^"]+Filter)" to be an object/,
+    (m) => ({
+      fix: `${m[2]} takes operators, not a bare value: write { "${m[2]}": { "${operatorOf(m[3])}": ${m[1]} } }.`,
+      next: "capa_graphql_build",
+    }),
+  ],
+  [
+    /Expected value of type "([^"!]+Filter)!?", found ([^;]+?)\.(?:$|\s)/,
+    (m, error) => {
+      // The API's hint gives a real condition for the place (spec 17, amendment 144): a model's filter holds
+      // conditions on fields, and and or a list of them, so an operator such as eq would be refused again.
+      const shown = CONDITION_EXAMPLE.exec(error.hint ?? "");
+      if (shown) return { fix: `Write ${shown[1]} as ${shown[2]}.`, next: "capa_graphql_build" };
+      // Only an item of and or or is a filter that cannot be null, so a null there is an item to drop or fill.
+      if (m[2] === "null" && m[0].includes("!")) {
+        return { fix: `${m[1]}! is an item of and or or: remove the null, or write a condition in its place.`, next: "capa_graphql_build" };
+      }
+      return { fix: `${m[1]} takes an object of operators, e.g. { ${operatorOf(m[1])}: ${m[2]} }.`, next: "capa_graphql_build" };
+    },
+  ],
+  [
+    // A part of the filter that is not the shape it takes, named by its place (amendment 144): "filter.and[1].not is null."
+    /\b((?:filter|where)(?:\.\S+)?) is (?:null|not a JSON object|not an array|empty)\./,
+    (m) => ({
+      fix: /\.(?:and|or)$/.test(m[1])
+        ? `${m[1]} takes a list of conditions, [{ <field>: { <operator>: <value> } }], or leave it out.`
+        : `${m[1]} takes one condition, { <field>: { <operator>: <value> } }, or leave it out.`,
+      next: "capa_graphql_build",
+    }),
+  ],
+  [
+    / with (\w+) expects at least one value\./,
+    (m) => ({ fix: `${m[1]} needs at least one value: send one, or leave the condition out when the list is empty.`, next: "capa_graphql_build" }),
+  ],
+  [
+    /Field "([^"]+)" of type "([^"]+)" must have a selection of subfields/,
+    (m) => ({ fix: `${m[1]} is an object (${m[2]}); select fields inside it, at least { id }.`, next: "capa_graphql_query" }),
+  ],
+  [
+    /Value "([^"]+)" does not exist in "([^"]+)" enum/,
+    (m) => ({ fix: `${m[1]} is not a value of ${m[2]}. Call capa_graphql_schema with model "${modelTypeOf(m[2])}" for its sort values.`, next: "capa_graphql_schema" }),
+  ],
+];
+
+function asObject(value) {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Why a request never reached Capa, read from what `fetch`, undici, Node or
+ * this server wrote about it: a system code, "timeout", or "fetch failed" for
+ * a failure that names no cause. Null for anything else.
+ */
+function transportOf(text) {
+  const value = String(text ?? "");
+  if (/did not answer .* within|\bTimeoutError\b|aborted due to timeout|\bUND_ERR_(?:CONNECT|HEADERS|BODY)_TIMEOUT\b/.test(value)) return "timeout";
+  const code = /\b(ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN|EHOSTUNREACH|ENETUNREACH|UND_ERR_SOCKET)\b/.exec(value)?.[1];
+  if (code) return code === "ETIMEDOUT" ? "timeout" : code;
+  return /\bfetch failed\b|Could not reach Capa|socket hang up/.test(value) ? "fetch failed" : null;
+}
+
+/** An HTTP status a text states as one ("HTTP 404", "status 400", "Capa API 401"), never a number that is part of an address. */
+const statusIn = (text) => /\b(?:HTTP|status|Capa API)[:\s]\s*([1-5]\d\d)\b/i.exec(String(text ?? ""))?.[1];
+
+/** The name Node prints before a thrown error's message: `CapaError: `, `TypeError [ERR_X]: `. */
+const ERROR_NAME = /^\s*(?:Uncaught )?(?:[A-Z][A-Za-z]*)?Error(?: \[[^\]]+\])?: /;
+
+/** A snake_case word: what every Capa error code is, and what a path such as node_modules or task_queues is too. */
+const SNAKE = /\b[a-z]+(?:_[a-z]+)+\b/g;
+
+/**
+ * A field `util.inspect` prints on a line of its own, `  code: 'query_too_complex',`,
+ * as the SDK's CapaError prints in a server log: the string in whichever quotes
+ * inspect chose, or a number. Its first line, since a CapaError's own fields
+ * come before the `graphqlErrors` it holds.
+ */
+function inspectedField(text, name) {
+  const match = new RegExp(`^ {2}${name}: (?:(['"\`])((?:\\\\.|(?!\\1).)*)\\1|(\\d+)),?$`, "m").exec(text);
+  if (!match) return undefined;
+  if (match[3] !== undefined) return Number(match[3]);
+  return match[2].replace(/\\(.)/g, (_all, char) => (char === "n" ? "\n" : char));
+}
+
+/**
+ * Messages whose wording names their code: graphql-js's validation messages,
+ * which the API sends as `graphql_validation_failed`, and the API's own for a
+ * cursor. How `String(error)` of the SDK's CapaError, which prints the message
+ * alone, still names its code. A budget's wording is read by `budgetOf`.
+ */
+const WORDED_CODES = [
+  [/Cannot query field "|Unknown argument "|must have a selection of subfields|does not exist in "[^"]+" enum|Expected value of type "/, "graphql_validation_failed"],
+  [/\bthis cursor is not valid\b/, "invalid_cursor"],
+  [/\b(?:filter|where)(?:\.\S+)? is (?:null|not a JSON object|not an array|empty)\.| with \w+ expects at least one value\./, "invalid_filter_value"],
+];
+
+/**
+ * One error from pasted text: plain words, a code and message, or a thrown
+ * error as Node prints it, `String(error)`, `error.stack` or `util.inspect`.
+ * The code is the one inspect printed, else the first word of the text that is
+ * a code this guide knows (never `task_queues` from a stack line), else what a
+ * budget refusal's or a validation message's own wording says.
+ */
+function textError(text) {
+  const printed = ERROR_NAME.test(text);
+  const message = printed ? text.split("\n")[0].replace(ERROR_NAME, "") : text;
+  const inspected = inspectedField(text, "code");
+  const known =
+    (typeof inspected === "string" && /^[a-z]+(?:_[a-z]+)+$/.test(inspected) ? inspected : undefined) ??
+    message.match(SNAKE)?.find((word) => GUIDE[word]) ??
+    text.match(SNAKE)?.find((word) => GUIDE[word]) ??
+    budgetOf(message)?.code ??
+    WORDED_CODES.find(([wording]) => wording.test(message))?.[1];
+  const transport = known ? null : transportOf(text);
+  if (transport) return { transport, message: text };
+  const status = inspectedField(text, "status") ?? Number(statusIn(text) ?? NaN);
+  const hint = inspectedField(text, "hint");
+  const param = inspectedField(text, "param");
+  return {
+    code: known,
+    message,
+    ...(typeof hint === "string" ? { hint } : {}),
+    ...(typeof param === "string" ? { param } : {}),
+    status: Number.isInteger(status) ? status : undefined,
+  };
+}
+
+/** Every error item in whatever shape it arrived: GraphQL, REST, a tool's output or plain text. */
+export function normalizeErrors(input) {
+  const value = asObject(input);
+  if (typeof value === "string") return [textError(value)];
+  if (Array.isArray(value)) return value.flatMap(normalizeErrors);
+  if (!value || typeof value !== "object") return [];
+  if (Array.isArray(value.errors)) return value.errors.flatMap(normalizeErrors);
+  if (value.error && typeof value.error === "object") return normalizeErrors(value.error);
+  const ext = value.extensions ?? {};
+  const transport = value.code ?? ext.code ? null : transportOf(`${value.message ?? ""} ${value.cause?.code ?? value.cause?.message ?? ""}`);
+  if (transport) return [{ transport, message: value.message }];
+  return [
+    {
+      code: value.code ?? ext.code,
+      message: value.message,
+      hint: value.hint ?? ext.hint,
+      param: value.param ?? ext.param,
+      path: value.path,
+      status: value.status,
+    },
+  ];
+}
+
+/**
+ * The fix and the tool for one error: a budget refusal's own numbers, else
+ * the concrete fix a validation or coercion message spells out, else the
+ * code's general fix. Null for a message and code this guide does not know.
+ * The same advice reaches a tool's Next line and capa_explain_error.
+ */
+function adviceFor(error) {
+  const budget = budgetOf(error.message);
+  if (budget) {
+    // The API's hint names the exact change when one first fits: its message and that sentence are the fix, as sent.
+    const hinted = hintedFix(error.hint);
+    return { fix: hinted ? `${String(error.message).trim()} ${hinted.sentence}` : budget.fix, next: budget.next, budget };
+  }
+  for (const [pattern, advice] of VALIDATION_PATTERNS) {
+    const match = pattern.exec(error.message ?? "");
+    if (match) return advice(match, error);
+  }
+  const entry = error.code ? GUIDE[error.code] : undefined;
+  if (!entry) return null;
+  return { fix: typeof entry.fix === "function" ? entry.fix(error) : entry.fix, next: entry.next };
+}
+
+/**
+ * What to do about a refused request, one line per distinct fix (at most
+ * three), each with the tool that helps, if any: a mutation is not a naming
+ * problem, and neither is a budget, whose line carries what the request
+ * measured and the limit.
+ *
+ *   Next:
+ *   - query_too_complex: articles: could read 40,200 entries, over the limit of 5,000. Pass coauthors(first: 24) to fit, or lower first elsewhere. Tool: capa_graphql_build.
+ */
+export function nextSteps(errors) {
+  const lines = [];
+  for (const error of errors) {
+    if (!error.code) continue;
+    const advice = adviceFor(error);
+    const line = advice
+      ? `${error.code}: ${advice.fix}${advice.next ? ` Tool: ${advice.next}.` : ""}`
+      : `${error.code}: read the message and hint. Tool: capa_explain_error.`;
+    if (!lines.includes(line)) lines.push(line);
+    if (lines.length === 3) break;
+  }
+  if (!lines.length) lines.push("Read the message above. Tool: capa_explain_error explains any code.");
+  return `Next:\n${lines.map((line) => `- ${line}`).join("\n")}`;
+}
+
+/** The one tool to call next for these errors: the first known error's, or capa_explain_error. */
+export function nextTool(errors) {
+  for (const error of errors) {
+    const advice = adviceFor(error);
+    if (advice) return advice.next ?? null;
+  }
+  return "capa_explain_error";
+}
+
+/**
+ * A request that never reached Capa: no API answered, so there is no code, no
+ * hint and no tool that helps, only the step this server gives for a host it
+ * cannot reach (client.mjs).
+ */
+function explainTransport(error) {
+  const timeout = error.transport === "timeout";
+  // Node 18's fetch tried only ::1 for localhost, which an API listening on IPv4 refuses.
+  const ipv6 = !timeout && /\[?::1\]?:\d+/.test(error.message ?? "")
+    ? " The address tried was ::1, IPv6's localhost: an API listening on IPv4 only answers at http://127.0.0.1:<port>, so use that in CAPA_API_URL, or run Node 20 or later."
+    : "";
+  const next = timeout ? TIMEOUT_NEXT : UNREACHABLE_NEXT;
+  return {
+    code: "unreachable",
+    transport: error.transport,
+    ...(error.message ? { message: error.message } : {}),
+    meaning: timeout
+      ? "Capa did not answer in time, so no API error code or hint came back."
+      : "The request never reached Capa's API, so no error code or hint came back: the connection itself failed.",
+    fix: `${next[0].toUpperCase()}${next.slice(1)}${ipv6}`,
+  };
+}
+
+/** One explained error: the API's own words first, then the guide's, a budget's numbers passed through. */
+export function explainOne(error) {
+  if (error.transport) return explainTransport(error);
+  const entry = error.code ? GUIDE[error.code] : undefined;
+  const advice = adviceFor(error);
+  const out = { code: error.code ?? "unknown" };
+  if (error.status) out.status = error.status;
+  if (error.message) out.message = error.message;
+  if (error.param) out.param = error.param;
+  if (error.path) out.path = error.path;
+  if (error.hint) out.apiHint = error.hint;
+  out.meaning = entry?.meaning ?? "Not a code this guide knows. Read message and apiHint; they come from the API.";
+  if (advice) out.fix = advice.fix;
+  if (advice?.budget) out.budget = { measured: advice.budget.measured, limit: advice.budget.limit };
+  // Auth, plan and transport errors have no tool that helps; say nothing then.
+  if (advice?.next) out.next = advice.next;
+  else if (!advice) out.next = "capa_graphql_schema";
+  if (error.code && entry) out.docs = `https://docs.capacms.com/errors/${error.code}`;
+  return out;
+}