@gjsify/cli 0.52.0 → 0.54.0

package/lib/utils/ship/layout.js

@@ -7,7 +7,8 @@
 // is the first layout that is NOT a prefix substitution: the launcher, the bundle,
 // the shared libraries and the data tree each move somewhere different, and on
 // macOS the native files leave the bundle directory altogether for
-// `Contents/Frameworks`.
+// `Contents/Resources/native` — a path Apple's own layout does not have, for the
+// measured reason {@link layoutForOs}'s darwin row carries.
 //
 // So the layout is a MAP from the prefix-relative plan to a stage-relative path,
 // and `planStage` keeps producing the prefix-relative plan for all three. That
@@ -168,12 +169,34 @@ export const LAYOUTS = {
         // everything that is not, and `Contents/Frameworks` the dylibs — which is
         // the split that makes this more than a prefix: the `gi/` directory that
         // sits INSIDE `lib/<name>/` on Linux leaves the bundle directory entirely.
+        //
+        // …AND THE NATIVE DIRECTORY IS NOT APPLE'S, because `Contents/Frameworks`
+        // is RESERVED FOR NESTED CODE and one directory of it is loadable code
+        // that cannot be there. Measured on darwin-arm64 / macOS 27 with the
+        // published `@gjsify/gtk-runtime-darwin-arm64` staged by M2b: `codesign`
+        // refuses the BUNDLE SEAL with *"bundle format unrecognized, invalid, or
+        // unsuitable / In subcomponent: …/gtk/lib/gstreamer-1.0"*, so
+        // `gjsify ship darwin --sign` cannot sign a real GTK application at all —
+        // and it does so at exit 1 with the payload half-signed. The trigger is not
+        // gstreamer: it is any directory under `Contents/Frameworks` whose last
+        // dot-separated component parses as a version, because `codesign` reads
+        // `foo-1.0`, `foo1.0` and `Versions/1.0` as a VERSIONED NESTED BUNDLE
+        // (`<name>-<version>` is a framework's shape) and then finds no
+        // `Contents/Info.plist` inside. The relocated closure carries three:
+        // `girepository-1.0`, `gdk-pixbuf-2.0/2.10.0` and `lib/gstreamer-1.0`.
+        //
+        // The same three under `Contents/Resources` seal and verify at exit 0, which
+        // is the whole measurement. So `native` is the ONE seam that moves: the
+        // relocated closure, the addon, the app's own `gi/` dylibs and both launchers'
+        // `GI_TYPELIB_PATH`/`GJSIFY_GI_LIBRARY_PATH` all read it, so the tree and
+        // every path that names it move together. Library validation is unaffected —
+        // it follows the SIGNATURE (§ `signing.ts`'s darwin row), not the directory.
         dirs: (identity) => {
             const app = appBundleDir(identity);
             return {
                 launcher: `${app}/Contents/MacOS`,
                 bundle: `${app}/Contents/Resources/lib`,
-                native: `${app}/Contents/Frameworks`,
+                native: `${app}/Contents/Resources/native`,
                 data: `${app}/Contents/Resources/share`,
                 other: `${app}/Contents/Resources`,
             };

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

@@ -1,4 +1,5 @@
 import type { ChildProcess } from 'node:child_process';
+import { type Win32Invocation } from './win32-command.js';
 /**
  * What the calling command does once this spawn settles.
  *
@@ -82,6 +83,18 @@ export interface SpawnCompletion {
     /** The child's stderr — only under `stdio: 'capture'`, `''` when it wrote none. */
     stderr?: string;
 }
+/**
+ * Rewrite a bare command for Windows (see `utils/win32-command.ts`). A no-op on
+ * every other platform, and on win32 for anything already carrying a path or
+ * extension. `env` is the CHILD's, because its `PATH` is what must be searched.
+ *
+ * Exported for the synchronous PROBES that cannot go through
+ * {@link spawnToCompletion} (`<tool> --version` in `check-system-deps.ts`, the
+ * runtime probe in `runtimes.ts`): a raw `execFileSync('deno', …)` is ENOENT on
+ * Windows when deno came from `npm i -g deno`, which installs a `.cmd` shim, so
+ * `--runtime deno` was refused as "not installed" on a host where `deno` runs.
+ */
+export declare function toSpawnable(cmd: string, args: readonly string[], env?: NodeJS.ProcessEnv): Win32Invocation;
 /**
  * Run `cmd args…` to completion and resolve with its exit code and signal.
  *

package/lib/utils/spawn.js

@@ -60,7 +60,7 @@
 //
 // ## What is spawned still matters — the Windows rewrite
 //
-// This helper also carries the Windows command rewrite (`forWin32`), which is a
+// This helper also carries the Windows command rewrite (`toSpawnable`), which is a
 // second reason to come through it, and the one that applies OUTSIDE the CLI too:
 //
 //   • a real executable (`git`, `gh`, `node`, `gjs`, `flatpak`, `process.execPath`)
@@ -93,10 +93,15 @@ function resolveEnv(opts) {
 /**
  * Rewrite a bare command for Windows (see `utils/win32-command.ts`). A no-op on
  * every other platform, and on win32 for anything already carrying a path or
- * extension. Applied to BOTH paths below so the blocking and streaming branches
- * agree; `env` is the CHILD's, because its `PATH` is what must be searched.
+ * extension. `env` is the CHILD's, because its `PATH` is what must be searched.
+ *
+ * Exported for the synchronous PROBES that cannot go through
+ * {@link spawnToCompletion} (`<tool> --version` in `check-system-deps.ts`, the
+ * runtime probe in `runtimes.ts`): a raw `execFileSync('deno', …)` is ENOENT on
+ * Windows when deno came from `npm i -g deno`, which installs a `.cmd` shim, so
+ * `--runtime deno` was refused as "not installed" on a host where `deno` runs.
  */
-function forWin32(cmd, args, env) {
+export function toSpawnable(cmd, args, env) {
     const rewritten = resolveWin32Command(cmd, args, {
         platform: process.platform,
         env: env ?? process.env,
@@ -132,7 +137,7 @@ export function spawnToCompletion(cmd, args, opts) {
     // must not touch it — see `SpawnToCompletionOptions.shell`.
     const invocation = opts.shell
         ? { cmd, args: [...args], windowsVerbatimArguments: false }
-        : forWin32(cmd, args, env);
+        : toSpawnable(cmd, args, env);
     if (mustBlock(opts)) {
         // `'inherit'` is NOT forwarded through `@gjsify/child_process`'s GJS
         // spawnSync path (it drives a private main context via

package/lib/utils/watch-loop.d.ts

@@ -23,9 +23,23 @@ export declare function spawnSupervised(cmd: string, cmdArgs: string[], env?: No
  * "this project").
  */
 export declare function spawnBundleSupervised(runtime: ExampleRuntime, bundlePath: string, cwd: string, subject: string): Promise<ChildProcess>;
+/** One path the loop watches — a directory recursively, or the directory's own entries only. */
+export interface WatchTarget {
+    path: string;
+    recursive: boolean;
+}
 export interface WatchLoopOptions {
-    /** Directory watched recursively. */
+    /** Directory watched recursively — the label and the default when `watch` is not given. */
     dir: string;
+    /**
+     * Several paths instead of `dir` alone. `gjsify webext dev` needs it: its
+     * sources sit in sibling top-level directories next to `node_modules`, and a
+     * recursive watch on the project root costs one `Gio.FileMonitor` per
+     * directory under GJS, `node_modules` included.
+     */
+    watch?: readonly WatchTarget[];
+    /** An absolute changed path the loop must not rebuild for (build output, caches). */
+    ignore?: (changed: string) => boolean;
     /** How `dir` is spelled in the loop's own log lines. Defaults to `dir`. */
     dirLabel?: string;
     /** Prefix for the loop's log lines: `[<label>] …`. */

package/lib/utils/watch-loop.js

@@ -125,7 +125,7 @@ export function isSelfWrite(dir, output, filename) {
  * fix, and a dev loop that dies on a syntax error is a dev loop nobody uses.
  */
 export async function runWatchLoop(opts) {
-    const { dir, label, prepare, build, spawnChild, output, debounceMs = 200 } = opts;
+    const { dir, label, prepare, build, spawnChild, output, ignore, debounceMs = 200 } = opts;
     // Say so BEFORE the first build: `gjsify run`'s in-process dispatch acts on
     // this the moment the handler resolves, and a first build that throws still
     // leaves the loop watching.
@@ -164,13 +164,16 @@ export async function runWatchLoop(opts) {
     };
     await rebuild();
     let debounce = null;
-    const watcher = watch(dir, { recursive: true }, (_event, filename) => {
-        if (isSelfWrite(dir, output, typeof filename === 'string' ? filename : null))
+    const watchers = (opts.watch ?? [{ path: dir, recursive: true }]).map((target) => watch(target.path, { recursive: target.recursive }, (_event, filename) => {
+        const name = typeof filename === 'string' ? filename : null;
+        if (isSelfWrite(target.path, output, name))
+            return;
+        if (ignore && name !== null && ignore(resolve(target.path, name)))
             return;
         if (debounce)
             clearTimeout(debounce);
         debounce = setTimeout(() => void rebuild(), debounceMs);
-    });
+    }));
     // Under GJS nothing else keeps us here. An `fs.watch` handle is a Gio file
     // monitor, not a Node handle count, and the supervised spawn's own
     // `ensureMainLoop()` declines to arm anything: it is reached from a
@@ -198,7 +201,8 @@ export async function runWatchLoop(opts) {
         if (debounce)
             clearTimeout(debounce);
         child?.kill();
-        watcher.close();
+        for (const watcher of watchers)
+            watcher.close();
         process.exit(0);
     };
     process.on('SIGINT', shutdown);

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

@@ -0,0 +1,42 @@
+import { type ZipEntry } from '../ship/zip.js';
+import type { RasterizeInput } from '../ship/icons.js';
+import type { ResolvedWebext } from './config.js';
+import type { WebextTarget } from './targets.js';
+export interface BundleRequest {
+    entry: string;
+    outfile: string;
+    format: 'esm' | 'iife';
+    define: Record<string, string>;
+    minify: boolean;
+}
+export interface WebextBuildOptions {
+    config: ResolvedWebext;
+    targets: readonly WebextTarget[];
+    /** Absolute; the target folders are `<outDir>/<target>`. */
+    outDir: string;
+    mode: 'production' | 'development';
+    /** Effective defines: the config's, then the command line's. */
+    define: Record<string, string>;
+    /**
+     * Overwrite files instead of starting from an empty folder. `dev` needs it:
+     * deleting the folder `web-ext run` watches makes Firefox unload the
+     * extension mid-rebuild (measured in beifahrer).
+     */
+    inPlace: boolean;
+    zip: boolean;
+    /** Bundle one entry. Injectable so the assembly is testable without a bundler. */
+    bundle: (request: BundleRequest) => Promise<void>;
+    rasterize?: (input: RasterizeInput) => Promise<Map<number, Uint8Array>>;
+    log?: (line: string) => void;
+}
+export interface WebextBuildResult {
+    /** target id → absolute folder. */
+    folders: Map<string, string>;
+    /** target id → absolute zip path (only with `zip`). */
+    zips: Map<string, string>;
+}
+/** One `SOURCE_DATE_EPOCH`-aware timestamp for every entry, so a rebuild zips to the same bytes. */
+export declare function zipTimestamp(env?: NodeJS.ProcessEnv): number;
+/** Every file under `dir`, as archive entries relative to it. */
+export declare function zipEntriesOf(dir: string): ZipEntry[];
+export declare function buildWebext(opts: WebextBuildOptions): Promise<WebextBuildResult>;