@statechange/xano-cli 0.2.0

package/README.md

@@ -0,0 +1,251 @@
+# @statechange/xano-cli
+
+CLI for Xano workspace management, performance analysis, XanoScript generation, and operational insights. Uses Xano's private APIs to provide capabilities not available through the standard Meta API.
+
+## Installation
+
+```bash
+npm install -g @statechange/xano-cli
+```
+
+Or run directly with npx:
+
+```bash
+npx @statechange/xano-cli <command>
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate with your StateChange API key
+sc-xano auth init --api-key <your-api-key>
+
+# 2. Verify connection and see available instances
+sc-xano auth whoami
+
+# 3. Check your Xano session health
+sc-xano auth status
+
+# 4. Run commands (instance, workspace, and token auto-resolve)
+sc-xano inventory workspace
+sc-xano performance top-endpoints
+sc-xano audit workspace
+```
+
+Once authenticated, the CLI auto-resolves your Xano instance, workspace, and token from the StateChange backend. No extra flags needed if you have a single instance.
+
+## Authentication & Session Management
+
+The CLI uses a StateChange API key to fetch Xano credentials automatically:
+
+```bash
+# Interactive setup
+sc-xano auth init
+
+# Or provide key directly
+sc-xano auth init --api-key <key>
+
+# Check auth status
+sc-xano auth whoami
+
+# Check Xano token health
+sc-xano auth status
+
+# Override defaults
+sc-xano auth set-instance <hostname> --workspace <id>
+```
+
+### Session Freshness
+
+Your Xano session token is refreshed whenever you open Xano in the browser with the StateChange extension active. The CLI monitors token health automatically:
+
+- **Fresh token** — commands run normally
+- **Stale token** — a warning is shown, but commands still proceed
+- **Expired token** — a warning is shown; if Xano rejects the request, the CLI prompts you to open Xano and polls until the session is refreshed
+- **401/403 errors** — the CLI advises running `auth status` to diagnose
+
+Run `sc-xano auth status` at any time to check your session.
+
+### Fallback Options
+
+You can also provide credentials directly via flags or environment variables:
+
+| Flag | Environment Variable | Description |
+|------|---------------------|-------------|
+| `--api-key` | `STATECHANGE_API_KEY` | StateChange API key |
+| `--instance` | `XANO_INSTANCE` | Xano instance hostname |
+| `--workspace` | `XANO_WORKSPACE` | Workspace ID |
+| `--token` | `XANO_TOKEN` | Xano API token |
+| `--branch` | — | Branch ID (default: 0) |
+| `--format` | — | Output format: `table`, `json`, or `yaml` |
+
+All commands support `--format table` (default, human-readable), `--format json`, and `--format yaml`. The yaml format is recommended for AI/LLM consumption.
+
+## Commands
+
+### `inventory` — Workspace Overview
+
+```bash
+sc-xano inventory workspace           # Object counts summary
+sc-xano inventory functions            # List functions with tags
+sc-xano inventory tables               # List database tables
+sc-xano inventory tasks                # List background tasks
+sc-xano inventory triggers             # List triggers
+sc-xano inventory addons               # List addons
+sc-xano inventory middleware           # List middleware
+sc-xano inventory mcp-servers          # List MCP/toolset servers
+```
+
+### `performance` — Performance Analysis
+
+Find slow endpoints, trace execution bottlenecks, and deep-dive into request stacks.
+
+```bash
+# Top slowest endpoints (last 24 hours)
+sc-xano performance top-endpoints
+sc-xano performance top-endpoints --lookback 48 --limit 10
+
+# Trace: aggregate stack analysis across multiple executions
+sc-xano performance trace endpoint <query-id> --samples 10
+sc-xano performance trace task <task-id> --samples 10
+sc-xano performance trace trigger <trigger-id> --samples 10
+
+# Deep-dive: full stack expansion for a single request
+sc-xano performance deep-dive <request-id>
+
+# Scan functions for nested slow steps
+sc-xano performance scan-functions
+sc-xano performance scan-functions --min-nesting 3
+
+# Use yaml for AI-driven analysis
+sc-xano performance top-endpoints --format yaml
+sc-xano performance deep-dive <request-id> --format yaml
+```
+
+**Trace** aggregates timing data across N samples, showing duration percentiles (avg, p50, p95, p99) and per-step breakdown by `_xsid`.
+
+**Deep-dive** expands a single request's stack into a tree with direct vs rollup timing, percentage breakdowns, loop iteration counts, and warnings for slow steps inside loops (N+1 queries, lambda blocks, external API calls).
+
+### `xray` — Function Analysis
+
+Analyze function internals: step hierarchy, performance warnings, dependencies.
+
+```bash
+sc-xano xray function --id <function-id>
+sc-xano xray scan-workspace
+sc-xano xray scan-workspace --include-warnings
+```
+
+### `audit` — Workspace Auditing
+
+```bash
+sc-xano audit workspace        # API configurations
+sc-xano audit swagger           # Unsecured Swagger endpoints
+sc-xano audit database          # Table schemas and indexes
+sc-xano audit middleware
+sc-xano audit addons
+sc-xano audit tasks
+sc-xano audit triggers
+sc-xano audit mcp-servers
+```
+
+### `secure` — Security Management
+
+```bash
+sc-xano secure swagger --app-id <id> --disable           # Disable Swagger
+sc-xano secure swagger --app-id <id> --require-token      # Require token
+```
+
+### `history` — Execution History
+
+```bash
+sc-xano history requests                          # Recent API requests
+sc-xano history requests --page 2                 # Paginate
+sc-xano history request <request-id>              # Detailed request info
+sc-xano history tasks <task-id>                   # Task execution history
+sc-xano history task-run <task-id> <run-id>       # Detailed task run
+sc-xano history triggers <trigger-id>             # Trigger history
+sc-xano history mcp-servers <tool-id>             # MCP server history
+```
+
+### `logs` — Log Retention Management
+
+View and control how much execution history Xano retains per endpoint, task, or trigger.
+
+```bash
+# View retention settings
+sc-xano logs show                             # All objects
+sc-xano logs show --custom-only               # Only non-default settings
+sc-xano logs show endpoint <id>               # Single endpoint with parent app context
+sc-xano logs show app <id>                    # App + all its endpoints
+
+# Update retention
+sc-xano logs set endpoint <id> --limit -1     # Unlimited (for debugging)
+sc-xano logs set endpoint <id> --limit 100    # Default
+sc-xano logs set endpoint <id> --limit 0      # Disable
+
+# Watch for new executions in real-time
+sc-xano logs watch endpoint <id>
+```
+
+Useful when performance deep-dives show `stack_truncated: true` — set the limit to unlimited, trigger a new execution, then deep-dive the untruncated result.
+
+### `xanoscript` — XanoScript Generation & Conversion
+
+```bash
+sc-xano xanoscript generate function <id>
+sc-xano xanoscript generate table <id>
+sc-xano xanoscript generate api <id>
+
+sc-xano xanoscript export-all --type function
+sc-xano xanoscript export-all --type table --output-dir ./backup
+
+sc-xano xanoscript convert myfunction.xs
+cat myfunction.xs | sc-xano xanoscript convert
+```
+
+### `health` — Instance Health (Master API)
+
+```bash
+sc-xano health instances
+sc-xano health database --instance-id <id>
+sc-xano health clear-history --instance-id <id>
+sc-xano health restart-tasks --instance-id <id>
+```
+
+### `flush` — Cache Management
+
+```bash
+sc-xano flush     # Clear cached sink data
+```
+
+## How It Works
+
+This CLI uses Xano's private `api:mvp-admin` endpoints (the same APIs that power the Xano dashboard) to provide operational capabilities beyond the public Meta API.
+
+| Capability | This CLI | Xano MCP |
+|-----------|----------|----------|
+| Live workspace data | Yes | No |
+| Performance analysis | Yes | No |
+| Execution history | Yes | No |
+| Log retention management | Yes | No |
+| XanoScript generation | Yes | No |
+| XanoScript validation | No | Yes |
+| XanoScript docs | No | Yes |
+| Meta API docs | No | Yes |
+
+## AI Integration
+
+The recommended way to use this CLI with AI coding assistants is to install the skills:
+
+```bash
+npx skills add @statechange/xano-cli
+```
+
+This teaches your AI agent how to use the CLI for workspace management and performance analysis workflows. Skills are included in the `skills/` directory of the package.
+
+For manual use, add `--format yaml` to any command for the most token-efficient structured output.
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,22 @@
+/**
+ * StateChange CLI Authentication
+ * Manages long-lived API key from file, env var, or command line
+ */
+export interface AuthConfig {
+    apiKey: string;
+    authToken?: string;
+    authTokenExpires?: number;
+    xanoInstance?: string;
+    xanoWorkspace?: number;
+}
+export declare function getAuthFilePath(): string;
+export declare function loadAuthFromFile(): AuthConfig | null;
+export declare function saveAuthToFile(config: AuthConfig): void;
+export declare function getStateChangeApiKey(options?: {
+    apiKey?: string;
+}): string | null;
+/**
+ * Exchange API key for auth token
+ */
+export declare function getAuthToken(apiKey: string): Promise<string>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wBAAgB,gBAAgB,IAAI,UAAU,GAAG,IAAI,CASpD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAQvD;AAED,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CASjF;AAID;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkDlE"}

