@hansenexus/hud 0.3.0 → 0.4.0

package/dist/plugins/ops/server.js

@@ -0,0 +1,380 @@
+import { i as definePlugin } from "../../plugins-DVy_vaYr.js";
+import { i as OPS_CAPABILITY, n as combineStates, t as TELEMETRY_RANGES } from "../../types-QJUajwWq.js";
+//#region src/plugins/ops/errors.ts
+/**
+* A provider failure whose message is safe to send to the client (it names
+* the upstream and its status, never a URL with credentials or a token).
+* The routes answer 502 with it; any other error becomes a generic 502.
+*/
+var OpsProviderError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "OpsProviderError";
+	}
+};
+/** Upstream calls give up after this, so a dead host never hangs a panel. */
+const UPSTREAM_TIMEOUT_MS = 5e3;
+//#endregion
+//#region src/plugins/ops/env.ts
+/** Reads a server env var. Absent `process` (MSW in a browser) reads as unset. */
+function readEnv(name) {
+	if (typeof process === "undefined") return void 0;
+	const value = process.env[name];
+	return value === "" ? void 0 : value;
+}
+/** `process.cwd()`, or undefined where there is none. */
+function currentDir() {
+	const proc = globalThis.process;
+	return typeof proc?.cwd === "function" ? proc.cwd() : void 0;
+}
+//#endregion
+//#region src/plugins/ops/git-head.ts
+/**
+* Branch named by a `HEAD` file: `ref: refs/heads/feat/x` → `feat/x`.
+* A detached HEAD (a bare sha) names no branch.
+*/
+function parseHead(head) {
+	return /^ref:\s*refs\/heads\/(.+)$/.exec(head.trim())?.[1] ?? null;
+}
+/** Git dir a worktree's `.git` file points at: `gitdir: /repo/.git/worktrees/x`. */
+function parseGitFile(content) {
+	return /^gitdir:\s*(.+)$/m.exec(content)?.[1]?.trim() ?? null;
+}
+function parents(dir) {
+	const parts = dir.replace(/[\\/]+$/, "").split(/[\\/]/);
+	const dirs = [];
+	for (let i = parts.length; i > 0; i--) dirs.push(parts.slice(0, i).join("/") || "/");
+	return dirs;
+}
+/**
+* Branch of the git checkout containing `cwd` (default `process.cwd()`), read
+* from `.git/HEAD` without spawning git. Walks up, so an app inside a monorepo
+* finds the root's `.git`; follows a worktree's `.git` file. Null when there
+* is no checkout, no filesystem (edge runtime, browser) or HEAD is detached.
+*/
+async function readGitBranch(cwd = currentDir()) {
+	if (!cwd) return null;
+	let fs;
+	try {
+		fs = await import("node:fs/promises");
+	} catch {
+		return null;
+	}
+	for (const dir of parents(cwd)) {
+		const dotGit = `${dir === "/" ? "" : dir}/.git`;
+		try {
+			return parseHead(await fs.readFile(`${dotGit}/HEAD`, "utf8"));
+		} catch {}
+		try {
+			const gitDir = parseGitFile(await fs.readFile(dotGit, "utf8"));
+			if (gitDir) {
+				const absolute = /^([\\/]|[A-Za-z]:)/.test(gitDir) ? gitDir : `${dir}/${gitDir}`;
+				return parseHead(await fs.readFile(`${absolute}/HEAD`, "utf8"));
+			}
+		} catch {}
+	}
+	return null;
+}
+//#endregion
+//#region src/plugins/ops/github-actions.ts
+const BRANCH_ENV = [
+	"HUD_GIT_BRANCH",
+	"VERCEL_GIT_COMMIT_REF",
+	"GITHUB_HEAD_REF",
+	"GITHUB_REF_NAME"
+];
+const REPO = /^[\w.-]+\/[\w.-]+$/;
+/** GitHub's status + conclusion pair as one state. */
+function githubRunState(status, conclusion) {
+	if (status === "in_progress") return "running";
+	if (status !== "completed") return "queued";
+	switch (conclusion) {
+		case "success": return "success";
+		case "failure":
+		case "timed_out":
+		case "startup_failure":
+		case "action_required": return "failure";
+		case "cancelled":
+		case "stale": return "cancelled";
+		default: return "neutral";
+	}
+}
+function toRun(run) {
+	const name = run.name ?? `workflow ${run.workflow_id}`;
+	const title = run.display_title ?? run.head_commit?.message.split("\n")[0] ?? name;
+	return {
+		id: String(run.id),
+		name,
+		title,
+		state: githubRunState(run.status, run.conclusion),
+		...run.head_branch ? { branch: run.head_branch } : {},
+		sha: run.head_sha.slice(0, 7),
+		url: run.html_url,
+		startedAt: run.created_at
+	};
+}
+/**
+* State of the newest commit among `runs` (newest first): the latest run of
+* each workflow on that commit, combined.
+*/
+function headState(runs) {
+	const head = runs[0]?.head_sha;
+	if (!head) return {
+		sha: null,
+		state: null
+	};
+	const latest = /* @__PURE__ */ new Map();
+	for (const run of runs) if (run.head_sha === head && !latest.has(run.workflow_id)) latest.set(run.workflow_id, run);
+	const states = [...latest.values()].map((run) => githubRunState(run.status, run.conclusion));
+	return {
+		sha: head.slice(0, 7),
+		state: combineStates(states)
+	};
+}
+/**
+* GitHub Actions as the `ops` plugin's CI provider. Server only: the token is
+* read from env on each request and only ever sent to GitHub.
+*
+* ```ts
+* ops({ ci: githubActions({ repo: "hansenexus/hud" }) })
+* ```
+*/
+function githubActions(options) {
+	const { repo, tokenEnv = "GITHUB_TOKEN", limit = 10, cacheSeconds = 15 } = options;
+	if (!REPO.test(repo)) throw new Error(`hud ops: githubActions repo "${repo}" must be owner/name`);
+	const apiUrl = (options.apiUrl ?? "https://api.github.com").replace(/\/+$/, "");
+	const cache = /* @__PURE__ */ new Map();
+	async function resolveBranch() {
+		const { branch } = options;
+		if (typeof branch === "string") return branch;
+		if (typeof branch === "function") return await branch() ?? null;
+		for (const name of BRANCH_ENV) {
+			const value = readEnv(name);
+			if (value) return value;
+		}
+		return readGitBranch();
+	}
+	async function fetchRuns(token, branch) {
+		const params = new URLSearchParams({ per_page: String(Math.max(limit, 20)) });
+		if (branch) params.set("branch", branch);
+		let res;
+		try {
+			res = await fetch(`${apiUrl}/repos/${repo}/actions/runs?${params}`, {
+				headers: {
+					authorization: `Bearer ${token}`,
+					accept: "application/vnd.github+json",
+					"x-github-api-version": "2022-11-28"
+				},
+				signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS)
+			});
+		} catch {
+			throw new OpsProviderError("GitHub unreachable");
+		}
+		if (!res.ok) throw new OpsProviderError(`GitHub answered ${res.status}`);
+		return (await res.json()).workflow_runs ?? [];
+	}
+	function cachedRuns(token, branch) {
+		const key = branch ?? "";
+		const hit = cache.get(key);
+		if (hit && Date.now() - hit.at < cacheSeconds * 1e3) return hit.value;
+		const value = fetchRuns(token, branch);
+		cache.set(key, {
+			at: Date.now(),
+			value
+		});
+		value.catch(() => cache.delete(key));
+		return value;
+	}
+	return {
+		name: "github-actions",
+		async snapshot() {
+			const branch = await resolveBranch();
+			const base = {
+				provider: "github-actions",
+				repo,
+				branch
+			};
+			const token = readEnv(tokenEnv);
+			if (!token) return {
+				...base,
+				configured: false,
+				missing: tokenEnv,
+				state: null,
+				sha: null,
+				runs: []
+			};
+			const runs = await cachedRuns(token, branch);
+			const head = branch ? headState(runs) : {
+				sha: null,
+				state: null
+			};
+			return {
+				...base,
+				configured: true,
+				...head,
+				runs: runs.slice(0, limit).map(toRun)
+			};
+		}
+	};
+}
+//#endregion
+//#region src/plugins/ops/signoz.ts
+const SERVICE = /^[\w.-]{1,128}$/;
+const RANGE_SECONDS = {
+	"1h": 3600,
+	"24h": 86400,
+	"7d": 604800
+};
+const RANGE_STEP = {
+	"1h": "5m",
+	"24h": "15m",
+	"7d": "1h"
+};
+/** PromQL for the three numbers, from SigNoz's span metrics. */
+function signozQueries(service) {
+	const label = `service_name="${service}"`;
+	return {
+		errorRate: `sum(rate(signoz_calls_total{${label},status_code="STATUS_CODE_ERROR"}[5m]))`,
+		p95Ms: `histogram_quantile(0.95, sum(rate(signoz_latency_bucket{${label}}[5m])) by (le))`,
+		requestRate: `sum(rate(signoz_calls_total{${label}}[5m]))`
+	};
+}
+/** Latest sample of the first series; null when there is none or it is not a number. */
+function latestValue(result) {
+	const values = result.data?.result?.[0]?.values;
+	const last = values?.[values.length - 1];
+	if (!last) return null;
+	const value = Number.parseFloat(last[1]);
+	return Number.isFinite(value) ? value : null;
+}
+/**
+* SigNoz as the `ops` plugin's telemetry provider: error rate, p95 latency and
+* request rate of one service over its PromQL `query_range` API. Server only:
+* the URL and API key come from env on each request.
+*
+* ```ts
+* ops({ telemetry: signoz({ service: "hansenexus" }) })
+* ```
+*/
+function signoz(options) {
+	const { service, urlEnv = "SIGNOZ_QUERY_URL", apiKeyEnv = "SIGNOZ_API_KEY" } = options;
+	if (!SERVICE.test(service)) throw new Error(`hud ops: signoz service "${service}" is not a valid name`);
+	const queries = signozQueries(service);
+	async function query(baseUrl, apiKey, promql, range) {
+		const end = Math.floor(Date.now() / 1e3);
+		const params = new URLSearchParams({
+			query: promql,
+			start: String(end - RANGE_SECONDS[range]),
+			end: String(end),
+			step: RANGE_STEP[range]
+		});
+		const res = await fetch(`${baseUrl.replace(/\/+$/, "")}/api/v1/query_range?${params}`, {
+			headers: apiKey ? { "SIGNOZ-API-KEY": apiKey } : {},
+			signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS)
+		});
+		if (!res.ok) throw new OpsProviderError(`SigNoz answered ${res.status}`);
+		return latestValue(await res.json());
+	}
+	return {
+		name: "signoz",
+		async snapshot(range) {
+			const base = {
+				provider: "signoz",
+				service,
+				range
+			};
+			const url = readEnv(urlEnv);
+			if (!url) return {
+				...base,
+				configured: false,
+				missing: urlEnv,
+				errorRate: null,
+				p95Ms: null,
+				requestRate: null
+			};
+			const apiKey = readEnv(apiKeyEnv);
+			const [errorRate, p95Ms, requestRate] = await Promise.allSettled([
+				query(url, apiKey, queries.errorRate, range),
+				query(url, apiKey, queries.p95Ms, range),
+				query(url, apiKey, queries.requestRate, range)
+			]);
+			if (errorRate.status === "rejected" && p95Ms.status === "rejected" && requestRate.status === "rejected") throw errorRate.reason instanceof OpsProviderError ? errorRate.reason : new OpsProviderError("SigNoz unreachable");
+			const value = (r) => r.status === "fulfilled" ? r.value : null;
+			return {
+				...base,
+				configured: true,
+				errorRate: value(errorRate),
+				p95Ms: value(p95Ms),
+				requestRate: value(requestRate)
+			};
+		}
+	};
+}
+//#endregion
+//#region src/plugins/ops/server.ts
+const NO_STORE = { "cache-control": "no-store" };
+function failed(error, what) {
+	if (error instanceof OpsProviderError) return Response.json({
+		ok: false,
+		error: error.message
+	}, {
+		status: 502,
+		headers: NO_STORE
+	});
+	console.error(`hud ops: ${what} failed`, error);
+	return Response.json({
+		ok: false,
+		error: `${what} failed`
+	}, {
+		status: 502,
+		headers: NO_STORE
+	});
+}
+function isRange(value) {
+	return TELEMETRY_RANGES.includes(value);
+}
+/**
+* Server half of the `ops` plugin. Pass it to `createHudHandler`; each
+* provider adds its route, so an app without telemetry serves no
+* `/telemetry`. Tokens and keys stay in the providers: responses carry
+* run data, numbers and the name of a missing env var, never a secret.
+*/
+function ops({ ci, telemetry } = {}) {
+	const routes = {};
+	if (ci) routes["/ci"] = { GET: async () => {
+		try {
+			const [snapshot, deployment] = await Promise.all([ci.snapshot(), ci.deployment?.()]);
+			const body = {
+				ok: true,
+				...snapshot,
+				...ci.deployment ? { deployment: deployment ?? null } : {}
+			};
+			return Response.json(body, { headers: NO_STORE });
+		} catch (error) {
+			return failed(error, ci.name);
+		}
+	} };
+	if (telemetry) routes["/telemetry"] = { GET: async (request) => {
+		const range = new URL(request.url).searchParams.get("range") ?? "1h";
+		if (!isRange(range)) return Response.json({
+			ok: false,
+			error: `range must be one of ${TELEMETRY_RANGES.join(", ")}`
+		}, { status: 400 });
+		try {
+			const body = {
+				ok: true,
+				...await telemetry.snapshot(range)
+			};
+			return Response.json(body, { headers: NO_STORE });
+		} catch (error) {
+			return failed(error, telemetry.name);
+		}
+	} };
+	return definePlugin({
+		id: "ops",
+		capability: OPS_CAPABILITY,
+		routes
+	});
+}
+//#endregion
+export { OpsProviderError, githubActions, ops, signoz };

