feat: warn when Better Notes is not installed

Add isBetterNotesInstalled() helper and surface a warning notification
on startup plus clear errors during export stating Better Notes is a
requirement. Bump version to 1.0.3.

.gitea/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build

.gitea/workflows/release.yml

@@ -8,6 +8,7 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    if: startsWith(gitea.ref, 'refs/tags/v')
     outputs:
       version: ${{ steps.version.outputs.version }}
       tag: ${{ steps.version.outputs.tag }}
@@ -19,7 +20,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "22"
           cache: "npm"
 
       - name: Install dependencies
@@ -30,18 +31,145 @@ jobs:
 
       - name: Get version
         id: version
+        env:
+          GITEA_REF: ${{ gitea.ref }}
         run: |
-          echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+          echo "version=${GITEA_REF#refs/tags/v}" >> $GITHUB_OUTPUT
-          echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+          echo "tag=${GITEA_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: build-output
+          path: .scaffold/build/
+          retention-days: 1
+
+  update-rolling-release:
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: build-output
+          path: .scaffold/build/
+
+      - name: Upsert rolling 'release' tag with latest update.json
+        env:
+          GITEA_TOKEN: ${{ gitea.token }}
+          API_URL: ${{ gitea.server_url }}/api/v1
+          REPO: ${{ gitea.repository }}
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          set -euo pipefail
+          TAG="release"
+
+          echo "=== Configuration ==="
+          echo "API_URL: ${API_URL}"
+          echo "REPO: ${REPO}"
+          echo "VERSION: ${VERSION}"
+
+          # Check if the rolling release already exists
+          EXISTING=$(curl -s -o /dev/null -w "%{http_code}" \
+            "${API_URL}/repos/${REPO}/releases/tags/${TAG}" \
+            -H "Authorization: token ${GITEA_TOKEN}")
+
+          echo "Existing release check: HTTP ${EXISTING}"
+
+          if [ "${EXISTING}" = "200" ]; then
+            # Fetch the release ID
+            RELEASE_ID=$(curl -s "${API_URL}/repos/${REPO}/releases/tags/${TAG}" \
+              -H "Authorization: token ${GITEA_TOKEN}" \
+              | jq -r '.id')
+
+            echo "Found existing 'release' release (ID: ${RELEASE_ID}). Replacing assets..."
+
+            # Delete all existing assets so we can upload fresh ones
+            ASSETS=$(curl -s "${API_URL}/repos/${REPO}/releases/${RELEASE_ID}/assets" \
+              -H "Authorization: token ${GITEA_TOKEN}")
+            echo "${ASSETS}" | jq -r '.[].id' | while read -r ASSET_ID; do
+              echo "Deleting asset ${ASSET_ID}..."
+              curl -s -X DELETE "${API_URL}/repos/${REPO}/releases/${RELEASE_ID}/assets/${ASSET_ID}" \
+                -H "Authorization: token ${GITEA_TOKEN}"
+            done
+
+            # Update the release body and ensure it stays marked as pre-release
+            curl -s -X PATCH "${API_URL}/repos/${REPO}/releases/${RELEASE_ID}" \
+              -H "Authorization: token ${GITEA_TOKEN}" \
+              -H "Content-Type: application/json" \
+              -d "{\"body\": \"Rolling release — always points to the latest update manifest (currently v${VERSION}). Do not delete.\", \"prerelease\": true}"
+
+          else
+            # Create the rolling release for the first time
+            echo "Creating new 'release' release..."
+
+            # Ensure the tag exists (Gitea requires the tag to exist before creating a release for it)
+            curl -s -X POST "${API_URL}/repos/${REPO}/tags" \
+              -H "Authorization: token ${GITEA_TOKEN}" \
+              -H "Content-Type: application/json" \
+              -d "{\"tag_name\": \"${TAG}\", \"target\": \"main\"}" || true
+
+            RELEASE=$(curl -s -X POST "${API_URL}/repos/${REPO}/releases" \
+              -H "Authorization: token ${GITEA_TOKEN}" \
+              -H "Content-Type: application/json" \
+              -d "{
+                \"tag_name\": \"${TAG}\",
+                \"name\": \"Update Manifest (rolling)\",
+                \"body\": \"Rolling release — always points to the latest update manifest (currently v${VERSION}). Do not delete.\",
+                \"draft\": false,
+                \"prerelease\": true
+              }")
+
+            RELEASE_ID=$(echo "${RELEASE}" | jq -r '.id')
+
+            if [ -z "${RELEASE_ID}" ] || [ "${RELEASE_ID}" = "null" ]; then
+              echo "Failed to create rolling release. Response: ${RELEASE}"
+              exit 1
+            fi
+
+            echo "Created rolling release ID: ${RELEASE_ID}"
+          fi
+
+          # Upload update.json and update-beta.json to the rolling release
+          for JSON in .scaffold/build/update.json .scaffold/build/update-beta.json; do
+            [ -f "${JSON}" ] || continue
+            FILENAME=$(basename "${JSON}")
+            echo "Uploading ${FILENAME} to rolling release..."
+            curl -s -X POST "${API_URL}/repos/${REPO}/releases/${RELEASE_ID}/assets?name=${FILENAME}" \
+              -H "Authorization: token ${GITEA_TOKEN}" \
+              -H "Content-Type: application/json" \
+              --data-binary "@${JSON}"
+          done
+
+          echo "Rolling 'release' release updated to v${VERSION}."
+
+  publish-release:
+    runs-on: ubuntu-latest
+    needs: [build, update-rolling-release]
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: build-output
+          path: .scaffold/build/
 
       - name: Create versioned release and upload assets
         env:
