mortctl 0.1.0

package/src/commands/eligible.ts

@@ -0,0 +1,121 @@
+/**
+ * mortctl eligible command - Check loan program eligibility
+ */
+
+import { Command } from 'commander';
+import { LoanScenario, PropertyType, OccupancyType, LoanPurpose } from '../types';
+import { checkAllEligibility, findBestProgram } from '../lib/eligibility';
+
+export function createEligibleCommand(): Command {
+  const eligible = new Command('eligible')
+    .description('Check eligibility for loan programs')
+    .requiredOption('--property-value <amount>', 'Property value')
+    .requiredOption('--loan-amount <amount>', 'Loan amount')
+    .requiredOption('--credit-score <score>', 'Credit score')
+    .option('--property-type <type>', 'Property type', 'single-family')
+    .option('--occupancy <type>', 'Occupancy type', 'primary')
+    .option('--purpose <type>', 'Loan purpose', 'purchase')
+    .option('--units <n>', 'Number of units', '1')
+    .option('--county <name>', 'County for loan limits')
+    .option('--state <abbr>', 'State abbreviation')
+    .option('--veteran', 'Veteran/military eligibility', false)
+    .option('--rural', 'Rural/USDA eligible location', false)
+    .option('--first-time', 'First-time homebuyer', false)
+    .option('--format <type>', 'Output format (json|table)', 'table')
+    .action(async (options) => {
+      try {
+        const scenario: LoanScenario = {
+          propertyValue: parseFloat(options.propertyValue),
+          loanAmount: parseFloat(options.loanAmount),
+          downPayment: parseFloat(options.propertyValue) - parseFloat(options.loanAmount),
+          creditScore: parseInt(options.creditScore),
+          propertyType: options.propertyType as PropertyType,
+          occupancy: options.occupancy as OccupancyType,
+          purpose: options.purpose as LoanPurpose,
+          units: parseInt(options.units),
+          county: options.county,
+          state: options.state,
+          veteran: options.veteran,
+          rural: options.rural,
+          firstTimeHomebuyer: options.firstTime,
+          interestRate: 6.5, // Default for calculations
+          termYears: 30,
+        };
+
+        const eligibility = checkAllEligibility(scenario);
+        const recommended = findBestProgram(eligibility);
+
+        if (options.format === 'json') {
+          console.log(JSON.stringify({ 
+            scenario: {
+              propertyValue: scenario.propertyValue,
+              loanAmount: scenario.loanAmount,
+              ltv: (scenario.loanAmount / scenario.propertyValue * 100).toFixed(2),
+              creditScore: scenario.creditScore,
+            },
+            eligibility,
+            recommendedProgram: recommended,
+          }, null, 2));
+        } else {
+          const ltv = (scenario.loanAmount / scenario.propertyValue * 100);
+          
+          console.log('═══════════════════════════════════════════════════════════════');
+          console.log('LOAN PROGRAM ELIGIBILITY');
+          console.log('═══════════════════════════════════════════════════════════════');
+          console.log('');
+          console.log(`Property Value:     $${scenario.propertyValue.toLocaleString()}`);
+          console.log(`Loan Amount:        $${scenario.loanAmount.toLocaleString()}`);
+          console.log(`LTV:                ${ltv.toFixed(1)}%`);
+          console.log(`Credit Score:       ${scenario.creditScore}`);
+          console.log(`Property:           ${scenario.propertyType}, ${scenario.occupancy}`);
+          console.log('');
+          console.log('PROGRAM ELIGIBILITY');
+          console.log('───────────────────────────────────────────────────────────────');
+          
+          for (const result of eligibility) {
+            const status = result.eligible ? '✓' : '✗';
+            const programName = result.program.toUpperCase().padEnd(15);
+            console.log(`${status} ${programName}`);
+            
+            if (!result.eligible && result.reasons) {
+              for (const reason of result.reasons) {
+                console.log(`    ✗ ${reason}`);
+              }
+            }
+            
+            if (result.eligible) {
+              if (result.minDownPayment !== undefined) {
+                console.log(`    Min down: $${result.minDownPayment.toLocaleString()}`);
+              }
+              if (result.rateAdjustment) {
+                const adj = result.rateAdjustment > 0 ? `+${result.rateAdjustment}%` : `${result.rateAdjustment}%`;
+                console.log(`    Rate adj: ${adj}`);
+              }
+            }
+            
+            if (result.warnings) {
+              for (const warning of result.warnings) {
+                console.log(`    ⚠ ${warning}`);
+              }
+            }
+            console.log('');
+          }
+
+          if (recommended) {
+            console.log('───────────────────────────────────────────────────────────────');
+            console.log(`💡 RECOMMENDED: ${recommended.toUpperCase()}`);
+          } else {
+            console.log('───────────────────────────────────────────────────────────────');
+            console.log('⚠ No programs eligible - review requirements');
+          }
+          
+          console.log('═══════════════════════════════════════════════════════════════');
+        }
+      } catch (error: any) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+      }
+    });
+
+  return eligible;
+}

