fix(plugins): refresh unchanged-version bundle descriptions (#22295)

Refresh known display descriptions in same-version bundled plugin registrations only when every behavioral field matches. Compare manifests in their persisted JSON form and await bundle reconciliation before final volume-free package qualification.

Verified 77 focused tests, server typechecking, and all 59 successful PR checks. Greptile 5/5 with no unresolved review comments.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Devin FoleyandPaperclip authored and GitHub committed 2026-11-19 09:26:06 -08:00
1 parent b7177db6aa
commit 417802ca87
9 files changed
+146 -5

No files matched your search

@@ -5,6 +5,7 @@ import { bundledImageFixture } from "./helpers/bundled-image-fixture.js";
import { createBundledPluginPackageResolver } from "../services/bundled-plugin-package.js";
import { BUNDLED_PLUGIN_CATALOG, resolveBundledPluginInstalls } from "../services/bundled-plugins.js";
import { readDistributionPluginCatalog } from "../services/distribution-plugin-catalog.js";
import { pluginManifestValidator } from "../services/plugin-manifest-validator.js";
import boxd from "../../../packages/plugins/sandbox-providers/boxd/src/manifest.js";
import createos from "../../../packages/plugins/sandbox-providers/createos/src/manifest.js";
@@ -39,6 +40,16 @@ describe("bundled image package identity", () => {
expect(resolver.inspect(registration, manifest)).toMatchObject({ compatible: true, identity: { kind: "bundled_image", catalogKey: "fixture", pluginKey: manifest.id, version: "1.0.0" } });
});
it("compares parsed optional fields in the JSON form that registrations store", () => {
const { resolver, registration, manifest } = fixture();
const parsed = pluginManifestValidator().parseOrThrow({ ...manifest, capabilities: kubernetes.capabilities, environmentDrivers: kubernetes.environmentDrivers });
expect(Object.hasOwn(parsed.environmentDrivers![0]!, "supportsLoginPty")).toBe(true);
const stored = JSON.parse(JSON.stringify(parsed));
expect(Object.hasOwn(stored.environmentDrivers[0], "supportsLoginPty")).toBe(false);
expect(resolver.inspect({ ...registration, manifestJson: stored }, parsed)).toMatchObject({ compatible: true });
expect(resolver.inspect({ ...registration, manifestJson: stored }, { ...parsed, description: "changed" })).toMatchObject({ compatible: false });
});
it("rejects mismatched package names, versions, identity and escaping entrypoints", () => {
const { resolver, registration } = fixture();
for (const update of [
@@ -2,6 +2,8 @@ import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node
import os from "node:os";
import path from "node:path";
import { afterAll, describe, expect, it, vi } from "vitest";
import { pluginManifestValidator } from "../services/plugin-manifest-validator.js";
import kubernetes from "../../../packages/plugins/sandbox-providers/kubernetes/src/manifest.js";
import {
BUNDLED_PLUGIN_CATALOG,
DEFAULT_BUNDLED_CATALOG_ROOT,
@@ -415,6 +417,59 @@ describe("ensureBundledPlugins", () => {
);
});
it.each(["plugin", "driver", "setting"] as const)("refreshes only a %s description for an existing Core bundle at the same version", async (field) => {
const previous = { ...makeManifest(DAYTONA.pluginKey, "0.1.0"), description: "Old plugin description",
environmentDrivers: [{ driverKey: "daytona", kind: "sandbox_provider" as const, displayName: "Daytona", description: "Old driver description",
configSchema: { type: "object", properties: { autoStopInterval: { type: "number", description: "Old setting description" } } } }] };
const manifest = structuredClone(previous);
if (field === "plugin") manifest.description = "New plugin description";
if (field === "driver") manifest.environmentDrivers[0]!.description = "New driver description";
if (field === "setting") manifest.environmentDrivers[0]!.configSchema.properties.autoStopInterval.description = "New setting description";
const { deps, loadManifest, update, installPlugin } = makeDeps({ rows: { [DAYTONA.pluginKey]: {
id: "row-daytona", pluginKey: DAYTONA.pluginKey, status: "ready", version: "0.1.0", manifestJson: previous,
} } });
loadManifest.mockResolvedValue(manifest);
await ensureBundledPlugins([DAYTONA], deps, { reinstallUninstalled: false });
expect(update).toHaveBeenCalledExactlyOnceWith("row-daytona", { version: "0.1.0", manifest });
expect(installPlugin).not.toHaveBeenCalled();
});
it("refreshes a parsed Core bundle against a JSON-persisted registration without repeated writes", async () => {
const manifest = pluginManifestValidator().parseOrThrow(kubernetes);
const stored = JSON.parse(JSON.stringify(manifest)); stored.description = "Previous help text";
const { deps, loadManifest, update } = makeDeps({ rows: { [K8S.pluginKey]: {
id: "row-kubernetes", pluginKey: K8S.pluginKey, status: "ready", version: manifest.version, manifestJson: stored,
} } });
loadManifest.mockResolvedValue(manifest);
await ensureBundledPlugins([K8S], deps, { reinstallUninstalled: false });
expect(update).toHaveBeenCalledExactlyOnceWith("row-kubernetes", { version: manifest.version, manifest });
const unchanged = makeDeps({ rows: { [K8S.pluginKey]: {
id: "row-kubernetes", pluginKey: K8S.pluginKey, status: "ready", version: manifest.version, manifestJson: JSON.parse(JSON.stringify(manifest)),
} } });
unchanged.loadManifest.mockResolvedValue(manifest);
await ensureBundledPlugins([K8S], unchanged.deps, { reinstallUninstalled: false });
expect(unchanged.update).not.toHaveBeenCalled();
});
it.each(["capability", "entrypoint", "schema", "default", "pending-approval", "uninstalled"] as const)("does not treat a %s change as description-only", async (change) => {
const previous = { ...makeManifest(DAYTONA.pluginKey, "0.1.0"), description: "Old description",
entrypoints: { worker: "dist/worker.js" },
environmentDrivers: [{ driverKey: "daytona", kind: "sandbox_provider" as const, displayName: "Daytona",
configSchema: { type: "object", properties: { config: { type: "object", default: { description: "old runtime value" } } } } }] };
const manifest = structuredClone(previous); manifest.description = "New description";
if (change === "capability") manifest.capabilities = ["issues.read"];
if (change === "entrypoint") manifest.entrypoints.worker = "dist/other.js";
if (change === "schema") manifest.environmentDrivers[0]!.configSchema.properties.config.type = "string";
if (change === "default") manifest.environmentDrivers[0]!.configSchema.properties.config.default.description = "new runtime value";
const { deps, loadManifest, update } = makeDeps({ rows: { [DAYTONA.pluginKey]: {
id: "row-daytona", pluginKey: DAYTONA.pluginKey, status: change === "pending-approval" ? "upgrade_pending" : change === "uninstalled" ? "uninstalled" : "ready",
version: "0.1.0", manifestJson: previous,
} } });
loadManifest.mockResolvedValue(manifest);
await ensureBundledPlugins([DAYTONA], deps, { reinstallUninstalled: false });
expect(update).not.toHaveBeenCalled();
});
it("does not reconcile when the persisted version already matches the bundle", async () => {
const { deps, update } = makeDeps({
rows: {
@@ -0,0 +1,33 @@
import { beforeEach, expect, it, vi } from "vitest";
import { qualifyCloudConfigurationForCurrentImage } from "../services/cloud-configuration-qualification.js";
const { qualify } = vi.hoisted(() => ({ qualify: vi.fn() }));
vi.mock("../services/cloud-configuration-migration.js", () => ({ cloudConfigurationMigrationService: () => ({ qualify }) }));
vi.mock("../services/plugin-loader.js", () => ({ pluginLoader: () => ({ loadManifest: async () => null }) }));
beforeEach(() => { qualify.mockReset(); });
it("waits for a delayed bundled manifest update before qualifying a volume-free image", async () => {
let release!: () => void;
let manifestUpdated = false;
const manifestsReady = new Promise<void>(resolve => { release = () => { manifestUpdated = true; resolve(); }; });
qualify.mockImplementation(async () => {
expect(manifestUpdated).toBe(true);
return { configurationPackagesEligible: true };
});
const result = qualifyCloudConfigurationForCurrentImage({} as Parameters<typeof qualifyCloudConfigurationForCurrentImage>[0], {
runtimeEnv: { PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: "tenant-fixture" }, bundledManifestsReady: manifestsReady,
});
await Promise.resolve();
expect(qualify).not.toHaveBeenCalled();
release();
await expect(result).resolves.toMatchObject({ configurationPackagesEligible: true });
expect(qualify).toHaveBeenCalledTimes(1);
});
it("does not qualify when bundled manifest reconciliation rejects", async () => {
await expect(qualifyCloudConfigurationForCurrentImage({} as Parameters<typeof qualifyCloudConfigurationForCurrentImage>[0], {
runtimeEnv: { PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: "tenant-fixture" }, bundledManifestsReady: Promise.reject(new Error("refresh failed")),
})).rejects.toThrow("refresh failed");
expect(qualify).not.toHaveBeenCalled();
});
+4 -2
View File
@@ -1451,7 +1451,7 @@ export async function createApp(
// that must not outrun plugin availability — managed sandbox environments
// (`applyManagedEnvironments`) run before the heartbeat resumes queued
// runs — can sequence on it. It never rejects.
const bundledPluginsStartup = ensureBundledPlugins(
const bundledPluginManifestsReady = ensureBundledPlugins(
bundledPluginInstalls,
{ registry: pluginRegistry, loader, lifecycle, logger },
// Managed mode reinstalls soft-uninstalled bundles (the control plane
@@ -1459,7 +1459,9 @@ export async function createApp(
// Disabled plugins never start automatically. Added distribution permissions
// still enter upgrade_pending so enabling them requires an operator decision.
{ reinstallUninstalled: managedAutoInstallKeys !== null, preservePackagePath: managedAutoInstallKeys !== null },
)
);
app.locals.bundledPluginManifestsReady = trackIdleWork(bundledPluginManifestsReady);
const bundledPluginsStartup = bundledPluginManifestsReady
.then(() => loader.loadAll())
.then((result) => {
if (!result) return;
+3 -1
View File
@@ -2160,7 +2160,9 @@ async function startServerWithDatabaseTeardown(
}
if (deploymentListenUrl !== null) {
const qualification = await startupTimeline.precondition("cloud_configuration", () => qualifyCloudConfigurationForCurrentImage(db as any));
const qualification = await startupTimeline.precondition("cloud_configuration", () => qualifyCloudConfigurationForCurrentImage(db as any, {
bundledManifestsReady: app.locals.bundledPluginManifestsReady,
}));
if (qualification && !qualification.configurationPackagesEligible) {
throw new Error(`Volume-free server packages are not eligible: ${qualification.blockers.map(blocker => blocker.code).join(", ")}`);
}
@@ -7,6 +7,10 @@ import { assertDistributionManifestCapabilities } from "./distribution-plugin-ca
export type BundledPluginRegistration = Pick<PluginRecord, "pluginKey" | "packageName" | "version" | "manifestJson">;
export function pluginManifestJson(manifest: PaperclipPluginManifestV1): PaperclipPluginManifestV1 {
return JSON.parse(JSON.stringify(manifest)) as PaperclipPluginManifestV1;
}
export interface BundledPluginPackageIdentity {
kind: "bundled_image";
catalogKey: string;
@@ -88,7 +92,7 @@ export function createBundledPluginPackageResolver(installs: readonly ResolvedBu
const install = byKey.get(plugin.pluginKey)!;
if (!verifiedManifest) return { compatible: false, pluginKey: plugin.pluginKey, code: "missing_manifest_evidence", reason: "Image manifest evidence is required" };
assertManifest(install, verifiedManifest);
if (!isDeepStrictEqual(verifiedManifest, plugin.manifestJson)) throw new Error("Approved plugin manifest does not match the image");
if (!isDeepStrictEqual(pluginManifestJson(verifiedManifest), pluginManifestJson(plugin.manifestJson))) throw new Error("Approved plugin manifest does not match the image");
return { compatible: true, identity: {
kind: "bundled_image", catalogKey: install.key, pluginKey: plugin.pluginKey,
packageName: plugin.packageName, version: plugin.version,
+25 -1
View File
@@ -2,6 +2,7 @@ import path from "node:path";
import fs from "node:fs";
import { isDeepStrictEqual } from "node:util";
import { isCloudManagedInstance } from "./cloud-instance.js";
import { pluginManifestJson } from "./bundled-plugin-package.js";
import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
import { assertDistributionManifestCapabilities, readDistributionPluginCatalog, type DistributionPlugin } from "./distribution-plugin-catalog.js";
@@ -257,6 +258,26 @@ function defaultBundleManifestExists(localPath: string): boolean {
return fs.existsSync(path.join(localPath, "dist", "manifest.js"));
}
function withoutDisplayDescriptions(manifest: PaperclipPluginManifestV1): unknown {
const copy = pluginManifestJson(manifest) as unknown as Record<string, unknown>;
const removeDescription = (value: unknown) => {
if (value && typeof value === "object" && !Array.isArray(value)) {
const object = value as Record<string, unknown>;
if (typeof object.description === "string") delete object.description;
}
};
removeDescription(copy);
if (Array.isArray(copy.environmentDrivers)) for (const driver of copy.environmentDrivers) {
removeDescription(driver);
const schema = driver?.configSchema;
removeDescription(schema);
if (schema?.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties)) {
for (const property of Object.values(schema.properties)) removeDescription(property);
}
}
return copy;
}
/**
* Reconcile a present bundled plugin's persisted manifest with the shipped
* bundle. The bundle is part of the release image, so its manifest is the
@@ -294,7 +315,10 @@ async function reconcileBundledPluginManifest(
}
const rebindPackage = !preservePackagePath && install.distribution && existing.packagePath !== install.localPath && existing.status !== "uninstalled";
const refreshDistribution = install.distribution && !isDeepStrictEqual(bundleManifest, existing.manifestJson);
if (bundleManifest.version === existing.version && !rebindPackage && !requiresApproval && !refreshDistribution) return;
const refreshDescriptions = !install.distribution && !["uninstalled", "upgrade_pending"].includes(existing.status) &&
!isDeepStrictEqual(pluginManifestJson(bundleManifest), pluginManifestJson(existing.manifestJson)) &&
isDeepStrictEqual(withoutDisplayDescriptions(bundleManifest), withoutDisplayDescriptions(existing.manifestJson));
if (bundleManifest.version === existing.version && !rebindPackage && !requiresApproval && !refreshDistribution && !refreshDescriptions) return;
await deps.registry.update(existing.id, {
version: bundleManifest.version,
manifest: bundleManifest,
@@ -10,9 +10,11 @@ import { pluginLoader } from "./plugin-loader.js";
export async function qualifyCloudConfigurationForCurrentImage(db: Db, options: {
runtimeEnv?: CloudInstanceEnv;
expectedPackageEvidenceDigest?: string;
bundledManifestsReady?: Promise<unknown>;
} = {}) {
const env = options.runtimeEnv ?? process.env;
if (!isCloudManagedInstance(env)) return null;
await options.bundledManifestsReady;
const service = cloudConfigurationMigrationService(db, { runtimeEnv: env });
const catalogRoot = resolveBundledCatalogRoot(env);
let installs: ResolvedBundledPlugin[];