## Theia Project Information

This section contains informations specific about the Theia Project and code base, which the user is currenty working on.

### Architecture overview

Theia has a modular architecture and consists of so-called "Theia extensions", which are technically node packages.
Most features and generally the source code can be found under "/packages/" which hosts a list of Theia extensions for different sorts of features.
Theia applications can be used in the browser or (via Electron) on the desktop, but generally have a front end (browser application) and a backend part (node application).
Therefore, extensions can contribute to the front end and the backend. This is reflected in the folder structure of extensions:
- src/browser: Frontend part of an extensions
- src/node: Backend part of an extension.
- src/common: Common/shared components, interfaces and protocol information for front end back end communication

Theia uses dependency injection (via inversify) to wired components. If a class is contributed via dependency injection it needs to be bound in the corresponding frontend or
backend module (which usually already exists in existing packages)

#### Widgets

Widgets are views that are visible in the workbench of a Theia-based application.

#### Commands

Commands in Theia are actions that can be executed by users and programmatically. They are registered through the `CommandRegistry` and can be triggered via menus, 
keybindings, or other UI elements such as toolbar items.

Commands are contributed via `CommandContribution`, see for example: packages/ai-chat-ui/src/browser/chat-view-widget-toolbar-contribution.tsx

#### Toolbars

Toolbars in Theia are UI components that provide quick access to commonly used commands. They can be added to various parts of the workbench including the main toolbar, 
 and custom widget toolbars.

Toolbars are typically contributed through:
- `TabBarToolbarContribution`: For adding toolbar items to tab bars
- `ToolbarContribution`: For contributing to main application toolbars
ToolbarContributions are located in separate files.
Browse the following file for an example: packages/ai-chat-ui/src/browser/chat-view-widget-toolbar-contribution.tsx

### Coding Guidelines

- Trailing white spaces and empty lines with white spaces are forbidden
- Use constants for values that never get reassigned
- The use of `null` is forbidden. Use `undefined` instead for representing absent or uninitialized values.
- Use single quotes (`'`) for string literals instead of double quotes (`"`).
- Use Theia's Event/Emitter/Disposable for handling event listener patterns

### Test File References

When writing new tests, refer to the following files to see example tests and ensure consistency in style and methodology within the project:

- **Backend Test Example**: `packages/core/src/common/content-replacer.spec.ts`
- **Frontend Test Example**: `packages/ai-code-completion/src/browser/code-completion-postprocessor.spec.ts`

Tests are located in the same directory as the components under test.

### Compile and Test

If you want to compile something, run the linter or tests, prefer to execute them for changed packages first, as they will run faster. Only build the full project once you are
done for a final validation.

### Preferences

Theia uses a preferences system for user/workspace settings. To add new preferences:

1. Define a `PreferenceSchema` with property definitions (type, default, description)
2. Create a `PreferenceContribution` symbol and bind it
3. Use `PreferenceProxy` for type-safe access to preference values

**Example:** `packages/workspace/src/common/workspace-trust-preferences.ts`

### Plugin API Extensions

To extend the plugin API (VS Code compatible API):

1. **Type definitions:** Add to `packages/plugin/src/theia.d.ts`
2. **Plugin-side implementation:** `packages/plugin-ext/src/plugin/` (e.g., `workspace.ts`)
3. **Main-side implementation:** `packages/plugin-ext/src/main/browser/` (e.g., `workspace-main.ts`)
4. **RPC protocol:** Define in `packages/plugin-ext/src/common/plugin-api-rpc.ts`
5. **Expose to plugins:** `packages/plugin-ext/src/plugin/plugin-context.ts`

Events flow: Main side service → `workspace-main.ts` → RPC → `workspace.ts` → plugin context

#### Proposed APIs

For APIs that are not yet stable, Theia follows VS Code's proposed API pattern:

1. **Define proposed types:** Create `packages/plugin/src/theia.proposed.<feature>.d.ts`
2. **Enable via package.json:** Extensions must declare `enabledApiProposals` in their package.json
3. **Implementation:** Same as stable APIs, but types come from the proposed file

Note: Some VS Code APIs that were previously "proposed" are now stable (e.g., workspace trust). Check VS Code's current API status before creating proposed API files.

### Styling

Theia permits extensive color theming and makes extensive use of CSS variables. Styles are typically located either in an `index.css` file for an entire package or in a
module-level CSS file.

- **Color variable contribution example**: `packages/core/src/browser/common-frontend-contribution.ts`
- **Package-level CSS example**: `packages/ai-ide/src/browser/style/index.css`
- **Module-specific CSS example**: `packages/core/src/browser/style/tabs.css`

### FileService and Filesystem Access (Browser Mode)

The `FileService` in browser mode communicates with the backend via RPC and has **restricted filesystem access**:

- **Accessible paths:** Files within the current workspace directory or the Theia user config directory (e.g., `~/.theia/`)
- **Inaccessible paths:** Arbitrary filesystem paths outside these boundaries (e.g., `/tmp/`, `/etc/`)

When implementing browser-side services that need to read files from user-configured directories:
1. Use `FileService` from `@theia/filesystem/lib/browser/file-service`
2. Convert paths to URIs using `URI.fromFilePath(path)`
3. Expect `fileService.exists()` to return `false` for paths outside allowed boundaries
4. Document that users should configure paths within their workspace or config directory

**Reference implementation:** `packages/ai-core/src/browser/skill-service.ts` and `packages/ai-core/src/browser/frontend-prompt-customization-service.ts`
