axusage 3.3.0 → 3.4.0

package/README.md

@@ -151,6 +151,73 @@ Human-readable output includes:
 JSON output provides structured data for automation.
 Prometheus output emits text metrics suitable for scraping.
 
+## Serve Mode
+
+`axusage serve` starts an HTTP server that exposes Prometheus metrics at `/metrics` for scraping, with automatic polling.
+
+### Usage
+
+```bash
+# Start with defaults (port 3848, poll every 5 minutes)
+axusage serve
+
+# Custom configuration
+axusage serve --port 9090 --interval 60 --service claude
+
+# With environment variables
+AXUSAGE_PORT=9090 AXUSAGE_INTERVAL=60 axusage serve
+```
+
+### Options
+
+| Flag                   | Env Var            | Default     | Description                 |
+| ---------------------- | ------------------ | ----------- | --------------------------- |
+| `--port <port>`        | `AXUSAGE_PORT`     | `3848`      | Port to listen on           |
+| `--host <host>`        | `AXUSAGE_HOST`     | `127.0.0.1` | Host to bind to             |
+| `--interval <seconds>` | `AXUSAGE_INTERVAL` | `300`       | Polling interval in seconds |
+| `--service <service>`  | `AXUSAGE_SERVICE`  | all         | Service to monitor          |
+
+### Endpoints
+
+- `GET /metrics` — Prometheus text exposition (`text/plain; version=0.0.4`). Returns 503 if no data has been fetched yet.
+- `GET /health` — JSON health status with version, last refresh time, tracked services, and errors.
+
+### Container Deployment
+
+```bash
+# Build image
+podman build -t axusage .
+
+# Run (configure credential sources via AXUSAGE_SOURCES)
+podman run -p 3848:3848 --user 1000:1000 \
+  -e AXUSAGE_SOURCES='{"claude":{"source":"vault","name":"claude-oauth"}}' \
+  -e AXVAULT_URL=http://axvault:3847 \
+  -e AXVAULT_API_KEY=axv_sk_... \
+  axusage
+```
+
+### Docker Compose
+
+```bash
+cp .env.example .env
+# Edit .env with credential sources and vault config
+docker compose up -d --build
+```
+
+### Publishing
+
+Container publishing is part of CI/CD:
+
+- Pushes to `main` run the `Release` workflow.
+- If `semantic-release` creates a new version tag, CI builds and publishes a multi-arch image to `registry.j4k.dev/axusage:<version>`.
+
+For manual publishing:
+
+```bash
+./scripts/publish-image.sh --dry-run
+./scripts/publish-image.sh --version 1.0.0
+```
+
 ## Troubleshooting
 
 ### "Required dependency '... not found'"

package/dist/cli.js

@@ -3,6 +3,7 @@ import { Command, Option } from "@commander-js/extra-typings";
 import packageJson from "../package.json" with { type: "json" };
 import { authSetupCommand } from "./commands/auth-setup-command.js";
 import { authStatusCommand } from "./commands/auth-status-command.js";
+import { serveCommand } from "./commands/serve-command.js";
 import { usageCommand } from "./commands/usage-command.js";
 import { getCredentialSourcesPath } from "./config/credential-sources.js";
 import { getAvailableServices } from "./services/service-adapter-registry.js";
@@ -19,6 +20,7 @@ const program = new Command()
     .showHelpAfterError("(add --help for additional information)")
     .showSuggestionAfterError()
     .helpCommand(false)
