330 lines
11 KiB
Markdown
330 lines
11 KiB
Markdown
# GitHub Firefox Updates Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Publish signed Firefox XPI releases to GitHub Releases and let installed alpha extensions discover them through a GitHub-hosted update manifest.
|
|
|
|
**Architecture:** Firefox keeps one immutable `update_url` targeting the current GitHub Release's `updates.json` asset. A small Node helper owns the tag, asset URL and update-manifest formatting so it has focused unit tests. The existing local signing command remains local; an explicit publishing command uploads its two artifacts to the public GitHub release.
|
|
|
|
**Tech Stack:** Manifest V2 JSON, Node.js CommonJS tests, Bash, `web-ext`, GitHub CLI (`gh`).
|
|
|
|
## Global Constraints
|
|
|
|
- Publish repository: `mirivlad/verstak-browser-extension`.
|
|
- Firefox addon ID: `verstak-bridge@verstak.app`.
|
|
- Initial GitHub release: `v2.0.2`; package and both browser manifests are version `2.0.2`.
|
|
- Every alpha GitHub release is ordinary/latest, not a prerelease.
|
|
- XPI remains Mozilla-signed as an unlisted/self-distributed addon before upload.
|
|
- `npm run release:firefox` remains a local sign-and-package action.
|
|
- `npm run publish:firefox` is the only command allowed to create or modify a GitHub Release.
|
|
- Generated `release/` output remains untracked.
|
|
|
|
---
|
|
|
|
### Task 1: Make GitHub update metadata testable
|
|
|
|
**Files:**
|
|
- Create: `scripts/firefox-github-release.js`
|
|
- Create: `scripts/test-firefox-github-release.js`
|
|
- Modify: `package.json:8-15`
|
|
|
|
**Interfaces:**
|
|
- Produces `releaseTag(version)`, `releaseAssetURL(version, assetName)`, and `updateManifest(addonID, version, assetName)` from `scripts/firefox-github-release.js`.
|
|
- `updateManifest` returns the object written as `updates.json` and uses the fixed GitHub repository.
|
|
- Later shell scripts invoke `node scripts/firefox-github-release.js write-updates <addon-id> <version> <asset-name> <output-path>`.
|
|
|
|
- [ ] **Step 1: Write the failing metadata test**
|
|
|
|
Create `scripts/test-firefox-github-release.js` with:
|
|
|
|
```js
|
|
const assert = require('assert');
|
|
const release = require('./firefox-github-release');
|
|
|
|
const version = '2.0.2';
|
|
const asset = 'verstak-firefox-2.0.2.xpi';
|
|
assert.equal(release.releaseTag(version), 'v2.0.2');
|
|
assert.equal(
|
|
release.releaseAssetURL(version, asset),
|
|
'https://github.com/mirivlad/verstak-browser-extension/releases/download/v2.0.2/verstak-firefox-2.0.2.xpi',
|
|
);
|
|
assert.deepEqual(release.updateManifest('verstak-bridge@verstak.app', version, asset), {
|
|
addons: {
|
|
'verstak-bridge@verstak.app': {
|
|
updates: [{
|
|
version: '2.0.2',
|
|
update_link: 'https://github.com/mirivlad/verstak-browser-extension/releases/download/v2.0.2/verstak-firefox-2.0.2.xpi',
|
|
}],
|
|
},
|
|
},
|
|
});
|
|
console.log('Firefox GitHub release metadata tests passed');
|
|
```
|
|
|
|
- [ ] **Step 2: Run the focused test and verify it fails**
|
|
|
|
Run: `node scripts/test-firefox-github-release.js`
|
|
|
|
Expected: failure because `scripts/firefox-github-release.js` does not yet exist.
|
|
|
|
- [ ] **Step 3: Implement the metadata helper**
|
|
|
|
Create `scripts/firefox-github-release.js` with these exact exports and CLI:
|
|
|
|
```js
|
|
const fs = require('fs');
|
|
const REPOSITORY = 'mirivlad/verstak-browser-extension';
|
|
|
|
function releaseTag(version) { return `v${version}`; }
|
|
function releaseAssetURL(version, assetName) {
|
|
return `https://github.com/${REPOSITORY}/releases/download/${releaseTag(version)}/${assetName}`;
|
|
}
|
|
function updateManifest(addonID, version, assetName) {
|
|
return { addons: { [addonID]: { updates: [{ version, update_link: releaseAssetURL(version, assetName) }] } } };
|
|
}
|
|
|
|
if (require.main === module) {
|
|
const [, , command, addonID, version, assetName, outputPath] = process.argv;
|
|
if (command !== 'write-updates' || !addonID || !version || !assetName || !outputPath) process.exitCode = 2;
|
|
else fs.writeFileSync(outputPath, `${JSON.stringify(updateManifest(addonID, version, assetName), null, 2)}\n`);
|
|
}
|
|
|
|
module.exports = { REPOSITORY, releaseTag, releaseAssetURL, updateManifest };
|
|
```
|
|
|
|
- [ ] **Step 4: Register and run the test**
|
|
|
|
Append `node scripts/test-firefox-github-release.js` to the existing `test`
|
|
script in `package.json`, then run:
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
Expected: all existing tests and `Firefox GitHub release metadata tests passed`.
|
|
|
|
- [ ] **Step 5: Commit and push**
|
|
|
|
```bash
|
|
git add package.json scripts/firefox-github-release.js scripts/test-firefox-github-release.js
|
|
git commit -m "test: cover Firefox GitHub release metadata"
|
|
git push origin main
|
|
```
|
|
|
|
### Task 2: Point Firefox and local release artifacts at GitHub
|
|
|
|
**Files:**
|
|
- Modify: `firefox/manifest.json:8-17`
|
|
- Modify: `scripts/release-firefox-xpi.sh:29-70`
|
|
- Test: `scripts/test-firefox-github-release.js`
|
|
|
|
**Interfaces:**
|
|
- Firefox reads `https://github.com/mirivlad/verstak-browser-extension/releases/latest/download/updates.json`.
|
|
- `release-firefox-xpi.sh` invokes the Task 1 helper to write a versioned update manifest.
|
|
- It continues producing `release/firefox/verstak-firefox-<version>.xpi` and `release/firefox/updates.json` locally.
|
|
|
|
- [ ] **Step 1: Extend the failing test with the stable manifest URL**
|
|
|
|
Add this assertion to `scripts/test-firefox-github-release.js` before its final
|
|
success message:
|
|
|
|
```js
|
|
const firefoxManifest = require('../firefox/manifest.json');
|
|
assert.equal(
|
|
firefoxManifest.browser_specific_settings.gecko.update_url,
|
|
'https://github.com/mirivlad/verstak-browser-extension/releases/latest/download/updates.json',
|
|
);
|
|
```
|
|
|
|
- [ ] **Step 2: Run the focused test and verify it fails**
|
|
|
|
Run: `node scripts/test-firefox-github-release.js`
|
|
|
|
Expected: assertion failure because the manifest still uses `mirv.top`.
|
|
|
|
- [ ] **Step 3: Replace the update endpoint and JSON writer**
|
|
|
|
In `firefox/manifest.json`, replace only the Gecko `update_url` value with:
|
|
|
|
```json
|
|
"update_url": "https://github.com/mirivlad/verstak-browser-extension/releases/latest/download/updates.json"
|
|
```
|
|
|
|
In `scripts/release-firefox-xpi.sh`, remove `UPDATE_BASE_URL` and replace the
|
|
heredoc that writes `updates.json` with:
|
|
|
|
```bash
|
|
node scripts/firefox-github-release.js write-updates \
|
|
"$ADDON_ID" "$VERSION" "$RELEASE_XPI" "$RELEASE_DIR/updates.json"
|
|
```
|
|
|
|
- [ ] **Step 4: Run targeted checks**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
node scripts/test-firefox-github-release.js
|
|
bash -n scripts/release-firefox-xpi.sh
|
|
npm test
|
|
npm run build
|
|
```
|
|
|
|
Expected: all commands succeed; `dist/firefox/manifest.json` contains the
|
|
GitHub update URL after the build.
|
|
|
|
- [ ] **Step 5: Commit and push**
|
|
|
|
```bash
|
|
git add firefox/manifest.json scripts/release-firefox-xpi.sh scripts/test-firefox-github-release.js
|
|
git commit -m "feat: host Firefox updates on GitHub Releases"
|
|
git push origin main
|
|
```
|
|
|
|
### Task 3: Add explicit GitHub publishing and public instructions
|
|
|
|
**Files:**
|
|
- Create: `scripts/publish-firefox-github-release.sh`
|
|
- Modify: `package.json:8-15`
|
|
- Modify: `README.md:42-68`
|
|
- Test: `scripts/publish-firefox-github-release.sh`
|
|
|
|
**Interfaces:**
|
|
- `npm run publish:firefox` calls `scripts/publish-firefox-github-release.sh`.
|
|
- The script runs the existing local release command, then uploads
|
|
`verstak-firefox-<version>.xpi` and `updates.json` to release tag
|
|
`v<version>` in `mirivlad/verstak-browser-extension`.
|
|
- A pre-existing tag receives asset replacement through `gh release upload --clobber`.
|
|
|
|
- [ ] **Step 1: Write the shell-contract test**
|
|
|
|
Create a Node test that reads the publish script and asserts the mandatory
|
|
commands are present:
|
|
|
|
```js
|
|
const assert = require('assert');
|
|
const fs = require('fs');
|
|
const source = fs.readFileSync('scripts/publish-firefox-github-release.sh', 'utf8');
|
|
assert.match(source, /gh auth status/);
|
|
assert.match(source, /gh release create/);
|
|
assert.match(source, /gh release upload/);
|
|
assert.match(source, /--clobber/);
|
|
assert.match(source, /--latest/);
|
|
```
|
|
|
|
Place those assertions in `scripts/test-firefox-github-release.js` and run the
|
|
test. Expected: it fails before the publish script exists.
|
|
|
|
- [ ] **Step 2: Implement an explicit idempotent publisher**
|
|
|
|
Create `scripts/publish-firefox-github-release.sh` with this behavior:
|
|
|
|
1. Set `ROOT_DIR`, `cd` to it and run `gh auth status`.
|
|
2. Run `./scripts/release-firefox-xpi.sh`.
|
|
3. Read `VERSION` from `dist/firefox/manifest.json`, set `TAG="v${VERSION}"`,
|
|
`REPOSITORY="mirivlad/verstak-browser-extension"`, and locate the two local
|
|
release assets by exact names.
|
|
4. Run `gh release view "$TAG" --repo "$REPOSITORY"`; when it is absent, run
|
|
`gh release create "$TAG" "$XPI" "$UPDATES" --repo "$REPOSITORY" --title
|
|
"Verstak Browser Extension $VERSION" --generate-notes --latest --target
|
|
"$(git rev-parse HEAD)"`.
|
|
5. When the release already exists, run `gh release upload "$TAG" "$XPI"
|
|
"$UPDATES" --repo "$REPOSITORY" --clobber`.
|
|
6. Print the GitHub release URL with `gh release view "$TAG" --repo
|
|
"$REPOSITORY" --json url --jq .url`.
|
|
|
|
- [ ] **Step 3: Register the command and document it**
|
|
|
|
Add to `package.json`:
|
|
|
|
```json
|
|
"publish:firefox": "./scripts/publish-firefox-github-release.sh"
|
|
```
|
|
|
|
Rewrite the Firefox Release README section so it documents:
|
|
|
|
- the public [GitHub Releases](https://github.com/mirivlad/verstak-browser-extension/releases) page;
|
|
- `VERSTAK_BROWSER_ENV=/path/to/.env npm run publish:firefox`;
|
|
- that signing remains unlisted with Mozilla but distribution and automatic
|
|
updates use GitHub Release assets;
|
|
- that the first `v2.0.2` publish bootstraps the `latest/download/updates.json`
|
|
endpoint.
|
|
|
|
- [ ] **Step 4: Run checks without publishing**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
bash -n scripts/publish-firefox-github-release.sh
|
|
node scripts/test-firefox-github-release.js
|
|
npm test
|
|
npm run build
|
|
git diff --check
|
|
```
|
|
|
|
Expected: all commands succeed. Do not invoke `npm run publish:firefox` in this
|
|
task; it creates a public GitHub Release and needs available AMO credentials.
|
|
|
|
- [ ] **Step 5: Commit and push**
|
|
|
|
```bash
|
|
git add README.md package.json scripts/publish-firefox-github-release.sh scripts/test-firefox-github-release.js
|
|
git commit -m "feat: publish Firefox releases to GitHub"
|
|
git push origin main
|
|
```
|
|
|
|
### Task 4: Bootstrap and verify the first public update release
|
|
|
|
**Files:**
|
|
- Generated: `release/firefox/verstak-firefox-2.0.2.xpi` (untracked)
|
|
- Generated: `release/firefox/updates.json` (untracked)
|
|
|
|
**Interfaces:**
|
|
- Consumes the Task 3 `npm run publish:firefox` command and valid AMO signing credentials.
|
|
- Produces GitHub Release tag `v2.0.2` and public XPI/update-manifest assets.
|
|
|
|
- [ ] **Step 1: Verify release credentials before write operations**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
gh auth status
|
|
test -n "${VERSTAK_BROWSER_ENV:-}" || test -f .env
|
|
```
|
|
|
|
Expected: authenticated GitHub CLI and a configured environment file path for
|
|
the existing AMO signing command.
|
|
|
|
- [ ] **Step 2: Publish the first release**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
npm run publish:firefox
|
|
```
|
|
|
|
Expected: Mozilla signing succeeds, GitHub Release `v2.0.2` is latest, and it
|
|
contains `verstak-firefox-2.0.2.xpi` plus `updates.json`.
|
|
|
|
- [ ] **Step 3: Verify public delivery**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
gh release view v2.0.2 --repo mirivlad/verstak-browser-extension --json isLatest,url,assets
|
|
curl -fsSL https://github.com/mirivlad/verstak-browser-extension/releases/latest/download/updates.json
|
|
```
|
|
|
|
Expected: the release is latest and the JSON contains addon ID
|
|
`verstak-bridge@verstak.app`, version `2.0.2`, and the versioned GitHub XPI
|
|
asset URL.
|
|
|
|
- [ ] **Step 4: Record release verification without committing assets**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
git status --short
|
|
```
|
|
|
|
Expected: no generated `release/` assets are staged or committed.
|