@fuzzle/opencode-accountant 0.0.12 → 0.0.13-next.1

package/README.md

@@ -93,10 +93,10 @@ The `classify-statements` tool classifies bank statement CSV files by provider a
 
 ```yaml
 paths:
-  import: statements/import
-  pending: doc/agent/todo/import
-  done: doc/agent/done/import
-  unrecognized: statements/import/unrecognized
+  import: import/incoming
+  pending: import/pending
+  done: import/done
+  unrecognized: import/unrecognized
   rules: ledger/rules
 
 providers:
@@ -176,35 +176,31 @@ providers:
 your-project/
 ├── config/
 │   └── import/
-│       └── providers.yaml
+│       └── providers.yaml          # Configures all paths below
 ├── ledger/
-│   └── rules/                                   # hledger rules files
-│       └── <provider>-{account-number}.rules    # {account-number} from metadata extraction
-├── statements/
-│   └── import/                                  # Drop CSV files here
-│       └── unrecognized/                        # Unclassified files moved here
-└── doc/
-    └── agent/
-        ├── todo/
-        │   └── import/
-        │       └── <provider>/                  # e.g. revolut
-        │           └── <currency>/              # e.g. chf, eur, usd, btc
-        └── done/
-            └── import/
-                └── <provider>/
-                    └── <currency>/
+│   └── rules/                      # {paths.rules}
+│       └── <provider>-{account-number}.rules
+├── import/
+│   ├── incoming/                   # {paths.import} - Drop CSV files here
+│   ├── pending/                    # {paths.pending} - Classified files
+│   │   └── <provider>/             # e.g., revolut, ubs
+│   │       └── <currency>/         # e.g., chf, eur, usd, btc
+│   ├── done/                       # {paths.done} - Processed files
+│   │   └── <provider>/
+│   │       └── <currency>/
+│   └── unrecognized/               # {paths.unrecognized} - Unknown files
 ```
 
 #### Workflow
 
-1. Drop CSV files into `statements/import/`
+1. Drop CSV files into `{paths.import}` (default: `import/incoming/`)
 2. Run `classify-statements` tool
-3. Files are moved to `doc/agent/todo/import/<provider>/<currency>/`
-4. Unrecognized files are moved to `statements/import/unrecognized/`
+3. Files are moved to `{paths.pending}/<provider>/<currency>/` (default: `import/pending/`)
+4. Unrecognized files are moved to `{paths.unrecognized}/` (default: `import/unrecognized/`)
 5. Run `import-statements` with `checkOnly: true` to validate transactions
 6. If unknown postings found: Add rules to the `.rules` file, repeat step 5
 7. Once all transactions match: Run `import-statements` with `checkOnly: false`
-8. Transactions are imported to journal, CSV files moved to `doc/agent/done/import/`
+8. Transactions are imported to journal, CSV files moved to `{paths.done}/<provider>/<currency>/` (default: `import/done/`)
 
 ### Statement Import
 
@@ -223,11 +219,13 @@ The `import-statements` tool imports classified CSV statements into hledger usin
 The tool matches CSV files to their rules files by parsing the `source` directive in each `.rules` file. For example, if `ubs-account.rules` contains:
 
 ```
-source ../../doc/agent/todo/import/ubs/chf/transactions.csv
+source ../../import/pending/ubs/chf/transactions.csv
 ```
 
 The tool will use that rules file when processing `transactions.csv`.
 
+**Note:** The `source` path should match your configured `{paths.pending}` directory structure.
+
 See the hledger documentation for details on rules file format and syntax.
 
 #### Unknown Postings

package/agent/accountant.md

@@ -8,6 +8,7 @@ tools:
   bash: true
   edit: true
   write: true
+  # MCP tools available: classify-statements, import-statements, update-prices
 permission:
   bash: allow
   edit: allow
@@ -49,15 +50,42 @@ When working with accounting tasks:
 1. **File organization** - Keep transactions in appropriate year journals
 1. **Duplicate checking** - Take extra care to avoid duplicate transactions
 1. **Unintended edits** - If a balance is off, check the journal for unintended edits
