@postman/postman-plugin 0.2.2 → 0.4.0

package/skills/flows/SKILL.md

@@ -1,212 +1,63 @@
 ---
 name: flows
-description: Runs, deploys, and debugs Postman Flows from the command line — executing a flow file locally, triggering a deployed flow over its webhook, deploying one so it becomes callable, and tracing a failed run to the block that broke. Use when the user names a flow and an action ("run the Checkout flow", "deploy this flow", "why did that flow run fail", "what flows do I have"). Covers `postman flows list`, `run`, `trigger`, `deploy`, `update`, `list-runs`, and `get-run`.
+description: Use when running, deploying, or debugging an existing Postman Flow. Distinguishes local graph execution from a deployed webhook, reuses named input scenarios, and follows a run to the failing block rather than treating an HTTP response as whole-flow success. Use for requests such as "why did this flow fail".
 ---
 
 # Postman Flows
 
-## Overview
-
-Listing flows, running them, deploying them so they become callable, and
-tracing a failed run to the block that caused it — all through
-`postman flows`.
-
-## Core knowledge
-
-A flow is a graph of blocks, not a script. That single fact drives the rest of
-this skill: a flow has two independent execution paths, and its HTTP response
-describes one block rather than the whole graph, so debugging takes a
-different command than running.
-
-### Local file vs deployed artifact
-
-`run` and `trigger` are not two ways to execute one flow. Postman Flows has
-two Native Git modes, and they are isolated from each other:
-
-- **Cloud View** (the default) syncs flows to Postman Cloud, which is what
-  makes them shareable and **deployable** — so Cloud View is the only side
-  `deploy`, `trigger`, `update`, `list-runs` and `get-run` ever address.
-- **Local View** stores flows as JSON in a local Git repo, updated as they are
-  edited. Those flows **cannot be shared or deployed**, have no snapshots, and
-  are isolated from the flows in Cloud View.
-
-| | `flows run <path>` | `flows trigger <flowId>` |
-| --- | --- | --- |
-| Executes | a flow JSON file on this machine | the cloud-deployed flow, via its webhook |
-| Returns | status, output, test results, exit code | Run ID + HTTP status + response body |
-| Observability | own stdout, `--output`, `--reporters` | `get-run`, per block |
-| Environment file | `-e/--environment` | not supported |
-
-`run` exits nonzero on failure, which is what lets a CI job gate on it.
-`trigger` goes through the real webhook URL, so it exercises the deployed path
-end-to-end — auth and trigger configuration included — and registers a cloud
-run that `get-run` can explain block by block.
-
-`postman init` scaffolds `postman/flows/`, and Postman's `flows run` examples
-use that path. Note what puts files there: the Git-connected Flows experience
-is **desktop-app only**, so `postman/flows/*.json` is written by the desktop
-app's Local View, not by the CLI — `workspace push`/`pull` carry no flows
-handling whatever else they sync. Don't tell a user to `workspace pull` to
-obtain a flow file.
-
-### What deploying buys, and what it requires
-
-Deploying puts the flow in Postman's cloud and attaches an HTTP trigger, which
-is what makes it reachable by schedules, webhooks, third-party apps, and other
-APIs — the flow stops being something a human opens and becomes callable
-infrastructure.
-
-Three preconditions sit outside the CLI, so no flag or retry satisfies them:
-the flow must be in Cloud View, its Start block must be configured with an API
-request trigger, and its canvas must have a Response block. Check these before
-re-running a failed deploy with different arguments.
-
-`--path` is a suffix appended to a generated base URL, not a full URL.
-
-### Inputs: `-i` versus a scenario
-
-A scenario is a named input set stored **in the flow definition**, generated
-when someone adds an input to the Start block. Because it travels with the
-flow, `-s "Staging"` is reproducible across invocations and across people,
-where `-i key=value` is per-invocation. Start-block inputs can be declared
-secret, which is what `--show-secrets` unmasks in dry-run output.
-
-Precedence: `-s` supplies payload, headers, and query; `--headers` and
-`--query` override it; `-i`/`-f` override its values.
-
-### Identifiers
-
-`flows list` is the only way to turn a flow name into an id —
-`.postman/resources.yaml` maps collections to cloud ids but has no flows
-section, so there is nothing local to read. Both `list` and `list-runs`
-**require** `-w/--workspace`; take that id from `workspace.id` in
-`.postman/resources.yaml`, which `bootstrap` records.
-
-Run IDs have no single documented shape (`session-abc123` and `main/1a123ab1`
-both appear in Postman's own material). Use whatever `trigger` or `list-runs`
-printed, verbatim, and apply the same rule to flow ids.
-
-### Plan and permission gating
-
-`flows run` is documented as Enterprise-only, and the cloud subcommands need
-`postman login`. `Access denied. Please check your permissions for the
-specified resource.` on *every* workspace is a credential-scope or plan
-signal, not a wrong-workspace signal — and never means the workspace has no
-flows.
-
-## Deploying: propose, confirm, then verify
-
-Deploy is the one multi-phase workflow here, because it is mutating and
-because its result is only half-useful without the follow-up check.
-
-1. **Resolve the id.** `flows list --workspace <id> --filter "Checkout"`. On
-   multiple matches, show name + id + last-updated and let the user pick.
-2. **Propose the path.** Derive it from the flow name — "Checkout" →
-   `/checkout` — so the user is confirming a concrete value rather than
-   answering an open question. Raise `--auth` here if the trigger will be
-   reachable by anyone who learns the URL.
-3. **Confirm, then run** `flows deploy <flowId> --path /checkout`.
-4. **Report the Trigger URL and whether the trigger is enabled.** A deploy can
-   land with the trigger off, which looks identical to a broken deploy at call
-   time. If it is off, offer `flows update <flowId> --trigger on`.
-
-When the deploy existed only so the flow could be run, trigger it in the same
-turn and report the Run ID — deploy-then-trigger is one job.
-
-## Running and triggering
-
-Show the command before running it, and map the request onto flags: inputs to
-`-i`, a payload file to `-f`, query to `-q`, headers to `--headers`, a named
-scenario to `-s`.
-
-```bash
-postman flows run postman/flows/checkout.json -i amount=4200
-postman flows trigger <flowId> -i amount=4200
-```
-
-`run` is documented as Enterprise-only, so check the plan before building a
-workflow on the local path. Where the flow is already in Cloud View, `trigger`
-covers the gap; a Local View flow has no such fallback, since it cannot be
-deployed.
-
-`-n/--dry-run` on `trigger` prints the resolved URL and payload without
-sending — worth reaching for when a flow writes to real systems, since a
-trigger is not a read-only probe. For CI, `--output json` and `--reporters
-html` persist results, and `--workspace` is required if the flow contains
-connector blocks (it fails at the block, not at startup).
-
-Report the Run ID on every trigger, including successes; it is the only handle
-on the run afterwards.
-
-Two failures are recoverable rather than terminal, and both recover through a
-confirmed mutation. A 404 hinting `To deploy it, run: postman flows deploy`
-means the flow exists but was never deployed — offer the deploy above, then
-re-trigger. A disabled-trigger error means it is deployed but not accepting
-calls — offer `flows update <flowId> --trigger on`, then trigger.
-
-## Debugging a run
-
-A trigger's response body is the Response block's output. A flow can answer
-200 with a failed block upstream, and a 500 says nothing about which block
-produced it — so read the run, not the response.
-
-```bash
-postman flows list-runs --workspace <id> --flow <flowId> --range 3d
-postman flows get-run --run-id <runId> --logs
-```
-
-`list-runs` recovers a Run ID nobody wrote down; its `--range` defaults to
-`1h`, so widen it before concluding a run is missing. Start `get-run` without
-`--logs` and add them when the summary does not explain the failure;
-`--filter` narrows to a block-id prefix.
-
-Report the failing block, the reason, and the run status:
-
-```
-Run session-abc123 — failed
-  Failing block: "HTTP Request (Get Orders)"
-  Reason:        downstream returned 504 after 10s timeout
-  Status:        error
-```
-
-## Critical Rules
-
-1. **Resolve ids, never infer them.** A name is not an id, and no id format is
-   documented well enough to validate against. Ambiguous name → present
-   candidates and ask.
-2. **`deploy` and `update` need explicit confirmation.** They change what the
-   flow does for every caller: a deploy exposes a trigger path, `--trigger
-   on|off` starts or stops accepting calls, and `--auth off` removes
-   authentication from a live trigger.
-3. **Report the failing block, not the log.** `--logs` output is input to your
-   analysis; the user needs the block, the reason, and the status.
-4. **Surface CLI errors verbatim** and read them literally. "Flow file not
-   found", a required-option error, and "Access denied" have three different
-   fixes, and only the last is about permissions.
-5. **A missing or unauthenticated CLI is `bootstrap`'s job** — route there
-   rather than improvising an install or a second login.
-
-## Anti-patterns
-
-1. **Don't substitute `run` for `trigger` when a flow isn't deployed.** A
-   green local run says nothing about the deployed path a caller hits, and a
-   Local View flow cannot be deployed at all.
-2. **Don't hunt for a different workspace id when access is denied across
-   every workspace you try.** A blanket denial points at the credential's
-   scope or the plan, not at the id.
-3. **Don't pass `-x/--suppress-exit-code` in CI.** It makes a failed flow
-   report success to the pipeline, which removes the only thing gating it.
-4. **Don't put reusable inputs on the command line.** A payload that matters
-   more than once belongs in a Start-block scenario, where it travels with the
-   flow.
-
-## Reference
-
-- [Flows CLI flags](reference/flow_cli_flags.md) — full flag tables per
-  subcommand, the BETA dataset-iteration flags, and the short-flag collisions
-  between subcommands. Read before composing a command with flags not shown
-  above.
-- `bootstrap` skill — CLI install, login, and the workspace id these commands
-  require.
-- `api-discovery` skill — `postman search flows` finds a flow by text across
-  Postman, a different dataset from `flows list`'s workspace enumeration.
+A Flow saves an API workflow as a graph of blocks. Named inputs make runs
+repeatable, deployment makes the workflow callable by other systems, and
+block-level run evidence shows where it failed. These benefits come from
+different execution paths; choosing the wrong path can produce a passing
+result that says nothing about the caller's actual workflow.
+
+1. Choose the artifact the user means. `postman flows run <path>` executes a
+   local JSON file; `postman flows trigger <flow-id>` calls the deployed
+   webhook, including trigger auth and configuration. Local View and Cloud
+   View artifacts are isolated: local files cannot be assumed deployable,
+   and `workspace pull` does not download them. The desktop app's Git-connected
+   Local View produces those files. Check current local-run entitlement before
+   building CI around it; a deployed flow is not a substitute for a different
+   local artifact.
+2. Resolve hosted IDs through `flows list --workspace <id>`; there is no
+   local flow mapping in `.postman/resources.yaml`. Reuse its `workspace.id`
+   when applicable or use **api-discovery** for cross-workspace search.
+   Resolve ambiguous names before mutating a flow. Use returned flow/run IDs
+   verbatim; their spelling is not a reliable validation rule.
+3. Reuse a Start-block scenario when the same payload should travel with the
+   flow. `-s` supplies payload, headers, and query; explicit headers/query and
+   `-i`/`-f` override those values. One-off inputs belong on the invocation.
+   For deployed flows with side effects, `trigger --dry-run` lets you inspect
+   the resolved call first; keep secrets masked.
+4. Deploy when the workflow needs a callable URL. The hosted flow needs a
+   Start block configured for an API request trigger and a Response block;
+   changing CLI flags cannot repair missing canvas configuration. Resolve
+   the path suffix and intended authentication before deploying. Deploy/auth
+   changes affect other callers; a scoped user request authorizes that change,
+   while unrequested public exposure or auth removal needs consent.
+5. Inspect the deployed URL and whether its trigger is enabled. A deployed
+   but disabled flow is not ready to receive calls; `flows update <id>
+   --trigger on` enables it when intended. If deployment is part of a requested
+   run, continue through triggering and capture the Run ID. A request only to
+   deploy does not authorize executing unrelated downstream writes.
+6. Diagnose from run evidence. A trigger response is the Response block's
+   output: HTTP 200 can coexist with another failed block. Use
+   `flows get-run --run-id <id>` and add `--logs` or a block filter when the
+   summary does not explain it. `flows list-runs --workspace <id> --flow <id>`
+   recovers missing run IDs; widen its time range before concluding absence.
+7. In CI, preserve the local run's failure exit code and persist its result
+   and reports. Connector blocks need `--workspace` even for a local file;
+   otherwise failure occurs inside the graph. An access denial across several
+   workspaces points toward credentials or entitlement, not an empty flow list.
+   Use **bootstrap** for unresolved CLI/authentication setup.
+
+Read [command options](reference/flow_cli_flags.md) for inputs, reporters,
+dataset iteration, and flag collisions; check installed subcommand `-h` before
+carrying an option between commands.
+
+## Verification
+
+Report which artifact and path executed, its inputs/scenario without secrets,
+and the actual result. For a trigger, retain the Run ID; for a failure, name
+the failing block and cause. For a deployment, report URL, auth, and enabled
+state separately from any execution result.

package/skills/flows/reference/flow_cli_flags.md

@@ -57,8 +57,9 @@ takes `on|off`.
 with `Invalid command parameters: trigger: At least one option is required:
 --trigger or --auth`.
 
-Both are mutating and confirmation-gated. `--auth off` strips authentication
-from a live trigger — never run it as a convenience.
+Both change the live trigger for other callers. Apply an already authorized
+change within its scope; obtain consent before an unrequested access change.
+`--auth off` removes authentication, so it is not a remedy for a failed login.
 
 ## `flows run <path>`
 

package/skills/performance-testing/SKILL.md

@@ -1,71 +1,55 @@
 ---
 name: performance-testing
-description: Load-tests a collection with concurrent virtual users, a chosen load profile, and pass/fail thresholds on latency or error rate — run locally or on Postman's cloud runners. Use when the user asks to "load test this API," "run a performance test," "check how this holds up under load," or "benchmark this collection." Covers `postman performance run`. This generates real traffic against a real target — confirm the target and scale before running, the same way any action with effects outside this session gets confirmed.
+description: Use when load-testing or benchmarking an API with concurrent virtual users and latency or error thresholds. Reuses a collection to probe a chosen failure mode and distinguishes target limits from load-generator limits. Use for requests such as "load test this API".
 ---
 
 # Performance Testing
 
-## Overview
-
-`performance run <collectionId>` is not `collection run` with more
-iterations — it's a dedicated load-test mode: many virtual users hitting the
-collection concurrently for a set duration, shaped by a load profile, scored
-against thresholds you define, on infrastructure you choose. The collection
-under test is authored the normal way — see the `collection-schema-v3` skill
-if it needs edits before the load test is meaningful (e.g. an assertion
-that would fail every VU's request identically).
-
-## Core knowledge
-
-- **Load profile is what you're actually testing.** `fixed` holds steady
-  concurrency (does this hold up at N users, sustained); `ramp-up` increases
-  gradually (where does it start to degrade); `spike` bursts suddenly (does
-  a sudden surge break it); `peak` sustains near-maximum load (does it
-  survive staying there). Pick based on the failure mode being probed, not
-  by default.
-- **`--runner` chooses where load originates.** `local` runs from the
-  current machine/CI runner — bounded by its own resources, fine for
-  internal or low-scale targets. `postman-cloud` runs from Postman's
-  infrastructure — needed for realistic external-scale load, or once local
-  resources would cap the achievable VU count. `postman-cloud-static-ip`
-  is the same, from a static-IP range — needed when the target allowlists
-  by IP.
-- **`--pass-if "less_than(p95, 500)"` turns a load test into a gate.**
-  Metrics: `avg`, `p90`, `p95`, `p99`, `error_rate`, `rps`. Checked after the
-  run completes, not enforced live — a bad configuration still generates its
-  full load before the gate fails.
-- **`--use-mock` points the test at a mock instead of a real backend** — for
-  load-testing collection/script logic itself, or to baseline mock-only
-  latency and isolate app/network slowness from what the mock adds.
-- **`--setup-collection`/`--teardown-collection`** (cloud runner only) run
-  once before/after the whole test — for provisioning or cleanup, not
-  per-iteration setup.
-- **`--dataset-id`/`--dataset-view-id`** drive iteration data from a Postman
-  Dataset instead of a flat `--data-file`; `--dataset-distribution` controls
-  whether rows are spread round-robin, fixed, or randomly across VUs.
-
-## Critical Rules
-
-1. **Running this against a real, non-mock backend generates real load with
-   real consequences — confirm the target, VU count, and duration with the
-   user before running,** the same way any action with effects outside this
-   session gets confirmed. Default to a low `--vu-count` and short
-   `--duration` for a first run against anything live, or point it at a mock
-   (`--use-mock`) when the goal is testing the collection, not the backend.
-2. **A `--pass-if` gate doesn't stop the load early.** The full VU count and
-   duration run regardless of whether the threshold will ultimately pass —
-   plan for that cost, don't assume a failing gate means less traffic was
-   sent.
-3. **Cloud runners come from Postman's IP ranges.** Before assuming a
-   `postman-cloud` run will reach a target, check whether it's IP-allowlisted
-   — use `postman-cloud-static-ip` if so, rather than discovering the
-   mismatch as a wall of connection failures.
+A collection supplies realistic request sequences; `postman performance run`
+adds concurrency and a load profile. This makes performance claims repeatable,
+but only for the workload, data, and network path actually exercised.
+Collections run directly: converting with `postman-to-k6` is not required.
+
+1. Choose the failure mode before the profile: `fixed` tests sustained
+   concurrency, `ramp-up` explores degradation as load grows, `spike` tests
+   sudden surges, and `peak` tests staying near maximum load. Reuse the
+   collection's auth and assertions, and check that its operations and data
+   represent the workload rather than repeating one unusually cheap request.
+2. Establish the target, VU count, duration, and effects of write requests
+   before sending load. Existing user authorization for that scope is enough;
+   resolve missing limits before stressing a shared or production service.
+   Thresholds are evaluated after the run, so a failing gate will not stop
+   traffic early. A small initial run can expose wiring failures before a
+   larger authorized test.
+3. Choose the runner by reachability and capacity. `local` uses this machine
+   or CI runner; its CPU or network can become the bottleneck. `postman-cloud`
+   moves generation to Postman's infrastructure, while
+   `postman-cloud-static-ip` supports targets with IP allowlists. Verify
+   reachability before interpreting connection failures as service capacity.
+4. Set thresholds that represent the user's objective, such as
+   `--pass-if "less_than(p95, 500)"`. Supported metrics include `avg`, `p90`,
+   `p95`, `p99`, `error_rate`, and `rps`; latency alone can look good when
+   requests fail quickly. Use `postman performance run -h` for current syntax,
+   units, and runner-specific options.
+5. Isolate test data where concurrent writes would collide. **datasets**
+   supports controlled row distribution across VUs; setup/teardown collections
+   on hosted runners execute once around the test, not once per iteration.
+   `--use-mock` can baseline collection/script overhead, but its numbers
+   cannot establish the real backend's capacity.
+
+## Importing from JMeter
+
+Have a JMeter `.jmx` instead of a collection? Don't rebuild it by hand — run the
+bundled importer (`references/jmeter-import/scripts/jmx_to_postman.py <plan>.jmx
+-o <out>`; see `references/jmeter-import/README.md`), then treat its output as the
+collection above. Read the generated report: it marks what mapped exactly, what
+was approximated, and which JMeter features have no equivalent here — think-time
+timers, concurrent thread groups, and non-HTTP (JDBC/FTP/LDAP/Java) samplers are
+reported, never faked.
 
 ## Verification
 
-State the actual metrics the run produced (p95, error rate, rps — whatever
-the `--pass-if` checked, plus the ones it didn't) and whether the gate
-passed, not just that the run completed. State which runner actually
-executed it (`local`/`postman-cloud`/`postman-cloud-static-ip`) — that
-determines whether the numbers reflect the target's real-world reachability
-or only local-network conditions.
+Report the workload, runner, achieved traffic, latency and error metrics,
+and threshold verdict. Identify generator limits or target errors that prevent
+attributing the result to API capacity. See **api-testing** for functional
+assertions and **ci-integration** when the measured threshold becomes a gate.

package/skills/performance-testing/references/jmeter-import/README.md

@@ -0,0 +1,113 @@
+
+# Importing a JMeter `.jmx` into Postman
+
+> Reference for the `performance-testing` skill. Run the importer, review the report, then the result is an ordinary performance run.
+
+Turn a JMeter test plan into three artifacts:
+
+1. **Postman Collection v2.1** — requests, flow, headers, auth, variables, extractors, assertions.
+2. **Performance config** — VU count, duration, load profile, data file, `--pass-if`, and the exact `postman performance run` command.
+3. **Import report** — what imported exactly, what was approximated, what needs manual work, what is unsupported.
+
+The parsing and building are **deterministic Python** (`scripts/`). You (the model) only do the judgment calls the scripts flag: translating Groovy/BeanShell scripts to JavaScript and resolving extractors Python can't (XPath/CSS/complex JSONPath).
+
+## When NOT to guess
+
+Postman performance runs do not support everything JMeter does. The scripts already encode the gaps (see `postman-perf-capabilities.md`). Never invent a Postman feature to cover a JMeter one. If something can't import, it goes in the report's "Needs manual work" or "Not supported" section — that is a correct outcome, not a failure.
+
+## Correctness rules the importer reproduces (do not regress)
+
+These are JMeter semantics that are easy to get subtly wrong. They're covered by `tests/score.py`:
+
+- **Implicit HTTP success** — JMeter fails a sample on HTTP ≥ 400 even with no assertion. Each request gets a default `pm.test` asserting the code is 200–399, **unless** the plan already checks the status code or sets *assume_success* (Ignore Status).
+- **Port 0 / -1** → "use protocol default" → omitted from the URL.
+- **Full-URL path** — if `HTTPSampler.path` is itself an absolute URL, it's used verbatim; domain/port are ignored.
+- **HEAD / TRACE arguments** — JMeter does not send separate parameters as a query for these; they're dropped (reported).
+- **Duplicate headers** — in-scope header managers merge; the nearer/last value per name wins and the collapse is reported.
+- **Sampler-scoped config** — a Header Manager / Auth Manager / HTTP Defaults inside a request's own subtree applies to that request.
+- **Security** — the parser refuses DTD/ENTITY (XXE) and caps input at 25 MiB.
+
+## Workflow
+
+### 1. Run the importer
+
+```bash
+python3 scripts/jmx_to_postman.py INPUT.jmx -o OUTDIR --json-report
+# CI gate: add --fail-on-blockers to exit non-zero when any item needs manual work
+```
+
+Produces in `OUTDIR`:
+- `<name>.postman_collection.json` — the collection (import-ready)
+- `<name>.perf.md` / `<name>.perf.json` — performance config + CLI command
+- `<name>.report.md` — the import report
+- `<name>.ir.json` — machine-readable intermediate model + `manual_tasks` + `warnings` (from `--json-report`)
+
+Python 3.8+ only, standard library — no pip installs.
+
+### 2. Resolve the manual tasks
+
+Open `<name>.ir.json` and read `manual_tasks`. Each has `request`, `kind`, `detail`. Handle by kind:
+
+- **`script`** — a JSR223/BeanShell pre/post-processor was auto-translated to JS and wrapped in an IIFE. Open that request's `event` script in the collection, read the `// REVIEW` block, and correct the translation. Use `script-translation.md` for the mapping. Common fixes: `prev`/`ctx`/`sampler` accessors, `.each{}` loops, `import`/`new` statements.
+- **`script_sampler`** — a standalone JSR223/BeanShell *sampler* (no HTTP). The stub is a GET to an empty URL carrying the translated script. Decide with the user: delete it, fold its logic into an adjacent request's pre/post script, or replace with a real request.
+- **`xpath` / `css`** — the Postman sandbox has no built-in XPath/CSS selector engine. Rewrite the extractor against the JSON body if the response is JSON, or use `xml2js`/`cheerio` via `require(...)` in the script (confirm availability), or drop it with a note.
+- **`jsonpath` too complex** — the path used wildcards/filters/recursion. Rewrite it as explicit property access in the request's test script.
+
+Edit the collection JSON in place. Keep the `// REVIEW` comments until the logic is confirmed.
+
+### 3. Validate the output
+
+Confirm the collection is valid v2.1 JSON and — the part that matters — that **every generated `event` script parses as JavaScript** (`node --check` each `exec`, or equivalent). A syntax error in a generated script is invisible in the file and only surfaces when the perf run executes that request, mid-load. Fix any bad script before handing off.
+
+### 4. Finalise the report
+
+`<name>.report.md` already has the four sections. Add anything you changed while resolving manual tasks so the report matches the collection you're handing off.
+
+### 5. Hand off the perf config
+
+`<name>.perf.md`'s command has a `<COLLECTION_UID>` placeholder — the collection must be uploaded to a workspace first to get a real UID. The `--pass-if` value is a suggestion unless the JMeter plan had a Duration Assertion, so surface the VU/duration/profile/pass-if choices for the user to adjust.
+
+### 6. (optional) Publish to a Postman workspace
+
+Only on explicit user consent — and **never make the user paste a workspace ID**. Pick the destination like this:
+
+- **If the current folder is already a connected workspace** (the usual headless case), use it — `postman workspace push` targets the workspace bound to this directory, no ID. Just tell the user which one.
+- **If the user named a workspace** (by name), resolve it with `postman workspace list --json` and match.
+- **Otherwise present a choice, don't demand an ID.** Run `postman workspace list --json`, show the **names**, and ask the user to pick one *or* create a new one:
+  - **pick existing** → connect it once with `postman workspace pull <id>` (ID taken from the list), then push.
+  - **create new** → the CLI has no `create`; make it via MCP `createWorkspace` (or the Postman app), then `pull` and push.
+- **Get the imported collection into the bound workspace before pushing.** The importer emits a standalone v2.1 `*.postman_collection.json`; a pulled workspace is a git-native v3 tree. After `pull`, bring the file in with `postman collection migrate <file>.postman_collection.json` into the workspace's collections directory (check `postman collection migrate -h`), then `postman workspace push`. Pushing a folder that has no collection in its tree uploads nothing.
+- **Push through the CLI, not MCP.** MCP `createCollection` drops each request's URL (requests land blank); use MCP only if the `postman` binary genuinely can't be installed, and repair URLs afterward.
+- Interrogate `postman <cmd> -h` for exact flags — the help is authoritative, this file is not.
+
+Smoke-test with `postman collection run` — the **same runtime that executes the perf test**, not a generic client — so the request is proven under the variable/auth resolution it will actually run under. Then wire the returned UID into the perf command.
+
+## Fallback: when you cannot run Python
+
+If this environment has no code execution, do **not** refuse — import by hand, following the exact same rules the script encodes. Output must be identical in shape (collection v2.1 + perf config + report).
+
+1. **Read first:** `mapping-table.md` (what maps to what), `postman-perf-capabilities.md` (the hard limits), `script-translation.md` (Groovy/BeanShell → JS). These ARE the algorithm.
+2. **Parse the JMX by the one structural rule:** every element is followed by a sibling `<hashTree>` holding its children. Walk those pairs. A config element (Header Manager, Auth, HTTP Defaults, extractor, assertion) applies to every sampler in its subtree; the same element inside a sampler's own hashTree applies only to that sampler.
+3. **Apply the non-negotiable rules** (same as the script). Use the **exact JS templates in `script-translation.md`** for extractors and assertions so a hand import matches the script output byte-for-byte:
+   - `${var}` → `{{var}}`; `${__UUID}`→`{{$guid}}`, `${__time}`→`{{$timestamp}}`, `${__Random(..)}`→`{{$randomInt}}`, `${__RandomString(..)}`→`{{$randomAlphaNumeric}}`.
+   - Every request gets a default `pm.test` asserting HTTP 200–399 — **unless** that request has a Response Assertion whose `test_field` is `response_code` **or** `response_message`, **or** any assertion with `assume_success=true`. An assertion on the **body** (`response_data`) does NOT suppress it.
+   - Port 0/-1 → omit. Full-URL path (`path` starts with `http://`/`https://`) → use verbatim, ignore domain/port. HEAD/TRACE args → drop + note. Keep inherited headers as-is even on a GET (JMeter still sends them); don't prune.
+   - Extractors → `pm.collectionVariables.set` in the test script; assertions → `pm.test`. (Templates in the reference.)
+   - Thread group → VUs = `num_threads`; **duration (minutes) = round(`ThreadGroup.duration` seconds ÷ 60), minimum 1**; profile = `ramp-up` if `ramp_time`>0 or a plugin/concurrency group, else `fixed`. Loop counts → duration (there is no iteration count). One `--pass-if` only; a Duration Assertion → `less_than(p95, <ms>)`, else default `less_than(error_rate, 5)`.
+   - Timers / concurrent thread groups / non-HTTP samplers → **not supported**; list them in the report, never fake them.
+4. **Produce the same files** a run would: the collection JSON, the perf `.md`, and the report with the four sections (imported / approximated / needs manual work / not supported).
+5. **State clearly** in your answer that this was a by-hand import (no Python), so it's best-effort and not the deterministic, tested path.
+
+This fallback is lower-reliability than running the script — flag anything you were unsure about.
+
+## Mapping
+
+The full per-element mapping (fidelity + whether the script or the model owns it) is `mapping-table.md` — it's the algorithm for the fallback and the regression contract, so it's kept there, not restated here.
+
+## Scope limits (hard facts, verified against the CLI/engine code)
+
+- Performance runs execute **one collection repeated across VUs**. Multiple thread groups cannot run concurrently in a single run.
+- Runs are **time-based**, not iteration-based. JMeter loop counts become a duration.
+- `--pass-if` is a **single, non-repeatable** condition. Extra assertions stay as `pm.test` in scripts.
+- **No native think time.** JMeter timers are approximated — group-scope ones as `--delay-request`, per-request ones as a pre-request pause — not reproduced exactly. Always reported.
+- Only **HTTP(S)** samplers import. JDBC/FTP/LDAP/Java/TCP/Debug/Dummy samplers are reported as skipped.

package/skills/performance-testing/references/jmeter-import/import-report.md

@@ -0,0 +1,52 @@
+# Import Report — <TEST PLAN NAME>
+
+> Generated by `jmx_to_postman.py`; sections below are auto-filled. After resolving
+> manual tasks, update the "Needs manual work" list and the summary counts.
+
+## Summary
+
+- Thread groups: <N>
+- HTTP requests imported: <N>
+- Folders: <N>
+- Script-only samplers (stubs): <N>
+- Collection variables: <N>
+- Data files: <N>
+- Items needing manual work: <N>
+
+## Imported exactly
+
+- HTTP requests (method, URL, headers, query/body params)
+- Response assertions → `pm.test` (status / body contains / equals / matches)
+- Regex & Boundary extractors → `pm.collectionVariables.set`
+- Simple JSONPath extractors (dot/index paths) → property access
+- Basic/Digest auth, User Defined Variables → collection variables
+- `${var}` → `{{var}}` interpolation
+
+## Approximated
+
+- **Thread group load** → VU count + duration + one of 4 load profiles.
+- **Loop counts / iterations** → duration in minutes.
+- <element-specific warnings…>
+
+## Needs manual work
+
+- **[kind]** `request`: <what and why>
+
+## Not supported by Postman performance runs (dropped)
+
+- **Think time / timers** — no equivalent.
+- **Multiple concurrent thread groups** — a run is one collection repeated across VUs.
+- **Flow control** (If/While) — requests flattened; restore with `pm.execution.setNextRequest`/`skipRequest`.
+- **Cookie/Cache/DNS managers** — cookies handled automatically per VU.
+- **Non-HTTP samplers** (JDBC/FTP/LDAP/Java/TCP/Debug) — HTTP only.
+
+## Performance run
+
+```bash
+postman performance run <COLLECTION_UID> \
+    --vu-count <N> --duration <MIN> --load-profile <fixed|ramp-up|spike|peak> \
+    [--data-file <file>] [--pass-if "<fn>(<metric>, <value>)"]
+```
+
+Upload the collection to a workspace first to get its UID. `--pass-if` is a suggested
+default unless the JMeter plan had a Duration Assertion.