@drakulavich/oura-cli 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-09
+
+### Added
+- `sync --prune=<collections>` applies removals the truncation guard refuses. The guard keeps rows when a response drops most of what one request described, which is right for a partial or short answer and wrong for a genuine large correction — and it cannot tell them apart, so a genuine one was refused on every run with no way through. Narrowing the window did not help: the scope is the returned rows' own bounds, so the ratio never moved, and `sync --from D --to D` refused identically. The flag is the user's answer to the question the guard cannot ask, per run and never stored.
+
+  It is scoped to the collections named because consent is per collection: the refusal message names the collection to pass (`re-run with --prune=hr`), so lifting the guard for one does not lift it for another that answers short in the same run — a loss that never comes back behind `--from`, since the next ordinary sync resumes from the watermark. `--prune=all` covers every collection; a valueless `--prune` is refused, because as a string flag it would otherwise swallow whatever came next on the line. Removals that went past the guard are counted separately from ordinary reconciliation, in the JSON as `pruned` and on the collection line as `(N past the truncation guard)`, so a bypass is never silent. `refused` and `pruned` carry the collection name alongside the count (`{rows, collection}`), because they are the only fields that imply a follow-up command and the command takes a name the table-keyed payload did not contain — `sync` is JSON-only off a TTY, and an agent that cannot map `heartrate` back to `hr` would reach for `--prune=all`. A run that passed the flag also records `pruneScope`, so a kept JSON log can say whether the guard was lifted and over what. A piece that returns nothing still removes nothing, flag or not. Where two pieces overlap, every piece covering a row is consulted before that row is decided, and one doubting piece is enough to keep it — a verdict taken while walking the pieces would have been settled by whichever came first, so the same responses in a different order could delete a row instead of keeping it. (#100)
+
+### Fixed
+- `sync` kept both rows when Oura reclassified a heart-rate sample (`awake` → `workout` shares the timestamp, and the unique index is `(timestamp, source)`), and no command could repair it. A re-fetched window is now reconciled against the response: rows the API no longer has are removed, inside the same transaction as the inserts. Verified on a copy of a real cache, where it removed exactly the five stale samples the exploratory session had found. (#91)
+- The same for the five tables whose `day` is not unique (`sleep_model`, `workouts`, `sessions`, `rest_mode_periods`, `enhanced_tags`): a record re-issued under a new id used to leave both rows, so `report` averaged one night twice. The scope of a removal always comes from the response and from one request at a time — a range wider than the endpoint allows is fetched in pieces, and a piece that answers with nothing describes nothing, so its days keep their rows. A piece whose answer would drop most of what is stored for it is treated as truncated: the removal is refused and reported. (#71)
+- `sync` reports `removed` and `refused` per table in its JSON, and the progress line says how many stale rows went and how many were kept because the response looked truncated.
+- `ensureSchema` read the schema version and applied migrations with nothing serialising the two, so concurrent commands recorded the same migration several times — harmless only while every migration is `CREATE ... IF NOT EXISTS`, and a hard failure for the loser as soon as one is an `ALTER TABLE`. Check and apply now run under `BEGIN IMMEDIATE`. Two processes creating the same cache also raced on `PRAGMA journal_mode = WAL`, which answers `SQLITE_BUSY` without waiting out `busy_timeout`; losing that race is no longer an error, since the winner set the mode this process wanted. (#77)
+- A misspelled global flag left its value in the command position, so the CLI reported the value as the command name — and for `--tok <token>` that put a Personal Access Token into an error message. A near miss of a known flag is now blamed on the flag (`Unknown flag "--tok". Did you mean --token?`), and a value that cannot be a command name is never quoted back. (#95)
+- An empty `--token` or `OURA_TOKEN` fell through to the token file, so a wrapper expanding an unset variable authenticated as whoever that file holds; an empty `OURA_TZ` fell through to the system zone and shifted every day boundary silently. Both are now `BAD_ARGS`, like the `--db` case fixed in 0.6.0, through one shared guard. (#92)
+- A database in a directory the user cannot write reported `attempt to write a readonly database` with a hint about the file's format. The file is fine; SQLite needs to create `-wal` and `-shm` beside it. Permission failures now get their own hint. (#78)
+- `doctor` runs SQLite's `quick_check` and reports it as a new `integrity` check, so a cache with a damaged page is named instead of passing every command until something touches the broken page. `doctor` also survives reading a corrupt cache rather than crashing part-way through its own checks, and `healthcheck`'s description now says it proves the file opens, not that its contents are intact. (#78)
+
 ## [0.6.0] - 2026-09-06
 
 ### Fixed

package/README.md

@@ -54,7 +54,7 @@ oura-cli sync     # first sync fetches the last 30 days; later syncs resume from
 oura-cli report   # weekly digest in the terminal
 ```
 
-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). Heart rate goes back two weeks each time, because Oura publishes workout samples days after the day they belong to. `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.
+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). Heart rate goes back two weeks each time, because Oura publishes workout samples days after the day they belong to. A re-fetched window ends up holding exactly what the API returned for it: a sample Oura reclassified, or a record it re-issued under a new id, replaces the row it supersedes instead of joining it. When a response drops most of what one request covered — the shape of a partial or short answer — those rows are kept rather than deleted, and `sync` names the collection and how many. `oura-cli sync --prune=hr` then applies them for that collection once you have judged the correction genuine; `oura-cli sync --prune=all` does it for every collection in the run, which also lifts the guard on any collection that answers short in the same run. `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
 
@@ -183,7 +183,7 @@ 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, plus `error` when `ok` is false.
+- `oura-cli healthcheck` — `{ok, version, latencyMs}` JSON for liveness probes, plus `error` when `ok` is false. It proves the database opens and answers a query; it does not inspect the contents. `oura-cli doctor` runs SQLite's `quick_check` for that.
 - 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.

package/dist/index.js

@@ -1198,6 +1198,14 @@ import { resolve, dirname } from "path";
 import { homedir } from "os";
 import { chmodSync, existsSync, mkdirSync } from "fs";
 
+// src/lib/require-value.ts
+function requireValue(value, source, fallback) {
+  if (value.trim() === "") {
+    throw new CliError("BAD_ARGS", `${source} has no value`, `Pass a value, or remove ${source} to fall back to ${fallback}.`);
+  }
+  return value;
+}
+
 // src/db/migrations.ts
 var MIGRATIONS = [
   {
@@ -1405,27 +1413,30 @@ CREATE INDEX IF NOT EXISTS idx_ring_battery_level_day ON ring_battery_level(day)
 // src/db/open.ts
 var DB_HINT = "Check the path in --db / OURA_DB_PATH and that the file is a SQLite database oura-cli created.";
 var BUSY_HINT = "Another oura-cli process is using this database; wait for it to finish and retry.";
+var PERMISSION_HINT = "Check that you can write both the file and the directory holding it \u2014 SQLite creates -wal and -shm files alongside the database.";
 var BUSY_TIMEOUT_MS = 5000;
+var WAL_SWITCH_ATTEMPTS = 20;
+var WAL_SWITCH_WAIT_MS = 25;
+function hintFor(detail) {
+  if (/database is locked|SQLITE_BUSY/i.test(detail))
+    return BUSY_HINT;
+  if (/readonly database|read-only|EACCES|permission denied|unable to open database file/i.test(detail))
+    return PERMISSION_HINT;
+  return DB_HINT;
+}
 function dbError(what, err) {
   const detail = err instanceof Error ? err.message : String(err);
-  const hint = /database is locked|SQLITE_BUSY/i.test(detail) ? BUSY_HINT : DB_HINT;
-  return new CliError("DB_ERROR", `${what}: ${detail}`, hint);
+  return new CliError("DB_ERROR", `${what}: ${detail}`, hintFor(detail));
 }
 function asDbError(err) {
   return err instanceof SQLiteError ? dbError("Database query failed", err) : undefined;
 }
-function requirePath(value, source) {
-  if (value.trim() === "") {
-    throw new CliError("BAD_ARGS", `${source} has no path`, `Pass a path to a SQLite file, or remove ${source} to fall back to the default database.`);
-  }
-  return value;
-}
 function getDbPath(explicit) {
   if (explicit !== undefined)
-    return requirePath(explicit, "--db");
+    return requireValue(explicit, "--db", "the default database");
   const fromEnv = process.env.OURA_DB_PATH;
   if (fromEnv !== undefined)
-    return requirePath(fromEnv, "OURA_DB_PATH");
+    return requireValue(fromEnv, "OURA_DB_PATH", "the default database");
   return resolve(homedir(), ".oura-cli", "oura.db");
 }
 function openDatabase(explicit) {
@@ -1439,15 +1450,31 @@ function openDatabase(explicit) {
     if (isNew)
       chmodSync(dbPath, 384);
     db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
-    const mode = db.query("PRAGMA journal_mode").get();
-    if (mode.journal_mode !== "wal")
-      db.exec("PRAGMA journal_mode = WAL");
+    if (journalMode(db) !== "wal")
+      enableWal(db);
     db.exec("PRAGMA foreign_keys = ON");
     return db;
   } catch (err) {
     throw dbError(`Cannot open database ${dbPath}`, err);
   }
 }
+function journalMode(db) {
+  return db.query("PRAGMA journal_mode").get().journal_mode;
+}
+function enableWal(db) {
+  for (let attempt = 0;; attempt++) {
+    try {
+      db.exec("PRAGMA journal_mode = WAL");
+      return;
+    } catch (err) {
+      if (journalMode(db) === "wal")
+        return;
+      if (attempt >= WAL_SWITCH_ATTEMPTS)
+        throw err;
+      Bun.sleepSync(WAL_SWITCH_WAIT_MS + Math.random() * WAL_SWITCH_WAIT_MS);
+    }
+  }
+}
 function schemaVersion(db) {
   db.exec("CREATE TABLE IF NOT EXISTS _schema_version (version INTEGER NOT NULL)");
   const row = db.query("SELECT MAX(version) AS v FROM _schema_version").get();
@@ -1455,12 +1482,23 @@ function schemaVersion(db) {
 }
 function ensureSchema(db, migrations = MIGRATIONS) {
   try {
-    const current = schemaVersion(db);
-    for (const m of migrations) {
-      if (m.version > current) {
-        db.exec(m.sql);
-        db.query("INSERT INTO _schema_version (version) VALUES (?)").run(m.version);
+    if (schemaVersion(db) >= Math.max(0, ...migrations.map((m) => m.version)))
+      return;
+    db.exec("BEGIN IMMEDIATE");
+    try {
+      const current = schemaVersion(db);
+      for (const m of migrations) {
+        if (m.version > current) {
+          db.exec(m.sql);
+          db.query("INSERT INTO _schema_version (version) VALUES (?)").run(m.version);
+        }
       }
+      db.exec("COMMIT");
+    } catch (err) {
+      try {
+        db.exec("ROLLBACK");
+      } catch {}
+      throw err;
     }
   } catch (err) {
     throw dbError("Schema migration failed", err);
@@ -1475,10 +1513,11 @@ function defaultTokenPath() {
   return process.env.OURA_TOKEN_PATH ?? resolve2(homedir2(), ".oura-token");
 }
 function resolveToken(explicit, tokenPath) {
-  if (explicit)
-    return { token: explicit.trim(), source: "--token" };
-  if (process.env.OURA_TOKEN)
-    return { token: process.env.OURA_TOKEN.trim(), source: "OURA_TOKEN" };
+  if (explicit !== undefined)
+    return { token: requireValue(explicit, "--token", "the token file").trim(), source: "--token" };
+  const fromEnv = process.env.OURA_TOKEN;
+  if (fromEnv !== undefined)
+    return { token: requireValue(fromEnv, "OURA_TOKEN", "the token file").trim(), source: "OURA_TOKEN" };
   const path = tokenPath ?? defaultTokenPath();
   try {
     return { token: readFileSync(path, "utf-8").trim(), source: path };
@@ -1685,8 +1724,9 @@ function localDateToUtcRange(localDate, timezone) {
   return [iso(localMidnightMs(localDate, timezone)), iso(localMidnightMs(shiftDay(localDate, 1), timezone))];
 }
 function resolveDefaultTimezone() {
-  if (process.env.OURA_TZ)
-    return process.env.OURA_TZ;
+  const fromEnv = process.env.OURA_TZ;
+  if (fromEnv !== undefined)
+    return requireValue(fromEnv, "OURA_TZ", "the system timezone");
   try {
     return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
   } catch {
@@ -2374,13 +2414,15 @@ function rangeQueries(c, start, end, tz) {
     return [];
   return c.rangeParams === "date" ? dateQueries(start, end, c.maxRangeDays, c.dayRangeOffset ?? [0, 0]) : datetimeQueries(start, end, tz, c.maxRangeDays);
 }
-async function fetchCollection(client, c, start, end, tz) {
-  const rows = [];
+async function fetchCollectionByPiece(client, c, start, end, tz) {
+  const pieces = [];
   for (const query of rangeQueries(c, start, end, tz)) {
-    for (const row of await client.fetch(c.endpoint, query))
-      rows.push(row);
+    pieces.push(await client.fetch(c.endpoint, query));
   }
-  return rows;
+  return pieces;
+}
+async function fetchCollection(client, c, start, end, tz) {
+  return (await fetchCollectionByPiece(client, c, start, end, tz)).flat();
 }
 
 // src/commands/describe.ts
@@ -2482,15 +2524,116 @@ function describeCommand(version, getCommands) {
   });
 }
 
+// src/db/reconcile.ts
+function identityColumns(c) {
+  const unique = c.columns.filter((col) => col.unique).map((col) => col.name);
+  if (unique.length > 0)
+    return unique;
+  const pk = c.columns.filter((col) => col.pk).map((col) => col.name);
+  if (pk.length > 0)
+    return pk;
+  return (c.indexes ?? []).find((i) => i.unique)?.columns ?? [];
+}
+var MAX_REMOVED_SHARE = 0.5;
+var ALWAYS_SAFE_TO_REMOVE = 5;
+var KEY_SEPARATOR = "\x00";
+function emptyPlan() {
+  return { added: 0, stale: [], refused: 0, bypassed: 0 };
+}
+function keyOf(values) {
+  return values.map((v) => String(v)).join(KEY_SEPARATOR);
+}
+function planWindow(db, c, pieces, options = {}) {
+  const identity = identityColumns(c);
+  if (identity.length === 0)
+    return emptyPlan();
+  const pickOf = (name) => c.columns.find((col) => col.name === name)?.pick;
+  const identityPicks = identity.map(pickOf);
+  const scopeName = c.rangeParams === "datetime" ? "timestamp" : "day";
+  const scopePick = pickOf(scopeName);
+  if (scopePick === undefined || identityPicks.some((p) => p === undefined))
+    return emptyPlan();
+  const keyFor = (row) => keyOf(identityPicks.map((pick) => pick(row)));
+  const wanted = new Set(pieces.flat().map(keyFor));
+  const plan = emptyPlan();
+  const judged = pieces.map((piece) => {
+    if (piece.length === 0)
+      return null;
+    const scopeValues = piece.map((row) => scopePick(row)).filter((v) => v !== null && v !== undefined).map(String);
+    if (scopeValues.length === 0)
+      return null;
+    const days = [...new Set(scopeValues)];
+    const [where, params] = c.rangeParams === "datetime" ? [`${scopeName} BETWEEN ? AND ?`, [minOf(scopeValues), maxOf(scopeValues)]] : [`${scopeName} IN (${days.map(() => "?").join(", ")})`, days];
+    const stored = db.query(`SELECT ${identity.join(", ")} FROM ${c.table} WHERE ${where}`).all(...params);
+    const storedKeys = new Set;
+    const stale = [];
+    for (const row of stored) {
+      const values = identity.map((name) => row[name] ?? null);
+      const key = keyOf(values);
+      storedKeys.add(key);
+      if (!wanted.has(key))
+        stale.push(values);
+    }
+    const looksTruncated = stale.length > ALWAYS_SAFE_TO_REMOVE && stale.length > stored.length * MAX_REMOVED_SHARE;
+    const fresh = [...new Set(piece.map(keyFor))].filter((key) => !storedKeys.has(key));
+    return { stale, looksTruncated, fresh };
+  });
+  const doubted = new Set;
+  for (const p of judged) {
+    if (p?.looksTruncated)
+      for (const values of p.stale)
+        doubted.add(keyOf(values));
+  }
+  const countedNew = new Set;
+  const countedStale = new Set;
+  for (const p of judged) {
+    if (p === null)
+      continue;
+    for (const key of p.fresh) {
+      if (countedNew.has(key))
+        continue;
+      countedNew.add(key);
+      plan.added += 1;
+    }
+    for (const values of p.stale) {
+      const key = keyOf(values);
+      if (countedStale.has(key))
+        continue;
+      countedStale.add(key);
+      if (doubted.has(key) && !options.prune) {
+        plan.refused += 1;
+      } else {
+        if (doubted.has(key))
+          plan.bypassed += 1;
+        plan.stale.push(values);
+      }
+    }
+  }
+  return plan;
+}
+function applyWindowPlan(db, c, plan) {
+  if (plan.stale.length === 0)
+    return 0;
+  const identity = identityColumns(c);
+  const del = db.query(`DELETE FROM ${c.table} WHERE ${identity.map((name) => `${name} IS ?`).join(" AND ")}`);
+  let removed = 0;
+  for (const values of plan.stale)
+    removed += del.run(...values).changes;
+  return removed;
+}
+function minOf(values) {
+  return values.reduce((a, b) => b < a ? b : a);
+}
+function maxOf(values) {
+  return values.reduce((a, b) => b > a ? b : a);
+}
+
 // src/db/sync.ts
 var BACKFILL_DAYS = 30;
 function lastDay(db, table, end) {
   return db.query(`SELECT MAX(day) AS d FROM ${table} WHERE day <= ?`).get(end).d;
 }
-function rowCount(db, table) {
-  return db.query(`SELECT COUNT(*) AS n FROM ${table}`).get().n;
-}
-async function importDaily(db, client, clock, log, window = {}) {
+async function importDaily(db, client, clock, log, window = {}, options = {}) {
   const { today, tz } = clock;
   const _log = log ?? (() => {});
   const end = window.to ?? today;
@@ -2505,10 +2648,19 @@ async function importDaily(db, client, clock, log, window = {}) {
   const isFirstSync = ranged.every((p) => p.last === null);
   const startDate = ranged.map((p) => p.resume).sort()[0];
   _log(isFirstSync && window.from === undefined ? `First sync \u2014 backfilling the last ${BACKFILL_DAYS} days: ${startDate} \u2192 ${end}` : `Syncing ${startDate} \u2192 ${end}`);
+  if (options.prune !== undefined) {
+    const scope = options.prune === "all" ? "every collection" : options.prune.join(", ");
+    _log(`--prune: applying removals even where a response looks truncated (${scope})`);
+  }
   const fetched = {};
   const added = {};
+  const removed = {};
+  const refused = {};
+  const pruned = {};
+  const mayPrune = (name) => options.prune === "all" || (options.prune?.includes(name) ?? false);
   for (const { c, start } of plan) {
-    const rows = await fetchCollection(client, c, start, end, tz);
+    const pieces = await fetchCollectionByPiece(client, c, start, end, tz);
+    const rows = pieces.flat();
     const stmt = db.query(insertSql(c));
     if (c.rangeParams === "none") {
       const pk = c.columns.find((col) => col.pk)?.name;
@@ -2526,17 +2678,37 @@ async function importDaily(db, client, clock, log, window = {}) {
       _log(`  + ${c.name} (${c.table}): ${rows.length} fetched, ${added[c.table]} new${rows.length === 0 ? ", table cleared" : ""}`);
       continue;
     }
-    const before = rowCount(db, c.table);
-    db.transaction((rs) => {
-      for (const r of rs)
-        stmt.run(...rowValues(c, r));
-    })(rows);
+    const { windowPlan, gone } = db.transaction((ps) => {
+      const windowPlan = planWindow(db, c, ps, { prune: mayPrune(c.name) });
+      for (const piece of ps)
+        for (const r of piece)
+          stmt.run(...rowValues(c, r));
+      return { windowPlan, gone: applyWindowPlan(db, c, windowPlan) };
+    }).immediate(pieces);
     fetched[c.table] = rows.length;
-    added[c.table] = rowCount(db, c.table) - before;
-    _log(`  + ${c.name} (${c.table}): ${rows.length} fetched, ${added[c.table]} new`);
+    added[c.table] = windowPlan.added;
+    if (gone > 0)
+      removed[c.table] = gone;
+    if (windowPlan.refused > 0)
+      refused[c.table] = { rows: windowPlan.refused, collection: c.name };
+    if (windowPlan.bypassed > 0)
+      pruned[c.table] = { rows: windowPlan.bypassed, collection: c.name };
+    const tail = gone > 0 ? `, ${gone} stale removed${windowPlan.bypassed > 0 ? ` (${windowPlan.bypassed} past the truncation guard)` : ""}` : "";
+    const kept = windowPlan.refused > 0 ? `, ${windowPlan.refused} rows kept that the API did not return \u2014 too many to drop on one response; re-run with --prune=${c.name} to apply them` : "";
+    _log(`  + ${c.name} (${c.table}): ${rows.length} fetched, ${added[c.table]} new${tail}${kept}`);
   }
   _log("Import complete.");
-  return { startDate, endDate: end, fetched, added, isFirstSync };
+  return {
+    startDate,
+    endDate: end,
+    fetched,
+    added,
+    removed,
+    refused,
+    pruned,
+    isFirstSync,
+    ...options.prune === undefined ? {} : { pruneScope: options.prune }
+  };
 }
 
 // src/db/queries.ts
@@ -2788,10 +2960,30 @@ function resolveWindow(opts, today) {
   }
   return { from, to };
 }
-async function runSync(ctx, window = {}) {
+var PRUNE_ALL = "all";
+function resolvePruneScope(value) {
+  if (value === undefined || value === false)
+    return;
+  const raw = value === true ? "" : String(value);
+  const wanted = raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
+  if (wanted.length === 0 || wanted.some((n) => n.startsWith("-"))) {
+    throw new CliError("BAD_ARGS", "--prune needs a value naming what to prune.", `Use --prune=<collection> (for example --prune=hr), a comma-separated list, or --prune=${PRUNE_ALL} for every collection.`);
+  }
+  if (wanted.includes(PRUNE_ALL)) {
+    if (wanted.length === 1)
+      return PRUNE_ALL;
+    throw new CliError("BAD_ARGS", `--prune=${PRUNE_ALL} cannot be combined with collection names.`, `Use --prune=${PRUNE_ALL} on its own, or list the collections you mean.`);
+  }
+  const unknown = wanted.filter((n) => byName(n) === undefined);
+  if (unknown.length > 0) {
+    throw new CliError("BAD_ARGS", `--prune: unknown collection${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}.`, `Known collections: ${names().join(", ")}.`);
+  }
+  return [...new Set(wanted)];
+}
+async function runSync(ctx, window = {}, options = {}) {
   const lines = [];
   const log = ctx.format === "table" ? (m) => lines.push(m) : undefined;
-  const importResult = await importDaily(ctx.db, ctx.client, { today: ctx.today, tz: ctx.tz }, log, window);
+  const importResult = await importDaily(ctx.db, ctx.client, { today: ctx.today, tz: ctx.tz }, log, window, options);
   const today = getDaySummary(ctx.db, ctx.today);
   return {
     json: { import: importResult, today },
@@ -2799,15 +2991,18 @@ async function runSync(ctx, window = {}) {
 `)
   };
 }
-var syncCommand = dataCommand({
+var syncArgs = {
+  from: { type: "string", description: "Re-fetch every collection from this day (YYYY-MM-DD) instead of from its last stored day" },
+  to: { type: "string", description: "End of the explicit window (YYYY-MM-DD, default: today); requires --from" },
+  prune: { type: "string", description: "Apply removals sync kept back: --prune=hr, a list, or --prune=all" }
+};
+var syncDef = {
   meta: { name: "sync", description: "Import latest data from Oura API and return today's summary" },
-  args: {
-    from: { type: "string", description: "Re-fetch every collection from this day (YYYY-MM-DD) instead of from its last stored day" },
-    to: { type: "string", description: "End of the explicit window (YYYY-MM-DD, default: today); requires --from" }
-  },
+  args: syncArgs,
   needs: { db: true, client: true },
-  run: (ctx, args) => runSync(ctx, resolveWindow({ from: args.from, to: args.to }, ctx.today))
-});
+  run: (ctx, args) => runSync(ctx, resolveWindow({ from: args.from, to: args.to }, ctx.today), { prune: resolvePruneScope(args.prune) })
+};
+var syncCommand = dataCommand(syncDef);
 
 // src/commands/db.ts
 var SYNC_HINT = "Run `oura-cli sync` to download your data. Oura publishes a day's summary after that night's sleep syncs from the ring.";
@@ -3132,7 +3327,7 @@ var reportCommand = dataCommand({
 // src/commands/healthcheck.ts
 function healthcheckCommand(version) {
   return defineCommand({
-    meta: { name: "healthcheck", description: "Quick local DB health probe (JSON: {ok, version, latencyMs}, plus error when ok is false)." },
+    meta: { name: "healthcheck", description: "Fast liveness probe: opens the local database and runs one query (JSON: {ok, version, latencyMs}, plus error when ok is false). It proves the file opens, not that its contents are intact \u2014 `doctor` checks that." },
     args: { ...commonArgs },
     run({ args }) {
       assertKnownArgs(commonArgs, args);
@@ -3213,8 +3408,18 @@ async function runChecks(deps) {
     checks.push({ id: "database", status: "fail", detail: msg });
   }
   if (db) {
-    const last = latestDataDay(db);
-    if (!last) {
+    const damage = quickCheck(db);
+    checks.push(damage === null ? { id: "integrity", status: "ok", detail: "Database passes SQLite quick_check." } : { id: "integrity", status: "fail", detail: `Database is damaged: ${damage}`, fix: "Delete the cache file (--db / OURA_DB_PATH) and run `oura-cli sync` to rebuild it." });
+    let last = null;
+    let readFailed;
+    try {
+      last = latestDataDay(db);
+    } catch (err) {
+      readFailed = err instanceof Error ? err.message : String(err);
+    }
+    if (readFailed !== undefined) {
+      checks.push({ id: "data", status: "fail", detail: `Cannot read the cache: ${readFailed}`, fix: "Delete the cache file (--db / OURA_DB_PATH) and run `oura-cli sync` to rebuild it." });
+    } else if (!last) {
       checks.push({ id: "data", status: "warn", detail: "No data in the local cache yet.", fix: "oura-cli sync" });
     } else {
       const ageDays = Math.round((new Date(`${deps.today}T00:00:00Z`).getTime() - new Date(`${last}T00:00:00Z`).getTime()) / 86400000);
@@ -3225,6 +3430,7 @@ async function runChecks(deps) {
       }
     }
   } else {
+    checks.push({ id: "integrity", status: "fail", detail: "Cannot check integrity \u2014 database unavailable." });
     checks.push({ id: "data", status: "fail", detail: "Cannot check data \u2014 database unavailable." });
   }
   db?.close();
@@ -3233,6 +3439,15 @@ async function runChecks(deps) {
   const nextStep = checks.find((c) => !settled(c.status))?.fix ?? null;
   return { ok, checks, nextStep };
 }
+function quickCheck(db) {
+  try {
+    const rows = db.query("PRAGMA quick_check(1)").all();
+    const first = rows[0] === undefined ? "ok" : Object.values(rows[0])[0] ?? "ok";
+    return first === "ok" ? null : first;
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
 var DATA_TABLES = ["daily_sleep", "daily_readiness", "daily_activity"];
 function latestDataDay(db) {
   let latest = null;
@@ -3375,7 +3590,36 @@ var fetchCommand = dataCommand({
 
 // src/lib/citty-error.ts
 var ANSI2 = /\u001b\[[0-9;]*m/g;
-function fromCittyError(err, removedCommandHints = {}) {
+var COMMAND_NAME = /^[a-z][a-z0-9-]{0,19}$/;
+function editDistanceAtMostOne(a, b) {
+  if (Math.abs(a.length - b.length) > 1)
+    return false;
+  let i = 0, j = 0, edits = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      i++;
+      j++;
+      continue;
+    }
+    if (++edits > 1)
+      return false;
+    if (a.length > b.length)
+      i++;
+    else if (a.length < b.length)
+      j++;
+    else {
+      i++;
+      j++;
+    }
+  }
+  return edits + (a.length - i) + (b.length - j) <= 1;
+}
+function nearestGlobalFlag(token) {
+  if (!token.startsWith("--") || token.length < 4)
+    return;
+  return [...GLOBAL_FLAGS_WITH_VALUE].find((flag) => flag !== token && (editDistanceAtMostOne(flag, token) || flag.startsWith(token)));
+}
+function fromCittyError(err, removedCommandHints = {}, rawArgs = []) {
   const code = err?.code;
   if (typeof code !== "string")
     return err;
@@ -3383,6 +3627,14 @@ function fromCittyError(err, removedCommandHints = {}) {
   switch (code) {
     case "E_UNKNOWN_COMMAND": {
       const name = message.replace(/^Unknown command\s*/, "").trim();
+      const before = rawArgs[rawArgs.lastIndexOf(name) - 1];
+      const meant = before === undefined ? undefined : nearestGlobalFlag(before);
+      if (meant) {
+        return new CliError("BAD_ARGS", `Unknown flag "${before}".`, `Did you mean ${meant}? Its value was read as a command name.`);
+      }
+      if (!COMMAND_NAME.test(name)) {
+        return new CliError("BAD_ARGS", "Unknown command.", "A value was read as a command name. Check the flags before it, and run `oura-cli --help` for the list of commands.");
+      }
       const hint = Object.hasOwn(removedCommandHints, name) ? removedCommandHints[name] : "Run `oura-cli --help` for the list of commands.";
       return new CliError("BAD_ARGS", `Unknown command "${name}".`, hint);
     }
@@ -3437,7 +3689,7 @@ if (isVersionRequest(rawArgs)) {
   runMain(main, { rawArgs });
 } else {
   runCommand(main, { rawArgs }).catch((raw) => {
-    const err = fromCittyError(raw, REMOVED_COMMANDS);
+    const err = fromCittyError(raw, REMOVED_COMMANDS, rawArgs);
     emitError(err, formatFromArgv(rawArgs, process.stdout.isTTY === true));
     process.exit(exitCodeFor(err));
   });

package/docs/schemas/doctor.json

@@ -13,7 +13,7 @@
         "required": ["id", "status", "detail"],
         "additionalProperties": false,
         "properties": {
-          "id":     { "type": "string", "enum": ["token", "token-valid", "database", "data"] },
+          "id":     { "type": "string", "enum": ["token", "token-valid", "database", "integrity", "data"] },
           "status": { "type": "string", "enum": ["ok", "warn", "fail", "skip"] },
           "detail": { "type": "string" },
           "fix":    { "type": "string" }

package/package.json

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