universal-plugin 0.12.2 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -43,6 +43,7 @@
     "@repobuddy/upx": "^0.2.0",
     "@toon-format/toon": "^4.1.1",
     "commander": "^15.0.0",
+    "rolldown": "^1.2.11",
     "semver": "^7.8.1"
   },
   "devDependencies": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.12.2",
+	"version": "0.14.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"
@@ -19,6 +19,35 @@
 				"cursor": {},
 				"codex": {},
 				"copilot-cli": {}
+			},
+			"scripts": {
+				"skills/adopt-upx/scripts/rewrite-upx.mjs": "src/skill-scripts/rewrite-upx.ts",
+				"skills/doctor-universal-plugin/scripts/doctor.mjs": "src/skill-scripts/doctor.ts",
+				"skills/marketplace/scripts/install-docs.mjs": "src/skill-scripts/install-docs.ts",
+				"skills/build-plugin/scripts/build.mjs": {
+					"source": "src/skill-scripts/run-cli.ts",
+					"command": "plugin build"
+				},
+				"skills/init-universal-plugin/scripts/init.mjs": {
+					"source": "src/skill-scripts/run-cli.ts",
+					"command": "plugin init"
+				},
+				"skills/version/scripts/version.mjs": {
+					"source": "src/skill-scripts/run-cli.ts",
+					"command": "plugin version"
+				},
+				"skills/marketplace/scripts/add.mjs": {
+					"source": "src/skill-scripts/run-cli.ts",
+					"command": "marketplace add"
+				},
+				"skills/marketplace/scripts/marketplace.mjs": {
+					"source": "src/skill-scripts/run-cli.ts",
+					"command": "marketplace init"
+				},
+				"skills/marketplace/scripts/validate.mjs": {
+					"source": "src/skill-scripts/run-cli.ts",
+					"command": "marketplace validate"
+				}
 			}
 		}
 	}

package/readme.md

@@ -39,8 +39,9 @@ npx universal-plugin plugin init --npm           # also wire an npm package to s
 npx universal-plugin plugin build                # generate vendor manifests
 npx universal-plugin plugin install              # install the working copy into the runtimes it targets
 npx universal-plugin plugin uninstall            # take it back out
-npx universal-plugin plugin version <bump>       # move the version across every file carrying one
-npx universal-plugin plugin bundle               # pin skill npx references to workspace versions
+npx universal-plugin plugin version <bump>       # stamp the version into every place it lives (author bump)
+npx universal-plugin plugin version 1.4.0        # explicit number (semantic-release prepareCmd)
+npx universal-plugin plugin version --from-package  # take package.json's version (changesets, release-please)
 ```
 
 `build` writes `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, and
@@ -69,11 +70,11 @@ npx universal-plugin sync apply <action-id>
 ### publish
 
 ```sh
-npx universal-plugin publish sync-version             # copy packagePath/package.json version into plugin.json, then rebuild
+npx universal-plugin publish check-version            # fail when any place carries a different version (read-only, for CI)
 ```
 
-This writes the canonical `plugin.json` only. Run `plugin build` afterwards, or the vendor manifests
-keep their previous version.
+`publish sync-version` and `plugin bundle` are deprecated aliases of `plugin version --from-package`
+and `plugin version`. They print a warning and are removed in the next minor release.
 
 ### marketplace
 
@@ -136,7 +137,7 @@ upx cyber-skills@^2 audit validate
 ```
 
 Use a caret range on the major rather than an exact pin, so one global install serves every caller.
-`plugin bundle --runner upx` emits references in this form.
+The `adopt-upx` skill rewrites references to this form.
 
 `upx` only works once it is installed globally. `npx` ships with npm, so keep `npx` as the default
 anywhere you cannot guarantee that install.

package/references/plugin-design.md

@@ -247,17 +247,18 @@ If the repo needs explicit symlink tracking: `mcp.json symlink` in `.gitattribut
 
 ### Pinning a self-published server to the plugin version
 
