@gjsify/rolldown-plugin-gjsify 0.52.0 → 0.53.0

package/README.md

@@ -40,6 +40,17 @@ import {
 } from '@gjsify/rolldown-plugin-gjsify';
 ```
 
+## Native addons (`--app gjs`)
+
+A Node-API addon package (`bufferutil`, `better-sqlite3`, `lightningcss`, `@signalapp/libsignal-client`, …) is rewritten to `loadAddon()` from `@gjsify/napi`, which GJS cannot load by itself. On `--app node` the same packages stay external and keep resolving from `node_modules`.
+
+For a GJS build the bundle records the addon's **package identity**, not a path — see [ADR 0084](../../docs/adr/0084-an-addon-is-found-by-package-identity.md). Every `.node` the package ships is enumerated at build time, keyed by platform (`linux-x64`, `linux-x64-musl`, `darwin-arm64`, …), and the bundle picks the entry for the host it finds itself on when it loads. Consequences worth knowing:
+
+- The bundle is **relocatable** — move the output tree and it still loads its addon, because nothing names the machine that built it.
+- The addon **package** must be installed somewhere the bundle can reach (its own `node_modules`, or an `addons/<package>/` next to the bundle that no gjsify step fills yet). A single copied `.node` file is not enough; a `.node` that `dlopen`s a sibling library or reads a data file beside itself needs its directory.
+- A cross-build works when the target's binary is installed on the builder: a multi-platform npm package, or `gjsify install`, which materialises every platform package.
+- `runtimeResolve` (set from `format === 'esm'` by `gjsify build`) gates the whole mechanism: without the bundle-URL banner there is nothing to anchor on, so the rewrite is declined with a warning rather than emitting a path that would only be right on the build machine.
+
 ## License
 
 MIT

package/lib/app/browser.js

@@ -83,6 +83,7 @@ export const setupForBrowser = async (input) => {
             define: {
                 global: 'globalThis',
                 window: 'globalThis',
+                'process.env.NODE_ENV': '"production"',
             },
         },
         output: {

package/lib/app/gjs.js

@@ -19,6 +19,7 @@ import { globToEntryPoints } from '../utils/entry-points.js';
 import { nodeModulesPathRewritePlugin, getBundleDirFromOutput } from '../plugins/rewrite-node-modules-paths.js';
 import { processStubPlugin } from '../plugins/process-stub.js';
 import { cssAsStringPlugin } from '../plugins/css-as-string.js';
+import { consoleAssignPlugin } from '../plugins/console-assign.js';
 import { shebangPlugin, resolveShebangLine, inputShebangStripPlugin } from '../plugins/shebang.js';
 import { wrapInputWithSideEffects } from '../utils/entry-wrapper.js';
 const _shimDir = dirname(fileURLToPath(import.meta.url));
@@ -132,8 +133,13 @@ export const setupForGjs = async (input) => {
             target: 'firefox140',
             define: {
                 global: 'globalThis',
+                // An identity, unlike on `--app node` (ADR 0079): GJS itself defines `window`
+                // as a non-configurable alias of the global, so `typeof window` is 'object'
+                // with or without it. What a browser branch then calls on it comes from
+                // `dom-events/register/global-event-target` (`addEventListener` & co.).
                 window: 'globalThis',
                 'process.env.READABLE_STREAM': '"disable"',
+                'process.env.NODE_ENV': '"production"',
             },
             // Rewrite bare `console` to a named import from our shim. Rolldown's
             // `inject` (not a register-style global write) because GJS defines
@@ -182,6 +188,9 @@ export const setupForGjs = async (input) => {
         // banner, and acorn (the auto-globals detector) rejects the `#` byte.
         // The final-output shebang is composed by shebangPlugin's renderChunk.
         inputShebangStripPlugin(),
+        // A module assigning the global `console` gets a local binding, or the inject
+        // below turns its assignment into `ASSIGN_TO_IMPORT` and fails the build.
+        ...(consoleShimPath ? [consoleAssignPlugin()] : []),
         // Platform-file forks for the desktop, ADR 0032 § 9: `.gtk` → `.<os>` →
         // `.desktop` → base. BEFORE the alias layer, so a platform fork of a
         // module that also has a Node-builtin substitution wins over the
