edupage-cli 0.1.0

data/lib/edupage/server/api.rb

@@ -0,0 +1,113 @@
+require "json"
+require "sinatra/base"
+
+module Edupage
+  module Server
+    # REST API and MCP endpoint.
+    #
+    # Routes are generated from Registry: the path comes from the resource's scope and
+    # the query parameters from its declared filters, so a resource reachable from the
+    # CLI is reachable here with the same name and the same options. Everything is GET;
+    # this tool never writes to Edupage.
+    class API < Sinatra::Base
+      configure do
+        set :show_exceptions, false
+        set :raise_errors, false
+        set :logging, false
+        # Sinatra 4 rejects unexpected Host headers by default. What actually limits
+        # exposure here is the bind address (loopback unless asked otherwise) plus the
+        # bearer token, and the default list breaks reverse proxies and test clients
+        # for no gain, so host checking is left off deliberately.
+        set :host_authorization, { permitted_hosts: [] }
+      end
+
+      class << self
+        attr_accessor :account_options, :mcp_server
+      end
+
+      before do
+        content_type :json
+        next if request.path_info == "/healthz"
+
+        halt(401, error_body("Unauthorized: send Authorization: Bearer <token>")) unless Auth.authorized?(request)
+      end
+
+      get "/healthz" do
+        content_type :json
+        JSON.generate(status: "ok", version: VERSION)
+      end
+
+      # One route per resource, with the path shape dictated by the scope.
+      Registry.each do |resource|
+        get resource.rest_path do
+          records = resolve(resource)
+          payload = Serializer.call(records)
+
+          JSON.pretty_generate(
+            data: payload,
+            meta: {
+              resource: resource.name,
+              count: payload.is_a?(Array) ? payload.size : 1
+            }
+          )
+        end
+      end
+
+      # MCP over HTTP, so `edupage server` covers both surfaces.
+      %i[get post delete].each do |verb|
+        public_send(verb, "/mcp") do
+          transport = self.class.mcp_server&.http_transport
+          halt(503, error_body("MCP is not enabled on this server")) unless transport
+
+          status, headers, body = transport.handle_request(request)
+          headers.each { |key, value| response.headers[key] = value }
+          halt(status, Array(body).join)
+        end
+      end
+
+      # Error blocks set the status and return the body; halting from inside one
+      # bypasses Sinatra's own response handling and yields the wrong status.
+      # A level of the chain was left unspecified. The path normally makes that
+      # impossible, but the answer still has to say what could have been chosen.
+      error AmbiguousScopeError do
+        error = env["sinatra.error"]
+        status 400
+        JSON.generate(error: error.message, level: error.level, candidates: error.candidates)
+      end
+
+      error NotFoundError do
+        status 404
+        error_body(env["sinatra.error"].message)
+      end
+
+      error MissingCredentialsError, LoginError, SessionExpiredError do
+        status 401
+        error_body(env["sinatra.error"].message)
+      end
+
+      error Edupage::Error do
+        status 500
+        error_body(env["sinatra.error"].message)
+      end
+
+      private
+
+      def resolve(resource)
+        merged = self.class.account_options.to_h.merge(symbolize(params))
+        context = Registry::Context.new(
+          account: Edupage.account(username: merged[:username], school: merged[:school]),
+          school: merged[:school], student: merged[:student], year: merged[:year]
+        )
+        resource.call(context, merged)
+      end
+
+      def symbolize(hash)
+        hash.to_h { |key, value| [key.to_sym, value] }
+      end
+
+      def error_body(message)
+        JSON.generate(error: message)
+      end
+    end
+  end
+end

data/lib/edupage/server/auth.rb

