Skip to content

Releases

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

Choose a tag to compare

@dithiothreitol dithiothreitol released this 12 Nov 20:34

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

v0.6.0 · Structured workouts and clearer CLI

Choose a tag to compare

@dithiothreitol dithiothreitol released this 04 Nov 21:33

Version 0.6.0 adds detailed workout instructions and makes the terminal descriptions easier to follow. Version 0.6.0 is available on npm and GitHub. All six npm packages use the latest tag. The Codex plugin ZIP includes the CLI, MCP server and dependencies.

Fixed

  • Fractional pace now rounds correctly across minute boundaries in CLI and
    Intervals.icu work/recovery steps.
  • Hard running and timed swimming repetitions explain their actual intent;
    standalone sessions do not imply a known training phase.
  • Multisport rule links now refer to MULTISPORT rather than running foundations.

Added

  • Phase-specific cycling and swimming recipes with objectives, rationale,
    success criteria, warm-up, main work, recovery and cool-down.
  • Named swimming drills, RPE guidance without current calibration, and
    bounded progression for bike/run bricks.
  • Coaching instructions in CLI/MCP, JSON/YAML, Markdown, HTML, ICS and
    Intervals.icu; FIT step notes and explicit recovery power/pace.
  • MS-6 documents recipe parameters, evidence boundaries and device limits.

Changed

  • CLI workout cards separate objectives, structure, rationale and adjustments
    with coloured headings. Planned peak RPE has a labelled ten-step colour scale;
    recovery targets have separate rows, and durations use minutes and seconds.
  • Replacement and shortening previews compare structured cards; confirmation
    shows a concise summary. Plain/MCP output keeps headings and numeric RPE.
  • FTP/CSS without a current dated source now uses subjective effort guidance.
  • Shortening preserves complete repetitions and the minimum quality stimulus.
  • A time budget too small for a quality set explicitly produces an easy session.

Distribution and limits

  • Six npm packages at version 0.6.0 (latest), plus a self-contained Codex plugin
    and terminal examples on GitHub.
  • Training recipe parameters remain documented engineering choices; independent
    coaching review and tests on physical Garmin/Suunto watches are still pending.
  • FIT step notes may be truncated to 254 UTF-8 bytes; full instructions remain
    available through CLI/MCP and text exports.

Verification

  • Public npm installation (fresh directory and cache, no authentication): PASS. All six latest tags resolve to 0.6.0; 56 CLI commands, 11 MCP calls, 128 FIT files and 8 ICS calendars / 231 events. Coaching metadata and coloured RPE output verified.
  • Local suite: 1076/1076 tests passed, types, build and generated skills checked.
  • Coaching simulation: 17 real CLI calls, 72 sessions and 22 workout recipes.
  • Isolated package installation: 56 CLI commands, 11 MCP calls, 128 FIT files and 8 ICS calendars / 231 events.
  • Relocated plugin: 40 CLI calls, 58 MCP calls, all 22 tools, 50 resources and 2 prompts.
  • All six CI jobs passed, Linux/Windows and Node 22.18/24.

Install from npm

npm install -g trainctl@0.6.0
# Or run without a global installation:
npx --yes trainctl@0.6.0 --version

MCP: npx --yes trainctl-mcp@0.6.0. Requires Node >=22.18.0.

Downloads

  • trainctl-codex-0.6.0.zip: extract to a permanent directory and follow INSTALL.txt. Requires Node >=22.18.0. The bundled CLI runs through node plugin/scripts/trainctl.mjs.
  • trainctl-x-examples-0.6.0.zip: 10 terminal images at 1600×900, draft Polish posts, alt text and an offline gallery. Captured during 0.6.0 development using synthetic data.
  • validation.json, npm-validation.json and SHA256SUMS.txt: verification details and asset integrity.

Workout objective and RPE scale

Full changes: v0.5.0...v0.6.0

v0.5.0 — multisport, Codex plugin and responsive CLI

Choose a tag to compare

@dithiothreitol dithiothreitol released this 04 Nov 16:25

Version 0.5.0 is distributed through GitHub only: source code and the bundled Codex plugin are available below. No 0.5.0 npm packages are published as part of this release. The ZIP plugin includes its dependencies and works without downloading them from npm.

