trainerroad-cli 0.1.0 → 0.2.0

package/src/lib/command-manifest.mjs

@@ -37,6 +37,12 @@ export const COMMANDS = {
       "node src/cli.mjs timeline --target quinnsprouse --public --json",
     ],
   },
+  "train-now": {
+    summary: "Fetch TrainerRoad AI suggested workouts (TrainNow) for a target duration (private mode).",
+    usage: [
+      "node src/cli.mjs train-now [--duration <minutes>] [--num-suggestions <n>] [--category climbing|endurance|attacking] [--json|--jsonl]",
+    ],
+  },
   events: {
     summary: "Show calendar events/races from timeline (private mode).",
     usage: [
@@ -105,6 +111,60 @@ export const COMMANDS = {
       "node src/cli.mjs power-records [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--row-type 100|101] [--indoor-only true|false] [--limit <n>] [--full] [--json|--jsonl]",
     ],
   },
+  "workout-library": {
+    summary: "Search the TrainerRoad workout library with agent-friendly filters (private mode).",
+    usage: [
+      'node src/cli.mjs workout-library [--search <text>] [--zone <name>|--zone-id <id>] [--profile <name>|--profile-id <id>] [--outside true|false] [--has-instructions true|false] [--min-duration <minutes>] [--max-duration <minutes>] [--min-tss <n>] [--max-tss <n>] [--min-level <n>] [--max-level <n>] [--sort level|level-desc|duration|duration-desc|tss|tss-desc|name|name-desc] [--limit <n>] [--page-size <n>] [--json|--jsonl]',
+    ],
+  },
+  "workout-recommend": {
+    summary: "Recommend library workouts by ranking candidates against target duration/level/TSS (private mode).",
+    usage: [
+      'node src/cli.mjs workout-recommend [--search <text>] [--zone <name>|--zone-id <id>] [--profile <name>|--profile-id <id>] [--outside true|false] [--has-instructions true|false] [--min-duration <minutes>] [--max-duration <minutes>] [--min-tss <n>] [--max-tss <n>] [--min-level <n>] [--max-level <n>] [--target-duration <minutes>] [--target-tss <n>] [--target-level <n>] [--count <n>] [--candidate-limit <n>] [--page-size <n>] [--sort level|level-desc|duration|duration-desc|tss|tss-desc|name|name-desc] [--json|--jsonl]',
+    ],
+  },
+  "workout-details": {
+    summary: "Fetch detailed workout-library metadata for a workout ID (private mode).",
+    usage: [
+      "node src/cli.mjs workout-details --id <workout-id> [--include-chart true|false] [--chart-point-limit <n>] [--json|--jsonl]",
+    ],
+  },
+  "add-workout": {
+    summary: "Add a library workout to the calendar on a target date (private mode; reconciles flaky API responses).",
+    usage: [
+      "node src/cli.mjs add-workout --workout-id <workout-id> --date YYYY-MM-DD [--outside true|false] [--json|--jsonl]",
+    ],
+  },
+  "copy-workout": {
+    summary: "Copy an existing planned workout to another date (private mode).",
+    usage: [
+      "node src/cli.mjs copy-workout --id <planned-activity-id> --date YYYY-MM-DD [--json|--jsonl]",
+    ],
+  },
+  "workout-alternates": {
+    summary: "List alternate workout options for a planned workout (private mode).",
+    usage: [
+      "node src/cli.mjs workout-alternates --id <planned-activity-id> [--category similar|easier|harder|longer|shorter] [--json|--jsonl]",
+    ],
+  },
+  "move-workout": {
+    summary: "Move a planned workout to a different date (private mode).",
+    usage: [
+      "node src/cli.mjs move-workout --id <planned-activity-id> --to YYYY-MM-DD [--json|--jsonl]",
+    ],
+  },
+  "replace-workout": {
+    summary: "Replace a planned workout with a specific alternate workout ID (private mode).",
+    usage: [
+      "node src/cli.mjs replace-workout --id <planned-activity-id> --alternate-id <workout-id> [--update-duration true|false] [--json|--jsonl]",
+    ],
+  },
+  "switch-workout": {
+    summary: "Switch a planned workout between inside and outside variants (private mode).",
+    usage: [
+      "node src/cli.mjs switch-workout --id <planned-activity-id> --mode inside|outside [--json|--jsonl]",
+    ],
+  },
   logout: {
     summary: "Clear local persisted session.",
     usage: ["node src/cli.mjs logout"],
@@ -115,7 +175,8 @@ export const PROJECT_NOTICE = "Unofficial tool. Not affiliated with or endorsed
 
 export const GLOBAL_NOTES = [
   PROJECT_NOTICE,
-  "Environment: TR_USERNAME, TR_PASSWORD, TR_SESSION_FILE",
+  "Environment: TR_USERNAME, TR_PASSWORD, TR_SESSION_FILE, TR_TIMEZONE",
+  "Timezone: --tz <IANA timezone> (for example America/New_York).",
   "Output modes: default JSON, --json, --jsonl, --output <path>",
   "Session file default: .trainerroad/session.json",
   "Private mode: authenticated cookie session + full workout endpoints.",
@@ -161,8 +222,7 @@ function trimFlagPrefix(flag) {
 
 function mergeFlagGroups(...groups) {
   return new Set(
-    groups
-      .flat()
+    [...groups.flat(), "tz"]
       .map((flag) => trimFlagPrefix(flag))
       .filter(Boolean),
   );
@@ -212,6 +272,14 @@ export const COMMAND_FLAG_ALLOWLIST = {
     SHARED_FLAGS.publicProfile,
     ["full"],
   ),
+  "train-now": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    ["duration", "num-suggestions", "category"],
+  ),
   events: mergeFlagGroups(
     SHARED_FLAGS.help,
     SHARED_FLAGS.output,
@@ -324,5 +392,115 @@ export const COMMAND_FLAG_ALLOWLIST = {
     SHARED_FLAGS.credentials,
     ["start-date", "end-date", "row-type", "indoor-only", "slot", "limit", "full"],
   ),
+  "workout-library": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    [
+      "search",
+      "zone",
+      "zone-id",
+      "profile",
+      "profile-id",
+      "outside",
+      "has-instructions",
+      "min-duration",
+      "max-duration",
+      "min-tss",
+      "max-tss",
+      "min-level",
+      "max-level",
+      "sort",
+      "limit",
+      "page-size",
+    ],
+  ),
+  "workout-recommend": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    [
+      "search",
+      "zone",
+      "zone-id",
+      "profile",
+      "profile-id",
+      "outside",
+      "has-instructions",
+      "min-duration",
+      "max-duration",
+      "min-tss",
+      "max-tss",
+      "min-level",
+      "max-level",
+      "target-duration",
+      "target-tss",
+      "target-level",
+      "count",
+      "candidate-limit",
+      "page-size",
+      "sort",
+    ],
+  ),
+  "workout-details": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    ["id", "include-chart", "chart-point-limit"],
+  ),
+  "add-workout": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    ["workout-id", "date", "outside"],
+  ),
+  "copy-workout": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    ["id", "date"],
+  ),
+  "workout-alternates": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    ["id", "category"],
+  ),
+  "move-workout": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    ["id", "to"],
+  ),
+  "replace-workout": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    ["id", "alternate-id", "update-duration"],
+  ),
+  "switch-workout": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    ["id", "mode"],
+  ),
   logout: mergeFlagGroups(SHARED_FLAGS.help, SHARED_FLAGS.output, SHARED_FLAGS.session),
 };

