wiq-cli 0.1.0

data/lib/wiq/commands/workflows.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class Workflows < Base
+      desc "list", "List all documented workflows"
+      long_desc <<~DESC
+        Workflows are named recipes that map a human question to a CLI
+        command sequence. Use them to bootstrap agent flows for common
+        club-admin tasks.
+
+        Each workflow carries:
+          name         kebab-case slug (the lookup key)
+          category     attendance | leads | roster | finance |
+                       memberships | fundraising | store
+          question     natural-language framing — match against this
+          parameters   structured list of {name, type, required, ...}
+          recipe       ordered command strings with <placeholder> and
+                       [optional] brackets
+          admin_only   true means non-admin coach PATs will 403
+          notes        when present, agent-facing guidance
+
+        Placeholder syntax in recipes:
+          <name>          required substitution (must match a parameter)
+          [--flag <name>] optional bracket — drop the whole thing when
+                          the parameter isn't provided
+
+        Run `wiq workflows show <name>` for a single workflow's full detail.
+      DESC
+      def list
+        rows = Wiq::Workflows::ALL.values.map { |w| summary_row(w) }
+        render_index(
+          rows,
+          summary: "#{rows.size} documented workflows across #{Wiq::Workflows::CATEGORIES.size} categories.",
+          breadcrumbs: [
+            { "cmd" => "wiq workflows show <name>", "description" => "Detail for one workflow" },
+            { "cmd" => "wiq commands", "description" => "Full command tree (for ad-hoc composition)" }
+          ]
+        )
+      end
+
+      desc "show NAME", "Show a single workflow's full detail"
+      long_desc <<~DESC
+        Returns the complete workflow definition: question, parameters
+        (with types and required/default), the recipe (ordered command
+        list), admin_only flag, and notes.
+
+        Use this after `wiq workflows list` narrows you to a candidate.
+      DESC
+      def show(name)
+        workflow = Wiq::Workflows::ALL[name]
+        unless workflow
+          available = Wiq::Workflows::ALL.keys.sort.join(", ")
+          raise Wiq::Error.new(
+            "Unknown workflow #{name.inspect}.",
+            code: "workflow_not_found",
+            hint: "Available: #{available}"
+          )
+        end
+
+        render(workflow,
+               summary: "#{workflow[:name]} — #{workflow[:question]}",
+               breadcrumbs: workflow[:recipe].map do |cmd|
+                 { "cmd" => cmd, "description" => "Run this step" }
+               end)
+      end
+
+      default_task :list
+
+      no_commands do
+        def summary_row(workflow)
+          {
+            "name" => workflow[:name],
+            "category" => workflow[:category],
+            "question" => workflow[:question],
+            "admin_only" => workflow[:admin_only] == true,
+            "step_count" => workflow[:recipe].size,
+            "parameter_count" => workflow[:parameters].size
+          }
+        end
+      end
+    end
+  end
+end

