@fuzzle/opencode-accountant 0.0.9-next.1 → 0.0.10

package/README.md

@@ -97,6 +97,7 @@ paths:
   pending: doc/agent/todo/import
   done: doc/agent/done/import
   unrecognized: statements/import/unrecognized
+  rules: ledger/rules
 
 providers:
   revolut:
@@ -121,9 +122,9 @@ providers:
         currencyField: Currency
         skipRows: 9
         delimiter: ';'
-        renamePattern: 'transactions-ubs-{accountnumber}.csv'
+        renamePattern: 'transactions-ubs-{account-number}.csv'
         metadata:
-          - field: accountnumber
+          - field: account-number
             row: 0
             column: 1
             normalize: spaces-to-dashes
@@ -143,6 +144,7 @@ providers:
 | `pending`      | Base path for classified files awaiting import  |
 | `done`         | Base path for archived files after import       |
 | `unrecognized` | Directory for files that couldn't be classified |
+| `rules`        | Directory containing hledger `.rules` files     |
 
 **Provider Detection Rules:**
 
@@ -175,15 +177,18 @@ your-project/
 ├── config/
 │   └── import/
 │       └── providers.yaml
+├── 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
+│   └── 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
+        │       └── <provider>/                  # e.g. revolut
+        │           └── <currency>/              # e.g. chf, eur, usd, btc
         └── done/
             └── import/
                 └── <provider>/
@@ -196,7 +201,40 @@ your-project/
 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/`
-5. After successful import, files should be moved to `doc/agent/done/import/`
+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/`
+
+### Statement Import
+
+The `import-statements` tool imports classified CSV statements into hledger using rules files. It validates transactions before import and identifies any that cannot be categorized.
+
+#### Tool Arguments
+
+| Argument    | Type    | Default | Description                                 |
+| ----------- | ------- | ------- | ------------------------------------------- |
+| `provider`  | string  | -       | Filter by provider (e.g., `revolut`, `ubs`) |
+| `currency`  | string  | -       | Filter by currency (e.g., `chf`, `eur`)     |
+| `checkOnly` | boolean | `true`  | If true, only validate without importing    |
+
+#### Rules File Matching
+
+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
+```
+
+The tool will use that rules file when processing `transactions.csv`.
+
+See the hledger documentation for details on rules file format and syntax.
+
+#### Unknown Postings
+
+When a transaction doesn't match any `if` pattern in the rules file, hledger assigns it to `income:unknown` or `expenses:unknown` depending on the transaction direction. The tool reports these so you can add appropriate rules.
+
+For detailed output format examples, see [`docs/tools/import-statements.md`](docs/tools/import-statements.md).
 
 ## Development
 

package/agent/accountant.md

@@ -3,13 +3,13 @@ description: Specialized agent for hledger accounting tasks and transaction mana
 prompt: You are an accounting specialist with expertise in hledger and double-entry bookkeeping. Your role is to help maintain accurate financial records following the user's conventions.
 mode: subagent
 temperature: 0.1
-steps: 5
+steps: 8
 tools:
-  bash: false
+  bash: true
   edit: true
   write: true
 permission:
-  bash: deny
+  bash: allow
   edit: allow
   glob: allow
   grep: allow
@@ -24,25 +24,19 @@ permission:
 
 ## Repository Structure
 
-- `.hledger.journal` - Global hledger journal file,
+- `.hledger.journal` - Global hledger journal file
 - `ledger/` - All ledger related files are stored here
 - `ledger/currencies/` - Currency exchange rate files
 - `ledger/YYYY.journal` - Annual hledger journal files
+- `ledger/rules` - hledger rules files
 - `statements/` - Bank and broker account statements
 - `statements/import` - Upload folder for new statements to process
-- `statements/provider/YYYY` - Location where processed statements are stored
-- `doc/agent/todo/` - Agents task work directory
+- `statements/{provider}/YYYY` - Processed statements organized by source and year
+- `doc/agent/todo/` - Agent's task work directory
 - `doc/agent/done/` - Tasks completed by the agent
 - `config/conventions/` - Accounting conventions
 - `config/rules/` - import rules files
 
-## System Environment
-
-**Required for accounting tasks:**
-
-- `pricehist` - Price data fetching
-- `hledger`, `hledger-fmt` - Accounting operations
-
 ## Conventions & Workflow
 
 All account conventions, conversion patterns (currency, crypto, equity postings), transaction status management, import
@@ -59,15 +53,5 @@ 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`
-
-## Common Tasks
-
-- Adding new transactions from statements
-- Processing crypto purchases and transfers
-- Currency conversions between CHF/EUR/USD
-- Validating journal integrity
-- Generating balance reports
-- Correcting malformed transactions
-
-Focus on accuracy, precision, and strict adherence to the repository's accounting conventions.
+1. **Statement tracking** - Move processed statements to `statements/{provider}/YYYY`
+1. **Consistency** - Maintain consistent formatting and naming conventions across all files

