@gjsify/cli 0.41.0 → 0.43.0

package/lib/utils/gjs-bundle-guard.js

@@ -37,6 +37,29 @@
 // links the module, so one bad specifier kills the whole bundle. A dynamic
 // `import('node:x')` throws lazily at its call site — a real bug, but not "the artifact
 // cannot load", and not what this gate is for.
+// ## `node:` was never the general case
+//
+// A bare `node:` specifier is one shape of ONE defect: the emitted module imports
+// something the GJS loader cannot resolve. GJS's ESM loader has no node_modules walker
+// and does not follow `package.json#exports`, so ANY bare specifier that survives into a
+// `--app gjs` bundle is dead on arrival — `ImportError: Module not found: <specifier>`,
+// again before one line runs. MEASURED: a `.tsx` entry with no JSX configuration makes
+// oxc default to the automatic runtime with `importSource: 'react'`, the bundle carries
+// `import { jsx } from "react/jsx-runtime"`, rolldown reports that as an
+// `UNRESOLVED_IMPORT` **warning**, `gjsify build` exits 0, and `gjs -m` on the artifact
+// dies with `ImportError: Module not found: react/jsx-runtime`. The `node:`-only guard
+// saw none of it.
+//
+// The legitimate-vs-broken line is the same one `plugins/unresolved-workspace-import.ts`
+// draws one layer up, and for the same reason a blanket "fail on any external" cannot be
+// used: a DECLARED external is a promise the caller made and must be honoured. So the
+// guard asks the target's OWN externals predicate (`createGjsExternalsPredicate`, the one
+// `externalsPlugin` enforces) rather than a second list that can drift, and it ignores
+// everything that is not a bare specifier — `gi://Gtk?version=4.0`, `file:`/`resource:`
+// URLs and relative sibling-chunk paths all name something GJS can resolve on its own.
+// `chunk.imports` also carries the fileNames of other EMITTED chunks, un-prefixed, so the
+// emitted set is passed in and excluded by name.
+import { locateSurvivingJsx, formatSurvivingJsx } from '@gjsify/rolldown-plugin-gjsify';
 /**
  * Bare `node:` specifiers a `--app gjs` bundle may keep as static imports.
  *
@@ -64,18 +87,104 @@ export function findDisallowedNodeImports(chunks, allowed = GJS_ALLOWED_NODE_IMP
     }
     return [...found].sort();
 }
-/** Throw when a built `--app gjs` bundle statically imports Node builtins. */
-export function assertGjsBundleLoadable(chunks, outfile) {
-    const offenders = findDisallowedNodeImports(chunks);
-    if (offenders.length === 0)
+/**
+ * Is `id` a BARE package specifier — the only shape GJS's ESM loader cannot resolve on
+ * its own?
+ *
+ * Relative and absolute paths name a file; anything carrying a URL scheme names a
+ * loader GJS either has (`gi:`, `file:`, `resource:`) or will report itself. `node:` is
+ * classified BEFORE this, because it has its own message and its own symptom.
+ * A win32 drive path (`C:\…`) matches the scheme test, which is the intended answer.
+ */
+export function isBareSpecifier(id) {
+    if (id.startsWith('.') || id.startsWith('/') || id.startsWith('\\'))
+        return false;
+    return !/^[A-Za-z][A-Za-z0-9+.-]*:/.test(id);
+}
+/**
+ * The distinct bare specifiers `chunks` statically import that nothing in this build
+ * promised to provide. Sorted, so the error message and any test are stable.
+ */
+export function findUnresolvableBareImports(chunks, policy = {}) {
+    const emitted = new Set(policy.emitted ?? []);
+    const found = new Set();
+    for (const chunk of chunks) {
+        for (const specifier of chunk.imports ?? []) {
+            // `node:` has its own diagnosis; classifying it here too would report one
+            // defect twice with two different fixes.
+            if (specifier.startsWith('node:'))
+                continue;
+            if (!isBareSpecifier(specifier))
+                continue;
+            if (emitted.has(specifier))
+                continue;
+            if (policy.isExternal?.(specifier))
+                continue;
+            found.add(specifier);
+        }
+    }
+    return [...found].sort();
+}
+/**
+ * Throw when a built `--app gjs` bundle statically imports something GJS cannot
+ * resolve — a bare `node:` builtin, or any other bare specifier this build did not
+ * declare external.
+ *
+ * The two are reported separately because they have different symptoms and different
+ * fixes: a `node:` specifier aborts with "Unsupported URI scheme", any other bare one
+ * with "Module not found", and the first means an alias target failed while the second
+ * means the dependency is simply not there.
+ */
+export function assertGjsBundleLoadable(chunks, outfile, policy = {}) {
+    const nodeOffenders = findDisallowedNodeImports(chunks);
+    if (nodeOffenders.length > 0) {
+        throw new Error(`gjsify build --app gjs: ${outfile} still imports ${nodeOffenders.length} bare \`node:\` module(s), ` +
+            'which stock GJS cannot resolve — it would fail at load with ' +
+            '"ImportError: Unsupported URI scheme for importing: node".\n' +
+            nodeOffenders.map((s) => `  - ${s}`).join('\n') +
+            '\n\nThese should have been aliased to their `@gjsify/*` polyfills. The usual cause is that the ' +
+            'alias TARGET could not be resolved, so the bundler externalised the import instead (look for ' +
+            'UNRESOLVED_IMPORT warnings above): e.g. a workspace checkout whose `@gjsify/*` packages have no ' +
+            'built `lib/`. Build the workspace first (`gjsify run build:infra`), or fix the resolution, then ' +
+            'rebuild.');
+    }
+    const bareOffenders = findUnresolvableBareImports(chunks, policy);
+    if (bareOffenders.length === 0)
         return;
-    throw new Error(`gjsify build --app gjs: ${outfile} still imports ${offenders.length} bare \`node:\` module(s), ` +
-        'which stock GJS cannot resolve — it would fail at load with ' +
-        '"ImportError: Unsupported URI scheme for importing: node".\n' +
-        offenders.map((s) => `  - ${s}`).join('\n') +
-        '\n\nThese should have been aliased to their `@gjsify/*` polyfills. The usual cause is that the ' +
-        'alias TARGET could not be resolved, so the bundler externalised the import instead (look for ' +
-        'UNRESOLVED_IMPORT warnings above): e.g. a workspace checkout whose `@gjsify/*` packages have no ' +
-        'built `lib/`. Build the workspace first (`gjsify run build:infra`), or fix the resolution, then ' +
-        'rebuild.');
+    throw new Error(`gjsify build --app gjs: ${outfile} statically imports ${bareOffenders.length} bare package ` +
+        'specifier(s) nothing in this build resolves or declares external. GJS has no node_modules walker ' +
+        'and does not follow `package.json#exports`, so it aborts the whole module graph at load with ' +
+        '"ImportError: Module not found: <specifier>".\n' +
+        bareOffenders.map((s) => `  - ${s}`).join('\n') +
+        '\n\nRolldown reports these as UNRESOLVED_IMPORT WARNINGS and re-emits the original specifier, ' +
+        'which is why the build reached this point at all. Likely causes:\n' +
+        '  - the package is not installed — add it as a dependency and `gjsify install`.\n' +
+        '  - a JSX entry with no JSX configuration: oxc then defaults to the automatic runtime with ' +
+        '`importSource: "react"`, so the bundle imports `react/jsx-runtime`. Point ' +
+        '`gjsify.bundler.transform.jsx.importSource` (or tsconfig `"jsxImportSource"`) at a runtime ' +
+        'this project HAS, or use `"jsx": "preserve"` plus the framework compiler that consumes it.\n' +
+        '  - the specifier is meant to be provided by the host at runtime — then say so, with ' +
+        '`gjsify.bundler.external`.');
+}
+/**
+ * Throw when a written `--app gjs` chunk is not parseable JavaScript because raw JSX
+ * survived into it. See `@gjsify/rolldown-plugin-gjsify`'s `utils/jsx-survival.ts` for
+ * why the oracle is a parse and not a pattern, and for the measurement.
+ *
+ * Called ONLY when the effective JSX setting PRESERVES JSX, which is the only way it can
+ * reach an artifact: oxc compiles it otherwise. That is not a cost dodge but the precise
+ * condition — though the cost is real, and measured: parsing the repo's largest bundle
+ * (`dist/cli.gjs.mjs`, 6.8 MB) takes ~850 ms, which is not worth paying on every GJS
+ * build to re-answer a question the transform already settled.
+ */
+export function assertGjsBundleParses(chunks, label) {
+    for (const chunk of chunks) {
+        const code = chunk.code;
+        if (typeof code !== 'string' || code.length === 0)
+            continue;
+        const found = locateSurvivingJsx(code);
+        if (found === null)
+            continue;
+        throw new Error(formatSurvivingJsx(found, chunk.fileName ? `${label} (${chunk.fileName})` : label));
+    }
 }

package/lib/utils/jsx-config.d.ts

@@ -0,0 +1,45 @@
+export interface JsxConfigInput {
+    /** `gjsify.bundler.transform.jsx`, exactly as configured (any of oxc's shapes). */
+    transformJsx?: unknown;
+    /** tsconfig `compilerOptions.jsx`. */
+    tsconfigJsx?: string | undefined;
+    /** tsconfig `compilerOptions.jsxImportSource` — names the runtime on its own. */
+    tsconfigJsxImportSource?: string | undefined;
+}
+export interface JsxConfigVerdict {
+    /** Did anything at all name a JSX policy? `false` means oxc's react default applies. */
+    configured: boolean;
+    /** Will JSX survive the transform, so that a compiler downstream must consume it? */
+    preserves: boolean;
+}
+/**
+ * Read the effective JSX policy.
+ *
+ * `configured` is deliberately satisfied by ANY value, `false` and an unrecognised string
+ * included: the gate's subject is a project that said nothing, not one whose setting this
+ * function fails to recognise. `transform.jsx: false` already fails the build loudly from
+ * inside oxc (measured: exit 1), which is a legitimate way to answer the question.
+ */
+export declare function describeJsxConfig(input: JsxConfigInput): JsxConfigVerdict;
+/**
+ * Flatten Rolldown's three `input` shapes (string, array, name→path record) into the
+ * paths themselves. Takes `unknown` on purpose: the caller holds a post-glob-expansion
+ * `EntryPoints` from the bundler package, and this module has no business importing that
+ * type to look at strings.
+ */
+export declare function collectEntryPaths(entryPoints: unknown): string[];
+/** The first entry point whose extension carries JSX, or `undefined`. */
+export declare function findJsxEntryPoint(entryPoints: readonly string[]): string | undefined;
+/**
+ * The refusal. Names the file, what the default would do to it, and the routes that answer
+ * the question — PRESERVE-plus-compiler first, because that is the one a GTK host wants:
+ * `@gjsify/gtk-host/jsx-runtime` is a TYPE surface whose `jsx()`/`jsxs()` THROW on purpose
+ * ("a TYPE surface, not an automatic JSX runtime"), so naming it as an `importSource`
+ * trades a build that fails for a build that dies at the first element. An error message
+ * that recommends the wrong fix is worse than one that recommends none.
+ *
+ * Scoped to `--app gjs` by its caller: on `--app node`/`--app browser` the react default
+ * is a legitimate answer for a project that has react installed, and refusing there would
+ * break real builds for a mistake they did not make.
+ */
+export declare function jsxConfigMissingError(entry: string): Error;

package/lib/utils/jsx-config.js

@@ -0,0 +1,98 @@
+// The pre-build JSX question: has this project configured JSX AT ALL, and does what it
+// configured PRESERVE JSX?
+//
+// Neither answer is available from the bundler, and both decide whether a `--app gjs`
+// build can produce anything loadable:
+//
+//  - NOTHING configured. oxc's transformer then applies its own default — the AUTOMATIC
+//    runtime with `importSource: 'react'` — so a `.tsx` entry emits
+//    `import { jsx } from "react/jsx-runtime"`. Rolldown reports the miss as an
+//    `UNRESOLVED_IMPORT` WARNING, re-emits the specifier, and the build exits 0; `gjs -m`
+//    on the artifact then dies with `ImportError: Module not found: react/jsx-runtime`.
+//    MEASURED end to end on a two-line `.tsx` (exit 0, then exit 1 under gjs). The
+//    artifact gate in `gjs-bundle-guard.ts` catches it too — but AFTER a full bundle, and
+//    it can only name `react/jsx-runtime`, not the `.tsx` the reader has to fix. And the
+//    default is never right for this target: `react/jsx-runtime` builds React elements,
+//    which render NOTHING on a GTK host even on the project that happens to have react
+//    installed.
+//  - `preserve` configured. JSX is meant to survive the transform so a framework compiler
+//    can take it (`babel-preset-solid`, the Vue SFC compiler). Whether one is REGISTERED
+//    is not knowable here — a plugin declares no JSX capability — so this only reports
+//    that JSX may survive, and the post-bundle syntax check decides.
+//
+// Both `gjsify.bundler.transform.jsx` and tsconfig `compilerOptions.jsx` reach oxc, and
+// the explicit `transform.jsx` WINS: measured with tsconfig `"jsx": "react-jsx"` +
+// `"jsxImportSource": "solid-js"` and `bundler.transform.jsx: "preserve"` — the artifact
+// kept raw JSX. Measured too, and the reason `preserve` is matched literally rather than
+// by "TS spellings that keep JSX": tsconfig `"jsx": "react-native"`, which TypeScript
+// documents as preserving, is NOT preserved by oxc — it compiled to runtime calls.
+/** The JSX-bearing extensions oxc classifies as JSX-capable. */
+const JSX_SOURCE_RE = /\.(?:jsx|tsx|mjsx|cjsx|mtsx|ctsx)$/i;
+/**
+ * Read the effective JSX policy.
+ *
+ * `configured` is deliberately satisfied by ANY value, `false` and an unrecognised string
+ * included: the gate's subject is a project that said nothing, not one whose setting this
+ * function fails to recognise. `transform.jsx: false` already fails the build loudly from
+ * inside oxc (measured: exit 1), which is a legitimate way to answer the question.
+ */
+export function describeJsxConfig(input) {
+    const { transformJsx, tsconfigJsx, tsconfigJsxImportSource } = input;
+    const configured = transformJsx !== undefined || tsconfigJsx !== undefined || tsconfigJsxImportSource !== undefined;
+    const preserves = transformJsx !== undefined ? transformJsx === 'preserve' : tsconfigJsx === 'preserve';
+    return { configured, preserves };
+}
+/**
+ * Flatten Rolldown's three `input` shapes (string, array, name→path record) into the
+ * paths themselves. Takes `unknown` on purpose: the caller holds a post-glob-expansion
+ * `EntryPoints` from the bundler package, and this module has no business importing that
+ * type to look at strings.
+ */
+export function collectEntryPaths(entryPoints) {
+    if (typeof entryPoints === 'string')
+        return [entryPoints];
+    if (Array.isArray(entryPoints))
+        return entryPoints.filter((e) => typeof e === 'string');
+    if (entryPoints !== null && typeof entryPoints === 'object') {
+        return Object.values(entryPoints).filter((e) => typeof e === 'string');
+    }
+    return [];
+}
+/** The first entry point whose extension carries JSX, or `undefined`. */
+export function findJsxEntryPoint(entryPoints) {
+    return entryPoints.find((entry) => JSX_SOURCE_RE.test(entry));
+}
+/**
+ * The refusal. Names the file, what the default would do to it, and the routes that answer
+ * the question — PRESERVE-plus-compiler first, because that is the one a GTK host wants:
+ * `@gjsify/gtk-host/jsx-runtime` is a TYPE surface whose `jsx()`/`jsxs()` THROW on purpose
+ * ("a TYPE surface, not an automatic JSX runtime"), so naming it as an `importSource`
+ * trades a build that fails for a build that dies at the first element. An error message
+ * that recommends the wrong fix is worse than one that recommends none.
+ *
+ * Scoped to `--app gjs` by its caller: on `--app node`/`--app browser` the react default
+ * is a legitimate answer for a project that has react installed, and refusing there would
+ * break real builds for a mistake they did not make.
+ */
+export function jsxConfigMissingError(entry) {
+    return new Error(`gjsify build --app gjs: ${entry} contains JSX, but nothing configures a JSX transform — not ` +
+        '`gjsify.bundler.transform.jsx`, and not tsconfig `compilerOptions.jsx`.\n\n' +
+        "Left unset, the bundler's transformer defaults to the automatic runtime with " +
+        '`importSource: "react"`, so the bundle would import `react/jsx-runtime`. GJS cannot resolve a ' +
+        'bare specifier at all (no node_modules walker, no `exports` map), so the build would exit 0 with ' +
+        'an UNRESOLVED_IMPORT warning and the artifact would abort at load with "ImportError: Module not ' +
+        'found: react/jsx-runtime" — and where react IS installed it would render React elements, which a ' +
+        'GTK host does nothing with.\n\n' +
+        'Configure one of:\n' +
+        '  - PRESERVED JSX plus the framework compiler that consumes it — the route a GTK host wants.\n' +
+        '    Set `"jsx": "preserve"` (in `gjsify.bundler.transform.jsx` or tsconfig\n' +
+        '    `compilerOptions.jsx`) and register the compiler under `gjsify.bundler.plugins`:\n' +
+        '    `babel-preset-solid` for Solid, the Vue SFC compiler for Vue. Pair it with tsconfig\n' +
+        '    `"jsxImportSource": "@gjsify/gtk-host"` for the TYPES.\n' +
+        '  - an automatic JSX runtime this project actually has:\n' +
+        '      "bundler": { "transform": { "jsx": { "importSource": "<pkg exporting ./jsx-runtime>" } } }\n' +
+        '    or the same in tsconfig: `"jsx": "react-jsx"` + `"jsxImportSource": "<pkg>"`. NOT\n' +
+        '    `@gjsify/gtk-host` — its `/jsx-runtime` is a TYPE surface and throws when called.\n' +
+        '  - `"jsx": false`, if this entry should contain no JSX at all: the transformer then\n' +
+        '    reports the JSX itself instead of compiling it for a runtime that is not there.');
+}

package/lib/utils/node-script.d.ts

@@ -1,4 +1,7 @@
+import type { SpawnCompletionContract } from './spawn.js';
 export interface RunNodeScriptOptions {
+    /** The caller's teardown contract, forwarded verbatim — see `RunGjsBundleOptions.completion`. */
+    completion: SpawnCompletionContract;
     /** Exit the process when the script succeeds. See `RunGjsBundleOptions.exitOnSuccess`. */
     exitOnSuccess?: boolean;
 }
@@ -9,4 +12,4 @@ export interface RunNodeScriptOptions {
  * Terminal callers pass `exitOnSuccess` (a GJS main loop armed by the spawn
  * parks the process otherwise); see {@link runGjsBundle}.
  */
-export declare function runNodeScript(file: string, extraArgs?: string[], options?: RunNodeScriptOptions): Promise<void>;
+export declare function runNodeScript(file: string, extraArgs: string[] | undefined, options: RunNodeScriptOptions): Promise<void>;

package/lib/utils/node-script.js

@@ -59,7 +59,7 @@ function scriptCacheEnabled() {
  * Terminal callers pass `exitOnSuccess` (a GJS main loop armed by the spawn
  * parks the process otherwise); see {@link runGjsBundle}.
  */
-export async function runNodeScript(file, extraArgs = [], options = {}) {
+export async function runNodeScript(file, extraArgs = [], options) {
     const scriptPath = resolve(file);
     if (!existsSync(scriptPath) || !statSync(scriptPath).isFile()) {
         console.error(`gjsify run --node-script: no such file: ${scriptPath}`);
@@ -72,7 +72,11 @@ export async function runNodeScript(file, extraArgs = [], options = {}) {
         // differ from what the runtime would have done itself. `quiet` because the echo
         // would print `node <file>` — what the package.json script already reads — behind
         // ~2 kB of native-library env, a dozen times per build chain.
-        await runRuntimeBundle(host, scriptPath, extraArgs, { exitOnSuccess: options.exitOnSuccess, quiet: true });
+        await runRuntimeBundle(host, scriptPath, extraArgs, {
+            completion: options.completion,
+            exitOnSuccess: options.exitOnSuccess,
+            quiet: true,
+        });
         return;
     }
     // Dynamic import keeps the bundler machinery out of the eager module graph
@@ -90,6 +94,22 @@ export async function runNodeScript(file, extraArgs = [], options = {}) {
             define: { 'import.meta.url': JSON.stringify(pathToFileURL(scriptPath).href) },
             globals,
             excludeGlobals,
+            // OPT-IN, and the widest of the three call sites — say what it does and
+            // does not mean. This function is reached through the `node` shim `gjsify
+            // run` puts on the PATH, so it also bundles a consumer's
+            // `"start": "node ./src/main.mjs"`, not only a repo build script. The
+            // discriminator is therefore "the CLI is bundling this on the project's
+            // behalf", NOT "this is toolchain".
+            //
+            // Narrowing it to the CLI's own tree was considered and does not work: in
+            // the ADR 0002 bootstrap the CLI is a GLOBAL install (`install.mjs` →
+            // `gjsify install -g`) and the script is in the user's clone, so no
+            // containment test relates them. What contains the hazard instead is
+            // PROJECT FIRST (a resolvable dependency is never shadowed) plus the
+            // `this.warn` the guard emits on every rescue, which names the package and
+            // the anchor — so a mixed artifact is visible in the build log rather than
+            // byte-identical to a healthy one.
+            resolveFromToolchain: true,
         });
     }
     catch (err) {
@@ -99,5 +119,9 @@ export async function runNodeScript(file, extraArgs = [], options = {}) {
     }
     // Quiet for the same reason as the node path above; the bundle's location is
     // deterministic (`node_modules/.cache/gjsify/node-scripts/<name>-<hash>/<name>.mjs`).
-    await runGjsBundle(bundlePath, extraArgs, { exitOnSuccess: options.exitOnSuccess, quiet: true });
+    await runGjsBundle(bundlePath, extraArgs, {
+        completion: options.completion,
+        exitOnSuccess: options.exitOnSuccess,
+        quiet: true,
+    });
 }

package/lib/utils/npm-oidc.js

@@ -80,11 +80,14 @@ export async function fetchGithubOidcToken(audience, log) {
         throw new OidcUnavailableError('GitHub Actions OIDC env vars (ACTIONS_ID_TOKEN_REQUEST_{URL,TOKEN}) not set. ' +
             'The calling workflow needs `permissions: id-token: write`.', 'no-env');
     }
-    // Append the audience by STRING CONCATENATION, as @actions/core's getIDToken does. Do NOT
-    // use `URL.searchParams.set` + `.href`: under GJS that serialization dropped the `audience`
-    // param, so GitHub issued an id-token with the DEFAULT audience (the repo API URL) and npm
-    // rejected an otherwise-valid token with 401 — repository/workflow_ref/sub all matched the
-    // Trusted Publisher, only `aud` was wrong.
+    // Append the audience by STRING CONCATENATION, as @actions/core's getIDToken does.
+    //
+    // fixed upstream in gjsify: `URL.searchParams.set` + `.href` used to DROP the parameter under
+    // GJS — the mutation never reached the serialisation — so GitHub issued an id-token with the
+    // DEFAULT audience (the repo API URL) and npm rejected an otherwise-valid token with 401:
+    // repository/workflow_ref/sub all matched the Trusted Publisher, only `aud` was wrong. The
+    // URL live view now works, so the ban is lifted; the concatenation stays because it is what
+    // the reference implementation does, not because the alternative is broken.
     const sep = url.includes('?') ? '&' : '?';
     const requestUrl = `${url}${sep}audience=${encodeURIComponent(audience)}`;
     log?.(`gjsify oidc: GET ${requestUrl.replace(bearer, '<bearer>')}`);

package/lib/utils/onboard-probe.d.ts

@@ -26,8 +26,31 @@ export interface ProbeOptions {
     retryDelayMs?: number;
     /** Injected delay (tests pass a no-op). Default: real `setTimeout`. */
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * Does this name exist on the registry? The PACKUMENT oracle — see
+     * {@link packumentExists}. Tests inject it; production uses the real fetch.
+     */
+    exists?: (registry: string, name: string) => Promise<boolean | null>;
 }
 export declare const PROBE_RETRY_DELAY_MS = 400;
+/**
+ * Does the registry serve a packument for this name?
+ *
+ * THE ORACLE, and the reason it exists: npm's trust endpoint answers `2xx` with an
+ * EMPTY LIST for a name that was never published. `classifyTrustList` reads that as
+ * `untrusted`, so `gjsify onboard` planned "already on npm, just needs trust" for a
+ * package that did not exist — it trusted the name, reported `0 to publish+trust`
+ * and published NOTHING. A bootstrap command reporting its own gap as closed, and
+ * it is why the v0.36.0 repair failed twice before anyone looked at the registry.
+ *
+ * `GET <registry>/<name>` is unauthenticated and needs no OTP, so it answers in the
+ * one situation that matters: a `--dry-run` before the maintainer has an OTP to
+ * hand, where every trust read is `401` and the plan is otherwise empty.
+ *
+ * `null` means UNDECIDED (network or an unexpected status) — never "absent". A
+ * bootstrap that publishes on a failed probe is worse than one that reports blocked.
+ */
+export declare function packumentExists(registry: string, name: string): Promise<boolean | null>;
 /** Default probe concurrency — kept SMALL so a single token never bursts npm. */
 export declare const DEFAULT_PROBE_CONCURRENCY = 4;
 /** Map a classified trust state to the action the onboard sweep should take. */

package/lib/utils/onboard-probe.js

@@ -11,6 +11,43 @@
 import { DEFAULT_REGISTRY, registryFor } from '@gjsify/npm-registry';
 import { classifyTrustList, trustUrl } from './trust-registry.js';
 export const PROBE_RETRY_DELAY_MS = 400;
+/**
+ * Does the registry serve a packument for this name?
+ *
+ * THE ORACLE, and the reason it exists: npm's trust endpoint answers `2xx` with an
+ * EMPTY LIST for a name that was never published. `classifyTrustList` reads that as
+ * `untrusted`, so `gjsify onboard` planned "already on npm, just needs trust" for a
+ * package that did not exist — it trusted the name, reported `0 to publish+trust`
+ * and published NOTHING. A bootstrap command reporting its own gap as closed, and
+ * it is why the v0.36.0 repair failed twice before anyone looked at the registry.
+ *
+ * `GET <registry>/<name>` is unauthenticated and needs no OTP, so it answers in the
+ * one situation that matters: a `--dry-run` before the maintainer has an OTP to
+ * hand, where every trust read is `401` and the plan is otherwise empty.
+ *
+ * `null` means UNDECIDED (network or an unexpected status) — never "absent". A
+ * bootstrap that publishes on a failed probe is worse than one that reports blocked.
+ */
+export async function packumentExists(registry, name) {
+    const base = registry.endsWith('/') ? registry.slice(0, -1) : registry;
+    try {
+        // `Accept` narrows the response to the abbreviated packument: the full one
+        // for a package like `@gjsify/cli` is megabytes, and existence is all we ask.
+        const res = await fetch(`${base}/${name.replace('/', '%2f')}`, {
+            method: 'GET',
+            headers: { accept: 'application/vnd.npm.install-v1+json' },
+        });
+        if (res.status === 404)
+            return false;
+        if (res.ok)
+            return true;
+        return null;
+    }
+    catch {
+        // A DNS or TLS failure is not evidence of absence.
+        return null;
+    }
+}
 /** Default probe concurrency — kept SMALL so a single token never bursts npm. */
 export const DEFAULT_PROBE_CONCURRENCY = 4;
 /** Map a classified trust state to the action the onboard sweep should take. */
@@ -48,6 +85,34 @@ export async function probeTrustState(request, ws, ctx, opts = {}) {
         res = await request('GET', url);
         state = classifyTrustList(res.status, res.json, classifyOpts);
     }
+    // `untrusted` is the ONE ambiguous answer: the trust endpoint returns `2xx` with
+    // an empty list both for "published, nobody trusted it" and for "no such name".
+    // Only that case pays for the extra read — `trusted` cannot be a missing package
+    // and `unpublished` already has its answer.
+    // Two questions, two endpoints. The trust list answers "who may publish this",
+    // and onboard also needs "does this name exist at all" — which it can only
+    // INFER from the trust list, and infers wrongly in both ambiguous states:
+    //
+    //   untrusted      npm serves 2xx and an EMPTY list for a name that was never
+    //                  published — byte-identical to a real package that simply has
+    //                  no trusted publisher configured.
+    //   auth-required  a 401 says nothing whatsoever about existence. It is also
+    //                  where EVERY package lands in a `--dry-run` run before the
+    //                  maintainer has an OTP to hand, which is exactly the moment
+    //                  the plan is being read to decide whether to proceed.
+    //
+    // The packument answers the question directly and unauthenticated, and a 404
+    // there is proof no OTP could change. Only these two states pay for the extra
+    // read: `trusted` cannot be a missing package, and `unpublished` already has
+    // its answer from the endpoint it just asked.
+    if (state === 'untrusted' || state === 'auth-required') {
+        const exists = await (opts.exists ?? packumentExists)(registry, ws.name);
+        // ONLY a definitive 404 reclassifies. `null` — network failure, unexpected
+        // status — leaves the state exactly as it was: a bootstrap that publishes
+        // on a failed read is worse than one that reports itself blocked.
+        if (exists === false)
+            state = 'unpublished';
+    }
     return { ws, registry, url, state, httpStatus: res.status, action: actionForState(state) };
 }
 /**

package/lib/utils/run-gjs.d.ts

@@ -1,4 +1,5 @@
 import { type NativeEnv } from './detect-native-packages.js';
+import { type SpawnCompletionContract } from './spawn.js';
 /**
  * Pure env computation: the typelib + shared-library search paths {@link runGjsBundle} would
  * inject into the spawned `gjs`, plus the formatted prefix for the `$ …` echo. Which library
@@ -15,6 +16,16 @@ export declare function computeNativeEnvForBundle(bundlePath: string, cwd?: stri
  * bundle's own node_modules tree.
  */
 export interface RunGjsBundleOptions {
+    /**
+     * The teardown contract of the command that will end this process — the same field,
+     * and the same reason, `spawnToCompletion` demands. Required rather than defaulted:
+     * absent, a caller silently inherited the side that ARMS the GJS main loop.
+     *
+     * Distinct from {@link exitOnSuccess}, which asks WHO performs the exit. `gjsify test`
+     * is `'exit'` — its handler exits at the end of `commands/test.ts` — while leaving
+     * `exitOnSuccess` off, because an exit HERE would truncate its multi-runtime loop.
+     */
+    completion: SpawnCompletionContract;
     /**
      * Exit this process with code 0 once the child succeeds. Under GJS, `ensureMainLoop()`
      * (armed by spawn) keeps the parent's GLib loop alive after the child exits, so a TERMINAL
@@ -31,4 +42,4 @@ export interface RunGjsBundleOptions {
      */
     quiet?: boolean;
 }
-export declare function runGjsBundle(bundlePath: string, extraArgs?: string[], options?: RunGjsBundleOptions): Promise<void>;
+export declare function runGjsBundle(bundlePath: string, extraArgs: string[] | undefined, options: RunGjsBundleOptions): Promise<void>;

package/lib/utils/run-gjs.js

@@ -9,9 +9,9 @@
 //
 // Env composition is split out as the pure `computeNativeEnvForBundle()` so the e2e tests can
 // assert the env without spawning gjs.
-import { spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { detectNativePackages, buildNativeEnv } from './detect-native-packages.js';
+import { describeExit, spawnToCompletion } from './spawn.js';
 /**
  * Pure env computation: the typelib + shared-library search paths {@link runGjsBundle} would
  * inject into the spawned `gjs`, plus the formatted prefix for the `$ …` echo. Which library
@@ -40,7 +40,7 @@ export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd(), inher
         .join(' ');
     return { env, envPrefix };
 }
-export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
+export async function runGjsBundle(bundlePath, extraArgs = [], options) {
     const { env: nativeEnv, envPrefix } = computeNativeEnvForBundle(bundlePath);
     const env = {
         ...process.env,
@@ -52,36 +52,29 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
     const gjsCommand = ['gjs', ...gjsArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
     if (!options.quiet)
         console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${gjsCommand}`);
-    const child = spawn('gjs', gjsArgs, { env, stdio: 'inherit' });
-    let failed = false;
-    // The CHILD's own exit code, re-raised verbatim; a spawn error (no `gjs` on PATH) has none
-    // of its own and falls back to 1. Collapsing every failure to 1 lost information callers
-    // act on — a chain reading `$?` to tell "tool failed" from "tool says no" saw 1 for both.
-    let childCode = 1;
-    await new Promise((resolvePromise, reject) => {
-        child.on('close', (code) => {
-            if (code !== 0) {
-                childCode = code ?? 1;
-                reject(new Error(`gjs exited with code ${code}`));
-            }
-            else {
-                resolvePromise();
-            }
-        });
-        child.on('error', reject);
-    }).catch((err) => {
+    // The CHILD's own exit code is re-raised verbatim; a spawn error (no `gjs` on PATH) has
+    // none of its own and falls back to 1. Collapsing every failure to 1 lost information
+    // callers act on — a chain reading `$?` to tell "tool failed" from "tool says no" saw 1
+    // for both.
+    const failed = (code) => {
+        // `process.exitCode` is set BEFORE exiting because `gjsify run <script>` dispatches a
+        // nested `gjsify run <bundle>` IN PROCESS: the outer command reads `process.exitCode`
+        // to propagate. Without it a failing `test:gjs` returned 0 through the `test` chain,
+        // and through `gjsify foreach test` in CI. The `return` guards a fall-through exit.
+        process.exitCode = code;
+        return process.exit(code);
+    };
+    let result;
+    try {
+        result = await spawnToCompletion('gjs', gjsArgs, { completion: options.completion, env });
+    }
+    catch (err) {
         console.error(err.message);
-        failed = true;
-    });
-    if (failed) {
-        // Set `process.exitCode` synchronously BEFORE exiting: under GJS `process.exit()` is
-        // deferred (the GLib main loop is armed), so under run.ts's in-process script dispatch
-        // execution returns to the caller, which propagates by reading `process.exitCode`.
-        // Without it, `gjsify run <script>` wrapping `gjsify run <bundle>` swallowed a non-zero
-        // gjs exit and returned 0 — masking a failing `test:gjs` in the `test` chain, and via
-        // `gjsify foreach test` in CI. The `return` guards a fall-through second `exit`.
-        process.exitCode = childCode;
-        return process.exit(childCode);
+        return failed(1);
+    }
+    if (result.code !== 0) {
+        console.error(`gjs exited with ${describeExit(result)}`);
+        return failed(result.code ?? 1);
     }
     // See RunGjsBundleOptions.exitOnSuccess — terminal callers opt in,
     // mid-flow callers (test.ts's runtime loop) keep the process alive.