# bru-converter

Convert [OpenCollection YAML](https://docs.usebruno.com/opencollection-yaml/overview) collections (Bruno v3.0+) to Bruno's `.bru` format for use with the [Bruno CLI](https://docs.usebruno.com/cli/overview).

## Why

Bruno's UI saves collections in the OpenCollection YAML format starting from v3.0. The Bruno CLI still operates on `.bru` files. This tool bridges the two: design your collections in Bruno UI, then convert them to `.bru` for scripting, CI/CD, or any workflow that relies on the CLI.

## Installation

```bash
npm install -g bru-converter
```

Or as a project dependency:

```bash
npm install bru-converter
```

## CLI

```bash
bru-converter <input-dir> [output-dir]
```

`input-dir` must contain an `opencollection.yml` file. `output-dir` defaults to `./output`.

```bash
# Convert a collection
bru-converter ./my-collection ./my-bru-collection

# Suppress summary output
bru-converter ./my-collection ./my-bru-collection --quiet
```

**Example output:**

```
Converted 12 requests, 2 environments, 3 folders
Output: ./my-bru-collection
Warnings:
  - users/draft.yml: Missing required field 'http.url' — skipped
```

Exit code `0` on success (warnings are non-fatal), `1` on error.

## Library

```typescript
import {
  convertCollection,  // filesystem: dir → dir
  convertRequest,     // in-memory: YAML string → .bru string
  convertManifest,    // in-memory: opencollection.yml → bruno.json + collection.bru
  convertFolder,      // in-memory: folder.yml → folder.bru string
  convertEnvironment, // in-memory: environment .yml → .bru string
} from 'bru-converter'
```

### Convert an entire collection

```typescript
const result = await convertCollection('./my-collection', './output')

console.log(`${result.requestsConverted} requests converted`)
console.log(`${result.environmentsConverted} environments converted`)

for (const warning of result.warnings) {
  console.warn(`[${warning.type}] ${warning.file}: ${warning.message}`)
}
```

### Convert a single request in memory

```typescript
import { convertRequest } from 'bru-converter'

const yaml = `
info:
  name: Get Users
  type: http
  seq: 1
http:
  method: GET
  url: https://api.example.com/users
  auth:
    type: bearer
    bearer:
      token: "{{api_token}}"
`

const bru = convertRequest(yaml)
// meta {
//   name: Get Users
//   type: http
//   seq: 1
// }
//
// get {
//   url: https://api.example.com/users
//   body: none
//   auth: bearer
// }
//
// auth:bearer {
//   token: {{api_token}}
// }
```

## Input / Output Structure

```
my-collection/              →    my-bru-collection/
├── opencollection.yml      →    ├── bruno.json
│                                ├── collection.bru
├── environments/           →    ├── environments/
│   └── dev.yml             →    │   └── dev.bru
├── users/                  →    ├── users/
│   ├── folder.yml          →    │   ├── folder.bru
│   ├── get-users.yml       →    │   ├── get-users.bru
│   └── create-user.yml     →    │   └── create-user.bru
└── orders/                 →    └── orders/
    └── list-orders.yml     →        └── list-orders.bru
```

## What Gets Converted

| OpenCollection | .bru output |
|---|---|
| `opencollection.yml` | `bruno.json` + `collection.bru` |
| `folder.yml` | `folder.bru` |
| Request `*.yml` | `*.bru` |
| `environments/*.yml` | `environments/*.bru` |

**Supported request features:** all HTTP methods, query/path params, headers, JSON/text/XML/GraphQL/form/multipart/file bodies, bearer/basic/API key/digest/OAuth2/AWS v4/NTLM/WSSE auth, pre-request scripts, post-response scripts, tests, assertions, variables, settings, docs.

**Non-fatal warnings** are emitted (without stopping conversion) for:
- Requests missing `http.method` or `http.url` — skipped
- Unrecognized top-level YAML fields — skipped
- Duplicate request names within a folder — renamed with numeric suffix (`-2`, `-3`, …)

## Requirements

- Node.js 18+
- Input must follow the [OpenCollection YAML spec](https://docs.usebruno.com/opencollection-yaml/overview) (Bruno v3.0+)

## Development

```bash
npm install
npm run build
npm test
```

## License

MIT