trainerroad-cli 0.1.0

package/src/commands/annotations.mjs

@@ -0,0 +1,53 @@
+import { compactAnnotationRecord } from "../lib/planning-normalizers.mjs";
+
+export async function commandAnnotations(flags, deps) {
+  const {
+    resolveQueryContext,
+    requirePrivateContext,
+    applyAgentRecordFilters,
+    toRecordsOnlyPayload,
+    isJsonMode,
+    writeOutput,
+    hasAgentRecordTransforms,
+  } = deps;
+
+  const context = await resolveQueryContext(flags);
+  requirePrivateContext(context, "annotations");
+
+  const fullRecords = Array.isArray(context.timeline?.annotations)
+    ? context.timeline.annotations
+    : [];
+  const baseRecords = flags.full ? fullRecords : fullRecords.map((record) => compactAnnotationRecord(record));
+  const { records: filteredRecords, filterSummary } = applyAgentRecordFilters(baseRecords, flags);
+
+  const payload = {
+    mode: "private",
+    generatedAt: new Date().toISOString(),
+    command: "annotations",
+    query: { full: Boolean(flags.full) },
+    filters: filterSummary,
+    member: { memberId: context.memberInfo.memberId, username: context.memberInfo.username },
+    count: filteredRecords.length,
+    records: filteredRecords,
+  };
+  const outputPayload = flags["records-only"] ? toRecordsOnlyPayload(payload) : payload;
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(outputPayload, flags, (value) => {
+      const lines = [`Annotations (${value.count})`];
+      if (hasAgentRecordTransforms(flags) || flags["records-only"] || flags.full) {
+        for (const item of value.records) lines.push(`- ${JSON.stringify(item)}`);
+        if (value.filters) lines.push(`Filter output: ${value.filters.outputCount}/${value.filters.inputCount}`);
+        return lines.join("\n");
+      }
+      for (const annotation of value.records) {
+        lines.push(
+          `- ${annotation.dateOnly ?? "(unknown-date)"} type=${annotation.typeLabel ?? annotation.typeId} durationDays=${annotation.durationDays ?? "n/a"}`,
+        );
+      }
+      return lines.join("\n");
+    });
+    return;
+  }
+  await writeOutput(outputPayload, { ...flags, json: !flags.jsonl });
+}

package/src/commands/auth.mjs

@@ -0,0 +1,28 @@
+export async function commandLogin(flags, deps) {
+  const { withClient, readPasswordFromStdin, writeOutput } = deps;
+  const client = await withClient(flags);
+  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,
+    password,
+    returnPath: flags["return-path"] ?? "/app/career/quinnsprouse",
+  });
+  await writeOutput(result, { ...flags, json: true });
+}
+
+export async function commandWhoAmI(flags, deps) {
+  const { withClient, writeOutput } = deps;
+  const client = await withClient(flags);
+  const info = await client.getMemberInfo();
+  await writeOutput(info, { ...flags, json: true });
+}
+
+export async function commandLogout(flags, deps) {
+  const { withClient, writeOutput } = deps;
+  const client = await withClient(flags);
+  await client.clearSession();
+  await writeOutput({ ok: true, message: "Session cleared." }, { ...flags, json: true });
+}

package/src/commands/discovery.mjs

