feat(cli): add Sublime Text and Emacs Client editors, improve error messages and documentation (#21090)

Co-authored-by: Ananth Kini <ananthkini1@gmail.com>

packages/cli/src/ui/utils/editorUtils.ts

@@ -7,14 +7,33 @@
 import { spawn, spawnSync } from 'node:child_process';
 import type { ReadStream } from 'node:tty';
 import {
-  coreEvents,
+  ALL_EDITORS,
   CoreEvent,
+  coreEvents,
   type EditorType,
   getEditorCommand,
+  getEditorExtraArgs,
+  getEditorWaitFlag,
   isGuiEditor,
   isTerminalEditor,
+  isValidEditorType,
+  resolveEditorTypeFromCommand,
 } from '@google/gemini-cli-core';
 
+/**
+ * Command name substrings used to guess whether an unknown $VISUAL/$EDITOR
+ * value is a GUI editor. This is a fallback for editors not in the registry;
+ * registered editors are detected via resolveEditorTypeFromCommand instead.
+ */
+const HEURISTIC_GUI_COMMANDS = [
+  'code',
+  'cursor',
+  'subl',
+  'zed',
+  'atom',
+  'agy',
+] as const;
+
 /**
  * Opens a file in an external editor and waits for it to close.
  * Handles raw mode switching to ensure the editor can interact with the terminal.
@@ -23,36 +42,65 @@ import {
  * @param stdin The stdin stream from Ink/Node
  * @param setRawMode Function to toggle raw mode
  * @param preferredEditorType The user's preferred editor from config
+ * @param openInNewWindow Whether to open VS Code-family editors in a new window
  */
 export async function openFileInEditor(
   filePath: string,
   stdin: ReadStream | null | undefined,
   setRawMode: ((mode: boolean) => void) | undefined,
   preferredEditorType?: EditorType,
+  openInNewWindow?: boolean,
 ): Promise<void> {
   let command: string | undefined = undefined;
   const args = [filePath];
+  // Extra args that come before the file path (e.g. -nw for emacsclient)
+  const extraArgs: string[] = [];
 
   if (preferredEditorType) {
+    if (!isValidEditorType(preferredEditorType)) {
+      coreEvents.emitFeedback(
+        'error',
+        `Editor '${preferredEditorType}' is not a recognized editor identifier. ` +
+          `Supported editors: ${ALL_EDITORS.join(', ')}. ` +
+          `Use /editor to select one, or set the $VISUAL or $EDITOR environment variable.`,
+      );
+      return;
+    }
     command = getEditorCommand(preferredEditorType);
     if (isGuiEditor(preferredEditorType)) {
-      args.unshift('--wait');
+      args.unshift(getEditorWaitFlag(preferredEditorType));
     }
+    extraArgs.push(
+      ...getEditorExtraArgs(preferredEditorType, {
+        newWindow: openInNewWindow,
+      }),
+    );
   }
 
   if (!command) {
-    command = process.env['VISUAL'] ?? process.env['EDITOR'];
-    if (command) {
-      const lowerCommand = command.toLowerCase();
-      const isGui = ['code', 'cursor', 'subl', 'zed', 'atom'].some((gui) =>
-        lowerCommand.includes(gui),
-      );
-      if (
-        isGui &&
-        !lowerCommand.includes('--wait') &&
-        !lowerCommand.includes('-w')
-      ) {
-        args.unshift(lowerCommand.includes('subl') ? '-w' : '--wait');
+    const envCommand = process.env['VISUAL'] ?? process.env['EDITOR'];
+    if (envCommand) {
+      command = envCommand;
+      const [envExecutable = ''] = envCommand.split(' ');
+      const resolvedType = resolveEditorTypeFromCommand(envExecutable);
+      if (resolvedType) {
+        if (
+          isGuiEditor(resolvedType) &&
+          !envCommand.includes('--wait') &&
+          !envCommand.includes('-w')
+        ) {
+          args.unshift(getEditorWaitFlag(resolvedType));
+        }
+        extraArgs.push(
+          ...getEditorExtraArgs(resolvedType, { newWindow: openInNewWindow }),
+        );
+      } else {
+        // Heuristic fallback for commands not in the registry
+        const lower = envCommand.toLowerCase();
+        const isGui = HEURISTIC_GUI_COMMANDS.some((g) => lower.includes(g));
+        if (isGui && !lower.includes('--wait') && !lower.includes('-w')) {
+          args.unshift(lower.includes('subl') ? '-w' : '--wait');
+        }
       }
     }
   }
@@ -66,7 +114,16 @@ export async function openFileInEditor(
   // Determine if we should use sync or async based on the command/editor type.
   // If we have a preferredEditorType, we can check if it's a terminal editor.
   // Otherwise, we guess based on the command name.
-  const terminalEditors = ['vi', 'vim', 'nvim', 'emacs', 'hx', 'nano'];
+  const terminalEditors = [
+    'vi',
+    'vim',
+    'nvim',
+    'emacs',
+    'emacsclient',
+    'hx',
+    'nano',
+    'micro',
+  ];
   const isTerminal = preferredEditorType
     ? isTerminalEditor(preferredEditorType)
     : terminalEditors.some((te) => executable.toLowerCase().includes(te));
@@ -86,58 +143,60 @@ export async function openFileInEditor(
 
   try {
     if (isTerminal) {
-      const result = spawnSync(executable, [...initialArgs, ...args], {
-        stdio: 'inherit',
-        shell: process.platform === 'win32',
-      });
-      if (result.error) {
-        coreEvents.emitFeedback(
-          'error',
-          '[editorUtils] external terminal editor error',
-          result.error,
-        );
-        throw result.error;
-      }
-      if (typeof result.status === 'number' && result.status !== 0) {
-        const err = new Error(
-          `External editor exited with status ${result.status}`,
-        );
-        coreEvents.emitFeedback(
-          'error',
-          '[editorUtils] external editor error',
-          err,
-        );
-        throw err;
-      }
-    } else {
-      await new Promise<void>((resolve, reject) => {
-        const child = spawn(executable, [...initialArgs, ...args], {
+      const result = spawnSync(
+        executable,
+        [...initialArgs, ...extraArgs, ...args],
+        {
           stdio: 'inherit',
           shell: process.platform === 'win32',
-        });
+        },
+      );
+      if (result.error) {
+        const spawnErr = result.error as NodeJS.ErrnoException;
+        coreEvents.emitFeedback(
+          'error',
+          spawnErr.code === 'ENOENT'
+            ? `Editor command '${executable}' was not found in PATH. Install it or use /editor to choose another editor.`
+            : (spawnErr.message ?? String(spawnErr)),
+        );
+        return;
+      }
+      if (typeof result.status === 'number' && result.status !== 0) {
+        coreEvents.emitFeedback(
+          'error',
+          `External editor exited with status ${result.status}`,
+        );
+        return;
+      }
+    } else {
+      await new Promise<void>((resolve) => {
+        const child = spawn(
+          executable,
+          [...initialArgs, ...extraArgs, ...args],
+          {
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+          },
+        );
 
         child.on('error', (err) => {
+          const spawnErr = err as NodeJS.ErrnoException;
+          resolve();
           coreEvents.emitFeedback(
             'error',
-            '[editorUtils] external editor spawn error',
-            err,
+            spawnErr.code === 'ENOENT'
+              ? `Editor command '${executable}' was not found in PATH. Install it or use /editor to choose another editor.`
+              : (spawnErr.message ?? String(spawnErr)),
           );
-          reject(err);
         });
 
         child.on('close', (status) => {
+          resolve();
           if (typeof status === 'number' && status !== 0) {
-            const err = new Error(
-              `External editor exited with status ${status}`,
-            );
             coreEvents.emitFeedback(
               'error',
-              '[editorUtils] external editor error',
-              err,
+              `External editor exited with status ${status}`,
             );
-            reject(err);
-          } else {
-            resolve();
           }
         });
       });