plasalid 0.2.0

package/dist/scanner/pipeline.d.ts

@@ -0,0 +1,32 @@
+export interface ScanFileResult {
+    fileId: string | null;
+    status: "scanned" | "needs_input" | "failed" | "skipped" | "replaced";
+    summary?: string;
+    error?: string;
+    pendingQuestions: number;
+}
+export interface ScanOptions {
+    interactive?: boolean;
+    force?: boolean;
+    onProgress?: (msg: string) => void;
+}
+export declare function scanFile(filePath: string, opts?: ScanOptions): Promise<ScanFileResult>;
+export interface ScanSummary {
+    total: number;
+    scanned: number;
+    replaced: number;
+    skipped: number;
+    needsInput: number;
+    failed: number;
+    details: {
+        name: string;
+        relPath: string;
+        result: ScanFileResult;
+    }[];
+}
+export interface RunScanOptions extends ScanOptions {
+    /** Optional regex (string). Partial, case-insensitive, against the relative path. */
+    regex?: string;
+}
+export declare function compileMatcher(input: string): RegExp;
+export declare function runScan(opts?: RunScanOptions): Promise<ScanSummary>;

package/dist/scanner/pipeline.js

@@ -0,0 +1,137 @@
+import { randomUUID } from "crypto";
+import { getDb } from "../db/connection.js";
+import { runScanAgent } from "../ai/agent.js";
+import { statusSpinner, makePromptUser, makeAgentOnProgress, } from "../cli/ux.js";
+import { readPdf, buildDocumentBlock } from "./pdf.js";
+import { buildScanUserMessage } from "./prompts.js";
+import { scanDataDir } from "./walker.js";
+import { unlockIfNeeded, persistUnlockOutcome } from "./unlock.js";
+// ── DB helpers ──────────────────────────────────────────────────────────────
+function findScannedByHash(db, hash) {
+    return db
+        .prepare(`SELECT id FROM scanned_files WHERE file_hash = ?`)
+        .get(hash) ?? null;
+}
+function deleteScannedFile(db, id) {
+    db.prepare(`DELETE FROM scanned_files WHERE id = ?`).run(id);
+}
+function insertScannedFile(db, args) {
+    const id = `sf:${randomUUID()}`;
+    db.prepare(`INSERT INTO scanned_files (id, path, file_hash, mime, status)
+     VALUES (?, ?, ?, ?, 'pending')`).run(id, args.path, args.hash, args.mime);
+    return id;
+}
+function countPendingQuestions(db, fileId) {
+    const row = db
+        .prepare(`SELECT COUNT(*) as n FROM pending_questions WHERE file_id = ? AND resolved_at IS NULL`)
+        .get(fileId);
+    return row.n;
+}
+function setFileStatus(db, id, status, fields = {}) {
+    db.prepare(`UPDATE scanned_files
+     SET status = ?, scanned_at = datetime('now'), error = ?, raw_text = COALESCE(?, raw_text)
+     WHERE id = ?`).run(status, fields.error ?? null, fields.raw_text ?? null, id);
+}
+// ── Per-file scan ───────────────────────────────────────────────────────────
+export async function scanFile(filePath, opts = {}) {
+    const db = getDb();
+    const file = readPdf(filePath);
+    const existing = findScannedByHash(db, file.hash);
+    if (existing && !opts.force) {
+        return { fileId: existing.id, status: "skipped", pendingQuestions: countPendingQuestions(db, existing.id) };
+    }
+    const wasReplaced = !!existing;
+    if (existing) {
+        deleteScannedFile(db, existing.id);
+    }
+    let unlocked;
+    try {
+        unlocked = await unlockIfNeeded({
+            db,
+            filePath,
+            bytes: file.bytes,
+            interactive: opts.interactive ?? true,
+        });
+    }
+    catch (err) {
+        return { fileId: null, status: "failed", error: err.message, pendingQuestions: 0 };
+    }
+    persistUnlockOutcome(db, filePath, unlocked.outcome);
+    const fileId = insertScannedFile(db, { path: filePath, hash: file.hash, mime: file.mime });
+    const block = buildDocumentBlock(unlocked.decrypted, file.fileName, file.mime);
+    const messages = [
+        {
+            role: "user",
+            content: [
+                block,
+                { type: "text", text: buildScanUserMessage({ fileName: file.fileName }) },
+            ],
+        },
+    ];
+    const spinner = statusSpinner(`Scanning ${file.fileName}...`);
+    let summary = "";
+    try {
+        const text = await runScanAgent({
+            db,
+            initialMessages: messages,
+            prompt: { fileName: file.fileName },
+            agentCtx: {
+                fileId,
+                interactive: opts.interactive ?? true,
+                promptUser: opts.interactive === false ? undefined : makePromptUser(spinner),
+                onComplete: (s) => { summary = s; },
+            },
+            onProgress: makeAgentOnProgress(spinner, file.fileName),
+        });
+        const stillPending = countPendingQuestions(db, fileId);
+        if (stillPending > 0) {
+            setFileStatus(db, fileId, "needs_input", { raw_text: text });
+            spinner.info(`${file.fileName} needs input (${stillPending} pending).`);
+            return { fileId, status: "needs_input", summary: summary || text, pendingQuestions: stillPending };
+        }
+        setFileStatus(db, fileId, "scanned", { raw_text: text });
+        spinner.succeed(`Scanned ${file.fileName}.`);
+        return {
+            fileId,
+            status: wasReplaced ? "replaced" : "scanned",
+            summary: summary || text,
+            pendingQuestions: 0,
+        };
+    }
+    catch (err) {
+        setFileStatus(db, fileId, "failed", { error: err.message });
+        spinner.fail(`${file.fileName} failed: ${err.message}`);
+        return { fileId, status: "failed", error: err.message, pendingQuestions: countPendingQuestions(db, fileId) };
+    }
+}
+export function compileMatcher(input) {
+    return new RegExp(input, "i");
+}
+export async function runScan(opts = {}) {
+    const matcher = opts.regex ? compileMatcher(opts.regex) : null;
+    const files = scanDataDir().filter(f => (matcher ? matcher.test(f.relPath) : true));
+    const summary = {
+        total: files.length,
+        scanned: 0,
+        replaced: 0,
+        skipped: 0,
+        needsInput: 0,
+        failed: 0,
+        details: [],
+    };
+    for (const f of files) {
+        const result = await scanFile(f.path, opts);
+        summary.details.push({ name: f.name, relPath: f.relPath, result });
+        if (result.status === "scanned")
+            summary.scanned++;
+        else if (result.status === "replaced")
+            summary.replaced++;
+        else if (result.status === "skipped")
+            summary.skipped++;
+        else if (result.status === "needs_input")
+            summary.needsInput++;
+        else if (result.status === "failed")
+            summary.failed++;
+    }
+    return summary;
+}

