universal-plugin 0.2.1 → 0.2.2

package/dist/cli.mjs

@@ -8,8 +8,12 @@ import * as childProcess from "node:child_process";
 //#region src/cli-options.ts
 /** Repo root; resolves to cwd when omitted. */
 const ROOT_OPTION = new Option("--root <path>", "Plugin root directory");
+/** Resolves `--root` to an absolute path (cwd when omitted). Absolute is the contract: a relative
+*  root such as `.` breaks any ancestor walk downstream (`path.dirname('.') === '.'` terminates the
+*  walk on its first step), which would make the same operation behave differently depending on the
+*  cwd it was invoked from. */
 function resolveRoot(root) {
-	return root ?? process.cwd();
+	return root === void 0 ? process.cwd() : path.resolve(root);
 }
 //#endregion
 //#region src/state/state.ts
@@ -186,138 +190,13 @@ function output(data, readable) {
 	else readable();
 }
 //#endregion
-//#region src/pin/fs.ts
-const TEXT_EXTENSIONS = new Set([
-	".md",
-	".mdx",
-	".markdown",
-	".json",
-	".yaml",
-	".yml",
-	".txt"
-]);
-/** Resolves the plugin's skills directory: the manifest's `skills` field under `root`,
-*  defaulting to `<root>/skills/`. */
-function resolveSkillsDir(root, manifestSkills) {
-	return path.join(root, manifestSkills ?? "skills/");
-}
-function walk(dir) {
-	if (!fsNode.existsSync(dir)) return [];
-	const files = [];
-	for (const entry of fsNode.readdirSync(dir, { withFileTypes: true })) {
-		const entryPath = path.join(dir, entry.name);
-		if (entry.isDirectory()) files.push(...walk(entryPath));
-		else if (entry.isFile() && TEXT_EXTENSIONS.has(path.extname(entry.name))) files.push(entryPath);
-	}
-	return files;
-}
-function realPinFs(skillsDir) {
-	return {
-		listSkillFiles: () => walk(skillsDir),
-		readFile: (p) => fsNode.readFileSync(p, "utf8"),
-		writeFile: (p, c) => fsNode.writeFileSync(p, c, "utf8")
-	};
-}
-//#endregion
-//#region src/pin/pin.ts
-const PIN_PATTERN = /npx\s+(?:--yes\s+|-y\s+)?([@a-z0-9/._-]+)@(\S+)/g;
-/** Strips a trailing backtick, quote, or paren that isn't part of the version token. */
-function stripTrailing(raw) {
-	return raw.replace(/[`'")]+$/, "");
-}
-function extractPins(text) {
-	const pins = [];
-	for (const match of text.matchAll(PIN_PATTERN)) {
-		const pkg = match[1];
-		const current = match[2];
-		if (!pkg || !current) continue;
-		pins.push({
-			pkg,
-			current: stripTrailing(current),
-			file: ""
-		});
-	}
-	return pins;
-}
-const SEMVER_PATTERN = /^[~^]?\d+\.\d+\.\d+$/;
-function isValidSemver(version) {
-	return SEMVER_PATTERN.test(version);
-}
-/** True when a pin is a concrete version (optionally range-prefixed), not a placeholder like `<version>`. */
-function isConcreteVersion(version) {
-	return isValidSemver(version);
-}
-function majorOf(version) {
-	const [major] = version.replace(/^[~^]/, "").split(".");
-	return Number(major);
-}
-/** Pure semver compare: -1 if a < b, 0 if equal, 1 if a > b. Ignores build/prerelease metadata. */
-function compareSemver(a, b) {
-	const partsA = a.split(".").map(Number);
-	const partsB = b.split(".").map(Number);
-	for (let i = 0; i < 3; i++) {
-		const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0);
-		if (diff !== 0) return diff > 0 ? 1 : -1;
-	}
-	return 0;
-}
-function pickTarget(current, available, opts) {
-	if (!isValidSemver(current)) return available.latest;
-	const currentBare = current.replace(/^[~^]/, "");
-	const currentMajor = majorOf(current);
-	const candidates = available.versions.filter((v) => {
-		if (!isValidSemver(v)) return false;
-		if (opts.allowMajor) return true;
-		return majorOf(v) === currentMajor;
-	});
-	if (candidates.length === 0) return currentBare;
-	let best = candidates[0];
-	for (const candidate of candidates.slice(1)) if (compareSemver(candidate, best) > 0) best = candidate;
-	if (compareSemver(best, currentBare) < 0) return currentBare;
-	return best;
-}
-function styleRange(version, style) {
-	switch (style) {
-		case "exact": return version;
-		case "tilde": return `~${version}`;
-		case "caret": return `^${version}`;
-	}
-}
-function normalizeRange(raw) {
-	switch (raw) {
-		case "exact": return "exact";
-		case "tilde":
-		case "~": return "tilde";
-		case "caret":
-		case "^": return "caret";
-		default: throw new Error(`Invalid --range value "${raw}" — expected exact, tilde, caret, ~, or ^`);
-	}
-}
-//#endregion
-//#region src/pin/registry.ts
-function encodePkg(pkg) {
-	return pkg.replace("/", "%2f");
-}
-/** Registry client backed by the global `fetch` (Node ≥22). Resilient — network errors and
-*  non-2xx responses resolve to `null` rather than throwing. */
-function realRegistryClient(registryBase) {
-	const base = registryBase.replace(/\/+$/, "");
-	return { async fetchVersions(pkg) {
-		try {
-			const res = await fetch(`${base}/${encodePkg(pkg)}`);
-			if (!res.ok) return null;
-			const doc = await res.json();
-			const latest = doc["dist-tags"]?.latest;
-			const versions = doc.versions ? Object.keys(doc.versions) : [];
-			if (!latest) return null;
-			return {
-				latest,
-				versions
-			};
-		} catch {
-			return null;
-		}
-	} };
+//#region src/json.ts
+/** Detects indentation style from JSON text. Returns `'\t'` for tabs or a number for space count.
+*  Falls back to `'\t'` when no indentation is detected. */
+function detectIndent(json) {
+	const match = json.match(/\n([ \t]+)/);
+	if (!match) return "	";
+	return match[1].startsWith("	") ? "	" : match[1].length;
 }
 //#endregion
 //#region src/build/build.ts
@@ -328,11 +207,6 @@ const VENDOR_OUTPUT = {
 	"copilot-cli": "plugin.json"
 };
 const KNOWN_VENDORS = new Set(Object.keys(VENDOR_OUTPUT));
-function detectIndent$1(json) {
-	const match = json.match(/\n([ \t]+)/);
-	if (!match) return "	";
-	return match[1].startsWith("	") ? "	" : match[1].length;
-}
 function readManifest(root) {
 	const manifestPath = path.join(root, ".plugin", "plugin.json");
 	if (!fsNode.existsSync(manifestPath)) throw new Error(`No .plugin/plugin.json found at ${root}`);
@@ -348,15 +222,21 @@ function validateManifest(manifest) {
 function buildPlugin(root, opts = {}) {
 	const manifestPath = path.join(root, ".plugin", "plugin.json");
 	if (!fsNode.existsSync(manifestPath)) throw new Error(`No .plugin/plugin.json found at ${root}`);
-	const indent = detectIndent$1(fsNode.readFileSync(manifestPath, "utf8"));
+	const indent = detectIndent(fsNode.readFileSync(manifestPath, "utf8"));
 	const manifest = readManifest(root);
 	const errors = validateManifest(manifest);
 	if (errors.length > 0) throw new Error(`plugin.json validation failed:\n${errors.map((e) => `  - ${e}`).join("\n")}`);
 	const warnings = [];
+	const rows = [];
 	const vendorExtensions = manifest.vendorExtensions ?? {};
 	let vendors = Object.keys(vendorExtensions).filter((v) => {
 		if (!KNOWN_VENDORS.has(v)) {
 			warnings.push(`Unknown vendor "${v}" in vendorExtensions — skipped`);
+			rows.push({
+				vendor: v,
+				path: "-",
+				status: "skipped"
+			});
 			return false;
 		}
 		return true;
@@ -370,13 +250,16 @@ function buildPlugin(root, opts = {}) {
 		return {
 			vendors: [],
 			written: [],
-			warnings
+			warnings,
+			rows,
+			summary: summarize(rows)
 		};
 	}
 	const written = [];
 	const { vendorExtensions: _ext, $schema: _schema, ...canonical } = manifest;
 	for (const vendor of vendors) {
-		const outputPath = path.join(root, VENDOR_OUTPUT[vendor]);
+		const relPath = VENDOR_OUTPUT[vendor];
+		const outputPath = path.join(root, relPath);
 		const outputDir = path.dirname(outputPath);
 		const vendorFields = vendorExtensions[vendor] ?? {};
 		const vendorManifest = {
@@ -387,126 +270,391 @@ function buildPlugin(root, opts = {}) {
 			console.log(`[${vendor}] → ${outputPath}`);
 			for (const key of Object.keys(vendorFields)) console.log(`  + ${key} (from vendorExtensions)`);
 		}
-		if (!opts.dryRun) {
-			if (opts.clean && fsNode.existsSync(outputPath)) fsNode.unlinkSync(outputPath);
-			fsNode.mkdirSync(outputDir, { recursive: true });
-			fsNode.writeFileSync(outputPath, `${JSON.stringify(vendorManifest, null, indent)}\n`);
+		try {
+			if (!opts.dryRun) {
+				if (opts.clean && fsNode.existsSync(outputPath)) fsNode.unlinkSync(outputPath);
+				fsNode.mkdirSync(outputDir, { recursive: true });
+				fsNode.writeFileSync(outputPath, `${JSON.stringify(vendorManifest, null, indent)}\n`);
+			}
+			written.push(outputPath);
+			rows.push({
+				vendor,
+				path: relPath,
+				status: "built"
+			});
+		} catch (err) {
+			warnings.push(`Failed to write "${vendor}" → ${relPath}: ${err instanceof Error ? err.message : String(err)}`);
+			rows.push({
+				vendor,
+				path: relPath,
+				status: "failed"
+			});
 		}
-		written.push(outputPath);
 	}
 	return {
 		vendors,
 		written,
-		warnings
+		warnings,
+		rows,
+		summary: summarize(rows)
+	};
+}
+function summarize(rows) {
+	return {
+		built: rows.filter((r) => r.status === "built").length,
+		skipped: rows.filter((r) => r.status === "skipped").length,
+		failed: rows.filter((r) => r.status === "failed").length
+	};
+}
+//#endregion
+//#region src/build/cli.ts
+const NEXT_STEP$1 = "→ universal-plugin plugin validate\n";
+function buildCommand() {
+	const cmd = new Command("build").description("Generate vendor manifests from .plugin/plugin.json");
+	cmd.option("--vendor <id>", "Build only the named vendor").option("--dry-run", "Print what would be written without writing").option("--verbose", "Print field-by-field transformation decisions").option("--clean", "Delete generated manifests before building").option("--format <format>", "Output format: json or toon (default: toon)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin build --vendor claude-code\n").action((opts) => {
+		try {
+			const result = buildPlugin(resolveRoot(opts.root), {
+				vendor: opts.vendor,
+				dryRun: opts.dryRun,
+				verbose: opts.verbose,
+				clean: opts.clean
+			});
+			for (const warning of result.warnings) process.stderr.write(`warn: ${warning}\n`);
+			const { built, skipped, failed } = result.summary;
+			output({
+				built: result.rows.filter((r) => r.status === "built"),
+				skipped: result.rows.filter((r) => r.status === "skipped"),
+				failed: result.rows.filter((r) => r.status === "failed"),
+				summary: result.summary,
+				warnings: result.warnings
+			}, () => {
+				if (result.rows.length > 0) printTable(result.rows, [
+					{
+						label: "vendor",
+						get: (r) => r.vendor
+					},
+					{
+						label: "path",
+						get: (r) => r.path
+					},
+					{
+						label: "status",
+						get: (r) => r.status
+					}
+				]);
+				console.log(`built ${built}, skipped ${skipped}, failed ${failed}`);
+			});
+			process.stderr.write(NEXT_STEP$1);
+			if (failed > 0) process.exitCode = 1;
+		} catch (err) {
+			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+			process.exit(1);
+		}
+	});
+	return cmd;
+}
+//#endregion
+//#region src/pin/fs.ts
+const TEXT_EXTENSIONS = new Set([
+	".md",
+	".mdx",
+	".markdown",
+	".json",
+	".yaml",
+	".yml",
+	".txt"
+]);
+/** Resolves the plugin's skills directory: the manifest's `skills` field under `root`,
+*  defaulting to `<root>/skills/`. */
+function resolveSkillsDir(root, manifestSkills) {
+	return path.join(root, manifestSkills ?? "skills/");
+}
+function walk(dir) {
+	if (!fsNode.existsSync(dir)) return [];
+	const files = [];
+	for (const entry of fsNode.readdirSync(dir, { withFileTypes: true })) {
+		const entryPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) files.push(...walk(entryPath));
+		else if (entry.isFile() && TEXT_EXTENSIONS.has(path.extname(entry.name))) files.push(entryPath);
+	}
+	return files;
+}
+function realPinFs(skillsDir) {
+	return {
+		listSkillFiles: () => walk(skillsDir),
+		readFile: (p) => fsNode.readFileSync(p, "utf8"),
+		writeFile: (p, c) => fsNode.writeFileSync(p, c, "utf8")
 	};
 }
+//#endregion
+//#region src/pin/pin.ts
+const PIN_PATTERN = /npx\s+(?:--yes\s+|-y\s+)?([@a-z0-9/._-]+)@(\S+)/g;
+/** Strips a trailing backtick, quote, or paren that isn't part of the version token. */
+function stripTrailing(raw) {
+	return raw.replace(/[`'")]+$/, "");
+}
+function extractPins(text) {
+	const pins = [];
+	for (const match of text.matchAll(PIN_PATTERN)) {
+		const pkg = match[1];
+		const current = match[2];
+		if (!pkg || !current) continue;
+		pins.push({
+			pkg,
+			current: stripTrailing(current),
+			file: ""
+		});
+	}
+	return pins;
+}
+//#endregion
+//#region src/bundle/bundle.ts
 function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-/** Rewrites every `npx <pkg>@<anything>` occurrence to `npx <pkg>@<next>`, regardless of the
-*  version each occurrence currently carries — so a plugin's references to one CLI converge
-*  (a concrete pin, a placeholder, and a stale pin all land on the same resolved value). */
+/** Rewrites every `npx <pkg>@<anything>` occurrence in `content` to `npx <pkg>@<next>`, regardless
+*  of whether the occurrence is a concrete version or a placeholder like `<version>` — so every
+*  reference to one CLI converges on the same resolved value. */
 function rewritePin(content, pkg, next) {
 	const pattern = new RegExp(`(npx\\s+(?:--yes\\s+|-y\\s+)?${escapeRegExp(pkg)}@)[^\\s\`'")]+`, "g");
 	return content.replace(pattern, `$1${next}`);
 }
-/** Scans the plugin's skills for `npx <pkg>@<pin>` references and resolves each distinct
-*  in-scope package's current version from the registry, rewriting the pins in place. */
-async function resolvePins(root, opts, client, pinFs) {
-	const range = opts.range ?? "exact";
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/;
+const PIN_EXEMPT_PATTERN = /(^|\n)\s*pin-exempt:\s*true\s*(\n|$)/;
+/** True when a SKILL.md's frontmatter declares `metadata.pin-exempt: true` — its version strings
+*  are documentation/illustration, never rewritten by `bundle`. Nesting under `metadata` is not
+*  enforced structurally (no YAML dependency); the key's presence anywhere in the frontmatter block
+*  is the marker. */
+function isPinExempt(skillMdContent) {
+	const match = skillMdContent.match(FRONTMATTER_PATTERN);
+	if (!match) return false;
+	return PIN_EXEMPT_PATTERN.test(match[1]);
+}
+function dirOf(filePath) {
+	const idx = Math.max(filePath.lastIndexOf("/"), filePath.lastIndexOf("\\"));
+	return idx === -1 ? "" : filePath.slice(0, idx);
+}
+function isUnderExemptDir(filePath, exemptDirs) {
+	for (const dir of exemptDirs) if (filePath.startsWith(`${dir}/`) || filePath.startsWith(`${dir}\\`)) return true;
+	return false;
+}
+/** Scans the plugin's skills for `npx <pkg>@<pin>` references and, for each in-scope package that
+*  resolves against the workspace, rewrites every occurrence to that package's local version. A
+*  pin-exempt skill (and every file under its directory) is excluded entirely — never scanned,
+*  never rewritten, never reported. */
+function bundlePins(pinFs, versionSource, opts = {}) {
 	const files = pinFs.listSkillFiles();
 	const contents = /* @__PURE__ */ new Map();
-	const currentsByPkg = /* @__PURE__ */ new Map();
+	for (const file of files) contents.set(file, pinFs.readFile(file));
+	const exemptDirs = /* @__PURE__ */ new Set();
 	for (const file of files) {
-		const content = pinFs.readFile(file);
-		contents.set(file, content);
-		for (const pin of extractPins(content)) {
-			const list = currentsByPkg.get(pin.pkg) ?? [];
-			list.push(pin.current);
-			currentsByPkg.set(pin.pkg, list);
-		}
+		if (!file.endsWith("/SKILL.md") && !file.endsWith("\\SKILL.md")) continue;
+		if (isPinExempt(contents.get(file))) exemptDirs.add(dirOf(file));
 	}
-	const scope = opts.packages && opts.packages.length > 0 ? new Set(opts.packages) : null;
-	const inScope = [...currentsByPkg.entries()].filter(([pkg]) => !scope || scope.has(pkg));
-	const results = [];
-	results.warnings = [];
-	for (const [pkg, currents] of inScope) {
-		const anchor = currents.find(isConcreteVersion) ?? currents[0];
-		const available = await client.fetchVersions(pkg);
-		if (!available) {
-			results.warnings.push(`registry lookup for "${pkg}" failed — skipped`);
-			results.push({
+	const inScope = files.filter((file) => !isUnderExemptDir(file, exemptDirs));
+	const currentsByPkg = /* @__PURE__ */ new Map();
+	for (const file of inScope) for (const pin of extractPins(contents.get(file))) {
+		const list = currentsByPkg.get(pin.pkg) ?? [];
+		list.push(pin.current);
+		currentsByPkg.set(pin.pkg, list);
+	}
+	const warnings = [];
+	const pins = [];
+	for (const [pkg, currents] of currentsByPkg) {
+		const current = currents[0];
+		const lookup = versionSource.resolve(pkg);
+		if (!lookup.inWorkspace) {
+			pins.push({
 				package: pkg,
-				current: anchor,
-				resolved: anchor,
+				current,
+				resolved: current,
 				status: "skipped"
 			});
 			continue;
 		}
-		const written = styleRange(pickTarget(anchor, available, { allowMajor: opts.allowMajor ?? false }), range);
+		if (lookup.version === void 0) {
+			warnings.push(`workspace package "${pkg}" has no readable package.json version — skipped`);
+			pins.push({
+				package: pkg,
+				current,
+				resolved: current,
+				status: "skipped"
+			});
+			continue;
+		}
+		const target = lookup.version;
 		let changed = false;
-		for (const file of files) {
+		for (const file of inScope) {
 			const content = contents.get(file);
-			const rewritten = rewritePin(content, pkg, written);
+			const rewritten = rewritePin(content, pkg, target);
 			if (rewritten !== content) {
 				changed = true;
 				contents.set(file, rewritten);
 				if (!opts.dryRun) pinFs.writeFile(file, rewritten);
 			}
 		}
-		results.push({
+		pins.push({
 			package: pkg,
-			current: anchor,
-			resolved: written,
-			status: changed ? "updated" : "unchanged"
+			current,
+			resolved: target,
+			status: changed ? "pinned" : "unchanged"
 		});
 	}
-	return results;
+	if (pins.length > 0 && pins.every((pin) => pin.status === "skipped")) warnings.push(`resolved 0 of ${pins.length} referenced package(s) against the workspace — no pins were rewritten`);
+	return {
+		pins,
+		warnings
+	};
 }
 //#endregion
-//#region src/build/cli.ts
-const DEFAULT_REGISTRY = "https://registry.npmjs.org";
-function collect(value, previous) {
-	return [...previous, value];
+//#region src/bundle/fs.ts
+const DEFAULT_GLOBS = ["packages/*"];
+/** Walks up from `start` looking for `pnpm-workspace.yaml`; falls back to `start` itself when no
+*  ancestor declares one (the workspace glob then resolves relative to `start`). `start` is resolved
+*  to an absolute path first — a relative one (`.`) would end the walk on its first step, silently
+*  making workspace discovery depend on the cwd the command was invoked from. */
+function findMonorepoRoot(start) {
+	const from = path.resolve(start);
+	let dir = from;
+	for (;;) {
+		if (fsNode.existsSync(path.join(dir, "pnpm-workspace.yaml"))) return dir;
+		const parent = path.dirname(dir);
+		if (parent === dir) return from;
+		dir = parent;
+	}
 }
-function buildCommand() {
-	const cmd = new Command("build").description("Generate vendor manifests from .plugin/plugin.json");
-	cmd.option("--vendor <id>", "Build only the named vendor").option("--dry-run", "Print what would be written without writing").option("--verbose", "Print field-by-field transformation decisions").option("--clean", "Delete generated manifests before building").option("--format <format>", "Output format: json or text (default: text)").option("--registry <url>", "Registry to resolve pinned CLI versions from", DEFAULT_REGISTRY).option("--range <style>", "Pin style to write: exact, tilde, or caret (~/^ accepted)", "exact").option("--package <name>", "Limit pin resolution to this package (repeatable)", collect, []).option("--allow-major", "Allow pin resolution to cross a major version boundary").option("--skip-pins", "Skip pin resolution entirely (manifests only)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin build --vendor claude-code --range tilde\n").action(async (opts) => {
+/** Minimal `packages:` list extraction from a `pnpm-workspace.yaml` — no YAML dependency, just the
+*  flat glob-list shape pnpm-workspace files use. */
+function parseWorkspaceGlobs(yamlText) {
+	const lines = yamlText.split(/\r?\n/);
+	const globs = [];
+	let inPackages = false;
+	for (const line of lines) {
+		if (/^packages:\s*$/.test(line)) {
+			inPackages = true;
+			continue;
+		}
+		if (!inPackages) continue;
+		const item = line.match(/^\s*-\s*["']?([^"'\s#]+)["']?\s*$/);
+		if (item) {
+			globs.push(item[1]);
+			continue;
+		}
+		if (/^\S/.test(line)) inPackages = false;
+	}
+	return globs;
+}
+function readWorkspaceGlobs(monorepoRoot) {
+	const yamlPath = path.join(monorepoRoot, "pnpm-workspace.yaml");
+	if (!fsNode.existsSync(yamlPath)) return DEFAULT_GLOBS;
+	try {
+		const globs = parseWorkspaceGlobs(fsNode.readFileSync(yamlPath, "utf8"));
+		return globs.length > 0 ? globs : DEFAULT_GLOBS;
+	} catch {
+		return DEFAULT_GLOBS;
+	}
+}
+/** Expands a workspace glob to its member directories. Only the `<dir>/*` shape pnpm-workspace
+*  files use is supported; a glob without a trailing `/*` is treated as a single literal path. */
+function expandGlob(monorepoRoot, glob) {
+	if (glob.endsWith("/*")) {
+		const base = path.join(monorepoRoot, glob.slice(0, -2));
+		if (!fsNode.existsSync(base)) return [];
+		return fsNode.readdirSync(base, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => path.join(base, entry.name));
+	}
+	const dir = path.join(monorepoRoot, glob);
+	return fsNode.existsSync(dir) ? [dir] : [];
+}
+/** Discovers every workspace member's version, keyed by its `package.json` `name` field (falling
+*  back to the directory name when `package.json` is missing or unreadable — registering the
+*  package as an in-workspace member with an unresolved version, distinct from a package with no
+*  workspace entry at all). */
+function discoverWorkspace(root) {
+	const monorepoRoot = findMonorepoRoot(root);
+	const globs = readWorkspaceGlobs(monorepoRoot);
+	const map = /* @__PURE__ */ new Map();
+	for (const glob of globs) for (const dir of expandGlob(monorepoRoot, glob)) {
+		let name = path.basename(dir);
+		let version;
+		try {
+			const pkg = JSON.parse(fsNode.readFileSync(path.join(dir, "package.json"), "utf8"));
+			if (typeof pkg.name === "string") name = pkg.name;
+			if (typeof pkg.version === "string") version = pkg.version;
+		} catch {}
+		map.set(name, version);
+	}
+	return map;
+}
+/** Writes `<root>/.plugin/pins.json` — a flat, key-sorted `{ "<package>": "<resolvedVersion>" }`
+*  map of the workspace-resolved pins (`pinned` + `unchanged`), so a bundled plugin's skills can read
+*  the shipped version programmatically (e.g. `${CLAUDE_PLUGIN_ROOT}/.plugin/pins.json`). External /
+*  `skipped` packages are excluded — they have no authoritative workspace version. */
+function writePinsMap(root, pins) {
+	const map = {};
+	for (const pin of pins) if (pin.status === "pinned" || pin.status === "unchanged") map[pin.package] = pin.resolved;
+	const sorted = {};
+	for (const key of Object.keys(map).sort((a, b) => a.localeCompare(b))) sorted[key] = map[key];
+	const dir = path.join(root, ".plugin");
+	fsNode.mkdirSync(dir, { recursive: true });
+	const pinsPath = path.join(dir, "pins.json");
+	const existing = fsNode.existsSync(pinsPath) ? fsNode.readFileSync(pinsPath, "utf8") : null;
+	const indent = existing ? detectIndent(existing) : "	";
+	fsNode.writeFileSync(pinsPath, `${JSON.stringify(sorted, null, indent)}\n`);
+}
+function realVersionSource(workspace) {
+	return { resolve(pkg) {
+		if (!workspace.has(pkg)) return { inWorkspace: false };
+		return {
+			inWorkspace: true,
+			version: workspace.get(pkg)
+		};
+	} };
+}
+//#endregion
+//#region src/bundle/cli.ts
+const TRUNCATE_THRESHOLD = 20;
+const NEXT_STEP = "→ review and commit the pinned skills\n";
+/** Every referenced package skipped: nothing was rewritten, so the next step is to check the
+*  workspace resolution rather than to commit a bundle that does not exist. */
+const NOTHING_RESOLVED_STEP = "→ nothing was pinned — confirm --root is inside the workspace that owns these packages before releasing\n";
+function bundleCommand() {
+	const cmd = new Command("bundle").description("Pin the plugin's skill npx references to their workspace package.json versions (release form)");
+	cmd.option("--dry-run", "Resolve and report pins without writing them").option("--full", "Show every pins row without truncation").option("--format <format>", "Output format: json or toon (default: toon)").addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin bundle --dry-run --full\n").action((opts) => {
 		try {
 			const root = resolveRoot(opts.root);
-			const result = buildPlugin(root, {
-				vendor: opts.vendor,
-				dryRun: opts.dryRun,
-				verbose: opts.verbose,
-				clean: opts.clean
-			});
+			const result = bundlePins(realPinFs(resolveSkillsDir(root, readManifest(root).skills)), realVersionSource(discoverWorkspace(root)), { dryRun: opts.dryRun });
+			if (!opts.dryRun) writePinsMap(root, result.pins);
 			for (const warning of result.warnings) process.stderr.write(`warn: ${warning}\n`);
-			let pins = Object.assign([], { warnings: [] });
-			if (!opts.skipPins) {
-				const skillsDir = resolveSkillsDir(root, readManifest(root).skills);
-				const client = realRegistryClient(opts.registry);
-				const pinFs = realPinFs(skillsDir);
-				pins = await resolvePins(root, {
-					packages: opts.package,
-					allowMajor: opts.allowMajor,
-					dryRun: opts.dryRun,
-					range: normalizeRange(opts.range)
-				}, client, pinFs);
-				for (const warning of pins.warnings) process.stderr.write(`warn: ${warning}\n`);
-			}
-			output({
-				...result,
-				pins
-			}, () => {
-				if (result.vendors.length > 0) {
-					printFields({ vendors: result.vendors.join(", ") });
-					printTable(result.written.map((p) => ({ path: p })), [{
-						label: "output",
-						get: (r) => opts.dryRun ? `(dry-run) ${r.path}` : r.path
-					}]);
-				}
-				for (const p of pins) console.log(`${p.package}  ${p.current} → ${p.resolved}  ${p.status}`);
+			const pinned = result.pins.filter((p) => p.status === "pinned").length;
+			const unchanged = result.pins.filter((p) => p.status === "unchanged").length;
+			const skipped = result.pins.filter((p) => p.status === "skipped").length;
+			output({ pins: result.pins }, () => {
+				const truncated = !opts.full && result.pins.length > TRUNCATE_THRESHOLD;
+				const rows = truncated ? result.pins.slice(0, TRUNCATE_THRESHOLD) : result.pins;
+				if (rows.length > 0) printTable(rows, [
+					{
+						label: "package",
+						get: (r) => r.package
+					},
+					{
+						label: "current",
+						get: (r) => r.current
+					},
+					{
+						label: "resolved",
+						get: (r) => r.resolved
+					},
+					{
+						label: "status",
+						get: (r) => r.status
+					}
+				]);
+				if (truncated) console.log(`… +${result.pins.length - TRUNCATE_THRESHOLD} more — rerun with --full`);
+				console.log(`pinned ${pinned}, unchanged ${unchanged}, skipped ${skipped}`);
 			});
+			if (result.pins.length === 0) process.stderr.write("nothing to bundle\n");
+			const noneResolved = result.pins.length > 0 && skipped === result.pins.length;
+			process.stderr.write(noneResolved ? NOTHING_RESOLVED_STEP : NEXT_STEP);
 		} catch (err) {
 			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
 			process.exit(1);
@@ -898,11 +1046,6 @@ const realSyncVersionFs = {
 };
 //#endregion
 //#region src/publish/sync-version.ts
-function detectIndent(json) {
-	const match = json.match(/\n([ \t]+)/);
-	if (!match) return "	";
-	return match[1].startsWith("	") ? "	" : match[1].length;
-}
 function syncVersion(root, syncFs) {
 	const manifestPath = path.join(root, ".plugin", "plugin.json");
 	if (!syncFs.exists(manifestPath)) throw new Error(`No .plugin/plugin.json found at ${root}`);
@@ -1093,8 +1236,9 @@ function syncCommand() {
 const program = new Command();
 program.name("universal-plugin").description("Universal AI agent plugin build tool").version("0.0.0").helpCommand(false);
 function pluginCommand() {
-	const cmd = new Command("plugin").description("Author the canonical plugin manifest (build; validate, init planned)");
+	const cmd = new Command("plugin").description("Author the canonical plugin manifest (build, bundle; validate, init planned)");
 	cmd.addCommand(buildCommand());
+	cmd.addCommand(bundleCommand());
 	return cmd;
 }
 program.addCommand(pluginCommand());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -48,10 +48,11 @@
   },
   "scripts": {
     "build": "tsdown",
+    "check:spec": "sdd-check-specs",
     "dev": "tsx src/cli.ts",
     "knip": "knip",
     "lint": "biome check .",
-    "test": "pnpm build && vitest run src",
+    "test": "vitest run src",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "verify": "pnpm typecheck && pnpm lint && pnpm test"