@postman/postman-plugin 0.2.2 → 0.4.0

package/README.md

@@ -24,12 +24,22 @@ Install Postman in every compatible coding agent detected on your machine:
 npx @postman/postman-plugin
 ```
 
-One command configures **Claude Code, Codex, Cursor, Factory Droid, Kimi Code,
-OpenCode and Pi**. Run it again to update, `status` to see what's installed,
+One command configures **Antigravity, Claude Code, Codex, GitHub Copilot CLI, Cursor,
+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.
 
 You can also use the following commands to install individually:
 
+### Antigravity
+
+```bash
+agy plugin install https://github.com/postmanlabs/postman-plugin
+```
+
+Run the same command again to update; `agy plugin uninstall postman` removes it.
+In the Antigravity app, **Customizations → Plugins → + Install from URL** takes
+the same URL.
+
 ### Claude Code
 
 [View Postman on Claude Plugins](https://claude.com/plugins/postman)
@@ -60,6 +70,16 @@ codex plugin add postman@postman
 /add-plugin postman
 ```
 
+### GitHub Copilot CLI
+
+```bash
+copilot plugin marketplace add postmanlabs/postman-plugin
+copilot plugin install postman@postman
+```
+
+`copilot plugin marketplace update postman`, then `copilot plugin update postman`, updates it. Sign in to Postman's MCP server
+with `/mcp` inside a Copilot CLI session.
+
 ### Factory Droid
 
 ```bash
@@ -85,8 +105,14 @@ Postman's MCP server with `/mcp-config login plugin-postman:postman`.
 
 ### OpenCode
 
-OpenCode loads Postman from a clone of this repository and a one-line loader
-file. [opencode/README.md](https://github.com/postmanlabs/postman-plugin/blob/main/opencode/README.md#install) has the commands.
+```bash
+opencode plugin add github:postmanlabs/postman-plugin
+```
+
+That is OpenCode 2.0.4 or later. On OpenCode 1.14.33 or later the command is
+`opencode plugin --global github:postmanlabs/postman-plugin`.
+[opencode/README.md](https://github.com/postmanlabs/postman-plugin/blob/main/opencode/README.md#install) has how to update and remove
+it, and the older clone-and-loader install.
 
 ### Pi
 
@@ -166,17 +192,39 @@ test consumers without waiting for the real service to be ready or available.
 
 The mock stays local until you choose to push and deploy it. When teammates or
 external systems need access, the same mock can become a durable hosted URL
-without rebuilding it in another tool.
+without rebuilding it in another tool. Pushed to the service's own workspace,
+it's the mock other teams' simulations pull first.
+
+### Develop against simulated dependencies
+
+The [`api-simulation`](https://github.com/postmanlabs/postman-plugin/blob/main/skills/api-simulation/) skill runs your code (a service
+you're changing, a frontend, a test suite or a demo) for real against stand-ins
+for the HTTP services it calls, served together on one port from one
+`.sim.yaml`. Each stand-in is the owning team's mock when they publish one.
+It reuses an existing `.sim.yaml`, proves a change with a request through the
+changed path, and answers "what happens if X goes down" by running each failure.
+Pushing the simulation is optional and needs your approval. It needs Postman CLI
+1.70.0 or later:
+
+```bash
+postman simulation run postman/simulations/orders-dev.sim.yaml --port 4900
+```
+
+The service under test is never mocked. It runs for real, so a passing run
+shows the change works against what the mocks model; it doesn't replace a run
+against the real upstreams. The simulation can also run in CI, and any
+dependency can take injected latency, error, rate-limit, or chaos conditions to
+exercise failure paths.
 
 
 ## How Postman builds context
 
 Work done in a Postman folder produces artifacts: collection runs, lint
 results, request history, mock deployments. When that folder is connected to a
-Postman workspace, after `postman init`, those artifacts are
-published to it as they are produced. The workspace is
-where a teammate, a reviewer, or another agent can see what the agent actually
-did.
+Postman workspace after `postman init`, those artifacts are published to it as
+they are produced. The workspace persists that context for future work and
+enables teammates, reviewers, and other agents to share and build on what the
+agent did.
 
 What each command contributes to the connected workspace:
 
@@ -185,7 +233,7 @@ What each command contributes to the connected workspace:
 | `postman collection run` | Run results and run history |
 | `postman application test` | Test run results |
 | `postman spec lint` | Lint results, including violation counts and pass/fail |
-| `postman workspace push` | The local workspace contents |
+| `postman workspace push` | Local workspace contents, persisted as context for future work and sharing with others |
 | `postman runner start` | Runner processing and health activity |
 | `postman flows run` | Flow run results |
 | `postman request` | Agent's API interaction activity |

package/dist/hosts/antigravity.js

@@ -0,0 +1,47 @@
+import { REPO } from '../source.js';
+import { guard, mustProbeJson, mustRun, parseJson } from './shared.js';
+import { result } from './types.js';
+// `agy plugin install` clones a git URL into ~/.gemini/config/plugins/<name>. It has no update
+// command; installing again replaces the copy in place, so a re-run is the update.
+const PLUGIN_NAME = 'postman', SOURCE = `https://github.com/${REPO}`, NEXT = 'Restart Antigravity for the change to take effect.';
+const isOurs = (plugin) => plugin.name === PLUGIN_NAME;
+export const antigravity = {
+    id: 'antigravity',
+    name: 'Antigravity',
+    route: '.antigravity-plugin',
+    async detect(system) {
+        return (await system.which('agy')) !== null;
+    },
+    async status(system) {
+        const exec = await system.probe('agy', ['plugin', 'list', '--json']), plugins = exec.code === 0 ? parseJson(exec.stdout) : null;
+        if (!Array.isArray(plugins)) {
+            return { installed: null, detail: 'could not read `agy plugin list --json`', notes: [] };
+        }
+        const installed = plugins.find(isOurs);
+        if (!installed) {
+            return { installed: false, detail: 'not installed', notes: [] };
+        }
+        return {
+            installed: true,
+            detail: `${PLUGIN_NAME} ${installed.version ?? ''}`.trim(),
+            notes: installed.enabled === false ? ['installed but disabled; run `agy plugin enable postman`'] : []
+        };
+    },
+    install(system) {
+        return guard(async () => {
+            const plugins = await mustProbeJson(system, 'agy', ['plugin', 'list', '--json']), current = plugins.some(isOurs);
+            await mustRun(system, 'agy', ['plugin', 'install', SOURCE]);
+            return result('done', `${current ? 'updated' : 'installed'} ${PLUGIN_NAME}`, NEXT);
+        });
+    },
+    remove(system) {
+        return guard(async () => {
+            const plugins = await mustProbeJson(system, 'agy', ['plugin', 'list', '--json']);
+            if (!plugins.some(isOurs)) {
+                return result('skipped', 'not installed');
+            }
+            await mustRun(system, 'agy', ['plugin', 'uninstall', PLUGIN_NAME]);
+            return result('done', `uninstalled ${PLUGIN_NAME}`, NEXT);
+        });
+    }
+};

