universal-plugin 0.11.2 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -42,7 +42,7 @@
     "@cyberuni/agent-harness": "^0.3.0",
     "@repobuddy/upx": "^0.2.0",
     "@toon-format/toon": "^4.1.1",
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
     "semver": "^7.8.1"
   },
   "devDependencies": {
@@ -53,7 +53,7 @@
     "tsdown": "^0.23.0",
     "tsx": "^4.22.3",
     "typescript": "^6.0.0",
-    "vitest": "^4.1.7"
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=22"

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.11.2",
+	"version": "0.12.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/readme.md

@@ -69,7 +69,7 @@ npx universal-plugin sync apply <action-id>
 ### publish
 
 ```sh
-npx universal-plugin publish sync-version             # copy packagePath/package.json version into plugin.json
+npx universal-plugin publish sync-version             # copy packagePath/package.json version into plugin.json, then rebuild
 ```
 
 This writes the canonical `plugin.json` only. Run `plugin build` afterwards, or the vendor manifests

package/skills/build-plugin/SKILL.md

@@ -56,6 +56,7 @@ The command never prompts, so it is safe to run unattended.
 | `--dry-run` | Validate and report the plan, write nothing. Run this first when unsure what will change |
 | `--vendor <id>` | Build one vendor (`claude-code`, `cursor`, `codex`, `copilot-cli`), and refresh only its catalog |
 | `--verbose` | Print each field-level decision the derivation made |
+| `--strict-dependencies` | Fail when a refreshed catalog cannot resolve a declared dependency. Use in CI |
 | `--format json` | The same result as JSON, for scripts |
 
 `--clean` also exists. It deletes derived manifests before rewriting them, so reach for it only
@@ -76,9 +77,14 @@ A catalog row reads `updated`, `unchanged`, or `planned` on `--dry-run`. A build
 catalog, and it keeps an entry's non-local source, such as an npm package, while it re-derives the
 version. To add a catalog or change a source, use `marketplace`.
 
+The build also checks each declared dependency against the catalogs it refreshes. A bare dependency
+the catalog does not list warns: offer the user both fixes the warning names, listing it with
+`marketplace add` or qualifying it with the marketplace that lists it. A dependency whose entry
+declares a `source` is listed in the catalog by the build itself.
+
 Read stderr too. The build drops what a vendor cannot represent and warns instead of failing: a hook
 handler type a vendor cannot run, a `harnesses.copilot-cli` override with no delivery path, an
-invalid catalog. Each warning names something that will not reach a runtime. Tell the user each
+invalid catalog, a dependency the catalog cannot resolve. Each warning names something that will not reach a runtime. Tell the user each
 one; do not bury it in a summary.
 
 `built 0` with "nothing to build" is not success. The manifest declares no vendor, so hand it to

package/skills/doctor-universal-plugin/SKILL.md

@@ -73,8 +73,8 @@ Each `code` below is what the script emits.
 | `no-manifest` | no root `plugin.json` — this is not a plugin yet | `/universal-plugin:init-universal-plugin` |
 | `legacy-manifest` | root `plugin.json` with neither `$schema` nor `extensions` — a single-vendor manifest on the canonical path | `/universal-plugin:init-universal-plugin`, adopt route |
 | `vendor-only` | a vendor manifest with no canonical manifest above it | `/universal-plugin:init-universal-plugin`, adopt route |
-| `unbuilt` | a declared vendor whose output path holds no file — that runtime sees no plugin | `universal-plugin plugin build` |
-| `stale` | a derived manifest older than `plugin.json` | `universal-plugin plugin build` |
+| `unbuilt` | a declared vendor whose output path holds no file — that runtime sees no plugin | `/universal-plugin:build-plugin` |
+| `stale` | a derived manifest older than `plugin.json`; for a derived directory (`com.github.copilot/`), its newest file is what is compared | `/universal-plugin:build-plugin` |
 | `hand-edited` | a derived manifest that `build` would rewrite — the edit is already lost, it just has not been overwritten yet | move the field to the canonical manifest or to `harnesses.<vendor>`, then rebuild |
 | `unknown-vendor` | a `vendors` entry no build target matches; reported as `skipped` plus a warning | fix the id in `plugin.json` |
 | `unsupported-component` | a component path on the shared extension names a component one targeted vendor has none of (`agents` for Codex, `rules` for Claude Code, …); the build leaves it out of that vendor's manifest | declare the path under `harnesses.<vendor>` for the vendors that read it, or leave it — nothing is lost |
@@ -82,7 +82,7 @@ Each `code` below is what the script emits.
 | `codex-fields-missing` | Codex is targeted without `version` or `description`; the build fails and writes **nothing at all**, including for the other vendors | add both to the canonical top level |
 | `version-drift` | the `packagePath` `package.json` and the canonical manifest carry different versions | `/universal-plugin:version` |
 | `unreleased-content` | shipped content was committed after the commit that set the current version — a consumer keyed on that version never re-extracts it | `/universal-plugin:version` |
-| `copilot-root-components` | agents, commands, rules, hooks, or LSP servers sit at the plugin root with no copy under `com.github.copilot/` — Copilot CLI reads them only from there in spec mode, so it loads none of them, silently | `universal-plugin plugin build` |
+| `copilot-root-components` | agents, commands, rules, hooks, or LSP servers sit at the plugin root with no copy under `com.github.copilot/` — Copilot CLI reads them only from there in spec mode, so it loads none of them, silently | `/universal-plugin:build-plugin` |
 | `stale-github-plugin` | a leftover `.github/plugin/plugin.json` from an older build — shadowed by root and no longer generated | `/universal-plugin:remove-plugin` |
 | `shadowing-manifest` | a `.plugin/plugin.json` exists — it outranks root in Copilot CLI's search order and silently shadows the canonical manifest | `/universal-plugin:remove-plugin` |
 | `no-vendors` | no vendor is declared, so the build writes nothing and no runtime reads the plugin. On a repository still on the pre-0.6 layout the build stops rather than reporting an empty result, and the detail says so — read it beside `legacy-manifest` and `shadowing-manifest`, which name the signals | `/universal-plugin:init-universal-plugin`, adopt route on the pre-0.6 layout, else update route |
@@ -126,7 +126,7 @@ the diff:
 ```bash
 git status --short          # must be clean first, or the diff proves nothing
 npx universal-plugin plugin build
-git diff -- .claude-plugin .cursor-plugin .codex-plugin
+git diff -- .claude-plugin .cursor-plugin .codex-plugin com.github.copilot
 ```
 
 An empty diff means the derived manifests match what the canonical manifest says. Any hunk is drift —
@@ -180,6 +180,7 @@ is meant to ship — content that is still being worked on is not a finding to a
 | Task | Skill |
 |------|-------|
 | Create, adopt, or change what the plugin declares | `init-universal-plugin` |
+| Rebuild the derived manifests (`unbuilt`, `stale`, `copilot-root-components`) | `build-plugin` |
 | Move the plugin's version | `version` |
 | Remove derived manifests, or the plugin itself | `remove-plugin` |
 | Generate the repository's own marketplace catalogs | `marketplace` |

package/skills/doctor-universal-plugin/scripts/doctor.mjs

@@ -30,6 +30,15 @@ const readJson = (file) => {
 	}
 }
 const mtime = (file) => (fs.existsSync(file) ? fs.statSync(file).mtimeMs : null)
