@dizzlkheinz/ynab-mcpb 0.15.1 → 0.16.1

package/src/tools/reconciliation/reportFormatter.ts

@@ -14,6 +14,8 @@ import type {
 import type { LegacyReconciliationResult } from './executor.js';
 import type { MoneyValue } from '../../utils/money.js';
 
+const SECTION_DIVIDER = '-'.repeat(60);
+
 /**
  * Options for report formatting
  */
@@ -24,6 +26,7 @@ export interface ReportFormatterOptions {
   includeDetailedMatches?: boolean | undefined;
   maxUnmatchedToShow?: number | undefined;
   maxInsightsToShow?: number | undefined;
+  notes?: string[] | undefined;
 }
 
 /**
@@ -40,6 +43,11 @@ export function formatHumanReadableReport(
   // Header
   sections.push(formatHeader(accountLabel, analysis));
 
+  // Contextual notes (if provided)
+  if (options.notes && options.notes.length > 0) {
+    sections.push(formatNotesSection(options.notes));
+  }
+
   // Balance check section
   sections.push(formatBalanceSection(analysis.balance_info, analysis.summary));
 
@@ -67,12 +75,22 @@ export function formatHumanReadableReport(
  */
 function formatHeader(accountName: string, analysis: ReconciliationAnalysis): string {
   const lines: string[] = [];
-  lines.push(`📊 ${accountName} Reconciliation Report`);
-  lines.push('═'.repeat(60));
+  lines.push(`${accountName} Reconciliation Report`);
+  lines.push(SECTION_DIVIDER);
   lines.push(`Statement Period: ${analysis.summary.statement_date_range}`);
   return lines.join('\n');
 }
 
+function formatNotesSection(notes: string[]): string {
+  const lines: string[] = [];
+  lines.push('Notes');
+  lines.push(SECTION_DIVIDER);
+  for (const note of notes) {
+    lines.push(`- ${note}`);
+  }
+  return lines.join('\n');
+}
+
 /**
  * Format the balance check section
  */
@@ -81,18 +99,18 @@ function formatBalanceSection(
   summary: ReconciliationAnalysis['summary'],
 ): string {
   const lines: string[] = [];
-  lines.push('BALANCE CHECK');
-  lines.push('═'.repeat(60));
+  lines.push('Balance Check');
+  lines.push(SECTION_DIVIDER);
 
   // Current balances
-  lines.push(`✓ YNAB Cleared Balance:  ${summary.current_cleared_balance.value_display}`);
-  lines.push(`✓ Statement Balance:     ${summary.target_statement_balance.value_display}`);
+  lines.push(`- YNAB Cleared Balance:  ${summary.current_cleared_balance.value_display}`);
+  lines.push(`- Statement Balance:     ${summary.target_statement_balance.value_display}`);
   lines.push('');
 
   // Discrepancy status
   const discrepancyMilli = balanceInfo.discrepancy.value_milliunits;
   if (discrepancyMilli === 0) {
-    lines.push('✅ BALANCES MATCH PERFECTLY');
+    lines.push('Balances match perfectly.');
   } else {
     const direction = discrepancyMilli > 0 ? 'ynab_higher' : 'bank_higher';
     const directionLabel =
@@ -100,8 +118,8 @@ function formatBalanceSection(
         ? 'YNAB shows MORE than statement'
         : 'Statement shows MORE than YNAB';
 
-    lines.push(`❌ DISCREPANCY: ${balanceInfo.discrepancy.value_display}`);
-    lines.push(`   Direction: ${directionLabel}`);
+    lines.push(`Discrepancy: ${balanceInfo.discrepancy.value_display}`);
+    lines.push(`Direction: ${directionLabel}`);
   }
 
   return lines.join('\n');
@@ -115,21 +133,21 @@ function formatTransactionAnalysisSection(
   options: ReportFormatterOptions,
 ): string {
   const lines: string[] = [];
-  lines.push('TRANSACTION ANALYSIS');
-  lines.push('═'.repeat(60));
+  lines.push('Transaction Analysis');
+  lines.push(SECTION_DIVIDER);
 
   const summary = analysis.summary;
   lines.push(
-    `✓ Automatically matched:  ${summary.auto_matched} of ${summary.bank_transactions_count} transactions`,
+    `- Automatically matched:  ${summary.auto_matched} of ${summary.bank_transactions_count} transactions`,
   );
-  lines.push(`✓ Suggested matches:      ${summary.suggested_matches}`);
-  lines.push(`✓ Unmatched bank:         ${summary.unmatched_bank}`);
-  lines.push(`✓ Unmatched YNAB:         ${summary.unmatched_ynab}`);
+  lines.push(`- Suggested matches:      ${summary.suggested_matches}`);
+  lines.push(`- Unmatched bank:         ${summary.unmatched_bank}`);
+  lines.push(`- Unmatched YNAB:         ${summary.unmatched_ynab}`);
 
   // Show unmatched bank transactions (if any)
   if (analysis.unmatched_bank.length > 0) {
     lines.push('');
-    lines.push('❌ UNMATCHED BANK TRANSACTIONS:');
+    lines.push('Unmatched bank transactions:');
     const maxToShow = options.maxUnmatchedToShow ?? 5;
     const toShow = analysis.unmatched_bank.slice(0, maxToShow);
 
@@ -145,7 +163,7 @@ function formatTransactionAnalysisSection(
   // Show suggested matches (if any)
   if (analysis.suggested_matches.length > 0) {
     lines.push('');
-    lines.push('💡 SUGGESTED MATCHES:');
+    lines.push('Suggested matches:');
     const maxToShow = options.maxUnmatchedToShow ?? 3;
     const toShow = analysis.suggested_matches.slice(0, maxToShow);
 
@@ -194,8 +212,8 @@ function formatAmount(amountMilli: number): string {
  */
 function formatInsightsSection(insights: ReconciliationInsight[], maxToShow: number = 3): string {
   const lines: string[] = [];
-  lines.push('KEY INSIGHTS');
-  lines.push('═'.repeat(60));
+  lines.push('Key Insights');
+  lines.push(SECTION_DIVIDER);
 
   const toShow = insights.slice(0, maxToShow);
   for (const insight of toShow) {
@@ -222,18 +240,18 @@ function formatInsightsSection(insights: ReconciliationInsight[], maxToShow: num
 }
 
 /**
- * Get emoji icon for severity level
+ * Get text icon for severity level
  */
 function getSeverityIcon(severity: string): string {
   switch (severity) {
     case 'critical':
-      return '🚨';
+      return '[CRITICAL]';
     case 'warning':
-      return '⚠️';
+      return '[WARN]';
     case 'info':
-      return 'ℹ️';
+      return '[INFO]';
     default:
-      return '•';
+      return '[NOTE]';
   }
 }
 
@@ -260,13 +278,13 @@ function formatEvidenceSummary(evidence: Record<string, unknown>): string | null
  */
 function formatExecutionSection(execution: LegacyReconciliationResult): string {
   const lines: string[] = [];
-  lines.push('EXECUTION SUMMARY');
-  lines.push('═'.repeat(60));
+  lines.push('Execution Summary');
+  lines.push(SECTION_DIVIDER);
 
   const summary = execution.summary;
-  lines.push(`• Transactions created:  ${summary.transactions_created}`);
-  lines.push(`• Transactions updated:  ${summary.transactions_updated}`);
-  lines.push(`• Date adjustments:      ${summary.dates_adjusted}`);
+  lines.push(`Transactions created:  ${summary.transactions_created}`);
+  lines.push(`Transactions updated:  ${summary.transactions_updated}`);
+  lines.push(`Date adjustments:      ${summary.dates_adjusted}`);
 
   // Show top recommendations if any
   if (execution.recommendations.length > 0) {
@@ -275,7 +293,7 @@ function formatExecutionSection(execution: LegacyReconciliationResult): string {
     const maxRecs = 3;
     const toShow = execution.recommendations.slice(0, maxRecs);
     for (const rec of toShow) {
-      lines.push(`  • ${rec}`);
+      lines.push(`  - ${rec}`);
     }
     if (execution.recommendations.length > maxRecs) {
       lines.push(`  ... and ${execution.recommendations.length - maxRecs} more`);
@@ -284,9 +302,9 @@ function formatExecutionSection(execution: LegacyReconciliationResult): string {
 
   lines.push('');
   if (summary.dry_run) {
-    lines.push('⚠️  Dry run only — no YNAB changes were applied.');
+    lines.push('NOTE: Dry run only - no YNAB changes were applied.');
   } else {
-    lines.push('✅ Changes applied to YNAB. Review structured output for action details.');
+    lines.push('Changes applied to YNAB. Review structured output for action details.');
   }
 
   return lines.join('\n');
@@ -300,8 +318,8 @@ function formatRecommendationsSection(
   execution?: LegacyReconciliationResult,
 ): string {
   const lines: string[] = [];
-  lines.push('RECOMMENDED ACTIONS');
-  lines.push('═'.repeat(60));
+  lines.push('Recommended Actions');
+  lines.push(SECTION_DIVIDER);
 
   // If we have execution results, recommendations are already shown
   if (execution && !execution.summary.dry_run) {
@@ -312,11 +330,11 @@ function formatRecommendationsSection(
   // Show next steps from analysis
   if (analysis.next_steps.length > 0) {
     for (const step of analysis.next_steps) {
-      lines.push(`• ${step}`);
+      lines.push(`- ${step}`);
     }
   } else {
-    lines.push('• No specific actions recommended.');
-    lines.push('• Review the structured output for detailed match information.');
+    lines.push('No specific actions recommended.');
+    lines.push('Review the structured output for detailed match information.');
   }
 
   return lines.join('\n');

package/src/tools/transactionTools.ts

@@ -755,6 +755,16 @@ export async function handleListTransactions(
       let usedDelta = false;
 
       if (params.account_id) {
+        // Validate that the account exists before fetching transactions
+        // YNAB API returns empty array for invalid account IDs instead of an error
+        const accountsResult = await deltaFetcher.fetchAccounts(params.budget_id);
+        const accountExists = accountsResult.data.some(
+          (account) => account.id === params.account_id,
+        );
+        if (!accountExists) {
+          throw new Error(`Account ${params.account_id} not found in budget ${params.budget_id}`);
+        }
+
         const result = await deltaFetcher.fetchTransactionsByAccount(
           params.budget_id,
           params.account_id,

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/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.