diff --git a/.github/dependabot.yml b/.github/dependabot.yml index f365b34..0565384 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -56,6 +56,22 @@ updates: - dependency-name: '@types/node' update-types: [version-update:semver-major] + # The store-upload tool release.yml installs on its own (docs/12 §3): four + # packages, kept apart from the toolchain because they run beside store + # credentials. Its own directory, so its bumps arrive as their own PRs. + - package-ecosystem: npm + directory: /tools/publish + schedule: + interval: weekly + day: monday + open-pull-requests-limit: 2 + cooldown: + default-days: 7 + commit-message: + prefix: chore + prefix-development: chore + include: scope + - package-ecosystem: github-actions directory: / schedule: diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f0ba03c..ab70096 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -59,6 +59,9 @@ jobs: # tabs/scripting/host_permissions that never appear in the config file. - run: npm run build - run: npm run check:manifest + # The second package (docs/08 §9), held to its own key set and floor. + - run: npm run build:firefox + - run: npm run check:manifest -- --browser firefox windows: # Not a required check. The owner develops on Windows, and the paths that diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 71486d1..467c22e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -5,11 +5,16 @@ # (required by docs/09 §5), performs no store submission, and exposes no # `outputs:`, so a caller cannot reference the zip it built. # -# Three jobs, least privilege first. `build` installs, runs every gate and -# packages with a READ-ONLY token; only `publish`, which installs nothing and -# runs no repository code, ever holds `contents: write`. Before this split one -# job ran `npm ci` — every dependency's install script plus our own tests — -# while holding a write token that checkout had also left in .git/config. +# Least privilege first. `build` installs, runs every gate and packages with a +# READ-ONLY token; only `publish`, which installs nothing and runs no +# repository code, ever holds `contents: write`. Before the split one job ran +# `npm ci` — every dependency's install script plus our own tests — while +# holding a write token that checkout had also left in .git/config. +# +# Since v1.3.0 there are three release files: the Chromium package (the Chrome +# Web Store AND Edge Add-ons take it), the Firefox package, and the sources +# archive AMO reviews (docs/08 §9, docs/13 §1c). And three store jobs, one per +# store, each off until its repo variable says otherwise (docs/12 §3). name: Release on: @@ -47,33 +52,40 @@ jobs: - run: npm run check:licenses - run: npm audit --omit=dev --audit-level=low - - run: npm run zip # wxt zip → .output/--chrome.zip + - run: npm run zip # → .output/--chrome.zip (Chrome Web Store, Edge Add-ons) + - run: npm run zip:firefox # → …-firefox.zip and …-sources.zip (Firefox Add-ons) - # Gate the artifact, not just the config it was built from. A tag is the - # last point at which an unintended permission can still be stopped. + # Gate the artifacts, not just the config they were built from. A tag is + # the last point at which an unintended permission can still be stopped. - run: npm run check:manifest + - run: npm run check:manifest -- --browser firefox - - name: Verify tag matches manifest version + - name: Verify tag matches both manifests run: | set -euo pipefail - MANIFEST_VERSION=$(jq -r '.version' .output/chrome-mv3/manifest.json) TAG_VERSION="${GITHUB_REF_NAME#v}" - test "$MANIFEST_VERSION" = "$TAG_VERSION" \ - || { echo "::error::tag $TAG_VERSION != manifest $MANIFEST_VERSION"; exit 1; } - - - name: SHA256SUMS - working-directory: .output - run: sha256sum *-chrome.zip > SHA256SUMS.txt + for target in chrome firefox; do + MANIFEST_VERSION=$(jq -r '.version' ".output/${target}-mv3/manifest.json") + test "$MANIFEST_VERSION" = "$TAG_VERSION" \ + || { echo "::error::tag $TAG_VERSION != $target manifest $MANIFEST_VERSION"; exit 1; } + done # Staged in a plain directory: upload-artifact skips hidden paths by - # default, and `.output` is one. Left there, the upload found nothing and - # the first v1.1.0 tag run failed before any Release existed — the split - # into build and publish jobs had never run on a tag until then. + # default, and `.output` is one. Each file by its exact name: a glob would + # pass with one of the three missing. - name: Stage the release files run: | set -euo pipefail + VERSION="${GITHUB_REF_NAME#v}" mkdir dist - cp .output/*-chrome.zip .output/SHA256SUMS.txt dist/ + for file in "bookmarkmagic-${VERSION}-chrome.zip" \ + "bookmarkmagic-${VERSION}-firefox.zip" \ + "bookmarkmagic-${VERSION}-sources.zip"; do + test -f ".output/$file" || { echo "::error::missing release file $file"; exit 1; } + cp ".output/$file" dist/ + done + (cd dist && sha256sum bookmarkmagic-*.zip > SHA256SUMS.txt) + cat dist/SHA256SUMS.txt - uses: actions/upload-artifact@v7 with: @@ -101,9 +113,9 @@ jobs: run: sha256sum -c SHA256SUMS.txt # Idempotent on purpose. `gh release create` fails outright if a Release - # for the tag already exists, so any failure AFTER this step — realistically - # the store job below, once CWS_AUTOPUBLISH is on — used to strand the tag: - # re-running could not get past this line (docs/13 §7). + # for the tag already exists, so any failure AFTER this step — a store + # job, realistically — used to strand the tag: re-running could not get + # past this line (docs/13 §7). - name: Create or update the Release env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} @@ -112,45 +124,141 @@ jobs: set -euo pipefail if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then echo "Release $GITHUB_REF_NAME exists — re-uploading assets." - gh release upload "$GITHUB_REF_NAME" dist/*-chrome.zip dist/SHA256SUMS.txt --clobber + gh release upload "$GITHUB_REF_NAME" dist/*.zip dist/SHA256SUMS.txt --clobber else - gh release create "$GITHUB_REF_NAME" dist/*-chrome.zip dist/SHA256SUMS.txt \ + gh release create "$GITHUB_REF_NAME" dist/*.zip dist/SHA256SUMS.txt \ --verify-tag --generate-notes fi - store: - # v1.0.x/v1.1.x are published by hand (docs/12 §3). Flipping the repo - # variable CWS_AUTOPUBLISH to 'true' turns this on once the four CHROME_* - # secrets exist. A variable, not a secret: only variables are allowed here. + # --- Stores (docs/12 §3) ------------------------------------------------- + # + # One job per store, so a store's credentials never share a runner with + # another's and one store refusing an upload does not stop the others. Each + # runs in a GitHub Environment that holds only its own secrets (give it the + # owner as required reviewer), is off until its repo VARIABLE is 'true' (a + # secret is not allowed in a job-level `if:`), and installs only + # tools/publish — publish-browser-extension and its three dependencies, from + # their own lockfile, scripts off — not the dev toolchain: a job's secrets + # are readable by everything on its runner. Never re-run a store job that + # succeeded: every store refuses a version number it has already seen. + + # A sparse checkout of tools/publish still brings the repository's root files + # (cone mode), .nvmrc among them. + store-chrome: name: Publish to Chrome Web Store needs: publish if: vars.CWS_AUTOPUBLISH == 'true' runs-on: ubuntu-latest timeout-minutes: 15 + environment: chrome-web-store permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false + sparse-checkout: tools/publish - uses: actions/setup-node@v7 with: node-version-file: .nvmrc - cache: npm - - run: npm ci --ignore-scripts + - run: npm ci --ignore-scripts --prefix tools/publish - uses: actions/download-artifact@v8 with: name: release-${{ github.ref_name }} path: dist - - name: Submit the Release asset + - name: Check the file against the published checksums + working-directory: dist + run: sha256sum -c --ignore-missing SHA256SUMS.txt + - name: Submit env: + # API v2: v1.1 was shut down on 2026-10-15. Set explicitly — the tool + # still defaults to v1.1. + CHROME_API_VERSION: v2 + CHROME_PUBLISHER_ID: ${{ secrets.CHROME_PUBLISHER_ID }} CHROME_EXTENSION_ID: ${{ secrets.CHROME_EXTENSION_ID }} - CHROME_CLIENT_ID: ${{ secrets.CHROME_CLIENT_ID }} - CHROME_CLIENT_SECRET: ${{ secrets.CHROME_CLIENT_SECRET }} - CHROME_REFRESH_TOKEN: ${{ secrets.CHROME_REFRESH_TOKEN }} - # The locally installed wxt, never `npx wxt`: npx may fetch and run an - # unpinned package with these four secrets in its environment. - run: ./node_modules/.bin/wxt submit --chrome-zip dist/*-chrome.zip + CHROME_SERVICE_ACCOUNT_CLIENT_EMAIL: ${{ secrets.CHROME_SERVICE_ACCOUNT_CLIENT_EMAIL }} + CHROME_SERVICE_ACCOUNT_PRIVATE_KEY: ${{ secrets.CHROME_SERVICE_ACCOUNT_PRIVATE_KEY }} + run: | + set -euo pipefail + ./tools/publish/node_modules/.bin/publish-extension \ + --chrome-zip "dist/bookmarkmagic-${GITHUB_REF_NAME#v}-chrome.zip" + + store-firefox: + name: Publish to Firefox Add-ons + needs: publish + if: vars.AMO_AUTOPUBLISH == 'true' + runs-on: ubuntu-latest + timeout-minutes: 30 + environment: firefox-add-ons + permissions: + contents: read + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + sparse-checkout: tools/publish + - uses: actions/setup-node@v7 + with: + node-version-file: .nvmrc + - run: npm ci --ignore-scripts --prefix tools/publish + - uses: actions/download-artifact@v8 + with: + name: release-${{ github.ref_name }} + path: dist + - name: Check the files against the published checksums + working-directory: dist + run: sha256sum -c --ignore-missing SHA256SUMS.txt + - name: Submit + env: + FIREFOX_EXTENSION_ID: ${{ secrets.FIREFOX_EXTENSION_ID }} + FIREFOX_JWT_ISSUER: ${{ secrets.FIREFOX_JWT_ISSUER }} + FIREFOX_JWT_SECRET: ${{ secrets.FIREFOX_JWT_SECRET }} + FIREFOX_CHANNEL: listed + # Desktop only: Firefox for Android has no bookmarks API (docs/08 §9). + FIREFOX_COMPATIBILITY: firefox + run: | + set -euo pipefail + VERSION="${GITHUB_REF_NAME#v}" + ./tools/publish/node_modules/.bin/publish-extension \ + --firefox-zip "dist/bookmarkmagic-${VERSION}-firefox.zip" \ + --firefox-sources-zip "dist/bookmarkmagic-${VERSION}-sources.zip" + + store-edge: + name: Publish to Microsoft Edge Add-ons + needs: publish + if: vars.EDGE_AUTOPUBLISH == 'true' + runs-on: ubuntu-latest + timeout-minutes: 30 + environment: edge-add-ons + permissions: + contents: read + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + sparse-checkout: tools/publish + - uses: actions/setup-node@v7 + with: + node-version-file: .nvmrc + - run: npm ci --ignore-scripts --prefix tools/publish + - uses: actions/download-artifact@v8 + with: + name: release-${{ github.ref_name }} + path: dist + - name: Check the file against the published checksums + working-directory: dist + run: sha256sum -c --ignore-missing SHA256SUMS.txt + - name: Submit + env: + # API v1.1 keys expire every 72 days (docs/12 §3). + EDGE_PRODUCT_ID: ${{ secrets.EDGE_PRODUCT_ID }} + EDGE_CLIENT_ID: ${{ secrets.EDGE_CLIENT_ID }} + EDGE_API_KEY: ${{ secrets.EDGE_API_KEY }} + run: | + set -euo pipefail + # Edge Add-ons takes the Chromium package unchanged (docs/08 §10). + ./tools/publish/node_modules/.bin/publish-extension \ + --edge-zip "dist/bookmarkmagic-${GITHUB_REF_NAME#v}-chrome.zip" # A job INSIDE this workflow, not an `on: release: [published]` caller. # A Release created by `gh release create` under the default GITHUB_TOKEN @@ -172,7 +280,7 @@ jobs: # `on: push: tags` — so without this the job exits 1 and never announces. tag_override: ${{ github.ref_name }} # Named, not `inherit`: the reusable is pinned to a moving branch, so it gets - # only the two webhooks it reads — never the CHROME_* or SONAR secrets. The + # only the two webhooks it reads — never the store or SONAR secrets. The # names also differ: this repo stores RELEASES_WEBHOOK / REPO_WEBHOOK, while # the reusable reads DISCORD_* — with `inherit` it received neither and would # have failed on "No webhooks configured" the day DISCORD_ANNOUNCE was set. diff --git a/docs/09_SECURITY_PRIVACY.md b/docs/09_SECURITY_PRIVACY.md index d053abe..5e790e8 100644 --- a/docs/09_SECURITY_PRIVACY.md +++ b/docs/09_SECURITY_PRIVACY.md @@ -156,7 +156,10 @@ enters the tree through a reviewed change to the lists — or one `EXCEPTIONS` entry with its reason and a `15` decision-log row — never unnoticed inside a Dependabot bump. The gate trusts each package's own declaration, as any lockfile-based check must, and needs neither `node_modules` nor the network. -It runs in `verify`, in CI's `quality` job and in the release build. +It runs in `verify`, in CI's `quality` job and in the release build, over the +root lockfile and, since v1.3.0, `tools/publish/package-lock.json` — the +store-upload tool, which ships nothing, so it is held to the toolchain list +(`12 §3`). Considered and not used: `actions/dependency-review-action`. It sees only what a pull request changes, reads licences from ClearlyDefined rather than diff --git a/docs/12_CI_CD.md b/docs/12_CI_CD.md index 5b9ca82..08cd49b 100644 --- a/docs/12_CI_CD.md +++ b/docs/12_CI_CD.md @@ -420,7 +420,8 @@ means "unknown", not "not done". posts. Unset means skipped; a reusable-workflow caller cannot use `continue-on-error` to absorb a failure (§2.3). - [x] Dependabot: npm weekly, grouped dev minor+patch, `github-actions` too — - `.github/dependabot.yml`. Both ecosystems have a 7-day `cooldown` + `.github/dependabot.yml` — and since v1.3.0 `tools/publish/` (the + store-upload tool's own lockfile, §3) as a third ecosystem entry. Both ecosystems have a 7-day `cooldown` (matching `.npmrc` `min-release-age=7`, `09 §3.1`); WXT is excluded from the group so every WXT bump arrives alone and gets its built-manifest diff; majors of the TypeScript pair and `@types/node` are ignored. diff --git a/qodana.yaml b/qodana.yaml index a33b828..dc5651c 100644 --- a/qodana.yaml +++ b/qodana.yaml @@ -40,3 +40,10 @@ exclude: - name: DuplicatedCode paths: - src/styles/tokens.css + +# Clean since 2026-11-18 (docs/12 §2.7): any new finding turns this workflow +# red, so it is fixed or switched off here with its reason — never left +# standing to be ignored. Not a required check. +failureConditions: + severityThresholds: + any: 0 diff --git a/scripts/check-licenses.d.mts b/scripts/check-licenses.d.mts index 51ba106..bb519fa 100644 --- a/scripts/check-licenses.d.mts +++ b/scripts/check-licenses.d.mts @@ -7,7 +7,10 @@ export const TOOLCHAIN_LICENSES: readonly string[]; export const EXCEPTIONS: Readonly>; export function satisfies(expression: string, allowed: readonly string[]): boolean; export function packageNameOf(key: string): string; -export function checkLockfile(lock: unknown): { +export function checkLockfile( + lock: unknown, + options?: { shipsCode?: boolean }, +): { problems: string[]; checked: number; counts: Map; diff --git a/scripts/check-licenses.mjs b/scripts/check-licenses.mjs index 9508b1d..1308b12 100644 --- a/scripts/check-licenses.mjs +++ b/scripts/check-licenses.mjs @@ -24,7 +24,8 @@ * npm; this gate trusts it, as every lockfile-based checker must. It needs no * `node_modules` and no network, so it runs before anything is installed. * - * Usage: node scripts/check-licenses.mjs — reads /package-lock.json, + * Usage: node scripts/check-licenses.mjs — reads /package-lock.json and + * /tools/publish/package-lock.json (the store-upload tool, docs/12 §3), * resolved from this file. Its tests call `checkLockfile(lock)` directly. */ import { readFileSync } from 'node:fs'; @@ -142,10 +143,14 @@ function printable(value) { /** * Check every installed package of a v2/v3 lockfile. * - * @param {unknown} lock — the parsed `package-lock.json` + * @param {unknown} lock - the parsed `package-lock.json` + * @param {{ shipsCode?: boolean }} [options] - `shipsCode: false` for a lockfile + * that builds nothing into the extension (tools/publish), where the credited + * packages are not expected * @returns {{ problems: string[], checked: number, counts: Map }} */ -export function checkLockfile(lock) { +export function checkLockfile(lock, options = {}) { + const shipsCode = options.shipsCode ?? true; /** @type {string[]} */ const problems = []; /** @type {Map} */ @@ -181,7 +186,7 @@ export function checkLockfile(lock) { } } - for (const name of CREDITED_PACKAGES) { + for (const name of shipsCode ? CREDITED_PACKAGES : []) { if (!shippedSeen.has(name)) { problems.push(`${printable(name)}: credited as shipping, but not in the lockfile`); } @@ -189,18 +194,34 @@ export function checkLockfile(lock) { return { problems, checked, counts }; } +/** The lockfiles this repository installs from, and whether each builds the extension. */ +const LOCKFILES = [ + { path: 'package-lock.json', shipsCode: true }, + { path: 'tools/publish/package-lock.json', shipsCode: false }, +]; + /** @returns {number} exit code */ function main() { - const lockPath = resolve(fileURLToPath(import.meta.url), '..', '..', 'package-lock.json'); - /** @type {unknown} */ - let lock; - try { - lock = JSON.parse(readFileSync(lockPath, 'utf8')); - } catch (cause) { - console.error(`::error::check-licenses: cannot read package-lock.json (${String(cause)})`); - return 1; + const repo = resolve(fileURLToPath(import.meta.url), '..', '..'); + /** @type {string[]} */ + const problems = []; + let checked = 0; + /** @type {Map} */ + const counts = new Map(); + for (const { path, shipsCode } of LOCKFILES) { + /** @type {unknown} */ + let lock; + try { + lock = JSON.parse(readFileSync(resolve(repo, path), 'utf8')); + } catch (cause) { + console.error(`::error::check-licenses: cannot read ${path} (${String(cause)})`); + return 1; + } + const result = checkLockfile(lock, { shipsCode }); + for (const problem of result.problems) problems.push(`${path}: ${problem}`); + checked += result.checked; + for (const [license, n] of result.counts) counts.set(license, (counts.get(license) ?? 0) + n); } - const { problems, checked, counts } = checkLockfile(lock); if (problems.length > 0) { for (const problem of problems) console.error(`::error::check-licenses: ${problem}`); console.error( diff --git a/tests/unit/scripts/check-licenses.test.ts b/tests/unit/scripts/check-licenses.test.ts index 92a98b3..2e9ac9e 100644 --- a/tests/unit/scripts/check-licenses.test.ts +++ b/tests/unit/scripts/check-licenses.test.ts @@ -134,6 +134,19 @@ describe('checkLockfile', () => { ]); }); + it('expects no credited package in a lockfile that ships nothing (tools/publish)', () => { + const tools = { lockfileVersion: 3, packages: { 'node_modules/cac': { license: 'MIT' } } }; + expect(checkLockfile(tools, { shipsCode: false }).problems).toEqual([]); + expect(checkLockfile(tools).problems).toHaveLength(4); + }); + + it('passes the publish tool lockfile', () => { + const lock: unknown = JSON.parse( + readFileSync(join(process.cwd(), 'tools/publish/package-lock.json'), 'utf8'), + ); + expect(checkLockfile(lock, { shipsCode: false }).problems).toEqual([]); + }); + it('skips the root project and workspace links', () => { const lock = lockWith({ 'packages/local': { link: true }, diff --git a/tools/publish/.npmrc b/tools/publish/.npmrc new file mode 100644 index 0000000..50c6670 --- /dev/null +++ b/tools/publish/.npmrc @@ -0,0 +1,6 @@ +# Supply-chain cooldown (docs/01 §6): resolve every install to the newest +# release that has been public for at least 7 days. Malicious versions +# published to npm have historically been caught and pulled within hours to +# days; a week of age keeps this repo out of that window. Units are DAYS. +# Dependabot applies the same rule through `cooldown` in dependabot.yml. +min-release-age=7 diff --git a/tools/publish/package-lock.json b/tools/publish/package-lock.json new file mode 100644 index 0000000..0120859 --- /dev/null +++ b/tools/publish/package-lock.json @@ -0,0 +1,62 @@ +{ + "name": "bookmarkmagic-publish", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "bookmarkmagic-publish", + "license": "GPL-3.0-or-later", + "devDependencies": { + "publish-browser-extension": "6.2.0" + } + }, + "node_modules/@topcli/prompts": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/@topcli/prompts/-/prompts-4.0.0.tgz", + "integrity": "sha512-kkKYPb4k/6kRdnESt77B5vJrrYnYHIYczwv0P1c+tfN/IWEx3KZeKEHoUq7sImIyBEXWdA2uakIroD9pmRJziQ==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=22.0.0" + } + }, + "node_modules/cac": { + "version": "7.1.0", + "resolved": "https://registry.npmjs.org/cac/-/cac-7.1.0.tgz", + "integrity": "sha512-LMDU/U2yA4IPIY8KT0NsNPWEYZvAMkbgyspxJ6btJaYV+WMDOHAZCmB0lsTObiHaRS1V/ztKAl7+TSkTqXyeoA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=20.19.0" + } + }, + "node_modules/publish-browser-extension": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/publish-browser-extension/-/publish-browser-extension-6.2.0.tgz", + "integrity": "sha512-yIxoJ54RdTqyfdLrc+8mswCmEeh9x/03JrtF8Ney8zjzKplKgg4fdTs3hRP33IcWImak98yAHSI8ZBVAflsDNg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@topcli/prompts": "^4.0.0", + "cac": "^7.0.0", + "tasuku": "^2.3.0" + }, + "bin": { + "publish-extension": "bin/publish-extension.mjs" + }, + "engines": { + "node": ">=22.0.0" + } + }, + "node_modules/tasuku": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/tasuku/-/tasuku-2.3.0.tgz", + "integrity": "sha512-9Jtk+XAnttslCw4i9RceSZGr2PT5TLn0vUyWnoP2SdlSYzkiYRY6kB5qnPi5IQ/Em8e4oBow1rpaA39iijTIrA==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/privatenumber/tasuku?sponsor=1" + } + } + } +} diff --git a/tools/publish/package.json b/tools/publish/package.json new file mode 100644 index 0000000..a1f38b5 --- /dev/null +++ b/tools/publish/package.json @@ -0,0 +1,9 @@ +{ + "name": "bookmarkmagic-publish", + "private": true, + "description": "The store-upload tool release.yml runs, installed apart from the dev toolchain so store credentials share a runner with four packages instead of three hundred (docs/12 §3).", + "license": "GPL-3.0-or-later", + "devDependencies": { + "publish-browser-extension": "6.2.0" + } +}