@dizzlkheinz/ynab-mcpb 0.15.1 → 0.16.1

package/docs/plans/2025-11-20-reloadable-config-token-validation.md

@@ -1,93 +0,0 @@
-# Reloadable Config & Token Validation Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Make config parsing reloadable for env-mutation tests/CI, harden token validation against malformed responses, and confirm integration runs with a valid YNAB token.
-
-**Architecture:** Parse env vars on-demand via `loadConfig()` (with a backward-compatible `config` singleton), inject per-server config instances instead of module globals, and wrap YNAB token validation failures (including non-JSON responses) into `AuthenticationError` with clear messaging.
-
-**Tech Stack:** Node + TypeScript, Zod, dotenv, Vitest, YNAB SDK, esbuild.
-
-### Task 1: Reloadable config loader
-
-**Files:**
-- Modify: `src/server/config.ts`
-- Modify: `src/server/__tests__/config.test.ts`
-
-**Step 1: Write failing test**  
-Add a test that calls `loadConfig()` twice after mutating `process.env.YNAB_ACCESS_TOKEN` (without re-importing the module) and expects the second call to return the updated token.
-
-**Step 2: Run test to verify failure**  
-Run `npx vitest run src/server/__tests__/config.test.ts` and confirm the new test fails because the loader is still tied to initial state.
-
-**Step 3: Implement reloadable loader**  
-Keep the Zod schema and explicit `config` singleton, but ensure `loadConfig()` re-parses `process.env` on every call (optionally allowing an env override for tests) and throws `ValidationError` on failure; keep `import 'dotenv/config'` so `.env` is loaded for Node execution.
-
-**Step 4: Re-run targeted test**  
-Re-run `npx vitest run src/server/__tests__/config.test.ts` to confirm the reloadable behavior passes.
-
-### Task 2: Inject per-instance config into YNABMCPServer
-
-**Files:**
-- Modify: `src/server/YNABMCPServer.ts`
-- Modify: `src/server/__tests__/YNABMCPServer.test.ts`
-- Modify: `src/server/__tests__/server-startup.integration.test.ts`
-
-**Step 1: Add/adjust tests**  
-Add coverage that changing `process.env.YNAB_ACCESS_TOKEN` before constructing a new `YNABMCPServer` produces a server wired to the new token (no module cache reset), and update expectations to align with `ValidationError` from `loadConfig()` where appropriate.
-
-**Step 2: Run tests to see failures**  
-Run `npx vitest run src/server/__tests__/YNABMCPServer.test.ts src/server/__tests__/server-startup.integration.test.ts`.
-
-**Step 3: Apply code changes**  
-Ensure the constructor stores `const configInstance = loadConfig()` and uses it for YNAB API creation, token validation, and tool execution auth; remove any lingering usage of the `config` singleton for runtime behavior.
-
-**Step 4: Re-run the affected tests**  
-Re-run the same Vitest targets to verify per-instance config wiring passes.
-
-### Task 3: Token validation resilience
-
-**Files:**
-- Modify: `src/server/YNABMCPServer.ts`
-- Modify: `src/server/__tests__/server-startup.integration.test.ts`
-
-**Step 1: Write failing test**  
-Mock `ynab.API().user.getUser` to reject with a `SyntaxError`/HTML-shaped error and expect `validateToken()` to reject with `AuthenticationError("Unexpected response from YNAB during token validation")` instead of surfacing the raw syntax failure.
-
-**Step 2: Run test to confirm failure**  
-Run `npx vitest run src/server/__tests__/server-startup.integration.test.ts`.
-
-**Step 3: Implement graceful handling**  
-Wrap token validation to catch non-JSON/SyntaxError cases (or responses lacking expected shape) and throw `AuthenticationError` with the clear message while preserving existing 401/403 mapping.
-
-**Step 4: Re-run validation tests**  
-Re-run the targeted integration test to ensure the new mapping passes.
-
-### Task 4: Test alignment & runner portability
-
-**Files:**
-- Modify: `src/server/__tests__/config.test.ts`
-- Modify: `scripts/run-throttled-integration-tests.js`
-
-**Step 1: Align config test patterns**  
-Update any assertions relying on module-level parsing side effects to use `vi.resetModules()` + `loadConfig()` explicitly for reload checks; keep singleton expectations where intentional.
-
-**Step 2: Harden integration runner on Windows**  
-Change the throttled runner to spawn Vitest via a platform-portable path (e.g., `node` + resolved `vitest` bin) to avoid `spawn EINVAL` with `.cmd` on Windows.
-
-**Step 3: Run quick smoke**  
-Run `node scripts/run-throttled-integration-tests.js --help` or kick a single file to ensure the wrapper executes without path errors.
-
-### Task 5: Full verification
-
-**Files/Commands:**
-- Commands: `npm test`, `npm run test:integration:core` (with `YNAB_ACCESS_TOKEN` set), optionally `npm run test:integration:domain`.
-
-**Step 1: Run unit suite**  
-Execute `npm test` to ensure unit coverage stays green.
-
-**Step 2: Run core integrations with real token**  
-Execute `npm run test:integration:core` using a known-good `YNAB_ACCESS_TOKEN`; capture any regressions.
-
-**Step 3: Optional extended coverage**  
-If time permits, run `npm run test:integration:domain` for broader confidence; note any skips or rate-limit impacts.

