@powerduck/openapi-cli 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Public types for @powerduck/openapi-cli.
+ */
+type ProtocolName = "http" | "sse" | "websocket" | "graphql" | "grpc" | "mcp";
+type ReportFormat = "json" | "cli" | "html";
+type TestStatus = "passed" | "failed" | "skipped" | "error";
+interface AuthConfig {
+    type: "bearer" | "basic" | "apikey" | "none";
+    token?: string;
+    username?: string;
+    password?: string;
+    key?: string;
+    value?: string;
+    in?: "header" | "query";
+}
+interface TlsConfig {
+    /** Path to a CA certificate bundle (PEM). */
+    caCert?: string;
+    /** Path to a client certificate (PEM) for mTLS. */
+    clientCert?: string;
+    /** Path to a client private key (PEM) for mTLS. */
+    clientKey?: string;
+    /** Skip TLS certificate verification (insecure). */
+    strictSSL?: boolean;
+}
+interface FilterConfig {
+    /** Only test these HTTP methods (e.g. ["get","post"]). */
+    methods?: string[];
+    /** Only test paths matching any of these regex patterns. */
+    paths?: string[];
+    /** Only test operations with these tags. */
+    tags?: string[];
+    /** Only test these operationIds. */
+    operationIds?: string[];
+}
+interface CliConfig {
+    /** Path to the OpenAPI 3.2 JSON file. */
+    specPath: string;
+    /** Override the server URL from the spec. */
+    serverUrl?: string;
+    /** Directory to write report files. Default: "./openapi-cli-report". */
+    outputDir?: string;
+    /** Report formats to generate. Default: ["json","cli","html"]. */
+    formats?: ReportFormat[];
+    /** Filter which operations to test. */
+    filter?: FilterConfig;
+    /** Max concurrent requests. Default: 5. */
+    concurrency?: number;
+    /** Per-request timeout in ms. Default: 30000. */
+    timeout?: number;
+    /** HTTP(S) proxy URL (e.g. http://proxy:8080). */
+    proxy?: string;
+    /** TLS / certificate configuration. */
+    tls?: TlsConfig;
+    /** Extra headers sent with every request. */
+    headers?: Record<string, string>;
+    /** Authentication configuration. */
+    auth?: AuthConfig;
+    /** Postman variables ({{name}}) to inject. */
+    variables?: Record<string, string>;
+    /** Exit with non-zero code if any test fails. Default: true. */
+    failOnError?: boolean;
+    /** Path to a .env file (KEY=VALUE per line). */
+    envFile?: string;
+    /** gRPC-specific: use server reflection. Default: true. */
+    grpcReflection?: boolean;
+    /** gRPC-specific: paths to .proto files or directories. */
+    grpcProtoPaths?: string[];
+    /** MCP-specific: transport for MCP operations. Default: "streamable-http". */
+    mcpTransport?: "streamable-http" | "stdio";
+    /** MCP stdio: command to spawn. */
+    mcpCommand?: string;
+    /** MCP stdio: command arguments. */
+    mcpArgs?: string[];
+    /** MCP stdio: working directory. */
+    mcpCwd?: string;
+}
+interface AssertionResult {
+    name: string;
+    passed: boolean;
+    error?: string;
+}
+interface TestResult {
+    operationId: string;
+    path: string;
+    method: string;
+    protocol: ProtocolName | string;
+    status: TestStatus;
+    durationMs: number;
+    response?: {
+        status?: number;
+        statusText?: string;
+        contentType?: string;
+        sizeBytes?: number;
+        body?: unknown;
+        text?: string;
+        headers?: Record<string, string>;
+        events?: unknown[];
+        streaming?: boolean;
+    };
+    assertions?: AssertionResult[];
+    error?: string;
+    timestamp: string;
+}
+interface TestSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    errors: number;
+    skipped: number;
+    durationMs: number;
+    passRate: number;
+}
+interface TestReport {
+    summary: TestSummary;
+    results: TestResult[];
+    config: CliConfig;
+    generatedAt: string;
+    version: string;
+}
+
+/**
+ * Run all tests defined in the spec.
+ */
+declare function runTests(config: CliConfig): Promise<TestReport>;
+
+declare const DEFAULT_CONFIG: Required<Pick<CliConfig, "outputDir" | "formats" | "concurrency" | "timeout" | "failOnError" | "grpcReflection" | "mcpTransport">>;
+interface CliArgs {
+    spec?: string;
+    server?: string;
+    output?: string;
+    format?: string;
+    method?: string;
+    path?: string;
+    tag?: string;
+    operationId?: string;
+    concurrency?: number;
+    timeout?: number;
+    proxy?: string;
+    ca?: string;
+    cert?: string;
+    key?: string;
+    insecure?: boolean;
+    header?: string[];
+    bearer?: string;
+    variable?: string[];
+    config?: string;
+    env?: string;
+    failOnError?: boolean;
+    grpcReflection?: boolean;
+    grpcProto?: string[];
+    mcpTransport?: string;
+    mcpCommand?: string;
+    mcpArgs?: string;
+    mcpCwd?: string;
+}
+/**
+ * Resolve the final CliConfig from CLI args, an optional config file,
+ * environment variables, and defaults.
+ */
+declare function resolveConfig(args: CliArgs): CliConfig;
+/**
+ * Check whether a spec path is a remote URL.
+ */
+declare function isRemoteSpec(specPath: string): boolean;
+/**
+ * Load and parse the OpenAPI spec from a local file or remote URL.
+ */
+declare function loadSpec(config: CliConfig): Promise<any>;
+
+/**
+ * Assertion engine. Supports two sources:
+ * 1. Declarative `x-tests` array on the operation (simple, JSON-serializable).
+ * 2. Postman `x-postman-scripts.test` string (full pm.* API, executed by
+ *    @powerduck/request's script sandbox and surfaced via onAssertion).
+ */
+
+interface DeclarativeAssertion {
+    name: string;
+    /** What to assert. */
+    assert: "status" | "header" | "bodyContains" | "jsonPath" | "responseTime" | "bodyEquals";
+    /** Expected status code (for assert=status). */
+    value?: number;
+    /** Header name (for assert=header). */
+    key?: string;
+    /** Substring to check (for assert=header / bodyContains). */
+    contains?: string;
+    /** JSONPath expression (for assert=jsonPath). Simple dot-notation supported. */
+    path?: string;
+    /** Expected value at path (for assert=jsonPath). */
+    equals?: unknown;
+    /** Whether the path must exist (for assert=jsonPath). */
+    exists?: boolean;
+    /** Max response time in ms (for assert=responseTime). */
+    max?: number;
+    /** Expected body string (for assert=bodyEquals). */
+    body?: string;
+}
+interface AssertionContext {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+    bodyText?: string;
+    durationMs: number;
+}
+/**
+ * Run declarative assertions against a response context.
+ */
+declare function runDeclarativeAssertions(assertions: DeclarativeAssertion[], ctx: AssertionContext): AssertionResult[];
+/**
+ * Minimal JSONPath resolver supporting dot notation and array indices.
+ * e.g. "$.data.items[0].id" or "data.user.name"
+ */
+declare function resolveJsonPath(obj: unknown, path: string): unknown;
+/**
+ * Extract declarative assertions from an OpenAPI operation.
+ * Looks for `x-tests` on the operation or path item.
+ */
+declare function extractAssertions(operation: any, pathItem?: any): DeclarativeAssertion[];
+/**
+ * Extract Postman test scripts from an operation.
+ * Looks for `x-postman-scripts.test` on the operation.
+ */
+declare function extractPostmanScripts(operation: any): string | undefined;
+
+declare function generateJsonReport(report: TestReport, outputDir: string): string;
+
+/**
+ * CLI reporter: prints a colored, human-readable summary to stdout.
+ * No external dependencies — uses ANSI escape codes directly.
+ */
+
+declare function generateCliReport(report: TestReport): string;
+/**
+ * Print the CLI report to stdout and return it.
+ */
+declare function printCliReport(report: TestReport): string;
+
+declare function generateHtmlReport(report: TestReport, outputDir: string): string;
+
+export { type AssertionResult, type AuthConfig, type CliArgs, type CliConfig, DEFAULT_CONFIG, type DeclarativeAssertion, type FilterConfig, type ProtocolName, type ReportFormat, type TestReport, type TestResult, type TestStatus, type TestSummary, type TlsConfig, extractAssertions, extractPostmanScripts, generateCliReport, generateHtmlReport, generateJsonReport, isRemoteSpec, loadSpec, printCliReport, resolveConfig, resolveJsonPath, runDeclarativeAssertions, runTests };

