@dataworks-technology/cli 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dataworks-technology/cli",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "The official command-line interface for the Dataworks Data Engine",
   "type": "module",
   "license": "MIT",
@@ -11,12 +11,16 @@
   "homepage": "https://github.com/Dataworks-Technology/Dataworks-CLI#readme",
   "bugs": "https://github.com/Dataworks-Technology/Dataworks-CLI/issues",
   "bin": {
-    "dw": "./bin/run.js"
+    "dw": "./bin/run.js",
+    "dw-mcp": "./bin/mcp.js"
   },
   "files": [
     ".github/.assets",
+    ".agents/plugins/marketplace.json",
+    ".claude-plugin/marketplace.json",
     "bin",
     "dist",
+    "plugins",
     "schema",
     "skills",
     "oclif.manifest.json",
@@ -27,21 +31,25 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "bun run generate && tsc -p tsconfig.build.json && node node_modules/oclif/bin/run.js manifest",
+    "build": "bun run sync:plugin-version && bun run generate && tsc -p tsconfig.build.json && node node_modules/oclif/bin/run.js manifest",
     "commands": "node ./bin/run.js commands --json",
     "dev": "node --import tsx ./bin/dev.js",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "generate": "bun scripts/generate-commands.ts",
-    "generate:check": "bun scripts/generate-commands.ts --check",
+    "generate": "bun scripts/generate-commands.ts && bun scripts/generate-metrics.ts",
+    "generate:check": "bun scripts/generate-commands.ts --check && bun scripts/generate-metrics.ts --check",
     "lint": "tsc --noEmit",
-    "typecheck": "tsc --noEmit",
     "maintain:sdk": "bun scripts/maintenance/update-sdk.ts",
+    "postinstall": "node ./bin/postinstall.js",
+    "preinstall": "if [ -f scripts/get-sdk-authtoken.ts ]; then bun scripts/get-sdk-authtoken.ts ./; fi",
     "prepack": "bun run build && bun run test",
     "prepare": "husky",
+    "sdk": "bun scripts/get-sdk-authtoken.ts ./",
     "smoke:litellm": "bun scripts/maintenance/smoke-agent.ts",
+    "sync:plugin-version": "bun scripts/sync-plugin-version.ts",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
   },
   "oclif": {
     "bin": "dw",
@@ -50,6 +58,9 @@
     "helpClass": "./dist/help.js",
     "topicSeparator": " ",
     "topics": {
+      "agents": {
+        "description": "Install Dataworks skills and tools for supported AI coding agents"
+      },
       "tenant": {
         "description": "List available tenants or select the tenant used by subsequent commands"
       }
@@ -64,15 +75,18 @@
   "dependencies": {
     "@apollo/client": "4.2.1",
     "@dataworks-technology/data": "0.6.1",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "@napi-rs/keyring": "1.3.0",
     "@oclif/core": "4.13.3",
     "@oclif/plugin-autocomplete": "3.2.50",
     "aws-appsync-subscription-link": "4.0.3",
-    "graphql": "16.14.1"
+    "graphql": "16.14.1",
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@commitlint/cli": "19.8.1",
     "@commitlint/config-conventional": "19.8.1",
+    "@dataworks/sdk": "3.5.0",
     "@types/node": "22.18.0",
     "husky": "9.1.7",
     "lint-staged": "16.1.5",

package/plugins/dataworks/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "dataworks",
+  "version": "1.4.0",
+  "description": "Query athlete metrics from Dataworks using the authenticated local CLI session.",
+  "author": { "name": "Dataworks Technology" },
+  "homepage": "https://github.com/Dataworks-Technology/Dataworks-CLI",
+  "repository": "https://github.com/Dataworks-Technology/Dataworks-CLI",
+  "license": "MIT",
+  "keywords": ["dataworks", "metrics", "sport", "data-explorer"]
+}

package/plugins/dataworks/.codex-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "name": "dataworks",
+  "version": "1.4.0",
+  "description": "Query athlete metrics from Dataworks using the authenticated local CLI session.",
+  "author": { "name": "Dataworks Technology", "url": "https://dataworks.live/" },
+  "homepage": "https://github.com/Dataworks-Technology/Dataworks-CLI",
+  "repository": "https://github.com/Dataworks-Technology/Dataworks-CLI",
+  "license": "MIT",
+  "keywords": ["dataworks", "metrics", "sport", "data-explorer"],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Dataworks",
+    "shortDescription": "Query athlete metrics safely",
+    "longDescription": "Resolve athletes and return normalized GPS, heart-rate, and other Dataworks metric values through one read-only tool.",
+    "developerName": "Dataworks Technology",
+    "category": "Data",
+    "capabilities": ["Read"],
+    "websiteURL": "https://dataworks.live/",
+    "defaultPrompt": [
+      "Give me the last 30 GPS values for James Haigh",
+      "Show the latest heart rate for athlete ID X",
+      "Query speed values for this athlete since noon"
+    ],
+    "brandColor": "#111827"
+  }
+}

