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.
chore: release v1.0.2
2026-09-29 17:55:36 +02:00 · 2026-09-29 17:35:27 +02:00 · 2026-09-29 17:34:28 +02:00 · 2026-02-17 23:56:10 +01:00 · 2026-02-17 23:52:51 +01:00 · 2026-02-17 23:50:08 +01:00
13 changed files with 203 additions and 125 deletions
@@ -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
@@ -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 "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+          echo "version=${GITEA_REF#refs/tags/v}" >> $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 }}"
-          TAG="${{ steps.version.outputs.tag }}"
-          REPO="${GITHUB_REPOSITORY}"
-          API_URL="${GITHUB_SERVER_URL}/api/v1"
+          set -euo pipefail
+
+          echo "=== Configuration ==="
+          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}."
@@ -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

 ---
@@ -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
@@ -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.*"
    }
  }
 }
@@ -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",
@@ -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",
@@ -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);
@@ -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) {
-          addon.warn("Better Notes plugin not found - some features may not work");
+        if (!addon.isBetterNotesInstalled()) {
+          warnBetterNotesRequired(addon);
        }

        Zotero.PreferencePanes.register({
@@ -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;
  },
@@ -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);

@@ -143,8 +143,11 @@ export class OrgExporter {
      throw new Error("Notes path is not configured");
    }

-    if (!Zotero.BetterNotes?.api?.convert?.note2md) {
-      throw new Error("Better Notes plugin is required but not found");
+    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"
+      );
    }

    await this.prefs.ensureNotesDirectory();
@@ -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",
      },
    ],
Author	SHA1	Message	Date
Ignacio Ballesteros	8d842f2a80	feat: warn when Better Notes is not installed CI / build (push) Successful in 23s Details Release / build (push) Successful in 1m18s Details Release / update-rolling-release (push) Successful in 8s Details Release / publish-release (push) Successful in 8s Details 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.	2026-09-29 17:55:36 +02:00
Ignacio Ballesteros	2366db009b	chore: release v1.0.2 CI / build (push) Successful in 16s Details Release / build (push) Successful in 1m49s Details Release / update-rolling-release (push) Successful in 9s Details Release / publish-release (push) Successful in 10s Details	2026-09-29 17:35:27 +02:00
Ignacio Ballesteros	8393cca8dd	feat: add Zotero 10 support CI / build (push) Successful in 21s Details Bump strict_max_version to 10.0.* and esbuild target to firefox140 (Zotero 9/10 Firefox 140 ESR base). Update docs accordingly.	2026-09-29 17:34:28 +02:00
Ignacio Ballesteros	15e55ee126	chore: bump version to 1.0.1 for update test CI / build (push) Successful in 21s Details Release / build (push) Successful in 38s Details Release / update-rolling-release (push) Successful in 7s Details Release / publish-release (push) Successful in 7s Details	2026-02-17 23:56:10 +01:00
Ignacio Ballesteros	52efde64c0	fix: mark rolling 'release' as pre-release so v1.0.0 shows as latest CI / build (push) Successful in 21s Details Release / build (push) Successful in 26s Details Release / update-rolling-release (push) Successful in 6s Details Release / publish-release (push) Successful in 6s Details	2026-02-17 23:52:51 +01:00
Ignacio Ballesteros	2768eb39de	fix: correct Gitea Actions release workflow CI / build (push) Successful in 20s Details Release / build (push) Successful in 26s Details Release / update-rolling-release (push) Successful in 7s Details Release / publish-release (push) Successful in 7s Details - Use gitea.ref/server_url/repository context vars instead of GitHub env vars - Move API_URL and REPO into env: block so context expressions are evaluated - Pass gitea.ref via env: for version extraction (GITEA_REF) - Replace grep/cut JSON parsing with jq throughout - Fix tag creation body: use 'target' key instead of 'message' - Add set -euo pipefail and diagnostic echo output to both run blocks - Add null check on jq-parsed RELEASE_ID in publish-release	2026-02-17 23:50:08 +01:00
Ignacio Ballesteros	30f2b4f810	fix: use gitea.token instead of missing GITEA_TOKEN secret CI / build (push) Successful in 20s Details Release / build (push) Successful in 25s Details Release / update-rolling-release (push) Failing after 17s Details Release / publish-release (push) Has been skipped Details	2026-02-17 23:33:53 +01:00
Ignacio Ballesteros	f47a203a80	fix: downgrade artifact actions to v3 for Gitea GHES compatibility CI / build (push) Successful in 36s Details Release / build (push) Successful in 38s Details Release / update-rolling-release (push) Failing after 17s Details Release / publish-release (push) Has been skipped Details	2026-02-17 23:30:00 +01:00
Ignacio Ballesteros	1ed9829f58	ci: add CI workflow for main, fix release pipeline ordering and node version CI / build (push) Successful in 45s Details Release / build (push) Failing after 22s Details Release / update-rolling-release (push) Has been skipped Details Release / publish-release (push) Has been skipped Details - Add ci.yml to build on every push to main (Node 22) - Add job-level guard on release build job (startsWith refs/tags/v) - Bump Node to 22 in release.yml to satisfy zotero-plugin-scaffold >=22.8.0 - Extract publish-release as a third job (needs: [build, update-rolling-release]) so the versioned release and XPI are only published after the full pipeline succeeds	2026-02-17 23:24:05 +01:00
Ignacio Ballesteros	e836809fc0	fix: use GITEA_SERVER_URL instead of GITHUB_SERVER_URL in release workflow	2026-02-17 23:03:27 +01:00