@gjsify/cli 0.3.14 → 0.3.16

package/lib/types/config-data.d.ts

@@ -1,5 +1,23 @@
-import type { RolldownOptions, OutputOptions } from 'rolldown';
+import type { RolldownOptions, OutputOptions, RolldownPluginOption } from 'rolldown';
 import type { ConfigDataLibrary, ConfigDataTypescript } from './index.js';
+/**
+ * Plugin entry resolvable by package name from the project's `node_modules`.
+ * Lets users describe the plugin chain in `package.json#gjsify` without
+ * dropping to a JS-form config file. The CLI imports the named module,
+ * picks the chosen export (defaults to `default`), and calls it with
+ * `options`.
+ *
+ * Example:
+ * ```jsonc
+ * { "name": "@gjsify/vite-plugin-blueprint", "options": { "minify": true } }
+ * { "name": "@gjsify/vite-plugin-gettext", "export": "msgfmtPlugin", "options": { ... } }
+ * ```
+ */
+export interface BundlerPluginByName {
+    name: string;
+    export?: string;
+    options?: unknown;
+}
 /**
  * Subset of `RolldownOptions` accepted in `.gjsifyrc.js`. Mirrors the legacy
  * `esbuild?: BuildOptions` field — a thin pass-through. The orchestrator
@@ -9,9 +27,14 @@ import type { ConfigDataLibrary, ConfigDataTypescript } from './index.js';
  * `output` is constrained to a single `OutputOptions` object (Rolldown also
  * accepts an array for multi-output builds, but the CLI surface targets the
  * single-output use case).
+ *
+ * `plugins` is widened to also accept `BundlerPluginByName` entries — these
+ * are resolved by the CLI from the project's `node_modules` before the
+ * Rolldown call.
  */
