Skip to content

Commit 7f00577

Browse files
22149620832214962083
committed
docs: add readme for each module
1 parent fcfb4cf commit 7f00577

File tree

24 files changed

+4602
-0
lines changed

24 files changed

+4602
-0
lines changed

‎.cursor-rules/.generate-readme-cursorrules‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Module README Generator for Aide VSCode Extension
2+
3+
## Task Description
4+
5+
You're tasked with creating comprehensive README files for the modules of the Aide VSCode extension, an AI-powered code assistance tool. Each README should explain the module's purpose, functionality, and integration with the larger system to help developers (both current and future) understand the codebase.
6+
7+
## Context
8+
9+
The Aide codebase is complex with multiple interconnected modules. Each module serves a specific purpose within the extension's architecture. These READMEs will serve as documentation to help developers navigate and understand the codebase efficiently.
10+
11+
## Input Format
12+
13+
I will provide you with:
14+
15+
- The path to a specific module folder (e.g., `/src/extension/ai`)
16+
- A directory listing showing all files and subdirectories within the module
17+
- Access to key files through file attachments or code snippets
18+
19+
## Output Requirements
20+
21+
Create a comprehensive README.md file with the following sections:
22+
23+
1. **Module Overview**: Write 2-3 concise sentences describing the module's primary purpose and importance within the system.
24+
25+
2. **Core Functionality**: Create a bullet list (4-6 items) of the main capabilities this module provides. Format each bullet as "**Name**: Description".
26+
27+
3. **Key Components**: Organize components by category (e.g., by subdirectory or functional area). For each key file/class, include:
28+
- File name with extension
29+
- Brief description of its purpose
30+
- Key functionality it provides
31+
4. **Dependencies**: List both internal module dependencies and external libraries with a brief explanation of how they're used.
32+
33+
5. **Usage Examples**: Provide 1-2 code examples showing how the module is typically used within the system. Use realistic variable names and include comments.
34+
35+
6. **Architecture Notes**: Explain the design patterns, data flow, and architectural decisions. Include a mermaid diagram when the module has complex interactions.
36+
37+
## Style Guidelines
38+
39+
- Use clear, technically precise language appropriate for experienced developers
40+
- Focus on high-level functionality rather than implementation details
41+
- Maintain a neutral, informative tone
42+
- Structure information hierarchically with clear headings and subheadings
43+
- Use bold formatting for emphasis on key terms
44+
- Keep the entire README under 1000 words for quick reference
45+
- Include a mermaid diagram for modules with complex interactions or data flows
46+
47+
## Example Structure
48+
49+
````markdown
50+
# Module Name
51+
52+
## Module Overview
53+
54+
[2-3 sentences describing primary purpose]
55+
56+
## Core Functionality
57+
58+
- **Feature One**: Description of this feature
59+
- **Feature Two**: Description of this feature
60+
[...]
61+
62+
## Key Components
63+
64+
### Category/Directory One
65+
66+
- **file1.ts**: Description and purpose
67+
- **file2.ts**: Description and purpose
68+
69+
### Category/Directory Two
70+
71+
[...]
72+
73+
## Dependencies
74+
75+
[List of internal and external dependencies with explanations]
76+
77+
## Usage Examples
78+
79+
```typescript
80+
// Example code showing how to use this module
81+
```
82+
````
83+
84+
## Architecture Notes
85+
86+
[Description of design patterns and architectural decisions]
87+
88+
```mermaid
89+
[Diagram showing component relationships]
90+
```
91+
92+
```
93+
94+
This prompt has been structured to follow Anthropic's best practices with clear sections, specific instructions, and example formatting. It should help produce high-quality, consistent README files that match the style of the ones you've already created.
95+
```

‎.i18n-cursorrules‎ renamed to ‎.cursor-rules/.update-i18n-cursorrules‎

File renamed without changes.