package/dist/auth.js

@@ -0,0 +1,94 @@
+/**
+ * StateChange CLI Authentication
+ * Manages long-lived API key from file, env var, or command line
+ */
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const AUTH_FILE_PATH = join(homedir(), ".statechange", "auth.json");
+export function getAuthFilePath() {
+    return AUTH_FILE_PATH;
+}
+export function loadAuthFromFile() {
+    try {
+        const content = readFileSync(AUTH_FILE_PATH, "utf-8");
+        const config = JSON.parse(content);
+        if (!config.apiKey)
+            return null;
+        return config;
+    }
+    catch (e) {
+        return null;
+    }
+}
+export function saveAuthToFile(config) {
+    const dir = join(homedir(), ".statechange");
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch (e) {
+        // Directory might already exist
+    }
+    writeFileSync(AUTH_FILE_PATH, JSON.stringify(config, null, 2), "utf-8");
+}
+export function getStateChangeApiKey(options) {
+    // 1. Command line flag
+    if (options?.apiKey)
+        return options.apiKey;
+    // 2. Environment variable
+    if (process.env.STATECHANGE_API_KEY)
+        return process.env.STATECHANGE_API_KEY;
+    // 3. Auth file
+    const auth = loadAuthFromFile();
+    if (auth?.apiKey)
+        return auth.apiKey;
+    return null;
+}
+const STATECHANGE_BACKEND_URL = "https://api.statechange.ai/api:jKMCYXQa/";
+/**
+ * Exchange API key for auth token
+ */
+export async function getAuthToken(apiKey) {
+    // Check if we have a cached valid token
+    const auth = loadAuthFromFile();
+    if (auth?.authToken &&
+        auth?.authTokenExpires &&
+        Date.now() < auth.authTokenExpires) {
+        return auth.authToken;
+    }
+    // Exchange API key for token
+    const response = await fetch(`${STATECHANGE_BACKEND_URL}auth/key`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ key: apiKey }),
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        if (response.status === 401) {
+            throw new Error("Invalid or expired API key");
+        }
+        throw new Error(`Failed to authenticate: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+    const data = (await response.json());
+    const token = data.token;
+    // Cache the token (expires in 24 hours, cache for 23 hours to be safe)
+    const expiresAt = Date.now() + 23 * 60 * 60 * 1000; // 23 hours in milliseconds
+    if (auth) {
+        auth.authToken = token;
+        auth.authTokenExpires = expiresAt;
+        saveAuthToFile(auth);
+    }
+    else {
+        // Create new config with just the token (API key should already be saved)
+        const newAuth = loadAuthFromFile();
+        if (newAuth) {
+            newAuth.authToken = token;
+            newAuth.authTokenExpires = expiresAt;
+            saveAuthToFile(newAuth);
+        }
+    }
+    return token;
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/commands/audit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Audit CLI Commands
+ */
+import { Command } from "commander";
+export declare function createAuditCommand(program: Command): Command;
+//# sourceMappingURL=audit.d.ts.map

package/dist/commands/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/commands/audit.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,WAwUlD"}