universal-plugin 0.6.0 → 0.8.0

package/dist/run.mjs

@@ -1,271 +0,0 @@
-#!/usr/bin/env node
-import * as fsNode from "node:fs";
-import * as path from "node:path";
-import * as semver$1 from "semver";
-import { spawnSync } from "node:child_process";
-//#region src/run/fs.ts
-function readInstall(dir) {
-	try {
-		const raw = fsNode.readFileSync(path.join(dir, "package.json"), "utf8");
-		const pkg = JSON.parse(raw);
-		if (typeof pkg.version !== "string") return void 0;
-		return {
-			dir,
-			version: pkg.version,
-			bin: pkg.bin
-		};
-	} catch {
-		return;
-	}
-}
-function packageDirIn(nodeModulesDir, pkg) {
-	return path.join(nodeModulesDir, ...pkg.split("/"));
-}
-/** Every ancestor `node_modules` directory from `startDir` up to the filesystem root, nearest
-*  first. */
-function ancestorNodeModulesDirs(startDir) {
-	const dirs = [];
-	let dir = startDir;
-	for (;;) {
-		dirs.push(path.join(dir, "node_modules"));
-		const parent = path.dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
-	}
-	return dirs;
-}
-/** Walks `node_modules` from `cwd` up through its ancestors, nearest first, collecting every
-*  install of `pkg` found along the way (an install missing a readable `package.json` version is
-*  skipped, not a match). */
-function findLocalInstalls(pkg, cwd) {
-	const installs = [];
-	for (const nodeModulesDir of ancestorNodeModulesDirs(cwd)) {
-		const install = readInstall(packageDirIn(nodeModulesDir, pkg));
-		if (install) installs.push(install);
-	}
-	return installs;
-}
-function globalRoot() {
-	try {
-		const out = spawnSync("npm", ["root", "-g"], { encoding: "utf8" }).stdout?.trim();
-		return out ? out : void 0;
-	} catch {
-		return;
-	}
-}
-function findGlobalInstall(pkg) {
-	const root = globalRoot();
-	if (!root) return void 0;
-	return readInstall(packageDirIn(root, pkg));
-}
-function spawnBin(binPath, args) {
-	const result = spawnSync(binPath, args, { stdio: "inherit" });
-	if (result.error) throw result.error;
-	return result.status ?? 1;
-}
-function spawnNpx(args) {
-	const result = spawnSync("npx", args, { stdio: "inherit" });
-	if (result.error) throw result.error;
-	return result.status ?? 1;
-}
-function realRunFs() {
-	return {
-		findLocalInstalls: (pkg) => findLocalInstalls(pkg, process.cwd()),
-		findGlobalInstall,
-		spawnBin,
-		spawnNpx
-	};
-}
-//#endregion
-//#region src/run/run.ts
-const NPM_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
-/** A loose approximation of npm's package-name rules: lowercase, alphanumeric/`.`/`_`/`-`, an
-*  optional `@scope/` prefix, non-empty. Good enough to reject the obviously malformed without
-*  chasing every edge npm itself enforces. */
-function isValidPackageName(name) {
-	if (!name || name.length > 214) return false;
-	return NPM_NAME_PATTERN.test(name);
-}
-/** Splits `<pkg>@<range>` on the **last** `@` at index > 0, so a scoped name's leading `@` survives.
-*  No `@` after index 0 — or a trailing `@` with an empty range — is a bare package (range `*`). A
-*  package name that is empty or violates npm's naming rules is a fail-loud error. */
-function parseSpec(spec) {
-	if (!spec) return {
-		ok: false,
-		error: "error: no package spec given"
-	};
-	const lastAt = spec.lastIndexOf("@");
-	let pkg;
-	let rangeRaw;
-	if (lastAt <= 0) {
-		pkg = spec;
-		rangeRaw = "";
-	} else {
-		pkg = spec.slice(0, lastAt);
-		rangeRaw = spec.slice(lastAt + 1);
-	}
-	if (!isValidPackageName(pkg)) return {
-		ok: false,
-		error: `error: unparseable package spec "${spec}"`
-	};
-	const bare = rangeRaw === "";
-	return {
-		ok: true,
-		spec: {
-			pkg,
-			range: bare ? "*" : rangeRaw,
-			bare
-		}
-	};
-}
-/** A valid semver range drives local-first matching; a non-empty non-semver spec (`next`,
-*  `latest`) is a dist-tag that can't be matched against an installed `package.json` version. */
-function isSemverRange(range) {
-	return semver$1.validRange(range) !== null;
-}
-/** Nearest-local → global, first install whose version satisfies `range`. `locals` must already be
-*  nearest-first. */
-function selectInstall(range, locals, globalInstall) {
-	for (const install of locals) if (semver$1.satisfies(install.version, range)) return install;
-	if (globalInstall && semver$1.satisfies(globalInstall.version, range)) return globalInstall;
-}
-/** Resolves the executable from a `package.json` `bin` field: a string bin, an object entry keyed
-*  by the package's unscoped name (even among several bins), or a single-entry object. A
-*  multi-entry object with no name match, or a missing `bin` field entirely, fails loud — `upx`
-*  never guesses which bin to run. */
-function resolveBinPath(pkgName, bin) {
-	if (bin === void 0) return {
-		ok: false,
-		error: `error: package "${pkgName}" declares no bin field`
-	};
-	if (typeof bin === "string") return {
-		ok: true,
-		bin
-	};
-	const entries = Object.entries(bin);
-	if (entries.length === 0) return {
-		ok: false,
-		error: `error: package "${pkgName}" declares no bin field`
-	};
-	if (entries.length === 1) return {
-		ok: true,
-		bin: entries[0][1]
-	};
-	const match = bin[pkgName.includes("/") ? pkgName.slice(pkgName.lastIndexOf("/") + 1) : pkgName] ?? bin[pkgName];
-	if (match) return {
-		ok: true,
-		bin: match
-	};
-	return {
-		ok: false,
-		error: `error: package "${pkgName}" declares multiple bins and none matches its name — upx never guesses which to run`
-	};
-}
-const KNOWN_LEADING_FLAGS = new Set(["--help", "-h"]);
-/** A flag is a token starting with `-`; `upx`'s own flags are recognized only before the first
-*  non-flag token (the package spec) — everything from the spec onward belongs to the child. An
-*  unknown flag before the spec fails loud. */
-function parseArgv(argv) {
-	if (argv.length === 0) return {
-		ok: false,
-		error: "error: no package spec given"
-	};
-	const first = argv[0];
-	if (first.startsWith("-")) {
-		if (KNOWN_LEADING_FLAGS.has(first)) return {
-			ok: true,
-			args: {
-				help: true,
-				spec: void 0,
-				childArgs: []
-			}
-		};
-		return {
-			ok: false,
-			error: `error: unknown flag "${first}"`
-		};
-	}
-	return {
-		ok: true,
-		args: {
-			help: false,
-			spec: first,
-			childArgs: argv.slice(1)
-		}
-	};
-}
-function fallbackNotice(pkg, range) {
-	return `upx: no installed ${pkg} satisfies "${range}", using npx`;
-}
-/** A dist-tag (`next`, `latest`) is not a version range, so the miss notice must not claim the
-*  installed versions failed to "satisfy" it — it never could. Keeps the fixed
-*  `upx: no installed <pkg>` prefix shared with {@link fallbackNotice}. */
-function distTagNotice(pkg, tag) {
-	return `upx: no installed ${pkg}; "${tag}" is a dist-tag, using npx`;
-}
-const HELP_TEXT = `Usage: upx <pkg>@<range> [args…]
-
-Runs a package's CLI from a local or global install matching <range>, falling
-back to npx when nothing installed satisfies it.
-
-Example:
-  $ upx cyberplace@^1.0.0 build
-`;
-/** Resolves `argv` (everything after `upx`) to a running child, per the Resolution algorithm in
-*  the spec: parse → classify the range → search local-then-global → resolve the bin → spawn, or
-*  fall back to npx with the spec exactly as given. */
-function runUpx(argv, fs) {
-	const parsedArgv = parseArgv(argv);
-	if (!parsedArgv.ok) return {
-		kind: "error",
-		message: parsedArgv.error
-	};
-	if (parsedArgv.args.help) return {
-		kind: "help",
-		text: HELP_TEXT
-	};
-	const specResult = parseSpec(parsedArgv.args.spec);
-	if (!specResult.ok) return {
-		kind: "error",
-		message: specResult.error
-	};
-	const { pkg, range, bare } = specResult.spec;
-	const childArgs = parsedArgv.args.childArgs;
-	const semverRange = isSemverRange(range);
-	if (semverRange) {
-		const install = selectInstall(range, fs.findLocalInstalls(pkg), fs.findGlobalInstall(pkg));
-		if (install) {
-			const binResult = resolveBinPath(pkg, install.bin);
-			if (!binResult.ok) return {
-				kind: "error",
-				message: binResult.error
-			};
-			const binPath = path.join(install.dir, binResult.bin);
-			return {
-				kind: "exit",
-				code: fs.spawnBin(binPath, childArgs)
-			};
-		}
-	}
-	const npxSpec = bare ? pkg : `${pkg}@${range}`;
-	return {
-		kind: "exit",
-		code: fs.spawnNpx([npxSpec, ...childArgs]),
-		notice: semverRange ? fallbackNotice(pkg, range) : distTagNotice(pkg, range)
-	};
-}
-//#endregion
-//#region src/run/cli.ts
-const outcome = runUpx(process.argv.slice(2), realRunFs());
-if (outcome.kind === "help") {
-	process.stdout.write(outcome.text);
-	process.exit(0);
-}
-if (outcome.kind === "error") {
-	process.stderr.write(`${outcome.message}\n`);
-	process.exit(1);
-}
-if (outcome.notice) process.stderr.write(`${outcome.notice}\n`);
-process.exit(outcome.code);
-//#endregion
-export {};