Added

  • Cycling, swimming and mixed-sport plans with separate profiles, time volumes,
    equipment constraints, session IDs and multisport race groups.
  • Reviewed substitutions in all six directions between running, cycling and
    swimming, with time budgets, trade-offs and restoration of the original session.
  • Schema v1 to v2 migration with preview/apply, protected history, journal entries
    for the sport actually performed, and recovery after interrupted writes.
  • Multisport FIT, ICS and HTML exports, calendar withdrawal/reactivation, and
    activity matching across Intervals.icu and imported FIT/TCX/GPX files.
  • A self-contained Codex plugin bundle with 21 training tools, six skills and
    trainctl_workspace for selecting the training directory explicitly.
  • --color auto|always|never and --plain; responsive tables, consistent sport
    colours, readable help and separate session metadata in the CLI.

Fixed

  • week --session now selects the requested session, including other weeks,
    and rejects unknown IDs or conflicting sport filters.
  • init --from-intervals respects agent setup and commit options; a conflicting
    --sports option is rejected before contacting the provider or writing files.
  • CLI logs of a spontaneous sport change now use the same default modified
    status as MCP unless an explicit status is supplied.
  • Codex no longer treats the plugin cache as the training workspace. A server
    session binds to one selected directory and keeps its credential context separate.
  • Interactive selectors and the week browser now emit valid terminal control
    sequences. Narrow layouts preserve labels, full IDs and Unicode graphemes.

Dependencies and validation

  • Updated the MCP SDK, Zod, Vitest/Vite and transitive dependencies; adapted the
    test runner to Vitest 4. The dependency audit returned no known advisories.
  • CI checks source, installed npm tarballs and relocated plugin bundles on Linux
    and Windows. Export checks use Garmin FIT SDK and ICAL.js independently.

Known limits

  • Cycling/swimming templates and substitution limits remain explicit engineering
    choices; a substitution is not a claim of physiological equivalence.
  • Physical-watch acceptance is separate from file/parser validation. Suunto
    account pairing and live Google Calendar import were not completed in this audit.
  • Multisport groups export linked sessions; swimming FIT send-off is unsupported,
    and pace is descriptive when stroke is the executable target.

Release verification

  • Local full suite: 1044/1044 passed, types/build and npm dry-run passed.
  • CI: all six jobs passed, Linux/Windows and Node 22.18/24.
  • Installed tarballs: 56 CLI commands, 11 MCP calls, 128 FIT files and 8 ICS calendars verified.
  • Bundled plugin: all 22 tools, 40 CLI calls, 57 MCP calls, 49 resources and 2 prompts.
  • Attachments: plugin ZIP, SHA-256 sums, validation metadata and CLI output renders using synthetic data.

To install the Codex plugin, extract the ZIP to a permanent directory and follow INSTALL.txt. Node >=22.18.0 is required.

v0.4.0 — plugin for Claude Code and Codex, activity files, and a plan that keeps your decisions

Choose a tag to compare

@dithiothreitol dithiothreitol released this 21 Oct 21:35

Install: npx trainctl@0.4.0, MCP: npx -y trainctl-mcp@0.4.0, plugin for Claude Code and Codex from this repository (see docs/integrations/agents.md). New package: trainctl-sync-files. Full history in CHANGELOG.md.

Fixed — found by running every command on a fresh directory

  • review on a Sunday no longer reports the whole week's volume next to the
    number of remaining sessions ("52 km across 1 sessions"); it shows what is
    left of the week's target.
  • A directory without trainctl.yaml now points to trainctl init instead of
    trainctl plan, which would only have pointed back to init.
  • why no longer prints "About 0 minutes" for a rest day, no longer states the
    session's purpose twice, and lists each rule once with its text and
    provenance instead of in two separate sections.
  • log answers with what the plan had for that day next to what was recorded,
    says when an entry falls on a rest day, and returns structured data for MCP.
  • Messages print plan/plan.yaml on every system (Windows printed plan\plan.yaml).
  • A plan generated by another minor version of the engine is reported in
    today, week, why, review and check (informational; never fails
    --strict). A plan file with a newer schema is refused with advice to
    upgrade trainctl.
  • Rule sources link to docs/science/FOUNDATIONS.md on GitHub, pinned to the
    release tag — the file is not part of the npm package, so the relative path
    in why, desk and AGENTS.md led nowhere after installation.

