@termix-ssh/plugin-sdk 1.0.0

package/cli/commands/test.mjs

@@ -0,0 +1,33 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+/**
+ * Runs vitest through its own entry rather than the npx shim, so no shell is
+ * involved and paths with spaces work the same on every platform.
+ */
+export async function test({ cwd, args }) {
+  const require = createRequire(import.meta.url);
+
+  let vitestBin;
+  try {
+    // vitest.mjs is the package bin, not an exported subpath, so resolve the
+    // manifest and walk to it.
+    const manifest = require.resolve("vitest/package.json", { paths: [cwd] });
+    vitestBin = path.join(path.dirname(manifest), "vitest.mjs");
+  } catch {
+    throw new Error(
+      "vitest is not installed. Run npm install at the repo root.",
+    );
+  }
+
+  const result = spawnSync(
+    process.execPath,
+    [vitestBin, "run", "--config", "vitest.config.ts", ...args],
+    { cwd, stdio: "inherit" },
+  );
+
+  if (result.status !== 0) {
+    throw new Error(`vitest exited with ${result.status}`);
+  }
+}

package/cli/commands/validate.mjs

@@ -0,0 +1,215 @@
+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);
+  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;
+}
+
+export async function validate({ cwd }) {
+  const raw = readManifest(cwd);
+  const parseManifest = await loadParseManifest();
+  const { errors } = parseManifest(raw);
+
+  const problems = [...errors];
+
+  // The manifest names files. They have to be there.
+  const referenced = [
+    raw.backend ?? "dist/backend.js",
+    raw.frontend ?? "dist/frontend.js",
+    raw.locales ?? "locales",
+  ];
+  for (const rel of referenced) {
+    if (!fs.existsSync(path.join(cwd, rel))) {
+      problems.push(`manifest references ${rel}, which does not exist`);
+    }
+  }
+
+  problems.push(
+    ...(await validateMigrations(cwd, raw.id ?? path.basename(cwd))),
+  );
+  problems.push(...validateNativeDependencies(cwd, raw));
+  problems.push(...validatePackage(cwd, raw));
+  problems.push(...validateChangelogFile(cwd, raw));
+
+  if (problems.length > 0) {
+    for (const problem of problems) console.error(`  ${problem}`);
+    throw new Error(`${raw.id ?? path.basename(cwd)}: manifest is not valid.`);
+  }
+
+  console.log(`ok  ${raw.id ?? path.basename(cwd)}`);
+}
+
+/**
+ * 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.
+ */
+function validatePackage(cwd, raw) {
+  const problems = [];
+  const pkgPath = path.join(cwd, "package.json");
+  if (!fs.existsSync(pkgPath)) return problems;
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+
+  if (pkg.version && raw.version && pkg.version !== raw.version) {
+    problems.push(
+      `package.json version ${pkg.version} does not match manifest version ${raw.version}`,
+    );
+  }
+
+  const sdkRange =
+    pkg.peerDependencies?.["@termix-ssh/plugin-sdk"] ??
+    pkg.dependencies?.["@termix-ssh/plugin-sdk"] ??
+    pkg.devDependencies?.["@termix-ssh/plugin-sdk"];
+  if (!sdkRange) {
+    problems.push("package.json does not depend on @termix-ssh/plugin-sdk");
+  } else if (sdkRange === "*" || sdkRange === "latest") {
+    problems.push(
+      `@termix-ssh/plugin-sdk is "${sdkRange}"; pin a range such as "^1.0.0"`,
+    );
+  }
+  return problems;
+}
+
+/**
+ * CHANGELOG.json 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",
+        ]
+      : [];
+  }
+  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}`,
+  );
+}
+
+/**
+ * A native dependency has to actually be a real dependency of the plugin, or
+ * the build's external declaration points at nothing node_modules can
+ * resolve at runtime.
+ */
+function validateNativeDependencies(cwd, raw) {
+  const problems = [];
+  const nativeDependencies = raw.nativeDependencies ?? [];
+  if (nativeDependencies.length === 0) return problems;
+
+  const pkgPath = path.join(cwd, "package.json");
+  const pkg = fs.existsSync(pkgPath)
+    ? JSON.parse(fs.readFileSync(pkgPath, "utf8"))
+    : {};
+  const deps = { ...pkg.dependencies };
+
+  for (const name of nativeDependencies) {
+    if (!(name in deps)) {
+      problems.push(
+        `nativeDependencies names "${name}", which is not in this plugin's own package.json dependencies`,
+      );
+    }
+  }
+
+  return problems;
+}
+
+const DIALECTS = ["sqlite", "postgres", "mysql"];
+
+/**
+ * Checks that a plugin's migrations only touch tables it owns.
+ *
+ * The server enforces this too, because a plugin installed from a tarball
+ * never ran this command. Here it is a build-time error with a file name
+ * attached, rather than a plugin that fails to activate later.
+ */
+async function validateMigrations(cwd, pluginId) {
+  const { LEGACY_TABLE_OWNERS: LEGACY_TABLES } =
+    await import("../../dist/db.js");
+  const { collectOwnedIndexes, findUnownedTableWrites } =
+    await import("../../dist/ddl.js");
+
+  const problems = [];
+  const legacy = new Set(
+    Object.entries(LEGACY_TABLES)
+      .filter(([, owner]) => owner === pluginId)
+      .map(([table]) => table),
+  );
+  const root = path.join(cwd, "migrations");
+  if (!fs.existsSync(root)) return problems;
+
+  const present = DIALECTS.filter((dialect) =>
+    fs.existsSync(path.join(root, dialect)),
+  );
+
+  const byDialect = new Map();
+  for (const dialect of present) {
+    const dir = path.join(root, dialect);
+    const files = fs
+      .readdirSync(dir)
+      .filter((file) => file.endsWith(".sql"))
+      .sort();
+    byDialect.set(dialect, files);
+    const sqls = files.map((file) =>
+      fs.readFileSync(path.join(dir, file), "utf8"),
+    );
+    const indexes = collectOwnedIndexes(pluginId, sqls, legacy);
+
+    for (const [index, file] of files.entries()) {
+      if (!/^\d{4}_[a-z0-9_]+\.sql$/.test(file)) {
+        problems.push(
+          `migrations/${dialect}/${file} must be named NNNN_name.sql, lower snake_case`,
+        );
+      }
+
+      const sql = sqls[index];
+      for (const problem of findUnownedTableWrites(
+        pluginId,
+        sql,
+        legacy,
+        indexes,
+      )) {
+        problems.push(`migrations/${dialect}/${file} ${problem}`);
+      }
+    }
+  }
+
+  // A migration that exists for one engine and not another leaves that
+  // deployment without the table, which is how alert_rules ended up
+  // SQLite-only in core.
+  const [first, ...rest] = present;
+  for (const dialect of rest) {
+    const a = byDialect.get(first);
+    const b = byDialect.get(dialect);
+    for (const file of a) {
+      if (!b.includes(file)) {
+        problems.push(`migrations/${dialect}/${file} is missing`);
+      }
+    }
+    for (const file of b) {
+      if (!a.includes(file)) {
+        problems.push(`migrations/${first}/${file} is missing`);
+      }
+    }
+  }
+
+  return problems;
+}

