@theholocron/holocron-plugin-bruno 0.0.0-stage → 5.0.0-alpha.442

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Newton Koumantzelis
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,47 @@
1
- # Temporary Holding Version
1
+ # `@theholocron/holocron-plugin-bruno`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Bruno plugin for [Holocron](../../cli/cli). Implements the `tooling` capability over files: `holocron export requests`
4
+ writes the repo's request collections as OpenCollection YAML, which Bruno imports. Bruno has no HTTP API and no account
5
+ to sync to, so there is no token and no network call.
6
+
7
+ ## Install
8
+
9
+ <!-- prettier-ignore -->
10
+ ```bash
11
+ pnpm add -D @theholocron/holocron-plugin-bruno
12
+
13
+ ```
14
+
15
+ ## Config
16
+
17
+ <!-- prettier-ignore -->
18
+ ```ts
19
+ providers: {
20
+ tooling: [
21
+ ["bruno", {
22
+ collectionFiles: ["requests/collection.json"],
23
+ envFiles: ["requests/environment.json"],
24
+ }],
25
+ ],
26
+ },
27
+ ```
28
+
29
+ ### Options
30
+
31
+ | Option | Required | Description |
32
+ | ----------------- | -------- | --------------------------------------------------------------------------------------------------- |
33
+ | `collectionFiles` | Yes | The collection JSON files (v2.1), relative to the repo root. Each becomes one YAML file. |
34
+ | `envFiles` | No | The environment JSON files, relative to the repo root. Every exported collection holds all of them. |
35
+
36
+ ## What it does
37
+
38
+ - `export` converts each collection with Bruno's collection reader (`@usebruno/converters`, which rewrites `pm.*` scripts to
39
+ `bru.*` / `req.*`) and the OpenCollection writer (`@opencollection/converters`), dumped with `js-yaml`, and writes
40
+ `<name>.yml` under the folder it is given. Environments are inside the document; a secret-type variable is marked `transient`.
41
+ Converter issues are returned, not thrown. A dry run converts and writes nothing.
42
+ - `sync` does nothing and succeeds: Bruno keeps no state, and the files are written by `export`.
43
+ - `doctor` checks `collectionFiles` is set and every file exists and parses as JSON.
44
+
45
+ ## Documentation
46
+
47
+ See the [plugin page](https://docs.theholocron.dev/holocron/plugins/bruno/).
@@ -0,0 +1,56 @@
1
+ import { Tooling, ToolingDoctorReport, ToolingExportInput, ToolingExportResult } from "@theholocron/cli";
2
+ /** Options for the Bruno `tooling` provider: the same two file lists the other tooling providers take. */
3
+ interface BrunoToolingOptions {
4
+ /** Collection JSON files (v2.1), relative to `repoRoot`. */
5
+ collectionFiles?: string[];
6
+ /** Environment JSON files, relative to `repoRoot`; each goes into every exported collection. */
7
+ envFiles?: string[];
8
+ /** Working repo root. Defaults to `process.cwd()`. */
9
+ repoRoot?: string;
10
+ }
11
+ /** The Bruno implementation of the `tooling` capability: files only. */
12
+ export declare class BrunoTooling implements Tooling {
13
+ private readonly options;
14
+ /** The capability this class provides, always `"tooling"`. */
15
+ readonly key: "tooling";
16
+ /** The provider name, `"bruno"`. */
17
+ readonly providerName = "bruno";
18
+ private readonly repoRoot;
19
+ constructor(options?: BrunoToolingOptions);
20
+ /** Nothing to reconcile: Bruno keeps no state of its own, and the files are written by {@link export}. */
21
+ sync(): Promise<void>;
22
+ doctor(): Promise<ToolingDoctorReport>;
23
+ export(input: ToolingExportInput): Promise<ToolingExportResult>;
24
+ }
25
+ /** What {@link convertCollection} produced. */
26
+ interface ConvertedCollection {
27
+ /** The OpenCollection document, as YAML. */
28
+ text: string;
29
+ /** What the converters reported they could not carry across, one line each. */
30
+ issues: string[];
31
+ }
32
+ /**
33
+ * Converts one v2.1 collection (and the environments that go with it) to an OpenCollection YAML document: Bruno's
34
+ * reader turns it into a Bruno collection and rewrites its `pm.*` scripts to `bru.*` / `req.*`, then the OpenCollection
35
+ * converter lays that out, environments included (a secret-type variable becomes `transient`). Each environment is
36
+ * given its `.bru` file name first, because that is where the OpenCollection converter takes its name from.
37
+ */
38
+ export declare function convertCollection(collection: unknown, environments: unknown[]): Promise<ConvertedCollection>;
39
+ /**
40
+ * The YAML file name for each collection file, in order: its own name with `.yml` for `.json` (`collection.json` is
41
+ * `collection.yml`). Two files with the same name would overwrite each other, so those use the whole path instead,
42
+ * its folders joined with `-` (`apps-a-collection.yml`).
43
+ */
44
+ export declare function outputNames(files: string[]): string[];
45
+ /** Options for the Bruno plugin; the same as the `tooling` capability's. */
46
+ export type BrunoPluginOptions = BrunoToolingOptions;
47
+ /** Builds the `tooling` capability from the plugin options. */
48
+ export declare function tooling(options: BrunoPluginOptions): Tooling;
49
+ /** Creates the Bruno plugin: its `tooling` capability. It has no probes, because there is nothing remote to poke. */
50
+ export declare function createPlugin(options?: BrunoPluginOptions): {
51
+ name: string;
52
+ capabilities: {
53
+ tooling: () => Tooling;
54
+ };
55
+ };
56
+ export type { BrunoToolingOptions, ConvertedCollection };
package/dist/index.mjs ADDED
@@ -0,0 +1,143 @@
1
+ import { mkdir, readFile, writeFile } from "node:fs/promises";
2
+ import { basename, extname, join, resolve } from "node:path";
3
+ import { brunoToOpenCollection } from "@opencollection/converters";
4
+ import { postmanToBruno, postmanToBrunoEnvironment } from "@usebruno/converters";
5
+ import { dump } from "js-yaml";
6
+ // src/convert-collection.ts
7
+ /** One line for a converter's issue, whatever shape it came in. */
8
+ const describeIssue = (issue) => {
9
+ if (typeof issue === "string") return issue;
10
+ if (issue !== null && typeof issue === "object" && "message" in issue && typeof issue.message === "string") return issue.message;
11
+ return JSON.stringify(issue);
12
+ };
13
+ /**
14
+ * Converts one v2.1 collection (and the environments that go with it) to an OpenCollection YAML document: Bruno's
15
+ * reader turns it into a Bruno collection and rewrites its `pm.*` scripts to `bru.*` / `req.*`, then the OpenCollection
16
+ * converter lays that out, environments included (a secret-type variable becomes `transient`). Each environment is
17
+ * given its `.bru` file name first, because that is where the OpenCollection converter takes its name from.
18
+ */
19
+ async function convertCollection(collection, environments) {
20
+ const read = await postmanToBruno(collection, { preserveScripts: false });
21
+ const bruno = read.collection;
22
+ const converted = await Promise.all(environments.map((env) => postmanToBrunoEnvironment(env)));
23
+ if (converted.length > 0) bruno.environments = converted.map((env) => ({
24
+ ...env,
25
+ filename: `${env.name}.bru`
26
+ }));
27
+ return {
28
+ text: dump(brunoToOpenCollection(bruno), { lineWidth: 120 }),
29
+ issues: (read.issues ?? []).map(describeIssue)
30
+ };
31
+ }
32
+ // src/output-names.ts
33
+ /**
34
+ * The YAML file name for each collection file, in order: its own name with `.yml` for `.json` (`collection.json` is
35
+ * `collection.yml`). Two files with the same name would overwrite each other, so those use the whole path instead,
36
+ * its folders joined with `-` (`apps-a-collection.yml`).
37
+ */
38
+ function outputNames(files) {
39
+ const stem = (file) => basename(file, extname(file));
40
+ const counts = /* @__PURE__ */ new Map();
41
+ for (const file of files) counts.set(stem(file), (counts.get(stem(file)) ?? 0) + 1);
42
+ return files.map((file) => {
43
+ if (counts.get(stem(file)) === 1) return `${stem(file)}.yml`;
44
+ return `${file.slice(0, file.length - extname(file).length).split("/").filter(Boolean).join("-")}.yml`;
45
+ });
46
+ }
47
+ // src/capabilities/tooling.ts
48
+ /**
49
+ * `tooling` capability for Bruno.
50
+ *
51
+ * Bruno has no HTTP API and no account to push to: it reads a folder of files. So this provider works on files only,
52
+ * with no token and no network, and its one real job is `export()`: it writes each of the repo's collection files as
53
+ * an OpenCollection YAML document (with the environments inside it), for `holocron export requests`.
54
+ *
55
+ * `sync()` has nothing to reconcile, so it does nothing and succeeds: `holocron setup` calls it on every `tooling`
56
+ * provider, and the files are written by `export()`, which is the person's call, never a side effect of `setup`.
57
+ * `doctor()` checks the input files exist and parse as JSON.
58
+ */
59
+ /** The text of what a read, a parse or a converter threw: always an `Error`. */
60
+ const message = (err) => err.message;
61
+ /** Reads and parses a JSON file; an unreadable or invalid one throws an error that names the file. */
62
+ async function readJson(root, file) {
63
+ try {
64
+ return JSON.parse(await readFile(resolve(root, file), "utf8"));
65
+ } catch (err) {
66
+ throw new Error(`${file}: ${message(err)}`, { cause: err });
67
+ }
68
+ }
69
+ /** The Bruno implementation of the `tooling` capability: files only. */
70
+ var BrunoTooling = class {
71
+ options;
72
+ /** The capability this class provides, always `"tooling"`. */
73
+ key = "tooling";
74
+ /** The provider name, `"bruno"`. */
75
+ providerName = "bruno";
76
+ repoRoot;
77
+ constructor(options = {}) {
78
+ this.options = options;
79
+ this.repoRoot = options.repoRoot ?? process.cwd();
80
+ }
81
+ /** Nothing to reconcile: Bruno keeps no state of its own, and the files are written by {@link export}. */
82
+ async sync() {}
83
+ async doctor() {
84
+ const { collectionFiles = [], envFiles = [] } = this.options;
85
+ if (collectionFiles.length === 0) return {
86
+ ok: false,
87
+ message: "no `collectionFiles` are set, so there is nothing to export"
88
+ };
89
+ const problems = [];
90
+ for (const file of [...collectionFiles, ...envFiles]) try {
91
+ await readJson(this.repoRoot, file);
92
+ } catch (err) {
93
+ problems.push(message(err));
94
+ }
95
+ if (problems.length > 0) return {
96
+ ok: false,
97
+ message: problems.join("; ")
98
+ };
99
+ return {
100
+ ok: true,
101
+ message: `${collectionFiles.length + envFiles.length} request file(s) read`
102
+ };
103
+ }
104
+ async export(input) {
105
+ const { collectionFiles, envFiles, outDir, repoRoot } = input;
106
+ const environments = await Promise.all(envFiles.map((file) => readJson(repoRoot, file)));
107
+ const names = outputNames(collectionFiles);
108
+ const files = [];
109
+ const issues = [];
110
+ for (const [index, file] of collectionFiles.entries()) {
111
+ const converted = await convertCollection(await readJson(repoRoot, file), environments).catch((err) => {
112
+ throw new Error(`${file}: ${message(err)}`, { cause: err });
113
+ });
114
+ for (const issue of converted.issues) issues.push({
115
+ file,
116
+ message: issue
117
+ });
118
+ const name = names[index];
119
+ if (!input.dryRun) {
120
+ await mkdir(outDir, { recursive: true });
121
+ await writeFile(join(outDir, name), converted.text);
122
+ }
123
+ files.push(name);
124
+ }
125
+ return {
126
+ files,
127
+ issues
128
+ };
129
+ }
130
+ };
131
+ // src/index.ts
132
+ /** Builds the `tooling` capability from the plugin options. */
133
+ function tooling(options) {
134
+ return new BrunoTooling(options);
135
+ }
136
+ /** Creates the Bruno plugin: its `tooling` capability. It has no probes, because there is nothing remote to poke. */
137
+ function createPlugin(options = {}) {
138
+ return {
139
+ name: "@theholocron/holocron-plugin-bruno",
140
+ capabilities: { tooling: () => tooling(options) }
141
+ };
142
+ }
143
+ export { BrunoTooling, convertCollection, createPlugin, outputNames, tooling };
package/package.json CHANGED
@@ -1,6 +1,70 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-bruno",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "5.0.0-alpha.442",
4
+ "description": "Holocron plugin for Bruno. Implements the tooling capability over files: it exports the repo's request collections as OpenCollection YAML.",
5
+ "keywords": [
6
+ "bruno",
7
+ "holocron",
8
+ "plugin",
9
+ "tooling"
10
+ ],
11
+ "homepage": "https://docs.theholocron.dev/holocron/plugins/bruno/",
12
+ "bugs": "https://github.com/theholocron/holocron/issues",
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/theholocron/holocron.git",
16
+ "directory": "plugins/holocron-plugin-bruno"
17
+ },
18
+ "license": "MIT",
19
+ "author": "Newton Koumantzelis",
20
+ "sideEffects": false,
21
+ "type": "module",
22
+ "exports": {
23
+ ".": {
24
+ "types": "./dist/index.d.mts",
25
+ "import": "./dist/index.mjs",
26
+ "default": "./dist/index.mjs"
27
+ }
28
+ },
29
+ "files": [
30
+ "dist"
31
+ ],
32
+ "dependencies": {
33
+ "@opencollection/converters": "^0.0.2",
34
+ "@usebruno/converters": "^0.25.0",
35
+ "js-yaml": "^5.5.0"
36
+ },
37
+ "devDependencies": {
38
+ "@types/node": "^26",
39
+ "@vitest/coverage-v8": "^5.1.0",
40
+ "@vitest/eslint-plugin": "^1.6.28",
41
+ "eslint": "^10.14.0",
42
+ "eslint-plugin-n": "^18.5.0",
43
+ "globals": "^17.14.0",
44
+ "tsdown": "^0.23.5",
45
+ "tsx": "4.23.15",
46
+ "typescript": "^5.9.3",
47
+ "vitest": "^5.1.0",
48
+ "@theholocron/cli": "5.0.0-alpha.442",
49
+ "@theholocron/eslint-config": "^8.9.0-alpha.17",
50
+ "@theholocron/tsconfig": "^8.9.0-alpha.17",
51
+ "@theholocron/vitest-config": "^8.9.0-alpha.17",
52
+ "@theholocron/tsdown-config": "^8.9.0-alpha.17"
53
+ },
54
+ "peerDependencies": {
55
+ "@theholocron/cli": "5.0.0-alpha.442"
56
+ },
57
+ "engines": {
58
+ "node": ">=22"
59
+ },
60
+ "publishConfig": {
61
+ "access": "public"
62
+ },
63
+ "scripts": {
64
+ "build": "tsdown",
65
+ "lint:code": "eslint .",
66
+ "test:unit": "vitest run --coverage",
67
+ "test:watch": "vitest",
68
+ "typecheck": "tsc --noEmit"
69
+ }
6
70
  }