# AGENTS.md — OpenVibe.Host

## Project Overview

OpenVibe.Host is two things in one repository:

1. **The network's operator plane, `ovhost`** — a root-run CLI/library that deploys, rolls back, validates, probes,
   backs up and restore-drills every service on the host. It is installed at `/usr/local/lib/openvibe-host`
   (linked `/usr/local/bin/ovhost`) with the inventory `/etc/openvibe/host.json`; it is updated with
   `sudo ovhost self-update`, not by the catalog deploy.
2. **The `openvibe.host` catalog service** — hosting compared honestly (cloud/VPS/dedicated plans, offers, domain
   prices, benchmarks, price history, staff entries) and the console where a person connects their own hosting
   accounts. It runs at port 4910.

- **Domain:** `openvibe.host` (catalog) · **Port:** 4910 · **Service id:** `host` · **Env prefix:** `HOST`/`OV_`
- **Runtime:** Node 22, Express 4, PostgreSQL 18 through `openvibe-sdk/db` (PGlite in development/tests), Valkey 9;
  plain systemd/nginx/git/ffmpeg-free host tools for the CLI.
- **Read first:** [README.md](README.md) (very long and authoritative), [docs/deploy-strategies.md](docs/deploy-strategies.md),
  [docs/backups.md](docs/backups.md), [docs/restore-drills.md](docs/restore-drills.md),
  [docs/data-provisioning.md](docs/data-provisioning.md), [host.example.json](host.example.json).

**Network context:** the catalog uses Network SSO/staff (`host.catalog.manage`), the JWKS, client-credentials for the
outbox relay and `ovhost alerts relay`, and `network.status.incident` for incidents/maintenance. The catalog's pages
are OpenVibe.Search documents; discussion is OpenVibe.Community (thread refs only); prices come from OpenVibe.Sources
(optional ingest) and keyed provider APIs. `ovhost` calls only the host's own services, Network, Events, Prometheus and
the backup bucket.

## Commands

```bash
npm ci                         # install (contracts/sdk/shared/publishing pinned by tag)
npm run dev                    # http://localhost:4910, PGlite under data/
npm start                      # node server/index.js
npm test                       # every test/*.test.js; system calls go to test/fake-host.js
npm run test:pg                # the same through PostgreSQL + PgBouncer
npm test -- catalog            # only test files whose name contains the word
node --check <file.js>         # syntax check (no linter configured)
sudo ovhost --version          # the installed CLI (not this checkout, unless run as ./bin/ovhost)
sudo ovhost status [<service>...]           # units, sha, readiness, protected sessions
sudo ovhost validate <service> [--manifest <file>]   # env NAMES, units, port, vhost+nginx -t, deps, lifecycle
sudo ovhost plan <service> [--to <sha>] [--no-fetch] [--restart]
sudo ovhost deploy <service> [--wait-idle] [--force] [--restart] [--to <sha>] [--install-units]
sudo ovhost rollback <service> [--to <sha|release>] [--wait-idle] [--force]
sudo ovhost backup --all [--offsite] [--logical] | sudo ovhost drill <service> [--keep]
sudo ovhost incident|maintenance|freeze ... | sudo ovhost alerts relay | sudo ovhost self-update
```

Every command takes `--json` and `--inventory <file>`. Exit codes: `0` ok · `1` usage/precondition (held lock) · `2`
validation failed, nothing restarted · `3` not ready, rolled back and serving · `4` rollback failed, **manual
intervention** · `5` protected sessions active (or `--wait-idle` gave up) · `6` frozen (`--force` goes through;
rollbacks are never frozen).

## Architecture at a Glance

- **CLI entry:** [bin/ovhost](bin/ovhost) → [lib/cli.js](lib/cli.js), commands under [lib/commands/](lib/commands/)
  (`backup.js`, `data.js`, `drill.js`, `self-update.js`, `service-add.js`, `snapshot.js`, `status.js`, `validate.js`).