package/docs/plans/2025-11-21-fix-transaction-cached-property.md

@@ -1,362 +0,0 @@
-# Fix Missing `cached` Property in Large Transaction Responses
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Fix GitHub Action test failure by adding the missing `cached` property to large transaction list responses.
-
-**Architecture:** The `handleListTransactions` function in `transactionTools.ts` has two response paths: normal (lines 815+) and large response (lines 788-812). The large response path is missing the `cached` and `cache_info` properties that the normal path includes, causing test assertion failures when transaction data exceeds 90KB.
-
-**Tech Stack:** TypeScript, Vitest, YNAB API integration tests
-
----
-
-## Background
-
-**Current Issue:**
-- GitHub Action failing: `src/tools/__tests__/accountTools.delta.integration.test.ts:94`
-- Error: `expected undefined to be false // Object.is equality`
-- Test code: `expect(firstPayload.cached).toBe(false);`
-
-**Root Cause:**
-File `src/tools/transactionTools.ts` has two response code paths:
-1. **Large response path** (lines 788-812): When transactions > 90KB, returns preview + summary
-2. **Normal path** (lines 815+): Returns full transaction list
-
-The large response path returns an object WITHOUT the `cached` property.
-The normal path returns an object WITH `cached: cacheHit` and `cache_info`.
-
-**Test accounts with many transactions trigger the large response path, causing `cached` to be undefined.**
-
----
-
-## Task 1: Add Unit Test Coverage for Large Response Path
-
-**Files:**
-- Read: `src/tools/__tests__/transactionTools.test.ts`
-- Modify: `src/tools/__tests__/transactionTools.test.ts` (add test after existing tests)
-
-**Step 1: Read the existing test file to understand patterns**
-
-```bash
-cat src/tools/__tests__/transactionTools.test.ts | head -100
-```
-
-Expected: See test structure, mocking patterns, imports
-
-**Step 2: Write failing test for large response cached property**
-
-Add this test to `src/tools/__tests__/transactionTools.test.ts` in the appropriate describe block:
-
-```typescript
-it('should include cached property in large response path', async () => {
-  // Create large transaction list (> 90KB)
-  const largeTransactionList: ynab.TransactionDetail[] = [];
-  for (let i = 0; i < 5000; i++) {
-    largeTransactionList.push({
-      id: `transaction-${i}`,
-      date: '2025-01-01',
-      amount: -10000,
-      memo: 'Test transaction with long memo to increase size '.repeat(10),
-      cleared: 'cleared',
-      approved: true,
-      flag_color: null,
-      account_id: 'test-account',
-      payee_id: null,
-      category_id: null,
-      transfer_account_id: null,
-      transfer_transaction_id: null,
-      matched_transaction_id: null,
-      import_id: null,
-      import_payee_name: null,
-      import_payee_name_original: null,
-      debt_transaction_type: null,
-      deleted: false,
-      account_name: 'Test Account',
-      payee_name: 'Test Payee',
-      category_name: 'Test Category',
-      subtransactions: [],
-    } as ynab.TransactionDetail);
-  }
-
-  const mockDeltaFetcher = {
-    fetchTransactionsByAccount: vi.fn().mockResolvedValue({
-      data: largeTransactionList,
-      wasCached: false,
-      usedDelta: false,
-    }),
-  } as unknown as DeltaFetcher;
-
-  const result = await handleListTransactions(mockYnabAPI, mockDeltaFetcher, {
-    budget_id: 'test-budget',
-    account_id: 'test-account',
-  });
-
-  const content = result.content?.[0];
-  expect(content).toBeDefined();
-  expect(content?.type).toBe('text');
-
-  const parsedResponse = JSON.parse(content!.text);
-
-  // Should have cached property even in large response path
-  expect(parsedResponse.cached).toBeDefined();
-  expect(parsedResponse.cached).toBe(false);
-  expect(parsedResponse.cache_info).toBeDefined();
-});
-```
-
-**Step 3: Run the test to verify it fails**
-
-```bash
-npm run test:unit -- src/tools/__tests__/transactionTools.test.ts -t "should include cached property in large response path"
-```
-
-Expected: FAIL with error about `cached` being undefined
-
-**Step 4: Commit the failing test**
-
-```bash
-git add src/tools/__tests__/transactionTools.test.ts
-git commit -m "test: add failing test for cached property in large transaction responses"
-```
-
----
-
-## Task 2: Fix Large Response Path to Include Cached Property
-
-**Files:**
-- Modify: `src/tools/transactionTools.ts:788-812`
-
-**Step 1: Read the current large response code**
-
-```bash
-cat src/tools/transactionTools.ts | sed -n '788,812p'
-```
-
-Expected: See the current implementation missing `cached` and `cache_info`
-
-**Step 2: Add cached properties to large response**
-
-In `src/tools/transactionTools.ts`, replace lines 788-812 with:
-
-```typescript
-      if (estimatedSize > sizeLimit) {
-        // Return summary and suggest export
-        const preview = transactions.slice(0, 50);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: responseFormatter.format({
-                message: `Found ${transactions.length} transactions (${Math.round(estimatedSize / 1024)}KB). Too large to display all.`,
-                suggestion: "Use 'export_transactions' tool to save all transactions to a file.",
-                showing: `First ${preview.length} transactions:`,
-                total_count: transactions.length,
-                estimated_size_kb: Math.round(estimatedSize / 1024),
-                cached: cacheHit,
-                cache_info: cacheHit
-                  ? `Data retrieved from cache for improved performance${usedDelta ? ' (delta merge applied)' : ''}`
-                  : 'Fresh data retrieved from YNAB API',
-                preview_transactions: preview.map((transaction) => ({
-                  id: transaction.id,
-                  date: transaction.date,
-                  amount: milliunitsToAmount(transaction.amount),
-                  memo: transaction.memo,
-                  payee_name: transaction.payee_name,
-                  category_name: transaction.category_name,
-                })),
-              }),
-            },
-          ],
-        };
-      }
-```
-
-**Changes:**
-- Added `cached: cacheHit,` after `estimated_size_kb`
-- Added `cache_info` with same pattern as normal response path
-
-**Step 3: Run unit tests to verify fix**
-
-```bash
-npm run test:unit -- src/tools/__tests__/transactionTools.test.ts -t "should include cached property in large response path"
-```
-
-Expected: PASS
-
-**Step 4: Run all transaction tool tests**
-
-```bash
-npm run test:unit -- src/tools/__tests__/transactionTools.test.ts
-```
-
-Expected: All tests PASS
-
-**Step 5: Commit the fix**
-
-```bash
-git add src/tools/transactionTools.ts
-git commit -m "fix: add cached property to large transaction response path
-
-- Large responses (>90KB) now include cached and cache_info properties
-- Maintains consistency with normal response path
-- Fixes test failure in delta integration tests"
-```
-
----
-
-## Task 3: Verify Integration Test Now Passes
-
-**Files:**
-- Test: `src/tools/__tests__/accountTools.delta.integration.test.ts`
-
-**Step 1: Run the failing integration test locally**
-
-```bash
-npm run test:integration -- src/tools/__tests__/accountTools.delta.integration.test.ts -t "reports delta usage for list_transactions after a change"
-```
-
-Expected: PASS (requires YNAB_ACCESS_TOKEN environment variable)
-
-Note: If you don't have a YNAB token or want to skip, this is acceptable - the GitHub Action will verify.
-
-**Step 2: Run type checking**
-
-```bash
-npm run type-check
-```
-
-Expected: No TypeScript errors
-
-**Step 3: Run all unit tests to ensure no regressions**
-
-```bash
-npm run test:unit
-```
-
-Expected: All tests PASS
-
-**Step 4: Commit verification checkpoint**
-
-```bash
-git add -A
-git commit -m "test: verify integration test passes with cached property fix"
-```
-
----
-
-## Task 4: Update CHANGELOG and Documentation
-
-**Files:**
-- Modify: `CHANGELOG.md` (add entry at top of Unreleased section)
-
-**Step 1: Add CHANGELOG entry**
-
-Add this entry to the `## [Unreleased]` section in `CHANGELOG.md`:
-
-```markdown
-### Fixed
-- Fixed missing `cached` property in large transaction list responses (>90KB)
-  - Large response path now includes `cached` and `cache_info` properties
-  - Maintains consistency with normal response path
-  - Resolves integration test failures when accounts have many transactions
-```
-
-**Step 2: Commit documentation**
-
-```bash
-git add CHANGELOG.md
-git commit -m "docs: add CHANGELOG entry for cached property fix"
-```
-
----
-
-## Task 5: Push and Verify GitHub Action
-
-**Files:**
-- Remote: GitHub Actions CI
-
-**Step 1: Push all commits to remote**
-
-```bash
-git push origin HEAD
-```
-
-Expected: Push successful
-
-**Step 2: Monitor GitHub Action**
-
-```bash
-gh run watch
-```
-
-Expected:
-- Job `unit-tests` should PASS
-- Job `integration-core` should PASS (was previously failing at accountTools.delta.integration.test.ts)
-
-**Step 3: Verify specific test that was failing**
-
-Check GitHub Action logs for:
-```
-✓ src/tools/__tests__/accountTools.delta.integration.test.ts > Delta-backed account tool handlers > reports delta usage for list_transactions after a change
-```
-
-Expected: Green checkmark, no assertion errors
-
-**Step 4: Create completion summary**
-
-Document verification results:
-```markdown
-## Verification Complete
-
-- ✅ Unit tests passing locally
-- ✅ Integration tests passing locally (if run)
-- ✅ Type checking passing
-- ✅ GitHub Actions CI passing
-- ✅ Specific failing test now passes
-
-The `cached` property is now consistently included in all transaction list responses.
-```
-
----
-
-## Testing Strategy
-
-**Unit Tests:**
-- New test verifies large response path includes `cached` property
-- Existing tests verify normal response path unchanged
-
-**Integration Tests:**
-- `accountTools.delta.integration.test.ts` verifies delta fetcher integration
-- Test creates real transaction, expects `cached: false` on first call
-- Was failing because large accounts returned `cached: undefined`
-
-**Manual Verification:**
-- GitHub Action will run full integration suite with real YNAB API
-- Throttled test runner prevents rate limit issues
-- Sequential execution ensures reliable results
-
----
-
-## Rate Limiting Context (For Reference)
-
-**Note:** The GitHub Action failure was NOT a rate limiting issue. The codebase already has excellent rate limiting:
-
-**Existing Rate Limit Infrastructure:**
-- `scripts/run-throttled-integration-tests.js` - Sequential test execution with request tracking
-- Client-side throttling (200 req/hour with 20 req buffer)
-- Request history pruning (60-minute sliding window)
-- Intelligent wait logic with min/max bounds
-- Per-test estimated API call counts
-
-**No changes needed to rate limiting.** The issue was purely a missing property in the response object.
-
----
-
-## Success Criteria
-
-- ✅ Unit test passes for large response cached property
-- ✅ Integration test `accountTools.delta.integration.test.ts:94` passes
-- ✅ GitHub Action CI pipeline passes completely
-- ✅ No TypeScript errors
-- ✅ CHANGELOG updated
-- ✅ All commits follow conventional commit format

