@gjsify/cli 0.36.0 → 0.38.0

package/lib/utils/prompt.js

@@ -1,20 +1,17 @@
 // Interactive prompts for `gjsify login` / `gjsify trust`.
 //
-// On a TTY every prompt runs inside a single RAW-mode session (`runRawSession`)
-// that reads key-by-key with manual echo and a guaranteed cooked-mode restore
-// (try/finally). This deliberately does NOT rely on the terminal's cooked
-// line-discipline nor on the shared `process.stdin` resume/pause cycle:
-//   - The old visible prompt read a cooked line via `process.stdin` 'data'
-//     events. With the line discipline in an unexpected state (e.g. ICRNL off
-//     after a prior raw prompt) Enter arrived as a bare `\r` that never
-//     terminated the cooked line — the prompt hung showing `name^M`. The
-//     resume/pause churn on the shared stdin singleton between two sequential
-//     prompts also intermittently dropped the line or resolved it empty.
-//   - Reading raw + handling `\r`/`\n` ourselves removes both failure modes.
+// On a TTY every prompt runs inside a single RAW-mode session (`runRawSession`) reading
+// key-by-key with manual echo and a guaranteed cooked-mode restore. It deliberately relies on
+// neither the terminal's cooked line-discipline nor the shared `process.stdin` resume/pause
+// cycle: a cooked read with the line discipline in an unexpected state (ICRNL off after a prior
+// raw prompt) saw Enter arrive as a bare `\r` that never terminated the line, hanging the prompt
+// showing `name^M`, and the resume/pause churn on the shared stdin singleton between sequential
+// prompts intermittently dropped the line or resolved it empty. Handling `\r`/`\n` here removes
+// both failure modes.
 //
-// Raw mode (via @gjsify/process → terminal-native) now also clears ISIG, so
-// Ctrl-C is delivered as a `\x03` keystroke we handle (restore + exit) instead
-// of a SIGINT that would kill the process leaving the terminal in raw mode.
+// Raw mode (via @gjsify/process → terminal-native) also clears ISIG, so Ctrl-C arrives as a
+// `\x03` keystroke handled below (restore + exit) rather than a SIGINT that would kill the
+// process leaving the terminal in raw mode.
 //
 // Non-TTY stdin (piped input, CI) keeps a plain line read so
 // `printf 'user\npass\n' | gjsify login` still works.
