@postman/postman-plugin 0.4.0 → 0.4.1

package/README.md

@@ -28,6 +28,14 @@ One command configures **Antigravity, Claude Code, Codex, GitHub Copilot CLI, Cu
 Factory Droid, Kimi Code, OpenCode and Pi**. Run it again to update, `status` to see what's installed,
 and `remove` to uninstall; `--agent <id>` limits any of them to one agent.
 
+For Codex, installation also approves Postman's session-start hook, which adds
+instructions for using Postman's API skills. There is no separate hook prompt
+or dump of its instructions. Already trusted hooks are left alone. If Codex's
+hook API is unavailable, installation continues with a note to approve the hook
+inside Codex. Run the installer and Codex with the same `HOME` and `CODEX_HOME`;
+hook approval applies to that profile. If Codex later refreshes the plugin from
+`main` and its contents change, run the installer again to approve the update.
+
 You can also use the following commands to install individually:
 
 ### Antigravity
@@ -58,10 +66,15 @@ does nothing where the marketplace is already registered.
 [View Postman on ChatGPT Plugins](https://chatgpt.com/plugins/postman?open_in_app)
 
 ```bash
-codex plugin marketplace add postmanlabs/postman-plugin
+codex plugin marketplace add postmanlabs/postman-plugin --ref main
+codex plugin marketplace upgrade postman
 codex plugin add postman@postman
 ```
 
+These commands track `main`; review the session-start hook in Codex after a
+manual install. The npx installer also approves the hook after each install or
+update.
+
 ### Cursor
 
 [View Postman on the Cursor Marketplace](https://cursor.com/marketplace/postman)

package/dist/hosts/codex-hooks.js

@@ -0,0 +1,68 @@
+import path from 'node:path';
+export const POSTMAN_HOOK_KEY = 'postman@postman:hooks/codex-hooks.json:session_start:0:0';
+async function postmanHook(rpc, cwd) {
+    const result = await rpc.request('hooks/list', { cwds: [cwd] });
+    if (!Array.isArray(result?.data) || result.data.some((entry) => !Array.isArray(entry.hooks) || entry.errors?.length)) {
+        throw new Error('hooks/list returned no usable hook listing');
+    }
+    const hooks = result.data.flatMap((entry) => entry.hooks).filter((hook) => hook.key === POSTMAN_HOOK_KEY);
+    if (hooks.length > 1) {
+        throw new Error('hooks/list returned more than one Postman session-start hook');
+    }
+    return hooks[0];
+}
+const trustEdit = (hash) => ({
+    edits: [{ keyPath: 'hooks.state', value: { [POSTMAN_HOOK_KEY]: { trusted_hash: hash } }, mergeStrategy: 'upsert' }],
+    reloadUserConfig: true
+});
+/** Approves only Postman's current hook after installation; unsupported APIs never fail the install. */
+export async function approvePostmanHook(system) {
+    const note = (message) => system.log(`  note: ${message}`);
+    let writeAttempted = false;
+    if (system.dryRun) {
+        note('Would inspect and approve Postman\'s current session-start hook after installation through codex app-server:');
+        system.log(`  config/batchWrite ${JSON.stringify(trustEdit('<currentHash from hooks/list>'))}`);
+        return;
+    }
+    try {
+        await system.withJsonRpc('codex', ['app-server'], async (rpc) => {
+            // Version of this small protocol client, independent of the plugin's release.
+            await rpc.request('initialize', { clientInfo: { name: 'postman-plugin-installer', version: '1' } });
+            rpc.notify('initialized');
+            const hook = await postmanHook(rpc, system.cwd);
+            if (!hook) {
+                note('Postman\'s session-start hook was not found; hook approval skipped.');
+                return;
+            }
+            if (hook.trustStatus === 'trusted') {
+                note('Postman\'s Codex session-start hook is already trusted.');
+                return;
+            }
+            if (!['untrusted', 'modified'].includes(hook.trustStatus) || !hook.currentHash || typeof hook.currentHash !== 'string') {
+                throw new Error('Postman\'s hook has an unsupported trust status or hash');
+            }
+            // Confirm the installed instructions are present before approving their hook.
+            const mandateFile = path.resolve(path.dirname(hook.sourcePath), 'session-start-context.md'), mandate = await system.readFile(mandateFile);
+            if (!mandate?.trim()) {
+                throw new Error('could not read the installed hooks/session-start-context.md');
+            }
+            // Startup can refresh marketplaces. A changed hash needs another check,
+            // rather than approving a different version from the one inspected above.
+            const current = await postmanHook(rpc, system.cwd);
+            if (!current || current.currentHash !== hook.currentHash || !['untrusted', 'modified'].includes(current.trustStatus)) {
+                note('Postman\'s hook changed while checking it; approval skipped. Re-run to approve the current version.');
+                return;
+            }
+            writeAttempted = true;
+            await rpc.request('config/batchWrite', trustEdit(hook.currentHash));
+            const after = await postmanHook(rpc, system.cwd);
+            note(after?.trustStatus === 'trusted' && after.currentHash === hook.currentHash ?
+                'Approved Postman\'s Codex session-start hook.' :
+                'Codex accepted the approval write, but the hook is not confirmed trusted. Review it in Codex.');
+        });
+    }
+    catch (error) {
+        // Older Codex releases may lack app-server or hooks/list. Installation still succeeds.
+        note(`Hook approval ${writeAttempted ? 'could not be confirmed' : 'skipped'}: ${error instanceof Error ? error.message : String(error)}. Review the hook in Codex.`);
+    }
+}

package/dist/hosts/codex.js

@@ -1,20 +1,39 @@
-import { REPO, isSameRepo, redact } from '../source.js';
-import { blocked, failed, guard, mustProbeJson, mustRun, parseJson } from './shared.js';
+import { BRANCH, GIT_URL, REPO, isSameRepo, redact } from '../source.js';
+import { StepFailed, blocked, failed, guard, mustProbeJson, mustRun, parseJson } from './shared.js';
 import { result } from './types.js';
+import { approvePostmanHook } from './codex-hooks.js';
 // Codex names the marketplace after `.claude-plugin/marketplace.json`'s `name`.
 // `npx plugins add` installs a second copy under its own `plugins-cli` marketplace.
-const MARKETPLACE = 'postman', PLUGIN_ID = `postman@${MARKETPLACE}`, SHADOW_IDS = ['postman@plugins-cli'], NEXT = 'Restart Codex for the change to take effect.';
+const MARKETPLACE = 'postman', PLUGIN_ID = `postman@${MARKETPLACE}`, LEGACY_REF = 'codex-release', SHADOW_IDS = ['postman@plugins-cli'], NEXT = 'Restart Codex for the change to take effect.';
 function isInstalled(plugins, id) {
     return plugins.some((plugin) => plugin.pluginId === id && plugin.installed !== false);
 }
 async function listPlugins(system) {
     return (await mustProbeJson(system, 'codex', ['plugin', 'list', '--json'])).installed ?? [];
 }
+/** The marketplace's ref as Codex's own config reader reports it; `marketplace list --json` doesn't. */
+export async function registeredRef(system) {
+    const replies = await system.rpc('codex', ['app-server'], [
+        { method: 'initialize', params: { clientInfo: { name: 'postman-plugin', version: '0' } } },
+        { method: 'initialized', notify: true },
+        { method: 'config/read', params: {} }
+    ]), read = replies?.[1]?.result, entry = read?.config?.marketplaces?.[MARKETPLACE];
+    if (!entry || typeof entry !== 'object') {
+        return undefined;
+    }
+    return typeof entry.ref === 'string' ? entry.ref : entry.ref === null || entry.ref === undefined ? null : undefined;
+}
+async function addMarketplace(system) {
+    await mustRun(system, 'codex', ['plugin', 'marketplace', 'add', REPO, '--ref', BRANCH, '--json']);
+    // `add` records no revision, so without this Codex's next startup refetches the plugin and asks for approval again.
+    await mustRun(system, 'codex', ['plugin', 'marketplace', 'upgrade', MARKETPLACE, '--json']);
+}
+/** Adds or upgrades the marketplace, leaving the old release branch for `migrate`. */
 async function refreshMarketplace(system) {
     const listing = await mustProbeJson(system, 'codex', ['plugin', 'marketplace', 'list', '--json']), existing = listing.marketplaces?.find((marketplace) => marketplace.name === MARKETPLACE);
     if (!existing) {
-        await mustRun(system, 'codex', ['plugin', 'marketplace', 'add', REPO, '--json']);
-        return;
+        await addMarketplace(system);
+        return 'ready';
     }
     // A local marketplace can carry any path text, so only a git source counts as this repo.
     const { sourceType, source } = existing.marketplaceSource ?? {};
@@ -22,7 +41,58 @@ async function refreshMarketplace(system) {
         const from = source ? `${sourceType ?? 'unknown'} source ${redact(source)}` : 'an unknown source';
         blocked(`marketplace ${MARKETPLACE} is registered from ${from}, not ${REPO}`);
     }
-    await mustRun(system, 'codex', ['plugin', 'marketplace', 'upgrade', MARKETPLACE, '--json']);
+    if (system.dryRun) {
+        system.log(`  note: Would ask Codex for marketplace ${MARKETPLACE}'s ref: upgrade it on ${BRANCH}, migrate ${LEGACY_REF} to ${BRANCH}, preserve an unreadable ref, or stop for a custom ref. App-server is deferred because its startup can refresh plugins.`);
+        return 'deferred';
+    }
+    const ref = await registeredRef(system);
+    if (ref === undefined) {
+        system.log(`  note: Could not read marketplace ${MARKETPLACE}'s ref through codex app-server; keeping its registration and skipping ref migration.`);
+    }
+    if (ref === BRANCH || ref === null || ref === undefined) {
+        await mustRun(system, 'codex', ['plugin', 'marketplace', 'upgrade', MARKETPLACE, '--json']);
+        return 'ready';
+    }
+    if (ref !== LEGACY_REF) {
+        blocked(`marketplace ${MARKETPLACE} tracks ${ref}, not ${BRANCH}; run \`codex plugin marketplace remove ${MARKETPLACE}\` and re-run`);
+    }
+    return 'legacy';
+}
+/** Re-registers the previous marketplace and its plugin; true when every step exits 0. */
+async function restoreLegacy(system, wasInstalled) {
+    // Exits non-zero when the failed step left nothing registered, which is the state wanted here.
+    await system.run('codex', ['plugin', 'marketplace', 'remove', MARKETPLACE, '--json']);
+    const steps = [['plugin', 'marketplace', 'add', REPO, '--ref', LEGACY_REF, '--json'], ...(wasInstalled ? [['plugin', 'add', PLUGIN_ID, '--json']] : [])];
+    for (const args of steps) {
+        if ((await system.run('codex', args)).code !== 0) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Moves a marketplace registered at the old release branch to main, then adds the plugin. `remove`
+ * uninstalls Postman too, so a failure after it puts the previous registration back.
+ */
+async function migrate(system, wasInstalled) {
+    const reach = await system.probe('git', ['ls-remote', '--exit-code', GIT_URL, `refs/heads/${BRANCH}`]);
+    if (reach.code !== 0) {
+        failed(`can't reach ${BRANCH} in ${REPO}, so marketplace ${MARKETPLACE} was left tracking ${LEGACY_REF}`);
+    }
+    await mustRun(system, 'codex', ['plugin', 'marketplace', 'remove', MARKETPLACE, '--json']);
+    try {
+        await addMarketplace(system);
+        await mustRun(system, 'codex', ['plugin', 'add', PLUGIN_ID, '--json']);
+    }
+    catch (error) {
+        if (!(error instanceof StepFailed)) {
+            throw error;
+        }
+        const restored = await restoreLegacy(system, wasInstalled);
+        failed(`${error.outcome.message}\n${restored ?
+            `restored marketplace ${MARKETPLACE} tracking ${LEGACY_REF}${wasInstalled ? ` and ${PLUGIN_ID}` : ''}` :
+            `could not restore it either; run \`codex plugin marketplace remove ${MARKETPLACE}\`, \`codex plugin marketplace add ${REPO} --ref ${BRANCH}\`, \`codex plugin marketplace upgrade ${MARKETPLACE}\` and \`codex plugin add ${PLUGIN_ID}\``}`);
+    }
 }
 async function removeInstalled(system, plugins, ids) {
     const present = ids.filter((id) => isInstalled(plugins, id));
@@ -44,18 +114,27 @@ export const codex = {
             return { installed: null, detail: 'could not read `codex plugin list --json`', notes: [] };
         }
         const installed = plugins.find((plugin) => plugin.pluginId === PLUGIN_ID && plugin.installed !== false), notes = SHADOW_IDS.filter((id) => isInstalled(plugins, id)).map((id) => `${id} duplicates it and will be removed`);
+        if (installed && await registeredRef(system) === LEGACY_REF) {
+            notes.push(`marketplace ${MARKETPLACE} tracks ${LEGACY_REF} and will be re-added at ${BRANCH}; the installer then approves its session-start hook`);
+        }
         return installed ?
             { installed: true, detail: `${PLUGIN_ID} ${installed.version ?? ''}`.trim(), notes } :
             { installed: false, detail: 'not installed', notes };
     },
     install(system) {
         return guard(async () => {
-            await refreshMarketplace(system);
+            // Listed first: re-registering the marketplace uninstalls its plugins.
             const plugins = await listPlugins(system), wasInstalled = isInstalled(plugins, PLUGIN_ID);
             // `add` is idempotent and is also how Codex updates an installed plugin. It runs
             // before the duplicate is removed, so a failed add still leaves a working copy.
-            await mustRun(system, 'codex', ['plugin', 'add', PLUGIN_ID, '--json']);
+            if (await refreshMarketplace(system) === 'legacy') {
+                await migrate(system, wasInstalled);
+            }
+            else {
+                await mustRun(system, 'codex', ['plugin', 'add', PLUGIN_ID, '--json']);
+            }
             await removeInstalled(system, plugins, SHADOW_IDS);
+            await approvePostmanHook(system);
             return result('done', `${wasInstalled ? 'updated' : 'installed'} ${PLUGIN_ID}`, NEXT);
         });
     },

package/dist/json-rpc.js

@@ -0,0 +1,113 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+export class JsonRpcError extends Error {
+    reply;
+    constructor(reply) {
+        super(`app-server RPC error ${reply.code ?? ''}: ${reply.message ?? 'unknown error'}`);
+        this.reply = reply;
+    }
+}
+/** One stdio session with a deadline for each request. */
+export async function withJsonRpc(file, args, env, use, timeoutMs) {
+    // npm's Windows launchers need cmd.exe, just as System.run's launchers do.
+    const quote = (arg) => /^[\w@./:=-]+$/.test(arg) ? arg : `"${arg}"`, shell = /\.(cmd|bat)$/i.test(file), child = shell ?
+        spawn(quote(file), args.map(quote), { env, shell: true, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }) :
+        spawn(file, args, { env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }), lines = createInterface({ input: child.stdout }), pending = new Map();
+    let nextId = 0, failure;
+    function fail(error) {
+        failure = error;
+        for (const entry of pending.values()) {
+            clearTimeout(entry.timer);
+            entry.reject(error);
+        }
+        pending.clear();
+    }
+    child.on('error', fail);
+    child.stdin.on('error', fail);
+    // Drain diagnostics without putting arbitrary app-server output into installer logs.
+    child.stderr.resume();
+    const closed = new Promise((resolve) => child.once('close', (code) => {
+        fail(new Error(`app-server closed (exit ${code ?? 'signal'})`));
+        resolve();
+    }));
+    lines.on('line', (line) => {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            fail(new Error('app-server returned invalid JSON'));
+            return;
+        }
+        // Notifications are not replies. A server request is unsupported by this client.
+        if (message && typeof message.method === 'string') {
+            if (message.id !== undefined) {
+                child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'Method not found' } }) + '\n');
+            }
+            return;
+        }
+        const entry = pending.get(message?.id);
+        if (!entry) {
+            return;
+        }
+        clearTimeout(entry.timer);
+        pending.delete(message.id);
+        if (message.error) {
+            entry.reject(new JsonRpcError(message.error));
+        }
+        else if ('result' in message) {
+            entry.resolve(message.result);
+        }
+        else {
+            entry.reject(new Error('app-server reply has no result'));
+        }
+    });
+    try {
+        return await use({
+            request(method, params) {
+                if (failure) {
+                    return Promise.reject(failure);
+                }
+                const id = ++nextId;
+                return new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => fail(new Error(`app-server timed out waiting for ${method}`)), timeoutMs);
+                    pending.set(id, { resolve: (value) => resolve(value), reject, timer });
+                    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+                });
+            },
+            notify(method, params) {
+                if (failure) {
+                    throw failure;
+                }
+                child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n');
+            }
+        });
+    }
+    finally {
+        fail(new Error('app-server session ended'));
+        lines.close();
+        child.stdin.end();
+        if (child.exitCode === null && child.signalCode === null) {
+            if (shell && process.platform === 'win32' && child.pid) {
+                // Killing cmd.exe alone leaves its Codex child holding the pipes open.
+                spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore', windowsHide: true }).on('error', () => child.kill());
+            }
+            else {
+                child.kill();
+            }
+        }
+        let force;
+        const forced = new Promise((resolve) => {
+            force = setTimeout(() => {
+                child.kill('SIGKILL');
+                // A descendant retaining a pipe must not hold the installer open.
+                child.stdin.destroy();
+                child.stdout.destroy();
+                child.stderr.destroy();
+                resolve();
+            }, 1000);
+        });
+        await Promise.race([closed, forced]);
+        clearTimeout(force);
+    }
+}

package/dist/system.js

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { redact } from './source.js';
+import { JsonRpcError, withJsonRpc } from './json-rpc.js';
 // A missing file, or a path through something that isn't a directory. Anything else,
 // such as a file that exists but can't be read, must not pass for "absent".
 const ABSENT = ['ENOENT', 'ENOTDIR'];
@@ -35,8 +36,8 @@ function execute(file, args, env) {
 export function formatCommand(command, args) {
     return [command, ...args].map((part) => redact(part)).map((part) => (/^[\w@./:=~-]+$/.test(part) ? part : JSON.stringify(part))).join(' ');
 }
-export function createSystem({ dryRun = false, log = (line) => console.log(line) } = {}) {
-    const env = process.env, platform = process.platform;
+export function createSystem({ dryRun = false, log = (line) => console.log(line), env = process.env, home = os.homedir(), cwd = process.cwd() } = {}) {
+    const platform = process.platform;
     async function which(command) {
         const extensions = platform === 'win32' ? (env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : [''];
         for (const dir of (env.PATH || '').split(path.delimiter).filter(Boolean)) {
@@ -59,10 +60,11 @@ export function createSystem({ dryRun = false, log = (line) => console.log(line)
         return (await which(command)) || command;
     }
     return {
-        home: os.homedir(),
+        home,
         platform,
         env,
         dryRun,
+        cwd,
         which,
         async exists(file) {
             try {
@@ -101,6 +103,35 @@ export function createSystem({ dryRun = false, log = (line) => console.log(line)
         async probe(command, args) {
             return execute(await resolve(command), args, env);
         },
+        async rpc(command, args, calls) {
+            if (dryRun) {
+                return null;
+            }
+            try {
+                return await withJsonRpc(await resolve(command), args, env, async (rpc) => {
+                    const replies = [];
+                    for (const call of calls) {
+                        if (call.notify) {
+                            rpc.notify(call.method, call.params);
+                            continue;
+                        }
+                        try {
+                            replies.push({ result: await rpc.request(call.method, call.params) });
+                        }
+                        catch (error) {
+                            if (!(error instanceof JsonRpcError)) {
+                                throw error;
+                            }
+                            replies.push({ error: error.reply });
+                        }
+                    }
+                    return replies;
+                }, 30000);
+            }
+            catch {
+                return null;
+            }
+        },
         async run(command, args, options = {}) {
             log(`  $ ${formatCommand(command, args)}`);
             if (dryRun) {
@@ -108,6 +139,12 @@ export function createSystem({ dryRun = false, log = (line) => console.log(line)
             }
             return execute(await resolve(command), args, { ...env, ...options.env });
         },
+        async withJsonRpc(command, args, use, timeoutMs = 15000) {
+            log(`  $ ${formatCommand(command, args)} (stdio RPC)`);
+            if (!dryRun) {
+                return withJsonRpc(await resolve(command), args, env, use, timeoutMs);
+            }
+        },
         async writeFile(file, content) {
             log(`  write ${file}`);
             if (!dryRun) {

package/mcp.pi.json

@@ -6,8 +6,8 @@
       "description": "Postman workspaces, collections, specs, environments, mocks and monitors",
       "headers": {
         "X-Source": "postman-pi-plugin",
-        "X-Plugin-Version": "0.4.0",
-        "User-Agent": "postman-pi-plugin/0.4.0"
+        "X-Plugin-Version": "0.4.1",
+        "User-Agent": "postman-pi-plugin/0.4.1"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman/postman-plugin",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Postman's API engineering skills for coding agents: a Pi package, and an npx installer that sets up Claude Code, Codex, Cursor, Kimi Code, Factory Droid, OpenCode and Pi.",
   "type": "module",
   "license": "Apache-2.0",

package/skills/performance-testing/SKILL.md

@@ -39,12 +39,12 @@ Collections run directly: converting with `postman-to-k6` is not required.
 
 ## 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
+Have a JMeter `.jmx` instead of a collection? Import it by following
+`references/jmeter-import/README.md`, then treat the result as the collection
+above. Its mapping table carries the JMeter semantics that are easy to get
+wrong, and the import report 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

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

@@ -1,7 +1,6 @@
-
 # 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.
+> Reference for the `performance-testing` skill. Import the plan, review the report, then the result is an ordinary performance run.
 
 Turn a JMeter test plan into three artifacts:
 
@@ -9,65 +8,57 @@ Turn a JMeter test plan into three artifacts:
 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.
+There is no importer to run: you read the `.jmx` and build these yourself. The files next to this one are the algorithm:
 
-## Correctness rules the importer reproduces (do not regress)
+- `mapping-table.md` — what each JMeter element becomes, and how faithfully.
+- `postman-perf-capabilities.md` — the hard limits of the import target.
+- `script-translation.md` — Groovy/BeanShell → JS, and the JS templates for extractors and assertions.
+- `import-report.md` — the report's shape.
 
-These are JMeter semantics that are easy to get subtly wrong. They're covered by `tests/score.py`:
+## When NOT to guess
 
-- **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.
+Postman performance runs do not support everything JMeter does (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.
 
 ## 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
-```
+### 1. Walk the plan
 
-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`)
+JMX has one structural rule: every element is followed by a sibling `<hashTree>` holding its children. Walk those pairs. A config element (Header Manager, Auth Manager, 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. For a large plan, work one thread group or controller at a time.
 
-Python 3.8+ only, standard library — no pip installs.
+### 2. Apply the JMeter semantics
 
-### 2. Resolve the manual tasks
+These are easy to get subtly wrong:
 
-Open `<name>.ir.json` and read `manual_tasks`. Each has `request`, `kind`, `detail`. Handle by kind:
+- **Implicit HTTP success** — JMeter fails a sample on HTTP ≥ 400 even with no assertion. Every request gets the default 200–399 `pm.test` from `script-translation.md`, **unless** it has a Response Assertion whose `test_field` is `response_code` or `response_message`, or any assertion with `assume_success=true` (Ignore Status). An assertion on the body (`response_data`) does not suppress it.
+- **Port 0 / -1** → "use protocol default" → omit from the URL.
+- **Full-URL path** — if `HTTPSampler.path` starts with `http://` or `https://`, use it verbatim and ignore domain/port.
+- **HEAD / TRACE arguments** — JMeter doesn't send separate parameters as a query for these; drop them and note it.
+- **Headers** — in-scope Header Managers merge; the nearer/last value per name wins, and the collapse is reported. Keep inherited headers even on a GET (JMeter still sends them).
+- **Variables and functions** — `${var}` → `{{var}}`; `${__UUID}` → `{{$guid}}`, `${__time}` → `{{$timestamp}}`, `${__Random(..)}` → `{{$randomInt}}`, `${__RandomString(..)}` → `{{$randomAlphaNumeric}}`.
+- **Extractors and assertions** — extractors become `pm.collectionVariables.set` in the test script, assertions become `pm.test`. Use the templates in `script-translation.md` so every import produces the same code.
+- **Load** — VUs = `num_threads`; duration (minutes) = round(`ThreadGroup.duration` seconds ÷ 60), minimum 1; profile = `ramp-up` if `ramp_time` > 0 or it's a plugin/concurrency group, else `fixed`. Loop counts become duration (there is no iteration count). One `--pass-if` only: a Duration Assertion → `less_than(p95, <ms>)`, otherwise default to `less_than(error_rate, 5)`.
+- **Timers, concurrent thread groups, non-HTTP samplers** → not supported. List them in the report; never fake them.
 
-- **`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.
+### 3. Handle what needs judgment
 
-Edit the collection JSON in place. Keep the `// REVIEW` comments until the logic is confirmed.
+- **JSR223/BeanShell pre/post-processors** — translate to a prerequest/test script with `script-translation.md`. Mark anything you're unsure of with a `// REVIEW` comment and list it under "Needs manual work".
+- **JSR223/BeanShell samplers** (no HTTP) — decide with the user: delete it, fold its logic into an adjacent request's script, or replace it with a real request.
+- **XPath / CSS extractors** — the sandbox has no XPath/CSS engine. Rewrite against the JSON body if the response is JSON, use `xml2js`/`cheerio` via `require(...)` (confirm availability), or drop it with a note.
+- **Complex JSONPath** (wildcards, filters, recursion) — rewrite as explicit property access in the test script.
 
-### 3. Validate the output
+### 4. Validate the collection
 
-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.
+Confirm the collection is valid v2.1 JSON and that **every `event` script parses as JavaScript** (`node --check` each `exec`, or equivalent). A syntax error in a script is invisible in the file and only surfaces when the perf run executes that request, mid-load.
 
-### 4. Finalise the report
+### 5. Write 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.
+Fill in `import-report.md`'s sections and counts so the report matches the collection you're handing off.
 
-### 5. Hand off the perf config
+### 6. 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.
+The command needs a collection UID, so the collection must be in a workspace first. 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
+### 7. (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:
 
@@ -76,38 +67,16 @@ Only on explicit user consent — and **never make the user paste a workspace ID
 - **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.
+- **Get the imported collection into the bound workspace before pushing.** The import is 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.
+- **No think time.** JMeter timers are not reproduced; each one is reported.
 - Only **HTTP(S)** samplers import. JDBC/FTP/LDAP/Java/TCP/Debug/Dummy samplers are reported as skipped.