@gjsify/cli 0.53.0 → 0.54.0

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

@@ -5,6 +5,11 @@ export interface RpmInputs {
     payload: readonly PayloadEntry[];
     prefix: string;
     depends: readonly string[];
+    /**
+     * Soft dependencies, written as the `RECOMMEND*` tags — an `&optional` typelib
+     * (ADR 0087), which the package installs with and runs without.
+     */
+    recommends?: readonly string[];
     /** RPM architecture (`x86_64`, `noarch`, …). */
     archLabel: string;
     mtime: number;

package/lib/utils/ship/rpm.js

@@ -54,6 +54,17 @@ const TAG = {
     REQUIREFLAGS: 1048,
     REQUIRENAME: 1049,
     REQUIREVERSION: 1050,
+    // The recommend trio. NOT the 1099/1046/1047 of rpm ≤ 4.18, which shared ONE
+    // index space with `REQUIRENAME`; since 4.19 each dependency tag carries its
+    // own arrays. MEASURED against a package `rpmbuild` produced and read back with
+    // `rpm` 6.0.2: RECOMMENDNAME is a STRING_ARRAY of its own right after
+    // PROVIDEVERSION, not an extension of the four REQUIRE entries. The numbers are
+    // in the 5000s for that reason and a wrong one is invisible here — rpm either
+    // ignores the tag or refuses the header, and `rpm -qp --recommends` is what
+    // says which (e2e `ship`).
+    RECOMMENDNAME: 5046,
+    RECOMMENDVERSION: 5047,
+    RECOMMENDFLAGS: 5048,
     RPMVERSION: 1064,
     POSTINPROG: 1086,
     POSTUNPROG: 1088,
@@ -225,6 +236,10 @@ function mainHeaderEntries(inputs, files, cpio, compressed) {
     // From the PAYLOAD, not the settings — see the same call in `deb.ts`.
     const scripts = renderRpmScriptlets(readPayloadFacts(inputs.payload), inputs.prefix);
     const requires = buildRequires(inputs.depends, scripts, readShebangInterpreters(inputs.payload));
+    // OMITTED, not written empty: rpm rejects a zero-count array (the same rule
+    // `encodeValue` enforces), so a package with no `&optional` namespace carries
+    // no RECOMMEND tag at all.
+    const recommends = buildRecommends(inputs.recommends ?? []);
     const entries = [
         { tag: TAG.HEADERI18NTABLE, type: RpmType.STRING_ARRAY, value: ['C'] },
         { tag: TAG.NAME, type: RpmType.STRING, value: settings.binaryName },
@@ -277,6 +292,13 @@ function mainHeaderEntries(inputs, files, cpio, compressed) {
         { tag: TAG.REQUIRENAME, type: RpmType.STRING_ARRAY, value: requires.names },
         { tag: TAG.REQUIREFLAGS, type: RpmType.INT32, value: requires.flags },
         { tag: TAG.REQUIREVERSION, type: RpmType.STRING_ARRAY, value: requires.versions },
+        ...(recommends.names.length > 0
+            ? [
+                { tag: TAG.RECOMMENDNAME, type: RpmType.STRING_ARRAY, value: recommends.names },
+                { tag: TAG.RECOMMENDFLAGS, type: RpmType.INT32, value: recommends.flags },
+                { tag: TAG.RECOMMENDVERSION, type: RpmType.STRING_ARRAY, value: recommends.versions },
+            ]
+            : []),
         { tag: TAG.PAYLOADFORMAT, type: RpmType.STRING, value: 'cpio' },
         { tag: TAG.PAYLOADCOMPRESSOR, type: RpmType.STRING, value: 'gzip' },
         // Write-side metadata only — no reader acts on it (rpm-format.md § 6.5).
@@ -383,6 +405,26 @@ function buildRequires(depends, scripts, interpreters) {
     }
     return { names, flags, versions };
 }
+/**
+ * The three parallel `Recommends` arrays — the soft half of
+ * {@link buildRequires}, same relation spelling, no `RPMLIB` and no sense bits.
+ *
+ * `0` is the right flags value and not a missing one: rpm reads an unversioned
+ * recommendation as "any version", which is what an `&optional` typelib package
+ * means (the app asks for the NAMESPACE, never for a version of the package).
+ */
+function buildRecommends(recommends) {
+    const names = [];
+    const flags = [];
+    const versions = [];
+    for (const depend of recommends) {
+        const parsed = parseDepend(depend);
+        names.push(parsed.name);
+        flags.push(senseFor(parsed.relation));
+        versions.push(parsed.version ?? '');
+    }
+    return { names, flags, versions };
+}
 function senseFor(relation) {
     switch (relation) {
         case '>=':

package/lib/utils/ship/settings.js

@@ -166,6 +166,12 @@ export function resolveShipSettings(input) {
         throw new Error('gjsify ship: no licence — set `license` in package.json (an SPDX id, e.g. "MIT") ' +
             'or `gjsify.ship.license.project`. Both deb and rpm carry it as a required field.');
     }
+    // Written BACK, not read twice: the packers read `settings.license` and the AppStream
+    // renderers read `metadata.license.project`, so resolving the `package.json#license`
+    // fallback into the first alone left `<project_license>` empty in the staged metainfo
+    // and warned about a field the project had answered. The returned metadata is what every
+    // renderer reads, so this is where the one answer has to land.
+    metadata.license = { ...metadata.license, project: license };
     const maintainer = ship.maintainer ?? formatAuthor(pkg.author) ?? formatDeveloper(metadata);
     if (!maintainer) {
         throw new Error('gjsify ship: no maintainer — set `author` in package.json ("Name <you@example.com>"), ' +

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

@@ -30,14 +30,19 @@ export interface SignerDescriptor {
     /** argv after {@link tool}, for ONE file. */
     args: (input: SignArgs) => readonly string[];
     /**
-     * The entitlements this signer asks for, or `[]` where the OS has none.
+     * The entitlements this signer asks for, given the identity in hand.
+     *
+     * A FUNCTION, not a list, and the darwin row's second argument is what makes
+     * that necessary: the set depends on whether the identity is a real one, and
+     * one entitlement is exactly wrong in one of the two directions. It is a
+     * measured difference, not a preference — see {@link SIGNERS}.darwin.
      *
      * `[]` is an ANSWER and not an omission — the same rule `Layout.metadata`
      * states. Windows has no equivalent concept at all, and a signer that granted
      * nothing on macOS would be a different decision from one that has nothing to
      * grant.
      */
-    entitlements: readonly string[];
+    entitlements: (adhoc: boolean) => readonly string[];
     /**
      * Does this signer seal the ARTIFACT ROOT after signing the images inside it?
      *

package/lib/utils/ship/signing.js

@@ -18,7 +18,10 @@
 //     an ad-hoc `LC_CODE_SIGNATURE` already (they must — `install_name_tool`
 //     invalidates the original during relocation). So the darwin leg re-signs
 //     every image, and the result is new BYTES for the packer rather than a
-//     container around the old ones.
+//     container around the old ones. § A16's corollary of this — "the same
+//     identity everywhere, so library validation has nothing to object to" — is
+//     measured FALSE for the ad-hoc identity, and the darwin row's
+//     `entitlements` is where that correction lives.
 //  4. THE ORDER IS STRUCTURAL, not conventional (§ A17). `readStage` compares
 //     each file's SIZE against `.gjsify-ship-stage.json`, and a size is no more
 //     re-sign-proof than a digest. BOTH halves are measured and they agree:
@@ -66,10 +69,10 @@
 //    `.dmg` is stapled and the `.zip` is told what a user has to do instead.
 //
 // WHAT IS STILL NOT DONE, deliberately: `signtool` is never given a timestamp URL
-// (see the win32 row), and the entitlement § A16 is about —
-// `com.apple.security.cs.disable-library-validation` — is NOT granted, because
-// § A4's re-sign of every image in the closure is the design of record and
-// granting the entitlement would quietly make it look unnecessary.
+// (see the win32 row), and the named-identity half of § A16 is untested because it
+// needs a certificate — the GRANT of `disable-library-validation` is the measured
+// ad-hoc answer, and § A4's re-sign of every image stays the design of record for
+// the Developer ID that notarisation will actually require.
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, sep } from 'node:path';
 import { isOnPath } from '../check-system-deps.js';
@@ -123,32 +126,52 @@ export const SIGNERS = {
             ...(adhoc ? [] : ['--timestamp']),
             file,
         ],
-        // FOUR OF THE REFERENCE'S SIX, and both omissions are decisions:
+        // FIVE OF THE REFERENCE'S SIX for an ad-hoc identity, FOUR for a real one,
+        // and the difference is the one § A16 left open — now MEASURED, on
+        // darwin-arm64 with the published `@gjsify/gtk-runtime-darwin-arm64` staged
+        // into the bundle (`utils/ship/layout.ts` carries the rest of that run).
         //
-        //  * `com.apple.security.cs.get-task-allow` is granted by
-        //    `refs/node/tools/osx-entitlements.plist:15` and is a DEBUGGING
-        //    entitlement — it lets another process attach to this one. Apple's
-        //    notarisation rules refuse a Developer-ID artifact carrying it, so
-        //    shipping it would trade a working debug build for an artifact that
-        //    cannot be distributed. The reference signs its own build; we sign what
-        //    a stranger downloads.
-        //  * `com.apple.security.cs.disable-library-validation` is § A16's open
-        //    question and stays open. § A4's design of record is that every Mach-O
-        //    in the closure is re-signed with the SAME identity as the launcher, so
-        //    library validation has nothing to object to — and granting the
-        //    entitlement anyway would make that re-sign look optional the first
-        //    time somebody reads this list.
+        // § A16's premise was that library validation has nothing to object to
+        // because every Mach-O carries the SAME identity as the launcher. That is
+        // true for a Developer ID and FALSE for `--sign -`: an ad-hoc signature has
+        // no team at all, so the running process and the dylib it dlopens report
+        // different team IDs and the load is refused —
         //
-        // The four that remain are what a shipped V8 needs under a hardened
-        // runtime, plus the one our own loader story needs:
-        // `@gjsify/node-gi`'s `maybeReexecForGtkRuntime` sets `DYLD_*` for its
-        // child on darwin, and a hardened process may not do that without
-        // `allow-dyld-environment-variables`.
-        entitlements: [
+        //   dlopen(…/prebuilds/darwin-arm64/node_gi.node): code signature in
+        //   <378B2FDA-…> '…node_gi.node' not valid for use in process: mapping
+        //   process and mapped file (non-platform) have different Team IDs
+        //
+        // — at `require('@gjsify/node-gi')`, the FIRST thing a shipped `.app` does,
+        // with every image correctly signed. Same bundle, same signer, same argv,
+        // one more entitlement: `interpreter:`/`gtk-runtime:`/`chrome: ok`/
+        // `render: 480x320`/`done: 0`.
+        //
+        // So it is granted WHERE IT IS NEEDED, which is ad-hoc only. A Developer ID
+        // signs the whole closure with one team and needs nothing, and Apple's
+        // notarisation rules read a `disable-library-validation` entitlement on a
+        // Developer-ID artifact as shipping unsigned code — so granting it there
+        // would trade a distributable artifact for a locally runnable one. The
+        // GRANT therefore stays what § A16 asked to know: § A4's re-sign of every
+        // image is the design of record, and the entitlement is what makes the
+        // ad-hoc proof of it RUNNABLE rather than a signature `codesign` accepts and
+        // dyld refuses.
+        //
+        // The four both share are what a shipped V8 needs under a hardened runtime,
+        // plus the one our own loader story needs: `@gjsify/node-gi`'s
+        // `maybeReexecForGtkRuntime` sets `DYLD_*` for its child on darwin, and a
+        // hardened process may not do that without `allow-dyld-environment-variables`.
+        //
+        // `get-task-allow` is absent from both, and that is a decision:
+        // `refs/node/tools/osx-entitlements.plist:15` grants it, it is a DEBUGGING
+        // entitlement — it lets another process attach to this one — and Apple's
+        // notarisation rules refuse a Developer-ID artifact carrying it. The
+        // reference signs its own build; we sign what a stranger downloads.
+        entitlements: (adhoc) => [
             'com.apple.security.cs.allow-jit',
             'com.apple.security.cs.allow-unsigned-executable-memory',
             'com.apple.security.cs.disable-executable-page-protection',
             'com.apple.security.cs.allow-dyld-environment-variables',
+            ...(adhoc ? ['com.apple.security.cs.disable-library-validation'] : []),
         ],
         // The `.app` is a bundle, and a bundle's signature is the seal over its
         // whole tree — the images alone leave `codesign --verify` with nothing to
@@ -156,9 +179,10 @@ export const SIGNERS = {
         sealsBundle: true,
         sealAddPrefix: (bundleRoot) => `${bundleRoot}/Contents/_CodeSignature/`,
         configKey: 'gjsify.ship.sign.darwin.identity',
-        gap: 'the images are signed and the bundle is sealed; UNVERIFIED end to end — no macOS host in this ' +
-            'repository has run a `--sign` over a real `.app`, and ADR 0024 § A16 still leaves library ' +
-            'validation unmeasured',
+        gap: 'the images are signed and the bundle is sealed, and the seal survives both the `.zip` and the ' +
+            '`.dmg` round trip; § A16 stands measured in ONE direction only — library validation refuses an ' +
+            'ad-hoc-signed dylib, so the ad-hoc identity grants `disable-library-validation` while a named ' +
+            'one does not, and no run in this repository has ever held the named one',
     },
     win32: {
         layoutOs: 'win32',
@@ -180,8 +204,10 @@ export const SIGNERS = {
         // Windows has no equivalent concept. An Authenticode signature carries no
         // capability claims — what a hardened runtime and an entitlement do on
         // macOS is done on Windows by the manifest and by AppContainer, neither of
-        // which this signer touches.
-        entitlements: [],
+        // which this signer touches. `() => []` rather than `[]` because the field is
+        // a function of the identity (see the darwin row), and this one ignores the
+        // argument instead of reading `adhoc` out of it.
+        entitlements: () => [],
         // A Windows program directory is a DIRECTORY and nothing more: there is no
         // manifest to seal and no per-directory signature format. `signtool` signs
         // images, one at a time, which is what the loop above already does.
@@ -303,9 +329,10 @@ export async function signPayload(input) {
     writePayload(workDir, payload, '');
     const adhoc = input.identity === ADHOC_IDENTITY;
     let entitlements;
-    if (signer.entitlements.length > 0) {
+    const granted = signer.entitlements(adhoc);
+    if (granted.length > 0) {
         mkdirSync(dirname(input.entitlementsPath), { recursive: true });
-        writeFileSync(input.entitlementsPath, renderEntitlements(signer.entitlements));
+        writeFileSync(input.entitlementsPath, renderEntitlements(granted));
         entitlements = input.entitlementsPath;
     }
     const run = async (file, what) => {

package/lib/utils/ship/stage-manifest.d.ts

@@ -102,6 +102,18 @@ export interface StageManifest {
     mtime: number;
     /** GI namespaces the bundle imports, `Ns-Version` where the specifier pins one. */
     namespaces: string[];
+    /**
+     * The subset of {@link namespaces} the BUNDLE marks optional (ADR 0087).
+     *
+     * OPTIONAL on read, deliberately, and that is the {STAGE_SCHEMA_VERSION} header's
+     * "a field an older reader would simply ignore" case: a stage written before the
+     * split has no such key, and answering "nothing is optional" makes every
+     * namespace a `Depends:` again — today's behaviour, and the SAFE direction. A
+     * newer reader packing an OLDER stage therefore over-declares instead of dropping
+     * a requirement the artifact cannot run without, which is the one error here that
+     * ships a package that dies at first launch.
+     */
+    optionalNamespaces?: string[];
     settings: PackSettings;
     staged: StageFileRecord[];
     overlay: Partial<Record<FormatId, StageOverlayFile[]>>;
@@ -113,6 +125,8 @@ export interface StageManifestInput {
     formats: readonly FormatDescriptor[];
     mtime: number;
     namespaces: readonly string[];
+    /** The optional subset of {@link namespaces} — see {@link StageManifest}. */
+    optionalNamespaces?: readonly string[];
     staged: readonly StagedFile[];
     /** Per-format overlay, as `planOverlay` produced it. */
     overlay: ReadonlyMap<FormatId, readonly StagedFile[]>;

package/lib/utils/ship/stage-manifest.js

@@ -187,6 +187,7 @@ export function writeStageManifest(input) {
         formats: input.formats.map((format) => format.id),
         mtime: input.mtime,
         namespaces: [...input.namespaces],
+        optionalNamespaces: [...(input.optionalNamespaces ?? [])],
         settings: toPackSettings(input.settings),
         staged: input.staged.map((file) => ({
             path: file.path,
@@ -276,6 +277,12 @@ export function readStageManifest(stageDir) {
         }),
         mtime: expectInteger(data.mtime, at('mtime')),
         namespaces: expectArray(data.namespaces, at('namespaces')).map((entry, index) => expectString(entry, at(`namespaces[${index}]`))),
+        // Absent is the empty set, not an error — see the field's doc comment.
+        ...(data.optionalNamespaces === undefined
+            ? {}
+            : {
+                optionalNamespaces: expectArray(data.optionalNamespaces, at('optionalNamespaces')).map((entry, index) => expectString(entry, at(`optionalNamespaces[${index}]`))),
+            }),
         settings: readPackSettings(record(data.settings, at('settings')), at('settings')),
         staged: expectArray(data.staged, at('staged')).map((entry, index) => {
             const file = record(entry, at(`staged[${index}]`));

package/lib/utils/webext/targets.d.ts

@@ -1,4 +1,4 @@
-export type WebextBrowser = 'chrome' | 'edge' | 'firefox' | 'safari';
+export type WebextBrowser = 'chrome' | 'edge' | 'firefox' | 'opera' | 'safari';
 export interface WebextTarget {
     /** As spelled in `gjsify.webext.targets` and the output directory name. */
     readonly id: string;

package/lib/utils/webext/targets.js

@@ -4,14 +4,22 @@
 // `@gjsify/manifest-conformance` (plain `.mjs`, no import from here), so a
 // target added on one side and not the other is refused by the rule before a
 // build ever sees it.
-export const WEBEXT_BROWSERS = ['chrome', 'edge', 'firefox', 'safari'];
+export const WEBEXT_BROWSERS = ['chrome', 'edge', 'firefox', 'opera', 'safari'];
 /** What a project gets when it declares no `targets`. */
 export const DEFAULT_WEBEXT_TARGETS = ['chrome-mv3', 'firefox-mv3'];
 /**
- * Chromium-based browsers no longer load Manifest V2 at all, so a `chrome-mv2`
- * folder would build, zip, and then be rejected by the browser and the store.
+ * Why a browser takes no Manifest V2 folder, absent where it still does. Chrome
+ * and Edge removed MV2 in the browser, so the folder would build, zip, and then
+ * be refused on load. Opera still LOADS an MV2 extension but its store is
+ * MV3-only (Opera, 2025-09), so the folder is refused a step later instead. The
+ * outcome is the same either way, which is why the sentence is per browser and
+ * not one claim the three do not all support.
  */
-const MV2_REMOVED = new Set(['chrome', 'edge']);
+const MV2_UNSUPPORTED = new Map([
+    ['chrome', 'chrome has removed Manifest V2'],
+    ['edge', 'edge has removed Manifest V2'],
+    ['opera', "opera's extension store accepts Manifest V3 only"],
+]);
 export function parseWebextTarget(id) {
     const match = /^([a-z]+)-mv([23])$/.exec(id);
     const browser = match?.[1];
@@ -20,9 +28,9 @@ export function parseWebextTarget(id) {
             `${WEBEXT_BROWSERS.join(', ')} (e.g. chrome-mv3, firefox-mv2).`);
     }
     const manifestVersion = match[2] === '2' ? 2 : 3;
-    if (manifestVersion === 2 && MV2_REMOVED.has(browser)) {
-        throw new Error(`gjsify webext: target "${id}" does not exist any more: ${browser} has removed Manifest V2. ` +
-            `Use ${browser}-mv3.`);
+    const why = manifestVersion === 2 ? MV2_UNSUPPORTED.get(browser) : undefined;
+    if (why !== undefined) {
+        throw new Error(`gjsify webext: target "${id}" does not exist any more: ${why}. Use ${browser}-mv3.`);
     }
     return { id, browser, manifestVersion };
 }
@@ -30,7 +38,11 @@ export function parseWebextTarget(id) {
 export function webExtRunTarget(target) {
     if (target.browser === 'firefox')
         return 'firefox-desktop';
-    if (target.browser === 'chrome' || target.browser === 'edge')
+    // By ENGINE, not by brand: the chromium driver's only browser-specific input is the
+    // binary, and `--browser-binary` already carries it — the claim branded Chrome and
+    // Edge already make. Refusing opera here would be a claim about the operator's
+    // binary, which is not what this switch is about.
+    if (target.browser === 'chrome' || target.browser === 'edge' || target.browser === 'opera')
         return 'chromium';
     return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.53.0",
+    "version": "0.54.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,21 +142,22 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.53.0",
-        "@gjsify/create-app": "^0.53.0",
-        "@gjsify/node-globals": "^0.53.0",
-        "@gjsify/node-polyfills": "^0.53.0",
-        "@gjsify/npm-registry": "^0.53.0",
-        "@gjsify/resolve-npm": "^0.53.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.53.0",
-        "@gjsify/vite-plugin-blueprint": "^0.53.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.53.0",
-        "@gjsify/semver": "^0.53.0",
-        "@gjsify/tar": "^0.53.0",
-        "@gjsify/tsc": "^0.53.0",
-        "@gjsify/utils": "^0.53.0",
-        "@gjsify/web-polyfills": "^0.53.0",
-        "@gjsify/workspace": "^0.53.0",
+        "@gjsify/blueprint": "^0.54.0",
+        "@gjsify/buffer": "^0.54.0",
+        "@gjsify/create-app": "^0.54.0",
+        "@gjsify/node-globals": "^0.54.0",
+        "@gjsify/node-polyfills": "^0.54.0",
+        "@gjsify/npm-registry": "^0.54.0",
+        "@gjsify/resolve-npm": "^0.54.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.54.0",
+        "@gjsify/vite-plugin-blueprint": "^0.54.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.54.0",
+        "@gjsify/semver": "^0.54.0",
+        "@gjsify/tar": "^0.54.0",
+        "@gjsify/tsc": "^0.54.0",
+        "@gjsify/utils": "^0.54.0",
+        "@gjsify/web-polyfills": "^0.54.0",
+        "@gjsify/workspace": "^0.54.0",
         "acorn": "^8.17.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
@@ -165,13 +166,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.53.0",
+        "@gjsify/unit": "^0.54.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.53.0",
-        "@gjsify/rolldown-native": "^0.53.0"
+        "@gjsify/oxfmt-native": "^0.54.0",
+        "@gjsify/rolldown-native": "^0.54.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {