edupage-cli 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d88122f0b43b1dd402338602fa5ea159a965330816f0a5104bbc05ebc7032dde
-  data.tar.gz: 6c648935914a8e1c78da2ed253c3f625384a61af26442ac63ce027981cf8c73c
+  metadata.gz: 121fd1c2fcc0aa186c79565930684a7bd169589616178ed763fdd742d5330926
+  data.tar.gz: 17a1e8c2205330a58eb1208e91948b445f643c4c9078b9a43e6d0e7ac1713099
 SHA512:
-  metadata.gz: 0d533b61ff18ec78c95a8282e123cf4271eb554949277fed4391619a20b007e5c2b9dc5f7c9965ece0bb19971eff3ca73b403df894f69bc628c9022ee6a86592
-  data.tar.gz: 188a7210840c7f1263229aaf857c89fe080f6d7376c33d198d1707f956436faca839dc4e0ede25544242ef18c1192e4c866b591d3bdf772f89cd69c31233c506
+  metadata.gz: 5147f956c0b5dcd81674676a3219adda32d453fda2d766ae2d3b8dd5573d809a4298a6e8c9f57ccb76e1bb4e16d5e3f44db60dd7aaf9e2cbb791f11e762f49b0
+  data.tar.gz: 19a1ec3e5a0b9e47883d5199ddbd81f0a9bf615b5618460cd601a1831a60387ca5ab44604439ff47ce4c772a27b2fb5e4a42b7b6e133947cd7d3c098f54e833e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Al Hafoudh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,44 +1,117 @@
 # edupage-cli
 
 Read-only prístup k účtu na [Edupage](https://www.edupage.org) - ako Ruby knižnica, CLI,
-REST API a MCP server. Všetky štyri povrchy stoja na tom istom kóde a drží ich v súlade
-parity test.
+REST API a MCP server. Všetky štyri rozhrania používajú rovnaký kód a ich zhodu
+stráži parity test.
 
-Edupage nemá verejné API. Každá stránka je server-rendered HTML s JSON-om zabaleným
-v `<script>` blokoch a session si navyše drží skryté kurzory "aktuálne dieťa" a
-"aktuálny školský rok", ktoré treba nastaviť skôr, než má fetch vôbec zmysel. Toto
-všetko rieši knižnica za teba.
+![edupage v termináli](docs/screenshot.png)
+
+Edupage nemá verejné API. Každá stránka je HTML vygenerované na serveri s JSON-om
+vloženým do blokov `<script>`. Session si navyše interne pamätá "aktuálne dieťa"
+a "aktuálny školský rok", ktoré treba nastaviť pred načítaním dát. Toto všetko
+rieši knižnica za teba.
 
 ## Inštalácia
 
+### Inštalácia jedným príkazom
+
+**macOS (funguje aj na Linuxe)**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/alhafoudh/edupage-cli/main/install.sh | sh
+```
+
+Skript použije Homebrew, ak je dostupný, inak nainštaluje gem cez Ruby 3.2 alebo novšie.
+Ak nie je dostupná ani jedna možnosť, skončí s pokynmi. Homebrew ani Ruby sám neinštaluje.
+
+**Windows (PowerShell)**
+
+```powershell
+irm https://raw.githubusercontent.com/alhafoudh/edupage-cli/main/install.ps1 | iex
+```
+
+Skript použije existujúce Ruby 3.2 alebo novšie. Ak Ruby nie je nainštalované vôbec,
+nainštaluje Ruby+Devkit 3.4 cez winget a nástroje MSYS2 na zostavovanie cez `ridk install`. Potom
+nainštaluje gem edupage-cli. Na Windows na ARM navyše nainštaluje libxml2/libxslt z MSYS2
+a zostaví s nimi nokogiri, pretože pre arm64 Windows nie je dostupný predkompilovaný gem.
+
+Potom sa prihlás cez `edupage login`. Heslo sa uloží do Správcu poverení Windows
+(Credential Manager). Prihlasovacie údaje môžeš nastaviť aj cez premenné prostredia:
+
+```powershell
+setx EDUPAGE_USERNAME "tvoje_pouzivatelske_meno"
+setx EDUPAGE_PASSWORD "tvoje_heslo"
+setx EDUPAGE_SCHOOL "tvoja_skola"
+```
+
+Po nastavení otvor nové okno terminálu, aby sa premenné načítali.
+
+edupage-cli si môžeš nainštalovať aj manuálne nasledujúcimi spôsobmi.
+
+### Ručná inštalácia
+
+Cez Homebrew na macOS aj Linuxe:
+
+```bash
+brew install alhafoudh/edupage/edupage-cli
+edupage login
+```
+
+Formula je v tape [alhafoudh/homebrew-edupage](https://github.com/alhafoudh/homebrew-edupage).
+Zostavuje sa zo zdrojového kódu označeného tagom, používa Ruby z Homebrew a gemy si
+ukladá oddelene, takže nezasahuje do ostatných inštalácií Ruby. Pri prvej inštalácii sa kompiluje zopár natívnych
+gemov (puma, nio4r), čo trvá pár desiatok sekúnd.
+
+Alebo ako gem, ak už Ruby 3.2+ máš:
+
+```bash
+gem install edupage-cli
+```
+
+Alebo priamo z checkoutu:
+
 ```bash
 bundle install
 bundle exec exe/edupage login
 ```
 
-`login` heslo najprv overí voči Edupage a až potom ho uloží do macOS keychainu, takže
-sa tam nikdy nedostane preklep.
+`login` najprv overí heslo prihlásením do Edupage a až potom ho uloží do úložiska
+hesiel operačného systému, takže heslo s preklepom neuloží.
 
-## Credentials
+## Prihlasovacie údaje
 
 Hľadajú sa v tomto poradí:
 
 | Poradie | Zdroj |
 |---|---|
 | 1 | `EDUPAGE_USERNAME`, `EDUPAGE_PASSWORD`, `EDUPAGE_SCHOOL` |
-| 2 | macOS keychain (service `edupage-cli`), cez `edupage login` |
+| 2 | `--username`, `--school`, potom `~/.config/edupage-cli/config.yml` (len meno a škola) |
+| 3 | úložisko hesiel systému, cez `edupage login` (len heslo) |
+
+Úložisko hesiel podľa systému:
+
+| Systém | Úložisko |
+|---|---|
+| macOS | keychain (service `edupage-cli`) |
+| Windows | Správca poverení, generic credential `edupage-cli:<meno>` |
+| Linux | Secret Service (GNOME Keyring, KWallet) cez `secret-tool`, atribúty `service=edupage-cli`, `account=<meno>` |
 
-`edupage auth` ukáže, ktorý zdroj sa práve používa, a upozorní, keď `EDUPAGE_PASSWORD`
-prekrýva heslo v keychaine - inak by to vyzeralo, že `edupage login` nič neurobil.
+Na Linuxe treba mať nainštalovaný `secret-tool` (balík `libsecret-tools` alebo `libsecret`)
+a bežiacu D-Bus session. Bez nich ostáva len `EDUPAGE_PASSWORD`.
 
-Netajné nastavenia sú v `~/.config/edupage-cli/config.yml`, session a cache stránok
+Keď je nastavená `EDUPAGE_PASSWORD`, úložisko hesiel sa vôbec nepoužije, ani sa do neho
+nenahliada. `edupage auth` ukáže, ktorý zdroj sa práve používa, a pri úložisku vtedy napíše
+`not consulted` - inak by to vyzeralo, že `edupage login` nič neurobil.
+
+Nastavenia bez citlivých údajov sú v `~/.config/edupage-cli/config.yml`, session a cache stránok
 v `~/.cache/edupage-cli/`.
 
-## Reťazec
+## Hierarchia výberu
 
-Všetko visí na `account > škola > študent > ročník` a žiadna úroveň sa nedá preskočiť.
-Každá sa rozhoduje rovnako: explicitný výber vyhráva, jediná možnosť sa vezme ticho,
-čokoľvek iné skončí chybou so zoznamom možností.
+Výber sa riadi hierarchiou `account > škola > študent > školský rok` a žiadna úroveň
+sa nedá preskočiť. Na každej úrovni platí rovnaké pravidlo: prednosť má explicitný
+výber, jediná možnosť sa vyberie automaticky a v ostatných prípadoch príkaz skončí
+chybou so zoznamom možností.
 
 ```
 $ edupage students
@@ -47,11 +120,12 @@ No school selected. Pick one:
   --school zusdemo Základná umelecká škola Demo
 ```
 
-Default v configu sa **za výber nepočíta**: `default_school` hovorí len to, na ktorý
-`*.edupage.org` host sa prihlásiť, nikdy nie to, čie dáta čítaš.
+Predvolená hodnota v configu sa **za výber nepočíta**: `default_school` určuje iba
+server `*.edupage.org`, na ktorý sa prihlásiť, nie to, čie dáta čítaš.
 
-Jedinou výnimkou je ročník - ten sa doplní na aktuálny, lebo "teraz" je jednoznačné.
-Výstup vždy povie, ktorý rok použil, a keď je prázdny, ukáže, kde dáta sú:
+Jedinou výnimkou je školský rok - automaticky sa vyberie aktuálny, lebo "teraz" je
+jednoznačné. Vo výstupe je vždy uvedené, ktorý rok sa použil, a ak preň nie sú žiadne
+dáta, výstup ukáže, v ktorých rokoch sú:
 
 ```
 $ edupage grades --school zsdemo --student Jana
@@ -78,8 +152,9 @@ Globálne prepínače: `--school --student --year --username --json --yaml --no-
 --verbose`. Meno študenta stačí zadať ako unikátny prefix, takže `--student Jana`
 postačuje.
 
-Tabuľkový výstup má hlavičku s tým, z akej školy, študenta a roka dáta pochádzajú;
-`--json` a `--yaml` ju nemajú, aby zostali bajt na bajt zhodné s REST a MCP odpoveďami.
+Tabuľkový výstup má hlavičku s údajmi o škole, študentovi a školskom roku. Výstupy
+`--json` a `--yaml` hlavičku nemajú, aby boli bajt po bajte zhodné s odpoveďami REST API
+a MCP.
 
 ```
 $ edupage grades --school zsdemo --student Jana --year 2025
@@ -95,8 +170,8 @@ year    : 2025/2026
 └──────────────────┴───────────────────────────────┴───────┴────────┴─────────────────────────┘
 ```
 
-Tabuľka sa prispôsobí šírke terminálu: keď sa nezmestí, uberá sa vždy najširšiemu
-stĺpcu a dlhý text sa zalomí, takže dátumy a známky zostanú celé.
+Tabuľka sa prispôsobí šírke terminálu: keď sa nezmestí, vždy sa zúži najširší
+stĺpec a dlhý text sa zalomí, takže dátumy a známky zostanú celé.
 
 Servisné príkazy: `edupage auth`, `edupage session status|refresh|logout`,
 `edupage cache info|clear`, `edupage config path|get|set`.
@@ -119,8 +194,9 @@ jana.grades                                     # skratka pre aktuálny rok
 ```
 
 Kolekcie sú lazy a reťaziteľné: `where order limit offset find_by first count`.
-`where(name: ...)` hľadá naprieč menom, skratkou aj id záznamu; každý iný kľúč porovnáva
-svoj atribút a berie hodnotu, regexp, range, pole alebo lambdu.
+`where(name: ...)` hľadá v mene, skratke aj id záznamu; pri ostatných kľúčoch sa
+porovnáva príslušný atribút. Ako podmienku možno zadať hodnotu, regulárny výraz, rozsah,
+pole alebo lambdu.
 
 ## Server
 
@@ -130,7 +206,7 @@ edupage mcp               # MCP cez stdio, pre editory a desktop klientov
 ```
 
 Počúva na `127.0.0.1` a pri prvom spustení si vygeneruje bearer token do configu.
-Všetky rúty sú `GET`, všetky MCP tooly sú označené ako read-only.
+Všetky trasy sú `GET`, všetky MCP tooly sú označené ako read-only.
 
 ```bash
 curl -H "Authorization: Bearer $TOKEN" \
@@ -140,7 +216,7 @@ curl -H "Authorization: Bearer $TOKEN" \
 ### Zapojenie MCP
 
 `edupage mcp-add` zaregistruje server u klienta, `edupage mcp-config` iba vypíše
-`mcpServers` záznam, keď si ho chceš umiestniť sám.
+záznam `mcpServers`, ak si ho chceš do configu pridať ručne.
 
 ```bash
 edupage mcp-add claude-code --scope user    # cez `claude mcp add`
@@ -153,26 +229,30 @@ edupage mcp-config                          # len JSON a nič iné
 edupage mcp-config --http
 ```
 
-Pridávanie je **idempotentné**: zhodný záznam nechá tak, odlišný zosúladí a chýbajúci
+Pridávanie je **idempotentné**: zhodný záznam ponechá, odlišný upraví a chýbajúci
 doplní. Config Claude Desktopu sa zlučuje, nie prepisuje - ostatné servery aj nesúvisiace
 nastavenia zostanú - a predošlá verzia sa odloží ako `.bak`.
 
-Pre lokálny nástroj je lepší default stdio: proces vlastní klient, takže netreba nič
-autentifikovať ani držať bežiaci server. `--http` mieri na `/mcp` bežiaceho
-`edupage server` a nesie token v `Authorization` hlavičke, čo sa hodí, keď jeden proces
-zdieľa viac klientov.
+Pre lokálny nástroj je lepšie predvolené stdio: proces spravuje klient, takže netreba
+riešiť autentifikáciu ani udržiavať server v chode. `--http` sa pripája na `/mcp`
+spusteného `edupage server` a posiela token v hlavičke `Authorization`, čo sa hodí, keď
+jeden proces zdieľa viac klientov.
 
-Ani jeden variant nepripína školu ani študenta - to sú úrovne reťazca a model si ich má
-zvoliť pri každom volaní.
+Ani jeden variant nenastavuje školu ani študenta napevno - sú to úrovne hierarchie
+a model si ich má zvoliť pri každom volaní.
 
-Vygenerovaný stdio záznam používa absolútne cesty a nastavuje `BUNDLE_GEMFILE`, lebo MCP
-klienti spúšťajú servery z vlastného pracovného adresára. A spúšťajú ich aj **bez
-nastaveného locale**, čo je dôvod, prečo každý súbor otvárame explicitne ako UTF-8
-a nie cez `Encoding.default_external`.
+Vygenerovaný stdio záznam používa absolútne cesty a pri behu z checkoutu nastavuje
+`BUNDLE_GEMFILE`, lebo MCP klienti spúšťajú servery z vlastného pracovného adresára.
+Pri inštalácii cez Homebrew ukazuje na `$(brew --prefix)/opt/edupage-cli/bin/edupage`,
+nie na verziovanú cestu v `Cellar`, takže záznam zostane platný aj po `brew upgrade`. Zariaďuje to
+premenná `EDUPAGE_EXECUTABLE`, ktorú nastavuje wrapper z formuly; rovnako ju môže
+použiť akýkoľvek iný balíčkovač. MCP klienti navyše spúšťajú servery aj **bez
+nastaveného locale**, preto každý súbor otvárame výslovne ako UTF-8 a nespoliehame sa
+na `Encoding.default_external`.
 
-## Ako povrchy zostávajú v súlade
+## Ako udržiavame rozhrania v súlade
 
-Resources sú deklarované raz, v `lib/edupage/registry/resources.rb`:
+Zdroje sú deklarované na jednom mieste, v `lib/edupage/registry/resources.rb`:
 
 ```ruby
 resource :grades do
@@ -183,31 +263,34 @@ resource :grades do
 end
 ```
 
-Z toho sa vygeneruje CLI príkaz, REST rúta aj MCP tool a `spec/registry_parity_spec.rb`
-spadne, ak niektorý chýba alebo sa mu rozídu parametre. Výstup `--json`, telo REST
+Z toho sa vygeneruje CLI príkaz, REST trasa aj MCP tool a `spec/registry_parity_spec.rb`
+spadne, ak niektorý z nich chýba alebo má odlišné parametre. Výstup `--json`, telo REST
 odpovede aj výsledok MCP toolu idú cez jeden serializer, takže sú bajt na bajt zhodné.
 
-`scope` zároveň deklaruje, na ktorých úrovniach reťazca resource stojí, takže ho všetky
-tri povrchy vynucujú rovnako: REST ich nesie ako segmenty cesty, MCP input schéma ich
-označí ako required a CLI odmietne so zoznamom možností.
+`scope` zároveň určuje, ktoré úrovne hierarchie zdroj vyžaduje, a všetky tri rozhrania
+ich vyžadujú rovnako: v REST sú súčasťou cesty, vstupná schéma MCP ich označí ako povinné
+a CLI príkaz bez nich odmietne a vypíše zoznam možností.
 
 ## Poznámky k samotnému Edupage
 
-Veci, ktoré stojí za to vedieť - všetky overené proti živému účtu:
-
-- **Jeden login môže pokrývať viac škôl.** `mauth` vráti jednu session na každú školu.
-- **Session drží aktuálne dieťa a aktuálny školský rok.** Prepnutie ktoréhokoľvek z nich
-  je side effect na zdieľanom stave servera, takže prebieha pod file lockom a každá
-  odpoveď sa kontroluje proti tomu, čo sa pýtalo.
-- **Tieto prepnutia zaostávajú.** Edupage prepnutie potvrdí okamžite, ale ešte request
-  alebo dva servíruje stránku predošlého dieťaťa či roka, takže sa fetch opakuje, kým sa
-  stránka nezhoduje. Vrátiť zaostávajúcu stránku by potichu znamenalo rozvrh iného dieťaťa.
+Veci, ktoré stojí za to vedieť - všetky overené na živom účte:
+
+- **Jedným účtom sa dá prihlásiť do viacerých škôl.** `mauth` vráti jednu session na
+  každú školu.
+- **Session drží aktuálne dieťa a aktuálny školský rok.** Prepnutie dieťaťa aj roka mení
+  zdieľaný stav na serveri, preto prebieha pod súborovým zámkom a pri každej odpovedi sa
+  overuje, či zodpovedá požadovanému dieťaťu a roku.
+- **Prepnutie sa prejaví s oneskorením.** Edupage prepnutie potvrdí okamžite, ale ešte
+  request alebo dva vracia stránku predošlého dieťaťa či roka, takže sa fetch opakuje,
+  kým stránka nesedí. Ak by sa vrátila neaktuálna stránka, dostal by si bez upozornenia
+  rozvrh iného dieťaťa.
 - **Číselníky sa medzi rokmi menia.** Zoznam tried za 2025 nie je ten istý ako za 2026,
   preto je rok súčasťou každého cache kľúča.
 - **Timeline je spoločná pre všetky deti rodiča** a delí sa lokálne podľa mapy
   `childGroups`.
-- **Domáce úlohy majú dva tvary** - zadané triede alebo jednému žiakovi. Treba oba: na
-  účte, na ktorom to vzniklo, je 15 zo 16 úloh jedného dieťaťa toho druhého druhu.
+- **Domáce úlohy sa zadávajú buď celej triede, alebo jednotlivým žiakom.** Treba
+  podporovať oba prípady: na účte, na ktorom to vzniklo, je 15 zo 16 úloh jedného
+  dieťaťa zadaných individuálne.
 
 ## Vývoj
 
@@ -215,16 +298,16 @@ Veci, ktoré stojí za to vedieť - všetky overené proti živému účtu:
 bundle exec rspec
 ```
 
-Testy bežia proti ručne písaným payloadom, nie proti nahratým stránkam: tie skutočné
+Testy používajú ručne pripravené payloady, nie uložené stránky: tie skutočné
 majú stovky kilobajtov a sú v nich mená cudzích detí.
 
 Keby predsa len vznikla VCR kazeta, `spec/support/cassette_scrubber.rb` z nej pred
-zápisom na disk vyhádže osobné údaje - mená, názvy škôl, subdomény aj e-maily, a to
-v tele odpovede, v URI aj v hlavičkách. Mená nezoberie z pevného zoznamu, ale **z odpovede
-samotnej** - z polí, kam ich Edupage vždy dáva - a potom nahradí každý ich výskyt vrátane
+zápisom na disk odstráni osobné údaje - mená, názvy škôl, subdomény aj e-maily, a to
+v tele odpovede, v URI aj v hlavičkách. Mená neberie z pevného zoznamu, ale **priamo
+z odpovede** - z polí, kam ich Edupage vždy dáva - a potom nahradí každý ich výskyt vrátane
 tých vo voľnom texte správ. Pseudonym je odvodený z pôvodnej hodnoty, takže ten istý
-človek je v každej kazete ten istý vymyslený človek a krížové odkazy v payloade
-zostanú platné; späť sa z toho dostať nedá. Keďže slovenčina skloňuje, hľadá sa aj
+človek má v každej kazete rovnaký pseudonym a vzájomné odkazy v payloade zostanú
+platné; pôvodnú hodnotu sa z pseudonymu spätne získať nedá. Keďže slovenčina skloňuje, hľadá sa aj
 kmeň mena, takže zmiznú aj tvary ako `Janu` či `Kováčovej`, nielen základný tvar.
 
 Overiť sa to dá proti živému účtu:
@@ -237,14 +320,26 @@ EDUPAGE_LIVE_USERNAME=you@example.com EDUPAGE_LIVE_SCHOOL=yourschool \
 Ten test si zoznam mien, ktoré sa v kazete nesmú objaviť, **načíta zo živého účtu**, nie
 z ručne napísaného zoznamu - spadne teda aj vtedy, keď pribudne spolužiak alebo druhá
 škola, ktorú scrubber nevie nájsť. Zároveň kontroluje, že sa kazeta uložila ako čitateľný
-text: Edupage servíruje stránky gzipnuté a komprimované telo by prešlo každou kontrolou
-na meno, hoci by v ňom boli všetky.
+text: Edupage posiela stránky gzipnuté a kontrola mien by v komprimovanom tele nič
+nenašla, hoci by v ňom všetky mená zostali.
+
+CI beží na Ruby 3.2 až 4.0 na Linuxe, macOS a Windows. Každý adapter úložiska hesiel sa
+testuje proti skutočnému úložisku na svojom systéme: macOS job si vytvorí vlastný odomknutý
+keychain, Linux job spustí gnome-keyring v D-Bus session a Windows job použije Správcu
+poverení. Na ostatných systémoch sa tieto testy preskočia.
+
+### Vydanie
 
-CI beží na Ruby 3.2, 3.3 a 3.4 na Linuxe, plus jeden macOS job, ktorý si vytvorí vlastný
-odomknutý keychain, aby sa keychain testy naozaj spustili a nepreskočili.
+Vydanie spustí zmena `Edupage::VERSION` v `lib/edupage/version.rb`. Keď CI na `main`
+prejde, release workflow pushne gem na rubygems.org, vytvorí tag a GitHub release
+a nakoniec aktualizuje formulu v tape
+[alhafoudh/homebrew-edupage](https://github.com/alhafoudh/homebrew-edupage) na nový tag
+(cez deploy key v secrete `HOMEBREW_TAP_DEPLOY_KEY`). Tap má vlastné CI, ktoré formulu
+postaví a otestuje na macOS (arm64, Intel) aj Linuxe (x64, arm64). Každý krok je
+idempotentný, takže zlyhaný beh stačí spustiť znova.
 
 ## Rozsah
 
-Read-only, zámerne. Nič tu do Edupage nezapisuje - žiadne odpovede na správy, žiadne
+Zámerne iba na čítanie. Do Edupage sa nič nezapisuje - žiadne odpovede na správy, žiadne
 označovanie úloh za hotové, žiadne podpisovanie známok. `spec/registry_parity_spec.rb`
 aj samostatný CI job overujú, že sa v `lib/` neobjaví write endpoint.

data/lib/edupage/account.rb

@@ -111,7 +111,7 @@ module Edupage
       { username: username, name: name, schools: schools.map(&:origin) }
     end
 
-    # Forgets the stored sessions. The keychain password is untouched.
+    # Forgets the stored sessions. The stored password is untouched.
     def logout!
       @store.delete(username)
     end

data/lib/edupage/cli.rb

@@ -45,11 +45,11 @@ module Edupage
 
     # --- credentials -------------------------------------------------------------------
 
-    desc "login", "Verify credentials and store the password in the macOS keychain"
+    desc "login", "Verify credentials and store the password in the OS credential store"
     method_option :username, type: :string, desc: "Edupage login (email)"
     method_option :stdin, type: :boolean, desc: "Read the password from stdin instead of prompting"
     def login
-      keychain = require_keychain!
+      store = require_system_adapter!
       username = options[:username] || Edupage.config.default_username ||
                  ask("Username (email):")
       school = options[:school] || Edupage.config.default_school || ask("School (e.g. zsdemo):")
@@ -57,23 +57,26 @@ module Edupage
 
       raise Error, "No password given" if password.empty?
 
-      # Verified before it is stored, so a typo never ends up in the keychain.
+      # Verified before it is stored, so a typo never ends up in the store.
       users = Client.mauth(school: school, username: username, password: password)
-      keychain.store(username: username, password: password)
+      store.store(username: username, password: password)
 
-      say "Stored password for #{username}."
+      say "Stored password for #{username} in the #{store.display_name}."
       say "Schools: #{users.map { |u| u[:origin] }.join(", ")}"
       remember_defaults(username, school)
+      return unless Credentials.new.password_from_env?
+
+      say "EDUPAGE_PASSWORD is set and wins over the stored password until you unset it.", :yellow
     end
 
-    desc "logout", "Remove the stored password from the keychain"
+    desc "logout", "Remove the stored password from the OS credential store"
     method_option :username, type: :string
     def logout
-      keychain = require_keychain!
+      store = require_system_adapter!
       username = options[:username] || Edupage.config.default_username or
         raise MissingCredentialsError, "No username; pass --username."
 
-      say(keychain.delete(username: username) ? "Removed password for #{username}." : "Nothing stored for #{username}.")
+      say(store.delete(username: username) ? "Removed password for #{username}." : "Nothing stored for #{username}.")
       say "Session cache is separate; use `edupage session logout` to drop it.", :yellow
     end
 
@@ -87,12 +90,8 @@ module Edupage
                         auth_row("school", safe { credentials.school }, credentials.school_source),
                         auth_row("password", credentials.password_source ? "(set)" : "(missing)",
                                  credentials.password_source),
-                        auth_row("keychain", keychain_status(username), nil)
+                        auth_row("credential store", credential_store_status(credentials, username), nil)
                       ])