-          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_TOKEN: ${{ gitea.token }}
+          API_URL: ${{ gitea.server_url }}/api/v1
+          REPO: ${{ gitea.repository }}
+          VERSION: ${{ needs.build.outputs.version }}
+          TAG: ${{ needs.build.outputs.tag }}
         run: |
-          VERSION="${{ steps.version.outputs.version }}"
+          set -euo pipefail
-          TAG="${{ steps.version.outputs.tag }}"
+
-          REPO="${GITHUB_REPOSITORY}"
+          echo "=== Configuration ==="
-          API_URL="${GITHUB_SERVER_URL}/api/v1"
+          echo "API_URL: ${API_URL}"
+          echo "REPO: ${REPO}"
+          echo "VERSION: ${VERSION}"
+          echo "TAG: ${TAG}"
 
           # Create the versioned release
           RELEASE=$(curl -s -X POST "${API_URL}/repos/${REPO}/releases" \
@@ -55,9 +183,9 @@ jobs:
               \"prerelease\": false
             }")
 
-          RELEASE_ID=$(echo "${RELEASE}" | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2)
+          RELEASE_ID=$(echo "${RELEASE}" | jq -r '.id')
 
-          if [ -z "${RELEASE_ID}" ]; then
+          if [ -z "${RELEASE_ID}" ] || [ "${RELEASE_ID}" = "null" ]; then
             echo "Failed to create release. Response: ${RELEASE}"
             exit 1
           fi
@@ -87,102 +215,3 @@ jobs:
           done
 
           echo "Versioned release ${TAG} published."
