bbdata-cli 0.1.1 → 0.3.0

package/dist/templates/queries/hitter-batted-ball.ts

@@ -0,0 +1,66 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+
+const template: QueryTemplate = {
+  id: 'hitter-batted-ball',
+  name: 'Hitter Batted Ball Profile',
+  category: 'hitter',
+  description: 'Exit velocity, launch angle, hard hit rate, barrel rate, batted ball distribution',
+  preferredSources: ['savant', 'fangraphs'],
+  requiredParams: ['player'],
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query hitter-batted-ball --player "Aaron Judge" --season 2025',
+    'bbdata query hitter-batted-ball --player "Juan Soto"',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'batting',
+    };
+  },
+
+  columns() {
+    return ['Metric', 'Value'];
+  },
+
+  transform(data) {
+    const pitches = data as PitchData[];
+    const batted = pitches.filter((p) => p.launch_speed !== null && p.launch_speed > 0);
+
+    if (batted.length === 0) return [];
+
+    const evs = batted.map((p) => p.launch_speed!);
+    const las = batted.map((p) => p.launch_angle!);
+    const avgEv = evs.reduce((s, v) => s + v, 0) / evs.length;
+    const avgLa = las.reduce((s, v) => s + v, 0) / las.length;
+
+    const hardHit = batted.filter((p) => p.launch_speed! >= 95).length;
+    // Barrel = EV >= 98 mph and LA between 26-30 (simplified)
+    const barrels = batted.filter(
+      (p) => p.launch_speed! >= 98 && p.launch_angle! >= 26 && p.launch_angle! <= 30,
+    ).length;
+
+    const linedrives = batted.filter((p) => p.bb_type === 'line_drive').length;
+    const flyballs = batted.filter((p) => p.bb_type === 'fly_ball').length;
+    const groundballs = batted.filter((p) => p.bb_type === 'ground_ball').length;
+    const popups = batted.filter((p) => p.bb_type === 'popup').length;
+
+    return [
+      { Metric: 'Batted Balls', Value: batted.length },
+      { Metric: 'Avg Exit Velocity', Value: avgEv.toFixed(1) + ' mph' },
+      { Metric: 'Max Exit Velocity', Value: Math.max(...evs).toFixed(1) + ' mph' },
+      { Metric: 'Avg Launch Angle', Value: avgLa.toFixed(1) + '°' },
+      { Metric: 'Hard Hit Rate (95+ mph)', Value: ((hardHit / batted.length) * 100).toFixed(1) + '%' },
+      { Metric: 'Barrel Rate', Value: ((barrels / batted.length) * 100).toFixed(1) + '%' },
+      { Metric: 'Line Drive %', Value: ((linedrives / batted.length) * 100).toFixed(1) + '%' },
+      { Metric: 'Fly Ball %', Value: ((flyballs / batted.length) * 100).toFixed(1) + '%' },
+      { Metric: 'Ground Ball %', Value: ((groundballs / batted.length) * 100).toFixed(1) + '%' },
+      { Metric: 'Popup %', Value: ((popups / batted.length) * 100).toFixed(1) + '%' },
+    ];
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/hitter-hot-cold-zones.ts

@@ -0,0 +1,81 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+
+// 3x3 strike zone grid
+const ZONES = {
+  'High-In':    { xMin: -0.83, xMax: -0.28, zMin: 2.83, zMax: 3.5 },
+  'High-Mid':   { xMin: -0.28, xMax: 0.28,  zMin: 2.83, zMax: 3.5 },
+  'High-Out':   { xMin: 0.28,  xMax: 0.83,  zMin: 2.83, zMax: 3.5 },
+  'Mid-In':     { xMin: -0.83, xMax: -0.28, zMin: 2.17, zMax: 2.83 },
+  'Mid-Mid':    { xMin: -0.28, xMax: 0.28,  zMin: 2.17, zMax: 2.83 },
+  'Mid-Out':    { xMin: 0.28,  xMax: 0.83,  zMin: 2.17, zMax: 2.83 },
+  'Low-In':     { xMin: -0.83, xMax: -0.28, zMin: 1.5,  zMax: 2.17 },
+  'Low-Mid':    { xMin: -0.28, xMax: 0.28,  zMin: 1.5,  zMax: 2.17 },
+  'Low-Out':    { xMin: 0.28,  xMax: 0.83,  zMin: 1.5,  zMax: 2.17 },
+} as const;
+
+const template: QueryTemplate = {
+  id: 'hitter-hot-cold-zones',
+  name: 'Hitter Hot/Cold Zones',
+  category: 'hitter',
+  description: '3x3 strike zone grid with BA, SLG, whiff rate, and pitch count per zone',
+  preferredSources: ['savant'],
+  requiredParams: ['player'],
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query hitter-hot-cold-zones --player "Shohei Ohtani" --season 2025',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'batting',
+    };
+  },
+
+  columns() {
+    return ['Zone', 'Pitches', 'Swings', 'Whiff %', 'AVG', 'SLG'];
+  },
+
+  transform(data) {
+    const pitches = data as PitchData[];
+    if (pitches.length === 0) return [];
+
+    return Object.entries(ZONES).map(([zoneName, bounds]) => {
+      const inZone = pitches.filter(
+        (p) =>
+          p.plate_x >= bounds.xMin && p.plate_x < bounds.xMax &&
+          p.plate_z >= bounds.zMin && p.plate_z < bounds.zMax,
+      );
+
+      const swings = inZone.filter((p) =>
+        p.description.includes('swing') || p.description.includes('foul') || p.description.includes('hit_into_play'),
+      );
+      const whiffs = inZone.filter((p) => p.description.includes('swinging_strike'));
+
+      const abs = inZone.filter((p) => p.events && !['walk', 'hit_by_pitch'].includes(p.events));
+      const hits = abs.filter((p) =>
+        ['single', 'double', 'triple', 'home_run'].includes(p.events ?? ''),
+      );
+      const totalBases = abs.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);
+
+      return {
+        Zone: zoneName,
+        Pitches: inZone.length,
+        Swings: swings.length,
+        'Whiff %': swings.length > 0 ? ((whiffs.length / swings.length) * 100).toFixed(1) + '%' : '—',
+        AVG: abs.length > 0 ? (hits.length / abs.length).toFixed(3) : '—',
+        SLG: abs.length > 0 ? (totalBases / abs.length).toFixed(3) : '—',
+      };
+    });
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/hitter-raw-bip.ts

