fss-link 1.0.40 → 1.0.45

package/dist/ui/hooks/useSlashCompletion.test.ts

@@ -0,0 +1,434 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @vitest-environment jsdom */
+
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import { useSlashCompletion } from './useSlashCompletion.js';
+import { CommandContext, SlashCommand } from '../commands/types.js';
+import { useState } from 'react';
+import { Suggestion } from '../components/SuggestionsDisplay.js';
+
+// Test harness to capture the state from the hook's callbacks.
+function useTestHarnessForSlashCompletion(
+  enabled: boolean,
+  query: string | null,
+  slashCommands: readonly SlashCommand[],
+  commandContext: CommandContext,
+) {
+  const [suggestions, setSuggestions] = useState<Suggestion[]>([]);
+  const [isLoadingSuggestions, setIsLoadingSuggestions] = useState(false);
+  const [isPerfectMatch, setIsPerfectMatch] = useState(false);
+
+  const { completionStart, completionEnd } = useSlashCompletion({
+    enabled,
+    query,
+    slashCommands,
+    commandContext,
+    setSuggestions,
+    setIsLoadingSuggestions,
+    setIsPerfectMatch,
+  });
+
+  return {
+    suggestions,
+    isLoadingSuggestions,
+    isPerfectMatch,
+    completionStart,
+    completionEnd,
+  };
+}
+
+describe('useSlashCompletion', () => {
+  // A minimal mock is sufficient for these tests.
+  const mockCommandContext = {} as CommandContext;
+
+  describe('Top-Level Commands', () => {
+    it('should suggest all top-level commands for the root slash', async () => {
+      const slashCommands = [
+        { name: 'help', altNames: ['?'], description: 'Show help' },
+        {
+          name: 'stats',
+          altNames: ['usage'],
+          description: 'check session stats. Usage: /stats [model|tools]',
+        },
+        { name: 'clear', description: 'Clear the screen' },
+        {
+          name: 'memory',
+          description: 'Manage memory',
+          subCommands: [{ name: 'show', description: 'Show memory' }],
+        },
+        { name: 'chat', description: 'Manage chat history' },
+      ] as unknown as SlashCommand[];
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      expect(result.current.suggestions.length).toBe(slashCommands.length);
+      expect(result.current.suggestions.map((s) => s.label)).toEqual(
+        expect.arrayContaining(['help', 'clear', 'memory', 'chat', 'stats']),
+      );
+    });
+
+    it('should filter commands based on partial input', async () => {
+      const slashCommands = [
+        { name: 'memory', description: 'Manage memory' },
+      ] as unknown as SlashCommand[];
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/mem',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      expect(result.current.suggestions).toEqual([
+        { label: 'memory', value: 'memory', description: 'Manage memory' },
+      ]);
+    });
+
+    it('should suggest commands based on partial altNames', async () => {
+      const slashCommands = [
+        {
+          name: 'stats',
+          altNames: ['usage'],
+          description: 'check session stats. Usage: /stats [model|tools]',
+        },
+      ] as unknown as SlashCommand[];
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/usag',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      expect(result.current.suggestions).toEqual([
+        {
+          label: 'stats',
+          value: 'stats',
+          description: 'check session stats. Usage: /stats [model|tools]',
+        },
+      ]);
+    });
+
+    it('should NOT provide suggestions for a perfectly typed command that is a leaf node', async () => {
+      const slashCommands = [
+        { name: 'clear', description: 'Clear the screen', action: vi.fn() },
+      ] as unknown as SlashCommand[];
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/clear',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      expect(result.current.suggestions).toHaveLength(0);
+    });
+
+    it.each([['/?'], ['/usage']])(
+      'should not suggest commands when altNames is fully typed',
+      async (query) => {
+        const mockSlashCommands = [
+          {
+            name: 'help',
+            altNames: ['?'],
+            description: 'Show help',
+            action: vi.fn(),
+          },
+          {
+            name: 'stats',
+            altNames: ['usage'],
+            description: 'check session stats. Usage: /stats [model|tools]',
+            action: vi.fn(),
+          },
+        ] as unknown as SlashCommand[];
+
+        const { result } = renderHook(() =>
+          useTestHarnessForSlashCompletion(
+            true,
+            query,
+            mockSlashCommands,
+            mockCommandContext,
+          ),
+        );
+
+        expect(result.current.suggestions).toHaveLength(0);
+      },
+    );
+
+    it('should not provide suggestions for a fully typed command that has no sub-commands or argument completion', async () => {
+      const slashCommands = [
+        { name: 'clear', description: 'Clear the screen' },
+      ] as unknown as SlashCommand[];
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/clear ',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      expect(result.current.suggestions).toHaveLength(0);
+    });
+
+    it('should not provide suggestions for an unknown command', async () => {
+      const slashCommands = [
+        { name: 'help', description: 'Show help' },
+      ] as unknown as SlashCommand[];
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/unknown-command',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      expect(result.current.suggestions).toHaveLength(0);
+    });
+  });
+
+  describe('Sub-Commands', () => {
+    it('should suggest sub-commands for a parent command', async () => {
+      const slashCommands = [
+        {
+          name: 'memory',
+          description: 'Manage memory',
+          subCommands: [
+            { name: 'show', description: 'Show memory' },
+            { name: 'add', description: 'Add to memory' },
+          ],
+        },
+      ] as unknown as SlashCommand[];
+
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/memory',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      expect(result.current.suggestions).toHaveLength(2);
+      expect(result.current.suggestions).toEqual(
+        expect.arrayContaining([
+          { label: 'show', value: 'show', description: 'Show memory' },
+          { label: 'add', value: 'add', description: 'Add to memory' },
+        ]),
+      );
+    });
+
+    it('should suggest all sub-commands when the query ends with the parent command and a space', async () => {
+      const slashCommands = [
+        {
+          name: 'memory',
+          description: 'Manage memory',
+          subCommands: [
+            { name: 'show', description: 'Show memory' },
+            { name: 'add', description: 'Add to memory' },
+          ],
+        },
+      ] as unknown as SlashCommand[];
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/memory ',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      expect(result.current.suggestions).toHaveLength(2);
+      expect(result.current.suggestions).toEqual(
+        expect.arrayContaining([
+          { label: 'show', value: 'show', description: 'Show memory' },
+          { label: 'add', value: 'add', description: 'Add to memory' },
+        ]),
+      );
+    });
+
+    it('should filter sub-commands by prefix', async () => {
+      const slashCommands = [
+        {
+          name: 'memory',
+          description: 'Manage memory',
+          subCommands: [
+            { name: 'show', description: 'Show memory' },
+            { name: 'add', description: 'Add to memory' },
+          ],
+        },
+      ] as unknown as SlashCommand[];
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/memory a',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      expect(result.current.suggestions).toEqual([
+        { label: 'add', value: 'add', description: 'Add to memory' },
+      ]);
+    });
+
+    it('should provide no suggestions for an invalid sub-command', async () => {
+      const slashCommands = [
+        {
+          name: 'memory',
+          description: 'Manage memory',
+          subCommands: [
+            { name: 'show', description: 'Show memory' },
+            { name: 'add', description: 'Add to memory' },
+          ],
+        },
+      ] as unknown as SlashCommand[];
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/memory dothisnow',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      expect(result.current.suggestions).toHaveLength(0);
+    });
+  });
+
+  describe('Argument Completion', () => {
+    it('should call the command.completion function for argument suggestions', async () => {
+      const availableTags = [
+        'my-chat-tag-1',
+        'my-chat-tag-2',
+        'another-channel',
+      ];
+      const mockCompletionFn = vi
+        .fn()
+        .mockImplementation(
+          async (_context: CommandContext, partialArg: string) =>
+            availableTags.filter((tag) => tag.startsWith(partialArg)),
+        );
+
+      const slashCommands = [
+        {
+          name: 'chat',
+          description: 'Manage chat history',
+          subCommands: [
+            {
+              name: 'resume',
+              description: 'Resume a saved chat',
+              completion: mockCompletionFn,
+            },
+          ],
+        },
+      ] as unknown as SlashCommand[];
+
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/chat resume my-ch',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      await waitFor(() => {
+        expect(mockCompletionFn).toHaveBeenCalledWith(
+          mockCommandContext,
+          'my-ch',
+        );
+      });
+
+      await waitFor(() => {
+        expect(result.current.suggestions).toEqual([
+          { label: 'my-chat-tag-1', value: 'my-chat-tag-1' },
+          { label: 'my-chat-tag-2', value: 'my-chat-tag-2' },
+        ]);
+      });
+    });
+
+    it('should call command.completion with an empty string when args start with a space', async () => {
+      const mockCompletionFn = vi
+        .fn()
+        .mockResolvedValue(['my-chat-tag-1', 'my-chat-tag-2', 'my-channel']);
+
+      const slashCommands = [
+        {
+          name: 'chat',
+          description: 'Manage chat history',
+          subCommands: [
+            {
+              name: 'resume',
+              description: 'Resume a saved chat',
+              completion: mockCompletionFn,
+            },
+          ],
+        },
+      ] as unknown as SlashCommand[];
+
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/chat resume ',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      await waitFor(() => {
+        expect(mockCompletionFn).toHaveBeenCalledWith(mockCommandContext, '');
+      });
+
+      await waitFor(() => {
+        expect(result.current.suggestions).toHaveLength(3);
+      });
+    });
+
+    it('should handle completion function that returns null', async () => {
+      const completionFn = vi.fn().mockResolvedValue(null);
+      const slashCommands = [
+        {
+          name: 'chat',
+          description: 'Manage chat history',
+          subCommands: [
+            {
+              name: 'resume',
+              description: 'Resume a saved chat',
+              completion: completionFn,
+            },
+          ],
+        },
+      ] as unknown as SlashCommand[];
+
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/chat resume ',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      await waitFor(() => {
+        expect(result.current.suggestions).toHaveLength(0);
+      });
+    });
+  });
+});