@@ -0,0 +1,165 @@
+import {
+  AGENT_FILTER_OPTIONS,
+  AGENT_OUTPUT_OPTIONS,
+  COMMANDS,
+  FILTERABLE_COMMANDS,
+} from "../lib/command-manifest.mjs";
+
+export function buildDiscoveryPayload(level = 1, commandFilter = null) {
+  const commandEntries = Object.entries(COMMANDS)
+    .filter(([name]) => !commandFilter || name === commandFilter)
+    .map(([name, def]) => ({
+      name,
+      summary: def.summary,
+      usage: level >= 2 ? def.usage : undefined,
+      supportsAgentFilters: FILTERABLE_COMMANDS.has(name),
+      agentFilters: level >= 3 && FILTERABLE_COMMANDS.has(name) ? AGENT_FILTER_OPTIONS : undefined,
+      agentOutputOptions:
+        level >= 3 && FILTERABLE_COMMANDS.has(name) ? AGENT_OUTPUT_OPTIONS : undefined,
+    }));
+
+  const payload = {
+    generatedAt: new Date().toISOString(),
+    progressiveDisclosureLevel: level,
+    discoveryFlow: {
+      level1: "Find command families and choose auth mode.",
+      level2: "Pick command and run with --json for machine output.",
+      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 help future --json",
+    ],
+    commandCount: commandEntries.length,
+    commands: commandEntries,
+  };
+
+  if (level >= 3) {
+    payload.agentPatterns = [
+      {
+        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",
+      },
+      {
+        pattern: "Find hard completed rides",
+        command:
+          "node src/cli.mjs 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",
+      },
+    ];
+  }
+
+  return payload;
+}
+
+export async function commandDiscover(flags, deps) {
+  const { requirePositiveInteger, isJsonMode, writeOutput } = deps;
+  const level = requirePositiveInteger(flags.level, 1);
+  const boundedLevel = Math.min(Math.max(level, 1), 3);
+  const commandFilter = flags.command ? String(flags.command).trim() : null;
+  if (commandFilter && !COMMANDS[commandFilter]) {
+    throw new Error(`Unknown command for --command: ${commandFilter}`);
+  }
+
+  const payload = buildDiscoveryPayload(boundedLevel, commandFilter);
+  if (!isJsonMode(flags)) {
+    await writeOutput(payload, flags, (value) => {
+      const lines = [
+        `Discovery level: ${value.progressiveDisclosureLevel}`,
+        "Flow:",
+        `- L1: ${value.discoveryFlow.level1}`,
+        `- L2: ${value.discoveryFlow.level2}`,
+        `- L3: ${value.discoveryFlow.level3}`,
+        `Commands returned: ${value.commandCount}`,
+      ];
+      for (const command of value.commands) {
+        lines.push(`- ${command.name}: ${command.summary}`);
+      }
+      lines.push("Tip: add --json for structured discovery payload.");
+      return lines.join("\n");
+    });
+    return;
+  }
+  await writeOutput(payload, { ...flags, json: !flags.jsonl });
+}
+
+export async function commandCapabilities(flags, deps) {
+  const { writeOutput } = deps;
+  const payload = {
+    generatedAt: new Date().toISOString(),
+    authModes: {
+      private: {
+        method: "cookie-session + anti-forgery form post",
+        browserRequired: false,
+        flow: [
+          "GET /app/login?ReturnUrl=...",
+          "parse __RequestVerificationToken + ReturnUrl",
+          "POST /app/login (x-www-form-urlencoded)",
+          "store SharedTrainerRoadAuth cookie",
+        ],
+      },
+      public: {
+        method: "username-based unauthenticated endpoint access",
+        browserRequired: false,
+        endpoint: "GET /app/api/tss/{username}",
+        limitations: [
+          "No detailed workout names/durations from public endpoint",
+          "No private react-calendar detail endpoints without auth",
+        ],
+      },
+    },
+    endpointCoverage: {
+      privateFull: [
+        "GET /app/api/member-info",
+        "GET /app/api/react-calendar/{memberId}/timeline",
+        "GET /app/api/react-calendar/{memberId}/activities (ids header)",
+        "GET /app/api/react-calendar/{memberId}/planned-activities (ids header)",
+        "GET /app/api/react-calendar/{memberId}/personal-records (ids header)",
+        "GET /app/api/career/{memberId}/levels",
+        "GET /app/api/career/{username}/new",
+        "GET /app/api/weight-history/{memberId}/all",
+        "GET /app/api/plan-builder/current-custom-plan/{username}",
+        "GET /app/api/plan-builder/{username}/all-user-plans",
+        "GET /app/api/plan-builder/{username}/plan-phases",
+        "GET /app/api/ai-ftp-detection/can-use-ai-ftp/{memberId}",
+        "GET /app/api/calendar/aiftp/{memberId}/ai-failure-status",
+        "GET /app/api/seasons/{memberId}",
+        "GET /app/api/onboarding/power-ranking?memberId={memberId}",
+        "GET /app/api/onboarding/personal-records?startTime=...&endTime=...",
+        "POST /app/api/personal-records/for-date-range/{memberId}?rowType=...&indoorOnly=...",
+      ],
+      publicLimited: [
+        "GET /app/api/tss/{username} (day-level TSS + FTP history)",
+      ],
+    },
+    commands: Object.keys(COMMANDS),
+    agentFeatures: {
+      progressiveDisclosure: [
+        "discover --level 1",
+        "discover --level 2",
+        "discover --level 3 --json",
+        "help <command> --json",
+      ],
+      filterableCommands: Array.from(FILTERABLE_COMMANDS),
+      filterOptions: AGENT_FILTER_OPTIONS,
+      outputOptions: AGENT_OUTPUT_OPTIONS,
+    },
+    outputModes: ["text", "json", "jsonl"],
+  };
+
+  await writeOutput(payload, flags, () => {
+    return [
+      "Capabilities:",
+      "- Private mode (authenticated): full timeline + workout details.",
+      "- Public mode (unauthenticated): day-level TSS/ride/planned signals + FTP history.",
+      "- Commands support both via automatic mode selection and --target/--public flags.",
+    ].join("\n");
+  });
+}

