@salesforce/graphiti 10.10.2

package/src/intent/get-schema-with-priming.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { type GraphQLSchema } from "graphql";
+import { primeSchemaWithLock, type PrimeDeps } from "../lib/prime-schema.js";
+import { getSchema } from "../lib/walker.js";
+
+export interface SchemaWithPriming {
+	schema: GraphQLSchema;
+	instanceUrl: string;
+	primingNote?: string;
+}
+
+/**
+ * Resolve the schema for `orgAlias`, lazily priming the on-disk cache on miss.
+ *
+ * - Cache hit → `{ schema, instanceUrl }` only.
+ * - Cache miss + auth resolves → introspects, writes cache, returns
+ *   `{ schema, instanceUrl, primingNote: 'Note: Primed schema cache for "<org>" (took Nms)' }`.
+ *   Callers thread the note into their `ToolOutput.warnings[]` per FR-13.3.
+ * - Auth missing or introspection failure → throws (FR-13.5 / FR-13.6).
+ *
+ * The returned schema is loaded by instance URL (auth-free fast path), so the
+ * cost of `getSchema(prime.instanceUrl)` is just a Map lookup after the first
+ * call per process.
+ */
+export async function getSchemaWithPriming(
+	orgAlias: string,
+	deps?: PrimeDeps,
+): Promise<SchemaWithPriming> {
+	const prime = await primeSchemaWithLock(orgAlias, deps);
+	const schema = getSchema(prime.instanceUrl);
+	const base = { schema, instanceUrl: prime.instanceUrl };
+	return prime.cached
+		? base
+		: {
+				...base,
+				primingNote: `Note: Primed schema cache for "${orgAlias}" (took ${prime.durationMs}ms)`,
+			};
+}

package/src/intent/select-child-relationship.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { type GraphQLSchema } from "graphql";
+import { type ChildRelationshipSpec } from "./types.js";
+import { selectDottedFieldPath } from "../lib/path-selection.js";
+import { deepSetArg, type QuerySession } from "../lib/session.js";
+import { normalizeOrderBy, promoteVariables } from "../lib/variable-promotion.js";
+
+/**
+ * Render a UIAPI child relationship onto an existing query session as
+ * `<rel> { edges { node { ... } } }`, with optional `first` / `filter` /
+ * `orderBy` arguments on the connection. `$varName` leaves in `filter` and
+ * `orderBy` promote to typed query variables (same machinery as the top-level
+ * connection).
+ *
+ * Shared by `buildList` and `buildDetail`. Behavior is identical between
+ * callers — the connection node path is the only thing that varies.
+ */
+export function selectChildRelationship(
+	session: QuerySession,
+	schema: GraphQLSchema,
+	parentNodePath: string[],
+	child: ChildRelationshipSpec,
+): void {
+	const childConnectionPath = [...parentNodePath, child.relationshipName];
+	const childNodePath = [...childConnectionPath, "edges", "node"];
+
+	for (const field of child.fields) {
+		selectDottedFieldPath(session, schema, childNodePath, field);
+	}
+
+	if (child.first !== undefined) {
+		deepSetArg(session, childConnectionPath, "first", [], String(child.first));
+	}
+	if (child.filter) {
+		promoteVariables(session, schema, childConnectionPath, "where", child.filter);
+		deepSetArg(session, childConnectionPath, "where", [], JSON.stringify(child.filter));
+	}
+	const childOrderBy = normalizeOrderBy(child.orderBy);
+	if (childOrderBy) {
+		promoteVariables(session, schema, childConnectionPath, "orderBy", childOrderBy);
+		deepSetArg(session, childConnectionPath, "orderBy", [], JSON.stringify(childOrderBy));
+	}
+}

package/src/intent/types.ts

