|
| 1 | +// SPDX-License-Identifier: PMPL-1.0-or-later |
| 2 | +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> |
| 3 | +// |
| 4 | +// BoJ Server — API client module |
| 5 | +// |
| 6 | +// Direct passthrough clients for GitHub and GitLab APIs, plus |
| 7 | +// BoJ REST API wrappers for cartridge operations. |
| 8 | + |
| 9 | +import { isValidCartridgeName } from "./security.js"; |
| 10 | +import { warn } from "./logger.js"; |
| 11 | +import { SERVER_VERSION } from "./version.js"; |
| 12 | + |
| 13 | +const BOJ_BASE = process.env.BOJ_URL || "http://localhost:7700"; |
| 14 | +const GITHUB_TOKEN = process.env.GITHUB_TOKEN || ""; |
| 15 | +const GITLAB_TOKEN = process.env.GITLAB_TOKEN || ""; |
| 16 | + |
| 17 | +// =================================================================== |
| 18 | +// BoJ REST API wrappers |
| 19 | +// =================================================================== |
| 20 | + |
| 21 | +/** @returns {Promise<object>} */ |
| 22 | +async function fetchHealth() { |
| 23 | + try { |
| 24 | + const res = await fetch(`${BOJ_BASE}/health`); |
| 25 | + return await res.json(); |
| 26 | + } catch { |
| 27 | + return { status: "offline", message: "BoJ REST API not reachable. Start the server with: systemctl --user start boj-server" }; |
| 28 | + } |
| 29 | +} |
| 30 | + |
| 31 | +/** @returns {Promise<object>} */ |
| 32 | +async function fetchMenu() { |
| 33 | + try { |
| 34 | + const res = await fetch(`${BOJ_BASE}/menu`); |
| 35 | + return await res.json(); |
| 36 | + } catch { |
| 37 | + warn("BoJ REST API unreachable, using offline menu"); |
| 38 | + const { OFFLINE_MENU } = await import("./offline-menu.js"); |
| 39 | + return OFFLINE_MENU; |
| 40 | + } |
| 41 | +} |
| 42 | + |
| 43 | +/** @returns {Promise<object>} */ |
| 44 | +async function fetchCartridges() { |
| 45 | + try { |
| 46 | + const res = await fetch(`${BOJ_BASE}/cartridges`); |
| 47 | + return await res.json(); |
| 48 | + } catch { |
| 49 | + const { OFFLINE_MENU } = await import("./offline-menu.js"); |
| 50 | + return { |
| 51 | + note: "Offline mode — cartridge matrix available when BoJ REST API is running", |
| 52 | + cartridges: Object.keys( |
| 53 | + OFFLINE_MENU.tier_teranga |
| 54 | + .concat(OFFLINE_MENU.tier_shield) |
| 55 | + .reduce((acc, c) => { acc[c.name] = c.domain; return acc; }, {}) |
| 56 | + ), |
| 57 | + }; |
| 58 | + } |
| 59 | +} |
| 60 | + |
| 61 | +/** |
| 62 | + * @param {string} name |
| 63 | + * @param {object} [params] |
| 64 | + * @returns {Promise<object>} |
| 65 | + */ |
| 66 | +async function invokeCartridge(name, params) { |
| 67 | + if (!isValidCartridgeName(name)) { |
| 68 | + return { error: `Invalid cartridge name: ${name}` }; |
| 69 | + } |
| 70 | + try { |
| 71 | + const res = await fetch(`${BOJ_BASE}/cartridge/${encodeURIComponent(name)}/invoke`, { |
| 72 | + method: "POST", |
| 73 | + headers: { "Content-Type": "application/json" }, |
| 74 | + body: JSON.stringify(params || {}), |
| 75 | + }); |
| 76 | + return await res.json(); |
| 77 | + } catch { |
| 78 | + return { error: "BoJ REST API not reachable. Invocation requires a running server.", cartridge: name, hint: "Start with: systemctl --user start boj-server" }; |
| 79 | + } |
| 80 | +} |
| 81 | + |
| 82 | +/** |
| 83 | + * @param {string} name |
| 84 | + * @returns {Promise<object>} |
| 85 | + */ |
| 86 | +async function fetchCartridgeInfo(name) { |
| 87 | + if (!isValidCartridgeName(name)) { |
| 88 | + return { error: `Invalid cartridge name: ${name}` }; |
| 89 | + } |
| 90 | + try { |
| 91 | + const res = await fetch(`${BOJ_BASE}/cartridge/${encodeURIComponent(name)}`); |
| 92 | + return await res.json(); |
| 93 | + } catch { |
| 94 | + const { OFFLINE_MENU } = await import("./offline-menu.js"); |
| 95 | + const all = OFFLINE_MENU.tier_teranga.concat(OFFLINE_MENU.tier_shield); |
| 96 | + const found = all.find(c => c.name === name); |
| 97 | + return found || { error: `Unknown cartridge: ${name}` }; |
| 98 | + } |
| 99 | +} |
| 100 | + |
| 101 | +// =================================================================== |
| 102 | +// GitHub API |
| 103 | +// =================================================================== |
| 104 | + |
| 105 | +/** |
| 106 | + * @param {string} method |
| 107 | + * @param {string} path |
| 108 | + * @param {object} [body] |
| 109 | + * @returns {Promise<object>} |
| 110 | + */ |
| 111 | +async function githubApiCall(method, path, body) { |
| 112 | + if (!GITHUB_TOKEN) { |
| 113 | + return { error: "GITHUB_TOKEN not set. Store in vault-mcp or export to environment." }; |
| 114 | + } |
| 115 | + try { |
| 116 | + const url = `https://api.github.com${path}`; |
| 117 | + const opts = { |
| 118 | + method, |
| 119 | + headers: { |
| 120 | + "Authorization": `Bearer ${GITHUB_TOKEN}`, |
| 121 | + "Accept": "application/vnd.github+json", |
| 122 | + "X-GitHub-Api-Version": "2022-11-28", |
| 123 | + "User-Agent": `boj-server/${SERVER_VERSION}`, |
| 124 | + }, |
| 125 | + }; |
| 126 | + if (body && method !== "GET") { |
| 127 | + opts.headers["Content-Type"] = "application/json"; |
| 128 | + opts.body = JSON.stringify(body); |
| 129 | + } |
| 130 | + const res = await fetch(url, opts); |
| 131 | + const data = await res.json(); |
| 132 | + const rateLimit = { |
| 133 | + remaining: res.headers.get("x-ratelimit-remaining"), |
| 134 | + reset: res.headers.get("x-ratelimit-reset"), |
| 135 | + limit: res.headers.get("x-ratelimit-limit"), |
| 136 | + }; |
| 137 | + return { status: res.status, data, rateLimit }; |
| 138 | + } catch (err) { |
| 139 | + return { error: `GitHub API error: ${err.message}` }; |
| 140 | + } |
| 141 | +} |
| 142 | + |
| 143 | +/** |
| 144 | + * @param {string} query |
| 145 | + * @param {object} [variables] |
| 146 | + * @returns {Promise<object>} |
| 147 | + */ |
| 148 | +async function githubGraphQL(query, variables) { |
| 149 | + if (!GITHUB_TOKEN) { |
| 150 | + return { error: "GITHUB_TOKEN not set." }; |
| 151 | + } |
| 152 | + try { |
| 153 | + const res = await fetch("https://api.github.com/graphql", { |
| 154 | + method: "POST", |
| 155 | + headers: { |
| 156 | + "Authorization": `Bearer ${GITHUB_TOKEN}`, |
| 157 | + "Content-Type": "application/json", |
| 158 | + "User-Agent": `boj-server/${SERVER_VERSION}`, |
| 159 | + }, |
| 160 | + body: JSON.stringify({ query, variables: variables || {} }), |
| 161 | + }); |
| 162 | + return await res.json(); |
| 163 | + } catch (err) { |
| 164 | + return { error: `GitHub GraphQL error: ${err.message}` }; |
| 165 | + } |
| 166 | +} |
| 167 | + |
| 168 | +/** |
| 169 | + * Route GitHub tool calls to real API. |
| 170 | + * @param {string} toolName |
| 171 | + * @param {Record<string, any>} args |
| 172 | + * @returns {Promise<object>} |
| 173 | + */ |
| 174 | +async function handleGitHubTool(toolName, args) { |
| 175 | + switch (toolName) { |
| 176 | + case "boj_github_list_repos": |
| 177 | + return githubApiCall("GET", `/user/repos?per_page=${args.per_page || 30}&sort=${args.sort || "updated"}`); |
| 178 | + case "boj_github_get_repo": |
| 179 | + return githubApiCall("GET", `/repos/${args.owner}/${args.repo}`); |
| 180 | + case "boj_github_create_issue": |
| 181 | + return githubApiCall("POST", `/repos/${args.owner}/${args.repo}/issues`, { title: args.title, body: args.body, labels: args.labels }); |
| 182 | + case "boj_github_list_issues": |
| 183 | + return githubApiCall("GET", `/repos/${args.owner}/${args.repo}/issues?state=${args.state || "open"}&per_page=${args.per_page || 30}`); |
| 184 | + case "boj_github_get_issue": |
| 185 | + return githubApiCall("GET", `/repos/${args.owner}/${args.repo}/issues/${args.issue_number}`); |
| 186 | + case "boj_github_comment_issue": |
| 187 | + return githubApiCall("POST", `/repos/${args.owner}/${args.repo}/issues/${args.issue_number}/comments`, { body: args.body }); |
| 188 | + case "boj_github_create_pr": |
| 189 | + return githubApiCall("POST", `/repos/${args.owner}/${args.repo}/pulls`, { title: args.title, body: args.body, head: args.head, base: args.base || "main" }); |
| 190 | + case "boj_github_list_prs": |
| 191 | + return githubApiCall("GET", `/repos/${args.owner}/${args.repo}/pulls?state=${args.state || "open"}`); |
| 192 | + case "boj_github_get_pr": |
| 193 | + return githubApiCall("GET", `/repos/${args.owner}/${args.repo}/pulls/${args.pull_number}`); |
| 194 | + case "boj_github_merge_pr": |
| 195 | + return githubApiCall("PUT", `/repos/${args.owner}/${args.repo}/pulls/${args.pull_number}/merge`, { merge_method: args.method || "merge" }); |
| 196 | + case "boj_github_search_code": |
| 197 | + return githubApiCall("GET", `/search/code?q=${encodeURIComponent(args.query)}`); |
| 198 | + case "boj_github_search_issues": |
| 199 | + return githubApiCall("GET", `/search/issues?q=${encodeURIComponent(args.query)}`); |
| 200 | + case "boj_github_get_file": |
| 201 | + return githubApiCall("GET", `/repos/${args.owner}/${args.repo}/contents/${args.path}?ref=${args.ref || "main"}`); |
| 202 | + case "boj_github_graphql": |
| 203 | + return githubGraphQL(args.query, args.variables); |
| 204 | + default: |
| 205 | + return { error: `Unknown GitHub tool: ${toolName}` }; |
| 206 | + } |
| 207 | +} |
| 208 | + |
| 209 | +// =================================================================== |
| 210 | +// GitLab API |
| 211 | +// =================================================================== |
| 212 | + |
| 213 | +/** |
| 214 | + * @param {string} method |
| 215 | + * @param {string} path |
| 216 | + * @param {object} [body] |
| 217 | + * @returns {Promise<object>} |
| 218 | + */ |
| 219 | +async function gitlabApiCall(method, path, body) { |
| 220 | + if (!GITLAB_TOKEN) { |
| 221 | + return { error: "GITLAB_TOKEN not set." }; |
| 222 | + } |
| 223 | + const baseUrl = process.env.GITLAB_URL || "https://gitlab.com"; |
| 224 | + try { |
| 225 | + const url = `${baseUrl}/api/v4${path}`; |
| 226 | + const opts = { |
| 227 | + method, |
| 228 | + headers: { |
| 229 | + "PRIVATE-TOKEN": GITLAB_TOKEN, |
| 230 | + "Accept": "application/json", |
| 231 | + "User-Agent": `boj-server/${SERVER_VERSION}`, |
| 232 | + }, |
| 233 | + }; |
| 234 | + if (body && method !== "GET") { |
| 235 | + opts.headers["Content-Type"] = "application/json"; |
| 236 | + opts.body = JSON.stringify(body); |
| 237 | + } |
| 238 | + const res = await fetch(url, opts); |
| 239 | + const data = await res.json(); |
| 240 | + return { status: res.status, data }; |
| 241 | + } catch (err) { |
| 242 | + return { error: `GitLab API error: ${err.message}` }; |
| 243 | + } |
| 244 | +} |
| 245 | + |
| 246 | +/** |
| 247 | + * Route GitLab tool calls to real API. |
| 248 | + * @param {string} toolName |
| 249 | + * @param {Record<string, any>} args |
| 250 | + * @returns {Promise<object>} |
| 251 | + */ |
| 252 | +async function handleGitLabTool(toolName, args) { |
| 253 | + switch (toolName) { |
| 254 | + case "boj_gitlab_list_projects": |
| 255 | + return gitlabApiCall("GET", `/projects?owned=true&per_page=${args.per_page || 20}`); |
| 256 | + case "boj_gitlab_get_project": |
| 257 | + return gitlabApiCall("GET", `/projects/${encodeURIComponent(args.project_id)}`); |
| 258 | + case "boj_gitlab_create_issue": |
| 259 | + return gitlabApiCall("POST", `/projects/${encodeURIComponent(args.project_id)}/issues`, { title: args.title, description: args.description }); |
| 260 | + case "boj_gitlab_list_issues": |
| 261 | + return gitlabApiCall("GET", `/projects/${encodeURIComponent(args.project_id)}/issues?state=${args.state || "opened"}`); |
| 262 | + case "boj_gitlab_create_mr": |
| 263 | + return gitlabApiCall("POST", `/projects/${encodeURIComponent(args.project_id)}/merge_requests`, { title: args.title, source_branch: args.source, target_branch: args.target || "main" }); |
| 264 | + case "boj_gitlab_list_mrs": |
| 265 | + return gitlabApiCall("GET", `/projects/${encodeURIComponent(args.project_id)}/merge_requests?state=${args.state || "opened"}`); |
| 266 | + case "boj_gitlab_list_pipelines": |
| 267 | + return gitlabApiCall("GET", `/projects/${encodeURIComponent(args.project_id)}/pipelines`); |
| 268 | + case "boj_gitlab_setup_mirror": |
| 269 | + return gitlabApiCall("POST", `/projects/${encodeURIComponent(args.project_id)}/remote_mirrors`, { url: args.target_url, enabled: true }); |
| 270 | + default: |
| 271 | + return { error: `Unknown GitLab tool: ${toolName}` }; |
| 272 | + } |
| 273 | +} |
| 274 | + |
| 275 | +export { |
| 276 | + BOJ_BASE, |
| 277 | + fetchCartridgeInfo, |
| 278 | + fetchCartridges, |
| 279 | + fetchHealth, |
| 280 | + fetchMenu, |
| 281 | + handleGitHubTool, |
| 282 | + handleGitLabTool, |
| 283 | + invokeCartridge, |
| 284 | +}; |
0 commit comments