bbdata-cli 0.1.1 → 0.3.0

package/dist/templates/queries/matchup-situational.ts

@@ -0,0 +1,68 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PlayerStats } from '../../adapters/types.js';
+
+const template: QueryTemplate = {
+  id: 'matchup-situational',
+  name: 'Situational Splits',
+  category: 'matchup',
+  description: 'Performance in key situations — RISP, high leverage, close & late, by inning',
+  preferredSources: ['fangraphs', 'mlb-stats-api'],
+  requiredParams: ['player'],
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query matchup-situational --player "Juan Soto" --season 2025',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'batting',
+    };
+  },
+
+  columns() {
+    return ['Situation', 'PA', 'AVG', 'OBP', 'SLG', 'K %', 'BB %'];
+  },
+
+  transform(data) {
+    // Situational splits typically come pre-computed from FanGraphs
+    // With raw pitch data this would require game state context
+    // This template works best with FanGraphs/MLB API aggregated splits
+    const stats = data as PlayerStats[];
+
+    if (stats.length === 0) return [];
+
+    const player = stats[0];
+    const s = player.stats;
+
+    // Return whatever aggregated stats we have — format for display
+    return [
+      {
+        Situation: 'Overall',
+        PA: s.plateAppearances ?? s.PA ?? '—',
+        AVG: formatStat(s.avg ?? s.AVG),
+        OBP: formatStat(s.obp ?? s.OBP),
+        SLG: formatStat(s.slg ?? s.SLG),
+        'K %': formatPct(s.strikeOuts ?? s.SO, s.plateAppearances ?? s.PA),
+        'BB %': formatPct(s.baseOnBalls ?? s.BB, s.plateAppearances ?? s.PA),
+      },
+    ];
+  },
+};
+
+function formatStat(val: unknown): string {
+  if (val === null || val === undefined) return '—';
+  const n = Number(val);
+  if (isNaN(n)) return String(val);
+  return n < 1 ? n.toFixed(3) : n.toFixed(1);
+}
+
+function formatPct(num: unknown, denom: unknown): string {
+  const n = Number(num);
+  const d = Number(denom);
+  if (isNaN(n) || isNaN(d) || d === 0) return '—';
+  return ((n / d) * 100).toFixed(1) + '%';
+}
+
+registerTemplate(template);

package/dist/templates/queries/pitcher-arsenal.ts

