OverviewFilesCommitsIssuesDocsReleasesPeers

favela-web commits / 2e14256

README: two surfaces that do not exist, and a test suite broken for 18 days
Named favela-cli and favela-native as the sibling surfaces. Neither exists — `ls` confirms — and the real two are favela-surface and favela-surface-android. The env var count said ~38; bin/favela-web.js reads 33 distinct process.env names. The Run section documented `npm test` as "node suite" and test:ws, and omitted test:bare entirely, which is where the appview and everything that opens a corestore is tested. All three are now listed, with the file count (74) and the reason the node script exists: those files are the runtime-agnostic layer and say so in their own headers. Noted as a divergence from the fleet's brittle-bare gate rather than left to look like an oversight. And stated the failure rather than leaving a reader to find it: `npm test` dies at test/strip-vectors.test.mjs, which reads spec/vectors/markdown-strip.json. That file moved to favela-markdown on 2026-09-02 (spec/MOVED-record-specs.md records the move) and the test did not go with it, so the suite has aborted on the first file since. Pre-existing and unrelated to this commit — the test was added 2026-08-05 in 1be2a41, the vectors left in 71f2724. Not fixed here because removing a test file is a decision, not a docs edit. The case for removing it: favela-markdown's test/strip.test.js runs the same vectors against the real stripper ("every vector reproduces byte-for-byte", plus facet invariants), while this one only ever checked the vectors were well-formed — its own header says "No stripper exists yet". Keeping a validator here also re-creates exactly the coupling the MOVED note gives as the reason for the move. Glyph count 3 -> 0. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2e142568cfa338233cf2cf38f0789fbf768747ea
by plankatron <fleeky@gmail.com> · 2026-09-20T20:46:11.000Z

Changed files (1) +18 -6

README.md +18 -6
……@@ -2,7 +2,8 @@
22
33The **web / SSR surface of Favela** — the native, P2P-local, community-owned social client + appview over
44the self-custody atproto stack ([hyper-proto-peer](../hyper-proto-peer)). One of the Favela surfaces
5(alongside `favela-cli` and `favela-native`). Bluesky is an optional POSSE **lens export**, not the home.
5(alongside `favela-surface` and `favela-surface-android`). Bluesky is an optional POSSE **lens
6export**, not the home.
67
78A Bare backend that reads a roster of DIDs over pure P2P ([atproto-did-peer](../atproto-did-peer)), folds
89them into a local appview index, and serves the views **server-rendered** (no-JS HTML at real URLs) plus
……@@ -33,7 +34,7 @@ Then set the two things that have **no default** (see Config), and start it:
3334pgh app start favela-web # http://localhost:4041
3435```
3536
36⚠ **Unconfigured means inert, on purpose.** With no `FAVELA_ROSTER` this node indexes nothing, and with
37**Unconfigured means inert, on purpose.** With no `FAVELA_ROSTER` this node indexes nothing, and with
3738no write transport it refuses every write. Earlier versions defaulted both to the author's own fleet,
3839so a fresh install silently indexed someone else's timeline and aimed its writes at their production
3940node. Empty is the correct unconfigured state; the errors tell you what to set.
……@@ -55,7 +56,7 @@ Overrides go in `~/.config/pgh/apps.json` under `favela-web.env` (there is no CL
5556| Var | Default | Meaning |
5657|---|---|---|
5758| `FAVELA_PORT` | `4041` | HTTP port |
58| `FAVELA_HOST` | `0.0.0.0` (manifest) / `127.0.0.1` (code) | ⚠ a hand-run `bare bin/favela-web.js` binds loopback |
59| `FAVELA_HOST` | `0.0.0.0` (manifest) / `127.0.0.1` (code) | a hand-run `bare bin/favela-web.js` binds loopback |
5960| `ATPROTO_OVERLAY_ROOT` | hpp's `data/atproto-repo` | shared record byte store; wrong path silently downgrades every DID to firehose backfill |
6061| `FAVELA_STORE_ROOT` | `~/.config/favela-web/data` | appview corestore — keep it OUTSIDE the install tree or `pgh app update` wipes it |
6162| `FAVELA_EXTERNAL_URL` | — | public URL published in did:web / feed records |
……@@ -64,7 +65,7 @@ Overrides go in `~/.config/pgh/apps.json` under `favela-web.env` (there is no CL
6465| `FAVELA_REQUIRE_MEMBERSHIP` | off | `1` = writers must also be on a community roster |
6566| `FAVELA_LABELER_SEED` | off | enable favela's own atproto labeler (interim) |
6667
67`bin/favela-web.js` reads ~38 env vars in total; the rest are tuning (`FAVELA_SPACEDUST`,
68`bin/favela-web.js` reads 33 env vars in total; the rest are tuning (`FAVELA_SPACEDUST`,
6869`FAVELA_RETENTION_BUDGET`, `FAVELA_AP_BRIDGE`, …) and are safe to ignore.
6970
7071## Who may read and write
……@@ -74,7 +75,7 @@ delegated — any atproto account can prove that about itself.
7475
7576- **Reads** are public by default. A community closes its site with `set-meta visibility members`; the
7677 sign-in path, static assets and `/xrpc/*` stay reachable regardless (`lib/gate-policy.js`).
77 ⚠ `/xrpc/*` must stay open: bsky's AppView reads the lens anonymously.
78 `/xrpc/*` must stay open: bsky's AppView reads the lens anonymously.
7879- **Writes** pass one default-deny gate (`lib/check.js`). A new POST route is treated as a repo write
7980 until it is deliberately classified otherwise.
8081 - repo writes require **owning the repo** — `viewer.did` must equal the DID this node's hpp signs for;
……@@ -89,9 +90,20 @@ reachable instance can front the lens without exposing an authoring path.
8990
9091```sh
9192bare bin/favela-web.js # FAVELA_PORT=4041 by default
92npm test # node suite; npm run test:ws for the bare-ws firehose test
93npm test # the pure modules — render, gates, codecs — under node
94npm run test:bare # the appview and everything that opens a corestore, under bare
95npm run test:ws # the bare-ws label firehose
9396```
9497
9874 test files across the three scripts. `npm test` runs under node rather than `brittle-bare`
99because those files are the runtime-agnostic layer and say so, which is a divergence from the rest of
100the fleet; anything touching a store or a swarm is in `test:bare`.
101
102`npm test` currently fails at `test/strip-vectors.test.mjs`: it reads
103`spec/vectors/markdown-strip.json`, and that file moved to `favela-markdown` on 2026-09-02 (see
104`spec/MOVED-record-specs.md`) without the test moving with it. favela-markdown's `test/strip.test.js`
105covers the same vectors against the real stripper, which this one never did.
106
95107Deployed as a pgh app (`pgh.type: daemon`, `runtime: bare`); the [atproto-bridge](../atproto-bridge)
96108membrane proxies the lens-export XRPC to it (`FAVELA_WEB_UPSTREAM`).
97109