-
-      return unless credentials.password_shadowed?
-
-      say "EDUPAGE_PASSWORD is set and overrides the keychain entry.", :yellow
     end
 
     # --- session and cache ---------------------------------------------------------------
@@ -115,7 +114,7 @@ module Edupage
         say "Logged in again: #{account.schools.map(&:origin).join(", ")}"
       when "logout"
         store.delete(username)
-        say "Dropped stored sessions for #{username}. The keychain password is untouched."
+        say "Dropped stored sessions for #{username}. The stored password is untouched."
       else
         raise Error, "Unknown session subcommand #{subcommand.inspect}"
       end
@@ -310,12 +309,9 @@ module Edupage
                     format: options[:json] ? :json : (options[:yaml] ? :yaml : :table))
     end
 
-    def require_keychain!
-      unless Credentials::Keychain.available?
-        raise Thor::Error, "The macOS keychain is unavailable on #{RUBY_PLATFORM}; use EDUPAGE_PASSWORD."
-      end
-
-      Credentials::Keychain.new
+    def require_system_adapter!
+      Credentials.system_adapter or
+        raise Thor::Error, "No OS credential store is available on #{RUBY_PLATFORM}; use EDUPAGE_PASSWORD."
     end
 
     def ask_password
@@ -375,8 +371,10 @@ module Edupage
       }
     end
 
