@salesforce/graphiti 10.10.2

package/src/lib/__tests__/path-selection.spec.ts

@@ -0,0 +1,219 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildSchema } from "graphql";
+import { describe, expect, it } from "vitest";
+import { selectDottedFieldPath } from "../path-selection.js";
+import { renderQuery } from "../query-builder.js";
+import { createSession, type QuerySession } from "../session.js";
+import { MutationContextError } from "../walker.js";
+
+// Models a Salesforce-shaped UIAPI with:
+//   - Value wrapper types (StringValue { value: String }) on scalar fields
+//   - A polymorphic Owner union (User | Group) — User has Email, Group does not
+//   - A scalar Id field that is NOT wrapped (matches UIAPI convention)
+//   - A non-polymorphic Account parent (plain object) for the control case
+const schema = buildSchema(`
+	type Query {
+		uiapi: UIAPI!
+	}
+
+	type UIAPI {
+		query: RecordQuery!
+	}
+
+	type RecordQuery {
+		Account(first: Int): AccountConnection!
+		Case(first: Int): CaseConnection!
+	}
+
+	type AccountConnection { edges: [AccountEdge!]! }
+	type AccountEdge { node: Account! }
+
+	type CaseConnection { edges: [CaseEdge!]! }
+	type CaseEdge { node: Case! }
+
+	type Account {
+		Id: ID!
+		Name: StringValue
+		Industry: StringValue
+		Owner: OwnerUnion
+	}
+
+	type Case {
+		Id: ID!
+		Subject: StringValue
+		Owner: OwnerUnion
+		Account: Account
+	}
+
+	union OwnerUnion = User | Group
+
+	type User {
+		Id: ID!
+		Name: StringValue
+		Email: StringValue
+	}
+
+	type Group {
+		Id: ID!
+		Name: StringValue
+	}
+
+	type StringValue {
+		value: String
+	}
+`);
+
+function makeSession(): QuerySession {
+	const session = createSession("test-org", "query");
+	session.navigationPath = ["query"];
+	return session;
+}
+
+const accountNodePath = ["uiapi", "query", "Account", "edges", "node"];
+const caseNodePath = ["uiapi", "query", "Case", "edges", "node"];
+
+describe("path-selection", () => {
+	describe("non-polymorphic dotted path", () => {
+		it("selects a scalar through a plain parent relationship", () => {
+			const session = makeSession();
+
+			selectDottedFieldPath(session, schema, caseNodePath, "Account.Name");
+
+			const query = renderQuery(session);
+			expect(query).toMatch(/Account\b[\s\S]*Name[\s\S]*\{[\s\S]*value/);
+			// Should NOT introduce inline fragments — Account is a plain object.
+			expect(query).not.toMatch(/\.\.\. on /);
+		});
+
+		it("selects Id without appending .value", () => {
+			const session = makeSession();
+
+			selectDottedFieldPath(session, schema, accountNodePath, "Id");
+
+			const query = renderQuery(session);
+			// Id is a scalar directly under Account; no `value` wrapper.
+			expect(query).toMatch(/Id\b/);
+			expect(query).not.toMatch(/Id \{[\s\S]*value/);
+		});
+
+		it("unwraps a StringValue to its .value selection", () => {
+			const session = makeSession();
+
+			selectDottedFieldPath(session, schema, accountNodePath, "Name");
+
+			const query = renderQuery(session);
+			// Name is a value wrapper — must select Name { value }.
+			expect(query).toMatch(/Name \{[\s\S]*value/);
+		});
+	});
+
+	describe("polymorphic union expansion", () => {
+		it("expands a polymorphic union segment to inline fragments", () => {
+			const session = makeSession();
+
+			selectDottedFieldPath(session, schema, accountNodePath, "Owner.Name");
+
+			const query = renderQuery(session);
+			// Both members of OwnerUnion (User and Group) have Name → both selected.
+			expect(query).toMatch(/Owner \{[\s\S]*\.\.\. on User \{[\s\S]*Name \{[\s\S]*value/);
+			expect(query).toMatch(/Owner \{[\s\S]*\.\.\. on Group \{[\s\S]*Name \{[\s\S]*value/);
+		});
+
+		it("skips union members that lack the field", () => {
+			const session = makeSession();
+
+			// Email exists on User but NOT on Group — we should select on User only,
+			// silently skipping Group rather than failing the whole call.
+			selectDottedFieldPath(session, schema, accountNodePath, "Owner.Email");
+
+			const query = renderQuery(session);
+			expect(query).toMatch(/\.\.\. on User \{[\s\S]*Email \{[\s\S]*value/);
+			expect(query).not.toMatch(/\.\.\. on Group \{[\s\S]*Email/);
+		});
+
+		it("throws when no union member has the field", () => {
+			const session = makeSession();
+
+			// BadField exists on neither User nor Group. Without a guard the function
+			// would silently no-op and the caller would render `query { }`. Fail loudly.
+			expect(() =>
+				selectDottedFieldPath(session, schema, accountNodePath, "Owner.BadField"),
+			).toThrow(/Field "BadField" not found on any member of union OwnerUnion/);
+		});
+
+		it("does not collide with sibling selections", () => {
+			const session = makeSession();
+
+			// Mixed selection: a non-polymorphic field, then a polymorphic one. The
+			// rendered query must contain both, and the union expansion must not
+			// disrupt the simple selection above it.
+			selectDottedFieldPath(session, schema, accountNodePath, "Name");
+			selectDottedFieldPath(session, schema, accountNodePath, "Owner.Name");
+
+			const query = renderQuery(session);
+			expect(query).toMatch(/Name \{[\s\S]*value/);
+			expect(query).toMatch(/Owner \{[\s\S]*\.\.\. on User/);
+			expect(query).toMatch(/Owner \{[\s\S]*\.\.\. on Group/);
+		});
+	});
+
+	describe("mutation context — MutationContextError", () => {
+		const mutationSchema = buildSchema(`
+			type Query { _placeholder: Boolean }
+			type Mutation { uiapi(input: UIAPIMutationsInput): UIAPIMutations! }
+			input UIAPIMutationsInput { allOrNone: Boolean }
+			type UIAPIMutations {
+				AccountCreate(input: AccountCreateInput!): AccountCreatePayload
+			}
+			input AccountCreateInput { Account: AccountCreateRepresentation! }
+			input AccountCreateRepresentation { Name: String }
+			type AccountCreatePayload { Record: Account }
+			type Account { Id: ID!, Name: StringValue, Owner: User }
+			type User { Id: ID!, Name: StringValue }
+			type StringValue { value: String }
+		`);
+
+		const mutationRecordPath = ["uiapi", "AccountCreate", "Record"];
+
+		function makeMutationSession(): QuerySession {
+			return createSession("test-org", "mutation");
+		}
+
+		it("throws MutationContextError for relationship field in mutation result", () => {
+			const session = makeMutationSession();
+
+			expect(() =>
+				selectDottedFieldPath(session, mutationSchema, mutationRecordPath, "Owner.Name"),
+			).toThrow(MutationContextError);
+		});
+
+		it("MutationContextError message includes field name and guidance", () => {
+			const session = makeMutationSession();
+
+			try {
+				selectDottedFieldPath(session, mutationSchema, mutationRecordPath, "Owner.Name");
+				expect.fail("should have thrown");
+			} catch (err) {
+				expect(err).toBeInstanceOf(MutationContextError);
+				expect((err as MutationContextError).message).toMatch(/Owner/);
+				expect((err as MutationContextError).message).toMatch(/not available in mutation results/);
+			}
+		});
+
+		it("does not throw MutationContextError for scalar fields in mutation result", () => {
+			const session = makeMutationSession();
+
+			expect(() =>
+				selectDottedFieldPath(session, mutationSchema, mutationRecordPath, "Name"),
+			).not.toThrow();
+
+			const query = renderQuery(session);
+			expect(query).toMatch(/Name \{[\s\S]*value/);
+		});
+	});
+});

package/src/lib/__tests__/prime-schema.spec.ts

@@ -0,0 +1,269 @@
+/**
+ * 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 { describe, expect, it } from "vitest";
+
+describe("lib/prime-schema", () => {
+	it("atomic-write: temp file is renamed to final path, no .tmp left behind", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-prime-"));
+		const finalPath = path.join(tmpRoot, "abc123.json");
+
+		const { atomicWriteJson } = await import("../fs-utils.js");
+
+		atomicWriteJson(finalPath, { hello: "world" });
+
+		expect(fs.existsSync(finalPath)).toBe(true);
+		expect(JSON.parse(fs.readFileSync(finalPath, "utf-8"))).toEqual({ hello: "world" });
+
+		const leftovers = fs.readdirSync(tmpRoot).filter((f) => f.includes(".tmp"));
+		expect(leftovers).toEqual([]);
+
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	it("atomic-write: parallel calls in the same process do not collide", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-prime-parallel-"));
+		const finalPath = path.join(tmpRoot, "p.json");
+
+		const { atomicWriteJson } = await import("../fs-utils.js");
+
+		// 16 parallel writers — would surface a temp-name collision quickly.
+		await Promise.all(
+			Array.from({ length: 16 }, (_, i) =>
+				Promise.resolve().then(() => atomicWriteJson(finalPath, { i })),
+			),
+		);
+
+		expect(fs.existsSync(finalPath)).toBe(true);
+		const leftovers = fs.readdirSync(tmpRoot).filter((f) => f.includes(".tmp"));
+		expect(leftovers).toEqual([]);
+		const contents = JSON.parse(fs.readFileSync(finalPath, "utf-8"));
+		expect(typeof contents.i).toBe("number");
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	it("lock: holder runs work, lock dir cleaned up after", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-lock-"));
+		const finalPath = path.join(tmpRoot, "x.json");
+		const { withSchemaLock } = await import("../prime-schema.js");
+
+		let ran = false;
+		await withSchemaLock(finalPath, async () => {
+			ran = true;
+			expect(fs.existsSync(`${finalPath}.lock`)).toBe(true);
+		});
+
+		expect(ran).toBe(true);
+		expect(fs.existsSync(`${finalPath}.lock`)).toBe(false);
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	it("lock: cleanup tolerates stray files inside the lock dir (e.g. .DS_Store)", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-lock-stray-"));
+		const finalPath = path.join(tmpRoot, "stray.json");
+		const { withSchemaLock } = await import("../prime-schema.js");
+
+		await withSchemaLock(finalPath, async () => {
+			// Simulate a stray file appearing inside the lock dir mid-work
+			// (macOS Finder, an editor swap, an OS indexer, etc.).
+			fs.writeFileSync(path.join(`${finalPath}.lock`, ".DS_Store"), "stray");
+		});
+
+		expect(fs.existsSync(`${finalPath}.lock`)).toBe(false);
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	it("lock: lock survives errors in the work function", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-lock-err-"));
+		const finalPath = path.join(tmpRoot, "y.json");
+		const { withSchemaLock } = await import("../prime-schema.js");
+
+		await expect(
+			withSchemaLock(finalPath, async () => {
+				throw new Error("boom");
+			}),
+		).rejects.toThrow(/boom/);
+		expect(fs.existsSync(`${finalPath}.lock`)).toBe(false);
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	it("lock: second waiter short-circuits when first holder primed the cache", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-lock-race-"));
+		const finalPath = path.join(tmpRoot, "z.json");
+		const { withSchemaLock } = await import("../prime-schema.js");
+		const { atomicWriteJson } = await import("../fs-utils.js");
+
+		let firstStarted = false;
+		let firstFinishedWriting = false;
+		let secondWorkRan = false;
+
+		const first = withSchemaLock(finalPath, async () => {
+			firstStarted = true;
+			await new Promise((r) => setTimeout(r, 200));
+			atomicWriteJson(finalPath, { primed: true });
+			firstFinishedWriting = true;
+		});
+
+		// Wait for first to acquire before launching second.
+		while (!firstStarted) await new Promise((r) => setTimeout(r, 5));
+
+		const second = withSchemaLock(finalPath, async () => {
+			secondWorkRan = true;
+			return "ran" as const;
+		});
+
+		const [, secondResult] = await Promise.all([first, second]);
+		expect(firstFinishedWriting).toBe(true);
+		expect(secondWorkRan).toBe(false);
+		expect(secondResult).toBeUndefined();
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	it("lock: stale lock dir older than STALE_LOCK_MS is reclaimed", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-lock-stale-"));
+		const finalPath = path.join(tmpRoot, "w.json");
+		const lockPath = `${finalPath}.lock`;
+		fs.mkdirSync(lockPath);
+		// Backdate the lock dir's mtime to well past the 7-min stale threshold.
+		const past = new Date(Date.now() - 10 * 60_000);
+		fs.utimesSync(lockPath, past, past);
+
+		const { withSchemaLock } = await import("../prime-schema.js");
+		let ran = false;
+		await withSchemaLock(finalPath, async () => {
+			ran = true;
+		});
+		expect(ran).toBe(true);
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	it("primeSchemaWithLock: returns metadata + duration on first prime", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-prime-pub-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+
+		try {
+			const { primeSchemaWithLock } = await import("../prime-schema.js");
+
+			let downloadCalls = 0;
+			const stubDeps = {
+				getOrgAuth: async () => ({
+					alias: "test-org",
+					instanceUrl: "https://example.my.salesforce.com",
+					accessToken: "fake-token",
+					username: "user@example.com",
+					orgId: "00Dxx0000000000",
+				}),
+				downloadSchema: async () => {
+					downloadCalls++;
+					// downloadSchema's real impl writes the cache file. Simulate that.
+					const { schemaCacheKeyForInstanceUrl } = await import("../introspect.js");
+					const { atomicWriteJson } = await import("../fs-utils.js");
+					const cacheKey = schemaCacheKeyForInstanceUrl("https://example.my.salesforce.com");
+					atomicWriteJson(path.join(tmpRoot, "schemas", `${cacheKey}.json`), {
+						data: { __schema: { types: [] } },
+						__graphiti: {
+							instanceUrl: "https://example.my.salesforce.com",
+							alias: "test-org",
+							cachedAt: new Date().toISOString(),
+						},
+					});
+					return {
+						cacheKey,
+						instanceUrl: "https://example.my.salesforce.com",
+						typeCount: 0,
+						downloadedAt: new Date().toISOString(),
+						filePath: path.join(tmpRoot, "schemas", `${cacheKey}.json`),
+					};
+				},
+			};
+
+			const result = await primeSchemaWithLock("test-org", stubDeps);
+
+			expect(result.cached).toBe(false);
+			expect(typeof result.durationMs).toBe("number");
+			expect(result.durationMs).toBeGreaterThanOrEqual(0);
+			expect(result.filePath).toMatch(/\.json$/);
+			expect(fs.existsSync(result.filePath)).toBe(true);
+			expect(downloadCalls).toBe(1);
+
+			// Second call must be a cache hit, not a re-introspection.
+			const second = await primeSchemaWithLock("test-org", stubDeps);
+			expect(second.cached).toBe(true);
+			expect(second.durationMs).toBe(0);
+			expect(downloadCalls).toBe(1);
+			expect(second.instanceUrl).toBe("https://example.my.salesforce.com");
+		} finally {
+			delete process.env.GRAPHITI_HOME;
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		}
+	});
+
+	it("primeSchemaWithLock: surfaces auth-missing error verbatim", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-prime-noauth-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+
+		try {
+			const { primeSchemaWithLock } = await import("../prime-schema.js");
+
+			const stubDeps = {
+				getOrgAuth: async () => {
+					throw new Error(
+						'Unknown org "nonexistent-org". Run `sf org login web -a nonexistent-org`.',
+					);
+				},
+				downloadSchema: async () => {
+					throw new Error("should not be called");
+				},
+			};
+
+			await expect(primeSchemaWithLock("nonexistent-org", stubDeps)).rejects.toThrow(
+				/unknown org|sf org login/i,
+			);
+		} finally {
+			delete process.env.GRAPHITI_HOME;
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		}
+	});
+
+	it("primeSchemaWithLock: awaits an async getOrgAuth and returns its instanceUrl", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-prime-async-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+		try {
+			const { primeSchemaWithLock } = await import("../prime-schema.js");
+			const stubDeps = {
+				getOrgAuth: async () => ({
+					alias: "o",
+					username: "u",
+					instanceUrl: "https://o.my.salesforce.com",
+					accessToken: "t",
+					orgId: "00D",
+				}),
+				downloadSchema: async () => {
+					const { schemaCacheKeyForInstanceUrl } = await import("../introspect.js");
+					const { atomicWriteJson } = await import("../fs-utils.js");
+					const cacheKey = schemaCacheKeyForInstanceUrl("https://o.my.salesforce.com");
+					const filePath = path.join(tmpRoot, "schemas", `${cacheKey}.json`);
+					atomicWriteJson(filePath, { data: { __schema: { types: [] } } });
+					return {
+						cacheKey,
+						instanceUrl: "https://o.my.salesforce.com",
+						typeCount: 0,
+						downloadedAt: new Date().toISOString(),
+						filePath,
+					};
+				},
+			};
+			const result = await primeSchemaWithLock("o", stubDeps);
+			expect(result.instanceUrl).toBe("https://o.my.salesforce.com");
+		} finally {
+			delete process.env.GRAPHITI_HOME;
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		}
+	});
+});

package/src/lib/__tests__/query-builder.spec.ts

@@ -0,0 +1,95 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { describe, expect, it } from "vitest";
+import { makeSession, TEST_SCHEMA } from "../../__tests__/helpers/schema.js";
+import { selectLeafInSession } from "../../commands/query.js";
+import { renderQuery } from "../query-builder.js";
+import {
+	addVariable,
+	createSiblingFieldInstance,
+	selectLeaf,
+	setAliasOnPath,
+	setArg,
+} from "../session.js";
+import { resolvePath } from "../walker.js";
+
+describe("query-builder", () => {
+	describe("integration with walker (fragment validation)", () => {
+		it("fragment directories validate compatibility during navigation", () => {
+			const session = makeSession();
+
+			expect(resolvePath(TEST_SCHEMA, "query", ["search", "[Account]"]).typeName).toBe("Account");
+			expect(() => resolvePath(TEST_SCHEMA, "query", ["search", "[Viewer]"])).toThrow(
+				/not a possible type of union SearchHit/,
+			);
+
+			session.navigationPath = ["query", "search", "[Account]"];
+			selectLeafInSession(session, "name");
+
+			expect(renderQuery(session)).toMatch(/\.\.\. on Account \{\n\s+name\n\s+\}/);
+		});
+	});
+
+	describe("inline fragment dot-paths", () => {
+		it("supports inline fragment syntax for union types", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "search"];
+
+			selectLeafInSession(session, "[Account].name", "accountName");
+
+			const query = renderQuery(session);
+			expect(query).toMatch(/\.\.\. on Account \{/);
+			expect(query).toMatch(/accountName: name/);
+		});
+
+		it("supports nested inline fragment dot-paths", () => {
+			const session = makeSession();
+			session.navigationPath = ["query"];
+
+			selectLeafInSession(session, "search.[Contact].email");
+
+			const query = renderQuery(session);
+			expect(query).toMatch(/\.\.\. on Contact \{/);
+			expect(query).toMatch(/email/);
+		});
+	});
+
+	describe("aliasing rendering", () => {
+		it("renders multiple aliased instances with different variables", () => {
+			const session = makeSession();
+
+			addVariable(session, "$limit", "Int");
+			addVariable(session, "$otherLimit", "Int");
+			addVariable(session, "$accountFilter", "AccountFilter");
+			addVariable(session, "$otherFilter", "AccountFilter");
+
+			session.navigationPath = ["query", "accounts"];
+			setAliasOnPath(session, ["accounts"], "highRevenueAccounts");
+			setArg(session, ["accounts"], "first", "$limit");
+			setArg(session, ["accounts"], "where", "$accountFilter");
+
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+
+			session.navigationPath = ["query", "accounts"];
+			createSiblingFieldInstance(session, ["accounts"], "regionalAccounts");
+			setArg(session, ["accounts"], "first", "$otherLimit");
+			setArg(session, ["accounts"], "where", "$otherFilter");
+
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "id"]);
+
+			const query = renderQuery(session);
+			expect(query).toMatch(
+				/highRevenueAccounts: accounts\(first: \$limit, where: \$accountFilter\)/,
+			);
+			expect(query).toMatch(
+				/regionalAccounts: accounts\(first: \$otherLimit, where: \$otherFilter\)/,
+			);
+		});
+	});
+});

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

@@ -0,0 +1,74 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { describe, expect, it } from "vitest";
+import { makeSession } from "../../__tests__/helpers/schema.js";
+import { formatHelp, formatNextSteps, QUERY_COMMANDS } from "../query-commands.js";
+
+describe("query-commands", () => {
+	describe("command registry", () => {
+		it("lists all expected commands", () => {
+			const names = QUERY_COMMANDS.map((c) => c.name);
+			for (const expected of [
+				"pwd",
+				"ls",
+				"cd",
+				"select",
+				"drop",
+				"set",
+				"alias",
+				"var",
+				"show",
+				"check",
+				"run",
+				"help",
+				"interactive",
+			]) {
+				expect(names).toContain(expected);
+			}
+		});
+
+		it("every command spec has a non-empty summary and usage", () => {
+			for (const spec of QUERY_COMMANDS) {
+				expect(spec.summary.length).toBeGreaterThan(0);
+				expect(spec.usage.length).toBeGreaterThan(0);
+			}
+		});
+	});
+
+	describe("formatHelp", () => {
+		it("with no topic returns a full listing", () => {
+			const help = formatHelp();
+			expect(help).toContain("pwd");
+			expect(help).toContain("select");
+			expect(help).toContain("interactive");
+			expect(help).toContain("Run `help <subcommand>`");
+		});
+
+		it("with known topic returns usage and examples", () => {
+			const help = formatHelp("set");
+			expect(help).toContain("set");
+			expect(help).toContain("Usage:");
+			expect(help).toContain("Examples:");
+		});
+
+		it("with unknown topic returns an error message", () => {
+			const help = formatHelp("nonexistent_command");
+			expect(help).toContain("Unknown help topic");
+		});
+	});
+
+	describe("formatNextSteps", () => {
+		it("returns next-step hints for each key command", () => {
+			const session = makeSession();
+			for (const cmd of ["new", "ls", "cd", "select", "set", "var", "show", "check"]) {
+				const output = formatNextSteps({ sessionId: session.id, command: cmd, session });
+				expect(output).toContain("Next steps:");
+				expect(output).toContain("graphiti query");
+			}
+		});
+	});
+});