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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -202,22 +202,18 @@ your-project/
202
202
 
203
203
  #### Workflow
204
204
 
205
- The `import-pipeline` tool provides an atomic, safe import workflow using git worktrees:
205
+ The `import-pipeline` tool operates directly on the working directory:
206
206
 
207
207
  1. Drop CSV files into `{paths.import}` (default: `import/incoming/`)
208
- 2. Run `import-pipeline` tool with optional provider/currency filters
208
+ 2. Run `import-pipeline` tool
209
209
  3. The tool automatically:
210
- - Creates an isolated git worktree
211
- - Syncs CSV files from main repo to worktree
212
- - Classifies CSV files by provider/currency
210
+ - Classifies CSV files by provider/currency (creates import contexts in `.memory/`)
213
211
  - Extracts accounts from rules and creates declarations in year journal
214
212
  - Validates all transactions have matching rules
215
213
  - Imports transactions to the appropriate year journal
216
214
  - Reconciles closing balance (auto-detected from CSV metadata or data analysis)
217
- - Merges changes back to main branch with `--no-ff`
218
- - Deletes processed CSV files from main repo's import/incoming
219
- - Cleans up the worktree
220
- 4. If any step fails, the worktree is discarded and main branch remains untouched (CSV files are preserved for retry)
215
+ - CSV files move: `incoming/` `pending/` `done/`
216
+ 4. All changes remain uncommitted for inspection. If any step fails, partially processed files remain in place for debugging
221
217
 
222
218
  ### Statement Import
223
219
 
@@ -82,71 +82,23 @@ Bash is FORBIDDEN for:
82
82
 
83
83
  **IMPORTANT:** You MUST use `import-pipeline` for statement imports. Do NOT edit journals manually, run `hledger import` directly, or move files with bash commands.
84
84
 
85
- The `import-pipeline` tool provides an **atomic, safe workflow** using git worktrees:
85
+ The `import-pipeline` tool operates directly on the working directory:
86
86
 
87
87
  1. **Prepare**: Drop CSV files into `{paths.import}` (configured in `config/import/providers.yaml`, default: `import/incoming`)
88
- 2. **Run Pipeline**: Execute `import-pipeline` (optionally filter by `provider` and `currency`)
89
- 3. **Automatic Processing**: The tool creates an isolated git worktree and:
90
- - Syncs CSV files from main repo to worktree
91
- - Classifies CSV files by provider/currency
88
+ 2. **Run Pipeline**: Execute `import-pipeline`
89
+ 3. **Automatic Processing**: The tool:
90
+ - Classifies CSV files by provider/currency (creates import contexts in `.memory/`)
92
91
  - Extracts required accounts from rules files and updates year journal
93
- - Validates all transactions have matching rules
92
+ - Validates all transactions have matching rules (dry run)
94
93
  - Imports transactions to the appropriate year journal
95
94
  - Reconciles closing balance (auto-detected from CSV metadata or data, or manual override)
96
- - Merges changes back to main branch with `--no-ff`
97
- - Deletes processed CSV files from main repo's import/incoming
98
- - Cleans up the worktree
99
- 4. **Handle Failures**: If any step fails (e.g., unknown postings found):
100
- - Worktree is preserved by default at `/tmp/import-worktree-<uuid>` for debugging
101
- - Main branch remains untouched
95
+ - CSV files move: `incoming/` `pending/` `done/`
96
+ 4. **After Pipeline**: All changes remain uncommitted in your working directory for inspection
97
+ 5. **Handle Failures**: If any step fails (e.g., unknown postings found):
98
+ - Changes remain in place for inspection (partially processed files stay in `pending/`)
102
99
  - Review error output for unknown postings with full CSV row data
103
100
  - Update rules file with `if` directives to match the transaction
104
- - Re-run `import-pipeline`
105
-
106
- ### Error Recovery and Worktree Preservation
107
-
108
- **Default Behavior:**
109
-
110
- - On success: Worktrees are automatically cleaned up
111
- - On error: Worktrees are preserved in `/tmp/import-worktree-<uuid>` for debugging
112
- - Worktrees in `/tmp` are automatically cleaned up on system reboot
113
-
114
- **Manual Recovery from Failed Import:**
115
-
116
- If an import fails and the worktree is preserved, you can:
117
-
118
- 1. **Inspect the worktree:**
119
-
120
- ```bash
121
- cd /tmp/import-worktree-<uuid>
122
- hledger check # Validate journal
123
- hledger balance # Check balances
124
- cat ledger/2026.journal # View imported transactions
125
- ```
126
-
127
- 2. **Continue the import manually:**
128
-
129
- ```bash
130
- cd /tmp/import-worktree-<uuid>
131
- # Fix any issues (edit rules, fix transactions, etc.)
132
- git add .
133
- git commit -m "Fix import issues"
134
- git checkout main
135
- git merge --no-ff import-<uuid>
136
- ```
137
-
138
- 3. **Clean up when done:**
139
-
140
- ```bash
141
- git worktree remove /tmp/import-worktree-<uuid>
142
- ```
143
-
144
- 4. **Or use the cleanup tool:**
145
- ```bash
146
- cleanup-worktrees # Removes worktrees >24h old
147
- cleanup-worktrees --all true # Removes all import worktrees
148
- cleanup-worktrees --dryRun true # Preview without removing
149
- ```
101
+ - Re-run `import-pipeline` (use `--skipClassify true` if files are already classified)
150
102
 