package/src/lib/planning-normalizers.mjs

@@ -1,3 +1,5 @@
+import { normalizeTimeZone, toDateOnlyInTimeZone } from "./timezone.mjs";
+
 const PROGRESSION_ZONE_META = {
   33: { zoneKey: "endurance", zoneLabel: "Endurance", sortOrder: 1 },
   16: { zoneKey: "tempo", zoneLabel: "Tempo", sortOrder: 2 },
@@ -20,8 +22,13 @@ function toIsoDateFromPlanned(item) {
 }
 
 export function toIsoDate(value) {
-  if (typeof value === "string" && value.length >= 10) return value.slice(0, 10);
-  return new Date(value).toISOString().slice(0, 10);
+  if (typeof value === "string" && value.length >= 10 && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+    return value.slice(0, 10);
+  }
+  return (
+    toDateOnlyInTimeZone(value, normalizeTimeZone(), { assumeUtcForOffsetlessDateTime: true }) ??
+    new Date(value).toISOString().slice(0, 10)
+  );
 }
 
 function toIsoDateFromCalendarDate(dateValue) {

package/src/lib/timezone.mjs

@@ -0,0 +1,187 @@
+const DATE_ONLY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_TIME_WITH_OFFSET_PATTERN = /(Z|[+\-]\d{2}:\d{2})$/i;
+
+function isFiniteDate(date) {
+  return date instanceof Date && Number.isFinite(date.getTime());
+}
+
+function pickPart(parts, type) {
+  const found = parts.find((part) => part.type === type);
+  return found ? found.value : null;
+}
+
+function toDateTimeParts(date, timeZone) {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+    timeZoneName: "shortOffset",
+  });
+  return formatter.formatToParts(date);
+}
+
+function toDateOnlyParts(date, timeZone) {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  });
+  return formatter.formatToParts(date);
+}
+
+export function normalizeTimeZone(value = null, fallback = null) {
+  const fromArg = typeof value === "string" ? value.trim() : "";
+  const fromEnv = typeof process.env.TR_TIMEZONE === "string" ? process.env.TR_TIMEZONE.trim() : "";
+  const fromIntl = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const candidate = fromArg || fromEnv || fallback || fromIntl || "UTC";
+
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: candidate });
+    return candidate;
+  } catch {
+    throw new Error(`Invalid timezone "${candidate}". Use an IANA timezone like "America/New_York".`);
+  }
+}
+
+export function parseApiDateTime(value, { assumeUtcForOffsetlessDateTime = true } = {}) {
+  if (value == null) return null;
+
+  if (value instanceof Date) {
+    return isFiniteDate(value) ? new Date(value.getTime()) : null;
+  }
+
+  if (typeof value === "number") {
+    const parsed = new Date(value);
+    return isFiniteDate(parsed) ? parsed : null;
+  }
+
+  if (typeof value !== "string") return null;
+  const raw = value.trim();
+  if (!raw) return null;
+
+  if (DATE_ONLY_PATTERN.test(raw)) {
+    const parsedDateOnly = new Date(`${raw}T00:00:00Z`);
+    return isFiniteDate(parsedDateOnly) ? parsedDateOnly : null;
+  }
+
+  let normalized = raw;
+  if (
+    assumeUtcForOffsetlessDateTime &&
+    /^\d{4}-\d{2}-\d{2}T/.test(raw) &&
+    !DATE_TIME_WITH_OFFSET_PATTERN.test(raw)
+  ) {
+    normalized = `${raw}Z`;
+  }
+
+  const parsed = new Date(normalized);
+  return isFiniteDate(parsed) ? parsed : null;
+}
+
+export function toDateOnlyInTimeZone(
+  value,
+  timeZone,
+  { assumeUtcForOffsetlessDateTime = true } = {},
+) {
+  if (typeof value === "string" && DATE_ONLY_PATTERN.test(value.trim())) {
+    return value.trim();
+  }
+
+  const parsed = parseApiDateTime(value, { assumeUtcForOffsetlessDateTime });
+  if (!parsed) return null;
+
+  const parts = toDateOnlyParts(parsed, normalizeTimeZone(timeZone));
+  const year = pickPart(parts, "year");
+  const month = pickPart(parts, "month");
+  const day = pickPart(parts, "day");
+  if (!year || !month || !day) return null;
+  return `${year}-${month}-${day}`;
+}
+
+export function formatDateTimeInTimeZone(
+  value,
+  timeZone,
+  { assumeUtcForOffsetlessDateTime = true } = {},
+) {
+  const parsed = parseApiDateTime(value, { assumeUtcForOffsetlessDateTime });
+  if (!parsed) return null;
+
+  const parts = toDateTimeParts(parsed, normalizeTimeZone(timeZone));
+  const year = pickPart(parts, "year");
+  const month = pickPart(parts, "month");
+  const day = pickPart(parts, "day");
+  const hour = pickPart(parts, "hour");
+  const minute = pickPart(parts, "minute");
+  const second = pickPart(parts, "second");
+  const timeZoneName = pickPart(parts, "timeZoneName");
+  if (!year || !month || !day || !hour || !minute || !second) return null;
+
+  const suffix = timeZoneName ? ` ${timeZoneName}` : "";
+  return `${year}-${month}-${day}T${hour}:${minute}:${second}${suffix}`;
+}
+
+export function shiftDateOnly(dateOnly, days) {
+  const parsed = parseApiDateTime(dateOnly, { assumeUtcForOffsetlessDateTime: false });
+  if (!parsed) return null;
+  parsed.setUTCDate(parsed.getUTCDate() + Number(days));
+  return parsed.toISOString().slice(0, 10);
+}
+
+export function dateOnlyNowInTimeZone(timeZone) {
+  return toDateOnlyInTimeZone(new Date(), normalizeTimeZone(timeZone), {
+    assumeUtcForOffsetlessDateTime: false,
+  });
+}
+
+export function isoDateShiftInTimeZone(days, timeZone) {
+  const today = dateOnlyNowInTimeZone(timeZone);
+  return shiftDateOnly(today, days);
+}
+
+export function summarizeActivityTimeWindow(
+  started,
+  durationInSeconds,
+  timeZone,
+  { assumeUtcForOffsetlessDateTime = true } = {},
+) {
+  const startDate = parseApiDateTime(started, { assumeUtcForOffsetlessDateTime });
+  if (!startDate) return null;
+
+  const duration =
+    durationInSeconds != null && Number.isFinite(Number(durationInSeconds))
+      ? Number(durationInSeconds)
+      : null;
+  const endDate = duration != null ? new Date(startDate.getTime() + duration * 1000) : null;
+  const normalizedTimeZone = normalizeTimeZone(timeZone);
+
+  const startedDateOnly = toDateOnlyInTimeZone(startDate, normalizedTimeZone, {
+    assumeUtcForOffsetlessDateTime: false,
+  });
+  const endedDateOnly = endDate
+    ? toDateOnlyInTimeZone(endDate, normalizedTimeZone, {
+      assumeUtcForOffsetlessDateTime: false,
+    })
+    : null;
+
+  return {
+    startedAtUtc: startDate.toISOString(),
+    startedAtLocal: formatDateTimeInTimeZone(startDate, normalizedTimeZone, {
+      assumeUtcForOffsetlessDateTime: false,
+    }),
+    endedAtUtc: endDate ? endDate.toISOString() : null,
+    endedAtLocal: endDate
+      ? formatDateTimeInTimeZone(endDate, normalizedTimeZone, {
+        assumeUtcForOffsetlessDateTime: false,
+      })
+      : null,
+    localDate: startedDateOnly,
+    endLocalDate: endedDateOnly,
+    crossesMidnightLocal:
+      Boolean(startedDateOnly) && Boolean(endedDateOnly) && startedDateOnly !== endedDateOnly,
+  };
+}