trainerroad-cli 0.1.1 → 0.2.0

package/README.md

@@ -14,6 +14,19 @@ 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
+
 ## Install
 
 ### Run without install (npx)
@@ -64,9 +77,36 @@ 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 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
 ```
 
-3. Discover all commands
+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 --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
+```
+
+`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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trainerroad-cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Unofficial CLI for authenticating with TrainerRoad and querying timeline/workout data",
   "main": "src/cli.mjs",
   "bin": {
@@ -21,6 +21,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 +34,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

@@ -31,7 +31,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,
@@ -67,6 +77,14 @@ function printGlobalHelp() {
   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("  node src/cli.mjs move-workout --id <planned-id> --to 2026-03-13 --json");
+  console.log("  node src/cli.mjs workout-alternates --id <planned-id> --category easier --json");
+  console.log('  node src/cli.mjs workout-library --zone "Endurance" --profile "Sustained Power" --min-duration 45 --max-duration 75 --json');
+  console.log('  node src/cli.mjs workout-recommend --zone "Endurance" --profile "Sustained Power" --target-duration 60 --target-level 1.0 --count 3 --json');
+  console.log("  node src/cli.mjs train-now --duration 60 --json");
+  console.log("  node src/cli.mjs workout-details --id 18128 --include-chart --json");
+  console.log("  node src/cli.mjs add-workout --workout-id 18128 --date 2026-03-16 --json");
+  console.log("  node src/cli.mjs copy-workout --id <planned-id> --date 2026-03-16 --json");
 }
 
 function levenshteinDistance(left, right) {
@@ -650,6 +668,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 +707,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/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 });
+}