-A plugin whose MCP server is its own npm package writes an unpinned invocation — `{"command": "npx", "args": ["-y", "my-server", "mcp"]}` — and a consumer on plugin 1.4.0 then gets 1.4.0's skills alongside whatever `npx` resolves as latest for the server. Mark the entry and `build` stamps the version on:
+A plugin whose MCP server is its own npm package writes an unpinned invocation — `{"command": "npx", "args": ["-y", "my-server", "mcp"]}` — and a consumer on plugin 1.4.0 then gets 1.4.0's skills alongside whatever `npx` resolves as latest for the server. Mark the entry and `plugin version` stamps the version on at release:
 
 ```json
 { "command": "npx", "args": ["-y", "my-server", "mcp"], "pinToPluginVersion": true }
 ```
 
-- **The marker is required.** `build` never name-matches — a plugin may publish its server under a package name that is not the plugin's, and an unrelated `npx -y widget-cli` must never be stamped with this plugin's version.
-- **The marker never reaches a runtime.** It is a build directive, not part of any vendor's schema, so `build` strips it from every derived manifest and derived `mcp.json`. The authored files are left as written.
-- An already-pinned specifier is **overwritten** with the manifest version, and the build warns naming the version it replaced. Do not hand-pin a marked entry.
-- A marked entry the build cannot pin — the `command` is not `npx`/`upx`, the manifest declares no `version`, or `args` carry no package specifier — is warned about and left alone; the build stays green.
-- `copilot-cli` reads the canonical manifest directly, so it has no derived manifest to receive the pin; the build warns rather than pretending otherwise.
+- **The marker is required.** Stamping never name-matches — a plugin may publish its server under a package name that is not the plugin's, and an unrelated `npx -y widget-cli` must never be stamped with this plugin's version.
+- **The marker never reaches a runtime.** It is a directive, not part of any vendor's schema, so `build` strips it from every derived manifest and derived `mcp.json` and copies the entry otherwise as authored. `build` never decides a version.
+- **`plugin version` writes the pin** into the authored entry, inline or in the mcp file, and keeps the marker. An already-pinned specifier is overwritten with the new version. Do not hand-pin a marked entry.
+- A marked entry that cannot be pinned — the `command` is not `npx`/`upx`, or `args` carry no package specifier — is warned about and left alone.
+- `publish check-version` and `doctor` compare marked entries too, so a stale pin is reported as drift.
+- `copilot-cli` reads the canonical manifest directly, so the stamped authored entry is what it sees.
 
 ## Environment Variable Mapping
 
@@ -278,10 +279,20 @@ A plugin whose MCP server is its own npm package writes an unpinned invocation
 
 **Rules (Cursor-only):** `.mdc` files in `rules/`. Required frontmatter: `description`. Optional: `alwaysApply` (bool), `globs` (file-pattern array). Bundle `commands/setup.md` to merge rule content into project's `AGENTS.md` — after that merge, `.mdc` files are redundant.
 
-**Decision tree for always-on guidance:**
+## Rules vs References
+
+"Always-on" assumes one agent per session. In an orchestrated system, a team of subagents each with its own focus, always-on content is injected into every subagent whatever its role. Anything that is not true for every role costs context and dilutes focus.
+
+- **Always-on content is the HCF (highest common factor) of all agents.** It holds only the constraints every agent in every role must follow, such as "never commit secrets" or "use Conventional Commits". That set is small.
+- **`rules/` is for the HCF only.** It stays for backward compatibility and for simple single-agent setups where no orchestration is involved. Its scope is narrow on purpose.
+- **Shared guidance is a reference, not a rule.** Content that cuts across components but applies only to some roles or tasks (a design standard, a review checklist, a workflow discipline) belongs in `references/<name>.md`. Whichever agent, skill, command, hook, or MCP server needs it loads it by name on demand, through the `reference` skill in the `cyber-agent-harness` plugin.
+
+**Decision tree for guidance:**
+- Every agent, every role (the HCF) → merge into **AGENTS.md**. For Cursor-only delivery, use `rules/` + `commands/setup.md`.
+- Cross-cutting, scoped to a role or task → `references/<name>.md`, loaded by name
 - Situation-triggered → **skill** (all agents)