+    # Packagers that run edupage through a wrapper (the Homebrew formula) name the
+    # stable entry point here, so the registered path survives upgrades.
     def executable_path
-      File.expand_path($PROGRAM_NAME)
+      ENV["EDUPAGE_EXECUTABLE"] || File.expand_path($PROGRAM_NAME)
     end
 
     def bundler_gemfile
@@ -523,11 +521,17 @@ module Edupage
       "'#{part.gsub("'", %q('\''))}'"
     end
 
-    def keychain_status(username)
-      return "unavailable on #{RUBY_PLATFORM}" unless Credentials::Keychain.available?
-      return "available (service edupage-cli), but no username to look up" unless username
+    # Reads the outcome off the password resolution instead of asking the store again,
+    # so with EDUPAGE_PASSWORD set the store is never touched.
+    def credential_store_status(credentials, username)
+      return "not consulted (EDUPAGE_PASSWORD set)" if credentials.password_from_env?
+
+      adapter = Credentials.system_adapter
+      return "unavailable on #{RUBY_PLATFORM}" unless adapter
+      return "#{adapter.display_name}, but no username to look up" unless username
 
-      Credentials::Keychain.new.stored?(username: username) ? "stored for #{username}" : "nothing stored for #{username}"
+      stored = credentials.password_source == adapter.source_for(:password)
+      "#{adapter.display_name}, #{stored ? "stored" : "nothing stored"} for #{username}"
     end
 
     def auth_row(label, value, source)