package/src/commands/limits.ts

@@ -0,0 +1,91 @@
+/**
+ * mortctl limits command - Show conforming loan limits
+ */
+
+import { Command } from 'commander';
+import { getConformingLimit, LOAN_LIMITS_2026, HIGH_COST_COUNTIES } from '../lib/calculations';
+
+export function createLimitsCommand(): Command {
+  const limits = new Command('limits')
+    .description('Show conforming loan limits')
+    .option('--county <name>', 'County name (e.g., "Los Angeles")')
+    .option('--state <abbr>', 'State abbreviation (e.g., "CA")')
+    .option('--units <n>', 'Number of units (1-4)', '1')
+    .option('--list-high-cost', 'List all high-cost counties', false)
+    .option('--format <type>', 'Output format (json|table)', 'table')
+    .action(async (options) => {
+      try {
+        const units = parseInt(options.units);
+
+        if (options.listHighCost) {
+          if (options.format === 'json') {
+            console.log(JSON.stringify(HIGH_COST_COUNTIES, null, 2));
+          } else {
+            console.log('═══════════════════════════════════════════════════════════════');
+            console.log('HIGH-COST COUNTIES (2026)');
+            console.log('═══════════════════════════════════════════════════════════════');
+            console.log('');
+            for (const [county, limit] of Object.entries(HIGH_COST_COUNTIES)) {
+              console.log(`${county.padEnd(30)} $${limit.toLocaleString()}`);
+            }
+            console.log('═══════════════════════════════════════════════════════════════');
+          }
+          return;
+        }
+
+        const countyKey = options.county && options.state 
+          ? `${options.county}, ${options.state}`
+          : undefined;
+
+        const conformingLimit = getConformingLimit(countyKey, units);
+        const isHighCost = countyKey && HIGH_COST_COUNTIES[countyKey];
+
+        // Unit multipliers for display
+        const unitLimits: Record<number, number> = {};
+        for (let u = 1; u <= 4; u++) {
+          unitLimits[u] = getConformingLimit(countyKey, u);
+        }
+
+        const result = {
+          year: 2026,
+          county: countyKey || 'Baseline (standard counties)',
+          isHighCost: !!isHighCost,
+          units,
+          conformingLimit,
+          allUnitLimits: unitLimits,
+          baseline: LOAN_LIMITS_2026,
+        };
+
+        if (options.format === 'json') {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log('═══════════════════════════════════════════════════════════════');
+          console.log('CONFORMING LOAN LIMITS (2026)');
+          console.log('═══════════════════════════════════════════════════════════════');
+          console.log('');
+          console.log(`Area:               ${result.county}`);
+          console.log(`High-Cost:          ${result.isHighCost ? 'Yes' : 'No'}`);
+          console.log('');
+          console.log('LIMITS BY UNIT COUNT');
+          console.log('───────────────────────────────────────────────────────────────');
+          console.log(`1-Unit:             $${unitLimits[1].toLocaleString()}`);
+          console.log(`2-Unit:             $${unitLimits[2].toLocaleString()}`);
+          console.log(`3-Unit:             $${unitLimits[3].toLocaleString()}`);
+          console.log(`4-Unit:             $${unitLimits[4].toLocaleString()}`);
+          console.log('');
+          console.log('NATIONAL BASELINE');
+          console.log('───────────────────────────────────────────────────────────────');
+          console.log(`Conforming Floor:   $${LOAN_LIMITS_2026.baseline.toLocaleString()}`);
+          console.log(`High-Cost Ceiling:  $${LOAN_LIMITS_2026.highCost.toLocaleString()}`);
+          console.log(`FHA Floor:          $${LOAN_LIMITS_2026.fhaFloor.toLocaleString()}`);
+          console.log(`FHA Ceiling:        $${LOAN_LIMITS_2026.fhaCeiling.toLocaleString()}`);
+          console.log('═══════════════════════════════════════════════════════════════');
+        }
+      } catch (error: any) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+      }
+    });
+
+  return limits;
+}

package/src/commands/ltv.ts

