feat: add diagnostics route and broken link method

- add missing working directory
- use npm binary as exec

.forgejo/workflows/deploy.yaml

@@ -1,21 +1,3 @@
-# name: Deploy eolas-api
-# on:
-#   push:
-#     branches: [main]
-# jobs:
-#   deploy:
-#     runs-on: ubuntu-latest
-#     steps:
-#       - uses: actions/checkout@v3
-#       - run: |
-#           echo "${{ secrets.VPS_DEPLOY_USER_SSH_KEY }}" > /tmp/ssh_key
-#           chmod 600 /tmp/ssh_key
-#           ssh -i /tmp/ssh_key -o StrictHostKeyChecking=no ${{ vars.VPS_DEPLOY_USER }} "bash -c 'cd /var/www/eolas-api && rm -rf * .[^.]*'"
-#           scp -i /tmp/ssh_key -o StrictHostKeyChecking=no -r ./* ${{ vars.VPS_DEPLOY_USER }}:/var/www/eolas-api/
-#           rm /tmp/ssh_key
-#
-#
-
 name: Deploy eolas-api
 on:
   push:
@@ -28,78 +10,41 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Determine version bump and update package.json
-        id: version
-        run: |
-          latest_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
-          echo "Previous version: $latest_tag"
-
-          commit_msg=$(git log -1 --pretty=%B)
-
-          version=${latest_tag#v}
-          IFS='.' read -r major minor patch <<< "$version"
-
-          if echo "$commit_msg" | grep -qE "^major(\(.*\))?:|BREAKING CHANGE:"; then
-            major=$((major + 1))
-            minor=0
-            patch=0
-          elif echo "$commit_msg" | grep -qE "^feat(\(.*\))?:"; then
-            minor=$((minor + 1))
-            patch=0
-          elif echo "$commit_msg" | grep -qE "^fix(\(.*\))?:"; then
-            patch=$((patch + 1))
-          else
-            echo "No version bump needed"
-            echo "new_tag=" >> $GITHUB_OUTPUT
-            exit 0
-          fi
-
-          new_tag="v${major}.${minor}.${patch}"
-          new_version="${major}.${minor}.${patch}"
-          echo "New version: $new_tag"
-          echo "new_tag=$new_tag" >> $GITHUB_OUTPUT
-          echo "new_version=$new_version" >> $GITHUB_OUTPUT
-
-          # Save commit message for later (escape newlines)
-          echo "$commit_msg" > /tmp/commit_msg.txt
-
-          # Update package.json
-          sed -i "s/\"version\": \".*\"/\"version\": \"$new_version\"/" package.json
-
-      - name: Commit version change
-        if: steps.version.outputs.new_tag != ''
-        run: |
-          git config user.name "forgejo-actions[bot]"
-          git config user.email "forgejo-actions[bot]@noreply"
-          git add package.json
-          git commit --amend --no-edit
-          git push -f origin main
-
-      - name: Create and push tag
-        if: steps.version.outputs.new_tag != ''
-        run: |
-          git tag ${{ steps.version.outputs.new_tag }}
-          git push origin ${{ steps.version.outputs.new_tag }}
-
-      - name: Create Forgejo Release
-        if: steps.version.outputs.new_tag != ''
-        run: |
-          # Read and escape commit message for JSON
-          commit_msg=$(cat /tmp/commit_msg.txt | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | sed ':a;N;$!ba;s/\n/\\n/g')
-
-          curl -X POST \
-            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases" \
-            -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
-            -H "Content-Type: application/json" \
-            -d "{
-              \"tag_name\": \"${{ steps.version.outputs.new_tag }}\",
-              \"name\": \"${{ steps.version.outputs.new_tag }}\",
-              \"body\": \"$commit_msg\"
-            }"
       - name: Deploy to VPS
         run: |
+          echo "⚡ INFO Installing rsync" 
+          apt-get update && apt-get install -y rsync
+
+          echo "⚡ INFO Retrieving SSH key for deploy user" 
           echo "${{ secrets.VPS_DEPLOY_USER_SSH_KEY }}" > /tmp/ssh_key
           chmod 600 /tmp/ssh_key