+// A derived directory (copilot-cli's com.github.copilot/) is as fresh as the newest file in it. The
+// directory's own mtime moves only when an entry is added, removed or renamed, so a rebuild that
+// rewrites its files in place leaves it as old as the first build (issue #144).
+const contentMtime = (abs) => {
+	const stat = fs.statSync(abs)
+	if (!stat.isDirectory()) return stat.mtimeMs
+	const files = fs.readdirSync(abs).map((entry) => contentMtime(path.join(abs, entry)))
+	return files.length === 0 ? stat.mtimeMs : Math.max(...files)
+}
 
 const VENDOR_MANIFESTS = ['.claude-plugin/plugin.json', '.cursor-plugin/plugin.json', '.codex-plugin/plugin.json']
 
@@ -207,7 +216,7 @@ if (build === null) {
 		const abs = path.join(root, row.path)
 		const exists = fs.existsSync(abs)
 		// `canonical` means the vendor reads root plugin.json; no derived file is expected.
-		const stale = row.status === 'built' && exists && manifestMtime !== null && mtime(abs) < manifestMtime
+		const stale = row.status === 'built' && exists && manifestMtime !== null && contentMtime(abs) < manifestMtime
 		vendors.push({ vendor: row.vendor, path: row.path, status: row.status, exists, stale })
 
 		if (row.status === 'built' && !exists) {

package/skills/publish-plugin/README.md

@@ -22,6 +22,14 @@ Every check and every entry field in Steps 1–2 reads from the plugin location
 from the cwd by assumption. Getting this wrong means the marketplace entry ends up pointing at the
 marketplace repo's own URL instead of the plugin's.
 
+## A plugin's dependencies go with it
+
+A plain dependency (no marketplace named) resolves against the marketplace the plugin is installed
+from, so publishing a plugin whose plain dependency the catalog does not list publishes something
+nobody can install. The skill lists such a dependency in the same PR, or stops and asks for it to be
+published first. A dependency that names another marketplace only needs that marketplace in the
+catalog's `allowCrossMarketplaceDependenciesOn`, which the skill offers to add.
+
 ## Why this is not the `marketplace` skill
 
 `marketplace` generates a repository's own local catalog — no submission, no shared listing, no PR.

package/skills/publish-plugin/SKILL.md

@@ -19,7 +19,7 @@ Publishing has four steps:
 
 0. **Locate** — work out which repo is which, and where the plugin and the marketplace each live
 1. **Pre-flight** — validate the plugin is ready
-2. **Prepare entries** — build the entry for each vendor marketplace file that exists
+2. **Prepare entries** — build the entry for each vendor marketplace file that exists, and resolve the plugin's dependencies against the target marketplace
 3. **Submit PR** — one PR that updates all relevant marketplace files
 
 Work through each step in order. Do not skip pre-flight even if the user says the plugin is ready.
@@ -211,7 +211,39 @@ If the plugin is already listed (this is an update), find its existing entry, up
 
 Show all prepared entries to the user and ask them to confirm before proceeding.
 
-### 2f. Validate the catalogs
+### 2f. Resolve the plugin's dependencies
+
+Claude Code installs a plugin only when every dependency it declares resolves, so a catalog that lists
+the plugin but not what it depends on publishes a plugin nobody can install. Read the declaration
+Claude Code receives, from the **plugin location**: `dependencies` in `.claude-plugin/plugin.json`
+(the built manifest), or, if that has not been built, the canonical one —
+`extensions["org.cyberuni.universal-plugin"].harnesses["claude-code"].dependencies`, else
+`extensions["org.cyberuni.universal-plugin"].dependencies` in `plugin.json`. No declaration means
+nothing to do here.
+
+Each entry is a string (`<plugin>` or `<plugin>@<marketplace>`, optionally with an `@^range` tail) or
+an object (`{ "name", "marketplace"?, "version"?, ... }`). Sort each one:
+
+- **Plain** — a bare `<plugin>`, or an object with no `marketplace`. Claude Code resolves it against
+  the marketplace the plugin is installed from, which is this one. If the target catalog
+  (`.claude-plugin/marketplace.json`) already lists that name, it is resolved. Otherwise it must be
+  listed in this same PR: locate the dependency's own repository or package (an object's `source`
+  field, when present, says where it is distributed from; otherwise ask the user), run Step 1's
+  pre-flight against it, and prepare its entries exactly as 2b–2e do for the main plugin — then
+  resolve *its* plain dependencies the same way. If a plain dependency cannot be listed (no
+  repository or package to read, pre-flight fails, the user declines), **stop**: tell the user to
+  publish that dependency to this marketplace first, and do not open the PR.
+- **Names a marketplace** — `<plugin>@<marketplace>`, or an object with `marketplace`. Not held to
+  this catalog's listing, even when the marketplace it names is this one; do not add an entry for
+  it. When the named marketplace is **not** this catalog's `name`, Claude Code refuses the
+  dependency at install unless this catalog's top-level `allowCrossMarketplaceDependenciesOn` lists
+  that marketplace. If it does not, tell the user that installs from this marketplace need it, and
+  offer to add the marketplace name to that array in the same PR.
+
+Report how each dependency was sorted and what was done about it, and include the dependency entries
+in what you show the user to confirm.
+
+### 2g. Validate the catalogs
 
 Before moving to Step 3, run the validator against the marketplace repo's working copy (the same
 checkout the entries were just written into):