@@ -0,0 +1,97 @@
+/**
+ * mortctl ltv command - Calculate LTV/CLTV/HCLTV
+ */
+
+import { Command } from 'commander';
+import { calculateLtv, calculatePmi } from '../lib/calculations';
+
+export function createLtvCommand(): Command {
+  const ltv = new Command('ltv')
+    .description('Calculate loan-to-value ratios')
+    .requiredOption('--property-value <amount>', 'Property value or purchase price')
+    .option('--loan-amount <amount>', 'Loan amount (or use --down-payment)')
+    .option('--down-payment <amount>', 'Down payment amount')
+    .option('--second-lien <amount>', 'Second mortgage/lien amount', '0')
+    .option('--heloc <amount>', 'HELOC amount', '0')
+    .option('--credit-score <score>', 'Credit score for PMI estimate', '720')
+    .option('--format <type>', 'Output format (json|table)', 'table')
+    .action(async (options) => {
+      try {
+        const propertyValue = parseFloat(options.propertyValue);
+        let loanAmount: number;
+
+        if (options.loanAmount) {
+          loanAmount = parseFloat(options.loanAmount);
+        } else if (options.downPayment) {
+          loanAmount = propertyValue - parseFloat(options.downPayment);
+        } else {
+          console.error('Error: Must specify either --loan-amount or --down-payment');
+          process.exit(1);
+        }
+
+        const secondLien = parseFloat(options.secondLien);
+        const heloc = parseFloat(options.heloc);
+        const creditScore = parseInt(options.creditScore);
+
+        const ltvResult = calculateLtv(propertyValue, loanAmount, secondLien, heloc);
+        const pmiResult = calculatePmi({
+          ltv: ltvResult.ltv,
+          creditScore,
+          loanAmount,
+        });
+
+        const downPayment = propertyValue - loanAmount;
+        const downPaymentPct = (downPayment / propertyValue) * 100;
+
+        if (options.format === 'json') {
+          console.log(JSON.stringify({ 
+            propertyValue,
+            loanAmount,
+            downPayment,
+            downPaymentPct: Math.round(downPaymentPct * 100) / 100,
+            ...ltvResult,
+            pmi: pmiResult,
+          }, null, 2));
+        } else {
+          console.log('═══════════════════════════════════════════════════════════════');
+          console.log('LTV CALCULATION');
+          console.log('═══════════════════════════════════════════════════════════════');
+          console.log('');
+          console.log(`Property Value:     $${propertyValue.toLocaleString()}`);
+          console.log(`Loan Amount:        $${loanAmount.toLocaleString()}`);
+          console.log(`Down Payment:       $${downPayment.toLocaleString()} (${downPaymentPct.toFixed(1)}%)`);
+          console.log('');
+          console.log('LTV RATIOS');
+          console.log('───────────────────────────────────────────────────────────────');
+          console.log(`LTV:                ${ltvResult.ltv.toFixed(2)}%`);
+          if (secondLien > 0 || heloc > 0) {
+            console.log(`CLTV:               ${ltvResult.cltv.toFixed(2)}%`);
+            console.log(`HCLTV:              ${ltvResult.hcltv.toFixed(2)}%`);
+          }
+          console.log('');
+          
+          if (pmiResult.required) {
+            console.log('PMI ESTIMATE');
+            console.log('───────────────────────────────────────────────────────────────');
+            console.log(`PMI Required:       Yes`);
+            console.log(`Monthly PMI:        $${pmiResult.monthlyAmount.toLocaleString()}`);
+            console.log(`Annual PMI:         $${pmiResult.annualAmount.toLocaleString()}`);
+            console.log(`PMI Rate:           ${pmiResult.ratePercent}%`);
+            console.log(`Auto-Cancel at:     ${pmiResult.cancellationLtv}% LTV`);
+            if (pmiResult.monthsToCancel) {
+              console.log(`Est. Months to Cancel: ~${pmiResult.monthsToCancel}`);
+            }
+          } else {
+            console.log('PMI:                Not required (LTV ≤ 80%)'  );
+          }
+          
+          console.log('═══════════════════════════════════════════════════════════════');
+        }
+      } catch (error: any) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+      }
+    });
+
+  return ltv;
+}

package/src/commands/payment.ts

