Skip to content

CLAUDE.md

Latest commit

 

History

History
199 lines (154 loc) · 8.49 KB

CLAUDE.md

File metadata and controls

199 lines (154 loc) · 8.49 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Quick Command Buttons is a VS Code extension that adds customizable command buttons to the status bar. It allows users to execute terminal commands and VS Code API functions with one click, supports infinite nesting of command groups, and features a React-based visual configuration UI.

Development Commands

Extension Development

# Extension source (TypeScript)
cd src/extension
npm run compile      # Compile TypeScript
npm run lint         # Run ESLint
npm run test         # Run Vitest tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Generate coverage report
npm run test:ci      # CI test mode

# Package extension
npm run package          # Create .vsix package
npm run install-package  # Install locally
npm run vsce-publish     # Publish to VS Code Marketplace
npm run ovsx-publish     # Publish to Open VSX Registry

Web View Development

# React + Vite configuration UI
cd src/view
npm run dev      # Start dev server
npm run build    # Build for production
npm run lint     # Run ESLint
npm run preview  # Preview build

Architecture

Extension Core Architecture

The extension follows a dependency injection pattern with clear separation of concerns:

  1. Main Entry (src/extension/main.ts): Orchestrates initialization, registers commands, manages lifecycle
  2. Adapters (src/internal/adapters.ts): Abstraction layer for VS Code API (enables testing)
  3. Managers (src/internal/managers/): Domain-specific business logic
    • StatusBarManager: Status bar button lifecycle and rendering
    • TerminalManager: Terminal creation and command execution
    • ConfigManager: Configuration reading/writing with 3-tier fallback (Local → Workspace → Global)
    • ImportExportManager: Configuration import/export with preview, conflict detection, and backup
    • ButtonSetManager: Button set CRUD, active set switching, per-scope storage
  4. Providers (src/internal/providers/):
    • CommandTreeProvider: Sidebar tree view data provider
    • ConfigWebviewProvider: React-based configuration UI host

Key Design Patterns

  • Factory Pattern: Static create() methods for dependency construction
  • Adapter Pattern: createVSCodeConfigReader, createVSCodeStatusBarCreator for VS Code API abstraction
  • Observer Pattern: Configuration change listeners trigger UI refresh

Type System

ButtonConfig uses discriminated union for type safety:

type CommandButton = BaseButtonConfig & { command: string; group?: never };
type GroupButton = BaseButtonConfig & { command?: never; group: ButtonConfig[] };
type ButtonConfig = CommandButton | GroupButton;
  • Type guards: isCommandButton(), isGroupButton() for runtime discrimination
  • Mutual exclusivity: command and group cannot coexist (enforced by never type)

Command Execution Flow

Button Click → executeButtonCommand() → determineButtonExecutionType()
  → executeCommand: Direct terminal execution
  → showQuickPick: Show nested command selection with keyboard shortcuts
  → executeAll: Recursively execute all group commands

Multi-Language Keyboard Support

The extension supports 15 keyboard layouts via src/internal/keyboard-layout-converter.ts:

  • Layout converters: Korean, Russian, Arabic, Hebrew, German, Spanish, Czech, Greek, Persian, Belarusian, Ukrainian, Kazakh
  • Advanced converters: Japanese (WanaKana), Chinese (Pinyin), Hindi (Sanscript)
  • Shortcuts match using findMatchingShortcut() with variant generation

Configuration Scopes

Three configuration scopes with automatic fallback (Local → Workspace → Global):

  • Local: Project workspace state (personal, Git-excluded, devcontainer-isolated)
  • Workspace: .vscode/settings.json (team collaboration, Git-tracked)
  • Global: User settings (personal commands across all projects)

Select via Configuration UI or quickCommandButtons.configurationTarget setting.

Fallback Logic: When buttons are not found in selected scope, automatically falls back to next scope:

  • Local (empty) → Workspace → Global
  • Workspace (empty) → Global

Storage:

  • Local: workspaceState (SQLite, per-workspace isolation)
  • Workspace/Global: VS Code settings (JSON)

Webview Architecture

React-based configuration UI with:

  • Drag & Drop: @dnd-kit for command reordering
  • UI Components: shadcn/ui + Radix UI primitives
  • VS Code Communication: vscode.postMessage() API for config sync
  • Theming: VS Code theme synchronization via use-dark-mode hook
  • Error Handling: Error boundary for webview stability
  • User Feedback: Toast notification system for configuration feedback
  • Accessibility: ARIA labels and keyboard navigation support
  • Color Picker: Visual color selection for button customization
  • i18n: Multi-language support (English/Korean) with language selector

Testing Strategy

  • Unit tests: All manager/provider classes have .spec.ts files (co-located)
  • Test framework: Vitest with TypeScript support
  • Mocking: VS Code API mocked via adapters layer
  • Coverage: Use test:coverage for reports

File Structure Notes

src/
  extension/                     # VS Code extension entry
    main.ts                      # Entry point (activate/deactivate)
    main.spec.ts                 # Integration tests
  internal/                      # Internal business logic
    managers/                    # Domain-specific managers
      config-manager.ts          # Configuration reading/writing
      status-bar-manager.ts      # Status bar button lifecycle
      terminal-manager.ts        # Terminal creation/execution
      import-export-manager.ts   # Import/export with preview and conflict detection
      button-set-manager.ts      # Button set management and switching
    providers/                   # VS Code providers
      command-tree-provider.ts   # Sidebar tree view
      webview-provider.ts        # React configuration UI host
    utils/                       # Internal utilities
    adapters.ts                  # VS Code API abstraction layer
    command-executor.ts          # Command execution logic
    keyboard-layout-converter.ts # Multi-language keyboard support
    show-all-commands.ts         # Command palette integration
  pkg/                           # Public package exports
    types.ts                     # Shared type definitions
    config-constants.ts          # Configuration constants
  shared/                        # Shared utilities
    constants.ts
    types.ts
  view/src/                      # React configuration UI
    app.tsx                      # Root component
    core/                        # Reusable UI components (shadcn/ui)
    components/                  # Feature-specific components
      error-boundary.tsx         # Error handling wrapper
    context/                     # React context providers
    hooks/                       # Custom hooks
      use-dark-mode.tsx          # VS Code theme synchronization
      use-webview-communication.tsx
    i18n/                        # Internationalization
      locales/                   # Translation files (en.json, ko.json)

Important Constraints

  • No interface keyword: Always use type (per TypeScript guidelines)
  • Arrow functions: Use for standalone functions, regular methods inside classes
  • Type safety: Avoid any type and type assertions
  • Test coverage: Write unit tests for all new business logic
  • Configuration validation: JSON schema in package.json enforces valid button configs

VS Code Extension Specifics

  • Entry point: main field in root package.json points to compiled src/extension/out/extension/main.js
  • Activation: onStartupFinished event (lazy load)
  • Commands: All prefixed with quickCommandButtons.*
  • Views: quickCommandsContainer activity bar, quickCommandsTree view
  • Webview: Hosted in ConfigWebviewProvider with VS Code webview API

Common Pitfalls

  1. Don't forget to refresh UI: Status bar and tree view need explicit refresh() on config changes
  2. Shortcut uniqueness: validateShortcuts() enforces unique shortcuts per group
  3. Recursive groups: Commands support infinite nesting via ButtonConfig.group
  4. Terminal naming: Custom terminalName allows command organization
  5. executeAll flag: Executes all group commands simultaneously (monitoring use case)