@drakulavich/oura-cli 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -6,6 +6,18 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-09-06
+
+### Fixed
+- `db trends N` covers N calendar days ending today; it used to include one day more than the heading claimed. (#52)
+- `report` no longer averages a day whose activity is still accumulating as if it were complete. A day counts as complete once it is over in the report timezone and the ring has uploaded past its end (the newest heart-rate sample in the cache is the proxy); activity and steps averages, the high-activity pattern and the steps recommendation stop at the last complete day, while sleep and readiness — final once they exist — still use the whole window. The partial day stays in the daily table, marked `*`, with one line explaining it. (#57)
+- A 401/403 from the Oura API carries a hint (`oura-cli login` with a fresh token), like a missing token already did. (#54)
+
+### Changed
+- `manifest`: `healthcheck.expects` lists the `error` field that `healthcheck` emits when `ok` is false. (#54)
+- `report` JSON: `days[].partial`, `completeThrough`, `lastUpload` and `averages[].count` are added; nothing is removed or renamed. (#57)
+- README's automation section no longer claims JSON Schemas for every output shape (they cover `fetch` and `doctor`), explains that `doctor` and `healthcheck` exit 0 with `ok: false` when the probe itself ran, and records two quirks kept for compatibility: `report --period month` returns `weekStart`/`weekEnd`, and `heartrate.day` is the date written in Oura's timestamp, UTC in practice. (#54)
+
 ## [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.
@@ -329,6 +341,7 @@ Fixes from the 0.5.0 exploratory testing sessions: the seam between citty and th
 - Local SQLite cache at `~/.oura-cli/oura.db`.
 - Auth via `oura-cli login`, `OURA_TOKEN`, `OURA_TOKEN_PATH`, or `~/.oura-token`.
 
+[0.5.2]: https://github.com/drakulavich/oura-cli/releases/tag/v0.5.2
 [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

package/README.md

@@ -96,7 +96,7 @@ oura-cli report                   # weekly (default)
 oura-cli report --period month    # 30-day window with weekly buckets
 ```
 
-Reports cover daily scores, averages, deltas vs the previous window, sleep details, and a short recommendation block.
+Reports cover daily scores, averages, deltas vs the previous window, sleep details, and a short recommendation block. A day whose activity is still accumulating (today, or the last day before the ring stopped syncing) is shown with a `*` and kept out of the activity averages and recommendations; the JSON says so via `days[].partial` and `completeThrough`.
 
 ### Trends and stats
 
@@ -170,10 +170,12 @@ Runtime: [Bun](https://bun.sh). Storage: built-in `bun:sqlite`. CLI parsing: [ci
 If you're driving the CLI from a script or LLM harness:
 
 - `oura-cli describe` — JSON manifest of every command, argument, and output schema. Agents discover capabilities without scraping `--help`.
-- `oura-cli healthcheck` — `{ok, version, latencyMs}` JSON for liveness probes.
+- `oura-cli healthcheck` — `{ok, version, latencyMs}` JSON for liveness probes, plus `error` when `ok` is false.
+- Gate on `.ok`, not on the exit code: `doctor` exits 0 with `ok: false` for any warning-level check (no data yet, stale data, Oura API unreachable), and `healthcheck` exits 0 with `ok: false` for an unusable database (the probe itself ran). `doctor --offline` skips the token-validation call, and a skipped check still counts towards `ok`.
 - 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. 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.
+- JSON Schemas under [`docs/schemas/`](docs/schemas/) cover `fetch <collection>`, `doctor` and the `describe` manifest itself, semver-stable; `describe` names the schema next to each command. 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. The local-data commands (`sync`, `db *`, `report`) have no schema files yet; their shapes are versioned through the CHANGELOG.
+- Two contract quirks, kept for compatibility: `report --period month` returns its window as `weekStart`/`weekEnd`, and `heartrate.day` in the cache is the date written in Oura's timestamp (UTC in practice) while every `--day`/`--tz` argument is local.
 
 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.
 

package/dist/index.js

@@ -1438,7 +1438,7 @@ class OuraClient {
       const redacted = redactSecrets(rawBody);
       const body = redacted.length > 200 ? redacted.slice(0, 200) + "\u2026 (truncated)" : redacted;
       if (response.status === 401 || response.status === 403) {
-        throw new CliError("TOKEN_INVALID", `Oura API ${response.status}: ${body}`);
+        throw new CliError("TOKEN_INVALID", `Oura API ${response.status}: ${body}`, "Run `oura-cli login` with a fresh Personal Access Token, or check OURA_TOKEN.");
       }
       throw new CliError("API_ERROR", `Oura API ${response.status}: ${body}`);
     }
@@ -2092,7 +2092,7 @@ async function fetchCollection(client, c, start, end, tz) {
 }
 
 // src/commands/describe.ts
-var OUTPUT_SCHEMAS = { doctor: "docs/schemas/doctor.json" };
+var OUTPUT_SCHEMAS = { doctor: "docs/schemas/doctor.json", describe: "docs/schemas/describe.json" };
 var ENUM_ARGS = {
   fetch: { collection: names() },
   report: { period: ["week", "month"] }
@@ -2255,7 +2255,7 @@ function getDaySummary(db, day) {
   };
 }
 function getTrends(db, days, today) {
-  const start = shiftDay(today, -days);
+  const start = shiftDay(today, -(days - 1));
   const results = [];
   const metrics = [
     ["Sleep Score", "daily_sleep", "score"],
@@ -2513,15 +2513,19 @@ function dayLabel(dateStr) {
   const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
   return `${day} ${dd}/${mm}`;
 }
-function getReport(db, days, today) {
+function getReport(db, days, today, tz = "UTC") {
   const period = days <= 7 ? "week" : "month";
   const weekEnd = today;
   const weekStart = shiftDay(today, -(days - 1));
   const prevWeekEnd = shiftDay(today, -days);
   const prevWeekStart = shiftDay(today, -(days * 2 - 1));
+  const windowDays = daysBack(today, days);
+  const lastUpload = db.query("SELECT MAX(timestamp) AS t FROM heartrate").get().t;
+  const isComplete = (d) => d < today && (lastUpload === null || Date.parse(localDateToUtcRange(d, tz)[1]) <= Date.parse(lastUpload));
+  const completeThrough = [...windowDays].reverse().find(isComplete) ?? null;
+  const activityEnd = completeThrough ?? shiftDay(weekStart, -1);
   const dailyRows = [];
-  for (let i = days - 1;i >= 0; i--) {
-    const d = shiftDay(today, -i);
+  for (const d of windowDays) {
     const sl = db.query("SELECT score FROM daily_sleep WHERE day=?").get(d);
     const rd = db.query("SELECT score FROM daily_readiness WHERE day=?").get(d);
     const ac = db.query("SELECT score, steps FROM daily_activity WHERE day=?").get(d);
@@ -2531,7 +2535,8 @@ function getReport(db, days, today) {
       sleep: sl?.score ?? null,
       readiness: rd?.score ?? null,
       activity: ac?.score ?? null,
-      steps: ac?.steps ?? null
+      steps: ac?.steps ?? null,
+      partial: ac != null && !isComplete(d)
     });
   }
   const metrics = [
@@ -2542,7 +2547,8 @@ function getReport(db, days, today) {
   ];
   const averages = [];
   for (const [label, table, col, isSteps] of metrics) {
-    const curr = db.query(`SELECT AVG(${col}) as avg, MIN(${col}) as min, MAX(${col}) as max, COUNT(${col}) as cnt FROM ${table} WHERE day BETWEEN ? AND ?`).get(weekStart, weekEnd);
+    const end = table === "daily_activity" ? activityEnd : weekEnd;
+    const curr = db.query(`SELECT AVG(${col}) as avg, MIN(${col}) as min, MAX(${col}) as max, COUNT(${col}) as cnt FROM ${table} WHERE day BETWEEN ? AND ?`).get(weekStart, end);
     const prev = db.query(`SELECT AVG(${col}) as avg FROM ${table} WHERE day BETWEEN ? AND ?`).get(prevWeekStart, prevWeekEnd);
     if (curr.cnt > 0 && curr.avg !== null) {
       const diff = prev.avg !== null ? curr.avg - prev.avg : null;
@@ -2551,6 +2557,7 @@ function getReport(db, days, today) {
         avg: curr.avg,
         min: curr.min,
         max: curr.max,
+        count: curr.cnt,
         prevAvg: prev.avg,
         diff,
         isSteps
@@ -2561,7 +2568,7 @@ function getReport(db, days, today) {
   const spo2 = sp.cnt > 0 && sp.avg !== null ? { avg: +sp.avg.toFixed(1), min: +sp.min.toFixed(1), max: +sp.max.toFixed(1) } : null;
   const lowSleep = db.query("SELECT day, score FROM daily_sleep WHERE day BETWEEN ? AND ? AND score < 70 ORDER BY score").all(weekStart, weekEnd).map((r) => ({ ...r, dayLabel: dayLabel(r.day) }));
   const lowReadiness = db.query("SELECT day, score FROM daily_readiness WHERE day BETWEEN ? AND ? AND score < 70 ORDER BY score").all(weekStart, weekEnd).map((r) => ({ ...r, dayLabel: dayLabel(r.day) }));
-  const highActivity = db.query("SELECT day, score, steps FROM daily_activity WHERE day BETWEEN ? AND ? AND score >= 90 ORDER BY score DESC").all(weekStart, weekEnd).map((r) => ({ ...r, dayLabel: dayLabel(r.day) }));
+  const highActivity = db.query("SELECT day, score, steps FROM daily_activity WHERE day BETWEEN ? AND ? AND score >= 90 ORDER BY score DESC").all(weekStart, activityEnd).map((r) => ({ ...r, dayLabel: dayLabel(r.day) }));
   const sd = db.query(`SELECT AVG(total_sleep_duration) as totalSleep, AVG(deep_sleep_duration) as deepSleep,
             AVG(rem_sleep_duration) as remSleep, AVG(light_sleep_duration) as lightSleep,
             AVG(efficiency) as efficiency, AVG(average_hrv) as hrv, AVG(lowest_heart_rate) as lowestHr
@@ -2570,7 +2577,7 @@ function getReport(db, days, today) {
   const recommendations = [];
   const avgSleep = db.query("SELECT AVG(score) as avg FROM daily_sleep WHERE day BETWEEN ? AND ?").get(weekStart, weekEnd);
   const avgReady = db.query("SELECT AVG(score) as avg FROM daily_readiness WHERE day BETWEEN ? AND ?").get(weekStart, weekEnd);
-  const avgSteps = db.query("SELECT AVG(steps) as avg FROM daily_activity WHERE day BETWEEN ? AND ?").get(weekStart, weekEnd);
+  const avgSteps = db.query("SELECT AVG(steps) as avg FROM daily_activity WHERE day BETWEEN ? AND ?").get(weekStart, activityEnd);
   if (avgSleep.avg !== null && avgSleep.avg < 75) {
     recommendations.push("sleep_low");
   } else if (avgSleep.avg !== null && avgSleep.avg >= 85) {
@@ -2586,7 +2593,7 @@ function getReport(db, days, today) {
   } else if (avgSteps.avg !== null && avgSteps.avg >= 1e4) {
     recommendations.push("steps_great");
   }
-  return { period, weekStart, weekEnd, days: dailyRows, averages, spo2, patterns: { lowSleep, lowReadiness, highActivity }, sleepDetails, recommendations };
+  return { period, weekStart, weekEnd, days: dailyRows, completeThrough, lastUpload, averages, spo2, patterns: { lowSleep, lowReadiness, highActivity }, sleepDetails, recommendations };
 }
 
 // src/render/format-report.ts
@@ -2642,12 +2649,24 @@ function bucketDaysIntoWeeks(days) {
       avgSleep: sleepVals.length > 0 ? sleepVals.reduce((a, b) => a + b, 0) / sleepVals.length : null,
       avgReadiness: readinessVals.length > 0 ? readinessVals.reduce((a, b) => a + b, 0) / readinessVals.length : null,
       avgActivity: activityVals.length > 0 ? activityVals.reduce((a, b) => a + b, 0) / activityVals.length : null,
-      totalSteps: stepsVals.length > 0 ? stepsVals.reduce((a, b) => a + b, 0) : null
+      totalSteps: stepsVals.length > 0 ? stepsVals.reduce((a, b) => a + b, 0) : null,
+      partial: chunk.some((d) => d.partial)
     });
   }
   return buckets;
 }
-function formatReport(data, format, period) {
+function partialDayNote(data, tz) {
+  const partial = data.days.filter((d) => d.partial);
+  if (partial.length === 0)
+    return null;
+  const newest = partial[partial.length - 1];
+  const newestLabel = newest.day === data.weekEnd ? "today" : newest.dayLabel;
+  const which = partial.length === 1 ? `${newestLabel} is` : `${newestLabel} and ${partial.length - 1} earlier day${partial.length > 2 ? "s" : ""} are`;
+  const synced = data.lastUpload ? `ring last synced ${formatLocal(data.lastUpload, tz)}` : "ring sync time unknown";
+  const covers = data.completeThrough ? `through ${data.completeThrough}` : "no complete day yet";
+  return `  * ${which} still accumulating (${synced}); activity averages cover ${covers}.`;
+}
+function formatReport(data, format, period, tz = "UTC") {
   if (format === "json")
     return JSON.stringify(data, null, 2);
   const lines = [];
@@ -2658,6 +2677,9 @@ function formatReport(data, format, period) {
     lines.push(source_default.bold("  Oura Monthly Report"));
   }
   lines.push(source_default.gray(`  ${data.weekStart} \u2014 ${data.weekEnd}`));
+  const note = partialDayNote(data, tz);
+  if (note)
+    lines.push(source_default.yellow(note));
   lines.push("");
   const hasReportData = data.days.some((day) => day.sleep !== null || day.readiness !== null || day.activity !== null || day.steps !== null) || data.averages.length > 0 || data.spo2 !== null || data.sleepDetails !== null;
   if (!hasReportData) {
@@ -2673,7 +2695,7 @@ function formatReport(data, format, period) {
     lines.push(`  ${"Day".padEnd(10)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Active".padStart(7)} ${"Steps".padStart(8)}`);
     lines.push(source_default.gray("  " + "\u2500".repeat(52)));
     for (const d of data.days) {
-      lines.push(`  ${d.dayLabel.padEnd(10)} ${scoreCell(d.sleep, 6)} ${scoreCell(d.readiness, 6)} ${scoreCell(d.activity, 7)} ${stepsCell(d.steps, 8)}`);
+      lines.push(`  ${(d.partial ? d.dayLabel + "*" : d.dayLabel).padEnd(10)} ${scoreCell(d.sleep, 6)} ${scoreCell(d.readiness, 6)} ${scoreCell(d.activity, 7)} ${stepsCell(d.steps, 8)}`);
     }
     lines.push("");
   } else {
@@ -2686,7 +2708,7 @@ function formatReport(data, format, period) {
       const avgSleepInt = b.avgSleep !== null ? Math.round(b.avgSleep) : null;
       const avgReadyInt = b.avgReadiness !== null ? Math.round(b.avgReadiness) : null;
       const avgActiveInt = b.avgActivity !== null ? Math.round(b.avgActivity) : null;
-      lines.push(`  ${b.weekOf.padEnd(12)} ${scoreCell(avgSleepInt, 6)} ${scoreCell(avgReadyInt, 6)} ${scoreCell(avgActiveInt, 7)} ${stepsCell(b.totalSteps, 10)}`);
+      lines.push(`  ${(b.partial ? b.weekOf + "*" : b.weekOf).padEnd(12)} ${scoreCell(avgSleepInt, 6)} ${scoreCell(avgReadyInt, 6)} ${scoreCell(avgActiveInt, 7)} ${stepsCell(b.totalSteps, 10)}`);
     }
     lines.push("");
   }
@@ -2747,15 +2769,15 @@ var reportCommand = dataCommand({
     if (period !== "week" && period !== "month") {
       throw new CliError("BAD_ARGS", `--period must be "week" or "month", got "${period}".`);
     }
-    const data = getReport(ctx.db, period === "week" ? 7 : 30, ctx.today);
-    return { json: data, text: () => formatReport(data, "table", period) };
+    const data = getReport(ctx.db, period === "week" ? 7 : 30, ctx.today, ctx.tz);
+    return { json: data, text: () => formatReport(data, "table", period, ctx.tz) };
   }
 });
 
 // src/commands/healthcheck.ts
 function healthcheckCommand(version) {
   return defineCommand({
-    meta: { name: "healthcheck", description: "Quick local DB health probe (JSON: {ok, version, latencyMs})." },
+    meta: { name: "healthcheck", description: "Quick local DB health probe (JSON: {ok, version, latencyMs}, plus error when ok is false)." },
     args: { ...commonArgs },
     run({ args }) {
       assertKnownArgs(commonArgs, args);
@@ -2919,7 +2941,7 @@ function buildOpenclawManifest(version, commands) {
       examples: EXAMPLES[c.name] ?? [`oura-cli ${c.name}`]
     })),
     envVars: ["OURA_TOKEN", "OURA_TOKEN_PATH", "OURA_DB_PATH", "OURA_TZ"],
-    healthcheck: { command: "healthcheck", expects: { ok: "boolean", version: "string", latencyMs: "number" } }
+    healthcheck: { command: "healthcheck", expects: { ok: "boolean", version: "string", latencyMs: "number", error: "string, present only when ok is false" } }
   };
 }
 function manifestCommand(version, getCommands) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/oura-cli",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Oura Ring CLI — query and analyze Oura Ring health data from the command line, designed for humans and AI agents.",
   "keywords": [
     "oura",