@dizzlkheinz/ynab-mcpb 0.16.0 → 0.16.1

package/docs/plans/2025-11-21-v014-hardening.md

@@ -1,153 +0,0 @@
-# YNAB MCP v0.14 Hardening Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Ship v0.14 with tighter schema fidelity, cache/knowledge resets, resilient config+token handling, clearer reconciliation errors, and strongly-typed dry-run payloads.
-
-**Architecture:** Focused, TDD-driven changes inside existing server/tool layers: enforce ToolRegistry metadata/schema parity, route cache clears through DeltaCache, inject per-instance config with robust token validation, add error normalization in reconciliation executor, and replace untyped dry-run request blobs with explicit Zod schemas mirrored by handlers.
-
-**Tech Stack:** TypeScript 5, Node 18+, MCP SDK, Zod, Vitest (unit/integration/e2e), Prettier/ESLint, docs in `docs/reference`.
-
-### Task 1: Enforce tool metadata schema parity
-
-**Files:**
-- Modify: `src/server/toolRegistry.ts`
-- Modify: `src/server/__tests__/toolRegistry.test.ts`
-
-**Step 1: Write failing unit test**
-Add a case that registers a tool whose `metadata.inputJsonSchema` differs from the generated schema and expects an error: `metadata input schema must match generated schema for tool "budget-sync"`.
-
-**Step 2: Run test to see it fail**
-`npm run test:unit -- --runInBand src/server/__tests__/toolRegistry.test.ts --testNamePattern "metadata input schema"`
-
-**Step 3: Implement enforcement**
-In `register`, call a new helper (e.g., `ensureMetadataSchemaMatches`) that generates the JSON schema from `inputSchema`; if `metadata.inputJsonSchema` exists and differs, throw; otherwise populate it. Remove redundant schema regeneration in `listTools` when metadata is present.
-
-**Step 4: Re-run unit test**
-`npm run test:unit -- --runInBand src/server/__tests__/toolRegistry.test.ts --testNamePattern "metadata input schema"`
-
-**Step 5: Commit**
-`git add src/server/toolRegistry.ts src/server/__tests__/toolRegistry.test.ts && git commit -m "fix: validate tool metadata schemas at registration"`
-
-### Task 2: Make clear_cache reset delta knowledge
-
-**Files:**
-- Modify: `src/server/YNABMCPServer.ts`
-- Modify: `src/server/__tests__/YNABMCPServer.integration.test.ts`
-- Modify: `docs/reference/TOOLS.md`
-
-**Step 1: Add failing integration test**
-In `YNABMCPServer.integration.test.ts`, assert that after `list_accounts` populates caches, `clear_cache` drives knowledge entries to zero via `diagnostic_info` with `include_delta: true`.
-
-**Step 2: Run test to confirm failure**
-`npm run test:integration:domain -- --testNamePattern "clear cache runs"`
-
-**Step 3: Implement reset**
-In `setupToolRegistry`, change the `clear_cache` handler to call `this.deltaCache.forceFullRefresh()` (not just `cacheManager.clear()`), ensuring both cache and `ServerKnowledgeStore` reset.
-
-**Step 4: Update docs**
-Document in `docs/reference/TOOLS.md` that `clear_cache` now clears cache *and* delta knowledge.
-
-**Step 5: Re-run integration slice**
-`npm run test:integration:domain -- --testNamePattern "clear cache runs"`
-
-**Step 6: Commit**
-`git add src/server/YNABMCPServer.ts src/server/__tests__/YNABMCPServer.integration.test.ts docs/reference/TOOLS.md && git commit -m "feat: reset delta knowledge when cache is cleared"`
-
-### Task 3: Reloadable config, per-instance server config, and resilient token validation
-
-**Files:**
-- Modify: `src/server/config.ts`
-- Modify: `src/server/YNABMCPServer.ts`
-- Modify: `src/server/__tests__/config.test.ts`
-- Modify: `src/server/__tests__/YNABMCPServer.test.ts`
-- Modify: `src/server/__tests__/server-startup.integration.test.ts`
-- Modify: `scripts/run-throttled-integration-tests.js`
-
-**Step 1: Verify/extend config reload tests**
-Ensure `config.test.ts` covers re-parsing on successive `loadConfig()` calls and explicit env overrides. Add a case asserting per-call env changes are observed.
-
-**Step 2: Add failing per-instance server test**
-In `YNABMCPServer.test.ts`, instantiate two servers after mutating `process.env.YNAB_ACCESS_TOKEN` and assert each uses its instantiation-time config (via diagnostic/info accessor).
-
-**Step 3: Make config injectable per instance**
-In `YNABMCPServer.ts`, replace module-level `config` usage with `this.serverConfig = loadConfig()` inside the constructor; route YNAB API creation and tool setup through `this.serverConfig`.
-
-**Step 4: Harden token validation**
-Wrap `validateToken` to catch `SyntaxError` / malformed JSON or HTML responses from YNAB and throw `AuthenticationError` with guidance; keep 401/403 handling; rethrow others.
-
-**Step 5: Windows-safe throttled runner**
-In `scripts/run-throttled-integration-tests.js`, spawn Vitest via a platform-safe path (use `.cmd` on win32, otherwise the binary) and avoid EINVAL issues.
-
-**Step 6: Run focused tests**
-`npm run test:unit -- src/server/__tests__/config.test.ts src/server/__tests__/YNABMCPServer.test.ts`
-`npm run test:integration:core -- --testNamePattern "server-startup"`
-`node scripts/run-throttled-integration-tests.js --help` (manual sanity on Windows)
-
-**Step 7: Commit**
-`git add src/server/config.ts src/server/YNABMCPServer.ts src/server/__tests__/*.ts scripts/run-throttled-integration-tests.js && git commit -m "feat: reloadable config and robust token validation"`
-
-### Task 4: Propagate fatal YNAB errors during reconciliation
-
-**Files:**
-- Modify: `src/tools/reconciliation/executor.ts`
-- Modify: `src/tools/reconciliation/__tests__/executor.test.ts`
-- Modify: `src/tools/reconciliation/__tests__/executor.integration.test.ts`
-
-**Step 1: Add failing unit tests for error normalization**
-Cover `normalizeYnabError`, `shouldPropagateYnabError`, and status/message shaping for 429/404 plus generic errors.
-
-**Step 2: Implement normalization helpers**
-Add helpers in `executor.ts` to parse YNAB SDK error objects, standard Errors, and strings; decide propagation for 401/403/404/429/500/503; attach status to thrown Error.
-
-**Step 3: Add failing integration test for bulk rate-limit**
-Simulate bulk create rejecting with `id: '429'` and assert `executeReconciliation` rejects with status 429 instead of silent fallback.
-
-**Step 4: Wire helpers into bulk + sequential paths**
-In bulk chunk catch blocks, propagate fatal errors, otherwise log and fall back; in sequential creation, log failure reasons with status and propagate fatal errors after logging.
-
-**Step 5: Run reconciliation suites**
-`npm run test:unit -- src/tools/reconciliation/__tests__/executor.test.ts`
-`npm run test:integration:reconciliation` (or project pattern)
-
-**Step 6: Commit**
-`git add src/tools/reconciliation/executor.ts src/tools/reconciliation/__tests__/executor*.test.ts && git commit -m "fix: propagate fatal YNAB errors during reconciliation"`
-
-### Task 5: Strongly type dry-run transaction outputs
-
-**Files:**
-- Modify: `src/tools/schemas/outputs/transactionMutationOutputs.ts`
-- Modify: `src/tools/schemas/outputs/__tests__/transactionMutationSchemas.test.ts`
-- Modify: `src/tools/transactionTools.ts`
-- Modify: `src/tools/__tests__/transactionTools.test.ts`
-- (Optional) Modify: `src/tools/__tests__/transactionTools.integration.test.ts`, `src/__tests__/workflows.e2e.test.ts`
-
-**Step 1: Add failing schema tests**
-Assert dry-run `request` for create/update/delete matches explicit schemas (no `budget_id`/`dry_run`, required ids present) and rejects arbitrary `z.record` payloads.
-
-**Step 2: Define typed dry-run request schemas**
-In `transactionMutationOutputs.ts`, introduce `CreateTransactionDryRunRequestSchema`, `UpdateTransactionDryRunRequestSchema`, and `DeleteTransactionDryRunRequestSchema` (omit `budget_id`/`dry_run`), export inferred types, and replace existing `z.record` uses in dry-run branches.
-
-**Step 3: Update handler dry-run branches**
-In `transactionTools.ts`, build `request` objects that include only allowed fields (exclude `budget_id`/`dry_run`) for create/update/delete dry-runs.
-
-**Step 4: Update unit tests**
-Adjust/create tests in `transactionTools.test.ts` to assert dry-run outputs match the new schemas and make no API calls.
-
-**Step 5: (Optional) Integration/E2E checks**
-Add integration/E2E assertions that dry-run outputs validate against updated schemas.
-
-**Step 6: Run targeted suites**
-`npm run test:unit -- src/tools/schemas/outputs/__tests__/transactionMutationSchemas.test.ts src/tools/__tests__/transactionTools.test.ts`
-`npm run test:integration -- --testPathPattern=transactionTools` (if present)
-
-**Step 7: Commit**
-`git add src/tools/schemas/outputs/transactionMutationOutputs.ts src/tools/schemas/outputs/__tests__/transactionMutationSchemas.test.ts src/tools/transactionTools.ts src/tools/__tests__/transactionTools.test.ts && git commit -m "feat: type-safe dry-run transaction outputs"`
-
-### Final verification (after all tasks)
-
-- `npm run lint`
-- `npm run type-check`
-- `npm test`
-- `npm run build` (or `npm run build:prod` if cutting release)
-- Update `CHANGELOG.md` and `.pr-description.md` with changes and test commands.