@drakulavich/oura-cli 0.4.5 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,93 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-09-05
+
+Fixes from the 0.5.0 exploratory testing sessions: the seam between citty and the command runner, and the sync window.
+
+### Changed
+- `sync` JSON: `import.counts` is replaced by `import.fetched` (rows the API returned per table) and `import.added` (net growth: days or samples the table did not hold before; a revised row for a day already stored counts as fetched, not new). The text summary prints `sleep 28 (+0)` in the same spirit, so a repeat run no longer looks like it imported 28 days. (#51)
+- `sync --from YYYY-MM-DD [--to YYYY-MM-DD]` re-fetches an explicit window for every collection, for recovery after an interrupted run or a deliberate backfill. `--to` defaults to today and requires `--from`. (#53)
+
+### Fixed
+- `sync` resumes every collection from its own last stored day instead of a single watermark taken from the three daily tables. A run interrupted after those tables (Ctrl-C, a crash) used to advance the watermark and leave the other six collections with a permanent gap that no later sync could fill. (#53)
+- First sync fetches exactly 30 inclusive days, as documented, not 31. (#46)
+- `fetch sleep-periods --day D` and `sync` no longer miss the requested day's sleep periods, and `fetch workout --from A --to B` no longer drops workouts on day B: Oura treats `start_date` as exclusive for `sleep` and `end_date` as exclusive for `workout`, and the request bounds are now shifted accordingly. (#58)
+- Two `oura-cli` processes on the same cache no longer fail with `database is locked`: connections wait up to 5 s for a lock, `PRAGMA journal_mode = WAL` is only issued when the file is not already in WAL mode (that statement itself needs an exclusive lock), and a lock that does outlast the wait reports a hint naming the cause. (#56)
+- `~/.oura-cli/` and a newly created cache file are created with `0700` / `0600` permissions, matching the token file; existing files are left alone. (#60)
+- `doctor --offline` reports the token check as `skip` rather than `ok`. The new status keeps `ok: true` and produces no next step, but an agent gating on the JSON can now tell "not checked" from "passed"; `docs/schemas/doctor.json` lists the value. (#59)
+- README: bundle size, the sync wording above, the token-missing message shape, and the `fetch sleep` pipe example, which read a readiness contributor (`hrv_balance`) off the sleep collection and printed `null` for every row. (#62)
+- A token containing whitespace or a line break (for example a token file with a second line) is rejected as `TOKEN_INVALID` (exit 2) naming the source; previously it reached the API layer and came back as `UNKNOWN` with the token quoted in the message. Every error message and hint is now passed through the secret redactor. (#47)
+- `DB_ERROR` (exit 4) is reachable: a corrupt cache file, an unusable `--db` path or a failing query in `db *`, `sync` and `report` now report `DB_ERROR` with a hint instead of `UNKNOWN` / exit 1. (#48)
+- Errors raised before a command runs — unknown command, missing positional, no command on a pipe — use the same envelope as every other error: JSON on stderr when piped, text on a TTY, nothing on stdout, `--no-color` honoured. The commands removed in 0.5.0 (`db reset`, `db import`, `sleep|readiness|activity|hr|spo2|stress|workout …`) point at `fetch`/`sync`. `--help` and a bare `oura-cli` on a TTY still show usage, and `--version` now answers even when other flags are present (it used to exit 1 with usage unless it was the only argument), but not when it sits in another flag's value position. (#49)
+- Undeclared flags and extra positionals are `BAD_ARGS` instead of being ignored, for every command including `describe`, `manifest`, `healthcheck` and `login`: `fetch sleep --dayz 7` no longer returns today's data with exit 0, and `db trends -5` no longer falls back to the 30-day default. (#50, part of #52)
+- Global flags placed before the subcommand are no longer moved past a `--` separator, and `oura-cli constructor` (any `Object.prototype` name) is an unknown command instead of a silent exit 0.
+
+## [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
@@ -242,6 +329,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Local SQLite cache at `~/.oura-cli/oura.db`.
 - Auth via `oura-cli login`, `OURA_TOKEN`, `OURA_TOKEN_PATH`, or `~/.oura-token`.
 
+[0.5.1]: https://github.com/drakulavich/oura-cli/releases/tag/v0.5.1
+[0.5.0]: https://github.com/drakulavich/oura-cli/releases/tag/v0.5.0
 [0.4.4]: https://github.com/drakulavich/oura-cli/releases/tag/v0.4.4
 [0.4.3]: https://github.com/drakulavich/oura-cli/releases/tag/v0.4.3
 [0.4.2]: https://github.com/drakulavich/oura-cli/releases/tag/v0.4.2

package/README.md

@@ -17,7 +17,7 @@
 - **Offline-first.** Everything caches into `~/.oura-cli/oura.db` after one `oura-cli sync`. Reports keep working when your internet doesn't.
 - **Real terminal reports.** `oura-cli report` writes a weekly or monthly digest with averages, trend deltas, and "you slept poorly Tuesday" callouts. No dashboards, no logging in.
 - **Pipe-friendly.** Output auto-switches to stable JSON when stdout isn't a terminal. Analyse with `jq`, plot with `gnuplot`, or feed it into your own scripts.
-- **Single 100 kB binary, MIT, no telemetry.** Built on Bun; zero native dependencies.
+- **Single ~110 kB binary, MIT, no telemetry.** Built on Bun; zero native dependencies.
 
 ## Install
 
@@ -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 fetches the last 30 days; later syncs resume from the last stored day
+oura-cli report   # weekly digest in the terminal
 ```
 
-That's it. Subsequent `oura-cli sync` pulls only new days.
+Subsequent `oura-cli sync` re-fetches each collection from its own last stored day (Oura revises recent days, so the overlap is deliberate) and reports rows fetched (+new). `oura-cli sync --from 2026-08-01 [--to 2026-08-07]` re-fetches an explicit window for every collection instead — for example after an interrupted sync. `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, deep: .contributors.deep_sleep}'
 oura-cli db trends 90 > trends.json
 ```
 
@@ -136,7 +163,7 @@ This tool reads your personal health data — handle the token with care.
 | Sleep model      | Oura V2 `sleep`               | `sleep_model`         |
 | Cardiovascular age | Oura V2 `cardiovascular_age` | `cardiovascular_age`  |
 
-Runtime: [Bun](https://bun.sh). Storage: built-in `bun:sqlite`. CLI parsing: [citty](https://github.com/unjs/citty). Output styling: [chalk](https://github.com/chalk/chalk). One 100 kB `dist/index.js`, no native deps.
+Runtime: [Bun](https://bun.sh). Storage: built-in `bun:sqlite`. CLI parsing: [citty](https://github.com/unjs/citty). Output styling: [chalk](https://github.com/chalk/chalk). One ~110 kB `dist/index.js`, no native deps.
 
 ## Automation (LLM agents, scripts, MCP)
 
@@ -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.