@gjsify/cli 0.36.0 → 0.37.0

package/lib/commands/install.d.ts

@@ -22,37 +22,41 @@ export declare const installCommand: Command<unknown, InstallOptions>;
 /**
  * Which dependency NAMES are optional across the given manifests.
  *
- * The specs handed to the install backend are flat `"<name>@<range>"` strings —
- * `projectSpecsFromPackageJson` merges the three dependency blocks — so the kind
- * has to travel beside them. It matters for exactly one decision: an
- * incompatible `os`/`cpu`/`libc` skips an OPTIONAL dependency and fails a
- * REQUIRED one (see `NativeInstallOptions.optionalSpecs`).
+ * The specs handed to the backend are flat `"<name>@<range>"` strings, so the
+ * kind has to travel beside them. It decides exactly one thing: an incompatible
+ * `os`/`cpu`/`libc` skips an OPTIONAL dependency and fails a REQUIRED one (see
+ * `NativeInstallOptions.optionalSpecs`).
  *
- * REQUIRED WINS ACROSS MANIFESTS, OPTIONAL WINS WITHIN ONE — and the two halves
- * are different rules for different reasons, so neither is a special case of the
- * other:
- *   - Across manifests: in a workspace the same package can be a plain dependency
- *     of one member and an optionalDependency of another. Those are two real
- *     edges; if one of them is not allowed to be missing, the install is not
- *     allowed to silently miss it. Subtracting rather than "last block seen" also
- *     makes the answer independent of manifest iteration order.
- *   - Within one manifest: a name in BOTH blocks is OPTIONAL, because npm says so
- *     ("entries in optionalDependencies will override entries of the same name in
- *     dependencies") — there is only ONE edge and the optional block names its
- *     kind. Treating it as required is the root-edge twin of the transitive defect
- *     `requiredDepEntries` fixes: `optionalDependencies: { fsevents }` alongside a
- *     `dependencies: { fsevents }` line would fail every Linux install with
+ * REQUIRED WINS ACROSS MANIFESTS, OPTIONAL WINS WITHIN ONE — two rules with two
+ * reasons, neither a special case of the other:
+ *   - Across manifests: one package can be a plain dependency of one member and
+ *     an optionalDependency of another. Those are two real edges, and an edge
+ *     that may not be missing must not be silently missed. Subtracting rather
+ *     than "last block seen" also makes the answer order-independent.
+ *   - Within one manifest: a name in BOTH blocks is OPTIONAL because npm says so
+ *     ("entries in optionalDependencies will override entries of the same name
+ *     in dependencies") — one edge, and the optional block names its kind.
+ *     Treating it as required is the root-edge twin of the defect
+ *     `requiredDepEntries` fixes: `optionalDependencies: { fsevents }` beside a
+ *     `dependencies: { fsevents }` line failed every Linux install with
  *     EBADPLATFORM over a package npm never installs there.
  */
 export declare function optionalDependencyNames(manifests: readonly PackageJson[]): Set<string>;
