@gjsify/cli 0.45.0 → 0.47.0

package/lib/commands/ship.js

@@ -35,19 +35,20 @@ import { discoverPayload } from '../utils/ship/discover.js';
 import { buildDmgImage, dmgVolumeDir, dmgVolumeName } from '../utils/ship/dmg.js';
 import { buildFlatpakBundle } from '../utils/ship/flatpak.js';
 import { localizeMetadata } from '../utils/ship/localize-metadata.js';
-import { assertHostCanFinish, assertToolsInstalled, configuredFormats, defaultFormatIds, formatIdsFor, resolveFormats, windowsProgramDirName, FORMAT_IDS, FORMATS, } from '../utils/ship/formats.js';
+import { assertHostCanFinish, assertToolsInstalled, canCarryTicket, configuredFormats, defaultFormatIds, formatIdsFor, resolveFormats, windowsProgramDirName, FORMAT_IDS, FORMATS, } from '../utils/ship/formats.js';
 import { assertLayoutSupportsArch, hostLayout, layoutForOs, place, placeStage, resolveLayout, LAYOUT_NAMES, } from '../utils/ship/layout.js';
 import { isNodeRuntimeTarget, resolveNodeRuntime } from '../utils/ship/node-runtime.js';
+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 { 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, resolveNotaryPlan, resolveSignPlan, signPayload, } from '../utils/ship/signing.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, resolveShipSettings } from '../utils/ship/settings.js';
+import { declaredBundlePath, resolveShipApp, 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]';
@@ -177,13 +178,21 @@ async function assemble(args) {
     const configData = await config.forCommand(projectDir);
     const ship = configData.ship ?? {};
     const flatpak = configData.flatpak ?? {};
-    assertShippableTarget(configData.app);
-    // Resolved HERE and not from `settings`, because the format list is decided
-    // before anything is built and `resolveShipSettings` runs after. The
-    // defaulting rule is the one `resolveShipSettings` states and must stay the
-    // same one: an undeclared target means `gjs`, never the host runtime this
-    // command happens to run under.
-    const interpreter = configData.app === 'node' ? 'node' : 'gjs';
+    // THE ONE RESOLUTION, and it runs HERE because the format list is decided
+    // before anything is built while `resolveShipSettings` runs after. Its result
+    // is threaded into the settings rather than re-derived there: two defaulting
+    // rules for one question is how the format list and the emitted `Depends:`
+    // came to answer for different targets (#1486). Why the runtime is per target
+    // at all, and why an absent override means the project field: `resolveShipApp`.
+    const resolvedApp = resolveShipApp({ project: configData.app, perTarget: ship.app, layoutOs: layout.os });
+    const interpreter = resolvedApp.app;
+    // SAID, not swallowed, like every other narrowing in this function. An
+    // override that changed the launcher, the dependency and the format list
+    // without a line of output is one nobody can tell from the project default.
+    if (resolvedApp.overridden) {
+        console.log(`${LOG} runtime for ${layout.name}: ${interpreter} — \`${resolvedApp.key}\` overrides ` +
+            `\`gjsify.app${configData.app === undefined ? '' : `: "${configData.app}"`}\`.`);
+    }
     const pkg = (readPackageJson(join(projectDir, 'package.json')) ?? {});
     // Resolved before anything is built or written: a typo'd `--target`
     // should not cost a build and leave a half-written `ship/stage/`.
@@ -233,8 +242,11 @@ async function assemble(args) {
         // and the two need different next steps.
         if (unusable.length > 0) {
             console.log(`${LOG} ${unusable.map((format) => format.id).join(', ')} wrap the ${layout.name} layout but ` +
-                `cannot run \`gjsify.app: "${interpreter}"\` — ${unusable[0]?.interpreterGap ?? ''}. ` +
-                'Assembling the layout only; pass --target to be told the same thing as an error.');
+                `cannot run \`${interpreter}\`, which \`${resolvedApp.key}\` resolves to — ` +
+                `${unusable[0]?.interpreterGap ?? ''}. Set \`gjsify.ship.app.${layout.os}\` to ` +
+                `"${unusable[0]?.interpreters.join('" / "')}" to ship this OS on that runtime; it leaves every ` +
+                'other target on `gjsify.app`. Assembling the layout only; pass --target to be told the same ' +
+                'thing as an error.');
         }
     }
     if (!args.stage)
