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

package/dist/next/graphql/selection.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectToSelection = selectToSelection;
+exports.graphqlToSelect = graphqlToSelect;
+/**
+ * selection.ts — a REST read as a typed-builder selection, and back.
+ *
+ * The SDK writes a read three ways: a REST `select` (`entries.list`), the
+ * tool spec (`{ model, fields, first, sort, filter }`, which
+ * `buildGraphQLQuery` prints and the Explorer and MCP builders share), and the
+ * typed builder's selection (`{ articles: { args, nodes: { ... } } }`, which
+ * `client.graphql.query` runs and `toTree` reads). `selectToGraphQL` writes a
+ * REST read as the tool spec and `selectToSelection` as a selection;
+ * `graphqlToSelect` takes either back to REST (G brief, npm item 4). Each goes
+ * through the tool spec, which checks every name.
+ *
+ * A selection written here names what `toTree` needs to answer exactly what
+ * REST answers: `id`, `model` and `status` on every entry, `pageInfo {
+ * hasNextPage endCursor }` on every relation list, and every media field REST
+ * returns.
+ */
+const plan_1 = require("./plan");
+const rest_1 = require("./rest");
+const typed_1 = require("./typed");
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** The system fields REST returns on every entry, whatever the select says. */
+const ALWAYS = new Set(["id", "model", "status"]);
+const PAGE_INFO = { hasNextPage: true, endCursor: true };
+// ------------------------------------------------ REST read to selection ---
+/** One entry's selection: id, model and status, then each planned field. */
+function entrySelection(fields) {
+    const out = { id: true, model: true, status: true };
+    for (const planned of fields) {
+        if (ALWAYS.has(planned.name))
+            continue;
+        const kind = planned.field?.kind;
+        if (!planned.children) {
+            out[planned.name] = true;
+        }
+        else if (kind === "media") {
+            out[planned.name] = Object.fromEntries(planned.children.map((child) => [child.name, true]));
+        }
+        else if (kind === "relationList") {
+            const args = {};
+            if (planned.first !== undefined)
+                args.first = planned.first;
+            if (planned.sort !== undefined)
+                args.sort = planned.sort;
+            if (planned.after !== undefined)
+                args.after = planned.after;
+            out[planned.name] = { ...(Object.keys(args).length ? { args } : {}), nodes: entrySelection(planned.children), pageInfo: { ...PAGE_INFO } };
+        }
+        else {
+            out[planned.name] = entrySelection(planned.children);
+        }
+    }
+    return out;
+}
+/**
+ * The typed-builder selection a REST read is equal to. `client.graphql.query`
+ * runs it, and `toTree` turns its result into the REST `data`:
+ *
+ *   const schema = await capa.graphqlSchema();
+ *   const selection = selectToSelection(schema, "articles", "title,author(name)", { sort: ["-views"], limit: 5 });
+ *   const { data } = await capa.graphql.query(selection);
+ *   const { articles } = toTree(data, selection, schema);
+ *   // deep-equal to (await capa.entries.list("articles", { select: "title,author(name)", sort: ["-views"], limit: 5 })).data
+ *
+ * It takes what `selectToGraphQL` takes and refuses what it refuses, with
+ * `CapaBuildError`. Built at run time, its result is untyped.
+ */
+function selectToSelection(summary, namespace, select, options = {}) {
+    const plan = (0, plan_1.planQuery)(summary, (0, rest_1.selectToGraphQL)(summary, namespace, select, options));
+    const entry = entrySelection(plan.fields);
+    if (plan.mode === "single") {
+        return { [plan.model.singleField]: { args: { id: plan.id }, ...entry } };
+    }
+    const args = {};
+    // REST's limit before a cursor is GraphQL's last (spec 17, amendment 55),
+    // and before=end is last with no before, the end of the list (amendment 132).
+    const fromEnd = plan.before === plan_1.END_OF_LIST;
+    if (fromEnd)
+        args.last = plan.first ?? plan_1.LIST_DEFAULT;
+    else if (plan.first !== undefined)
+        args[plan.before === undefined ? "first" : "last"] = plan.first;
+    if (plan.after !== undefined)
+        args.after = plan.after;
+    if (plan.before !== undefined && !fromEnd)
+        args.before = plan.before;
+    if (plan.sort !== undefined)
+        args.sort = plan.sort;
+    if (plan.filter !== undefined)
+        args.filter = plan.filter;
+    // A page read backward pages on back from its startCursor, as REST's page.prev.
+    const pageInfo = plan.before === undefined ? { ...PAGE_INFO } : { ...PAGE_INFO, hasPreviousPage: true, startCursor: true };
+    const root = { ...(Object.keys(args).length ? { args } : {}), nodes: entry, pageInfo };
+    if (plan.totalCount)
+        root.totalCount = true;
+    return { [plan.model.listField]: root };
+}
+// ------------------------------------------------ selection to REST read ---
+/** A connection's entry selection: `nodes`, or `edges { node }`. */
+function entriesOf(selection, name) {
+    if (isObject(selection.nodes))
+        return selection.nodes;
+    if (isObject(selection.edges) && isObject(selection.edges.node))
+        return selection.edges.node;
+    throw new plan_1.CapaBuildError(`${name} selects no entries: select nodes { ... }, or edges { node { ... } }`);
+}
+/** A level's `args`, refusing any not in `allowed`. */
+function argsOf(selection, allowed, name) {
+    const args = selection.args ?? {};
+    if (!isObject(args))
+        throw new plan_1.CapaBuildError(`args of ${name} must be an object`);
+    for (const key of Object.keys(args)) {
+        if (args[key] !== undefined && !allowed.includes(key)) {
+            throw new plan_1.CapaBuildError(`${key} on ${name} has no REST twin here. Its args: ${allowed.join(", ")}`, [], [...allowed]);
+        }
+    }
+    return args;
+}
+/** An entry's selection as tool-spec fields; the builder checks every name when the spec is planned. */
+function specFieldsOf(summary, model, selection) {
+    const fields = [];
+    for (const key of (0, typed_1.selectedKeys)(selection)) {
+        const value = selection[key];
+        const aliased = (0, typed_1.aliasedField)(value);
+        if (aliased !== undefined) {
+            throw new plan_1.CapaBuildError(`${key} aliases ${aliased} below the root field, and REST has one value per field: select ${aliased} under its own name`);
+        }
+        if (ALWAYS.has(key))
+            continue;
+        const field = model.fields.find((f) => f.name === key);
+        if (!isObject(value) || !field) {
+            fields.push(key);
+            continue;
+        }
+        const target = summary.models.find((m) => m.namespace === field.target);
+        if (field.kind === "media") {
+            fields.push({ field: key, fields: (0, typed_1.selectedKeys)(value) });
+        }
+        else if (field.kind === "relationList" && target) {
+            const args = argsOf(value, ["first", "sort", "after"], key);
+            const spec = { field: key, fields: specFieldsOf(summary, target, entriesOf(value, key)) };
+            if (args.first !== undefined)
+                spec.first = args.first;
+            // `sort: "name_ASC"` or `["name_ASC"]`: the plan takes either, and refuses more than one.
+            if (args.sort !== undefined)
+                spec.sort = args.sort;
+            // The plan refuses a cursor on a relation list outside a read of one entry, as the API does.
+            if (args.after !== undefined)
+                spec.after = args.after;
+            fields.push(spec);
+        }
+        else if (target) {
+            fields.push({ field: key, fields: specFieldsOf(summary, target, value) });
+        }
+        else {
+            fields.push({ field: key, fields: (0, typed_1.selectedKeys)(value) });
+        }
+    }
+    return fields;
+}
+function graphqlToSelect(summary, read) {
+    // A tool spec names its model; a selection's keys are root fields, each an object.
+    if (isObject(read) && typeof read.model === "string")
+        return (0, rest_1.specToSelect)(summary, read);
+    return selectionRequest(summary, read);
+}
+/** A selection's REST request: one model root field, a list or a single entry. */
+function selectionRequest(summary, selection) {
+    if (!isObject(selection))
+        throw new plan_1.CapaBuildError("graphqlToSelect needs a tool spec, { model: \"articles\", ... }, or a builder selection, { articles: { nodes: { ... } } }");
+    const roots = (0, typed_1.selectedKeys)(selection);
+    if (roots.length !== 1) {
+        throw new plan_1.CapaBuildError(`graphqlToSelect reads one model root field, and this selection has ${roots.length}: ${roots.join(", ") || "none"}`);
+    }
+    const value = selection[roots[0]];
+    // REST has no aliases: an alias root reads as the field it names.
+    const root = (0, typed_1.aliasedField)(value) ?? roots[0];
+    const list = summary.models.find((m) => m.listField === root);
+    const single = list ? undefined : summary.models.find((m) => m.singleField === root);
+    if ((!list && !single) || !isObject(value)) {
+        throw new plan_1.CapaBuildError(`${root} is not a model root field, so it has no REST read`, [], summary.models.flatMap((m) => [m.listField, m.singleField]));
+    }
+    if (single) {
+        const args = argsOf(value, ["id"], root);
+        const spec = { model: single.namespace, mode: "single", id: args.id, fields: specFieldsOf(summary, single, value) };
+        return (0, rest_1.specToSelect)(summary, spec);
+    }
+    const model = (0, plan_1.findModel)(summary, list.namespace);
+    const args = argsOf(value, ["first", "last", "after", "before", "sort", "filter"], root);
+    const spec = { model: model.namespace, fields: specFieldsOf(summary, model, entriesOf(value, root)) };
+    const first = args.first ?? args.last;
+    if (first !== undefined)
+        spec.first = first;
+    if (args.after !== undefined)
+        spec.after = args.after;
+    // GraphQL reads a null cursor as none, as Relay's first backward fetch sends it.
+    if (args.before !== undefined && args.before !== null)
+        spec.before = args.before;
+    // last with no cursor reads the end of the list: REST's before=end (spec 17, amendment 132).
+    else if (args.last !== undefined && args.last !== null)
+        spec.before = plan_1.END_OF_LIST;
+    if (args.sort !== undefined)
+        spec.sort = (Array.isArray(args.sort) ? args.sort : [args.sort]);
+    if (args.filter !== undefined)
+        spec.filter = args.filter;
+    if (value.totalCount === true)
+        spec.totalCount = true;
+    return (0, rest_1.specToSelect)(summary, spec);
+}