package/dist/hosts/copilot.js

@@ -0,0 +1,60 @@
+import { REPO } from '../source.js';
+import { guard, mustProbeJson, mustRun, parseJson } from './shared.js';
+import { result } from './types.js';
+// Copilot CLI is deprecating direct installs (repos, URLs, local paths), so this installs from this
+// repo as a marketplace, which Copilot reads from `.claude-plugin/marketplace.json`. Once Postman is
+// listed in awesome-copilot, which Copilot ships registered, `postman@awesome-copilot` replaces it.
+const PLUGIN_NAME = 'postman', MARKETPLACE = 'postman', PLUGIN_ID = `${PLUGIN_NAME}@${MARKETPLACE}`, NEXT = 'Restart Copilot CLI (or run /restart) for the change to take effect.';
+const isOurs = (plugin) => plugin.name === PLUGIN_NAME, 
+// A direct install has no marketplace; it would load the same skills a second time.
+isDirect = (plugin) => isOurs(plugin) && !plugin.marketplace;
+export const copilot = {
+    id: 'copilot',
+    name: 'GitHub Copilot CLI',
+    route: '.github/plugin',
+    async detect(system) {
+        return (await system.which('copilot')) !== null;
+    },
+    async status(system) {
+        const exec = await system.probe('copilot', ['plugin', 'list', '--json']), plugins = exec.code === 0 ? parseJson(exec.stdout) : null;
+        if (!Array.isArray(plugins)) {
+            return { installed: null, detail: 'could not read `copilot plugin list --json`', notes: [] };
+        }
+        const installed = plugins.find(isOurs);
+        if (!installed) {
+            return { installed: false, detail: 'not installed', notes: [] };
+        }
+        return {
+            installed: true,
+            detail: `${PLUGIN_NAME} ${installed.version ?? ''}`.trim(),
+            notes: installed.enabled === false ? ['installed but disabled; run `copilot plugin enable postman`'] : []
+        };
+    },
+    install(system) {
+        return guard(async () => {
+            const plugins = await mustProbeJson(system, 'copilot', ['plugin', 'list', '--json']), marketplaces = await mustProbeJson(system, 'copilot', ['plugin', 'marketplace', 'list', '--json']), current = plugins.some((plugin) => isOurs(plugin) && plugin.marketplace === MARKETPLACE);
+            if (marketplaces.some((marketplace) => marketplace.name === MARKETPLACE)) {
+                await mustRun(system, 'copilot', ['plugin', 'marketplace', 'update', MARKETPLACE]);
+            }
+            else {
+                await mustRun(system, 'copilot', ['plugin', 'marketplace', 'add', REPO]);
+            }
+            // The same name can't be installed twice, so a direct install goes first.
+            if (plugins.some(isDirect)) {
+                await mustRun(system, 'copilot', ['plugin', 'uninstall', PLUGIN_NAME]);
+            }
+            await mustRun(system, 'copilot', current ? ['plugin', 'update', PLUGIN_NAME] : ['plugin', 'install', PLUGIN_ID]);
+            return result('done', `${current ? 'updated' : 'installed'} ${PLUGIN_ID}`, NEXT);
+        });
+    },
+    remove(system) {
+        return guard(async () => {
+            const plugins = await mustProbeJson(system, 'copilot', ['plugin', 'list', '--json']);
+            if (!plugins.some(isOurs)) {
+                return result('skipped', 'not installed');
+            }
+            await mustRun(system, 'copilot', ['plugin', 'uninstall', PLUGIN_NAME]);
+            return result('done', `uninstalled ${PLUGIN_NAME}`, NEXT);
+        });
+    }
+};