@@ -282,7 +294,11 @@ async function assemble(args) {
         flatpak,
         cli: { outDir: args.out, arch: args.arch, layoutOs: layout.os },
         discovered,
-        app: configData.app,
+        // The RESOLVED runtime, never `configData.app`. Everything downstream —
+        // the launcher, `deriveDepends`, the carried runtime, the stage manifest —
+        // reads `settings.app`, so this is the one hand-off that decides whether
+        // those generators speak about this target or about the project.
+        app: interpreter,
     });
     for (const warning of warnings)
         console.warn(`${LOG} ${warning}`);
@@ -420,6 +436,17 @@ async function assemble(args) {
         if (runtime.launcher.interpreter === undefined && layout.runtimeGap !== undefined) {
             console.warn(`${LOG} ${layout.runtimeGap}`);
         }
+        // The same shape one axis over (ADR 0038). `share/fonts` is NOT in the list
+        // above — it needs no install step on any layout, so `linuxInstallDependent`
+        // classifies it as portable — but "the directory is reached" and "this OS's
+        // Pango reads that directory at all" are different questions, and only the
+        // first is settled by the payload. CONDITIONAL on the payload actually
+        // carrying a face, like `runtimeGap` is on the missing interpreter: telling a
+        // project that ships no font which fontconfig its Mac would consult is noise,
+        // and noise is what trains people to stop reading these lines.
+        if (layout.fontGap !== undefined && planned.some((file) => isUnder(file.path, SHARE.fonts))) {
+            console.warn(`${LOG} ${layout.fontGap}`);
+        }
         // THE OTHER AXIS, warned about HERE and refused in `packOne`, and the split
         // is the same one `runtimeGap` and `assertFormatCanRunInterpreter` already
         // draw. A stage is a build intermediate, and assembling one for an
@@ -517,7 +544,11 @@ async function assemble(args) {
         // none; or the configured `targets` all wrap another one, which the branch
         // above has already SAID in its own words rather than repeating here.
         const none = unusable.length > 0
-            ? `(none — ${unusable.map((format) => format.id).join(' and ')} need \`gjsify.app: "node"\`)`
+            ? // The key that fixes it, which used to be `gjsify.app` and is now
+                // this target's own: naming the project field here is how a macOS
+                // stage came to move the Linux `Depends:` (#1486).
+                `(none — ${unusable.map((format) => format.id).join(' and ')} need ` +
+                    `\`gjsify.ship.app.${layout.os}: "node"\`)`
             : formatIdsFor(layout.os).length === 0
                 ? `(none — no format wraps the ${layout.name} layout)`
                 : '(none asked for)';
@@ -842,6 +873,13 @@ async function packOne(input) {
             identity: input.sign.identity,
             signer: input.sign.signer,
             workDir: join(outRoot, 'signed', format.id),
+            // What the darwin signer SEALS, from the layout that named it —
+            // `<App>.app` there, `''` on the two layouts with no bundle.
+            bundleRoot: layout.root(settings),
+            // OUTSIDE `signed/<id>/`: that directory is listed and compared
+            // with the payload, so an entitlements plist written into it would
+            // read as a file `codesign` added.
+            entitlementsPath: join(outRoot, 'signed', `${format.id}.entitlements.plist`),
             verbose: input.verbose,
             log: (line) => console.log(`${LOG} ${line}`),
         })
@@ -1030,6 +1068,27 @@ async function packOne(input) {
                 verbose: input.verbose,
                 log: (line) => console.log(`${LOG} ${line}`),
             });
