@termix-ssh/plugin-sdk 1.0.2 → 1.0.5

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 1.0.5
+
+### Fixed
+
+- `execCommand` timeout errors no longer include the command, which could hold a sudo password
+- `termix-plugin validate` fails when a plugin ships migrations for some database engines but not all three
+- `termix-plugin migrations` loads the table definitions from a path with a `#` or other URL characters in it
+- Text, json and encrypted columns are `longtext` on MySQL in new migrations, so they are no longer capped at 64KB. Existing migrations keep `text`
+- `i18next`, `react-dom`, `react-i18next` and `sonner` are optional peer dependencies, so npm stops installing them into backend-only plugins
+- `termix-plugin validate` accepts a beta version like `1.1.0-beta.1` when the changelog's newest release is `1.1.0` or older, so beta releases pass
+
+## 1.0.4
+
+### Fixed
+
+- `termix-plugin build` puts a plugin's own Tailwind classes in core's utilities layer, so responsive, hover and group variants and `className` overrides on SDK components work. Plain classes core already ships stay below core's utilities as before, while variants core ships go with the plugin's own so `max-h-56 md:max-h-none` keeps its order. Rebuild a plugin to pick it up
+
+## 1.0.3
+
+Plugin API 1.2.0.
+
+### Added
+
+- `docs` manifest field: an https link to the plugin's docs. Termix shows it as a Documentation link on the plugin's page and in its settings
+- `env` manifest field: the environment variables the plugin reads, listed in its docs and on its page
+- `app.docs` and `useDocsUrl()` for links into the plugin's own docs, and `DocsLink` in `@termix-ssh/plugin-sdk/ui`
+- `PanelShell` takes a `docs` link and shows it as a book icon in the header
+- `@termix-ssh/plugin-sdk/openapi` with `buildOpenApi()`, and `termix-plugin openapi`, which writes `dist/openapi.json` from the `@openapi` blocks in `src/backend`. `build` runs it too
+- `@termix-ssh/plugin-sdk/docs` with `pluginDocsUrl()`, `pluginDocsPage()` and `pluginEnvVars()`
+- `termix-plugin validate` warns when `docs/index.md` is missing or the source reads an env var the manifest does not list
+
 ## 1.0.2
 
 ### Added

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -12,7 +12,7 @@
 
 ## Overview
 
