/**
 * 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 {
	formatArgsDirectoryListing,
	formatDirectoryListing,
	formatInputDirectoryListing,
	formatVariablesListing,
	parseSearchTerms,
	parseSearchRegex,
	type AliasEntry,
	type FieldLongInfo,
} from "../lib/formatter.js";
import { getCachedObjectInfo } from "../lib/object-info.js";
import { renderQuery } from "../lib/query-builder.js";
import {
	deepSetArg,
	deepSetVariableValue,
	formatPath,
	getArgsFieldPath,
	getChildren,
	getFocusedNodeAtPath,
	getInputSubPath,
	getNavigationContext,
	isAliasedSegment,
	isArgsSegment,
	isFragmentSegment,
	normalizeFragmentSegment,
	isInArgsContext,
	listInstancesAtPath,
	parseVariablePath,
	pathKey,
	queryNavToSchemaPath,
	selectLeaf,
	setVariableDefault,
	setVariableRuntimeValue,
	syncFocusFromNavigationPath,
	toSchemaPath,
	type FieldProjectionNode,
	type OperationType,
	type ProjectionNode,
	type QuerySession,
} from "../lib/session.js";
import {
	getRootFields,
	getSchema,
	resolveArgByName,
	resolveFieldOnPath,
	resolveInputPath,
	resolvePath,
	type InputWalkerResult,
	type WalkerResult,
} from "../lib/walker.js";

// Re-export for use by other modules and external consumers.
export type { WalkerResult, InputWalkerResult, QuerySession, FieldProjectionNode, ProjectionNode };

// ── CommandError ──────────────────────────────────────────────────────────────

export class CommandError extends Error {
	exitCode: number;
	constructor(message: string, exitCode = 1) {
		super(message);
		this.name = "CommandError";
		this.exitCode = exitCode;
	}
}

export const EXIT_CODES = {
	SUCCESS: 0,
	USER_ERROR: 1,
	VALIDATION_FAILURE: 2,
	EXECUTION_FAILURE: 3,
	AUTH_FAILURE: 4,
} as const;

// ── Schema helper ─────────────────────────────────────────────────────────────

export function getSessionSchema(session: QuerySession): GraphQLSchema {
	if (!session.instanceUrl) {
		throw new CommandError(
			`Session ${session.id} has no instanceUrl. Recreate it with \`graphiti query new <org>\`.`,
		);
	}
	return getSchema(session.instanceUrl);
}

// ── Internal helpers ──────────────────────────────────────────────────────────

export function walkerResultAtPath(
	session: QuerySession,
	navPath = session.navigationPath,
): WalkerResult {
	const schema = getSessionSchema(session);
	const schemaPath = queryNavToSchemaPath(navPath);
	return resolvePath(schema, session.operation, schemaPath);
}

export function parsePathInput(currentPath: string[], rawPath: string): string[] {
	if (!rawPath || rawPath === ".") return [...currentPath];
	const absolute = rawPath.startsWith("/");
	const parts = rawPath.split("/").filter((part) => part.length > 0);
	const base = absolute ? [] : [...currentPath];

	for (const part of parts) {
		if (part === ".") continue;
		if (part === "..") {
			base.pop();
			continue;
		}
		if (part === "@args" && base.length > 0 && base[base.length - 1] === "@args") {
			continue;
		}
		base.push(normalizeFragmentSegment(part));
	}

	return base;
}

export function resolveAliasSegments(session: QuerySession, navPath: string[]): string[] {
	const result = [...navPath];
	const queryIdx = result.indexOf("query");
	if (queryIdx === -1) return result;

	let parentId: string | null = null;
	for (let i = queryIdx + 1; i < result.length; i++) {
		const seg = result[i];
		if (isArgsSegment(seg) || isFragmentSegment(seg) || isAliasedSegment(seg)) break;

		const children = getChildren(session, parentId);
		const aliasMatch = children.find(
			(n): n is FieldProjectionNode => n.kind === "field" && n.alias === seg,
		);
		if (aliasMatch) {
			result[i] = `${aliasMatch.alias}(${aliasMatch.fieldName})`;
			const schemaPath = toSchemaPath(result.slice(queryIdx + 1, i + 1));
			session.focusByPath[pathKey(schemaPath)] = aliasMatch.id;
			parentId = aliasMatch.id;
			continue;
		}

		const fieldName = seg;
		const schemaPath = toSchemaPath(result.slice(queryIdx + 1, i + 1));
		const focusedId = session.focusByPath[pathKey(schemaPath)];
		const node =
			children.find((n) => n.id === focusedId) ??
			children.find((n) => n.kind === "field" && n.fieldName === fieldName);
		parentId = node?.id ?? null;
	}

	return result;
}

export function resolveDirectoryPathInSession(session: QuerySession, rawPath: string): string[] {
	let resolved = parsePathInput(session.navigationPath, rawPath);

	if (resolved.length === 0) return resolved;

	if (resolved.length > 0 && resolved[0] !== "query" && resolved[0] !== "variables") {
		resolved = ["query", ...resolved];
	}

	const ctx = getNavigationContext(resolved);

	if (ctx === "root") {
		throw new Error("At root, navigate into `query/` or `variables/`.");
	}

	if (ctx === "variables") {
		return resolveVariablesPath(session, resolved);
	}

	resolved = resolveAliasSegments(session, resolved);

	if (isInArgsContext(resolved)) {
		return resolveArgsPath(session, resolved);
	}

	const schemaPath = queryNavToSchemaPath(resolved);
	if (schemaPath.length === 0) return resolved;

	const schema = getSessionSchema(session);
	const wr = resolvePath(schema, session.operation, schemaPath);
	if (wr.isLeaf) {
		const last = resolved[resolved.length - 1];
		throw new Error(
			`Cannot cd into leaf node ${formatPath(resolved)} (${wr.typeName}). Use \`select ${last}\` instead.`,
		);
	}

	return resolved;
}

export function resolveArgsPath(session: QuerySession, resolved: string[]): string[] {
	const schema = getSessionSchema(session);
	const fieldSchemaPath = getArgsFieldPath(resolved);
	const inputSubPath = getInputSubPath(resolved);

	const wr = resolvePath(schema, session.operation, fieldSchemaPath);
	if (wr.args.length === 0) {
		throw new Error(`Field at ${formatPath(fieldSchemaPath)} has no arguments.`);
	}

	if (inputSubPath.length === 0) return resolved;

	const argName = inputSubPath[0];
	const argInfo = resolveArgByName(schema, wr, argName);
	const rawTypeName = argInfo.typeName;

	const remaining = inputSubPath.slice(1);
	if (remaining.length === 0) {
		const inputResult = resolveInputPath(schema, rawTypeName, []);
		if (inputResult.isLeaf && !inputResult.isList) {
			throw new Error(
				`Cannot cd into "${argName}" — it is a scalar (${inputResult.typeName}). Use \`assign ${argName} <value>\` instead.`,
			);
		}
		return resolved;
	}

	const inputResult = resolveInputPath(schema, rawTypeName, remaining);
	if (inputResult.isLeaf && !inputResult.isList) {
		const last = remaining[remaining.length - 1];
		throw new Error(
			`Cannot cd into "${last}" — it is a scalar (${inputResult.typeName}). Use \`assign\` to set its value.`,
		);
	}

	return resolved;
}

export function resolveVariablesPath(session: QuerySession, resolved: string[]): string[] {
	if (resolved.length === 1) return resolved;

	const varParsed = parseVariablePath(resolved);
	if (!varParsed) throw new Error("Invalid variables path.");

	const variable = session.variables.find((v) => v.name === varParsed.varName);
	if (!variable) {
		throw new Error(
			`Variable "$${varParsed.varName}" is not defined. Use \`define $${varParsed.varName} <Type>\` to create it.`,
		);
	}

	if (varParsed.inputSubPath.length === 0) {
		const schema = getSessionSchema(session);
		const rawTypeName = variable.type.replace(/[![\]]/g, "");
		const inputResult = resolveInputPath(schema, rawTypeName, []);
		if (inputResult.isLeaf && !inputResult.isList) {
			throw new Error(
				`Cannot cd into "$${varParsed.varName}" — it is a scalar type (${variable.type}). Use \`assign\` to set its value.`,
			);
		}
		return resolved;
	}

	const schema = getSessionSchema(session);
	const rawTypeName = variable.type.replace(/[![\]]/g, "");
	const inputResult = resolveInputPath(schema, rawTypeName, varParsed.inputSubPath);
	if (inputResult.isLeaf && !inputResult.isList) {
		const last = varParsed.inputSubPath[varParsed.inputSubPath.length - 1];
		throw new Error(
			`Cannot cd into "${last}" — it is a scalar (${inputResult.typeName}). Use \`assign\` to set its value.`,
		);
	}

	return resolved;
}

export function getCurrentInstances(session: QuerySession): ProjectionNode[] {
	if (session.navigationPath.length === 0) return [];
	return listInstancesAtPath(session, toSchemaPath(session.navigationPath));
}

export function getActiveInstanceId(session: QuerySession): string | undefined {
	return session.focusByPath[pathKey(toSchemaPath(session.navigationPath))];
}

export function buildSelectionInfo(session: QuerySession): {
	selectedFields: Set<string>;
	optionalFields: Set<string>;
	aliases: AliasEntry[];
} {
	const activeNode = getFocusedNodeAtPath(
		session,
		queryNavToSchemaPath(session.navigationPath),
		false,
	);
	const parentId = activeNode?.id ?? null;
	const children = getChildren(session, parentId);

	const selectedFields = new Set<string>();
	const optionalFields = new Set<string>();
	const aliases: AliasEntry[] = [];

	for (const child of children) {
		if (child.kind === "field") {
			selectedFields.add(child.fieldName);
			if (child.directives.some((d) => d.name === "optional")) {
				optionalFields.add(child.fieldName);
			}
			if (child.alias) {
				aliases.push({
					alias: child.alias,
					fieldName: child.fieldName,
					argCount: Object.keys(child.args).length,
					isActive: session.focusByPath[pathKey(child.schemaPath)] === child.id,
				});
			}
		}
	}

	return { selectedFields, optionalFields, aliases };
}

export function buildFieldLongInfo(
	session: QuerySession,
	wr: WalkerResult,
): Map<string, FieldLongInfo> {
	const map = new Map<string, FieldLongInfo>();
	const sObjectName = detectSObjectName(session);
	const objInfo = sObjectName ? getCachedObjectInfo(session.orgAlias, sObjectName) : null;

	if (!objInfo) return map;

	const metaByApi = new Map(objInfo.fields.map((f) => [f.apiName, f]));
	const relByName = new Map(
		objInfo.fields.filter((f) => f.relationshipName).map((f) => [f.relationshipName!, f]),
	);
	const childRelByName = new Map(
		objInfo.childRelationships
			.filter((cr) => cr.relationshipName)
			.map((cr) => [cr.relationshipName!, cr]),
	);

	for (const field of wr.fields) {
		const info: FieldLongInfo = {
			required: false,
			createable: true,
			updateable: true,
			defaultedOnCreate: false,
			filterable: true,
			sortable: true,
		};

		const meta = metaByApi.get(field.name);
		if (meta) {
			info.required = meta.required;
			info.createable = meta.createable;
			info.updateable = meta.updateable;
			info.defaultedOnCreate = meta.defaultedOnCreate;
			info.filterable = meta.filterable;
			info.sortable = meta.sortable;
			info.label = meta.label ?? undefined;
			info.dataType = meta.dataType ?? undefined;
			info.nameField = meta.nameField || undefined;
			info.compound = meta.compound || undefined;
			info.compoundFieldName = meta.compoundFieldName ?? undefined;
			info.extraTypeInfo = meta.extraTypeInfo ?? undefined;
			info.calculated = meta.calculated || undefined;
			info.custom = meta.custom || undefined;
			info.inlineHelpText = meta.inlineHelpText ?? undefined;
			if (meta.precision > 0) info.precision = meta.precision;
			if (meta.scale > 0) info.scale = meta.scale;

			if (meta.reference && meta.referenceToInfos.length > 0) {
				info.referenceTargets = meta.referenceToInfos.map((r) => r.apiName);
				const nameFields = meta.referenceToInfos.flatMap((r) => r.nameFields);
				if (nameFields.length > 0) info.referenceNameFields = nameFields;
			}
		}

		const relMeta = relByName.get(field.name);
		if (relMeta && relMeta.reference && relMeta.referenceToInfos.length > 0) {
			info.referenceTargets = relMeta.referenceToInfos.map((r) => r.apiName);
			const nameFields = relMeta.referenceToInfos.flatMap((r) => r.nameFields);
			if (nameFields.length > 0) info.referenceNameFields = nameFields;
		}

		const cr = childRelByName.get(field.name);
		if (cr) {
			info.childRelTarget = `${cr.childObjectApiName}.${cr.fieldName}`;
		}

		const picklist = objInfo.picklists.find((p) => p.apiName === field.name);
		if (picklist && picklist.values.length > 0) {
			info.picklistValues = picklist.values
				.map((v) => v.value)
				.filter((v): v is string => v !== null);
		}

		map.set(field.name, info);
	}

	return map;
}

export function formatAliasContext(session: QuerySession): string | null {
	if (session.navigationPath.length === 0) return null;
	const ctx = getNavigationContext(session.navigationPath);
	if (ctx !== "query" || isInArgsContext(session.navigationPath)) return null;

	const schemaPath = queryNavToSchemaPath(session.navigationPath);
	if (schemaPath.length === 0) return null;
	const instances = listInstancesAtPath(session, schemaPath);
	const fieldInstances = instances.filter((n): n is FieldProjectionNode => n.kind === "field");

	if (fieldInstances.length === 0) return null;

	const hasAliases = fieldInstances.some((n) => n.alias);
	if (fieldInstances.length === 1 && !hasAliases) return null;

	const activeId = session.focusByPath[pathKey(schemaPath)];

	if (fieldInstances.length === 1) {
		const inst = fieldInstances[0];
		const argCount = Object.keys(inst.args).length;
		const argPart = argCount > 0 ? ` [${argCount} arg${argCount === 1 ? "" : "s"}]` : "";
		return `Alias: ${inst.alias}${argPart}`;
	}

	const parts = fieldInstances.map((inst) => {
		const isActive = inst.id === activeId || (!activeId && inst === fieldInstances[0]);
		const name = inst.alias ?? "(unnamed)";
		const argCount = Object.keys(inst.args).length;
		const argPart = argCount > 0 ? ` [${argCount} arg${argCount === 1 ? "" : "s"}]` : "";
		return `${isActive ? "* " : "  "}${name}${argPart}`;
	});

	return `Aliases: ${parts.join("  |  ")}`;
}

export function detectSObjectName(session: QuerySession, overridePath?: string[]): string | null {
	const schemaPath = overridePath ?? queryNavToSchemaPath(session.navigationPath);

	if (session.operation === "mutation") {
		const idx = schemaPath.indexOf("uiapi");
		if (idx !== -1 && schemaPath[idx + 1]) {
			const match = schemaPath[idx + 1].match(/^(\w+?)(?:Create|Update|Delete)$/);
			if (match) return match[1];
		}
	}

	const queryIdx = schemaPath.indexOf("query");
	if (queryIdx !== -1 && schemaPath[queryIdx + 1]) {
		return schemaPath[queryIdx + 1];
	}

	const aggIdx = schemaPath.indexOf("aggregate");
	if (aggIdx !== -1 && schemaPath[aggIdx + 1]) {
		return schemaPath[aggIdx + 1];
	}

	return null;
}

export function printDirectory(
	session: QuerySession,
	opts: {
		search?: string;
		regex?: string;
		long?: boolean;
		all?: boolean;
		showFields?: boolean;
		dataCloud?: boolean;
	} = {},
): void {
	const ctx = getNavigationContext(session.navigationPath);

	if (session.navigationPath.length === 0 || ctx === "root") {
		console.log("  query/");
		console.log("  variables/");
		return;
	}

	if (ctx === "variables") {
		printVariablesDirectory(session, opts);
		return;
	}

	if (isInArgsContext(session.navigationPath)) {
		printArgsDirectory(session, opts);
		return;
	}

	const schemaPath = queryNavToSchemaPath(session.navigationPath);
	if (schemaPath.length === 0) {
		const schema = getSessionSchema(session);
		let rootFields = getRootFields(schema, session.operation);
		const rootMatcher = opts.regex
			? parseSearchRegex(opts.regex)
			: opts.search
				? parseSearchTerms(opts.search)
				: undefined;
		if (rootMatcher) {
			rootFields = rootFields.filter((f) => rootMatcher.test(f.name));
		}
		for (const f of rootFields) {
			console.log(`  ${f.name}/`);
		}
		return;
	}

	const walkerResult = walkerResultAtPath(session);
	const { selectedFields, optionalFields, aliases } = buildSelectionInfo(session);

	let fieldLongInfo: Map<string, FieldLongInfo> | undefined;
	if (opts.long) {
		fieldLongInfo = buildFieldLongInfo(session, walkerResult);
	}

	if (opts.showFields !== false) {
		console.log(
			formatDirectoryListing(walkerResult, {
				searchPattern: opts.search,
				regexPattern: opts.regex,
				long: opts.long,
				all: opts.all,
				hasArgs: walkerResult.args.length > 0,
				aliases,
				selectedFields,
				optionalFields,
				fieldLongInfo,
				dataCloud: opts.dataCloud,
			}),
		);
	}
}

export function printArgsDirectory(
	session: QuerySession,
	opts: {
		search?: string;
		regex?: string;
		long?: boolean;
		all?: boolean;
		showFields?: boolean;
	} = {},
): void {
	const schema = getSessionSchema(session);
	const fieldSchemaPath = getArgsFieldPath(session.navigationPath);
	const inputSubPath = getInputSubPath(session.navigationPath);
	const wr = resolvePath(schema, session.operation, fieldSchemaPath);

	const node = getFocusedNodeAtPath(session, fieldSchemaPath, false);
	const currentArgs = node && node.kind === "field" ? node.args : {};

	if (inputSubPath.length === 0) {
		console.log(
			formatArgsDirectoryListing(wr.args, !!opts.long, currentArgs, opts.search, opts.regex),
		);
		return;
	}

	const argName = inputSubPath[0];
	const argInfo = resolveArgByName(schema, wr, argName);
	const rawTypeName = argInfo.typeName;
	const remaining = inputSubPath.slice(1);
	const inputResult = resolveInputPath(schema, rawTypeName, remaining);

	let currentValues: Record<string, unknown> | undefined;
	let listElementCount: number | undefined;
	if (node && node.kind === "field") {
		const raw = node.args[argName];
		if (raw) {
			try {
				let parsed = JSON.parse(raw);
				for (const seg of remaining) {
					if (parsed === null || parsed === undefined) break;
					if (/^\d+$/.test(seg)) {
						parsed = Array.isArray(parsed) ? parsed[Number(seg)] : undefined;
					} else {
						parsed = typeof parsed === "object" ? parsed[seg] : undefined;
					}
				}
				if (inputResult.isList && Array.isArray(parsed)) {
					listElementCount = parsed.length;
					currentValues = {};
					for (let i = 0; i < parsed.length; i++) {
						currentValues[String(i)] = parsed[i];
					}
				} else if (typeof parsed === "object" && parsed !== null) {
					currentValues = parsed as Record<string, unknown>;
				}
			} catch {
				/* no current values */
			}
		}
	}

	console.log(
		formatInputDirectoryListing(
			inputResult,
			!!opts.long,
			currentValues,
			listElementCount,
			opts.search,
			opts.regex,
		),
	);
}