data/lib/wiq/commands/wrestlers.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class Wrestlers < Base
+      # Match WrestlerProfile constants in app/models/wrestler_profile.rb.
+      PROFILE_TYPES = %w[teammate alumnus guest all].freeze
+      DEFAULT_PER_PAGE = 20
+
+      desc "list", "Search wrestlers — narrow ID-discovery surface"
+      long_desc <<~DESC
+        Narrow listing + filtering, primarily for ID discovery before
+        running another command (e.g. `wiq check_ins wrestler <id>`).
+        Default page size is 20; there's no --all flag. For exhaustive
+        exports use `wiq reports run RosterReport [--append-properties …]`
+        or `wiq reports run FullExportWrestlerReport`.
+
+        Filters translate to Ransack params server-side:
+          --query              free-text name search (legacy `?query=`)
+          --first-name         q[first_name_cont]
+          --last-name          q[last_name_cont]
+          --roster <id>        q[rosters_id_eq] — filter to one roster
+          --weight-class       q[weight_class_numeric_eq] — exact numeric
+          --academic-class     q[academic_class_eq] (senior, junior, …)
+          --age                q[age_eq]
+          --profile-type       teammate (default) | alumnus | guest | all
+
+        Multi-roster intersection ("kids on both A AND B") is supported
+        by the API but not yet exposed in the CLI — use the web UI for
+        now or compose two `--roster <id>` calls and intersect
+        client-side.
+
+        --expand opts into a wider payload:
+          rosters                Adds full roster details per wrestler
+          registration_answers   Adds intake-form answers per wrestler
+
+        Base payload is already wider than most index endpoints (parents,
+        coach_guardians, profile_photos, basic roster refs all render by
+        default). For agents on a tight context window, prefer
+        `wiq wrestlers show <id>` once you've narrowed to a candidate.
+      DESC
+      method_option :query, type: :string, desc: "Free-text name search"
+      method_option :first_name, type: :string, desc: "First name (contains)"
+      method_option :last_name, type: :string, desc: "Last name (contains)"
+      method_option :roster, type: :numeric, desc: "Filter to a single roster id"
+      method_option :weight_class, type: :string,
+                                   desc: "Weight class (exact numeric, e.g. 132)"
+      method_option :academic_class, type: :string,
+                                     desc: "senior, junior, sophomore, freshman, …"
+      method_option :age, type: :numeric, desc: "Age in years (exact)"
+      method_option :profile_type, type: :string, enum: PROFILE_TYPES, default: "teammate",
+                                   desc: "Default 'teammate' matches the WIQ web UI default; " \
+                                         "'all' removes the filter entirely"
+      method_option :expand, type: :string,
+                             desc: "CSV: rosters, registration_answers"
+      method_option :per_page, type: :numeric, default: DEFAULT_PER_PAGE,
+                               desc: "Page size (default 20; narrow surface)"
+      def list
+        params = build_list_params
+
+        records, total = fetch_index("/api/v1/wrestlers", params, key: "wrestlers")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} wrestlers#{summary_filters_suffix}.",
+          breadcrumbs: [
+            { "cmd" => "wiq wrestlers show <id>", "description" => "Drill into one wrestler" },
+            { "cmd" => "wiq check_ins wrestler <id>", "description" => "See a wrestler's check-in history" },
+            { "cmd" => "wiq reports run RosterReport --roster 0 --append-properties <q_ids>",
+              "description" => "For exhaustive exports, use a report instead" }
+          ]
+        )
+      end
+
+      desc "show ID", "Fetch a single wrestler profile"
+      long_desc <<~DESC
+        Single-wrestler drill-down. Returns the full base payload
+        (basic profile, parents, coach_guardians, profile_photos,
+        rosters refs).
+
+        Pass --expand for additional sections:
+          rosters                Full roster details with tags
+          registration_answers   Intake-form answers
+      DESC
+      method_option :expand, type: :string,
+                             desc: "CSV: rosters, registration_answers"
+      def show(id)
+        params = {}
+        params["expand_rosters"] = true if expand_includes?("rosters")
+        params["expand_registration_answers"] = true if expand_includes?("registration_answers")
+        wrestler = client.get("/api/v1/wrestlers/#{id}", params)
+        render(wrestler,
+               summary: "Wrestler #{wrestler["id"]} — #{wrestler["full_name"] || wrestler["display_name"]}",
+               breadcrumbs: [
+                 { "cmd" => "wiq check_ins wrestler #{wrestler["id"]}",
+                   "description" => "Check-in history for this wrestler" },
+                 { "cmd" => "wiq registrations answers --profile #{wrestler["id"]} --profile-type WrestlerProfile",
+                   "description" => "Registration answers (subject to visibility gating)" }
+               ])
+      end
+
+      no_commands do
+        # Extracted so the spec can verify the option → query-param mapping
+        # without round-tripping a real Faraday connection.
+        def build_list_params
+          params = { "per_page" => options[:per_page] || DEFAULT_PER_PAGE }
+          params["query"] = options[:query] if options[:query]
+          params["q[first_name_cont]"] = options[:first_name] if options[:first_name]
+          params["q[last_name_cont]"] = options[:last_name] if options[:last_name]
+          params["q[rosters_id_eq]"] = options[:roster] if options[:roster]
+          params["q[weight_class_numeric_eq]"] = options[:weight_class] if options[:weight_class]
+          params["q[academic_class_eq]"] = options[:academic_class] if options[:academic_class]
+          params["q[age_eq]"] = options[:age] if options[:age]
+          params["q[profile_type_eq]"] = options[:profile_type] if profile_type_filter?
+          params["expand_rosters"] = true if expand_includes?("rosters")
+          params["expand_registration_answers"] = true if expand_includes?("registration_answers")
+          params
+        end
+
+        def profile_type_filter?
+          options[:profile_type] && options[:profile_type] != "all"
+        end
+
+        def expand_includes?(part)
+          return false unless options[:expand]
+
+          options[:expand].split(",").map(&:strip).include?(part)
+        end
+
+        def summary_filters_suffix
+          bits = []
+          bits << "matching #{options[:query].inspect}" if options[:query]
+          bits << "in roster #{options[:roster]}" if options[:roster]
+          bits << "weight class #{options[:weight_class]}" if options[:weight_class]
+          bits << "profile_type=#{options[:profile_type]}" if profile_type_filter? && options[:profile_type] != "teammate"
+          bits.empty? ? "" : " (#{bits.join(", ")})"
+        end
+      end
+    end
+  end
+end

