@oh-my-pi/omp-stats 17.3.4 → 17.3.7

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [17.3.6] - 2026-08-17
+
+### Fixed
+
+- Fixed the stats dashboard being unreachable from container hosts by accepting an explicit `--host` bind address while preserving loopback-only binding and same-origin API access by default.
+
 ## [17.3.0] - 2026-08-13
 
 ### Added

package/dist/types/index.d.ts

@@ -2,6 +2,16 @@
 export { getDashboardStats, getToolDashboardStats, getTotalMessageCount, type SyncOptions, type SyncProgress, smokeTestSyncWorker, syncAllSessions, } from "./aggregator.js";
 export { closeDb } from "./db.js";
 export { getGainDashboardStats } from "./gain-aggregator.js";
-export { startServer } from "./server.js";
+export { formatStatsDashboardUrl, startServer } from "./server.js";
 export type { GainDashboardStats, GainSource, GainSourceTotals, GainTimeSeriesPoint, } from "./shared-types.js";
 export type { AggregatedStats, DashboardStats, FolderStats, MessageStats, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, TimeSeriesPoint, ToolDashboardStats, ToolModelStats, ToolTimeSeriesPoint, ToolUsageStats, } from "./types.js";
+/** Parsed arguments for the standalone `omp-stats` entry point. */
+export interface StandaloneStatsArgs {
+    port: number;
+    host: string;
+    json: boolean;
+    sync: boolean;
+    help: boolean;
+}
+/** Parse the standalone `omp-stats` arguments used by the production entry point. */
+export declare function parseStandaloneStatsArgs(args: string[]): StandaloneStatsArgs;

package/dist/types/port-conflict.d.ts

@@ -1,7 +1,9 @@
 /** Header stamped on every dashboard response so reuse probes can identify us. */
 export declare const STATS_DASHBOARD_HEADER = "x-omp-stats-dashboard";
-/** Identity-header value for dashboards enforcing loopback-only, same-origin access. */
-export declare const STATS_DASHBOARD_SECURITY_VERSION = "2";
+/** Header recording the server's requested bind host so reuse cannot change its exposure scope. */
+export declare const STATS_DASHBOARD_HOSTNAME_HEADER = "x-omp-stats-hostname";
+/** Identity-header value for dashboards enforcing an explicit bind host and same-origin access. */
+export declare const STATS_DASHBOARD_SECURITY_VERSION = "3";
 /** IPv4 loopback address shared by the dashboard server and reuse probe. */
 export declare const STATS_DASHBOARD_HOSTNAME = "127.0.0.1";
 /**
@@ -9,6 +11,6 @@ export declare const STATS_DASHBOARD_HOSTNAME = "127.0.0.1";
  * The preflight is needed on platforms that permit wildcard and loopback-specific
  * listeners to coexist on one port.
  */
-export declare function prepareStatsPort(port: number): Promise<"retry" | "reuse">;
+export declare function prepareStatsPort(port: number, hostname?: string): Promise<"retry" | "reuse">;
 /** Reuse or reclaim a listener found after the server bind reports EADDRINUSE. */
-export declare function recoverStatsPort(port: number): Promise<"retry" | "reuse">;
+export declare function recoverStatsPort(port: number, hostname?: string): Promise<"retry" | "reuse">;

package/dist/types/server.d.ts

@@ -2,10 +2,12 @@
  * Handle API requests.
  */
 export declare function handleApi(req: Request): Promise<Response>;
+/** Format a dashboard origin, including brackets required by IPv6 literals. */
+export declare function formatStatsDashboardUrl(hostname: string, port: number): string;
 /**
  * Start the HTTP server, reusing a live dashboard or reclaiming a stale omp listener.
  */