export function printVariablesDirectory(
	session: QuerySession,
	opts: {
		search?: string;
		regex?: string;
		long?: boolean;
		all?: boolean;
		showFields?: boolean;
	} = {},
): void {
	const varParsed = parseVariablePath(session.navigationPath);

	if (!varParsed) {
		console.log(formatVariablesListing(session.variables, !!opts.long));
		return;
	}

	const variable = session.variables.find((v) => v.name === varParsed.varName);
	if (!variable) {
		console.log(`Variable "$${varParsed.varName}" is not defined.`);
		return;
	}

	const schema = getSessionSchema(session);
	const rawTypeName = variable.type.replace(/[![\]]/g, "");
	const inputResult = resolveInputPath(schema, rawTypeName, varParsed.inputSubPath);

	let currentValues: Record<string, unknown> | undefined;
	let listElementCount: number | undefined;
	if (variable.runtimeValue) {
		try {
			let parsed = JSON.parse(variable.runtimeValue);
			for (const seg of varParsed.inputSubPath) {
				if (parsed === null || parsed === undefined) break;
				if (/^\d+$/.test(seg)) {
					parsed = Array.isArray(parsed) ? parsed[Number(seg)] : undefined;
				} else {
					parsed = typeof parsed === "object" ? parsed[seg] : undefined;
				}
			}
			if (inputResult.isList && Array.isArray(parsed)) {
				listElementCount = parsed.length;
				currentValues = {};
				for (let i = 0; i < parsed.length; i++) {
					currentValues[String(i)] = parsed[i];
				}
			} else if (typeof parsed === "object" && parsed !== null) {
				currentValues = parsed as Record<string, unknown>;
			}
		} catch {
			/* no current values */
		}
	}

	console.log(
		formatInputDirectoryListing(
			inputResult,
			!!opts.long,
			currentValues,
			listElementCount,
			opts.search,
			opts.regex,
		),
	);
}