-1. **Statement tracking** - Move processed statements to `statements/{provider}/YYYY`
 1. **Consistency** - Maintain consistent formatting and naming conventions across all files
 
+## Required Tools
+
+You have access to specialized MCP tools that MUST be used for their designated tasks. Do NOT attempt to replicate their functionality with bash commands, direct hledger CLI calls, or manual file edits.
+
+| Tool                  | Use For                            | NEVER Do Instead                           |
+| --------------------- | ---------------------------------- | ------------------------------------------ |
+| `classify-statements` | Organizing incoming CSV files      | Manual file moves or bash `mv` commands    |
+| `import-statements`   | Importing transactions to journals | `hledger import`, manual journal edits     |
+| `update-prices`       | Fetching exchange rates            | `curl` to price APIs, manual price entries |
+
+These tools handle validation, deduplication, error checking, and file organization automatically. Bypassing them risks data corruption, duplicate transactions, and inconsistent state.
+
+## Bash Usage Policy
+
+Bash is allowed ONLY for:
+
+- Validation commands: `hledger check`, `hledger-fmt`, `hledger bal`
+- Read-only queries: `hledger print`, `hledger reg`, `hledger accounts`
+- File inspection: `cat`, `head`, `tail` (read-only)
+
+Bash is FORBIDDEN for:
+
+- `hledger import` - use `import-statements` tool instead
+- Moving/copying CSV files - use `classify-statements` tool instead
+- Editing journal files directly - use `edit` tool only for rules files
+- Fetching prices - use `update-prices` tool instead
+
 ## Statement Import Workflow
 
-Use the `import-statements` tool to import bank statements. Do not edit the ledger manually! The workflow:
+**IMPORTANT:** You MUST use the MCP tools below for statement imports. Do NOT edit journals manually, run `hledger import` directly, or move files with bash commands. The workflow:
 
-1. **Prepare**: Drop CSV files into the incoming import folder configured in `config/import/providers.yaml` 
-2. **Classify**: Run `classify-statements` tool to move files to the configured import pending folder
+1. **Prepare**: Drop CSV files into `{paths.import}` (configured in `config/import/providers.yaml`, default: `import/incoming`)
+2. **Classify**: Run `classify-statements` tool to organize files by provider/currency
+   - Files moved to `{paths.pending}/<provider>/<currency>/`
 3. **Validate (check mode)**: Run `import-statements(checkOnly: true)` to validate transactions
 4. **Handle unknowns**: If unknown postings found:
    - Tool returns full CSV row data for each unknown posting
@@ -65,7 +93,7 @@ Use the `import-statements` tool to import bank statements. Do not edit the ledg
    - Create or update rules file with `if` directives to match the transaction
    - Repeat step 3 until all postings are matched
 5. **Import**: Once all transactions have matching rules, run `import-statements(checkOnly: false)`
-6. **Complete**: Transactions imported to journal, CSVs moved to `doc/agent/done/import/`
+6. **Complete**: Transactions imported to journal, CSVs moved to `{paths.done}/<provider>/<currency>/`
 
 ### Rules Files
 
@@ -73,3 +101,75 @@ Use the `import-statements` tool to import bank statements. Do not edit the ledg
 - Match CSV to rules file via the `source` directive in each `.rules` file
 - Use field names from the `fields` directive for matching
 - Unknown account pattern: `income:unknown` (positive amounts) / `expenses:unknown` (negative amounts)
