hae-vault 0.1.0

package/.env.example

@@ -0,0 +1,7 @@
+HVAULT_DB_PATH=~/.hae-vault/health.db
+HVAULT_PORT=4242
+HVAULT_TOKEN=
+HVAULT_WATCH_DIR=~/Downloads
+HVAULT_WATCH_INTERVAL=60
+HVAULT_TARGET=default
+HVAULT_ENV_FILE=

package/CLAUDE.md

@@ -0,0 +1,220 @@
+# hae-vault — Claude Code Guide
+
+## Project Identity
+
+- **npm package name:** `hae-vault`
+- **CLI command:** `hvault`
+- **Install:** `npm install -g hae-vault`
+- **Language:** TypeScript (Node.js 22+, ESM, NodeNext)
+- **Status:** Implemented and working — 570k+ rows ingested from real Apple Health data
+
+---
+
+## What This Project Does
+
+`hae-vault` is an npm package with three responsibilities:
+
+1. **Server** (`hvault serve`): HTTP server that receives health data pushed from the **Health Auto Export** iOS app. POST to `/api/ingest`, writes to local SQLite.
+
+2. **Import** (`hvault import <file>`): Bulk import from a HAE JSON or ZIP export file. Idempotent via SHA-256 hash tracking — skips already-imported files.
+
+3. **Watch** (`hvault watch`): Polls a directory for new HAE export files, auto-imports on schedule. Configurable via env vars.
+
+4. **CLI** (`hvault <command>`): Query interface for AI agents (OpenClaw). Returns JSON.
+
+---
+
+## Ecosystem Context
+
+```
+OpenClaw (AI agent platform, remote server)
+├── skill: whoop-up       ← existing, WHOOP wearable, live API calls
+├── skill: hae-vault      ← Apple Health archive, queries SQLite
+│
+├── whoop-up CLI          ← npm install -g whoop-up (already published)
+└── hvault CLI            ← npm install -g hae-vault (local install)
+     └── reads ~/.hae-vault/health.db (SQLite)
+
+iPhone (Health Auto Export app)
+  └── REST API automation → POST http://server:4242/api/ingest
+        └── writes to health.db via hvault serve
+
+OR
+
+HAE Manual Export → .zip file → hvault import export.zip
+```
+
+---
+
+## Source Structure
+
+```
+hae-vault/
+├── src/
+│   ├── index.ts             ← entry point, Commander CLI
+│   ├── config.ts            ← env config singleton (dotenv + HVAULT_* vars)
+│   ├── server/
+│   │   ├── app.ts           ← Express HTTP server
+│   │   └── ingest.ts        ← parse payload → write to DB, returns IngestResult
+│   ├── db/
+│   │   ├── schema.ts        ← SQLite schema + openDb() + closeDb()
+│   │   ├── metrics.ts       ← upsertMetrics()
+│   │   ├── sleep.ts         ← upsertSleep()
+│   │   ├── workouts.ts      ← upsertWorkout()
+│   │   └── importLog.ts     ← hasBeenImported() + logImport() (SHA-256 dedup)
+│   ├── parse/
+│   │   ├── time.ts          ← 5-format date parser
+│   │   ├── metrics.ts       ← MetricData[] → NormalizedMetric[]
+│   │   ├── sleep.ts         ← detect 3 variants, normalizeSleep()
+│   │   └── workouts.ts      ← WorkoutData[] → NormalizedWorkout
+│   ├── util/
+│   │   └── zip.ts           ← extractPayloadFromZip() — adm-zip, finds HealthAutoExport-*.json
+│   ├── cli/
+│   │   ├── index.ts         ← program + all command registrations
+│   │   ├── serve.ts         ← hvault serve
+│   │   ├── import.ts        ← hvault import <file> (JSON or ZIP, dedup via import_log)
+│   │   ├── watch.ts         ← hvault watch (polls dir, auto-imports, exports tick())
+│   │   ├── metrics.ts       ← hvault metrics --metric <name> --days N
+│   │   ├── sleep.ts         ← hvault sleep --days N
+│   │   ├── workouts.ts      ← hvault workouts --days N
+│   │   ├── summary.ts       ← hvault summary --days N
+│   │   ├── query.ts         ← hvault query "<sql>"
+│   │   └── info.ts          ← hvault sources | last-sync | stats
+│   └── types/
+│       └── hae.ts           ← TypeScript interfaces for HAE payload
+├── tests/
+│   ├── types.test.ts
+│   ├── parse-time.test.ts
+│   ├── parse-sleep.test.ts
+│   ├── parse-metrics.test.ts
+│   ├── parse-workouts.test.ts
+│   ├── db-schema.test.ts
+│   ├── db-metrics.test.ts
+│   ├── db-sleep.test.ts
+│   ├── db-workouts.test.ts
+│   ├── db-import-log.test.ts
+│   ├── ingest.test.ts
+│   ├── util-zip.test.ts
+│   └── cli-watch.test.ts
+├── docs/plans/              ← design + implementation plan docs
+├── CLAUDE.md
+├── SKILL.md                 ← OpenClaw skill definition
+├── package.json             ← bin: { "hvault": "dist/index.js" }
+└── tsconfig.json
+```
+
+---
+
+## CLI Commands
+
+```bash
+# Server
+hvault serve                          # start HTTP ingest server (default port 4242)
+hvault serve --port 4242              # custom port
+hvault serve --token <secret>         # require Authorization: Bearer <secret>
+
+# Import from file (JSON or ZIP)
+hvault import export.json             # import HAE JSON export
+hvault import export.zip              # import HAE zip (extracts HealthAutoExport-*.json)
+hvault import export.zip --target me  # tag with device/person name
+
+# Watch directory for new exports
+hvault watch                          # uses HVAULT_WATCH_DIR env var
+hvault watch --dir ~/Downloads        # watch specific directory
+hvault watch --interval 60            # check every 60 seconds
+
+# Query (all return JSON, --pretty for formatted)
+hvault metrics --metric step_count --days 30
+hvault metrics --metric heart_rate --days 7
+hvault sleep --days 14
+hvault workouts --days 30
+hvault summary --days 90
+hvault query "<sql>"                  # raw SQL → JSON
+hvault sources                        # metric coverage in DB
+hvault last-sync                      # last REST API push received
+hvault stats                          # row counts per table
+```
+
+---
+
+## Environment Variables
+
+Load order: CLI flag > env var > `.env` file > hardcoded default.
+
+In Docker: set env vars directly — no `.env` file needed.
+
+```bash
+HVAULT_ENV_FILE=/path/to/.env            # override .env file location (default: CWD/.env)
+HVAULT_DB_PATH=~/.hae-vault/health.db   # SQLite DB location (tilde expanded)
+HVAULT_PORT=4242                         # serve port
+HVAULT_TOKEN=secret                      # bearer token for serve
+HVAULT_WATCH_DIR=~/Downloads             # directory to watch for exports (tilde expanded)
+HVAULT_WATCH_INTERVAL=60                 # watch poll interval (seconds)
+HVAULT_TARGET=default                    # default target name
+```
+
+---
+
+## SQLite Schema
+
+Database: `~/.hae-vault/health.db`
+
+### Tables
+- `metrics` — all health metrics (steps, HR, HRV, etc.)  `UNIQUE(ts, metric, source, target)`
+- `sleep` — nightly sleep records (3 schema variants handled)  `UNIQUE(date, source, target)`
+- `workouts` — workout sessions  `UNIQUE(ts, name, target)`
+- `sync_log` — REST API push history
+- `import_log` — file import history with SHA-256 hash for deduplication  `UNIQUE(file_hash)`
+
+### Key implementation notes
+- **WAL mode** — concurrent reads while server writes
+- **`INSERT OR REPLACE`** — idempotent upserts throughout
+- **`import_log` hash check** — skip re-importing identical files
+- **DB path** from `HVAULT_DB_PATH` env or `~/.hae-vault/health.db`
+
+---
+
+## Payload Format (HAE REST API)
+
+Top-level:
+```json
+{ "data": { "metrics": [], "workouts": [], "stateOfMind": [], ... } }
+```
+
+### Date format — 5 variants (all handled by `src/parse/time.ts`)
+```
+"2026-01-15 14:30:00 +0000"          ← 24-hour
+"2026-01-15 2:30:00 PM +0000"        ← 12-hour uppercase
+"2026-01-15 2:30:00 pm +0000"        ← 12-hour lowercase
+"2026-01-15 2:30:00\u202fPM +0000"   ← narrow non-breaking space before PM
+"2026-01-15 2:30:00\u202fpm +0000"   ← narrow non-breaking space before pm
+```
+
+### Sleep — 3 schema variants (detected by `src/parse/sleep.ts`)
+- `detailed` — has `startDate`/`endDate` (non-aggregated phases)
+- `aggregated_v2` — has `core`/`deep`/`rem` + `source` (HAE >= 6.6.2)
+- `aggregated_v1` — has `sleepSource`/`inBedSource` (HAE < 6.6.2)
+
+Detection: `'startDate' in dp` → detailed | `'core' in dp` → v2 | else → v1
+
+---
+
+## Development
+
+```bash
+npm install
+npm run dev -- serve             # run server without building
+npm run build                    # compile TypeScript → dist/
+npm test                         # run all tests (59 passing)
+npm install -g .                 # install globally as hvault
+```
+
+---
+
+## Reference Projects
+
+Located at `/Volumes/storage/01_Projects/whoop/healthy/`:
+
+- `health-auto-export-server/` — TypeScript/MongoDB reference. Useful: `MetricName.ts`, `Metric.ts`
+- `apple-health-ingester/` — Go reference. Useful: `types.go` (canonical type defs + time parser)
+- `restapi.md` — Official HAE REST API documentation