@@ -0,0 +1,65 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+
+/**
+ * Raw batted-ball projection — one row per ball in play with hit coordinates.
+ * Powers the spray chart. Filters to pitches where launch_speed is recorded
+ * (i.e., the ball was actually put in play).
+ */
+const template: QueryTemplate = {
+  id: 'hitter-raw-bip',
+  name: 'Hitter Raw Batted Balls',
+  category: 'hitter',
+  description: 'One row per batted ball with hit coordinates, exit velo, and launch angle',
+  preferredSources: ['savant'],
+  requiredParams: ['player'],
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query hitter-raw-bip --player "Aaron Judge" --season 2025 --format json',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'batting',
+    };
+  },
+
+  columns() {
+    return [
+      'hc_x',
+      'hc_y',
+      'launch_speed',
+      'launch_angle',
+      'events',
+      'bb_type',
+      'game_date',
+    ];
+  },
+
+  transform(data) {
+    const pitches = data as PitchData[];
+    if (pitches.length === 0) return [];
+
+    return pitches
+      .filter(
+        (p) =>
+          p.launch_speed != null &&
+          p.launch_speed > 0 &&
+          p.hc_x != null &&
+          p.hc_y != null,
+      )
+      .map((p) => ({
+        hc_x: p.hc_x,
+        hc_y: p.hc_y,
+        launch_speed: p.launch_speed,
+        launch_angle: p.launch_angle,
+        events: p.events ?? 'unknown',
+        bb_type: p.bb_type ?? 'unknown',
+        game_date: p.game_date,
+      }));
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/hitter-vs-pitch-type.ts

@@ -0,0 +1,78 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+import { pitchTypeName } from '../../adapters/types.js';
+
+const template: QueryTemplate = {
+  id: 'hitter-vs-pitch-type',
+  name: 'Hitter vs Pitch Type',
+  category: 'hitter',
+  description: 'Swing rate, whiff rate, exit velocity, and outcomes by pitch type faced',
+  preferredSources: ['savant'],
+  requiredParams: ['player'],
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query hitter-vs-pitch-type --player "Mookie Betts" --season 2025',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'batting',
+    };
+  },
+
+  columns() {
+    return ['Pitch Type', 'Seen', 'Swing %', 'Whiff %', 'Foul %', 'In Play', 'Avg EV', 'SLG'];
+  },
+
+  transform(data) {
+    const pitches = data as PitchData[];
+    if (pitches.length === 0) return [];
+
+    const byType = new Map<string, PitchData[]>();
+    for (const p of pitches) {
+      if (!p.pitch_type) continue;
+      const group = byType.get(p.pitch_type) ?? [];
+      group.push(p);
+      byType.set(p.pitch_type, group);
+    }
+
+    return Array.from(byType.entries())
+      .map(([type, group]) => {
+        const swings = group.filter((p) =>
+          p.description.includes('swing') || p.description.includes('foul') || p.description.includes('hit_into_play'),
+        );
+        const whiffs = group.filter((p) => p.description.includes('swinging_strike'));
+        const fouls = group.filter((p) => p.description.includes('foul'));
+        const inPlay = group.filter((p) => p.description.includes('hit_into_play'));
+        const contacted = group.filter((p) => p.launch_speed !== null && p.launch_speed > 0);
+
+        // SLG on contact
+        const totalBases = group.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 abs = group.filter((p) => p.events && !['walk', 'hit_by_pitch', 'sac_fly', 'sac_bunt'].includes(p.events)).length;
+
+        return {
+          'Pitch Type': pitchTypeName(type),
+          Seen: group.length,
+          'Swing %': ((swings.length / group.length) * 100).toFixed(1) + '%',
+          'Whiff %': swings.length > 0 ? ((whiffs.length / swings.length) * 100).toFixed(1) + '%' : '—',
+          'Foul %': swings.length > 0 ? ((fouls.length / swings.length) * 100).toFixed(1) + '%' : '—',
+          'In Play': inPlay.length,
+          'Avg EV': contacted.length > 0
+            ? (contacted.reduce((s, p) => s + p.launch_speed!, 0) / contacted.length).toFixed(1) + ' mph'
+            : '—',
+          SLG: abs > 0 ? (totalBases / abs).toFixed(3) : '—',
+        };
+      })
+      .sort((a, b) => (b.Seen as number) - (a.Seen as number));
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/hitter-zone-grid.ts

@@ -0,0 +1,90 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+
+// 3x3 strike zone grid (copied from hitter-hot-cold-zones.ts)
+// row: 0 = high, 2 = low. col: 0 = inside (catcher POV left), 2 = outside.
+const ZONES: { name: string; row: number; col: number; xMin: number; xMax: number; zMin: number; zMax: number }[] = [
+  { name: 'High-In',  row: 0, col: 0, xMin: -0.83, xMax: -0.28, zMin: 2.83, zMax: 3.5  },
+  { name: 'High-Mid', row: 0, col: 1, xMin: -0.28, xMax:  0.28, zMin: 2.83, zMax: 3.5  },
+  { name: 'High-Out', row: 0, col: 2, xMin:  0.28, xMax:  0.83, zMin: 2.83, zMax: 3.5  },
+  { name: 'Mid-In',   row: 1, col: 0, xMin: -0.83, xMax: -0.28, zMin: 2.17, zMax: 2.83 },
+  { name: 'Mid-Mid',  row: 1, col: 1, xMin: -0.28, xMax:  0.28, zMin: 2.17, zMax: 2.83 },
+  { name: 'Mid-Out',  row: 1, col: 2, xMin:  0.28, xMax:  0.83, zMin: 2.17, zMax: 2.83 },
+  { name: 'Low-In',   row: 2, col: 0, xMin: -0.83, xMax: -0.28, zMin: 1.5,  zMax: 2.17 },
+  { name: 'Low-Mid',  row: 2, col: 1, xMin: -0.28, xMax:  0.28, zMin: 1.5,  zMax: 2.17 },
+  { name: 'Low-Out',  row: 2, col: 2, xMin:  0.28, xMax:  0.83, zMin: 1.5,  zMax: 2.17 },
+];
+
+/**
+ * 3x3 zone grid with numeric row/col indices and averaged xwOBA.
+ * Powers the zone-profile heatmap visualization. Unlike hitter-hot-cold-zones
+ * which returns strings for human display, this returns numerics for charting.
+ */
+const template: QueryTemplate = {
+  id: 'hitter-zone-grid',
+  name: 'Hitter Zone Grid (numeric)',
+  category: 'hitter',
+  description: '3x3 strike zone grid with numeric row/col/xwoba for heatmap visualization',
+  preferredSources: ['savant'],
+  requiredParams: ['player'],
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query hitter-zone-grid --player "Shohei Ohtani" --format json',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'batting',
+    };
+  },
+
+  columns() {
+    return ['zone', 'row', 'col', 'pitches', 'xwoba'];
+  },
+
+  transform(data) {
+    const pitches = data as PitchData[];
+    if (pitches.length === 0) return [];
+
+    return ZONES.map((z) => {
+      const inZone = pitches.filter(
+        (p) =>
+          p.plate_x >= z.xMin && p.plate_x < z.xMax &&
+          p.plate_z >= z.zMin && p.plate_z < z.zMax,
+      );
+
+      // Compute actual xwOBA across all plate-appearance-ending events in
+      // this zone (not just balls in play). Walks and HBPs use their canonical
+      // wOBA weights; strikeouts contribute zero; batted balls use the
+      // Statcast expected wOBA for that event.
+      const paEnding = inZone.filter((p) => p.events != null);
+      let xwobaSum = 0;
+      for (const p of paEnding) {
+        if (p.events === 'walk') {
+          xwobaSum += 0.69;
+        } else if (p.events === 'hit_by_pitch') {
+          xwobaSum += 0.72;
+        } else if (p.events === 'strikeout') {
+          xwobaSum += 0;
+        } else {
+          // Batted ball: use Statcast estimated wOBA for the contact event
+          xwobaSum += p.estimated_woba ?? 0;
+        }
+      }
+      const xwoba = paEnding.length > 0 ? xwobaSum / paEnding.length : 0;
+
+      return {
+        zone: z.name,
+        row: z.row,
+        col: z.col,
+        pitches: inZone.length,
+        pa: paEnding.length,
+        xwoba: Number(xwoba.toFixed(3)),
+      };
+    });
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/index.ts

@@ -0,0 +1,27 @@
+// Import all templates to trigger registration
+import './pitcher-arsenal.js';
+import './pitcher-velocity-trend.js';
+import './pitcher-handedness-splits.js';
+import './hitter-batted-ball.js';
+import './hitter-vs-pitch-type.js';
+import './hitter-hot-cold-zones.js';
+import './matchup-pitcher-vs-hitter.js';
+import './matchup-situational.js';
+import './leaderboard-custom.js';
+import './leaderboard-comparison.js';
+import './trend-rolling-average.js';
+import './trend-year-over-year.js';
+import './pitcher-raw-pitches.js';
+import './hitter-raw-bip.js';
+import './hitter-zone-grid.js';
+
+export {
+  getTemplate,
+  getAllTemplates,
+  getTemplatesByCategory,
+  listTemplates,
+  type QueryTemplate,
+  type QueryTemplateParams,
+  type QueryResult,
+  type QueryCategory,
+} from './registry.js';

package/dist/templates/queries/leaderboard-comparison.ts

@@ -0,0 +1,72 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PlayerStats } from '../../adapters/types.js';
+
+const template: QueryTemplate = {
+  id: 'leaderboard-comparison',
+  name: 'Player Comparison',
+  category: 'leaderboard',
+  description: 'Side-by-side comparison of multiple players across key metrics vs league average',
+  preferredSources: ['fangraphs', 'mlb-stats-api'],
+  requiredParams: ['players'],
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query leaderboard-comparison --players "Aaron Judge,Juan Soto,Mookie Betts"',
+  ],
+
+  buildQuery(params) {
+    return {
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'batting',
+    };
+  },
+
+  columns(params) {
+    return ['Metric', ...(params.players ?? [])];
+  },
+
+  transform(data, params) {
+    const allStats = data as PlayerStats[];
+    const playerNames = params.players ?? [];
+
+    // Match players by name (case-insensitive partial match)
+    const matched = playerNames.map((name) => {
+      const norm = name.toLowerCase();
+      return allStats.find((s) => s.player_name.toLowerCase().includes(norm));
+    });
+
+    // Key batting metrics to compare
+    const metrics = [
+      'AVG', 'OBP', 'SLG', 'OPS', 'wRC+', 'WAR', 'HR', 'RBI',
+      'K%', 'BB%', 'ISO', 'BABIP',
+    ];
+
+    return metrics.map((metric) => {
+      const row: Record<string, unknown> = { Metric: metric };
+      for (let i = 0; i < playerNames.length; i++) {
+        const player = matched[i];
+        if (!player) {
+          row[playerNames[i]] = '—';
+          continue;
+        }
+        const val = findStatValue(player.stats, metric);
+        row[playerNames[i]] = val ?? '—';
+      }
+      return row;
+    });
+  },
+};
+
+function findStatValue(stats: Record<string, unknown>, key: string): string | null {
+  const lower = key.toLowerCase().replace(/[+%]/g, '');
+  for (const [k, v] of Object.entries(stats)) {
+    if (k.toLowerCase().replace(/[+%]/g, '') === lower) {
+      if (v === null || v === undefined) return null;
+      const n = Number(v);
+      if (isNaN(n)) return String(v);
+      return n < 1 && n > 0 ? n.toFixed(3) : n % 1 === 0 ? String(n) : n.toFixed(1);
+    }
+  }
+  return null;
+}
+
+registerTemplate(template);

