@drift-beacon/plugin 0.1.0

package/dist/vite.js

@@ -0,0 +1,370 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * `driftBeacon()` (`@drift-beacon/plugin/vite`): the Vite plugin of a plugin package. The UI is the author's
+ * own Vite app rooted at `ui/`; this plugin builds main next to it, so `dist/` is exactly the release package.
+ *
+ * `vite build` builds main once the UI is written. `vite` (`pnpm dev`) serves the UI with HMR, watch-builds main
+ * into `dist/` and keeps the manifest, the icon and the config types in sync. It writes a marker (dev.ts) that
+ * the Drift Beacon server polls; the server then connects to Vite's HMR socket and sends lines to print here.
+ *
+ * Through `link:`, a bare `vite` import from here would resolve to Cartridge's copy, whose types never match
+ * another copy's. So vite is only a type here: at run time the plugin loads the project's own vite, and the
+ * public signature names no vite type.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { stripVTControlCharacters, styleText } from "node:util";
+import { DEV_MARKER } from "./dev.js";
+import { PACKAGE_JSON } from "./internal/package-layout.js";
+import { prepare } from "./prepare.js";
+/** How long `pnpm dev` waits for a Drift Beacon server before saying how to connect one. */
+const HINT_DELAY_MS = 5_000;
+/**
+ * The Vite plugin for a Drift Beacon plugin package: `plugins: [driftBeacon()]`. It owns `root`, `base` and
+ * `build.outDir`. Typed as `{ name: string }` so it fits any Vite version's `plugins`.
+ */
+export function driftBeacon() {
+    let pkg = "";
+    let dist = "";
+    let manifest;
+    let manifestBytes;
+    const plugin = {
+        name: "drift-beacon",
+        config(config, env) {
+            if (env.isPreview)
+                return;
+            pkg = path.resolve(config.root ?? process.cwd());
+            // Read, not assumed: `dbplugin pack` redirects the whole build into a temp folder through `build.outDir`.
+            dist = config.build?.outDir ? path.resolve(pkg, config.build.outDir) : path.join(pkg, "dist");
+            for (const file of ["ui/index.html", "main/src/index.ts"]) {
+                if (!existsSync(path.join(pkg, file)))
+                    throw new Error(`driftBeacon(): ${file} not found in ${pkg}`);
+            }
+            const hmr = config.server?.hmr;
+            if (typeof hmr === "object" && (hmr.port !== undefined || hmr.path !== undefined)) {
+                throw new Error("driftBeacon(): a custom server.hmr port or path is not supported");
+            }
+            ({ manifest, bytes: manifestBytes } = prepare(pkg, { strict: true }));
+            // `dist/ui` is outside the root `ui/`, so Vite only empties it when asked to.
+            return { root: path.join(pkg, "ui"), base: "./", build: { outDir: path.join(dist, "ui"), emptyOutDir: true } };
+        },
+        // `vite` (`pnpm dev`). A Vite restart creates the new server before closing the old one: both share the state.
+        configureServer(server) {
+            serveDev(server, devStates.get(pkg) ?? startDev(pkg, dist, manifest, manifestBytes, server.config.logger));
+        },
+        // `vite build` (and `dbplugin pack`). Runs after the UI is written (and Vite has copied `ui/public/` into `dist/ui/`).
+        async writeBundle() {
+            const vite = await loadVite(pkg);
+            await vite.build(mainBuild(vite, pkg, { outDir: path.join(dist, "main"), minify: true, sourcemap: false, logLevel: "warn" }));
+            writeAtomic(path.join(dist, "manifest.json"), manifestBytes);
+            writeAtomic(path.join(dist, "package.json"), `${JSON.stringify(PACKAGE_JSON, null, 2)}\n`);
+            writeMarker(dist, { pluginId: manifest.id, session: null, uiUrl: null });
+        },
+    };
+    return plugin;
+}
+/** The project's own vite: through `link:`, a bare import would resolve to the SDK's copy. */
+const loadVite = async (pkg) => import(__rewriteRelativeImportExtension(pathToFileURL(createRequire(path.join(pkg, "package.json")).resolve("vite")).href));
+/** Main as one ESM file, with every dependency bundled except the SDK, which the plugin host supplies. */
+function mainBuild(vite, pkg, options) {
+    // One file on both Vite 7 (Rollup) and Vite 8 (Rolldown, which deprecates `inlineDynamicImports`).
+    const single = "rolldownVersion" in vite ? { codeSplitting: false } : { inlineDynamicImports: true };
+    return {
+        configFile: false,
+        root: pkg,
+        // Vite copies publicDir in every build: a stray `<pkg>/public/` must not reach `dist/main/`.
+        publicDir: false,
+        logLevel: options.logLevel,
+        build: {
+            ssr: "main/src/index.ts",
+            outDir: options.outDir,
+            target: "node24",
+            emptyOutDir: true,
+            minify: options.minify,
+            sourcemap: options.sourcemap,
+            watch: options.watch ?? null,
+            rollupOptions: {
+                external: ["@drift-beacon/plugin"],
+                output: { format: "es", entryFileNames: "index.js", ...single },
+            },
+        },
+        ssr: { noExternal: true },
+    };
+}
+// On globalThis, so the state survives whatever reloads this module; keyed by package root, so one process
+// (a test file) can serve several roots.
+const DEV_STATES = Symbol.for("drift-beacon.dev");
+const shared = globalThis;
+shared[DEV_STATES] ??= new Map();
+const devStates = shared[DEV_STATES];
+/** Once per root: seed `dist/` and start the main watch build. */
+function startDev(pkg, dist, manifest, bytes, logger) {
+    writeAtomic(path.join(dist, "manifest.json"), bytes);
+    writeAtomic(path.join(dist, "package.json"), `${JSON.stringify(PACKAGE_JSON, null, 2)}\n`);
+    const state = {
+        pkg,
+        dist,
+        session: randomUUID(),
+        manifest,
+        manifestBytes: bytes,
+        watcher: Promise.resolve(undefined),
+        buildId: hashDist(dist),
+        uiUrl: null,
+        socket: null,
+        hint: undefined,
+        logger,
+        servers: 0,
+    };
+    devStates.set(pkg, state);
+    syncIcon(state, true);
+    state.watcher = watchMain(state).catch((error) => {
+        print(state.logger, { level: "error", text: `✗ Could not start the main build: ${shorten(state, error.message)}` });
+        return undefined;
+    });
+    return state;
+}
+/**
+ * Builds main into `.drift-beacon/main-next/` on every save, then moves the files into `dist/main/`: never a
+ * half-written bundle in `dist/`, and at the same depth, so the map's relative sources still resolve.
+ */
+async function watchMain(state) {
+    const vite = await loadVite(state.pkg);
+    const staging = path.join(state.pkg, ".drift-beacon/main-next");
+    const options = { outDir: staging, minify: false, sourcemap: true, watch: {}, logLevel: "silent" };
+    const watcher = (await vite.build(mainBuild(vite, state.pkg, options)));
+    // Vite closes each event's bundle itself.
+    watcher.on("event", (event) => {
+        if (event.code === "BUNDLE_END") {
+            try {
+                moveFiles(staging, path.join(state.dist, "main"));
+                const changed = writeDevMarker(state);
+                print(state.logger, {
+                    level: "info",
+                    text: `main built in ${event.duration} ms${changed ? "" : " · no changes"}`,
+                });
+            }
+            catch (error) {
+                print(state.logger, { level: "error", text: `✗ Could not update dist/main: ${error.message}` });
+            }
+        }
+        else if (event.code === "ERROR") {
+            // dist/ is untouched, so the server keeps the last good build.
+            const reason = shorten(state, event.error.message).replaceAll(/\n\s*\n/g, "\n");
+            print(state.logger, {
+                level: "error",
+                text: `✗ main build failed: ${reason}\nThe runtime keeps running the last good build.`,
+            });
+        }
+    });
+    return watcher;
+}
+/** Per dev server: the manifest and icon watchers, the marker, and the server's socket. */
+function serveDev(server, state) {
+    state.servers += 1;
+    state.logger = server.config.logger;
+    const manifestFile = path.join(state.pkg, "manifest.json");
+    server.watcher.add(manifestFile);
+    // Vite already watches its root `ui/`, so the icon's changes arrive here too.
+    server.watcher.on("all", (event, file) => {
+        if (file === manifestFile && event !== "unlink")
+            updateManifest(state);
+        else if (state.manifest.icon && file === path.join(state.pkg, "ui/public", state.manifest.icon))
+            syncIcon(state, false);
+    });
+    server.httpServer?.on("listening", () => {
+        state.uiUrl = server.resolvedUrls?.local[0] ?? null;
+        // Even before main has built: the server can connect and serve the UI meanwhile.
+        writeDevMarker(state);
+        clearTimeout(state.hint);
+        state.hint = setTimeout(() => {
+            if (!state.socket)
+                print(state.logger, { level: "warn", text: noServerHint(state) });
+        }, HINT_DELAY_MS).unref();
+    });
+    // On the dev server's own close: its http server emits "close" only if it listened, and has none in middleware mode.
+    const close = server.close.bind(server);
+    let open = true;
+    server.close = () => {
+        if (open) {
+            open = false;
+            release(state);
+        }
+        return close();
+    };
+    // Vite custom events over the HMR socket. Never `server.ws.send`: it broadcasts, plugin iframes included.
+    server.ws.on("drift-beacon:hello", (data, client) => {
+        if (data?.session !== state.session)
+            return;
+        const welcome = { v: 1, session: state.session, pluginId: state.manifest.id };
+        client.send("drift-beacon:welcome", welcome); // this socket only
+        clearTimeout(state.hint);
+        const { socket } = client;
+        state.socket = socket;
+        socket.once("close", () => {
+            if (state.socket !== socket)
+                return;
+            state.socket = null;
+            print(state.logger, { level: "warn", text: "! Drift Beacon server disconnected; waiting for it…" });
+        });
+    });
+    server.ws.on("drift-beacon:print", (data, client) => {
+        if (client.socket === state.socket)
+            print(state.logger, data);
+    });
+}
+/** One dev server closed: the last one for the root stops the main watch build and forgets the root. */
+function release(state) {
+    if (--state.servers > 0)
+        return;
+    clearTimeout(state.hint);
+    if (devStates.get(state.pkg) === state)
+        devStates.delete(state.pkg);
+    void state.watcher.then((watcher) => watcher?.close());
+}
+/** A saved manifest: checked, copied, and its config types and icon refreshed. An invalid one keeps the old copy. */
+function updateManifest(state) {
+    try {
+        const { manifest, bytes } = prepare(state.pkg, { strict: true });
+        // A missing icon was already reported under its name; say it again only for a new name.
+        const renamed = manifest.icon !== state.manifest.icon;
+        state.manifest = manifest;
+        state.manifestBytes = bytes;
+        syncIcon(state, renamed);
+        // Copies the manifest.
+        writeDevMarker(state);
+    }
+    catch (error) {
+        print(state.logger, {
+            level: "error",
+            text: `✗ ${shorten(state, error.message)}\nDrift Beacon keeps the last valid manifest.`,
+        });
+    }
+}
+/** Copies the manifest icon from `ui/public/` into `dist/ui/` (Vite does it in a build), or removes a deleted one. */
+function syncIcon(state, warnMissing) {
+    const { icon } = state.manifest;
+    if (!icon)
+        return;
+    const source = path.join(state.pkg, "ui/public", icon);
+    const target = path.join(state.dist, "ui", icon);
+    try {
+        if (existsSync(source)) {
+            writeAtomic(target, readFileSync(source));
+            return;
+        }
+        rmSync(target, { force: true });
+    }
+    catch (error) {
+        print(state.logger, { level: "error", text: `✗ Could not copy the icon: ${error.message}` });
+        return;
+    }
+    if (warnMissing) {
+        print(state.logger, {
+            level: "warn",
+            text: `! manifest.json names icon ${icon}, but ui/public/${icon} is missing`,
+        });
+    }
+}
+/** Moves every staged file into `to`, maps first and `index.js` last, so the new index.js never meets an old map. */
+function moveFiles(from, to) {
+    const rank = (file) => (file === "index.js" ? 2 : file.endsWith(".map") ? 0 : 1);
+    const files = readdirSync(from, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => path.relative(from, path.join(entry.parentPath, entry.name)))
+        .sort((a, b) => rank(a) - rank(b));
+    for (const file of files) {
+        mkdirSync(path.dirname(path.join(to, file)), { recursive: true });
+        renameSync(path.join(from, file), path.join(to, file));
+    }
+}
+/**
+ * Writes the dev marker for what is in `dist/` now; true when its build id changed. The manifest, `package.json`
+ * and a missing icon are written first, so a `dist/` deleted while `pnpm dev` runs is whole again.
+ */
+function writeDevMarker(state) {
+    writeAtomic(path.join(state.dist, "manifest.json"), state.manifestBytes);
+    writeAtomic(path.join(state.dist, "package.json"), `${JSON.stringify(PACKAGE_JSON, null, 2)}\n`);
+    const { icon } = state.manifest;
+    if (icon && !existsSync(path.join(state.dist, "ui", icon)))
+        syncIcon(state, false);
+    const buildId = writeMarker(state.dist, { pluginId: state.manifest.id, session: state.session, uiUrl: state.uiUrl });
+    const changed = buildId !== state.buildId;
+    state.buildId = buildId;
+    return changed;
+}
+const noServerHint = (state) => [
+    `! No Drift Beacon server has connected after ${HINT_DELAY_MS / 1000} s.`,
+    `The server connects when it finds dist/${DEV_MARKER} in a folder directly`,
+    `under its DEV_PLUGINS_PATH. Run it in development mode with DEV_PLUGINS_PATH=${path.dirname(state.pkg)}`,
+].join("\n");
+/** Plain text with package paths made relative, for messages that come from Vite or the file system. */
+const shorten = (state, text) => stripVTControlCharacters(text).replaceAll(`${state.pkg}${path.sep}`, "").trim();
+const TIME = new Intl.DateTimeFormat(undefined, { hour: "numeric", minute: "numeric", second: "numeric" });
+const STYLES = {
+    info: [],
+    success: "green",
+    warn: "yellow",
+    error: "red",
+};
+/**
+ * Prints a line (from the server, or about the local build) through Vite's logger, timed like Vite's own lines
+ * but tagged `[beacon]` (Vite's `timestamp` option would tag it `[vite]`). The first line is coloured by level;
+ * the others are dimmed and indented under it.
+ */
+function print(logger, { level, text }) {
+    const time = TIME.format(new Date());
+    const [first = "", ...rest] = String(text).split("\n");
+    const indent = " ".repeat(`${time} [beacon] `.length);
+    const message = [
+        `${styleText("dim", time)} ${styleText(["bold", "cyan"], "[beacon]")} ${styleText(STYLES[level] ?? [], first)}`,
+        ...rest.map((line) => styleText("dim", indent + line)),
+    ].join("\n");
+    if (level === "error")
+        logger.error(message);
+    else if (level === "warn")
+        logger.warn(message);
+    else
+        logger.info(message);
+}
+// ============================================================================
+// Shared
+// ============================================================================
+/** Writes the marker for what is in `dist/` now and returns its build id. */
+function writeMarker(dist, { pluginId, session, uiUrl }) {
+    const buildId = hashDist(dist);
+    // The HMR socket shares the UI's host and port; a relative base serves it at `/`.
+    const marker = { v: 1, pluginId, buildId, session, uiUrl, wsUrl: uiUrl?.replace(/^http/, "ws") ?? null };
+    writeAtomic(path.join(dist, DEV_MARKER), `${JSON.stringify(marker, null, 2)}\n`);
+    return buildId;
+}
+/**
+ * The build id: sha256 of what the server loads, first 16 hex characters. Null until main is built. It
+ * covers `ui/index.html` so a UI-only build still refreshes an open static UI.
+ */
+function hashDist(dist) {
+    if (!existsSync(path.join(dist, "main/index.js")))
+        return null;
+    const hash = createHash("sha256");
+    for (const name of ["manifest.json", "main/index.js", "main/index.js.map", "ui/index.html"]) {
+        const file = path.join(dist, name);
+        if (existsSync(file))
+            hash.update(`${name}\0`).update(readFileSync(file));
+    }
+    return hash.digest("hex").slice(0, 16);
+}
+/** Writes through a temporary file and a rename, so the server never reads a partial file. */
+function writeAtomic(file, content) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(`${file}.tmp`, content);
+    renameSync(`${file}.tmp`, file);
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@drift-beacon/plugin",
+  "version": "0.1.0",
+  "description": "The Drift Beacon plugin SDK: APIs for plugin main code and UIs, the driftBeacon() Vite plugin and the dbplugin CLI",
+  "license": "MIT",
+  "author": {
+    "name": "Drift Beacon",
+    "url": "https://driftbeacon.app"
+  },
+  "homepage": "https://driftbeacon.app",
+  "keywords": [
+    "drift-beacon",
+    "plugin",
+    "sdk",
+    "vite-plugin"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "default": "./dist/ui.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "dbplugin": "bin/dbplugin.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "fflate": "^0.8.3"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.9",
+    "vite": "^7.1.2 || ^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "26.6.2",
+    "typescript": "6.0.3",
+    "vite": "7.1.2"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit && node scripts/api-report.mjs --check",
+    "api:update": "node scripts/api-report.mjs"
+  }
+}