@matimo/bruno 0.1.0

package/README.md

@@ -0,0 +1,174 @@
+# @matimo/bruno
+
+Bruno CLI tools for Matimo — Enable AI agents to autonomously manage, execute, and validate API test collections.
+
+## 📦 Installation
+
+```bash
+npm install @matimo/bruno
+```
+
+## 🚀 Quick Start
+
+### TypeScript / JavaScript
+
+```typescript
+import { MatimoInstance } from '@matimo/core';
+
+const matimo = await MatimoInstance.init('./packages/bruno/tools');
+
+// List all collections in workspace
+const collections = await matimo.execute('bruno_list_collections', {
+  workspace_path: './collections'
+});
+
+// Get collection metadata before running
+const info = await matimo.execute('bruno_get_collection_info', {
+  collection_path: './collections/payment-api'
+});
+
+// Run entire collection
+const result = await matimo.execute('bruno_run_collection', {
+  collection_path: './collections/payment-api',
+  environment: 'staging',
+  report_path: './reports/staging-results.json'
+});
+
+// Run single request for debugging
+const response = await matimo.execute('bruno_run_request', {
+  collection_path: './collections/auth',
+  request_name: 'Login',
+  environment: 'staging'
+});
+
+// Bootstrap from OpenAPI spec
+const imported = await matimo.execute('bruno_import_openapi', {
+  spec_source: 'https://api.example.com/openapi.json',
+  output_directory: './collections',
+  collection_name: 'Generated API Tests'
+});
+
+// Create new collection
+const created = await matimo.execute('bruno_create_collection', {
+  collection_path: './collections/new-service',
+  collection_name: 'New Service Tests'
+});
+```
+
+## 📋 Available Tools
+
+### 1. `bruno_run_collection`
+Execute a Bruno API collection with configurable environments, data files, and reporting.
+
+**Parameters:**
+- `collection_path` (required) — Path to collection file or directory
+- `environment` — Environment name (dev, staging, prod)
+- `env_file` — Path to environment file override
+- `data_file` — CSV/JSON data file for data-driven testing
+- `iteration_count` — Number of iterations to run
+- `delay_ms` — Delay between requests
+- `tags` — Comma-separated tags (run requests with ALL tags)
+- `exclude_tags` — Comma-separated tags (skip requests with ANY tags)
+- `tests_only` — Run only requests with tests/assertions
+- `bail_on_failure` — Stop on first failure
+- `parallel` — Run requests in parallel
+- `sandbox_mode` — JavaScript execution mode ('safe' or 'developer')
+- `report_format` — Report format (json, junit, html)
+- `report_path` — Path to write report file
+
+**Returns:** Collection execution results, summary, and report path
+
+### 2. `bruno_run_request`
+Execute a single request for targeted debugging and validation.
+
+**Parameters:**
+- `collection_path` (required) — Collection directory
+- `request_name` (required) — Request name to execute
+- `environment` — Environment name override
+- `env_file` — Environment file override
+- `sandbox_mode` — JavaScript execution mode
+
+**Returns:** Request/response details and assertion results
+
+### 3. `bruno_list_collections`
+Discover all collections in a workspace.
+
+**Parameters:**
+- `workspace_path` (required) — Workspace directory
+- `filter` — Filter by collection name (substring)
+
+**Returns:** Array of collection metadata
+
+### 4. `bruno_get_collection_info`
+Introspect collection structure before execution.
+
+**Parameters:**
+- `collection_path` (required) — Collection path
+
+**Returns:** Collection structure, requests, environments, variables
+
+### 5. `bruno_import_openapi`
+Bootstrap a collection from OpenAPI 3.0 specification.
+
+**Parameters:**
+- `spec_source` (required) — Path or URL to OpenAPI spec
+- `output_directory` (required) — Where to create collection
+- `collection_name` — Collection name
+- `collection_format` — 'bru' or 'opencollection'
+- `group_by` — Group by 'tags' or 'path'
+- `insecure` — Skip TLS verification
+
+**Returns:** Collection path and metadata
+
+### 6. `bruno_create_collection`
+Create a new empty collection scaffold.
+
+**Parameters:**
+- `collection_path` (required) — Collection creation path
+- `collection_name` (required) — Collection name
+
+**Returns:** Creation status and path
+
+## 🔄 Agent Workflows
+
+### Autonomous Test Execution
+```
+Agent discovers spec → import_openapi → set environment → run_collection → parse results
+```
+
+### Multi-Environment Validation
+```
+list_collections → for each environment: set_env + run_collection → compare results
+```
+
+### Targeted Debugging
+```
+get_collection_info → run_request (single endpoint) → analyze response
+```
+
+### Data-Driven Testing
+```
+run_collection with CSV file → multiple iterations → aggregate metrics
+```
+
+## 🔐 Authentication
+
+Tools use environment variables for credentials. Bruno CLI manages environment setup — tools wrap CLI execution.
+
+## 📖 Prerequisites
+
+- **Bruno CLI** installed globally: `npm install -g @usebruno/cli` (or `pnpm install -g @usebruno/cli`)
+- **Node.js** 18+ required
+- Bruno collections in `.bru` format or OpenAPI specs
+
+## 🤝 Integration
+
+Works with:
+- **LangChain** — Convert to StructuredTool
+- **CrewAI** — Convert to BaseTool
+- **MCP** — Expose via JSON-RPC to Claude / other MCP clients
+- **Native** — Direct SDK usage
+
+## 📝 License
+
+MIT

