@gjsify/cli 0.42.0 → 0.44.0

package/lib/types/config-data.d.ts

@@ -1,5 +1,5 @@
 import type { RolldownOptions, OutputOptions, RolldownPluginOption } from 'rolldown';
-import type { App } from '@gjsify/rolldown-plugin-gjsify';
+import type { App, SourceDialect } from '@gjsify/rolldown-plugin-gjsify';
 import type { ConfigDataLibrary, ConfigDataTypescript } from './index.js';
 /**
  * Plugin entry resolvable by package name from the project's `node_modules`, so
@@ -82,6 +82,20 @@ export interface ConfigData {
      * working ANSI colors). Default: true.
      */
     consoleShim?: boolean;
+    /**
+     * The dialect the SOURCE is written in (ADR 0032 § 2 + § 8). `'react-native'`
+     * aliases `react-native` onto `@gjsify/react-native` and gates every named
+     * import against the support table at BUILD time. `gjs` and `node` app builds.
+     * Default: unset.
+     *
+     * Opt-in and never inferred from the dependency list: a monorepo with a phone
+     * leg installs the real `react-native` on purpose, and redirecting the
+     * specifier for every build in that tree would change what that leg resolves.
+     *
+     * NOT `gjsify.runtimes['react-native']`, which answers the opposite question —
+     * see the header of `SourceDialect`.
+     */
+    dialect?: SourceDialect;
     /** Comma-separated global identifiers to register. Format: see CliBuildOptions. */
     globals?: string;
     /**
@@ -328,6 +342,38 @@ export interface AppMetadata {
      * https://www.freedesktop.org/software/appstream/docs/sect-Metadata-DesktopApps.html#tag-dapp-kudos
      */
     kudos?: string[];
+    /**
+     * File types this package DEFINES for the whole system — a shared-mime-info
+     * document staged into `share/mime/packages/`.
+     *
+     * Distinct from `provides.mimetypes`, which only says the app HANDLES a type.
+     * For a standard type (`text/plain`, `application/pdf`) handling is all you
+     * need: the distribution already defines it. For a type of your own
+     * (`application/x-bauplan`) handling it is not enough and the failure is
+     * silent — nothing on the system knows the type exists, so a `.bauplan` file
+     * is never recognised as one, `MimeType=` in the desktop entry matches
+     * nothing, and double-clicking the file does nothing at all. No error, no
+     * log line: the association simply never fires.
+     *
+     * Every type declared here is added to the handled set automatically, because
+     * defining a file type in your own package and then not opening it is not a
+     * thing anyone means to do.
+     */
+    mimeTypes?: Array<{
+        /** `<media>/<subtype>`, e.g. `application/x-bauplan`. */
+        type: string;
+        /**
+         * What a file manager shows instead of the raw type string. Required:
+         * a type with no comment is listed to the user as `application/x-bauplan`.
+         */
+        comment: string;
+        /** Filename patterns, e.g. `["*.bauplan"]`. */
+        globs?: string[];
+        /** A registered type to inherit from, e.g. `application/zip` for a zip container. */
+        subClassOf?: string;
+        /** Fallback icon name when no type-specific icon is installed. */
+        genericIcon?: string;
+    }>;
     /**
      * What this app provides to the system. `<binary>` is auto-included with the
      * value of `command` when omitted — AppStream needs it to register the binary
@@ -464,8 +510,66 @@ export interface ConfigDataShip extends AppMetadata {
     extraFiles?: Record<string, string>;
     /** Arguments the launcher appends before the user's own. */
     execArgs?: string[];
+    /**
+     * How `--target flatpak` builds the app: the runtime it links against and
+     * what the finished app is allowed to do.
+     *
+     * The new home of the `gjsify.flatpak` BUILD keys (ADR 0024 § 8). The old
+     * spelling still resolves and warns — the window, and what deliberately did
+     * NOT move, is `utils/ship/flatpak-config.ts`.
+     */
+    flatpak?: ShipFlatpakOptions;
 }
