@xyteai/cli 0.1.0

package/docs/schemas/inspect-fleet.v1.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xyte.dev/schemas/inspect-fleet.v1.schema.json",
+  "title": "Xyte Fleet Inspect V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "generatedAtUtc",
+    "tenantId",
+    "totals",
+    "status",
+    "highlights"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "xyte.inspect.fleet.v1"
+    },
+    "generatedAtUtc": {
+      "type": "string"
+    },
+    "tenantId": {
+      "type": "string"
+    },
+    "totals": {
+      "type": "object",
+      "required": [
+        "devices",
+        "spaces",
+        "incidents",
+        "tickets"
+      ],
+      "properties": {
+        "devices": {
+          "type": "integer"
+        },
+        "spaces": {
+          "type": "integer"
+        },
+        "incidents": {
+          "type": "integer"
+        },
+        "tickets": {
+          "type": "integer"
+        }
+      }
+    },
+    "status": {
+      "type": "object",
+      "required": [
+        "devices",
+        "incidents",
+        "tickets",
+        "spaces"
+      ],
+      "properties": {
+        "devices": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer"
+          }
+        },
+        "incidents": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer"
+          }
+        },
+        "tickets": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer"
+          }
+        },
+        "spaces": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer"
+          }
+        }
+      }
+    },
+    "highlights": {
+      "type": "object",
+      "required": [
+        "offlineDevices",
+        "offlinePct",
+        "activeIncidents",
+        "activeIncidentPct",
+        "openTickets"
+      ],
+      "properties": {
+        "offlineDevices": {
+          "type": "integer"
+        },
+        "offlinePct": {
+          "type": "number"
+        },
+        "activeIncidents": {
+          "type": "integer"
+        },
+        "activeIncidentPct": {
+          "type": "number"
+        },
+        "openTickets": {
+          "type": "integer"
+        }
+      }
+    }
+  }
+}

package/docs/schemas/report.v1.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xyte.dev/schemas/report.v1.schema.json",
+  "title": "Xyte Report V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "generatedAtUtc",
+    "tenantId",
+    "format",
+    "outputPath",
+    "includeSensitive"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "xyte.report.v1"
+    },
+    "generatedAtUtc": {
+      "type": "string"
+    },
+    "tenantId": {
+      "type": "string"
+    },
+    "format": {
+      "type": "string",
+      "enum": [
+        "markdown",
+        "pdf"
+      ]
+    },
+    "outputPath": {
+      "type": "string"
+    },
+    "includeSensitive": {
+      "type": "boolean"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@xyteai/cli",
+  "version": "0.1.0",
+  "description": "Xyte CLI, TUI, skills, and MCP bridge for zero-friction AI operations",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xyte-io/xyte-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xyte-io/xyte-cli/issues"
+  },
+  "homepage": "https://github.com/xyte-io/xyte-cli#readme",
+  "keywords": [
+    "xyte",
+    "cli",
+    "tui",
+    "mcp",
+    "agent",
+    "operations"
+  ],
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "xyte-cli": "dist/bin/xyte-cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "skills",
+    "docs/schemas"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist coverage",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "install:global": "npm run build && npm link",
+    "uninstall:global": "npm unlink -g @xyteai/cli || true",
+    "reinstall:global": "npm run uninstall:global && npm run install:global",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "tui": "tsx src/bin/xyte-cli.ts tui",
+    "release:publish": "bash scripts/publish.sh all",
+    "release:publish:cli": "bash scripts/publish.sh cli",
+    "release:publish:pages": "bash scripts/publish.sh pages"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-node": "^0.211.0",
+    "@types/pdfkit": "^0.17.4",
+    "ajv": "^8.17.1",
+    "blessed": "^0.1.81",
+    "commander": "^14.0.3",
+    "pdfkit": "^0.17.2",
+    "pino": "^10.3.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/blessed": "^0.1.25",
+    "@types/node": "^22.13.4",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  }
+}

