@gjsify/cli 0.3.14 → 0.3.15

package/src/types/config-data.ts

@@ -1,6 +1,25 @@
-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
@@ -10,9 +29,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>;
 };
 
 /**
@@ -69,9 +93,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`.
@@ -84,4 +120,106 @@ 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/src/utils/install-global.ts

@@ -0,0 +1,182 @@
+// 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';
+
+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 function defaultGlobalLayout(): GlobalLayout {
+    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'),
+    };
+}
+
+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 function linkGlobalBins(packageNames: string[], layout: GlobalLayout): LinkedBin[] {
+    fs.mkdirSync(layout.binDir, { recursive: true });
+    const created: LinkedBin[] = [];
+
+    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: string): string {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+function pickBinMap(
+    pkgName: string,
+    pkgJson: Record<string, unknown>,
+): Map<string, string> | null {
+    const gjsifyEntry = pkgJson.gjsify as { bin?: string | Record<string, string> } | undefined;
+    if (gjsifyEntry?.bin !== undefined) {
+        return normalizeBin(pkgName, gjsifyEntry.bin);
+    }
+    const npmBin = pkgJson.bin as string | Record<string, string> | undefined;
+    if (npmBin !== undefined) {
+        return normalizeBin(pkgName, npmBin);
+    }
+    return null;
+}
+
+function normalizeBin(
+    pkgName: string,
+    bin: string | Record<string, string>,
+): Map<string, string> {
+    const out = new Map<string, string>();
+    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: string): Record<string, unknown> {
+    return JSON.parse(fs.readFileSync(file, 'utf-8')) as Record<string, unknown>;
+}
+
+/** Returns `true` if `binDir` is on the user's PATH. */
+export function binDirOnPath(binDir: string): boolean {
+    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: string): string {
+    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/src/utils/resolve-plugin-by-name.ts

@@ -0,0 +1,106 @@
+// 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';
+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 function isPluginByName(value: unknown): value is PluginByName {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        typeof (value as { name?: unknown }).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: ReadonlyArray<RolldownPluginOption | PluginByName>,
+    projectDir: string,
+): Promise<RolldownPluginOption[]> {
+    const requireFromProject = createRequire(join(projectDir, 'package.json'));
+    const out: RolldownPluginOption[] = [];
+
+    for (const entry of plugins) {
+        if (!isPluginByName(entry)) {
+            out.push(entry as RolldownPluginOption);
+            continue;
+        }
+
+        let resolvedPath: string;
+        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 as Error).message})`,
+            );
+        }
+
+        const mod = await import(pathToFileURL(resolvedPath).href);
+        const exportName = entry.export ?? 'default';
+        const factory = (mod as Record<string, unknown>)[exportName];
+
+        if (typeof factory !== 'function') {
+            const available = Object.keys(mod).filter(
+                (k) => typeof (mod as Record<string, unknown>)[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 as (opts?: unknown) => unknown)(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 as RolldownPluginOption);
+    }
+
+    return out;
+}