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

package/README.md

@@ -202,18 +202,22 @@ your-project/
 
 #### Workflow
 
-The `import-pipeline` tool operates directly on the working directory:
+The `import-pipeline` tool provides an atomic, safe import workflow using git worktrees:
 
 1. Drop CSV files into `{paths.import}` (default: `import/incoming/`)
-2. Run `import-pipeline` tool
+2. Run `import-pipeline` tool with optional provider/currency filters
 3. The tool automatically:
-   - Classifies CSV files by provider/currency (creates import contexts in `.memory/`)
+   - Creates an isolated git worktree
+   - Syncs CSV files from main repo to worktree
+   - Classifies CSV files by provider/currency
    - Extracts accounts from rules and creates declarations in year journal
    - Validates all transactions have matching rules
    - Imports transactions to the appropriate year journal
    - Reconciles closing balance (auto-detected from CSV metadata or data analysis)
-   - CSV files move: `incoming/` → `pending/` → `done/`
-4. All changes remain uncommitted for inspection. If any step fails, partially processed files remain in place for debugging
+   - Merges changes back to main branch with `--no-ff`
+   - Deletes processed CSV files from main repo's import/incoming
+   - Cleans up the worktree
+4. If any step fails, the worktree is discarded and main branch remains untouched (CSV files are preserved for retry)
 
 ### Statement Import
 

package/agent/accountant.md

@@ -82,23 +82,71 @@ Bash is FORBIDDEN for:
 
 **IMPORTANT:** You MUST use `import-pipeline` for statement imports. Do NOT edit journals manually, run `hledger import` directly, or move files with bash commands.
 
-The `import-pipeline` tool operates directly on the working directory:
+The `import-pipeline` tool provides an **atomic, safe workflow** using git worktrees:
 
 1. **Prepare**: Drop CSV files into `{paths.import}` (configured in `config/import/providers.yaml`, default: `import/incoming`)
-2. **Run Pipeline**: Execute `import-pipeline`
-3. **Automatic Processing**: The tool:
-   - Classifies CSV files by provider/currency (creates import contexts in `.memory/`)
+2. **Run Pipeline**: Execute `import-pipeline` (optionally filter by `provider` and `currency`)
+3. **Automatic Processing**: The tool creates an isolated git worktree and:
+   - Syncs CSV files from main repo to worktree
+   - Classifies CSV files by provider/currency
    - Extracts required accounts from rules files and updates year journal
-   - Validates all transactions have matching rules (dry run)
+   - Validates all transactions have matching rules
    - 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
-5. **Handle Failures**: If any step fails (e.g., unknown postings found):
-   - Changes remain in place for inspection (partially processed files stay in `pending/`)
+   - Merges changes back to main branch with `--no-ff`
+   - Deletes processed CSV files from main repo's import/incoming
+   - Cleans up the worktree
+4. **Handle Failures**: If any step fails (e.g., unknown postings found):
+   - Worktree is preserved by default at `/tmp/import-worktree-<uuid>` for debugging
+   - Main branch remains untouched
    - Review error output for unknown postings with full CSV row data
    - Update rules file with `if` directives to match the transaction
-   - Re-run `import-pipeline` (use `--skipClassify true` if files are already classified)
+   - Re-run `import-pipeline`
+
+### Error Recovery and Worktree Preservation
+
+**Default Behavior:**
+
+- On success: Worktrees are automatically cleaned up
+- On error: Worktrees are preserved in `/tmp/import-worktree-<uuid>` for debugging
+- Worktrees in `/tmp` are automatically cleaned up on system reboot
+
+**Manual Recovery from Failed Import:**
+
+If an import fails and the worktree is preserved, you can:
+
+1. **Inspect the worktree:**
+
+   ```bash
+   cd /tmp/import-worktree-<uuid>
+   hledger check                    # Validate journal
+   hledger balance                   # Check balances
+   cat ledger/2026.journal           # View imported transactions
+   ```
+
+2. **Continue the import manually:**
+
+   ```bash
+   cd /tmp/import-worktree-<uuid>
+   # Fix any issues (edit rules, fix transactions, etc.)
+   git add .
+   git commit -m "Fix import issues"
+   git checkout main
+   git merge --no-ff import-<uuid>
+   ```
+
+3. **Clean up when done:**
+
+   ```bash
+   git worktree remove /tmp/import-worktree-<uuid>
+   ```
+
+4. **Or use the cleanup tool:**
+   ```bash
+   cleanup-worktrees                 # Removes worktrees >24h old
+   cleanup-worktrees --all true      # Removes all import worktrees
+   cleanup-worktrees --dryRun true   # Preview without removing
+   ```
 
 **Logs:**
 
