@wattsonclub/wattson-cli 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@wattsonclub/wattson-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "private": false,
+  "version": "0.1.0",
+  "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",
+    "skill",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "zod": "^3.25.76",
+    "esbuild": "^0.25.12"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,60 @@
+---
+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.
+
+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; subsequent token refresh is automatic.
+
+Verify `wattson auth status` and `wattson --json athlete profile`. `wattson auth logout` clears local credentials. Do not assume that local logout revokes other sessions. 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 payload structure 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. Fix validation errors before saving. FTP-relative values are fractions: `0.55` means 55%, not `55`.
+
+Only save when the user's task authorizes publishing the workout. 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`.
+
+Legacy CLI `plan schedule`, `session load-workout`, `session adapt` and `session complete` are compatibility APIs, not remote start/control of the current app. Do not synthesize a ride completion. The CLI is not full MCP parity: use MCP for library listing/retirement/calendar scheduling and course discovery/import when those commands are absent from `wattson --help`.
+
+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,375 @@
+> Command examples inherited from the compatibility CLI. Current offline app behavior is described in ../SKILL.md; legacy scheduling/session calls do not remotely control the app.
+
+# Planner CLI examples
+
+This file exists to make the intended agent/operator flow concrete.
+
+Design rule:
+- natural language belongs in the agent layer
+- structured inputs belong in planner-api / planner-cli
+- prefer deterministic request bodies over special `...from-prompt` endpoints
+
+Operator defaults:
+- use `wattson --help` to inspect the live command surface
+- add `--json` when the output is meant for automation or another agent step
+- add `--base-url <url>` when you are pointing at a non-default planner-api instance
+
+## 0. Sanity-check the surface
+
+```bash
+wattson health
+wattson --json health
+wattson --base-url http://192.168.1.50:3000 health
+```
+
+## 1. Recommend a workout for today
+
+```bash
+wattson recommend daily athlete-1 \
+  --available-time-min 20 \
+  --prefer-objective vo2max \
+  --hard-constraint "indoor only"
+```
+
+## 2. Draft a workout from simple flags
+
+```bash
+wattson workout draft athlete-1 \
+  --objective vo2max \
+  --duration-min 20 \
+  --execution-mode erg \
+  --style-hint "3 high intensity intervals"
+```
+
+This is the intended translation pattern for agents:
+
+- user says: `Create me a 20 min session with 3 high intensity intervals`
+- agent infers:
+  - objective: `vo2max`
+  - durationMin: `20`
+  - allowedExecutionModes: `["erg"]`
+  - styleHints: `["3 high intensity intervals"]`
+- agent calls `workout draft`
+
+## 3. Draft a workout from a full JSON body
+
+```bash
+wattson workout draft --input-file /tmp/draft-workout.json
+```
+
+Example `/tmp/draft-workout.json`:
+
+```json
+{
+  "athleteId": "athlete-1",
+  "objective": "vo2max",
+  "durationMin": 20,
+  "constraints": {
+    "allowedExecutionModes": ["erg"],
+    "maxPctFtp": 1.2
+  },
+  "context": {
+    "styleHints": ["3 high intensity intervals"]
+  }
+}
+```
+
+Note:
+- FTP-relative values are fractional in structured payloads
+- `maxPctFtp: 1.2` means `120% FTP`
+- `target: { "mode": "pct_ftp", "value": 0.55 }` means `55% FTP`
+- never pass whole percentages like `120` or `55`
+
+## 4. Revise a workout from a structured patch
+
+```bash
+wattson workout revise --input-file /tmp/revise-workout.json
+```
+
+Example `/tmp/revise-workout.json`:
+
+```json
+{
+  "patch": {
+    "workoutId": "workout-1",
+    "baseVersion": 2,
+    "preserve": ["objective", "interval_structure"],
+    "changes": {
+      "durationDeltaSec": -120,
+      "intensityMultiplier": 0.95,
+      "addCadenceFocus": false,
+      "removeLastInterval": false,
+      "switchToRecovery": false
+    },
+    "naturalLanguage": "Keep the same shape, just make it slightly easier and a bit shorter.",
+    "reason": "Rider requested a lighter version."
+  }
+}
+```
+
+This is the intended translation pattern for agents:
+- user says: `make it slightly easier`
+- agent chooses a structured patch like:
+  - `intensityMultiplier: 0.95`
+  - maybe preserve objective / interval structure
+  - include the original natural-language request as trace context when helpful
+
+## 5. Validate a workout before saving
+
+```bash
+wattson workout validate --input-file /tmp/validate-workout.json
+```
+
+Example `/tmp/validate-workout.json`:
+
+```json
+{
+  "workout": {
+    "id": "workout-1",
+    "version": 2,
+    "createdAt": "2026-04-09T00:00:00.000Z",
+    "updatedAt": "2026-04-09T00:00:00.000Z",
+    "createdBy": { "type": "system", "system": "planner_api" },
+    "updatedBy": { "type": "system", "system": "planner_api" },
+    "kind": "workout_definition",
+    "athleteId": "athlete-1",
+    "title": "VO2 20",
+    "objective": "vo2max",
+    "sport": "cycling_indoor",
+    "status": "draft",
+    "athleteContext": {
+      "ftpWatts": 250,
+      "constraints": []
+    },
+    "blocks": [
+      {
+        "id": "block-1",
+        "type": "steady",
+        "durationSec": 300,
+        "target": { "mode": "pct_ftp", "value": 0.55 },
+        "instructions": ["Warm up"]
+      }
+    ],
+    "constraints": {
+      "allowedExecutionModes": ["erg"]
+    },
+    "rationale": {
+      "summary": "Short VO2-focused session",
+      "whyToday": ["Fits available time"]
+    },
+    "tags": ["vo2", "short"]
+  }
+}
+```
+
+## 6. Save a validated workout
+
+```bash
+wattson workout save --input-file /tmp/save-workout.json
+```
+
+Example `/tmp/save-workout.json`:
+
+```json
+{
+  "workout": {
+    "id": "workout-1",
+    "version": 2,
+    "createdAt": "2026-04-09T00:00:00.000Z",
+    "updatedAt": "2026-04-09T00:00:00.000Z",
+    "createdBy": { "type": "system", "system": "planner_api" },
+    "updatedBy": { "type": "system", "system": "planner_api" },
+    "kind": "workout_definition",
+    "athleteId": "athlete-1",
+    "title": "VO2 20",
+    "objective": "vo2max",
+    "sport": "cycling_indoor",
+    "status": "validated",
+    "athleteContext": {
+      "ftpWatts": 250,
+      "constraints": []
+    },
+    "blocks": [
+      {
+        "id": "block-1",
+        "type": "steady",
+        "durationSec": 300,
+        "target": { "mode": "pct_ftp", "value": 0.55 },
+        "instructions": ["Warm up"]
+      }
+    ],
+    "constraints": {
+      "allowedExecutionModes": ["erg"]
+    },
+    "rationale": {
+      "summary": "Short VO2-focused session",
+      "whyToday": ["Fits available time"]
+    },
+    "tags": ["vo2", "short"]
+  },
+  "expectedValidationStatus": "pass"
+}
+```
+
+The same `%FTP` rule applies here:
+- use fractional values like `0.55` and `1.2`
+- do not send whole percentages like `55` or `120`
+
+## 7. Schedule a saved workout
+
+```bash
+wattson plan schedule athlete-1 \
+  --workout-id workout-1 \
+  --version 2 \
+  --date 2026-04-10
+```
+
+Note:
+- the CLI takes `athleteId` here and hides the current HTTP `planId` convention (`<athleteId>:current-plan`)
+
+## 8. Inspect the compiled runtime plan
+
+```bash
+wattson workout runtime-plan workout-1 --version 2
+```
+
+## 9. Queue the saved workout into an active trainer session
+
+```bash
+wattson session load-workout \
+  --athlete-id athlete-1 \
+  --workout-id workout-1 \
+  --version 2
+```
+
+## 10. Complete a session from simple flags
+
+```bash
+wattson session complete session-123 \
+  --status completed \
+  --completion-kind completed \
+  --elapsed-sec 1200 \
+  --completed-duration-sec 1200 \
+  --compliance-pct 98 \
+  --note "Strong finish"
+```
+
+## 11. Complete a session from a structured JSON body
+
+```bash
+wattson session complete session-123 --input-file /tmp/complete-session.json
+```
+
+Example `/tmp/complete-session.json`:
+
+```json
+{
+  "status": "completed",
+  "completionKind": "completed",
+  "startedAt": "2026-04-09T10:00:00.000Z",
+  "endedAt": "2026-04-09T10:20:00.000Z",
+  "executionMode": "erg",
+  "liveSummary": {
+    "elapsedSec": 1200
+  },
+  "actualMetrics": {
+    "avgPower": 245,
+    "avgHrBpm": 158,
+    "maxHrBpm": 173,
+    "compliancePct": 98,
+    "completedDurationSec": 1200,
+    "completedTss": 42
+  },
+  "notes": ["Strong finish"]
+}
+```
+
+## 12. Apply a bounded live adaptation
+
+```bash
+wattson session adapt session-123 \
+  --op skip_interval \
+  --reason "Rider requested it" \
+  --payload-json '{"stepIndex":2}'
+```
+
+Allowed live ops today:
+- `reduce_intensity`
+- `increase_intensity`
+- `extend_recovery`
+- `skip_interval`
+- `shorten_workout`
+- `switch_execution_mode`
+
+That means:
+- `skip the next interval` -> yes, good fit
+- `make it a bit easier` -> yes, good fit
+- `add another interval` -> not yet a first-class live op; that would need a richer structural adaptation model later
+
+## 13. Inspect the summary after completion
+
+```bash
+wattson session summary session-123
+```
+
+## 14. Inspect canonical telemetry after completion
+
+```bash
+wattson session telemetry session-123
+wattson --json session telemetry session-123
+```
+
+If no telemetry has been persisted yet, JSON mode returns:
+
+```json
+{
+  "telemetry": null
+}
+```
+
+## 15. Inspect persisted artifact metadata
+
+```bash
+wattson session artifacts session-123
+wattson --json session artifacts session-123
+```
+
+Use this when you want artifact state/metadata without pulling inline FIT base64 content.
+
+## 16. Fetch the deterministic FIT export
+
+```bash
+wattson session fit session-123
+wattson --json session fit session-123 > /tmp/session-fit.json
+```
+
+Important:
+- `session fit` returns inline `contentBase64`
+- `session artifacts` is usually the better inspection command when you only need status/metadata
+
+## 17. Enqueue or retry Strava sync
+
+```bash
+wattson session strava-sync session-123
+wattson --json session strava-sync session-123
+```
+
+Important:
+- this corresponds to an async backend operation
+- the underlying HTTP route returns `202 Accepted`
+- use `session artifacts`, `session fit`, or later session reads to inspect the resulting state
+
+## A practical agent loop
+
+A practical agent should usually do this:
+
+1. interpret the user request
+2. choose the smallest structured planner action that matches it
+3. keep natural language as context / rationale, not as the API contract itself
+4. validate before saving when changing workout structure
+5. ingest final session completion once the ride is done
+6. inspect telemetry / artifacts / FIT / Strava sync state after completion when durability matters
+7. use bounded live adaptation ops during an active session
+
+The planner API should stay structured.
+The agent should do the interpretation.