@salesforce/graphiti 10.10.2

package/src/commands/build.ts

@@ -0,0 +1,288 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import {
+	CommandError,
+	getSessionSchema,
+	selectLeafInSession,
+	parsePathInput,
+	printQuery,
+} from "./query-helpers.js";
+import {
+	loadSession,
+	saveSession,
+	getNavigationContext,
+	isInArgsContext,
+	queryNavToSchemaPath,
+	getArgsFieldPath,
+	getInputSubPath,
+	getChildren,
+	getFocusedNodeAtPath,
+	formatPath,
+	findDescendantByAlias,
+	removeNodeByIdWithPrune,
+	removeSelectionAtPath,
+	removeVariable,
+	deepRemoveArg,
+	removeListElement,
+	appendListElement,
+	createSiblingFieldInstance,
+	type FieldProjectionNode,
+} from "../lib/session.js";
+import { resolveFieldOnPath } from "../lib/walker.js";
+
+export function querySelect(sessionId: string, leafName: string, opts: { alias?: string }): void {
+	const session = loadSession(sessionId);
+	selectLeafInSession(session, leafName, opts.alias);
+	saveSession(session);
+
+	console.log(`Selected ${leafName}${opts.alias ? ` as ${opts.alias}` : ""}.`);
+	console.log("");
+	printQuery(session);
+}
+
+export function querySelectLs(sessionId: string): void {
+	const session = loadSession(sessionId);
+	const currentSchemaPath = queryNavToSchemaPath(session.navigationPath);
+
+	const leaves = session.nodes.filter((node): node is FieldProjectionNode => {
+		if (node.kind !== "field") return false;
+		return getChildren(session, node.id).length === 0;
+	});
+
+	if (leaves.length === 0) {
+		console.log("No fields selected. Use `select <field>` or `select <path:alias>` to add fields.");
+		return;
+	}
+
+	console.log(`Selected fields (${leaves.length}):`);
+	console.log("");
+	for (const leaf of leaves) {
+		const fullPath = leaf.schemaPath;
+		let displayPath: string;
+		if (
+			currentSchemaPath.length > 0 &&
+			fullPath.length > currentSchemaPath.length &&
+			currentSchemaPath.every((seg, i) => seg === fullPath[i])
+		) {
+			displayPath = fullPath.slice(currentSchemaPath.length).join(".");
+		} else {
+			displayPath = "/" + fullPath.join("/");
+		}
+		const aliasPart = leaf.alias ? ` → ${leaf.alias}` : "";
+		const optPart = leaf.directives.some((d) => d.name === "optional") ? " @optional" : "";
+		console.log(`  ${displayPath}${aliasPart}${optPart}`);
+	}
+	console.log("");
+	console.log("Remove with: rm <alias> or rm <dot.path>");
+}
+
+export function queryRm(sessionId: string, rawInput: string): void {
+	const session = loadSession(sessionId);
+	const ctx = getNavigationContext(session.navigationPath);
+
+	if (rawInput.startsWith("$") && !isInArgsContext(session.navigationPath)) {
+		const cleanName = rawInput.replace(/^\$/, "");
+		const removed = removeVariable(session, cleanName);
+		if (!removed) {
+			throw new CommandError(`Variable "$${cleanName}" is not defined.`);
+		}
+		saveSession(session);
+		console.log(`Removed variable $${cleanName} and all references to it.`);
+		console.log("Tip: use `undo` to restore it.");
+		console.log("");
+		printQuery(session);
+		return;
+	}
+
+	if (ctx === "variables" && !isInArgsContext(session.navigationPath)) {
+		const cleanName = rawInput.replace(/^\$/, "");
+		const removed = removeVariable(session, cleanName);
+		if (!removed) {
+			throw new CommandError(`Variable "$${cleanName}" is not defined.`);
+		}
+		saveSession(session);
+		console.log(`Removed variable $${cleanName} and all references to it.`);
+		console.log("Tip: use `undo` to restore it.");
+		console.log("");
+		printQuery(session);
+		return;
+	}
+
+	if (isInArgsContext(session.navigationPath)) {
+		const fieldSchemaPath = getArgsFieldPath(session.navigationPath);
+		const inputSubPath = getInputSubPath(session.navigationPath);
+
+		const fullPath = [...inputSubPath, ...rawInput.split(".")];
+
+		if (fullPath.length === 0) {
+			throw new CommandError("Usage: rm <argName> or rm <index>");
+		}
+
+		const argName = fullPath[0];
+		const nested = fullPath.slice(1);
+
+		if (/^\d+$/.test(rawInput) && inputSubPath.length > 0) {
+			const parentArgName = inputSubPath[0];
+			const parentNested = inputSubPath.slice(1);
+			const removed = removeListElement(
+				session,
+				fieldSchemaPath,
+				parentArgName,
+				parentNested,
+				Number(rawInput),
+			);
+			if (removed) {
+				saveSession(session);
+				console.log(`Removed list element ${rawInput}.`);
+				console.log("");
+				printQuery(session);
+				return;
+			}
+		}
+
+		const removed = deepRemoveArg(session, fieldSchemaPath, argName, nested);
+		if (!removed) {
+			throw new CommandError(`No value set at "${rawInput}".`);
+		}
+		saveSession(session);
+		console.log(`Removed "${rawInput}".`);
+		console.log("");
+		printQuery(session);
+		return;
+	}
+
+	const currentSchemaPath = queryNavToSchemaPath(session.navigationPath);
+
+	let spec = rawInput;
+	let explicitAlias: string | undefined;
+	const colonIdx = rawInput.lastIndexOf(":");
+	const afterColon = colonIdx > 0 ? rawInput.slice(colonIdx + 1) : "";
+	if (colonIdx > 0 && afterColon.length > 0 && !/[./:]/.test(afterColon)) {
+		spec = rawInput.slice(0, colonIdx);
+		explicitAlias = afterColon;
+	}
+
+	const normalizedSpec =
+		spec.includes(".") && !spec.includes("/") ? spec.replace(/\./g, "/") : spec;
+
+	if (normalizedSpec.includes("/")) {
+		const parts = normalizedSpec.split("/");
+		const leafName = parts.pop()!;
+		const dirPath = parts.join("/");
+		const resolved = parsePathInput(session.navigationPath, dirPath);
+		const targetSchemaPath = queryNavToSchemaPath(resolved);
+		const selector = explicitAlias ?? undefined;
+		const removed =
+			removeSelectionAtPath(session, [...targetSchemaPath, leafName], selector) ||
+			removeSelectionAtPath(session, [...targetSchemaPath, leafName]);
+		if (!removed) {
+			throw new CommandError(`No selected projection matching "${rawInput}" exists.`);
+		}
+		saveSession(session);
+		console.log(`Removed "${rawInput}".`);
+		console.log("");
+		printQuery(session);
+		return;
+	}
+
+	const focusedNode = getFocusedNodeAtPath(session, currentSchemaPath, false);
+	const parentId = focusedNode?.id ?? null;
+	const aliasedChild = getChildren(session, parentId).find(
+		(n): n is FieldProjectionNode => n.kind === "field" && n.alias === rawInput,
+	);
+	if (aliasedChild) {
+		const removed =
+			removeSelectionAtPath(session, [...currentSchemaPath, aliasedChild.fieldName], rawInput) ||
+			removeSelectionAtPath(session, [...currentSchemaPath, aliasedChild.fieldName]);
+		if (removed) {
+			saveSession(session);
+			console.log(`Removed "${rawInput}".`);
+			console.log("");
+			printQuery(session);
+			return;
+		}
+	}
+
+	const fieldRemoved =
+		removeSelectionAtPath(session, [...currentSchemaPath, rawInput], rawInput) ||
+		removeSelectionAtPath(session, [...currentSchemaPath, rawInput]);
+	if (fieldRemoved) {
+		saveSession(session);
+		console.log(`Removed "${rawInput}".`);
+		console.log("");
+		printQuery(session);
+		return;
+	}
+
+	const deepNode = findDescendantByAlias(session, parentId, rawInput);
+	if (deepNode) {
+		removeNodeByIdWithPrune(session, deepNode.id);
+		saveSession(session);
+		console.log(`Removed "${rawInput}".`);
+		console.log("");
+		printQuery(session);
+		return;
+	}
+
+	throw new CommandError(
+		`No selected projection matching "${rawInput}" exists under ${formatPath(session.navigationPath)}.` +
+			"\nTip: Use dot-path syntax (e.g. `rm Owner.Name.value`) or alias name. Run `select ls` to see all selections.",
+	);
+}
+
+export function queryMkdir(sessionId: string, rest: string[]): void {
+	const session = loadSession(sessionId);
+	const ctx = getNavigationContext(session.navigationPath);
+
+	if (isInArgsContext(session.navigationPath)) {
+		const fieldSchemaPath = getArgsFieldPath(session.navigationPath);
+		const inputSubPath = getInputSubPath(session.navigationPath);
+
+		if (inputSubPath.length === 0) {
+			throw new CommandError(
+				"Navigate to a specific argument first (e.g. `cd orderBy`), then use `mkdir` to add a list element.",
+			);
+		}
+
+		const argName = inputSubPath[0];
+		const nestedPath = inputSubPath.slice(1);
+
+		const idx = appendListElement(session, fieldSchemaPath, argName, nestedPath);
+		saveSession(session);
+		console.log(`Created element ${idx}/`);
+		console.log(`Navigate into it with: cd ${idx}`);
+		return;
+	}
+
+	if (ctx === "query") {
+		if (rest.length < 2) {
+			throw new CommandError(
+				"Usage: mkdir <alias> <fieldName>  — creates an aliased projection instance.",
+			);
+		}
+		const alias = rest[0];
+		const fieldName = rest[1];
+
+		const schemaPath = queryNavToSchemaPath(session.navigationPath);
+		const schema = getSessionSchema(session);
+
+		resolveFieldOnPath(schema, session.operation, schemaPath, fieldName);
+
+		const targetPath = [...schemaPath, fieldName];
+		createSiblingFieldInstance(session, targetPath, alias);
+		saveSession(session);
+		console.log(`Created aliased instance: ${alias}(${fieldName})/`);
+		console.log(`Navigate into it with: cd ${alias}`);
+		console.log("");
+		printQuery(session);
+		return;
+	}
+
+	throw new CommandError(
+		"`mkdir` works inside `query/` (to create aliased instances) or inside `@args/` (to add list elements).",
+	);
+}

package/src/commands/connect.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { getOrgAuth } from "../lib/auth.js";
+import { downloadSchema, getSchemaMetadata } from "../lib/introspect.js";
+
+export async function connectCommand(
+	orgAlias: string,
+	opts: { refresh?: boolean } = {},
+): Promise<void> {
+	console.log(`Connecting to ${orgAlias}...`);
+
+	const auth = await getOrgAuth(orgAlias);
+	console.log(`Authenticated as ${auth.username} on ${auth.instanceUrl}`);
+
+	if (!opts.refresh) {
+		const existing = getSchemaMetadata(auth.instanceUrl);
+		if (existing) {
+			const age = formatSchemaAge(new Date(existing.downloadedAt));
+			console.log(`Schema already cached: ${existing.typeCount} types (downloaded ${age}).`);
+			console.log(`Run \`graphiti connect ${orgAlias} --refresh\` to re-download.`);
+			return;
+		}
+	}
+
+	console.log("Downloading 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)`);
+	}, 100);
+
+	try {
+		const meta = await downloadSchema(auth);
+		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).`);
+	} catch (err) {
+		clearInterval(spinner);
+		process.stderr.write("\r");
+		throw err;
+	}
+}
+
+function formatSchemaAge(date: Date): string {
+	const diffMs = Date.now() - date.getTime();
+	const diffMin = Math.floor(diffMs / 60_000);
+	if (diffMin < 1) return "just now";
+	if (diffMin < 60) return `${diffMin}m ago`;
+	const diffHr = Math.floor(diffMin / 60);
+	if (diffHr < 24) return `${diffHr}h ago`;
+	const diffDays = Math.floor(diffHr / 24);
+	return `${diffDays}d ago`;
+}

package/src/commands/describe.ts

@@ -0,0 +1,246 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any -- graphiti traverses untyped schema/introspection JSON; see follow-up to replace with `unknown` + narrowing */
+
+import type { GraphQLSchema } from "graphql";
+import { getOrgAuth } from "../lib/auth.js";
+import {
+	getObjectInfo,
+	getRequiredCreateFields,
+	type ObjectInfoResult,
+	type FieldMetadata,
+} from "../lib/object-info.js";
+import { getSchema, inspectType } from "../lib/walker.js";
+
+export async function describeCommand(orgAlias: string, sObjectName: string): Promise<void> {
+	const auth = await getOrgAuth(orgAlias);
+	const schema = getSchema(auth.instanceUrl);
+
+	let objInfo: ObjectInfoResult | null = null;
+	try {
+		objInfo = await getObjectInfo(auth, orgAlias, sObjectName);
+	} catch {
+		// Fall back to schema-only
+	}
+
+	if (!objInfo) {
+		console.log(`Could not fetch ObjectInfo for "${sObjectName}". Showing schema-only view.`);
+		console.log("");
+		showSchemaOnlyView(schema, sObjectName);
+		return;
+	}
+
+	const _metaByApi = new Map(objInfo.fields.map((f) => [f.apiName, f]));
+
+	// Object header
+	const capabilities: string[] = [];
+	if (objInfo.queryable) capabilities.push("queryable");
+	if (objInfo.createable) capabilities.push("createable");
+	if (objInfo.updateable) capabilities.push("updateable");
+	if (objInfo.deletable) capabilities.push("deletable");
+	if (objInfo.searchable) capabilities.push("searchable");
+
+	console.log(
+		`${sObjectName}  "${objInfo.labelPlural ?? objInfo.label ?? sObjectName}"  (keyPrefix: ${objInfo.keyPrefix ?? "n/a"}, nameField: ${objInfo.nameFields.join(", ") || "n/a"})`,
+	);
+	console.log(`  ${capabilities.join(", ")}`);
+	if (objInfo.recordTypeInfos.length > 1) {
+		const available = objInfo.recordTypeInfos.filter((r) => r.available);
+		console.log(`  Record types: ${available.map((r) => r.name).join(", ")}`);
+	}
+	console.log("");
+
+	// Fields table
+	console.log(`Fields (${objInfo.fields.length}):`);
+	const sortedFields = [...objInfo.fields].sort((a, b) => {
+		// Name field first, then required, then alphabetical
+		if (a.nameField && !b.nameField) return -1;
+		if (!a.nameField && b.nameField) return 1;
+		if (a.required && !b.required) return -1;
+		if (!a.required && b.required) return 1;
+		return a.apiName.localeCompare(b.apiName);
+	});
+
+	for (const field of sortedFields) {
+		const line = formatFieldRow(field, objInfo);
+		console.log(`  ${line}`);
+	}
+
+	// Create fields
+	const createFields = objInfo.fields.filter((f) => f.createable);
+	const requiredOnCreate = getRequiredCreateFields(objInfo);
+	if (createFields.length > 0) {
+		console.log("");
+		console.log(
+			`Create fields (${createFields.length}):  ${createFields.map((f) => f.apiName).join(", ")}`,
+		);
+		if (requiredOnCreate.length > 0) {
+			console.log(`  Required on create: ${requiredOnCreate.map((f) => f.apiName).join(", ")}`);
+		} else {
+			console.log("  Required on create: (none -- all have defaults or are optional)");
+		}
+	}
+
+	// Update fields
+	const updateFields = objInfo.fields.filter((f) => f.updateable);
+	if (updateFields.length > 0) {
+		console.log("");
+		console.log(
+			`Update fields (${updateFields.length}):  ${updateFields.map((f) => f.apiName).join(", ")}`,
+		);
+		const createOnly = objInfo.fields.filter((f) => f.createable && !f.updateable);
+		if (createOnly.length > 0) {
+			console.log(`  Create-only (cannot update): ${createOnly.map((f) => f.apiName).join(", ")}`);
+		}
+	}
+
+	// Child relationships
+	const namedRels = objInfo.childRelationships.filter((cr) => cr.relationshipName);
+	if (namedRels.length > 0) {
+		console.log("");
+		console.log(`Child relationships (${namedRels.length}):`);
+		for (const cr of namedRels.slice(0, 20)) {
+			console.log(
+				`  ${cr.relationshipName!.padEnd(30)} -> ${cr.childObjectApiName}.${cr.fieldName}`,
+			);
+		}
+		if (namedRels.length > 20) {
+			console.log(`  ... ${namedRels.length - 20} more`);
+		}
+	}
+
+	// Picklists summary
+	if (objInfo.picklists.length > 0) {
+		console.log("");
+		console.log(`Picklist fields (${objInfo.picklists.length}):`);
+		for (const pl of objInfo.picklists) {
+			const vals = pl.values.map((v) => v.value).filter((v): v is string => v !== null);
+			console.log(`  ${pl.apiName.padEnd(25)} ${vals.join(", ")}`);
+		}
+	}
+
+	// Filter and OrderBy examples
+	console.log("");
+	console.log("Filter examples:");
+	const filterableFields = objInfo.fields.filter((f) => f.filterable && !f.compound);
+	const picklistField = filterableFields.find((f) => f.dataType === "PICKLIST");
+	const stringField = filterableFields.find((f) => f.dataType === "STRING" && f.filterable);
+	const dateField = filterableFields.find((f) => f.dataType === "DATETIME" && f.filterable);
+
+	if (picklistField) {
+		const pl = objInfo.picklists.find((p) => p.apiName === picklistField.apiName);
+		const val = pl?.values[0]?.value ?? "<value>";
+		console.log(`  { "${picklistField.apiName}": { "eq": "${val}" } }`);
+	}
+	if (stringField) {
+		console.log(`  { "${stringField.apiName}": { "like": "%search%" } }`);
+	}
+	if (picklistField && dateField) {
+		console.log(
+			`  { "and": [{ "${picklistField.apiName}": { "eq": "<value>" } }, { "${dateField.apiName}": { "gt": "2024-01-01T00:00:00Z" } }] }`,
+		);
+	}
+
+	const sortableFields = objInfo.fields.filter((f) => f.sortable && !f.compound);
+	if (sortableFields.length > 0) {
+		console.log("");
+		console.log("OrderBy examples:");
+		const first = sortableFields[0];
+		console.log(`  { "${first.apiName}": { "order": "DESC" } }`);
+		if (sortableFields.length > 1) {
+			console.log(
+				`  { "${sortableFields[0].apiName}": { "order": "ASC" }, "${sortableFields[1].apiName}": { "order": "DESC" } }`,
+			);
+		}
+	}
+}
+
+function formatFieldRow(field: FieldMetadata, objInfo: ObjectInfoResult): string {
+	const name = field.apiName.padEnd(28);
+	const dataType = (field.dataType ?? "UNKNOWN").padEnd(14);
+
+	const label = field.label && field.label !== field.apiName ? `"${field.label}"` : "";
+
+	const tags: string[] = [];
+	if (field.required && field.createable && !field.defaultedOnCreate) tags.push("required");
+	if (field.required && field.defaultedOnCreate) tags.push("auto");
+	if (field.nameField) tags.push("name-field");
+	if (!field.filterable) tags.push("no-filter");
+	if (!field.sortable) tags.push("no-sort");
+	if (!field.createable && !field.updateable) tags.push("read-only");
+	if (field.createable && !field.updateable) tags.push("create-only");
+	if (field.defaultedOnCreate && field.createable) tags.push("default-on-create");
+	if (field.calculated) tags.push("formula");
+	if (field.custom) tags.push("custom");
+	if (field.compound) tags.push("compound");
+	if (field.compoundFieldName) tags.push(`child of ${field.compoundFieldName}`);
+
+	let extra = "";
+	if (field.reference && field.referenceToInfos.length > 0) {
+		const targets = field.referenceToInfos.map((r) => {
+			const nameFields = r.nameFields.length > 0 ? ` (${r.nameFields.join(", ")})` : "";
+			return `${r.apiName}${nameFields}`;
+		});
+		extra = `-> ${targets.join(", ")}`;
+	}
+
+	const picklist = objInfo.picklists.find((p) => p.apiName === field.apiName);
+	if (picklist && picklist.values.length > 0) {
+		const vals = picklist.values.map((v) => v.value).filter((v): v is string => v !== null);
+		if (vals.length <= 6) {
+			extra = `values: [${vals.join(", ")}]`;
+		} else {
+			extra = `values: [${vals.slice(0, 5).join(", ")}, ... +${vals.length - 5}]`;
+		}
+	}
+
+	if (field.extraTypeInfo) {
+		extra += extra ? ` (${field.extraTypeInfo})` : `(${field.extraTypeInfo})`;
+	}
+
+	if (field.precision > 0) {
+		extra += extra ? ` precision=${field.precision}` : `precision=${field.precision}`;
+		if (field.scale > 0) extra += `,scale=${field.scale}`;
+	}
+
+	if (field.inlineHelpText) {
+		extra += extra ? ` -- ${field.inlineHelpText}` : field.inlineHelpText;
+	}
+
+	const tagStr = tags.length > 0 ? `[${tags.join(", ")}]` : "";
+	const labelStr = label ? `  ${label}` : "";
+
+	return `${name} ${dataType}${labelStr}  ${tagStr}  ${extra}`.trimEnd();
+}
+
+function showSchemaOnlyView(schema: GraphQLSchema, typeName: string): void {
+	try {
+		const info = inspectType(schema, typeName);
+		console.log(`${typeName} (${info.kind})`);
+		if (info.description) console.log(`  ${info.description}`);
+		console.log("");
+		if (info.fields.length > 0) {
+			console.log("Fields:");
+			for (const f of info.fields) {
+				console.log(`  ${f.name.padEnd(28)} ${f.typeName}${f.isNonNull ? "!" : ""}`);
+			}
+		}
+		if (info.inputFields.length > 0) {
+			console.log("Input fields:");
+			for (const f of info.inputFields) {
+				console.log(`  ${f.name.padEnd(28)} ${f.typeName}${f.isNonNull ? "!" : ""}`);
+			}
+		}
+		if (info.enumValues.length > 0) {
+			console.log("Values:");
+			for (const v of info.enumValues) {
+				console.log(`  ${v.name}${v.description ? `  -- ${v.description}` : ""}`);
+			}
+		}
+	} catch (_e: any) {
+		console.error(`Type "${typeName}" not found in schema.`);
+	}
+}