edupage-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d88122f0b43b1dd402338602fa5ea159a965330816f0a5104bbc05ebc7032dde
+  data.tar.gz: 6c648935914a8e1c78da2ed253c3f625384a61af26442ac63ce027981cf8c73c
+SHA512:
+  metadata.gz: 0d533b61ff18ec78c95a8282e123cf4271eb554949277fed4391619a20b007e5c2b9dc5f7c9965ece0bb19971eff3ca73b403df894f69bc628c9022ee6a86592
+  data.tar.gz: 188a7210840c7f1263229aaf857c89fe080f6d7376c33d198d1707f956436faca839dc4e0ede25544242ef18c1192e4c866b591d3bdf772f89cd69c31233c506

data/README.md

@@ -0,0 +1,250 @@
+# 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.
+
+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.
+
+## Inštalácia
+
+```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.
+
+## Credentials
+
+Hľadajú sa v tomto poradí:
+
+| Poradie | Zdroj |
+|---|---|
+| 1 | `EDUPAGE_USERNAME`, `EDUPAGE_PASSWORD`, `EDUPAGE_SCHOOL` |
+| 2 | macOS keychain (service `edupage-cli`), cez `edupage login` |
+
+`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.
+
+Netajné nastavenia sú v `~/.config/edupage-cli/config.yml`, session a cache stránok
+v `~/.cache/edupage-cli/`.
+
+## Reťazec
+
+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í.
+
+```
+$ edupage students
+No school selected. Pick one:
+  --school zsdemo  Základná škola Demo
+  --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š.
+
+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ú:
+
+```
+$ edupage grades --school zsdemo --student Jana
+school  : zsdemo  (Základná škola Demo)
+student : Jana Nováková (4.A)
+year    : 2026/2027 (current)  [default]
+No records.
+Nothing here for 2026/2027 (current). Try --year 2025 (172), --year 2024 (116).
+```
+
+## CLI
+
+```bash
+edupage schools
+edupage students   --school zsdemo
+edupage timetable  --school zsdemo --student Jana --from 2026-09-21 --to 2026-09-25
+edupage homeworks  --school zsdemo --student Jana --due 2026-09-14
+edupage years      --school zsdemo --student Jana
+edupage grades     --school zsdemo --student Jana --year 2025 --term P1 --subject MAT
+edupage timeline   --school zsdemo --student Peter --type message
+```
+
+Globálne prepínače: `--school --student --year --username --json --yaml --no-cache
+--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.
+
+```
+$ edupage grades --school zsdemo --student Jana --year 2025
+school  : zsdemo  (Základná škola Demo)
+student : Jana Nováková (4.A)
+year    : 2025/2026
+┌──────────────────┬───────────────────────────────┬───────┬────────┬─────────────────────────┐
+│ created at       │ subject                       │ value │ weight │ title                   │
+├──────────────────┼───────────────────────────────┼───────┼────────┼─────────────────────────┤
+│ 2025-09-13 10:53 │ Slovenský jazyk a literatúra  │ 1     │ 1.0    │ Čítanie                 │
+│ 2025-09-20 08:16 │ Matematika                    │ 1     │ 1.0    │ Sčítanie a odčítanie    │
+│                  │                               │       │        │ do 20 bez prechodu      │
+└──────────────────┴───────────────────────────────┴───────┴────────┴─────────────────────────┘
+```
+
+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é.
+
+Servisné príkazy: `edupage auth`, `edupage session status|refresh|logout`,
+`edupage cache info|clear`, `edupage config path|get|set`.
+
+## Knižnica
+
+```ruby
+require "edupage"
+
+school = Edupage.account.school("zsdemo")
+jana = school.students.find_by(name: /Jana/)
+
+jana.timetable                                  # dnes
+jana.timetable(Date.today..Date.today + 6)      # týždeň
+jana.homeworks.where(subject: "SJL").order(:due_on)
+
+jana.years                                      # 2026 (aktuálny), 2025, 2024 ...
+jana.year(2025).grades.where(term: :P1, subject: "MAT")
+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.
+
+## Server
+
+```bash
+edupage server            # REST na /api/v1, MCP na /mcp
+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.
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "http://127.0.0.1:4567/api/v1/schools/zsdemo/students/Jana/years/2025/grades?term=P1"
+```
+
+### 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.
+
+```bash
+edupage mcp-add claude-code --scope user    # cez `claude mcp add`
+edupage mcp-add claude-desktop              # zlúči sa do claude_desktop_config.json
+edupage mcp-add all --scope user            # oboje
+edupage mcp-add all --dry-run               # ukáže, čo by spravil, nezmení nič
+edupage mcp-add all --http                  # zaregistruje HTTP endpoint namiesto stdio
+
+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
+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.
+
+Ani jeden variant nepripína školu ani študenta - to sú úrovne reťazca 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`.
+
+## Ako povrchy zostávajú v súlade
+
+Resources sú deklarované raz, v `lib/edupage/registry/resources.rb`:
+
+```ruby
+resource :grades do
+  scope   :year
+  summary "Grades for a school year"
+  param   :term, type: :enum, values: %w[P1 P2], desc: "Half-year"
+  resolve ->(year, p) { year.grades.where(term: p[:term]) }
+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
+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í.
+
+## 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.
+- **Čí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.
+
+## Vývoj
+
+```bash
+bundle exec rspec
+```
+
+Testy bežia proti ručne písaným payloadom, nie proti nahratým stránkam: 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
+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
+kmeň mena, takže zmiznú aj tvary ako `Janu` či `Kováčovej`, nielen základný tvar.
+
+Overiť sa to dá proti živému účtu:
+
+```bash
+EDUPAGE_LIVE_USERNAME=you@example.com EDUPAGE_LIVE_SCHOOL=yourschool \
+  bundle exec rspec spec/live_recording_spec.rb --tag live
+```
+
+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.
+
+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.
+
+## Rozsah
+
+Read-only, zámerne. Nič tu do Edupage 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/exe/edupage

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "edupage"
+require "edupage/cli"
+
+Edupage::CLI.start(ARGV)