package/src/commands/events.mjs

@@ -0,0 +1,52 @@
+import { compactEventRecord } from "../lib/planning-normalizers.mjs";
+
+export async function commandEvents(flags, deps) {
+  const {
+    resolveQueryContext,
+    requirePrivateContext,
+    applyAgentRecordFilters,
+    toRecordsOnlyPayload,
+    isJsonMode,
+    writeOutput,
+    hasAgentRecordTransforms,
+  } = deps;
+
+  const context = await resolveQueryContext(flags);
+  requirePrivateContext(context, "events");
+
+  const fullRecords = Array.isArray(context.timeline?.events) ? context.timeline.events : [];
+  const baseRecords = flags.full ? fullRecords : fullRecords.map((record) => compactEventRecord(record));
+  const { records: filteredRecords, filterSummary } = applyAgentRecordFilters(baseRecords, flags);
+
+  const payload = {
+    mode: "private",
+    generatedAt: new Date().toISOString(),
+    command: "events",
+    query: { full: Boolean(flags.full) },
+    filters: filterSummary,
+    member: { memberId: context.memberInfo.memberId, username: context.memberInfo.username },
+    count: filteredRecords.length,
+    records: filteredRecords,
+  };
+  const outputPayload = flags["records-only"] ? toRecordsOnlyPayload(payload) : payload;
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(outputPayload, flags, (value) => {
+      const lines = [`Events (${value.count})`];
+      if (hasAgentRecordTransforms(flags) || flags["records-only"] || flags.full) {
+        for (const item of value.records) lines.push(`- ${JSON.stringify(item)}`);
+        if (value.filters) lines.push(`Filter output: ${value.filters.outputCount}/${value.filters.inputCount}`);
+        return lines.join("\n");
+      }
+      for (const event of value.records) {
+        const when = event.dateOnly ?? event.started ?? "(unknown-date)";
+        lines.push(
+          `- ${when} ${event.name ?? "(unnamed-event)"} | priority=${event.racePriority ?? "n/a"} | tss=${event.tss ?? "n/a"}`,
+        );
+      }
+      return lines.join("\n");
+    });
+    return;
+  }
+  await writeOutput(outputPayload, { ...flags, json: !flags.jsonl });
+}

package/src/commands/ftp.mjs

