@timqi/pier 0.0.1

package/docs/deploy.md

@@ -0,0 +1,307 @@
+# Running Pier as a service (Linux, systemd)
+
+Pier is one Node process that binds the loopback. Running it in a terminal is
+a complete installation — nothing below is required to *use* Pier. What systemd
+adds is the thing a terminal cannot: scheduled tasks fire and IM channels stay
+connected while nobody is logged in.
+
+That is also why this document is Linux-only. A laptop closes its lid; the
+machine you want always-on is a server, and on that machine systemd is already
+there.
+
+## The short version
+
+```sh
+npm install -g @timqi/pier
+pier service install
+journalctl --user -u pier -e     # the password, printed once
+```
+
+That writes the unit below, enables linger, and starts the service. The rest of
+this page is what it wrote and why — read it before widening the bind, and when
+you want the unit to say something different.
+
+## Prerequisites
+
+- Node 24 or newer (`node:sqlite` is used unflagged).
+- The `sqlite3` CLI, for the off-machine backup and password steps below. Pier
+  itself does not need it.
+- A checkout, built once:
+
+```sh
+git clone git@github.com:timqi/pier.git ~/pier
+cd ~/pier && npm ci && npm run build
+```
+
+The unit below runs the build output, so a deploy is always "update the
+checkout, rebuild, restart" — never "run from source".
+
+## The unit
+
+A **user** unit, not a system one: Pier runs as you, reads your Pi
+configuration, and drives sessions in your own directories. Running it as root
+or as a dedicated system user means an agent that cannot touch the files you
+wanted it to work on.
+
+`~/.config/systemd/user/pier.service` — what `pier service install` generates,
+with your node and your entry point filled in:
+
+```ini
+[Unit]
+Description=Pier — agent workspace
+Documentation=https://github.com/timqi/pier
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h/pier
+# An absolute path on purpose: systemd starts with a minimal PATH, so a node
+# installed by nvm/fnm/asdf is not on it. `command -v node` gives you this.
+ExecStart=/usr/bin/node dist/main.js
+Environment=NODE_ENV=production
+# Loopback by default. Put a reverse proxy in front before widening this —
+# whoever reaches this port can drive an agent that runs a shell.
+Environment=HOST=127.0.0.1
+Environment=PORT=3141
+# Where the database, the boards and the generated password hash live.
+Environment=PIER_HOME=%h/.pier
+Restart=always
+RestartSec=2
+# The journal is where the first-run password is printed, so keep it readable.
+StandardOutput=journal
+StandardError=journal
+# Otherwise every line is tagged "node"; this makes `journalctl -t pier` work.
+SyslogIdentifier=pier
+
+[Install]
+WantedBy=default.target
+```
+
+Enable it, and tell logind to keep your user manager alive after you log out —
+without lingering, every scheduled task stops when your SSH session ends:
+
+```sh
+loginctl enable-linger "$USER"
+systemctl --user daemon-reload
+systemctl --user enable --now pier
+```
+
+## Memory limits
+
+Worth setting: an agent runs whatever a turn decided to run, so the failure to
+plan for is a build or a test suite eating the machine, not Pier itself
+leaking. A cgroup limit turns "the box OOMs and sshd dies with it" into "the
+heaviest process inside this unit is killed".
+
+User units can do this without root as long as the memory controller is
+delegated to your user manager, which it is by default on current systemd:
+
+```sh
+systemctl show "user@$(id -u).service" -p DelegateControllers
+# DelegateControllers=cpu memory pids   ← memory listed means these work
+```
+
+`~/.config/systemd/user/pier.service.d/limits.conf` — a drop-in, so the unit
+above stays about what Pier is and this file is about what it may consume:
+
+The limit is on the **whole unit**: `node`, every Pi subagent, and every
+command a turn ran, added together — plus the page cache those processes
+touched, which is why the soft ceiling should be the one that bites. So size it
+as a share of the machine, not as "how much should Pier need". Percentages are
+relative to installed physical memory, which also keeps this file portable:
+
+```ini
+[Service]
+# Soft ceiling: past this the kernel reclaims hard and lets the unit crawl
+# instead of killing anything. This is the one that should bite first.
+MemoryHigh=60%
+# Hard ceiling: the kernel OOM-kills *inside this cgroup*. The number exists to
+# protect everything outside it — the OS, sshd, your other services — so what
+# it should leave behind is a few GB for them, not a small share for Pier.
+MemoryMax=75%
+# Swapping an agent is worse than failing it — the machine stops responding
+# long before the limit is reached.
+MemorySwapMax=0
+# A runaway command an agent ran can fork as well as allocate.
+TasksMax=512
+# The unit's own processes are the preferred victims if the *machine* still
+# runs out, e.g. before these limits are tuned. Works with no cgroup limit at
+# all, which makes it the cheapest half of this file.
+OOMScoreAdjust=200
+# A child being OOM-killed must not take the service with it: the turn that
+# ran it fails, Pier keeps serving. (Delegated units default to this; set
+# explicitly because the default depends on system configuration.)
+OOMPolicy=continue
+```
+
+On a dedicated 4–8 GB VPS those percentages land around 2.5–6 GB, which is
+roughly what one agent doing ordinary work needs. On a big shared box, prefer
+absolute values sized to what you are willing to lose to a runaway build —
+`MemoryHigh=8G` / `MemoryMax=12G` on 32 GB, say — because 75% of a large
+machine is no longer a meaningful ceiling.
+
+Pick the numbers by measuring, not by guessing — Pier idles in the hundreds of
+MB, and what varies is what the agent runs:
+
+```sh
+systemctl --user show pier -p MemoryCurrent -p MemoryPeak
+systemd-cgtop --depth=3 "user.slice/user-$(id -u).slice"
+```
+
+A limit that fires during ordinary work is worse than none: the turn dies with
+a signal and the cause is a kernel message nobody reads. Set it to protect the
+machine, then raise it the first time it kills something legitimate.
+
+## Logs
+
+Pier writes to stdout and stderr and to nothing else — no log file, no
+rotation, no log configuration. Under the unit above that *is* the log:
+journald stamps the time, keeps the history and rotates it, which is why
+nothing in Pier reimplements any of that.
+
+```sh
+journalctl --user -u pier -f            # follow
+journalctl --user -u pier -p warning    # only what went wrong
+journalctl --user -u pier --since -1h | grep 'tasks:'   # one area
+```
+
+Every line is `area: message` — `core`, `agent`, `tasks`, `slack`, `telegram`,
+`channels`, `web`, `auth`, `boards`, `client`, `pier` — so an area is a grep
+and a level is a `-p`. The level reaches journald as a syslog priority prefix, which Pier
+emits only when systemd says the output is a journal (`$JOURNAL_STREAM`); run
+in a terminal, the same lines carry a timestamp and a level word instead.
+
+What is logged by default: process start and shutdown, sessions opening,
+conversation → session routing, every turn ending, every task run queued and
+settled, callback and message delivery failures with their retries, adapters
+starting (and failing to start or stop), dropped inbound messages, failed
+logins, and any request that threw. A watch probe that matched nothing is the
+one routine event kept at `debug` — it fires on every interval.
+
+`client:` is the browser's half, posted back by the workbench (`ui/report.ts`)
+and written into this same stream: script errors, unhandled rejections and a
+dead SSE stream, each with the view and the user agent. It comes from signed-in
+tabs only — the route sits behind the password like the rest of `/api`, so
+nobody who cannot already reach Pier can write into this journal. The person sees the
+same sentence in the chat pane, so "I clicked and nothing happened" has a line
+on both ends:
+
+```sh
+journalctl --user -u pier | grep 'client:'
+```
+
+```sh
+systemctl --user set-environment PIER_LOG=debug   # + per-message tracing
+systemctl --user restart pier
+```
+
+`PIER_LOG` takes `debug`, `info` (default), `warn`, `error` or `silent`. Prefer
+turning `debug` on for a session and back off: it logs one line per inbound
+message and per tool call.
+
+## First login
+
+Pier generates a password on an empty database and prints it once, so the
+journal is where you read it:
+
+```sh
+journalctl --user -u pier | grep -A2 'no password'
+```
+
+Only its scrypt hash is stored. If you lose it, drop the row and restart — a
+new password is generated and printed:
+
+```sh
+sqlite3 ~/.pier/db/pier.db 'DELETE FROM auth'
+systemctl --user restart pier
+```
+
+Changing the password invalidates every session cookie: the cookies are signed
+with the stored hash.
+
+## Updating
+
+Manually, which is also exactly what an automated update has to do:
+
+```sh
+cd ~/pier
+git fetch --tags && git checkout v0.2.0   # a tag, not a branch
+npm ci && npm run build
+systemctl --user restart pier
+```
+
+A newer Pier brings its own schema up on the next start: the migrations run in
+one transaction before the port opens, and the version they leave behind is
+stamped in the database. Before touching an existing database it snapshots it
+to `~/.pier/db/pier.db.v<N>.bak` (`N` = the schema it was at), so the step you
+cannot forget is the one you never take. **Upgrades only.** Start an older Pier
+on a database a newer one has migrated and it refuses to run rather than write
+tables it does not understand — the way back down is that `.bak`:
+
+```sh
+systemctl --user stop pier
+cd ~/.pier/db && rm -f pier.db pier.db-wal pier.db-shm && cp pier.db.v1.bak pier.db
+# then check out the Pier that speaks schema 1 again
+```
+
+The three newest snapshots are kept and older ones removed as later upgrades
+supersede them; each is a full copy of the database, so size grows with the
+database, not with the number of releases. They sit next to the database and
+therefore protect against a bad upgrade, not against a lost disk — an
+off-machine copy is still yours to take.
+
+### Can it update itself?
+
+Yes, with one caveat that decides the shape: **the updater must not be a child
+of the service it restarts.** `systemctl --user restart pier` kills everything
+in `pier.service`'s cgroup, so an update script spawned by Pier dies halfway
+through — sometimes after unpacking and before restarting, which is the one
+outcome worse than not updating.
+
+So the update runs as its own unit. `~/.config/systemd/user/pier-update.service`:
+
+```ini
+[Unit]
+Description=Update Pier to the latest tag
+
+[Service]
+Type=oneshot
+WorkingDirectory=%h/pier
+ExecStart=/bin/sh -lc 'git fetch --tags && git checkout "$(git describe --tags --abbrev=0 origin/main)" && npm ci && npm run build'
+ExecStartPost=/bin/sh -lc 'systemctl --user restart pier'
+```
+
+Pier can then trigger an update with a single call that survives its own
+restart, because the work happens in a different cgroup:
+
+```sh
+systemctl --user start pier-update.service
+```
+
+Deliberately **not** a `systemd.timer`. An unattended update is a machine that
+rewrites its own code from the network while holding your API keys, and it
+interrupts whatever session was mid-turn to do it. The intended shape is that
+Pier notices a newer release and says so (not built yet), while starting the
+update stays a decision someone makes. `Restart=always` above is what makes
+that decision cheap — the service comes back on its own.
+
+## Remote access
+
+The unit binds the loopback, and that is the intended posture. To reach it from
+elsewhere, pick a tunnel rather than a wider bind:
+
+- `ssh -L 3141:localhost:3141 server` — nothing to configure, nothing exposed.
+- Tailscale, or Cloudflare Tunnel — no open port, and TLS terminates outside.
+- A reverse proxy (Caddy, nginx) if you want a real hostname. Terminate TLS
+  there and pass `X-Forwarded-For`; Pier's login throttle counts per forwarded
+  client, and its session cookie is marked `Secure` when the proxy reports
+  `X-Forwarded-Proto: https`.
+
+## Backups
+
+Two paths hold everything: `~/.pier/db/pier.db` (tasks, channels, the chat →
+session map, workbench state, settings, the password hash) and
+`~/.pier/boards/`. Copy the database with `sqlite3 ... "VACUUM INTO '…'"`
+rather than `cp`, which under WAL can miss the most recent commits. Pi's own session history lives under its
+config directory (`PI_CODING_AGENT_DIR`, `~/.pi/agent` by default).

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@timqi/pier",
+  "version": "0.0.1",
+  "description": "A self-hosted workspace for coding agents: web workbench and IM channels in front of Pi sessions",
+  "license": "AGPL-3.0-only",
+  "repository": "github:timqi/pier",
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "bin": {
+    "pier": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js",
+    "skills",
+    "docs/deploy.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "dev": "npm run build:web && tsx watch src/main.ts",
+    "dev:web": "vite",
+    "build": "tsc && npm run build:web && npm run build:assets",
+    "build:assets": "mkdir -p dist/boards dist/web && cp src/boards/pier.css dist/boards/ && rm -rf dist/web/public && cp -r src/web/public dist/web/public",
+    "prepack": "npm run build",
+    "build:web": "vite build",
+    "check": "tsc --noEmit && tsc -p tsconfig.web.json --noEmit",
+    "lint": "oxlint src",
+    "test": "vitest run --passWithNoTests"
+  },
+  "devDependencies": {
+    "@tailwindcss/typography": "^0.5.20",
+    "@tailwindcss/vite": "^4.3.3",
+    "oxlint": "^1.79.0",
+    "tailwindcss": "^4.3.3",
+    "tsx": "^4.23.12",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.1",
+    "vitest": "^4.1.11"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@hono/node-server": "^2.1.1",
+    "croner": "^10.0.1",
+    "dompurify": "^3.4.14",
+    "highlight.js": "^11.12.0",
+    "hono": "^4.13.3",
+    "marked": "^18.0.10",
+    "typebox": "^1.3.7"
+  }
+}

