@salesforce/graphiti 10.10.2

package/src/lib/tokenize.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Split a command line into tokens, honoring single and double quotes.
+ * A quote only opens a quoted span at a token boundary (when `current` is
+ * empty); a quote char mid-token is kept literally. Shared by the CLI
+ * `chain` command and the MCP `sf_gql_raw` parser.
+ */
+export function tokenizeCommand(input: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let inSingle = false;
+	let inDouble = false;
+
+	for (const ch of input) {
+		if (ch === "'" && !inDouble) {
+			if (!inSingle && current.length > 0) {
+				current += ch;
+			} else {
+				inSingle = !inSingle;
+			}
+		} else if (ch === '"' && !inSingle) {
+			if (!inDouble && current.length > 0) {
+				current += ch;
+			} else {
+				inDouble = !inDouble;
+			}
+		} else if (ch === " " && !inSingle && !inDouble) {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+		} else {
+			current += ch;
+		}
+	}
+	if (current) tokens.push(current);
+	return tokens;
+}

package/src/lib/uiapi.ts

@@ -0,0 +1,176 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Salesforce UIAPI shape facts as a public library surface.
+ *
+ * The graphiti library below this module is GraphQL-generic — it knows
+ * about sessions, projection nodes, schema walking, and validation, but
+ * not about Salesforce. The MCP server above this module composes
+ * intent-shaped builders (`buildList`, `buildDetail`, etc.) that bake
+ * in product opinions like pagination defaults and mutation return
+ * shapes.
+ *
+ * In between, every consumer that targets Salesforce UIAPI ends up
+ * needing the same handful of facts: where the connection field lives,
+ * how mutation results are nested, when to unwrap a value wrapper,
+ * what the filter / orderBy / input type names look like. This module
+ * collects those facts so the MCP, the CLI, the eval harness, and any
+ * future surface can call into one place instead of re-discovering
+ * each convention.
+ *
+ * What belongs here:
+ *   - Path constructors for UIAPI's nested shapes.
+ *   - Type-shape detection (value wrappers).
+ *   - Naming conventions for filter / orderBy / mutation input types.
+ *
+ * What does NOT belong here:
+ *   - Pagination defaults, "always select Id on mutations", "$id: ID!"
+ *     conventions — those are MCP-specific opinions.
+ *   - Spec types (`ListSpec`, `DetailSpec`, etc.) — those are MCP tool
+ *     surface, not graphiti API.
+ *   - Schema priming, codegen packaging, warning filtering — those
+ *     wrap library output for the MCP's `ToolOutput` and live in MCP.
+ */
+
+import { isInterfaceType, isObjectType, type GraphQLSchema } from "graphql";
+import { type OperationType } from "./session.js";
+import { resolvePath } from "./walker.js";
+
+// ── Path constructors ─────────────────────────────────────────────────────────
+
+/** `["uiapi", "query", <object>]` — the connection field for an SObject. */
+export function connectionPath(object: string): string[] {
+	return ["uiapi", "query", object];
+}
+
+/**
+ * Given any UIAPI connection-field path, returns the per-record selection
+ * scope inside it (`[...connection, "edges", "node"]`). Works for top-level
+ * connections AND for nested child-relationship connections.
+ */
+export function connectionNodePath(connection: string[]): string[] {
+	return [...connection, "edges", "node"];
+}
+
+/**
+ * `["uiapi", "query", <object>, "edges", "node"]` — the per-record selection
+ * scope for a top-level list query. Composition of `connectionNodePath` +
+ * `connectionPath` for the common case.
+ */
+export function nodePath(object: string): string[] {
+	return connectionNodePath(connectionPath(object));
+}
+
+/**
+ * `[...connection, "pageInfo"]` — the cursor-pagination metadata path on
+ * any UIAPI connection field. Selecting fields here is a caller opinion;
+ * the path itself is a UIAPI fact.
+ */
+export function pageInfoPath(connection: string[]): string[] {
+	return [...connection, "pageInfo"];
+}
+
+/** `["uiapi", <object><Op>]` — the mutation field at the root of the operation. */
+export function mutationFieldPath(object: string, op: "Create" | "Update" | "Delete"): string[] {
+	return ["uiapi", `${object}${op}`];
+}
+
+/**
+ * `["uiapi", <object><Op>, "Record"]` — the per-record selection scope inside
+ * a mutation result. Delete returns no record, so this only applies to
+ * Create / Update.
+ */
+export function mutationRecordPath(object: string, op: "Create" | "Update"): string[] {
+	return [...mutationFieldPath(object, op), "Record"];
+}
+
+/** `["uiapi", "aggregate", <object>]` — the aggregate root for an SObject. */
+export function aggregatePath(object: string): string[] {
+	return ["uiapi", "aggregate", object];
+}
+
+// ── Type-shape detection ──────────────────────────────────────────────────────
+
+/**
+ * Returns true when the named type is a UIAPI value wrapper — an object
+ * (or interface) type whose name ends in `Value` and that exposes a
+ * `value` field (e.g. `StringValue`, `PicklistValue`, `DateTimeValue`).
+ *
+ * Callers use this to decide whether to select `field` directly or
+ * `field { value }`. The check is permissive enough to catch the full
+ * Salesforce wrapper family without false positives on unrelated
+ * `*Value`-named types — those would also need a `value` field to
+ * satisfy the second condition.
+ */
+export function isValueWrapperType(schema: GraphQLSchema, typeName: string): boolean {
+	if (!typeName.endsWith("Value")) return false;
+	const t = schema.getType(typeName);
+	if (!t) return false;
+	if (!isObjectType(t) && !isInterfaceType(t)) return false;
+	return Object.prototype.hasOwnProperty.call(t.getFields(), "value");
+}
+
+/**
+ * Resolves the path that should actually be selected for a single
+ * (non-dotted) scalar field on `basePath`. Encapsulates two UIAPI
+ * facts in one call:
+ *
+ *   - `Id` is a real scalar — return the path as-is.
+ *   - `Name`-shaped fields resolve to a value wrapper — append "value".
+ *   - Other shapes (raw scalars, leaves) — return the path as-is.
+ *
+ * Returns `null` when the path can't be resolved against the schema,
+ * letting the caller decide whether to throw, warn, or fall back. The
+ * helper deliberately does NOT call `selectLeaf` on the session — it
+ * returns the path so callers stay in control of the projection
+ * (alias handling, error reporting, etc.).
+ *
+ * For dotted paths that may traverse a polymorphic union, callers
+ * should use `selectDottedFieldPath` from `./path-selection.js`
+ * instead — that helper handles the union expansion AND calls into
+ * the equivalent of this resolver internally.
+ */
+export function resolveScalarSelectionPath(
+	schema: GraphQLSchema,
+	operation: OperationType,
+	basePath: string[],
+	fieldName: string,
+): string[] | null {
+	const fullPath = [...basePath, fieldName];
+	if (fieldName === "Id") return fullPath;
+
+	try {
+		const wr = resolvePath(schema, operation, fullPath);
+		if (wr.isLeaf) return fullPath;
+		if (isValueWrapperType(schema, wr.typeName)) return [...fullPath, "value"];
+		return fullPath;
+	} catch {
+		return null;
+	}
+}
+
+// ── Naming conventions ────────────────────────────────────────────────────────
+
+/** `<Object>_Filter` — the connection field's `where` input type name. */
+export function filterTypeName(object: string): string {
+	return `${object}_Filter`;
+}
+
+/** `<Object>_OrderBy` — the connection field's `orderBy` singleton input type name. */
+export function orderByTypeName(object: string): string {
+	return `${object}_OrderBy`;
+}
+
+/** `<Object>CreateInput` — the create mutation's `input` argument type name. */
+export function createInputTypeName(object: string): string {
+	return `${object}CreateInput`;
+}
+
+/** `<Object>UpdateInput` — the update mutation's `input` argument type name. */
+export function updateInputTypeName(object: string): string {
+	return `${object}UpdateInput`;
+}