package/definition.yaml

@@ -0,0 +1,33 @@
+# Bruno CLI Provider Definition
+#
+# This file defines the configuration for Bruno CLI tools.
+# All Bruno tools reference this provider definition.
+
+name: bruno-provider
+type: provider
+version: '1.0.0'
+
+description: |
+  Bruno CLI Provider Configuration
+
+  All Bruno tools use the locally-installed Bruno CLI.
+
+  Setup:
+  1. Install Bruno CLI:
+     npm install -g @usebruno/cli
+     or
+     brew install bruno
+
+  2. Bruno CLI v3+ provides:
+     - Collection management (create, list, import)
+     - Request execution (run single or full suite)
+     - OpenAPI spec import and generation
+     - Test result reporting
+
+  Authentication:
+  Bruno CLI tools run locally and don't require credentials.
+  API keys for tested endpoints should be provided in environment variables.
+
+  Documentation:
+  - Bruno Docs: https://www.usebruno.com/
+  - CLI Reference: https://www.usebruno.com/docs/cli/cli-overview

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@matimo/bruno",
+  "version": "0.1.0",
+  "description": "Bruno CLI tools for Matimo — API collection execution, import, and validation",
+  "files": [
+    "tools",
+    "README.md",
+    "definition.yaml"
+  ],
+  "dependencies": {
+    "@usebruno/cli": "^3.3.0",
+    "@matimo/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "matimo": "0.1.0-alpha.14"
+  }
+}

package/tools/bru-utils.ts

@@ -0,0 +1,51 @@
+import { execFileSync } from 'child_process';
+
+export const BRU_MIN_VERSION_STR = '1.0.0';
+const BRU_MIN_VERSION = [1, 0, 0] as const;
+
+/**
+ * Verify the Bruno CLI is installed and meets the minimum required version.
+ *
+ * - Throws if `bru` is not found in PATH (ENOENT).
+ * - Throws if the installed version is below {@link BRU_MIN_VERSION_STR}.
+ * - Skips silently if the version string cannot be parsed (graceful degradation).
+ */
+export function checkBruVersion(): void {
+  let versionOutput: string;
+  try {
+    versionOutput = execFileSync('bru', ['--version'], { encoding: 'utf-8', stdio: 'pipe' });
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error(
+        "Bruno CLI ('bru') is not installed or not in PATH. " +
+          'Install it with: npm install -g @usebruno/cli',
+      );
+    }
+    // Other error — skip version check (bru is installed but --version failed for another reason)
+    return;
+  }
+
+  const match = versionOutput.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return; // Unparseable output — skip check
+
+  const installed: [number, number, number] = [
+    parseInt(match[1], 10),
+    parseInt(match[2], 10),
+    parseInt(match[3], 10),
+  ];
+
+  const [iMaj, iMin, iPatch] = installed;
+  const [minMaj, minMin, minPatch] = BRU_MIN_VERSION;
+
+  const belowMin =
+    iMaj < minMaj ||
+    (iMaj === minMaj && iMin < minMin) ||
+    (iMaj === minMaj && iMin === minMin && iPatch < minPatch);
+
+  if (belowMin) {
+    throw new Error(
+      `Bruno CLI version ${versionOutput.trim()} is below the minimum required version ` +
+        `${BRU_MIN_VERSION_STR}. Upgrade with: npm install -g @usebruno/cli`,
+    );
+  }
+}

package/tools/bruno_add_request/definition.yaml