- **Operator core:** [lib/inventory.js](lib/inventory.js) (the inventory model and its refusals),
  [lib/executor.js](lib/executor.js) (deploy/rollback orchestration), [lib/systemd.js](lib/systemd.js) (the socket
  guard and `setpriv` drops), [lib/readiness.js](lib/readiness.js), [lib/probes.js](lib/probes.js) (protected
  sessions, `http-json-count`/`postgresql-count`/`sum` and `addFields` semantics), [lib/nginx.js](lib/nginx.js)
  (render + transactional install), [lib/releases.js](lib/releases.js), [lib/release-layout.js](lib/release-layout.js),
  [lib/deps.js](lib/deps.js), [lib/deploy-guard.js](lib/deploy-guard.js), [lib/lock.js](lib/lock.js),
  [lib/envfile.js](lib/envfile.js) (names/emptiness only), [lib/lifecycle.js](lib/lifecycle.js),
  [lib/dbengine.js](lib/dbengine.js), [lib/backup-crypto.js](lib/backup-crypto.js), [lib/offsite.js](lib/offsite.js),
  [lib/retention.js](lib/retention.js), [lib/alerts.js](lib/alerts.js), [lib/announce.js](lib/announce.js),
  [lib/incidents.js](lib/incidents.js), [lib/nodes.js](lib/nodes.js), [lib/media.js](lib/media.js),
  [lib/browser-watch.js](lib/browser-watch.js), [lib/dns.js](lib/dns.js), [lib/certs.js](lib/certs.js),
  [lib/commands/snapshot.js](lib/commands/snapshot.js), [lib/tar.js](lib/tar.js), [lib/archive.js](lib/archive.js).
- **Inventory:** [host.example.json](host.example.json) is the model (checkout/owner/units/socket/unitSources, env
  required names, port, loopback ready URL/headers, packages/install/build hooks, `noRestartPaths`, `protected`
  probes, drain, databases, backupOnChange, nginx, layout, workerUnits, auxiliaryUnits, objects, strategy). The real
  `/etc/openvibe/host.json` is **never committed**.
- **Catalog service:** [server/app.js](server/app.js), [server/index.js](server/index.js), [server/config.js](server/config.js),
  [server/db.js](server/db.js), [server/catalog/](server/catalog/) (`mapping.js`, `ingest.js`, `keyed-feeds.js`,
  `offers.js`, `domains.js`, `domain-check.js`, `rdap.js`, `benchmarks.js`, `community.js`, `pricing.js`, `trend.js`,
  `search-index.js`), [server/console/console.js](server/console/console.js), [server/http/](server/http/),
  [server/auth/](server/auth/) (capabilities, forms, SSO, viewer), [server/render/](server/render/),
  [server/data-sources-config.js](server/data-sources-config.js), [server/account-data.js](server/account-data.js),
  [server/worker.js](server/worker.js).
- **Database:** [server/db.js](server/db.js) and [migrations/](migrations/): catalog providers/plans/promos/
  price changes/offers/domain prices/benchmarks, `host_console_accounts`/`host_console_actions`, `config_keys`/
  `config_snapshots`, `event_outbox`, `account_data_events`, `telemetry_samples`. Migration 0008 dropped the old
  static-hosting engine tables on purpose.
- **Deploy:** [deploy/systemd/openvibe-host.service](deploy/systemd/openvibe-host.service) (127.0.0.1:4910,
  `/etc/openvibe/host.env`, checkout `/opt/openvibe.host`, state `/var/lib/openvibe-host-api`) and the operator
  timers in [deploy/systemd/](deploy/systemd/) (`openvibe-backup`, `-alerts`, `-browsercheck`, `-authhealth`,
  `-readyhealth`, `-devpath`, `-toolsjob`); nginx files in [deploy/nginx/](deploy/nginx/). `sudo ovhost deploy host`
  (strategy `git-checkout`); `sudo ovhost rollback host --to <sha>`.

## Ownership and Boundaries

Host owns (a) the operator plane: inventory, env-name validation, deploy strategies, readiness/drain, release log,
certificate inventory, vhost rendering/install, config snapshots, backups/offsite/retention, restore drills, incidents,
alerts relay and release announcements; (b) the catalog: providers/plans/promotions/price history, offers, registrar
prices and domain checks, benchmarks and their one-time links, the console's sealed provider tokens and action log, the
catalog Search documents; (c) the data role and its `add-service.sh`. It does **not** own: product business logic
(calls hooks and `/api/ready`, `/api/streams`), secrets (reads env **names** and emptiness only; the sole exception is
its own root-only `/etc/openvibe/backup.env`), certificate issuance (certbot; inventory only), platform-wide credentials
for hosted code, or static hosting (moved to OpenVibe.Space on 2026-10-12; `/hosting`, `/projects*`, `/sites*`,
`/deploys*`, `/domains*`, `/preview*`, `*.openvibe.host` and the old APIs answer **410** with a link to Space).

