# pirc-extension

The [pi](https://github.com/earendil-works/pi) extension of
[PiRC](https://pirc.dev): it puts every interactive pi session on a PiRC
relay, so that you can follow and drive it from a phone or another
client. You need a relay of your own; PiRC's self-hosting guide covers
running one.

This repository holds releases only: the extension built into one file
(`index.js`). Its source is in PiRC's repository.

## Install

pi installs it from this repository with `git` and `npm`. Pin it to a
release:

```sh
pi install git:<this repository's host and path>@vX.Y.Z
```

To upgrade, upgrade your relay first, then install the newer tag the same
way. `pi update` keeps a pinned install where it is. Installing without a
tag follows this repository's default branch, and `pi update --extensions`
then moves it whenever a release is published, possibly ahead of your
relay.

## Enrol

In pi:

```
/pirc enrol wss://<relay-address>:<port>
```

The footer reads "pirc: awaiting approval" until the relay's operator
approves the host: on the relay, `pirc-relay pending` lists the hosts
waiting, and `pirc-relay approve <key>` admits one. Compare the key with the
one `/pirc status` shows here: the label is whatever the host claims.

Or, to skip the approval, issue a host token on the relay first
(`pirc-relay add-host --label <name>`) and give it to the command:
`/pirc enrol wss://<relay-address>:<port> <token>`.

`/pirc status` shows the connection, and `/pirc reconnect` reconnects.
The enrolment is saved in `~/.config/pirc/host.json` (or the file
`PIRC_CONFIG` names), with the host's key beside it in `host.key`; every pi
process on the host uses the same key. `PIRC_RELAY` overrides the relay
URL, and `PIRC_TOKEN` supplies a registration token, so a host can be
enrolled without the command; a relay URL without a token asks for approval.

If the relay's certificate is self-signed or from a private CA, set
`NODE_EXTRA_CA_CERTS` to the CA's PEM file in the environment pi starts in.

## Where pi runs

Clients name a session by the terminal it runs in. In tmux, that is the
tmux session and window (found through `$TMUX_PANE`); in
[herdr](https://herdr.dev), the workspace and tab (through its socket).
The names are checked again whenever pi does something: a prompt, a turn
starting or ending, a client's request. So a window renamed while pi sits
idle shows its new name after pi's next turn.

For any other terminal, or to name sessions your own way, another pi
extension can say where pi runs:

```ts
pi.events.emit("pirc:place", { kind: "zellij", group: "work", window: "api" });
pi.events.emit("pirc:place", { display: "deploys" }); // shown as it is
pi.events.emit("pirc:place", {});   // show nothing
pi.events.emit("pirc:place", null); // back to PiRC's own detection
```

Fields: `kind`, `group` (a tmux session, a workspace), `groupNumber`,
`window` (a window, a tab), `windowNumber`, `pane` and `display`, each
optional; names are cut to 128 bytes. A place given this way stands until
the next one, so the extension can update it whenever it likes.

## Licence

MIT; see `LICENSE`. The bundle includes third-party code, listed in
`NOTICE`, under the licences in `third_party/`.