@@ -221,7 +253,11 @@ npx universal-plugin marketplace validate --root .
 ```
 
 This is the same check `marketplace init`/`build` rely on — it catches an entry shape no runtime can
-load (a bad `source`, a missing required key) before it reaches a PR. Fix any reported issue and
+load (a bad `source`, a missing required key) before it reaches a PR. In the Claude catalog it also
+reports a plain dependency the catalog does not list and a dependency on a marketplace missing from
+`allowCrossMarketplaceDependenciesOn`, as far as it can see them offline (an entry's own
+`dependencies`, and plugins at `./` paths) — so it does not replace 2f for a plugin listed from npm
+or git. Fix any reported issue and
 re-run before continuing. Do not open the PR while validation fails.
 
 ---
@@ -266,7 +302,7 @@ git checkout -b add-<plugin-name>
 
 ### 3c. Edit all detected marketplace files
 
-For each vendor marketplace file detected in Step 2a, append the plugin entry to its `plugins` array. Preserve formatting and all existing entries exactly. Stage all changed files together.
+For each vendor marketplace file detected in Step 2a, append the plugin entry — and the entry of each dependency 2f listed — to its `plugins` array, and add any `allowCrossMarketplaceDependenciesOn` change the user accepted in 2f. Preserve formatting and all existing entries exactly. Stage all changed files together.
 
 ### 3d. Commit and push
 
@@ -319,6 +355,8 @@ gh pr create \
 - [ ] Semver version string
 - [ ] SPDX license identifier
 - [ ] Entry appended to each detected marketplace file
+- [ ] Every plain dependency is listed in this marketplace (here or already)
+- [ ] Every marketplace a dependency names is in `allowCrossMarketplaceDependenciesOn`, or noted as not needed
 EOF
 )"
 ```
@@ -337,7 +375,8 @@ Return the PR URL to the user when done.
 | Name conflict in marketplace | Check existing entries in each marketplace file first |
 | Plugin loads but skills missing | Add `skills` array to the Claude Code marketplace entry |
 | Entry installs nothing for a monorepo plugin | `source` was `url`/root-clone instead of `git-subdir` — redo 2b/2c with the plugin's actual repo-relative path |
-| `marketplace validate` fails after 2f | Fix the reported shape before opening the PR — do not open it while validation fails |
+| Install fails resolving a dependency | 2f was skipped — list the plain dependency in this marketplace, or allow the named marketplace in `allowCrossMarketplaceDependenciesOn` |
+| `marketplace validate` fails after 2g | Fix the reported shape before opening the PR — do not open it while validation fails |
 | Entry's `repository`/`source.url` points at the marketplace repo | Step 0 role detection was skipped or overridden wrongly — re-check which repo the cwd is |
 
 ---

package/skills/publish-plugin/evals/evals.json

@@ -30,6 +30,12 @@
 			"prompt": "I'm a maintainer of cyberuni/marketplace and I already have it checked out here. I want to add a plugin called 'db-migrate' that lives at github.com/someuser/db-migrate. Add it.",
 			"expected_output": "Detects the cwd is the marketplace repo itself, not the plugin, so it reads the plugin's metadata from the given URL (cloning it to a scratch location) instead of the cwd, then works directly in the existing checkout (fetch/merge, branch, edit, commit, push, PR) rather than cloning or forking cyberuni/marketplace again. The prepared entry's source/repository URL points at db-migrate's repo, not at cyberuni/marketplace.",
 			"files": []
+		},
+		{
+			"id": 6,
+			"prompt": "Publish buddy-agent-harness (in ~/code/buddy-agent-harness) to the cyberplace marketplace. Its plugin.json declares dependencies [\"agent-harness\", { \"name\": \"cyber-asana\", \"marketplace\": \"cyberuni\" }]. cyberplace's .claude-plugin/marketplace.json does not list agent-harness and has no allowCrossMarketplaceDependenciesOn.",
+			"expected_output": "Reads the plugin's dependencies before submitting. Treats \"agent-harness\" as a plain dependency resolved against cyberplace: since cyberplace does not list it, prepares agent-harness's entry in the same PR from its own repository/package (after pre-flight), or stops and tells the user to publish agent-harness first — never opens a PR listing buddy-agent-harness without it. Treats cyber-asana@cyberuni as a named-marketplace dependency: adds no entry for it, says installs from cyberplace need \"cyberuni\" in allowCrossMarketplaceDependenciesOn, and offers to add it.",
+			"files": []
 		}
 	]
 }

package/skills/version/README.md

@@ -18,7 +18,7 @@ The first question the skill asks is whether the repository uses changesets.
 
 - **With changesets** — the number is decided by the release, not by this skill. Add a changeset, let
   the release run, and `publish sync-version` carries the released number into the canonical
-  manifest.
+  manifest and re-derives the vendor manifests. With `--no-build`, `plugin build` is the next step.
 - **Without** — `plugin version <bump>` is the whole step. `scripts/version.mjs` runs it from the CLI
   shipped beside the skill, so nothing is downloaded.
 

package/skills/version/SKILL.md

@@ -22,12 +22,17 @@ test -d .changeset && echo "changesets"
 
 **If it does**, the version number is decided by changesets, not by you. Add a changeset and let the
 release run — the repo's `version` script should already call `publish sync-version`, which carries
-the released number from `package.json` into the canonical manifest:
+the released number from `package.json` into the canonical manifest and re-derives the vendor
+manifests, the same way `plugin version` does:
 
 ```bash
 npx universal-plugin publish sync-version
 ```
 
+If the script passes `--no-build`, it must run `plugin build` next (`/universal-plugin:build-plugin`);
+otherwise the vendor manifests and `com.github.copilot/` keep the old version, and a consumer's
+plugin cache never re-extracts.
+
 Do **not** run `plugin version` in a changesets repo — it would decide a number changesets is about
 to decide again.
 
@@ -109,6 +114,7 @@ Every guard resolves before the first write, so a failed run leaves the tree unt
 | Task | Skill |
 |------|-------|
 | Create, adopt, or change what the plugin declares | `init-universal-plugin` |
+| Re-derive the vendor manifests by hand | `build-plugin` |
 | Check whether the two authored versions agree | `doctor` |
 | Add a changeset for the change being released | `add-changeset` |
 | Refresh the repository's own marketplace catalogs after a bump | `marketplace` |