@gjsify/cli 0.52.0 → 0.54.0

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

package/lib/utils/webext/config.js

@@ -0,0 +1,234 @@
+// `package.json#gjsify.webext` — read, validated and resolved to absolute paths
+// in one place, so every subcommand (build, zip, dev) works from the same answer.
+//
+// Every problem is collected before throwing: a config with three mistakes
+// should cost one run to fix, not three.
+import { existsSync, statSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { DEFAULT_WEBEXT_TARGETS, parseWebextTarget } from './targets.js';
+export const DEFAULT_ICON_SIZES = [16, 32, 48, 128];
+const MANIFEST_CANDIDATES = ['manifest.ts', 'manifest.mts', 'manifest.js', 'manifest.mjs', 'manifest.json'];
+/** Output names become file names in every target (`<name>.js`, `<name>.html`). */
+const OUTPUT_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The zip base name a package gets when it declares none: its npm name without the scope. */
+export function defaultArtifactName(packageName) {
+    const bare = (packageName ?? 'extension').replace(/^@[^/]+\//, '');
+    return bare === '' ? 'extension' : bare;
+}
+/**
+ * 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 function iconSourceForSize(source, size) {
+    if (typeof source === 'string')
+        return source;
+    const ceilings = Object.keys(source)
+        .filter((key) => /^\d+$/.test(key))
+        .map(Number)
+        .sort((a, b) => a - b);
+    const ceiling = ceilings.find((value) => size <= value);
+    return ceiling === undefined ? source.default : source[String(ceiling)];
+}
+/**
+ * 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 function resolveWebextConfig(pkg, root, exists = defaultExists) {
+    const problems = [];
+    const raw = pkg.gjsify?.webext;
+    if (raw === undefined) {
+        throw new Error('gjsify webext: this package declares no `gjsify.webext` block in package.json. ' +
+            'Add one naming at least the manifest and one script or page — see `gjsify webext build --help`.');
+    }
+    if (!isRecord(raw))
+        throw new Error('gjsify webext: `gjsify.webext` must be an object.');
+    const block = raw;
+    const abs = (path) => (isAbsolute(path) ? path : resolve(root, path));
+    const need = (label, path, kind) => {
+        const full = abs(path);
+        if (!exists(full, kind))
+            problems.push(`${label} "${path}" is not a ${kind === 'dir' ? 'directory' : 'file'}.`);
+        return full;
+    };
+    const targets = [];
+    const targetIds = block.targets ?? [...DEFAULT_WEBEXT_TARGETS];
+    if (!Array.isArray(targetIds) || targetIds.length === 0) {
+        problems.push('`targets` must be a non-empty array of target names.');
+    }
+    else {
+        for (const id of targetIds) {
+            try {
+                if (targets.some((t) => t.id === id))
+                    problems.push(`target "${id}" is listed twice.`);
+                else
+                    targets.push(parseWebextTarget(String(id)));
+            }
+            catch (err) {
+                problems.push(err.message.replace(/^gjsify webext: /, ''));
+            }
+        }
+    }
+    let manifest = '';
+    if (block.manifest !== undefined) {
+        manifest = need('`manifest`', block.manifest, 'file');
+    }
+    else {
+        const found = MANIFEST_CANDIDATES.find((candidate) => exists(join(root, candidate), 'file'));
+        if (found === undefined) {
+            problems.push(`no \`manifest\` declared and none of ${MANIFEST_CANDIDATES.join(', ')} exists.`);
+        }
+        else {
+            manifest = join(root, found);
+        }
+    }
+    const outputs = new Map();
+    const claim = (output, by) => {
+        const previous = outputs.get(output);
+        if (previous !== undefined)
+            problems.push(`${by} and ${previous} both write ${output}.`);
+        else
+            outputs.set(output, by);
+    };
+    const readEntries = (key) => {
+        const out = new Map();
+        const value = block[key];
+        if (value === undefined)
+            return out;
+        if (!isRecord(value)) {
+            problems.push(`\`${key}\` must map an output name to a source file.`);
+            return out;
+        }
+        for (const [name, source] of Object.entries(value)) {
+            if (!OUTPUT_NAME_RE.test(name)) {
+                problems.push(`\`${key}.${name}\`: an output name is a plain file name (letters, digits, . _ -).`);
+                continue;
+            }
+            if (typeof source !== 'string') {
+                problems.push(`\`${key}.${name}\` must be a path.`);
+                continue;
+            }
+            out.set(name, need(`\`${key}.${name}\``, source, 'file'));
+            if (key === 'scripts')
+                claim(`${name}.js`, `\`scripts.${name}\``);
+            else
+                claim(`${name}.html`, `\`pages.${name}\``);
+        }
+        return out;
+    };
+    const scripts = readEntries('scripts');
+    const pages = readEntries('pages');
+    if (scripts.size === 0 && pages.size === 0) {
+        problems.push('declare at least one entry under `scripts` or `pages`; there is nothing to build.');
+    }
+    // A page's first script is written as `<page>.js`, so it competes with `scripts` for the name.
+    for (const name of pages.keys()) {
+        if (scripts.has(name))
+            problems.push(`\`scripts.${name}\` and the script of \`pages.${name}\` both write ${name}.js.`);
+    }
+    let icons = null;
+    if (block.icons !== undefined) {
+        if (!isRecord(block.icons) || !isRecord(block.icons.sources)) {
+            problems.push('`icons` must be an object with a `sources` map (icon name → SVG).');
+        }
+        else {
+            const sizes = block.icons.sizes ?? DEFAULT_ICON_SIZES;
+            if (!Array.isArray(sizes) || sizes.length === 0 || sizes.some((s) => !Number.isInteger(s) || s <= 0)) {
+                problems.push('`icons.sizes` must be a non-empty list of positive integers.');
+            }
+            const svgTargets = new Set(block.icons.svg ?? []);
+            for (const id of svgTargets) {
+                if (!targets.some((t) => t.id === id)) {
+                    problems.push(`\`icons.svg\` names "${id}", which is not one of this package's targets.`);
+                }
+            }
+            const sources = new Map();
+            for (const [name, source] of Object.entries(block.icons.sources)) {
+                if (!OUTPUT_NAME_RE.test(name)) {
+                    problems.push(`\`icons.sources.${name}\`: an icon name is a plain file name.`);
+                    continue;
+                }
+                if (typeof source !== 'string' && !isRecord(source)) {
+                    problems.push(`\`icons.sources.${name}\` must be an SVG path or a map of size ceilings to SVGs.`);
+                    continue;
+                }
+                const bySize = new Map();
+                for (const size of sizes) {
+                    const svg = iconSourceForSize(source, size);
+                    if (svg === undefined) {
+                        problems.push(`\`icons.sources.${name}\` has no SVG for ${size} px — add a "default".`);
+                        continue;
+                    }
+                    if (!/\.svg$/i.test(svg))
+                        problems.push(`\`icons.sources.${name}\`: "${svg}" is not an .svg file.`);
+                    bySize.set(size, abs(svg));
+                }
+                for (const svg of new Set(bySize.values())) {
+                    if (!exists(svg, 'file'))
+                        problems.push(`\`icons.sources.${name}\`: "${svg}" does not exist.`);
+                }
+                sources.set(name, bySize);
+            }
+            icons = { sizes, sources, svgTargets };
+        }
+    }
+    const optionalDir = (key, fallback) => {
+        const declared = block[key];
+        if (declared !== undefined)
+            return need(`\`${key}\``, declared, 'dir');
+        const implicit = join(root, fallback);
+        return exists(implicit, 'dir') ? implicit : null;
+    };
+    const publicDir = optionalDir('public', 'public');
+    const localesDir = optionalDir('locales', '_locales');
+    const define = block.define ?? {};
+    if (!isRecord(define) || Object.values(define).some((v) => typeof v !== 'string')) {
+        problems.push('`define` must map identifiers to JS expressions given as strings.');
+    }
+    const watch = block.watch ?? [];
+    if (!Array.isArray(watch) || watch.some((w) => typeof w !== 'string')) {
+        problems.push('`watch` must be a list of directories.');
+    }
+    if (problems.length > 0) {
+        throw new Error(`gjsify webext: \`gjsify.webext\` in ${join(root, 'package.json')}:\n  - ${problems.join('\n  - ')}`);
+    }
+    return {
+        root,
+        name: block.name ?? defaultArtifactName(pkg.name),
+        version: pkg.version ?? '0.0.0',
+        targets,
+        manifest,
+        scripts,
+        pages,
+        icons,
+        publicDir,
+        localesDir,
+        outDir: abs(block.outDir ?? '.output'),
+        define: define,
+        watch: watch.map(abs),
+        minify: block.minify ?? true,
+    };
+}
+function defaultExists(path, kind) {
+    if (!existsSync(path))
+        return false;
+    const stat = statSync(path);
+    return kind === 'dir' ? stat.isDirectory() : stat.isFile();
+}
+/** Narrow the configured targets to the ones a command was asked for. */
+export function selectTargets(config, requested) {
+    if (requested === undefined || requested.length === 0)
+        return config.targets;
+    return requested.map((id) => {
+        const found = config.targets.find((t) => t.id === id);
+        if (found)
+            return found;
+        // Parse first: an unknown spelling deserves the vocabulary message, not "not configured".
+        parseWebextTarget(id);
+        throw new Error(`gjsify webext: target "${id}" is not in \`gjsify.webext.targets\` (${config.targets.map((t) => t.id).join(', ')}).`);
+    });
+}

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

@@ -0,0 +1,24 @@
+import { type RasterizeInput } from '../ship/icons.js';
+import type { ResolvedWebextIcons } from './config.js';
+import type { WebextTarget } from './targets.js';
+/** Where an icon lives inside a target folder, per size (`{ "16": "icons/idle-16.png" }`). */
+export declare function webextIconPaths(icons: ResolvedWebextIcons, name: string, target: WebextTarget): Record<string, string>;
+/**
+ * Every file an SVG target receives, keyed by its path in the target. Two
+ * different sources with one base name would overwrite each other there, so
+ * that is refused rather than decided by iteration order.
+ */
+export declare function svgIconFiles(icons: ResolvedWebextIcons): Map<string, string>;
+export interface RenderedIcons {
+    /** `icons/<name>-<size>.png` → bytes. Empty when no target needs rasters. */
+    png: Map<string, Uint8Array>;
+    /** `icons/<file>.svg` → source path. Empty when no target draws SVG. */
+    svg: Map<string, string>;
+}
+/**
+ * Render what the configured targets need, once for all of them: one child
+ * process per distinct SVG, each rendering every size that SVG is used for.
+ */
+export declare function renderWebextIcons(icons: ResolvedWebextIcons, targets: readonly WebextTarget[], rasterize?: (input: RasterizeInput) => Promise<Map<number, Uint8Array>>): Promise<RenderedIcons>;
+/** Write the icons one target receives into its folder. */
+export declare function writeWebextIcons(rendered: RenderedIcons, icons: ResolvedWebextIcons, target: WebextTarget, dir: string): void;

package/lib/utils/webext/icons.js

@@ -0,0 +1,83 @@
+// Extension icons from SVG (ADR 0077 § 2): PNGs at every size for the targets
+// that need rasters (Chromium draws no SVG in `icons`/`action.default_icon`),
+// the SVG files themselves for the targets that draw them (Firefox).
+//
+// The rendering is `ship`'s: librsvg in a `gjs -c` child, IHDR-checked, the same
+// on a GJS-hosted and a Node-hosted CLI. Only the naming lives here, and it
+// lives in ONE function (`webextIconPaths`) that both the file writer and the
+// manifest's `ctx.icons(name)` read, so a manifest cannot name an icon path the
+// build did not write.
+import { copyFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { rasterizeSvg } from '../ship/icons.js';
+/** Where an icon lives inside a target folder, per size (`{ "16": "icons/idle-16.png" }`). */
+export function webextIconPaths(icons, name, target) {
+    const bySize = icons.sources.get(name);
+    if (bySize === undefined) {
+        throw new Error(`gjsify webext: the manifest asks for icon "${name}", and \`gjsify.webext.icons.sources\` declares ` +
+            `${[...icons.sources.keys()].map((n) => `"${n}"`).join(', ') || 'none'}.`);
+    }
+    const svg = icons.svgTargets.has(target.id);
+    const out = {};
+    for (const size of icons.sizes) {
+        out[String(size)] = svg ? `icons/${basename(bySize.get(size))}` : `icons/${name}-${size}.png`;
+    }
+    return out;
+}
+/**
+ * Every file an SVG target receives, keyed by its path in the target. Two
+ * different sources with one base name would overwrite each other there, so
+ * that is refused rather than decided by iteration order.
+ */
+export function svgIconFiles(icons) {
+    const files = new Map();
+    for (const [name, bySize] of icons.sources) {
+        for (const source of bySize.values()) {
+            const path = `icons/${basename(source)}`;
+            const previous = files.get(path);
+            if (previous !== undefined && previous !== source) {
+                throw new Error(`gjsify webext: icon "${name}" uses ${source}, and ${previous} has the same file name; ` +
+                    'an SVG target would receive only one of them as ' +
+                    path +
+                    '. Rename one.');
+            }
+            files.set(path, source);
+        }
+    }
+    return files;
+}
+/**
+ * Render what the configured targets need, once for all of them: one child
+ * process per distinct SVG, each rendering every size that SVG is used for.
+ */
+export async function renderWebextIcons(icons, targets, rasterize = rasterizeSvg) {
+    const needsPng = targets.some((t) => !icons.svgTargets.has(t.id));
+    const needsSvg = targets.some((t) => icons.svgTargets.has(t.id));
+    const png = new Map();
+    if (needsPng) {
+        const jobs = new Map();
+        for (const [name, bySize] of icons.sources) {
+            for (const [size, svg] of bySize)
+                jobs.set(svg, [...(jobs.get(svg) ?? []), { size, name }]);
+        }
+        for (const [svg, uses] of jobs) {
+            const sizes = [...new Set(uses.map((u) => u.size))];
+            const rendered = await rasterize({ svg, sizes, command: 'gjsify webext' });
+            for (const { size, name } of uses)
+                png.set(`icons/${name}-${size}.png`, rendered.get(size));
+        }
+    }
+    return { png, svg: needsSvg ? svgIconFiles(icons) : new Map() };
+}
+/** Write the icons one target receives into its folder. */
+export function writeWebextIcons(rendered, icons, target, dir) {
+    mkdirSync(join(dir, 'icons'), { recursive: true });
+    if (icons.svgTargets.has(target.id)) {
+        for (const [path, source] of rendered.svg)
+            copyFileSync(source, join(dir, path));
+    }
+    else {
+        for (const [path, bytes] of rendered.png)
+            writeFileSync(join(dir, path), bytes);
+    }
+}

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

@@ -0,0 +1,32 @@
+import { type WebextTarget } from './targets.js';
+export interface WebExtRunOptions {
+    sourceDir: string;
+    target: WebextTarget;
+    profile: string;
+    browserBinary?: string;
+    headless?: boolean;
+}
+/** `web-ext run` arguments. Pure, so the flag spelling per browser is pinned by a spec. */
+export declare function webExtRunArgs(opts: WebExtRunOptions): string[];
+/**
+ * The persistent dev profile. Persistent because a fresh profile per run loses
+ * whatever the developer set up in the browser (a login, a granted permission)
+ * on every restart.
+ */
+export declare function defaultDevProfile(name: string, target: WebextTarget, env?: NodeJS.ProcessEnv): string;
+/** How to spawn web-ext: always the BARE name, with the environment that finds it. */
+export interface WebExtCommand {
+    cmd: 'web-ext';
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * The `web-ext` to run: the project's own install (walking up, because a
+ * workspace hoists it to the root), else one on PATH, else null.
+ *
+ * A project install is put on the child's PATH rather than spawned by its path:
+ * on Windows it is a `.cmd` shim, Node refuses to spawn a batch file directly
+ * (EINVAL, CVE-2024-27980), and `spawnToCompletion` routes only a BARE name
+ * through `cmd.exe`.
+ */
+export declare function resolveWebExt(root: string, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): WebExtCommand | null;
+export declare const WEB_EXT_MISSING: string;

package/lib/utils/webext/launch.js

@@ -0,0 +1,77 @@
+// Launching a browser with the dev build (ADR 0077 § 6) — through `web-ext run`,
+// which loads the folder as a temporary add-on and reloads it when the folder
+// changes. Firefox cannot load an unpacked extension from a command-line flag at
+// all; web-ext does it over the remote debugging protocol.
+//
+// web-ext is a Node program. Once `gjsify exec` (ADR 0076, #1812) ships, this is
+// the one place that changes: the spawn goes through it and a GJS-only host can
+// run the dev loop.
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join } from 'node:path';
+import { isOnPath } from '../check-system-deps.js';
+import { webExtRunTarget } from './targets.js';
+/** `web-ext run` arguments. Pure, so the flag spelling per browser is pinned by a spec. */
+export function webExtRunArgs(opts) {
+    const driver = webExtRunTarget(opts.target);
+    if (driver === null) {
+        throw new Error(`gjsify webext dev: web-ext cannot launch ${opts.target.browser}. Build with \`gjsify webext build ` +
+            `--target ${opts.target.id}\` and load the folder by hand, or pass \`--no-launch\`.`);
+    }
+    const args = [
+        'run',
+        '--source-dir',
+        opts.sourceDir,
+        '--target',
+        driver,
+        '--no-input',
+        '--profile-create-if-missing',
+    ];
+    if (driver === 'firefox-desktop') {
+        args.push('--firefox-profile', opts.profile, '--keep-profile-changes');
+        if (opts.browserBinary)
+            args.push('--firefox', opts.browserBinary);
+        if (opts.headless)
+            args.push('--arg=-headless');
+    }
+    else {
+        args.push('--chromium-profile', opts.profile);
+        if (opts.browserBinary)
+            args.push('--chromium-binary', opts.browserBinary);
+        if (opts.headless)
+            args.push('--arg=--headless=new');
+    }
+    return args;
+}
+/**
+ * The persistent dev profile. Persistent because a fresh profile per run loses
+ * whatever the developer set up in the browser (a login, a granted permission)
+ * on every restart.
+ */
+export function defaultDevProfile(name, target, env = process.env) {
+    const cache = env.XDG_CACHE_HOME || join(homedir(), '.cache');
+    return join(cache, 'gjsify', 'webext', name, target.id);
+}
+/**
+ * The `web-ext` to run: the project's own install (walking up, because a
+ * workspace hoists it to the root), else one on PATH, else null.
+ *
+ * A project install is put on the child's PATH rather than spawned by its path:
+ * on Windows it is a `.cmd` shim, Node refuses to spawn a batch file directly
+ * (EINVAL, CVE-2024-27980), and `spawnToCompletion` routes only a BARE name
+ * through `cmd.exe`.
+ */
+export function resolveWebExt(root, platform = process.platform, env = process.env) {
+    const leaf = platform === 'win32' ? 'web-ext.cmd' : 'web-ext';
+    for (let dir = root;; dir = dirname(dir)) {
+        const bin = join(dir, 'node_modules', '.bin');
+        if (existsSync(join(bin, leaf))) {
+            return { cmd: 'web-ext', env: { ...env, PATH: [bin, env.PATH].filter(Boolean).join(delimiter) } };
+        }
+        if (dirname(dir) === dir)
+            break;
+    }
+    return isOnPath('web-ext') ? { cmd: 'web-ext', env } : null;
+}
+export const WEB_EXT_MISSING = 'gjsify webext dev: `web-ext` is not installed. Add it to the project (`gjsify install --save-dev web-ext`) ' +
+    'or install it globally, or pass `--no-launch` to rebuild without a browser.';