-`@termix-ssh/plugin-sdk` is what every [Termix](https://github.com/Termix-SSH/Termix) plugin builds against, including the ones that ship with Termix. It has the types for a plugin's backend and frontend, table definitions, the manifest schema, test helpers, and the `termix-plugin` CLI. The easiest way to start is the [Termix Plugin Template](https://github.com/Termix-SSH/Termix-Plugin-Template).
+`@termix-ssh/plugin-sdk` is what every [Termix](https://github.com/Termix-SSH/Termix) plugin builds against, including the ones that ship with Termix. It has the types for a plugin's backend and frontend, table definitions, the manifest schema, test helpers, and the `termix-plugin` CLI. The easiest way to start is the [Termix Plugin Template](https://github.com/Termix-SSH/Termix-Plugin-Template). The full guide is at [docs.termix.site/develop](https://docs.termix.site/develop).
 
 <br />
 
@@ -28,8 +28,10 @@ npm install --save-dev @termix-ssh/plugin-sdk
 
 ```bash
 npx termix-plugin build                  # bundle dist/backend.js and dist/frontend.js
+npx termix-plugin patch                  # apply the plugin's dependency patches (build does this too)
 npx termix-plugin test                   # run the plugin's Vitest suite
 npx termix-plugin validate               # check manifest.json and the files it names
+npx termix-plugin openapi                # write dist/openapi.json from @openapi comments
 npx termix-plugin migrations             # write migrations from the table definitions
 npx termix-plugin pack                   # write <id>-<version>.tmxplug
 npx termix-plugin changelog              # print this version's notes from CHANGELOG.md
@@ -39,7 +41,7 @@ npx termix-plugin keygen --out <dir>     # make a new signing key pair
 npx termix-plugin dev --server <url> --key <tmx_...>   # install on a server and reinstall on every change
 ```
 
-`dev` needs developer mode on (Admin settings, Plugins) and an API key from an
+`dev` needs developer mode on (Settings, General) and an API key from an
 admin account. It installs the plugin from a file, marked unverified, and
 reinstalls it each time you save. `TERMIX_SERVER_URL` and `TERMIX_API_KEY` work
 in place of the flags. Reload the page to pick up frontend changes.

package/cli/commands/build.mjs

@@ -6,6 +6,8 @@ import * as esbuild from "esbuild";
 import { BACKEND_EXTERNALS, FRONTEND_EXTERNALS } from "../lib/externals.mjs";
 import { staticUrlImports } from "../lib/static-url-imports.mjs";
 import { readManifest, resolveEntry, copyDir } from "../lib/plugin-dir.mjs";
+import { openapi } from "./openapi.mjs";
+import { splitByCoreClasses } from "../lib/css-classes.mjs";
 
 const BACKEND_ENTRIES = [
   "src/backend/index.ts",
@@ -96,35 +98,44 @@ export function applyPatches(cwd, pluginId) {
   }
 }
 
-const THEME_CSS = path.join(
+const HOST_DIR = path.join(
   path.dirname(fileURLToPath(import.meta.url)),
   "..",
   "..",
   "dist",
   "host",
-  "theme.css",
 );
+const THEME_CSS = path.join(HOST_DIR, "theme.css");
+const CORE_CLASSES = path.join(HOST_DIR, "core-classes.json");
 
-/**
- * Compiles the Tailwind classes the plugin's frontend uses into
- * dist/frontend.css, against the theme core ships in the SDK. Core only
- * compiles its own classes, so a class no core file happens to use would
- * otherwise have no CSS at all. Appended to whatever CSS the bundle already
- * produced (a library's stylesheet the plugin imports).
- */
 /**
  * Moves a plugin's Tailwind layers under their own names. Core orders
  * termix-plugin-utilities above its base styles and below its own utilities,
  * so a plugin's copy of `.hidden` can never beat core's `md:flex` just
- * because the plugin's file loaded later.
+ * because the plugin's file loaded later. Only classes core also ships go
+ * there; `utilities: false` keeps the rest in core's own utilities layer.
  */
-export function lowerPluginLayers(css) {
+export function lowerPluginLayers(css, { utilities = true } = {}) {
+  const layers = utilities ? "properties|utilities" : "properties";
   return css.replace(
-    /@layer (properties|utilities)(?=[\s{;,])/g,
+    new RegExp(`@layer (${layers})(?=[\\s{;,])`, "g"),
     "@layer termix-plugin-$1",
   );
 }
 
+/** Classes core's CSS has rules for, or null with an SDK built before 1.0.4. */
+function readCoreClasses() {
+  if (!fs.existsSync(CORE_CLASSES)) return null;
+  return new Set(JSON.parse(fs.readFileSync(CORE_CLASSES, "utf8")));
+}
+
+/**
+ * Compiles the Tailwind classes the plugin's frontend uses into
+ * dist/frontend.css, against the theme core ships in the SDK. Core only
+ * compiles its own classes, so a class no core file happens to use would
+ * otherwise have no CSS at all. Appended to whatever CSS the bundle already
+ * produced (a library's stylesheet the plugin imports).
+ */
 export async function buildTailwind(cwd, outDir) {
   const { compile, optimize } = await import("@tailwindcss/node");
   const { Scanner } = await import("@tailwindcss/oxide");
@@ -136,10 +147,9 @@ export async function buildTailwind(cwd, outDir) {
     `@import ${JSON.stringify(THEME_CSS.replaceAll("\\", "/"))};`,
     '@import "tailwindcss/utilities.css" layer(utilities);',
   ].join("\n");
-  const compiler = await compile(input, {
-    base: path.dirname(THEME_CSS),
-    onDependency: () => {},
-  });
+  // build() adds to what a compiler already emitted, so each half gets its own.
+  const compiler = () =>
+    compile(input, { base: path.dirname(THEME_CSS), onDependency: () => {} });
   const scanner = new Scanner({
     sources: [
       {
@@ -151,9 +161,23 @@ export async function buildTailwind(cwd, outDir) {
   });
   // Flattened and minified the way core's own CSS is, so it does not rely
   // on native CSS nesting.
-  const css = lowerPluginLayers(
-    optimize(compiler.build(scanner.scan()), { minify: true }).code.trim(),
-  );
+  const emit = async (candidates, options) =>
+    candidates.length === 0
+      ? ""
+      : lowerPluginLayers(
+          optimize((await compiler()).build(candidates), {
+            minify: true,
+          }).code.trim(),
+          options,
+        );
+  const candidates = scanner.scan();
+  const coreClasses = readCoreClasses();
+  const { shared, own } = coreClasses
+    ? splitByCoreClasses(candidates, coreClasses)
+    : { shared: candidates, own: [] };
+  const css = [await emit(shared), await emit(own, { utilities: false })]
+    .filter(Boolean)
+    .join("\n");
   if (!css) return;
   const target = path.join(outDir, "frontend.css");
   const existing = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
@@ -241,6 +265,7 @@ export async function build({ cwd }) {
 
   copyDir(path.join(cwd, "locales"), path.join(outDir, "locales"));
   copyDir(path.join(cwd, "migrations"), path.join(outDir, "migrations"));
+  await openapi({ cwd, quiet: true });
 
   console.log(`built ${pluginId}`);
 }

package/cli/commands/dev.mjs

@@ -42,7 +42,7 @@ export function resolveDevOptions(args, env = process.env) {
 
 const HINTS = {
   DEVELOPER_MODE_OFF:
-    "Turn on developer mode in Admin settings, under Plugins, then save again.",
+    "Turn on Plugin developer mode in Settings, General, then save again.",
   SIGNED_ONLY:
     "The server sets TERMIX_REQUIRE_SIGNED_PLUGINS, so it never installs unsigned files.",
   BUNDLED_ID: "That id ships with Termix. Use a different id while developing.",

package/cli/commands/migrations.mjs

@@ -17,7 +17,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import * as esbuild from "esbuild";
 import { BACKEND_EXTERNALS } from "../lib/externals.mjs";
 import { readManifest, resolveEntry } from "../lib/plugin-dir.mjs";
@@ -53,7 +53,7 @@ async function loadDefinitions(cwd) {
       external: BACKEND_EXTERNALS,
     });
 
-    const module = await import(`file://${outfile.split(path.sep).join("/")}`);
+    const module = await import(pathToFileURL(outfile).href);
     const tables = module.tables ?? module.default;
     if (!Array.isArray(tables)) {
       throw new Error(

package/cli/commands/openapi.mjs

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readManifest } from "../lib/plugin-dir.mjs";
+import { loadSdkModule } from "./validate.mjs";
+
+/**
+ * Writes dist/openapi.json from the @openapi blocks in src/backend. A plugin
+ * with no documented routes gets no file.
+ */
+export async function openapi({ cwd, quiet = false }) {
+  const manifest = readManifest(cwd);
+  const pluginId = manifest.id ?? path.basename(cwd);
+  const backendDir = path.join(cwd, "src", "backend");
+  if (!fs.existsSync(backendDir)) return null;
+
+  const { buildOpenApi, hasOpenApiPaths } = await loadSdkModule("openapi");
+  const spec = await buildOpenApi({
+    title: `${manifest.name ?? pluginId} API`,
+    version: manifest.version ?? "0.0.0",
+    description: manifest.description,
+    files: [path.join(backendDir, "**", "*.{ts,tsx,js,mjs}")],
+  });
+
+  const target = path.join(cwd, "dist", "openapi.json");
+  if (!hasOpenApiPaths(spec)) {
+    fs.rmSync(target, { force: true });
+    if (!quiet) console.log(`${pluginId}: no documented routes`);
+    return null;
+  }
+
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, `${JSON.stringify(spec, null, 2)}\n`);
+  if (!quiet) {
+    console.log(
+      `wrote dist/openapi.json (${Object.keys(spec.paths).length} paths)`,
+    );
+  }
+  return target;
+}

package/cli/commands/validate.mjs

@@ -41,6 +41,10 @@ export async function validate({ cwd }) {
   problems.push(...validatePackage(cwd, raw));
   problems.push(...(await validateChangelogFile(cwd, raw)));
 
+  for (const warning of docsWarnings(cwd, raw)) {
+    console.warn(`  warn  ${warning}`);
+  }
+
   if (problems.length > 0) {
     for (const problem of problems) console.error(`  ${problem}`);
     throw new Error(`${raw.id ?? path.basename(cwd)}: manifest is not valid.`);
@@ -49,6 +53,69 @@ export async function validate({ cwd }) {
   console.log(`ok  ${raw.id ?? path.basename(cwd)}`);
 }
 
+/** Env vars core sets for everyone, so a plugin need not list them. */
+const CORE_ENV = new Set([
+  "DATA_DIR",
+  "NODE_ENV",
+  "PORT",
+  "BASE_PATH",
+  "VERSION",
+  "HOME",
+  "TMPDIR",
+  "TEMP",
+  "TMP",
+  "PATH",
+  "APPDATA",
+  "LOCALAPPDATA",
+  "USERPROFILE",
+  "ELECTRON_EMBEDDED",
+]);
+
+const ENV_READS = [
+  /process\.env\.([A-Z][A-Z0-9_]*)/g,
+  /process\.env\[\s*["'`]([A-Z][A-Z0-9_]*)["'`]\s*\]/g,
+  /\benv\.([A-Z][A-Z0-9_]*)\b/g,
+  /\benv\[\s*["'`]([A-Z][A-Z0-9_]*)["'`]\s*\]/g,
+];
+
+function walkSources(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walkSources(full, out);
+    else if (/\.(ts|tsx|js|mjs|cjs)$/.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Docs gaps that do not block a release: no docs/index.md, or a process.env
+ * read the manifest does not list in env.
+ */
+export function docsWarnings(cwd, raw) {
+  const warnings = [];
+  if (!fs.existsSync(path.join(cwd, "docs", "index.md"))) {
+    warnings.push("docs/index.md is missing, so the plugin has no docs page");
+  }
+  const declared = new Set(
+    Array.isArray(raw.env) ? raw.env.map((e) => e?.name) : [],
+  );
+  const missing = new Set();
+  for (const file of walkSources(path.join(cwd, "src"))) {
+    const text = fs.readFileSync(file, "utf8");
+    for (const pattern of ENV_READS) {
+      for (const match of text.matchAll(pattern)) {
+        const name = match[1];
+        if (!declared.has(name) && !CORE_ENV.has(name)) missing.add(name);
+      }
+    }
+  }
+  for (const name of [...missing].sort()) {
+    warnings.push(`reads ${name} but manifest env does not list it`);
+  }
+  return warnings;
+}
+
 /**
  * package.json has to agree with the manifest: the same version, and a real
  * SDK range rather than "*", so a plugin built against a newer SDK says so.
@@ -151,6 +218,11 @@ async function validateMigrations(cwd, pluginId) {
   const present = DIALECTS.filter((dialect) =>
     fs.existsSync(path.join(root, dialect)),
   );
+  for (const dialect of DIALECTS) {
+    if (present.length > 0 && !present.includes(dialect)) {
+      problems.push(`migrations/${dialect} is missing`);
+    }
+  }
 
   const byDialect = new Map();
   for (const dialect of present) {

package/cli/index.mjs

@@ -15,6 +15,7 @@ import { sign, verify, keygen } from "./commands/sign.mjs";
 import { migrations } from "./commands/migrations.mjs";
 import { dev } from "./commands/dev.mjs";
 import { changelog } from "./commands/changelog.mjs";
+import { openapi } from "./commands/openapi.mjs";
 
 const COMMANDS = {
   build,
@@ -32,6 +33,7 @@ const COMMANDS = {
   migrations,
   dev,
   changelog,
+  openapi,
 };
 
 const [command, ...args] = process.argv.slice(2);
@@ -50,6 +52,7 @@ if (!command || command === "--help" || command === "-h") {
       "  verify     Check a .tmxplug's .sig <file> --key <base64>[,...]",
       "  keygen     Write a new signing key pair [--out dir]",
       "  migrations Generate migrations from the plugin's table definitions",
+      "  openapi    Write dist/openapi.json from the @openapi blocks in src/backend",
       "  changelog  Print a version's notes from CHANGELOG.md [--version x.y.z]",
       "  dev        Build, pack and install on a running server, again on every change",
       "             [--server url] [--key tmx_...] [--once]",

package/cli/lib/css-classes.mjs

@@ -0,0 +1,37 @@
+/**
+ * The class names a stylesheet has rules for, unescaped, so `.md\:w-44`
+ * reads as the candidate `md:w-44` a plugin writes.
+ */
+export function classNamesInCss(css) {
+  const names = new Set();
+  // Declarations hold numbers like 0.25rem, so only selectors are read.
+  const selectors = css.replace(/\{[^{}]*\}/g, "{}");
+  for (const match of selectors.matchAll(
+    /\.((?:\\[0-9a-fA-F]{1,6} ?|\\.|[\w-])+)/g,
+  )) {
+    names.add(
+      match[1].replace(/\\([0-9a-fA-F]{1,6}) ?|\\(.)/g, (_all, hex, char) =>
+        hex ? String.fromCodePoint(parseInt(hex, 16)) : char,
+      ),
+    );
+  }
+  return names;
+}
+
+/**
+ * Splits a plugin's candidates by whether core's own CSS already has them.
+ * A plain class core ships keeps the plugin's copy below core's utilities, so
+ * it can never reorder core's rules. Everything else goes in core's utilities
+ * layer: plugin-only classes, and every variant (md:, hover:, ...) even when
+ * core ships it, so `max-h-56 md:max-h-none` is ordered in one build and a
+ * variant still beats core's own base class.
+ */
+export function splitByCoreClasses(candidates, coreClasses) {
+  const shared = [];
+  const own = [];
+  for (const candidate of candidates) {
+    const plain = !candidate.includes(":");
+    (plain && coreClasses.has(candidate) ? shared : own).push(candidate);
+  }
+  return { shared, own };
+}

package/dist/changelog.d.ts

@@ -52,7 +52,9 @@ export declare function parseChangelog(markdown: string): {
 };
 /**
  * Checks a CHANGELOG.md. With a manifest version, the newest release has to
- * be that version, so a release never ships without its notes.
+ * be that version, so a release never ships without its notes. A beta like
+ * 1.1.0-beta.2 gets its notes from git, so it only needs the newest release
+ * to be 1.1.0 or older.
  */
 export declare function validateChangelog(markdown: string, manifestVersion?: string): string[];
 /**

package/dist/changelog.js

@@ -145,7 +145,9 @@ export function parseChangelog(markdown) {
 }
 /**
  * Checks a CHANGELOG.md. With a manifest version, the newest release has to
- * be that version, so a release never ships without its notes.
+ * be that version, so a release never ships without its notes. A beta like
+ * 1.1.0-beta.2 gets its notes from git, so it only needs the newest release
+ * to be 1.1.0 or older.
  */
 export function validateChangelog(markdown, manifestVersion) {
     const { changelog, problems } = parseChangelog(markdown);
@@ -154,7 +156,15 @@ export function validateChangelog(markdown, manifestVersion) {
         return problems;
     }
     const newest = changelog.releases[0].version;
-    if (manifestVersion && newest !== manifestVersion) {
+    const base = manifestVersion
+        ? semver.valid(semver.coerce(manifestVersion))
+        : null;
+    const betaOk = !!manifestVersion &&
+        !!semver.prerelease(manifestVersion) &&
+        !!base &&
+        !!semver.valid(newest) &&
+        semver.lte(newest, base);
+    if (manifestVersion && newest !== manifestVersion && !betaOk) {
         problems.push(`the newest release is ${newest}, but the manifest version is ${manifestVersion}`);
     }
     return problems;

package/dist/db.d.ts

@@ -37,7 +37,7 @@ interface Builder<T extends PluginColumn = PluginColumn> {
 }
 /** Auto-incrementing surrogate key: integer on sqlite, serial, auto_increment. */
 export declare const id: () => Builder<PluginColumn>;
-/** Unbounded string. Never indexable: MySQL cannot index TEXT. */
+/** Unbounded string, LONGTEXT on MySQL. Never indexable: MySQL cannot index TEXT. */
 export declare const text: () => Builder<PluginColumn>;
 /** Bounded string. Indexable on every engine. */
 export declare const varchar: (length?: number) => Builder<PluginColumn>;

package/dist/db.js

@@ -28,7 +28,7 @@ function builder(column) {
 }
 /** Auto-incrementing surrogate key: integer on sqlite, serial, auto_increment. */
 export const id = () => builder({ type: "id", primaryKey: true, notNull: true });
-/** Unbounded string. Never indexable: MySQL cannot index TEXT. */
+/** Unbounded string, LONGTEXT on MySQL. Never indexable: MySQL cannot index TEXT. */
 export const text = () => builder({ type: "text" });
 /** Bounded string. Indexable on every engine. */
 export const varchar = (length = KEY_LENGTH) => builder({ type: "varchar", length });