@xyteai/cli 0.1.0

package/skills/xyte-cli/references/tui-flows.md

@@ -0,0 +1,126 @@
+# Headless Flows (Agent-First)
+
+Use `xyte-cli tui --headless` as the visual/tooling interface for agents.
+
+## Base Pattern
+
+```bash
+xyte-cli tui --headless --screen <screen> --format json --once --tenant <tenant-id>
+```
+
+Supported screens:
+- `setup`
+- `config`
+- `dashboard`
+- `spaces`
+- `devices`
+- `incidents`
+- `tickets`
+
+## Deterministic Branching (Required)
+
+1. Request operational screen (for example `dashboard`).
+2. Parse last non-startup frame.
+3. If `frame.screen == "setup"` and `frame.meta.redirectedFrom` is set:
+- treat tenant/keys/setup as blocking
+- switch to setup/config remediation flow
+4. Retry requested operational screen after remediation.
+
+## Setup/Config Remediation Flow
+
+1. Check readiness frame:
+```bash
+xyte-cli tui --headless --screen setup --format json --once --tenant <tenant-id>
+```
+
+2. If missing auth, run CLI key-slot operations:
+```bash
+xyte-cli auth key add --tenant <tenant-id> --provider xyte-org --name primary --key <value> --set-active
+xyte-cli auth key list --tenant <tenant-id> --format json
+xyte-cli config doctor --tenant <tenant-id> --format json
+```
+
+3. Re-request operational headless frame.
+
+## Per-Screen Headless Recipes
+
+Setup:
+```bash
+xyte-cli tui --headless --screen setup --format json --once --tenant <tenant-id>
+```
+
+Config:
+```bash
+xyte-cli tui --headless --screen config --format json --once --tenant <tenant-id>
+```
+
+Dashboard:
+```bash
+xyte-cli tui --headless --screen dashboard --format json --once --tenant <tenant-id>
+```
+
+Spaces:
+```bash
+xyte-cli tui --headless --screen spaces --format json --once --tenant <tenant-id>
+```
+
+Devices:
+```bash
+xyte-cli tui --headless --screen devices --format json --once --tenant <tenant-id>
+```
+
+Incidents:
+```bash
+xyte-cli tui --headless --screen incidents --format json --once --tenant <tenant-id>
+```
+
+Tickets:
+```bash
+xyte-cli tui --headless --screen tickets --format json --once --tenant <tenant-id>
+```
+
+## Follow Mode (Streaming)
+
+```bash
+xyte-cli tui --headless --screen spaces --format json --follow --interval-ms 2000 --tenant <tenant-id>
+```
+
+Use `--follow` only when continuous status is needed.
+
+## Metadata Keys Agents Should Parse
+
+From top-level frame:
+- `schemaVersion` (expect `xyte.headless.frame.v1`)
+- `sessionId` (stable for one run)
+- `sequence` (monotonic ordering key in `--follow`)
+
+From `frame.meta`:
+- `readiness`
+- `connection`
+- `refreshState`
+- `renderSafety`
+- `tableFormat`
+- `activePane`
+- `availablePanes`
+- `navigationMode`
+- `tabId`
+- `tabOrder`
+- `tabNavBoundary`
+- `redirectedFrom` (when setup gate blocks)
+- `contract.frameVersion`
+- `contract.tableFormat`
+- `contract.navigationMode`
+
+## Output Mode
+
+Headless is JSON-only. Always parse NDJSON frames:
+```bash
+xyte-cli tui --headless --screen config --format json --once --tenant <tenant-id>
+```
+
+## Safety Model
+
+- Headless frames are read-only visualization.
+- Mutations still must go through guarded CLI commands:
+  - non-read methods require `--allow-write`
+  - delete methods require `--allow-write --confirm <endpoint-key>`