+/**
+ * Build the `sh` shim for one bin. Which interpreter it tries first is decided
+ * per platform below; the probe is per-INVOCATION, not per-install, so the same
+ * shim works before and after the workspace's `lib/` has been built.
+ *
+ * Both targets are absolute so the shim survives the different cwds consumers
+ * (`yarn run`, `npm run`, a direct PATH invocation) call it from.
+ */
 export declare function buildBinShim(wsLocation: string, nodeTarget?: string, gjsTarget?: string, nativePrebuildDirs?: string[], platform?: string, scanRoot?: string): string;
 /**
  * `.cmd` / `.ps1` companions for {@link buildBinShim}.
  *
- * The `sh` shim's gjs-first / node-fallback probe has no Windows counterpart to
- * express: there is no GJS host on Windows at all (no prebuilt `libgjs` — see
- * `website/src/content/docs/platform-support.md`), so a workspace that ships
- * both targets resolves to Node here, and a GJS-only workspace gets an honest
+ * There is no GJS host on Windows at all (no prebuilt `libgjs` — see
+ * `website/src/content/docs/platform-support.md`), so a workspace shipping both
+ * targets resolves to Node here, and a GJS-only workspace gets an honest
  * `gjs`-invoking shim that fails exactly the way the `sh` one does.
  *
  * Exported + platform-free so it is unit-tested from Linux.
@@ -61,49 +65,6 @@ export declare function buildWorkspaceBinShimsForWindows(wsLocation: string, nod
     cmd: string;
     ps1: string;
 };
-/**
- * Lay the GJS bundler engine down after a PROJECT install, when the host will
- * need it and does not have it. Closes #1005.
- *
- * The engine is an OPTIONAL PEER of `@gjsify/cli`, deliberately: a plain
- * `npm install @gjsify/cli` on Node/macOS/Windows must not fetch Linux
- * prebuilds. But nobody resolves it for a project — npm 7+ skips optional peers,
- * and the native backend does not resolve peerDependencies at all
- * (`install-backend-native.ts:76`). Under GJS there is no npm `rolldown`
- * fallback, so `gjsify build` simply cannot work. Every consumer in the
- * workspace independently discovered this and hand-declared the engine.
- *
- * Four conditions, and the second is the one worth reading:
- *
- *   (a) `@gjsify/cli` is in this tree — otherwise the engine has no caller.
- *   (b) THE HOST CAN RUN GJS, which is NOT the same question as `isGjs()`.
- *       `isGjs()` asks which runtime is executing the installer; the launcher
- *       (`bin-shim.ts:616`) prefers the GJS bundle whenever `command -v gjs`
- *       succeeds, so a tree installed BY NODE is routinely built BY GJS. Gating
- *       on the interpreter would reproduce #1005 for every contributor who
- *       installs on Node and builds through the shim. `runMinimalChecks()` above
- *       already probed for gjs, so this costs no extra spawn — and it goes
- *       nowhere near `which`.
- *   (c) No engine is already reachable — asked with the same walk the BUILD uses.
- *   (d) Not `--immutable`. A frozen install cannot acquire something its
- *       lockfile does not name without breaking the contract `--immutable`
- *       exists to hold, so that case warns and installs nothing.
- *
- * Deliberately NOT gated on `gjsify.app` or on "declares a build script":
- * neither of the failing consumers declares the former, and the latter would
- * mean pattern-matching script bodies — the hand-maintained judgement that
- * drifts, which ADR 0017 rejects by name.
- *
- * NOT recorded in the lockfile. `installPackages` writes one only under
- * `if (resolved && opts.lockfile)` and the default is falsy, so a consumer's
- * `gjsify-lock.json` is never rewritten by this. An e2e row pins that.
- *
- * Ordering is not a constraint here, unlike the global path (which must precede
- * `linkGlobalBins`): `buildNativeEnvPreamble` scans the prefix at LAUNCH time
- * (`bin-shim.ts:432-444`), so a shim written before the engine arrives still
- * exports its dir. `tests/e2e/global-install-engine/run.mjs:361-374` asserts
- * exactly that case.
- */
 export interface EnsureProjectGjsEngineDeps {
     /** Project root. Defaults to `process.cwd()`. */
     cwd?: string;
@@ -115,5 +76,41 @@ export interface EnsureProjectGjsEngineDeps {
     /** Injected so a host that HAS an engine can still exercise the missing branch. */
     hasEngineFn?: (dir: string) => boolean;
 }
+/**
+ * Lay the GJS bundler engine down after a PROJECT install, when the host will need
+ * it and does not have it (#1005).
+ *
+ * The engine is an OPTIONAL PEER of `@gjsify/cli` on purpose — a plain
+ * `npm install @gjsify/cli` on Node must not fetch prebuilds — but nobody resolves
+ * it for a project: npm 7+ skips optional peers and the native backend does not
+ * resolve `peerDependencies` at all. Under GJS there is no npm `rolldown`
+ * fallback, so `gjsify build` had nothing to load.
+ *
+ * Four conditions, and (b) is the one worth reading:
+ *
+ *   (a) `@gjsify/cli` is in this tree — otherwise the engine has no caller.
+ *   (b) THE HOST CAN RUN GJS, which is NOT the `isGjs()` question. `isGjs()` asks
+ *       which runtime is executing the installer, but the launcher prefers the GJS
+ *       bundle whenever `command -v gjs` succeeds, so a tree installed BY NODE is
+ *       routinely built BY GJS. Gating on the interpreter reproduces #1005 for
+ *       every contributor who installs on Node and builds through the shim.
+ *       `runMinimalChecks()` already probed for gjs, so this costs no extra spawn.
+ *   (c) No engine is already reachable — asked with the same walk the BUILD uses.
+ *   (d) Not `--immutable`: a frozen install cannot acquire what its lockfile does
+ *       not name, so that case warns and installs nothing.
+ *
+ * NOT gated on `gjsify.app` or on "declares a build script": neither failing
+ * consumer declares the former, and the latter means pattern-matching script
+ * bodies, the drifting hand-maintained judgement ADR 0017 rejects by name.
+ * ADR 0020 records the simpler `optionalDependencies` shape that would retire
+ * this policy entirely.
+ *
+ * NOT recorded in the lockfile — `installPackages` writes one only when both
+ * `resolved` and `opts.lockfile` hold — so a consumer's `gjsify-lock.json` is
+ * never rewritten by this; an e2e row pins it. Ordering is free here, unlike the
+ * global path: `buildNativeEnvPreamble` scans the prefix at LAUNCH time, so a shim
+ * written before the engine arrives still exports its dir
+ * (`tests/e2e/global-install-engine/`).
+ */
 export declare function ensureProjectGjsEngine(args: InstallOptions, gjsFound: boolean, deps?: EnsureProjectGjsEngineDeps): Promise<void>;
 export {};