xonecas.io
8058
Ir

irvc / commit 0142753

chore: docs pass, CLAUDE.md and remove vps specifics

xonecas2026-10-12 0142753b1e9347ad619913c46bb08e89e3558788 parent a3979ce

5 files changed

AGENTS.md+0−67
@@ -8,75 +8,8 @@ the need is rising for a private self hosted instance of this.
88
99 This is ours.
1010
11-## This box is production
12-
13-**This checkout is the live instance at https://irvc.xonecas.io. It is not a
14-sandbox.** The `irvc` systemd service runs from this directory
15-(`WorkingDirectory` = this repo). Treat everything here as live.
16-
17-- `web/dist` is served live from disk per request. `cd web && npm run build`
18- **deploys the frontend immediately** — no separate deploy step.
19-- `irvc.db` (WAL) is the live database: all users, invites, sessions, channels,
20- messages. It is the only state.
21-- `./irvc` is the live binary; `go build -o irvc .` replaces it on disk (the
22- service picks it up on restart).
23-- Host config (DNS, Caddy, firewall, Caddyfile) lives in `../vps/README.md`.
24-- Deployment runbook: `DEPLOY.md`.
25-
26-### SQLite: be very, very careful
27-
28-The DB holds real users and messages. Losing or corrupting it loses everything.
29-
30-- **Never start a second server process against `irvc.db`.** One process owns it.
31-- **Never run schema migrations, manual writes, or `sqlite3` mutations by hand.**
32- Read-only inspection is fine; anything that writes is not.
33-- Don't copy, move, truncate, or delete the DB, `-wal`, or `-shm` files.
34-- Don't create accounts or invites in it without Sean's explicit approval.
35-
36-When verifying changes, use the live site directly (`agent-browser` against
37-https://irvc.xonecas.io) — never spin up a local instance.
38-
3911 ## Docs
4012
4113 - `README.md` — build, configuration, invites, run.
4214 - `irvc.md` — design.
4315 - `DEPLOY.md` — runbook for the VPS deployment.
44-
45-## Agent test account
46-
47-This is the shared test account for agents. Use it for any live UI checks.
48-
49-- URL: https://irvc.xonecas.io
50-- Username: `deepseek`
51-- Password: `deepseek`
52-
53-Rules:
54-
55-- Use only this account. It is the only account agents may use.
56-- Never create new accounts or invites without explicit approval from Sean.
57-
58-### Seeing the UI
59-
60-Use `agent-browser`:
61-
62-```bash
63-agent-browser open https://irvc.xonecas.io
64-agent-browser snapshot -i # find the username/password fields
65-agent-browser fill @e<user> deepseek
66-agent-browser fill @e<pass> deepseek
67-agent-browser click @e<join>
68-agent-browser screenshot /tmp/irvc.png
69-```
70-
71-If already logged in, just open and snapshot.
72-
73-Note: this React app does not respond to `agent-browser click`/`press` for some
74-controls (e.g. `send`, Enter-to-send). Native clicks work but React handlers may
75-not fire. Fall back to dispatching the real DOM event via `agent-browser eval`:
76-
77-```bash
78-# submit the message form
79-agent-browser eval "document.querySelector('form').requestSubmit()"
80-# click a button by title
81-agent-browser eval "[...document.querySelectorAll('button')].find(b=>b.title==='dark mode').click()"
82-```
CLAUDE.md+1−0
@@ -0,0 +1 @@
1+AGENTS.md
FEEDBACK.md+0−11
@@ -1,11 +0,0 @@
1-# FEEDBACK
2-
3-Features requested on voice.
4-
5-- **GFM** — GitHub-flavored markdown in messages. DONE
6-- **Image support** — image preview plus focus dialog (click to enlarge).
7-- **`/me`** — emote/action command. CAN BE DONE WITH MARKDOWN `_is happy_`
8-- **`/collapse`** — slash command to collapse, plus a settings-pane option to make the choice durable.
9-- **Multiline input** — compose messages across multiple lines. DONE
10-
11-Source: sean's messages 15–17 in `#general`, 2026-10-11.
README.md+10−2
@@ -9,7 +9,8 @@ deployment runbook.
99 Three processes on one host:
1010
1111 - **livekit-server** — voice only. Ephemeral rooms.
12-- **irvc** (this repo, Go) — API, auth, text chat over WebSocket, SQLite.
12+- **irvc** (this repo, Go) — API, auth, text chat and presence over WebSocket,
13+ media uploads, SQLite.
1314 - **Caddy** — TLS + reverse proxy for the frontend, API, and LiveKit signal.
1415
1516 ## System dependencies
@@ -24,10 +25,13 @@ Bare Linux, no Docker. On Arch:
2425
2526 ## Build
2627
28+`make` builds both the Go server and the web frontend. Or step by step:
29+
2730 go build -o irvc .
2831 cd web && npm install && npm run build
2932
30-`web/dist` is served by the Go process.
33+`web/dist` is served by the Go process. `make test` runs the Go and npm tests;
34+`make fmt` formats. For frontend work, `cd web && npm run dev` runs Vite.
3135
3236 ## Configuration
3337
@@ -46,6 +50,10 @@ Secrets come from the shell env:
4650
4751 Voice is disabled if the LiveKit vars are unset.
4852
53+The address, DB, media, upload, and LiveKit URL settings also have flags
54+(`--listen`, `--db`, `--media-dir`, `--max-upload`, `--livekit-url`). Run
55+`./irvc --help`. `./irvc --gen-secret` prints a random session secret.
56+
4957 Example `livekit.yaml` (run with `livekit-server --config livekit.yaml`):
5058
5159 port: 7880
irvc.md+41−24
@@ -10,14 +10,17 @@ Small, private chat + voice for 4–6 people on one VPS. No data gathering, full
1010
1111 **In:**
1212 - Server-side accounts, invite-only.
13-- Text channels with persisted history (IRC-like).
14-- Voice channels, ephemeral (not recorded).
15-- Presence: online/offline.
13+- Text channels with persisted history (IRC-like), GFM markdown, multiline compose, mentions.
14+- Image attachments (raster only), stored on disk.
15+- Voice channels, ephemeral (not recorded), with mute, deafen, per-peer volume, mic processing, a level-based noise gate, and a join/leave tone.
16+- Presence: online/offline, plus who is in each voice channel without joining.
17+- Client themes, font size, per-user voice settings.
1618 - One server per deployment, seeded with one text and one voice channel.
1719
1820 **Out (now):**
1921 - Large scale, multi-node, clustering.
20-- Recording, screen share, DMs.
22+- Recording, screen share, video, DMs.
23+- Message editing/deletion/search, channel CRUD.
2124 - Email, OAuth, passkeys.
2225 - Docker.
2326 - Backups.
@@ -28,26 +31,28 @@ Small, private chat + voice for 4–6 people on one VPS. No data gathering, full
2831 One VPS, three processes:
2932
3033 - **LiveKit** — self-hosted, voice only. Own ports: signal `7880`, TCP `7881`, media `50000-60000/udp`. Media ports exposed raw, not proxied.
31-- **Gin server (Go)** — API, auth, invite/session handling, token minting, text chat over WebSocket, SQLite.
34+- **Gin server (Go)** — API, auth, invite/session handling, LiveKit token minting, text chat and presence over WebSocket, media upload/serve, SQLite.
3235 - **Caddy** — TLS + reverse proxy for frontend and API. Terminates TLS; proxies `wss` to LiveKit signal.
3336
3437 Split:
3538 - Text → our WebSocket + SQLite. LiveKit not involved.
36-- Voice → LiveKit. Ephemeral.
37-- Presence → our WebSocket (connected = online).
39+- Voice → LiveKit. Ephemeral. The Go server mints tokens but never dials LiveKit.
40+- Presence → our WebSocket (connected = online; voice occupancy broadcast to all).
41+- Media → disk under the media dir, served by Go.
3842
3943 ## Auth & Identity
4044
4145 - Invite links: single-use, 14-day expiry. Anyone with a link creates a user and joins.
4246 - Revoke = delete the row.
4347 - Passwords hashed with argon2id.
44-- Login → session cookie (`HttpOnly`, `Secure`, `SameSite=Lax`) → server mints a short-lived LiveKit token when a voice channel is joined.
45-- Rate limit login and invite-claim endpoints.
48+- Login → session cookie (`HttpOnly`, `Secure`, `SameSite=Lax`), 30-day TTL, server-side session row. Cookie value is HMAC-signed.
49+- Server mints a short-lived LiveKit token when a voice channel is joined.
50+- Rate limit login and invite-claim endpoints (per IP).
4651 - No email. Admin resets passwords by hand.
4752
4853 ## Data (SQLite)
4954
50-WAL mode, `busy_timeout`. One file, the only state.
55+WAL mode, `busy_timeout`. One file, the only state; uploaded media lives in the media dir.
5156
5257 ```
5358 users (id, username, pass_hash, created_at)
@@ -57,23 +62,31 @@ channels (id, type, name, position, created_at) -- type: text | voice
5762 messages (id, channel_id, user_id, body, created_at)
5863 ```
5964
60-Seed: one text channel `#general`, one voice channel `general`.
65+- Messages are returned joined with their author's username.
66+- Seed: one text channel `#general`, one voice channel `general`.
67+- Uploaded images: random names, raster only (no SVG/HTML), served with `nosniff`.
6168
6269 ## Behavior
6370
64-- **Channels:** seeded only (`#general` text, `general` voice). Ordered by `position`. CRUD is out of scope for now.
65-- **Text:** messages persist; shown as timestamp, author, content. Live append over WS.
66-- **Voice:** joining a voice channel connects to its LiveKit room. Not persisted, not recorded.
67-- **Presence:** a user is online while their WS connection is up; otherwise offline. No invisible mode.
71+- **Channels:** seeded only (`#general` text, `general` voice). Ordered by `position`. CRUD is out of scope.
72+- **Text:** GFM markdown; single newlines are hard breaks. Messages persist; live append over WS. Rendered as timestamp, author, content.
73+- **Mentions:** `@username` highlights the message for that user; typing `@` opens an autocomplete.
74+- **Commands:** `/me <action>` renders an emote as `* user action`; `/collapse` hides images in the current channel.
75+- **Images:** pasted or attached, uploaded, rendered inline with a click-to-zoom dialog. Collapsible per message or channel-wide.
76+- **Voice:** joining a voice channel connects to its LiveKit room (`voice-<id>`). Not persisted, not recorded. Occupants are visible to everyone without joining.
77+- **Voice controls:** mute, deafen (local only), per-peer volume, mic/speaker device, quality preset, echo cancellation, noise suppression, auto gain, voice isolation, level-based noise gate, join/leave tone.
78+- **Presence:** a user is online while their WS connection is up; otherwise offline. Voice occupancy rides along with presence. No invisible mode.
79+- **Settings:** themes, font size, and voice preferences are client-side (device-local). Voice occupancy is server-side only.
6880
6981 ## Frontend
7082
71-- React, modern. oxlint + oxfmt. Tailwind + Shadcn.
72-- Dark sepia theme (colors from `../www`), monospace, minimalist, functional.
83+- React, modern. oxlint + oxfmt. Tailwind + Shadcn. LiveKit client.
84+- Two themes (`80s-nicotine` sepia default, `tuxedo` grayscale) × light/dark, applied before first paint. Monospace, minimalist, functional.
7385 - Layout:
74- - Left sidebar: text channels, then voice channels.
75- - Focus pane: selected item, or first text channel by default.
76- - Right sidebar (toggleable): user list with online/offline.
86+ - Left sidebar: text channels, voice channels (with occupants), then users (online/offline). Collapsible; overlays on mobile.
87+ - Focus pane: chat for the selected text channel, or the settings pane.
88+ - Header: sidebar toggle, current channel or settings title.
89+- Settings pane: theme, font size, sounds, deafen, voice-activation meter/threshold, devices, quality, mic processing.
7790
7891 ## Config
7992
@@ -82,14 +95,18 @@ Secrets from shell env, `IRVC_*`:
8295 ```
8396 IRVC_LISTEN_ADDR
8497 IRVC_DB_PATH
85-IRVC_SESSION_SECRET
86-IRVC_LIVEKIT_URL
98+IRVC_SESSION_SECRET required to run
99+IRVC_LIVEKIT_URL browser-facing
87100 IRVC_LIVEKIT_API_KEY
88101 IRVC_LIVEKIT_SECRET
102+IRVC_MEDIA_DIR uploaded image storage
103+IRVC_MAX_UPLOAD max upload bytes
89104 ```
90105
91-LiveKit key/secret must match the LiveKit server config and ours.
106+LiveKit key/secret must match the LiveKit server config and ours. Voice is disabled when the LiveKit vars are unset.
107+
108+Flags mirror these. `irvc invite` creates an invite and prints a `/join?token=...` link; `irvc --gen-secret` prints a random session secret. A Makefile wraps build/test/fmt for Go and npm.
92109
93110 ## Deployment
94111
95-Bare Linux, no Docker. README lists system-level deps. Services start on boot and restart on crash (systemd).
112+Bare Linux, no Docker. README lists system-level deps. Services start on boot and restart on crash (systemd). See `DEPLOY.md` for the runbook.