@cli4ai/openapi 1.0.0

package/README.md

@@ -0,0 +1,136 @@
+# @cli4ai/openapi
+
+Turn any OpenAPI spec into a dynamic CLI tool.
+
+## Installation
+
+```bash
+cli4ai add -g openapi
+```
+
+## Usage
+
+### Load and inspect a spec
+
+```bash
+# From URL
+cli4ai run openapi load https://petstore3.swagger.io/api/v3/openapi.json
+
+# From file
+cli4ai run openapi load ./api-spec.json
+```
+
+### List all operations
+
+```bash
+# List all operations
+cli4ai run openapi list https://petstore3.swagger.io/api/v3/openapi.json
+
+# Filter by tag
+cli4ai run openapi list ./spec.json --tag pets
+
+# Filter by method
+cli4ai run openapi list ./spec.json --method POST
+```
+
+### Call an endpoint
+
+```bash
+# By operationId
+cli4ai run openapi call ./spec.json getPetById id=123
+
+# By method and path
+cli4ai run openapi call ./spec.json "GET /pet/{petId}" petId=123
+
+# With query parameters
+cli4ai run openapi call ./spec.json findPetsByStatus status=available
+
+# With request body
+cli4ai run openapi call ./spec.json addPet body='{"name":"Fluffy","status":"available"}'
+
+# Dry run (show request without executing)
+cli4ai run openapi call ./spec.json getPetById id=123 --dry-run
+```
+
+### View schemas
+
+```bash
+# List all schemas
+cli4ai run openapi schema ./spec.json
+
+# View specific schema
+cli4ai run openapi schema ./spec.json Pet
+```
+
+## Authentication
+
+Set environment variables for authentication:
+
+```bash
+# Bearer token
+export OPENAPI_BEARER_TOKEN="your-token"
+
+# API key (uses X-API-Key header or spec-defined header)
+export OPENAPI_API_KEY="your-api-key"
+
+# Override base URL
+export OPENAPI_BASE_URL="https://api.example.com/v2"
+```
+
+## Examples
+
+### Petstore API
+
+```bash
+# Load the spec
+cli4ai run openapi load https://petstore3.swagger.io/api/v3/openapi.json
+
+# List pets
+cli4ai run openapi call https://petstore3.swagger.io/api/v3/openapi.json findPetsByStatus status=available
+
+# Get a specific pet
+cli4ai run openapi call https://petstore3.swagger.io/api/v3/openapi.json getPetById petId=1
+```
+
+### GitHub API
+
+```bash
+export OPENAPI_BEARER_TOKEN="ghp_your_token"
+
+# Get user info
+cli4ai run openapi call https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json "GET /user"
+```
+
+## Parameter Passing
+
+Parameters can be passed in several ways:
+
+```bash
+# key=value format
+cli4ai run openapi call ./spec.json operation param1=value1 param2=value2
+
+# --key=value format
+cli4ai run openapi call ./spec.json operation --param1=value1
+
+# Request body as JSON
+cli4ai run openapi call ./spec.json operation body='{"key":"value"}'
+```
+
+## Output
+
+All output is JSON for easy parsing:
+
+```json
+{
+  "status": 200,
+  "statusText": "OK",
+  "headers": { ... },
+  "data": { ... }
+}
+```
+
+## Limitations
+
+- Only JSON specs are supported (no YAML)
+- OAuth2 flows require manual token acquisition
+- File uploads not yet supported

package/cli4ai.json

