@gjsify/cli 0.42.0 → 0.44.0

package/lib/actions/build.d.ts

@@ -72,6 +72,12 @@ export declare class BuildAction {
      * natively, `@gjsify/rolldown-native` via `synthRolldownOutput`), and it
      * cannot be fooled by a `node:` specifier quoted inside a string, which a
      * text scan cannot tell from a statement.
+     *
+     * The same list also answers the GENERAL form of the question — any bare
+     * specifier GJS cannot resolve, `node:` or not — which is why the target's
+     * externals predicate and the emitted fileNames are handed over: they are
+     * what separates a declared external and a sibling chunk from a dependency
+     * that simply is not there.
      */
     private assertGjsOutputLoadable;
     /**

package/lib/actions/build.js

@@ -1,5 +1,5 @@
 import { runBundle, runWatch, bundleToChunks } from '../bundler-pick.js';
-import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine, NODE_SHEBANG } from '@gjsify/rolldown-plugin-gjsify';
+import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine, NODE_SHEBANG, createGjsExternalsPredicate, globToEntryPoints, } from '@gjsify/rolldown-plugin-gjsify';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { resolveUserPlugins } from '../utils/resolve-plugin-by-name.js';
 import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, detectNodeGiGlobals, } from '@gjsify/rolldown-plugin-gjsify/globals';
@@ -10,7 +10,8 @@ import { chmod, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promis
 import { normalizeBundlerOptions, mergeBundlerOptions } from '../utils/normalize-bundler-options.js';
 import { inputSourceDirs, isOutdirInsideSource, libraryOutputLeakError } from '../utils/library-output.js';
 import { detectHtmlEntry, parseHtmlEntry, emitBrowserHtml, htmlOutPathFor } from '../utils/html-entry.js';
-import { assertGjsBundleLoadable } from '../utils/gjs-bundle-guard.js';
+import { assertGjsBundleLoadable, assertGjsBundleParses } from '../utils/gjs-bundle-guard.js';
+import { collectEntryPaths, describeJsxConfig, findJsxEntryPoint, jsxConfigMissingError } from '../utils/jsx-config.js';
 import { giSystemProbes } from '../utils/gi-runtime-paths.js';
 import { escapeRawNulForGjs } from '../utils/gjs-source-escape.js';
 import { assertNodeBundleGlobalsShimmed } from '../utils/node-bundle-guard.js';
@@ -149,6 +150,21 @@ export class BuildAction {
         const multipleBuilds = moduleOutdir && mainOutdir && moduleOutdir !== mainOutdir;
         const pnp = await buildPnpPlugin();
         const pnpPlugins = pnp ? [pnp] : [];
+        // The same chain `buildApp` assembles, and it was missing here entirely:
+        // a library build resolved NO user plugin and NO user text loader, then
+        // emitted the default transform at exit 0. Configuring
+        // `gjsify.bundler.plugins` and watching it do nothing is the repo's most
+        // expensive failure shape, and `@gjsify/gtk-host` itself builds with
+        // `--library` — which is where it was found.
+        const userTextLoader = textLoaderPlugin({ loaders: this.configData.loaders });
+        const userPlugins = userTextLoader ? [userTextLoader] : [];
+        if (userBundler.plugins?.length) {
+            // Under GJS a plugin module cannot always be imported directly — the
+            // native ESM loader does not follow `package.json#exports` — so the
+            // same bundle-then-import escape the app path uses is passed in here.
+            const resolved = await resolveUserPlugins(userBundler.plugins, process.cwd(), isGjs() ? { loadModule: (pth, name) => this.loadPluginViaGjsBundle(pth, name, verbose) } : {});
+            userPlugins.push(...resolved);
+        }
         const results = [];
         if (multipleBuilds) {
             // Both outdirs are derived from module/main — always guard them
@@ -168,6 +184,7 @@ export class BuildAction {
                 output: { dir: moduleOutdir },
                 userAliases: aliases,
                 pnpPlugins,
+                userPlugins,
             }));
             const mainFormat = mainOutdir.includes('/cjs') || mainOutExt === '.cjs' ? 'cjs' : 'esm';
             results.push(await runOneLibraryBuild({
@@ -182,6 +199,7 @@ export class BuildAction {
                 output: { dir: mainOutdir },
                 userAliases: aliases,
                 pnpPlugins,
+                userPlugins,
             }));
         }
         else {
@@ -207,6 +225,7 @@ export class BuildAction {
                 output: { dir: outdir },
                 userAliases: aliases,
                 pnpPlugins,
+                userPlugins,
             }));
         }
         return results;
@@ -375,10 +394,22 @@ export class BuildAction {
      * natively, `@gjsify/rolldown-native` via `synthRolldownOutput`), and it
      * cannot be fooled by a `node:` specifier quoted inside a string, which a
      * text scan cannot tell from a statement.
+     *
+     * The same list also answers the GENERAL form of the question — any bare
+     * specifier GJS cannot resolve, `node:` or not — which is why the target's
+     * externals predicate and the emitted fileNames are handed over: they are
+     * what separates a declared external and a sibling chunk from a dependency
+     * that simply is not there.
      */
