@dizzlkheinz/ynab-mcpb 0.12.2 → 0.15.0

package/docs/guides/ARCHITECTURE.md

@@ -1,24 +1,23 @@
 # YNAB MCP Server Architecture
 
-This guide explains the v0.8.x modular architecture, core components, and architectural patterns.
+This guide explains the modular architecture, core components, and architectural patterns.
 
 ## Table of Contents
 
-- [v0.8.x Modular Architecture](#v08x-modular-architecture)
+- [Modular Architecture](#modular-architecture)
 - [Core Components](#core-components)
 - [Dependency Injection Pattern](#dependency-injection-pattern)
-- [Developing Tools with v0.8.x](#developing-tools-with-v08x)
+- [Developing Tools](#developing-tools)
 - [Cache Management](#cache-management)
 - [Service Module Patterns](#service-module-patterns)
-- [Migration from v0.7.x](#migration-from-v07x)
 
-## v0.8.x Modular Architecture
+## Modular Architecture
 
-The v0.8.x series introduces a completely refactored architecture that improves maintainability, testability, and performance while maintaining 100% backward compatibility.
+The server uses a modular architecture that improves maintainability, testability, and performance.
 
 ### Architecture Overview
 
-The v0.8.x architecture consists of several key components working together:
+The architecture consists of several key components working together:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -92,10 +91,10 @@ Focused modules handling specific server concerns:
 
 ## Dependency Injection Pattern
 
-The v0.8.x releases adopt explicit dependency injection for better testability and maintainability:
+The architecture uses explicit dependency injection for better testability and maintainability:
 
 ```typescript
-// v0.8.x pattern - explicit dependencies
+// Explicit dependency injection pattern
 class MyService {
   constructor(
     private cacheManager: CacheManager,
@@ -120,11 +119,11 @@ class MyService {
 const myService = new MyService(cacheManager, errorHandler, budgetResolver);
 ```
 
-## Developing Tools with v0.8.x
+## Developing Tools
 
 ### Tool Development Patterns
 
-Creating new tools in v0.8.x follows the Tool Registry pattern for consistency and maintainability.
+Creating new tools follows the Tool Registry pattern for consistency and maintainability.
 
 #### 1. Define Tool Schema
 
@@ -250,7 +249,7 @@ export async function handleMyTool(params: MyToolRequest): Promise<any> {
 
 ### Understanding the Enhanced Cache System
 
-The v0.8.x line introduces a sophisticated caching system designed for performance and observability.
+The server includes a sophisticated caching system designed for performance and observability.
 
 #### Cache Configuration
 
@@ -423,7 +422,7 @@ export async function handleSetDefaultBudget(params: SetDefaultBudgetRequest) {
 
 ### Working with Service Modules
 
-The v0.8.x releases decompose server functionality into focused service modules.
+The server decomposes functionality into focused service modules.
 
 #### Resource Manager
 
@@ -528,122 +527,6 @@ class MyDiagnosticManager extends DiagnosticManager {
 }
 ```
 
-## Migration from v0.7.x
-
-### No Breaking Changes for Users
-
-**Important:** All v0.7.x tool calls, parameters, and responses work identically in v0.8.x. This section is for developers working with the internal architecture.
-
-### Internal API Changes
-
-#### Error Handling Migration
-
-**v0.7.x Pattern:**
-```typescript
-// Direct error throwing
-if (!budgetId) {
-  throw new Error('No budget ID provided');
-}
-```
-
-**v0.8.x Pattern:**
-```typescript
-// Centralized error handling with consistent format
-const result = BudgetResolver.resolveBudgetId(providedId, defaultId);
-if (typeof result !== 'string') {
-  return result; // Returns properly formatted CallToolResult
-}
-```
-
-#### Caching Migration
-
-**v0.7.x Pattern:**
-```typescript
-// Manual cache management
-const cached = cacheManager.get(key);
-if (cached && !isExpired(cached)) {
-  return cached.data;
-}
-
-const result = await apiCall();
-cacheManager.set(key, result, ttl);
-return result;
-```
-
-**v0.8.x Pattern:**
-```typescript
-// Enhanced cache wrapper with observability
-return cacheManager.wrap(key, {
-  ttl: CACHE_TTLS.ACCOUNTS,
-  staleWhileRevalidate: 120000,
-  loader: () => apiCall()
-});
-```
-
-#### Tool Registration Migration
-
-**v0.7.x Pattern:**
-```typescript
-// Direct switch statement in handleCallTool
-case 'my_tool':
-  return withSecurityWrapper(async () => {
-    const validated = MyToolSchema.parse(params);
-    return await handleMyTool(validated);
-  });
-```
-
-**v0.8.x Pattern:**
-```typescript
-// Registry-based registration
-registry.register({
-  name: 'my_tool',
-  description: 'Tool description',
-  inputSchema: MyToolSchema,
-  handler: adapt(handleMyTool),
-  defaultArgumentResolver: resolveBudgetId()
-});
-```
-
-### Testing Pattern Updates
-
-**Enhanced Dependency Injection for Testing:**
-
-```typescript
-// v0.8.x - Mock individual services
-const mockCacheManager = {
-  wrap: vi.fn().mockImplementation((key, options) => options.loader()),
-  getStats: vi.fn().mockReturnValue({ hit_rate: 0.5 })
-};
-
-const mockErrorHandler = {
-  createErrorResponse: vi.fn().mockReturnValue({ success: false })
-};
-
-// Test with mocked dependencies
-const service = new MyService(mockCacheManager, mockErrorHandler);
-```
-
-### Import Path Updates
-
-Most imports remain the same due to barrel exports:
-
-```typescript
-// Still works (barrel export)
-import { handleMyTool } from '../tools/myTool.js';
-
-// New modular imports available
-import { parseCSV } from '../tools/compareTransactions/parser.js';
-import { findMatches } from '../tools/compareTransactions/matcher.js';
-import { formatResults } from '../tools/compareTransactions/formatter.js';
-```
-
-### Performance Improvements to Expect
-
-- **Cache Hit Rate**: 60-80% for repeated operations
-- **Initial Load Time**: Faster due to cache warming
-- **Memory Usage**: More efficient with LRU eviction
-- **Error Response Time**: Faster with pre-formatted responses
-
 ---
 
 For practical development patterns and examples, see [`DEVELOPMENT.md`](DEVELOPMENT.md).

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

@@ -0,0 +1,93 @@
+# 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

@@ -0,0 +1,362 @@
+# 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