@salesforce/graphiti 10.10.2

package/src/lib/prime-schema.ts

@@ -0,0 +1,195 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { getOrgAuth as realGetOrgAuth, type OrgAuth } from "./auth.js";
+import {
+	downloadSchema as realDownloadSchema,
+	normalizeInstanceUrl,
+	schemaCacheKeyForInstanceUrl,
+	schemaDir,
+	type SchemaMetadata,
+} from "./introspect.js";
+
+// FR-13.7 originally suggested a 10-30s introspection budget. Empirical
+// smoke testing against real Salesforce UIAPI schemas measures ~135s for
+// a ~40MB introspection. We size the stale-lock threshold and the waiter
+// timeout for ~3× that observed worst case (~7 min): comfortable headroom
+// for normal operation while keeping crashed-holder recovery within a few
+// minutes. If introspection ever legitimately exceeds 5 min the design
+// assumption ("priming completes in minutes, not tens of minutes") has
+// changed and these constants should be revisited together (likely with
+// a heartbeat that refreshes the lock dir's mtime while held).
+const STALE_LOCK_MS = 7 * 60_000;
+const POLL_MS = 100;
+const MAX_WAIT_MS = 7 * 60_000;
+
+/**
+ * Acquire a filesystem advisory lock at `${finalPath}.lock` (a directory,
+ * since `mkdir` is atomic on POSIX), run `work`, then release the lock.
+ *
+ * If another process holds the lock, this polls every 100ms for the lock
+ * to be released. On release, if `finalPath` now exists, the work function
+ * is skipped (the other process already did it). If `finalPath` still does
+ * not exist (the other process aborted without writing), this acquires the
+ * lock and runs `work`.
+ *
+ * Contract: `work` will NOT run when `finalPath` exists at any point during
+ * the lock dance — including immediately after we acquire the lock (a holder
+ * may have finished and released the lock between our last EEXIST poll and
+ * our successful `mkdir`). In that case the lock is released and the
+ * function returns `undefined`.
+ *
+ * Stale locks (older than STALE_LOCK_MS) are reclaimed.
+ */
+export async function withSchemaLock<T>(
+	finalPath: string,
+	work: () => Promise<T>,
+): Promise<T | undefined> {
+	const lockPath = `${finalPath}.lock`;
+	fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+
+	const startedWaitingAt = Date.now();
+	while (true) {
+		try {
+			fs.mkdirSync(lockPath); // atomic; throws EEXIST if held
+			break;
+		} catch (e: unknown) {
+			const err = e as NodeJS.ErrnoException;
+			if (err.code !== "EEXIST") throw e;
+
+			// If the cache exists now, another holder finished — short-circuit.
+			if (fs.existsSync(finalPath)) return undefined;
+
+			// Stale-lock reclaim. Known TOCTOU: between this `statSync` and
+			// the `rmSync` below, another process may have already reclaimed
+			// the stale lock and re-created a fresh one — in which case we'd
+			// remove the fresh lock. Window is microseconds and the next
+			// `mkdirSync` retry self-heals (we'd re-acquire or re-block);
+			// not worth fcntl-level locking to close.
+			try {
+				const stat = fs.statSync(lockPath);
+				if (Date.now() - stat.mtimeMs > STALE_LOCK_MS) {
+					// Recursive removal: a stray file inside the lock dir
+					// (e.g. macOS `.DS_Store`) would make `rmdirSync` throw
+					// ENOTEMPTY, which the bare catch below would swallow,
+					// leaving the stale lock in place.
+					fs.rmSync(lockPath, { recursive: true });
+					continue;
+				}
+			} catch {
+				// Lock vanished between EEXIST and stat — loop and retry mkdir.
+			}
+
+			if (Date.now() - startedWaitingAt > MAX_WAIT_MS) {
+				throw new Error(
+					`Timed out waiting ${MAX_WAIT_MS}ms for schema priming lock at ${lockPath}`,
+				);
+			}
+			await new Promise((r) => setTimeout(r, POLL_MS));
+		}
+	}
+
+	// We now hold the lock. Re-check for the cache: a holder that finished
+	// between our last EEXIST poll and our successful mkdir may have just
+	// primed it. Avoid running `work` redundantly.
+	if (fs.existsSync(finalPath)) {
+		try {
+			fs.rmSync(lockPath, { recursive: true });
+		} catch {
+			// best-effort
+		}
+		return undefined;
+	}
+
+	try {
+		return await work();
+	} finally {
+		// Recursive remove tolerates stray files inside the lock dir (e.g.
+		// macOS `.DS_Store`) that would otherwise make `rmdirSync` throw
+		// ENOTEMPTY and leak the lock until the 7-min stale timeout.
+		try {
+			fs.rmSync(lockPath, { recursive: true });
+		} catch {
+			// Already gone — fine.
+		}
+	}
+}
+
+export interface PrimeResult {
+	cached: boolean;
+	filePath: string;
+	durationMs: number;
+	/** Resolved instance URL (already auth-resolved). */
+	instanceUrl: string;
+}
+
+/**
+ * Dependencies that `primeSchemaWithLock` calls. Defaulted to the real
+ * graphiti implementations; tests pass stubs.
+ */
+export interface PrimeDeps {
+	getOrgAuth: (orgAlias: string) => Promise<OrgAuth>;
+	downloadSchema: (auth: OrgAuth) => Promise<SchemaMetadata>;
+}
+
+const REAL_DEPS: PrimeDeps = {
+	getOrgAuth: realGetOrgAuth,
+	downloadSchema: realDownloadSchema,
+};
+
+/**
+ * Lazily prime the on-disk schema cache for `orgAlias`.
+ *
+ * - If `<HOME>/.graphiti/schemas/<hash>.json` already exists, returns
+ *   `{cached: true}` immediately.
+ * - Otherwise: resolves auth via `deps.getOrgAuth` (throws verbatim if the
+ *   alias is not authenticated, per FR-13.5), acquires the schema lock via
+ *   `withSchemaLock`, calls `deps.downloadSchema(auth)` (which writes the
+ *   cache atomically via `downloadSchema`'s internal use of
+ *   `atomicWriteJson`), releases the lock, and returns
+ *   `{cached: false, durationMs}`. Per FR-13.6, partial caches never reach
+ *   disk because writes are atomic.
+ *
+ * Concurrent callers in the same or different processes serialize on the
+ * lock dir; only one performs introspection. Subsequent waiters observe
+ * the primed cache and short-circuit (FR-13.4).
+ */
+export async function primeSchemaWithLock(
+	orgAlias: string,
+	deps: PrimeDeps = REAL_DEPS,
+): Promise<PrimeResult> {
+	// We must call `deps.getOrgAuth` first because it is the only injected
+	// source of the org's `instanceUrl`, which the cache key is derived from.
+	// In tests this returns a stub; in production it is memoized inside
+	// `auth.ts`'s in-process cache, so the org is resolved via `@salesforce/core`
+	// at most once per org alias per process.
+	const auth = await deps.getOrgAuth(orgAlias);
+	const instanceUrl = normalizeInstanceUrl(auth.instanceUrl);
+	const cacheKey = schemaCacheKeyForInstanceUrl(instanceUrl);
+	const filePath = path.join(schemaDir(), `${cacheKey}.json`);
+
+	if (fs.existsSync(filePath)) {
+		return { cached: true, filePath, durationMs: 0, instanceUrl };
+	}
+
+	const start = Date.now();
+	let primed = false;
+	await withSchemaLock(filePath, async () => {
+		// withSchemaLock re-checks `finalPath` after acquire and short-
+		// circuits if it now exists, so when our work runs we know we
+		// must do the introspection.
+		await deps.downloadSchema(auth);
+		primed = true;
+	});
+
+	if (!primed) {
+		// Another process primed while we were waiting.
+		return { cached: true, filePath, durationMs: Date.now() - start, instanceUrl };
+	}
+	return { cached: false, filePath, durationMs: Date.now() - start, instanceUrl };
+}