package/dist/next/graphql/sha256.d.ts

@@ -0,0 +1,13 @@
+/**
+ * sha256.ts — the hash a persisted query is stored under.
+ *
+ * Web Crypto when the runtime has it (browsers, edge runtimes, Node 19+), and a
+ * small pure implementation otherwise. The fallback exists instead of a
+ * `node:crypto` import because this entry point is also bundled for the
+ * browser and the edge, where a `node:` specifier fails the build, and Node 18
+ * (still inside `engines`) has no global `crypto`.
+ */
+/** SHA-256 of `bytes`, synchronously. Exported for tests. */
+export declare function sha256Pure(bytes: Uint8Array): string;
+/** Lowercase hex SHA-256 of the UTF-8 bytes of `text`. */
+export declare function sha256Hex(text: string): Promise<string>;

package/dist/next/graphql/sha256.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * sha256.ts — the hash a persisted query is stored under.
+ *
+ * Web Crypto when the runtime has it (browsers, edge runtimes, Node 19+), and a
+ * small pure implementation otherwise. The fallback exists instead of a
+ * `node:crypto` import because this entry point is also bundled for the
+ * browser and the edge, where a `node:` specifier fails the build, and Node 18
+ * (still inside `engines`) has no global `crypto`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256Pure = sha256Pure;
+exports.sha256Hex = sha256Hex;
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+function hex(bytes) {
+    let out = "";
+    for (const byte of bytes)
+        out += byte.toString(16).padStart(2, "0");
+    return out;
+}
+/** SHA-256 of `bytes`, synchronously. Exported for tests. */
+function sha256Pure(bytes) {
+    const bitLength = bytes.length * 8;
+    const padded = new Uint8Array(((bytes.length + 9 + 63) >> 6) << 6);
+    padded.set(bytes);
+    padded[bytes.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(bitLength / 0x100000000));
+    view.setUint32(padded.length - 4, bitLength >>> 0);
+    const h = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = view.getUint32(offset + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+            const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, hh] = h;
+        for (let i = 0; i < 64; i++) {
+            const t1 = (hh + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + w[i]) >>> 0;
+            const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h[0] += a;
+        h[1] += b;
+        h[2] += c;
+        h[3] += d;
+        h[4] += e;
+        h[5] += f;
+        h[6] += g;
+        h[7] += hh;
+    }
+    const out = new Uint8Array(32);
+    const outView = new DataView(out.buffer);
+    h.forEach((word, i) => outView.setUint32(i * 4, word));
+    return hex(out);
+}
+/** Lowercase hex SHA-256 of the UTF-8 bytes of `text`. */
+async function sha256Hex(text) {
+    const bytes = new TextEncoder().encode(text);
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle)
+        return hex(new Uint8Array(await subtle.digest("SHA-256", bytes)));
+    return sha256Pure(bytes);
+}

