@gjsify/cli 0.35.0 → 0.37.0

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

@@ -6,64 +6,57 @@ interface ParsedSpec {
     range: string;
 }
 /**
- * One placed package in the resolved tree. Exported as a TYPE only: it is the
- * graph shape {@link computeOptionalFlags} and {@link applyPlatformFilter} take,
- * so a spec can inject a tree by hand instead of driving a whole install to reach
- * them. Nothing outside this module constructs one for real.
+ * One placed package in the resolved tree. Exported as a TYPE only, so a spec can
+ * hand {@link computeOptionalFlags} and {@link applyPlatformFilter} a graph
+ * directly instead of driving a whole install; nothing outside this module
+ * constructs one for real.
  */
 export interface ResolvedNode {
-    /** Package name (e.g. `@gjsify/cli`, `lodash`). */
     name: string;
     version: string;
     tarballUrl: string;
     integrity?: string;
-    /** Where this node lives relative to the install prefix. Always
-     *  starts with `node_modules/`; nested entries look like
-     *  `node_modules/<parent>/node_modules/<dep>`. */
+    /** Relative to the install prefix. Always starts with `node_modules/`; nested
+     *  entries look like `node_modules/<parent>/node_modules/<dep>`. */
     installPath: string;
-    /** `dependencies` field from the packument (range strings keyed by name). */
+    /** Ranges keyed by name, as published. */
     dependencies: Record<string, string>;
-    /** `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.
+     * The version's `os`/`cpu`/`libc` declaration, as published. Recorded here
+     * (and in the lockfile) so the VERDICT can be recomputed for whichever host
+     * runs the install — 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`).
+     * Read from the FULL packument, the only document carrying `libc`: the
+     * abbreviated one can never PROVE a `libc` restriction is absent, so a
+     * declaration built from it is silently incomplete for exactly the packages
+     * the field exists for (nine of this repo's own — `@gjsify/{rolldown,
+     * lightningcss,oxfmt}-native`, `webgl`, `napi`, `sab-native`,
+     * `terminal-native`, `http2-native`, `http-soup-bridge` — 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`.
+     * an incompatible platform means: skip silently vs. fail the install. 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).
+     * fixpoint on both the fresh-resolve and the lockfile path before anything
+     * reads it. What the BFS assigns at placement time is a forward guess, used
+     * only to decide whether a resolve FAILURE under this node is tolerated.
      *
-     * 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.
+     * Absent must read as `false` (= required): callers also build nodes
+     * structurally caring only 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 vanishing 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.
+     * Set by {@link applyPlatformFilter}: not runnable on the install target, so
+     * not downloaded or extracted. Never persisted — a per-host verdict, not a
+     * property of the resolution.
      */
     inert?: boolean;
 }
@@ -74,21 +67,19 @@ export interface 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.
+ * `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 — skipped vs. fatal. The
+ * live shape is `optionalDependencies: { fsevents }` in a project manifest: npm
+ * leaves fsevents out on Linux and installs fine, so treating every top-level
+ * spec as required turns that into a hard EBADPLATFORM for a package nothing on
+ * the host would 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).
+ * It rides the SAME options object `install-backend.ts` forwards wholesale here.
+ * If that forwarding is ever changed to destructure, this field must be forwarded
+ * with it, or top-level optional deps quietly become required again — the
+ * `install-platform-filter` e2e is where that assumption is pinned.
  */
 export interface NativeInstallOptions extends InstallOptions {
     /**
@@ -100,115 +91,90 @@ export interface NativeInstallOptions extends InstallOptions {
 }
 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.
+ * Split a resolved tree into what THIS target can install, marking the rest inert.
+ * A post-pass rather than a filter during the walk (as in arborist's
+ * `refs/npm-cli/workspaces/arborist/lib/arborist/build-ideal-tree.js`) 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.
+ *   - REQUIRED + incompatible → EBADPLATFORM. A required dep the host cannot run
+ *     is a broken install, not a smaller one, so it fails loudly with
+ *     `pkgid`/`current`/`required`. `--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 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.
+ * The skip line carries npm's `current`/`required` payload so `--verbose` recovers
+ * 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.
  *