package/skills/xyte-cli/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: xyte-cli
+description: "Use for @xyte/cli operations: first-run setup, tenant/key auth, guarded endpoint calls, inspect/report generation, JSON-only headless TUI snapshots, and MCP tool serving with schema-validated outputs."
+---
+
+# XYTE Skill Router (One-Stop, Agent-Native)
+
+Last updated: 2026-02-15
+
+This skill is the entrypoint for deterministic Xyte operations via `xyte-cli`.
+
+## Invocation Rules
+
+- Use `xyte-cli` commands directly.
+- Do not use source/dev entrypoints (`npx`, `tsx`, `src/*`, `dist/*`, `bin/*`).
+- If `xyte-cli` is unavailable, ask the user to install `@xyte/cli` globally instead of improvising an entrypoint.
+- Command option correctness:
+  - `xyte-cli tenant list` has no `--format`.
+  - `xyte-cli setup status` supports `--format json|text`.
+
+## Purpose and Trigger Conditions
+
+Use when the request involves any of:
+- setup/readiness for Xyte access
+- tenant/key-slot management
+- endpoint discovery or endpoint invocation
+- fleet inspection/deep-dive/reporting
+- headless TUI JSON frame consumption
+- MCP tool bridge for external agents
+
+## Non-Goals
+
+- Do not use this skill for arbitrary product strategy or generic markdown authoring.
+- Do not perform writes by default.
+- Do not use headless text output; headless is JSON-only.
+
+## Mandatory Safety Rules
+
+- Default to read-only.
+- Require explicit user intent before writes.
+- Non-read endpoint calls must include `--allow-write`.
+- Destructive endpoint calls must include `--confirm <endpoint-key>`.
+- In automation, always pass `--tenant <tenant-id>`.
+
+## Deterministic Execution Order
+
+1. Setup/readiness:
+- `xyte-cli doctor install --format json`
+- `xyte-cli setup status --tenant <tenant-id> --format json`
+- `xyte-cli config doctor --tenant <tenant-id> --format json`
+
+2. Auth/tenant (if missing/incomplete):
+- `xyte-cli setup run --non-interactive --tenant <tenant-id> --key <value>`
+- `xyte-cli tenant use <tenant-id>`
+- `xyte-cli auth key list --tenant <tenant-id> --format json`
+
+3. Endpoint operations:
+- `xyte-cli list-endpoints --tenant <tenant-id>`
+- `xyte-cli describe-endpoint <endpoint-key>`
+- `xyte-cli call <endpoint-key> --tenant <tenant-id> ...`
+
+4. Insights/reports:
+- `xyte-cli inspect fleet --tenant <tenant-id> --format json`
+- `xyte-cli inspect deep-dive --tenant <tenant-id> --window <hours> --format json`
+- `xyte-cli report generate --tenant <tenant-id> --input <deep-dive.json> --out <report.pdf>`
+
+5. Headless and MCP:
+- `xyte-cli tui --headless --screen <screen> --format json --once --tenant <tenant-id>`
+- `xyte-cli mcp serve`
+
+## Workflow Selector
+
+| Intent | Primary command |
+| --- | --- |
+| First-time onboarding (interactive) | `xyte-cli` |
+| Setup non-interactive | `xyte-cli setup run --non-interactive --tenant <tenant-id> --key <value>` |
+| Readiness snapshot | `xyte-cli setup status --tenant <tenant-id> --format json` |
+| Connectivity diagnostics | `xyte-cli config doctor --tenant <tenant-id> --format json` |
+| Read endpoint call + envelope | `xyte-cli call <endpoint-key> --tenant <tenant-id> --output-mode envelope --strict-json` |
+| Guarded write endpoint call | `xyte-cli call <endpoint-key> --tenant <tenant-id> --allow-write ...` |
+| Guarded delete endpoint call | `xyte-cli call <endpoint-key> --tenant <tenant-id> --allow-write --confirm <endpoint-key> ...` |
+| Fleet summary | `xyte-cli inspect fleet --tenant <tenant-id> --format json` |
+| Deep-dive analytics | `xyte-cli inspect deep-dive --tenant <tenant-id> --window <hours> --format json` |
+| PDF report generation | `xyte-cli report generate --tenant <tenant-id> --input <deep-dive.json> --out <path>.pdf` |
+| Headless snapshot (JSON NDJSON) | `xyte-cli tui --headless --screen <screen> --format json --once --tenant <tenant-id>` |
+| Continuous headless monitoring | `xyte-cli tui --headless --screen <screen> --format json --follow --interval-ms <ms> --tenant <tenant-id>` |
+| MCP tool bridge | `xyte-cli mcp serve` |
+
+## Minimal Command Recipes
+
+Read call:
+```bash
+xyte-cli call organization.devices.getDevices --tenant <tenant-id> --output-mode envelope --strict-json
+```
+
+Write call (guarded):
+```bash
+xyte-cli call organization.commands.sendCommand \
+  --tenant <tenant-id> \
+  --allow-write \
+  --path-json '{"device_id":"<device-id>"}' \
+  --body-json '{"name":"reboot"}'
+```
+
+Delete call (guarded):
+```bash
+xyte-cli call organization.commands.cancelCommand \
+  --tenant <tenant-id> \
+  --allow-write \
+  --confirm organization.commands.cancelCommand \
+  --path-json '{"device_id":"<device-id>","command_id":"<command-id>"}'
+```
+
+Headless:
+```bash
+xyte-cli tui --headless --screen dashboard --format json --once --tenant <tenant-id>
+```
+
+Inspect + report:
+```bash
+xyte-cli inspect deep-dive --tenant <tenant-id> --window 24 --format json > /tmp/deep-dive.json
+xyte-cli report generate --tenant <tenant-id> --input /tmp/deep-dive.json --out /tmp/xyte-findings.pdf
+```
+
+## Contract IDs and Schemas
+
+Schema/version IDs:
+- call envelope: `xyte.call.envelope.v1`
+- headless frame: `xyte.headless.frame.v1`
+- inspect fleet: `xyte.inspect.fleet.v1`
+- inspect deep dive: `xyte.inspect.deep-dive.v1`
+- report metadata: `xyte.report.v1`
+
+Canonical schemas:
+- `docs/schemas/call-envelope.v1.schema.json`
+- `docs/schemas/headless-frame.v1.schema.json`
+- `docs/schemas/inspect-fleet.v1.schema.json`
+- `docs/schemas/inspect-deep-dive.v1.schema.json`
+- `docs/schemas/report.v1.schema.json`
+
+## MCP Tool Surface (Current)
+
+Current tool names:
+- `xyte_setup_status`
+- `xyte_config_doctor`
+- `xyte_list_endpoints`
+- `xyte_describe_endpoint`
+- `xyte_call`
+- `xyte_inspect_fleet`
+- `xyte_report_generate`
+
+Guard semantics in MCP mirror CLI:
+- write endpoints require `allow_write: true`
+- destructive endpoints require matching `confirm`
+
+## Troubleshooting Entrypoints
+
+- First-run/setup issues:
+  - `xyte-cli`
+  - `xyte-cli setup run --non-interactive --tenant <tenant-id> --key <value>`
+- Readiness/connectivity:
+  - `xyte-cli setup status --tenant <tenant-id> --format json`
+  - `xyte-cli config doctor --tenant <tenant-id> --format json`
+- TUI crash diagnostics:
+```bash
+XYTE_TUI_DEBUG=1 XYTE_TUI_DEBUG_LOG=/tmp/xyte-tui-debug.log xyte-cli tui --tenant <tenant-id>
+```
+- Headless errors:
+  - ensure `--headless --format json` (no text format in headless)
+  - parse NDJSON and use the last runtime frame (`meta.startup != true`)
+
+## References (Load As Needed)
+
+- `references/endpoints.md`
+- `references/tui-flows.md`
+- `references/headless-contract.md`
+
+## Notes for Agents
+
+- Keep this file short in-context; use references for deep procedures.
+- Keep tenant explicit in automation (`--tenant <tenant-id>`).

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Xyte Ops Agent"
+  short_description: "Deterministic Xyte CLI ops: first-run setup, guarded calls, inspect/report, headless JSON, MCP."
+  default_prompt: "Use $xyte-cli as the operational router for @xyte/cli. Invoke commands directly with `xyte-cli` (do not use source/dev entrypoints like npx/tsx/src/dist/bin paths). Default path: run `xyte-cli` for first-run onboarding (API key + tenant label) and dashboard access. For automation, always pass `--tenant`, use JSON outputs, enforce `--allow-write` for non-read calls and `--confirm <endpoint-key>` for destructive calls, use `xyte-cli tui --headless --format json` for machine frames, and generate reports with `xyte-cli report generate` (PDF default, redacted unless include-sensitive is explicitly requested)."

