@dizzlkheinz/ynab-mcpb 0.16.0 → 0.17.0

package/src/types/toolRegistration.ts

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview Type definitions for the tool factory registration pattern.
+ * Provides ToolContext for dependency injection and typed handler signatures
+ * used by domain-specific tool factory functions.
+ * @module types/toolRegistration
+ */
+
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+import type {
+  ToolRegistry,
+  ToolExecutionPayload,
+  DefaultArgumentResolver,
+} from '../server/toolRegistry.js';
+import type { DeltaFetcher } from '../tools/deltaFetcher.js';
+import type { DeltaCache } from '../server/deltaCache.js';
+import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
+import type { DiagnosticManager } from '../server/diagnostics.js';
+import type { CacheManager } from '../server/cacheManager.js';
+
+/**
+ * Context object passed to tool factory functions. Contains the dependencies
+ * required by tool adapters and handlers.
+ *
+ * @stable This interface is part of the public tool registration contract.
+ * Changes to this interface may affect all domain tool factories.
+ */
+export interface ToolContext {
+  ynabAPI: ynab.API;
+  deltaFetcher: DeltaFetcher;
+  deltaCache: DeltaCache;
+  serverKnowledgeStore: ServerKnowledgeStore;
+  getDefaultBudgetId: () => string | undefined;
+  setDefaultBudget: (budgetId: string) => void;
+  cacheManager: CacheManager;
+  diagnosticManager?: DiagnosticManager;
+}
+
+/**
+ * Factory function signature for registering a domain's tools.
+ */
+export type ToolFactory = (registry: ToolRegistry, context: ToolContext) => void;
+
+/**
+ * Common adapter signature used within tool factories.
+ */
+export type Adapter<TInput extends Record<string, unknown>> = (
+  payload: ToolExecutionPayload<TInput>,
+) => Promise<CallToolResult>;
+
+/**
+ * Generic handler signature used by adapter helpers.
+ */
+export type Handler<TInput extends Record<string, unknown>> = (
+  api: ynab.API,
+  params: TInput,
+) => Promise<CallToolResult>;
+
+/**
+ * Handler signature for operations that require delta fetching.
+ */
+export type DeltaHandler<TInput extends Record<string, unknown>> = (
+  api: ynab.API,
+  deltaFetcher: DeltaFetcher,
+  params: TInput,
+) => Promise<CallToolResult>;
+
+/**
+ * Handler signature for write operations that update caches and knowledge stores.
+ */
+export type WriteHandler<TInput extends Record<string, unknown>> = (
+  api: ynab.API,
+  deltaCache: DeltaCache,
+  serverKnowledgeStore: ServerKnowledgeStore,
+  params: TInput,
+) => Promise<CallToolResult>;
+
+/**
+ * Handler signature for tools that do not accept input parameters.
+ */
+export type NoInputHandler = (api: ynab.API) => Promise<CallToolResult>;
+
+/**
+ * Helper type for default argument resolver factories.
+ */
+export type BudgetIdResolverFactory = <
+  TInput extends { budget_id?: string | undefined },
+>() => DefaultArgumentResolver<TInput>;

package/.dxtignore

