@drakulavich/oura-cli 0.4.5 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,71 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-05
+
+### Breaking
+- Per-collection API commands replaced by `fetch <collection>`; `db reset` and `db import` removed. See "Changed" and "Removed" below.
+
+### Changed
+- `sync` fetches heartrate over the same window as every other collection (from the last synced day, or 30 days back on first sync) instead of today only, in pieces of at most 30 × 24 hours because the heartrate endpoint rejects longer ranges; consecutive pieces do not share a boundary instant, so no sample is fetched twice. Days the ring synced while `oura-cli sync` did not run are no longer skipped; the unique `(timestamp, source)` index keeps re-fetched samples from duplicating.
+- README "First five minutes" now leads with a concrete report sample,
+  documents `login` → `doctor` → `sync` → `report` as the onboarding path,
+  states plainly that `login` hides the token as you type, and adds a
+  symptom → command recovery table.
+- Text formatters moved from the repo root into `src/render/` (internal).
+- Every data command runs through one runner that resolves the output format, opens and always closes the database, creates the API client and maps errors to exit codes. `sync` progress lines are printed together with the summary instead of streaming. `--no-color` now takes effect before any output (internal).
+- Token resolution lives in `src/api/token.ts` and is shared by the API client and `doctor`; the two SQLite wrappers merged into `src/db/open.ts` (internal). A whitespace-only token is now rejected as missing instead of being sent as an empty bearer token.
+- Every Oura collection is described once in `src/collections/`; table DDL, inserts and the sync loop derive from it. A test proves the derived DDL matches the shipped migrations (internal).
+- **Breaking:** the seven per-collection commands (`sleep`, `readiness`, `activity`, `hr`, `spo2`, `stress`, `workout` × `today|date|week`) are replaced by `oura-cli fetch <collection> [--day D | --from A --to B | --days N]`. `sleep-periods` and `cv-age` are now fetchable too.
+- `describe` and `manifest` are generated from the registered command tree, so they can no longer drift from the CLI; `manifest` examples that referenced a non-existent `--start` flag are gone.
+- `docs/schemas/<collection>.json` are generated (`bun run schemas`) and checked by a test; added `sleep-periods.json` and `cv-age.json`.
+
+### Removed
+- `db reset` and the CSV importer it relied on (it read a hard-coded personal directory), and the `db import` alias of `sync`.
+- `vo2max` no longer appears in `db stats`; the table was never populated. `db stats` now lists tables in registry order (`heartrate` fourth, `cardiovascular_age` last); key by `table`, not position.
+
+### Added
+- `oura-cli doctor` diagnoses token resolution (honoring `--token` like every
+  other command), live token validity (skippable with `--offline`), local
+  database health, and data freshness across sleep/readiness/activity in one
+  pass. `ok` is true only when every check is clean — a warning is enough to
+  clear "everything looks healthy". `nextStep` is the first non-ok check's
+  fix, so it never recommends a command (like `sync`) that would just hit the
+  same root cause (like an unreachable API) a check upstream already found.
+  Both `table` and `json` output are supported; the JSON shape is published
+  as `docs/schemas/doctor.json`.
+
+### Fixed
+- `fetch --day/--from/--to` and `db date` reject calendar-invalid dates such as `2026-02-30` with `BAD_ARGS` instead of sending them to the API or querying nothing. `db trends <days>` rejects anything but a positive integer instead of failing with `UNKNOWN` (`abc`) or silently returning nothing (`0`).
+- An unknown `--format` is rejected for `fetch` too (it used to be silently accepted); `fetch` errors now render as text on a TTY and as JSON when piped.
+- An unknown `--tz` / `OURA_TZ` is reported as `BAD_ARGS` with a hint instead of an `UNKNOWN` error from the date formatter.
+- `fetch hr` and the heartrate step of `sync` now send `start_datetime`/`end_datetime` (UTC instants covering the requested local days in `OURA_TZ`), which is what the Oura heartrate endpoint takes; every other collection keeps `start_date`/`end_date`. Previously heartrate was queried with date parameters the endpoint does not define.
+- The API client follows `next_token` and returns every page, so ranges longer than one page (heartrate over several days) are no longer silently truncated.
+- Local-day boundaries are computed at local midnight instead of noon, so `fetch hr --day` on a DST transition day covers the whole 23- or 25-hour day rather than shifting by an hour (internal `localDateToUtcRange`, previously unused).
+- Interactive `oura-cli login` now hides the Personal Access Token while it is
+  typed and explains how to use `--token` safely in non-interactive contexts.
+- `oura-cli report` now explains when no data is available and directs new
+  users to run `oura-cli sync`, instead of showing an all-empty report table.
+- Reports containing only sleep-detail data are no longer mistaken for empty
+  reports and continue to show the available sleep metrics.
+- `oura-cli db today` and `oura-cli db week` now explain when the local cache
+  has no data for the requested range and point at `oura-cli sync`, instead of
+  showing an all-dash table. JSON output is unchanged.
+- `oura-cli sync` now says explicitly when it is a first sync backfilling the
+  default 30 days, names the resolved date range for both first and
+  incremental syncs, and prints a per-collection import count summary in
+  table mode. JSON output gains an additive `import.isFirstSync` boolean.
+- `OuraStressDay.day_summary`, `OuraWorkout.label` and `OuraSleepModel.type` are
+  now typed `?: string | null`, matching the Oura OpenAPI spec (checked against
+  1.37), which marks all three nullable and omits them from `required`. The
+  declared types claimed a value is always present, so code reading them could
+  assume one that never arrives. `importDaily` now maps an absent value to
+  `NULL` explicitly instead of relying on `bun:sqlite` silently coercing
+  `undefined`.
+- `db week`, `db trends`, `db stats`, `report` and `sync` now compute "today"
+  and every window boundary in the configured timezone (`--tz` / `OURA_TZ`);
+  previously they used UTC and disagreed with `db today` around midnight.
+
 ## [0.4.5] - 2026-07-18
 
 ### Removed