package/dist/templates/queries/leaderboard-custom.ts

@@ -0,0 +1,90 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PlayerStats } from '../../adapters/types.js';
+
+const template: QueryTemplate = {
+  id: 'leaderboard-custom',
+  name: 'Custom Leaderboard',
+  category: 'leaderboard',
+  description: 'Top N players by any metric — with minimum qualification thresholds',
+  preferredSources: ['fangraphs', 'mlb-stats-api'],
+  requiredParams: ['stat'],
+  optionalParams: ['season', 'team', 'top', 'minPa', 'minIp'],
+  examples: [
+    'bbdata query leaderboard-custom --stat barrel_rate --min-pa 200 --top 20',
+    'bbdata query leaderboard-custom --stat ERA --min-ip 100 --top 10 --format table',
+  ],
+
+  buildQuery(params) {
+    const pitchingStats = ['era', 'fip', 'xfip', 'siera', 'whip', 'k/9', 'bb/9', 'hr/9', 'ip', 'w', 'sv', 'hld'];
+    const isPitching = pitchingStats.includes((params.stat ?? '').toLowerCase());
+    return {
+      season: params.season ?? new Date().getFullYear(),
+      team: params.team,
+      stat_type: isPitching ? 'pitching' : 'batting',
+      min_pa: params.minPa,
+      min_ip: params.minIp,
+    };
+  },
+
+  columns(params) {
+    return ['Rank', 'Player', 'Team', params.stat ?? 'Stat', 'PA/IP'];
+  },
+
+  transform(data, params) {
+    const stats = data as PlayerStats[];
+    if (stats.length === 0) return [];
+
+    const statKey = params.stat ?? '';
+    const top = params.top ?? 20;
+
+    // Find the stat in each player's stats object (case-insensitive search)
+    const withStat = stats
+      .map((player) => {
+        const value = findStat(player.stats, statKey);
+        return { player, value };
+      })
+      .filter((p) => p.value !== null)
+      .sort((a, b) => {
+        // ERA, FIP, etc. sort ascending; most others descending
+        const ascending = ['era', 'fip', 'xfip', 'siera', 'whip', 'bb%'].includes(
+          statKey.toLowerCase(),
+        );
+        return ascending
+          ? (a.value as number) - (b.value as number)
+          : (b.value as number) - (a.value as number);
+      })
+      .slice(0, top);
+
+    return withStat.map((entry, idx) => ({
+      Rank: idx + 1,
+      Player: entry.player.player_name,
+      Team: entry.player.team,
+      [statKey]: typeof entry.value === 'number'
+        ? entry.value < 1 && entry.value > 0
+          ? entry.value.toFixed(3)
+          : entry.value.toFixed(1)
+        : String(entry.value),
+      'PA/IP': entry.player.stats.plateAppearances ?? entry.player.stats.PA
+        ?? entry.player.stats.inningsPitched ?? entry.player.stats.IP ?? '—',
+    }));
+  },
+};
+
+function findStat(stats: Record<string, unknown>, key: string): number | null {
+  // Direct match
+  if (key in stats) {
+    const val = Number(stats[key]);
+    return isNaN(val) ? null : val;
+  }
+  // Case-insensitive match
+  const lower = key.toLowerCase();
+  for (const [k, v] of Object.entries(stats)) {
+    if (k.toLowerCase() === lower || k.toLowerCase().replace(/[_%]/g, '') === lower.replace(/[_%]/g, '')) {
+      const val = Number(v);
+      return isNaN(val) ? null : val;
+    }
+  }
+  return null;
+}
+
+registerTemplate(template);

