@shetty4l/core 0.1.3

package/src/cli.ts

@@ -0,0 +1,109 @@
+/**
+ * CLI argument parsing and command dispatch scaffold.
+ *
+ * Zero-dependency CLI primitives shared across all services.
+ * Each service defines its own commands and help text.
+ */
+
+// --- Arg parsing ---
+
+export interface ParsedArgs {
+  command: string;
+  args: string[];
+  json: boolean;
+}
+
+/**
+ * Parse CLI arguments into a command name, positional args, and the --json flag.
+ * Strips `--json` from the args array before extracting the command.
+ */
+export function parseArgs(args: string[]): ParsedArgs {
+  const filtered = args.filter((a) => a !== "--json");
+  const json = args.includes("--json");
+  const [command = "help", ...rest] = filtered;
+  return { command, args: rest, json };
+}
+
+// --- Uptime formatting ---
+
+/**
+ * Format a duration in seconds into a human-readable string.
+ * Examples: "45s", "3m 12s", "2h 15m"
+ */
+export function formatUptime(seconds: number): string {
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) {
+    return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+  }
+  const hours = Math.floor(seconds / 3600);
+  const mins = Math.floor((seconds % 3600) / 60);
+  return `${hours}h ${mins}m`;
+}
+
+// --- Command dispatch ---
+
+export type CommandHandler = (
+  args: string[],
+  json: boolean,
+) => void | Promise<void>;
+
+export interface RunCliOpts {
+  /** Service name, used in error messages. */
+  name: string;
+  /** Current version string. */
+  version: string;
+  /** Map of command name -> handler function. */
+  commands: Record<string, CommandHandler>;
+  /** Help text to display for --help and the `help` command. */
+  help: string;
+}
+
+/**
+ * Run the CLI: parse process.argv, dispatch to the matching command handler.
+ *
+ * Handles --help/-h, --version/-v, and unknown commands automatically.
+ * Calls `process.exit(0)` after successful command execution.
+ */
+export async function runCli(opts: RunCliOpts): Promise<void> {
+  const rawArgs = process.argv.slice(2);
+
+  if (
+    rawArgs.includes("--help") ||
+    rawArgs.includes("-h") ||
+    rawArgs.length === 0
+  ) {
+    console.log(opts.help);
+    process.exit(0);
+  }
+
+  if (rawArgs.includes("--version") || rawArgs.includes("-v")) {
+    console.log(opts.version);
+    process.exit(0);
+  }
+
+  const { command, args, json } = parseArgs(rawArgs);
+
+  if (command === "help") {
+    console.log(opts.help);
+    process.exit(0);
+  }
+
+  if (command === "version") {
+    if (json) {
+      console.log(JSON.stringify({ version: opts.version }));
+    } else {
+      console.log(opts.version);
+    }
+    process.exit(0);
+  }
+
+  const handler = opts.commands[command];
+  if (!handler) {
+    console.error(`${opts.name}: unknown command "${command}"`);
+    console.error(`Run "${opts.name} --help" for usage.`);
+    process.exit(1);
+  }
+
+  await handler(args, json);
+  process.exit(0);
+}

package/src/config.ts

