feat: make each plugin an npm workspace built by a termix-plugin CLI

packages/plugin-sdk/cli/commands/build.mjs

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+import * as esbuild from "esbuild";
+import { BACKEND_EXTERNALS, FRONTEND_EXTERNALS } from "../lib/externals.mjs";
+import { legacyCoreImports } from "../lib/legacy-core-imports.mjs";
+import { readManifest, resolveEntry, copyDir } from "../lib/plugin-dir.mjs";
+
+const BACKEND_ENTRIES = [
+  "src/backend/index.ts",
+  "src/backend/index.mjs",
+  "src/backend/index.js",
+];
+const FRONTEND_ENTRIES = [
+  "src/frontend/index.tsx",
+  "src/frontend/index.ts",
+  "src/frontend/index.mjs",
+  "src/frontend/index.js",
+];
+
+export async function build({ cwd }) {
+  const manifest = readManifest(cwd);
+  const pluginId = manifest.id ?? path.basename(cwd);
+  const outDir = path.join(cwd, "dist");
+
+  fs.rmSync(outDir, { recursive: true, force: true });
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const backendEntry = resolveEntry(cwd, BACKEND_ENTRIES);
+  if (!backendEntry) {
+    throw new Error(
+      `${pluginId}: no backend entry (looked for ${BACKEND_ENTRIES.join(", ")})`,
+    );
+  }
+
+  await esbuild.build({
+    entryPoints: [backendEntry],
+    outfile: path.join(outDir, "backend.js"),
+    bundle: true,
+    format: "esm",
+    platform: "node",
+    target: "node22",
+    sourcemap: true,
+    logLevel: "warning",
+    external: BACKEND_EXTERNALS,
+    plugins: [legacyCoreImports({ pluginId, platform: "node" })],
+  });
+
+  const frontendEntry = resolveEntry(cwd, FRONTEND_ENTRIES);
+  if (frontendEntry) {
+    await esbuild.build({
+      entryPoints: [frontendEntry],
+      outfile: path.join(outDir, "frontend.js"),
+      bundle: true,
+      format: "esm",
+      platform: "browser",
+      target: "es2022",
+      jsx: "automatic",
+      sourcemap: true,
+      logLevel: "warning",
+      external: FRONTEND_EXTERNALS,
+      plugins: [legacyCoreImports({ pluginId, platform: "browser" })],
+    });
+  }
+
+  copyDir(path.join(cwd, "locales"), path.join(outDir, "locales"));
+  copyDir(path.join(cwd, "migrations"), path.join(outDir, "migrations"));
+
+  console.log(`built ${pluginId}`);
+}

packages/plugin-sdk/cli/commands/pack.mjs

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+import { create } from "tar";
+import { readManifest } from "../lib/plugin-dir.mjs";
+
+/** Everything a server needs to run the plugin, and nothing else. D3 signs it. */
+const CONTENTS = [
+  "manifest.json",
+  "dist",
+  "locales",
+  "migrations",
+  "README.md",
+  "CHANGELOG.md",
+];
+
+export async function pack({ cwd }) {
+  const manifest = readManifest(cwd);
+  const pluginId = manifest.id ?? path.basename(cwd);
+  const version = manifest.version ?? "0.0.0";
+
+  if (!fs.existsSync(path.join(cwd, "dist", "backend.js"))) {
+    throw new Error(`${pluginId}: nothing built. Run termix-plugin build.`);
+  }
+
+  const files = CONTENTS.filter((entry) =>
+    fs.existsSync(path.join(cwd, entry)),
+  );
+  const outfile = path.join(cwd, `${pluginId}-${version}.tgz`);
+
+  await create({ gzip: true, cwd, file: outfile }, files);
+
+  console.log(`packed ${path.basename(outfile)}`);
+}

