@fuzzle/opencode-accountant 0.7.2-next.1 → 0.7.2

package/agent/accountant.md

@@ -118,7 +118,8 @@ The `import-pipeline` tool operates directly on the working directory:
 3. **Automatic Processing**: The tool:
    - Classifies CSV files by provider/currency (creates import contexts in `.memory/`)
    - Extracts required accounts from rules files and updates year journal
-   - Validates and imports transactions to the appropriate year journal
+   - Validates all transactions have matching rules (dry run)
+   - Imports transactions to the appropriate year journal
    - Reconciles closing balance (auto-detected from CSV metadata or data, or manual override)
    - CSV files move: `incoming/` → `pending/` → `done/`
 4. **After Pipeline**: All changes remain uncommitted in your working directory for inspection
@@ -192,7 +193,8 @@ The following are MCP tools available to you. Always call these tools directly -
 1. Classifies CSV files and creates import contexts (unless `skipClassify: true`)
 2. For each context (sequentially, fail-fast):
    - Extracts accounts from matched rules and updates year journal with declarations
-   - Validates and imports transactions to year journal, moves CSV from `pending/` to `done/`
+   - Validates all transactions have matching rules (dry run)
+   - Imports transactions to year journal, moves CSV from `pending/` to `done/`
    - Reconciles closing balance (auto-detected from CSV metadata/data or manual override)
 3. All changes remain uncommitted in the working directory
 

package/dist/index.js

@@ -23667,6 +23667,28 @@ async function importStatements(directory, agent, options, configLoader = loadIm
   }
   const hasUnknowns = totalUnknown > 0;
   const hasErrors = filesWithErrors > 0 || filesWithoutRules > 0;
