@gjsify/cli 0.51.1 → 0.53.0

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

@@ -2,6 +2,8 @@ import type { LayoutMetadataInput } from './layout.js';
 /** Where the two files live inside a bundle. Apple's names, not ours. */
 export declare const BUNDLE_INFO_PLIST = "Contents/Info.plist";
 export declare const BUNDLE_PKGINFO = "Contents/PkgInfo";
+/** Where `CFBundleIconFile` is resolved: the bundle's resources directory, and nowhere else. */
+export declare const BUNDLE_RESOURCES = "Contents/Resources";
 /**
  * Render `Contents/Info.plist`.
  *
@@ -30,19 +32,12 @@ export declare const BUNDLE_PKGINFO = "Contents/PkgInfo";
  * release). Emitting `version` twice would throw the distinction away on the one
  * OS that has a field for it.
  *
- * KEYS DELIBERATELY ABSENT are listed in this module's header. `CFBundleIconFile`
- * is the one a reader will reach for first, and it is absent for a reason that
- * outlives the key: M2a ships NO icon. `png2icns`, `icnsutil` and `iconutil` are
- * all absent from this workstation and from the CI image, so an `.icns` written
- * here could only be read back by a reader written here — `selfReading: true`,
- * which `flatpak.spec.ts` reds. The unblocker is an independent Linux ICNS reader
- * entering the CI image; until one does, the hicolor PNG/SVG the payload already
- * carries stays the only icon, unread on macOS.
+ * KEYS DELIBERATELY ABSENT are listed in this module's header.
  *
  * A TWELFTH KEY, `ATSApplicationFontsPath`, is emitted when the bundle carries
  * faces, and it is the first one here NOT cited to `refs/` — so the exception is
  * stated rather than left to be noticed (ADR 0038). The rule this module opens
- * with exists against DECORATION: the five absent keys are cosmetic, nothing a
+ * with exists against DECORATION: the four absent keys are cosmetic, nothing a
  * reader here can open contains them, and emitting one would be a guess with no
  * observable behind it. This key is a MECHANISM, and its citation is Apple's own
  * *Information Property List Key Reference*, which states the scope in the terms
@@ -51,6 +46,21 @@ export declare const BUNDLE_PKGINFO = "Contents/PkgInfo";
  * app and not for the system as a whole."* The value is a path relative to
  * `Contents/Resources`.
  *
+ * A THIRTEENTH, `CFBundleIconFile`, is the same shape of exception and closes the
+ * gap the previous version of this comment recorded: M2a shipped NO icon because
+ * nothing on Linux could read an `.icns` back. Two things changed. `icns.ts` now
+ * writes the container from rasters `icons.ts` renders through librsvg, and the
+ * readers were measured rather than assumed: CPython `struct` walks the element
+ * table in `verify-app-plist.py` (in CI), Pillow 12.3 opens all ten elements (on
+ * the workstation), `icns2png` reads three of ten and is NOT relied on, and
+ * `iconutil` on macOS is the reader with authority — a VM run, recorded with the
+ * change that lands this key. The citation is the same key reference: *"The name
+ * of the bundle's icon file, located in the Resources folder"*, and the
+ * measurement that motivates it is the released 0.8.0 bundle of one app on macOS
+ * 15.7 with no key, no `.icns` and the generic Finder icon. `CFBundleIconName` is
+ * NOT emitted: it names an asset-catalog entry (`Assets.car`), which this tree
+ * does not produce, and a name with no catalog is a dangling reference.
+ *
  * It is also the only route there is. Pango on macOS is CoreText-backed, GTK is
  * not built against fontconfig on that platform, and
  * `pango_font_map_add_font_file()` answers `G_IO_ERROR_NOT_SUPPORTED` on the
@@ -63,7 +73,7 @@ export declare const BUNDLE_PKGINFO = "Contents/PkgInfo";
  * Pango's CoreText map then holds the family, is unverified here — which is what
  * `Layout.fontGap` says out loud rather than letting a green stage imply.
  */
