fix(plugins): validate Codex companion launch metadata

This commit is contained in:
morluto
2026-10-14 01:23:15 +08:00
parent b7dabdbc4f
commit a85bfed8dc
15 changed files with 315 additions and 99 deletions
+1 -1
View File
@@ -21,7 +21,7 @@
"command": "node",
"args": [
"${CLAUDE_PLUGIN_ROOT}/scripts/plugin-mcp-launcher.mjs",
"rea-agents@6.4.0"
"6.4.0"
]
}
}
+3 -5
View File
@@ -2,11 +2,9 @@
"mcpServers": {
"rea": {
"command": "node",
"args": [
"./scripts/plugin-mcp-launcher.mjs",
"rea-agents@6.4.0"
],
"cwd": "."
"args": ["./scripts/plugin-mcp-launcher.mjs", "6.4.0"],
"cwd": ".",
"startup_timeout_sec": 30
}
}
}
+2 -1
View File
@@ -63,7 +63,8 @@
"bridge/mitmproxy/capture.py",
"scripts/rea.mjs",
"scripts/plugin-mcp-launcher.mjs",
"scripts/lib/packageRunnerCommand.mjs",
"src/application/PackageRunnerCommand.mjs",
"src/application/PackageRunnerCommand.d.mts",
"scripts/rea-android-workspace-guardian.mjs",
"scripts/electron-active-hook.cjs",
"scripts/electron-active-hook-boundaries.cjs",
+37 -9
View File
@@ -8,10 +8,31 @@ const PLUGIN_MANIFEST_PATHS = [
".claude-plugin/plugin.json",
".codex-plugin/plugin.json",
];
const PLUGIN_PACKAGE_NAME = "rea-agents";
const pluginManifestSchema = versionSchema.extend({
const inlinePluginManifestSchema = versionSchema.extend({
mcpServers: z.object({
rea: z.object({ args: z.array(z.string()) }),
rea: z.object({
command: z.literal("node"),
args: z.tuple([
z.literal("${CLAUDE_PLUGIN_ROOT}/scripts/plugin-mcp-launcher.mjs"),
z.string(),
]),
}),
}),
});
const codexPluginManifestSchema = versionSchema.extend({
mcpServers: z.literal("./.mcp.json"),
});
const codexServerConfigSchema = z.object({
mcpServers: z.object({
rea: z.object({
command: z.literal("node"),
args: z.tuple([
z.literal("./scripts/plugin-mcp-launcher.mjs"),
z.string(),
]),
cwd: z.literal("."),
startup_timeout_sec: z.number().int().positive(),
}),
}),
});
const sectionsSchema = z.object({
@@ -203,9 +224,16 @@ async function validateCandidate(git, sha, version, commits) {
// previous server, so both are version authority like server.json.
const launches = [];
for (const path of PLUGIN_MANIFEST_PATHS) {
const manifest = await readJson(git, sha, path, pluginManifestSchema);
const manifest =
path === ".codex-plugin/plugin.json"
? await readJson(git, sha, path, codexPluginManifestSchema)
: await readJson(git, sha, path, inlinePluginManifestSchema);
versions.push([path, manifest.version]);
launches.push([path, manifest.mcpServers.rea.args[1]]);
const server =
path === ".codex-plugin/plugin.json"
? await readJson(git, sha, ".mcp.json", codexServerConfigSchema)
: manifest;
launches.push([path, server.mcpServers.rea.args[1]]);
}
// Catalogs are generated and checked from this candidate by the release job;
// they are not version authority stored in the immutable source tree.
@@ -228,13 +256,13 @@ async function validateCandidate(git, sha, version, commits) {
);
}
}
// Compare the whole specifier: a bare version would make npx fetch a
// package named after the release number.
const requiredLaunch = `${PLUGIN_PACKAGE_NAME}@${version}`;
// Plugin JSON stores only a scalar version. The launcher owns the fixed
// package name and constructs the complete registry specifier at runtime.
const requiredLaunch = version;
for (const [location, launched] of launches) {
if (launched !== requiredLaunch) {
throw new Error(
`${location}@${sha} launches ${launched ?? "no package"}; release branch requires ${requiredLaunch}.`,
`${location}@${sha} launches version ${launched ?? "no version"}; release branch requires ${requiredLaunch}.`,
);
}
}
+4 -4
View File
@@ -368,6 +368,7 @@ export function verifyReleaseNotes(raw, text, body) {
const VERSION_ONLY_PLUGIN_METADATA = new Set([
".claude-plugin/plugin.json",
".codex-plugin/plugin.json",
".mcp.json",
".claude-plugin/marketplace.json",
".agents/plugins/marketplace.json",
]);
@@ -390,10 +391,9 @@ function pluginMetadataWithoutVersions(path, text) {
}
if ("version" in manifest) manifest.version = "";
const launch = manifest.mcpServers?.rea?.args;
// Only the version after the last "@" is release-owned; a different package
// name changes what the plugin runs.
if (Array.isArray(launch) && typeof launch[1] === "string")
launch[1] = launch[1].replace(/@[^@/]*$/u, "@");
// Only the scalar pinned version is release-owned; the launcher owns the
// fixed package name and the executable/path remain product behavior.
if (Array.isArray(launch) && typeof launch[1] === "string") launch[1] = "";
return JSON.stringify(manifest);
}
+111 -10
View File
@@ -1,29 +1,29 @@
#!/usr/bin/env node
import { spawn } from "node:child_process";
import { randomUUID } from "node:crypto";
import { access, mkdtemp, rm } from "node:fs/promises";
import { constants, tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { packageRunnerCommand } from "./lib/packageRunnerCommand.mjs";
import { packageRunnerCommand } from "../src/application/PackageRunnerCommand.mjs";
// The manifest owns this exact package pin; args[1] remains release-managed.
// Keep the package name at the launcher boundary so release automation updates
// only a scalar version in plugin JSON, never a compound package specifier.
// No build, dependency installation or ambient latest-version lookup is needed
// to run this bootstrap from a Git-installed plugin.
const [packageSpecifier, ...extra] = process.argv.slice(2);
const [version, ...extra] = process.argv.slice(2);
if (
extra.length !== 0 ||
!/^rea-agents@\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/u.test(
packageSpecifier ?? "",
)
!/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/u.test(version ?? "")
) {
process.stderr.write(
"REA plugin requires one exact rea-agents@VERSION pin.\n",
);
process.exitCode = 1;
} else {
await launch(packageSpecifier);
await launch(`rea-agents@${version}`);
}
async function launch(packageSpecifier) {
@@ -71,12 +71,15 @@ async function launch(packageSpecifier) {
process.exitCode = 1;
return;
}
if (process.platform === "win32") {
await launchWindowsFallback(command, args, workingDirectory);
return;
}
const child = spawn(command, args, {
cwd: workingDirectory,
// A dedicated POSIX process group gives this launcher ownership of the
// package runner and any server it starts. Windows keeps direct-child
// signaling until a verified Job Object owner is available here.
detached: process.platform !== "win32",
// package runner and any server it starts.
detached: true,
stdio: "inherit",
shell: false,
});
@@ -134,6 +137,104 @@ async function launch(packageSpecifier) {
});
}
async function launchWindowsFallback(command, args, workingDirectory) {
let spawnOwnedProviderProcess;
try {
({ spawnOwnedProviderProcess } =
await import("../dist/process/ProviderProcess.js"));
} catch (cause) {
await rm(workingDirectory, { recursive: true }).catch(() => {});
process.stderr.write(
`REA plugin cannot safely launch a Windows fallback without the owned process supervisor: ${cause.message}\n`,
);
process.exitCode = 1;
return;
}
let owned;
try {
owned = await spawnOwnedProviderProcess({
command,
arguments: args,
runId: randomUUID(),
cwd: workingDirectory,
stdin: "pipe",
platform: "win32",
});
} catch (cause) {
await rm(workingDirectory, { recursive: true }).catch(() => {});
process.stderr.write(
`REA plugin could not start the owned Windows process tree: ${cause.message}\n`,
);
process.exitCode = 1;
return;
}
const child = owned.process;
child.stdout?.pipe(process.stdout);
child.stderr?.pipe(process.stderr);
if (child.stdin === null || child.stdin === undefined) {
const cleanup = await owned.cleanup?.();
if (cleanup?.cleaned === true)
await rm(workingDirectory, { recursive: true }).catch(() => {});
else
process.stderr.write(
`REA plugin retained its Windows process ownership directory at ${workingDirectory} because cleanup was not verified.\n`,
);
process.stderr.write(
"REA plugin Windows process supervisor did not provide protocol stdin.\n",
);
process.exitCode = 1;
return;
}
process.stdin.pipe(child.stdin);
let cleanupFailed = false;
let cleanupPromise;
const signals = new Map();
for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
const forward = () => {
if (child.exitCode !== null || child.signalCode !== null) return;
cleanupPromise ??= owned
.cleanup?.()
.then((result) => {
if (!result.cleaned) {
cleanupFailed = true;
process.stderr.write(
`REA plugin could not verify Windows process-tree cleanup: ${result.reason}\n`,
);
}
})
.catch((cause) => {
cleanupFailed = true;
process.stderr.write(
`REA plugin Windows process-tree cleanup failed: ${cause.message}\n`,
);
});
};
signals.set(signal, forward);
process.on(signal, forward);
}
child.once("error", (cause) => {
process.stderr.write(
`REA plugin Windows process supervisor failed: ${cause.message}\n`,
);
process.exitCode = 1;
});
child.once("close", async (code) => {
for (const [signal, listener] of signals) process.off(signal, listener);
await cleanupPromise;
if (!cleanupFailed) {
try {
await rm(workingDirectory, { recursive: true });
} catch (cause) {
cleanupFailed = true;
process.stderr.write(
`REA plugin retained its working directory at ${workingDirectory}: ${cause.message}\n`,
);
}
}
process.exitCode = code === 0 && cleanupFailed ? 1 : (code ?? 1);
});
}
function isMissing(cause) {
return (
typeof cause === "object" &&
+7 -10
View File
@@ -73,25 +73,20 @@ export async function verifyPackagePack({ root, workspace }) {
);
const serverConfig = path.startsWith(".codex")
? JSON.parse(
(
await exec("tar", [
"-xOf",
tarball,
"package/.mcp.json",
])
).stdout,
(await exec("tar", ["-xOf", tarball, "package/.mcp.json"])).stdout,
)
: manifest;
const expectedArgs = [
`${path.startsWith(".claude") ? "${CLAUDE_PLUGIN_ROOT}/" : "./"}scripts/plugin-mcp-launcher.mjs`,
`${packedManifest.name}@${packedManifest.version}`,
packedManifest.version,
];
if (
manifest.version !== packedManifest.version ||
manifest.skills !== "./skills" ||
(path.startsWith(".codex")
? manifest.mcpServers !== "./.mcp.json" ||
serverConfig.mcpServers?.rea?.cwd !== "."
serverConfig.mcpServers?.rea?.cwd !== "." ||
serverConfig.mcpServers?.rea?.startup_timeout_sec !== 30
: false) ||
serverConfig.mcpServers?.rea?.command !== "node" ||
JSON.stringify(serverConfig.mcpServers?.rea?.args) !==
@@ -105,7 +100,9 @@ export async function verifyPackagePack({ root, workspace }) {
throw new Error("Packaged Codex MCP server declaration is missing");
for (const path of [
"scripts/plugin-mcp-launcher.mjs",
"scripts/lib/packageRunnerCommand.mjs",
"src/application/PackageRunnerCommand.mjs",
"src/application/PackageRunnerCommand.d.mts",
"dist/application/PackageRunnerCommand.mjs",
])
if (!packedFiles.includes(`package/${path}`))
throw new Error(
@@ -2,7 +2,7 @@ import { basename, isAbsolute, resolve } from "node:path";
import { valid } from "semver";
import { PRODUCT_IDENTITY } from "../identity.js";
import { packageRunnerCommand } from "../../scripts/lib/packageRunnerCommand.mjs";
import { packageRunnerCommand } from "./PackageRunnerCommand.mjs";
/** Package runners whose pinned launcher setup can register. */
export type PackageRunner = "npx" | "bunx";
@@ -24,9 +24,24 @@ const pluginManifestPaths = [
".codex-plugin/plugin.json",
] as const;
const pluginManifest = (version: string, launch = `rea-agents@${version}`) => ({
const pluginManifest = (version: string, launch = version) => ({
version,
mcpServers: { rea: { args: ["-y", launch, "mcp"] } },
mcpServers: {
rea: {
command: "node",
args: ["${CLAUDE_PLUGIN_ROOT}/scripts/plugin-mcp-launcher.mjs", launch],
},
},
});
const codexServerConfig = (version: string, launch = version) => ({
mcpServers: {
rea: {
command: "node",
args: ["./scripts/plugin-mcp-launcher.mjs", launch],
startup_timeout_sec: 30,
},
},
});
async function metadata(
@@ -40,9 +55,12 @@ async function metadata(
for (const path of pluginManifestPaths)
await mkdir(join(directory, dirname(path)), { recursive: true });
const files = {
...Object.fromEntries(
pluginManifestPaths.map((path) => [path, pluginManifest(version)]),
),
".claude-plugin/plugin.json": pluginManifest(version),
".codex-plugin/plugin.json": {
version,
mcpServers: "./.mcp.json",
},
".mcp.json": codexServerConfig(version),
"package.json": { name: "rea-agents", version },
"package-lock.json": { version, packages: { "": { version } } },
".release-please-manifest.json": { ".": version },
@@ -581,27 +599,15 @@ it.each([
});
it.each(
pluginManifestPaths.flatMap((path) => [
{
path,
stale: "version",
manifest: pluginManifest("5.1.0", "rea-agents@6.0.0"),
failure: "declares 5.1.0; release branch requires 6.0.0",
},
{
path,
stale: "server launch",
manifest: pluginManifest("6.0.0", "rea-agents@5.1.0"),
failure:
"launches rea-agents@5.1.0; release branch requires rea-agents@6.0.0",
},
{
path,
stale: "server launch without the package name",
manifest: pluginManifest("6.0.0", "6.0.0"),
failure: "launches 6.0.0; release branch requires rea-agents@6.0.0",
},
]),
pluginManifestPaths.map((path) => ({
path,
stale: "version",
manifest:
path === ".codex-plugin/plugin.json"
? { version: "5.1.0", mcpServers: "./.mcp.json" }
: pluginManifest("5.1.0"),
failure: "declares 5.1.0; release branch requires 6.0.0",
})),
)("rejects a plugin $stale in $path", async ({ path, manifest, failure }) => {
const f = await fixture();
await candidate(f, "6.0.0");
@@ -614,6 +620,29 @@ it.each(
});
});
it.each([
{
path: ".claude-plugin/plugin.json",
manifest: pluginManifest("6.0.0", "5.1.0"),
},
{
path: ".mcp.json",
manifest: codexServerConfig("6.0.0", "5.1.0"),
},
])("reads the release pin from $path", async ({ path, manifest }) => {
const f = await fixture();
await candidate(f, "6.0.0");
await writeFile(join(f.directory, path), JSON.stringify(manifest));
await git(f.directory, ["add", "."]);
await git(f.directory, ["commit", "-m", "chore: stale plugin launch"]);
await expect(verify(f)).rejects.toMatchObject({
code: 1,
stderr: expect.stringContaining(
`launches version 5.1.0; release branch requires 6.0.0`,
),
});
});
it("checks a publish merge using its pre-release first parent baseline", async () => {
const f = await fixture();
const sourceSha = await candidate(f, "6.0.0");
+74 -17
View File
@@ -47,6 +47,7 @@ const pluginManifests = [
".claude-plugin/plugin.json",
".codex-plugin/plugin.json",
] as const;
const pluginServerConfig = ".mcp.json";
const pluginMarketplaces = [
".claude-plugin/marketplace.json",
@@ -58,15 +59,43 @@ const pluginMarketplace = (version: string, packageName = "rea-agents") => ({
],
});
const pluginServer = (version: string, command = "node") => ({
mcpServers: {
rea: {
command,
args: ["./scripts/plugin-mcp-launcher.mjs", version],
startup_timeout_sec: 30,
},
},
});
const pluginManifest = (
version: string,
{ skills = ["./skill"], packageName = "rea-agents" } = {},
{ skills = ["./skill"], command = "node" } = {},
) => ({
version,
skills,
mcpServers: { rea: { args: ["-y", `${packageName}@${version}`, "mcp"] } },
mcpServers: {
rea: {
command,
args: ["${CLAUDE_PLUGIN_ROOT}/scripts/plugin-mcp-launcher.mjs", version],
},
},
});
const pluginManifestFor = (
path: (typeof pluginManifests)[number],
version: string,
options: { skills?: string[]; command?: string } = {},
) =>
path === ".codex-plugin/plugin.json"
? {
version,
skills: options.skills ?? ["./skill"],
mcpServers: "./.mcp.json",
}
: pluginManifest(version, options);
beforeAll(async () => {
const workspace = await createTestWorkspace("rea-release-notes-seed-");
seedWorkspaceRoot = workspace.root;
@@ -86,9 +115,13 @@ beforeAll(async () => {
await mkdir(join(directory, dirname(path)), { recursive: true });
await writeFile(
join(directory, path),
JSON.stringify(pluginManifest("6.3.0")),
JSON.stringify(pluginManifestFor(path, "6.3.0")),
);
}
await writeFile(
join(directory, pluginServerConfig),
JSON.stringify(pluginServer("6.3.0")),
);
for (const path of pluginMarketplaces) {
await mkdir(join(directory, dirname(path)), { recursive: true });
await writeFile(
@@ -409,8 +442,12 @@ it("binds publication to complete recorded history and the reviewed base", async
for (const path of pluginManifests)
await writeFile(
join(f.directory, path),
JSON.stringify(pluginManifest("6.4.0")),
JSON.stringify(pluginManifestFor(path, "6.4.0")),
);
await writeFile(
join(f.directory, pluginServerConfig),
JSON.stringify(pluginServer("6.4.0")),
);
for (const path of pluginMarketplaces)
await writeFile(
join(f.directory, path),
@@ -420,6 +457,7 @@ it("binds publication to complete recorded history and the reviewed base", async
"add",
"CHANGELOG.md",
...pluginManifests,
pluginServerConfig,
...pluginMarketplaces,
]);
await git(f.directory, ["commit", "-m", "chore: release notes"]);
@@ -445,22 +483,15 @@ it("binds publication to complete recorded history and the reviewed base", async
});
});
it.each(
pluginManifests.flatMap((path) => [
{ path, change: "the skill path", edit: { skills: ["./another-skill"] } },
{
path,
change: "the launched package",
edit: { packageName: "another-package" },
},
]),
)(
"treats a release that changes $change in $path as a product change",
async ({ path, edit }) => {
it.each(pluginManifests)(
"treats a release that changes the skill path in %s as a product change",
async (path) => {
const f = await fixture();
await writeFile(
join(f.directory, path),
JSON.stringify(pluginManifest("6.4.0", edit)),
JSON.stringify(
pluginManifestFor(path, "6.4.0", { skills: ["./another-skill"] }),
),
);
await git(f.directory, ["add", "CHANGELOG.md", path]);
await git(f.directory, ["commit", "-m", "chore: release notes"]);
@@ -474,6 +505,32 @@ it.each(
},
);
it.each([
{
path: ".claude-plugin/plugin.json",
content: pluginManifest("6.4.0", { command: "other-launcher" }),
},
{
path: pluginServerConfig,
content: pluginServer("6.4.0", "other-launcher"),
},
])(
"keeps launcher behavior in $path outside version-only metadata",
async ({ path, content }) => {
const f = await fixture();
await writeFile(join(f.directory, path), JSON.stringify(content));
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}`,
),
});
},
);
it("checks the live merged PR and exact Git snapshot before either publication route", async () => {
const f = await fixture();
await mkdir(join(f.directory, "docs/releases"), { recursive: true });
@@ -10,8 +10,8 @@ const launcher = fileURLToPath(
new URL("../../../scripts/plugin-mcp-launcher.mjs", import.meta.url),
);
const start = (path: string, packageSpecifier = "rea-agents@6.4.0-rc.1") => {
const child = spawn(process.execPath, [launcher, packageSpecifier], {
const start = (path: string, version = "6.4.0-rc.1") => {
const child = spawn(process.execPath, [launcher, version], {
env: {
...process.env,
PATH: `${path}${delimiter}${process.env.PATH ?? ""}`,
@@ -65,7 +65,7 @@ it.skipIf(process.platform === "win32")(
process.stdin.pipe(process.stdout);
process.stdin.on("end", () => { process.exitCode = 7; });
`);
const { child, closed } = start(bin, "rea-agents@6.4.0-rc.1");
const { child, closed } = start(bin, "6.4.0-rc.1");
child.stdin.end('{"jsonrpc":"2.0","id":1}\n');
expect(await closed).toEqual({
code: 7,
@@ -162,7 +162,7 @@ it.skipIf(process.platform === "win32")(
it("rejects a shell expression instead of treating it as the pinned package", async () => {
const root = await createTestTempDirectory("rea-plugin-invalid-pin-");
const { child, closed } = start(root, "rea-agents@6.4.0&echo wrong");
const { child, closed } = start(root, "6.4.0&echo wrong");
child.stdin.end();
expect(await closed).toMatchObject({
code: 1,
+14 -10
View File
@@ -195,7 +195,7 @@ describe("plugin manifests", () => {
});
});
it.each(pluginManifests)(
it.each([...pluginManifests, pluginServerConfig])(
"pins the plugin manifest %s and Codex's server config path",
async (path) => {
const packageJson = (await readJson("package.json")) as {
@@ -251,7 +251,12 @@ describe("plugin manifests", () => {
expect(updatedJson.get(".claude-plugin/plugin.json")).toMatchObject({
version: nextVersion,
mcpServers: {
rea: { args: ["-y", `rea-agents@${nextVersion}`, "mcp"] },
rea: {
args: [
"${CLAUDE_PLUGIN_ROOT}/scripts/plugin-mcp-launcher.mjs",
nextVersion,
],
},
},
});
expect(updatedJson.get(".codex-plugin/plugin.json")).toMatchObject({
@@ -259,7 +264,10 @@ describe("plugin manifests", () => {
});
expect(updatedJson.get(pluginServerConfig)).toMatchObject({
mcpServers: {
rea: { args: ["-y", `rea-agents@${nextVersion}`, "mcp"] },
rea: {
args: ["./scripts/plugin-mcp-launcher.mjs", nextVersion],
startup_timeout_sec: 30,
},
},
});
for (const path of [
@@ -281,7 +289,6 @@ describe("plugin manifests", () => {
it("pins the plugin server launch from the shared MCP declaration", async () => {
const packageJson = (await readJson("package.json")) as {
name: string;
version: string;
};
@@ -289,10 +296,7 @@ describe("plugin manifests", () => {
mcpServers: {
rea: {
command: "node",
args: [
"./scripts/plugin-mcp-launcher.mjs",
`${packageJson.name}@${packageJson.version}`,
],
args: ["./scripts/plugin-mcp-launcher.mjs", packageJson.version],
cwd: ".",
},
},
@@ -332,8 +336,8 @@ describe("plugin manifests", () => {
);
});
it("carries the owned Codex startup timeout in the Codex plugin server entry", async () => {
expect(await readJson(".codex-plugin/plugin.json")).toMatchObject({
it("carries the owned Codex startup timeout in the companion server entry", async () => {
expect(await readJson(pluginServerConfig)).toMatchObject({
mcpServers: {
rea: {
startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds,
+2 -1
View File
@@ -1,10 +1,11 @@
{
"extends": "./tsconfig.json",
"compilerOptions": {
"allowJs": true,
"rootDir": "src",
"types": ["node"]
},
"include": ["src/**/*.ts"],
"include": ["src/**/*.ts", "src/**/*.mjs"],
"exclude": [
"src/**/*.fixture.ts",
"src/**/*.test.ts",