@capacms/mcp 0.2.0

package/lib/graphql/document.mjs

@@ -0,0 +1,388 @@
+/**
+ * document.mjs — the connections a GraphQL document reads, found by FIELD NAME
+ * rather than by the keys of its answer.
+ *
+ * A cut answer must stay pageable (lib/bound.mjs), which means knowing which
+ * lists are a connection's entries, which object is its pageInfo, and which
+ * way the page runs. The answer alone cannot say: `items: nodes` answers
+ * under `items`, `info: pageInfo` under `info`, and a page read with `last`
+ * and `before` looks exactly like one read with `first`. The document can, so
+ * this reads it: operations, fragments, inline fragments, aliases and
+ * argument values, the executable part of the GraphQL grammar and nothing
+ * else. It is written here because this package has no dependencies.
+ *
+ * A document this cannot read gives `null`, and the caller falls back to
+ * reading the answer by its literal key names. The API has already parsed
+ * and run the document by then, so that only happens on a reader bug.
+ */
+
+const PUNCTUATORS = new Set(["!", "$", "&", "(", ")", ":", "=", "@", "[", "]", "{", "|", "}"]);
+const NAME = /[_A-Za-z][_0-9A-Za-z]*/y;
+const NUMBER = /-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+/** The fields of a PageInfo that a cut repairs. */
+const PAGE_FIELDS = ["hasNextPage", "hasPreviousPage", "startCursor", "endCursor"];
+
+class Unreadable extends Error {}
+
+/** The document's tokens: `{ kind: "punct" | "name" | "number" | "string", value, start, end }`, `end` exclusive. */
+function tokenize(source) {
+  const tokens = [];
+  let at = 0;
+  while (at < source.length) {
+    const c = source[at];
+    if (c === "#") {
+      while (at < source.length && source[at] !== "\n" && source[at] !== "\r") at++;
+    } else if (c === " " || c === "\t" || c === "\n" || c === "\r" || c === "," || c === "") {
+      at++;
+    } else if (source.startsWith("...", at)) {
+      tokens.push({ kind: "punct", value: "...", start: at, end: at + 3 });
+      at += 3;
+    } else if (PUNCTUATORS.has(c)) {
+      tokens.push({ kind: "punct", value: c, start: at, end: at + 1 });
+      at++;
+    } else if (source.startsWith('"""', at)) {
+      const end = blockStringEnd(source, at + 3);
+      tokens.push({ kind: "string", value: source.slice(at + 3, end), start: at, end: end + 3 });
+      at = end + 3;
+    } else if (c === '"') {
+      const [value, end] = readString(source, at + 1);
+      tokens.push({ kind: "string", value, start: at, end });
+      at = end;
+    } else {
+      const token = matchAt(NAME, source, at, "name") ?? matchAt(NUMBER, source, at, "number");
+      if (!token) throw new Unreadable(`unexpected ${c}`);
+      tokens.push({ ...token, start: at, end: at + token.text.length });
+      at += token.text.length;
+    }
+  }
+  return tokens;
+}
+
+function matchAt(pattern, source, at, kind) {
+  pattern.lastIndex = at;
+  const match = pattern.exec(source);
+  return match ? { kind, value: kind === "number" ? Number(match[0]) : match[0], text: match[0] } : null;
+}
+
+function blockStringEnd(source, from) {
+  for (let at = from; at < source.length; at++) {
+    if (source[at] === "\\" && source.startsWith('\\"""', at)) at += 3;
+    else if (source.startsWith('"""', at)) return at;
+  }
+  throw new Unreadable("unterminated block string");
+}
+
+function readString(source, from) {
+  let at = from;
+  let raw = "";
+  while (at < source.length && source[at] !== '"') {
+    if (source[at] === "\n" || source[at] === "\r") break;
+    if (source[at] === "\\") {
+      raw += source.slice(at, at + (source[at + 1] === "u" ? 6 : 2));
+      at += source[at + 1] === "u" ? 6 : 2;
+    } else {
+      raw += source[at++];
+    }
+  }
+  if (source[at] !== '"') throw new Unreadable("unterminated string");
+  return [JSON.parse(`"${raw}"`), at + 1];
+}
+
+/** A recursive-descent reader over the tokens, for the executable definitions only. */
+function parse(source) {
+  const tokens = tokenize(source);
+  let at = 0;
+  const peek = (value) => tokens[at]?.kind === "punct" && tokens[at].value === value;
+  const next = () => {
+    if (at >= tokens.length) throw new Unreadable("unexpected end of document");
+    return tokens[at++];
+  };
+  const expect = (value) => {
+    const token = next();
+    if (token.kind !== "punct" || token.value !== value) throw new Unreadable(`expected ${value}`);
+  };
+  const name = () => {
+    const token = next();
+    if (token.kind !== "name") throw new Unreadable("expected a name");
+    return token.value;
+  };
+
+  const value = () => {
+    const token = next();
+    if (token.kind === "punct" && token.value === "$") return { variable: name() };
+    if (token.kind === "punct" && token.value === "[") {
+      const items = [];
+      while (!peek("]")) items.push(value());
+      expect("]");
+      return { list: items };
+    }
+    if (token.kind === "punct" && token.value === "{") {
+      const fields = {};
+      while (!peek("}")) {
+        const key = name();
+        expect(":");
+        fields[key] = value();
+      }
+      expect("}");
+      return { object: fields };
+    }
+    if (token.kind === "name") return { literal: token.value === "null" ? null : token.value === "true" ? true : token.value === "false" ? false : token.value };
+    if (token.kind === "string" || token.kind === "number") return { literal: token.value };
+    throw new Unreadable("expected a value");
+  };
+  /** A field's arguments by name, and where the document writes them: `spans` (from the name to the value's end) and `close`, the `)`. */
+  const args = () => {
+    const out = {};
+    const spans = {};
+    if (!peek("(")) return { values: out, spans, close: null };
+    expect("(");
+    while (!peek(")")) {
+      const start = tokens[at].start;
+      const key = name();
+      expect(":");
+      out[key] = value();
+      spans[key] = { start, end: tokens[at - 1].end };
+    }
+    const close = tokens[at].start;
+    expect(")");
+    return { values: out, spans, close };
+  };
+  const directives = () => {
+    while (peek("@")) {
+      expect("@");
+      name();
+      args();
+    }
+  };
+  const type = () => {
+    if (peek("[")) {
+      expect("[");
+      type();
+      expect("]");
+    } else {
+      name();
+    }
+    if (peek("!")) expect("!");
+  };
+  const selectionSet = () => {
+    expect("{");
+    const selections = [];
+    while (!peek("}")) selections.push(selection());
+    expect("}");
+    return selections;
+  };
+  const selection = () => {
+    if (peek("...")) {
+      expect("...");
+      if (tokens[at]?.kind === "name" && tokens[at].value !== "on") {
+        const spread = name();
+        directives();
+        return { spread };
+      }
+      if (tokens[at]?.kind === "name") {
+        next();
+        name();
+      }
+      directives();
+      return { inline: selectionSet() };
+    }
+    const first = name();
+    let field = first;
+    let alias = first;
+    if (peek(":")) {
+      expect(":");
+      field = name();
+    }
+    const nameEnd = tokens[at - 1].end;
+    const fieldArgs = args();
+    directives();
+    return {
+      field,
+      key: alias,
+      args: fieldArgs.values,
+      written: { nameEnd, args: fieldArgs.spans, close: fieldArgs.close },
+      selections: peek("{") ? selectionSet() : [],
+    };
+  };
+
+  const operations = [];
+  const fragments = new Map();
+  while (at < tokens.length) {
+    if (peek("{")) {
+      operations.push({ name: null, variables: {}, selections: selectionSet() });
+      continue;
+    }
+    const keyword = name();
+    if (keyword === "fragment") {
+      const fragment = name();
+      if (name() !== "on") throw new Unreadable("expected on");
+      name();
+      directives();
+      fragments.set(fragment, selectionSet());
+    } else if (keyword === "query" || keyword === "mutation" || keyword === "subscription") {
+      const operation = tokens[at]?.kind === "name" ? name() : null;
+      const variables = {};
+      if (peek("(")) {
+        expect("(");
+        while (!peek(")")) {
+          expect("$");
+          const variable = name();
+          expect(":");
+          type();
+          variables[variable] = peek("=") ? (expect("="), value()) : { literal: undefined };
+          directives();
+        }
+        expect(")");
+      }
+      directives();
+      operations.push({ name: operation, variables, selections: selectionSet() });
+    } else {
+      throw new Unreadable(`unexpected ${keyword}`);
+    }
+  }
+  return { operations, fragments };
+}
+
+/** A value with every variable replaced by what was sent, else the variable's default. */
+function resolve(node, variables, defaults) {
+  if (!node) return undefined;
+  if ("variable" in node) {
+    if (variables && Object.hasOwn(variables, node.variable)) return variables[node.variable];
+    return resolve(defaults[node.variable], variables, defaults);
+  }
+  if ("list" in node) return node.list.map((item) => resolve(item, variables, defaults));
+  if ("object" in node) return Object.fromEntries(Object.entries(node.object).map(([k, v]) => [k, resolve(v, variables, defaults)]));
+  return node.literal;
+}
+
+/**
+ * The fields a selection set reads, by response key, through fragments and
+ * inline fragments. Fields sharing a key are one field: their selections merge.
+ */
+function fieldsOf(selections, fragments, seen = new Set()) {
+  const byKey = new Map();
+  const add = (list) => {
+    for (const selection of list) {
+      if (selection.spread !== undefined) {
+        if (seen.has(selection.spread)) continue;
+        const fragment = fragments.get(selection.spread);
+        if (!fragment) throw new Unreadable(`unknown fragment ${selection.spread}`);
+        add(fieldsOf(fragment, fragments, new Set([...seen, selection.spread])).flatMap((f) => f.parts));
+      } else if (selection.inline) {
+        add(selection.inline);
+      } else {
+        const known = byKey.get(selection.key);
+        if (known) known.parts.push(selection);
+        else byKey.set(selection.key, { key: selection.key, field: selection.field, args: selection.args, parts: [selection] });
+      }
+    }
+  };
+  add(selections);
+  return [...byKey.values()].map((f) => ({ ...f, selections: f.parts.flatMap((p) => p.selections) }));
+}
+
+/** The response keys of the fields named `name` among `fields`. */
+const keysNamed = (fields, name) => fields.filter((f) => f.field === name).map((f) => f.key);
+
+/**
+ * Every connection `query` reads, by the path of response keys that leads to
+ * it (list positions left out): `{ "binItems": { nodes, edges, pageInfo,
+ * backward } }`, where `nodes` are the keys its entry lists answer under,
+ * `edges` each `{ key, cursor: [keys] }`, `pageInfo` each `{ key, fields: {
+ * hasNextPage: [keys], ... } }`, `backward` is true for a page read with
+ * `last` or `before` (a root field; a relation list pages forward only), and
+ * `first` is the page size the document asks for, or null. A
+ * connection is a field whose selection reads `nodes` or `edges`.
+ * `at` prefixes every path with where the answer holds the data (`data`).
+ * `null` when the document cannot be read or names no single operation.
+ */
+export function connectionsOf(query, variables, operationName, { at: prefix = "" } = {}) {
+  let parsed;
+  try {
+    parsed = parse(String(query));
+  } catch (error) {
+    if (error instanceof Unreadable || error instanceof SyntaxError) return null;
+    throw error;
+  }
+  const { operations, fragments } = parsed;
+  const operation = operationName ? operations.find((o) => o.name === operationName) : operations.length === 1 ? operations[0] : undefined;
+  if (!operation) return null;
+  const found = {};
+  const visit = (selections, path, depth) => {
+    // `path` is the prefix at depth 0, and each field's response key below it.
+    for (const field of fieldsOf(selections, fragments)) {
+      if (!field.selections.length) continue;
+      const at = path ? `${path}.${field.key}` : field.key;
+      const inner = fieldsOf(field.selections, fragments);
+      const nodes = keysNamed(inner, "nodes");
+      const edges = inner.filter((f) => f.field === "edges").map((f) => ({ key: f.key, cursor: keysNamed(fieldsOf(f.selections, fragments), "cursor") }));
+      if (nodes.length || edges.length) {
+        const arg = (name) => resolve(field.args[name], variables, operation.variables);
+        found[at] = {
+          nodes,
+          edges,
+          pageInfo: inner
+            .filter((f) => f.field === "pageInfo")
+            .map((f) => {
+              const pageFields = fieldsOf(f.selections, fragments);
+              return { key: f.key, fields: Object.fromEntries(PAGE_FIELDS.map((name) => [name, keysNamed(pageFields, name)])) };
+            }),
+          backward: depth === 0 && (arg("last") != null || arg("before") != null),
+          first: typeof arg("first") === "number" ? arg("first") : null,
+        };
+      }
+      visit(field.selections, at, depth + 1);
+    }
+  };
+  try {
+    visit(operation.selections, prefix, 0);
+  } catch (error) {
+    if (error instanceof Unreadable) return null;
+    throw error;
+  }
+  return found;
+}
+
+/** The fields a selection set writes itself, through inline fragments; a named fragment is shared, so it is left out. */
+function writtenFields(selections) {
+  return selections.flatMap((selection) => (selection.inline ? writtenFields(selection.inline) : selection.spread !== undefined ? [] : [selection]));
+}
+
+/**
+ * `query` reading on the relation list at `path` from `cursor`: that
+ * connection's `after` set, or replaced, where the document writes the field,
+ * or through its variable when the document passes `after` as one. `path` is
+ * response keys from the root field (`article.coauthors`). Returns `{ query,
+ * variables }`, or null when the document cannot be read or the list is not
+ * one field the operation writes once: a field inside a named fragment is
+ * shared by every place the fragment is spread, so it is never edited.
+ */
+export function withAfter(query, variables, operationName, path, cursor) {
+  let parsed;
+  try {
+    parsed = parse(String(query));
+  } catch (error) {
+    if (error instanceof Unreadable || error instanceof SyntaxError) return null;
+    throw error;
+  }
+  const { operations } = parsed;
+  const operation = operationName ? operations.find((o) => o.name === operationName) : operations.length === 1 ? operations[0] : undefined;
+  if (!operation) return null;
+  let found = [];
+  let level = operation.selections;
+  for (const key of path.split(".")) {
+    found = writtenFields(level).filter((field) => field.key === key);
+    if (!found.length) return null;
+    level = found.flatMap((field) => field.selections);
+  }
+  if (found.length !== 1) return null;
+  const { args, written } = found[0];
+  if (args.after && "variable" in args.after) return { query, variables: { ...(variables ?? {}), [args.after.variable]: cursor } };
+  const text = `after: ${JSON.stringify(cursor)}`;
+  const edited = args.after
+    ? query.slice(0, written.args.after.start) + text + query.slice(written.args.after.end)
+    : written.close !== null
+      ? `${query.slice(0, written.close)}, ${text}${query.slice(written.close)}`
+      : `${query.slice(0, written.nameEnd)}(${text})${query.slice(written.nameEnd)}`;
+  return { query: edited, variables };
+}

