edupage-cli 0.1.0

data/lib/edupage/config.rb

@@ -0,0 +1,96 @@
+require "fileutils"
+require "securerandom"
+require "yaml"
+
+module Edupage
+  # User configuration in ~/.config/edupage-cli/config.yml.
+  #
+  # Holds only non-secret settings. The password never lives here - see Credentials.
+  class Config
+    DEFAULTS = {
+      # Which *.edupage.org host to authenticate against. It is a login anchor only:
+      # it does not choose which school's data is read - see Registry::Context.
+      "default_school" => nil,
+      "default_username" => nil,
+      "server" => {
+        "host" => "127.0.0.1",
+        "port" => 4567,
+        "token" => nil
+      }
+    }.freeze
+
+    class << self
+      def load(path = self.path)
+        # Read as UTF-8 rather than through the locale, so a process started without
+        # LANG (an MCP client, launchd) does not choke on a non-ASCII value.
+        raw = File.exist?(path) ? (YAML.safe_load(File.read(path, encoding: Encoding::UTF_8)) || {}) : {}
+        new(deep_merge(DEFAULTS, raw), path: path)
+      end
+
+      def path
+        ENV["EDUPAGE_CONFIG"] || File.join(config_home, "edupage-cli", "config.yml")
+      end
+
+      def config_home
+        ENV["XDG_CONFIG_HOME"] || File.expand_path("~/.config")
+      end
+
+      def cache_home
+        ENV["XDG_CACHE_HOME"] || File.expand_path("~/.cache")
+      end
+
+      def cache_dir
+        ENV["EDUPAGE_CACHE_DIR"] || File.join(cache_home, "edupage-cli")
+      end
+
+      def deep_merge(base, other)
+        base.merge(other) do |_key, a, b|
+          a.is_a?(Hash) && b.is_a?(Hash) ? deep_merge(a, b) : (b.nil? ? a : b)
+        end
+      end
+    end
+
+    attr_reader :path
+
+    def initialize(data, path: self.class.path)
+      @data = data
+      @path = path
+    end
+
+    def [](key)
+      @data[key.to_s]
+    end
+
+    def []=(key, value)
+      @data[key.to_s] = value
+    end
+
+    def default_school = self["default_school"]
+    def default_username = self["default_username"]
+
+    def server = self["server"] || {}
+
+    # Lazily minted on first use so `edupage server` works without setup, but the token
+    # is only generated once and then persisted.
+    def server_token
+      server["token"] || begin
+        token = SecureRandom.urlsafe_base64(32)
+        @data["server"] = server.merge("token" => token)
+        save
+        token
+      end
+    end
+
+    def to_h = @data
+
+    def save
+      FileUtils.mkdir_p(File.dirname(path))
+      # Written 0600: the file carries the server bearer token.
+      File.open(path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |f|
+        f.set_encoding(Encoding::UTF_8)
+        f.write(YAML.dump(@data))
+      end
+      self
+    end
+  end
+end

data/lib/edupage/credentials/env.rb

@@ -0,0 +1,27 @@
+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

@@ -0,0 +1,120 @@
+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

data/lib/edupage/credentials.rb

@@ -0,0 +1,118 @@
+module Edupage
+  # Resolves username / password / school from an ordered list of providers.
+  #
+  # 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`.
+  class Credentials
+    Resolved = Struct.new(:value, :source, keyword_init: true)
+
+    attr_reader :username_override, :school_override
+
+    def initialize(username: nil, school: nil, providers: nil, 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
+    end
+
+    def username
+      resolved_username.value or
+        raise MissingCredentialsError,
+              "No username. Pass --username, set EDUPAGE_USERNAME, or set default_username in #{@config.path}."
+    end
+
+    def password
+      resolved_password.value or
+        raise MissingCredentialsError, missing_password_message
+    end
+
+    def school
+      resolved_school.value
+    end
+
+    def username_source = resolved_username.source
+    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
+    end
+
+    def to_h
+      { username: resolved_username.value, school: resolved_school.value }
+    end
+
+    # Never let a password reach a log line, a backtrace or `p`.
+    def inspect = "#<Edupage::Credentials username=#{resolved_username.value.inspect}>"
+    alias to_s inspect
+
+    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
+    end
+
+    def resolved_password
+      @resolved_password ||=
+        from_providers(: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
+    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
+    end
+
+    def wrap(value, source)
+      return nil if value.nil? || value.to_s.empty?
+
+      Resolved.new(value: value.to_s, source: source)
+    end
+
+    def missing_password_message
+      if Credentials::Keychain.available?
+        "No password. Run `edupage login`, or set EDUPAGE_PASSWORD."
+      else
+        "No password and the macOS keychain is unavailable on this platform. Set EDUPAGE_PASSWORD."
+      end
+    end
+  end
+end

data/lib/edupage/errors.rb

@@ -0,0 +1,74 @@
+module Edupage
+  # Base for everything this library raises on purpose.
+  class Error < StandardError; end
+
+  # No usable username/password could be assembled from any provider.
+  class MissingCredentialsError < Error; end
+
+  # Edupage rejected the credentials.
+  class LoginError < Error; end
+
+  # The login matched several accounts and none was selected.
+  class AmbiguousAccountError < LoginError
+    attr_reader :candidates
+
+    def initialize(candidates)
+      @candidates = candidates
+      list = candidates.map { |c| "#{c[:userid]} (#{c[:origin]})" }.join(", ")
+      super("Login matches multiple accounts: #{list}. Pass school: to pick one.")
+    end
+  end
+
+  # The stored session is no longer valid and could not be renewed.
+  class SessionExpiredError < Error; end
+
+  # The school demands two-factor approval for this login. Edupage still hands out a
+  # session id and answers the liveness ping, but every page redirects to /login/, so
+  # logging in again cannot help.
+  class TwoFactorRequiredError < LoginError
+    attr_reader :origin
+
+    def initialize(origin)
+      @origin = origin
+      super("#{origin} requires two-factor approval for this login, which edupage-cli " \
+            "cannot complete yet. Data from this school is unavailable.")
+    end
+  end
+
+  # Edupage answered, but not with anything we can read.
+  class ParseError < Error
+    attr_reader :snippet
+
+    def initialize(message, snippet: nil)
+      @snippet = snippet
+      super(snippet ? "#{message} (got: #{snippet.to_s[0, 200].inspect})" : message)
+    end
+  end
+
+  # Transport-level failure that survived the retries in Client.
+  class RequestError < Error; end
+
+  # Asked for a school/student/year that this account cannot see.
+  class NotFoundError < Error; end
+
+  # A level of the account > school > student > year chain was left unspecified while
+  # several options existed.
+  #
+  # Deliberately not a NotFoundError: "you did not choose" and "it does not exist" are
+  # different situations, and the surfaces answer them differently - the CLI lists the
+  # options, the REST API answers 400 rather than 404.
+  class AmbiguousScopeError < Error
+    # level: :school or :student
+    # candidates: [{ id:, label: }, ...] - enough for any surface to render a choice
+    attr_reader :level, :candidates
+
+    def initialize(level, candidates)
+      @level = level
+      @candidates = candidates
+      super("No #{level} selected; #{candidates.size} to choose from")
+    end
+  end
+
+  # The keychain provider was asked for something this platform cannot do.
+  class UnsupportedPlatformError < Error; end
+end

data/lib/edupage/model.rb

@@ -0,0 +1,131 @@
+require "date"
+require "time"
+
+module Edupage
+  # Base for every value object parsed out of an Edupage payload.
+  #
+  # Models are thin wrappers over the raw hash Edupage sent. The `attribute` DSL maps
+  # Edupage's Slovak/abbreviated keys onto Ruby names and casts once, in one place,
+  # instead of scattering `data["numberinclass"].to_i` through the codebase. The raw
+  # hash stays reachable via #data for the fields nobody has modelled yet.
+  class Model
+    CASTS = {
+      string: ->(v) { v.nil? ? nil : v.to_s },
+      integer: ->(v) { v.nil? || v.to_s.empty? ? nil : Integer(v, exception: false) },
+      float: ->(v) { v.nil? || v.to_s.empty? ? nil : Float(v, exception: false) },
+      boolean: ->(v) { [true, "1", 1, "true"].include?(v) },
+      date: ->(v) { parse_date(v) },
+      time: ->(v) { parse_time(v) },
+      raw: ->(v) { v }
+    }.freeze
+
+    class << self
+      def attributes = @attributes ||= superclass.respond_to?(:attributes) ? superclass.attributes.dup : {}
+
+      # Declares a reader backed by +key+ in the raw payload.
+      #
+      #   attribute :first_name, "firstname"
+      #   attribute :number, "numberinclass", cast: :integer
+      #
+      # A block receives the raw hash for values that need assembling rather than
+      # looking up.
+      def attribute(name, key = name.to_s, cast: nil, &block)
+        # A block usually assembles an object (a Subject, a list of Teachers), so it
+        # defaults to no cast; a plain key lookup defaults to a string.
+        cast ||= block ? :raw : :string
+        attributes[name.to_sym] = { key: key.to_s, cast: cast, block: block }
+
+        define_method(name) do
+          @computed.fetch(name) { @computed[name] = read_attribute(name) }
+        end
+      end
+
+      def parse_date(value)
+        return value if value.is_a?(Date) && !value.is_a?(DateTime)
+        return nil if value.nil? || value.to_s.empty?
+
+        Date.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      def parse_time(value)
+        return value if value.is_a?(Time)
+        return nil if value.nil? || value.to_s.empty?
+
+        # Edupage sends local wall-clock timestamps with no zone.
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    attr_reader :data, :school
+
+    def initialize(data, school: nil)
+      @data = data || {}
+      @school = school
+      @computed = {}
+    end
+
+    # Most Edupage records key off one of these.
+    def id
+      @id ||= (data["id"] || data["studentid"] || data["ucitelid"] || data["classid"]).then do |value|
+        value.nil? ? nil : value.to_s
+      end
+    end
+
+    def name = respond_to?(:full_name) ? full_name : data["name"]
+
+    # Strings a human might use to refer to this record on the command line.
+    # `where(subject: "MAT")` should match the short code as readily as the full name.
+    def match_strings
+      [id, (name if respond_to?(:name)), (short if respond_to?(:short))]
+        .compact.map(&:to_s).reject(&:empty?)
+    end
+
+    def matches?(query)
+      return true if query.nil?
+
+      case query
+      when Model then id == query.id
+      when Regexp then match_strings.any? { |candidate| candidate.match?(query) }
+      else match_strings.any? { |candidate| candidate.casecmp?(query.to_s) }
+      end
+    end
+
+    def to_h
+      self.class.attributes.keys.to_h { |name| [name, serialize(public_send(name))] }
+                          .merge(id: id).compact
+    end
+
+    def ==(other) = other.is_a?(self.class) && !id.nil? && id == other.id
+    alias eql? ==
+
+    def hash = [self.class, id].hash
+
+    def inspect
+      shown = self.class.attributes.keys.first(4)
+                  .to_h { |a| [a, public_send(a)] }.compact
+                  .map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+      "#<#{self.class.name.split("::").last} id=#{id.inspect} #{shown}>"
+    end
+
+    private
+
+    def read_attribute(name)
+      spec = self.class.attributes.fetch(name)
+      raw = spec[:block] ? instance_exec(data, &spec[:block]) : data[spec[:key]]
+      CASTS.fetch(spec[:cast]).call(raw)
+    end
+
+    def serialize(value)
+      case value
+      when Model then value.id
+      when Array then value.map { |v| serialize(v) }
+      when Date, Time then value.iso8601
+      else value
+      end
+    end
+  end
+end

data/lib/edupage/models/assignment.rb

@@ -0,0 +1,83 @@
+module Edupage
+  module Models
+    # Something the student has to do: homework, a test, an exam, a project.
+    #
+    # Edupage announces these as timeline items, in two shapes that the upstream JS
+    # library treats very differently and which are unified here:
+    #
+    #   class-wide  recipient is a plan ("CustPlan8562"), the whole class gets it
+    #   personal    recipient is the pupil ("Student113506")
+    #
+    # Both carry the real content in the embedded payload, so both are read the same
+    # way. Only handling the first shape loses every individually assigned task - two
+    # thirds of them on the account this was built against.
+    class Assignment < TimelineItem
+      HOMEWORK_TYPES = %w[hw etesthw].freeze
+      EXAM_TYPES = %w[bexam sexam oexam rexam exam testing].freeze
+      TEST_TYPES = %w[test etest etestprint].freeze
+      PROJECT_TYPES = %w[pexam projekt].freeze
+
+      # Timeline items that represent an assignment of some kind.
+      TIMELINE_TYPES = %w[homework testpridelenie].freeze
+
+      def self.assignment?(row)
+        TIMELINE_TYPES.include?(row["typ"].to_s)
+      end
+
+      # "hw", "test", ... - the payload's own type, falling back to homework, which is
+      # what a plain `homework` timeline item is.
+      def assignment_type
+        value = payload["typ"] || payload["etype"]
+        value.to_s.empty? ? "hw" : value.to_s.split("|").first
+      end
+      alias type assignment_type
+
+      def title = presence(payload["nazov"])
+      def description = presence(payload["popis"])
+
+      def due_on = Model.parse_date(payload["date"])
+      def assigned_on = created_at&.to_date
+
+      def subject = school&.subject(payload["predmetid"])
+      def school_class = school&.school_class(payload["triedaid"])
+      def teacher = owner.is_a?(Teacher) ? owner : nil
+
+      def plan_id = payload["planid"]
+      def super_id = payload["superid"] || payload["e_superid"]
+
+      # True when the task went to a whole class rather than to one pupil.
+      def class_wide? = recipient_user_string.to_s.start_with?("CustPlan", "Trieda", "Plan")
+
+      def homework? = HOMEWORK_TYPES.include?(assignment_type)
+      def exam? = EXAM_TYPES.include?(assignment_type)
+      def test? = TEST_TYPES.include?(assignment_type)
+      def project? = PROJECT_TYPES.include?(assignment_type)
+
+      def overdue? = due_on ? due_on < Date.today : false
+
+      def name = title
+      def match_strings = [id, title, subject&.short, subject&.name, assignment_type].compact.map(&:to_s)
+
+      def to_s
+        [
+          due_on ? "due #{due_on}" : nil,
+          subject&.short,
+          title
+        ].compact.join(" | ")
+      end
+
+      def to_h
+        {
+          id: id, type: assignment_type, title: title, description: description,
+          subject: subject&.name, teacher: teacher&.full_name,
+          assigned_on: assigned_on&.iso8601, due_on: due_on&.iso8601,
+          class_wide: class_wide?, student: student&.full_name
+        }.compact
+      end
+
+      private
+
+      def presence(value) = value.nil? || value.to_s.empty? ? nil : value.to_s
+    end
+  end
+end

data/lib/edupage/models/classroom.rb

@@ -0,0 +1,13 @@
+module Edupage
+  module Models
+    # A room. Edupage also models floors and buildings as classrooms, which is why
+    # some entries are hidden from the class book.
+    class Classroom < Model
+      attribute :name
+      attribute :short
+      attribute :hidden_in_classbook, "cb_hidden", cast: :boolean
+
+      alias hidden_in_classbook? hidden_in_classbook
+    end
+  end
+end