/**
 * 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 */

/**
 * Barrel module — re-exports all query subcommands so existing imports
 * like `from '../commands/query.js'` continue to work unchanged.
 */

// ── Re-exports from query-helpers ─────────────────────────────────────────────
export {
	CommandError,
	EXIT_CODES,
	getSessionSchema,
	walkerResultAtPath,
	parsePathInput,
	resolveAliasSegments,
	resolveDirectoryPathInSession,
	resolveArgsPath,
	resolveVariablesPath,
	getCurrentInstances,
	getActiveInstanceId,
	buildSelectionInfo,
	buildFieldLongInfo,
	formatAliasContext,
	detectSObjectName,
	printDirectory,
	printArgsDirectory,
	printVariablesDirectory,
	printQuery,
	requireFieldDirectory,
	dotPathToSlashPath,
	selectLeafInSession,
	pathPointsToArgs,
	resolveArgType,
	validateVariableAssignment,
	validateLiteralAssignment,
	assignViaPath,
	emitObjectInfoWarnings,
	assignInArgsContext,
	assignInVariablesContext,
	inferTypeFromArgsPath,
} from "./query-helpers.js";
export type { WalkerResult } from "./query-helpers.js";

// ── Re-exports from navigate ──────────────────────────────────────────────────
export { queryPwd, queryLs, queryCd } from "./navigate.js";

// ── Re-exports from build ─────────────────────────────────────────────────────
export { querySelect, querySelectLs, queryRm, queryMkdir } from "./build.js";

// ── Re-exports from args ──────────────────────────────────────────────────────
export { queryAssign, queryUnassign, queryDefine } from "./args.js";

// ── Re-exports from review ────────────────────────────────────────────────────
export {
	queryShow,
	queryShowJson,
	queryShowQueryOnly,
	queryValidate,
	queryValidateAll,
	queryExecute,
	queryCodegen,
	buildSampleInputFields,
	validateStrictMutation,
} from "./review.js";

// ── Re-exports from meta ──────────────────────────────────────────────────────
export { queryExample, printInputExamples, queryHelp } from "./meta.js";

// ── Re-exports from session-mgmt ──────────────────────────────────────────────
export {
	queryNew,
	queryClone,
	querySessionsList,
	querySessionsRm,
	querySessionsPrune,
	querySessionsClean,
	formatAge,
	parseDuration,
} from "./session-mgmt.js";

// ── Imports used by the dispatcher ────────────────────────────────────────────
import { queryAssign, queryUnassign, queryDefine } from "./args.js";
import { querySelectLs, queryRm, queryMkdir } from "./build.js";
import { queryHelp } from "./meta.js";
import { queryPwd, queryLs, queryCd } from "./navigate.js";
import {
	printQuery,
	selectLeafInSession,
	getSessionSchema,
	buildSelectionInfo,
	buildFieldLongInfo,
	walkerResultAtPath,
} from "./query-helpers.js";
import { CommandError } from "./query-helpers.js";
import {
	queryShow,
	queryShowJson,
	queryShowQueryOnly,
	queryValidate,
	queryValidateAll,
	queryExecute,
	queryCodegen,
} from "./review.js";
import {
	queryClone,
	querySessionsList,
	querySessionsRm,
	querySessionsPrune,
	querySessionsClean,
} from "./session-mgmt.js";
import { getOutputMode } from "../lib/command-registry.js";
import { renderQuery } from "../lib/query-builder.js";
import { formatHelp, isInteractiveMode } from "../lib/query-commands.js";
import {
	loadSession,
	saveSession,
	pushUndoSnapshot,
	popUndo,
	formatPath,
	getNavigationContext,
	isInArgsContext,
	queryNavToSchemaPath,
	getChildren,
	type FieldProjectionNode,
} from "../lib/session.js";
import { validateQuery } from "../lib/validator.js";
import { getRootFields } from "../lib/walker.js";

interface ParsedSetArgs {
	specs: { path: string; value: string }[];
	deferredVarDefs: [string, string][];
	cursorFieldPrefix: string;
	hasCursor: boolean;
}

/**
 * Parse inline key=value args with full shorthand support:
 * - where.Field=Value → where={"Field":{"eq":"Value"}}
 * - where.Field=$var → deferred variable binding
 * - orderBy=Field:DESC → orderBy.Field.order=DESC
 * - cursor → deferred $after variable definition
 */
