@wattsonclub/wattson-cli 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@wattsonclub/wattson-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "private": false,
+  "version": "0.1.1",
+  "type": "module",
+  "bin": {
+    "wattson": "./dist/bin.js",
+    "trainer-planner": "./dist/bin.js"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "build": "node build.mjs",
+    "prepack": "npm run build"
+  },
+  "description": "Wattson training planner CLI",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist/bin.js",
+    "dist/bin.js.LEGAL.txt",
+    "dist/THIRD-PARTY-NOTICES.txt",
+    "skill/SKILL.md",
+    "skill/references/commands.md",
+    "skill/references/workout-building-blocks.md",
+    "skill/references/workout-text-format.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "zod": "^3.25.76",
+    "esbuild": "^0.25.12"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: wattson
+description: Use the Wattson CLI to authenticate a local or remote agent, inspect athlete profiles and uploaded rides, and draft, validate and save structured cycling workouts. Use for terminal automation with Wattson, not remote control of an offline ride.
+---
+
+# Wattson
+
+## 1. Install and inspect
+
+Requires Node.js 22 or newer. Install `npm install -g @wattsonclub/wattson-cli`, then run `wattson --help`. Use the commands advertised by the installed version; do not invent MCP-equivalent commands.
+
+Human guide: [wattson.club/cli](https://wattson.club/cli). Agent discovery: [llms.txt](https://wattson.club/llms.txt). Full supported command families and copyable payload transformations: [commands](references/commands.md).
+
+The default API is `https://api.wattson.club`. Override with `--base-url`, `WATTSON_API_BASE_URL` or legacy `PLANNER_API_BASE_URL` only for an explicitly chosen environment. Confirm `wattson health` succeeds before continuing.
+
+## 2. Authenticate
+
+Run `wattson auth status` (exit 1 means signed out, including with `--json`). If not signed in:
+
+- On the user's own computer: `wattson auth login` opens browser OAuth with a localhost callback.
+- On an SSH host, server, container, or agent runtime: `wattson auth login --remote` prints a verification URL and a short-lived user code and waits for approval. The user opens that URL on their own phone/laptop, signs in, checks the code and explicitly approves. No inbound port or SSH tunnel is needed.
+
+Deliver login URLs and codes privately to the requesting user, never in a shared group. Never request their password, copy browser cookies, approve on their behalf, or expose access/refresh tokens. A timeout or denial means not authenticated; start a new login only at the user's request. For an unattended agent, complete the initial approval interactively; both flows request `planner:read planner:write`. Subsequent API requests automatically refresh and retry once on HTTP 401; a failed refresh-token request clears saved login. `--timeout <seconds>` overrides the five-minute login timeout.
+
+Verify `wattson auth status` and `wattson --json athlete profile`. `wattson auth logout` attempts server logout, ignores server errors, then removes local credentials. It does not guarantee OAuth-token revocation or logout of other sessions. Tokens are unencrypted in a file with mode `0600` (new parent directory `0700`); JSON auth output omits tokens but includes identity metadata. See the reference for paths and overrides. Keep the credential directory persistent and private for containers; do not bake credentials into an image.
+
+## 3. Inspect before changing
+
+Use `--json` for machine consumption and check exit status. Login instructions are interactive information, not a successful login result.
+
+```sh
+wattson --json athlete profile
+wattson --json athlete readiness latest
+wattson --json athlete sessions --limit 10
+wattson --json workout get WORKOUT_ID --version 1
+wattson --json workout revisions WORKOUT_ID
+wattson --json session summary SESSION_ID
+```
+
+Omit athlete IDs to use the authenticated athlete. Do not infer permission to access someone else's athlete ID.
+
+## 4. Draft, validate, save
+
+Translate natural language into structured inputs. Read [workout building blocks](references/workout-building-blocks.md) for the complete field/primitive reference, exact composition examples, constraints and revision options, and [workout text format](references/workout-text-format.md) for readable previews.
+
+```sh
+wattson --json workout draft --objective vo2max --duration-min 20 --execution-mode erg --style-hint "3 hard intervals"
+wattson --json workout validate --input-file validate.json
+wattson --json workout save --input-file save.json
+```
+
+Draft output is not a save request: construct the appropriate payload described in [command examples](references/commands.md). A draft alone is not published. Inspect `validation.status`: validation can exit 0 even for `fail`. Fix failures and review warnings before saving; the reference example requires `pass`. FTP-relative values are fractions: `0.55` means 55%, not `55`.
+
+Only save when the user's task authorizes adding or updating the workout in their library. After saving, verify the returned workout ID/version with `workout get`. Report “saved to your library, ready for the app to download,” not confirmed device delivery. Revisions require validation and save too.
+
+## 5. Respect the offline ride model
+
+The rider's app downloads saved workouts and runs the selected ride locally. A suspended/offline app syncs when it returns online. Uploaded rides can then be reviewed with `athlete sessions`, `session summary`, `session telemetry` and `session artifacts`. FIT export returns inline base64, not a downloaded file. Enqueue/retry `session strava-sync` only when the user authorizes Strava publication; acceptance is asynchronous, not delivery confirmation.
+
+Use `workout list`, `workout schedule ID --date YYYY-MM-DD`, `workout unschedule ID`, and `workout retire ID` for library management. Strava routes and starred segments can be listed and imported as courses (see reference). The former Today-plan and session load/adapt/complete commands have been removed. Do not synthesize ride completion. The CLI also exposes MCP-equivalent sharing, course discovery, onboarding and research operations. Use the command reference to translate a tool call; preserve its input fields and inspect the same response. A server restriction (such as limited Strava access) applies regardless of interface.
+
+Finish by verifying the affected read endpoint and summarizing the result. Distinguish a successful local command from device acknowledgement or Strava delivery.

package/skill/references/commands.md

@@ -0,0 +1,280 @@
+# Wattson CLI command reference
+
+Current offline workout/ride workflow. [Human guide](https://wattson.club/cli) · [Agent discovery](https://wattson.club/llms.txt).
+
+## Install and authenticate
+
+Requires Node.js 22+. Shell examples use Bash; JSON transformations require `jq`.
+
+```bash
+npm install -g @wattsonclub/wattson-cli
+wattson --help
+wattson health
+wattson auth login
+# Alternatively, on SSH/server/container/agent runtime:
+wattson auth login --remote
+wattson --json auth status
+wattson --json athlete profile
+```
+
+Choose one login flow. Local login uses OAuth authorization code + PKCE and browser callback `http://127.0.0.1:8976/oauth/callback`. Remote login uses device authorization: verification URL and short-lived code appear on stderr; the CLI waits for approval on the user's phone/computer. No inbound port or SSH tunnel is required. Both request `planner:read planner:write`; there is no scope-selection flag. `--timeout SECONDS` overrides the five-minute wait (remote authorization may expire sooner). Denial/timeout is not authentication. Deliver URLs/codes privately to the requester; never approve on their behalf, request passwords, or copy cookies/tokens.
+
+API requests refresh on HTTP 401 and retry once, persisting replacement credentials. A failed refresh-token request removes saved state and requires login again. `auth status` checks authenticated bootstrap; signed-out status exits 1, including JSON mode. JSON auth output excludes tokens but includes identity metadata.
+
+Credentials are unencrypted JSON, written atomically with file mode `0600`; newly created parent directories use `0700`. Unix default: `$XDG_STATE_HOME/trainer-planner/auth.json` or `~/.local/state/trainer-planner/auth.json`. Windows: `%LOCALAPPDATA%/trainer-planner/auth.json`, falling back under the user's AppData/Local. `WATTSON_AUTH_FILE`, then legacy `PLANNER_CLI_AUTH_FILE`, override the path. Keep it private and persistent; do not print/commit credentials or bake them into images. Stored credentials are matched to the API base URL.
+
+`wattson auth logout` attempts `/auth/logout` with saved refresh token and bearer credentials, then deletes the local file even if the server call fails. This is **not** a guarantee of OAuth-token revocation or logout of other sessions.
+
+## Global behavior and supported families
+
+Use `wattson [--base-url URL] [--json] COMMAND`. API precedence: `--base-url`, `WATTSON_API_BASE_URL`, legacy `PLANNER_API_BASE_URL`, default `https://api.wattson.club`. Override only for an intentionally selected environment. Omit optional athlete IDs for the signed-in athlete; explicit IDs are not permission to access others.
+
+`--json` returns the API response, not a universal wrapper. Errors go to stderr; check exit codes. Successful transport for `workout validate` can exit 0 with `validation.status: "fail"`.
+
+| Family | Supported commands |
+| --- | --- |
+| Auth | `auth login [--remote] [--timeout SECONDS]`, `auth status`, `auth logout` |
+| Service | `health` |
+| Athlete | `athlete profile [athleteId]`, `athlete readiness latest [athleteId] [--as-of ISO]`, `athlete sessions [athleteId] [--from DATE] [--to DATE] [--limit N]` |
+| Recommendation | `recommend daily [athleteId] --available-time-min N [--date DATE] [--prefer-objective OBJECTIVE] [--hard-constraint TEXT ...]` |
+| Authoring | `workout draft`, `workout revise`, `workout validate`, `workout save` (below) |
+| Workout reads | `workout get ID [--version N]`, `workout revisions ID`, `workout runtime-plan ID --version N` |
+| Ride reads/exports | `session summary ID`, `session telemetry ID`, `session artifacts ID`, `session fit ID` |
+| External publication | `session strava-sync ID` (authorized, asynchronous) |
+| Library/calendar | `workout list [athleteId] [--limit N]`, `workout schedule ID --date YYYY-MM-DD`, `workout unschedule ID`, `workout retire ID` |
+| Courses/discovery/sharing/research | See the full MCP mapping below; structured operations accept `--input-file PATH` or `--input-json JSON`. |
+
+The CLI covers the current MCP action and research tools. Strava account connection remains in the app, not in either tool surface. Strava availability depends on server access mode. Course imports return a course profile; they do not save or schedule a workout.
+
+## Inspect, draft, validate, save, verify
+
+Read profile/readiness before choosing targets. Recommendations are advice, not saved workouts.
+
+```bash
+wattson --json athlete profile
+wattson --json athlete readiness latest
+wattson --json recommend daily --available-time-min 20 --prefer-objective vo2max
+```
+
+Run in a private working directory, signed in, for a request authorizing library creation. This sequence stops on errors and requires validation `pass` before constructing the save request. Review the draft and validation issues before the save step.
+
+```bash
+set -euo pipefail
+umask 077
+wattson --json workout draft --objective vo2max --duration-min 20 --execution-mode erg --style-hint "3 hard intervals" > draft.json
+# Draft output: {workout, validationPreview?}. Validate input: {workout}.
+jq -e '{workout: .workout} | select(.workout != null)' draft.json > validate.json
+wattson --json workout validate --input-file validate.json > validation.json
+jq -e '.validation.status == "pass"' validation.json >/dev/null
+# Validation output has no workout. Preserve the original definition.
+jq -e '{workout: .workout, expectedValidationStatus: "pass"}' validate.json > save.json
+wattson --json workout save --input-file save.json > saved.json
+workout_id=$(jq -er '.workoutId' saved.json)
+workout_version=$(jq -er '.version' saved.json)
+wattson --json workout get "$workout_id" --version "$workout_version"
+wattson --json workout runtime-plan "$workout_id" --version "$workout_version"
+```
+
+For `warn`, review the issues and deliberately use the observed expected status only if acceptable; for `fail`, fix and revalidate. Never merely relabel a workout as validated. Save recomputes validation: `expectedValidationStatus` is a conflict guard. Passing saves persist as `validated` even if input status was `draft`. Save returns `{workoutId, version, status}`, not `{workout}`.
+
+Draft flags also support repeatable `--execution-mode` and `--style-hint`, `--max-pct-ftp`, and `--readiness-snapshot-id`. Structured draft/revise/validate/save input uses **one** of `--input-file` or `--input-json`:
+
+```bash
+wattson --json workout draft --input-json '{"objective":"vo2max","durationMin":20,"constraints":{"allowedExecutionModes":["erg"],"maxPctFtp":1.2},"context":{"styleHints":["3 hard intervals"]}}'
+```
+
+Signed-in structured drafts may omit `athleteId`. FTP values are fractions: `1.2` = 120%, `0.55` = 55%. See [building blocks](workout-building-blocks.md) and [workout text](workout-text-format.md). Preserve returned IDs, version, attribution, athlete context and blocks; don't invent a partial workout definition.
+
+### Revise a saved version
+
+Using `saved.json` above, only for an authorized edit (retain `set -euo pipefail`):
+
+```bash
+jq '{patch: {workoutId: .workoutId, baseVersion: .version, preserve: ["objective", "interval_structure"], changes: {intensityMultiplier: 0.95}, reason: "Rider requested a slightly easier version."}}' saved.json > revise.json
+wattson --json workout revise --input-file revise.json > revised.json
+jq -e '{workout: .workout} | select(.workout != null)' revised.json > validate.json
+wattson --json workout validate --input-file validate.json > validation.json
+jq -e '.validation.status == "pass"' validation.json >/dev/null
+jq --slurpfile prior saved.json '{workout: .workout, expectedValidationStatus: "pass", expectedLatestVersion: $prior[0].version}' validate.json > save.json
+wattson --json workout save --input-file save.json > revised-saved.json
+wattson --json workout get "$(jq -er '.workoutId' revised-saved.json)" --version "$(jq -er '.version' revised-saved.json)"
+wattson --json workout revisions "$(jq -er '.workoutId' revised-saved.json)"
+```
+
+`revise` returns `{workout, diff}`; it does not save. `expectedLatestVersion` guards concurrent edits; on conflict, fetch latest and reconsider. Other patch changes: `newTitle`, `newObjective`, `durationDeltaSec`, `addCadenceFocus`, `removeLastInterval`, `switchToRecovery`. Translate natural language into structured intent.
+
+## Offline app and uploaded rides
+
+Report **saved to your library, ready for the app to download**. The app downloads workouts; the rider selects and executes them locally. A suspended/offline app syncs when online again. CLI success is not device acknowledgement, ride start or completion. Never fabricate a session to make a workflow look finished.
+
+```bash
+wattson --json athlete sessions --limit 10
+# Replace SESSION_ID with a real uploaded session ID.
+wattson --json session summary SESSION_ID
+wattson --json session telemetry SESSION_ID
+wattson --json session artifacts SESSION_ID
+```
+
+Telemetry can be `{ "telemetry": null }` when not persisted. Artifacts returns metadata without inline FIT bytes. Treat ride/health data as private; retrieve/export within the user's request.
+
+### FIT export
+
+`session fit` returns `fitFile` with inline `contentBase64`, filename, MIME type, byte count and SHA-256. It does not write a FIT file. If export is requested:
+
+```bash
+wattson --json session fit SESSION_ID > session-fit.json
+node --input-type=module <<'NODE'
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+const { fitFile } = JSON.parse(readFileSync('session-fit.json', 'utf8'));
+const bytes = Buffer.from(fitFile.contentBase64, 'base64');
+if (bytes.length !== fitFile.sizeBytes || createHash('sha256').update(bytes).digest('hex') !== fitFile.checksumSha256.toLowerCase()) {
+  throw new Error('FIT size/checksum mismatch');
+}
+writeFileSync('ride.fit', bytes, { mode: 0o600, flag: 'wx' });
+NODE
+```
+
+### Strava publication/retry — only when authorized
+
+```bash
+wattson --json session strava-sync SESSION_ID
+wattson --json session summary SESSION_ID
+wattson --json session artifacts SESSION_ID
+```
+
+This enqueues/retries an asynchronous backend operation (HTTP 202). It requires the relevant Strava connection; the CLI has no account-connect command. Inspect `session.externalSync.strava` on later session summaries for status, activity URL or errors. Report pending until the backend confirms delivery; FIT export or HTTP 202 is not proof of Strava publication. Avoid tight polling.
+
+## Library calendar and courses
+
+```bash
+wattson --json workout list --limit 20
+wattson workout schedule WORKOUT_ID --date 2026-11-13
+wattson workout unschedule WORKOUT_ID
+wattson workout retire WORKOUT_ID
+wattson strava routes --limit 20
+wattson strava starred-segments --limit 20
+wattson course import-strava-route --input-json '{"route":"123456"}'
+wattson course import-strava-segment --input-json '{"segment":"629046"}'
+```
+
+Scheduling sets the library workout's calendar date, not a legacy plan slot or remote start. Unscheduling clears that date; retirement removes the workout from the downloadable library. Verify with `workout get` and `workout list`. Course imports also accept `effortPctFtp` as a fraction.
+
+## Removed commands
+
+`plan current`, `plan schedule`, `runtime-plan today`, `session load-workout`, `session adapt`, and `session complete` are no longer CLI commands. Their backend compatibility routes are not the current app workflow. Use library scheduling and uploaded-ride reads instead; do not synthesize a ride completion.
+
+Finish with an affected read endpoint; distinguish server persistence, app synchronization, recorded riding and external publication.
+
+
+## MCP and CLI interchangeability
+
+Use the same authenticated account and API environment for equivalent results. The CLI calls the same backend through the typed client; it does not require an MCP server process. Local/internal athlete-ID inputs do not grant access to other accounts. Server/provider access restrictions still apply.
+
+```bash
+wattson --json tool list
+wattson --json tool schema draft_workout
+wattson --json tool schema validate_workout
+wattson --json tool schema generate_terrain_course
+# Same payload as the MCP tool, same result data:
+wattson --json tool draft_workout --input-json '{"objective":"endurance","durationMin":30}'
+```
+
+`tool TOOL_NAME --input-json JSON` (or `--input-file PATH`) accepts the corresponding MCP input envelope. `tool schema TOOL_NAME` describes fields, types, defaults and constraints; invocation also enforces contract refinements. Inspect the installed version rather than guessing a flag. The normal CLI commands remain available for humans.
+
+| MCP tool | CLI command |
+| --- | --- |
+| `list_saved_workouts` | `workout list` |
+| `health` | `health` |
+| `get_athlete_profile` | `athlete profile` |
+| `get_readiness_snapshot` | `athlete readiness latest` |
+| `get_recent_sessions` | `athlete sessions` |
+| `get_saved_workout` | `workout get` |
+| `get_workout_runtime_plan` | `workout runtime-plan` |
+| `list_saved_workout_revisions` | `workout revisions` |
+| `summarize_session` | `session summary` |
+| `get_session_telemetry` | `session telemetry` |
+| `get_session_artifacts` | `session artifacts` |
+| `get_session_fit_export` | `session fit` |
+| `lookup_climb` | `course lookup` |
+| `find_my_strava_segments` | `strava find-segments` |
+| `import_strava_segment` | `course import-strava-segment` |
+| `import_gpx_course` | `course import-gpx` |
+| `generate_terrain_course` | `course generate-terrain` |
+| `import_strava_activity_course` | `course import-strava-activity` |
+| `build_road_course` | `course build-road` |
+| `import_climb_page` | `course import-climb-page` |
+| `get_my_climb_history` | `course history` |
+| `explore_strava_segments` | `strava explore` |
+| `get_my_strava_segment_efforts` | `strava segment-efforts` |
+| `list_my_strava_starred_segments` | `strava starred-segments` |
+| `list_my_favourite_strava_climbs` | `strava favourite-climbs` |
+| `recommend_first_workout` | `recommend first` |
+| `list_my_strava_routes` | `strava routes` |
+| `import_strava_route` | `course import-strava-route` |
+| `draft_workout` | `workout draft` |
+| `revise_workout` | `workout revise` |
+| `validate_workout` | `workout validate` |
+| `save_workout` | `workout save` |
+| `schedule_saved_workout` | `workout schedule` |
+| `retire_saved_workout` | `workout retire` |
+| `trigger_session_strava_sync` | `session strava-sync` |
+| `create_workout_share` | `share create` |
+| `preview_workout_share` | `share preview` |
+| `import_workout_share` | `share import` |
+| `search` | `research search` |
+| `fetch` | `research fetch` |
+
+For new course/discovery/sharing/recommendation commands, schema field names map to kebab-case flags (`effortPctFtp` → `--effort-pct-ftp`). Nested fields use dots (`--answers.ideal-minutes 30`); objects/arrays can be JSON. Booleans take explicit `true`/`false`. Do not combine `--input-json`/`--input-file` with field flags. Existing convenience commands keep their documented flags (for example, `workout get --version`); use generic `tool` invocation for a literal MCP payload.
+
+### Sharing: create, preview, import
+
+```bash
+wattson --json share create --input-json '{"workoutId":"WORKOUT_ID","workoutVersion":1}' > share.json
+share_id=$(jq -er '.shareId' share.json)
+wattson --json share preview "$share_id" > preview.json
+# Only when the user wants to add the shared workout to their own library:
+wattson --json share import "$share_id" > imported.json
+wattson --json workout list
+```
+
+Creation returns `{shareId,url}` for an owned, saved revision. Share IDs are UUIDs, not arbitrary URLs. Sharing exposes a sanitized template (title, objective, blocks, constraints), not the owner's profile, rationale, schedule or ride history. Block instructions are shared: don't put private notes there if sharing the workout. Anyone with the link can access the public preview. Authenticated preview returns `{item}` with recipient-adjusted artifacts and does **not** save. Import returns `{item,alreadyImported}`; repeated imports may reuse an existing copy. It does not start or schedule a ride.
+
+### All course sources and discovery
+
+```bash
+wattson --json course lookup "Ventoux" --limit 3
+wattson --json course generate-terrain --input-json '{"distanceM":5000,"averageGradePct":5,"shape":"hairpins","seed":7}'
+wattson --json course import-gpx --gpx-file route.gpx --name "My climb"
+wattson --json course build-road --input-json '{"start":{"place":"Bédoin, France"},"end":{"place":"Mont Ventoux, France"}}'
+wattson --json course import-climb-page --input-json '{"url":"https://climbfinder.com/en/climbs/mont-ventoux-bedoin"}'
+wattson --json course history --limit 20
+wattson --json strava find-segments "Collserola" --limit 5
+wattson --json strava explore --input-json '{"place":"Girona","radiusKm":10}'
+wattson --json strava segment-efforts "629046" --limit 10
+wattson --json strava favourite-climbs --limit 3 --recent-rides 6
+wattson --json course import-strava-activity --input-json '{"activity":"123456","startDistanceM":1000,"endDistanceM":6000}'
+```
+
+Replace example Strava IDs with real accessible items. Course sources return profiles; compose a `climb` block from the returned `course`, allow grade execution, then validate/save the workout. Lookup returns a `climbs` array instead of one top-level `course`. GPX takes exactly one of text or a public GPX URL; `--gpx-file` reads local text. Strava activity imports are limited to the rider's own rides. Use `tool schema` for every optional field, bound and default; the [authoring reference](workout-building-blocks.md) explains course embedding, pacing estimates and runtime completion.
+
+Limited Strava mode still permits segment import, name matching against starred segments, and ride upload/retry; it restricts other Strava reads. Changing interfaces does not bypass that policy. Lookup, GPX, terrain, road and supported climb pages are alternatives without those Strava reads.
+
+### First-workout recommendations
+
+```bash
+wattson --json recommend first --input-json '{"answers":{"idealMinutes":30,"maxMinutes":45,"goal":"fitness","freshness":"normal"},"useStrava":false}' > first.json
+jq '{workout:.draft.workout}' first.json > validate.json
+wattson --json workout validate --input-file validate.json
+```
+
+This returns a draft and rationale, not a saved workout. Its definition is at `.draft.workout`, unlike `workout draft`'s `.workout`. Continue the same reviewed validate/save flow above. Use `tool schema recommend_first_workout` for questionnaire choices and all optional answers. Unknown FTP stays omitted; never invent one. `recommend daily` is a separate legacy advisory helper, not this onboarding operation or a saved plan.
+
+### Research search and fetch
+
+```bash
+wattson --json research search "threshold"
+wattson --json research fetch "DOCUMENT_ID_FROM_SEARCH"
+```
+
+These use the same profile/saved-workout/uploaded-ride corpus, ranking and document handles as MCP research. They are not web search. Fetch a returned handle rather than constructing IDs. The output may contain the signed-in athlete's private training data.