trainbud 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zsadigzade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICKSTART.md

@@ -0,0 +1,182 @@
+# Quickstart
+
+Get TrainBud running in about 5 minutes.
+
+## Prerequisites
+
+- Node.js 20 or newer ([`.nvmrc`](./.nvmrc) included)
+- A Garmin Connect account with synced device data
+- Garmin Connect **MFA disabled** (the underlying library does not support MFA yet)
+
+## Recommended: one-command setup
+
+```bash
+git clone https://github.com/Zsadigzade/trainbud.git
+cd trainbud
+npm install
+npm run build
+npm link          # puts `trainbud` on your PATH
+trainbud setup
+```
+
+> `npm link` is what makes the bare `trainbud` command work. Without it every
+> `trainbud ...` line below is "command not found", because TrainBud is not on
+> the npm registry — so `trainbud` does **not** work either, and would run
+> whatever gets published under that name in future. If you would rather not
+> link, every command works as `node dist/index.js <command>` from the repo root.
+> Undo with `npm unlink -g trainbud`.
+
+The setup wizard will:
+
+1. Ask for your Garmin Connect email and password
+2. Save credentials to `.env`
+3. Authenticate with Garmin Connect
+4. Detect Cursor and Claude Desktop on your machine
+5. Offer to add TrainBud to your MCP client config automatically
+6. Optionally run a live API check against all 9 tools
+
+After setup, **restart your MCP client completely** (Cursor or Claude Desktop), then ask:
+
+- "What did I do today?"
+- "How's my sleep been this week?"
+- "Am I recovered enough to train hard?"
+
+### Claude Code: plugin or slash commands
+
+**Plugin (recommended)** — skills + MCP in one install:
+
+```bash
+/plugin marketplace add Zsadigzade/trainbud
+/plugin install trainbud@trainbud
+```
+
+Then `/trainbud:trainbud-setup` and `/trainbud:trainbud`.
+
+**In-repo skills** — if you cloned the repo and run `claude` here:
+
+1. `/trainbud-setup` — guided install + MCP config + live check
+2. Restart MCP client
+3. `/trainbud` — ask any fitness question
+
+See [`plugin/README.md`](./plugin/README.md) for plugin details.
+
+## Verify without an MCP client
+
+After setup, you can confirm Garmin Connect access directly:
+
+```bash
+trainbud check
+```
+
+Example output:
+
+```text
+TrainBud live check
+
+  get_latest_activity       ✓  Activity: Morning Run, Distance: 5.2 km, Start: ...
+  get_activities_range      ✓  3 activities found
+  get_sleep_data            ✓  7 nights retrieved
+  get_heart_rate_trends     ✓  30-day trend loaded
+  get_recovery_status       ✓  Score: 72 (Ready to train)
+  get_body_composition      ✗  No body composition data found for the last 30 days.
+  get_stress_levels         ✓  7-day stress trend loaded
+  get_vo2_max_trends        ✓  30-day VO2 max trend loaded
+  get_training_insights     ✓  Weekly summary generated
+
+All 9 checks passed. TrainBud is ready to use.
+```
+
+## Manual setup (alternative)
+
+If you prefer to configure files yourself:
+
+### 1. Install
+
+```bash
+git clone https://github.com/Zsadigzade/trainbud.git
+cd trainbud
+npm install
+```
+
+### 2. Configure credentials
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+GARMIN_EMAIL=your@email.com
+GARMIN_PASSWORD=yourpassword
+```
+
+### 3. Build and authenticate
+
+```bash
+npm run build
+trainbud auth
+```
+
+You should see: `Garmin authentication successful. Session saved.`
+
+### 4. Connect to Cursor or Claude Desktop
+
+**Cursor:** `%USERPROFILE%\.cursor\mcp.json` (Windows) or `~/.cursor/mcp.json` (macOS/Linux)
+
+**Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`  
+**Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "trainbud": {
+      "command": "node",
+      "args": ["C:/path/to/trainbud/dist/index.js", "start"],
+      "env": {
+        "GARMIN_EMAIL": "your@email.com",
+        "GARMIN_PASSWORD": "yourpassword"
+      }
+    }
+  }
+}
+```
+
+Restart your MCP client.
+
+## Web AI (claude.ai, ChatGPT)
+
+For web AI platforms that require remote MCP connectors:
+
+```bash
+trainbud serve
+```
+
+Then expose via HTTPS tunnel and add to claude.ai Connectors. Full guide: [docs/WEB-MCP.md](./docs/WEB-MCP.md)
+
+## Useful commands
+
+```bash
+trainbud setup         # Interactive first-time setup (recommended)
+trainbud serve         # Remote HTTP MCP for web AI connectors
+trainbud check         # Live diagnostics against all tools
+trainbud status        # Check session + cache
+trainbud cache clear   # Force fresh data fetch
+trainbud auth          # Re-login if session expired
+trainbud start         # Start MCP server manually (stdio)
+```
+
+## Troubleshooting setup
+
+| Issue | Fix |
+|-------|-----|
+| Authentication failed | Verify email/password; disable MFA at connect.garmin.com |
+| MCP client doesn't see tools | Restart the client completely (not just reload window) |
+| Stale data | Run `trainbud cache clear` |
+| `dist/index.js` not found | Run `npm run build` |
+
+## Next steps
+
+- [README.md](./README.md) — full reference
+- [examples/prompts.md](./examples/prompts.md) — sample questions
+- [docs/VAULT.md](./docs/VAULT.md) — architecture, branding, and design notes (Obsidian vault)

package/README.md

@@ -0,0 +1,322 @@
+# TrainBud
+
+**Talk to your training data.**
+
+TrainBud is an open-source MCP server that connects your Garmin Connect fitness data to Claude, Cursor, and other AI assistants. Ask about workouts, sleep, heart rate, recovery, and body composition in plain English — privately, on your machine.
+
+> **Disclaimer:** TrainBud is an unofficial community project. It is not affiliated with, endorsed by, or sponsored by Garmin Ltd. Garmin Connect is a trademark of Garmin Ltd.
+
+[![CI](https://github.com/Zsadigzade/trainbud/actions/workflows/ci.yml/badge.svg)](https://github.com/Zsadigzade/trainbud/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node 20+](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](.nvmrc)
+
+## Try it
+
+Once connected to your MCP client, ask things like:
+
+- *"What did I do today?"*
+- *"How's my sleep been this week?"*
+- *"Am I recovered enough to train hard tomorrow?"*
+- *"Is my resting heart rate trending down?"*
+
+See [examples/prompts.md](./examples/prompts.md) for more ideas.
+
+## Why TrainBud
+
+- **Private** — credentials stay in your local `.env`; data is cached on your machine
+- **Local-first** — SQLite cache, session tokens in `.trainbud/`
+- **Works everywhere** — Windows, macOS, Linux (Node.js 20+)
+- **Any MCP client** — Claude Desktop, Cursor, and other stdio-compatible clients
+- **Smart fetching** — batched API calls and automatic re-auth when sessions expire
+
+## Quick start
+
+```bash
+npx trainbud setup
+```
+
+The setup wizard walks you through credentials, authentication, and connecting Cursor or
+Claude Desktop — no MCP config editing required. Then restart your MCP client and ask it
+what you did today.
+
+To keep `trainbud` on your PATH instead of typing `npx` every time:
+
+```bash
+npm install -g trainbud
+trainbud setup
+```
+
+Needs Node 20+. Full walkthrough: [QUICKSTART.md](./QUICKSTART.md)
+
+<details>
+<summary><b>From source</b> (for contributors, or to run an unreleased commit)</summary>
+
+```bash
+git clone https://github.com/Zsadigzade/trainbud.git
+cd trainbud
+npm install
+npm run build
+npm link          # puts `trainbud` on your PATH; undo with `npm unlink -g trainbud`
+trainbud setup
+```
+
+Without `npm link`, every `trainbud <command>` in this README is
+`node dist/index.js <command>` run from the repo root. If `dist/` does not exist yet,
+run `npm run build` first.
+</details>
+
+## Claude Code plugin (recommended)
+
+Install as a [Claude Code plugin](https://code.claude.com/docs/en/plugins) — skills **and** MCP server in one step:
+
+```bash
+/plugin marketplace add Zsadigzade/trainbud
+/plugin install trainbud@trainbud
+```
+
+Set credentials, then restart Claude Code:
+
+```bash
+export GARMIN_EMAIL="your@email.com"
+export GARMIN_PASSWORD="yourpassword"
+```
+
+| Command | What it does |
+|---------|----------------|
+| `/trainbud:trainbud-setup` | First-time setup and diagnostics |
+| `/trainbud:trainbud` | Ask about workouts, sleep, recovery, HR, stress, VO2 max |
+
+Plugin files live in [`plugin/`](./plugin/). See [`plugin/README.md`](./plugin/README.md).
+
+## Claude Code skills (in-repo)
+
+This repo also ships project skills in [`.claude/skills/`](./.claude/skills/) for development without installing the plugin:
+
+| Command | What it does |
+|---------|----------------|
+| `/trainbud-setup` | Install, authenticate, configure MCP, run live check |
+| `/trainbud` | Ask about workouts, sleep, recovery, HR, stress, VO2 max |
+
+Open the repo in **Claude Code** (`claude` in this directory) — skills load automatically.
+
+To use skills in **every** project without the plugin, copy them to `~/.claude/skills/`.
+
+After setup, restart your MCP client and try `/trainbud` with *"What did I do today?"*
+
+## Dashboard
+
+`trainbud serve` hosts a dashboard at `/dashboard`. It is phone-first, because the
+pairing flow is: you are standing next to the watch holding a phone when you approve a
+code.
+
+It shows what stands out today against your own baselines, this week against last week,
+and resting heart rate and sleep plotted against your own 30-day median — all read from
+the local history store, so it paints instantly and works even when your Connect session
+has expired. **A break in a line is a day with no measurement, not a zero.**
+
+It is also where you tell TrainBud who it is talking to:
+
+| Setting | What it changes |
+|---|---|
+| Name, units, primary sport, weekly goal | Every renderer, and what the AI is told about you |
+| Thresholds | Where green becomes amber and amber becomes red — on the watch too |
+| Watch cards | Which cards appear on the wrist and in what order, live on the next sync |
+| AI model, tone, answer length | How the Ask card and the daily insight sound |
+| Your own Ask questions | Up to five, 32 characters each. They lead the watch's Ask menu; the rest of the slots stay generated from what fired |
+| Monthly spending cap | Optional. Refuses an Ask past the cap instead of spending past it |
+| Privacy | Local feature counters, on by default, with a delete button |
+
+**Usage.** TrainBud runs on your own AI provider key, so every question and every daily
+insight is charged to you. The dashboard shows the tokens and cost per call, the month to
+date, and a 30-day chart. A model this build has no published price for is recorded with
+its cost left *unknown* rather than as zero — a call priced at zero would make a cap that
+can never trip.
+
+Nothing on this page leaves your machine. There is no endpoint to send it to.
+
+## Garmin watch widget (Connect IQ)
+
+View recovery, sleep, activity, stress, and VO2 max on your Garmin watch via a Connect IQ widget in [`ciq/`](./ciq/).
+
+**Requires:** `trainbud serve` running + HTTPS tunnel (same setup as web AI).
+
+1. Start the server and tunnel:
+   ```bash
+   trainbud serve
+   cloudflared tunnel --url http://127.0.0.1:3847
+   ```
+2. Build and sideload the widget — see [ciq/README.md](./ciq/README.md)
+3. In **Garmin Connect Mobile** → Connect IQ → TrainBud settings, set:
+   - **Server URL** — your tunnel URL (e.g. `https://abc.trycloudflare.com`)
+4. Open the widget on your watch — it shows a pairing code. Approve it in the dashboard (`/dashboard?token=YOUR_API_KEY`) to complete setup. The dashboard swaps that token for a session cookie and drops it from the URL, so the address bar is safe to screenshot afterwards.
+
+The glance shows recovery and sleep from the last cached summary, so it renders without
+waiting on the network. Open it and tap or swipe to cycle through the cards you left switched on in the dashboard. The watch
+calls `GET /api/watch` — a compact JSON summary, not the full MCP protocol.
+
+## Connect to Claude Desktop
+
+Edit `claude_desktop_config.json`:
+
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`  
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "trainbud": {
+      "command": "node",
+      "args": ["C:/path/to/trainbud/dist/index.js", "start"],
+      "env": {
+        "GARMIN_EMAIL": "your@email.com",
+        "GARMIN_PASSWORD": "yourpassword"
+      }
+    }
+  }
+}
+```
+
+With `trainbud` on your PATH (`npm install -g trainbud`, or `npm link` from a clone),
+point the client at the command instead of a path:
+
+```json
+{
+  "mcpServers": {
+    "trainbud": {
+      "command": "trainbud",
+      "args": ["start"]
+    }
+  }
+}
+```
+
+Restart your MCP client, then start asking questions.
+
+## Tools
+
+| Tool | What it answers |
+|------|-----------------|
+| `get_latest_activity` | Your most recent workout — distance, pace, HR, elevation |
+| `get_activities_range` | Activities between two dates |
+| `get_sleep_data` | Sleep duration, stages, score, awakenings |
+| `get_heart_rate_trends` | Resting, max, and average HR over time |
+| `get_recovery_status` | Recovery score from HRV, sleep, stress, resting HR |
+| `get_body_composition` | Weight, body fat, and muscle mass trends |
+| `get_stress_levels` | Daily stress averages and trends |
+| `get_vo2_max_trends` | VO2 max fitness trends over time |
+| `get_training_insights` | Combined weekly summary (activities, sleep, recovery, stress) |
+| `get_findings` | What stands out against **your own** 28-day baselines, not a population average |
+| `get_week_review` | This week against last, the load forecast, sleep debt, and your next race |
+| `remember_context` | Record a goal, a race and its date, an injury, or a note |
+| `get_user_context` | What is on record about you, on any date |
+| `log_subjective` | How a session actually felt — RPE, soreness, mood |
+
+## CLI
+
+```bash
+trainbud setup          # Interactive first-time setup (recommended)
+trainbud serve          # Remote HTTP MCP for web AI (claude.ai, ChatGPT)
+trainbud check          # Live diagnostics against all tools
+trainbud doctor         # What the watch would see: public URL, AI key, history depth
+trainbud backfill       # Pull Garmin history into the local store (resumable)
+trainbud findings       # What stands out against your own baselines
+trainbud start          # Start the MCP server (stdio)
+trainbud auth           # Force re-authentication
+trainbud cache clear    # Clear cached data
+trainbud status         # Show session and cache status
+trainbud --version      # Print version
+```
+
+Every one of these also works as `npx trainbud <command>` without installing anything.
+
+### Troubleshooting: `trainbud: command not found`
+
+Either use `npx trainbud <command>`, or install it globally with
+`npm install -g trainbud`. Running from a clone instead? Run `npm link` once from the
+repo root, or call the built entry point directly with `node dist/index.js doctor`
+(after `npm run build`).
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GARMIN_EMAIL` | — | Garmin Connect email |
+| `GARMIN_PASSWORD` | — | Garmin Connect password |
+| `TRAINBUD_SESSION_PATH` | `.trainbud/session.json` | Session token storage |
+| `TRAINBUD_LOG_PATH` | `.trainbud/mcp.log` | Log file path |
+| `TRAINBUD_CACHE_PATH` | `.trainbud/cache.db` | SQLite cache database |
+| `CACHE_TTL_ACTIVITIES` | `1800` | Activity cache TTL (seconds) |
+| `CACHE_TTL_SLEEP` | `7200` | Sleep cache TTL (seconds) |
+| `CACHE_TTL_STATS` | `3600` | Stats cache TTL (seconds) |
+| `TRAINBUD_API_KEY` | auto-generated | Bearer token for HTTP MCP (`trainbud serve`) |
+| `TRAINBUD_HOST` | `127.0.0.1` | Bind host for HTTP server |
+| `TRAINBUD_PORT` | `3847` | Bind port for HTTP server |
+
+## Security & privacy
+
+- Credentials live only in your local `.env` file — never sent to a third party
+- Session tokens in `.trainbud/session.json` are as sensitive as a password
+- Tool errors are sanitized before reaching the AI client
+- Uses the unofficial [`garmin-connect`](https://www.npmjs.com/package/garmin-connect) npm package (not Garmin's enterprise OAuth API)
+- **MFA is not supported** by the underlying library — disable MFA or use an app-specific password
+- The server binds `127.0.0.1` by default. It is only reachable from the internet if
+  you point a tunnel at it, and every route except `/health` needs the API key
+- The dashboard takes the key once, on `/dashboard?token=…`, then trades it for an
+  `HttpOnly` session cookie and redirects to a clean URL — so the key does not sit in
+  your address bar, your history, or a screenshot
+- **A paired watch holds the API key itself**, not a scoped per-device token. Pairing
+  approval hands over the same key that opens the dashboard and `/mcp`. Revoke a watch
+  by changing `TRAINBUD_API_KEY` and pairing again. A narrower per-device token is
+  planned; until then, treat pairing as handing out a password
+
+### What TrainBud is not
+
+- **Not a hosted service.** There is no TrainBud account and no TrainBud server. You run
+  it, on your machine, against your own Garmin credentials
+- **Not an official Garmin integration.** It drives an unofficial library against the
+  Connect web API. Garmin can change that API without notice, and does
+- **Not MFA-compatible.** If your Connect account has MFA on, this will not log in
+- **Not free to ask.** The AI features run on your own Anthropic key and are billed to
+  you. The dashboard meters every call and can refuse past a cap you set
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Authentication failed | Verify `.env` credentials, run `trainbud auth` |
+| MFA enabled on account | Disable MFA or use an app-specific password |
+| Stale data | Run `trainbud cache clear` |
+| Rate limited | Wait 60 seconds; cached responses are used when available |
+| Watch shows "Not a TrainBud server" or error -400 | Your public URL is answering with something that is not TrainBud's JSON — usually a tunnel that is down. Run `trainbud doctor`; it says exactly what came back |
+| Watch shows "Watch not authorised" | The API key changed since the watch paired. Pair it again from the dashboard |
+| Watch shows "AI not set up" | AI is bring-your-own-key. Paste an Anthropic key into the dashboard |
+| No sleep/HR data | Ensure your Garmin device has synced to Garmin Connect |
+| Server won't start | Check that `GARMIN_EMAIL` and `GARMIN_PASSWORD` are set in `.env` |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test          # 551 tests via the Node test runner
+npm run lint
+npm run dev       # Start with auto-reload
+```
+
+Use `.nvmrc` with nvm/fnm for Node 20. If your project path contains `#`, use `npm test` instead of `npm run test:vitest`.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [docs/VAULT.md](./docs/VAULT.md) for architecture and design notes (Obsidian vault, outside this repo).
+
+## Roadmap
+
+- [x] VO2 max trends
+- [x] Stress levels
+- [x] Training insights
+- [ ] Workout comparison
+- [ ] Docker image
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+Garmin Connect is a trademark of Garmin Ltd. This project is not affiliated with Garmin Ltd.

