@matimo/bruno 0.1.0

package/tools/bruno_get_collection_info/index.ts

@@ -0,0 +1,119 @@
+import { getGlobalMatimoLogger } from '@matimo/core';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+
+const logger = getGlobalMatimoLogger();
+
+interface RequestInfo {
+  name: string;
+  method: string;
+  url: string;
+  path: string;
+  tags: string[];
+  has_tests: boolean;
+}
+
+async function scanBruFiles(dir: string, results: RequestInfo[]): Promise<void> {
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry);
+    try {
+      const stat = await fs.stat(fullPath);
+      if (stat.isDirectory() && entry !== 'node_modules') {
+        await scanBruFiles(fullPath, results);
+      } else if (!stat.isDirectory() && entry.endsWith('.bru')) {
+        try {
+          const content = await fs.readFile(fullPath, 'utf-8');
+          const methodMatch = content.match(/^(get|post|put|patch|delete|head|options)\s*\{/im);
+          const method = methodMatch ? methodMatch[1].toUpperCase() : 'UNKNOWN';
+          const nameMatch = content.match(/meta\s*\{[^}]*name:\s*(.+)/i);
+          const name = nameMatch ? nameMatch[1].trim() : path.basename(entry, '.bru');
+          const urlMatch = content.match(/^\s+url:\s*(.+)$/m);
+          const url = urlMatch ? urlMatch[1].trim() : '';
+          const tagsMatch = content.match(/tags:\s*\[([^\]]*)\]/);
+          const tags = tagsMatch
+            ? tagsMatch[1].split(',').map((t) => t.trim()).filter(Boolean)
+            : [];
+          const hasTests = /\btests\s*\{/.test(content);
+          results.push({ name, method, url, path: fullPath, tags, has_tests: hasTests });
+        } catch {
+          results.push({
+            name: path.basename(entry, '.bru'),
+            method: 'UNKNOWN',
+            url: '',
+            path: fullPath,
+            tags: [],
+            has_tests: false,
+          });
+        }
+      }
+    } catch {
+      // skip
+    }
+  }
+}
+
+export default async function execute(params: Record<string, unknown>): Promise<unknown> {
+  const collectionPath = params.collection_path as string;
+
+  if (!collectionPath) {
+    return {
+      success: false,
+      collection: undefined,
+      errors: ['collection_path parameter is required'],
+    };
+  }
+
+  try {
+    logger.info(`Getting collection info: ${collectionPath}`);
+    const absolutePath = path.resolve(collectionPath);
+
+    const brunoJsonPath = path.join(absolutePath, 'bruno.json');
+    let collectionName = path.basename(absolutePath);
+
+    // Verify the path exists before proceeding
+    try {
+      await fs.stat(absolutePath);
+    } catch {
+      return {
+        success: false,
+        collection: undefined,
+        errors: [`Collection path not found: ${collectionPath}`],
+      };
+    }
+
+    try {
+      const raw = await fs.readFile(brunoJsonPath, 'utf-8');
+      const parsed = JSON.parse(raw) as { name?: string };
+      if (parsed.name) collectionName = parsed.name;
+    } catch {
+      // bruno.json missing — use dirname as name
+    }
+
+    const requests: RequestInfo[] = [];
+    await scanBruFiles(absolutePath, requests);
+
+    return {
+      success: true,
+      collection: {
+        name: collectionName,
+        path: absolutePath,
+        requests,
+      },
+    };
+  } catch (error) {
+    logger.error(
+      `Get collection info failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return {
+      success: false,
+      collection: undefined,
+      errors: [error instanceof Error ? error.message : String(error)],
+    };
+  }
+}

package/tools/bruno_import_openapi/definition.yaml

@@ -0,0 +1,75 @@
+name: bruno_import_openapi
+description: Bootstrap a new Bruno collection from an OpenAPI 3.0 specification (YAML or JSON). Enables agents to auto-generate test collections from API specs without manual setup.
+version: '1.0.0'
+status: approved
+
+parameters:
+  spec_source:
+    type: string
+    required: true
+    description: Path or URL to OpenAPI specification (YAML or JSON)
+
+  output_directory:
+    type: string
+    required: true
+    description: Directory where imported collection will be created
+
+  collection_name:
+    type: string
+    required: false
+    description: Name for imported collection (defaults to spec name)
+
+  collection_format:
+    type: string
+    required: false
+    default: bru
+    description: Format for collection files - 'bru' (classic) or 'opencollection' (YAML)
+
+  group_by:
+    type: string
+    required: false
+    default: tags
+    description: Group requests by 'tags' or 'path'
+
+  insecure:
+    type: boolean
+    required: false
+    default: false
+    description: Skip TLS verification when source is HTTPS URL
+
+execution:
+  type: function
+  code: index.ts
+  timeout: 30000
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    collection_path:
+      type: string
+    collection_name:
+      type: string
+    requests_created:
+      type: number
+    message:
+      type: string
+    errors:
+      type: array
+      items:
+        type: string
+
+
+examples:
+  - name: "Import from local OpenAPI YAML"
+    params:
+      spec_source: "./specs/payment-api.yaml"
+      output_directory: "./collections"
+      collection_name: "Payment API"
+
+  - name: "Import from remote OpenAPI URL"
+    params:
+      spec_source: "https://api.example.com/openapi.json"
+      output_directory: "./collections"
+      group_by: "path"

package/tools/bruno_import_openapi/index.ts

@@ -0,0 +1,102 @@
+import { getGlobalMatimoLogger } from '@matimo/core';
+import { execFileSync } from 'child_process';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { checkBruVersion } from '../bru-utils';
+
+const logger = getGlobalMatimoLogger();
+
+/** Count .bru files recursively — compatible with Node 18+. */
+async function countBruFilesRecursively(dir: string): Promise<number> {
+  let count = 0;
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry);
+    try {
+      const stat = await fs.stat(fullPath);
+      if (stat.isDirectory() && entry !== 'node_modules') {
+        count += await countBruFilesRecursively(fullPath);
+      } else if (!stat.isDirectory() && entry.endsWith('.bru')) {
+        count++;
+      }
+    } catch {
+      // skip
+    }
+  }
+  return count;
+}
+
+export default async function execute(params: Record<string, unknown>): Promise<unknown> {
+  const specSource = params.spec_source as string;
+  const outputDirectory = params.output_directory as string;
+
+  if (!specSource || !outputDirectory) {
+    return {
+      success: false,
+      collection_path: '',
+      collection_name: '',
+      requests_created: 0,
+      message: 'spec_source and output_directory parameters are required',
+      errors: ['spec_source and output_directory parameters are required'],
+    };
+  }
+
+  checkBruVersion();
+
+  const collectionName = (params.collection_name as string) || 'Imported Collection';
+  const absoluteOutput = path.resolve(outputDirectory);
+
+  try {
+    logger.info(`Importing OpenAPI from: ${specSource} to ${absoluteOutput}`);
+
+    const args: string[] = [
+      'import', 'openapi',
+      '--source', specSource,
+      '--output', absoluteOutput,
+      '--collection-name', collectionName,
+    ];
+
+    if (params.group_by) args.push('--group-by', params.group_by as string);
+    if (params.insecure === true) args.push('--insecure');
+
+    logger.debug(`Executing: bru ${args.join(' ')}`);
+
+    execFileSync('bru', args, { encoding: 'utf-8', stdio: 'pipe' });
+
+    logger.info('OpenAPI import completed');
+
+    // Count generated .bru files using a Node 18-compatible recursive walk
+    let requestsCreated = 0;
+    try {
+      requestsCreated = await countBruFilesRecursively(absoluteOutput);
+    } catch {
+      // best-effort count
+    }
+
+    return {
+      success: true,
+      collection_path: absoluteOutput,
+      collection_name: collectionName,
+      requests_created: requestsCreated,
+      message: `Collection "${collectionName}" imported from OpenAPI spec`,
+      errors: [],
+    };
+  } catch (error) {
+    logger.error(
+      `OpenAPI import failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return {
+      success: false,
+      collection_path: absoluteOutput,
+      collection_name: collectionName,
+      requests_created: 0,
+      message: 'Import failed',
+      errors: [error instanceof Error ? error.message : String(error)],
+    };
+  }
+}

package/tools/bruno_list_collections/definition.yaml

@@ -0,0 +1,49 @@
+name: bruno_list_collections
+description: Discover all Bruno API collections in a workspace directory. Returns collection metadata including name, path, and request count.
+version: '1.0.0'
+status: approved
+
+parameters:
+  workspace_path:
+    type: string
+    required: true
+    description: Path to Bruno workspace directory
+
+  filter:
+    type: string
+    required: false
+    description: Filter collections by name (substring match)
+
+execution:
+  type: function
+  code: index.ts
+  timeout: 10000
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    collections:
+      type: array
+      items:
+        type: object
+        properties:
+          name:
+            type: string
+          path:
+            type: string
+          request_count:
+            type: number
+        required: ["name", "path", "request_count"]
+
+
+examples:
+  - name: "List all collections in workspace"
+    params:
+      workspace_path: "./bruno-collections"
+
+  - name: "Filter collections by name"
+    params:
+      workspace_path: "./bruno-collections"
+      filter: "api"

package/tools/bruno_list_collections/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();
+
+async function countBruFilesRecursively(dir: string): Promise<number> {
+  let count = 0;
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry);
+    try {
+      const stat = await fs.stat(fullPath);
+      if (stat.isDirectory() && entry !== 'node_modules') {
+        count += await countBruFilesRecursively(fullPath);
+      } else if (!stat.isDirectory() && entry.endsWith('.bru')) {
+        count++;
+      }
+    } catch {
+      // skip
+    }
+  }
+  return count;
+}
+
+async function findCollections(
+  dir: string
+): Promise<Array<{ name: string; path: string; request_count: number }>> {
+  const results: Array<{ name: string; path: string; request_count: number }> = [];
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return results;
+  }
+
+  if (entries.includes('bruno.json')) {
+    const brunoJsonPath = path.join(dir, 'bruno.json');
+    let name = path.basename(dir);
+    try {
+      const raw = await fs.readFile(brunoJsonPath, 'utf-8');
+      const parsed = JSON.parse(raw) as { name?: string };
+      if (parsed.name) name = parsed.name;
+    } catch {
+      // use dirname
+    }
+    // Count .bru files recursively so nested requests are included
+    const requestCount = await countBruFilesRecursively(dir);
+    results.push({ name, path: dir, request_count: requestCount });
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry);
+    try {
+      const stat = await fs.stat(fullPath);
+      if (stat.isDirectory() && entry !== 'node_modules') {
+        const nested = await findCollections(fullPath);
+        results.push(...nested);
+      }
+    } catch {
+      // skip
+    }
+  }
+
+  return results;
+}
+
+export default async function execute(params: Record<string, unknown>): Promise<unknown> {
+  const workspacePath = params.workspace_path as string;
+
+  if (!workspacePath) {
+    return { success: false, collections: [], errors: ['workspace_path parameter is required'] };
+  }
+
+  try {
+    logger.info(`Listing collections in: ${workspacePath}`);
+    const absolutePath = path.resolve(workspacePath);
+    let collections = await findCollections(absolutePath);
+
+    if (params.filter) {
+      const filter = (params.filter as string).toLowerCase();
+      collections = collections.filter((c) => c.name.toLowerCase().includes(filter));
+    }
+
+    return { success: true, collections };
+  } catch (error) {
+    logger.error(
+      `List collections failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return {
+      success: false,
+      collections: [],
+      errors: [error instanceof Error ? error.message : String(error)],
+    };
+  }
+}

package/tools/bruno_run_collection/definition.yaml

@@ -0,0 +1,131 @@
+name: bruno_run_collection
+description: Execute a Bruno API collection with configurable environment, data files, and reporting options. Returns structured JSON results with test assertions, metrics, and failure details.
+version: '1.0.0'
+status: approved
+
+parameters:
+  collection_path:
+    type: string
+    required: true
+    description: Path to Bruno collection file (.bru) or collection directory
+
+  environment:
+    type: string
+    required: false
+    description: Environment name to use for execution (e.g., dev, staging, prod)
+
+  env_file:
+    type: string
+    required: false
+    description: Path to environment file (.bru or .json) to override collection environment
+
+  data_file:
+    type: string
+    required: false
+    description: Path to CSV or JSON data file for data-driven testing
+
+  iteration_count:
+    type: number
+    required: false
+    default: 1
+    description: Number of times to run the collection
+
+  delay_ms:
+    type: number
+    required: false
+    description: Delay between each request in milliseconds
+
+  tags:
+    type: string
+    required: false
+    description: Comma-separated tags - only run requests with ALL specified tags
+
+  exclude_tags:
+    type: string
+    required: false
+    description: Comma-separated tags - skip requests with ANY of these tags
+
+  tests_only:
+    type: boolean
+    required: false
+    default: false
+    description: Only run requests that have tests or active assertions
+
+  bail_on_failure:
+    type: boolean
+    required: false
+    default: false
+    description: Stop execution after first failure
+
+  parallel:
+    type: boolean
+    required: false
+    default: false
+    description: Run requests in parallel order
+
+  sandbox_mode:
+    type: string
+    required: false
+    default: safe
+    description: JavaScript execution mode - 'safe' or 'developer'
+
+  report_path:
+    type: string
+    required: false
+    description: Custom path for JSON report output (defaults to temp directory)
+
+execution:
+  type: function
+  code: index.ts
+  timeout: 120000
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    summary:
+      type: object
+      properties:
+        total_requests:
+          type: number
+        passed:
+          type: number
+        failed:
+          type: number
+        execution_time_ms:
+          type: number
+    results:
+      type: array
+      items:
+        type: object
+    errors:
+      type: array
+      items:
+        type: string
+    report_path:
+      type: string
+
+
+examples:
+  - name: "Run entire collection against staging"
+    params:
+      collection_path: "./collections/my-api"
+      environment: "staging"
+      report_format: json
+      report_path: "./reports/staging-results.json"
+
+  - name: "Run data-driven tests with bail on failure"
+    params:
+      collection_path: "./collections/auth-flow.bru"
+      data_file: "./data/users.csv"
+      bail_on_failure: true
+      report_format: html
+      report_path: "./reports/auth-flow.html"
+
+  - name: "Run only tagged tests in parallel"
+    params:
+      collection_path: "./collections/api"
+      tags: "smoke,critical"
+      parallel: true
+      iteration_count: 3

package/tools/bruno_run_collection/index.ts

@@ -0,0 +1,99 @@
+import { getGlobalMatimoLogger } from '@matimo/core';
+import { execFileSync } from 'child_process';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { checkBruVersion } from '../bru-utils';
+
+const logger = getGlobalMatimoLogger();
+
+export default async function execute(params: Record<string, unknown>): Promise<unknown> {
+  const collectionPath = params.collection_path as string;
+
+  if (!collectionPath) {
+    return {
+      success: false,
+      summary: { total_requests: 0, passed: 0, failed: 0, execution_time_ms: 0 },
+      results: [],
+      errors: ['collection_path parameter is required'],
+    };
+  }
+
+  checkBruVersion();
+
+  const absolutePath = path.resolve(collectionPath);
+  const reportPath = path.resolve((params.report_path as string | undefined) ?? path.join(os.tmpdir(), `bru-report-${Date.now()}.json`));
+
+  try {
+    logger.info(`Running Bruno collection: ${absolutePath}`);
+
+    const args: string[] = ['run', '.', '-r', '--reporter-json', reportPath];
+
+    if (params.environment) args.push('--env', params.environment as string);
+    if (params.env_file) args.push('--env-file', params.env_file as string);
+    if (params.data_file) args.push('--csv-file-path', params.data_file as string);
+    if (params.iteration_count) args.push('--iteration-count', String(params.iteration_count));
+    if (params.delay_ms) args.push('--delay', String(params.delay_ms));
+    if (params.tags) args.push('--tags', params.tags as string);
+    if (params.exclude_tags) args.push('--exclude-tags', params.exclude_tags as string);
+    if (params.tests_only === true) args.push('--tests-only');
+    if (params.bail_on_failure === true) args.push('--bail');
+    if (params.parallel === true) args.push('--parallel');
+    args.push('--sandbox', (params.sandbox_mode as string) || 'safe');
+
+    logger.debug(`Executing: bru ${args.join(' ')}`);
+
+    let exitCode = 0;
+    try {
+      execFileSync('bru', args, { encoding: 'utf-8', stdio: 'pipe', cwd: absolutePath });
+    } catch (execError) {
+      // bru exits non-zero when tests fail — that's OK, we still read the report
+      exitCode = 1;
+      logger.warn(`bru run exited with non-zero status: ${execError instanceof Error ? execError.message : String(execError)}`);
+    }
+
+    // Read JSON report written by --reporter-json
+    let reportData: Record<string, unknown> = {};
+    try {
+      const raw = await fs.readFile(reportPath, 'utf-8');
+      reportData = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      logger.warn('Could not read/parse JSON report');
+    }
+
+    // Map Bruno report fields to schema-declared keys
+    const summaryRaw = (reportData.summary as Record<string, number> | undefined) ?? {};
+    const totalRequests = (summaryRaw.totalRequests ?? 0) as number;
+    const passed = (summaryRaw.passedRequests ?? 0) as number;
+    const failed = (summaryRaw.failedRequests ?? 0) as number;
+    const executionTimeMs = (summaryRaw.totalTime ?? 0) as number;
+
+    const rawResults = (reportData.results as unknown[]) ?? [];
+    const results = rawResults.map((r) => {
+      const req = r as Record<string, unknown>;
+      return {
+        name: req.suiteName ?? req.name ?? 'unknown',
+        success: req.status === 'pass' || req.passed === true,
+        status: (req.response as Record<string, unknown> | undefined)?.status ?? 0,
+      };
+    });
+
+    return {
+      success: exitCode === 0,
+      summary: { total_requests: totalRequests, passed, failed, execution_time_ms: executionTimeMs },
+      results,
+      report_path: reportPath,
+      errors: [],
+    };
+  } catch (error) {
+    logger.error(
+      `Collection execution failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return {
+      success: false,
+      summary: { total_requests: 0, passed: 0, failed: 0, execution_time_ms: 0 },
+      results: [],
+      errors: [error instanceof Error ? error.message : String(error)],
+    };
+  }
+}