Changed — trainctl plan keeps what you decided (ADR-033)

  • On an existing plan, plan regenerates only the future. Past and logged
    days, pinned days, hand edits, approved shortenings and days whose new session
    would exceed a saved time budget stay as they are. An approved volume baseline
    from adapt --apply is kept until you change athlete.recentWeeklyKm.
    Previously every regeneration silently discarded all of that — including on
    the documented path "add a race result → trainctl plan".
  • The same training cycle keeps its phase boundaries; a different goal distance,
    or a new goal after the race, starts a new cycle and keeps the earlier weeks
    as history ("week 2/12" counts the current cycle). On race day the race
    counts as done only when most of its distance is logged or synced (a day
    logged as skipped never counts), so a morning shakeout before a postponed
    race keeps the same cycle.
  • Right after adapt --apply, plan reproduces the approved days, including
    strength sessions, time-budget caps and the day of the decision. Later,
    strength follows the current phases and strength.days.
  • A plan/plan.yaml that cannot be read (a merge conflict, a missing goal) is
    never overwritten silently: plan refuses until it is fixed or --fresh is
    given, and status no longer suggests a plan that would fail.
  • trainctl diff shows exactly the regeneration plan would perform.
    plan --fresh (MCP fresh) starts over and lists what it discards.
  • Fixed: a race result recorded inside the plan's horizon did not reset the
    calibration rhythm (W-12), so a regeneration could schedule a time trial a
    week after a fresh 10 km result.

Added — a CLI you can script

  • --json on every command prints { code, data, output } — the same data the
    MCP tools return (ADR-035).
  • -C <dir> / TRAINCTL_DIR for the CLI, as the MCP server already had.
  • TRAINCTL_TODAY=YYYY-MM-DD simulates the date; every CLI and MCP output
    announces it, and past-day protection and proposal expiry follow it (ADR-034).
  • Relative dates in the CLI: today, tomorrow, yesterday, +N/-N,
    weekday names in English and Polish. MCP tools stay ISO-only.
  • trainctl log without flags in a terminal asks: pick a session from the last
    week, then status, distance, time, RPE and a note.
  • trainctl status / trainctl_status: profile validity, engine version,
    calibration, key source (never its value), .env protection, last pull,
    journal, saved proposals with their validity today, uncommitted files.
  • --commit [message] on init, plan, log, shift, reschedule --apply,
    adapt --apply and shorten --apply (MCP commit) commits exactly the files
    the command changed — never secrets, sync.json or other staged changes
    (ADR-040). init --commit includes .gitignore when it created it or when it
    had no uncommitted changes before the secret patterns were added.
  • today shows the estimated duration and the next session.
  • trainctl completion bash|zsh|fish|pwsh, examples under trainctl help <command>.
  • Usage errors (unknown command or flag, a date that is not a date) exit with 2.

Added — trainctl in Claude Code and Codex (ADR-036)

  • A plugin in plugin/, with this repository as its marketplace for both agents:
    /plugin marketplace add dithiothreitol/trainctl + /plugin install trainctl@trainctl
    in Claude Code, codex plugin marketplace add dithiothreitol/trainctl in Codex.
    It bundles the MCP server, the coach persona and four task skills
    (review, debrief, shorten, what-if), and in Claude Code two hooks: the
    coach instructions at session start in a training directory, and
    trainctl check after an edit of plan/plan.yaml.
  • Skills are generated from the same text as AGENTS.md
    (node tools/plugin/render-skills.ts); plugin.test.ts fails on drift.
  • trainctl init --agent claude|codex|all (MCP agent) writes
    .claude/settings.json or .codex/config.toml; existing files are never
    overwritten.
  • MCP: trainctl_rule explains a rule by ID with its source class and a link to
    FOUNDATIONS for this version; resources trainctl://plan, trainctl://config,
    trainctl://agents, trainctl://rules/{id}; prompts weekly-review and
    debrief. CLI: trainctl rules [id].
  • trainctl check returns its findings as data (--json, MCP, the hook).
  • tools/release/bump-version.mjs moves every pinned version together: packages,
    plugin manifests, MCP configs, the hook and the CI examples.

