paperos 0.2.0

A programmable editor built on the Runact actor runtime
Documentation
# Extension Management System

## Overview

Extensions are the fundamental building blocks of PaperOS. The editor, terminal, Git integration, LSP, search, AI, and other capabilities are all composable extensions running on a small stable core. Users modify the environment itself by adding, removing, or replacing extensions.

An extension may provide:

```text
Commands
Events
Actors
Views
Panels
Menus
Keybindings
Configuration
Services
Resources
Tasks
Capabilities
```

Example:

```text
Git Extension
 ├── git.status
 ├── git.commit
 ├── git.push
 ├── GitActor
 ├── SourceControlView
 └── Git configuration
```

## Extension Layout

Extensions reside in `~/.config/paperos/extensions/<name>/`:

```
extensions/
├── my-greeter/        — extension directory
│   ├── manifest.json  — metadata (name, version, dependencies)
│   └── init.lua       — extension code (returns a Lua table)
├── tree-sitter/
│   ├── manifest.json
│   └── init.lua
```

## Extension Capabilities

Every extension declares the capabilities it requires. The runtime grants or denies them at load time based on user or policy configuration.

Potential capability classes:

```text
filesystem.read
filesystem.write
network
process.spawn
shell
clipboard
workspace
ui
secrets
```

An extension should declare required capabilities in its manifest. The user or runtime decides whether they are granted. An extension that needs `filesystem.write` but is not granted that capability should degrade gracefully, not crash.

## Extension Lifecycle

Every extension follows a lifecycle:

```text
Discovered
   ↓
Loaded
   ↓
Initialized
   ↓
Running
   ↓
Stopping
   ↓
Stopped
```

An extension may also be:

```text
Reloaded
Disabled
Upgraded
Failed
```

The extension manager controls this lifecycle. A failed extension should be isolated — it should not crash the rest of the environment. Runact supervision can restart failed components.

## Extension Isolation

An extension should not automatically have unrestricted access. Instead, it receives explicit capabilities at load time.

```
Extension
    │
    ▼
Capabilities
```

This enables controlled extension permissions. Extensions communicate through stable APIs rather than directly manipulating internal Rust structures. Each extension runs in its own Lua state with isolated global variables.

## Manifest Format

Each extension declares a `manifest.json`:

```json
{
  "name": "syntax-highlight",
  "version": "1.0.0",
  "description": "Tree-sitter based syntax highlighting",
  "author": "User Name",
  "depends": ["buffer-api>=0.2", "config>=1.0.0"],
  "provides": ["syntax-highlighting"],
  "capabilities": ["filesystem.read", "workspace.read"]
}
```

Fields:

| Field         | Type     | Description                                        |
|---------------|----------|----------------------------------------------------|
| `name`        | string   | Unique extension identifier                        |
| `version`     | string   | SemVer-style version string                        |
| `description` | string   | Human-readable summary                             |
| `author`      | string   | Extension author                                   |
| `depends`     | string[] | List of required extensions with version constraints |
| `provides`    | string[] | List of capabilities other extensions can depend on |
| `capabilities`| string[] | List of runtime capabilities required by this extension |

## Version Constraints

Dependencies support these constraints:

| Syntax              | Meaning                                    |
|---------------------|--------------------------------------------|
| `"name"`            | Any version                                |
| `"name>=X.Y.Z"`     | Minimum version (inclusive)                |
| `"name==X.Y.Z"`     | Exact version                              |
| `"name>=X.Y,<X+1.0"`| Range — at least X.Y, less than X+1.0     |
| `"name>1.0,<=2.0"`  | Greater than 1.0 and at most 2.0           |

Example: `"buffer-api>=0.2,<1.0"` — any version from 0.2 up to (but not
including) 1.0.

## Dependency Resolution

### Algorithm

1. **Parse all available extensions** from `extensions/` directory.
2. **Build dependency graph** — each node has its version constraints.
3. **Select compatible versions** — find the highest version satisfying all
   constraints for each dependency.
4. **Topological sort** — load dependencies before dependents.
5. **Handle conflicts** — if no version satisfies all constraints, use the
   highest requested version and warn.

### Conflict Example

Extensions requesting `buffer-api`:

- `syntax-highlight` requires `buffer-api>=0.2`
- `debugger` requires `buffer-api>=0.3`
- `legacy-plugin` requires `buffer-api<0.3`