-export declare function renderInfoPlist(input: LayoutMetadataInput, fontsPath?: string): string;
+export declare function renderInfoPlist(input: LayoutMetadataInput, fontsPath?: string, iconFile?: string): string;
 /**
  * Render `Contents/PkgInfo`: the package type and the signature, eight bytes, no
  * newline.

package/lib/utils/ship/plist.js

@@ -14,8 +14,10 @@
 // (`.github/ship-oracle/verify-modes.py`), and it parses the XML form.
 //
 // EVERY KEY BELOW IS CITED to a file in `refs/` that a real macOS toolchain
-// produced or consumes. Keys that are merely plausible — `CFBundleIconFile`,
-// `LSMinimumSystemVersion`, `NSHighResolutionCapable`, `LSApplicationCategoryType`,
+// produced or consumes, or — for the two MECHANISM keys, `ATSApplicationFontsPath`
+// and `CFBundleIconFile` — to Apple's own key reference plus a measurement on a
+// Mac. Keys that are merely plausible — `LSMinimumSystemVersion`,
+// `NSHighResolutionCapable`, `LSApplicationCategoryType`,
 // `NSHumanReadableCopyright` — are not emitted, because nothing a reader here can
 // open contains them.
 //
@@ -32,6 +34,8 @@
 /** Where the two files live inside a bundle. Apple's names, not ours. */
 export const BUNDLE_INFO_PLIST = 'Contents/Info.plist';
 export const BUNDLE_PKGINFO = 'Contents/PkgInfo';
+/** Where `CFBundleIconFile` is resolved: the bundle's resources directory, and nowhere else. */
+export const BUNDLE_RESOURCES = 'Contents/Resources';
 /**
  * The four-character bundle type of an application, and the signature that says
  * "none".
@@ -139,19 +143,12 @@ function arrayEntry(key, values) {
  * release). Emitting `version` twice would throw the distinction away on the one
  * OS that has a field for it.
  *
- * KEYS DELIBERATELY ABSENT are listed in this module's header. `CFBundleIconFile`
- * is the one a reader will reach for first, and it is absent for a reason that
- * outlives the key: M2a ships NO icon. `png2icns`, `icnsutil` and `iconutil` are
- * all absent from this workstation and from the CI image, so an `.icns` written
- * here could only be read back by a reader written here — `selfReading: true`,
- * which `flatpak.spec.ts` reds. The unblocker is an independent Linux ICNS reader
- * entering the CI image; until one does, the hicolor PNG/SVG the payload already
- * carries stays the only icon, unread on macOS.
+ * KEYS DELIBERATELY ABSENT are listed in this module's header.
  *
  * A TWELFTH KEY, `ATSApplicationFontsPath`, is emitted when the bundle carries
  * faces, and it is the first one here NOT cited to `refs/` — so the exception is
  * stated rather than left to be noticed (ADR 0038). The rule this module opens
- * with exists against DECORATION: the five absent keys are cosmetic, nothing a
+ * with exists against DECORATION: the four absent keys are cosmetic, nothing a
  * reader here can open contains them, and emitting one would be a guess with no
  * observable behind it. This key is a MECHANISM, and its citation is Apple's own
  * *Information Property List Key Reference*, which states the scope in the terms
@@ -160,6 +157,21 @@ function arrayEntry(key, values) {
  * app and not for the system as a whole."* The value is a path relative to
  * `Contents/Resources`.
  *
+ * A THIRTEENTH, `CFBundleIconFile`, is the same shape of exception and closes the
+ * gap the previous version of this comment recorded: M2a shipped NO icon because
+ * nothing on Linux could read an `.icns` back. Two things changed. `icns.ts` now
+ * writes the container from rasters `icons.ts` renders through librsvg, and the
+ * readers were measured rather than assumed: CPython `struct` walks the element
+ * table in `verify-app-plist.py` (in CI), Pillow 12.3 opens all ten elements (on
+ * the workstation), `icns2png` reads three of ten and is NOT relied on, and
+ * `iconutil` on macOS is the reader with authority — a VM run, recorded with the
+ * change that lands this key. The citation is the same key reference: *"The name
+ * of the bundle's icon file, located in the Resources folder"*, and the
+ * measurement that motivates it is the released 0.8.0 bundle of one app on macOS
+ * 15.7 with no key, no `.icns` and the generic Finder icon. `CFBundleIconName` is
+ * NOT emitted: it names an asset-catalog entry (`Assets.car`), which this tree
+ * does not produce, and a name with no catalog is a dangling reference.
+ *
  * It is also the only route there is. Pango on macOS is CoreText-backed, GTK is
  * not built against fontconfig on that platform, and
  * `pango_font_map_add_font_file()` answers `G_IO_ERROR_NOT_SUPPORTED` on the
@@ -172,7 +184,7 @@ function arrayEntry(key, values) {
  * Pango's CoreText map then holds the family, is unverified here — which is what
  * `Layout.fontGap` says out loud rather than letting a green stage imply.
  */