## Catalog and Console

- **Catalog data comes only from named sources**: Sources items (`HOST_CATALOG_INGEST`, `HOST_CATALOG_SOURCES_URL`),
  keyed provider feeds (DigitalOcean/Hetzner read every six hours with a sealed read-only token from
  `host.data_sources`; env fallback `HOST_DIGITALOCEAN_TOKEN`/`HOST_HETZNER_TOKEN`), and staff entries with a source
  URL. **Nothing is estimated**: a value the source does not state is "Unknown". LightSail monthly = hourly × 744,
  IPv6-only bundles show 0 IPv4, OVH addons are joined to their product, Vultr is disabled (its API host forbids
  robots). `POST /internal/config/host.data_sources/test/:key` makes one read-only call and never returns the token.
- **Offers** from LowEndSpirit's public feed; LowEndTalk/LowEndBox feeds are off (403 to the production host). Keep
  headline/poster/date/link and a stated monthly or yearly price with its monthly equivalent; editorials/giveaways are
  not offers; a removed post is hidden; >120 days drops off; `sort=price` needs a currency and converts nothing.
- **Domains** from registrars' public price lists (Porkbun keyless; Handshake names out) with append-only change
  history; a name check asks the ending's RDAP (IANA bootstrap, https only, no redirects, 6 s, 10 min cache, 30/min
  per address) and prices the name at popular endings; each registrar's search is a plain deep link.