package/dist/next/graphql/summary.d.ts

@@ -0,0 +1,83 @@
+import { type CapaIntrospection } from "./introspection";
+export type GraphQLFieldKind = "scalar" | "media" | "json" | "relation" | "relationList" | "id" | "idList";
+export interface GraphQLFieldSummary {
+    /** The GraphQL field name, which differs from the namespace when N5 renamed it. */
+    name: string;
+    namespace: string;
+    capaType: string;
+    arrayType: string | null;
+    graphqlType: string;
+    kind: GraphQLFieldKind;
+    /** The related model's namespace, for a relation this key can read. */
+    target: string | null;
+    sortable: boolean;
+    /** The operators and one-hop fields its filter input accepts. */
+    filterOps: string[];
+    /**
+     * The GraphQL type of each of `filterOps`: `String` for `has` on a list of
+     * text or true/false values, `Boolean` for `exists`, `StringFilter` for a
+     * hop. What a REST filter value is converted to (`selectToGraphQL`).
+     */
+    filterInputs: Record<string, string>;
+    /** Why a later Capa-Version phases this field out, or null while it is current. */
+    deprecationReason: string | null;
+}
+/** A system field a model's filter takes (`id`, `createdAt`, `_tags`), with its operators as for a field. */
+export type GraphQLSystemFilterSummary = Pick<GraphQLFieldSummary, "name" | "filterOps" | "filterInputs">;
+export interface GraphQLModelSummary {
+    namespace: string;
+    typeName: string;
+    description: string;
+    listField: string;
+    singleField: string;
+    filterType: string;
+    /**
+     * The system fields `filterType` filters, in the order it declares them,
+     * each with its operators: `id`, `createdAt`, `updatedAt`, `publishedAt`
+     * and `_tags` on the API today (spec 17, amendment 56).
+     */
+    systemFilters: GraphQLSystemFilterSummary[];
+    sortType: string;
+    sortValues: string[];
+    fields: GraphQLFieldSummary[];
+    /**
+     * Namespaces of the model's fields the type leaves out, because their
+     * GraphQL names collide (N5): the description's `Not exposed:` line. REST
+     * still reads them, so a system key they shadow is `$`-named there too.
+     */
+    notExposed: string[];
+}
+/**
+ * `Q` is the `CapaQuery` type of the client that read the schema, when it was
+ * created with one: `toTree` reads the types from it. It is never a runtime
+ * value.
+ */
+export interface GraphQLSchemaSummary<Q = unknown> {
+    version: string;
+    models: GraphQLModelSummary[];
+    /**
+     * Namespaces of the models this key reads that GraphQL leaves out, because
+     * their type names would collide (N1): the `Query` description's
+     * `Models not exposed in GraphQL:` list. REST reads them at
+     * `/api/entries/<namespace>`.
+     */
+    restOnly: string[];
+    readonly __capaQuery?: Q;
+}
+export declare function modelNamespaceOf(description: string | null | undefined): string | null;
+/** A model's display name, the one the Capa admin shows: its description's first line without `(model <namespace>)`. */
+export declare function modelDisplayName(model: GraphQLModelSummary): string;
+/** The namespaces a model type's description lists as not exposed. */
+export declare function notExposedFields(description: string | null | undefined): string[];
+export declare function parseFieldDescription(description: string | null | undefined): {
+    namespace: string;
+    capaType: string;
+    arrayType: string | null;
+    target: string | null;
+} | null;
+/**
+ * Compact a `CapaIntrospection` answer. Models sorted by namespace. Pass the
+ * codegen'd `CapaQuery` as `Q` (`summarizeIntrospection<CapaQuery>(json)`) to
+ * type `toTree` with a schema read from a file.
+ */
+export declare function summarizeIntrospection<Q = unknown>(introspection: CapaIntrospection): GraphQLSchemaSummary<Q>;