package/src/lib/query-builder.ts

@@ -0,0 +1,193 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import type { QuerySession, ProjectionNode, DirectiveNode } from "./session.js";
+import { getChildren, getEffectiveArgs } from "./session.js";
+
+/**
+ * Renders a QuerySession's selection tree into a properly formatted GraphQL query string.
+ */
+export function renderQuery(session: QuerySession): string {
+	const parts: string[] = [];
+
+	// Operation line with variables
+	const varDefs =
+		session.variables.length > 0
+			? `(${session.variables
+					.map((v) => {
+						let def = `$${v.name}: ${v.type}`;
+						if (v.defaultValue !== undefined) def += ` = ${v.defaultValue}`;
+						return def;
+					})
+					.join(", ")})`
+			: "";
+
+	const operationKeyword = session.operation === "aggregate" ? "query" : session.operation;
+	const operationName = session.operationName ? ` ${session.operationName}` : "";
+	const operationBody = renderChildren(session, null, 1);
+	if (operationBody) {
+		parts.push(`${operationKeyword}${operationName}${varDefs} {`);
+		parts.push(operationBody);
+		parts.push("}");
+	} else {
+		parts.push(`${operationKeyword}${operationName}${varDefs} { }`);
+	}
+
+	return parts.join("\n");
+}
+
+function renderChildren(session: QuerySession, parentId: string | null, depth: number): string {
+	const _indent = "  ".repeat(depth);
+	const lines: string[] = [];
+
+	for (const child of getChildren(session, parentId)) {
+		if (child.kind === "field") {
+			lines.push(renderField(session, child, depth));
+		} else {
+			lines.push(renderInlineFragment(session, child, depth));
+		}
+	}
+
+	return lines.join("\n");
+}
+
+function renderField(
+	session: QuerySession,
+	node: Extract<ProjectionNode, { kind: "field" }>,
+	depth: number,
+): string {
+	const indent = "  ".repeat(depth);
+	let line = indent;
+
+	// Alias
+	if (node.alias) {
+		line += `${node.alias}: `;
+	}
+
+	line += node.fieldName;
+
+	// Arguments
+	const argEntries = Object.entries(getEffectiveArgs(session, node));
+	if (argEntries.length > 0) {
+		const argParts = argEntries.map(([name, value]) => {
+			return `${name}: ${formatArgValue(value)}`;
+		});
+		line += `(${argParts.join(", ")})`;
+	}
+
+	// Directives
+	for (const dir of node.directives) {
+		line += ` ${renderDirective(dir)}`;
+	}
+
+	// Sub-selections
+	const childNodes = getChildren(session, node.id);
+	const hasChildren = childNodes.length > 0;
+
+	if (hasChildren) {
+		const childContent = renderChildren(session, node.id, depth + 1);
+		line += ` {\n${childContent}\n${indent}}`;
+	}
+
+	return line;
+}
+
+function renderInlineFragment(
+	session: QuerySession,
+	frag: Extract<ProjectionNode, { kind: "fragment" }>,
+	depth: number,
+): string {
+	const indent = "  ".repeat(depth);
+	let line = `${indent}... on ${frag.onType}`;
+
+	for (const dir of frag.directives) {
+		line += ` ${renderDirective(dir)}`;
+	}
+
+	const childContent = renderChildren(session, frag.id, depth + 1);
+	if (childContent) {
+		line += ` {\n${childContent}\n${indent}}`;
+	} else {
+		line += " { }";
+	}
+
+	return line;
+}
+
+function renderDirective(dir: DirectiveNode): string {
+	const argEntries = Object.entries(dir.args);
+	if (argEntries.length === 0) {
+		return `@${dir.name}`;
+	}
+	const argParts = argEntries.map(([name, value]) => `${name}: ${formatArgValue(value)}`);
+	return `@${dir.name}(${argParts.join(", ")})`;
+}
+
+/**
+ * Formats an argument value for rendering in GraphQL.
+ * Handles variable references ($varName), raw JSON objects, numbers, booleans, and strings.
+ */
+function formatArgValue(value: string): string {
+	const trimmed = value.trim();
+
+	// Variable reference
+	if (trimmed.startsWith("$")) return trimmed;
+
+	// Numeric
+	if (/^-?\d+(\.\d+)?$/.test(trimmed)) return trimmed;
+
+	// Boolean / null
+	if (trimmed === "true" || trimmed === "false" || trimmed === "null") return trimmed;
+
+	// Enum value (unquoted identifier)
+	if (/^[A-Z_][A-Z0-9_]*$/i.test(trimmed) && trimmed === trimmed.toUpperCase()) return trimmed;
+
+	// JSON object or array — convert to GraphQL literal syntax
+	if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+		return jsonToGraphQL(trimmed);
+	}
+
+	// Quoted string — pass through
+	if (trimmed.startsWith('"') && trimmed.endsWith('"')) return trimmed;
+
+	// Default: wrap in quotes
+	return `"${trimmed.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Converts a JSON string to GraphQL object literal syntax.
+ * GraphQL uses unquoted keys: { Status: { ne: "Closed" } }
+ */
+function jsonToGraphQL(jsonStr: string): string {
+	try {
+		const parsed = JSON.parse(jsonStr);
+		return valueToGraphQL(parsed);
+	} catch {
+		// If not valid JSON, return as-is (might already be in GraphQL format)
+		return jsonStr;
+	}
+}
+
+function valueToGraphQL(value: unknown): string {
+	if (value === null || value === undefined) return "null";
+	if (typeof value === "boolean") return String(value);
+	if (typeof value === "number") return String(value);
+	if (typeof value === "string") {
+		if (value.startsWith("$")) return value;
+		// Emit uppercase identifiers as bare enum tokens (e.g. DESC, ASC, EVERYTHING)
+		if (/^[A-Z_][A-Z0-9_]*$/.test(value)) return value;
+		return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map(valueToGraphQL).join(", ")}]`;
+	}
+	if (typeof value === "object") {
+		const entries = Object.entries(value as Record<string, unknown>);
+		const parts = entries.map(([k, v]) => `${k}: ${valueToGraphQL(v)}`);
+		return `{ ${parts.join(", ")} }`;
+	}
+	return String(value);
+}