@@ -0,0 +1,200 @@
+/**
+ * Shared configuration loading primitives.
+ *
+ * Provides XDG directory resolution, path expansion, env var interpolation,
+ * port validation, and a generic JSON config file loader.
+ *
+ * All functions that can fail with expected errors return Result<T>.
+ * No console output — callers decide what to log.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import type { Port, Result } from "./result";
+import { err, ok } from "./result";
+
+// --- Directory resolution ---
+
+/**
+ * Resolve the XDG data directory for a service.
+ * Uses `$XDG_DATA_HOME/{name}` if set, otherwise `~/.local/share/{name}`.
+ */
+export function getDataDir(name: string): string {
+  const xdgData = process.env.XDG_DATA_HOME;
+  if (xdgData) {
+    return join(xdgData, name);
+  }
+  return join(homedir(), ".local", "share", name);
+}
+
+/**
+ * Resolve the XDG config directory for a service.
+ * Uses `$XDG_CONFIG_HOME/{name}` if set, otherwise `~/.config/{name}`.
+ */
+export function getConfigDir(name: string): string {
+  const xdgConfig = process.env.XDG_CONFIG_HOME;
+  if (xdgConfig) {
+    return join(xdgConfig, name);
+  }
+  return join(homedir(), ".config", name);
+}
+
+// --- Path expansion ---
+
+/**
+ * Expand `~` at the start of a path to the user's home directory.
+ */
+export function expandPath(path: string): string {
+  if (path.startsWith("~")) {
+    return join(homedir(), path.slice(1));
+  }
+  return path;
+}
+
+// --- Env var interpolation ---
+
+/**
+ * Replace `${ENV_VAR}` patterns in a string with the corresponding env value.
+ * Returns Err if a referenced env var is not set.
+ */
+export function interpolateEnvVars(value: string): Result<string> {
+  let error: string | undefined;
+
+  const result = value.replace(
+    /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g,
+    (_match, varName: string) => {
+      const envValue = process.env[varName];
+      if (envValue === undefined) {
+        error = `Config references \${${varName}} but it is not set in the environment`;
+        return "";
+      }
+      return envValue;
+    },
+  );
+
+  if (error) return err(error);
+  return ok(result);
+}
+
+/**
+ * Recursively walk a JSON-parsed value and interpolate env vars in all strings.
+ * Returns Err on the first missing env var.
+ */
+export function interpolateDeep(value: unknown): Result<unknown> {
+  if (typeof value === "string") {
+    return interpolateEnvVars(value);
+  }
+  if (Array.isArray(value)) {
+    const results: unknown[] = [];
+    for (const item of value) {
+      const r = interpolateDeep(item);
+      if (!r.ok) return r;
+      results.push(r.value);
+    }
+    return ok(results);
+  }
+  if (value !== null && typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      const r = interpolateDeep(v);
+      if (!r.ok) return r;
+      result[k] = r.value;
+    }
+    return ok(result);
+  }
+  return ok(value);
+}
+
+// --- Port validation ---
+
+/**
+ * Parse and validate a port number from a string value.
+ * Returns a branded Port type on success, Err on invalid input.
+ */
+export function parsePort(value: string, source: string): Result<Port> {
+  const port = Number.parseInt(value, 10);
+  if (Number.isNaN(port) || port < 1 || port > 65535) {
+    return err(
+      `${source}: "${value}" is not a valid port number (must be 1-65535)`,
+    );
+  }
+  return ok(port as Port);
+}
+
+// --- JSON config loader ---
+
+export interface LoadJsonConfigOpts<T> {
+  /** Service name, used for directory resolution. */
+  name: string;
+  /** Default config object. All fields should have defaults. */
+  defaults: T;
+  /** Path to the config file. Defaults to `~/.config/{name}/config.json`. */
+  configPath?: string;
+}
+
+export interface ConfigLoadResult<T> {
+  /** The resolved configuration. */
+  config: T;
+  /** Where the config was loaded from: "file" or "defaults". */
+  source: "file" | "defaults";
+  /** Path that was checked (whether it existed or not). */
+  path: string;
+}
+
+/**
+ * Load a JSON config file with defaults and `${ENV_VAR}` interpolation.
+ *
+ * Load order:
+ *   1. Start with `defaults`
+ *   2. Deep-merge fields from the config file (if it exists)
+ *   3. Interpolate `${ENV_VAR}` patterns in all string values
+ *
+ * Returns Result with config and metadata about the load.
+ * Services should apply their own env var overrides and validation
+ * on the returned config object.
+ */
+export function loadJsonConfig<T extends Record<string, unknown>>(
+  opts: LoadJsonConfigOpts<T>,
+): Result<ConfigLoadResult<T>> {
+  const filePath =
+    opts.configPath ?? join(getConfigDir(opts.name), "config.json");
+
+  if (!existsSync(filePath)) {
+    return ok({
+      config: { ...opts.defaults },
+      source: "defaults" as const,
+      path: filePath,
+    });
+  }
+
+  let rawText: string;
+  try {
+    rawText = readFileSync(filePath, "utf-8");
+  } catch (e) {
+    return err(`Failed to read config file ${filePath}: ${e}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawText);
+  } catch {
+    return err(`Failed to parse config file ${filePath}: invalid JSON`);
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return err(`Config file ${filePath}: must be a JSON object`);
+  }
+
+  const interpolated = interpolateDeep(parsed);
+  if (!interpolated.ok) return interpolated as Result<never>;
+
+  return ok({
+    config: {
+      ...opts.defaults,
+      ...(interpolated.value as Record<string, unknown>),
+    } as T,
+    source: "file" as const,
+    path: filePath,
+  });
+}

package/src/daemon.ts

@@ -0,0 +1,204 @@
+/**
+ * Daemon process management.
+ *
+ * Manages background service processes via PID files.
+ * Parameterized by service name so each service can reuse the same logic.
+ *
+ * No console output — returns structured results for the caller to log.
+ */
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "fs";
+import { join } from "path";
+import type { Result } from "./result";
+import { err, ok } from "./result";
+
+// --- Types ---
+
+export interface DaemonManagerOpts {
+  /** Service name (e.g. "engram"). Used in status messages. */
+  name: string;
+  /** Directory for PID and log files (e.g. ~/.config/engram). */
+  configDir: string;
+  /** Absolute path to the CLI entry point (e.g. /path/to/src/cli.ts). */
+  cliPath: string;
+  /** CLI command to run in foreground mode. Defaults to "serve". */
+  serveCommand?: string;
+  /** Health endpoint URL for verifying the daemon is responsive. */
+  healthUrl?: string;
+  /** Milliseconds to wait after spawn before health-checking. Defaults to 500. */
+  startupWaitMs?: number;
+  /** Milliseconds to wait for graceful stop before SIGKILL. Defaults to 5000. */
+  stopTimeoutMs?: number;
+}
+
+export interface DaemonStatus {
+  running: boolean;
+  pid?: number;
+  port?: number;
+  uptime?: number;
+}
+
+export interface DaemonManager {
+  start(): Promise<Result<DaemonStatus>>;
+  stop(): Promise<Result<DaemonStatus>>;
+  restart(): Promise<Result<DaemonStatus>>;
+  status(): Promise<DaemonStatus>;
+}
+
+// --- Internal helpers ---
+
+function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readPid(pidFile: string): number | undefined {
+  if (!existsSync(pidFile)) return undefined;
+  try {
+    const content = readFileSync(pidFile, "utf-8").trim();
+    const pid = Number.parseInt(content, 10);
+    return Number.isNaN(pid) ? undefined : pid;
+  } catch {
+    return undefined;
+  }
+}
+
+function writePid(pidFile: string, pid: number): void {
+  Bun.write(pidFile, String(pid));
+}
+
+function removePidFile(pidFile: string): void {
+  try {
+    unlinkSync(pidFile);
+  } catch {
+    // Already gone
+  }
+}
+
+// --- Factory ---
+
+/**
+ * Create a daemon manager for a service.
+ *
+ * The daemon is a `bun run <cliPath> serve` background process.
+ * State is tracked via a PID file in `configDir`.
+ */
+export function createDaemonManager(opts: DaemonManagerOpts): DaemonManager {
+  const {
+    name,
+    configDir,
+    cliPath,
+    serveCommand = "serve",
+    healthUrl,
+    startupWaitMs = 500,
+    stopTimeoutMs = 5000,
+  } = opts;
+
+  const pidFile = join(configDir, `${name}.pid`);
+  const logFile = join(configDir, `${name}.log`);
+
+  async function checkHealth(): Promise<{
+    healthy: boolean;
+    uptime?: number;
+    port?: number;
+  }> {
+    if (!healthUrl) return { healthy: false };
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 2000);
+      const res = await fetch(healthUrl, { signal: controller.signal });
+      clearTimeout(timeout);
+      if (!res.ok) return { healthy: false };
+      const data = (await res.json()) as {
+        uptime?: number;
+        port?: number;
+      };
+      return { healthy: true, uptime: data.uptime, port: data.port };
+    } catch {
+      return { healthy: false };
+    }
+  }
+
+  const manager: DaemonManager = {
+    async status(): Promise<DaemonStatus> {
+      const pid = readPid(pidFile);
+      if (!pid || !isProcessRunning(pid)) {
+        if (pid) removePidFile(pidFile);
+        return { running: false };
+      }
+
+      const health = await checkHealth();
+      return {
+        running: true,
+        pid,
+        uptime: health.uptime,
+        port: health.port,
+      };
+    },
+
+    async start(): Promise<Result<DaemonStatus>> {
+      const current = await manager.status();
+      if (current.running) {
+        return err(`${name}: already running (PID ${current.pid})`);
+      }
+
+      if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true });
+      }
+
+      const proc = Bun.spawn(["bun", "run", cliPath, serveCommand], {
+        stdout: Bun.file(logFile),
+        stderr: Bun.file(logFile),
+        stdin: "ignore",
+      });
+
+      writePid(pidFile, proc.pid);
+      await new Promise((resolve) => setTimeout(resolve, startupWaitMs));
+
+      const status = await manager.status();
+      if (status.running) {
+        return ok(status);
+      }
+
+      removePidFile(pidFile);
+      return err(`${name}: failed to start (check ${logFile})`);
+    },
+
+    async stop(): Promise<Result<DaemonStatus>> {
+      const current = await manager.status();
+      if (!current.running || !current.pid) {
+        removePidFile(pidFile);
+        return err(`${name}: not running`);
+      }
+
+      process.kill(current.pid, "SIGTERM");
+
+      const interval = 100;
+      let waited = 0;
+      while (waited < stopTimeoutMs) {
+        await new Promise((resolve) => setTimeout(resolve, interval));
+        waited += interval;
+        if (!isProcessRunning(current.pid)) break;
+      }
+
+      if (isProcessRunning(current.pid)) {
+        process.kill(current.pid, "SIGKILL");
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+
+      removePidFile(pidFile);
+      return ok({ running: false, pid: current.pid });
+    },
+
+    async restart(): Promise<Result<DaemonStatus>> {
+      await manager.stop();
+      return manager.start();
+    },
+  };
+
+  return manager;
+}

package/src/http.ts

@@ -0,0 +1,138 @@
+/**
+ * HTTP server infrastructure.
+ *
+ * Shared Bun.serve wrapper with automatic CORS handling,
+ * health endpoint, and JSON response utilities.
+ */
+
+// --- Constants ---
+
+const CORS_HEADERS: Readonly<Record<string, string>> = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization",
+};
+
+// --- Response utilities ---
+
+/**
+ * Standard CORS headers for local-first services.
+ * Returns a fresh copy to prevent mutation.
+ */
+export function corsHeaders(): Record<string, string> {
+  return { ...CORS_HEADERS };
+}
+
+/**
+ * CORS preflight response (204 No Content).
+ */
+export function corsPreflightResponse(): Response {
+  return new Response(null, { status: 204, headers: corsHeaders() });
+}
+
+/**
+ * JSON success response with CORS headers.
+ */
+export function jsonOk(body: unknown, status: number = 200): Response {
+  return Response.json(body, { status, headers: corsHeaders() });
+}
+
+/**
+ * JSON error response with CORS headers.
+ */
+export function jsonError(status: number, message: string): Response {
+  return Response.json({ error: message }, { status, headers: corsHeaders() });
+}
+
+/**
+ * Health endpoint response with standard fields.
+ * Pass `extra` to include service-specific health data.
+ */
+export function healthResponse(
+  version: string,
+  startTime: number,
+  extra?: Record<string, unknown>,
+): Response {
+  return jsonOk({
+    status: "healthy",
+    version,
+    uptime: Math.floor((Date.now() - startTime) / 1000),
+    ...extra,
+  });
+}
+
+// --- Server ---
+
+export interface ServerOpts {
+  /** Port to listen on. */
+  port: number;
+  /** Hostname to bind to. Defaults to "127.0.0.1". */
+  host?: string;
+  /** Service version string (included in /health response). */
+  version: string;
+  /**
+   * Application request handler.
+   * Called for all requests that are NOT OPTIONS preflight or GET /health.
+   * Return `null` to signal "not found" (server will return 404).
+   */
+  onRequest: (
+    req: Request,
+    url: URL,
+  ) => Response | Promise<Response> | null | Promise<Response | null>;
+}
+
+export interface HttpServer {
+  /** Actual port the server is listening on. */
+  port: number;
+  /** Stop the server. */
+  stop: () => void;
+}
+
+/**
+ * Create and start an HTTP server with automatic CORS and /health handling.
+ *
+ * Request handling order:
+ *   1. OPTIONS -> CORS preflight response
+ *   2. GET /health -> standard health response
+ *   3. Everything else -> `opts.onRequest()`
+ *   4. If onRequest returns null -> 404
+ */
+export function createServer(opts: ServerOpts): HttpServer {
+  const { port, host = "127.0.0.1", version, onRequest } = opts;
+  const startTime = Date.now();
+
+  const server = Bun.serve({
+    port,
+    hostname: host,
+    async fetch(req: Request): Promise<Response> {
+      const url = new URL(req.url);
+
+      if (req.method === "OPTIONS") {
+        return corsPreflightResponse();
+      }
+
+      if (url.pathname === "/health" && req.method === "GET") {
+        return healthResponse(version, startTime);
+      }
+
+      try {
+        const result = await onRequest(req, url);
+        if (result === null) {
+          return jsonError(404, `Not found: ${url.pathname}`);
+        }
+        return result;
+      } catch (error) {
+        console.error("HTTP request error:", error);
+        return jsonError(
+          500,
+          error instanceof Error ? error.message : "Internal server error",
+        );
+      }
+    },
+  });
+
+  return {
+    port: server.port ?? port,
+    stop: () => server.stop(),
+  };
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @shetty4l/core
+ *
+ * Shared infrastructure primitives for Bun/TypeScript services.
+ *
+ * Import from the root for convenience, or from sub-paths for specificity:
+ *   import { config, http } from "@shetty4l/core"
+ *   import { parsePort } from "@shetty4l/core/config"
+ */
+
+export * as cli from "./cli";
+// Domain modules — exported as namespaces
+export * as config from "./config";
+export * as daemon from "./daemon";
+export * as http from "./http";
+export type { Err, Ok, Port, Result } from "./result";
+export { err, ok } from "./result";
+export type { ShutdownOpts } from "./signals";
+export { onShutdown } from "./signals";
+// Universal primitives — exported directly
+export { readVersion } from "./version";

package/src/result.ts

@@ -0,0 +1,28 @@
+/**
+ * Lightweight Result type for explicit error handling.
+ *
+ * Use Result for expected failures (invalid input, missing files, parse errors).
+ * Use throw for programmer errors (invariant violations, bugs).
+ */
+
+// --- Result type ---
+
+export type Ok<T> = { readonly ok: true; readonly value: T };
+export type Err<E> = { readonly ok: false; readonly error: E };
+export type Result<T, E = string> = Ok<T> | Err<E>;
+
+export function ok<T>(value: T): Ok<T> {
+  return { ok: true, value };
+}
+
+export function err<E>(error: E): Err<E> {
+  return { ok: false, error };
+}
+
+// --- Branded types ---
+
+/**
+ * A validated port number (1-65535).
+ * Created only via `config.parsePort()`.
+ */
+export type Port = number & { readonly __brand: "Port" };