-export declare function startServer(port?: number): Promise<{
+export declare function startServer(port?: number, hostname?: string): Promise<{
     hostname: string;
     port: number;
     stop: () => void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/omp-stats",
-	"version": "17.3.4",
+	"version": "17.3.7",
 	"description": "Local observability dashboard for pi AI usage statistics",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -39,9 +39,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "17.3.4",
-		"@oh-my-pi/pi-catalog": "17.3.4",
-		"@oh-my-pi/pi-utils": "17.3.4",
+		"@oh-my-pi/pi-ai": "17.3.7",
+		"@oh-my-pi/pi-catalog": "17.3.7",
+		"@oh-my-pi/pi-utils": "17.3.7",
 		"@tailwindcss/node": "^4.3.2",
 		"chart.js": "^4.5.1",
 		"lucide-react": "^1.24.0",

package/src/index.ts

@@ -4,7 +4,7 @@ import { parseArgs } from "node:util";
 import { formatDuration, formatNumber, formatPercent } from "@oh-my-pi/pi-utils";
 import { getDashboardStats, getTotalMessageCount, syncAllSessions } from "./aggregator";
 import { closeDb } from "./db";
-import { startServer } from "./server";
+import { formatStatsDashboardUrl, startServer } from "./server";
 
 export {
 	getDashboardStats,
@@ -17,7 +17,7 @@ export {
 } from "./aggregator";
 export { closeDb } from "./db";
 export { getGainDashboardStats } from "./gain-aggregator";
-export { startServer } from "./server";
+export { formatStatsDashboardUrl, startServer } from "./server";
 export type {
 	GainDashboardStats,
 	GainSource,
@@ -96,19 +96,42 @@ async function printStats(): Promise<void> {
 	console.log("");
 }
 
-/**
- * Main CLI entry point.
- */
-async function main(): Promise<void> {
+/** Parsed arguments for the standalone `omp-stats` entry point. */
+export interface StandaloneStatsArgs {
+	port: number;
+	host: string;
+	json: boolean;
+	sync: boolean;
+	help: boolean;
+}
+
+/** Parse the standalone `omp-stats` arguments used by the production entry point. */
+export function parseStandaloneStatsArgs(args: string[]): StandaloneStatsArgs {
 	const { values } = parseArgs({
+		args,
 		options: {
 			port: { type: "string", short: "p", default: "3847" },
+			host: { type: "string", default: "127.0.0.1" },
 			json: { type: "boolean", short: "j", default: false },
 			sync: { type: "boolean", short: "s", default: false },
 			help: { type: "boolean", short: "h", default: false },
 		},
 		allowPositionals: true,
 	});
+	return {
+		port: parseInt(values.port || "3847", 10),
+		host: values.host || "127.0.0.1",
+		json: values.json ?? false,
+		sync: values.sync ?? false,
+		help: values.help ?? false,
+	};
+}
+
+/**
+ * Main CLI entry point.
+ */
+async function main(): Promise<void> {
+	const values = parseStandaloneStatsArgs(process.argv.slice(2));
 
 	if (values.help) {
 		console.log(`
@@ -119,6 +142,7 @@ Usage:
 
 Options:
   -p, --port <port>  Port for the dashboard server (default: 3847)
+  --host <host>       Host to bind (default: 127.0.0.1)
   -j, --json         Output stats as JSON and exit
   -s, --sync         Sync session files and show summary
   -h, --help         Show this help message
@@ -126,7 +150,7 @@ Options:
 Examples:
   omp-stats              # Start dashboard server
   omp-stats --json       # Print stats as JSON
-  omp-stats --port 8080  # Start on custom port
+  omp-stats --host 0.0.0.0 # Explicitly expose on all IPv4 interfaces
   omp-stats --sync       # Sync and show summary
 `);
 		return;
@@ -171,9 +195,8 @@ Examples:
 		}
 
 		// Start server
-		const port = parseInt(values.port || "3847", 10);
-		const { hostname, port: actualPort } = await startServer(port);
-		console.log(`Dashboard available at: http://${hostname}:${actualPort}`);
+		const { port: actualPort } = await startServer(values.port, values.host);
+		console.log(`Dashboard available at: ${formatStatsDashboardUrl(values.host, actualPort)}`);
 		console.log("Press Ctrl+C to stop\n");
 
 		// Keep process running

package/src/port-conflict.ts

@@ -17,23 +17,28 @@ interface PortHolder {
 
 /** Header stamped on every dashboard response so reuse probes can identify us. */
 export const STATS_DASHBOARD_HEADER = "x-omp-stats-dashboard";
+/** Header recording the server's requested bind host so reuse cannot change its exposure scope. */
+export const STATS_DASHBOARD_HOSTNAME_HEADER = "x-omp-stats-hostname";
 
-/** Identity-header value for dashboards enforcing loopback-only, same-origin access. */
-export const STATS_DASHBOARD_SECURITY_VERSION = "2";
+/** Identity-header value for dashboards enforcing an explicit bind host and same-origin access. */
+export const STATS_DASHBOARD_SECURITY_VERSION = "3";
 
 /** IPv4 loopback address shared by the dashboard server and reuse probe. */
 export const STATS_DASHBOARD_HOSTNAME = "127.0.0.1";
 
 type StatsDashboardProbe = "reusable" | "occupied" | "unreachable";
 
-async function probeStatsDashboard(port: number): Promise<StatsDashboardProbe> {
+async function probeStatsDashboard(port: number, hostname: string): Promise<StatsDashboardProbe> {
+	const probeHostname = hostname === "0.0.0.0" ? STATS_DASHBOARD_HOSTNAME : hostname === "::" ? "::1" : hostname;
+	const urlHostname = probeHostname.includes(":") ? `[${probeHostname}]` : probeHostname;
 	try {
-		const response = await fetch(`http://${STATS_DASHBOARD_HOSTNAME}:${port}/api/stats/models`, {
+		const response = await fetch(`http://${urlHostname}:${port}/api/stats/models`, {
 			signal: AbortSignal.timeout(STATS_PROBE_TIMEOUT_MS),
 		});
 		const reusable =
 			response.status === 200 &&
 			response.headers.get(STATS_DASHBOARD_HEADER) === STATS_DASHBOARD_SECURITY_VERSION &&
+			response.headers.get(STATS_DASHBOARD_HOSTNAME_HEADER) === hostname &&
 			!response.headers.has("Access-Control-Allow-Origin");
 		await response.body?.cancel();
 		return reusable ? "reusable" : "occupied";
@@ -248,16 +253,16 @@ async function reclaimStatsPort(port: number): Promise<"retry"> {
  * The preflight is needed on platforms that permit wildcard and loopback-specific
  * listeners to coexist on one port.
  */
-export async function prepareStatsPort(port: number): Promise<"retry" | "reuse"> {
+export async function prepareStatsPort(port: number, hostname = STATS_DASHBOARD_HOSTNAME): Promise<"retry" | "reuse"> {
 	if (port === 0) return "retry";
-	const probe = await probeStatsDashboard(port);
+	const probe = await probeStatsDashboard(port, hostname);
 	if (probe === "reusable") return "reuse";
 	if (probe === "occupied") return reclaimStatsPort(port);
 	return "retry";
 }
 
 /** Reuse or reclaim a listener found after the server bind reports EADDRINUSE. */
-export async function recoverStatsPort(port: number): Promise<"retry" | "reuse"> {
-	if ((await probeStatsDashboard(port)) === "reusable") return "reuse";
+export async function recoverStatsPort(port: number, hostname = STATS_DASHBOARD_HOSTNAME): Promise<"retry" | "reuse"> {
+	if ((await probeStatsDashboard(port, hostname)) === "reusable") return "reuse";
 	return reclaimStatsPort(port);
 }

package/src/server.ts

@@ -26,6 +26,7 @@ import {
 	recoverStatsPort,
 	STATS_DASHBOARD_HEADER,
 	STATS_DASHBOARD_HOSTNAME,
+	STATS_DASHBOARD_HOSTNAME_HEADER,
 	STATS_DASHBOARD_SECURITY_VERSION,
 } from "./port-conflict";
 
@@ -306,10 +307,16 @@ async function handleStatic(requestPath: string): Promise<Response> {
 	return new Response("Not Found", { status: 404 });
 }
 
-function createDashboardServer(port: number) {
+/** Format a dashboard origin, including brackets required by IPv6 literals. */
+export function formatStatsDashboardUrl(hostname: string, port: number): string {
+	const urlHostname = hostname.includes(":") && !hostname.startsWith("[") ? `[${hostname}]` : hostname;
+	return `http://${urlHostname}:${port}`;
+}
+
+function createDashboardServer(port: number, hostname: string) {
 	const server = Bun.serve({
 		port,
-		hostname: STATS_DASHBOARD_HOSTNAME,
+		hostname,
 		async fetch(req) {
 			const url = new URL(req.url);
 			const path = url.pathname;
@@ -318,6 +325,7 @@ function createDashboardServer(port: number) {
 			// recognize this dashboard without allowing cross-origin API reads.
 			const dashboardHeaders: Record<string, string> = {
 				[STATS_DASHBOARD_HEADER]: STATS_DASHBOARD_SECURITY_VERSION,
+				[STATS_DASHBOARD_HOSTNAME_HEADER]: hostname,
 			};
 
 			if (req.method === "OPTIONS") {
@@ -358,37 +366,40 @@ function createDashboardServer(port: number) {
 /**
  * Start the HTTP server, reusing a live dashboard or reclaiming a stale omp listener.
  */
-export async function startServer(port = 3847): Promise<{ hostname: string; port: number; stop: () => void }> {
+export async function startServer(
+	port = 3847,
+	hostname = STATS_DASHBOARD_HOSTNAME,
+): Promise<{ hostname: string; port: number; stop: () => void }> {
 	await ensureClientBuild();
-	const preparation = await prepareStatsPort(port);
+	const preparation = await prepareStatsPort(port, hostname);
 	if (preparation === "reuse") {
-		return { hostname: STATS_DASHBOARD_HOSTNAME, port, stop: () => {} };
+		return { hostname, port, stop: () => {} };
 	}
 
 	try {
-		const server = createDashboardServer(port);
+		const server = createDashboardServer(port, hostname);
 		return {
-			hostname: STATS_DASHBOARD_HOSTNAME,
+			hostname,
 			port: server.port ?? port,
 			stop: () => server.stop(),
 		};
 	} catch (error) {
 		if (!(error instanceof Error && "code" in error && error.code === "EADDRINUSE")) throw error;
 
-		const recovery = await recoverStatsPort(port);
+		const recovery = await recoverStatsPort(port, hostname);
 		if (recovery === "reuse") {
-			return { hostname: STATS_DASHBOARD_HOSTNAME, port, stop: () => {} };
+			return { hostname, port, stop: () => {} };
 		}
 
 		try {
-			const server = createDashboardServer(port);
+			const server = createDashboardServer(port, hostname);
 			return {
-				hostname: STATS_DASHBOARD_HOSTNAME,
+				hostname,
 				port: server.port ?? port,
 				stop: () => server.stop(),
 			};
 		} catch (retryError) {
-			throw new Error(`Failed to start stats dashboard on port ${port} after reclaiming it.`, {
+			throw new Error(`Failed to start stats dashboard on ${hostname}:${port} after reclaiming it.`, {
 				cause: retryError,
 			});
 		}