-export function renderInfoPlist(input, fontsPath) {
+export function renderInfoPlist(input, fontsPath, iconFile) {
     const name = assertPlistText(input.name, 'CFBundleName', 'gjsify.ship.name');
     const executable = assertPlistText(input.binaryName, 'CFBundleExecutable', 'gjsify.ship.binaryName');
     const appId = assertPlistText(input.appId, 'CFBundleIdentifier', 'gjsify.ship.appId');
@@ -195,6 +207,11 @@ export function renderInfoPlist(input, fontsPath) {
         stringEntry('CFBundleDevelopmentRegion', 'en'),
         stringEntry('CFBundleDisplayName', name),
         stringEntry('CFBundleExecutable', executable),
+        // Between Executable and Identifier is where the alphabet puts it. Absent,
+        // not empty, for a bundle that carries no icon (`kind: 'cli'`): an empty
+        // name is a file lookup that fails, which macOS answers with the same
+        // generic icon and no diagnostic.
+        ...(iconFile === undefined ? [] : [stringEntry('CFBundleIconFile', iconFile)]),
         stringEntry('CFBundleIdentifier', appId),
         stringEntry('CFBundleInfoDictionaryVersion', '6.0'),
         stringEntry('CFBundleName', name),

package/lib/utils/ship/settings.js

@@ -175,8 +175,9 @@ export function resolveShipSettings(input) {
     const description = descriptionParagraphs(metadata.description) ?? [summary];
     const sections = sectionsFor(metadata.categories);
     if (kind === 'app' && discovered.iconFiles.length === 0) {
-        warnings.push(`gjsify ship: no icon found — the installed app will show a placeholder in menus and app stores. ` +
-            'Point `gjsify.ship.icon` at an SVG (or a directory of sized PNGs).');
+        warnings.push(`gjsify ship: no icon found — the installed app will show a placeholder in menus and app stores ` +
+            'on Linux, and the darwin and windows layouts refuse to stage without one. Point ' +
+            '`gjsify.ship.icon` at an SVG (or a directory of sized PNGs).');
     }
     // Resolved here rather than in the packer, because the packer may run on a
     // host with no `package.json` at all (ADR 0024 § A2) — and because the

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>;

package/lib/utils/webext/build.js

@@ -0,0 +1,120 @@
+// `gjsify webext build|zip|dev` — assemble one folder per target (ADR 0077 § 4).
+//
+// Every bundle is built ONCE into a staging directory and copied into each
+// target; only the manifest and the icon files differ between targets. That is
+// beifahrer's measured arrangement, and it is also what makes a target cheap:
+// adding `edge-mv3` to a project costs a copy, not a rebuild.
+import { cpSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { buildZip } from '../ship/zip.js';
+import { renderWebextIcons, webextIconPaths, writeWebextIcons } from './icons.js';
+import { checkManifest, composeManifest, loadManifestTemplate } from './manifest.js';
+import { planPage } from './pages.js';
+/** The fixed ZIP timestamp when SOURCE_DATE_EPOCH is unset: 1980-01-01, the format's floor. */
+const ZIP_EPOCH_FLOOR = 315532800;
+/** One `SOURCE_DATE_EPOCH`-aware timestamp for every entry, so a rebuild zips to the same bytes. */
+export function zipTimestamp(env = process.env) {
+    const epoch = Number(env.SOURCE_DATE_EPOCH);
+    return Number.isFinite(epoch) && epoch >= ZIP_EPOCH_FLOOR ? epoch : ZIP_EPOCH_FLOOR;
+}
+/** Every file under `dir`, as archive entries relative to it. */
+export function zipEntriesOf(dir) {
+    const out = [];
+    const walk = (current) => {
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else
+                out.push({ path: relative(dir, full).split(/[\\/]/).join('/'), mode: 0o644, data: readFileSync(full) });
+        }
+    };
+    walk(dir);
+    return out;
+}
+export async function buildWebext(opts) {
+    const { config, targets, outDir, define } = opts;
+    const log = opts.log ?? ((line) => console.log(line));
+    const minify = opts.mode === 'production' && config.minify;
+    const stage = join(outDir, '.stage');
+    rmSync(stage, { recursive: true, force: true });
+    mkdirSync(stage, { recursive: true });
+    try {
+        for (const [name, entry] of config.scripts) {
+            await opts.bundle({ entry, outfile: join(stage, `${name}.js`), format: 'iife', define, minify });
+        }
+        const written = new Map();
+        for (const [name, htmlPath] of config.pages) {
+            const plan = planPage(name, htmlPath, readFileSync(htmlPath, 'utf8'));
+            for (const script of plan.scripts) {
+                await opts.bundle({
+                    entry: script.entry,
+                    outfile: join(stage, script.output),
+                    format: script.format,
+                    define,
+                    minify,
+                });
+            }
+            for (const sheet of plan.stylesheets) {
+                const previous = written.get(sheet.output);
+                if (previous !== undefined && previous !== sheet.source) {
+                    throw new Error(`gjsify webext: pages link ${previous} and ${sheet.source}, which would both be written as ` +
+                        `${sheet.output}. Rename one.`);
+                }
+                written.set(sheet.output, sheet.source);
+                cpSync(sheet.source, join(stage, sheet.output));
+            }
+            writeFileSync(join(stage, `${name}.html`), plan.html);
+        }
+        const icons = config.icons;
+        const rendered = icons ? await renderWebextIcons(icons, targets, opts.rasterize) : null;
+        const template = await loadManifestTemplate(config.manifest);
+        const result = { folders: new Map(), zips: new Map() };
+        for (const target of targets) {
+            const dir = join(outDir, target.id);
+            if (!opts.inPlace)
+                rmSync(dir, { recursive: true, force: true });
+            mkdirSync(dir, { recursive: true });
+            // Public files first, so a built file of the same name wins.
+            if (config.publicDir)
+                cpSync(config.publicDir, dir, { recursive: true });
+            if (config.localesDir)
+                cpSync(config.localesDir, join(dir, '_locales'), { recursive: true });
+            cpSync(stage, dir, { recursive: true });
+            if (icons && rendered)
+                writeWebextIcons(rendered, icons, target, dir);
+            const ctx = {
+                target: target.id,
+                browser: target.browser,
+                manifestVersion: target.manifestVersion,
+                mode: opts.mode,
+                version: config.version,
+                define,
+                icons: (name) => {
+                    if (!icons) {
+                        throw new Error(`gjsify webext: the manifest asks for icon "${name}" and \`gjsify.webext.icons\` is not declared.`);
+                    }
+                    return webextIconPaths(icons, name, target);
+                },
+            };
+            const manifest = await composeManifest(template, ctx);
+            writeFileSync(join(dir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+            const problems = checkManifest(manifest, target, dir);
+            if (problems.length > 0) {
+                throw new Error(`gjsify webext: ${target.id} would not load:\n  - ${problems.join('\n  - ')}`);
+            }
+            result.folders.set(target.id, dir);
+            log(`built ${relative(process.cwd(), dir) || dir}`);
+            if (opts.zip) {
+                const file = join(outDir, `${config.name}-${config.version}-${target.id}.zip`);
+                writeFileSync(file, buildZip(zipEntriesOf(dir), zipTimestamp()));
+                result.zips.set(target.id, file);
+                log(`zipped ${relative(process.cwd(), file) || file} (${Math.round(statSync(file).size / 1024)} KiB)`);
+            }
+        }
+        return result;
+    }
+    finally {
+        rmSync(stage, { recursive: true, force: true });
+    }
+}

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

@@ -0,0 +1,72 @@
+import { type WebextTarget } from './targets.js';
+/** A source SVG per icon name: one file, or one per size ceiling (`{ "default": …, "32": … }`). */
+export type WebextIconSource = string | Record<string, string>;
+export interface WebextIconsConfig {
+    sizes?: number[];
+    sources: Record<string, WebextIconSource>;
+    /** Targets that receive the SVG files themselves instead of rendered PNGs. */
+    svg?: string[];
+}
+/** The block as a project writes it. */
+export interface WebextConfig {
+    name?: string;
+    targets?: string[];
+    manifest?: string;
+    scripts?: Record<string, string>;
+    pages?: Record<string, string>;
+    icons?: WebextIconsConfig;
+    public?: string;
+    locales?: string;
+    outDir?: string;
+    define?: Record<string, string>;
+    watch?: string[];
+    minify?: boolean;
+}
+export interface ResolvedWebextIcons {
+    sizes: number[];
+    /** name → absolute SVG path per size. */
+    sources: Map<string, Map<number, string>>;
+    svgTargets: Set<string>;
+}
+/** The block after validation, with every path absolute. */
+export interface ResolvedWebext {
+    root: string;
+    name: string;
+    version: string;
+    targets: WebextTarget[];
+    manifest: string;
+    scripts: Map<string, string>;
+    pages: Map<string, string>;
+    icons: ResolvedWebextIcons | null;
+    publicDir: string | null;
+    localesDir: string | null;
+    outDir: string;
+    define: Record<string, string>;
+    watch: string[];
+    minify: boolean;
+}
+export declare const DEFAULT_ICON_SIZES: number[];
+interface PackageShape {
+    name?: string;
+    version?: string;
+    gjsify?: {
+        webext?: unknown;
+    };
+}
+/** The zip base name a package gets when it declares none: its npm name without the scope. */
+export declare function defaultArtifactName(packageName: string | undefined): string;
+/**
+ * Pick the SVG an icon uses at `size`: the smallest numeric ceiling that is
+ * `>= size`, else `default`. Returns undefined when neither covers the size.
+ */
+export declare function iconSourceForSize(source: WebextIconSource, size: number): string | undefined;
+/**
+ * Validate `gjsify.webext` and resolve it against the package root.
+ *
+ * `exists` is injectable so the specs can describe a project without writing
+ * one to disk.
+ */
+export declare function resolveWebextConfig(pkg: PackageShape, root: string, exists?: (path: string, kind: 'file' | 'dir') => boolean): ResolvedWebext;
+/** Narrow the configured targets to the ones a command was asked for. */
+export declare function selectTargets(config: ResolvedWebext, requested: readonly string[] | undefined): WebextTarget[];
+export {};