package/cli/index.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * termix-plugin: build, validate, test, pack and sign a Termix plugin.
+ *
+ * Run from a plugin directory (a plugin repo's npm run build does).
+ */
+
+import process from "node:process";
+import { applyPatches, build } from "./commands/build.mjs";
+import { readManifest } from "./lib/plugin-dir.mjs";
+import { validate } from "./commands/validate.mjs";
+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";
+
+const COMMANDS = {
+  build,
+  patch: async ({ cwd }) => applyPatches(cwd, readManifest(cwd).id),
+  validate,
+  // The tests exercise patched dependencies, so patch first like build does.
+  test: async (options) => {
+    applyPatches(options.cwd, readManifest(options.cwd).id);
+    return test(options);
+  },
+  pack,
+  sign,
+  verify,
+  keygen,
+  migrations,
+};
+
+const [command, ...args] = process.argv.slice(2);
+
+if (!command || command === "--help" || command === "-h") {
+  console.log(
+    [
+      "Usage: termix-plugin <command>",
+      "",
+      "  build      Bundle the plugin into dist/",
+      "  patch      Apply the plugin's dependency patches (build does this too)",
+      "  validate   Check manifest.json and the files it names",
+      "  test       Apply the patches, then run the plugin's vitest suite",
+      "  pack       Write <id>-<version>.tmxplug of the built plugin [--out dir]",
+      "  sign       Sign a .tmxplug with TERMIX_PLUGIN_SIGNING_KEY <file>",
+      "  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",
+    ].join("\n"),
+  );
+  process.exit(command ? 0 : 1);
+}
+
+const run = COMMANDS[command];
+if (!run) {
+  console.error(`Unknown command: ${command}`);
+  process.exit(1);
+}
+
+try {
+  await run({ cwd: process.cwd(), args });
+} catch (error) {
+  console.error(error?.message ?? error);
+  process.exit(1);
+}

package/cli/lib/changelog.mjs

@@ -0,0 +1,126 @@
+export const CHANGE_TYPES = [
+  "added",
+  "changed",
+  "fixed",
+  "removed",
+  "deprecated",
+  "security",
+];
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TOP_KEYS = ["$schema", "unreleased", "releases"];
+const RELEASE_KEYS = ["version", "date", "notes", "changes"];
+const CHANGE_KEYS = ["type", "text"];
+
+function compareVersions(a, b) {
+  const pa = SEMVER.exec(a);
+  const pb = SEMVER.exec(b);
+  for (let i = 1; i <= 3; i++) {
+    const diff = Number(pa[i]) - Number(pb[i]);
+    if (diff !== 0) return diff;
+  }
+  if (pa[4] === pb[4]) return 0;
+  if (!pa[4]) return 1;
+  if (!pb[4]) return -1;
+  return pa[4] < pb[4] ? -1 : 1;
+}
+
+function unknownKeys(value, allowed, where, problems) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key))
+      problems.push(`${where} has unknown key "${key}"`);
+  }
+}
+
+function checkChanges(changes, where, problems) {
+  if (!Array.isArray(changes)) {
+    problems.push(`${where} must be an array`);
+    return;
+  }
+  changes.forEach((change, i) => {
+    const at = `${where}[${i}]`;
+    if (!change || typeof change !== "object" || Array.isArray(change)) {
+      problems.push(`${at} must be an object`);
+      return;
+    }
+    unknownKeys(change, CHANGE_KEYS, at, problems);
+    if (!CHANGE_TYPES.includes(change.type)) {
+      problems.push(`${at}.type must be one of ${CHANGE_TYPES.join(", ")}`);
+    }
+    if (typeof change.text !== "string" || change.text.trim() === "") {
+      problems.push(`${at}.text must be a non-empty string`);
+    }
+  });
+}
+
+/**
+ * Checks a parsed CHANGELOG.json. The newest release has to be the version
+ * in the manifest, so a release never ships without its notes.
+ */
+export function validateChangelog(changelog, manifestVersion) {
+  const problems = [];
+  if (!changelog || typeof changelog !== "object" || Array.isArray(changelog)) {
+    return ["CHANGELOG.json must be an object"];
+  }
+  unknownKeys(changelog, TOP_KEYS, "CHANGELOG.json", problems);
+
+  if (changelog.unreleased !== undefined) {
+    checkChanges(changelog.unreleased, "unreleased", problems);
+  }
+
+  const releases = changelog.releases;
+  if (!Array.isArray(releases) || releases.length === 0) {
+    problems.push("releases must be a non-empty array");
+    return problems;
+  }
+
+  const seen = new Set();
+  releases.forEach((release, i) => {
+    const at = `releases[${i}]`;
+    if (!release || typeof release !== "object" || Array.isArray(release)) {
+      problems.push(`${at} must be an object`);
+      return;
+    }
+    unknownKeys(release, RELEASE_KEYS, at, problems);
+    if (typeof release.version !== "string" || !SEMVER.test(release.version)) {
+      problems.push(`${at}.version must be a version like 1.2.3`);
+    } else if (seen.has(release.version)) {
+      problems.push(`${at}.version ${release.version} is listed twice`);
+    } else {
+      seen.add(release.version);
+    }
+    if (
+      release.date !== undefined &&
+      (typeof release.date !== "string" || !DATE.test(release.date))
+    ) {
+      problems.push(`${at}.date must be a date like 2026-10-01`);
+    }
+    if (release.notes !== undefined && typeof release.notes !== "string") {
+      problems.push(`${at}.notes must be a string`);
+    }
+    checkChanges(release.changes, `${at}.changes`, problems);
+    if (Array.isArray(release.changes) && release.changes.length === 0) {
+      problems.push(`${at}.changes must list at least one change`);
+    }
+  });
+
+  const versions = releases
+    .map((release) => release?.version)
+    .filter((v) => typeof v === "string" && SEMVER.test(v));
+  for (let i = 1; i < versions.length; i++) {
+    if (compareVersions(versions[i - 1], versions[i]) < 0) {
+      problems.push("releases must be listed newest first");
+      break;
+    }
+  }
+
+  const newest = releases[0]?.version;
+  if (manifestVersion && newest !== manifestVersion) {
+    problems.push(
+      `the newest release is ${newest}, but manifest version is ${manifestVersion}`,
+    );
+  }
+
+  return problems;
+}

