@gjsify/cli 0.26.1 → 0.27.1

package/lib/utils/install-backend-native.d.ts

@@ -1,5 +1,6 @@
 import { type Packument } from '@gjsify/npm-registry';
 import type { InstallOptions } from './install-backend.ts';
+import { type PlatformDeclaration, type PlatformTarget } from './platform-check.js';
 interface ParsedSpec {
     name: string;
     range: string;
@@ -19,12 +20,105 @@ interface ResolvedNode {
     /** `optionalDependencies` field from the packument. */
     optionalDependencies: Record<string, string>;
     bin?: string | Record<string, string>;
+    /**
+     * The version's `os`/`cpu`/`libc` declaration, as published. Recorded on the
+     * node (and in the lockfile) so the compatibility VERDICT can be recomputed
+     * for whichever host runs the install — see the header note on portability.
+     *
+     * Read from the FULL packument, which is the only document that carries
+     * `libc`. That is not an optimisation detail leaking into a comment: the
+     * abbreviated document can never PROVE the absence of a `libc` restriction,
+     * so a declaration built from it would be silently incomplete for exactly
+     * the packages the field exists for (this repo publishes nine of them —
+     * `@gjsify/{rolldown,lightningcss,oxfmt}-native`, `webgl`, `napi`,
+     * `sab-native`, `terminal-native`, `http2-native`, `http-soup-bridge` all
+     * declare `libc: ["glibc"]` and NO `os`/`cpu`).
+     */
+    platform?: PlatformDeclaration;
+    /**
+     * Is this node reachable ONLY through optionalDependency edges? Decides what
+     * an incompatible platform means: skip silently (optional) vs. fail the
+     * install (required). npm calls the same set `optionalSet`.
+     *
+     * DERIVED, not an input — {@link computeOptionalFlags} recomputes it as a
+     * fixpoint over the placed graph before anything reads it, on the fresh-
+     * resolve AND the lockfile path. The value the BFS assigns at placement time
+     * is a forward guess used only to decide whether a resolve FAILURE under this
+     * node is tolerated; it is edge-order-dependent and must never be the final
+     * answer (header note, invariant 2).
+     *
+     * OPTIONAL FIELD, and absent must read as `false` (= required): nodes are
+     * also built structurally by callers that only care about name/installPath,
+     * and the safe default for an unknown edge kind is the loud one — a required
+     * incompatible dependency fails the install instead of being silently
+     * dropped from the tree.
+     */
+    optional?: boolean;
+    /**
+     * Set by {@link applyPlatformFilter}: this node cannot run on the install
+     * target, so it is not downloaded or extracted. Never persisted — it is a
+     * per-host verdict, not a property of the resolution.
+     */
+    inert?: boolean;
 }
 export interface InstalledTopLevel {
     name: string;
     version: string;
 }
-export declare function installPackagesNative(opts: InstallOptions): Promise<InstalledTopLevel[]>;
+/**
+ * {@link InstallOptions} plus what only the NATIVE backend can use.
+ *
+ * `optionalSpecs` exists because a spec is a flat `"<name>@<range>"` string by
+ * the time it reaches here — `projectSpecsFromPackageJson` flattens
+ * `dependencies`, `devDependencies` and `optionalDependencies` into one list —
+ * yet the KIND decides what an incompatible `os`/`cpu`/`libc` means: an optional
+ * dependency is skipped, a required one fails the install. The shape that makes
+ * this concrete is `optionalDependencies: { fsevents }` in a project's own
+ * manifest: on Linux npm leaves fsevents out and installs fine, so treating
+ * every top-level spec as required would turn that into a hard EBADPLATFORM for
+ * a package nothing on the host would ever load.
+ *
+ * It rides the SAME options object `install-backend.ts` forwards wholesale to
+ * this function. If that forwarding is ever changed to destructure, this field
+ * must be forwarded with it — otherwise top-level optional deps quietly become
+ * required again (and the `install-platform-filter` e2e goes red, which is where
+ * that assumption is pinned).
+ */
+export interface NativeInstallOptions extends InstallOptions {
+    /**
+     * Names (not spec strings — the range differs per requester) of top-level
+     * specs declared as `optionalDependencies`. Absent ⇒ every top-level spec is
+     * required, the pre-platform-filter behaviour.
+     */
+    optionalSpecs?: Set<string>;
+}
+export declare function installPackagesNative(opts: NativeInstallOptions): Promise<InstalledTopLevel[]>;
+/**
+ * Split a resolved tree into what THIS target can install, marking the rest
+ * inert. Mirrors arborist's post-resolve platform pass
+ * (`refs/npm-cli/workspaces/arborist/lib/arborist/build-ideal-tree.js`, the
+ * `checkPlatform` loop around line 210) rather than filtering during the walk,
+ * for two reasons: the verdict must be identical whether the tree came from a
+ * fresh resolve or from `gjsify-lock.json`, and a node's optionality is only
+ * final once every edge that could reach it has been visited.
+ *
+ * The two outcomes are npm's, including the asymmetry around `force`:
+ *   - REQUIRED + incompatible → EBADPLATFORM. A required dependency the host
+ *     cannot run is a broken install, not a smaller one; failing loudly with
+ *     `pkgid`/`current`/`required` is the only honest answer. `--force`
+ *     suppresses it (the user is asserting something about their own machine).
+ *   - OPTIONAL + incompatible → inert: not downloaded, not extracted, still in
+ *     the lockfile. `--force` does NOT lift this — npm says so in as many words
+ *     ("We ignore the --force and --engine-strict flags") and it is right:
+ *     forcing an optional binary that cannot load buys a download and nothing
+ *     else.
+ *
+ * The skip line goes through the debug logger with npm's `current`/`required`
+ * payload, so `--verbose` recovers exactly WHY a package is absent. Silence
+ * here is what made the original defect invisible in the other direction: 3.67
+ * GB arrived with no line saying it should not have.
+ */
+export declare function applyPlatformFilter(nodes: ResolvedNode[], target: PlatformTarget, force: boolean, log: Logger): ResolvedNode[];
 /**
  * Warn about a native package that installed WITHOUT a usable binary.
  *
@@ -64,6 +158,20 @@ export declare function writeBinEntry(opts: {
     binName: string;
     targetAbs: string;
     platform?: string;
+    /**
+     * Set when this entry is the package's GJS-runnable artifact (declared via
+     * `gjsify.bin`). Then the entry is a GENERATED launcher rather than a link
+     * to a file with a shebang — see {@link buildShLauncher} for why, and
+     * {@link pickBinMap} for why `gjsify.bin` has to win here at all.
+     *
+     * The preamble is what exports `GI_TYPELIB_PATH` / the loader path before
+     * `gjs` starts. It cannot be done from inside the bundle: GI resolves the
+     * typelib while the runtime boots, before the first line runs.
+     */
+    gjs?: {
+        envPreamble: string;
+        prebuildDirs: readonly string[];
+    };
 }): void;
 type Logger = (fmt: string, ...args: unknown[]) => void;
 export {};