@gjsify/vite-plugin-blueprint 0.35.0 → 0.36.0

package/lib/index.d.ts

@@ -3,4 +3,5 @@ export interface BlueprintPluginOptions {
     minify?: boolean;
     verbose?: boolean;
 }
+export { resolveBlueprintCompiler, formatMissingBlueprintCompiler } from './resolve-compiler.js';
 export default function blueprintPlugin(options?: BlueprintPluginOptions): Plugin;

package/lib/index.js

@@ -1,16 +1,29 @@
 import { execa } from 'execa';
 import minifyXML from 'minify-xml';
+import { formatMissingBlueprintCompiler, resolveBlueprintCompiler } from './resolve-compiler.js';
+export { resolveBlueprintCompiler, formatMissingBlueprintCompiler } from './resolve-compiler.js';
 export default function blueprintPlugin(options = {}) {
     const { minify = false, verbose = false } = options;
     return {
         name: 'vite-plugin-blueprint',
         async load(id) {
             if (id.endsWith('.blp')) {
+                // Resolved per load rather than once at plugin construction, so a
+                // compiler installed mid-watch is picked up without a restart —
+                // and so the "missing" diagnostic names the .blp that wanted it.
+                const compiler = resolveBlueprintCompiler();
+                if (!compiler) {
+                    throw new Error(`${id}: ${formatMissingBlueprintCompiler()}`);
+                }
                 try {
                     // Compile .blp file and get XML output directly
-                    const { stdout } = await execa('blueprint-compiler', ['compile', id]);
+                    const { stdout } = await execa(compiler.file, [...compiler.prefixArgs, 'compile', id], {
+                        // Only ever an overlay (an MSYS2 PATH prepend); undefined
+                        // inherits the environment unchanged.
+                        env: compiler.env,
+                    });
                     if (verbose)
-                        console.log(`Compiled ${id}`);
+                        console.log(`Compiled ${id} (blueprint-compiler via ${compiler.source})`);
                     let xmlContent = stdout;
                     // Minify XML if option is enabled
                     if (minify) {
@@ -22,8 +35,12 @@ export default function blueprintPlugin(options = {}) {
                     return `export default ${JSON.stringify(xmlContent)};`;
                 }
                 catch (error) {
-                    console.error(`Error processing ${id}:`, error);
-                    throw error;
+                    // The compiler EXISTS and refused the file, so this is a
+                    // blueprint syntax/type error and its own stderr is the
+                    // useful part — surface that, not an install hint the reader
+                    // has already satisfied.
+                    const detail = error instanceof Error ? error.stderr || error.message : String(error);
+                    throw new Error(`${id}: blueprint-compiler failed (${compiler.file})\n${detail}`);
                 }
             }
         },

package/lib/resolve-compiler.d.ts

@@ -0,0 +1,27 @@
+/** A spawnable blueprint-compiler, plus how it was found (for `verbose`). */
+export interface ResolvedBlueprintCompiler {
+    /** The executable to spawn. */
+    file: string;
+    /** Arguments that must precede blueprint-compiler's own (e.g. the script path). */
+    prefixArgs: string[];
+    /** Environment overlay to spawn with, or undefined to inherit unchanged. */
+    env?: Record<string, string>;
+    source: 'env' | 'path' | 'msys2';
+}
+/**
+ * Locate a usable blueprint-compiler, or null when there is none.
+ *
+ * Order: `BLUEPRINT_COMPILER` (an explicit answer always wins, and is the escape
+ * hatch for an install none of the probes below know about) → `PATH` → an MSYS2
+ * install on win32.
+ */
+export declare function resolveBlueprintCompiler(): ResolvedBlueprintCompiler | null;
+/**
+ * What to tell someone who has no blueprint-compiler.
+ *
+ * Names the install command for THIS platform rather than listing every one:
+ * the reader is on one host and the other two lines are noise they have to
+ * filter. `BLUEPRINT_COMPILER` is mentioned everywhere because it is the answer
+ * for any install the probes miss.
+ */
+export declare function formatMissingBlueprintCompiler(): string;

package/lib/resolve-compiler.js

@@ -0,0 +1,145 @@
+// Where is `blueprint-compiler`, and what do we say when it is nowhere?
+//
+// Split out of the plugin so it is answerable in a test without a compiler
+// installed, and because the answer is genuinely platform-shaped on Windows.
+//
+// The failure this replaces: the plugin called `execa('blueprint-compiler', …)`
+// and rethrew whatever came back, so a host without it got an ExecaError stack
+// naming the COMMAND THAT FAILED and nothing about what to install. Measured on
+// the win11-gjsify VM, that error was read as "blueprint-compiler is a GNOME
+// Python tool, so it is unavailable on Windows" — a conclusion that reached a
+// docs file and stopped anyone building a `.blp` showcase there for a day. It is
+// available; nothing said how to get it.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * MSYS2 install roots to probe on win32, in order.
+ *
+ * MSYS2 is the ONLY way to get blueprint-compiler onto Windows today, and not
+ * for the reason the tool's Python-ness suggests: it is pure Python (PyPI ships
+ * a `py3-none-any` wheel), but `blueprintcompiler/gir.py` reads TYPELIBS through
+ * `GIRepository`, so it needs PyGObject — which publishes no Windows wheel, so
+ * `pip install blueprint-compiler` dies building it from source. MSYS2 is where
+ * Python, PyGObject and the typelibs arrive already fitted together.
+ *
+ * `C:\msys64` is the installer default; the `$USERPROFILE` entries cover the
+ * extracted-archive install, which is what a host without admin rights gets;
+ * `C:\tools\msys64` is Chocolatey's.
+ */
+const MSYS2_ROOTS = [
+    process.env.MSYS2_ROOT,
+    'C:\\msys64',
+    process.env.USERPROFILE && join(process.env.USERPROFILE, 'msys64'),
+    process.env.USERPROFILE && join(process.env.USERPROFILE, 'Tools', 'msys64'),
+    'C:\\tools\\msys64',
+].filter((root) => typeof root === 'string' && root.length > 0);
+/**
+ * MSYS2 environments, most-preferred first. `ucrt64` is MSYS2's own default for
+ * new installs and links the modern Universal CRT; the others are probed so an
+ * existing install is not rejected for being older.
+ */
+const MSYS2_ENVS = ['ucrt64', 'mingw64', 'clang64'];
+/** Executable suffixes to try for a bare command name. Windows needs them; POSIX does not. */
+const EXE_SUFFIXES = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+/** First existing `<dir>/<cmd><suffix>`, or null. */
+function findOnPath(cmd) {
+    const pathVar = process.env.PATH;
+    if (!pathVar)
+        return null;
+    const sep = process.platform === 'win32' ? ';' : ':';
+    for (const dir of pathVar.split(sep)) {
+        if (!dir)
+            continue;
+        for (const suffix of EXE_SUFFIXES) {
+            const candidate = join(dir, cmd + suffix);
+            try {
+                if (existsSync(candidate))
+                    return candidate;
+            }
+            catch {
+                // An unreadable PATH entry is not an answer about `cmd`.
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Find an MSYS2-provided blueprint-compiler.
+ *
+ * MSYS2 installs it as a SHEBANG SCRIPT with no `.exe` beside it, which Windows
+ * cannot execute — so this returns MSYS2's own `python.exe` with the script as
+ * its first argument, rather than the script alone. `<env>/bin` is prepended to
+ * PATH because the script imports PyGObject, which loads MSYS2's libglib and its
+ * typelibs from there.
+ *
+ * Deliberately does NOT set `GI_TYPELIB_PATH` at the gjsify GTK runtime bundle:
+ * those typelibs are gvsbuild's and name `glib-2.0-0.dll` in their
+ * `shared_library` field while MSYS2 ships `libglib-2.0-0.dll`. Measured — it
+ * fails with "Failed to load shared library", and the obvious repair (put both
+ * on PATH) would load two GLib builds into one process, which is a worse problem
+ * than the one it solves.
+ */
+function findInMsys2() {
+    if (process.platform !== 'win32')
+        return null;
+    for (const root of MSYS2_ROOTS) {
+        for (const env of MSYS2_ENVS) {
+            const bin = join(root, env, 'bin');
+            const script = join(bin, 'blueprint-compiler');
+            const python = join(bin, 'python.exe');
+            try {
+                if (!existsSync(script) || !existsSync(python))
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            return {
+                file: python,
+                prefixArgs: [script],
+                env: { PATH: `${bin};${process.env.PATH ?? ''}` },
+                source: 'msys2',
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Locate a usable blueprint-compiler, or null when there is none.
+ *
+ * Order: `BLUEPRINT_COMPILER` (an explicit answer always wins, and is the escape
+ * hatch for an install none of the probes below know about) → `PATH` → an MSYS2
+ * install on win32.
+ */
+export function resolveBlueprintCompiler() {
+    const override = process.env.BLUEPRINT_COMPILER;
+    if (override) {
+        return { file: override, prefixArgs: [], source: 'env' };
+    }
+    const onPath = findOnPath('blueprint-compiler');
+    if (onPath) {
+        return { file: onPath, prefixArgs: [], source: 'path' };
+    }
+    return findInMsys2();
+}
+/**
+ * What to tell someone who has no blueprint-compiler.
+ *
+ * Names the install command for THIS platform rather than listing every one:
+ * the reader is on one host and the other two lines are noise they have to
+ * filter. `BLUEPRINT_COMPILER` is mentioned everywhere because it is the answer
+ * for any install the probes miss.
+ */
+export function formatMissingBlueprintCompiler() {
+    const install = process.platform === 'win32'
+        ? 'MSYS2 packages it prebuilt (it needs PyGObject, which has no Windows wheel, so pip cannot):\n' +
+            '    pacman -S mingw-w64-ucrt-x86_64-blueprint-compiler mingw-w64-ucrt-x86_64-gtk4 mingw-w64-ucrt-x86_64-libadwaita\n' +
+            '  An MSYS2 install under C:\\msys64, %USERPROFILE%\\msys64, %USERPROFILE%\\Tools\\msys64 or\n' +
+            '  C:\\tools\\msys64 is found automatically — it does NOT need to be on PATH.'
+        : process.platform === 'darwin'
+            ? 'brew install blueprint-compiler'
+            : 'sudo dnf install blueprint-compiler   (Debian/Ubuntu: sudo apt install blueprint-compiler)';
+    return ('blueprint-compiler was not found, so a .blp template cannot be compiled.\n' +
+        `  ${install}\n` +
+        '  Or set BLUEPRINT_COMPILER to its full path.');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/vite-plugin-blueprint",
-    "version": "0.35.0",
+    "version": "0.36.0",
     "description": "Compile GNOME Blueprint .blp templates to XML strings via blueprint-compiler. Vite / Rollup / Rolldown compatible.",
     "type": "module",
     "main": "lib/index.js",
@@ -11,6 +11,10 @@
             "types": "./lib/index.d.ts",
             "default": "./lib/index.js"
         },
+        "./resolve": {
+            "types": "./lib/resolve-compiler.d.ts",
+            "default": "./lib/resolve-compiler.js"
+        },
         "./types": {
             "types": "./types/blueprint.d.ts"
         }
@@ -64,6 +68,11 @@
         "vite": "^8.1.3"
     },
     "gjsify": {
-        "tier": 1
+        "tier": 1,
+        "os": {
+            "linux": "supported",
+            "darwin": "supported",
+            "win32": "supported"
+        }
     }
 }