trainerroad-cli 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.3.0 - 2026-03-25
+
+- Added richer command help with examples, required-flag metadata, and machine-readable help payloads.
+- Improved agent-facing failure messages so missing required flags fail fast with actionable retry guidance.
+- Added `--dry-run` previews for calendar mutation commands.
+- Made convergent mutation commands idempotent when the requested end state is already satisfied.
+- Fixed login default return-path handling so it follows the provided username.
+- Added automated tests covering CLI help/error behavior and write-command dry-run/no-op semantics.

package/README.md

@@ -14,6 +14,27 @@ CLI to fetch TrainerRoad data for your account, including:
 - power ranking and power records
 - weight history
 
+It can also perform a small set of verified calendar writes for planned workouts:
+
+- search the workout library by zone/profile/search text/duration/level
+- fetch AI suggested workouts from TrainNow
+- recommend library workouts against target duration/level/TSS
+- fetch workout-library details by workout ID
+- add a library workout to a calendar date
+- copy an existing planned workout to another date
+- move a planned workout to a new date
+- list TrainerRoad alternate workout options
+- replace a workout with a specific alternate
+- switch a workout between inside and outside
+
+## Agent-Friendly Behavior
+
+- Non-interactive by default. Inputs are flags or stdin, not prompts.
+- Progressive disclosure. Use `trainerroad-cli help <command>` or `trainerroad-cli discover`.
+- Command help includes concrete examples and flag descriptions.
+- Write commands support `--dry-run` previews.
+- Common retry cases are idempotent no-ops instead of duplicate calendar writes.
+
 ## Install
 
 ### Run without install (npx)
@@ -64,9 +85,38 @@ trainerroad-cli plan --view current --json
 trainerroad-cli levels --json
 trainerroad-cli ftp --json
 trainerroad-cli today --tz America/New_York --json
+trainerroad-cli train-now --duration 60 --json
+trainerroad-cli workout-library --zone "Endurance" --profile "Sustained Power" --min-duration 45 --max-duration 75 --json
+trainerroad-cli workout-recommend --zone "Endurance" --profile "Sustained Power" --target-duration 60 --target-level 1.0 --count 3 --json
+trainerroad-cli workout-details --id 18128 --include-chart --json
+trainerroad-cli add-workout --workout-id 18128 --date 2026-03-16 --json
+trainerroad-cli add-workout --workout-id 18128 --date 2026-03-16 --dry-run
+trainerroad-cli copy-workout --id <planned-activity-id> --date 2026-03-16 --json
+```
+
+3. Mutate planned workouts
+
+First get a planned workout ID from `future --details`:
+
+```bash
+trainerroad-cli future --days 14 --details --json
+```
+
+Then use that planned activity ID:
+
+```bash
+trainerroad-cli workout-alternates --id <planned-activity-id> --category easier --json
+trainerroad-cli move-workout --id <planned-activity-id> --to 2026-03-13 --dry-run
+trainerroad-cli move-workout --id <planned-activity-id> --to 2026-03-13 --json
+trainerroad-cli replace-workout --id <planned-activity-id> --alternate-id <workout-id> --json
+trainerroad-cli switch-workout --id <planned-activity-id> --mode outside --json
+trainerroad-cli copy-workout --id <planned-activity-id> --date 2026-03-16 --json
 ```
 
-3. Discover all commands
+`copy-workout` is the reliable way to place an existing planned workout on another date.
+`add-workout` exists, but TrainerRoad's add endpoints are still inconsistent and may fail even after retry/reconciliation.
+
+4. Discover all commands
 
 ```bash
 trainerroad-cli help
@@ -90,6 +140,15 @@ Use `--target <username>` and/or `--public` for public mode queries.
 - `--records-only`: lighter record payloads
 - `--tz <IANA timezone>`: localize day boundaries/timestamps (defaults to `TR_TIMEZONE` or system timezone)
 
