@gjsify/cli 0.3.13 → 0.3.15

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

@@ -1,9 +1,81 @@
-import type { BuildOptions as EsbuildOptions } from 'esbuild';
+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
+ * applies platform defaults on top of these, so most projects only need
+ * `output.file` / `output.dir` here.
+ *
+ * `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' | 'plugins'> & {
+    output?: OutputOptions;
+    plugins?: Array<RolldownPluginOption | BundlerPluginByName>;
+};
+/**
+ * Legacy `esbuild?: BuildOptions` shape — kept as a compatibility shim for
+ * one minor release. Setting it logs a deprecation warning; the supported
+ * subset of fields is mapped into `bundler` at config-load time.
+ *
+ * Drop in 0.5.0.
+ */
+export interface LegacyEsbuildOptions {
+    outfile?: string;
+    outdir?: string;
+    format?: 'esm' | 'cjs' | 'iife';
+    external?: string[];
+    define?: Record<string, string>;
+    inject?: string[];
+    banner?: {
+        js?: string;
+    };
+    target?: string | string[];
+    minify?: boolean;
+    sourcemap?: boolean | 'inline' | 'external' | 'both';
+    mainFields?: string[];
+    conditions?: string[];
+    platform?: 'browser' | 'node' | 'neutral';
+    loader?: Record<string, string>;
+}
 export interface ConfigData {
     /** Switch on the verbose mode */
     verbose?: boolean;
-    esbuild?: EsbuildOptions;
+    /**
+     * Bundler-level options forwarded to Rolldown. Replaces the legacy
+     * `esbuild` field. The orchestrator applies platform-specific defaults
+     * on top — most projects only need to set `output.file` / `output.dir`.
+     */
+    bundler?: BundlerOptions;
+    /**
+     * @deprecated Use `bundler` instead. Will be removed in 0.5.0. The shim
+     * maps the supported subset of esbuild fields into the equivalent
+     * Rolldown shape and logs a deprecation warning.
+     */
+    esbuild?: LegacyEsbuildOptions;
     library?: ConfigDataLibrary;
     typescript?: ConfigDataTypescript;
     /** An array of glob patterns to exclude matches and aliases */
@@ -19,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`.
@@ -34,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/normalize-bundler-options.d.ts

@@ -0,0 +1,17 @@
+import type { ConfigData, BundlerOptions } from '../types/config-data.js';
+export declare function normalizeBundlerOptions(configData: ConfigData): BundlerOptions;
+/**
+ * Shallow merge with deep-merge of `output`, `transform`, and `resolve`. The
+ * second argument wins on conflicts, matching `merge(target, ...sources)`
+ * semantics from `@gjsify/rolldown-plugin-gjsify/utils/merge`.
+ *
+ * `base` is typically the Rolldown-generic shape returned by the orchestrator;
+ * `overrides` is the user's `BundlerOptions` from `.gjsifyrc.js` plus CLI
+ * flag merges. Single-output assumption matches `BundlerOptions['output']`.
+ *
+ * The orchestrator-side `input` is authoritative — it's the post-glob-expansion
+ * value. Overriding it with the user's raw glob string would re-introduce
+ * unresolved glob patterns into the final Rolldown call. Same for `external`,
+ * which the orchestrator concatenates with platform defaults already.
+ */
+export declare function mergeBundlerOptions(base: BundlerOptions, overrides: BundlerOptions): BundlerOptions;

package/lib/utils/normalize-bundler-options.js