151
103
  **Logs:**
152
104
 
@@ -155,13 +107,6 @@ If an import fails and the worktree is preserved, you can:
155
107
  - Log path is included in import-pipeline output
156
108
  - Review the log to understand what failed and why
157
109
 
158
- **Force Cleanup on Error:**
159
- If you prefer the old behavior (always cleanup, even on error):
160
-
161
- ```bash
162
- import-pipeline --keepWorktreeOnError false
163
- ```
164
-
165
110
  ### Rules Files
166
111
 
167
112
  - The location of the rules files is configured in `config/import/providers.yaml`
@@ -196,44 +141,39 @@ The following are MCP tools available to you. Always call these tools directly -
196
141
 
197
142
  ### import-pipeline
198
143
 
199
- **Purpose:** Atomic import workflow that classifies, validates, imports, and reconciles bank statements.
144
+ **Purpose:** Import workflow that classifies, validates, imports, and reconciles bank statements.
200
145
 
201
146
  **Usage:**
202
147
 
203
148
  - Basic: `import-pipeline()`
204
- - Filtered: `import-pipeline(provider: "ubs", currency: "chf")`
205
- - With manual closing balance: `import-pipeline(provider: "revolut", closingBalance: "CHF 1234.56")`
149
+ - With manual closing balance: `import-pipeline(closingBalance: "CHF 1234.56")`
206
150
  - Skip classification: `import-pipeline(skipClassify: true)` (if files already classified)
207
151
 
208
152
  **Arguments:**
209
153
 
210
- | Argument | Type | Default | Description |
211
- | ---------------- | ------- | ------- | -------------------------------------------------- |
212
- | `provider` | string | - | Filter by provider (e.g., `revolut`, `ubs`) |
213
- | `currency` | string | - | Filter by currency (e.g., `chf`, `eur`) |
214
- | `skipClassify` | boolean | `false` | Skip classification step |
215
- | `closingBalance` | string | - | Manual closing balance for reconciliation |
216
- | `account` | string | - | Manual account override (auto-detected from rules) |
154
+ | Argument | Type | Default | Description |
155
+ | ---------------- | ------- | ------- | ------------------------------------------------------------------------------ |
156
+ | `provider` | string | - | Logger metadata (does not filter CSV selection — use classify step for that) |
157
+ | `currency` | string | - | Logger metadata (does not filter CSV selection — use classify step for that) |
158
+ | `skipClassify` | boolean | `false` | Skip classification step |
159
+ | `closingBalance` | string | - | Manual closing balance for reconciliation |
160
+ | `account` | string | - | Manual account override (auto-detected from rules) |
217
161
 
218
162
  **Behavior:**
219
163
 
220
- 1. Creates isolated git worktree
221
- 2. Syncs CSV files from main repo to worktree
222
- 3. Classifies CSV files (unless `skipClassify: true`)
223
- 4. Extracts accounts from matched rules and updates year journal with declarations
224
- 5. Validates all transactions have matching rules (dry run)
225
- 6. Imports transactions to year journal
226
- 7. Reconciles closing balance (auto-detected from CSV metadata/data or manual override)
227
- 8. Merges to main with `--no-ff` commit
228
- 9. Deletes processed CSV files from main repo's import/incoming
229
- 10. Cleans up worktree
164
+ 1. Classifies CSV files and creates import contexts (unless `skipClassify: true`)
165
+ 2. For each context (sequentially, fail-fast):
166
+ - Extracts accounts from matched rules and updates year journal with declarations
167
+ - Validates all transactions have matching rules (dry run)
168
+ - Imports transactions to year journal, moves CSV from `pending/` to `done/`
169
+ - Reconciles closing balance (auto-detected from CSV metadata/data or manual override)
170
+ 3. All changes remain uncommitted in the working directory
230
171
 
231
172
  **Output:** Returns step-by-step results with success/failure for each phase
232
173
 
233
174
  **On Failure:**
234
175
 
235
- - Worktree is discarded automatically
236
- - Main branch remains untouched
176
+ - Changes remain in place for inspection
237
177
  - Error details include unknown postings with full CSV row data
238
178
  - Fix rules and re-run the pipeline
239
179