-
-      - name: Upload build artifacts for next job
-        uses: actions/upload-artifact@v4
-        with:
-          name: build-output
-          path: .scaffold/build/
-          retention-days: 1
-
-  update-rolling-release:
-    runs-on: ubuntu-latest
-    needs: build
-
-    steps:
-      - name: Download build artifacts
-        uses: actions/download-artifact@v4
-        with:
-          name: build-output
-          path: .scaffold/build/
-
-      - name: Upsert rolling 'release' tag with latest update.json
-        env:
-          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
-        run: |
-          TAG="release"
-          REPO="${GITHUB_REPOSITORY}"
-          API_URL="${GITHUB_SERVER_URL}/api/v1"
-          VERSION="${{ needs.build.outputs.version }}"
-
-          # Check if the rolling release already exists
-          EXISTING=$(curl -s -o /dev/null -w "%{http_code}" \
-            "${API_URL}/repos/${REPO}/releases/tags/${TAG}" \
-            -H "Authorization: token ${GITEA_TOKEN}")
-
-          if [ "${EXISTING}" = "200" ]; then
-            # Fetch the release ID
-            RELEASE_ID=$(curl -s "${API_URL}/repos/${REPO}/releases/tags/${TAG}" \
-              -H "Authorization: token ${GITEA_TOKEN}" \
-              | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2)
-
-            echo "Found existing 'release' release (ID: ${RELEASE_ID}). Replacing assets..."
-
-            # Delete all existing assets so we can upload fresh ones
-            ASSETS=$(curl -s "${API_URL}/repos/${REPO}/releases/${RELEASE_ID}/assets" \
-              -H "Authorization: token ${GITEA_TOKEN}")
-            echo "${ASSETS}" | grep -o '"id":[0-9]*' | cut -d: -f2 | while read ASSET_ID; do
-              echo "Deleting asset ${ASSET_ID}..."
-              curl -s -X DELETE "${API_URL}/repos/${REPO}/releases/${RELEASE_ID}/assets/${ASSET_ID}" \
-                -H "Authorization: token ${GITEA_TOKEN}"
-            done
-
-            # Update the release body to reflect the current version
-            curl -s -X PATCH "${API_URL}/repos/${REPO}/releases/${RELEASE_ID}" \
-              -H "Authorization: token ${GITEA_TOKEN}" \
-              -H "Content-Type: application/json" \
-              -d "{\"body\": \"Rolling release — always points to the latest update manifest (currently v${VERSION}). Do not delete.\"}"
-
-          else
-            # Create the rolling release for the first time
-            echo "Creating new 'release' release..."
-
-            # Ensure the tag exists (Gitea requires the tag to exist before creating a release for it)
-            curl -s -X POST "${API_URL}/repos/${REPO}/tags" \
-              -H "Authorization: token ${GITEA_TOKEN}" \
-              -H "Content-Type: application/json" \
-              -d "{\"tag_name\": \"${TAG}\", \"message\": \"Rolling release tag for update.json hosting\"}" || true
-
-            RELEASE=$(curl -s -X POST "${API_URL}/repos/${REPO}/releases" \
-              -H "Authorization: token ${GITEA_TOKEN}" \
-              -H "Content-Type: application/json" \
-              -d "{
-                \"tag_name\": \"${TAG}\",
-                \"name\": \"Update Manifest (rolling)\",
-                \"body\": \"Rolling release — always points to the latest update manifest (currently v${VERSION}). Do not delete.\",
-                \"draft\": false,
-                \"prerelease\": false
-              }")
-
-            RELEASE_ID=$(echo "${RELEASE}" | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2)
-
-            if [ -z "${RELEASE_ID}" ]; then
-              echo "Failed to create rolling release. Response: ${RELEASE}"
-              exit 1
-            fi
-
-            echo "Created rolling release ID: ${RELEASE_ID}"
-          fi
-
-          # Upload update.json and update-beta.json to the rolling release
-          for JSON in .scaffold/build/update.json .scaffold/build/update-beta.json; do
-            [ -f "${JSON}" ] || continue
-            FILENAME=$(basename "${JSON}")
-            echo "Uploading ${FILENAME} to rolling release..."
-            curl -s -X POST "${API_URL}/repos/${REPO}/releases/${RELEASE_ID}/assets?name=${FILENAME}" \
-              -H "Authorization: token ${GITEA_TOKEN}" \
-              -H "Content-Type: application/json" \
-              --data-binary "@${JSON}"
-          done
-
-          echo "Rolling 'release' release updated to v${VERSION}."

AGENTS.md

@@ -25,7 +25,7 @@ npm run release           # Bump version, commit, tag, and build
 This project does not currently have automated tests. To test manually:
 
 1. Run `npm run build` to create the XPI
-2. Install the XPI in Zotero 7
+2. Install the XPI in Zotero 7–10
 3. Test export functionality manually via Tools menu
 
 ---

README.md

@@ -12,7 +12,7 @@ Export PDF and EPUB annotations from Zotero to Org-mode files for use with Emacs
 
 ## Requirements
 