package/dist/plugins/ops.d.ts

@@ -0,0 +1,26 @@
+import { c as HudPluginProps } from "../plugins-CQ_0w1ot.js";
+import { c as TelemetryRange, i as CiRun, l as TelemetryResponse, o as CiState, r as CiResponse, t as CiDeployment } from "../types-f3jlNxzw.js";
+//#region src/plugins/ops/index.d.ts
+declare function OpsPill({ ctx }: HudPluginProps): import("react").JSX.Element;
+export interface OpsOptions {
+  /** Show the CI section and the CI state in the pill. Default true. */
+  ci?: boolean;
+  /** Show the telemetry section. Default true. */
+  telemetry?: boolean;
+}
+/**
+ * CI and telemetry: the pill shows the CI state of the branch the server runs
+ * on, the panel lists recent runs, the deployment (when the CI provider knows
+ * it) and error rate, p95 and request rate. Client half; the providers live in
+ * the server half, `@hansenexus/hud/plugins/ops/server`, which reads tokens
+ * from env and never sends them to the browser.
+ */
+export declare function ops({ ci, telemetry }?: OpsOptions): {
+  readonly id: "ops";
+  readonly title: "Ops";
+  readonly capability: "cicd.read";
+  readonly panel: ({ ctx }: HudPluginProps) => import("react").JSX.Element;
+  readonly pill?: typeof OpsPill;
+};
+//#endregion
+export type { CiDeployment, CiResponse, CiRun, CiState, TelemetryRange, TelemetryResponse };