@gjsify/cli 0.35.0 → 0.37.0

package/lib/utils/publish-headers.d.ts

@@ -1,15 +1,13 @@
 import { type NpmrcConfig } from '@gjsify/npm-registry';
 /**
  * Percent-encode a package name for the publish PUT path, matching
- * npm-package-arg's `escapedName` convention (npa.js:188):
- * `this.escapedName = name.replace('/', '%2f')`.
+ * npm-package-arg's `escapedName` convention.
  *
  * Scoped: `@scope/name` → `@scope%2fname` (literal `@`, lowercase `%2f`, the
  * scope/name segments NOT otherwise re-encoded — npm only replaces the slash).
- * Unscoped: returned unchanged (npa stores the bare name; the only characters
- * npm forbids are those `encodeURIComponent` would touch, which npa rejects up
- * front). The npm registry is picky about this exact shape on the publish PUT
- * URL — `%2F` (uppercase) or a re-encoded `@` would miss the create route.
+ * Unscoped: returned unchanged. The registry is picky about this exact shape on
+ * the publish PUT URL — uppercase `%2F` or a re-encoded `@` misses the create
+ * route.
  */
 export declare function escapePackageName(name: string): string;
 export interface PublishHeaderOptions {
@@ -19,8 +17,7 @@ export interface PublishHeaderOptions {
     otp?: string;
     /**
      * Override the `authorization` header (e.g. an OIDC Bearer token resolved
-     * after `buildHeaders` ran). When set it replaces whatever the npmrc auth
-     * resolution produced.
+     * after `buildHeaders` ran), replacing whatever npmrc auth resolution produced.
      */
     authorization?: string;
     /**
@@ -37,8 +34,7 @@ export interface PublishHeaderOptions {
  * `npm-command: publish`, `npm-auth-type` (`web`, or `legacy` when `--otp`),
  * `user-agent`, and `npm-otp` when an OTP is supplied.
  *
- * Notably it does NOT set an `accept: *` wildcard — `npm-registry-fetch` sends
- * no `accept` header on the publish PUT; the stray wildcard gjsify used to send
- * is dropped to match.
+ * Notably NO `accept` header: `npm-registry-fetch` sends none on the publish PUT,
+ * and a wildcard here misses the create route.
  */
 export declare function buildPublishHeaders(url: string, opts: PublishHeaderOptions): Record<string, string>;

package/lib/utils/publish-headers.js

@@ -3,48 +3,30 @@
 // package correctly.
 //
 // Root cause this fixes: a first-publish of a never-before-published
-// `@scope/<name>` via token auth was returning a bare `404 Not Found` (body
-// `Not Found`, NOT a JSON npm error). That is a routing miss, not a
-// payload-validation failure — npm's write frontdoor keys the create path on
-// the `npm-command` header, which gjsify was not sending. `npm publish` with
-// the same ~/.npmrc token succeeds because libnpmpublish goes through
+// `@scope/<name>` via token auth returned a bare `404 Not Found` (body
+// `Not Found`, NOT a JSON npm error). That is a ROUTING miss, not a
+// payload-validation failure — npm's write frontdoor keys the create path on the
+// `npm-command` header, which gjsify was not sending. `npm publish` with the same
+// ~/.npmrc token succeeds because libnpmpublish goes through
 // `npm-registry-fetch`'s `getHeaders`, which always sets `npm-command`
-// (+ `npm-auth-type`, + a real `user-agent`).
-//
-// Evidence (refs/npm-cli):
-//   - `lib/npm.js:404`  `flat.npmCommand = this.command`  → set for EVERY npm
-//     command; equals `"publish"` for `npm publish`.
-//   - `node_modules/npm-registry-fetch/lib/index.js:231-233`
-//        `if (opts.npmCommand) headers['npm-command'] = opts.npmCommand`
-//     and `:219-221` `if (opts.authType) headers['npm-auth-type'] = …`
-//     and `:215-217` `'user-agent': opts.userAgent`.
-//   - `workspaces/config/lib/definitions/definitions.js:282-290` — `auth-type`
-//     default `'web'`, flattened to `flatOptions.authType`.
-//   - `:1581-1587` — when `--otp` is set, npm forces `auth-type` to `'legacy'`
-//     before flattening, so an OTP publish sends `npm-auth-type: legacy`.
-//   - `node_modules/npm-package-arg/lib/npa.js:188`
-//        `this.escapedName = name.replace('/', '%2f')` — lowercase `%2f`,
-//     literal `@`. (gjsify's URL encoding already matches this — it was never
-//     the bug.)
+// (+ `npm-auth-type`, + a real `user-agent`). Reference: `refs/npm-cli`.
 //
 // This module pulls in no `gi://` and no runtime fetch/Soup stack, so it is
-// unit-testable on both Node and GJS. Its one filesystem touch is the
-// manifest walk backing the user-agent version — see `cliVersion()`.
+// unit-testable on both Node and GJS. Its one filesystem touch is the manifest
+// walk backing the user-agent version — see `cliVersion()`.
 import { readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildHeaders } from '@gjsify/npm-registry';
 /**
  * Percent-encode a package name for the publish PUT path, matching
- * npm-package-arg's `escapedName` convention (npa.js:188):
- * `this.escapedName = name.replace('/', '%2f')`.
+ * npm-package-arg's `escapedName` convention.
  *
  * Scoped: `@scope/name` → `@scope%2fname` (literal `@`, lowercase `%2f`, the
  * scope/name segments NOT otherwise re-encoded — npm only replaces the slash).
- * Unscoped: returned unchanged (npa stores the bare name; the only characters
- * npm forbids are those `encodeURIComponent` would touch, which npa rejects up
- * front). The npm registry is picky about this exact shape on the publish PUT
- * URL — `%2F` (uppercase) or a re-encoded `@` would miss the create route.
+ * Unscoped: returned unchanged. The registry is picky about this exact shape on
+ * the publish PUT URL — uppercase `%2F` or a re-encoded `@` misses the create
+ * route.
  */
 export function escapePackageName(name) {
     return name.replace('/', '%2f');
@@ -57,34 +39,26 @@ export function escapePackageName(name) {
  * `npm-command: publish`, `npm-auth-type` (`web`, or `legacy` when `--otp`),
  * `user-agent`, and `npm-otp` when an OTP is supplied.
  *
- * Notably it does NOT set an `accept: *` wildcard — `npm-registry-fetch` sends
- * no `accept` header on the publish PUT; the stray wildcard gjsify used to send
- * is dropped to match.
+ * Notably NO `accept` header: `npm-registry-fetch` sends none on the publish PUT,
+ * and a wildcard here misses the create route.
  */
 export function buildPublishHeaders(url, opts) {
     const headers = buildHeaders(url, { npmrc: opts.npmrc });
-    // npm-registry-fetch never sets `accept` on the publish PUT — drop the
-    // placeholder `accept-encoding` we don't want to influence the create route
-    // either. (buildHeaders defaults accept-encoding to `identity`; a publish
-    // PUT body is JSON we generated, so the encoding header is irrelevant — but
-    // we keep it harmless and explicit by leaving it as buildHeaders set it.)
-    // content-type: application/json — npm-registry-fetch sets this for any
-    // non-string/non-stream/non-buffer body (index.js:63-67); our body is a
-    // JSON string, so we set it explicitly.
+    // `buildHeaders`' `accept-encoding: identity` default is left as it set it —
+    // the PUT body is JSON we generated, so the encoding header is irrelevant here.
+    // npm-registry-fetch sets this for any non-string/non-stream/non-buffer body;
+    // ours is a JSON string, so it is set explicitly.
     headers['content-type'] = 'application/json';
-    // npm-command: publish — THE routing header. npm sets it for every command
-    // (npm.js:404); the registry's write frontdoor uses it to route the
-    // create-package PUT. Missing it = bare `404 Not Found` on a new package.
+    // THE routing header: npm sets it for every command, and the registry's write
+    // frontdoor uses it to route the create-package PUT. Missing it = bare
+    // `404 Not Found` on a new package.
     headers['npm-command'] = 'publish';
-    // npm-auth-type — `web` by default, `legacy` when an OTP is supplied
-    // (definitions.js:1583-1586). Sent by getHeaders (index.js:219-221).
+    // npm forces auth-type `legacy` whenever `--otp` is set, `web` otherwise.
     headers['npm-auth-type'] = opts.otp ? 'legacy' : 'web';
-    // user-agent — a real npm-shaped UA (getHeaders index.js:215-217).
     headers['user-agent'] = opts.userAgent ?? defaultUserAgent();
-    // npm-otp — only when an OTP is supplied (index.js:243-245).
     if (opts.otp)
         headers['npm-otp'] = opts.otp;
-    // authorization override (OIDC token resolved after npmrc auth).
+    // OIDC token resolved after npmrc auth.
     if (opts.authorization)
         headers['authorization'] = opts.authorization;
     return headers;
@@ -94,21 +68,18 @@ export function buildPublishHeaders(url, opts) {
  * `@gjsify/cli` is a DUAL-ENTRY package and neither layer covers both entries:
  *
  * 1. **`__PACKAGE_VERSION__`** — the compile-time define
- *    (`package.json#gjsify.defineFromPackageJson`), the mechanism
- *    `@gjsify/npm-registry` uses for the same stale-UA bug. Zero I/O, but the
- *    bundler only ever writes `dist/cli.gjs.mjs`: the npm-wired Node bin under
- *    `lib/` is emitted by plain `tsc`, which knows nothing about defines. A
- *    define alone would therefore have left the Node entry — the one `npm
- *    install @gjsify/cli` actually runs — on a permanent placeholder.
+ *    (`package.json#gjsify.defineFromPackageJson`). Zero I/O, but the bundler only
+ *    writes `dist/cli.gjs.mjs`; the npm-wired Node bin under `lib/` comes from
+ *    plain `tsc`, which knows nothing about defines. A define alone would leave the
+ *    Node entry — the one `npm install @gjsify/cli` runs — on a permanent placeholder.
  *
  * 2. **an upward manifest walk** for the nearest `package.json` naming
  *    `@gjsify/cli`, covering `lib/`. Deliberately NOT a fixed
- *    `new URL('../../package.json', import.meta.url)` read: that resolves
- *    correctly from `lib/utils/` but points one directory too high from
- *    `dist/`, and the build-time `inlineStaticReads` pass that would have
- *    frozen it is scoped to `node_modules` paths, so first-party source never
- *    gets it. The walk is depth-independent and so works from `src/`, `lib/`,
- *    `dist/`, and from an installed `node_modules/@gjsify/cli/**` alike.
+ *    `new URL('../../package.json', import.meta.url)` read: that resolves correctly
+ *    from `lib/utils/` but points one directory too high from `dist/`, and the
+ *    build-time `inlineStaticReads` pass that would have frozen it is scoped to
+ *    `node_modules` paths. The walk is depth-independent, so it works from `src/`,
+ *    `lib/`, `dist/` and an installed `node_modules/@gjsify/cli/**` alike.
  *
  * `GJSIFY_CLI_PACKAGE_JSON` overrides both, matching `self-update.ts`.
  */
@@ -147,10 +118,10 @@ function walkForCliVersion() {
     return '';
 }
 /**
- * npm-CLI-shaped user-agent. Format mirrors npm-registry-fetch's
- * `default-opts.js` (`npm@<v>/node@<v>+<arch> (<platform>)`); we substitute the
- * gjsify CLI identity. The registry does not validate the exact value — it just
- * must be a non-placeholder UA, which some WAF / CDN frontdoors require.
+ * npm-CLI-shaped user-agent, mirroring npm-registry-fetch's
+ * `npm@<v>/node@<v>+<arch> (<platform>)` with the gjsify CLI identity substituted.
+ * The registry does not validate the value; it must merely be a non-placeholder UA,
+ * which some WAF / CDN frontdoors require.
  */
 function defaultUserAgent() {
     const proc = globalThis.process;

package/lib/utils/publishable-packages.d.ts

@@ -1,18 +1,16 @@
 import type { Workspace } from '@gjsify/workspace';
 /**
  * Package-group directories holding publishable packages that are NOT root
- * workspaces. Add one here the moment a new non-workspace publishable group
- * appears — this list is the only thing standing between such a package and a
- * silently broken first release.
+ * workspaces. Extend this the moment a new such group appears — the list is the
+ * only thing standing between one and a silently broken first release.
  */
 export declare const NON_WORKSPACE_PUBLISHABLE_DIRS: readonly [readonly ["packages", "node-gi"], readonly ["packages", "napi"]];
 /**
  * Publishable packages in {@link NON_WORKSPACE_PUBLISHABLE_DIRS}, shaped as
  * `Workspace` entries so callers can treat them like any other package.
  *
- * Best-effort by design: a missing directory or an unreadable/malformed
- * manifest is skipped rather than thrown, because this runs inside sweeps whose
- * value is covering everything they can reach.
+ * Best-effort by design — a missing directory or malformed manifest is skipped,
+ * not thrown: this runs inside sweeps whose value is covering everything reachable.
  */
 export declare function discoverNonWorkspacePublishables(cwd: string): Workspace[];
 /**

package/lib/utils/publishable-packages.js

@@ -1,23 +1,20 @@
 // Publishable-package discovery shared by `gjsify trust` and `gjsify onboard`.
 //
-// `discoverWorkspaces` only sees ROOT WORKSPACES. Some publishable packages
+// `discoverWorkspaces` only sees ROOT WORKSPACES, and some publishable packages
 // deliberately are not: each is an independent native engine with its own CI
-// workflow, kept out of the workspace graph so a full `gjsify foreach` never
-// tries to build it. They still publish through `release.yml`, so every sweep
-// that reasons about "what do we publish" has to include them — otherwise the
-// sweep silently under-reports and the package's first release fails the OIDC
-// exchange with `404 — package not found`.
-//
-// That is not hypothetical: `gjsify onboard` reported 127 packages "already
-// done" on 2026-07-26 while `@gjsify/napi` was neither in the list nor
-// published at all, because only `packages/node-gi/*` was carved out.
+// workflow, kept out of the graph so a full `gjsify foreach` never tries to build
+// it. They still publish through `release.yml`, so a sweep that reasons about
+// "what do we publish" must include them — otherwise it silently under-reports and
+// the package's first release fails the OIDC exchange with `404 — package not
+// found`. Measured: `gjsify onboard` called 127 packages "already done" while
+// `@gjsify/napi` was neither listed nor published, because only
+// `packages/node-gi/*` had been carved out.
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 /**
  * Package-group directories holding publishable packages that are NOT root
- * workspaces. Add one here the moment a new non-workspace publishable group
- * appears — this list is the only thing standing between such a package and a
- * silently broken first release.
+ * workspaces. Extend this the moment a new such group appears — the list is the
+ * only thing standing between one and a silently broken first release.
  */
 export const NON_WORKSPACE_PUBLISHABLE_DIRS = [
     ['packages', 'node-gi'], // @gjsify/node-gi + the @gjsify/gtk-runtime-* bundles
@@ -27,13 +24,12 @@ export const NON_WORKSPACE_PUBLISHABLE_DIRS = [
  * Publishable packages in {@link NON_WORKSPACE_PUBLISHABLE_DIRS}, shaped as
  * `Workspace` entries so callers can treat them like any other package.
  *
- * Best-effort by design: a missing directory or an unreadable/malformed
- * manifest is skipped rather than thrown, because this runs inside sweeps whose
- * value is covering everything they can reach.
+ * Best-effort by design — a missing directory or malformed manifest is skipped,
+ * not thrown: this runs inside sweeps whose value is covering everything reachable.
  */
 export function discoverNonWorkspacePublishables(cwd) {
-    // Walk up to the repo root. Anchored on the FIRST configured group rather
-    // than on `packages/` itself, which also exists inside individual packages.
+    // Walk up to the repo root, anchored on the FIRST configured group rather than
+    // on `packages/` itself, which also exists inside individual packages.
     let root = cwd;
     const anchor = NON_WORKSPACE_PUBLISHABLE_DIRS[0];
     for (let i = 0; i < 8; i++) {

package/lib/utils/resolve-gjs-entry.d.ts

@@ -5,14 +5,11 @@ interface ResolvedEntry {
 }
 export declare function resolveGjsEntry(pkgDir: string, binName: string | null): ResolvedEntry;
 /**
- * Resolve the `--app node` bundle of a package for the non-gjs runtimes
- * (node/bun/deno all consume it). Resolution order:
- *   1. explicit `gjsify.example.node` (a package can name its node bundle)
- *   2. convention: the node twin of the GJS entry — swap the `<name>.gjs.<ext>`
- *      infix to `<name>.node.<ext>` and probe `.node.{mjs,js,cjs}` (gjsify's
- *      `build:node → dist/<name>.node.mjs` convention; the GJS entry is
- *      `dist/<name>.gjs.js`, so the extension can differ).
- * Hard-fails with an actionable hint when neither is found.
+ * Resolve the `--app node` bundle, which node/bun/deno all consume. An explicit
+ * `gjsify.example.node` wins; otherwise the node twin of the GJS entry is derived by
+ * swapping the `.gjs.<ext>` infix for `.node.<ext>` and probing `mjs`/`js`/`cjs` —
+ * the extension can differ, since `build:node` emits `dist/<name>.node.mjs` while the
+ * GJS entry is `dist/<name>.gjs.js`.
  */
 export declare function resolveNodeEntry(pkgDir: string): string;
 export {};

package/lib/utils/resolve-gjs-entry.js

@@ -1,20 +1,8 @@
-// Resolve the GJS entry point of an installed package.
-//
-// Per the `gjsify` field convention (see CLI reference):
-//
-//   {
-//     "gjsify": {
-//       "main": "dist/gjs.js",
-//       "bin":  { "name-a": "dist/a.js", "name-b": "dist/b.js" }
-//     }
-//   }
-//
-// Resolution order:
-//   1. user-supplied bin name + `gjsify.bin[name]`     → that path
-//   2. single-entry `gjsify.bin`                       → the only path
-//   3. `gjsify.main`                                   → that path
-//   4. fallback: `package.json#main`                   → that path (advisory warning)
-//   5. otherwise: hard-fail with a fix hint
+// Resolve the GJS entry point of an installed package, per the `gjsify` field
+// convention. In order: a requested `gjsify.bin[name]`, a single-entry
+// `gjsify.bin`, `gjsify.main`, then `package.json#main` — the last flagged
+// `fromFallback` so the caller can warn (`commands/dlx.ts` does). No entry at all,
+// or several bins with none named, hard-fails with a fix hint.
 import { readFileSync } from 'node:fs';
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
@@ -64,14 +52,11 @@ export function resolveGjsEntry(pkgDir, binName) {
     return { bundlePath, binName: resolvedBin, fromFallback };
 }
 /**
- * Resolve the `--app node` bundle of a package for the non-gjs runtimes
- * (node/bun/deno all consume it). Resolution order:
- *   1. explicit `gjsify.example.node` (a package can name its node bundle)
- *   2. convention: the node twin of the GJS entry — swap the `<name>.gjs.<ext>`
- *      infix to `<name>.node.<ext>` and probe `.node.{mjs,js,cjs}` (gjsify's
- *      `build:node → dist/<name>.node.mjs` convention; the GJS entry is
- *      `dist/<name>.gjs.js`, so the extension can differ).
- * Hard-fails with an actionable hint when neither is found.
+ * Resolve the `--app node` bundle, which node/bun/deno all consume. An explicit
+ * `gjsify.example.node` wins; otherwise the node twin of the GJS entry is derived by
+ * swapping the `.gjs.<ext>` infix for `.node.<ext>` and probing `mjs`/`js`/`cjs` —
+ * the extension can differ, since `build:node` emits `dist/<name>.node.mjs` while the
+ * GJS entry is `dist/<name>.gjs.js`.
  */
 export function resolveNodeEntry(pkgDir) {
     const pkgJsonPath = join(pkgDir, 'package.json');
@@ -79,7 +64,6 @@ export function resolveNodeEntry(pkgDir) {
         throw new Error(`no package.json found at ${pkgDir}`);
     }
     const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
-    // 1. Explicit declaration wins.
     const explicit = pkg.gjsify?.example?.node;
     if (explicit) {
         const p = resolve(pkgDir, explicit);
@@ -88,7 +72,6 @@ export function resolveNodeEntry(pkgDir) {
         }
         return p;
     }
-    // 2. Derive from the GJS entry.
     const gjsEntry = pkg.gjsify?.main ?? (pkg.gjsify?.bin ? Object.values(pkg.gjsify.bin)[0] : undefined) ?? pkg.main;
     if (!gjsEntry) {
         throw new Error(`package "${pkg.name ?? pkgDir}" has no entry to derive a node bundle from — ` +

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

@@ -2,20 +2,15 @@ export interface ResolveNpmPackageOptions {
     /** Anchor directory to search from (typically the caller's cwd). */
     cwd?: string;
     /**
-     * Bundle path or module URL to anchor the bundle-side createRequire
-     * at. Pass `import.meta.url` from the call site so the bundle's
-     * own node_modules chain stays reachable even when the CLI is
-     * invoked from an unrelated cwd.
+     * Bundle path or module URL to anchor the bundle-side createRequire at. Pass
+     * `import.meta.url` from the call site so the bundle's own node_modules chain stays
+     * reachable even when the CLI is invoked from an unrelated cwd.
      */
     bundleUrl?: string;
 }
 /**
- * Resolve a bare npm specifier through multiple createRequire anchors.
- * Returns the absolute filesystem path of the resolved module, or null
- * if no anchor succeeded.
- *
- * Each anchor is tried in priority order — `GJSIFY_NODE_PATH` (highest)
- * → caller cwd → workspace root → bundle URL → parent-dir walk from
- * cwd. The first anchor whose `require.resolve()` succeeds wins.
+ * Resolve a bare npm specifier through the anchors listed above, returning the resolved
+ * module's absolute path or null when every anchor failed. Callers usually wrap the result in
+ * `pathToFileURL().href` before a dynamic `import(...)`.
  */
 export declare function resolveNpmPackage(specifier: string, opts?: ResolveNpmPackageOptions): string | null;

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

@@ -1,88 +1,59 @@
 // Multi-anchor npm-package resolver for the GJS-bundled CLI.
 //
-// GJS's native ESM loader has no node_modules walker — a bare
-// `await import('rolldown')` from inside the bundle throws
-// `ImportError: Module not found: rolldown` even when the package is
-// physically present in a node_modules above the caller's cwd.
+// GJS's native ESM loader has no node_modules walker — a bare `await import('rolldown')`
+// from inside the bundle throws `ImportError: Module not found: rolldown` even when the
+// package is physically present in a node_modules above the caller's cwd.
 //
-// `createRequire(import.meta.url)` works when invoked under Node, and
-// when invoked under GJS *with* `@gjsify/module`'s polyfill it walks the
-// node_modules chain from the URL it was anchored at. But it walks
-// only ONE chain — the one rooted at the anchor's parent. When the
-// bundle lives at `<install>/dist/cli.gjs.mjs` and the user runs
-// `gjs -m <install>/dist/cli.gjs.mjs build …` from a completely
-// unrelated cwd (`/tmp/sandbox/`) whose `node_modules` is the only
-// place rolldown is present, anchoring on the bundle URL misses it.
+// `createRequire(import.meta.url)` works under Node, and under GJS with `@gjsify/module`'s
+// polyfill it walks the node_modules chain from the URL it was anchored at — but only ONE
+// chain, the one rooted at the anchor's parent. When the bundle lives at
+// `<install>/dist/cli.gjs.mjs` and the user runs it from an unrelated cwd whose
+// `node_modules` is the only place rolldown is present, anchoring on the bundle URL misses
+// it. So a bare specifier is tried against several anchors, first hit wins:
 //
-// This helper resolves a bare specifier against multiple anchors in
-// order — the first one that resolves wins:
-//
-//   1. `GJSIFY_NODE_PATH` env override (colon-separated dir list,
-//      matches Node's NODE_PATH semantics — each entry is treated as a
-//      synthetic `node_modules` parent).
+//   1. `GJSIFY_NODE_PATH` env override (NODE_PATH semantics — each entry is a synthetic
+//      `node_modules` parent).
 //   2. Caller-supplied anchor dir (typically process.cwd()).
-//   3. Workspace root from `findWorkspaceRoot(anchorDir)` — finds the
-//      monorepo top when invoked from a sub-package directory.
+//   3. Workspace root from `findWorkspaceRoot(anchorDir)` — the monorepo top when invoked
+//      from a sub-package directory.
 //   4. Bundle path's parent chain (`import.meta.url` of THIS module).
-//   5. Parent dirs of the anchor (fallback for nested-without-workspace
-//      setups — matches `oxc-resolve.ts`'s walker).
-//
-// Returns the absolute path on success (the caller usually wraps it in
-// `pathToFileURL().href` before passing to dynamic `import(...)`).
-// Returns null when every anchor failed.
+//   5. Parent dirs of the anchor (nested-without-workspace layouts).
 //
-// Reference: `packages/infra/cli/src/commands/tsc.ts` (workspace-root +
-// cwd anchoring precedent) and `packages/infra/cli/src/utils/oxc-resolve.ts`
-// (parent-dir walker precedent).
+// Precedents: `commands/tsc.ts` (workspace-root + cwd anchoring), `utils/oxc-resolve.ts`
+// (parent-dir walker).
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { delimiter, join, resolve } from 'node:path';
 import { findWorkspaceRoot } from './workspace-root.js';
 /**
- * Resolve a bare npm specifier through multiple createRequire anchors.
- * Returns the absolute filesystem path of the resolved module, or null
- * if no anchor succeeded.
- *
- * Each anchor is tried in priority order — `GJSIFY_NODE_PATH` (highest)
- * → caller cwd → workspace root → bundle URL → parent-dir walk from
- * cwd. The first anchor whose `require.resolve()` succeeds wins.
+ * Resolve a bare npm specifier through the anchors listed above, returning the resolved
+ * module's absolute path or null when every anchor failed. Callers usually wrap the result in
+ * `pathToFileURL().href` before a dynamic `import(...)`.
  */
 export function resolveNpmPackage(specifier, opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
-    // 1. GJSIFY_NODE_PATH env override (NODE_PATH-like) — each entry is
-    //    treated as a directory whose own `node_modules` participates
-    //    in the lookup. Mirrors Node's NODE_PATH semantics.
     const envPath = process.env['GJSIFY_NODE_PATH'];
     if (envPath) {
-        // `path.delimiter`, not `':'` — Node's own NODE_PATH uses `;` on
-        // Windows, and this override claims to mirror NODE_PATH semantics. Split
-        // on a colon there and even a SINGLE entry is destroyed: `C:\tools`
-        // becomes `['C', '\tools']`, neither of which resolves, so the documented
-        // override silently did nothing on Windows and fell through to anchor 2.
-        // `commands/run.ts` and `utils/run-lifecycle-script.ts` already get this
-        // right; this was the site that was missed.
+        // `path.delimiter`, not `':'` — NODE_PATH uses `;` on Windows, where splitting on a
+        // colon destroys even a SINGLE entry (`C:\tools` → `['C', '\tools']`), so the
+        // documented override silently did nothing there and fell through to anchor 2.
         for (const dir of envPath.split(delimiter).filter(Boolean)) {
             const hit = tryResolveFromDir(specifier, resolve(dir));
             if (hit)
                 return hit;
         }
     }
-    // 2. Caller cwd → walk up for nearest node_modules/<pkg>.
     const fromCwd = tryResolveFromDir(specifier, cwd);
     if (fromCwd)
         return fromCwd;
-    // 3. Workspace root (monorepo top, if any).
     const wsRoot = findWorkspaceRoot(cwd);
     if (wsRoot && wsRoot !== cwd) {
         const fromWsRoot = tryResolveFromDir(specifier, wsRoot);
         if (fromWsRoot)
             return fromWsRoot;
     }
-    // 4. Bundle path's own parent chain — anchored at the bundle URL
-    //    so the install-time node_modules layout (e.g.
-    //    `<install>/node_modules/rolldown` next to the CLI bundle)
-    //    is reachable even when the user runs the bundle directly from
-    //    an unrelated cwd.
+    // Anchored at the bundle URL so the install-time layout (`<install>/node_modules/rolldown`
+    // next to the CLI bundle) stays reachable when the bundle is run from an unrelated cwd.
     if (opts.bundleUrl) {
         try {
             const req = createRequire(opts.bundleUrl);
@@ -92,11 +63,8 @@ export function resolveNpmPackage(specifier, opts = {}) {
             // Fall through.
         }
     }
-    // 5. Parent-dir walk from cwd as a last resort (nested
-    //    package layouts without a workspace marker). Capped at 8
-    //    levels to avoid runaway filesystem walks on pathological
-    //    layouts. Matches the depth `oxc-resolve.ts` uses for its
-    //    equivalent walker.
+    // Last resort for nested layouts without a workspace marker. Depth-capped so a
+    // pathological layout cannot turn a failed resolve into a filesystem walk to `/`.
     let dir = resolve(cwd, '..');
     for (let i = 0; i < 8; i++) {
         const hit = tryResolveFromDir(specifier, dir);
@@ -110,11 +78,9 @@ export function resolveNpmPackage(specifier, opts = {}) {
     return null;
 }
 /**
- * Attempt to resolve `specifier` as if a fictional source file at
- * `<dir>/__gjsify_resolve__.js` were doing the lookup. createRequire's
- * algorithm walks up from the anchor's parent for `node_modules/<pkg>`
- * so seeding it inside `<dir>` makes `<dir>/node_modules/<pkg>` the
- * first hit.
+ * Resolve `specifier` as if a fictional source file at `<dir>/__gjsify_resolve__.js` were
+ * doing the lookup: createRequire walks up from the anchor's PARENT for `node_modules/<pkg>`,
+ * so seeding it inside `<dir>` makes `<dir>/node_modules/<pkg>` the first hit.
  */
 function tryResolveFromDir(specifier, dir) {
     try {

package/lib/utils/resolve-plugin-by-name.d.ts

@@ -10,32 +10,24 @@ export interface PluginByName {
 /**
  * Strategy for turning a resolved plugin file path into its module namespace.
  *
- * On Node this is a plain dynamic `import()`. Under GJS it cannot be — GJS's
- * native ESM loader does not follow npm `package.json#exports` subpath maps
- * for bare specifiers, so importing a plugin whose source does
- * `import … from '@scope/pkg/internal-subpath'` throws
- * `Module not found: @scope/pkg/internal-subpath` even when the file is on
- * disk. The CLI injects a GJS strategy that first bundles the plugin to a
- * single self-contained ESM file (Rolldown resolves the exports map at
- * bundle time), then imports that. See `BuildAction.loadPluginViaGjsBundle`.
+ * A plain dynamic `import()` on Node, but under GJS it cannot be: GJS's native ESM loader does not
+ * follow npm `package.json#exports` subpath maps for bare specifiers, so a plugin whose source
+ * does `import … from '@scope/pkg/internal-subpath'` throws `Module not found` even with the file
+ * on disk. The CLI injects a GJS strategy that first bundles the plugin to one self-contained ESM
+ * file (Rolldown resolves the exports map at bundle time), then imports that — see
+ * `BuildAction.loadPluginViaGjsBundle`.
  */
 export type LoadPluginModule = (resolvedPath: string, pluginName: string) => Promise<Record<string, unknown>>;
 export interface ResolveUserPluginsOptions {
-    /**
-     * Override how a resolved plugin path is turned into its module
-     * namespace. Defaults to a direct dynamic `import()` (correct on Node).
-     */
+    /** Defaults to a direct dynamic `import()`, which is correct on Node. */
     loadModule?: LoadPluginModule;
 }
 /** Type-guard: a `PluginByName` shape rather than a Rolldown plugin object. */
 export declare function isPluginByName(value: unknown): value is PluginByName;
 /**
- * Resolve a list of mixed user plugins. Entries that are already plugin
- * objects pass through unchanged; entries shaped like `PluginByName` get
- * dynamically imported, instantiated with their `options`, and returned in
- * the same position. Resolution is anchored at `projectDir`.
- *
- * Throws when a name fails to resolve, when the chosen export is not a
- * function, or when the factory returns nothing.
+ * Resolve a list of mixed user plugins, anchored at `projectDir`. Plugin objects pass through
+ * unchanged; `PluginByName` entries are imported, instantiated with their `options`, and returned
+ * in the same position. Throws when a name fails to resolve, the chosen export is not a function,
+ * or the factory returns nothing.
  */
 export declare function resolveUserPlugins(plugins: ReadonlyArray<RolldownPluginOption | PluginByName>, projectDir: string, options?: ResolveUserPluginsOptions): Promise<RolldownPluginOption[]>;