@@ -0,0 +1,45 @@
+module Edupage
+  module Server
+    # Bearer-token check for the HTTP surfaces.
+    #
+    # The server hands out a child's school record, so it binds to localhost and
+    # requires a token by default. Binding anywhere else has to be asked for explicitly.
+    module Auth
+      LOOPBACK = %w[127.0.0.1 ::1 localhost].freeze
+
+      module_function
+
+      def token = Edupage.config.server_token
+
+      def loopback?(host) = LOOPBACK.include?(host.to_s)
+
+      # Refuses to expose the account to a network without a deliberate choice.
+      def check_binding!(host)
+        return if loopback?(host)
+
+        Edupage.logger.warn(
+          "Binding to #{host} makes this account reachable from the network; a token is required."
+        )
+      end
+
+      def authorized?(request)
+        presented = bearer(request) || request.params["token"]
+        return false if presented.nil? || presented.empty?
+
+        secure_compare(presented, token)
+      end
+
+      def bearer(request)
+        header = request.env["HTTP_AUTHORIZATION"].to_s
+        header[/\ABearer\s+(.+)\z/i, 1]
+      end
+
+      # Constant-time comparison; a token check that returns early leaks its prefix.
+      def secure_compare(left, right)
+        return false unless left.bytesize == right.bytesize
+
+        left.bytes.zip(right.bytes).reduce(0) { |result, (a, b)| result | (a ^ b) }.zero?
+      end
+    end
+  end
+end

data/lib/edupage/server/mcp.rb

@@ -0,0 +1,107 @@
+require "mcp"
+
+module Edupage
+  module Server
+    # MCP server exposing the same resources as the CLI and the REST API.
+    #
+    # Tools are generated from Registry, so the tool list, its arguments and their types
+    # cannot diverge from the other surfaces. Every tool is read-only and says so, which
+    # lets clients skip approval prompts.
+    class MCP
+      SERVER_NAME = "edupage".freeze
+
+      INSTRUCTIONS = <<~TEXT.freeze
+        Read-only access to an Edupage school account: schools, students, timetables,
+        homework, and grades.
+
+        Most data belongs to one student and one school year. Call edupage_students to
+        find the students, and edupage_years to find which years hold data - in early
+        autumn the current year is usually empty and the interesting grades are in the
+        previous one. Pass `student` as a name or id and `year` as e.g. 2025.
+      TEXT
+
+      def initialize(account_options: {})
+        @account_options = account_options
+      end
+
+      def server
+        @server ||= ::MCP::Server.new(
+          name: SERVER_NAME,
+          title: "Edupage",
+          version: VERSION,
+          instructions: INSTRUCTIONS,
+          tools: tools
+        )
+      end
+
+      # Blocks, serving MCP on stdin/stdout for editors and desktop clients.
+      def run_stdio
+        ::MCP::Server::Transports::StdioTransport.new(server).open
+      end
+
+      # Rack entry point for the /mcp endpoint of `edupage server`.
+      def http_transport
+        @http_transport ||= ::MCP::Server::Transports::StreamableHTTPTransport.new(
+          server,
+          stateless: true,
+          enable_json_response: true
+        )
+      end
+
+      def handle_http(request) = http_transport.handle_request(request)
+
+      def tools
+        Registry.all.map { |resource| build_tool(resource) }
+      end
+
+      private
+
+      def build_tool(resource)
+        options = @account_options
+
+        ::MCP::Tool.define(
+          name: resource.tool_name,
+          title: resource.name.to_s.tr("_", " ").capitalize,
+          description: describe(resource),
+          input_schema: input_schema(resource),
+          annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
+        ) do |**arguments|
+          MCP.respond(resource, arguments, options)
+        end
+      end
+
+      # Runs a resource and wraps the result the way MCP expects. Kept as a module
+      # method so the tool blocks stay tiny and testable.
+      def self.respond(resource, arguments, account_options)
+        params = account_options.merge(arguments.transform_keys(&:to_sym))
+        context = Registry::Context.new(
+          account: Edupage.account(username: params[:username], school: params[:school]),
+          school: params[:school], student: params[:student], year: params[:year]
+        )
+        payload = Serializer.call(resource.call(context, params))
+
+        ::MCP::Tool::Response.new([{ type: "text", text: JSON.pretty_generate(payload) }])
+      rescue Edupage::Error => e
+        ::MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.message}" }], error: true)
+      end
+
+      def describe(resource)
+        scope_note =
+          case resource.scope
+          when :year then " Needs a student; year defaults to the current one."
+          when :student then " Needs a student."
+          else ""
+          end
+
+        "#{resource.summary}.#{scope_note}"
+      end
+
+      def input_schema(resource)
+        properties = resource.all_params.to_h { |param| [param.name.to_s, param.json_schema] }
+        required = resource.all_params.select(&:required).map { |p| p.name.to_s }
+
+        { type: "object", properties: properties, required: required }
+      end
+    end
+  end
+end

