feat(plugins): sandbox plugin UI extensions and EXPLAIN parsers in CSP-restricted iframes

package.json

@@ -14,6 +14,7 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc -b && vite build",
+    "build:plugin-guest": "node packages/plugin-guest/build.mjs",
     "lint": "eslint . && node scripts/check-theme-tokens.mjs",
     "lint:theme": "node scripts/check-theme-tokens.mjs",
     "test:contrast": "vitest run tests/utils/themeContrast.test.ts",
@@ -96,6 +97,7 @@
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.26",
+    "esbuild": "^0.27.4",
     "gitnexus": "^1.6.9",
     "globals": "^16.5.0",
     "jsdom": "^28.1.0",

packages/create-plugin/src/cli.ts

@@ -10,7 +10,7 @@ import { titleCase, validateDbType, validateName, validateQuote } from "./valida
 // Resolved at runtime so `--version` can never drift from package.json again.
 const PACKAGE_VERSION = (createRequire(import.meta.url)("../package.json") as { version: string }).version;
 // Caret range written into scaffolded plugins; bump alongside packages/plugin-api.
-const PLUGIN_API_VERSION = "0.2.0";
+const PLUGIN_API_VERSION = "0.3.0";
 const MIN_TABULARIS_VERSION = "0.9.20";
 
 function main(argv: string[]): number {

packages/create-plugin/tsconfig.json

@@ -4,6 +4,7 @@
     "module": "ESNext",
     "moduleResolution": "bundler",
     "lib": ["ES2022"],
+    "types": ["node"],
     "strict": true,
     "noImplicitAny": true,
     "noUnusedLocals": true,
@@ -17,7 +18,7 @@
     "resolveJsonModule": true,
     "verbatimModuleSyntax": true,
     "outDir": "dist",
-    "rootDir": "src"
+    "rootDir": "../.."
   },
   "include": ["src/**/*"],
   "exclude": ["dist", "node_modules", "scripts", "tests", "templates"]

packages/explain/README.md

@@ -53,13 +53,13 @@ SQLite `EXPLAIN QUERY PLAN` rows:
 import { parseExplain, parseExplainFor, parseRawExplain } from "@tabularis/explain";
 
 // Sniff the format of a pasted blob or an uploaded file:
-const plan = parseExplain(raw);
+const plan = await parseExplain(raw);
 
 // Or name the engine when the caller knows it:
-const hinted = parseExplainFor(raw, "mysql");
+const hinted = await parseExplainFor(raw, "mysql");
 
 // Or parse the raw payload a host driver handed over:
-const fromDriver = parseRawExplain({ engine, format, payload, original_query });
+const fromDriver = await parseRawExplain({ engine, format, payload, original_query });
 ```
 
 A host obtains the bytes however it likes — a driver, a pasted textarea, an
@@ -86,6 +86,9 @@ registerExplainParser({
 ```
 
 Import the parser package before calling `parseRawExplain` or source detection.
+These helpers are asynchronous because plugin parsers run in isolated guest
+frames. Await `detectFormat`, `detectFormatFor`, `parseExplain`,
+`parseExplainFor`, `parseRawExplain`, and `resolveExplainOutput`.
 Registering the same format again replaces it, which supports plugin upgrades;
 call `unregisterExplainParser(format)` when unloading it.
 

packages/explain/src/parsers/source.ts

@@ -97,8 +97,8 @@ export function explainEngineFromDriverName(name: string): ExplainEngine | null
  *
  * Recognises the two Postgres shapes before trying registered custom sniffers.
  */
