@salesforce/graphiti 10.20.2 → 10.21.0

package/src/schemas/__tests__/tool-adapter.spec.ts

@@ -0,0 +1,299 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import os from "node:os";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AuthError, SchemaError, UserInputError } from "../../lib/errors.js";
+import { SchemaRefreshError } from "../../lib/prime-schema.js";
+import { MutationContextError } from "../../lib/walker.js";
+import { classifyError, PATH_MARKERS, runTool } from "../tool-adapter.js";
+
+describe("schemas/tool-adapter — classifyError", () => {
+	describe("typed-marker routing (primary signal)", () => {
+		it("routes SchemaError to Schema", () => {
+			const r = classifyError(new SchemaError("No cached schema for org"));
+			expect(r.category).toBe("Schema");
+			expect(r.text).toBe("No cached schema for org");
+		});
+
+		it("routes SchemaRefreshError to Schema", () => {
+			const r = classifyError(
+				new SchemaRefreshError("refresh failed; keeping cache", {
+					instanceUrl: "https://x.my.salesforce.com",
+				}),
+			);
+			expect(r.category).toBe("Schema");
+			expect(r.text).toBe("refresh failed; keeping cache");
+		});
+
+		it("routes AuthError to Auth", () => {
+			const r = classifyError(new AuthError('Failed to get org info for "foo"'));
+			expect(r.category).toBe("Auth");
+			expect(r.text).toBe('Failed to get org info for "foo"');
+		});
+
+		it("routes MutationContextError to UserInput", () => {
+			const r = classifyError(
+				new MutationContextError("field X is not available in mutation results"),
+			);
+			expect(r.category).toBe("UserInput");
+			expect(r.text).toBe("field X is not available in mutation results");
+		});
+
+		// A typed marker wins even when its message would heuristically match a
+		// different category — e.g. a SchemaError whose text mentions a builder.
+		it("prefers the typed marker over a conflicting heuristic", () => {
+			const r = classifyError(new SchemaError("buildList: is not a valid GraphQL Name"));
+			expect(r.category).toBe("Schema");
+		});
+	});
+
+	describe("heuristic routing (untyped fallbacks)", () => {
+		it("classifies builder/GraphQL-Name failures as UserInput", () => {
+			expect(
+				classifyError(new Error("buildList: object 'Order Item' is not a valid GraphQL Name"))
+					.category,
+			).toBe("UserInput");
+			expect(
+				classifyError(new Error("buildAggregate: aggregation 'sum' requires a field (FR-8.3)"))
+					.category,
+			).toBe("UserInput");
+			expect(classifyError(new Error('Field "Bogus" not found on "Account".')).category).toBe(
+				"UserInput",
+			);
+		});
+
+		it("classifies untyped auth-shaped messages as Auth", () => {
+			expect(
+				classifyError(new Error('Missing accessToken or instanceUrl for "foo"')).category,
+			).toBe("Auth");
+			expect(classifyError(new Error("run `sf org login` first")).category).toBe("Auth");
+		});
+
+		it("classifies untyped schema-shaped messages as Schema", () => {
+			expect(classifyError(new Error("No cached schema for org foo")).category).toBe("Schema");
+			expect(classifyError(new Error("Introspection query returned errors")).category).toBe(
+				"Schema",
+			);
+		});
+
+		it("falls back to Internal for anything unrecognized", () => {
+			expect(classifyError(new Error("kaboom")).category).toBe("Internal");
+		});
+
+		it("handles a non-Error throw via String()", () => {
+			const r = classifyError("a bare string");
+			expect(r.category).toBe("Internal");
+			expect(r.text).toContain("a bare string");
+		});
+	});
+
+	describe("Internal sanitization (info-disclosure guard)", () => {
+		it("strips home dir + absolute repo paths and truncates the stack", () => {
+			const home = os.homedir();
+			const err = new Error(`boom at ${home}/secret/file.ts`);
+			err.stack = [
+				`Error: boom at ${home}/secret/file.ts`,
+				`    at fn (${home}/Development/webapps/packages/graphiti/src/lib/foo.ts:10:5)`,
+				`    at bar (/some/abs/node_modules/pkg/index.js:1:1)`,
+				`    at baz (${home}/x/y.ts:2:2)`,
+				`    at dropped (${home}/should/not/appear.ts:9:9)`,
+			].join("\n");
+
+			const r = classifyError(err);
+			expect(r.category).toBe("Internal");
+
+			// No local filesystem layout leaks to the host.
+			expect(r.text).not.toContain(home);
+			// Repo-absolute prefix is relativized to a package-relative path.
+			expect(r.text).toContain("packages/graphiti/src/lib/foo.ts");
+			expect(r.text).toContain("node_modules/pkg/index.js");
+			// Home-rooted frames keep a tilde marker instead of the absolute path.
+			expect(r.text).toContain("~/x/y.ts");
+			// Message line is sanitized too.
+			expect(r.text).toContain("boom at ~/secret/file.ts");
+			// Stack is truncated: the 4th-and-beyond frames are dropped.
+			expect(r.text).not.toContain("dropped");
+			expect(r.text.split("\n")).toHaveLength(4); // message + 3 frames
+		});
+
+		// N4 fix: assert relativization against a foreign (non-HOME) absolute path,
+		// so the test can't pass tautologically off the same os.homedir() the
+		// adapter captured.
+		it("relativizes a repo path under a foreign home, not just the test HOME", () => {
+			const err = new Error("boom");
+			err.stack = [
+				"Error: boom",
+				"    at fn (/home/someoneelse/ci/checkout/packages/graphiti/src/x.ts:1:1)",
+			].join("\n");
+			const r = classifyError(err);
+			expect(r.text).toContain("packages/graphiti/src/x.ts");
+			expect(r.text).not.toContain("/home/someoneelse");
+		});
+	});
+
+	describe("typed UserInput + heuristic anchoring (M3/M5)", () => {
+		it("routes UserInputError to UserInput (M3 — walker navigation is now typed)", () => {
+			expect(
+				classifyError(
+					new UserInputError('Type "X" is not a possible type of union Y. Allowed: A, B'),
+				).category,
+			).toBe("UserInput");
+			expect(
+				classifyError(new UserInputError('Type "X" does not implement interface Y. Allowed: A'))
+					.category,
+			).toBe("UserInput");
+		});
+
+		// M5: messages an earlier, looser heuristic would have mislabeled UserInput
+		// must stay Internal — otherwise a genuine internal bug is both miscategorized
+		// AND silently dropped from the stderr operator log.
+		it("keeps internal-shaped messages as Internal (no regex false-positives)", () => {
+			expect(classifyError(new Error('The "path" argument requires a string')).category).toBe(
+				"Internal",
+			);
+			expect(classifyError(new Error("Module not found on disk")).category).toBe("Internal");
+			expect(classifyError(new Error("Config must contain at least one entry")).category).toBe(
+				"Internal",
+			);
+			expect(classifyError(new Error("the usage is undocumented")).category).toBe("Internal");
+			expect(classifyError(new Error("Cannot index into the cache map")).category).toBe("Internal");
+		});
+
+		it("still classifies the real anchored UserInput shapes correctly (no false-negatives)", () => {
+			const userInput = [
+				"select requires at least one <path[:alias]>",
+				"var requires a name, e.g. var $id <path> [default]",
+				"set: usage is `set [<field-path>] <key>=<value> ...` or `set <path> <value>`",
+				'Field "Bogus" not found on type Account. Available: Id, Name',
+				'Field "x" not found on input type AccountInput. Available: Name',
+				'Cannot index into non-list type Account with "0".',
+				'sf_gql_discover mode "describe_field" requires "field".',
+				"buildAggregate: aggregation 'sum' requires a field (FR-8.3)",
+			];
+			for (const msg of userInput) {
+				expect(classifyError(new Error(msg)).category).toBe("UserInput");
+			}
+		});
+	});
+});
+
+describe("schemas/tool-adapter — path sanitization across all categories (M1/M6/H1)", () => {
+	const savedHome = process.env.GRAPHITI_HOME;
+	afterEach(() => {
+		if (savedHome === undefined) delete process.env.GRAPHITI_HOME;
+		else process.env.GRAPHITI_HOME = savedHome;
+	});
+
+	it("sanitizes a Schema error's embedded cache/lock path — verbatim categories are NOT exempt (M1)", () => {
+		// GRAPHITI_HOME outside the home dir (CI/shared mount) — the old home-only
+		// strip would have missed this; relativizing against schemaDir() catches it (H1).
+		process.env.GRAPHITI_HOME = "/srv/shared/graphiti";
+		const lock = "/srv/shared/graphiti/schemas/deadbeef.json.lock";
+		const r = classifyError(
+			new SchemaError(`Timed out waiting 420000ms for schema priming lock at ${lock}`),
+		);
+		expect(r.category).toBe("Schema");
+		expect(r.text).not.toContain("/srv/shared/graphiti");
+		expect(r.text).toContain(PATH_MARKERS.schemaCache);
+	});
+
+	it("sanitizes a home-rooted path embedded in an Auth error message (M1)", () => {
+		const home = os.homedir();
+		const r = classifyError(new AuthError(`Failed to get org info; see ${home}/.sfdx/alias.json`));
+		expect(r.category).toBe("Auth");
+		expect(r.text).not.toContain(home);
+		expect(r.text).toContain(`${PATH_MARKERS.home}/.sfdx/alias.json`);
+	});
+
+	it("redacts an unknown absolute path (/tmp, /var/folders) anywhere in the message (H1)", () => {
+		const r = classifyError(
+			new Error("kaboom while reading /var/folders/ab/cd/T/secret.json mid-flight"),
+		);
+		expect(r.category).toBe("Internal");
+		expect(r.text).not.toContain("/var/folders/ab/cd/T/secret.json");
+		expect(r.text).toContain(PATH_MARKERS.redacted);
+	});
+
+	it("does not mangle URLs (their path is not a filesystem path)", () => {
+		const r = classifyError(
+			new Error("posted to https://acme.my.salesforce.com/services/data/v59.0 and failed"),
+		);
+		expect(r.text).toContain("https://acme.my.salesforce.com/services/data/v59.0");
+	});
+
+	// Ciaran's blocker: U+2028/U+2029 are not escaped by JSON.stringify and trip a
+	// Claude.AI 408 (MCP TS SDK #2155). They must be stripped from the error text.
+	it("strips U+2028/U+2029 line separators from a classified error message", () => {
+		const r = classifyError(new SchemaError("No cached schema\u2028for org\u2029x"));
+		expect(r.category).toBe("Schema");
+		expect(r.text).not.toMatch(/[\u2028\u2029]/);
+		expect(r.text).toBe("No cached schemafor orgx");
+	});
+});
+
+describe("schemas/tool-adapter — runTool", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("returns a plain JSON text envelope on success (no isError)", async () => {
+		const result = await runTool(async () => ({ ok: true, n: 1 }));
+		expect(result.isError).toBeUndefined();
+		expect(result.content).toHaveLength(1);
+		expect(result.content[0]).toEqual({ type: "text", text: JSON.stringify({ ok: true, n: 1 }) });
+	});
+
+	// Ciaran's note: the SUCCESS envelope also serializes user/codegen output, which
+	// JSON.stringify won't escape — so runTool must strip U+2028/2029 there too.
+	it("strips U+2028/U+2029 from the success envelope (codegen output vector)", async () => {
+		const result = await runTool(async () => ({ types: "type X = {\u2028 a: string \u2029}" }));
+		expect(result.isError).toBeUndefined();
+		expect(result.content[0]?.text).not.toMatch(/[\u2028\u2029]/);
+		expect(result.content[0]?.text).toBe(JSON.stringify({ types: "type X = { a: string }" }));
+	});
+
+	it("prefixes each category in the isError envelope", async () => {
+		const cases: { throw: unknown; prefix: string }[] = [
+			{ throw: new MutationContextError("bad mutation field"), prefix: "UserInput: " },
+			{ throw: new AuthError("Failed to get org info"), prefix: "Auth: " },
+			{ throw: new SchemaError("No cached schema"), prefix: "Schema: " },
+			{ throw: new Error("kaboom"), prefix: "Internal: " },
+		];
+		for (const c of cases) {
+			const result = await runTool(async () => {
+				throw c.throw;
+			});
+			expect(result.isError).toBe(true);
+			expect(result.content[0]?.type).toBe("text");
+			expect(result.content[0]?.text.startsWith(c.prefix)).toBe(true);
+		}
+	});
+
+	it("logs the full Internal error to stderr but returns only the sanitized envelope", async () => {
+		const spy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+		const home = os.homedir();
+		const err = new Error(`internal boom at ${home}/private/x.ts`);
+		const result = await runTool(async () => {
+			throw err;
+		});
+
+		// Full error (with the real path) is logged off the stdio JSON-RPC channel.
+		expect(spy).toHaveBeenCalledWith("[graphiti-mcp] Internal tool error:", err);
+		// The returned envelope is sanitized.
+		expect(result.isError).toBe(true);
+		expect(result.content[0]?.text.startsWith("Internal: ")).toBe(true);
+		expect(result.content[0]?.text).not.toContain(home);
+	});
+
+	it("does not log non-Internal (expected) errors to stderr", async () => {
+		const spy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+		await runTool(async () => {
+			throw new AuthError("Failed to get org info");
+		});
+		expect(spy).not.toHaveBeenCalled();
+	});
+});

package/src/schemas/tool-adapter.ts

@@ -0,0 +1,165 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import os from "node:os";
+import { AuthError, SchemaError, UserInputError } from "../lib/errors.js";
+import { graphitiHome, schemaDir } from "../lib/introspect.js";
+import { SchemaRefreshError } from "../lib/prime-schema.js";
+import { MutationContextError } from "../lib/walker.js";
+
+/**
+ * Shared MCP tool adapter (W-22697673). Wraps an intent invocation so that any
+ * throw becomes a sanitized, category-prefixed error envelope instead of leaking
+ * a raw stack/file path to the MCP host. Categories (message prefix):
+ *  - `UserInput:` — bad agent input / spec violations (FR-8.3/8.4, GraphQL Name,
+ *                   walker navigation).
+ *  - `Auth:`      — credential resolution failures.
+ *  - `Schema:`    — introspection / priming / schema-build failures.
+ *  - `Internal:`  — everything else; message + a truncated stack (the full error
+ *                   is logged to stderr, off the stdio channel).
+ *
+ * Auth/Schema/UserInput are carried by typed markers (AuthError, SchemaError,
+ * SchemaRefreshError, UserInputError, MutationContextError) classified by
+ * `instanceof`; the message-shape heuristics below are a secondary fallback for
+ * untyped throws. The sanitized message is returned for EVERY category — not
+ * just Internal — because typed Auth/Schema errors embed cache/lock paths and
+ * wrapped jsforce/@salesforce/core causes embed `~/.sfdx/...` paths.
+ */
+
+export type ErrorCategory = "UserInput" | "Auth" | "Schema" | "Internal";
+
+interface ToolTextResult {
+	// Index signature mirrors the MCP SDK's CallToolResult so this is assignable
+	// to a registerTool handler's return type.
+	[key: string]: unknown;
+	content: { type: "text"; text: string }[];
+	isError?: boolean;
+}
+
+// UserInput failures thrown by the intent/lib layer that aren't already carried
+// by a typed error. Each alternative is anchored to (or contextualized by) the
+// actual emitting message so a generic Node/library error does NOT get
+// mislabeled UserInput (which would also hide it from the Internal stderr log).
+// New UserInput sites should prefer throwing `UserInputError` over extending this.
+const USER_INPUT_RE =
+	/(^build[A-Z]\w*:|^sf_gql_discover |^command \d+ \(|^empty command\b|^unknown command\b|^(?:select|set|var)\b.*\brequires\b|^set: usage is|is not a valid GraphQL Name|not found on (?:type|input type|field|any member of union)|not found on "|not found in schema|Cannot select field|Cannot apply an inline fragment|Cannot navigate into|Cannot index into non-list type|^Argument "|Empty field name|not supported in v1|Invalid org alias or username)/;
+
+// Defensive fallbacks in case a schema/auth failure ever reaches the adapter
+// untyped (the typed AuthError/SchemaError markers are the primary signal).
+const SCHEMA_RE =
+	/(No cached schema|Introspection query|Schema has no |did not return a __schema|Schema priming)/;
+const AUTH_RE = /(Failed to get org info|Missing accessToken or instanceUrl|sf org login)/;
+
+/**
+ * Markers substituted for redacted local paths. Exported as the single source of
+ * truth so tests assert against these constants instead of re-typing the literals
+ * (closes the drift between the sanitizer and its tests).
+ */
+export const PATH_MARKERS = {
+	schemaCache: "<schema-cache>",
+	graphitiHome: "<graphiti-home>",
+	home: "~",
+	redacted: "<path>",
+} as const;
+
+// Unicode line separators (U+2028/U+2029) are legal in JSON strings but are NOT
+// escaped by JSON.stringify; left raw in `content.text` they trip a Claude.AI 408
+// timeout (MCP TS SDK #2155). Strip them from every host-visible envelope.
+const LINE_SEPARATOR_RE = /[\u2028\u2029]/g;
+function stripLineSeparators(s: string): string {
+	return s.replace(LINE_SEPARATOR_RE, "");
+}
+
+/**
+ * Redact local filesystem layout from error text so the MCP host never sees the
+ * developer's home dir, OS username, repo checkout location, or schema-cache
+ * path (W-22697673 info-disclosure). Applied to every category's message.
+ */
+function sanitizePaths(s: string): string {
+	let out = stripLineSeparators(s).replace(/file:\/\//g, "");
+	// 1) Repo-internal: drop any absolute prefix before packages/ or node_modules/
+	//    so a frame relativizes to `packages/graphiti/...` regardless of checkout.
+	out = out.replace(/(?:\/[^\s/]+)+\/(?=packages\/|node_modules\/)/g, "");
+	// 2) Relativize known graphiti roots to stable, non-sensitive markers. Longest
+	//    first: schemaDir() is under graphitiHome() is (usually) under homedir().
+	//    Relativizing against schemaDir()/graphitiHome() — not just homedir() —
+	//    closes the leak when GRAPHITI_HOME lives outside the home dir (CI/shared mounts).
+	const roots: [string, string][] = (
+		[
+			[schemaDir(), PATH_MARKERS.schemaCache],
+			[graphitiHome(), PATH_MARKERS.graphitiHome],
+			[os.homedir(), PATH_MARKERS.home],
+		] as [string, string][]
+	)
+		.filter(([root]) => root.length > 1)
+		.sort((a, b) => b[0].length - a[0].length);
+	for (const [root, marker] of roots) out = out.split(root).join(marker);
+	// 3) Redact any remaining absolute path (POSIX or Windows) at a token boundary
+	//    — /tmp, /var/folders, a foreign user's home, etc. The leading-boundary
+	//    guard avoids mangling URLs, whose path follows a non-boundary char (":"/host).
+	out = out.replace(
+		/(^|[\s("'=])(?:[A-Za-z]:)?(?:[/\\][^\s:)"',\\]+){2,}/g,
+		(_m, pre: string) => `${pre}${PATH_MARKERS.redacted}`,
+	);
+	return out;
+}
+
+function truncatedStack(e: unknown): string[] {
+	if (!(e instanceof Error) || !e.stack) return [];
+	return e.stack
+		.split("\n")
+		.slice(1, 4) // first ~3 frames after the message line
+		.map((line) => sanitizePaths(line.trim()));
+}
+
+function categoryOf(e: unknown, message: string): ErrorCategory {
+	if (e instanceof SchemaRefreshError || e instanceof SchemaError) return "Schema";
+	if (e instanceof AuthError) return "Auth";
+	if (e instanceof UserInputError || e instanceof MutationContextError) return "UserInput";
+	if (USER_INPUT_RE.test(message)) return "UserInput";
+	if (AUTH_RE.test(message)) return "Auth";
+	if (SCHEMA_RE.test(message)) return "Schema";
+	return "Internal";
+}
+
+/** Classify a thrown error into a category + sanitized message text. */
+export function classifyError(e: unknown): { category: ErrorCategory; text: string } {
+	const message = e instanceof Error ? e.message : String(e);
+	const category = categoryOf(e, message);
+	const safeMessage = sanitizePaths(message);
+	if (category !== "Internal") return { category, text: safeMessage };
+
+	// Internal: unexpected. Attach a truncated, path-stripped stack for the host.
+	const frames = truncatedStack(e);
+	const text = frames.length
+		? `${safeMessage}\n${frames.map((f) => `  ${f}`).join("\n")}`
+		: safeMessage;
+	return { category, text };
+}
+
+/**
+ * Run an MCP tool's intent invocation. Returns the success envelope
+ * (`JSON.stringify(output)`) or a category-prefixed `{ isError: true }` envelope.
+ * Internal (unexpected) errors are additionally logged in full to stderr, which
+ * is separate from the stdio JSON-RPC channel, so operators keep the real stack.
+ */
+export async function runTool(fn: () => Promise<unknown>): Promise<ToolTextResult> {
+	try {
+		const output = await fn();
+		// Strip U+2028/2029 from the success envelope too: codegen/GraphQL output can
+		// carry them and JSON.stringify won't escape them (MCP TS SDK #2155).
+		return { content: [{ type: "text", text: stripLineSeparators(JSON.stringify(output)) }] };
+	} catch (e) {
+		const { category, text } = classifyError(e);
+		if (category === "Internal") {
+			console.error("[graphiti-mcp] Internal tool error:", e);
+		}
+		return {
+			isError: true,
+			content: [{ type: "text", text: stripLineSeparators(`${category}: ${text}`) }],
+		};
+	}
+}