package/dist/hosts/index.js

@@ -1,8 +1,10 @@
+import { antigravity } from './antigravity.js';
 import { claudeCode } from './claude-code.js';
 import { codex } from './codex.js';
+import { copilot } from './copilot.js';
 import { cursor } from './cursor.js';
 import { factory } from './factory.js';
 import { kimi } from './kimi.js';
 import { opencode } from './opencode.js';
 import { pi } from './pi.js';
-export const HOSTS = [claudeCode, codex, cursor, factory, kimi, opencode, pi];
+export const HOSTS = [antigravity, claudeCode, codex, copilot, cursor, factory, kimi, opencode, pi];

package/dist/hosts/opencode-config.js

@@ -0,0 +1,147 @@
+// OpenCode's config is JSONC: comments and trailing commas are allowed, and users edit it by hand.
+// Reading it and removing one array entry from it must therefore leave everything else as written.
+const PUNCTUATION = '{}[]:,', WHITESPACE = /\s/, WHITESPACE_ONLY = /^\s*$/;
+function tokenize(text) {
+    const tokens = [];
+    let index = text.charCodeAt(0) === 0xFEFF ? 1 : 0;
+    while (index < text.length) {
+        const char = text[index];
+        if (WHITESPACE.test(char)) {
+            index += 1;
+        }
+        else if (text.startsWith('//', index)) {
+            // A line comment ends at either line terminator; a CR-only file has no \n at all.
+            const lineEnd = text.slice(index).search(/[\r\n]/);
+            index = lineEnd === -1 ? text.length : index + lineEnd + 1;
+        }
+        else if (text.startsWith('/*', index)) {
+            const close = text.indexOf('*/', index + 2);
+            if (close === -1) {
+                // An unterminated comment is not valid JSONC; keep it as a token JSON.parse will reject.
+                tokens.push({ kind: 'other', start: index, end: text.length, text: text.slice(index) });
+                break;
+            }
+            index = close + 2;
+        }
+        else if (char === '"') {
+            let end = index + 1;
+            while (end < text.length && text[end] !== '"') {
+                end += text[end] === '\\' ? 2 : 1;
+            }
+            tokens.push({ kind: 'string', start: index, end: end + 1, text: text.slice(index, end + 1) });
+            index = end + 1;
+        }
+        else if (PUNCTUATION.includes(char)) {
+            tokens.push({ kind: 'punct', start: index, end: index + 1, text: char });
+            index += 1;
+        }
+        else {
+            let end = index;
+            while (end < text.length && !WHITESPACE.test(text[end]) && !PUNCTUATION.includes(text[end]) && text[end] !== '"' && !text.startsWith('//', end) && !text.startsWith('/*', end)) {
+                end += 1;
+            }
+            tokens.push({ kind: 'other', start: index, end, text: text.slice(index, end) });
+            index = end;
+        }
+    }
+    return tokens;
+}
+/** Parses JSONC; `null` when it is not valid even after comments and trailing commas are dropped. */
+export function parseJsonc(text) {
+    const tokens = tokenize(text);
+    let json = '';
+    tokens.forEach((token, at) => {
+        const next = tokens[at + 1];
+        if (token.text === ',' && next && (next.text === ']' || next.text === '}')) {
+            return;
+        }
+        json += `${token.text} `;
+    });
+    try {
+        return JSON.parse(json || 'null');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The direct string elements of the root object's array under `key`, or `null` when there is no such array or the root
+ * object has `key` more than once: JSON.parse keeps the last one, so editing any of them could leave the one that counts.
+ */
+function stringElements(tokens, key) {
+    let depth = 0, found = null, occurrences = 0;
+    for (let at = 0; at < tokens.length; at += 1) {
+        const token = tokens[at];
+        if (token.kind === 'punct' && '{['.includes(token.text)) {
+            depth += 1;
+        }
+        else if (token.kind === 'punct' && '}]'.includes(token.text)) {
+            depth -= 1;
+        }
+        else if (depth === 1 && token.kind === 'string' && tokens[at + 1]?.text === ':') {
+            let value;
+            try {
+                value = JSON.parse(token.text);
+            }
+            catch {
+                continue;
+            }
+            if (value !== key) {
+                continue;
+            }
+            occurrences += 1;
+            if (tokens[at + 2]?.text !== '[') {
+                continue;
+            }
+            const elements = [];
+            let nested = 1;
+            for (let inner = at + 3; inner < tokens.length && nested > 0; inner += 1) {
+                const item = tokens[inner];
+                if (item.kind === 'punct' && '{['.includes(item.text)) {
+                    nested += 1;
+                }
+                else if (item.kind === 'punct' && '}]'.includes(item.text)) {
+                    nested -= 1;
+                }
+                else if (nested === 1 && item.kind === 'string') {
+                    elements.push({
+                        start: item.start,
+                        end: item.end,
+                        value: JSON.parse(item.text),
+                        before: tokens[inner - 1].text === ',' ? tokens[inner - 1] : null,
+                        after: tokens[inner + 1]?.text === ',' ? tokens[inner + 1] : null
+                    });
+                }
+            }
+            found ??= elements;
+        }
+    }
+    return occurrences === 1 ? found : null;
+}
+/** `text` without the first `value` in the array under `key`, comments and layout intact; `null` if it is not there or the result would not parse. */
+export function withoutArrayString(text, key, value) {
+    const element = stringElements(tokenize(text), key)?.find((entry) => entry.value === value);
+    if (!element) {
+        return null;
+    }
+    let start = element.start, end = element.end;
+    if (element.after) {
+        end = element.after.end;
+        while (WHITESPACE.test(text[end] ?? '')) {
+            end += 1;
+        }
+    }
+    else if (element.before && WHITESPACE_ONLY.test(text.slice(element.before.end, element.start))) {
+        start = element.before.start;
+    }
+    // A comment between the comma and the last element belongs to the element before it, so only the comma goes.
+    else if (element.before) {
+        while (/[ \t]/.test(text[start - 1] ?? '')) {
+            start -= 1;
+        }
+        const edited = text.slice(0, element.before.start) + text.slice(element.before.end, start) + text.slice(end);
+        return parseJsonc(edited) === null ? null : edited;
+    }
+    const edited = text.slice(0, start) + text.slice(end);
+    return parseJsonc(edited) === null ? null : edited;
+}