@postman/postman-plugin 0.2.2 → 0.3.0

package/README.md

@@ -85,8 +85,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
 
@@ -168,15 +174,33 @@ 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.
 
+### Develop against simulated dependencies
+
+The [`api-simulation`](https://github.com/postmanlabs/postman-plugin/blob/main/skills/api-simulation/) skill is the local loop for a
+service change: find every dependency the service calls, mock each one (reusing
+the owning team's mock when they publish one), serve them on one port from one
+`.sim.yaml`, run the real service against them, test, and push. 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 +209,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/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;
+}

package/dist/hosts/opencode.js

@@ -1,12 +1,262 @@
+import { createHash } from 'node:crypto';
 import path from 'node:path';
-import { OPENCODE_SHIM } from '../source.js';
-import { blocked, guard, removeClone, syncClone } from './shared.js';
+import { OPENCODE_MINIMUM, OPENCODE_SHIM, OPENCODE_SPEC, REPO, isSameRepo, redact } from '../source.js';
+import { parseJsonc, withoutArrayString } from './opencode-config.js';
+import { assertCloneRemovable, blocked, failed, guard, mustRun, removeClone } 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.';
+// OpenCode 1 lists its plugins under `plugin`, OpenCode 2 under `plugins`. OpenCode 2's `plugin add` and `plugin remove`
+// edit the first of these that exists in the config directory (`resolveConfigPath` in its packages/cli).
+const KEYS = ['plugin', 'plugins'], CONFIG_FILES = ['opencode.json', 'opencode.jsonc', path.join('.opencode', 'opencode.json'), path.join('.opencode', 'opencode.jsonc')], samePath = (a, b) => path.relative(a, b) === '', NEXT = 'Restart OpenCode for the change to take effect.', 
+// Installs another spec instead, such as a copy of a change before it merges.
+SPEC_VARIABLE = 'POSTMAN_PLUGIN_OPENCODE_SPEC', configDir = (system) => path.join(system.env.XDG_CONFIG_HOME || path.join(system.home, '.config'), 'opencode'), 
+// OpenCode 2 reads only OPENCODE_CONFIG_DIR when it is set (`Global` in its packages/util/src/global.ts); OpenCode 1
+// reads it as well as the default directory. `major` is null where an entry anywhere matters, as for remove.
+configDirs = (system, major) => (major !== null && major >= 2 && system.env.OPENCODE_CONFIG_DIR ?
+    [system.env.OPENCODE_CONFIG_DIR] :
+    [system.env.OPENCODE_CONFIG_DIR, configDir(system)])
+    .filter((dir) => Boolean(dir))
+    .filter((dir, at, dirs) => dirs.findIndex((other) => samePath(other, dir)) === at), 
+// OpenCode 2 keeps one cached copy of each git plugin here, named `git-<slug>-<first 12 hex of sha256(spec)>`.
+cachedCopy = (system, spec) => path.join(system.env.XDG_CACHE_HOME || path.join(system.home, '.cache'), 'opencode', 'npm', `git-${gitSlug(spec)}-${createHash('sha256').update(spec).digest('hex').slice(0, 12)}`), 
+// `plugin add` and `plugin remove` act on OPENCODE_CONFIG_DIR when it is set, wherever our entry was found.
+// Compared as paths, not strings: Windows spells the same directory with either slash, in any case.
+inConfigOf = (system, entry) => (system.env.OPENCODE_CONFIG_DIR && !samePath(system.env.OPENCODE_CONFIG_DIR, entry.dir) ?
+    { env: { OPENCODE_CONFIG_DIR: entry.dir } } :
+    undefined), 
+// The older install: a clone of this repo next to a one-line loader file that imports it.
+cloneDir = (system) => path.join(configDir(system), 'postman-plugin'), shimFile = (system) => path.join(configDir(system), 'plugins', 'postman.ts'), shimTarget = (system) => path.join(cloneDir(system), 'opencode', 'src', 'index.ts');
+/** OpenCode 2's name for a git spec's cache: its last path segment, as `gitSlug` in packages/util/src/npm.ts derives it. */
+function gitSlug(spec) {
+    let target = spec.split('#')[0];
+    try {
+        target = decodeURIComponent(target);
+    }
+    catch {
+        // OpenCode falls back to the undecoded spec too.
+    }
+    return target.replace(/\.git$/i, '').split(/[/:\\]/).at(-1)?.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'repository';
+}
+/** What this run installs: `OPENCODE_SPEC`, or the spec POSTMAN_PLUGIN_OPENCODE_SPEC names. */
+const specToInstall = (system) => system.env[SPEC_VARIABLE] || OPENCODE_SPEC;
+/** The plugin's repository through `github:` or a git URL at any ref or range, or the spec POSTMAN_PLUGIN_OPENCODE_SPEC installs. */
+function isOurSpec(system, spec) {
+    const bare = spec.split('#')[0];
+    if (spec === system.env[SPEC_VARIABLE]) {
+        return true;
+    }
+    return bare.startsWith('github:') ? isSameRepo(bare.slice('github:'.length), REPO) : isSameRepo(bare.replace(/^git\+/, ''), REPO);
+}
+/** True when the dotted version `found` precedes `minimum`. */
+function isBefore(found, minimum) {
+    const differing = found.findIndex((part, at) => part !== minimum[at]);
+    return differing !== -1 && found[differing] < minimum[differing];
+}
+/** The release `opencode` is, refusing one older than the first of its major that installs Postman with `opencode plugin`. */
+async function installableVersion(system) {
+    const probe = await system.probe('opencode', ['--version']), match = probe.stdout.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (probe.code !== 0 || !match) {
+        return failed('could not read the version `opencode --version` prints');
+    }
+    const found = match.slice(1).map(Number), major = found[0], minimum = OPENCODE_MINIMUM[major], older = minimum !== undefined && isBefore(found, minimum);
+    if (major < 1 || older) {
+        return blocked(`OpenCode ${match[0]} is older than ${(minimum ?? OPENCODE_MINIMUM[1]).join('.')}, the first ${major}.x release that installs Postman with \`opencode plugin\`; update OpenCode and re-run`);
+    }
+    return { major, text: match[0] };
+}
+/** Our entries in OpenCode's global config, and the config files that could not be read. */
+async function configured(system, major) {
+    const entries = [], unreadable = [], jsoncLists = new Set();
+    // OpenCode 1 reads only the files directly in a config directory, never its `.opencode/` copies.
+    const names = major !== null && major < 2 ? CONFIG_FILES.slice(0, 2) : CONFIG_FILES;
+    for (const [dir, file] of configDirs(system, major).flatMap((dir) => names.map((name) => [dir, path.join(dir, name)]))) {
+        const text = await system.readFile(file);
+        if (text === null) {
+            continue;
+        }
+        const config = parseJsonc(text);
+        if (!config || typeof config !== 'object') {
+            unreadable.push(file);
+            continue;
+        }
+        for (const key of KEYS) {
+            const list = config[key];
+            for (const item of Array.isArray(list) ? list : []) {
+                const form = typeof item === 'string' ? 'string' : Array.isArray(item) ? 'tuple' : 'object', spec = form === 'string' ? item : form === 'tuple' ? item[0] : item?.package;
+                if (typeof spec === 'string' && isOurSpec(system, spec)) {
+                    entries.push({ dir, file, key, spec, form, shadowed: false });
+                }
+            }
+        }
+        if (samePath(file, path.join(dir, CONFIG_FILES[1])) && Array.isArray(config.plugin)) {
+            jsoncLists.add(dir);
+        }
+    }
+    // OpenCode 1 merges its global opencode.json and then opencode.jsonc with a merge that replaces arrays.
+    for (const entry of entries) {
+        entry.shadowed = entry.key === 'plugin' && samePath(entry.file, path.join(entry.dir, CONFIG_FILES[0])) && jsoncLists.has(entry.dir);
+    }
+    return { entries, unreadable };
+}
+async function readableEntries(system, major) {
+    const { entries, unreadable } = await configured(system, major);
+    return unreadable.length ? failed(`${unreadable[0]} is not valid JSON; fix it and re-run`) : entries;
+}
+async function legacyState(system) {
+    const cloned = await system.exists(cloneDir(system)), shim = await system.readFile(shimFile(system));
+    return { cloned, shim, loadable: cloned && await system.exists(shimTarget(system)) };
+}
+/** Throws `blocked` when the older install cannot be deleted whole, changing nothing. */
+async function preflightLegacy(system) {
+    const { cloned, shim } = await legacyState(system);
+    // A loader we didn't write may still import the clone; deleting it would break that file.
+    if (cloned && shim !== null && shim !== OPENCODE_SHIM) {
+        blocked(`${shimFile(system)} has other contents and may load ${cloneDir(system)}; move it aside and re-run`);
+    }
+    await assertCloneRemovable(system, cloneDir(system));
+}
+/** Deletes the clone and loader of the older install, refusing anything that is not ours. */
+async function removeLegacy(system) {
+    const { cloned, shim } = await legacyState(system);
+    if (!cloned && shim !== OPENCODE_SHIM) {
+        return [];
+    }
+    // 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 removed;
+}
+/** The file OpenCode 2's `plugin add` and `plugin remove` edit in `dir`; `remove` exits 0 when the entry is in another one. */
+async function editedFile(system, dir) {
+    for (const name of CONFIG_FILES) {
+        if (await system.exists(path.join(dir, name))) {
+            return path.join(dir, name);
+        }
+    }
+    return path.join(dir, CONFIG_FILES[0]);
+}
+/** The major of the `opencode` on PATH, or null when it can't say; only OpenCode 2 has `plugin remove`. */
+async function cliMajor(system) {
+    const probe = await system.probe('opencode', ['--version']), match = probe.code === 0 ? probe.stdout.match(/(\d+)\.\d+\.\d+/) : null;
+    return match ? Number(match[1]) : null;
+}
+async function removedByOpenCode(system, entry) {
+    return entry.key === 'plugins' && entry.form !== 'tuple' && samePath(entry.file, await editedFile(system, entry.dir));
+}
+/** The config without the entry, for an entry OpenCode has no command to remove; refuses one it can't take out cleanly. */
+async function withoutEntry(system, entry) {
+    const text = await system.readFile(entry.file), edited = text === null || entry.form !== 'string' ? null : withoutArrayString(text, entry.key, entry.spec);
+    return edited ?? blocked(`could not remove ${redact(entry.spec)} from ${entry.file} without rewriting it; delete that entry yourself and re-run`);
+}
+/**
+ * The file OpenCode's add writes. OpenCode 1's `plugin --global` writes its default config directory, whatever
+ * OPENCODE_CONFIG_DIR says, and there the first of opencode.json and opencode.jsonc that exists (`patchOne` in its
+ * plugin/install.ts).
+ */
+async function destination(system, version, entry) {
+    if (version.major >= 2) {
+        return editedFile(system, entry.dir);
+    }
+    const json = path.join(configDir(system), CONFIG_FILES[0]), jsonc = path.join(configDir(system), CONFIG_FILES[1]);
+    return (await system.exists(json)) || !(await system.exists(jsonc)) ? json : jsonc;
+}
+/** OpenCode 1 adds to opencode.json, but ignores that file's list when the opencode.jsonc beside it has one of its own. */
+async function assertAddIsRead(system, version) {
+    const jsonc = path.join(configDir(system), CONFIG_FILES[1]);
+    if (version.major >= 2 || !(await system.exists(path.join(configDir(system), CONFIG_FILES[0])))) {
+        return;
+    }
+    const config = parseJsonc((await system.readFile(jsonc)) ?? '{}');
+    if (Array.isArray(config?.plugin)) {
+        blocked(`OpenCode 1 would add Postman to ${path.join(configDir(system), CONFIG_FILES[0])}, but reads only the \`plugin\` list in ${jsonc}; add \`${redact(specToInstall(system))}\` to that list yourself, or merge the two files, and re-run`);
+    }
+}
+/** Refuses an entry OpenCode's add would not write back to: it would register a second copy elsewhere instead. */
+async function assertLands(system, version, entry) {
+    const target = await destination(system, version, entry);
+    if (!samePath(entry.file, target)) {
+        blocked(`${entry.file} registers ${redact(entry.spec)}, but OpenCode would write to ${target}; move the entry, with any options, there and re-run`);
+    }
+}
+/** Refetches a git spec the entry already names. */
+async function refreshInPlace(system, version, entry) {
+    await assertLands(system, version, entry);
+    await addFresh(system, version, entry.spec, inConfigOf(system, entry), true);
+}
+/** Adds `spec`, then takes out the entry it supersedes; a refusal to take it out comes before anything is added. */
+async function replaceEntry(system, version, entry, spec) {
+    // OpenCode 1 would add the new spec to another file and leave the old file's list overriding it.
+    if (version.major < 2) {
+        await assertLands(system, version, entry);
+    }
+    const byOpenCode = version.major >= 2 && await removedByOpenCode(system, entry);
+    if (!byOpenCode) {
+        await withoutEntry(system, entry);
+    }
+    // OpenCode 1 replaces an entry for the same package in place only when forced; unforced, it changes nothing.
+    await addFresh(system, version, spec, inConfigOf(system, entry), true);
+    // Either major may have replaced it in place already.
+    if (!(await configured(system, version.major)).entries.some((left) => left.spec === entry.spec && left.key === entry.key && samePath(left.file, entry.file))) {
+        return;
+    }
+    if (byOpenCode) {
+        await mustRun(system, 'opencode', ['plugin', 'remove', entry.spec], inConfigOf(system, entry));
+    }
+    else {
+        await system.writeFile(entry.file, await withoutEntry(system, entry));
+    }
+}
+/** OpenCode 2 fetches into `.staging-*` and renames it to a numeric generation only once the fetch succeeds (packages/util/src/npm.ts). */
+async function isComplete(system, cache) {
+    return (await system.readDir(cache)).some((entry) => /^\d+$/.test(entry));
+}
+/**
+ * OpenCode 2 caches a git plugin by its spec and `plugin add` reuses the cache, even one an earlier
+ * `plugin remove` left behind, so a newer commit only arrives when the cached copy is gone; `plugin update`
+ * would do it but needs OpenCode's background service, which a second instance or a cold start answers
+ * wrongly. The copy is moved aside, not deleted, so a failed fetch leaves the plugin as it was. OpenCode 1
+ * re-resolves a git spec on every add; `force` makes it replace an entry for the same package in place.
+ */
+async function addFresh(system, version, spec, options, force = false) {
+    if (version.major < 2) {
+        await mustRun(system, 'opencode', ['plugin', '--global', ...(force ? ['--force'] : []), spec], options);
+        return;
+    }
+    const copy = cachedCopy(system, spec), previous = `${copy}.previous`;
+    // A run stopped after setting the copy aside left the working one only under `.previous`, beside nothing or an unfinished fetch.
+    if (!(await isComplete(system, copy)) && await isComplete(system, previous)) {
+        await system.remove(copy);
+        await system.rename(previous, copy);
+    }
+    const cached = await isComplete(system, copy);
+    if (cached) {
+        await system.remove(previous);
+        await system.rename(copy, previous);
+    }
+    try {
+        await mustRun(system, 'opencode', ['plugin', 'add', spec], options);
+    }
+    catch (error) {
+        if (cached) {
+            await system.remove(copy);
+            await system.rename(previous, copy);
+        }
+        throw error;
+    }
+    if (cached) {
+        await system.remove(previous);
+    }
+}
+function summary(action, spec, removed) {
+    return `${action} ${spec}${removed.length ? `; removed the older install at ${removed.join(' and ')}` : ''}`;
+}
 export const opencode = {
     id: 'opencode',
     name: 'OpenCode',
@@ -15,47 +265,78 @@ export const opencode = {
         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`] : [])
+        const { entries, unreadable } = await configured(system, await cliMajor(system)), { cloned, shim, loadable } = await legacyState(system), legacy = loadable && shim === OPENCODE_SHIM, notes = [
+            ...(legacy ? [`${cloneDir(system)} loads the same skills and will be removed`] : []),
+            ...(shim !== null && shim !== OPENCODE_SHIM ? [`${shimFile(system)} has other contents; install will refuse to remove it`] : []),
+            ...(cloned && !loadable ? [`${cloneDir(system)} exists but has no opencode/src/index.ts for a loader to import`] : [])
         ];
-        return { installed: false, detail: 'not installed', notes };
+        const read = entries.filter((entry) => !entry.shadowed), shadowed = entries.filter((entry) => entry.shadowed).map((entry) => `${entry.file} registers ${redact(entry.spec)}, but OpenCode 1 reads the opencode.jsonc beside it instead`);
+        if (read.length) {
+            return { installed: true, detail: `${redact(read[0].spec)} in ${read[0].file}`, notes: [...shadowed, ...notes] };
+        }
+        if (shadowed.length) {
+            return { installed: false, detail: 'not loaded', notes: [...shadowed, ...notes] };
+        }
+        if (unreadable.length) {
+            return { installed: null, detail: `could not read ${unreadable[0]}`, notes };
+        }
+        return legacy ?
+            { installed: true, detail: `clone at ${cloneDir(system)}`, notes } :
+            { 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 version = await installableVersion(system), entries = await readableEntries(system, version.major), spec = specToInstall(system), entry = entries[0];
+            // Each would load the same skills, and refreshing one would leave the others loading the rest.
+            if (entries.length > 1) {
+                blocked(`found ${entries.length} entries for Postman (${entries.map((found) => `${redact(found.spec)} in ${found.file}`).join(', ')}); keep one, with any options, and re-run`);
+            }
+            if (entry?.shadowed) {
+                blocked(`${entry.file} registers ${redact(entry.spec)}, but OpenCode 1 reads only the \`plugin\` list in the opencode.jsonc beside it; move the entry there and re-run`);
+            }
+            // Both copies would load the same skills, so an older install that cannot be deleted whole stops us before the new one goes in.
+            await preflightLegacy(system);
+            if (!entry) {
+                await assertAddIsRead(system, version);
+                await addFresh(system, version, spec);
+                return result('done', summary('installed', redact(spec), await removeLegacy(system)), NEXT);
+            }
+            // An entry under the other major's list is moved over: refreshing it would add a second one under this major's.
+            const refresh = entry.spec === spec && entry.key === (version.major >= 2 ? 'plugins' : 'plugin');
+            if (refresh) {
+                await refreshInPlace(system, version, entry);
             }
-            const action = await syncClone(system, cloneDir(system));
-            if (shim === null) {
-                await system.writeFile(shimFile(system), OPENCODE_SHIM);
+            else {
+                await replaceEntry(system, version, entry, spec);
             }
-            return result('done', `${action} ${cloneDir(system)}`, NEXT);
+            return result('done', summary(refresh ? 'updated' : `replaced ${redact(entry.spec)} under \`${entry.key}\` with`, redact(spec), await removeLegacy(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) {
+            const entries = await readableEntries(system, null), { cloned, shim } = await legacyState(system);
+            if (!entries.length && !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`);
+            // Everything that can refuse is checked before anything is removed, so a refusal leaves no half-removed state.
+            await preflightLegacy(system);
+            const hasRemove = ((await cliMajor(system)) ?? 0) >= 2, byOpenCode = await Promise.all(entries.map(async (entry) => hasRemove && removedByOpenCode(system, entry)));
+            for (const [at, entry] of entries.entries()) {
+                if (!byOpenCode[at]) {
+                    await withoutEntry(system, entry);
+                }
             }
-            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));
+            const removed = [];
+            for (const [at, entry] of entries.entries()) {
+                if (byOpenCode[at]) {
+                    await mustRun(system, 'opencode', ['plugin', 'remove', entry.spec], inConfigOf(system, entry));
+                }
+                else {
+                    await system.writeFile(entry.file, await withoutEntry(system, entry));
+                }
+                removed.push(redact(entry.spec));
             }
+            removed.push(...await removeLegacy(system));
             return result('done', `removed ${removed.join(' and ')}`, NEXT);
         });
     }

package/dist/hosts/shared.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { BRANCH, GIT_URL, REPO, isSameRepo, redact } from '../source.js';
+import { BRANCH, GIT_URL, REPO, isSameRepo, redact, redactText } from '../source.js';
 import { formatCommand } from '../system.js';
 import { result } from './types.js';
 export class StepFailed extends Error {
@@ -21,7 +21,7 @@ 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);
+    const output = redactText(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. */
@@ -93,7 +93,8 @@ export async function syncClone(system, dir) {
     await mustRun(system, 'git', ['clone', '--depth', '1', '--branch', BRANCH, GIT_URL, dir]);
     return 'cloned';
 }
-export async function removeClone(system, dir) {
+/** Throws `blocked` unless `dir` is absent or a clean clone of this repo on `main` with nothing unpushed. */
+export async function assertCloneRemovable(system, dir) {
     if (!(await system.exists(dir))) {
         return;
     }
@@ -109,6 +110,12 @@ export async function removeClone(system, dir) {
     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`);
     }
+}
+export async function removeClone(system, dir) {
+    if (!(await system.exists(dir))) {
+        return;
+    }
+    await assertCloneRemovable(system, dir);
     await system.remove(dir);
 }
 /** Converts a thrown `StepFailed` into its result; anything else is an unexpected failure. */