@termix-ssh/plugin-sdk 1.0.0 → 1.0.1

package/README.md

@@ -32,11 +32,18 @@ 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 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
 npx termix-plugin sign <file.tmxplug>    # sign it, needs TERMIX_PLUGIN_SIGNING_KEY
 npx termix-plugin verify <file.tmxplug> --key <base64>   # check a signature
 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
+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.
+
 <br />
 
 ## Support

package/cli/commands/changelog.mjs

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readManifest } from "../lib/plugin-dir.mjs";
+import { loadSdkModule } from "./validate.mjs";
+
+/**
+ * Prints one version's notes from CHANGELOG.md, the manifest version unless
+ * --version says otherwise. The release workflow uses it as the release body.
+ */
+export async function changelog({ cwd, args = [] }) {
+  const index = args.indexOf("--version");
+  const version =
+    index === -1 ? readManifest(cwd).version : args[index + 1] || null;
+  if (!version) throw new Error("--version needs a value");
+
+  const file = path.join(cwd, "CHANGELOG.md");
+  if (!fs.existsSync(file)) throw new Error("There is no CHANGELOG.md");
+
+  const { changelogSection } = await loadSdkModule("changelog");
+  const section = changelogSection(fs.readFileSync(file, "utf8"), version);
+  if (!section) {
+    throw new Error(`CHANGELOG.md has no notes for ${version}`);
+  }
+  process.stdout.write(`${section}\n`);
+}

package/cli/commands/dev.mjs

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { build } from "./build.mjs";
+import { pack } from "./pack.mjs";
+import { readManifest } from "../lib/plugin-dir.mjs";
+
+const SOURCE_DIRS = new Set(["src", "locales", "migrations"]);
+const SOURCE_FILES = new Set(["manifest.json", "package.json", "README.md"]);
+
+function readOption(args, name) {
+  const index = args.indexOf(name);
+  if (index === -1) return null;
+  const value = args[index + 1];
+  if (!value) throw new Error(`${name} needs a value`);
+  return value;
+}
+
+/** True when a changed path (relative to the plugin) feeds its build. */
+export function isSourceChange(filename) {
+  if (!filename) return false;
+  const parts = String(filename).replaceAll("\\", "/").split("/");
+  if (parts.length === 1) return SOURCE_FILES.has(parts[0]);
+  return SOURCE_DIRS.has(parts[0]);
+}
+
+export function resolveDevOptions(args, env = process.env) {
+  const server = (
+    readOption(args, "--server") ??
+    env.TERMIX_SERVER_URL ??
+    "http://localhost:30001"
+  ).replace(/\/+$/, "");
+  const key = readOption(args, "--key") ?? env.TERMIX_API_KEY ?? null;
+  if (!key) {
+    throw new Error(
+      "An admin API key is needed. Pass --key tmx_... or set TERMIX_API_KEY.",
+    );
+  }
+  return { server, key, once: args.includes("--once") };
+}
+
+const HINTS = {
+  DEVELOPER_MODE_OFF:
+    "Turn on developer mode in Admin settings, under Plugins, 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.",
+  ALREADY_INSTALLED:
+    "Uninstall the copy installed from the registry first, then save again.",
+};
+
+async function request(fetchImpl, url, init) {
+  const response = await fetchImpl(url, init);
+  const text = await response.text();
+  let body = null;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = { error: text };
+  }
+  if (!response.ok) {
+    const code = body?.code;
+    const hint = code && HINTS[code] ? `\n  ${HINTS[code]}` : "";
+    throw new Error(
+      `${response.status} ${body?.error ?? response.statusText}${hint}`,
+    );
+  }
+  return body;
+}
+
+/** Uploads a packed .tmxplug and installs it, agreeing to what it asks for. */
+export async function pushPlugin(
+  file,
+  { server, key },
+  fetchImpl = globalThis.fetch,
+) {
+  const auth = { Authorization: `Bearer ${key}` };
+  const preview = await request(fetchImpl, `${server}/plugins/upload`, {
+    method: "POST",
+    headers: { ...auth, "Content-Type": "application/octet-stream" },
+    body: fs.readFileSync(file),
+  });
+  const result = await request(
+    fetchImpl,
+    `${server}/plugins/upload/${preview.token}/install`,
+    {
+      method: "POST",
+      headers: { ...auth, "Content-Type": "application/json" },
+      body: JSON.stringify({ capabilities: preview.capabilities }),
+    },
+  );
+  return { preview, result };
+}
+
+/**
+ * Builds, packs and installs the plugin on a running Termix server, then
+ * does it again on every source change. The server needs developer mode on.
+ */
+export async function dev({ cwd, args = [] }) {
+  const options = resolveDevOptions(args);
+  const outDir = fs.mkdtempSync(path.join(os.tmpdir(), "termix-plugin-dev-"));
+  let lastCapabilities = null;
+
+  const cycle = async () => {
+    const started = Date.now();
+    await build({ cwd });
+    const file = await pack({ cwd, args: ["--out", outDir] });
+    const { preview, result } = await pushPlugin(file, options);
+    fs.rmSync(file, { force: true });
+    const capabilities = preview.capabilities.join(", ") || "none";
+    if (capabilities !== lastCapabilities) {
+      console.log(`  capabilities ${capabilities}`);
+      lastCapabilities = capabilities;
+    }
+    console.log(
+      `installed ${result.id}@${result.version} on ${options.server} (${result.state}, ${Date.now() - started} ms)`,
+    );
+  };
+
+  try {
+    await cycle();
+  } catch (error) {
+    if (options.once) throw error;
+    console.error(error?.message ?? error);
+  }
+  if (options.once) return;
+
+  const { id } = readManifest(cwd);
+  console.log(`watching ${id} for changes, Ctrl+C to stop`);
+  let timer = null;
+  let running = false;
+  let again = false;
+  const fire = async () => {
+    if (running) {
+      again = true;
+      return;
+    }
+    running = true;
+    try {
+      await cycle();
+    } catch (error) {
+      console.error(error?.message ?? error);
+    } finally {
+      running = false;
+      if (again) {
+        again = false;
+        void fire();
+      }
+    }
+  };
+  fs.watch(cwd, { recursive: true }, (_event, filename) => {
+    if (!isSourceChange(filename)) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => void fire(), 300);
+  });
+  await new Promise(() => {});
+}

