wiq-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cac3732fa4c286907bce03d6ac62765477d828507719a29074873a9f9b90bde2
+  data.tar.gz: c686b4e1fb901e6554727c7030eb63d66cd70f659ca95345db2124b0ec6c9138
+SHA512:
+  metadata.gz: 970cfd866b44f27e8be608f8ddb40b147521bc241557637e545b21e23ec490d6e5a6ca8b6252b9f1c5f5a0ece7d1ad4a12f6457b80e1131c0beef691a5e65a3d
+  data.tar.gz: 22e94b802d4b4209c32131919733b68937775515a0b089ce764c1496758b281562e5532b708258351bac66c78f2db138eaefa9b55987dcb68671112ef2272ca5

data/LICENSE

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

data/README.md

@@ -0,0 +1,144 @@
+# wiq-cli
+
+> [!WARNING]
+> **Research preview — v0.1.0.** This is an exploratory tool. The command
+> surface, output shapes, and behavior are subject to change quickly and
+> without backwards compatibility guarantees between releases. Not yet
+> recommended for production-critical automation. Pin your gem version
+> if you build anything load-bearing on top of it.
+
+Read-only command-line interface for [WrestlingIQ](https://www.wrestlingiq.com).
+Designed to be driven by both humans and AI agents (Claude Code, Cursor,
+etc.) via per-user personal access tokens (PATs).
+
+## Getting started
+
+Four steps. Roughly five minutes end-to-end.
+
+### 1. Install
+
+```bash
+gem install wiq-cli
+```
+
+Requires Ruby 3.1+. On macOS, the system Ruby is too old —
+`brew install ruby` (or use rbenv / asdf) before running the gem install.
+
+### 2. Get a personal access token
+
+Sign into WrestlingIQ in your browser, then visit:
+
+**https://www.wrestlingiq.com/settings/personal_access_tokens**
+
+Click "New token", give it a name (e.g., `wiq-cli on my laptop`),
+and copy the token value. **You'll only see it once** — paste it
+somewhere safe for the next step.
+
+The token inherits your WrestlingIQ permissions. If you're an admin
+coach, your CLI will be able to run admin reports; if you're not, it
+won't. Either way, the token can be revoked anytime from the same
+page.
+
+### 3. Log in
+
+```bash
+wiq auth login
+```
+
+The CLI prompts for the host (defaults to production — just press
+Enter) and the token (paste the value from step 2). It verifies
+against the API and stores the token at
+`~/.config/wiq/credentials.json` (mode 0600, never logged).
+
+Sanity-check:
+
+```bash
+wiq doctor
+```
+
+All checks should pass and "Bound profile" should show your name + team.
+
+### 4. Install the Claude Code skill (optional but recommended)
+
+```bash
+wiq setup claude
+```
+
+This drops a small `SKILL.md` into `~/.claude/skills/wiq/` that
+teaches Claude how to drive the CLI. Claude Code auto-detects it
+within the current session — no restart needed.
+
+Now you can ask Claude things like:
+
+- "How is our prospect pipeline doing?"
+- "Show me everyone who hasn't been to practice in 2 weeks"
+- "Which families have failed payments that weren't retried successfully?"
+
+…and Claude will translate them into the right CLI commands.
+
+## Try it without Claude
+
+```bash
+wiq rosters list                                            # Browse rosters
+wiq prospects summary                                       # Pipeline dashboard
+wiq events list --start 2026-05-01 --end 2026-05-31         # Calendar
+wiq workflows list                                          # Curated multi-step recipes
+wiq reports types                                           # 36 report types w/ recommendations
+wiq commands                                                # Full JSON command tree (for agents)
+```
+
+Pass `--help` to any command for the full option list. Pass
+`--json` for the structured envelope, `--agent` for bare JSON, or
+just let the default pretty output flow.
+
+## Multiple clubs / multiple roles
+
+If you have PATs for different WIQ accounts (different clubs, or
+both a coach + parent role), store each under its own alias:
+
+```bash
+wiq auth login                          # First login → slot "default"
+wiq auth login --as westside            # Second account → slot "westside"
+wiq --as westside rosters list          # Run against the second slot
+WIQ_ALIAS=westside wiq events list      # Same, via env var
+```
+
+Full mechanic + resolution chain documented in `docs/wiq_api_notes.md`.
+
+## If something doesn't work
+
+```bash
+wiq doctor                              # Diagnostic checks (host, token, reachability, profile)
+wiq auth status                         # Shows the resolved credential
+wiq auth list                           # All stored credentials
+```
+
+If `wiq doctor` reports a failure or you see an unexpected error code,
+the error envelope includes a `hint` field pointing at the next thing
+to try. If you get stuck, email
+[support@wrestlingiq.com](mailto:support@wrestlingiq.com) with the
+output (the CLI never logs your token — paste the full JSON safely).
+
+## Output modes
+
+| Flag | Output |
+| --- | --- |
+| (default) | Pretty JSON to a TTY, bare JSON when piped |
+| `--json` | Full envelope: `{ok, data, summary, breadcrumbs, meta}` |
+| `--agent` | Bare `data` as JSON — best for headless agents |
+
+## Where things live
+
+- [`docs/wiq_api_notes.md`](docs/wiq_api_notes.md) — auth model, response shapes, gotchas, what the CLI maps to in `/api/v1`
+- [`docs/deferred.md`](docs/deferred.md) — work explicitly out of scope for v1 + the rationale
+- [`share/skills/wiq/SKILL.md`](share/skills/wiq/SKILL.md) — the bundled Claude Code skill content
+
+## Status
+
+v0.1.0 — 29 commands across 16 groups, 117 RSpec smoke examples.
+Reads-only except for report submission (the API's canonical async
+pattern). Write commands deferred — see `docs/deferred.md`.
+
+## License
+
+MIT.

data/bin/wiq

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "wiq"
+
+begin
+  Wiq::CLI.start(ARGV)
+rescue Wiq::Error => e
+  Wiq::Output.render_error(e, options: { agent: ARGV.include?("--agent"), json: ARGV.include?("--json") })
+  exit(e.exit_code)
+rescue Faraday::Error => e
+  Wiq::Output.render_error(
+    Wiq::Error.new(e.message, code: "network_error", hint: "Check the host URL and your network."),
+    options: { agent: ARGV.include?("--agent"), json: ARGV.include?("--json") }
+  )
+  exit(1)
+rescue Interrupt
+  warn "\nInterrupted"
+  exit(130)
+end

data/docs/deferred.md

@@ -0,0 +1,155 @@
+# Deferred work
+
+Everything we've explicitly chosen NOT to ship in v1. Each item carries a
+one-line "why we punted" so future-us doesn't have to re-derive the
+decision. Re-order as priorities shift; the headings are descriptive, not
+priority-ordered.
+
+Last updated: 2026-05-12 (after L1 ships).
+
+## Agent-discovery surface
+
+- ~~**L2 — `wiq workflows` command.**~~ SHIPPED. 14 curated workflows
+  across 7 categories (attendance, leads, roster, finance, memberships,
+  fundraising, store) in `lib/wiq/workflows.rb`. Each carries a
+  `question`, structured `parameters` (with types + enums + required
+  flags), an ordered `recipe` (with `<placeholder>` and `[--flag <name>]`
+  syntax), and `admin_only` flag propagated from underlying reports.
+  Spec invariants enforce parameter↔placeholder consistency and
+  admin_only drift detection across `Workflows::ALL` and
+  `Reports::TYPES`.
+- ~~**L3 — SKILL.md + Claude Code installer.**~~ SHIPPED.
+  `share/skills/wiq/SKILL.md` (lean — 10.8 KB) bundled in the gem,
+  installed via `wiq setup claude` (default `~/.claude/skills/wiq/`,
+  `--project` for per-project, `--force` to overwrite, `--print` to
+  inspect). Uses Claude Code's canonical skill format (no plugin
+  wrapper — confirmed via current docs). Sections cover bootstrap,
+  three core surfaces (commands/workflows/reports), auth model,
+  multi-club aliases, output modes, error codes table, pagination,
+  report decision matrix, common gotchas, what's NOT available.
+- ~~**Per-command `agent_notes` annotations.**~~ SHIPPED via Thor
+  `long_desc` blocks on every command across all 11 groups. Surfaces in
+  `wiq <group> help <cmd>` today; Phase 2's `wiq <cmd> --help --agent`
+  will project it to structured JSON.
+- ~~**Recommendation pass on the other report types.**~~ SHIPPED — 20
+  REC, 1 DEP, 15 NEU, 9 admin_only across the 36 entries in
+  `Reports::TYPES`. User-curated.
+- ~~**`wiq commands` JSON tree dump.**~~ SHIPPED. Walks Thor's
+  registry, emits stable nested JSON: `{name, version, global_options,
+  top_level_commands, groups: [{name, description, commands:
+  [{name, description, long_description, usage, options}]}]}`. Filters
+  Thor internals (`help`, `tree`), surfaces `enum` constraints,
+  reverses Thor's `map` so display names match what users type
+  (`run` not `run_report`, `check` not `check_all`).
+- **Per-command `--help --agent` JSON mode.** Deferred per the
+  Phase 2 scoping discussion — `wiq commands` covers the discovery
+  case in one call (~30 KB total). Add later only if a real agent
+  flow needs per-command JSON narrowly (filter the same introspection
+  output to one entry; very low cost).
+- **`.surface` drift CI.** Snapshot of the command tree at repo root; CI
+  fails on drift without an explicit update. Worth it once the command
+  surface stabilizes (i.e., after L2 lands).
+
+## Commands not yet exposed
+
+- ~~**`wiq events types`**~~ SHIPPED. Six canonical strings from
+  `app/models/event.rb` (practice, dual_meet, tournament, scramble,
+  private_lesson, other) surfaced via static command.
+- **`wiq events create`** — recurring practice/event creation
+  (`POST /api/v1/events` with `repeat:` block). Write surface; deferred
+  until v1.1.
+- **`wiq check_ins record`** — mark attendance via CLI
+  (`POST/PUT /api/v1/events/:id/check_ins`). Write surface; deferred.
+- **`wiq invoice_payments list`** — receipts/payment-instance granularity
+  for tracing money on a specific subscription. Endpoint exists
+  (`GET /api/v1/billing_subscriptions/:id/invoice_payments`). Hold
+  until a real use case beats `wiq charges list` for clarity.
+- ~~**`wiq wrestlers list`**~~ SHIPPED narrow. Default per_page=20, no
+  --all flag, base payload kept tight. Filters translate to Ransack
+  (--first-name, --last-name, --weight-class, --academic-class, --age,
+  --roster, --profile-type) + legacy free-text --query. --expand opts
+  into rosters / registration_answers per row. Multi-roster
+  intersection deferred (API supports it; CLI surface didn't justify
+  the complexity for v1). `wiq wrestlers show <id>` paired.
+- **`wiq url parse <url>`** — extract team/roster/event IDs from WIQ web
+  URLs. Initial-plan item; useful for agents pasted URLs by humans.
+- **`wiq paid_sessions create/update`**, **`wiq rosters create/update`**,
+  etc. — every write path on every resource. v1 is reads-only except
+  report submission. Cherry-pick as customers ask.
+- **Prospect write commands.** API supports `POST /prospect_families`,
+  `PATCH /prospect_families/:id` (incl. assigned_coach), `DELETE`,
+  `POST /prospect_families/:id/prospects`, `PATCH /prospects/:id`
+  (incl. stage transitions via `advance_to!`), and
+  `POST /prospect_families/:id/notes` (with `clear_follow_up_for[]` /
+  `add_follow_up_for[]` side-effect params). Reads-only in v1 — most
+  pipeline edits happen in the drawer UI today, and exposing
+  stage-transition writes without first watching agents use them is
+  asking for trouble.
+
+## Packaging / distribution
+
+- **macOS Keychain integration.** Currently file-based at
+  `~/.config/wiq/credentials.json` mode 0600. Keychain via the `keyring`
+  gem was in the original plan; the gem has compilation quirks and the
+  file store is fine for v1. Add once we have at least one customer
+  using the CLI.
+- **Homebrew tap (`brew install wrestlingiq/tap/wiq-cli`).** Initial-plan
+  distribution channel for Mac users. Gem-only install for v1.
+- **`curl …/install-cli | bash` script.** Agent-friendly env-setup
+  installer. Gem-only install for v1.
+- ~~**README.md**~~ SHIPPED (lean — install, bootstrap, common
+  commands, multi-club, Claude integration, output modes, pointers
+  to docs/). **CHANGELOG.md** still deferred — wait for v0.2.
+- **Integration / command-level tests.** Smoke layer landed
+  (`spec/{pagination,credentials,errors,config,output,client,season_resolver}_spec.rb`,
+  57 examples covering config resolution, error mapper, pagination,
+  output formatters, client wrap-unwrap, season filter). Still missing:
+  full Thor-invocation tests that exercise the command modules end-to-end
+  (`wiq rosters list --as westside` against a stubbed API). Add once a
+  command module starts carrying real logic beyond passing params through.
+
+## Output
+
+- **`--md` Markdown output mode.** Three modes (pretty/json/agent) cover
+  v1. Add when an agent actually needs Markdown inline in a chat surface.
+
+## Verification gaps (driven by user, not me)
+
+- **End-to-end smoke against real staging.** Auth flow + at least one
+  paginated index + one report poll. User is driving this.
+- **Confirm `PracticeAttendanceReport.result` / `CheckInSummaryReport.result`
+  shapes are agent-friendly.** Both land in `report.result` as opaque
+  jsonb; verify the structure is parseable without an HTML-strip step.
+- **OpenAPI regeneration.** `wrestling/doc/openapi.yaml` is ~1 year
+  stale. Run `OPENAPI=1 bundle exec rspec` and inspect the diff before
+  the CLI / spec is published externally. WIQ-app side, not CLI side.
+
+## Backend asks (push back to WIQ app team)
+
+- **`GET /api/v1/prospects?query=<str>` 500s on ambiguous ORDER BY.**
+  Found during the Phase 5 agent telemetry pass. The controller does
+  `Prospect.joins(:prospect_family).merge(ProspectFamily.search(query))
+  .order(created_at: :desc)` — both `prospects` and `prospect_families`
+  have `created_at`, so the join makes the order ambiguous. One-line
+  fix on the WIQ-app side: change to
+  `.order("prospects.created_at DESC")` (or
+  `.order(Prospect.arel_table[:created_at].desc)`). The CLI documents
+  the workaround (use `wiq prospect_families list --query` — same
+  matches, returns families with prospects embedded) until this ships.
+
+
+- ~~**`days_threshold` permit fix on `Api::V1::ReportsController`**~~ —
+  SHIPPED. The CLI's `--days-threshold` flag now lands on the model
+  unchanged; no further CLI work needed.
+- **Echo `request_id`** in the response body or `X-Request-ID` header,
+  for support correlation. Today the CLI can't give a customer a request
+  ID to ship to support.
+- **Real location/site filter on events.** `Event.location` is free-text
+  and not in `ransackable_attributes`. WIQ team has flagged a structured
+  location concept as roadmap. Until then the CLI deliberately exposes
+  no `--site` flag.
+- **Subdomain discovery flow for `wiq auth login`.** PAT settings URL
+  lives at `<team-subdomain>.wrestlingiq.com/settings/personal_access_tokens`.
+  If a customer doesn't know their subdomain, the CLI can't deep-link
+  them. Either document a discovery flow on the marketing site or accept
+  the host URL interactively (current plan).