data/lib/edupage/server.rb

@@ -0,0 +1,57 @@
+module Edupage
+  # `edupage server`: the REST API and the MCP endpoint in one process.
+  module Server
+    DEFAULT_HOST = "127.0.0.1".freeze
+    DEFAULT_PORT = 4567
+
+    module_function
+
+    def start(host: nil, port: nil, token: nil, account_options: {})
+      require "puma"
+      require "rack"
+
+      host ||= Edupage.config.server["host"] || DEFAULT_HOST
+      port = (port || Edupage.config.server["port"] || DEFAULT_PORT).to_i
+
+      if token
+        Edupage.config["server"] = Edupage.config.server.merge("token" => token)
+        Edupage.config.save
+      end
+
+      Auth.check_binding!(host)
+      resolved_token = Auth.token
+
+      API.account_options = account_options
+      API.mcp_server = MCP.new(account_options: account_options)
+
+      announce(host, port, resolved_token)
+      run(API, host: host, port: port)
+    end
+
+    def run(app, host:, port:)
+      server = Puma::Server.new(app)
+      server.add_tcp_listener(host, port)
+      trap("INT") { server.stop }
+      trap("TERM") { server.stop }
+      server.run.join
+    end
+
+    def announce(host, port, token)
+      base = "http://#{host}:#{port}"
+      $stderr.puts <<~BANNER
+        edupage #{VERSION}
+
+          REST   #{base}/api/v1/...
+          MCP    #{base}/mcp
+          health #{base}/healthz
+
+          token  #{token}
+
+        Example:
+          curl -H "Authorization: Bearer #{token}" #{base}/api/v1/schools
+
+        Stored in #{Edupage.config.path}. Ctrl-C to stop.
+      BANNER
+    end
+  end
+end

data/lib/edupage/session.rb