package/lib/graphql/filter-values.mjs

@@ -0,0 +1,92 @@
+/**
+ * filter-values.mjs — filter values as the scalar types the schema declares.
+ *
+ * GraphQL refuses a variable of the wrong type outright, and an agent writes
+ * a filter the way it reads: `{ "a_bool": { "has": "true" } }` on a list of
+ * true/false values, whose filter input the schema declares as
+ * `BooleanListFilter` (spec 17, amendment 59), is refused as written. So every
+ * filter `capa_graphql_build` sends is converted to the operand types its
+ * input declares: `"true"` goes as `true`, `"10"` on a number as `10`. A value
+ * that cannot be converted is left as written, and the API refuses it with its
+ * own message.
+ *
+ * THE SAME CONVERSION AS `@capacms/sdk`'s filter-values.ts, written again here
+ * because this package has no dependencies; the shared vector file pins both.
+ */
+
+const LIST_OPERATORS = new Set(["in", "nin", "hasAny", "hasAll"]);
+/** The operand types of a system filter (`IDFilter`, `DateTimeFilter`). */
+const SYSTEM_OPERANDS = {
+  eq: "String", ne: "String", lt: "String", lte: "String", gt: "String", gte: "String",
+  in: "String", nin: "String", exists: "Boolean", null: "Boolean",
+};
+const LOGIC_KEYS = new Set(["and", "or", "not"]);
+
+/** A JSON object: a filter, or one field's operators. */
+export const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** One operand as the GraphQL scalar `type`, when it reads as one. */
+function toScalar(type, value) {
+  switch (type) {
+    case "Float":
+    case "Int":
+      return typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value)) ? Number(value) : value;
+    case "Boolean":
+      return value === "true" ? true : value === "false" ? false : value;
+    case "String":
+    case "ID":
+    case "DateTime":
+      return typeof value === "number" || typeof value === "boolean" ? String(value) : value;
+    default:
+      return value;
+  }
+}
+
+/** One operand of `operator` as `type`; a list operand item by item. */
+function typedOperand(operator, value, type) {
+  if (value === null || value === undefined || !LIST_OPERATORS.has(operator)) return toScalar(type, value);
+  return (Array.isArray(value) ? value : [value]).map((item) => toScalar(type, item));
+}
+
+function typedOperations(operations, operands) {
+  return Object.fromEntries(Object.entries(operations).map(([op, value]) => [op, typedOperand(op, value, operands[op])]));
+}
+
+/** A relation's own operators typed, and each hop into its target typed by the target field's operands. */
+function typedRelation(operands, target, operations) {
+  const out = {};
+  for (const [name, value] of Object.entries(operations)) {
+    const hop = target?.fields.find((f) => f.name === name);
+    out[name] =
+      isObject(value) && (hop || name === "id")
+        ? typedOperations(value, hop ? hop.filterInputs ?? {} : SYSTEM_OPERANDS)
+        : typedOperand(name, value, operands[name]);
+  }
+  return out;
+}
+
+/**
+ * A `<Type>Filter` value with every operand converted to the type the schema
+ * declares for it: through `and`, `or` and `not`, on system keys and on every
+ * field, and one hop into a relation's target. Keys keep the order written.
+ */
+export function typedFilter(summary, model, filter) {
+  const out = {};
+  for (const [key, value] of Object.entries(filter)) {
+    if (LOGIC_KEYS.has(key)) {
+      const typed = (part) => (isObject(part) ? typedFilter(summary, model, part) : part);
+      out[key] = Array.isArray(value) ? value.map(typed) : typed(value);
+      continue;
+    }
+    if (!isObject(value)) {
+      out[key] = value;
+      continue;
+    }
+    const field = model.fields.find((f) => f.name === key);
+    if (!field) out[key] = typedOperations(value, model.systemFilters.find((system) => system.name === key)?.filterInputs ?? SYSTEM_OPERANDS);
+    else if (field.kind === "relation" || field.kind === "relationList") {
+      out[key] = typedRelation(field.filterInputs ?? {}, summary.models.find((m) => m.namespace === field.target), value);
+    } else out[key] = typedOperations(value, field.filterInputs ?? {});
+  }
+  return out;
+}