package/dist/index.js

@@ -0,0 +1 @@
+import{DEFAULT_CONFIG as o,extractAssertions as r,extractPostmanScripts as m,generateCliReport as p,generateHtmlReport as t,generateJsonReport as R,isRemoteSpec as Z,loadSpec as c,printCliReport as e,resolveConfig as f,resolveJsonPath as h,runDeclarativeAssertions as i,runTests as j}from"./chunk-XORDZRWZ.js";export{o as DEFAULT_CONFIG,r as extractAssertions,m as extractPostmanScripts,p as generateCliReport,t as generateHtmlReport,R as generateJsonReport,Z as isRemoteSpec,c as loadSpec,e as printCliReport,f as resolveConfig,h as resolveJsonPath,i as runDeclarativeAssertions,j as runTests};

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@powerduck/openapi-cli",
+  "version": "0.2.0",
+  "description": "CI-ready CLI for batch-testing OpenAPI documents across HTTP, SSE, WebSocket, GraphQL, gRPC and MCP",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "openapi-cli": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "build": "tsc --noEmit && tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build",
+    "check": "tsc --noEmit && vitest run"
+  },
+  "keywords": [
+    "openapi",
+    "cli",
+    "testing",
+    "grpc",
+    "mcp",
+    "graphql",
+    "sse",
+    "websocket",
+    "ci",
+    "api-testing",
+    "contract-testing"
+  ],
+  "license": "MIT",
+  "author": "Powerduck limited",
+  "dependencies": {
+    "@powerduck/openapi-parser": "^0.3.3",
+    "@powerduck/request": "^0.2.2",
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "terser": "^5.51.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "@vitest/coverage-v8": "^3.2.7",
+    "vitest": "^3.2.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PowerDuckie/openapi-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PowerDuckie/openapi-cli/issues"
+  },
+  "homepage": "https://github.com/PowerDuckie/openapi-cli#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}