@hansenexus/hud 0.2.0 → 0.4.0

package/dist/plugins/access.d.ts

@@ -0,0 +1,41 @@
+import { c as HudPluginProps, r as HudCapability } from "../plugins-CQ_0w1ot.js";
+import "../index-BYsdS-7d.js";
+import { c as CAPABILITY_MATRIX, d as hasCapability, i as resolveHudAccess, l as CapabilityMatrixOverride, n as HudAccess, r as hudRequiresUnlock, s as ACCESS_UNLOCK_CAPABILITY, u as HUD_CAPABILITIES } from "../access-CNvJOwKM.js";
+//#region src/plugins/access/access-panel.d.ts
+declare function AccessPill(): import("react").JSX.Element;
+//#endregion
+//#region src/plugins/access/unlock-store.d.ts
+type UnlockStatus = "checking" | "locked" | "unlocked" | "unconfigured";
+/**
+ * `HudAccessControl.useUnlocked`: development is open, a disabled or unknown
+ * tier never unlocks, every deployed tier asks the server once per mount.
+ */
+declare function useUnlocked(envName: string, apiBase: string): boolean;
+//#endregion
+//#region src/plugins/access/index.d.ts
+export interface AccessOptions {
+  /** Replaces the default matrix's list for a deployed tier. Keep it equal to the server half's. */
+  matrix?: CapabilityMatrixOverride;
+}
+/**
+ * Opt-in for deployed tiers. Without it `defineHud` renders nothing outside
+ * development. With it the HUD follows the env ladder: a tier's capability
+ * matrix narrows the plugins, and until the operator unlocks with the
+ * server's password only this plugin's lock shows.
+ *
+ * Client half; the password check lives in `@hansenexus/hud/plugins/access/server`
+ * (`accessServer()` + `accessGuard()`), and the password never reaches the browser.
+ */
+export declare function access(options?: AccessOptions): {
+  readonly id: "access";
+  readonly title: "Access";
+  readonly capability: "access.unlock";
+  readonly pill: typeof AccessPill;
+  readonly panel: ({ ctx }: HudPluginProps) => import("react").JSX.Element;
+  readonly access: {
+    readonly can: (env: string, capability: HudCapability) => boolean;
+    readonly useUnlocked: typeof useUnlocked;
+  };
+};
+//#endregion
+export { ACCESS_UNLOCK_CAPABILITY, CAPABILITY_MATRIX, type CapabilityMatrixOverride, HUD_CAPABILITIES, type HudAccess, type UnlockStatus, hasCapability, hudRequiresUnlock, resolveHudAccess };

package/dist/plugins/access.js