+            // AND THEN THE TICKET, on the artifacts that can hold one. Submitting
+            // and stapling are two questions with two answers, and the `.zip` is
+            // where they come apart: the notary service accepts it and `stapler`
+            // refuses it. Without the ticket the artifact still installs — every
+            // launch asks Gatekeeper online instead, and fails closed on a machine
+            // with no network, which is the failure a user reads as "the app is
+            // damaged".
+            if (canCarryTicket(format.id)) {
+                await stapleArtifact({
+                    notary: input.notarize.notary,
+                    artifact: target,
+                    verbose: input.verbose,
+                    log: (line) => console.log(`${LOG} ${line}`),
+                });
+            }
+            else {
+                console.warn(`${LOG} ${format.id} is notarised and NOT stapled: \`stapler\` takes a UDIF image, a ` +
+                    "signed flat package or a code-signed bundle, and an archive is none of them. Apple's " +
+                    'remedy is to staple each item that went INTO the archive and re-create it — for this ' +
+                    'artifact that is the `.app`, which `--target macos-app` writes beside it.');
+            }
         }
     }
     return { format: format.id, path: target, size };
@@ -1078,8 +1137,10 @@ function assertPackable(formats, layout, chosenBy, unusable = []) {
     if (unusable.length > 0) {
         throw new Error(`gjsify ship: ${unusable.map((format) => format.id).join(' and ')} wrap the ${layout.name} ` +
             `layout, and neither can run this project — ${unusable[0]?.interpreterGap ?? ''}.\n` +
-            `    \`gjsify ship ${layout.name} --stage\` assembles the tree anyway; packing it is what ` +
-            'the milestone that stages an interpreter is for (#1354 M2b).');
+            `    Set \`gjsify.ship.app.${layout.os}\` to ` +
+            `"${unusable[0]?.interpreters.join('" / "')}" — it overrides \`gjsify.app\` for THIS target and\n` +
+            '    leaves every other one alone, which is what lets one project be GJS on Linux and Node here.\n' +
+            `    \`gjsify ship ${layout.name} --stage\` assembles the tree either way.`);
     }
     // A THIRD emptiness, and the one the last throw in this function used to
     // mis-diagnose. A layout that HAS formats still reaches here with none
@@ -1136,66 +1197,13 @@ function assertPackable(formats, layout, chosenBy, unusable = []) {
         ' Every layout this gjsify knows has one (ADR 0024 stages 2-5), so this is a layout added ' +
         'without a `FORMATS` row.');
 }