function parseInlineSetArgs(tokens: string[]): ParsedSetArgs {
	const specs: { path: string; value: string }[] = [];
	const deferredVarDefs: [string, string][] = [];

	// Normalize: split any space-containing tokens (e.g. from quoted shell args)
	const expanded: string[] = [];
	for (const t of tokens) {
		if (t.includes(" ") && !t.startsWith("{") && !t.startsWith("[")) {
			expanded.push(...t.split(/\s+/));
		} else {
			expanded.push(t);
		}
	}

	const hasCursor = expanded.includes("cursor");
	const filteredNoCursor = hasCursor ? expanded.filter((t) => t !== "cursor") : expanded;

	let fieldPrefix = "";
	let startIdx = 0;

	if (filteredNoCursor.length > 0 && !filteredNoCursor[0].includes("=")) {
		fieldPrefix = filteredNoCursor[0];
		startIdx = 1;
	}

	for (let i = startIdx; i < filteredNoCursor.length; i++) {
		const token = filteredNoCursor[i];
		const eqIdx = token.indexOf("=");
		if (eqIdx > 0) {
			let key = token.slice(0, eqIdx);
			let val = token.slice(eqIdx + 1);

			// Collect continuation tokens for multi-word where values (e.g. where.Status=On Hold)
			const isWhereShorthand = /^(.*?)?where\.(\w+)(?:\.(\w+))?$/.test(key);
			if (isWhereShorthand && !val.startsWith("$") && !val.startsWith("{")) {
				while (i + 1 < filteredNoCursor.length) {
					const next = filteredNoCursor[i + 1];
					if (next.includes("=") || next === "cursor" || next.startsWith("--")) break;
					val += " " + next;
					i++;
				}
			}

			// orderBy shorthand: orderBy=Field:DESC → orderBy.Field.order=DESC
			if (key === "orderBy" || key.endsWith("/orderBy") || key.endsWith(".orderBy")) {
				const orderMatch = val.match(/^(\w+):(ASC|DESC)$/i);
				if (orderMatch) {
					key = `${key}.${orderMatch[1]}.order`;
					val = orderMatch[2].toUpperCase();
				}
			}

			// where shorthand: where.Field=Value → where={"Field":{"eq":"Value"}}
			const whereMatch = key.match(/^(.*?)?where\.(\w+)(?:\.(\w+))?$/);
			if (whereMatch) {
				const prefix = whereMatch[1] || "";
				const field = whereMatch[2];
				// Auto-detect `like` operator when value contains SQL wildcards (%) and no explicit operator
				const op =
					whereMatch[3] ||
					(val.includes("%") && !val.startsWith("$") && !val.startsWith("{") ? "like" : "eq");

				// Warn on empty where value — likely shell expanded $var to empty string
				if (val === "" && !isInteractiveMode()) {
					const hint = `Warning: ${key}= has an empty value. Did the shell expand a $variable?\n  Tip: use single quotes to prevent expansion: '${key}=$yourVar'`;
					console.error(hint);
				}

				if (val.startsWith("$")) {
					let resolvedPrefix = fieldPrefix;
					if (
						resolvedPrefix &&
						!resolvedPrefix.startsWith("/") &&
						!resolvedPrefix.startsWith("query/") &&
						!resolvedPrefix.startsWith("@args")
					) {
						resolvedPrefix = `query/${resolvedPrefix}`;
					}
					const varPath = resolvedPrefix
						? `${resolvedPrefix}/@args/${prefix}where/${field}/${op}`
						: `${prefix}where/${field}/${op}`;
					deferredVarDefs.push([val, varPath]);
					continue;
				}

				key = `${prefix}where`;
				let parsedVal: unknown = val;
				if (val === "null") parsedVal = null;
				else if (val === "true") parsedVal = true;
				else if (val === "false") parsedVal = false;
				else if (/^-?\d+(\.\d+)?$/.test(val)) parsedVal = Number(val);
				else parsedVal = val;
				val = JSON.stringify({ [field]: { [op]: parsedVal } });
			}

			let resolvedPrefix = fieldPrefix;
			if (
				resolvedPrefix &&
				!resolvedPrefix.startsWith("/") &&
				!resolvedPrefix.startsWith("query/") &&
				!resolvedPrefix.startsWith("@args")
			) {
				resolvedPrefix = `query/${resolvedPrefix}`;
			}
			const fullPath = resolvedPrefix ? `${resolvedPrefix}/@args/${key}` : key;
			specs.push({ path: fullPath, value: val });
		}
	}
	return { specs, deferredVarDefs, cursorFieldPrefix: fieldPrefix, hasCursor };
}

/**
 * Builds a JSON result object for commands that don't have their own JSON handler.
 * Called after the command executes to capture the result state.
 */
function buildJsonResult(
	command: string,
	sessionId: string,
	extra: Record<string, unknown> = {},
): Record<string, unknown> {
	try {
		const session = loadSession(sessionId);
		const result: Record<string, unknown> = { command, ...extra };

		switch (command) {
			case "pwd":
				result.path = formatPath(session.navigationPath);
				break;

			case "cd":
				result.path = formatPath(session.navigationPath);
				break;

			case "ls": {
				result.path = formatPath(session.navigationPath);
				const ctx = getNavigationContext(session.navigationPath);
				if (ctx === "query" && !isInArgsContext(session.navigationPath)) {
					const schemaPath = queryNavToSchemaPath(session.navigationPath);
					if (schemaPath.length > 0) {
						try {
							const schema = getSessionSchema(session);
							const _wr = getRootFields(schema, session.operation);
							const walkerRes = walkerResultAtPath(session);
							const { selectedFields } = buildSelectionInfo(session);
							const fieldLongInfo = buildFieldLongInfo(session, walkerRes);
							result.type = { name: walkerRes.typeName, kind: walkerRes.kind };
							result.hasArgs = walkerRes.args.length > 0;
							result.args = walkerRes.args.map((a) => ({
								name: a.name,
								type: a.typeName,
								required: a.isNonNull,
							}));
							result.fields = walkerRes.fields.map((f) => {
								const entry: Record<string, unknown> = {
									name: f.name,
									type: f.typeName,
									kind: f.typeKind,
									selected: selectedFields.has(f.name),
								};
								const longInfo = fieldLongInfo.get(f.name);
								if (longInfo) entry.metadata = longInfo;
								return entry;
							});
							result.totalFields = walkerRes.fields.length;
						} catch {
							/* path may not resolve */
						}
					}
				}
				break;
			}

			case "select":
			case "drop":
			case "alias":
			case "set":
			case "unset":
			case "var":
			case "optional":
			case "reset":
			case "undo":
			case "clone":
				result.query = renderQuery(session);
				result.path = formatPath(session.navigationPath);
				result.selectedFields = session.nodes.filter(
					(n) => n.kind === "field" && getChildren(session, n.id).length === 0,
				).length;
				result.totalNodes = session.nodes.length;
				if (session.variables.length > 0) {
					result.variables = session.variables.map((v) => ({
						name: v.name,
						type: v.type,
						defaultValue: v.defaultValue ?? null,
						runtimeValue: v.runtimeValue ?? null,
					}));
				}
				break;

			case "check": {
				const schema = getSessionSchema(session);
				const queryString = renderQuery(session);
				const errors = validateQuery(schema, queryString);
				result.valid = errors.length === 0;
				result.query = queryString;
				if (errors.length > 0) {
					result.errors = errors.map((e) => ({
						message: typeof e === "string" ? e : ((e as any).message ?? String(e)),
					}));
				}
				break;
			}

			default:
				break;
		}

		return result;
	} catch {
		return { command, ...extra };
	}
}

// ── Shared dispatcher ─────────────────────────────────────────────────────────