package/lib/graphql/more.mjs

@@ -0,0 +1,97 @@
+/**
+ * more.mjs — the relation lists in an answer that hold more entries than
+ * they show, and how to read on.
+ *
+ * A relation list inside an entry is a connection of its own, read `first`
+ * entries at a time (100 when the document gives no first, the API's
+ * default). Its pageInfo says whether more come next, but it sits deep in
+ * the answer, and a list whose document selected no pageInfo says nothing at
+ * all: bin-250 answered 100 of its 250 items, and nothing told the agent so.
+ * So the tools name each such list at the top of the answer.
+ *
+ * Reading on takes a one-entry read: the API pages a relation list with
+ * `after` only when every entry above it is one entry (the single root field,
+ * then single relations), since a cursor belongs to one entry's list. The
+ * entry to read is the one that holds the list, or, past single relations,
+ * the nearest entry above it in a list.
+ */
+import { NESTED_DEFAULT } from "./build.mjs";
+
+/** Lists named in full; the note counts the rest. */
+const LISTED = 5;
+
+const join = (path, key) => (typeof key === "number" ? `${path}[${key}]` : path ? `${path}.${key}` : key);
+const firstKey = (holder, keys) => keys.find((key) => holder?.[key] !== undefined);
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * Every relation list in `data` (the answer's data, found at `at`) that holds
+ * more than it shows, as `{ path, shown, endCursor?, pageInfo?, entry? }`:
+ * `hasNextPage` true, or, with no pageInfo selected (`pageInfo: false`), as
+ * many entries as its page. `connections` is connectionsOf(query, ..., { at
+ * }); a root connection is left out, since its pageInfo is at the top of the
+ * answer already. `entry` is the id of the entry to read on from, when the
+ * document selected it.
+ */
+export function relationsWithMore(data, connections, at) {
+  if (!connections || !isObject(data)) return [];
+  const found = [];
+  for (const [shape, connection] of Object.entries(connections)) {
+    const keys = shape.slice(at.length + 1).split(".");
+    if (keys.length < 2) continue;
+    // `holder` is the entry to read on from: the root single field's entry,
+    // then each element of a list (an edge's entry is under node).
+    const walk = (value, index, path, holder) => {
+      if (Array.isArray(value)) {
+        value.forEach((item, i) => walk(item, index, join(path, i), keys[index] === "node" ? holder : item));
+        return;
+      }
+      if (!isObject(value)) return;
+      if (index === keys.length) {
+        const more = moreOf(value, connection);
+        if (more) found.push({ path, ...more, ...(typeof holder?.id === "string" ? { entry: holder.id } : {}) });
+        return;
+      }
+      const key = keys[index];
+      const next = value[key];
+      if (next === undefined || next === null) return;
+      walk(next, index + 1, join(path, key), index === 0 || key === "node" ? next : holder);
+    };
+    walk(data, 0, at, null);
+  }
+  return found;
+}
+
+/** `{ shown, endCursor? }` when this connection holds more than it shows, else null. */
+function moreOf(holder, connection) {
+  const listKey = firstKey(holder, [...connection.nodes, ...connection.edges.map((edge) => edge.key)]);
+  const shown = Array.isArray(holder[listKey]) ? holder[listKey].length : 0;
+  const info = connection.pageInfo.map(({ key, fields }) => ({ value: holder[key], fields })).find(({ value }) => isObject(value));
+  const says = info && firstKey(info.value, info.fields.hasNextPage);
+  if (says !== undefined) {
+    if (info.value[says] !== true) return null;
+    const cursorKey = firstKey(info.value, info.fields.endCursor);
+    const endCursor = cursorKey !== undefined ? info.value[cursorKey] : undefined;
+    return { shown, ...(typeof endCursor === "string" ? { endCursor } : {}) };
+  }
+  // No pageInfo to ask: a full page may hide more.
+  const page = typeof connection.first === "number" ? connection.first : NESTED_DEFAULT;
+  return shown >= page ? { shown, pageInfo: false } : null;
+}
+
+/**
+ * The lists that fit `budget` characters, cursors included, in order; the
+ * first one without its cursor when even that does not fit.
+ */
+export function listedWithin(lists, budget) {
+  const kept = [];
+  for (const list of lists.slice(0, LISTED)) {
+    if (JSON.stringify([...kept, list]).length > budget) break;
+    kept.push(list);
+  }
+  if (!kept.length && lists.length) {
+    const { endCursor: _cursor, next: _next, ...bare } = lists[0];
+    kept.push(bare);
+  }
+  return kept;
+}