feat(app): Enhanced slash commands with app navigation and fixes

[benzntech]

Summary

This PR enhances the slash command system with context-aware app navigation commands, bug fixes from code review, and improved code quality. The implementation is inspired by HAPI's extensible architecture while maintaining existing patterns.

New Features

1. App Navigation Commands

Add navigation slash commands that work in both web app and Telegram:

• /home - Navigate to home screen
• /sessions - View all active sessions
• /profiles - Manage profiles
• /settings - Open settings
• /help - Show help (context-aware: alert in Telegram, navigation in web)

2. Context-Aware Display

// Enable app commands when needed
const suggestions = await searchCommands(sessionId, query, {
    includeAppCommands: true  // Show navigation commands
});

3. Command Handler Hook

New useCommandHandler hook with:

• Automatic routing based on command source (app/sdk/builtin)
• Telegram haptic feedback integration
• Clear callback API for SDK commands
• TypeScript support with CommandItem interface

4. Command Source Tracking

interface CommandItem {
    command: string;
    description?: string;
    source?: 'builtin' | 'sdk' | 'app';  // Track command origin
}

Bug Fixes

Fix #182: Commands filtered by first letter

Problem: Only commands starting with 'c' appeared in autocomplete (iOS bug)

Solution: Fuse.js fuzzy search searches across all command names and descriptions, not filtered by first letter.

Code:

const fuse = new Fuse(commands, {
    keys: [
        { name: 'command', weight: 0.7 },
        { name: 'description', weight: 0.3 }
    ]
});

Remove 'help' Conflict

Problem: help was in both IGNORED_COMMANDS and APP_COMMANDS

Solution: Removed from ignore list since we provide it as an app navigation command.

Improved Duplicate Detection

Problem: Only checked DEFAULT_COMMANDS for duplicates, could miss conflicts with APP_COMMANDS

Solution:

// Before: Only checked defaults
if (!commands.find(c => c.command === cmd)) { ... }

// After: Checks all existing commands
const existingCommand = commands.find(c => c.command === cmd);
if (!existingCommand) { ... }

Fixed React Dependency Arrays

Problem: options object in dependencies caused unnecessary re-renders

Solution: Destructure callbacks at hook top level:

const { onCommandExecuted, onUnknownCommand, onSdkCommand } = options;
// Use individual callbacks in dependency array

Code Quality Improvements

1. Exported Command Constants

Before: Command lists duplicated in two files

After: Single source of truth

// suggestionCommands.ts
export const APP_COMMAND_NAMES = ['home', 'sessions', ...] as const;
export const BUILTIN_COMMAND_NAMES = ['compact', 'clear'] as const;

// useCommandHandler.ts
import { APP_COMMAND_NAMES, BUILTIN_COMMAND_NAMES } from '@/sync/suggestionCommands';

2. Clear SDK Command API

Before: SDK commands had no handler (unclear behavior)

After: Explicit callback:

const { executeCommandItem } = useCommandHandler({
    onSdkCommand: (cmd) => {
        sendMessageToCLI(`/${cmd}`);  // Clear contract
    }
});

Documentation

SLASH_COMMANDS.md

Complete implementation guide with:

• Architecture diagram
• Usage examples
• Command definitions
• Testing checklist
• Integration guide

CODE_REVIEW_FIXES.md

All fixes applied with before/after code examples and migration guide.

RELATED_ISSUES.md

Analysis of existing issues and PRs:

• Issue Only slash commands starting with c #182 (fixed)
• Issue Feature request: all CC slash commands handling. #14 (reviewed)
• Issue Doesn't pick up "custom commands" #203 (future work)
• PR feat(app): Add preset messages for quick slash command input #495 (compatible)

Testing

• TypeScript type checking passes
• Fuzzy search works across all commands (not filtered by first letter)
• App navigation commands work in web app
• App navigation commands work in Telegram
• No duplicate commands in autocomplete
• Haptic feedback works in Telegram Web App
• Help command shows different UI (alert vs navigation)
• SDK commands trigger onSdkCommand callback
• Builtin commands send to CLI
• No unnecessary re-renders

Performance

✅ Optimized dependency arrays
✅ Fuse.js fuzzy search (typo-tolerant)
✅ No caching issues (reads fresh from session metadata)

Backward Compatibility

✅ No breaking changes except:

• SDK commands now require onSdkCommand callback (previously unclear)
• includeAppCommands defaults to false (opt-in)

Related Issues & PRs

• Fixes Only slash commands starting with c #182 - Commands filtered by first letter (iOS bug)
• Addresses Feature request: all CC slash commands handling. #14 - Reviewed IGNORED_COMMANDS list
• Compatible with PR feat(app): Add preset messages for quick slash command input #495 - Preset messages work well with autocomplete
• Issue Doesn't pick up "custom commands" #203 - User commands (future work, requires CLI integration)

Migration Guide

For Existing Code Using Autocomplete

Before:

const suggestions = await searchCommands(sessionId, query);
// Only shows builtin + SDK commands

After:

const suggestions = await searchCommands(sessionId, query, {
    includeAppCommands: true  // Add navigation commands
});

For SDK Command Handling

Before:

const { executeCommandItem } = useCommandHandler();
// SDK commands did nothing

After:

const { executeCommandItem } = useCommandHandler({
    onSdkCommand: (cmd) => sendMessageToCLI(`/${cmd}`)
});

Next Steps (Future Work)

1. User-defined commands (Issue Doesn't pick up "custom commands" #203) - Scan ~/.claude/commands/ like HAPI
2. Command categories - Group commands by type
3. Command aliases - /h → /help, /s → /sessions
4. Keyboard shortcuts - Cmd+K to open command palette

---

Summary: This PR provides a production-ready slash command system with app navigation, fixes existing bugs, and improves code quality. The implementation is backward-compatible with clear migration paths.

[benzntech]

Additional Note: Telegram Integration

This PR also lays the groundwork for Telegram Mini App slash commands. While the full Telegram integration (files like useTelegramCommands.ts, TELEGRAM_COMMANDS.md) is not included in this PR, the core slash command system now supports:

1. Context-aware commands - includeAppCommands flag
2. Haptic feedback - Telegram Web App integration in useCommandHandler
3. Source tracking - source: 'app' for navigation commands
4. Extensible architecture - Easy to add Telegram-specific commands

The Telegram-specific files can be added in a follow-up PR once this foundation is merged.

Testing in Telegram Web App

import { useCommandHandler } from '@/hooks/useCommandHandler';
import { useTelegram } from '@/hooks/useTelegram';

function ChatInput() {
    const { isTelegramWebApp } = useTelegram();
    const { executeCommandItem } = useCommandHandler({
        onSdkCommand: (cmd) => sendMessageToCLI(`/${cmd}`)
    });

    // Commands work seamlessly in Telegram
    // Haptic feedback automatically provided
}

Let me know if you'd like the full Telegram integration included or prefer it as a separate PR!