export function printQuery(session: QuerySession): void {
	console.log("Query:");
	console.log(renderQuery(session));
}

export function requireFieldDirectory(session: QuerySession): string[] {
	const ctx = getNavigationContext(session.navigationPath);
	if (ctx !== "query") {
		throw new Error("This command requires a query field directory. Navigate into query/ first.");
	}
	const schemaPath = queryNavToSchemaPath(session.navigationPath);
	if (schemaPath.length === 0) {
		throw new Error(
			"You are at the root of the query tree. Navigate into a field first (e.g. `cd uiapi`).",
		);
	}
	const last = session.navigationPath[session.navigationPath.length - 1];
	if (isFragmentSegment(last)) {
		throw new Error(
			"The current directory is an inline fragment. Arguments and aliases apply to field directories only.",
		);
	}
	return schemaPath;
}

export function dotPathToSlashPath(dotPath: string): string {
	const segments: string[] = [];
	let i = 0;
	while (i < dotPath.length) {
		if (dotPath[i] === ".") {
			i++;
			continue;
		}
		if (dotPath[i] === "[") {
			const close = dotPath.indexOf("]", i);
			if (close === -1) {
				segments.push(dotPath.slice(i));
				break;
			}
			segments.push(normalizeFragmentSegment(dotPath.slice(i, close + 1)));
			i = close + 1;
		} else {
			let end = dotPath.indexOf(".", i);
			if (end === -1) end = dotPath.length;
			segments.push(normalizeFragmentSegment(dotPath.slice(i, end)));
			i = end;
		}
	}
	return segments.join("/");
}