package/dist/ui/hooks/useSlashCompletion.ts

@@ -0,0 +1,187 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useState, useEffect } from 'react';
+import { Suggestion } from '../components/SuggestionsDisplay.js';
+import { CommandContext, SlashCommand } from '../commands/types.js';
+
+export interface UseSlashCompletionProps {
+  enabled: boolean;
+  query: string | null;
+  slashCommands: readonly SlashCommand[];
+  commandContext: CommandContext;
+  setSuggestions: (suggestions: Suggestion[]) => void;
+  setIsLoadingSuggestions: (isLoading: boolean) => void;
+  setIsPerfectMatch: (isMatch: boolean) => void;
+}
+
+export function useSlashCompletion(props: UseSlashCompletionProps): {
+  completionStart: number;
+  completionEnd: number;
+} {
+  const {
+    enabled,
+    query,
+    slashCommands,
+    commandContext,
+    setSuggestions,
+    setIsLoadingSuggestions,
+    setIsPerfectMatch,
+  } = props;
+  const [completionStart, setCompletionStart] = useState(-1);
+  const [completionEnd, setCompletionEnd] = useState(-1);
+
+  useEffect(() => {
+    if (!enabled || query === null) {
+      return;
+    }
+
+    const fullPath = query?.substring(1) || '';
+    const hasTrailingSpace = !!query?.endsWith(' ');
+    const rawParts = fullPath.split(/\s+/).filter((p) => p);
+    let commandPathParts = rawParts;
+    let partial = '';
+
+    if (!hasTrailingSpace && rawParts.length > 0) {
+      partial = rawParts[rawParts.length - 1];
+      commandPathParts = rawParts.slice(0, -1);
+    }
+
+    let currentLevel: readonly SlashCommand[] | undefined = slashCommands;
+    let leafCommand: SlashCommand | null = null;
+
+    for (const part of commandPathParts) {
+      if (!currentLevel) {
+        leafCommand = null;
+        currentLevel = [];
+        break;
+      }
+      const found: SlashCommand | undefined = currentLevel.find(
+        (cmd) => cmd.name === part || cmd.altNames?.includes(part),
+      );
+      if (found) {
+        leafCommand = found;
+        currentLevel = found.subCommands as readonly SlashCommand[] | undefined;
+      } else {
+        leafCommand = null;
+        currentLevel = [];
+        break;
+      }
+    }
+
+    let exactMatchAsParent: SlashCommand | undefined;
+    if (!hasTrailingSpace && currentLevel) {
+      exactMatchAsParent = currentLevel.find(
+        (cmd) =>
+          (cmd.name === partial || cmd.altNames?.includes(partial)) &&
+          cmd.subCommands,
+      );
+
+      if (exactMatchAsParent) {
+        leafCommand = exactMatchAsParent;
+        currentLevel = exactMatchAsParent.subCommands;
+        partial = '';
+      }
+    }
+
+    setIsPerfectMatch(false);
+    if (!hasTrailingSpace) {
+      if (leafCommand && partial === '' && leafCommand.action) {
+        setIsPerfectMatch(true);
+      } else if (currentLevel) {
+        const perfectMatch = currentLevel.find(
+          (cmd) =>
+            (cmd.name === partial || cmd.altNames?.includes(partial)) &&
+            cmd.action,
+        );
+        if (perfectMatch) {
+          setIsPerfectMatch(true);
+        }
+      }
+    }
+
+    const depth = commandPathParts.length;
+    const isArgumentCompletion =
+      leafCommand?.completion &&
+      (hasTrailingSpace ||
+        (rawParts.length > depth && depth > 0 && partial !== ''));
+
+    if (hasTrailingSpace || exactMatchAsParent) {
+      setCompletionStart(query.length);
+      setCompletionEnd(query.length);
+    } else if (partial) {
+      if (isArgumentCompletion) {
+        const commandSoFar = `/${commandPathParts.join(' ')}`;
+        const argStartIndex =
+          commandSoFar.length + (commandPathParts.length > 0 ? 1 : 0);
+        setCompletionStart(argStartIndex);
+      } else {
+        setCompletionStart(query.length - partial.length);
+      }
+      setCompletionEnd(query.length);
+    } else {
+      setCompletionStart(1);
+      setCompletionEnd(query.length);
+    }
+
+    if (isArgumentCompletion) {
+      const fetchAndSetSuggestions = async () => {
+        setIsLoadingSuggestions(true);
+        const argString = rawParts.slice(depth).join(' ');
+        const results =
+          (await leafCommand!.completion!(commandContext, argString)) || [];
+        const finalSuggestions = results.map((s) => ({ label: s, value: s }));
+        setSuggestions(finalSuggestions);
+        setIsLoadingSuggestions(false);
+      };
+      fetchAndSetSuggestions();
+      return;
+    }
+
+    const commandsToSearch = currentLevel || [];
+    if (commandsToSearch.length > 0) {
+      let potentialSuggestions = commandsToSearch.filter(
+        (cmd) =>
+          cmd.description &&
+          (cmd.name.startsWith(partial) ||
+            cmd.altNames?.some((alt) => alt.startsWith(partial))),
+      );
+
+      if (potentialSuggestions.length > 0 && !hasTrailingSpace) {
+        const perfectMatch = potentialSuggestions.find(
+          (s) => s.name === partial || s.altNames?.includes(partial),
+        );
+        if (perfectMatch && perfectMatch.action) {
+          potentialSuggestions = [];
+        }
+      }
+
+      const finalSuggestions = potentialSuggestions.map((cmd) => ({
+        label: cmd.name,
+        value: cmd.name,
+        description: cmd.description,
+      }));
+
+      setSuggestions(finalSuggestions);
+      return;
+    }
+
+    setSuggestions([]);
+  }, [
+    enabled,
+    query,
+    slashCommands,
+    commandContext,
+    setSuggestions,
+    setIsLoadingSuggestions,
+    setIsPerfectMatch,
+  ]);
+
+  return {
+    completionStart,
+    completionEnd,
+  };
+}