+
+## Tool Usage Reference
+
+The following are MCP tools available to you. Always call these tools directly - do not attempt to replicate their behavior with shell commands.
+
+### classify-statements
+
+**Purpose:** Organizes CSV files by auto-detecting provider and currency.
+
+**Usage:** `classify-statements()` (no arguments)
+
+**Behavior:**
+
+- Scans `{paths.import}` for CSV files
+- Detects provider using header matching + filename patterns
+- Moves classified files to `{paths.pending}/<provider>/<currency>/`
+- Moves unrecognized files to `{paths.unrecognized}/`
+- Aborts if any file collision detected (no partial moves)
+
+**Output:** Returns classified/unrecognized file lists with target paths
+
+**Common issues:**
+
+- Unrecognized files → Add provider config to `config/import/providers.yaml`
+- Collisions → Move/rename existing pending files before re-running
+
+---
+
+### import-statements
+
+**Purpose:** Imports classified CSV transactions into hledger journals.
+
+**Usage:**
+
+- Check mode (default): `import-statements(checkOnly: true)` or `import-statements()`
+- Import mode: `import-statements(checkOnly: false)`
+
+**Behavior:**
+
+- Processes CSV files in `{paths.pending}/<provider>/<currency>/`
+- Matches each CSV to rules file via `source` directive
+- Check mode: Validates transactions, reports unknown postings with full CSV row data
+- Import mode: Only proceeds if ALL transactions have known accounts, moves CSVs to `{paths.done}/`
+
+**Output:** Returns per-file results with transaction counts and unknown postings (if any)
+
+**Required for import:**
+
+- All transactions must have matching rules (no `income:unknown` or `expenses:unknown`)
+- Each CSV must have a corresponding `.rules` file in `{paths.rules}`
+
+---
+
+### update-prices
+
+**Purpose:** Fetches currency exchange rates and updates `ledger/currencies/` journals.
+
+**Usage:**
+
+- Daily mode (default): `update-prices()` or `update-prices(backfill: false)`
+- Backfill mode: `update-prices(backfill: true)`
+
+**Behavior:**
+
+- Daily mode: Fetches yesterday's prices only
+- Backfill mode: Fetches from `backfill_date` (or Jan 1 of current year) to yesterday
+- Updates journal files in-place with deduplication (newer prices overwrite older for same date)
+- Processes all currencies independently (partial failures possible)
+
+**Output:** Returns per-currency results with latest price line or error message
+
+**Configuration:** `config/prices.yaml` defines currencies, sources, pairs, and backfill dates

package/dist/index.js

@@ -17689,6 +17689,18 @@ function countTransactions(hledgerOutput) {
   }
   return count;
 }
