> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Files Channel

> File system operations and real-time watching

## Overview

The `files` channel provides file system operations and real-time file change notifications. Operations use a request-response pattern with request IDs. File watcher events are pushed from the server without a request ID.

| Constraint      | Value   |
| --------------- | ------- |
| Max file size   | 100 MB  |
| Binary encoding | Base64  |
| Path traversal  | Blocked |

### Ignored Paths

The file watcher ignores changes in these directories:

`node_modules`, `.git`, `.next`, `dist`, `build`, `__pycache__`

## File Operations

All operations are sent as client-to-server messages with a `requestId`. The server responds with a message of the same `type` and `requestId`.

### `list`

List the contents of a directory.

```json theme={null}
{
  "channel": "files",
  "type": "list",
  "requestId": "req-1",
  "path": "/src"
}
```

Response:

```json theme={null}
{
  "channel": "files",
  "type": "list",
  "requestId": "req-1",
  "data": [
    { "name": "index.ts", "type": "file", "size": 1420, "modified": "2025-02-20T10:30:00Z" },
    { "name": "utils", "type": "directory", "size": 0, "modified": "2025-02-19T08:15:00Z" }
  ]
}
```

| Field      | Type    | Description                       |
| ---------- | ------- | --------------------------------- |
| `name`     | string  | File or directory name            |
| `type`     | string  | `"file"` or `"directory"`         |
| `size`     | integer | Size in bytes (0 for directories) |
| `modified` | string  | ISO 8601 last modified timestamp  |

### `read`

Read the contents of a file. Text files return UTF-8 content. Binary files return Base64-encoded content.

```json theme={null}
{
  "channel": "files",
  "type": "read",
  "requestId": "req-2",
  "path": "/src/index.ts"
}
```

Response:

```json theme={null}
{
  "channel": "files",
  "type": "read",
  "requestId": "req-2",
  "data": {
    "content": "import express from 'express';\n...",
    "encoding": "utf-8"
  }
}
```

| Field      | Type   | Description                                           |
| ---------- | ------ | ----------------------------------------------------- |
| `content`  | string | File content (raw text or Base64)                     |
| `encoding` | string | `"utf-8"` for text files, `"base64"` for binary files |

### `write`

Write content to a file. Creates the file if it does not exist. Creates parent directories as needed.

```json theme={null}
{
  "channel": "files",
  "type": "write",
  "requestId": "req-3",
  "path": "/src/config.ts",
  "content": "export const PORT = 3000;\n",
  "encoding": "utf-8"
}
```

| Field      | Type   | Required | Description                                  |
| ---------- | ------ | -------- | -------------------------------------------- |
| `path`     | string | Yes      | File path to write                           |
| `content`  | string | Yes      | File content                                 |
| `encoding` | string | No       | `"utf-8"` (default) or `"base64"` for binary |

### `mkdir`

Create a directory. Creates parent directories as needed.

```json theme={null}
{
  "channel": "files",
  "type": "mkdir",
  "requestId": "req-4",
  "path": "/src/components"
}
```

### `delete`

Delete a file or directory.

```json theme={null}
{
  "channel": "files",
  "type": "delete",
  "requestId": "req-5",
  "path": "/src/old-file.ts"
}
```

### `rename`

Rename or move a file or directory.

```json theme={null}
{
  "channel": "files",
  "type": "rename",
  "requestId": "req-6",
  "oldPath": "/src/utils.ts",
  "newPath": "/src/helpers.ts"
}
```

| Field     | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `oldPath` | string | Yes      | Current path |
| `newPath` | string | Yes      | New path     |

### `stat`

Get metadata for a file or directory.

```json theme={null}
{
  "channel": "files",
  "type": "stat",
  "requestId": "req-7",
  "path": "/src/index.ts"
}
```

Response:

```json theme={null}
{
  "channel": "files",
  "type": "stat",
  "requestId": "req-7",
  "data": {
    "name": "index.ts",
    "type": "file",
    "size": 1420,
    "modified": "2025-02-20T10:30:00Z",
    "permissions": "rw-r--r--"
  }
}
```

| Field         | Type    | Description                      |
| ------------- | ------- | -------------------------------- |
| `name`        | string  | File or directory name           |
| `type`        | string  | `"file"` or `"directory"`        |
| `size`        | integer | Size in bytes                    |
| `modified`    | string  | ISO 8601 last modified timestamp |
| `permissions` | string  | Unix permission string           |

## Watcher Events

The server pushes file change events in real time. These messages have no `requestId`.

### `change`

A file or directory was created, modified, or deleted.

```json theme={null}
{
  "channel": "files",
  "type": "change",
  "event": "modify",
  "path": "/src/index.ts",
  "fileType": "file"
}
```

| Field      | Type   | Description                           |
| ---------- | ------ | ------------------------------------- |
| `event`    | string | `"create"`, `"modify"`, or `"delete"` |
| `path`     | string | Affected file path                    |
| `fileType` | string | `"file"` or `"directory"`             |

## Error Responses

If an operation fails, the server responds with the same `requestId` and an `error` field:

```json theme={null}
{
  "channel": "files",
  "type": "read",
  "requestId": "req-2",
  "error": "File not found: /src/missing.ts"
}
```

## Path Security

All paths are resolved relative to the workspace root. Directory traversal attempts (e.g., `../../etc/passwd`) are rejected with an error. Symlinks that resolve outside the workspace root are also blocked.