-- **[Zotero](https://www.zotero.org/) 7.0+**
+- **[Zotero](https://www.zotero.org/) 7.0+ (through 10.x)**
 - **[Better Notes](https://github.com/windingwind/zotero-better-notes)** plugin — must be installed before this plugin
 - **[Pandoc](https://pandoc.org/)** — for Markdown to Org conversion
 
@@ -89,7 +89,7 @@ src/
     ├── exporter.ts   # Attachment detection, sync checking, batch export
     ├── converter.ts  # Markdown → Org via pandoc, file I/O
     ├── notifier.ts   # Zotero event handlers (sync finish, tab close)
-    └── menu.ts       # Menu registration (Zotero 7 + 8 compatible)
+    └── menu.ts       # Menu registration (Zotero 7 + 8/10 compatible)
 
 addon/                # Static plugin files copied verbatim into the XPI
 ├── manifest.json
@@ -170,7 +170,7 @@ The dev server (`npm start`) watches for changes in `src/` and `addon/`, rebuild
 There are no automated tests. To test manually:
 
 1. `npm run build` to produce the XPI
-2. Install the XPI in a Zotero 7 instance via **Tools → Add-ons → Install Add-on From File...**
+2. Install the XPI in a Zotero 7–10 instance via **Tools → Add-ons → Install Add-on From File...**
 3. Exercise the export functionality manually via the Tools menu and right-click context menu
 
 ### Releasing

addon/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 2,
   "name": "Zotero Org Export Annotations",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Export Zotero PDF/EPUB annotations to Org-mode files for Emacs, org-roam, and citar",
   "author": "Ignacio",
   "homepage_url": "https://gitea.bueso.eu/ignacio.ballesteros/zotero-notes-export-org",
@@ -14,7 +14,7 @@
       "id": "org-export-annotations@zotero.org",
       "update_url": "https://gitea.bueso.eu/ignacio.ballesteros/zotero-notes-export-org/releases/download/release/update.json",
       "strict_min_version": "7.0",
-      "strict_max_version": "8.*"
+      "strict_max_version": "10.0.*"
     }
   }
 }

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "zotero-org-export-annotations",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "zotero-org-export-annotations",
-      "version": "1.0.0",
+      "version": "1.0.3",
       "license": "GPL-3.0-or-later",
       "devDependencies": {
         "@types/node": "^20.11.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "zotero-org-export-annotations",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Export Zotero PDF/EPUB annotations to Org-mode files for Emacs integration",
   "config": {
     "addonName": "Zotero Org Export Annotations",

src/addon.ts

@@ -31,6 +31,10 @@ export class OrgExportAnnotationsAddon {
     this.log(`Initialized version ${this.version}`);
   }
 
+  isBetterNotesInstalled(): boolean {
+    return Boolean(Zotero.BetterNotes?.api?.convert?.note2md);
+  }
+
   log(message: string, ...args: unknown[]): void {
     if (this.data.env === "development" || this.prefs?.debug) {
       Zotero.debug(`[OrgExportAnnotations] ${message}`, false);

src/hooks.ts

@@ -12,14 +12,22 @@ export interface Hooks {
   onMenuExportSelected(): Promise<void>;
 }
 
-function showNotification(message: string): void {
+function showNotification(message: string, headline = "Org Export"): void {
   const pw = new Zotero.ProgressWindow({ closeOnClick: true });
-  pw.changeHeadline("Org Export");
+  pw.changeHeadline(headline);
   pw.addDescription(message);
   pw.show();
   pw.startCloseTimer(4000);
 }
 
+function warnBetterNotesRequired(addon: OrgExportAnnotationsAddon): void {
+  const message =
+    "Better Notes plugin is required for Org export.\n" +
+    "Please install it from: https://github.com/windingwind/zotero-better-notes";
+  addon.warn(message);
+  showNotification(message, "Org Export - Missing Requirement");
+}
+
 export function createHooks(addon: OrgExportAnnotationsAddon): Hooks {
   let notifierIDs: string[] = [];
 
@@ -35,8 +43,8 @@ export function createHooks(addon: OrgExportAnnotationsAddon): Hooks {
           Zotero.uiReadyPromise,
         ]);
 
-        if (!Zotero.BetterNotes) {
+        if (!addon.isBetterNotesInstalled()) {
-          addon.warn("Better Notes plugin not found - some features may not work");
+          warnBetterNotesRequired(addon);
         }
 
         Zotero.PreferencePanes.register({

src/index.ts

@@ -9,6 +9,7 @@ Zotero.OrgExportAnnotations = {
   log: addon.log.bind(addon),
   error: addon.error.bind(addon),
   warn: addon.warn.bind(addon),
+  isBetterNotesInstalled: addon.isBetterNotesInstalled.bind(addon),
   get id() {
     return addon.id;
   },

src/modules/converter.ts

@@ -9,6 +9,13 @@ export async function convertToOrg(
   const mdPath = PathUtils.join(notesPath, `${citationKey}.md`);
 
   try {
+    if (!Zotero.OrgExportAnnotations.isBetterNotesInstalled()) {
+      throw new Error(
+        "Better Notes plugin is required for Org export. " +
+          "Please install it from: https://github.com/windingwind/zotero-better-notes"
+      );
+    }
+
     const mdContent = await Zotero.BetterNotes!.api.convert.note2md(note, notesPath);
     await Zotero.File.putContentsAsync(mdPath, mdContent);
 

src/modules/exporter.ts

@@ -143,8 +143,11 @@ export class OrgExporter {
       throw new Error("Notes path is not configured");
     }
 
-    if (!Zotero.BetterNotes?.api?.convert?.note2md) {
+    if (!Zotero.OrgExportAnnotations.isBetterNotesInstalled()) {
-      throw new Error("Better Notes plugin is required but not found");
+      throw new Error(
+        "Better Notes plugin is required for Org export. " +
+          "Please install it from: https://github.com/windingwind/zotero-better-notes"
+      );
     }
 
     await this.prefs.ensureNotesDirectory();

zotero-plugin.config.ts

@@ -18,7 +18,7 @@ export default defineConfig({
       {
         entryPoints: ["src/index.ts"],
         bundle: true,
-        target: "firefox128",
+        target: "firefox140",
         outfile: ".scaffold/build/addon/content/scripts/index.js",
       },
     ],