Added — execution without a hub, a fuller calendar, context from the watch (ADR-037)

  • New package trainctl-sync-files: reads exported FIT, TCX and GPX files
    (also .gz, as in Strava and Garmin bulk exports) as a pull-only source, with
    no dependencies. trainctl pull --from <folder> (MCP from) and
    sync.files in trainctl.yaml for review without an API key. Skipped files
    are named. The same run exported in two formats (start within 60 s, similar
    distance) counts once, keeping the richest file: FIT, then TCX, then GPX.
    init adds activities/ to .gitignore.
  • The sync port is split into ActivitySource (pull) and SyncProvider
    (pull + push).
  • push sends races as race events (RACE_A/B/C) and strength sessions as
    separate WeightTraining entries, in their own requests: if intervals.icu
    refuses either form, a race falls back to an ordinary entry, a warning says
    so, and the running sessions are pushed regardless. Cleanup of stale entries
    now covers every trainctl- entry, not only workouts. Not yet verified on a
    live intervals.icu account.
  • review quotes resting heart rate, sleep and weight from the synced wellness
    data, and RPE recorded in the hub where the journal has none — verbatim, with
    the source, never averaged or turned into a verdict. HRV and CTL/ATL are
    deliberately left out (H-1, P-4).

Added — the engine: time, life after the race, a plan without a race

  • Time budget (time.weeklyMinutes, weekdayMinutes, weekendMinutes,
    E-2): weeks over the weekly budget get a lower volume target, days over their
    limit are shortened with the same rules as shorten and carry the trade-off;
    the plan says when the budget lowers the peak below the level recommended
    for the distance, and what the peak would be without it (P-7/P-8). Races and
    time trials are never cut.
    A week keeps its macrocycle target; the volume the budget leaves is stored
    next to it (timeCappedKm), and week, adapt, diff and export show it.
    A zone recalibration from adapt changes paces: day limits shorten
    sessions that no longer fit from the current week, the weekly budget lowers
    volume from the next week on, and volume goes up again through plan.
  • Transition block after the goal race (R-8): after a half marathon or
    longer, two weeks — about half the pre-race volume, easy only, first run on
    the third day after a marathon (R-1), then back to normal with one accent;
    one week at ~70% after a shorter goal (R-10). Strength returns in the second
    week (R-9). Measured first: tools/corpus/post_race_profile.py (three long
    races in the corpus — a weak basis, stated as such). today and why say
    "after the race" instead of "outside the plan", and a new goal set during the
    block starts its cycle after it.
  • A plan without a race (goal.kind: base, until, P-11): base weeks only,
    deload every fourth week, growth to your documented peak and a plateau; no
    taper, no prediction, no race pack.
  • Strength variants and journal: two weeks of getting into it (F-18), then
    heavy sessions, one maintenance session a week in the peak (F-12, F-14);
    trainctl log --strength done|skipped [--minutes] (MCP strength) records a
    session without touching the run entry of the same day; review and today
    show it.
  • Trail results no longer calibrate road zones while a road result exists
    (Z-10); a trail-only calibration is used with a warning.
  • Rules E-2, F-18, P-11, R-8, R-9, R-10 and Z-10 in FOUNDATIONS §10, marked as
    engineering choices where no source exists. The corpus backtest is unchanged
    (volume 1.04, Δ accents 0, Δ sessions 0, tune-ups 6/6).

Docs

  • README command tables list shorten an...
Read more

v0.3.0 — three coaching workflows: shorten, why, review

Choose a tag to compare

@dithiothreitol dithiothreitol released this 21 Oct 20:21

Install: npx trainctl@0.3.0, MCP: npx -y trainctl-mcp@0.3.0. Full history in CHANGELOG.md.