package/dist/scanner/prompts.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The user-message prelude that accompanies the PDF document block. The persona
+ * and rules live in the scan system prompt (src/ai/system-prompt.ts); this
+ * message is a per-file instruction.
+ */
+export declare function buildScanUserMessage(opts: {
+    fileName: string;
+}): string;

package/dist/scanner/prompts.js

@@ -0,0 +1,20 @@
+/**
+ * The user-message prelude that accompanies the PDF document block. The persona
+ * and rules live in the scan system prompt (src/ai/system-prompt.ts); this
+ * message is a per-file instruction.
+ */
+export function buildScanUserMessage(opts) {
+    return [
+        `Please scan the attached document.`,
+        `File: ${opts.fileName}`,
+        ``,
+        `Steps:`,
+        `1. Call list_accounts to see what already exists.`,
+        `2. Infer the primary account type (asset / liability / income / expense) from the document's header, account type field, and transaction patterns.`,
+        `3. If this document references an account that isn't yet in the chart, call create_account once. Mask the account number to the last 4 digits.`,
+        `4. Persist any document-level metadata you find (statement_day, due_day, points_balance, etc.) using update_account_metadata.`,
+        `5. For every transaction in the document, call record_journal_entry with balanced debit/credit lines. Use existing accounts where possible; create expense/income accounts as needed.`,
+        `6. If a row is ambiguous, call ask_user before guessing.`,
+        `7. When you are done, call mark_file_scanned with a short summary.`,
+    ].join("\n");
+}

package/dist/scanner/state-machine.d.ts

