@theholocron/holocron-plugin-postman 5.0.0-alpha.437 → 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/README.md +20 -18
- package/dist/index.d.mts +10 -1
- package/dist/index.mjs +122 -26
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -19,7 +19,8 @@ Postman ships a CLI (`postman`, the newer + more capable successor to
|
|
|
19
19
|
`newman`), but for our `tooling` surface — collection / spec / environment
|
|
20
20
|
**management** — REST is the canonical interface and avoids a system-binary
|
|
21
21
|
dependency. The CLI is best suited for running collections (the newman use
|
|
22
|
-
case); we sync, we don't run.
|
|
22
|
+
case); we sync, we don't run. The one thing it uses the CLI for is `export`
|
|
23
|
+
(below), which has no REST equivalent.
|
|
23
24
|
|
|
24
25
|
## Auth
|
|
25
26
|
|
|
@@ -69,23 +70,24 @@ Generate the key at <https://web.postman.co/settings/me/api-keys>.
|
|
|
69
70
|
|
|
70
71
|
## What's implemented
|
|
71
72
|
|
|
72
|
-
| Method | What it does
|
|
73
|
-
| ---------------------------------------------------------------------------------- |
|
|
74
|
-
| **Tooling interface** |
|
|
75
|
-
| `sync()` | Finds or makes the workspace; with `specFile`, upserts the Spec Hub spec and delete-then-imports the collection; replaces or creates each `collectionFiles` collection; find-or-creates each env in `envFiles`.
|
|
76
|
-
| `
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
73
|
+
| Method | What it does |
|
|
74
|
+
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
75
|
+
| **Tooling interface** | |
|
|
76
|
+
| `sync()` | Finds or makes the workspace; with `specFile`, upserts the Spec Hub spec and delete-then-imports the collection; replaces or creates each `collectionFiles` collection; find-or-creates each env in `envFiles`. |
|
|
77
|
+
| `export(input)` | Optional. Runs `postman collection migrate <file> --output <dir>` for each collection file (the Postman CLI, `brew install --cask postman-cli`, or `./.humans/setup.sh` in this repo) and lists the files it wrote, one folder per collection: Postman's schema 3.0 YAML. An environment file is reported as not exported. No API key, no workspace. A dry run migrates into a temporary folder and removes it. Not verified against the real CLI. |
|
|
78
|
+
| `doctor()` | Probes `/me` + `/workspaces`; returns `{ ok, message }`. |
|
|
79
|
+
| **Postman-specific methods** (on `PostmanTooling`, not on the `Tooling` interface) | |
|
|
80
|
+
| `getMyself` | `GET /me` — authed user identity. |
|
|
81
|
+
| `listWorkspaces` | `GET /workspaces`. |
|
|
82
|
+
| `findCollectionByName` | `GET /collections?workspace=…` + name filter. |
|
|
83
|
+
| `deleteCollection` | `DELETE /collections/{uid}`. |
|
|
84
|
+
| `importOpenApi` | `POST /import/openapi?workspace=…` with the spec stringified into `{ type: "string", input }`. |
|
|
85
|
+
| `findEnvironmentByName` | `GET /environments?workspace=…` + name filter. |
|
|
86
|
+
| `createEnvironment` | `POST /environments?workspace=…`. |
|
|
87
|
+
| `updateEnvironment` | `PUT /environments/{uid}`. |
|
|
88
|
+
| `findSpecByName` | `GET /specs?workspaceId=…` + name filter. |
|
|
89
|
+
| `createSpec` | `POST /specs?workspaceId=…` (flat body — name/type are NOT wrapped under `spec`). |
|
|
90
|
+
| `upsertSpecFile` | `PATCH /specs/{id}/files/{path}` (PUT returns 404 here). |
|
|
89
91
|
|
|
90
92
|
## Status
|
|
91
93
|
|
package/dist/index.d.mts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { AuthError, PluginToken, ResolveTokenInput, Tooling, ToolingDoctorReport, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
|
|
1
|
+
import { AuthError, PluginToken, ResolveTokenInput, Tooling, ToolingDoctorReport, ToolingExportInput, ToolingExportResult, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
|
|
2
|
+
import { spawnSync } from "node:child_process";
|
|
2
3
|
import { PostmanClient, PostmanClient as PostmanClient$1, PostmanClientOptions, PostmanCollection, PostmanEnvironment, PostmanPlanLimitError, PostmanSpec, PostmanUser, PostmanWorkspace, createPostmanClient, detectPlanLimit } from "@theholocron/postman-client";
|
|
3
4
|
/** Resolves the Postman API key from `--token`, `HOLOCRON_POSTMAN_TOKEN`, `POSTMAN_API_KEY` or the keyring, and throws an `AuthError` when none is set. */
|
|
4
5
|
export declare const resolveToken: import("@theholocron/cli").TokenResolver;
|
|
@@ -23,6 +24,8 @@ interface PostmanToolingOptions {
|
|
|
23
24
|
envFiles?: string[];
|
|
24
25
|
/** Working repo root. Defaults to process.cwd(). */
|
|
25
26
|
repoRoot?: string;
|
|
27
|
+
/** Override the spawn function the Postman CLI is run with, in tests. */
|
|
28
|
+
spawn?: typeof spawnSync;
|
|
26
29
|
}
|
|
27
30
|
/** The Postman implementation of the `tooling` capability: syncs an OpenAPI spec, collection and environments into a workspace. */
|
|
28
31
|
export declare class PostmanTooling implements Tooling {
|
|
@@ -41,6 +44,12 @@ export declare class PostmanTooling implements Tooling {
|
|
|
41
44
|
private syncEnvironmentFile;
|
|
42
45
|
/** The workspace id: `workspaceId`, else the workspace named `workspace`, which is made when absent. Memoized. */
|
|
43
46
|
private resolveWorkspaceId;
|
|
47
|
+
/**
|
|
48
|
+
* Writes each collection file in Postman's schema 3.0 YAML layout under `input.outDir` by running the Postman CLI
|
|
49
|
+
* (`postman collection migrate`), one folder per collection. Environment files are reported as issues, not exported.
|
|
50
|
+
* Needs the CLI on the PATH and no API key: it never touches the workspace.
|
|
51
|
+
*/
|
|
52
|
+
export(input: ToolingExportInput): Promise<ToolingExportResult>;
|
|
44
53
|
/** Checks the key and the configured workspace; reports the authenticated user and the workspace, or why either failed. */
|
|
45
54
|
doctor(): Promise<ToolingDoctorReport>;
|
|
46
55
|
/** Returns the authenticated Postman user. */
|
package/dist/index.mjs
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import { AuthError, ProviderApiError, connectionProbe, createResolveToken } from "@theholocron/cli";
|
|
2
|
-
import { readFile } from "node:fs/promises";
|
|
3
|
-
import { basename, resolve } from "node:path";
|
|
2
|
+
import { mkdir, mkdtemp, readFile, readdir, rm } from "node:fs/promises";
|
|
3
|
+
import { basename, extname, join, relative, resolve } from "node:path";
|
|
4
4
|
import { errorMessage } from "@theholocron/misc-utils";
|
|
5
|
+
import { tmpdir } from "node:os";
|
|
6
|
+
import { spawnSync } from "node:child_process";
|
|
5
7
|
import { PostmanPlanLimitError, createPostmanClient, detectPlanLimit } from "@theholocron/postman-client";
|
|
6
8
|
// src/auth.ts
|
|
7
9
|
/** Resolves the Postman API key from `--token`, `HOLOCRON_POSTMAN_TOKEN`, `POSTMAN_API_KEY` or the keyring, and throws an `AuthError` when none is set. */
|
|
@@ -13,34 +15,119 @@ const resolveToken = createResolveToken({
|
|
|
13
15
|
});
|
|
14
16
|
/** Every token this plugin takes, for `holocron doctor secrets --verify`. */
|
|
15
17
|
const tokens = [resolveToken.token];
|
|
16
|
-
// src/
|
|
18
|
+
// src/export-collections.ts
|
|
17
19
|
/**
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
20
|
+
* The folder each collection is written to, in order: its own file name without the extension (`collection.json`
|
|
21
|
+
* is `collection`). Two files with the same name would write into one folder, so those use the whole path instead,
|
|
22
|
+
* its folders joined with `-` (`apps-a-collection`).
|
|
23
|
+
*/
|
|
24
|
+
function exportDirNames(files) {
|
|
25
|
+
const stem = (file) => basename(file, extname(file));
|
|
26
|
+
const counts = /* @__PURE__ */ new Map();
|
|
27
|
+
for (const file of files) counts.set(stem(file), (counts.get(stem(file)) ?? 0) + 1);
|
|
28
|
+
return files.map((file) => {
|
|
29
|
+
if (counts.get(stem(file)) === 1) return stem(file);
|
|
30
|
+
return file.slice(0, file.length - extname(file).length).split("/").filter(Boolean).join("-");
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
/** Every file below `dir`, relative to it and sorted; a folder that is not there holds none. */
|
|
34
|
+
async function listFiles(dir) {
|
|
35
|
+
return (await readdir(dir, {
|
|
36
|
+
recursive: true,
|
|
37
|
+
withFileTypes: true
|
|
38
|
+
}).catch(() => [])).filter((entry) => entry.isFile()).map((entry) => relative(dir, join(entry.parentPath, entry.name))).sort();
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Writes each collection in Postman's schema 3.0 YAML layout by running `postman collection migrate` on it, one folder
|
|
42
|
+
* per collection under `outDir`. The CLI only migrates collections, so an environment file is reported as an issue and
|
|
43
|
+
* not exported. On a dry run the CLI writes into a temporary folder, which is listed and then removed, so `outDir` is
|
|
44
|
+
* never touched. A collection the CLI cannot migrate throws, naming the file.
|
|
45
|
+
*/
|
|
46
|
+
async function exportCollections(input, cli) {
|
|
47
|
+
const { collectionFiles, envFiles, outDir, repoRoot } = input;
|
|
48
|
+
const names = exportDirNames(collectionFiles);
|
|
49
|
+
const base = input.dryRun ? await mkdtemp(join(tmpdir(), "holocron-export-")) : outDir;
|
|
50
|
+
const files = [];
|
|
51
|
+
const issues = [];
|
|
52
|
+
try {
|
|
53
|
+
if (!input.dryRun) await mkdir(outDir, { recursive: true });
|
|
54
|
+
for (const [index, file] of collectionFiles.entries()) {
|
|
55
|
+
const name = names[index];
|
|
56
|
+
cli.migrate(resolve(repoRoot, file), join(base, name));
|
|
57
|
+
const written = await listFiles(join(base, name));
|
|
58
|
+
if (written.length === 0) issues.push({
|
|
59
|
+
file,
|
|
60
|
+
message: "`postman collection migrate` wrote no files"
|
|
61
|
+
});
|
|
62
|
+
files.push(...written.map((path) => join(name, path)));
|
|
63
|
+
}
|
|
64
|
+
} finally {
|
|
65
|
+
if (input.dryRun) await rm(base, {
|
|
66
|
+
recursive: true,
|
|
67
|
+
force: true
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
for (const file of envFiles) issues.push({
|
|
71
|
+
file,
|
|
72
|
+
message: "not exported: `postman collection migrate` converts collections only, so there is no 3.0 environment"
|
|
73
|
+
});
|
|
74
|
+
return {
|
|
75
|
+
files,
|
|
76
|
+
issues
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
// src/shell.ts
|
|
80
|
+
/**
|
|
81
|
+
* Thin wrapper around `spawnSync` for the Postman CLI (`postman`), the CLI-transport counterpart of `rest.ts`.
|
|
37
82
|
*
|
|
38
|
-
* The
|
|
39
|
-
*
|
|
83
|
+
* The only thing it runs is `postman collection migrate <file> --output <dir>`, which writes a collection in
|
|
84
|
+
* Postman's schema 3.0 YAML layout. The stdio shape is the usual one for a vendor CLI, `['inherit', 'pipe', 'pipe']`:
|
|
85
|
+
* stdin stays attached so a CLI that wants a terminal can ask for one, and the output is read here.
|
|
40
86
|
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
87
|
+
* Not verified against the real CLI: it was not installed where this was written, so the arguments and the layout it
|
|
88
|
+
* writes follow Postman's documentation and are exercised only through an injected `spawn`.
|
|
43
89
|
*/
|
|
90
|
+
/** Where to install the CLI, said when it is missing. */
|
|
91
|
+
const INSTALL_HINT = "install it from https://learning.postman.com/docs/postman-cli/postman-cli-installation/ (macOS: brew install --cask postman-cli)";
|
|
92
|
+
/** The Postman CLI, run as a child process. */
|
|
93
|
+
var PostmanCli = class {
|
|
94
|
+
spawnImpl;
|
|
95
|
+
/** The binary this wrapper runs; defaults to `"postman"`. */
|
|
96
|
+
binary;
|
|
97
|
+
constructor(opts = {}) {
|
|
98
|
+
this.spawnImpl = opts.spawn ?? spawnSync;
|
|
99
|
+
this.binary = opts.binary ?? "postman";
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Runs `postman collection migrate <file> --output <outDir>` and throws when it cannot: the CLI is not installed,
|
|
103
|
+
* or it exits non-zero (its own message, trimmed, is the error).
|
|
104
|
+
*/
|
|
105
|
+
migrate(file, outDir) {
|
|
106
|
+
const out = this.spawnImpl(this.binary, [
|
|
107
|
+
"collection",
|
|
108
|
+
"migrate",
|
|
109
|
+
file,
|
|
110
|
+
"--output",
|
|
111
|
+
outDir
|
|
112
|
+
], {
|
|
113
|
+
encoding: "utf-8",
|
|
114
|
+
stdio: [
|
|
115
|
+
"inherit",
|
|
116
|
+
"pipe",
|
|
117
|
+
"pipe"
|
|
118
|
+
]
|
|
119
|
+
});
|
|
120
|
+
if (out.error) {
|
|
121
|
+
const missing = out.error.code === "ENOENT";
|
|
122
|
+
throw new Error(missing ? `the Postman CLI (\`${this.binary}\`) is not installed: ${INSTALL_HINT}` : `could not run \`${this.binary}\`: ${out.error.message}`, { cause: out.error });
|
|
123
|
+
}
|
|
124
|
+
if (out.status !== 0) {
|
|
125
|
+
const said = `${out.stderr ?? ""}`.trim() || `${out.stdout ?? ""}`.trim() || `exit status ${out.status}`;
|
|
126
|
+
throw new Error(`\`${this.binary} collection migrate\` failed for ${file}: ${said}`);
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
};
|
|
130
|
+
// src/capabilities/tooling.ts
|
|
44
131
|
/** The Postman implementation of the `tooling` capability: syncs an OpenAPI spec, collection and environments into a workspace. */
|
|
45
132
|
var PostmanTooling = class {
|
|
46
133
|
client;
|
|
@@ -153,6 +240,14 @@ var PostmanTooling = class {
|
|
|
153
240
|
return made.id;
|
|
154
241
|
})();
|
|
155
242
|
}
|
|
243
|
+
/**
|
|
244
|
+
* Writes each collection file in Postman's schema 3.0 YAML layout under `input.outDir` by running the Postman CLI
|
|
245
|
+
* (`postman collection migrate`), one folder per collection. Environment files are reported as issues, not exported.
|
|
246
|
+
* Needs the CLI on the PATH and no API key: it never touches the workspace.
|
|
247
|
+
*/
|
|
248
|
+
async export(input) {
|
|
249
|
+
return exportCollections(input, new PostmanCli(this.opts.spawn ? { spawn: this.opts.spawn } : {}));
|
|
250
|
+
}
|
|
156
251
|
/** Checks the key and the configured workspace; reports the authenticated user and the workspace, or why either failed. */
|
|
157
252
|
async doctor() {
|
|
158
253
|
try {
|
|
@@ -318,6 +413,7 @@ function tooling(ctx) {
|
|
|
318
413
|
if (ctx.options.collectionName !== void 0) opts.collectionName = ctx.options.collectionName;
|
|
319
414
|
if (ctx.options.envFiles !== void 0) opts.envFiles = ctx.options.envFiles;
|
|
320
415
|
if (ctx.options.repoRoot !== void 0) opts.repoRoot = ctx.options.repoRoot;
|
|
416
|
+
if (ctx.options.spawn !== void 0) opts.spawn = ctx.options.spawn;
|
|
321
417
|
return new PostmanTooling(ctx.client, opts);
|
|
322
418
|
}
|
|
323
419
|
/** Creates the Postman plugin: its `tooling` capability and its `connection` probe. */
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@theholocron/holocron-plugin-postman",
|
|
3
|
-
"version": "5.0.0-alpha.
|
|
3
|
+
"version": "5.0.0-alpha.442",
|
|
4
4
|
"description": "Holocron plugin for Postman. Implements the tooling capability against Postman's REST API — workspace + collection + spec + environment sync.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"holocron",
|
|
@@ -40,19 +40,19 @@
|
|
|
40
40
|
"tsx": "4.23.15",
|
|
41
41
|
"typescript": "^5.9.3",
|
|
42
42
|
"vitest": "^5.1.0",
|
|
43
|
-
"@theholocron/cli": "5.0.0-alpha.
|
|
44
|
-
"@theholocron/http-client": "^1.58.0-alpha.32",
|
|
43
|
+
"@theholocron/cli": "5.0.0-alpha.442",
|
|
45
44
|
"@theholocron/misc-utils": "^1.17.0-alpha.4",
|
|
46
45
|
"@theholocron/postman-client": "^1.58.0-alpha.32",
|
|
46
|
+
"@theholocron/eslint-config": "^8.9.0-alpha.17",
|
|
47
47
|
"@theholocron/tsdown-config": "^8.9.0-alpha.17",
|
|
48
|
-
"@theholocron/
|
|
48
|
+
"@theholocron/http-client": "^1.58.0-alpha.32",
|
|
49
49
|
"@theholocron/tsconfig": "^8.9.0-alpha.17",
|
|
50
|
-
"@theholocron/
|
|
50
|
+
"@theholocron/vitest-config": "^8.9.0-alpha.17"
|
|
51
51
|
},
|
|
52
52
|
"peerDependencies": {
|
|
53
53
|
"@theholocron/misc-utils": "^1.16.0",
|
|
54
54
|
"@theholocron/postman-client": "^1.43.1",
|
|
55
|
-
"@theholocron/cli": "5.0.0-alpha.
|
|
55
|
+
"@theholocron/cli": "5.0.0-alpha.442"
|
|
56
56
|
},
|
|
57
57
|
"peerDependenciesMeta": {
|
|
58
58
|
"@theholocron/postman-client": {}
|