endurance-coach 0.1.1 → 1.0.0

package/README.md

@@ -1,5 +1,8 @@
 # Endurance Coach
 
+Originally forked from Claude Coach.
+This project is now independently maintained and has evolved with a different architecture and goals, focusing on agent-first, schema-driven endurance planning.
+
 Endurance Coach allows you to use Claude (or any AI assistant) to create custom-tailored training programs for triathlons, marathons, and other endurance activities. Using a data-driven approach and principles from top training plans, the AI will create a training plan that's uniquely fit for you, your personal fitness, and the constraints you have in the next couple of weeks. Maybe you're recovering from an injury, maybe you're traveling and don't have access to a pool or track in a certain week - tell the AI about it and it'll create a plan that works for you.
 
 The output is a beautiful training plan app that allows you to add, edit, or move workouts, mark them as complete, and update key training data like heart rate zones, LTHR, threshold paces, FTP, and others. Your data is kept locally in your browser.

package/dist/cli.js

@@ -9,6 +9,9 @@ import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { ProxyAgent, setGlobalDispatcher } from "undici";
 import { validatePlan, formatValidationErrors } from "./schema/training-plan.schema.js";
+import { validateCompactPlan, formatCompactValidationErrors, } from "./schema/compact-plan.schema.js";
+import { loadTemplates, parseYaml, stringifyYaml } from "./templates/index.js";
+import { expandPlan, validateWorkoutRefs } from "./expander/index.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // ============================================================================
 // Proxy Configuration
@@ -62,6 +65,10 @@ function parseArgs() {
             else if (args[i].startsWith("--output=")) {
                 renderArgs.outputFile = args[i].split("=")[1];
             }
+            else if (!args[i].startsWith("-") && !renderArgs.outputFile) {
+                // Accept positional output argument (helps when npm consumes -o)
+                renderArgs.outputFile = args[i];
+            }
         }
         return renderArgs;
     }
@@ -97,10 +104,61 @@ function parseArgs() {
             log.error("validate command requires an input file");
             process.exit(1);
         }