@@ -208,8 +217,11 @@ export const setupForGjs = async (input) => {
         // from `@gjsify/napi`, which is BUNDLED, not external. Order matters:
         // after aliasPlugin so a user alias pinning an addon's native entry wins,
         // before externalsPlugin so the acquisition is claimed first. Inert
-        // otherwise; `--app gjs` only.
-        napiNodeAddonPlugin(),
+        // otherwise; `--app gjs` only. `runtimeResolve` is the SAME `format ===
+        // 'esm'` gate the path rewriter below carries: the shim resolves the
+        // addon from the bundle's own URL, which only the ESM output's
+        // bundle-URL banner records (ADR 0084).
+        napiNodeAddonPlugin({ runtimeResolve: format === 'esm' }),
         // Externals policy as a resolveId hook — the only form BOTH engines
         // honour. Runs after the alias plugin's `pre` resolveId so aliases apply
         // first.

package/lib/app/nativescript.js

@@ -26,7 +26,7 @@
 // "this package IS the native implementation" sense and therefore promises a
 // `globals.mjs` it does not ship. The slot vocabulary's `native` means "the
 // RUNTIME provides this, use its value", so the bridge packages are
-// mis-declared; that is tracked in status/open-todos.md and must be settled
+// mis-declared; that is tracked in status/open-todos/README.md and must be settled
 // before this table is composed.
 //
 // Derived `@gjsify/<X>` entries are merged into the map below, so an import by

package/lib/app/node.d.ts

@@ -43,7 +43,7 @@ export declare function enableGjsRegistersForNode(baseAliases: Record<string, st
  * emptying both stay, so a cross-platform package's node bundle keeps loading on
  * plain Node without node-gi installed.
  *
- * KNOWN NARROWNESS (tracked in status/open-todos.md): a genuine GJS source whose
+ * KNOWN NARROWNESS (tracked in status/open-todos/README.md): a genuine GJS source whose
  * ONLY platform reach is `gi://` (no ambient global, no bare built-in) is not
  * recognised — its `@girs/*` and its registers are both emptied. A surviving
  * `gi://` import cannot simply become a third signal: its shim loads node-gi

package/lib/app/node.js

@@ -11,6 +11,7 @@ import { cssAsStringPlugin } from '../plugins/css-as-string.js';
 import { gjsImportsEmptyPlugin } from '../plugins/gjs-imports-empty.js';
 import { gjsGiNodePlugin, gjsBuiltinModulesNodePlugin } from '../plugins/gjs-gi-node.js';
 import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
+import { nodeNativeExternalPlugin } from '../plugins/node-native-external.js';
 import { platformResolvePlugin, desktopSuffixChain, desktopOsSuffix, DESKTOP_REFUSED_SUFFIXES, } from '../plugins/platform-resolve.js';
 import { reactNativeAliasPlugin } from '../plugins/react-native-alias.js';
 import { reactNativeSupportGatePlugin } from '../plugins/react-native-gate.js';
@@ -178,7 +179,7 @@ export function enableGjsRegistersForNode(baseAliases) {
  * emptying both stay, so a cross-platform package's node bundle keeps loading on
  * plain Node without node-gi installed.
  *
- * KNOWN NARROWNESS (tracked in status/open-todos.md): a genuine GJS source whose
+ * KNOWN NARROWNESS (tracked in status/open-todos/README.md): a genuine GJS source whose
  * ONLY platform reach is `gi://` (no ambient global, no bare built-in) is not
  * recognised — its `@girs/*` and its registers are both emptied. A surviving
  * `gi://` import cannot simply become a third signal: its shim loads node-gi
@@ -192,9 +193,9 @@ export function isGjsSourceBuild(options) {
 }
 export const setupForNode = async (input) => {
     const userExternal = input.userExternal ?? [];
-    // node-datachannel and `@gjsify/node-gi` are native addons that cannot be
-    // bundled — their loaders resolve a `.node` binary relative to their own
-    // installed location, so both must stay external.
+    // `@gjsify/node-gi` stays external by name: the injected globals shim and the
+    // bare-module specifiers below name it before any package is resolved. Every
+    // other native addon package is found by `nodeNativeExternalPlugin`.
     //
     // GJS-specific specifiers (`gi://*`, `@girs/*`) are deliberately NOT
     // externalised: `gjsGiNodePlugin` rewrites `gi://` to `requireGi`, and
@@ -204,7 +205,6 @@ export const setupForNode = async (input) => {
     // `ERR_UNSUPPORTED_ESM_URL_SCHEME`.
     const exactExternal = [
         ...EXTERNALS_NODE,
-        'node-datachannel',
         '@gjsify/node-gi',
         '@gjsify/node-gi/gi',
         NODE_GI_GLOBALS_SPECIFIER,
@@ -275,16 +275,28 @@ export const setupForNode = async (input) => {
         external: exactExternal,
         resolve: {
             mainFields: format === 'esm' ? ['module', 'main', 'browser'] : ['main', 'module', 'browser'],
-            // CJS-priority conditions. Rolldown takes the package's first matching
-            // key, so adding 'import' would route ws v8 (which lists 'import'
-            // before 'require') through its incomplete ESM wrapper.
-            conditionNames: format === 'esm' ? ['require', 'node', 'module'] : ['require'],
+            // Neither 'import' nor 'require' on the esm build: rolldown adds the one
+            // matching each call site's kind, as Node's resolver does. Listing 'require'
+            // made every `import` take the CJS build wherever a package declares
+            // `require` first — `import basex from 'base-x'` then bound
+            // `module.exports` as the default and threw "(0, x.default) is not a
+            // function" at load, while the same source ran on Node. `--app gjs` lost
+            // the pinned 'import' for the mirror bug (#1130). 'module' is not a
+            // condition Node knows, and a require() would take it wherever a package
+            // lists it before 'require'.
+            conditionNames: format === 'esm' ? ['node'] : ['require'],
         },
         transform: {
             target: 'node24',
             define: {
                 global: 'globalThis',
-                window: 'globalThis',
+                // NO `window` define (ADR 0079): Node has none, and a bundle must see the same
+                // `typeof window` as its source run. A reverse-bridge DOM app gets `window`
+                // from @gjsify/dom-elements/register/document, which defines it at runtime.
+                // NO `process.env.NODE_ENV` define either, unlike gjs/browser (#1355): Node
+                // has a real `process.env`, so a Node bundle reads NODE_ENV at run time like
+                // its source does. Baking "production" in selected React's production build,
+                // which has no `act`, in every `--app node` test bundle.
             },
         },
         output: {
@@ -352,6 +364,10 @@ export const setupForNode = async (input) => {
         // externals policy — a redirect after `externalsPlugin` would find the
         // specifier already externalised.
         ...(input.pluginOptions.dialect === 'react-native' ? [reactNativeAliasPlugin()] : []),
+        // Node-API addon packages stay external so Node loads their `.node` from
+        // `node_modules` (see the plugin header). Resolves THROUGH the alias layer
+        // (`this.resolve`), so an aliased specifier is judged by where it lands.
+        nodeNativeExternalPlugin(),
         aliasPlugin({ entries: aliasEntries }),
         // Blueprint (.blp → XML string): the reverse bridge runs REAL GTK on Node,
         // so a GJS app entry with composite-template windows must build for

package/lib/index.d.ts

@@ -6,6 +6,7 @@ export { REWRITE_FILTER, extractPackageSpec, getBundleDirFromOutput, rewriteCont
 export type { NodeModulesPathRewriteOptions, RewriteResult } from './plugins/rewrite-node-modules-paths.js';
 export { processStubPlugin, GJS_PROCESS_STUB, composeBanner } from './plugins/process-stub.js';
 export { giRuntimePathsStub } from './plugins/gi-runtime-paths.js';
+export { bindConsoleLocally, consoleAssignPlugin, freeConsoleAssignmentInsertion, CONSOLE_LOCAL_BINDING, } from './plugins/console-assign.js';
 export type { GiSystemProbe } from './plugins/gi-runtime-paths.js';
 export type { ProcessStubPluginOptions } from './plugins/process-stub.js';
 export { cssAsStringPlugin } from './plugins/css-as-string.js';
@@ -20,8 +21,9 @@ export { externalsPlugin } from './plugins/externals.js';
 export type { ExternalsPredicate, ExternalsPluginOptions } from './plugins/externals.js';
 export { unresolvedWorkspaceImportPlugin, classifyImport, isWorkspaceSpecifier, formatUnresolvedWorkspaceImport, buildReverseAliasIndex, UnresolvedWorkspaceImportError, } from './plugins/unresolved-workspace-import.js';
 export type { WorkspaceImportGuardOptions, WorkspaceImportGuardTarget, ImportVerdict, ClassifyImportInput, UnresolvedWorkspaceImportDetails, } from './plugins/unresolved-workspace-import.js';
-export { napiNodeAddonPlugin, resolveAddonPath, nearestPackageRoot, classifySpecifier, directNodeShim, nodeGypBuildShim, bindingsShim, napiRsShim, ADDON_FILTER_RE, isNapiRsPackageJson, isNapiRsSibling, isGjsifyNativeBridge, detectNapiRsEntry, hostNapiRsTriple, AddonNotBuiltError, } from './plugins/napi-node-addon.js';
+export { napiNodeAddonPlugin, resolveAddonPath, enumerateAddonTargets, nearestPackageRoot, classifySpecifier, directNodeShim, nodeGypBuildShim, bindingsShim, napiRsShim, ADDON_FILTER_RE, isNapiRsPackageJson, isNapiRsSibling, isGjsifyNativeBridge, detectNapiRsEntry, hostNapiRsTriple, AddonNotBuiltError, } from './plugins/napi-node-addon.js';
 export type { NapiNodeAddonPluginOptions, AddonPackageJson } from './plugins/napi-node-addon.js';
+export { nodeNativeExternalPlugin, isNodeAddonPackage, packageNameOf } from './plugins/node-native-external.js';
 export { platformResolvePlugin, nativescriptSuffixChain, desktopSuffixChain, browserSuffixChain, desktopOsSuffix, DESKTOP_OS_SUFFIXES, DESKTOP_REFUSED_SUFFIXES, BROWSER_REFUSED_SUFFIXES, PlatformVariantExternalError, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.js';
 export type { PlatformResolvePluginOptions, NativescriptPlatform } from './plugins/platform-resolve.js';
 export { rnRouteManifestPlugin, renderRouteManifest, walkRoutes, RouteManifestError, RN_ROUTES_MODULE_ID, MAX_ROUTE_DEPTH, } from './plugins/rn-route-manifest.js';

package/lib/index.js

@@ -6,6 +6,7 @@ export * from './library/index.js';
 export { REWRITE_FILTER, extractPackageSpec, getBundleDirFromOutput, rewriteContents, shouldRewrite, shouldInline, nodeModulesPathRewritePlugin, } from './plugins/rewrite-node-modules-paths.js';
 export { processStubPlugin, GJS_PROCESS_STUB, composeBanner } from './plugins/process-stub.js';
 export { giRuntimePathsStub } from './plugins/gi-runtime-paths.js';
+export { bindConsoleLocally, consoleAssignPlugin, freeConsoleAssignmentInsertion, CONSOLE_LOCAL_BINDING, } from './plugins/console-assign.js';
 export { cssAsStringPlugin } from './plugins/css-as-string.js';
 export { textLoaderPlugin } from './plugins/text-loader.js';
 export { shebangPlugin, GJS_SHEBANG, NODE_SHEBANG, expandEnvTemplate, resolveShebangLine } from './plugins/shebang.js';
@@ -13,7 +14,8 @@ export { aliasPlugin } from './plugins/alias.js';
 export { gjsImportsEmptyPlugin } from './plugins/gjs-imports-empty.js';
 export { externalsPlugin } from './plugins/externals.js';
 export { unresolvedWorkspaceImportPlugin, classifyImport, isWorkspaceSpecifier, formatUnresolvedWorkspaceImport, buildReverseAliasIndex, UnresolvedWorkspaceImportError, } from './plugins/unresolved-workspace-import.js';
-export { napiNodeAddonPlugin, resolveAddonPath, nearestPackageRoot, classifySpecifier, directNodeShim, nodeGypBuildShim, bindingsShim, napiRsShim, ADDON_FILTER_RE, isNapiRsPackageJson, isNapiRsSibling, isGjsifyNativeBridge, detectNapiRsEntry, hostNapiRsTriple, AddonNotBuiltError, } from './plugins/napi-node-addon.js';
+export { napiNodeAddonPlugin, resolveAddonPath, enumerateAddonTargets, nearestPackageRoot, classifySpecifier, directNodeShim, nodeGypBuildShim, bindingsShim, napiRsShim, ADDON_FILTER_RE, isNapiRsPackageJson, isNapiRsSibling, isGjsifyNativeBridge, detectNapiRsEntry, hostNapiRsTriple, AddonNotBuiltError, } from './plugins/napi-node-addon.js';
+export { nodeNativeExternalPlugin, isNodeAddonPackage, packageNameOf } from './plugins/node-native-external.js';
 export { platformResolvePlugin, nativescriptSuffixChain, desktopSuffixChain, browserSuffixChain, desktopOsSuffix, DESKTOP_OS_SUFFIXES, DESKTOP_REFUSED_SUFFIXES, BROWSER_REFUSED_SUFFIXES, PlatformVariantExternalError, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.js';
 export { rnRouteManifestPlugin, renderRouteManifest, walkRoutes, RouteManifestError, RN_ROUTES_MODULE_ID, MAX_ROUTE_DEPTH, } from './plugins/rn-route-manifest.js';
 export { reactNativeAliasPlugin, classifyReactNativeSpecifier, couldBeSurfaceSpecifier, loadLayer, FALLBACK_SURFACES, REACT_NATIVE_ALIAS_TARGET, REACT_NATIVE_SPECIFIER, ReactNativeDeepImportError, ReactNativeAliasTargetMissingError, SURFACE_MENTION, SURFACE_NAME_PREFIXES, } from './plugins/react-native-alias.js';

package/lib/plugins/console-assign.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from 'rolldown';
+export declare const CONSOLE_LOCAL_BINDING = "var console = globalThis.console;";
+/**
+ * Where to insert the local binding in `code`, or null when the module does not assign
+ * the GLOBAL `console`. Null as well when the module declares a `console` anywhere: its
+ * assignments may target that binding, and declaring a second one would not parse.
+ * The offset is after the directive prologue, so a `'use strict'` stays a directive.
+ */
+export declare function freeConsoleAssignmentInsertion(code: string): number | null;
+/** `code` with the local `console` binding inserted, or null when it needs none. */
+export declare function bindConsoleLocally(code: string): string | null;
+/** Composed by `--app gjs` whenever the console shim is injected. */
+export declare function consoleAssignPlugin(): Plugin;

package/lib/plugins/console-assign.js

@@ -0,0 +1,125 @@
+// Give a module that ASSIGNS the global `console` a local binding of its own, so the
+// `--app gjs` console `inject` leaves it alone.
+//
+// `--app gjs` rewrites every free `console` into an import from `shims/console-gjs`
+// (rolldown `transform.inject`), because GJS defines `globalThis.console` non-writable
+// and non-configurable. An import binding cannot be assigned, so ONE sloppy-mode
+// `console = { log() {} }` anywhere in the dependency graph failed the whole build with
+// `ASSIGN_TO_IMPORT: Cannot assign to import 'console'`. Measured: `node-forge`'s
+// `lib/log.js` does exactly that on its browser-without-console branch, and it reaches
+// `wxt` through `web-ext`, so `gjsify exec wxt` could not be rebuilt at all.
+//
+// The binding is `var console = globalThis.console`: the module keeps working with the
+// runtime's console, and its assignment lands on its own variable — which is all a
+// sloppy-mode write to a non-writable global ever did under GJS. Only such a module
+// gives up the shim's print()-based output; every other module is untouched.
+//
+// Detection is an AST question (a parameter or a `const console` is a binding, not an
+// assignment to the global), asked only of sources the cheap pattern admits.
+import * as acorn from 'acorn';
+import * as walk from 'acorn-walk';
+import { extractBindingNames } from '../utils/detect-free-globals.js';
+const CANDIDATE_RE = /(?:^|[^.\w$])console\s*=(?![=>])/;
+const SOURCE_RE = /\.(?:m|c)?jsx?$/;
+export const CONSOLE_LOCAL_BINDING = 'var console = globalThis.console;';
+function parse(code) {
+    const base = { ecmaVersion: 'latest', allowHashBang: true, allowAwaitOutsideFunction: true };
+    try {
+        return acorn.parse(code, { ...base, sourceType: 'module' });
+    }
+    catch {
+        // Sloppy CJS (the node-forge case: `with`, legacy octals, top-level `return`)
+        // is not a valid module; the script grammar is the one it was written in.
+    }
+    try {
+        return acorn.parse(code, { ...base, sourceType: 'script', allowReturnOutsideFunction: true });
+    }
+    catch {
+        // Not JavaScript acorn can read (a syntax newer than acorn): leave it to the
+        // bundler, which reports an assignment it cannot bundle loudly on its own.
+        return null;
+    }
+}
+/**
+ * Where to insert the local binding in `code`, or null when the module does not assign
+ * the GLOBAL `console`. Null as well when the module declares a `console` anywhere: its
+ * assignments may target that binding, and declaring a second one would not parse.
+ * The offset is after the directive prologue, so a `'use strict'` stays a directive.
+ */
+export function freeConsoleAssignmentInsertion(code) {
+    if (!CANDIDATE_RE.test(code))
+        return null;
+    const ast = parse(code);
+    if (!ast)
+        return null;
+    let declares = false;
+    let assigns = false;
+    const bindsConsole = (node) => !!node && extractBindingNames(node).includes('console');
+    walk.full(ast, (node) => {
+        switch (node.type) {
+            case 'VariableDeclarator':
+                if (bindsConsole(node.id))
+                    declares = true;
+                break;
+            case 'FunctionDeclaration':
+            case 'FunctionExpression':
+            case 'ArrowFunctionExpression':
+                if (bindsConsole(node.id) || node.params.some((p) => bindsConsole(p)))
+                    declares = true;
+                break;
+            case 'ClassDeclaration':
+            case 'ClassExpression':
+                if (bindsConsole(node.id))
+                    declares = true;
+                break;
+            case 'CatchClause':
+                if (bindsConsole(node.param))
+                    declares = true;
+                break;
+            case 'ImportSpecifier':
+            case 'ImportDefaultSpecifier':
+            case 'ImportNamespaceSpecifier':
+                if (node.local.name === 'console')
+                    declares = true;
+                break;
+            case 'AssignmentExpression':
+                if (bindsConsole(node.left))
+                    assigns = true;
+                break;
+        }
+    });
+    if (!assigns || declares)
+        return null;
+    let offset = 0;
+    for (const statement of ast.body) {
+        if (statement.type !== 'ExpressionStatement' || !('directive' in statement))
+            break;
+        offset = statement.end;
+    }
+    return offset;
+}
+/** `code` with the local `console` binding inserted, or null when it needs none. */
+export function bindConsoleLocally(code) {
+    const at = freeConsoleAssignmentInsertion(code);
+    if (at === null)
+        return null;
+    // No newline, so every later line keeps its number; after a directive the `;` ends
+    // it even when the source relied on ASI (`'use strict'\n`).
+    const sep = at === 0 ? '' : ';';
+    return `${code.slice(0, at)}${sep}${CONSOLE_LOCAL_BINDING}${code.slice(at)}`;
+}
+/** Composed by `--app gjs` whenever the console shim is injected. */
+export function consoleAssignPlugin() {
+    return {
+        name: 'gjsify-console-assign',
+        transform: {
+            filter: { id: SOURCE_RE },
+            handler(code, id) {
+                if (!SOURCE_RE.test(id))
+                    return null;
+                const out = bindConsoleLocally(code);
+                return out === null ? null : { code: out, map: null };
+            },
+        },
+    };
+}