@@ -0,0 +1,166 @@
+module Edupage
+  # A live connection to one Edupage school.
+  #
+  # Two things make this more than a cookie holder:
+  #
+  # 1. Re-login. Sessions expire server-side; any request can come back as a redirect
+  #    to /login/. #request notices that, logs in again and retries once.
+  #
+  # 2. Cursors. Edupage keeps the "current child" and "current school year" in the
+  #    session, not in the request, so asking for Jana's 2025 grades means mutating
+  #    shared server state first. #with_cursor does that under a cross-process lock.
+  class Session
+    SWITCH_CHILD_PATH = "/login/switchchild".freeze
+    SET_YEAR_PATH = "/znamky/?what=setyear".freeze
+    PING_PATH = "/login/eauth?portalping".freeze
+
+    attr_reader :origin, :username, :userid, :role, :name
+
+    def initialize(origin:, username:, session_id: nil, credentials:, userid: nil, role: nil,
+                   name: nil, store: SessionStore.new, client: nil)
+      @origin = origin
+      @username = username
+      @credentials = credentials
+      @store = store
+      @userid = userid
+      @role = role
+      @name = name
+      @client = client || Client.new(origin: origin, session_id: session_id)
+
+      # Cursor state is only trustworthy while we hold the lock, since another process
+      # sharing this session can switch it at any time. #release_lock clears it.
+      @cursor = { child: nil, year: nil }
+      @lock_depth = 0
+    end
+
+    def session_id = @client.session_id
+
+    def get(path) = request(:get, path)
+    def post(path, data = {}) = request(:post, path, data)
+
+    def parent? = role.to_s.downcase.start_with?("rodic")
+
+    # Cheap liveness check: 49 bytes, versus 375 KB for /user/.
+    def valid?
+      !@client.post(PING_PATH, "gpids" => "").expired?
+    end
+
+    # Logs in again and persists the new session id.
+    def refresh!
+      users = Client.mauth(school: origin, username: username, password: @credentials.password)
+      entry = users.find { |u| u[:origin] == origin }
+      raise SessionExpiredError, "Account #{username} no longer has access to #{origin}" unless entry
+      raise TwoFactorRequiredError, origin if entry[:needs_2fa]
+
+      @client.session_id = entry[:session_id]
+      @userid = entry[:userid]
+      @role = entry[:role]
+      @name = [entry[:first_name], entry[:last_name]].compact.join(" ")
+      persist!
+      # A fresh session starts with the server's own defaults, not ours.
+      @cursor = { child: nil, year: nil }
+      self
+    end
+
+    # Runs the block with the session pointing at the given child and/or school year.
+    #
+    # Holds an exclusive lock for the whole block - not just the switch - so a
+    # concurrent process cannot move the cursor between our switch and our fetch, which
+    # would silently return another child's or another year's data.
+    #
+    # Re-entrant: nested calls reuse the held lock and skip switches that are already
+    # in effect.
+    def with_cursor(child: nil, year: nil)
+      with_lock do
+        # Setting the second cursor can trigger a re-login, which resets the first one
+        # server-side. Re-apply until both actually hold before handing over control.
+        2.times do
+          set_child(child) if child
+          set_year(year) if year
+          break if cursors_match?(child, year)
+        end
+
+        unless cursors_match?(child, year)
+          raise Error, "Could not pin session #{origin} to child=#{child.inspect} year=#{year.inspect}"
+        end
+
+        yield self
+      end
+    end
+
+    def current_child = @cursor[:child]
+    def current_year = @cursor[:year]
+
+    def persist!
+      @store.store(username, origin, session_id: session_id, userid: userid, role: role, name: name)
+    end
+
+    def inspect
+      "#<Edupage::Session origin=#{origin.inspect} username=#{username.inspect} role=#{role.inspect}>"
+    end
+
+    private
+
+    def cursors_match?(child, year)
+      (child.nil? || @cursor[:child] == child.to_s) &&
+        (year.nil? || @cursor[:year] == year.to_s)
+    end
+
+    def with_lock(&block)
+      return yield if @lock_depth.positive?
+
+      @store.with_lock do
+        @lock_depth += 1
+        begin
+          block.call
+        ensure
+          @lock_depth -= 1
+          # Outside the lock another process may move the cursors, so what we knew
+          # about them expires with the lock.
+          @cursor = { child: nil, year: nil } if @lock_depth.zero?
+        end
+      end
+    end
+
+    def set_child(student_id)
+      id = student_id.to_s
+      return if @cursor[:child] == id
+
+      response = get("#{SWITCH_CHILD_PATH}?studentid=#{id}")
+      unless response.ok? && response.body.to_s.strip.start_with?("OK")
+        raise Error, "Failed to switch to child #{id} (HTTP #{response.status})"
+      end
+
+      @cursor[:child] = id
+    end
+
+    def set_year(year_id)
+      id = year_id.to_s
+      return if @cursor[:year] == id
+
+      response = post(SET_YEAR_PATH, "znamky_yearid" => id)
+      # The endpoint echoes the year it actually selected. That echo is the only
+      # trustworthy confirmation: /user/ reports the new selectedYear immediately most
+      # of the time, but occasionally lags a request behind (Edupage runs several app
+      # servers and the dashboard appears to be cached per server). Consumers that care
+      # about the year of a document - /user/ carries year-dependent dbi - must check
+      # it themselves and refetch; see School#document.
+      selected = response.body.to_s.strip.delete('"')
+      raise Error, "Failed to switch to year #{id} (HTTP #{response.status})" unless response.ok?
+      raise Error, "Edupage selected year #{selected} instead of #{id}" unless selected == id
+
+      @cursor[:year] = selected
+    end
+
+    def request(method, path, data = nil, retried: false)
+      response = data.nil? ? @client.get(path) : @client.post(path, data)
+      return response unless response.expired?
+
+      raise SessionExpiredError, "Session for #{origin} expired and re-login did not help" if retried
+
+      Edupage.logger.debug("Session for #{origin} expired, logging in again")
+      refresh!
+      request(method, path, data, retried: true)
+    end
+  end
+end