@@ -26,10 +23,9 @@ function isTtyStdin() {
     return Boolean(stdin.isTTY) && typeof stdin.setRawMode === 'function';
 }
 /**
- * Pure key handler for the raw-mode line editor — the single source of truth
- * for how a keystroke updates the buffer + echo. Kept pure (no I/O) so it is
- * unit-testable: this is what makes Enter (`\r` OR `\n`) reliably submit, masks
- * passwords, and treats Ctrl-C as an interrupt rather than text.
+ * Pure key handler for the raw-mode line editor — the single source of truth for how a keystroke
+ * updates the buffer + echo. Pure (no I/O) so the rules are unit-testable: Enter is `\r` OR `\n`,
+ * passwords mask, and Ctrl-C is an interrupt rather than text.
  */
 export function applyKey(buf, ch, mask) {
     if (ch === '\r' || ch === '\n') {

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

@@ -3,36 +3,31 @@ export type Diagnose404Reason = 'dead-token' | 'live-token-404' | 'unknown';
 export interface Diagnose404Result {
     /** Discriminant — drives the JSON shape + exit-code path in the caller. */
     reason: Diagnose404Reason;
-    /** Username from `/-/whoami` when reason === 'live-token-404'. */
+    /** Set only when `reason === 'live-token-404'`. */
     username?: string;
-    /** Multi-line, human-friendly hint ready for stderr emission. */
+    /** Multi-line hint, ready for stderr as-is. */
     message: string;
 }
 interface Diagnose404Input {
     /** Full package name including scope, e.g. `@gjsify/abort-controller`. */
     packageName: string;
-    /** Pinned version we tried to publish. */
     version: string;
-    /** Registry URL (with or without trailing slash). */
+    /** Registry URL, with or without trailing slash. */
     registry: string;
-    /** Parsed .npmrc — used to derive Authorization on the whoami probe. */
+    /** Source of the Authorization header on the whoami probe. */
     npmrc: NpmrcConfig | undefined;
 }
 /**
- * Probe `/-/whoami` to disambiguate the 404 cause. Best-effort: any thrown
- * error / non-2xx falls through to `reason: 'unknown'` so the caller's
- * generic error path runs untouched.
- *
- * Pure async I/O — no side effects, no process.exit, no console writes.
- * The caller owns presentation (stderr vs stdout, plain vs JSON).
+ * Probe `/-/whoami` to disambiguate the 404 cause. Best-effort: a thrown error or
+ * non-2xx yields `reason: 'unknown'`, leaving the caller's generic error path
+ * untouched. No side effects and no writes — the caller owns presentation.
  */
 export declare function diagnose404(input: Diagnose404Input): Promise<Diagnose404Result>;
 /**
- * Heuristic: is the 404 body the "dead-token-or-missing-package" shape?
- * npm's PUT returns plain text `Not Found` (sometimes empty body). We trigger
- * the diagnostic for both, plus for the JSON `{"error":"Not Found"}` shape
- * just in case. Other 404 bodies (e.g. with a structured npm error code)
- * keep the generic error path.
+ * Is the 404 body the "dead-token-or-missing-package" shape? npm's PUT answers
+ * with plain-text `Not Found` or an empty body; the JSON `{"error":"Not Found"}`
+ * form is accepted too. Any other 404 body — notably one carrying a structured npm
+ * error code — keeps the generic error path.
  */
 export declare function is404DiagnosticCandidate(body: string): boolean;
 export {};

package/lib/utils/publish-diagnose.js

@@ -1,31 +1,19 @@
 // Dead-token vs new-package diagnostic for `gjsify publish`.
 //
-// When the publish PUT returns `404 Not Found` (body `"Not Found"` or empty)
-// it is ambiguous between two very different situations:
+// A `404 Not Found` on the publish PUT is npm's shape for two very different
+// causes, and guessing sends the user down the wrong path entirely: the
+// `_authToken` has been revoked/expired (npm answers an unrecognised bearer with
+// 404, not 401), or the scoped package genuinely is not on npm yet and needs the
+// first-publish bootstrap from AGENTS.md.
 //
-//   1. The `_authToken` in ~/.npmrc has been revoked / expired. The npm
-//      registry's 404 is its way of saying "we don't recognize this
-//      bearer". Easy to mistake for a missing-package error and send the
-//      user down the wrong path (Trusted-Publisher-bootstrap setup).
-//   2. The scoped `@gjsify/<pkg>` genuinely doesn't exist on npm yet —
-//      the first-publish bootstrap step from AGENTS.md.
-//
-// `GET /-/whoami` with the SAME Authorization header disambiguates: a live
-// token returns `{"username": "..."}`, a dead token returns `{}` (status 200
-// in both cases — the empty body is npm's signal).
-//
-// `npm publish` from npm-cli handles dead tokens with `401 EOTP` + a clear
-// "one-time-password or refresh the token" hint. The 404 path is npm's
-// PUT-specific shape and `gjsify publish` previously just printed the
-// opaque body. This helper closes the diagnostic gap.
+// `GET /-/whoami` with the SAME Authorization header disambiguates: a live token
+// returns `{"username": "…"}`, a dead one returns `{}` — status 200 for both, so
+// the EMPTY BODY is the signal.
 import { whoami } from '@gjsify/npm-registry';
 /**
- * Probe `/-/whoami` to disambiguate the 404 cause. Best-effort: any thrown
- * error / non-2xx falls through to `reason: 'unknown'` so the caller's
- * generic error path runs untouched.
- *
- * Pure async I/O — no side effects, no process.exit, no console writes.
- * The caller owns presentation (stderr vs stdout, plain vs JSON).
+ * Probe `/-/whoami` to disambiguate the 404 cause. Best-effort: a thrown error or
+ * non-2xx yields `reason: 'unknown'`, leaving the caller's generic error path
+ * untouched. No side effects and no writes — the caller owns presentation.
  */
 export async function diagnose404(input) {
     const { packageName, version, registry, npmrc } = input;
@@ -85,11 +73,10 @@ function formatUnknown(name, version) {
     return `gjsify publish: ${name}@${version} — 404 Not Found`;
 }
 /**
- * Heuristic: is the 404 body the "dead-token-or-missing-package" shape?
- * npm's PUT returns plain text `Not Found` (sometimes empty body). We trigger
- * the diagnostic for both, plus for the JSON `{"error":"Not Found"}` shape
- * just in case. Other 404 bodies (e.g. with a structured npm error code)
- * keep the generic error path.
+ * Is the 404 body the "dead-token-or-missing-package" shape? npm's PUT answers
+ * with plain-text `Not Found` or an empty body; the JSON `{"error":"Not Found"}`
+ * form is accepted too. Any other 404 body — notably one carrying a structured npm
+ * error code — keeps the generic error path.
  */
 export function is404DiagnosticCandidate(body) {
     const trimmed = body.trim();

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;