-- Always-on, cross-agent → merge into **AGENTS.md**
-- Always-on, Cursor-only → `rules/` + `commands/setup.md`
+- Agent-specific → the agent definition file
+- Skill-specific → the `SKILL.md` body
 
 ## Namespacing
 
@@ -312,6 +323,7 @@ Default scope: **team**.
 - Relying on extended component types (commands, rules, agents, hooks) for core functionality — silently ignored on non-supporting hosts
 - Duplicating SKILL.md content in `plugin.json` — the manifest is a path index, never a content mirror
 - Using `rules/` for cross-agent always-on guidance — use AGENTS.md instead
+- Putting role- or task-scoped guidance in always-on context (`rules/` or AGENTS.md) — make it a reference loaded on demand
 - Putting install-time metadata in `plugin.json` instead of `skill.json`
 
 ## Cross-Platform Portability

package/schema/extension.schema.json

@@ -53,6 +53,37 @@
 		"outputStyles": {
 			"$ref": "#/$defs/pathValue",
 			"description": "Output style resources. Default: ./output-styles/."
+		},
+		"scripts": {
+			"type": "object",
+			"description": "Skill script entries 'plugin build' compiles into self-contained .mjs files. Keyed by the output path, relative to the plugin root (e.g. skills/doctor/scripts/doctor.mjs); each value is the source path, relative to the plugin root, or { source, command } where command is the CLI command path the entry runs. Never written to a derived manifest.",
+			"propertyNames": {
+				"pattern": "\\.mjs$"
+			},
+			"additionalProperties": {
+				"oneOf": [
+					{
+						"type": "string",
+						"minLength": 1
+					},
+					{
+						"type": "object",
+						"required": ["source"],
+						"additionalProperties": false,
+						"properties": {
+							"source": {
+								"type": "string",
+								"minLength": 1
+							},
+							"command": {
+								"type": "string",
+								"minLength": 1,
+								"description": "The CLI command path this entry runs (e.g. 'plugin build'). Every compiled script carries the map of these to their entries."
+							}
+						}
+					}
+				]
+			}
 		}
 	},
 	"$defs": {

package/skills/adopt-upx/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: adopt-upx
 description: Use this skill when the user wants to make their skills use upx — the fast local-first package runner shipped as @repobuddy/upx. Trigger on phrases like "make my skills use upx", "adopt the upx runner", "speed up npx calls", "switch to upx", or "rewrite npx pins to upx". Rewrites `npx <pkg>@<version>` references to a caret range on `upx` (`^<major>`, or `^0.<minor>` for a 0.x pin) across one skill, a named set, or every skill in the project.
+metadata:
+  pin-exempt: true
 ---
 
 # Adopt upx
 
 Rewrites `npx <pkg>@<version>` references inside `SKILL.md` files to a caret range on `upx` — the
 fast local-first runner shipped by `universal-plugin` (see the package
-[`readme.md`](../../readme.md#upx--the-fast-package-runner) for the `upx` contract).
+[`readme.md`](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/readme.md#upx-the-fast-package-runner) for the `upx` contract).
 
 ## When to use
 
@@ -51,7 +53,7 @@ Left alone (never rewritten):
   installed version; these already go straight to `npx` inside `upx` itself on a miss)
 - **Already-`upx` references** — nothing to do
 - **Any skill marked `pin-exempt: true`** in its frontmatter — its version strings are
-  documentation/illustration, not real invocations. This mirrors how `plugin bundle` treats
+  documentation/illustration, not real invocations. This mirrors how `plugin version` treats
   pin-exempt skills; `upgrade-plugin` is a live example.
 
 ## Choose scope

package/skills/adopt-upx/scripts/rewrite-upx.mjs

@@ -1,168 +1,131 @@
 #!/usr/bin/env node
-// Rewrites `npx <pkg>@<version>` references inside SKILL.md files to the fast local-first
-// `upx <pkg>@^<major>` form. See ../SKILL.md for the full contract; this is the mechanism.
-//
-// Usage:
-//   node rewrite-upx.mjs --all                    # every SKILL.md under cwd
-//   node rewrite-upx.mjs skills/my-skill           # one skill (dir or SKILL.md path)
-//   node rewrite-upx.mjs skills/a skills/b/SKILL.md skills/c-*   # a named set (paths + globs)
-//   node rewrite-upx.mjs --all --dry-run           # report only, write nothing
-//
-// Rewrite rule: `npx <pkg>@<concrete-semver>` -> `upx <pkg>@^<major>` (caret on the major, so
-// one global `upx` install serves many pinned callers). A `0.x` pin instead becomes
-// `upx <pkg>@^0.<minor>` — under semver a `0.x` minor bump is breaking, so `^0` would be far too
-// loose. Left alone:
-//   - `@<placeholder>` (non-semver, e.g. `@<version>`) — not a real pin
-//   - dist-tags (e.g. `@next`, `@latest`) — upx can't range-match these, they go to npx anyway
-//   - any occurrence already using `upx` — nothing to rewrite
-//   - any SKILL.md whose frontmatter declares `pin-exempt: true` — its versions are illustration
-//     (the same convention the plugin bundler uses)
-//
-// Idempotent: a second run finds no more `npx <pkg>@<semver>` occurrences to rewrite.
-
-import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
-import { join, resolve } from 'node:path'
-
-const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.turbo'])
-
-const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/
-const PIN_EXEMPT_PATTERN = /(^|\n)\s*pin-exempt:\s*true\s*(\n|$)/
-
-// Matches `npx <pkg>@<version>` — mirrors the pattern `plugin bundle` uses for pin rewriting,
-// but only for the `npx` runner word (upx refs are already fast, nothing to do). The package
-// class includes `@` and `/` so a scoped package (`@acme/cli@1.2.3`) matches; greedy matching
-// backtracks to the LAST `@`, which separates the version.
-const NPX_REF_PATTERN = /\bnpx(\s+(?:--yes\s+|-y\s+)?)([@a-z0-9/._-]+)@([^\s`'")]+)/g
-
-const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
-
+// Compiled by `universal-plugin plugin build` from src/skill-scripts/rewrite-upx.ts. Edit the source, not this file.
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.14.0","entry":"skills/adopt-upx/scripts/rewrite-upx.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 { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+//#region src/skill-scripts/rewrite-upx.ts
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	"build",
+	".turbo"
+]);
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/;
+const PIN_EXEMPT_PATTERN = /(^|\n)\s*pin-exempt:\s*true\s*(\n|$)/;
+const NPX_REF_PATTERN = /\bnpx(\s+(?:--yes\s+|-y\s+)?)([@a-z0-9/._-]+)@([^\s`'")]+)/g;
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 function isPinExempt(content) {
-	const match = FRONTMATTER_PATTERN.exec(content)
-	if (!match) return false
-	return PIN_EXEMPT_PATTERN.test(match[1])
+	const match = FRONTMATTER_PATTERN.exec(content);
+	if (!match) return false;
+	return PIN_EXEMPT_PATTERN.test(match[1]);
 }
-
-// `>=1.0.0` → `^<major>` (any release in that major). A `0.x` version is special: under semver a
-// `0.x` minor bump is a breaking change, so `^0` (= `>=0.0.0 <1.0.0`) is far too loose — pin the
-// minor instead with `^0.<minor>` (= that `0.<minor>.x` line only).
 function caretRange(version) {
-	const [major, minor] = version.split('.')
-	return major === '0' ? `^0.${minor}` : `^${major}`
+	const [major, minor] = version.split(".");
+	return major === "0" ? `^0.${minor}` : `^${major}`;
 }
-
 function rewriteContent(content) {
-	let changed = 0
-	const next = content.replace(NPX_REF_PATTERN, (whole, ws, pkg, version) => {
-		if (!SEMVER_PATTERN.test(version)) return whole // placeholder or dist-tag — leave alone
-		changed++
-		return `upx${ws}${pkg}@${caretRange(version)}`
-	})
-	return { next, changed }
+	let changed = 0;
+	return {
+		next: content.replace(NPX_REF_PATTERN, (whole, ws, pkg, version) => {
+			if (!SEMVER_PATTERN.test(version)) return whole;
+			changed++;
+			return `upx${ws}${pkg}@${caretRange(version)}`;
+		}),
+		changed
+	};
 }
-
 function findSkillFiles(root) {
-	const out = []
-	const st = statSync(root, { throwIfNoEntry: false })
-	if (!st) return out
+	const out = [];
+	const st = statSync(root, { throwIfNoEntry: false });
+	if (!st) return out;
 	if (st.isFile()) {
-		if (root.endsWith('SKILL.md')) out.push(root)
-		return out
+		if (root.endsWith("SKILL.md")) out.push(root);
+		return out;
 	}
 	if (st.isDirectory()) {
-		const direct = join(root, 'SKILL.md')
+		const direct = join(root, "SKILL.md");
 		if (statSync(direct, { throwIfNoEntry: false })?.isFile()) {
-			out.push(direct)
-			return out // a skill dir given directly — don't also recurse into it
+			out.push(direct);
+			return out;
 		}
-		for (const entry of readdirSync(root, { withFileTypes: true })) {
-			if (entry.isDirectory()) {
-				if (SKIP_DIRS.has(entry.name)) continue
-				out.push(...findSkillFiles(join(root, entry.name)))
-			}
+		for (const entry of readdirSync(root, { withFileTypes: true })) if (entry.isDirectory()) {
+			if (SKIP_DIRS.has(entry.name)) continue;
+			out.push(...findSkillFiles(join(root, entry.name)));
 		}
 	}
-	return out
+	return out;
 }
-
-// Minimal glob: only `*` within a single path segment (no `**`). Enough for named-set patterns
-// like `skills/foo-*` or `skills/*/SKILL.md`.
 function expandGlob(pattern) {
-	if (!pattern.includes('*')) return null
-	const segments = pattern.split('/')
-	let bases = ['.']
+	if (!pattern.includes("*")) return null;
+	const segments = pattern.split("/");
+	let bases = ["."];
 	for (const seg of segments) {
-		if (!seg.includes('*')) {
-			bases = bases.map((b) => join(b, seg))
-			continue
+		if (!seg.includes("*")) {
+			bases = bases.map((b) => join(b, seg));
+			continue;
 		}
-		const re = new RegExp('^' + seg.split('*').map(escapeRegExp).join('.*') + '$')
-		const next = []
+		const re = new RegExp("^" + seg.split("*").map(escapeRegExp).join(".*") + "$");
+		const next = [];
 		for (const b of bases) {
-			const st = statSync(b, { throwIfNoEntry: false })
-			if (!st?.isDirectory()) continue
-			for (const entry of readdirSync(b)) {
-				if (re.test(entry)) next.push(join(b, entry))
-			}
+			if (!statSync(b, { throwIfNoEntry: false })?.isDirectory()) continue;
+			for (const entry of readdirSync(b)) if (re.test(entry)) next.push(join(b, entry));
 		}
-		bases = next
+		bases = next;
 	}
-	return bases
+	return bases;
 }
-
 function escapeRegExp(value) {
-	return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-
 function resolveTargets(args) {
-	const all = args.includes('--all')
-	const dryRun = args.includes('--dry-run')
-	const positional = args.filter((a) => a !== '--all' && a !== '--dry-run')
-
-	if (all) return { files: findSkillFiles('.'), dryRun }
-
-	const files = []
+	const all = args.includes("--all");
+	const dryRun = args.includes("--dry-run");
+	const positional = args.filter((a) => a !== "--all" && a !== "--dry-run");
+	if (all) return {
+		files: findSkillFiles("."),
+		dryRun
+	};
+	const files = [];
 	for (const arg of positional) {
-		const globbed = expandGlob(arg)
-		if (globbed) {
-			for (const g of globbed) files.push(...findSkillFiles(g))
-		} else {
-			files.push(...findSkillFiles(arg))
-		}
+		const globbed = expandGlob(arg);
+		if (globbed) for (const g of globbed) files.push(...findSkillFiles(g));
+		else files.push(...findSkillFiles(arg));
 	}
-	return { files: [...new Set(files)], dryRun }
+	return {
+		files: [...new Set(files)],
+		dryRun
+	};
 }
-
 function main() {
-	const args = process.argv.slice(2)
+	const args = process.argv.slice(2);
 	if (args.length === 0) {
-		console.error('usage: rewrite-upx.mjs (--all | <path-or-glob>...) [--dry-run]')
-		process.exit(1)
+		console.error("usage: rewrite-upx.mjs (--all | <path-or-glob>...) [--dry-run]");
+		process.exit(1);
 	}
-
-	const { files, dryRun } = resolveTargets(args)
+	const { files, dryRun } = resolveTargets(args);
 	if (files.length === 0) {
-		console.error('no SKILL.md files matched — nothing to do')
-		process.exit(0)
+		console.error("no SKILL.md files matched — nothing to do");
+		process.exit(0);
 	}
-
-	let touched = 0
-	let skippedExempt = 0
+	let touched = 0;
+	let skippedExempt = 0;
 	for (const file of files) {
-		const abs = resolve(file)
-		const content = readFileSync(abs, 'utf8')
+		const abs = resolve(file);
+		const content = readFileSync(abs, "utf8");
 		if (isPinExempt(content)) {
-			skippedExempt++
-			console.log(`skip (pin-exempt): ${file}`)
-			continue
+			skippedExempt++;
+			console.log(`skip (pin-exempt): ${file}`);
+			continue;
 		}
-		const { next, changed } = rewriteContent(content)
-		if (changed === 0) continue
-		touched++
-		console.log(`${dryRun ? '[dry-run] ' : ''}rewrite (${changed}): ${file}`)
-		if (!dryRun) writeFileSync(abs, next, 'utf8')
+		const { next, changed } = rewriteContent(content);
+		if (changed === 0) continue;
+		touched++;
+		console.log(`${dryRun ? "[dry-run] " : ""}rewrite (${changed}): ${file}`);
+		if (!dryRun) writeFileSync(abs, next, "utf8");
 	}
-
-	console.log(`\n${touched} file(s) rewritten, ${skippedExempt} skipped (pin-exempt), ${files.length} scanned.`)
+	console.log(`\n${touched} file(s) rewritten, ${skippedExempt} skipped (pin-exempt), ${files.length} scanned.`);
 }
-
-main()
+main();
+//#endregion
+export {};

package/skills/build-plugin/README.md

@@ -22,7 +22,7 @@ rather than reported as success.
 ## Install
 
 Ships with the `universal-plugin` plugin. It is invoked in Claude Code as
-`/universal-plugin:build-plugin`.
+`/universal-plugin:build-plugin` (pnpm install: `pnpm-universal-plugin-build-plugin`).
 
 ## References
 

package/skills/build-plugin/SKILL.md

@@ -15,6 +15,7 @@ beside it is **derived**, and this build is the one step that writes all of it:
 | `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, `.codex-plugin/plugin.json` | Claude Code, Cursor, Codex |
 | `com.github.copilot/` (agents, commands, rules, hooks, LSP) | Copilot CLI in spec mode; the manifest itself is root `plugin.json` |
 | this plugin's entry in each marketplace catalog the repository already carries | anyone installing from the repository |
+| each declared `scripts` entry, compiled into one self-contained `.mjs` in its skill | the skill, wherever it was linked or copied to |
 
 So a change to the plugin is not done until it has been built. A runtime reads the derived files,
 not the canonical manifest, and a derived file that predates the change still ships the old plugin.
@@ -38,15 +39,15 @@ grep -n "plugin build" package.json
 
 If a script already runs `plugin build`, run that script (for example `pnpm plugin:build`). It
 carries the project's own `--root` and whatever it chains after the build, such as a formatter over
-the written JSON. Otherwise run the launcher shipped beside this skill:
+the written JSON. Otherwise run this skill's launcher:
 
 ```bash
 node scripts/build.mjs --root <plugin-root>
 ```
 
-Resolve `scripts/build.mjs` against this skill's own directory. It runs the CLI that shipped beside
-it, so nothing is downloaded and the build cannot resolve a different version from the one installed.
-`npx universal-plugin plugin build` is the fallback. `--root` defaults to the working directory and
+Resolve `scripts/build.mjs` against this skill's own directory. It runs the CLI the project installed
+(`pnpm exec universal-plugin`), else the CLI pinned to the version this skill shipped with
+(`npx universal-plugin@0.14.0`), so it works in a skill that was linked or copied on its own. `--root` defaults to the working directory and
 must name the directory that holds the canonical `plugin.json`.
 
 The command never prompts, so it is safe to run unattended.
@@ -73,6 +74,12 @@ Default stdout is TOON: one row per vendor (`vendor, path, status`), one row per
 | `canonical` | Copilot CLI with nothing to derive: root `plugin.json` serves it directly |
 | `skipped` / `failed` | the row says why; fix that and rebuild |
 
+A script row (`path, status`) reads `compiled` or `unchanged`. On `--dry-run` it reads `unchanged`,
+`missing`, `stale` (its source moved on), or `version` (only its embedded version did, which
+`publish check-version` reports). A `failed` row is an entry that could not be made self-contained,
+usually an import that does not resolve; the build exits 1 and the warning names it. A script over
+150 KB warns: the skill should call the installed CLI instead of compiling it in.
+
 A catalog row reads `updated`, `unchanged`, or `planned` on `--dry-run`. A build **never creates** a
 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`.
@@ -84,7 +91,8 @@ 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, a dependency the catalog cannot resolve. Each warning names something that will not reach a runtime. Tell the user each
+invalid catalog, a dependency the catalog cannot resolve, a skill link that climbs out of the skill
+folder. 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
@@ -100,7 +108,7 @@ derived files together:
 git status --short
 ```
 
-Expect the vendor manifests, `com.github.copilot/`, and any refreshed catalog. A diff outside those paths did not come from the build.
+Expect the vendor manifests, `com.github.copilot/`, any refreshed catalog, and any compiled script. A diff outside those paths did not come from the build.
 
 ## Guards
 
@@ -120,8 +128,8 @@ Validation runs before the first write, so a failed build leaves the tree untouc
 - **Edit `plugin.json` to get a different derived manifest.** A per-vendor field belongs under
   `extensions["org.cyberuni.universal-plugin"].harnesses.<vendor>`. That is a declaration, and
   `init-universal-plugin` owns it.
-- **Expect a build to pin skill `npx` references.** That is the release-time `plugin bundle`, not
-  this step.
+- **Expect a build to pin skill `npx` references or decide a version.** Build derives and copies
+  whatever `plugin.json` carries. Stamping is the release-time `plugin version`, not this step.
 - **Expect a build to copy governances into skills.** A skill loads a reference through the
   `reference` skill in the `cyber-agent-harness` plugin; the build does not copy them and has no
   `--check` flag.
@@ -141,3 +149,4 @@ Validation runs before the first write, so a failed build leaves the tree untouc
 - Spec: [`plugin/build/`](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/plugin/build/README.md)
 - [ADR-0014](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0014-build-refreshes-catalogs.md): the build refreshes catalogs it finds
 - [ADR-0017](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0017-retire-governance-for-reference.md): the build no longer copies governances into skills
+- [ADR-0019](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0019-build-compiles-skill-scripts.md): the build compiles skill script entries into committed `.mjs`

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.14.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 {};