@shetty4l/core 0.1.28 → 0.1.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shetty4l/core",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Shared infrastructure primitives for Bun/TypeScript services",
   "repository": {
     "type": "git",

package/src/cli.ts

@@ -5,6 +5,8 @@
  * Each service defines its own commands and help text.
  */
 
+import type { DaemonManager } from "./daemon";
+
 // --- Arg parsing ---
 
 export interface ParsedArgs {
@@ -184,3 +186,158 @@ export async function runCli(opts: RunCliOpts): Promise<void> {
     process.exit(result);
   }
 }
+
+// --- Daemon command factories ---
+
+export interface DaemonCommandsOpts {
+  /** Service name (e.g. "synapse"). Used in output messages. */
+  name: string;
+  /** Factory that returns a DaemonManager. Called lazily per command. */
+  getDaemon: () => DaemonManager;
+}
+
+/**
+ * Create standard daemon lifecycle commands: start, stop, status, restart.
+ *
+ * Returns four CommandHandler functions ready to register with runCli.
+ * Output format is standardized across all services.
+ */
+export function createDaemonCommands(opts: DaemonCommandsOpts): {
+  start: CommandHandler;
+  stop: CommandHandler;
+  status: CommandHandler;
+  restart: CommandHandler;
+} {
+  const { name, getDaemon } = opts;
+
+  const start: CommandHandler = async () => {
+    const result = await getDaemon().start();
+    if (!result.ok) {
+      console.error(result.error);
+      return 1;
+    }
+    const { pid, port } = result.value;
+    const portStr = port != null ? `, port: ${port}` : "";
+    console.log(`${name} daemon started (PID: ${pid}${portStr})`);
+    return 0;
+  };
+
+  const stop: CommandHandler = async () => {
+    const result = await getDaemon().stop();
+    if (!result.ok) {
+      if (result.error.includes("not running")) {
+        console.log(`${name} daemon is not running`);
+      } else {
+        console.error(result.error);
+      }
+      return 1;
+    }
+    console.log(`${name} daemon stopped (was PID: ${result.value.pid})`);
+    return 0;
+  };
+
+  const status: CommandHandler = async (_args, json) => {
+    const s = await getDaemon().status();
+
+    if (json) {
+      console.log(JSON.stringify(s, null, 2));
+      return s.running ? 0 : 1;
+    }
+
+    if (!s.running) {
+      console.log(`${name} is not running`);
+      return 1;
+    }
+
+    const uptimeStr = s.uptime != null ? formatUptime(s.uptime) : "unknown";
+    const portStr = s.port != null ? `, port: ${s.port}` : "";
+    console.log(
+      `${name} is running (PID: ${s.pid}${portStr}, uptime: ${uptimeStr})`,
+    );
+    return 0;
+  };
+
+  const restart: CommandHandler = async () => {
+    const result = await getDaemon().restart();
+    if (!result.ok) {
+      console.error(result.error);
+      return 1;
+    }
+    const { pid, port } = result.value;
+    const portStr = port != null ? `, port: ${port}` : "";
+    console.log(`${name} daemon restarted (PID: ${pid}${portStr})`);
+    return 0;
+  };
+
+  return { start, stop, status, restart };
+}
+
+// --- Health command factory ---
+
+export interface HealthCommandOpts {
+  /** Service name (e.g. "synapse"). Used in output messages. */
+  name: string;
+  /** Returns the health endpoint URL. Called lazily per invocation. */
+  getHealthUrl: () => string;
+  /**
+   * Optional callback to print service-specific health data after the
+   * standard Status/Version/Uptime fields (e.g. provider health table).
+   */
+  formatExtra?: (data: Record<string, unknown>) => void;
+}
+
+/**
+ * Create a standard `health` CLI command that fetches /health and displays
+ * the result. Supports --json for machine-readable output.
+ */
+export function createHealthCommand(opts: HealthCommandOpts): CommandHandler {
+  const { name, getHealthUrl, formatExtra } = opts;
+
+  return async (_args, json) => {
+    const healthUrl = getHealthUrl();
+    const port = safeParsePort(healthUrl);
+
+    let response: Response;
+    try {
+      response = await fetch(healthUrl);
+    } catch {
+      if (json) {
+        console.log(JSON.stringify({ error: "Server not reachable", port }));
+      } else {
+        console.error(`${name} is not running on port ${port}`);
+      }
+      return 1;
+    }
+
+    const data = (await response.json()) as Record<string, unknown>;
+
+    if (json) {
+      console.log(JSON.stringify(data, null, 2));
+      return data.status === "healthy" ? 0 : 1;
+    }
+
+    console.log(
+      `\nStatus:  ${data.status === "healthy" ? "healthy" : "degraded"}`,
+    );
+    console.log(`Version: ${data.version}`);
+    if (typeof data.uptime === "number") {
+      console.log(`Uptime:  ${formatUptime(data.uptime)}`);
+    }
+
+    if (formatExtra) {
+      formatExtra(data);
+    }
+
+    console.log();
+    return data.status === "healthy" ? 0 : 1;
+  };
+}
+
+/** Extract port from a URL string, returning "unknown" on failure. */
+function safeParsePort(url: string): string {
+  try {
+    return new URL(url).port || "unknown";
+  } catch {
+    return "unknown";
+  }
+}

package/src/http.ts

@@ -81,6 +81,17 @@ export interface ServerOpts {
     req: Request,
     url: URL,
   ) => Response | Promise<Response> | null | Promise<Response | null>;
+  /**
+   * Optional custom health endpoint handler.
+   * When provided, called instead of the default healthResponse().
+   * Return a full Response to control both body and HTTP status
+   * (e.g. 503 for degraded state). Use healthResponse() inside
+   * the handler for the standard healthy case.
+   */
+  onHealth?: (
+    version: string,
+    startTime: number,
+  ) => Response | Promise<Response>;
 }
 
 export interface HttpServer {
@@ -100,7 +111,7 @@ export interface HttpServer {
  *   4. If onRequest returns null -> 404
  */
 export function createServer(opts: ServerOpts): HttpServer {
-  const { port, host = "127.0.0.1", version, onRequest, name } = opts;
+  const { port, host = "127.0.0.1", version, onRequest, onHealth, name } = opts;
   const startTime = Date.now();
   const prefix = name ? `${name}: ` : "";
 
@@ -115,7 +126,9 @@ export function createServer(opts: ServerOpts): HttpServer {
       }
 
       if (url.pathname === "/health" && req.method === "GET") {
-        return healthResponse(version, startTime);
+        return onHealth
+          ? onHealth(version, startTime)
+          : healthResponse(version, startTime);
       }
 
       try {