package/README.md

@@ -0,0 +1,206 @@
+# hae-vault
+
+[![npm version](https://img.shields.io/npm/v/hae-vault.svg)](https://www.npmjs.com/package/hae-vault)
+
+CLI + HTTP server for Apple Health data from the [Health Auto Export](https://www.healthexportapp.com) iOS app. Ingests via REST API or ZIP file, stores in local SQLite.
+
+```bash
+npm install -g hae-vault
+```
+
+## Quick start
+
+```bash
+hvault serve                          # start ingest server (port 4242)
+hvault import export.zip              # bulk import from HAE export file
+hvault dashboard                      # full terminal dashboard
+hvault summary --color                # N-day averages with emoji indicators
+```
+
+## Setup
+
+1. Install the [Health Auto Export](https://www.healthexportapp.com) iOS app
+2. In HAE: Settings → REST API → set server URL to `http://your-server:4242/api/ingest`
+3. Or: export a ZIP from HAE and run `hvault import export.zip`
+
+**Optional:** create `.env` in your working directory to override defaults:
+
+```env
+HVAULT_DB_PATH=~/.hae-vault/health.db   # SQLite DB location
+HVAULT_PORT=4242                         # ingest server port
+HVAULT_TOKEN=secret                      # bearer token for serve (optional)
+HVAULT_WATCH_DIR=~/Downloads             # directory to watch for exports
+```
+
+## Commands
+
+### Ingest
+
+| Command | Description |
+| --- | --- |
+| `hvault serve` | Start HTTP server, receive HAE REST API pushes |
+| `hvault import <file>` | Import HAE JSON or ZIP export (idempotent) |
+| `hvault watch` | Watch directory and auto-import new HAE exports |
+
+### Query
+
+Output is JSON by default. Add `--pretty` for formatted JSON.
+
+| Command | Description |
+| --- | --- |
+| `hvault metrics --metric <name>` | Time series for a specific metric |
+| `hvault sleep` | Sleep records with stage breakdown |
+| `hvault workouts` | Workout sessions |
+| `hvault summary` | Per-metric averages over N days (JSON) |
+| `hvault query "<sql>"` | Raw SQL query |
+
+### Analysis
+
+Output is pretty-printed by default. Add `--json` for raw JSON.
+
+| Command | Description |
+| --- | --- |
+| `hvault summary --color` | N-day averages with emoji indicators |
+| `hvault dashboard` | Full terminal dashboard with trends |
+| `hvault trends` | Multi-metric trend analysis with direction arrows |
+
+### Info
+
+| Command | Description |
+| --- | --- |
+| `hvault sources` | Metric coverage in DB (name, count, date range) |
+| `hvault last-sync` | Last HAE REST API push received |
+| `hvault stats` | Row counts per table |
+
+## Example output
+
+`hvault dashboard`:
+```
+📅 2026-02-18 | Apple Health Vault
+
+── Sleep (last night) ────────────────
+😴 7.2h | Efficiency: 94%
+   Deep: 1.5h (21%) | REM: 2.1h (29%) | Light: 3.6h (50%)
+   Awake: 0.3h | Source: Apple Watch
+
+── Activity (recent) ─────────────────
+👟 8,432 steps | 🔥 420 kcal active
+   Stand hours: 10
+
+── Heart Health ──────────────────────
+💓 Resting HR: 58bpm | HRV: 44ms
+
+── Recent Workouts ───────────────────
+🚶 2026-02-17  Walking            45min   280 kcal
+🚴 2026-02-15  Cycling            62min   420 kcal
+
+── 7-Day Trends ──────────────────────
+   Steps:         7,200 → 8,432 ↑  (avg 7,840)
+   Sleep:         6.8h → 7.2h ↑   (avg 7.1h)
+   Resting HR:    60 → 58bpm ↓    (avg 59)
+   HRV:           42 → 44ms ↑     (avg 43)
+
+── Vault Stats ───────────────────────
+   Metrics: 570,432 | Sleep: 365 | Workouts: 248
+   Last sync: 2026-02-18 09:23 UTC
+```
+
+`hvault summary --color --days 30`:
+```
+📊 30-Day Summary
+
+👟 Avg Steps:       8,432
+💓 Avg Resting HR:  58bpm
+🧠 Avg HRV:         44ms
+😴 Avg Sleep:       7.2h
+🔥 Avg Active Cal:  420 kcal
+```
+
+`hvault trends --days 7`:
+```
+📊 7-Day Trends
+
+👟 Steps:      8,432 avg (6,100–11,200) ↑
+💓 Resting HR: 58bpm avg (55–62) ↓
+🧠 HRV:        44ms avg (38–52) ↑
+😴 Sleep:      7.2h avg (5.5–8.9h) ↑
+🔥 Active Cal: 420 kcal avg (280–620) →
+```
+
+`hvault stats`:
+```json
+{"metrics":570432,"sleep":365,"workouts":248,"syncs":12}
+```
+
+## Flags
+
+### Ingest flags
+
+| Flag | Applies to | Description |
+| --- | --- | --- |
+| `--port <n>` | serve | HTTP port (default: 4242) |
+| `--token <secret>` | serve | Require `Authorization: Bearer` header |
+| `--target <name>` | import, watch | Tag data with device/person name |
+| `--dir <path>` | watch | Directory to watch |
+| `--interval <s>` | watch | Poll interval in seconds (default: 60) |
+
+### Query flags
+
+| Flag | Description |
+| --- | --- |
+| `--days <n>` | Days of history (default varies per command) |
+| `--metric <name>` | Metric name, e.g. `step_count`, `resting_heart_rate` |
+| `--pretty` | Pretty-print JSON output |
+
+### Analysis flags
+
+| Flag | Applies to | Description |
+| --- | --- | --- |
+| `--days <n>` | all analysis | Days of history (default: 7 or 90) |
+| `-c, --color` | summary | Pretty terminal output |
+| `--json` | dashboard, trends | Raw JSON output |
+
+## Environment variables
+
+Load order: CLI flag > env var > `.env` file > default.
+
+```bash
+HVAULT_DB_PATH=~/.hae-vault/health.db   # SQLite DB location
+HVAULT_PORT=4242                         # serve port
+HVAULT_TOKEN=secret                      # bearer token for serve
+HVAULT_WATCH_DIR=~/Downloads             # directory to watch
+HVAULT_WATCH_INTERVAL=60                 # watch poll interval (seconds)
+HVAULT_TARGET=default                    # default target name
+HVAULT_ENV_FILE=/path/to/.env            # override .env file location
+```
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | General error |
+
+## Development
+
+```bash
+git clone https://github.com/mrkhachaturov/hae-vault.git
+cd hae-vault
+npm install
+
+npm run dev -- serve         # run server without building
+npm run dev -- dashboard     # run dashboard without building
+npm run build                # compile TypeScript → dist/
+npm test                     # run test suite
+npm install -g .             # install globally as hvault
+```
+
+Node.js 22+ required.
+
+## Full command reference
+
+→ [docs/COMMANDS.md](docs/COMMANDS.md)
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: hae-vault
+description: >
+  Apple Health archive database. Use for: historical Apple Health data (steps,
+  heart rate, HRV, sleep, workouts, mindfulness, respiratory rate, blood oxygen
+  from iPhone/Apple Watch), multi-day trends, long-term patterns. Data comes
+  from Health Auto Export iOS app synced to local SQLite. NOT for WHOOP data —
+  use whoop-up skill for that. NOT for live/real-time data.
+metadata:
+  openclaw:
+    emoji: "🍎"
+    requires:
+      bins:
+        - hvault
+    install:
+      - id: node
+        kind: node
+        package: hae-vault
+        bins:
+          - hvault
+        label: "Install hae-vault (node)"
+---
+
+# hae-vault
+
+Query Apple Health data stored locally by `hvault serve` from the Health Auto Export iOS app.
+
+## Commands
+
+```bash
+# Query last 30 days of steps
+hvault metrics --metric step_count --days 30
+
+# Query HRV
+hvault metrics --metric heart_rate_variability --days 30
+
+# Query sleep (last 14 nights)
+hvault sleep --days 14
+
+# Query workouts (last 30 days)
+hvault workouts --days 30
+
+# Summary averages across all metrics (90 days)
+hvault summary --days 90
+
+# Raw SQL for custom queries
+hvault query "SELECT date, qty FROM metrics WHERE metric='step_count' ORDER BY date DESC LIMIT 7"
+
+# What's in the DB?
+hvault sources
+hvault last-sync
+hvault stats
+```
+
+## Available Metrics (common)
+
+step_count, heart_rate, heart_rate_variability, resting_heart_rate,
+active_energy, basal_energy_burned, respiratory_rate, blood_oxygen_saturation,
+weight_body_mass, body_fat_percentage, sleep_analysis (via hvault sleep),
+mindful_minutes, vo2max, walking_running_distance, flights_climbed

package/dist/cli/dashboard.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const dashboardCommand: Command;
+//# sourceMappingURL=dashboard.d.ts.map

package/dist/cli/dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../../src/cli/dashboard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6GpC,eAAO,MAAM,gBAAgB,SAoIzB,CAAC"}