@@ -0,0 +1,181 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Shared envelope returned by every typed intent function. The MCP tool
+ * adapter JSON-stringifies this into the tool-call result; library
+ * consumers (CLI, eval harness) use it directly. Per FR-3 of the spec.
+ */
+export interface ToolOutput {
+	query: string;
+	variables: VariableInfo[];
+	types: string;
+	warnings: string[];
+}
+
+export interface VariableInfo {
+	name: string;
+	type: string;
+	required: boolean;
+	description?: string;
+}
+
+export interface ChildRelationshipSpec {
+	relationshipName: string;
+	fields: string[];
+	first?: number;
+	filter?: Record<string, unknown>;
+	orderBy?: Record<string, unknown> | Record<string, unknown>[];
+}
+
+export interface ListSpec {
+	org: string;
+	object: string;
+	fields: string[];
+	parentFields?: string[];
+	childRelationships?: ChildRelationshipSpec[];
+	filter?: Record<string, unknown>;
+	orderBy?: Record<string, unknown> | Record<string, unknown>[];
+	first?: number;
+	scope?: string;
+	operationName?: string;
+}
+
+export interface DetailSpec {
+	org: string;
+	object: string;
+	fields: string[];
+	parentFields?: string[];
+	childRelationships?: ChildRelationshipSpec[];
+	/** Variable name (without leading `$`) for the record Id; default `"id"`. Declared as `<name>: ID!` per FR-5.5. */
+	idVariable?: string;
+	/** GraphQL operation name; default `<Object>Detail`. */
+	operationName?: string;
+}
+
+export type AggregationFunction = "count" | "countDistinct" | "sum" | "avg" | "min" | "max";
+
+export const GROUP_BY_FUNCTIONS = [
+	"CALENDAR_MONTH",
+	"CALENDAR_QUARTER",
+	"CALENDAR_YEAR",
+	"DAY_IN_MONTH",
+	"DAY_IN_WEEK",
+	"DAY_IN_YEAR",
+	"FISCAL_MONTH",
+	"FISCAL_QUARTER",
+	"FISCAL_YEAR",
+	"HOUR_IN_DAY",
+	"CALENDAR_MONTH_IN_YEAR",
+	"FISCAL_MONTH_IN_YEAR",
+	"WEEK_IN_YEAR",
+] as const;
+
+export type GroupByFunction = (typeof GROUP_BY_FUNCTIONS)[number];
+
+export interface GroupByDateElement {
+	field: string;
+	function: GroupByFunction;
+}
+
+export type GroupByElement = string | GroupByDateElement;
+
+export interface AggregationSpec {
+	function: AggregationFunction;
+	field?: string;
+	alias?: string;
+}
+
+export interface AggregateSpec {
+	org: string;
+	object: string;
+	groupBy?: GroupByElement[];
+	aggregations?: AggregationSpec[];
+	filter?: Record<string, unknown>;
+	orderBy?: Record<string, unknown> | Record<string, unknown>[];
+	first?: number;
+	operationName?: string;
+}
+
+export type DiscoverMode = "list_objects" | "describe_object" | "describe_field";
+
+export interface DiscoverSpec {
+	org: string;
+	mode: DiscoverMode;
+	object?: string;
+	field?: string;
+	search?: string;
+}
+
+export interface FieldDescription {
+	name: string;
+	label: string;
+	type: string;
+	filterable: boolean;
+	sortable: boolean;
+	nameField: boolean;
+	compound: boolean;
+	defaultedOnCreate: boolean;
+	picklistValues?: string[];
+}
+
+export interface ObjectDescription {
+	name: string;
+	fields: FieldDescription[];
+	childRelationships: { relationshipName: string; childObject: string }[];
+	parentReferences: { field: string; targetObjects: string[] }[];
+	filterableFields: string[];
+	orderByExample: Record<string, unknown>;
+	requiredOnCreate: string[];
+}
+
+export type DiscoverOutput =
+	| {
+			mode: "list_objects";
+			objects: { name: string; label?: string }[];
+			warnings?: string[];
+	  }
+	| { mode: "describe_object"; object: ObjectDescription; warnings?: string[] }
+	| { mode: "describe_field"; field: FieldDescription; warnings?: string[] };
+
+export interface CreateSpec {
+	org: string;
+	object: string;
+	returnFields?: string[];
+	inputVariable?: string;
+	operationName?: string;
+}
+
+export interface UpdateSpec {
+	org: string;
+	object: string;
+	returnFields?: string[];
+	inputVariable?: string;
+	operationName?: string;
+}
+
+export interface DeleteSpec {
+	org: string;
+	object: string;
+	inputVariable?: string;
+	operationName?: string;
+}
+
+export type RawOperation = "query" | "mutation" | "aggregate";
+
+export interface RawSpec {
+	org: string;
+	/**
+	 * CLI-style commands applied in order to a transient session. v1 supports
+	 * `select <path[:alias]>`, `set [<path>] <key>=<value>`, and
+	 * `var $name <path> [default]`. See FR-12.
+	 */
+	commands: string[];
+	/** Operation root; default `"query"`. Sets the `createSession` operation. */
+	operation?: RawOperation;
+	/** Codegen type prefix / operation name override (FR-12.3). */
+	typeName?: string;
+}

