matimo-bruno 0.1.0__tar.gz

matimo_bruno-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# Dependencies
+**/node_modules/
+package-lock.json
+yarn.lock
+
+# Build output
+**/dist/
+*.tsbuildinfo
+
+# Python compiled / build
+**/__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+**/build/
+**/.eggs/
+**/.venv/
+**/.mypy_cache/
+**/.ruff_cache/
+**/.pytest_cache/
+
+# Test coverage
+**/coverage/
+**/.nyc_output/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+typescript/examples/mcp/matimo-tools/.matimo-approvals.json
+typescript/examples/mcp/matimo-tools/fetch-weather/definition.yaml
+typescript/examples/mcp/matimo-tools/npm_downloads/definition.yaml
+typescript/examples/mcp/matimo-tools/skills/ecosystem-health/SKILL.md
+typescript/examples/mcp/matimo-tools/skills/matimo-health-check/SKILL.md
+typescript/examples/mcp/matimo-tools/skills/moltbook-identity/SKILL.md
+typescript/packages/cli/.matimo/certs/server.crt
+typescript/packages/cli/.matimo/certs/server.key
+typescript/examples/mcp/.matimo/certs/server.crt
+typescript/examples/mcp/.matimo/certs/server.key

matimo_bruno-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: matimo-bruno
+Version: 0.1.0
+Summary: Matimo provider — Bruno API testing tools (collections, requests, imports, reports)
+License: MIT
+Keywords: agents,ai,api-testing,bruno,matimo,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Requires-Dist: matimo-core<0.2.0,>=0.1.0
+Description-Content-Type: text/markdown
+
+# matimo-bruno
+
+Bruno CLI tools for Matimo — Enable AI agents to autonomously manage, execute, and validate API test collections.
+
+## 📦 Installation
+
+```bash
+pip install matimo-bruno
+```
+
+## 🚀 Quick Start
+
+### Python
+
+```python
+from matimo import Matimo
+
+matimo = await Matimo.init()
+
+# List all collections in workspace
+collections = await matimo.execute('bruno_list_collections', {
+    'workspace_path': './collections'
+})
+
+# Get collection metadata before running
+info = await matimo.execute('bruno_get_collection_info', {
+    'collection_path': './collections/payment-api'
+})
+
+# Run entire collection
+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
+response = await matimo.execute('bruno_run_request', {
+    'collection_path': './collections/auth',
+    'request_name': 'Login',
+    'environment': 'staging'
+})
+
+# Bootstrap from OpenAPI spec
+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
+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: `pnpm install -g @usebruno/cli`
+- **Python** 3.11+
+- 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

matimo_bruno-0.1.0/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
+pip install matimo-bruno
+```
+
+## 🚀 Quick Start
+
+### Python
+
+```python
+from matimo import Matimo
+
+matimo = await Matimo.init()
+
+# List all collections in workspace
+collections = await matimo.execute('bruno_list_collections', {
+    'workspace_path': './collections'
+})
+
+# Get collection metadata before running
+info = await matimo.execute('bruno_get_collection_info', {
+    'collection_path': './collections/payment-api'
+})
+
+# Run entire collection
+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
+response = await matimo.execute('bruno_run_request', {
+    'collection_path': './collections/auth',
+    'request_name': 'Login',
+    'environment': 'staging'
+})
+
+# Bootstrap from OpenAPI spec
+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
+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: `pnpm install -g @usebruno/cli`
+- **Python** 3.11+
+- 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

matimo_bruno-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "matimo-bruno"
+version = "0.1.0"
+description = "Matimo provider — Bruno API testing tools (collections, requests, imports, reports)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["ai", "tools", "agents", "matimo", "bruno", "api-testing"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "matimo-core>=0.1.0,<0.2.0",
+]
+
+[project.entry-points."matimo.providers"]
+bruno = "matimo_bruno:get_tools_path"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/matimo_bruno"]

matimo_bruno-0.1.0/src/matimo_bruno/__init__.py

@@ -0,0 +1,7 @@
+"""Matimo Bruno provider - API testing tools via Bruno CLI."""
+
+
+def get_tools_path() -> str:
+    """Return path to tools directory for Matimo discovery."""
+    from pathlib import Path
+    return str(Path(__file__).parent / "tools")

matimo_bruno-0.1.0/src/matimo_bruno/_bru_utils.py

@@ -0,0 +1,51 @@
+"""Shared utilities for Bruno CLI tools."""
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+
+BRU_MIN_VERSION: tuple[int, int, int] = (1, 0, 0)
+BRU_MIN_VERSION_STR = "1.0.0"
+
+
+def check_bru_version() -> None:
+    """Verify the Bruno CLI is installed and meets the minimum required version.
+
+    Raises:
+        RuntimeError: If ``bru`` is not installed or below :data:`BRU_MIN_VERSION`.
+
+    Silently skips the version comparison when the version output cannot be
+    parsed (graceful degradation — the tool is installed, which is sufficient).
+    """
+    if shutil.which("bru") is None:
+        raise RuntimeError(
+            "Bruno CLI ('bru') is not installed or not in PATH. "
+            "Install it with: npm install -g @usebruno/cli  "
+            "or via Homebrew: brew install bruno"
+        )
+    try:
+        result = subprocess.run(
+            ["bru", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        version_str = result.stdout.strip()
+        match = re.match(r"^(\d+)\.(\d+)\.(\d+)", version_str)
+        if match:
+            installed: tuple[int, int, int] = (
+                int(match.group(1)),
+                int(match.group(2)),
+                int(match.group(3)),
+            )
+            if installed < BRU_MIN_VERSION:
+                raise RuntimeError(
+                    f"Bruno CLI version {version_str} is below the minimum required "
+                    f"version {BRU_MIN_VERSION_STR}. "
+                    f"Upgrade with: npm install -g @usebruno/cli"
+                )
+    except RuntimeError:
+        raise  # Re-raise version-too-low errors
+    except Exception:  # noqa: BLE001
+        pass  # Best-effort check — if version cannot be determined, proceed

matimo_bruno-0.1.0/src/matimo_bruno/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: executor.py
+  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"