@@ -0,0 +1,89 @@
+import { registerTemplate, type QueryTemplate, type QueryTemplateParams } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+import { pitchTypeName } from '../../adapters/types.js';
+
+const template: QueryTemplate = {
+  id: 'pitcher-arsenal',
+  name: 'Pitcher Arsenal Profile',
+  category: 'pitcher',
+  description: 'Pitch usage rates, velocity, spin, movement, and whiff rates by pitch type',
+  preferredSources: ['savant', 'fangraphs', 'mlb-stats-api'],
+  requiredParams: ['player'],
+  optionalParams: ['season', 'pitchType'],
+  examples: [
+    'bbdata query pitcher-arsenal --player "Corbin Burnes" --season 2025',
+    'bbdata query pitcher-arsenal --player "Spencer Strider"',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'pitching',
+      pitch_type: params.pitchType ? [params.pitchType] : undefined,
+    };
+  },
+
+  columns() {
+    return [
+      'Pitch Type',
+      'Usage %',
+      'Avg Velo',
+      'Avg Spin',
+      'H Break',
+      'V Break',
+      'Whiff %',
+      'Put Away %',
+      'Pitches',
+    ];
+  },
+
+  transform(data, _params) {
+    const pitches = data as PitchData[];
+    if (pitches.length === 0) return [];
+
+    // Group by pitch type
+    const byType = new Map<string, PitchData[]>();
+    for (const pitch of pitches) {
+      if (!pitch.pitch_type) continue;
+      const group = byType.get(pitch.pitch_type) ?? [];
+      group.push(pitch);
+      byType.set(pitch.pitch_type, group);
+    }
+
+    const total = pitches.length;
+
+    return Array.from(byType.entries())
+      .map(([type, group]) => {
+        const count = group.length;
+        const swings = group.filter((p) =>
+          p.description.includes('swing') || p.description.includes('foul'),
+        );
+        const whiffs = group.filter((p) =>
+          p.description.includes('swinging_strike'),
+        );
+        const twoStrikes = group.filter((p) =>
+          p.description.includes('strikeout') || p.description.includes('swinging_strike'),
+        );
+
+        return {
+          'Pitch Type': pitchTypeName(type),
+          'Usage %': ((count / total) * 100).toFixed(1) + '%',
+          'Avg Velo': (group.reduce((s, p) => s + p.release_speed, 0) / count).toFixed(1) + ' mph',
+          'Avg Spin': Math.round(group.reduce((s, p) => s + p.release_spin_rate, 0) / count) + ' rpm',
+          'H Break': (group.reduce((s, p) => s + p.pfx_x, 0) / count).toFixed(1) + ' in',
+          'V Break': (group.reduce((s, p) => s + p.pfx_z, 0) / count).toFixed(1) + ' in',
+          'Whiff %': swings.length > 0
+            ? ((whiffs.length / swings.length) * 100).toFixed(1) + '%'
+            : '—',
+          'Put Away %': twoStrikes.length > 0
+            ? ((whiffs.length / count) * 100).toFixed(1) + '%'
+            : '—',
+          'Pitches': count,
+        };
+      })
+      .sort((a, b) => (b.Pitches as number) - (a.Pitches as number));
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/pitcher-handedness-splits.ts

@@ -0,0 +1,81 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+
+const template: QueryTemplate = {
+  id: 'pitcher-handedness-splits',
+  name: 'Pitcher Handedness Splits',
+  category: 'pitcher',
+  description: 'Performance splits vs LHH and RHH — BA, SLG, K%, BB%, pitch mix, exit velocity',
+  preferredSources: ['savant', 'fangraphs'],
+  requiredParams: ['player'],
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query pitcher-handedness-splits --player "Blake Snell" --season 2025',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'pitching',
+    };
+  },
+
+  columns() {
+    return ['vs', 'PA', 'AVG', 'SLG', 'K %', 'BB %', 'Avg EV', 'Whiff %'];
+  },
+
+  transform(data) {
+    const pitches = data as PitchData[];
+    if (pitches.length === 0) return [];
+
+    return (['L', 'R'] as const).map((hand) => {
+      const group = pitches.filter((p) => p.stand === hand);
+      if (group.length === 0) {
+        return { vs: `vs ${hand}HH`, PA: 0, AVG: '—', SLG: '—', 'K %': '—', 'BB %': '—', 'Avg EV': '—', 'Whiff %': '—' };
+      }
+
+      // Plate appearances (approximate: count events)
+      const pas = group.filter((p) => p.events !== null);
+      const hits = pas.filter((p) =>
+        ['single', 'double', 'triple', 'home_run'].includes(p.events ?? ''),
+      );
+      const strikeouts = pas.filter((p) => p.events === 'strikeout');
+      const walks = pas.filter((p) => ['walk', 'hit_by_pitch'].includes(p.events ?? ''));
+
+      // Exit velocity on contact
+      const contacted = group.filter((p) => p.launch_speed !== null && p.launch_speed > 0);
+      const avgEv = contacted.length > 0
+        ? contacted.reduce((s, p) => s + (p.launch_speed ?? 0), 0) / contacted.length
+        : null;
+
+      // Total bases for SLG
+      const totalBases = pas.reduce((sum, p) => {
+        if (p.events === 'single') return sum + 1;
+        if (p.events === 'double') return sum + 2;
+        if (p.events === 'triple') return sum + 3;
+        if (p.events === 'home_run') return sum + 4;
+        return sum;
+      }, 0);
+
+      // Whiff rate
+      const swings = group.filter((p) =>
+        p.description.includes('swing') || p.description.includes('foul'),
+      );
+      const whiffs = group.filter((p) => p.description.includes('swinging_strike'));
+
+      return {
+        vs: `vs ${hand}HH`,
+        PA: pas.length,
+        AVG: pas.length > 0 ? (hits.length / pas.length).toFixed(3) : '—',
+        SLG: pas.length > 0 ? (totalBases / pas.length).toFixed(3) : '—',
+        'K %': pas.length > 0 ? ((strikeouts.length / pas.length) * 100).toFixed(1) + '%' : '—',
+        'BB %': pas.length > 0 ? ((walks.length / pas.length) * 100).toFixed(1) + '%' : '—',
+        'Avg EV': avgEv !== null ? avgEv.toFixed(1) + ' mph' : '—',
+        'Whiff %': swings.length > 0 ? ((whiffs.length / swings.length) * 100).toFixed(1) + '%' : '—',
+      };
+    });
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/pitcher-raw-pitches.ts

@@ -0,0 +1,62 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+
+/**
+ * Raw pitch-level projection — one row per pitch, coordinate columns preserved.
+ * Powers the pitch-movement visualization (pfx_x, pfx_z scatter).
+ * Unlike pitcher-arsenal this does NOT aggregate; viz builders need per-pitch points.
+ */
+const template: QueryTemplate = {
+  id: 'pitcher-raw-pitches',
+  name: 'Pitcher Raw Pitches',
+  category: 'pitcher',
+  description: 'One row per pitch with coordinate columns for visualization (movement, location)',
+  preferredSources: ['savant'],
+  requiredParams: ['player'],
+  optionalParams: ['season', 'pitchType'],
+  examples: [
+    'bbdata query pitcher-raw-pitches --player "Corbin Burnes" --season 2025 --format json',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'pitching',
+      pitch_type: params.pitchType ? [params.pitchType] : undefined,
+    };
+  },
+
+  columns() {
+    return [
+      'pitch_type',
+      'release_speed',
+      'release_spin_rate',
+      'pfx_x',
+      'pfx_z',
+      'plate_x',
+      'plate_z',
+      'game_date',
+    ];
+  },
+
+  transform(data) {
+    const pitches = data as PitchData[];
+    if (pitches.length === 0) return [];
+
+    return pitches
+      .filter((p) => p.pitch_type)
+      .map((p) => ({
+        pitch_type: p.pitch_type,
+        release_speed: p.release_speed,
+        release_spin_rate: p.release_spin_rate,
+        pfx_x: p.pfx_x,
+        pfx_z: p.pfx_z,
+        plate_x: p.plate_x,
+        plate_z: p.plate_z,
+        game_date: p.game_date,
+      }));
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/pitcher-velocity-trend.ts

@@ -0,0 +1,73 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+import { pitchTypeName } from '../../adapters/types.js';
+
+const template: QueryTemplate = {
+  id: 'pitcher-velocity-trend',
+  name: 'Pitcher Velocity Trend',
+  category: 'pitcher',
+  description: 'Month-by-month fastball velocity tracking — flags drops > 0.5 mph',
+  preferredSources: ['savant'],
+  requiredParams: ['player'],
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query pitcher-velocity-trend --player "Gerrit Cole" --season 2025',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'pitching',
+    };
+  },
+
+  columns() {
+    return ['Month', 'Avg Velo', 'Max Velo', 'Min Velo', 'Δ vs Prior', 'Pitches', 'Flag'];
+  },
+
+  transform(data) {
+    const pitches = (data as PitchData[]).filter(
+      (p) => ['FF', 'SI', 'FC'].includes(p.pitch_type) && p.release_speed > 0,
+    );
+
+    if (pitches.length === 0) return [];
+
+    // Group by month
+    const byMonth = new Map<string, PitchData[]>();
+    for (const pitch of pitches) {
+      const month = pitch.game_date.slice(0, 7); // YYYY-MM
+      const group = byMonth.get(month) ?? [];
+      group.push(pitch);
+      byMonth.set(month, group);
+    }
+
+    const months = Array.from(byMonth.entries()).sort(([a], [b]) => a.localeCompare(b));
+    let prevAvg: number | null = null;
+
+    return months.map(([month, group]) => {
+      const velos = group.map((p) => p.release_speed);
+      const avg = velos.reduce((s, v) => s + v, 0) / velos.length;
+      const max = Math.max(...velos);
+      const min = Math.min(...velos);
+
+      const delta = prevAvg !== null ? avg - prevAvg : 0;
+      const flag = prevAvg !== null && delta < -0.5 ? '⚠ DROP' : '';
+      prevAvg = avg;
+
+      return {
+        Month: month,
+        'Avg Velo': avg.toFixed(1) + ' mph',
+        'Max Velo': max.toFixed(1) + ' mph',
+        'Min Velo': min.toFixed(1) + ' mph',
+        'Δ vs Prior': prevAvg !== null && delta !== 0
+          ? (delta > 0 ? '+' : '') + delta.toFixed(1) + ' mph'
+          : '—',
+        Pitches: group.length,
+        Flag: flag,
+      };
+    });
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/registry.ts

@@ -0,0 +1,73 @@
+import type { DataSource, AdapterQuery, PitchData, PlayerStats } from '../../adapters/types.js';
+
+export type QueryCategory = 'pitcher' | 'hitter' | 'matchup' | 'leaderboard' | 'trend';
+
+export interface QueryTemplateParams {
+  player?: string;
+  players?: string[];
+  team?: string;
+  season?: number;
+  stat?: string;
+  pitchType?: string;
+  minPa?: number;
+  minIp?: number;
+  top?: number;
+  seasons?: string; // "2023-2025"
+}
+
+export interface QueryResult {
+  rows: Record<string, unknown>[];
+  columns: string[];
+  title: string;
+  description: string;
+  source: DataSource;
+  cached: boolean;
+}
+
+export interface QueryTemplate {
+  id: string;
+  name: string;
+  category: QueryCategory;
+  description: string;
+  preferredSources: DataSource[];
+  requiredParams: (keyof QueryTemplateParams)[];
+  optionalParams: (keyof QueryTemplateParams)[];
+  examples: string[];
+
+  /** Build the adapter query from user-provided params */
+  buildQuery(params: QueryTemplateParams): AdapterQuery;
+
+  /** Transform raw adapter data into display rows */
+  transform(data: PitchData[] | PlayerStats[], params: QueryTemplateParams): Record<string, unknown>[];
+
+  /** Column names for display */
+  columns(params: QueryTemplateParams): string[];
+}
+
+// Template registry
+const templates = new Map<string, QueryTemplate>();
+
+export function registerTemplate(template: QueryTemplate): void {
+  templates.set(template.id, template);
+}
+
+export function getTemplate(id: string): QueryTemplate | undefined {
+  return templates.get(id);
+}
+
+export function getAllTemplates(): QueryTemplate[] {
+  return Array.from(templates.values());
+}
+
+export function getTemplatesByCategory(category: QueryCategory): QueryTemplate[] {
+  return getAllTemplates().filter((t) => t.category === category);
+}
+
+export function listTemplates(): { id: string; name: string; category: string; description: string }[] {
+  return getAllTemplates().map((t) => ({
+    id: t.id,
+    name: t.name,
+    category: t.category,
+    description: t.description,
+  }));
+}

package/dist/templates/queries/trend-rolling-average.ts

@@ -0,0 +1,98 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+
+const template: QueryTemplate = {
+  id: 'trend-rolling-average',
+  name: 'Season Trend (Rolling Average)',
+  category: 'trend',
+  description: '15-game (hitters) or 5-start (pitchers) rolling averages — identifies sustained trends',
+  preferredSources: ['savant'],
+  requiredParams: ['player'],
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query trend-rolling-average --player "Freddie Freeman" --season 2025',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'batting',
+    };
+  },
+
+  columns() {
+    return ['Window', 'Window End', 'Games', 'AVG', 'SLG', 'K %', 'Avg EV', 'Hard Hit %'];
+  },
+
+  transform(data) {
+    const pitches = data as PitchData[];
+    if (pitches.length === 0) return [];
+
+    // Group by game date
+    const byDate = new Map<string, PitchData[]>();
+    for (const p of pitches) {
+      const group = byDate.get(p.game_date) ?? [];
+      group.push(p);
+      byDate.set(p.game_date, group);
+    }
+
+    const dates = Array.from(byDate.keys()).sort();
+    const windowSize = 15;
+
+    if (dates.length < windowSize) {
+      return [{
+        Window: 'Insufficient data',
+        'Window End': '',
+        Games: dates.length,
+        AVG: '—',
+        SLG: '—',
+        'K %': '—',
+        'Avg EV': '—',
+        'Hard Hit %': '—',
+      }];
+    }
+
+    // Calculate rolling windows
+    const results: Record<string, unknown>[] = [];
+
+    for (let i = 0; i <= dates.length - windowSize; i += Math.max(1, Math.floor(windowSize / 3))) {
+      const windowDates = dates.slice(i, i + windowSize);
+      const windowPitches = windowDates.flatMap((d) => byDate.get(d) ?? []);
+
+      const pas = windowPitches.filter((p) => p.events !== null);
+      const hits = pas.filter((p) => ['single', 'double', 'triple', 'home_run'].includes(p.events ?? ''));
+      const ks = pas.filter((p) => p.events === 'strikeout');
+      const totalBases = pas.reduce((sum, p) => {
+        if (p.events === 'single') return sum + 1;
+        if (p.events === 'double') return sum + 2;
+        if (p.events === 'triple') return sum + 3;
+        if (p.events === 'home_run') return sum + 4;
+        return sum;
+      }, 0);
+
+      const batted = windowPitches.filter((p) => p.launch_speed !== null && p.launch_speed > 0);
+      const avgEv = batted.length > 0
+        ? batted.reduce((s, p) => s + p.launch_speed!, 0) / batted.length
+        : null;
+      const hardHit = batted.filter((p) => p.launch_speed! >= 95).length;
+
+      const windowEnd = windowDates[windowDates.length - 1]!;
+
+      results.push({
+        Window: `${windowDates[0]} → ${windowEnd}`,
+        'Window End': windowEnd,
+        Games: windowDates.length,
+        AVG: pas.length > 0 ? (hits.length / pas.length).toFixed(3) : '—',
+        SLG: pas.length > 0 ? (totalBases / pas.length).toFixed(3) : '—',
+        'K %': pas.length > 0 ? ((ks.length / pas.length) * 100).toFixed(1) + '%' : '—',
+        'Avg EV': avgEv !== null ? avgEv.toFixed(1) + ' mph' : '—',
+        'Hard Hit %': batted.length > 0 ? ((hardHit / batted.length) * 100).toFixed(1) + '%' : '—',
+      });
+    }
+
+    return results;
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/trend-year-over-year.ts

@@ -0,0 +1,73 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PlayerStats } from '../../adapters/types.js';
+
+const template: QueryTemplate = {
+  id: 'trend-year-over-year',
+  name: 'Year-over-Year Comparison',
+  category: 'trend',
+  description: 'Compare metric changes year to year — flags changes greater than 10%',
+  preferredSources: ['fangraphs', 'mlb-stats-api'],
+  requiredParams: ['player'],
+  optionalParams: ['seasons'], // e.g. "2023-2025"
+  examples: [
+    'bbdata query trend-year-over-year --player "Julio Rodriguez" --seasons 2023-2025',
+  ],
+
+  buildQuery(params) {
+    // We'll need multiple seasons — use the most recent by default
+    const season = params.season ?? new Date().getFullYear();
+    return {
+      player_name: params.player,
+      season,
+      stat_type: 'batting',
+    };
+  },
+
+  columns() {
+    return ['Metric', 'Prior', 'Current', 'Change', 'Flag'];
+  },
+
+  transform(data, params) {
+    const stats = data as PlayerStats[];
+    if (stats.length === 0) return [];
+
+    // If we have multi-season data, compare last two
+    // With single-season data, we show what we have
+    const player = stats[0];
+    const s = player.stats;
+
+    // Key metrics to compare
+    const metrics = ['AVG', 'OBP', 'SLG', 'HR', 'wRC+', 'K%', 'BB%', 'WAR', 'ISO', 'BABIP'];
+
+    return metrics.map((metric) => {
+      const current = findStat(s, metric);
+      // Without multi-season support in a single query, we show current only
+      // Full YoY requires querying multiple seasons (future enhancement)
+      return {
+        Metric: metric,
+        Prior: '—',
+        Current: current !== null ? formatVal(current) : '—',
+        Change: '—',
+        Flag: '',
+      };
+    });
+  },
+};
+
+function findStat(stats: Record<string, unknown>, key: string): number | null {
+  const lower = key.toLowerCase().replace(/[+%]/g, '');
+  for (const [k, v] of Object.entries(stats)) {
+    if (k.toLowerCase().replace(/[+%]/g, '') === lower) {
+      const n = Number(v);
+      return isNaN(n) ? null : n;
+    }
+  }
+  return null;
+}
+
+function formatVal(n: number): string {
+  if (n < 1 && n > 0) return n.toFixed(3);
+  return n % 1 === 0 ? String(n) : n.toFixed(1);
+}
+
+registerTemplate(template);

package/dist/templates/reports/advance-lineup.hbs

@@ -0,0 +1,29 @@
+# Advance Report: {{team}} Lineup
+
+**Season:** {{season}} | **For:** {{audience}} | **Generated:** {{date}}
+
+---
+
+## Header
+
+| Field | Value |
+|-------|-------|
+| Opponent | {{team}} |
+| Season | {{season}} |
+
+## Lineup Overview
+
+*Projected lineup, team tendencies, overall approach — to be populated*
+
+## Hitter Breakdowns
+
+*Individual hitter cards — to be generated per player:*
+*Strengths, weaknesses, pitch approach, hot/cold zones*
+
+## Key Matchups
+
+*Critical at-bats to plan for — to be filled by coaching staff*
+
+---
+
+*Generated by bbdata CLI · 1-page advance format*