package/skills/xyte-cli/scripts/check_headless.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+RUN_CLI="$SCRIPT_DIR/run_xyte_cli.sh"
+VALIDATE_SCHEMA="$SCRIPT_DIR/validate_with_schema.js"
+TENANT_ID="${1:-}"
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "jq is required" >&2
+  exit 1
+fi
+
+if [[ ! -x "$RUN_CLI" ]]; then
+  echo "Missing launcher script: $RUN_CLI" >&2
+  exit 1
+fi
+
+if [[ ! -x "$VALIDATE_SCHEMA" ]]; then
+  echo "Missing validator script: $VALIDATE_SCHEMA" >&2
+  exit 1
+fi
+
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+if [[ ! -f "$REPO_ROOT/dist/bin/xyte-cli.js" ]]; then
+  echo "Build output missing at $REPO_ROOT/dist/bin/xyte-cli.js" >&2
+  echo "Run: npm run build" >&2
+  exit 1
+fi
+
+SCREENS=(setup config dashboard spaces devices incidents tickets)
+META_KEYS=(inputState queueDepth droppedEvents transitionState refreshState navigationMode activePane availablePanes tabId tabOrder tabNavBoundary renderSafety tableFormat contract)
+TMP_CFG="$(mktemp -d)"
+trap 'rm -rf "$TMP_CFG"' EXIT
+
+PASS_COUNT=0
+for screen in "${SCREENS[@]}"; do
+  cmd=("$RUN_CLI" tui --headless --screen "$screen" --format json --once --no-motion)
+  if [[ -n "$TENANT_ID" ]]; then
+    cmd+=(--tenant "$TENANT_ID")
+  fi
+
+  if [[ -n "$TENANT_ID" ]]; then
+    output="$("${cmd[@]}")"
+  else
+    output="$(XYTE_CLI_CONFIG_DIR="$TMP_CFG" XYTE_CLI_KEYCHAIN_BACKEND=memory "${cmd[@]}")"
+  fi
+
+  runtime_frame="$(printf '%s\n' "$output" | jq -c 'select((.meta.startup // false) | not)' | tail -n1)"
+  if [[ -z "$runtime_frame" ]]; then
+    echo "FAIL [$screen] no runtime frame" >&2
+    exit 1
+  fi
+
+  printf '%s\n' "$runtime_frame" | jq -e '.schemaVersion == "xyte.headless.frame.v1"' >/dev/null
+  printf '%s\n' "$runtime_frame" | jq -e '.sessionId | type == "string"' >/dev/null
+  printf '%s\n' "$runtime_frame" | jq -e '.sequence | type == "number"' >/dev/null
+
+  for key in "${META_KEYS[@]}"; do
+    printf '%s\n' "$runtime_frame" | jq -e --arg k "$key" '.meta | has($k)' >/dev/null
+  done
+
+  printf '%s\n' "$runtime_frame" | jq -e '.meta.contract.frameVersion == "xyte.headless.frame.v1"' >/dev/null
+
+  runtime_path="$TMP_CFG/headless-$screen.json"
+  printf '%s\n' "$runtime_frame" > "$runtime_path"
+  "$VALIDATE_SCHEMA" "$REPO_ROOT/docs/schemas/headless-frame.v1.schema.json" "$runtime_path" >/dev/null
+
+  runtime_screen="$(printf '%s\n' "$runtime_frame" | jq -r '.screen')"
+  if [[ "$screen" != "setup" && "$screen" != "config" && "$runtime_screen" == "setup" ]]; then
+    redirected_from="$(printf '%s\n' "$runtime_frame" | jq -r '.meta.redirectedFrom // ""')"
+    if [[ "$redirected_from" != "$screen" ]]; then
+      echo "FAIL [$screen] expected redirectedFrom=$screen, got '$redirected_from'" >&2
+      exit 1
+    fi
+  fi
+
+  printf '%s\n' "$runtime_frame" | jq -e '.panels | type == "array"' >/dev/null
+  echo "PASS [$screen] runtime_screen=$runtime_screen"
+  PASS_COUNT=$((PASS_COUNT + 1))
+done
+
+echo "Headless smoke passed: $PASS_COUNT/${#SCREENS[@]} screens"

package/skills/xyte-cli/scripts/endpoint_filters_report.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+SPEC="$REPO_ROOT/src/spec/public-endpoints.json"
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "jq is required" >&2
+  exit 1
+fi
+
+if [[ ! -f "$SPEC" ]]; then
+  echo "Spec file not found: $SPEC" >&2
+  exit 1
+fi
+
+echo "key | method | query_params | pagination"
+echo "--- | --- | --- | ---"
+
+jq -r '
+  .[]
+  | select((.queryParams | length) > 0)
+  | {
+      key,
+      method,
+      query: (.queryParams | join(", ")),
+      pagination: (if ((.queryParams | index("page")) != null or (.queryParams | index("per_page")) != null)
+                   then "page/per_page"
+                   else "none"
+                   end)
+    }
+  | "\(.key) | \(.method) | \(.query) | \(.pagination)"
+' "$SPEC"

package/skills/xyte-cli/scripts/run_xyte_cli.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+cd "$REPO_ROOT"
+
+if [[ ! -x ./bin/xyte-cli ]]; then
+  echo "xyte-cli binary wrapper not found at ./bin/xyte-cli" >&2
+  exit 1
+fi
+
+./bin/xyte-cli "$@"