+    .enablePositionalOptions()
     .option("--no-color", "disable color output")
     .option("-s, --service <service>", `Service to query (${getAvailableServices().join(", ")}, all) - defaults to all`)
     .addOption(new Option("-o, --format <format>", "Output format")
@@ -27,6 +29,16 @@ const program = new Command()
     .option("--auth-setup <service>", "set up authentication for a service (directs to appropriate CLI)")
     .option("--auth-status [service]", "check authentication status for services")
     .addHelpText("after", () => `\nExamples:\n  # Fetch usage for all services\n  ${packageJson.name}\n\n  # JSON output for a single service\n  ${packageJson.name} --service claude --format json\n\n  # TSV output for piping to cut, awk, sort\n  ${packageJson.name} --format tsv | tail -n +2 | awk -F'\\t' '{print $1, $4"%"}'\n\n  # Filter Prometheus metrics with standard tools\n  ${packageJson.name} --format prometheus | grep axusage_utilization_percent\n\n  # Check authentication status for all services\n  ${packageJson.name} --auth-status\n\nSources config file: ${getCredentialSourcesPath()}\n(or set AXUSAGE_SOURCES to JSON to bypass file)\n\n${formatRequiresHelpText()}\nOverride CLI paths: AXUSAGE_CLAUDE_PATH, AXUSAGE_CODEX_PATH, AXUSAGE_GEMINI_PATH, AXUSAGE_GH_PATH\n`);
+program
+    .command("serve")
+    .description("Start HTTP server exposing Prometheus metrics at /metrics")
+    .option("-p, --port <port>", "Port to listen on (env: AXUSAGE_PORT)")
+    .option("-H, --host <host>", "Host to bind to (env: AXUSAGE_HOST)")
+    .option("--interval <seconds>", "Polling interval in seconds (env: AXUSAGE_INTERVAL)")
+    .option("-s, --service <service>", "Service to monitor (env: AXUSAGE_SERVICE, default: all)")
+    .action(async (options) => {
+    await serveCommand(options);
+});
 function fail(message) {
     console.error(`Error: ${message}`);
     console.error("Try 'axusage --help' for details.");

package/dist/commands/serve-command.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Serve command handler — starts an HTTP server exposing Prometheus metrics.
+ */
+type ServeCommandOptions = {
+    readonly port?: string;
+    readonly host?: string;
+    readonly interval?: string;
+    readonly service?: string;
+};
+export declare function serveCommand(options: ServeCommandOptions): Promise<void>;
+export {};

package/dist/commands/serve-command.js

@@ -0,0 +1,116 @@
+/**
+ * Serve command handler — starts an HTTP server exposing Prometheus metrics.
+ */
+import { getServeConfig } from "../config/serve-config.js";
+import { selectServicesToQuery } from "./fetch-service-usage.js";
+import { fetchServicesInParallel } from "./usage-command.js";
+import { formatPrometheusMetrics } from "../utils/format-prometheus-metrics.js";
+import { createServer } from "../server/server.js";
+import { createHealthRouter, createMetricsRouter } from "../server/routes.js";
+import { getAvailableServices } from "../services/service-adapter-registry.js";
+export async function serveCommand(options) {
+    const config = getServeConfig(options);
+    const availableServices = getAvailableServices();
+    if (config.service !== undefined &&
+        config.service.toLowerCase() !== "all" &&
+        !availableServices.includes(config.service.toLowerCase())) {
+        console.error(`Unknown service "${config.service}". Supported: ${availableServices.join(", ")}.`);
+        if (process.exitCode === undefined)
+            process.exitCode = 1;
+        return;
+    }
+    const servicesToQuery = selectServicesToQuery(config.service);
+    // Cached state
+    let cachedMetrics;
+    let lastRefreshTime;
+    let lastRefreshErrors = [];
+    let refreshing = false;
+    async function refreshMetrics() {
+        if (refreshing)
+            return;
+        refreshing = true;
+        try {
+            const results = await fetchServicesInParallel(servicesToQuery);
+            const successes = [];
+            const errors = [];
+            for (const { service, result } of results) {
+                if (result.ok) {
+                    successes.push(result.value);
+                }
+                else {
+                    const statusSuffix = result.error.status === undefined
+                        ? ""
+                        : ` (HTTP ${String(result.error.status)})`;
+                    errors.push(`${service}: fetch failed${statusSuffix}`);
+                    console.error(`Warning: Failed to fetch ${service}: ${result.error.message}`);
+                }
+            }
+            lastRefreshErrors = errors;
+            lastRefreshTime = new Date();
+            // All services failed → clear cache so /metrics returns 503 instead of
+            // serving stale data that could mask outages in Prometheus alerting.
+            cachedMetrics =
+                successes.length > 0
+                    ? await formatPrometheusMetrics(successes)
+                    : undefined;
+        }
+        finally {
+            refreshing = false; // eslint-disable-line require-atomic-updates -- single-threaded guard, no race
+        }
+    }
+    // Initial fetch
+    console.error(`Fetching initial metrics for: ${servicesToQuery.join(", ")}`);
+    await refreshMetrics();
+    // Create server
+    const healthRouter = createHealthRouter(() => ({
+        lastRefreshTime,
+        services: servicesToQuery,
+        errors: lastRefreshErrors,
+        hasMetrics: cachedMetrics !== undefined,
+    }));
+    const metricsRouter = createMetricsRouter(() => ({
+        metrics: cachedMetrics,
+    }));
+    const server = createServer(config, [healthRouter, metricsRouter]);
+    // Graceful shutdown handler — registered before start so signals during
+    // startup are handled. process.once ensures at-most-one invocation per signal.
+    // Object wrapper lets the shutdown closure reference the interval assigned
+    // after server.start(), without needing a reassignable `let`.
+    const poll = {
+        intervalId: undefined,
+    };
+    const shutdown = () => {
+        console.error("\nShutting down...");
+        if (poll.intervalId !== undefined)
+            clearInterval(poll.intervalId);
+        // Force-exit if server.stop() hangs (e.g. keep-alive connections not closing)
+        const forceExit = setTimeout(() => {
+            console.error("Shutdown timed out, forcing exit");
+            // eslint-disable-next-line unicorn/no-process-exit -- CLI graceful shutdown
+            process.exit(1);
+        }, 5000);
+        forceExit.unref();
+        server.stop().then(() => {
+            clearTimeout(forceExit);
+            // eslint-disable-next-line unicorn/no-process-exit -- CLI graceful shutdown
+            process.exit(0);
+        }, (error) => {
+            clearTimeout(forceExit);
+            console.error("Error during shutdown:", error);
+            // eslint-disable-next-line unicorn/no-process-exit -- CLI graceful shutdown
+            process.exit(1);
+        });
+    };
+    process.once("SIGTERM", shutdown);
+    process.once("SIGINT", shutdown);
+    // Start server first — if this throws (e.g. EADDRINUSE), no polling interval
+    // is left dangling keeping the process alive.
+    await server.start();
+    // Start polling only after a successful listen.
+    poll.intervalId = setInterval(() => {
+        void refreshMetrics().catch((error) => {
+            console.error("Unexpected error during metrics refresh:", error);
+        });
+    }, config.intervalMs);
+    console.error(`Polling every ${String(config.intervalMs / 1000)}s for: ${servicesToQuery.join(", ")}`);
+}

package/dist/config/serve-config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Configuration for axusage serve mode.
+ *
+ * Priority: CLI flags > environment variables > defaults.
+ */
+export type ServeConfig = {
+    readonly port: number;
+    readonly host: string;
+    readonly intervalMs: number;
+    readonly service: string | undefined;
+};
+type ServeConfigOverrides = {
+    readonly port?: string;
+    readonly host?: string;
+    readonly interval?: string;
+    readonly service?: string;
+};
+/** Parse serve config from environment and CLI overrides */
+export declare function getServeConfig(overrides?: ServeConfigOverrides): ServeConfig;
+export {};

package/dist/config/serve-config.js

@@ -0,0 +1,40 @@
+/**
+ * Configuration for axusage serve mode.
+ *
+ * Priority: CLI flags > environment variables > defaults.
+ */
+const DEFAULT_PORT = 3848;
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_INTERVAL_SECONDS = 300; // 5 minutes
+/** Parse serve config from environment and CLI overrides */
+export function getServeConfig(overrides = {}) {
+    const port = parsePort(overrides.port ?? process.env.AXUSAGE_PORT);
+    const host = overrides.host || process.env.AXUSAGE_HOST || DEFAULT_HOST;
+    const intervalSeconds = parsePositiveInt(overrides.interval ?? process.env.AXUSAGE_INTERVAL, DEFAULT_INTERVAL_SECONDS, "AXUSAGE_INTERVAL");
+    const service = (overrides.service ?? process.env.AXUSAGE_SERVICE) || undefined;
+    return {
+        port,
+        host,
+        intervalMs: intervalSeconds * 1000,
+        service,
+    };
+}
+function parsePort(value) {
+    if (!value)
+        return DEFAULT_PORT;
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw new Error(`Invalid port: ${value}`);
+    }
+    return port;
+}
+function parsePositiveInt(value, defaultValue, name) {
+    if (!value)
+        return defaultValue;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        console.error(`Invalid ${name} value "${value}", using default ${String(defaultValue)}`);
+        return defaultValue;
+    }
+    return parsed;
+}