export function selectLeafInSession(session: QuerySession, leafSpec: string, alias?: string): void {
	syncFocusFromNavigationPath(session);
	const schema = getSessionSchema(session);

	let normalizedSpec: string;
	if (leafSpec.includes(".") && !leafSpec.includes("/")) {
		normalizedSpec = dotPathToSlashPath(leafSpec);
	} else if (leafSpec.includes("/") && leafSpec.includes(".")) {
		const parts = leafSpec.split("/");
		const lastPart = parts.pop()!;
		if (lastPart.includes(".")) {
			const dotParts = dotPathToSlashPath(lastPart);
			normalizedSpec = [...parts, ...dotParts.split("/")].join("/");
		} else {
			normalizedSpec = leafSpec;
		}
	} else {
		normalizedSpec = leafSpec;
	}

	if (
		normalizedSpec.includes("/") &&
		!normalizedSpec.startsWith("/") &&
		!normalizedSpec.startsWith("query/") &&
		!normalizedSpec.startsWith("variables/") &&
		getNavigationContext(session.navigationPath) === "root"
	) {
		const firstSeg = normalizedSpec.split("/")[0];
		const rootFields = getRootFields(schema, session.operation);
		if (rootFields.some((f) => f.name === firstSeg)) {
			normalizedSpec = `query/${normalizedSpec}`;
		}
	}

	if (normalizedSpec.includes("/")) {
		const parts = normalizedSpec.split("/");
		const leafName = parts.pop()!;
		const dirPath = parts.join("/");

		let resolved = parsePathInput(session.navigationPath, dirPath);
		resolved = resolveAliasSegments(session, resolved);
		const schemaPath =
			getNavigationContext(resolved) === "query"
				? queryNavToSchemaPath(resolved)
				: toSchemaPath(resolved);

		let fieldResult: WalkerResult;
		try {
			fieldResult = resolveFieldOnPath(schema, session.operation, schemaPath, leafName);
		} catch (error: any) {
			if ((leafName === "value" || leafName === "displayValue") && parts.length >= 1) {
				try {
					const dirResult = resolvePath(schema, session.operation, schemaPath);
					if (dirResult.isLeaf) {
						const scalarFieldName = schemaPath[schemaPath.length - 1];
						const parentSchemaPath = schemaPath.slice(0, -1);
						selectLeaf(session, [...parentSchemaPath, scalarFieldName], alias);
						console.log(
							`  (auto-corrected: ${scalarFieldName} is a ${dirResult.typeName} scalar — selected directly without .${leafName})`,
						);
						return;
					}
				} catch {
					/* fall through to original error */
				}
			}

			// Auto-inject Record/ for mutation payloads: when a field isn't found on a Payload type,
			// find the Payload ancestor in the schemaPath and inject Record/ after it
			if (session.operation === "mutation" && error.message?.includes("Payload")) {
				try {
					// Walk the schemaPath to find where the Payload type is
					for (let pi = 1; pi <= schemaPath.length; pi++) {
						const candidatePath = schemaPath.slice(0, pi);
						let parentResult: WalkerResult;
						try {
							parentResult = resolvePath(schema, session.operation, candidatePath);
						} catch {
							continue;
						}
						if (
							parentResult.typeName.endsWith("Payload") &&
							parentResult.fields.some((f) => f.name === "Record")
						) {
							// Reconstruct path with Record/ injected after the Payload
							const afterPayload = schemaPath.slice(pi);
							const newSchemaPath = [...candidatePath, "Record", ...afterPayload];
							const recordResult = resolveFieldOnPath(
								schema,
								session.operation,
								newSchemaPath,
								leafName,
							);
							if (recordResult.isLeaf) {
								selectLeaf(session, [...newSchemaPath, leafName], alias);
								console.log(
									`  (auto-injected Record/: path adjusted to include Record/ inside ${parentResult.typeName})`,
								);
								return;
							}
							if (
								recordResult.typeName.endsWith("Value") &&
								recordResult.fields.some((f) => f.name === "value")
							) {
								selectLeaf(session, [...newSchemaPath, leafName, "value"], alias);
								console.log(
									`  (auto-injected Record/.../${leafName}/value inside ${parentResult.typeName})`,
								);
								return;
							}
							break;
						}
					}
				} catch {
					/* fall through to original error */
				}
			}

			if (session.navigationPath.length < 4 && parts[0] === "edges") {
				throw new Error(
					`${error.message}\nHint: "edges" is part of a connection type. Navigate to the connection first with \`cd query/uiapi/query/<SObject>\`, then select fields.`,
				);
			}

			throw error;
		}
		if (!fieldResult.isLeaf) {
			const leaves = fieldResult.fields
				.filter((f) => f.typeKind === "SCALAR" || f.typeKind === "ENUM")
				.map((f) => f.name);
			if (fieldResult.typeName.endsWith("Value") && leaves.includes("value")) {
				selectLeaf(session, [...schemaPath, leafName, "value"], alias);
				console.log(
					`  (auto-expanded: ${leafName} is a ${fieldResult.typeName} wrapper — selected ${leafName}/value)`,
				);
				return;
			}
			const leafHint = leaves.length > 0 ? ` Available leaves: ${leaves.join(", ")}` : "";
			throw new Error(
				`Cannot select "${leafName}" from ${formatPath(schemaPath)} because it resolves to ${fieldResult.typeName}. Navigate into it with \`cd ${normalizedSpec.replace(/\/[^/]+$/, "")}\` and select one of its leaf children.${leafHint}`,
			);
		}
		selectLeaf(session, [...schemaPath, leafName], alias);
		return;
	}

	const schemaPath = queryNavToSchemaPath(session.navigationPath);
	const fieldResult = resolveFieldOnPath(schema, session.operation, schemaPath, normalizedSpec);
	if (!fieldResult.isLeaf) {
		const leaves = fieldResult.fields
			.filter((f) => f.typeKind === "SCALAR" || f.typeKind === "ENUM")
			.map((f) => f.name);
		if (fieldResult.typeName.endsWith("Value") && leaves.includes("value")) {
			selectLeaf(session, [...schemaPath, normalizedSpec, "value"], alias);
			console.log(
				`  (auto-expanded: ${normalizedSpec} is a ${fieldResult.typeName} wrapper — selected ${normalizedSpec}/value)`,
			);
			return;
		}
		const leafHint = leaves.length > 0 ? ` Available leaves: ${leaves.join(", ")}` : "";
		throw new Error(
			`Cannot select "${normalizedSpec}" from ${formatPath(schemaPath)} because it resolves to ${fieldResult.typeName}. Navigate into it with \`cd ${normalizedSpec}\` and select one of its leaf children.${leafHint}`,
		);
	}
	selectLeaf(session, [...schemaPath, normalizedSpec], alias);
}

