feat: shell history (#1169)

4 files changed, 510 insertions, 2 deletions

diff --git a/packages/cli/src/ui/components/InputPrompt.test.tsx b/packages/cli/src/ui/components/InputPrompt.test.tsx
new file mode 100644
index 00000000..d0133e53
--- /dev/null
+++ b/packages/cli/src/ui/components/InputPrompt.test.tsx
@@ -0,0 +1,187 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { render } from 'ink-testing-library';
+import { InputPrompt, InputPromptProps } from './InputPrompt.js';
+import type { TextBuffer } from './shared/text-buffer.js';
+import { Config } from '@gemini-cli/core';
+import { vi } from 'vitest';
+import { useShellHistory } from '../hooks/useShellHistory.js';
+import { useCompletion } from '../hooks/useCompletion.js';
+import { useInputHistory } from '../hooks/useInputHistory.js';
+
+vi.mock('../hooks/useShellHistory.js');
+vi.mock('../hooks/useCompletion.js');
+vi.mock('../hooks/useInputHistory.js');
+
+type MockedUseShellHistory = ReturnType<typeof useShellHistory>;
+type MockedUseCompletion = ReturnType<typeof useCompletion>;
+type MockedUseInputHistory = ReturnType<typeof useInputHistory>;
+
+describe('InputPrompt', () => {
+  let props: InputPromptProps;
+  let mockShellHistory: MockedUseShellHistory;
+  let mockCompletion: MockedUseCompletion;
+  let mockInputHistory: MockedUseInputHistory;
+  let mockBuffer: TextBuffer;
+
+  const mockedUseShellHistory = vi.mocked(useShellHistory);
+  const mockedUseCompletion = vi.mocked(useCompletion);
+  const mockedUseInputHistory = vi.mocked(useInputHistory);
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+
+    mockBuffer = {
+      text: '',
+      cursor: [0, 0],
+      lines: [''],
+      setText: vi.fn((newText: string) => {
+        mockBuffer.text = newText;
+        mockBuffer.lines = [newText];
+        mockBuffer.cursor = [0, newText.length];
+        mockBuffer.viewportVisualLines = [newText];
+        mockBuffer.allVisualLines = [newText];
+      }),
+      viewportVisualLines: [''],
+      allVisualLines: [''],
+      visualCursor: [0, 0],
+      visualScrollRow: 0,
+      handleInput: vi.fn(),
+      move: vi.fn(),
+      moveToOffset: vi.fn(),
+      killLineRight: vi.fn(),
+      killLineLeft: vi.fn(),
+      openInExternalEditor: vi.fn(),
+      newline: vi.fn(),
+      replaceRangeByOffset: vi.fn(),
+    } as unknown as TextBuffer;
+
+    mockShellHistory = {
+      addCommandToHistory: vi.fn(),
+      getPreviousCommand: vi.fn().mockReturnValue(null),
+      getNextCommand: vi.fn().mockReturnValue(null),
+      resetHistoryPosition: vi.fn(),
+    };
+    mockedUseShellHistory.mockReturnValue(mockShellHistory);
+
+    mockCompletion = {
+      suggestions: [],
+      activeSuggestionIndex: -1,
+      isLoadingSuggestions: false,
+      showSuggestions: false,
+      visibleStartIndex: 0,
+      navigateUp: vi.fn(),
+      navigateDown: vi.fn(),
+      resetCompletionState: vi.fn(),
+      setActiveSuggestionIndex: vi.fn(),
+      setShowSuggestions: vi.fn(),
+    };
+    mockedUseCompletion.mockReturnValue(mockCompletion);
+
+    mockInputHistory = {
+      navigateUp: vi.fn(),
+      navigateDown: vi.fn(),
+      handleSubmit: vi.fn(),
+    };
+    mockedUseInputHistory.mockReturnValue(mockInputHistory);
+
+    props = {
+      buffer: mockBuffer,
+      onSubmit: vi.fn(),
+      userMessages: [],
+      onClearScreen: vi.fn(),
+      config: {
+        getProjectRoot: () => '/test/project',
+        getTargetDir: () => '/test/project/src',
+      } as unknown as Config,
+      slashCommands: [],
+      shellModeActive: false,
+      setShellModeActive: vi.fn(),
+      inputWidth: 80,
+      suggestionsWidth: 80,
+      focus: true,
+    };
+  });
+
+  const wait = (ms = 50) => new Promise((resolve) => setTimeout(resolve, ms));
+
+  it('should call shellHistory.getPreviousCommand on up arrow in shell mode', async () => {
+    props.shellModeActive = true;
+    const { stdin, unmount } = render(<InputPrompt {...props} />);
+    await wait();
+
+    stdin.write('\u001B[A');
+    await wait();
+
+    expect(mockShellHistory.getPreviousCommand).toHaveBeenCalled();
+    unmount();
+  });
+
+  it('should call shellHistory.getNextCommand on down arrow in shell mode', async () => {
+    props.shellModeActive = true;
+    const { stdin, unmount } = render(<InputPrompt {...props} />);
+    await wait();
+
+    stdin.write('\u001B[B');
+    await wait();
+
+    expect(mockShellHistory.getNextCommand).toHaveBeenCalled();
+    unmount();
+  });
+
+  it('should set the buffer text when a shell history command is retrieved', async () => {
+    props.shellModeActive = true;
+    vi.mocked(mockShellHistory.getPreviousCommand).mockReturnValue(
+      'previous command',
+    );
+    const { stdin, unmount } = render(<InputPrompt {...props} />);
+    await wait();
+
+    stdin.write('\u001B[A');
+    await wait();
+
+    expect(mockShellHistory.getPreviousCommand).toHaveBeenCalled();
+    expect(props.buffer.setText).toHaveBeenCalledWith('previous command');
+    unmount();
+  });
+
+  it('should call shellHistory.addCommandToHistory on submit in shell mode', async () => {
+    props.shellModeActive = true;
+    props.buffer.setText('ls -l');
+    const { stdin, unmount } = render(<InputPrompt {...props} />);
+    await wait();
+
+    stdin.write('\r');
+    await wait();
+
+    expect(mockShellHistory.addCommandToHistory).toHaveBeenCalledWith('ls -l');
+    expect(props.onSubmit).toHaveBeenCalledWith('ls -l');
+    unmount();
+  });
+
+  it('should NOT call shell history methods when not in shell mode', async () => {
+    props.buffer.setText('some text');
+    const { stdin, unmount } = render(<InputPrompt {...props} />);
+    await wait();
+
+    stdin.write('\u001B[A'); // Up arrow
+    await wait();
+    stdin.write('\u001B[B'); // Down arrow
+    await wait();
+    stdin.write('\r'); // Enter
+    await wait();
+
+    expect(mockShellHistory.getPreviousCommand).not.toHaveBeenCalled();
+    expect(mockShellHistory.getNextCommand).not.toHaveBeenCalled();
+    expect(mockShellHistory.addCommandToHistory).not.toHaveBeenCalled();
+
+    expect(mockInputHistory.navigateUp).toHaveBeenCalled();
+    expect(mockInputHistory.navigateDown).toHaveBeenCalled();
+    expect(props.onSubmit).toHaveBeenCalledWith('some text');
+    unmount();
+  });
+});
diff --git a/packages/cli/src/ui/components/InputPrompt.tsx b/packages/cli/src/ui/components/InputPrompt.tsx
index 4d2f299b..f9f7ead6 100644
--- a/packages/cli/src/ui/components/InputPrompt.tsx
+++ b/packages/cli/src/ui/components/InputPrompt.tsx
@@ -13,6 +13,7 @@ import { cpSlice, cpLen, TextBuffer } from './shared/text-buffer.js';
 import chalk from 'chalk';
 import stringWidth from 'string-width';
 import process from 'node:process';
