trainerroad-cli 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.4.0 - 2026-09-02
+
+- Added `add-annotation`, `remove-annotation`, and `annotation-details`: create time off, illness, injury, and note entries (single or multi-day via `--days` or `--end-date`), remove them by id (no-op when already gone), and read the title and notes that the timeline rows omit. Uses `POST/DELETE /app/api/calendar/annotations` and `GET /app/api/react-calendar/annotation/{id}`, confirmed live.
+- Added `add-event`: creates a race or event via `POST /app/api/calendar/plannedactivities/event` with discipline (by name or id), A/B/C priority, duration, and either a TSS or a 1-10 intensity estimate. Confirmed live. Events are removed with `remove-workout`.
+- Added `remove-workout`: deletes a planned workout or event by planned-activity id via `DELETE /app/api/calendar/plannedactivities/{id}` (confirmed live), with `--dry-run` and a no-op when the record is already gone.
+- Fixed swapped annotation type labels: typeId 2 is illness and typeId 4 is time off (checked against the web app's enum and real calendar entries). Plan-marker ids 5 to 10 are now labelled too.
+- Added `workout-image`: saves a workout's power-profile chart as PNG (default, via the optional `@resvg/resvg-js` package) or SVG. Workout records from `workout-library` and `workout-details` now include `chartUrl`.
+- Fixed `power-records`: the web app moved to `POST /app/api/personal-records/{memberId}`; the old `/for-date-range` path stays as a 404 fallback.
+- Key normalisation now runs per object at every depth, because personal-records nests PascalCase rows inside a camelCase envelope.
+- Help output uses per-command flag descriptions, so shared names like `--type` and `--days` read correctly for each command.
+- Write commands report an `adaptiveTraining` note, and the README explains how Adaptive Training reacts to calendar changes and how an agent should read an athlete's situation.
+- Fixed `login`: TrainerRoad replaced the server-rendered login form with a React app, so the token scrape failed. `login` now posts JSON to `/app/api/login/login` the way the web app does, and falls back to the old form flow if that route ever disappears. A bad password now fails with "TrainerRoad rejected the username or password" instead of a redirect error.
+- Fixed `plan` returning 404s: plan-builder endpoints are requested by numeric `memberId` instead of username (the username stays in the referer). The career-summary endpoint had the same problem and now takes a `memberId` too.
+- Made a missing `current-custom-plan` (HTTP 404) non-fatal. The web app no longer calls that endpoint at all, so when it is absent `currentPlan` is derived from `all-user-plans` (the plan whose start/end window contains today) and its matching `plan-phases` rows. `currentPlan.source` reports which path produced it, and `currentPhaseName` names the active phase.
+- Every API request now sends `trainerroad-jsonformat: camel-case` by default, and a PascalCase payload is normalised to camelCase if the header is ever ignored, so a dropped header or a casing change cannot blank the output.
+- Request failures throw `HttpError` with `status`, `statusText`, `path`, and `payload` (message unchanged).
+- Added tests for the JSON login flow and its fallback, memberId-keyed URLs, the format header, PascalCase normalisation, non-fatal 404 handling, and date-window current-plan derivation.
+
+## 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

@@ -26,6 +26,42 @@ It can also perform a small set of verified calendar writes for planned workouts
 - list TrainerRoad alternate workout options
 - replace a workout with a specific alternate
 - switch a workout between inside and outside
+- remove a planned workout or event
+- add a race or event with discipline, priority, and a TSS or intensity estimate
+- add and remove calendar annotations: time off, illness, injury, notes
+- save a workout's power-profile chart as PNG or SVG
+
+## 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.
+- Every write returns `before`/`after` (or the created record) so the caller can verify without a second call.
+
+## How TrainerRoad Reacts To Calendar Changes
+
+TrainerRoad's Adaptive Training treats the calendar as input. Agents managing an athlete's plan should expect:
+
+- Removing or skipping a planned workout can cause TrainerRoad to rebuild the upcoming plan around the gap.
+- Adding a workout, or marking time off, illness, or injury, can likewise shift the surrounding planned workouts.
+- Planned workouts carry `recommendationReason`, `adaptationLocked`, and `adaptationAltered` fields that show whether TrainerRoad chose or altered them.
+- After any write, re-read `future --days 14 --details` before deciding the next step. Do not assume the calendar looks the way it did before the write.
+
+Write commands echo this in an `adaptiveTraining` field so it is visible in machine-readable output.
+
+## Reading The Athlete's Situation
+
+A useful order for an agent building a picture of how training is going:
+
+1. `whoami` for FTP, weight, and timezone.
+2. `plan --view current` for the plan, its phases, and the phase the athlete is in today.
+3. `past --days 28 --details` and `future --days 14 --details` for what happened and what is scheduled.
+4. `levels` for progression levels by zone, and `ftp-prediction` for where FTP is heading.
+5. `annotations --from <date>` for time off, illness, and injury, and `annotation-details --id` for the notes behind them.
+6. `events` for upcoming races.
+7. `workout-image --id <workout-id>` when a picture of a workout's intervals helps explain it.
 
 ## Install
 
@@ -82,6 +118,7 @@ trainerroad-cli workout-library --zone "Endurance" --profile "Sustained Power" -
 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
 ```
 
@@ -97,16 +134,34 @@ 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
+trainerroad-cli remove-workout --id <planned-activity-id> --dry-run
 ```
 
 `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
+4. Events, annotations, and images
+
+```bash
+trainerroad-cli add-event --name "Black Fork" --date 2027-05-01 --discipline gravel --priority A --duration 300 --tss 340 --dry-run
+trainerroad-cli add-event --name "Tuesday crit" --date 2026-10-06 --discipline criterium --priority C --duration 60 --intensity 9 --json
+trainerroad-cli remove-workout --id <planned-activity-id> --json   # events and workouts share this
+trainerroad-cli add-annotation --type time-off --date 2026-09-21 --days 3 --title "Travel" --dry-run
+trainerroad-cli add-annotation --type illness --date 2026-09-21 --end-date 2026-09-23 --notes "Head cold" --json
+trainerroad-cli annotation-details --id <annotation-id> --json
+trainerroad-cli remove-annotation --id <annotation-id> --json
+trainerroad-cli workout-image --id 1592808 --file fishers.png
+trainerroad-cli workout-image --id 1592808 --format svg --file fishers.svg
+```
+
+PNG output uses the optional `@resvg/resvg-js` package. If it is not installed, use `--format svg`.
+
+5. Discover all commands
 
 ```bash
 trainerroad-cli help
@@ -130,6 +185,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.2.0",
+  "version": "0.4.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",
@@ -43,7 +45,11 @@
     "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"
+    "logout": "node src/cli.mjs logout",
+    "workout-image": "node src/cli.mjs workout-image",
+    "add-annotation": "node src/cli.mjs add-annotation",
+    "remove-annotation": "node src/cli.mjs remove-annotation",
+    "annotation-details": "node src/cli.mjs annotation-details"
   },
   "keywords": [
     "trainerroad",
@@ -58,5 +64,8 @@
   "type": "module",
   "dependencies": {
     "playwright": "^1.58.2"
+  },
+  "optionalDependencies": {
+    "@resvg/resvg-js": "^2.6.2"
   }
 }