data/lib/wiq/config.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Wiq
+  # Resolves host + alias + token from the documented precedence chain.
+  #
+  # Host:
+  #   --host > WIQ_HOST > .wiq/config.json:host > sole stored host
+  #         > PRODUCTION_HOST
+  #
+  # Alias (only meaningful once host is known):
+  #   --as > WIQ_ALIAS > .wiq/config.json:alias > sole alias for host > "default"
+  #
+  # Token:
+  #   WIQ_TOKEN (direct override) > credentials store (host, alias)
+  class Config
+    PRODUCTION_HOST = "https://www.wrestlingiq.com"
+
+    attr_reader :host, :alias_name, :token, :sources
+
+    def self.load(options = {})
+      new(options).tap(&:resolve!)
+    end
+
+    def initialize(options = {})
+      @options = options || {}
+      @sources = {}
+    end
+
+    def resolve!
+      @host = resolve_host
+      @alias_name = resolve_alias if @host
+      @token = resolve_token
+      self
+    end
+
+    def require_host!
+      raise HostUnsetError unless @host
+    end
+
+    def require_token!
+      require_host!
+      return if @token
+
+      # No env override, no usable alias-keyed entry — decide which error to raise.
+      aliases = Credentials.aliases_for(@host)
+      if aliases.empty?
+        raise NotAuthenticatedError
+      elsif @alias_name && !Credentials.for_host(@host, @alias_name)
+        raise AliasNotFoundError.new(@host, @alias_name, aliases)
+      elsif @alias_name.nil?
+        raise AmbiguousAliasError.new(@host, aliases)
+      else
+        raise NotAuthenticatedError
+      end
+    end
+
+    def trace
+      {
+        host: @host,
+        host_source: @sources[:host],
+        alias: @alias_name,
+        alias_source: @sources[:alias],
+        token_present: !@token.nil?,
+        token_source: @sources[:token],
+        credentials_path: Credentials.path,
+        repo_config_path: repo_config_path
+      }
+    end
+
+    private
+
+    def resolve_host
+      if (val = @options[:host])
+        @sources[:host] = "--host flag"
+        return val
+      end
+      if (val = ENV["WIQ_HOST"])
+        @sources[:host] = "WIQ_HOST env"
+        return val
+      end
+      if (val = repo_config["host"])
+        @sources[:host] = "repo config (#{repo_config_path})"
+        return val
+      end
+      hosts = Credentials.hosts
+      if hosts.size == 1
+        @sources[:host] = "credentials store (sole host)"
+        return hosts.first
+      end
+      @sources[:host] = "production default"
+      PRODUCTION_HOST
+    end
+
+    def resolve_alias
+      if (val = @options[:as])
+        @sources[:alias] = "--as flag"
+        return val
+      end
+      if (val = ENV["WIQ_ALIAS"])
+        @sources[:alias] = "WIQ_ALIAS env"
+        return val
+      end
+      if (val = repo_config["alias"])
+        @sources[:alias] = "repo config (#{repo_config_path})"
+        return val
+      end
+      aliases = Credentials.aliases_for(@host)
+      if aliases.size == 1
+        @sources[:alias] = "credentials store (sole alias)"
+        return aliases.first
+      end
+      if aliases.include?(Credentials::DEFAULT_ALIAS)
+        @sources[:alias] = "credentials store (default)"
+        return Credentials::DEFAULT_ALIAS
+      end
+      @sources[:alias] = aliases.empty? ? "no credentials stored" : "ambiguous (#{aliases.join(", ")})"
+      nil
+    end
+
+    def resolve_token
+      return nil unless @host
+
+      if (val = ENV["WIQ_TOKEN"])
+        @sources[:token] = "WIQ_TOKEN env"
+        return val
+      end
+      return nil unless @alias_name
+
+      entry = Credentials.for_host(@host, @alias_name)
+      return nil unless entry && entry["token"]
+
+      @sources[:token] = "credentials store (alias=#{@alias_name})"
+      entry["token"]
+    end
+
+    def repo_config
+      @repo_config ||= load_repo_config
+    end
+
+    def repo_config_path
+      @repo_config_path
+    end
+
+    def load_repo_config
+      dir = Dir.pwd
+      while dir != "/" && !dir.empty?
+        candidate = File.join(dir, ".wiq", "config.json")
+        if File.exist?(candidate)
+          @repo_config_path = candidate
+          begin
+            return JSON.parse(File.read(candidate))
+          rescue JSON::ParserError
+            return {}
+          end
+        end
+        parent = File.dirname(dir)
+        break if parent == dir
+        dir = parent
+      end
+      {}
+    end
+  end
+end