-        return {
+        const validateArgs = {
             command: "validate",
             inputFile: args[1],
+            compact: args.includes("--compact") || args[1].endsWith(".yaml") || args[1].endsWith(".yml"),
+        };
+        return validateArgs;
+    }
+    if (args[0] === "expand") {
+        if (!args[1]) {
+            log.error("expand command requires an input file");
+            process.exit(1);
+        }
+        const expandArgs = {
+            command: "expand",
+            inputFile: args[1],
+        };
+        for (let i = 2; i < args.length; i++) {
+            if (args[i] === "--output" || args[i] === "-o") {
+                expandArgs.outputFile = args[i + 1];
+                i++;
+            }
+            else if (args[i].startsWith("--output=")) {
+                expandArgs.outputFile = args[i].split("=")[1];
+            }
+            else if (args[i] === "--format") {
+                expandArgs.format = args[i + 1];
+                i++;
+            }
+            else if (args[i].startsWith("--format=")) {
+                expandArgs.format = args[i].split("=")[1];
+            }
+            else if (args[i] === "--verbose" || args[i] === "-v") {
+                expandArgs.verbose = true;
+            }
+        }
+        return expandArgs;
+    }
+    if (args[0] === "templates") {
+        const templatesArgs = {
+            command: "templates",
         };
+        for (let i = 1; i < args.length; i++) {
+            if (args[i] === "--sport") {
+                templatesArgs.sport = args[i + 1];
+                i++;
+            }
+            else if (args[i].startsWith("--sport=")) {
+                templatesArgs.sport = args[i].split("=")[1];
+            }
+            else if (args[i] === "show") {
+                templatesArgs.show = args[i + 1];
+                i++;
+            }
+        }
+        return templatesArgs;
     }
     if (args[0] === "schema") {
         return { command: "schema" };
@@ -160,8 +218,10 @@ Commands:
   sync              Sync activities from Strava
   auth              Get Strava authorization URL or exchange code for tokens
   schema            Print the training plan JSON schema reference
-  validate <file>   Validate a training plan JSON against the schema
-  render <file>     Render a training plan JSON to HTML
+  validate <file>   Validate a training plan against the schema
+  expand <file>     Expand a compact YAML plan to full JSON format
+  render <file>     Render a training plan to HTML
+  templates         List available workout templates
   query <sql>       Run a SQL query against the database
   modify            Apply backup changes to a training plan
   help              Show this help message
@@ -181,6 +241,18 @@ Sync Options:
   --client-secret=SEC   Strava API client secret (for OAuth flow)
   --days=N              Days of history to sync (default: 730)
 
+Validate Options:
+  --compact             Force compact plan validation (auto-detected for .yaml files)
+
+Expand Options:
+  --output, -o FILE     Output file (default: stdout)
+  --format json|yaml    Output format (default: json)
+  --verbose, -v         Show template resolution details
+
+Templates Options:
+  --sport SPORT         Filter by sport (run, bike, swim)
+  show <template-id>    Show details of a specific template
+
 Render Options:
   --output, -o FILE     Output HTML file (default: <input>.html)
 
@@ -497,32 +569,62 @@ function getTemplatePath() {
 }
 function runRender(args) {
     log.start("Rendering training plan...");
-    // Read the plan JSON
-    let planJson;
+    const isCompact = args.inputFile.endsWith(".yaml") || args.inputFile.endsWith(".yml");
+    // Read the plan file
+    let planContent;
     try {
-        planJson = readFileSync(args.inputFile, "utf-8");
+        planContent = readFileSync(args.inputFile, "utf-8");
     }
-    catch (err) {
+    catch {
         log.error(`Could not read input file: ${args.inputFile}`);
         process.exit(1);
     }
-    // Parse JSON
-    let planData;
-    try {
-        planData = JSON.parse(planJson);
-    }
-    catch (err) {
-        log.error("Input file is not valid JSON");
-        process.exit(1);
+    let planJson;
+    if (isCompact) {
+        // Handle compact YAML plan
+        log.info("Detected compact YAML plan, expanding...");
+        // Parse YAML
+        let compactData;
+        try {
+            compactData = parseYaml(planContent);
+        }
+        catch {
+            log.error("Input file is not valid YAML");
+            process.exit(1);
+        }
+        // Validate compact plan
+        const compactValidation = validateCompactPlan(compactData);
+        if (!compactValidation.success) {
+            log.error("Compact plan validation failed:");
+            console.error(formatCompactValidationErrors(compactValidation.errors));
+            process.exit(1);
+        }
+        // Load templates and expand
+        const templates = loadTemplates();
+        const expanded = expandPlan(compactValidation.data, templates);
+        log.success("Plan expanded successfully");
+        planJson = JSON.stringify(expanded, null, 2);
     }
-    // Validate against schema
-    const validation = validatePlan(planData);
-    if (!validation.success) {
-        log.error("Training plan validation failed:");
-        console.error(formatValidationErrors(validation.errors));
-        process.exit(1);
+    else {
+        // Handle full JSON plan
+        let planData;
+        try {
+            planData = JSON.parse(planContent);
+        }
+        catch {
+            log.error("Input file is not valid JSON");
+            process.exit(1);
+        }
+        // Validate against schema
+        const validation = validatePlan(planData);
+        if (!validation.success) {
+            log.error("Training plan validation failed:");
+            console.error(formatValidationErrors(validation.errors));
+            process.exit(1);
+        }
+        log.success("Plan schema validated successfully");
+        planJson = planContent;
     }
-    log.success("Plan schema validated successfully");
     // Read the template
     const templatePath = getTemplatePath();
     let template = readFileSync(templatePath, "utf-8");
@@ -558,33 +660,208 @@ async function runQuery(args) {
 // Validate Command
 // ============================================================================
 function runValidate(args) {
-    log.start("Validating training plan...");
-    // Read the plan JSON
-    let planJson;
+    const isCompact = args.compact;
+    log.start(`Validating ${isCompact ? "compact" : "full"} training plan...`);
+    // Read the plan file
+    let planContent;
     try {
-        planJson = readFileSync(args.inputFile, "utf-8");
+        planContent = readFileSync(args.inputFile, "utf-8");
     }
-    catch (err) {
+    catch {
         log.error(`Could not read input file: ${args.inputFile}`);
         process.exit(1);
     }
-    // Parse JSON
+    // Parse content (YAML or JSON)
     let planData;
     try {
-        planData = JSON.parse(planJson);
+        if (args.inputFile.endsWith(".yaml") || args.inputFile.endsWith(".yml")) {
+            planData = parseYaml(planContent);
+        }
+        else {
+            planData = JSON.parse(planContent);
+        }
     }
     catch (err) {
-        log.error("Input file is not valid JSON");
+        log.error(`Input file is not valid ${isCompact ? "YAML" : "JSON"}`);
         process.exit(1);
     }
-    // Validate against schema
-    const validation = validatePlan(planData);
+    if (isCompact) {
+        // Validate against compact schema
+        const validation = validateCompactPlan(planData);
+        if (!validation.success) {
+            log.error("Compact plan validation failed:");
+            console.error(formatCompactValidationErrors(validation.errors));
+            process.exit(1);
+        }
+        // Also validate template references
+        const templates = loadTemplates();
+        const templateErrors = validateWorkoutRefs(validation.data, templates);
+        if (templateErrors.length > 0) {
+            log.warn("Template reference warnings:");
+            templateErrors.forEach((e) => console.error(`  - ${e}`));
+        }
+        log.success("Compact plan is valid!");
+    }
+    else {
+        // Validate against full schema
+        const validation = validatePlan(planData);
+        if (!validation.success) {
+            log.error("Validation failed:");
+            console.error(formatValidationErrors(validation.errors));
+            process.exit(1);
+        }
+        log.success("Plan is valid!");
+    }
+}
+// ============================================================================
+// Expand Command
+// ============================================================================
+function runExpand(args) {
+    log.start("Expanding compact plan...");
+    // Read the compact plan
+    let planContent;
+    try {
+        planContent = readFileSync(args.inputFile, "utf-8");
+    }
+    catch {
+        log.error(`Could not read input file: ${args.inputFile}`);
+        process.exit(1);
+    }
+    // Parse YAML
+    let planData;
+    try {
+        planData = parseYaml(planContent);
+    }
+    catch {
+        log.error("Input file is not valid YAML");
+        process.exit(1);
+    }
+    // Validate compact plan
+    const validation = validateCompactPlan(planData);
     if (!validation.success) {
-        log.error("Validation failed:");
-        console.error(formatValidationErrors(validation.errors));
+        log.error("Compact plan validation failed:");
+        console.error(formatCompactValidationErrors(validation.errors));
         process.exit(1);
     }
-    log.success("Plan is valid!");
+    // Load templates
+    const templates = loadTemplates();
+    if (args.verbose) {
+        log.info(`Loaded ${templates.ids().length} templates`);
+    }
+    // Validate template references
+    const templateErrors = validateWorkoutRefs(validation.data, templates);
+    if (templateErrors.length > 0) {
+        log.warn("Template reference warnings:");
+        templateErrors.forEach((e) => console.error(`  - ${e}`));
+    }
+    // Expand the plan
+    const expanded = expandPlan(validation.data, templates);
+    if (args.verbose) {
+        log.info(`Expanded ${expanded.weeks.length} weeks`);
+    }
+    // Format output
+    let output;
+    if (args.format === "yaml") {
+        output = stringifyYaml(expanded);
+    }
+    else {
+        output = JSON.stringify(expanded, null, 2);
+    }
+    // Write output
+    if (args.outputFile) {
+        writeFileSync(args.outputFile, output);
+        log.success(`Expanded plan written to: ${args.outputFile}`);
+    }
+    else {
+        console.log(output);
+    }
+}
+// ============================================================================
+// Templates Command
+// ============================================================================
+function runTemplates(args) {
+    const templates = loadTemplates();
+    if (args.show) {
+        // Show details of a specific template
+        const template = templates.get(args.show);
+        if (!template) {
+            log.error(`Template not found: ${args.show}`);
+            console.log("\nAvailable templates:");
+            templates.ids().forEach((id) => console.log(`  - ${id}`));
+            process.exit(1);
+        }
+        console.log(`\n${template.name} (${template.id})`);
+        console.log(`${"=".repeat(template.name.length + template.id.length + 3)}`);
+        console.log(`\nSport: ${template.sport}`);
+        console.log(`Category: ${template.category}`);
+        console.log(`Type: ${template.type}`);
+        if (template.targetZone) {
+            console.log(`Target Zone: ${template.targetZone}`);
+        }
+        if (template.rpe) {
+            console.log(`RPE: ${template.rpe}`);
+        }
+        if (template.estimatedDuration) {
+            console.log(`Estimated Duration: ${template.estimatedDuration} min`);
+        }
+        if (template.params && Object.keys(template.params).length > 0) {
+            console.log("\nParameters:");
+            for (const [name, param] of Object.entries(template.params)) {
+                const required = param.required ? " (required)" : "";
+                const defaultVal = param.default !== undefined ? ` [default: ${param.default}]` : "";
+                console.log(`  - ${name}: ${param.type}${required}${defaultVal}`);
+                if (param.description) {
+                    console.log(`    ${param.description}`);
+                }
+            }
+        }
+        console.log("\nUsage examples:");
+        const paramNames = template.params ? Object.keys(template.params) : [];
+        if (paramNames.length === 0) {
+            console.log(`  ${template.id}`);
+        }
+        else {
+            const defaults = paramNames
+                .filter((p) => template.params[p].default !== undefined)
+                .map((p) => template.params[p].default);
+            if (defaults.length > 0) {
+                console.log(`  ${template.id}(${defaults.join(", ")})`);
+            }
+            console.log(`  ${template.id}(${paramNames.join(", ")})`);
+        }
+        console.log("\nWorkout description:");
+        console.log(template.humanReadable);
+    }
+    else {
+        // List all templates
+        const sport = args.sport;
+        const list = templates.list(sport);
+        if (list.length === 0) {
+            console.log("No templates found.");
+            return;
+        }
+        console.log(`\nAvailable Templates${sport ? ` (${sport})` : ""}:`);
+        console.log("=".repeat(40));
+        // Group by category
+        const byCategory = new Map();
+        for (const t of list) {
+            const cat = t.category;
+            if (!byCategory.has(cat)) {
+                byCategory.set(cat, []);
+            }
+            byCategory.get(cat).push(t);
+        }
+        for (const [category, categoryTemplates] of byCategory) {
+            console.log(`\n${category.toUpperCase()}:`);
+            for (const t of categoryTemplates) {
+                const params = t.params ? Object.keys(t.params) : [];
+                const paramStr = params.length > 0 ? `(${params.join(", ")})` : "";
+                console.log(`  ${t.id}${paramStr} - ${t.name}`);
+            }
+        }
+        console.log(`\nTotal: ${list.length} templates`);
+        console.log("\nUse 'endurance-coach templates show <id>' to see template details.");
+    }
 }
 // ============================================================================
 // Schema Command
@@ -1060,6 +1337,12 @@ async function main() {
         case "validate":
             runValidate(args);
             break;
+        case "expand":
+            runExpand(args);
+            break;
+        case "templates":
+            runTemplates(args);
+            break;
         case "render":
             runRender(args);
             break;

package/dist/expander/expander.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Core Expander
+ *
+ * Converts compact training plans to expanded format for HTML rendering.
+ */
+import type { CompactPlan } from "../schema/compact-plan.js";
+import type { TemplateRegistry, InterpolationContext } from "../templates/index.js";
+import type { ExpandedPlan, ExpandedWorkout, ExpansionOptions } from "./types.js";
+/**
+ * Expand a single workout from its template reference.
+ */
+export declare function expandWorkout(ref: string, workoutId: string, context: InterpolationContext, templates: TemplateRegistry): ExpandedWorkout;
+/**
+ * Expand a compact plan into the full format for HTML rendering.
+ */
+export declare function expandPlan(compact: CompactPlan, templates: TemplateRegistry, options?: ExpansionOptions): ExpandedPlan;
+/**
+ * Validate that all workout references in a compact plan have corresponding templates.
+ */
+export declare function validateWorkoutRefs(compact: CompactPlan, templates: TemplateRegistry): string[];