Skip to content

trainctl 0.9.0: corpus-checked running engine, one view layout, session plan by default

Latest

Choose a tag to compare

@dithiothreitol dithiothreitol released this 12 Nov 20:34
· 1 commit to main since this release

trainctl 0.9.0 brings a running engine checked against a coaching corpus, one row layout for every view, workout-level review from laps, and the session plan as the default data model. It collects four stages of work since 0.6.0.

Highlights

A running engine measured, not guessed

  • Season shape checked against a coaching corpus. A matrix of 576 synthetic profiles (base volume × days × goal × horizon × time budget) generates plans without shape violations: the long run stays the longest session, no single session carries the week, easy running stays at or above 75%.
  • A long-run track that grows by at most 2 km per loading week, and accents that progress through the season (J-8), with a 1000/400/200 m ladder in the peak phase.
  • Weekly time budget caps the peak of the macrocycle instead of trimming week by week, so deloads and the taper stay lighter than the weeks around them.
  • Return after a break. trainctl log --to … --reason illness|injury|travel|other records a break, and adapt proposes a return block to approve (R-5 after illness, R-11 after a layoff, no volume proposal after an injury).
  • trainctl check reports season-shape issues; trainctl rules explains every rule the engine cites, with its source.

Views on one row layout

  • trainctl season: the whole season, one week per row, with accents and the long run.
  • week, today, PLAN.md and the printable sheet share the same session rows; --full brings back the full cards.
  • review against the targets: laps from FIT, TCX or intervals.icu are matched to the planned repetitions, with paces and the share within range. Auto laps are reported as such; heart rate is never judged.
  • View options: miles (units: imperial), Polish club notation (notation: club) and a heart-rate ceiling for easy and long runs from hrMax and sex. Pace stays the target.

One data model

  • trainctl init writes the session-plan profile (schema 2). A running profile with the running block uses the full running engine; cycling and swimming live in the same file.
  • Running-plan parity. In a running workspace on schema 2, why, status, review, adapt, desk and break logging behave exactly as in the running plan, and proposals are applied with --apply.
  • Structured running steps. Warm-up, repetitions with a pace range and recovery, strides, hills and progression thirds reach the FIT file and the intervals.icu workout as real steps, each with the RPE range of its segment.

Upgrade notes

  • The first trainctl plan after updating rewrites future days of an existing plan. Past, logged, pinned and approved days stay as they are. Run trainctl diff first to preview the change.
  • New workspaces use schema 2. Existing running-plan profiles keep working unchanged. To move one, run trainctl migrate --prepare, review the proposal, then trainctl migrate --apply <id>; every profile field is carried over and the originals are kept in plan/migrations/<id>/.
  • The Claude Code plugin starts trainctl-mcp@0.9.0 through npx; update the plugin to pick up this version.

Install

npx trainctl@0.9.0 init           # no install
npm install -g trainctl@0.9.0     # or install the CLI
claude mcp add trainctl --env TRAINCTL_DIR="/path/to/my-training" -- npx -y trainctl-mcp@0.9.0

Codex users can download trainctl-codex-0.9.0.zip below. It bundles the CLI, the MCP server and their dependencies; follow INSTALL.txt. Node.js 22.18 or newer is required.

All six npm packages are published at 0.9.0 with the latest tag: trainctl, trainctl-mcp, trainctl-core, trainctl-export, trainctl-sync-intervalsicu, trainctl-sync-files.

Verification

  • 1672 tests, typecheck and build on the release commit; CI green on Linux and Windows with Node 22.18 and 24, including installation from tarballs.
  • Tarballs installed in an isolated directory and the CLI and MCP scenarios run from them: 128 FIT files decoded with the Garmin FIT SDK, 8 calendars, 11 MCP calls.
  • The same scenarios run again from the public npm registry without authentication (npm-validation.json).
  • SHA256SUMS.txt lists the checksums of the attached files.

Assets

File Contents
trainctl-codex-0.9.0.zip Codex plugin with the bundled CLI and MCP server
validation.json Local validation of the release commit and the plugin bundle
npm-validation.json Validation of the published npm packages
SHA256SUMS.txt SHA-256 checksums of the files above

Full changelog: CHANGELOG.md · Compare v0.6.0...v0.9.0