// ── Assignment / validation helpers ──────────────────────────────────────────

export function pathPointsToArgs(p: string): boolean {
	return p.includes("@args") || (p.includes("/") && p.split("/").some((s) => s === "@args"));
}

export function resolveArgType(
	session: QuerySession,
	fieldSchemaPath: string[],
	argName: string,
	inputPath: string[],
): { expectedType: string; argTypeKind: string } {
	const schema = getSessionSchema(session);
	const wr = resolvePath(schema, session.operation, fieldSchemaPath);
	const argInfo = resolveArgByName(schema, wr, argName);

	if (inputPath.length > 0) {
		const inputResult = resolveInputPath(schema, argInfo.typeName, inputPath);
		return { expectedType: inputResult.typeName, argTypeKind: inputResult.kind };
	}
	return { expectedType: argInfo.typeName, argTypeKind: argInfo.typeKind };
}

export function validateVariableAssignment(
	session: QuerySession,
	fieldSchemaPath: string[],
	argName: string,
	inputPath: string[],
	varRef: string,
): void {
	const cleanName = varRef.replace(/^\$/, "");
	const variable = session.variables.find((v) => v.name === cleanName);
	if (!variable) {
		throw new CommandError(
			`Variable "$${cleanName}" is not defined. Define it first with \`define $${cleanName} <path>\`.`,
		);
	}

	const { expectedType } = resolveArgType(session, fieldSchemaPath, argName, inputPath);
	const varBaseType = variable.type.replace(/[![\]]/g, "");

	if (varBaseType !== expectedType) {
		throw new CommandError(
			`Type mismatch: $${cleanName} is ${variable.type}, but ${argName}${inputPath.length > 0 ? "." + inputPath.join(".") : ""} expects ${expectedType}.`,
		);
	}
}

