Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -30,5 +30,9 @@ jobs:
path: test-results/
- uses: actions/upload-artifact@v7
with:
name: spectral-extension
name: spectral-chromium
path: dist/
- uses: actions/upload-artifact@v7
with:
name: spectral-firefox
path: dist-firefox/
17 changes: 10 additions & 7 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name: Release

# Pushing a tag such as v0.1.0 builds the store package and attaches it to a
# GitHub Release, so every uploaded version stays downloadable.
# Pushing a tag such as v0.1.1 builds the store packages (Chromium and Firefox) and
# attaches them to a GitHub Release, so every uploaded version stays downloadable.
on:
push:
tags: ["v*"]
Expand All @@ -21,7 +21,7 @@ jobs:

- name: Check the tag matches the manifest version
run: |
manifest=$(jq -r .version public/manifest.json)
manifest=$(jq -r .version src/manifest.json)
pkg=$(jq -r .version package.json)
echo "Tag: $GITHUB_REF_NAME, manifest: $manifest, package.json: $pkg"
test "$GITHUB_REF_NAME" = "v$manifest"
Expand All @@ -33,14 +33,17 @@ jobs:
- run: npm run build
- run: npm run firefox:lint

- name: Zip the contents of dist/
- name: Zip the contents of each build
run: |
(cd dist && zip -qrX "../spectral-$VERSION.zip" .)
unzip -l "spectral-$VERSION.zip"
(cd dist && zip -qrX "../spectral-$VERSION-chromium.zip" .)
(cd dist-firefox && zip -qrX "../spectral-$VERSION-firefox.zip" .)
unzip -l "spectral-$VERSION-chromium.zip"
unzip -l "spectral-$VERSION-firefox.zip"

- name: Create the release
env:
GH_TOKEN: ${{ github.token }}
run: |
gh release create "$GITHUB_REF_NAME" "spectral-$VERSION.zip" \
gh release create "$GITHUB_REF_NAME" \
"spectral-$VERSION-chromium.zip" "spectral-$VERSION-firefox.zip" \
--title "Spectral $VERSION" --generate-notes --verify-tag
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ tmp/
### Project build output
node_modules/
dist/
dist-firefox/
build/
test-results/
playwright-report/
Expand Down
16 changes: 10 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,17 +13,21 @@ by [docs/AI-AGENTS.md](docs/AI-AGENTS.md); `CLAUDE.md` is a pointer to it.

- Install: `npm ci` (Node 22 or later).
- Validate: `npm run check` (typecheck and unit tests; always run after editing).
- Build: `npm run build` writes the unpacked extension to `dist/` through
`scripts/build.ts`: the popup with `vite.config.ts`, then the background as
a single IIFE with no imports, because Safari does not load module
background scripts.
- Build: `npm run build` writes the unpacked extension to `dist/` (Chromium
browsers and Safari) and `dist-firefox/` through `scripts/build.ts`: the
popup with `vite.config.ts`, then the background as a single IIFE with no
imports, because Safari does not load module background scripts.
- Manifest: edit `src/manifest.json`, never a built one. `scripts/manifest.ts`
adds `background.service_worker` for Chromium (whose stores reject
`background.scripts`) or `background.scripts` for Firefox, and keeps
`browser_specific_settings` only for Firefox.
- End-to-end: `npm run test:e2e` drives the built extension in Chromium with
a fixture site and mocked DoH and RDAP; run it after `npm run build`. Set
`CHROMIUM_PATH` to use an existing Chromium instead of Playwright's.
- Icons: `npm run icons` regenerates `public/icons/` from `scripts/icon.svg`;
commit both.
- Watch: `npm run dev` rebuilds `dist/` on change; reload the extension in the browser.
- Firefox: `npm run firefox:lint` validates `dist/` for AMO (after a build);
- Watch: `npm run dev` rebuilds `dist/` and `dist-firefox/` on change; reload the extension in the browser.
- Firefox: `npm run firefox:lint` validates `dist-firefox/` for AMO (after a build);
`npm run firefox:run` and `npm run firefox:android -- --android-device=<id>`
launch it.
- Safari on iOS: `.github/workflows/safari.yml` runs on a macOS runner, only on
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,11 @@ How to use this file:
- Extension icons.
- Released under the MIT License.