+## Help
+
+```bash
+trainerroad-cli help
+trainerroad-cli help future
+trainerroad-cli future --help
+trainerroad-cli help move-workout --json
+```
+
 ## Security
 
 - Session cookies are stored in `.trainerroad/session.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trainerroad-cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Unofficial CLI for authenticating with TrainerRoad and querying timeline/workout data",
   "main": "src/cli.mjs",
   "bin": {
@@ -9,10 +9,12 @@
   },
   "files": [
     "src",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
+    "test": "node --test",
     "recon": "node scripts/recon.mjs",
     "cli": "node src/cli.mjs",
     "help": "node src/cli.mjs help",
@@ -21,6 +23,7 @@
     "login": "node src/cli.mjs login",
     "whoami": "node src/cli.mjs whoami",
     "timeline": "node src/cli.mjs timeline",
+    "train-now": "node src/cli.mjs train-now",
     "events": "node src/cli.mjs events",
     "annotations": "node src/cli.mjs annotations",
     "levels": "node src/cli.mjs levels",
@@ -33,6 +36,15 @@
     "ftp-prediction": "node src/cli.mjs ftp-prediction",
     "power-ranking": "node src/cli.mjs power-ranking",
     "power-records": "node src/cli.mjs power-records",
+    "workout-library": "node src/cli.mjs workout-library",
+    "workout-recommend": "node src/cli.mjs workout-recommend",
+    "workout-details": "node src/cli.mjs workout-details",
+    "add-workout": "node src/cli.mjs add-workout",
+    "copy-workout": "node src/cli.mjs copy-workout",
+    "workout-alternates": "node src/cli.mjs workout-alternates",
+    "move-workout": "node src/cli.mjs move-workout",
+    "replace-workout": "node src/cli.mjs replace-workout",
+    "switch-workout": "node src/cli.mjs switch-workout",
     "logout": "node src/cli.mjs logout"
   },
   "keywords": [

package/src/cli.mjs

@@ -17,7 +17,9 @@ import {
   AGENT_FILTER_OPTIONS,
   AGENT_OUTPUT_OPTIONS,
   COMMAND_FLAG_ALLOWLIST,
+  COMMAND_REQUIRED_FLAGS,
   COMMANDS,
+  FLAG_DETAILS,
   FILTERABLE_COMMANDS,
   GLOBAL_NOTES,
   PROJECT_NOTICE,
@@ -31,7 +33,17 @@ import { commandLevels } from "./commands/levels.mjs";
 import { commandPlan } from "./commands/plan.mjs";
 import { commandPowerRanking, commandPowerRecords } from "./commands/power.mjs";
 import { commandTimeline } from "./commands/timeline.mjs";
+import { commandTrainNow } from "./commands/train-now.mjs";
 import { commandWeightHistory } from "./commands/weight-history.mjs";
+import { commandWorkoutLibrary } from "./commands/workout-library.mjs";
+import { commandWorkoutRecommend } from "./commands/workout-recommend.mjs";
+import { commandAddWorkout, commandCopyWorkout, commandWorkoutDetails } from "./commands/workout-tools.mjs";
+import {
+  commandMoveWorkout,
+  commandReplaceWorkout,
+  commandSwitchWorkout,
+  commandWorkoutAlternates,
+} from "./commands/workout-mutations.mjs";
 import { commandFuture, commandPast, commandToday } from "./commands/workouts.mjs";
 import {
   formatDateTimeInTimeZone,
@@ -56,17 +68,27 @@ function printGlobalHelp() {
   for (const note of GLOBAL_NOTES) console.log(`  - ${note}`);
   console.log("");
   console.log("Progressive disclosure:");
-  console.log("  node src/cli.mjs discover --level 1");
-  console.log("  node src/cli.mjs discover --level 2");
-  console.log("  node src/cli.mjs discover --command future --level 3 --json");
+  console.log("  trainerroad-cli discover --level 1");
+  console.log("  trainerroad-cli discover --level 2");
+  console.log("  trainerroad-cli discover --command future --level 3 --json");
+  console.log("");
+  console.log('Use "trainerroad-cli <command> --help" for command-specific options and examples.');
   console.log("");
   console.log("Examples:");
-  console.log("  node src/cli.mjs login --username quinnsprouse --password-stdin");
-  console.log("  node src/cli.mjs future --days 30 --details --json");
-  console.log("  node src/cli.mjs today --tz America/New_York --json");
-  console.log("  node src/cli.mjs future --from 2026-03-01 --to 2026-03-31 --min-tss 60 --fields id,title,tss --jsonl");
-  console.log("  node src/cli.mjs timeline --target quinnsprouse --public --json");
-  console.log("  node src/cli.mjs ftp --target quinnsprouse --public --json");
+  console.log("  trainerroad-cli login --username quinnsprouse --password-stdin");
+  console.log("  trainerroad-cli future --days 30 --details --json");
+  console.log("  trainerroad-cli today --tz America/New_York --json");
+  console.log("  trainerroad-cli future --from 2026-03-01 --to 2026-03-31 --min-tss 60 --fields id,title,tss --jsonl");
+  console.log("  trainerroad-cli timeline --target quinnsprouse --public --json");
+  console.log("  trainerroad-cli ftp --target quinnsprouse --public --json");
+  console.log("  trainerroad-cli move-workout --id <planned-id> --to 2026-03-13 --dry-run");
+  console.log("  trainerroad-cli workout-alternates --id <planned-id> --category easier --json");
+  console.log('  trainerroad-cli workout-library --zone "Endurance" --profile "Sustained Power" --min-duration 45 --max-duration 75 --json');
+  console.log('  trainerroad-cli workout-recommend --zone "Endurance" --profile "Sustained Power" --target-duration 60 --target-level 1.0 --count 3 --json');
+  console.log("  trainerroad-cli train-now --duration 60 --json");
+  console.log("  trainerroad-cli workout-details --id 18128 --include-chart --json");
+  console.log("  trainerroad-cli add-workout --workout-id 18128 --date 2026-03-16 --dry-run");
+  console.log("  trainerroad-cli copy-workout --id <planned-id> --date 2026-03-16 --json");
 }
 
 function levenshteinDistance(left, right) {
@@ -179,6 +201,45 @@ function validateCommandFlags(command, flags) {
   return { unknownFlags, allowlist: Array.from(allowlist) };
 }
 
+function formatFlagLabel(name) {
+  const detail = FLAG_DETAILS[name] ?? {};
+  return `--${name}${detail.placeholder ? ` ${detail.placeholder}` : ""}`;
+}
+
+function getCommandHelpOptions(command) {
+  const allowlist = Array.from(COMMAND_FLAG_ALLOWLIST[command] ?? []);
+  const requiredFlags = new Set(COMMAND_REQUIRED_FLAGS[command] ?? []);
+  return allowlist.map((name) => ({
+    name,
+    label: formatFlagLabel(name),
+    description: FLAG_DETAILS[name]?.description ?? "No description available.",
+    required: requiredFlags.has(name),
+  }));
+}
+
+function formatMissingRequiredFlagMessage(command, flagName) {
+  const def = COMMANDS[command];
+  const requiredFlags = (COMMAND_REQUIRED_FLAGS[command] ?? []).map((name) => `--${name}`);
+  const usageLines = Array.isArray(def?.usage) ? def.usage : [];
+  const exampleLines = Array.isArray(def?.examples) ? def.examples : [];
+  const lines = [`Missing required flag --${flagName} for "trainerroad-cli ${command}".`];
+
+  if (requiredFlags.length > 0) {
+    lines.push("", `Required flags: ${requiredFlags.join(", ")}`);
+  }
+  if (usageLines.length > 0) {
+    lines.push("", "Usage:");
+    for (const line of usageLines) lines.push(`  ${line}`);
+  }
+  if (exampleLines.length > 0) {
+    lines.push("", "Examples:");
+    for (const line of exampleLines) lines.push(`  ${line}`);
+  }
+
+  lines.push("", `Run "trainerroad-cli help ${command}" for more detail.`);
+  return lines.join("\n");
+}
+
 function printCommandHelp(command, flags = {}) {
   const def = COMMANDS[command];
   if (!def) {
@@ -186,11 +247,16 @@ function printCommandHelp(command, flags = {}) {
     return 1;
   }
   if (flags.json) {
+    const options = getCommandHelpOptions(command);
     const payload = {
       command,
       summary: def.summary,
       usage: def.usage,
-      timezoneOption: "--tz <IANA timezone> (defaults to TR_TIMEZONE or system timezone)",
+      examples: def.examples ?? [],
+      options,
+      requiredFlags: options.filter((option) => option.required).map((option) => option.name),
+      nonInteractive: true,
+      supportsDryRun: options.some((option) => option.name === "dry-run"),
       supportsAgentFilters: FILTERABLE_COMMANDS.has(command),
       agentFilterOptions: FILTERABLE_COMMANDS.has(command) ? AGENT_FILTER_OPTIONS : [],
       agentOutputOptions: FILTERABLE_COMMANDS.has(command) ? AGENT_OUTPUT_OPTIONS : [],
@@ -207,18 +273,15 @@ function printCommandHelp(command, flags = {}) {
   console.log("Usage:");
   for (const line of def.usage) console.log(`  ${line}`);
   console.log("");
-  console.log("Timezone:");
-  console.log("  --tz <IANA timezone> Override local-day bucketing (defaults: TR_TIMEZONE or system timezone).");
-  if (FILTERABLE_COMMANDS.has(command)) {
+  console.log("Options:");
+  for (const option of getCommandHelpOptions(command)) {
+    const suffix = option.required ? " [required]" : "";
+    console.log(`  ${option.label.padEnd(34)} ${option.description}${suffix}`);
+  }
+  if (Array.isArray(def.examples) && def.examples.length > 0) {
     console.log("");
-    console.log("Agent filters:");
-    for (const option of AGENT_FILTER_OPTIONS) {
-      console.log(`  ${option.flag.padEnd(14)} ${option.description}`);
-    }
-    console.log("Agent output options:");
-    for (const option of AGENT_OUTPUT_OPTIONS) {
-      console.log(`  ${option.flag.padEnd(14)} ${option.description}`);
-    }
+    console.log("Examples:");
+    for (const line of def.examples) console.log(`  ${line}`);
   }
   return 0;
 }
@@ -625,6 +688,13 @@ async function main() {
     summarizeActivityTime,
     withClient,
     readPasswordFromStdin,
+    requireFlag: (commandName, incomingFlags, flagName) => {
+      const value = incomingFlags[flagName];
+      if (value === undefined || value === null || value === "") {
+        throw new Error(formatMissingRequiredFlagMessage(commandName, flagName));
+      }
+      return value;
+    },
     normalizeFtpHistory,
     getLastItem,
     normalizeFitnessThresholds,
@@ -650,6 +720,9 @@ async function main() {
     case "timeline":
       await commandTimeline(flags, commandDeps);
       return;
+    case "train-now":
+      await commandTrainNow(flags, commandDeps);
+      return;
     case "events":
       await commandEvents(flags, commandDeps);
       return;
@@ -686,6 +759,33 @@ async function main() {
     case "power-records":
       await commandPowerRecords(flags, commandDeps);
       return;
+    case "workout-library":
+      await commandWorkoutLibrary(flags, commandDeps);
+      return;
+    case "workout-recommend":
+      await commandWorkoutRecommend(flags, commandDeps);
+      return;
+    case "workout-details":
+      await commandWorkoutDetails(flags, commandDeps);
+      return;
+    case "add-workout":
+      await commandAddWorkout(flags, commandDeps);
+      return;
+    case "copy-workout":
+      await commandCopyWorkout(flags, commandDeps);
+      return;
+    case "workout-alternates":
+      await commandWorkoutAlternates(flags, commandDeps);
+      return;
+    case "move-workout":
+      await commandMoveWorkout(flags, commandDeps);
+      return;
+    case "replace-workout":
+      await commandReplaceWorkout(flags, commandDeps);
+      return;
+    case "switch-workout":
+      await commandSwitchWorkout(flags, commandDeps);
+      return;
     case "logout":
       await commandLogout(flags, commandDeps);
       return;

package/src/commands/auth.mjs

@@ -1,14 +1,15 @@
 export async function commandLogin(flags, deps) {
   const { withClient, readPasswordFromStdin, writeOutput } = deps;
   const client = await withClient(flags);
+  const username = flags.username ?? process.env.TR_USERNAME ?? null;
   const password =
     flags["password-stdin"]
       ? await readPasswordFromStdin()
       : flags.password ?? process.env.TR_PASSWORD ?? null;
   const result = await client.login({
-    username: flags.username ?? process.env.TR_USERNAME ?? null,
+    username,
     password,
-    returnPath: flags["return-path"] ?? "/app/career/quinnsprouse",
+    returnPath: flags["return-path"] ?? (username ? `/app/career/${username}` : "/app/career"),
   });
   await writeOutput(result, { ...flags, json: true });
 }

package/src/commands/discovery.mjs

@@ -12,6 +12,7 @@ export function buildDiscoveryPayload(level = 1, commandFilter = null) {
       name,
       summary: def.summary,
       usage: level >= 2 ? def.usage : undefined,
+      examples: level >= 2 ? def.examples : undefined,
       supportsAgentFilters: FILTERABLE_COMMANDS.has(name),
       agentFilters: level >= 3 && FILTERABLE_COMMANDS.has(name) ? AGENT_FILTER_OPTIONS : undefined,
       agentOutputOptions:
@@ -27,11 +28,11 @@ export function buildDiscoveryPayload(level = 1, commandFilter = null) {
       level3: "Apply --from/--to/--type/--contains/--min-tss/--max-tss/--sort/--result-limit/--fields.",
     },
     firstSteps: [
-      "node src/cli.mjs capabilities --json",
-      "node src/cli.mjs whoami --json",
-      "node src/cli.mjs future --days 30 --json",
-      "node src/cli.mjs today --tz America/New_York --json",
-      "node src/cli.mjs help future --json",
+      "trainerroad-cli capabilities --json",
+      "trainerroad-cli whoami --json",
+      "trainerroad-cli future --days 30 --json",
+      "trainerroad-cli today --tz America/New_York --json",
+      "trainerroad-cli help future --json",
     ],
     commandCount: commandEntries.length,
     commands: commandEntries,
@@ -42,17 +43,17 @@ export function buildDiscoveryPayload(level = 1, commandFilter = null) {
       {
         pattern: "Summarize future workouts in a date window",
         command:
-          "node src/cli.mjs future --from 2026-03-01 --to 2026-03-31 --fields id,title,tss,date --sort date --json",
+          "trainerroad-cli future --from 2026-03-01 --to 2026-03-31 --fields id,title,tss,date --sort date --json",
       },
       {
         pattern: "Find hard completed rides",
         command:
-          "node src/cli.mjs past --days 90 --details --min-tss 80 --sort tss-desc --result-limit 20 --jsonl",
+          "trainerroad-cli past --days 90 --details --min-tss 80 --sort tss-desc --result-limit 20 --jsonl",
       },
       {
         pattern: "Extract only fields for downstream tools",
         command:
-          "node src/cli.mjs today --details --fields recordType,name,started,tss --json",
+          "trainerroad-cli today --details --fields recordType,name,started,tss --json",
       },
     ];
   }

package/src/commands/train-now.mjs

@@ -0,0 +1,142 @@
+function stripHtml(value) {
+  return String(value ?? "")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const CATEGORY_NAME_MAP = {
+  climbing: "Climbing",
+  endurance: "Endurance",
+  attacking: "Attacking",
+};
+
+function normalizeCategoryName(value) {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  return CATEGORY_NAME_MAP[normalized] ?? null;
+}
+
+function summarizeWorkoutInfo(info) {
+  if (!info || typeof info !== "object") return null;
+  return {
+    workoutId: info.id ?? null,
+    workoutName: info.name ?? null,
+    duration: info.duration ?? null,
+    durationMinutes:
+      Number.isFinite(Number(info.durationInSeconds)) ? Math.round(Number(info.durationInSeconds) / 60) : null,
+    tss: info.tss ?? null,
+    intensityFactor: info.intensityFactor ?? null,
+    energyKj: info.kj ?? null,
+    zoneId: info.progressionId ?? null,
+    progressionLevel: info.progressionLevel ?? null,
+    workoutDifficultyRating: info.workoutDifficultyRating ?? null,
+    isOutside: info.isOutside ?? null,
+    profileId: info.profileId ?? null,
+    imageUrl: info.picUrl ?? null,
+  };
+}
+
+function summarizeSuggestion(categoryName, suggestion, workoutInfo) {
+  return {
+    category: categoryName,
+    source: suggestion?.source ?? null,
+    workoutId: suggestion?.workoutId ?? workoutInfo?.workoutId ?? null,
+    ...workoutInfo,
+    predictionMetrics: suggestion?.predictionMetrics ?? {},
+  };
+}
+
+function flattenSuggestions(suggestions, workoutInfoById, categoryFilter = null) {
+  const categories = suggestions && typeof suggestions === "object" ? Object.entries(suggestions) : [];
+  const rows = [];
+  for (const [categoryName, items] of categories) {
+    if (categoryFilter && categoryName !== categoryFilter) continue;
+    for (const item of Array.isArray(items) ? items : []) {
+      rows.push(
+        summarizeSuggestion(
+          categoryName,
+          item,
+          workoutInfoById.get(Number(item?.workoutId)) ?? null,
+        ),
+      );
+    }
+  }
+  return rows;
+}
+
+async function requirePrivateMember(flags, deps) {
+  const { withClient } = deps;
+  const client = await withClient(flags);
+  try {
+    const memberInfo = await client.getMemberInfo();
+    return { client, memberInfo };
+  } catch {
+    throw new Error("train-now requires private authenticated mode. Login first with trainerroad-cli login.");
+  }
+}
+
+export async function commandTrainNow(flags, deps) {
+  const { isJsonMode, requirePositiveInteger, writeOutput } = deps;
+  const { client, memberInfo } = await requirePrivateMember(flags, deps);
+
+  const duration = requirePositiveInteger(flags.duration, 60);
+  const numSuggestions = requirePositiveInteger(flags["num-suggestions"], 10);
+  const categoryFilter = flags.category ? normalizeCategoryName(flags.category) : null;
+  if (flags.category && !categoryFilter) {
+    throw new Error('Invalid --category. Expected one of: climbing, endurance, attacking.');
+  }
+
+  const [status, suggestionsPayload] = await Promise.all([
+    client.getTrainNowStatus(memberInfo.username),
+    client.getTrainNowSuggestions({ duration, numSuggestions }, memberInfo.username),
+  ]);
+
+  const suggestionIds = Array.from(
+    new Set(
+      Object.values(suggestionsPayload?.suggestions ?? {})
+        .flatMap((items) => (Array.isArray(items) ? items : []))
+        .map((item) => Number(item?.workoutId))
+        .filter((value) => Number.isFinite(value)),
+    ),
+  );
+  const workoutInfo = await client.getWorkoutInformation(suggestionIds, memberInfo.username);
+  const workoutInfoById = new Map(
+    (Array.isArray(workoutInfo) ? workoutInfo : [])
+      .map((item) => [Number(item?.id), summarizeWorkoutInfo(item)])
+      .filter(([id]) => Number.isFinite(id)),
+  );
+
+  const records = flattenSuggestions(suggestionsPayload?.suggestions, workoutInfoById, categoryFilter);
+  const payload = {
+    generatedAt: new Date().toISOString(),
+    command: "train-now",
+    member: { memberId: memberInfo.memberId, username: memberInfo.username },
+    query: { duration, numSuggestions, category: categoryFilter },
+    status,
+    recommendedCategory: suggestionsPayload?.recommendedCategory ?? null,
+    hasRpePredictionServiceFailure: Boolean(suggestionsPayload?.hasRpePredictionServiceFailure),
+    count: records.length,
+    records,
+  };
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(payload, flags, (value) => {
+      const lines = [
+        `TrainNow suggestions (${value.count}) duration=${value.query.duration}m`,
+      ];
+      for (const item of value.records) {
+        lines.push(
+          `- [${item.category}] ${item.workoutName ?? "(untitled)"} | workoutId=${item.workoutId} | duration=${item.durationMinutes ?? "?"}m | tss=${item.tss ?? "?"} | level=${item.progressionLevel ?? "?"}`,
+        );
+      }
+      return lines.join("\n");
+    });
+    return;
+  }
+
+  await writeOutput(payload, { ...flags, json: !flags.jsonl });
+}