- **Benchmarks**: a signed-in person gets a one-time YABS link (24 h, 10/day); Host parses the JSON field by field
  (never the server's address), stores it, and never shows the submitter. They or staff may remove a result; export
  carries results and links, erasure deletes the links and leaves results anonymous.
- **Order** comes only from the visitor's sort; affiliate links are `rel="sponsored nofollow noopener"` with the
  provider's disclosure beside them and never change the order.
- **Console**: each provider token is checked when added, sealed AES-256-GCM under `HOST_CREDENTIALS_KEY` (32 bytes,
  hex/base64), never shown again (only the last four clear), opened only to call that provider, deleted on disconnect.
  Power on/off/reboot reach the provider and are logged. With no key the console connects nothing and says so.
  Account export/deletion (ADR-033) carries accounts (never tokens) + action log and erases them.
- **Discussion** uses Community thread refs `{service:'host', type:'provider'|'plan', id}` only; hidden providers and
  hidden/gone plans have no page, and status changes hide/reopen threads after commit. With no
  `HOST_COMMUNITY_URL`, no Discussion block appears.

## Operator Rules (the ones that page you)

- **Socket units are never stopped/restarted** except the release-layout rebind when the unit file changed or pid 1
  does not hold the port. Every `systemctl` call goes through the guard.
- **Protected sessions:** Live's `/api/streams`, Media's `/api/ready` counters, Events SSE, Chat sockets, Games players,
  OpenRestream ingest, Tools jobs. A probe that **cannot answer while the service runs counts as active**, never zero.
  `--wait-idle` waits for two idle checks in a row; `--force` proceeds with a warning. `null` from a service is
  unknown, so the restart is held; an `addFields` field the service does not report at all is zero (older service).
- **Tracked local changes block a deploy**; they are never discarded. One operation per service at a time (pid lock
  with stale recovery). Every attempt is in the release log, refusals included.
- **Readiness:** poll `/api/ready`; on failure restore the previous sha, reinstall dependencies if they differed,
  restart, and exit 3 (or 4 + MANUAL INTERVENTION if that fails).
- **Dependencies** must resolve (`node_modules/<dep>/package.json` parses and names the package) before anything
  restarts; install only when the lockfile/deps changed and restore `package-lock.json` if npm rewrote it.
- **nginx** changes are transactional: render, `nginx -t`, install, reload; a failed test restores the previous files
  and does not reload. Certificates are inventory only; no key file is read.
- **Secrets** never leave an env file: no value in text/JSON output, logs, snapshots or backup manifests. Backups are
  root-only (0700/0600), off-host copies AES-256-GCM encrypted and authenticated; a failed verification is `failed`,
  never `skipped`.
- **Restore drills** check the dump, restore into a scratch database/role, start a sandboxed second instance, compare
  declared HTTP paths and row counts, then stop it and drop the scratch objects. `drill` exits 0 passed, 1 refused,
  2 failed; run as root only.
- **Inventory** must be root-owned and not group/world-writable when `ovhost` runs as root; relative paths, non-loopback
  probe URLs, non-SELECT probe queries and vhost names with a path are refused. `workerUnits` are never started/stopped
  by ovhost; `auxiliaryUnits` restart only when their `restartOn` path changed.
- **Lifecycle:** each service's Contracts manifest (≥0.55.0) supplies liveness/shutdown/drains/workers/rollback/
  contracts/leases; the inventory block may override. `validate` fails on a missing field or a deadline longer than a
  unit's stop timeout, and on a different `KillSignal`.
- **Self-update** refuses a dirty tree, a branch other than `main` or a divergence; it restarts nothing.

## Key Pitfalls

- **This repository deploys two things differently:** `sudo ovhost deploy host` replaces the catalog checkout at
  `/opt/openvibe.host`, but **not** the CLI install at `/usr/local/lib/openvibe-host`; after a merge to `main` run
  `sudo ovhost self-update` or the CLI silently runs behind.
- **Never commit `host.json`** or a real env value. `host.example.json` is the model; `service add` copies an entry
  and backs up the live inventory.
- **Stage C is not started** and Stage B's engine is gone. Do not resurrect `/projects`, `/sites`, `/deploys`,
  `/domains` or `*.openvibe.host`; they answer 410 for a reason.
- **Console tokens:** never log, return, export or snapshot a provider token; only the last four clear characters may
  appear. The export carries accounts without tokens.
- **Catalog honesty:** no estimated price, no converted currency, no affiliate-driven order, no invented benchmark
  field. A source that does not state a value is Unknown.
- **IndexNow** is off without `INDEXNOW_KEY`; a re-check at the same price sends nothing; key served at `/<key>.txt`.
- **Freeze** (`ovhost freeze`) makes deploys exit 6; rollbacks are never frozen and `--force` goes through.
- **Browser check** is report only: it never changes the exit code or the release record.
- **Boot order drop-ins** (`openvibe-.service.d/`, PgBouncer after PostgreSQL) are `unitSources` of the host service;
  `sudo ovhost validate host` reports drift and `sudo ovhost deploy host --install-units` installs them.

## Testing

`npm test` runs every file in [test/](test/) with every system call against [test/fake-host.js](test/fake-host.js):
acceptance, deploy/rollback/guard, release layouts and strategies, probes, readiness, socket guard, env
validation, nginx/certs, backups (pgBackRest/logical/offsite), drills, data provisioning/role, boot-order drop-ins,
alerts/announce/incidents, catalog (ingest, keyed feeds, offers, domains/RDAP, benchmarks, discussion, search, trends,
staff), console, account data, actor limits, CSP, engine-moved 410s, browser check/watch, DNS, nodes, inference planner,
and the deploy wrapper. `npm run test:pg` for PostgreSQL. Run the narrowest file first, then the suite; always
`node --check` changed files.

## Documentation

- [README.md](README.md) — catalog, console, static hosting moved, purpose/rules, owns, does-not-own, depends on,
  capabilities, stages, acceptance, using ovhost, inventory, deploy, installing, security, development, launch rule.
- [docs/deploy-strategies.md](docs/deploy-strategies.md), [docs/backups.md](docs/backups.md),
  [docs/restore-drills.md](docs/restore-drills.md), [docs/data-provisioning.md](docs/data-provisioning.md),
  [docs/db-inventory.md](docs/db-inventory.md), [docs/browser-check.md](docs/browser-check.md),
  [docs/release-notifications.md](docs/release-notifications.md), [docs/operator-alerts.md](docs/operator-alerts.md),
  [docs/incidents-and-dns.md](docs/incidents-and-dns.md), [docs/no-502.md](docs/no-502.md),
  [docs/ready-health.md](docs/ready-health.md), [docs/host-firewall.md](docs/host-firewall.md),
  [docs/threat-review.md](docs/threat-review.md), [docs/launch.md](docs/launch.md), [docs/developer-path.md](docs/developer-path.md).
- [SECURITY.md](SECURITY.md), [host.example.json](host.example.json).