Added — everyday coaching workflows

  • shorten --minutes 40 / trainctl_shorten saves a single-session proposal,
    accounting for preparation, recovery and strength. Reduced quality variants
    preserve pace and bookends; easy replacements explicitly give up the original
    purpose. Approved exceptions survive adaptation and carry their rationale
    when moved. All use the existing proposal ID and expiry protections.
  • why explains the stored session's goal, phase, dose, neighboring demanding
    sessions, execution and time constraints; it identifies manual edits.
  • review --prepare / trainctl_review(prepare=true) combines execution facts
    with a saved diff for approval, or explains why no change can be prepared.
    Seven-day reports cover exactly seven dates; refresh includes the 21-day
    adaptation window. No test result means a request for data, not a timestamp-only
    recalibration patch. CLI, MCP and agent onboarding support both languages.

Fixed — training workflow audit

  • Generated weeks reconcile actual session distances with their budget. Small
    budgets no longer force minimum-size quality sessions; lint reports mileage
    and easy-share deviations instead of suppressing low-volume warnings.
  • Zone-only recalibration preserves approved workout structure and volume.
    Volume changes are anchored in upcoming weeks; accepted baselines are saved
    in the plan instead of replaying progression from its original date.
  • Proposals expire at the next local calendar day. Historical date selection
    cannot bypass protection of past sessions. Manual swaps also respect recorded
    sessions, race dates, pins and time budgets.
  • Race distance is separate from training volume. Training compliance excludes
    both planned and actual races. Unknown race duration is no longer 15 minutes.
  • Hill returns count toward distance and duration. FIT and intervals.icu preserve
    alternating/progression remainders; estimates count the final exported recovery.
  • Conflicting tune-ups are rejected explicitly. Generation respects the preferred
    long-run day; taper carries frequency forward and reports infeasible schedules.
    Full-day blocks also remove strength, with a visible trade-off.
  • log --test-time MM:SS (MCP: testTime) stores the measured segment separately.
    Whole-session time is never suggested as the test result. Synced completed
    tests also trigger a request for their missing result.
  • Input validation rejects non-finite numbers, negative distances, malformed
    times and impossible calendar dates.

Validation: 641 passing tests, including 21 audit regression cases and 35
coaching-workflow regression cases. Type checks, builds and installation of all
five packages verified, including CLI workflows, FIT/mobile export and MCP.

v0.2.0 — reviewed adaptation and time-aware scheduling

Choose a tag to compare

@dithiothreitol dithiothreitol released this 21 Oct 20:21

Install: npx trainctl@0.2.0, MCP: npx -y trainctl-mcp@0.2.0. Full history in CHANGELOG.md.

Reviewed adaptation and time-aware scheduling

  • Execution data now distinguishes unknown from explicitly skipped sessions.
    Pull, review and adaptation share running-only classification and the latest
    journal correction. Shorter sync refreshes retain older history.
  • adapt --prepare saves an inspectable, content-addressed plan proposal;
    adapt --apply <id> applies exactly that proposal and rejects changed inputs
    or edited proposal files. Past, logged, pinned and manually edited days stay
    intact. Applicable patches cover volume and calibration; recovery remains an
    individual coaching decision.
  • reschedule --time YYYY-MM-DD=minutes --pin YYYY-MM-DD --preparation minutes
    honors time budgets including preparation, recoveries and strength. Preview
    exposes alternatives (--strategy long|quality) and dropped sessions.
  • Plans retain calibration inputs and generated-day checksums. why explains
    result selection and rule provenance; excluded/exclusionReason let runners
    retain unsuitable race results without using them for zones or predictions.
  • MCP tools return structured domain data with output schemas and annotations.
  • export --what mobile --date YYYY-MM-DD: standalone responsive workout HTML,
    including light/dark mode, session steps, purpose and expandable reasoning.
  • Fixed new-result detection comparing a result collection against itself,
    cycling counting toward a planned run, and the sync test's dependence on the
    current calendar date. pull --date makes historical sync ranges explicit.

See the workflow guide for examples and boundaries.