package/dist/ui/hooks/useStateAndRef.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React from 'react';
+
+// Hook to return state, state setter, and ref to most up-to-date value of state.
+// We need this in order to setState and reference the updated state multiple
+// times in the same function.
+export const useStateAndRef = <
+  // Everything but function.
+  T extends object | null | undefined | number | string,
+>(
+  initialValue: T,
+) => {
+  const [_, setState] = React.useState<T>(initialValue);
+  const ref = React.useRef<T>(initialValue);
+
+  const setStateInternal = React.useCallback<typeof setState>(
+    (newStateOrCallback) => {
+      let newValue: T;
+      if (typeof newStateOrCallback === 'function') {
+        newValue = newStateOrCallback(ref.current);
+      } else {
+        newValue = newStateOrCallback;
+      }
+      setState(newValue);
+      ref.current = newValue;
+    },
+    [],
+  );
+
+  return [ref, setStateInternal] as const;
+};

package/dist/ui/hooks/useTerminalSize.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useEffect, useState } from 'react';
+
+const TERMINAL_PADDING_X = 8;
+
+export function useTerminalSize(): { columns: number; rows: number } {
+  const [size, setSize] = useState({
+    columns: (process.stdout.columns || 60) - TERMINAL_PADDING_X,
+    rows: process.stdout.rows || 20,
+  });
+
+  useEffect(() => {
+    function updateSize() {
+      setSize({
+        columns: (process.stdout.columns || 60) - TERMINAL_PADDING_X,
+        rows: process.stdout.rows || 20,
+      });
+    }
+
+    process.stdout.on('resize', updateSize);
+    return () => {
+      process.stdout.off('resize', updateSize);
+    };
+  }, []);
+
+  return size;
+}