package/dist/next/graphql/summary.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelNamespaceOf = modelNamespaceOf;
+exports.modelDisplayName = modelDisplayName;
+exports.notExposedFields = notExposedFields;
+exports.parseFieldDescription = parseFieldDescription;
+exports.summarizeIntrospection = summarizeIntrospection;
+/**
+ * summary.ts — a key's GraphQL schema, compacted to what a query builder needs.
+ *
+ * Every name here is READ from introspection, never computed: the API owns the
+ * naming rules (G plan N1 to N10), and a builder that re-derived `blogPosts`
+ * from `blog_posts` would drift from the server the first time a rule moved.
+ * The model namespace and Capa field type are not GraphQL concepts, so the API
+ * writes them into descriptions in fixed formats (N9), parsed here.
+ */
+const field_names_1 = require("../field-names");
+const introspection_1 = require("./introspection");
+/** N9: `<modelName> (model <namespace>)`, on the first line of a model type's description. */
+const MODEL_DESCRIPTION = /\(model ([^()\s]+)\)$/;
+/**
+ * N9: `Capa field <namespace>, type <type>[ of <arrayType>][, model <target>]`,
+ * on the description's last line. The lines above it are the field's label
+ * and an enum's options, for people (spec 17, amendment 49). The namespace is
+ * written as REST writes it, quoted when it holds a character REST's grammars
+ * use (`"price.usd"`, amendment 121), so it is read back before use.
+ */
+const FIELD_DESCRIPTION = /(?:^|\n)Capa field ("(?:[^"]|"")*"|[^,\s]+), type (\S+)(?: of (\S+))?(?:, model ([^,\s]+))?$/;
+/** N9: the second line of a model type's description, when N5 left fields out. */
+const NOT_EXPOSED = /^Not exposed: (.+)$/m;
+/** N9: the end of the `Query` description, when N1 left models out. */
+const MODELS_NOT_EXPOSED = /Models not exposed in GraphQL: ([^\n]+?)\.?$/m;
+/** The keys of a `<Type>Filter` that combine conditions rather than name a field. */
+const FILTER_LOGIC = new Set(["and", "or", "not"]);
+function modelNamespaceOf(description) {
+    const firstLine = (description ?? "").split("\n")[0];
+    return MODEL_DESCRIPTION.exec(firstLine)?.[1] ?? null;
+}
+/** A model's display name, the one the Capa admin shows: its description's first line without `(model <namespace>)`. */
+function modelDisplayName(model) {
+    return model.description.split("\n")[0].replace(/ \(model [^()]+\)$/, "") || model.namespace;
+}
+/** The namespaces of an N9 list line, each bare or quoted as REST writes it. */
+function namespaceList(line) {
+    if (!line)
+        return [];
+    const items = (0, field_names_1.splitOutside)(line[1], ",", { nested: false }) ?? line[1].split(",");
+    return items.map((item) => item.trim()).filter(Boolean).map((item) => (0, field_names_1.readName)(item) ?? item);
+}
+/** The namespaces a model type's description lists as not exposed. */
+function notExposedFields(description) {
+    return namespaceList(NOT_EXPOSED.exec(description ?? ""));
+}
+function parseFieldDescription(description) {
+    const match = FIELD_DESCRIPTION.exec(description ?? "");
+    const namespace = match ? (0, field_names_1.readName)(match[1]) : null;
+    if (!match || namespace === null)
+        return null;
+    return { namespace, capaType: match[2], arrayType: match[3] ?? null, target: match[4] ?? null };
+}
+function kindOf(field, types, modelTypes) {
+    const named = (0, introspection_1.namedType)(field.type);
+    const list = (0, introspection_1.isListType)(field.type);
+    if (named === "ID")
+        return list ? "idList" : "id";
+    if (named === "Media")
+        return "media";
+    if (named === "JSON")
+        return "json";
+    if (modelTypes.has(named))
+        return "relation";
+    if (named.endsWith("RelationConnection") && types.get(named)?.kind === "OBJECT")
+        return "relationList";
+    return "scalar";
+}
+/**
+ * Compact a `CapaIntrospection` answer. Models sorted by namespace. Pass the
+ * codegen'd `CapaQuery` as `Q` (`summarizeIntrospection<CapaQuery>(json)`) to
+ * type `toTree` with a schema read from a file.
+ */
+function summarizeIntrospection(introspection) {
+    const types = new Map(introspection.__schema.types.map((type) => [type.name, type]));
+    const query = types.get(introspection.__schema.queryType.name);
+    const roots = query?.fields ?? [];
+    const namespaceByType = new Map();
+    for (const type of introspection.__schema.types) {
+        if (type.kind !== "OBJECT")
+            continue;
+        const namespace = modelNamespaceOf(type.description);
+        if (namespace)
+            namespaceByType.set(type.name, namespace);
+    }
+    const modelTypes = new Set(namespaceByType.keys());
+    const models = [];
+    for (const [typeName, namespace] of namespaceByType) {
+        const list = roots.find((root) => (0, introspection_1.namedType)(root.type) === `${typeName}Connection` && root.args.some((arg) => arg.name === "first"));
+        const single = roots.find((root) => (0, introspection_1.namedType)(root.type) === typeName && root.args.some((arg) => arg.name === "id"));
+        if (!list || !single)
+            continue;
+        const filterType = (0, introspection_1.namedType)(list.args.find((arg) => arg.name === "filter")?.type ?? { kind: "", name: "" });
+        const sortType = (0, introspection_1.namedType)(list.args.find((arg) => arg.name === "sort")?.type ?? { kind: "", name: "" });
+        const sortValues = (types.get(sortType)?.enumValues ?? []).map((value) => value.name);
+        const filterFields = new Map((types.get(filterType)?.inputFields ?? []).map((input) => [input.name, input]));
+        const type = types.get(typeName);
+        const operandsOf = (name) => {
+            const input = filterFields.get(name);
+            const operands = input ? (types.get((0, introspection_1.namedType)(input.type))?.inputFields ?? []) : [];
+            return {
+                filterOps: operands.map((operand) => operand.name),
+                filterInputs: Object.fromEntries(operands.map((operand) => [operand.name, (0, introspection_1.namedType)(operand.type)])),
+            };
+        };
+        const fields = [];
+        for (const field of type.fields ?? []) {
+            const parsed = parseFieldDescription(field.description);
+            if (!parsed)
+                continue;
+            fields.push({
+                name: field.name,
+                namespace: parsed.namespace,
+                capaType: parsed.capaType,
+                arrayType: parsed.arrayType,
+                graphqlType: (0, introspection_1.printTypeRef)(field.type),
+                kind: kindOf(field, types, modelTypes),
+                target: parsed.target,
+                sortable: sortValues.includes(`${field.name}_ASC`),
+                ...operandsOf(field.name),
+                deprecationReason: field.isDeprecated ? field.deprecationReason ?? "No longer supported" : null,
+            });
+        }
+        const fieldNames = new Set(fields.map((field) => field.name));
+        models.push({
+            namespace,
+            typeName,
+            description: type.description ?? "",
+            listField: list.name,
+            singleField: single.name,
+            filterType,
+            systemFilters: [...filterFields.keys()]
+                .filter((name) => !FILTER_LOGIC.has(name) && !fieldNames.has(name))
+                .map((name) => ({ name, ...operandsOf(name) })),
+            sortType,
+            sortValues,
+            fields,
+            notExposed: notExposedFields(type.description),
+        });
+    }
+    models.sort((a, b) => (a.namespace < b.namespace ? -1 : a.namespace > b.namespace ? 1 : 0));
+    const restOnly = namespaceList(MODELS_NOT_EXPOSED.exec(query?.description ?? ""));
+    return { version: introspection.version ?? "", models, restOnly };
+}