@@ -0,0 +1,250 @@
+import { i as definePlugin, n as HudApiError } from "../plugins-DVy_vaYr.js";
+import { d as hudUnlockTtlMs, i as hasCapability, l as hudRequiresUnlock, n as CAPABILITY_MATRIX, o as resolveMatrix, p as resolveHudAccess, r as HUD_CAPABILITIES, s as toHudEnv, t as ACCESS_UNLOCK_CAPABILITY } from "../capabilities-CjulXFQX.js";
+import { useEffect, useState, useSyncExternalStore } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/plugins/access/unlock-store.ts
+/**
+* Unlock state of the page's HUD. The browser never sees the password or the
+* token: the cookie is httpOnly and only the server can judge it, so this
+* store asks the unlock route rather than reading anything locally.
+*/
+let state = {
+	env: "development",
+	status: "checking",
+	error: null
+};
+const listeners = /* @__PURE__ */ new Set();
+function set(patch) {
+	state = {
+		...state,
+		...patch
+	};
+	for (const listener of listeners) listener();
+}
+function subscribe(listener) {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}
+const getState = () => state;
+function useUnlockState() {
+	return useSyncExternalStore(subscribe, getState, getState);
+}
+function errorOf(body) {
+	if (body && typeof body === "object" && "error" in body && typeof body.error === "string") return body.error;
+}
+/** Asks `<apiBase>/access/unlock` whether this browser is unlocked. Any failure keeps it shut. */
+async function refreshUnlockStatus(apiBase) {
+	try {
+		const res = await fetch(`${apiBase.replace(/\/+$/, "")}/access/unlock`, {
+			cache: "no-store",
+			headers: { accept: "application/json" }
+		});
+		const body = await res.json().catch(() => ({}));
+		if (!res.ok || !body || typeof body !== "object") {
+			set({ status: "locked" });
+			return;
+		}
+		const { configured, unlocked } = body;
+		set({ status: configured === false ? "unconfigured" : unlocked === true ? "unlocked" : "locked" });
+	} catch {
+		set({ status: "locked" });
+	}
+}
+/** Trades the password for the unlock cookie through the plugin's own route. */
+async function submitPassword(api, password) {
+	set({ error: null });
+	try {
+		if ((await api("/unlock", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ password })
+		}))?.unlocked === true) {
+			set({ status: "unlocked" });
+			return true;
+		}
+		set({ error: "unlock refused" });
+	} catch (cause) {
+		set({ error: cause instanceof HudApiError ? errorOf(cause.body) ?? `unlock refused (${cause.status})` : "unlock failed" });
+	}
+	return false;
+}
+/**
+* `HudAccessControl.useUnlocked`: development is open, a disabled or unknown
+* tier never unlocks, every deployed tier asks the server once per mount.
+*/
+function useUnlocked(envName, apiBase) {
+	const env = toHudEnv(envName);
+	const access = resolveHudAccess(env);
+	const { status } = useUnlockState();
+	useEffect(() => {
+		const required = hudRequiresUnlock(access);
+		set({
+			env,
+			status: access === "open" ? "unlocked" : required ? "checking" : "locked"
+		});
+		if (required) refreshUnlockStatus(apiBase);
+	}, [
+		env,
+		access,
+		apiBase
+	]);
+	if (access === "open") return true;
+	if (access === "denied") return false;
+	return status === "unlocked";
+}
+//#endregion
+//#region src/plugins/access/access-panel.tsx
+const ACCESS_TEXT = {
+	open: "open, no password",
+	password: "password",
+	flag: "password, observe-only",
+	denied: "disabled"
+};
+const field = {
+	flex: 1,
+	minWidth: 0,
+	padding: "3px 6px",
+	font: "inherit",
+	fontFamily: "var(--hud-mono)",
+	color: "var(--hud-fg)",
+	background: "var(--hud-bg-subtle)",
+	border: "1px solid var(--hud-border)",
+	borderRadius: 4
+};
+const button = {
+	padding: "3px 10px",
+	border: "1px solid var(--hud-border)",
+	borderRadius: 4
+};
+function AccessPill() {
+	const { env, status } = useUnlockState();
+	const access = resolveHudAccess(env);
+	const unlocked = access === "open" || status === "unlocked";
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+		className: "dot",
+		"data-rating": unlocked ? "good" : "poor"
+	}), access === "open" ? "Open" : unlocked ? "Unlocked" : "Locked"] });
+}
+/** The panel a locked deployed HUD shows instead of every other plugin. */
+function createAccessPanel(matrix) {
+	return function AccessPanel({ ctx }) {
+		const { env, status, error } = useUnlockState();
+		const [password, setPassword] = useState("");
+		const [submitting, setSubmitting] = useState(false);
+		const access = resolveHudAccess(env);
+		const ttlHours = hudUnlockTtlMs(access) / 36e5;
+		async function onSubmit(event) {
+			event.preventDefault();
+			if (!password || submitting) return;
+			setSubmitting(true);
+			const ok = await submitPassword(ctx.api, password);
+			setSubmitting(false);
+			if (ok) setPassword("");
+		}
+		return /* @__PURE__ */ jsxs("div", {
+			style: {
+				display: "grid",
+				gap: 8
+			},
+			children: [
+				/* @__PURE__ */ jsxs("div", { children: [
+					/* @__PURE__ */ jsx("strong", { children: env }),
+					" ",
+					/* @__PURE__ */ jsxs("span", {
+						className: "empty",
+						children: ["· ", ACCESS_TEXT[access]]
+					})
+				] }),
+				status === "unconfigured" && /* @__PURE__ */ jsx("p", {
+					className: "empty",
+					style: { margin: 0 },
+					children: "No unlock password is configured on this deployment's server, so the HUD cannot be unlocked here."
+				}),
+				status !== "unconfigured" && access !== "open" && status !== "unlocked" && /* @__PURE__ */ jsxs("form", {
+					style: {
+						display: "flex",
+						gap: 6
+					},
+					onSubmit,
+					children: [/* @__PURE__ */ jsx("input", {
+						type: "password",
+						autoComplete: "off",
+						value: password,
+						onChange: (event) => setPassword(event.target.value),
+						placeholder: "hud password",
+						"aria-label": "hud password",
+						style: field
+					}), /* @__PURE__ */ jsx("button", {
+						type: "submit",
+						style: button,
+						disabled: !password || submitting,
+						children: submitting ? "Checking…" : "Unlock"
+					})]
+				}),
+				error && /* @__PURE__ */ jsx("p", {
+					role: "alert",
+					style: {
+						margin: 0,
+						color: "var(--hud-poor)"
+					},
+					children: error
+				}),
+				access !== "open" && status === "unlocked" && /* @__PURE__ */ jsxs("p", {
+					className: "empty",
+					style: { margin: 0 },
+					children: [
+						"Unlocked for up to ",
+						ttlHours,
+						" h."
+					]
+				}),
+				access !== "open" && status !== "unlocked" && ttlHours > 0 && /* @__PURE__ */ jsxs("p", {
+					className: "empty",
+					style: { margin: 0 },
+					children: [
+						"An unlock lasts ",
+						ttlHours,
+						" h."
+					]
+				}),
+				/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("div", {
+					className: "empty",
+					children: "Capabilities"
+				}), /* @__PURE__ */ jsx("code", {
+					style: {
+						fontFamily: "var(--hud-mono)",
+						whiteSpace: "pre-wrap"
+					},
+					children: env === "development" ? "all" : matrix[env].join("\n") || "none"
+				})] })
+			]
+		});
+	};
+}
+//#endregion
+//#region src/plugins/access/index.tsx
+/**
+* Opt-in for deployed tiers. Without it `defineHud` renders nothing outside
+* development. With it the HUD follows the env ladder: a tier's capability
+* matrix narrows the plugins, and until the operator unlocks with the
+* server's password only this plugin's lock shows.
+*
+* Client half; the password check lives in `@hansenexus/hud/plugins/access/server`
+* (`accessServer()` + `accessGuard()`), and the password never reaches the browser.
+*/
+function access(options = {}) {
+	const matrix = resolveMatrix(options.matrix);
+	return definePlugin({
+		id: "access",
+		title: "Access",
+		capability: ACCESS_UNLOCK_CAPABILITY,
+		pill: AccessPill,
+		panel: createAccessPanel(matrix),
+		access: {
+			can: (env, capability) => capability === "access.unlock" || hasCapability(toHudEnv(env), capability, matrix),
+			useUnlocked
+		}
+	});
+}
+//#endregion
+export { ACCESS_UNLOCK_CAPABILITY, CAPABILITY_MATRIX, HUD_CAPABILITIES, access, hasCapability, hudRequiresUnlock, resolveHudAccess };