package/src/cli.mjs

@@ -17,7 +17,10 @@ import {
   AGENT_FILTER_OPTIONS,
   AGENT_OUTPUT_OPTIONS,
   COMMAND_FLAG_ALLOWLIST,
+  COMMAND_REQUIRED_FLAGS,
   COMMANDS,
+  FLAG_DETAILS,
+  COMMAND_FLAG_DETAILS,
   FILTERABLE_COMMANDS,
   GLOBAL_NOTES,
   PROJECT_NOTICE,
@@ -41,7 +44,15 @@ import {
   commandReplaceWorkout,
   commandSwitchWorkout,
   commandWorkoutAlternates,
+  commandRemoveWorkout,
 } from "./commands/workout-mutations.mjs";
+import {
+  commandAddAnnotation,
+  commandAnnotationDetails,
+  commandRemoveAnnotation,
+} from "./commands/annotation-mutations.mjs";
+import { commandWorkoutImage } from "./commands/workout-image.mjs";
+import { commandAddEvent } from "./commands/event-mutations.mjs";
 import { commandFuture, commandPast, commandToday } from "./commands/workouts.mjs";
 import {
   formatDateTimeInTimeZone,
@@ -66,25 +77,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("  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");
+  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) {
@@ -197,6 +210,49 @@ function validateCommandFlags(command, flags) {
   return { unknownFlags, allowlist: Array.from(allowlist) };
 }
 
+function flagDetail(command, name) {
+  return COMMAND_FLAG_DETAILS[command]?.[name] ?? FLAG_DETAILS[name] ?? {};
+}
+
+function formatFlagLabel(command, name) {
+  const detail = flagDetail(command, 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(command, name),
+    description: flagDetail(command, 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) {
@@ -204,11 +260,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 : [],
@@ -225,18 +286,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;
 }
@@ -360,14 +418,14 @@ function getLastItem(values) {
 
 function compactPersonalRecord(record) {
   return {
-    seconds: record?.Seconds ?? null,
-    watts: record?.Watts ?? null,
-    workoutDate: record?.WorkoutDate ?? null,
-    workoutSeconds: record?.WorkoutSeconds ?? null,
-    workoutGuid: record?.WorkoutGuid ?? null,
-    workoutRecordId: record?.WorkoutRecordId ?? null,
-    workoutRecordName: record?.WorkoutRecordName ?? null,
-    surveyResponse: record?.SurveyResponseTranslated ?? null,
+    seconds: record?.seconds ?? record?.Seconds ?? null,
+    watts: record?.watts ?? record?.Watts ?? null,
+    workoutDate: record?.workoutDate ?? record?.WorkoutDate ?? null,
+    workoutSeconds: record?.workoutSeconds ?? record?.WorkoutSeconds ?? null,
+    workoutGuid: record?.workoutGuid ?? record?.WorkoutGuid ?? null,
+    workoutRecordId: record?.workoutRecordId ?? record?.WorkoutRecordId ?? null,
+    workoutRecordName: record?.workoutRecordName ?? record?.WorkoutRecordName ?? null,
+    surveyResponse: record?.surveyResponseTranslated ?? record?.SurveyResponseTranslated ?? null,
   };
 }
 
@@ -643,6 +701,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,
@@ -734,6 +799,24 @@ async function main() {
     case "switch-workout":
       await commandSwitchWorkout(flags, commandDeps);
       return;
+    case "add-event":
+      await commandAddEvent(flags, commandDeps);
+      return;
+    case "remove-workout":
+      await commandRemoveWorkout(flags, commandDeps);
+      return;
+    case "workout-image":
+      await commandWorkoutImage(flags, commandDeps);
+      return;
+    case "annotation-details":
+      await commandAnnotationDetails(flags, commandDeps);
+      return;
+    case "add-annotation":
+      await commandAddAnnotation(flags, commandDeps);
+      return;
+    case "remove-annotation":
+      await commandRemoveAnnotation(flags, commandDeps);
+      return;
     case "logout":
       await commandLogout(flags, commandDeps);
       return;

package/src/commands/annotation-mutations.mjs

@@ -0,0 +1,253 @@
+import {
+  ANNOTATION_TYPE_IDS,
+  ANNOTATION_TYPE_LABELS,
+  compactAnnotationDetail,
+} from "../lib/planning-normalizers.mjs";
+import { shiftDateOnly } from "../lib/timezone.mjs";
+import { isHttpStatus } from "../trainerroad-client.mjs";
+
+const DAY_SECONDS = 86_400;
+
+function dateOnlyDiffDays(fromDateOnly, toDateOnly) {
+  const [fy, fm, fd] = fromDateOnly.split("-").map(Number);
+  const [ty, tm, td] = toDateOnly.split("-").map(Number);
+  return Math.round((Date.UTC(ty, tm - 1, td) - Date.UTC(fy, fm - 1, fd)) / DAY_SECONDS / 1000);
+}
+
+// TrainerRoad's Adaptive Training reacts to calendar changes: time off, illness, and injury
+// entries can prompt it to adjust the surrounding planned workouts. Surface that to agents.
+const ADAPTIVE_NOTE =
+  "TrainerRoad may adapt nearby planned workouts in response to this change. Re-read `future` afterwards.";
+
+function resolveAnnotationType(value) {
+  if (value === undefined || value === null || value === "") return null;
+  const raw = String(value).trim().toLowerCase();
+  if (/^\d+$/.test(raw)) {
+    const typeId = Number(raw);
+    return { typeId, typeLabel: ANNOTATION_TYPE_LABELS[typeId] ?? `type-${typeId}` };
+  }
+  const typeId = ANNOTATION_TYPE_IDS[raw] ?? ANNOTATION_TYPE_IDS[raw.replace(/[\s_]+/g, "-")];
+  if (typeId === undefined) return null;
+  return { typeId, typeLabel: ANNOTATION_TYPE_LABELS[typeId] };
+}
+
+function validTypeNames() {
+  return Object.keys(ANNOTATION_TYPE_IDS).join(", ");
+}
+
+function annotationTitleFor(typeLabel) {
+  return typeLabel
+    .split("-")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+async function requirePrivateMember(flags, deps) {
+  const { withClient } = deps;
+  const client = await withClient(flags);
+  let memberInfo;
+  try {
+    memberInfo = await client.getMemberInfo();
+  } catch {
+    throw new Error(
+      "This command requires private authenticated mode. Login first with trainerroad-cli login.",
+    );
+  }
+  return { client, memberInfo };
+}
+
+async function annotationIdsOnCalendar(client, memberInfo) {
+  const timeline = await client.getTimeline(memberInfo.memberId, memberInfo.username);
+  const rows = Array.isArray(timeline?.annotations) ? timeline.annotations : [];
+  return new Set(rows.map((row) => String(row?.id)).filter((id) => id && id !== "undefined"));
+}
+
+export async function commandAnnotationDetails(flags, deps) {
+  const { isJsonMode, requireFlag, writeOutput } = deps;
+  const annotationId = String(requireFlag("annotation-details", flags, "id"));
+  const { client, memberInfo } = await requirePrivateMember(flags, deps);
+  const raw = await client.getAnnotation(annotationId, memberInfo.username);
+  const annotation = compactAnnotationDetail(raw);
+
+  const payload = {
+    generatedAt: new Date().toISOString(),
+    command: "annotation-details",
+    member: { memberId: memberInfo.memberId, username: memberInfo.username },
+    query: { annotationId },
+    annotation,
+    raw: flags.full ? raw : undefined,
+  };
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(payload, flags, (value) => {
+      const a = value.annotation;
+      return [
+        `${a.typeLabel} ${a.dateOnly}..${a.endDateOnly} (${a.durationDays}d) | id=${a.id}`,
+        `title: ${a.title ?? "(none)"}`,
+        `notes: ${a.text ?? "(none)"}`,
+      ].join("\n");
+    });
+    return;
+  }
+  await writeOutput(payload, { ...flags, json: !flags.jsonl });
+}
+
+export async function commandAddAnnotation(flags, deps) {
+  const { isJsonMode, requireFlag, toBoolean, normalizeDateOnlyInput, requirePositiveInteger, writeOutput } = deps;
+  const dryRun = toBoolean(flags["dry-run"], false);
+  const type = resolveAnnotationType(requireFlag("add-annotation", flags, "type"));
+  if (!type) {
+    throw new Error(`Invalid --type "${flags.type}". Expected one of: ${validTypeNames()}, or a numeric typeId.`);
+  }
+  const date = normalizeDateOnlyInput(requireFlag("add-annotation", flags, "date"), null);
+  if (!date) throw new Error(`Invalid --date "${flags.date}". Expected YYYY-MM-DD.`);
+
+  let durationDays = requirePositiveInteger(flags.days, 1);
+  if (flags["end-date"] !== undefined && flags["end-date"] !== null && flags["end-date"] !== "") {
+    const endDate = normalizeDateOnlyInput(flags["end-date"], null);
+    if (!endDate) throw new Error(`Invalid --end-date "${flags["end-date"]}". Expected YYYY-MM-DD.`);
+    const diff = dateOnlyDiffDays(date, endDate);
+    if (diff === null || diff < 0) {
+      throw new Error(`--end-date ${endDate} is before --date ${date}.`);
+    }
+    durationDays = diff + 1;
+  }
+  const endDateOnly = shiftDateOnly(date, durationDays - 1);
+
+  const title = flags.title !== undefined && flags.title !== null && String(flags.title) !== ""
+    ? String(flags.title)
+    : annotationTitleFor(type.typeLabel);
+  const text = flags.notes !== undefined && flags.notes !== null ? String(flags.notes) : "";
+  const colorId = requirePositiveInteger(flags["color-id"], 2);
+
+  const request = {
+    date,
+    timeOfDay: null,
+    duration: durationDays * DAY_SECONDS,
+    title,
+    text,
+    typeId: type.typeId,
+    colorId,
+  };
+  const preview = {
+    typeId: type.typeId,
+    typeLabel: type.typeLabel,
+    dateOnly: date,
+    endDateOnly,
+    durationDays,
+    title,
+    text,
+    colorId,
+  };
+
+  const { client, memberInfo } = await requirePrivateMember(flags, deps);
+
+  const base = {
+    generatedAt: new Date().toISOString(),
+    command: "add-annotation",
+    member: { memberId: memberInfo.memberId, username: memberInfo.username },
+    query: preview,
+    adaptiveTraining: ADAPTIVE_NOTE,
+  };
+
+  if (dryRun) {
+    const payload = {
+      ...base,
+      dryRun: true,
+      annotation: null,
+      request,
+      message: `Would add ${type.typeLabel} "${title}" on ${date}${durationDays > 1 ? ` through ${endDateOnly}` : ""}.`,
+    };
+    if (!isJsonMode(flags)) {
+      await writeOutput(payload, flags, (value) => `${value.message}\nNo changes made.`);
+      return;
+    }
+    await writeOutput(payload, { ...flags, json: !flags.jsonl });
+    return;
+  }
+
+  const before = await annotationIdsOnCalendar(client, memberInfo);
+  await client.createAnnotation(request, memberInfo.username);
+  const after = await annotationIdsOnCalendar(client, memberInfo);
+  const createdIds = [...after].filter((id) => !before.has(id));
+
+  let annotation = null;
+  for (const id of createdIds) {
+    const detail = compactAnnotationDetail(await client.getAnnotation(id, memberInfo.username));
+    if (detail.typeId === type.typeId && detail.dateOnly === date) {
+      annotation = detail;
+      break;
+    }
+  }
+
+  const payload = {
+    ...base,
+    dryRun: false,
+    annotation,
+    request,
+    message: annotation
+      ? `Added ${annotation.typeLabel} "${annotation.title}" on ${annotation.dateOnly}${annotation.durationDays > 1 ? ` through ${annotation.endDateOnly}` : ""} (id=${annotation.id}).`
+      : "TrainerRoad accepted the annotation but it could not be located on the calendar afterwards. Run `annotations` to inspect.",
+  };
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(payload, flags, (value) => `${value.message}\n${value.adaptiveTraining}`);
+    return;
+  }
+  await writeOutput(payload, { ...flags, json: !flags.jsonl });
+}
+
+export async function commandRemoveAnnotation(flags, deps) {
+  const { isJsonMode, requireFlag, toBoolean, writeOutput } = deps;
+  const dryRun = toBoolean(flags["dry-run"], false);
+  const annotationId = String(requireFlag("remove-annotation", flags, "id"));
+  const { client, memberInfo } = await requirePrivateMember(flags, deps);
+
+  let before = null;
+  try {
+    before = compactAnnotationDetail(await client.getAnnotation(annotationId, memberInfo.username));
+  } catch (error) {
+    if (!isHttpStatus(error, 404)) throw error;
+  }
+  const noop = before === null;
+
+  const base = {
+    generatedAt: new Date().toISOString(),
+    command: "remove-annotation",
+    member: { memberId: memberInfo.memberId, username: memberInfo.username },
+    query: { annotationId },
+    before,
+    adaptiveTraining: ADAPTIVE_NOTE,
+  };
+
+  if (dryRun || noop) {
+    const payload = {
+      ...base,
+      dryRun,
+      noop,
+      message: noop
+        ? `No annotation with id ${annotationId} exists on the calendar.`
+        : `Would remove ${before.typeLabel} "${before.title}" on ${before.dateOnly}.`,
+    };
+    if (!isJsonMode(flags)) {
+      await writeOutput(payload, flags, (value) => (value.noop ? value.message : `${value.message}\nNo changes made.`));
+      return;
+    }
+    await writeOutput(payload, { ...flags, json: !flags.jsonl });
+    return;
+  }
+
+  await client.deleteAnnotation(annotationId, memberInfo.username);
+  const payload = {
+    ...base,
+    dryRun: false,
+    noop: false,
+    message: `Removed ${before.typeLabel} "${before.title}" on ${before.dateOnly} (id=${annotationId}).`,
+  };
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(payload, flags, (value) => `${value.message}\n${value.adaptiveTraining}`);
+    return;
+  }
+  await writeOutput(payload, { ...flags, json: !flags.jsonl });
+}

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 });
 }