@@ -107,6 +155,13 @@ The `import-pipeline` tool operates directly on the working directory:
 - Log path is included in import-pipeline output
 - Review the log to understand what failed and why
 
+**Force Cleanup on Error:**
+If you prefer the old behavior (always cleanup, even on error):
+
+```bash
+import-pipeline --keepWorktreeOnError false
+```
+
 ### Rules Files
 
 - The location of the rules files is configured in `config/import/providers.yaml`
@@ -141,39 +196,44 @@ The following are MCP tools available to you. Always call these tools directly -
 
 ### import-pipeline
 
-**Purpose:** Import workflow that classifies, validates, imports, and reconciles bank statements.
+**Purpose:** Atomic import workflow that classifies, validates, imports, and reconciles bank statements.
 
 **Usage:**
 
 - Basic: `import-pipeline()`
-- With manual closing balance: `import-pipeline(closingBalance: "CHF 1234.56")`
+- Filtered: `import-pipeline(provider: "ubs", currency: "chf")`
+- With manual closing balance: `import-pipeline(provider: "revolut", closingBalance: "CHF 1234.56")`
 - Skip classification: `import-pipeline(skipClassify: true)` (if files already classified)
 
 **Arguments:**
 
-| Argument         | Type    | Default | Description                                                                    |
-| ---------------- | ------- | ------- | ------------------------------------------------------------------------------ |
-| `provider`       | string  | -       | Logger metadata (does not filter CSV selection — use classify step for that)    |
-| `currency`       | string  | -       | Logger metadata (does not filter CSV selection — use classify step for that)    |
-| `skipClassify`   | boolean | `false` | Skip classification step                                                       |
-| `closingBalance` | string  | -       | Manual closing balance for reconciliation                                      |
-| `account`        | string  | -       | Manual account override (auto-detected from rules)                             |
+| Argument         | Type    | Default | Description                                        |
+| ---------------- | ------- | ------- | -------------------------------------------------- |
+| `provider`       | string  | -       | Filter by provider (e.g., `revolut`, `ubs`)        |
+| `currency`       | string  | -       | Filter by currency (e.g., `chf`, `eur`)            |
+| `skipClassify`   | boolean | `false` | Skip classification step                           |
+| `closingBalance` | string  | -       | Manual closing balance for reconciliation          |
+| `account`        | string  | -       | Manual account override (auto-detected from rules) |
 
 **Behavior:**
 
-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 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
+1. Creates isolated git worktree
+2. Syncs CSV files from main repo to worktree
+3. Classifies CSV files (unless `skipClassify: true`)
+4. Extracts accounts from matched rules and updates year journal with declarations
+5. Validates all transactions have matching rules (dry run)
+6. Imports transactions to year journal
+7. Reconciles closing balance (auto-detected from CSV metadata/data or manual override)
+8. Merges to main with `--no-ff` commit
+9. Deletes processed CSV files from main repo's import/incoming
+10. Cleans up worktree
 
 **Output:** Returns step-by-step results with success/failure for each phase
 
 **On Failure:**
 
-- Changes remain in place for inspection
+- Worktree is discarded automatically
+- Main branch remains untouched
 - Error details include unknown postings with full CSV row data
 - Fix rules and re-run the pipeline