package/dist/plugins/agent/server.d.ts

@@ -0,0 +1,129 @@
+import { r as GrabPayload, t as ComponentHint } from "../../payload-CLKDVZWl.js";
+import { a as DispatchTargetInfo, i as DispatchReceipt, n as AgentSessionStatus, o as SessionsResponse, r as DispatchBody, t as AgentSession } from "../../types-DADBRiGk.js";
+import { ChildProcess, SpawnOptions } from "node:child_process";
+//#region src/plugins/agent/providers/types.d.ts
+/** What a provider receives: the raw request plus the prompt built from it. */
+interface DispatchOrder {
+  note: string;
+  payload: GrabPayload | null;
+  hints: ComponentHint[];
+  /** `dispatchPrompt(...)` of the above; what an agent should be told. */
+  prompt: string;
+}
+type ProviderStatus = {
+  available: true;
+} | {
+  available: false;
+  reason: string;
+};
+/**
+ * The `dispatch` provider seam. One implementation per backend: `hermes()`
+ * and `claudeCode()` ship with the plugin; anything with the same shape works.
+ * Runs server side only.
+ */
+interface DispatchProvider {
+  /** Unique among the providers passed in; the client selects a target by it. */
+  id: string;
+  label: string;
+  description?: string;
+  /** Default: available. */
+  status?: () => ProviderStatus | Promise<ProviderStatus>;
+  /** Starts work and returns as soon as it is accepted, not when it finishes. */
+  dispatch: (order: DispatchOrder) => Promise<{
+    runId: string;
+    detail?: string;
+  }>;
+  /** Runs and sessions this backend knows about, for the Sessions panel. */
+  sessions?: () => Promise<AgentSession[]>;
+}
+//#endregion
+//#region src/plugins/agent/prompt.d.ts
+interface PromptInput {
+  note: string;
+  payload: GrabPayload | null;
+  hints?: readonly ComponentHint[] | undefined;
+}
+/** The task text every provider receives: grab context first, then the instruction. */
+export declare function dispatchPrompt({ note, payload, hints }: PromptInput): string;
+//#endregion
+//#region src/plugins/agent/providers/claude-code.d.ts
+interface ClaudeCodeOptions {
+  /** Repository the agent works in. Default `process.cwd()`, the dev server's root. */
+  cwd?: string;
+  /** Default `claude`. */
+  command?: string;
+  /**
+   * Arguments for one run. Default `["-p", prompt, "--permission-mode", "acceptEdits"]`:
+   * headless, may edit files, asks (and therefore stops) before running commands.
+   */
+  args?: (prompt: string) => string[];
+  label?: string;
+  /** Where each run's stdout and stderr go. Default `<tmpdir>/hud-agent`. */
+  logDir?: string;
+  /** How many recent transcripts the Sessions panel lists. Default 8. */
+  transcripts?: number;
+  /** Home directory holding `.claude/projects`. Default `os.homedir()`. */
+  home?: string;
+  /** Test seam. */
+  spawn?: (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+}
+/**
+ * Dispatches to a local Claude Code: each run is `claude -p <prompt>` spawned
+ * (argv, no shell) in `cwd`, detached so it outlives a dev-server reload, with
+ * its output in a log file. Sessions are the runs started here plus the most
+ * recent Claude Code transcripts of `cwd`.
+ */
+export declare function claudeCode({ cwd: cwdOption, command, args, label, logDir: logDirOption, transcripts, home: homeOption, spawn: spawnOption }?: ClaudeCodeOptions): DispatchProvider;
+//#endregion
+//#region src/plugins/agent/providers/hermes.d.ts
+interface HermesOptions {
+  /** Hermes Agent API server, e.g. `http://hn-hub:8642`. */
+  baseUrl: string;
+  /** Bearer token, or a getter read per request. Missing: the target shows as unavailable. */
+  token: string | undefined | (() => string | undefined);
+  /** Sent as the run's `instructions` (an ephemeral system prompt), e.g. a playbook. */
+  instructions?: string;
+  label?: string;
+  /** Per-request timeout. Default 10 s. */
+  timeoutMs?: number;
+  /** Test seam. */
+  fetch?: typeof fetch;
+}
+/**
+ * Dispatches to a Hermes Agent API server: `POST /v1/runs` starts a
+ * background run (202 `{ run_id }`), `GET /v1/jobs` lists runs for the
+ * Sessions panel. The token never leaves the server.
+ */
+export declare function hermes({ baseUrl, token, instructions, label, timeoutMs, fetch: fetchImpl }: HermesOptions): DispatchProvider;
+//#endregion
+//#region src/plugins/agent/server.d.ts
+export interface AgentServerOptions {
+  /** Dispatch backends, first available is the panel's default target. */
+  providers: readonly DispatchProvider[];
+}
+/**
+ * Server half of `agentDispatch`: `GET /targets` lists the providers,
+ * `POST /dispatch` hands a grab plus instruction to one of them.
+ */
+export declare function agentDispatch({ providers }: AgentServerOptions): {
+  readonly id: "agent-dispatch";
+  readonly routes: {
+    readonly "/targets": {
+      GET: () => Promise<Response>;
+    };
+    readonly "/dispatch": {
+      readonly POST: (request: Request) => Promise<Response>;
+    };
+  };
+};
+/** Server half of `agentSessions`: `GET /sessions` merges every provider's sessions. */
+export declare function agentSessions({ providers }: AgentServerOptions): {
+  readonly id: "agent-sessions";
+  readonly routes: {
+    "/sessions": {
+      GET: () => Promise<Response>;
+    };
+  };
+};
+//#endregion
+export type { AgentSession, AgentSessionStatus, ClaudeCodeOptions, DispatchBody, DispatchOrder, DispatchProvider, DispatchReceipt, DispatchTargetInfo, HermesOptions, ProviderStatus, SessionsResponse };