package/skills/xyte-cli/references/endpoints.md

@@ -0,0 +1,106 @@
+# Endpoint Usage Reference (CLI + Headless Agents)
+
+Use this file for deterministic endpoint operations with `xyte-cli call`.
+
+## Discovery Sequence
+
+1. List available endpoint keys:
+```bash
+xyte-cli list-endpoints
+```
+
+2. Inspect one endpoint contract before calling:
+```bash
+xyte-cli describe-endpoint <endpoint-key>
+```
+
+3. Call with explicit tenant and structured params:
+```bash
+xyte-cli call <endpoint-key> \
+  --tenant <tenant-id> \
+  --output-mode envelope \
+  --path-json '{"id":"..."}' \
+  --query-json '{"page":1}' \
+  --body-json '{"field":"value"}'
+```
+
+## Guard Requirements by Method
+
+| Method | Guard Requirement |
+| --- | --- |
+| `GET`, `HEAD`, `OPTIONS` | No write guard required |
+| `POST`, `PUT`, `PATCH` | Must include `--allow-write` |
+| `DELETE` | Must include `--allow-write` and `--confirm <endpoint-key>` |
+
+## Filters and Pagination Matrix (from spec)
+
+Derived from the bundled public endpoint spec.
+
+| Endpoint Key | Query Fields | Pagination Fields | Notes |
+| --- | --- | --- | --- |
+| `organization.spaces.getSpaces` | `page`, `per_page`, `id`, `parent_id`, `name`, `path_includes`, `space_type`, `created_before`, `created_after` | `page`, `per_page` | Main listing endpoint with server-side filtering |
+| `organization.devices.getHistories` | `status`, `from`, `to`, `device_id`, `space_id`, `name` | none | Filtered history lookup; can be time-windowed |
+
+All other current endpoint specs in this repo have no declared query params.
+
+## Concrete Filter/Pagination Examples
+
+### `organization.spaces.getSpaces`
+
+```bash
+xyte-cli call organization.spaces.getSpaces \
+  --tenant <tenant-id> \
+  --query-json '{
+    "page": 1,
+    "per_page": 25,
+    "parent_id": "<space-id>",
+    "name": "room",
+    "space_type": "room"
+  }'
+```
+
+### `organization.devices.getHistories`
+
+```bash
+xyte-cli call organization.devices.getHistories \
+  --tenant <tenant-id> \
+  --query-json '{
+    "status": "online",
+    "from": "2026-02-01T00:00:00Z",
+    "to": "2026-02-06T23:59:59Z",
+    "space_id": "<space-id>"
+  }'
+```
+
+## Common Endpoint Keys
+
+Organization:
+- `organization.devices.getDevices`
+- `organization.devices.getDevice`
+- `organization.incidents.getIncidents`
+- `organization.tickets.getTickets`
+- `organization.commands.sendCommand`
+
+Partner:
+- `partner.devices.getDevices`
+- `partner.devices.getDeviceInfo`
+- `partner.tickets.getTickets`
+
+Device:
+- `device.device-info.getDeviceInfo`
+- `device.telemetries.sendTelemetry`
+- `device.device-info.setCloudSettings`
+
+## Multi-tenant Determinism
+
+- Always pass `--tenant <tenant-id>` for automation.
+- Prefer `--output-mode envelope` for machine loops to capture request/guard/retry metadata.
+- Use `xyte-cli tenant use <tenant-id>` only for interactive/default context.
+- Keep auth explicit with named slots:
+  - `xyte-cli auth key list --tenant <tenant-id> --format json`
+  - `xyte-cli auth key use --tenant <tenant-id> --provider <provider> --slot <id|name>`
+
+## Notes
+
+- Keep endpoint exploration and invocation on `xyte-cli` commands.
+- Do not rely on repo-local script paths for agent operation.

