bbdata-cli 0.1.0 → 0.2.0

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-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,86 @@
+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', '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', 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;
+
+      results.push({
+        Window: `${windowDates[0]} → ${windowDates[windowDates.length - 1]}`,
+        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*

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

@@ -0,0 +1,60 @@
+# Advance Report: {{player}} (SP)
+
+**Season:** {{season}} | **For:** {{audience}} | **Generated:** {{date}}
+
+---
+
+## Recent Form
+
+*Last 5 starts — to be populated with game log data*
+
+## Pitch Mix & Sequencing
+
+{{#if data.pitcher-arsenal}}
+### Arsenal Overview
+
+| Pitch | Usage | Velo | Spin | Whiff % |
+|-------|-------|------|------|---------|
+{{#each data.pitcher-arsenal}}
+| {{this.[Pitch Type]}} | {{this.[Usage %]}} | {{this.[Avg Velo]}} | {{this.[Avg Spin]}} | {{this.[Whiff %]}} |
+{{/each}}
+
+### By Count (to be populated)
+- **Ahead in count:** Primary pitch selection
+- **Behind in count:** Go-to pitch
+- **Two-strike:** Put-away pitch
+{{else}}
+*Arsenal data not available*
+{{/if}}
+
+## Times Through the Order
+
+*3rd time adjustment, velocity drop patterns — to be analyzed from pitch-level data*
+
+## Platoon Vulnerabilities
+
+{{#if data.pitcher-handedness-splits}}
+| Split | PA | AVG | SLG | K % | BB % |
+|-------|-----|-----|-----|-----|------|
+{{#each data.pitcher-handedness-splits}}
+| {{this.vs}} | {{this.PA}} | {{this.AVG}} | {{this.SLG}} | {{this.[K %]}} | {{this.[BB %]}} |
+{{/each}}
+{{else}}
+*Splits data not available*
+{{/if}}
+
+## How to Attack
+
+### Early in Game (1st time through)
+- *To be filled: patient approach? aggressive?*
+
+### Late in Game (3rd+ time through)
+- *To be filled: exploit fatigue patterns?*
+
+### Key Weaknesses
+- *To be filled by evaluator*
+
+---
+
+*Generated by bbdata CLI · Data sources: {{sources}}*
+*This is a 1-page advance report designed for in-game use.*

package/dist/templates/reports/college-hitter-draft.hbs

@@ -0,0 +1,49 @@
+# College Hitter Draft Report: {{player}}
+
+**Season:** {{season}} | **Generated:** {{date}}
+
+---
+
+## Header
+
+| Field | Value |
+|-------|-------|
+| Player | {{player}} |
+| School | *To be filled* |
+| Bats/Throws | *To be filled* |
+| Position | *To be filled* |
+| Age | *To be filled* |
+
+## Physical
+
+*Body type, athleticism, strength projection — to be filled*
+
+## Tool Grades (20-80 Scale)
+
+| Tool | Present | Future | Notes |
+|------|---------|--------|-------|
+| Hit | — | — | *Bat speed, plate coverage* |
+| Power | — | — | *Raw, game power, pull/oppo* |
+| Speed | — | — | *Run times, baserunning IQ* |
+| Field | — | — | *Actions, arm, range* |
+| Arm | — | — | *Strength, accuracy* |
+
+## Performance
+
+*College slash line, K%, BB%, wood bat league stats — to be filled*
+
+## Projection
+
+*Ceiling, floor, likely outcome — to be filled*
+
+## Risk
+
+*Swing concerns, defensive fit, signability — to be filled*
+
+## Recommendation
+
+*Draft round range, comparison — to be filled*
+
+---
+
+*Generated by bbdata CLI*

package/dist/templates/reports/college-pitcher-draft.hbs

@@ -0,0 +1,48 @@
+# College Pitcher Draft Report: {{player}}
+
+**Season:** {{season}} | **Generated:** {{date}}
+
+---
+
+## Header
+
+| Field | Value |
+|-------|-------|
+| Player | {{player}} |
+| School | *To be filled* |
+| Throws | *To be filled* |
+| Age | *To be filled* |
+| Height/Weight | *To be filled* |
+
+## Physical
+
+*Body type, athleticism, projectability — to be filled by evaluator*
+
+## Arsenal Grades (20-80 Scale)
+
+| Tool | Present | Future | Notes |
+|------|---------|--------|-------|
+| Fastball | — | — | *Velo, life, command* |
+| Breaking Ball | — | — | *Type, spin, depth* |
+| Changeup | — | — | *Fade, deception* |
+| Command | — | — | *Zone control, sequencing* |
+
+## Performance
+
+*College stats: ERA, K/9, BB/9, WHIP — to be filled*
+
+## Projection
+
+*Ceiling, floor, likely outcome — to be filled by evaluator*
+
+## Risk
+
+*Injury history, workload, mechanics — to be filled by evaluator*
+
+## Recommendation
+
+*Draft round range, comparison, acquire/pass — to be filled*
+
+---
+
+*Generated by bbdata CLI*

package/dist/templates/reports/dev-progress.hbs

@@ -0,0 +1,29 @@
+# Development Progress Report: {{player}}
+
+**Season:** {{season}} | **Generated:** {{date}}
+
+---
+
+## Current Stats
+
+*Current level, slash line, K%, BB%, ISO — to be populated*
+
+## Trend Analysis
+
+*Month-over-month progression, key metric changes — to be populated*
+
+## Mechanical Notes
+
+*Changes, adjustments, coach observations — to be filled by evaluator*
+
+## Development Goals
+
+*Target areas for improvement — to be filled by development staff*
+
+## Next Steps
+
+*Promotion timeline, assignment recommendation — to be filled*
+
+---
+
+*Generated by bbdata CLI*

package/dist/templates/reports/draft-board-card.hbs

@@ -0,0 +1,35 @@
+# {{player}} — Draft Board Card
+
+**Generated:** {{date}}
+
+---
+
+| Field | Value |
+|-------|-------|
+| **Name** | {{player}} |
+| **Position** | *To be filled* |
+| **School** | *To be filled* |
+| **B/T** | *To be filled* |
+| **Age** | *To be filled* |
+
+### Tool Grades
+
+| Hit | Power | Speed | Field | Arm | OFP |
+|-----|-------|-------|-------|-----|-----|
+| — | — | — | — | — | — |
+
+### Projection
+
+*One-line ceiling* — *To be filled*
+
+### Comp
+
+*Player comparison* — *To be filled*
+
+### Round Range
+
+*Expected draft range* — *To be filled*
+
+---
+
+*bbdata CLI · Draft room card format*

package/dist/templates/reports/hs-prospect.hbs

@@ -0,0 +1,48 @@
+# High School Prospect Report: {{player}}
+
+**Season:** {{season}} | **Generated:** {{date}}
+
+---
+
+## Header
+
+| Field | Value |
+|-------|-------|
+| Player | {{player}} |
+| School | *To be filled* |
+| Position | *To be filled* |
+| Commitment | *To be filled* |
+
+## Physical
+
+*Body type, athleticism, projectability — to be filled*
+
+## Tool Grades (20-80 Scale)
+
+| Tool | Present | Future | Notes |
+|------|---------|--------|-------|
+| Hit | — | — | |
+| Power | — | — | |
+| Speed | — | — | |
+| Field | — | — | |
+| Arm | — | — | |
+
+## Makeup
+
+*Work ethic, competitiveness, coachability — to be filled*
+
+## Projection
+
+*Development timeline, ceiling, floor — to be filled*
+
+## Signability
+
+*Commitment strength, slot expectations — to be filled*
+
+## Recommendation
+
+*Draft/follow recommendation — to be filled*
+
+---
+
+*Generated by bbdata CLI*