- * gjsify install is node-free (it runs under GJS) and does NOT run a package's
- * `install`/`postinstall` lifecycle script — running e.g. `node-gyp rebuild` would
- * need Node + a C++ toolchain, breaking that property (see the header's "out of
- * scope"). Such a package works only if it SHIPS a prebuild for the platform (the
- * sanctioned path — `prebuilds/<platform>-<arch>/…`) or is later built by hand. When
- * neither is present the package silently loads no binary (the `@gjsify/node-gi
- * 0.21.0` case: installed, but `node_gi.node` absent → the consumer hit a runtime
- * failure with no hint). Surface it at install time with an actionable line. Pure
- * detection — no script is run, so node-free-ness is preserved.
+ * This install is node-free and does NOT run `install`/`postinstall` scripts —
+ * `node-gyp rebuild` would need Node plus a C++ toolchain. Such a package works
+ * only if it SHIPS a prebuild (`prebuilds/<platform>-<arch>/…`) or is built by
+ * hand; with neither it silently loads no binary, as `@gjsify/node-gi 0.21.0` did
+ * (installed, `node_gi.node` absent, consumer hit a runtime failure with no hint).
+ * Pure detection — no script is run, so node-free-ness is preserved.
  */
 export declare function warnMissingNativeBuilds(nodes: ResolvedNode[], prefix: string, log: Logger): void;
 /**
- * A node's REQUIRED dependency edges: its `dependencies`, minus every name its
- * `optionalDependencies` also lists. The one place that decides what kind an edge
- * is — both the resolve walk and the optionality fixpoint read it, so the two
- * cannot drift.
+ * A node's REQUIRED dependency edges: its `dependencies` minus every name its
+ * `optionalDependencies` also lists. The ONE place that decides an edge's kind —
+ * both the resolve walk and the optionality fixpoint read it, so they cannot drift.
  *
- * THE SUBTRACTION IS npm's RULE, not a policy of ours: "entries in
- * optionalDependencies will override entries of the same name in dependencies, so
- * it's usually best to only put in one place" (npm's package.json docs). Measured
- * on `@parcel/rust@2.16.4`, which lists all eight per-platform napi packages in
- * both blocks: `npm install` exits 0, installs `@parcel/rust-linux-x64-gnu` only,
- * and writes `"optional": true` for all eight in its `package-lock.json`.
+ * The subtraction is npm's rule, not ours: "entries in optionalDependencies will
+ * override entries of the same name in dependencies" (npm's package.json docs).
  *
- * WHY IT IS NOT MERELY A DEDUP: the kind decides what an incompatible
- * `os`/`cpu`/`libc` MEANS (`applyPlatformFilter` — fatal vs. inert) and whether a
- * failed resolve is tolerated. Reading `dependencies` alone therefore does not
- * just visit a name twice, it promotes a foreign-platform binary to a required
- * dependency and fails installs npm completes.
+ * NOT MERELY A DEDUP: the kind decides what an incompatible `os`/`cpu`/`libc` MEANS
+ * (fatal vs. inert in `applyPlatformFilter`) and whether a failed resolve is
+ * tolerated. Reading `dependencies` alone does not just visit a name twice, it
+ * promotes a foreign-platform binary to a required dependency and fails installs npm
+ * completes — the header note's invariant 3.
  *
- * The inverse direction is deliberately NOT symmetric: a name in
- * `optionalDependencies` alone is optional (no `dependencies` entry to override),
- * which is what {@link resolveDeps}'s second queue loop covers.
+ * Deliberately NOT symmetric: a name in `optionalDependencies` alone is optional (no
+ * `dependencies` entry to override), covered by {@link resolveDeps}'s second queue loop.
  */
 export declare function requiredDepEntries(node: Pick<ResolvedNode, 'dependencies' | 'optionalDependencies'>): [string, string][];
 /**
- * Recompute every node's `optional` flag as a FIXPOINT over the placed graph.
- * The only writer of the final flag; whatever the nodes arrive carrying is an
- * input nothing checked (a BFS forward guess on the resolve path, a value read
- * back out of a file on the lockfile path) and is overwritten unconditionally.
+ * Recompute every node's `optional` flag as a FIXPOINT over the placed graph. The
+ * only writer of the final flag; whatever the nodes arrive carrying is an input
+ * nothing checked (a BFS forward guess on the resolve path, a value read out of a
+ * file on the lockfile path) and is overwritten unconditionally.
  *
- * DEFINITION: a node is REQUIRED iff it is reachable from `requiredNames`
- * through REQUIRED edges alone ({@link requiredDepEntries} — `dependencies` minus
- * the names `optionalDependencies` overrides); every other node is optional.
- * Optionality is therefore INHERITED — a plain dependency OF an optional package
- * is still optional — which is what npm's `optionalSet` computes.
+ * DEFINITION: a node is REQUIRED iff reachable from `requiredNames` through
+ * REQUIRED edges alone ({@link requiredDepEntries}); every other node is optional.
+ * Optionality is therefore INHERITED — a plain dependency OF an optional package is
+ * still optional, which is what npm's `optionalSet` computes.
  *
  * WHY A FIXPOINT AND NOT A ONE-SHOT PROMOTION AT THE REUSE SITE (the reviewed
- * defect): the walk queues a node's own dep edges at the moment it is placed,
- * carrying the optionality it had THEN. Promoting the node later leaves its
- * children behind, so the answer depends on which edge BFS happened to traverse
- * first — a genuinely required transitive dep reached first through an optional
- * edge stayed flagged optional, was persisted that way, and was then silently
- * skipped by the platform filter on every machine instead of raising
- * EBADPLATFORM. A monotone worklist over the FINISHED graph cannot have that
- * property: "required" only ever spreads, so the result is independent of visit
- * order. npm reaches for the same shape and says so —
- * refs/npm-cli/workspaces/arborist/lib/calc-dep-flags.js: "If a node is changed,
- * we add to the queue and continue until no more changes."
+ * defect): the walk queues a node's dep edges when it is placed, carrying the
+ * optionality it had THEN, so promoting the node later leaves its children behind and
+ * the answer depends on which edge BFS traversed first. A required transitive dep
+ * reached first through an optional edge stayed flagged optional, was persisted that
+ * way, and was then silently skipped by the platform filter on every machine instead
+ * of raising EBADPLATFORM. A monotone worklist over the FINISHED graph cannot have
+ * that property: "required" only ever spreads, so the result is order-independent.
+ * Same shape as refs/npm-cli/workspaces/arborist/lib/calc-dep-flags.js.
  *
- * PATH-INDEPENDENCE IS THE OTHER REQUIREMENT, and it is why the lockfile carries
- * an `optionalDependencies` map per entry (v4). The walk USED to read
- * `dependencies` only, for exactly that reason — a lockfile entry recorded nothing
- * else, so consulting `node.optionalDependencies` would have made the two paths
- * compute different flags for the same tree. The premise was fixable and the
- * consequence was not: a publisher listing the same name in BOTH blocks means
- * "optional" to npm, came out REQUIRED here, and the shape is not rare — it is
- * `@parcel/rust@2.16.4` (all eight per-platform napi packages in both blocks), so
- * every Linux install of any tree containing parcel failed with EBADPLATFORM on
- * `@parcel/rust-darwin-x64` while `npm install` thinned the same tree and exited
- * 0. "Erring toward REQUIRED errs toward the loud failure" is true and was the
- * wrong trade: the loud failure was not a real one, and no `--force` lifts it
- * (nor should it). So the declaration is persisted and both paths subtract it.
- * Reading a pre-v4 lockfile leaves the map empty, which reproduces the old
- * behaviour for that file alone — see READABLE_LOCKFILE_VERSIONS.
+ * PATH-INDEPENDENCE is the other requirement, and why the lockfile carries an
+ * `optionalDependencies` map per entry (v4). This walk USED to read `dependencies`
+ * only, because a lockfile entry recorded nothing else and consulting
+ * `node.optionalDependencies` would have made the two paths compute different flags
+ * for one tree. That premise was fixable and its consequence — a both-blocks name
+ * coming out REQUIRED — was not (header note, invariant 3). A pre-v4 lockfile leaves
+ * the map empty and reproduces the old behaviour for that file alone
+ * (READABLE_LOCKFILE_VERSIONS).
  *
- * Runs before `writeLockfile` so the persisted flag is the final one, and before
- * `applyPlatformFilter` so the fatal-vs-inert decision reads it rather than the
- * guess. Exported so the unit spec can drive it with INJECTED graphs: the whole
- * fatal-vs-inert question is decided by these two functions in composition, and
- * that is worth pinning without a registry.
+ * Exported so the unit spec can drive it with INJECTED graphs — the whole
+ * fatal-vs-inert question is decided by this and `applyPlatformFilter` in
+ * composition, worth pinning without a registry.
  */
 export declare function computeOptionalFlags(nodes: ResolvedNode[], requiredNames: Set<string>, log: Logger): void;
 export declare function parseSpec(raw: string): ParsedSpec;