export function validateLiteralAssignment(
	session: QuerySession,
	fieldSchemaPath: string[],
	argName: string,
	inputPath: string[],
	value: string,
	contextHint: string,
): void {
	const schema = getSessionSchema(session);
	const wr = resolvePath(schema, session.operation, fieldSchemaPath);
	const argInfo = resolveArgByName(schema, wr, argName);
	const rawTypeName = argInfo.typeName;

	const isJsonLiteral = /^\s*[{[]/.test(value);

	if (inputPath.length > 0) {
		const inputResult = resolveInputPath(schema, rawTypeName, inputPath);
		if (!inputResult.isLeaf && !isJsonLiteral) {
			throw new CommandError(
				`Cannot assign to "${inputPath[inputPath.length - 1]}" — it is ${inputResult.typeName} (${inputResult.kind}). ` +
					contextHint,
			);
		}
	} else if (argInfo.typeKind !== "SCALAR" && argInfo.typeKind !== "ENUM" && !isJsonLiteral) {
		throw new CommandError(
			`Cannot assign a literal to "${argName}" — it is ${rawTypeName} (${argInfo.typeKind}). ` +
				contextHint,
		);
	}

	if (isJsonLiteral) {
		const sanitized = value.replace(/\$[a-zA-Z_]\w*/g, '"__var_placeholder__"');
		try {
			JSON.parse(sanitized);
		} catch {
			throw new CommandError(
				`Invalid JSON for "${argName}": ${value.slice(0, 60)}${value.length > 60 ? "..." : ""}`,
			);
		}
	}
}

export function assignViaPath(session: QuerySession, rawPath: string, value: string): void {
	const normalized = rawPath.replace(/\./g, "/");

	let resolved = parsePathInput(session.navigationPath, normalized);
	resolved = resolveAliasSegments(session, resolved);

	if (!isInArgsContext(resolved)) {
		throw new CommandError(
			`Path "${rawPath}" does not point into an @args/ directory. ` +
				"Use a path like `@args/first` or `Account/@args/where`.",
		);
	}

	const fieldSchemaPath = getArgsFieldPath(resolved);
	const inputSubPath = getInputSubPath(resolved);

	if (inputSubPath.length === 0) {
		throw new CommandError(
			"Path points to @args/ root. Specify a specific argument: e.g. `@args/first` or `@args/where`.",
		);
	}

	const argName = inputSubPath[0];
	const inputPath = inputSubPath.slice(1);

	if (value.startsWith("$")) {
		validateVariableAssignment(session, fieldSchemaPath, argName, inputPath, value);
	} else {
		validateLiteralAssignment(
			session,
			fieldSchemaPath,
			argName,
			inputPath,
			value,
			`Assign to a deeper path (e.g. \`@args/${argName}/...\`) or assign a $variable reference.`,
		);
	}

	deepSetArg(session, fieldSchemaPath, argName, inputPath, value);

	emitObjectInfoWarnings(session, fieldSchemaPath, argName, inputPath, value);
}

export function emitObjectInfoWarnings(
	session: QuerySession,
	fieldSchemaPath: string[],
	argName: string,
	inputPath: string[],
	value: string,
): void {
	const sObjectName = detectSObjectName(session, fieldSchemaPath);
	if (!sObjectName) return;

	const objInfo = getCachedObjectInfo(session.orgAlias, sObjectName);
	if (!objInfo) return;

	const metaByApi = new Map(objInfo.fields.map((f) => [f.apiName, f]));

	if ((argName === "where" || argName === "orderBy") && /^\s*[{[]/.test(value)) {
		try {
			const parsed = JSON.parse(value);
			const fieldNames = typeof parsed === "object" && parsed !== null ? Object.keys(parsed) : [];
			for (const fn of fieldNames) {
				if (fn === "and" || fn === "or" || fn === "not") continue;
				const meta = metaByApi.get(fn);
				if (!meta) continue;
				if (argName === "where" && !meta.filterable) {
					console.log(
						`  Warning: ${fn} is not filterable per ObjectInfo. This where clause may fail at runtime.`,
					);
				}
				if (argName === "orderBy" && !meta.sortable) {
					console.log(
						`  Warning: ${fn} is not sortable per ObjectInfo. This orderBy clause may fail at runtime.`,
					);
				}
			}
		} catch {
			/* not valid JSON — skip */
		}
		return;
	}

	const fieldName = inputPath.length > 0 ? inputPath[0] : argName;
	const isInWhere = argName === "where" || inputPath.includes("where");
	const isInOrderBy = argName === "orderBy" || inputPath.includes("orderBy");
	const meta = metaByApi.get(fieldName);

	if (meta) {
		if (isInWhere && !meta.filterable) {
			console.log(
				`  Warning: ${fieldName} is not filterable per ObjectInfo. This where clause may fail at runtime.`,
			);
		}
		if (isInOrderBy && !meta.sortable) {
			console.log(
				`  Warning: ${fieldName} is not sortable per ObjectInfo. This orderBy clause may fail at runtime.`,
			);
		}

		// Create-only field guard: warn when assigning a create-only field in an update mutation context
		const isMutationUpdate =
			session.operation === "mutation" && fieldSchemaPath.some((s) => /Update$/.test(s));
		if (isMutationUpdate && meta.createable && !meta.updateable) {
			console.log(
				`  Warning: ${fieldName} is create-only (not updateable). Setting it in an update mutation will fail at runtime.`,
			);
		}
	}

	if (!value.startsWith("$") && !value.startsWith("{") && !value.startsWith("[")) {
		const picklist = objInfo.picklists.find((p) => p.apiName === fieldName);
		if (picklist && picklist.values.length > 0) {
			const cleanValue = value.replace(/^"|"$/g, "");
			const validValues = picklist.values
				.map((v) => v.value)
				.filter((v): v is string => v !== null);
			if (validValues.length > 0 && !validValues.includes(cleanValue)) {
				console.log(`  Warning: "${cleanValue}" is not a known picklist value for ${fieldName}.`);
				console.log(`  Valid values: ${validValues.join(", ")}`);
			}
		}
	}
}

export function assignInArgsContext(
	session: QuerySession,
	segments: string[],
	value: string,
): void {
	const fieldSchemaPath = getArgsFieldPath(session.navigationPath);
	const currentInputSub = getInputSubPath(session.navigationPath);

	const fullInputPath = [...currentInputSub, ...segments];

	if (fullInputPath.length === 0) {
		throw new CommandError("Usage: assign <name> <value>");
	}

	const argName = fullInputPath[0];
	const inputPath = fullInputPath.slice(1);

	if (value.startsWith("$")) {
		validateVariableAssignment(session, fieldSchemaPath, argName, inputPath, value);
	} else {
		validateLiteralAssignment(
			session,
			fieldSchemaPath,
			argName,
			inputPath,
			value,
			`Navigate into it with \`cd\` and assign its leaf fields, or assign a $variable reference.`,
		);
	}

	deepSetArg(session, fieldSchemaPath, argName, inputPath, value);

	emitObjectInfoWarnings(session, fieldSchemaPath, argName, inputPath, value);
}

export function assignInVariablesContext(
	session: QuerySession,
	segments: string[],
	value: string,
	setDefault = false,
): void {
	const varParsed = parseVariablePath(session.navigationPath);

	if (!varParsed) {
		if (segments.length === 1 && segments[0].startsWith("$")) {
			const cleanName = segments[0].replace(/^\$/, "");
			const variable = session.variables.find((v) => v.name === cleanName);
			if (!variable) throw new CommandError(`Variable "$${cleanName}" is not defined.`);
			if (setDefault) {
				setVariableDefault(session, cleanName, value);
				console.log(`Set default for $${cleanName} = ${value}`);
			} else {
				setVariableRuntimeValue(session, cleanName, value);
			}
			return;
		}
		throw new CommandError(
			"Navigate into a variable first (e.g. `cd $myVar`) or specify: `assign [--default] $varName <value>`.",
		);
	}

	if (setDefault) {
		throw new CommandError(
			"--default can only be used on a whole variable (e.g. `assign --default $varName <value>`), not on nested paths.",
		);
	}

	const fullPath = [...varParsed.inputSubPath, ...segments];
	deepSetVariableValue(session, varParsed.varName, fullPath, value);
}

export function inferTypeFromArgsPath(
	schema: GraphQLSchema,
	operation: OperationType,
	fieldSchemaPath: string[],
	inputSubPath: string[],
): { inferredType: string; argName: string; argInputPath: string[] } {
	const argName = inputSubPath[0];
	const wr = resolvePath(schema, operation, fieldSchemaPath);
	const argInfo = resolveArgByName(schema, wr, argName);

	let inferredType: string;
	if (inputSubPath.length === 1) {
		inferredType = argInfo.typeName;
		if (argInfo.isList) inferredType = `[${inferredType}]`;
		if (argInfo.isNonNull) inferredType += "!";
	} else {
		const nestedPath = inputSubPath.slice(1);
		const inputResult = resolveInputPath(schema, argInfo.typeName, nestedPath);
		inferredType = inputResult.typeName;
		if (inputResult.isList) inferredType = `[${inferredType}]`;
		if (inputResult.isNonNull) inferredType += "!";
	}

	return { inferredType, argName, argInputPath: inputSubPath.slice(1) };
}