@gjsify/cli 0.64.1 → 0.64.2-next.255

package/lib/actions/build.d.ts

@@ -94,6 +94,22 @@ export declare class BuildAction {
      * on the prediction, not a second opinion.
      */
     private assertNodeOutputGlobals;
+    /**
+     * Post-bundle gate for `--app nativescript`: every GI namespace the emitted
+     * bundle loads has to be one the APK was told to carry (ADR 0117 § 2).
+     *
+     * THE ORACLE IS THE EMITTED FILE, like the two gates above and for the same
+     * reason — that is the artifact that gets installed. What it reads there is a
+     * LOWER BOUND, which is why only one direction is fatal: a namespace the scan
+     * found and the config omits WILL be missing from the APK, while a namespace the
+     * config names and the scan missed may simply be reached in a way no static read
+     * can see (`planGiSelection` carries the full argument).
+     *
+     * Android is the one target where this is not advice. A `.deb` that under-declares
+     * its typelibs can still be fixed by installing a package; an APK carries its
+     * whole GI stack or does without it.
+     */
+    private assertNativescriptGiSelected;
     /**
      * Post-bundle step for a `--app browser` HTML entry: write the processed
      * `index.html` beside the JS bundle, with the entry `<script>`'s `src`

package/lib/actions/build.js

@@ -15,6 +15,8 @@ import { collectEntryPaths, describeJsxConfig, findJsxEntryPoint, jsxConfigMissi
 import { giSystemProbes } from '../utils/gi-runtime-paths.js';
 import { escapeRawNulForGjs } from '../utils/gjs-source-escape.js';
 import { assertNodeBundleGlobalsShimmed } from '../utils/node-bundle-guard.js';
+import { scanGiNamespaces } from '../utils/ship/gi-namespaces.js';
+import { planGiSelection } from '../utils/ship/gi-selection.js';
 import { DEP_CHANGE_LOCKFILES } from '../utils/package-inputs.js';
 const DEFAULT_GJS_SHEBANG = '#!/usr/bin/env -S gjs -m';
 /**
@@ -439,6 +441,51 @@ export class BuildAction {
             assertNodeBundleGlobalsShimmed(code, item.fileName ? `${label} (${item.fileName})` : label);
         }
     }
+    /**
+     * Post-bundle gate for `--app nativescript`: every GI namespace the emitted
+     * bundle loads has to be one the APK was told to carry (ADR 0117 § 2).
+     *
+     * THE ORACLE IS THE EMITTED FILE, like the two gates above and for the same
+     * reason — that is the artifact that gets installed. What it reads there is a
+     * LOWER BOUND, which is why only one direction is fatal: a namespace the scan
+     * found and the config omits WILL be missing from the APK, while a namespace the
+     * config names and the scan missed may simply be reached in a way no static read
+     * can see (`planGiSelection` carries the full argument).
+     *
+     * Android is the one target where this is not advice. A `.deb` that under-declares
+     * its typelibs can still be fixed by installing a package; an APK carries its
+     * whole GI stack or does without it.
+     */
+    assertNativescriptGiSelected(result, outfile, outdir) {
+        const label = outfile ?? outdir ?? 'the nativescript bundle';
+        const scanned = new Set();
+        for (const item of result.output ?? []) {
+            if (item.type !== 'chunk')
+                continue;
+            const code = item.code;
+            if (typeof code !== 'string' || code.length === 0)
+                continue;
+            for (const namespace of scanGiNamespaces(code))
+                scanned.add(namespace);
+        }
+        let selection;
+        try {
+            selection = planGiSelection({
+                declared: this.configData.nativescript?.giNamespaces ?? [],
+                scanned: [...scanned],
+            });
+        }
+        catch (error) {
+            // Re-thrown with the artifact in it: `planGiSelection` is pure and knows
+            // the namespaces but not which file they were read from.
+            throw new Error(`gjsify build: ${label}: ${error.message}`);
+        }
+        for (const namespace of selection.unscanned) {
+            console.warn(`[gjsify] --app nativescript: nativescript.giNamespaces declares ${namespace}, which ` +
+                `${label} does not appear to import. The APK carries it anyway — drop it if nothing ` +
+                'needs it, since every selected namespace costs APK size.');
+        }
+    }
     /**
      * Post-bundle step for a `--app browser` HTML entry: write the processed
      * `index.html` beside the JS bundle, with the entry `<script>`'s `src`
@@ -849,6 +896,13 @@ export class BuildAction {
         if (app === 'node' && autoMode && !pluginOpts.nodeGiGlobalsInject) {
             this.assertNodeOutputGlobals(writeResult, outfile, outdir);
         }
+        // Refuse to hand back a `--app nativescript` bundle that imports a GI namespace
+        // the APK will not carry. The payload is selected from a pinned sysroot at
+        // package-build time (ADR 0117), so there is no host to fall back on: the
+        // alternative to this gate is an APK that installs and throws at the import.
+        if (app === 'nativescript') {
+            this.assertNativescriptGiSelected(writeResult, outfile, outdir);
+        }
         // Browser HTML entry: emit the processed `index.html` beside the bundle
         // (engine-portable post-step — the native rolldown engine has no
         // `emitFile`, so this can't live in a plugin). `outfile` is guaranteed

package/lib/config.js

@@ -317,6 +317,25 @@ export class Config {
                 'introspection to answer `gi://` with. `--app gjs` resolves it natively and `--app node` ' +
                 'through @gjsify/node-gi, so neither needs a widget renderer standing in for it.');
         }
+        // And the same rule once more for the namespace selection, which only an
+        // Android payload can act on: on every other target `gi://` is answered by a
+        // system typelib or by `requireGi`, so a list here would be read, validated
+        // and then change nothing about the artifact.
+        if (configData.nativescript?.giNamespaces !== undefined && configData.app !== 'nativescript') {
+            throw new Error(`gjsify build: nativescript.giNamespaces has no effect on --app ${configData.app}. ` +
+                'It selects what an Android APK carries (ADR 0117); every other target resolves ' +
+                '`gi://` against a GI stack the host already has.');
+        }
+        for (const entry of configData.nativescript?.giNamespaces ?? []) {
+            // `Ns` or `Ns-Version`, because that is what the AAR builder resolves
+            // against the typelib names in the sysroot. A free-form string here
+            // surfaces as "the prefix has no typelib for …" hours later, naming the
+            // typo rather than the shape.
+            if (!/^[A-Za-z][A-Za-z\d_]*(-\d+(\.\d+)*)?$/.test(entry)) {
+                throw new Error(`gjsify build: nativescript.giNamespaces entry "${entry}" is not a GI namespace. ` +
+                    'Write it as `Gtk` or `Gtk-4.0`.');
+            }
+        }
         if (cliArgs.globals !== undefined)
             configData.globals = cliArgs.globals;
         // Fallback applied post-merge (not as a yargs `default:`) so a

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

@@ -213,6 +213,37 @@ export interface ConfigData {
     format?: ConfigDataFormat;
     /** Config for `gjsify test`. `--entry`, `--outdir`, `--runtime` override these. */
     test?: ConfigDataTest;
+    /** Config for the `nativescript` target — what the APK carries (ADR 0117). */
+    nativescript?: ConfigDataNativescript;
+}
+/**
+ * What a NativeScript build decides that no other target has to.
+ *
+ * Its own namespace rather than top-level keys, for the reason `flatpak` and `ship`
+ * have one: these settings mean nothing on `gjs`, `node` or `browser`, and a
+ * top-level `giNamespaces` would read like a bundler option on every target.
+ */
+export interface ConfigDataNativescript {
+    /**
+     * The GI namespaces this APK carries, as `Ns` or `Ns-Version` (ADR 0117 § 2).
+     *
+     * ANDROID HAS NO SYSTEM GI STACK, so unlike a `.deb` there is no `Depends:` that
+     * a host can satisfy: every typelib and every backing `.so` is in the APK or is
+     * not reachable at all. The payload is cross-compiled against a sha256-pinned
+     * sysroot long before an app build, so this list cannot conjure a namespace the
+     * sysroot lacks — it SELECTS from what the sysroot has.
+     *
+     * Declared rather than inferred, and the asymmetry is the point: the scan of the
+     * emitted bundle is a LOWER BOUND (a namespace reached through a computed
+     * specifier is invisible to it), so an imported namespace missing from this list
+     * fails the build by name, while a listed one the scan did not see is only a
+     * warning about a larger-than-necessary APK.
+     *
+     * Unset is not the same as `[]` in intent but is in effect: both mean the
+     * measured core set (GLib, GObject, Gio and friends), which backs the runtime
+     * itself and ships whether or not anything declares it.
+     */
+    giNamespaces?: string[];
 }
 /** Optional pointer to a non-default oxc config file. */
 export interface ConfigDataFormat {
@@ -323,10 +354,14 @@ export interface AppMetadata {
     /**
      * App-store screenshots. `url` must be an absolute HTTPS URL to a PNG;
      * `environment` lets Flathub group by desktop; the first entry defaults to
-     * `type="default"`.
+     * `type="default"`. `localizedUrls` maps a language code (`de`, `pt_BR`)
+     * to a screenshot of the app in that language; each becomes an extra
+     * `<image xml:lang="…">`, so software centres show the user's language
+     * and fall back to `url`.
      */
     screenshots?: Array<{
         url: string;
+        localizedUrls?: Record<string, string>;
         caption?: string;
         captionTranslatorHint?: string;
         environment?: 'plasma' | 'gnome' | 'cli';

package/lib/utils/app-metadata.js

@@ -176,6 +176,9 @@ function renderMetainfo(inputs, kind) {
             const envAttr = s.environment ? ` environment="${escapeXml(s.environment)}"` : '';
             lines.push(`    <screenshot${typeAttr}${envAttr}>`);
             lines.push(`      <image>${escapeXml(s.url)}</image>`);
+            for (const [lang, url] of Object.entries(s.localizedUrls ?? {})) {
+                lines.push(`      <image xml:lang="${escapeXml(lang)}">${escapeXml(url)}</image>`);
+            }
             if (s.caption) {
                 pushTranslatorHint(lines, s.captionTranslatorHint, '      ');
                 lines.push(`      <caption>${escapeXml(s.caption)}</caption>`);

package/lib/utils/metainfo-quality.js

@@ -306,9 +306,12 @@ export async function lintMetainfo(xml, options = {}) {
         add('screenshot-missing', 'warning', 'at-least-one-screenshot', 'screenshots', 'at least one screenshot is expected');
     }
     else {
+        // A screenshot with an untagged image plus `<image xml:lang="de">` twins is English: the
+        // twins are alternatives, and the untagged one is what a non-German user sees.
+        const englishTag = (t) => t === '' || langBase(t) === 'en';
         const isEnglish = (s) => {
-            const tags = [lang(s), ...kids(s, 'image').map(lang)];
-            return tags.every((t) => t === '' || langBase(t) === 'en');
+            const images = kids(s, 'image').map(lang);
+            return englishTag(lang(s)) && (images.length === 0 || images.some(englishTag));
         };
         if (!shots.some(isEnglish)) {
             add('screenshot-no-english', 'warning', 'at-least-one-screenshot', 'screenshots', 'no screenshot without xml:lang (or in English)');

package/lib/utils/ship/gi-selection.d.ts

@@ -0,0 +1,18 @@
+/** What {@link planGiSelection} decided, and what it wants the build to say out loud. */
+export interface GiSelection {
+    /** The namespaces to hand the AAR builder, as the config spells them, deduped and sorted. */
+    selected: string[];
+    /** Declared but not found in the bundle — worth a warning, never a refusal. */
+    unscanned: string[];
+}
+/**
+ * Reconcile the configured namespace set with the one the emitted bundle imports.
+ *
+ * @param spec.declared `nativescript.giNamespaces`, as `Ns` or `Ns-Version`
+ * @param spec.scanned what {@link scanGiNamespaces} read off the emitted bundle
+ * @throws when the bundle imports a namespace the config does not cover
+ */
+export declare function planGiSelection({ declared, scanned }: {
+    declared: string[];
+    scanned: string[];
+}): GiSelection;

package/lib/utils/ship/gi-selection.js

@@ -0,0 +1,73 @@
+// Which GI namespaces does this Android APK carry? — ADR 0117 § 2, the CLI half.
+//
+// THE CONFIG DECIDES AND THE BUNDLE IS CHECKED AGAINST IT, which is the asymmetry
+// the ADR turns on. The payload is cross-compiled hours earlier by
+// `build-gi-runtime-android.mjs` against a sha256-pinned sysroot; nothing at app-build
+// time can conjure a typelib that is not in it. So the config is the input, and the
+// scan of the emitted bundle is the EVIDENCE that the input is complete.
+//
+// The scan is a LOWER BOUND, and the two directions of disagreement are therefore not
+// symmetric:
+//
+//   * IMPORTED, NOT CONFIGURED → build error naming the namespace. The scanner found a
+//     real import; the APK will not have the typelib; the device throws at that import,
+//     after the download, reading like an application bug. This is the same failure
+//     `deriveDepends` refuses for distro packages (ADR 0024 § 6), reached from Android.
+//   * CONFIGURED, NOT IMPORTED → warning. `scanGiNamespaces` reads the emitted file and
+//     cannot see a namespace reached through a computed specifier, nor one loaded by a
+//     native dependency. Refusing here would make a correct project unbuildable on the
+//     scanner's blind spot — so it reports a probably-larger-than-necessary APK and
+//     builds it.
+//
+// COMPARED BY NAMESPACE, NOT BY STRING. A config may pin an ABI (`Gtk-4.0`) where the
+// bundle's specifier carries no version (`import 'gi://Gtk'`), and vice versa. Both
+// sides mean the same namespace, and string equality would fail a correct project on
+// the spelling.
+/** `Gtk-4.0` → `Gtk`; `Gtk` → `Gtk`. */
+function namespaceOf(entry) {
+    const dash = entry.indexOf('-');
+    return dash === -1 ? entry : entry.slice(0, dash);
+}
+/**
+ * The namespaces every AAR carries whether or not anything declares them.
+ *
+ * These back `libnode_gi.so` itself, so they are in the payload's DT_NEEDED closure
+ * before any selection happens (ADR 0110's measured core set). Demanding them in the
+ * config would make the key boilerplate and fail every project that exists today, for
+ * a selection that cannot change the bytes.
+ */
+const ALWAYS_PRESENT = new Set(['GLib', 'GObject', 'Gio', 'GioUnix', 'GLibUnix', 'GModule', 'GIRepository']);
+/**
+ * Reconcile the configured namespace set with the one the emitted bundle imports.
+ *
+ * @param spec.declared `nativescript.giNamespaces`, as `Ns` or `Ns-Version`
+ * @param spec.scanned what {@link scanGiNamespaces} read off the emitted bundle
+ * @throws when the bundle imports a namespace the config does not cover
+ */
+export function planGiSelection({ declared, scanned }) {
+    // A bare and a pinned declaration of one namespace are one selection, and the
+    // pinned spelling wins: it says something the bare one does not.
+    const byNamespace = new Map();
+    for (const entry of declared) {
+        const ns = namespaceOf(entry);
+        const held = byNamespace.get(ns);
+        if (held === undefined || (held === ns && entry !== ns))
+            byNamespace.set(ns, entry);
+    }
+    const missing = [
+        ...new Set(scanned.map(namespaceOf).filter((ns) => !byNamespace.has(ns) && !ALWAYS_PRESENT.has(ns))),
+    ].sort();
+    if (missing.length > 0) {
+        throw new Error(`The bundle imports ${missing.join(', ')}, which nativescript.giNamespaces does not declare. ` +
+            'An Android APK carries only the typelibs the config selects (ADR 0117), so this would ' +
+            `install and then throw at the import. Add ${missing.length === 1 ? 'it' : 'them'} to ` +
+            'nativescript.giNamespaces, or stop importing ' +
+            `${missing.length === 1 ? 'it' : 'them'}.`);
+    }
+    const seen = new Set(scanned.map(namespaceOf));
+    const unscanned = [...byNamespace.entries()]
+        .filter(([ns]) => !seen.has(ns))
+        .map(([, entry]) => entry)
+        .sort();
+    return { selected: [...byNamespace.values()].sort(), unscanned };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.64.1",
+    "version": "0.64.2-next.255",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,22 +142,22 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/blueprint": "^0.64.1",
-        "@gjsify/buffer": "^0.64.1",
-        "@gjsify/create-app": "^0.64.1",
-        "@gjsify/node-globals": "^0.64.1",
-        "@gjsify/node-polyfills": "^0.64.1",
-        "@gjsify/npm-registry": "^0.64.1",
-        "@gjsify/resolve-npm": "^0.64.1",
-        "@gjsify/rolldown-plugin-gjsify": "^0.64.1",
-        "@gjsify/vite-plugin-blueprint": "^0.64.1",
-        "@gjsify/rolldown-plugin-pnp": "^0.64.1",
-        "@gjsify/semver": "^0.64.1",
-        "@gjsify/tar": "^0.64.1",
-        "@gjsify/tsc": "^0.64.1",
-        "@gjsify/utils": "^0.64.1",
-        "@gjsify/web-polyfills": "^0.64.1",
-        "@gjsify/workspace": "^0.64.1",
+        "@gjsify/blueprint": "0.64.2-next.255",
+        "@gjsify/buffer": "0.64.2-next.255",
+        "@gjsify/create-app": "0.64.2-next.255",
+        "@gjsify/node-globals": "0.64.2-next.255",
+        "@gjsify/node-polyfills": "0.64.2-next.255",
+        "@gjsify/npm-registry": "0.64.2-next.255",
+        "@gjsify/resolve-npm": "0.64.2-next.255",
+        "@gjsify/rolldown-plugin-gjsify": "0.64.2-next.255",
+        "@gjsify/vite-plugin-blueprint": "0.64.2-next.255",
+        "@gjsify/rolldown-plugin-pnp": "0.64.2-next.255",
+        "@gjsify/semver": "0.64.2-next.255",
+        "@gjsify/tar": "0.64.2-next.255",
+        "@gjsify/tsc": "0.64.2-next.255",
+        "@gjsify/utils": "0.64.2-next.255",
+        "@gjsify/web-polyfills": "0.64.2-next.255",
+        "@gjsify/workspace": "0.64.2-next.255",
         "acorn": "^8.17.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
@@ -166,13 +166,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.64.1",
+        "@gjsify/unit": "0.64.2-next.255",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.64.1",
-        "@gjsify/rolldown-native": "^0.64.1"
+        "@gjsify/oxfmt-native": "0.64.2-next.255",
+        "@gjsify/rolldown-native": "0.64.2-next.255"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {
@@ -191,5 +191,6 @@
     "bugs": {
         "url": "https://github.com/gjsify/gjsify/issues"
     },
-    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/infra/cli#readme"
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/infra/cli#readme",
+    "gitHead": "6c88ac780b9742fce781e9b35aa2f45c125d8064"
 }