package/cli/lib/externals.mjs

@@ -0,0 +1,46 @@
+/**
+ * Host-provided packages.
+ *
+ * These ship with the Termix server and are never bundled into a plugin:
+ * bundling them would give each plugin its own copy of express or React, and
+ * a second ssh2 would mean a second set of native bindings. A plugin may
+ * depend on anything outside these lists, and that does get bundled.
+ *
+ * A plugin lists the ones it uses as peerDependencies. Only add a package here
+ * when core itself ships it; a library one plugin needs belongs in that
+ * plugin's own dependencies, so it can update without a core release.
+ *
+ * Node builtins are external automatically through platform: "node".
+ */
+
+export const BACKEND_EXTERNALS = [
+  "@termix-ssh/plugin-sdk",
+  "@termix-ssh/plugin-sdk/*",
+  "express",
+  "ssh2",
+  "ws",
+  "multer",
+  "cookie-parser",
+  "axios",
+  "drizzle-orm",
+  "drizzle-orm/*",
+  // Native image processing, loaded on first use by the terminal's image upload.
+  "sharp",
+];
+
+/**
+ * Resolved by the page's import map to the shell's own copies, because these
+ * must be one instance: React, i18next, the toast store, and the SDK entries
+ * that share state with core. Anything else a plugin imports is bundled.
+ */
+export const FRONTEND_EXTERNALS = [
+  "react",
+  "react-dom",
+  "react/jsx-runtime",
+  "react-dom/client",
+  "i18next",
+  "react-i18next",
+  "sonner",
+  "@termix-ssh/plugin-sdk/frontend",
+  "@termix-ssh/plugin-sdk/ui",
+];