package/plugins/dataworks/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "dataworks": {
+      "command": "dw-mcp",
+      "args": []
+    }
+  }
+}

package/plugins/dataworks/skills/query-dataworks-metrics/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: query-dataworks-metrics
+description: Query historical Dataworks athlete metrics such as GPS, heart rate, speed, altitude, cadence, power, timing, or custom metrics. Use when a user asks for latest, last, recent, or time-bounded metric values for an athlete by ID or name.
+---
+
+# Query Dataworks metrics
+
+Use the `query_metrics` tool. It is read-only and uses the current authenticated
+`dw` session and selected tenant.
+
+If `query_metrics` is unavailable, tell the user to run `dw agents install`
+once in their terminal, then start a new Codex thread or run `/reload-plugins`
+in Claude Code. Do not substitute raw GraphQL or guess that setup succeeded.
+
+## Construct the request
+
+- Pass `athlete_id` when the user provides a Dataworks athlete public ID.
+- Otherwise pass `athlete_name`; let the tool resolve it and surface ambiguity.
+- Map the user's wording onto a canonical metric name from the catalogue below.
+  Case, spaces, hyphens and underscores are ignored, so "Heart Rate" resolves to
+  `heartrate`. Do not invent a metric name.
+- Default to `limit: 30` and `order: newest` only when the user did not specify
+  a count or order.
+- Preserve explicit `from` and `to` times as ISO 8601 date-times.
+- Pass `event_id`, `dataset_datasource_id`, or `tenant_id` only when explicitly
+  supplied or already resolved. Never guess an ID.
+- For a genuinely custom metric absent from the catalogue, pass its exact name
+  and an explicit `metric_category`.
+
+## Metric catalogue
+
+Canonical names, grouped by Data Explorer category. This list is generated from
+`@dataworks/sdk`, the same source the Console's Data Explorer uses.
+
+<!-- generated:metrics start -->
+
+- **METRICS_TYPE_A** — `latlong`, `net-time`, `checkpoint-time`, `leg-time`, `sub-time`, `checkpoint`, `segment`, `distance`, `distance-swim`, `distance-bike`, `distance-run`, `lap`, `sector`, `status`, `is-drafting`, `total-drafting-seconds`, `heading-degrees`, `yoyo-count`
+- **METRICS_TYPE_B** — `speed`, `location-speed`, `altitude`, `cadence-cycling`, `cadence`, `active-energy-burned`, `horizontal-accuracy`, `gap-to-leader`, `gap-to-ahead`, `time-to-leader`, `rank`, `speed-bike`, `pace`, `pace-swim`, `pace-run`
+- **METRICS_TYPE_C** — `heartrate`, `power`, `power-cycling`, `pwr_instant`
+<!-- generated:metrics end -->
+
+Aliases also accepted: `gps`/`location`/`position` → `latlong`;
+`hr`/`bpm`/`pulse` → `heartrate`; `watts` → `power`; `rpm` → `cadence`;
+`elevation` → `altitude`; `calories` → `active-energy-burned`;
+`placing` → `rank`.
+
+There is no `timing` metric — use `net-time`, `checkpoint-time`, `leg-time`, or
+`sub-time`.
+
+Examples:
+
+- “Give me the last 30 GPS values for James Haigh” → `athlete_name: "James
+Haigh"`, `metric: "GPS"`, `limit: 30`, `order: "newest"`.
+- “Tell me James Haigh's maximum heart rate” → `athlete_name: "James Haigh"`,
+  `metric: "heartrate"`, then take the maximum over the returned rows.
+- “Cadence for Sam since noon” → `athlete_name: "Sam"`, `metric: "cadence"`,
+  `from: <the unambiguous ISO 8601 time requested>`.
+
+## Handle results
+
+Use `structuredContent`, not the human summary. Report the resolved athlete ID,
+environment, tenant, canonical metric, order, and returned count. GPS rows include
+decoded `position.latitude` and `position.longitude`; heart-rate values are
+numeric with unit `bpm` when the source value is valid.
+
+If the tool reports `ATHLETE_AMBIGUOUS`, present its candidates and ask the user
+to choose. For `AUTH_REQUIRED` or `TENANT_REQUIRED`, follow the recovery command
+in the error and retry. For `METRIC_CATEGORY_REQUIRED`, the error's `suggestions`
+list the closest canonical names — retry with one rather than asking the user to
+spell the metric. Never expose credentials or session material.

