@contractkit/plugin-bruno

@contractkit/contractkit-plugin-bruno

ContractKit plugin that generates a Bruno REST API collection from .ck operation files. The output is a ready-to-open OpenCollection directory.

Installation

pnpm add @contractkit/contractkit-plugin-bruno

Configuration

{
  "plugins": {
    "@contractkit/contractkit-plugin-bruno": {
      "output": "bruno-collection",
      "collectionName": "Acme API",
      "auth": {
        "defaultScheme": "bearerAuth",
        "schemes": {
          "bearerAuth": {
            "type": "http",
            "scheme": "bearer"
          }
        }
      }
    }
  }
}

Options

Option	Type	Default	Description
baseDir	string	rootDir	Base directory for the output
output	string	"bruno-collection"	Output directory name
collectionName	string	basename of rootDir	Collection name shown in Bruno
randomExamples	boolean	true	Use Bruno faker templates ({{$randomUUID}}, {{$randomEmail}}, etc.) for compatible scalar fields so each send produces fresh data. Set to false for stable, deterministic placeholders.
includeInternal	boolean	true	Include operations marked internal. Set to false to omit them from the collection.
auth.defaultScheme	string	—	Key from auth.schemes to apply by default
auth.schemes	object	—	Map of scheme name → security scheme definition
environments	object	—	Map of environment name → variables. Each entry produces a environments/<name>.yml file. See Environments.

Auth scheme types

type	Required fields	Description
"http" with scheme: "bearer"	—	Bearer token auth
"http" with scheme: "basic"	—	HTTP Basic auth
"apiKey"	name, in ("header" or "query")	API key in a header or query param

Output structure

bruno-collection/
├── bruno.json             # Collection manifest
├── environments/
│   └── Local.bru          # Default environment with base URL variable
└── <area>/
    └── <operation>.bru    # One request file per HTTP verb per operation

The output directory is fully replaced on each run — stale request files from removed operations are automatically cleaned up.

Per-operation overrides

Add a plugins block to any operation in a .ck file to deep-merge a YAML fragment into the generated request. The Bruno plugin reads plugins.bruno.template; the value is either an inline YAML string or a file:///http(s):// URL that the CLI resolves to the file/response body before the plugin runs:

post: {
    plugins: {
        bruno: { template: "file://overrides/auth-token.yml" }
    }
    response: { 200: AuthResponse }
}

The file:// path is relative to the .ck source file. The resolved content is deep-merged into the generated request YAML — objects recurse, arrays replace entirely:

# overrides/auth-token.yml
runtime:
  script:
    req: |
      bru.setVar("token", bru.getEnvVar("adminToken"));

validateBrunoExtension (run during compilation) enforces the shape: the value must be an object whose only allowed key is template: string. Anything else fails the build with a precise error.

Authoring tip: combine per-operation template URLs with {{var}} substitution to factor out a shared override directory:

options {
    keys: { bruno: "../../bruno-overrides" }
}

operation /payments/{id}: {
    get: {
        plugins: { bruno: { template: "file://{{bruno}}/payments/get-payment.yml" } }
        response: { 200: { application/json: Payment } }
    }
}

The {{bruno}} reference can also be supplied workspace-wide via the plugin's keys config in contractkit.config.json.

Environments

Provide an environments block in the plugin config to control what environments/<name>.yml files Bruno sees. Each top-level key becomes a file; its values become the variables in that file:

{
  "plugins": {
    "@contractkit/contractkit-plugin-bruno": {
      "environments": {
        "local": {
          "baseUrl": "http://localhost:3000",
          "token": ""
        },
        "staging": {
          "baseUrl": "https://staging.example.com",
          "token": ""
        }
      }
    }
  }
}

Notes:

• Variable values are coerced to strings and always emitted with double quotes.
• When environments is omitted or empty, a default environments/local.yml is emitted with baseUrl=http://localhost:3000 plus any auth env-var placeholders the default auth scheme requires.
• When environments is provided, the default is replaced entirely — auth variables are not auto-injected, so include them explicitly if needed.

Programmatic use

import { createBrunoPlugin } from '@contractkit/contractkit-plugin-bruno';

const plugin = createBrunoPlugin({
  output: 'bruno-collection',
  collectionName: 'My API',
  auth: {
    defaultScheme: 'bearerAuth',
    schemes: {
      bearerAuth: { type: 'http', scheme: 'bearer' },
    },
  },
});