@salesforce/graphiti 10.10.2

package/src/commands/__tests__/query.spec.ts

@@ -0,0 +1,137 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { describe, expect, it } from "vitest";
+import { TEST_SCHEMA, makeSession } from "../../__tests__/helpers/schema.js";
+import { captureStdout } from "../../__tests__/helpers/stdout.js";
+import { createSession, loadSession, saveSession } from "../../lib/session.js";
+import { clearSchemaCache, primeSchemaCache } from "../../lib/walker.js";
+import {
+	dispatchQueryCommand,
+	getSessionSchema,
+	resolveDirectoryPathInSession,
+	selectLeafInSession,
+} from "../query.js";
+
+describe("commands/query", () => {
+	describe("dispatchQueryCommand", () => {
+		it("routes help correctly", async () => {
+			const session = makeSession();
+			saveSession(session);
+
+			const output = await captureStdout(async () => {
+				await dispatchQueryCommand(session.id, "help", [], {});
+			});
+
+			expect(output.includes("pwd") || output.includes("select")).toBe(true);
+		});
+
+		it("routes unknown commands with an error message", async () => {
+			const session = makeSession();
+			saveSession(session);
+
+			await expect(dispatchQueryCommand(session.id, "zzz_unknown", [], {})).rejects.toThrow(
+				/Unknown subcommand/,
+			);
+		});
+
+		it("cd updates session navigation path", async () => {
+			const session = makeSession();
+			session.navigationPath = [];
+			saveSession(session);
+
+			await captureStdout(async () => {
+				await dispatchQueryCommand(session.id, "cd", ["query/viewer"], {});
+			});
+
+			const updated = loadSession(session.id);
+			expect(updated.navigationPath).toEqual(["query", "viewer"]);
+		});
+
+		it("select adds leaf to projection", async () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "viewer"];
+			saveSession(session);
+
+			await captureStdout(async () => {
+				await dispatchQueryCommand(session.id, "select", ["id"], {});
+			});
+
+			const updated = loadSession(session.id);
+			expect(updated.nodes.some((n) => n.kind === "field" && n.fieldName === "id")).toBe(true);
+		});
+	});
+
+	describe("resolveDirectoryPathInSession (cd)", () => {
+		it("resolves query/ prefix paths", () => {
+			const session = makeSession();
+			session.navigationPath = ["query"];
+
+			const resolved = resolveDirectoryPathInSession(session, "accounts");
+			expect(resolved).toEqual(["query", "accounts"]);
+		});
+
+		it("handles @args navigation", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts"];
+
+			const resolved = resolveDirectoryPathInSession(session, "@args");
+			expect(resolved).toEqual(["query", "accounts", "@args"]);
+		});
+
+		it("cd into @args input object fields", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts", "@args"];
+
+			const resolved = resolveDirectoryPathInSession(session, "where");
+			expect(resolved).toEqual(["query", "accounts", "@args", "where"]);
+		});
+
+		it("rejects scalar args as leaf", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts", "@args"];
+
+			expect(() => resolveDirectoryPathInSession(session, "first")).toThrow(
+				/Cannot cd into "first" — it is a scalar/,
+			);
+		});
+	});
+
+	describe("selectLeafInSession", () => {
+		it("leaf-only selection rejects non-leaf fields", () => {
+			const session = makeSession();
+			session.navigationPath = ["query"];
+
+			expect(() => selectLeafInSession(session, "viewer")).toThrow(/Cannot select "viewer"/);
+
+			session.navigationPath = ["query", "viewer"];
+			selectLeafInSession(session, "id");
+		});
+
+		it("select through union without brackets gives a helpful error", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "search"];
+
+			expect(() => selectLeafInSession(session, "name")).toThrow(
+				/Use inline fragment syntax: on:Account\/name/,
+			);
+		});
+	});
+
+	describe("getSessionSchema", () => {
+		it("resolves by session.instanceUrl", () => {
+			clearSchemaCache();
+			primeSchemaCache("https://o.my.salesforce.com", TEST_SCHEMA);
+			const session = createSession("o", "query", "https://o.my.salesforce.com");
+			expect(getSessionSchema(session)).toBe(TEST_SCHEMA);
+		});
+
+		it("throws when session has no instanceUrl", () => {
+			const session = createSession("o", "query");
+			expect(() => getSessionSchema(session)).toThrow(/instanceUrl/);
+		});
+	});
+});

package/src/commands/args.ts

