@gjsify/cli 0.42.0 → 0.43.0

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

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/ship/deb.d.ts

@@ -1,7 +1,7 @@
-import type { PayloadEntry } from './payload.js';
-import type { ShipSettings } from './types.js';
+import { type PayloadEntry } from './payload.js';
+import type { PackSettings } from './types.js';
 export interface DebInputs {
-    settings: ShipSettings;
+    settings: PackSettings;
     /** The staged payload, prefix-relative. */
     payload: readonly PayloadEntry[];
     /** Install prefix, e.g. `/usr`. */

package/lib/utils/ship/deb.js

@@ -20,8 +20,9 @@ import { createArArchive } from './ar.js';
 import { formatDebDepend } from './depends.js';
 import { gzipDeterministic } from './gzip.js';
 import { renderDebScripts } from './scripts.js';
+import { readPayloadFacts } from './payload.js';
 export async function buildDeb(inputs) {
-    const { settings, payload, mtime } = inputs;
+    const { payload, mtime } = inputs;
     const prefix = inputs.prefix.replace(/^\/+/, '');
     const named = payload.map((entry) => ({ ...entry, tarPath: `./${posix.join(prefix, entry.path)}` }));
     const directories = ancestorDirectories(named.map((entry) => entry.tarPath));
@@ -44,7 +45,10 @@ export async function buildDeb(inputs) {
         { name: './control', body: control, mode: 0o644, mtime },
         { name: './md5sums', body: md5sums, mode: 0o644, mtime },
     ];
-    const maintainerScripts = renderDebScripts(settings, inputs.prefix);
+    // From the PAYLOAD, not the settings: the maintainer scripts refresh exactly the
+    // directories this package wrote into, and since ADR 0024 § A2 this packer also runs on a
+    // host that has the staged tree and no project to ask.
+    const maintainerScripts = renderDebScripts(readPayloadFacts(payload), inputs.prefix);
     for (const [name, body] of Object.entries(maintainerScripts)) {
         // dpkg refuses a maintainer script outside 0555–0775 with the mode in
         // the error, so this is 0755 rather than "whatever the source had".

package/lib/utils/ship/depends.d.ts

@@ -14,16 +14,19 @@ import type { FormatId } from './types.js';
  * is how a project whose bundle really does run on older GJS lowers it.
  */
 export declare const DEFAULT_GJS_FLOOR = "1.86";
-/**
- * Warn when the derived floor cannot be satisfied by a released Debian.
- * Returns the warning lines; empty when the floor is fine.
- */
 export declare function warnAboutGjsFloor(format: FormatId, floor: string): string[];
 export interface DependsInputs {
     /** GI namespaces the bundle imports, in `Ns-Version` spelling. */
     namespaces: readonly string[];
-    /** `'app'` installs a desktop entry and icons; `'cli'` does not. */
-    kind: 'app' | 'cli';
+    /**
+     * Whether the payload installs into `share/icons/hicolor/`.
+     *
+     * Was `kind: 'app' | 'cli'`, which is a proxy for the question and not the question:
+     * `hicolor-icon-theme` is depended on because it OWNS that directory, so an app that
+     * installs no icon used to declare a dependency it never touched. Derived from the payload
+     * (`readPayloadFacts`), which is also the only thing the packing host has (ADR 0024 § A2).
+     */
+    hasIcons: boolean;
     /** Whether the payload installs GSettings schemas. */
     hasSchemas: boolean;
     /** User-supplied additions for this format. */

package/lib/utils/ship/depends.js

@@ -35,14 +35,34 @@
  * is how a project whose bundle really does run on older GJS lowers it.
  */
 export const DEFAULT_GJS_FLOOR = '1.86';
+/**
+ * The package providing `glib-compile-schemas`, per format.
+ *
+ * A record, not `format === 'deb' ? … : …`. The ternary reads as a two-way
+ * choice and is really "deb, or ELSE rpm's package name" — measured on a third
+ * format, `dmg` got `glib2`, at exit 0, in the `Depends:` of a package that has
+ * no such thing. Adding a `FormatId` now fails to build here instead.
+ */
+const SCHEMA_COMPILER_PACKAGE = { deb: 'libglib2.0-bin', rpm: 'glib2' };
 /** Debian's `gjs` versions per suite, as measured 2026-08-15 — see {@link warnAboutGjsFloor}. */
 const DEBIAN_GJS = 'trixie ships 1.82.3 and forky 1.88.1; 1.84 and 1.86 were skipped';
 /**
  * Warn when the derived floor cannot be satisfied by a released Debian.
  * Returns the warning lines; empty when the floor is fine.
  */
+/**
+ * Which formats this Debian-suite warning is ABOUT.
+ *
+ * A `Record<FormatId, …>` and not `format !== 'deb'`: the negative form answers
+ * for every format that will ever exist, and answers "stay quiet" — so a third
+ * format would inherit silence about a floor nobody has checked for its distro,
+ * with no compile error. As a record, adding a `FormatId` fails to build until
+ * someone decides. `rpm` is false because Fedora ships a current GJS, which is a
+ * measured fact about Fedora, not a default.
+ */
+const GJS_FLOOR_IS_DEBIAN_NEWS = { deb: true, rpm: false };
 export function warnAboutGjsFloor(format, floor) {
-    if (format !== 'deb')
+    if (!GJS_FLOOR_IS_DEBIAN_NEWS[format])
         return [];
     // Only a floor forky ACTUALLY satisfies is quiet. The first cut tested
     // `>= 1.88.1` and therefore went silent for 1.90 and 2.0 as well — the
@@ -171,7 +191,9 @@ export function deriveDepends(format, inputs) {
             'have to. (`gjsify.ship.depends.<format>` is for dependencies that are not typelibs at all — it ' +
             'appends, and deliberately does not silence this.)');
     }
-    if (inputs.kind === 'app')
+    // The package that owns `/usr/share/icons/hicolor` — so this follows the icons, not the
+    // app/cli distinction that used to stand in for them.
+    if (inputs.hasIcons)
         out.push('hicolor-icon-theme');
     // The package that ships `glib-compile-schemas`, NOT `gsettings-desktop-schemas`
     // (which ships GNOME's own `org.gnome.desktop.*` schemas and has nothing to
@@ -182,7 +204,7 @@ export function deriveDepends(format, inputs) {
     // `Gio.Settings.new()` aborts the app — an install that succeeds and an app
     // that does not start.
     if (inputs.hasSchemas)
-        out.push(format === 'deb' ? 'libglib2.0-bin' : 'glib2');
+        out.push(SCHEMA_COMPILER_PACKAGE[format]);
     out.push(...inputs.extra);
     // Set-dedupe keeps first-insertion order, so `gjs` stays first and the
     // list is stable across runs.