data/lib/wiq/credentials.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "time"
+
+module Wiq
+  # File-backed credential store. ~/.config/wiq/credentials.json, mode 0600.
+  # Shape:
+  #   {
+  #     "<host>": {
+  #       "<alias>": { "token": "...", "token_prefix": "...", "name": "...",
+  #                    "profile": {...}, "stored_at": "..." },
+  #       "<alias>": { ... }
+  #     }
+  #   }
+  module Credentials
+    DEFAULT_PATH = File.join(Dir.home, ".config", "wiq", "credentials.json")
+    DEFAULT_ALIAS = "default"
+
+    module_function
+
+    def path
+      ENV["WIQ_CREDENTIALS_PATH"] || DEFAULT_PATH
+    end
+
+    def load_all
+      return {} unless File.exist?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError
+      {}
+    end
+
+    def for_host(host, alias_name)
+      load_all.dig(host, alias_name)
+    end
+
+    def aliases_for(host)
+      Array((load_all[host] || {}).keys)
+    end
+
+    def hosts
+      load_all.keys
+    end
+
+    # Flat list across hosts × aliases. Useful for `wiq auth list`. Excludes the
+    # raw token; callers should never log tokens.
+    def all_entries
+      load_all.flat_map do |host, by_alias|
+        by_alias.map do |alias_name, entry|
+          {
+            "host" => host,
+            "alias" => alias_name,
+            "token_prefix" => entry["token_prefix"],
+            "name" => entry["name"],
+            "profile" => entry["profile"],
+            "stored_at" => entry["stored_at"]
+          }
+        end
+      end
+    end
+
+    def store(host:, alias_name:, token:, token_prefix: nil, name: nil, profile: nil)
+      data = load_all
+      data[host] ||= {}
+      data[host][alias_name] = {
+        "token" => token,
+        "token_prefix" => token_prefix,
+        "name" => name,
+        "profile" => profile,
+        "stored_at" => Time.now.utc.iso8601
+      }.compact
+      write(data)
+    end
+
+    def remove(host, alias_name)
+      data = load_all
+      bucket = data[host]
+      return false unless bucket
+      return false unless bucket.delete(alias_name)
+
+      data.delete(host) if bucket.empty?
+      write(data)
+      true
+    end
+
+    def write(data)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |f|
+        f.write(JSON.pretty_generate(data))
+      end
+    end
+  end
+end