-export type BundlerOptions = Omit<RolldownOptions, 'output'> & {
+export type BundlerOptions = Omit<RolldownOptions, 'output' | 'plugins'> & {
     output?: OutputOptions;
+    plugins?: Array<RolldownPluginOption | BundlerPluginByName>;
 };
 /**
  * Legacy `esbuild?: BuildOptions` shape — kept as a compatibility shim for
@@ -68,9 +91,21 @@ export interface ConfigData {
      */
     globals?: string;
     /**
-     * Prepend GJS shebang to output and mark executable. See CliBuildOptions.
+     * Prepend a shebang to the output bundle and mark it executable.
+     *
+     *   `true`  → use the default `#!/usr/bin/env -S gjs -m` line
+     *   `false` → no shebang (default)
+     *   `"…"`   → custom line. Supports `${env:NAME}` and `${env:NAME:-default}`
+     *             placeholders against `process.env`. The leading `#!` is
+     *             added automatically if omitted. Useful when an outer
+     *             build tool (Meson, Flatpak) exports the GJS interpreter
+     *             path as `GJS_CONSOLE` (e.g. `/usr/bin/gjs-console`).
+     *
+     * Example: `"shebang": "${env:GJS_CONSOLE:-/usr/bin/env -S gjs} -m"`
+     *
+     * See also `CliBuildOptions.shebang`.
      */
-    shebang?: boolean;
+    shebang?: boolean | string;
     /**
      * Extra module aliases layered on top of the built-in alias map.
      * Comes from `gjsify build --alias FROM=TO`.
@@ -83,4 +118,110 @@ export interface ConfigData {
      * Example: `["fetch", "XMLHttpRequest"]` excludes the HTTP polyfill stack.
      */
     excludeGlobals?: string[];
+    /**
+     * Compile-time defines populated from `package.json` fields. Each entry
+     * maps a JS identifier (the define key) to a dotted package.json path.
+     * Values are JSON-stringified before merging into `bundler.transform.define`.
+     *
+     * Example:
+     * ```jsonc
+     * "defineFromPackageJson": {
+     *   "__PACKAGE_VERSION__": { "field": "version" },
+     *   "__PACKAGE_NAME__":    { "field": "name" }
+     * }
+     * ```
+     *
+     * Replaces the wrapper-script pattern (`spawnSync('gjsify', ['build',
+     * '--define', '__VERSION__=' + JSON.stringify(pkg.version)])`) used by
+     * `@ts-for-gir/cli` before this option existed.
+     */
+    defineFromPackageJson?: Record<string, {
+        field: string;
+    }>;
+    /**
+     * Compile-time defines populated from `process.env` at config-load time.
+     * Each entry maps a JS identifier to an environment variable name with an
+     * optional default. Values are JSON-stringified before merging into
+     * `bundler.transform.define`. When the variable is unset and no default
+     * is provided, the identifier is replaced with the literal `undefined`
+     * so consumer code can safely guard with `typeof X === 'undefined'` or
+     * `X ?? fallback`.
+     *
+     * Example:
+     * ```jsonc
+     * "defineFromEnv": {
+     *   "__APPLICATION_ID__": { "env": "APPLICATION_ID", "default": "org.example.App" },
+     *   "__PREFIX__":         { "env": "PREFIX" }
+     * }
+     * ```
+     *
+     * Designed for projects whose build is driven by an outer tool (Meson,
+     * Make, CI) that exports environment variables — avoids a wrapper script
+     * just to thread them through to the bundler.
+     */
+    defineFromEnv?: Record<string, {
+        env: string;
+        default?: string;
+    }>;
+    /**
+     * Extension → loader-kind map for files Rolldown does not classify
+     * natively. Currently only `'text'` is implemented — the file's content
+     * becomes the JS string default export (`export default "<content>"`).
+     * Replaces the legacy esbuild `loader: { '.ui': 'text' }` pattern.
+     *
+     * Example:
+     * ```jsonc
+     * "loaders": { ".ui": "text", ".asm": "text" }
+     * ```
+     *
+     * Lives at the top level (not under `bundler`) so it doesn't leak into
+     * Rolldown's options on pass-through; the CLI converts it into a
+     * `text-loader` plugin prepended to the bundler's plugin chain.
+     */
+    loaders?: Record<string, 'text'>;
+    /**
+     * Flatpak-related configuration consumed by `gjsify flatpak <sub>`.
+     * Lives in its own top-level namespace so the bundler config doesn't
+     * accumulate concerns and `flatpak init` / `flatpak ci` can read defaults
+     * declaratively. CLI flags override these values.
+     */
+    flatpak?: ConfigDataFlatpak;
+}
+/**
+ * Flatpak-toolchain config consumed by the `gjsify flatpak` subcommand
+ * group. All fields optional — sensible defaults apply when missing.
+ */
+export interface ConfigDataFlatpak {
+    /** Reverse-DNS app id, e.g. `eu.jumplink.Learn6502`. Defaults to `package.json#name` if it looks like a reverse-DNS id. */
+    appId?: string;
+    /**
+     * Runtime family. Default `'gnome'` — needed at runtime by GJS bundles
+     * for GLib/GObject/GIO. `'freedesktop'` is only suitable for non-gjsify
+     * CLI tools (no GJS interpreter ships in the Freedesktop runtime).
+     */
+    runtime?: 'gnome' | 'freedesktop';
+    /** Runtime/SDK version, e.g. `'50'` for GNOME or `'24.08'` for Freedesktop. */
+    runtimeVersion?: string;
+    /** Extra SDK extensions, e.g. `['org.freedesktop.Sdk.Extension.node24']` for build-time `yarn install`. */
+    sdkExtensions?: string[];
+    /** Path components prepended to PATH inside the build sandbox. */
+    appendPath?: string[];
+    /** The binary name to run (`/app/bin/<command>`). Defaults to `appId`. */
+    command?: string;
+    /** Finish-args (capabilities). Default depends on `runtime` + `--cli-only`. */
+    finishArgs?: string[];
+    /** Extra Flatpak modules prepended before the app's own meson/simple module (e.g. `blueprint-compiler` build). */
+    extraModules?: unknown[];
+    /** Cleanup glob patterns applied to the final manifest, e.g. `['/include', '/lib/pkgconfig']`. */
+    cleanup?: string[];
+    /** Source-of-truth lockfile for `gjsify flatpak deps` — `yarn.lock` or `package-lock.json`. */
+    lockfile?: string;
+    /**
+     * GitHub-Actions container image override for `gjsify flatpak ci`.
+     * Default derived from runtime + runtimeVersion:
+     *   gnome+50 → `ghcr.io/flathub-infra/flatpak-github-actions:gnome-50`
+     */
+    ciContainer?: string;
+    /** Branches the generated workflow triggers on. Default `['main']`. */
+    ciBranches?: string[];
 }