package/dist/next/graphql/tree-layout.d.ts

@@ -0,0 +1,36 @@
+/**
+ * tree-layout.ts — the part of a key's schema `toTree` reads, small enough to
+ * ship in the code codegen writes.
+ *
+ * `toTree` needs to know, for each model, its root fields, and for each field
+ * whether it is a plain value under its own name or something to lay out: a
+ * field N5 renamed (`hero_image` is `hero-image` under REST's `fields`), a
+ * relation or a relation list to expand, a relation the key cannot read (an
+ * id), or media. A `GraphQLSchemaSummary` knows that, from one introspection
+ * request. `capa-codegen --graphql` knows it too, when it writes the types, so
+ * it writes it down as `capaTreeLayout`, and a server that imports it reads no
+ * schema at all before its first `toTree`.
+ */
+import type { GraphQLFieldSummary, GraphQLSchemaSummary } from "./summary";
+/** A field `toTree` lays out rather than copies, by its GraphQL `name`. */
+export type TreeLayoutField = Pick<GraphQLFieldSummary, "name" | "namespace" | "kind" | "target">;
+export interface TreeLayoutModel {
+    /** The model's namespace: each entry's `model`, and what a relation's `target` names. */
+    namespace: string;
+    listField: string;
+    singleField: string;
+    /** The fields that are not a plain value under their own name. Any other field is copied as it is. */
+    fields: ReadonlyArray<TreeLayoutField>;
+}
+/**
+ * What `toTree` reads of a schema. A `GraphQLSchemaSummary` is one, and so is
+ * the `capaTreeLayout` constant `capa-codegen --graphql` writes, typed with the
+ * codegen'd `CapaQuery` as `Q` so the tree is typed from the selection.
+ */
+export interface CapaTreeLayout<Q = unknown> {
+    readonly models: ReadonlyArray<TreeLayoutModel>;
+    /** The `CapaQuery` type the layout was written for. Never a runtime value. */
+    readonly __capaQuery?: Q;
+}
+/** The layout of a schema summary: every model, and only the fields `toTree` lays out. */
+export declare function treeLayoutOf(summary: GraphQLSchemaSummary): CapaTreeLayout;

package/dist/next/graphql/tree-layout.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.treeLayoutOf = treeLayoutOf;
+/** Whether `toTree` copies a field as it is: a scalar or JSON value under its own name. */
+function copiedAsIs(field) {
+    return (field.kind === "scalar" || field.kind === "json") && field.name === field.namespace;
+}
+/** The layout of a schema summary: every model, and only the fields `toTree` lays out. */
+function treeLayoutOf(summary) {
+    return {
+        models: summary.models.map((model) => ({
+            namespace: model.namespace,
+            listField: model.listField,
+            singleField: model.singleField,
+            fields: model.fields
+                .filter((field) => !copiedAsIs(field))
+                .map(({ name, namespace, kind, target }) => ({ name, namespace, kind, target })),
+        })),
+    };
+}