data/lib/wiq/errors.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Wiq
+  class Error < StandardError
+    attr_reader :code, :hint, :exit_code, :details
+
+    def initialize(message, code: "error", hint: nil, exit_code: 1, details: nil)
+      super(message)
+      @code = code
+      @hint = hint
+      @exit_code = exit_code
+      @details = details
+    end
+  end
+
+  class ConfigError < Error
+    def initialize(message, code: "config_error", **opts)
+      super(message, code: code, **opts)
+    end
+  end
+
+  class HostUnsetError < ConfigError
+    def initialize
+      super(
+        "No WIQ host configured.",
+        code: "host_unset",
+        hint: "Run `wiq auth login` to configure a host and token, or pass --host."
+      )
+    end
+  end
+
+  class NotAuthenticatedError < ConfigError
+    def initialize
+      super(
+        "No personal access token configured.",
+        code: "not_authenticated",
+        hint: "Run `wiq auth login` to store a PAT for this host."
+      )
+    end
+  end
+
+  class AmbiguousAliasError < ConfigError
+    def initialize(host, aliases)
+      super(
+        "Multiple credential aliases stored for #{host}: #{aliases.join(", ")}.",
+        code: "ambiguous_alias",
+        hint: "Pass --as <alias>, set WIQ_ALIAS, or add `alias` to .wiq/config.json. " \
+              "Run `wiq auth list` to see what's stored."
+      )
+    end
+  end
+
+  class AliasNotFoundError < ConfigError
+    def initialize(host, alias_name, available)
+      hint = if available.empty?
+        "No credentials stored for this host. Run `wiq auth login`."
+      else
+        "Available aliases for #{host}: #{available.join(", ")}."
+      end
+      super(
+        "No credential stored for #{host} under alias #{alias_name.inspect}.",
+        code: "alias_not_found",
+        hint: hint
+      )
+    end
+  end
+
+  class AliasConflictError < ConfigError
+    def initialize(host, alias_name)
+      super(
+        "An entry already exists for #{host} under alias #{alias_name.inspect}.",
+        code: "alias_conflict",
+        hint: "Pass --as <other-name> to store under a different slot, or --force to overwrite."
+      )
+    end
+  end
+
+  # Mirror of the HTTP error envelope from /api/v1.
+  class APIError < Error
+    attr_reader :status, :response_body, :request_id
+
+    def initialize(status:, body:, request_id: nil)
+      @status = status
+      @response_body = body
+      @request_id = request_id
+
+      code, message, hint = derive(status, body)
+      super(message, code: code, hint: hint, exit_code: 1, details: body)
+    end
+
+    private
+
+    def derive(status, body)
+      msgs = extract_messages(body)
+      case status
+      when 401
+        ["unauthorized", "Token rejected by server (401).",
+         "Run `wiq auth status` to inspect the active token; `wiq auth login` to replace it."]
+      when 403
+        ["forbidden", "Server denied access (403): #{msgs}",
+         "PATs inherit the user's permissions. Confirm the minting user can see this resource in the web app."]
+      when 404
+        ["not_found", "Resource not found (404).", nil]
+      when 422
+        ["validation_failed", "Validation error (422): #{msgs}", nil]
+      when 429
+        ["rate_limited", "Rate limited (429): #{msgs}",
+         "WIQ enforces 100 req/3s per IP. Back off and retry."]
+      else
+        ["http_#{status}", "HTTP #{status}: #{msgs}", nil]
+      end
+    end
+
+    # /api/v1 always returns { "errors": <array|hash> }. Flatten to a human string.
+    def extract_messages(body)
+      return body.to_s unless body.is_a?(Hash)
+
+      errs = body["errors"] || body[:errors]
+      return "no error body" if errs.nil?
+
+      case errs
+      when Array
+        errs.join("; ")
+      when Hash
+        errs.flat_map { |field, msgs| Array(msgs).map { |m| "#{field}: #{m}" } }.join("; ")
+      else
+        errs.to_s
+      end
+    end
+  end
+
+  class ReportFailedError < Error
+    def initialize(report)
+      super(
+        "Report ##{report["id"]} (#{report["type"]}) finished with status `failed`.",
+        code: "report_failed",
+        details: report["result"]
+      )
+    end
+  end
+
+  class ReportTimeoutError < Error
+    def initialize(report, timeout)
+      super(
+        "Report ##{report["id"]} did not finish within #{timeout}s (last status: #{report["status"]}).",
+        code: "report_timeout",
+        hint: "Pass --timeout to wait longer, or re-check later with `wiq reports show #{report["id"]}`.",
+        details: report
+      )
+    end
+  end
+
+  class SeasonNotFoundError < Error
+    def initialize(year)
+      super(
+        "No paid sessions overlap year #{year}.",
+        code: "season_not_found",
+        hint: "Run `wiq paid_sessions list` to see configured registration periods."
+      )
+    end
+  end
+
+  class SeasonUnsupportedError < Error
+    def initialize(type, matches)
+      super(
+        "Season #{matches.size > 1 ? "is ambiguous" : "cannot be applied automatically"} for report type #{type}.",
+        code: "season_unsupported_for_type",
+        hint: "Pass --paid-session <id> explicitly. Matching paid sessions: #{matches.map { |m| m["id"] }.join(", ")}"
+      )
+    end
+  end
+end