@@ -216,20 +182,18 @@ export declare function pickVersion(packument: Packument, range: string, preferr
 /**
  * Materialise ONE `node_modules/.bin/<name>` entry for `targetAbs`.
  *
- * Exported (and platform-injectable) so the Windows branch is unit-tested from
- * a Linux host — the file layout and shim contents are asserted there; only the
- * `symlinkSync`/`CreateSymbolicLink` syscall behaviour itself is OS-bound.
+ * Exported and platform-injectable so the Windows branch is unit-tested from a Linux
+ * host; only the `symlinkSync`/`CreateSymbolicLink` syscall itself is OS-bound.
  *
- * POSIX: a relative symlink, with a copy as the fallback (some filesystems and
- * container overlays reject symlinks).
+ * POSIX: a relative symlink, falling back to a copy (some filesystems and container
+ * overlays reject symlinks).
  *
- * Windows: `.bin/<name>` is not on `PATHEXT` and Windows has no shebang
- * handling, so a symlink OR a copy of a `#!/usr/bin/env node` script is
- * unrunnable — and a *file* symlink additionally needs elevation or Developer
- * Mode, so the previous code reliably fell into its copy fallback and produced
- * a dead entry. npm solves this with three sibling files (`<name>` for
- * git-bash/MSYS/WSL, `<name>.cmd` for cmd.exe, `<name>.ps1` for pwsh); we write
- * the same set from the same templates. See `./bin-shim.ts`.
+ * Windows: `.bin/<name>` is not on `PATHEXT` and Windows has no shebang handling, so a
+ * symlink OR a copy of a `#!/usr/bin/env node` script is unrunnable — and a *file*
+ * symlink additionally needs elevation or Developer Mode, so the previous code reliably
+ * fell into its copy fallback and produced a dead entry. npm's answer is three sibling
+ * files (`<name>` for git-bash/MSYS/WSL, `<name>.cmd` for cmd.exe, `<name>.ps1` for
+ * pwsh); the same set is written from the same templates (`./bin-shim.ts`).
  */
 export declare function writeBinEntry(opts: {
     binDir: string;
@@ -237,25 +201,23 @@ export declare function writeBinEntry(opts: {
     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.
+     * Set when this entry is the package's GJS-runnable artifact (`gjsify.bin`), making
+     * it a GENERATED launcher rather than a link to a file with a shebang — see
+     * {@link buildShLauncher} for why, {@link pickBinMap} for why `gjsify.bin` wins.
      *
-     * 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.
+     * The preamble 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[];
     };
     /**
-     * The package's npm `bin` target, when it declares one ALONGSIDE
-     * `gjsify.bin`. The launcher then picks a runtime per invocation instead of
-     * hard-coding `gjs` — see {@link pickBinMap}. Absent for a package that
-     * declares only one of the two, which is every package but `@gjsify/cli`
-     * today.
+     * The package's npm `bin` target when it declares one ALONGSIDE `gjsify.bin`; the
+     * launcher then picks a runtime per invocation instead of hard-coding `gjs` (see
+     * {@link pickBinMap}). Absent for a package declaring only one of the two, which is
+     * every package but `@gjsify/cli` today.
      */
     nodeFallbackAbs?: string;
 }): void;