fix(plugins): distribute canonical skills from the exact npm release

This commit is contained in:
morluto
2026-10-13 21:41:20 +08:00
parent 07680f66e2
commit 11404c05f4
11 changed files with 174 additions and 25 deletions
+3 -2
View File
@@ -7,8 +7,9 @@
{
"name": "rea",
"source": {
"source": "local",
"path": "./"
"source": "npm",
"package": "rea-agents",
"version": "6.4.0"
},
"policy": {
"installation": "AVAILABLE",
+5 -1
View File
@@ -10,7 +10,11 @@
{
"name": "rea",
"description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
"source": "./",
"source": {
"source": "npm",
"package": "rea-agents",
"version": "6.4.0"
},
"category": "development"
}
]
+1 -3
View File
@@ -15,9 +15,7 @@
"decompiler",
"mcp-server"
],
"skills": [
"./.agents/skills/reverse-engineer-anything"
],
"skills": "./skills",
"mcpServers": {
"rea": {
"command": "npx",
+1 -3
View File
@@ -15,9 +15,7 @@
"decompiler",
"mcp-server"
],
"skills": [
"./.agents/skills/reverse-engineer-anything"
],
"skills": "./skills",
"mcpServers": {
"rea": {
"command": "npx",
+15 -7
View File
@@ -783,15 +783,23 @@ Ghidra/JDK installation; neither is inferred from startup alone.
## Agent plugins and marketplaces
The repository root is both a Claude Code plugin
(`.claude-plugin/plugin.json`) and a Codex plugin
(`.codex-plugin/plugin.json`). Each manifest bundles the
`reverse-engineer-anything` skill from `.agents/skills/` and registers the
stdio server through `npx`, pinned to the exact package version in that
manifest, without a second distribution artifact.
REA's npm package is the shared Claude Code and Codex plugin artifact. It
contains `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, and the
canonical generated `skills/` tree. Both manifests select `./skills` and pin
the stdio MCP server to that exact package version. The existing release skill
generator also pins CLI recovery commands to the same version.
The repository is also its own single-plugin marketplace, through
The repository's single-plugin marketplaces are declared in
`.claude-plugin/marketplace.json` and `.agents/plugins/marketplace.json`.
Both select an exact `rea-agents` npm version instead of mutable source-checkout
contents. Release Please updates their selectors alongside the plugin manifests.
No plugin-only publication or generated skill files committed to Git are needed.
This distribution becomes installable after the first qualified npm release
containing these plugin manifests. Earlier published packages are not changed
by this source proposal. For local source development, generate the existing
packaged skill before loading the repository as a plugin; the authored
`.agents/skills/` tree is not the plugin's shipped skill layout.
In Claude Code:
+2
View File
@@ -67,6 +67,8 @@
"scripts/hopper-demo-x11.py",
"scripts/prepack.mjs",
"scripts/prepare.mjs",
".claude-plugin/plugin.json",
".codex-plugin/plugin.json",
"skills",
"README.md",
"DISCLAIMER.md",
+10
View File
@@ -51,6 +51,16 @@
"type": "json",
"path": ".codex-plugin/plugin.json",
"jsonpath": "$.mcpServers.rea.args[1]"
},
{
"type": "json",
"path": ".claude-plugin/marketplace.json",
"jsonpath": "$.plugins[0].source.version"
},
{
"type": "json",
"path": ".agents/plugins/marketplace.json",
"jsonpath": "$.plugins[0].source.version"
}
]
}
+26 -8
View File
@@ -365,15 +365,29 @@ export function verifyReleaseNotes(raw, text, body) {
};
}
const VERSION_ONLY_PLUGIN_MANIFESTS = new Set([
const VERSION_ONLY_PLUGIN_METADATA = new Set([
".claude-plugin/plugin.json",
".codex-plugin/plugin.json",
".claude-plugin/marketplace.json",
".agents/plugins/marketplace.json",
]);
/** Serialize a plugin manifest with its release-owned version fields blanked. */
function pluginManifestWithoutVersions(text) {
/** Serialize plugin metadata with only its release-owned version fields blanked. */
function pluginMetadataWithoutVersions(path, text) {
const manifest = JSON.parse(text);
if (manifest === null || typeof manifest !== "object") return text;
if (path.endsWith("marketplace.json")) {
if (Array.isArray(manifest.plugins))
for (const plugin of manifest.plugins)
if (
plugin?.name === "rea" &&
plugin?.source?.source === "npm" &&
plugin.source.package === "rea-agents" &&
typeof plugin.source.version === "string"
)
plugin.source.version = "";
return JSON.stringify(manifest);
}
if ("version" in manifest) manifest.version = "";
const launch = manifest.mcpServers?.rea?.args;
// Only the version after the last "@" is release-owned; a different package
@@ -384,17 +398,21 @@ function pluginManifestWithoutVersions(text) {
}
/**
* A plugin manifest also carries plugin behavior, so a release may change only
* its version and pinned server launch. Any other difference, an unreadable
* Plugin metadata also carries behavior, so a release may change only
* its version, pinned server launch, and exact REA marketplace version. Any other difference, an unreadable
* side, or a manifest added by the release counts as a product change.
*/
async function changesOnlyPluginVersions(run, path, from, to) {
try {
return (
pluginManifestWithoutVersions(
pluginMetadataWithoutVersions(
path,
await run("git", ["show", `${from}:${path}`]),
) ===
pluginManifestWithoutVersions(await run("git", ["show", `${to}:${path}`]))
pluginMetadataWithoutVersions(
path,
await run("git", ["show", `${to}:${path}`]),
)
);
} catch {
return false;
@@ -473,7 +491,7 @@ export async function verifyInventoryHistory(run, raw, source) {
for (const path of paths) {
if (allowed.has(path)) continue;
if (
VERSION_ONLY_PLUGIN_MANIFESTS.has(path) &&
VERSION_ONLY_PLUGIN_METADATA.has(path) &&
(await changesOnlyPluginVersions(run, path, inventory.target, resolved))
)
continue;
+28
View File
@@ -60,6 +60,34 @@ export async function verifyPackagePack({ root, workspace }) {
throw new Error(
"packaged skill metadata did not match the catalog shipped in the package",
);
for (const path of [
".claude-plugin/plugin.json",
".codex-plugin/plugin.json",
]) {
const manifest = JSON.parse(
(await exec("tar", ["-xOf", tarball, `package/${path}`])).stdout,
);
if (
manifest.version !== packedManifest.version ||
manifest.skills !== "./skills" ||
JSON.stringify(manifest.mcpServers?.rea?.args) !==
JSON.stringify([
"-y",
`${packedManifest.name}@${packedManifest.version}`,
"mcp",
])
)
throw new Error(
`Packaged plugin ${path} does not match the exact runtime and canonical skill release`,
);
}
if (
skill.includes(`${packedManifest.name}@latest`) ||
!skill.includes(`${packedManifest.name}@${packedManifest.version}`)
)
throw new Error(
"Packaged plugin skill recovery is not pinned to the shipped runtime",
);
if (
packedFiles.some(
(path) => path.includes("__pycache__") || path.endsWith(".pyc"),
+48 -1
View File
@@ -48,6 +48,16 @@ const pluginManifests = [
".codex-plugin/plugin.json",
] as const;
const pluginMarketplaces = [
".claude-plugin/marketplace.json",
".agents/plugins/marketplace.json",
] as const;
const pluginMarketplace = (version: string, packageName = "rea-agents") => ({
plugins: [
{ name: "rea", source: { source: "npm", package: packageName, version } },
],
});
const pluginManifest = (
version: string,
{ skills = ["./skill"], packageName = "rea-agents" } = {},
@@ -79,6 +89,13 @@ beforeAll(async () => {
JSON.stringify(pluginManifest("6.3.0")),
);
}
for (const path of pluginMarketplaces) {
await mkdir(join(directory, dirname(path)), { recursive: true });
await writeFile(
join(directory, path),
JSON.stringify(pluginMarketplace("6.3.0")),
);
}
await git(directory, ["add", "."]);
await git(directory, ["commit", "-m", "chore: baseline"]);
const base = await git(directory, ["rev-parse", "HEAD"]);
@@ -394,7 +411,17 @@ it("binds publication to complete recorded history and the reviewed base", async
join(f.directory, path),
JSON.stringify(pluginManifest("6.4.0")),
);
await git(f.directory, ["add", "CHANGELOG.md", ...pluginManifests]);
for (const path of pluginMarketplaces)
await writeFile(
join(f.directory, path),
JSON.stringify(pluginMarketplace("6.4.0")),
);
await git(f.directory, [
"add",
"CHANGELOG.md",
...pluginManifests,
...pluginMarketplaces,
]);
await git(f.directory, ["commit", "-m", "chore: release notes"]);
const source = await git(f.directory, ["rev-parse", "HEAD"]);
// Release PRs bump the plugin manifest version and pinned launch only.
@@ -592,3 +619,23 @@ it("fails closed on partial GitHub errors and non-advancing pagination without s
});
await expect(access(output)).rejects.toMatchObject({ code: "ENOENT" });
});
it.each(pluginMarketplaces)(
"treats a marketplace package change in %s as product behavior",
async (path) => {
const f = await fixture();
await writeFile(
join(f.directory, path),
JSON.stringify(pluginMarketplace("6.4.0", "another-package")),
);
await git(f.directory, ["add", "CHANGELOG.md", path]);
await git(f.directory, ["commit", "-m", "chore: release notes"]);
await expect(
f.invoke(["check", "--manifest", f.manifest, "--source", "HEAD"]),
).rejects.toMatchObject({
stderr: expect.stringContaining(
`Product changed after notes target; regenerate inventory: ${path}`,
),
});
},
);
@@ -61,6 +61,14 @@ describe("release configuration", () => {
jsonpath,
})),
),
...[
".claude-plugin/marketplace.json",
".agents/plugins/marketplace.json",
].map((path) => ({
type: "json",
path,
jsonpath: "$.plugins[0].source.version",
})),
],
},
},
@@ -150,6 +158,33 @@ describe("release configuration", () => {
});
describe("plugin manifests", () => {
it("distributes both plugins with generated canonical skills from the exact npm release", async () => {
const pkg = (await readJson("package.json")) as {
version: string;
files: string[];
};
expect(pkg.files).toEqual(
expect.arrayContaining([...pluginManifests, "skills"]),
);
for (const path of pluginManifests)
expect(await readJson(path)).toMatchObject({ skills: "./skills" });
for (const path of [
".claude-plugin/marketplace.json",
".agents/plugins/marketplace.json",
])
expect(await readJson(path)).toMatchObject({
plugins: [
{
source: {
source: "npm",
package: "rea-agents",
version: pkg.version,
},
},
],
});
});
it.each(pluginManifests)(
"pins the plugin manifest %s and its server launch to the package version",
async (path) => {