# TrapOS

A small in-game operating system for ComputerCraft / CC:Tweaked, built around a single-threaded event loop and a routed networking layer.

## Installation

Install `ccpm` first. This is the only step that needs `wget` with a URL:
```
wget run https://raw.githubusercontent.com/guillaumearm/cc-libs/master/install-ccpm.lua
```

Then sync the default registry (`guillaumearm/cc-libs`) and install TrapOS:
```
ccpm update
ccpm install trapos
```

Install individual packages instead if you want to cherry-pick:
```
> ccpm install trapos-net
> ccpm install trapos-ui
```

Install `ccpm` from the beta branch (one-time opt-in, asks for confirmation):
```
wget run https://raw.githubusercontent.com/guillaumearm/cc-libs/next/install-ccpm.lua --beta
```

Once `ccpm` is installed from beta, the default registry tracks `next`; `ccpm update` and `ccpm upgrade` keep using that branch.

After install, every boot shows a colored MOTD with the installed version and branch (lime for stable, orange + `[BETA]` for beta).

## Packages

TrapOS is split into packages, each described by a `packages/<name>/ccpm.json`:

- `trapos-core`: the package manager (`ccpm`), event loop, `upgrade`, `events`.
- `trapos-test`: the test framework (`libtest`) and suite runner (`runtest`).
- `trapos-boot`: the startup MOTD and autostart server launcher.
- `trapos-net`: routed modem networking (`net`, `router`, `ping`, `ping-server`).
- `trapos-ui`: the terminal UI toolkit (`libtui`, `tuidemo`).
- `trapos-ai`: the AI client for `opencode serve`.
- `trapos`: full TrapOS meta-package (`trapos-boot`, `trapos-net`, `trapos-ui`, `trapos-test`, and `trapos-ai` during beta).

The `trapos` meta-package is the user-facing full install. Package descriptors list
files and autostart servers; installed state is tracked under `/trapos`.

## ccpm

`ccpm` is the TrapOS package manager. `install-ccpm.lua` installs it by installing
the required `trapos-core` package and configures the default registry
(`guillaumearm/cc-libs`).

```
ccpm install <package>     ccpm reinstall <package>   ccpm uninstall <package>
ccpm update                ccpm upgrade
ccpm ls                    ccpm available [term]      ccpm search [term]
ccpm info <package>
ccpm registry ls           ccpm registry add <name> [--branch <b>] [--type github|http]
ccpm registry rm <name>
```

`ccpm update` fetches registry package indexes into `/trapos/ccpm.cache.json`.
`ccpm available` lists cached packages and marks installed packages as up-to-date or
updatable. `ccpm upgrade` upgrades installed packages based on that cache.

Registries default to GitHub (`owner/repo`); `http`/`https` base URLs are also
supported. State lives in `/trapos/ccpm.json` (registries),
`/trapos/ccpm.lock.json` (installed packages), and `/trapos/ccpm.cache.json`
(available packages). See [ADR-0010](docs/adrs/adr-0010-ccpm-package-manager.md).

## APIs
- `/apis/eventloop`: a simple event loop API.
- `/apis/net`: an API to simplify sending and receiving routed messages, based on the `eventloop` library.

## Servers
Servers listed in `manifest.autostart` are launched at boot by `startup/servers.lua`.

- `/servers/ping-server`: allows a machine to respond to a `ping` command.

## Programs
- `router`: routes messages. You need to set up a router to use all `apis/net`-based programs and libraries.
- `ping`: pings machines using `apis/net`.
- `events`: emits and logs computer events.
- `upgrade`: alias for `ccpm upgrade`.

## Development
See [DEVELOPMENT.md](./DEVELOPMENT.md) for local development installation.