deck-plugin-sdk 1.12.3 → 1.13.0

package/README.md

@@ -94,4 +94,6 @@ needs a newer one, with a sentence rather than an error from inside your module.
 ## Publishing
 
 A plugin is published by being listed in Deck's registry, which points at a release in your own
-repository. Until that is open to submissions, ask.
+repository. `deck-plugin publish` makes the release and submits it; `deck-plugin publish --dry-run`
+runs every check the registry will and prints the points the version will get, check by check.
+Everything else is in [Publishing](../docs/guide/publishing.md).

package/bin/deck-plugin.mjs

@@ -82,7 +82,8 @@ function copyInto(manifest, defaultTarget) {
   const { target, dir: plugins } = pluginsDir(defaultTarget);
   const dest = join(plugins, manifest.id);
   mkdirSync(dest, { recursive: true });
-  for (const f of ["plugin.json", "plugin.js", "mcp.js"]) {
+  // icon.svg only when plugin.json names it: Deck reads it from beside the manifest.
+  for (const f of ["plugin.json", "plugin.js", "mcp.js", ...(manifest.icon === "icon.svg" ? ["icon.svg"] : [])]) {
     if (existsSync(join(dir, f))) cpSync(join(dir, f), join(dest, f));
   }
   return { target, dest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deck-plugin-sdk",
-  "version": "1.12.3",
+  "version": "1.13.0",
   "description": "Build a plugin for Deck, outside the Deck repository.",
   "type": "module",
   "license": "MIT",

package/publish.mjs

@@ -8,6 +8,7 @@
 //   the manifest, README, LICENSE and package-lock.json; a clean, pushed git tree; a build from
 //   the lockfile exactly as the registry will repeat it (npm ci, then this SDK's build); the
 //   release's files and sizes; and that its permissions cover what the bundle calls.
+// It also prints the points the registry will give this version (validate.mjs, points()).
 // Then it tags v<version>, makes the GitHub release with the built files, and opens a pull
 // request to the registry adding submissions/<id>.json, through the author's fork. The registry's
 // checks run on that PR and merge it when they pass.
@@ -17,7 +18,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkAssets, checkId, checkLockfile, checkManifest, checkPermissions } from "./validate.mjs";
+import { checkAssets, checkIcon, checkId, checkLockfile, checkManifest, checkPermissions, fileFacts, ICON_FILE, points } from "./validate.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const REGISTRY = "deck-desktop/deck-registry";
@@ -38,6 +39,10 @@ export async function publish(dir, manifest, { dryRun, buildPlugin }) {
   // ---- what is in the folder ----
   errors.push(...checkId(manifest.id ?? ""), ...checkManifest(manifest));
   if (!existsSync(join(dir, "README.md"))) errors.push("no README.md: it is the plugin's page in Deck and on the website");
+  if (manifest.icon === ICON_FILE) {
+    if (!existsSync(join(dir, ICON_FILE))) errors.push(`plugin.json's icon is ${ICON_FILE}, and there is none beside it`);
+    else errors.push(...checkIcon(readFileSync(join(dir, ICON_FILE), "utf8")));
+  }
   if (!["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING"].some((f) => existsSync(join(dir, f)))) errors.push("no LICENSE: say how others may use it (the scaffold's is MIT)");
   if (existsSync(join(dir, ".npmrc"))) errors.push("there is an .npmrc: the registry installs from registry.npmjs.org only, so remove it");
   const lockAt = join(dir, "package-lock.json");
@@ -72,10 +77,10 @@ export async function publish(dir, manifest, { dryRun, buildPlugin }) {
   if (!npm) { console.error("  ✗ npm was not found beside node"); process.exit(1); }
   run(process.execPath, [npm, "ci", "--ignore-scripts", "--no-audit", "--no-fund"]);
   await buildPlugin(dir);
-  const files = ["plugin.json", "plugin.js", "mcp.js"].filter((f) => existsSync(join(dir, f)));
+  const files = ["plugin.json", "plugin.js", "mcp.js", ...(manifest.icon === ICON_FILE ? [ICON_FILE] : [])].filter((f) => existsSync(join(dir, f)));
   errors.push(...checkAssets("plugin", files.map((f) => ({ name: f, size: statSync(join(dir, f)).size }))));
   const table = JSON.parse(readFileSync(join(here, "permissions.json"), "utf8"));
-  const perms = checkPermissions(manifest.permissions, readFileSync(join(dir, "plugin.js"), "utf8"), table);
+  const perms = checkPermissions(manifest.permissions, readFileSync(join(dir, "plugin.js"), "utf8"), table, manifest.id);
   errors.push(...perms.errors);
   notes.push(...perms.notes);
   if (errors.length) {
@@ -85,6 +90,17 @@ export async function publish(dir, manifest, { dryRun, buildPlugin }) {
 
   say(`\n${manifest.name} ${manifest.version} is ready: ${files.join(", ")}${manifest.permissions.length ? `; it uses ${manifest.permissions.join(", ")}` : ""}.`);
   for (const n of notes) say(`  note: ${n}`);
+
+  // ---- its points, as the registry will give them ----
+  const read = (f) => (existsSync(join(dir, f)) ? readFileSync(join(dir, f), "utf8") : null);
+  const tsc = join(dir, "node_modules", "typescript", "bin", "tsc");
+  let typechecks = null;
+  if (!custom && existsSync(join(dir, "tsconfig.json")) && existsSync(tsc)) typechecks = ok(process.execPath, [tsc, "--noEmit", "-p", "."]);
+  let newestSdk = null;
+  try { newestSdk = (await (await fetch("https://registry.npmjs.org/deck-plugin-sdk/latest")).json()).version ?? null; } catch { /* offline: scored as not current */ }
+  const score = points({ ...fileFacts(read), buildVerified: !custom, typechecks, permissions: manifest.permissions, used: perms.used, newestSdk });
+  say(`\nPoints: ${score.total} of 100`);
+  for (const c of score.checks) say(`  ${c.got ? "✓" : "✗"} ${c.label} (${c.got}/${c.max})${c.fix ? ` — ${c.fix}` : ""}`);
   if (dryRun) {
     say(`\nDry run: nothing was tagged, released or submitted. Without --dry-run this tags ${tag}, releases it on ${repo}, and opens a PR to ${REGISTRY}.`);
     return;

package/template/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- First version.

package/template/plugin.json

@@ -5,6 +5,6 @@
   "icon": "Sparkles",
   "color": "#a78bfa",
   "version": "0.1.0",
-  "minDeck": "1.12.3",
+  "minDeck": "1.13.0",
   "permissions": []
 }

package/types/core/bridge.d.ts

@@ -844,7 +844,8 @@ export declare const remoteHome: (host: string, sudo: boolean) => Promise<string
 export declare const sshHosts: () => Promise<string[]>;
 export declare const fsWrite: (path: string, content: string) => Promise<void>;
 /** Raw bytes — a PDF, an image, a response — which a string would corrupt. Sent as the raw body,
- *  the path percent-encoded in a header; a remote path writes over SSH. */
+ *  the path percent-encoded in a header; a remote path writes over SSH. A local write makes a
+ *  missing folder first, so a plugin's dataDir() needs no fsCreateDir. */
 export declare const fsWriteBytes: (path: string, bytes: Uint8Array) => Promise<void>;
 /** Write bytes without ever clobbering: dedupes the name on collision, returns the path used. */
 export declare const fsSaveUnique: (saveTo: string, defaultName: string, bytes: Uint8Array) => Promise<string>;

package/types/core/editor/conflictlens.d.ts

@@ -0,0 +1,3 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/** Once, at startup: the command the buttons run, the buttons, and the tints on every file model. */
+export declare function installConflictLens(): void;

package/types/core/editor/conflicts.d.ts

@@ -0,0 +1,23 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+/** One block, by the 1-based line numbers of its markers. */
+export interface ConflictBlock {
+    start: number;
+    /** The `|||||||` line of a diff3 block, else null. */
+    base: number | null;
+    mid: number;
+    end: number;
+}
+export type ConflictPick = "current" | "incoming" | "both";
+/** Every complete block, in order. A block left unclosed is not one: nothing is offered for it. */
+export declare function findConflicts(lines: string[]): ConflictBlock[];
+/** The lines a block resolves to: one side, or both with the current change first. The base never. */
+export declare function resolution(lines: string[], b: ConflictBlock, pick: ConflictPick): string[];
+/**
+ * The edit replacing block `b` with `with`, as a 1-based range (start line and column, end line
+ * and column) and its text. Whole lines go, end marker included; when nothing is kept the block's
+ * lines are removed rather than left as one empty line. `lastCol(n)` is line n's last column.
+ */
+export declare function conflictEdit(lineCount: number, lastCol: (n: number) => number, b: ConflictBlock, keep: string[], eol: string): {
+    range: readonly [number, number, number, number];
+    text: string;
+};

package/validate.mjs

@@ -11,7 +11,7 @@ export const RESERVED = new Set(["terminals", "editor", "docs", "settings", "dec
  * 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 BUILD_RUNS = ["deck-plugin-sdk", "esbuild", "react", "lucide-react", "framer-motion", "typescript"];
 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.-]+))?$/;
@@ -44,13 +44,41 @@ export function checkManifest(m) {
   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");
+  if (typeof m.icon === "string" && m.icon.endsWith(".svg") && m.icon !== ICON_FILE) errors.push(`an icon of its own must be named ${ICON_FILE}`);
+  return errors;
+}
+
+// ---- a plugin's own icon ----
+// `"icon": "icon.svg"` in plugin.json, in place of a lucide name: a file in the package, drawn in
+// one colour (the plugin's) as a mask, the way Deck draws its own icons, so it never runs and
+// follows the theme. Only shapes are allowed in it.
+
+/** The one file name a plugin's own icon may have. */
+export const ICON_FILE = "icon.svg";
+/** The largest icon accepted: an icon is a few shapes, and the catalogue carries it inline. */
+export const MAX_ICON = 16 * 1024;
+const ICON_TAGS = new Set(["svg", "g", "path", "circle", "rect", "line", "polyline", "polygon", "ellipse", "title", "desc"]);
+
+/** What is wrong with an icon.svg's text: [] when it is only shapes, with a viewBox, small enough. */
+export function checkIcon(svg) {
+  const errors = [];
+  if (Buffer.byteLength(svg) > MAX_ICON) errors.push(`${ICON_FILE} is ${(Buffer.byteLength(svg) / 1024).toFixed(1)} KB; an icon may be 16 KB at most`);
+  const body = svg.replace(/^\uFEFF?\s*(<\?xml[^>]*\?>\s*)?/, "").replace(/<!--[\s\S]*?-->/g, "").trim();
+  if (!/^<svg[\s>]/.test(body)) errors.push(`${ICON_FILE} must be an <svg> element`);
+  if (!/<svg[^>]*\sviewBox\s*=/.test(body)) errors.push(`${ICON_FILE} needs a viewBox, so it scales to the size it is drawn at`);
+  if (/<!|<\?/.test(body)) errors.push(`${ICON_FILE} may not hold a DOCTYPE, an entity or a processing instruction`);
+  const tags = [...new Set([...body.matchAll(/<\/?\s*([\w:-]+)/g)].map((m) => m[1]))].filter((t) => !ICON_TAGS.has(t));
+  if (tags.length) errors.push(`${ICON_FILE} may hold only shapes; remove ${tags.map((t) => `<${t}>`).join(", ")}`);
+  const attrs = [...new Set([...body.matchAll(/\s([\w:-]+)\s*=/g)].map((m) => m[1]))].filter((a) => /^on|^(href|xlink:href|style)$/i.test(a));
+  if (attrs.length) errors.push(`${ICON_FILE} may not have ${attrs.join(", ")}: no scripts, links or styles`);
+  if (/url\s*\(|javascript:|data:/i.test(body)) errors.push(`${ICON_FILE} may not point at anything outside itself (url(), data: or javascript:)`);
   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);
+  const ok = (n) => kind === "plugin" ? ["plugin.json", "plugin.js", "mcp.js", ICON_FILE].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}\``);
@@ -86,8 +114,14 @@ export function checkLockfile(lock) {
  * 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.
+ *
+ * With the plugin's `id`, a config named in full (`"state/term-procs"`, another
+ * plugin's `data/<id>/…`) needs "deck", as Deck's bridge asks at run time: a plain name is kept in
+ * the plugin's own folder, a name with a "/" is one of Deck's or another plugin's. Only names
+ * written out whole are seen (a name built at run time is not), and one only compared against, as
+ * a config-changed listener does, counts too: such a plugin almost always reads it.
  */
-export function checkPermissions(declared, bundle, table) {
+export function checkPermissions(declared, bundle, table, id) {
   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 };
@@ -104,9 +138,89 @@ export function checkPermissions(declared, bundle, table) {
   for (const [mod, p] of Object.entries(table.modules)) {
     if (new RegExp(`__deck\\?\\.${mod}\\b`).test(bundle)) needs.set(p, [...(needs.get(p) ?? []), mod]);
   }
+  if (id) {
+    // A minified bundle keeps the name but not the call's, so the names are what is looked for.
+    for (const [, name] of bundle.matchAll(/["'`]((?:settings|state|cache|secrets|logs)\/[\w./-]+|data\/[\w-]+\/[\w./-]*)["'`]/g)) {
+      const seen = needs.get("deck") ?? [], what = `the config "${name}"`;
+      if (!name.startsWith(`data/${id}/`) && !seen.includes(what)) needs.set("deck", [...seen, what]);
+    }
+  }
   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 };
+  return { errors, notes, used: [...needs.keys()] };
+}
+
+// ---- points ----
+// A version's points: advice for whoever is choosing a plugin, never a gate (the checks above are
+// that). Worked out once when it is published, by the registry for a submission and by
+// `deck-plugin publish --dry-run` on the author's machine, from the same facts, so they agree.
+
+/** The files a licence may be in, in the order they are looked for. */
+export const LICENSE_FILES = ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING"];
+/** Open-source licences, each by a phrase its text always has. */
+const LICENSES = [
+  ["MIT", /Permission is hereby granted, free of charge/i],
+  ["Apache-2.0", /Apache License[\s\S]{0,40}Version 2\.0/i],
+  ["BSD", /Redistribution and use in source and binary forms/i],
+  ["ISC", /Permission to use, copy, modify, and\/or distribute this software for any\s+purpose/i],
+  ["MPL-2.0", /Mozilla Public License,? (?:v\. |Version )2\.0/i],
+  ["GPL", /GNU (?:Affero |Lesser )?General Public License/i],
+  ["Unlicense", /This is free and unencumbered software released into the public domain/i],
+];
+export const licenseOf = (text) => LICENSES.find(([, re]) => re.test(text))?.[0] ?? null;
+/** A README that shows the plugin: a markdown or HTML image, or a video. */
+export const showsMedia = (md) => /!\[[^\]]*\]\(\s*[^)\s]|<img\s[^>]*src=|<video\s/i.test(md);
+
+/**
+ * The facts that need only the package's files. `read(name)` gives a file's text at the tag, or
+ * null when there is none.
+ */
+export function fileFacts(read) {
+  const licence = LICENSE_FILES.map(read).find((t) => t != null);
+  let lock = null;
+  try { lock = JSON.parse(read("package-lock.json") ?? "null"); } catch { /* not a lockfile, so none */ }
+  return {
+    license: licence == null ? null : licenseOf(licence),
+    changelog: read("CHANGELOG.md") != null,
+    readmeMedia: showsMedia(read("README.md") ?? ""),
+    lockfile: !!lock && !checkLockfile(lock).length,
+    sdk: lock?.packages?.["node_modules/deck-plugin-sdk"]?.version ?? null,
+  };
+}
+
+/** How many minor versions `v` is behind `newest`: Infinity across a major. */
+function minorsBehind(v, newest) {
+  const [a, b] = [v, newest].map((x) => x.split("-")[0].split(".").map(Number));
+  if (a[0] !== b[0]) return a[0] > b[0] ? 0 : Infinity;
+  return Math.max(0, b[1] - a[1]);
+}
+
+/**
+ * A version's points out of 100, check by check. `f` is fileFacts plus what the registry learns by
+ * building it: buildVerified, typechecks (true, false, or null when it could not be run), the
+ * permissions declared (null when plugin.json has none) and used, and the newest SDK on npm.
+ * A check not earned says how to earn it.
+ */
+export function points(f) {
+  const unused = f.permissions ? f.permissions.filter((p) => !f.used.includes(p)) : [];
+  const checks = [
+    ["readme-media", "The README shows it, with a screenshot or other image", 10, f.readmeMedia,
+      "Add a screenshot to README.md"],
+    ["changelog", "It has a changelog", 10, f.changelog, "Add a CHANGELOG.md saying what each version changed"],
+    ["license", "It has an open-source licence", 10, !!f.license, "Add a LICENSE with an open-source licence, such as MIT"],
+    ["lockfile", "Its lockfile installs only from npm, every package with a hash", 10, f.lockfile,
+      "Commit a package-lock.json made by npm 7 or newer, with nothing linked or from elsewhere"],
+    ["build-verified", "The registry rebuilt it from its source and got the same files", 10, f.buildVerified,
+      "Release what `npm ci && npm run build` makes at the tag, with no deck-plugin.config.mjs"],
+    ["permissions", "It says what it uses", 10, Array.isArray(f.permissions), "List what it uses in plugin.json's \"permissions\""],
+    ["least-privilege", "It asks for nothing it does not use", 10, Array.isArray(f.permissions) && !unused.length,
+      unused.length ? `Remove ${unused.join(", ")} from "permissions": its code never uses ${unused.length > 1 ? "them" : "it"}` : "List what it uses in plugin.json's \"permissions\""],
+    ["typechecks", "It type-checks", 20, f.typechecks === true,
+      f.typechecks === null ? "Let the registry rebuild it, with a tsconfig.json, so it can be type-checked" : "Make `npx tsc --noEmit` pass"],
+    ["up-to-date", "It is built with a current SDK", 10, !!(f.sdk && f.newestSdk && minorsBehind(f.sdk, f.newestSdk) <= 1),
+      `Build it with deck-plugin-sdk ${f.newestSdk ?? "at its newest"}`],
+  ].map(([id, label, max, ok, fix]) => ({ id, label, max, got: ok ? max : 0, ...(ok ? {} : { fix }) }));
+  return { total: checks.reduce((n, c) => n + c.got, 0), checks };
 }