+function extractTransactionYears(hledgerOutput) {
+  const years = new Set;
+  const lines = hledgerOutput.split(`
+`);
+  for (const line of lines) {
+    const match = line.match(/^(\d{4})-\d{2}-\d{2}\s+/);
+    if (match) {
+      years.add(parseInt(match[1], 10));
+    }
+  }
+  return years;
+}
 
 // src/utils/rulesParser.ts
 function parseSkipRows(rulesContent) {
@@ -17903,6 +17915,30 @@ function findMatchingCsvRow(posting, csvRows, config2) {
 }
 
 // src/tools/import-statements.ts
+function ensureYearJournalExists(directory, year) {
+  const ledgerDir = path6.join(directory, "ledger");
+  const yearJournalPath = path6.join(ledgerDir, `${year}.journal`);
+  const mainJournalPath = path6.join(directory, ".hledger.journal");
+  if (!fs7.existsSync(ledgerDir)) {
+    fs7.mkdirSync(ledgerDir, { recursive: true });
+  }
+  if (!fs7.existsSync(yearJournalPath)) {
+    fs7.writeFileSync(yearJournalPath, `; ${year} transactions
+`);
+  }
+  if (!fs7.existsSync(mainJournalPath)) {
+    throw new Error(`.hledger.journal not found at ${mainJournalPath}. Create it first with appropriate includes.`);
+  }
+  const mainJournalContent = fs7.readFileSync(mainJournalPath, "utf-8");
+  const includeDirective = `include ledger/${year}.journal`;
+  if (!mainJournalContent.includes(includeDirective)) {
+    const newContent = mainJournalContent.trimEnd() + `
+` + includeDirective + `
+`;
+    fs7.writeFileSync(mainJournalPath, newContent);
+  }
+  return yearJournalPath;
+}
 function findPendingCsvFiles(pendingDir, provider, currency) {
   const csvFiles = [];
   if (!fs7.existsSync(pendingDir)) {
@@ -18006,18 +18042,32 @@ async function importStatementsCore(directory, agent, options, configLoader = lo
     const unknownPostings = parseUnknownPostings(result.stdout);
     const transactionCount = countTransactions(result.stdout);
     const matchedCount = transactionCount - unknownPostings.length;
+    const years = extractTransactionYears(result.stdout);
+    if (years.size > 1) {
+      const yearList = Array.from(years).sort().join(", ");
+      filesWithErrors++;
+      fileResults.push({
+        csv: path6.relative(directory, csvFile),
+        rulesFile: path6.relative(directory, rulesFile),
+        totalTransactions: transactionCount,
+        matchedTransactions: matchedCount,
+        unknownPostings: [],
+        error: `CSV contains transactions from multiple years (${yearList}). Split the CSV by year before importing.`
+      });
+      continue;
+    }
+    const transactionYear = years.size === 1 ? Array.from(years)[0] : undefined;
     if (unknownPostings.length > 0) {
       try {
         const rulesContent = fs7.readFileSync(rulesFile, "utf-8");
         const rulesConfig = parseRulesFile(rulesContent);
         const csvRows = parseCsvFile(csvFile, rulesConfig);
         for (const posting of unknownPostings) {
-          const csvRow = findMatchingCsvRow({
+          posting.csvRow = findMatchingCsvRow({
             date: posting.date,
             description: posting.description,
             amount: posting.amount
           }, csvRows, rulesConfig);
-          posting.csvRow = csvRow;
         }
       } catch {
         for (const posting of unknownPostings) {
@@ -18033,7 +18083,8 @@ async function importStatementsCore(directory, agent, options, configLoader = lo
       rulesFile: path6.relative(directory, rulesFile),
       totalTransactions: transactionCount,
       matchedTransactions: matchedCount,
-      unknownPostings
+      unknownPostings,
+      transactionYear
     });
   }
   const hasUnknowns = totalUnknown > 0;
@@ -18077,11 +18128,53 @@ async function importStatementsCore(directory, agent, options, configLoader = lo
     });
   }
   const importedFiles = [];
-  for (const csvFile of csvFiles) {
-    const rulesFile = findRulesForCsv(csvFile, rulesMapping);
+  for (const fileResult of fileResults) {
+    const csvFile = path6.join(directory, fileResult.csv);
+    const rulesFile = fileResult.rulesFile ? path6.join(directory, fileResult.rulesFile) : null;
     if (!rulesFile)
       continue;
-    const result = await hledgerExecutor(["import", csvFile, "--rules-file", rulesFile]);
+    const year = fileResult.transactionYear;
+    if (!year) {
+      return JSON.stringify({
+        success: false,
+        files: fileResults,
+        summary: {
+          filesProcessed: csvFiles.length,
+          filesWithErrors: 1,
+          filesWithoutRules,
+          totalTransactions,
+          matched: totalMatched,
+          unknown: totalUnknown
+        },
+        error: `No transactions found in ${fileResult.csv}`
+      });
+    }
+    let yearJournalPath;
+    try {
+      yearJournalPath = ensureYearJournalExists(directory, year);
+    } catch (error45) {
+      return JSON.stringify({
+        success: false,
+        files: fileResults,
+        summary: {
+          filesProcessed: csvFiles.length,
+          filesWithErrors: 1,
+          filesWithoutRules,
+          totalTransactions,
+          matched: totalMatched,
+          unknown: totalUnknown
+        },
+        error: error45 instanceof Error ? error45.message : String(error45)
+      });
+    }
+    const result = await hledgerExecutor([
+      "import",
+      "-f",
+      yearJournalPath,
+      csvFile,
+      "--rules-file",
+      rulesFile
+    ]);
     if (result.exitCode !== 0) {
       return JSON.stringify({
         success: false,
@@ -18094,7 +18187,7 @@ async function importStatementsCore(directory, agent, options, configLoader = lo
           matched: totalMatched,
           unknown: totalUnknown
         },
-        error: `Import failed for ${path6.relative(directory, csvFile)}: ${result.stderr.trim()}`
+        error: `Import failed for ${fileResult.csv}: ${result.stderr.trim()}`
       });
     }
     importedFiles.push(csvFile);