package/docs/plans/2025-11-21-reconciliation-error-handling.md

@@ -1,90 +0,0 @@
-# Reconciliation Error Handling Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Fix reconciliation integration failures by properly surfacing YNAB API errors (invalid accounts, rate limits) so tests skip or fail appropriately instead of silently returning zero creations.
-
-**Architecture:** Add a small error-normalization layer inside the reconciliation executor to interpret YNAB SDK error payloads, propagate fatal conditions (429/invalid account) as errors, and include actionable reasons in action logs for rate-limit detection. Keep bulk/sequential creation flow intact while improving error transparency.
-
-**Tech Stack:** TypeScript, Vitest, YNAB SDK, Node 22+
-
-### Task 1: Normalize YNAB API errors
-
-**Files:**
-- Modify: `src/tools/reconciliation/executor.ts`
-- Test: `src/tools/reconciliation/__tests__/executor.test.ts`
-
-**Step 1: Add error normalization utilities**
-
-```ts
-// executor.ts (near helper section)
-interface NormalizedYnabError { status?: number; name?: string; message: string; detail?: string }
-function normalizeYnabError(err: unknown): NormalizedYnabError { /* parse err.error.id/detail/status, strings, Error */ }
-function shouldPropagateYnabError(err: NormalizedYnabError): boolean { return [401, 403, 404, 429, 500].includes(err.status ?? 0); }
-function attachStatus(err: NormalizedYnabError): Error { const e = new Error(err.message || err.detail || 'YNAB API error'); if (err.status) (e as any).status = err.status; if (err.name) e.name = err.name; return e; }
-```
-
-**Step 2: Use normalized errors in bulk chunk handling**
-
-```ts
-// executor.ts processBulkChunk catch
-const ynabErr = normalizeYnabError(error);
-if (shouldPropagateYnabError(ynabErr)) throw attachStatus(ynabErr);
-const reason = ynabErr.message;
-bulkOperationDetails.bulk_chunk_failures += 1;
-actions_taken.push({ type: 'bulk_create_fallback', reason: `Bulk chunk #${chunkIndex} failed (${reason})...` });
-```
-
-Expected: rate-limit or invalid-account errors now bubble; other bulk failures still fall back.
-
-### Task 2: Propagate fatal errors during sequential creation
-
-**Files:**
-- Modify: `src/tools/reconciliation/executor.ts`
-- Test: `src/tools/reconciliation/__tests__/executor.integration.test.ts`
-
-**Step 1: Update sequential catch block**
-
-```ts
-const ynabErr = normalizeYnabError(error);
-const failureReason = ynabErr.message;
-actions_taken.push({ type: 'create_transaction_failed', reason: ...failureReason... });
-if (shouldPropagateYnabError(ynabErr)) throw attachStatus(ynabErr);
-```
-
-Include status-aware message so `containsRateLimitFailure` sees 429 text.
-
-**Step 2: Ensure transaction failure counters reflect thrown errors**
-
-If fatal error occurs, increment `transaction_failures` before throw to preserve metrics.
-
-### Task 3: Cover new error handling with tests
-
-**Files:**
-- Modify: `src/tools/reconciliation/__tests__/executor.test.ts`
-- Modify: `src/tools/reconciliation/__tests__/executor.integration.test.ts` (if needed for assertions/fixtures)
-
-**Step 1: Add unit tests for non-Error YNAB payload**
-
-```ts
-it('propagates rate-limit error objects with status codes', async () => {
-  mockCreateTransactions.rejects({ error: { id: '429', detail: 'Too many requests' } });
-  await expect(executeReconciliation(...)).rejects.toMatchObject({ status: 429 });
-});
-```
-
-**Step 2: Add unit test for invalid account error propagation**
-
-Mock 404 payload and expect rejection; verify action reason contains detail when not thrown.
-
-**Step 3: Adjust integration expectation if fixtures rely on new messaging**
-
-Ensure `containsRateLimitFailure` continues to match updated reason text (no code changes anticipated).
-
-### Task 4: Verify fixes locally
-
-**Commands:**
-- `npx vitest run --project unit --runInBand src/tools/reconciliation/__tests__/executor.test.ts`
-- `npm run test:integration:core -- --testNamePattern="Reconciliation Executor - Bulk Create Integration"` (rerun the failing suite)
-
-Expected: unit tests pass; integration suite either passes or rate-limit skips instead of failing counts.