package/dist/server/routes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Route handlers for axusage serve mode.
+ */
+import { Router } from "express";
+type HealthStatus = {
+    readonly lastRefreshTime: Date | undefined;
+    readonly services: readonly string[];
+    readonly errors: readonly string[];
+    readonly hasMetrics: boolean;
+};
+type MetricsStatus = {
+    readonly metrics: string | undefined;
+};
+/** Create router for GET /health */
+export declare function createHealthRouter(getStatus: () => HealthStatus): Router;
+/** Create router for GET /metrics */
+export declare function createMetricsRouter(getMetrics: () => MetricsStatus): Router;
+export {};

package/dist/server/routes.js

@@ -0,0 +1,37 @@
+/**
+ * Route handlers for axusage serve mode.
+ */
+import { Router } from "express";
+import packageJson from "../../package.json" with { type: "json" };
+/** Create router for GET /health */
+export function createHealthRouter(getStatus) {
+    const router = Router();
+    router.get("/health", (_request, response) => {
+        const status = getStatus();
+        const healthy = status.hasMetrics;
+        response.status(healthy ? 200 : 503).json({
+            status: healthy ? "ok" : "degraded",
+            version: packageJson.version,
+            lastRefresh: status.lastRefreshTime?.toISOString(),
+            services: status.services,
+            errors: status.errors,
+        });
+    });
+    return router;
+}
+/** Create router for GET /metrics */
+export function createMetricsRouter(getMetrics) {
+    const router = Router();
+    router.get("/metrics", (_request, response) => {
+        const { metrics } = getMetrics();
+        if (!metrics) {
+            response.status(503).type("text/plain").send("No data yet\n");
+            return;
+        }
+        response
+            .status(200)
+            .type("text/plain; version=0.0.4; charset=utf-8")
+            .send(metrics);
+    });
+    return router;
+}