package/src/lib/__tests__/apply-command.parity.spec.ts

@@ -0,0 +1,97 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildSchema, type GraphQLSchema } from "graphql";
+import { describe, expect, it } from "vitest";
+import { dispatchQueryCommand } from "../../commands/query.js";
+import { applyCommand } from "../apply-command.js";
+import { renderQuery } from "../query-builder.js";
+import { createSession, saveSession, loadSession } from "../session.js";
+import { primeSchemaCache } from "../walker.js";
+
+const SCHEMA: GraphQLSchema = buildSchema(`
+	type Query { uiapi: UIAPI! }
+	type UIAPI { query: RecordQuery! }
+	type RecordQuery {
+		Case(first: Int, after: String, where: Case_Filter, orderBy: Case_OrderBy): CaseConnection!
+	}
+	input Case_Filter { Status: PicklistOperators, Subject: StringOperators }
+	input Case_OrderBy { CreatedDate: OrderByClause }
+	input PicklistOperators { eq: String, ne: String, in: [String!] }
+	input StringOperators { eq: String, like: String }
+	input OrderByClause { order: Order! }
+	enum Order { ASC DESC }
+	type CaseConnection { edges: [CaseEdge!]!, pageInfo: PageInfo! }
+	type CaseEdge { node: Case! }
+	type PageInfo { hasNextPage: Boolean!, endCursor: String }
+	type Case { Id: ID!, Subject: StringValue, Status: StringValue }
+	type StringValue { value: String }
+`);
+
+const ORG = "test-parity";
+const ORG_URL = "https://test-parity.my.salesforce.com";
+primeSchemaCache(ORG, SCHEMA);
+primeSchemaCache(ORG_URL, SCHEMA);
+
+// Each case = a sequence of commands run through BOTH engines; we compare the
+// final rendered query. All set commands use an absolute field-path prefix
+// (raw sessions never `cd`, so prefix-less forms are out of scope by design).
+const CASES: { name: string; commands: string[] }[] = [
+	{ name: "select dotted leaf", commands: ["select uiapi/query/Case/edges/node/Subject/value"] },
+	{
+		name: "select with alias",
+		commands: ["select uiapi/query/Case/edges/node/Subject/value:subj"],
+	},
+	{
+		name: "select multiple leaves",
+		commands: ["select uiapi/query/Case/edges/node/Id uiapi/query/Case/edges/node/Subject/value"],
+	},
+	{ name: "set scalar arg", commands: ["set uiapi/query/Case first=5"] },
+	{ name: "set where shorthand → JSON", commands: ["set uiapi/query/Case where.Status=New"] },
+	{ name: "set where like on % wildcard", commands: ["set uiapi/query/Case where.Subject=Acme%"] },
+	{ name: "set orderBy shorthand", commands: ["set uiapi/query/Case orderBy=CreatedDate:DESC"] },
+	{
+		name: "set where=$var deferred binding",
+		commands: ["set uiapi/query/Case where.Status=$status"],
+	},
+	{ name: "set multiple specs", commands: ["set uiapi/query/Case first=5 where.Status=New"] },
+	{ name: "var declare+bind", commands: ["var $status uiapi/query/Case/@args/where/Status/eq"] },
+	{
+		name: "select + set + var sequence",
+		commands: [
+			"select uiapi/query/Case/edges/node/Subject/value",
+			"set uiapi/query/Case first=10",
+			"var $status uiapi/query/Case/@args/where/Status/eq",
+		],
+	},
+];
+
+function viaApplyCommand(commands: string[]): string {
+	const session = createSession(ORG, "query", ORG_URL);
+	for (const cmd of commands) applyCommand(session, SCHEMA, cmd);
+	return renderQuery(session);
+}
+
+async function viaDispatcher(commands: string[]): Promise<string> {
+	const session = createSession(ORG, "query", ORG_URL);
+	saveSession(session);
+	const id = session.id;
+	for (const cmd of commands) {
+		const [verb, ...rest] = cmd.split(/\s+/);
+		await dispatchQueryCommand(id, verb, rest, {});
+	}
+	return renderQuery(loadSession(id));
+}
+
+describe("lib/apply-command — parity with CLI dispatcher", () => {
+	for (const c of CASES) {
+		it(`renders identically: ${c.name}`, async () => {
+			const fromApply = viaApplyCommand(c.commands);
+			const fromDispatch = await viaDispatcher(c.commands);
+			expect(fromApply).toEqual(fromDispatch);
+		});
+	}
+});

