@postman/postman-plugin 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Postman, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,9 +1,163 @@
-# @postman/postman-plugin
+<div align="center">
 
-Namespace placeholder for `@postman/postman-plugin`.
+<a href="https://www.postman.com/"><img src="https://assets.getpostman.com/common-share/postman-logo-horizontal-320x132.png" alt="Postman" width="240" /></a>
 
-Real releases ship from CI via OIDC Trusted Publishing — see the linked
-repository for the release workflow. This `0.0.0` stub exists only to claim
-the name under the `@postman` scope and apply least-privilege team
-permissions. It is private (`--access restricted`); the first real release
-makes the package public if/when the team decides.
+# Postman Plugin
+**Powering API engineering for agents**
+
+The Postman plugin brings filesystem-first API development and organization-wide
+API context to coding agents. It enables agents to design, mock, test, document,
+monitor, and ship APIs directly from Claude Code, Cursor, and Codex. Every
+operation produces inspectable files or CLI commands that fit naturally into
+Git and CI, while the Postman Context Graph helps agents understand
+dependencies, ownership, runtime behavior, and the likely impact of a change.
+
+[Install](#install) · [Highlights](#highlights)
+
+</div>
+
+## Install
+
+Install Postman in every compatible coding agent detected on your machine:
+
+```bash
+npx @postman/postman-plugin
+```
+
+One command configures **Claude Code, Codex, Cursor, Kimi Code and OpenCode**.
+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:
+
+### Claude Code
+
+[View Postman on Claude Plugins](https://claude.com/plugins/postman)
+
+```bash
+claude plugin install postman@postman
+```
+
+### Cursor
+
+[View Postman on the Cursor Marketplace](https://cursor.com/marketplace/postman)
+
+```text
+/add-plugin postman
+```
+
+### Codex
+
+[View Postman on ChatGPT Plugins](https://chatgpt.com/plugins/postman?open_in_app)
+
+```bash
+codex plugin add postman@postman
+```
+
+## Highlights
+
+### Filesystem-first API development
+
+All postman resources have a filesystem representation, so your agent can work
+with the API ecosystem through the interface it understands best: files. API
+specifications, collections, environments, examples, mocks, documentation,
+and Flows can live beside the application code.
+
+The git-native [v3 collection schema](https://github.com/postmanlabs/postman-plugin/blob/main/skills/collection-schema-v3/) makes this
+especially agent-friendly. A collection is a directory tree under
+`postman/collections/`, where every request, folder definition, and saved
+example is its own YAML file. Environments use the same file-first model under
+`postman/environments/`. HTTP, GraphQL, gRPC, WebSocket, Socket.IO, MQTT, MCP,
+and LLM requests all have defined schemas the agent can follow.
+
+That means the agent can:
+
+- Read or change one request without rewriting a large collection export.
+- Generate requests and examples directly from an API specification.
+- Produce small, reviewable Git diffs and resolve changes with normal code
+  review workflows.
+- Lint and test the files locally before anything is shared with a Postman
+  workspace.
+
+
+### Context Graph: know what breaks before you make a change
+
+A repository can show what an endpoint calls, but rarely who calls it, whether
+those consumers are active in production, where they are deployed, or which
+team owns them. The Context Graph fills that gap with a private, authenticated,
+organization-wide map of your API ecosystem.
+
+It reconciles signals from the systems where API knowledge already lives:
+
+- **Postman workspaces:** specifications, collections, monitors, and mocks
+- **GitHub:** repositories, API definitions, and source-level call sites
+- **New Relic:** deployments, runtime traffic, latency, errors, and telemetry
+
+The [`api-discovery`](https://github.com/postmanlabs/postman-plugin/blob/main/skills/api-discovery/) skill lets the agent start with the
+thing you plan to change and ask one natural-language question:
+
+```bash
+postman context-graph ask "What could break if we change the billing API?" --wait
+```
+
+
+The graph discovers the surrounding scope—including repositories that are not
+checked out locally—before the agent starts editing code. It refreshes nightly
+as services, deployments, ownership, and runtime relationships change.
+
+In Postman's controlled benchmark across 468 repositories, starting with this
+map used **up to 74% fewer tokens, 52% fewer tool calls, and 72% lower cost**.
+Accuracy also improved in 18 of 21 scored prompt-model pairs. Most graph
+queries completed in roughly 20–40 seconds. Read the methodology and results in
+[Introducing the Context Graph API: One Map of Your API Ecosystem](https://blog.postman.com/introducing-the-context-graph-api-one-map-of-your-api-ecosystem/).
+
+### File-first API mocks
+
+The [`api-mocking`](https://github.com/postmanlabs/postman-plugin/blob/main/skills/api-mocking/) skill creates a working mock from an
+OpenAPI specification or collection and stores the implementation beside the
+API code. The agent can run it locally, add success and failure scenarios, and
+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.
+
+
+## Telemetry
+
+Some Postman CLI commands report usage analytics by default. Where supported,
+you can disable reporting for an individual command with
+`--no-report-events`. `postman application test` uses
+`--report-events=false` instead.
+
+What is sent by default:
+
+| Command | Data sent |
+| --- | --- |
+| `postman collection run` | Run analytics and run history |
+| `postman application test` | Run results and analytics |
+| `postman spec lint` | Lint analytics, including violation counts and pass/fail |
+| `postman workspace push` | Push analytics |
+| `postman runner start` | Runner analytics |
+| `postman flows run` | Flow-run analytics |
+| `postman request` | Request analytics |
+
+Important limits:
+
+- `postman collection run --no-report-events` disables analytics but does not
+  disable run-history uploads.
+- `postman init` makes richer reporting opt-in with `--report-events`; it does
+  not accept `--report-events=false`.
+- The CLI also sends a minimal, unauthenticated event indicating that certain
+  commands ran. Reporting flags do not disable these client events. They are
+  emitted by `collection run`, `spec lint`, `workspace push`, `init`, the
+  `mock` commands, and `performance run` in the US region; other regions,
+  including the EU, do not emit them.
+- The plugin registers Postman's hosted MCP server as a fallback when the CLI
+  cannot run. MCP tool calls reach Postman and are not controlled by CLI
+  reporting flags; avoiding that traffic requires not installing the MCP
+  server.
+
+## License
+
+Apache-2.0 — see [LICENSE](https://github.com/postmanlabs/postman-plugin/blob/main/LICENSE).

package/dist/cli.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from 'node:util';
+import { HOSTS } from './hosts/index.js';
+import { EXIT, run } from './run.js';
+import { createSystem } from './system.js';
+const COMMANDS = { install: 'install', status: 'status', remove: 'remove', uninstall: 'remove' }, HOST_IDS = HOSTS.map((host) => host.id), USAGE = `Install the Postman plugin into every coding agent on this machine.
+
+Usage: npx @postman/postman-plugin [command] [options]
+
+Commands:
+  install     Install into each detected agent, or update it there (default)
+  status      Show which agents are detected and whether Postman is installed
+  remove      Uninstall from each detected agent (alias: uninstall)
+
+Options:
+  --agent <id>  Only these agents; repeat or comma-separate: ${HOST_IDS.join(', ')}
+  -y, --yes     Don't ask for confirmation (required when not in a terminal)
+  --dry-run     Print what would change without changing anything
+  -h, --help    Show this help
+  -v, --version Show the version
+
+Exit codes:
+  0  Done, or nothing needed doing
+  1  Something failed or was blocked, you cancelled, or install found no agent
+  2  Bad usage, or confirmation needed but no terminal (use --yes)
+  3  Done, except a step only you can do (printed as "next:")`;
+function version() {
+    const manifest = new URL('../package.json', import.meta.url);
+    return JSON.parse(fs.readFileSync(manifest, 'utf8')).version;
+}
+async function confirm(question) {
+    const readline = createInterface({ input: stdin, output: stdout });
+    try {
+        return !/^n/i.test((await readline.question(question)).trim());
+    }
+    finally {
+        readline.close();
+    }
+}
+function fail(message) {
+    console.error(`${message}\n\n${USAGE}`);
+    return EXIT.usage;
+}
+async function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                agent: { type: 'string', multiple: true },
+                yes: { type: 'boolean', short: 'y' },
+                'dry-run': { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'v' }
+            }
+        });
+    }
+    catch (error) {
+        return fail(error.message);
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        console.log(USAGE);
+        return EXIT.ok;
+    }
+    if (values.version) {
+        console.log(version());
+        return EXIT.ok;
+    }
+    const command = COMMANDS[positionals[0] ?? 'install'], agents = (values.agent ?? []).flatMap((value) => value.split(',')).map((value) => value.trim()).filter(Boolean), unknown = agents.filter((agent) => !HOST_IDS.includes(agent));
+    if (!command || positionals.length > 1) {
+        return fail(`Unknown command: ${positionals.join(' ')}`);
+    }
+    // An empty selection would mean "every agent", the opposite of what `--agent` asked for.
+    if (values.agent && !agents.length) {
+        return fail('--agent was given no agent id');
+    }
+    if (unknown.length) {
+        return fail(`Unknown agent: ${unknown.join(', ')}`);
+    }
+    return run(createSystem({ dryRun: Boolean(values['dry-run']) }), HOSTS, {
+        command,
+        agents: agents,
+        yes: Boolean(values.yes),
+        isTTY: Boolean(stdin.isTTY),
+        confirm
+    });
+}
+process.exitCode = await main(process.argv.slice(2));

package/dist/hosts/claude-code.js

@@ -0,0 +1,84 @@
+import { redact } from '../source.js';
+import { blocked, failed, guard, mustProbeJson, mustRun, parseJson } from './shared.js';
+import { result } from './types.js';
+// Anthropic's catalog entry is the Claude Code install; our own marketplace
+// would register the same skills a second time under `postman@postman`.
+const MARKETPLACE = { name: 'claude-plugins-official', repo: 'anthropics/claude-plugins-official' }, PLUGIN_ID = `postman@${MARKETPLACE.name}`, SHADOW_IDS = ['postman@postman'], SCOPE = 'user', NEXT = 'Restart Claude Code for the change to take effect.';
+const isOurs = (plugin) => plugin.id === PLUGIN_ID || SHADOW_IDS.includes(plugin.id);
+function listPlugins(system) {
+    return mustProbeJson(system, 'claude', ['plugin', 'list', '--json']);
+}
+function otherScopeNotes(plugins) {
+    const projects = new Map();
+    for (const plugin of plugins.filter((entry) => isOurs(entry) && entry.scope !== SCOPE)) {
+        projects.set(plugin.id, (projects.get(plugin.id) ?? new Set()).add(plugin.projectPath ?? plugin.scope));
+    }
+    return [...projects].map(([id, paths]) => `${id} is also installed at project or local scope in ${paths.size} project${paths.size === 1 ? '' : 's'}; left alone`);
+}
+async function refreshMarketplace(system) {
+    const marketplaces = await mustProbeJson(system, 'claude', ['plugin', 'marketplace', 'list', '--json']), existing = marketplaces.find((marketplace) => marketplace.name === MARKETPLACE.name);
+    if (!existing) {
+        await mustRun(system, 'claude', ['plugin', 'marketplace', 'add', MARKETPLACE.repo, '--scope', SCOPE]);
+        return;
+    }
+    if (existing.repo !== MARKETPLACE.repo) {
+        const source = existing.repo ?? existing.url ?? existing.path;
+        blocked(`marketplace ${MARKETPLACE.name} is registered from ${source ? redact(source) : 'an unknown source'}, not ${MARKETPLACE.repo}`);
+    }
+    await mustRun(system, 'claude', ['plugin', 'marketplace', 'update', MARKETPLACE.name]);
+}
+async function uninstallAtUserScope(system, plugins, ids) {
+    for (const id of ids) {
+        if (plugins.some((plugin) => plugin.id === id && plugin.scope === SCOPE)) {
+            await mustRun(system, 'claude', ['plugin', 'uninstall', id, '--scope', SCOPE, '--json']);
+        }
+    }
+}
+export const claudeCode = {
+    id: 'claude-code',
+    name: 'Claude Code',
+    route: '.claude-plugin',
+    async detect(system) {
+        return (await system.which('claude')) !== null;
+    },
+    async status(system) {
+        const exec = await system.probe('claude', ['plugin', 'list', '--json']), plugins = exec.code === 0 ? parseJson(exec.stdout) : null;
+        if (!Array.isArray(plugins)) {
+            return { installed: null, detail: 'could not read `claude plugin list --json`', notes: [] };
+        }
+        const installed = plugins.find((plugin) => plugin.id === PLUGIN_ID && plugin.scope === SCOPE), shadows = plugins.filter((plugin) => SHADOW_IDS.includes(plugin.id) && plugin.scope === SCOPE), notes = [
+            ...shadows.map((plugin) => `${plugin.id} (${SCOPE} scope) duplicates it and will be uninstalled`),
+            ...otherScopeNotes(plugins)
+        ];
+        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);
+            const plugins = await listPlugins(system), verb = plugins.some((plugin) => plugin.id === PLUGIN_ID && plugin.scope === SCOPE) ? 'update' : 'install';
+            // Replacement first: if it fails, the duplicate is still a working copy.
+            await mustRun(system, 'claude', ['plugin', verb, PLUGIN_ID, '--scope', SCOPE, '--json']);
+            await uninstallAtUserScope(system, plugins, SHADOW_IDS);
+            return result('done', `${verb === 'update' ? 'updated' : 'installed'} ${PLUGIN_ID}`, NEXT);
+        });
+    },
+    remove(system) {
+        return guard(async () => {
+            const plugins = await listPlugins(system), ids = [PLUGIN_ID, ...SHADOW_IDS].filter((id) => plugins.some((plugin) => plugin.id === id && plugin.scope === SCOPE));
+            if (!ids.length) {
+                return result('skipped', 'not installed at user scope');
+            }
+            await uninstallAtUserScope(system, plugins, ids);
+            // status() sees only the official ID, so the duplicate's removal is confirmed here.
+            if (!system.dryRun) {
+                const after = await listPlugins(system), left = ids.filter((id) => after.some((plugin) => plugin.id === id && plugin.scope === SCOPE));
+                if (left.length) {
+                    failed(`uninstall exited 0, but ${left.join(', ')} is still installed at user scope`);
+                }
+            }
+            return result('done', `uninstalled ${ids.join(', ')}`, NEXT);
+        });
+    }
+};

package/dist/hosts/codex.js

@@ -0,0 +1,77 @@
+import { REPO, isSameRepo, redact } from '../source.js';
+import { blocked, failed, guard, mustProbeJson, mustRun, parseJson } from './shared.js';
+import { result } from './types.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.';
+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 ?? [];
+}
+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;
+    }
+    // A local marketplace can carry any path text, so only a git source counts as this repo.
+    const { sourceType, source } = existing.marketplaceSource ?? {};
+    if (sourceType !== 'git' || !isSameRepo(source, REPO)) {
+        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']);
+}
+async function removeInstalled(system, plugins, ids) {
+    const present = ids.filter((id) => isInstalled(plugins, id));
+    for (const id of present) {
+        await mustRun(system, 'codex', ['plugin', 'remove', id, '--json']);
+    }
+    return present;
+}
+export const codex = {
+    id: 'codex',
+    name: 'Codex',
+    route: '.codex-plugin',
+    async detect(system) {
+        return (await system.which('codex')) !== null;
+    },
+    async status(system) {
+        const exec = await system.probe('codex', ['plugin', 'list', '--json']), plugins = exec.code === 0 ? parseJson(exec.stdout)?.installed : null;
+        if (!Array.isArray(plugins)) {
+            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`);
+        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);
+            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']);
+            await removeInstalled(system, plugins, SHADOW_IDS);
+            return result('done', `${wasInstalled ? 'updated' : 'installed'} ${PLUGIN_ID}`, NEXT);
+        });
+    },
+    remove(system) {
+        return guard(async () => {
+            const removed = await removeInstalled(system, await listPlugins(system), [PLUGIN_ID, ...SHADOW_IDS]);
+            // status() sees only our ID, so the duplicate's removal is confirmed here.
+            if (removed.length && !system.dryRun) {
+                const after = await listPlugins(system), left = removed.filter((id) => isInstalled(after, id));
+                if (left.length) {
+                    failed(`remove exited 0, but ${left.join(', ')} is still installed`);
+                }
+            }
+            return removed.length ?
+                result('done', `removed ${removed.join(', ')}`, NEXT) :
+                result('skipped', 'not installed');
+        });
+    }
+};

package/dist/hosts/cursor.js

@@ -0,0 +1,59 @@
+import path from 'node:path';
+import { guard, removeClone, syncClone } from './shared.js';
+import { result } from './types.js';
+// Cursor has no command to install a plugin, but loads any plugin folder under
+// plugins/local. Its Marketplace keeps its own copy under plugins/cache.
+const localClone = (system) => path.join(system.home, '.cursor', 'plugins', 'local', 'postman'), marketplaceCopy = (system) => path.join(system.home, '.cursor', 'plugins', 'cache', 'cursor-public', 'postman'), NEXT = 'Reload the Cursor window (Developer: Reload Window) for the change to take effect.', 
+// Cursor keeps a disabled Marketplace copy on disk and records "enabled" only in its
+// private state database, so the copy being there doesn't mean Postman is active.
+CHECK_ENABLED = 'If Postman isn\'t active in Cursor, enable it in Cursor Settings > Plugins.', MAYBE_TWICE = 'The Cursor Marketplace copy is present too; if it\'s enabled, Postman loads twice, so disable one in Cursor Settings > Plugins.';
+export const cursor = {
+    id: 'cursor',
+    name: 'Cursor',
+    route: '.cursor-plugin',
+    async detect(system) {
+        return (await system.which('cursor')) !== null ||
+            (system.platform === 'darwin' && await system.exists('/Applications/Cursor.app')) ||
+            await system.exists(path.join(system.home, '.cursor'));
+    },
+    async status(system) {
+        const fromMarketplace = await system.exists(marketplaceCopy(system)), cloned = await system.exists(localClone(system)), 
+        // The manifest Cursor reads; a directory without it is nothing Cursor can load.
+        loadable = cloned && await system.exists(path.join(localClone(system), '.cursor-plugin', 'plugin.json')), notes = [
+            ...(cloned && !loadable ? [`${localClone(system)} exists but has no .cursor-plugin/plugin.json, so Cursor loads nothing from it`] : []),
+            ...(fromMarketplace && loadable ? ['the Cursor Marketplace copy is present too; if it\'s enabled, both load Postman'] : [])
+        ];
+        if (loadable) {
+            return { installed: true, detail: `local clone at ${localClone(system)}`, notes };
+        }
+        return fromMarketplace ?
+            { installed: true, detail: 'Cursor Marketplace copy present (enabled or not is up to Cursor)', notes } :
+            { installed: false, detail: 'not installed', notes };
+    },
+    install(system) {
+        return guard(async () => {
+            const fromMarketplace = await system.exists(marketplaceCopy(system));
+            if (fromMarketplace && !(await system.exists(localClone(system)))) {
+                return result('skipped', 'the Cursor Marketplace copy is present', CHECK_ENABLED);
+            }
+            // An existing clone is kept even next to the Marketplace copy, which may be
+            // disabled: a duplicate is visible and fixable, deleting the working copy is not.
+            const action = await syncClone(system, localClone(system));
+            return result('done', `${action} ${localClone(system)}`, fromMarketplace ? `${NEXT} ${MAYBE_TWICE}` : NEXT);
+        });
+    },
+    remove(system) {
+        return guard(async () => {
+            const cloned = await system.exists(localClone(system));
+            if (cloned) {
+                await removeClone(system, localClone(system));
+            }
+            if (await system.exists(marketplaceCopy(system))) {
+                return result('manual', cloned ?
+                    `removed ${localClone(system)}, but the Cursor Marketplace copy is still installed` :
+                    'installed from the Cursor Marketplace', 'Uninstall it in Cursor Settings > Plugins.');
+            }
+            return cloned ? result('done', `removed ${localClone(system)}`, NEXT) : result('skipped', 'not installed');
+        });
+    }
+};

package/dist/hosts/index.js

@@ -0,0 +1,6 @@
+import { claudeCode } from './claude-code.js';
+import { codex } from './codex.js';
+import { cursor } from './cursor.js';
+import { kimi } from './kimi.js';
+import { opencode } from './opencode.js';
+export const HOSTS = [claudeCode, codex, cursor, kimi, opencode];

package/dist/hosts/kimi.js

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { PLUGINS_CLI, REPO } from '../source.js';
+import { blocked, guard, mustRun, parseJson } from './shared.js';
+import { result } from './types.js';
+// Kimi Code installs plugins only from its TUI (`/plugins install`), so the
+// `plugins` CLI writes its plugin store instead. Kimi records it as a local path.
+const PLUGIN_ID = 'postman', NEXT = 'Restart Kimi Code for the change to take effect.', kimiHome = (system) => system.env.KIMI_CODE_HOME || path.join(system.home, '.kimi-code'), installedFile = (system) => path.join(kimiHome(system), 'plugins', 'installed.json'), binary = (system) => `kimi${system.platform === 'win32' ? '.exe' : ''}`;
+// The same places `plugins` looks, so both agree on whether Kimi is here.
+function binaryCandidates(system) {
+    return [
+        path.join(kimiHome(system), 'bin', binary(system)),
+        path.join(system.home, '.local', 'bin', binary(system)),
+        path.join(system.home, '.kimi', 'bin', binary(system))
+    ];
+}
+export const kimi = {
+    id: 'kimi',
+    name: 'Kimi Code',
+    route: '.kimi-plugin',
+    async detect(system) {
+        if (await system.which('kimi')) {
+            return true;
+        }
+        for (const candidate of binaryCandidates(system)) {
+            if (await system.exists(candidate)) {
+                return true;
+            }
+        }
+        return false;
+    },
+    async status(system) {
+        const text = await system.readFile(installedFile(system));
+        if (text === null) {
+            return { installed: false, detail: 'not installed', notes: [] };
+        }
+        const plugins = parseJson(text)?.plugins;
+        if (!Array.isArray(plugins)) {
+            return { installed: null, detail: `could not read ${installedFile(system)}`, notes: [] };
+        }
+        return plugins.some((plugin) => plugin.id === PLUGIN_ID) ?
+            { installed: true, detail: `${PLUGIN_ID} in ${installedFile(system)}`, notes: [] } :
+            { installed: false, detail: 'not installed', notes: [] };
+    },
+    install(system) {
+        return guard(async () => {
+            if (!(await system.which('npx'))) {
+                blocked('npx is not on PATH');
+            }
+            // Only picks the verb: an unreadable store must not stop the install that could repair it.
+            const installed = await kimi.status(system).then((status) => status.installed, () => null);
+            // An explicit --package outranks the npm_config_package an outer `npx -p` exports to us.
+            await mustRun(system, 'npx', ['-y', `--package=${PLUGINS_CLI}`, 'plugins', 'add', REPO, '--target', 'kimi', '--yes'], {
+                env: { DISABLE_TELEMETRY: '1', DO_NOT_TRACK: '1' }
+            });
+            return result('done', `${installed ? 'updated' : 'installed'} ${PLUGIN_ID} in ${kimiHome(system)}`, NEXT);
+        });
+    },
+    async remove(system) {
+        const { installed } = await kimi.status(system);
+        return installed === false ?
+            result('skipped', 'not installed') :
+            result('manual', 'Kimi Code has no shell command to uninstall a plugin', 'Run `/plugins remove postman` inside Kimi Code.');
+    }
+};

package/dist/hosts/opencode.js

@@ -0,0 +1,62 @@
+import path from 'node:path';
+import { OPENCODE_SHIM } from '../source.js';
+import { blocked, guard, removeClone, syncClone } from './shared.js';
+import { result } from './types.js';
+// The install opencode/README.md documents: a clone of this repo next to a
+// one-line plugin file that re-exports opencode/src/index.ts from it.
+const configDir = (system) => path.join(system.env.XDG_CONFIG_HOME || path.join(system.home, '.config'), 'opencode'), cloneDir = (system) => path.join(configDir(system), 'postman-plugin'), shimFile = (system) => path.join(configDir(system), 'plugins', 'postman.ts'), 
+// What OPENCODE_SHIM imports; a directory without it loads nothing.
+shimTarget = (system) => path.join(cloneDir(system), 'opencode', 'src', 'index.ts'), NEXT = 'Restart OpenCode for the change to take effect.';
+export const opencode = {
+    id: 'opencode',
+    name: 'OpenCode',
+    route: 'opencode/package.json',
+    async detect(system) {
+        return (await system.which('opencode')) !== null;
+    },
+    async status(system) {
+        const cloned = await system.exists(cloneDir(system)), loadable = cloned && await system.exists(shimTarget(system)), shim = await system.readFile(shimFile(system));
+        if (loadable && shim === OPENCODE_SHIM) {
+            return { installed: true, detail: `clone at ${cloneDir(system)}`, notes: [] };
+        }
+        const notes = [
+            ...(shim !== null && shim !== OPENCODE_SHIM ? [`${shimFile(system)} has other contents; install will refuse to overwrite it`] : []),
+            ...(cloned && !loadable ? [`${cloneDir(system)} exists but has no opencode/src/index.ts for the loader to import`] : []),
+            ...(loadable && shim === null ? [`${cloneDir(system)} exists but nothing loads it`] : [])
+        ];
+        return { installed: false, detail: 'not installed', notes };
+    },
+    install(system) {
+        return guard(async () => {
+            const shim = await system.readFile(shimFile(system));
+            if (shim !== null && shim !== OPENCODE_SHIM) {
+                blocked(`${shimFile(system)} exists with other contents; move it aside and re-run`);
+            }
+            const action = await syncClone(system, cloneDir(system));
+            if (shim === null) {
+                await system.writeFile(shimFile(system), OPENCODE_SHIM);
+            }
+            return result('done', `${action} ${cloneDir(system)}`, NEXT);
+        });
+    },
+    remove(system) {
+        return guard(async () => {
+            const cloned = await system.exists(cloneDir(system)), shim = await system.readFile(shimFile(system));
+            if (!cloned && shim !== OPENCODE_SHIM) {
+                return result('skipped', 'not installed');
+            }
+            // A loader we didn't write may still import the clone; deleting it would break that file.
+            if (shim !== null && shim !== OPENCODE_SHIM) {
+                blocked(`${shimFile(system)} has other contents and may load ${cloneDir(system)}; move it aside and re-run`);
+            }
+            const removed = cloned ? [cloneDir(system)] : [];
+            // The clone is checked before anything is deleted, so a refusal leaves both in place.
+            await removeClone(system, cloneDir(system));
+            if (shim === OPENCODE_SHIM) {
+                await system.remove(shimFile(system));
+                removed.push(shimFile(system));
+            }
+            return result('done', `removed ${removed.join(' and ')}`, NEXT);
+        });
+    }
+};

package/dist/hosts/shared.js

@@ -0,0 +1,117 @@
+import path from 'node:path';
+import { BRANCH, GIT_URL, REPO, isSameRepo, redact } from '../source.js';
+import { formatCommand } from '../system.js';
+import { result } from './types.js';
+export class StepFailed extends Error {
+    outcome;
+    constructor(outcome) {
+        super(outcome.message);
+        this.outcome = outcome;
+    }
+}
+export function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function lastLines(text, count = 5) {
+    return text.trim().split('\n').slice(-count).join('\n');
+}
+function describeFailure(command, args, exec) {
+    const output = lastLines(exec.stderr) || lastLines(exec.stdout);
+    return `\`${formatCommand(command, args)}\` exited ${exec.code}${output ? `\n${output}` : ''}`;
+}
+/** Runs a state-changing command and throws `StepFailed` if it exits non-zero. */
+export async function mustRun(system, command, args, options) {
+    const exec = await system.run(command, args, options);
+    if (exec.code !== 0) {
+        throw new StepFailed(result('failed', describeFailure(command, args, exec)));
+    }
+}
+/** Runs a read-only JSON listing; throws `StepFailed` if it fails or does not parse. */
+export async function mustProbeJson(system, command, args) {
+    const exec = await system.probe(command, args), parsed = exec.code === 0 ? parseJson(exec.stdout) : null;
+    if (parsed === null) {
+        throw new StepFailed(result('failed', exec.code === 0 ?
+            `\`${formatCommand(command, args)}\` printed output that is not JSON` :
+            describeFailure(command, args, exec)));
+    }
+    return parsed;
+}
+export function blocked(message) {
+    throw new StepFailed(result('blocked', message));
+}
+export function failed(message) {
+    throw new StepFailed(result('failed', message));
+}
+async function cloneOrigin(system, dir) {
+    const exec = await system.probe('git', ['-C', dir, 'remote', 'get-url', 'origin']);
+    return exec.code === 0 ? exec.stdout.trim() : null;
+}
+/** Refuses to touch a directory at our path unless it is a clone of this repo. */
+async function assertOurClone(system, dir) {
+    if (!(await system.exists(path.join(dir, '.git')))) {
+        blocked(`${dir} exists but is not a git clone; move it aside and re-run`);
+    }
+    const origin = await cloneOrigin(system, dir);
+    if (!isSameRepo(origin ?? undefined, REPO)) {
+        blocked(`${dir} is a clone of ${origin ? redact(origin) : 'an unknown remote'}, not ${REPO}; move it aside and re-run`);
+    }
+}
+/** A clone someone switched to another branch is theirs to switch back, not ours. */
+async function assertOnBranch(system, dir) {
+    const exec = await system.probe('git', ['-C', dir, 'symbolic-ref', '--short', 'HEAD']), branch = exec.code === 0 ? exec.stdout.trim() : null;
+    if (branch !== BRANCH) {
+        blocked(`${dir} is on ${branch ? `branch ${branch}` : 'a detached HEAD'}, not ${BRANCH}; run \`git -C ${dir} switch ${BRANCH}\` and re-run`);
+    }
+}
+async function assertGit(system) {
+    if (!(await system.which('git'))) {
+        blocked('git is not on PATH');
+    }
+}
+/** Clones this repo into `dir`, or fast-forwards an existing clone of it. */
+export async function syncClone(system, dir) {
+    await assertGit(system);
+    if (await system.exists(dir)) {
+        await assertOurClone(system, dir);
+        await assertOnBranch(system, dir);
+        await mustRun(system, 'git', ['-C', dir, 'pull', '--ff-only', 'origin', BRANCH]);
+        return 'updated';
+    }
+    await mustRun(system, 'git', ['clone', '--depth', '1', '--branch', BRANCH, GIT_URL, dir]);
+    return 'cloned';
+}
+export async function removeClone(system, dir) {
+    if (!(await system.exists(dir))) {
+        return;
+    }
+    await assertGit(system);
+    await assertOurClone(system, dir);
+    await assertOnBranch(system, dir);
+    const changes = await system.probe('git', ['-C', dir, 'status', '--porcelain']);
+    if (changes.code !== 0 || changes.stdout.trim()) {
+        blocked(`${dir} has local changes; commit or discard them, or delete it yourself`);
+    }
+    // A clean tree can still hold commits that exist nowhere else.
+    const ahead = await system.probe('git', ['-C', dir, 'rev-list', '--count', `origin/${BRANCH}..HEAD`]);
+    if (ahead.code !== 0 || ahead.stdout.trim() !== '0') {
+        blocked(`${dir} has commits that aren't on origin/${BRANCH}; push or drop them, or delete it yourself`);
+    }
+    await system.remove(dir);
+}
+/** Converts a thrown `StepFailed` into its result; anything else is an unexpected failure. */
+export async function guard(step) {
+    try {
+        return await step();
+    }
+    catch (error) {
+        if (error instanceof StepFailed) {
+            return error.outcome;
+        }
+        return result('failed', error instanceof Error ? error.message : String(error));
+    }
+}

package/dist/hosts/types.js

@@ -0,0 +1,3 @@
+export function result(outcome, message, next) {
+    return next ? { outcome, message, next } : { outcome, message };
+}

package/dist/run.js

@@ -0,0 +1,120 @@
+export const EXIT = { ok: 0, failed: 1, usage: 2, manual: 3 };
+const FAILED = ['failed', 'blocked'];
+function padEnd(text, width) {
+    return text + ' '.repeat(Math.max(1, width - text.length));
+}
+function stateLabel(status) {
+    if (status.installed === null) {
+        return 'unknown';
+    }
+    return status.installed ? 'installed' : 'not installed';
+}
+function printStatuses(system, targets, width) {
+    for (const { host, status } of targets) {
+        system.log(`  ${padEnd(host.name, width)}${padEnd(stateLabel(status), 15)}${status.installed === false ? '' : status.detail}`.trimEnd());
+        for (const note of status.notes) {
+            system.log(`  ${' '.repeat(width)}note: ${note}`);
+        }
+    }
+}
+function printResult(system, { result }) {
+    system.log(`  ${result.outcome}: ${result.message.replaceAll('\n', '\n    ')}`);
+    if (result.next) {
+        system.log(`  next: ${result.next}`);
+    }
+}
+async function readStatus(system, host) {
+    try {
+        return await host.status(system);
+    }
+    catch (error) {
+        return { installed: null, detail: `could not read its state: ${error instanceof Error ? error.message : String(error)}`, notes: [] };
+    }
+}
+async function execute(system, command, host) {
+    try {
+        const outcome = await host[command](system);
+        if (outcome.outcome !== 'done' || system.dryRun) {
+            return outcome;
+        }
+        // An agent CLI that exits 0 without doing the work is caught here, not reported as done.
+        const after = await readStatus(system, host), expected = command === 'install';
+        if (after.installed === null) {
+            return { outcome: 'failed', message: `${outcome.message}, but it could not be confirmed: ${after.detail}` };
+        }
+        return after.installed === expected ?
+            outcome :
+            { outcome: 'failed', message: `${outcome.message}, but ${host.name} still reports it as ${expected ? 'not installed' : 'installed'}` };
+    }
+    catch (error) {
+        return { outcome: 'failed', message: error instanceof Error ? error.message : String(error) };
+    }
+}
+function joinNames(hosts) {
+    const names = hosts.map((host) => host.name);
+    return names.length > 1 ? `${names.slice(0, -1).join(', ')} and ${names.at(-1)}` : names.join('');
+}
+/** Returns the process exit code. */
+export async function run(system, hosts, options) {
+    const requested = options.agents.length ? hosts.filter((host) => options.agents.includes(host.id)) : [...hosts], width = Math.max(...hosts.map((host) => host.name.length)) + 2, reports = [], targets = [];
+    for (const host of requested) {
+        let detected;
+        try {
+            detected = await host.detect(system);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            reports.push({ host, result: { outcome: 'failed', message: `could not check whether ${host.name} is here: ${reason}` } });
+            continue;
+        }
+        if (detected) {
+            targets.push({ host, status: await readStatus(system, host) });
+        }
+        else if (options.agents.length) {
+            reports.push({ host, result: { outcome: 'blocked', message: `${host.name} was not found on this machine` } });
+        }
+    }
+    if (!targets.length) {
+        system.log(options.agents.length ?
+            'None of the requested agents was found.' :
+            `No supported coding agent found. Supported: ${joinNames(requested)}.`);
+        reports.forEach((report) => system.log(`  ${report.result.message}`));
+        // Nothing to remove is a clean remove; nothing to install into is not a successful install.
+        return options.command === 'install' || (options.command === 'remove' && reports.length) ? EXIT.failed : EXIT.ok;
+    }
+    // "Found:" over "not installed" read to agents as "not found"; the header says both things.
+    system.log(`Found ${targets.length} coding agent${targets.length === 1 ? '' : 's'}. Postman in each:`);
+    printStatuses(system, targets, width);
+    reports.forEach((report) => system.log(`  ${padEnd(report.host.name, width)}${report.result.message}`));
+    if (options.command === 'status') {
+        return EXIT.ok;
+    }
+    // Every detected adapter gets the command, even one whose status says "not installed":
+    // remove also clears duplicates and half-finished installs that status doesn't count.
+    const command = options.command;
+    if (!options.yes && !system.dryRun) {
+        const verb = command === 'install' ? 'install or update Postman in' : 'remove Postman from', names = joinNames(targets.map((target) => target.host));
+        if (!options.isTTY) {
+            system.log(`\nNothing changed: there is no terminal to confirm in. To ${verb} ${names}, re-run with --yes (add --agent <id> for only some).`);
+            return EXIT.usage;
+        }
+        if (!(await options.confirm(`\n${verb[0].toUpperCase()}${verb.slice(1)} ${names}? [Y/n] `))) {
+            system.log('Cancelled.');
+            return EXIT.failed;
+        }
+    }
+    for (const { host } of targets) {
+        system.log(`\n${host.name}`);
+        const report = { host, result: await execute(system, command, host) };
+        printResult(system, report);
+        reports.push(report);
+    }
+    system.log(`\n${system.dryRun ? 'Dry run, nothing changed' : 'Summary'}:`);
+    for (const { host, result } of reports) {
+        system.log(`  ${padEnd(host.name, width)}${padEnd(result.outcome, 9)}${result.message.split('\n')[0]}`);
+    }
+    if (reports.some(({ result }) => FAILED.includes(result.outcome))) {
+        return EXIT.failed;
+    }
+    return reports.some(({ result }) => result.outcome === 'manual') ? EXIT.manual : EXIT.ok;
+}

package/dist/source.js

@@ -0,0 +1,28 @@
+/** Where every host's copy of the plugin comes from. The npm package carries no skills. */
+export const REPO = 'postmanlabs/postman-plugin';
+export const GIT_URL = `https://github.com/${REPO}.git`;
+/** The branch every clone this installer makes tracks. */
+export const BRANCH = 'main';
+/** Must stay byte-identical to the shim in opencode/README.md; test/routes.test.js enforces it. */
+export const OPENCODE_SHIM = "export { default } from '../postman-plugin/opencode/src/index.ts';\n";
+/** Pinned: this third-party CLI writes Kimi's plugin store for us, and an unpinned npx would run whatever is latest. */
+export const PLUGINS_CLI = 'plugins@1.3.4';
+// A git transport (not `file://`, which names a local path), optional user-info, then
+// GitHub's host and its `/`, or the scp-style `git@github.com:` form with no scheme.
+const GITHUB_PREFIX = /^(?:(?:https?|ssh|git|git\+ssh|ssh\+git|git\+https):\/\/)?(?:[^@/]+@)?github\.com[:/]/, 
+// User-info in a URL, or before an scp-style `host:path`; the conventional `git@` is kept.
+URL_USER_INFO = /^([a-z][a-z+.-]*:\/\/)(?!git@)[^@/]+@/i, SCP_USER_INFO = /^(?!git@)[^@/:]+@(?=[^/:]+:)/;
+function normalize(source) {
+    return source.trim().toLowerCase()
+        .replace(GITHUB_PREFIX, '')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/, '');
+}
+/** True for `owner/repo`, or any HTTPS, SSH or git URL of it, with or without `.git`. */
+export function isSameRepo(source, repo) {
+    return typeof source === 'string' && normalize(source) === repo.toLowerCase();
+}
+/** Strips a URL's user-info, where a token would be, so a source can be printed. */
+export function redact(source) {
+    return source.replace(URL_USER_INFO, '$1').replace(SCP_USER_INFO, '');
+}

package/dist/system.js

@@ -0,0 +1,113 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+// 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'];
+// Nothing is ever written to a command's stdin, so it gets EOF at once: a CLI that
+// stops to ask something fails instead of waiting forever for an answer.
+const STDIO = ['ignore', 'pipe', 'pipe'];
+// npm installs agent CLIs on Windows as `.cmd` shims, which only cmd.exe can start.
+function needsShell(file) {
+    return /\.(cmd|bat)$/i.test(file);
+}
+function quoteForCmd(arg) {
+    return /^[\w@./:=-]+$/.test(arg) ? arg : `"${arg}"`;
+}
+function execute(file, args, env) {
+    return new Promise((resolve) => {
+        const shell = needsShell(file), child = shell ?
+            spawn(quoteForCmd(file), args.map(quoteForCmd), { env, shell: true, stdio: STDIO, windowsHide: true }) :
+            spawn(file, args, { env, stdio: STDIO, windowsHide: true });
+        let stdout = '', stderr = '';
+        // Decodes across chunks, so a multi-byte character split between two isn't mangled.
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        child.on('error', (error) => resolve({ code: 127, stdout, stderr: stderr + error.message }));
+        child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    });
+}
+export function formatCommand(command, args) {
+    return [command, ...args].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;
+    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)) {
+            for (const extension of extensions) {
+                const candidate = path.join(dir, command + extension);
+                try {
+                    await fs.access(candidate, fs.constants.X_OK);
+                    if ((await fs.stat(candidate)).isFile()) {
+                        return candidate;
+                    }
+                }
+                catch {
+                    // Not in this directory.
+                }
+            }
+        }
+        return null;
+    }
+    async function resolve(command) {
+        return (await which(command)) || command;
+    }
+    return {
+        home: os.homedir(),
+        platform,
+        env,
+        dryRun,
+        which,
+        async exists(file) {
+            try {
+                await fs.access(file);
+                return true;
+            }
+            catch (error) {
+                if (ABSENT.includes(error.code ?? '')) {
+                    return false;
+                }
+                throw error;
+            }
+        },
+        async readFile(file) {
+            try {
+                return await fs.readFile(file, 'utf8');
+            }
+            catch (error) {
+                if (ABSENT.includes(error.code ?? '')) {
+                    return null;
+                }
+                throw error;
+            }
+        },
+        async probe(command, args) {
+            return execute(await resolve(command), args, env);
+        },
+        async run(command, args, options = {}) {
+            log(`  $ ${formatCommand(command, args)}`);
+            if (dryRun) {
+                return { code: 0, stdout: '', stderr: '' };
+            }
+            return execute(await resolve(command), args, { ...env, ...options.env });
+        },
+        async writeFile(file, content) {
+            log(`  write ${file}`);
+            if (!dryRun) {
+                await fs.mkdir(path.dirname(file), { recursive: true });
+                await fs.writeFile(file, content);
+            }
+        },
+        async remove(file) {
+            log(`  remove ${file}`);
+            if (!dryRun) {
+                await fs.rm(file, { recursive: true, force: true });
+            }
+        },
+        log
+    };
+}