package/src/lib/query-commands.ts

@@ -0,0 +1,290 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { COMMANDS, type CommandDef } from "./command-registry.js";
+import type { QuerySession } from "./session.js";
+import type { WalkerResult } from "./walker.js";
+
+// ── Interactive mode flag ─────────────────────────────────────────────────────
+
+let _interactiveMode = false;
+
+export function setInteractiveMode(on: boolean): void {
+	_interactiveMode = on;
+}
+
+export function isInteractiveMode(): boolean {
+	return _interactiveMode;
+}
+
+// ── Backward-compatible re-export ─────────────────────────────────────────────
+// QUERY_COMMANDS was the original registry. It now delegates to the canonical
+// COMMANDS array in command-registry.ts so there is a single source of truth.
+export { COMMANDS as QUERY_COMMANDS };
+
+// ── Formatting helpers ───────────────────────────────────────────────────────
+
+export function formatHelp(topic?: string): string {
+	const lines: string[] = [];
+
+	if (topic) {
+		const spec: CommandDef | undefined = COMMANDS.find((c) => c.name === topic);
+		if (!spec) {
+			return `Unknown help topic: "${topic}". Run \`help\` with no arguments for a full list.`;
+		}
+		lines.push(`${spec.name} — ${spec.summary}`);
+		lines.push("");
+		const usagePrefix = _interactiveMode ? "" : "graphiti ";
+		const usageStr = spec.usage.startsWith("graphiti ")
+			? spec.usage
+			: `${usagePrefix}${spec.usage}`;
+		lines.push(`Usage: ${usageStr}`);
+		if (spec.subcommands && spec.subcommands.length > 0) {
+			lines.push("");
+			lines.push("Subcommands:");
+			for (const sub of spec.subcommands) {
+				lines.push(`  ${sub.usage.padEnd(32)} ${sub.description}`);
+			}
+		}
+
+		if (topic === "ls") {
+			lines.push("");
+			lines.push("Search behavior (--search):");
+			lines.push('  Multiple terms are OR-matched: --search "Name Id" matches fields');
+			lines.push('  containing either "Name" or "Id". Each term is prefix-matched');
+			lines.push('  against CamelCase word segments, so "Id" matches "AccountId"');
+			lines.push('  but not "Hide".');
+		}
+
+		if (topic === "alias" || topic === "mkdir") {
+			lines.push("");
+			lines.push("Multi-query composition:");
+			lines.push("  Use alias to create multiple named instances of the same field,");
+			lines.push("  each with different arguments. This lets you combine several queries");
+			lines.push("  into a single GraphQL request (e.g. dashboard tiles + lists).");
+			lines.push("");
+			lines.push("  # Full end-to-end example (from /query/uiapi/query):");
+			lines.push("  alias newCases Case");
+			lines.push('  set newCases/@args/where \'{"Status":{"eq":"New"}}\'');
+			lines.push("  set newCases/@args/first 10");
+			lines.push("  select newCases/edges/node/Id newCases/edges/node/Subject/value");
+			lines.push("");
+			lines.push("  alias myCases Case");
+			lines.push("  set myCases/@args/scope MINE");
+			lines.push("  set myCases/@args/first 20");
+			lines.push("  select myCases/edges/node/Id myCases/edges/node/Status/value");
+			lines.push("");
+			lines.push("  show   # see the combined query");
+		}
+
+		if (topic === "chain") {
+			lines.push("");
+			lines.push("Note: session management commands (new, use, connect, describe,");
+			lines.push("interactive) must be run as separate commands before chaining.");
+			lines.push("Only session-scoped commands (cd, ls, select, set, var, etc.)");
+			lines.push("can be used inside a chain.");
+		}
+
+		if (topic === "set" || topic === "assign") {
+			lines.push("");
+			lines.push("Inline key=value syntax (preferred):");
+			lines.push("  set first=10                              # set on current field");
+			lines.push("  set uiapi/query/Case first=10 scope=MINE  # with absolute field path");
+			lines.push('  set where=\'{"Status":{"eq":"New"}}\'       # JSON value');
+			lines.push("");
+			lines.push("Legacy pair syntax:");
+			lines.push("  set @args/first 10");
+			lines.push('  set @args/where/Name/like "Acme%"');
+		}
+
+		lines.push("");
+		lines.push("Examples:");
+		for (const ex of spec.examples) {
+			const exPrefix = _interactiveMode ? "  " : "  ";
+			lines.push(`${exPrefix}${ex}`);
+		}
+		return lines.join("\n");
+	}
+
+	lines.push("Graphiti CLI — Progressive GraphQL query builder for Salesforce");
+	lines.push("");
+	lines.push(
+		"Session resolution: --session / -s flag > GRAPHITI_SESSION env var > ~/.graphiti/active",
+	);
+	lines.push("JSON output: --json flag or GRAPHITI_AGENT=1 env var");
+	lines.push("");
+	lines.push("Setup:");
+	for (const name of ["new", "use", "connect"]) {
+		const spec = COMMANDS.find((c) => c.name === name);
+		if (spec) lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+	}
+	lines.push("");
+	lines.push("Navigation:");
+	for (const name of ["pwd", "ls", "cd"]) {
+		const spec = COMMANDS.find((c) => c.name === name)!;
+		lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+	}
+	lines.push("");
+	lines.push("Query Building:");
+	for (const name of ["select", "drop", "alias", "optional", "undo"]) {
+		const spec = COMMANDS.find((c) => c.name === name)!;
+		lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+	}
+	lines.push("");
+	lines.push("Arguments & Variables:");
+	for (const name of ["set", "unset", "var"]) {
+		const spec = COMMANDS.find((c) => c.name === name)!;
+		lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+	}
+	lines.push("");
+	lines.push("Review & Execute:");
+	for (const name of ["show", "check", "run", "describe", "codegen"]) {
+		const spec = COMMANDS.find((c) => c.name === name)!;
+		lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+	}
+	lines.push("");
+	lines.push("Session Management:");
+	for (const name of ["sessions", "clone", "reset"]) {
+		const spec = COMMANDS.find((c) => c.name === name)!;
+		lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+	}
+	lines.push("");
+	lines.push("Other:");
+	const otherCommands = _interactiveMode ? ["chain", "help"] : ["chain", "help", "interactive"];
+	for (const name of otherCommands) {
+		const spec = COMMANDS.find((c) => c.name === name);
+		if (spec) lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+	}
+	lines.push("");
+	lines.push("Run `help <subcommand>` for detailed usage and examples.");
+	return lines.join("\n");
+}
+
+// ── Next-steps hints ─────────────────────────────────────────────────────────
+
+export interface NextStepsContext {
+	sessionId: string;
+	command: string;
+	walkerResult?: WalkerResult;
+	session?: QuerySession;
+}
+
+export function formatNextSteps(ctx: NextStepsContext): string {
+	const { sessionId: sid, command, walkerResult: wr, session } = ctx;
+	const lines: string[] = [];
+	const p = (cmd: string, desc: string) => {
+		if (_interactiveMode) {
+			lines.push(`  ${cmd.padEnd(36)} # ${desc}`);
+		} else {
+			lines.push(`  graphiti query ${sid} ${cmd.padEnd(36)} # ${desc}`);
+		}
+	};
+
+	const isRoot = !session || session.navigationPath.length === 0;
+	const hasSelections = session ? session.nodes.length > 0 : false;
+	const hasArgs = wr && wr.args.length > 0;
+	const isLeaf = wr?.isLeaf ?? false;
+	const _hasFragments = wr && wr.possibleTypes.length > 0;
+	const hasFields = wr && !wr.isLeaf && wr.fields.length > 0;
+
+	lines.push("");
+	lines.push("Next steps:");
+
+	switch (command) {
+		case "new": {
+			p("cd query", "navigate into the query tree");
+			p("ls", "see available root fields");
+			p("interactive", "start an interactive session");
+			break;
+		}
+
+		case "ls": {
+			if (isLeaf) {
+				if (!isRoot && session) {
+					const leaf = session.navigationPath[session.navigationPath.length - 1];
+					p(`cd ..`, "go up to parent directory");
+					p(`select ${leaf}`, "select this leaf field");
+				}
+			} else {
+				if (hasFields) {
+					const firstDir = wr!.fields.find((f) => f.typeKind !== "SCALAR" && f.typeKind !== "ENUM");
+					const firstLeaf = wr!.fields.find(
+						(f) => f.typeKind === "SCALAR" || f.typeKind === "ENUM",
+					);
+					if (firstDir) p(`cd ${firstDir.name}`, `navigate into ${firstDir.name}/`);
+					if (firstLeaf) p(`select ${firstLeaf.name}`, `add ${firstLeaf.name} to projection`);
+					const hasConnections = wr!.fields.some((f) => f.typeName.includes("Connection"));
+					if (hasConnections && firstDir)
+						p(`alias myAlias ${firstDir.name}`, "compose multiple queries via aliases");
+				}
+				if (hasArgs) p(`cd @args`, "navigate into arguments");
+				if (!isRoot) p(`cd ..`, "go up one level");
+			}
+			break;
+		}
+
+		case "cd": {
+			p(`ls`, "see contents at this path");
+			if (hasArgs) p(`cd @args`, "configure field arguments");
+			if (hasFields) {
+				const firstLeaf = wr!.fields.find((f) => f.typeKind === "SCALAR" || f.typeKind === "ENUM");
+				if (firstLeaf) p(`select ${firstLeaf.name}`, `add ${firstLeaf.name} to projection`);
+			}
+			break;
+		}
+
+		case "select": {
+			p(`ls`, "see more available fields");
+			if (!isRoot) p(`cd ..`, "go up to parent");
+			if (hasSelections) {
+				p(`show`, "preview the current query string");
+				p(`check`, "validate the query");
+			}
+			break;
+		}
+
+		case "assign":
+		case "set": {
+			p(`show`, "preview query with arguments");
+			p(`ls`, "see other fields to set");
+			if (hasSelections) p(`check`, "validate the query");
+			break;
+		}
+
+		case "define":
+		case "var": {
+			p(`cd /variables/$varName`, "navigate into the variable to set values");
+			p(`show`, "preview the query signature");
+			break;
+		}
+
+		case "show": {
+			p(`check`, "validate the query");
+			if (hasSelections) p(`run`, "execute the query against the org");
+			break;
+		}
+
+		case "validate":
+		case "check": {
+			if (hasSelections) p(`run`, "execute the validated query");
+			p(`show`, "preview the query string");
+			break;
+		}
+
+		default: {
+			p(`ls`, "list contents at current path");
+			p(`show`, "preview the current query");
+			if (hasSelections) p(`check`, "validate the query");
+			break;
+		}
+	}
+
+	if (lines.length <= 2) {
+		p(`help`, "show all available commands");
+	}
+
+	return lines.join("\n");
+}