package/dist/index.js

@@ -1341,7 +1341,7 @@ var require_papaparse = __commonJS((exports, module) => {
 });
 
 // src/index.ts
-import { dirname as dirname2, join as join5 } from "path";
+import { dirname as dirname4, join as join7 } from "path";
 import { fileURLToPath } from "url";
 
 // src/utils/agentLoader.ts
@@ -16584,7 +16584,13 @@ import * as fs4 from "fs";
 import * as fs3 from "fs";
 import * as path3 from "path";
 var CONFIG_FILE2 = "config/import/providers.yaml";
-var REQUIRED_PATH_FIELDS = ["import", "pending", "done", "unrecognized"];
+var REQUIRED_PATH_FIELDS = [
+  "import",
+  "pending",
+  "done",
+  "unrecognized",
+  "rules"
+];
 var REQUIRED_DETECTION_FIELDS = ["header", "currencyField"];
 function validatePaths(paths) {
   if (typeof paths !== "object" || paths === null) {
@@ -16600,7 +16606,8 @@ function validatePaths(paths) {
     import: pathsObj.import,
     pending: pathsObj.pending,
     done: pathsObj.done,
-    unrecognized: pathsObj.unrecognized
+    unrecognized: pathsObj.unrecognized,
+    rules: pathsObj.rules
   };
 }
 function validateDetectionRule(providerName, index, rule) {
@@ -16968,15 +16975,369 @@ var classify_statements_default = tool({
     return classifyStatementsCore(directory, agent);
   }
 });
+// src/tools/import-statements.ts
+import * as fs6 from "fs";
+import * as path6 from "path";
+
+// src/utils/rulesMatcher.ts
+import * as fs5 from "fs";
+import * as path5 from "path";
+function parseSourceDirective(content) {
+  const match = content.match(/^source\s+([^\n#]+)/m);
+  if (!match) {
+    return null;
+  }
+  return match[1].trim();
+}
+function resolveSourcePath(sourcePath, rulesFilePath) {
+  if (path5.isAbsolute(sourcePath)) {
+    return sourcePath;
+  }
+  const rulesDir = path5.dirname(rulesFilePath);
+  return path5.resolve(rulesDir, sourcePath);
+}
+function loadRulesMapping(rulesDir) {
+  const mapping = {};
+  if (!fs5.existsSync(rulesDir)) {
+    return mapping;
+  }
+  const files = fs5.readdirSync(rulesDir);
+  for (const file2 of files) {
+    if (!file2.endsWith(".rules")) {
+      continue;
+    }
+    const rulesFilePath = path5.join(rulesDir, file2);
+    const stat = fs5.statSync(rulesFilePath);
+    if (!stat.isFile()) {
+      continue;
+    }
+    const content = fs5.readFileSync(rulesFilePath, "utf-8");
+    const sourcePath = parseSourceDirective(content);
+    if (!sourcePath) {
+      continue;
+    }
+    const absoluteCsvPath = resolveSourcePath(sourcePath, rulesFilePath);
+    mapping[absoluteCsvPath] = rulesFilePath;
+  }
+  return mapping;
+}
+function findRulesForCsv(csvPath, mapping) {
+  if (mapping[csvPath]) {
+    return mapping[csvPath];
+  }
+  const normalizedCsvPath = path5.normalize(csvPath);
+  for (const [mappedCsv, rulesFile] of Object.entries(mapping)) {
+    if (path5.normalize(mappedCsv) === normalizedCsvPath) {
+      return rulesFile;
+    }
+  }
+  return null;
+}
+
+// src/utils/hledgerExecutor.ts
+var {$: $2 } = globalThis.Bun;
+async function defaultHledgerExecutor(cmdArgs) {
+  try {
+    const result = await $2`hledger ${cmdArgs}`.quiet().nothrow();
+    return {
+      stdout: result.stdout.toString(),
+      stderr: result.stderr.toString(),
+      exitCode: result.exitCode
+    };
+  } catch (error45) {
+    return {
+      stdout: "",
+      stderr: error45 instanceof Error ? error45.message : String(error45),
+      exitCode: 1
+    };
+  }
+}
+function parseUnknownPostings(hledgerOutput) {
+  const unknownPostings = [];
+  const lines = hledgerOutput.split(`
+`);
+  let currentDate = "";
+  let currentDescription = "";
+  for (const line of lines) {
+    const headerMatch = line.match(/^(\d{4}-\d{2}-\d{2})\s+(.+)$/);
+    if (headerMatch) {
+      currentDate = headerMatch[1];
+      currentDescription = headerMatch[2].trim();
+      continue;
+    }
+    const postingMatch = line.match(/^\s+(income:unknown|expenses:unknown)\s+([^\s]+(?:\s+[^\s=]+)?)\s*(?:=\s*(.+))?$/);
+    if (postingMatch && currentDate) {
+      unknownPostings.push({
+        date: currentDate,
+        description: currentDescription,
+        amount: postingMatch[2].trim(),
+        account: postingMatch[1],
+        balance: postingMatch[3]?.trim()
+      });
+    }
+  }
+  return unknownPostings;
+}
+function countTransactions(hledgerOutput) {
+  const lines = hledgerOutput.split(`
+`);
+  let count = 0;
+  for (const line of lines) {
+    if (/^\d{4}-\d{2}-\d{2}\s+/.test(line)) {
+      count++;
+    }
+  }
+  return count;
+}
+
+// src/tools/import-statements.ts
+function findPendingCsvFiles(pendingDir, provider, currency) {
+  const csvFiles = [];
+  if (!fs6.existsSync(pendingDir)) {
+    return csvFiles;
+  }
+  let searchPath = pendingDir;
+  if (provider) {
+    searchPath = path6.join(searchPath, provider);
+    if (currency) {
+      searchPath = path6.join(searchPath, currency);
+    }
+  }
+  if (!fs6.existsSync(searchPath)) {
+    return csvFiles;
+  }
+  function scanDirectory(directory) {
+    const entries = fs6.readdirSync(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path6.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        scanDirectory(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith(".csv")) {
+        csvFiles.push(fullPath);
+      }
+    }
+  }
+  scanDirectory(searchPath);
+  return csvFiles.sort();
+}
+async function importStatementsCore(directory, agent, options, configLoader = loadImportConfig, hledgerExecutor = defaultHledgerExecutor) {
+  if (agent !== "accountant") {
+    return JSON.stringify({
+      success: false,
+      error: `This tool is restricted to the accountant agent only. Called by: ${agent || "main assistant"}`,
+      hint: "Use: Task(subagent_type='accountant', prompt='import statements')"
+    });
+  }
+  let config2;
+  try {
+    config2 = configLoader(directory);
+  } catch (error45) {
+    return JSON.stringify({
+      success: false,
+      error: `Failed to load configuration: ${error45 instanceof Error ? error45.message : String(error45)}`,
+      hint: 'Ensure config/import/providers.yaml exists with required paths including "rules"'
+    });
+  }
+  const pendingDir = path6.join(directory, config2.paths.pending);
+  const rulesDir = path6.join(directory, config2.paths.rules);
+  const doneDir = path6.join(directory, config2.paths.done);
+  const rulesMapping = loadRulesMapping(rulesDir);
+  const csvFiles = findPendingCsvFiles(pendingDir, options.provider, options.currency);
+  if (csvFiles.length === 0) {
+    return JSON.stringify({
+      success: true,
+      files: [],
+      summary: {
+        filesProcessed: 0,
+        filesWithErrors: 0,
+        filesWithoutRules: 0,
+        totalTransactions: 0,
+        matched: 0,
+        unknown: 0
+      },
+      message: "No CSV files found to process"
+    });
+  }
+  const fileResults = [];
+  let totalTransactions = 0;
+  let totalMatched = 0;
+  let totalUnknown = 0;
+  let filesWithErrors = 0;
+  let filesWithoutRules = 0;
+  for (const csvFile of csvFiles) {
+    const rulesFile = findRulesForCsv(csvFile, rulesMapping);
+    if (!rulesFile) {
+      filesWithoutRules++;
+      fileResults.push({
+        csv: path6.relative(directory, csvFile),
+        rulesFile: null,
+        totalTransactions: 0,
+        matchedTransactions: 0,
+        unknownPostings: [],
+        error: "No matching rules file found"
+      });
+      continue;
+    }
+    const result = await hledgerExecutor(["print", "-f", csvFile, "--rules-file", rulesFile]);
+    if (result.exitCode !== 0) {
+      filesWithErrors++;
+      fileResults.push({
+        csv: path6.relative(directory, csvFile),
+        rulesFile: path6.relative(directory, rulesFile),
+        totalTransactions: 0,
+        matchedTransactions: 0,
+        unknownPostings: [],
+        error: `hledger error: ${result.stderr.trim() || "Unknown error"}`
+      });
+      continue;
+    }
+    const unknownPostings = parseUnknownPostings(result.stdout);
+    const transactionCount = countTransactions(result.stdout);
+    const matchedCount = transactionCount - unknownPostings.length;
+    totalTransactions += transactionCount;
+    totalMatched += matchedCount;
+    totalUnknown += unknownPostings.length;
+    fileResults.push({
+      csv: path6.relative(directory, csvFile),
+      rulesFile: path6.relative(directory, rulesFile),
+      totalTransactions: transactionCount,
+      matchedTransactions: matchedCount,
+      unknownPostings
+    });
+  }
+  const hasUnknowns = totalUnknown > 0;
+  const hasErrors = filesWithErrors > 0 || filesWithoutRules > 0;
+  if (options.checkOnly !== false) {
+    const result = {
+      success: !hasUnknowns && !hasErrors,
+      files: fileResults,
+      summary: {
+        filesProcessed: csvFiles.length,
+        filesWithErrors,
+        filesWithoutRules,
+        totalTransactions,
+        matched: totalMatched,
+        unknown: totalUnknown
+      }
+    };
+    if (hasUnknowns) {
+      result.message = `Found ${totalUnknown} transaction(s) with unknown accounts. Add rules to categorize them.`;
+    } else if (hasErrors) {
+      result.message = `Some files had errors. Check the file results for details.`;
+    } else {
+      result.message = "All transactions matched. Ready to import with checkOnly: false";
+    }
+    return JSON.stringify(result);
+  }
+  if (hasUnknowns || hasErrors) {
+    return JSON.stringify({
+      success: false,
+      files: fileResults,
+      summary: {
+        filesProcessed: csvFiles.length,
+        filesWithErrors,
+        filesWithoutRules,
+        totalTransactions,
+        matched: totalMatched,
+        unknown: totalUnknown
+      },
+      error: "Cannot import: some transactions have unknown accounts or files have errors",
+      hint: "Run with checkOnly: true to see details, then add missing rules"
+    });
+  }
+  const importedFiles = [];
+  for (const csvFile of csvFiles) {
+    const rulesFile = findRulesForCsv(csvFile, rulesMapping);
+    if (!rulesFile)
+      continue;
+    const result = await hledgerExecutor(["import", csvFile, "--rules-file", rulesFile]);
+    if (result.exitCode !== 0) {
+      return JSON.stringify({
+        success: false,
+        files: fileResults,
+        summary: {
+          filesProcessed: csvFiles.length,
+          filesWithErrors: 1,
+          filesWithoutRules,
+          totalTransactions,
+          matched: totalMatched,
+          unknown: totalUnknown
+        },
+        error: `Import failed for ${path6.relative(directory, csvFile)}: ${result.stderr.trim()}`
+      });
+    }
+    importedFiles.push(csvFile);
+  }
+  for (const csvFile of importedFiles) {
+    const relativePath = path6.relative(pendingDir, csvFile);
+    const destPath = path6.join(doneDir, relativePath);
+    const destDir = path6.dirname(destPath);
+    if (!fs6.existsSync(destDir)) {
+      fs6.mkdirSync(destDir, { recursive: true });
+    }
+    fs6.renameSync(csvFile, destPath);
+  }
+  return JSON.stringify({
+    success: true,
+    files: fileResults.map((f) => ({
+      ...f,
+      imported: true
+    })),
+    summary: {
+      filesProcessed: csvFiles.length,
+      filesWithErrors: 0,
+      filesWithoutRules: 0,
+      totalTransactions,
+      matched: totalMatched,
+      unknown: 0
+    },
+    message: `Successfully imported ${totalTransactions} transaction(s) from ${importedFiles.length} file(s)`
+  });
+}
+var import_statements_default = tool({
+  description: `Import classified bank statement CSVs into hledger using rules files.
+
+This tool processes CSV files in the pending import directory and uses hledger's CSV import capabilities with matching rules files.
+
+**Check Mode (checkOnly: true, default):**
+- Runs hledger print to preview transactions
+- Identifies transactions with 'income:unknown' or 'expenses:unknown' accounts
+- These indicate missing rules that need to be added
+
+**Import Mode (checkOnly: false):**
+- First validates all transactions have known accounts
+- If any unknowns exist, aborts and reports them
+- If all clean, imports transactions and moves CSVs to done directory
+
+**Workflow:**
+1. Run with checkOnly: true (or no args)
+2. If unknowns found, add rules to the appropriate .rules file
+3. Repeat until no unknowns
+4. Run with checkOnly: false to import`,
+  args: {
+    provider: tool.schema.string().optional().describe('Filter by provider (e.g., "revolut", "ubs"). If omitted, process all providers.'),
+    currency: tool.schema.string().optional().describe('Filter by currency (e.g., "chf", "eur"). If omitted, process all currencies for the provider.'),
+    checkOnly: tool.schema.boolean().optional().describe("If true (default), only check for unknown accounts without importing. Set to false to perform actual import.")
+  },
+  async execute(params, context) {
+    const { directory, agent } = context;
+    return importStatementsCore(directory, agent, {
+      provider: params.provider,
+      currency: params.currency,
+      checkOnly: params.checkOnly
+    });
+  }
+});
 // src/index.ts
-var __dirname2 = dirname2(fileURLToPath(import.meta.url));
-var AGENT_FILE = join5(__dirname2, "..", "agent", "accountant.md");
+var __dirname2 = dirname4(fileURLToPath(import.meta.url));
+var AGENT_FILE = join7(__dirname2, "..", "agent", "accountant.md");
 var AccountantPlugin = async () => {
   const agent = loadAgent(AGENT_FILE);
   return {
     tool: {
       "update-prices": update_prices_default,
-      "classify-statements": classify_statements_default
+      "classify-statements": classify_statements_default,
+      "import-statements": import_statements_default
     },
     config: async (config2) => {
       if (agent) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzzle/opencode-accountant",
-  "version": "0.0.9-next.1",
+  "version": "0.0.10",
   "description": "An OpenCode accounting agent, specialized in double-entry-bookkepping with hledger",
   "author": {
     "name": "ali bengali",