@@ -0,0 +1,108 @@
+name: bruno_add_request
+description: Add a new HTTP request to a Bruno collection programmatically. Creates a .bru file with the specified method, URL, headers, body, and test assertions.
+version: '1.0.0'
+status: approved
+
+parameters:
+  collection_path:
+    type: string
+    required: true
+    description: Path to Bruno collection directory
+    example: './api-tests/payment-api'
+
+  request_name:
+    type: string
+    required: true
+    description: Request name (becomes .bru filename, alphanumeric + hyphens)
+    example: 'get-users'
+
+  method:
+    type: string
+    required: true
+    description: HTTP method
+    enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']
+    example: 'GET'
+
+  url:
+    type: string
+    required: true
+    description: Full request URL (can contain {variables})
+    example: 'https://api.example.com/users/{user_id}'
+
+  headers:
+    type: object
+    required: false
+    description: HTTP headers as key-value pairs
+    example:
+      Content-Type: 'application/json'
+      Authorization: 'Bearer {api_token}'
+
+  body:
+    type: string
+    required: false
+    description: Request body (JSON or raw text)
+    example: '{"name": "John", "email": "john@example.com"}'
+
+  tests:
+    type: string
+    required: false
+    description: Bruno test script (JavaScript assertions)
+    example: |
+      test("Status is 200", function() {
+        expect(res.getStatus()).to.equal(200);
+      });
+
+  documentation:
+    type: string
+    required: false
+    description: Request documentation/description
+    example: 'Fetch list of all users from the system'
+
+execution:
+  type: function
+  code: index.ts
+  timeout: 10000
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+      description: Whether request was created successfully
+    request_path:
+      type: string
+      description: Full path to created .bru file
+    request_name:
+      type: string
+      description: Request name
+    message:
+      type: string
+      description: Success or error message
+
+examples:
+  - name: "Add GET request with headers"
+    params:
+      collection_path: "./api-tests/payment-api"
+      request_name: "get-transactions"
+      method: "GET"
+      url: "https://api.payment.com/v1/transactions"
+      headers:
+        Authorization: "Bearer {api_token}"
+        Accept: "application/json"
+
+  - name: "Add POST request with body and tests"
+    params:
+      collection_path: "./api-tests/payment-api"
+      request_name: "create-payment"
+      method: "POST"
+      url: "https://api.payment.com/v1/payments"
+      headers:
+        Content-Type: "application/json"
+        Authorization: "Bearer {api_token}"
+      body: '{"amount": 100, "currency": "USD", "description": "Payment for order"}'
+      tests: |
+        test("Payment created with 201", function() {
+          expect(res.getStatus()).to.equal(201);
+          expect(res.getBody().id).to.exist;
+        });
+      documentation: "Create a new payment transaction"

package/tools/bruno_add_request/index.ts

