@postman/postman-plugin 0.2.2 → 0.4.0

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.
Files changed (53) hide show
  1. package/README.md +58 -10
  2. package/dist/hosts/antigravity.js +47 -0
  3. package/dist/hosts/copilot.js +60 -0
  4. package/dist/hosts/index.js +3 -1
  5. package/dist/hosts/opencode-config.js +147 -0
  6. package/dist/hosts/opencode.js +315 -34
  7. package/dist/hosts/shared.js +10 -3
  8. package/dist/source.js +19 -5
  9. package/dist/system.js +20 -1
  10. package/hooks/session-start-context.md +1 -1
  11. package/mcp.pi.json +2 -2
  12. package/package.json +1 -1
  13. package/skills/ai-readiness/SKILL.md +40 -44
  14. package/skills/api-discovery/SKILL.md +64 -129
  15. package/skills/api-discovery/reference/orbit.md +17 -5
  16. package/skills/api-documentation/SKILL.md +38 -25
  17. package/skills/api-engineer/SKILL.md +78 -23
  18. package/skills/api-mocking/SKILL.md +117 -135
  19. package/skills/api-monitoring/SKILL.md +52 -129
  20. package/skills/api-simulation/SKILL.md +138 -0
  21. package/skills/api-simulation/reference/sim_yaml_schema.md +50 -0
  22. package/skills/api-testing/SKILL.md +48 -95
  23. package/skills/bootstrap/SKILL.md +123 -210
  24. package/skills/bootstrap/reference/cli_installation.md +4 -3
  25. package/skills/ci-integration/SKILL.md +53 -112
  26. package/skills/collection-schema-v3/SKILL.md +43 -204
  27. package/skills/collection-schema-v3/reference/http.md +150 -0
  28. package/skills/datasets/SKILL.md +89 -314
  29. package/skills/datasets/reference/spreadsheets.md +25 -0
  30. package/skills/flows/SKILL.md +57 -206
  31. package/skills/flows/reference/flow_cli_flags.md +3 -2
  32. package/skills/performance-testing/SKILL.md +46 -62
  33. package/skills/performance-testing/references/jmeter-import/README.md +113 -0
  34. package/skills/performance-testing/references/jmeter-import/import-report.md +52 -0
  35. package/skills/performance-testing/references/jmeter-import/mapping-table.md +97 -0
  36. package/skills/performance-testing/references/jmeter-import/postman-perf-capabilities.md +56 -0
  37. package/skills/performance-testing/references/jmeter-import/script-translation.md +98 -0
  38. package/skills/performance-testing/references/jmeter-import/scripts/groovy_to_js.py +83 -0
  39. package/skills/performance-testing/references/jmeter-import/scripts/jmx_to_postman.py +1433 -0
  40. package/skills/postman-mcp-server/SKILL.md +53 -59
  41. package/skills/postman-mcp-server/references/docs.md +0 -1
  42. package/skills/postman-mcp-server/references/learn.md +10 -9
  43. package/skills/postman-mcp-server/references/mock.md +0 -1
  44. package/skills/postman-mcp-server/references/search.md +0 -1
  45. package/skills/postman-mcp-server/references/security.md +0 -1
  46. package/skills/postman-mcp-server/references/setup.md +0 -1
  47. package/skills/postman-mcp-server/references/sync.md +0 -1
  48. package/skills/postman-mcp-server/references/test.md +0 -1
  49. package/skills/variables/SKILL.md +63 -0
  50. package/skills/webhook-testing/SKILL.md +103 -0
  51. package/skills/webhook-testing/reference/forwarding.md +10 -0
  52. package/skills/webhook-testing/reference/outbound_webhooks.md +25 -0
  53. package/skills/webhook-testing/reference/webhook_scripts.md +163 -0
@@ -1,216 +1,129 @@
1
1
  ---
2
2
  name: bootstrap