package/src/lib/validator.ts

@@ -0,0 +1,143 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any -- graphiti traverses untyped schema/introspection JSON; see follow-up to replace with `unknown` + narrowing */
+
+import {
+	type GraphQLSchema,
+	type GraphQLInputObjectType,
+	parse,
+	validate,
+	isInputObjectType,
+	isEnumType,
+	isNonNullType,
+	getNamedType,
+} from "graphql";
+
+// ── Full query validation ────────────────────────────────────────────────────
+
+export interface ValidationError {
+	message: string;
+	locations?: { line: number; column: number }[];
+}
+
+/**
+ * Validates a complete GraphQL query string against a schema.
+ * Uses graphql-js's parse() + validate() for comprehensive checking.
+ */
+export function validateQuery(schema: GraphQLSchema, queryString: string): ValidationError[] {
+	let document;
+	try {
+		document = parse(queryString);
+	} catch (err: any) {
+		return [{ message: `Parse error: ${err.message}` }];
+	}
+
+	const errors = validate(schema, document);
+	return errors.map((e) => ({
+		message: e.message,
+		locations: e.locations?.map((l) => ({ line: l.line, column: l.column })),
+	}));
+}
+
+// ── Input type validation ────────────────────────────────────────────────────
+
+export interface InputValidationError {
+	path: string;
+	message: string;
+}
+
+/**
+ * Validates a JSON value against a named input type from the schema.
+ * Recursively checks field names, nested types, and basic type compatibility.
+ */
+export function validateInputValue(
+	schema: GraphQLSchema,
+	typeName: string,
+	value: unknown,
+): InputValidationError[] {
+	const type = schema.getType(typeName);
+	if (!type) {
+		return [{ path: "", message: `Type "${typeName}" not found in schema` }];
+	}
+
+	if (!isInputObjectType(type)) {
+		return [
+			{
+				path: "",
+				message: `"${typeName}" is not an input type (it's a ${type.astNode?.kind ?? "unknown"})`,
+			},
+		];
+	}
+
+	const errors: InputValidationError[] = [];
+	validateInputObject(schema, type, value, "", errors);
+	return errors;
+}
+
+function validateInputObject(
+	schema: GraphQLSchema,
+	type: GraphQLInputObjectType,
+	value: unknown,
+	path: string,
+	errors: InputValidationError[],
+): void {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		errors.push({
+			path: path || "(root)",
+			message: `Expected an object for ${type.name}, got ${typeof value}`,
+		});
+		return;
+	}
+
+	const fields = type.getFields();
+	const valueObj = value as Record<string, unknown>;
+
+	for (const key of Object.keys(valueObj)) {
+		if (!fields[key]) {
+			const available = Object.keys(fields).slice(0, 10).join(", ");
+			errors.push({
+				path: path ? `${path}.${key}` : key,
+				message: `Unknown field "${key}" on ${type.name}. Available: ${available}${Object.keys(fields).length > 10 ? "..." : ""}`,
+			});
+		}
+	}
+
+	for (const [fieldName, field] of Object.entries(fields)) {
+		const fieldPath = path ? `${path}.${fieldName}` : fieldName;
+		const fieldValue = valueObj[fieldName];
+
+		if (fieldValue === undefined) {
+			if (isNonNullType(field.type) && field.defaultValue === undefined) {
+				errors.push({ path: fieldPath, message: `Required field "${fieldName}" is missing` });
+			}
+			continue;
+		}
+
+		const namedType = getNamedType(field.type);
+		if (
+			namedType &&
+			isInputObjectType(namedType) &&
+			typeof fieldValue === "object" &&
+			fieldValue !== null
+		) {
+			if (Array.isArray(fieldValue)) {
+				fieldValue.forEach((item, i) => {
+					validateInputObject(schema, namedType, item, `${fieldPath}[${i}]`, errors);
+				});
+			} else {
+				validateInputObject(schema, namedType, fieldValue, fieldPath, errors);
+			}
+		} else if (namedType && isEnumType(namedType) && typeof fieldValue === "string") {
+			const validValues = namedType.getValues().map((v) => v.name);
+			if (!validValues.includes(fieldValue)) {
+				errors.push({
+					path: fieldPath,
+					message: `Invalid enum value "${fieldValue}" for ${namedType.name}. Valid: ${validValues.join(", ")}`,
+				});
+			}
+		}
+	}
+}