-/**
- * Refuse a build target this command cannot package correctly.
- *
- * `gjs` and `node` are packageable: `renderLauncher` execs the one
- * `settings.app` names and `deriveDepends` declares the same one — `gjs >= …`,
- * or `nodejs (>= 24)` / `nodejs(engine) >= 24`. Until #1354's M0 this said "only
- * `gjs` can be packaged today", which was true: the launcher execed gjs
- * unconditionally, so a `--app node` package would have installed and died at
- * startup.
- *
- * `browser` and `nativescript` stay refused, and not for want of a launcher
- * line: a browser bundle has no process to start, and NativeScript ships as an
- * APK/IPA through a different pipeline entirely (ADR 0024 § 4).
- *
- * DELIBERATELY NOT PER LAYOUT, and the first cut of the layout axis got this
- * exactly backwards. Reading ADR § 4's runtime table as a per-layout `app`
- * requirement refused `gjsify.app: "gjs"` for the macOS layout — i.e. refused the
- * entire audience of this command from assembling a `.app` — while a project with
- * no `gjsify.app` key sailed through and staged a launcher naming `node` in front
- * of a GJS bundle. Both halves came from the same mistake: § 4 derives the runtime
- * a SHIPPED ARTIFACT carries, which is `Layout.shippedRuntime` and is printed as
- * `Layout.runtimeGap`. What the launcher execs is what the PAYLOAD was built for,
- * and that is `settings.app` on every layout.
- *
- * An undeclared target is the common case for a GJS app and is allowed. It must
- * NOT be resolved through `Config.forBuild`, whose fallback is the HOST runtime
- * — that would refuse, or worse silently re-target, a perfectly good GJS project
- * merely for running this command under Node.
- *
- * WHY THIS REFUSES AND `Layout.runtimeGap` ONLY WARNS, since the two describe
- * neighbouring predicaments and get opposite treatment. A target this command
- * cannot package would leave here as an ARTIFACT — a `.deb` a stranger installs,
- * which then fails at startup, with no gate between here and their machine. The
- * `runtimeGap` warns about something that is not an artifact: it is printed over a
- * staged tree, and only when that tree carries no interpreter of its own.
- *
- * This paragraph used to end "the day a Windows format exists, that warning has to
- * become this refusal". #1354 M3 is that day, and the refusal it became is
- * {@link assertFormatCanRunInterpreter} — per FORMAT rather than per layout,
- * because what a runtime can execute is a property of the container and not of the
- * tree it wraps. This function stayed exactly as wide as it was.
- *
- * Phase one only. Phase two does not re-read `gjsify.app` — it has no project —
- * but it is not unchecked either: `assertLauncherMatchesInterpreter` compares
- * the staged `bin/<name>`'s own `exec` line against the dependency about to be
- * written.
- */
-function assertShippableTarget(app) {
-    if (app === undefined || app === 'gjs' || app === 'node')
-        return;
-    throw new Error(`gjsify ship: this project declares \`gjsify.app: "${app}"\`, and only \`gjs\` and \`node\` can be ` +
-        'packaged. A browser bundle has no process to launch, and a NativeScript app ships as an APK/IPA ' +
-        'through a different pipeline. ADR 0024 § 4 has the runtime-per-OS table.');
-}
 /**
  * Refuse a format whose runtime cannot provide the interpreter the launcher execs.
  *
  * THE HOLE THIS CLOSES, and it was opened by the commit that made `--app node`
- * packageable. `assertShippableTarget` used to refuse `app: 'node'` outright, so
- * no format ever saw one. Lifting that made deb and rpm correct and left Flatpak
+ * packageable. The shippable-target refusal — `resolveShipApp` in
+ * `utils/ship/settings.ts`, a free function in this file until #1486 — used to
+ * refuse `app: 'node'` outright, so no format ever saw one. Lifting that made deb and rpm correct and left Flatpak
  * silently wrong: measured at exit 0, a `--target flatpak --stage` with
  * `app: 'node'` emitted a manifest with `runtime: org.gnome.Platform`,
  * `runtime-version: 50`, no `sdk-extensions` and no `append-path`, beside a
@@ -1213,14 +1221,19 @@ function assertShippableTarget(app) {
 function assertFormatCanRunInterpreter(format, app) {
     if (format.interpreters.includes(app))
         return;
-    throw new Error(`gjsify ship: this project is \`gjsify.app: "${app}"\`, and the ${format.id} runtime cannot run it — ` +
-        `it provides ${format.interpreters.join(', ')}.\n` +
+    throw new Error(
+    // The TARGET's runtime, not "this project is": since #1486 the two can
+    // differ, and a message naming `gjsify.app` for a per-target answer sends
+    // the reader to the key whose edit moves every OTHER target's `Depends:`.
+    `gjsify ship: this ${format.layoutOs} target runs \`${app}\`, and the ${format.id} runtime cannot ` +
+        `run it — it provides ${format.interpreters.join(', ')}.\n` +
         // The ROW's own sentence, not one written here. Hardcoded, this
         // paragraph told the first `.app` author about
         // `org.freedesktop.Sdk.Extension.node2x` and the GNOME runtime.
         `    ${format.interpreterGap}.\n` +
-        '    Build the formats that wrap this layout and can run it, or ship this app as ' +
-        `\`gjsify.app: "${format.interpreters.join('" / "')}"\`.`);
+        '    Build the formats that wrap this layout and can run it, or set ' +
+        `\`gjsify.ship.app.${format.layoutOs}: "${format.interpreters.join('" / "')}"\` ` +
+        '(which overrides `gjsify.app` for this target alone).');
 }
 /**
  * Run the project's own `build` script, as a CHILD process.

package/lib/commands/upgrade.d.ts

@@ -1,3 +1,4 @@
+import { type DependencyGroup } from '../utils/dep-aggregation.js';
 import type { Command } from '../types/index.js';
 interface UpgradeOptions {
     latest?: boolean;
@@ -8,10 +9,32 @@ interface UpgradeOptions {
     excludeWorkspace?: string;
     align?: boolean;
     check?: boolean;
+    exact?: boolean;
     dryRun?: boolean;
     cwd?: string;
     verbose?: boolean;
     yes?: boolean;
 }
 export declare const upgradeCommand: Command<unknown, UpgradeOptions>;
+/**
+ * `--exact` half of the CI gate: does every matched dep carry a bare version?
+ *
+ * Consistency and exactness are different questions, and the first cannot answer the
+ * second: a repository where every manifest agrees on `^4.1.0` is perfectly consistent
+ * and still lets a minor release move a subpath under a lockfile-less install. That is
+ * the hazard ADR 0029 § Risks 1 names for `@girs/*`, whose `./vocabulary` export is what
+ * `@gjsify/gtk-host` consumes — so the pin has to be the whole version, and something
+ * has to say so on every PR.
+ *
+ * Returns the number of offending declarations so the caller can exit once for both arms.
+ */
+export declare function reportInexactRanges(groups: readonly DependencyGroup[]): number;
+/**
+ * The range a dependency will be WRITTEN at.
+ *
+ * Preview and write share this deliberately. They were two expressions for one decision
+ * for exactly one revision, and `--dry-run --exact` announced `^4.3.0` while the writer
+ * would have produced `4.3.0` — a tool describing a change it was not about to make.
+ */
+export declare function targetRange(prefix: string, version: string, exact: boolean): string;
 export {};

