endurance-coach 0.1.0 → 1.0.0

package/dist/expander/zones.js

@@ -0,0 +1,159 @@
+/**
+ * Zone Calculator
+ *
+ * Calculates training zone ranges from threshold values.
+ * Uses standard physiological percentages for zone calculations.
+ */
+// ============================================================================
+// Heart Rate Zone Calculation
+// ============================================================================
+/**
+ * Standard 5-zone heart rate model based on LTHR percentages.
+ */
+const HR_ZONE_DEFINITIONS = [
+    { zone: 1, name: "Recovery", percentLow: 0, percentHigh: 81 },
+    { zone: 2, name: "Aerobic", percentLow: 81, percentHigh: 89 },
+    { zone: 3, name: "Tempo", percentLow: 89, percentHigh: 94 },
+    { zone: 4, name: "Threshold", percentLow: 94, percentHigh: 100 },
+    { zone: 5, name: "VO2max", percentLow: 100, percentHigh: 106 },
+];
+/**
+ * Calculate heart rate zones from LTHR.
+ *
+ * Uses the standard 5-zone model with percentages of LTHR.
+ */
+export function calculateHRZones(config) {
+    const { lthr, maxHR, restingHR } = config;
+    const zones = HR_ZONE_DEFINITIONS.map((def) => ({
+        zone: def.zone,
+        name: def.name,
+        percentLow: def.percentLow,
+        percentHigh: def.percentHigh,
+        hrLow: Math.round(lthr * (def.percentLow / 100)),
+        hrHigh: Math.round(lthr * (def.percentHigh / 100)),
+    }));
+    return {
+        lthr,
+        maxHR,
+        restingHR,
+        zones,
+    };
+}
+// ============================================================================
+// Pace Zone Calculation
+// ============================================================================
+/**
+ * Parse a pace string into seconds per unit.
+ *
+ * @example
+ * parsePace("5:30/km") // { seconds: 330, unit: "km" }
+ * parsePace("8:00/mi") // { seconds: 480, unit: "mi" }
+ * parsePace("5:30") // { seconds: 330, unit: undefined }
+ */
+export function parsePace(pace) {
+    const match = pace.match(/^(\d+):(\d{2})(?:\/(\w+))?$/);
+    if (!match) {
+        throw new Error(`Invalid pace format: ${pace}`);
+    }
+    const minutes = parseInt(match[1], 10);
+    const seconds = parseInt(match[2], 10);
+    const unit = match[3];
+    return {
+        seconds: minutes * 60 + seconds,
+        unit,
+    };
+}
+/**
+ * Format seconds back to a pace string.
+ *
+ * @example
+ * formatPace(330, "km") // "5:30/km"
+ * formatPace(480) // "8:00"
+ */
+export function formatPace(seconds, unit) {
+    const mins = Math.floor(seconds / 60);
+    const secs = Math.round(seconds % 60);
+    const base = `${mins}:${secs.toString().padStart(2, "0")}`;
+    return unit ? `${base}/${unit}` : base;
+}
+/**
+ * Standard pace zone definitions based on Jack Daniels' VDOT system.
+ * Offsets are in seconds per km from threshold pace.
+ */
+const PACE_ZONE_DEFINITIONS = [
+    { zone: "E", name: "Easy", offsetSeconds: 60 }, // +60s from threshold
+    { zone: "M", name: "Marathon", offsetSeconds: 30 }, // +30s from threshold
+    { zone: "T", name: "Threshold", offsetSeconds: 0 }, // At threshold
+    { zone: "I", name: "Interval", offsetSeconds: -15 }, // -15s from threshold
+    { zone: "R", name: "Repetition", offsetSeconds: -30 }, // -30s from threshold
+];
+/**
+ * Calculate pace zones from threshold pace.
+ */
+export function calculatePaceZones(thresholdPace) {
+    const { seconds: thresholdSeconds, unit } = parsePace(thresholdPace);
+    const zones = PACE_ZONE_DEFINITIONS.map((def) => {
+        const paceSeconds = thresholdSeconds + def.offsetSeconds;
+        return {
+            zone: def.zone,
+            name: def.name,
+            pace: formatPace(paceSeconds, unit),
+            paceSeconds,
+        };
+    });
+    return {
+        thresholdPace,
+        thresholdPaceSeconds: thresholdSeconds,
+        zones,
+    };
+}
+// ============================================================================
+// Combined Zone Calculation
+// ============================================================================
+/**
+ * Calculate all athlete zones from compact plan inputs.
+ */
+export function calculateAthleteZones(hrConfig, paces) {
+    const zones = {};
+    // Calculate HR zones if LTHR provided
+    if (hrConfig) {
+        zones.run = zones.run || {};
+        zones.run.hr = calculateHRZones(hrConfig);
+        // Also apply to bike if no separate bike HR zones
+        zones.bike = zones.bike || {};
+        zones.bike.hr = calculateHRZones(hrConfig);
+        zones.maxHR = hrConfig.maxHR;
+        zones.restingHR = hrConfig.restingHR;
+    }
+    // Calculate pace zones if threshold pace provided
+    if (paces?.threshold) {
+        zones.run = zones.run || {};
+        zones.run.pace = calculatePaceZones(paces.threshold);
+    }
+    return zones;
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Get the HR zone for a given heart rate.
+ */
+export function getHRZoneForValue(hr, zones) {
+    return zones.zones.find((z) => hr >= z.hrLow && hr <= z.hrHigh);
+}
+/**
+ * Get the pace zone for a given pace.
+ */
+export function getPaceZoneForValue(paceSeconds, zones) {
+    // Find the closest zone
+    let closest;
+    let minDiff = Infinity;
+    for (const zone of zones.zones) {
+        const diff = Math.abs(paceSeconds - zone.paceSeconds);
+        if (diff < minDiff) {
+            minDiff = diff;
+            closest = zone;
+        }
+    }
+    return closest;
+}

package/dist/index.d.ts

@@ -4,4 +4,8 @@
  * Public API for validating and working with training plans.
  */
 export { validatePlan, validatePlanOrThrow, formatValidationErrors, getJsonSchema, TrainingPlanSchema, WorkoutSchema, TrainingWeekSchema, TrainingDaySchema, TrainingPhaseSchema, AthleteAssessmentSchema, AthleteZonesSchema, RaceStrategySchema, UnitPreferencesSchema, PlanMetaSchema, type TrainingPlan, type Workout, type TrainingWeek, type TrainingDay, type TrainingPhase, type AthleteAssessment, type AthleteZones, type RaceStrategy, type UnitPreferences, type ValidationResult, type ValidationError, } from "./schema/training-plan.schema.js";
+export { validateCompactPlan, validateCompactPlanOrThrow, formatCompactValidationErrors, CompactPlanSchema, CompactAthleteSchema, CompactPhaseSchema, CompactWeekSchema, type CompactPlan, type CompactAthlete, type CompactPhase, type CompactWeek, type CompactWeekSchedule, type CompactRaceStrategy, type AthletePaces, type CompactValidationResult, type CompactValidationError, } from "./schema/compact-plan.schema.js";
+export { parseWorkoutRef, parseWeekRange } from "./schema/compact-plan.js";
+export { loadTemplates, loadTemplatesFromArray, getTemplatesPath, validateTemplate, validateTemplateOrThrow, interpolate, interpolateObject, createContext, parseYaml, stringifyYaml, type WorkoutTemplate, type TemplateParam, type TemplateParams, type TemplateRegistry, type InterpolationContext, } from "./templates/index.js";
+export { expandPlan, expandWorkout, validateWorkoutRefs, calculateHRZones, calculatePaceZones, calculateAthleteZones, parsePace, formatPace, type ExpandedPlan, type ExpandedWeek, type ExpandedDay, type ExpandedWorkout, type ExpandedPhase, type ExpandedAthleteZones, type ExpansionOptions, } from "./expander/index.js";
 export type { Sport, WorkoutType, IntensityUnit, DurationUnit, StepType, SwimDistanceUnit, LandDistanceUnit, FirstDayOfWeek, IntensityTarget, DurationTarget, WorkoutStep, IntervalSet, StructuredWorkout, WeekSummary, HeartRateZones, PowerZones, SwimZones, PaceZones, } from "./schema/training-plan.js";

package/dist/index.js

@@ -3,7 +3,7 @@
  *
  * Public API for validating and working with training plans.
  */
-// Schema validation
+// Full Schema validation (v1.0 - expanded format)
 export { 
 // Validation functions
 validatePlan, validatePlanOrThrow, formatValidationErrors, getJsonSchema, 
@@ -11,3 +11,11 @@ validatePlan, validatePlanOrThrow, formatValidationErrors, getJsonSchema,
 TrainingPlanSchema, 
 // Component schemas (for partial validation)
 WorkoutSchema, TrainingWeekSchema, TrainingDaySchema, TrainingPhaseSchema, AthleteAssessmentSchema, AthleteZonesSchema, RaceStrategySchema, UnitPreferencesSchema, PlanMetaSchema, } from "./schema/training-plan.schema.js";
+// Compact Schema validation (v2.0 - template-based format)
+export { validateCompactPlan, validateCompactPlanOrThrow, formatCompactValidationErrors, CompactPlanSchema, CompactAthleteSchema, CompactPhaseSchema, CompactWeekSchema, } from "./schema/compact-plan.schema.js";
+// Compact plan utilities
+export { parseWorkoutRef, parseWeekRange } from "./schema/compact-plan.js";
+// Templates
+export { loadTemplates, loadTemplatesFromArray, getTemplatesPath, validateTemplate, validateTemplateOrThrow, interpolate, interpolateObject, createContext, parseYaml, stringifyYaml, } from "./templates/index.js";
+// Expander
+export { expandPlan, expandWorkout, validateWorkoutRefs, calculateHRZones, calculatePaceZones, calculateAthleteZones, parsePace, formatPace, } from "./expander/index.js";

package/dist/schema/compact-plan.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Compact Training Plan Schema
+ *
+ * A minimal schema for AI models to generate training plans.
+ * The compact format is expanded to the full format for HTML rendering.
+ *
+ * Key design principles:
+ * - Minimal output for models to generate
+ * - Template references instead of full workout definitions
+ * - Athlete paces/zones as inputs, system calculates ranges
+ */
+export type Sport = "swim" | "bike" | "run" | "strength" | "brick" | "race" | "rest";
+export type FirstDayOfWeek = "monday" | "sunday";
+export type DistanceUnit = "km" | "mi";
+/**
+ * Athlete's pace values for different workout intensities.
+ * Models specify these once, templates interpolate them.
+ */
+export interface AthletePaces {
+    easy?: string;
+    long?: string;
+    tempo?: string;
+    threshold?: string;
+    marathon?: string;
+    halfMarathon?: string;
+    interval?: string;
+    r200?: string;
+    r400?: string;
+    r800?: string;
+    r1k?: string;
+    rMile?: string;
+    bikeFtp?: number;
+    bikeEasy?: string;
+    bikeTempo?: string;
+    bikeThreshold?: string;
+    swimCss?: string;
+    swimEasy?: string;
+    swimTempo?: string;
+}
+/**
+ * Heart rate zone configuration.
+ * Only LTHR required - zone ranges are calculated automatically.
+ */
+export interface HRZoneConfig {
+    lthr: number;
+    maxHR?: number;
+    restingHR?: number;
+}
+/**
+ * Athlete's training zones.
+ * Minimal input, system calculates full zone ranges.
+ */
+export interface AthleteZones {
+    hr?: HRZoneConfig;
+}
+/**
+ * Athlete preferences and constraints.
+ */
+export interface AthleteConstraints {
+    daysPerWeek?: number | string;
+    preferredDays?: string[];
+    maxLongRunHours?: number;
+    maxLongBikeHours?: number;
+    notes?: string[];
+}
+/**
+ * Complete athlete configuration in compact format.
+ */
+export interface CompactAthlete {
+    name: string;
+    event: string;
+    eventDate: string;
+    paces: AthletePaces;
+    zones?: AthleteZones;
+    constraints?: AthleteConstraints;
+    unit?: DistanceUnit;
+    firstDayOfWeek?: FirstDayOfWeek;
+}
+/**
+ * A training phase defines a block of focused training.
+ * Weeks can be a range string or array of week numbers.
+ */
+export interface CompactPhase {
+    name: string;
+    weeks: string | number[];
+    focus: string;
+    keyWorkouts?: string[];
+}
+/**
+ * A workout reference is a template ID with optional parameters.
+ *
+ * Format: "template.id" or "template.id(param)" or "template.id(param1, param2)"
+ *
+ * Examples:
+ *   - "easy(30)" → easy run, 30 minutes
+ *   - "intervals.400(6)" → 6x400m intervals
+ *   - "long(90)" → 90-minute long run
+ *   - "rest" → rest day (no params)
+ *   - "tempo(20)" → 20-minute tempo section
+ */
+export type WorkoutRef = string;
+/**
+ * Day of the week as used in the schedule.
+ */
+export type DayOfWeek = "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" | "Sun";
+/**
+ * A week's workout schedule maps days to workout references.
+ * Days without workouts are implicitly rest days.
+ */
+export interface CompactWeekSchedule {
+    [day: string]: WorkoutRef | WorkoutRef[];
+}
+/**
+ * A training week in the compact format.
+ */
+export interface CompactWeek {
+    week: number;
+    phase: string;
+    focus?: string;
+    isRecoveryWeek?: boolean;
+    targetHours?: number;
+    workouts: CompactWeekSchedule;
+}
+/**
+ * Simplified race strategy for the compact format.
+ */
+export interface CompactRaceStrategy {
+    goalTime?: string;
+    pacing?: {
+        swim?: string;
+        bike?: string;
+        run?: string;
+    };
+    nutrition?: string;
+    notes?: string[];
+}
+/**
+ * The complete compact training plan.
+ *
+ * This is what AI models generate. It's transformed to the full
+ * expanded format for HTML rendering and device export.
+ */
+export interface CompactPlan {
+    version: "2.0";
+    athlete: CompactAthlete;
+    phases: CompactPhase[];
+    weeks: CompactWeek[];
+    raceStrategy?: CompactRaceStrategy;
+}
+/**
+ * Parsed workout reference.
+ */
+export interface ParsedWorkoutRef {
+    templateId: string;
+    params: (string | number)[];
+}
+/**
+ * Parse a workout reference string into its components.
+ *
+ * Examples:
+ *   "easy(30)" → { templateId: "easy", params: [30] }
+ *   "intervals.400(6)" → { templateId: "intervals.400", params: [6] }
+ *   "rest" → { templateId: "rest", params: [] }
+ *   "tempo(20, 90)" → { templateId: "tempo", params: [20, 90] }
+ */
+export declare function parseWorkoutRef(ref: string): ParsedWorkoutRef;
+/**
+ * Parse a week range string into an array of week numbers.
+ *
+ * Examples:
+ *   "1-3" → [1, 2, 3]
+ *   "4-6" → [4, 5, 6]
+ *   [1, 2, 3] → [1, 2, 3] (passthrough)
+ */
+export declare function parseWeekRange(weeks: string | number[]): number[];

package/dist/schema/compact-plan.js

@@ -0,0 +1,64 @@
+/**
+ * Compact Training Plan Schema
+ *
+ * A minimal schema for AI models to generate training plans.
+ * The compact format is expanded to the full format for HTML rendering.
+ *
+ * Key design principles:
+ * - Minimal output for models to generate
+ * - Template references instead of full workout definitions
+ * - Athlete paces/zones as inputs, system calculates ranges
+ */
+/**
+ * Parse a workout reference string into its components.
+ *
+ * Examples:
+ *   "easy(30)" → { templateId: "easy", params: [30] }
+ *   "intervals.400(6)" → { templateId: "intervals.400", params: [6] }
+ *   "rest" → { templateId: "rest", params: [] }
+ *   "tempo(20, 90)" → { templateId: "tempo", params: [20, 90] }
+ */
+export function parseWorkoutRef(ref) {
+    const match = ref.match(/^([a-zA-Z0-9_.]+)(?:\(([^)]*)\))?$/);
+    if (!match) {
+        throw new Error(`Invalid workout reference: "${ref}"`);
+    }
+    const templateId = match[1];
+    const paramsStr = match[2];
+    let params = [];
+    if (paramsStr) {
+        params = paramsStr.split(",").map((p) => {
+            const trimmed = p.trim();
+            const num = Number(trimmed);
+            return isNaN(num) ? trimmed : num;
+        });
+    }
+    return { templateId, params };
+}
+/**
+ * Parse a week range string into an array of week numbers.
+ *
+ * Examples:
+ *   "1-3" → [1, 2, 3]
+ *   "4-6" → [4, 5, 6]
+ *   [1, 2, 3] → [1, 2, 3] (passthrough)
+ */
+export function parseWeekRange(weeks) {
+    if (Array.isArray(weeks)) {
+        return weeks;
+    }
+    const match = weeks.match(/^(\d+)-(\d+)$/);
+    if (!match) {
+        throw new Error(`Invalid week range: "${weeks}"`);
+    }
+    const start = parseInt(match[1], 10);
+    const end = parseInt(match[2], 10);
+    if (start > end) {
+        throw new Error(`Invalid week range: start (${start}) > end (${end})`);
+    }
+    const result = [];
+    for (let i = start; i <= end; i++) {
+        result.push(i);
+    }
+    return result;
+}