3
- description: Resolves the Postman CLI, authenticates when the task needs it, and manages the filesystem/workspace binding for a repository. Use when the user asks to set up Postman, enable filesystem workflows, authenticate, initialize, import, connect, pull, push, sync, or share a workspace — and before skills that need a linked workspace, only when the CLI, linked workspace, or spec path has not already been confirmed.
3
+ description: Use when resolving Postman CLI setup, authentication, or a repository workspace binding; initializing local API files; handling a CLI error that says an operation isn't allowed because of insufficient entitlements; or importing, pulling, pushing, syncing, or sharing workspace resources. Reuses existing context and chooses sync direction without duplicating a workspace or rebinding a dependency. Use for requests such as "set up Postman for this repo".
4
4
  ---
5
5
 
6
6
  # Bootstrap Postman for This Repo
7
7
 
8
- ## Overview
9
-
10
- One-time and idempotent: every other Postman skill in this plugin reads the
11
- values this one records and re-derives none of them. Finding an existing
12
- `postman/` tree or an OpenAPI file is a signal to inspect, not to assume this
13
- repo is already set up.
14
-
15
- ## Rules
16
-
17
- - Make ad-hoc HTTP calls with `postman request`, never `curl` or another
18
- client. If the request already exists in a collection, preserve its saved
19
- auth, variables, scripts, and payload by using `postman collection run
20
- <collection-path> -i <request>` instead of reconstructing it on the command
21
- line; see `api-testing`.
22
- - Never invent a subcommand or a flag. Run `-h` first and believe it.
23
- - Lint specs with `postman spec lint`, never `postman api …` — the API Builder
24
- is deprecated in v12+ and the CLI prints no warning.
25
- - Local commands need no login; only commands that reach the Postman
26
- workspace do. Don't force a login the task doesn't need.
27
- - A missing `postman` binary means install it. Route to `postman-mcp-server`
28
- only after an install has been attempted and actually failed.
29
- - Never fabricate a workspace id, spec path, or collections directory. Report
30
- the gap and stop.
31
- - Never echo an API key or session token into output, logs, or summaries.
32
- - "Present" is not "current": check the version and existing links before
33
- setting anything up.
34
- - Wire up an existing repo only. Never scaffold a new API or a starter spec.
35
- - Write no host-specific paths — the same `skills/` directory loads on every
36
- route.
37
- - Do not use `init` or `workspace create` to share or import a workspace that
38
- already exists. Choose the direction of sync from the lifecycle table below.
39
-
40
- ## Ask the CLI: `-h`
41
-
42
- The CLI is self-describing at different levels. Walk down only as far as the
43
- question needs:
44
-
45
- ```bash
46
- postman -h # resources: collection, spec, mock, monitor, workspace, api, flows…
47
- postman <resource> -h # that resource's actions
48
- postman <resource> <action> -h # real flags, defaults, and worked `Eg.` lines
49
- ```
50
-
51
- Read the third level before writing any command that carries a flag — it is the
52
- only place defaults are stated, and a wrong default fails silently. Live output
53
- is authoritative over any summary, including this file. There is also no single
54
- verb for "is the workspace linked and synced": run `postman workspace -h` and
55
- pick from what it prints.
56
-
57
- ---
58
-
59
- # Process
60
-
61
- Three steps, in order. Stop at the first that fails and report which one.
62
-
63
- ## 1. Resolve the CLI
64
-
65
- ### 1.1 Check what is already there
66
-
67
- **Present, and at which version?**
68
-
69
- ```bash
70
- command -v postman && postman --version
71
- ```
72
-
73
- **Current?** Never blocking — no network is a normal answer. But don't call a
74
- feature missing without having made this comparison.
75
-
76
- ```bash
77
- npm view postman-cli version
78
- ```
79
-
80
- ### 1.2 Install only if missing
81
-
82
- **Preferred — npm, all platforms:**
83
-
84
- ```bash
85
- npm install -g postman-cli
86
- ```
87
-
88
- **Windows, or avoiding a global npm install:** use the platform installers in
89
- [reference/cli_installation.md](reference/cli_installation.md). Every route puts
90
- `postman` on `PATH`.
91
-
92
- **Updating a copy that already exists:** use the same route that installed it.
93
- curl-installed binaries don't take `npm install -g` cleanly.
94
-
95
- **If every route fails:** name what blocked you — no Node, no shell, no write
96
- access, or a hosted session that cannot install — then hand off to the
97
- `postman-mcp-server` skill. An attempted install that actually failed is the
98
- only thing that qualifies.
99
-
100
- ## 2. Establish the filesystem and workspace bindings
101
-
102
- ### 2.1 Authenticate only if this step needs it
103
-
104
- Local commands need no login, and `postman init` is among them — its own help
105
- says *"No authentication, and safe in CI."* Skip this entirely unless the
106
- command you're about to run pulls or pushes an existing workspace, or shares
107
- one with a team.
108
-
109
- **With an API key — preferred, non-interactive:**
110
-
111
- ```bash
112
- [ -n "$POSTMAN_API_KEY" ] && postman login --with-api-key "$POSTMAN_API_KEY"
113
- ```
114
-
115
- **Browser flow, when that variable is unset:**
116
-
117
- ```bash
118
- postman login
119
- ```
120
-
121
- **Never echo the key or token.** Auth state lives in the CLI's own config; this
122
- skill writes no credential file. Report that authentication succeeded, nothing
123
- more.
124
-
125
- ### 2.2 Inspect both sides before choosing a command
126
-
127
- Read `.postman/resources.yaml` for `localResources` and `workspace.id`, and
128
- inspect the local `postman/` tree. When the user names an existing workspace or
129
- asks to import, sync, or share one, use `workspace list --json` and `workspace
130
- get <id> --elements --json` to confirm the workspace side. Never create a
131
- second workspace merely because this repository is not connected yet.
132
-
133
- Prefer filesystem-first work: materialize an existing workspace with
134
- `workspace pull <id>`, or initialize local files with `postman init --no-cloud`
135
- when no workspace exists. Then inspect, edit, diff, and validate the
136
- version-controlled files before any push.
137
-
138
- | Existing state and intent | Use | Why |
139
- | --- | --- | --- |
140
- | No workspace exists; start locally | `postman init --json --no-cloud` | Creates the git-native filesystem without requiring login. |
141
- | No workspace exists; create and bind one | `postman workspace create --visibility <value>` or the explicit init creation path | Creation is the requested lifecycle event. |
142
- | Workspace exists; enable filesystem work | `postman workspace pull <workspace-id>` | Connects the workspace to the repository and materializes its entities under `postman/`. |
143
- | Workspace exists; record only the Git binding | `postman workspace connect-git <workspace-id> [path]` | Binds without downloading its contents. |
144
- | Bound workspace; the workspace is authoritative | `postman workspace pull` | Refreshes local files from the connected workspace. |
145
- | Bound workspace; local files are authoritative | `postman workspace diff --push-strategy default`, then `postman workspace push` | Previews and publishes creates/updates without deleting unmatched workspace entities. |
146
- | “Share this existing workspace with my team” and it is already team-accessible | Diff, then `postman workspace push` | Publishes local contents to the existing workspace; `create` would make a duplicate. |
147
-
148
- If “share” also requires changing a personal workspace's visibility or team
149
- permissions, inspect its metadata first. `push` synchronizes entities; it does
150
- not change access control. Do not create a replacement to work around a missing
151
- metadata-update command.
152
-
153
- `workspace diff` is read-only. Match its push strategy to the intended push.
154
- `--push-strategy force-sync` can delete workspace entities absent locally, so use it
155
- only when the user explicitly requests mirroring and approves the shown
156
- deletions. Do not add `-y` merely to bypass a prompt.
157
-
158
- ### 2.3 Initialize only when there is no workspace to pull
159
-
160
- `postman init --json` is the agent-facing form. It writes
161
- `.postman/resources.yaml` and scaffolds `postman/` for specs, collections and
162
- environments. Downstream skills read that file and nothing else.
163
-
164
- ```bash
165
- postman init --json --no-cloud # local only, no workspace
166
- postman init --json --visibility personal # also create and bind a workspace
167
- ```
168
-
169
- Use `--visibility` only when a new workspace is actually wanted. If the
170
- workspace already exists, use `pull` to enable the filesystem workflow;
171
- use `push` only when publishing local changes to an already-bound workspace.
172
-
173
- **The workspace step is interactive** without `--no-cloud` or `--visibility`.
174
-
175
- **Read the payload, not stderr.** Take `bindings` and `exitCode` from the JSON.
176
- Each binding reports a `source` of `inferred` or `none` — an inferred spec is a
177
- guess worth confirming before building on it.
178
-
179
- **Exit codes that are not failures:** 2 means several specs could be
180
- authoritative, so re-run with `--spec <path>`. 5 means the local files were
181
- written but the requested workspace was not created — it does *not* mean re-run.
182
-
183
- ## 3. Verify and report
184
-
185
- ### 3.1 Checkpoints
186
-
187
- - `postman --version` returned a real version.
188
- - Auth is confirmed, or established as not required for this task.
189
- - `.postman/resources.yaml` names a spec or a collections directory.
190
- - `workspace.id` is set, or the run was deliberately local-only — `--no-cloud`
191
- leaves it empty and still exits 0, which is a pass, not a gap.
192
- - After `pull`, expected workspace entities exist under `postman/`. After
193
- `push`, report created/updated entities and conflicts; do not claim a
194
- workspace is shared unless its access level permits the intended teammates.
195
-
196
- "The CLI is installed" is not the bar, and a loaded skill configures nothing.
197
-
198
- ### 3.2 Summary format
199
-
200
- ```md
201
- ## Postman bootstrap
202
- - **CLI**: <version> (latest: <version> | not checked)
203
- - **Auth**: <api-key | browser | not required for this task>
204
- - **Workspace**: <id | none — local only>
205
- - **Spec path**: <path (inferred | explicit) | none — user must create>
206
- - **Collections dir**: <path | none — user must create>
207
- ```
208
-
209
- ---
210
-
211
- # Reference Files
212
-
213
- - `collection-schema-v3` skill — read when inspecting or writing the
214
- collection files this skill resolves.
215
- - [CLI Installation](reference/cli_installation.md) — read for install, update
216
- and uninstall commands per platform.
8
+ A local Postman project puts contracts, runnable requests, environments, and
9
+ mocks beside implementation code so they can be inspected, diffed, and reviewed
10
+ in a PR. A workspace binding connects that work to maintained shared context.
11
+ Setup is useful when it resolves a missing capability or binding; a local API
12
+ check does not need a new workspace merely to proceed.
13
+
14
+ ## Resolve only the missing setup
15
+
16
+ Inspect `postman --version`, `.postman/resources.yaml`, and the relevant
17
+ `postman/` files before installing or initializing. Existing files are clues,
18
+ not proof that paths and workspace IDs still describe this service. Preserve
19
+ confirmed bindings for downstream skills rather than rediscovering them.
20
+
21
+ **api-engineer**, **api-documentation**, **api-mocking**, **api-testing**, and
22
+ **ci-integration** depend on this skill only for unresolved setup, authentication,
23
+ or bindings. After resolving those prerequisites, return to the requesting
24
+ skill's workflow; local work with confirmed setup can skip bootstrap entirely.
25
+
26
+ If the CLI is missing, use `npm install -g postman-cli` or the applicable
27
+ [platform installer](reference/cli_installation.md). Update an existing CLI
28
+ through its original installation route; installing a second copy can leave
29
+ the shell invoking the old binary. If installation is blocked, report the
30
+ constraint and use **postman-mcp-server** for supported hosted operations.
31
+
32
+ Use `postman <resource> <action> -h` to resolve flags and defaults for the
33
+ installed CLI; cached examples can describe another version. Compare versions
34
+ when diagnosing a missing capability rather than making an update a universal
35
+ prerequisite. Spec lint belongs to `postman spec lint`; the deprecated
36
+ `postman api` surface is not interchangeable.
37
+
38
+ Local file operations need no normal login. `postman init` uses an agent-scoped
39
+ session, so logging in first adds no value to that branch. Authenticate when
40
+ an operation needs existing workspace resources: use
41
+ `postman login --with-api-key "$POSTMAN_API_KEY"` when the key is already in
42
+ the environment, otherwise `postman login`. Keep credential values out of
43
+ logs and committed files; **variables** owns request-secret handling.
44
+
45
+ ## Owning workspace versus dependency
46
+
47
+ Read `localResources` and `workspace.id` in `.postman/resources.yaml`. When
48
+ working with an existing workspace, inspect its identity and elements with
49
+ `workspace list --json` and `workspace get <id> --elements --json`.
50
+ The owning workspace represents this repository's service; another service's
51
+ resource is a dependency. That distinction determines which context can be
52
+ pulled without replacing the repository's binding.
53
+
54
+ | State and intended outcome | Operation |
55
+ | --- | --- |
56
+ | Existing local layout meets the task | Reuse its files and bindings |
57
+ | This service has a workspace; work on it locally | `postman workspace pull <workspace-id>` |
58
+ | Only record this service's Git binding | `postman workspace connect-git <workspace-id> [path]` |
59
+ | Another service's collection, environment, or mock is needed | Use **api-discovery**'s dependency workflow |
60
+ | New project with no existing workspace | `postman init --json`; add `--visibility personal` or `--visibility team` when creating a workspace is intended |
61
+ | Bound workspace is authoritative | `postman workspace pull` |
62
+ | Validated local changes should be published | Preview with `postman workspace diff --push-strategy default`, then `postman workspace push` |
63
+
64
+ Inspect local changes before pulling so an import does not discard work.
65
+ Creating a second workspace does not connect an existing one, and pushing to a
66
+ workspace does not grant teammates access. If sharing requires a visibility
67
+ or permission change, inspect that metadata and resolve the access change
68
+ separately rather than creating a replacement.
69
+
70
+ `workspace diff` is read-only; use the strategy planned for the push.
71
+ The default push creates/updates entities without deleting unmatched ones.
72
+ `--push-strategy force-sync` can delete entities absent locally and belongs
73
+ only to explicitly requested mirroring with the shown deletions approved.
74
+ A request to publish supplies consent for its scoped push; otherwise obtain
75
+ consent after the diff is reviewable. See **ci-integration** for publishing
76
+ reviewed changes after merge.
77
+
78
+ ## Interpret initialization without losing partial success
79
+
80
+ Run init inside the intended repository. It scaffolds Postman files and
81
+ `.postman/resources.yaml`; API implementation and a starter contract are
82
+ separate work, not prerequisites to setup.
83
+
84
+ `--json` avoids interactive prompts. Without `--visibility` it skips workspace
85
+ creation; with it, creation and binding are requested. Read `bindings` and
86
+ `exitCode` from the JSON payload. A binding marked `inferred` is a candidate
87
+ contract, not a confirmed source of truth. Exit 2 means multiple specs need
88
+ selection with `--spec <path>`. Exit 5 means local files were written but
89
+ workspace creation failed; inspect that partial result before retrying.
90
+
91
+ ## Subscription or usage limit
92
+
93
+ A CLI command can fail because the user's subscription does not allow the
94
+ operation or its credits or usage quota are exhausted. There is no fixed
95
+ message for this; recognize wording such as "usage limit exceeded", "usage
96
+ quota has been exceeded", or "reached" or "breached" or "exceeded" a limit for the account,
97
+ team, or a plan-governed operation. Also recognize plan-dependent caps phrased
98
+ as an operation that "does not allow more than" or "requires at least" a stated
99
+ amount. Do not classify a temporary rate limit or a fixed per-resource
100
+ validation cap as a subscription limit. Retrying will not clear a subscription
101
+ limit, so stop retrying and run `postman whoami` to see whose session the CLI
102
+ is using.
103
+
104
+ If it reports a guest session ("Using Postman as a guest", or
105
+ `"status": "guest"` with `--json`), such as the one `postman init` creates
106
+ without a login, tell the user - so do it explicitly and cleanly in a new paragraph,
107
+ that they need to sign up for a Postman account to get more credits and continue work,
108
+ which also keeps the work done as a guest.
109
+ If you run it for them, `postman signup --json` prints a `claimUrl`
110
+ to hand over and then waits until they finish signing up in the browser.
111
+ Ask the user if they want you to initiate signup for them.
112
+
113
+ If the whoami probe reports a signed-in account, then explicitly and cleanly in a new paragraph,
114
+ tell the user that they need to upgrade their plan, and that they can do so at
115
+ https://postman.postman.co/settings/team/billing.
116
+
117
+ ## Verification
118
+
119
+ Report the working CLI, relevant paths, and actual binding or remaining gap.
120
+ For a pull, confirm the intended entities appeared locally; for a push, report
121
+ created/updated entities and conflicts. Installation alone does not establish
122
+ a usable project, and successful sync does not establish teammate access.
123
+
124
+ ## Reporting CLI and skill gaps
125
+
126
+ Concrete reports help fix recurring CLI failures and misleading skill guidance.
127
+ When actual use exposes one, handle the user's task first, then report the gap
128
+ with `postman feedback`. Include a sanitized reproduction and the expected and
129
+ observed behavior; exclude secrets, user data, and proprietary content.
@@ -1,8 +1,9 @@
1
1
  # Postman CLI Installation