package/cli/commands/validate.mjs

@@ -2,24 +2,22 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { readManifest } from "../lib/plugin-dir.mjs";
-import { validateChangelog } from "../lib/changelog.mjs";
 
 /**
  * The manifest rules live in src/manifest.ts, which the server uses too, so
  * there is one implementation rather than a copy here that drifts.
  */
-async function loadParseManifest() {
-  const entry = new URL("../../dist/manifest.js", import.meta.url);
+export async function loadSdkModule(name) {
+  const entry = new URL(`../../dist/${name}.js`, import.meta.url);
   if (!fs.existsSync(fileURLToPath(entry))) {
     throw new Error("The plugin SDK is not built yet. Run: npm run build:sdk");
   }
-  const mod = await import(entry.href);
-  return mod.parseManifest;
+  return import(entry.href);
 }
 
 export async function validate({ cwd }) {
   const raw = readManifest(cwd);
-  const parseManifest = await loadParseManifest();
+  const { parseManifest } = await loadSdkModule("manifest");
   const { errors } = parseManifest(raw);
 
   const problems = [...errors];
@@ -41,7 +39,7 @@ export async function validate({ cwd }) {
   );
   problems.push(...validateNativeDependencies(cwd, raw));
   problems.push(...validatePackage(cwd, raw));
-  problems.push(...validateChangelogFile(cwd, raw));
+  problems.push(...(await validateChangelogFile(cwd, raw)));
 
   if (problems.length > 0) {
     for (const problem of problems) console.error(`  ${problem}`);
@@ -82,26 +80,20 @@ function validatePackage(cwd, raw) {
 }
 
 /**
- * CHANGELOG.json is optional, but when it is there it has to parse and its
+ * CHANGELOG.md is optional, but when it is there it has to parse and its
  * newest release has to match the manifest version.
  */
-function validateChangelogFile(cwd, raw) {
-  const jsonPath = path.join(cwd, "CHANGELOG.json");
-  if (!fs.existsSync(jsonPath)) {
-    return fs.existsSync(path.join(cwd, "CHANGELOG.md"))
-      ? [
-          "CHANGELOG.md is no longer shipped; move the release notes to CHANGELOG.json",
-        ]
-      : [];
+async function validateChangelogFile(cwd, raw) {
+  if (fs.existsSync(path.join(cwd, "CHANGELOG.json"))) {
+    return [
+      "CHANGELOG.json is no longer read; move the release notes to CHANGELOG.md",
+    ];
   }
-  let changelog;
-  try {
-    changelog = JSON.parse(fs.readFileSync(jsonPath, "utf8"));
-  } catch (error) {
-    return [`CHANGELOG.json is not valid JSON: ${error.message}`];
-  }
-  return validateChangelog(changelog, raw.version).map(
-    (problem) => `CHANGELOG.json: ${problem}`,
+  const mdPath = path.join(cwd, "CHANGELOG.md");
+  if (!fs.existsSync(mdPath)) return [];
+  const { validateChangelog } = await loadSdkModule("changelog");
+  return validateChangelog(fs.readFileSync(mdPath, "utf8"), raw.version).map(
+    (problem) => `CHANGELOG.md: ${problem}`,
   );
 }
 

package/cli/index.mjs

@@ -13,6 +13,8 @@ import { test } from "./commands/test.mjs";
 import { pack } from "./commands/pack.mjs";
 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";
 
 const COMMANDS = {
   build,
@@ -28,6 +30,8 @@ const COMMANDS = {
   verify,
   keygen,
   migrations,
+  dev,
+  changelog,
 };
 
 const [command, ...args] = process.argv.slice(2);
@@ -46,6 +50,10 @@ 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",
+      "  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]",
+      "             (or TERMIX_SERVER_URL and TERMIX_API_KEY; needs developer mode)",
     ].join("\n"),
   );
   process.exit(command ? 0 : 1);

package/cli/lib/tmxplug.mjs

@@ -9,7 +9,7 @@ export const TMXPLUG_CONTENTS = [
   "locales",
   "migrations",
   "README.md",
-  "CHANGELOG.json",
+  "CHANGELOG.md",
   "icon.svg",
 ];
 

package/dist/backend.d.ts

@@ -285,6 +285,9 @@ export interface PluginRouterOptions {
      * and matched exactly ("/callback", not "/plugin-api/<id>/callback"). A
      * ":name" segment matches one segment, and a trailing "/*" matches any
      * number of further segments, for a proxied page ("/chooser/:id/*").
+     * An entry only opens the route registered with that same path, for the
+     * methods it was registered with, so a literal route beside a ":param"
+     * ("/webhook/config" next to "/webhook/:token") still needs a login.
      *
      * For the handful of routes an unauthenticated third party has to reach: an
      * OIDC callback, an inbound webhook. Every entry is audited when the router
@@ -1601,8 +1604,9 @@ export interface PluginBinarySpec {
     /** Hex SHA-256 the file must have. */
     sha256: string;
     /**
-     * Paths checked before downloading, such as a copy baked into the Docker
-     * image. One whose checksum matches is used in place.
+     * Absolute paths checked before downloading, such as a copy baked into the
+     * Docker image. Only a regular file named `name` is considered, and one
+     * whose checksum matches is used in place.
      */
     prebuilt?: readonly string[];
 }

package/dist/changelog.d.ts

@@ -0,0 +1,67 @@
+/**
+ * CHANGELOG.md: every release of a plugin (or of core) in one Markdown file.
+ *
+ *   # Changelog
+ *
+ *   ## Unreleased
+ *
+ *   ### Added
+ *   - Something merged but not shipped yet
+ *
+ *   ## 1.1.0 - 2026-10-06
+ *
+ *   An optional summary paragraph.
+ *
+ *   ### Added
+ *   - Something new
+ *
+ *   ### Fixed
+ *   - Something broken
+ *
+ * Releases are listed newest first, and the newest one has to be the
+ * manifest version. The date is optional until the version ships.
+ */
+export declare const CHANGE_TYPES: readonly ["added", "changed", "fixed", "removed", "deprecated", "security"];
+export type ChangeType = (typeof CHANGE_TYPES)[number];
+export interface ChangelogChange {
+    type: ChangeType;
+    text: string;
+}
+export interface ChangelogRelease {
+    version: string;
+    date?: string;
+    summary?: string;
+    changes: ChangelogChange[];
+}
+export interface Changelog {
+    unreleased: ChangelogChange[];
+    /** Newest first, as written. */
+    releases: ChangelogRelease[];
+}
+export interface ReleaseNotes {
+    summary?: string;
+    changes: ChangelogChange[];
+}
+/**
+ * Parses the body under one release heading: an optional summary, then
+ * `### Added` style sections of bullets. Indented lines continue the bullet
+ * above them.
+ */
+export declare function parseReleaseNotes(body: string, where?: string): ReleaseNotes & {
+    problems: string[];
+};
+/** Parses a whole CHANGELOG.md. Problems are reported, never thrown. */
+export declare function parseChangelog(markdown: string): {
+    changelog: Changelog;
+    problems: 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.
+ */
+export declare function validateChangelog(markdown: string, manifestVersion?: string): string[];
+/**
+ * The Markdown under one version's heading, as written, for a release body.
+ * Null when the version is not in the file.
+ */
+export declare function changelogSection(markdown: string, version: string): string | null;

package/dist/changelog.js

@@ -0,0 +1,195 @@
+/**
+ * CHANGELOG.md: every release of a plugin (or of core) in one Markdown file.
+ *
+ *   # Changelog
+ *
+ *   ## Unreleased
+ *
+ *   ### Added
+ *   - Something merged but not shipped yet
+ *
+ *   ## 1.1.0 - 2026-10-06
+ *
+ *   An optional summary paragraph.
+ *
+ *   ### Added
+ *   - Something new
+ *
+ *   ### Fixed
+ *   - Something broken
+ *
+ * Releases are listed newest first, and the newest one has to be the
+ * manifest version. The date is optional until the version ships.
+ */
+import semver from "semver";
+export const CHANGE_TYPES = [
+    "added",
+    "changed",
+    "fixed",
+    "removed",
+    "deprecated",
+    "security",
+];
+const RELEASE_HEADING = /^##\s+\[?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\]?(?:\s+-\s+(.+?))?\s*$/;
+const UNRELEASED_HEADING = /^##\s+\[?unreleased\]?\s*$/i;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const BULLET = /^[-*]\s+(.*)$/;
+const COMMENT = /^<!--.*-->$/;
+/**
+ * Parses the body under one release heading: an optional summary, then
+ * `### Added` style sections of bullets. Indented lines continue the bullet
+ * above them.
+ */
+export function parseReleaseNotes(body, where = "release") {
+    const problems = [];
+    const summary = [];
+    const changes = [];
+    let section = null;
+    let current = null;
+    let fence = false;
+    for (const raw of body.replace(/\r/g, "").split("\n")) {
+        const line = raw.trimEnd();
+        const trimmed = line.trim();
+        if (trimmed.startsWith("```"))
+            fence = !fence;
+        if (!fence && trimmed.startsWith("### ")) {
+            const name = trimmed.slice(4).trim().toLowerCase();
+            if (CHANGE_TYPES.includes(name)) {
+                section = name;
+            }
+            else {
+                problems.push(`${where} has an unknown section "${trimmed.slice(4).trim()}", use one of ${CHANGE_TYPES.map(title).join(", ")}`);
+                section = null;
+            }
+            current = null;
+            continue;
+        }
+        if (!section) {
+            if (trimmed || summary.length > 0)
+                summary.push(line);
+            continue;
+        }
+        if (!trimmed || COMMENT.test(trimmed))
+            continue;
+        const bullet = fence ? null : BULLET.exec(line);
+        if (bullet) {
+            current = { type: section, text: bullet[1].trim() };
+            changes.push(current);
+        }
+        else if (current && /^\s/.test(line)) {
+            current.text += `\n${trimmed}`;
+        }
+        else {
+            problems.push(`${where} has text under "### ${title(section)}" that is not a list item: ${trimmed}`);
+        }
+    }
+    for (const change of changes) {
+        if (!change.text) {
+            problems.push(`${where} has an empty list item`);
+        }
+    }
+    const text = summary.join("\n").trim();
+    return { ...(text ? { summary: text } : {}), changes, problems };
+}
+/** Parses a whole CHANGELOG.md. Problems are reported, never thrown. */
+export function parseChangelog(markdown) {
+    const problems = [];
+    const changelog = { unreleased: [], releases: [] };
+    const lines = markdown.replace(/\r/g, "").split("\n");
+    const blocks = [];
+    let fence = false;
+    lines.forEach((line, i) => {
+        if (line.trim().startsWith("```"))
+            fence = !fence;
+        if (!fence && /^##\s/.test(line)) {
+            blocks.push({ heading: line.trim(), line: i + 1, body: [] });
+        }
+        else if (blocks.length > 0) {
+            blocks[blocks.length - 1].body.push(line);
+        }
+    });
+    const seen = new Set();
+    blocks.forEach((block, i) => {
+        if (UNRELEASED_HEADING.test(block.heading)) {
+            if (i !== 0)
+                problems.push(`"## Unreleased" has to come first`);
+            const notes = parseReleaseNotes(block.body.join("\n"), "Unreleased");
+            problems.push(...notes.problems);
+            changelog.unreleased = notes.changes;
+            return;
+        }
+        const match = RELEASE_HEADING.exec(block.heading);
+        if (!match) {
+            problems.push(`line ${block.line}: "${block.heading}" should look like "## 1.2.0 - 2026-10-06"`);
+            return;
+        }
+        const [, version, date] = match;
+        if (date !== undefined && !DATE.test(date)) {
+            problems.push(`${version} has a date "${date}", use YYYY-MM-DD`);
+        }
+        if (seen.has(version))
+            problems.push(`${version} is listed twice`);
+        seen.add(version);
+        const notes = parseReleaseNotes(block.body.join("\n"), version);
+        problems.push(...notes.problems);
+        if (notes.changes.length === 0) {
+            problems.push(`${version} has no changes listed`);
+        }
+        changelog.releases.push({
+            version,
+            ...(date && DATE.test(date) ? { date } : {}),
+            ...(notes.summary ? { summary: notes.summary } : {}),
+            changes: notes.changes,
+        });
+    });
+    const versions = changelog.releases.map((r) => r.version);
+    for (let i = 1; i < versions.length; i++) {
+        if (semver.lt(versions[i - 1], versions[i])) {
+            problems.push("releases must be listed newest first");
+            break;
+        }
+    }
+    return { changelog, problems };
+}
+/**
+ * Checks a CHANGELOG.md. With a manifest version, the newest release has to
+ * be that version, so a release never ships without its notes.
+ */
+export function validateChangelog(markdown, manifestVersion) {
+    const { changelog, problems } = parseChangelog(markdown);
+    if (changelog.releases.length === 0) {
+        problems.push('no releases found, add a "## 1.0.0" heading');
+        return problems;
+    }
+    const newest = changelog.releases[0].version;
+    if (manifestVersion && newest !== manifestVersion) {
+        problems.push(`the newest release is ${newest}, but the manifest version is ${manifestVersion}`);
+    }
+    return problems;
+}
+/**
+ * The Markdown under one version's heading, as written, for a release body.
+ * Null when the version is not in the file.
+ */
+export function changelogSection(markdown, version) {
+    const lines = markdown.replace(/\r/g, "").split("\n");
+    let start = -1;
+    let fence = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim().startsWith("```"))
+            fence = !fence;
+        if (fence || !/^##\s/.test(line))
+            continue;
+        if (start >= 0) {
+            return lines.slice(start, i).join("\n").trim();
+        }
+        const match = RELEASE_HEADING.exec(line.trim());
+        if (match && match[1] === version)
+            start = i + 1;
+    }
+    return start >= 0 ? lines.slice(start).join("\n").trim() : null;
+}
+function title(type) {
+    return type.charAt(0).toUpperCase() + type.slice(1);
+}