@dataworks-technology/cli 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dataworks-technology/cli",
-  "version": "1.1.0",
+  "version": "1.3.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,7 +31,7 @@
     "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 .",
@@ -37,9 +41,11 @@
     "lint": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
     "maintain:sdk": "bun scripts/maintenance/update-sdk.ts",
+    "postinstall": "node ./bin/postinstall.js",
     "prepack": "bun run build && bun run test",
     "prepare": "husky",
     "smoke:litellm": "bun scripts/maintenance/smoke-agent.ts",
+    "sync:plugin-version": "bun scripts/sync-plugin-version.ts",
     "test": "vitest run",
     "test:watch": "vitest"
   },
@@ -49,6 +55,17 @@
     "commands": "./dist/commands",
     "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"
+      }
+    },
+    "plugins": [
+      "@oclif/plugin-autocomplete"
+    ],
     "additionalHelpFlags": [
       "-h"
     ]
@@ -56,10 +73,13 @@
   "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",

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

@@ -0,0 +1,17 @@
+{
+  "name": "dataworks",
+  "version": "1.3.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,37 @@
+{
+  "name": "dataworks",
+  "version": "1.3.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,48 @@
+---
+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.
+- Pass the user's metric wording directly. The tool understands GPS/location and
+  heart-rate/HR/BPM aliases, plus common speed, altitude, cadence, power, and
+  timing names.
+- 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 an unknown custom metric, pass its exact name and explicit
+  `metric_category`.
+
+Examples:
+
+- “Give me the last 30 GPS values for James Haigh” → `athlete_name: "James
+Haigh"`, `metric: "GPS"`, `limit: 30`, `order: "newest"`.
+- “Latest heart rate for athlete ID X” → `athlete_id: "X"`, `metric: "heart
+rate"`, `limit: 1`.
+- “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. 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/schema/operation-overrides.json

@@ -8,6 +8,55 @@
     "onAdaptorLogEventNoSession": "data adaptor-log-event watch-no-session",
     "onAdaptorStatusChangeAll": "data adaptor-status watch-all"
   },
+  "operations": {
+    "executeDataExplorerQuery": {
+      "description": "Query Data Explorer metrics with explicit columns, optional filters, ordering, aggregation, and row limits.",
+      "arguments": {
+        "columns": {
+          "description": "Required JSON array of category columns; base columns are timestamp, datasetdatasourcepublicid, eventpublicid, athletepublicid, metric, and current",
+          "example": "[\"timestamp\",\"athletepublicid\",\"metric\",\"current\"]"
+        },
+        "filterRules": {
+          "description": "AWSJSON string shaped as {combinator,rules:[{field,operator,value}]}; operators include =, !=, >, <, >=, <=, contains, and in",
+          "example": "{\"combinator\":\"and\",\"rules\":[{\"field\":\"metric\",\"operator\":\"in\",\"value\":\"latlong\"}]}"
+        },
+        "limit": {
+          "description": "Maximum number of rows to return",
+          "example": "30"
+        },
+        "metricCategory": {
+          "description": "Metric category: METRICS_TYPE_A for GPS/position/timing, METRICS_TYPE_B for speed/altitude/cadence, or METRICS_TYPE_C for heart rate/power/zones",
+          "example": "METRICS_TYPE_A"
+        },
+        "orderBy": {
+          "description": "Column used to order rows",
+          "example": "timestamp"
+        },
+        "orderDirection": {
+          "description": "Sort direction: ASC or DESC",
+          "example": "DESC"
+        },
+        "queryExecutionId": {
+          "description": "Existing asynchronous query execution ID to poll",
+          "example": "query-execution-123"
+        }
+      },
+      "examples": [
+        {
+          "description": "Run a complete query from a reusable input file",
+          "command": "dw data data-explorer execute --input @data-explorer-query.json --json"
+        },
+        {
+          "description": "Return the latest 30 rows from a metric category",
+          "command": "dw data data-explorer execute --columns '[\"timestamp\",\"athletepublicid\",\"metric\",\"current\"]' --metric-category METRICS_TYPE_A --limit 30 --order-by timestamp --order-direction DESC --json"
+        },
+        {
+          "description": "Return the latest 30 GPS positions for one athlete",
+          "command": "dw data data-explorer execute --input @gps-query.json --json"
+        }
+      ]
+    }
+  },
   "mutations": {
     "archiveEventFiles": "destructive",
     "captureStory": "standard",

package/skills/dataworks-cli/SKILL.md

@@ -1,13 +1,20 @@
 ---
 name: dataworks-cli
-description: Route every request to inspect, query, create, update, delete, ingest, monitor, subscribe to, or otherwise act on Dataworks through the `dw` CLI. Use whenever a user asks for any action involving Dataworks data, tenants, authentication, the Data Engine API, events, adaptors, datasets, or related resources.
+description: Route operational requests to inspect, query, create, update, delete, ingest, monitor, subscribe to, or otherwise act on the Dataworks platform through the `dw` CLI. Use for Dataworks data, tenants, authentication, Data Engine API operations, events, adaptors, datasets, and related platform resources. Do not use for developing, testing, documenting, packaging, or releasing the CLI itself.
 ---
 
 # 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,9 +23,10 @@ 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 select ...`
+   - Tenant discovery and persistence: `dw tenant list` and `dw tenant select ...`
    - Metric ingestion: `dw ingest`
    - Realtime events: `dw events subscribe`
    - Datasource errors: `dw report-error`
@@ -28,19 +36,26 @@ can perform the action.
 
 ## Authenticate and select a tenant
 
-Authenticate with `dw auth login --environment uat|live` and inspect the session
-with `dw auth status --json`. Never print, log, or write `DW_PASSWORD`,
-`DW_SESSION_JSON`, tokens, or API keys.
+Inspect the current session first with `dw auth status --json`. Log in only when
+needed, using either `dw auth login --environment uat` or
+`dw auth login --environment live`. If a browser cannot open, add
+`--no-browser`, show the authorization URL, and let the human complete login.
+Never emit a placeholder command containing `uat|live`; select one exact value
+from the request or current profile, or ask which environment to use.
+Never print, log, or write `DW_PASSWORD`, `DW_SESSION_JSON`, tokens,
+authorization headers, API keys, or credential-store contents.
 
-Use `dw tenant select --json` to list authorized tenants, `dw tenant select` for
-interactive selection, or `dw tenant select <id>` for a direct selection. The
-selected tenant persists for subsequent commands. Use `--tenant` only for an
-explicit one-command override.
+Use `dw tenant list --json` to list authorized tenants and identify the current
+selection, `dw tenant select` for interactive selection, or
+`dw tenant select <id>` for a direct selection. The selected tenant persists for
+subsequent commands. Use `--tenant` only for an explicit one-command override.
 
 ## Execute safely
 
-Use `--json` for finite machine-readable results. Treat subscription output as
-NDJSON and process it incrementally.
+Always add `--json` when an agent runs a command that emits data; never parse the
+default human-readable tables. Finite results use a stable `{data,meta}` JSON
+envelope. With `--json`, subscriptions emit NDJSON; process each line
+incrementally.
 
 Before any mutation:
 
@@ -50,8 +65,107 @@ Before any mutation:
 3. Add `--yes` only after approval. Never infer approval from the presence of
    credentials.
 
+Apply this mutation workflow only when command help exposes `--dry-run` and
+`--yes`. Never invent behavior flags for built-in commands.
+
 For bulk ingest, default to strict validation. Use `--best-effort` only when
 dropping invalid metrics is acceptable, and report every dropped item.
 
-Report the command used, the selected environment and tenant when relevant, and
-the result without exposing credentials or unredacted sensitive values.
+Report a sanitized command, the selected environment and tenant when relevant,
+and the result. Omit or redact payload values, personal data, session material,
+and other sensitive values.
+
+## Ingest metrics
+
+Resolve omitted context before ingesting:
+
+1. Use `dw data event list --all --json` to identify the event.
+2. Use `dw data dataset-datasource list --all --json` to identify the
+   dataset-datasource and inspect its configured metrics.
+3. If a name or description matches multiple resources, ask the human to choose;
+   never guess an ID.
+4. Use the current Unix timestamp only when the user means "now". Otherwise ask
+   for or preserve the requested timestamp.
+
+Each metric requires `athletePublicId`, `metric`, `value`, and a positive integer
+`timestamp`. Pass a JSON array, a `{ "metrics": [...] }` object, `@file`, or `-`
+for standard input. For example, after resolving the event and
+dataset-datasource, ingest a heart rate of 120 for athlete `athlete-X` with:
+
+```sh
+dw ingest --event event-123 --dataset-datasource ds-456 --metrics '[{"athletePublicId":"athlete-X","metric":"heartrate","value":120,"timestamp":1700000000}]' --json
+```
+
+Strict validation is the default and sends nothing if any metric is invalid. Add
+`--best-effort` only when the human accepts partial ingestion.
+
+`dw ingest` supports neither `--dry-run` nor `--yes`; never add them. It sends
+data immediately after validation. Do not add a `unit` property: use the metric
+configured on the dataset-datasource and pass the numeric BPM as `value`. If the
+target is Live, show the resolved event, dataset-datasource, athlete, metric,
+value, and timestamp and obtain confirmation before running the command.
+
+## Subscribe to realtime metrics
+
+Use channel shape
+`dataworks/<dataset-datasource-id>/<event-id>/<metric-or-*>`. A leading slash is
+optional. Use `*` to receive all metrics or a metric name to narrow the stream:
+
+```sh
+dw events subscribe --channel dataworks/1/1/* --json
+dw events subscribe --channel dataworks/1/1/heartrate --json
+```
+
+Subscriptions are long-running. Press `Ctrl+C` once to close the WebSocket and
+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,
+`METRICS_TYPE_B` for speed/altitude/cadence, and `METRICS_TYPE_C` for heart
+rate/power/zones. The base columns are `timestamp`,
+`datasetdatasourcepublicid`, `eventpublicid`, `athletepublicid`, `metric`, and
+`current`. Prefer a reusable `--input @file` for complex filters; use individual
+flags for simple queries:
+
+```sh
+dw data data-explorer execute --columns '["timestamp","athletepublicid","metric","current"]' --metric-category METRICS_TYPE_A --limit 30 --order-by timestamp --order-direction DESC --json
+```
+
+Pass `--filter-rules` as an AWSJSON string shaped like
+`{"combinator":"and","rules":[{"field":"metric","operator":"in","value":"latlong"}]}`.
+Each rule contains `field`, `operator`, and string `value`; comma-separate
+multiple values for `in`.
+
+For a request such as "the last 30 GPS values for James Haigh":
+
+1. Run `dw data athlete list --all --json` and match the name case-insensitively.
+2. Require one exact athlete match; ask if multiple athletes match.
+3. Use `dw data data-explorer execute`; do not substitute a guessed generated
+   command or raw GraphQL while this command is available.
+4. Use GPS metric `latlong` in `METRICS_TYPE_A`. Filter on both `metric` and
+   lowercase `athletepublicid`, order by `timestamp` descending, and limit to 30. For athlete `athlete-123`, run:
+
+   ```sh
+   dw data data-explorer execute --columns '["timestamp","athletepublicid","current"]' --metric-category METRICS_TYPE_A --filter-rules '{"combinator":"and","rules":[{"field":"metric","operator":"in","value":"latlong"},{"field":"athletepublicid","operator":"in","value":"athlete-123"}]}' --limit 30 --order-by timestamp --order-direction DESC --json
+   ```
+
+5. Replace `athlete-123` with the resolved public ID and run the query with
+   `--json`. If status is `RUNNING` with a `queryExecutionId`, repeat the same
+   command with `--query-execution-id <id>` until it completes.
+6. Return the 30 values in timestamp order and retain the athlete ID used in the
+   result summary. The `rows` field is AWSJSON: decode JSON until it is an array.
+   Interpret each `current` value as a `latitude:longitude` string.
+
+Do not guess an athlete, event, dataset-datasource, or tenant ID. Resolve IDs
+with CLI list commands and ask only when multiple resources match.

package/skills/dataworks-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Dataworks CLI"
+  short_description: "Operate Dataworks safely through the dw CLI"
+  default_prompt: "Use $dataworks-cli to inspect or operate Dataworks through the dw CLI."