Files
worldwideview/scripts/sync-local-plugins.mjs
T
Silvertakana 8f58c26e27 fix(sync): inline process.env, inlineDynamicImports, and CSS copy for local plugins (#201)
* fix(sync): add process.env replacement, inlineDynamicImports, and CSS copy to syncToPublic

- Inline replace-process-env Rollup plugin transforms process.env.NODE_ENV to "production"
  to prevent ReferenceError in browser bundles that lack a Node.js environment
- Switch codeSplitting to inlineDynamicImports: true so the build produces a single
  self-contained ES module with no bare chunk specifiers that the browser cannot resolve
- Add rollup-plugin-external-globals to remap shared host deps (react, cesium, zustand, SDK)
  to globalThis.__WWV_HOST__.* at bundle time
- syncToPublic now copies any .css files emitted alongside the .mjs bundle (e.g. from
  gridstack or other CSS-importing libs) into public/plugins-local/<id>/

* docs(plugin): add bundle footguns -- CSP/CSS, inlineDynamicImports, process.env, CORS
2026-05-29 10:46:04 +12:00

412 lines
15 KiB
JavaScript

/**
* @file sync-local-plugins.mjs
* @description Local plugin synchronization and build utility.
* Scans `local-plugins/`, compiles bundles using Vite, and hydrates the
* `public/plugins-local/` directory for the Next.js dev server.
* @module scripts
*/
import fs from "fs";
import os from "os";
import path from "path";
import { build } from "vite";
import { fileURLToPath } from "url";
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const ROOT = path.resolve(__dirname, "..");
const LOCAL_PLUGINS_DIR = path.join(ROOT, "local-plugins");
const OUTPUT_DIR = path.join(ROOT, "public", "plugins-local");
// External globals — must match extract-plugins.mjs pattern
const EXTERNAL_GLOBALS = {
"react": "globalThis.__WWV_HOST__.React",
"react-dom": "globalThis.__WWV_HOST__.ReactDOM",
"react/jsx-runtime": "globalThis.__WWV_HOST__.jsxRuntime",
"@worldwideview/wwv-plugin-sdk": "globalThis.__WWV_HOST__.WWVPluginSDK",
"cesium": "globalThis.__WWV_HOST__.Cesium",
"resium": "globalThis.__WWV_HOST__.Resium",
};
/**
* Synthetic host-module exports for `@/` imports that plugins use to access
* the host application's runtime objects (store, plugin manager, components).
*
* When a plugin sub-component does `import { useStore } from "@/core/state/store"`,
* the tsconfig `@/*` alias (inherited from the main app root tsconfig) would normally
* resolve that to the actual `src/core/state/store.ts` file — pulling the entire Zustand
* store (and its transitive deps like `src/core/edition.ts`) into the bundle.
* This plugin intercepts those imports at the resolveId stage, before Vite touches
* the filesystem, and substitutes a synthetic module that reads from the host globals
* injected at runtime by `hostGlobals.ts`.
*/
const HOST_MODULE_SYNTHETICS = {
"@/core/state/store": `export const useStore = globalThis.__WWV_HOST__.useStore;`,
"@/core/plugins/PluginManager": `export const pluginManager = globalThis.__WWV_HOST__.pluginManager;`,
"@/components/video/CameraStream": `export const CameraStream = globalThis.__WWV_HOST__.CameraStream;`,
"zustand": `
const zustand = globalThis.__WWV_HOST__.zustand || {};
export default zustand;
export const { create, createStore } = zustand;
`,
};
/**
* @function wwvHostRedirectPlugin
* @description Vite plugin that intercepts host-app module imports (`@/core/...`,
* `@/components/...`) in local plugin builds and redirects them to the runtime
* host globals instead of bundling the full app source tree.
*
* @returns {import('vite').Plugin}
*/
function wwvHostRedirectPlugin() {
return {
name: "wwv-host-redirect",
enforce: "pre",
resolveId(id) {
if (id in HOST_MODULE_SYNTHETICS) return `\0${id}`;
return null;
},
load(id) {
if (!id.startsWith("\0")) return null;
const originalId = id.slice(1);
return HOST_MODULE_SYNTHETICS[originalId] ?? null;
},
};
}
/**
* @function readJsonFile
* @description Reads a UTF-8 JSON file, tolerating a leading BOM (U+FEFF).
* Node's `fs.readFileSync(p, 'utf-8')` preserves the BOM byte, which `JSON.parse`
* then rejects with "Unexpected token". Scaffolders and editors on Windows
* occasionally emit BOMs into `package.json`; pnpm/npm strip them silently,
* so we match that behavior here to avoid breaking dev on otherwise-valid files.
* @param {string} filePath
* @returns {any}
*/
function readJsonFile(filePath) {
let text = fs.readFileSync(filePath, "utf-8");
if (text.charCodeAt(0) === 0xFEFF) text = text.slice(1);
return JSON.parse(text);
}
/**
* @function discoverLocalPlugins
* @description Finds all directories in `local-plugins/` that contain a valid
* `package.json` with a `worldwideview` manifest block.
* @returns {Array<{dir: string, manifest: any, pluginDir: string}>}
*/
export function discoverLocalPlugins() {
if (!fs.existsSync(LOCAL_PLUGINS_DIR)) return [];
return fs.readdirSync(LOCAL_PLUGINS_DIR)
.filter(dir => {
if (dir.startsWith(".")) return false;
const pkgPath = path.join(LOCAL_PLUGINS_DIR, dir, "package.json");
if (!fs.existsSync(pkgPath)) return false;
const pkg = readJsonFile(pkgPath);
return !!pkg.worldwideview;
})
.map(dir => {
const pkgPath = path.join(LOCAL_PLUGINS_DIR, dir, "package.json");
const pkg = readJsonFile(pkgPath);
const manifest = pkg.worldwideview;
manifest.version = pkg.version;
manifest.name = pkg.name;
manifest.description = pkg.description;
return { dir, manifest, pkg, pluginDir: path.join(LOCAL_PLUGINS_DIR, dir) };
});
}
/**
* @function resolvePluginEntry
* @description Resolves the TypeScript source entry file for a plugin.
*
* Resolution order:
* 1. `worldwideview.dev_entry` — explicit override in the manifest block
* 2. `pkg.types` — if it points to a .ts/.tsx source file (not a .d.ts declaration)
* 3. `pkg.source` — explicit source field (less common, but valid)
* 4. Heuristic fallback: src/index.ts → src/index.tsx → index.ts → index.tsx
*
* @param {string} pluginDir - Absolute path to the plugin directory.
* @param {any} manifest - The parsed `worldwideview` manifest block.
* @param {any} pkg - The full parsed package.json object.
* @returns {string|null} Absolute path to the entry file, or null if not found.
*/
function resolvePluginEntry(pluginDir, manifest, pkg) {
const candidates = [];
if (manifest.dev_entry) {
candidates.push(path.join(pluginDir, manifest.dev_entry));
}
// pkg.types points to the TS source in all WWV plugins (e.g. "src/index.ts")
if (pkg.types && !pkg.types.endsWith(".d.ts")) {
candidates.push(path.join(pluginDir, pkg.types));
}
if (pkg.source) {
candidates.push(path.join(pluginDir, pkg.source));
}
// Heuristic fallbacks
for (const rel of ["src/index.ts", "src/index.tsx", "index.ts", "index.tsx"]) {
candidates.push(path.join(pluginDir, rel));
}
return candidates.find(f => fs.existsSync(f)) ?? null;
}
const SKIP_DIRS = new Set(["dist", "node_modules", ".git", ".turbo", ".vite"]);
/**
* @function latestSourceMtime
* @description Walks a plugin directory and returns the newest mtime (ms) across
* source files. Used to decide whether a cached `dist/frontend.mjs` is still valid.
* Skips build/output dirs so this is fast even on cold disks.
* @param {string} rootDir
* @returns {number} newest mtime in ms, or 0 if no files found
*/
function latestSourceMtime(rootDir) {
let newest = 0;
/** @param {string} dir */
function walk(dir) {
let entries;
try {
entries = fs.readdirSync(dir, { withFileTypes: true });
} catch {
return;
}
for (const entry of entries) {
if (entry.name.startsWith(".") && entry.name !== ".env") continue;
if (SKIP_DIRS.has(entry.name)) continue;
const full = path.join(dir, entry.name);
if (entry.isDirectory()) {
walk(full);
} else if (entry.isFile()) {
const m = fs.statSync(full).mtimeMs;
if (m > newest) newest = m;
}
}
}
walk(rootDir);
return newest;
}
/**
* @function isBuildFresh
* @description Returns true if the plugin's existing `dist/frontend.mjs` is newer
* than every source file under its directory — meaning Vite would produce a
* byte-identical bundle and the build can be skipped.
* @param {string} pluginDir
* @returns {boolean}
*/
function isBuildFresh(pluginDir) {
const distFile = path.join(pluginDir, "dist", "frontend.mjs");
if (!fs.existsSync(distFile)) return false;
const distMtime = fs.statSync(distFile).mtimeMs;
const sourceMtime = latestSourceMtime(pluginDir);
return distMtime >= sourceMtime;
}
/**
* @function buildPlugin
* @description Invokes the Vite build engine to compile a plugin's source
* into a single ES module, externalizing shared host dependencies.
*
* Returns `"fresh"` if an up-to-date `dist/frontend.mjs` already exists (no build run),
* `true` if Vite produced a new bundle, or `false` on failure.
*/
export async function buildPlugin({ dir, manifest, pkg, pluginDir }) {
if (isBuildFresh(pluginDir)) {
return "fresh";
}
const entryFile = resolvePluginEntry(pluginDir, manifest, pkg ?? {});
if (!entryFile) {
console.warn(`[sync] ⚠ No entry file found for ${dir}, skipping`);
return false;
}
try {
await build({
root: pluginDir,
// Disable auto-loading the plugin's own vite.config.ts — the local
// plugins' node_modules may be symlinked to a different repo's SDK
// build (worktree scenario), which breaks config loading. The sync
// script provides all necessary config inline.
configFile: false,
logLevel: "warn",
plugins: [wwvHostRedirectPlugin()],
build: {
lib: {
entry: entryFile,
formats: ["es"],
fileName: () => "frontend.mjs",
},
outDir: "dist",
emptyOutDir: true,
rollupOptions: {
external: Object.keys(EXTERNAL_GLOBALS),
output: {
globals: EXTERNAL_GLOBALS,
inlineDynamicImports: true,
banner: '"use client";',
},
plugins: [
{
name: 'replace-process-env',
transform(code) {
if (!code.includes('process.env.NODE_ENV')) return null;
return {
code: code.replace(/process\.env\.NODE_ENV/g, '"production"'),
map: null,
};
},
},
(await import("rollup-plugin-external-globals")).default(EXTERNAL_GLOBALS),
],
onwarn(warning, warn) {
if (warning.code === 'MODULE_LEVEL_DIRECTIVE' && warning.message.includes('"use client"')) {
return;
}
if (warning.code === 'SOURCEMAP_ERROR') {
return;
}
warn(warning);
}
},
minify: false, // Keep readable for dev
sourcemap: true,
},
});
return true;
} catch (err) {
console.error(`[sync] ❌ Build failed for ${dir}:`, err.message);
return false;
}
}
export function syncToPublic({ dir, manifest, pluginDir }, { quiet = false } = {}) {
const publicName = manifest.id || dir.replace("wwv-plugin-", "");
const targetDir = path.join(OUTPUT_DIR, publicName);
const distFile = path.join(pluginDir, "dist", "frontend.mjs");
const distMap = path.join(pluginDir, "dist", "frontend.mjs.map");
if (!fs.existsSync(distFile)) {
console.warn(`[sync] ⚠ No dist for ${dir}, skipping sync`);
return;
}
fs.mkdirSync(targetDir, { recursive: true });
fs.copyFileSync(distFile, path.join(targetDir, "frontend.mjs"));
if (fs.existsSync(distMap)) {
fs.copyFileSync(distMap, path.join(targetDir, "frontend.mjs.map"));
}
// Copy any CSS files emitted alongside the bundle (e.g. from gridstack imports)
const distDir = path.join(pluginDir, "dist");
for (const f of fs.readdirSync(distDir)) {
if (f.endsWith(".css")) {
fs.copyFileSync(path.join(distDir, f), path.join(targetDir, f));
}
}
// Generate plugin.json manifest for the marketplace load route
const pluginJson = {
id: manifest.id || publicName,
name: manifest.name || publicName,
version: manifest.version || "0.0.0",
description: manifest.description || "",
type: manifest.type || "data-layer",
format: "bundle",
trust: "unverified",
capabilities: manifest.capabilities || ["data:own"],
category: manifest.category || "custom",
icon: manifest.icon || "Box",
entry: `/plugins-local/${publicName}/frontend.mjs`,
};
fs.writeFileSync(
path.join(targetDir, "plugin.json"),
JSON.stringify(pluginJson, null, 2)
);
if (!quiet) console.log(`[sync] ✅ ${publicName} → public/plugins-local/${publicName}/`);
}
// Clean stale plugins from public/plugins-local/ that no longer exist in local-plugins/
function cleanStale(activeIds) {
if (!fs.existsSync(OUTPUT_DIR)) return;
const activeSet = new Set(activeIds);
for (const dir of fs.readdirSync(OUTPUT_DIR)) {
if (!activeSet.has(dir)) {
fs.rmSync(path.join(OUTPUT_DIR, dir), { recursive: true, force: true });
console.log(`[sync] 🗑 Removed stale plugin: ${dir}`);
}
}
}
/**
* @function runWithConcurrency
* @description Runs an async worker over `items` with a fixed concurrency cap.
* Vite builds are CPU-bound; running all ~30 in parallel thrashes the scheduler
* and balloons RSS. A cap around half the logical cores keeps wall-clock low
* without starving the rest of the dev environment (Next.js, the data engine).
* @template T, R
* @param {T[]} items
* @param {number} concurrency
* @param {(item: T) => Promise<R>} worker
* @returns {Promise<R[]>}
*/
async function runWithConcurrency(items, concurrency, worker) {
const results = new Array(items.length);
let cursor = 0;
const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
while (true) {
const i = cursor++;
if (i >= items.length) return;
results[i] = await worker(items[i]);
}
});
await Promise.all(workers);
return results;
}
export async function syncAll() {
const plugins = discoverLocalPlugins();
if (plugins.length === 0) {
console.log("[sync] No local plugins found.");
cleanStale([]);
return;
}
const concurrency = Math.max(2, Math.min(plugins.length, Math.ceil(os.cpus().length / 2)));
console.log(`[sync] Found ${plugins.length} local plugin(s); building with concurrency=${concurrency}`);
const started = Date.now();
let freshCount = 0;
let builtCount = 0;
await runWithConcurrency(plugins, concurrency, async (plugin) => {
const result = await buildPlugin(plugin);
if (result === "fresh") freshCount++;
else if (result) builtCount++;
if (result) syncToPublic(plugin, { quiet: result === "fresh" });
});
console.log(`[sync] Done in ${((Date.now() - started) / 1000).toFixed(1)}s (${builtCount} built, ${freshCount} cached)`);
const activeIds = plugins.map(p => p.manifest.id || p.dir.replace("wwv-plugin-", ""));
cleanStale(activeIds);
}
// Run directly: node scripts/sync-local-plugins.mjs
const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
if (isDirectRun) {
syncAll().catch(err => {
console.error("[sync] Fatal:", err);
process.exit(1);
});
}