package/lib/utils/install-global.d.ts

@@ -0,0 +1,54 @@
+export interface GlobalLayout {
+    /** Where extracted package trees live: `<prefix>/node_modules/<pkg>/`. */
+    prefix: string;
+    /** Where bin-name symlinks land. Typically `~/.local/bin`. */
+    binDir: string;
+}
+/**
+ * Compute the canonical global install layout for the current user. Honours
+ * `XDG_DATA_HOME` (per the XDG Base Directory Spec) plus
+ * `GJSIFY_GLOBAL_PREFIX` and `GJSIFY_GLOBAL_BIN_DIR` escape hatches for tests.
+ */
+export declare function defaultGlobalLayout(): GlobalLayout;
+export interface LinkedBin {
+    /** The bin-name (key from `bin` / `gjsify.bin`). */
+    name: string;
+    /** Absolute path to the file the symlink points at. */
+    target: string;
+    /** Absolute path to the symlink (under `binDir`). */
+    link: string;
+}
+/**
+ * Install each top-level package's bin entries into `binDir` as small POSIX
+ * `sh` launchers that exec the real bin. Reads each package's installed
+ * `package.json` to discover bins; prefers `gjsify.bin` (GJS-bundled bins)
+ * over the npm `bin` field, falling back to npm `bin` when no GJS map is
+ * declared. Stale launchers are replaced (latest install wins).
+ *
+ * Why launchers instead of symlinks:
+ *
+ *   When a GJS bundle is invoked via a symlink in $PATH, the kernel follows
+ *   the symlink to find the executable but passes the original (symlink)
+ *   path to it. The bundle's shebang then runs as `gjs -m <symlink-path>`,
+ *   which makes `import.meta.url` resolve to the symlink directory — so any
+ *   path computation relative to `import.meta.url` (e.g. ts-for-gir's
+ *   `findTemplatesRoot()`, version-discovery `readFileSync`s, gjsify's own
+ *   `import.meta.url` rewrites) looks for assets in the wrong place.
+ *
+ *   A `sh` launcher invokes the real path explicitly, so the bundle sees its
+ *   real install location in `import.meta.url` and every relative read works.
+ *   This costs ~50 bytes per bin and one extra `exec` per launch — both
+ *   negligible compared to `gjs -m` cold-start time.
+ *
+ *   Plain Node bins are unaffected by either approach (Node defaults to
+ *   resolving symlinks in ESM module URLs); launchers are uniform for
+ *   simplicity and so we don't need to discriminate by runtime here.
+ */
+export declare function linkGlobalBins(packageNames: string[], layout: GlobalLayout): LinkedBin[];
+/** Returns `true` if `binDir` is on the user's PATH. */
+export declare function binDirOnPath(binDir: string): boolean;
+/**
+ * Extracts the package name from a spec like `name@1.2`, `@scope/name`,
+ * or `@scope/name@latest`. Returns the unchanged string for plain names.
+ */
+export declare function specToPackageName(spec: string): string;

package/lib/utils/install-global.js