-    assertGjsOutputLoadable(result, outfile, outdir) {
+    assertGjsOutputLoadable(result, outfile, outdir, userExternal) {
         const chunks = (result.output ?? []).filter((item) => item.type === 'chunk');
-        assertGjsBundleLoadable(chunks, outfile ?? outdir ?? 'the GJS bundle');
+        assertGjsBundleLoadable(chunks, outfile ?? outdir ?? 'the GJS bundle', {
+            // The target's OWN predicate, not a second list: `externalsPlugin` enforces
+            // this exact one, so a specifier the build let through as external cannot be
+            // reported as unresolvable here.
+            isExternal: createGjsExternalsPredicate(userExternal ?? []),
+            emitted: (result.output ?? []).map((item) => item.fileName),
+        });
     }
     /**
      * Post-bundle gate for `--app node`: throw when the emitted bundle still
@@ -544,6 +575,21 @@ export class BuildAction {
     async buildApp(app = 'gjs', opts = {}) {
         const { verbose, typescript, exclude, library: pkg, aliases, excludeGlobals } = this.configData;
         const userBundler = normalizeBundlerOptions(this.configData);
+        // Refuse a JSX entry with no JSX policy BEFORE bundling anything — see
+        // `utils/jsx-config.ts` for what the unset default emits and why it can never be
+        // right for this target. The glob expansion is paid only on the failing branch:
+        // when JSX is configured there is nothing to name.
+        const jsxPolicy = describeJsxConfig({
+            transformJsx: userBundler.transform?.jsx,
+            tsconfigJsx: typescript?.compilerOptions?.jsx,
+            tsconfigJsxImportSource: typescript?.compilerOptions?.jsxImportSource,
+        });
+        if (app === 'gjs' && !jsxPolicy.configured) {
+            const entries = collectEntryPaths(await globToEntryPoints(userBundler.input, exclude));
+            const jsxEntry = findJsxEntryPoint(entries);
+            if (jsxEntry !== undefined)
+                throw jsxConfigMissingError(jsxEntry);
+        }
         // --- `--app browser` HTML entry (Vite-style) ---
         // When the entry is an `index.html`, bundle the module its
         // `<script type="module" src>` references (rewrite `input` to that
@@ -584,7 +630,7 @@ export class BuildAction {
             throw new Error('gjsify build: an .html entry needs an explicit --outfile ' +
                 '(e.g. --outfile dist-app/app.js); the emitted index.html is written beside it.');
         }
-        const { consoleShim, globals } = this.configData;
+        const { consoleShim, globals, dialect } = this.configData;
         const userExternal = Array.isArray(userBundler.external) ? userBundler.external : undefined;
         const userBanner = typeof userBundler.output?.banner === 'string' ? userBundler.output.banner : undefined;
         const pluginOpts = {
@@ -594,6 +640,7 @@ export class BuildAction {
             exclude,
             reflection: typescript?.reflection,
             consoleShim,
+            ...(dialect !== undefined ? { dialect } : {}),
             ...(aliases ? { aliases } : {}),
             ...(opts.preserveDefaultExport ? { preserveDefaultExport: true } : {}),
             ...(opts.toolchainAnchor !== undefined ? { toolchainAnchor: opts.toolchainAnchor } : {}),
@@ -746,7 +793,7 @@ export class BuildAction {
             // 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],
+            plugins: [...pnpPlugins, ...cfg.prePlugins, ...userPlugins, ...cfg.plugins],
         };
         if (opts.watch) {
             await this.runWatchLoop(finalOpts, app, outfile, outdir, verbose);
@@ -762,9 +809,15 @@ export class BuildAction {
         if ((app === 'gjs' || app === 'node') && this.configData.shebang) {
             await this.applyShebang(app, outfile, verbose);
         }
-        // Refuse to hand back a `--app gjs` bundle stock GJS cannot even load.
+        // Refuse to hand back a `--app gjs` bundle stock GJS cannot even load: one that
+        // imports what the runtime cannot resolve, or — when the transform was told to
+        // keep JSX — one that is not parseable JavaScript at all.
         if (app === 'gjs') {
-            this.assertGjsOutputLoadable(writeResult, outfile, outdir);
+            this.assertGjsOutputLoadable(writeResult, outfile, outdir, userExternal);
+            if (jsxPolicy.preserves) {
+                const chunks = (writeResult.output ?? []).filter((item) => item.type === 'chunk');
+                assertGjsBundleParses(chunks, outfile ?? outdir ?? 'the GJS bundle');
+            }
         }
         // Refuse to hand back a `--app node` bundle that reaches for GJS ambient
         // globals nothing seeds. Only meaningful when the shim was NOT injected:
@@ -882,7 +935,11 @@ async function runOneLibraryBuild(args) {
     const merged = mergeBundlerOptions(cfg.options, args.userBundler);
     const finalOpts = {
         ...merged,
-        plugins: [...args.pnpPlugins, ...cfg.plugins],
+        // Same order as the app path: PnP resolves, then the user transforms,
+        // then gjsify's own chain. `merged.plugins` is deliberately NOT spread —
+        // the user's entries arrive RESOLVED, in `userPlugins`, exactly as
+        // `buildApp` passes them.
+        plugins: [...args.pnpPlugins, ...cfg.prePlugins, ...args.userPlugins, ...cfg.plugins],
     };
     return await runBundle(finalOpts);
 }

package/lib/commands/affected-classify.js

@@ -85,11 +85,13 @@ const IGNORE = [
     /^docs\//,
     ...OTHER_WORKFLOW_INPUTS,
     // Neither `@gjsify/node-gi` (the Node-native GI engine) nor `@gjsify/napi` (the
-    // N-API host over SpiderMonkey) is a gjsify workspace member: the GJS-first
-    // install/foreach tooling cannot build their node-gyp addons or Vala+C++/meson
-    // shim, so `main.yml` neither builds nor tests them and their own workflows are
-    // the source of truth. Without the carve-outs their files map to no workspace,
-    // land in `unmatched`, and force a full run on every node-gi/napi PR.
+    // N-API host over SpiderMonkey) is a gjsify workspace member — WHY is ADR 0031,
+    // which this comment used to carry alone. The short of it: node-gi's `build` is
+    // `node-gyp rebuild`, so a member would enter `foreach build` in a container with
+    // no GTK/GI toolchain. `main.yml` therefore neither builds nor tests them and
+    // their own workflows are the source of truth. Without the carve-outs their files
+    // map to no workspace, land in `unmatched`, and force a full run on every
+    // node-gi/napi PR.
     /^packages\/node-gi\//,
     /^packages\/napi\//,
     // Flatpak build/distribution tooling (SDK-extension manifest + metainfo). No

package/lib/commands/build.js

@@ -1,5 +1,6 @@
 import { Config } from '../config.js';
 import { BuildAction } from '../actions/build.js';
+import { SOURCE_DIALECTS } from '@gjsify/rolldown-plugin-gjsify';
 // NO `normalize: true` ON THE GLOB-BEARING OPTIONS — `entry-points` and
 // `exclude` are PATTERNS, not paths.
 //
@@ -106,6 +107,11 @@ export const buildCommand = {
             type: 'string',
             choices: ['silent', 'error', 'warning', 'info', 'debug', 'verbose'],
             default: 'warning',
+        })
+            .option('dialect', {
+            description: "The dialect the SOURCE is written in. 'react-native' aliases 'react-native' onto '@gjsify/react-native' and fails the build on an import whose ADR 0032 support-table status is not supported/partial. GJS and Node app builds. This is NOT gjsify.runtimes['react-native'], which declares the runtime a package RUNS on — the two answer opposite questions.",
+            type: 'string',
+            choices: [...SOURCE_DIALECTS],
         })
             .option('console-shim', {
             description: 'Inject a console shim into GJS builds for clean output without the GLib prefix and with working ANSI colors. Use --no-console-shim to disable. Only applies to GJS app builds.',

package/lib/commands/flatpak/ci.js

@@ -9,7 +9,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { Config } from '../../config.js';
-import { defaultCiContainer, looksLikeAppId, readPackageJson, resolveRuntime } from './utils.js';
+import { defaultCiContainer, looksLikeAppId, readPackageJson } from './utils.js';
+import { resolveRuntime } from '../../utils/flatpak-runtime.js';
+import { pickFlatpakBuildKeys } from '../../utils/ship/flatpak-config.js';
 export const flatpakCiCommand = {
     command: 'ci',
     description: 'Scaffold .github/workflows/flatpak.yml using the flathub-infra container + flatpak-builder@v6 action.',
@@ -68,7 +70,13 @@ export const flatpakCiCommand = {
         }
         const manifest = args.manifest ?? `${appId}.json`;
         const bundle = args.bundle ?? `${appId}.flatpak`;
-        const { runtime, runtimeVersion } = resolveRuntime(flatpak, {});
+        // Through the deprecation window, not straight off `gjsify.flatpak`: a
+        // project told to move these keys to `gjsify.ship.flatpak` must not lose
+        // them here — the CI container tag is derived from the runtime, so
+        // reading the old block alone scaffolds a workflow against the default
+        // GNOME release rather than the pinned one.
+        const buildKeys = pickFlatpakBuildKeys(configData.ship?.flatpak, flatpak).values;
+        const { runtime, runtimeVersion } = resolveRuntime(buildKeys, {});
         const runtimeImage = args.runtimeImage ??
             flatpak.ciContainer ??
             defaultCiContainer(runtime, runtimeVersion);

package/lib/commands/flatpak/init.js

@@ -13,7 +13,9 @@
 //     with `skip-icons-check`.
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { DEFAULT_CLI_FINISH_ARGS, DEFAULT_GUI_FINISH_ARGS, looksLikeAppId, readPackageJson, resolveRuntime, } from './utils.js';
+import { looksLikeAppId, readPackageJson } from './utils.js';
+import { DEFAULT_CLI_FINISH_ARGS, DEFAULT_GUI_FINISH_ARGS, deriveAppendPath, resolveRuntime, } from '../../utils/flatpak-runtime.js';
+import { pickFlatpakBuildKeys } from '../../utils/ship/flatpak-config.js';
 import { renderDesktop, renderFlathubJson, renderMetainfoApp, renderMetainfoCli, validateScaffoldInputs, } from './scaffold.js';
 import { Config } from '../../config.js';
 import { OxcNotFoundError, hasOxcDevDep, runOxfmt } from '../../utils/oxc-resolve.js';
@@ -109,17 +111,24 @@ export const flatpakInitCommand = {
                 'or rename the package to a reverse-DNS id like org.example.MyApp.');
         }
         const kind = args.kind ?? flatpak.kind ?? (args.cliOnly ? 'cli' : 'app');
-        const { runtime, runtimeId, sdk, runtimeVersion } = resolveRuntime(flatpak, {
+        // The six BUILD keys come through the deprecation window
+        // (`utils/ship/flatpak-config.ts`), not straight off `gjsify.flatpak`.
+        // These commands did NOT move, but the keys did: a project that followed
+        // `ship`'s own advice and moved them would otherwise lose them here and
+        // get a committed manifest against a different runtime version with
+        // different finish-args, silently, at exit 0.
+        const buildKeys = pickFlatpakBuildKeys(configData.ship?.flatpak, flatpak).values;
+        const { runtime, runtimeId, sdk, runtimeVersion } = resolveRuntime(buildKeys, {
             runtime: args.runtime,
             runtimeVersion: args.runtimeVersion,
         });
-        const sdkExtensions = mergeArrays(flatpak.sdkExtensions, args.sdkExtension);
-        const appendPath = flatpak.appendPath ?? (sdkExtensions?.length ? deriveAppendPath(sdkExtensions) : undefined);
+        const sdkExtensions = mergeArrays(buildKeys.sdkExtensions, args.sdkExtension);
+        const appendPath = buildKeys.appendPath ?? (sdkExtensions?.length ? deriveAppendPath(sdkExtensions) : undefined);
         const command = args.command ?? flatpak.command ?? appId;
         const explicitFinishArgs = args.finishArg;
         const finishArgs = explicitFinishArgs !== undefined
             ? explicitFinishArgs
-            : (flatpak.finishArgs ?? (kind === 'cli' ? DEFAULT_CLI_FINISH_ARGS : DEFAULT_GUI_FINISH_ARGS));
+            : (buildKeys.finishArgs ?? (kind === 'cli' ? DEFAULT_CLI_FINISH_ARGS : DEFAULT_GUI_FINISH_ARGS));
         const manifest = {
             id: appId,
             runtime: runtimeId,
@@ -133,7 +142,7 @@ export const flatpakInitCommand = {
         }
         manifest.command = command;
         manifest['finish-args'] = finishArgs;
-        const cleanup = flatpak.cleanup;
+        const cleanup = buildKeys.cleanup;
         if (cleanup?.length)
             manifest.cleanup = cleanup;
         // Module assembly. Two precedence rules:
@@ -253,16 +262,6 @@ function mergeArrays(a, b) {
         return undefined;
     return [...(a ?? []), ...(b ?? [])];
 }
-function deriveAppendPath(sdkExtensions) {
-    const out = [];
-    for (const ext of sdkExtensions) {
-        const m = /^org\.freedesktop\.Sdk\.Extension\.([A-Za-z0-9-]+)$/.exec(ext);
-        if (m)
-            out.push(`/usr/lib/sdk/${m[1]}/bin`);
-    }
-    out.push('/app/bin');
-    return out;
-}
 function deriveModuleName(appId) {
     const parts = appId.split('.');
     return parts[parts.length - 1] || appId;

package/lib/commands/flatpak/utils.d.ts

@@ -1,32 +1,6 @@
-import type { ConfigDataFlatpak } from '../../types/config-data.js';
-/**
- * Default GNOME-Platform runtime version. Bumped per release window.
- * GNOME 50 = April 2026 stable; tracked in
- * https://docs.flathub.org/docs/for-app-authors/requirements.
- */
-export declare const DEFAULT_GNOME_RUNTIME_VERSION = "50";
-/** Default Freedesktop-Platform runtime version (LTS-ish). */
-export declare const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = "24.08";
-/** Permissive GUI defaults for GTK4 + Adwaita apps. */
-export declare const DEFAULT_GUI_FINISH_ARGS: string[];
-/** Lean defaults for headless CLI tools — no display, no GPU. */
-export declare const DEFAULT_CLI_FINISH_ARGS: string[];
 /** Read package.json from a directory. Throws a helpful error if missing/invalid. */
 export declare function readPackageJson(dir: string): Record<string, unknown>;
 /** True if a name string looks like a reverse-DNS Flatpak app id. */
 export declare function looksLikeAppId(value: unknown): value is string;
-/**
- * Pick the runtime + sdk + version triple from config + CLI overrides.
- * `--runtime` and `--runtime-version` flags win over config values.
- */
-export declare function resolveRuntime(flatpak: ConfigDataFlatpak | undefined, overrides: {
-    runtime?: string;
-    runtimeVersion?: string;
-}): {
-    runtime: 'gnome' | 'freedesktop';
-    runtimeId: string;
-    sdk: string;
-    runtimeVersion: string;
-};
 /** Default container image for the GitHub Actions workflow. */
 export declare function defaultCiContainer(runtime: 'gnome' | 'freedesktop', runtimeVersion: string): string;

package/lib/commands/flatpak/utils.js

@@ -1,18 +1,10 @@
 // Shared helpers for the `gjsify flatpak <sub>` subcommand group.
+//
+// The runtime/SDK/finish-args half moved to `utils/flatpak-runtime.ts` when
+// `gjsify ship --target flatpak` became its second caller — see that file's
+// header. What is left here is what only these subcommands ask.
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-/**
- * Default GNOME-Platform runtime version. Bumped per release window.
- * GNOME 50 = April 2026 stable; tracked in
- * https://docs.flathub.org/docs/for-app-authors/requirements.
- */
-export const DEFAULT_GNOME_RUNTIME_VERSION = '50';
-/** Default Freedesktop-Platform runtime version (LTS-ish). */
-export const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = '24.08';
-/** Permissive GUI defaults for GTK4 + Adwaita apps. */
-export const DEFAULT_GUI_FINISH_ARGS = ['--device=dri', '--share=ipc', '--socket=fallback-x11', '--socket=wayland'];
-/** Lean defaults for headless CLI tools — no display, no GPU. */
-export const DEFAULT_CLI_FINISH_ARGS = [];
 /** Read package.json from a directory. Throws a helpful error if missing/invalid. */
 export function readPackageJson(dir) {
     const path = resolve(dir, 'package.json');
@@ -34,23 +26,6 @@ export function readPackageJson(dir) {
 export function looksLikeAppId(value) {
     return typeof value === 'string' && /^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z][A-Za-z0-9_-]*){2,}$/.test(value);
 }
-/**
- * Pick the runtime + sdk + version triple from config + CLI overrides.
- * `--runtime` and `--runtime-version` flags win over config values.
- */
-export function resolveRuntime(flatpak, overrides) {
-    const runtime = (overrides.runtime ?? flatpak?.runtime ?? 'gnome');
-    if (runtime !== 'gnome' && runtime !== 'freedesktop') {
-        throw new Error(`gjsify flatpak: unknown runtime "${runtime}" (expected "gnome" or "freedesktop")`);
-    }
-    const runtimeVersion = overrides.runtimeVersion ??
-        flatpak?.runtimeVersion ??
-        (runtime === 'gnome' ? DEFAULT_GNOME_RUNTIME_VERSION : DEFAULT_FREEDESKTOP_RUNTIME_VERSION);
-    if (runtime === 'gnome') {
-        return { runtime, runtimeId: 'org.gnome.Platform', sdk: 'org.gnome.Sdk', runtimeVersion };
-    }
-    return { runtime, runtimeId: 'org.freedesktop.Platform', sdk: 'org.freedesktop.Sdk', runtimeVersion };
-}
 /** Default container image for the GitHub Actions workflow. */
 export function defaultCiContainer(runtime, runtimeVersion) {
     const tag = `${runtime}-${runtimeVersion}`;

package/lib/commands/ship.d.ts

@@ -3,6 +3,8 @@ interface ShipOptions {
     target?: string[];
     out?: string;
     stage: boolean;
+    'from-stage'?: string;
+    'expect-target'?: string;
     'skip-build': boolean;
     arch?: string;
     verbose: boolean;