@@ -0,0 +1,210 @@
+export async function commandFtp(flags, deps) {
+  const {
+    requirePositiveInteger,
+    resolveQueryContext,
+    normalizeFtpHistory,
+    getLastItem,
+    isJsonMode,
+    writeOutput,
+  } = deps;
+
+  const historyLimit = requirePositiveInteger(flags["history-limit"], 50);
+  const context = await resolveQueryContext(flags);
+  let historySource = context.publicTss ?? null;
+
+  if (context.mode === "private") {
+    try {
+      historySource = await context.client.getPublicTssByUsername(context.memberInfo.username);
+    } catch {
+      historySource = null;
+    }
+  }
+
+  const fullHistory = normalizeFtpHistory(
+    historySource?.ftpRecordsDate ?? historySource?.FtpRecordsDate ?? [],
+  );
+  const records = historyLimit > 0 ? fullHistory.slice(-historyLimit) : fullHistory;
+  const latest = getLastItem(fullHistory);
+
+  if (context.mode === "private") {
+    const payload = {
+      mode: "private",
+      generatedAt: new Date().toISOString(),
+      command: "ftp",
+      member: { memberId: context.memberInfo.memberId, username: context.memberInfo.username },
+      currentFtp: context.memberInfo.ftp ?? latest?.value ?? null,
+      ftpHistoryCount: fullHistory.length,
+      query: { historyLimit },
+      records,
+    };
+
+    if (!isJsonMode(flags)) {
+      await writeOutput(payload, flags, (value) => {
+        const lines = [
+          `FTP: ${value.currentFtp ?? "unknown"} [private mode]`,
+          `History points: ${value.ftpHistoryCount}`,
+        ];
+        for (const item of value.records) {
+          lines.push(`- ${item.dateOnly} ftp=${item.value}`);
+        }
+        return lines.join("\n");
+      });
+      return;
+    }
+    await writeOutput(payload, { ...flags, json: !flags.jsonl });
+    return;
+  }
+
+  const payload = {
+    mode: "public",
+    generatedAt: new Date().toISOString(),
+    command: "ftp",
+    member: { username: context.targetUsername },
+    currentFtp: latest?.value ?? null,
+    ftpHistoryCount: fullHistory.length,
+    query: { historyLimit },
+    records,
+    limitations: [
+      "Public mode can expose FTP history only when profile data is public.",
+      "No AI FTP detection or private progression internals in public mode.",
+    ],
+  };
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(payload, flags, (value) => {
+      const lines = [
+        `FTP: ${value.currentFtp ?? "unknown"} [public mode]`,
+        `History points: ${value.ftpHistoryCount}`,
+      ];
+      for (const item of value.records) {
+        lines.push(`- ${item.dateOnly} ftp=${item.value}`);
+      }
+      lines.push(`Limitations: ${value.limitations.join(" ")}`);
+      return lines.join("\n");
+    });
+    return;
+  }
+  await writeOutput(payload, { ...flags, json: !flags.jsonl });
+}
+
+export async function commandFtpPrediction(flags, deps) {
+  const {
+    resolveQueryContext,
+    requirePrivateContext,
+    toIsoDate,
+    isoDateShift,
+    normalizeFitnessThresholds,
+    dateOnlyDiffDays,
+    countPlannedWorkoutsInRange,
+    isJsonMode,
+    writeOutput,
+  } = deps;
+
+  const context = await resolveQueryContext(flags);
+  requirePrivateContext(context, "ftp-prediction");
+
+  const [eligibility, failureStatus, levels, timeline] = await Promise.all([
+    context.client.getAiFtpEligibility(context.memberInfo.memberId, context.memberInfo.username),
+    context.client.getAiFtpFailureStatus(context.memberInfo.memberId, context.memberInfo.username),
+    context.client.getCareerLevels(context.memberInfo.memberId, context.memberInfo.username),
+    context.client.getTimeline(context.memberInfo.memberId, context.memberInfo.username),
+  ]);
+
+  const detection = eligibility?.additionalData?.detection ?? {};
+  const projectedProgressionLevels = Array.isArray(detection?.projectedProgressionLevels)
+    ? detection.projectedProgressionLevels
+    : [];
+  const currentProgressionLevels = Array.isArray(detection?.currentProgressionLevels)
+    ? detection.currentProgressionLevels
+    : [];
+  const nextAiFtpAvailability = eligibility?.additionalData?.nextAiFtpAvailability ?? null;
+  const nextAiFtpAvailabilityDateOnly = nextAiFtpAvailability ? toIsoDate(nextAiFtpAvailability) : null;
+  const todayDateOnly = isoDateShift(0);
+  const fitnessThresholds = normalizeFitnessThresholds(timeline?.fitnessThresholds ?? []);
+  const currentFtpRaw = detection?.ftp ?? context.memberInfo.ftp ?? null;
+  const currentFtp = Number.isFinite(Number(currentFtpRaw)) ? Number(currentFtpRaw) : null;
+
+  let predictedThreshold = null;
+  if (nextAiFtpAvailabilityDateOnly) {
+    const matching = fitnessThresholds.filter((row) => row.dateOnly === nextAiFtpAvailabilityDateOnly);
+    if (matching.length > 0) predictedThreshold = matching[matching.length - 1];
+  }
+  if (!predictedThreshold) {
+    const futureCandidates = fitnessThresholds.filter(
+      (row) => row.dateOnly >= todayDateOnly && !row.isApplied,
+    );
+    if (futureCandidates.length > 0) predictedThreshold = futureCandidates[0];
+  }
+
+  const predictedFtp = predictedThreshold?.value ?? null;
+  const predictionDate = predictedThreshold?.date ?? nextAiFtpAvailability ?? null;
+  const predictionDateOnly = predictedThreshold?.dateOnly ?? nextAiFtpAvailabilityDateOnly ?? null;
+  const daysUntilPrediction =
+    predictionDateOnly != null ? dateOnlyDiffDays(todayDateOnly, predictionDateOnly) : null;
+  const ftpDelta =
+    Number.isFinite(currentFtp) && Number.isFinite(predictedFtp) ? predictedFtp - currentFtp : null;
+  const ftpDeltaPercent =
+    ftpDelta != null && currentFtp && currentFtp !== 0
+      ? Math.round((ftpDelta / currentFtp) * 100)
+      : null;
+  const plannedWorkoutCount =
+    predictionDateOnly != null
+      ? countPlannedWorkoutsInRange(timeline?.plannedActivities ?? [], todayDateOnly, predictionDateOnly)
+      : null;
+
+  const payload = {
+    mode: "private",
+    generatedAt: new Date().toISOString(),
+    command: "ftp-prediction",
+    member: { memberId: context.memberInfo.memberId, username: context.memberInfo.username },
+    canUseAiFtp: Boolean(eligibility?.can),
+    reasonCode: eligibility?.reason ?? null,
+    modelVersion: eligibility?.modelVersion ?? detection?.modelVersion ?? null,
+    detectionFtp: detection?.ftp ?? null,
+    currentFtp,
+    predictedFtp,
+    predictionDate,
+    predictionDateOnly,
+    daysUntilPrediction,
+    ftpDelta,
+    ftpDeltaPercent,
+    plannedWorkoutCount,
+    nextAiFtpAvailability,
+    nextAiFtpAvailabilityDateOnly,
+    lastViewed: eligibility?.additionalData?.lastViewed ?? null,
+    aiFailureStatus: failureStatus?.status ?? null,
+    projectedProgressionLevels,
+    currentProgressionLevels,
+    levels: levels?.levels ?? {},
+    levelsTimestamp: levels?.timestamp ?? null,
+    predictionThresholdSource: predictedThreshold,
+    futureFitnessThresholds: fitnessThresholds.filter((row) => row.dateOnly >= todayDateOnly),
+    records: projectedProgressionLevels,
+  };
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(payload, flags, (value) => {
+      const lines = [
+        `AI FTP usable: ${value.canUseAiFtp}`,
+        `Reason code: ${value.reasonCode}`,
+        `Current FTP: ${value.currentFtp ?? value.detectionFtp ?? "unknown"}`,
+        `Predicted FTP: ${value.predictedFtp ?? "unknown"}`,
+        `Prediction date: ${value.predictionDateOnly ?? value.nextAiFtpAvailabilityDateOnly ?? "unknown"}`,
+        `Days until prediction: ${value.daysUntilPrediction ?? "unknown"}`,
+        `FTP delta: ${value.ftpDelta ?? "unknown"} (${value.ftpDeltaPercent ?? "unknown"}%)`,
+        `Planned workouts in window: ${value.plannedWorkoutCount ?? "unknown"}`,
+        `AI failure status: ${value.aiFailureStatus}`,
+      ];
+      if (value.nextAiFtpAvailability) lines.push(`Next AI FTP availability: ${value.nextAiFtpAvailability}`);
+      lines.push(`Projected progression updates: ${value.projectedProgressionLevels.length}`);
+      for (const item of value.projectedProgressionLevels) {
+        lines.push(
+          `- progressionId=${item.progressionId} from=${item.previousDisplayLevel} to=${item.displayFinalLevel}`,
+        );
+      }
+      return lines.join("\n");
+    });
+    return;
+  }
+  await writeOutput(payload, { ...flags, json: !flags.jsonl });
+}

