universal-plugin 0.16.3 → 0.17.1

package/skills/marketplace/references/update.md

@@ -0,0 +1,75 @@
+# Route: update
+
+Change one entry the catalogs already list, and keep everything else about it. This is the route
+for an entry that is listed and wrong or stale: a new source, a moved pin, one field.
+
+`add --force` is not a substitute. It replaces the entry with what `add` can derive, so it needs
+`--owner` and the other `add` inputs again, and it drops what it cannot derive: `category`,
+`author`, any field a curator wrote by hand. Use `update` whenever the entry already exists.
+
+An entry that is not listed yet is `add`'s (`references/add.md`). A plugin this repository holds is
+re-derived by `init` or `plugin build`; reach for `update` there only for a field neither derives,
+such as `category`.
+
+## 1. Work out the change
+
+Name the entry by the name the catalogs list it under, then say what changes:
+
+| The user wants | Flags |
+| --- | --- |
+| Move the entry to another source, such as the `github` shorthand to an https `url` | `--source <spec>` |
+| Bump or change a pin | `--ref <branch-or-tag>`, `--sha <commit>` |
+| Change one field | `--description`, `--version`, `--homepage`, `--repository`, `--license`, `--keywords`, `--category` |
+| Remove a field or a pin | `--unset <field>`, repeatable; `--unset ref`, `--unset sha` |
+
+`--source` is read exactly the way `add` reads its spec, so the same collisions apply: write
+`./plugins/alpha` or pass `--path` for a directory, and `--npm`, `--github`, `--url`, and `--subdir`
+shape it the same way. A `<plugin>@<marketplace>` spec is refused; copying an entry is `add`'s job.
+
+Two pin rules to state to the user before running:
+
+- **A new git source keeps the old pin** unless `--ref` or `--sha` comes with it. Switching how a
+  repository is reached does not move which commit installs.
+- **`--ref` alone keeps an existing `sha`.** A sha pinned for the old ref then names a commit the
+  new one has moved past. When bumping a ref, pass `--unset sha` too, or pass the new `--sha`.
+
+## 2. Preview, then write
+
+```bash
+node scripts/update.mjs repobuddy --source https://github.com/cyberuni/repobuddy.git --dry-run
+```
+
+Resolve that path against this skill's own directory; `npx universal-plugin marketplace update` is
+the fallback. Run `--dry-run` first and show the plan. The command never prompts.
+
+| Status | Means |
+| --- | --- |
+| `updated` | the entry changed |
+| `unchanged` | already says exactly this |
+| `planned` | `--dry-run` only |
+| `skipped` | that catalog is missing, does not list the entry, or its runtime cannot install the new source; the reason says which |
+
+With no target flags all four catalogs are selected, so a `skipped` row for a catalog that never
+listed the entry is normal. Report every skip with its reason anyway. Two deserve a sentence each:
+
+- **A runtime that cannot install the new source keeps its old entry.** Moving an entry to `npm`
+  leaves Copilot CLI and Cursor on the source they had. Say so; the user may want those entries
+  removed, which is a hand decision this skill does not make.
+- **A shield catalog may appear.** Copilot CLI and Cursor read the Claude catalog when they have none
+  of their own. If the new source would break them there, their own catalog is written without the
+  entry, as `add` does. Tell the user the file appeared and why.
+
+The Codex catalog takes only `version` and `category` of the field flags, because that is all its
+entries carry. A description changed everywhere else is not missing from Codex by mistake.
+
+## 3. Validate
+
+The command checks every catalog it plans to write, with the same checks as `validate`, before it
+writes anything. An update that would introduce an issue stops and writes nothing; fix the input and
+rerun. An issue the catalogs already had does not stop it.
+
+So the write is safe, but the repository may still carry older issues. Follow
+`references/validate.md` and report its result, not just the update's.
+
+Then state plainly that nothing was published: the change sits in the repository until it is pushed
+and a user refreshes the marketplace.

package/skills/marketplace/references/validate.md

@@ -35,7 +35,7 @@ the fix is to run `init` or `add` so the runtime gets a catalog of its own.
 
 Fix an issue in the source it comes from, then regenerate. An entry's fields are derived, so an
 npm-style `repository` object belongs fixed in the plugin's `plugin.json` (for a discovered plugin)
