vde-layout 1.0.1 → 1.1.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { Command, CommanderError } from "commander";
+import { defineCommand, parseArgs, renderUsage } from "citty";
 import fs from "fs-extra";
 import path from "node:path";
 import os from "node:os";
@@ -8,10 +8,11 @@ import * as YAML from "yaml";
 import { parse } from "yaml";
 import { z } from "zod";
 import { createHash } from "node:crypto";
-import chalk from "chalk";
+import chalk, { Chalk } from "chalk";
 import { execa } from "execa";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
+import stringWidth from "string-width";
 
 //#region src/utils/errors.ts
 const ErrorCodes = {
@@ -114,6 +115,21 @@ const formatters = {
 //#region src/models/schema.ts
 const WindowModeSchema = z.enum(["new-window", "current-window"]);
 const TerminalBackendSchema = z.enum(["tmux", "wezterm"]);
+const SELECT_UI_MODES = ["auto", "fzf"];
+const SELECT_SURFACE_MODES = [
+	"auto",
+	"inline",
+	"tmux-popup"
+];
+const SelectUiModeSchema = z.enum(SELECT_UI_MODES);
+const SelectSurfaceModeSchema = z.enum(SELECT_SURFACE_MODES);
+const SelectorFzfSchema = z.object({ extraArgs: z.array(z.string().min(1)).optional() }).strict();
+const SelectorDefaultsSchema = z.object({
+	ui: SelectUiModeSchema.optional(),
+	surface: SelectSurfaceModeSchema.optional(),
+	tmuxPopupOpts: z.string().min(1).optional(),
+	fzf: SelectorFzfSchema.optional()
+}).strict();
 const TerminalPaneSchema = z.object({
 	name: z.string().min(1),
 	command: z.string().optional(),
@@ -145,7 +161,10 @@ const PresetSchema = z.object({
 	backend: TerminalBackendSchema.optional()
 });
 const ConfigSchema = z.object({
-	defaults: z.object({ windowMode: WindowModeSchema.optional() }).optional(),
+	defaults: z.object({
+		windowMode: WindowModeSchema.optional(),
+		selector: SelectorDefaultsSchema.optional()
+	}).optional(),
 	presets: z.record(PresetSchema)
 });
 
@@ -248,7 +267,8 @@ const createConfigLoader = (options = {}) => {
 		const candidates = [];
 		const projectCandidate = findProjectConfigCandidate();
 		if (projectCandidate !== null) candidates.push(projectCandidate);
-		candidates.push(...buildDefaultSearchPaths());
+		const defaultSearchPathGroups = buildDefaultSearchPathGroups();
+		candidates.push(...flattenSearchPathGroups(defaultSearchPathGroups));
 		return [...new Set(candidates)];
 	};
 	const loadConfig = async () => {
@@ -258,16 +278,16 @@ const createConfigLoader = (options = {}) => {
 			return validateYAML(await safeReadFile(filePath));
 		}
 		const searchPaths = computeCachedSearchPaths();
-		const existingPaths = await filterExistingPaths(searchPaths);
-		if (existingPaths.length === 0) throw createConfigError("Configuration file not found", ErrorCodes.CONFIG_NOT_FOUND, { searchPaths });
+		const globalPaths = await resolveFirstExistingPaths(buildDefaultSearchPathGroups());
 		const projectPath = findProjectConfigCandidate();
-		const globalPaths = existingPaths.filter((filePath) => filePath !== projectPath);
+		const projectConfigExists = projectPath !== null ? await fs.pathExists(projectPath) : false;
+		if (globalPaths.length === 0 && !projectConfigExists) throw createConfigError("Configuration file not found", ErrorCodes.CONFIG_NOT_FOUND, { searchPaths });
 		let mergedConfig = { presets: {} };
 		for (const globalPath of globalPaths) {
 			const config = validateYAML(await safeReadFile(globalPath));
 			mergedConfig = mergeConfigs(mergedConfig, config, emitWarning);
 		}
-		if (projectPath !== null && await fs.pathExists(projectPath)) {
+		if (projectPath !== null && projectConfigExists) {
 			const config = validateYAML(await safeReadFile(projectPath));
 			mergedConfig = mergeConfigs(mergedConfig, config, emitWarning);
 		}
@@ -287,21 +307,36 @@ const createConfigLoader = (options = {}) => {
 		getSearchPaths: () => computeCachedSearchPaths()
 	};
 };
-const buildDefaultSearchPaths = () => {
-	const paths = [];
+const buildDefaultSearchPathGroups = () => {
+	const pathGroups = [];
 	const vdeConfigPath = process.env.VDE_CONFIG_PATH;
-	if (vdeConfigPath !== void 0) paths.push(path.join(vdeConfigPath, "layout.yml"));
+	if (vdeConfigPath !== void 0) pathGroups.push([path.join(vdeConfigPath, "layout.yml")]);
 	const homeDir = process.env.HOME ?? os.homedir();
 	const xdgConfigHome = process.env.XDG_CONFIG_HOME ?? path.join(homeDir, ".config");
-	paths.push(path.join(xdgConfigHome, "vde", "layout.yml"));
+	pathGroups.push([path.join(xdgConfigHome, "vde", "layout", "config.yml"), path.join(xdgConfigHome, "vde", "layout.yml")]);
+	return pathGroups.map((group) => [...new Set(group)]);
+};
+const flattenSearchPathGroups = (pathGroups) => {
+	const paths = [];
+	for (const group of pathGroups) paths.push(...group);
 	return [...new Set(paths)];
 };
+const resolveFirstExistingPaths = async (pathGroups) => {
+	const existingPaths = await Promise.all(pathGroups.map(async (group) => findFirstExisting(group)));
+	const seenPaths = /* @__PURE__ */ new Set();
+	const resolvedPaths = [];
+	for (const existingPath of existingPaths) if (existingPath !== null && !seenPaths.has(existingPath)) {
+		seenPaths.add(existingPath);
+		resolvedPaths.push(existingPath);
+	}
+	return resolvedPaths;
+};
 const findProjectConfigCandidate = () => {
 	let currentDir = process.cwd();
 	const { root } = path.parse(currentDir);
 	while (true) {
-		const candidate = path.join(currentDir, ".vde", "layout.yml");
-		if (fs.existsSync(candidate)) return candidate;
+		const candidates = [path.join(currentDir, ".vde", "layout", "config.yml"), path.join(currentDir, ".vde", "layout.yml")];
+		for (const candidate of candidates) if (fs.existsSync(candidate)) return candidate;
 		if (currentDir === root) break;
 		const parent = path.dirname(currentDir);
 		if (parent === currentDir) break;
@@ -313,11 +348,6 @@ const findFirstExisting = async (paths) => {
 	for (const candidate of paths) if (await fs.pathExists(candidate)) return candidate;
 	return null;
 };
-const filterExistingPaths = async (paths) => {
-	const existing = [];
-	for (const candidate of paths) if (await fs.pathExists(candidate)) existing.push(candidate);
-	return existing;
-};
 const safeReadFile = async (filePath) => {
 	try {
 		return await fs.readFile(filePath, "utf8");
@@ -339,15 +369,39 @@ const mergeConfigs = (base, override, emitWarning) => {
 	const baseDefaults = base.defaults;
 	const overrideDefaults = override.defaults;
 	if (baseDefaults?.windowMode !== void 0 && overrideDefaults?.windowMode !== void 0 && baseDefaults.windowMode !== overrideDefaults.windowMode) emitWarning(`[vde-layout] defaults.windowMode conflict: "${baseDefaults.windowMode}" overridden by "${overrideDefaults.windowMode}"`);
+	const mergedSelectorDefaults = mergeSelectorDefaults({
+		baseSelector: baseDefaults?.selector,
+		overrideSelector: overrideDefaults?.selector,
+		emitWarning
+	});
 	const mergedDefaults = baseDefaults !== void 0 || overrideDefaults !== void 0 ? {
 		...baseDefaults ?? {},
-		...overrideDefaults ?? {}
+		...overrideDefaults ?? {},
+		...mergedSelectorDefaults !== void 0 ? { selector: mergedSelectorDefaults } : {}
 	} : void 0;
 	return mergedDefaults === void 0 ? { presets: mergedPresets } : {
 		defaults: mergedDefaults,
 		presets: mergedPresets
 	};
 };
+const mergeSelectorDefaults = ({ baseSelector, overrideSelector, emitWarning }) => {
+	if (baseSelector === void 0 && overrideSelector === void 0) return;
+	if (baseSelector?.ui !== void 0 && overrideSelector?.ui !== void 0 && baseSelector.ui !== overrideSelector.ui) emitWarning(`[vde-layout] defaults.selector.ui conflict: "${baseSelector.ui}" overridden by "${overrideSelector.ui}"`);
+	if (baseSelector?.surface !== void 0 && overrideSelector?.surface !== void 0 && baseSelector.surface !== overrideSelector.surface) emitWarning(`[vde-layout] defaults.selector.surface conflict: "${baseSelector.surface}" overridden by "${overrideSelector.surface}"`);
+	if (baseSelector?.tmuxPopupOpts !== void 0 && overrideSelector?.tmuxPopupOpts !== void 0 && baseSelector.tmuxPopupOpts !== overrideSelector.tmuxPopupOpts) emitWarning(`[vde-layout] defaults.selector.tmuxPopupOpts conflict: "${baseSelector.tmuxPopupOpts}" overridden by "${overrideSelector.tmuxPopupOpts}"`);
+	const baseExtraArgs = baseSelector?.fzf?.extraArgs;
+	const overrideExtraArgs = overrideSelector?.fzf?.extraArgs;
+	if (Array.isArray(baseExtraArgs) && Array.isArray(overrideExtraArgs) && JSON.stringify(baseExtraArgs) !== JSON.stringify(overrideExtraArgs)) emitWarning(`[vde-layout] defaults.selector.fzf.extraArgs conflict: global value overridden by project value`);
+	const mergedFzf = baseSelector?.fzf !== void 0 || overrideSelector?.fzf !== void 0 ? {
+		...baseSelector?.fzf ?? {},
+		...overrideSelector?.fzf ?? {}
+	} : void 0;
+	return {
+		...baseSelector ?? {},
+		...overrideSelector ?? {},
+		...mergedFzf !== void 0 ? { fzf: mergedFzf } : {}
+	};
+};
 
 //#endregion
 //#region src/layout/preset.ts
@@ -2706,9 +2760,9 @@ const resolveWindowMode = ({ cli, preset, defaults }) => {
 
 //#endregion
 //#region src/cli/preset-execution.ts
-const executePreset = async ({ presetName, options, presetManager, createCommandExecutor, core, logger, handleError, handlePipelineFailure, output = (line) => console.log(line), cwd = process.cwd(), env = process.env }) => {
+const executePreset = async ({ presetName, options, skipLoadConfig = false, presetManager, createCommandExecutor, core, logger, handleError, handlePipelineFailure, output = (line) => console.log(line), cwd = process.cwd(), env = process.env }) => {
 	try {
-		await presetManager.loadConfig();
+		if (skipLoadConfig !== true) await presetManager.loadConfig();
 		const preset = typeof presetName === "string" && presetName.length > 0 ? presetManager.getPreset(presetName) : presetManager.getDefaultPreset();
 		const windowModeResolution = resolveWindowModeForPreset({
 			presetManager,
@@ -2794,57 +2848,518 @@ const resolveWindowModeForPreset = ({ presetManager, options, presetWindowMode }
 	});
 };
 
+//#endregion
+//#region src/cli/select-args.ts
+const selectUiModes = SELECT_UI_MODES;
+const selectSurfaceModes = SELECT_SURFACE_MODES;
+const selectUiModeSet = new Set(selectUiModes);
+const selectSurfaceModeSet = new Set(selectSurfaceModes);
+const isSelectUiMode = (value) => {
+	return selectUiModeSet.has(value);
+};
+const isSelectSurfaceMode = (value) => {
+	return selectSurfaceModeSet.has(value);
+};
+const normalizeSelectArgs = (args) => {
+	const normalized = [];
+	for (let index = 0; index < args.length; index += 1) {
+		const token = args[index];
+		if (typeof token !== "string") continue;
+		if (token === "--") {
+			normalized.push(...args.slice(index));
+			break;
+		}
+		if (typeof token === "string" && token.startsWith("--select=")) {
+			const mode = token.slice(9);
+			normalized.push("--select");
+			if (mode.length > 0) normalized.push("--select-ui", mode);
+			continue;
+		}
+		if (token === "--select") {
+			const nextToken = args[index + 1];
+			if (typeof nextToken === "string" && isSelectUiMode(nextToken)) {
+				normalized.push("--select", "--select-ui", nextToken);
+				index += 1;
+				continue;
+			}
+		}
+		normalized.push(token);
+	}
+	return normalized;
+};
+const resolveSelectUiMode = (uiValue) => {
+	if (uiValue === void 0) return "auto";
+	if (isSelectUiMode(uiValue)) return uiValue;
+	throw new Error(`Invalid value for --select-ui: "${uiValue}". Expected one of: ${selectUiModes.join(", ")}`);
+};
+const resolveSelectSurfaceMode = (surfaceValue) => {
+	if (surfaceValue === void 0) return "auto";
+	if (isSelectSurfaceMode(surfaceValue)) return surfaceValue;
+	throw new Error(`Invalid value for --select-surface: "${surfaceValue}". Expected one of: ${selectSurfaceModes.join(", ")}`);
+};
+
+//#endregion
+//#region src/cli/preset-selector.ts
+const FZF_BINARY = "fzf";
+const FZF_CHECK_TIMEOUT_MS = 5e3;
+const MAX_PREVIEW_BASE64_LENGTH = 64 * 1024;
+const RESERVED_FZF_ARGS = new Set([
+	"delimiter",
+	"with-nth",
+	"ansi",
+	"preview",
+	"preview-window",
+	"tmux"
+]);
+const selectorChalk = new Chalk({ level: 1 });
+const sanitizeTsvCell = (value) => {
+	return (value ?? "").replace(/[\t\r\n]+/g, " ");
+};
+const padDisplayCell = (value, width) => {
+	const paddingLength = Math.max(0, width - stringWidth(value));
+	return `${value}${" ".repeat(paddingLength)}`;
+};
+const buildPresetPreviewYaml = ({ presetKey, preset }) => {
+	return YAML.stringify({ presets: { [presetKey]: preset } });
+};
+const defaultCheckFzfAvailability = async () => {
+	try {
+		await execa(FZF_BINARY, ["--version"], { timeout: FZF_CHECK_TIMEOUT_MS });
+		return true;
+	} catch (error) {
+		const execaError = error;
+		if (execaError.code === "ENOENT" || execaError.code === "ETIMEDOUT" || execaError.code === "ERR_EXECA_TIMEOUT" || execaError.timedOut === true) return false;
+		throw error;
+	}
+};
+const defaultRunFzf = async ({ args, input, cwd, env }) => {
+	return { stdout: (await execa(FZF_BINARY, args, {
+		input,
+		cwd,
+		env,
+		stderr: "inherit"
+	})).stdout };
+};
+const ensureFzfAvailable = async (checkFzfAvailability) => {
+	if (await checkFzfAvailability()) return;
+	throw createEnvironmentError("fzf is required for preset selection UI", ErrorCodes.BACKEND_NOT_FOUND, {
+		backend: "fzf",
+		binary: FZF_BINARY
+	});
+};
+const isTmuxSession = (env) => {
+	return typeof env.TMUX === "string" && env.TMUX.length > 0;
+};
+const resolveSurfaceMode = ({ surfaceMode, env }) => {
+	if (surfaceMode === "auto") return isTmuxSession(env) ? "tmux-popup" : "inline";
+	return surfaceMode;
+};
+const validateExtraFzfArgs = (fzfExtraArgs) => {
+	for (const arg of fzfExtraArgs) {
+		if (typeof arg !== "string" || arg.length === 0) throw new Error("Empty value is not allowed for --fzf-arg");
+		if (!arg.startsWith("--")) continue;
+		const withoutPrefix = arg.slice(2);
+		if (withoutPrefix.length === 0) continue;
+		const optionName = withoutPrefix.split("=")[0];
+		if (optionName !== void 0 && RESERVED_FZF_ARGS.has(optionName)) throw new Error(`--fzf-arg cannot override reserved fzf option: --${optionName}`);
+	}
+};
+const buildFzfArgs = ({ surfaceMode, tmuxPopupOptions, fzfExtraArgs, env }) => {
+	validateExtraFzfArgs(fzfExtraArgs);
+	const resolvedSurfaceMode = resolveSurfaceMode({
+		surfaceMode,
+		env
+	});
+	if (resolvedSurfaceMode === "tmux-popup" && isTmuxSession(env) !== true) throw new Error("tmux popup selector surface requires running inside tmux");
+	return [
+		"--delimiter=\\t",
+		"--ansi",
+		"--with-nth=2",
+		"--prompt=preset> ",
+		"--layout=reverse",
+		"--height=80%",
+		"--border",
+		"--preview=node -e 'process.stdout.write(Buffer.from(process.argv[1], \"base64\").toString(\"utf8\"))' {3}",
+		"--preview-window=right,60%,border-left,wrap",
+		...resolvedSurfaceMode === "tmux-popup" ? [tmuxPopupOptions !== void 0 ? `--tmux=${tmuxPopupOptions}` : "--tmux"] : [],
+		...fzfExtraArgs
+	];
+};
+const toPresetRows = ({ presetInfos, presetManager }) => {
+	const rows = presetInfos.map((presetInfo) => {
+		const key = sanitizeTsvCell(presetInfo.key);
+		const name = sanitizeTsvCell(presetInfo.name);
+		const description = sanitizeTsvCell(presetInfo.description);
+		const preset = presetManager.getPreset(presetInfo.key);
+		const previewYaml = buildPresetPreviewYaml({
+			presetKey: presetInfo.key,
+			preset
+		});
+		const previewBase64 = Buffer.from(previewYaml, "utf8").toString("base64");
+		if (previewBase64.length > MAX_PREVIEW_BASE64_LENGTH) throw new Error(`Preset preview is too large for fzf inline preview payload: "${presetInfo.key}" (${previewBase64.length} bytes)`);
+		return {
+			key,
+			name,
+			description,
+			previewBase64
+		};
+	});
+	const keyColumnWidth = rows.reduce((maxWidth, row) => Math.max(maxWidth, stringWidth(row.key)), 0);
+	const nameColumnWidth = rows.reduce((maxWidth, row) => Math.max(maxWidth, stringWidth(row.name)), 0);
+	return rows.map((row) => {
+		const key = padDisplayCell(row.key, keyColumnWidth);
+		const name = padDisplayCell(row.name, nameColumnWidth);
+		const description = row.description.length > 0 ? row.description : selectorChalk.gray("(no description)");
+		const display = `${selectorChalk.cyan(key)}  ${selectorChalk.bold(name)}  ${selectorChalk.dim(description)}`;
+		return {
+			key: row.key,
+			name: row.name,
+			description: row.description,
+			display,
+			previewBase64: row.previewBase64
+		};
+	});
+};
+const buildFzfInput = (rows) => {
+	return rows.map((row, index) => {
+		return [
+			String(index),
+			row.display,
+			row.previewBase64
+		].join("	");
+	}).join("\n");
+};
+const parseSelectedPresetName = ({ selectedLine, rows }) => {
+	const trimmed = selectedLine.trim();
+	if (trimmed.length === 0) return null;
+	const idCell = trimmed.split("	")[0];
+	const id = Number(idCell);
+	if (!Number.isInteger(id) || id < 0 || id >= rows.length) throw new Error("Invalid selection returned from fzf");
+	return rows[id]?.key ?? null;
+};
+const runFzfSelector = async ({ rows, fzfArgs, runFzf, cwd, env }) => {
+	try {
+		const presetName = parseSelectedPresetName({
+			selectedLine: (await runFzf({
+				input: buildFzfInput(rows),
+				args: [...fzfArgs],
+				cwd,
+				env
+			})).stdout,
+			rows
+		});
+		if (presetName === null) return { status: "cancelled" };
+		return {
+			status: "selected",
+			presetName
+		};
+	} catch (error) {
+		if (error.exitCode === 130) return { status: "cancelled" };
+		throw error;
+	}
+};
+const selectPreset = async ({ uiMode, surfaceMode, tmuxPopupOptions, fzfExtraArgs = [], presetManager, logger, skipLoadConfig = false, cwd = process.cwd(), env = process.env, isInteractive = () => process.stdin.isTTY === true && process.stdout.isTTY === true && process.stderr.isTTY === true, checkFzfAvailability = defaultCheckFzfAvailability, runFzf = defaultRunFzf }) => {
+	if (isInteractive() !== true) throw new Error("Preset selection requires an interactive terminal");
+	await ensureFzfAvailable(checkFzfAvailability);
+	if (skipLoadConfig !== true) await presetManager.loadConfig();
+	const presetInfos = presetManager.listPresets();
+	if (presetInfos.length === 0) throw new Error("No presets defined");
+	const fzfArgs = buildFzfArgs({
+		surfaceMode,
+		tmuxPopupOptions,
+		fzfExtraArgs,
+		env
+	});
+	logger.debug(`Preset selection UI: ${uiMode}`);
+	return runFzfSelector({
+		rows: toPresetRows({
+			presetInfos,
+			presetManager
+		}),
+		fzfArgs,
+		runFzf,
+		cwd,
+		env
+	});
+};
+
 //#endregion
 //#region src/cli/index.ts
+const backendValues = ["tmux", "wezterm"];
+const listCommandName = "list";
+const EXIT_CODE_CANCELLED = 130;
+const optionNamesAllowOptionLikeValue = new Set(["fzfArg", "fzf-arg"]);
+const toKebabCase = (value) => {
+	return value.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+};
+const toOptionSpec = (kind, optionName) => {
+	return {
+		kind,
+		allowOptionLikeValue: optionNamesAllowOptionLikeValue.has(optionName)
+	};
+};
+const buildOptionSpecs = (argsDef) => {
+	const longOptions = /* @__PURE__ */ new Map();
+	const shortOptions = /* @__PURE__ */ new Map();
+	for (const [argName, arg] of Object.entries(argsDef)) {
+		if (arg.type === "positional") continue;
+		const valueKind = arg.type === "boolean" ? "boolean" : "value";
+		const kebabName = toKebabCase(argName);
+		longOptions.set(argName, toOptionSpec(valueKind, argName));
+		longOptions.set(kebabName, toOptionSpec(valueKind, kebabName));
+		const aliases = "alias" in arg ? Array.isArray(arg.alias) ? arg.alias : typeof arg.alias === "string" ? [arg.alias] : [] : [];
+		for (const alias of aliases) {
+			if (alias.length === 1) {
+				shortOptions.set(alias, toOptionSpec(valueKind, alias));
+				continue;
+			}
+			longOptions.set(alias, toOptionSpec(valueKind, alias));
+			const kebabAlias = toKebabCase(alias);
+			longOptions.set(kebabAlias, toOptionSpec(valueKind, kebabAlias));
+		}
+	}
+	return {
+		longOptions,
+		shortOptions
+	};
+};
+const validateRawOptions = (args, optionSpecs) => {
+	for (let index = 0; index < args.length; index += 1) {
+		const token = args[index];
+		if (typeof token !== "string") continue;
+		if (token === "--") break;
+		if (!token.startsWith("-") || token === "-") continue;
+		if (token.startsWith("--")) {
+			const value = token.slice(2);
+			if (value.length === 0) continue;
+			const separatorIndex = value.indexOf("=");
+			const rawOptionName = separatorIndex >= 0 ? value.slice(0, separatorIndex) : value;
+			const optionName = rawOptionName.startsWith("no-") ? rawOptionName.slice(3) : rawOptionName;
+			const optionSpec = optionSpecs.longOptions.get(optionName);
+			const kind = optionSpec?.kind;
+			if (kind === void 0) throw new Error(`Unknown option: --${rawOptionName}`);
+			if (kind === "value") if (separatorIndex >= 0) {
+				if (value.slice(separatorIndex + 1).length === 0) throw new Error(`Missing value for option: --${optionName}`);
+			} else {
+				const nextToken = args[index + 1];
+				if (typeof nextToken !== "string" || nextToken.length === 0) throw new Error(`Missing value for option: --${optionName}`);
+				if (nextToken.startsWith("-") && optionSpec?.allowOptionLikeValue !== true) throw new Error(`Missing value for option: --${optionName}`);
+				index += 1;
+			}
+			continue;
+		}
+		const shortFlags = token.slice(1);
+		for (let flagIndex = 0; flagIndex < shortFlags.length; flagIndex += 1) {
+			const option = shortFlags[flagIndex];
+			if (typeof option !== "string" || option.length === 0) continue;
+			const optionSpec = optionSpecs.shortOptions.get(option);
+			const kind = optionSpec?.kind;
+			if (kind === void 0) throw new Error(`Unknown option: -${option}`);
+			if (kind === "value") {
+				if (flagIndex < shortFlags.length - 1) break;
+				const nextToken = args[index + 1];
+				if (typeof nextToken !== "string" || nextToken.length === 0) throw new Error(`Missing value for option: -${option}`);
+				if (nextToken.startsWith("-") && optionSpec?.allowOptionLikeValue !== true) throw new Error(`Missing value for option: -${option}`);
+				index += 1;
+				break;
+			}
+		}
+	}
+};
+const getPositionals = (args) => {
+	return args._.filter((value) => typeof value === "string");
+};
+const collectOptionValues = ({ args, optionNames }) => {
+	const values = [];
+	const optionNameSet = new Set(optionNames);
+	for (let index = 0; index < args.length; index += 1) {
+		const token = args[index];
+		if (typeof token !== "string") continue;
+		if (token === "--") break;
+		if (!token.startsWith("--")) continue;
+		const eqIndex = token.indexOf("=");
+		const rawName = eqIndex >= 0 ? token.slice(2, eqIndex) : token.slice(2);
+		if (optionNameSet.has(rawName) !== true) continue;
+		if (eqIndex >= 0) {
+			values.push(token.slice(eqIndex + 1));
+			continue;
+		}
+		const nextToken = args[index + 1];
+		if (typeof nextToken === "string") {
+			values.push(nextToken);
+			index += 1;
+		}
+	}
+	return values;
+};
 const createCli = (options = {}) => {
 	const presetManager = options.presetManager ?? createPresetManager();
 	const createCommandExecutor = options.createCommandExecutor ?? ((opts) => {
 		if (opts.dryRun) return createDryRunExecutor({ verbose: opts.verbose });
 		return createRealExecutor({ verbose: opts.verbose });
 	});
+	const selectPreset$1 = options.selectPreset ?? selectPreset;
 	const core = options.core ?? {
 		compilePreset,
 		compilePresetFromValue,
 		createLayoutPlan,
 		emitPlan
 	};
-	const program = new Command();
 	const version = loadPackageVersion(createRequire(import.meta.url));
 	let logger = createLogger();
 	const errorHandlers = createCliErrorHandlers({ getLogger: () => logger });
-	const setupProgram = () => {
-		program.exitOverride();
-		program.name("vde-layout").description("VDE (Vibrant Development Environment) Layout Manager - tmux pane layout management tool").version(version, "-v, --version", "Show version").helpOption("-h, --help", "Show help");
-		program.option("--verbose", "Show detailed logs", false);
-		program.option("--dry-run", "Display commands without executing", false);
-		program.option("--backend <backend>", "Select terminal backend (tmux or wezterm)");
-		program.option("--config <path>", "Path to configuration file");
-		program.option("--current-window", "Use the current tmux window for layout (kills other panes)", false);
-		program.option("--new-window", "Always create a new tmux window for layout", false);
-		program.hook("preAction", (_thisCommand, actionCommand) => {
+	const rootArgsDef = {
+		preset: {
+			type: "positional",
+			description: "Preset name (defaults to \"default\" preset when omitted)",
+			required: false
+		},
+		verbose: {
+			type: "boolean",
+			description: "Show detailed logs"
+		},
+		dryRun: {
+			type: "boolean",
+			description: "Display commands without executing"
+		},
+		backend: {
+			type: "enum",
+			options: [...backendValues],
+			description: "Select terminal backend (tmux or wezterm)"
+		},
+		config: {
+			type: "string",
+			valueHint: "path",
+			description: "Path to configuration file"
+		},
+		currentWindow: {
+			type: "boolean",
+			description: "Use the current tmux window for layout (kills other panes)"
+		},
+		newWindow: {
+			type: "boolean",
+			description: "Always create a new tmux window for layout"
+		},
+		select: {
+			type: "boolean",
+			description: "Select preset from interactive UI"
+		},
+		selectUi: {
+			type: "enum",
+			options: [...selectUiModes],
+			description: "Select preset UI backend (auto or fzf)"
+		},
+		selectSurface: {
+			type: "enum",
+			options: [...selectSurfaceModes],
+			description: "Select selector surface mode (auto, inline, or tmux-popup)"
+		},
+		selectTmuxPopupOpts: {
+			type: "string",
+			valueHint: "opts",
+			description: "tmux popup options used for fzf --tmux=<opts> (example: 80%,70%)"
+		},
+		fzfArg: {
+			type: "string",
+			valueHint: "arg",
+			description: "Additional argument passed to fzf selector (repeatable)"
+		},
+		help: {
+			type: "boolean",
+			alias: "h",
+			description: "Show help"
+		},
+		version: {
+			type: "boolean",
+			alias: "v",
+			description: "Show version"
+		}
+	};
+	const listCommand = defineCommand({ meta: {
+		name: listCommandName,
+		description: "List available presets"
+	} });
+	const rootCommand = defineCommand({
+		meta: {
+			name: "vde-layout",
+			description: "VDE (Vibrant Development Environment) Layout Manager - tmux pane layout management tool",
+			version
+		},
+		args: rootArgsDef,
+		subCommands: { [listCommandName]: listCommand }
+	});
+	const optionSpecs = buildOptionSpecs(rootArgsDef);
+	const run = async (args = process.argv.slice(2)) => {
+		logger = createLogger();
+		try {
+			const normalizedArgs = normalizeSelectArgs(args);
+			validateRawOptions(normalizedArgs, optionSpecs);
+			const parsedArgs = parseArgs(normalizedArgs, rootArgsDef);
+			const fzfCliArgs = collectOptionValues({
+				args: normalizedArgs,
+				optionNames: ["fzf-arg", "fzfArg"]
+			});
+			const positionals = getPositionals(parsedArgs);
+			const headPositional = positionals[0];
+			if (parsedArgs.help === true) {
+				const usage = headPositional === listCommandName ? await renderUsage(listCommand, rootCommand) : await renderUsage(rootCommand);
+				console.log(`${usage}\n`);
+				return 0;
+			}
+			if (parsedArgs.version === true) {
+				console.log(version);
+				return 0;
+			}
 			logger = applyRuntimeOptions({
-				runtimeOptions: typeof actionCommand.optsWithGlobals === "function" ? actionCommand.optsWithGlobals() : program.opts(),
+				runtimeOptions: {
+					verbose: parsedArgs.verbose === true,
+					config: typeof parsedArgs.config === "string" ? parsedArgs.config : void 0
+				},
 				createLogger,
 				presetManager
 			});
-		});
-		program.command("list").description("List available presets").action(async () => {
-			lastExitCode = await listPresets({
-				presetManager,
-				logger,
-				onError: errorHandlers.handleError
-			});
-		});
-		program.argument("[preset]", "Preset name (defaults to \"default\" preset when omitted)").action(async (presetName) => {
-			const opts = program.opts();
-			lastExitCode = await executePreset({
-				presetName,
+			if (headPositional === listCommandName) {
+				const extraArgs = positionals.slice(1);
+				if (extraArgs.length > 0) throw new Error(`too many arguments for '${listCommandName}'. Expected 0 arguments but got ${extraArgs.length}.`);
+				return await listPresets({
+					presetManager,
+					logger,
+					onError: errorHandlers.handleError
+				});
+			}
+			if (positionals.length > 1) throw new Error(`too many arguments. Expected at most 1 argument but got ${positionals.length}.`);
+			if (parsedArgs.selectUi !== void 0 && parsedArgs.select !== true) throw new Error("--select-ui requires --select");
+			if (parsedArgs.selectSurface !== void 0 && parsedArgs.select !== true) throw new Error("--select-surface requires --select");
+			if (parsedArgs.selectTmuxPopupOpts !== void 0 && parsedArgs.select !== true) throw new Error("--select-tmux-popup-opts requires --select");
+			if (fzfCliArgs.length > 0 && parsedArgs.select !== true) throw new Error("--fzf-arg requires --select");
+			if (parsedArgs.select === true && typeof headPositional === "string" && headPositional.length > 0) throw new Error("Cannot use preset argument with --select");
+			let resolvedPresetName = headPositional;
+			let configLoaded = false;
+			if (parsedArgs.select === true) {
+				await presetManager.loadConfig();
+				configLoaded = true;
+				const selectorDefaults = presetManager.getDefaults()?.selector;
+				const selection = await selectPreset$1({
+					uiMode: resolveSelectUiMode(typeof parsedArgs.selectUi === "string" ? parsedArgs.selectUi : selectorDefaults?.ui),
+					surfaceMode: resolveSelectSurfaceMode(typeof parsedArgs.selectSurface === "string" ? parsedArgs.selectSurface : selectorDefaults?.surface),
+					tmuxPopupOptions: typeof parsedArgs.selectTmuxPopupOpts === "string" ? parsedArgs.selectTmuxPopupOpts : selectorDefaults?.tmuxPopupOpts,
+					fzfExtraArgs: [...selectorDefaults?.fzf?.extraArgs ?? [], ...fzfCliArgs],
+					presetManager,
+					logger,
+					skipLoadConfig: true
+				});
+				if (selection.status === "cancelled") return EXIT_CODE_CANCELLED;
+				resolvedPresetName = selection.presetName;
+			}
+			return await executePreset({
+				presetName: resolvedPresetName,
+				skipLoadConfig: configLoaded,
 				options: {
-					verbose: opts.verbose === true,
-					dryRun: opts.dryRun === true,
-					currentWindow: opts.currentWindow === true,
-					newWindow: opts.newWindow === true,
-					backend: opts.backend
+					verbose: parsedArgs.verbose === true,
+					dryRun: parsedArgs.dryRun === true,
+					currentWindow: parsedArgs.currentWindow === true,
+					newWindow: parsedArgs.newWindow === true,
+					backend: typeof parsedArgs.backend === "string" ? parsedArgs.backend : void 0
 				},
 				presetManager,
 				createCommandExecutor,
@@ -2853,20 +3368,9 @@ const createCli = (options = {}) => {
 				handleError: errorHandlers.handleError,
 				handlePipelineFailure: errorHandlers.handlePipelineFailure
 			});
-		});
-	};
-	let lastExitCode = 0;
-	setupProgram();
-	const run = async (args = process.argv.slice(2)) => {
-		lastExitCode = 0;
-		logger = createLogger();
-		try {
-			await program.parseAsync(args, { from: "user" });
 		} catch (error) {
-			if (error instanceof CommanderError) return error.exitCode;
 			return errorHandlers.handleError(error);
 		}
-		return lastExitCode;
 	};
 	return { run };
 };