data/lib/edupage/credentials/adapter.rb

@@ -0,0 +1,34 @@
+module Edupage
+  class Credentials
+    # Common interface of every credential source.
+    #
+    # Credentials asks adapters in a fixed order and stops at the first value, so an
+    # adapter only ever runs when every adapter before it came up empty. A source that
+    # does not hold a field just returns nil for it.
+    class Adapter
+      class << self
+        def available?
+          raise NotImplementedError, "#{name}.available? is not implemented"
+        end
+
+        def display_name
+          raise NotImplementedError, "#{name}.display_name is not implemented"
+        end
+      end
+
+      def display_name = self.class.display_name
+
+      def username(**) = nil
+      def school(**) = nil
+      def password(**) = nil
+
+      # Whether `edupage login` can store a password here.
+      def writable? = false
+
+      # Label shown by `edupage auth` next to a value this adapter supplied.
+      def source_for(_field)
+        raise NotImplementedError, "#{self.class.name}#source_for is not implemented"
+      end
+    end
+  end
+end

data/lib/edupage/credentials/adapters/env.rb

@@ -0,0 +1,36 @@
+module Edupage
+  class Credentials
+    module Adapters
+      # Highest-priority source: plain environment variables. Whatever it supplies wins,
+      # and nothing after it is consulted for that field.
+      class Env < Adapter
+        VARS = {
+          username: "EDUPAGE_USERNAME",
+          password: "EDUPAGE_PASSWORD",
+          school: "EDUPAGE_SCHOOL"
+        }.freeze
+
+        class << self
+          def available? = true
+          def display_name = "environment"
+        end
+
+        def initialize(env = ENV)
+          super()
+          @env = env
+        end
+
+        def username(**) = @env[VARS[:username]]
+        def password(**) = @env[VARS[:password]]
+
+        # Accepts either "zsdemo" or "zsdemo.edupage.org".
+        def school(**)
+          value = @env[VARS[:school]]
+          value&.sub(/\.edupage\.org\z/, "")
+        end
+
+        def source_for(field) = "ENV: #{VARS[field]}"
+      end
+    end
+  end
+end

