ray-finance 0.4.0 → 0.4.1

package/dist/ai/insights.js

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { getNetWorth, getAccountBalances, getDebts, getBudgetStatuses, getGoals, compareSpending, formatMoney, categoryLabel, } from "../queries/index.js";
 import { getLatestScore } from "../scoring/index.js";
+import { getUpcomingBills } from "../db/bills.js";
 const MAX_CHARS = 6000;
 export function computeInsights(db) {
     // Fresh install guard
@@ -138,35 +139,14 @@ function buildGoals(db) {
 }
 function buildUpcoming(db) {
     const parts = [];
-    // Recurring bills due in next 7 days
-    const now = new Date();
-    const todayDay = now.getDate();
-    const daysInMonth = new Date(now.getFullYear(), now.getMonth() + 1, 0).getDate();
-    const endDay = todayDay + 7;
-    let bills = [];
-    if (endDay <= daysInMonth) {
-        bills = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN ? AND ?`).all(todayDay + 1, endDay);
-    }
-    else {
-        // Wraparound: rest of this month + start of next
-        const thisMonthBills = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN ? AND ?`).all(todayDay + 1, daysInMonth);
-        const nextMonthBills = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN 1 AND ?`).all(endDay - daysInMonth);
-        bills = [...thisMonthBills, ...nextMonthBills];
-    }
-    // Also handle bills on day 31 in shorter months
-    if (daysInMonth < 31) {
-        const endOfMonthBills = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month > ? AND day_of_month NOT IN (SELECT day_of_month FROM recurring_bills WHERE day_of_month BETWEEN ? AND ?)`).all(daysInMonth, todayDay + 1, Math.min(endDay, daysInMonth));
-        // These bills fall on the last day of the month
-        if (daysInMonth >= todayDay + 1 && daysInMonth <= endDay) {
-            bills.push(...endOfMonthBills);
-        }
-    }
+    const bills = getUpcomingBills(db, 7);
+    const today = startOfUtcDay(new Date());
     if (bills.length > 0) {
         const billStrs = bills.slice(0, 5).map(b => {
-            const daysUntil = b.day_of_month > todayDay
-                ? b.day_of_month - todayDay
-                : daysInMonth - todayDay + b.day_of_month;
-            return `${b.name} (${formatMoney(b.amount)}) due in ${daysUntil} days`;
+            const daysUntil = Math.round((b.date.getTime() - today.getTime()) / 86400000);
+            const amt = formatMoney(b.amount);
+            const extra = b.note ? ` ${b.note}` : "";
+            return `${b.name} (${amt}${extra}) due in ${daysUntil} days`;
         });
         parts.push(`UPCOMING: ${billStrs.join(", ")}`);
     }
@@ -318,21 +298,12 @@ export function cliBriefing(db) {
         }
     }
     // Upcoming bills
