@gjsify/cli 0.47.0 → 0.49.0

package/lib/actions/build.js

@@ -630,7 +630,7 @@ export class BuildAction {
             throw new Error('gjsify build: an .html entry needs an explicit --outfile ' +
                 '(e.g. --outfile dist-app/app.js); the emitted index.html is written beside it.');
         }
-        const { consoleShim, globals, dialect } = this.configData;
+        const { consoleShim, globals, dialect, giRenderer } = this.configData;
         const userExternal = Array.isArray(userBundler.external) ? userBundler.external : undefined;
         const userBanner = typeof userBundler.output?.banner === 'string' ? userBundler.output.banner : undefined;
         const pluginOpts = {
@@ -641,6 +641,7 @@ export class BuildAction {
             reflection: typescript?.reflection,
             consoleShim,
             ...(dialect !== undefined ? { dialect } : {}),
+            ...(giRenderer === true ? { giRenderer: true } : {}),
             ...(aliases ? { aliases } : {}),
             ...(opts.preserveDefaultExport ? { preserveDefaultExport: true } : {}),
             ...(opts.toolchainAnchor !== undefined ? { toolchainAnchor: opts.toolchainAnchor } : {}),

package/lib/commands/affected-classify.js

@@ -146,6 +146,27 @@ const SCRIPT_COUPLINGS = [
         runE2E: true,
         why: '@gjsify/create-app build → node scripts/process-template.mjs reads templates/',
     },
+    {
+        // THE SAME SHAPE AS `.githooks/` ABOVE, one layer up: the guard's trigger names
+        // the TEST's path instead of the thing under test. `AppRegistry.runApplication`
+        // holds three lines observable only by RUNNING the loop —
+        // `registerBuiltinWidgets()`, the `toShellOptions` passthrough and
+        // `provideWindowChrome()` — and their one external observer is
+        // `tests/e2e/react-native-devtools`, which main.yml's `e2e` job now runs under
+        // xvfb + a session bus (#1550). Without this entry a change confined to
+        // `packages/framework/react-native/**` seeds its own workspace, the e2e tier
+        // stays OFF (it turns on for a `tests/e2e/**` touch), and the suite is silent
+        // for exactly the PRs it exists to catch. Measured on #1540: deleting
+        // `provideWindowChrome()` left format, lint, tsc and all in-process assertions
+        // green while the application drew two header bars.
+        //
+        // No extra seeds — the package is a workspace and already seeds itself. The
+        // TIER is the point, as for `.githooks/`.
+        match: /^packages\/framework\/react-native\//,
+        seeds: [],
+        runE2E: true,
+        why: 'tests/e2e/react-native-devtools is the only external observer of AppRegistry.runApplication',
+    },
 ];
 export function classifyAndExpand(workspaces, changedFiles) {
     const files = changedFiles.map((f) => f.replace(/\\/g, '/')).filter((f) => f.length > 0);
@@ -255,7 +276,15 @@ export function classifyAndExpand(workspaces, changedFiles) {
             global: false,
             reason: `test-only (${remaining.length} file(s) in ${only})`,
             workspaces: [only],
-            runE2E: touchedE2E,
+            // `|| couplingRunE2E`: this shortcut skips CLOSURE EXPANSION, and a
+            // declared tier is not part of the closure. Dropping it here made a
+            // coupling's reach depend on the SHAPE of the changed path — the
+            // `.githooks/` entry survived only because a hook is not a spec file,
+            // while `packages/framework/react-native/src/widgets.spec.ts` fell
+            // through and turned the e2e tier back off. Measured by the vector
+            // "a react-native spec file ALSO turns the e2e tier on", which was RED
+            // when it was written (#1550).
+            runE2E: touchedE2E || couplingRunE2E,
             runIntegration: touchedIntegration || isIntegrationWorkspace(only),
             skipAll: false,
         };

package/lib/commands/build.js

@@ -112,6 +112,10 @@ export const buildCommand = {
             description: "The dialect the SOURCE is written in. 'react-native' aliases 'react-native' onto '@gjsify/react-native' and fails the build on an import whose ADR 0032 support-table status is not supported/partial. GJS and Node app builds. This is NOT gjsify.runtimes['react-native'], which declares the runtime a package RUNS on — the two answer opposite questions.",
             type: 'string',
             choices: [...SOURCE_DIALECTS],
+        })
+            .option('gi-renderer', {
+            description: "Resolve `gi://Ns?version=X` to the target's widget renderer instead of an empty module (ADR 0034 stage 9): --app browser answers gi://Adw and gi://Gtk out of @gjsify/adwaita-web, --app nativescript out of @gjsify/adwaita-nativescript. A namespace with no renderer, and a ?version= the renderer's vocabulary was not generated against, both FAIL the build by name. Off by default — a gi:// import on those targets is usually a GJS-only code path pulled in transitively.",
+            type: 'boolean',
         })
             .option('console-shim', {
             description: 'Inject a console shim into GJS builds for clean output without the GLib prefix and with working ANSI colors. Use --no-console-shim to disable. Only applies to GJS app builds.',

package/lib/commands/dlx.js

@@ -13,6 +13,7 @@
 import { runGjsBundle } from '../utils/run-gjs.js';
 import { parseSpec } from '../utils/parse-spec.js';
 import { resolveGjsEntry } from '../utils/resolve-gjs-entry.js';
+import { doubleDashArgs } from '../utils/double-dash-args.js';
 import { cacheDirFor, createCacheKey, getValidCachedPkg, makePrepareDir, resolveInstalledPkgDir, symlinkSwap, } from '../utils/dlx-cache.js';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
 export const dlxCommand = {
@@ -25,7 +26,11 @@ export const dlxCommand = {
         // --help` shows ts-for-gir's --help instead of gjsify dlx's.
         // Without `populate--`, the trailing `--help` is consumed at
         // the gjsify level and the bundle never sees it.
-        .parserConfiguration({ 'populate--': true })
+        // `parse-positional-numbers: false` alongside it: the `--` tail and the
+        // `[extraArgs..]` positional are the caller's argv, not numbers, and yargs
+        // otherwise retypes a bare `5` (#1531). `--cache-max-age` declares
+        // `type: 'number'` and is unaffected.
+        .parserConfiguration({ 'populate--': true, 'parse-positional-numbers': false })
         .positional('spec', {
         description: 'Package spec (`name`, `name@version`, `@scope/name@spec`, or local path).',
         type: 'string',
@@ -84,8 +89,7 @@ export const dlxCommand = {
         // number)[]`), so flags like `--help` reach the bundle untouched.
         // Merge those into the positional extraArgs the splitter sees so
         // both call shapes share one downstream path.
-        const passthroughDoubleDash = (args['--'] ?? []).map((v) => String(v));
-        const extraArgsCombined = [...(args.extraArgs ?? []), ...passthroughDoubleDash];
+        const extraArgsCombined = [...(args.extraArgs ?? []), ...doubleDashArgs(args)];
         const { binName, extraArgs } = splitBinAndArgs(pkgDir, args.binOrArg, extraArgsCombined);
         const entry = resolveGjsEntry(pkgDir, binName);
         if (entry.fromFallback) {

package/lib/commands/foreach.js

@@ -15,6 +15,7 @@ import { affectedClosure, buildDependencyGraph, discoverWorkspaces, filterWorksp
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { cliRuntimeClosure } from '../utils/cli-runtime-closure.js';
 import { prefixLines } from '../utils/prefixed-output.js';
+import { doubleDashArgs } from '../utils/double-dash-args.js';
 import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
 // The ONE runner-selection rule, shared rather than re-derived. This file used to
 // carry its own copy; `workspace.ts` grew the bootstrap-CLI branch and the copy
@@ -267,6 +268,12 @@ export const foreachCommand = {
         //   gjsify foreach --exec -- npm publish --tag latest
         // without yargs grabbing --tag/--access/etc.
         'populate--': true,
+        // …and keep that tail as the TEXT the caller typed. Without
+        // this yargs types a bare number in the array as a `number`,
+        // which is how `--verify-timeout 5 --tag latest` reached 209
+        // npm publishes as `--verify-timeout --tag latest` (#1531).
+        // Declared `type: 'number'` options (`--jobs`) are unaffected.
+        'parse-positional-numbers': false,
     }),
     handler: async (args) => {
         // Walk up to the monorepo root — foreach is sometimes invoked
@@ -286,7 +293,7 @@ export const foreachCommand = {
             // Script mode silently DROPPED everything after `--` (only --exec
             // consumed args['--']). Forward them to each child invocation,
             // matching `yarn workspaces foreach run <script> -- <flags>`.
-            const fromDoubleDash = (args['--'] ?? []).filter((v) => typeof v === 'string');
+            const fromDoubleDash = doubleDashArgs(args);
             if (fromDoubleDash.length > 0)
                 cmdArgs = [...cmdArgs, ...fromDoubleDash];
         }
@@ -294,7 +301,7 @@ export const foreachCommand = {
             // With populate--:true, anything after the literal `--`
             // separator lands in top-level args['--']. yargs DOES NOT
             // attach it to args._ — it's a sibling array.
-            const fromDoubleDash = (args['--'] ?? []).filter((v) => typeof v === 'string');
+            const fromDoubleDash = doubleDashArgs(args);
             if (fromDoubleDash.length > 0) {
                 if (!cmd) {
                     cmd = fromDoubleDash[0];

package/lib/commands/install.js

@@ -23,7 +23,7 @@ import { spawnSync } from 'node:child_process';
 import { forceExit } from '../utils/force-exit.js';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks } from '../utils/check-system-deps.js';
-import { detectNativePackages } from '../utils/detect-native-packages.js';
+import { detectHostLibc, detectNativePackages, muslPrebuildFallbacks } from '../utils/detect-native-packages.js';
 import { buildLauncherShims, buildNativeEnvPreamble } from '../utils/bin-shim.js';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
 import { atomicWriteStrict } from '../utils/install-cache-fs.js';
@@ -1339,6 +1339,26 @@ async function runPostInstallChecks(args) {
             console.log(`  • ${pkg.name}`);
         }
         console.log('\nUse `gjsify run <bundle>` to launch with LD_LIBRARY_PATH/GI_TYPELIB_PATH set.');
+        // The install is the ONLY moment this is knowable: the libc axis is decided
+        // here, the failure it predicts happens in another process, days later, and
+        // names something else entirely (see `muslPrebuildFallbacks`). The list is
+        // the point — it is what lets a later `Error relocating` line be matched to
+        // a package.
+        const fellBack = muslPrebuildFallbacks(detectHostLibc(process.platform), native);
+        if (fellBack.length > 0) {
+            console.warn(`\nWarning: musl host — ${fellBack.length} of ${native.length} package(s) ship no \`-musl\`` +
+                ' prebuild, so the\n  default (glibc) build was used:');
+            for (const name of fellBack)
+                console.warn(`    ${name}`);
+            console.warn('  Most of these run anyway: a bridge that links only GLib records no libc at all.\n' +
+                '  One that links glibc loads too — musl aliases `libc.so.6` to itself — and then\n' +
+                '  fails at dlopen on its first glibc-only symbol:\n' +
+                '    Error relocating <prebuild>.so: <symbol>: symbol not found\n' +
+                '  A bridge lost that way is silently absent from the next build rather than\n' +
+                '  reported, so the first symptom can be an unrelated-looking bundler error\n' +
+                '  (`Could not load <file>` from rolldown, for the CSS bridge). Nothing to\n' +
+                '  install: no `-musl` package is published for any target yet.');
+        }
     }
     maybeInstallGitHooks();
 }

package/lib/commands/publish.js

@@ -42,6 +42,7 @@
 import { readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
+import { base64Encode } from '../utils/base64.js';
 import { DEFAULT_REGISTRY, registryFor } from '@gjsify/npm-registry';
 import { buildPublishHeaders, escapePackageName } from '../utils/publish-headers.js';
 import { packWorkspace } from './pack.js';
@@ -789,14 +790,6 @@ function buildPublishPayload(opts) {
         payload.access = access;
     return payload;
 }
-function base64Encode(bytes) {
-    let str = '';
-    const chunk = 0x8000;
-    for (let i = 0; i < bytes.length; i += chunk) {
-        str += String.fromCharCode(...bytes.subarray(i, i + chunk));
-    }
-    return btoa(str);
-}
 function handleOidcFailure(err, packageName, asJson) {
     if (err instanceof OidcUnavailableError) {
         const msg = `gjsify publish: OIDC not available — ${err.message}`;

package/lib/commands/run.js

@@ -15,6 +15,7 @@
 // to disambiguate can pass `./<file>` explicitly.
 import { readFileSync, statSync } from 'node:fs';
 import { basename, delimiter, join, resolve } from 'node:path';
+import { doubleDashArgs } from '../utils/double-dash-args.js';
 import { describeExit, spawnToCompletion } from '../utils/spawn.js';
 import { runGjsBundle } from '../utils/run-gjs.js';
 import { runRuntimeBundle } from '../utils/run-node.js';
@@ -93,6 +94,11 @@ export const runCommand = {
         // Without this, anything after `--` lands in args._ and is
         // silently dropped by the handler.
         'populate--': true,
+        // …and hand that tail on as the TEXT the caller typed. Without
+        // this yargs types a bare number in the array — and in the
+        // `[args..]` positional — as a `number`, which the reader below
+        // used to drop outright (#1531).
+        'parse-positional-numbers': false,
         // Forward UNKNOWN flags to the target without requiring `--`:
         //   gjsify run dist/app.gjs.mjs serve --port 8080 --year 2025
         // Without this, the top-level `.strict()` (cli-app.ts) rejects
@@ -111,8 +117,7 @@ export const runCommand = {
         // than silently discarding them (without it they land in args._ and
         // are never forwarded to the child).
         const positionalArgs = args.args ?? [];
-        const doubleDashArgs = (args['--'] ?? []).filter((v) => typeof v === 'string');
-        const extraArgs = [...positionalArgs, ...doubleDashArgs];
+        const extraArgs = [...positionalArgs, ...doubleDashArgs(args)];
         // `--node-script` (explicit) → run an UNBUNDLED Node-style script on the
         // host runtime; under GJS it is bundled `--app gjs` on the fly first.
         // Checked before `--runtime` and `--workspace`: it is a file mode, and

package/lib/commands/ship.js

@@ -42,13 +42,14 @@ import { isUnder, SHARE } from '../utils/ship/share-dirs.js';
 import { compileSchemasForStage } from '../utils/ship/schemas.js';
 import { buildMsi, MSI_PAYLOAD_DIR } from '../utils/ship/msi.js';
 import { buildZip, zipEntriesFromPayload } from '../utils/ship/zip.js';
+import { assertEntryRunsUnder } from '../utils/ship/entry-interpreter.js';
 import { scanGiNamespaces } from '../utils/ship/gi-namespaces.js';
 import { assertLauncherMatchesInterpreter, assertPayloadMatchesArch, buildTimestamp, isArchIndependent, linuxInstallDependent, readPayloadFacts, } from '../utils/ship/payload.js';
 import { assertOverlayIsLicensed, planOverlay, planStage } from '../utils/ship/plan.js';
 import { assertHostCanSign, notarizeArtifact, stapleArtifact, resolveNotaryPlan, resolveSignPlan, signPayload, } from '../utils/ship/signing.js';
 import { renderLauncher } from '../utils/ship/launcher.js';
 import { buildRpm } from '../utils/ship/rpm.js';
-import { declaredBundlePath, resolveShipApp, resolveShipSettings, } from '../utils/ship/settings.js';
+import { resolveShipApp, resolveShipBundle, resolveShipSettings, } from '../utils/ship/settings.js';
 import { assertExpectedTarget, assertFormatsStaged, formatTarget, overlayFiles, readStageManifest, resolveStageMtime, warnOnToolSkew, writeStageManifest, STAGE_MANIFEST_FILE, } from '../utils/ship/stage-manifest.js';
 import { directorySize, readStage, writePayload, writeStage } from '../utils/ship/stage-writer.js';
 const LOG = '[gjsify ship]';
@@ -280,12 +281,22 @@ async function assemble(args) {
             assertCanPack(format);
     if (!args['skip-build'])
         await runProjectBuild(projectDir);
+    // THE OTHER HALF of the resolution above, and they are one decision: the
+    // runtime a target execs and the entry it hands that runtime (#1545). Two
+    // keys, resolved by two twin functions, compared by `assertEntryRunsUnder`
+    // as soon as both answers and the file exist.
+    const resolvedBundle = resolveShipBundle({ pkg, ship, layoutOs: layout.os });
+    if (resolvedBundle.overridden) {
+        console.log(`${LOG} entry for ${layout.name}: ${resolvedBundle.declared} — \`${resolvedBundle.key}\` ` +
+            'overrides `gjsify.main`.');
+    }
     const discovered = discoverPayload({
         projectDir,
         pkg,
         ship,
         flatpakIcon: flatpak.icon,
-        declaredBundle: declaredBundlePath(pkg, ship),
+        declaredBundle: resolvedBundle.declared,
+        foreignBundles: resolvedBundle.foreign,
     });
     const { settings, metadata, warnings } = resolveShipSettings({
         projectDir,
@@ -308,6 +319,21 @@ async function assemble(args) {
     // the packing host.
     for (const format of formats)
         assertFormatCanRunInterpreter(format, settings.app);
+    // The entry, read ONCE: the pair check below and the namespace scan further
+    // down both ask what this file imports, and a bundle is the biggest file in
+    // the project.
+    const bundleSource = readFileSync(settings.bundlePath, 'utf-8');
+    // BEFORE anything is staged, for the reason above and one more: this is the
+    // refusal that says the artifact could never have started, and the run that
+    // reports it must not also print a stage path.
+    assertEntryRunsUnder({
+        interpreter: settings.app,
+        source: bundleSource,
+        entry: relative(projectDir, settings.bundlePath) || settings.bundlePath,
+        appKey: resolvedApp.key,
+        bundleKey: resolvedBundle.key,
+        layoutOs: layout.os,
+    });
     const mtime = buildTimestamp(settings.bundlePath);
     const metadataInputs = {
         appId: settings.appId,
@@ -354,6 +380,8 @@ async function assemble(args) {
         metainfo: translated.metainfo,
         desktopEntry: translated.desktopEntry,
         licenseText: settings.licenseFile === undefined ? undefined : readFileSync(settings.licenseFile, 'utf-8'),
+        changelogText: settings.changelogFile === undefined ? undefined : readFileSync(settings.changelogFile, 'utf-8'),
+        mtime,
     };
     const outRoot = resolve(projectDir, settings.outDir);
     const stageDir = join(outRoot, 'stage');
@@ -466,7 +494,7 @@ async function assemble(args) {
     // `gi://` specifiers are what the emitted `Depends:` is derived from
     // (ADR 0024 § 6), and the packing host has the staged copy but no way to
     // tell which staged file is the entry.
-    const namespaces = scanGiNamespaces(readFileSync(settings.bundlePath, 'utf-8'));
+    const namespaces = scanGiNamespaces(bundleSource);
     if (args.verbose)
         console.log(`${LOG} gi namespaces: ${namespaces.join(', ') || '(none)'}`);
     // PLACED, like the payload, and through the same map. `planOverlay` answers a
@@ -481,7 +509,7 @@ async function assemble(args) {
     // overlay reaches it by the same route.
     const overlay = new Map();
     for (const format of formats) {
-        overlay.set(format.id, planOverlay(settings, format, stageInputs).map((file) => ({
+        overlay.set(format.id, (await planOverlay(settings, format, stageInputs)).map((file) => ({
             ...file,
             path: place(layout, settings, file.path),
         })));

package/lib/commands/upgrade.js

@@ -12,11 +12,15 @@
 //      matching packages automatically without prompting; same selection
 //      logic as above but no UI loop.
 //
-//   3. `--align`: offline consistency-only mode. Finds deps declared at
-//      multiple ranges across the workspace and proposes a single range
-//      (the highest declared) — no registry calls.
+//   3. `--align`: offline repair mode. Finds deps declared at multiple ranges
+//      across the workspace and proposes a single range (the highest declared)
+//      — no registry calls. With `--exact` it repairs the second question too:
+//      a dep every manifest declares identically as `^4.1.0` is consistent and
+//      still carries an operator, so the operator goes as well.
 //
-//   4. `--check`: CI gate. Exits non-zero when any inconsistency exists.
+//   4. `--check`: CI gate. Exits non-zero when any inconsistency exists; with
+//      `--exact`, also when any matched declaration carries a range operator.
+//      Whatever `--check` rejects, `--align` with the same flags repairs.
 //
 // Filters:
 //
@@ -36,7 +40,7 @@ import { parse } from '@gjsify/semver';
 import { DEFAULT_REGISTRY, fetchPackument, parseNpmrc } from '@gjsify/npm-registry';
 import { discoverWorkspaces, filterWorkspaces } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
-import { groupByDependency, findInconsistencies, } from '../utils/dep-aggregation.js';
+import { groupByDependency, findInconsistencies, isInconsistent, } from '../utils/dep-aggregation.js';
 export const upgradeCommand = {
     command: 'upgrade',
     description: 'Workspace-aware dependency upgrades. Walks every package.json in the monorepo, groups by dep, flags inconsistencies. `--latest` / `--minor` / `--patch` for bulk-mode, `--align` for offline consistency-only mode, `--check` for CI drift detection.',
@@ -71,7 +75,7 @@ export const upgradeCommand = {
             type: 'string',
         })
             .option('align', {
-            description: 'Offline consistency mode: find deps declared at multiple ranges across the workspace and align them to the highest. No registry calls.',
+            description: 'Offline repair mode: find deps declared at multiple ranges across the workspace and align them to the highest. With `--exact`, also drop the range operator from declarations that already agree. No registry calls.',
             type: 'boolean',
             default: false,
         })
@@ -81,7 +85,7 @@ export const upgradeCommand = {
             default: false,
         })
             .option('exact', {
-            description: 'Pin without a range operator. When writing, emits `1.2.3` instead of `^1.2.3`; with `--check`, fails on any matched dep that carries one. Pair with `--filter` — a repository-wide exactness check fails on every ordinary caret dep by design.',
+            description: 'Pin without a range operator. When writing, emits `1.2.3` instead of `^1.2.3`; with `--check`, fails on any matched dep that carries one; with `--align`, repairs exactly that. Pair with `--filter` — a repository-wide exactness run touches every ordinary caret dep by design.',
             type: 'boolean',
             default: false,
         })
@@ -348,22 +352,63 @@ function runCheckMode(groups, exact = false) {
             console.error(`    ${range.padEnd(16)} — ${holders.join(', ')}`);
         }
     }
-    console.error(`\nFix: run \`gjsify upgrade --align\` (offline; aligns each dep to its highest declared range).`);
+    console.error(exact
+        ? `\nFix: run \`gjsify upgrade --align --exact\` (offline; aligns each dep to its highest declared version and drops the operator).`
+        : `\nFix: run \`gjsify upgrade --align\` (offline; aligns each dep to its highest declared range).`);
     process.exit(1);
 }
+/**
+ * The groups `--align` has work on.
+ *
+ * Inconsistency is the whole question for a bare `--align`: a dep every manifest declares
+ * identically is done. `--exact` asks a second one, and the two do not overlap — a tree
+ * where every manifest says `^4.1.0` is perfectly consistent and carries an operator on
+ * every one of those declarations, which is precisely what `--check --exact` rejects.
+ *
+ * Selecting on inconsistency alone therefore made the repair that `--check --exact`'s own
+ * failure message names answer `nothing to do` to the tree it was pointed at: the gate
+ * demanded a property the fix could not deliver, cheerfully. Measured on bauplaner's five
+ * `@girs/*` declarations, all five `^4.1.0` and all five consistent.
+ */
+function alignTargets(groups, exact) {
+    if (!exact)
+        return findInconsistencies(groups);
+    return groups.filter((g) => isInconsistent(g) || g.occurrences.some((o) => o.prefix !== ''));
+}
+/**
+ * A repair that silently skipped part of its job must not report success.
+ *
+ * The loop that produces is gate red → repair "done" → gate red, where the second red
+ * reads as if the repair had never run. `^1.x` is the shape that lands here: `--check
+ * --exact` flags the operator, and no single version can be read out of the range to pin
+ * it at, so there is nothing to write and the CLI says which deps those are instead.
+ */
+function reportUnrepairable(groups) {
+    console.error(`\ngjsify upgrade --align: ${groups.length} dep(s) left unrepaired — no version to align on:\n`);
+    for (const g of groups) {
+        console.error(`  ${ANSI.bold}${g.name}${ANSI.reset}  ${[...g.declaredRanges].join(', ')}`);
+    }
+    console.error(`\nThose ranges name no single version. Edit them by hand, or resolve one with \`--latest\`.`);
+    return process.exit(1);
+}
 function runAlignMode(groups, args) {
-    const inconsistencies = findInconsistencies(groups);
-    if (inconsistencies.length === 0) {
-        console.log(`gjsify upgrade --align: nothing to do. ${groups.length} dep(s) already consistent.`);
+    const exact = args.exact ?? false;
+    const targets = alignTargets(groups, exact);
+    if (targets.length === 0) {
+        console.log(`gjsify upgrade --align: nothing to do. ${groups.length} dep(s) already consistent` +
+            (exact ? `, every declaration pinned exactly.` : `.`));
         return;
     }
-    // For each inconsistency, the alignment target is the highest declared version
-    // — preserve the prefix of the dominant occurrence so the range shape doesn't
-    // mutate (caret stays caret, tilde stays tilde).
+    // For each target, the alignment version is the highest declared one — preserve the
+    // prefix of the dominant occurrence so the range shape doesn't mutate (caret stays
+    // caret, tilde stays tilde). Under `--exact` the prefix is dropped, in `targetRange`.
     const updates = [];
-    for (const g of inconsistencies) {
-        if (!g.highestVersion)
+    const unrepairable = [];
+    for (const g of targets) {
+        if (!g.highestVersion) {
+            unrepairable.push(g);
             continue;
+        }
         // Pick a prefix: use the prefix of the dominant range; if dominant has
         // no prefix, default to "^" (the npm-cli default).
         const dominantOcc = g.occurrences.find((o) => o.currentRange === g.dominantRange);
@@ -375,21 +420,24 @@ function runAlignMode(groups, args) {
             occurrences: g.occurrences.map((o) => ({ ...o, prefix })),
         });
     }
-    if (updates.length === 0) {
-        console.log('gjsify upgrade --align: inconsistencies present but no parseable target version. No-op.');
-        return;
-    }
-    console.log(`gjsify upgrade --align: aligning ${updates.length} inconsistent dep(s) to their highest declared version:\n`);
-    for (const u of updates) {
-        const newPrefix = u.occurrences[0]?.prefix ?? '^';
-        console.log(`  ${u.name.padEnd(28)}  ranges: ${[...u.declaredRanges].join(', ')}  →  ${targetRange(newPrefix, u.latestVersion, args.exact ?? false)}`);
-    }
-    if (args.dryRun) {
-        console.log('\n[gjsify upgrade --align] --dry-run: no files changed.');
-        return;
+    if (updates.length > 0) {
+        console.log(exact
+            ? `gjsify upgrade --align --exact: pinning ${updates.length} dep(s) to their highest declared version, without a range operator:\n`
+            : `gjsify upgrade --align: aligning ${updates.length} inconsistent dep(s) to their highest declared version:\n`);
+        for (const u of updates) {
+            const newPrefix = u.occurrences[0]?.prefix ?? '^';
+            console.log(`  ${u.name.padEnd(28)}  ranges: ${[...u.declaredRanges].join(', ')}  →  ${targetRange(newPrefix, u.latestVersion, exact)}`);
+        }
+        if (args.dryRun) {
+            console.log('\n[gjsify upgrade --align] --dry-run: no files changed.');
+        }
+        else {
+            const files = applyToFiles(updates, exact);
+            console.log(`\n✏️  updated ${updates.length} dep(s) across ${files} package.json file(s).`);
+        }
     }
-    const files = applyToFiles(updates, args.exact);
-    console.log(`\n✏️  updated ${updates.length} dep(s) across ${files} package.json file(s).`);
+    if (unrepairable.length > 0)
+        return reportUnrepairable(unrepairable);
 }
 // ─── Registry resolution (group-aware) ─────────────────────────────────
 async function resolveCandidateGroups(groups, npmrc, verbose, mode) {

package/lib/config.js

@@ -5,6 +5,7 @@ import { pathToFileURL } from 'node:url';
 import { isGjs, hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { buildAppForRuntime } from './utils/runtimes.js';
 import { DIALECT_APPS, isSourceDialect, SOURCE_DIALECTS } from '@gjsify/rolldown-plugin-gjsify';
+import { GI_RENDERER_APPS } from '@gjsify/resolve-npm';
 /**
  * Does the failed `import()` of a config look like a MODULE-RESOLUTION failure
  * (the config imports something GJS's ESM loader can't resolve for an external
@@ -269,6 +270,8 @@ export class Config {
         configData.exclude = cliArgs.exclude || [];
         if (cliArgs.consoleShim !== undefined)
             configData.consoleShim = cliArgs.consoleShim;
+        if (cliArgs.giRenderer !== undefined)
+            configData.giRenderer = cliArgs.giRenderer;
         // `--dialect` narrows here rather than at the call site. yargs `choices`
         // already rejects an unknown value typed on the command line, but a
         // `gjsify.dialect` in package.json or `.gjsifyrc.*` never passes through
@@ -303,6 +306,16 @@ export class Config {
                 `It composes on ${[...DIALECT_APPS].join(' and ')} only. ` +
                 'Drop the dialect, or build one of those targets.');
         }
+        // Same rule for the `gi://` arm, and the same reason: `--gi-renderer --app gjs`
+        // would parse, resolve and compose nothing, so the flag would be accepted and
+        // ignored. On `gjs` and `node` the specifier is already answered — natively and
+        // through `requireGi` — so there is nothing for a renderer to substitute for.
+        if (configData.giRenderer === true && !GI_RENDERER_APPS.includes(configData.app)) {
+            throw new Error(`gjsify build: --gi-renderer has no effect on --app ${configData.app}. ` +
+                `It composes on ${GI_RENDERER_APPS.join(' and ')} only — the targets with no GObject ` +
+                '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.');
+        }
         if (cliArgs.globals !== undefined)
             configData.globals = cliArgs.globals;
         // Fallback applied post-merge (not as a yargs `default:`) so a

package/lib/types/cli-build-options.d.ts

@@ -36,6 +36,12 @@ export interface CliBuildOptions {
      * whatever was typed, and the narrowing happens once, where the value is read.
      */
     dialect?: string;
+    /**
+     * Resolve `gi://Ns?version=X` to the target's widget renderer instead of an empty
+     * module — `--gi-renderer` (ADR 0034 stage 9). `browser` and `nativescript` targets.
+     * Default: unset; see `ConfigData.giRenderer` for why it is opt-in.
+     */
+    giRenderer?: boolean;
     /**
      * Comma-separated global identifiers the code needs, e.g.
      * `"fetch,Buffer,process,URL,crypto"`. Each maps to the corresponding

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

@@ -96,6 +96,20 @@ export interface ConfigData {
      * see the header of `SourceDialect`.
      */
     dialect?: SourceDialect;
+    /**
+     * Resolve `gi://Ns?version=X` to the target's widget renderer rather than to an
+     * empty module (ADR 0034 stage 9). `--app browser` answers out of
+     * `@gjsify/adwaita-web`, `--app nativescript` out of `@gjsify/adwaita-nativescript`;
+     * `GI_RENDERERS` in `@gjsify/resolve-npm` is the table, and a target with no row
+     * there has no arm. Default: unset.
+     *
+     * Opt-in, never inferred: a `gi://` import reaching one of those targets today is
+     * usually a GJS-only code path pulled in transitively, which the empty module
+     * silences on purpose. On by default it would pull a widget toolkit into bundles
+     * that never named one, and turn every unanswerable namespace from a silent stub
+     * into a hard build failure.
+     */
+    giRenderer?: boolean;
     /** Comma-separated global identifiers to register. Format: see CliBuildOptions. */
     globals?: string;
     /**
@@ -464,14 +478,27 @@ export interface ConfigDataShip extends AppMetadata {
     /**
      * The built bundle `bin/<name>` executes. Default: `gjsify.main`, then
      * `package.json#main`. Its whole directory is staged into `lib/<name>/`.
+     *
+     * A STRING is one entry for every target; a TABLE names one per OS, keyed
+     * like {@link ShipAppOptions} and resolved beside it. An application with two
+     * hosts has two bundles built from one source — `gjsify.app` decides which
+     * runtime a target execs, and this decides which of those bundles it hands
+     * that runtime (#1545).
      */
-    bundle?: string;
+    bundle?: string | ShipBundleOptions;
     /** Icon file, or a directory of them. Sizes are read from the path or the filename. */
     icon?: string;
     /** A `*.gschema.xml` file, or a directory of them. */
     schemas?: string;
     /** Licence file. Default: the first of LICENSE, LICENSE.md, LICENSE.txt, COPYING. */
     licenseFile?: string;
+    /**
+     * The project's own changelog, rendered into the `.deb`'s
+     * `share/doc/<package>/changelog.Debian.gz` (Debian Policy § 4.4).
+     * Default: the first of CHANGELOG.md, CHANGELOG, CHANGELOG.txt, NEWS.md,
+     * searched up to the repository root exactly as `licenseFile` is.
+     */
+    changelogFile?: string;
     /** deb `Section:`. Default: derived from `categories`. */
     section?: string;
     /** rpm `Group:`. Default: derived from `categories`. */
@@ -611,6 +638,29 @@ export interface ShipAppOptions {
     /** What a Windows program directory carries. `node` is the only value its formats accept. */
     win32?: 'gjs' | 'node';
 }
+/**
+ * `gjsify.ship.bundle` — the ENTRY per OS, the twin of {@link ShipAppOptions}.
+ *
+ * The two answer one question between them, and answering only half of it is
+ * what #1545 measured: `gjsify.ship.app.darwin: "node"` pointed the launcher at
+ * `node` while the payload stayed the project's `main` — a `--app gjs` bundle,
+ * because Linux is that project's primary target. Both halves were honoured,
+ * they contradicted each other, and the `.app` died on its first import.
+ *
+ * Same OS spelling as everywhere else in this block (`process.platform`), and
+ * the same fall-through: a target with no key here keeps `gjsify.main`. What it
+ * does NOT keep is another target's entry — a bundle declared for one OS is
+ * dropped from every other OS's payload, since no interpreter but that one can
+ * load it.
+ */
+export interface ShipBundleOptions {
+    /** The entry a `.deb`/`.rpm`/Flatpak installs. */
+    linux?: string;
+    /** The entry `<App>.app/Contents/Resources/lib/` carries. */
+    darwin?: string;
+    /** The entry the Windows program directory carries. */
+    win32?: string;
+}
 /**
  * `gjsify.ship.sign` — an IDENTITY per OS, and never a certificate.
  *