@@ -0,0 +1,60 @@
+import type { StoredPassword } from "./password-store.js";
+/**
+ * Pure state machine for the unlock phase of a single file scan. Side effects
+ * (mupdf calls, prompts, DB reads) live in the orchestrator; this module only
+ * encodes the transition logic so it can be exhaustively unit-tested.
+ */
+export declare const MAX_PASSWORD_ATTEMPTS = 3;
+export type UnlockOutcome = {
+    kind: "plaintext";
+} | {
+    kind: "from-store";
+    storedId: string;
+} | {
+    kind: "from-user";
+    password: string;
+};
+export type UnlockState = {
+    kind: "init";
+} | {
+    kind: "trying-stored";
+    candidates: StoredPassword[];
+} | {
+    kind: "awaiting-user";
+    attempt: number;
+} | {
+    kind: "done";
+    decrypted: Buffer;
+    outcome: UnlockOutcome;
+} | {
+    kind: "failed";
+    reason: string;
+};
+export type UnlockEvent = {
+    kind: "INSPECTED_PLAINTEXT";
+    bytes: Buffer;
+} | {
+    kind: "INSPECTED_ENCRYPTED";
+    candidates: StoredPassword[];
+} | {
+    kind: "STORED_UNLOCK_OK";
+    decrypted: Buffer;
+    usedStoredId: string;
+} | {
+    kind: "STORED_UNLOCK_EXHAUSTED";
+} | {
+    kind: "USER_CANCELLED";
+} | {
+    kind: "UNLOCK_OK";
+    decrypted: Buffer;
+    password: string;
+} | {
+    kind: "UNLOCK_FAIL";
+};
+export declare function isTerminal(state: UnlockState): boolean;
+/**
+ * Pure transition. Throws if the event doesn't make sense for the current state;
+ * the orchestrator never produces such combinations, so reaching the throw is a
+ * programmer error worth surfacing loudly.
+ */
+export declare function transition(state: UnlockState, event: UnlockEvent): UnlockState;

package/dist/scanner/state-machine.js

@@ -0,0 +1,64 @@
+/**
+ * Pure state machine for the unlock phase of a single file scan. Side effects
+ * (mupdf calls, prompts, DB reads) live in the orchestrator; this module only
+ * encodes the transition logic so it can be exhaustively unit-tested.
+ */
+export const MAX_PASSWORD_ATTEMPTS = 3;
+export function isTerminal(state) {
+    return state.kind === "done" || state.kind === "failed";
+}
+/**
+ * Pure transition. Throws if the event doesn't make sense for the current state;
+ * the orchestrator never produces such combinations, so reaching the throw is a
+ * programmer error worth surfacing loudly.
+ */
+export function transition(state, event) {
+    switch (state.kind) {
+        case "init":
+            if (event.kind === "INSPECTED_PLAINTEXT") {
+                return { kind: "done", decrypted: event.bytes, outcome: { kind: "plaintext" } };
+            }
+            if (event.kind === "INSPECTED_ENCRYPTED") {
+                return { kind: "trying-stored", candidates: event.candidates };
+            }
+            break;
+        case "trying-stored":
+            if (event.kind === "STORED_UNLOCK_OK") {
+                return {
+                    kind: "done",
+                    decrypted: event.decrypted,
+                    outcome: { kind: "from-store", storedId: event.usedStoredId },
+                };
+            }
+            if (event.kind === "STORED_UNLOCK_EXHAUSTED") {
+                return { kind: "awaiting-user", attempt: 1 };
+            }
+            break;
+        case "awaiting-user":
+            if (event.kind === "USER_CANCELLED") {
+                return { kind: "failed", reason: "password required" };
+            }
+            if (event.kind === "UNLOCK_OK") {
+                return {
+                    kind: "done",
+                    decrypted: event.decrypted,
+                    outcome: { kind: "from-user", password: event.password },
+                };
+            }
+            if (event.kind === "UNLOCK_FAIL") {
+                if (state.attempt >= MAX_PASSWORD_ATTEMPTS) {
+                    return {
+                        kind: "failed",
+                        reason: `incorrect password after ${MAX_PASSWORD_ATTEMPTS} attempts`,
+                    };
+                }
+                return { kind: "awaiting-user", attempt: state.attempt + 1 };
+            }
+            break;
+        case "done":
+        case "failed":
+            // Terminal — no further transitions.
+            break;
+    }
+    throw new Error(`Invalid unlock transition: ${state.kind} + ${event.kind}`);
+}

package/dist/scanner/unlock.d.ts

