Build script and document updates (#14)

Author: snipsnipsnip

.github/workflows/release.yml

@@ -11,6 +11,8 @@ jobs:
       contents: write
     steps:
     - uses: actions/checkout@v5
+      with:
+        fetch-depth: 0
 
     - name: Setup Node.js
       uses: actions/setup-node@v5
@@ -40,8 +42,6 @@ jobs:
     - name: Build
       run: corepack yarn build
 
-    - name: Create Release
-      uses: softprops/action-gh-release@v2
-      with:
-        files: dist/*.xpi
-        generate_release_notes: true
+    - run: npx changelogithub@13.16.0 --assets 'dist/*.xpi'
+      env:
+        GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.gitignore

@@ -3,6 +3,7 @@ build/
 .vscode/
 .zed/
 .web-ext-config.mjs
+manifest.json
 
 # Logs
 logs

.web-ext-config.example.mjs

@@ -7,5 +7,6 @@ export default {
     firefox: "/usr/bin/thunderbird",
     firefoxProfile: "/home/your/.config/your-testing-thunderbird-profile",
     profileCreateIfMissing: true,
+    // keepProfileChanges: true,
   },
 };

README.md

@@ -47,7 +47,7 @@ Basically `yarn && yarn build`. See [CONTRIBUTING.md](./CONTRIBUTING.md) to get
 
 1. Launch your favorite text editor.
 2. Start GhostText server in your text editor (e.g. with `:GhostTextStart` in Vim).
-3. Press the gray Ghostbird button <img src="./ext/gray.svg" width="24" height="24" border="1"> in the Thunderbird mail compose window. (The default shortcut is `Ctrl-E`)
+3. Press the gray Ghostbird button <img src="./ext/gray.svg" width="24" height="24" border="1"> in the Thunderbird mail compose window. (The default shortcut is <kbd>Ctrl</kbd>+<kbd>E</kbd>)
    * If the connection is successful, the button will turn blue <img src="./ext/blue.svg" width="24" height="24" border="1">.
    * If the connection fails, the button will turn red <img src="./ext/red.svg" width="24" height="24" border="1">. Make sure that the GhostText server is listening. See [Troubleshooting page of original GhostText](https://ghosttext.fregante.com/troubleshooting/#unable-to-connect).
 4. Write your email in the text editor.
@@ -157,8 +157,8 @@ If you liked the idea, please:
 We need help with:
 
 * [Website](https://exteditor.github.io/ghostbird/) and materials (Please post [screenshots to the wiki](https://github.com/exteditor/ghostbird/wiki/Screenshots))
-* [Testing with various text editors](https://github.com/exteditor/ghostbird/wiki/Text_editors_known_to_work_with)
-* [Testing with various OSes](https://github.com/exteditor/ghostbird/wiki/OSes_known_to_work_with)
+* [Testing with various text editors](https://github.com/exteditor/ghostbird/wiki/TextEditorsKnownToWorkWith)
+* [Testing with various OSes](https://github.com/exteditor/ghostbird/wiki/OSesKnownToWorkWith)
 * Wiki pages for [user guides](https://github.com/exteditor/ghostbird/wiki/HowTo) and [troubleshooting](https://github.com/exteditor/ghostbird/wiki/Troubleshooting)
 * Developing the server counterpart so that this can be used as an External Editor replacement ([GhostText-Any](https://github.com/newsch/GhostText-Any/) or [Helix-Ghost][helix] can be a good starting point)
 * Creating a testing checklist for testing and debugging ([This page](https://github.com/exteditor/exteditor/wiki/Things-to-test) can be a good starting point)

doc/faq.md

@@ -20,7 +20,7 @@
 ### What text editors are supported?
 
 * See [Requirements section in README.md](../README.md#requirements), but it isn't the official list. If your favorite editor isn't listed, try searching for it.
-* If you tried the add-on, please add your text editor to [the wiki page](https://github.com/exteditor/ghostbird/wiki/Text_editors_known_to_work_with).
+* If you tried the add-on, please add your favorite text editor to [the wiki page](https://github.com/exteditor/ghostbird/wiki/TextEditorsKnownToWorkWith) if it's not there.
 
 ### How do I install it?
 
@@ -53,7 +53,7 @@
     <img width="400" height="194" title="profile-wide email format config" alt="profile-wide email format config" src="https://github.com/user-attachments/assets/cbbe7494-1cce-4da8-944f-f5b99d925de4" />
 
   * You can set per-account option at `Account Setting`>`Composition & Addressing`>`Composition` section. Check or uncheck the `Compose messages in HTML format` checkbox.
- 
+
     <img width="400" height="184" alt="per-account email format config" title="per-account email format config" src="https://github.com/user-attachments/assets/9305cec5-dc83-4893-8128-bdbaadaa9f6f" />
 
 * After adjusting the option, you have to start a `New Message`.

package.json

@@ -64,7 +64,7 @@
     "git-describe": "^4.1.1",
     "jsdom": "^26.1.0",
     "rolldown": "latest",
-    "tsdown": "^0.14.1",
+    "tsdown": "^0.15.1",
     "typedoc": "^0.28.12",
     "typedoc-plugin-markdown": "^4.8.1",
     "typedoc-plugin-mermaid": "^1.12.0",
@@ -75,5 +75,10 @@
   },
   "peerDependencies": {
     "@vitest/ui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@vitest/ui": {
+      "optional": true
+    }
   }
 }

tools/generate_manifest.ts

@@ -3,18 +3,28 @@ import type { EmittedAsset, Plugin } from "rolldown"
 import manifest from "../manifest_template.json" with { type: "json" }
 import pkg from "../package.json" with { type: "json" }
 
-type VersionInfo = { version: string; envInfo: Record<string, string> | undefined }
+type VersionInfo = { version: string }
 
 export type Options = { env?: undefined | Record<string, string> }
 
 /** Generates manifest.json from the template file */
 export const generateManifest = ({ env }: Options = {}): Plugin => ({
   name: "generate_manifest",
   async generateBundle(): Promise<void> {
+    // manifest.json can be reused for reproducibility
+    let existing = await this.resolve("./ext/manifest.json")
+    if (existing) {
+      this.info(`manifest.json already exists; skipping generation`)
+      return
+    }
+
     this.info("Generating manifest.json")
-    let { version, envInfo } = await getVersionInfo(env ?? {}).catch((e) => {
+    let { version } = await getVersionInfo(env).catch((e) => {
       this.warn(e)
-      return { version: "unknown", envInfo: undefined }
+      this.warn(
+        "Generating dummy version; Build from a Git clone or place your ext/manifest.json to use the real one instead",
+      )
+      return { version: `unknown-${Date.now()}-try-placing-your-manifest-json-in-ext-directory-before-build` }
     })
     let manifest = makeManifestJson(version)
 
@@ -24,14 +34,6 @@ export const generateManifest = ({ env }: Options = {}): Plugin => ({
       originalFileName: "manifest_template.json",
       source: manifest,
     } satisfies EmittedAsset)
-
-    if (envInfo) {
-      this.emitFile({
-        type: "asset",
-        fileName: "env.yarn",
-        source: listEnv(envInfo),
-      } satisfies EmittedAsset)
-    }
   },
 })
 
@@ -47,43 +49,33 @@ function makeManifestJson(version: string): string {
   return JSON.stringify(contents, undefined, 2)
 }
 
-async function getVersionInfo(envInfo: Record<string, string>): Promise<VersionInfo> {
-  let { GITHUB_REF_NAME: refName, GITHUB_SHA: sha, GITHUB_REF_TYPE: refType } = envInfo
+async function getVersionInfo(envInfo: undefined | Record<string, string>): Promise<VersionInfo> {
+  let { GITHUB_REF_NAME: refName, GITHUB_SHA: sha, GITHUB_REF_TYPE: refType } = envInfo ?? {}
 
   // Use version info from env if available
   if (refName && sha && refType) {
     if (refType === "tag" && refName.startsWith("v")) {
       // this is a release build
-      return { version: refName.slice(1), envInfo }
+      let version = appendSha(refName.slice(1), sha)
+      return { version }
     } else {
       // this is a nightly build
-      return { version: `nightly-${refName}-${sha}`, envInfo }
+      return { version: `nightly-${refName}-${sha}` }
     }
   }
 
   // Query git for local build
-  let { semverString } = await gitDescribe({
+  let { semverString, hash, distance } = await gitDescribe({
     customArguments: ["--abbrev=16"],
   })
   if (!semverString) {
     throw Error("couldn't get the version from git")
   }
-  return { version: semverString, envInfo: undefined }
+  let version = distance === 0 ? appendSha(semverString, hash.slice(1)) : semverString
+
+  return { version }
 }
 
-function listEnv(envInfo: Record<string, string>): string {
-  let keys = new Set([
-    "CI",
-    "GITHUB_REF_NAME",
-    "GITHUB_SHA",
-    "GITHUB_REF_TYPE",
-    "GITHUB_SERVER_URL",
-    "GITHUB_REPOSITORY",
-    "GITHUB_RUN_ID",
-  ])
-  return Object.entries(envInfo)
-    .filter((pair) => keys.has(pair[0]))
-    .sort()
-    .map((pair) => pair.join("="))
-    .join("\n")
+function appendSha(version: string, sha: string): string {
+  return `${version}.${parseInt(sha.slice(0, 7), 16)}`
 }

tools/tsdown_config.ts

@@ -18,7 +18,7 @@
  */
 
 import { existsSync } from "node:fs"
-import { dirname, resolve } from "node:path"
+import { dirname, join, resolve } from "node:path"
 import { env } from "node:process"
 import type { Options, UserConfig } from "tsdown"
 import { barrelsby } from "./barrelsby"
@@ -33,23 +33,19 @@ export default (): UserConfig => {
   ]
 }
 
-const isRelease = env.CI === "true"
+const isRelease = env.CI === "true" || existsSync(join(__dirname, "..", "ext", "manifest.json"))
 
 const commonConfig = {
   outDir: "dist/ext/",
   tsconfig: "src/root/tsconfig.json",
   ignoreWatch: [/[/](?:[.]|build[/]|dist[/])/i, /index[.]ts$/i],
   platform: "browser",
-  // Corresponds to Thunderbird 128 ESR
-  target: "firefox128",
+  // Corresponds to Thunderbird 140 ESR
+  target: "firefox140",
   sourcemap: true,
   // We don't remove whitespaces for people like me who enjoy unpacking xpis and reading the content.
   // We still bundle because it reduces the number of files to check.
-  minify: {
-    compress: false,
-    mangle: false,
-    removeWhitespace: false,
-  },
+  minify: "dce-only",
   define: {
     // Remove in-source tests
     "import.meta.vitest": "undefined",