data/lib/edupage/credentials/adapters/macos_keychain.rb

@@ -0,0 +1,87 @@
+require "open3"
+require "rbconfig"
+
+module Edupage
+  class Credentials
+    module Adapters
+      # The macOS keychain, driven through /usr/bin/security.
+      #
+      # The password is never passed in argv (where `ps` would expose it). `security`
+      # reads it from stdin instead, prompting twice, so writes send the value twice.
+      #
+      # `security add-generic-password` exits 0 even when the two reads disagree, storing
+      # an empty password - which is what the read-back in SystemAdapter#store catches.
+      class MacosKeychain < SystemAdapter
+        SECURITY = "/usr/bin/security".freeze
+        # Runs a command in a new session, without a controlling terminal. macOS ships no
+        # setsid(1), so Ruby itself does the setsid before exec.
+        DETACH = [RbConfig.ruby, "-e", "Process.setsid; exec(*ARGV)"].freeze
+
+        class << self
+          def available?
+            RUBY_PLATFORM.include?("darwin") && File.executable?(SECURITY)
+          end
+
+          def display_name = "macOS keychain"
+        end
+
+        def source_for(_field) = "keychain"
+
+        private
+
+        def read(username)
+          # -g, not -w: for non-ASCII passwords `-w` prints bare hex, which is
+          # indistinguishable from an ASCII password that happens to look like hex
+          # ("deadbeef"). -g prefixes the hex form with 0x, so it can be told apart.
+          _out, err, status = Open3.capture3(
+            SECURITY, "find-generic-password", "-s", service, "-a", username, "-g"
+          )
+          return nil unless status.success?
+
+          parse_password(err)
+        end
+
+        def write(username, secret)
+          # -w last with no value: `security` prompts on stdin rather than taking argv.
+          # It prefers /dev/tty over stdin when it has a terminal, so it runs detached
+          # from ours; otherwise it would ignore stdin_data and prompt the user instead.
+          _out, err, status = Open3.capture3(
+            *DETACH, SECURITY, "add-generic-password", "-s", service, "-a", username,
+            "-l", "#{service} (#{username})", "-U", "-w",
+            stdin_data: "#{secret}\n#{secret}\n"
+          )
+          raise Error, "Failed to store password in keychain: #{err.strip}" unless status.success?
+        end
+
+        def remove(username)
+          _out, _err, status = Open3.capture3(
+            SECURITY, "delete-generic-password", "-s", service, "-a", username
+          )
+          status.success?
+        end
+
+        # `security -g` writes one of these to stderr:
+        #   password: "plain-ascii"
+        #   password: 0x73336372  "s3cr3t-\303\241"
+        # The hex form is exact bytes, so it is preferred whenever present.
+        def parse_password(stderr)
+          line = stderr.lines.find { |l| l.start_with?("password:") }
+          return nil unless line
+
+          if (hex = line[/password: 0x([0-9A-Fa-f]+)/, 1])
+            [hex].pack("H*").force_encoding(Encoding::UTF_8)
+          elsif (quoted = line[/password: "(.*)"\s*\z/m, 1])
+            unescape(quoted)
+          end
+        end
+
+        def unescape(str)
+          str.gsub(/\\(\d{3}|.)/) do
+            esc = Regexp.last_match(1)
+            esc.match?(/\A\d{3}\z/) ? esc.to_i(8).chr : esc
+          end.force_encoding(Encoding::UTF_8)
+        end
+      end
+    end
+  end
+end