package/skills/xyte-cli/scripts/validate_agent_contracts.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+RUN_CLI="$SCRIPT_DIR/run_xyte_cli.sh"
+VALIDATE_SCHEMA="$SCRIPT_DIR/validate_with_schema.js"
+TENANT_ID="${1:-}"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "jq is required" >&2
+  exit 1
+fi
+
+if [[ -z "$TENANT_ID" ]]; then
+  echo "Usage: $(basename "$0") <tenant-id>" >&2
+  exit 1
+fi
+
+if [[ ! -x "$VALIDATE_SCHEMA" ]]; then
+  echo "Missing validator script: $VALIDATE_SCHEMA" >&2
+  exit 1
+fi
+
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+echo "Validating call envelope contract..."
+set +e
+CALL_OUTPUT="$("$RUN_CLI" call organization.devices.getDevices --tenant "$TENANT_ID" --output-mode envelope 2>/dev/null)"
+CALL_EXIT=$?
+set -e
+
+if [[ -z "$CALL_OUTPUT" ]]; then
+  echo "FAIL call envelope emitted empty output" >&2
+  exit 1
+fi
+printf '%s\n' "$CALL_OUTPUT" | jq -e '.schemaVersion == "xyte.call.envelope.v1"' >/dev/null
+printf '%s\n' "$CALL_OUTPUT" | jq -e '.requestId | type == "string"' >/dev/null
+CALL_PATH="$TMP_DIR/call-envelope.json"
+printf '%s\n' "$CALL_OUTPUT" > "$CALL_PATH"
+"$VALIDATE_SCHEMA" "$REPO_ROOT/docs/schemas/call-envelope.v1.schema.json" "$CALL_PATH"
+echo "PASS call envelope (exit=$CALL_EXIT)"
+
+echo "Validating inspect fleet contract..."
+FLEET_OUTPUT="$("$RUN_CLI" inspect fleet --tenant "$TENANT_ID" --format json)"
+printf '%s\n' "$FLEET_OUTPUT" | jq -e '.schemaVersion == "xyte.inspect.fleet.v1"' >/dev/null
+FLEET_PATH="$TMP_DIR/fleet.json"
+printf '%s\n' "$FLEET_OUTPUT" > "$FLEET_PATH"
+"$VALIDATE_SCHEMA" "$REPO_ROOT/docs/schemas/inspect-fleet.v1.schema.json" "$FLEET_PATH"
+echo "PASS inspect fleet"
+
+echo "Validating inspect deep-dive + report contracts..."
+DEEP_OUTPUT="$("$RUN_CLI" inspect deep-dive --tenant "$TENANT_ID" --format json)"
+printf '%s\n' "$DEEP_OUTPUT" | jq -e '.schemaVersion == "xyte.inspect.deep-dive.v1"' >/dev/null
+DEEP_PATH="$TMP_DIR/deep-dive.json"
+REPORT_PATH="$TMP_DIR/report.md"
+printf '%s\n' "$DEEP_OUTPUT" > "$DEEP_PATH"
+"$VALIDATE_SCHEMA" "$REPO_ROOT/docs/schemas/inspect-deep-dive.v1.schema.json" "$DEEP_PATH"
+
+REPORT_OUTPUT="$("$RUN_CLI" report generate --tenant "$TENANT_ID" --input "$DEEP_PATH" --out "$REPORT_PATH" --format markdown)"
+printf '%s\n' "$REPORT_OUTPUT" | jq -e '.schemaVersion == "xyte.report.v1"' >/dev/null
+REPORT_META_PATH="$TMP_DIR/report-meta.json"
+printf '%s\n' "$REPORT_OUTPUT" > "$REPORT_META_PATH"
+"$VALIDATE_SCHEMA" "$REPO_ROOT/docs/schemas/report.v1.schema.json" "$REPORT_META_PATH"
+[[ -s "$REPORT_PATH" ]]
+echo "PASS report generation"
+
+echo "Validating headless contract..."
+"$SCRIPT_DIR/check_headless.sh" "$TENANT_ID"
+
+echo "All agent contracts validated."

package/skills/xyte-cli/scripts/validate_with_schema.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+const path = require('node:path');
+const Ajv2020 = require('ajv/dist/2020').default;
+
+function usage() {
+  process.stderr.write('Usage: validate_with_schema.js <schema.json> <data.json>\n');
+  process.exit(1);
+}
+
+const [, , schemaPathArg, dataPathArg] = process.argv;
+if (!schemaPathArg || !dataPathArg) {
+  usage();
+}
+
+const schemaPath = path.resolve(schemaPathArg);
+const dataPath = path.resolve(dataPathArg);
+
+const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+const data = JSON.parse(fs.readFileSync(dataPath, 'utf8'));
+const ajv = new Ajv2020({ strict: false });
+const validate = ajv.compile(schema);
+
+if (!validate(data)) {
+  process.stderr.write(`Schema validation failed for ${dataPath}\n`);
+  process.stderr.write(`${JSON.stringify(validate.errors, null, 2)}\n`);
+  process.exit(2);
+}
+
+process.stdout.write(`Schema validation passed: ${path.basename(dataPath)} against ${path.basename(schemaPath)}\n`);