-or passed as `--repository <url>` (for an added one).
+or set with `update <name> --repository <url>` (for an added one, `references/update.md`).
 
 The top-level `name` and `owner` live in the catalog itself, and `owner` must be an object —
 `{ "name": "…" }`, never the `"Name <email>"` string `package.json` uses.

package/skills/marketplace/scripts/add.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.3","entry":"skills/marketplace/scripts/add.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.1","entry":"skills/marketplace/scripts/add.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/marketplace/scripts/install-docs.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/install-docs.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.3","entry":"skills/marketplace/scripts/install-docs.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.1","entry":"skills/marketplace/scripts/install-docs.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";

package/skills/marketplace/scripts/marketplace.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.3","entry":"skills/marketplace/scripts/marketplace.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.1","entry":"skills/marketplace/scripts/marketplace.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/marketplace/scripts/update.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.1","entry":"skills/marketplace/scripts/update.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+import { spawnSync } from "node:child_process";
+//#region src/compile/scripts.ts
+/** The global the header assigns the script data to. Framework-neutral: a script's own code, or the
+*  library it inlines, reads it; universal-plugin depends on neither. */
+const SCRIPT_GLOBAL = "__SKILL_SCRIPT__";
+//#endregion
+//#region src/skill-scripts/cli-runner.ts
+/** The data `plugin build` embedded in this compiled script. */
+function skillScript() {
+	const data = globalThis[SCRIPT_GLOBAL];
+	if (data === void 0) throw new Error("this script runs only as compiled by `plugin build`");
+	return data;
+}
+/** Runs the universal-plugin CLI. A skill may be copied away from its package, so it never reaches
+*  for a CLI beside it: the project's installed CLI first, then the one pinned to this script's
+*  version, which `plugin version` stamps. */
+function runCli(args, options = {}) {
+	const { bin, package: pkg, version } = skillScript();
+	const name = bin ?? "universal-plugin";
+	if (spawnSync("pnpm", [
+		"exec",
+		name,
+		"--version"
+	], { encoding: "utf8" }).status === 0) return spawnSync("pnpm", [
+		"exec",
+		name,
+		...args
+	], {
+		encoding: "utf8",
+		...options
+	});
+	const pinned = `${pkg ?? "universal-plugin"}@${version ?? "latest"}`;
+	return spawnSync("npx", [pinned, ...args], {
+		encoding: "utf8",
+		...options
+	});
+}
+//#endregion
+//#region src/skill-scripts/run-cli.ts
+const script = skillScript();
+const command = Object.entries(script.commands).find(([, entry]) => entry === script.entry)?.[0];
+if (command === void 0) {
+	process.stderr.write(`${script.entry} declares no command in the scripts map\n`);
+	process.exit(1);
+}
+const result = runCli([...command.split(" "), ...process.argv.slice(2)], { stdio: "inherit" });
+process.exit(result.status ?? 1);
+//#endregion
+export {};

package/skills/marketplace/scripts/validate.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.3","entry":"skills/marketplace/scripts/validate.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.1","entry":"skills/marketplace/scripts/validate.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/migrate-plugin/SKILL.md

@@ -87,7 +87,7 @@ configuration is:
 }
 ```
 
-Retain existing package entries such as `bin`, `dist`, and `governances`.
+Retain existing package entries such as `bin`, `dist`, and `references`.
 Never replace the allowlist wholesale.
 
 ## 4. Bundle the CLI with tsdown
@@ -173,7 +173,6 @@ as a follow-up instead of doing it inside this migration.
 
 Point every version and build step at the new plugin root:
 
-- Set the manifest extension's `packagePath` to `"."`.
 - `universal-plugin plugin version --from-package --root <pkg>` reads `packagePath` from
   `<pkg>/.agents/universal-plugin.json`, not from the manifest extension. With
   no `packagePath` it reads `<pkg>/package.json`, so a package that holds its

package/skills/publish-plugin/SKILL.md

@@ -34,7 +34,8 @@ is the common case.
 
 ### 0a. Identify the marketplace repo
 
-Default to `cyberuni/cyberplace` unless the user names another one.
+Default to `cyberuni/cyberplace` unless the user names another one. The commands below call it
+`<marketplace-repo>` (`<owner>/<repo>`), and its repository name `<marketplace-repo-name>`.
 
 ### 0b. Identify which repo the cwd is
 
@@ -239,6 +240,14 @@ The `source` field supports the same shapes as Claude Code (`url`, `github`, `gi
 
 If the plugin is already listed (this is an update), find its existing entry, update changed fields, and preserve any curator-added fields not in the standard shape. Do not overwrite `publishedAt` if present — add `"updatedAt": "<today>"` instead.
 
