@salesforce/graphiti 10.10.2 → 10.11.0

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

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { buildSchema } from "graphql";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { makeNoopPrimeDeps } from "../../__tests__/helpers/prime-deps.js";
+import { captureStdout } from "../../__tests__/helpers/stdout.js";
+import { schemaCacheKeyForInstanceUrl, schemaDir } from "../../lib/introspect.js";
+import { type PrimeDeps, SchemaRefreshError } from "../../lib/prime-schema.js";
+import { connectCommand } from "../connect.js";
+
+const ORG = "test-connect-cli";
+const ORG_URL = "https://test-connect-cli.my.salesforce.com";
+const SCHEMA = buildSchema(`type Query { x: Int }`);
+
+describe("commands/connect", () => {
+	let tmpRoot: string;
+
+	beforeEach(() => {
+		tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-cmd-connect-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+	});
+
+	afterEach(() => {
+		delete process.env.GRAPHITI_HOME;
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	function schemaFile(): string {
+		return path.join(schemaDir(), `${schemaCacheKeyForInstanceUrl(ORG_URL)}.json`);
+	}
+
+	it("--refresh routes through the shared path and clears the on-disk ObjectInfo cache", async () => {
+		const deps = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+		await captureStdout(() => connectCommand(ORG, {}, deps)); // initial prime
+
+		// Seed an ObjectInfo disk cache entry for this org — the stale data a
+		// refresh must clear (the bug this story fixes).
+		const oiDir = path.join(tmpRoot, "cache", "objectInfos", ORG);
+		fs.mkdirSync(oiDir, { recursive: true });
+		fs.writeFileSync(path.join(oiDir, "Account.json"), "{}");
+		expect(fs.existsSync(oiDir)).toBe(true);
+
+		const out = await captureStdout(() => connectCommand(ORG, { refresh: true }, deps));
+		expect(fs.existsSync(oiDir)).toBe(false); // cleared by the refresh
+		expect(out).toMatch(/Refreshed test-connect-cli/);
+	});
+
+	it("--refresh failure throws SchemaRefreshError and keeps the cached schema", async () => {
+		const good = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+		await captureStdout(() => connectCommand(ORG, {}, good)); // prime a real cache
+
+		const before = fs.readFileSync(schemaFile(), "utf-8");
+		const failing: PrimeDeps = {
+			getOrgAuth: good.getOrgAuth,
+			downloadSchema: async () => {
+				throw new Error("introspection failed");
+			},
+		};
+
+		await expect(
+			captureStdout(() => connectCommand(ORG, { refresh: true }, failing)),
+		).rejects.toBeInstanceOf(SchemaRefreshError);
+
+		// The previously cached schema is left intact.
+		expect(fs.readFileSync(schemaFile(), "utf-8")).toBe(before);
+	});
+
+	it("connect without --refresh on a cached org reports 'already cached' and does not download", async () => {
+		const good = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+		await captureStdout(() => connectCommand(ORG, {}, good)); // prime
+
+		let downloadCalls = 0;
+		const counting: PrimeDeps = {
+			getOrgAuth: good.getOrgAuth,
+			downloadSchema: async (a) => {
+				downloadCalls++;
+				return good.downloadSchema(a);
+			},
+		};
+
+		const out = await captureStdout(() => connectCommand(ORG, {}, counting));
+		expect(out).toMatch(/already cached/);
+		expect(downloadCalls).toBe(0);
+	});
+});

package/src/commands/connect.ts

@@ -5,18 +5,23 @@
  */
 
 import { getOrgAuth } from "../lib/auth.js";
-import { downloadSchema, getSchemaMetadata } from "../lib/introspect.js";
+import { getSchemaMetadata } from "../lib/introspect.js";
+import { type PrimeDeps, primeSchemaWithLock } from "../lib/prime-schema.js";
 
 export async function connectCommand(
 	orgAlias: string,
 	opts: { refresh?: boolean } = {},
+	deps?: PrimeDeps,
 ): Promise<void> {
+	const getAuth = deps?.getOrgAuth ?? getOrgAuth;
 	console.log(`Connecting to ${orgAlias}...`);
 
-	const auth = await getOrgAuth(orgAlias);
+	const auth = await getAuth(orgAlias);
 	console.log(`Authenticated as ${auth.username} on ${auth.instanceUrl}`);
 
 	if (!opts.refresh) {
+		// Resolve via the already-resolved instance URL (not the alias) so we
+		// don't trigger a second org resolution, and so injected deps stay honored.
 		const existing = getSchemaMetadata(auth.instanceUrl);
 		if (existing) {
 			const age = formatSchemaAge(new Date(existing.downloadedAt));
@@ -26,21 +31,38 @@ export async function connectCommand(
 		}
 	}
 
-	console.log("Downloading GraphQL schema via introspection...");
+	const verb = opts.refresh ? "Refreshing" : "Downloading";
+	console.log(`${verb} GraphQL schema via introspection...`);
 	const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 	let i = 0;
 	const startTime = Date.now();
 	const spinner = setInterval(() => {
 		const elapsed = ((Date.now() - startTime) / 1000).toFixed(0);
-		process.stderr.write(`\r${frames[i++ % frames.length]} Downloading schema... (${elapsed}s)`);
+		process.stderr.write(`\r${frames[i++ % frames.length]} ${verb} schema... (${elapsed}s)`);
 	}, 100);
 
 	try {
-		const meta = await downloadSchema(auth);
+		// Route through the shared priming layer so a refresh coherently clears
+		// all three caches (introspection JSON, in-memory schema, ObjectInfo) and
+		// coalesces with any concurrent CLI/MCP refresh. A failed refresh throws
+		// SchemaRefreshError (kept caches + staleness message), surfaced by cli.ts.
+		const result = await primeSchemaWithLock(orgAlias, deps, { forceRefresh: !!opts.refresh });
 		clearInterval(spinner);
 		process.stderr.write("\r");
 		const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
-		console.log(`Connected to ${orgAlias}. Schema cached: ${meta.typeCount} types (${elapsed}s).`);
+		// `result.typeCount` is set on the download path; a coalesced refresh
+		// (no download performed here) falls back to a one-time metadata read.
+		const typeCount = result.typeCount ?? getSchemaMetadata(auth.instanceUrl)?.typeCount ?? 0;
+		if (opts.refresh && !result.refreshed) {
+			// A concurrent refresh produced the new schema while we waited.
+			console.log(
+				`Schema for ${orgAlias} was just refreshed by a concurrent process: ${typeCount} types.`,
+			);
+		} else if (opts.refresh) {
+			console.log(`Refreshed ${orgAlias}. Schema cached: ${typeCount} types (${elapsed}s).`);
+		} else {
+			console.log(`Connected to ${orgAlias}. Schema cached: ${typeCount} types (${elapsed}s).`);
+		}
 	} catch (err) {
 		clearInterval(spinner);
 		process.stderr.write("\r");

package/src/intent/__tests__/build-connect.spec.ts

@@ -0,0 +1,103 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { buildSchema } from "graphql";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { makeNoopPrimeDeps } from "../../__tests__/helpers/prime-deps.js";
+import { type PrimeDeps, SchemaRefreshError } from "../../lib/prime-schema.js";
+import { buildConnect } from "../build-connect.js";
+
+const ORG = "test-connect";
+const ORG_URL = "https://test-connect.my.salesforce.com";
+const SCHEMA = buildSchema(`type Query { x: Int }`);
+
+function failingPrimeDeps(err: unknown): PrimeDeps {
+	return {
+		getOrgAuth: async () => ({
+			alias: ORG,
+			username: "u",
+			instanceUrl: ORG_URL,
+			accessToken: "t",
+			orgId: "00D",
+		}),
+		downloadSchema: async () => {
+			throw err;
+		},
+	};
+}
+
+describe("intent/build-connect", () => {
+	let tmpRoot: string;
+
+	beforeEach(() => {
+		tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-build-connect-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+	});
+
+	afterEach(() => {
+		delete process.env.GRAPHITI_HOME;
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	it("lazily primes on first connect (cached: false, refreshed: false)", async () => {
+		const out = await buildConnect(
+			{ org: ORG },
+			{ primeDeps: makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA) },
+		);
+		expect(out.cached).toBe(false);
+		expect(out.refreshed).toBe(false);
+		expect(out.instanceUrl).toBe(ORG_URL);
+		expect(out.warnings).toBeUndefined();
+	});
+
+	it("returns cached when a connect finds an existing schema and forceRefresh is omitted", async () => {
+		const primeDeps = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+		await buildConnect({ org: ORG }, { primeDeps }); // prime
+		const out = await buildConnect({ org: ORG }, { primeDeps });
+		expect(out.cached).toBe(true);
+		expect(out.refreshed).toBe(false);
+	});
+
+	it("forceRefresh re-downloads and reports refreshed: true", async () => {
+		const primeDeps = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+		await buildConnect({ org: ORG }, { primeDeps }); // prime
+		const out = await buildConnect({ org: ORG, forceRefresh: true }, { primeDeps });
+		expect(out.refreshed).toBe(true);
+		expect(out.cached).toBe(false);
+	});
+
+	it("refresh failure with a surviving cache returns a soft staleness warning", async () => {
+		// Prime a real cache first, then fail the refresh.
+		await buildConnect({ org: ORG }, { primeDeps: makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA) });
+
+		const out = await buildConnect(
+			{ org: ORG, forceRefresh: true },
+			{
+				primeDeps: failingPrimeDeps(new Error("introspection failed")),
+			},
+		);
+
+		expect(out.refreshed).toBe(false);
+		expect(out.cached).toBe(true);
+		expect(out.instanceUrl).toBe(ORG_URL);
+		expect(out.durationMs).toBe(0);
+		expect(out.warnings?.[0]).toMatch(/keeping the previously cached schema/i);
+	});
+
+	it("refresh failure with no prior cache propagates the error", async () => {
+		await expect(
+			buildConnect(
+				{ org: ORG, forceRefresh: true },
+				{
+					primeDeps: failingPrimeDeps(new Error("introspection failed")),
+				},
+			),
+		).rejects.toBeInstanceOf(SchemaRefreshError);
+	});
+});

package/src/intent/build-connect.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { type ConnectOutput, type ConnectSpec } from "./types.js";
+import { type PrimeDeps, primeSchemaWithLock, SchemaRefreshError } from "../lib/prime-schema.js";
+
+export interface ConnectDeps {
+	primeDeps?: PrimeDeps;
+}
+
+/**
+ * Build the `sf_gql_connect` payload (W-22845606). Primes the schema cache for
+ * `spec.org`, or — with `spec.forceRefresh` — re-downloads it and coherently
+ * clears all three caches (on-disk introspection JSON, in-memory parsed schema,
+ * ObjectInfo).
+ *
+ * Failure policy (Q6 of the plan): a failed *refresh* that leaves a usable
+ * cached schema behind is recoverable, so we return a soft `ConnectOutput`
+ * (`refreshed: false`, `cached: true`) carrying a staleness-aware `warnings[]`
+ * entry — the agent can keep working on the still-valid schema. A failure with
+ * no prior cache (or any non-refresh failure such as missing auth) propagates,
+ * so the MCP SDK surfaces it as a hard tool error.
+ */
+export async function buildConnect(
+	spec: ConnectSpec,
+	deps: ConnectDeps = {},
+): Promise<ConnectOutput> {
+	try {
+		const prime = await primeSchemaWithLock(spec.org, deps.primeDeps, {
+			forceRefresh: spec.forceRefresh,
+		});
+		return {
+			org: spec.org,
+			instanceUrl: prime.instanceUrl,
+			refreshed: prime.refreshed,
+			cached: prime.cached,
+			durationMs: prime.durationMs,
+		};
+	} catch (e) {
+		if (e instanceof SchemaRefreshError && e.staleSince) {
+			return {
+				org: spec.org,
+				instanceUrl: e.instanceUrl,
+				refreshed: false,
+				cached: true,
+				durationMs: 0,
+				warnings: [e.message],
+			};
+		}
+		throw e;
+	}
+}

package/src/intent/types.ts

@@ -164,6 +164,31 @@ export interface DeleteSpec {
 	operationName?: string;
 }
 
+export interface ConnectSpec {
+	org: string;
+	/**
+	 * Re-download the schema even if it is already cached, coherently clearing
+	 * all three caches (on-disk introspection JSON, in-memory parsed schema, and
+	 * ObjectInfo). Defaults to false — a plain connect lazily primes on miss.
+	 */
+	forceRefresh?: boolean;
+}
+
+export interface ConnectOutput {
+	org: string;
+	instanceUrl: string;
+	/** True when this call performed a forced re-download. */
+	refreshed: boolean;
+	/** True when an existing cache satisfied the request (no download performed). */
+	cached: boolean;
+	durationMs: number;
+	/**
+	 * Populated when a refresh failed but a usable cached schema survived — the
+	 * staleness-aware message tells the caller the cache is still valid.
+	 */
+	warnings?: string[];
+}
+
 export type RawOperation = "query" | "mutation" | "aggregate";
 
 export interface RawSpec {

package/src/lib/__tests__/introspect.spec.ts

@@ -376,6 +376,40 @@ describe("introspect", () => {
 			}
 		});
 
+		it("bounds the introspection with a timeout and opts the POST into one retry (W-22845606)", async () => {
+			const core = (await import("@salesforce/core")) as unknown as {
+				__request: ReturnType<typeof vi.fn>;
+			};
+			core.__request.mockClear();
+			core.__request.mockResolvedValueOnce({ data: { __schema: { types: [] } } });
+
+			const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-dl-opts-"));
+			const prevHome = process.env.GRAPHITI_HOME;
+			process.env.GRAPHITI_HOME = tmpRoot;
+			try {
+				await downloadSchema(auth);
+				// connection.request(requestInfo, options) — the 2nd arg bounds the
+				// request (jsforce defaults to 30 min) and opts POST into retry
+				// (jsforce skips POST by default).
+				const options = core.__request.mock.calls[0][1] as {
+					timeout?: number;
+					retry?: { methods?: string[]; maxRetries?: number; statusCodes?: number[] };
+				};
+				expect(typeof options?.timeout).toBe("number");
+				expect(options.timeout as number).toBeGreaterThan(0);
+				expect(options?.retry?.methods).toContain("POST");
+				// Pin the transient-failure contract (W-22845606): exactly one retry on
+				// the listed 5xx/429/420 codes — jsforce's defaults (maxRetries 5, POST
+				// not retried) would otherwise apply, and value drift here is invisible
+				// to tsc/eslint since it's a plain object literal.
+				expect(options?.retry?.maxRetries).toBe(1);
+				expect(options?.retry?.statusCodes).toEqual([420, 429, 500, 502, 503, 504]);
+			} finally {
+				process.env.GRAPHITI_HOME = prevHome;
+				fs.rmSync(tmpRoot, { recursive: true, force: true });
+			}
+		});
+
 		it("throws when the response contains GraphQL errors", async () => {
 			const core = (await import("@salesforce/core")) as unknown as {
 				__request: ReturnType<typeof vi.fn>;