-export function detectFormat(raw: string): ExplainSourceFormat {
-  return detectFormatFor(raw, null);
+export async function detectFormat(raw: string): Promise<ExplainSourceFormat> {
+  return await detectFormatFor(raw, null);
 }
 
 /**
@@ -108,19 +108,19 @@ export function detectFormat(raw: string): ExplainSourceFormat {
  * Built-in hints retain their historical decisions. Custom parsers are tried
  * in registry order and only through their side-effect-free sniffers.
  */
-export function detectFormatFor(
+export async function detectFormatFor(
   raw: string,
   engine: ExplainEngine | null,
-): ExplainSourceFormat {
+): Promise<ExplainSourceFormat> {
   switch (engine) {
     case "postgres":
-      return detectPostgresFormat(raw);
+      return Promise.resolve(detectPostgresFormat(raw));
     case "mysql":
-      if (looksLikeJson(raw)) return "mysql-json";
+      if (looksLikeJson(raw)) return Promise.resolve("mysql-json");
       if (raw.trim() === "") {
         throw new Error("Unsupported EXPLAIN file format: input is empty");
       }
-      return "mysql-text";
+      return Promise.resolve("mysql-text");
     case "sqlite":
       throw new Error(
         "SQLite EXPLAIN QUERY PLAN has no text form here: pass its " +
@@ -129,16 +129,14 @@ export function detectFormatFor(
     case null: {
       const builtinFormat = detectPostgresFormatOrNull(raw);
       if (builtinFormat !== null) return builtinFormat;
-
-      const customFormat = sniffRegisteredFormat(raw, null);
+      const customFormat = await sniffRegisteredFormat(raw, null);
       if (customFormat !== null) return customFormat;
-
       throw new Error(
         "Unsupported EXPLAIN file format: expected Postgres JSON or text output",
       );
     }
     default: {
-      const format = sniffRegisteredFormat(raw, engine);
+      const format = await sniffRegisteredFormat(raw, engine);
       if (format !== null) return format;
       throw new Error(`Unsupported EXPLAIN file format for engine '${engine}'`);
     }
@@ -161,10 +159,10 @@ function detectPostgresFormatOrNull(
   return null;
 }
 
-function sniffRegisteredFormat(
+async function sniffRegisteredFormat(
   raw: string,
   engine: ExplainEngine | null,
-): ExplainSourceFormat | null {
+): Promise<ExplainSourceFormat | null> {
   const normalizedEngine = engine?.trim().toLowerCase() ?? null;
 
   for (const parser of listExplainParsers()) {
@@ -180,7 +178,7 @@ function sniffRegisteredFormat(
     if (parser.sniff === undefined) continue;
 
     try {
-      if (parser.sniff(raw)) return parser.format;
+      if (await parser.sniff(raw)) return parser.format;
     } catch {
       // A sniffer is advisory; one broken parser must not block later parsers.
     }
@@ -206,16 +204,17 @@ function looksLikePostgresText(raw: string): boolean {
  *
  * Equivalent to `parseExplainFor(raw, null)`.
  */
-export function parseExplain(raw: string): ExplainPlan {
+export function parseExplain(raw: string): Promise<ExplainPlan> {
   return parseExplainFor(raw, null);
 }
 
 /** Parse a payload, using the caller's engine hint when there is one. */
-export function parseExplainFor(
+export async function parseExplainFor(
   raw: string,
   engine: ExplainEngine | null,
-): ExplainPlan {
-  return parserFor(detectFormatFor(raw, engine)).parse(raw);
+): Promise<ExplainPlan> {
+  const format = await detectFormatFor(raw, engine);
+  return await parserFor(format).parse(raw);
 }
 
 /**

packages/explain/src/raw.ts

@@ -44,7 +44,7 @@ export type ExplainQueryOutput =
   | { kind: "plan"; plan: ExplainPlan };
 
 /** Parse a driver's raw EXPLAIN payload into a plan. */
-export function parseRawExplain(raw: RawExplainOutput): ExplainPlan {
+export async function parseRawExplain(raw: RawExplainOutput): Promise<ExplainPlan> {
   const parser = getExplainParser(raw.format);
   if (parser === null) {
     throw new Error(
@@ -53,7 +53,7 @@ export function parseRawExplain(raw: RawExplainOutput): ExplainPlan {
     );
   }
 
-  const plan = parser.parse(raw.payload);
+  const plan = await parser.parse(raw.payload);
   return {
     ...plan,
     driver: raw.engine,
@@ -62,6 +62,6 @@ export function parseRawExplain(raw: RawExplainOutput): ExplainPlan {
 }
 
 /** Normalise either shape of `ExplainQueryOutput` into a plan. */
-export function resolveExplainOutput(output: ExplainQueryOutput): ExplainPlan {
-  return output.kind === "plan" ? output.plan : parseRawExplain(output.raw);
+export function resolveExplainOutput(output: ExplainQueryOutput): Promise<ExplainPlan> {
+  return output.kind === "plan" ? Promise.resolve(output.plan) : parseRawExplain(output.raw);
 }

packages/explain/src/registry.ts

@@ -9,9 +9,9 @@ export interface RegisteredExplainParser {
   /** Human label for format pickers. */
   readonly label?: string;
   /** Parse the raw payload or throw an Error. */
-  parse(payload: string): ExplainPlan;
+  parse(payload: string): ExplainPlan | Promise<ExplainPlan>;
   /** Cheap, side-effect-free source detection. */
-  sniff?(payload: string): boolean;
+  sniff?(payload: string): boolean | Promise<boolean>;
 }
 
 const builtinParsersByFormat = new Map(

packages/explain/tests/parsers/postgres.test.ts

@@ -48,22 +48,22 @@ const POSTGRES_NESTED = `[
 
 describe("postgres parsers", () => {
   describe("detectFormat", () => {
-    it("accepts a JSON array", () => {
-      expect(detectFormat(" \n [\n  {} ]")).toBe("postgres-json");
+    it("accepts a JSON array", async () => {
+      expect(await detectFormat(" \n [\n  {} ]")).toBe("postgres-json");
     });
 
-    it("accepts a JSON object", () => {
-      expect(detectFormat('{ "Plan": {} }')).toBe("postgres-json");
+    it("accepts a JSON object", async () => {
+      expect(await detectFormat('{ "Plan": {} }')).toBe("postgres-json");
     });
 
-    it("rejects plain text without a cost header", () => {
-      expect(() =>
+    it("rejects plain text without a cost header", async () => {
+      await expect(
         detectFormat("Seq Scan on users  (cost=0.00..12.34 rows=100)"),
-      ).toThrow(/Unsupported/);
+      ).rejects.toThrow(/Unsupported/);
     });
 
-    it("recognises text output with a cost header", () => {
-      expect(detectFormat(POSTGRES_TEXT_FLAT)).toBe("postgres-text");
+    it("recognises text output with a cost header", async () => {
+      expect(await detectFormat(POSTGRES_TEXT_FLAT)).toBe("postgres-text");
     });
   });
 
@@ -112,20 +112,20 @@ describe("postgres parsers", () => {
   });
 
   describe("parseExplain error paths", () => {
-    it("rejects an empty array", () => {
-      expect(() => parseExplain("[]")).toThrow(/empty/);
+    it("rejects an empty array", async () => {
+      await expect(parseExplain("[]")).rejects.toThrow(/empty/);
     });
 
-    it("rejects a missing Plan key", () => {
-      expect(() => parseExplain('[{"NotAPlan": 1}]')).toThrow(/Plan/);
+    it("rejects a missing Plan key", async () => {
+      await expect(parseExplain('[{"NotAPlan": 1}]')).rejects.toThrow(/Plan/);
     });
 
-    it("rejects invalid JSON", () => {
-      expect(() => parseExplain("[not json]")).toThrow(/Failed to parse/);
+    it("rejects invalid JSON", async () => {
+      await expect(parseExplain("[not json]")).rejects.toThrow(/Failed to parse/);
     });
 
-    it("rejects an unsupported format", () => {
-      expect(() => parseExplain("-> Nested Loop  (cost=0.00..1.23)")).toThrow(
+    it("rejects an unsupported format", async () => {
+      await expect(parseExplain("-> Nested Loop  (cost=0.00..1.23)")).rejects.toThrow(
         /Unsupported/,
       );
     });
@@ -192,8 +192,8 @@ describe("postgres parsers", () => {
   });
 
   describe("parseExplain routing", () => {
-    it("routes text output to the text parser", () => {
-      const plan = parseExplain(POSTGRES_TEXT_FLAT);
+    it("routes text output to the text parser", async () => {
+      const plan = await parseExplain(POSTGRES_TEXT_FLAT);
       expect(plan.root.node_type).toBe("Seq Scan");
     });
   });

packages/explain/tests/parsers/source.test.ts

@@ -44,8 +44,8 @@ const POSTGRES_TEXT = " Seq Scan on users  (cost=0.00..12.34 rows=100 width=80)\
 
 describe("source dispatch", () => {
   describe("an engine hint reaches parsers that sniffing cannot", () => {
-    it("parses MySQL JSON when the engine is given", () => {
-      const plan = parseExplainFor(MYSQL_JSON, "mysql");
+    it("parses MySQL JSON when the engine is given", async () => {
+      const plan = await parseExplainFor(MYSQL_JSON, "mysql");
 
       expect(plan.driver).toBe("mysql");
       expect(plan.root.relation).toBe("users");
@@ -54,60 +54,60 @@ describe("source dispatch", () => {
       expect(plan.raw_output).not.toBeNull();
     });
 
-    it("keeps MariaDB optimizer time as planning time", () => {
-      const plan = parseExplainFor(MARIADB_ANALYZE_JSON, "mysql");
+    it("keeps MariaDB optimizer time as planning time", async () => {
+      const plan = await parseExplainFor(MARIADB_ANALYZE_JSON, "mysql");
 
       expect(plan.planning_time_ms).toBe(1.875);
       expect(plan.has_analyze_data, "r_* fields are actual data").toBe(true);
       expect(plan.root.relation).toBe("orders");
     });
 
-    it("parses MySQL text when the engine is given", () => {
-      const plan = parseExplainFor(MYSQL_TEXT, "mysql");
+    it("parses MySQL text when the engine is given", async () => {
+      const plan = await parseExplainFor(MYSQL_TEXT, "mysql");
 
       expect(plan.driver).toBe("mysql");
       expect(plan.root.node_type).toBe("Nested Loop");
       expect(plan.has_analyze_data).toBe(true);
     });
 
-    it("still fails on MySQL JSON without a hint, as before", () => {
+    it("still fails on MySQL JSON without a hint, as before", async () => {
       // Sniffing sees a leading `{` and tries Postgres, which has no `Plan` key.
-      expect(() => parseExplain(MYSQL_JSON)).toThrow(/Plan/);
+      await expect(parseExplain(MYSQL_JSON)).rejects.toThrow(/Plan/);
     });
   });
 
   describe("the unhinted path is unchanged", () => {
-    it("matches the previous sniffing behaviour", () => {
-      expect(detectFormat(POSTGRES_JSON)).toBe("postgres-json");
-      expect(detectFormat(POSTGRES_TEXT)).toBe("postgres-text");
-      expect(detectFormatFor(POSTGRES_JSON, null)).toBe(detectFormat(POSTGRES_JSON));
-      expect(() => detectFormat("not a plan at all")).toThrow(/Unsupported/);
+    it("matches the previous sniffing behaviour", async () => {
+      expect(await detectFormat(POSTGRES_JSON)).toBe("postgres-json");
+      expect(await detectFormat(POSTGRES_TEXT)).toBe("postgres-text");
+      expect(await detectFormatFor(POSTGRES_JSON, null)).toBe(await detectFormat(POSTGRES_JSON));
+      await expect(detectFormat("not a plan at all")).rejects.toThrow(/Unsupported/);
     });
 
-    it("agrees with sniffing when a postgres hint is given", () => {
+    it("agrees with sniffing when a postgres hint is given", async () => {
       for (const raw of [POSTGRES_JSON, POSTGRES_TEXT]) {
-        expect(detectFormatFor(raw, "postgres")).toBe(detectFormat(raw));
+        expect(await detectFormatFor(raw, "postgres")).toBe(await detectFormat(raw));
       }
-      const plan = parseExplainFor(POSTGRES_JSON, "postgres");
+      const plan = await parseExplainFor(POSTGRES_JSON, "postgres");
       expect(plan.driver).toBe("postgres");
     });
   });
 
   describe("edges", () => {
-    it("reports that sqlite has no text form", () => {
-      expect(() => parseExplainFor("SCAN users", "sqlite")).toThrow(
+    it("reports that sqlite has no text form", async () => {
+      await expect(parseExplainFor("SCAN users", "sqlite")).rejects.toThrow(
         /buildSqliteTree/,
       );
     });
 
-    it("rejects empty input for every engine", () => {
-      expect(() => parseExplainFor("", null)).toThrow();
-      expect(() => parseExplainFor("", "postgres")).toThrow();
-      expect(() => parseExplainFor("   \n ", "mysql")).toThrow();
+    it("rejects empty input for every engine", async () => {
+      await expect(parseExplainFor("", null)).rejects.toThrow();
+      await expect(parseExplainFor("", "postgres")).rejects.toThrow();
+      await expect(parseExplainFor("   \n ", "mysql")).rejects.toThrow();
     });
 
-    it("reports MySQL JSON missing its query_block", () => {
-      expect(() => parseExplainFor('{"not_a_block": 1}', "mysql")).toThrow(
+    it("reports MySQL JSON missing its query_block", async () => {
+      await expect(parseExplainFor('{"not_a_block": 1}', "mysql")).rejects.toThrow(
         /query_block/,
       );
     });
@@ -127,15 +127,15 @@ describe("source dispatch", () => {
   });
 
   describe("withSourceLabel", () => {
-    it("labels a plan with an empty original query", () => {
-      const plan = parseExplainFor(POSTGRES_JSON, "postgres");
+    it("labels a plan with an empty original query", async () => {
+      const plan = await parseExplainFor(POSTGRES_JSON, "postgres");
       const labelled = withSourceLabel(plan, "plan.json");
       expect(labelled.original_query).toBe("-- loaded from plan.json");
     });
 
-    it("leaves a stamped original query alone", () => {
+    it("leaves a stamped original query alone", async () => {
       const plan = {
-        ...parseExplainFor(POSTGRES_JSON, "postgres"),
+        ...(await parseExplainFor(POSTGRES_JSON, "postgres")),
         original_query: "SELECT 1",
       };
       expect(withSourceLabel(plan, "plan.json").original_query).toBe("SELECT 1");