@@ -1,57 +0,0 @@
-node_modules/
-src/
-**/__tests__/
-**/*.test.*
-coverage/
-*.log
-.*/
-**/*.map
-tsconfig*.json
-vitest.config.ts
-vitest-reporters/
-eslint.config.js
-test-results.json
-test-results/
-README.md
-
-# Sensitive credential files
-.chunkhound.json
-.mcp.json
-.env*
-
-# Build metadata
-meta.json
-bundle-analysis.html
-
-# Development-only markdown files
-AGENTS.md
-TESTING_NOTES.md
-CODEREVIEW_RESPONSE.md
-SCHEMA_IMPROVEMENT_SUMMARY.md
-
-# Test files and data
-test_*.js
-test_*.mjs
-test-*.js
-test-*.cjs
-test-*.csv
-test-exports/
-accountactivity-merged.csv
-
-# Temporary and development files
-temp/
-tmp/
-fix-types.sh
-NUL
-package-lock.json
-
-# Development plans (keep user-facing docs)
-docs/plans/
-docs/bulk-transaction-operations-plan.md
-docs/delta-request-plan.md
-docs/reconciliation-flow.md
-
-# Scripts (not needed for distribution)
-scripts/
-
-# keep dist/, manifest.json, CHANGELOG.md, CLAUDE.md, LICENSE, docs/ (except plans)

package/.github/workflows/pr-description-check.yml

@@ -1,88 +0,0 @@
-name: PR Description Check
-
-on:
-  pull_request:
-    types: [opened, edited, synchronize]
-
-permissions:
-  contents: read
-  issues: write
-  pull-requests: read
-
-jobs:
-  check-description:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check PR Description Format
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
-        with:
-          script: |
-            const body = context.payload.pull_request.body || '';
-
-            // Required sections from template
-            const requiredSections = [
-              'Type of change',
-              'Public API surface checklist',
-              'Versioning and release'
-            ];
-
-            const missingSections = requiredSections.filter(section =>
-              !body.includes(section)
-            );
-
-            if (missingSections.length > 0) {
-              // Build comment as array to avoid YAML indentation issues
-              const commentLines = [
-                '⚠️ **PR Description Check Failed**',
-                '',
-                'The PR description is missing required sections from the template:',
-                ...missingSections.map(s => `- ${s}`),
-                '',
-                'Please update the description to include these sections. You can view the template at:',
-                `https://github.com/${context.repo.owner}/${context.repo.repo}/blob/master/.github/pull_request_template.md`,
-                '',
-                'Or run this command to update it:',
-                '```bash',
-                `gh pr edit ${context.payload.pull_request.number} --body-file .github/pull_request_template.md`,
-                '```'
-              ];
-              const comment = commentLines.join('\n');
-
-              // Upsert comment: update existing bot comment or create new one
-              const botCommentPrefix = '⚠️ **PR Description Check Failed**';
-              // Paginate through all comments to handle PRs with >30 comments
-              const comments = await github.paginate(
-                github.rest.issues.listComments,
-                {
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: context.payload.pull_request.number,
-                  per_page: 100
-                }
-              );
-
-              const existingComment = comments.find(
-                c => c.user.type === 'Bot' && c.body.startsWith(botCommentPrefix)
-              );
-
-              if (existingComment) {
-                await github.rest.issues.updateComment({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  comment_id: existingComment.id,
-                  body: comment
-                });
-              } else {
-                await github.rest.issues.createComment({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: context.payload.pull_request.number,
-                  body: comment
-                });
-              }
-
-              // Fail the check
-              core.setFailed(`Missing required sections: ${missingSections.join(', ')}`);
-            } else {
-              console.log('✅ All required sections present in PR description');
-            }

package/CODEREVIEW_RESPONSE.md

@@ -1,128 +0,0 @@
-# Code Review Response: reconciliationOutputs.ts
-
-## Summary
-
-CodeRabbit provided two suggestions for improving `src/tools/schemas/outputs/reconciliationOutputs.ts`. After technical analysis of the codebase, I've determined:
-
-1. **Feedback #1 (ExecutionActionRecordSchema typing)**: Already implemented ✅
-2. **Feedback #2 (discrepancy_direction validation)**: Not implementing - technically sound but violates architectural principles ❌
-
-## Feedback #1: Stronger Typing for Transaction Field
-
-**Suggestion:** Use discriminated unions instead of `z.record(z.string(), z.unknown())` for the transaction field in `ExecutionActionRecordSchema`.
-
-**Status:** ✅ **Already Implemented**
-
-### Analysis
-
-The CodeRabbit feedback appears to be outdated. The current implementation (lines 431-479) already uses a discriminated union with strong typing:
-
-```typescript
-export const ExecutionActionRecordSchema = z.discriminatedUnion('type', [
-  // Successful transaction creation
-  z.object({
-    type: z.literal('create_transaction'),
-    transaction: CreatedTransactionSchema.nullable(),
-    // ...
-  }),
-  // Failed transaction creation
-  z.object({
-    type: z.literal('create_transaction_failed'),
-    transaction: TransactionCreationPayloadSchema,
-    // ...
-  }),
-  // ... other action types
-]);
-```
-
-Each action type has its own specific schema:
-
-- `CreatedTransactionSchema` - for successful creations (line 371)
-- `TransactionCreationPayloadSchema` - for failed/dry-run creations (line 387)
-- `TransactionUpdatePayloadSchema` - for status/date changes (line 402)
-- `DuplicateDetectionPayloadSchema` - for duplicate detection (line 412)
-
-This provides full type safety without the drawbacks of loose typing.
-
-## Feedback #2: Validate discrepancy_direction Against Actual Discrepancy
-
-**Suggestion:** Add a Zod refinement to ensure `discrepancy_direction` matches the sign of `balance.discrepancy.amount`.
-
-**Status:** ❌ **Not Implementing**
-
-### Analysis
-
-While technically correct, this validation violates architectural principles and provides minimal benefit:
-
-#### Current Implementation (reconcileAdapter.ts:122-135)
-
-The `convertBalanceInfo` function deterministically derives `discrepancy_direction` from `discrepancyMilli`:
-
-```typescript
-const convertBalanceInfo = (analysis: ReconciliationAnalysis) => {
-  const discrepancyMilli = analysis.balance_info.discrepancy.value_milliunits;
-  const direction =
-    discrepancyMilli === 0 ? 'balanced' : discrepancyMilli > 0 ? 'ynab_higher' : 'bank_higher';
-
-  return {
-    current_cleared: analysis.balance_info.current_cleared,
-    // ...
-    discrepancy: analysis.balance_info.discrepancy,
-    discrepancy_direction: direction,
-    on_track: analysis.balance_info.on_track,
-  };
-};
-```
-
-This logic is:
-
-- **Simple and obvious**: Direct mapping from sign to direction
-- **Well-tested**: Part of the adapter layer
-- **Single point of truth**: Consistency enforced at construction time
-
-#### Why Not Add Schema Validation?
-
-1. **Violates Single Responsibility Principle**
-   The schema's job is to validate structure, not business logic consistency. The adapter already enforces this invariant at construction time.
-
-2. **Adds Runtime Overhead**
-   Schema validation runs on every payload validation. This adds unnecessary computation for a condition that should never occur if the adapter works correctly.
-
-3. **Couples Schema to Business Logic**
-   The schema would need to know the thresholds and logic for determining direction. This creates tight coupling between layers that should be independent.
-
-4. **Limited Bug Detection Value**
-   If the adapter logic is broken, we'd want to fix the adapter, not catch it at validation time. Schema validation wouldn't prevent the bug, just detect it later in the pipeline.
-
-5. **Test Coverage Sufficient**
-   The adapter has comprehensive test coverage. Adding redundant validation at the schema level doesn't improve reliability.
-
-### Alternative Considered
-
-If we were truly concerned about this invariant, the better approach would be:
-
-1. Add unit tests specifically for the `convertBalanceInfo` function
-2. Add integration tests that verify the full payload structure
-3. Add a comment in the schema documenting the expected relationship
-
-But given the simplicity of the current implementation and existing test coverage, none of these are necessary.
-
-### Recommendation
-
-**Accept Feedback #1 as already implemented.**
-**Respectfully decline Feedback #2** - the adapter already enforces consistency, and adding schema-level validation would violate architectural principles without meaningful benefit.
-
----
-
-## Files Changed
-
-- `src/tools/schemas/outputs/reconciliationOutputs.ts` - No changes required (already has strong typing)
-- `CODEREVIEW_RESPONSE.md` - This document
-
-## Tests
-
-All existing tests pass:
-
-- ✅ `npm run type-check` - TypeScript compilation successful
-- ✅ `npm run test:unit -- reconciliationOutputs` - 26/26 tests passing
-- ✅ No regressions in related tests

package/SCHEMA_IMPROVEMENT_SUMMARY.md

@@ -1,120 +0,0 @@
-# ExecutionActionRecord Schema Type Safety Improvements
-
-## Summary
-
-Addressed CodeRabbit's feedback about weak typing in `ExecutionActionRecordSchema` by replacing the generic `z.record(z.string(), z.unknown())` transaction field with a discriminated union based on action type.
-
-## Problem
-
-The original schema at line 370 in `reconciliationOutputs.ts` used:
-
-```typescript
-export const ExecutionActionRecordSchema = z.object({
-  type: z.string(),
-  transaction: z.record(z.string(), z.unknown()).nullable(),
-  // ...
-});
-```
-
-This provided no type safety for transaction data, making the code prone to runtime errors if assumptions about transaction structure were incorrect.
-
-## Solution
-
-Implemented a **discriminated union** based on the `type` field, with each action type having its own strongly-typed transaction schema:
-
-### Action Types & Transaction Schemas
-
-1. **`create_transaction`** - Successful transaction creation
-   - Transaction: `CreatedTransactionSchema.nullable()`
-   - Full YNAB API transaction response with `.passthrough()` for additional fields
-   - Optional fields: `bulk_chunk_index`, `correlation_key`
-
-2. **`create_transaction_failed`** - Failed transaction creation
-   - Transaction: `TransactionCreationPayloadSchema` (required)
-   - The request payload that failed to create
-   - Optional fields: `bulk_chunk_index`, `correlation_key`
-
-3. **`create_transaction_duplicate`** - Duplicate detection
-   - Transaction: `DuplicateDetectionPayloadSchema` (required)
-   - Contains `transaction_id` (nullable) and optional `import_id`
-   - Required fields: `bulk_chunk_index`, `duplicate: true`
-   - Optional: `correlation_key`
-
-4. **`update_transaction`** - Transaction update (status/date)
-   - Transaction: Union of `CreatedTransactionSchema.nullable()` (real execution) or `TransactionUpdatePayloadSchema` (dry run)
-   - Handles both full transaction responses and minimal update payloads
-
-5. **`balance_checkpoint`** - Balance alignment checkpoint
-   - Transaction: `z.null()` (always null)
-   - No optional fields
-
-6. **`bulk_create_fallback`** - Bulk operation fallback to sequential
-   - Transaction: `z.null()` (always null)
-   - Required: `bulk_chunk_index`
-
-### Helper Schemas
-
-**`CreatedTransactionSchema`**
-
-- Validates YNAB API transaction responses
-- Uses `.passthrough()` to allow additional API fields
-- Required: `id`, `date`, `amount`
-- Optional: `memo`, `cleared`, `approved`, `payee_name`, `category_name`, `import_id`
-
-**`TransactionCreationPayloadSchema`**
-
-- Validates transaction creation requests
-- Required: `account_id`, `date`, `amount`
-- Optional: `payee_name`, `memo`, `cleared`, `approved`, `import_id`
-
-**`TransactionUpdatePayloadSchema`**
-
-- Validates transaction update requests
-- Required: `transaction_id`
-- Optional: `new_date`, `cleared`
-
-**`DuplicateDetectionPayloadSchema`**
-
-- Validates duplicate detection metadata
-- Required: `transaction_id` (nullable)
-- Optional: `import_id`
-
-## Benefits
-
-1. **Type Safety** - Compile-time checking of transaction field structure
-2. **Self-Documenting** - Schema clearly shows what data each action type contains
-3. **Runtime Validation** - Zod catches malformed data before it causes issues
-4. **Better Errors** - Discriminated union provides clear validation error messages
-5. **Flexibility** - `.passthrough()` on `CreatedTransactionSchema` allows future YNAB API additions
-6. **Zero Breaking Changes** - Backward compatible, all existing data validates correctly
-
-## Testing
-
-Created comprehensive test suite (`reconciliationOutputs.test.ts`) with 26 passing tests covering:
-
-- All 6 action types with valid data
-- Negative cases (wrong types, missing required fields)
-- Discriminated union behavior (unknown types, type mismatches)
-- Helper schema validation
-- Edge cases (null transactions, passthrough fields)
-
-## Files Changed
-
-1. `src/tools/schemas/outputs/reconciliationOutputs.ts` - Schema definitions
-2. `src/tools/schemas/outputs/__tests__/reconciliationOutputs.test.ts` - New test suite
-
-## Verification
-
-- ✅ TypeScript compilation passes (`npm run type-check`)
-- ✅ All 26 new schema tests pass
-- ✅ Build succeeds (`npm run build`)
-- ✅ MCPB package generation succeeds
-- ✅ No runtime changes to executor.ts needed (schemas match actual usage)
-
-## Implementation Notes
-
-The discriminated union matches exactly how the executor currently constructs action records (verified by analyzing `src/tools/reconciliation/executor.ts` lines 226-580). No changes to runtime code were needed, proving this is a pure type-safety enhancement.
-
-## Follow-up Opportunities
-
-Consider applying the same pattern to other schemas with generic `z.record()` fields if similar type safety concerns exist elsewhere in the codebase.