@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 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
- | `doctor()` | Probes `/me` + `/workspaces`; returns `{ ok, message }`. |
77
- | **Postman-specific methods** (on `PostmanTooling`, not on the `Tooling` interface) | |
78
- | `getMyself` | `GET /me` — authed user identity. |
79
- | `listWorkspaces` | `GET /workspaces`. |
80
- | `findCollectionByName` | `GET /collections?workspace=…` + name filter. |
81
- | `deleteCollection` | `DELETE /collections/{uid}`. |
82
- | `importOpenApi` | `POST /import/openapi?workspace=…` with the spec stringified into `{ type: "string", input }`. |
83
- | `findEnvironmentByName` | `GET /environments?workspace=…` + name filter. |
84
- | `createEnvironment` | `POST /environments?workspace=…`. |
85
- | `updateEnvironment` | `PUT /environments/{uid}`. |
86
- | `findSpecByName` | `GET /specs?workspaceId=…` + name filter. |
87
- | `createSpec` | `POST /specs?workspaceId=…` (flat body — name/type are NOT wrapped under `spec`). |
88
- | `upsertSpecFile` | `PATCH /specs/{id}/files/{path}` (PUT returns 404 here). |
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/capabilities/tooling.ts
18
+ // src/export-collections.ts
17
19
  /**
18
- * `tooling` capability for Postman.
19
- *
20
- * Ported from rando-id/rando.id `adapters/postman.ts`. The holocron
21
- * `Tooling` interface stays narrow (`sync` + `doctor`); the
22
- * Postman-specific surface (workspaces, collections, environments,
23
- * Spec Hub) lives as additional methods on this class for callers
24
- * that need direct access.
25
- *
26
- * `sync()` flow:
27
- * 1. Read the local OpenAPI spec from `options.specFile`
28
- * 2. Find or create the Spec Hub spec by name in the workspace;
29
- * upsert the spec file content
30
- * 3. Find any existing collection with the same name and delete it
31
- * (Postman's import-from-OpenAPI path is create-only — no stable
32
- * update path for collections produced from a spec)
33
- * 4. Import the spec as a fresh collection
34
- * 5. For each `collectionFiles[i]`, find the collection by `info.name` and replace it, or create it
35
- * 6. For each `envFiles[i]`, find-or-create the environment; a secret the file leaves empty keeps the value
36
- * the environment already holds
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 workspace is `workspaceId` when given, else the one named `workspace`, made (type `workspaceType`,
39
- * default `personal`) when it does not exist. `doctor()` never makes it.
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
- * `doctor()` probes `/me` for auth + `/workspaces` for workspace
42
- * reachability and returns a `ToolingDoctorReport`.
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.437",
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.437",
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/vitest-config": "^8.9.0-alpha.17",
48
+ "@theholocron/http-client": "^1.58.0-alpha.32",
49
49
  "@theholocron/tsconfig": "^8.9.0-alpha.17",
50
- "@theholocron/eslint-config": "^8.9.0-alpha.17"
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.437"
55
+ "@theholocron/cli": "5.0.0-alpha.442"
56
56
  },
57
57
  "peerDependenciesMeta": {
58
58
  "@theholocron/postman-client": {}