data/lib/edupage/account.rb

@@ -0,0 +1,121 @@
+module Edupage
+  # The logged-in person, and the entry point to everything else.
+  #
+  # One set of credentials can reach several schools - a parent with children at two
+  # schools gets two entries from a single login, each with its own session - so an
+  # account owns a list of schools rather than being tied to one.
+  class Account
+    class << self
+      # Reuses stored sessions when they are still alive and only logs in when needed.
+      def login(username: nil, school: nil, credentials: nil, store: SessionStore.new, cache: nil)
+        credentials ||= Credentials.new(username: username, school: school)
+        username = credentials.username
+
+        sessions = restore(username, credentials, store)
+        sessions = authenticate(credentials, store) if sessions.empty?
+
+        new(username: username, sessions: sessions, credentials: credentials,
+            store: store, cache: cache)
+      end
+
+      private
+
+      # A dead session is renewed rather than dropped: sessions expire one school at a
+      # time, and dropping one would hide that school until all the others died too.
+      def restore(username, credentials, store)
+        store.all(username).filter_map do |origin, entry|
+          session = Session.new(
+            origin: origin, username: username, session_id: entry[:session_id],
+            credentials: credentials, userid: entry[:userid], role: entry[:role],
+            name: entry[:name], store: store
+          )
+          next session if session.valid?
+
+          Edupage.logger.debug("Stored session for #{origin} expired, logging in again")
+          renew(session, store)
+        end
+      end
+
+      # Only a school the account can no longer reach is dropped, and forgotten so it is
+      # not pinged again. A wrong password still raises.
+      #
+      # A school behind 2FA stays listed, so asking for its data names the real problem
+      # instead of "no such school"; the other schools must stay usable meanwhile.
+      def renew(session, store)
+        session.refresh!
+      rescue TwoFactorRequiredError
+        session
+      rescue SessionExpiredError
+        store.delete(session.username, session.origin)
+        nil
+      end
+
+      def authenticate(credentials, store)
+        anchor = credentials.school
+        unless anchor
+          raise MissingCredentialsError,
+                "No school to log in against. Pass --school, set EDUPAGE_SCHOOL, or set default_school."
+        end
+
+        Client.mauth(school: anchor, username: credentials.username, password: credentials.password)
+              .map do |entry|
+          Session.new(
+            origin: entry[:origin], username: credentials.username, session_id: entry[:session_id],
+            credentials: credentials, userid: entry[:userid], role: entry[:role],
+            name: [entry[:first_name], entry[:last_name]].compact.join(" "), store: store
+          ).tap(&:persist!)
+        end
+      end
+    end
+
+    attr_reader :username, :credentials
+
+    def initialize(username:, sessions:, credentials:, store: SessionStore.new, cache: nil)
+      @username = username
+      @sessions = sessions
+      @credentials = credentials
+      @store = store
+      @cache = cache
+    end
+
+    def schools
+      @schools ||= Relation.wrap(@sessions.map { |session| School.new(session, cache: cache) })
+    end
+
+    def cache = @cache ||= Cache.new
+
+    # One school is taken silently; several without a choice is refused.
+    #
+    # The config's default_school is not consulted here on purpose - it says where to log
+    # in, not which school's data to read. See Registry::Context.
+    def school(origin = nil)
+      if origin.nil?
+        raise AmbiguousScopeError.new(:school, school_candidates) if schools.count > 1
+
+        return schools.first || raise(NotFoundError, "#{username} has access to no schools")
+      end
+
+      schools.find { |school| school.matches?(origin) } or
+        raise NotFoundError,
+              "No school #{origin.inspect} for #{username}. Available: #{schools.map(&:origin).join(", ")}"
+    end
+
+    def school_candidates
+      schools.map { |school| { id: school.origin, label: school.name } }
+    end
+
+    # Taken from the login rather than any school page, so it works before any fetch.
+    def name = @sessions.map(&:name).compact.reject(&:empty?).first
+
+    def to_h
+      { username: username, name: name, schools: schools.map(&:origin) }
+    end
+
+    # Forgets the stored sessions. The keychain password is untouched.
+    def logout!
+      @store.delete(username)
+    end
+
+    def inspect = "#<Edupage::Account #{username.inspect} schools=#{@sessions.map(&:origin).inspect}>"
+  end
+end