data/lib/edupage/credentials/adapters/secret_service.rb

@@ -0,0 +1,60 @@
+require "open3"
+
+module Edupage
+  class Credentials
+    module Adapters
+      # The freedesktop Secret Service (GNOME Keyring, KWallet), driven through
+      # `secret-tool` from libsecret.
+      #
+      # Entries carry the attributes service=<service> and account=<username>. The
+      # password goes in on stdin, never in argv; with a pipe rather than a terminal on
+      # stdin, `secret-tool store` reads it verbatim instead of prompting.
+      #
+      # Without a D-Bus session (a plain SSH login, a container) lookups fail; that reads
+      # as "nothing stored" so ENV-less runs still get the usual missing-password hint.
+      class SecretService < SystemAdapter
+        class << self
+          def available?
+            RUBY_PLATFORM.include?("linux") && !executable.nil?
+          end
+
+          def display_name = "Secret Service (libsecret)"
+
+          def executable
+            ENV.fetch("PATH", "").split(File::PATH_SEPARATOR)
+               .map { |dir| File.join(dir, "secret-tool") }
+               .find { |path| File.executable?(path) }
+          end
+        end
+
+        def source_for(_field) = "secret service"
+
+        private
+
+        def attributes(username) = ["service", service, "account", username]
+
+        def read(username)
+          # Prints the secret as-is, without a trailing newline when stdout is a pipe.
+          out, _err, status = Open3.capture3(self.class.executable, "lookup", *attributes(username))
+          status.success? ? out.force_encoding(Encoding::UTF_8) : nil
+        end
+
+        def write(username, secret)
+          _out, err, status = Open3.capture3(
+            self.class.executable, "store", "--label", "#{service} (#{username})", *attributes(username),
+            stdin_data: secret
+          )
+          raise Error, "Failed to store password in #{display_name}: #{err.strip}" unless status.success?
+        end
+
+        # `secret-tool clear` exits 0 whether or not anything matched, so whether there
+        # was something to remove is checked first.
+        def remove(username)
+          existed = stored?(username: username)
+          Open3.capture3(self.class.executable, "clear", *attributes(username))
+          existed
+        end
+      end
+    end
+  end
+end

data/lib/edupage/credentials/adapters/windows_credential_manager.rb

@@ -0,0 +1,127 @@
+module Edupage
+  class Credentials
+    module Adapters
+      # Windows Credential Manager, called through advapi32 with Fiddle.
+      #
+      # Windows ships no command that reads a stored password back (cmdkey only writes
+      # one), so this talks to the Cred* API directly: no subprocess, and the password
+      # never appears in argv.
+      #
+      # Entries are generic credentials named "<service>:<username>". The blob holds the
+      # password as UTF-8 bytes; Credential Manager treats it as opaque.
+      class WindowsCredentialManager < SystemAdapter
+        CRED_TYPE_GENERIC = 1
+        CRED_PERSIST_LOCAL_MACHINE = 2
+
+        class << self
+          def available? = Gem.win_platform?
+          def display_name = "Windows Credential Manager"
+
+          # Built on first use, so Fiddle is never loaded on other platforms or when ENV
+          # already supplied the password.
+          def api
+            @api ||= begin
+              require "fiddle/import"
+
+              Module.new do
+                extend Fiddle::Importer
+
+                dlload "advapi32.dll"
+                extern "int CredReadW(void*, uint32_t, uint32_t, void*)"
+                extern "int CredWriteW(void*, uint32_t)"
+                extern "int CredDeleteW(void*, uint32_t, uint32_t)"
+                extern "void CredFree(void*)"
+              end
+            end
+          end
+
+          # CREDENTIALW. FILETIME is two DWORDs; Fiddle works out the padding before
+          # each pointer, so the layout matches on both x64 and arm64.
+          def credential
+            @credential ||= api.struct([
+                                         "uint32_t flags",
+                                         "uint32_t type",
+                                         "void* target_name",
+                                         "void* comment",
+                                         "uint32_t last_written_low",
+                                         "uint32_t last_written_high",
+                                         "uint32_t blob_size",
+                                         "void* blob",
+                                         "uint32_t persist",
+                                         "uint32_t attribute_count",
+                                         "void* attributes",
+                                         "void* target_alias",
+                                         "void* user_name"
+                                       ])
+          end
+        end
+
+        def source_for(_field) = "credential manager"
+
+        def target_name(username) = "#{service}:#{username}"
+
+        private
+
+        # Each entry point fetches the API first: that is what requires Fiddle, so it has
+        # to happen before any other Fiddle constant is touched.
+        def read(username)
+          api = self.class.api
+          slot = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP, Fiddle::RUBY_FREE)
+          return nil if api.CredReadW(wide(target_name(username)), CRED_TYPE_GENERIC, 0, slot).zero?
+
+          address = slot.ptr.to_i
+          begin
+            entry = self.class.credential.new(address)
+            Fiddle::Pointer.new(entry.blob.to_i)[0, entry.blob_size].force_encoding(Encoding::UTF_8)
+          ensure
+            api.CredFree(address)
+          end
+        end
+
+        def write(username, secret)
+          api = self.class.api
+          # Locals keep the buffers alive until CredWriteW has copied them.
+          target = wide(target_name(username))
+          user = wide(username)
+          blob = secret.b
+
+          entry = self.class.credential.malloc(Fiddle::RUBY_FREE)
+          entry.flags = 0
+          entry.type = CRED_TYPE_GENERIC
+          entry.target_name = target.to_i
+          entry.comment = 0
+          entry.last_written_low = 0
+          entry.last_written_high = 0
+          entry.blob_size = blob.bytesize
+          entry.blob = Fiddle::Pointer[blob].to_i
+          entry.persist = CRED_PERSIST_LOCAL_MACHINE
+          entry.attribute_count = 0
+          entry.attributes = 0
+          entry.target_alias = 0
+          entry.user_name = user.to_i
+
+          return unless api.CredWriteW(entry.to_ptr, 0).zero?
+
+          raise Error, "Failed to store password in #{display_name} (Win32 error #{Fiddle.win32_last_error})"
+        end
+
+        # Whether there is anything to remove is checked up front rather than read off
+        # ERROR_NOT_FOUND (1168): on Windows arm64 with Ruby 4.0, Fiddle reports the last error
+        # as 0 after a failed CredDeleteW.
+        def remove(username)
+          return false unless stored?(username: username)
+
+          api = self.class.api
+          return true unless api.CredDeleteW(wide(target_name(username)), CRED_TYPE_GENERIC, 0).zero?
+
+          raise Error, "Failed to remove password from #{display_name} (Win32 error #{Fiddle.win32_last_error.inspect})"
+        end
+
+        # A NUL-terminated UTF-16LE copy of +str+, as the W functions expect.
+        def wide(str)
+          Fiddle::Pointer["#{str}\0".encode(Encoding::UTF_16LE)]
+        end
+      end
+    end
+  end
+end

