@desplega.ai/qa-use 2.8.6 → 2.9.0

package/README.md

@@ -96,6 +96,27 @@ qa-use browser run                     # Interactive REPL mode
 
 Run `qa-use browser --help` for the full list of 29 browser commands.
 
+### API Commands
+
+Dynamic API access powered by live OpenAPI (`/api/v1/openapi.json`) with local cache fallback.
+
+```bash
+qa-use api ls                             # List endpoints from live/cached OpenAPI
+qa-use api /api/v1/tests                  # Call endpoint (method inferred)
+qa-use api -X POST /api/v1/tests-actions/run --input body.json
+qa-use api ls --refresh                   # Force refresh OpenAPI cache
+qa-use api ls --offline                   # Use cached OpenAPI only
+```
+
+| Command | Description |
+|---------|-------------|
+| `qa-use api ls` | List `/api/v1/*` endpoints from OpenAPI |
+| `qa-use api <path>` | Send API request to endpoint |
+| `qa-use api ... --refresh` | Force OpenAPI spec refresh |
+| `qa-use api ... --offline` | Use cached spec without network |
+
+If live spec fetch fails, qa-use falls back to the last cached spec and prints a stale-cache warning.
+
 ### Setup Commands
 
 | Command | Description |

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@desplega.ai/qa-use",
-    "version": "2.8.6",
+    "version": "2.9.0",
     "packageManager": "bun@^1.3.4",
     "description": "QA automation tool for browser testing with MCP server support",
     "type": "module",
@@ -37,10 +37,12 @@
         "test:unit": "node scripts/test-unit.js",
         "test:integration": "node scripts/test-integration.js",
         "test:coverage": "bun test --coverage --preload ./test-setup.ts",
+        "generate:docs": "tsx scripts/generate-docs.ts",
         "generate:readme": "node scripts/generate-readme-tools.js",
         "generate:types": "tsx scripts/generate-types.ts",
+        "check:docs": "tsx scripts/generate-docs.ts && git diff --exit-code src/cli/generated/docs-content.ts || (echo '❌ Docs content is stale — run bun run generate:docs and commit the result' && exit 1)",
         "release": "bun scripts/release.ts",