package/skills/xyte-cli/references/headless-contract.md

@@ -0,0 +1,96 @@
+# Headless JSON Contract
+
+This contract is for agent parsers consuming:
+
+```bash
+xyte-cli tui --headless --screen <screen> --format json --once --tenant <tenant-id>
+```
+
+## Frame Model
+
+Each line is one JSON frame.
+
+Required top-level fields:
+- `schemaVersion` (`"xyte.headless.frame.v1"`)
+- `timestamp` (ISO string)
+- `sessionId` (stable per run)
+- `sequence` (monotonic per run)
+- `mode` (`"headless"`)
+- `screen` (screen id)
+- `title` (string)
+- `status` (string)
+- `tenantId` (string or omitted)
+- `motionEnabled` (boolean)
+- `motionPhase` (number)
+- `logo` (string)
+- `panels` (array)
+- `meta` (object)
+
+## Startup vs Runtime Frames
+
+Startup frames:
+- `meta.startup == true`
+- typically no operational panels
+
+Runtime frame selection rule:
+- parse the **last** frame where `meta.startup` is missing or `false`
+
+## Required `meta` Keys (Runtime)
+
+- `inputState`: `idle | modal | busy`
+- `queueDepth`: number
+- `droppedEvents`: number
+- `transitionState`: `idle | switching`
+- `refreshState`: `idle | loading | retrying | error`
+- `navigationMode`: `pane-focus`
+- `activePane`: string
+- `availablePanes`: string[]
+- `tabId`: screen id
+- `tabOrder`: screen id[]
+- `tabNavBoundary`: `left | right | null`
+- `renderSafety`: `ok | truncated`
+- `tableFormat`: `compact-v1`
+- `contract.frameVersion`: `xyte.headless.frame.v1`
+- `contract.tableFormat`: `compact-v1`
+- `contract.navigationMode`: `pane-focus`
+
+Common optional keys:
+- `readiness`
+- `connection`
+- `retry`
+- `blocking`
+- `redirectedFrom`
+
+## Setup Gate Rule
+
+If operational screen is blocked by readiness:
+- emitted `screen` is `setup`
+- `meta.redirectedFrom` contains requested screen
+
+Agent behavior:
+1. detect redirect
+2. run setup/config remediation via CLI
+3. retry original requested screen
+
+## Panel Parsing
+
+Panel fields:
+- `id`
+- `title`
+- `kind`: `stats | table | text`
+- optional `status`
+
+By kind:
+- `stats`: parse `stats[]` items `{label, value}`
+- `table`: parse `table.columns[]` and `table.rows[][]`
+- `text`: parse `text.lines[]`
+
+## Render Safety Guidance
+
+- `meta.renderSafety == "truncated"` means payload preview was safely truncated.
+- Do not assume full raw object data is present in text panels.
+- Use direct CLI endpoint calls when complete raw payload is required.
+
+## JSON Schema
+
+- Schema file: `docs/schemas/headless-frame.v1.schema.json`