@dataworks-technology/cli 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dataworks-technology/cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "The official command-line interface for the Dataworks Data Engine",
   "type": "module",
   "license": "MIT",
@@ -49,6 +49,14 @@
     "commands": "./dist/commands",
     "helpClass": "./dist/help.js",
     "topicSeparator": " ",
+    "topics": {
+      "tenant": {
+        "description": "List available tenants or select the tenant used by subsequent commands"
+      }
+    },
+    "plugins": [
+      "@oclif/plugin-autocomplete"
+    ],
     "additionalHelpFlags": [
       "-h"
     ]
@@ -58,6 +66,7 @@
     "@dataworks-technology/data": "0.6.1",
     "@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"
   },

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,6 +1,6 @@
 ---
 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
@@ -18,7 +18,7 @@ can perform the action.
 4. Prefer the narrowest matching command:
    - 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 +28,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 +57,99 @@ 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
+
+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."