-        "prepublishOnly": "bun run build && bun lint && bun typecheck",
+        "prepublishOnly": "bun run generate:docs && bun run check:docs && bun run build && bun lint && bun typecheck",
         "cc:validate": "claude plugin validate ."
     },
     "keywords": [

package/dist/src/cli/commands/api/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const apiCommand: Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/cli/commands/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,eAAO,MAAM,UAAU,SAGtB,CAAC"}

package/dist/src/cli/commands/api/index.js

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+import { lsCommand } from './ls.js';
+import { registerApiRequestAction } from './request.js';
+export const apiCommand = registerApiRequestAction(new Command('api').description('Call desplega.ai API endpoints using OpenAPI metadata'), { endpointRequired: false });
+apiCommand.addCommand(lsCommand);
+//# sourceMappingURL=index.js.map

package/dist/src/cli/commands/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/cli/commands/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAExD,MAAM,CAAC,MAAM,UAAU,GAAG,wBAAwB,CAChD,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,uDAAuD,CAAC,EACvF,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAC5B,CAAC;AAEF,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC"}

package/dist/src/cli/commands/api/lib/http.d.ts

@@ -0,0 +1,18 @@
+export interface ExecuteApiRequestOptions {
+    apiUrl: string;
+    apiKey?: string;
+    method: string;
+    path: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    body?: unknown;
+}
+export interface ExecuteApiRequestResult {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    data: unknown;
+}
+export declare function formatApiResponseError(status: number, statusText: string, data: unknown): string;
+export declare function executeApiRequest(options: ExecuteApiRequestOptions): Promise<ExecuteApiRequestResult>;
+//# sourceMappingURL=http.d.ts.map

package/dist/src/cli/commands/api/lib/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../../../../src/cli/commands/api/lib/http.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,OAAO,CAAC;CACf;AAMD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAYhG;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAkClC"}

package/dist/src/cli/commands/api/lib/http.js

@@ -0,0 +1,51 @@
+import axios from 'axios';
+function normalizeApiUrl(apiUrl) {
+    return apiUrl.replace(/\/$/, '');
+}
+export function formatApiResponseError(status, statusText, data) {
+    if (data && typeof data === 'object') {
+        const payload = data;
+        if (payload.message && typeof payload.message === 'string') {
+            return `HTTP ${status} ${statusText}: ${payload.message}`;
+        }
+        if (payload.detail && typeof payload.detail === 'string') {
+            return `HTTP ${status} ${statusText}: ${payload.detail}`;
+        }
+    }
+    return `HTTP ${status} ${statusText}`;
+}
+export async function executeApiRequest(options) {
+    const requestConfig = {
+        method: options.method,
+        baseURL: normalizeApiUrl(options.apiUrl),
+        url: options.path,
+        headers: {
+            ...(options.apiKey ? { Authorization: `Bearer ${options.apiKey}` } : {}),
+            ...options.headers,
+        },
+        params: options.query,
+        data: options.body,
+        timeout: 25000,
+        validateStatus: () => true,
+    };
+    try {
+        const response = await axios.request(requestConfig);
+        const headers = {};
+        for (const [key, value] of Object.entries(response.headers || {})) {
+            headers[key] = Array.isArray(value) ? value.join(', ') : String(value);
+        }
+        return {
+            status: response.status,
+            statusText: response.statusText,
+            headers,
+            data: response.data,
+        };
+    }
+    catch (error) {
+        if (axios.isAxiosError(error)) {
+            throw new Error(error.message);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/src/cli/commands/api/lib/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../../../../src/cli/commands/api/lib/http.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,OAAO,CAAC;AAmB1B,SAAS,eAAe,CAAC,MAAc;IACrC,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,UAAkB,EAAE,IAAa;IACtF,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,IAA6C,CAAC;QAC9D,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC3D,OAAO,QAAQ,MAAM,IAAI,UAAU,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC;QAC5D,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACzD,OAAO,QAAQ,MAAM,IAAI,UAAU,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,MAAM,IAAI,UAAU,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAiC;IAEjC,MAAM,aAAa,GAAuB;QACxC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC;QACxC,GAAG,EAAE,OAAO,CAAC,IAAI;QACjB,OAAO,EAAE;YACP,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxE,GAAG,OAAO,CAAC,OAAO;SACnB;QACD,MAAM,EAAE,OAAO,CAAC,KAAK;QACrB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,KAAK;QACd,cAAc,EAAE,GAAG,EAAE,CAAC,IAAI;KAC3B,CAAC;IAEF,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QACpD,MAAM,OAAO,GAA2B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;YAClE,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACzE,CAAC;QAED,OAAO;YACL,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,OAAO;YACP,IAAI,EAAE,QAAQ,CAAC,IAAI;SACpB,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/src/cli/commands/api/lib/openapi-cache.d.ts

@@ -0,0 +1,10 @@
+export interface CachedOpenApiSpec {
+    apiUrl: string;
+    fetchedAt: string;
+    etag?: string;
+    specHash: string;
+    spec: unknown;
+}
+export declare function readOpenApiCache(apiUrl: string): CachedOpenApiSpec | undefined;
+export declare function writeOpenApiCache(entry: CachedOpenApiSpec): void;
+//# sourceMappingURL=openapi-cache.d.ts.map

package/dist/src/cli/commands/api/lib/openapi-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-cache.d.ts","sourceRoot":"","sources":["../../../../../../src/cli/commands/api/lib/openapi-cache.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf;AA+BD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAG9E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAShE"}

package/dist/src/cli/commands/api/lib/openapi-cache.js

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const CONFIG_PATH = join(homedir(), '.qa-use.json');
+function normalizeApiUrl(apiUrl) {
+    return apiUrl.replace(/\/$/, '');
+}
+function readConfig() {
+    if (!existsSync(CONFIG_PATH)) {
+        return {};
+    }
+    try {
+        return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeConfig(config) {
+    try {
+        writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+    }
+    catch {
+        // Ignore cache write failures (permissions, disk full, etc.)
+    }
+}
+export function readOpenApiCache(apiUrl) {
+    const key = normalizeApiUrl(apiUrl);
+    return readConfig().openapi_cache?.[key];
+}
+export function writeOpenApiCache(entry) {
+    const key = normalizeApiUrl(entry.apiUrl);
+    const config = readConfig();
+    config.openapi_cache = config.openapi_cache || {};
+    config.openapi_cache[key] = {
+        ...entry,
+        apiUrl: key,
+    };
+    writeConfig(config);
+}
+//# sourceMappingURL=openapi-cache.js.map

package/dist/src/cli/commands/api/lib/openapi-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-cache.js","sourceRoot":"","sources":["../../../../../../src/cli/commands/api/lib/openapi-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,cAAc,CAAC,CAAC;AAepD,SAAS,eAAe,CAAC,MAAc;IACrC,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,UAAU;IACjB,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAgB,CAAC;IACvE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,MAAmB;IACtC,IAAI,CAAC;QACH,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,6DAA6D;IAC/D,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,GAAG,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACpC,OAAO,UAAU,EAAE,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAwB;IACxD,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,EAAE,CAAC;IAClD,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG;QAC1B,GAAG,KAAK;QACR,MAAM,EAAE,GAAG;KACZ,CAAC;IACF,WAAW,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC"}

package/dist/src/cli/commands/api/lib/openapi-errors.d.ts

@@ -0,0 +1,8 @@
+export declare class OpenApiError extends Error {
+    constructor(message: string);
+}
+export declare function formatMissingSpecError(apiUrl: string, detail?: string): string;
+export declare function formatInvalidSpecError(detail: string): string;
+export declare function formatStaleCacheWarning(apiUrl: string, fetchedAt: string, reason: string): string;
+export declare function formatOfflineCacheMissError(apiUrl: string): string;
+//# sourceMappingURL=openapi-errors.d.ts.map

package/dist/src/cli/commands/api/lib/openapi-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-errors.d.ts","sourceRoot":"","sources":["../../../../../../src/cli/commands/api/lib/openapi-errors.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAG9E;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjG;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElE"}

package/dist/src/cli/commands/api/lib/openapi-errors.js

@@ -0,0 +1,20 @@
+export class OpenApiError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OpenApiError';
+    }
+}
+export function formatMissingSpecError(apiUrl, detail) {
+    const suffix = detail ? `\nReason: ${detail}` : '';
+    return `Unable to load OpenAPI spec from ${apiUrl}/api/v1/openapi.json and no cached spec is available.${suffix}\nRun the command again when online or provide credentials with QA_USE_API_KEY.`;
+}
+export function formatInvalidSpecError(detail) {
+    return `OpenAPI spec is invalid: ${detail}`;
+}
+export function formatStaleCacheWarning(apiUrl, fetchedAt, reason) {
+    return `Warning: using stale cached OpenAPI spec for ${apiUrl} (cached at ${fetchedAt}). Refresh failed: ${reason}`;
+}
+export function formatOfflineCacheMissError(apiUrl) {
+    return `Offline mode requested, but no cached OpenAPI spec exists for ${apiUrl}. Run with --refresh while online first.`;
+}
+//# sourceMappingURL=openapi-errors.js.map

package/dist/src/cli/commands/api/lib/openapi-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-errors.js","sourceRoot":"","sources":["../../../../../../src/cli/commands/api/lib/openapi-errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,MAAe;IACpE,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,aAAa,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACnD,OAAO,oCAAoC,MAAM,wDAAwD,MAAM,iFAAiF,CAAC;AACnM,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAc;IACnD,OAAO,4BAA4B,MAAM,EAAE,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,MAAc,EAAE,SAAiB,EAAE,MAAc;IACvF,OAAO,gDAAgD,MAAM,eAAe,SAAS,sBAAsB,MAAM,EAAE,CAAC;AACtH,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,MAAc;IACxD,OAAO,iEAAiE,MAAM,0CAA0C,CAAC;AAC3H,CAAC"}

package/dist/src/cli/commands/api/lib/openapi-spec.d.ts

@@ -0,0 +1,62 @@
+export type OpenApiRefreshMode = 'default' | 'refresh' | 'offline';
+interface OpenApiPathOperation {
+    summary?: string;
+    operationId?: string;
+    tags?: string[];
+    parameters?: Array<{
+        name?: string;
+        in?: string;
+        required?: boolean;
+        schema?: {
+            type?: string;
+        };
+    }>;
+    requestBody?: {
+        required?: boolean;
+    };
+}
+interface OpenApiSpecDocument {
+    openapi: string;
+    paths: Record<string, Record<string, OpenApiPathOperation>>;
+    components?: {
+        securitySchemes?: Record<string, unknown>;
+    };
+}
+export interface NormalizedOperation {
+    key: string;
+    method: string;
+    path: string;
+    summary?: string;
+    operationId?: string;
+    tags: string[];
+    parameters: Array<{
+        name: string;
+        in: 'path' | 'query' | 'header' | 'cookie' | 'unknown';
+        required: boolean;
+        schemaType?: string;
+    }>;
+    parameterCount: number;
+    requestBodyRequired: boolean;
+}
+export interface OpenApiSpecIndex {
+    raw: OpenApiSpecDocument;
+    operations: Record<string, NormalizedOperation>;
+}
+export interface LoadedOpenApiSpec {
+    source: 'live' | 'cache';
+    stale: boolean;
+    apiUrl: string;
+    fetchedAt: string;
+    etag?: string;
+    specHash: string;
+    index: OpenApiSpecIndex;
+    warnings: string[];
+}
+export interface LoadOpenApiSpecOptions {
+    apiUrl: string;
+    apiKey?: string;
+    refreshMode?: OpenApiRefreshMode;
+}
+export declare function loadOpenApiSpec(options: LoadOpenApiSpecOptions): Promise<LoadedOpenApiSpec>;
+export {};
+//# sourceMappingURL=openapi-spec.d.ts.map

package/dist/src/cli/commands/api/lib/openapi-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-spec.d.ts","sourceRoot":"","sources":["../../../../../../src/cli/commands/api/lib/openapi-spec.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEnE,UAAU,oBAAoB;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,MAAM,CAAC,EAAE;YACP,IAAI,CAAC,EAAE,MAAM,CAAC;SACf,CAAC;KACH,CAAC,CAAC;IACH,WAAW,CAAC,EAAE;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;CACH;AAED,UAAU,mBAAmB;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAC5D,UAAU,CAAC,EAAE;QACX,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC3C,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;QACvD,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,mBAAmB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,gBAAgB,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAkHD,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0FjG"}

package/dist/src/cli/commands/api/lib/openapi-spec.js

@@ -0,0 +1,166 @@
+import { createHash } from 'node:crypto';
+import { readOpenApiCache, writeOpenApiCache } from './openapi-cache.js';
+import { formatInvalidSpecError, formatMissingSpecError, formatOfflineCacheMissError, formatStaleCacheWarning, OpenApiError, } from './openapi-errors.js';
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head']);
+function normalizeApiUrl(apiUrl) {
+    return apiUrl.replace(/\/$/, '');
+}
+function buildOpenApiUrl(apiUrl) {
+    return `${normalizeApiUrl(apiUrl)}/api/v1/openapi.json`;
+}
+function computeSpecHash(spec) {
+    return createHash('sha256').update(JSON.stringify(spec)).digest('hex');
+}
+function validateOpenApiDocument(spec) {
+    if (!spec || typeof spec !== 'object') {
+        throw new OpenApiError(formatInvalidSpecError('expected an object payload'));
+    }
+    const candidate = spec;
+    if (!candidate.openapi || typeof candidate.openapi !== 'string') {
+        throw new OpenApiError(formatInvalidSpecError('missing `openapi` version string'));
+    }
+    if (!candidate.paths || typeof candidate.paths !== 'object' || Array.isArray(candidate.paths)) {
+        throw new OpenApiError(formatInvalidSpecError('missing `paths` object'));
+    }
+    if (candidate.components &&
+        candidate.components.securitySchemes !== undefined &&
+        (typeof candidate.components.securitySchemes !== 'object' ||
+            Array.isArray(candidate.components.securitySchemes))) {
+        throw new OpenApiError(formatInvalidSpecError('`components.securitySchemes` must be an object'));
+    }
+    return candidate;
+}
+function normalizeOperations(spec) {
+    const operations = {};
+    for (const [path, pathItem] of Object.entries(spec.paths)) {
+        if (!pathItem || typeof pathItem !== 'object') {
+            continue;
+        }
+        for (const [method, operation] of Object.entries(pathItem)) {
+            const normalizedMethod = method.toLowerCase();
+            if (!HTTP_METHODS.has(normalizedMethod)) {
+                continue;
+            }
+            const op = operation || {};
+            const key = `${normalizedMethod.toUpperCase()} ${path}`;
+            operations[key] = {
+                key,
+                method: normalizedMethod.toUpperCase(),
+                path,
+                summary: op.summary,
+                operationId: op.operationId,
+                tags: Array.isArray(op.tags) ? op.tags.filter((tag) => typeof tag === 'string') : [],
+                parameters: Array.isArray(op.parameters)
+                    ? op.parameters
+                        .filter((parameter) => Boolean(parameter?.name))
+                        .map((parameter) => ({
+                        name: String(parameter.name),
+                        in: parameter.in === 'path' ||
+                            parameter.in === 'query' ||
+                            parameter.in === 'header' ||
+                            parameter.in === 'cookie'
+                            ? parameter.in
+                            : 'unknown',
+                        required: Boolean(parameter.required),
+                        schemaType: parameter.schema?.type,
+                    }))
+                    : [],
+                parameterCount: Array.isArray(op.parameters) ? op.parameters.length : 0,
+                requestBodyRequired: Boolean(op.requestBody?.required),
+            };
+        }
+    }
+    return operations;
+}
+function createIndex(spec) {
+    return {
+        raw: spec,
+        operations: normalizeOperations(spec),
+    };
+}
+function fromCache(cache, stale, warning) {
+    const spec = validateOpenApiDocument(cache.spec);
+    return {
+        source: 'cache',
+        stale,
+        apiUrl: cache.apiUrl,
+        fetchedAt: cache.fetchedAt,
+        etag: cache.etag,
+        specHash: cache.specHash,
+        index: createIndex(spec),
+        warnings: warning ? [warning] : [],
+    };
+}
+export async function loadOpenApiSpec(options) {
+    const apiUrl = normalizeApiUrl(options.apiUrl);
+    const refreshMode = options.refreshMode || 'default';
+    const cache = readOpenApiCache(apiUrl);
+    if (refreshMode === 'offline') {
+        if (!cache) {
+            throw new OpenApiError(formatOfflineCacheMissError(apiUrl));
+        }
+        return fromCache(cache, false);
+    }
+    const headers = {};
+    if (options.apiKey) {
+        headers.Authorization = `Bearer ${options.apiKey}`;
+    }
+    if (refreshMode !== 'refresh' && cache?.etag) {
+        headers['If-None-Match'] = cache.etag;
+    }
+    let response;
+    try {
+        response = await fetch(buildOpenApiUrl(apiUrl), {
+            method: 'GET',
+            headers,
+        });
+    }
+    catch (error) {
+        if (!cache) {
+            throw new OpenApiError(formatMissingSpecError(apiUrl, error instanceof Error ? error.message : 'network failure'));
+        }
+        return fromCache(cache, true, formatStaleCacheWarning(apiUrl, cache.fetchedAt, error instanceof Error ? error.message : 'network failure'));
+    }
+    if (response.status === 304) {
+        if (!cache) {
+            throw new OpenApiError(formatMissingSpecError(apiUrl, 'received 304 without cached spec'));
+        }
+        return fromCache(cache, false);
+    }
+    if (!response.ok) {
+        const reason = `HTTP ${response.status}`;
+        if (!cache) {
+            throw new OpenApiError(formatMissingSpecError(apiUrl, reason));
+        }
+        return fromCache(cache, true, formatStaleCacheWarning(apiUrl, cache.fetchedAt, reason));
+    }
+    let jsonPayload;
+    try {
+        jsonPayload = await response.json();
+    }
+    catch {
+        throw new OpenApiError(formatInvalidSpecError('response body is not valid JSON'));
+    }
+    const spec = validateOpenApiDocument(jsonPayload);
+    const specHash = computeSpecHash(spec);
+    const fetchedAt = new Date().toISOString();
+    const etag = response.headers.get('etag') ?? undefined;
+    writeOpenApiCache({
+        apiUrl,
+        fetchedAt,
+        etag,
+        specHash,
+        spec,
+    });
+    return {
+        source: 'live',
+        stale: false,
+        apiUrl,
+        fetchedAt,
+        etag,
+        specHash,
+        index: createIndex(spec),
+        warnings: [],
+    };
+}
+//# sourceMappingURL=openapi-spec.js.map

package/dist/src/cli/commands/api/lib/openapi-spec.js.map

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

package/dist/src/cli/commands/api/lib/output.d.ts

@@ -0,0 +1,8 @@
+import type { NormalizedOperation } from './openapi-spec.js';
+export interface RenderListOptions {
+    source: 'live' | 'cache';
+    stale: boolean;
+    json?: boolean;
+}
+export declare function renderOperationList(operations: NormalizedOperation[], options: RenderListOptions): string;
+//# sourceMappingURL=output.d.ts.map

package/dist/src/cli/commands/api/lib/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../../../../src/cli/commands/api/lib/output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AASD,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,mBAAmB,EAAE,EACjC,OAAO,EAAE,iBAAiB,GACzB,MAAM,CAkCR"}

package/dist/src/cli/commands/api/lib/output.js

@@ -0,0 +1,31 @@
+function pad(value, width) {
+    if (value.length >= width) {
+        return value;
+    }
+    return `${value}${' '.repeat(width - value.length)}`;
+}
+export function renderOperationList(operations, options) {
+    if (options.json) {
+        return JSON.stringify({
+            source: options.source,
+            stale: options.stale,
+            count: operations.length,
+            operations,
+        }, null, 2);
+    }
+    if (operations.length === 0) {
+        return `No API operations matched your filters.\nSource: ${options.source}${options.stale ? ' (stale cache)' : ''}`;
+    }
+    const methodWidth = Math.max(6, ...operations.map((operation) => operation.method.length));
+    const pathWidth = Math.max(20, ...operations.map((operation) => operation.path.length));
+    const lines = [
+        `Source: ${options.source}${options.stale ? ' (stale cache)' : ''}`,
+        `${pad('METHOD', methodWidth)}  ${pad('PATH', pathWidth)}  SUMMARY`,
+        `${'-'.repeat(methodWidth)}  ${'-'.repeat(pathWidth)}  ${'-'.repeat(32)}`,
+    ];
+    for (const operation of operations) {
+        lines.push(`${pad(operation.method, methodWidth)}  ${pad(operation.path, pathWidth)}  ${operation.summary || ''}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=output.js.map

package/dist/src/cli/commands/api/lib/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../../../../../src/cli/commands/api/lib/output.ts"],"names":[],"mappings":"AAQA,SAAS,GAAG,CAAC,KAAa,EAAE,KAAa;IACvC,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,GAAG,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,UAAiC,EACjC,OAA0B;IAE1B,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC,SAAS,CACnB;YACE,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,KAAK,EAAE,UAAU,CAAC,MAAM;YACxB,UAAU;SACX,EACD,IAAI,EACJ,CAAC,CACF,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,oDAAoD,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACtH,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3F,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAExF,MAAM,KAAK,GAAG;QACZ,WAAW,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,EAAE;QACnE,GAAG,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,KAAK,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,WAAW;QACnE,GAAG,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE;KAC1E,CAAC;IAEF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CACR,GAAG,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,KAAK,SAAS,CAAC,OAAO,IAAI,EAAE,EAAE,CACvG,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/src/cli/commands/api/ls.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const lsCommand: Command;
+//# sourceMappingURL=ls.d.ts.map

package/dist/src/cli/commands/api/ls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ls.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/api/ls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwBpC,eAAO,MAAM,SAAS,SAwElB,CAAC"}

package/dist/src/cli/commands/api/ls.js

@@ -0,0 +1,76 @@
+import { Command } from 'commander';
+import { loadConfig } from '../../lib/config.js';
+import { error, formatError, warning } from '../../lib/output.js';
+import { loadOpenApiSpec } from './lib/openapi-spec.js';
+import { renderOperationList } from './lib/output.js';
+function getRefreshMode(options) {
+    if (options.refresh && options.offline) {
+        throw new Error('Cannot use --refresh and --offline together');
+    }
+    if (options.refresh)
+        return 'refresh';
+    if (options.offline)
+        return 'offline';
+    return 'default';
+}
+export const lsCommand = new Command('ls')
+    .description('List available /api/v1 endpoints from OpenAPI')
+    .option('-X, --method <method>', 'Filter by HTTP method (GET, POST, PUT, PATCH, DELETE)')
+    .option('-q, --query <text>', 'Filter by text in path, summary, or operation id')
+    .option('--tag <tag>', 'Filter by OpenAPI tag')
+    .option('--json', 'Render JSON output')
+    .option('--refresh', 'Force refresh OpenAPI spec from server')
+    .option('--offline', 'Use cached OpenAPI spec only')
+    .action(async (options, command) => {
+    try {
+        const parentOptions = (command.parent?.opts() || {});
+        const effectiveOptions = {
+            ...parentOptions,
+            ...options,
+        };
+        const config = await loadConfig();
+        const apiUrl = config.api_url || process.env.QA_USE_API_URL || 'https://api.desplega.ai';
+        const apiKey = config.api_key || process.env.QA_USE_API_KEY;
+        const refreshMode = getRefreshMode(effectiveOptions);
+        const loadedSpec = await loadOpenApiSpec({ apiUrl, apiKey, refreshMode });
+        if (loadedSpec.stale) {
+            for (const message of loadedSpec.warnings) {
+                console.error(warning(message));
+            }
+        }
+        let operations = Object.values(loadedSpec.index.operations);
+        if (effectiveOptions.method) {
+            const expectedMethod = effectiveOptions.method.toUpperCase();
+            operations = operations.filter((operation) => operation.method === expectedMethod);
+        }
+        if (effectiveOptions.query) {
+            const query = effectiveOptions.query.toLowerCase();
+            operations = operations.filter((operation) => {
+                return (operation.path.toLowerCase().includes(query) ||
+                    (operation.summary || '').toLowerCase().includes(query) ||
+                    (operation.operationId || '').toLowerCase().includes(query));
+            });
+        }
+        if (effectiveOptions.tag) {
+            const tag = effectiveOptions.tag.toLowerCase();
+            operations = operations.filter((operation) => operation.tags.some((operationTag) => operationTag.toLowerCase() === tag));
+        }
+        operations.sort((a, b) => {
+            const pathCompare = a.path.localeCompare(b.path);
+            if (pathCompare !== 0) {
+                return pathCompare;
+            }
+            return a.method.localeCompare(b.method);
+        });
+        console.log(renderOperationList(operations, {
+            source: loadedSpec.source,
+            stale: loadedSpec.stale,
+            json: effectiveOptions.json,
+        }));
+    }
+    catch (err) {
+        console.error(error(`Failed to list API operations: ${formatError(err)}`));
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=ls.js.map