data/lib/edupage/cache.rb

@@ -0,0 +1,101 @@
+require "fileutils"
+require "json"
+require "time"
+
+module Edupage
+  # File-backed cache for parsed Edupage payloads.
+  #
+  # Fetching is expensive in a way that matters here: one dashboard is ~375 KB and a
+  # single CLI invocation needs it before it can answer anything. Caching the parsed
+  # payload keyed by (school, year, child, resource) makes consecutive commands cheap.
+  #
+  # The year is part of the key because Edupage's directory changes between years - the
+  # class list for 2025 is genuinely different from 2026's - and the child is part of it
+  # because timetables are per-child.
+  #
+  # Anything from a finished school year never changes, so it is kept indefinitely;
+  # everything else gets a short TTL.
+  class Cache
+    FOREVER = Float::INFINITY
+
+    TTL = {
+      document: 3600,     # dashboard: directory, four days of timetable, the feed
+      znamky: 900,        # grades for the current year
+      timetable: 3600,    # an explicitly fetched date range
+      default: 900
+    }.freeze
+
+    attr_reader :root
+
+    def initialize(root: Config.cache_dir, enabled: true)
+      @root = root
+      @enabled = enabled
+    end
+
+    def enabled? = @enabled
+
+    def disable! = (@enabled = false)
+
+    # Reads a cached value or computes and stores it.
+    #
+    # `immutable: true` marks data from a closed school year, which is kept forever.
+    def fetch(*key, kind: :default, immutable: false, &block)
+      return block.call unless enabled?
+
+      path = path_for(key)
+      ttl = immutable ? FOREVER : TTL.fetch(kind, TTL[:default])
+
+      cached = read(path, ttl)
+      return cached if cached
+
+      block.call.tap { |value| write(path, value) }
+    end
+
+    def read(path, ttl)
+      return nil unless File.exist?(path)
+      return nil unless fresh?(path, ttl)
+
+      # Explicit UTF-8, never the locale's default: these payloads are full of Slovak
+      # names, and a process launched without LANG (an MCP client, a launchd job) gets
+      # US-ASCII as default_external, which makes every read of a cached page fail.
+      JSON.parse(File.read(path, encoding: Encoding::UTF_8))
+    rescue JSON::ParserError, Errno::ENOENT
+      nil
+    end
+
+    def write(path, value)
+      FileUtils.mkdir_p(File.dirname(path))
+      # Written via a temporary file so a concurrent reader never sees a half-written
+      # document; several processes share this directory.
+      temp = "#{path}.#{Process.pid}.tmp"
+      File.write(temp, JSON.generate(value), mode: "w:UTF-8")
+      File.rename(temp, path)
+      value
+    rescue SystemCallError => e
+      Edupage.logger.debug("Could not cache #{path}: #{e.message}")
+      value
+    end
+
+    def clear
+      FileUtils.rm_rf(Dir.glob(File.join(root, "*")))
+    end
+
+    def entries = Dir.glob(File.join(root, "**", "*.json"))
+
+    def path_for(key)
+      parts = key.flatten.compact.map { |part| sanitize(part) }
+      File.join(root, *parts[0..-2], "#{parts.last}.json")
+    end
+
+    private
+
+    def fresh?(path, ttl)
+      return true if ttl == FOREVER
+
+      Time.now - File.mtime(path) < ttl
+    end
+
+    # Ids can be negative and origins are hostnames; keep both filesystem-safe.
+    def sanitize(part) = part.to_s.gsub(/[^A-Za-z0-9_.-]/, "_")
+  end
+end

