endurance-coach 1.1.0 → 1.3.0

package/README.md

@@ -89,6 +89,17 @@ In the next step, the AI will ask you about yourself, the event you're training
 
 The AI will use this information to create a plan tailored to your current fitness level. The more detail you provide, the better your plan will be.
 
+## Contributing
+
+We welcome contributions from the community! Whether you want to add workout templates, improve the UI, fix bugs, or enhance documentation, your help is appreciated.
+
+Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for:
+
+- Development setup instructions
+- Coding standards and guidelines
+- How to submit pull requests
+- Areas where we need help
+
 # About
 
 ## Lineage & Architectural Evolution

package/dist/cli/args.d.ts

@@ -0,0 +1,117 @@
+export interface SyncArgs {
+    command: "sync";
+    clientId?: string;
+    clientSecret?: string;
+    accessToken?: string;
+    refreshToken?: string;
+    days?: number;
+}
+export interface RenderArgs {
+    command: "render";
+    inputFile: string;
+    outputFile?: string;
+}
+export interface StatsArgs {
+    command: "stats";
+    weeks?: number;
+    longestWeeks?: number;
+    json: boolean;
+}
+export interface TrainingLoadArgs {
+    command: "training-load";
+    weeks?: number;
+    json: boolean;
+}
+export interface FoundationArgs {
+    command: "foundation";
+    topWeeks?: number;
+    json: boolean;
+}
+export interface StrengthArgs {
+    command: "strength";
+    months?: number;
+    longMonths?: number;
+    easyHrMax?: number;
+    longMinutes?: number;
+    years?: number;
+    json: boolean;
+}
+export interface SchedulePreferencesArgs {
+    command: "schedule-preferences";
+    rideMinutes?: number;
+    runMinutes?: number;
+    json: boolean;
+}
+export interface HrZonesArgs {
+    command: "hr-zones";
+    weeks?: number;
+    distributionWeeks?: number;
+    json: boolean;
+}
+export interface QueryArgs {
+    command: "query";
+    sql: string;
+    json: boolean;
+}
+export interface AuthArgs {
+    command: "auth";
+    clientId?: string;
+    clientSecret?: string;
+    code?: string;
+}
+export interface ActivityLapsArgs {
+    command: "activity";
+    id: number;
+    laps: true;
+}
+export interface HelpArgs {
+    command: "help";
+}
+export interface ValidateArgs {
+    command: "validate";
+    inputFile: string;
+    compact?: boolean;
+}
+export interface ExpandArgs {
+    command: "expand";
+    inputFile: string;
+    outputFile?: string;
+    format?: "json" | "yaml";
+    verbose?: boolean;
+}
+export interface TemplatesArgs {
+    command: "templates";
+    sport?: string;
+    show?: string;
+    type?: string;
+    source?: "user" | "builtin" | "all";
+    verbose?: boolean;
+    create?: string;
+    category?: string;
+    templateFile?: string;
+    overwrite?: boolean;
+    dryRun?: boolean;
+    example?: boolean;
+    userTemplatesDir?: string;
+    validate?: string;
+}
+export interface SchemaArgs {
+    command: "schema";
+}
+export interface ModifyArgs {
+    command: "modify";
+    backup: string;
+    plan: string;
+    output?: string;
+}
+export type CliArgs = SyncArgs | RenderArgs | StatsArgs | TrainingLoadArgs | FoundationArgs | StrengthArgs | SchedulePreferencesArgs | HrZonesArgs | QueryArgs | AuthArgs | ActivityLapsArgs | HelpArgs | ModifyArgs | ValidateArgs | SchemaArgs | ExpandArgs | TemplatesArgs;
+/**
+ * Parse command-line arguments from process.argv and produce the corresponding CLI command object.
+ *
+ * The returned object identifies the selected command and any parsed options or flags.
+ *
+ * Note: for missing required inputs or invalid option values this function logs an error and exits the process with status 1.
+ *
+ * @returns A `CliArgs` object describing the requested command and its parsed options
+ */
+export declare function parseArgs(): CliArgs;

package/dist/cli/args.js

