deck-plugin-sdk 1.10.3 → 1.11.1

package/validate.mjs

@@ -1,112 +1,112 @@
-// The checks a package must pass to be published, that need nothing but its files: shared by
-// `deck-plugin publish` (which runs them before anything leaves the machine) and the registry's
-// own validation (deck-registry's tools/validate.mjs, which adds what needs GitHub: who owns it,
-// the release, the rebuild). One copy, so the two cannot disagree about what is valid.
-//
-// Pure: no network, no filesystem.
-
-/** Deck's own modules and the view prefixes: a plugin with one of these ids could never load. */
-export const RESERVED = new Set(["terminals", "editor", "docs", "settings", "deck", "module", "plugin", "browser"]);
-/**
- * Packages the registry's rebuild executes. Each must be the real one from npm, since the rebuild
- * runs on a machine that can merge; see the SECURITY note in deck-registry's tools/validate.mjs.
- */
-export const BUILD_RUNS = ["deck-plugin-sdk", "esbuild", "react", "lucide-react", "framer-motion"];
-export const MAX_FILE = 10 * 1024 * 1024, MAX_TOTAL = 15 * 1024 * 1024;
-export const ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
-export const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
-
-/** A file's name as a release asset: flat, so a language's snippets/x.json is snippets--x.json. */
-export const assetName = (name) => name.replace(/\//g, "--");
-
-export function compareVersions(a, b) {
-  const x = SEMVER.exec(a), y = SEMVER.exec(b);
-  for (let i = 1; i <= 3; i++) if (Number(x[i]) !== Number(y[i])) return Number(x[i]) - Number(y[i]);
-  if (x[4] === y[4]) return 0;
-  return x[4] === undefined ? 1 : y[4] === undefined ? -1 : x[4] < y[4] ? -1 : 1;
-}
-
-/** An id: its shape, and not one of Deck's own. */
-export function checkId(id) {
-  const errors = [];
-  if (!ID.test(id)) errors.push(`the id \`${id}\` must be lowercase letters, digits and dashes, 40 at most`);
-  if (RESERVED.has(id)) errors.push(`\`${id}\` is one of Deck's own names and cannot be a package id`);
-  return errors;
-}
-
-/** A plugin's plugin.json, for publishing: what the registry shows and what Deck needs. */
-export function checkManifest(m) {
-  const errors = [];
-  if (typeof m.name !== "string" || !m.name.trim() || m.name.length > 60) errors.push("the name must be 1 to 60 characters");
-  if (typeof m.description !== "string" || m.description.trim().length < 10 || m.description.length > 300) {
-    errors.push("the description must be 10 to 300 characters");
-  }
-  if (typeof m.version !== "string" || !SEMVER.test(m.version)) errors.push("`version` must be a version, such as \"1.0.0\"");
-  if (typeof m.minDeck !== "string" || !SEMVER.test(m.minDeck)) errors.push("`minDeck` must say which Deck it needs, such as \"1.8.0\"");
-  if (m.color !== undefined && !/^#[0-9a-f]{6}$/i.test(m.color)) errors.push("`color` must be #rrggbb");
-  return errors;
-}
-
-/** The release's files: the allowed names, the required ones, and the size limits. */
-export function checkAssets(kind, assets) {
-  const errors = [];
-  const ok = (n) => kind === "plugin" ? ["plugin.json", "plugin.js", "mcp.js"].includes(n) : n === "language.json" || /^snippets--[\w.-]+\.json$/.test(n);
-  for (const a of assets) if (!ok(a.name)) errors.push(`the release has \`${a.name}\`, which a ${kind} cannot contain`);
-  for (const need of kind === "plugin" ? ["plugin.json", "plugin.js"] : ["language.json"]) {
-    if (!assets.some((a) => a.name === need)) errors.push(`the release has no \`${need}\``);
-  }
-  for (const a of assets) if (a.size > MAX_FILE) errors.push(`\`${a.name}\` is ${(a.size / 1048576).toFixed(1)} MB; a file may be 10 MB at most`);
-  const total = assets.reduce((n, a) => n + a.size, 0);
-  if (total > MAX_TOTAL) errors.push(`the release is ${(total / 1048576).toFixed(1)} MB; a package may be 15 MB at most`);
-  for (const a of assets) if ("digest" in a && !/^sha256:[0-9a-f]{64}$/.test(a.digest ?? "")) errors.push(`GitHub gives no sha256 for \`${a.name}\`; upload it again`);
-  return errors;
-}
-
-/** Whether a lockfile lets `npm ci` install only published npm packages. */
-export function checkLockfile(lock) {
-  const errors = [];
-  if (!lock || lock.lockfileVersion < 2 || typeof lock.packages !== "object") return ["package-lock.json must be npm 7 or newer (lockfileVersion 2 or 3)"];
-  for (const [path, p] of Object.entries(lock.packages)) {
-    if (path === "") continue;
-    if (p.link) { errors.push(`\`${path}\` is a link to a folder; publish it to npm or bundle it`); continue; }
-    if (!p.resolved?.startsWith("https://registry.npmjs.org/") || !/^sha(512|384|256)-/.test(p.integrity ?? "")) {
-      errors.push(`\`${path}\` does not come from registry.npmjs.org with an integrity hash`);
-    }
-    const name = path.replace(/^.*node_modules\//, "");
-    const runs = BUILD_RUNS.includes(name) || name.startsWith("@esbuild/");
-    if (runs && p.name && p.name !== name) errors.push(`\`${name}\` is an alias of \`${p.name}\`; the build runs it, so it must be the real package`);
-  }
-  if (!lock.packages["node_modules/deck-plugin-sdk"]) errors.push("the lockfile has no deck-plugin-sdk; a plugin is built with it");
-  return errors;
-}
-
-/**
- * What a plugin's permissions must be, from its manifest and its bundle (`table` is the SDK's
- * permissions.json): only known names, and covering every bridge call the bundle makes. The shim
- * calls the bridge as `b().fsWrite(`, which minifying keeps, so `().fn(` is the pattern, and a
- * method of the same name on something else (a RegExp's .exec) does not count. Reaching Deck's
- * internals directly, around the bridge, is refused outright.
- */
-export function checkPermissions(declared, bundle, table) {
-  const errors = [], notes = [];
-  if (!Array.isArray(declared)) {
-    return { errors: ['plugin.json must say what it uses: "permissions": [...], or [] when it needs nothing beyond its own data and settings'], notes };
-  }
-  const unknown = declared.filter((p) => !(p in table.permissions));
-  if (unknown.length) errors.push(`unknown permission${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")} (known: ${Object.keys(table.permissions).join(", ")})`);
-  if (/__TAURI_INTERNALS__|__TAURI_IPC__|window\.__TAURI__\b/.test(bundle)) {
-    errors.push("its bundle reaches Deck's internals directly, around the bridge its permissions apply to");
-  }
-  const needs = new Map();
-  for (const [fn, p] of Object.entries(table.bridge)) {
-    if (new RegExp(`\\(\\)\\.${fn}\\(`).test(bundle)) needs.set(p, [...(needs.get(p) ?? []), fn]);
-  }
-  for (const [mod, p] of Object.entries(table.modules)) {
-    if (new RegExp(`__deck\\?\\.${mod}\\b`).test(bundle)) needs.set(p, [...(needs.get(p) ?? []), mod]);
-  }
-  for (const [p, fns] of needs) {
-    if (!declared.includes(p)) errors.push(`it uses ${fns.slice(0, 4).join(", ")}${fns.length > 4 ? ` and ${fns.length - 4} more` : ""}, which ${fns.length > 1 ? "need" : "needs"} the "${p}" permission; add it to "permissions"`);
-  }
-  if (/\beval\(|new Function\(/.test(bundle)) notes.push("Its bundle uses eval or new Function, which runs code made at run time; a library may do this legitimately.");
-  return { errors, notes };
-}
+// The checks a package must pass to be published, that need nothing but its files: shared by
+// `deck-plugin publish` (which runs them before anything leaves the machine) and the registry's
+// own validation (deck-registry's tools/validate.mjs, which adds what needs GitHub: who owns it,
+// the release, the rebuild). One copy, so the two cannot disagree about what is valid.
+//
+// Pure: no network, no filesystem.
+
+/** Deck's own modules and the view prefixes: a plugin with one of these ids could never load. */
+export const RESERVED = new Set(["terminals", "editor", "docs", "settings", "deck", "module", "plugin", "browser"]);
+/**
+ * Packages the registry's rebuild executes. Each must be the real one from npm, since the rebuild
+ * runs on a machine that can merge; see the SECURITY note in deck-registry's tools/validate.mjs.
+ */
+export const BUILD_RUNS = ["deck-plugin-sdk", "esbuild", "react", "lucide-react", "framer-motion"];
+export const MAX_FILE = 10 * 1024 * 1024, MAX_TOTAL = 15 * 1024 * 1024;
+export const ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+export const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+
+/** A file's name as a release asset: flat, so a language's snippets/x.json is snippets--x.json. */
+export const assetName = (name) => name.replace(/\//g, "--");
+
+export function compareVersions(a, b) {
+  const x = SEMVER.exec(a), y = SEMVER.exec(b);
+  for (let i = 1; i <= 3; i++) if (Number(x[i]) !== Number(y[i])) return Number(x[i]) - Number(y[i]);
+  if (x[4] === y[4]) return 0;
+  return x[4] === undefined ? 1 : y[4] === undefined ? -1 : x[4] < y[4] ? -1 : 1;
+}
+
+/** An id: its shape, and not one of Deck's own. */
+export function checkId(id) {
+  const errors = [];
+  if (!ID.test(id)) errors.push(`the id \`${id}\` must be lowercase letters, digits and dashes, 40 at most`);
+  if (RESERVED.has(id)) errors.push(`\`${id}\` is one of Deck's own names and cannot be a package id`);
+  return errors;
+}
+
+/** A plugin's plugin.json, for publishing: what the registry shows and what Deck needs. */
+export function checkManifest(m) {
+  const errors = [];
+  if (typeof m.name !== "string" || !m.name.trim() || m.name.length > 60) errors.push("the name must be 1 to 60 characters");
+  if (typeof m.description !== "string" || m.description.trim().length < 10 || m.description.length > 300) {
+    errors.push("the description must be 10 to 300 characters");
+  }
+  if (typeof m.version !== "string" || !SEMVER.test(m.version)) errors.push("`version` must be a version, such as \"1.0.0\"");
+  if (typeof m.minDeck !== "string" || !SEMVER.test(m.minDeck)) errors.push("`minDeck` must say which Deck it needs, such as \"1.8.0\"");
+  if (m.color !== undefined && !/^#[0-9a-f]{6}$/i.test(m.color)) errors.push("`color` must be #rrggbb");
+  return errors;
+}
+
+/** The release's files: the allowed names, the required ones, and the size limits. */
+export function checkAssets(kind, assets) {
+  const errors = [];
+  const ok = (n) => kind === "plugin" ? ["plugin.json", "plugin.js", "mcp.js"].includes(n) : n === "language.json" || /^snippets--[\w.-]+\.json$/.test(n);
+  for (const a of assets) if (!ok(a.name)) errors.push(`the release has \`${a.name}\`, which a ${kind} cannot contain`);
+  for (const need of kind === "plugin" ? ["plugin.json", "plugin.js"] : ["language.json"]) {
+    if (!assets.some((a) => a.name === need)) errors.push(`the release has no \`${need}\``);
+  }
+  for (const a of assets) if (a.size > MAX_FILE) errors.push(`\`${a.name}\` is ${(a.size / 1048576).toFixed(1)} MB; a file may be 10 MB at most`);
+  const total = assets.reduce((n, a) => n + a.size, 0);
+  if (total > MAX_TOTAL) errors.push(`the release is ${(total / 1048576).toFixed(1)} MB; a package may be 15 MB at most`);
+  for (const a of assets) if ("digest" in a && !/^sha256:[0-9a-f]{64}$/.test(a.digest ?? "")) errors.push(`GitHub gives no sha256 for \`${a.name}\`; upload it again`);
+  return errors;
+}
+
+/** Whether a lockfile lets `npm ci` install only published npm packages. */
+export function checkLockfile(lock) {
+  const errors = [];
+  if (!lock || lock.lockfileVersion < 2 || typeof lock.packages !== "object") return ["package-lock.json must be npm 7 or newer (lockfileVersion 2 or 3)"];
+  for (const [path, p] of Object.entries(lock.packages)) {
+    if (path === "") continue;
+    if (p.link) { errors.push(`\`${path}\` is a link to a folder; publish it to npm or bundle it`); continue; }
+    if (!p.resolved?.startsWith("https://registry.npmjs.org/") || !/^sha(512|384|256)-/.test(p.integrity ?? "")) {
+      errors.push(`\`${path}\` does not come from registry.npmjs.org with an integrity hash`);
+    }
+    const name = path.replace(/^.*node_modules\//, "");
+    const runs = BUILD_RUNS.includes(name) || name.startsWith("@esbuild/");
+    if (runs && p.name && p.name !== name) errors.push(`\`${name}\` is an alias of \`${p.name}\`; the build runs it, so it must be the real package`);
+  }
+  if (!lock.packages["node_modules/deck-plugin-sdk"]) errors.push("the lockfile has no deck-plugin-sdk; a plugin is built with it");
+  return errors;
+}
+
+/**
+ * What a plugin's permissions must be, from its manifest and its bundle (`table` is the SDK's
+ * permissions.json): only known names, and covering every bridge call the bundle makes. The shim
+ * calls the bridge as `b().fsWrite(`, which minifying keeps, so `().fn(` is the pattern, and a
+ * method of the same name on something else (a RegExp's .exec) does not count. Reaching Deck's
+ * internals directly, around the bridge, is refused outright.
+ */
+export function checkPermissions(declared, bundle, table) {
+  const errors = [], notes = [];
+  if (!Array.isArray(declared)) {
+    return { errors: ['plugin.json must say what it uses: "permissions": [...], or [] when it needs nothing beyond its own data and settings'], notes };
+  }
+  const unknown = declared.filter((p) => !(p in table.permissions));
+  if (unknown.length) errors.push(`unknown permission${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")} (known: ${Object.keys(table.permissions).join(", ")})`);
+  if (/__TAURI_INTERNALS__|__TAURI_IPC__|window\.__TAURI__\b/.test(bundle)) {
+    errors.push("its bundle reaches Deck's internals directly, around the bridge its permissions apply to");
+  }
+  const needs = new Map();
+  for (const [fn, p] of Object.entries(table.bridge)) {
+    if (new RegExp(`\\(\\)\\.${fn}\\(`).test(bundle)) needs.set(p, [...(needs.get(p) ?? []), fn]);
+  }
+  for (const [mod, p] of Object.entries(table.modules)) {
+    if (new RegExp(`__deck\\?\\.${mod}\\b`).test(bundle)) needs.set(p, [...(needs.get(p) ?? []), mod]);
+  }
+  for (const [p, fns] of needs) {
+    if (!declared.includes(p)) errors.push(`it uses ${fns.slice(0, 4).join(", ")}${fns.length > 4 ? ` and ${fns.length - 4} more` : ""}, which ${fns.length > 1 ? "need" : "needs"} the "${p}" permission; add it to "permissions"`);
+  }
+  if (/\beval\(|new Function\(/.test(bundle)) notes.push("Its bundle uses eval or new Function, which runs code made at run time; a library may do this legitimately.");
+  return { errors, notes };
+}