extension/docs/SPEC.md

# Technical Specification

## System Overview
The system is a Visual Studio Code (VS Code) extension designed to facilitate project analysis and management. It integrates with external APIs for authentication and data processing, and provides a user interface within VS Code for interaction. The main components include services for analysis, file collection, reminders, and status updates, as well as authentication management and API client functionalities.

## Core Functionality

### Authentication Management
- **`AuthManager` (src/auth/manager.ts)**
  - **Singleton Pattern**: Ensures a single instance is used throughout the application.
  - **Key Methods**:
    - `generateRandomToken`: Generates a random token using `crypto.randomBytes`.
    - `getOrCreateClientId`: Retrieves or creates a client ID stored in VSCode's secrets.
    - `getStoredToken`, `storeToken`, `clearToken`: Manages the authentication token storage.
    - `isAuthenticated`, `getAuthToken`: Checks and retrieves the authentication token.
    - `startPolling`: Polls an external authentication service to check for a valid token.
    - `initiateAuth`: Initiates the authentication process, including generating auth state, opening an external browser for auth, and starting the polling process.
    - `logout`: Clears the stored token and stops any ongoing polling.

### API Client
- **`ApiClient` (src/api/client.ts)**
  - **`makeAuthenticatedRequest`**: Handles making authenticated API requests.
    - **Token Retrieval**: Attempts to get an auth token from `AuthManager`.
    - **Body Stringification and Compression**: Stringifies the request body and compresses it if `shouldGzip` is `true`.
    - **Request Execution**: Makes the API request with appropriate headers and handles errors.
    - **Progress Handling**: Optionally shows a progress indicator during the request.

### Project Analysis
- **`AnalysisService` (src/services/AnalysisService.ts)**
  - **`analyze(details?: string): Promise<void>`**: Core function that triggers the analysis process. It uses `ProjectManager` to handle the project operation and catches any errors to display them in the status bar and VS Code message window.
  - **Integration**: Singleton pattern, integration with `StatusBarService` for status updates, and error handling with detailed logging and user notifications.

### File Collection
- **`FileCollectionService` (src/services/FileCollectionService.ts)**
  - **`collectFiles(): Promise<FileNode[]>`**: Main function to collect files from the workspace, respecting ignore patterns and size limits.
  - **`getDirectorySizeReport(): string`**: Generates a report of directory sizes.
  - **`getTotalSize(): number`**: Returns the total size of collected files.
  - **Integration**: Uses async generators for efficient directory scanning, integrates with `.gitignore` and `.hanzoignore` for custom ignore patterns, and provides detailed logging and summarization of included and ignored files.

### Reminder Service
- **`ReminderService` (src/services/ReminderService.ts)**
  - **`triggerManually(): void`**: Manually triggers the reminder check.
  - **`dispose(): void`**: Cleans up resources and timers.
  - **Core Logic**: Periodic checks for significant changes in the workspace to prompt reanalysis. Uses both Git and file system tracking based on availability.
  - **Integration**: Debounced event handling, cooldown and forced reminder mechanisms, and integration with `StatusBarService` and `AnalysisService` for status updates and reanalysis.

### Status Bar Updates
- **`StatusBarService` (src/services/StatusBarService.ts)**
  - **`setAnalyzing(message: string = 'Analyzing project...'): void`**
  - **`setIdle(): void`**
  - **`setError(message: string = 'Analysis failed'): void`**
  - **`setSuccess(message: string = 'Analysis complete'): void`**
  - **`dispose(): void`**
  - **Integration**: Singleton pattern to manage the VS Code status bar item, with different states for analyzing, idle, error, and success with appropriate tooltips and commands.

### Configuration Management
- **`getConfig` (src/config.ts)**
  - **`getConfig(): Config`**: Retrieves the appropriate configuration based on the environment. It defaults to 'production' if the environment variable `VSCODE_ENV` is not set. This function is critical as it ensures the application uses the correct configuration for its operations, directly impacting its functionality and security.

### Extension Activation
- **`activate` (src/extension.ts)**
  - **Description**: Initializes the extension, registers commands, and sets up the main functionality. It initializes the `AuthManager`, registers immediate commands, and initializes the extension API.
  - **Core Behavior**:
    - Registers commands like `hanzo.openManager`, `hanzo.login`, and others.
    - Initializes the `AuthManager` and stores the extension API for command access.
    - Calls `initializeExtension` to set up services and panel creation.

### Project Management
- **`ProjectManager` (src/extension.ts)**
  - **Description**: Manages project-related operations, including file updates, UI updates, and project analysis.
  - **Core Methods**:
    - `updateProjectFiles`: Writes project specification and IDE-specific rules to files.
    - `updateUI`: Updates the webview panel UI based on the operation status.
    - `showNotification`: Displays notifications in VS Code.
    - `determineProjectType`: Determines whether to analyze or initialize a project.
    - `handleProjectOperation`: Handles the main project operation, including file collection, API calls, and specification refinement.

## Architecture
The system is structured to facilitate seamless interaction between the VS Code extension and external APIs. Data flows from the user’s workspace through the `FileCollectionService`, which gathers and processes files. This data is then sent to the `AnalysisService` for project analysis, utilizing the `ApiClient` for authenticated API requests. The `AuthManager` handles all authentication-related operations, ensuring secure communication with external services. The `StatusBarService` provides real-time feedback to the user within VS Code, while the `ReminderService` ensures that users are prompted to reanalyze their projects when significant changes occur. The `ProjectManager` orchestrates the core project-related operations, integrating all services to provide a cohesive user experience.