phase-2: extract shared utils

server/market/BenchmarkProvider.js

@@ -0,0 +1,73 @@
+import { YahooClient } from './YahooClient.js';
+import { REGIME } from '../config/constants.js';
+
+const TTL_MS = 60 * 60 * 1000;
+
+const DEFAULTS = {
+  sp500Price: 5000,
+  riskFreeRate: 4.5,
+  vixLevel: 20,
+  rateRegime: REGIME.HIGH,
+  volatilityRegime: REGIME.NORMAL,
+  benchmarks: { marketPE: 22, techPE: 30, reitYield: 3.5, igSpread: 1.0 },
+};
+
+const rateRegime = (rate) => (rate < 2 ? REGIME.LOW : rate <= 5 ? REGIME.NORMAL : REGIME.HIGH);
+const volRegime = (vix) => (vix < 15 ? REGIME.LOW : vix <= 25 ? REGIME.NORMAL : REGIME.HIGH);
+
+const pe = (summary) =>
+  summary.summaryDetail?.trailingPE ?? summary.defaultKeyStatistics?.forwardPE;
+
+export class BenchmarkProvider {
+  // logger: object with .warn() — defaults to console so CLI behaviour is unchanged.
+  constructor({ logger = console } = {}) {
+    this.client = new YahooClient();
+    this.cache = { data: null, expiresAt: 0 };
+    this.logger = logger;
+  }
+
+  async getMarketContext() {
+    if (this.cache.data && Date.now() < this.cache.expiresAt) return this.cache.data;
+
+    try {
+      const [sp500, tn10y, vix, spy, xlk, xlre, lqd] = await Promise.all([
+        this.client.fetchSummary('^GSPC'),
+        this.client.fetchSummary('^TNX'),
+        this.client.fetchSummary('^VIX'),
+        this.client.fetchSummary('SPY'),
+        this.client.fetchSummary('XLK'),
+        this.client.fetchSummary('XLRE'),
+        this.client.fetchSummary('LQD'),
+      ]);
+
+      const riskFreeRate = tn10y.price?.regularMarketPrice ?? 0;
+      const sp500Price = sp500.price?.regularMarketPrice ?? 0;
+      const vixLevel = vix.price?.regularMarketPrice ?? 0;
+
+      if (!sp500Price || !riskFreeRate) throw new Error('Invalid market data (zero values)');
+
+      const lqdYield = (lqd.summaryDetail?.trailingAnnualDividendYield ?? 0) * 100;
+
+      const context = {
+        sp500Price,
+        riskFreeRate,
+        vixLevel,
+        rateRegime: rateRegime(riskFreeRate),
+        volatilityRegime: volRegime(vixLevel),
+        benchmarks: {
+          marketPE: pe(spy) ?? 22,
+          techPE: pe(xlk) ?? 30,
+          reitYield: (xlre.summaryDetail?.trailingAnnualDividendYield ?? 0.035) * 100,
+          igSpread: Math.max(0.1, lqdYield - riskFreeRate),
+        },
+        timestamp: new Date().toISOString(),
+      };
+
+      this.cache = { data: context, expiresAt: Date.now() + TTL_MS };
+      return context;
+    } catch (err) {
+      this.logger.warn('Market data fetch failed, using defaults:', err.message);
+      return this.cache.data ?? DEFAULTS;
+    }
+  }
+}

server/market/MarketRegime.js

@@ -0,0 +1,63 @@
+import { SECTOR, ASSET_TYPE, REGIME } from '../config/constants.js';
+
+export class MarketRegime {
+  constructor(marketContext) {
+    const b = marketContext?.benchmarks ?? {};
+    this.marketPE = b.marketPE ?? 22;
+    this.techPE = b.techPE ?? 30;
+    this.reitYield = b.reitYield ?? 3.5;
+    this.igSpread = b.igSpread ?? 1.0;
+    this.rateRegime = marketContext?.rateRegime ?? REGIME.NORMAL;
+    this.volatilityRegime = marketContext?.volatilityRegime ?? REGIME.NORMAL;
+  }
+
+  getInflatedOverrides(type, sector) {
+    if (type === ASSET_TYPE.STOCK) return this._stock(sector);
+    if (type === ASSET_TYPE.ETF) return this._etf();
+    if (type === ASSET_TYPE.BOND) return this._bond();
+    return { gates: {}, thresholds: {} };
+  }
+
+  _stock(sector) {
+    if (sector === SECTOR.REIT) {
+      return {
+        gates: {},
+        // In HIGH rate environment tighten REIT yield floor — REITs must compete harder with bonds.
+        thresholds: {
+          minYield: +(this.reitYield * (this.rateRegime === REGIME.HIGH ? 0.95 : 0.85)).toFixed(2),
+          maxPFFO: 20,
+        },
+      };
+    }
+    if (sector === SECTOR.TECHNOLOGY) {
+      return {
+        gates: {
+          maxPERatio: Math.round(this.techPE * 1.3),
+          maxPegGate: +(this.techPE / 15).toFixed(1),
+        },
+        thresholds: {},
+      };
+    }
+    // In HIGH rate environment, compress the P/E tolerance — higher rates mean
+    // future earnings are discounted more aggressively (lower DCF valuations).
+    const peMultiplier = this.rateRegime === REGIME.HIGH ? 1.2 : 1.5;
+    return {
+      gates: {
+        maxPERatio: Math.round(this.marketPE * peMultiplier),
+        maxPegGate: +(this.marketPE / 12).toFixed(1),
+      },
+      thresholds: {},
+    };
+  }
+
+  _etf() {
+    return { gates: { maxExpenseRatio: 0.75 }, thresholds: { minYield: 0.5 } };
+  }
+
+  _bond() {
+    // In HIGH rate environment demand a wider spread — the opportunity cost of holding
+    // corporate bonds over Treasuries is higher when risk-free rate is elevated.
+    const spreadMultiplier = this.rateRegime === REGIME.HIGH ? 0.9 : 0.8;
+    return { gates: {}, thresholds: { minSpread: +(this.igSpread * spreadMultiplier).toFixed(2) } };
+  }
+}

server/market/YahooClient.js

@@ -0,0 +1,40 @@
+import YahooFinance from 'yahoo-finance2';
+
+export class YahooClient {
+  constructor() {
+    // Instantiate the client as required by v3
+    this.yf = new YahooFinance({
+      suppressNotices: ['yahooSurvey'],
+    });
+  }
+
+  async fetchSummary(ticker, retries = 3, backoff = 1000) {
+    for (let i = 0; i < retries; i++) {
+      try {
+        return await this.yf.quoteSummary(ticker, {
+          modules: [
+            'assetProfile',
+            'financialData',
+            'defaultKeyStatistics',
+            'price',
+            'summaryDetail',
+          ],
+        });
+      } catch (error) {
+        if (i === retries - 1) throw error;
+        await new Promise((res) => setTimeout(res, backoff * (i + 1)));
+      }
+    }
+  }
+
+  // Fetches upcoming earnings dates, ex-dividend date, and dividend date for a ticker.
+  // Returns null on failure so callers can skip gracefully.
+  async fetchCalendarEvents(ticker) {
+    try {
+      const r = await this.yf.quoteSummary(ticker, { modules: ['calendarEvents'] });
+      return r.calendarEvents ?? null;
+    } catch {
+      return null;
+    }
+  }
+}