package/dist/templates/queries/matchup-pitcher-vs-hitter.ts

@@ -0,0 +1,81 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+import { pitchTypeName } from '../../adapters/types.js';
+
+const template: QueryTemplate = {
+  id: 'matchup-pitcher-vs-hitter',
+  name: 'Pitcher vs Hitter Matchup',
+  category: 'matchup',
+  description: 'Career head-to-head history — PA, H, HR, BB, K, BA, SLG, most common pitches',
+  preferredSources: ['savant'],
+  requiredParams: ['players'], // expects [pitcher, hitter]
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query matchup-pitcher-vs-hitter --players "Gerrit Cole,Aaron Judge"',
+  ],
+
+  buildQuery(params) {
+    // Query for the pitcher's data — we'll filter for the specific batter in transform
+    return {
+      player_name: params.players?.[0],
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'pitching',
+    };
+  },
+
+  columns() {
+    return ['Metric', 'Value'];
+  },
+
+  transform(data, params) {
+    const pitches = data as PitchData[];
+    const hitterName = (params.players?.[1] ?? '').toLowerCase();
+
+    // Filter to only PAs against the target hitter
+    const matchup = pitches.filter((p) =>
+      p.batter_name.toLowerCase().includes(hitterName),
+    );
+
+    if (matchup.length === 0) {
+      return [{ Metric: 'Note', Value: `No matchup data found for ${params.players?.[1] ?? 'hitter'}` }];
+    }
+
+    const pas = matchup.filter((p) => p.events !== null);
+    const hits = pas.filter((p) => ['single', 'double', 'triple', 'home_run'].includes(p.events ?? ''));
+    const hrs = pas.filter((p) => p.events === 'home_run');
+    const ks = pas.filter((p) => p.events === 'strikeout');
+    const bbs = pas.filter((p) => ['walk', 'hit_by_pitch'].includes(p.events ?? ''));
+    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);
+
+    // Most common pitch types
+    const pitchCounts = new Map<string, number>();
+    for (const p of matchup) {
+      pitchCounts.set(p.pitch_type, (pitchCounts.get(p.pitch_type) ?? 0) + 1);
+    }
+    const topPitches = Array.from(pitchCounts.entries())
+      .sort(([, a], [, b]) => b - a)
+      .slice(0, 3)
+      .map(([type, count]) => `${pitchTypeName(type)} (${count})`)
+      .join(', ');
+
+    return [
+      { Metric: 'Total Pitches', Value: matchup.length },
+      { Metric: 'Plate Appearances', Value: pas.length },
+      { Metric: 'Hits', Value: hits.length },
+      { Metric: 'Home Runs', Value: hrs.length },
+      { Metric: 'Strikeouts', Value: ks.length },
+      { Metric: 'Walks', Value: bbs.length },
+      { Metric: 'AVG', Value: pas.length > 0 ? (hits.length / pas.length).toFixed(3) : '—' },
+      { Metric: 'SLG', Value: pas.length > 0 ? (totalBases / pas.length).toFixed(3) : '—' },
+      { Metric: 'Most Common Pitches', Value: topPitches },
+    ];
+  },
+};
+
+registerTemplate(template);