data/lib/edupage/credentials/system_adapter.rb

@@ -0,0 +1,78 @@
+module Edupage
+  class Credentials
+    # Base for the operating system's own credential stores. They hold only the
+    # password, keyed by service and username; username and school come from ENV,
+    # flags or config.
+    #
+    # Subclasses implement the private #read, #write and #remove. Everything that has to
+    # hold for every store - no lookups where the store does not exist, no empty
+    # passwords, a read-back after every write - lives here.
+    class SystemAdapter < Adapter
+      SERVICE = "edupage-cli".freeze
+
+      attr_reader :service
+
+      def initialize(service: SERVICE)
+        super()
+        @service = service
+      end
+
+      def writable? = true
+
+      def password(username: nil, **)
+        return nil if username.nil? || username.empty?
+        return nil unless self.class.available?
+
+        value = read(username)
+        value && !value.empty? ? value : nil
+      end
+
+      def store(username:, password:)
+        ensure_available!
+        secret = password.to_s
+        raise ArgumentError, "password must not be empty" if secret.empty?
+
+        write(username, secret)
+
+        # Stores can report success and still persist something else (see
+        # MacosKeychain), so a write only counts once it reads back intact.
+        unless password(username: username) == secret
+          raise Error, "#{display_name} reported success but stored a different password"
+        end
+
+        true
+      end
+
+      # True when something was stored and is now gone.
+      def delete(username:)
+        ensure_available!
+        remove(username)
+      end
+
+      def stored?(username:)
+        !password(username: username).nil?
+      end
+
+      private
+
+      def read(_username)
+        raise NotImplementedError, "#{self.class.name}#read is not implemented"
+      end
+
+      def write(_username, _secret)
+        raise NotImplementedError, "#{self.class.name}#write is not implemented"
+      end
+
+      def remove(_username)
+        raise NotImplementedError, "#{self.class.name}#remove is not implemented"
+      end
+
+      def ensure_available!
+        return if self.class.available?
+
+        raise UnsupportedPlatformError,
+              "The #{display_name} is not available on #{RUBY_PLATFORM}. Use EDUPAGE_PASSWORD instead."
+      end
+    end
+  end
+end

data/lib/edupage/credentials.rb

@@ -1,25 +1,39 @@
 module Edupage
-  # Resolves username / password / school from an ordered list of providers.
+  # Resolves username / password / school from credential adapters.
   #
-  # ENV always wins over the keychain. That ordering is deliberate but surprising
-  # (an `edupage login` looks like a no-op while EDUPAGE_PASSWORD is exported), so
-  # #password_source is reported by `edupage auth status`.
+  # ENV wins over everything. When it supplies a value nothing else is consulted, and the
+  # operating system's credential store in particular is never touched: no keychain
+  # prompt, no subprocess, no FFI load. That store is looked up lazily and only as the
+  # last resort for the password. Username and school fall back to --username/--school
+  # and then config instead.
   class Credentials
     Resolved = Struct.new(:value, :source, keyword_init: true)
 
+    # Tried in order; the first one available on this machine is the system store.
+    SYSTEM_ADAPTERS = [
+      Adapters::MacosKeychain,
+      Adapters::WindowsCredentialManager,
+      Adapters::SecretService
+    ].freeze
+
+    class << self
+      # The credential store of this operating system, or nil when there is none.
+      def system_adapter
+        SYSTEM_ADAPTERS.find(&:available?)&.new
+      end
+    end
+
     attr_reader :username_override, :school_override
 
-    def initialize(username: nil, school: nil, providers: nil, config: Edupage.config)
+    # +system+ is a callable rather than an adapter so that building Credentials never
+    # touches the store; it is called at most once, and only when ENV has no password.
+    def initialize(username: nil, school: nil, env: Adapters::Env.new,
+                   system: -> { Credentials.system_adapter }, config: Edupage.config)
       @username_override = username
       @school_override = school
       @config = config
-      @providers = providers || default_providers
-    end
-
-    def default_providers
-      [Credentials::Env.new].tap do |list|
-        list << Credentials::Keychain.new if Credentials::Keychain.available?
-      end
+      @env = env
+      @system = system
     end
 
     def username
@@ -41,20 +55,9 @@ module Edupage
     def password_source = resolved_password.source
     def school_source   = resolved_school.source
 
-    # True when ENV supplies the password while a lower-priority provider also holds
-    # one, i.e. a stored password is being silently shadowed. Providers are compared by
-    # the source they report rather than by class, so any provider chain works.
-    def password_shadowed?
-      winning = resolved_password.source
-      return false unless winning&.start_with?("ENV:")
-
-      user = resolved_username.value
-      @providers.any? do |provider|
-        next false if provider.source_for(:password) == winning
-
-        value = provider.password(username: user)
-        value && !value.empty?
-      end
+    # True when ENV supplies the password, i.e. the system store is not consulted.
+    def password_from_env?
+      !from(@env, :password).nil?
     end
 
     def to_h
@@ -68,37 +71,39 @@ module Edupage
     private
 
     def resolved_username
-      @resolved_username ||= begin
-        from_providers(:username) ||
-          wrap(@username_override, "--username") ||
-          wrap(@config.default_username, "config") ||
-          Resolved.new(value: nil, source: nil)
-      end
+      @resolved_username ||=
+        from(@env, :username) ||
+        wrap(@username_override, "--username") ||
+        wrap(@config.default_username, "config") ||
+        Resolved.new(value: nil, source: nil)
     end
 
     def resolved_password
       @resolved_password ||=
-        from_providers(:password, username: resolved_username.value) ||
+        from(@env, :password) ||
+        from(system_adapter, :password, username: resolved_username.value) ||
         Resolved.new(value: nil, source: nil)
     end
 
     def resolved_school
-      @resolved_school ||= begin
-        from_providers(:school) ||
-          wrap(@school_override, "--school") ||
-          wrap(@config.default_school, "config") ||
-          Resolved.new(value: nil, source: nil)
-      end
+      @resolved_school ||=
+        from(@env, :school) ||
+        wrap(@school_override, "--school") ||
+        wrap(@config.default_school, "config") ||
+        Resolved.new(value: nil, source: nil)
     end
 
-    # An override beats a lower-priority provider but never beats ENV, so overrides are
-    # only consulted after the provider chain comes up empty.
-    def from_providers(field, **args)
-      @providers.each do |provider|
-        value = provider.public_send(field, **args)
-        return Resolved.new(value: value, source: provider.source_for(field)) if value && !value.empty?
-      end
-      nil
+    def system_adapter
+      return @system_adapter if defined?(@system_adapter)
+
+      @system_adapter = @system.call
+    end
+
+    def from(adapter, field, **args)
+      return nil unless adapter
+
+      value = adapter.public_send(field, **args)
+      Resolved.new(value: value, source: adapter.source_for(field)) if value && !value.empty?
     end
 
     def wrap(value, source)