-    const todayDay = now.getDate();
-    const endDay = todayDay + 7;
-    let bills = [];
-    if (endDay <= daysInMonth) {
-        bills = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN ? AND ?`).all(todayDay + 1, endDay);
-    }
-    else {
-        const a = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN ? AND ?`).all(todayDay + 1, daysInMonth);
-        const b = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN 1 AND ?`).all(endDay - daysInMonth);
-        bills = [...a, ...b];
-    }
+    const bills = getUpcomingBills(db, 7);
     if (bills.length > 0) {
         lines.push("");
+        const today = startOfUtcDay(new Date());
         const billStrs = bills.slice(0, 3).map(b => {
-            const daysUntil = b.day_of_month > todayDay ? b.day_of_month - todayDay : daysInMonth - todayDay + b.day_of_month;
+            const daysUntil = Math.round((b.date.getTime() - today.getTime()) / 86400000);
             return chalk.dim(`${b.name} ${fmtMoney(b.amount)}`) + chalk.dim(` in ${daysUntil}d`);
         });
         lines.push(`  ${chalk.dim("upcoming")}  ${billStrs.join(chalk.dim("  ·  "))}`);
@@ -357,6 +328,9 @@ export function cliBriefing(db) {
 function fmtMoney(n) {
     return "$" + Math.abs(n).toLocaleString("en-US", { minimumFractionDigits: 0, maximumFractionDigits: 0 });
 }
+function startOfUtcDay(d) {
+    return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+}
 function miniBar(pct) {
     const width = 8;
     const clamped = Math.max(0, Math.min(100, pct));

package/dist/apple-import.d.ts

@@ -0,0 +1,53 @@
+import type BetterSqlite3 from "libsql";
+type Database = BetterSqlite3.Database;
+export interface AppleImportOptions {
+    csvPath: string;
+    balance?: number;
+    limit?: number;
+    replaceRange?: boolean;
+    dryRun?: boolean;
+}
+export interface AppleImportResult {
+    accountId: string;
+    accountCreated: boolean;
+    rowsParsed: number;
+    rowsInserted: number;
+    rowsSkipped: number;
+    rowsDeleted: number;
+    warnings: string[];
+    dateRange: {
+        first: string;
+        last: string;
+    } | null;
+    balance: number | null;
+}
+interface ParsedRow {
+    transactionDate: string;
+    description: string;
+    merchant: string;
+    category: string;
+    type: string;
+    amount: number;
+}
+/** Parse RFC 4180 CSV: handles quoted fields, embedded commas, and escaped quotes ("") */
+export declare function parseCsv(text: string): string[][];
+/** Parse CSV text. Returns parsed rows + warnings for malformed rows. Throws on bad header. */
+export declare function parseAppleCsv(text: string): {
+    rows: ParsedRow[];
+    warnings: string[];
+    replaceWindow: {
+        first: string;
+        last: string;
+    } | null;
+};
+/** True if the Apple Card account row already exists in the DB */
+export declare function appleAccountExists(db: Database): boolean;
+/** Returns the current balance of the Apple Card account, or null if it doesn't exist */
+export declare function getAppleAccountBalance(db: Database): number | null;
+/** Returns the current credit limit of the Apple Card account, or null if unset */
+export declare function getAppleAccountLimit(db: Database): number | null;
+/** Count of existing Apple Card rows within a date range (for --replace-range preview) */
+export declare function countAppleRowsInRange(db: Database, first: string, last: string): number;
+/** Run the import end-to-end. Returns a result struct for the CLI layer to format. */
+export declare function runAppleImport(db: Database, opts: AppleImportOptions): AppleImportResult;
+export {};

package/dist/apple-import.js

@@ -0,0 +1,372 @@
+import { createHash } from "crypto";
+import { readFileSync } from "fs";
+const INSTITUTION_ID = "manual-apple";
+const INSTITUTION_NAME = "Apple";
+const ACCOUNT_ID = "manual-apple-card";
+const ACCOUNT_NAME = "Apple Card";
+const EXPECTED_HEADER = [
+    "Transaction Date",
+    "Clearing Date",
+    "Description",
+    "Merchant",
+    "Category",
+    "Type",
+    "Amount (USD)",
+    "Purchased By",
+];
+// Apple exports Title Case categories; Ray's scoring and spending queries expect
+// Plaid UPPERCASE_SNAKE_CASE codes. Mapping here so Apple transactions participate
+// in restaurant/shopping counts, budget checks, and spending totals.
+const CATEGORY_MAP = {
+    Restaurants: { category: "FOOD_AND_DRINK", subcategory: "FOOD_AND_DRINK_RESTAURANT" },
+    Grocery: { category: "FOOD_AND_DRINK", subcategory: "FOOD_AND_DRINK_GROCERIES" },
+    Alcohol: { category: "FOOD_AND_DRINK", subcategory: "FOOD_AND_DRINK_ALCOHOL_AND_BARS" },
+    Shopping: { category: "GENERAL_MERCHANDISE", subcategory: null },
+    Gas: { category: "TRANSPORTATION", subcategory: "TRANSPORTATION_GAS" },
+    Transportation: { category: "TRANSPORTATION", subcategory: null },
+    Tolls: { category: "TRANSPORTATION", subcategory: "TRANSPORTATION_TOLLS" },
+    Airlines: { category: "TRAVEL", subcategory: "TRAVEL_FLIGHTS" },
+    Hotels: { category: "TRAVEL", subcategory: "TRAVEL_LODGING" },
+    Entertainment: { category: "ENTERTAINMENT", subcategory: null },
+    Medical: { category: "MEDICAL", subcategory: null },
+    Utilities: { category: "RENT_AND_UTILITIES", subcategory: null },
+    "Govt-services-parking": { category: "GOVERNMENT_AND_NON_PROFIT", subcategory: null },
+    // Payment (negative): card payment from your bank. Mapped to TRANSFER_IN
+    // because Ray's income queries (getIncome, getCashFlow*, compareSpending)
+    // exclude only TRANSFER_IN from `amount < 0`-as-income — LOAN_PAYMENTS would
+    // be counted as income and inflate cash-flow numbers. The corresponding
+    // outflow on the bank account will appear as TRANSFER_OUT via Plaid.
+    Payment: { category: "TRANSFER_IN", subcategory: null },
+    // Installment (positive): Apple Card monthly financing charge (e.g., iPhone).
+    // Amortization of a prior purchase, not new spending — LOAN_PAYMENTS keeps it
+    // out of total-spend aggregation.
+    Installment: { category: "LOAN_PAYMENTS", subcategory: null },
+    // Credit (negative): a refund. Without mapping, queries/index.ts would count
+    // it as income. TRANSFER_IN excludes it from income totals.
+    Credit: { category: "TRANSFER_IN", subcategory: null },
+    Other: { category: null, subcategory: null },
+};
+const TYPE_LABELS = {
+    Payment: "transfer",
+    Credit: "refund",
+    Installment: "installment",
+};
+/** Parse RFC 4180 CSV: handles quoted fields, embedded commas, and escaped quotes ("") */
+export function parseCsv(text) {
+    const rows = [];
+    let row = [];
+    let field = "";
+    let inQuotes = false;
+    let i = 0;
+    // Strip BOM if present
+    if (text.charCodeAt(0) === 0xfeff)
+        i = 1;
+    while (i < text.length) {
+        const c = text[i];
+        if (inQuotes) {
+            if (c === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i += 2;
+                    continue;
+                }
+                inQuotes = false;
+                i++;
+                continue;
+            }
+            field += c;
+            i++;
+            continue;
+        }
+        if (c === '"') {
+            inQuotes = true;
+            i++;
+            continue;
+        }
+        if (c === ",") {
+            row.push(field);
+            field = "";
+            i++;
+            continue;
+        }
+        if (c === "\r") {
+            i++;
+            continue;
+        }
+        if (c === "\n") {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = "";
+            i++;
+            continue;
+        }
+        field += c;
+        i++;
+    }
+    // Final field / row (no trailing newline)
+    if (field.length > 0 || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows;
+}
+function parseDate(mdy) {
+    const m = mdy.match(/^(\d{2})\/(\d{2})\/(\d{4})$/);
+    if (!m)
+        return null;
+    return `${m[3]}-${m[1]}-${m[2]}`;
+}
+function parseAmount(s) {
+    const n = parseFloat(s);
+    return isNaN(n) ? null : n;
+}
+function transactionId(date, amount, merchant, occurrence) {
+    const key = `${date}|${amount}|${merchant}|${occurrence}`;
+    return "apple-" + createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+/**
+ * Assigns a stable occurrence index to rows sharing the same (date, amount, merchant).
+ * Without this, genuinely separate same-day same-merchant same-amount transactions
+ * (e.g. two $2.40 subway swipes) would collapse into one via hash collision.
+ *
+ * Stability requirement: the same CSV exported twice must produce the same indices
+ * so re-imports stay idempotent. We sort rows by every field before numbering so
+ * the order doesn't depend on Apple's export order.
+ */
+function assignOccurrenceIndices(rows) {
+    const sorted = [...rows].sort((a, b) => {
+        if (a.transactionDate !== b.transactionDate)
+            return a.transactionDate < b.transactionDate ? -1 : 1;
+        if (a.amount !== b.amount)
+            return a.amount - b.amount;
+        if (a.merchant !== b.merchant)
+            return a.merchant < b.merchant ? -1 : 1;
+        if (a.description !== b.description)
+            return a.description < b.description ? -1 : 1;
+        if (a.category !== b.category)
+            return a.category < b.category ? -1 : 1;
+        if (a.type !== b.type)
+            return a.type < b.type ? -1 : 1;
+        return 0;
+    });
+    const counts = {};
+    return sorted.map(r => {
+        const key = `${r.transactionDate}|${r.amount}|${r.merchant}`;
+        const occurrence = counts[key] ?? 0;
+        counts[key] = occurrence + 1;
+        return { ...r, occurrence };
+    });
+}
+function mapCategory(appleCat) {
+    return CATEGORY_MAP[appleCat] ?? { category: null, subcategory: null };
+}
+/** Parse CSV text. Returns parsed rows + warnings for malformed rows. Throws on bad header. */
+export function parseAppleCsv(text) {
+    const raw = parseCsv(text);
+    if (raw.length === 0)
+        throw new Error("CSV file is empty.");
+    const header = raw[0];
+    const headerMismatch = header.length !== EXPECTED_HEADER.length ||
+        EXPECTED_HEADER.some((col, i) => header[i] !== col);
+    if (headerMismatch) {
+        throw new Error(`This doesn't look like an Apple Card CSV export.\n` +
+            `  Expected columns: ${EXPECTED_HEADER.join(", ")}\n` +
+            `  Got:              ${header.join(", ")}\n` +
+            `  Export from https://card.apple.com/ (the web portal, not the Wallet app).`);
+    }
+    const rows = [];
+    const warnings = [];
+    // Every row whose Transaction Date parsed, including rows later skipped for
+    // bad amount/columns. `--replace-range` must delete across the *full* CSV
+    // window — narrowing to surviving rows would leave stale rows at the edges
+    // when a boundary row has a bad amount.
+    const allParsedDates = [];
+    for (let i = 1; i < raw.length; i++) {
+        const r = raw[i];
+        if (r.length === 1 && r[0] === "")
+            continue;
+        // Parse date first — recorded in allParsedDates regardless of later
+        // column/amount failures, so --replace-range covers the full CSV window
+        // even when a boundary row has too few columns.
+        const date = r.length >= 1 ? parseDate(r[0]) : null;
+        if (date)
+            allParsedDates.push(date);
+        if (r.length < EXPECTED_HEADER.length) {
+            warnings.push(`Row ${i + 1}: expected ${EXPECTED_HEADER.length} columns, got ${r.length} — skipped`);
+            continue;
+        }
+        if (!date) {
+            warnings.push(`Row ${i + 1}: unparseable Transaction Date "${r[0]}" — skipped`);
+            continue;
+        }
+        const amount = parseAmount(r[6]);
+        if (amount === null) {
+            warnings.push(`Row ${i + 1}: unparseable Amount "${r[6]}" — skipped`);
+            continue;
+        }
+        rows.push({
+            transactionDate: date,
+            description: r[2],
+            merchant: r[3],
+            category: r[4],
+            type: r[5],
+            amount,
+        });
+    }
+    let replaceWindow = null;
+    if (allParsedDates.length > 0) {
+        const sorted = [...allParsedDates].sort();
+        replaceWindow = { first: sorted[0], last: sorted[sorted.length - 1] };
+    }
+    return { rows, warnings, replaceWindow };
+}
+/** True if the Apple Card account row already exists in the DB */
+export function appleAccountExists(db) {
+    return Boolean(db.prepare(`SELECT 1 FROM accounts WHERE account_id = ?`).get(ACCOUNT_ID));
+}
+/** Returns the current balance of the Apple Card account, or null if it doesn't exist */
+export function getAppleAccountBalance(db) {
+    const r = db.prepare(`SELECT current_balance FROM accounts WHERE account_id = ?`).get(ACCOUNT_ID);
+    return r?.current_balance ?? null;
+}
+/** Returns the current credit limit of the Apple Card account, or null if unset */
+export function getAppleAccountLimit(db) {
+    const r = db.prepare(`SELECT balance_limit FROM accounts WHERE account_id = ?`).get(ACCOUNT_ID);
+    return r?.balance_limit ?? null;
+}
+/** Count of existing Apple Card rows within a date range (for --replace-range preview) */
+export function countAppleRowsInRange(db, first, last) {
+    const r = db
+        .prepare(`SELECT COUNT(*) as n FROM transactions WHERE account_id = ? AND date BETWEEN ? AND ?`)
+        .get(ACCOUNT_ID, first, last);
+    return r.n;
+}
+/** Run the import end-to-end. Returns a result struct for the CLI layer to format. */
+export function runAppleImport(db, opts) {
+    const text = readFileSync(opts.csvPath, "utf-8");
+    const { rows, warnings, replaceWindow } = parseAppleCsv(text);
+    if (rows.length === 0) {
+        return {
+            accountId: ACCOUNT_ID,
+            accountCreated: false,
+            rowsParsed: 0,
+            rowsInserted: 0,
+            rowsSkipped: 0,
+            rowsDeleted: 0,
+            warnings,
+            dateRange: null,
+            balance: null,
+        };
+    }
+    const dates = rows.map(r => r.transactionDate).sort();
+    const first = dates[0];
+    const last = dates[dates.length - 1];
+    const replaceFirst = replaceWindow?.first ?? first;
+    const replaceLast = replaceWindow?.last ?? last;
+    if (opts.dryRun) {
+        const rowsDeletedPreview = opts.replaceRange ? countAppleRowsInRange(db, replaceFirst, replaceLast) : 0;
+        // With --replace-range, every CSV row is a fresh insert (the prior rows are
+        // deleted first). Without it, count which transaction_ids already exist so
+        // the user sees a real would-insert vs would-skip breakdown — the whole
+        // point of --dry-run.
+        let wouldInsert = rows.length;
+        let wouldSkip = 0;
+        if (!opts.replaceRange) {
+            const exists = db.prepare(`SELECT 1 FROM transactions WHERE transaction_id = ?`);
+            const indexed = assignOccurrenceIndices(rows);
+            wouldInsert = 0;
+            for (const row of indexed) {
+                const id = transactionId(row.transactionDate, row.amount, row.merchant, row.occurrence);
+                if (exists.get(id))
+                    wouldSkip++;
+                else
+                    wouldInsert++;
+            }
+        }
+        return {
+            accountId: ACCOUNT_ID,
+            accountCreated: !appleAccountExists(db),
+            rowsParsed: rows.length,
+            rowsInserted: wouldInsert,
+            rowsSkipped: wouldSkip,
+            rowsDeleted: rowsDeletedPreview,
+            warnings,
+            dateRange: { first, last },
+            balance: opts.balance ?? getAppleAccountBalance(db),
+        };
+    }
+    const accountCreated = !appleAccountExists(db);
+    let rowsDeleted = 0;
+    let rowsInserted = 0;
+    let rowsSkipped = 0;
+    const insertInst = db.prepare(`INSERT INTO institutions (item_id, access_token, name, products)
+     VALUES (?, 'manual', ?, '[]')
+     ON CONFLICT(item_id) DO NOTHING`);
+    const insertAcc = db.prepare(`INSERT INTO accounts (account_id, item_id, name, type, subtype, currency, current_balance, balance_limit, updated_at)
+     VALUES (?, ?, ?, 'credit', 'credit card', 'USD', ?, ?, datetime('now'))
+     ON CONFLICT(account_id) DO UPDATE SET
+       current_balance = COALESCE(excluded.current_balance, current_balance),
+       balance_limit   = COALESCE(excluded.balance_limit, balance_limit),
+       updated_at      = datetime('now')`);
+    // Derive available_balance = limit - current_balance after the upsert resolves
+    // both fields (so re-runs that omit one of --balance/--limit still produce a
+    // correct value using the prior stored side). Without this, ai/insights.ts
+    // skips the card from utilization (it requires available_balance IS NOT NULL).
+    const updateAvailable = db.prepare(`UPDATE accounts
+     SET available_balance = balance_limit - current_balance
+     WHERE account_id = ?
+       AND balance_limit IS NOT NULL
+       AND current_balance IS NOT NULL`);
+    // Mirror the resolved balance into the liabilities table. getDebts() uses
+    // liabilities as the authoritative source (with rate/min payment/due date)
+    // for any account_id it covers, and falls through to accounts only for
+    // account_ids not in liabilities. Without this upsert, Apple Card debt would
+    // appear only in the fallback path without rate/min-payment metadata.
+    // type='credit' matches Plaid's syncLiabilities convention (src/plaid/sync.ts)
+    // — keeps debt-view labels consistent across import sources.
+    const upsertLiability = db.prepare(`INSERT INTO liabilities (account_id, type, current_balance, updated_at)
+     SELECT ?, 'credit', current_balance, datetime('now')
+     FROM accounts WHERE account_id = ? AND current_balance IS NOT NULL
+     ON CONFLICT(account_id, type) DO UPDATE SET
+       current_balance = excluded.current_balance,
+       updated_at      = datetime('now')`);
+    const deleteRange = db.prepare(`DELETE FROM transactions WHERE account_id = ? AND date BETWEEN ? AND ?`);
+    const insertTx = db.prepare(`INSERT OR IGNORE INTO transactions
+       (transaction_id, account_id, amount, date, name, merchant_name, category, subcategory,
+        pending, iso_currency_code, payment_channel, label, note)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, 'USD', NULL, ?, NULL)`);
+    const work = db.transaction(() => {
+        insertInst.run(INSTITUTION_ID, INSTITUTION_NAME);
+        insertAcc.run(ACCOUNT_ID, INSTITUTION_ID, ACCOUNT_NAME, opts.balance ?? null, opts.limit ?? null);
+        updateAvailable.run(ACCOUNT_ID);
+        upsertLiability.run(ACCOUNT_ID, ACCOUNT_ID);
+        if (opts.replaceRange) {
+            const info = deleteRange.run(ACCOUNT_ID, replaceFirst, replaceLast);
+            rowsDeleted = Number(info.changes);
+        }
+        const indexed = assignOccurrenceIndices(rows);
+        for (const row of indexed) {
+            const mapping = mapCategory(row.category);
+            const id = transactionId(row.transactionDate, row.amount, row.merchant, row.occurrence);
+            const label = TYPE_LABELS[row.type] ?? null;
+            const info = insertTx.run(id, ACCOUNT_ID, row.amount, row.transactionDate, row.description || row.merchant, row.merchant || null, mapping.category, mapping.subcategory, label);
+            if (Number(info.changes) === 1)
+                rowsInserted++;
+            else
+                rowsSkipped++;
+        }
+    });
+    work();
+    return {
+        accountId: ACCOUNT_ID,
+        accountCreated,
+        rowsParsed: rows.length,
+        rowsInserted,
+        rowsSkipped,
+        rowsDeleted,
+        warnings,
+        dateRange: { first, last },
+        balance: opts.balance ?? getAppleAccountBalance(db),
+    };
+}

