trainerroad-cli 0.1.0

package/src/lib/agent-filters.mjs

@@ -0,0 +1,287 @@
+function toIsoDate(value) {
+  if (typeof value === "string" && value.length >= 10) return value.slice(0, 10);
+  return new Date(value).toISOString().slice(0, 10);
+}
+
+function toIsoDateFromPlannedRecord(record) {
+  return `${String(record.date.year).padStart(4, "0")}-${String(record.date.month).padStart(2, "0")}-${String(record.date.day).padStart(2, "0")}`;
+}
+
+function normalizeDateOnlyInput(value, fallback) {
+  if (value == null || value === "") return fallback;
+  const normalized = String(value).trim();
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(normalized)) {
+    throw new Error(`Invalid date "${value}". Expected YYYY-MM-DD.`);
+  }
+  return normalized;
+}
+
+function requireNumber(value, fallback) {
+  if (value == null) return fallback;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return parsed;
+}
+
+function requirePositiveInteger(value, fallback) {
+  const parsed = requireNumber(value, fallback);
+  if (!Number.isInteger(parsed) || parsed < 1) return fallback;
+  return parsed;
+}
+
+function splitCsv(value) {
+  if (value == null || value === true) return [];
+  return String(value)
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function toLowerOrNull(value) {
+  if (value == null) return null;
+  return String(value).toLowerCase();
+}
+
+function getByPath(object, pathValue) {
+  if (!pathValue) return undefined;
+  const segments = String(pathValue)
+    .split(".")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  let cursor = object;
+  for (const segment of segments) {
+    if (cursor == null || typeof cursor !== "object") return undefined;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+
+function projectRecordFields(record, fields) {
+  const output = {};
+  for (const field of fields) {
+    const value = getByPath(record, field);
+    output[field] = value === undefined ? null : value;
+  }
+  return output;
+}
+
+function resolveRecordDateOnly(record) {
+  if (!record || typeof record !== "object") return null;
+  if (typeof record.dateOnly === "string") return record.dateOnly;
+  if (record.date && typeof record.date === "object" && Number.isFinite(record.date.year)) {
+    return toIsoDateFromPlannedRecord(record);
+  }
+  if (typeof record.date === "string") return toIsoDate(record.date);
+  if (typeof record.started === "string") return toIsoDate(record.started);
+  if (typeof record.workoutDate === "string") return toIsoDate(record.workoutDate);
+  return null;
+}
+
+function resolveRecordType(record) {
+  if (!record || typeof record !== "object") return null;
+  if (record.recordType != null) return record.recordType;
+  if (record.type != null) return record.type;
+  if (record.activityType != null) return record.activityType;
+  if (record.typeId != null) return record.typeId;
+  if (record.progressionId != null) return record.progressionId;
+  return null;
+}
+
+function resolveRecordTss(record) {
+  if (!record || typeof record !== "object") return null;
+  const candidates = [
+    record.tss,
+    record.actualTss,
+    record.plannedTssTotal,
+    record.estimatedTss,
+    record.Tss,
+  ];
+  for (const candidate of candidates) {
+    const numeric = Number(candidate);
+    if (Number.isFinite(numeric)) return numeric;
+  }
+  return null;
+}
+
+function resolveRecordText(record) {
+  if (!record || typeof record !== "object") return "";
+  const textParts = [
+    record.name,
+    record.title,
+    record.planName,
+    record.zoneLabel,
+    record.zoneKey,
+    record.typeLabel,
+    record.workoutRecordName,
+    record.recordType,
+    record.type,
+  ]
+    .filter((value) => value != null)
+    .map((value) => String(value));
+  return textParts.join(" ").toLowerCase();
+}
+
+function compareNullableNumbers(a, b) {
+  const left = Number.isFinite(a) ? a : null;
+  const right = Number.isFinite(b) ? b : null;
+  if (left == null && right == null) return 0;
+  if (left == null) return 1;
+  if (right == null) return -1;
+  return left - right;
+}
+
+function parseAgentFilterConfig(flags) {
+  const fromDate = flags.from ? normalizeDateOnlyInput(flags.from, null) : null;
+  const toDate = flags.to ? normalizeDateOnlyInput(flags.to, null) : null;
+  const minTss =
+    flags["min-tss"] != null && flags["min-tss"] !== true ? Number(flags["min-tss"]) : null;
+  const maxTss =
+    flags["max-tss"] != null && flags["max-tss"] !== true ? Number(flags["max-tss"]) : null;
+  const sort = toLowerOrNull(flags.sort);
+  const contains = toLowerOrNull(flags.contains);
+  const typeFilters = splitCsv(flags.type).map((value) => value.toLowerCase());
+  const fields = splitCsv(flags.fields);
+  const resultLimit = requirePositiveInteger(flags["result-limit"], null);
+  return {
+    fromDate,
+    toDate,
+    minTss: Number.isFinite(minTss) ? minTss : null,
+    maxTss: Number.isFinite(maxTss) ? maxTss : null,
+    sort,
+    contains,
+    typeFilters,
+    fields,
+    resultLimit,
+  };
+}
+
+export function applyAgentRecordFilters(records, flags) {
+  const config = parseAgentFilterConfig(flags);
+  const input = Array.isArray(records) ? records : [];
+  let output = [...input];
+
+  if (config.fromDate || config.toDate) {
+    output = output.filter((record) => {
+      const dateOnly = resolveRecordDateOnly(record);
+      if (!dateOnly) return false;
+      if (config.fromDate && dateOnly < config.fromDate) return false;
+      if (config.toDate && dateOnly > config.toDate) return false;
+      return true;
+    });
+  }
+
+  if (config.typeFilters.length > 0) {
+    output = output.filter((record) => {
+      const recordTypeRaw = resolveRecordType(record);
+      if (recordTypeRaw == null) return false;
+      const recordType = String(recordTypeRaw).toLowerCase();
+      const numericType = Number(recordTypeRaw);
+      return config.typeFilters.some((candidate) => {
+        if (candidate === recordType) return true;
+        const numericCandidate = Number(candidate);
+        return (
+          Number.isFinite(numericCandidate) &&
+          Number.isFinite(numericType) &&
+          numericCandidate === numericType
+        );
+      });
+    });
+  }
+
+  if (config.contains) {
+    output = output.filter((record) => resolveRecordText(record).includes(config.contains));
+  }
+
+  if (config.minTss != null || config.maxTss != null) {
+    output = output.filter((record) => {
+      const tss = resolveRecordTss(record);
+      if (!Number.isFinite(tss)) return false;
+      if (config.minTss != null && tss < config.minTss) return false;
+      if (config.maxTss != null && tss > config.maxTss) return false;
+      return true;
+    });
+  }
+
+  switch (config.sort) {
+    case "date":
+      output.sort((a, b) => {
+        const left = resolveRecordDateOnly(a) ?? "";
+        const right = resolveRecordDateOnly(b) ?? "";
+        return left.localeCompare(right);
+      });
+      break;
+    case "date-desc":
+      output.sort((a, b) => {
+        const left = resolveRecordDateOnly(a) ?? "";
+        const right = resolveRecordDateOnly(b) ?? "";
+        return right.localeCompare(left);
+      });
+      break;
+    case "tss":
+      output.sort((a, b) => compareNullableNumbers(resolveRecordTss(a), resolveRecordTss(b)));
+      break;
+    case "tss-desc":
+      output.sort((a, b) => compareNullableNumbers(resolveRecordTss(b), resolveRecordTss(a)));
+      break;
+    case "name":
+      output.sort((a, b) => resolveRecordText(a).localeCompare(resolveRecordText(b)));
+      break;
+    case "name-desc":
+      output.sort((a, b) => resolveRecordText(b).localeCompare(resolveRecordText(a)));
+      break;
+    default:
+      break;
+  }
+
+  if (config.resultLimit != null) {
+    output = output.slice(0, config.resultLimit);
+  }
+
+  if (config.fields.length > 0) {
+    output = output.map((record) => projectRecordFields(record, config.fields));
+  }
+
+  const filterSummary = {
+    from: config.fromDate,
+    to: config.toDate,
+    type: config.typeFilters,
+    contains: config.contains,
+    minTss: config.minTss,
+    maxTss: config.maxTss,
+    sort: config.sort,
+    resultLimit: config.resultLimit,
+    fields: config.fields,
+    inputCount: input.length,
+    outputCount: output.length,
+  };
+
+  return { records: output, filterSummary };
+}
+
+export function hasAgentRecordTransforms(flags) {
+  return Boolean(
+    flags.from ||
+      flags.to ||
+      flags.type ||
+      flags.contains ||
+      flags["min-tss"] ||
+      flags["max-tss"] ||
+      flags.sort ||
+      flags["result-limit"] ||
+      flags.fields,
+  );
+}
+
+export function toRecordsOnlyPayload(payload) {
+  return {
+    mode: payload?.mode ?? null,
+    generatedAt: payload?.generatedAt ?? new Date().toISOString(),
+    command: payload?.command ?? null,
+    query: payload?.query ?? null,
+    filters: payload?.filters ?? null,
+    member: payload?.member ?? null,
+    count: Array.isArray(payload?.records) ? payload.records.length : payload?.count ?? 0,
+    records: Array.isArray(payload?.records) ? payload.records : [],
+    limitations: payload?.limitations ?? undefined,
+  };
+}

package/src/lib/command-manifest.mjs

@@ -0,0 +1,328 @@
+export const COMMANDS = {
+  help: {
+    summary: "Show global help or command help.",
+    usage: [
+      "node src/cli.mjs help",
+      "node src/cli.mjs help <command>",
+      "node src/cli.mjs <command> --help",
+    ],
+  },
+  discover: {
+    summary: "Agent-oriented command discovery with progressive disclosure levels.",
+    usage: [
+      "node src/cli.mjs discover",
+      "node src/cli.mjs discover --level 1|2|3 [--json]",
+      "node src/cli.mjs discover --command future --level 3 --json",
+    ],
+  },
+  capabilities: {
+    summary: "Show supported auth/data capabilities (private + public modes).",
+    usage: ["node src/cli.mjs capabilities [--json]"],
+  },
+  login: {
+    summary: "Authenticate and persist cookie session for private data access.",
+    usage: [
+      "node src/cli.mjs login --username <u> --password <p> [--return-path /app/career/<username>]",
+      "node src/cli.mjs login --username <u> --password-stdin",
+    ],
+  },
+  whoami: {
+    summary: "Fetch authenticated member profile info (`/app/api/member-info`).",
+    usage: ["node src/cli.mjs whoami [--json]"],
+  },
+  timeline: {
+    summary: "Get profile summary (private full timeline or public TSS-derived summary).",
+    usage: [
+      "node src/cli.mjs timeline [--target <username>] [--public] [--full] [--json]",
+      "node src/cli.mjs timeline --target quinnsprouse --public --json",
+    ],
+  },
+  events: {
+    summary: "Show calendar events/races from timeline (private mode).",
+    usage: [
+      "node src/cli.mjs events [--full] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--type <value>] [--contains <text>] [--min-tss <n>] [--max-tss <n>] [--sort date|date-desc|name|name-desc|tss|tss-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+  },
+  annotations: {
+    summary: "Show timeline annotations (time off, notes, illness/injury markers) (private mode).",
+    usage: [
+      "node src/cli.mjs annotations [--full] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--type <value>] [--contains <text>] [--sort date|date-desc|name|name-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+  },
+  levels: {
+    summary: "Show progression levels by zone (private mode).",
+    usage: [
+      "node src/cli.mjs levels [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--type <zone|progressionId>] [--contains <text>] [--sort name|name-desc|date|date-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+  },
+  plan: {
+    summary: "Show training plan data (current plan, phases, or all plans) (private mode).",
+    usage: [
+      "node src/cli.mjs plan [--view current|phases|plans] [--full] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--type <value>] [--contains <text>] [--sort date|date-desc|name|name-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+  },
+  "weight-history": {
+    summary: "Show historical body-weight entries (private mode).",
+    usage: [
+      "node src/cli.mjs weight-history [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--contains <text>] [--sort date|date-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+  },
+  today: {
+    summary: "Show today's planned/completed activity for private or public profile mode.",
+    usage: [
+      "node src/cli.mjs today [--date YYYY-MM-DD] [--target <username>] [--public] [--details] [--type <value>] [--contains <text>] [--min-tss <n>] [--max-tss <n>] [--sort date|date-desc|tss|tss-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+  },
+  future: {
+    summary: "Show future plan data for private or public profile mode.",
+    usage: [
+      "node src/cli.mjs future [--days <n>] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--target <username>] [--public] [--details] [--type <value>] [--contains <text>] [--min-tss <n>] [--max-tss <n>] [--sort date|date-desc|tss|tss-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+  },
+  past: {
+    summary: "Show past activity data for private or public profile mode.",
+    usage: [
+      "node src/cli.mjs past [--days <n>] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--limit <n>] [--target <username>] [--public] [--details] [--type <value>] [--contains <text>] [--min-tss <n>] [--max-tss <n>] [--sort date|date-desc|tss|tss-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+  },
+  ftp: {
+    summary: "Show FTP snapshot and FTP history (private or public mode).",
+    usage: [
+      "node src/cli.mjs ftp [--target <username>] [--public] [--history-limit <n>] [--json|--jsonl]",
+    ],
+  },
+  "ftp-prediction": {
+    summary: "Show AI FTP detection eligibility/status and progression impact (private mode).",
+    usage: ["node src/cli.mjs ftp-prediction [--json]"],
+  },
+  "power-ranking": {
+    summary: "Show best-power percentile ranking by duration (private mode).",
+    usage: ["node src/cli.mjs power-ranking [--json|--jsonl]"],
+  },
+  "power-records": {
+    summary: "Show date-range personal power records from TrainerRoad PR endpoint (private mode).",
+    usage: [
+      "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]",
+    ],
+  },
+  logout: {
+    summary: "Clear local persisted session.",
+    usage: ["node src/cli.mjs logout"],
+  },
+};
+
+export const PROJECT_NOTICE = "Unofficial tool. Not affiliated with or endorsed by TrainerRoad.";
+
+export const GLOBAL_NOTES = [
+  PROJECT_NOTICE,
+  "Environment: TR_USERNAME, TR_PASSWORD, TR_SESSION_FILE",
+  "Output modes: default JSON, --json, --jsonl, --output <path>",
+  "Session file default: .trainerroad/session.json",
+  "Private mode: authenticated cookie session + full workout endpoints.",
+  "Public mode: username-based endpoint (`/app/api/tss/{username}`) with limited detail.",
+  "Agent filters: --from --to --type --contains --min-tss --max-tss --sort --result-limit --fields",
+  "Agent output: --records-only",
+];
+
+export const AGENT_FILTER_OPTIONS = [
+  { flag: "--from", type: "YYYY-MM-DD", description: "Inclusive lower date bound." },
+  { flag: "--to", type: "YYYY-MM-DD", description: "Inclusive upper date bound." },
+  { flag: "--type", type: "csv", description: "Record type filter (e.g. 1,planned,completed)." },
+  { flag: "--contains", type: "string", description: "Case-insensitive text match against title/name." },
+  { flag: "--min-tss", type: "number", description: "Minimum TSS threshold." },
+  { flag: "--max-tss", type: "number", description: "Maximum TSS threshold." },
+  { flag: "--sort", type: "enum", description: "date|date-desc|tss|tss-desc|name|name-desc" },
+  { flag: "--result-limit", type: "number", description: "Post-filter record cap." },
+  { flag: "--fields", type: "csv", description: "Project records to selected field paths." },
+];
+
+export const AGENT_OUTPUT_OPTIONS = [
+  {
+    flag: "--records-only",
+    type: "boolean",
+    description: "Return only envelope + records (drops heavy side payload fields).",
+  },
+];
+
+export const FILTERABLE_COMMANDS = new Set([
+  "today",
+  "future",
+  "past",
+  "events",
+  "annotations",
+  "levels",
+  "plan",
+  "weight-history",
+]);
+
+function trimFlagPrefix(flag) {
+  return String(flag ?? "").replace(/^--/, "").trim();
+}
+
+function mergeFlagGroups(...groups) {
+  return new Set(
+    groups
+      .flat()
+      .map((flag) => trimFlagPrefix(flag))
+      .filter(Boolean),
+  );
+}
+
+const SHARED_FLAGS = {
+  help: ["help"],
+  output: ["output"],
+  session: ["session-file"],
+  credentials: ["username", "password"],
+  publicProfile: ["target", "public"],
+  json: ["json"],
+  jsonAndJsonl: ["json", "jsonl"],
+  agentFilters: AGENT_FILTER_OPTIONS.map((option) => trimFlagPrefix(option.flag)),
+  agentOutput: AGENT_OUTPUT_OPTIONS.map((option) => trimFlagPrefix(option.flag)),
+};
+
+export const COMMAND_FLAG_ALLOWLIST = {
+  help: mergeFlagGroups(SHARED_FLAGS.help, SHARED_FLAGS.json),
+  discover: mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.json,
+    ["level", "command"],
+  ),
+  capabilities: mergeFlagGroups(SHARED_FLAGS.help, SHARED_FLAGS.output, SHARED_FLAGS.json),
+  login: mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    ["password-stdin", "return-path"],
+  ),
+  whoami: mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.json,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+  ),
+  timeline: mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.json,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    SHARED_FLAGS.publicProfile,
+    ["full"],
+  ),
+  events: mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    SHARED_FLAGS.agentFilters,
+    SHARED_FLAGS.agentOutput,
+    ["full"],
+  ),
+  annotations: mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    SHARED_FLAGS.agentFilters,
+    SHARED_FLAGS.agentOutput,
+    ["full"],
+  ),
+  levels: mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    SHARED_FLAGS.agentFilters,
+    SHARED_FLAGS.agentOutput,
+  ),
+  plan: mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    SHARED_FLAGS.agentFilters,
+    SHARED_FLAGS.agentOutput,
+    ["view", "full"],
+  ),
+  "weight-history": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    SHARED_FLAGS.agentFilters,
+    SHARED_FLAGS.agentOutput,
+  ),
+  today: mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    SHARED_FLAGS.publicProfile,
+    SHARED_FLAGS.agentFilters,
+    SHARED_FLAGS.agentOutput,
+    ["date", "details"],
+  ),
+  future: mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    SHARED_FLAGS.publicProfile,
+    SHARED_FLAGS.agentFilters,
+    SHARED_FLAGS.agentOutput,
+    ["days", "from", "to", "details"],
+  ),
+  past: mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    SHARED_FLAGS.publicProfile,
+    SHARED_FLAGS.agentFilters,
+    SHARED_FLAGS.agentOutput,
+    ["days", "limit", "from", "to", "details"],
+  ),
+  ftp: mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    SHARED_FLAGS.publicProfile,
+    ["history-limit"],
+  ),
+  "ftp-prediction": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.json,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+  ),
+  "power-ranking": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+  ),
+  "power-records": mergeFlagGroups(
+    SHARED_FLAGS.help,
+    SHARED_FLAGS.output,
+    SHARED_FLAGS.jsonAndJsonl,
+    SHARED_FLAGS.session,
+    SHARED_FLAGS.credentials,
+    ["start-date", "end-date", "row-type", "indoor-only", "slot", "limit", "full"],
+  ),
+  logout: mergeFlagGroups(SHARED_FLAGS.help, SHARED_FLAGS.output, SHARED_FLAGS.session),
+};