package/src/lib/variable-promotion.ts

@@ -0,0 +1,145 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Library helpers that close two correctness gaps in any consumer
+ * (CLI, MCP intent layer, eval harness) that turns a typed JSON spec
+ * into a GraphQL operation:
+ *
+ *   - `promoteVariables` finds `$varName` string leaves anywhere in
+ *     a filter / orderBy / scope value, infers each one's GraphQL
+ *     type from the schema, and registers it on the session so the
+ *     rendered operation declares the variables it references.
+ *
+ *   - `normalizeOrderBy` collapses an array-shaped orderBy input to
+ *     a singleton object, matching Salesforce's connection-field
+ *     `<Object>_OrderBy` schema. Tolerating the array shape is
+ *     necessary for clients (and earlier MCP versions) that inferred
+ *     a list type.
+ *
+ * Both are pure (or session-mutating but otherwise pure) and have no
+ * dependency on the MCP server, the CLI, or any I/O. They live next
+ * to `path-selection.ts` as the second piece of the "what every
+ * graphiti consumer needs" library surface.
+ */
+
+import { type GraphQLSchema } from "graphql";
+import { addVariable, type QuerySession } from "./session.js";
+import { inferTypeFromArgsPath } from "../commands/query-helpers.js";
+
+const VAR_PLACEHOLDER_RE = /^\$([A-Za-z_][\w]*)$/;
+
+/**
+ * Recursively walks `value` looking for `$varName` string leaves. For
+ * each one, infers the GraphQL type at that input path via
+ * `inferTypeFromArgsPath` and calls `addVariable(session, name, type)`.
+ * Promoted variables strip a trailing `!` (query variables are
+ * nullable by convention; callers requiring NonNull use the `var`
+ * command directly).
+ *
+ * If type inference throws — for example because the input path
+ * doesn't exist on the schema — the helper falls back to `String`
+ * rather than failing the whole render. A wrong-type variable is
+ * easier for a user to debug than a hard error before they see their
+ * query.
+ *
+ * @param session         Session to add variables to.
+ * @param schema          The loaded GraphQL schema.
+ * @param fieldSchemaPath Path of the field whose argument we are
+ *                        promoting against (e.g. `["uiapi", "query",
+ *                        "Account"]`).
+ * @param argName         The argument name (`"where"`, `"orderBy"`,
+ *                        `"scope"`).
+ * @param value           The argument value — can be a primitive,
+ *                        array, or nested object.
+ * @param warnings        Optional warnings sink. Strings starting with
+ *                        `$` that don't form a valid GraphQL Name
+ *                        (e.g. `$1var`, `$foo-bar`) push a warning
+ *                        here so callers see the typo instead of
+ *                        silently rendering the literal.
+ */
+export function promoteVariables(
+	session: QuerySession,
+	schema: GraphQLSchema,
+	fieldSchemaPath: string[],
+	argName: string,
+	value: unknown,
+	warnings?: string[],
+): void {
+	walk(session, schema, fieldSchemaPath, argName, value, [], warnings);
+}
+
+function walk(
+	session: QuerySession,
+	schema: GraphQLSchema,
+	fieldSchemaPath: string[],
+	argName: string,
+	value: unknown,
+	pathInsideArg: string[],
+	warnings: string[] | undefined,
+): void {
+	if (typeof value === "string") {
+		const m = VAR_PLACEHOLDER_RE.exec(value);
+		if (!m || !m[1]) {
+			if (value.startsWith("$") && warnings) {
+				const argPath = [argName, ...pathInsideArg].join(".");
+				warnings.push(
+					`Variable: '${value}' at '${argPath}' starts with '$' but is not a valid variable placeholder; rendered as a literal string. Variable names must match /^[A-Za-z_][A-Za-z0-9_]*$/.`,
+				);
+			}
+			return;
+		}
+		const varName = m[1];
+		try {
+			const { inferredType } = inferTypeFromArgsPath(schema, session.operation, fieldSchemaPath, [
+				argName,
+				...pathInsideArg,
+			]);
+			const declared = inferredType.endsWith("!") ? inferredType.slice(0, -1) : inferredType;
+			addVariable(session, varName, declared);
+		} catch {
+			addVariable(session, varName, "String");
+		}
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) {
+			walk(
+				session,
+				schema,
+				fieldSchemaPath,
+				argName,
+				value[i],
+				[...pathInsideArg, String(i)],
+				warnings,
+			);
+		}
+		return;
+	}
+	if (value && typeof value === "object") {
+		for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+			walk(session, schema, fieldSchemaPath, argName, v, [...pathInsideArg, k], warnings);
+		}
+	}
+}
+
+/**
+ * Collapses an array-shaped orderBy input to its first element, so
+ * callers can pass either shape without knowing Salesforce's
+ * connection-field schema requires a singleton `<Object>_OrderBy`.
+ *
+ * - `[{Name: "ASC"}, ...]`  → `{Name: "ASC"}`
+ * - `[]`                    → `undefined`
+ * - `{Name: "ASC"}`         → unchanged
+ * - `undefined`             → `undefined`
+ */
+export function normalizeOrderBy<T>(orderBy: T | T[] | undefined): T | undefined {
+	if (orderBy === undefined) return undefined;
+	if (Array.isArray(orderBy)) {
+		return orderBy.length > 0 ? orderBy[0] : undefined;
+	}
+	return orderBy;
+}