package/cli/lib/plugin-dir.mjs

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function readManifest(cwd) {
+  const manifestPath = path.join(cwd, "manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`No manifest.json in ${cwd}`);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    throw new Error(`manifest.json is not valid JSON: ${error.message}`);
+  }
+}
+
+/** The first of these that exists, or null. */
+export function resolveEntry(cwd, candidates) {
+  for (const candidate of candidates) {
+    const full = path.join(cwd, candidate);
+    if (fs.existsSync(full)) return full;
+  }
+  return null;
+}
+
+export function copyDir(from, to) {
+  if (!fs.existsSync(from)) return false;
+  fs.cpSync(from, to, { recursive: true });
+  return true;
+}

package/cli/lib/signing.mjs

@@ -0,0 +1,86 @@
+import crypto from "node:crypto";
+
+/** The env var that holds the base64 PKCS8 private key. Never commit it. */
+export const SIGNING_KEY_ENV = "TERMIX_PLUGIN_SIGNING_KEY";
+
+// DER prefix of an Ed25519 SubjectPublicKeyInfo; the raw 32-byte key follows.
+const SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+export function sha256(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest();
+}
+
+export function publicKeyFromRaw(base64) {
+  const raw = Buffer.from(base64.trim(), "base64");
+  if (raw.length !== 32) throw new Error("A public key is 32 bytes, base64");
+  return crypto.createPublicKey({
+    key: Buffer.concat([SPKI_PREFIX, raw]),
+    format: "der",
+    type: "spki",
+  });
+}
+
+export function rawPublicKey(keyObject) {
+  const der = keyObject.export({ format: "der", type: "spki" });
+  return der.subarray(SPKI_PREFIX.length).toString("base64");
+}
+
+/** First 16 hex chars of the sha256 of the raw public key. */
+export function keyId(publicKeyBase64) {
+  return sha256(Buffer.from(publicKeyBase64, "base64"))
+    .toString("hex")
+    .slice(0, 16);
+}
+
+export function generateKeyPair() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+  const publicBase64 = rawPublicKey(publicKey);
+  return {
+    publicKey: publicBase64,
+    privateKey: privateKey
+      .export({ format: "der", type: "pkcs8" })
+      .toString("base64"),
+    keyId: keyId(publicBase64),
+  };
+}
+
+/** Accepts base64 PKCS8 DER (what keygen writes) or a PEM block. */
+export function loadPrivateKey(value) {
+  if (!value || !value.trim()) {
+    throw new Error(`${SIGNING_KEY_ENV} is not set`);
+  }
+  const trimmed = value.trim();
+  const key = trimmed.startsWith("-----BEGIN")
+    ? crypto.createPrivateKey(trimmed)
+    : crypto.createPrivateKey({
+        key: Buffer.from(trimmed, "base64"),
+        format: "der",
+        type: "pkcs8",
+      });
+  if (key.asymmetricKeyType !== "ed25519") {
+    throw new Error("The signing key must be an Ed25519 key");
+  }
+  return key;
+}
+
+/** Ed25519 over the raw 32-byte sha256 of the artifact, base64. */
+export function signArtifact(buffer, privateKey) {
+  return crypto.sign(null, sha256(buffer), privateKey).toString("base64");
+}
+
+/** The id of the first key that verifies the signature, or null. */
+export function verifyArtifact(buffer, signatureBase64, publicKeys) {
+  const digest = sha256(buffer);
+  const signature = Buffer.from(signatureBase64.trim(), "base64");
+  if (signature.length !== 64) return null;
+  for (const key of publicKeys) {
+    try {
+      if (crypto.verify(null, digest, publicKeyFromRaw(key), signature)) {
+        return keyId(key);
+      }
+    } catch {
+      // A malformed key is just a key that does not match.
+    }
+  }
+  return null;
+}