package/plugins/dataworks/skills/query-dataworks-metrics/agents/openai.yaml

@@ -0,0 +1,13 @@
+interface:
+  display_name: "Query Dataworks metrics"
+  short_description: "Query athlete metrics by name or ID"
+  default_prompt: "Use $query-dataworks-metrics to give me the last 30 GPS values for James Haigh."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "dataworks"
+      description: "Read-only Dataworks metric query server"
+
+policy:
+  allow_implicit_invocation: true

package/skills/dataworks-cli/SKILL.md

@@ -5,9 +5,16 @@ description: Route operational requests to inspect, query, create, update, delet
 
 # Dataworks CLI
 
-Use `dw` as the operational interface for every Dataworks action. Do not call a
+Use `dw` as the operational interface for Dataworks actions. When the
+`query_metrics` tool is available, use it for historical athlete metric requests;
+it is the read-only, CLI-authenticated interface over Data Explorer. Do not call a
 Dataworks HTTP or GraphQL endpoint directly, or use an SDK instead, when the CLI
-can perform the action.
+or this tool can perform the action.
+
+If a request needs `query_metrics` but the tool is unavailable, tell the user to
+run `dw agents install` once, then start a new Codex thread or run
+`/reload-plugins` in Claude Code. Do not claim the MCP server is registered until
+the restarted or reloaded agent exposes the tool.
 
 ## Route the request
 
@@ -16,6 +23,7 @@ can perform the action.
 2. Run `dw commands --json` to discover the installed command contract.
 3. Run `dw <command> --help` before constructing the exact call.
 4. Prefer the narrowest matching command:
+   - Historical athlete metrics: `query_metrics` when available
    - Data Engine entities: `dw data ...`
    - Authentication and session state: `dw auth ...`
    - Tenant discovery and persistence: `dw tenant list` and `dw tenant select ...`
@@ -113,6 +121,14 @@ return to the shell; do not leave orphaned subscription processes.
 
 ## Query Data Explorer
 
+Prefer `query_metrics` for requests framed in human terms, such as “the last 30
+GPS values for James Haigh” or “the latest heart rate for athlete ID X”. Pass
+exactly one of `athlete_name` and `athlete_id`. The tool resolves names without
+guessing, infers common metric categories, polls asynchronous queries, decodes
+AWSJSON, and returns normalized structured rows. Use the raw command workflow
+below only when the tool is unavailable or the request needs unsupported advanced
+Data Explorer fields or aggregation.
+
 Use `dw data data-explorer execute --help` to inspect the installed contract.
 Data Explorer queries require a JSON array of lowercase `columns` and a metric
 category. Use `METRICS_TYPE_A` for GPS/position/timing metrics,