build(firefox): a second package, MV3, held to its own manifest gate

wxt.config.ts now builds for the target browser (docs/08 §1, §9):

- `manifestVersion: 3` for every target — WXT built Firefox as MV2;
- Firefox gets browser_specific_settings.gecko — the permanent id
  bookmarkmagic@poli0981.dev, strict_min_version 140.0 (the first that
  accepts data_collection_permissions, which AMO requires of new add-ons),
  and data_collection_permissions { required: ["none"] } — and no
  minimum_chrome_version; Chrome keeps its floor of 136;
- Vite targets firefox140 for that package;
- the sources archive AMO reviews leaves out coverage, captures, store copy,
  docs, tests and tools.

Permissions, CSP, pages and icons are identical in both packages.
check-manifest.mjs takes --browser chrome|firefox, mapped through a fixed
table to .output/<target>-mv3 (still no path from the command line), and
pins each package's exact key set and floor; the gecko block is compared key
order aside. New npm scripts: build:firefox, zip:firefox; verify:full builds
and checks both packages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-11-18 22:10:35 +07:00
1 parent 355443ef6b
commit 779335802a
6 files changed
+238 -29

No files matched your search

+3 -1
View File
@@ -22,7 +22,9 @@
"dev": "wxt",
"dev:firefox": "wxt -b firefox",
"build": "wxt build",
"build:firefox": "wxt build -b firefox",
"zip": "wxt zip",
"zip:firefox": "wxt zip -b firefox",
"check": "svelte-check --tsconfig ./tsconfig.json --fail-on-warnings && tsc --noEmit && tsc -p tsconfig.scripts.json",
"lint": "biome check .",
"lint:fix": "biome check --write .",
@@ -35,7 +37,7 @@
"test:watch": "vitest",
"coverage": "vitest run --coverage",
"verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run check:licenses && npm run test",
"verify:full": "npm run verify && npm run coverage && npm run build && npm run check:manifest"
"verify:full": "npm run verify && npm run coverage && npm run build && npm run check:manifest && npm run build:firefox && npm run check:manifest -- --browser firefox"
},
"devDependencies": {
"@biomejs/biome": "2.6.6",
+5 -1
View File
@@ -2,4 +2,8 @@
* Types for scripts/check-manifest.mjs, so its tests can call it directly.
* The script itself is plain JavaScript checked with `// @ts-check`.
*/
export function checkExtension(outDir: string): { problems: string[]; readError?: string };
export const TARGETS: Record<string, { dir: string; keys: string[]; label: string }>;
export function checkExtension(
outDir: string,
target?: string,
): { problems: string[]; readError?: string };
+89 -19
View File
@@ -18,10 +18,12 @@
* 3. the bundle: none of the network identifiers `npm run guard` bans in the
* source, anywhere in the shipped JavaScript.
*
* Usage: node scripts/check-manifest.mjs — checks <repo>/.output/chrome-mv3,
* resolved from this file, not the cwd. It takes no arguments on purpose: a
* path from the command line flowed straight into file reads (SonarCloud
* S8707). Its tests call `checkExtension(dir)` directly instead.
* Usage: node scripts/check-manifest.mjs [--browser chrome|firefox] — checks
* <repo>/.output/chrome-mv3 (the default) or <repo>/.output/firefox-mv3 (since
* v1.3.0, docs/08 §9), resolved from this file, not the cwd. It takes no path:
* one from the command line flowed straight into file reads (SonarCloud
* S8707), so `--browser` only picks an entry of a fixed table. Its tests call
* `checkExtension(dir, target)` directly instead.
*/
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { join, relative, resolve } from 'node:path';
@@ -54,7 +56,10 @@ const EXPECTED_CSP =
*
* Adding a key here is a deliberate act. Check docs/08 §1 first.
*/
const EXPECTED_KEYS = [
/** @param {string} a @param {string} b */
const byName = (a, b) => a.localeCompare(b, 'en');
const COMMON_KEYS = [
'action',
'content_security_policy',
'default_locale',
@@ -62,13 +67,57 @@ const EXPECTED_KEYS = [
'homepage_url',
'icons',
'manifest_version',
'minimum_chrome_version',
'name',
'options_ui',
'permissions',
'version',
];
/**
* Firefox's block, exactly (docs/08 §9). The id is permanent once on AMO; the
* floor is the first Firefox that accepts `data_collection_permissions`.
*/
const FIREFOX_SETTINGS = {
gecko: {
id: 'bookmarkmagic@poli0981.dev',
strict_min_version: '140.0',
data_collection_permissions: { required: ['none'] },
},
};
/**
* The two packages (docs/08 §1): where each is built, its exact key set, and
* how its floor reads in the log. Edge Add-ons takes the Chrome package.
*
* @type {Record<string, { dir: string, keys: string[], label: string }>}
*/
export const TARGETS = {
chrome: {
dir: 'chrome-mv3',
keys: [...COMMON_KEYS, 'minimum_chrome_version'].sort(byName),
label: `Chrome ≥${CHROME_FLOOR}`,
},
firefox: {
dir: 'firefox-mv3',
keys: [...COMMON_KEYS, 'browser_specific_settings'].sort(byName),
label: 'Firefox ≥140, gecko id pinned',
},
};
/**
* A value's JSON with object keys sorted, so key order never decides equality.
* @param {unknown} value
* @returns {string}
*/
function canonical(value) {
if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
if (value !== null && typeof value === 'object') {
const entries = Object.entries(value).sort(([a], [b]) => byName(a, b));
return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(',')}}`;
}
return JSON.stringify(value) ?? 'undefined';
}
/** Keys that would widen the extension's reach. None may be present. */
const FORBIDDEN_KEYS = [
'host_permissions',
@@ -110,9 +159,6 @@ const NETWORK_IN_BUNDLE =
/** `src`/`href` values in a built page. Vite writes them double-quoted. */
const PAGE_REFS = /\b(?:src|href)="([^"]*)"/g;
/** @param {string} a @param {string} b */
const byName = (a, b) => a.localeCompare(b, 'en');
/** @param {string} dir @returns {string[]} */
function listFiles(dir) {
return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
@@ -133,8 +179,13 @@ function readManifest(outDir) {
}
}
/** @param {Record<string, unknown>} manifest @param {string[]} problems */
function checkManifest(manifest, problems) {
/**
* @param {Record<string, unknown>} manifest
* @param {string[]} problems
* @param {string} target - a key of TARGETS
*/
function checkManifest(manifest, problems, target) {
const expectedKeys = TARGETS[target]?.keys ?? [];
if (manifest.manifest_version !== 3) {
problems.push(`manifest_version is ${manifest.manifest_version}, expected 3`);
}
@@ -152,14 +203,20 @@ function checkManifest(manifest, problems) {
}
const actualKeys = Object.keys(manifest);
const unexpected = actualKeys.filter((key) => !EXPECTED_KEYS.includes(key)).sort(byName);
const missing = EXPECTED_KEYS.filter((key) => !actualKeys.includes(key));
const unexpected = actualKeys.filter((key) => !expectedKeys.includes(key)).sort(byName);
const missing = expectedKeys.filter((key) => !actualKeys.includes(key));
if (unexpected.length > 0) {
problems.push(`unexpected top-level key(s): ${unexpected.join(', ')} — see docs/08 §1`);
}
if (missing.length > 0) problems.push(`missing expected top-level key(s): ${missing.join(', ')}`);
if (manifest.minimum_chrome_version !== CHROME_FLOOR) {
if (target === 'firefox') {
if (canonical(manifest.browser_specific_settings) !== canonical(FIREFOX_SETTINGS)) {
problems.push(
`browser_specific_settings is ${JSON.stringify(manifest.browser_specific_settings)}, expected exactly ${JSON.stringify(FIREFOX_SETTINGS)} (docs/08 §9)`,
);
}
} else if (manifest.minimum_chrome_version !== CHROME_FLOOR) {
problems.push(
`minimum_chrome_version is ${JSON.stringify(manifest.minimum_chrome_version)}, expected "${CHROME_FLOOR}" (docs/01 §1)`,
);
@@ -235,15 +292,19 @@ function checkBundle(outDir, problems) {
* Check one built extension directory.
*
* @param {string} outDir
* @param {string} [target] - a key of TARGETS; `chrome` when omitted
* @returns {{ problems: string[], readError?: string }} no problems and no read
* error means the build is clean
*/
export function checkExtension(outDir) {
export function checkExtension(outDir, target = 'chrome') {
if (!Object.hasOwn(TARGETS, target)) {
return { problems: [], readError: `unknown target "${target}"` };
}
const manifest = readManifest(outDir);
if (typeof manifest === 'string') return { problems: [], readError: manifest };
/** @type {string[]} */
const problems = [];
checkManifest(manifest, problems);
checkManifest(manifest, problems, target);
checkInventory(outDir, manifest, problems);
checkBundle(outDir, problems);
return { problems };
@@ -251,10 +312,19 @@ export function checkExtension(outDir) {
/** @returns {number} the exit code */
function main() {
const flag = process.argv.indexOf('--browser');
const target = flag === -1 ? 'chrome' : (process.argv[flag + 1] ?? '');
const profile = Object.hasOwn(TARGETS, target) ? TARGETS[target] : undefined;
if (profile === undefined) {
console.error(`check-manifest: --browser must be one of ${Object.keys(TARGETS).join(', ')}`);
return 1;
}
const repo = resolve(fileURLToPath(new URL('..', import.meta.url)));
const { problems, readError } = checkExtension(join(repo, '.output', 'chrome-mv3'));
// The directory comes from the table, never from the command line.
const { problems, readError } = checkExtension(join(repo, '.output', profile.dir), target);
if (readError !== undefined) {
console.error(`check-manifest: ${readError} — run \`npm run build\` first.`);
const build = target === 'chrome' ? 'npm run build' : `npm run build:${target}`;
console.error(`check-manifest: ${readError} — run \`${build}\` first.`);
return 1;
}
if (problems.length > 0) {
@@ -268,7 +338,7 @@ function main() {
// Constants only: the manifest has just passed every check, so its values ARE
// these — and nothing read from a file is echoed into the log.
console.warn(
`check-manifest: clean — MV3, permissions exactly ${ALLOWED_PERMISSIONS.join(' + ')}, Chrome ≥${CHROME_FLOOR}, CSP pinned, inventory complete, no network API in the bundle.`,
`check-manifest: clean (${target}) — MV3, permissions exactly ${ALLOWED_PERMISSIONS.join(' + ')}, ${profile.label}, CSP pinned, inventory complete, no network API in the bundle.`,
);
return 0;
}
+21 -4
View File
@@ -89,7 +89,7 @@ describe('manifest', () => {
// Float16Array) that throw on the oldest Chrome still allowed to install.
expect(CONFIG).toMatch(/const CHROME_FLOOR = 136;/);
expect(CONFIG).toMatch(/minimum_chrome_version:\s*String\(CHROME_FLOOR\)/);
expect(CONFIG).toMatch(/target:\s*`chrome\$\{CHROME_FLOOR\}`/);
expect(CONFIG).toMatch(/:\s*`chrome\$\{CHROME_FLOOR\}`/);
// SAFETY: tsconfig.json is a committed file with exactly this shape; a
// missing key fails the expectations below rather than passing silently.
const tsconfig = JSON.parse(readFileSync(join(process.cwd(), 'tsconfig.json'), 'utf8')) as {
@@ -99,6 +99,21 @@ describe('manifest', () => {
expect(tsconfig.compilerOptions.lib).toEqual(['ES2025', 'DOM', 'DOM.Iterable']);
});
it('gives Firefox its own floor and gecko block, and Chrome its own floor (docs/08 §9)', () => {
// The one key that differs between the two packages — chosen by the
// target browser, never both in one manifest.
expect(CONFIG).toMatch(/const FIREFOX_FLOOR = 140;/);
expect(CONFIG).toMatch(
/browser === 'firefox'\s*\?\s*\{ browser_specific_settings: FIREFOX_SETTINGS \}\s*:\s*\{ minimum_chrome_version: String\(CHROME_FLOOR\) \}/,
);
// The id is permanent once on AMO: a change here is a new add-on.
expect(CONFIG).toContain("id: 'bookmarkmagic@poli0981.dev'");
expect(CONFIG).toMatch(/strict_min_version:\s*`\$\{FIREFOX_FLOOR\}\.0`/);
// Firefox's own "collects nothing" — the CWS privacy tab's answer.
expect(CONFIG).toContain("data_collection_permissions: { required: ['none'] }");
expect(CONFIG).toMatch(/env\.browser === 'firefox' \? `firefox\$\{FIREFOX_FLOOR\}`/);
});
it('declares the extension-page CSP once, production-only, and only ever stricter', () => {
// docs/08 §3: the CSP is what makes the zero-network promise browser-
// enforced. check-manifest.mjs pins the exact built string; this pins the
@@ -131,10 +146,12 @@ describe('manifest', () => {
expect(csp.match(/default-src[^"]*/g)).toEqual(["default-src 'none'"]);
});
it('keeps the manifest at v3 by not overriding WXT’s default', () => {
// WXT emits manifest_version 3 for the chrome-mv3 target. An explicit
// downgrade here would be the only way to lose it.
it('builds MV3 for every browser', () => {
// WXT defaults Firefox to MV2; `manifestVersion: 3` is what keeps the
// Firefox package on the manifest, CSP and review story of docs/08.
expect(CONFIG).toMatch(/manifestVersion:\s*3,/);
expect(CONFIG).not.toMatch(/manifest_version\s*:\s*2/);
expect(CONFIG).not.toMatch(/manifestVersion:\s*2/);
});
it('still points default_locale at en, and ships a _locales entry per UI locale', () => {
+73
View File
@@ -182,3 +182,76 @@ describe('check-manifest.mjs', () => {
expect(output).not.toContain('/etc');
});
});
describe('check-manifest.mjs — the Firefox package (docs/08 §9)', () => {
const { minimum_chrome_version: _chromeOnly, ...common } = MANIFEST;
const GECKO = {
id: 'bookmarkmagic@poli0981.dev',
strict_min_version: '140.0',
data_collection_permissions: { required: ['none'] },
};
const FIREFOX = { ...common, browser_specific_settings: { gecko: GECKO } };
function checkAs(dir: string, target: string): { status: number; output: string } {
const { problems, readError } = checkExtension(dir, target);
const failed = readError !== undefined || problems.length > 0;
return { status: failed ? 1 : 0, output: [readError ?? '', ...problems].join('\n') };
}
it('passes a correct Firefox build, in any key order', () => {
const reordered = {
...FIREFOX,
browser_specific_settings: {
gecko: {
data_collection_permissions: { required: ['none'] },
strict_min_version: '140.0',
id: 'bookmarkmagic@poli0981.dev',
},
},
};
for (const manifest of [FIREFOX, reordered]) {
const { status, output } = checkAs(build(manifest), 'firefox');
expect(status, output).toBe(0);
}
});
it.each([
['another add-on id', { ...GECKO, id: 'other@example.org' }],
['the old Firefox floor', { ...GECKO, strict_min_version: '128.0' }],
['no data-collection declaration', { id: GECKO.id, strict_min_version: '140.0' }],
[
'a data collection',
{ ...GECKO, data_collection_permissions: { required: ['bookmarksInfo'] } },
],
])('fails on %s', (_label, gecko) => {
const { status, output } = checkAs(
build({ ...FIREFOX, browser_specific_settings: { gecko } }),
'firefox',
);
expect(status, output).toBe(1);
expect(output).toContain('browser_specific_settings is');
});
it('fails on a Chrome floor in the Firefox package', () => {
const { status, output } = checkAs(
build({ ...FIREFOX, minimum_chrome_version: '136' }),
'firefox',
);
expect(status, output).toBe(1);
expect(output).toContain('unexpected top-level key(s): minimum_chrome_version');
});
it('fails on a gecko block in the Chrome package', () => {
const { status, output } = check(
build({ ...MANIFEST, browser_specific_settings: { gecko: GECKO } }),
);
expect(status, output).toBe(1);
expect(output).toContain('unexpected top-level key(s): browser_specific_settings');
});
it('refuses a target it has no profile for', () => {
const { status, output } = checkAs(build(FIREFOX), 'safari');
expect(status).toBe(1);
expect(output).toContain('unknown target');
});
});
+47 -4
View File
@@ -19,6 +19,27 @@ import { CREDITED_PACKAGES } from './scripts/credited-packages.mjs';
*/
const CHROME_FLOOR = 136;
/**
* Firefox's floor (docs/08 §9): the first Firefox that accepts
* `data_collection_permissions`, which AMO requires of every new extension;
* every ES2025 built-in is older (`RegExp.escape` and `Promise.try`, 134).
*/
const FIREFOX_FLOOR = 140;
/**
* Firefox's block — docs/08 §9. The id is permanent once the add-on is on AMO;
* "none" is Firefox's own declaration that nothing is collected, the same
* answer as the Chrome Web Store privacy tab. `check:manifest --browser
* firefox` pins all of it in the built package.
*/
const FIREFOX_SETTINGS = {
gecko: {
id: 'bookmarkmagic@poli0981.dev',
strict_min_version: `${FIREFOX_FLOOR}.0`,
data_collection_permissions: { required: ['none'] },
},
};
/**
* The zero-network promise, enforced by the browser — docs/08 §3.
*
@@ -101,10 +122,15 @@ const thirdPartyGate = {
export default defineConfig({
srcDir: 'src',
vite: () => ({
// MV3 for every target. WXT builds Firefox as MV2 unless told otherwise, and
// this project's manifest, CSP and review story are MV3 (docs/08 §1).
manifestVersion: 3,
vite: (env) => ({
plugins: [thirdPartyGate],
build: {
target: `chrome${CHROME_FLOOR}`,
// The floor the package states, so the compiler never emits syntax the
// oldest allowed browser cannot run.
target: env.browser === 'firefox' ? `firefox${FIREFOX_FLOOR}` : `chrome${CHROME_FLOOR}`,
// Vite's modulepreload polyfill is a network call (it fetches each chunk
// ahead of time) for browsers without native `<link rel=modulepreload>`.
// Every Chrome at or above the floor has it, so the polyfill is dead code
@@ -118,11 +144,14 @@ export default defineConfig({
// refuses to load the extension (missing __MSG_appName__ and icons).
publicDir: 'src/public',
modules: ['@wxt-dev/module-svelte'],
manifest: ({ command }) => ({
manifest: ({ browser, command }) => ({
name: '__MSG_appName__',
description: '__MSG_appDesc__',
default_locale: 'en',
minimum_chrome_version: String(CHROME_FLOOR),
// The one key that differs between the two packages (docs/08 §1).
...(browser === 'firefox'
? { browser_specific_settings: FIREFOX_SETTINGS }
: { minimum_chrome_version: String(CHROME_FLOOR) }),
permissions: ['bookmarks', 'storage'],
// Deep-link lands on #settings only when no Manager tab is open — with
// open_in_tab Chrome matches the singleton tab ignoring the fragment,
@@ -139,4 +168,18 @@ export default defineConfig({
content_security_policy: { extension_pages: EXTENSION_PAGE_CSP },
}),
}),
// The sources archive `wxt zip -b firefox` writes for AMO's reviewers
// (docs/08 §9): what rebuilds the package — the source, the configs, the
// lockfile, the scripts the build imports — and nothing that is not.
zip: {
excludeSources: [
'coverage/**',
'capture/**',
'store/**',
'docs/**',
'tests/**',
'tools/**',
'stats.html',
],
},
});