@@ -0,0 +1,123 @@
+// One-release deprecation shim: maps the legacy `esbuild?: BuildOptions`
+// field on `.gjsifyrc.js` / `package.json#gjsify` into the equivalent
+// `bundler?: RolldownOptions` shape. Logs a single warning per build.
+//
+// Drop in 0.5.0.
+let warnedOnce = false;
+export function normalizeBundlerOptions(configData) {
+    const fromBundler = (configData.bundler ?? {});
+    if (!configData.esbuild)
+        return fromBundler;
+    if (!warnedOnce) {
+        warnedOnce = true;
+        // eslint-disable-next-line no-console
+        console.warn("[gjsify] DEPRECATION: the 'esbuild' config key is deprecated and will be removed in 0.5.0. " +
+            "Rename it to 'bundler' (typed as RolldownOptions). See the migration notes in the gjsify CHANGELOG.");
+    }
+    const fromEsbuild = legacyEsbuildToRolldown(configData.esbuild);
+    // Plain user-config merge — we deliberately do NOT call
+    // `mergeBundlerOptions` here, because that function strips `input` and
+    // `external` from its overrides arg (it assumes the *orchestrator* is
+    // the override source and the user the base). Here both inputs are
+    // user-provided config and `input` must survive the merge.
+    const out = { ...fromEsbuild, ...fromBundler };
+    if (fromEsbuild.output || fromBundler.output) {
+        out.output = { ...(fromEsbuild.output ?? {}), ...(fromBundler.output ?? {}) };
+    }
+    if (fromEsbuild.transform || fromBundler.transform) {
+        out.transform = { ...(fromEsbuild.transform ?? {}), ...(fromBundler.transform ?? {}) };
+        if (fromEsbuild.transform?.define || fromBundler.transform?.define) {
+            out.transform.define = {
+                ...(fromEsbuild.transform?.define ?? {}),
+                ...(fromBundler.transform?.define ?? {}),
+            };
+        }
+    }
+    if (fromEsbuild.resolve || fromBundler.resolve) {
+        out.resolve = { ...(fromEsbuild.resolve ?? {}), ...(fromBundler.resolve ?? {}) };
+    }
+    return out;
+}
+/** Map the supported subset of esbuild BuildOptions into RolldownOptions. */
+function legacyEsbuildToRolldown(esb) {
+    const out = {};
+    const output = {};
+    const transform = {};
+    const resolve = {};
+    if (esb.outfile !== undefined)
+        output.file = esb.outfile;
+    if (esb.outdir !== undefined)
+        output.dir = esb.outdir;
+    if (esb.format !== undefined)
+        output.format = esb.format;
+    if (esb.minify !== undefined)
+        output.minify = esb.minify;
+    if (esb.sourcemap !== undefined) {
+        // esbuild has 'external' / 'both' which Rolldown doesn't — coerce to boolean.
+        output.sourcemap =
+            esb.sourcemap === 'inline'
+                ? 'inline'
+                : Boolean(esb.sourcemap);
+    }
+    if (esb.banner?.js !== undefined)
+        output.banner = esb.banner.js;
+    if (esb.target !== undefined) {
+        transform.target = Array.isArray(esb.target) ? esb.target.join(',') : esb.target;
+    }
+    if (esb.define !== undefined)
+        transform.define = esb.define;
+    if (esb.mainFields !== undefined)
+        resolve.mainFields = esb.mainFields;
+    if (esb.conditions !== undefined)
+        resolve.conditionNames = esb.conditions;
+    if (esb.external !== undefined)
+        out.external = esb.external;
+    if (esb.platform !== undefined)
+        out.platform = esb.platform;
+    if (Object.keys(output).length > 0)
+        out.output = output;
+    if (Object.keys(transform).length > 0)
+        out.transform = transform;
+    if (Object.keys(resolve).length > 0)
+        out.resolve = resolve;
+    // Discarded silently:
+    //   esb.inject  — esbuild's array-of-side-effect-files; surfaced at the
+    //                 CLI layer instead, via input expansion.
+    //   esb.loader  — Rolldown infers module types from extensions natively.
+    return out;
+}
+/**
+ * Shallow merge with deep-merge of `output`, `transform`, and `resolve`. The
+ * second argument wins on conflicts, matching `merge(target, ...sources)`
+ * semantics from `@gjsify/rolldown-plugin-gjsify/utils/merge`.
+ *
+ * `base` is typically the Rolldown-generic shape returned by the orchestrator;
+ * `overrides` is the user's `BundlerOptions` from `.gjsifyrc.js` plus CLI
+ * flag merges. Single-output assumption matches `BundlerOptions['output']`.
+ *
+ * The orchestrator-side `input` is authoritative — it's the post-glob-expansion
+ * value. Overriding it with the user's raw glob string would re-introduce
+ * unresolved glob patterns into the final Rolldown call. Same for `external`,
+ * which the orchestrator concatenates with platform defaults already.
+ */
+export function mergeBundlerOptions(base, overrides) {
+    // Strip fields the orchestrator owns authoritatively — the user has
+    // already had their say via the orchestrator's `userExternal` / input
+    // expansion; merging the raw values back on top would clobber the
+    // post-processing.
+    const { input: _ignoredInput, external: _ignoredExternal, ...overridesRest } = overrides;
+    const out = { ...base, ...overridesRest };
+    if (base.output || overrides.output) {
+        out.output = { ...(base.output ?? {}), ...(overrides.output ?? {}) };
+    }
+    if (base.transform || overrides.transform) {
+        out.transform = { ...(base.transform ?? {}), ...(overrides.transform ?? {}) };
+        if (base.transform?.define || overrides.transform?.define) {
+            out.transform.define = { ...(base.transform?.define ?? {}), ...(overrides.transform?.define ?? {}) };
+        }
+    }
+    if (base.resolve || overrides.resolve) {
+        out.resolve = { ...(base.resolve ?? {}), ...(overrides.resolve ?? {}) };
+    }
+    return out;
+}

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;
+}