package/cli/lib/static-url-imports.mjs

@@ -0,0 +1,54 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * `import url from "some/file.js?url"` in a plugin frontend, as core's Vite
+ * build allows: the file is copied next to the bundle under assets/ and the
+ * import becomes its URL, resolved against the bundle's own URL so it works
+ * under /plugin-assets/<id>/. Only scripts, since that is all the asset
+ * route serves (a pdfjs or Monaco worker, say).
+ */
+export function staticUrlImports({ outDir }) {
+  return {
+    name: "static-url-imports",
+    setup(build) {
+      build.onResolve({ filter: /\?url$/ }, async (args) => {
+        const target = args.path.slice(0, -"?url".length);
+        const resolved = await build.resolve(target, {
+          kind: args.kind,
+          resolveDir: args.resolveDir,
+          importer: args.importer,
+        });
+        if (resolved.errors.length > 0) return { errors: resolved.errors };
+        return { path: resolved.path, namespace: "static-url" };
+      });
+
+      build.onLoad({ filter: /.*/, namespace: "static-url" }, (args) => {
+        if (!/\.(m?js|cjs)$/.test(args.path)) {
+          return {
+            errors: [
+              {
+                text: `${args.path}: only script files can be imported with ?url`,
+              },
+            ],
+          };
+        }
+        const bytes = fs.readFileSync(args.path);
+        const hash = crypto
+          .createHash("sha256")
+          .update(bytes)
+          .digest("hex")
+          .slice(0, 8);
+        const base = path.basename(args.path).replace(/\.(m?js|cjs)$/, "");
+        const name = `${base}-${hash}.js`;
+        fs.mkdirSync(path.join(outDir, "assets"), { recursive: true });
+        fs.writeFileSync(path.join(outDir, "assets", name), bytes);
+        return {
+          contents: `export default new URL("./assets/${name}", import.meta.url).href;`,
+          loader: "js",
+        };
+      });
+    },
+  };
+}