@robinthues/rt-claude-coach 0.1.2 → 0.3.0

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { configExists, loadConfig, promptForConfig, saveConfig, saveTokens, getDbPath, createConfig, } from "./lib/config.js";
+import { configExists, loadConfig, promptForConfig, saveConfig, saveTokens, getDbPath, getDataDir, createConfig, } from "./lib/config.js";
 import { log } from "./lib/logging.js";
 import { migrate } from "./db/migrate.js";
 import { execute, initDatabase, query, queryJson } from "./db/client.js";
@@ -7,6 +7,10 @@ import { getAllActivities, getAthlete } from "./strava/api.js";
 import { insertAthlete, upsertSummaryActivity } from "./strava/store.js";
 import { syncActivityDetails } from "./strava/details.js";
 import { convertPlan } from "./garmin/index.js";
+import { buildFetchList, getDateStatuses, lastNDates, parseRecoveryDay, upsertRecoveryDay, } from "./recovery/index.js";
+import { buildAvailability, isIsoDate } from "./calendar/index.js";
+import { runBackup, runInit } from "./backup/index.js";
+import { runRestore } from "./backup/restore.js";
 import { readFileSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -23,6 +27,27 @@ const proxyUrl = process.env.HTTPS_PROXY ||
 if (proxyUrl) {
     setGlobalDispatcher(new ProxyAgent(proxyUrl));
 }
+export const DEFAULT_BACKUP_REPO = "RobinThues/claude-coach-data";
+export function parseBackupArgs(args) {
+    const parsed = {
+        command: "backup",
+        init: false,
+        push: true,
+        quiet: false,
+        repo: DEFAULT_BACKUP_REPO,
+    };
+    for (const arg of args.slice(1)) {
+        if (arg === "--init")
+            parsed.init = true;
+        else if (arg === "--no-push")
+            parsed.push = false;
+        else if (arg === "--quiet")
+            parsed.quiet = true;
+        else if (arg.startsWith("--repo="))
+            parsed.repo = arg.slice("--repo=".length);
+    }
+    return parsed;
+}
 function parseArgs() {
     const args = process.argv.slice(2);
     if (args.length === 0 || args[0] === "sync") {
@@ -96,6 +121,42 @@ function parseArgs() {
         }
         return exportArgs;
     }
+    if (args[0] === "garmin-status") {
+        const statusArgs = {
+            command: "garmin-status",
+            days: 14,
+            json: args.includes("--json"),
+        };
+        for (const arg of args) {
+            if (arg.startsWith("--days=")) {
+                const parsed = parseInt(arg.slice("--days=".length), 10);
+                if (Number.isNaN(parsed) || parsed < 1) {
+                    log.error("--days must be a positive integer");
+                    process.exit(1);
+                }
+                statusArgs.days = parsed;
+            }
+        }
+        return statusArgs;
+    }
+    if (args[0] === "import-garmin") {
+        if (!args[1]) {
+            log.error("import-garmin command requires an input JSON file");
+            process.exit(1);
+        }
+        return { command: "import-garmin", inputFile: args[1] };
+    }
+    if (args[0] === "calendar-availability") {
+        if (!args[1]) {
+            log.error("calendar-availability command requires an input JSON file");
+            process.exit(1);
+        }
+        return {
+            command: "calendar-availability",
+            inputFile: args[1],
+            json: args.includes("--json"),
+        };
+    }
     if (args[0] === "query") {
         if (!args[1]) {
             log.error("query command requires a SQL statement");
@@ -123,6 +184,19 @@ function parseArgs() {
         }
         return authArgs;
     }
+    if (args[0] === "backup") {
+        return parseBackupArgs(args);
+    }
+    if (args[0] === "restore-db") {
+        const parsed = { command: "restore-db", force: false };
+        for (const arg of args.slice(1)) {
+            if (arg === "--force")
+                parsed.force = true;
+            else if (arg.startsWith("--dump="))
+                parsed.dumpFile = arg.slice("--dump=".length);
+        }
+        return parsed;
+    }
     if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
         return { command: "help" };
     }
@@ -140,7 +214,12 @@ Commands:
   auth              Get Strava authorization URL or exchange code for tokens
   render <file>     Render a training plan JSON to HTML
   export-garmin <file>  Convert a plan JSON to Garmin sync workouts
+  garmin-status     Show which dates have Garmin recovery data, and what to fetch
+  import-garmin <file>  Import Garmin recovery MCP responses into the database
+  calendar-availability <file>  Normalize calendar MCP events into per-day busy blocks
   query <sql>       Run a SQL query against the database
+  backup            Commit the coach data directory and push it to the backup repo
+  restore-db        Rebuild coach.db from backup/coach-db.sql
   help              Show this help message
 
 Auth Options (for headless/Claude environments):
@@ -167,9 +246,26 @@ Export Garmin Options:
   --workout=ID          Export only the workout with this id
   --date=YYYY-MM-DD     Export only workouts on this date
 
+Garmin Status Options:
+  --days=N              Days of history to check (default: 14)
+  --json                Output as JSON, including the computed fetch list
+
+Calendar Availability Options:
+  --json                Output as JSON (default: plain per-day text)
+
 Query Options:
   --json                Output as JSON (default: plain text)
 
+Backup Options:
+  --init                One-time setup: git init, .gitignore, RESTORE.md, remote
+  --no-push             Commit locally without pushing
+  --quiet               Suppress non-error output (used by the Claude Code hook)
+  --repo=OWNER/NAME     Override the backup repo (default: RobinThues/claude-coach-data)
+
+Restore Options:
+  --dump=PATH           Read the dump from PATH instead of backup/coach-db.sql
+  --force               Move an existing coach.db to coach.db.bak, then restore
+
 Examples:
   # Headless auth flow (for Claude/automated environments)
   npx @robinthues/rt-claude-coach auth --client-id=12345 --client-secret=abc123
@@ -192,6 +288,18 @@ Examples:
 
   # Query the database
   npx @robinthues/rt-claude-coach query "SELECT * FROM weekly_volume LIMIT 5"
+
+  # Which recovery dates are missing, and what should be fetched?
+  npx @robinthues/rt-claude-coach garmin-status --days=14 --json
+
+  # Import verbatim Garmin MCP responses
+  npx @robinthues/rt-claude-coach import-garmin garmin-recovery.json
+
+  # Normalize verbatim calendar MCP events into per-day availability
+  npx @robinthues/rt-claude-coach calendar-availability calendar-events.json --json
+
+  # Read recovery data back
+  npx @robinthues/rt-claude-coach query "SELECT * FROM recovery_recent LIMIT 14"
 `);
 }
 // ============================================================================
@@ -485,6 +593,125 @@ function runExportGarmin(args) {
     log.success(`Wrote ${entries.length} Garmin workout entries to: ${outputFile}`);
 }
 // ============================================================================
+// Garmin Recovery Commands
+// ============================================================================
+async function runGarminStatus(args) {
+    await initDatabase();
+    migrate();
+    const dates = lastNDates(args.days);
+    const statuses = getDateStatuses(dates);
+    const today = dates[dates.length - 1];
+    const yesterday = lastNDates(2)[0];
+    const fetch = buildFetchList(statuses, today, yesterday);
+    if (args.json) {
+        console.log(JSON.stringify({ dates: statuses, fetch }, null, 2));
+        return;
+    }
+    for (const { date, status } of statuses) {
+        console.log(`${date}  ${status}`);
+    }
+    console.log(`\nFetch these ${fetch.length} date(s): ${fetch.join(", ")}`);
+}
+async function runImportGarmin(args) {
+    let fileContents;
+    try {
+        fileContents = readFileSync(args.inputFile, "utf-8");
+    }
+    catch {
+        log.error(`Could not read input file: ${args.inputFile}`);
+        process.exit(1);
+    }
+    let file;
+    try {
+        file = JSON.parse(fileContents);
+    }
+    catch {
+        log.error("Input file is not valid JSON");
+        process.exit(1);
+    }
+    if (typeof file !== "object" || file === null || !Array.isArray(file.days)) {
+        log.error('Input file must be an object with a "days" array');
+        process.exit(1);
+    }
+    await initDatabase();
+    migrate();
+    const failures = [];
+    let imported = 0;
+    for (const day of file.days) {
+        try {
+            upsertRecoveryDay(parseRecoveryDay(day));
+            console.log(`  ${day.date ?? "(no date)"}  imported`);
+            imported++;
+        }
+        catch (err) {
+            const date = day.date ?? "(no date)";
+            const reason = err.message;
+            console.log(`  ${date}  FAILED — ${reason}`);
+            failures.push({ date, reason });
+        }
+    }
+    if (failures.length === 0) {
+        log.success(`Imported ${imported} of ${file.days.length} date(s)`);
+    }
+    else if (imported > 0) {
+        log.warn(`Imported ${imported} of ${file.days.length} date(s)`);
+    }
+    if (failures.length > 0) {
+        log.error(`${failures.length} date(s) failed; successfully parsed dates were still committed`);
+        process.exit(1);
+    }
+}
+// ============================================================================
+// Calendar Availability Command
+// ============================================================================
+function runCalendarAvailability(args) {
+    let fileContents;
+    try {
+        fileContents = readFileSync(args.inputFile, "utf-8");
+    }
+    catch {
+        log.error(`Could not read input file: ${args.inputFile}`);
+        process.exit(1);
+    }
+    let input;
+    try {
+        input = JSON.parse(fileContents);
+    }
+    catch {
+        log.error("Input file is not valid JSON");
+        process.exit(1);
+    }
+    if (typeof input !== "object" ||
+        input === null ||
+        typeof input.timeZone !== "string" ||
+        typeof input.window !== "object" ||
+        input.window === null ||
+        typeof input.window.start !== "string" ||
+        typeof input.window.end !== "string" ||
+        !Array.isArray(input.calendars)) {
+        log.error('Input file must have "timeZone", "window" {start,end}, and a "calendars" array');
+        process.exit(1);
+    }
+    if (!isIsoDate(input.window.start) || !isIsoDate(input.window.end)) {
+        log.error('Input file "window.start" and "window.end" must be YYYY-MM-DD dates');
+        process.exit(1);
+    }
+    const output = buildAvailability(input);
+    if (args.json) {
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    for (const day of output.days) {
+        const parts = [];
+        for (const e of day.allDayEvents)
+            parts.push(`[all-day] ${e.title}`);
+        for (const b of day.busyBlocks)
+            parts.push(`${b.start}-${b.end} ${b.title}`);
+        const label = parts.length > 0 ? parts.join("; ") : "clear";
+        console.log(`${day.date} ${day.weekday.padEnd(9)} ${label}`);
+    }
+}
+// ============================================================================
 // Query Command
 // ============================================================================
 async function runQuery(args) {
@@ -499,6 +726,24 @@ async function runQuery(args) {
     }
 }
 // ============================================================================
+// Backup / Restore Commands
+// ============================================================================
+async function runBackupCommand(args) {
+    const code = args.init
+        ? await runInit({ repo: args.repo, quiet: args.quiet })
+        : await runBackup({ push: args.push, quiet: args.quiet });
+    process.exit(code);
+}
+function runRestoreDb(args) {
+    const code = runRestore({
+        dbPath: getDbPath(),
+        dumpPath: args.dumpFile ?? join(getDataDir(), "backup", "coach-db.sql"),
+        schemaPath: join(__dirname, "db", "schema.sql"),
+        force: args.force,
+    });
+    process.exit(code);
+}
+// ============================================================================
 // Main
 // ============================================================================
 async function main() {
@@ -519,12 +764,34 @@ async function main() {
         case "export-garmin":
             runExportGarmin(args);
             break;
+        case "garmin-status":
+            await runGarminStatus(args);
+            break;
+        case "import-garmin":
+            await runImportGarmin(args);
+            break;
+        case "calendar-availability":
+            runCalendarAvailability(args);
+            break;
         case "query":
             await runQuery(args);
             break;
+        case "backup":
+            await runBackupCommand(args);
+            break;
+        case "restore-db":
+            runRestoreDb(args);
+            break;
     }
 }
-main().catch((err) => {
-    log.error(err.message);
-    process.exit(1);
-});
+// Vitest sets VITEST=true in every test process. Importing this module for
+// its exported parsers (parseBackupArgs, etc.) must not also run the CLI
+// against the real environment, so skip main() there. Real invocations
+// (tsx src/cli.ts, or bin/claude-coach.js dynamically importing dist/cli.js)
+// never set this variable.
+if (process.env.VITEST !== "true") {
+    main().catch((err) => {
+        log.error(err.message);
+        process.exit(1);
+    });
+}

package/dist/db/client.js

@@ -12,6 +12,10 @@ async function detectBackend() {
         const sqlite = await import("node:sqlite");
         const dbPath = getDbPath();
         const db = new sqlite.DatabaseSync(dbPath);
+        // A backup dump holds a read-only connection open on this same file. A
+        // coach write during that window would otherwise fail at once with
+        // "database is locked" instead of just waiting the dump out.
+        db.exec("PRAGMA busy_timeout = 5000");
         return {
             query(sql) {
                 const stmt = db.prepare(sql);

package/dist/db/schema.sql

@@ -106,3 +106,67 @@ SELECT
 FROM activities
 ORDER BY start_date DESC
 LIMIT 50;
+
+-- Garmin daily recovery data (one row per calendar date)
+CREATE TABLE IF NOT EXISTS garmin_daily (
+  date TEXT PRIMARY KEY,              -- YYYY-MM-DD, local calendar date
+
+  -- Training readiness (selected entry; see src/recovery/parse.ts)
+  readiness_score INTEGER,
+  readiness_level TEXT,               -- LOW | MODERATE | HIGH | ...
+  readiness_feedback TEXT,            -- RESTED_AND_READY, WELL_DONE, ...
+  readiness_context TEXT,             -- which entry the parser selected
+  readiness_timestamp TEXT,
+  recovery_time_hours REAL,
+  acute_load INTEGER,
+
+  -- Readiness contributing factors (percent, 0-100)
+  sleep_factor_percent INTEGER,
+  recovery_factor_percent INTEGER,
+  training_load_factor_percent INTEGER,
+  hrv_factor_percent INTEGER,
+  stress_history_factor_percent INTEGER,
+  sleep_history_factor_percent INTEGER,
+
+  -- HRV
+  hrv_last_night_ms INTEGER,
+  hrv_weekly_avg_ms INTEGER,
+  hrv_status TEXT,                    -- BALANCED | UNBALANCED | LOW | ...
+  hrv_baseline_low_ms INTEGER,
+  hrv_baseline_upper_ms INTEGER,
+
+  -- Sleep
+  sleep_seconds INTEGER,
+  deep_sleep_seconds INTEGER,
+  light_sleep_seconds INTEGER,
+  rem_sleep_seconds INTEGER,
+  awake_seconds INTEGER,
+  sleep_score INTEGER,
+  sleep_score_qualifier TEXT,         -- EXCELLENT | GOOD | FAIR | POOR
+  avg_overnight_hrv REAL,
+  avg_sleep_stress REAL,
+
+  -- Resting heart rate
+  resting_hr INTEGER,
+
+  raw_json TEXT,                      -- merged raw MCP payloads for this date
+  synced_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_garmin_daily_date ON garmin_daily(date);
+
+DROP VIEW IF EXISTS recovery_recent;
+CREATE VIEW recovery_recent AS
+SELECT
+  date,
+  readiness_score,
+  readiness_level,
+  hrv_last_night_ms,
+  hrv_weekly_avg_ms,
+  hrv_status,
+  ROUND(sleep_seconds / 3600.0, 1) AS sleep_hours,
+  sleep_score,
+  resting_hr
+FROM garmin_daily
+WHERE date >= date('now', '-60 days')
+ORDER BY date DESC;

package/dist/db/sql.d.ts

@@ -0,0 +1,4 @@
+/** Quote a value as a SQL string literal, or NULL. */
+export declare function escapeString(str: string | null | undefined): string;
+/** Render a number as a SQL numeric literal, or NULL. */
+export declare function numOrNull(value: number | null | undefined): string;

package/dist/db/sql.js

@@ -0,0 +1,10 @@
+/** Quote a value as a SQL string literal, or NULL. */
+export function escapeString(str) {
+    if (str == null)
+        return "NULL";
+    return `'${str.replace(/'/g, "''")}'`;
+}
+/** Render a number as a SQL numeric literal, or NULL. */
+export function numOrNull(value) {
+    return value == null ? "NULL" : String(value);
+}

