@gjsify/cli 0.44.0 → 0.45.0

package/lib/utils/resolve-npm-package.d.ts

@@ -14,3 +14,59 @@ export interface ResolveNpmPackageOptions {
  * `pathToFileURL().href` before a dynamic `import(...)`.
  */
 export declare function resolveNpmPackage(specifier: string, opts?: ResolveNpmPackageOptions): string | null;
+/**
+ * The anchor a resolution was asked from — see {@link resolveInstalledPackage}.
+ *
+ * `'nowhere'` is a directory inside no project. Under Node it can only fail;
+ * under Bun it is where the sixth anchor shows itself.
+ */
+export type PackageAnchor = 'project' | 'nowhere';
+export interface ResolveInstalledPackageOptions extends ResolveNpmPackageOptions {
+    /**
+     * TEST SEAM — resolve `specifier` from one anchor, or `null`.
+     *
+     * Injected so Bun's behaviour below is reproducible from Node: a fake that
+     * answers the SAME path for both anchors is exactly what Bun does for a
+     * package the project never installed, and it is the only way to red this
+     * guard on a runtime that does not have the defect.
+     */
+    resolve?: (specifier: string, anchor: PackageAnchor) => string | null;
+}
+/**
+ * Resolve a bare specifier the way {@link resolveNpmPackage} does, but refuse an
+ * answer the RUNTIME invented rather than the project provided.
+ *
+ * THE SIXTH ANCHOR, which the list above does not mention because it is not
+ * ours. Bun auto-installs: `createRequire(<anchor>).resolve('<name>')` falls back
+ * to Bun's global install cache instead of throwing, so a package the project
+ * never declared resolves anyway. Measured, bun 1.3.14 vs node 24.19.0, asking
+ * for `@gjsify/node-gi` from a scratch directory:
+ *
+ *     node  →  MODULE_NOT_FOUND
+ *     bun   →  ~/.bun/install/cache/@gjsify/node-gi@0.44.0@@@1/index.js
+ *
+ * And it is not only the empty-directory case. A real project with a
+ * `package.json` and no `node_modules` — a fresh clone, or any Bun project
+ * relying on auto-install — gets the same cache hit, as does one that DECLARES
+ * the dependency without installing it. Only a `package.json` beside an EMPTY
+ * `node_modules` throws.
+ *
+ * WHY THAT MATTERS HERE AND NOT FOR {@link resolveNpmPackage}'s other callers.
+ * Resolving `rolldown` from a cache is fine: it is a TOOL, it runs and is
+ * forgotten. `@gjsify/node-gi`, `@gjsify/gtk-runtime-*` and
+ * `@gjsify/node-runtime-*` are PAYLOAD — `utils/ship/app-runtime.ts` copies
+ * their bytes into a `.app` that gets redistributed. A cache hit there ships
+ * files the project never declared, at whatever version that runtime happened to
+ * cache, and silently: the "install `<name>`" line that should have been printed
+ * never is. It is also #910's shape one level up, an addon paired with a closure
+ * it was not built against.
+ *
+ * THE DISCRIMINATOR IS A CONTROL, not a list of cache paths. Hardcoding
+ * `~/.bun/install/cache` would be this file guessing at another runtime's
+ * layout and going stale the first time Bun moves it. Asking the same question
+ * from a directory inside no project asks the RUNTIME instead: if both anchors
+ * answer with the identical path, the project contributed nothing to that
+ * answer. Under Node the control can only throw, so this is a strict no-op
+ * there — the resolution it returns is byte-identical to `resolveNpmPackage`'s.
+ */
+export declare function resolveInstalledPackage(specifier: string, opts?: ResolveInstalledPackageOptions): string | null;

package/lib/utils/resolve-npm-package.js

@@ -23,6 +23,7 @@
 // (parent-dir walker).
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
+import { tmpdir } from 'node:os';
 import { delimiter, join, resolve } from 'node:path';
 import { findWorkspaceRoot } from './workspace-root.js';
 /**
@@ -92,3 +93,71 @@ function tryResolveFromDir(specifier, dir) {
         return null;
     }
 }
+/**
+ * A directory that is inside no project, for the control probe.
+ *
+ * It does not have to EXIST — measured under bun 1.3.14, a non-existent path
+ * still reaches the cache, so this costs no filesystem access. It must have a
+ * parent, though: an anchor at the filesystem root (`/__r__.js`) throws even
+ * under Bun, which would make the control silently useless.
+ */
+const CONTROL_ANCHOR = join(tmpdir(), '.gjsify-nonexistent-control-anchor', '__gjsify_resolve__.js');
+/**
+ * Resolve a bare specifier the way {@link resolveNpmPackage} does, but refuse an
+ * answer the RUNTIME invented rather than the project provided.
+ *
+ * THE SIXTH ANCHOR, which the list above does not mention because it is not
+ * ours. Bun auto-installs: `createRequire(<anchor>).resolve('<name>')` falls back
+ * to Bun's global install cache instead of throwing, so a package the project
+ * never declared resolves anyway. Measured, bun 1.3.14 vs node 24.19.0, asking
+ * for `@gjsify/node-gi` from a scratch directory:
+ *
+ *     node  →  MODULE_NOT_FOUND
+ *     bun   →  ~/.bun/install/cache/@gjsify/node-gi@0.44.0@@@1/index.js
+ *
+ * And it is not only the empty-directory case. A real project with a
+ * `package.json` and no `node_modules` — a fresh clone, or any Bun project
+ * relying on auto-install — gets the same cache hit, as does one that DECLARES
+ * the dependency without installing it. Only a `package.json` beside an EMPTY
+ * `node_modules` throws.
+ *
+ * WHY THAT MATTERS HERE AND NOT FOR {@link resolveNpmPackage}'s other callers.
+ * Resolving `rolldown` from a cache is fine: it is a TOOL, it runs and is
+ * forgotten. `@gjsify/node-gi`, `@gjsify/gtk-runtime-*` and
+ * `@gjsify/node-runtime-*` are PAYLOAD — `utils/ship/app-runtime.ts` copies
+ * their bytes into a `.app` that gets redistributed. A cache hit there ships
+ * files the project never declared, at whatever version that runtime happened to
+ * cache, and silently: the "install `<name>`" line that should have been printed
+ * never is. It is also #910's shape one level up, an addon paired with a closure
+ * it was not built against.
+ *
+ * THE DISCRIMINATOR IS A CONTROL, not a list of cache paths. Hardcoding
+ * `~/.bun/install/cache` would be this file guessing at another runtime's
+ * layout and going stale the first time Bun moves it. Asking the same question
+ * from a directory inside no project asks the RUNTIME instead: if both anchors
+ * answer with the identical path, the project contributed nothing to that
+ * answer. Under Node the control can only throw, so this is a strict no-op
+ * there — the resolution it returns is byte-identical to `resolveNpmPackage`'s.
+ */
+export function resolveInstalledPackage(specifier, opts = {}) {
+    const resolve = opts.resolve ??
+        ((spec, anchor) => anchor === 'project'
+            ? resolveNpmPackage(spec, { cwd: opts.cwd, bundleUrl: opts.bundleUrl })
+            : tryResolveFromFile(spec, CONTROL_ANCHOR));
+    const hit = resolve(specifier, 'project');
+    if (hit === null)
+        return null;
+    const control = resolve(specifier, 'nowhere');
+    return control !== null && control === hit ? null : hit;
+}
+/** `createRequire(<file>).resolve(specifier)`, or `null`. The file need not exist. */
+function tryResolveFromFile(specifier, anchorFile) {
+    try {
+        return createRequire(pathToFileURL(anchorFile).href).resolve(specifier);
+    }
+    catch {
+        // Not resolvable from a directory in no project — which is the answer
+        // this probe wants on every runtime without a global-cache fallback.
+        return null;
+    }
+}

package/lib/utils/ship/app-runtime.d.ts

@@ -0,0 +1,214 @@
+import type { Layout, LayoutIdentity } from './layout.js';
+import { type ResolveInstalledPackageOptions } from '../resolve-npm-package.js';
+import type { StagedFile } from './types.js';
+/**
+ * The targets a relocated GTK closure is published for.
+ *
+ * The same three `@gjsify/gtk-runtime-*` packages node-gi resolves, and
+ * deliberately NOT derived from {@link NODE_RUNTIME_TARGETS}: the two lists agree
+ * today by coincidence of which platforms lack a dependable system stack, and
+ * deriving one from the other would make a future Linux GTK bundle silently imply
+ * a bundled Linux interpreter (which `node-runtime.ts` refuses on purpose).
+ */
+export declare const GTK_RUNTIME_TARGETS: readonly ["darwin-arm64", "darwin-x64", "win32-x64"];
+export type GtkRuntimeTarget = (typeof GTK_RUNTIME_TARGETS)[number];
+/** Is this `<platform>-<arch>` one of the published GTK-closure targets? */
+export declare function isGtkRuntimeTarget(target: string): target is GtkRuntimeTarget;
+/** The npm name carrying the relocated closure for a target. One spelling, derived. */
+export declare function gtkRuntimePackageName(target: GtkRuntimeTarget): string;
+/** The addon's filename, node-gi's `ADDON_FILENAME`. Identical in every prebuild. */
+export declare const NODE_GI_ADDON_FILENAME = "node_gi.node";
+/** The package whose `prebuilds/<target>/` holds the addon and, in CI, the closure beside it. */
+export declare const NODE_GI_PACKAGE = "@gjsify/node-gi";
+/** Where the relocated GTK closure is, once found. */
+export interface ResolvedGtkRuntime {
+    /** What produced the hit — an env var name, or the npm name it was resolved from. */
+    source: string;
+    /** The bundle directory: the one holding `lib/`, `girepository-1.0/`, `share/`. */
+    dir: string;
+    /** `<dir>/lib` on darwin, `<dir>/bin` on win32 — the loadable-code directory. */
+    libDir: string;
+    /** `<dir>/girepository-1.0`. */
+    typelibDir: string;
+}
+/** Where the node-gi addon is, once found. */
+export interface ResolvedNodeGiAddon {
+    /** The npm name it was resolved from. */
+    source: string;
+    /** Absolute path to `node_gi.node`. */
+    addonPath: string;
+}
+export interface ResolveRuntimeOptions {
+    /** Project directory to resolve from — the consumer's, not gjsify's. */
+    cwd?: string;
+    /** Environment to read the overrides from. Injected so it is testable. */
+    env?: Record<string, string | undefined>;
+    /**
+     * TEST SEAM, passed through to {@link resolveInstalledPackage} — resolve a
+     * specifier from one anchor. A fake answering the SAME path for both anchors
+     * is Bun's global-cache behaviour, which is otherwise unreachable from Node.
+     */
+    resolve?: ResolveInstalledPackageOptions['resolve'];
+}
+/**
+ * Locate the relocated GTK closure for `target`, or `null`.
+ *
+ * The search order MIRRORS `resolveGtkRuntimeBundle()` rather than inventing a
+ * second one, because the two have to agree: this function decides what gets
+ * copied into the bundle, and that function decides what the bundle finds at
+ * runtime. Four candidates, first complete hit wins:
+ *
+ *  1. `GJSIFY_GTK_RUNTIME` — an explicit bundle directory, for a maintainer
+ *     holding an unpublished or patched closure. The same variable the launcher
+ *     later EXPORTS, and the same precedence it has there.
+ *  2. `@gjsify/node-gi`'s own `prebuilds/<target>/gtk`. This is the layout the
+ *     macOS CI legs stage by hand (`node-gi.yml`: download the bundle artifact
+ *     into `prebuilds/darwin-<arch>/gtk`, the addon beside it), so a job that has
+ *     prepared node-gi for a conformance run has, by that act alone, prepared it
+ *     for a ship run.
+ *  3. the sibling monorepo directory `../gtk-runtime-<target>/gtk`, which is what
+ *     an in-repo `npm run build:bundle` writes.
+ *  4. the published `@gjsify/gtk-runtime-<target>` package's `gtk/`.
+ *
+ * A candidate counts only when it holds BOTH the loadable-code directory and the
+ * typelib directory — node-gi's own probe, restated here rather than weakened,
+ * because a directory that passes here and fails there is a `.app` that ships
+ * 200 MB and still cannot open a window.
+ */
+export declare function resolveGtkRuntime(target: GtkRuntimeTarget, options?: ResolveRuntimeOptions): ResolvedGtkRuntime | null;
+/**
+ * Locate the node-gi addon built for `target`, or `null`.
+ *
+ * ONE source, and no override. The addon and the closure ship as a matched pair —
+ * the addon's `@rpath` is `@loader_path/gtk/lib`, so it names the very directory
+ * the closure occupies — and `@gjsify/node-gi` publishes `prebuilds/` for all five
+ * of its platforms in ONE package, so resolving the package by name is already
+ * enough to reach a foreign target's binary from a Linux host. A second
+ * environment knob here would be a way to pair an addon with a closure it was not
+ * built against, which is #910's failure shape wearing a convenience.
+ */
+export declare function resolveNodeGiAddon(target: GtkRuntimeTarget, options?: ResolveRuntimeOptions): ResolvedNodeGiAddon | null;
+/** node-gi's JavaScript, as package-relative paths. */
+export interface ResolvedNodeGiPackage {
+    source: string;
+    /** The package root the files are relative to. */
+    root: string;
+    /** POSIX-separated, package-relative — `package.json`, the root `.js`, `overrides/**`. */
+    files: string[];
+}
+/**
+ * The files a SHIPPED `.app` needs from `@gjsify/node-gi`, or `null`.
+ *
+ * NOT the published tarball. `files` in node-gi's manifest also lists `src/`,
+ * `binding.gyp` and `scripts/install.mjs` — the inputs to `node-gyp`, which a
+ * `.app` never runs — and the `.d.ts` declarations, which nothing inside a bundle
+ * compiles against. And it lists `prebuilds/`, which this module stages into
+ * `Contents/Frameworks` instead, where a `.app` keeps loadable code.
+ *
+ * So the rule is what `require('@gjsify/node-gi/<subpath>')` can REACH:
+ * `package.json` (the `exports` map is what resolves every subpath), every `.js`
+ * at the package root (every `exports` target is one), and `overrides/`, which
+ * `gi.js` loads at runtime. `tests/e2e/ship-macos` holds that rule against the
+ * REAL package's `exports` map, so a node-gi release that adds an entry outside
+ * this set fails there rather than in a `.app` a stranger downloaded.
+ */
+export declare function resolveNodeGiPackage(options?: ResolveRuntimeOptions): ResolvedNodeGiPackage | null;
+/**
+ * Where each piece of the runtime lands inside the bundle — STAGE-relative.
+ *
+ * PURE, and derived from `Layout.dirs` rather than from a second set of string
+ * literals, so the paths the launcher exports and the paths the stager writes
+ * cannot drift: they are computed here once and both callers read this result.
+ *
+ * `Contents/Frameworks/node-gi/prebuilds/<target>/` is node-gi's OWN sibling
+ * layout reproduced verbatim inside `dirs.native`. It is not a naming preference:
+ * `resolveGtkRuntimeBundle()` probes `<dir>/lib` and `<dir>/girepository-1.0`,
+ * the addon's `@rpath` is `@loader_path/gtk/lib`, and `loaders.cache` addresses
+ * each pixbuf loader relative to the bundle toplevel. Reproducing the shape is
+ * what makes every one of those relations still true after the copy.
+ */
+export interface AppRuntimePaths {
+    /** `<App>.app/Contents/Frameworks/node-gi` — the package root the layout imitates. */
+    nodeGiRoot: string;
+    /**
+     * `<App>.app/Contents/Resources/lib/node_modules/@gjsify/node-gi` — where
+     * node-gi's JAVASCRIPT goes.
+     *
+     * Not a preference: `require('@gjsify/node-gi/gi')` from the staged bundle at
+     * `Contents/Resources/lib/<bundle>.mjs` walks `node_modules` upward from that
+     * file's own directory, and this is the FIRST directory that walk visits. Any
+     * other location works only by accident of what sits above the bundle.
+     */
+    nodeGiPackageDir: string;
+    /** `<nodeGiRoot>/prebuilds/<target>` — the addon and the closure, siblings. */
+    prebuildDir: string;
+    /** `<prebuildDir>/gtk` — what `GJSIFY_GTK_RUNTIME` names. */
+    gtkDir: string;
+    /** `<prebuildDir>/node_gi.node` — what `NODE_GI_NATIVE` pins. */
+    addonPath: string;
+    /**
+     * `<App>.app/Contents/MacOS/node`, or `<program dir>/node.exe` — beside the
+     * launcher that execs it, under the name the target's own release uses.
+     */
+    interpreterPath: string;
+    /** Node's own LICENSE, under `Contents/Resources` (macOS) or `share/` (Windows). */
+    interpreterLicensePath: string;
+}
+export declare function appRuntimePaths(layout: Layout, identity: LayoutIdentity, target: GtkRuntimeTarget): AppRuntimePaths;
+/** What the launcher must export and exec, once the runtime is staged. Absent member = not staged. */
+export interface LauncherRuntime {
+    /** Stage-relative path of the interpreter the bundle carries. */
+    interpreter?: string;
+    /** Stage-relative path of the GTK closure — `GJSIFY_GTK_RUNTIME`. */
+    gtkRuntimeDir?: string;
+    /** Stage-relative path of the node-gi addon — `NODE_GI_NATIVE`. */
+    nodeGiAddon?: string;
+}
+/** The staged runtime, and an account of what was and was not found. */
+export interface StagedAppRuntime {
+    /** Stage-relative files, already placed — they never passed through the prefix-relative plan. */
+    files: StagedFile[];
+    /** What the launcher can now name. */
+    launcher: LauncherRuntime;
+    /** One line per piece that WAS found, naming where it came from. */
+    found: string[];
+    /** One line per piece that was not, naming the package to install. */
+    missing: string[];
+}
+export interface StageAppRuntimeInput {
+    layout: Layout;
+    identity: LayoutIdentity;
+    /** `${layout.os}-${settings.arch}` — the target the payload was built for. */
+    target: GtkRuntimeTarget;
+    /** Project directory the three packages are resolved from. */
+    cwd: string;
+    /** Injected so the overrides are testable. */
+    env?: Record<string, string | undefined>;
+    /** Passed to every discovery below — see {@link ResolveRuntimeOptions.resolve}. */
+    resolve?: ResolveRuntimeOptions['resolve'];
+    /** The interpreter, already resolved — see `node-runtime.ts`. `null` when absent. */
+    interpreter: {
+        source: string;
+        nodePath: string;
+        licensePath: string;
+    } | null;
+}
+/**
+ * Stage the interpreter, the GTK closure and the addon into one bundle.
+ *
+ * PARTIAL BY DESIGN, and reported. An all-or-nothing rule would drop a 200 MB
+ * closure that IS present because an interpreter that is not shares the milestone
+ * with it, and would do it at exit 0 — while a bundle carrying the closure and no
+ * interpreter is a real, useful intermediate (it runs wherever a Node is on
+ * `PATH`, which is every developer's machine and no stranger's). So each piece is
+ * staged when found and named when not, and `commands/ship.ts` keeps
+ * `Layout.runtimeGap` for precisely the case where the interpreter is still
+ * missing.
+ *
+ * TREE-PRESERVING for the closure and FLAT for the other two, which is the whole
+ * distinction this module exists to draw: `listFilesRecursive` walks the bundle
+ * and every relative path is carried through unchanged, so
+ * `lib/gdk-pixbuf-2.0/2.10.0/loaders/libpixbufloader-svg.so` is still four levels
+ * under `gtk/` on the other side of the copy.
+ */
+export declare function stageAppRuntime(input: StageAppRuntimeInput): StagedAppRuntime;