@@ -0,0 +1,101 @@
+import { getGlobalMatimoLogger } from '@matimo/core';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+
+const logger = getGlobalMatimoLogger();
+
+function generateBruContent(params: Record<string, unknown>): string {
+  const requestName = params.request_name as string;
+  const method = (params.method as string).toLowerCase();
+  const url = params.url as string;
+  const headers = (params.headers as Record<string, string>) || {};
+  const body = params.body as string | undefined;
+  const tests = params.tests as string | undefined;
+  const documentation = params.documentation as string | undefined;
+
+  let content = '';
+
+  content += `meta {\n  name: ${requestName}\n  type: http\n  seq: 1\n}\n\n`;
+
+  if (documentation) {
+    content += `docs {\n  ${documentation}\n}\n\n`;
+  }
+
+  content += `${method} {\n  url: ${url}\n  body: ${body ? 'json' : 'none'}\n  auth: inherit\n}\n\n`;
+
+  if (Object.keys(headers).length > 0) {
+    content += `headers {\n`;
+    for (const [k, v] of Object.entries(headers)) {
+      content += `  ${k}: ${v}\n`;
+    }
+    content += `}\n\n`;
+  }
+
+  if (body) {
+    content += `body:json {\n`;
+    content += body
+      .split('\n')
+      .map((line) => `  ${line}`)
+      .join('\n');
+    content += `\n}\n\n`;
+  }
+
+  if (tests) {
+    content += `tests {\n`;
+    content += tests
+      .split('\n')
+      .map((line) => `  ${line}`)
+      .join('\n');
+    content += `\n}\n`;
+  }
+
+  return content;
+}
+
+export default async function execute(params: Record<string, unknown>): Promise<unknown> {
+  const collectionPath = params.collection_path as string;
+  const requestName = params.request_name as string;
+
+  if (!collectionPath || !requestName) {
+    return {
+      success: false,
+      request_path: '',
+      request_name: '',
+      message: 'collection_path and request_name are required',
+    };
+  }
+
+  try {
+    logger.info(`Adding request ${requestName} to collection at ${collectionPath}`);
+
+    const absoluteCollectionPath = path.resolve(collectionPath);
+    // Write requests into a dedicated requests/ subfolder (consistent with Bruno convention)
+    const requestsDir = path.join(absoluteCollectionPath, 'requests');
+    await fs.mkdir(requestsDir, { recursive: true });
+
+    const filename = `${requestName.toLowerCase().replace(/\s+/g, '-')}.bru`;
+    const requestPath = path.join(requestsDir, filename);
+
+    const content = generateBruContent(params);
+    await fs.writeFile(requestPath, content, 'utf-8');
+
+    logger.info(`Request written to ${requestPath}`);
+
+    return {
+      success: true,
+      request_path: requestPath,
+      request_name: requestName,
+      message: `Request '${requestName}' added to collection successfully`,
+    };
+  } catch (error) {
+    logger.error(
+      `Add request failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return {
+      success: false,
+      request_path: '',
+      request_name: requestName,
+      message: `Failed to add request: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}

package/tools/bruno_create_collection/definition.yaml

@@ -0,0 +1,46 @@
+name: bruno_create_collection
+description: Create a new empty Bruno collection scaffold with directory structure and configuration. Enables agents to initialize new collections for API testing projects.
+version: '1.0.0'
+status: approved
+
+parameters:
+  collection_path:
+    type: string
+    required: true
+    description: Path where new collection directory will be created
+
+  collection_name:
+    type: string
+    required: true
+    description: Name for the new collection
+
+execution:
+  type: function
+  code: index.ts
+  timeout: 15000
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    collection_path:
+      type: string
+    message:
+      type: string
+    errors:
+      type: array
+      items:
+        type: string
+
+
+examples:
+  - name: "Create new collection for microservice testing"
+    params:
+      collection_path: "./collections/user-service"
+      collection_name: "User Service API Tests"
+
+  - name: "Bootstrap collection for integration tests"
+    params:
+      collection_path: "./collections/e2e-workflows"
+      collection_name: "End-to-End Workflows"

package/tools/bruno_create_collection/index.ts

@@ -0,0 +1,55 @@
+import { getGlobalMatimoLogger } from '@matimo/core';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+
+const logger = getGlobalMatimoLogger();
+
+export default async function execute(params: Record<string, unknown>): Promise<unknown> {
+  const collectionPath = params.collection_path as string;
+  const collectionName = params.collection_name as string;
+
+  if (!collectionPath || !collectionName) {
+    return {
+      success: false,
+      collection_path: '',
+      message: 'collection_path and collection_name parameters are required',
+      errors: ['collection_path and collection_name parameters are required'],
+    };
+  }
+
+  try {
+    logger.info(`Creating collection: ${collectionName} at ${collectionPath}`);
+
+    const absolutePath = path.resolve(collectionPath);
+    await fs.mkdir(absolutePath, { recursive: true });
+
+    const brunoJson = {
+      version: '1',
+      name: collectionName,
+      type: 'collection',
+      ignore: [] as string[],
+    };
+
+    const brunoJsonPath = path.join(absolutePath, 'bruno.json');
+    await fs.writeFile(brunoJsonPath, JSON.stringify(brunoJson, null, 2), 'utf-8');
+
+    logger.info('Collection created successfully');
+
+    return {
+      success: true,
+      collection_path: absolutePath,
+      message: `Collection "${collectionName}" created at ${absolutePath}`,
+      errors: [],
+    };
+  } catch (error) {
+    logger.error(
+      `Create collection failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return {
+      success: false,
+      collection_path: collectionPath,
+      message: 'Collection creation failed',
+      errors: [error instanceof Error ? error.message : String(error)],
+    };
+  }
+}

package/tools/bruno_get_collection_info/definition.yaml

@@ -0,0 +1,61 @@
+name: bruno_get_collection_info
+description: Introspect a Bruno collection to get its structure, requests, environments, and configuration. Returns complete collection metadata for pre-flight validation before execution.
+version: '1.0.0'
+status: approved
+
+parameters:
+  collection_path:
+    type: string
+    required: true
+    description: Path to Bruno collection file or directory
+
+execution:
+  type: function
+  code: index.ts
+  timeout: 10000
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    collection:
+      type: object
+      properties:
+        name:
+          type: string
+        path:
+          type: string
+        requests:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+              method:
+                type: string
+              url:
+                type: string
+              path:
+                type: string
+              tags:
+                type: array
+                items:
+                  type: string
+              has_tests:
+                type: boolean
+    errors:
+      type: array
+      items:
+        type: string
+
+
+examples:
+  - name: "Inspect collection structure"
+    params:
+      collection_path: "./collections/payment-api"
+
+  - name: "Get full metadata before running"
+    params:
+      collection_path: "./collections/auth-flow.bru"