gitlab-badge-proxy 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ArdensLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,267 @@
-# Temporary Holding Version
+# gitlab-badge-proxy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A tiny [Hono](https://hono.dev) app that turns a **private** GitLab project's pipeline/coverage status
+into public SVG badges, without ever exposing the GitLab instance's hostname or an access token to
+the browser. Everything that touches the real GitLab URL happens server-side, inside the deployed
+function; the client only ever sees your own domain.
+
+## Why
+
+GitLab's own badge images (`/<namespace>/<project>/badges/<branch>/pipeline.svg`) require a logged-in
+session to view on a private project — there is no supported token query parameter for them (that was
+disabled upstream for security reasons). This proxy instead calls the GitLab **REST API** (which does
+accept a `PRIVATE-TOKEN` header) to read the latest pipeline status/coverage, then re-renders that as a
+[shields.io](https://shields.io) static badge, fetched and streamed server-side. The GitLab URL and
+token never appear in any client-visible response, header, or redirect.
+
+## Routes
+
+- `GET /pipeline.svg` — latest pipeline status on the configured ref (`passing` / `failing` / `running` / `unknown`).
+- `GET /coverage.svg` — coverage percentage of the latest pipeline on that ref, color-graded. Add
+  `?job=<job-name>` to scope it to one job's coverage instead of the pipeline's aggregate, same as
+  GitLab's own native badge query param.
+- `GET /release.svg` — latest release's tag (version badge, blue for stable / orange for
+  0.x or pre-release-like tags), same coloring convention as shields.io's version badges.
+- `GET /tag.svg` — most recently updated tag, same version-badge coloring as `release.svg`.
+- `GET /stars.svg`, `GET /forks.svg`, `GET /contributors.svg` — repository counts (abbreviated
+  for large numbers, e.g. `12.3k`).
+- `GET /issues.svg?state=opened|closed|all&labels=<comma,separated>` — issue count for the given
+  state (default `all`); green when the count is zero, yellow otherwise.
+- `GET /merge-requests.svg?state=opened|closed|merged|locked|all&labels=<comma,separated>` —
+  merge request count for the given state (default `opened`); shows "more than 10k" past
+  GitLab's own count-header limit.
+- `GET /last-commit.svg?ref=<ref>&path=<file>` — how long ago the most recent matching commit
+  landed (`ref` defaults to the configured `GITLAB_REF`).
+- `GET /license.svg` — the project's detected license name, or "not specified".
+- `GET /languages.svg` — the top language by percentage of code. `GET /languages-count.svg` —
+  how many distinct languages GitLab detected.
+- `GET /labels.svg?name=<label-name>` — renders that label's own color from GitLab.
+- `GET /go-mod.svg?filename=go.mod&ref=<ref>` — the Go version declared in `go.mod` (or another
+  path given via `filename`), as a version badge.
+- `GET /health` — liveness check; does not read GitLab configuration.
+
+On any failure (GitLab unreachable, bad token, pipeline has no coverage) the routes degrade to a grey
+"unknown" badge instead of erroring, so a broken/rotated token shows up as a stale badge, not a broken
+image or a leaked error message.
+
+## Configuration
+
+All configuration is env-only — nothing GitLab-specific is hardcoded in the source, so this package
+stays safe to publish and reuse. Copy [`.env.example`](.env.example) and fill in your own values (as
+Vercel project env vars in production, never committed):
+
+| Variable | Required | Description |
+|---|---|---|
+| `GITLAB_URL` | yes | Base URL of your GitLab instance. |
+| `GITLAB_TOKEN` | yes | Token with the `read_api` scope on the target project only. |
+| `GITLAB_PROJECT` | yes | Project path (`group/name`) or numeric ID. |
+| `GITLAB_REF` | no | Branch/ref to report on. Defaults to `master`. |
+| `CACHE_MAX_AGE_SECONDS` | no | Edge cache lifetime for successful responses. Defaults to `60`. |
+| `GITLAB_PROJECTS` | no | Comma-separated whitelist for the GitLab-shaped routes below. Empty by default. |
+
+## GitLab-compatible badge URLs
+
+GitLab's own badges live at `<gitlab-url>/<namespace>/<project>/badges/<ref>/pipeline.svg` (and
+`coverage.svg`), plus `<gitlab-url>/<namespace>/<project>/-/badges/release.svg` for the latest
+release (no ref — releases aren't tied to a branch). This proxy serves the same path shapes, so
+existing badge links keep working when you swap the GitLab host for this proxy's — e.g.
+`https://badges.yourdomain.tld/ardenslab/pm2-dash/badges/main/coverage.svg` or
+`https://badges.yourdomain.tld/ardenslab/pm2-dash/-/badges/release.svg`.
+
+For security, only project paths listed in `GITLAB_PROJECTS` are served this way; any other path
+(or one that doesn't match `/badges/<ref>/pipeline.svg`, `/badges/<ref>/coverage.svg`, or
+`/-/badges/release.svg`) returns a plain 404, the same as GitLab's own behavior for an unknown
+project — the token is never used to probe or confirm the existence of a project you haven't
+explicitly whitelisted. The ref segment is free-form (any branch of a whitelisted project), unlike
+the fixed `GITLAB_REF` used by the flat `/pipeline.svg` / `/coverage.svg` routes above. The coverage
+route also accepts `?job=<job-name>`, same as the flat route.
+
+## Badge preview page
+
+`GET /debug/<group/project>?ref=<branch>` renders an HTML page with every badge this proxy can
+produce for that project: its own GitLab-shaped routes, the fixed-default-project flat routes, and
+the shields.io badges that work through the `gitlab_url` emulation below — all as live `<img>` tags,
+so you can eyeball everything at once instead of constructing and testing each URL by hand. `GET
+/debug` alone redirects to the configured default project. Each embedded badge still goes through its
+own route's whitelist check when the browser loads it, so an unlisted project just shows 404s in
+place, same as using that badge URL directly.
+
+## GitLab API emulation (for shields.io and similar)
+
+Some badge generators — notably [shields.io](https://shields.io)'s generic `gitlab` badges
+(`/gitlab/v/release/<project>`, `/gitlab/v/tag/<project>`, etc.) — don't fetch a pre-rendered badge;
+instead they take a `gitlab_url` query param and build their own GitLab REST API calls against it
+(`<gitlab_url>/api/v4/projects/<project>/releases`, etc.). Pointing `gitlab_url` at your real GitLab
+instance would require that instance to be publicly reachable. Point it at this proxy instead, and it
+answers those specific calls on the real GitLab's behalf:
+
+```
+https://img.shields.io/gitlab/v/release/ardenslab%2Fpm2-dash?gitlab_url=https%3A%2F%2Fbadges.yourdomain.tld
+https://img.shields.io/gitlab/v/tag/ardenslab%2Fpm2-dash?gitlab_url=https%3A%2F%2Fbadges.yourdomain.tld
+```
+
+(Leave off the trailing slash on `gitlab_url` — with one, shields.io's own path gets appended with a
+doubled `/`; the proxy redirects to collapse it, but it's one fewer hop to just omit it.)
+
+Only a narrow, read-only slice of the real API is implemented — `releases`, `repository/tags`,
+`languages`, `issues_statistics`, and `pipelines`/`pipelines/:id`/`pipelines/:id/jobs` — covering the
+version/tag/pipeline/coverage/issue-count badge shapes. Same whitelist as the GitLab-shaped badge
+routes above (`GITLAB_PROJECTS`): an unlisted project, or any subpath not on that list (file contents,
+full issue/MR bodies, commit messages, contributor emails — anything with actual content rather than
+metadata), 404s instead of being proxied. Every response body also has the real `GITLAB_URL` stripped
+out first, since GitLab embeds it in `web_url`/`_links` on nearly every resource.
+
+## Installing as a library
+
+```bash
+npm install gitlab-badge-proxy
+```
+
+The package exports a ready-made [Hono](https://hono.dev) app plus the pieces used to build it:
+
+```ts
+import { app } from "gitlab-badge-proxy";
+// app.request(...) / app.fetch(...) — mount it directly, or compose it into a bigger Hono app.
+```
+
+```ts
+import { createApp, loadConfig, type Config } from "gitlab-badge-proxy";
+
+// Supply config explicitly instead of reading env vars:
+const config: Config = {
+  gitlabUrl: "https://gitlab.example.net",
+  gitlabToken: process.env.MY_TOKEN!,
+  project: "group/project",
+  ref: "main",
+  cacheMaxAgeSeconds: 60,
+};
+const app = createApp(() => config);
+```
+
+## Hosting your own proxy
+
+Whichever platform you pick, two things stay true everywhere: set the env vars from the
+[Configuration](#configuration) table above as that platform's secrets/environment feature (never
+commit them), and attach a domain that doesn't hint at the real GitLab host (e.g.
+`badges.yourdomain.tld`, not `gitlab-proxy-for-<realcompany>.vercel.app`) — that's the whole point of
+this proxy.
+
+### On Vercel
+
+Either install the package in your own project, or fork/clone this repo directly and deploy it as-is —
+both end up running the same `app`.
+
+**As a dependency in your own project:**
+
+```ts
+// api/index.ts
+import { handle } from "hono/vercel";
+import { app } from "gitlab-badge-proxy";
+
+export const GET = handle(app);
+export const runtime = "nodejs";
+```
+
+```json
+// vercel.json
+{ "rewrites": [{ "source": "/(.*)", "destination": "/api" }] }
+```
+
+Set the env vars in the Vercel project settings (Production + Preview), then `vercel deploy --prod`.
+
+**Forking/cloning this repo instead:** it already has `api/index.ts` and `vercel.json` set up the same
+way — `vercel link`, set the same env vars, `vercel deploy --prod`, done.
+
+### On Cloudflare Workers
+
+```ts
+// src/index.ts
+import { app } from "gitlab-badge-proxy";
+
+export default app; // Hono apps are already a `fetch(request, env, ctx)` handler
+```
+
+```toml
+# wrangler.toml
+name = "gitlab-badge-proxy"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+```
+
+Set `GITLAB_URL` / `GITLAB_PROJECT` / etc. with `wrangler secret put <NAME>` (or in the dashboard
+under Settings > Variables) rather than plaintext `[vars]`, since `GITLAB_TOKEN` is a credential. The
+config module reads `process.env`, so wire Worker bindings into that shape before calling
+`createApp`/`loadConfig` — e.g. `createApp(() => loadConfig(env as unknown as Record<string, string>))`
+inside your `fetch` handler, since Workers pass env as a per-request argument rather than a global.
+
+### On plain Node.js (bare metal, a VM, or Docker)
+
+```ts
+// server.mjs
+import { serve } from "@hono/node-server";
+import { app } from "gitlab-badge-proxy";
+
+serve({ fetch: app.fetch, port: Number(process.env.PORT) || 3000 });
+```
+
+```dockerfile
+# Dockerfile
+FROM node:22-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm install gitlab-badge-proxy @hono/node-server
+COPY server.mjs ./
+EXPOSE 3000
+CMD ["node", "server.mjs"]
+```
+
+Run with `docker run -p 3000:3000 --env-file .env your-image-name`, then put a reverse proxy
+(Caddy/nginx/your platform's own ingress) with TLS in front of it on your domain.
+
+### Anywhere else
+
+`app` is a standard Hono instance, and Hono ships adapters for most other JS runtimes — Deno, Bun, AWS
+Lambda, Netlify Functions, Fastly Compute — covered in
+[Hono's own deployment docs](https://hono.dev/docs/getting-started/basic). The app itself (`src/app.ts`)
+has no platform-specific code; only the few lines that call `serve()`/`handle()` change per target.
+
+## Development
+
+```bash
+npm install
+cp .env.example .env.local   # fill in real values, never commit this file
+npm run typecheck
+npm test
+npm run dev                  # plain Node server on :3000, serves the routes locally
+npm run dev:vercel           # optional: vercel dev, if you're testing the Vercel integration specifically
+```
+
+## Releasing
+
+CI/CD lives in [`.gitlab-ci.yml`](.gitlab-ci.yml) (this repo's origin is GitLab, not GitHub). Every
+push/MR runs `typecheck` + `test` + `build` on Node 22 and 24. Publishing uses the shared
+[`npm-publish`](https://gitlab.cloudnetwork.one/matteo/ci-templates) CI/CD component — the same one
+`pm2-dash` uses — instead of a bespoke publish job: it publishes whenever someone pushes to the
+`deploy-npm` branch, relying on the existing `prepublishOnly` script to typecheck/test/build first and
+on npm itself refusing to publish over a version that already exists (no separate version check).
+
+One-time setup:
+1. Generate an npm **Granular Access Token** (https://www.npmjs.com/settings/~/tokens), scoped to this
+   package, **read+write**, with **"bypass 2FA"** enabled (CI can't answer an OTP prompt).
+2. GitLab: Settings > CI/CD > Variables → add `NPM_TOKEN`, flagged **Masked** + **Protected**.
+3. GitLab: Settings > Repository > Protected branches → protect `deploy-npm` (protected variables are
+   only sent to protected branches/tags).
+
+To cut a release:
+
+```bash
+npm version patch --no-git-tag-version   # or minor / major — bumps package.json only
+git commit -am "1.2.3"
+git push origin HEAD:deploy-npm
+```
+
+The pipeline publishes automatically once that push lands; watch it under CI/CD > Pipelines.
+
+## License
+
+MIT © ArdensLab

package/dist/src/app.d.ts

@@ -0,0 +1,8 @@
+import { Hono } from "hono";
+import { type Config } from "./config.js";
+export { loadConfig, type Config } from "./config.js";
+import { buildShieldsUrl } from "./badge.js";
+export declare function createApp(getConfig?: () => Config): Hono;
+export { buildShieldsUrl };
+export declare const app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=app.d.ts.map

package/dist/src/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAgB,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAoBtD,OAAO,EACL,eAAe,EAkBhB,MAAM,YAAY,CAAC;AAuWpB,wBAAgB,SAAS,CAAC,SAAS,GAAE,MAAM,MAAmB,GAAG,IAAI,CAqNpE;AAED,OAAO,EAAE,eAAe,EAAE,CAAC;AAC3B,eAAO,MAAM,GAAG,4EAAc,CAAC"}

package/dist/src/app.js

@@ -0,0 +1,480 @@
+import { Hono } from "hono";
+import { loadConfig } from "./config.js";
+export { loadConfig } from "./config.js";
+import { getContributorsCount, getForksCount, getGoModVersion, getIssuesCount, getJobCoverage, getLabelColor, getLanguages, getLastCommitDate, getLatestPipeline, getLatestRelease, getLatestTag, getLicenseName, getMergeRequestsCount, getPipelineCoverage, getStarsCount, } from "./gitlab.js";
+import { buildShieldsUrl, contributorsToBadge, coverageToBadge, fetchBadgeSvg, forksToBadge, goModVersionToBadge, issuesToBadge, labelToBadge, languagesCountToBadge, lastCommitToBadge, licenseToBadge, mergeRequestsToBadge, pipelineStatusToBadge, releaseToBadge, starsToBadge, tagToBadge, topLanguageToBadge, } from "./badge.js";
+const UNKNOWN_PIPELINE = { label: "pipeline", message: "unknown", color: "lightgrey" };
+const UNKNOWN_COVERAGE = { label: "coverage", message: "unknown", color: "lightgrey" };
+const UNKNOWN_RELEASE = { label: "release", message: "unknown", color: "lightgrey" };
+const UNKNOWN = { label: "gitlab", message: "unknown", color: "lightgrey" };
+/** Matches GitLab's own badge URL shape: `<project path>/badges/<ref>/<pipeline|coverage>.svg`. */
+const BADGE_PATH_PATTERN = /^(.+)\/badges\/([^/]+)\/(pipeline|coverage)\.svg$/;
+/** Matches GitLab's latest-release badge shape: `<project path>/-/badges/release.svg` (no ref). */
+const RELEASE_PATH_PATTERN = /^(.+)\/-\/badges\/release\.svg$/;
+/**
+ * Known-safe `/api/v4/projects/:id/<subpath>` suffixes: just enough of the real GitLab REST API
+ * for shields.io-style "point gitlab_url at a different host" badges (release/tag/pipeline/
+ * coverage/language/issue-count) to work unmodified. Deliberately excludes anything whose response
+ * body carries content rather than metadata (file contents, commit messages, full issue/MR bodies,
+ * contributor emails) even though the token could read it — this stays a badge proxy, not an open
+ * GitLab API mirror.
+ */
+const API_LITERAL_SUBPATHS = ["releases", "repository/tags", "languages", "issues_statistics"];
+/** Splits a `/api/v4/projects/<rest>` tail into the (still possibly `%2F`-encoded) project id and
+ * the matched subpath (empty string for the bare project-root lookup). A `rest` that doesn't end in
+ * one of the known-safe shapes falls through to "whole thing is the id", which then simply fails the
+ * project whitelist check below — same 404 GitLab itself would give for a route shape it doesn't know. */
+function splitProjectApiPath(rest) {
+    for (const subpath of API_LITERAL_SUBPATHS) {
+        const suffix = `/${subpath}`;
+        if (rest.endsWith(suffix)) {
+            return { projectRaw: rest.slice(0, -suffix.length), subpath };
+        }
+    }
+    const jobsMatch = /^(.+)\/pipelines\/(\d+)\/jobs$/.exec(rest);
+    if (jobsMatch) {
+        return { projectRaw: jobsMatch[1], subpath: `pipelines/${jobsMatch[2]}/jobs` };
+    }
+    const pipelineMatch = /^(.+)\/pipelines\/(\d+)$/.exec(rest);
+    if (pipelineMatch) {
+        return { projectRaw: pipelineMatch[1], subpath: `pipelines/${pipelineMatch[2]}` };
+    }
+    if (rest.endsWith("/pipelines")) {
+        return { projectRaw: rest.slice(0, -"/pipelines".length), subpath: "pipelines" };
+    }
+    // No known subpath suffix matched: `rest` is just the (bare) project id, e.g. the project-root
+    // lookup GitLab's own stars/forks/license fields live on.
+    return { projectRaw: rest, subpath: "" };
+}
+function apiError(message, status) {
+    return new Response(JSON.stringify({ message }), {
+        status,
+        headers: { "content-type": "application/json; charset=utf-8" },
+    });
+}
+/**
+ * Projects a safe-listed subpath's upstream JSON down to just the fields the badges it's meant for
+ * actually use. GitLab nests far more than that in these responses even where it looks harmless —
+ * `/releases` items carry a full `commit` object (author/committer email, commit message) and a free-
+ * text `description` (release notes), and the project root carries `namespace`, `permissions`, etc.
+ * None of that is "the GitLab host", so the plain text-scrub in proxyGitlabApi doesn't catch it; this
+ * allowlists fields instead of blocklisting them, so a new upstream field can't leak by default.
+ */
+function minimizeApiResponse(subpath, data) {
+    if (subpath === "") {
+        const project = data;
+        return {
+            star_count: project.star_count ?? null,
+            forks_count: project.forks_count ?? null,
+            license: project.license ? { name: project.license.name } : null,
+        };
+    }
+    if (subpath === "releases") {
+        return data.map(({ name, tag_name }) => ({ name, tag_name }));
+    }
+    if (subpath === "repository/tags") {
+        return data.map(({ name }) => ({ name }));
+    }
+    if (subpath === "pipelines") {
+        return data.map(({ id, status }) => ({ id, status }));
+    }
+    if (/^pipelines\/\d+$/.test(subpath)) {
+        const pipeline = data;
+        return { id: pipeline.id, status: pipeline.status, coverage: pipeline.coverage ?? null };
+    }
+    if (/^pipelines\/\d+\/jobs$/.test(subpath)) {
+        return data.map(({ id, name, coverage }) => ({ id, name, coverage: coverage ?? null }));
+    }
+    // languages (name -> percentage) and issues_statistics (aggregate counts only) are already exactly
+    // as minimal as their upstream shape gets — nothing to drop.
+    return data;
+}
+/** Proxies one whitelisted, known-safe GitLab API call server-side: projects the response down to
+ * minimizeApiResponse's allowlisted fields on success (see there for why), and as a second layer,
+ * scrubs any remaining literal occurrence of the real GitLab URL — this proxy's whole point is to
+ * never let that host, or anything beyond a badge's worth of data, leak to the client. */
+async function proxyGitlabApi(config, projectPath, subpath, search) {
+    const upstream = `${config.gitlabUrl}/api/v4/projects/${encodeURIComponent(projectPath)}${subpath ? `/${subpath}` : ""}${search}`;
+    try {
+        const response = await fetch(upstream, { headers: { "PRIVATE-TOKEN": config.gitlabToken } });
+        const text = await response.text();
+        const maxAge = response.ok ? config.cacheMaxAgeSeconds : 30;
+        let body = text;
+        if (response.ok) {
+            try {
+                body = JSON.stringify(minimizeApiResponse(subpath, JSON.parse(text)));
+            }
+            catch (error) {
+                console.error("gitlab-badge-proxy: unexpected non-JSON response for a safe-listed subpath", error);
+                return apiError("502 Bad Gateway", 502);
+            }
+        }
+        body = body.split(config.gitlabUrl).join("");
+        return new Response(body, {
+            status: response.status,
+            headers: {
+                "content-type": "application/json; charset=utf-8",
+                "cache-control": `public, max-age=${maxAge}, s-maxage=${maxAge}`,
+            },
+        });
+    }
+    catch (error) {
+        console.error("gitlab-badge-proxy: failed to proxy GitLab API request", error);
+        return apiError("502 Bad Gateway", 502);
+    }
+}
+const HTML_ESCAPES = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => HTML_ESCAPES[char]);
+}
+function renderBadgeSection(title, note, badges) {
+    const items = badges
+        .map((badge) => `
+        <div class="badge">
+          <img src="${escapeHtml(badge.src)}" alt="${escapeHtml(badge.label)}" loading="lazy" />
+          <code>${escapeHtml(badge.src)}</code>
+        </div>`)
+        .join("");
+    return `
+    <section>
+      <h2>${escapeHtml(title)}</h2>
+      ${note ? `<p class="note">${note}</p>` : ""}
+      <div class="grid">${items}</div>
+    </section>`;
+}
+/**
+ * Renders a page of every badge this proxy knows how to produce for one project: its own
+ * GitLab-shaped routes, the fixed-default-project flat routes, and the shields.io badges that work
+ * through this proxy's `/api/v4` emulation (see API_LITERAL_SUBPATHS). Pure HTML generation — every
+ * `<img>` still goes through that route's own whitelist check when the browser loads it, so this page
+ * never needs its own authorization beyond what's already enforced downstream.
+ */
+function renderDebugPage(project, ref, origin) {
+    const encodedProject = encodeURIComponent(project);
+    const encodedOrigin = encodeURIComponent(origin);
+    const encodedRef = encodeURIComponent(ref);
+    const nativeProjectBadges = [
+        { label: "pipeline", src: `/${project}/badges/${ref}/pipeline.svg` },
+        { label: "coverage", src: `/${project}/badges/${ref}/coverage.svg` },
+        { label: "release", src: `/${project}/-/badges/release.svg` },
+    ];
+    const nativeDefaultBadges = [
+        { label: "pipeline", src: "/pipeline.svg" },
+        { label: "coverage", src: "/coverage.svg" },
+        { label: "release", src: "/release.svg" },
+        { label: "stars", src: "/stars.svg" },
+        { label: "forks", src: "/forks.svg" },
+        { label: "contributors", src: "/contributors.svg" },
+        { label: "issues", src: "/issues.svg" },
+        { label: "merge requests", src: "/merge-requests.svg" },
+        { label: "last commit", src: "/last-commit.svg" },
+        { label: "license", src: "/license.svg" },
+        { label: "tag", src: "/tag.svg" },
+        { label: "top language", src: "/languages.svg" },
+        { label: "language count", src: "/languages-count.svg" },
+        { label: "label color (bug)", src: "/labels.svg?name=bug" },
+        { label: "go.mod version", src: "/go-mod.svg" },
+    ];
+    const shieldsBadges = [
+        {
+            label: "release",
+            src: `https://img.shields.io/gitlab/v/release/${encodedProject}?gitlab_url=${encodedOrigin}`,
+        },
+        { label: "tag", src: `https://img.shields.io/gitlab/v/tag/${encodedProject}?gitlab_url=${encodedOrigin}` },
+        { label: "stars", src: `https://img.shields.io/gitlab/stars/${encodedProject}?gitlab_url=${encodedOrigin}` },
+        { label: "forks", src: `https://img.shields.io/gitlab/forks/${encodedProject}?gitlab_url=${encodedOrigin}` },
+        {
+            label: "license",
+            src: `https://img.shields.io/gitlab/license/${encodedProject}?gitlab_url=${encodedOrigin}`,
+        },
+        {
+            label: "top language",
+            src: `https://img.shields.io/gitlab/languages/${encodedProject}?gitlab_url=${encodedOrigin}`,
+        },
+        {
+            label: "language count",
+            src: `https://img.shields.io/gitlab/languages/count/${encodedProject}?gitlab_url=${encodedOrigin}`,
+        },
+        {
+            label: "issues (all)",
+            src: `https://img.shields.io/gitlab/issues/all/${encodedProject}?gitlab_url=${encodedOrigin}`,
+        },
+        {
+            label: "pipeline status",
+            src: `https://img.shields.io/gitlab/pipeline-status/${encodedProject}?gitlab_url=${encodedOrigin}&branch=${encodedRef}`,
+        },
+        {
+            label: "pipeline coverage",
+            src: `https://img.shields.io/gitlab/pipeline-coverage/${encodedProject}?gitlab_url=${encodedOrigin}&branch=${encodedRef}`,
+        },
+    ];
+    const escapedProject = escapeHtml(project);
+    const escapedRef = escapeHtml(ref);
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>gitlab-badge-proxy — badge preview</title>
+<style>
+  body { font-family: system-ui, sans-serif; margin: 2rem; background: #0f172a; color: #e2e8f0; }
+  h1 { font-size: 1.1rem; font-weight: 600; }
+  h2 { font-size: 0.95rem; margin-top: 2rem; border-bottom: 1px solid #334155; padding-bottom: 0.35rem; }
+  .note { color: #94a3b8; font-size: 0.8rem; max-width: 60ch; }
+  .grid { display: flex; flex-wrap: wrap; gap: 0.75rem; margin-top: 1rem; }
+  .badge { background: #1e293b; border-radius: 6px; padding: 0.6rem 0.75rem; display: flex; align-items: center; gap: 0.75rem; }
+  code { font-size: 0.7rem; color: #64748b; word-break: break-all; max-width: 32ch; }
+  img { height: 20px; flex-shrink: 0; }
+</style>
+</head>
+<body>
+  <h1>Badge preview for <code>${escapedProject}</code> @ <code>${escapedRef}</code></h1>
+  <p class="note">Project-scoped sections 404 unless <code>${escapedProject}</code> is listed in
+  <code>GITLAB_PROJECTS</code>. Change the project/ref via the URL: <code>/debug/&lt;group/project&gt;?ref=&lt;branch&gt;</code>.</p>
+  ${renderBadgeSection("Native — this project", null, nativeProjectBadges)}
+  ${renderBadgeSection("Native — default configured project", "Always targets the fixed <code>GITLAB_PROJECT</code> / <code>GITLAB_REF</code> from this deployment's config, regardless of the project above.", nativeDefaultBadges)}
+  ${renderBadgeSection("shields.io (via gitlab_url pointed at this proxy)", "Only the badge types this proxy's read-only <code>/api/v4</code> emulation supports. contributors/merge-requests/last-commit/labels/go-mod aren't exposed that way by design (their GitLab API responses carry emails, commit messages, or full titles) — use the native badges above for those instead.", shieldsBadges)}
+</body>
+</html>`;
+}
+function svgResponse(svg, maxAgeSeconds) {
+    return new Response(svg, {
+        headers: {
+            "content-type": "image/svg+xml; charset=utf-8",
+            "cache-control": `public, max-age=${maxAgeSeconds}, s-maxage=${maxAgeSeconds}, stale-while-revalidate=${maxAgeSeconds * 5}`,
+        },
+    });
+}
+async function resolveSpec(config, fallback, context, compute) {
+    try {
+        return { spec: await compute(), maxAge: config.cacheMaxAgeSeconds };
+    }
+    catch (error) {
+        console.error(`gitlab-badge-proxy: failed to resolve ${context}`, error);
+        return { spec: fallback, maxAge: 30 };
+    }
+}
+async function resolvePipelineSpec(config, projectPath, ref) {
+    return resolveSpec(config, UNKNOWN_PIPELINE, "pipeline status", async () => {
+        const pipeline = await getLatestPipeline(config, projectPath, ref);
+        return pipeline ? pipelineStatusToBadge(pipeline.status) : UNKNOWN_PIPELINE;
+    });
+}
+/** `jobName` scopes to one job's coverage (GitLab's own `?job=` param); omitted means the pipeline's aggregate coverage. */
+async function resolveCoverageSpec(config, projectPath, ref, jobName) {
+    return resolveSpec(config, UNKNOWN_COVERAGE, "coverage", async () => {
+        const pipeline = await getLatestPipeline(config, projectPath, ref);
+        const coverage = pipeline
+            ? jobName
+                ? await getJobCoverage(config, projectPath, pipeline.id, jobName)
+                : await getPipelineCoverage(config, projectPath, pipeline.id)
+            : null;
+        return coverageToBadge(coverage);
+    });
+}
+async function resolveReleaseSpec(config, projectPath) {
+    return resolveSpec(config, UNKNOWN_RELEASE, "release", async () => {
+        const release = await getLatestRelease(config, projectPath);
+        return releaseToBadge(release);
+    });
+}
+/** Registers a flat `/<path>.svg` route fixed to the configured default project (and ref, where relevant). */
+function registerBadgeRoute(app, getConfig, path, fallback, context, compute) {
+    app.get(path, async (c) => {
+        let config;
+        try {
+            config = getConfig();
+        }
+        catch (error) {
+            console.error("gitlab-badge-proxy: failed to load config", error);
+            return svgResponse(await fetchBadgeSvg(fallback), 30);
+        }
+        const { spec, maxAge } = await resolveSpec(config, fallback, context, () => compute(config, c));
+        return svgResponse(await fetchBadgeSvg(spec), maxAge);
+    });
+}
+export function createApp(getConfig = loadConfig) {
+    const app = new Hono();
+    // Collapses accidental double slashes (e.g. a caller's `gitlab_url` ending in `/`, concatenated
+    // with a path that also starts with `/`) instead of 404ing on them.
+    app.use(async (c, next) => {
+        const url = new URL(c.req.url);
+        if (url.pathname.includes("//")) {
+            url.pathname = url.pathname.replace(/\/{2,}/g, "/");
+            return c.redirect(url.pathname + url.search, 308);
+        }
+        await next();
+    });
+    app.get("/health", (c) => c.json({ ok: true }));
+    app.get("/pipeline.svg", async (c) => {
+        let config;
+        try {
+            config = getConfig();
+        }
+        catch (error) {
+            console.error("gitlab-badge-proxy: failed to load config", error);
+            return svgResponse(await fetchBadgeSvg(UNKNOWN_PIPELINE), 30);
+        }
+        const { spec, maxAge } = await resolvePipelineSpec(config, config.project, config.ref);
+        return svgResponse(await fetchBadgeSvg(spec), maxAge);
+    });
+    app.get("/coverage.svg", async (c) => {
+        let config;
+        try {
+            config = getConfig();
+        }
+        catch (error) {
+            console.error("gitlab-badge-proxy: failed to load config", error);
+            return svgResponse(await fetchBadgeSvg(UNKNOWN_COVERAGE), 30);
+        }
+        const { spec, maxAge } = await resolveCoverageSpec(config, config.project, config.ref, c.req.query("job"));
+        return svgResponse(await fetchBadgeSvg(spec), maxAge);
+    });
+    app.get("/release.svg", async (c) => {
+        let config;
+        try {
+            config = getConfig();
+        }
+        catch (error) {
+            console.error("gitlab-badge-proxy: failed to load config", error);
+            return svgResponse(await fetchBadgeSvg(UNKNOWN_RELEASE), 30);
+        }
+        const { spec, maxAge } = await resolveReleaseSpec(config, config.project);
+        return svgResponse(await fetchBadgeSvg(spec), maxAge);
+    });
+    registerBadgeRoute(app, getConfig, "/stars.svg", UNKNOWN, "stars", async (config) => starsToBadge(await getStarsCount(config, config.project)));
+    registerBadgeRoute(app, getConfig, "/forks.svg", UNKNOWN, "forks", async (config) => forksToBadge(await getForksCount(config, config.project)));
+    registerBadgeRoute(app, getConfig, "/contributors.svg", UNKNOWN, "contributors", async (config) => contributorsToBadge(await getContributorsCount(config, config.project)));
+    registerBadgeRoute(app, getConfig, "/issues.svg", UNKNOWN, "issues", async (config, c) => {
+        const state = c.req.query("state") ?? "all";
+        const labels = c.req.query("labels");
+        return issuesToBadge(await getIssuesCount(config, config.project, state, labels), state, labels);
+    });
+    registerBadgeRoute(app, getConfig, "/merge-requests.svg", UNKNOWN, "merge requests", async (config, c) => {
+        const state = c.req.query("state") ?? "opened";
+        const labels = c.req.query("labels");
+        return mergeRequestsToBadge(await getMergeRequestsCount(config, config.project, state, labels), state, labels);
+    });
+    registerBadgeRoute(app, getConfig, "/last-commit.svg", UNKNOWN, "last commit", async (config, c) => {
+        const ref = c.req.query("ref") ?? config.ref;
+        const path = c.req.query("path");
+        return lastCommitToBadge(await getLastCommitDate(config, config.project, ref, path));
+    });
+    registerBadgeRoute(app, getConfig, "/license.svg", UNKNOWN, "license", async (config) => licenseToBadge(await getLicenseName(config, config.project)));
+    registerBadgeRoute(app, getConfig, "/tag.svg", UNKNOWN, "tag", async (config) => tagToBadge(await getLatestTag(config, config.project)));
+    registerBadgeRoute(app, getConfig, "/languages.svg", UNKNOWN, "top language", async (config) => topLanguageToBadge(await getLanguages(config, config.project)));
+    registerBadgeRoute(app, getConfig, "/languages-count.svg", UNKNOWN, "language count", async (config) => languagesCountToBadge(await getLanguages(config, config.project)));
+    registerBadgeRoute(app, getConfig, "/labels.svg", UNKNOWN, "label", async (config, c) => {
+        const name = c.req.query("name");
+        if (!name) {
+            throw new Error("missing required ?name= query param");
+        }
+        return labelToBadge(name, await getLabelColor(config, config.project, name));
+    });
+    registerBadgeRoute(app, getConfig, "/go-mod.svg", UNKNOWN, "go.mod version", async (config, c) => {
+        const ref = c.req.query("ref") ?? config.ref;
+        const filename = c.req.query("filename") ?? "go.mod";
+        return goModVersionToBadge(await getGoModVersion(config, config.project, ref, filename));
+    });
+    // Visual test page: every native and shields.io badge shape this proxy can produce, for one
+    // project/ref given in the URL. /debug alone falls back to the fixed default project.
+    app.get("/debug", (c) => {
+        let config;
+        try {
+            config = getConfig();
+        }
+        catch (error) {
+            console.error("gitlab-badge-proxy: failed to load config", error);
+            return c.text("gitlab-badge-proxy: config not loaded", 500);
+        }
+        const ref = c.req.query("ref") ?? config.ref;
+        return c.redirect(`/debug/${config.project}?ref=${encodeURIComponent(ref)}`);
+    });
+    app.get("/debug/:project{.+}", (c) => {
+        let config;
+        try {
+            config = getConfig();
+        }
+        catch (error) {
+            console.error("gitlab-badge-proxy: failed to load config", error);
+            return c.text("gitlab-badge-proxy: config not loaded", 500);
+        }
+        const project = c.req.param("project");
+        const ref = c.req.query("ref") ?? config.ref;
+        const origin = new URL(c.req.url).origin;
+        return c.html(renderDebugPage(project, ref, origin));
+    });
+    // Minimal, read-only GitLab API emulation: lets badge generators that build their own GitLab API
+    // URLs (e.g. shields.io's generic `/gitlab/v/release/<project>?gitlab_url=...` badges) point
+    // straight at this proxy instead of the real GitLab host. See API_LITERAL_SUBPATHS above for the
+    // exact set of endpoints this covers.
+    app.get("/api/v4/projects/:rest{.+}", async (c) => {
+        let config;
+        try {
+            config = getConfig();
+        }
+        catch (error) {
+            console.error("gitlab-badge-proxy: failed to load config", error);
+            return apiError("500 Internal Server Error", 500);
+        }
+        const { projectRaw, subpath } = splitProjectApiPath(c.req.param("rest"));
+        const projectPath = decodeURIComponent(projectRaw);
+        if (!config.allowedProjects.includes(projectPath)) {
+            return apiError("404 Project Not Found", 404);
+        }
+        return proxyGitlabApi(config, projectPath, subpath, new URL(c.req.url).search);
+    });
+    // GitLab-shaped badge URLs, e.g. /ardenslab/pm2-dash/badges/master/coverage.svg — drop-in
+    // compatible with GitLab's own badge paths so existing README links keep working when the
+    // GitLab host is swapped for this proxy's. Only projects explicitly whitelisted via
+    // GITLAB_PROJECTS are served; anything else 404s, same as a project GitLab doesn't know about.
+    app.get("/:rest{.+}", async (c) => {
+        const rest = c.req.param("rest");
+        const releaseMatch = RELEASE_PATH_PATTERN.exec(rest);
+        if (releaseMatch) {
+            const [, projectPath] = releaseMatch;
+            let config;
+            try {
+                config = getConfig();
+            }
+            catch (error) {
+                console.error("gitlab-badge-proxy: failed to load config", error);
+                return svgResponse(await fetchBadgeSvg(UNKNOWN_RELEASE), 30);
+            }
+            if (!config.allowedProjects.includes(projectPath)) {
+                return c.notFound();
+            }
+            const { spec, maxAge } = await resolveReleaseSpec(config, projectPath);
+            return svgResponse(await fetchBadgeSvg(spec), maxAge);
+        }
+        const match = BADGE_PATH_PATTERN.exec(rest);
+        if (!match) {
+            return c.notFound();
+        }
+        const [, projectPath, ref, kind] = match;
+        let config;
+        try {
+            config = getConfig();
+        }
+        catch (error) {
+            console.error("gitlab-badge-proxy: failed to load config", error);
+            const fallback = kind === "pipeline" ? UNKNOWN_PIPELINE : UNKNOWN_COVERAGE;
+            return svgResponse(await fetchBadgeSvg(fallback), 30);
+        }
+        if (!config.allowedProjects.includes(projectPath)) {
+            return c.notFound();
+        }
+        const { spec, maxAge } = kind === "pipeline"
+            ? await resolvePipelineSpec(config, projectPath, ref)
+            : await resolveCoverageSpec(config, projectPath, ref, c.req.query("job"));
+        return svgResponse(await fetchBadgeSvg(spec), maxAge);
+    });
+    return app;
+}
+export { buildShieldsUrl };
+export const app = createApp();

package/dist/src/badge.d.ts

@@ -0,0 +1,28 @@
+export interface BadgeSpec {
+    label: string;
+    message: string;
+    color: string;
+}
+/** Status values documented at https://docs.gitlab.com/ee/api/pipelines.html */
+export declare function pipelineStatusToBadge(status: string): BadgeSpec;
+export declare function coverageToBadge(coverage: number | null): BadgeSpec;
+export declare function releaseToBadge(release: {
+    tagName: string;
+} | null): BadgeSpec;
+export declare function tagToBadge(tag: {
+    name: string;
+} | null): BadgeSpec;
+export declare function goModVersionToBadge(version: string | null): BadgeSpec;
+export declare function starsToBadge(count: number): BadgeSpec;
+export declare function forksToBadge(count: number): BadgeSpec;
+export declare function contributorsToBadge(count: number): BadgeSpec;
+export declare function issuesToBadge(count: number, state: string, labels: string | undefined): BadgeSpec;
+export declare function mergeRequestsToBadge(count: number, state: string, labels: string | undefined): BadgeSpec;
+export declare function lastCommitToBadge(committedDate: string | null): BadgeSpec;
+export declare function licenseToBadge(name: string | null): BadgeSpec;
+export declare function topLanguageToBadge(languages: Record<string, number>): BadgeSpec;
+export declare function languagesCountToBadge(languages: Record<string, number>): BadgeSpec;
+export declare function labelToBadge(name: string, color: string): BadgeSpec;
+export declare function buildShieldsUrl(spec: BadgeSpec): string;
+export declare function fetchBadgeSvg(spec: BadgeSpec): Promise<string>;
+//# sourceMappingURL=badge.d.ts.map

package/dist/src/badge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../src/badge.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAqB/D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAMlE;AAaD,wBAAgB,cAAc,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAK7E;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAKlE;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAKrE;AAaD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAErD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAErD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAE5D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAGjG;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAIxG;AAcD,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAKzE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAK7D;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAO/E;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAElF;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAEnE;AAOD,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAGvD;AASD,wBAAsB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAUpE"}

package/dist/src/badge.js

@@ -0,0 +1,151 @@
+/** Status values documented at https://docs.gitlab.com/ee/api/pipelines.html */
+export function pipelineStatusToBadge(status) {
+    switch (status) {
+        case "success":
+            return { label: "pipeline", message: "passing", color: "brightgreen" };
+        case "failed":
+            return { label: "pipeline", message: "failing", color: "red" };
+        case "running":
+        case "pending":
+        case "preparing":
+        case "waiting_for_resource":
+        case "created":
+            return { label: "pipeline", message: "running", color: "yellow" };
+        case "canceled":
+        case "skipped":
+            return { label: "pipeline", message: status, color: "lightgrey" };
+        case "manual":
+        case "scheduled":
+            return { label: "pipeline", message: "pending", color: "yellow" };
+        default:
+            return { label: "pipeline", message: "unknown", color: "lightgrey" };
+    }
+}
+export function coverageToBadge(coverage) {
+    if (coverage === null) {
+        return { label: "coverage", message: "unknown", color: "lightgrey" };
+    }
+    const color = coverage >= 90 ? "brightgreen" : coverage >= 75 ? "green" : coverage >= 50 ? "yellow" : "red";
+    return { label: "coverage", message: `${Math.round(coverage * 10) / 10}%`, color };
+}
+/** Mirrors shields.io's version-badge coloring: 0.x and alpha/beta/rc-like tags render orange, everything else blue. */
+function versionColor(tagName) {
+    const bare = tagName.replace(/^v/, "");
+    const isPrerelease = bare.startsWith("0") || /alpha|beta|snapshot|dev|pre|rc|scm|cvs/i.test(tagName);
+    return isPrerelease ? "orange" : "blue";
+}
+function withVPrefix(tagName) {
+    return tagName.startsWith("v") ? tagName : `v${tagName}`;
+}
+export function releaseToBadge(release) {
+    if (release === null) {
+        return { label: "release", message: "unknown", color: "lightgrey" };
+    }
+    return { label: "release", message: withVPrefix(release.tagName), color: versionColor(release.tagName) };
+}
+export function tagToBadge(tag) {
+    if (tag === null) {
+        return { label: "tag", message: "unknown", color: "lightgrey" };
+    }
+    return { label: "tag", message: withVPrefix(tag.name), color: versionColor(tag.name) };
+}
+export function goModVersionToBadge(version) {
+    if (version === null) {
+        return { label: "Go", message: "unknown", color: "lightgrey" };
+    }
+    return { label: "Go", message: withVPrefix(version), color: versionColor(version) };
+}
+/** Abbreviates large counts the way shields.io's badges do, e.g. 12345 -> "12.3k". */
+function metric(count) {
+    if (count >= 1_000_000) {
+        return `${(count / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+    }
+    if (count >= 1_000) {
+        return `${(count / 1_000).toFixed(1).replace(/\.0$/, "")}k`;
+    }
+    return String(count);
+}
+export function starsToBadge(count) {
+    return { label: "stars", message: metric(count), color: "blue" };
+}
+export function forksToBadge(count) {
+    return { label: "forks", message: metric(count), color: "blue" };
+}
+export function contributorsToBadge(count) {
+    return { label: "contributors", message: metric(count), color: "blue" };
+}
+export function issuesToBadge(count, state, labels) {
+    const label = labels ? `${labels} issues` : "issues";
+    return { label, message: `${metric(count)} ${state}`, color: count > 0 ? "yellow" : "brightgreen" };
+}
+export function mergeRequestsToBadge(count, state, labels) {
+    const label = labels ? `${labels} merge requests` : "merge requests";
+    const message = `${count > 10000 ? "more than " : ""}${metric(count)} ${state}`;
+    return { label, message, color: "blue" };
+}
+/** Coarse relative-time formatting, e.g. "today" / "3 days ago" / "2 months ago". */
+function relativeDate(iso) {
+    const diffDays = Math.floor((Date.now() - new Date(iso).getTime()) / 86_400_000);
+    if (diffDays < 1)
+        return "today";
+    if (diffDays === 1)
+        return "yesterday";
+    if (diffDays < 30)
+        return `${diffDays} days ago`;
+    const diffMonths = Math.floor(diffDays / 30);
+    if (diffMonths < 12)
+        return `${diffMonths} month${diffMonths > 1 ? "s" : ""} ago`;
+    const diffYears = Math.floor(diffMonths / 12);
+    return `${diffYears} year${diffYears > 1 ? "s" : ""} ago`;
+}
+export function lastCommitToBadge(committedDate) {
+    if (committedDate === null) {
+        return { label: "last commit", message: "unknown", color: "lightgrey" };
+    }
+    return { label: "last commit", message: relativeDate(committedDate), color: "blue" };
+}
+export function licenseToBadge(name) {
+    if (name === null) {
+        return { label: "license", message: "not specified", color: "lightgrey" };
+    }
+    return { label: "license", message: name, color: "blue" };
+}
+export function topLanguageToBadge(languages) {
+    const entries = Object.entries(languages);
+    if (entries.length === 0) {
+        return { label: "language", message: "unknown", color: "lightgrey" };
+    }
+    const [topLanguage, percentage] = entries.reduce((a, b) => (b[1] > a[1] ? b : a));
+    return { label: topLanguage.toLowerCase(), message: `${percentage.toFixed(1)}%`, color: "blue" };
+}
+export function languagesCountToBadge(languages) {
+    return { label: "languages", message: metric(Object.keys(languages).length), color: "blue" };
+}
+export function labelToBadge(name, color) {
+    return { label: "label", message: name, color: color.replace(/^#/, "") };
+}
+/** Escaping rules for shields.io's static badge endpoint. */
+function escapeSegment(segment) {
+    return segment.replace(/-/g, "--").replace(/_/g, "__").replace(/ /g, "_");
+}
+export function buildShieldsUrl(spec) {
+    const segments = [spec.label, spec.message, spec.color].map(escapeSegment).map(encodeURIComponent);
+    return `https://img.shields.io/badge/${segments.join("-")}.svg`;
+}
+/** Static fallback badge, used when shields.io itself is unreachable so we never throw from here. */
+const STATIC_UNKNOWN_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="98" height="20" role="img" aria-label="status: unknown">' +
+    '<rect width="98" height="20" fill="#9f9f9f" rx="3"/>' +
+    '<text x="49" y="14" fill="#fff" font-family="Verdana,sans-serif" font-size="11" text-anchor="middle">status: unknown</text>' +
+    "</svg>";
+export async function fetchBadgeSvg(spec) {
+    try {
+        const response = await fetch(buildShieldsUrl(spec));
+        if (!response.ok) {
+            return STATIC_UNKNOWN_SVG;
+        }
+        return await response.text();
+    }
+    catch {
+        return STATIC_UNKNOWN_SVG;
+    }
+}

package/dist/src/config.d.ts

@@ -0,0 +1,21 @@
+export interface Config {
+    /** Base URL of the private GitLab instance, e.g. https://gitlab.example.net. Never logged or echoed back. */
+    gitlabUrl: string;
+    /** Token with the read_api scope on the target project. Never logged or echoed back. */
+    gitlabToken: string;
+    /** Project path (`group/name`) or numeric project ID. */
+    project: string;
+    /** Branch/ref the badges are computed for. */
+    ref: string;
+    /** Edge/CDN cache lifetime in seconds for successful responses. */
+    cacheMaxAgeSeconds: number;
+    /**
+     * Project paths (`group/name`, nested groups allowed) that may be requested through the
+     * GitLab-shaped `/:project/badges/:ref/*.svg` routes. Empty by default: those routes stay
+     * disabled until a project is explicitly whitelisted here, so the proxy never turns into an
+     * open oracle for whatever projects the token happens to have read access to.
+     */
+    allowedProjects: string[];
+}
+export declare function loadConfig(env?: Record<string, string | undefined>): Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/src/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACrB,6GAA6G;IAC7G,SAAS,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAUD,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAYxF"}

package/dist/src/config.js

@@ -0,0 +1,20 @@
+function required(env, name) {
+    const value = env[name];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+export function loadConfig(env = process.env) {
+    return {
+        gitlabUrl: required(env, "GITLAB_URL").replace(/\/+$/, ""),
+        gitlabToken: required(env, "GITLAB_TOKEN"),
+        project: required(env, "GITLAB_PROJECT"),
+        ref: env.GITLAB_REF || "master",
+        cacheMaxAgeSeconds: env.CACHE_MAX_AGE_SECONDS ? Number(env.CACHE_MAX_AGE_SECONDS) : 60,
+        allowedProjects: (env.GITLAB_PROJECTS ?? "")
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0),
+    };
+}

package/dist/src/gitlab.d.ts

@@ -0,0 +1,31 @@
+import type { Config } from "./config.js";
+export interface PipelineSummary {
+    id: number;
+    status: string;
+}
+export interface ReleaseSummary {
+    name: string;
+    tagName: string;
+}
+export declare function getLatestPipeline(config: Config, projectPath: string, ref: string): Promise<PipelineSummary | null>;
+export declare function getPipelineCoverage(config: Config, projectPath: string, pipelineId: number): Promise<number | null>;
+/** Coverage reported by one specific job in the pipeline, mirroring GitLab's own `?job=` badge param. */
+export declare function getJobCoverage(config: Config, projectPath: string, pipelineId: number, jobName: string): Promise<number | null>;
+export declare function getLatestRelease(config: Config, projectPath: string): Promise<ReleaseSummary | null>;
+export declare function getStarsCount(config: Config, projectPath: string): Promise<number>;
+export declare function getForksCount(config: Config, projectPath: string): Promise<number>;
+export declare function getContributorsCount(config: Config, projectPath: string): Promise<number>;
+export type IssueState = "opened" | "closed" | "all";
+export declare function getIssuesCount(config: Config, projectPath: string, state: IssueState, labels: string | undefined): Promise<number>;
+export type MergeRequestState = "opened" | "closed" | "merged" | "locked" | "all";
+export declare function getMergeRequestsCount(config: Config, projectPath: string, state: MergeRequestState, labels: string | undefined): Promise<number>;
+export declare function getLastCommitDate(config: Config, projectPath: string, ref: string | undefined, path: string | undefined): Promise<string | null>;
+export declare function getLicenseName(config: Config, projectPath: string): Promise<string | null>;
+export declare function getLatestTag(config: Config, projectPath: string): Promise<{
+    name: string;
+} | null>;
+/** Language name -> percentage of the codebase, e.g. `{ TypeScript: 92.1, JavaScript: 7.9 }`. */
+export declare function getLanguages(config: Config, projectPath: string): Promise<Record<string, number>>;
+export declare function getLabelColor(config: Config, projectPath: string, name: string): Promise<string>;
+export declare function getGoModVersion(config: Config, projectPath: string, ref: string, filename: string): Promise<string | null>;
+//# sourceMappingURL=gitlab.d.ts.map

package/dist/src/gitlab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitlab.d.ts","sourceRoot":"","sources":["../../src/gitlab.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAiCD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAIjC;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOxB;AAED,yGAAyG;AACzG,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAcxB;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAQ1G;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGxF;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGxF;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO/F;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;AAErD,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;AAElF,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxB;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKhG;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAOxG;AAED,iGAAiG;AACjG,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAEvG;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGtG;AAID,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB"}

package/dist/src/gitlab.js

@@ -0,0 +1,116 @@
+async function gitlabRequest(config, projectPath, path) {
+    const projectSegment = encodeURIComponent(projectPath);
+    const url = `${config.gitlabUrl}/api/v4/projects/${projectSegment}${path}`;
+    const response = await fetch(url, {
+        headers: { "PRIVATE-TOKEN": config.gitlabToken },
+    });
+    if (!response.ok) {
+        throw new Error(`GitLab API responded with ${response.status}`);
+    }
+    return response;
+}
+async function gitlabGet(config, projectPath, path) {
+    return (await gitlabRequest(config, projectPath, path)).json();
+}
+async function gitlabGetText(config, projectPath, path) {
+    return (await gitlabRequest(config, projectPath, path)).text();
+}
+/** GitLab exposes some aggregate counts (contributors, merge requests) only via the `x-total` header. */
+async function gitlabGetTotalHeader(config, projectPath, path) {
+    const response = await gitlabRequest(config, projectPath, path);
+    const total = response.headers.get("x-total");
+    if (total === null) {
+        return null;
+    }
+    const value = Number.parseInt(total, 10);
+    return Number.isFinite(value) ? value : null;
+}
+export async function getLatestPipeline(config, projectPath, ref) {
+    const params = new URLSearchParams({ ref, order_by: "id", sort: "desc", per_page: "1" });
+    const pipelines = (await gitlabGet(config, projectPath, `/pipelines?${params}`));
+    return pipelines[0] ?? null;
+}
+export async function getPipelineCoverage(config, projectPath, pipelineId) {
+    const pipeline = (await gitlabGet(config, projectPath, `/pipelines/${pipelineId}`));
+    if (!pipeline.coverage) {
+        return null;
+    }
+    const value = Number.parseFloat(pipeline.coverage);
+    return Number.isFinite(value) ? value : null;
+}
+/** Coverage reported by one specific job in the pipeline, mirroring GitLab's own `?job=` badge param. */
+export async function getJobCoverage(config, projectPath, pipelineId, jobName) {
+    const params = new URLSearchParams({ per_page: "100" });
+    const jobs = (await gitlabGet(config, projectPath, `/pipelines/${pipelineId}/jobs?${params}`));
+    const matches = jobs.filter((job) => job.name === jobName && job.coverage != null);
+    if (matches.length === 0) {
+        return null;
+    }
+    const latest = matches.reduce((a, b) => (b.id > a.id ? b : a));
+    const value = typeof latest.coverage === "string" ? Number.parseFloat(latest.coverage) : latest.coverage;
+    return Number.isFinite(value) ? value : null;
+}
+export async function getLatestRelease(config, projectPath) {
+    const params = new URLSearchParams({ order_by: "released_at", sort: "desc", per_page: "1" });
+    const releases = (await gitlabGet(config, projectPath, `/releases?${params}`));
+    const release = releases[0];
+    return release ? { name: release.name, tagName: release.tag_name } : null;
+}
+export async function getStarsCount(config, projectPath) {
+    const project = (await gitlabGet(config, projectPath, ""));
+    return project.star_count;
+}
+export async function getForksCount(config, projectPath) {
+    const project = (await gitlabGet(config, projectPath, ""));
+    return project.forks_count;
+}
+export async function getContributorsCount(config, projectPath) {
+    const total = await gitlabGetTotalHeader(config, projectPath, `/repository/contributors?${new URLSearchParams({ page: "1", per_page: "1" })}`);
+    return total ?? 0;
+}
+export async function getIssuesCount(config, projectPath, state, labels) {
+    const params = labels ? `?${new URLSearchParams({ labels })}` : "";
+    const { statistics } = (await gitlabGet(config, projectPath, `/issues_statistics${params}`));
+    return statistics.counts[state];
+}
+export async function getMergeRequestsCount(config, projectPath, state, labels) {
+    const params = new URLSearchParams({ state, page: "1", per_page: "1" });
+    if (labels) {
+        params.set("labels", labels);
+    }
+    const total = await gitlabGetTotalHeader(config, projectPath, `/merge_requests?${params}`);
+    // GitLab omits x-total once a query matches more than 10k records.
+    return total ?? 10001;
+}
+export async function getLastCommitDate(config, projectPath, ref, path) {
+    const params = new URLSearchParams({ per_page: "1" });
+    if (ref)
+        params.set("ref_name", ref);
+    if (path)
+        params.set("path", path);
+    const commits = (await gitlabGet(config, projectPath, `/repository/commits?${params}`));
+    return commits[0]?.committed_date ?? null;
+}
+export async function getLicenseName(config, projectPath) {
+    const project = (await gitlabGet(config, projectPath, `?${new URLSearchParams({ license: "1" })}`));
+    return project.license?.name ?? null;
+}
+export async function getLatestTag(config, projectPath) {
+    const tags = (await gitlabGet(config, projectPath, `/repository/tags?${new URLSearchParams({ order_by: "updated" })}`));
+    return tags[0] ?? null;
+}
+/** Language name -> percentage of the codebase, e.g. `{ TypeScript: 92.1, JavaScript: 7.9 }`. */
+export async function getLanguages(config, projectPath) {
+    return (await gitlabGet(config, projectPath, "/languages"));
+}
+export async function getLabelColor(config, projectPath, name) {
+    const label = (await gitlabGet(config, projectPath, `/labels/${encodeURIComponent(name)}`));
+    return label.color;
+}
+const GO_VERSION_PATTERN = /^go ([^/\s]+)(\s*\/.+)?$/m;
+export async function getGoModVersion(config, projectPath, ref, filename) {
+    const params = new URLSearchParams({ ref });
+    const content = await gitlabGetText(config, projectPath, `/repository/files/${encodeURIComponent(filename)}/raw?${params}`);
+    const match = GO_VERSION_PATTERN.exec(content);
+    return match ? match[1] : null;
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "gitlab-badge-proxy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Server-side proxy that turns private GitLab pipeline/coverage status into public SVG badges, without ever exposing the GitLab instance's URL to clients.",
+  "type": "module",
+  "license": "MIT",
+  "author": "ArdensLab",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArdensLab/gitlab-badge-proxy.git"
+  },
+  "keywords": [
+    "gitlab",
+    "badge",
+    "shields.io",
+    "pipeline",
+    "coverage",
+    "svg",
+    "proxy",
+    "hono"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/app.d.ts",
+      "default": "./dist/src/app.js"
+    }
+  },
+  "types": "./dist/src/app.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "dev": "npm run build && node --env-file=.env.local scripts/dev-server.mjs",
+    "dev:vercel": "vercel dev",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "hono": "^4.6.0"
+  },
+  "devDependencies": {
+    "@hono/node-server": "^2.1.5",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^5.0.5"
+  }
+}