+For a change `marketplace update` covers (a new source, a moved `ref` or `sha` pin, or a field such as `description`, `version`, or `category`), run it in the marketplace checkout rather than editing the catalogs by hand. It keeps every field it is not given, curator fields included, and validates each catalog before writing:
+
+```bash
+npx universal-plugin marketplace update <plugin-name> --source <spec> --dry-run --root .
+```
+
+Drop `--dry-run` once the plan reads right. `updatedAt` and any other field it has no flag for are still set by hand.
+
 Show all prepared entries to the user and ask them to confirm before proceeding.
 
 ### 2f. Resolve the plugin's dependencies
@@ -309,15 +318,15 @@ Otherwise, the marketplace repo is elsewhere and needs a working copy. If the us
 (org member), work directly:
 
 ```bash
-gh repo clone cyberuni/cyberplace
-cd cyberplace
+gh repo clone <marketplace-repo>
+cd <marketplace-repo-name>
 ```
 
 If a fork is needed:
 
 ```bash
-gh repo fork cyberuni/cyberplace --clone --remote
-cd cyberplace
+gh repo fork <marketplace-repo> --clone --remote
+cd <marketplace-repo-name>
 git fetch upstream && git merge upstream/main
 ```
 
@@ -346,7 +355,7 @@ git push origin add-<plugin-name>
 
 ```bash
 gh pr create \
-  --repo cyberuni/cyberplace \
+  --repo <marketplace-repo> \
   --title "Add <plugin-name> v<version>" \
   --body "$(cat <<'EOF'
 ## Plugin

package/skills/version/README.md

@@ -27,8 +27,8 @@ semantic-release stamps files that exist only in the npm package unless `@semant
 commits them back. Git-sourced installs read `plugin.json` from the repository, so they need that
 commit-back.
 
-`plugin bundle` and `publish sync-version` are deprecated aliases and are removed in the next minor
-release.
+`plugin bundle` and `publish sync-version` are deprecated aliases. They have warned since 0.14.0 and will be
+removed in a later release.
 
 ## The part that is not automatable
 

package/skills/version/SKILL.md

@@ -74,7 +74,7 @@ node scripts/version.mjs --from-package
 ```
 
 Resolve that path against this skill's own directory; it runs the project's installed CLI
-(`pnpm exec universal-plugin`), else `npx universal-plugin@0.16.3` pinned to this skill's version.
+(`pnpm exec universal-plugin`), else `npx universal-plugin@0.17.1` pinned to this skill's version.
 `universal-plugin plugin version` on the `PATH` is the fallback. The command never prompts, so it is safe to run unattended once the
 source is decided.
 
@@ -138,8 +138,8 @@ Every guard resolves before the first write, so a failed run leaves the tree unt
   `plugin build`; the bump already re-derived them.
 - **Run `npm version`.** It knows only `package.json` and leaves the canonical manifest and the
   skill pins stale.
-- **Use the deprecated commands.** `plugin bundle` and `publish sync-version` print a warning and are
-  removed in the next minor release. `sync-version` now runs `plugin version --from-package`.
+- **Use the deprecated commands.** `plugin bundle` and `publish sync-version` print a deprecation
+  warning; use `plugin version` instead. `sync-version` now runs `plugin version --from-package`.
 
 ## Related skills
 
@@ -148,7 +148,7 @@ Every guard resolves before the first write, so a failed run leaves the tree unt
 | Create, adopt, or change what the plugin declares | `init-universal-plugin` |
 | Re-derive the vendor manifests by hand | `build-plugin` |
 | Check whether every place agrees (`unstamped`, `version-drift`) | `doctor-universal-plugin` |
-| Add a changeset for the change being released | `add-changeset` |
+| Add a changeset for the change being released | `buddy-changesets:changesets` |
 | Refresh the repository's own marketplace catalogs after a bump | `marketplace` |
 | List the released plugin in the shared marketplace | `publish-plugin` |
 

package/skills/version/scripts/version.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.3","entry":"skills/version/scripts/version.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.1","entry":"skills/version/scripts/version.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the