feat(tui): add spec name autocomplete for /run command (#89)

* feat(tui): add spec name autocomplete for /run command

- Add listSpecNames() utility to read .md files from specs directory
- Add fuzzyMatch() utility for sequential character matching
- Add specNames field to SessionState, loaded at startup and refreshed after /init
- Update CommandDropdown to use fuzzy matching instead of includes()
- Update ChatInput to detect /run <space> and show spec dropdown
- Thread specSuggestions from MainShell → ChatInput via sessionState.specNames

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* test(tui): add integration and keyboard navigation tests for spec autocomplete

- Add MainShell integration tests verifying specNames flows from
  SessionState through to the /run dropdown (4 scenarios: with specs,
  filtered results, undefined specNames, empty specNames)
- Add CommandDropdown keyboard navigation tests: Enter selects first
  item, Down arrow advances selection, Up arrow reverses it, clamping
  at index 0, Escape calls onCancel

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(tui): address code review feedback for spec autocomplete

- Add specSuggestions to updateValue dependency array (stale closure fix)
- Use node: prefix for fs/promises and path imports (codebase convention)
- Guard getMaxCommandWidth against empty array (prevents RangeError)
- Wrap handleInitComplete spec loading in try-catch (unhandled rejection fix)
- Log non-ENOENT errors in listSpecNames for debuggability

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(tui): address code review round 2 for spec autocomplete

- Remove unused `join` import from spec-names.ts
- Fix duplicate history entry when selecting spec from dropdown
- Refresh spec name cache after interview creates a new spec
- Clean up self-correcting comment in CommandDropdown test

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(tui): address code review round 3 for spec autocomplete

- Add itemPrefix prop to CommandDropdown (default '/') so spec names
  render without misleading slash prefix
- Hoist RUN_PREFIX constant to module scope (avoid per-render allocation)
- Wrap specSuggestions in useMemo to prevent unnecessary re-renders
- Replace console.debug with logger.debug for consistency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: federiconeri

src/index.ts

@@ -1,5 +1,6 @@
 import { createSessionState } from './repl/session-state.js';
 import { hasConfig, loadConfigWithDefaults } from './utils/config.js';
+import { listSpecNames } from './utils/spec-names.js';
 import { AVAILABLE_MODELS, getAvailableProvider, isAnthropicAlias } from './ai/providers.js';
 import type { AIProvider } from './ai/providers.js';
 import { notifyIfUpdateAvailable } from './utils/update-check.js';
@@ -61,14 +62,20 @@ async function startInkTui(initialScreen: AppScreen = 'shell', interviewFeature?
       }
     }
 
-    return createSessionState(
+    const specsDir = config
+      ? join(projectRoot, config.paths.specs)
+      : join(projectRoot, '.ralph/specs');
+    const specNames = await listSpecNames(specsDir);
+
+    const state = createSessionState(
       projectRoot,
       provider, // May be null if no API key
       model,
       undefined, // No scan result yet
       config,
       isInitialized
     );
+    return { ...state, specNames };
   }
 
   const initialState = await createCurrentSessionState();

src/repl/session-state.ts

@@ -27,6 +27,8 @@ export interface SessionState {
   conversationContext?: string;
   /** Whether /init has been run in this session */
   initialized: boolean;
+  /** Cached spec names from the configured specs directory */
+  specNames?: string[];
 }
 
 /**

src/tui/app.tsx

@@ -17,6 +17,7 @@ import type { AIProvider } from '../ai/providers.js';
 import type { ScanResult } from '../scanner/types.js';
 import type { SessionState } from '../repl/session-state.js';
 import { loadConfigWithDefaults } from '../utils/config.js';
+import { listSpecNames } from '../utils/spec-names.js';
 import { logger } from '../utils/logger.js';
 import { InterviewScreen } from './screens/InterviewScreen.js';
 import { InitScreen } from './screens/InitScreen.js';
@@ -135,6 +136,15 @@ export function App({
 
           savedPath = join(specsDir, `${featureName}.md`);
           writeFileSync(savedPath, spec, 'utf-8');
+
+          // Refresh spec name cache so the new spec shows in /run autocomplete
+          try {
+            const updatedSpecNames = await listSpecNames(specsDir);
+            setSessionState((prev) => ({ ...prev, specNames: updatedSpecNames }));
+          } catch {
+            // Non-critical: autocomplete will update on next restart
+          }
+
           onComplete?.(savedPath);
         } catch (err) {
           const reason = err instanceof Error ? err.message : String(err);
@@ -185,8 +195,19 @@ export function App({
   /**
    * Handle init completion - update state and navigate to shell
    */