@@ -0,0 +1,452 @@
+import { log } from "../lib/logging.js";
+// ============================================================================
+// MARK: Argument Parsing
+// ============================================================================
+/**
+ * Parse command-line arguments from process.argv and produce the corresponding CLI command object.
+ *
+ * The returned object identifies the selected command and any parsed options or flags.
+ *
+ * Note: for missing required inputs or invalid option values this function logs an error and exits the process with status 1.
+ *
+ * @returns A `CliArgs` object describing the requested command and its parsed options
+ */
+export function parseArgs() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === "sync") {
+        // Sync command (default)
+        const syncArgs = { command: "sync" };
+        for (const arg of args) {
+            if (arg.startsWith("--client-id=")) {
+                syncArgs.clientId = arg.split("=")[1];
+            }
+            else if (arg.startsWith("--client-secret=")) {
+                syncArgs.clientSecret = arg.split("=")[1];
+            }
+            else if (arg.startsWith("--access-token=")) {
+                syncArgs.accessToken = arg.split("=")[1];
+            }
+            else if (arg.startsWith("--refresh-token=")) {
+                syncArgs.refreshToken = arg.split("=")[1];
+            }
+            else if (arg.startsWith("--days=")) {
+                const parsed = parseInt(arg.split("=")[1], 10);
+                if (Number.isNaN(parsed)) {
+                    log.error("Invalid --days value: must be a number");
+                    process.exit(1);
+                }
+                syncArgs.days = parsed;
+            }
+        }
+        return syncArgs;
+    }
+    if (args[0] === "render") {
+        if (!args[1]) {
+            log.error("render command requires an input file");
+            process.exit(1);
+        }
+        const renderArgs = {
+            command: "render",
+            inputFile: args[1],
+        };
+        for (let i = 2; i < args.length; i++) {
+            if (args[i] === "--output" || args[i] === "-o") {
+                renderArgs.outputFile = args[i + 1];
+                i++;
+            }
+            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;
+    }
+    if (args[0] === "stats") {
+        const statsArgs = {
+            command: "stats",
+            json: args.includes("--json"),
+        };
+        for (let i = 1; i < args.length; i++) {
+            if (args[i] === "--weeks") {
+                statsArgs.weeks = parseInt(args[i + 1], 10);
+                i++;
+            }
+            else if (args[i].startsWith("--weeks=")) {
+                statsArgs.weeks = parseInt(args[i].split("=")[1], 10);
+            }
+            else if (args[i] === "--longest-weeks") {
+                statsArgs.longestWeeks = parseInt(args[i + 1], 10);
+                i++;
+            }
+            else if (args[i].startsWith("--longest-weeks=")) {
+                statsArgs.longestWeeks = parseInt(args[i].split("=")[1], 10);
+            }
+        }
+        return statsArgs;
+    }
+    if (args[0] === "training-load") {
+        const trainingLoadArgs = {
+            command: "training-load",
+            json: args.includes("--json"),
+        };
+        for (let i = 1; i < args.length; i++) {
+            if (args[i] === "--weeks") {
+                trainingLoadArgs.weeks = parseInt(args[i + 1]);
+                i++;
+            }
+            else if (args[i].startsWith("--weeks=")) {
+                trainingLoadArgs.weeks = parseInt(args[i].split("=")[1]);
+            }
+        }
+        return trainingLoadArgs;
+    }
+    if (args[0] === "foundation") {
+        const foundationArgs = {
+            command: "foundation",
+            json: args.includes("--json"),
+        };
+        for (let i = 1; i < args.length; i++) {
+            if (args[i] === "--top-weeks") {
+                foundationArgs.topWeeks = parseInt(args[i + 1]);
+                i++;
+            }
+            else if (args[i].startsWith("--top-weeks=")) {
+                foundationArgs.topWeeks = parseInt(args[i].split("=")[1]);
+            }
+        }
+        return foundationArgs;
+    }
+    if (args[0] === "strength") {
+        const strengthArgs = {
+            command: "strength",
+            json: args.includes("--json"),
+        };
+        for (let i = 1; i < args.length; i++) {
+            if (args[i] === "--months") {
+                strengthArgs.months = parseInt(args[i + 1]);
+                i++;
+            }
+            else if (args[i].startsWith("--months=")) {
+                strengthArgs.months = parseInt(args[i].split("=")[1]);
+            }
+            else if (args[i] === "--long-months") {
+                strengthArgs.longMonths = parseInt(args[i + 1]);
+                i++;
+            }
+            else if (args[i].startsWith("--long-months=")) {
+                strengthArgs.longMonths = parseInt(args[i].split("=")[1]);
+            }
+            else if (args[i] === "--easy-hr-max") {
+                strengthArgs.easyHrMax = parseInt(args[i + 1]);
+                i++;
+            }
+            else if (args[i].startsWith("--easy-hr-max=")) {
+                strengthArgs.easyHrMax = parseInt(args[i].split("=")[1]);
+            }
+            else if (args[i] === "--long-minutes") {
+                strengthArgs.longMinutes = parseInt(args[i + 1]);
+                i++;
+            }
+            else if (args[i].startsWith("--long-minutes=")) {
+                strengthArgs.longMinutes = parseInt(args[i].split("=")[1]);
+            }
+            else if (args[i] === "--years") {
+                strengthArgs.years = parseInt(args[i + 1]);
+                i++;
+            }
+            else if (args[i].startsWith("--years=")) {
+                strengthArgs.years = parseInt(args[i].split("=")[1]);
+            }
+        }
+        return strengthArgs;
+    }
+    if (args[0] === "schedule-preferences") {
+        const scheduleArgs = {
+            command: "schedule-preferences",
+            json: args.includes("--json"),
+        };
+        for (let i = 1; i < args.length; i++) {
+            if (args[i] === "--ride-minutes") {
+                scheduleArgs.rideMinutes = parseInt(args[i + 1]);
+                i++;
+            }
+            else if (args[i].startsWith("--ride-minutes=")) {
+                scheduleArgs.rideMinutes = parseInt(args[i].split("=")[1]);
+            }
+            else if (args[i] === "--run-minutes") {
+                scheduleArgs.runMinutes = parseInt(args[i + 1]);
+                i++;
+            }
+            else if (args[i].startsWith("--run-minutes=")) {
+                scheduleArgs.runMinutes = parseInt(args[i].split("=")[1]);
+            }
+        }
+        return scheduleArgs;
+    }
+    if (args[0] === "hr-zones") {
+        const hrArgs = {
+            command: "hr-zones",
+            json: args.includes("--json"),
+        };
+        for (let i = 1; i < args.length; i++) {
+            if (args[i] === "--weeks") {
+                hrArgs.weeks = parseInt(args[i + 1]);
+                i++;
+            }
+            else if (args[i].startsWith("--weeks=")) {
+                hrArgs.weeks = parseInt(args[i].split("=")[1]);
+            }
+            else if (args[i] === "--distribution-weeks") {
+                hrArgs.distributionWeeks = parseInt(args[i + 1]);
+                i++;
+            }
+            else if (args[i].startsWith("--distribution-weeks=")) {
+                hrArgs.distributionWeeks = parseInt(args[i].split("=")[1]);
+            }
+        }
+        return hrArgs;
+    }
+    if (args[0] === "query") {
+        if (!args[1]) {
+            log.error("query command requires a SQL statement");
+            process.exit(1);
+        }
+        const queryArgs = {
+            command: "query",
+            sql: args[1],
+            json: args.includes("--json"),
+        };
+        return queryArgs;
+    }
+    if (args[0] === "auth") {
+        const authArgs = { command: "auth" };
+        for (const arg of args) {
+            if (arg.startsWith("--client-id=")) {
+                authArgs.clientId = arg.slice("--client-id=".length);
+            }
+            else if (arg.startsWith("--client-secret=")) {
+                authArgs.clientSecret = arg.slice("--client-secret=".length);
+            }
+            else if (arg.startsWith("--code=")) {
+                authArgs.code = arg.slice("--code=".length);
+            }
+        }
+        return authArgs;
+    }
+    if (args[0] === "activity") {
+        if (!args[1]) {
+            log.error("activity command requires an activity ID");
+            process.exit(1);
+        }
+        const id = parseInt(args[1], 10);
+        if (Number.isNaN(id)) {
+            log.error(`Invalid activity ID: ${args[1]}`);
+            process.exit(1);
+        }
+        let laps = false;
+        for (let i = 2; i < args.length; i++) {
+            if (args[i] === "--laps") {
+                laps = true;
+            }
+        }
+        if (!laps) {
+            log.error("activity command requires a subcommand flag like --laps");
+            process.exit(1);
+        }
+        const activityArgs = {
+            command: "activity",
+            id,
+            laps: true,
+        };
+        return activityArgs;
+    }
+    if (args[0] === "validate") {
+        if (!args[1]) {
+            log.error("validate command requires an input file");
+            process.exit(1);
+        }
+        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] === "list") {
+                // Default subcommand, no action needed
+            }
+            else if (args[i] === "show") {
+                if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+                    templatesArgs.show = args[i + 1];
+                    i++;
+                }
+            }
+            else if (args[i] === "create") {
+                if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+                    templatesArgs.create = args[i + 1];
+                    i++;
+                }
+            }
+            else if (args[i] === "validate") {
+                if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+                    templatesArgs.validate = args[i + 1];
+                    i++;
+                }
+            }
+            else if (args[i] === "--sport") {
+                templatesArgs.sport = args[i + 1];
+                i++;
+            }
+            else if (args[i] === "--type") {
+                templatesArgs.type = args[i + 1];
+                i++;
+            }
+            else if (args[i] === "--source") {
+                const sourceVal = args[i + 1];
+                if (sourceVal === "user" || sourceVal === "builtin" || sourceVal === "all") {
+                    templatesArgs.source = sourceVal;
+                }
+                else {
+                    log.error(`Invalid source value: ${sourceVal}. Must be 'user', 'builtin', or 'all'`);
+                    process.exit(1);
+                }
+                i++;
+            }
+            else if (args[i] === "--verbose" || args[i] === "-v") {
+                templatesArgs.verbose = true;
+            }
+            else if (args[i] === "--category") {
+                templatesArgs.category = args[i + 1];
+                i++;
+            }
+            else if (args[i] === "--template-file") {
+                templatesArgs.templateFile = args[i + 1];
+                i++;
+            }
+            else if (args[i] === "--overwrite") {
+                templatesArgs.overwrite = true;
+            }
+            else if (args[i] === "--dry-run") {
+                templatesArgs.dryRun = true;
+            }
+            else if (args[i] === "--example") {
+                templatesArgs.example = true;
+            }
+            else if (args[i].startsWith("--sport=")) {
+                templatesArgs.sport = args[i].split("=")[1];
+            }
+            else if (args[i].startsWith("--type=")) {
+                templatesArgs.type = args[i].split("=")[1];
+            }
+            else if (args[i].startsWith("--source=")) {
+                const sourceVal = args[i].split("=")[1];
+                if (sourceVal === "user" || sourceVal === "builtin" || sourceVal === "all") {
+                    templatesArgs.source = sourceVal;
+                }
+                else {
+                    log.error(`Invalid source value: ${sourceVal}. Must be 'user', 'builtin', or 'all'`);
+                    process.exit(1);
+                }
+            }
+            else if (args[i].startsWith("--category=")) {
+                templatesArgs.category = args[i].split("=")[1];
+            }
+            else if (args[i].startsWith("--template-file=")) {
+                templatesArgs.templateFile = args[i].split("=")[1];
+            }
+            else if (!args[i].startsWith("-") &&
+                !templatesArgs.show &&
+                !templatesArgs.create &&
+                !templatesArgs.validate) {
+                // Treat as template ID for 'show' subcommand
+                templatesArgs.show = args[i];
+            }
+        }
+        return templatesArgs;
+    }
+    if (args[0] === "schema") {
+        return { command: "schema" };
+    }
+    if (args[0] === "modify") {
+        if (!args[1] || !args[2]) {
+            log.error("modify command requires --backup and --plan arguments");
+            process.exit(1);
+        }
+        const modifyArgs = {
+            command: "modify",
+            backup: "",
+            plan: "",
+        };
+        for (let i = 1; i < args.length; i++) {
+            if (args[i] === "--backup" || args[i] === "-b") {
+                modifyArgs.backup = args[i + 1];
+                i++;
+            }
+            else if (args[i].startsWith("--backup=")) {
+                modifyArgs.backup = args[i].split("=")[1];
+            }
+            else if (args[i] === "--plan" || args[i] === "-p") {
+                modifyArgs.plan = args[i + 1];
+                i++;
+            }
+            else if (args[i].startsWith("--plan=")) {
+                modifyArgs.plan = args[i].split("=")[1];
+            }
+            else if (args[i] === "--output" || args[i] === "-o") {
+                modifyArgs.output = args[i + 1];
+                i++;
+            }
+            else if (args[i].startsWith("--output=")) {
+                modifyArgs.output = args[i].split("=")[1];
+            }
+        }
+        if (!modifyArgs.backup || !modifyArgs.plan) {
+            log.error("Both --backup and --plan are required");
+            process.exit(1);
+        }
+        return modifyArgs;
+    }
+    if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+        return { command: "help" };
+    }
+    log.error(`Unknown command: ${args[0]}`);
+    process.exit(1);
+}