@@ -0,0 +1,306 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import {
+	CommandError,
+	getSessionSchema,
+	walkerResultAtPath,
+	parsePathInput,
+	resolveAliasSegments,
+	pathPointsToArgs,
+	assignViaPath,
+	assignInArgsContext,
+	assignInVariablesContext,
+	inferTypeFromArgsPath,
+	printQuery,
+} from "./query-helpers.js";
+import {
+	loadSession,
+	saveSession,
+	syncFocusFromNavigationPath,
+	getNavigationContext,
+	isInArgsContext,
+	getArgsFieldPath,
+	getInputSubPath,
+	addVariable,
+	deepSetArg,
+	deepRemoveArg,
+	formatPath,
+	type QuerySession,
+} from "../lib/session.js";
+import { resolvePath } from "../lib/walker.js";
+
+export function queryAssign(
+	sessionId: string,
+	specs: { path: string; value: string }[],
+	setDefault = false,
+): void {
+	const session = loadSession(sessionId);
+	syncFocusFromNavigationPath(session);
+	const ctx = getNavigationContext(session.navigationPath);
+
+	for (const { path: dotPath, value } of specs) {
+		if (pathPointsToArgs(dotPath)) {
+			assignViaPath(session, dotPath, value);
+			console.log(`Assigned ${dotPath} = ${value}`);
+			continue;
+		}
+
+		const segments = dotPath.includes("/")
+			? dotPath.split("/")
+			: dotPath.includes(".")
+				? dotPath.split(".")
+				: [dotPath];
+
+		if (ctx === "variables") {
+			assignInVariablesContext(session, segments, value, setDefault);
+		} else if (isInArgsContext(session.navigationPath)) {
+			assignInArgsContext(session, segments, value);
+		} else if (ctx === "query") {
+			const normalizedDotPath = dotPath.replace(/\./g, "/");
+			assignViaPath(session, `@args/${normalizedDotPath}`, value);
+			const displayPath = segments.join(".");
+			console.log(`Assigned @args/${displayPath} = ${value}`);
+			continue;
+		} else {
+			throw new CommandError(
+				"The `assign` command works inside `@args/` or `/variables/`, or with a path containing `@args/`.\n" +
+					"Example: `assign @args/first 10` or `cd @args` first.",
+			);
+		}
+
+		const displayPath = segments.join(".");
+		console.log(`Assigned ${displayPath} = ${value}`);
+	}
+
+	saveSession(session);
+	console.log("");
+	printQuery(session);
+}
+
+export function queryUnassign(sessionId: string, rawPath: string): void {
+	const session = loadSession(sessionId);
+	syncFocusFromNavigationPath(session);
+
+	const normalized = rawPath.replace(/\./g, "/");
+	const _resolved: string[] = [];
+
+	let rawResolved = parsePathInput(session.navigationPath, normalized);
+	if (rawResolved.length > 0 && rawResolved[0] !== "query" && rawResolved[0] !== "variables") {
+		rawResolved = ["query", ...rawResolved];
+	}
+	rawResolved = resolveAliasSegments(session, rawResolved);
+
+	// Collect all candidate @args resolutions and try each until one succeeds.
+	// This handles both explicit @args paths and shorthand paths like
+	// "uiapi/query/Case/where/Status" → "uiapi/query/Case/@args/where/Status"
+	const candidates: string[][] = [];
+
+	if (isInArgsContext(rawResolved)) {
+		candidates.push(rawResolved);
+	}
+
+	// Try injecting @args/ at each possible position
+	const parts = normalized.split("/");
+	for (let i = parts.length - 1; i >= 1; i--) {
+		const fieldPath = parts.slice(0, i).join("/");
+		const argPath = parts.slice(i).join("/");
+		const candidate = parsePathInput(session.navigationPath, `${fieldPath}/@args/${argPath}`);
+		if (candidate.length > 0 && candidate[0] !== "query" && candidate[0] !== "variables") {
+			candidate.unshift("query");
+		}
+		if (isInArgsContext(candidate)) {
+			candidates.push(resolveAliasSegments(session, candidate));
+		}
+	}
+
+	// Fall back: try prepending @args/ to whole path (works when navigated into a field)
+	const withArgs = parsePathInput(session.navigationPath, `@args/${normalized}`);
+	if (isInArgsContext(withArgs)) {
+		candidates.push(withArgs);
+	}
+
+	if (candidates.length === 0) {
+		throw new CommandError(
+			`Path "${rawPath}" does not point into an @args/ directory. ` +
+				"Use a path like `@args/first` or `unassign first`.",
+		);
+	}
+
+	// Try each candidate — use the first one where data actually exists
+	let removed = false;
+	for (const candidate of candidates) {
+		const fieldSchemaPath = getArgsFieldPath(candidate);
+		const inputSubPath = getInputSubPath(candidate);
+
+		if (inputSubPath.length === 0) continue;
+
+		const argName = inputSubPath[0];
+		const inputPath = inputSubPath.slice(1);
+
+		if (deepRemoveArg(session, fieldSchemaPath, argName, inputPath)) {
+			removed = true;
+			break;
+		}
+	}
+
+	if (!removed) {
+		throw new CommandError(`No value set at "${rawPath}".`);
+	}
+
+	saveSession(session);
+	console.log(`Removed ${rawPath}.`);
+	console.log("");
+	printQuery(session);
+}
+
+export function queryDefine(sessionId: string, rest: string[]): void {
+	const session = loadSession(sessionId);
+	const varName = rest[0];
+	if (!varName) {
+		throw new CommandError(
+			"Usage: define $name <path> [default]\n  e.g. define $filter @args/where",
+		);
+	}
+	const cleanName = varName.replace(/^\$/, "");
+	const pathArg = rest[1];
+	const defaultValue = rest[2];
+
+	if (pathArg) {
+		defineAtPath(session, cleanName, pathArg, defaultValue);
+		saveSession(session);
+		console.log("");
+		printQuery(session);
+		return;
+	}
+
+	if (isInArgsContext(session.navigationPath)) {
+		defineFromCurrentArgsPosition(session, cleanName);
+		saveSession(session);
+		console.log("");
+		printQuery(session);
+		return;
+	}
+
+	const ctx = getNavigationContext(session.navigationPath);
+	if (ctx === "query") {
+		const schemaPath = getArgsFieldPath(session.navigationPath);
+		if (schemaPath.length > 0) {
+			const wr = walkerResultAtPath(session);
+			if (wr.args.length === 0) {
+				throw new CommandError(
+					"This field has no arguments. Provide a path: `define $name @args/<arg>`.",
+				);
+			}
+		}
+		throw new CommandError(
+			"Provide a path: `define $name @args/where` or `define $name Account/@args/first`.",
+		);
+	}
+
+	if (ctx === "variables") {
+		throw new CommandError(
+			"Provide a path to an argument: `define $name /query/uiapi/query/Account/@args/where`.",
+		);
+	}
+
+	throw new CommandError("Usage: define $name <path> [default]\n  e.g. define $filter @args/where");
+}
+
+function defineFromCurrentArgsPosition(session: QuerySession, cleanName: string): void {
+	const schema = getSessionSchema(session);
+	const fieldSchemaPath = getArgsFieldPath(session.navigationPath);
+	const inputSubPath = getInputSubPath(session.navigationPath);
+
+	if (inputSubPath.length === 0) {
+		throw new CommandError(
+			"At @args/ root. Specify which argument: `define $name first` or `define $name where`.",
+		);
+	}
+
+	const { inferredType, argName, argInputPath } = inferTypeFromArgsPath(
+		schema,
+		session.operation,
+		fieldSchemaPath,
+		inputSubPath,
+	);
+	addVariable(session, cleanName, inferredType);
+	deepSetArg(session, fieldSchemaPath, argName, argInputPath, `$${cleanName}`);
+
+	const pathDesc = inputSubPath.join(".");
+	console.log(`Defined $${cleanName}: ${inferredType}`);
+	console.log(`Auto-assigned: ${pathDesc} = $${cleanName}`);
+	console.log("Tip: use `undo` to remove this variable definition.");
+}
+
+// Exported for the MCP `sf_gql_raw` parser (lib/apply-command.ts), which needs the
+// pure var-define logic without queryDefine's disk load/save. Already pure — only
+// the `export` keyword is added.
+export function defineAtPath(
+	session: QuerySession,
+	cleanName: string,
+	rawPath: string,
+	defaultValue?: string,
+): void {
+	const schema = getSessionSchema(session);
+
+	const normalized =
+		rawPath.includes(".") && !rawPath.includes("/") ? rawPath.replace(/\./g, "/") : rawPath;
+
+	let resolved = parsePathInput(session.navigationPath, normalized);
+
+	if (resolved.length > 0 && resolved[0] !== "query" && resolved[0] !== "variables") {
+		resolved = ["query", ...resolved];
+	}
+
+	if (!isInArgsContext(resolved)) {
+		// For mutations, auto-inject @args/input if the path points to a mutation field
+		if (session.operation === "mutation") {
+			const withArgsInput = [...resolved, "@args", "input"];
+			if (isInArgsContext(withArgsInput)) {
+				resolved = withArgsInput;
+			} else {
+				throw new CommandError(
+					`Path "${rawPath}" does not point into an @args/ directory. ` +
+						`Hint: for mutations, use the path with /@args/input appended, e.g. \`${rawPath}/@args/input\`.`,
+				);
+			}
+		} else {
+			throw new CommandError(
+				`Path "${rawPath}" does not point into an @args/ directory. ` +
+					"Use a path like `@args/where` or `Account/@args/first`.",
+			);
+		}
+	}
+
+	const fieldSchemaPath = getArgsFieldPath(resolved);
+	const inputSubPath = getInputSubPath(resolved);
+
+	if (inputSubPath.length === 0) {
+		throw new CommandError(
+			"Path points to @args/ root. Specify a specific argument: e.g. `@args/where` or `@args/first`.",
+		);
+	}
+
+	const wr = resolvePath(schema, session.operation, fieldSchemaPath);
+	if (wr.args.length === 0) {
+		throw new CommandError(`Field at ${formatPath(fieldSchemaPath)} has no arguments.`);
+	}
+
+	const { inferredType, argName, argInputPath } = inferTypeFromArgsPath(
+		schema,
+		session.operation,
+		fieldSchemaPath,
+		inputSubPath,
+	);
+	addVariable(session, cleanName, inferredType, defaultValue);
+	deepSetArg(session, fieldSchemaPath, argName, argInputPath, `$${cleanName}`);
+
+	const pathDesc = inputSubPath.join(".");
+	console.log(`Defined $${cleanName}: ${inferredType}${defaultValue ? ` = ${defaultValue}` : ""}`);
+	console.log(`Auto-assigned: ${pathDesc} = $${cleanName}`);
+	console.log("Tip: use `undo` to remove this variable definition.");
+}