-/** Flatpak-toolchain config for the `gjsify flatpak` subcommand group. */
+/**
+ * The Flatpak knobs `gjsify ship` reads. Every one has a derived default.
+ *
+ * There is no `modules` / `extraModules` here, and that is a decision rather
+ * than an omission: under `ship` the module list IS the staged payload
+ * (`buildsystem: simple` + `cp -a stage/.`), and an escape hatch injecting
+ * arbitrary build modules would put the second staging model back in the tree —
+ * the one thing ADR 0024 § 8 gates the whole migration on. A project that has
+ * to BUILD something inside the sandbox still has `gjsify flatpak init` +
+ * `gjsify flatpak build`, unchanged.
+ */
+export interface ShipFlatpakOptions {
+    /**
+     * Runtime family. Default `'gnome'` — a GJS bundle needs GLib/GObject/GIO at
+     * runtime, and no GJS interpreter ships in the Freedesktop runtime.
+     */
+    runtime?: 'gnome' | 'freedesktop';
+    /** Runtime/SDK version, e.g. `'50'` for GNOME or `'24.08'` for Freedesktop. */
+    runtimeVersion?: string;
+    /**
+     * The branch the app is exported under — the last segment of
+     * `app/<id>/<arch>/<branch>`. Default `'stable'`, which is what Flathub
+     * publishes and what `flatpak install` resolves without being told.
+     */
+    branch?: string;
+    /** Extra SDK extensions, e.g. `['org.freedesktop.Sdk.Extension.llvm17']`. */
+    sdkExtensions?: string[];
+    /**
+     * Path components prepended to `PATH` inside the build sandbox. Derived from
+     * `sdkExtensions` when unset, because an extension whose `bin` is not on
+     * PATH is one the build cannot use.
+     */
+    appendPath?: string[];
+    /** Finish-args (capabilities). Default depends on `kind`: GUI args for an app, none for a CLI. */
+    finishArgs?: string[];
+    /** Cleanup globs applied to `/app`, e.g. `['/include', '/lib/pkgconfig']`. */
+    cleanup?: string[];
+}
+/**
+ * Flatpak-toolchain config for the `gjsify flatpak` subcommand group.
+ *
+ * Six of these keys — `runtime`, `runtimeVersion`, `sdkExtensions`,
+ * `appendPath`, `finishArgs`, `cleanup` — have a second home at
+ * {@link ShipFlatpakOptions}, and `gjsify ship` warns when it reads them from
+ * here (ADR 0024 § 8; the window is `utils/ship/flatpak-config.ts`). They are
+ * NOT marked `@deprecated`: for the subcommands in this group they are still
+ * the only spelling, and those commands have not moved under `ship` yet
+ * (`status/open-todos.md`). Nothing else in this block is deprecated at all —
+ * the {@link AppMetadata} half is a designed alias, not a legacy one.
+ */
 export interface ConfigDataFlatpak extends AppMetadata {
     /** Reverse-DNS app id, e.g. `eu.jumplink.Learn6502`. Defaults to `package.json#name` if it looks like a reverse-DNS id. */
     appId?: string;

package/lib/utils/flatpak-runtime.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Default GNOME-Platform runtime version. Bumped per release window.
+ * GNOME 50 = April 2026 stable; tracked in
+ * https://docs.flathub.org/docs/for-app-authors/requirements.
+ */
+export declare const DEFAULT_GNOME_RUNTIME_VERSION = "50";
+/** Default Freedesktop-Platform runtime version (LTS-ish). */
+export declare const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = "24.08";
+/** Permissive GUI defaults for GTK4 + Adwaita apps. */
+export declare const DEFAULT_GUI_FINISH_ARGS: string[];
+/** Lean defaults for headless CLI tools — no display, no GPU. */
+export declare const DEFAULT_CLI_FINISH_ARGS: string[];
+/**
+ * The runtime keys, structurally — not `ConfigDataFlatpak`.
+ *
+ * Two config blocks answer this question now (`gjsify.flatpak` and
+ * `gjsify.ship.flatpak`, § the deprecation window in `utils/ship/flatpak-config.ts`),
+ * and a resolver typed to one of them would have to be duplicated for the other.
+ */
+export interface RuntimeSelection {
+    runtime?: string;
+    runtimeVersion?: string;
+}
+export interface ResolvedRuntime {
+    runtime: 'gnome' | 'freedesktop';
+    runtimeId: string;
+    sdk: string;
+    runtimeVersion: string;
+}
+/**
+ * Pick the runtime + sdk + version triple from config + CLI overrides.
+ * `--runtime` and `--runtime-version` flags win over config values.
+ */
+export declare function resolveRuntime(config: RuntimeSelection | undefined, overrides: RuntimeSelection): ResolvedRuntime;
+/**
+ * `append-path` for the build sandbox, derived from the declared SDK extensions.
+ *
+ * `/app/bin` is appended last so a build command finds the app's own binaries
+ * without knowing where they landed.
+ */
+export declare function deriveAppendPath(sdkExtensions: readonly string[]): string[];

package/lib/utils/flatpak-runtime.js

@@ -0,0 +1,54 @@
+// Which runtime a Flatpak is built against, and what the finished app may do.
+//
+// Lifted out of `commands/flatpak/` when `gjsify ship --target flatpak` became
+// the second caller (ADR 0024 § 8). Same move, same reason, as
+// `utils/app-metadata.ts`: these are facts about the APP, not about whichever
+// command happens to render them, and the second copy is the one that drifts —
+// a `DEFAULT_GNOME_RUNTIME_VERSION` bumped in one place and not the other
+// produces a `ship` Flatpak and a `flatpak init` Flatpak targeting different
+// GNOME releases from the same `package.json`.
+/**
+ * Default GNOME-Platform runtime version. Bumped per release window.
+ * GNOME 50 = April 2026 stable; tracked in
+ * https://docs.flathub.org/docs/for-app-authors/requirements.
+ */
+export const DEFAULT_GNOME_RUNTIME_VERSION = '50';
+/** Default Freedesktop-Platform runtime version (LTS-ish). */
+export const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = '24.08';
+/** Permissive GUI defaults for GTK4 + Adwaita apps. */
+export const DEFAULT_GUI_FINISH_ARGS = ['--device=dri', '--share=ipc', '--socket=fallback-x11', '--socket=wayland'];
+/** Lean defaults for headless CLI tools — no display, no GPU. */
+export const DEFAULT_CLI_FINISH_ARGS = [];
+/**
+ * Pick the runtime + sdk + version triple from config + CLI overrides.
+ * `--runtime` and `--runtime-version` flags win over config values.
+ */
+export function resolveRuntime(config, overrides) {
+    const runtime = (overrides.runtime ?? config?.runtime ?? 'gnome');
+    if (runtime !== 'gnome' && runtime !== 'freedesktop') {
+        throw new Error(`gjsify flatpak: unknown runtime "${runtime}" (expected "gnome" or "freedesktop")`);
+    }
+    const runtimeVersion = overrides.runtimeVersion ??
+        config?.runtimeVersion ??
+        (runtime === 'gnome' ? DEFAULT_GNOME_RUNTIME_VERSION : DEFAULT_FREEDESKTOP_RUNTIME_VERSION);
+    if (runtime === 'gnome') {
+        return { runtime, runtimeId: 'org.gnome.Platform', sdk: 'org.gnome.Sdk', runtimeVersion };
+    }
+    return { runtime, runtimeId: 'org.freedesktop.Platform', sdk: 'org.freedesktop.Sdk', runtimeVersion };
+}
+/**
+ * `append-path` for the build sandbox, derived from the declared SDK extensions.
+ *
+ * `/app/bin` is appended last so a build command finds the app's own binaries
+ * without knowing where they landed.
+ */
+export function deriveAppendPath(sdkExtensions) {
+    const out = [];
+    for (const ext of sdkExtensions) {
+        const m = /^org\.freedesktop\.Sdk\.Extension\.([A-Za-z0-9-]+)$/.exec(ext);
+        if (m)
+            out.push(`/usr/lib/sdk/${m[1]}/bin`);
+    }
+    out.push('/app/bin');
+    return out;
+}

package/lib/utils/gjs-bundle-guard.d.ts

@@ -1,9 +1,11 @@
-/** The one bundler-output field this guard needs, from either engine. */
+/** The bundler-output fields this guard needs, from either engine. */
 export interface GuardedChunk {
     /** Emitted chunk name, for the error message. */
     fileName?: string;
     /** External specifiers the chunk STATICALLY imports (rollup/rolldown contract). */
     imports?: readonly string[];
+    /** Emitted source, for the syntax check. Present on a written chunk on both engines. */
+    code?: string;
 }
 /**
  * Bare `node:` specifiers a `--app gjs` bundle may keep as static imports.
@@ -20,5 +22,57 @@ export declare const GJS_ALLOWED_NODE_IMPORTS: readonly string[];
  * allowlist. Sorted, so the error message and any test are stable.
  */
 export declare function findDisallowedNodeImports(chunks: readonly GuardedChunk[], allowed?: readonly string[]): string[];
-/** Throw when a built `--app gjs` bundle statically imports Node builtins. */
-export declare function assertGjsBundleLoadable(chunks: readonly GuardedChunk[], outfile: string): void;
+/**
+ * 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 declare function isBareSpecifier(id: string): boolean;
+/** What the caller must tell the guard about this build's own promises. */
+export interface GjsImportPolicy {
+    /**
+     * The target's own externals predicate — pass
+     * `createGjsExternalsPredicate(userExternal)`, the same one `externalsPlugin`
+     * enforces, so the guard and the build cannot disagree about what was declared.
+     * Omitted, nothing counts as declared.
+     */
+    isExternal?: (id: string) => boolean;
+    /**
+     * Every fileName the build emitted. `chunk.imports` lists sibling CHUNKS by fileName
+     * with no `./` prefix, which is indistinguishable from a bare package specifier — so
+     * the set is excluded by name rather than guessed at by shape.
+     */
+    emitted?: readonly string[];
+}
+/**
+ * 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 declare function findUnresolvableBareImports(chunks: readonly GuardedChunk[], policy?: GjsImportPolicy): string[];
+/**
+ * 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 declare function assertGjsBundleLoadable(chunks: readonly GuardedChunk[], outfile: string, policy?: GjsImportPolicy): void;
+/**
+ * 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 declare function assertGjsBundleParses(chunks: readonly GuardedChunk[], label: string): void;

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/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. */