packages/plugin-sdk/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}`);
+  }
+}

packages/plugin-sdk/cli/commands/validate.mjs

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readManifest } from "../lib/plugin-dir.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`);
+    }
+  }
+
+  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)}`);
+}

packages/plugin-sdk/cli/index.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * termix-plugin: build, validate, test and pack a Termix plugin.
+ *
+ * Run from a plugin directory (npm run build inside plugins/<id>/ does).
+ */
+
+import process from "node:process";
+import { build } from "./commands/build.mjs";
+import { validate } from "./commands/validate.mjs";
+import { test } from "./commands/test.mjs";
+import { pack } from "./commands/pack.mjs";
+
+const COMMANDS = { build, validate, test, pack };
+
+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/",
+      "  validate   Check manifest.json and the files it names",
+      "  test       Run the plugin's vitest suite",
+      "  pack       Write a .tgz of the built plugin",
+    ].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);
+}

packages/plugin-sdk/cli/lib/externals.mjs

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ *
+ * Node builtins are external automatically through platform: "node".
+ */
+
+export const BACKEND_EXTERNALS = [
+  "@termix/plugin-sdk",
+  "@termix/plugin-sdk/*",
+  "express",
+  "ssh2",
+  "ws",
+  "multer",
+  "cookie-parser",
+  "axios",
+  "jszip",
+  "guacamole-lite",
+  "@anthropic-ai/sdk",
+  "drizzle-orm",
+  "drizzle-orm/*",
+];
+
+export const FRONTEND_EXTERNALS = [
+  "react",
+  "react-dom",
+  "react/jsx-runtime",
+  "react-dom/client",
+  "@termix/plugin-sdk",
+  "@termix/plugin-sdk/*",
+  "i18next",
+  "react-i18next",
+  // Core-provided UI libraries. A7 serves these through the SDK ui entry.
+  "lucide-react",
+  "sonner",
+  "axios",
+  "cytoscape",
+  "react-cytoscapejs",
+  "guacamole-common-js",
+  "react-xtermjs",
+  "@xterm/*",
+  // Legacy: the shell's own modules, still reached by alias. A7 removes.
+  "@/*",
+];

packages/plugin-sdk/cli/lib/legacy-core-imports.mjs

@@ -0,0 +1,61 @@
+/**
+ * Legacy core imports: the debt D1 removes.
+ *
+ * Plugin code predates the SDK and still reaches core, and in one case a
+ * sibling plugin, by relative path. Those specifiers must stay out of the
+ * bundle and be rewritten to where the built server puts the target.
+ *
+ * The rewrite is output-relative, not source-relative. Every plugin bundles
+ * to plugins/<id>/dist/backend.js, which sits at the same depth the old
+ * per-file output did, so one prefix covers a source file at any nesting.
+ *
+ * Delete this file in D1, once every plugin reaches core through the SDK.
+ */
+
+// "../../../src/backend/" or "../../../../src/backend/", any depth.
+const CORE_BACKEND = /^(?:\.\.\/)+src\/backend\//;
+// Shared types. Mostly erased at compile, but automations imports a real
+// value (AUTOMATION_DEFINITION_VERSION), so this has to resolve at runtime.
+const CORE_TYPES = /^(?:\.\.\/)+src\/types\//;
+const CORE_UI = /^(?:\.\.\/)+src\/ui\//;
+// "../../../<other-plugin>/backend/" -- only plugins/ai/.../executor.ts today.
+// esbuild filters are Go RE2, which has no lookahead, so "src" is excluded in
+// the callback rather than the pattern.
+const CROSS_PLUGIN = /^(?:\.\.\/)+([a-z0-9-]+)\/(?:src\/)?backend\//;
+
+/** dist/plugins/<id>/dist/backend.js -> dist/backend/... */
+const COMPILED_CORE = "../../../backend/backend/";
+const COMPILED_TYPES = "../../../backend/types/";
+
+export function legacyCoreImports({ pluginId, platform }) {
+  return {
+    name: "legacy-core-imports",
+    setup(build) {
+      build.onResolve({ filter: CORE_BACKEND }, (args) => ({
+        path: args.path.replace(CORE_BACKEND, COMPILED_CORE),
+        external: true,
+      }));
+
+      build.onResolve({ filter: CORE_TYPES }, (args) => ({
+        path: args.path.replace(CORE_TYPES, COMPILED_TYPES),
+        external: true,
+      }));
+
+      // The shell's own modules. Only plugins/docker's frontend entry reaches
+      // core this way; every other frontend uses the "@/" alias, which is
+      // externalized by name. A7 removes both.
+      if (platform === "browser") {
+        build.onResolve({ filter: CORE_UI }, (args) => ({
+          path: args.path,
+          external: true,
+        }));
+      }
+
+      build.onResolve({ filter: CROSS_PLUGIN }, (args) => {
+        const [, other] = CROSS_PLUGIN.exec(args.path);
+        if (other === "src" || other === pluginId) return null;
+        return { path: `../../${other}/dist/backend.js`, external: true };
+      });
+    },
+  };
+}

packages/plugin-sdk/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;
+}