package/src/lib/__tests__/apply-command.spec.ts

@@ -0,0 +1,171 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildSchema, type GraphQLSchema } from "graphql";
+import { describe, expect, it } from "vitest";
+import { applyCommand } from "../apply-command.js";
+import { renderQuery } from "../query-builder.js";
+import { createSession } from "../session.js";
+import { primeSchemaCache } from "../walker.js";
+
+const SCHEMA: GraphQLSchema = buildSchema(`
+	type Query { uiapi: UIAPI! }
+	type UIAPI { query: RecordQuery! }
+	type RecordQuery {
+		Case(first: Int, after: String, where: Case_Filter, orderBy: Case_OrderBy): CaseConnection!
+	}
+	input Case_Filter { Status: PicklistOperators, Subject: StringOperators }
+	input Case_OrderBy { CreatedDate: OrderByClause }
+	input PicklistOperators { eq: String, ne: String, in: [String!] }
+	input StringOperators { eq: String, like: String }
+	input OrderByClause { order: Order! }
+	enum Order { ASC DESC }
+	type CaseConnection { edges: [CaseEdge!]!, pageInfo: PageInfo! }
+	type CaseEdge { node: Case! }
+	type PageInfo { hasNextPage: Boolean!, endCursor: String }
+	type Case { Id: ID!, Subject: StringValue, Status: StringValue }
+	type StringValue { value: String }
+`);
+
+const ORG = "test-apply";
+const ORG_URL = `https://${ORG}.my.salesforce.com`;
+primeSchemaCache(ORG_URL, SCHEMA);
+
+describe("lib/apply-command — routing", () => {
+	it("throws on an unknown verb", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		expect(() => applyCommand(session, SCHEMA, "cd uiapi")).toThrow(/unknown command 'cd'/);
+	});
+
+	it("throws on an empty command", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		expect(() => applyCommand(session, SCHEMA, "   ")).toThrow(/empty command/);
+	});
+});
+
+describe("lib/apply-command — select", () => {
+	it("selects a dotted leaf path with { value } wrapper", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		applyCommand(session, SCHEMA, "select uiapi/query/Case/edges/node/Subject/value");
+		const q = renderQuery(session);
+		expect(q).toMatch(/Subject\s*\{\s*value\s*\}/);
+	});
+
+	it("selects multiple space-separated leaves in one command", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		applyCommand(
+			session,
+			SCHEMA,
+			"select uiapi/query/Case/edges/node/Id uiapi/query/Case/edges/node/Subject/value",
+		);
+		const q = renderQuery(session);
+		expect(q).toMatch(/\bId\b/);
+		expect(q).toMatch(/Subject\s*\{\s*value\s*\}/);
+	});
+
+	it("applies a :alias to a selected leaf", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		applyCommand(session, SCHEMA, "select uiapi/query/Case/edges/node/Subject/value:subj");
+		const q = renderQuery(session);
+		// Alias is applied to the leaf field (value), not to the parent (Subject)
+		expect(q).toMatch(/subj:\s*value/);
+	});
+
+	it("throws when no selectable item is supplied", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		expect(() => applyCommand(session, SCHEMA, "select")).toThrow();
+	});
+});
+
+describe("lib/apply-command — var", () => {
+	it("declares a variable with type inferred from the path and binds it", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		applyCommand(session, SCHEMA, "var $status uiapi/query/Case/@args/where/Status/eq");
+		const q = renderQuery(session);
+		// declared in the operation signature...
+		expect(q).toMatch(/\$status:\s*String/);
+		// ...and bound into the where arg.
+		expect(q).toMatch(/Status:\s*\{\s*eq:\s*\$status\s*\}/);
+	});
+
+	it("throws when no variable name is given", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		expect(() => applyCommand(session, SCHEMA, "var")).toThrow();
+	});
+});
+
+describe("lib/apply-command — set", () => {
+	it("sets a scalar arg via key=value with an absolute field path", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		applyCommand(session, SCHEMA, "set uiapi/query/Case first=5");
+		expect(renderQuery(session)).toMatch(/first:\s*5/);
+	});
+
+	it("expands where.Field=Value into a filter object", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		applyCommand(session, SCHEMA, "set uiapi/query/Case where.Status=New");
+		expect(renderQuery(session)).toMatch(/Status:\s*\{\s*eq:\s*"?New"?\s*\}/);
+	});
+
+	it("auto-detects the like operator on a % wildcard value", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		applyCommand(session, SCHEMA, "set uiapi/query/Case where.Subject=Acme%");
+		expect(renderQuery(session)).toMatch(/Subject:\s*\{\s*like:/);
+	});
+
+	it("expands orderBy=Field:DESC into an orderBy clause", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		applyCommand(session, SCHEMA, "set uiapi/query/Case orderBy=CreatedDate:DESC");
+		expect(renderQuery(session)).toMatch(/CreatedDate:\s*\{\s*order:\s*DESC\s*\}/);
+	});
+
+	it("binds where.Field=$var as a deferred variable", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		applyCommand(session, SCHEMA, "set uiapi/query/Case where.Status=$status");
+		const q = renderQuery(session);
+		expect(q).toMatch(/\$status:/);
+		expect(q).toMatch(/Status:\s*\{\s*eq:\s*\$status\s*\}/);
+	});
+
+	it("throws on a malformed set with no key=value", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		expect(() => applyCommand(session, SCHEMA, "set")).toThrow();
+	});
+});
+
+describe("lib/apply-command — set additional branches", () => {
+	it("accepts the legacy `set <path> <value>` pair form", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		// The pair-form branch passes the path verbatim to assignViaPath (no
+		// `query/` auto-prefix), so the path must carry the operation-root
+		// `query/` segment that resolveAliasSegments keys off — same form the
+		// CLI dispatcher's pair branch requires.
+		applyCommand(session, SCHEMA, "set query/uiapi/query/Case/@args/first 7");
+		expect(renderQuery(session)).toMatch(/first:\s*7/);
+	});
+
+	it("cursor shorthand declares $after and selects pageInfo", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		// `cursor` must be mixed with a key=value so the parser routes through the
+		// hasKeyValue branch (which captures the field prefix). A bare
+		// `set <prefix> cursor` falls into the pair-loop and errors in both this
+		// port and the canonical CLI dispatcher, so the realistic form is mixed.
+		applyCommand(session, SCHEMA, "set uiapi/query/Case first=5 cursor");
+		const q = renderQuery(session);
+		expect(q).toMatch(/\$after:\s*String/);
+		expect(q).toMatch(/after:\s*\$after/);
+		expect(q).toMatch(/hasNextPage/);
+		expect(q).toMatch(/endCursor/);
+	});
+
+	it("applies multiple specs in one set command", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		applyCommand(session, SCHEMA, "set uiapi/query/Case first=5 where.Status=New");
+		const q = renderQuery(session);
+		expect(q).toMatch(/first:\s*5/);
+		expect(q).toMatch(/Status:\s*\{\s*eq:\s*"?New"?\s*\}/);
+	});
+});