package/dist/lib/config.d.ts

@@ -1,3 +1,4 @@
+export declare function getDataDir(): string;
 export interface StravaConfig {
     client_id: string;
     client_secret: string;

package/dist/lib/config.js

@@ -2,51 +2,57 @@ import { homedir } from "os";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
 import * as readline from "readline";
-const CONFIG_DIR = join(homedir(), ".claude-coach");
-const CONFIG_FILE = join(CONFIG_DIR, "config.json");
-const TOKENS_FILE = join(CONFIG_DIR, "tokens.json");
-const DB_FILE = join(CONFIG_DIR, "coach.db");
+export function getDataDir() {
+    return process.env.CLAUDE_COACH_DIR ?? join(homedir(), ".claude-coach");
+}
+function configFile() {
+    return join(getDataDir(), "config.json");
+}
+function tokensFile() {
+    return join(getDataDir(), "tokens.json");
+}
 export function ensureConfigDir() {
-    if (!existsSync(CONFIG_DIR)) {
-        mkdirSync(CONFIG_DIR, { recursive: true });
+    const dataDir = getDataDir();
+    if (!existsSync(dataDir)) {
+        mkdirSync(dataDir, { recursive: true });
     }
 }
 export function getConfigPath() {
-    return CONFIG_FILE;
+    return configFile();
 }
 export function getTokensPath() {
-    return TOKENS_FILE;
+    return tokensFile();
 }
 export function getDbPath() {
-    return process.env.CLAUDE_COACH_DB ?? DB_FILE;
+    return process.env.CLAUDE_COACH_DB ?? join(getDataDir(), "coach.db");
 }
 export function configExists() {
-    return existsSync(CONFIG_FILE);
+    return existsSync(configFile());
 }
 export function tokensExist() {
-    return existsSync(TOKENS_FILE);
+    return existsSync(tokensFile());
 }
 export function loadConfig() {
     if (!configExists()) {
-        throw new Error(`Config not found at ${CONFIG_FILE}. Run setup first.`);
+        throw new Error(`Config not found at ${configFile()}. Run setup first.`);
     }
-    const data = readFileSync(CONFIG_FILE, "utf-8");
+    const data = readFileSync(configFile(), "utf-8");
     return JSON.parse(data);
 }
 export function saveConfig(config) {
     ensureConfigDir();
-    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+    writeFileSync(configFile(), JSON.stringify(config, null, 2));
 }
 export function loadTokens() {
     if (!tokensExist()) {
-        throw new Error(`Tokens not found at ${TOKENS_FILE}. Run auth first.`);
+        throw new Error(`Tokens not found at ${tokensFile()}. Run auth first.`);
     }
-    const data = readFileSync(TOKENS_FILE, "utf-8");
+    const data = readFileSync(tokensFile(), "utf-8");
     return JSON.parse(data);
 }
 export function saveTokens(tokens) {
     ensureConfigDir();
-    writeFileSync(TOKENS_FILE, JSON.stringify(tokens, null, 2));
+    writeFileSync(tokensFile(), JSON.stringify(tokens, null, 2));
 }
 export function tokensExpired(tokens) {
     // Add 60 second buffer

package/dist/recovery/dates.d.ts

@@ -0,0 +1,12 @@
+import type { DateStatusRow } from "./types.js";
+/** Format a Date as a local-calendar YYYY-MM-DD, matching Garmin's day grain. */
+export declare function toLocalIsoDate(d: Date): string;
+/** The last `n` local dates ending with `today`, oldest first. */
+export declare function lastNDates(n: number, today?: Date): string[];
+/**
+ * Dates the skill should fetch from the Garmin MCP: anything missing or
+ * partial, plus today and yesterday unconditionally — Garmin revises last
+ * night's sleep and HRV hours after the fact, so a `present` row for those two
+ * days may still be stale.
+ */
+export declare function buildFetchList(statuses: DateStatusRow[], today: string, yesterday: string): string[];

package/dist/recovery/dates.js

@@ -0,0 +1,31 @@
+/** Format a Date as a local-calendar YYYY-MM-DD, matching Garmin's day grain. */
+export function toLocalIsoDate(d) {
+    const year = d.getFullYear();
+    const month = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+/** The last `n` local dates ending with `today`, oldest first. */
+export function lastNDates(n, today = new Date()) {
+    const dates = [];
+    for (let offset = n - 1; offset >= 0; offset--) {
+        const d = new Date(today.getTime());
+        d.setDate(d.getDate() - offset);
+        dates.push(toLocalIsoDate(d));
+    }
+    return dates;
+}
+/**
+ * Dates the skill should fetch from the Garmin MCP: anything missing or
+ * partial, plus today and yesterday unconditionally — Garmin revises last
+ * night's sleep and HRV hours after the fact, so a `present` row for those two
+ * days may still be stale.
+ */
+export function buildFetchList(statuses, today, yesterday) {
+    const fetch = new Set([today, yesterday]);
+    for (const { date, status } of statuses) {
+        if (status !== "present")
+            fetch.add(date);
+    }
+    return [...fetch].sort();
+}

package/dist/recovery/index.d.ts

@@ -0,0 +1,4 @@
+export { unwrapPayload, selectReadinessEntry, parseRecoveryDay } from "./parse.js";
+export { upsertRecoveryDay, getDateStatuses } from "./store.js";
+export { toLocalIsoDate, lastNDates, buildFetchList } from "./dates.js";
+export type { RecoveryDay, RecoveryDayInput, RecoveryImportFile, DateStatus, DateStatusRow, } from "./types.js";

package/dist/recovery/index.js

@@ -0,0 +1,3 @@
+export { unwrapPayload, selectReadinessEntry, parseRecoveryDay } from "./parse.js";
+export { upsertRecoveryDay, getDateStatuses } from "./store.js";
+export { toLocalIsoDate, lastNDates, buildFetchList } from "./dates.js";

package/dist/recovery/parse.d.ts

@@ -0,0 +1,21 @@
+import type { RecoveryDay, RecoveryDayInput } from "./types.js";
+/**
+ * Garmin MCP tools return `{ result: "<JSON string>" }` — the payload is a
+ * string containing JSON, not an object. Unwrap it, tolerating an already
+ * parsed object so a hand-assembled import file also works.
+ */
+export declare function unwrapPayload(payload: unknown): unknown;
+/**
+ * Readiness returns several entries per day with different contexts and
+ * different scores. Prefer the morning reading: it answers "should I train
+ * hard today". The post-exercise reset reflects the session just completed and
+ * would double-count fatigue already visible in that day's Strava activity.
+ */
+export declare function selectReadinessEntry(payload: unknown): Record<string, unknown> | null;
+/**
+ * Map one day of verbatim MCP payloads onto a flat row. All field mapping
+ * lives here so a Garmin field rename fails a test instead of being silently
+ * absorbed. Throws on an invalid date or unparseable payload; never on absent
+ * data.
+ */
+export declare function parseRecoveryDay(input: RecoveryDayInput): RecoveryDay;