2
2
 
3
- A global install, on `PATH`, installed by one of three tools depending on
4
- platform. Whichever one put the binary there is the one to use again when
5
- updating it — mixing tools leaves two `postman` binaries and a `PATH`
3
+ A global install on `PATH`. npm works anywhere Node is available; the curl
4
+ installer covers macOS, Linux, and WSL; and the PowerShell installer covers
5
+ Windows. Whichever route put the binary there is the one to use again when
6
+ updating it — mixing routes leaves two `postman` binaries and a `PATH`
6
7
  question.
7
8
 
8
9
  ## Install
@@ -1,121 +1,62 @@
1
1
  ---
2
2
  name: ci-integration
3
- description: Common CI integrations that can added as independent pass/fail gates. Use when the user asks to "add Postman to CI," "run this collection on every PR," "fail the build on a governance violation," or "push to the postman cloud workspace after merge to main", "add some api related operation in my Github actions".
3
+ description: Use when adding API tests, structural or governance lint, or AI-readiness gates to CI, or publishing reviewed API artifacts to a Postman workspace after merge. Makes contract checks repeatable and separates validation from shared workspace changes. Use for requests such as "run this collection on every PR".
4
4
  ---
5
5
 
6
6
  # CI Integration
7
7
 
8
- ## Overview
9
- These are some common workflows that one can add in their CI pipeline leveraging postman cli.
10
-
11
- ## Run a collection — a gated pipeline step
12
-
13
- `postman collection run <path/id>` exits nonzero on a failed `pm.test`
14
- assertion, which is what makes it a usable gate — see `api-testing` for how
15
- that exit code actually gets set. What's CI-specific: `-r junit,html` (or
16
- `--reporter-*-export`) writes a report your CI provider can surface as
17
- build artifacts or test annotations, instead of leaving the result buried in
18
- a log. `--bail` stops the run early on the first failure when a fast signal
19
- matters more than a full report.
20
-
21
- ## Lint — pick the target that matches the gate you want
22
-
23
- Three verbs look interchangeable and aren't — only two of them apply your
24
- organization's governance rules, and the CLI's own `-h` output is where that
25
- becomes visible (no assumption below goes further than what it printed):
26
-
27
- | Want to check | Command | Applies org governance? |
28
- | --- | --- | --- |
29
- | One spec against your rules | `spec lint <spec> --workspace-id <id> -f error` | Yes, via `--workspace-id` |
30
- | One collection's structure/style | `collection lint <path> -f error` | **No** — this verb takes no `--workspace-id` at all |
31
- | The whole workspace: every entity plus `.postman/resources.yaml` | `workspace lint --workspace-id <id> -f error` | Yes |
32
-
33
- `collection lint` is a schema/style check only — running it and reporting
34
- "governance passed" overstates what it did. If the ask is "does this
35
- collection violate our rules," `workspace lint` is the one that actually
36
- answers it (and covers every collection in the repo in one pass); reach for
37
- bare `collection lint` only when there's no workspace to fetch rules from
38
- yet.
39
-
40
- ## Push to workspace — only after merge
41
-
42
- `postman workspace push -y` is the one command in this skill that changes
43
- shared cloud state, so it belongs behind a merge-to-main trigger, not a PR
44
- trigger. `-y` skips confirmation prompts a non-interactive job can't answer.
45
- Leave `--no-prepare` off — the default prepare step is what assigns real IDs
46
- to entities that are new since the last push; skipping it because a run
47
- felt slow trades a few seconds for a push that silently fails to create
48
- anything new.
49
-
50
- `--push-strategy force-sync` mirrors the whole workspace, deleting any cloud
51
- entity with no local counterpart — genuinely destructive, and not the
52
- default for a reason. See Critical Rules before adding it to a merge job.
53
-
54
- ## AI readiness threshold
55
-
56
- `collection ai-readiness <path> --min-score <n>` and its spec-side
57
- counterpart `spec ai-readiness <path> --min-score <n>` (see `ai-readiness`
58
- skill) are a fourth, separate gate — they score AI-agent consumability, not
59
- test results or governance/structural style. Keep either in its own step:
60
- folding it into the same step as `run` or one of the `lint` verbs above
61
- hides which kind of check actually failed when the job goes red. Pick the
62
- verb that matches what's checked into the repo — `collection ai-readiness`
63
- for a git-synced collection, `spec ai-readiness` for an OpenAPI spec with no
64
- collection generated from it yet.
65
-
66
- ```yaml
67
- - run: postman collection ai-readiness ./postman/collections/My\ API --min-score 70
68
- ```
69
-
70
- ## Critical Rules
71
-
72
- 1. **Never collapse `run`, `lint`, and `ai-readiness` into one step, and
73
- never pass `-x`/`--suppress-exit-code` to a CI run.** One combined exit
74
- code hides which check broke; a suppressed one hides that anything broke
75
- at all.
76
- 2. **Gate `workspace push` to the merge event, never a PR event.** Everything
77
- else in this skill is read-only against the cloud; this is the one
78
- command that writes to it, so a PR-triggered push ships an unmerged
79
- branch's entities to the shared workspace.
80
- 3. **`--push-strategy force-sync` deletes cloud entities absent locally.**
81
- Only add it to a job whose explicit job is mirroring the workspace exactly,
82
- with that intent confirmed — never as the default merge step, where the
83
- default (create/update-only) strategy is the safe choice.
84
- 4. **Authenticate once, non-interactively:**
85
- `postman login --with-api-key "$POSTMAN_API_KEY"`, reading the key from
86
- the CI provider's secret store. Don't reach for `collection run`'s
87
- `--postman-api-key` as the general answer — it's US-region only — and
88
- `spec lint`/`workspace push` don't take it at all.
89
-
90
- ```yaml
91
- # WRONG — key committed in plain text, and scoped to one command anyway
92
- - run: postman collection run api.json --postman-api-key PMAK-abc123...
93
-
94
- # CORRECT — one non-interactive login, key from the provider's secret store
95
- - run: postman login --with-api-key "$POSTMAN_API_KEY"
96
- - run: postman collection run api.json
97
- - run: postman spec lint spec.yaml --workspace-id $WS -f error
98
- ```
99
- 5. **Never `newman run` in place of `postman collection run`.** The CLI is
100
- the supported runner every other skill here assumes; Newman forks the
101
- toolchain and skips whatever reporting/governance depends on the CLI
102
- specifically.
8
+ Versioned collections and specs let a PR carry its API checks beside the code
9
+ change. CI reruns those checks independently of the author's session, while
10
+ publishing after merge makes the reviewed contract available to teammates and
11
+ future work. **api-discovery** helps identify consumers the gate should cover;
12
+ the author's own passing tests do not establish cross-service compatibility.
13
+
14
+ 1. Select checks by the guarantee they establish:
15
+
16
+ | Guarantee | Gate |
17
+ | --- | --- |
18
+ | Saved behavioral assertions pass | `postman collection run <path-or-id>` |
19
+ | A collection's structure/style is valid | `postman collection lint <path> -f error` |
20
+ | A spec meets workspace governance rules | `postman spec lint <spec> --workspace-id <id> -f error` |
21
+ | Workspace entities and bindings pass lint/governance | `postman workspace lint --workspace-id <id> -f error` |
22
+ | Agent consumability meets an agreed threshold | `postman collection ai-readiness <path> --min-score <n>` or the spec equivalent |
23
+
24
+ Collection lint does not apply organization governance. Workspace-aware
25
+ lint evaluates the rules available to that workspace; it does not author
26
+ the policy. Confirm the intended rules are configured before claiming
27
+ compliance. Read command-specific `-h` for installed options.
28
+ 2. Keep gate results distinguishable so a failed build identifies behavior,
29
+ structure, governance, or readiness. Preserve nonzero exits; suppressing
30
+ them with `-x`/`--suppress-exit-code` removes the gate. For collection runs,
31
+ `-r junit,html` produces reviewable reports; `--bail` trades a complete
32
+ failure inventory for an earlier signal. See **api-testing** for assertion
33
+ semantics and **ai-readiness** for score limitations.
34
+ 3. Restore declared dependencies with `postman dependency install` when tests
35
+ use them. Choose the target deliberately: a mock checks behavior under a
36
+ model, while a live run sends real requests and can write data. PR gates
37
+ should use a suitable isolated target and credentials; being a test does
38
+ not make the command read-only.
39
+ 4. Authenticate only jobs that need workspace resources. Use the CI secret
40
+ store to supply `POSTMAN_API_KEY`, then
41
+ `postman login --with-api-key "$POSTMAN_API_KEY"`. A local-only gate need
42
+ not log in. Command-specific API-key flags are not a general replacement
43
+ for login across lint and push operations. Use **bootstrap** for unresolved
44
+ bindings, and **variables** for request credentials.
45
+ 5. Publish only the reviewed branch after its merge checks pass.
46
+ `postman workspace push -y` changes shared context; a PR-triggered push
47
+ would publish an unmerged contract. The normal prepare phase assigns IDs
48
+ to new entities, so `--no-prepare` can leave additions unpublished.
49
+ Inspect the intended diff and binding when configuring this job; `-y`
50
+ supplies noninteractive execution, not authorization for a different scope.
51
+ 6. Use the default create/update strategy unless exact mirroring is the
52
+ explicit requirement. `--push-strategy force-sync` can delete workspace
53
+ entities absent from the checkout, including resources managed elsewhere.
54
+ Follow **bootstrap**'s diff and consent boundary for that branch.
103
55
 