package/src/commands/levels.mjs

@@ -0,0 +1,58 @@
+import { buildLevelsByZone } from "../lib/planning-normalizers.mjs";
+
+export async function commandLevels(flags, deps) {
+  const {
+    resolveQueryContext,
+    requirePrivateContext,
+    applyAgentRecordFilters,
+    toRecordsOnlyPayload,
+    isJsonMode,
+    writeOutput,
+    hasAgentRecordTransforms,
+  } = deps;
+
+  const context = await resolveQueryContext(flags);
+  requirePrivateContext(context, "levels");
+
+  const [levelsPayload, eligibilityPayload] = await Promise.all([
+    context.client.getCareerLevels(context.memberInfo.memberId, context.memberInfo.username),
+    context.client.getAiFtpEligibility(context.memberInfo.memberId, context.memberInfo.username),
+  ]);
+  const records = buildLevelsByZone(levelsPayload, eligibilityPayload);
+  const { records: filteredRecords, filterSummary } = applyAgentRecordFilters(records, flags);
+
+  const payload = {
+    mode: "private",
+    generatedAt: new Date().toISOString(),
+    command: "levels",
+    filters: filterSummary,
+    member: { memberId: context.memberInfo.memberId, username: context.memberInfo.username },
+    levelsTimestamp: levelsPayload?.timestamp ?? null,
+    aiModelVersion:
+      eligibilityPayload?.modelVersion ??
+      eligibilityPayload?.additionalData?.detection?.modelVersion ??
+      null,
+    count: filteredRecords.length,
+    records: filteredRecords,
+  };
+  const outputPayload = flags["records-only"] ? toRecordsOnlyPayload(payload) : payload;
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(outputPayload, flags, (value) => {
+      const lines = [`Progression levels (${value.count})`];
+      if (hasAgentRecordTransforms(flags) || flags["records-only"]) {
+        for (const item of value.records) lines.push(`- ${JSON.stringify(item)}`);
+        if (value.filters) lines.push(`Filter output: ${value.filters.outputCount}/${value.filters.inputCount}`);
+        return lines.join("\n");
+      }
+      for (const record of value.records) {
+        lines.push(
+          `- ${record.zoneLabel} | recent=${record.recentLevel ?? "n/a"} | aiCurrent=${record.aiCurrentDisplayLevel ?? "n/a"} | aiProjected=${record.aiProjectedDisplayLevel ?? "n/a"} | delta=${record.aiDelta ?? "n/a"}`,
+        );
+      }
+      return lines.join("\n");
+    });
+    return;
+  }
+  await writeOutput(outputPayload, { ...flags, json: !flags.jsonl });
+}