package/skills/init/references/adopt.md

@@ -1,118 +0,0 @@
-# Adopt the open standard
-
-Convert something that is *already* a plugin — or already ships skills — onto the canonical
-Agent Plugins Specification manifest, without changing what it does.
-
-Two starting shapes land here:
-
-- **A vendor-specific plugin** — it has one or more hand-written vendor manifests
-  (`.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, …) and no canonical root
-  `plugin.json`.
-- **Bare public skills** — it ships `skills/<name>/SKILL.md` to users but has no plugin manifest of
-  any kind.
-
-Adoption is **lossless by contract**: every vendor that worked before must still work after. Step 6
-is the check that proves it — do not skip it.
-
-## Step 0 — Confirm the user wants this
-
-This is the skill's Phase 3 gate, and adoption always needs it: adoption rewrites the project's
-manifest layout and turns hand-written vendor manifests into generated artifacts. Say that plainly
-and get agreement before touching files. If the user declines,
-route back to whatever they originally asked for.
-
-Also confirm the working tree is clean (`git status`). The Step 6 diff is worthless if uncommitted
-changes are mixed in.
-
-## Step 1 — Inventory what exists
-
-```bash
-ls -d .claude-plugin .cursor-plugin .codex-plugin .github/plugin .plugin 2>/dev/null
-test -f plugin.json && cat plugin.json
-find . -name SKILL.md -not -path '*/node_modules/*' -not -path './.git/*'
-ls .mcp.json .lsp.json hooks/ commands/ agents/ rules/ output-styles/ 2>/dev/null
-```
-
-Record, for each vendor manifest found: its path, and every field it sets. You are about to
-reproduce all of it.
-
-**If a root `plugin.json` already exists**, read it before assuming anything. It is either the
-canonical manifest (has `$schema` pointing at `agent-plugins.org` and an `extensions` object — in
-which case there is nothing to adopt; route to `update.md`, or hand off to `doctor`, instead), or a legacy
-Copilot CLI manifest that now collides with the canonical path and must be folded in.
-
-## Step 2 — Sort every field into shared vs vendor-specific
-
-Build two buckets from the manifests you inventoried:
-
-- **Shared metadata** — `name`, `version`, `description`, `author`, `homepage`, `repository`,
-  `license`, `keywords`, and the component paths. These go at the canonical top level.
-- **Vendor-specific** — anything only one runtime understands (Cursor's `publisher`/`category`/
-  `tags`, Codex's `interface`, Copilot's `category`/`tags`). These go under
-  `extensions["org.cyberuni.universal-plugin"].harnesses.<vendor>`.
-
-Where two vendor manifests disagree on a shared field, **ask the user** which value is canonical
-rather than picking one. A silent choice here is a silent behavior change for one of their runtimes.
-
-## Step 3 — Write the canonical manifest
-
-Scaffold it, naming exactly the vendors you found in Step 1:
-
-```bash
-node scripts/init.mjs --name <name> --vendor claude-code --vendor cursor
-```
-
-Resolve `scripts/init.mjs` against this skill's directory; `npx universal-plugin plugin init` is the
-fallback.
-
-> `plugin init` writes a **minimal** manifest — `$schema`, `name`, and the `vendors` list. It does
-> not read your existing vendor manifests. Carry the Step 2 buckets in by hand afterwards.
-
-Then fill in the shared metadata and `harnesses` as laid out in
-[`create.md`](./create.md) Step 5. Point the component paths at the directories that already exist —
-adoption must not move files.
-
-For the bare-public-skills case there is no metadata to carry over; supply `name`, `description`,
-and `version`, set `"skills": "./skills/"`, and choose vendors with the user (see
-[`create.md`](./create.md) Step 2).
-
-## Step 4 — Decide what happens to the old manifests
-
-The vendor manifests are now **build outputs**. They stay at the same paths, but they are
-regenerated rather than edited.
-
-- Commit them as-is first, so Step 6 has a baseline to diff against.
-- Tell the user they are generated from here on, and that hand-edits will be overwritten by
-  `plugin build`.
-- If the project has a legacy root `plugin.json` for Copilot CLI, that path is now the canonical
-  manifest — its derived Copilot output moves elsewhere. Check the vendor output table in
-  [`create.md`](./create.md) Step 2 for the current path.
-
-## Step 5 — Build
-
-```bash
-npx universal-plugin plugin build
-```
-
-## Step 6 — Prove it was lossless
-
-This is the point of the whole procedure.
-
-```bash
-git diff -- .claude-plugin .cursor-plugin .codex-plugin .github/plugin
-```
-
-Read every line of that diff. Expect only formatting and key-order churn.
-
-**Any field that disappeared is a regression**, not a cleanup. Trace it back: either it belongs in
-the shared metadata, or it belongs in that vendor's `harnesses` entry, or it is a field the build
-does not yet support — in which case stop and tell the user rather than shipping a quiet
-capability loss.
-
-Then confirm the plugin still loads. See [`create.md`](./create.md) Step 8 for local install.
-
-## Step 7 — Hand off
-
-- Audit the skills: [`create.md`](./create.md) Step 6.
-- Shipping it on npm? → `migrate-plugin`.
-- Listing it in the marketplace? → `publish-plugin`.

package/skills/init/references/vendors/copilot-cli.md

@@ -1,53 +0,0 @@
-# GitHub Copilot CLI
-
-Reads the **canonical root `plugin.json` directly**. The build derives nothing for it and writes no
-file — `plugin build` reports it with status `canonical`, which is success, not a skipped target.
-
-## Why nothing is derived
-
-Copilot CLI searches four paths and takes the first match:
-
-```
-.plugin/plugin.json → plugin.json → .github/plugin/plugin.json → .claude-plugin/plugin.json
-```
-
-Root `plugin.json` — the canonical manifest — is second, so it always shadows the two below it. It
-has consumed Open Plugin Spec v1 manifests since v1.0.74, so it already serves the canonical manifest
-as-is.
-
-Earlier builds wrote `.github/plugin/plugin.json`. That path loses to root by construction and was
-never read; a leftover copy is stale and safe to delete.
-
-## Vendor-specific fields cannot be delivered
-
-A `harnesses["copilot-cli"]` entry has nowhere to go. The canonical schema is closed
-(`additionalProperties: false`), so a Copilot-only field cannot ride along in root, and there is no
-derived file to put it in. The build warns:
-
-```
-harnesses.copilot-cli sets category, tags, but copilot-cli reads the canonical plugin.json
-directly — these fields are not delivered
-```
-
-Treat that warning as a decision to make, not noise: either the field belongs to a vendor that has a
-derived manifest, or it does not ship. Do not invent a path for it.
-
-## Do not
-
-- **Do not delete root `plugin.json` to "clean up" a Copilot target.** It is the source of truth and
-  the Copilot manifest at once.
-- Do not write `.plugin/plugin.json`. It outranks root, so it would silently shadow the canonical
-  manifest with a copy nothing regenerates.
-
-## Hooks
-
-Copilot CLI accepts **either casing**, and the casing selects the payload format: PascalCase gets the
-Claude-compatible format, so the canonical file reaches Copilot CLI unchanged. Because Copilot CLI
-reads that file directly, the build derives nothing for it — an `agent` handler is reported as ignored
-at runtime rather than dropped. See [`claude-code.md`](./claude-code.md).
-
-## Dependencies
-
-Copilot CLI reads no plugin dependency. Because it reads the canonical manifest directly, there is no
-derived file to leave the declaration out of — it sits under `extensions`, which Copilot CLI ignores,
-and the build reports it as ignored at runtime. See [`claude-code.md`](./claude-code.md).