package/README.md

@@ -26,17 +26,45 @@ curl -fsSL https://bun.sh/install | bash   # if you don't have Bun yet
 bun add -g @drakulavich/oura-cli
 ```
 
-You'll also need a [Personal Access Token from Oura](https://cloud.ouraring.com/personal-access-tokens). Paste it into `oura-cli login` once — it lands at `~/.oura-token` with `0600` perms.
+You'll also need a [Personal Access Token from Oura](https://cloud.ouraring.com/personal-access-tokens). Run `oura-cli login` once — it hides the token as you type (nothing is echoed to the terminal) and saves it to `~/.oura-token` with `0600` perms.
 
 ## First five minutes
 
+Five minutes from now you'll have your week of sleep, readiness and activity in a terminal digest like this:
+
+```
+  Oura Weekly Report
+  2026-08-24 — 2026-08-30
+
+  Last 7 Days:
+  ────────────────────────────────────────────────────
+  Day         Sleep  Ready  Active    Steps
+  ────────────────────────────────────────────────────
+  Mon 24/08      87     74      68    9,668
+  Tue 25/08      82     79      74   11,204
+  ...
+```
+
+Four commands get you there:
+
 ```bash
-oura-cli login          # paste your PAT, one time
-oura-cli sync           # backfill recent days into ~/.oura-cli/oura.db
-oura-cli report         # weekly digest in the terminal
+oura-cli login    # paste your PAT — input is hidden, nothing echoes to the terminal
+oura-cli doctor   # confirm the token works and the local database is ready
+oura-cli sync     # first sync backfills the last 30 days; later syncs are incremental
+oura-cli report   # weekly digest in the terminal
 ```
 
-That's it. Subsequent `oura-cli sync` pulls only new days.
+Subsequent `oura-cli sync` only pulls new days, and `oura-cli db today` / `oura-cli db week` read the local cache instantly, no API call.
+
+### If something looks wrong
+
+| What you see | What to run |
+|---|---|
+| `No Oura data is available for this report yet.` | `oura-cli sync` |
+| `No Oura access token at ~/.oura-token` | `oura-cli login` |
+| `Oura API 401` | `oura-cli login` with a fresh PAT |
+| `db today` empty right after a sync | Normal — Oura publishes a day's summary after that night's sleep syncs from the ring. |
+| Anything else | `oura-cli doctor` |
 
 ## Daily use
 
@@ -58,7 +86,7 @@ oura-cli db date 2026-05-10
 
 ```bash
 oura-cli db week                  # local cache summary, no API hit
-oura-cli sleep week               # fresh sleep details direct from Oura
+oura-cli fetch sleep --days 7     # fresh sleep details direct from Oura
 ```
 
 ### Reports
@@ -77,26 +105,25 @@ oura-cli db trends 30             # score trends across the last 30 days
 oura-cli db stats                 # row counts, date range, personal bests
 ```
 
-### Per-endpoint detail
+### Raw API records
 
-When you want raw Oura V2 data, every endpoint shares the same shape — `today | date <day> | week`:
+`fetch` returns one collection straight from the Oura API as JSON, without touching the local cache.
 
 ```bash
-oura-cli sleep today
-oura-cli readiness date 2026-05-10
-oura-cli activity week
-oura-cli hr week
-oura-cli spo2 week
-oura-cli stress week
-oura-cli workout week
+oura-cli fetch sleep                       # today
+oura-cli fetch hr --days 7                 # last 7 days
+oura-cli fetch workout --from 2026-05-01 --to 2026-05-31
+oura-cli fetch sleep-periods --day 2026-06-01 | jq '.[] | {day, type, average_hrv}'
 ```
 
+Collections: `sleep readiness activity hr spo2 stress workout sleep-periods cv-age`.
+
 ### Piping to other tools
 
 Output auto-switches to JSON the moment you pipe it:
 
 ```bash
-oura-cli sleep week | jq '.[] | {day, score, hrv: .contributors.hrv_balance}'
+oura-cli fetch sleep --days 7 | jq '.[] | {day, score, hrv: .contributors.hrv_balance}'
 oura-cli db trends 90 > trends.json
 ```
 
@@ -146,7 +173,7 @@ If you're driving the CLI from a script or LLM harness:
 - `oura-cli healthcheck` — `{ok, version, latencyMs}` JSON for liveness probes.
 - Errors emit a stable JSON envelope on stderr: `{"error":{"code":"…","message":"…","hint":"…"}}`.
 - Documented exit codes: `0` success, `1` user error, `2` auth, `3` API, `4` storage.
-- JSON Schemas under [`docs/schemas/`](docs/schemas/) describe every output shape, semver-stable.
+- JSON Schemas under [`docs/schemas/`](docs/schemas/) describe every output shape, semver-stable. Per-collection schemas pin the identity fields (`id`, `day`, `timestamp`) and allow the rest of the Oura record through unchanged, so new upstream fields never break validation.
 
 Plays cleanly with [OpenClaw](https://github.com/openclaw/openclaw) — `oura-cli manifest` returns the tool-registry shape. A first-party `oura-mcp` companion is on the roadmap.