@@ -0,0 +1,48 @@
+{
+  "name": "openapi",
+  "version": "1.0.0",
+  "description": "Turn any OpenAPI spec into a dynamic CLI tool",
+  "entry": "run.ts",
+  "runtime": "node",
+  "commands": {
+    "load": {
+      "description": "Load an OpenAPI spec and list available endpoints",
+      "args": [
+        { "name": "spec", "required": true, "description": "URL or file path to OpenAPI spec" }
+      ]
+    },
+    "call": {
+      "description": "Call an API endpoint",
+      "args": [
+        { "name": "spec", "required": true, "description": "URL or file path to OpenAPI spec" },
+        { "name": "operationId", "required": true, "description": "Operation ID or 'METHOD /path'" }
+      ]
+    },
+    "list": {
+      "description": "List all operations in an OpenAPI spec",
+      "args": [
+        { "name": "spec", "required": true, "description": "URL or file path to OpenAPI spec" }
+      ]
+    }
+  },
+  "env": {
+    "OPENAPI_BASE_URL": {
+      "required": false,
+      "description": "Override the base URL from the spec"
+    },
+    "OPENAPI_API_KEY": {
+      "required": false,
+      "description": "API key for authentication"
+    },
+    "OPENAPI_BEARER_TOKEN": {
+      "required": false,
+      "description": "Bearer token for authentication"
+    }
+  },
+  "dependencies": {
+    "@cli4ai/lib": "^1.0.0"
+  },
+  "mcp": {
+    "enabled": true
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@cli4ai/openapi",
+  "version": "1.0.0",
+  "description": "Turn any OpenAPI spec into a dynamic CLI tool",
+  "author": "cliforai",
+  "license": "MIT",
+  "main": "run.ts",
+  "bin": {
+    "openapi": "./run.ts"
+  },
+  "type": "module",
+  "keywords": [
+    "cli4ai",
+    "cli",
+    "ai-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cliforai/packages",
+    "directory": "packages/openapi"
+  },
+  "homepage": "https://github.com/cliforai/packages/tree/main/packages/openapi",
+  "bugs": {
+    "url": "https://github.com/cliforai/packages/issues"
+  },
+  "dependencies": {
+    "@cli4ai/lib": "^1.0.0"
+  },
+  "files": [
+    "run.ts",
+    "cli4ai.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/run.ts

@@ -0,0 +1,504 @@
+#!/usr/bin/env npx tsx
+import { cli, output, log } from '@cli4ai/lib/cli.ts';
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+const program = cli('openapi', '1.0.0', 'Turn any OpenAPI spec into a dynamic CLI tool');
+
+// Types for OpenAPI 3.x
+interface OpenAPISpec {
+  openapi?: string;
+  swagger?: string;
+  info: {
+    title: string;
+    version: string;
+    description?: string;
+  };
+  servers?: Array<{ url: string; description?: string }>;
+  paths: Record<string, PathItem>;
+  components?: {
+    schemas?: Record<string, any>;
+    securitySchemes?: Record<string, SecurityScheme>;
+  };
+}
+
+interface PathItem {
+  get?: Operation;
+  post?: Operation;
+  put?: Operation;
+  patch?: Operation;
+  delete?: Operation;
+  options?: Operation;
+  head?: Operation;
+  parameters?: Parameter[];
+}
+
+interface Operation {
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  parameters?: Parameter[];
+  requestBody?: RequestBody;
+  responses?: Record<string, any>;
+  security?: Array<Record<string, string[]>>;
+  tags?: string[];
+}
+
+interface Parameter {
+  name: string;
+  in: 'path' | 'query' | 'header' | 'cookie';
+  required?: boolean;
+  description?: string;
+  schema?: { type?: string; default?: any; enum?: any[] };
+}
+
+interface RequestBody {
+  required?: boolean;
+  description?: string;
+  content?: Record<string, { schema?: any }>;
+}
+
+interface SecurityScheme {
+  type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+  name?: string;
+  in?: 'query' | 'header' | 'cookie';
+  scheme?: string;
+  bearerFormat?: string;
+}
+
+interface ParsedOperation {
+  method: string;
+  path: string;
+  operationId: string;
+  summary: string;
+  description?: string;
+  parameters: Parameter[];
+  requestBody?: RequestBody;
+  tags: string[];
+}
+
+// Store the source URL for resolving relative server URLs
+let specSourceUrl: string | null = null;
+
+// Load OpenAPI spec from URL or file
+async function loadSpec(specPath: string): Promise<OpenAPISpec> {
+  let content: string;
+
+  if (specPath.startsWith('http://') || specPath.startsWith('https://')) {
+    log(`Fetching spec from ${specPath}...`);
+    specSourceUrl = specPath;
+    const response = await fetch(specPath);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch spec: ${response.status} ${response.statusText}`);
+    }
+    content = await response.text();
+  } else {
+    specSourceUrl = null;
+    const filePath = resolve(process.env.CLI4AI_CWD || process.cwd(), specPath);
+    if (!existsSync(filePath)) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    content = readFileSync(filePath, 'utf-8');
+  }
+
+  try {
+    return JSON.parse(content);
+  } catch {
+    // Try YAML if JSON fails
+    throw new Error('Invalid spec format. Only JSON is currently supported.');
+  }
+}
+
+// Parse all operations from the spec
+function parseOperations(spec: OpenAPISpec): ParsedOperation[] {
+  const operations: ParsedOperation[] = [];
+  const methods = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head'] as const;
+
+  for (const [path, pathItem] of Object.entries(spec.paths || {})) {
+    const pathParams = pathItem.parameters || [];
+
+    for (const method of methods) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+
+      const operationId = operation.operationId || `${method.toUpperCase()} ${path}`;
+
+      operations.push({
+        method: method.toUpperCase(),
+        path,
+        operationId,
+        summary: operation.summary || operation.description || '',
+        description: operation.description,
+        parameters: [...pathParams, ...(operation.parameters || [])],
+        requestBody: operation.requestBody,
+        tags: operation.tags || [],
+      });
+    }
+  }
+
+  return operations;
+}
+
+// Get base URL from spec or environment
+function getBaseUrl(spec: OpenAPISpec): string {
+  if (process.env.OPENAPI_BASE_URL) {
+    return process.env.OPENAPI_BASE_URL.replace(/\/$/, '');
+  }
+
+  if (spec.servers && spec.servers.length > 0) {
+    let serverUrl = spec.servers[0].url.replace(/\/$/, '');
+
+    // Handle relative server URLs
+    if (serverUrl.startsWith('/') && specSourceUrl) {
+      try {
+        const sourceUrl = new URL(specSourceUrl);
+        serverUrl = `${sourceUrl.protocol}//${sourceUrl.host}${serverUrl}`;
+      } catch {
+        // If URL parsing fails, just use the relative path
+      }
+    }
+
+    return serverUrl;
+  }
+
+  // If no servers defined but we have a source URL, use its origin
+  if (specSourceUrl) {
+    try {
+      const sourceUrl = new URL(specSourceUrl);
+      return `${sourceUrl.protocol}//${sourceUrl.host}`;
+    } catch {
+      // Fall through to error
+    }
+  }
+
+  throw new Error('No base URL found. Set OPENAPI_BASE_URL or ensure spec has servers defined.');
+}
+
+// Build headers for authentication
+function buildAuthHeaders(spec: OpenAPISpec): Record<string, string> {
+  const headers: Record<string, string> = {};
+
+  if (process.env.OPENAPI_BEARER_TOKEN) {
+    headers['Authorization'] = `Bearer ${process.env.OPENAPI_BEARER_TOKEN}`;
+  }
+
+  if (process.env.OPENAPI_API_KEY && spec.components?.securitySchemes) {
+    // Find API key security scheme
+    for (const [, scheme] of Object.entries(spec.components.securitySchemes)) {
+      if (scheme.type === 'apiKey' && scheme.in === 'header' && scheme.name) {
+        headers[scheme.name] = process.env.OPENAPI_API_KEY;
+        break;
+      }
+    }
+    // Default to common header names if no scheme found
+    if (!headers['Authorization'] && !Object.keys(headers).some(k => k.toLowerCase().includes('key'))) {
+      headers['X-API-Key'] = process.env.OPENAPI_API_KEY;
+    }
+  }
+
+  return headers;
+}
+
+// Find operation by ID or method+path
+function findOperation(operations: ParsedOperation[], identifier: string): ParsedOperation | undefined {
+  // Try exact operationId match
+  let op = operations.find(o => o.operationId === identifier);
+  if (op) return op;
+
+  // Try case-insensitive operationId match
+  op = operations.find(o => o.operationId.toLowerCase() === identifier.toLowerCase());
+  if (op) return op;
+
+  // Try "METHOD /path" format
+  const match = identifier.match(/^(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\s+(.+)$/i);
+  if (match) {
+    const [, method, path] = match;
+    op = operations.find(o =>
+      o.method.toUpperCase() === method.toUpperCase() &&
+      o.path === path
+    );
+    if (op) return op;
+  }
+
+  return undefined;
+}
+
+// Parse CLI arguments into params
+function parseCallArgs(args: string[]): { params: Record<string, string>; body?: any } {
+  const params: Record<string, string> = {};
+  let body: any = undefined;
+
+  for (const arg of args) {
+    // Handle --param=value or --param value style
+    if (arg.startsWith('--')) {
+      const eqIndex = arg.indexOf('=');
+      if (eqIndex > 0) {
+        const key = arg.slice(2, eqIndex);
+        const value = arg.slice(eqIndex + 1);
+        if (key === 'body') {
+          try {
+            body = JSON.parse(value);
+          } catch {
+            body = value;
+          }
+        } else {
+          params[key] = value;
+        }
+      }
+    } else if (arg.startsWith('-')) {
+      // Skip short flags for now
+    } else if (arg.includes('=')) {
+      const [key, value] = arg.split('=', 2);
+      if (key === 'body') {
+        try {
+          body = JSON.parse(value);
+        } catch {
+          body = value;
+        }
+      } else {
+        params[key] = value;
+      }
+    }
+  }
+
+  return { params, body };
+}
+
+// Execute an API call
+async function executeCall(
+  spec: OpenAPISpec,
+  operation: ParsedOperation,
+  params: Record<string, string>,
+  body?: any
+): Promise<any> {
+  const baseUrl = getBaseUrl(spec);
+
+  // Build URL with path parameters
+  let url = operation.path;
+  for (const param of operation.parameters.filter(p => p.in === 'path')) {
+    const value = params[param.name];
+    if (!value && param.required) {
+      throw new Error(`Missing required path parameter: ${param.name}`);
+    }
+    if (value) {
+      url = url.replace(`{${param.name}}`, encodeURIComponent(value));
+    }
+  }
+
+  // Build query string
+  const queryParams = new URLSearchParams();
+  for (const param of operation.parameters.filter(p => p.in === 'query')) {
+    const value = params[param.name];
+    if (!value && param.required) {
+      throw new Error(`Missing required query parameter: ${param.name}`);
+    }
+    if (value) {
+      queryParams.set(param.name, value);
+    }
+  }
+
+  const queryString = queryParams.toString();
+  const fullUrl = `${baseUrl}${url}${queryString ? '?' + queryString : ''}`;
+
+  // Build headers
+  const headers: Record<string, string> = {
+    'Accept': 'application/json',
+    ...buildAuthHeaders(spec),
+  };
+
+  // Add header parameters
+  for (const param of operation.parameters.filter(p => p.in === 'header')) {
+    const value = params[param.name];
+    if (value) {
+      headers[param.name] = value;
+    }
+  }
+
+  // Build request options
+  const fetchOptions: RequestInit = {
+    method: operation.method,
+    headers,
+  };
+
+  // Add body for non-GET requests
+  if (body && !['GET', 'HEAD'].includes(operation.method)) {
+    headers['Content-Type'] = 'application/json';
+    fetchOptions.body = JSON.stringify(body);
+  }
+
+  log(`${operation.method} ${fullUrl}`);
+
+  const response = await fetch(fullUrl, fetchOptions);
+
+  const contentType = response.headers.get('content-type') || '';
+  let responseData: any;
+
+  if (contentType.includes('application/json')) {
+    responseData = await response.json();
+  } else {
+    responseData = await response.text();
+  }
+
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    headers: Object.fromEntries(response.headers.entries()),
+    data: responseData,
+  };
+}
+
+// Commands
+program
+  .command('load <spec>')
+  .description('Load an OpenAPI spec and show info')
+  .action(async (specPath: string) => {
+    try {
+      const spec = await loadSpec(specPath);
+      const operations = parseOperations(spec);
+
+      output({
+        title: spec.info.title,
+        version: spec.info.version,
+        description: spec.info.description,
+        openapi: spec.openapi || spec.swagger,
+        servers: spec.servers?.map(s => s.url) || [],
+        operationCount: operations.length,
+        tags: [...new Set(operations.flatMap(o => o.tags))],
+      });
+    } catch (error) {
+      output({ error: error instanceof Error ? error.message : String(error) });
+      process.exit(1);
+    }
+  });
+
+program
+  .command('list <spec>')
+  .description('List all operations in an OpenAPI spec')
+  .option('-t, --tag <tag>', 'Filter by tag')
+  .option('-m, --method <method>', 'Filter by HTTP method')
+  .action(async (specPath: string, options: { tag?: string; method?: string }) => {
+    try {
+      const spec = await loadSpec(specPath);
+      let operations = parseOperations(spec);
+
+      if (options.tag) {
+        operations = operations.filter(o =>
+          o.tags.some(t => t.toLowerCase().includes(options.tag!.toLowerCase()))
+        );
+      }
+
+      if (options.method) {
+        operations = operations.filter(o =>
+          o.method.toLowerCase() === options.method!.toLowerCase()
+        );
+      }
+
+      output({
+        count: operations.length,
+        operations: operations.map(o => ({
+          operationId: o.operationId,
+          method: o.method,
+          path: o.path,
+          summary: o.summary,
+          tags: o.tags,
+          parameters: o.parameters.map(p => ({
+            name: p.name,
+            in: p.in,
+            required: p.required || false,
+            type: p.schema?.type,
+          })),
+          hasRequestBody: !!o.requestBody,
+        })),
+      });
+    } catch (error) {
+      output({ error: error instanceof Error ? error.message : String(error) });
+      process.exit(1);
+    }
+  });
+
+program
+  .command('call <spec> <operationId> [args...]')
+  .description('Call an API endpoint. Pass parameters as key=value or --key=value')
+  .option('--dry-run', 'Show the request without executing')
+  .action(async (specPath: string, operationId: string, args: string[], options: { dryRun?: boolean }) => {
+    try {
+      const spec = await loadSpec(specPath);
+      const operations = parseOperations(spec);
+      const operation = findOperation(operations, operationId);
+
+      if (!operation) {
+        const suggestions = operations
+          .filter(o => o.operationId.toLowerCase().includes(operationId.toLowerCase()))
+          .slice(0, 5);
+
+        output({
+          error: `Operation not found: ${operationId}`,
+          suggestions: suggestions.map(o => o.operationId),
+          hint: 'Use "openapi list <spec>" to see all operations',
+        });
+        process.exit(1);
+      }
+
+      const { params, body } = parseCallArgs(args);
+
+      if (options.dryRun) {
+        const baseUrl = getBaseUrl(spec);
+        let url = operation.path;
+        for (const param of operation.parameters.filter(p => p.in === 'path')) {
+          const value = params[param.name] || `{${param.name}}`;
+          url = url.replace(`{${param.name}}`, value);
+        }
+
+        output({
+          dryRun: true,
+          method: operation.method,
+          url: `${baseUrl}${url}`,
+          operation: operation.operationId,
+          parameters: params,
+          body,
+          requiredParams: operation.parameters
+            .filter(p => p.required)
+            .map(p => ({ name: p.name, in: p.in })),
+        });
+        return;
+      }
+
+      const result = await executeCall(spec, operation, params, body);
+      output(result);
+    } catch (error) {
+      output({ error: error instanceof Error ? error.message : String(error) });
+      process.exit(1);
+    }
+  });
+
+program
+  .command('schema <spec> [schemaName]')
+  .description('Show schema definitions from the spec')
+  .action(async (specPath: string, schemaName?: string) => {
+    try {
+      const spec = await loadSpec(specPath);
+      const schemas = spec.components?.schemas || {};
+
+      if (schemaName) {
+        const schema = schemas[schemaName];
+        if (!schema) {
+          output({
+            error: `Schema not found: ${schemaName}`,
+            available: Object.keys(schemas),
+          });
+          process.exit(1);
+        }
+        output({ name: schemaName, schema });
+      } else {
+        output({
+          count: Object.keys(schemas).length,
+          schemas: Object.keys(schemas),
+        });
+      }
+    } catch (error) {
+      output({ error: error instanceof Error ? error.message : String(error) });
+      process.exit(1);
+    }
+  });
+
+program.parse();