@@ -0,0 +1,24 @@
+import type Database from "libsql";
+import { type UnlockOutcome } from "./state-machine.js";
+export interface UnlockCtx {
+    db: Database.Database;
+    filePath: string;
+    bytes: Buffer;
+    interactive: boolean;
+}
+/**
+ * Drive the pure unlock state machine to a terminal state, returning the
+ * decrypted bytes and the outcome (plaintext / from-store / from-user) so the
+ * caller can persist passwords or record stored-key usage.
+ */
+export declare function unlockIfNeeded(ctx: UnlockCtx): Promise<{
+    decrypted: Buffer;
+    outcome: UnlockOutcome;
+}>;
+/**
+ * After a successful unlock, persist the outcome:
+ *   from-store  → bump usage counter on the stored password
+ *   from-user   → save the new password under a filename-pattern key
+ *   plaintext   → no-op
+ */
+export declare function persistUnlockOutcome(db: Database.Database, filePath: string, outcome: UnlockOutcome): void;

package/dist/scanner/unlock.js

@@ -0,0 +1,122 @@
+import inquirer from "inquirer";
+import { basename } from "path";
+import { config } from "../config.js";
+import { statusSpinner } from "../cli/ux.js";
+import { findCandidates, savePassword, recordUse, suggestPattern, } from "./password-store.js";
+import { transition, isTerminal, } from "./state-machine.js";
+import { isEncrypted, unlock } from "./pdf-unlock.js";
+/**
+ * Drive the pure unlock state machine to a terminal state, returning the
+ * decrypted bytes and the outcome (plaintext / from-store / from-user) so the
+ * caller can persist passwords or record stored-key usage.
+ */
+export async function unlockIfNeeded(ctx) {
+    let state = { kind: "init" };
+    while (!isTerminal(state)) {
+        const event = await stepUnlock(state, ctx);
+        state = transition(state, event);
+    }
+    if (state.kind === "failed") {
+        throw new Error(state.reason);
+    }
+    if (state.kind !== "done") {
+        throw new Error(`unlock loop exited in non-terminal state ${state.kind}`);
+    }
+    return { decrypted: state.decrypted, outcome: state.outcome };
+}
+async function stepUnlock(state, ctx) {
+    switch (state.kind) {
+        case "init": {
+            const spinner = statusSpinner(`Inspecting ${basename(ctx.filePath)}...`);
+            try {
+                const encrypted = await isEncrypted(ctx.bytes);
+                if (!encrypted) {
+                    spinner.succeed(`${basename(ctx.filePath)} is not encrypted.`);
+                    return { kind: "INSPECTED_PLAINTEXT", bytes: ctx.bytes };
+                }
+                const candidates = findCandidates(ctx.db, ctx.filePath, config.dbEncryptionKey);
+                spinner.info(`${basename(ctx.filePath)} is encrypted (${candidates.length} saved password${candidates.length === 1 ? "" : "s"} match).`);
+                return { kind: "INSPECTED_ENCRYPTED", candidates };
+            }
+            catch (err) {
+                spinner.fail("Inspection failed.");
+                throw err;
+            }
+        }
+        case "trying-stored":
+            return await tryStoredPasswords(ctx.bytes, state.candidates);
+        case "awaiting-user": {
+            if (!ctx.interactive) {
+                return { kind: "USER_CANCELLED" };
+            }
+            const password = await promptForPassword(basename(ctx.filePath), state.attempt);
+            if (!password) {
+                return { kind: "USER_CANCELLED" };
+            }
+            const spinner = statusSpinner("Decrypting...");
+            const result = await unlock(ctx.bytes, password);
+            if (result.ok && result.decrypted) {
+                spinner.succeed("Decrypted.");
+                return { kind: "UNLOCK_OK", decrypted: result.decrypted, password };
+            }
+            spinner.fail(`Incorrect password (attempt ${state.attempt}/3).`);
+            return { kind: "UNLOCK_FAIL" };
+        }
+        default:
+            throw new Error(`stepUnlock called with terminal state ${state.kind}`);
+    }
+}
+async function tryStoredPasswords(bytes, candidates) {
+    if (candidates.length === 0) {
+        return { kind: "STORED_UNLOCK_EXHAUSTED" };
+    }
+    const spinner = statusSpinner(`Trying saved password 1/${candidates.length}...`);
+    for (let i = 0; i < candidates.length; i++) {
+        const cand = candidates[i];
+        spinner.text = `Trying saved password ${i + 1}/${candidates.length} (pattern ${cand.pattern})`;
+        const result = await unlock(bytes, cand.password);
+        if (result.ok && result.decrypted) {
+            spinner.succeed(`Unlocked with saved password (pattern ${cand.pattern}).`);
+            return {
+                kind: "STORED_UNLOCK_OK",
+                decrypted: result.decrypted,
+                usedStoredId: cand.id,
+            };
+        }
+    }
+    spinner.info("No saved password matched. Asking the user.");
+    return { kind: "STORED_UNLOCK_EXHAUSTED" };
+}
+async function promptForPassword(fileName, attempt) {
+    const message = attempt === 1
+        ? `This PDF is encrypted. Password for ${fileName}:`
+        : `Password for ${fileName} (attempt ${attempt}/3):`;
+    const { password } = await inquirer.prompt([
+        { type: "password", name: "password", mask: "*", message },
+    ]);
+    return String(password ?? "").trim();
+}
+/**
+ * After a successful unlock, persist the outcome:
+ *   from-store  → bump usage counter on the stored password
+ *   from-user   → save the new password under a filename-pattern key
+ *   plaintext   → no-op
+ */
+export function persistUnlockOutcome(db, filePath, outcome) {
+    if (outcome.kind === "from-store") {
+        recordUse(db, outcome.storedId);
+        return;
+    }
+    if (outcome.kind === "from-user") {
+        const pattern = suggestPattern(filePath);
+        const spinner = statusSpinner(`Saving password for pattern ${pattern}...`);
+        try {
+            savePassword(db, pattern, outcome.password, config.dbEncryptionKey);
+            spinner.succeed(`Saved password for pattern ${pattern} in secure vault.`);
+        }
+        catch (err) {
+            spinner.fail(`Could not save password: ${err.message}`);
+            throw err;
+        }
+    }
+}