package/dist/cli/chat.js

@@ -8,13 +8,51 @@ function rawReadLine(prompt, belowLines) {
         let cursor = 0; // cursor position within buf
         const out = process.stdout;
         const promptLen = stripAnsi(prompt).length;
-        // Redraws the buffer from the prompt onward and repositions the cursor
-        const redraw = () => {
-            out.write("\r" + prompt + buf + "\x1b[K"); // clear to end of line
-            // Move cursor back to the correct position
-            const back = buf.length - cursor;
-            if (back > 0)
-                out.write(`\x1b[${back}D`);
+        const cols = () => process.stdout.columns || 80;
+        // Rows occupied by prompt+text of the given length (accounting for wrap)
+        const calcRows = (len) => {
+            const total = promptLen + len;
+            return Math.max(1, Math.ceil(Math.max(1, total) / cols()));
+        };
+        // (row, col) of the position at offset `len` from the start of the prompt
+        const calcPos = (len) => {
+            const w = cols();
+            const abs = promptLen + len;
+            return { row: Math.floor(abs / w), col: abs % w };
+        };
+        let renderedRows = 1; // rows the prompt+buf occupy on screen
+        let curRow = 0; // current cursor row offset within the prompt area
+        // Full re-render: assumes cursor is at (curRow, *) within the prompt area. Moves
+        // to the top of the prompt, clears to end of screen, rewrites prompt+buf and
+        // belowLines, then positions cursor at `cursor` within buf.
+        const render = () => {
+            if (curRow > 0)
+                out.write(`\x1b[${curRow}A`);
+            out.write("\r");
+            // Clear from here to end of screen — drops all old wrapped rows AND belowLines
+            out.write("\x1b[J");
+            out.write(prompt + buf);
+            const endPos = calcPos(buf.length);
+            let fromRow = endPos.row;
+            let fromCol = endPos.col;
+            if (belowLines.length > 0) {
+                out.write("\n" + belowLines.join("\n"));
+                out.write(`\x1b[${belowLines.length}A`);
+                out.write("\r");
+                fromCol = 0;
+            }
+            const tgt = calcPos(cursor);
+            if (fromRow > tgt.row)
+                out.write(`\x1b[${fromRow - tgt.row}A`);
+            else if (tgt.row > fromRow)
+                out.write(`\x1b[${tgt.row - fromRow}B`);
+            if (tgt.col !== fromCol) {
+                out.write("\r");
+                if (tgt.col > 0)
+                    out.write(`\x1b[${tgt.col}C`);
+            }
+            renderedRows = calcRows(buf.length);
+            curRow = tgt.row;
         };
         // Find the start of the previous word boundary
         const wordLeft = () => {
@@ -34,14 +72,8 @@ function rawReadLine(prompt, belowLines) {
                 p++; // skip trailing spaces
             return p;
         };
-        // Render: prompt on current line, then content below, then move cursor back
-        out.write(prompt);
-        if (belowLines.length > 0) {
-            out.write("\n" + belowLines.join("\n"));
-            // Move cursor back up to the prompt line and to the end of prompt text
-            out.write(`\x1b[${belowLines.length}A`);
-            out.write("\r" + prompt);
-        }
+        // Initial render
+        render();
         process.stdin.setRawMode(true);
         process.stdin.resume();
         process.stdin.setEncoding("utf8");
@@ -57,36 +89,40 @@ function rawReadLine(prompt, belowLines) {
                 if (code === 3 || code === 4) {
                     cleanup();
                     out.write("\n");
-                    resolve("\x03");
+                    resolve({ input: "\x03", rows: renderedRows });
                     return;
                 }
                 // Ctrl+A — beginning of line
                 if (code === 1) {
                     if (cursor > 0) {
-                        out.write(`\x1b[${cursor}D`);
                         cursor = 0;
+                        render();
                     }
                     continue;
                 }
                 // Ctrl+E — end of line
                 if (code === 5) {
                     if (cursor < buf.length) {
-                        out.write(`\x1b[${buf.length - cursor}C`);
                         cursor = buf.length;
+                        render();
                     }
                     continue;
                 }
                 // Ctrl+K — delete from cursor to end of line
                 if (code === 11) {
-                    buf = buf.slice(0, cursor);
-                    out.write("\x1b[K");
+                    if (cursor < buf.length) {
+                        buf = buf.slice(0, cursor);
+                        render();
+                    }
                     continue;
                 }
                 // Ctrl+U — delete from cursor to beginning of line
                 if (code === 21) {
-                    buf = buf.slice(cursor);
-                    cursor = 0;
-                    redraw();
+                    if (cursor > 0) {
+                        buf = buf.slice(cursor);
+                        cursor = 0;
+                        render();
+                    }
                     continue;
                 }
                 // Ctrl+W — delete word backward
@@ -95,21 +131,27 @@ function rawReadLine(prompt, belowLines) {
                         const target = wordLeft();
                         buf = buf.slice(0, target) + buf.slice(cursor);
                         cursor = target;
-                        redraw();
+                        render();
                     }
                     continue;
                 }
                 // Enter
                 if (code === 13) {
                     cleanup();
-                    // Move cursor to end of buf first
-                    if (cursor < buf.length)
-                        out.write(`\x1b[${buf.length - cursor}C`);
+                    // Move cursor to end of buf
+                    const end = calcPos(buf.length);
+                    if (end.row > curRow)
+                        out.write(`\x1b[${end.row - curRow}B`);
+                    else if (curRow > end.row)
+                        out.write(`\x1b[${curRow - end.row}A`);
+                    out.write("\r");
+                    if (end.col > 0)
+                        out.write(`\x1b[${end.col}C`);
                     // Move past the below-content lines, then newline
                     for (let j = 0; j < belowLines.length; j++)
                         out.write("\x1b[1B");
                     out.write("\n");
-                    resolve(buf);
+                    resolve({ input: buf, rows: renderedRows });
                     return;
                 }
                 // Backspace
@@ -117,7 +159,7 @@ function rawReadLine(prompt, belowLines) {
                     if (cursor > 0) {
                         buf = buf.slice(0, cursor - 1) + buf.slice(cursor);
                         cursor--;
-                        redraw();
+                        render();
                     }
                     continue;
                 }
@@ -130,7 +172,7 @@ function rawReadLine(prompt, belowLines) {
                             const target = wordLeft();
                             buf = buf.slice(0, target) + buf.slice(cursor);
                             cursor = target;
-                            redraw();
+                            render();
                         }
                         continue;
                     }
@@ -139,8 +181,8 @@ function rawReadLine(prompt, belowLines) {
                         i++;
                         const target = wordLeft();
                         if (target < cursor) {
-                            out.write(`\x1b[${cursor - target}D`);
                             cursor = target;
+                            render();
                         }
                         continue;
                     }
@@ -148,8 +190,8 @@ function rawReadLine(prompt, belowLines) {
                         i++;
                         const target = wordRight();
                         if (target > cursor) {
-                            out.write(`\x1b[${target - cursor}C`);
                             cursor = target;
+                            render();
                         }
                         continue;
                     }
@@ -165,47 +207,42 @@ function rawReadLine(prompt, belowLines) {
                             const final = chunk[i];
                             // Modifier keys: ;3 = Option, ;5 = Ctrl, ;9 = Cmd (Kitty protocol)
                             const isWordMod = seq === "1;3" || seq === "1;5" || seq === "1;9";
-                            const isCmd = seq === "1;9";
                             if (final === "D") {
                                 if (isWordMod) {
-                                    // Option/Ctrl/Cmd+Left — word backward
                                     const target = wordLeft();
                                     if (target < cursor) {
-                                        out.write(`\x1b[${cursor - target}D`);
                                         cursor = target;
+                                        render();
                                     }
                                 }
                                 else if (cursor > 0) {
                                     cursor--;
-                                    out.write("\x1b[D");
+                                    render();
                                 }
                             }
                             else if (final === "C") {
                                 if (isWordMod) {
-                                    // Option/Ctrl/Cmd+Right — word forward
                                     const target = wordRight();
                                     if (target > cursor) {
-                                        out.write(`\x1b[${target - cursor}C`);
                                         cursor = target;
+                                        render();
                                     }
                                 }
                                 else if (cursor < buf.length) {
                                     cursor++;
-                                    out.write("\x1b[C");
+                                    render();
                                 }
                             }
                             else if (final === "H") {
-                                // Home
                                 if (cursor > 0) {
-                                    out.write(`\x1b[${cursor}D`);
                                     cursor = 0;
+                                    render();
                                 }
                             }
                             else if (final === "F") {
-                                // End
                                 if (cursor < buf.length) {
-                                    out.write(`\x1b[${buf.length - cursor}C`);
                                     cursor = buf.length;
+                                    render();
                                 }
                             }
                             else if (final === "u") {
@@ -220,7 +257,7 @@ function rawReadLine(prompt, belowLines) {
                                     if (cursor > 0) {
                                         buf = buf.slice(cursor);
                                         cursor = 0;
-                                        redraw();
+                                        render();
                                     }
                                 }
                             }
@@ -233,7 +270,7 @@ function rawReadLine(prompt, belowLines) {
                 if (code >= 32) {
                     buf = buf.slice(0, cursor) + chunk[i] + buf.slice(cursor);
                     cursor++;
-                    redraw();
+                    render();
                 }
             }
         };
@@ -385,22 +422,22 @@ export async function startChat() {
         process.stdout.write("\x1b[3A\r");
         // Print top rule, then prompt with bottom rule + footer rendered below
         console.log(rule);
-        const input = await rawReadLine(chalk.dim("❯ "), [rule, footerText]);
+        const { input, rows: promptRows } = await rawReadLine(chalk.dim("❯ "), [rule, footerText]);
         const trimmed = input.trim();
         if (!trimmed) {
-            // Clear the prompt frame (top rule + prompt + bottom rule + footer)
-            process.stdout.write("\x1b[3A\r");
-            for (let i = 0; i < 4; i++)
+            // Clear the prompt frame (prompt + bottom rule + footer); leave top rule
+            process.stdout.write(`\x1b[${promptRows + 2}A\r`);
+            for (let i = 0; i < promptRows + 3; i++)
                 process.stdout.write("\x1b[2K\x1b[1B");
-            process.stdout.write("\x1b[4A\r");
+            process.stdout.write(`\x1b[${promptRows + 3}A\r`);
             continue;
         }
-        // Replace prompt frame with gray-background user message
-        // Move up 4 lines (footer, bottom rule, prompt, top rule) and clear them
-        process.stdout.write("\x1b[4A\r");
-        for (let i = 0; i < 4; i++)
+        // Replace prompt frame (top rule + prompt + bottom rule + footer) with gray-bg user message
+        const frameRows = promptRows + 3;
+        process.stdout.write(`\x1b[${frameRows}A\r`);
+        for (let i = 0; i < frameRows; i++)
             process.stdout.write("\x1b[2K\x1b[1B");
-        process.stdout.write("\x1b[4A\r");
+        process.stdout.write(`\x1b[${frameRows}A\r`);
         // Print user message with gray background, padded to full width
         const msgText = `❯ ${trimmed}`;
         const pad = Math.max(0, cols - msgText.length);

package/dist/cli/commands.js

@@ -7,6 +7,7 @@ import { runDailySync } from "../daily-sync.js";
 import { startLinkServer } from "../server.js";
 import { addManualAccount, getManualAccounts, removeManualAccount, scrapeRedfinEstimate } from "../property.js";
 import { heading, progressBar, formatMoney, formatMoneyColored, dim, formatDuration, formatError, renderLogo, institutionName } from "./format.js";
+import { getUpcomingBills } from "../db/bills.js";
 export async function runSync() {
     const ora = (await import("ora")).default;
     const spinner = ora("Syncing transactions...").start();
@@ -429,20 +430,7 @@ export function showAlerts() {
 }
 export function showBills(days = 7) {
     const db = getDb();
-    const now = new Date();
-    const todayDay = now.getDate();
-    const daysInMonth = new Date(now.getFullYear(), now.getMonth() + 1, 0).getDate();
-    const endDay = todayDay + days;
-    let bills = [];
-    if (endDay <= daysInMonth) {
-        bills = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN ? AND ? ORDER BY day_of_month`).all(todayDay + 1, endDay);
-    }
-    else {
-        // Wraparound into next month
-        const thisMonth = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN ? AND ? ORDER BY day_of_month`).all(todayDay + 1, daysInMonth);
-        const nextMonth = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN 1 AND ? ORDER BY day_of_month`).all(endDay - daysInMonth);
-        bills = [...thisMonth, ...nextMonth];
-    }
+    const bills = getUpcomingBills(db, days);
     if (bills.length === 0) {
         console.log(`\nNo upcoming bills in the next ${days} days.`);
         return;
@@ -451,16 +439,13 @@ export function showBills(days = 7) {
     const maxName = Math.max(...bills.map(b => b.name.length));
     let total = 0;
     for (const b of bills) {
-        // Calculate the actual date for this bill
-        let billDate;
-        if (b.day_of_month > todayDay) {
-            billDate = new Date(now.getFullYear(), now.getMonth(), b.day_of_month);
-        }
-        else {
-            billDate = new Date(now.getFullYear(), now.getMonth() + 1, b.day_of_month);
-        }
-        const dateStr = billDate.toLocaleDateString("en-US", { month: "short", day: "numeric" });
-        console.log(`  ${dim(dateStr.padEnd(8))}${b.name.padEnd(maxName + 2)}${rawFormatMoney(b.amount).padStart(10)}`);
+        const dateStr = b.date.toLocaleDateString("en-US", {
+            month: "short", day: "numeric", timeZone: "UTC",
+        });
+        const amountStr = rawFormatMoney(b.amount);
+        const noteStr = b.note ? dim(` ${b.note}`) : "";
+        const tag = dim(`[${b.source}]`);
+        console.log(`  ${dim(dateStr.padEnd(8))}${b.name.padEnd(maxName + 2)}${amountStr.padStart(10)}${noteStr}  ${tag}`);
         total += b.amount;
     }
     console.log(`\n  ${dim("Total due:".padEnd(maxName + 10))}${chalk.bold(rawFormatMoney(total))}`);

package/dist/db/bills.d.ts

@@ -0,0 +1,22 @@
+import type Database from "libsql";
+export type BillSource = "card" | "recurring" | "manual";
+export type UpcomingBill = {
+    date: Date;
+    name: string;
+    amount: number;
+    source: BillSource;
+    /** Optional secondary amount shown in parens, e.g. minimum payment for credit cards. */
+    note?: string;
+};
+export type PlaidFrequency = "WEEKLY" | "BIWEEKLY" | "SEMI_MONTHLY" | "MONTHLY" | "ANNUALLY" | "UNKNOWN" | string;
+/**
+ * Predict the next occurrence after `lastDate` given Plaid's reported frequency.
+ * Returns null for UNKNOWN/unsupported frequencies.
+ */
+export declare function predictNextBillDate(lastDate: string, frequency: PlaidFrequency): Date | null;
+/**
+ * Collect upcoming outflows from Plaid recurring streams, credit/mortgage/student
+ * liability due dates, and manual recurring_bills. Sorted by date ascending.
+ * Returns bills whose predicted date is between tomorrow and today+`days` inclusive.
+ */
+export declare function getUpcomingBills(db: Database.Database, days: number): UpcomingBill[];

package/dist/db/bills.js

@@ -0,0 +1,134 @@
+/**
+ * Predict the next occurrence after `lastDate` given Plaid's reported frequency.
+ * Returns null for UNKNOWN/unsupported frequencies.
+ */
+export function predictNextBillDate(lastDate, frequency) {
+    const last = new Date(lastDate + "T00:00:00Z");
+    if (isNaN(last.getTime()))
+        return null;
+    switch (frequency) {
+        case "WEEKLY":
+            return addDays(last, 7);
+        case "BIWEEKLY":
+            return addDays(last, 14);
+        case "SEMI_MONTHLY": {
+            // Paychecks/bills on the 1st and 15th of the month.
+            const d = last.getUTCDate();
+            if (d < 15)
+                return new Date(Date.UTC(last.getUTCFullYear(), last.getUTCMonth(), 15));
+            return new Date(Date.UTC(last.getUTCFullYear(), last.getUTCMonth() + 1, 1));
+        }
+        case "MONTHLY":
+            return addMonths(last, 1);
+        case "ANNUALLY":
+            return addMonths(last, 12);
+        default:
+            return null;
+    }
+}
+function addDays(d, n) {
+    return new Date(d.getTime() + n * 86400000);
+}
+/** Add months, clamping to the last day of the target month (Jan 31 + 1mo → Feb 28/29). */
+function addMonths(d, n) {
+    const y = d.getUTCFullYear();
+    const m = d.getUTCMonth() + n;
+    const day = d.getUTCDate();
+    const daysInTarget = new Date(Date.UTC(y, m + 1, 0)).getUTCDate();
+    return new Date(Date.UTC(y, m, Math.min(day, daysInTarget)));
+}
+/**
+ * Collect upcoming outflows from Plaid recurring streams, credit/mortgage/student
+ * liability due dates, and manual recurring_bills. Sorted by date ascending.
+ * Returns bills whose predicted date is between tomorrow and today+`days` inclusive.
+ */
+export function getUpcomingBills(db, days) {
+    const now = new Date();
+    const today = startOfUtcDay(now);
+    const windowStart = addDays(today, 1);
+    const windowEnd = addDays(today, days);
+    const bills = [];
+    // 1. Plaid recurring streams (outflows only)
+    const streams = db.prepare(`SELECT description, merchant_name, frequency, avg_amount, last_amount, last_date
+     FROM recurring
+     WHERE is_active = 1 AND stream_type = 'outflow' AND last_date IS NOT NULL`).all();
+    for (const s of streams) {
+        const next = predictNextBillDate(s.last_date, s.frequency);
+        if (!next)
+            continue;
+        if (next < windowStart || next > windowEnd)
+            continue;
+        const amount = Math.abs(s.last_amount ?? s.avg_amount ?? 0);
+        if (amount === 0)
+            continue;
+        bills.push({
+            date: next,
+            name: s.merchant_name || s.description,
+            amount,
+            source: "recurring",
+        });
+    }
+    // 2. Liabilities with a scheduled due date
+    const liabs = db.prepare(`SELECT l.type, l.current_balance, l.minimum_payment, l.next_payment_due, a.name as account_name
+     FROM liabilities l
+     JOIN accounts a ON a.account_id = l.account_id
+     WHERE l.next_payment_due IS NOT NULL`).all();
+    for (const l of liabs) {
+        const due = new Date(l.next_payment_due + "T00:00:00Z");
+        if (isNaN(due.getTime()))
+            continue;
+        if (due < windowStart || due > windowEnd)
+            continue;
+        if (l.type === "credit") {
+            const stmt = l.current_balance ?? 0;
+            if (stmt <= 0)
+                continue;
+            bills.push({
+                date: due,
+                name: l.account_name,
+                amount: stmt,
+                source: "card",
+                note: l.minimum_payment != null ? `min ${formatShortMoney(l.minimum_payment)}` : undefined,
+            });
+        }
+        else {
+            const min = l.minimum_payment ?? 0;
+            if (min <= 0)
+                continue;
+            bills.push({
+                date: due,
+                name: l.account_name,
+                amount: min,
+                source: "card",
+            });
+        }
+    }
+    // 3. Manual recurring_bills (month/day schedule)
+    const manual = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month IS NOT NULL`).all();
+    for (const m of manual) {
+        const next = nextDayOfMonthDate(today, m.day_of_month);
+        if (next < windowStart || next > windowEnd)
+            continue;
+        bills.push({ date: next, name: m.name, amount: m.amount, source: "manual" });
+    }
+    bills.sort((a, b) => a.date.getTime() - b.date.getTime());
+    return bills;
+}
+function startOfUtcDay(d) {
+    return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+}
+/** Next calendar date matching the given day-of-month, clamping to month length. */
+function nextDayOfMonthDate(today, dayOfMonth) {
+    const y = today.getUTCFullYear();
+    const m = today.getUTCMonth();
+    const daysThisMonth = new Date(Date.UTC(y, m + 1, 0)).getUTCDate();
+    const clampedThisMonth = Math.min(dayOfMonth, daysThisMonth);
+    const candidate = new Date(Date.UTC(y, m, clampedThisMonth));
+    if (candidate > today)
+        return candidate;
+    const daysNextMonth = new Date(Date.UTC(y, m + 2, 0)).getUTCDate();
+    return new Date(Date.UTC(y, m + 1, Math.min(dayOfMonth, daysNextMonth)));
+}
+function formatShortMoney(n) {
+    return `$${Math.round(n).toLocaleString()}`;
+}

package/dist/recategorization.d.ts

@@ -0,0 +1,15 @@
+import type BetterSqlite3 from "libsql";
+type Database = BetterSqlite3.Database;
+export interface RecategorizationResult {
+    rulesEvaluated: number;
+    rulesSkipped: number;
+    transactionsUpdated: number;
+}
+/**
+ * Apply every row in `recategorization_rules` as an UPDATE against
+ * `transactions`. Called from both `runDailySync` and `runImportApple`; owns
+ * its own console output so both callers produce identical per-rule lines
+ * and the grand-total summary. Silent when no rules fire.
+ */
+export declare function applyRecategorizationRules(db: Database): RecategorizationResult;
+export {};

package/dist/recategorization.js

@@ -0,0 +1,46 @@
+// Only known column names are allowed in `match_field` — the value flows into
+// the UPDATE statement via string interpolation (rest of the query is
+// parametrized). Anything else is rejected to prevent SQL injection.
+const ALLOWED_MATCH_FIELDS = ["name", "merchant_name", "category", "subcategory"];
+/**
+ * Apply every row in `recategorization_rules` as an UPDATE against
+ * `transactions`. Called from both `runDailySync` and `runImportApple`; owns
+ * its own console output so both callers produce identical per-rule lines
+ * and the grand-total summary. Silent when no rules fire.
+ */
+export function applyRecategorizationRules(db) {
+    const rules = db.prepare(`SELECT match_field, match_pattern, target_category, target_subcategory, label FROM recategorization_rules`).all();
+    let rulesSkipped = 0;
+    let transactionsUpdated = 0;
+    for (const rule of rules) {
+        if (!ALLOWED_MATCH_FIELDS.includes(rule.match_field)) {
+            console.error(`  Skipping recat rule with invalid match_field: ${rule.match_field}`);
+            rulesSkipped++;
+            continue;
+        }
+        // Guard fires whenever the row isn't "already at target". Both branches
+        // write the full (category, subcategory) pair so a rule never leaves a
+        // stale subcategory attached to a new category (e.g. an "Amazon ->
+        // GENERAL_MERCHANDISE" rule applied to a row tagged
+        // FOOD_AND_DRINK / FOOD_AND_DRINK_GROCERIES). COALESCE is load-bearing on
+        // any nullable field we compare with `!=`: plain `!=` against NULL yields
+        // NULL (falsy in SQLite three-valued logic) and would silently exclude
+        // rows whose category or subcategory is NULL. Apple imports produce such
+        // rows for "Other" and any unmapped Apple category.
+        const result = rule.target_subcategory
+            ? db.prepare(`UPDATE transactions SET category = ?, subcategory = ? WHERE ${rule.match_field} LIKE ? AND (COALESCE(category, '') != ? OR COALESCE(subcategory, '') != ?)`).run(rule.target_category, rule.target_subcategory, rule.match_pattern, rule.target_category, rule.target_subcategory)
+            : db.prepare(`UPDATE transactions SET category = ?, subcategory = NULL WHERE ${rule.match_field} LIKE ? AND (COALESCE(category, '') != ? OR subcategory IS NOT NULL)`).run(rule.target_category, rule.match_pattern, rule.target_category);
+        if (result.changes > 0) {
+            console.log(`  Recategorized ${result.changes} txn(s): ${rule.label || rule.match_pattern}`);
+            transactionsUpdated += Number(result.changes);
+        }
+    }
+    if (transactionsUpdated > 0) {
+        console.log(`  Auto-recategorized ${transactionsUpdated} transaction(s).`);
+    }
+    return {
+        rulesEvaluated: rules.length,
+        rulesSkipped,
+        transactionsUpdated,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ray-finance",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Local-first CLI that turns your bank data into a personal AI financial advisor",
   "type": "module",
   "license": "MIT",