**Resolution:**
- Load `buffer-api` version `0.3` (highest satisfying first two)
- Load `syntax-highlight` and `debugger`
- Skip `legacy-plugin` with warning:
  `"legacy-plugin skipped: requires buffer-api<0.3 but 0.3 installed"`

### Circular Dependencies

Circular dependencies (A → B → A) produce an error:

```
Error: Circular dependency detected: A -> B -> A
```

## Load Order

Extensions load in **topological order**: dependencies first, then dependents.
This ensures that when an extension initializes, all its dependencies are
already running.

## Side-by-Side Versions (Future)

If the ecosystem grows to need conflicting versions simultaneously, extensions
can be namespaced:

```
extensions/
├── buffer-api-v0.2/
├── buffer-api-v0.3/
└── syntax-highlight/   # depends on exact "buffer-api-v0.2"
```

Each version runs in its own Lua state with isolated `BufferActor` instances.
This is a future capability — currently only single-version resolution is
supported.

## CLI Interface

Commands are available via `paperos ext` or `:ext` in command mode:

```bash
paperos ext list              # Show all extensions (enabled/disabled)
paperos ext list --json       # JSON output for tooling
paperos ext enable <name>     # Enable an extension
paperos ext disable <name>    # Disable an extension
paperos ext install <url>     # Download and install from a git URL
paperos ext info <name>       # Show manifest and load status
paperos ext reload            # Reload extensions without restart
```

## Runtime API

Extensions (and `init.lua`) interact via the `paper` global. See
`docs/customization.md` for the full user-facing reference. Summary:

```lua
paper.config.set(key, value)          -- typed settings (strings)
paper.config.get(key)
paper.theme.set(name, color)          -- theme.cursor-normal, border, ...
paper.commands.register(name, fn, desc) -- real editor commands (M-x visible)
paper.events.on(event, fn)            -- Lua handler for editor events
paper.events.publish(event, payload)  -- queued custom event
paper.keys.map(mode, key, command)    -- mode-only keymaps
paper.buffer.content()                -- document text
paper.buffer.set_content(text)
paper.buffer.insert_text(text)
paper.buffer.cursor()                 -- { row, col }
paper.buffer.move_to(row)
paper.cmd("command args")             -- queue any editor command
paper.open(path)                      -- sugar for paper.cmd("open ...")
paper.save()                          -- sugar for paper.cmd("save")
paper.panels.create(name)             -- named panel buffer
paper.panel.write(name, text)         -- write to a panel buffer
paper.extensions.list()               -- active extension names
paper.quit()                          -- request quit
```

Built-in events: `file.saved` (`{path, bytes}`), `buffer.changed`
(`{command, buffer}`). Commands and events are queued and drained by the
event loop — Lua never runs editor logic inline.

## Core Philosophies

All extensions follow two fundamental rules:

### 1. Every Action Is a Command

Extensions register commands via `runtime.register_command()`. User input flows through the command system — the event loop never directly mutates state. Even internal actions (scrolling, mode changes) are commands:

```rust
runtime.register_command("scroll-up", handler);
runtime.register_command("vi-mode", handler);
```

### 2. Every Visible Panel Is a Buffer

All UI state lives in `BufferActor`. Extensions read buffers via accessors and mutate them only by sending `BufferMessage`:

```rust
runtime.send(buffer_id, BufferMessage::InsertChar('a'));
runtime.send(buffer_id, BufferMessage::LoadContent(text));
```

BufferActor fields are **private** — direct field access from outside the actor is a compile-time error. This prevents extensions from bypassing the message protocol.

### Buffer Kinds

There is no buffer-kind concept. Panels are named buffers — the name is a
message-routing key in `PanelRegistry`, not a type.
`PanelRegistry` manages the panel-to-actor mapping by name string. The built-in
names are `"document"`, `"minibuffer"`, `"statusbar"`, `"help"`, and `"filetree"`.
Extensions may register custom panel names.

Buffer behavior is dispatched through the keymap registry (mode-only context)
and command handlers — not through any kind-based dispatch.

## Extension Types (Future)

PaperOS will eventually support three tiers of extensions:

```text
Rust Native Extension
       │
       ├── maximum capability
       └── high performance

WASM Extension
       │
       ├── sandboxed
       └── portable

Lua Extension
       │
       ├── lightweight
       └── highly customizable
```

Start with Lua. Add WASM and Rust native extensions later.