package/dist/cli/commands/expand.d.ts

@@ -0,0 +1,16 @@
+import type { ExpandArgs } from "../args.js";
+/**
+ * Executes the Expand command to transform a compact plan into an expanded plan.
+ *
+ * Reads the compact plan from disk, parses and validates it, loads templates (including user templates),
+ * validates template references, expands the plan, and emits the expanded plan as YAML or JSON.
+ *
+ * @param args - Command arguments:
+ *   - inputFile: Path to the compact plan file (YAML).
+ *   - outputFile: Optional path to write the expanded plan; if omitted the result is printed to stdout.
+ *   - format: Output format, either `"yaml"` or `"json"`.
+ *   - verbose: When true, emits additional progress information.
+ *
+ * Exits the process with code 1 on file read, YAML parse, or validation failures.
+ */
+export declare function runExpand(args: ExpandArgs): void;

package/dist/cli/commands/expand.js

@@ -0,0 +1,89 @@
+import { readFileSync, writeFileSync } from "fs";
+import { log } from "../../lib/logging.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";
+// ============================================================================
+// MARK: Expand Command
+// ============================================================================
+/**
+ * Executes the Expand command to transform a compact plan into an expanded plan.
+ *
+ * Reads the compact plan from disk, parses and validates it, loads templates (including user templates),
+ * validates template references, expands the plan, and emits the expanded plan as YAML or JSON.
+ *
+ * @param args - Command arguments:
+ *   - inputFile: Path to the compact plan file (YAML).
+ *   - outputFile: Optional path to write the expanded plan; if omitted the result is printed to stdout.
+ *   - format: Output format, either `"yaml"` or `"json"`.
+ *   - verbose: When true, emits additional progress information.
+ *
+ * Exits the process with code 1 on file read, YAML parse, or validation failures.
+ */
+export 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("Compact plan validation failed:");
+        console.error(formatCompactValidationErrors(validation.errors));
+        process.exit(1);
+    }
+    // Load templates (include user templates)
+    const templates = loadTemplates({ includeUserTemplates: true });
+    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("Compact plan validation failed with template reference warnings:");
+        templateErrors.forEach((e) => log.error(`  - ${e}`));
+        process.exit(1);
+    }
+    // Expand the plan
+    let expanded;
+    try {
+        expanded = expandPlan(validation.data, templates);
+    }
+    catch (error) {
+        log.error(`Failed to expand plan: ${error instanceof Error ? error.message : "Unknown error"}`);
+        process.exit(1);
+    }
+    if (args.verbose) {
+        log.info(`Expanded ${expanded.weeks.length} weeks`);
+    }
+    // Format output + write
+    try {
+        const output = args.format === "yaml" ? stringifyYaml(expanded) : JSON.stringify(expanded, null, 2);
+        if (args.outputFile) {
+            writeFileSync(args.outputFile, output);
+            log.success(`Expanded plan written to: ${args.outputFile}`);
+        }
+        else {
+            console.log(output);
+        }
+    }
+    catch (error) {
+        log.error(`Failed to write expanded plan: ${error instanceof Error ? error.message : "Unknown error"}`);
+        process.exit(1);
+    }
+}