vde-layout 0.0.8 → 0.1.0

package/README.md

@@ -112,6 +112,8 @@ layout:
       focus: true               # optional; only one pane should be true
       delay: 500                # optional; wait (ms) before running command
       title: "Server"           # optional; tmux pane title
+      ephemeral: true           # optional; close pane after command completes
+      closeOnError: false       # optional; if ephemeral, close on error (default: false)
     - type: vertical            # nested split
       ratio: [1, 1]
       panes:
@@ -119,6 +121,71 @@ layout:
         - name: "shell"
 ```
 
+### Template Tokens
+You can reference dynamically-assigned pane IDs within pane commands using template tokens. These tokens are resolved after the layout finishes splitting panes but before commands execute:
+
+- **`{{this_pane}}`** – References the current pane receiving the command
+- **`{{focus_pane}}`** – References the pane that will receive focus
+- **`{{pane_id:<name>}}`** – References a specific pane by its name
+
+Example:
+```yaml
+presets:
+  cross-pane-demo:
+    name: Cross Pane Coordination
+    layout:
+      type: vertical
+      ratio: [2, 1]
+      panes:
+        - name: editor
+          command: 'echo "Editor pane ID: {{this_pane}}"'
+          focus: true
+        - name: terminal
+          command: 'echo "I can reference the editor pane: {{pane_id:editor}}"'
+```
+
+**Common use cases:**
+- Send commands to other panes: `tmux send-keys -t {{pane_id:editor}} "npm test" Enter`
+- Display pane information for debugging: `echo "Current: {{this_pane}}, Focus: {{focus_pane}}"`
+- Coordinate tasks across multiple panes within your preset configuration
+
+### Ephemeral Panes
+Ephemeral panes automatically close after their command completes. This is useful for one-time tasks like builds, tests, or initialization scripts.
+
+```yaml
+panes:
+  - name: build
+    command: npm run build
+    ephemeral: true  # Pane closes when command finishes
+```
+
+**Error handling:**
+- By default, ephemeral panes remain open if the command fails, allowing you to inspect errors
+- Set `closeOnError: true` to close the pane regardless of success or failure
+
+```yaml
+panes:
+  - name: quick-test
+    command: npm test
+    ephemeral: true
+    closeOnError: false  # Default: stays open on error
+
+  - name: build-and-exit
+    command: npm run build
+    ephemeral: true
+    closeOnError: true  # Closes even if build fails
+```
+
+**Combining with template tokens:**
+```yaml
+panes:
+  - name: editor
+    command: nvim
+  - name: test-runner
+    command: 'tmux send-keys -t {{pane_id:editor}} ":!npm test" Enter'
+    ephemeral: true  # Run once and close
+```
+
 ### Ratio Normalization
 Ratios can be any set of positive integers. vde-layout normalizes them to percentages:
 - `[1, 1]` → `[50, 50]`

package/dist/index.js

@@ -120,7 +120,9 @@ const TerminalPaneSchema = z.object({
 	env: z.record(z.string()).optional(),
 	delay: z.number().int().positive().optional(),
 	title: z.string().optional(),
-	focus: z.boolean().optional()
+	focus: z.boolean().optional(),
+	ephemeral: z.boolean().optional(),
+	closeOnError: z.boolean().optional()
 }).strict();
 const SplitPaneSchema = z.lazy(() => z.object({
 	type: z.enum(["horizontal", "vertical"]),
@@ -730,6 +732,70 @@ const isFunctionalCoreError = (value) => {
 	return (candidate.kind === "compile" || candidate.kind === "plan" || candidate.kind === "emit" || candidate.kind === "execution") && typeof candidate.code === "string" && typeof candidate.message === "string";
 };
 
+//#endregion
+//#region src/utils/template-tokens.ts
+const TemplateTokenErrorImpl = function TemplateTokenError$1(message, tokenType, availablePanes) {
+	const error = new Error(message);
+	Object.setPrototypeOf(error, TemplateTokenErrorImpl.prototype);
+	error.name = "TemplateTokenError";
+	error.tokenType = tokenType;
+	error.availablePanes = availablePanes;
+	return error;
+};
+TemplateTokenErrorImpl.prototype = Object.create(Error.prototype);
+TemplateTokenErrorImpl.prototype.constructor = TemplateTokenErrorImpl;
+const TemplateTokenError = TemplateTokenErrorImpl;
+/**
+* Replaces template tokens in a command string with actual pane IDs.
+*
+* Uses a single-pass regex replacement to avoid nested token issues.
+* All tokens are replaced in a single pass, preventing already-replaced
+* values from being re-processed.
+*
+* @param input - Object containing the command and pane ID mappings
+* @returns The command string with all template tokens replaced
+* @throws TemplateTokenError if a referenced pane name is not found in the mapping
+*/
+const replaceTemplateTokens = ({ command, currentPaneRealId, focusPaneRealId, nameToRealIdMap }) => {
+	return command.replace(/\{\{(this_pane|focus_pane|pane_id:([^}]+))\}\}/g, (match, tokenContent, paneName) => {
+		if (tokenContent === "this_pane") return currentPaneRealId;
+		if (tokenContent === "focus_pane") return focusPaneRealId;
+		if (tokenContent.startsWith("pane_id:") && paneName !== void 0) {
+			const trimmedName = paneName.trim();
+			const paneId = nameToRealIdMap.get(trimmedName);
+			if (paneId === void 0) throw new TemplateTokenError(`Pane name "${trimmedName}" not found. Available panes: ${Array.from(nameToRealIdMap.keys()).join(", ")}`, "pane_id", Array.from(nameToRealIdMap.keys()));
+			return paneId;
+		}
+		return match;
+	});
+};
+/**
+* Builds a mapping from pane names to real pane IDs.
+*
+* **Duplicate Name Handling:**
+* If multiple panes share the same name, the last one in the terminals
+* array wins. This follows the iteration order of the layout tree.
+* It's recommended to use unique names for panes to avoid ambiguity
+* in template token references.
+*
+* **Virtual to Real ID Resolution:**
+* Only panes with successfully resolved real IDs (present in paneMap)
+* are included in the resulting map. This ensures that template tokens
+* only reference panes that have been properly created.
+*
+* @param terminals - Array of emitted terminals from the layout plan
+* @param paneMap - Map from virtual pane IDs to real pane IDs (backend-specific)
+* @returns A map from pane names to real pane IDs
+*/
+const buildNameToRealIdMap = (terminals, paneMap) => {
+	const nameToRealIdMap = /* @__PURE__ */ new Map();
+	for (const terminal of terminals) {
+		const realId = paneMap.get(terminal.virtualPaneId);
+		if (realId !== void 0) nameToRealIdMap.set(terminal.name, realId);
+	}
+	return nameToRealIdMap;
+};
+
 //#endregion
 //#region src/executor/plan-runner.ts
 const DOUBLE_QUOTE = "\"";
@@ -812,7 +878,8 @@ const executePlan = async ({ emission, executor, windowName, windowMode, onConfi
 	await executeTerminalCommands({
 		terminals: emission.terminals,
 		executor,
-		paneMap
+		paneMap,
+		focusPaneVirtualId: emission.summary.focusPaneId
 	});
 	const finalRealFocus = resolvePaneId(paneMap, emission.summary.focusPaneId);
 	if (typeof finalRealFocus === "string" && finalRealFocus.length > 0) await executeCommand(executor, [
@@ -868,7 +935,16 @@ const executeFocusStep = async ({ step, executor, paneMap }) => {
 		details: { command }
 	});
 };
-const executeTerminalCommands = async ({ terminals, executor, paneMap }) => {
+const executeTerminalCommands = async ({ terminals, executor, paneMap, focusPaneVirtualId }) => {
+	const nameToRealIdMap = buildNameToRealIdMap(terminals, paneMap);
+	if (!paneMap.has(focusPaneVirtualId)) raiseExecutionError("UNKNOWN_PANE", {
+		message: `Unknown focus pane: ${focusPaneVirtualId}`,
+		path: focusPaneVirtualId
+	});
+	const focusPaneRealId = ensureNonEmpty(resolvePaneId(paneMap, focusPaneVirtualId), () => raiseExecutionError("UNKNOWN_PANE", {
+		message: `Unknown focus pane: ${focusPaneVirtualId}`,
+		path: focusPaneVirtualId
+	}));
 	for (const terminal of terminals) {
 		const realPaneId = ensureNonEmpty(resolvePaneId(paneMap, terminal.virtualPaneId), () => raiseExecutionError("UNKNOWN_PANE", {
 			message: `Unknown terminal pane: ${terminal.virtualPaneId}`,
@@ -903,18 +979,44 @@ const executeTerminalCommands = async ({ terminals, executor, paneMap }) => {
 				path: terminal.virtualPaneId
 			});
 		}
-		if (typeof terminal.command === "string" && terminal.command.length > 0) await executeCommand(executor, [
-			"send-keys",
-			"-t",
-			realPaneId,
-			terminal.command,
-			"Enter"
-		], {
-			code: ErrorCodes.TMUX_COMMAND_FAILED,
-			message: `Failed to execute command for pane ${terminal.virtualPaneId}`,
-			path: terminal.virtualPaneId,
-			details: { command: terminal.command }
-		});
+		if (typeof terminal.command === "string" && terminal.command.length > 0) {
+			const focusPaneRealIdForCommand = terminal.command.includes("{{focus_pane}}") ? focusPaneRealId : "";
+			let commandWithTokensReplaced;
+			try {
+				commandWithTokensReplaced = replaceTemplateTokens({
+					command: terminal.command,
+					currentPaneRealId: realPaneId,
+					focusPaneRealId: focusPaneRealIdForCommand,
+					nameToRealIdMap
+				});
+			} catch (error) {
+				if (error instanceof TemplateTokenError) throw createFunctionalError("execution", {
+					code: "TEMPLATE_TOKEN_ERROR",
+					message: `Template token resolution failed for pane ${terminal.virtualPaneId}: ${error.message}`,
+					path: terminal.virtualPaneId,
+					details: {
+						command: terminal.command,
+						tokenType: error.tokenType,
+						availablePanes: error.availablePanes
+					}
+				});
+				throw error;
+			}
+			if (terminal.ephemeral === true) if (terminal.closeOnError === true) commandWithTokensReplaced = `${commandWithTokensReplaced}; exit`;
+			else commandWithTokensReplaced = `${commandWithTokensReplaced}; [ $? -eq 0 ] && exit`;
+			await executeCommand(executor, [
+				"send-keys",
+				"-t",
+				realPaneId,
+				commandWithTokensReplaced,
+				"Enter"
+			], {
+				code: ErrorCodes.TMUX_COMMAND_FAILED,
+				message: `Failed to execute command for pane ${terminal.virtualPaneId}`,
+				path: terminal.virtualPaneId,
+				details: { command: terminal.command }
+			});
+		}
 	}
 };
 const executeCommand = async (executor, command, context) => {
@@ -1398,20 +1500,22 @@ const buildDryRunSteps = (emission) => {
 	return steps;
 };
 const resolveCurrentWindow = async (context) => {
-	const activeWindow = context.list.windows.find((window) => window.isActive) ?? context.list.windows[0];
+	const preferredPaneId = typeof context.preferredPaneId === "string" && context.preferredPaneId.length > 0 ? context.preferredPaneId : void 0;
+	const preferredWindowId = preferredPaneId !== void 0 ? findWindowContainingPane(context.list, preferredPaneId) : void 0;
+	const activeWindow = (preferredWindowId !== void 0 ? context.list.windows.find((window) => window.windowId === preferredWindowId) : void 0) ?? context.list.windows.find((window) => window.isActive) ?? context.list.windows[0];
 	if (!activeWindow) throw createFunctionalError("execution", {
 		code: ErrorCodes.TERMINAL_COMMAND_FAILED,
 		message: "No active wezterm window detected",
 		details: { hint: "Launch wezterm and ensure a window is focused, or run with --new-window." }
 	});
-	const activeTab = activeWindow.tabs.find((tab) => tab.isActive) ?? activeWindow.tabs[0];
+	const activeTab = (preferredPaneId !== void 0 ? activeWindow.tabs.find((tab) => tab.panes.some((pane) => pane.paneId === preferredPaneId)) : void 0) ?? activeWindow.tabs.find((tab) => tab.isActive) ?? activeWindow.tabs[0];
 	if (!activeTab) throw createFunctionalError("execution", {
 		code: ErrorCodes.TERMINAL_COMMAND_FAILED,
 		message: "No active wezterm tab detected",
 		path: activeWindow.windowId,
 		details: { hint: "Ensure a wezterm tab is focused before using --current-window." }
 	});
-	const activePane = activeTab.panes.find((pane) => pane.isActive) ?? activeTab.panes[0];
+	const activePane = (preferredPaneId !== void 0 ? activeTab.panes.find((pane) => pane.paneId === preferredPaneId) : void 0) ?? activeTab.panes.find((pane) => pane.isActive) ?? activeTab.panes[0];
 	if (!activePane) throw createFunctionalError("execution", {
 		code: ErrorCodes.TERMINAL_COMMAND_FAILED,
 		message: "No active wezterm pane detected",
@@ -1485,7 +1589,8 @@ const waitForPaneRegistration = async ({ paneId, listWindows, windowHint }) => {
 		}
 	});
 };
-const resolveInitialPane = async ({ windowMode, prompt, dryRun, listWindows, runCommand, logCommand, initialCwd, workspaceHint, initialList }) => {
+const resolveInitialPane = async ({ windowMode, prompt, dryRun, listWindows, runCommand, logCommand, initialCwd, workspaceHint, initialList, preferredPaneId }) => {
+	const preferredPaneIdValue = typeof preferredPaneId === "string" && preferredPaneId.length > 0 ? preferredPaneId : void 0;
 	if (windowMode === "current-window") {
 		const snapshot = initialList ?? await listWindows();
 		const scoped = filterWindowsByWorkspace(snapshot, workspaceHint);
@@ -1493,12 +1598,14 @@ const resolveInitialPane = async ({ windowMode, prompt, dryRun, listWindows, run
 			list: scoped,
 			prompt,
 			dryRun,
-			logCommand
+			logCommand,
+			preferredPaneId: preferredPaneIdValue
 		});
 	}
 	const existingSnapshot = initialList ?? await listWindows();
 	const scopedExisting = filterWindowsByWorkspace(existingSnapshot, workspaceHint);
-	const activeWindow = findActiveWindow(scopedExisting);
+	const scopedPreferredWindowId = preferredPaneIdValue !== void 0 ? findWindowContainingPane(scopedExisting, preferredPaneIdValue) : void 0;
+	const activeWindow = (scopedPreferredWindowId !== void 0 ? scopedExisting.windows.find((window) => window.windowId === scopedPreferredWindowId) : void 0) ?? findActiveWindow(scopedExisting);
 	if (activeWindow) {
 		const args$1 = [
 			"spawn",
@@ -1618,7 +1725,14 @@ const sendTextToPane = async ({ paneId, text, runCommand, context }) => {
 		appendCarriageReturn(text)
 	], context);
 };
-const applyTerminalCommands = async ({ terminals, paneMap, runCommand }) => {
+const applyTerminalCommands = async ({ terminals, paneMap, runCommand, focusPaneVirtualId }) => {
+	const nameToRealIdMap = buildNameToRealIdMap(terminals, paneMap);
+	if (!paneMap.has(focusPaneVirtualId)) throw createFunctionalError("execution", {
+		code: ErrorCodes.INVALID_PANE,
+		message: `Unknown focus pane: ${focusPaneVirtualId}`,
+		path: focusPaneVirtualId
+	});
+	const focusPaneRealId = resolveRealPaneId(paneMap, focusPaneVirtualId, { stepId: focusPaneVirtualId });
 	for (const terminal of terminals) {
 		const realPaneId = resolveRealPaneId(paneMap, terminal.virtualPaneId, { stepId: terminal.virtualPaneId });
 		if (typeof terminal.cwd === "string" && terminal.cwd.length > 0) {
@@ -1646,16 +1760,42 @@ const applyTerminalCommands = async ({ terminals, paneMap, runCommand }) => {
 				}
 			});
 		}
-		if (typeof terminal.command === "string" && terminal.command.length > 0) await sendTextToPane({
-			paneId: realPaneId,
-			text: terminal.command,
-			runCommand,
-			context: {
-				message: `Failed to execute command for pane ${terminal.virtualPaneId}`,
-				path: terminal.virtualPaneId,
-				details: { command: terminal.command }
+		if (typeof terminal.command === "string" && terminal.command.length > 0) {
+			const focusPaneRealIdForCommand = terminal.command.includes("{{focus_pane}}") ? focusPaneRealId : "";
+			let commandWithTokensReplaced;
+			try {
+				commandWithTokensReplaced = replaceTemplateTokens({
+					command: terminal.command,
+					currentPaneRealId: realPaneId,
+					focusPaneRealId: focusPaneRealIdForCommand,
+					nameToRealIdMap
+				});
+			} catch (error) {
+				if (error instanceof TemplateTokenError) throw createFunctionalError("execution", {
+					code: "TEMPLATE_TOKEN_ERROR",
+					message: `Template token resolution failed for pane ${terminal.virtualPaneId}: ${error.message}`,
+					path: terminal.virtualPaneId,
+					details: {
+						command: terminal.command,
+						tokenType: error.tokenType,
+						availablePanes: error.availablePanes
+					}
+				});
+				throw error;
 			}
-		});
+			if (terminal.ephemeral === true) if (terminal.closeOnError === true) commandWithTokensReplaced = `${commandWithTokensReplaced}; exit`;
+			else commandWithTokensReplaced = `${commandWithTokensReplaced}; [ $? -eq 0 ] && exit`;
+			await sendTextToPane({
+				paneId: realPaneId,
+				text: commandWithTokensReplaced,
+				runCommand,
+				context: {
+					message: `Failed to execute command for pane ${terminal.virtualPaneId}`,
+					path: terminal.virtualPaneId,
+					details: { command: terminal.command }
+				}
+			});
+		}
 	}
 };
 const applySplitStep = async ({ step, paneMap, windowId, runCommand, listWindows, logPaneMapping }) => {
@@ -1744,7 +1884,8 @@ const createWeztermBackend = (context) => {
 			logCommand,
 			initialCwd,
 			workspaceHint,
-			initialList: cachedInitialList
+			initialList: cachedInitialList,
+			preferredPaneId: context.paneId
 		});
 		registerPaneWithAncestors(paneMap, initialVirtualPaneId, initialPaneId);
 		logPaneMapping(initialVirtualPaneId, initialPaneId);
@@ -1770,7 +1911,8 @@ const createWeztermBackend = (context) => {
 		await applyTerminalCommands({
 			terminals: emission.terminals,
 			paneMap,
-			runCommand
+			runCommand,
+			focusPaneVirtualId: emission.summary.focusPaneId
 		});
 		const focusVirtual = emission.summary.focusPaneId;
 		const focusPaneId = typeof focusVirtual === "string" ? paneMap.get(focusVirtual) : void 0;
@@ -2035,6 +2177,8 @@ const parseTerminalPane = (node) => {
 	const command = typeof node.command === "string" ? node.command : void 0;
 	const cwd = typeof node.cwd === "string" ? node.cwd : void 0;
 	const focus = node.focus === true ? true : void 0;
+	const ephemeral = node.ephemeral === true ? true : void 0;
+	const closeOnError = node.closeOnError === true ? true : void 0;
 	const env = normalizeEnv(node.env);
 	const options = collectOptions(node, new Set([
 		"name",
@@ -2042,6 +2186,8 @@ const parseTerminalPane = (node) => {
 		"cwd",
 		"env",
 		"focus",
+		"ephemeral",
+		"closeOnError",
 		"options",
 		"title",
 		"delay"
@@ -2053,6 +2199,8 @@ const parseTerminalPane = (node) => {
 		cwd,
 		env,
 		focus,
+		ephemeral,
+		closeOnError,
 		options
 	};
 };
@@ -2173,7 +2321,9 @@ const createTerminalNode = ({ id, terminal, focusOverride }) => {
 		cwd: terminal.cwd,
 		env: terminal.env,
 		options: terminal.options,
-		focus: focusOverride === true ? true : terminal.focus === true
+		focus: focusOverride === true ? true : terminal.focus === true,
+		ephemeral: terminal.ephemeral,
+		closeOnError: terminal.closeOnError
 	};
 };
 const ensureFocus = (node, focusPaneId) => {
@@ -2277,7 +2427,9 @@ const collectTerminals = (node) => {
 		cwd: node.cwd,
 		env: node.env,
 		focus: node.focus,
-		name: node.name
+		name: node.name,
+		ephemeral: node.ephemeral,
+		closeOnError: node.closeOnError
 	}];
 	return node.panes.flatMap((pane) => collectTerminals(pane));
 };