package/package.json

@@ -1,11 +1,50 @@
 {
-  "version": "0.0.0",
-  "description": "Namespace placeholder. Real releases ship from CI via OIDC Trusted Publishing.",
-  "license": "Apache-2.0",
-  "private": false,
   "name": "@postman/postman-plugin",
+  "version": "0.1.0",
+  "description": "Installs the Postman plugin into every supported coding agent on this machine.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Postman",
+    "email": "postman-plugins@postman.com",
+    "url": "https://github.com/postmanlabs"
+  },
+  "homepage": "https://github.com/postmanlabs/postman-plugin#install",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/postmanlabs/postman-plugin.git"
+    "url": "git+https://github.com/postmanlabs/postman-plugin.git",
+    "directory": "installer"
+  },
+  "bugs": "https://github.com/postmanlabs/postman-plugin/issues",
+  "keywords": [
+    "postman",
+    "claude-code",
+    "codex",
+    "cursor",
+    "kimi",
+    "opencode",
+    "agent-plugin"
+  ],
+  "bin": {
+    "postman-plugin": "dist/cli.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build && node scripts/pack-docs.js stage",
+    "postpack": "node scripts/pack-docs.js clean",
+    "test": "npm run build && node --test test/*.test.js"
+  },
+  "devDependencies": {
+    "@types/node": "24.5.2",
+    "typescript": "5.9.2"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }