universal-plugin 0.12.1 → 0.13.0

package/skills/build-plugin/scripts/build.mjs

@@ -1,11 +1,52 @@
 #!/usr/bin/env node
-// Runs `universal-plugin plugin build` from the CLI that ships beside this skill, so the manifests a
-// plugin ships are derived by the version the author installed, never by one `npx` resolves.
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-// <package>/skills/<skill>/scripts/build.mjs: four levels up is the package root.
-const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
-
-process.argv.splice(2, 0, 'plugin', 'build')
-await import(join(packageRoot, 'bin', 'universal-plugin.mjs'))
+// 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.13.0","entry":"skills/build-plugin/scripts/build.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"}};
+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/doctor-universal-plugin/SKILL.md

@@ -19,8 +19,9 @@ and that judgment belongs to the skill that owns the write.
 node scripts/doctor.mjs
 ```
 
-Resolve that path against this skill's own directory. It runs the CLI that shipped beside it against
-the current working directory, so nothing is downloaded; add `--root <path>` to diagnose elsewhere.
+Resolve that path against this skill's own directory. It asks the project's installed CLI
+(`pnpm exec universal-plugin`), else the CLI pinned to this skill's version (`npx`), about the
+current working directory; add `--root <path>` to diagnose elsewhere.
 Add `--marketplace-root <path>` (repeatable) to also check a **separately-cloned** shared marketplace
 repository (e.g. a local clone of `cyberuni/marketplace`) — see
 [Catalogs are checked at the repository root](#catalogs-are-checked-at-the-repository-root).
@@ -58,7 +59,7 @@ to derive. Never report it as a fault.
 A plugin that **does** declare those reports `copilot-cli` as `built` at `com.github.copilot/`
 instead. Declaring the canonical `$schema` moves them there: Copilot CLI stops reading them from the
 plugin root entirely, so a root-only layout loads none of them and says nothing
-([ADR-0015](../../.agents/spec/design/decisions/0015-copilot-spec-mode-namespace.md)). That is what
+([ADR-0015](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0015-copilot-spec-mode-namespace.md)). That is what
 `copilot-root-components` reports.
 
 If `node` is unavailable, read `scripts/doctor.mjs` and apply the same checks by hand: it composes
@@ -78,14 +79,19 @@ Each `code` below is what the script emits.
 | `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 |
+| `stale-script` | a compiled skill script (`scripts` in the extension) is missing, or no longer matches what its source compiles to. A script that differs only in its embedded version is `version-drift` instead, never both | `/universal-plugin:build-plugin`, then commit the compiled script |
+| `script-compile-failed` | a declared script entry could not be compiled into one self-contained file — usually an import that does not resolve from the plugin root | fix the entry, then `/universal-plugin:build-plugin` |
+| `script-over-budget` | a compiled skill script is over the 150 KB budget | have the skill call the installed CLI instead: `pnpm exec <bin>` with a pinned `npx` fallback |
+| `skill-link-escapes` | a relative Markdown link in a skill climbs out of the skill folder (`../../readme.md`). pnpm links or copies each skill folder on its own, and a plugin cache keeps only what ships, so the link resolves to nothing there | copy the file into the skill and link it relatively, or link it by URL |
 | `undeliverable-override` | `harnesses["copilot-cli"]` sets fields that reach nothing | `/universal-plugin:init-universal-plugin`, update route — move them to a vendor that has a derived manifest, or drop them |
 | `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` |
+| `version-drift` | one file carries a different version from the release's number — the canonical manifest, a derived vendor manifest, a catalog entry, a skill pin, a marked `mcpServers` entry, or the version a compiled skill script embeds; one finding per file, named by path | `/universal-plugin:version` (for a package-sourced drift, `universal-plugin plugin version --from-package`); then [offer the CI check](#offer-the-check-to-ci) |
+| `unstamped` | a place holds `0.0.0-development`, semantic-release's placeholder. The release has not stamped it yet, so it is not drift (severity low) | in `prepareCmd`, `plugin version ${nextRelease.version}`, and commit the stamped files back with `@semantic-release/git`; see `/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: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 |
+| `no-vendors` | no vendor is declared, so the build writes nothing and no runtime reads the plugin. When the repository carries `vendorExtensions` or a `.plugin/plugin.json`, 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 when `vendorExtensions` or `.plugin/plugin.json` is present, else update route |
 | `package-path-missing` | `packagePath` names a directory with no readable `package.json` | fix `packagePath`, or create the package |
 | `package-path-unknown` | the CLI could not report `packagePath` (a version too old to read it), so `version-drift` and `unreleased-content` were skipped rather than guessed | upgrade universal-plugin |
 | `misplaced-package-path` | `plugin.json` declares `packagePath` under `extensions["org.cyberuni.universal-plugin"]`, where the CLI never reads it — the plugin is silently treated as not shipping to npm | move it to `.agents/universal-plugin.json`, relative to the plugin root |
@@ -137,20 +143,44 @@ user can run, or ask before running it yourself.
 
 ## Version drift
 
-Two files carry an authored version: the canonical `plugin.json`, and the `package.json` at the
-`packagePath` the CLI reports (`config get --key packagePath`), resolved from the plugin root. The script compares
-them and emits `version-drift`.
+A version lives in five places. Two are authored: the canonical `plugin.json`, and the `package.json`
+at the `packagePath` the CLI reports (`config get --key packagePath`), resolved from the plugin root.
+The rest are stamped from them by `plugin version`: the vendor manifests, this plugin's entry in each
+repository catalog, the `npx`/`upx <package>@<version>` pins in the skills, and each `mcpServers`
+entry marked `pinToPluginVersion`.
 
-They diverge when someone ran `npm version`, or when changesets released a number that never flowed
-back. Both are `/universal-plugin:version`'s to fix — never patch one file by hand to match the
-other.
+The script asks `universal-plugin publish check-version` for the comparison and emits one
+`version-drift` per file that disagrees. The reference is the release's number: the `package.json`
+when `packagePath` is declared, else `plugin.json`. Pins are compared only when there is a package to
+pin, and a pin-exempt skill or a pin that is not a version (`<version>`, `latest`) is skipped. A place
+holding `0.0.0-development` is reported as `unstamped`, not as `version-drift`.
+
+Files diverge when someone ran `npm version`, or when a release tool (changesets, release-please,
+semantic-release) moved `package.json` and nothing stamped the number on. All of it is
+`/universal-plugin:version`'s to fix — never patch one file by hand to match another.
+
+### Offer the check to CI
+
+`doctor` is advisory and always exits 0. `publish check-version` is the same comparison, read-only,
+and exits 1 on drift, so a repository can fail the release PR instead of publishing a plugin that
+claims the old version. Once the version findings are reported, check whether the repository
+already runs it: search its `package.json` scripts and `.github/workflows/` for `check-version`. If
+it does not, offer to add it — ask first, because both are the user's files:
+
+- a `verify` (or `check`) script step: `universal-plugin publish check-version --root <plugin-root>`;
+- or a CI step after install on pull requests, for the release PR a changesets, release-please, or
+  semantic-release bot opens.
+
+Use the locked `universal-plugin` from the repository's devDependencies when it has one; otherwise
+`npx universal-plugin@0.13.0`, pinned. This check matters most where the release tool picks the
+number, because nothing else runs between that bump and publish.
 
 ## Unreleased content
 
 A runtime keys its plugin cache on the version, not on content: Claude Code resolves the version,
 finds it unchanged, and reports *"already at the latest version"* without re-extracting. So content
 pushed without a bump reaches nobody who already installed the plugin, and neither side is told
-([ADR-0010](../../.agents/spec/design/decisions/0010-version-policy.md) §6).
+([ADR-0010](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0010-version-policy.md) §6).
 
 The script compares the shipped paths — the canonical manifest, the skills directory, `agents/`,
 `governances/`, `references/`, `mcp.json` — against the commit that set the version the manifest carries now, and
@@ -158,7 +188,7 @@ emits `unreleased-content` for anything committed since. Uncommitted work is not
 shipped.
 
 Two cases are deliberately silent. A plugin that declares `packagePath` is skipped, because there the
-release picks the number (ADR-0010 §2) and content waiting ahead of the last released version is the
+release picks the number ([ADR-0010](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0010-version-policy.md) §2) and content waiting ahead of the last released version is the
 normal state of a branch. A tree with no git history is skipped rather than guessed at.
 
 The repair is the bump, and it belongs to `/universal-plugin:version`. Judge first whether the change