104
56
  ## Verification
105
57
 
106
- State each gate that ran and its individual result — not "CI passed," but
107
- which check ran, what it checked (governance vs. structure per the Lint
108
- table above, or AI-agent consumability for `ai-readiness`), and its exit
109
- code. If `workspace push` ran, confirm it was triggered by the merge event
110
- and not a PR event, state which push strategy was used, and report
111
- `Created`/`Updated` per entity rather than just "push succeeded." Confirm
112
- no secret value appears literally in the committed workflow file.
113
-
114
- ## Reference
115
-
116
- - `api-testing` skill — `collection run`'s exit-code semantics and reporter
117
- flags in full.
118
- - `collection-schema-v3` skill — what `workspace push` is actually pushing.
119
- - `bootstrap` skill — CLI resolution, workspace linking, `.postman/resources.yaml`.
120
- - `ai-readiness` skill — `collection ai-readiness`, `spec ai-readiness`, and
121
- their `--min-score` gate.
58
+ Validate the workflow's event conditions and secret references, then report
59
+ which gates actually ran, their targets and individual results. Distinguish a
60
+ locally checked workflow from an observed CI run. For publication, establish
61
+ the merge trigger, push strategy, created/updated entities, and conflicts;
62
+ a green job alone does not prove the intended artifacts became available.