-  const handleInitComplete = useCallback((newState: SessionState, generatedFiles?: string[]) => {
-    setSessionState(newState);
+  const handleInitComplete = useCallback(async (newState: SessionState, generatedFiles?: string[]) => {
+    // Refresh spec names after init (config may have changed)
+    let specNames: string[] = [];
+    try {
+      const specsDir = join(
+        newState.projectRoot,
+        newState.config?.paths.specs ?? '.ralph/specs'
+      );
+      specNames = await listSpecNames(specsDir);
+    } catch {
+      // Non-critical: autocomplete will work without spec names
+    }
+    setSessionState({ ...newState, specNames });
     const fileCount = generatedFiles?.length ?? 0;
     const msg = fileCount > 0
       ? `\u2713 Initialization complete. Generated ${fileCount} configuration file${fileCount === 1 ? '' : 's'}.`

src/tui/components/ChatInput.test.tsx

@@ -163,4 +163,95 @@ describe('ChatInput', () => {
     expect(frame).toContain('help');
     instance.unmount();
   });
+
+  describe('spec autocomplete (/run argument mode)', () => {
+    const SPEC_SUGGESTIONS = [
+      { name: 'auth-system', description: '' },
+      { name: 'user-profile', description: '' },
+      { name: 'payment-flow', description: '' },
+    ];
+
+    it('shows spec dropdown when typing /run followed by space', async () => {
+      const onSubmit = vi.fn();
+      const instance = await renderAndWait(
+        () => render(<ChatInput onSubmit={onSubmit} specSuggestions={SPEC_SUGGESTIONS} />),
+      );
+
+      await typeText(instance, '/run ');
+
+      const frame = stripAnsi(instance.lastFrame() ?? '');
+      expect(frame).toContain('auth-system');
+      expect(frame).toContain('user-profile');
+      instance.unmount();
+    });
+
+    it('does not show spec dropdown without trailing space', async () => {
+      const onSubmit = vi.fn();
+      const instance = await renderAndWait(
+        () => render(<ChatInput onSubmit={onSubmit} specSuggestions={SPEC_SUGGESTIONS} />),
+      );
+
+      await typeText(instance, '/run');
+
+      const frame = stripAnsi(instance.lastFrame() ?? '');
+      // Should show command dropdown for /run command, not spec dropdown
+      expect(frame).toContain('run');
+      // auth-system should not be visible (it's a spec name)
+      expect(frame).not.toContain('auth-system');
+      instance.unmount();
+    });
+
+    it('does not show spec dropdown for non-/run commands with space', async () => {
+      const onSubmit = vi.fn();
+      const instance = await renderAndWait(
+        () => render(<ChatInput onSubmit={onSubmit} specSuggestions={SPEC_SUGGESTIONS} />),
+      );
+
+      await typeText(instance, '/new ');
+
+      const frame = stripAnsi(instance.lastFrame() ?? '');
+      expect(frame).not.toContain('auth-system');
+      instance.unmount();
+    });
+
+    it('filters spec suggestions as user types after /run ', async () => {
+      const onSubmit = vi.fn();
+      const instance = await renderAndWait(
+        () => render(<ChatInput onSubmit={onSubmit} specSuggestions={SPEC_SUGGESTIONS} />),
+      );
+
+      await typeText(instance, '/run auth');
+
+      const frame = stripAnsi(instance.lastFrame() ?? '');
+      expect(frame).toContain('auth-system');
+      expect(frame).not.toContain('payment-flow');
+      instance.unmount();
+    });
+
+    it('does not show spec dropdown when specSuggestions is empty', async () => {
+      const onSubmit = vi.fn();
+      const instance = await renderAndWait(
+        () => render(<ChatInput onSubmit={onSubmit} specSuggestions={[]} />),
+      );
+
+      await typeText(instance, '/run ');
+
+      const frame = stripAnsi(instance.lastFrame() ?? '');
+      expect(frame).not.toContain('auth-system');
+      instance.unmount();
+    });
+
+    it('does not show spec dropdown when specSuggestions is undefined', async () => {
+      const onSubmit = vi.fn();
+      const instance = await renderAndWait(
+        () => render(<ChatInput onSubmit={onSubmit} />),
+      );
+
+      await typeText(instance, '/run ');
+
+      const frame = stripAnsi(instance.lastFrame() ?? '');
+      expect(frame).not.toContain('auth-system');
+      instance.unmount();
+    });
+  });
 });

src/tui/components/ChatInput.tsx

@@ -27,6 +27,8 @@ import {
   moveCursorByWordRight,
 } from '../utils/input-utils.js';
 
+const RUN_PREFIX = '/run ';
+
 /**
  * Props for the ChatInput component
  */
@@ -43,6 +45,8 @@ export interface ChatInputProps {
   commands?: Command[];
   /** Called when a slash command is selected */
   onCommand?: (command: string) => void;
+  /** Spec suggestions for /run argument autocomplete */
+  specSuggestions?: Command[];
 }
 
 /**
@@ -82,6 +86,7 @@ export function ChatInput({
   allowEmpty = false,
   commands = DEFAULT_COMMANDS,
   onCommand,
+  specSuggestions,
 }: ChatInputProps): React.ReactElement {
   const [value, setValue] = useState('');
   const [cursorOffset, setCursorOffset] = useState(0);
@@ -97,6 +102,14 @@ export function ChatInput({
   // Only filter on the command name part (before the first space)
   const commandFilter = isSlashCommand ? value.slice(1).split(' ')[0] : '';
 
+  // Detect "/run " argument autocomplete mode
+  const isRunArgMode =
+    specSuggestions !== undefined &&
+    specSuggestions.length > 0 &&
+    value.startsWith(RUN_PREFIX);
+  // The text the user has typed after "/run "
+  const runArgFilter = isRunArgMode ? value.slice(RUN_PREFIX.length) : '';
+
   // Store draft input when starting history navigation
   const draftRef = useRef<string>('');
 
@@ -116,13 +129,18 @@ export function ChatInput({
         resetNavigation();
       }
 
-      if (nextValue.startsWith('/') && !nextValue.includes(' ')) {
+      const isCommandMode = nextValue.startsWith('/') && !nextValue.includes(' ');
+      const isRunArgModeNext =
+        specSuggestions !== undefined &&
+        specSuggestions.length > 0 &&
+        nextValue.startsWith('/run ');
+      if (isCommandMode || isRunArgModeNext) {
         setShowDropdown(true);
       } else {
         setShowDropdown(false);
       }
     },
-    [clampCursor, resetNavigation]
+    [clampCursor, resetNavigation, specSuggestions]
   );
 
 
@@ -322,6 +340,18 @@ export function ChatInput({
     [onCommand, onSubmit, addToHistory, updateValue]
   );
 
+  /**
+   * Handle spec selection from /run argument dropdown
+   */
+  const handleSpecSelect = useCallback(
+    (specName: string) => {
+      const newValue = `/run ${specName}`;
+      updateValue(newValue, newValue.length, true);
+      setShowDropdown(false);
+    },
+    [updateValue]
+  );
+
   /**
    * Handle dropdown cancel
    */
@@ -366,8 +396,19 @@ export function ChatInput({
         )}
       </Box>
 
+      {/* Spec argument dropdown for /run <spec> */}
+      {showDropdown && isRunArgMode && specSuggestions && (
+        <CommandDropdown
+          commands={specSuggestions}
+          filter={runArgFilter}
+          onSelect={handleSpecSelect}
+          onCancel={handleDropdownCancel}
+          itemPrefix=""
+        />
+      )}
+
       {/* Command dropdown below input - only show while typing command name, not arguments */}
-      {showDropdown && isSlashCommand && !hasSpace && (
+      {showDropdown && isSlashCommand && !hasSpace && !isRunArgMode && (
         <CommandDropdown
           commands={commands}
           filter={commandFilter}