+import { useShellHistory } from '../hooks/useShellHistory.js';
 import { useCompletion } from '../hooks/useCompletion.js';
 import { isAtCommand, isSlashCommand } from '../utils/commandUtils.js';
 import { SlashCommand } from '../hooks/slashCommandProcessor.js';
@@ -58,16 +59,20 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
   );
 
   const resetCompletionState = completion.resetCompletionState;
+  const shellHistory = useShellHistory(config.getProjectRoot());
 
   const handleSubmitAndClear = useCallback(
     (submittedValue: string) => {
+      if (shellModeActive) {
+        shellHistory.addCommandToHistory(submittedValue);
+      }
       // Clear the buffer *before* calling onSubmit to prevent potential re-submission
       // if onSubmit triggers a re-render while the buffer still holds the old value.
       buffer.setText('');
       onSubmit(submittedValue);
       resetCompletionState();
     },
-    [onSubmit, buffer, resetCompletionState],
+    [onSubmit, buffer, resetCompletionState, shellModeActive, shellHistory],
   );
 
   const customSetTextAndResetCompletionSignal = useCallback(
@@ -81,7 +86,7 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
   const inputHistory = useInputHistory({
     userMessages,
     onSubmit: handleSubmitAndClear,
-    isActive: !completion.showSuggestions,
+    isActive: !completion.showSuggestions && !shellModeActive,
     currentQuery: buffer.text,
     onChange: customSetTextAndResetCompletionSignal,
   });
@@ -304,6 +309,13 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
 
       // Standard arrow navigation within the buffer
       if (key.upArrow && !completion.showSuggestions) {
+        if (shellModeActive) {
+          const prevCommand = shellHistory.getPreviousCommand();
+          if (prevCommand !== null) {
+            buffer.setText(prevCommand);
+          }
+          return;
+        }
         if (
           (buffer.allVisualLines.length === 1 || // Always navigate for single line
             (buffer.visualCursor[0] === 0 && buffer.visualScrollRow === 0)) &&
@@ -316,6 +328,13 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
         return;
       }
       if (key.downArrow && !completion.showSuggestions) {
+        if (shellModeActive) {
+          const nextCommand = shellHistory.getNextCommand();
+          if (nextCommand !== null) {
+            buffer.setText(nextCommand);
+          }
+          return;
+        }
         if (
           (buffer.allVisualLines.length === 1 || // Always navigate for single line
             buffer.visualCursor[0] === buffer.allVisualLines.length - 1) &&
diff --git a/packages/cli/src/ui/hooks/useShellHistory.test.ts b/packages/cli/src/ui/hooks/useShellHistory.test.ts
new file mode 100644
index 00000000..47fc5c62
--- /dev/null
+++ b/packages/cli/src/ui/hooks/useShellHistory.test.ts
@@ -0,0 +1,198 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { renderHook, act, waitFor } from '@testing-library/react';
+import { useShellHistory } from './useShellHistory.js';
+import * as fs from 'fs/promises';
+import path from 'path';
+
+vi.mock('fs/promises');
+
+const MOCKED_PROJECT_ROOT = '/test/project';
+const MOCKED_HISTORY_DIR = path.join(MOCKED_PROJECT_ROOT, '.gemini');
+const MOCKED_HISTORY_FILE = path.join(MOCKED_HISTORY_DIR, 'shell_history');
+
+describe('useShellHistory', () => {
+  const mockedFs = vi.mocked(fs);
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+
+    mockedFs.readFile.mockResolvedValue('');
+    mockedFs.writeFile.mockResolvedValue(undefined);
+    mockedFs.mkdir.mockResolvedValue(undefined);
+  });
+
+  it('should initialize and read the history file from the correct path', async () => {
+    mockedFs.readFile.mockResolvedValue('cmd1\ncmd2');
+    const { result } = renderHook(() => useShellHistory(MOCKED_PROJECT_ROOT));
+
+    await waitFor(() => {
+      expect(mockedFs.readFile).toHaveBeenCalledWith(
+        MOCKED_HISTORY_FILE,
+        'utf-8',
+      );
+    });
+
+    let command: string | null = null;
+    act(() => {
+      command = result.current.getPreviousCommand();
+    });
+
+    // History is loaded newest-first: ['cmd2', 'cmd1']
+    expect(command).toBe('cmd2');
+  });
+
+  it('should handle a non-existent history file gracefully', async () => {
+    const error = new Error('File not found') as NodeJS.ErrnoException;
+    error.code = 'ENOENT';
+    mockedFs.readFile.mockRejectedValue(error);
+
+    const { result } = renderHook(() => useShellHistory(MOCKED_PROJECT_ROOT));
+
+    await waitFor(() => {
+      expect(mockedFs.readFile).toHaveBeenCalled();
+    });
+
+    let command: string | null = null;
+    act(() => {
+      command = result.current.getPreviousCommand();
+    });
+
+    expect(command).toBe(null);
+  });
+
+  it('should add a command and write to the history file', async () => {
+    const { result } = renderHook(() => useShellHistory(MOCKED_PROJECT_ROOT));
+
+    await waitFor(() => expect(mockedFs.readFile).toHaveBeenCalled());
+
+    act(() => {
+      result.current.addCommandToHistory('new_command');
+    });
+
+    await waitFor(() => {
+      expect(mockedFs.mkdir).toHaveBeenCalledWith(MOCKED_HISTORY_DIR, {
+        recursive: true,
+      });
+      expect(mockedFs.writeFile).toHaveBeenCalledWith(
+        MOCKED_HISTORY_FILE,
+        'new_command', // Written to file oldest-first.
+      );
+    });
+
+    let command: string | null = null;
+    act(() => {
+      command = result.current.getPreviousCommand();
+    });
+    expect(command).toBe('new_command');
+  });
+
+  it('should navigate history correctly with previous/next commands', async () => {
+    mockedFs.readFile.mockResolvedValue('cmd1\ncmd2\ncmd3');
+    const { result } = renderHook(() => useShellHistory(MOCKED_PROJECT_ROOT));
+
+    // Wait for history to be loaded: ['cmd3', 'cmd2', 'cmd1']
+    await waitFor(() => expect(mockedFs.readFile).toHaveBeenCalled());
+
+    let command: string | null = null;
+
+    act(() => {
+      command = result.current.getPreviousCommand();
+    });
+    expect(command).toBe('cmd3');
+
+    act(() => {
+      command = result.current.getPreviousCommand();
+    });
+    expect(command).toBe('cmd2');
+
+    act(() => {
+      command = result.current.getPreviousCommand();
+    });
+    expect(command).toBe('cmd1');
+
+    // Should stay at the oldest command
+    act(() => {
+      command = result.current.getPreviousCommand();
+    });
+    expect(command).toBe('cmd1');
+
+    act(() => {
+      command = result.current.getNextCommand();
+    });
+    expect(command).toBe('cmd2');
+
+    act(() => {
+      command = result.current.getNextCommand();
+    });
+    expect(command).toBe('cmd3');
+
+    // Should return to the "new command" line (represented as empty string)
+    act(() => {
+      command = result.current.getNextCommand();
+    });
+    expect(command).toBe('');
+  });
+
+  it('should not add empty or whitespace-only commands to history', async () => {
+    const { result } = renderHook(() => useShellHistory(MOCKED_PROJECT_ROOT));
+    await waitFor(() => expect(mockedFs.readFile).toHaveBeenCalled());
+
+    act(() => {
+      result.current.addCommandToHistory('   ');
+    });
+
+    expect(mockedFs.writeFile).not.toHaveBeenCalled();
+  });
+
+  it('should truncate history to MAX_HISTORY_LENGTH (100)', async () => {
+    const oldCommands = Array.from({ length: 120 }, (_, i) => `old_cmd_${i}`);
+    mockedFs.readFile.mockResolvedValue(oldCommands.join('\n'));
+
+    const { result } = renderHook(() => useShellHistory(MOCKED_PROJECT_ROOT));
+    await waitFor(() => expect(mockedFs.readFile).toHaveBeenCalled());
+
+    act(() => {
+      result.current.addCommandToHistory('new_cmd');
+    });
+
+    // Wait for the async write to happen and then inspect the arguments.
+    await waitFor(() => expect(mockedFs.writeFile).toHaveBeenCalled());
+
+    // The hook stores history newest-first.
+    // Initial state: ['old_cmd_119', ..., 'old_cmd_0']
+    // After adding 'new_cmd': ['new_cmd', 'old_cmd_119', ..., 'old_cmd_21'] (100 items)
+    // Written to file (reversed): ['old_cmd_21', ..., 'old_cmd_119', 'new_cmd']
+    const writtenContent = mockedFs.writeFile.mock.calls[0][1] as string;
+    const writtenLines = writtenContent.split('\n');
+
+    expect(writtenLines.length).toBe(100);
+    expect(writtenLines[0]).toBe('old_cmd_21'); // New oldest command
+    expect(writtenLines[99]).toBe('new_cmd'); // Newest command
+  });
+
+  it('should move an existing command to the top when re-added', async () => {
+    mockedFs.readFile.mockResolvedValue('cmd1\ncmd2\ncmd3');
+    const { result } = renderHook(() => useShellHistory(MOCKED_PROJECT_ROOT));
+
+    // Initial state: ['cmd3', 'cmd2', 'cmd1']
+    await waitFor(() => expect(mockedFs.readFile).toHaveBeenCalled());
+
+    act(() => {
+      result.current.addCommandToHistory('cmd1');
+    });
+
+    // After re-adding 'cmd1': ['cmd1', 'cmd3', 'cmd2']
+    // Written to file (reversed): ['cmd2', 'cmd3', 'cmd1']
+    await waitFor(() => expect(mockedFs.writeFile).toHaveBeenCalled());
+
+    const writtenContent = mockedFs.writeFile.mock.calls[0][1] as string;
+    const writtenLines = writtenContent.split('\n');
+
+    expect(writtenLines).toEqual(['cmd2', 'cmd3', 'cmd1']);
+  });
+});
diff --git a/packages/cli/src/ui/hooks/useShellHistory.ts b/packages/cli/src/ui/hooks/useShellHistory.ts
new file mode 100644
index 00000000..0b1c8d98
--- /dev/null
+++ b/packages/cli/src/ui/hooks/useShellHistory.ts
@@ -0,0 +1,104 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { isNodeError } from '@gemini-cli/core';
+
+const HISTORY_DIR = '.gemini';
+const HISTORY_FILE = 'shell_history';
+const MAX_HISTORY_LENGTH = 100;
+
+async function getHistoryFilePath(projectRoot: string): Promise<string> {
+  const historyDir = path.join(projectRoot, HISTORY_DIR);
+  return path.join(historyDir, HISTORY_FILE);
+}
+
+async function readHistoryFile(filePath: string): Promise<string[]> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return content.split('\n').filter(Boolean);
+  } catch (error) {
+    if (isNodeError(error) && error.code === 'ENOENT') {
+      return [];
+    }
+    console.error('Error reading shell history:', error);
+    return [];
+  }
+}
+
+async function writeHistoryFile(
+  filePath: string,
+  history: string[],
+): Promise<void> {
+  try {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, history.join('\n'));
+  } catch (error) {
+    console.error('Error writing shell history:', error);
+  }
+}
+
+export function useShellHistory(projectRoot: string) {
+  const [history, setHistory] = useState<string[]>([]);
+  const [historyIndex, setHistoryIndex] = useState(-1);
+  const [historyFilePath, setHistoryFilePath] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function loadHistory() {
+      const filePath = await getHistoryFilePath(projectRoot);
+      setHistoryFilePath(filePath);
+      const loadedHistory = await readHistoryFile(filePath);
+      setHistory(loadedHistory.reverse()); // Newest first
+    }
+    loadHistory();
+  }, [projectRoot]);
+
+  const addCommandToHistory = useCallback(
+    (command: string) => {
+      if (!command.trim() || !historyFilePath) {
+        return;
+      }
+      const newHistory = [command, ...history.filter((c) => c !== command)]
+        .slice(0, MAX_HISTORY_LENGTH)
+        .filter(Boolean);
+      setHistory(newHistory);
+      // Write to file in reverse order (oldest first)
+      writeHistoryFile(historyFilePath, [...newHistory].reverse());
+      setHistoryIndex(-1);
+    },
+    [history, historyFilePath],
+  );
+
+  const getPreviousCommand = useCallback(() => {
+    if (history.length === 0) {
+      return null;
+    }
+    const newIndex = Math.min(historyIndex + 1, history.length - 1);
+    setHistoryIndex(newIndex);
+    return history[newIndex] ?? null;
+  }, [history, historyIndex]);
+
+  const getNextCommand = useCallback(() => {
+    if (historyIndex < 0) {
+      return null;
+    }
+    const newIndex = historyIndex - 1;
+    setHistoryIndex(newIndex);
+    if (newIndex < 0) {
+      return '';
+    }
+    return history[newIndex] ?? null;
+  }, [history, historyIndex]);
+
+  return {
+    addCommandToHistory,
+    getPreviousCommand,
+    getNextCommand,
+    resetHistoryPosition: () => setHistoryIndex(-1),
+  };
+}