@richhaase/c2 0.3.2 → 0.4.0

package/README.md

@@ -96,7 +96,12 @@ c2 trend -w 12
 
 ### HTML Report
 
-Generate a self-contained HTML progress report:
+Generate a self-contained HTML progress report. Coaching content from the
+store renders automatically when present: the latest narrative (as "Coach's
+Report"), notes from the last 14 days, and the training-plan excerpt.
+`c2 report --data` emits the entire report as structured JSON
+(`c2.report.v1`) — the machine-readable twin of the HTML, for agents and
+custom rendering surfaces:
 
 ```bash
 # Generate report.html in current directory
@@ -134,12 +139,96 @@ The CSV export includes `workout_type`, `rest_time_tenths`, and
 `rest_distance` columns so interval workouts are fully distinguishable from
 continuous pieces without having to consult the full JSON export.
 
+### Workout Detail & Derived Stats
+
+```bash
+# Full detail for one workout: splits, stroke summary, comments
+c2 show last
+c2 show 118212501
+
+# Derived analytics (the arithmetic, so coaches only interpret)
+c2 stats weekly -w 12     # volume/pace/SPM/HR per week
+c2 stats goal             # trajectory + projection
+c2 stats splits last      # per-split pace/HR + shape (even/negative/positive)
+c2 stats hr-pace -w 8     # avg HR by steady pace band, with early→late drift
+```
+
+All of these accept `--json`.
+
+### Coaching Data
+
+The store holds coaching content alongside workout data, so any coach — human
+or AI, on any machine — reads and writes the same facts:
+
+```bash
+# Subjective report after a row (athlete voice, linked to the workout)
+c2 note add --type subjective --workout last "felt slow early, opened up late"
+
+# Coach observations and durable lessons
+c2 note add --type lesson --author coach "HR cap is the rule, not pace"
+
+# Review
+c2 note list --since 2026-06-01
+c2 note list --workout 118212501 --json
+c2 show last                     # linked notes appear in workout detail
+
+# Training plan and coaching playbook (whole-document set/show)
+c2 plan set plan.md
+c2 playbook show
+
+# Dated coaching report narratives
+c2 narrative add 2026-07-05 report.md
+c2 narrative show
+```
+
+Notes are stored one file each for the most recent 7 days (safe under iCloud/
+Dropbox sync), then automatically compacted into one archive file per year
+(`c2 data compact` runs after every sync). `c2 data doctor` validates the
+whole store.
+
+### Machine-Readable Output
+
+`log`, `status`, `trend`, `show`, `stats`, and `data info` accept `--json` and emit a stable
+versioned envelope for scripts and AI agents:
+
+```json
+{ "schema": "c2.status.v1", "generated_at": "2026-07-05T18:00:00.000Z", "data": { } }
+```
+
+`export -f json` emits the same envelope (`c2.export.v1`) with the full
+workout records under `data.workouts`. `export -f jsonl` stays one raw
+workout per line for streaming.
+
+### Data Store
+
+Workout data and (soon) coaching data live in a single data directory,
+chosen during `c2 setup` and stored as `data_dir` in config. Point it at a
+synced folder (iCloud, Dropbox, a git repo) to share one store across
+machines — the config file with your API token always stays machine-local
+in `~/.config/c2/` (mode 600).
+
+```bash
+# Where is my data, and what's in it?
+c2 data info
+
+# Relocate the store (copies, verifies, updates config)
+c2 data move ~/Documents/KnowledgeBase/c2-data
+```
+
+Setup validates the directory you pick: it creates it if missing (with
+confirmation), checks writability, adopts an existing c2 store it finds
+there, and refuses to save a path that fails validation.
+
+Note: bare `c2` prints help. Unknown commands error instead of falling
+through to a default.
+
 ## Configuration
 
 Config lives at `~/.config/c2/config.json`. Created automatically on `c2 setup`.
 
 ```json
 {
+  "data_dir": "~/.config/c2/data",
   "api": {
     "base_url": "https://log.concept2.com",
     "token": "YOUR_TOKEN"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@richhaase/c2",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "CLI tool for syncing and analyzing Concept2 rowing data",
   "keywords": [
     "concept2",
@@ -31,8 +31,8 @@
     "commander": "^14.0.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.10",
-    "@types/bun": "^1.3.9"
+    "@biomejs/biome": "^2.4.11",
+    "@types/bun": "^1.3.12"
   },
   "files": [
     "src"

package/src/analysis.test.ts

@@ -0,0 +1,180 @@
+import { expect, test } from "bun:test";
+import { hrAtPace, splitShape, splitTable, strokeSummary } from "./analysis.ts";
+import { projectGoal } from "./commands/stats.ts";
+import type { StrokeData, Workout, WorkoutSplit } from "./models.ts";
+import type { GoalProgress } from "./stats.ts";
+
+function split(timeTenths: number, distance: number, spm: number, hr: number): WorkoutSplit {
+  return {
+    type: "distance",
+    time: timeTenths,
+    distance,
+    stroke_rate: spm,
+    heart_rate: { average: hr, max: hr + 8 },
+  };
+}
+
+function workoutWithSplits(splits: WorkoutSplit[]): Workout {
+  return {
+    id: 1,
+    user_id: 1,
+    date: "2026-07-03 12:00:00",
+    distance: splits.reduce((s, x) => s + (x.distance ?? 0), 0),
+    type: "rower",
+    time: splits.reduce((s, x) => s + x.time, 0),
+    time_formatted: "34:39.1",
+    workout: { targets: { pace: 1750 }, splits },
+  };
+}
+
+const NEGATIVE_SPLIT_WORKOUT = workoutWithSplits([
+  split(4280, 1200, 24, 93),
+  split(4210, 1200, 25, 107),
+  split(4140, 1200, 25, 115),
+  split(4076, 1200, 26, 120),
+  split(4088, 1200, 26, 122),
+]);
+
+test("splitTable computes per-split pace from tenths", () => {
+  const rows = splitTable(NEGATIVE_SPLIT_WORKOUT);
+  expect(rows.length).toBe(5);
+  expect(rows[0]!.pace_500m_seconds).toBe(178.3);
+  expect(rows[0]!.pace_500m).toBe("2:58.3");
+  expect(rows[3]!.pace_500m).toBe("2:49.8");
+  expect(rows[0]!.hr_avg).toBe(93);
+  expect(rows[0]!.hr_max).toBe(101);
+});
+
+test("splitShape detects the 07/03-style negative split", () => {
+  expect(splitShape(splitTable(NEGATIVE_SPLIT_WORKOUT))).toBe("negative");
+});
+
+test("splitShape detects even, positive, variable, and unknown", () => {
+  const even = workoutWithSplits([
+    split(4200, 1200, 25, 110),
+    split(4210, 1200, 25, 112),
+    split(4195, 1200, 25, 113),
+    split(4205, 1200, 25, 114),
+  ]);
+  expect(splitShape(splitTable(even))).toBe("even");
+
+  const positive = workoutWithSplits([
+    split(4000, 1200, 26, 118),
+    split(4100, 1200, 25, 120),
+    split(4250, 1200, 24, 121),
+    split(4350, 1200, 23, 122),
+  ]);
+  expect(splitShape(splitTable(positive))).toBe("positive");
+
+  const variable = workoutWithSplits([
+    split(4000, 1200, 26, 118),
+    split(4400, 1200, 22, 110),
+    split(3950, 1200, 27, 125),
+    split(4380, 1200, 22, 112),
+  ]);
+  expect(splitShape(splitTable(variable))).toBe("variable");
+
+  expect(splitShape(splitTable(workoutWithSplits([split(4200, 1200, 25, 110)])))).toBe("unknown");
+  expect(splitShape([])).toBe("unknown");
+});
+
+test("strokeSummary aggregates samples", () => {
+  const strokes: StrokeData[] = [
+    { t: 100, d: 500, p: 1750, spm: 24, hr: 110 },
+    { t: 200, d: 1000, p: 1730, spm: 25, hr: 118 },
+    { t: 300, d: 1500, p: 1710, spm: 26, hr: 126 },
+    { t: 400, d: 2000, p: 0, spm: 0, hr: 0 },
+  ];
+  const s = strokeSummary(strokes);
+  expect(s.samples).toBe(4);
+  expect(s.avg_pace_500m_seconds).toBe(173);
+  expect(s.avg_pace_500m).toBe("2:53.0");
+  expect(s.avg_spm).toBe(25);
+  expect(s.avg_hr).toBe(118);
+  expect(s.max_hr).toBe(126);
+});
+
+function goalFixture(overrides: Partial<GoalProgress>): GoalProgress {
+  return {
+    target: 1_000_000,
+    totalMeters: 900_000,
+    progress: 0.9,
+    weeksElapsed: 26,
+    totalWeeks: 52,
+    remainingMeters: 100_000,
+    remainingWeeks: 26,
+    requiredPace: 3846,
+    currentAvgPace: 20_000,
+    onPace: true,
+    ...overrides,
+  };
+}
+
+const PROJECT_NOW = new Date("2026-07-06T12:00:00");
+
+function daysAfterNow(n: number): Date {
+  return new Date(PROJECT_NOW.getTime() + n * 24 * 60 * 60 * 1000);
+}
+
+test("projectGoal projects over actual remaining time", () => {
+  const active = projectGoal(goalFixture({}), daysAfterNow(26 * 7), PROJECT_NOW);
+  expect(active.projected_total_meters).toBe(900_000 + 26 * 20_000);
+  expect(active.shortfall_meters).toBe(0);
+});
+
+test("projectGoal adds nothing after the goal window ends", () => {
+  const expired = projectGoal(
+    goalFixture({ weeksElapsed: 60, remainingWeeks: 1 }),
+    daysAfterNow(-2),
+    PROJECT_NOW,
+  );
+  expect(expired.projected_total_meters).toBe(900_000);
+  expect(expired.projected_pct).toBe(90);
+  expect(expired.shortfall_meters).toBe(100_000);
+});
+
+test("projectGoal handles fractional final weeks without over-projecting", () => {
+  const halfWeek = projectGoal(goalFixture({}), daysAfterNow(3.5), PROJECT_NOW);
+  expect(halfWeek.projected_total_meters).toBe(900_000 + 10_000);
+});
+
+function steadyWorkout(id: number, date: string, paceSecs: number, hr: number): Workout {
+  const distance = 6000;
+  return {
+    id,
+    user_id: 1,
+    date,
+    distance,
+    type: "rower",
+    time: Math.round(paceSecs * (distance / 500) * 10),
+    time_formatted: "x",
+    heart_rate: { average: hr },
+  };
+}
+
+const NOW = new Date("2026-07-05T12:00:00");
+
+test("hrAtPace buckets steady work and reports early-late drift", () => {
+  const workouts: Workout[] = [
+    steadyWorkout(1, "2026-05-20 08:00:00", 173, 120),
+    steadyWorkout(2, "2026-05-27 08:00:00", 174, 118),
+    steadyWorkout(3, "2026-06-24 08:00:00", 172, 112),
+    steadyWorkout(4, "2026-07-01 08:00:00", 171, 110),
+    steadyWorkout(5, "2026-07-03 08:00:00", 168, 115),
+    { ...steadyWorkout(6, "2026-07-02 08:00:00", 150, 140), rest_time: 600 },
+    steadyWorkout(7, "2026-01-01 08:00:00", 173, 130),
+  ];
+  const bands = hrAtPace(workouts, NOW, 8);
+
+  expect(bands.length).toBe(2);
+  const band170 = bands.find((b) => b.band_start_seconds === 170)!;
+  expect(band170.workouts).toBe(4);
+  expect(band170.early_avg_hr).toBe(119);
+  expect(band170.late_avg_hr).toBe(111);
+  expect(band170.hr_delta).toBe(-8);
+  expect(band170.band).toBe("2:50.0–2:55.0");
+
+  const band165 = bands.find((b) => b.band_start_seconds === 165)!;
+  expect(band165.workouts).toBe(1);
+  expect(band165.hr_delta).toBeNull();
+});

package/src/analysis.ts

@@ -0,0 +1,158 @@
+import type { StrokeData, Workout } from "./models.ts";
+import { formatSeconds, isIntervalWorkout, pace500mSeconds, parsedDate } from "./models.ts";
+
+const TENTHS_PER_SECOND = 10;
+const PACE_DISTANCE = 500;
+
+export interface SplitRow {
+  index: number;
+  distance: number | null;
+  time_seconds: number;
+  pace_500m_seconds: number | null;
+  pace_500m: string | null;
+  stroke_rate: number | null;
+  hr_avg: number | null;
+  hr_max: number | null;
+}
+
+export type SplitShape = "even" | "negative" | "positive" | "variable" | "unknown";
+
+const SHAPE_DRIFT_THRESHOLD_SECONDS = 1.5;
+const SHAPE_SPREAD_THRESHOLD_SECONDS = 6;
+
+export function splitTable(w: Workout): SplitRow[] {
+  const splits = w.workout?.splits ?? [];
+  return splits.map((s, i) => {
+    const seconds = s.time / TENTHS_PER_SECOND;
+    const pace =
+      s.distance != null && s.distance > 0 ? seconds * (PACE_DISTANCE / s.distance) : null;
+    return {
+      index: i + 1,
+      distance: s.distance ?? null,
+      time_seconds: Math.round(seconds * 10) / 10,
+      pace_500m_seconds: pace != null ? Math.round(pace * 10) / 10 : null,
+      pace_500m: pace != null ? formatSeconds(pace) : null,
+      stroke_rate: s.stroke_rate ?? null,
+      hr_avg: s.heart_rate?.average ?? null,
+      hr_max: s.heart_rate?.max ?? null,
+    };
+  });
+}
+
+export function splitShape(rows: SplitRow[]): SplitShape {
+  const paces = rows.map((r) => r.pace_500m_seconds).filter((p): p is number => p != null);
+  if (paces.length < 2) return "unknown";
+
+  const mid = Math.floor(paces.length / 2);
+  const firstHalf = paces.slice(0, mid);
+  const secondHalf = paces.slice(paces.length - mid);
+  const avg = (xs: number[]) => xs.reduce((a, b) => a + b, 0) / xs.length;
+  const drift = avg(firstHalf) - avg(secondHalf);
+  const spread = Math.max(...paces) - Math.min(...paces);
+
+  if (Math.abs(drift) <= SHAPE_DRIFT_THRESHOLD_SECONDS) {
+    return spread > SHAPE_SPREAD_THRESHOLD_SECONDS ? "variable" : "even";
+  }
+  return drift > 0 ? "negative" : "positive";
+}
+
+export interface StrokeSummary {
+  samples: number;
+  avg_pace_500m_seconds: number | null;
+  avg_pace_500m: string | null;
+  avg_spm: number | null;
+  avg_hr: number | null;
+  max_hr: number | null;
+}
+
+export function strokeSummary(strokes: StrokeData[]): StrokeSummary {
+  let paceSum = 0;
+  let paceCount = 0;
+  let spmSum = 0;
+  let spmCount = 0;
+  let hrSum = 0;
+  let hrCount = 0;
+  let maxHR = 0;
+  for (const s of strokes) {
+    if (s.p != null && s.p > 0) {
+      paceSum += s.p / TENTHS_PER_SECOND;
+      paceCount++;
+    }
+    if (s.spm != null && s.spm > 0) {
+      spmSum += s.spm;
+      spmCount++;
+    }
+    if (s.hr != null && s.hr > 0) {
+      hrSum += s.hr;
+      hrCount++;
+      if (s.hr > maxHR) maxHR = s.hr;
+    }
+  }
+  const avgPace = paceCount > 0 ? paceSum / paceCount : null;
+  return {
+    samples: strokes.length,
+    avg_pace_500m_seconds: avgPace != null ? Math.round(avgPace * 10) / 10 : null,
+    avg_pace_500m: avgPace != null ? formatSeconds(avgPace) : null,
+    avg_spm: spmCount > 0 ? Math.round((spmSum / spmCount) * 10) / 10 : null,
+    avg_hr: hrCount > 0 ? Math.round(hrSum / hrCount) : null,
+    max_hr: maxHR > 0 ? maxHR : null,
+  };
+}
+
+export interface HRPaceBand {
+  band_start_seconds: number;
+  band: string;
+  workouts: number;
+  avg_hr: number;
+  early_avg_hr: number | null;
+  late_avg_hr: number | null;
+  hr_delta: number | null;
+}
+
+const BAND_WIDTH_SECONDS = 5;
+const MIN_STEADY_DISTANCE = 1000;
+
+export function hrAtPace(workouts: Workout[], now: Date, weeks: number): HRPaceBand[] {
+  const cutoff = new Date(now);
+  cutoff.setDate(cutoff.getDate() - weeks * 7);
+  const midpoint = new Date(cutoff.getTime() + (now.getTime() - cutoff.getTime()) / 2);
+
+  const steady = workouts.filter((w) => {
+    if (isIntervalWorkout(w)) return false;
+    if (w.distance < MIN_STEADY_DISTANCE) return false;
+    if (!w.heart_rate?.average || w.heart_rate.average <= 0) return false;
+    const t = parsedDate(w);
+    return t >= cutoff && t <= now && pace500mSeconds(w) > 0;
+  });
+
+  const bands = new Map<number, { all: number[]; early: number[]; late: number[] }>();
+  for (const w of steady) {
+    const pace = pace500mSeconds(w);
+    const bandStart = Math.floor(pace / BAND_WIDTH_SECONDS) * BAND_WIDTH_SECONDS;
+    if (!bands.has(bandStart)) bands.set(bandStart, { all: [], early: [], late: [] });
+    const bucket = bands.get(bandStart)!;
+    const hr = w.heart_rate!.average!;
+    bucket.all.push(hr);
+    if (parsedDate(w) < midpoint) bucket.early.push(hr);
+    else bucket.late.push(hr);
+  }
+
+  const avg = (xs: number[]) =>
+    xs.length > 0 ? Math.round(xs.reduce((a, b) => a + b, 0) / xs.length) : null;
+
+  return [...bands.entries()]
+    .sort(([a], [b]) => a - b)
+    .map(([bandStart, bucket]) => {
+      const early = avg(bucket.early);
+      const late = avg(bucket.late);
+      return {
+        band_start_seconds: bandStart,
+        band: `${formatSeconds(bandStart)}–${formatSeconds(bandStart + BAND_WIDTH_SECONDS)}`,
+        workouts: bucket.all.length,
+        avg_hr: avg(bucket.all)!,
+        early_avg_hr: early,
+        late_avg_hr: late,
+        hr_delta: early != null && late != null ? late - early : null,
+      };
+    });
+}