A local-first multi-agent app development platform, built on PenguinHarness
/**
* The plugin import flows' pure half (features/plugins/plugin-import): the client-side size
* guard, the optional plugin-name field, the name a failed import is about, and the code → copy
* mapping.
*
* What matters is agreement with the SERVER rather than these functions' own arithmetic. The
* size guard exists only to save a user a pointless upload, so it must draw the line exactly
* where the server does (`>` the cap, not `>=`) — a stricter client silently blocks a legal
* file, a looser one replaces a clear refusal with a 413 after a long base64 upload. The name
* field is the same kind of agreement on a different rule: what it holds back is a request the
* server would answer 400 for, and what it must NOT hold back is the empty field, which is how
* the archive gets to name the plugin. The name and the message both feed a confirmation the
* user reads before overwriting a plugin directory, so a miss there either names the wrong
* plugin or asks in English.
*/
import { describe, expect, it } from "vitest";
import { ApiError } from "../src/api/client";
import { MB_BYTES } from "../src/lib/upload-limits";
import { S } from "../src/lib/strings";
import {
PLUGIN_NAME_PATTERN,
PLUGIN_ZIP_LIMIT_MB,
pluginImportErrorText,
pluginNameBody,
pluginNameFromError,
pluginNameFromUrl,
pluginNameInvalid,
pluginZipTooLarge,
} from "../src/features/plugins/plugin-import";
describe("pluginZipTooLarge", () => {
it("refuses one byte over the cap and accepts a zip of exactly the cap", () => {
// The server's check is `bytes.length > limit`, so the boundary file is legal; pinning both
// sides is the point, since an off-by-one here would be invisible in normal use and would
// reject exactly the archive a user just repacked to fit.
expect(pluginZipTooLarge(PLUGIN_ZIP_LIMIT_MB * MB_BYTES)).toBe(false);
expect(pluginZipTooLarge(PLUGIN_ZIP_LIMIT_MB * MB_BYTES + 1)).toBe(true);
expect(pluginZipTooLarge(0)).toBe(false);
});
});
describe("pluginNameFromUrl", () => {
it("names the repository of a GitHub repo URL, a trailing .git included", () => {
expect(pluginNameFromUrl("https://github.com/acme/my-plugin")).toBe("my-plugin");
expect(pluginNameFromUrl("https://github.com/acme/my-plugin.git")).toBe("my-plugin");
});
it("names the plugin root a tree URL points at, not the ref in front of it", () => {
// The plugin is the SUBDIRECTORY (the shallowest one carrying plugin.json), and the ref
// names a commit: the confirmation used to name the commit whenever the paste was of a
// directory rather than a whole repo.
expect(pluginNameFromUrl("https://github.com/acme/mono/tree/main/plugins/review")).toBe(
"review",
);
expect(pluginNameFromUrl("https://github.com/acme/mono/tree/main/skills/a/b/c")).toBe("c");
// No subdirectory at all: the URL still has to name something, and the repo is what it
// carries.
expect(pluginNameFromUrl("https://github.com/acme/mono/tree/main")).toBe("mono");
});
it("names the file a plain link points at, and is unmoved by a query, a fragment or a trailing slash", () => {
expect(pluginNameFromUrl("https://example.com/downloads/web-design.zip")).toBe("web-design");
// What a browser address bar hands back: a token, an anchor, or the slash copy-paste adds.
expect(pluginNameFromUrl("https://example.com/x.zip?token=abc#frag")).toBe("x");
expect(pluginNameFromUrl("https://github.com/acme/my-plugin/")).toBe("my-plugin");
});
it("names an npm package without its scope, whichever way the package is written", () => {
// The server installs under the package's own name — the scope is the publisher, and the
// package's directory (which is what carries plugin.json) is `package/` in every tarball.
expect(pluginNameFromUrl("@acme/data-analysis")).toBe("data-analysis");
expect(pluginNameFromUrl("@acme/[email protected]")).toBe("data-analysis");
expect(pluginNameFromUrl("npm:@acme/data-analysis")).toBe("data-analysis");
expect(pluginNameFromUrl("data-analysis")).toBe("data-analysis");
expect(pluginNameFromUrl("npm:[email protected]")).toBe("use-firecrawl");
expect(pluginNameFromUrl("https://www.npmjs.com/package/@acme/data-analysis")).toBe(
"data-analysis",
);
expect(pluginNameFromUrl("https://www.npmjs.com/package/data-analysis/v/0.2.13")).toBe(
"data-analysis",
);
});
it("keeps a repository and a package apart, and leaves the shape of an archive link alone", () => {
// The name rule is a precedence the confirmation has to reproduce: a GitHub URL is still a
// repository's name, an npmjs.com page that is not a package page names nothing, and another
// host's `/package/` path is that host's business.
expect(pluginNameFromUrl("https://github.com/acme/my-plugin")).toBe("my-plugin");
expect(pluginNameFromUrl("https://www.npmjs.com/settings/acme/tokens")).toBe("tokens");
expect(pluginNameFromUrl("https://example.com/package/thing.zip")).toBe("thing");
// A tarball link is named like a zip: the file stem, both suffixes dropped.
expect(pluginNameFromUrl("https://example.com/releases/use-firecrawl-0.2.13.tgz")).toBe(
"use-firecrawl-0.2.13",
);
});
});
describe("pluginNameInvalid", () => {
it("accepts the empty field — the name is optional — and every name the rule allows", () => {
// Empty is the normal case (the archive names the plugin), so holding it to the rule would
// block precisely the import that never needed a name.
expect(pluginNameInvalid("")).toBe(false);
expect(pluginNameInvalid(" ")).toBe(false);
expect(pluginNameInvalid("web-design")).toBe(false);
expect(pluginNameInvalid("web_design2")).toBe(false);
// The surrounding blanks are the user's typing, not a name: they are trimmed before the check
// rather than reported as a broken one.
expect(pluginNameInvalid(" web-design ")).toBe(false);
});
it("rejects what the server would answer 400 for, so the submit never earns that 400", () => {
// The name IS the directory the plugin is installed into, so a space, a dot, a slash or a
// non-ASCII character is a 400 on the route — and has to be an inline message here instead.
for (const name of ["web design", "web.design", "a/b", "a\\b", "插件", "web-design!"]) {
expect(pluginNameInvalid(name), name).toBe(true);
}
});
it("pins the pattern the inline message quotes", () => {
// The copy spells the rule out (^[A-Za-z0-9_-]+$) for a user who wants to see it; this keeps
// the quotation honest.
expect(PLUGIN_NAME_PATTERN.source).toBe("^[A-Za-z0-9_-]+$");
});
});
describe("pluginNameBody", () => {
it("omits the field entirely when the box is empty, so the server names the plugin itself", () => {
// Never `name: ""`: the server reads an absent name as "name it after the archive" and an
// empty one as a name that breaks the rule — the exact 400 this field exists to keep away.
expect(pluginNameBody("")).toEqual({});
expect("name" in pluginNameBody(" ")).toBe(false);
});
it("sends the typed name, trimmed", () => {
expect(pluginNameBody(" web-design ")).toEqual({ name: "web-design" });
});
});
describe("pluginNameFromError", () => {
it("reads the name out of the 409's own sentence", () => {
// The wording the plugin routes answer with today, quoted from the route itself rather than
// invented: the confirmation names a plugin the user is about to overwrite, and a wrong
// name there is worse than no confirmation at all.
const err = new ApiError(
409,
"plugin_exists",
"A user plugin named web-design is already installed.",
);
expect(pluginNameFromError(err, "fallback")).toBe("web-design");
});
it("also reads the tail form the skill and hook imports parse", () => {
const err = new ApiError(409, "plugin_exists", "Plugin is already installed: web-design");
expect(pluginNameFromError(err, "fallback")).toBe("web-design");
});
it("falls back to the caller's own name when the message names nothing", () => {
// A reworded server message must not leave the confirmation nameless; the picked file's
// stem (or the name the URL spells) is what the caller passes.
expect(pluginNameFromError(new ApiError(409, "plugin_exists", "conflict"), "picked")).toBe(
"picked",
);
expect(pluginNameFromError(new Error("boom"), "picked")).toBe("picked");
});
});
describe("pluginImportErrorText", () => {
/** The codes the upload, download and delete routes answer with for anything a user can fix. */
const CODES = [
"plugin_exists",
"plugin_builtin",
"unsupported_url",
"blocked_url",
"download_failed",
"invalid_plugin",
"plugin_too_large",
];
it("localizes every code the routes answer with, instead of showing the server's English message", () => {
for (const code of CODES) {
const text = pluginImportErrorText(new ApiError(400, code, "An English server message."));
expect(text, code).toBe((S.plugins.importErrors as Record<string, string>)[code]);
expect(text, code).not.toBe("An English server message.");
expect(text.length, code).toBeGreaterThan(0);
}
});
it("leaves codes it does not name to the shared mapping, and unknown failures to the generic text", () => {
expect(pluginImportErrorText(new ApiError(403, "admin_required", "Admin only."))).toBe(
(S.errors.byCode as Record<string, string>).admin_required,
);
expect(pluginImportErrorText(new Error("boom"))).toBe(S.common.unknownError);
});
it("maps the 413 the upload route answers for an over-size zip just as it maps the download one", () => {
// Both import routes answer `plugin_too_large` from the same cap, so the one code → copy row
// covers both — this pins the UPLOAD flow, whose over-size refusal used to arrive as
// `bad_request` (a code with no copy of its own, so it showed the server's English sentence).
// The mapping is keyed by code rather than by route or status, which is what makes that hold.
const text = pluginImportErrorText(
new ApiError(413, "plugin_too_large", "The archive exceeds the 14MB limit."),
);
expect(text).toBe((S.plugins.importErrors as Record<string, string>).plugin_too_large);
expect(text).not.toBe("The archive exceeds the 14MB limit.");
});
it("leaves bad_request to the server's own sentence", () => {
// The upload route's remaining refusals are bad_requests whose sentence is about the request
// in hand ("The zip archive is empty."), which says more than any generic line could — so the
// code deliberately stays out of both tables.
expect(
pluginImportErrorText(new ApiError(400, "bad_request", "The zip archive is empty.")),
).toBe("The zip archive is empty.");
});
});