package/skills/pier-boards/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: pier-boards
+description: Publish a Board — a folder of static HTML Pier serves at a stable URL — to present a report, digest, dashboard or handover note to the user. Read before building any page-shaped deliverable, or before editing an existing board.
+---
+
+# Building a Pier board
+
+A **board** is a directory in the boards folder `<pier>/AGENTS.md` names under
+"This Pier instance" — use that path verbatim; `~/.pier` is only the default.
+Pier serves `<board>/site/` and nothing else. Boards outlive sessions: any
+session may read or rewrite any board, and closing this one changes nothing.
+
+## Create one
+
+```
+<boards folder>/weekly-digest/
+  board.json
+  site/index.html
+```
+
+```json
+{
+  "title": "Weekly digest — infra",
+  "description": "What changed in infra this week and what needs a decision.",
+  "sessions": ["<your session id>"],
+  "public": false
+}
+```
+
+Those four fields are the whole manifest.
+
+- `slug`: `[a-z0-9][a-z0-9-]{0,63}`, and it is the URL — short and stable.
+- `description` is the Console list entry: write it for someone who has
+  forgotten this conversation.
+- `sessions`: append your own id, never replace — other ids are provenance too.
+
+## Publish, then hand over the link
+
+`"public": true` serves the board at `/p/<slug>/` **with no password**. Set it
+only if the user asked for a public or shareable board *in this request*;
+otherwise leave it `false`, say the board is private, and mention that Console →
+Boards flips it. Never publish credentials, internal paths, personal data or
+anything the user has not seen.
+
+The message announcing the board carries **one clickable link** — a bare path is
+not something a person can open, and a board nobody reached was not delivered.
+`<pier>/AGENTS.md` gives you the address, so there is nothing to look up:
+
+| The user asked for | Send |
+| --- | --- |
+| a board, nothing about sharing | `[Weekly digest](https://pier.example.com/boards/weekly-digest/)` — behind the Pier password |
+| a **public** board | `[Weekly digest](https://pier.example.com/p/weekly-digest/)` — no password |
+
+Never both: the pair invites pasting the password-free URL of a board that was
+never meant to leave the workspace, and `/p/<slug>/` 404s unless the manifest
+says `"public": true`. No address configured? Give the path, say Console →
+Settings turns it into a link, and never guess a host.
+
+## Writing the page
+
+A board is a **presentation**, not a text file: someone opens it to get an
+answer fast. Link the shipped stylesheet and write plain semantic HTML — no
+build, no npm, no framework:
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Weekly digest — infra</title>
+<link rel="stylesheet" href="/boards/_assets/pier.css">
+</head>
+<body>
+<div class="hero">
+  <h1>Weekly digest — infra</h1>
+  <p class="lede">Throughput is up, but two migrations need a decision before Friday.</p>
+  <p class="muted">18 Feb 2026 · covers 12 repos</p>
+</div>
+
+<div class="grid">
+  <div class="card"><span class="kpi good">12</span> PRs merged <span class="muted">+3 vs last week</span></div>
+  <div class="card"><span class="kpi warn">2</span> awaiting decision</div>
+  <div class="card"><span class="kpi">98.9%</span> uptime <span class="muted">30 d</span></div>
+</div>
+
+<div class="callout warn">
+  <strong>Needs you:</strong> the payments migration blocks two teams — approve or defer by Friday.
+</div>
+
+<h2>Payments is the only degraded service</h2>
+<table>
+  <thead><tr><th>Service</th><th>Status</th><th class="num">p95</th><th>Error budget</th></tr></thead>
+  <tbody>
+    <tr><td><strong>payments</strong></td><td><span class="tag bad">degraded</span></td><td class="num">910 ms</td>
+        <td><span class="bar bad" style="--v:18%"></span></td></tr>
+    <tr><td>api</td><td><span class="tag good">healthy</span></td><td class="num">142 ms</td>
+        <td><span class="bar good" style="--v:82%"></span></td></tr>
+  </tbody>
+</table>
+
+<details><summary>All 12 merged PRs</summary>
+<table><thead><tr><th>PR</th><th>Author</th><th>Merged</th></tr></thead>
+<tbody><tr><td>#412</td><td>ana</td><td>Mon</td></tr></tbody></table>
+</details>
+
+<footer>Written by Pier · data as of 18 Feb 09:00 · ask for an update to refresh</footer>
+</body>
+</html>
+```
+
+What makes it read as designed rather than generated:
+
+- **The lede is the verdict, not the topic.** "Two migrations need a decision by
+  Friday" answers; "This digest covers infra activity" restates the prompt. A
+  reader who stops after the hero must still leave with the point.
+- **Headings are findings.** "Payments is the only degraded service", not
+  "Services". A heading that could top any report — Overview, Summary, Details —
+  says nothing about this one.
+- **Every number carries its unit and its baseline**: "142 ms p95, was 120",
+  "12 of 40". A bare number is decoration; so is fake precision (98.8724% →
+  98.9%).
+- **End at the last useful block.** No closing summary, no filler section. The
+  footer holds provenance: data as-of, source, how to refresh.
+
+## What `pier.css` gives you
+
+Headings, paragraphs, lists, tables, `pre`/`code`, `blockquote`, `details` and
+`footer` are styled with **no classes at all**, dark mode included. The page
+sizes itself: a wide desktop canvas (62rem, 76rem on a very large screen) that
+reflows to one column on a phone, prose held to a readable measure while tables,
+`.grid`, `.split` and `.hero` use the full width — don't add a `max-width` of
+your own. Zebra striping, tables that scroll inside themselves, and `<details>`
+that print open are free. On top of that:
+
+| Class | Use it for |
+| --- | --- |
+| `.lede` | the one-sentence answer under the title |
+| `.hero` | the opening block: title + lede + date/scope, on a tinted panel |
+| `.grid` + `.card` | a KPI row (auto-fits to one column on a phone) |
+| `.kpi` | the headline number inside a card |
+| `.card` + `.good/.warn/.bad/.info` | a status card: accent edge and tinted fill |
+| `.callout` (`.good` `.warn` `.bad`) | the takeaway or the ask |
+| `.tag` (`.good` `.warn` `.bad` `.info`) | status pills in tables and lists |
+| `.good` `.warn` `.bad` | colour on a number or a word |
+| `.num` | right-aligned, tabular numeric table cells |
+| `.bar` (`.good` `.warn` `.bad`) | share-of-total inside a table: `style="--v:62%"` |
+| `.split` | two columns that stack on a phone: before/after, text + aside |
+| `.muted` | secondary text: dates, deltas, units, scope |
+
+Need something it lacks? A `<style>` block or your own CSS file inside `site/`
+is normal, and so is a custom colour or a hand-written layout when the content
+calls for one.
+
+## Pick the form from the content
+
+| What you have | How to present it |
+| --- | --- |
+| The single most important fact | `.hero` lede, or one `.kpi` on its own |
+| 2–4 headline metrics | `.grid` of `.card`s, each with `.kpi` + a `.muted` delta |
+| Something the reader must act on | `.callout warn` near the top, naming the deadline |
+| Items with a state | table with `.tag` pills, worst rows first |
+| Ranked or compared numbers | table, `.num` columns, `.bar` for share of total |
+| Progress toward a goal | `.bar` per row, or `.kpi` + "of 40 done" in `.muted` |
+| Two alternatives | `.split` with a `.card` each, verdict in the lede above |
+| A sequence of events | ordered list, date in `.muted` at the start of each item |
+| A trend over time | first/last + delta in words; inline SVG only if the shape *is* the news |
+| 200 rows | aggregate, show the 5–10 that matter, rest in `<details>` with the count in its summary |
+| 1–2 data points | a sentence or a `.callout` — a one-row table is a table costume |
+| Long raw output, logs, code | `<details>` at the bottom, or `<pre><code>` trimmed to the lines that matter |
+| Nothing to report | say so in the lede ("all 14 checks green") and stop — short is finished, not thin |
+
+Vary the forms: never two blocks of the same kind in a row, and prefer number →
+ask → proof → fold over six paragraphs. A status or decision board earns one
+screenful before the first `<details>`; only a handover or postmortem earns a
+long scroll. Colour is part of the message — green healthy/done, amber
+attention/pending, red broken/blocked, `.info` neutral emphasis — on the numbers
+and status cells that carry the point, never on ordinary prose; that contrast is
+what makes it read as signal.
+
+## Rules
+
+- **Static and self-contained.** Everything the page needs lives under `site/`
+  with relative paths. No CDN, no external fonts, no analytics, no `fetch()` —
+  a published board is served under a CSP that blocks all of it, so an external
+  reference is a broken page, not a slow one.
+- **Content, not an app.** Interaction is `<details>` and anchors; the page
+  stays readable with JavaScript off.
+- **Show, don't narrate.** A sentence describing numbers should have been a KPI
+  row or a table. Prose is for judgement — what it means, what to do.
+- **Structure before graphics.** A chart is inline SVG (no library) and only
+  when the *shape* of the data is the message. A three-row table beats any
+  picture of three numbers; no chart beats a decorative one.
+- **Only real data.** Every figure traces to something you saw this session, and
+  a gap is shown as a gap ("no data since Tue", "~3 weeks", "n=3") — never
+  smoothed into a clean number.
+- **Rewrite in place.** Updating a board means editing its files, not creating
+  `weekly-digest-v2`. The URL is the point.
+- Top-down — what this is → the answer → detail → raw data in `<details>` —
+  prose in the user's language, short headings, no emoji chrome.
+
+## If a board needs a build
+
+Pier ships no toolchain and the default is no build. If one is genuinely needed
+(a bundled charting library, a component layout), you own it: keep sources
+outside `site/` (e.g. `<board>/src/`), emit into `site/`, and write a
+`<board>/README.md` a future session can follow cold — install command, build
+command, output path, where the data came from. Never leave `site/`
+inconsistent with its sources; on an existing board look for that README first
+and rebuild, because hand-patching `site/` is lost on the next build.