@@ -0,0 +1,153 @@
+// Global-install helpers for `gjsify install -g <pkg>`.
+//
+// Layout (XDG-compliant, ~ = $HOME):
+//
+//   ~/.local/share/gjsify/global/
+//     node_modules/<pkg>/                  ← extracted package contents
+//       package.json
+//       bin/<pkg>                          ← original npm bin
+//       bin/<pkg>-gjs                      ← GJS bundle (declared via `gjsify.bin`)
+//       <pkg-data-files>                   ← e.g. `dist-templates/` for ts-for-gir
+//   ~/.local/bin/<bin-name>                ← symlink to the matching bin under node_modules
+//
+// Unlike the project install path (`gjsify install <pkg>` without -g), this
+// mode installs the requested top-level packages plus their runtime deps into
+// a user-owned XDG location, never mutates a project package.json, and links
+// bins into the user's PATH so the package is invocable as `<bin-name>` from
+// anywhere — the closest GJS equivalent of `npm i -g`.
+//
+// `gjsify.bin` (when declared) wins over the standard npm `bin` field on this
+// path because the user explicitly asked for the GJS-runnable artifact: e.g.
+// `ts-for-gir` (npm bin = bin/ts-for-gir Node script) becomes a symlink to
+// `bin/ts-for-gir-gjs` (the self-contained GJS bundle) instead.
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/**
+ * Compute the canonical global install layout for the current user. Honours
+ * `XDG_DATA_HOME` (per the XDG Base Directory Spec) plus
+ * `GJSIFY_GLOBAL_PREFIX` and `GJSIFY_GLOBAL_BIN_DIR` escape hatches for tests.
+ */
+export function defaultGlobalLayout() {
+    const prefixOverride = process.env.GJSIFY_GLOBAL_PREFIX;
+    const binOverride = process.env.GJSIFY_GLOBAL_BIN_DIR;
+    const home = os.homedir();
+    const xdgData = process.env.XDG_DATA_HOME ?? path.join(home, '.local', 'share');
+    return {
+        prefix: prefixOverride ?? path.join(xdgData, 'gjsify', 'global'),
+        binDir: binOverride ?? path.join(home, '.local', 'bin'),
+    };
+}
+/**
+ * Install each top-level package's bin entries into `binDir` as small POSIX
+ * `sh` launchers that exec the real bin. Reads each package's installed
+ * `package.json` to discover bins; prefers `gjsify.bin` (GJS-bundled bins)
+ * over the npm `bin` field, falling back to npm `bin` when no GJS map is
+ * declared. Stale launchers are replaced (latest install wins).
+ *
+ * Why launchers instead of symlinks:
+ *
+ *   When a GJS bundle is invoked via a symlink in $PATH, the kernel follows
+ *   the symlink to find the executable but passes the original (symlink)
+ *   path to it. The bundle's shebang then runs as `gjs -m <symlink-path>`,
+ *   which makes `import.meta.url` resolve to the symlink directory — so any
+ *   path computation relative to `import.meta.url` (e.g. ts-for-gir's
+ *   `findTemplatesRoot()`, version-discovery `readFileSync`s, gjsify's own
+ *   `import.meta.url` rewrites) looks for assets in the wrong place.
+ *
+ *   A `sh` launcher invokes the real path explicitly, so the bundle sees its
+ *   real install location in `import.meta.url` and every relative read works.
+ *   This costs ~50 bytes per bin and one extra `exec` per launch — both
+ *   negligible compared to `gjs -m` cold-start time.
+ *
+ *   Plain Node bins are unaffected by either approach (Node defaults to
+ *   resolving symlinks in ESM module URLs); launchers are uniform for
+ *   simplicity and so we don't need to discriminate by runtime here.
+ */
+export function linkGlobalBins(packageNames, layout) {
+    fs.mkdirSync(layout.binDir, { recursive: true });
+    const created = [];
+    for (const pkgName of packageNames) {
+        const pkgDir = path.join(layout.prefix, 'node_modules', pkgName);
+        const pkgJsonPath = path.join(pkgDir, 'package.json');
+        if (!fs.existsSync(pkgJsonPath))
+            continue;
+        const pkgJson = readJson(pkgJsonPath);
+        const binMap = pickBinMap(pkgName, pkgJson);
+        if (!binMap || binMap.size === 0)
+            continue;
+        for (const [binName, binTarget] of binMap) {
+            const targetAbs = path.join(pkgDir, binTarget);
+            if (!fs.existsSync(targetAbs))
+                continue;
+            try {
+                fs.chmodSync(targetAbs, 0o755);
+            }
+            catch {
+                /* best effort */
+            }
+            const linkPath = path.join(layout.binDir, binName);
+            fs.rmSync(linkPath, { force: true });
+            // Inline `${target}` directly — this file is rewritten on every
+            // install, paths are user-owned, and POSIX `sh` quoting via
+            // single-quotes plus `'\''` for embedded quotes is well-defined.
+            const launcher = `#!/bin/sh\nexec ${shQuote(targetAbs)} "$@"\n`;
+            fs.writeFileSync(linkPath, launcher);
+            fs.chmodSync(linkPath, 0o755);
+            created.push({ name: binName, target: targetAbs, link: linkPath });
+        }
+    }
+    return created;
+}
+function shQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function pickBinMap(pkgName, pkgJson) {
+    const gjsifyEntry = pkgJson.gjsify;
+    if (gjsifyEntry?.bin !== undefined) {
+        return normalizeBin(pkgName, gjsifyEntry.bin);
+    }
+    const npmBin = pkgJson.bin;
+    if (npmBin !== undefined) {
+        return normalizeBin(pkgName, npmBin);
+    }
+    return null;
+}
+function normalizeBin(pkgName, bin) {
+    const out = new Map();
+    if (typeof bin === 'string') {
+        const baseName = pkgName.startsWith('@')
+            ? pkgName.slice(pkgName.indexOf('/') + 1)
+            : pkgName;
+        out.set(baseName, bin);
+        return out;
+    }
+    for (const [k, v] of Object.entries(bin))
+        out.set(k, v);
+    return out;
+}
+function readJson(file) {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+}
+/** Returns `true` if `binDir` is on the user's PATH. */
+export function binDirOnPath(binDir) {
+    const PATH = process.env.PATH ?? '';
+    const sep = process.platform === 'win32' ? ';' : ':';
+    const want = path.resolve(binDir);
+    return PATH.split(sep).some((entry) => entry && path.resolve(entry) === want);
+}
+/**
+ * Extracts the package name from a spec like `name@1.2`, `@scope/name`,
+ * or `@scope/name@latest`. Returns the unchanged string for plain names.
+ */
+export function specToPackageName(spec) {
+    if (spec.startsWith('@')) {
+        const slash = spec.indexOf('/');
+        if (slash < 0)
+            return spec;
+        const at = spec.indexOf('@', slash);
+        return at < 0 ? spec : spec.slice(0, at);
+    }
+    const at = spec.indexOf('@');
+    return at < 0 ? spec : spec.slice(0, at);
+}