package/lib/commands/upgrade.js

@@ -79,6 +79,11 @@ export const upgradeCommand = {
             description: 'CI gate: exit non-zero when any dep is declared inconsistently across workspaces. Implies offline (no registry calls). Pairs with `--align` as the fix.',
             type: 'boolean',
             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.',
+            type: 'boolean',
+            default: false,
         })
             .option('dry-run', {
             description: 'Print the upgrade plan without writing package.json files.',
@@ -118,7 +123,7 @@ export const upgradeCommand = {
         const groups = groupByDependency(decls);
         // --check: exit non-zero if any inconsistency.
         if (args.check) {
-            return runCheckMode(groups);
+            return runCheckMode(groups, args.exact);
         }
         // --align: offline consistency-only, no registry calls.
         if (args.align) {
@@ -163,10 +168,10 @@ export const upgradeCommand = {
         if (args.dryRun) {
             const fileCount = uniqueLocations(selected).length;
             console.log(`[gjsify upgrade] --dry-run: would update ${selected.length} deps across ${fileCount} package.json file(s).`);
-            printChangePlan(selected);
+            printChangePlan(selected, args.exact);
             return;
         }
-        const files = applyToFiles(selected);
+        const files = applyToFiles(selected, args.exact);
         console.log(`✏️  updated ${selected.length} dep(s) across ${files} package.json file(s). Run \`gjsify install\` to apply.`);
     },
 };
@@ -281,10 +286,53 @@ function splitRange(range) {
     return { prefix, version: parsed?.version ?? null };
 }
 // ─── Modes: --check / --align ──────────────────────────────────────────
-function runCheckMode(groups) {
+/**
+ * `--exact` half of the CI gate: does every matched dep carry a bare version?
+ *
+ * Consistency and exactness are different questions, and the first cannot answer the
+ * second: a repository where every manifest agrees on `^4.1.0` is perfectly consistent
+ * and still lets a minor release move a subpath under a lockfile-less install. That is
+ * the hazard ADR 0029 § Risks 1 names for `@girs/*`, whose `./vocabulary` export is what
+ * `@gjsify/gtk-host` consumes — so the pin has to be the whole version, and something
+ * has to say so on every PR.
+ *
+ * Returns the number of offending declarations so the caller can exit once for both arms.
+ */
+export function reportInexactRanges(groups) {
+    const offenders = groups
+        .map((g) => ({ name: g.name, loose: g.occurrences.filter((o) => o.prefix !== '') }))
+        .filter((entry) => entry.loose.length > 0);
+    if (offenders.length === 0)
+        return 0;
+    const total = offenders.reduce((n, entry) => n + entry.loose.length, 0);
+    console.error(`gjsify upgrade --check --exact: FAIL. ${total} declaration(s) across ${offenders.length} dep(s) carry a range operator:\n`);
+    for (const entry of offenders) {
+        const byRange = new Map();
+        for (const occ of entry.loose) {
+            const list = byRange.get(occ.currentRange) ?? [];
+            list.push(occ.workspace);
+            byRange.set(occ.currentRange, list);
+        }
+        console.error(`  ${ANSI.bold}${entry.name}${ANSI.reset}`);
+        for (const [range, holders] of byRange.entries()) {
+            const shown = holders.length > 6 ? `${holders.slice(0, 6).join(', ')} … +${holders.length - 6}` : holders.join(', ');
+            console.error(`    ${range.padEnd(16)} — ${shown}`);
+        }
+    }
+    return total;
+}
+function runCheckMode(groups, exact = false) {
+    const inexact = exact ? reportInexactRanges(groups) : 0;
     const inconsistencies = findInconsistencies(groups);
+    if (inconsistencies.length === 0 && inexact > 0) {
+        console.error(`\nFix: run \`gjsify upgrade --align --exact\` (offline; drops the operator and keeps the version).`);
+        // `return`, not a bare call: under GJS the process does not halt here, and the
+        // consistency report below would run on top of the exactness one.
+        return process.exit(1);
+    }
     if (inconsistencies.length === 0) {
-        console.log(`gjsify upgrade --check: OK. ${groups.length} dep(s) consistently declared across workspaces.`);
+        console.log(`gjsify upgrade --check: OK. ${groups.length} dep(s) consistently declared across workspaces` +
+            (exact ? `, every declaration pinned exactly.` : `.`));
         return;
     }
     console.error(`gjsify upgrade --check: FAIL. ${inconsistencies.length} dep(s) declared at inconsistent ranges:\n`);
@@ -334,13 +382,13 @@ function runAlignMode(groups, args) {
     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(', ')}  →  ${newPrefix}${u.latestVersion}`);
+        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;
     }
-    const files = applyToFiles(updates);
+    const files = applyToFiles(updates, args.exact);
     console.log(`\n✏️  updated ${updates.length} dep(s) across ${files} package.json file(s).`);
 }
 // ─── Registry resolution (group-aware) ─────────────────────────────────
@@ -491,10 +539,10 @@ function renderDeclaredCell(c) {
         return joined;
     return joined.slice(0, 29) + '…';
 }
-function printChangePlan(selected) {
+function printChangePlan(selected, exact = false) {
     for (const u of selected) {
         for (const occ of u.occurrences) {
-            console.log(`  ${occ.workspace.padEnd(38)}  ${u.name.padEnd(28)}  ${occ.currentRange.padEnd(12)} → ${occ.prefix}${u.latestVersion}`);
+            console.log(`  ${occ.workspace.padEnd(38)}  ${u.name.padEnd(28)}  ${occ.currentRange.padEnd(12)} → ${targetRange(occ.prefix, u.latestVersion, exact)}`);
         }
     }
 }
@@ -543,7 +591,17 @@ async function promptSelection(candidates) {
     }
 }
 // ─── Write-back across all affected workspaces ─────────────────────────
-function applyToFiles(updates) {
+/**
+ * The range a dependency will be WRITTEN at.
+ *
+ * Preview and write share this deliberately. They were two expressions for one decision
+ * for exactly one revision, and `--dry-run --exact` announced `^4.3.0` while the writer
+ * would have produced `4.3.0` — a tool describing a change it was not about to make.
+ */
+export function targetRange(prefix, version, exact) {
+    return exact ? version : `${prefix}${version}`;
+}
+function applyToFiles(updates, exact = false) {
     // Group by workspace.location so each package.json is read + written once.
     const byLocation = new Map();
     for (const u of updates) {
@@ -559,25 +617,50 @@ function applyToFiles(updates) {
         const raw = readFileSync(pkgJsonPath, 'utf-8');
         const pkg = JSON.parse(raw);
         let changed = false;
+        const changedNames = [];
         for (const g of groups) {
             const occ = g.occurrences[0];
             const map = pkg[occ.field];
             if (!map)
                 continue;
-            const next = `${occ.prefix}${g.latestVersion}`;
+            const next = targetRange(occ.prefix, g.latestVersion, exact);
             if (map[g.name] !== next) {
                 map[g.name] = next;
                 changed = true;
+                changedNames.push(g.name);
             }
         }
         if (changed) {
             const indent = detectIndent(raw);
-            writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, indent) + (raw.endsWith('\n') ? '\n' : ''), 'utf-8');
+            const rewritten = JSON.stringify(pkg, null, indent) + (raw.endsWith('\n') ? '\n' : '');
+            writeFileSync(pkgJsonPath, keepUntouchedLines(raw, rewritten, changedNames), 'utf-8');
             touched++;
         }
     }
     return touched;
 }
+/**
+ * Take the re-serialised file, but keep every line that is not about a changed dep.
+ *
+ * A `JSON.parse` → `JSON.stringify` round trip rewrites the WHOLE file, and re-encoding
+ * is not identity: measured on this repository, pinning `@girs/*` decoded `\u2014` into
+ * an em dash inside three `description` fields nobody asked to touch, so a dependency
+ * bump arrived as a diff over unrelated prose. Semantically equal, and still noise a
+ * reviewer has to read past.
+ *
+ * Line-for-line only. Adding or removing a key changes the line count, and then the
+ * mapping is not sound — so that case falls back to the plain re-serialisation rather
+ * than guessing an alignment.
+ */
+function keepUntouchedLines(raw, rewritten, changedNames) {
+    const before = raw.split('\n');
+    const after = rewritten.split('\n');
+    if (before.length !== after.length)
+        return rewritten;
+    return after
+        .map((line, i) => (changedNames.some((name) => line.includes(`"${name}"`)) ? line : before[i]))
+        .join('\n');
+}
 function uniqueLocations(updates) {
     const set = new Set();
     for (const u of updates) {

package/lib/templates/install.mjs.tmpl

@@ -18,8 +18,8 @@
  * GJSIFY_INSTALL_BOOTSTRAP_CACHE.
  */
 
-import GLib from 'gi://GLib';
-import Gio from 'gi://Gio';
+import GLib from 'gi://GLib?version=2.0';
+import Gio from 'gi://Gio?version=2.0';
 import system, { exit } from 'system';
 
 /**

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

@@ -430,6 +430,25 @@ export interface ConfigDataShip extends AppMetadata {
     release?: string;
     /** `Maintainer:` / `Packager:` as `Name <email>`. Default: `package.json#author`. */
     maintainer?: string;
+    /**
+     * The runtime a shipped artifact runs, PER TARGET — `gjsify.app` is the
+     * default and a key here overrides it for one layout.
+     *
+     * KEYED IN THE `process.platform` SPELLING, like {@link ShipSignOptions} and
+     * for the same reason: the value that resolves is chosen by the LAYOUT being
+     * assembled — `FormatDescriptor.layoutOs` and the stage manifest's `target.os`
+     * — never by the host doing the assembling. `macos` and `windows` are the
+     * `gjsify ship <os>` POSITIONAL's spelling, and both `gjsify ship` and
+     * `manifest-conformance`'s `ship` rule refuse them BY NAME, because a runtime
+     * under a key nothing reads is a target that silently keeps the project-wide
+     * answer.
+     *
+     * `resolveShipApp` (`utils/ship/settings.ts`) is the only reader of this key
+     * or of `gjsify.app`, and holds the rest: what one field could not answer,
+     * the measurement behind it, and why an absent key means `gjsify.app` and
+     * never `Layout.shippedRuntime`.
+     */
+    app?: ShipAppOptions;
     /**
      * Formats to build when `--target` is not given. Default `['deb', 'rpm']`.
      *
@@ -526,6 +545,30 @@ export interface ConfigDataShip extends AppMetadata {
      * produces a package that installs its translations and shows none of them.
      */
     localeDir?: string;
+    /**
+     * A font file, or a directory of them, the application SHIPS (ADR 0038).
+     * Default: `data/fonts` when it exists.
+     *
+     * Staged into `share/fonts/<appId>/`, which is where fontconfig looks: under a
+     * `/usr` prefix through the stock `fonts.conf`'s unconditional
+     * `<dir>/usr/share/fonts</dir>`, and under every other prefix through
+     * `<dir prefix="xdg">fonts</dir>` plus the `XDG_DATA_DIRS` the launcher already
+     * exports. The app names the FAMILY in its styles and needs no install-layout
+     * knowledge, exactly as it needs none for icons or schemas.
+     *
+     * This is what a branded application needs: on a GNOME host the family is
+     * usually installed anyway, and on macOS, on Windows and on any Linux that is
+     * not GNOME it is not — so without shipping it Pango silently substitutes a
+     * fallback and the app merely looks wrong, at exit 0.
+     *
+     * `.woff` / `.woff2` / `.eot` are REFUSED. Whether FreeType opens a web-font
+     * wrapper is a BUILD option of the FreeType the app runs against (brotli for
+     * woff2, zlib for woff), so it is a property of the host's or the bundle's
+     * closure rather than of the file — and a font that resolves on the developer's
+     * box and not in the shipped bundle is the exact silent substitution this key
+     * exists to prevent. Ship the desktop face.
+     */
+    fonts?: string;
     /** Extra payload entries: prefix-relative destination → project-relative source. */
     extraFiles?: Record<string, string>;
     /** Arguments the launcher appends before the user's own. */
@@ -547,6 +590,27 @@ export interface ConfigDataShip extends AppMetadata {
      */
     sign?: ShipSignOptions;
 }
+/**
+ * `gjsify.ship.app` — the shipped runtime per OS, overriding `gjsify.app`.
+ *
+ * All three keys are present, which is where this differs from
+ * {@link ShipSignOptions}: `linux` is absent there because a `.deb` carries no
+ * per-file signature, while a Linux artifact very much has a runtime — it is the
+ * one that emits `Depends: gjs (>= 1.86)` or `Depends: nodejs (>= 24)`, and the
+ * whole point of this table is that stating darwin's answer must not move it.
+ *
+ * Only `gjs` and `node` are shippable. `browser` has no process to launch and
+ * `nativescript` ships as an APK/IPA through another pipeline (ADR 0024 § 4), so
+ * either one is refused here exactly as it is on `gjsify.app`.
+ */
+export interface ShipAppOptions {
+    /** What a `.deb`/`.rpm`/Flatpak depends on and what its launcher execs. */
+    linux?: 'gjs' | 'node';
+    /** What a `<App>.app` carries. `node` is the only value the macOS formats accept. */
+    darwin?: 'gjs' | 'node';
+    /** What a Windows program directory carries. `node` is the only value its formats accept. */
+    win32?: 'gjs' | 'node';
+}
 /**
  * `gjsify.ship.sign` — an IDENTITY per OS, and never a certificate.
  *

package/lib/utils/gi-search-path.js

@@ -36,9 +36,17 @@ import { detectNativePackages } from './detect-native-packages.js';
  *
  * `globalThis.imports?.gi` is both the sanctioned GJS probe spelling
  * (`.oxlintrc.json`) and the correct CONDITION, so no `isGjs()` beside it: the
- * question is "is there a GIRepository to prepend to", and a Node host answers
- * no by itself — the required no-op, since on Node the CLI uses the npm
- * `rolldown` crate and never wants a prebuild.
+ * question is "is there a GIRepository to prepend to", and a plain Node process has
+ * none — nothing here to write to, which is the required no-op.
+ *
+ * NOT because a Node host wants no prebuild. That justification stood here and is
+ * false exactly where it matters: on darwin `@gjsify/webkit-native`'s prebuild is
+ * the ONLY WebKit any host has (ADR 0022), and ADR 0024 § 4 puts macOS and Windows
+ * applications on Node + node-gi. What is true is narrower — the CLI on Node uses
+ * the npm `rolldown` crate — and generalising it to "a Node host never wants a
+ * prebuild" is what kept every OTHER Node prebuild env-bound until
+ * `@gjsify/node-gi`'s `native-prebuilds.js` (ADR 0021 § The Node host). The Node
+ * host is covered THERE, in the package that owns a GIRepository, not here.
  *
  * `dup_default()` is GLib >= 2.86, probed as a capability rather than caught:
  * an older GLib simply keeps today's behaviour (the launcher's environment, or