@@ -0,0 +1,100 @@
+/**
+ * mortctl payment command - Calculate monthly payment breakdown
+ */
+
+import { Command } from 'commander';
+import { calculatePaymentBreakdown, calculateMonthlyPayment } from '../lib/calculations';
+import { LoanScenario, PropertyType, OccupancyType, LoanPurpose } from '../types';
+
+export function createPaymentCommand(): Command {
+  const payment = new Command('payment')
+    .description('Calculate monthly payment breakdown (PITI)')
+    .requiredOption('--loan-amount <amount>', 'Loan amount')
+    .requiredOption('--rate <percent>', 'Interest rate (e.g., 6.5)')
+    .option('--term <years>', 'Loan term in years', '30')
+    .option('--property-value <amount>', 'Property value (for PMI/tax estimates)')
+    .option('--credit-score <score>', 'Credit score (for PMI)', '720')
+    .option('--taxes <amount>', 'Annual property taxes')
+    .option('--insurance <amount>', 'Annual homeowners insurance')
+    .option('--hoa <amount>', 'Monthly HOA dues', '0')
+    .option('--format <type>', 'Output format (json|table)', 'table')
+    .action(async (options) => {
+      try {
+        const loanAmount = parseFloat(options.loanAmount);
+        const rate = parseFloat(options.rate);
+        const term = parseInt(options.term);
+        const propertyValue = options.propertyValue ? parseFloat(options.propertyValue) : loanAmount * 1.25;
+
+        const scenario: LoanScenario = {
+          propertyValue,
+          loanAmount,
+          downPayment: propertyValue - loanAmount,
+          interestRate: rate,
+          termYears: term,
+          creditScore: parseInt(options.creditScore),
+          propertyType: 'single-family' as PropertyType,
+          occupancy: 'primary' as OccupancyType,
+          purpose: 'purchase' as LoanPurpose,
+          propertyTaxes: options.taxes ? parseFloat(options.taxes) : undefined,
+          homeownersInsurance: options.insurance ? parseFloat(options.insurance) : undefined,
+          hoaDues: parseFloat(options.hoa),
+        };
+
+        const breakdown = calculatePaymentBreakdown(scenario);
+        const ltv = (loanAmount / propertyValue * 100);
+
+        // Calculate total interest over life of loan
+        const piOnly = calculateMonthlyPayment(loanAmount, rate, term);
+        const totalPayments = piOnly * term * 12;
+        const totalInterest = totalPayments - loanAmount;
+
+        if (options.format === 'json') {
+          console.log(JSON.stringify({
+            loanAmount,
+            interestRate: rate,
+            termYears: term,
+            ltv: Math.round(ltv * 100) / 100,
+            breakdown,
+            lifetime: {
+              totalPayments: Math.round(totalPayments),
+              totalInterest: Math.round(totalInterest),
+            },
+          }, null, 2));
+        } else {
+          console.log('═══════════════════════════════════════════════════════════════');
+          console.log('MONTHLY PAYMENT BREAKDOWN');
+          console.log('═══════════════════════════════════════════════════════════════');
+          console.log('');
+          console.log(`Loan Amount:        $${loanAmount.toLocaleString()}`);
+          console.log(`Interest Rate:      ${rate}%`);
+          console.log(`Term:               ${term} years`);
+          console.log(`LTV:                ${ltv.toFixed(1)}%`);
+          console.log('');
+          console.log('PAYMENT BREAKDOWN');
+          console.log('───────────────────────────────────────────────────────────────');
+          console.log(`Principal & Interest:    $${breakdown.principalAndInterest.toLocaleString().padStart(10)}`);
+          console.log(`Property Taxes:          $${breakdown.propertyTaxes.toLocaleString().padStart(10)}`);
+          console.log(`Homeowners Insurance:    $${breakdown.homeownersInsurance.toLocaleString().padStart(10)}`);
+          if (breakdown.mortgageInsurance > 0) {
+            console.log(`Mortgage Insurance:      $${breakdown.mortgageInsurance.toLocaleString().padStart(10)}`);
+          }
+          if (breakdown.hoaDues > 0) {
+            console.log(`HOA Dues:                $${breakdown.hoaDues.toLocaleString().padStart(10)}`);
+          }
+          console.log('───────────────────────────────────────────────────────────────');
+          console.log(`TOTAL PAYMENT:           $${breakdown.totalPayment.toLocaleString().padStart(10)}`);
+          console.log('');
+          console.log('LOAN LIFETIME');
+          console.log('───────────────────────────────────────────────────────────────');
+          console.log(`Total Payments:      $${Math.round(totalPayments).toLocaleString()}`);
+          console.log(`Total Interest:      $${Math.round(totalInterest).toLocaleString()}`);
+          console.log('═══════════════════════════════════════════════════════════════');
+        }
+      } catch (error: any) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+      }
+    });
+
+  return payment;
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+/**
+ * mortctl - Mortgage underwriting calculations and eligibility
+ * Part of the LendCtl Suite
+ */
+
+import { Command } from 'commander';
+import { createLtvCommand } from './commands/ltv';
+import { createEligibleCommand } from './commands/eligible';
+import { createPaymentCommand } from './commands/payment';
+import { createLimitsCommand } from './commands/limits';
+
+const program = new Command();
+
+program
+  .name('mortctl')
+  .description('Mortgage underwriting calculations and eligibility - part of the LendCtl Suite')
+  .version('0.1.0');
+
+// Add commands
+program.addCommand(createLtvCommand());
+program.addCommand(createEligibleCommand());
+program.addCommand(createPaymentCommand());
+program.addCommand(createLimitsCommand());
+
+program.parse();
+
+// Export library components for programmatic use
+export * from './lib/calculations';
+export * from './lib/eligibility';
+export * from './types';