@drakulavich/oura-cli 0.5.2 → 0.7.0

package/dist/index.js

@@ -557,8 +557,26 @@ var init_source = __esm(() => {
   source_default = chalk;
 });
 
-// src/index.ts
+// src/lib/apply-color-mode.ts
 init_source();
+
+// src/lib/color-mode.ts
+function forcesColor(value) {
+  return value !== undefined && value !== "" && value !== "0" && value !== "false";
+}
+function shouldDisableColor(argv, env, isTty) {
+  if (argv.includes("--no-color") || env.NO_COLOR)
+    return true;
+  return !isTty && !forcesColor(env.FORCE_COLOR);
+}
+
+// src/lib/apply-color-mode.ts
+if (shouldDisableColor(process.argv, process.env, process.stdout.isTTY === true)) {
+  process.env.NO_COLOR = "1";
+  source_default.level = 0;
+}
+
+// src/index.ts
 import { readFileSync as readFileSync2 } from "fs";
 
 // node_modules/citty/dist/_chunks/libs/scule.mjs
@@ -1180,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 = [
   {
@@ -1309,26 +1335,108 @@ CREATE VIEW IF NOT EXISTS v_sleep_detail AS
         average_hrv, average_heart_rate as avg_hr, lowest_heart_rate as lowest_hr, efficiency
     FROM sleep_model ORDER BY day DESC;
     `
+  },
+  {
+    version: 3,
+    sql: `
+CREATE TABLE IF NOT EXISTS daily_resilience (
+    id TEXT PRIMARY KEY,
+    day TEXT UNIQUE,
+    level TEXT,
+    sleep_recovery REAL,
+    daytime_recovery REAL,
+    stress REAL
+);
+CREATE TABLE IF NOT EXISTS sleep_time (
+    id TEXT PRIMARY KEY,
+    day TEXT UNIQUE,
+    status TEXT,
+    recommendation TEXT,
+    bedtime_start_offset INTEGER,
+    bedtime_end_offset INTEGER,
+    day_tz INTEGER
+);
+CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY,
+    day TEXT,
+    type TEXT,
+    mood TEXT,
+    start_datetime TEXT,
+    end_datetime TEXT,
+    heart_rate TEXT,
+    heart_rate_variability TEXT,
+    motion_count TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_sessions_day ON sessions(day);
+CREATE TABLE IF NOT EXISTS rest_mode_periods (
+    id TEXT PRIMARY KEY,
+    day TEXT,
+    end_day TEXT,
+    start_time TEXT,
+    end_time TEXT,
+    episodes TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_rest_mode_periods_day ON rest_mode_periods(day);
+CREATE TABLE IF NOT EXISTS enhanced_tags (
+    id TEXT PRIMARY KEY,
+    day TEXT,
+    end_day TEXT,
+    start_time TEXT,
+    end_time TEXT,
+    tag_type_code TEXT,
+    comment TEXT,
+    custom_name TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_enhanced_tags_day ON enhanced_tags(day);
+CREATE TABLE IF NOT EXISTS ring_configuration (
+    id TEXT PRIMARY KEY,
+    color TEXT,
+    design TEXT,
+    firmware_version TEXT,
+    hardware_type TEXT,
+    set_up_at TEXT,
+    size INTEGER
+);
+CREATE TABLE IF NOT EXISTS ring_battery_level (
+    timestamp TEXT,
+    level INTEGER,
+    charging INTEGER,
+    in_charger INTEGER,
+    day TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_ring_battery_level_unique ON ring_battery_level(timestamp);
+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 getDbPath(explicit) {
-  if (explicit)
-    return explicit;
-  if (process.env.OURA_DB_PATH)
-    return process.env.OURA_DB_PATH;
+  if (explicit !== undefined)
+    return requireValue(explicit, "--db", "the default database");
+  const fromEnv = process.env.OURA_DB_PATH;
+  if (fromEnv !== undefined)
+    return requireValue(fromEnv, "OURA_DB_PATH", "the default database");
   return resolve(homedir(), ".oura-cli", "oura.db");
 }
 function openDatabase(explicit) {
@@ -1342,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();
@@ -1358,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);
@@ -1378,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 };
@@ -1469,15 +1605,13 @@ var SUBCOMMANDS = new Set([
 ]);
 function normalizeArgv(argv) {
   const [bun, script, ...rest] = argv;
-  const subIdx = rest.findIndex((a) => SUBCOMMANDS.has(a));
-  if (subIdx < 0)
-    return argv;
-  const before = rest.slice(0, subIdx);
-  const subcommandOnwards = rest.slice(subIdx);
+  const dd = rest.indexOf("--");
+  const scanned = dd >= 0 ? rest.slice(0, dd) : rest;
+  const passthrough = dd >= 0 ? rest.slice(dd) : [];
+  const kept = [];
   const hoisted = [];
-  const leftover = [];
-  for (let i = 0;i < before.length; i++) {
-    const tok = before[i];
+  for (let i = 0;i < scanned.length; i++) {
+    const tok = scanned[i];
     if (tok.includes("=")) {
       const name = tok.slice(0, tok.indexOf("="));
       if (GLOBAL_FLAGS_WITH_VALUE.has(name) || GLOBAL_FLAGS_BOOLEAN.has(name)) {
@@ -1487,8 +1621,8 @@ function normalizeArgv(argv) {
     }
     if (GLOBAL_FLAGS_WITH_VALUE.has(tok)) {
       hoisted.push(tok);
-      if (i + 1 < before.length) {
-        hoisted.push(before[i + 1]);
+      if (i + 1 < scanned.length) {
+        hoisted.push(scanned[i + 1]);
         i++;
       }
       continue;
@@ -1497,13 +1631,9 @@ function normalizeArgv(argv) {
       hoisted.push(tok);
       continue;
     }
-    leftover.push(tok);
+    kept.push(tok);
   }
-  const dd = subcommandOnwards.indexOf("--");
-  if (dd >= 0) {
-    return [bun, script, ...leftover, ...subcommandOnwards.slice(0, dd), ...hoisted, ...subcommandOnwards.slice(dd)];
-  }
-  return [bun, script, ...leftover, ...subcommandOnwards, ...hoisted];
+  return [bun, script, ...kept, ...hoisted, ...passthrough];
 }
 function isVersionRequest(rawArgs) {
   for (let i = 0;i < rawArgs.length; i++) {
@@ -1521,13 +1651,15 @@ function isVersionRequest(rawArgs) {
 }
 
 // src/lib/format-resolve.ts
-function resolveFormat({ explicit, isTty }) {
-  if (explicit === undefined)
-    return isTty ? "table" : "json";
-  if (explicit === "table" || explicit === "json")
-    return explicit;
+function assertValidFormat(explicit) {
+  if (explicit === undefined || explicit === "table" || explicit === "json")
+    return;
   throw new CliError("BAD_ARGS", `Unknown --format value: "${explicit}". Use "table" or "json".`);
 }
+function resolveFormat({ explicit, isTty }) {
+  assertValidFormat(explicit);
+  return explicit ?? (isTty ? "table" : "json");
+}
 function formatFromArgv(argv, isTty) {
   let explicit;
   for (let i = 0;i < argv.length; i++) {
@@ -1592,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 {
@@ -1659,6 +1792,8 @@ var processIo = {
 };
 var camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 function assertKnownArgs(declared, args) {
+  if ("format" in declared)
+    assertValidFormat(args.format);
   const known = new Set(["_"]);
   let positionals = 0;
   for (const [name, def] of Object.entries(declared)) {
@@ -1891,6 +2026,7 @@ var hr = defineCollection({
   conflict: "ignore",
   rangeParams: "datetime",
   maxRangeDays: 30,
+  syncLookbackDays: 14,
   identity: [{ field: "timestamp", format: "date-time", description: "ISO 8601 timestamp of the sample" }],
   columns: [
     { name: "timestamp", type: "TEXT", pick: (r) => r.timestamp },
@@ -2028,6 +2164,192 @@ var cvAge = defineCollection({
   ]
 });
 
+// src/collections/resilience.ts
+var resilience = defineCollection({
+  name: "resilience",
+  endpoint: "daily_resilience",
+  table: "daily_resilience",
+  description: "Daily resilience level with its sleep-recovery, daytime-recovery and stress contributors",
+  conflict: "replace",
+  rangeParams: "date",
+  identity: [
+    { field: "id", description: "Oura record id" },
+    { field: "day", format: "date", description: "Date the record applies to (YYYY-MM-DD)" }
+  ],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "day", type: "TEXT", unique: true, pick: (r) => r.day },
+    { name: "level", type: "TEXT", pick: (r) => r.level ?? null },
+    { name: "sleep_recovery", type: "REAL", pick: (r) => r.contributors?.sleep_recovery ?? null },
+    { name: "daytime_recovery", type: "REAL", pick: (r) => r.contributors?.daytime_recovery ?? null },
+    { name: "stress", type: "REAL", pick: (r) => r.contributors?.stress ?? null }
+  ]
+});
+
+// src/collections/vo2max.ts
+var vo2max = defineCollection({
+  name: "vo2max",
+  endpoint: "vO2_max",
+  table: "vo2max",
+  description: "Daily VO2 max estimate",
+  conflict: "replace",
+  rangeParams: "date",
+  dayRangeOffset: [0, 1],
+  identity: [
+    { field: "id", description: "Oura record id" },
+    { field: "day", format: "date", description: "Date the record applies to (YYYY-MM-DD)" }
+  ],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "day", type: "TEXT", unique: true, pick: (r) => r.day },
+    { name: "vo2_max", type: "REAL", pick: (r) => r.vo2_max ?? null },
+    { name: "timestamp", type: "TEXT", pick: (r) => r.timestamp }
+  ]
+});
+
+// src/collections/sleep-time.ts
+var sleepTime = defineCollection({
+  name: "sleep-time",
+  endpoint: "sleep_time",
+  table: "sleep_time",
+  description: "Suggested bedtime window (offsets in seconds from midnight) with status and recommendation",
+  conflict: "replace",
+  rangeParams: "date",
+  identity: [
+    { field: "id", description: "Oura record id" },
+    { field: "day", format: "date", description: "Date the record applies to (YYYY-MM-DD)" }
+  ],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "day", type: "TEXT", unique: true, pick: (r) => r.day },
+    { name: "status", type: "TEXT", pick: (r) => r.status ?? null },
+    { name: "recommendation", type: "TEXT", pick: (r) => r.recommendation ?? null },
+    { name: "bedtime_start_offset", type: "INTEGER", pick: (r) => r.optimal_bedtime?.start_offset ?? null },
+    { name: "bedtime_end_offset", type: "INTEGER", pick: (r) => r.optimal_bedtime?.end_offset ?? null },
+    { name: "day_tz", type: "INTEGER", pick: (r) => r.optimal_bedtime?.day_tz ?? null }
+  ]
+});
+
+// src/collections/session.ts
+var session = defineCollection({
+  name: "session",
+  endpoint: "session",
+  table: "sessions",
+  description: "Guided sessions (meditation, breathing, naps, rest) with their sample series as JSON",
+  conflict: "replace",
+  rangeParams: "date",
+  dayRangeOffset: [0, 1],
+  identity: [
+    { field: "id", description: "Oura record id" },
+    { field: "day", format: "date", description: "Date the session belongs to (YYYY-MM-DD)" }
+  ],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "day", type: "TEXT", pick: (r) => r.day },
+    { name: "type", type: "TEXT", pick: (r) => r.type ?? null },
+    { name: "mood", type: "TEXT", pick: (r) => r.mood ?? null },
+    { name: "start_datetime", type: "TEXT", pick: (r) => r.start_datetime },
+    { name: "end_datetime", type: "TEXT", pick: (r) => r.end_datetime },
+    { name: "heart_rate", type: "TEXT", pick: (r) => r.heart_rate == null ? null : JSON.stringify(r.heart_rate) },
+    { name: "heart_rate_variability", type: "TEXT", pick: (r) => r.heart_rate_variability == null ? null : JSON.stringify(r.heart_rate_variability) },
+    { name: "motion_count", type: "TEXT", pick: (r) => r.motion_count == null ? null : JSON.stringify(r.motion_count) }
+  ],
+  indexes: [{ name: "idx_sessions_day", columns: ["day"] }]
+});
+
+// src/collections/rest-mode.ts
+var restMode = defineCollection({
+  name: "rest-mode",
+  endpoint: "rest_mode_period",
+  table: "rest_mode_periods",
+  description: "Rest mode periods; `day` is the period start day, episodes are kept as JSON",
+  conflict: "replace",
+  rangeParams: "date",
+  dayRangeOffset: [0, 1],
+  identity: [
+    { field: "id", description: "Oura record id" },
+    { field: "start_day", format: "date", description: "First day of the period (YYYY-MM-DD)" }
+  ],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "day", type: "TEXT", pick: (r) => r.start_day },
+    { name: "end_day", type: "TEXT", pick: (r) => r.end_day ?? null },
+    { name: "start_time", type: "TEXT", pick: (r) => r.start_time ?? null },
+    { name: "end_time", type: "TEXT", pick: (r) => r.end_time ?? null },
+    { name: "episodes", type: "TEXT", pick: (r) => r.episodes == null ? null : JSON.stringify(r.episodes) }
+  ],
+  indexes: [{ name: "idx_rest_mode_periods_day", columns: ["day"] }]
+});
+
+// src/collections/tags.ts
+var tags = defineCollection({
+  name: "tags",
+  endpoint: "enhanced_tag",
+  table: "enhanced_tags",
+  description: "Tags the user added in the app; `day` is the tag start day",
+  conflict: "replace",
+  rangeParams: "date",
+  dayRangeOffset: [0, 1],
+  identity: [
+    { field: "id", description: "Oura record id" },
+    { field: "start_day", format: "date", description: "Day the tag starts on (YYYY-MM-DD)" }
+  ],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "day", type: "TEXT", pick: (r) => r.start_day },
+    { name: "end_day", type: "TEXT", pick: (r) => r.end_day ?? null },
+    { name: "start_time", type: "TEXT", pick: (r) => r.start_time ?? null },
+    { name: "end_time", type: "TEXT", pick: (r) => r.end_time ?? null },
+    { name: "tag_type_code", type: "TEXT", pick: (r) => r.tag_type_code ?? null },
+    { name: "comment", type: "TEXT", pick: (r) => r.comment ?? null },
+    { name: "custom_name", type: "TEXT", pick: (r) => r.custom_name ?? null }
+  ],
+  indexes: [{ name: "idx_enhanced_tags_day", columns: ["day"] }]
+});
+
+// src/collections/ring.ts
+var ring = defineCollection({
+  name: "ring",
+  endpoint: "ring_configuration",
+  table: "ring_configuration",
+  description: "Ring hardware, colour, size, firmware and set-up time; a snapshot list, not a day range",
+  conflict: "replace",
+  rangeParams: "none",
+  identity: [{ field: "id", description: "Oura ring id" }],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "color", type: "TEXT", pick: (r) => r.color ?? null },
+    { name: "design", type: "TEXT", pick: (r) => r.design ?? null },
+    { name: "firmware_version", type: "TEXT", pick: (r) => r.firmware_version ?? null },
+    { name: "hardware_type", type: "TEXT", pick: (r) => r.hardware_type ?? null },
+    { name: "set_up_at", type: "TEXT", pick: (r) => r.set_up_at ?? null },
+    { name: "size", type: "INTEGER", pick: (r) => r.size ?? null }
+  ]
+});
+
+// src/collections/battery.ts
+var battery = defineCollection({
+  name: "battery",
+  endpoint: "ring_battery_level",
+  table: "ring_battery_level",
+  description: "Ring battery level events (percent) with charging state",
+  conflict: "ignore",
+  rangeParams: "datetime",
+  maxRangeDays: 30,
+  identity: [{ field: "timestamp", format: "date-time", description: "ISO 8601 timestamp of the event" }],
+  columns: [
+    { name: "timestamp", type: "TEXT", pick: (r) => r.timestamp },
+    { name: "level", type: "INTEGER", pick: (r) => r.level ?? null },
+    { name: "charging", type: "INTEGER", pick: (r) => r.charging == null ? null : r.charging ? 1 : 0 },
+    { name: "in_charger", type: "INTEGER", pick: (r) => r.in_charger == null ? null : r.in_charger ? 1 : 0 },
+    { name: "day", type: "TEXT", pick: (r) => r.timestamp.slice(0, 10) }
+  ],
+  indexes: [
+    { name: "idx_ring_battery_level_unique", columns: ["timestamp"], unique: true },
+    { name: "idx_ring_battery_level_day", columns: ["day"] }
+  ]
+});
+
 // src/collections/index.ts
 var COLLECTIONS = [
   sleep,
@@ -2038,7 +2360,15 @@ var COLLECTIONS = [
   stress,
   workout,
   sleepPeriods,
-  cvAge
+  cvAge,
+  resilience,
+  vo2max,
+  sleepTime,
+  session,
+  restMode,
+  tags,
+  ring,
+  battery
 ];
 function names() {
   return COLLECTIONS.map((c) => c.name);
@@ -2078,17 +2408,21 @@ function datetimeQueries(start, end, tz, maxDays) {
   return out;
 }
 function rangeQueries(c, start, end, tz) {
+  if (c.rangeParams === "none")
+    return [{}];
   if (start > end)
     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
@@ -2190,43 +2524,191 @@ 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) {
-  return db.query(`SELECT MAX(day) AS d FROM ${table}`).get().d;
+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;
   const backfillStart = shiftDay(end, -(BACKFILL_DAYS - 1));
   const plan = COLLECTIONS.map((c) => {
-    const last = lastDay(db, c.table);
-    return { c, last, start: window.from ?? last ?? backfillStart };
+    const last = c.rangeParams === "none" ? null : lastDay(db, c.table, end);
+    const resume = window.from ?? last ?? backfillStart;
+    const start = window.from ?? shiftDay(resume, -(last === null ? 0 : c.syncLookbackDays ?? 0));
+    return { c, last, resume, start };
   });
-  const isFirstSync = plan.every((p) => p.last === null);
-  const startDate = plan.map((p) => p.start).sort()[0];
+  const ranged = plan.filter((p) => p.c.rangeParams !== "none");
+  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 before = rowCount(db, c.table);
+    const pieces = await fetchCollectionByPiece(client, c, start, end, tz);
+    const rows = pieces.flat();
     const stmt = db.query(insertSql(c));
-    db.transaction((rs) => {
-      for (const r of rs)
-        stmt.run(...rowValues(c, r));
-    })(rows);
+    if (c.rangeParams === "none") {
+      const pk = c.columns.find((col) => col.pk)?.name;
+      if (!pk)
+        throw new Error(`Snapshot collection ${c.name} must declare a primary-key column (enforced by the registry tests).`);
+      const ids = () => new Set(db.query(`SELECT ${pk} AS id FROM ${c.table}`).all().map((r) => r.id));
+      const known = ids();
+      db.transaction((rs) => {
+        db.exec(`DELETE FROM ${c.table}`);
+        for (const r of rs)
+          stmt.run(...rowValues(c, r));
+      })(rows);
+      fetched[c.table] = rows.length;
+      added[c.table] = [...ids()].filter((id) => !known.has(id)).length;
+      _log(`  + ${c.name} (${c.table}): ${rows.length} fetched, ${added[c.table]} new${rows.length === 0 ? ", table cleared" : ""}`);
+      continue;
+    }
+    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;
-    if (rows.length > 0)
-      _log(`  + ${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
@@ -2298,6 +2780,27 @@ function getStats(db, today) {
 
 // src/render/format.ts
 init_source();
+
+// src/lib/pad.ts
+var ANSI = /\u001B\[[0-9;]*m/g;
+function visibleWidth(text) {
+  return text.replace(ANSI, "").length;
+}
+function padLeft(text, width) {
+  const gap = width - visibleWidth(text);
+  return gap > 0 ? " ".repeat(gap) + text : text;
+}
+function padRight(text, width) {
+  const gap = width - visibleWidth(text);
+  return gap > 0 ? text + " ".repeat(gap) : text;
+}
+
+// src/lib/terminal.ts
+function terminalWidth() {
+  return process.stdout.isTTY && process.stdout.columns ? process.stdout.columns : 80;
+}
+
+// src/render/format.ts
 function scoreColor(score) {
   if (score === null)
     return source_default.gray("\u2014");
@@ -2351,13 +2854,35 @@ function formatDaySummary(summary, format, emptyHint) {
   return lines.join(`
 `);
 }
-function formatImportSummary(result) {
-  const n = (table) => `${result.fetched[table] ?? 0} (+${result.added[table] ?? 0})`;
-  return [
-    `  Fetched ${result.startDate} \u2192 ${result.endDate}, rows fetched (+new):`,
-    `    sleep ${n("daily_sleep")}   readiness ${n("daily_readiness")}   activity ${n("daily_activity")}   sleep periods ${n("sleep_model")}`,
-    `    spo2 ${n("daily_spo2")}   stress ${n("daily_stress")}   workouts ${n("workouts")}   heart rate ${n("heartrate")}   cardiovascular age ${n("cardiovascular_age")}`
-  ].join(`
+var SUMMARY_INDENT = 4;
+var SUMMARY_GAP = 2;
+var SUMMARY_MAX_COLUMNS = 4;
+function columnsThatFit(cellWidth, width) {
+  const fits = Math.floor((width - SUMMARY_INDENT + SUMMARY_GAP) / (cellWidth + SUMMARY_GAP));
+  return Math.max(1, Math.min(SUMMARY_MAX_COLUMNS, fits));
+}
+function rowsOf(cells, columns) {
+  const rows = [];
+  for (let i = 0;i < cells.length; i += columns) {
+    rows.push(" ".repeat(SUMMARY_INDENT) + cells.slice(i, i + columns).join(" ".repeat(SUMMARY_GAP)).trimEnd());
+  }
+  return rows;
+}
+function formatImportSummary(result, width = terminalWidth()) {
+  const counts = COLLECTIONS.map((c) => ({
+    name: c.name,
+    fetched: String(result.fetched[c.table] ?? 0),
+    added: String(result.added[c.table] ?? 0)
+  }));
+  const nameW = Math.max(...counts.map((c) => visibleWidth(c.name)));
+  const fetchedW = Math.max(...counts.map((c) => visibleWidth(c.fetched)));
+  const aligned = counts.map((c) => `${padRight(c.name, nameW)} ${padLeft(c.fetched, fetchedW)} (+${c.added})`);
+  const bare = counts.map((c) => `${c.name} ${c.fetched} (+${c.added})`);
+  const cellW = Math.max(...aligned.map(visibleWidth));
+  const columns = columnsThatFit(cellW, width);
+  const cells = columns === 1 ? bare : aligned.map((c) => padRight(c, cellW));
+  const head = `  Fetched ${result.startDate} \u2192 ${result.endDate}, rows fetched (+new):`;
+  return [head, ...rowsOf(cells, columns)].join(`
 `);
 }
 function formatWeekTable(days, format, emptyHint) {
@@ -2373,7 +2898,7 @@ function formatWeekTable(days, format, emptyHint) {
   }
   const header = `${"Day".padEnd(12)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Activity".padStart(9)} ${"Steps".padStart(7)} ${"Stress".padEnd(10)}`;
   const sep = source_default.gray("\u2500".repeat(56));
-  const rows = days.map((d) => `${d.day.padEnd(12)} ${scoreColor(d.sleep_score).padStart(6)} ${scoreColor(d.readiness_score).padStart(6)} ` + `${scoreColor(d.activity_score).padStart(9)} ${String(d.steps ?? "\u2014").padStart(7)} ${(d.stress ?? "\u2014").padEnd(10)}`);
+  const rows = days.map((d) => `${padRight(d.day, 12)} ${padLeft(scoreColor(d.sleep_score), 6)} ${padLeft(scoreColor(d.readiness_score), 6)} ` + `${padLeft(scoreColor(d.activity_score), 9)} ${padLeft(String(d.steps ?? "\u2014"), 7)} ${padRight(d.stress ?? "\u2014", 10)}`);
   return [`
   Last 7 Days`, sep, `  ${header}`, sep, ...rows.map((r) => `  ${r}`)].join(`
 `);
@@ -2422,19 +2947,43 @@ function formatStats(stats, format) {
 }
 
 // src/commands/sync.ts
-function resolveWindow(opts) {
+function resolveWindow(opts, today) {
   if (opts.to !== undefined && opts.from === undefined)
     throw new CliError("BAD_ARGS", "--to requires --from.");
   const from = opts.from === undefined ? undefined : assertCalendarDate(opts.from, "--from");
   const to = opts.to === undefined ? undefined : assertCalendarDate(opts.to, "--to");
   if (from !== undefined && to !== undefined && from > to)
     throw new CliError("BAD_ARGS", `--from (${from}) must not be after --to (${to}).`);
+  const end = to ?? today;
+  if (from !== undefined && from > end) {
+    throw new CliError("BAD_ARGS", `--from (${from}) is after the end of the window (${end}).`, "Pass --to as well to sync a window that ends in the future.");
+  }
   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 },
@@ -2442,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 }))
-});
+  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.";
@@ -2513,7 +3065,7 @@ function dayLabel(dateStr) {
   const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
   return `${day} ${dd}/${mm}`;
 }
-function getReport(db, days, today, tz = "UTC") {
+function getReport(db, days, today) {
   const period = days <= 7 ? "week" : "month";
   const weekEnd = today;
   const weekStart = shiftDay(today, -(days - 1));
@@ -2521,7 +3073,8 @@ function getReport(db, days, today, tz = "UTC") {
   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 newestActivityDay = db.query("SELECT MAX(day) AS d FROM daily_activity").get().d;
+  const isComplete = (d) => d < today && newestActivityDay !== null && newestActivityDay > d;
   const completeThrough = [...windowDays].reverse().find(isComplete) ?? null;
   const activityEnd = completeThrough ?? shiftDay(weekStart, -1);
   const dailyRows = [];
@@ -2607,13 +3160,13 @@ function colorizeScore(n) {
 }
 function scoreCell(n, width) {
   if (n === null)
-    return source_default.gray("\u2014".padStart(width));
-  return colorizeScore(n)(String(n).padStart(width));
+    return padLeft(source_default.gray("\u2014"), width);
+  return padLeft(colorizeScore(n)(String(n)), width);
 }
 function stepsCell(n, width) {
   if (n === null)
-    return source_default.gray("\u2014".padStart(width));
-  return n.toLocaleString().padStart(width);
+    return padLeft(source_default.gray("\u2014"), width);
+  return padLeft(n.toLocaleString(), width);
 }
 function fmtSeconds(s) {
   if (s === null)
@@ -2655,18 +3208,15 @@ function bucketDaysIntoWeeks(days) {
   }
   return buckets;
 }
-function partialDayNote(data, tz) {
-  const partial = data.days.filter((d) => d.partial);
-  if (partial.length === 0)
+function partialDayNote(data) {
+  const partial = data.days.find((d) => d.partial);
+  if (!partial)
     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 which = partial.day === data.weekEnd ? "today" : partial.dayLabel;
   const covers = data.completeThrough ? `through ${data.completeThrough}` : "no complete day yet";
-  return `  * ${which} still accumulating (${synced}); activity averages cover ${covers}.`;
+  return `  * ${which} is still accumulating; activity averages cover ${covers}.`;
 }
-function formatReport(data, format, period, tz = "UTC") {
+function formatReport(data, format, period) {
   if (format === "json")
     return JSON.stringify(data, null, 2);
   const lines = [];
@@ -2677,7 +3227,7 @@ function formatReport(data, format, period, tz = "UTC") {
     lines.push(source_default.bold("  Oura Monthly Report"));
   }
   lines.push(source_default.gray(`  ${data.weekStart} \u2014 ${data.weekEnd}`));
-  const note = partialDayNote(data, tz);
+  const note = partialDayNote(data);
   if (note)
     lines.push(source_default.yellow(note));
   lines.push("");
@@ -2769,15 +3319,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, ctx.tz);
-    return { json: data, text: () => formatReport(data, "table", period, ctx.tz) };
+    const data = getReport(ctx.db, period === "week" ? 7 : 30, ctx.today);
+    return { json: data, text: () => formatReport(data, "table", period) };
   }
 });
 
 // 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);
@@ -2858,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);
@@ -2870,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();
@@ -2878,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;
@@ -2896,28 +3466,34 @@ function exitCodeForChecks(checks) {
     return exitCodeFor(new CliError("TOKEN_MISSING", fail.detail));
   return exitCodeFor(new CliError("DB_ERROR", fail.detail));
 }
+async function runDoctor(ctx, args) {
+  const dbPath = getDbPath(args.db);
+  const deps = {
+    resolveToken: () => resolveToken(args.token),
+    openDb: () => {
+      const db = openDatabase(args.db);
+      ensureSchema(db);
+      return { db, path: dbPath };
+    },
+    createClient: (token) => new OuraClient({ token }),
+    offline: args.offline === true,
+    today: ctx.today
+  };
+  const result = await runChecks(deps);
+  return {
+    json: result,
+    text: () => formatDoctorTable(result),
+    exitCode: exitCodeForChecks(result.checks)
+  };
+}
 var doctorCommand = dataCommand({
   meta: { name: "doctor", description: "Diagnose token, database, and sync health, and suggest the next step." },
   args: { offline: { type: "boolean", default: false, description: "Skip the live Oura API token-validation call" } },
-  async run(ctx, args) {
-    const deps = {
-      resolveToken: () => resolveToken(args.token),
-      openDb: () => {
-        const db = openDatabase(args.db);
-        ensureSchema(db);
-        return { db, path: getDbPath(args.db) };
-      },
-      createClient: (token) => new OuraClient({ token }),
-      offline: args.offline === true,
-      today: ctx.today
-    };
-    const result = await runChecks(deps);
-    return {
-      json: result,
-      text: () => formatDoctorTable(result),
-      exitCode: exitCodeForChecks(result.checks)
-    };
-  }
+  run: (ctx, args) => runDoctor(ctx, {
+    db: args.db,
+    token: args.token,
+    offline: args.offline === true
+  })
 });
 
 // src/commands/manifest.ts
@@ -2979,10 +3555,15 @@ function resolveRange(opts) {
   }
   return { start: opts.today, end: opts.today };
 }
+function assertRangeAllowed(c, opts) {
+  if (c.rangeParams === "none" && [opts.day, opts.from, opts.to, opts.days].some((v) => v !== undefined)) {
+    throw new CliError("BAD_ARGS", `"${c.name}" is a snapshot, not a day range; it takes no --day, --from/--to or --days.`);
+  }
+}
 var fetchCommand = dataCommand({
   meta: { name: "fetch", description: "Fetch raw records for one Oura collection straight from the API (JSON)." },
   args: {
-    collection: { type: "positional", required: true, description: `Collection: ${names().join(" | ")}` },
+    collection: { type: "positional", required: true, description: `Collection: ${names().join(" | ")} (ring is a snapshot and takes no range flags)` },
     day: { type: "string", description: "Single day (YYYY-MM-DD). Default: today." },
     from: { type: "string", description: "Range start (YYYY-MM-DD); requires --to" },
     to: { type: "string", description: "Range end (YYYY-MM-DD); requires --from" },
@@ -2993,13 +3574,14 @@ var fetchCommand = dataCommand({
     const c = byName(args.collection);
     if (!c)
       throw new CliError("BAD_ARGS", `Unknown collection "${args.collection}".`, `Valid collections: ${names().join(", ")}`);
-    const { start, end } = resolveRange({
+    const opts = {
       day: args.day,
       from: args.from,
       to: args.to,
-      days: args.days,
-      today: ctx.today
-    });
+      days: args.days
+    };
+    assertRangeAllowed(c, opts);
+    const { start, end } = resolveRange({ ...opts, today: ctx.today });
     const client = new OuraClient(args.token ? { token: args.token } : {});
     const data = await fetchCollection(client, c, start, end, ctx.tz);
     return { json: data, text: () => JSON.stringify(data, null, 2) };
@@ -3007,15 +3589,52 @@ var fetchCommand = dataCommand({
 });
 
 // src/lib/citty-error.ts
-var ANSI = /\u001b\[[0-9;]*m/g;
-function fromCittyError(err, removedCommandHints = {}) {
+var ANSI2 = /\u001b\[[0-9;]*m/g;
+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;
-  const message = (err instanceof Error ? err.message : String(err)).replace(ANSI, "");
+  const message = (err instanceof Error ? err.message : String(err)).replace(ANSI2, "");
   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);
     }
@@ -3030,9 +3649,6 @@ function fromCittyError(err, removedCommandHints = {}) {
 
 // src/index.ts
 var VERSION = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf-8")).version;
-if (process.argv.includes("--no-color") || process.env.NO_COLOR) {
-  source_default.level = 0;
-}
 var subCommands = Object.assign(Object.create(null), {
   login: loginCommand,
   describe: describeCommand(VERSION, () => subCommands),
@@ -3073,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));
   });