export async function dispatchQueryCommand(
	sessionId: string,
	subcommand: string | undefined,
	rawRest: string[],
	opts: {
		search?: string;
		regex?: string;
		long?: boolean;
		all?: boolean;
		as?: string;
		quiet?: boolean;
		dataCloud?: boolean;
	} = {},
): Promise<Record<string, unknown> | void> {
	const jsonMode = rawRest.includes("--json") || getOutputMode() === "json";

	// Extract standard display options from rawRest (needed for chain mode where
	// opts is empty and flags like --search, -l, -a arrive as raw tokens).
	const rest: string[] = [];
	for (let i = 0; i < rawRest.length; i++) {
		const tok = rawRest[i];
		if (tok === "--json") continue;
		if (tok === "--search" && i + 1 < rawRest.length) {
			opts.search = opts.search ?? rawRest[++i];
		} else if (tok === "--regex" && i + 1 < rawRest.length) {
			opts.regex = opts.regex ?? rawRest[++i];
		} else if (tok === "--as" && i + 1 < rawRest.length) {
			opts.as = opts.as ?? rawRest[++i];
		} else if (tok === "-l" || tok === "--long") {
			opts.long = true;
		} else if (tok === "-a" || tok === "--all") {
			opts.all = true;
		} else if (tok === "-q" || tok === "--quiet") {
			opts.quiet = true;
		} else if (tok === "--data-cloud") {
			opts.dataCloud = true;
		} else {
			rest.push(tok);
		}
	}

	if (!subcommand) {
		if (jsonMode) {
			queryShowJson(sessionId);
			return;
		}
		queryShow(sessionId);
		return;
	}

	// Suppress human output in JSON mode by temporarily redirecting console.log
	const origLog = console.log;
	const origError = console.error;
	const capturedOutput: string[] = [];
	if (jsonMode && subcommand !== "show" && subcommand !== "run" && subcommand !== "codegen") {
		console.log = (...args: unknown[]) => {
			capturedOutput.push(args.map(String).join(" "));
		};
		console.error = (...args: unknown[]) => {
			capturedOutput.push(args.map(String).join(" "));
		};
	}

	try {
		if (!isInteractiveMode() && !opts.quiet && !jsonMode) {
			const echoArgs = [...rest];
			if (opts.long) echoArgs.push("-l");
			if (opts.all) echoArgs.push("-a");
			if (opts.search) echoArgs.push(`--search ${opts.search}`);
			if (opts.regex) echoArgs.push(`--regex ${opts.regex}`);
			if (opts.as) echoArgs.push(`--as ${opts.as}`);
			const echoLine =
				echoArgs.length > 0 ? `> ${subcommand} ${echoArgs.join(" ")}` : `> ${subcommand}`;
			origLog(echoLine);
		}

		const MUTATING_COMMANDS = new Set([
			"cd",
			"select",
			"drop",
			"set",
			"unset",
			"alias",
			"var",
			"optional",
			"reset",
		]);
		if (subcommand && MUTATING_COMMANDS.has(subcommand)) {
			const session = loadSession(sessionId);
			pushUndoSnapshot(session);
			saveSession(session);
		}

		switch (subcommand) {
			case "pwd": {
				queryPwd(sessionId);
				break;
			}

			case "cd": {
				const target = rest[0] ?? "/";
				queryCd(sessionId, target);
				break;
			}

			case "select": {
				if (rest[0] === "ls") {
					querySelectLs(sessionId);
					break;
				}
				const applyOptional = rest.includes("--optional");
				const selectItems: { spec: string; alias?: string }[] = [];
				for (const rawToken of rest) {
					if (rawToken.startsWith("--")) continue;
					const subTokens = rawToken.includes(" ")
						? rawToken.split(/\s+/).filter(Boolean)
						: [rawToken];
					for (const token of subTokens) {
						const colonIdx = token.lastIndexOf(":");
						const afterColon = colonIdx > 0 ? token.slice(colonIdx + 1) : "";
						if (colonIdx > 0 && afterColon.length > 0 && !/[./:]/.test(afterColon)) {
							selectItems.push({ spec: token.slice(0, colonIdx), alias: afterColon });
						} else {
							selectItems.push({ spec: token });
						}
					}
				}
				if (selectItems.length === 1 && !selectItems[0].alias && opts.as) {
					selectItems[0].alias = opts.as;
				}
				if (selectItems.length === 0) {
					console.error(
						"Usage: select <path[:alias]> [<path[:alias]> ...] or select <leaf> --as <alias>",
					);
					return;
				}
				const session = loadSession(sessionId);
				const successMessages: string[] = [];
				const failureMessages: string[] = [];
				for (const item of selectItems) {
					const snapNodes = JSON.parse(JSON.stringify(session.nodes));
					const snapFocus = JSON.parse(JSON.stringify(session.focusByPath));
					const nodeCountBefore = session.nodes.length;
					try {
						selectLeafInSession(session, item.spec, item.alias);
						if (applyOptional) {
							for (let ni = nodeCountBefore; ni < session.nodes.length; ni++) {
								const node = session.nodes[ni];
								if (!node.directives.some((d) => d.name === "optional")) {
									node.directives.push({ name: "optional", args: {} });
								}
							}
						}
						const optTag = applyOptional ? " @optional" : "";
						successMessages.push(
							`Selected ${item.spec}${item.alias ? ` as ${item.alias}` : ""}${optTag}.`,
						);
					} catch (error: any) {
						session.nodes = snapNodes;
						session.focusByPath = snapFocus;
						failureMessages.push(`Failed: ${item.spec} — ${error.message}`);
					}
				}
				if (successMessages.length > 0) {
					saveSession(session);
				}
				if (!opts.quiet) {
					for (const msg of successMessages) console.log(msg);
					if (failureMessages.length > 0) {
						console.log("");
						for (const msg of failureMessages) console.error(msg);
					}
					if (successMessages.length > 0) {
						console.log("");
						printQuery(session);
					}
				}
				if (failureMessages.length > 0 && successMessages.length === 0) {
					throw new Error(failureMessages.join("\n"));
				}
				break;
			}

			case "ls": {
				const lsDirs = rest.filter((r) => !r.startsWith("-"));
				await queryLs(
					sessionId,
					{
						search: opts.search,
						regex: opts.regex,
						long: opts.long,
						all: opts.all,
						dataCloud: opts.dataCloud,
					},
					lsDirs.length > 0 ? lsDirs : undefined,
				);
				break;
			}

			case "set": {
				const isDefault = rest.includes("--default");
				const filtered = rest.filter((r) => r !== "--default" && !r.startsWith("--"));

				// cursor shorthand: `set uiapi/query/Case cursor` or mixed with other args
				// Extract 'cursor' token and process it after the other set operations
				const hasCursor = filtered.includes("cursor");
				const filteredNoCursor = hasCursor ? filtered.filter((t) => t !== "cursor") : filtered;

				const specs: { path: string; value: string }[] = [];

				const hasKeyValue = filteredNoCursor.some(
					(t) => t.includes("=") && !t.startsWith("$") && !t.startsWith("{") && !t.startsWith("["),
				);

				// Determine field prefix (first non-key=value token)
				let cursorFieldPrefix = "";

				// Deferred variable definitions from where.Field=$var shorthand
				const deferredVarDefs: [string, string][] = [];

				if (hasKeyValue) {
					let fieldPrefix = "";
					let startIdx = 0;

					if (filteredNoCursor.length > 0 && !filteredNoCursor[0].includes("=")) {
						fieldPrefix = filteredNoCursor[0];
						startIdx = 1;
					}
					cursorFieldPrefix = fieldPrefix;

					for (let i = startIdx; i < filteredNoCursor.length; i++) {
						const token = filteredNoCursor[i];
						const eqIdx = token.indexOf("=");
						if (eqIdx > 0) {
							let key = token.slice(0, eqIdx);
							let val = token.slice(eqIdx + 1);

							// orderBy shorthand: orderBy=Field:DESC → orderBy.Field.order=DESC
							if (key === "orderBy" || key.endsWith("/orderBy") || key.endsWith(".orderBy")) {
								const orderMatch = val.match(/^(\w+):(ASC|DESC)$/i);
								if (orderMatch) {
									key = `${key}.${orderMatch[1]}.order`;
									val = orderMatch[2].toUpperCase();
								}
							}

							// where shorthand: where.Field=Value → where={"Field":{"eq":"Value"}}
							// Also supports: where.Field.op=Value (e.g. where.Name.like=%test%)
							// Variable binding: where.Field=$var → defines $var at where/Field/eq
							const whereMatch = key.match(/^(.*?)?where\.(\w+)(?:\.(\w+))?$/);
							if (whereMatch) {
								const prefix = whereMatch[1] || "";
								const field = whereMatch[2];
								// Auto-detect `like` operator when value contains SQL wildcards (%) and no explicit operator
								const op =
									whereMatch[3] ||
									(val.includes("%") && !val.startsWith("$") && !val.startsWith("{")
										? "like"
										: "eq");

								// If value starts with $, treat as variable binding
								if (val.startsWith("$")) {
									let resolvedPrefix = fieldPrefix;
									if (
										resolvedPrefix &&
										!resolvedPrefix.startsWith("/") &&
										!resolvedPrefix.startsWith("query/") &&
										!resolvedPrefix.startsWith("@args")
									) {
										resolvedPrefix = `query/${resolvedPrefix}`;
									}
									const varPath = resolvedPrefix
										? `${resolvedPrefix}/@args/${prefix}where/${field}/${op}`
										: `${prefix}where/${field}/${op}`;
									deferredVarDefs.push([val, varPath]);
									continue;
								}

								key = `${prefix}where`;
								// Try to parse as number/boolean/null, otherwise use string
								let parsedVal: unknown = val;
								if (val === "null") parsedVal = null;
								else if (val === "true") parsedVal = true;
								else if (val === "false") parsedVal = false;
								else if (/^-?\d+(\.\d+)?$/.test(val)) parsedVal = Number(val);
								else parsedVal = val;
								val = JSON.stringify({ [field]: { [op]: parsedVal } });
							}

							let resolvedPrefix = fieldPrefix;
							if (
								resolvedPrefix &&
								!resolvedPrefix.startsWith("/") &&
								!resolvedPrefix.startsWith("query/") &&
								!resolvedPrefix.startsWith("@args")
							) {
								resolvedPrefix = `query/${resolvedPrefix}`;
							}
							const fullPath = resolvedPrefix ? `${resolvedPrefix}/@args/${key}` : key;
							specs.push({ path: fullPath, value: val });
						} else {
							if (i + 1 < filteredNoCursor.length) {
								let resolvedPrefix = fieldPrefix;
								if (
									resolvedPrefix &&
									!resolvedPrefix.startsWith("/") &&
									!resolvedPrefix.startsWith("query/") &&
									!resolvedPrefix.startsWith("@args")
								) {
									resolvedPrefix = `query/${resolvedPrefix}`;
								}
								const path = resolvedPrefix ? `${resolvedPrefix}/@args/${token}` : token;
								specs.push({ path, value: filteredNoCursor[i + 1] });
								i++;
							}
						}
					}
				} else if (filteredNoCursor.length > 0) {
					for (let i = 0; i < filteredNoCursor.length; i += 2) {
						const dotPath = filteredNoCursor[i];
						const value = filteredNoCursor[i + 1];
						if (!dotPath || value === undefined) {
							console.error("Usage: set [<field-path>] <key>=<value> ... | set <path> <value>");
							return;
						}
						specs.push({ path: dotPath, value });
					}
				}

				if (specs.length === 0 && !hasCursor && deferredVarDefs.length === 0) {
					console.error("Usage: set [<field-path>] <key>=<value> ... | set <path> <value>");
					return;
				}
				if (specs.length > 0) {
					queryAssign(sessionId, specs, isDefault);
				}

				// Process deferred variable definitions from where.Field=$var shorthand
				for (const [varName, varPath] of deferredVarDefs) {
					queryDefine(sessionId, [varName, varPath]);
				}

				// cursor shorthand: defines $after variable at the after arg of the field prefix
				// and auto-selects pageInfo { hasNextPage, endCursor } for pagination support
				if (hasCursor) {
					// Determine the field prefix for cursor — use the first non-key=value token
					const prefix = cursorFieldPrefix || filteredNoCursor[0] || "";
					if (!prefix) {
						console.error(
							"cursor shorthand requires a field path prefix, e.g. `set uiapi/query/Case cursor`",
						);
						return;
					}
					const cursorPath = `${prefix}/@args/after`;
					queryDefine(sessionId, ["$after", cursorPath]);

					// Auto-select pageInfo fields needed for pagination loops
					const session = loadSession(sessionId);
					const pageInfoHasNext = `${prefix}/pageInfo/hasNextPage`;
					const pageInfoEndCursor = `${prefix}/pageInfo/endCursor`;
					try {
						selectLeafInSession(session, pageInfoHasNext);
						selectLeafInSession(session, pageInfoEndCursor);
						saveSession(session);
					} catch {
						// pageInfo may already be selected or path may not resolve — ignore
					}
				}
				break;
			}

			case "unset": {
				const target = rest[0];
				if (!target) {
					console.error("Usage: unset <path> (e.g. unset first, unset where/Name/like)");
					return;
				}
				queryUnassign(sessionId, target);
				break;
			}

			case "alias": {
				queryMkdir(sessionId, rest);
				break;
			}

			case "var": {
				if (rest.length === 0) {
					console.error("Usage: var $name [<path> | <Type>] [default]");
					return;
				}
				queryDefine(sessionId, rest);
				break;
			}

			case "show": {
				if (rest.includes("--query-only") || rest.includes("--raw")) {
					queryShowQueryOnly(sessionId);
				} else if (jsonMode) {
					queryShowJson(sessionId);
				} else {
					queryShow(sessionId);
				}
				break;
			}

			case "check": {
				if (rest.includes("--all") || opts.all) {
					queryValidateAll();
					break;
				}
				const strict = rest.includes("--strict");
				const withCodegen = rest.includes("--codegen");
				await queryValidate(sessionId, strict, { codegen: withCodegen });
				break;
			}

			case "run": {
				const adHoc: Record<string, string> = {};
				let dryRun = false;
				for (let i = 0; i < rest.length; i++) {
					if (rest[i] === "--dry-run") {
						dryRun = true;
						continue;
					}
					if (rest[i] === "--var" && rest[i + 1]) {
						const token = rest[++i];
						const eq = token.indexOf("=");
						if (eq !== -1) {
							adHoc[token.slice(0, eq).replace(/^\$/, "")] = token.slice(eq + 1);
						} else if (rest[i + 1] !== undefined && !rest[i + 1].startsWith("--")) {
							adHoc[token.replace(/^\$/, "")] = rest[++i];
						}
					}
				}
				await queryExecute(sessionId, Object.keys(adHoc).length > 0 ? adHoc : undefined, dryRun);
				if (!dryRun) {
					console.log("");
					console.log("Tip: Run `show` for a full session snapshot.");
				}
				break;
			}

			case "drop": {
				const fieldOrAlias = rest[0];
				if (!fieldOrAlias) {
					console.error("Usage: drop <target> (field, alias, arg, variable, or list index)");
					return;
				}
				queryRm(sessionId, fieldOrAlias);
				break;
			}

			case "help": {
				const topic = rest[0];
				queryHelp(sessionId, topic);
				break;
			}

			case "sessions": {
				const sessionsAction = rest[0];
				if (sessionsAction === "rm" || sessionsAction === "delete" || sessionsAction === "remove") {
					const target = rest[1];
					if (!target) {
						console.error("Usage: sessions rm <session-id-or-name>");
						return;
					}
					querySessionsRm(target);
				} else if (sessionsAction === "prune") {
					const olderThanIdx = rest.indexOf("--older-than");
					const duration = olderThanIdx !== -1 ? rest[olderThanIdx + 1] : undefined;
					if (!duration) {
						console.error("Usage: sessions prune --older-than <duration> (e.g. 1d, 12h, 30m)");
						return;
					}
					querySessionsPrune(duration);
				} else if (sessionsAction === "clean") {
					querySessionsClean();
				} else if (sessionsAction) {
					console.error(
						`Unknown sessions action "${sessionsAction}". Use "rm", "prune", or "clean".`,
					);
				} else {
					querySessionsList();
				}
				break;
			}

			case "reset": {
				const session = loadSession(sessionId);
				session.nodes = [];
				session.variables = [];
				session.focusByPath = {};
				session.navigationPath = [];
				saveSession(session);
				console.log("Session reset. All selections, arguments, and variables cleared.");
				break;
			}

			case "undo": {
				const session = loadSession(sessionId);
				const restored = popUndo(session);
				if (!restored) {
					console.log("Nothing to undo.");
					break;
				}

				const diffs: string[] = [];
				if (formatPath(session.navigationPath) !== formatPath(restored.navigationPath)) {
					diffs.push(`navigation → ${formatPath(restored.navigationPath)}`);
				}
				const nodeDelta = session.nodes.length - restored.nodes.length;
				if (nodeDelta > 0) diffs.push(`${nodeDelta} node${nodeDelta !== 1 ? "s" : ""} removed`);
				else if (nodeDelta < 0)
					diffs.push(`${-nodeDelta} node${-nodeDelta !== 1 ? "s" : ""} restored`);
				const addedVars = session.variables.filter(
					(v) => !restored.variables.some((rv) => rv.name === v.name),
				);
				const removedVars = restored.variables.filter(
					(v) => !session.variables.some((cv) => cv.name === v.name),
				);
				for (const v of addedVars) diffs.push(`removed $${v.name}`);
				for (const v of removedVars) diffs.push(`restored $${v.name}`);
				if (diffs.length === 0) {
					const currArgsJson = JSON.stringify(
						session.nodes
							.filter((n) => n.kind === "field")
							.map((n) => ({ id: n.id, args: (n as FieldProjectionNode).args })),
					);
					const restArgsJson = JSON.stringify(
						restored.nodes
							.filter((n) => n.kind === "field")
							.map((n) => ({ id: n.id, args: (n as FieldProjectionNode).args })),
					);
					if (currArgsJson !== restArgsJson) diffs.push("argument values changed");
				}

				saveSession(restored);
				const desc = diffs.length > 0 ? diffs.join(", ") : "last change";
				console.log(`Undone: ${desc}`);
				console.log("");
				printQuery(restored);
				break;
			}

			case "clone": {
				const nameIdx = rest.indexOf("--name");
				const cloneName =
					nameIdx !== -1
						? rest[nameIdx + 1]
						: rest[0] && !rest[0].startsWith("--")
							? rest[0]
							: undefined;
				const forceClone = rest.includes("--force") || rest.includes("-f");
				const cloneResult = queryClone(sessionId, cloneName, { force: forceClone });

				// Helper: collect args after a flag until the next --flag
				const collectFlagArgs = (flag: string): string[] => {
					const idx = rest.indexOf(flag);
					if (idx === -1) return [];
					const args: string[] = [];
					for (let j = idx + 1; j < rest.length; j++) {
						if (rest[j].startsWith("--") || rest[j].startsWith("-s")) break;
						args.push(rest[j]);
					}
					return args;
				};

				// Apply flags in order: --unset first (remove inherited args), then --set, then --var.
				// This ensures `clone --unset where --var $x path` works as expected:
				// the old where is removed before the new variable binding creates a new one.
				const clonedId = cloneResult.name ?? cloneResult.id;

				// 1. Apply --unset to remove args from the cloned session
				const unsetArgs = collectFlagArgs("--unset");
				if (unsetArgs.length > 0 && clonedId) {
					for (const path of unsetArgs) {
						queryUnassign(clonedId, path);
					}
				}

				// 2. Apply --set args to the cloned session (with full shorthand support)
				const setArgs = collectFlagArgs("--set");
				if (setArgs.length > 0 && clonedId) {
					const parsed = parseInlineSetArgs(setArgs);
					if (parsed.specs.length > 0) {
						queryAssign(clonedId, parsed.specs);
					}
					for (const [varName, varPath] of parsed.deferredVarDefs) {
						queryDefine(clonedId, [varName, varPath]);
					}
					if (parsed.hasCursor) {
						const prefix = parsed.cursorFieldPrefix || "";
						if (prefix) {
							const cursorPath = `${prefix}/@args/after`;
							queryDefine(clonedId, ["$after", cursorPath]);
							// Auto-select pageInfo for pagination
							const clonedSession = loadSession(clonedId);
							try {
								selectLeafInSession(clonedSession, `${prefix}/pageInfo/hasNextPage`);
								selectLeafInSession(clonedSession, `${prefix}/pageInfo/endCursor`);
								saveSession(clonedSession);
							} catch {
								/* ignore if already selected */
							}
						}
					}
				}

				// 3. Apply --var to bind a variable on the cloned session
				const varArgs = collectFlagArgs("--var");
				if (varArgs.length >= 2 && clonedId) {
					queryDefine(clonedId, varArgs);
				}

				// Apply --select to add fields to the cloned session
				const selectArgs = collectFlagArgs("--select");
				if (selectArgs.length > 0 && clonedId) {
					const clonedSession = loadSession(clonedId);
					for (const rawSpec of selectArgs) {
						const colonIdx = rawSpec.lastIndexOf(":");
						const afterColon = colonIdx > 0 ? rawSpec.slice(colonIdx + 1) : "";
						let spec: string;
						let alias: string | undefined;
						if (colonIdx > 0 && afterColon.length > 0 && !/[./:]/.test(afterColon)) {
							spec = rawSpec.slice(0, colonIdx);
							alias = afterColon;
						} else {
							spec = rawSpec;
						}
						try {
							selectLeafInSession(clonedSession, spec, alias);
							console.log(`Selected ${rawSpec}.`);
						} catch (error: any) {
							console.error(`Failed to select ${rawSpec}: ${error.message}`);
						}
					}
					saveSession(clonedSession);
					console.log("");
					printQuery(clonedSession);
				}

				// Return cloned session info so the CLI can auto-activate it
				return { _clonedSessionId: clonedId } as any;
			}

			case "optional": {
				if (rest.length === 0) {
					console.error(
						"Usage: optional <field-or-alias> [...] | optional --remove <field-or-alias> [...]",
					);
					return;
				}
				const removeMode = rest.includes("--remove");
				const targets = rest.filter((r) => !r.startsWith("--"));
				if (targets.length === 0) {
					console.error(
						"Usage: optional <field-or-alias> [...] | optional --remove <field-or-alias> [...]",
					);
					return;
				}
				const session = loadSession(sessionId);
				for (const target of targets) {
					const node = session.nodes.find(
						(n) =>
							n.kind === "field" &&
							((n as FieldProjectionNode).alias === target ||
								(n as FieldProjectionNode).fieldName === target),
					);
					if (!node) {
						console.error(
							`No selected field matching "${target}". Use \`select ls\` to see selected fields.`,
						);
						continue;
					}
					if (removeMode) {
						node.directives = node.directives.filter((d) => d.name !== "optional");
						console.log(`Removed @optional from ${target}.`);
					} else {
						if (!node.directives.some((d) => d.name === "optional")) {
							node.directives.push({ name: "optional", args: {} });
						}
						console.log(`Added @optional to ${target}.`);
					}
				}
				saveSession(session);
				console.log("");
				printQuery(session);
				break;
			}

			case "codegen": {
				await queryCodegen(sessionId, rest);
				break;
			}

			default:
				throw new CommandError(`Unknown subcommand: ${subcommand}\n${formatHelp()}`);
		}

		// Emit JSON result for all commands when in JSON mode
		if (jsonMode && subcommand !== "show" && subcommand !== "run" && subcommand !== "codegen") {
			console.log = origLog;
			console.error = origError;
			const result = buildJsonResult(subcommand, sessionId);
			origLog(JSON.stringify(result, null, 2));
			return result;
		}
	} finally {
		// Restore console in case of errors
		console.log = origLog;
		console.error = origError;
	}
}