Added

  • trainctl log --rpe <1–10> (CLI and the trainctl_log MCP tool): session
    effort on the CR-10 scale, stored in the journal and shown by today. The
    engine only stores and quotes it — it never converts feelings into zones,
    paces or volume (ADR-027; collection is grounded in P-6, the refusal in Z-4).
  • The weekly review has a new section, How it felt: journal entries with an
    RPE or a note from the reviewed window, quoted verbatim (the last entry per
    day wins). No aggregation, no thresholds — the trail is material for a
    conversation with the coach-agent, not input to arithmetic.
  • AGENTS.md grew a debrief ritual (after a logged session, ask how it went
    and record it; when the feeling clashes with the session's role, ask one
    question about context), rule 8 — feelings are for conversation, not
    arithmetic — and an opt-in offer of a scheduled Monday debrief.
  • docs/examples/proactive-review.md: the coach speaks first — a weekly
    check-in from the agent's scheduler or cron, with the consent and
    propose-don't-apply rules spelled out.

v0.1.1 — the packages actually run once installed

Choose a tag to compare

@dithiothreitol dithiothreitol released this 08 Aug 07:08

If you installed 0.1.0, it did not work. This release is the fix.

npx trainctl died on startup with ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING: 0.1.0 published its TypeScript sources with exports and bin pointing at .ts files, and Node deliberately refuses to strip types for anything under node_modules. That works in the repository and nowhere else. Every test ran from the source tree, so nothing caught it until the first npx after publishing.

Fixed

  • Packages ship compiled JavaScript (dist/) with type declarations and source maps, built by pnpm build; the TypeScript sources travel alongside, so a stack trace still lands on readable code. Development is unchanged — the repository still runs straight from TypeScript.
  • Export filenames dropped the Polish ł: interwały became interwa-y.fit, and a race called Bieg Wrocławski produced bieg-wroc-awski.ics. Letters Unicode does not decompose (ł ø đ ß æ œ) are transliterated now.
  • The MCP server reported a hard-coded 0.1.0 in its handshake regardless of the package version. Both binaries read their own manifest.

Added

  • trainctl --version — the bug-report template asked for it before it existed.
  • Two guards so this class of bug cannot ship again: packaging.test.ts asserts the published entry points are built files (and that versions match and descriptions are English), and CI packs all five tarballs, installs them into a clean directory, and runs the CLI and the MCP server from node_modules.

Changed

  • Package descriptions on npm are English; they were Polish in 0.1.0.

0.1.0 is deprecated on npm. Full detail: CHANGELOG.md, and the reasoning is recorded as ADR-026 in SPEC.md.

v0.1.0 — first public release

Choose a tag to compare

@dithiothreitol dithiothreitol released this 07 Aug 21:59

A running coach that lives in your terminal: a plan-generating engine with a CLI and an MCP server. Your training plan is a YAML file in a git repository, every session cites the research behind it, and your agent gets the coach as a tool.

mkdir my-training && cd my-training && git init
npx trainctl init && npx trainctl plan && npx trainctl today

Engine. Macrocycle from base to taper with pyramidal-to-polarised progression; session shapes drawn from a corpus of 50 real coaching plans; zones calibrated from race results, never from a watch's threshold estimate; finish prediction as a range, never a single number; a week re-solver that names the session it sacrifices and why.

Interfaces. 16 CLI commands and 16 MCP tools over the same handlers, so the agent and the terminal cannot disagree. check lints the plan against the engine's invariants and fails a CI pipeline; diff --plan compares two full plans, so "what if I move the race three weeks" is a branch, not a rewrite. English and Polish, both first-class.

Where it refuses. No injury-risk score, no readiness from HRV, no silent edits to your own plan — each refusal documented against the literature in docs/science/FOUNDATIONS.md (~60 sources, rule IDs quoted by trainctl why).

Requires Node ≥ 22.18; there is no build step, so the published package is the source you can read. Architecture and decisions: SPEC.md. Full changelog: CHANGELOG.md.

Known limits are listed in the changelog rather than hidden: activities reaching intervals.icu through Strava carry no data through its API, long runs are always generated easy (71% of the corpus coach's), and the backtest calibrates VDOT to an engineering value rather than the athlete's own results.


Tag note: v0.1.0 was moved once, hours after it was first cut, to include a fix for export filenames dropping the Polish ł (interwa-y.fit → interwaly.fit). Nothing had been published under the tag at that point — the npm packages are not out yet — so the tag now matches exactly what will be published.