package/dist/appDb.d.ts

@@ -0,0 +1,83 @@
+import Database from "better-sqlite3";
+export interface PairToken {
+    code: string;
+    created_at: number;
+    expires_at: number;
+    approved_at: number | null;
+}
+export interface PromptJob {
+    id: string;
+    prompt: string;
+    status: "pending" | "running" | "done" | "error";
+    result: string | null;
+    error: string | null;
+    created_at: number;
+    completed_at: number | null;
+}
+export declare const APP_DB_SCHEMA = "\n    CREATE TABLE IF NOT EXISTS settings (\n      key   TEXT PRIMARY KEY,\n      value TEXT NOT NULL\n    );\n    CREATE TABLE IF NOT EXISTS pair_tokens (\n      code        TEXT PRIMARY KEY,\n      created_at  INTEGER NOT NULL,\n      expires_at  INTEGER NOT NULL,\n      approved_at INTEGER\n    );\n    CREATE TABLE IF NOT EXISTS prompt_jobs (\n      id           TEXT PRIMARY KEY,\n      prompt       TEXT NOT NULL,\n      status       TEXT NOT NULL DEFAULT 'pending',\n      result       TEXT,\n      error        TEXT,\n      created_at   INTEGER NOT NULL,\n      completed_at INTEGER\n    );\n\n    -- Usage. cost_usd is nullable ON PURPOSE: a model this build has no\n    -- published price for records its tokens and leaves the cost unknown,\n    -- because a call priced at zero is a monthly cap that can never trip.\n    -- The schema lives here rather than in usage.ts so that opening the\n    -- database does not have to import the module that writes to it.\n    CREATE TABLE IF NOT EXISTS ai_usage (\n      id            INTEGER PRIMARY KEY AUTOINCREMENT,\n      at            INTEGER NOT NULL,\n      kind          TEXT    NOT NULL,\n      model         TEXT    NOT NULL,\n      source        TEXT    NOT NULL,\n      input_tokens  INTEGER NOT NULL,\n      output_tokens INTEGER NOT NULL,\n      cache_read_tokens  INTEGER NOT NULL DEFAULT 0,\n      cache_write_tokens INTEGER NOT NULL DEFAULT 0,\n      cost_usd      REAL\n    );\n    CREATE INDEX IF NOT EXISTS ai_usage_at ON ai_usage(at);\n\n    CREATE TABLE IF NOT EXISTS feature_usage (\n      name  TEXT NOT NULL,\n      day   TEXT NOT NULL,\n      count INTEGER NOT NULL,\n      PRIMARY KEY (name, day)\n    );\n";
+/**
+ * The open handle, for modules that own their own tables.
+ *
+ * `usage.ts` needs to read and write two tables of its own; routing that
+ * through a per-statement wrapper here would put its SQL in a file that has
+ * nothing to do with metering. The connection stays owned in one place -- this
+ * hands out the handle, not a second one.
+ */
+export declare function getAppDb(): Database.Database;
+export declare function getSetting(key: string): string | null;
+export declare function setSetting(key: string, value: string): void;
+export declare function deleteSetting(key: string): void;
+/** Setting keys starting with `prefix`, used to prune dated cache entries. */
+export declare function listSettingKeys(prefix: string): string[];
+/**
+ * A pair code is a bearer credential in disguise: /api/pair is unauthenticated
+ * by design, and /api/pair/<code>/status hands out the API key as soon as that
+ * code is approved. Math.random() was the source here, which means an attacker
+ * who mints a handful of codes from the open endpoint can recover the PRNG
+ * state and predict the code the real watch is displaying. randomInt draws from
+ * the CSPRNG, uniformly and without modulo bias, and zero-padding keeps the
+ * full six-digit space (including 000042) in play.
+ */
+export declare function generatePairCode(): string;
+export declare function createPairToken(): PairToken;
+export declare function getPairToken(code: string): PairToken | null;
+export declare function approvePairToken(code: string): boolean;
+export declare function deletePairToken(code: string): void;
+export declare function listPendingPairTokens(): PairToken[];
+/**
+ * How old an unfinished job has to be before it counts as wreckage.
+ *
+ * The watch polls a job id for about thirty seconds and then gives up, so
+ * anything younger than that is, or was until moments ago, an answer somebody
+ * is waiting for. Five minutes leaves room for a slow model call as well.
+ */
+export declare const STALE_PROMPT_JOB_SECONDS: number;
+/**
+ * A job the process died in the middle of is not still running.
+ *
+ * THIS USED TO RUN INSIDE `getDb()`, so the first time ANY process opened
+ * app.db it flipped every pending and running row to
+ * "The server stopped before this answer came back." -- including the rows
+ * belonging to a `serve` that was, at that moment, waiting on Anthropic. Every
+ * entry point opens this file, so asking a question on the watch and then
+ * running `trainbud doctor`, `status`, `findings` or a backfill killed the live
+ * answer from another process, and the watch drew "AI unavailable".
+ *
+ * Two changes, and both are needed. It is called once, from `serve` at startup,
+ * so a CLI command no longer writes to a server's table at all. And it will not
+ * touch a job younger than STALE_PROMPT_JOB_SECONDS, which is what protects a
+ * second server on the same box, and a restart racing an answer that is still
+ * in flight.
+ */
+export declare function reconcileStalePromptJobs(db: Database.Database, now?: number): void;
+/** Called once by `serve`, which is the only process that owns these jobs. */
+export declare function reconcilePromptJobsOnStartup(): void;
+export declare function createPromptJob(id: string, prompt: string): PromptJob;
+export declare function getPromptJob(id: string): PromptJob | null;
+export declare function updatePromptJob(id: string, update: {
+    status: PromptJob["status"];
+    result?: string;
+    error?: string;
+}): void;
+export declare function closeAppDb(): void;
+//# sourceMappingURL=appDb.d.ts.map

package/dist/appDb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appDb.d.ts","sourceRoot":"","sources":["../src/appDb.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AActC,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACjD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAID,eAAO,MAAM,aAAa,2pDA8CzB,CAAC;AAqBF;;;;;;;GAOG;AACH,wBAAgB,QAAQ,IAAI,QAAQ,CAAC,QAAQ,CAE5C;AAID,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAI3D;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAKxD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAgB,eAAe,IAAI,SAAS,CAqB3C;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAK3D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAStD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAElD;AAED,wBAAgB,qBAAqB,IAAI,SAAS,EAAE,CAKnD;AAOD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,GAAG,SAAgC,GAClC,IAAI,CAWN;AAOD,8EAA8E;AAC9E,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAarE;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKzD;AAED,wBAAgB,eAAe,CAC7B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE;IAAE,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACvE,IAAI,CAWN;AAED,wBAAgB,UAAU,IAAI,IAAI,CAKjC"}