package/dist/scanner/walker.d.ts

@@ -0,0 +1,8 @@
+export interface ScannedFile {
+    path: string;
+    name: string;
+    /** Path relative to the data dir, forward-slashed. */
+    relPath: string;
+}
+/** Walk the data directory recursively and return every supported file found. */
+export declare function scanDataDir(): ScannedFile[];

package/dist/scanner/walker.js

@@ -0,0 +1,42 @@
+import { readdirSync, statSync } from "fs";
+import { resolve, basename, relative, sep } from "path";
+import { getDataDir } from "../config.js";
+const SUPPORTED_EXTS = new Set([".pdf"]);
+function walk(dir, root, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.startsWith("."))
+            continue;
+        const full = resolve(dir, entry);
+        let s;
+        try {
+            s = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (s.isDirectory()) {
+            walk(full, root, out);
+        }
+        else if (s.isFile()) {
+            const ext = entry.slice(entry.lastIndexOf(".")).toLowerCase();
+            if (!SUPPORTED_EXTS.has(ext))
+                continue;
+            const rel = relative(root, full).split(sep).join("/");
+            out.push({ path: full, name: basename(full), relPath: rel });
+        }
+    }
+}
+/** Walk the data directory recursively and return every supported file found. */
+export function scanDataDir() {
+    const out = [];
+    const root = getDataDir();
+    walk(root, root, out);
+    return out;
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "plasalid",
+  "version": "0.2.0",
+  "description": "The local-first data layer for personal finance.",
+  "keywords": [
+    "finance",
+    "personal-finance",
+    "aggregator",
+    "parser",
+    "cli",
+    "ai",
+    "local"
+  ],
+  "homepage": "https://github.com/phureewat29/plasalid#readme",
+  "bugs": {
+    "url": "https://github.com/phureewat29/plasalid/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phureewat29/plasalid.git"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Phureewat A",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "plasalid": "dist/cli/index.js"
+  },
+  "directories": {
+    "example": "examples"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsx src/cli/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0",
+    "chalk": "^5.3.0",
+    "commander": "^13.0.0",
+    "dotenv": "^16.4.0",
+    "ink": "^5.2.1",
+    "ink-spinner": "^5.0.0",
+    "inquirer": "^12.0.0",
+    "libsql": "^0.5.0",
+    "mupdf": "^1.27.0",
+    "openai": "^6.37.0",
+    "ora": "^8.0.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.3.28",
+    "tsx": "^4.7.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}