+  if (options.checkOnly !== false) {
+    const result = {
+      success: !hasUnknowns && !hasErrors,
+      files: fileResults,
+      summary: {
+        filesProcessed: fileResults.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 buildErrorResultWithDetails("Cannot import: some transactions have unknown accounts or files have errors", fileResults, {
       filesProcessed: fileResults.length,
@@ -23675,7 +23697,7 @@ async function importStatements(directory, agent, options, configLoader = loadIm
       totalTransactions,
       matched: totalMatched,
       unknown: totalUnknown
-    }, "Add missing rules to categorize unknown transactions, then retry");
+    }, "Run with checkOnly: true to see details, then add missing rules");
   }
   const importResult = await executeImports(fileResults, directory, pendingDir, doneDir, hledgerExecutor);
   if (!importResult.success) {
@@ -23715,19 +23737,32 @@ var import_statements_default = tool({
 
 This tool processes CSV files in the pending import directory and uses hledger's CSV import capabilities with matching rules files.
 
-**Behavior:**
-- First validates all transactions have known accounts (runs hledger print)
-- If any 'income:unknown' or 'expenses:unknown' accounts found, aborts and reports them
+**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
+
 Note: This tool is typically called via import-pipeline for the full workflow.`,
   args: {
-    contextId: tool.schema.string().describe("Context ID from classify step. Used to locate the specific CSV file to process.")
+    contextId: tool.schema.string().describe("Context ID from classify step. Used to locate the specific CSV file to process."),
+    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 importStatements(directory, agent, {
-      contextId: params.contextId
+      contextId: params.contextId,
+      checkOnly: params.checkOnly
     });
   }
 });
@@ -24985,6 +25020,61 @@ async function buildSuggestionContext(context, contextId, logger) {
     logger
   };
 }
+async function executeDryRunStep(context, contextId, logger) {
+  logger?.startSection("Step 3: Dry Run Import");
+  logger?.logStep("Dry Run", "start");
+  const dryRunResult = await importStatements(context.directory, context.agent, {
+    contextId,
+    checkOnly: true
+  }, context.configLoader, context.hledgerExecutor);
+  const dryRunParsed = JSON.parse(dryRunResult);
+  const message = dryRunParsed.success ? `Dry run passed: ${dryRunParsed.summary?.totalTransactions || 0} transactions ready` : `Dry run failed: ${dryRunParsed.summary?.unknown || 0} unknown account(s)`;
+  logger?.logStep("Dry Run", dryRunParsed.success ? "success" : "error", message);
+  if (dryRunParsed.summary?.totalTransactions) {
+    logger?.info(`Found ${dryRunParsed.summary.totalTransactions} transactions`);
+  }
+  let postingsWithSuggestions = [];
+  if (!dryRunParsed.success) {
+    const allUnknownPostings = [];
+    for (const file2 of dryRunParsed.files ?? []) {
+      if (file2.unknownPostings && file2.unknownPostings.length > 0) {
+        allUnknownPostings.push(...file2.unknownPostings);
+      }
+    }
+    if (allUnknownPostings.length > 0) {
+      try {
+        const { suggestAccountsForPostingsBatch: suggestAccountsForPostingsBatch2 } = await Promise.resolve().then(() => (init_accountSuggester(), exports_accountSuggester));
+        const suggestionContext = await buildSuggestionContext(context, contextId, logger);
+        postingsWithSuggestions = await suggestAccountsForPostingsBatch2(allUnknownPostings, suggestionContext);
+      } catch (error45) {
+        logger?.error(`[ERROR] Failed to generate account suggestions: ${error45 instanceof Error ? error45.message : String(error45)}`);
+        postingsWithSuggestions = allUnknownPostings;
+      }
+    }
+  }
+  const detailsLog = postingsWithSuggestions.length > 0 ? formatUnknownPostingsLog(postingsWithSuggestions) : undefined;
+  context.result.steps.dryRun = buildStepResult(dryRunParsed.success, message, {
+    success: dryRunParsed.success,
+    summary: dryRunParsed.summary,
+    unknownPostings: postingsWithSuggestions.length > 0 ? postingsWithSuggestions : undefined,
+    detailsLog
+  });
+  if (!dryRunParsed.success) {
+    if (detailsLog) {
+      logger?.error("Dry run found unknown accounts or errors");
+      logger?.info(detailsLog);
+    }
+    logger?.endSection();
+    context.result.error = "Dry run found unknown accounts or errors";
+    context.result.hint = "Add rules to categorize unknown transactions, then retry. See details above for suggestions.";
+    throw new Error("Dry run failed");
+  }
+  if (dryRunParsed.summary?.totalTransactions === 0) {
+    logger?.endSection();
+    throw new NoTransactionsError;
+  }
+  logger?.endSection();
+}
 function formatUnknownPostingsLog(postings) {
   if (postings.length === 0)
     return "";
@@ -25021,40 +25111,18 @@ function formatUnknownPostingsLog(postings) {
 }
 async function executeImportStep(context, contextId, logger) {
   const importContext = loadContext(context.directory, contextId);
-  logger?.startSection(`Step 3: Import Transactions (${importContext.accountNumber || contextId})`);
+  logger?.startSection(`Step 4: Import Transactions (${importContext.accountNumber || contextId})`);
   logger?.logStep("Import", "start");
   const importResult = await importStatements(context.directory, context.agent, {
-    contextId
+    contextId,
+    checkOnly: false
   }, context.configLoader, context.hledgerExecutor);
   const importParsed = JSON.parse(importResult);
   const message = importParsed.success ? `Imported ${importParsed.summary?.totalTransactions || 0} transactions` : `Import failed: ${importParsed.error || "Unknown error"}`;
   logger?.logStep("Import", importParsed.success ? "success" : "error", message);
-  let postingsWithSuggestions;
-  let detailsLog;
-  if (!importParsed.success) {
-    const allUnknownPostings = [];
-    for (const file2 of importParsed.files ?? []) {
-      if (file2.unknownPostings && file2.unknownPostings.length > 0) {
-        allUnknownPostings.push(...file2.unknownPostings);
-      }
-    }
-    if (allUnknownPostings.length > 0) {
-      try {
-        const { suggestAccountsForPostingsBatch: suggestAccountsForPostingsBatch2 } = await Promise.resolve().then(() => (init_accountSuggester(), exports_accountSuggester));
-        const suggestionContext = await buildSuggestionContext(context, contextId, logger);
-        postingsWithSuggestions = await suggestAccountsForPostingsBatch2(allUnknownPostings, suggestionContext);
-      } catch (error45) {
-        logger?.error(`[ERROR] Failed to generate account suggestions: ${error45 instanceof Error ? error45.message : String(error45)}`);
-        postingsWithSuggestions = allUnknownPostings;
-      }
-      detailsLog = postingsWithSuggestions && postingsWithSuggestions.length > 0 ? formatUnknownPostingsLog(postingsWithSuggestions) : undefined;
-    }
-  }
   context.result.steps.import = buildStepResult(importParsed.success, message, {
     success: importParsed.success,
     summary: importParsed.summary,
-    unknownPostings: postingsWithSuggestions,
-    detailsLog,
     error: importParsed.error
   });
   if (importParsed.success) {
@@ -25065,26 +25133,16 @@ async function executeImportStep(context, contextId, logger) {
     });
   }
   if (!importParsed.success) {
-    if (detailsLog) {
-      logger?.error("Import found unknown accounts or errors");
-      logger?.info(detailsLog);
-    } else {
-      logger?.error("Import failed", new Error(importParsed.error || "Unknown error"));
-    }
+    logger?.error("Import failed", new Error(importParsed.error || "Unknown error"));
     logger?.endSection();
-    context.result.error = detailsLog ? "Import found unknown accounts or errors" : `Import failed: ${importParsed.error || "Unknown error"}`;
-    context.result.hint = detailsLog ? "Add rules to categorize unknown transactions, then retry. See details above for suggestions." : undefined;
+    context.result.error = `Import failed: ${importParsed.error || "Unknown error"}`;
     throw new Error("Import failed");
   }
-  if (importParsed.summary?.totalTransactions === 0) {
-    logger?.endSection();
-    throw new NoTransactionsError;
-  }
   logger?.endSection();
 }
 async function executeReconcileStep(context, contextId, logger) {
   const importContext = loadContext(context.directory, contextId);
-  logger?.startSection(`Step 4: Reconcile Balance (${importContext.accountNumber || contextId})`);
+  logger?.startSection(`Step 5: Reconcile Balance (${importContext.accountNumber || contextId})`);
   logger?.logStep("Reconcile", "start");
   const reconcileResult = await reconcileStatement(context.directory, context.agent, {
     contextId,
@@ -25163,6 +25221,7 @@ async function importPipeline(directory, agent, options, configLoader = loadImpo
       const importContext = loadContext(context.directory, contextId);
       logger.info(`Processing: ${importContext.filename} (${importContext.accountNumber || "unknown account"})`);
       await executeAccountDeclarationsStep(context, contextId, logger);
+      await executeDryRunStep(context, contextId, logger);
       await executeImportStep(context, contextId, logger);
       await executeReconcileStep(context, contextId, logger);
       totalTransactions += context.result.steps.import?.details?.summary?.totalTransactions || 0;
@@ -25200,8 +25259,9 @@ This tool orchestrates the full import workflow:
 **Pipeline Steps:**
 1. **Classify**: Moves CSVs from import/incoming to import/pending (optional, skip with skipClassify)
 2. **Account Declarations**: Ensures all required accounts are declared in year journal
-3. **Import**: Validates all transactions have known accounts, imports to journal (moves CSVs to import/done)
-4. **Reconcile**: Validates closing balance matches CSV metadata
+3. **Dry Run**: Validates all transactions have known accounts
+4. **Import**: Imports transactions to the journal (moves CSVs to import/done)
+5. **Reconcile**: Validates closing balance matches CSV metadata
 
 **Important:**
 - All changes remain uncommitted in your working directory

package/docs/tools/import-pipeline.md

@@ -12,8 +12,9 @@ The pipeline automates these sequential steps:
 1a. **Preprocess BTC CSV** _(Revolut only)_ - Add computed columns (fees in BTC, total, clean price) for hledger rules
 1b. **Generate BTC Purchases** _(Revolut only)_ - Cross-reference fiat + BTC CSVs for equity conversion entries
 2. **Account Declarations** - Ensure all accounts exist in year journals
-3. **Import** - Validate transactions, add to journals, move files to done
-4. **Reconcile** - Verify balances match expectations
+3. **Dry Run** - Validate transactions, check for unknown accounts
+4. **Import** - Add transactions to journals, move files to done
+5. **Reconcile** - Verify balances match expectations
 
 Steps 1a and 1b are Revolut-specific and are automatically skipped when no Revolut BTC CSV is present.
 
@@ -48,6 +49,10 @@ When all steps complete successfully:
       "success": true,
       "message": "Account declarations complete"
     },
+    "dryRun": {
+      "success": true,
+      "message": "Dry run complete - all transactions validated"
+    },
     "import": {
       "success": true,
       "message": "Imported 42 transactions"
@@ -81,9 +86,9 @@ When the incoming directory is empty:
 }
 ```
 
-### Failure - Unknown Accounts in Import
+### Failure - Unknown Accounts in Dry Run
 
-When import detects unknown accounts:
+When dry run detects unknown accounts:
 
 ```json
 {
@@ -98,13 +103,13 @@ When import detects unknown accounts:
       "success": true,
       "message": "Account declarations complete"
     },
-    "import": {
+    "dryRun": {
       "success": false,
-      "message": "Import failed: 3 transactions with unknown accounts"
+      "message": "Dry run failed: 3 transactions with unknown accounts"
     }
   },
-  "error": "Import found unknown accounts or errors",
-  "hint": "Add rules to categorize unknown transactions, then retry. See details above for suggestions."
+  "error": "Dry run validation failed: 3 transactions with unknown accounts",
+  "hint": "Update rules file to categorize unknown transactions"
 }
 ```
 
@@ -119,6 +124,7 @@ When reconciliation fails:
   "steps": {
     "classify": { "success": true },
     "accountDeclarations": { "success": true },
+    "dryRun": { "success": true },
     "import": { "success": true, "message": "Imported 42 transactions" },
     "reconcile": {
       "success": false,
@@ -200,17 +206,34 @@ See [classify-statements](classify-statements.md) for details.
 - Multiple years in single CSV
 - Cannot create year journal file
 
-### Step 3: Import
+### Step 3: Dry Run
+
+**Purpose**: Validate all transactions can be categorized before importing
+
+**What happens** (per context):
+
+1. Loads context to find CSV file
+2. Runs `hledger print` with rules file
+3. Checks for `income:unknown` or `expenses:unknown` accounts
+4. Reports unknown postings if found
+
+**Failure scenarios**:
+
+- Unknown accounts detected → **Pipeline stops here**
+- CSV parsing errors
+- Rules file syntax errors
 
-**Purpose**: Validate and add transactions to journal, mark files as processed
+**User action required**: Update rules file to categorize unknown transactions, then re-run pipeline.
+
+### Step 4: Import
+
+**Purpose**: Add transactions to journal and mark files as processed
 
 **What happens** (per context):
 
 1. Loads context to find CSV file
-2. Validates all transactions have known accounts (checks for `income:unknown`/`expenses:unknown`)
-3. If unknown accounts found, generates account suggestions and **stops pipeline**
-4. Imports transactions using `hledger import`
-5. Moves CSV from `pending/` to `done/`
+2. Imports transactions using `hledger import`
+3. Moves CSV from `pending/` to `done/`
 4. Updates context with:
    - `rulesFile` path
    - `yearJournal` path
@@ -219,14 +242,13 @@ See [classify-statements](classify-statements.md) for details.
 
 **Failure scenarios**:
 
-- Unknown accounts detected → **Pipeline stops here** with account suggestions
 - Duplicate transactions detected
 - Journal file write error
 - File move operation fails
 
 See [import-statements](import-statements.md) for details.
 
-### Step 4: Reconcile
+### Step 5: Reconcile
 
 **Purpose**: Verify imported transactions result in correct closing balance
 
@@ -298,7 +320,7 @@ See [reconcile-statement](reconcile-statement.md) for details.
         │                                       │
         ▼                                       │
 ┌────────────────────────────────────────┐      │
-│ STEPS 2-4 (for uuid-1):                │      │
+│ STEPS 2-5 (for uuid-1):                │      │
 │  • Account Declarations                 │      │
 │  • Dry Run                              │      │
 │  • Import                               │      │
@@ -309,9 +331,10 @@ See [reconcile-statement](reconcile-statement.md) for details.
         │                                       │
         │                                       ▼
         │                          ┌────────────────────────────────────────┐
-        │                          │ STEPS 2-4 (for uuid-2):                │
+        │                          │ STEPS 2-5 (for uuid-2):                │
         │                          │  • Account Declarations                 │
-        │                                  │                          │  • Import                               │
+        │                          │  • Dry Run                              │
+        │                          │  • Import                               │
         │                          │  • Reconcile                            │
         │                          │  • UPDATE: .memory/uuid-2.json         │
         │                          └────────────────────────────────────────┘
@@ -330,7 +353,7 @@ The pipeline processes contexts **one at a time**:
 ```
 for each contextId:
   1. Load context
-  2. Run steps 2-4 for this context
+  2. Run steps 2-5 for this context
   3. If ANY step fails → STOP PIPELINE
   4. Update context with results
   5. Move to next context
@@ -394,8 +417,8 @@ classify-statements
 # Output: { "contexts": ["uuid-1", "uuid-2"] }
 
 # Import each manually
-import-statements --contextId "uuid-1"
-import-statements --contextId "uuid-2"
+import-statements --contextId "uuid-1" --checkOnly false
+import-statements --contextId "uuid-2" --checkOnly false
 
 # Reconcile with different balances
 reconcile-statement --contextId "uuid-1" --closingBalance "EUR 1000.00"
@@ -415,12 +438,12 @@ import-pipeline --skipClassify
 ### Scenario 5: Handling Unknown Accounts
 
 ```bash
-# First run: import fails with unknown accounts
+# First run: dry run fails
 import-pipeline
-# Output: "Import found unknown accounts or errors"
+# Output: "Dry run failed: 3 transactions with unknown accounts"
 
-# Check which transactions are unknown (details in pipeline output)
-import-statements --contextId {from-output}
+# Check which transactions are unknown
+import-statements --contextId {from-output} --checkOnly true
 # Shows unknown postings with suggestions
 
 # Update rules file
@@ -439,7 +462,7 @@ import-pipeline --skipClassify
 | ----------------------- | ------------------- | ----------------------------- | --------------------------------------------------- |
 | File collision          | Classify            | Target file already exists    | Move existing file to done or delete                |
 | Unrecognized CSV        | Classify            | Unknown provider              | Add provider config or move to pending manually     |
-| Unknown accounts        | Import              | Transactions without rules    | Update rules file to categorize                     |
+| Unknown accounts        | Dry Run             | Transactions without rules    | Update rules file to categorize                     |
 | Balance mismatch        | Reconcile           | Missing transactions          | Check skip rules, verify all transactions imported  |
 | Context not found       | Import/Reconcile    | Invalid context ID            | Re-run classify-statements                          |
 | Multi-year CSV          | Account Declaration | CSV spans multiple years      | Split CSV by year or import to single year manually |
@@ -458,9 +481,9 @@ The output shows which step failed:
   "steps": {
     "classify": { "success": true },
     "accountDeclarations": { "success": true },
-    "import": { "success": false } // ← Failed here
+    "dryRun": { "success": false } // ← Failed here
   },
-  "error": "Import found unknown accounts or errors..."
+  "error": "Dry run validation failed..."
 }
 ```
 
@@ -471,7 +494,7 @@ The output shows which step failed:
 # contexts: ["abc123-..."]
 
 # Run the failed step individually
-import-statements --contextId "abc123-..."
+import-statements --contextId "abc123-..." --checkOnly true
 ```
 
 **Step 3: Fix issue and resume**
@@ -563,7 +586,7 @@ Context 3: classify → import → reconcile ✓
 The pipeline invokes these tools internally:
 
 1. `classify-statements` → Returns context IDs
-2. `import-statements` (per context) → Validates and imports, updates contexts
+2. `import-statements` (per context) → Updates contexts
 3. `reconcile-statement` (per context) → Updates contexts
 
 ### Manual Tool Usage
@@ -575,8 +598,11 @@ You can run tools independently for more control:
 classify-statements
 # → Get contextIds
 
-import-statements --contextId {uuid}
-# → Validate and import
+import-statements --contextId {uuid} --checkOnly true
+# → Validate first
+
+import-statements --contextId {uuid} --checkOnly false
+# → Import
 
 reconcile-statement --contextId {uuid}
 # → Reconcile
@@ -605,10 +631,11 @@ For typical import (1-2 CSVs, 50-100 transactions each):
 
 - **Classify**: <1 second
 - **Account Declarations**: <1 second
-- **Import**: 1-2 seconds (hledger validation + import)
+- **Dry Run**: 1-2 seconds (hledger processing)
+- **Import**: 1-2 seconds (hledger processing)
 - **Reconcile**: 1-2 seconds (hledger queries)
 
-**Total**: ~3-6 seconds per context
+**Total**: ~5-10 seconds per context
 
 ### Scalability
 
@@ -625,5 +652,5 @@ If you regularly import 50+ CSVs, consider:
 
 - [Import Context Architecture](../architecture/import-context.md) - Deep dive into context system
 - [classify-statements Tool](classify-statements.md) - Step 1: Classification
-- [import-statements Tool](import-statements.md) - Step 3: Import
-- [reconcile-statement Tool](reconcile-statement.md) - Step 4: Reconciliation
+- [import-statements Tool](import-statements.md) - Step 4: Import
+- [reconcile-statement Tool](reconcile-statement.md) - Step 5: Reconciliation

package/package.json

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