### Fixed

- Separate packages for Chromium browsers and Firefox, each declaring only
its own background key, so the Edge Add-ons store accepts the package.

<!--
## [0.1.0] - YYYY-MM-DD

Expand Down
28 changes: 17 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,11 +39,16 @@ npm ci
npm run build
```

Chrome: open `chrome://extensions`, enable Developer mode, choose Load
unpacked and select `dist/`.
The build writes `dist/` for Chromium browsers and Safari, and
`dist-firefox/` for Firefox; they differ only in `manifest.json`. Packaged
builds of each release are attached to the
[GitHub Releases](https://github.com/danielededo/spectral/releases).

Chrome and Edge: open `chrome://extensions` (or `edge://extensions`), enable
Developer mode, choose Load unpacked and select `dist/`.

Firefox (140 or later): open `about:debugging#/runtime/this-firefox`, choose
Load Temporary Add-on and select `dist/manifest.json`, or run
Load Temporary Add-on and select `dist-firefox/manifest.json`, or run
`npm run firefox:run`. Firefox treats host permissions as optional, so grant
"Access your data for all websites" from the extension's permissions page.

Expand All @@ -65,9 +70,8 @@ Settings, Apps, Safari, Extensions. A free Apple ID signature expires after
seven days. Whether Safari exposes response headers to extensions is not yet
verified, so the header-based findings may be missing there.

`npm run firefox:lint` validates the build against Mozilla's add-on rules.
The only expected warning is the ignored `background.service_worker` key,
which Chrome uses while Firefox uses `background.scripts`.
`npm run firefox:lint` validates the Firefox build against Mozilla's add-on
rules and is expected to report no warnings.

Response headers are captured while a page loads, so reload tabs that were
already open before the extension was installed.
Expand Down Expand Up @@ -99,7 +103,7 @@ it there whenever the table above changes.

```
npm run check # typecheck and unit tests
npm run dev # rebuild dist/ on change
npm run dev # rebuild dist/ and dist-firefox/ on change
npm run test:e2e # load dist/ in Chromium and drive the popup (build first)
npm run icons # regenerate public/icons/ from scripts/icon.svg
```
Expand Down Expand Up @@ -128,13 +132,14 @@ tests; see [AGENTS.md](AGENTS.md) for the architecture and conventions, and
├── LICENSE # MIT
├── package.json # scripts and dev dependencies
├── tsconfig.json
├── vite.config.ts # builds popup and service worker into dist/
├── vite.config.ts # popup build settings
├── playwright.config.ts # end-to-end test runner
├── public/
│ ├── manifest.json # Manifest V3, shared by Chrome and Firefox
│ └── icons/ # generated PNGs, 16 to 128 px
├── scripts/
│ ├── build.ts # builds the popup, then the background as one classic script
│ ├── build.ts # builds dist/ (Chromium) and dist-firefox/: popup, then background
│ ├── manifest.ts # writes each build's manifest.json from src/manifest.json
│ ├── manifest.test.ts
│ ├── icon.svg # icon source
│ └── render-icons.ts # renders icon.svg into public/icons/
├── e2e/
Expand All @@ -143,6 +148,7 @@ tests; see [AGENTS.md](AGENTS.md) for the architecture and conventions, and
│ ├── techstack.e2e.ts
│ └── tsconfig.json
├── src/
│ ├── manifest.json # Manifest V3 source; the build adds the background key per browser
│ ├── background.ts # service worker: captures main_frame responses
│ ├── shared/
│ │ └── capture.ts # per-tab capture in storage.session
Expand Down Expand Up @@ -182,7 +188,7 @@ tests; see [AGENTS.md](AGENTS.md) for the architecture and conventions, and
├── dependabot.yml # npm and GitHub Actions updates
└── workflows/
├── ci.yml # check, build, Firefox lint and end-to-end tests
├── release.yml # on a v* tag: store zip attached to a GitHub Release
├── release.yml # on a v* tag: Chromium and Firefox zips attached to a GitHub Release
└── safari.yml # on demand: unsigned iOS app with the Safari extension
```

Expand Down
21 changes: 15 additions & 6 deletions docs/STORE-LISTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ ask for nearly the same.

## Package

The version in the store is the `version` of `public/manifest.json`; it must
The version in the store is the `version` of `src/manifest.json`; it must
increase with every upload. Keep `package.json` on the same version.

To release, bump both versions on a branch, merge it, then tag the merge
Expand All @@ -18,8 +18,16 @@ git push origin v0.2.0
```

The `Release` workflow checks that the tag matches both versions, runs the
checks, builds, and attaches `spectral-<version>.zip` to a GitHub Release.
Upload that file to the store as it is.
checks, builds, and attaches two packages to a GitHub Release. Upload them to
the stores as they are:

- `spectral-<version>-chromium.zip`: Edge Add-ons and Chrome Web Store.
- `spectral-<version>-firefox.zip`: Firefox AMO.

They differ only in `manifest.json`. Chromium stores reject
`background.scripts` under Manifest V3 and Firefox has no background service
workers, so each build declares only its own background key, and only the
Firefox one carries `browser_specific_settings`.

To build the package by hand instead:

Expand All @@ -28,9 +36,10 @@ npm ci
npm run build
```

Zip the **contents** of `dist/` (the `manifest.json` at the root of the
archive, not inside a folder). The result for `0.1.0` is about 21 KB and
holds nine files. `store/*.zip` is ignored by git.
Zip the **contents** of `dist/` (Chromium) or `dist-firefox/` (Firefox),
with the `manifest.json` at the root of the archive, not inside a folder.
Each package is about 21 KB and holds nine files. `store/*.zip` is ignored by
git.

## Texts

Expand Down
3 changes: 2 additions & 1 deletion e2e/tsconfig.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
{
"extends": "../tsconfig.json",
"compilerOptions": {
"types": ["chrome", "node"]
"types": ["chrome", "node"],
"allowImportingTsExtensions": true
},
"include": [".", "../playwright.config.ts", "../scripts"]
}
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 4 additions & 4 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "spectral",
"version": "0.1.0",
"version": "0.1.1",
"private": true,
"description": "Browser extension that surfaces the infrastructure behind the site you are visiting",
"license": "MIT",
Expand All @@ -11,9 +11,9 @@
"typecheck": "tsc --noEmit && tsc --noEmit -p e2e",
"test": "vitest run",
"check": "npm run typecheck && npm run test",
"firefox:lint": "web-ext lint --source-dir dist",
"firefox:run": "web-ext run --source-dir dist",
"firefox:android": "web-ext run --source-dir dist --target firefox-android",
"firefox:lint": "web-ext lint --source-dir dist-firefox",
"firefox:run": "web-ext run --source-dir dist-firefox",
"firefox:android": "web-ext run --source-dir dist-firefox --target firefox-android",
"test:e2e": "playwright test",
"icons": "node scripts/render-icons.ts"
},
Expand Down
41 changes: 23 additions & 18 deletions scripts/build.ts
Original file line number Diff line number Diff line change
@@ -1,29 +1,34 @@
import { rm } from "node:fs/promises";
import { build } from "vite";
import { manifest, type Target } from "./manifest.ts";

// The background must be one classic script: Safari ignores "type": "module" for it,
// so it cannot share chunks with the popup and is built separately as an IIFE.
// Each browser family gets its own output, differing only in manifest.json.
const watch = process.argv.includes("--watch");
const mode = watch ? "development" : "production";
const targets: Record<string, Target> = { dist: "chromium", "dist-firefox": "firefox" };

await rm("dist", { recursive: true, force: true });
for (const [outDir, target] of Object.entries(targets)) {
await rm(outDir, { recursive: true, force: true });

await build({ mode, build: { watch: watch ? {} : null } });
await build({ mode, plugins: [manifest(target)], build: { outDir, watch: watch ? {} : null } });

await build({
configFile: false,
mode,
build: {
outDir: "dist",
emptyOutDir: false,
copyPublicDir: false,
sourcemap: watch,
watch: watch ? {} : null,
lib: {
entry: "src/background.ts",
formats: ["iife"],
name: "spectralBackground",
fileName: () => "background.js",
await build({
configFile: false,
mode,
build: {
outDir,
emptyOutDir: false,
copyPublicDir: false,
sourcemap: watch,
watch: watch ? {} : null,
lib: {
entry: "src/background.ts",
formats: ["iife"],
name: "spectralBackground",
fileName: () => "background.js",
},
},
},
});
});
}
23 changes: 23 additions & 0 deletions scripts/manifest.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
import { describe, expect, it } from "vitest";
import { manifestFor } from "./manifest.ts";

const base = {
manifest_version: 3,
name: "Spectral",
browser_specific_settings: { gecko: { id: "spectral@danielededo.it" } },
};

describe("manifestFor", () => {
it("gives Chromium only the service worker and no Gecko settings", () => {
const manifest = manifestFor(base, "chromium");
expect(manifest.background).toEqual({ service_worker: "background.js" });
expect(manifest).not.toHaveProperty("browser_specific_settings");
expect(manifest.name).toBe("Spectral");
});

it("gives Firefox only the background script and keeps Gecko settings", () => {
const manifest = manifestFor(base, "firefox");
expect(manifest.background).toEqual({ scripts: ["background.js"] });
expect(manifest.browser_specific_settings).toEqual(base.browser_specific_settings);
});
});
32 changes: 32 additions & 0 deletions scripts/manifest.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
import { readFile } from "node:fs/promises";
import type { Plugin } from "vite";

export type Target = "chromium" | "firefox";

const SOURCE = "src/manifest.json";

// Chromium stores reject background.scripts under Manifest V3 and Firefox has no
// background service workers, so each target gets only its own background key.
export function manifestFor(base: Record<string, unknown>, target: Target): Record<string, unknown> {
if (target === "firefox") return { ...base, background: { scripts: ["background.js"] } };
const { browser_specific_settings: _, ...chromium } = base;
return { ...chromium, background: { service_worker: "background.js" } };
}

// Emits manifest.json with the bundle, so watch rebuilds keep it in place.
export function manifest(target: Target): Plugin {
return {
name: "spectral-manifest",
buildStart() {
this.addWatchFile(SOURCE);
},
async generateBundle() {
const base = JSON.parse(await readFile(SOURCE, "utf8"));
this.emitFile({
type: "asset",
fileName: "manifest.json",
source: `${JSON.stringify(manifestFor(base, target), null, 2)}\n`,
});
},
};
}
8 changes: 1 addition & 7 deletions public/manifest.json → src/manifest.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"manifest_version": 3,
"name": "Spectral",
"version": "0.1.0",
"version": "0.1.1",
"description": "See the infrastructure behind the site you are visiting: CDN, hosting, network owner, DNS and email providers.",
"icons": {
"16": "icons/icon-16.png",
Expand All @@ -17,12 +17,6 @@
"32": "icons/icon-32.png"
}
},
"background": {
"service_worker": "background.js",
"scripts": [
"background.js"
]
},
"permissions": [
"webRequest",
"storage",
Expand Down
Loading