data/lib/edupage/session_store.rb

@@ -0,0 +1,131 @@
+require "fileutils"
+require "json"
+require "time"
+
+module Edupage
+  # Persists one Edupage session id per (username, school) so consecutive commands
+  # reuse a session instead of logging in again.
+  #
+  # The file holds live session ids, so it is created 0600 and every read-modify-write
+  # runs under an exclusive flock - `edupage server` and a CLI invocation routinely run
+  # at the same time.
+  class SessionStore
+    FILENAME = "sessions.json".freeze
+
+    attr_reader :path
+
+    def initialize(path: self.class.default_path)
+      @path = path
+    end
+
+    def self.default_path
+      File.join(Config.cache_dir, FILENAME)
+    end
+
+    def fetch(username, origin)
+      data = read
+      entry = data.dig(username.to_s, origin.to_s)
+      return nil unless entry && entry["session_id"]
+
+      symbolize(entry)
+    end
+
+    def all(username)
+      read.fetch(username.to_s, {}).transform_values { |e| symbolize(e) }
+    end
+
+    def store(username, origin, session_id:, userid: nil, role: nil, name: nil)
+      transaction do |data|
+        data[username.to_s] ||= {}
+        data[username.to_s][origin.to_s] = {
+          "session_id" => session_id,
+          "userid" => userid,
+          "role" => role,
+          "name" => name,
+          "saved_at" => Time.now.iso8601
+        }.compact
+      end
+    end
+
+    # Removes one school's session, or every session for the user when origin is nil.
+    def delete(username, origin = nil)
+      transaction do |data|
+        if origin
+          data[username.to_s]&.delete(origin.to_s)
+          data.delete(username.to_s) if data[username.to_s]&.empty?
+        else
+          data.delete(username.to_s)
+        end
+      end
+    end
+
+    def clear
+      transaction { |data| data.clear }
+    end
+
+    # Exclusive advisory lock used by Session#with_cursor. The server-side cursors
+    # (current child, current year) are global to a session, so two processes sharing a
+    # session must not interleave a switch with someone else's fetch.
+    def with_lock
+      FileUtils.mkdir_p(File.dirname(lock_path))
+      File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |file|
+        file.flock(File::LOCK_EX)
+        begin
+          yield
+        ensure
+          file.flock(File::LOCK_UN)
+        end
+      end
+    end
+
+    def lock_path = "#{path}.lock"
+
+    private
+
+    def read
+      return {} unless File.exist?(path)
+
+      # UTF-8 explicitly: the stored display name can contain diacritics, and a process
+      # started without LANG would otherwise read it as US-ASCII and fail to parse.
+      content = File.read(path, encoding: Encoding::UTF_8)
+      return {} if content.strip.empty?
+
+      JSON.parse(content)
+    rescue JSON::ParserError
+      # A truncated file is a cache, not a source of truth - start over rather than
+      # making every command fail.
+      Edupage.logger.warn("Discarding unreadable session store at #{path}")
+      {}
+    end
+
+    def transaction
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, File::RDWR | File::CREAT, 0o600) do |file|
+        file.set_encoding(Encoding::UTF_8)
+        file.flock(File::LOCK_EX)
+        begin
+          raw = file.read
+          data = raw.strip.empty? ? {} : (JSON.parse(raw) rescue {})
+          yield data
+          file.rewind
+          file.write(JSON.pretty_generate(data))
+          file.flush
+          file.truncate(file.pos)
+          data
+        ensure
+          file.flock(File::LOCK_UN)
+        end
+      end
+    end
+
+    def symbolize(entry)
+      {
+        session_id: entry["session_id"],
+        userid: entry["userid"],
+        role: entry["role"],
+        name: entry["name"],
+        saved_at: entry["saved_at"]
+      }
+    end
+  end
+end