-          ssh -i /tmp/ssh_key -o StrictHostKeyChecking=no ${{ vars.VPS_DEPLOY_USER }} "bash -c 'cd /var/www/eolas-api && rm -rf * .[^.]*'"
+
-          scp -i /tmp/ssh_key -o StrictHostKeyChecking=no -r ./* ${{ vars.VPS_DEPLOY_USER }}:/var/www/eolas-api/
+          echo "⚡ INFO Stopping service on VPS" 
+          ssh -i /tmp/ssh_key -o StrictHostKeyChecking=no ${{vars.VPS_DEPLOY_USER}} sudo /usr/bin/systemctl stop eolas-api.service 
+
+          echo "⚡ INFO Copy updated sourcefile files via rsync" 
+          rsync -avz --delete --inplace --exclude='.env' --exclude=".git" -e "ssh -i /tmp/ssh_key -o StrictHostKeyChecking=no" ./ ${{ vars.VPS_DEPLOY_USER }}:/var/www/eolas-api/
+
+          echo "⚡ INFO Run npm install on VPS" 
+          ssh -i /tmp/ssh_key -o StrictHostKeyChecking=no ${{vars.VPS_DEPLOY_USER}} "bash -l -c 'source ~/.nvm/nvm.sh && cd /var/www/eolas-api && npm install --omit=dev'"
+
+          echo "⚡ INFO Restarting service" 
+          ssh -i /tmp/ssh_key -o StrictHostKeyChecking=no ${{vars.VPS_DEPLOY_USER}} "bash -l -c 'sudo /usr/bin/systemctl daemon-reload && sudo /usr/bin/systemctl start eolas-api.service'"
+
           rm /tmp/ssh_key
+
+      - name: Notify success
+        if: success()
+        run: |
+          curl -u thomas:${{ secrets.NTFY_PASSWORD }} \
+               -H "Tags: Forgejo Runner" \
+               -d "🟩 eolas-api successfully deployed" \
+                https://ntfy.systemsobscure.net/eolas
+
+      - name: Notify failure
+        if: failure()
+        run: |
+          curl -u thomas:${{ secrets.NTFY_PASSWORD }} \
+               -H "Tags: Forgejo Runner" \
+               -d "🟥 An error occurred deploying eolas-api. See Forgejo Action logs." \
+                https://ntfy.systemsobscure.net/eolas

README.md

@@ -1,9 +1,207 @@
-TBC
+# eolas-api
 
-| HTTP Method | Path            | Parameter     | Returns                          |
+API written in NodeJS that queries my Zettelkasten, Eolas.
-| ----------- | --------------- | ------------- | -------------------------------- |
+
-| GET         | `entry`         | `entry_title` | Body text, tags, title           |
+It is a constituent part of my knowledge management system comprising [eolas](https://forgejo.systemsobscure.net/thomasabishop/eolas),
-| GET         | `tag`           | `tag_name`    | List of entries for supplied tag |
+[eolas-db](https://forgejo.systemsobscure.net/thomasabishop/eolas-db), and [eolas-app](https://forgejo.systemsobscure.net/thomasabishop/eolas-app).
-| GET         | `refs`          | `entry_title` | List of linked entries           |
+
-| GET         | `full_metadata` | `entry_title` | Tags, links, last modified       |
+The application reads from an SQLite database managed via [eolas-db](https://forgejo.systemsobscure.net/thomasabishop/eolas-db).
-| GET         | `graph`         | `null`        | Full network graph               |
+
+## Local development
+
+```sh
+npm install
+npm run start
+```
+
+This will start the local server at `http://localhost:4000`. It will look for
+stub database at `/data/eolas.db`.
+
+## Deployment
+
+The API is deployed to my remote VPS, residing at `/var/www/eolas-api`. The
+database that it reads from is located at `/data/sqlite/eolas/eolas.db`.
+
+Deployment is automated via [Forgejo action](https://forgejo.systemsobscure.net/thomasabishop/eolas-api/src/branch/main/.forgejo/workflows/deploy.yaml). Deployment actions are always executed by the `deploy` user on the VPS.
+
+The action script transfers the source files to the VPS and installs necessary
+packages. It also restarts the `eolas-api` systemd service on the VPS.
+
+### `systemd` service
+
+On the VPS, `eolas-api` runs as a `systemd` service. See the
+[unit file](./systemd/eolas-api.service) for details.
+
+## API
+
+### Search
+
+```
+GET /search/<search_term>
+```
+
+```json
+
+{
+  "count": 2,
+  "data": [
+    {
+      "entry": "Test_values_in_Bash",
+      "excerpt": "# <mark>Test</mark> values in Bash\n\n`<mark>test</mark>` is a built-in command that is used to compare values or determine whether\nsomething is the case.\n\nWe..."
+    },
+    {
+      "entry": "Testing_Python_code",
+      "excerpt": "...for a module called `lorem`, it will detzect the unit <mark>test</mark>\n  files `lorem_<mark>test</mark>.py` and `<mark>test</mark>_lorem.py`.\n- In order to detect tests..."
+    },
+```
+
+### Diagnostics
+
+#### Get broken links
+
+```
+GET /diagnostics/broken-links
+```
+
+```json
+{
+  "count": 1,
+  "data": [
+    {
+      "source_entry_title": "Reducing_fractions",
+      "broken_link_title": "Equivalent%20fractions"
+    }
+  ]
+}
+```
+
+### Entries
+
+#### Get all entries
+
+Return all entries. Optionally limit by length and/or date.
+
+```
+GET /entries?limit=2&sort=date
+```
+
+```json
+{
+  "count": 5,
+  "data": [
+    {
+      "title": "SSH",
+      "last_modified": "2025-07-10 14:26:04"
+    },
+    {
+      "title": "List_largest_files_bash",
+      "last_modified": "2025-07-07 16:49:12"
+    }
+  ]
+}
+```
+
+#### Get specific entry
+
+```
+GET /entries/Memory_versus_processor
+```
+
+```json
+{
+  "title": "Memory_versus_processor",
+  "last_modified": "2024-10-18 19:17:01",
+  "size": 270,
+  "body": "# Memory versus processor\n\n Would a more powerful processor with average or reduced memory capacity..."
+}
+```
+
+#### Get backlinks for an entry
+
+Defaults to alphabetic list.
+
+```
+GET /entries/backlinks/The_kernel
+```
+
+```json
+{
+  "count": 3,
+  "data": ["Boot_process", "Containerization", "CPU_architecture"]
+}
+```
+
+#### Get outlinks for an entry
+
+Defaults to alphabetic list.
+
+```
+GET /entries/outlinks/The_kernel
+```
+
+```json
+{
+  "count": 3,
+  "data": ["Basic_model_of_the_operating_system", "Processes", "User_Space"]
+}
+```
+
+#### Get entries associated with a specified tag
+
+Optionally sort chronologically.
+
+```
+GET /entries/tag/memory?sort=date
+```
+
+```json
+{
+  "count": 3,
+  "data": [
+    {
+      "entry_title": "Memory_addresses"
+    },
+    {
+      "entry_title": "Call_stack"
+    },
+    {
+      "entry_title": "The_memory_hierarchy"
+    }
+  ]
+}
+```
+
+### Tags
+
+#### Get all tags
+
+Sorted alphabetically.
+
+```
+GET /tags
+```
+
+```json
+{
+  "count": 119,
+  "data": ["algebra", "algorithms", "analogue", "android", "..."]
+}
+```
+
+#### Get tags for specified entry
+
+```
+GET /tags/The_kernel
+```
+
+```json
+{
+  "count": 4,
+  "data": [
+    "computer-architecture",
+    "memory",
+    "operating-systems",
+    "systems-programming"
+  ]
+}
+```

package-lock.json

@@ -10,7 +10,8 @@
 			"license": "ISC",
 			"dependencies": {
 				"cors": "^2.8.5",
-				"express": "^4.21.2"
+				"express": "^4.21.2",
+				"morgan": "^1.10.1"
 			},
 			"devDependencies": {
 				"eslint": "^9.20.0",
@@ -392,6 +393,24 @@
 			"dev": true,
 			"license": "MIT"
 		},
+		"node_modules/basic-auth": {
+			"version": "2.0.1",
+			"resolved": "https://registry.npmjs.org/basic-auth/-/basic-auth-2.0.1.tgz",
+			"integrity": "sha512-NF+epuEdnUYVlGuhaxbbq+dvJttwLnGY+YixlXlME5KpQ5W3CnXA5cVTneY3SPbPDRkcjMbifrwmFYcClgOZeg==",
+			"license": "MIT",
+			"dependencies": {
+				"safe-buffer": "5.1.2"
+			},
+			"engines": {
+				"node": ">= 0.8"
+			}
+		},
+		"node_modules/basic-auth/node_modules/safe-buffer": {
+			"version": "5.1.2",
+			"resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
+			"integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
+			"license": "MIT"
+		},
 		"node_modules/body-parser": {
 			"version": "1.20.3",
 			"resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.3.tgz",
@@ -1480,6 +1499,34 @@
 				"node": "*"
 			}
 		},
+		"node_modules/morgan": {
+			"version": "1.10.1",
+			"resolved": "https://registry.npmjs.org/morgan/-/morgan-1.10.1.tgz",
+			"integrity": "sha512-223dMRJtI/l25dJKWpgij2cMtywuG/WiUKXdvwfbhGKBhy1puASqXwFzmWZ7+K73vUPoR7SS2Qz2cI/g9MKw0A==",
+			"license": "MIT",
+			"dependencies": {
+				"basic-auth": "~2.0.1",
+				"debug": "2.6.9",
+				"depd": "~2.0.0",
+				"on-finished": "~2.3.0",
+				"on-headers": "~1.1.0"
+			},
+			"engines": {
+				"node": ">= 0.8.0"
+			}
+		},
+		"node_modules/morgan/node_modules/on-finished": {
+			"version": "2.3.0",
+			"resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.3.0.tgz",
+			"integrity": "sha512-ikqdkGAAyf/X/gPhXGvfgAytDZtDbr+bkNUJ0N9h5MI/dmdgCs3l6hoHrcUv41sRKew3jIwrp4qQDXiK99Utww==",
+			"license": "MIT",
+			"dependencies": {
+				"ee-first": "1.1.1"
+			},
+			"engines": {
+				"node": ">= 0.8"
+			}
+		},
 		"node_modules/ms": {
 			"version": "2.0.0",
 			"resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz",
@@ -1535,6 +1582,15 @@
 				"node": ">= 0.8"
 			}
 		},
+		"node_modules/on-headers": {
+			"version": "1.1.0",
+			"resolved": "https://registry.npmjs.org/on-headers/-/on-headers-1.1.0.tgz",
+			"integrity": "sha512-737ZY3yNnXy37FHkQxPzt4UZ2UWPWiCZWLvFZ4fu5cueciegX0zGPnrlY6bwRg4FdQOe9YU8MkmJwGhoMybl8A==",
+			"license": "MIT",
+			"engines": {
+				"node": ">= 0.8"
+			}
+		},
 		"node_modules/optionator": {
 			"version": "0.9.4",
 			"resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.4.tgz",

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "eolas-api",
-	"version": "0.2.1",
+	"version": "0.0.0",
 	"description": "API for querying eolas-db, my Zettelkasten database",
 	"license": "ISC",
 	"author": "Thomas Bishop",
@@ -8,12 +8,14 @@
 	"imports": {},
 	"main": "index.js",
 	"scripts": {
-		"start": "NODE_OPTIONS='--experimental-sqlite' node --watch --env-file=.env src/index.js",
+		"dev": "NODE_OPTIONS='--experimental-sqlite' node --watch --env-file=.env src/index.js",
+		"start": "NODE_OPTIONS='--experimental-sqlite' node --env-file=.env src/index.js",
 		"test": "echo \"Error: no test specified\" && exit 1"
 	},
 	"dependencies": {
 		"cors": "^2.8.5",
-		"express": "^4.21.2"
+		"express": "^4.21.2",
+		"morgan": "^1.10.1"
 	},
 	"devDependencies": {
 		"eslint": "^9.20.0",

src/controllers/DiagnosticsController.js

@@ -0,0 +1,18 @@
+export default class DiagnosticsController {
+    diagnosticsService
+
+    constructor(diagnosticsService) {
+        this.diagnosticsService = diagnosticsService
+    }
+
+    getBrokenLinks = (req, res) => {
+        const brokenLinks = this.diagnosticsService.getBrokenLinks()
+        if (!brokenLinks) {
+            return res.status(404).json({
+                message: `Broken link list could not be retrieved`,
+            })
+        }
+
+        return res.json(brokenLinks)
+    }
+}

src/controllers/SearchController.js

@@ -0,0 +1,19 @@
+export default class SearchController {
+	searchService
+
+	constructor(searchService) {
+		this.searchService = searchService
+	}
+
+	search = (req, res) => {
+		const query = req.params.query
+		const results = this.searchService.search(query)
+		if (!results) {
+			return res.status(404).json({
+				message: `No matches for query ${query}`,
+			})
+		}
+
+		return res.json(results)
+	}
+}

src/index.js

@@ -1,18 +1,30 @@
 import express from "express"
 import entries from "./routes/entries.js"
 import tags from "./routes/tags.js"
+import search from "./routes/search.js"
+import diagnostics from "./routes/diagnostics.js"
 import cors from "cors"
 import { validateApiKey } from "./middlewear/auth.js"
+import morgan from "morgan"
+
 const app = express()
 
-const port = process.env.PORT || 3000
+const port = process.env.PORT || 4000
 
+app.use(morgan("short"))
 app.use(cors())
 app.use(express.json())
 app.use("/", validateApiKey)
 app.use("/entries", entries)
 app.use("/tags", tags)
+app.use("/search", search)
+app.use("/diagnostics", diagnostics)
 
 app.listen(port, () => {
-	console.info(`INFO eolas-api server running at http://localhost:${port}`)
+	console.info(`TB-INFO eolas-api running on NodeJS ${process.version}`)
+	console.info(`TB-INFO eolas-api server running at http://localhost:${port}`)
+})
+
+app.get("/health", (req, res) => {
+	res.status(200).json({ status: "ok" })
 })

src/routes/diagnostics.js

@@ -0,0 +1,11 @@
+import express from "express"
+import DiagnosticsService from "../services/DiagnosticsService.js"
+import DiagnosticsController from "../controllers/DiagnosticsController.js"
+import database from "../db/connection.js"
+
+const router = express.Router()
+const diagnosticsService = new DiagnosticsService(database)
+const diagnosticsContoller = new DiagnosticsController(diagnosticsService)
+
+router.get("/broken-links", diagnosticsContoller.getBrokenLinks)
+export default router

src/routes/search.js

@@ -0,0 +1,12 @@
+import express from "express"
+import SearchService from "../services/SearchService.js"
+import SearchController from "../controllers/SearchController.js"
+import database from "../db/connection.js"
+
+const router = express.Router()
+const searchService = new SearchService(database)
+const searchController = new SearchController(searchService)
+
+router.get("/:query", searchController.search)
+
+export default router

src/services/DiagnosticsService.js

@@ -0,0 +1,17 @@
+import { GET_BROKEN_LINKS } from "../sql/diagnostics.js"
+
+export default class DiagnosticsService {
+    database
+
+    constructor(database) {
+        this.database = database
+    }
+
+    getBrokenLinks = () => {
+        const brokenLinks = this.database.prepare(GET_BROKEN_LINKS).all()
+        return {
+            count: brokenLinks.length,
+            data: brokenLinks,
+        }
+    }
+}

src/services/EntriesService.js

@@ -1,4 +1,10 @@
-import { GET_ALL_ENTRIES, GET_ENTRY, GET_ENTRIES_FOR_TAG, GET_BACKLINKS_FOR_ENTRY, GET_OUTLINKS_FOR_ENTRY } from "../sql/entries.js"
+import {
+	GET_ALL_ENTRIES,
+	GET_ENTRY,
+	GET_ENTRIES_FOR_TAG,
+	GET_BACKLINKS_FOR_ENTRY,
+	GET_OUTLINKS_FOR_ENTRY,
+} from "../sql/entries.js"
 
 export default class EntriesService {
 	database
@@ -42,7 +48,7 @@ export default class EntriesService {
 		const list = sorted.flatMap((i) => i.source_entry_title)
 		return {
 			count: backlinks.length,
-            data: list
+			data: list,
 		}
 	}
 
@@ -52,9 +58,8 @@ export default class EntriesService {
 		const list = sorted.flatMap((i) => i.target_entry_title)
 		return {
 			count: outlinks.length,
-            data: list
+			data: list,
 		}
-
 	}
 
 	_sortByTitle = (entries, fieldName) => {

src/services/SearchService.js

@@ -0,0 +1,17 @@
+import { SEARCH } from "../sql/search.js"
+
+export default class SearchService {
+    database
+
+    constructor(database) {
+        this.database = database
+    }
+
+    search = (query) => {
+        const results = this.database.prepare(SEARCH).all(query.trim())
+        return {
+            count: results.length,
+            data: results,
+        }
+    }
+}

src/sql/diagnostics.js

@@ -0,0 +1,3 @@
+const GET_BROKEN_LINKS = `SELECT * from broken_links`
+
+export { GET_BROKEN_LINKS }

src/sql/search.js

@@ -0,0 +1,3 @@
+const SEARCH = `SELECT title as entry, snippet(entries_fts, 1, '<mark>', '</mark>', '...', 24) as excerpt FROM entries_fts WHERE entries_fts MATCH ? ORDER BY rank LIMIT 25`
+
+export { SEARCH }

systemd/eolas-api.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=eolas-api
+After=network.target
+
+[Service]
+Type=simple
+User=deploy
+WorkingDirectory=/var/www/eolas-api
+Environment="NODE_OPTIONS=--experimental-sqlite"
+ExecStart=/home/deploy/.nvm/versions/node/v24.10.0/bin/node --env-file=.env /var/www/eolas-api/src/index.js
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target