ray-finance 0.2.2 → 0.2.4

package/SPEC.md

@@ -1,374 +0,0 @@
-# Ray Finance — Open Source Product Spec
-
-## Vision
-
-An open-source, local-first CLI that turns your bank data into a personal AI financial advisor. Everything runs on your machine. Your data never leaves your computer except for Plaid API calls (to sync bank data), Anthropic API calls (for AI chat), and optionally Resend API calls (for email digests).
-
-**Target audience:** Engineers who are finance-minded and want to optimize. People who'd rather query a SQLite database than open a budgeting app.
-
-**Positioning:** "Your finances in a local SQLite database. AI-powered. Private by design."
-
----
-
-## What Exists Today
-
-`ray-finance` is a fully functional personal finance AI agent built for couples. Current architecture:
-
-| Layer | Status | Files |
-|-------|--------|-------|
-| Plaid integration (sync, balances, investments, liabilities) | ✅ Complete | `plaid/client.ts`, `sync.ts`, `link.ts` |
-| Encrypted SQLite database (multi-tenant capable) | ✅ Complete | `db/connection.ts`, `schema.ts`, `encryption.ts` |
-| AI agent (Claude + tool use, agentic loop) | ✅ Complete | `ai/agent.ts`, `tools.ts`, `system-prompt.ts` |
-| 13 AI tools (net worth, transactions, budgets, goals, etc.) | ✅ Complete | `ai/tools.ts` |
-| Conversation memory + long-term memories | ✅ Complete | `ai/memory.ts` |
-| Daily scoring (0-100) + streaks | ✅ Complete | `scoring/index.ts` |
-| 14 achievements (gamification) | ✅ Complete | `scoring/index.ts` |
-| Alerts (large txns, low balance, budget overruns, price changes) | ✅ Complete | `alerts/index.ts` |
-| Daily sync + auto-recategorization (DB-driven rules) | ✅ Complete | `daily-sync.ts` |
-| Plaid Link web UI (bank connection flow) | ✅ Complete | `public/link.html`, `server.ts` |
-| Telegram bot interface | ✅ Complete | `telegram/bot.ts` |
-| Multi-tenant registry (hosted mode) | ✅ Complete | `db/registry.ts` |
-| Audit logging | ✅ Complete | `ai/audit.ts` |
-| Docker deployment | ✅ Complete | `Dockerfile`, `docker-compose.yml` |
-| Debt payoff simulator | ✅ Complete | `db/helpers.ts` |
-
----
-
-## What Needs to Change
-
-### 1. Remove Telegram, Add CLI
-
-**Strip:** `telegram/bot.ts`, Telegram references in `index.ts` and `config.ts`.
-
-**Add:** A CLI interface that replaces Telegram as the primary interaction layer.
-
-```
-ray                     # Interactive chat with your AI financial advisor
-ray sync                # Pull latest from Plaid
-ray link                # Connect a new bank account (opens browser)
-ray status              # Quick dashboard: balances, budgets, score
-ray transactions        # Recent transactions
-ray spending [period]   # Spending summary
-ray budgets             # Budget status
-ray goals               # Goal progress
-ray score               # Today's score + streaks
-ray alerts              # Active alerts
-ray forecast            # Project checking account balance through end of month
-ray digest              # Send daily digest email now
-ray setup               # Interactive first-run wizard
-```
-
-`ray` with no args drops into an interactive chat session — same AI agent, same tools, but in the terminal. Think `claude` CLI but for your finances.
-
-### 2. Setup Wizard (`ray setup`)
-
-```
-$ ray setup
-
-Welcome to Ray 🐟
-
-Your AI-powered financial advisor. Everything runs locally.
-
-Step 1: Plaid API keys
-  → Get free Development keys at https://dashboard.plaid.com/signup
-  Client ID: ________
-  Secret: ________
-
-Step 2: Connect your bank
-  → Opening Plaid Link in your browser...
-  ✓ Connected: Bank of America (3 accounts)
-  ✓ Synced 847 transactions
-
-Step 3: Anthropic API key (for AI chat)
-  → Get one at https://console.anthropic.com
-  API key: ________
-
-Step 4: Daily digest email (optional)
-  → Send daily email summaries via Resend
-  Resend API key: ________ (skip with Enter)
-  Email address: ________
-
-Step 5: Scheduled sync (optional)
-  → Set up automatic daily sync at 7am?
-  ✓ Created launchd agent (macOS) / cron job (Linux)
-
-✓ Setup complete. Run `ray` to start chatting.
-```
-
-Stores config in `~/.ray/config.json`, database in `~/.ray/data/finance.db`.
-
-### 3. Port Features from Personal Ray (`/Developer/ray`)
-
-The personal `ray` project has battle-tested features that `ray-finance` doesn't:
-
-| Feature | Personal `ray` | `ray-finance` | Action |
-|---------|---------------|---------------|--------|
-| Checking account forecast | ✅ Full | ❌ Missing | Port & generalize `forecast/bills-account.ts` |
-| Daily digest email | ✅ Minimal (just rebuilt) | ❌ Missing | Port the new 5-section minimal digest |
-| Leakage tracking | ✅ Just built | ❌ Missing | Port, generalize for any account-to-account transfers |
-| Auto-recategorization | Hardcoded | DB-driven rules table | `ray-finance` approach is better — keep it |
-| Net worth + property tracking | ✅ Redfin integration | ✅ Basic snapshots | Port Redfin scraper as optional plugin |
-| Debt payoff simulation | Basic | ✅ `simulatePayoff()` | Already in `ray-finance` |
-| Investment holdings sync | Manual | ✅ Plaid native | `ray-finance` is better |
-
-### 4. Package & Distribution
-
-```bash
-# Run directly
-npx ray-finance setup
-
-# Or clone and link
-git clone https://github.com/clarkdinnison/ray-finance
-cd ray-finance && npm install && npm link
-```
-
-Global CLI binary via `package.json` `"bin"` field pointing to compiled `dist/cli/index.js`.
-
-### 5. Data Structure
-
-```
-~/.ray/
-  config.json          # API keys, preferences, email settings
-  data/
-    finance.db         # All financial data (encrypted SQLite)
-```
-
-Nothing else. One config file, one database. Portable, backupable, inspectable.
-
----
-
-## CLI Commands — Detailed
-
-### `ray` (interactive chat)
-
-Opens an interactive session with the AI financial advisor. Same Claude agent + tool use as the Telegram bot, but in the terminal.
-
-```
-$ ray
-
-Ray 🐟 — Your AI financial advisor
-Type 'quit' to exit. All data is local.
-
-You: How much did we spend on food this month?
-
-Ray: You've spent $310 on food this month — $142 on groceries and $168 on
-restaurants/coffee. That's 34% of your $900 budget with 23 days left.
-You're on pace to hit about $425, well under budget.
-
-You: What's our net worth?
-
-Ray: $508,629 — up $247 from yesterday.
-Home equity: $450K | Investments: $83K | Cash: $2,600
-Credit card debt: $29,036 (your biggest drag — getting paid down at $535 biweekly)
-
-You: quit
-```
-
-### `ray status`
-
-Quick dashboard, no AI call needed. Pure DB queries.
-
-```
-$ ray status
-
-  Free to Spend     $26.31    Next paycheck in 5 days
-  Bills Account     $2,955
-  Savings           $760
-  Credit Card       -$29,036
-
-  Net Worth         $508,629  +$247 yesterday
-
-  Score             72/100    🍳 3d no restaurants
-
-  Budgets
-  ● Food            $310 / $900     34%
-  ● Shopping        $546 / $500     OVER
-  ● Entertainment   $80 / $565      14%
-```
-
-### `ray sync`
-
-```
-$ ray sync
-
-Syncing Bank of America...
-  Accounts: 4 updated
-  Transactions: +23 new, ~2 modified
-  Auto-recategorized: 3 transactions
-
-Net worth: $508,629 (+$247)
-Score (yesterday): 72/100
-```
-
-### `ray forecast`
-
-```
-$ ray forecast
-
-Bills Account Forecast — $2,955 available
-
-Mar 13 💵  $3,906   Paycheck +$5,016, Mortgage -$2,647, CC auto-pay -$535
-Mar 20     $2,536   Honda -$586, Edison -$206, subs
-Mar 26     $1,759   ← lowest point (above $1,500 buffer ✅)
-Mar 27 💵  $9,740   Paycheck +$5,016, Rent income +$3,500, CC auto-pay -$535
-Mar 31     $4,350   Rent -$4,300
-
-Surplus: $3,850 above $500 buffer
-```
-
-### `ray digest`
-
-Sends the daily email digest immediately. Same minimal format:
-1. Free to Spend balance + paycheck countdown
-2. Yesterday's spending
-3. Leakage warning (if any)
-4. One context line
-5. Net worth
-
----
-
-## File Changes
-
-### Delete
-- `src/telegram/bot.ts`
-
-### Rewrite
-- `src/index.ts` → CLI entry point with commander
-- `src/config.ts` → Read from `~/.ray/config.json` instead of `.env`
-- `src/server.ts` → Minimal, only runs temporarily during `ray link`
-
-### Add
-- `src/cli/index.ts` — Main CLI router (commander)
-- `src/cli/chat.ts` — Interactive AI chat session (replaces Telegram)
-- `src/cli/setup.ts` — First-run wizard (prompts for API keys, runs Plaid Link)
-- `src/cli/status.ts` — Quick dashboard
-- `src/cli/commands.ts` — All subcommands (sync, forecast, budgets, etc.)
-- `src/emails/daily-digest.ts` — Port minimal digest from personal ray
-- `src/forecast/index.ts` — Port & generalize checking account forecast
-
-### Keep As-Is
-- `src/plaid/*` — Plaid client, sync, link (already clean)
-- `src/db/*` — Database connection, schema, encryption, helpers
-- `src/ai/*` — Agent, tools, system prompt, memory, audit
-- `src/queries/*` — All financial queries
-- `src/scoring/*` — Daily scoring + achievements
-- `src/alerts/*` — Alert generation
-- `src/daily-sync.ts` — Daily sync orchestrator
-- `src/public/link.html` — Plaid Link web page
-
----
-
-## Daily Digest Email (Minimal)
-
-Ported from personal ray. Five sections max:
-
-1. **Free to Spend balance** — the one number that matters. Paycheck countdown.
-2. **Yesterday's spending** — amount + merchant names. Or "Nothing spent."
-3. **Leakage** — only if transfers detected between accounts. Hidden when clean.
-4. **One context line** — rotating factual reminder (next auto-pay, milestone countdown, etc.)
-5. **Net worth** — one line at the bottom.
-
-Subject: `Daily Finance Update`
-
-Users configure digest in setup: Resend API key + recipient emails. Optional — Ray works fine without email.
-
----
-
-## Scoring System
-
-Already built in `scoring/index.ts`. Daily score 0-100:
-
-- Base: 50
-- No restaurants: +15
-- No shopping: +15  
-- Food under daily pace: +10
-- Total discretionary under $50: +10
-- Zero-spend day: +25
-
-Streaks tracked: no-restaurant, no-shopping, all-budgets-on-pace.
-
-14 achievements: Kitchen Hero, Home Chef, Zero Hero, Monk Mode, Debt Crusher, Half Millionaire, etc.
-
----
-
-## Security & Privacy
-
-- **All financial data stored locally** in `~/.ray/data/finance.db`
-- **Database encrypted** with AES-256 via `better-sqlite3-multiple-ciphers`
-- **Plaid access tokens encrypted at rest** with separate key
-- **Outbound API calls only:**
-  - Plaid (bank sync) — required
-  - Anthropic (AI chat) — required for `ray` chat, not for `ray status/sync/forecast`
-  - Resend (email digest) — optional
-- **No telemetry, no analytics, no phoning home**
-- **Open source** — inspect every line
-
----
-
-## README Structure
-
-1. **Hero** — One-liner + demo GIF
-2. **What Ray Does** — Feature list with terminal screenshots
-3. **Quick Start** — `npx ray-finance setup`
-4. **Commands** — Reference for all CLI commands
-5. **Daily Digest** — Screenshot of the email + setup instructions
-6. **How It Works** — Architecture diagram (Plaid → SQLite → CLI/Email)
-7. **Security** — What data goes where, encryption details
-8. **Configuration** — All config options
-9. **Auto-Recategorization** — How to add custom rules
-10. **Contributing** — How to contribute
-11. **Ray Cloud** — "Don't want to set this up? Join the waitlist."
-
----
-
-## Landing Page
-
-Simple page at `rayfinance.dev` (or similar):
-
-- Demo video (2 min: setup → sync → chat → digest arriving on phone)
-- GitHub link with star count
-- Feature highlights with terminal screenshots
-- "Ray Cloud — coming soon" waitlist (email capture)
-- Security section (local-first, encrypted, open source)
-
----
-
-## Launch Plan
-
-### Week 1: Build
-- [ ] CLI scaffold with commander (index, setup, status, chat)
-- [ ] Port daily digest + forecast from personal ray
-- [ ] `ray setup` wizard (Plaid keys, bank link, Anthropic key, email config)
-- [ ] Scheduled sync (launchd on macOS, cron on Linux)
-- [ ] Polish `ray status` output
-
-### Week 2: Package & Document
-- [ ] Clean up README with demo GIF and screenshots
-- [ ] `npm publish` as global CLI
-- [ ] Landing page with demo video + waitlist
-- [ ] Record 2-minute demo video
-
-### Week 3: Launch
-- [ ] Hacker News — "Show HN: I built an open-source CLI that turns your bank data into a local AI financial advisor"
-- [ ] Reddit — r/selfhosted, r/personalfinance, r/commandline, r/node
-- [ ] Twitter/X — build-in-public thread showing the real product
-- [ ] Product Hunt
-
-### Post-Launch
-- [ ] Monitor waitlist signups for Ray Cloud demand
-- [ ] Community feedback → iterate on CLI
-- [ ] If waitlist > 500: build Ray Cloud (hosted version, email-based, no setup required)
-
----
-
-## Future: Ray Cloud (if demand exists)
-
-Hosted version for non-engineers. No CLI, no Plaid keys, no setup.
-
-- Sign up → connect bank → get daily digest email
-- Reply to email to ask Ray questions
-- $29-49/mo subscription
-- Powered by the same `ray-finance` codebase with a web onboarding layer
-- Clark's Plaid production keys handle all bank connections
-
-**Only build this if the open source launch validates demand via the waitlist.**

package/docker-compose.yml

@@ -1,9 +0,0 @@
-services:
-  ray:
-    build: .
-    env_file: .env
-    volumes:
-      - ./data:/app/data
-    ports:
-      - "3000:3000"
-    restart: unless-stopped

package/site/next-env.d.ts

@@ -1,6 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-/// <reference path="./.next/types/routes.d.ts" />
-
-// NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/site/next.config.ts

@@ -1,7 +0,0 @@
-import type { NextConfig } from "next";
-
-const nextConfig: NextConfig = {
-  output: "export",
-};
-
-export default nextConfig;