data/lib/edupage/version.rb

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

data/lib/edupage/year.rb

@@ -0,0 +1,77 @@
+module Edupage
+  # A school year for one student - the level at which grades and terms exist.
+  #
+  # Edupage keeps the selected year in the session rather than in the request, so this
+  # is a scope object rather than a fetched record: it remembers which (student, year)
+  # it stands for and pins both cursors around every fetch it makes.
+  class Year
+    attr_reader :school, :student, :id, :name
+
+    # term_rows are the yearterms entries for this year, already read while listing the
+    # years. Keeping them means #terms and #grade_count cost nothing.
+    def initialize(school:, student:, id:, name: nil, current: false, term_rows: nil)
+      @school = school
+      @student = student
+      @id = id.to_s
+      @name = name || "#{@id}/#{@id.to_i + 1}"
+      @current = current
+      @term_rows = term_rows
+    end
+
+    def current? = @current
+
+    # Every grade in the year. Edupage serves one half-year per request, so this is the
+    # union of the terms rather than a single fetch.
+    def grades
+      Relation.new(-> { terms.flat_map { |term| grades_for(term) } })
+    end
+
+    def terms
+      Relation.new(-> { build_terms })
+    end
+
+    # Grades of one half-year.
+    def grades_for(term)
+      document = school.znamky_for(student, year: id, term: term.id)
+      document.grades.map do |row|
+        Models::Grade.new(row, school: school, event: document.event_for(row),
+                               year: self, term: term)
+      end
+    end
+
+    def term(id)
+      terms.find { |t| t.id.to_s.casecmp?(id.to_s) } or
+        raise NotFoundError, "#{student.full_name} has no term #{id} in #{name}"
+    end
+
+    def grade_count = terms.sum { |t| t.grade_count.to_i }
+
+    # Year-scoped views of the school directory: dbi changes between years, so a class
+    # list from 2025 is not the same as this year's.
+    def classes = school.classes(year: id)
+    def teachers = school.teachers(year: id)
+    def subjects = school.subjects(year: id)
+
+    def match_strings = [id, name].compact
+    def matches?(query) = query.nil? || match_strings.any? { |c| c.casecmp?(query.to_s) }
+
+    def to_h = { id: id, name: name, current: current?, grade_count: grade_count }
+    def to_s = "#{name}#{current? ? " (current)" : ""}"
+    def inspect = "#<Edupage::Year #{name} student=#{student.full_name.inspect}>"
+
+    def ==(other) = other.is_a?(Year) && id == other.id && student == other.student
+    alias eql? ==
+    def hash = [Year, id, student.id].hash
+
+    private
+
+    def term_rows
+      @term_rows ||= school.znamky_for(student, year: id).year_terms
+                           .select { |row| row["yearid"].to_s == id }
+    end
+
+    def build_terms
+      term_rows.map { |row| Models::Term.new(row, school: school, year: self) }
+    end
+  end
+end