package/lib/utils/resolve-plugin-by-name.d.ts

@@ -0,0 +1,21 @@
+import type { RolldownPluginOption } from 'rolldown';
+/** User-supplied entry: a package name + optional named export and options. */
+export interface PluginByName {
+    name: string;
+    /** Named export to invoke. Defaults to the module's default export. */
+    export?: string;
+    /** Options forwarded to the plugin factory. */
+    options?: unknown;
+}
+/** Type-guard: a `PluginByName` shape rather than a Rolldown plugin object. */
+export declare function isPluginByName(value: unknown): value is PluginByName;
+/**
+ * Resolve a list of mixed user plugins. Entries that are already plugin
+ * objects pass through unchanged; entries shaped like `PluginByName` get
+ * dynamically imported, instantiated with their `options`, and returned in
+ * the same position. Resolution is anchored at `projectDir`.
+ *
+ * Throws when a name fails to resolve, when the chosen export is not a
+ * function, or when the factory returns nothing.
+ */
+export declare function resolveUserPlugins(plugins: ReadonlyArray<RolldownPluginOption | PluginByName>, projectDir: string): Promise<RolldownPluginOption[]>;

package/lib/utils/resolve-plugin-by-name.js

@@ -0,0 +1,75 @@
+// Resolve `bundler.plugins` entries that are specified by package name in
+// the user's gjsify config, e.g.:
+//
+//   "bundler": {
+//     "plugins": [
+//       { "name": "@gjsify/vite-plugin-blueprint", "options": { "minify": true } },
+//       { "name": "@gjsify/vite-plugin-gettext", "export": "msgfmtPlugin", "options": { ... } }
+//     ]
+//   }
+//
+// Lets `package.json#gjsify` describe the full plugin chain without dropping
+// to a JS-form config file (`gjsify.config.mjs`). Resolution is anchored at
+// the project root (where the config lives) so the project's own
+// `node_modules` wins over the CLI's own dependencies.
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** Type-guard: a `PluginByName` shape rather than a Rolldown plugin object. */
+export function isPluginByName(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.name === 'string' &&
+        // RolldownPluginOption can be `false | null | undefined | Plugin | Promise<Plugin>`.
+        // A real plugin always has a function-shape behavior; `name` alone is shared
+        // with our shape, so we additionally require absence of plugin-shape fields.
+        !('apply' in value) &&
+        !('resolveId' in value) &&
+        !('load' in value) &&
+        !('transform' in value) &&
+        !('renderChunk' in value) &&
+        !('generateBundle' in value));
+}
+/**
+ * Resolve a list of mixed user plugins. Entries that are already plugin
+ * objects pass through unchanged; entries shaped like `PluginByName` get
+ * dynamically imported, instantiated with their `options`, and returned in
+ * the same position. Resolution is anchored at `projectDir`.
+ *
+ * Throws when a name fails to resolve, when the chosen export is not a
+ * function, or when the factory returns nothing.
+ */
+export async function resolveUserPlugins(plugins, projectDir) {
+    const requireFromProject = createRequire(join(projectDir, 'package.json'));
+    const out = [];
+    for (const entry of plugins) {
+        if (!isPluginByName(entry)) {
+            out.push(entry);
+            continue;
+        }
+        let resolvedPath;
+        try {
+            resolvedPath = requireFromProject.resolve(entry.name);
+        }
+        catch (err) {
+            throw new Error(`gjsify config: failed to resolve plugin "${entry.name}" from ${projectDir}. ` +
+                `Add it to your project's dependencies, or pass a Plugin object directly. ` +
+                `(${err.message})`);
+        }
+        const mod = await import(pathToFileURL(resolvedPath).href);
+        const exportName = entry.export ?? 'default';
+        const factory = mod[exportName];
+        if (typeof factory !== 'function') {
+            const available = Object.keys(mod).filter((k) => typeof mod[k] === 'function');
+            throw new Error(`gjsify config: plugin "${entry.name}" has no function export "${exportName}". ` +
+                `Available function exports: ${available.length ? available.join(', ') : '(none)'}.`);
+        }
+        const plugin = await factory(entry.options);
+        if (plugin === undefined || plugin === null) {
+            throw new Error(`gjsify config: plugin "${entry.name}" factory returned ${plugin}. ` +
+                `Check the plugin's signature — it should return a Rolldown/Vite plugin object.`);
+        }
+        out.push(plugin);
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/cli",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "CLI for Gjsify",
   "type": "module",
   "main": "lib/index.js",
@@ -23,15 +23,15 @@
     "cli"
   ],
   "dependencies": {
-    "@gjsify/create-app": "^0.3.14",
-    "@gjsify/node-polyfills": "^0.3.14",
-    "@gjsify/npm-registry": "^0.3.14",
-    "@gjsify/resolve-npm": "^0.3.14",
-    "@gjsify/rolldown-plugin-gjsify": "^0.3.14",
-    "@gjsify/rolldown-plugin-pnp": "^0.3.14",
-    "@gjsify/semver": "^0.3.14",
-    "@gjsify/tar": "^0.3.14",
-    "@gjsify/web-polyfills": "^0.3.14",
+    "@gjsify/create-app": "^0.3.16",
+    "@gjsify/node-polyfills": "^0.3.16",
+    "@gjsify/npm-registry": "^0.3.16",
+    "@gjsify/resolve-npm": "^0.3.16",
+    "@gjsify/rolldown-plugin-gjsify": "^0.3.16",
+    "@gjsify/rolldown-plugin-pnp": "^0.3.16",
+    "@gjsify/semver": "^0.3.16",
+    "@gjsify/tar": "^0.3.16",
+    "@gjsify/web-polyfills": "^0.3.16",
     "cosmiconfig": "^9.0.1",
     "get-tsconfig": "^4.14.0",
     "pkg-types": "^2.3.1",

package/src/actions/build.ts

@@ -2,7 +2,8 @@ import type { ConfigData, BundlerOptions } from "../types/index.js";
 import type { App, PluginOptions } from "@gjsify/rolldown-plugin-gjsify";
 import type { RolldownOutput, RolldownPluginOption } from "rolldown";
 import { rolldown } from "rolldown";
-import { gjsifyPlugin } from "@gjsify/rolldown-plugin-gjsify";
+import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine } from "@gjsify/rolldown-plugin-gjsify";
+import { resolveUserPlugins } from "../utils/resolve-plugin-by-name.js";
 import {
     resolveGlobalsList,
     writeRegisterInjectFile,
@@ -13,7 +14,7 @@ import { dirname, extname } from "node:path";
 import { chmod, readFile, writeFile } from "node:fs/promises";
 import { normalizeBundlerOptions, mergeBundlerOptions } from "../utils/normalize-bundler-options.js";
 
-const GJS_SHEBANG = "#!/usr/bin/env -S gjs -m\n";
+const DEFAULT_GJS_SHEBANG = "#!/usr/bin/env -S gjs -m";
 
 /**
  * `true` when `path` points at a location that's unsafe to use as a build
@@ -190,8 +191,12 @@ export class BuildAction {
     }
 
     /**
-     * Post-processing: prepend GJS shebang and mark the output file executable.
-     * Only runs for GJS app builds with a resolvable single outfile.
+     * Post-processing: prepend the resolved shebang line and mark the
+     * output executable. Only runs for GJS app builds with a single outfile.
+     * The shebang plugin in `@gjsify/rolldown-plugin-gjsify` already injects
+     * during bundling — this hook is the safety net for anything that
+     * bypassed the plugin (e.g. user-supplied banners that out-ordered it),
+     * plus the chmod.
      */
     private async applyShebang(
         outfile: string | undefined,
@@ -205,6 +210,8 @@ export class BuildAction {
             return;
         }
 
+        const line = resolveShebangLine(this.configData.shebang) ?? DEFAULT_GJS_SHEBANG;
+
         const content = await readFile(outfile, "utf-8");
         if (content.startsWith("#!")) {
             if (verbose)
@@ -212,12 +219,12 @@ export class BuildAction {
                     `[gjsify] --shebang skipped: ${outfile} already starts with a shebang`,
                 );
         } else {
-            await writeFile(outfile, GJS_SHEBANG + content);
+            await writeFile(outfile, line + "\n" + content);
         }
         await chmod(outfile, 0o755);
         if (verbose)
             console.debug(
-                `[gjsify] --shebang: wrote shebang + chmod 0o755 to ${outfile}`,
+                `[gjsify] --shebang: wrote ${line} + chmod 0o755 to ${outfile}`,
             );
     }
 
@@ -283,6 +290,26 @@ export class BuildAction {
         const pnp = await buildPnpPlugin();
         const pnpPlugins: RolldownPluginOption[] = pnp ? [pnp] : [];
 
+        // User-supplied text loaders need to be available during BOTH the
+        // auto-globals pre-build (`detectAutoGlobals`) and the final build —
+        // otherwise Rolldown's parser hits unknown extensions like `.ui` /
+        // `.asm` during the pre-build, fails to parse them as JS/JSX, and
+        // the auto-globals iteration aborts before the final plugin chain is
+        // ever assembled. Build the user-plugin chain once, up front, and
+        // pass it into both passes.
+        const userTextLoader = textLoaderPlugin({ loaders: this.configData.loaders });
+        const userPlugins: RolldownPluginOption[] = userTextLoader ? [userTextLoader] : [];
+
+        // User-supplied bundler.plugins (mix of plugin objects + by-name
+        // entries) — resolved from the project's node_modules. Same
+        // ordering rationale as the text loader: must be present during
+        // auto-globals pre-build to avoid claiming the same files via
+        // Rolldown's default classifier.
+        if (userBundler.plugins?.length) {
+            const resolved = await resolveUserPlugins(userBundler.plugins, process.cwd());
+            userPlugins.push(...resolved);
+        }
+
         // --- Auto mode (with optional extras): iterative multi-pass build ---
         if (app === "gjs" && autoMode) {
             const gjsifyPluginFactory = async (opts: PluginOptions) => {
@@ -303,7 +330,7 @@ export class BuildAction {
             const { injectPath } = await detectAutoGlobals(
                 {
                     input: userBundler.input,
-                    plugins: pnpPlugins,
+                    plugins: [...pnpPlugins, ...userPlugins],
                     external: userBundler.external,
                     transform: userBundler.transform,
                     format,
@@ -337,9 +364,15 @@ export class BuildAction {
         );
 
         const merged = mergeBundlerOptions(cfg.options as BundlerOptions, userBundler);
+
         const finalOpts: BundlerOptions = {
             ...merged,
-            plugins: [...pnpPlugins, ...cfg.plugins],
+            // Drop user-config plugins from `merged` — they survived
+            // mergeBundlerOptions via spread but have already been resolved
+            // and appended into `userPlugins` above. Re-emitting the raw
+            // entries (which may include `BundlerPluginByName` shapes
+            // Rolldown doesn't understand) would crash the build.
+            plugins: [...pnpPlugins, ...userPlugins, ...cfg.plugins],
         };
 
         const build = await rolldown(finalOpts);