@capacms/mcp 0.2.0

package/lib/graphql/build.mjs

@@ -0,0 +1,725 @@
+/**
+ * build.mjs — a query spec as GraphQL text and as the equal REST request.
+ *
+ * The spec is the small JSON `capa_graphql_build` takes ("these fields of
+ * articles, newest first, five of them"). It is resolved once against the
+ * key's schema summary, then printed twice: GraphQL in the one format every
+ * Capa builder emits (G plan 1.3), and the `/api/entries` URL the API itself
+ * would translate it to.
+ *
+ * `@capacms/sdk` has the same builder in TypeScript (`buildGraphQLQuery`,
+ * `graphqlToSelect`). This package has no dependencies, so it cannot import
+ * it; instead both are tested against one vector file,
+ * `packages/sdk/test/fixtures/graphql-vectors.json`, byte for byte.
+ */
+import { didYouMean } from "../suggest.mjs";
+import { isObject, typedFilter } from "./filter-values.mjs";
+import { writeName, writePath, writePathSegment } from "./names.mjs";
+
+export { didYouMean };
+
+export class BuildError extends Error {
+  constructor(message, didYouMean = [], available = []) {
+    super(message);
+    this.name = "BuildError";
+    this.didYouMean = didYouMean;
+    this.available = available;
+  }
+}
+
+/**
+ * A model the key reads that GraphQL leaves out (N1), named: REST serves it,
+ * and no GraphQL tool can. Never a spelling to correct, so no didYouMean.
+ */
+export class RestOnlyModel extends BuildError {
+  constructor(namespace, restOnly) {
+    // N1 leaves a model out when its type name would collide with another's, as
+    // these spellings do; for the sentence only, never for a name that is sent.
+    const letters = (name) => name.toLowerCase().replace(/[^0-9a-z]/g, "");
+    const partners = restOnly.filter((other) => other !== namespace && letters(other) === letters(namespace));
+    const named = ["it", ...partners];
+    const why = partners.length
+      ? `${named.slice(0, -1).join(", ")} and ${named.at(-1)} would have the same GraphQL type name`
+      : "its namespace gives no GraphQL type name of its own";
+    super(`${namespace} is readable over REST only: GET /api/entries/${namespace}. GraphQL leaves it out, since ${why}.`);
+    this.name = "RestOnlyModel";
+    this.namespace = namespace;
+  }
+}
+
+/** N6: the system fields every model type has. */
+export const SYSTEM_FIELDS = ["id", "model", "status", "createdAt", "updatedAt", "publishedAt", "_version", "_tags", "_folder"];
+const MEDIA_FIELDS = ["id", "url", "alt", "type", "width", "height"];
+const MEDIA_DEFAULT = ["id", "url", "alt"];
+/** Relations below the root entry: the API's 5 levels of entries count the root as the first (spec 17, amendment 78). */
+export const MAX_RELATION_DEPTH = 4;
+/** How deep a relation may nest, as every explanation and guide here says it. */
+export const RELATION_DEPTH_RULE = `at most ${MAX_RELATION_DEPTH} relations below the root entry (${MAX_RELATION_DEPTH + 1} levels of entries)`;
+/** The API's page sizes when `first` is not given: a list root, and a relation list inside an entry. */
+const LIST_DEFAULT = 25;
+export const NESTED_DEFAULT = 100;
+/** REST's `before=end`: the last entries of the list, read back from its end (spec 17, amendment 132). */
+export const END_OF_LIST = "end";
+const RELATION_OPERATORS = new Set(["eq", "ne", "in", "nin", "exists", "null", "has", "hasAny", "hasAll"]);
+/**
+ * Field kinds whose filter is its own operators plus dotted paths below it (a
+ * relation's hops, a media value's id). A relation the key cannot read is one
+ * too, so a hop through it prints as REST's dotted path, never a nested object.
+ */
+const HOP_KINDS = new Set(["relation", "relationList", "id", "idList", "media"]);
+
+/** A model's display name, the one the Capa admin shows: its description's first line without `(model <namespace>)`. */
+export function displayName(model) {
+  return model.description.split("\n")[0].replace(/ \(model [^()]+\)$/, "") || model.namespace;
+}
+
+/**
+ * A model by namespace or type name, then by any of those or its display name
+ * ignoring case (`Writers`, `scalar specimens`). An unknown name is refused
+ * with the nearest models, each by namespace, whichever of its names was near.
+ */
+export function findModel(summary, wanted) {
+  const exact = summary.models.find((m) => m.namespace === wanted || m.typeName === wanted);
+  if (exact) return exact;
+  const restOnly = summary.restOnly ?? [];
+  if (restOnly.includes(wanted)) throw new RestOnlyModel(wanted, restOnly);
+  const lower = String(wanted).toLowerCase();
+  const loose = summary.models.filter((m) => [m.namespace, m.typeName, displayName(m)].some((name) => name.toLowerCase() === lower));
+  if (loose.length === 1) return loose[0];
+  const looseRestOnly = restOnly.filter((name) => name.toLowerCase() === lower);
+  if (!loose.length && looseRestOnly.length === 1) throw new RestOnlyModel(looseRestOnly[0], restOnly);
+  const namespaces = summary.models.map((m) => m.namespace);
+  if (loose.length > 1) {
+    throw new BuildError(`model ${wanted} is ambiguous: pass one of ${orList(loose.map((m) => m.namespace))}`, loose.map((m) => m.namespace), namespaces);
+  }
+  const namespaceOf = new Map(summary.models.flatMap((m) => [m.namespace, m.typeName, displayName(m)].map((name) => [name, m.namespace])));
+  const near = [...new Set(didYouMean(wanted, [...namespaceOf.keys()]).map((name) => namespaceOf.get(name)))];
+  throw new BuildError(`unknown model ${wanted}`, near, namespaces);
+}
+
+const targetOf = (summary, field) => summary.models.find((m) => m.namespace === field?.target);
+const selectableNames = (model) => [...SYSTEM_FIELDS, ...model.fields.map((f) => f.name)];
+
+/** By GraphQL name, then a system field, then by namespace: `createdAt` is the system field even beside a `createdAt_field`. */
+function findField(model, wanted) {
+  const byName = model.fields.find((f) => f.name === wanted);
+  if (byName) return byName;
+  if (SYSTEM_FIELDS.includes(wanted)) return null;
+  const byNamespace = model.fields.find((f) => f.namespace === wanted);
+  if (byNamespace) return byNamespace;
+  throw new BuildError(`unknown field ${wanted} on ${model.typeName}`, didYouMean(wanted, selectableNames(model)), selectableNames(model));
+}
+
+function checkFirst(value, where) {
+  if (!Number.isInteger(value) || value < 1 || value > 200) throw new BuildError(`${where} must be a whole number from 1 to 200`);
+  return value;
+}
+
+function checkSort(value, model, where) {
+  if (typeof value !== "string" || !model.sortValues.includes(value)) {
+    const written = typeof value === "string" ? restSortValue(value) : null;
+    if (written && model.sortValues.includes(written)) {
+      throw new BuildError(`${where} ${JSON.stringify(value)} is REST's sort syntax: write ${JSON.stringify(written)}`, [written]);
+    }
+    throw new BuildError(`${where} ${JSON.stringify(value)} is not a value of ${model.sortType}`, didYouMean(String(value), model.sortValues), model.sortValues);
+  }
+  return value;
+}
+
+// ------------------------------------------------------------ REST forms ---
+//
+// An agent that has read a REST twin writes REST: `author.name` or
+// `author(name)` for a relation's fields, `*` for every field, `-publishedAt`
+// for a sort. Each is refused with what to write instead, spelled out, since
+// the same read is one edit away. @capacms/sdk refuses them in the same
+// words, pinned by packages/sdk/test/fixtures/graphql-rest-forms.json.
+
+/** A REST sort key as a sort value: `-publishedAt` is `publishedAt_DESC`, `author.name` is `author__name_ASC`. */
+function restSortValue(value) {
+  const match = /^(-?)([^\s-][^\s]*)$/.exec(value);
+  if (!match || /_(ASC|DESC)$/.test(match[2])) return null;
+  return `${match[2].split(".").join("__")}_${match[1] ? "DESC" : "ASC"}`;
+}
+
+/** Split REST select text on the commas outside parentheses; null when the parentheses do not pair. */
+function restItems(text) {
+  const items = [];
+  let depth = 0;
+  let start = 0;
+  for (let at = 0; at < text.length; at++) {
+    if (text[at] === "(") depth++;
+    else if (text[at] === ")" && --depth < 0) return null;
+    else if (text[at] === "," && depth === 0) {
+      items.push(text.slice(start, at).trim());
+      start = at + 1;
+    }
+  }
+  if (depth !== 0) return null;
+  items.push(text.slice(start).trim());
+  return items.filter(Boolean);
+}
+
+/** One REST select item as a field of a spec: `author(name,limit:5)` is `{ field: "author", fields: ["name"], first: 5 }`. */
+function restItemSpec(text) {
+  const open = text.indexOf("(");
+  const dot = text.indexOf(".");
+  if (open === -1 && dot === -1) return text;
+  if (open === -1 || (dot !== -1 && dot < open)) return { field: text.slice(0, dot), fields: [restItemSpec(text.slice(dot + 1))] };
+  if (!text.endsWith(")")) return null;
+  const inner = restItems(text.slice(open + 1, -1));
+  if (!inner) return null;
+  const spec = { field: text.slice(0, open) };
+  const fields = [];
+  const args = {};
+  for (const item of inner) {
+    const modifier = /^(limit|sort|after):(.+)$/.exec(item);
+    if (!modifier) {
+      const nested = restItemSpec(item);
+      if (nested === null) return null;
+      fields.push(nested);
+    } else if (modifier[1] === "limit") args.first = Number(modifier[2]);
+    else if (modifier[1] === "sort") args.sort = restSortValue(modifier[2]) ?? modifier[2];
+    else args.after = modifier[2];
+  }
+  if (fields.length) spec.fields = fields;
+  return { ...spec, ...args };
+}
+
+/**
+ * The refusal for a field item written as REST writes a select, or null when
+ * `wanted` is not one. A dotted or parenthesised item counts only when what
+ * comes first is a field of `model`: a namespace may itself hold a dot.
+ */
+function restFormRefusal(model, wanted, at) {
+  if (wanted === "*") {
+    return new BuildError(`${at} "*" is REST's select syntax: leave fields out for every field that is not a relation, or name the fields you want`);
+  }
+  const head = /^[^.(]+/.exec(wanted)?.[0];
+  if (!head || head === wanted || !model.fields.some((f) => f.name === head || f.namespace === head)) return null;
+  const spec = restItemSpec(wanted);
+  if (spec === null || typeof spec === "string") return null;
+  return new BuildError(`${at} ${JSON.stringify(wanted)} is REST's select syntax: write ${JSON.stringify(spec)}`);
+}
+
+/**
+ * A relation list's sort: one value, as its argument takes (N7). A list of
+ * one, the root's shape, is that value; a longer list is refused, since the
+ * API sorts a relation list by one key.
+ */
+function oneSort(value, name) {
+  if (!Array.isArray(value)) return value;
+  if (value.length === 1) return value[0];
+  throw new BuildError(`sort on ${name} takes one value: a relation list sorts by one key, unlike the root's up to 3`);
+}
+
+function mediaChildren(fields, owner) {
+  const planned = [{ name: "id", field: null }];
+  for (const item of fields ?? MEDIA_DEFAULT) {
+    if (typeof item !== "string" || !MEDIA_FIELDS.includes(item)) {
+      const name = typeof item === "string" ? item : item?.field;
+      throw new BuildError(`unknown field ${name} on Media (${owner})`, didYouMean(name, MEDIA_FIELDS), MEDIA_FIELDS);
+    }
+    if (item !== "id") planned.push({ name: item, field: null });
+  }
+  return planned;
+}
+
+/** Every current non-relation field, single relations as `{ id }`, media as `{ id url alt }`; array relations and deprecated fields left out. */
+function defaultFields(model) {
+  return model.fields.filter((f) => f.kind !== "relationList" && !f.deprecationReason).map((f) => f.name);
+}
+
+/** The keys a relation spec (`{ field, fields, first, sort }`) takes. */
+const FIELD_SPEC_KEYS = ["field", "fields", "first", "sort"];
+
+/**
+ * A key the builder does not read is refused by name, at any depth: a typo
+ * dropped silently (`frist`) builds a query without the argument and reports
+ * that it worked.
+ */
+function checkSpecKeys(spec, path) {
+  for (const key of Object.keys(spec)) {
+    if (FIELD_SPEC_KEYS.includes(key)) continue;
+    const near = didYouMean(key, FIELD_SPEC_KEYS);
+    throw new BuildError(
+      `Unknown argument ${key} in ${path}.${near.length ? ` Did you mean ${near.join(" or ")}?` : ""} Allowed: ${FIELD_SPEC_KEYS.join(", ")}.`,
+      near,
+    );
+  }
+}
+
+/** `path` names where `specs` sit in the spec, `fields[1].fields`, for a refusal. */
+function planFields(summary, model, specs, depth, path = "fields") {
+  if (specs !== undefined && !Array.isArray(specs)) throw new BuildError(`fields of ${model.typeName} must be an array`);
+  const planned = [{ name: "id", field: null }];
+  const seen = new Set(["id"]);
+  for (const [index, spec] of (specs ?? defaultFields(model)).entries()) {
+    const nested = typeof spec === "object" && spec !== null;
+    if (nested) checkSpecKeys(spec, `${path}[${index}]`);
+    const wanted = nested ? spec.field : spec;
+    if (typeof wanted !== "string" || wanted === "") {
+      throw new BuildError(`each field of ${model.typeName} must be a name or { field, fields }`);
+    }
+    let field;
+    try {
+      field = findField(model, wanted);
+    } catch (error) {
+      throw (!nested && restFormRefusal(model, wanted, `${path}[${index}]`)) || error;
+    }
+    const name = field?.name ?? wanted;
+    if (seen.has(name)) continue;
+    seen.add(name);
+    const kind = field?.kind ?? "scalar";
+    if (nested && (spec.first !== undefined || spec.sort !== undefined) && kind !== "relationList") {
+      throw new BuildError(`first and sort apply to array relations; ${name} on ${model.typeName} is not one`);
+    }
+    if (kind === "relation" || kind === "relationList") {
+      const target = targetOf(summary, field);
+      if (!target) throw new BuildError(`${name} on ${model.typeName} points at a model this key cannot read`);
+      if (depth >= MAX_RELATION_DEPTH) throw new BuildError(`${name} would expand past ${MAX_RELATION_DEPTH} relation levels. Select ${name} without fields for its id, or read it with a second query`);
+      const children = planFields(summary, target, nested ? spec.fields ?? ["id"] : ["id"], depth + 1, `${path}[${index}].fields`);
+      const entry = { name, field, target, children };
+      if (nested && spec.first !== undefined) entry.first = checkFirst(spec.first, `first on ${name}`);
+      if (nested && spec.sort !== undefined) entry.sort = checkSort(oneSort(spec.sort, name), target, `sort on ${name}`);
+      planned.push(entry);
+    } else if (kind === "media") {
+      planned.push({ name, field, children: mediaChildren(nested ? spec.fields : undefined, name) });
+    } else {
+      if (nested && spec.fields !== undefined) {
+        throw new BuildError(
+          kind === "id" || kind === "idList"
+            ? `${name} on ${model.typeName} is an id here: this key cannot read the model it points at. Select ${name} without fields for the id`
+            : `${name} on ${model.typeName} has no fields to select`,
+        );
+      }
+      planned.push({ name, field });
+    }
+  }
+  return planned;
+}
+
+/** The system fields `model`'s filter takes, as the schema declares them. */
+const systemFilterNames = (model) => model.systemFilters.map((system) => system.name);
+
+/** Every name a filter object on `model` may start with. */
+export function filterableNames(model) {
+  return ["and", "or", "not", ...systemFilterNames(model), ...model.fields.filter((f) => f.filterOps.length > 0).map((f) => f.name)];
+}
+
+/** `a, b and c`, `a, b or c`: names in a sentence. */
+const andList = (names) => `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+const orList = (names) => `${names.slice(0, -1).join(", ")} or ${names.at(-1)}`;
+
+/** GraphQL scalars an operator takes; any other input type under a field's filter is a hop into a related field. */
+const OPERAND_SCALARS = new Set(["String", "ID", "Float", "Int", "Boolean", "DateTime", "JSON"]);
+/** The operators of a system field reached through a hop (`author: { id: { eq } }`), as the API's IDFilter and DateTimeFilter declare them. */
+const SYSTEM_HOP_OPERATORS = ["eq", "ne", "lt", "lte", "gt", "gte", "in", "nin", "exists", "null"];
+
+/** Whether `key` under `field`'s filter is a hop into a field of the related model rather than an operator. */
+export function isHop(field, key) {
+  const type = field.filterInputs?.[key];
+  return type !== undefined && !OPERAND_SCALARS.has(type);
+}
+
+/**
+ * The operator a bare value stands for under `operators`, and the value it
+ * takes: equality for one value, membership for a list, `null: true` for null.
+ */
+function operatorFor(operators, value) {
+  if (value === null) return operators.includes("null") ? ["null", true] : null;
+  if (Array.isArray(value)) {
+    const op = ["in", "hasAny"].find((name) => operators.includes(name));
+    return op ? [op, value] : null;
+  }
+  const op = ["eq", "has", "id"].find((name) => operators.includes(name));
+  return op ? [op, value] : null;
+}
+
+/**
+ * A filter written without operators (`{ "featured": true }`) is refused with
+ * the operator form to write instead: GraphQL declares an object of operators
+ * there, so the shorthand would fail on the API and has no REST twin.
+ */
+function refuseBareValue(label, operators, value, wrap) {
+  const operator = operatorFor(operators, value);
+  const fix = operator ? ` write ${JSON.stringify(wrap({ [operator[0]]: operator[1] }))}` : ` use one of ${orList(operators)}`;
+  throw new BuildError(`${label} takes operators, not a bare value:${fix}`, [], operators);
+}
+
+/**
+ * The keys under one field's filter: the input fields its filter type
+ * declares, each an operator or, on a relation, a hop into a field of the
+ * related model, which takes operators of its own. A relation the key cannot
+ * read is an id with no hop, refused without naming the model it points at.
+ */
+function checkFieldFilter(summary, model, field, operations) {
+  if (!isObject(operations)) refuseBareValue(field.name, field.filterOps, operations, (ops) => ({ [field.name]: ops }));
+  for (const [key, inner] of Object.entries(operations)) {
+    if (!field.filterOps.includes(key)) {
+      if (field.kind === "id" || field.kind === "idList") {
+        throw new BuildError(
+          `${field.name} on ${model.typeName} is an id here: this key cannot read the model it points at, so a filter cannot reach ${key} through it. Filter ${field.name} by id with ${orList(field.filterOps)}`,
+          [],
+          field.filterOps,
+        );
+      }
+      throw new BuildError(`unknown filter ${key} under ${field.name} on ${model.filterType}`, didYouMean(key, field.filterOps), field.filterOps);
+    }
+    if (!isHop(field, key)) continue;
+    const hop = targetOf(summary, field)?.fields.find((f) => f.name === key);
+    const operators = hop ? hop.filterOps : SYSTEM_HOP_OPERATORS;
+    const wrap = (ops) => ({ [field.name]: { [key]: ops } });
+    if (!isObject(inner)) refuseBareValue(`${field.name}.${key}`, operators, inner, wrap);
+    for (const op of Object.keys(inner)) {
+      if (!operators.includes(op)) {
+        throw new BuildError(`unknown filter ${op} under ${field.name}.${key} on ${model.filterType}`, didYouMean(op, operators), operators);
+      }
+    }
+  }
+}
+
+/** A filter's names and shapes, through and, or and not. The system fields it takes are the ones the schema declares. */
+function checkFilter(summary, model, filter) {
+  if (!isObject(filter)) throw new BuildError(`filter must be an object of ${model.filterType}`);
+  const allowed = filterableNames(model);
+  for (const [key, value] of Object.entries(filter)) {
+    if (key === "and" || key === "or") {
+      for (const part of Array.isArray(value) ? value : [value]) checkFilter(summary, model, part);
+      continue;
+    }
+    if (key === "not") {
+      checkFilter(summary, model, value);
+      continue;
+    }
+    if (!allowed.includes(key)) {
+      if (SYSTEM_FIELDS.includes(key)) {
+        throw new BuildError(
+          `${key} cannot be filtered: ${model.filterType} filters the system fields ${andList(systemFilterNames(model))} only`,
+          [],
+          allowed,
+        );
+      }
+      throw new BuildError(`unknown filter field ${key} on ${model.filterType}`, didYouMean(key, allowed), allowed);
+    }
+    const field = model.fields.find((f) => f.name === key);
+    const system = model.systemFilters.find((f) => f.name === key);
+    if (field) checkFieldFilter(summary, model, field, value);
+    else if (system && !isObject(value)) refuseBareValue(key, system.filterOps, value, (ops) => ({ [key]: ops }));
+  }
+  return filter;
+}
+
+/** Resolve and check a spec. Throws `BuildError`. */
+export function planQuery(summary, spec) {
+  if (!spec || typeof spec !== "object") throw new BuildError("a query spec must be an object with model");
+  const model = findModel(summary, spec.model);
+  // An id reads that one entry: it is never dropped into a list of every entry.
+  const mode = spec.mode ?? (spec.id !== undefined ? "single" : "list");
+  if (mode !== "list" && mode !== "single") throw new BuildError(`mode must be list or single, not ${String(mode)}`);
+  if (mode === "list" && spec.id !== undefined) {
+    throw new BuildError('id reads one entry, so it takes mode single: pass mode "single", or leave id out to list entries');
+  }
+  if (mode === "single") {
+    if (typeof spec.id !== "string" || spec.id === "") throw new BuildError("mode single needs id, the entry's UUID");
+    for (const key of ["first", "after", "before", "sort", "filter", "totalCount"]) {
+      if (spec[key] !== undefined) throw new BuildError(`${key} applies to mode list only`);
+    }
+  }
+  if (spec.after !== undefined && spec.before !== undefined) {
+    throw new BuildError("after and before page in opposite directions: pass after to read on, or before to read back, not both");
+  }
+  if (spec.after !== undefined && String(spec.after) === END_OF_LIST) {
+    throw new BuildError('after takes an endCursor, and "end" is none: pass before: "end" to read the last entries of the list');
+  }
+  const plan = {
+    model,
+    mode,
+    fields: planFields(summary, model, spec.fields, 0),
+    totalCount: spec.totalCount === true,
+    operationName: spec.operationName ?? `${model.typeName}${mode === "single" ? "ById" : "List"}`,
+  };
+  if (mode === "single") plan.id = spec.id;
+  if (spec.first !== undefined) plan.first = checkFirst(spec.first, "first");
+  if (spec.after !== undefined) plan.after = String(spec.after);
+  if (spec.before !== undefined) plan.before = String(spec.before);
+  if (spec.sort !== undefined) {
+    // One value may be given alone, as a relation list's sort is.
+    const sort = typeof spec.sort === "string" ? [spec.sort] : spec.sort;
+    if (!Array.isArray(sort) || sort.length === 0 || sort.length > 3) {
+      throw new BuildError(`sort takes 1 to 3 values of ${model.sortType}`, [], model.sortValues);
+    }
+    plan.sort = sort.map((value) => checkSort(value, model, "sort"));
+  }
+  if (spec.filter !== undefined) plan.filter = typedFilter(summary, model, checkFilter(summary, model, spec.filter));
+  return plan;
+}
+
+/**
+ * The most entries one entry of `fields` can read: itself, and for each
+ * expanded relation its limit (1 for a single relation; `first`, default 100,
+ * for a list) times what each of its entries can read. A list root reads
+ * `first` times this. It is never less than the API's pre-SQL bound, which
+ * counts a list with no `first` as 10 (spec 17, amendment 76), so a `first`
+ * that fits it fits both that bound and what the read returns.
+ */
+export function entriesPerEntry(fields) {
+  let total = 1;
+  for (const field of fields) {
+    if (!field.target) continue;
+    const limit = field.field?.kind === "relationList" ? field.first ?? NESTED_DEFAULT : 1;
+    total += limit * entriesPerEntry(field.children);
+  }
+  return total;
+}
+
+/**
+ * The largest `first` that keeps a list plan inside `limit` entries: 0 when
+ * even one entry reads more (its relation lists are then what to lower), and
+ * null when the plan's own `first` already fits.
+ */
+export function firstWithin(plan, limit) {
+  const first = Math.floor(limit / entriesPerEntry(plan.fields));
+  return first >= (plan.first ?? LIST_DEFAULT) ? null : first;
+}
+
+// ----------------------------------------------------------------- GraphQL ---
+
+const INDENT = "  ";
+
+/**
+ * `pages` also selects each relation list's `pageInfo`, and `cursors` its
+ * entries' cursors beside it: what a tool that runs the query reads to say
+ * which lists hold more than they show. A planned `after` on a relation list
+ * (never from a spec) reads on from a cursor.
+ */
+function printFields(fields, depth, pages = { pageInfo: false, cursors: false }) {
+  const pad = INDENT.repeat(depth);
+  const inner = pad + INDENT;
+  const lines = [];
+  for (const field of fields) {
+    if (!field.children) {
+      lines.push(`${pad}${field.name}`);
+    } else if (field.field?.kind === "relationList") {
+      const args = [];
+      if (field.first !== undefined) args.push(`first: ${field.first}`);
+      if (field.sort !== undefined) args.push(`sort: ${field.sort}`);
+      if (field.after !== undefined) args.push(`after: ${JSON.stringify(field.after)}`);
+      lines.push(`${pad}${field.name}${args.length ? `(${args.join(", ")})` : ""} {`, `${inner}nodes {`);
+      lines.push(...printFields(field.children, depth + 2, pages), `${inner}}`);
+      if (pages.cursors) lines.push(`${inner}edges {`, `${inner}${INDENT}cursor`, `${inner}}`);
+      if (pages.pageInfo) lines.push(`${inner}pageInfo {`, `${inner}${INDENT}hasNextPage`, `${inner}${INDENT}endCursor`, `${inner}}`);
+      lines.push(`${pad}}`);
+    } else {
+      lines.push(`${pad}${field.name} {`, ...printFields(field.children, depth + 1, pages), `${pad}}`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * `{ query, variables, operationName }` for a checked plan, in plan 1.3's
+ * format. `cursors` also selects each entry's cursor (`edges { cursor }`),
+ * in the root list and in every relation list, for a caller that may cut a
+ * list and must then hand back the cursor of the last entry kept; it selects
+ * each relation list's `pageInfo` too, as `pages` does alone.
+ */
+export function printGraphQL(plan, { cursors = false, pages = cursors } = {}) {
+  const nested = { pageInfo: pages || cursors, cursors };
+  const { model } = plan;
+  const variables = {};
+  const declared = [];
+  const passed = [];
+  const argument = (name, type, value) => {
+    if (value === undefined) return;
+    variables[name] = value;
+    declared.push(`$${name}: ${type}`);
+    passed.push(`${name}: $${name}`);
+  };
+  argument("id", "ID!", plan.id);
+  // REST's limit beside before is GraphQL's last beside before, the entries
+  // just before the cursor; the API refuses first there (spec 17, amendment 55).
+  // REST's before=end is last with no before, the end of the list (amendment 132).
+  const fromEnd = plan.before === END_OF_LIST;
+  argument(plan.before === undefined ? "first" : "last", "Int", fromEnd ? plan.first ?? LIST_DEFAULT : plan.first);
+  argument("after", "String", plan.after);
+  if (!fromEnd) argument("before", "String", plan.before);
+  argument("sort", `[${model.sortType}!]`, plan.sort);
+  argument("filter", model.filterType, plan.filter);
+  const root = plan.mode === "single" ? model.singleField : model.listField;
+  const lines = [`query ${plan.operationName}${declared.length ? `(${declared.join(", ")})` : ""} {`];
+  lines.push(`${INDENT}${root}${passed.length ? `(${passed.join(", ")})` : ""} {`);
+  if (plan.mode === "single") {
+    lines.push(...printFields(plan.fields, 2, nested));
+  } else {
+    const two = INDENT.repeat(2);
+    lines.push(`${two}nodes {`, ...printFields(plan.fields, 3, nested), `${two}}`);
+    if (cursors) lines.push(`${two}edges {`, `${two}${INDENT}cursor`, `${two}}`);
+    // A page read backward pages on back from its startCursor, as REST's page.prev.
+    const back = plan.before === undefined ? [] : [`${two}${INDENT}hasPreviousPage`, `${two}${INDENT}startCursor`];
+    lines.push(`${two}pageInfo {`, `${two}${INDENT}hasNextPage`, `${two}${INDENT}endCursor`, ...back, `${two}}`);
+    if (plan.totalCount) lines.push(`${two}totalCount`);
+  }
+  lines.push(`${INDENT}}`, "}");
+  return { query: lines.join("\n"), variables, operationName: plan.operationName };
+}
+
+export function buildGraphQLQuery(summary, spec) {
+  return printGraphQL(planQuery(summary, spec));
+}
+
+// -------------------------------------------------------------------- REST ---
+//
+// The REST twin is written exactly as the API writes it in
+// `extensions.capa.rest`, so an agent sees one REST syntax everywhere: the
+// filter as `where` JSON, keys in the filter input's declared order, the
+// root's default page size left out, a relation list's `first` written as
+// `limit:` whenever the spec gives it (REST's node bound counts an unwritten
+// limit as 10 and a written one in full, spec 17 amendment 76), a system
+// key a field shadows as `$tags`, and a namespace holding a character REST's
+// grammars use quoted (`"price.usd"`, names.mjs, amendment 121).
+// The vector file pins it to a live capture.
+
+/** System fields a REST `select` names, in the API's order, with their REST keys. `id`, `model`, `status` always come back. */
+const REST_SYSTEM_SELECT = [
+  ["createdAt", "createdAt"],
+  ["updatedAt", "updatedAt"],
+  ["publishedAt", "publishedAt"],
+  ["_version", "version"],
+  ["_folder", "folder"],
+  ["_tags", "tags"],
+];
+/** GraphQL system field names to REST system keys, where the two differ. */
+const REST_SYSTEM_KEY = { _version: "version", _folder: "folder", _tags: "tags" };
+/**
+ * Whether a field of `model` takes the REST name `namespace`: one GraphQL
+ * exposes, or one N5 left out (the type description's `Not exposed:` line),
+ * which REST still reads by that name.
+ */
+const hasField = (model, namespace) => model.fields.some((f) => f.namespace === namespace) || model.notExposed.includes(namespace);
+/**
+ * REST reads a plain name as a model field first, so a system key a field
+ * shadows is written `$tags` (`$createdAt`, `author.$id`), as the API writes
+ * it; plain wherever no field takes the name.
+ */
+const systemKeyName = (model, key) => (hasField(model, key) ? `$${key}` : key);
+/** Every filter operator, in the order the API's filter input types declare them. */
+const OPERATOR_ORDER = ["eq", "ne", "lt", "lte", "gt", "gte", "in", "nin", "contains", "startsWith", "endsWith", "has", "hasAny", "hasAll", "exists", "null", "id"];
+
+/** `keys` in `order` first, then the rest as they came. */
+function ordered(keys, order) {
+  const rank = (key) => (order.indexOf(key) === -1 ? order.length : order.indexOf(key));
+  return keys.map((key, i) => ({ key, i })).sort((a, b) => rank(a.key) - rank(b.key) || a.i - b.i).map((k) => k.key);
+}
+
+function restSort(summary, model, value) {
+  const match = /^(.*)_(ASC|DESC)$/.exec(value);
+  const [relationName, targetName] = match[1].split("__");
+  const direction = match[2] === "DESC" ? "-" : "";
+  const field = model.fields.find((f) => f.name === relationName);
+  if (targetName === undefined) return `${direction}${field ? writeName(field.namespace) : systemKeyName(model, relationName)}`;
+  const targetField = targetOf(summary, field)?.fields.find((f) => f.name === targetName);
+  return `${direction}${writePath([field?.namespace ?? relationName, targetField?.namespace ?? targetName])}`;
+}
+
+/**
+ * One level of `select`: system keys (`$tags` where a field is called `tags`),
+ * then fields, each namespace bare or quoted as REST writes it, a relation
+ * always with parentheses; a level that selects nothing else is `id` (`$id`
+ * beside a field called id).
+ */
+function restSelectText(summary, model, fields) {
+  const system = new Set(fields.filter((f) => !f.field).map((f) => f.name));
+  const items = REST_SYSTEM_SELECT.filter(([name]) => system.has(name)).map(([, key]) => systemKeyName(model, key));
+  for (const planned of fields) {
+    if (!planned.field) continue;
+    const namespace = writeName(planned.field.namespace);
+    if (!planned.target) {
+      items.push(namespace);
+      continue;
+    }
+    const args = [restSelectText(summary, planned.target, planned.children)];
+    if (planned.first !== undefined) args.push(`limit:${planned.first}`);
+    if (planned.sort !== undefined) args.push(`sort:${restSort(summary, planned.target, planned.sort)}`);
+    items.push(`${namespace}(${args.join(",")})`);
+  }
+  return items.length ? items.join(",") : systemKeyName(model, "id");
+}
+
+/** An operator object without null members, in operator order; null when empty. */
+function restOperations(value, order = OPERATOR_ORDER) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const out = {};
+  for (const key of ordered(Object.keys(value), order)) if (value[key] !== null && value[key] !== undefined) out[key] = value[key];
+  return Object.keys(out).length ? out : null;
+}
+
+/** A GraphQL filter as the REST `where` object, key for key as the API prints it. */
+function restWhere(summary, model, filter) {
+  const where = {};
+  const order = ["and", "or", "not", ...systemFilterNames(model), ...model.fields.map((f) => f.name)];
+  for (const key of ordered(Object.keys(filter), order)) {
+    const value = filter[key];
+    if (value === null || value === undefined) continue;
+    if (key === "and" || key === "or") {
+      where[key] = (Array.isArray(value) ? value : [value]).map((part) => restWhere(summary, model, part));
+      continue;
+    }
+    if (key === "not") {
+      const inner = restWhere(summary, model, value);
+      if (Object.keys(inner).length) where.not = inner;
+      continue;
+    }
+    const field = model.fields.find((f) => f.name === key);
+    const declared = (field ?? model.systemFilters.find((f) => f.name === key))?.filterOps;
+    const operations = restOperations(value, declared?.length ? declared : OPERATOR_ORDER);
+    if (!operations) continue;
+    if (!field) {
+      // A system field: `_tags` is REST's `tags`, or `$tags` beside a field called tags (amendment 56).
+      where[systemKeyName(model, REST_SYSTEM_KEY[key] ?? key)] = operations;
+      continue;
+    }
+    const written = writeName(field.namespace);
+    if (!HOP_KINDS.has(field.kind)) {
+      where[written] = operations;
+      continue;
+    }
+    const target = targetOf(summary, field);
+    const own = {};
+    const hops = [];
+    for (const [name, inner] of Object.entries(operations)) {
+      if (field.kind === "media" && name === "id") hops.push([`${written}.id`, { eq: inner }]);
+      else if (field.kind === "media" || RELATION_OPERATORS.has(name)) own[name] = inner;
+      else {
+        const hop = restOperations(inner);
+        const segment = target ? target.fields.find((f) => f.name === name)?.namespace ?? systemKeyName(target, name) : name;
+        if (hop) hops.push([`${written}.${writePathSegment(segment)}`, hop]);
+      }
+    }
+    if (Object.keys(own).length) where[written] = own;
+    for (const [path, hop] of hops) where[path] = hop;
+  }
+  return where;
+}
+
+const encode = (value) => encodeURIComponent(value).replace(/%2C/g, ",").replace(/%3A/g, ":").replace(/%24/g, "$");
+
+/** `{ path, select, params, url }`: the `/api/entries` request a plan is equal to, as the API prints it. */
+export function printRest(summary, plan) {
+  const { model } = plan;
+  const select = restSelectText(summary, model, plan.fields);
+  const params = [["select", select]];
+  if (plan.filter) {
+    const where = restWhere(summary, model, plan.filter);
+    if (Object.keys(where).length) params.push(["where", JSON.stringify(where)]);
+  }
+  if (plan.sort) params.push(["sort", plan.sort.map((value) => restSort(summary, model, value)).join(",")]);
+  if (plan.first !== undefined && plan.first !== LIST_DEFAULT) params.push(["limit", String(plan.first)]);
+  if (plan.after !== undefined) params.push(["after", plan.after]);
+  if (plan.before !== undefined) params.push(["before", plan.before]);
+  if (plan.totalCount) params.push(["count", "true"]);
+  const path =
+    plan.mode === "single"
+      ? `/api/entries/${encodeURIComponent(model.namespace)}/${encodeURIComponent(plan.id)}`
+      : `/api/entries/${encodeURIComponent(model.namespace)}`;
+  return { path, select, params, url: `${path}?${params.map(([k, v]) => `${k}=${encode(v)}`).join("&")}` };
+}