‎src/extension/actions/README.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Actions Module
2+
3+
## Module Overview
4+
5+
The Actions module is a critical part of the Aide VSCode extension that defines and implements a collection of server-side actions. These actions serve as the API layer that enables communication between the extension's user interface and its core functionality, providing a structured way to perform operations on various aspects of the system.
6+
7+
## Core Functionality
8+
9+
- **Action Collection System**: Organizes related actions into collection classes that extend `ServerActionCollection`
10+
- **Command Execution**: Provides methods to execute commands with proper context and error handling
11+
- **Resource Management**: Handles file operations, chat sessions, agent interactions, and settings management
12+
- **State Synchronization**: Ensures consistent state between UI and backend components
13+
- **Extension Feature Control**: Enables or disables extension features based on user configuration
14+
- **Integration Point**: Acts as the bridge between UI components and backend services
15+
- **Cross-Process Communication**: Facilitates communication between the extension backend (server) and UI (client) processes
16+
17+
## Key Components
18+
19+
### Collection Classes
20+
21+
Each file in this module exports a collection class that extends `ServerActionCollection` and provides a set of related actions:
22+
23+
- **AgentActionsCollection** (`agent-actions.ts`): Manages AI agents throughout their lifecycle, including starting, stopping, accepting, and rejecting agents. Provides methods for controlling multiple agent sessions and handling agent interactions.
24+
25+
- **AIModelActionsCollection** (`ai-model-actions.ts`): Manages AI models within the system, allowing for retrieval, creation, updating, and testing of models. Handles model feature detection and provides model settings for different extension features.
26+
27+
- **AIProviderActionsCollection** (`ai-provider-actions.ts`): Manages AI service providers, supporting operations like adding, updating, and removing providers. Ensures appropriate default provider and model selection.
28+
29+
- **ApplyActionsCollection** (`apply-actions.ts`): Manages code edit tasks, handling the creation, validation, acceptance, and rejection of code changes. Provides functionality for diffing, applying changes, and tracking edit history.
30+
31+
- **ChatActionsCollection** (`chat-actions.ts`): Handles chat functionality, including streaming conversations and prompt generation. Provides methods to process and respond to chat inputs.
32+
33+
- **ChatSessionActionsCollection** (`chat-session-actions.ts`): Manages chat sessions and their states, supporting creation, updating, and deleting of sessions. Handles session persistence and retrieval.
34+
35+
- **CodebaseActionsCollection** (`codebase-actions.ts`): Provides functionality for indexing and searching the codebase, including reindexing operations and status reporting. Essential for code-aware AI features.
36+
37+
- **DocActionsCollection** (`doc-actions.ts`): Handles documentation-related actions, including retrieval, generation, and management of documentation for various code elements.
38+
39+
- **FileActionsCollection** (`file-actions.ts`): Provides comprehensive file system operations, including reading, writing, traversing, and manipulating files and directories. Supports various encoding formats and filesystem schemes.
40+
41+
- **GitActionsCollection** (`git-actions.ts`): Manages Git operations, providing functionality for accessing Git repositories, branches, commits, and status information.
42+
43+
- **GitProjectActionsCollection** (`git-project-actions.ts`): Extends Git functionality with project-specific operations, supporting project initialization, cloning, and management.
44+
45+
- **InternalConfigActionsCollection** (`internal-config-actions.ts`): Handles internal configuration settings that control various aspects of the extension's behavior.
46+
47+
- **McpActionsCollection** (`mcp-actions.ts`): Manages the "Mission Control Panel" functionality, providing access to system monitoring, diagnostics, and control operations.
48+
49+
- **MentionActionsCollection** (`mention-actions.ts`): Implements the @-mentions functionality, allowing references to files, code elements, and other resources within chat contexts.
50+
51+
- **ProjectActionsCollection** (`project-actions.ts`): Manages project metadata, settings, and operations, providing functionality for working with different project types.
52+
53+
- **PromptSnippetActionsCollection** (`prompt-snippet-actions.ts`): Manages reusable prompt snippets, allowing users to create, edit, and use predefined prompts in chat interactions.
54+
55+
- **SettingsActionsCollection** (`settings-actions.ts`): Handles extension settings, providing methods to get, set, and validate user configuration options.
56+
57+
- **SystemActionsCollection** (`system-actions.ts`): Provides system-level operations, including extension status, version checking, and system information retrieval.
58+
59+
- **TerminalActionsCollection** (`terminal-actions.ts`): Manages terminal operations, allowing for command execution and terminal session management within the extension.
60+
61+
- **WebVMActionsCollection** (`webvm-actions.ts`): Provides functionality for the WebVM environment, supporting preview of web projects, file management, and VM lifecycle operations.
62+
63+
- **WorkspaceCheckpointActionsCollection** (`workspace-checkpoint-actions.ts`): Manages workspace checkpoint functionality, allowing users to create, restore, and manage snapshots of their workspace state.
64+
65+
### Index File
66+
67+
The `index.ts` file exports all action collections as a unified array, making them available throughout the extension:
68+
69+
```typescript
70+
export const serverActionCollections = [
71+
ChatActionsCollection,
72+
CodebaseActionsCollection,
73+
FileActionsCollection
74+
// ... other collections
75+
] as const satisfies (typeof ServerActionCollection)[]
76+
```
77+
78+
## Action System Architecture
79+
80+
The actions system is built on a client-server architecture that enables seamless communication between the extension backend (VSCode extension process) and frontend (WebView UI):
81+
82+
### Server-Side (Extension Backend)
83+
84+
Server actions are defined in this module and each extends the `ServerActionCollection` class. These collections are registered with the `ActionRegister` and made available through a proxy system.
85+
86+
**Server Action Structure:**
87+
88+
- Each collection has a unique `categoryName` property
89+
- Actions are methods of the collection class
90+
- Actions receive an `ActionContext` object that includes parameters and an abort controller
91+
- Server actions have access to the `registerManager` and `commandManager` for integration with other extension components
92+
93+
### Client-Side (WebView UI)
94+
95+
Client actions, defined in the webview layer, extend the `ClientActionCollection` class and provide UI-specific functionality like refreshing views or updating UI state.
96+
97+
### Cross-Process Communication
98+
99+
The action system uses a proxy mechanism to allow:
100+
101+
1. Server code to call client actions
102+
2. Client code to call server actions
103+
104+
This is handled through WebSocket communication, with action calls serialized and sent between processes.
105+
106+
## Dependencies
107+
108+
This module interacts with several other modules within the extension:
109+
110+
- **Register System**: Uses various registers to access functionality providers
111+
- **Command System**: Executes commands in response to actions
112+
- **Entity Models**: Operates on entities like `Conversation`, `Agent`, and `ChatContext`
113+
- **File System**: Interfaces with VSCode's file system API through a custom VFS layer
114+
- **AI Providers**: Communicates with AI models and providers for agent functionality
115+
116+
External dependencies include:
117+
118+
- VSCode API: For editor integration
119+
- immer: For immutable state updates
120+
- i18next: For internationalization
121+
- socket.io: For WebSocket communication between server and client
122+
123+
## Usage Examples
124+
125+
### Server-Side: Executing an Action (Extension)
126+
127+
In the extension (server) code, actions are executed using the `runAction` function from the `state` module:
128+
129+
```typescript
130+
// Example of executing a server action from server code
131+
import { runAction } from '@extension/state'
132+
133+
// Execute a server action
134+
const fileContent = await runAction().server.file.readFile({
135+
actionParams: {
136+
schemeUri: 'workspace:/path/to/file.ts'
137+
}
138+
})
139+
140+
// Execute a client action from server code
141+
await runAction(registerManager).client.chat.refreshCurrentChatSession({
142+
actionParams: {},
143+
webviewId // Specify which WebView should handle the action
144+
})
145+
```
146+
147+
### Client-Side: Executing an Action (WebView)
148+
149+
In the WebView (client) code, actions are executed using the actions API:
150+
151+
```typescript
152+
// Example of executing a server action from client code
153+
import { signalToController } from '@shared/utils/common'
154+
import { api } from '@webview/network/actions-api'
155+
156+
// React Query example for calling a server action
157+
const { data } = useQuery({
158+
queryKey: ['read-file', schemeUri],
159+
queryFn: ({ signal }) =>
160+
api.actions().server.file.readFile({
161+
actionParams: { schemeUri },
162+
abortController: signalToController(signal)
163+
})
164+
})
165+
166+
// Direct call example
167+
const handleClick = async () => {
168+
await api.actions().server.file.writeFile({
169+
actionParams: {
170+
schemeUri: 'workspace:/path/to/file.ts',
171+
data: 'Updated content'
172+
}
173+
})
174+
}
175+
```
176+
177+
## Architecture Notes
178+
179+
The Actions module follows a consistent pattern across all collection classes:
180+
181+
```mermaid
182+
graph TD
183+
WebView[WebView UI] <--> Socket[WebSocket] <--> Extension[Extension Process]
184+
WebView --> ClientActions[Client Actions] --> Socket
185+
Extension --> ServerActions[Server Actions] --> Socket
186+
ServerActions --> Registers[Registers]
187+
ServerActions --> Services[Services]
188+
ServerActions --> FileSystem[File System]
189+
ServerActions --> AIProviders[AI Providers]
190+
```
191+
192+
Each action follows a similar structure:
193+
194+
1. Receives an `ActionContext` with parameters and an abort controller
195+
2. Processes the request, potentially utilizing registers, services, or other components
196+
3. Returns the result or updates the state
197+
198+
The action system uses a category-based naming convention (e.g., `file.readFile`, `chat.streamChat`), making it easy to organize and discover functionality. This architecture enables a clean separation between UI logic and core functionality, allowing for better testability and maintenance.
199+
200+
The bidirectional nature of the action system allows for flexible communication patterns:
201+
202+
- Server can call client: For UI updates and notifications
203+
- Client can call server: For data operations and system functionality
204+
- Both support streaming responses: For real-time updates and progress reporting

0 commit comments

Comments
 (0)