@gjsify/cli 0.52.0 → 0.53.0

package/lib/utils/webext/manifest.js

@@ -0,0 +1,219 @@
+// The manifest per target (ADR 0077 § 3): a module or a JSON template,
+// composed WITHOUT converting keys between manifest versions, then checked
+// against the folder it describes.
+//
+// The checks are the ones a browser would otherwise report against the
+// manifest, far from the build that caused them: Chrome refuses to load a
+// folder whose background script is missing ("Could not load background
+// script") or that has `_locales/` without `default_locale`, and the store
+// rejects the same zip for the same reasons, days later.
+import { copyFileSync, existsSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Deep-merge `over` onto `base`: objects merge, arrays and scalars replace,
+ * `null` deletes. Arrays replace because "add a permission for Firefox" and
+ * "drop a permission for Firefox" cannot both be spelled by concatenation.
+ */
+export function mergeManifest(base, over) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(over)) {
+        if (value === null)
+            delete out[key];
+        else if (isRecord(value) && isRecord(out[key]))
+            out[key] = mergeManifest(out[key], value);
+        else
+            out[key] = value;
+    }
+    return out;
+}
+/** Apply a JSON template's `$targets` block for one target, and drop the block. */
+export function applyTargetOverrides(template, target) {
+    const { $targets, ...base } = template;
+    if ($targets === undefined)
+        return base;
+    if (!isRecord($targets))
+        throw new Error("gjsify webext: the manifest's `$targets` must be an object.");
+    const over = $targets[target];
+    if (over === undefined)
+        return base;
+    if (!isRecord(over))
+        throw new Error(`gjsify webext: \`$targets["${target}"]\` in the manifest must be an object.`);
+    return mergeManifest(base, over);
+}
+/** Produce the manifest for one target from a loaded template. */
+export async function composeManifest(template, ctx) {
+    const raw = typeof template === 'function' ? await template(ctx) : applyTargetOverrides(template, ctx.target);
+    if (!isRecord(raw)) {
+        throw new Error(`gjsify webext: the manifest for ${ctx.target} is not an object (got ${typeof raw}).`);
+    }
+    if (raw.version !== undefined)
+        return raw;
+    // Beside `name`, where a reader of manifest.json looks for it, rather than last.
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        out[key] = value;
+        if (key === 'name')
+            out.version = ctx.version;
+    }
+    if (out.version === undefined)
+        out.version = ctx.version;
+    return out;
+}
+let loadCounter = 0;
+/**
+ * Load a manifest template. A `.json` is parsed; a module is imported and its
+ * default export used.
+ *
+ * Every load is FRESH, because `webext dev` reloads the template on each
+ * rebuild and both hosts cache modules by URL: on Node a query string makes a
+ * new URL; under GJS the module is bundled (GJS cannot import `.ts`, nor a
+ * module with `node:` imports) and the bundle copied to a unique file name,
+ * because whether GJS's loader keeps a query string on a `file:` URL is not a
+ * thing to depend on.
+ */
+export async function loadManifestTemplate(path) {
+    if (/\.json$/i.test(path)) {
+        try {
+            return JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch (err) {
+            throw new Error(`gjsify webext: ${path} is not valid JSON: ${err.message}`);
+        }
+    }
+    let url;
+    let cleanup = null;
+    if (isGjs()) {
+        const { BuildAction } = await import('../../actions/build.js');
+        const bundled = await BuildAction.bundleFileForGjsCached(path, {
+            cacheSubdir: 'webext',
+            label: basename(path),
+            cache: false,
+            define: { 'import.meta.url': JSON.stringify(pathToFileURL(path).href) },
+        });
+        const copy = join(dirname(bundled), `manifest-${process.pid}-${++loadCounter}.mjs`);
+        copyFileSync(bundled, copy);
+        url = pathToFileURL(copy).href;
+        cleanup = () => rmSync(copy, { force: true });
+    }
+    else {
+        url = `${pathToFileURL(path).href}?t=${statSync(path).mtimeMs}-${++loadCounter}`;
+    }
+    try {
+        const mod = (await import(url));
+        const template = mod.default;
+        if (typeof template !== 'function' && !isRecord(template)) {
+            throw new Error(`gjsify webext: ${path} has no default export. Export the manifest object, or a function ` +
+                '`(ctx) => manifest` that receives the target.');
+        }
+        return template;
+    }
+    finally {
+        cleanup?.();
+    }
+}
+/** Keys that name a page, script, stylesheet or image inside the extension. */
+function addPath(out, value) {
+    if (typeof value !== 'string' || value === '')
+        return;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(value) || value.includes('*'))
+        return;
+    out.add(value.replace(/^\//, '').replace(/[?#].*$/, ''));
+}
+function addIconValue(out, value) {
+    if (typeof value === 'string')
+        addPath(out, value);
+    else if (isRecord(value))
+        for (const v of Object.values(value))
+            addPath(out, v);
+}
+/**
+ * Every file inside the extension the manifest refers to by path.
+ *
+ * Deliberately a list of the keys browsers LOAD from, not a walk over every
+ * string: `description` or a `commands` label that happens to look like a path
+ * is not a reference.
+ */
+export function manifestFileReferences(manifest) {
+    const out = new Set();
+    const background = manifest.background;
+    if (isRecord(background)) {
+        addPath(out, background.service_worker);
+        addPath(out, background.page);
+        if (Array.isArray(background.scripts))
+            for (const s of background.scripts)
+                addPath(out, s);
+    }
+    if (Array.isArray(manifest.content_scripts)) {
+        for (const cs of manifest.content_scripts) {
+            if (!isRecord(cs))
+                continue;
+            for (const key of ['js', 'css'])
+                if (Array.isArray(cs[key]))
+                    for (const f of cs[key])
+                        addPath(out, f);
+        }
+    }
+    for (const key of ['action', 'browser_action', 'page_action', 'sidebar_action']) {
+        const action = manifest[key];
+        if (!isRecord(action))
+            continue;
+        addPath(out, action.default_popup);
+        addPath(out, action.default_panel);
+        addIconValue(out, action.default_icon);
+    }
+    if (isRecord(manifest.options_ui))
+        addPath(out, manifest.options_ui.page);
+    addPath(out, manifest.options_page);
+    addPath(out, manifest.devtools_page);
+    if (isRecord(manifest.side_panel))
+        addPath(out, manifest.side_panel.default_path);
+    addIconValue(out, manifest.icons);
+    if (isRecord(manifest.chrome_url_overrides))
+        for (const v of Object.values(manifest.chrome_url_overrides))
+            addPath(out, v);
+    if (Array.isArray(manifest.web_accessible_resources)) {
+        for (const entry of manifest.web_accessible_resources) {
+            if (typeof entry === 'string')
+                addPath(out, entry);
+            else if (isRecord(entry) && Array.isArray(entry.resources))
+                for (const r of entry.resources)
+                    addPath(out, r);
+        }
+    }
+    return [...out].sort();
+}
+/**
+ * What is wrong with a composed manifest for the folder it will sit in.
+ * Returns problem sentences; empty means the browser has nothing to refuse
+ * that this build could have known about.
+ */
+export function checkManifest(manifest, target, dir) {
+    const problems = [];
+    if (manifest.manifest_version !== target.manifestVersion) {
+        problems.push(`manifest_version is ${JSON.stringify(manifest.manifest_version)}, and target ${target.id} is Manifest V${target.manifestVersion}. ` +
+            'gjsify does not convert keys between versions — branch on `ctx.manifestVersion` in the manifest.');
+    }
+    for (const ref of manifestFileReferences(manifest)) {
+        if (!existsSync(join(dir, ref))) {
+            problems.push(`the manifest names "${ref}", which the build did not write into ${target.id}/.`);
+        }
+    }
+    const hasLocales = existsSync(join(dir, '_locales'));
+    const defaultLocale = manifest.default_locale;
+    if (hasLocales && typeof defaultLocale !== 'string') {
+        problems.push('_locales/ exists but the manifest sets no default_locale; the browser refuses to load it.');
+    }
+    else if (!hasLocales && defaultLocale !== undefined) {
+        problems.push(`the manifest sets default_locale "${String(defaultLocale)}" but there is no _locales/ directory.`);
+    }
+    else if (typeof defaultLocale === 'string' &&
+        !existsSync(join(dir, '_locales', defaultLocale, 'messages.json'))) {
+        problems.push(`default_locale is "${defaultLocale}" but _locales/${defaultLocale}/messages.json does not exist.`);
+    }
+    return problems;
+}

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

@@ -0,0 +1,26 @@
+export interface PageScript {
+    /** Absolute path of the source the tag points at. */
+    entry: string;
+    /** `esm` for a `type="module"` tag, `iife` for a classic one. */
+    format: 'esm' | 'iife';
+    /** File name written into the target root. */
+    output: string;
+}
+export interface PageStylesheet {
+    source: string;
+    output: string;
+}
+export interface PagePlan {
+    html: string;
+    scripts: PageScript[];
+    stylesheets: PageStylesheet[];
+}
+/**
+ * Plan one page: which scripts to bundle and which stylesheets to copy, and the
+ * page with their references rewritten.
+ *
+ * Every relative `src` naming a JS/TS file is bundled. A prebuilt script that
+ * must load verbatim goes in `public/` and is referenced by an absolute
+ * extension path (`/vendor/x.js`), which is left alone.
+ */
+export declare function planPage(name: string, htmlPath: string, html: string): PagePlan;

package/lib/utils/webext/pages.js

@@ -0,0 +1,61 @@
+// An extension page (popup, options, side panel …) as the build sees it: the
+// local scripts it loads, the local stylesheets it links, and the page with
+// both rewritten to point at the built files in the target root.
+//
+// Regex-based on purpose, like `utils/html-entry.ts`: this rewrites attribute
+// values in author-written shell pages, it is not an HTML pipeline. Everything
+// not matched (inline `<style>`, inline scripts, remote URLs) passes through.
+import { basename, dirname, isAbsolute, resolve } from 'node:path';
+const SCRIPT_TAG_RE = /<script\b[^>]*\bsrc\s*=\s*["'][^"']+["'][^>]*>/gi;
+const LINK_TAG_RE = /<link\b[^>]*>/gi;
+const SRC_RE = /\bsrc\s*=\s*(["'])([^"']+)\1/i;
+const HREF_RE = /\bhref\s*=\s*(["'])([^"']+)\1/i;
+const MODULE_RE = /\btype\s*=\s*["']module["']/i;
+const STYLESHEET_RE = /\brel\s*=\s*["'][^"']*\bstylesheet\b[^"']*["']/i;
+/** Remote, protocol-relative, data: and extension-absolute URLs are not ours to bundle. */
+const NOT_LOCAL_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+const SOURCE_EXT_RE = /\.(?:[cm]?[jt]sx?)$/i;
+/**
+ * Plan one page: which scripts to bundle and which stylesheets to copy, and the
+ * page with their references rewritten.
+ *
+ * Every relative `src` naming a JS/TS file is bundled. A prebuilt script that
+ * must load verbatim goes in `public/` and is referenced by an absolute
+ * extension path (`/vendor/x.js`), which is left alone.
+ */
+export function planPage(name, htmlPath, html) {
+    const dir = dirname(htmlPath);
+    const scripts = [];
+    const stylesheets = [];
+    const local = (value) => {
+        if (NOT_LOCAL_RE.test(value) || value.startsWith('/'))
+            return null;
+        const path = value.replace(/[?#].*$/, '');
+        return isAbsolute(path) ? path : resolve(dir, path);
+    };
+    let out = html.replace(SCRIPT_TAG_RE, (tag) => {
+        const src = SRC_RE.exec(tag);
+        if (!src)
+            return tag;
+        const entry = local(src[2]);
+        if (entry === null || !SOURCE_EXT_RE.test(entry))
+            return tag;
+        const output = scripts.length === 0 ? `${name}.js` : `${name}-${scripts.length + 1}.js`;
+        scripts.push({ entry, format: MODULE_RE.test(tag) ? 'esm' : 'iife', output });
+        return tag.replace(SRC_RE, (_whole, quote) => `src=${quote}${output}${quote}`);
+    });
+    out = out.replace(LINK_TAG_RE, (tag) => {
+        if (!STYLESHEET_RE.test(tag))
+            return tag;
+        const href = HREF_RE.exec(tag);
+        if (!href)
+            return tag;
+        const source = local(href[2]);
+        if (source === null)
+            return tag;
+        const output = basename(source);
+        stylesheets.push({ source, output });
+        return tag.replace(HREF_RE, (_whole, quote) => `href=${quote}${output}${quote}`);
+    });
+    return { html: out, scripts, stylesheets };
+}

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

@@ -0,0 +1,13 @@
+export type WebextBrowser = 'chrome' | 'edge' | 'firefox' | 'safari';
+export interface WebextTarget {
+    /** As spelled in `gjsify.webext.targets` and the output directory name. */
+    readonly id: string;
+    readonly browser: WebextBrowser;
+    readonly manifestVersion: 2 | 3;
+}
+export declare const WEBEXT_BROWSERS: readonly WebextBrowser[];
+/** What a project gets when it declares no `targets`. */
+export declare const DEFAULT_WEBEXT_TARGETS: readonly string[];
+export declare function parseWebextTarget(id: string): WebextTarget;
+/** Whether `web-ext run` launches this target through its Firefox or its Chromium driver. */
+export declare function webExtRunTarget(target: WebextTarget): 'firefox-desktop' | 'chromium' | null;

package/lib/utils/webext/targets.js

@@ -0,0 +1,36 @@
+// The build targets of `gjsify webext` (ADR 0077 § 2): `<browser>-mv<2|3>`.
+//
+// The vocabulary is mirrored by the `webext` conformance rule in
+// `@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'];
+/** 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.
+ */
+const MV2_REMOVED = new Set(['chrome', 'edge']);
+export function parseWebextTarget(id) {
+    const match = /^([a-z]+)-mv([23])$/.exec(id);
+    const browser = match?.[1];
+    if (!match || browser === undefined || !WEBEXT_BROWSERS.includes(browser)) {
+        throw new Error(`gjsify webext: unknown target "${id}". A target is <browser>-mv<2|3> with browser one of ` +
+            `${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.`);
+    }
+    return { id, browser, manifestVersion };
+}
+/** Whether `web-ext run` launches this target through its Firefox or its Chromium driver. */
+export function webExtRunTarget(target) {
+    if (target.browser === 'firefox')
+        return 'firefox-desktop';
+    if (target.browser === 'chrome' || target.browser === 'edge')
+        return 'chromium';
+    return null;
+}

package/lib/utils/win32-command.d.ts

@@ -38,6 +38,23 @@ export declare function escapeCmdArgument(arg: string, doubleEscapeMetaChars?: b
  * `args` are the caller's UNESCAPED arguments; `comspec` is normally `%COMSPEC%`.
  */
 export declare function buildCmdExeInvocation(commandFile: string, args: readonly string[], comspec?: string): Win32Invocation;
+/**
+ * Find `cmd` on `ctx.env.PATH` the way the host's process creation would, or
+ * `undefined`.
+ *
+ * On win32 a bare name is tried with each `PATHEXT` extension per directory — the
+ * order `CreateProcess` itself uses — and NEVER as-is: the extensionless member of
+ * npm's shim trio (`npm`, `gjsify`) is a `sh` script that exists on disk and cannot
+ * be executed, so an existence probe that accepts it answers "yes" for a command
+ * that is ENOENT to `spawn`. A name that already carries an extension, and every
+ * name off win32, is probed verbatim.
+ *
+ * Exported because "is X on PATH" is asked outside the spawn path too
+ * (`isOnPath` in `check-system-deps.ts`), and a second, PATHEXT-blind walk there
+ * reported `signtool` missing on a Windows host with `signtool.exe` on PATH —
+ * `gjsify ship win32 --sign` refused to run on the one OS it can sign on.
+ */
+export declare function findOnPath(cmd: string, ctx: Win32ResolveContext): string | undefined;
 /**
  * Rewrite a bare command name into something Windows can actually spawn.
  *

package/lib/utils/win32-command.js

@@ -90,12 +90,27 @@ function isBareName(cmd) {
     return !cmd.includes('/') && !cmd.includes('\\') && !/\.[^.]+$/.test(cmd);
 }
 /**
- * Find `cmd` on the child's `PATH`, trying each `PATHEXT` extension per
- * directory — the order `CreateProcess` itself uses.
+ * Find `cmd` on `ctx.env.PATH` the way the host's process creation would, or
+ * `undefined`.
+ *
+ * On win32 a bare name is tried with each `PATHEXT` extension per directory — the
+ * order `CreateProcess` itself uses — and NEVER as-is: the extensionless member of
+ * npm's shim trio (`npm`, `gjsify`) is a `sh` script that exists on disk and cannot
+ * be executed, so an existence probe that accepts it answers "yes" for a command
+ * that is ENOENT to `spawn`. A name that already carries an extension, and every
+ * name off win32, is probed verbatim.
+ *
+ * Exported because "is X on PATH" is asked outside the spawn path too
+ * (`isOnPath` in `check-system-deps.ts`), and a second, PATHEXT-blind walk there
+ * reported `signtool` missing on a Windows host with `signtool.exe` on PATH —
+ * `gjsify ship win32 --sign` refused to run on the one OS it can sign on.
  */
-function lookupOnPath(cmd, ctx) {
-    const dirs = (lookupEnv(ctx.env, 'PATH') ?? '').split(';').filter(Boolean);
-    const exts = (lookupEnv(ctx.env, 'PATHEXT') ?? DEFAULT_PATHEXT).split(';').filter(Boolean);
+export function findOnPath(cmd, ctx) {
+    const win = ctx.platform === 'win32';
+    const dirs = (lookupEnv(ctx.env, 'PATH') ?? '').split(win ? ';' : ':').filter(Boolean);
+    const exts = win && !/\.[^.\\/]+$/.test(cmd)
+        ? (lookupEnv(ctx.env, 'PATHEXT') ?? DEFAULT_PATHEXT).split(';').filter(Boolean)
+        : [''];
     for (const dir of dirs) {
         for (const ext of exts) {
             const candidate = ctx.join(dir, cmd + ext);
@@ -115,7 +130,7 @@ function lookupOnPath(cmd, ctx) {
 export function resolveWin32Command(cmd, args, ctx) {
     if (ctx.platform !== 'win32' || !isBareName(cmd))
         return undefined;
-    const resolved = lookupOnPath(cmd, ctx);
+    const resolved = findOnPath(cmd, ctx);
     if (!resolved)
         return undefined;
     // `.exe`/`.com` run without an interpreter; spawning the resolved absolute path skips a

package/package.json

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