package/src/commands/plan.mjs

@@ -0,0 +1,81 @@
+import {
+  compactCurrentPlan,
+  compactPlanPhase,
+  compactPlanSummary,
+  toIsoDate,
+} from "../lib/planning-normalizers.mjs";
+
+export async function commandPlan(flags, deps) {
+  const {
+    resolveQueryContext,
+    requirePrivateContext,
+    applyAgentRecordFilters,
+    toRecordsOnlyPayload,
+    isJsonMode,
+    writeOutput,
+    hasAgentRecordTransforms,
+  } = deps;
+
+  const context = await resolveQueryContext(flags);
+  requirePrivateContext(context, "plan");
+
+  const view = String(flags.view ?? "phases").toLowerCase();
+  const validViews = new Set(["current", "phases", "plans"]);
+  if (!validViews.has(view)) {
+    throw new Error(`Invalid --view "${view}". Expected one of: current, phases, plans.`);
+  }
+
+  const [currentPlanRaw, allPlansRaw, phasesRaw] = await Promise.all([
+    context.client.getCurrentCustomPlan(context.memberInfo.username),
+    context.client.getAllUserPlans(context.memberInfo.username),
+    context.client.getPlanPhases(context.memberInfo.username),
+  ]);
+  const currentPlan = compactCurrentPlan(currentPlanRaw);
+  const plans = (Array.isArray(allPlansRaw) ? allPlansRaw : []).map((item) => compactPlanSummary(item));
+  const phases = (Array.isArray(phasesRaw) ? phasesRaw : []).map((item) => compactPlanPhase(item));
+
+  const viewRecords =
+    view === "current" ? (currentPlan ? [currentPlan] : []) : view === "plans" ? plans : phases;
+  const { records: filteredRecords, filterSummary } = applyAgentRecordFilters(viewRecords, flags);
+
+  const payload = {
+    mode: "private",
+    generatedAt: new Date().toISOString(),
+    command: "plan",
+    query: { view, full: Boolean(flags.full) },
+    filters: filterSummary,
+    member: { memberId: context.memberInfo.memberId, username: context.memberInfo.username },
+    counts: {
+      plans: plans.length,
+      phases: phases.length,
+      currentPlan: currentPlan ? 1 : 0,
+    },
+    currentPlan: flags.full || view === "current" ? currentPlan : compactCurrentPlan(currentPlanRaw),
+    plans: flags.full || view === "plans" ? plans : undefined,
+    phases: flags.full || view === "phases" ? phases : undefined,
+    count: filteredRecords.length,
+    records: filteredRecords,
+  };
+  const outputPayload = flags["records-only"] ? toRecordsOnlyPayload(payload) : payload;
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(outputPayload, flags, (value) => {
+      const lines = [
+        `Plan view=${value.query?.view ?? view} records=${value.count}`,
+      ];
+      if (hasAgentRecordTransforms(flags) || flags["records-only"]) {
+        for (const item of value.records) lines.push(`- ${JSON.stringify(item)}`);
+        if (value.filters) lines.push(`Filter output: ${value.filters.outputCount}/${value.filters.inputCount}`);
+        return lines.join("\n");
+      }
+      for (const item of value.records) {
+        lines.push(
+          `- ${item.name ?? item.planName ?? "(unnamed)"} ${item.dateOnly ?? "(no-date)"} -> ${item.end ? toIsoDate(item.end) : "n/a"}`,
+        );
+      }
+      return lines.join("\n");
+    });
+    return;
+  }
+  await writeOutput(outputPayload, { ...flags, json: !flags.jsonl });
+}