HarmenandClaude Opus 5
b2e9c8fc7a
De gebruiker koos ervoor het pakket meteen te maken en een installatie te proberen, met de image lokaal gebouwd en het recept in de repo. Dit is dat pakket. Er is nog niets gebouwd en niets geinstalleerd; "gebouwd" is hier nadrukkelijk niet "werkend". De zwaarste ontwerpvraag is met een precedent beslecht en niet met een gok. Trezor Suite is geen browser met een sessiecookie en kan dus niet achter de inlog van umbrelOS; het was onduidelijk of PROXY_AUTH_ADD "false" dan verantwoord is of een omweg. De eigen nostr-relay-app van Umbrel doet exact hetzelfde, om precies dezelfde reden, en heeft ook geen eigen ports:. De prijs staat in de compose en in het plan: wie die poort bereikt, bereikt de relay. Wat de schade beperkt is dat de relay elke eigenaar zonder limietenrij weigert. Daarom gaat de quota-manager mee, en dat is geen restje van Trezor's betaalde hosting: hij is wat die rijen aanmaakt. Relay en quota-manager komen uit dezelfde image met een ander command, want bovenstrooms is het een codebase met meerdere startscripts. Het command staat expliciet en leunt niet op de CMD van de Dockerfile, waar yarn start staat met bovenstrooms zelf een twijfel erbij. Het bouwrecept staat in tools/ en niet in de app-map. Dat is geen netheid: een Dockerfile staat niet in de update-whitelist, dus bouwen-in-de-app zou elke nieuwe versie een deinstallatie plus herinstallatie kosten. Onder tools/ en niet onder build/, want dat laatste staat in .gitignore als bouwselmap en het recept zou stilzwijgend buiten de repo zijn gebleven. Dat kwam pas bij git status aan het licht. De poort is 3851 en niet 4000. 4000 is de eigen poort van de relay maar ook een veelgebruikte poort, en een botsing op de host merk je pas als de app niet start. Die les komt van 50002 tegen Fulcrum. Nieuw testbestand test_appstore_vorm.py, en het gaat over de store en niet over een app: id gelijk aan mapnaam, store-voorvoegsel, veldvolgorde, app_proxy die naar een bestaande service wijst, en elke gemounte map die in de repo bestaat. Het vindt zijn apps zelf, dus een derde app valt er automatisch onder. Digests toetst het expres niet: geen van de twee apps haalt die regel vandaag en een suite die altijd rood staat wordt niet gelezen. Mutatie-getest met drie ingrepen: het app-id laten afwijken van de mapnaam, APP_HOST naar een niet-bestaande service laten wijzen, en de .gitkeep weghalen. Alle drie vielen om bij de juiste toets, en git diff was daarna leeg. Umbrelapp is gepromoveerd naar Actief als 008, tussen Proefopstelling en Appstore, en het masterplan is naar het archief. Wat er in de plannen als open blijft staan is niet klein: of Trezor Suite dit adres accepteert, of het databaseschema zichzelf aanmaakt, en hoe je een eigenaar registreert. Tests: 32 goed 0 fout, 39 goed 0 fout en 54 goed 0 fout, niets overgeslagen. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
113 lines
6.1 KiB
Markdown
113 lines
6.1 KiB
Markdown
# Docs - documentatiewortel van UmbrelApps
|
|
|
|
Dit is de **enige** documentatieboom in de repo, en dit is de **enige** README erin: alle regels over
|
|
waar iets hoort staan hieronder. De onderbouwing van de methode staat in `HomeGit/Docs/`.
|
|
|
|
```
|
|
Docs/
|
|
├── CONTINUE_HERE.md - dunne index: per prioriteitstier naar de "volgende stap" van elk actief plan
|
|
├── KNOWLEDGE.md - duurzame cross-plan kennis
|
|
├── CHANGELOG-<app>.md - versiegeschiedenis, per app
|
|
├── Plannen/
|
|
│ ├── Actief/NNN-<Plan>/ - PLAN.md (ontwerp) · TAKEN.md (checklist) · PROGRESS.md (log) · OPEN.md
|
|
│ ├── Archief/<Plan>/ - afgerond; hele map verhuist hierheen, nummer vervalt
|
|
│ └── Masterplannen/ - nog niet actief; elk plan als één <Naam>.PLAN.md
|
|
│ └── Archief/ - opgevolgd; hier wordt nooit in bewerkt
|
|
└── Referenties/ - uitsluitend naslag: dingen waar je rekening mee moet houden
|
|
```
|
|
|
|
De map `Plannen/Archief/` bestaat nog niet; lege mappen overleven git toch niet. Hij komt er zodra er
|
|
iets in gaat.
|
|
|
|
## Eén boom, twee apps
|
|
|
|
Deze repo is één community app store met twee apps erin, en er is **één** documentatiewortel voor allebei.
|
|
Dat is geen concessie maar de reden dat het samengevoegd is: de spec van de appstore, de manier om images
|
|
te pinnen en de manier van werken zijn voor beide apps dezelfde, en die stonden eerst in twee repo's naast
|
|
elkaar.
|
|
|
|
Wat dat vraagt:
|
|
|
|
- **elk plan hoort bij één app**, en dat staat in de kolom App van [CONTINUE_HERE.md](CONTINUE_HERE.md) en
|
|
in de kop van het plan zelf. De prioriteit loopt wél over beide heen: tier A is wat er nu moet gebeuren,
|
|
ongeacht welke app;
|
|
- **botst een plannaam, dan krijgt hij een achtervoegsel met de app**, en anders niet. Inleveren bij de
|
|
officiële store is per app, dus daar staan **Publicatie-Gate** en **Publicatie-Relay**. De rest houdt
|
|
gewoon zijn naam;
|
|
- **hetzelfde geldt voor `CHANGELOG`**, want `version` staat per manifest;
|
|
- **een referentie zegt voor wie hij is.** Sommige gelden voor beide apps, sommige voor één.
|
|
|
|
## Waar hoort iets
|
|
|
|
Twee vragen, in deze volgorde:
|
|
|
|
1. **Is het naslag** (geen status, hoort niet bij één plan, wordt niet per sessie bijgewerkt)? Dan
|
|
`Referenties/`.
|
|
2. **Anders is het een plan, en de status bepaalt de plek:** nog niet actief →
|
|
`Plannen/Masterplannen/<Naam>.PLAN.md`; er wordt aan gewerkt → `Plannen/Actief/NNN-<Naam>/`;
|
|
afgerond → `Plannen/Archief/<Naam>/`.
|
|
|
|
Twijfel? De test is: zit er werk aan vast dat ooit af moet zijn? Zo ja, dan is het een plan, ook als er
|
|
voorlopig niemand aan begint.
|
|
|
|
## Een plan begint als één bestand
|
|
|
|
Schrijf een nieuw plan als `Plannen/Masterplannen/<Naam>.PLAN.md`: doel, afbakening, niet-doelen, het
|
|
werk in grote lijnen, open punten. Pas als het werk écht begint, promoveer je het naar
|
|
`Plannen/Actief/NNN-<Naam>/` met de vier bestanden. De promotie-stappen staan in
|
|
`HomeGit/Docs/Werkproces.md` §1b.
|
|
|
|
Een masterplan heeft geen tier en geen nummer. Wat het wél kan hebben is een harde afhankelijkheid, en
|
|
die staat in de masterplannen-tabel van [CONTINUE_HERE.md](CONTINUE_HERE.md).
|
|
|
|
## Het nummer
|
|
|
|
`010-`, `020-`, in stappen van tien zodat er altijd een `015-` tussen kan. Drie cijfers. Het nummer is de
|
|
aanbevolen volgorde, **niet** de tier: die staat in de prioriteits-header van `TAKEN.md`.
|
|
|
|
**Het nummer bestaat op twee plekken: de mapnaam en `CONTINUE_HERE.md`.** Verwijs overal elders met de
|
|
naam van het plan: "zie het plan **Appstore**, `TAKEN.md` Fase 2". Binnen een plan link je relatief.
|
|
|
|
De reeks loopt over beide apps heen en is dus niet per app aaneengesloten. Dat is de bedoeling: er is één
|
|
volgorde van werken, niet twee.
|
|
|
|
## Sessie-protocol
|
|
|
|
**Starten:** `CONTINUE_HERE.md` → tier A → `Plannen/Actief/NNN-<Plan>/TAKEN.md` ("Volgende stap").
|
|
`PLAN.md` alleen bij twijfel over scope of ontwerp.
|
|
|
|
**Afsluiten:** `TAKEN.md` bijwerken, korte entry in `PROGRESS.md`, tier en de indexregel controleren,
|
|
gewijzigde bestanden opsommen.
|
|
|
|
## Projectspecifiek
|
|
|
|
**Alle documentatie staat hier, ook wat elders vaak in de root ligt.** In de repo-root blijft alleen
|
|
`README.md`, en die is geen documentatie maar de **voordeur**: Gitea toont hem op de repo-pagina, en dat
|
|
is voor een publieke app store het eerste wat iemand ziet. Hij hoort kort te blijven en door te verwijzen
|
|
naar deze map. De oude `ARCHITECTURE.md`, `STRUCTURE.md` en `QUICKSTART.md` uit de root zijn opgegaan in
|
|
[Referenties/Architectuur-huidig.md](Referenties/Architectuur-huidig.md); ze beschreven grotendeels
|
|
hetzelfde in drie versies.
|
|
|
|
**Er zijn drie testbestanden.** Twee gaan over Electrum Gate en noemen die app-map bij naam; het derde,
|
|
`tests/test_appstore_vorm.py`, gaat over de **store** en vindt zijn apps zelf, dus een derde app valt daar
|
|
automatisch onder. Hoe ze draaien staat in [../CLAUDE.md](../CLAUDE.md).
|
|
|
|
Dat derde bestand dekt precies de fouten die je op het apparaat pas merkt: `id` gelijk aan de mapnaam, het
|
|
store-voorvoegsel, de voorgeschreven veldvolgorde, een `app_proxy` die naar een bestaande service wijst, en
|
|
elke gemounte map die in de repo bestaat. Wat het **niet** doet is eisen dat elke `image:` een
|
|
`@sha256:`-digest heeft. Dat is wel de regel, maar geen van de twee apps haalt hem vandaag en een suite die
|
|
altijd rood staat wordt niet gelezen; het staat als taak in de plannen en de pinstatus wordt afgedrukt.
|
|
|
|
**"Gebouwd" en "werkend" liggen hier verder uit elkaar dan gebruikelijk.** Elk plan heeft daarom een
|
|
paragraaf Verificatie met de controles die **op de Umbrel zelf** gedaan moeten worden. Meld die uitslag,
|
|
inclusief wat er níet gecontroleerd is.
|
|
|
|
**De repo wordt publiek.** Dat is geen keuze maar een eis: umbreld kloont een community app store anoniem
|
|
en kan geen inloggegevens aanbieden. Houd daar rekening mee bij wat je opschrijft. Evolu Relay krijgt een
|
|
Postgres, en dan is er meer weg te houden dan bij Electrum Gate: geen wachtwoord in de compose, geen
|
|
`.env`, geen dump.
|
|
|
|
**Regeleindes zijn LF, afgedwongen door `.gitattributes`.** Dat is hier geen netheid: de configuratie
|
|
draait in een Linux-container, en een CRLF achter een `#!/bin/sh` laat een script stuklopen op een
|
|
foutmelding die nergens naar het echte probleem wijst.
|