@@ -108,10 +113,10 @@ module Edupage
     end
 
     def missing_password_message
-      if Credentials::Keychain.available?
-        "No password. Run `edupage login`, or set EDUPAGE_PASSWORD."
+      if (adapter = system_adapter)
+        "No password. Run `edupage login` to store it in the #{adapter.display_name}, or set EDUPAGE_PASSWORD."
       else
-        "No password and the macOS keychain is unavailable on this platform. Set EDUPAGE_PASSWORD."
+        "No password and no OS credential store is available on #{RUBY_PLATFORM}. Set EDUPAGE_PASSWORD."
       end
     end
   end

data/lib/edupage/version.rb

@@ -1,3 +1,3 @@
 module Edupage
-  VERSION = "0.1.0".freeze
+  VERSION = "0.2.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: edupage-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ahmed Al Hafoudh
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: mcp
   requirement: !ruby/object:Gem::Requirement
@@ -130,6 +144,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
 - exe/edupage
 - lib/edupage.rb
@@ -141,8 +156,12 @@ files:
 - lib/edupage/client.rb
 - lib/edupage/config.rb
 - lib/edupage/credentials.rb
-- lib/edupage/credentials/env.rb
-- lib/edupage/credentials/keychain.rb
+- lib/edupage/credentials/adapter.rb
+- lib/edupage/credentials/adapters/env.rb
+- lib/edupage/credentials/adapters/macos_keychain.rb
+- lib/edupage/credentials/adapters/secret_service.rb
+- lib/edupage/credentials/adapters/windows_credential_manager.rb
+- lib/edupage/credentials/system_adapter.rb
 - lib/edupage/errors.rb
 - lib/edupage/model.rb
 - lib/edupage/models/assignment.rb

data/lib/edupage/credentials/env.rb

@@ -1,27 +0,0 @@
-module Edupage
-  class Credentials
-    # Highest-priority provider: plain environment variables.
-    class Env
-      VARS = {
-        username: "EDUPAGE_USERNAME",
-        password: "EDUPAGE_PASSWORD",
-        school: "EDUPAGE_SCHOOL"
-      }.freeze
-
-      def initialize(env = ENV)
-        @env = env
-      end
-
-      def username(**) = @env[VARS[:username]]
-      def password(**) = @env[VARS[:password]]
-
-      # Accepts either "zsdemo" or "zsdemo.edupage.org".
-      def school(**)
-        value = @env[VARS[:school]]
-        value&.sub(/\.edupage\.org\z/, "")
-      end
-
-      def source_for(field) = "ENV: #{VARS[field]}"
-    end
-  end
-end

data/lib/edupage/credentials/keychain.rb

@@ -1,120 +0,0 @@
-require "open3"
-require "rbconfig"
-
-module Edupage
-  class Credentials
-    # Secondary provider: the macOS keychain, driven through /usr/bin/security.
-    #
-    # The password is never passed in argv (where `ps` would expose it). `security`
-    # reads it from stdin instead, prompting twice, so writes send the value twice.
-    #
-    # `security add-generic-password` exits 0 even when the two reads disagree, storing
-    # an empty password - so #store always reads the value back before reporting success.
-    class Keychain
-      SERVICE = "edupage-cli".freeze
-      SECURITY = "/usr/bin/security".freeze
-      # Runs a command in a new session, without a controlling terminal. macOS ships no
-      # setsid(1), so Ruby itself does the setsid before exec.
-      DETACH = [RbConfig.ruby, "-e", "Process.setsid; exec(*ARGV)"].freeze
-
-      class << self
-        def available?
-          RUBY_PLATFORM.include?("darwin") && File.executable?(SECURITY)
-        end
-      end
-
-      def initialize(service: SERVICE)
-        @service = service
-      end
-
-      # Only the password lives in the keychain; the other fields come from ENV or config.
-      def username(**) = nil
-      def school(**) = nil
-
-      def password(username: nil, **)
-        return nil if username.nil? || username.empty?
-        return nil unless self.class.available?
-
-        # -g, not -w: for non-ASCII passwords `-w` prints bare hex, which is
-        # indistinguishable from an ASCII password that happens to look like hex
-        # ("deadbeef"). -g prefixes the hex form with 0x, so it can be told apart.
-        _out, err, status = Open3.capture3(
-          SECURITY, "find-generic-password", "-s", @service, "-a", username, "-g"
-        )
-        return nil unless status.success?
-
-        value = parse_password(err)
-        value && !value.empty? ? value : nil
-      end
-
-      def store(username:, password:)
-        ensure_available!
-        secret = password.to_s
-        raise ArgumentError, "password must not be empty" if secret.empty?
-
-        # -w last with no value: `security` prompts on stdin rather than taking argv.
-        # It prefers /dev/tty over stdin when it has a terminal, so it runs detached
-        # from ours; otherwise it would ignore stdin_data and prompt the user instead.
-        _out, err, status = Open3.capture3(
-          *DETACH, SECURITY, "add-generic-password", "-s", @service, "-a", username,
-          "-l", "#{@service} (#{username})", "-U", "-w",
-          stdin_data: "#{secret}\n#{secret}\n"
-        )
-        raise Error, "Failed to store password in keychain: #{err.strip}" unless status.success?
-
-        # Guard against the silent-empty-write path described above.
-        unless password(username: username) == secret
-          raise Error, "Keychain reported success but stored a different password"
-        end
-
-        true
-      end
-
-      def delete(username:)
-        ensure_available!
-
-        _out, _err, status = Open3.capture3(
-          SECURITY, "delete-generic-password", "-s", @service, "-a", username
-        )
-        status.success?
-      end
-
-      def stored?(username:)
-        !password(username: username).nil?
-      end
-
-      def source_for(_field) = "keychain"
-
-      private
-
-      # `security -g` writes one of these to stderr:
-      #   password: "plain-ascii"
-      #   password: 0x73336372  "s3cr3t-\303\241"
-      # The hex form is exact bytes, so it is preferred whenever present.
-      def parse_password(stderr)
-        line = stderr.lines.find { |l| l.start_with?("password:") }
-        return nil unless line
-
-        if (hex = line[/password: 0x([0-9A-Fa-f]+)/, 1])
-          [hex].pack("H*").force_encoding(Encoding::UTF_8)
-        elsif (quoted = line[/password: "(.*)"\s*\z/m, 1])
-          unescape(quoted)
-        end
-      end
-
-      def unescape(str)
-        str.gsub(/\\(\d{3}|.)/) do
-          esc = Regexp.last_match(1)
-          esc.match?(/\A\d{3}\z/) ? esc.to_i(8).chr : esc
-        end.force_encoding(Encoding::UTF_8)
-      end
-
-      def ensure_available!
-        return if self.class.available?
-
-        raise UnsupportedPlatformError,
-              "The macOS keychain is not available on #{RUBY_PLATFORM}. Use EDUPAGE_PASSWORD instead."
-      end
-    end
-  end
-end