data/lib/edupage/cli/formatter.rb

@@ -0,0 +1,56 @@
+require "json"
+require "yaml"
+
+module Edupage
+  class CLI < Thor
+    # Renders a resolver result for a terminal.
+    #
+    # JSON and YAML go through Serializer, the same one the REST API and the MCP server
+    # use, so `--json` output is byte-identical across surfaces. The table view is the
+    # only thing unique to the CLI; Table draws it.
+    class Formatter
+      def initialize(output: $stdout, format: :table, width: nil)
+        @output = output
+        @format = format
+        @width = width || Table.terminal_width
+      end
+
+      def render(result, resource: nil)
+        case @format
+        when :json then @output.puts(JSON.pretty_generate(Serializer.call(result)))
+        when :yaml then @output.puts(YAML.dump(deep_stringify(Serializer.call(result))))
+        else render_table(result, resource)
+        end
+      end
+
+      private
+
+      def render_table(result, resource)
+        records = result.is_a?(Relation) || result.is_a?(Array) ? result.to_a : [result]
+        return @output.puts("No records.") if records.empty?
+
+        fields = resource&.table_fields
+        fields = default_fields(records.first) if fields.nil? || fields.empty?
+
+        rows = records.map { |record| fields.map { |f| Serializer.field(record, f).to_s } }
+        headers = fields.map { |f| Serializer.header(f) }
+        @output.puts(Table.boxed(headers, rows, width: @width))
+      end
+
+      # Falls back to whatever the object reports, for resources with no table_fields.
+      def default_fields(record)
+        return record.to_h.keys if record.respond_to?(:to_h)
+
+        [:to_s]
+      end
+
+      def deep_stringify(value)
+        case value
+        when Hash then value.to_h { |k, v| [k.to_s, deep_stringify(v)] }
+        when Array then value.map { |v| deep_stringify(v) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/edupage/cli/table.rb

@@ -0,0 +1,136 @@
+require "strings"
+require "tty-screen"
+require "tty-table"
+require "unicode/display_width"
+
+module Edupage
+  class CLI < Thor
+    # The one place tty-table is configured.
+    #
+    # Two shapes cover every aligned thing the CLI prints: #boxed for a result set
+    # (unicode frame, header row) and #plain for a short aligned list with no frame,
+    # such as the school/student/year block above a table.
+    #
+    # TTY::Table is always written out in full here - a bare `Table` inside this
+    # namespace is this module, not tty-table's.
+    module Table
+      # Below this a column carries no information, so shrinking stops there and the
+      # table is allowed to stay wider than the terminal.
+      MIN_COLUMN_WIDTH = 12
+
+      # One space of padding on each side of every column, inside the frame.
+      BOXED_PADDING = [0, 1].freeze
+
+      # The borderless renderer already separates columns with a single space, so its
+      # own padding would only make a label/value block airy.
+      PLAIN_PADDING = [0, 0].freeze
+
+      module_function
+
+      # A framed table with a header row.
+      def boxed(headers, rows, width: terminal_width)
+        # Unicode borders cost one vertical bar per column plus the closing one, on
+        # top of the two padding spaces each column already takes.
+        overhead = 3 * headers.size + 1
+        widths = fit(::TTY::Table.new(headers, rows), width, overhead)
+
+        table = ::TTY::Table.new(wrap(headers, widths), rows.map { |row| wrap(row, widths) })
+        table.render(:unicode, width: canvas(widths, overhead, width), column_widths: widths,
+                               multiline: true, padding: BOXED_PADDING)
+      end
+
+      # An aligned list with no border and no header: label/value pairs, candidate
+      # lists, anything that used to be built with ljust.
+      def plain(rows, width: terminal_width, indent: 0)
+        return "" if rows.empty?
+
+        # The null border draws nothing; the single space between columns is all there
+        # is on top of the content.
+        overhead = rows.first.size - 1
+        widths = fit(::TTY::Table.new(rows), width - indent, overhead)
+
+        table = ::TTY::Table.new(rows.map { |row| wrap(row, widths) })
+        rendered = table.render(:basic, width: canvas(widths, overhead, width - indent),
+                                        column_widths: widths,
+                                        multiline: true, padding: PLAIN_PADDING)
+
+        # Indented here rather than through the renderer's own :indent option, which
+        # only reaches the first line of a row and leaves wrapped continuations hanging
+        # to the left of the column they belong to.
+        #
+        # The renderer also pads the last column out to its full width; nothing follows
+        # it, so that is just trailing whitespace.
+        rendered.lines.map { |line| line.rstrip.empty? ? "" : "#{" " * indent}#{line.rstrip}" }
+                .join("\n")
+      end
+
+      def terminal_width = ::TTY::Screen.width
+
+      # Natural column widths, narrowed until the table fits the terminal.
+      #
+      # tty-table's own `resize: true` splits the width evenly between columns, which
+      # squeezes short ones like `value` and wraps their headers for no reason. The
+      # budget comes off the widest column instead: dates and marks stay whole and
+      # only the free-text column gives ground.
+      def fit(table, width, overhead)
+        widths = ::TTY::Table::Columns.widths_from(table)
+        budget = width - overhead
+
+        while widths.sum > budget
+          widest = widths.each_index.max_by { |index| widths[index] }
+          break if widths[widest] <= MIN_COLUMN_WIDTH
+
+          widths[widest] -= 1
+        end
+
+        widths
+      end
+
+      # The width handed to the renderer. Once every column is down to
+      # MIN_COLUMN_WIDTH the table can still be wider than the terminal - a timetable
+      # has six columns and a narrow window. Reporting the real total keeps it
+      # horizontal and lets the terminal wrap the overflow; a width it does not fit in
+      # makes tty-table flip the whole thing into vertical orientation and print a
+      # warning on stdout, which is worse and would end up in a pipe.
+      def canvas(widths, overhead, width) = [width, widths.sum + overhead].max
+
+      # Breaks the cells across lines before tty-table sees them, so the renderer has
+      # nothing left to wrap.
+      #
+      # strings 0.2.1, which tty-table wraps with, can return a line one character
+      # wider than asked for. In Strings::Wrap.format_line a word that ends exactly on
+      # the boundary leaves the line buffer empty; the space that follows it is then
+      # flushed as an empty line and glued onto the next word, which comes back out one
+      # character over - Strings.wrap("Slovenský jazyk", 9) gives "\nSlovenský \njazyk".
+      # Inside a frame that single character tears the border open.
+      #
+      # Wrapping one column short absorbs it: an overlong line still fits. That costs a
+      # character, so it is only done for the cells that actually trip the bug.
+      def wrap(cells, widths)
+        cells.each_with_index.map do |cell, index|
+          text = cell.to_s
+          width = widths[index]
+          next text if fits?(text, width)
+
+          lines = wrap_lines(text, width)
+          lines = wrap_lines(text, width - 1) if width > 1 && spoiled?(lines, width)
+          # The leading empty line the bug emits carries no content of its own.
+          lines.shift while lines.first&.empty?
+          lines.join("\n")
+        end
+      end
+
+      def wrap_lines(text, width) = ::Strings.wrap(text, width).lines.map(&:chomp)
+
+      def spoiled?(lines, width)
+        lines.first&.empty? || lines.any? { |line| ::Unicode::DisplayWidth.of(line) > width }
+      end
+
+      # A cell already inside its column is handed over untouched: the renderer has
+      # nothing to wrap, so it cannot widen it either.
+      def fits?(text, width)
+        text.lines.all? { |line| ::Unicode::DisplayWidth.of(line.chomp) <= width }
+      end
+    end
+  end
+end