package/dist/server/server.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Express HTTP server for axusage metrics.
+ *
+ * Designed for both CLI and library usage via factory pattern.
+ */
+import { type Express, type Router } from "express";
+import type { ServeConfig } from "../config/serve-config.js";
+/** Server instance with lifecycle methods */
+type AxusageServer = {
+    /** The Express application instance */
+    readonly app: Express;
+    /** Start listening on the configured host:port */
+    start(): Promise<void>;
+    /** Stop the server gracefully */
+    stop(): Promise<void>;
+};
+/** Create an axusage server instance */
+export declare function createServer(config: Pick<ServeConfig, "port" | "host">, routers: Router[]): AxusageServer;
+export {};

package/dist/server/server.js

@@ -0,0 +1,72 @@
+/**
+ * Express HTTP server for axusage metrics.
+ *
+ * Designed for both CLI and library usage via factory pattern.
+ */
+import express, {} from "express";
+/** Create and configure Express application */
+function createApp(routers) {
+    const app = express();
+    // Security: disable X-Powered-By header
+    app.disable("x-powered-by");
+    // Register all routers
+    for (const router of routers) {
+        app.use(router);
+    }
+    // 404 handler for unmatched routes
+    app.use((_request, response) => {
+        response.status(404).json({ error: "Not found" });
+    });
+    return app;
+}
+/** Create an axusage server instance */
+export function createServer(config, routers) {
+    const app = createApp(routers);
+    let server;
+    let stopPromise;
+    return {
+        app,
+        start() {
+            if (server) {
+                return Promise.reject(new Error("Server is already running. Call stop() before restarting."));
+            }
+            stopPromise = undefined;
+            return new Promise((resolve, reject) => {
+                const onStartupError = (error) => {
+                    server = undefined;
+                    reject(error);
+                };
+                server = app.listen(config.port, config.host, () => {
+                    server?.removeListener("error", onStartupError);
+                    server?.on("error", (error) => {
+                        console.error("Server error:", error);
+                    });
+                    console.error(`axusage listening on http://${config.host}:${String(config.port)}`);
+                    resolve();
+                });
+                server.once("error", onStartupError);
+            });
+        },
+        stop() {
+            if (stopPromise) {
+                return stopPromise;
+            }
+            if (!server) {
+                return Promise.resolve();
+            }
+            const serverToClose = server;
+            server = undefined;
+            stopPromise = new Promise((resolve, reject) => {
+                serverToClose.close((error) => {
+                    if (error) {
+                        reject(error);
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+            return stopPromise;
+        },
+    };
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "axusage",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Monitor API usage across Claude, ChatGPT, GitHub Copilot, and Gemini from a single CLI",
   "repository": {
     "type": "git",
@@ -58,11 +58,13 @@
     "commander": "^14.0.3",
     "conf": "^15.1.0",
     "env-paths": "^4.0.0",
+    "express": "^5.2.1",
     "prom-client": "^15.1.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@total-typescript/ts-reset": "^0.6.1",
+    "@types/express": "^5.0.6",
     "@types/node": "^25.3.0",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^10.0.1",