@rebasepro/server-core 0.7.0 → 0.9.0

package/src/utils/dev-port.ts

@@ -1,196 +0,0 @@
-/**
- * Dev-mode port resolution utilities.
- *
- * Provides a `listen` wrapper that automatically retries the next port when
- * the requested one is already in use, and writes the resolved port to a
- * well-known temp file so the CLI / frontend can discover it.
- *
- * Port affinity: when a port file already exists (e.g. after a tsx watch
- * restart), the saved port is tried FIRST so the backend stays on the same
- * port the frontend was configured with.
- *
- * This module is dev-only and should never run in production.
- */
-import type { Server } from "http";
-import path from "path";
-import fs from "fs";
-
-const MAX_PORT_ATTEMPTS = 20;
-
-/** Filename written next to the project `.env` so the CLI can read it. */
-export const DEV_PORT_FILENAME = ".rebase-dev-port";
-
-/**
- * Try to `listen` on `startPort`. If the port is busy (`EADDRINUSE`), increment
- * and retry up to `maxAttempts` times.
- *
- * When a port file already exists (written by a previous run), the saved port
- * is tried first to maintain port affinity across tsx watch restarts.
- *
- * Resolves with the port that was actually bound.
- */
-export function listenWithPortRetry(
-    server: Server,
-    startPort: number,
-    options?: {
-        host?: string;
-        maxAttempts?: number;
-        /** Absolute path to write the resolved port file into.  Defaults to `process.cwd()`. */
-        portFileDir?: string;
-        /** Service key to include in the state file for MCP server auto-discovery. */
-        serviceKey?: string;
-    }
-): Promise<number> {
-    const host = options?.host ?? "0.0.0.0";
-    const maxAttempts = options?.maxAttempts ?? MAX_PORT_ATTEMPTS;
-    const portFileDir = options?.portFileDir;
-
-    const isProd = process.env.NODE_ENV === "production";
-    if (isProd) {
-        return new Promise<number>((resolve, reject) => {
-            const onError = (err: Error) => {
-                reject(err);
-            };
-            server.once("error", onError);
-            server.listen(startPort, host, () => {
-                server.removeListener("error", onError);
-                resolve(startPort);
-            });
-        });
-    }
-
-    // Read affinity port from a previous run's port file.
-    // This ensures tsx watch restarts land on the same port the frontend was
-    // configured with, even if the CLI-computed port was different.
-    let affinityPort: number | null = null;
-    if (portFileDir) {
-        try {
-            const portFile = path.join(portFileDir, DEV_PORT_FILENAME);
-            if (fs.existsSync(portFile)) {
-                const saved = parseInt(fs.readFileSync(portFile, "utf-8").trim(), 10);
-                if (saved > 0 && saved < 65536 && saved !== startPort) {
-                    affinityPort = saved;
-                }
-            }
-        } catch { /* ignore */ }
-    }
-
-    return new Promise<number>((resolve, reject) => {
-        let attempt = 0;
-        // Build the ordered list of ports to try:
-        // 1. The affinity port (if different from startPort)
-        // 2. startPort, startPort+1, startPort+2, ...
-        const portsToTry: number[] = [];
-        if (affinityPort) portsToTry.push(affinityPort);
-        for (let i = 0; i < maxAttempts; i++) {
-            const p = startPort + i;
-            if (p !== affinityPort) portsToTry.push(p);
-        }
-
-        function tryNext(index: number) {
-            if (index >= portsToTry.length) {
-                reject(new Error(
-                    "All attempted ports are in use. " +
-                    "Stop other Rebase instances or specify a different port with --port."
-                ));
-                return;
-            }
-
-            const port = portsToTry[index];
-            attempt++;
-
-            const onError = (err: NodeJS.ErrnoException) => {
-                if (err.code === "EADDRINUSE") {
-                    server.removeListener("error", onError);
-                    tryNext(index + 1);
-                } else {
-                    reject(err);
-                }
-            };
-
-            server.once("error", onError);
-
-            server.listen(port, host, () => {
-                server.removeListener("error", onError);
-
-                // Write the port file so the CLI can pick it up
-                if (portFileDir) {
-                    try {
-                        const portFile = path.join(portFileDir, DEV_PORT_FILENAME);
-                        fs.writeFileSync(portFile, String(port), "utf-8");
-                    } catch {
-                        // Non-fatal — the CLI will fall back to parsing stdout
-                    }
-
-                    // Write .rebase/state.json so external scripts can discover
-                    // the running server port, URL, etc.
-                    writeStateFile(portFileDir, port, options?.serviceKey);
-                }
-
-                resolve(port);
-            });
-        }
-
-        tryNext(0);
-    });
-}
-
-/**
- * Clean up the dev port file and state file (call on graceful shutdown).
- */
-export function cleanupDevPortFile(dir: string): void {
-    try {
-        const portFile = path.join(dir, DEV_PORT_FILENAME);
-        if (fs.existsSync(portFile)) {
-            fs.unlinkSync(portFile);
-        }
-    } catch {
-        // ignore
-    }
-    try {
-        const stateFile = path.join(dir, ".rebase", "state.json");
-        if (fs.existsSync(stateFile)) {
-            fs.unlinkSync(stateFile);
-        }
-    } catch {
-        // ignore
-    }
-}
-
-/**
- * Write `.rebase/state.json` with runtime info for external scripts.
- *
- * Scripts can read this file to discover:
- * - `port`       — the actual port the backend is listening on
- * - `baseUrl`    — full URL including protocol and port
- * - `pid`        — the backend process ID
- * - `startedAt`  — ISO timestamp of when the server started
- * - `serviceKey` — (dev only) the REBASE_SERVICE_KEY for MCP auto-discovery
- *
- * @example Reading from a script:
- * ```ts
- * const state = JSON.parse(fs.readFileSync('.rebase/state.json', 'utf-8'));
- * const apiUrl = state.baseUrl; // "http://localhost:3519"
- * ```
- */
-function writeStateFile(projectRoot: string, port: number, serviceKey?: string): void {
-    try {
-        const rebaseDir = path.join(projectRoot, ".rebase");
-        if (!fs.existsSync(rebaseDir)) {
-            fs.mkdirSync(rebaseDir, { recursive: true });
-        }
-        const stateFile = path.join(rebaseDir, "state.json");
-        const state: Record<string, unknown> = {
-            port,
-            baseUrl: `http://localhost:${port}`,
-            pid: process.pid,
-            startedAt: new Date().toISOString()
-        };
-        if (serviceKey) {
-            state.serviceKey = serviceKey;
-        }
-        fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), "utf-8");
-    } catch {
-        // Non-fatal
-    }
-}

package/src/utils/logger.ts

@@ -1,143 +0,0 @@
-/**
- * Structured Logger for Rebase Backend
- *
- * Outputs JSON lines when `NODE_ENV=production`, human-readable prefixed
- * lines otherwise.  Designed to work with Google Cloud Logging severity levels.
- *
- * Usage:
- *   import { logger } from "./utils/logger";
- *   logger.info("Server started", { port: 3001 });
- *   logger.error("Request failed", { path: "/api/test", error: err });
- */
-
-export type LogLevel = "debug" | "info" | "warn" | "error";
-
-/** Google Cloud Logging severity strings. */
-const GCP_SEVERITY: Record<LogLevel, string> = {
-    debug: "DEBUG",
-    info: "INFO",
-    warn: "WARNING",
-    error: "ERROR"
-};
-
-const LOG_PRIORITY: Record<LogLevel, number> = {
-    debug: 0,
-    info: 1,
-    warn: 2,
-    error: 3
-};
-
-export interface LogEntry {
-    severity: string;
-    message: string;
-    timestamp: string;
-    [key: string]: unknown;
-}
-
-export interface Logger {
-    debug(message: string, data?: Record<string, unknown>): void;
-    info(message: string, data?: Record<string, unknown>): void;
-    warn(message: string, data?: Record<string, unknown>): void;
-    error(message: string, data?: Record<string, unknown>): void;
-    child(defaultFields: Record<string, unknown>): Logger;
-}
-
-function isProduction(): boolean {
-    return process.env.NODE_ENV === "production";
-}
-
-function getMinLevel(): LogLevel {
-    const env = (process.env.LOG_LEVEL || "info").toLowerCase();
-    if (env in LOG_PRIORITY) return env as LogLevel;
-    return "info";
-}
-
-/**
- * Serialise an Error into a plain object (stack + message).
- * Handles non-Error values gracefully.
- */
-function serialiseError(value: unknown): Record<string, unknown> {
-    if (value instanceof Error) {
-        return {
-            name: value.name,
-            message: value.message,
-            stack: value.stack
-        };
-    }
-    return { value: String(value) };
-}
-
-function formatData(data?: Record<string, unknown>): Record<string, unknown> | undefined {
-    if (!data) return undefined;
-    const out: Record<string, unknown> = {};
-    for (const [key, val] of Object.entries(data)) {
-        if (val instanceof Error) {
-            out[key] = serialiseError(val);
-        } else {
-            out[key] = val;
-        }
-    }
-    return out;
-}
-
-function createLogger(defaultFields: Record<string, unknown> = {}): Logger {
-    const minLevel = getMinLevel();
-
-    function emit(level: LogLevel, message: string, data?: Record<string, unknown>): void {
-        if (LOG_PRIORITY[level] < LOG_PRIORITY[minLevel]) return;
-
-        const merged = { ...defaultFields,
-...formatData(data) };
-
-        if (isProduction()) {
-            // Structured JSON for Cloud Logging
-            const entry: LogEntry = {
-                severity: GCP_SEVERITY[level],
-                message,
-                timestamp: new Date().toISOString(),
-                ...merged
-            };
-            const line = JSON.stringify(entry);
-
-            if (level === "error") {
-                process.stderr.write(line + "\n");
-            } else {
-                process.stdout.write(line + "\n");
-            }
-        } else {
-            // Human-readable for development
-            const prefix = level === "error" ? "❌"
-                : level === "warn" ? "⚠️"
-                : level === "info" ? "ℹ️"
-                : "🐛";
-            const extra = Object.keys(merged).length > 0 ? ` ${JSON.stringify(merged)}` : "";
-            const out = `${prefix} [${level.toUpperCase()}] ${message}${extra}`;
-
-            if (level === "error") {
-                console.error(out);
-            } else if (level === "warn") {
-                console.warn(out);
-            } else {
-                console.log(out);
-            }
-        }
-    }
-
-    return {
-        debug: (msg, data) => emit("debug", msg, data),
-        info: (msg, data) => emit("info", msg, data),
-        warn: (msg, data) => emit("warn", msg, data),
-        error: (msg, data) => emit("error", msg, data),
-        child(fields: Record<string, unknown>): Logger {
-            return createLogger({ ...defaultFields,
-...fields });
-        }
-    };
-}
-
-/**
- * Singleton logger instance.
- * In production: emits JSON lines with `severity`, `message`, `timestamp`.
- * In development: emits human-readable prefixed lines.
- */
-export const logger: Logger = createLogger();

package/src/utils/logging.ts

@@ -1,40 +0,0 @@
-/**
- * Configure console log levels based on environment variable
- * Call this early in your application to set up proper logging levels
- */
-export function configureLogLevel(logLevel?: string) {
-    const LOG_LEVEL = logLevel || process.env.LOG_LEVEL || "info";
-    const logLevels = { error: 0,
-warn: 1,
-info: 2,
-debug: 3 };
-    const currentLevel = logLevels[LOG_LEVEL as keyof typeof logLevels] ?? 2;
-
-    if (currentLevel < 3) console.debug = () => { };
-    if (currentLevel < 2) console.log = () => { };
-    if (currentLevel < 1) console.warn = () => { };
-    if (currentLevel < 0) console.error = () => { };
-}
-
-/** Module-scoped backup of the original console methods. */
-let originalConsole: Pick<Console, "log" | "warn" | "error" | "debug"> | undefined;
-
-/**
- * Reset console methods to their original state
- */
-export function resetConsole() {
-    // Store original methods if not already stored
-    if (!originalConsole) {
-        originalConsole = {
-            log: console.log,
-            warn: console.warn,
-            error: console.error,
-            debug: console.debug
-        };
-    }
-
-    console.log = originalConsole.log;
-    console.warn = originalConsole.warn;
-    console.error = originalConsole.error;
-    console.debug = originalConsole.debug;
-}

package/src/utils/request-id.ts

@@ -1,40 +0,0 @@
-/**
- * X-Request-ID Middleware for Hono.
- *
- * Generates a unique request identifier (UUID v4) for every inbound
- * request, or propagates an existing `X-Request-ID` header from the
- * caller. The ID is:
- *
- * 1. Stored in the Hono context (`c.get("requestId")`)
- * 2. Echoed back on the response as `X-Request-ID`
- *
- * Downstream middleware and handlers (request logger, error handler,
- * etc.) read the ID from context to include it in log entries and
- * error responses, enabling end-to-end request tracing across services.
- *
- * @example
- * ```ts
- * import { requestId } from "@rebasepro/server-core";
- * app.use("/*", requestId());
- * ```
- */
-import { randomUUID } from "node:crypto";
-import type { MiddlewareHandler } from "hono";
-import type { HonoEnv } from "../api/types";
-
-export const REQUEST_ID_HEADER = "X-Request-ID";
-
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-export function requestId(): MiddlewareHandler<HonoEnv> {
-    return async (c, next) => {
-        const incoming = c.req.header(REQUEST_ID_HEADER);
-        const id = incoming && UUID_RE.test(incoming) ? incoming : randomUUID();
-
-        c.set("requestId", id);
-
-        await next();
-
-        c.header(REQUEST_ID_HEADER, id);
-    };
-}

package/src/utils/request-logger.ts

@@ -1,72 +0,0 @@
-/**
- * Structured HTTP request logging middleware for Hono.
- *
- * Logs every request with method, path, status code, latency, and
- * content-length. In production, outputs JSON for Cloud Logging; in
- * development, emits a coloured one-liner.
- *
- * @example
- * ```ts
- * import { requestLogger } from "@rebasepro/server-core";
- * app.use("/*", requestLogger());
- * ```
- */
-import type { MiddlewareHandler } from "hono";
-import { logger as log } from "./logger";
-
-export interface RequestLoggerOptions {
-    /** Paths to skip logging (e.g. "/health"). Supports exact match. */
-    skip?: string[];
-}
-
-export function requestLogger(options?: RequestLoggerOptions): MiddlewareHandler {
-    const skipPaths = new Set(options?.skip ?? ["/health", "/favicon.ico"]);
-
-    return async (c, next) => {
-        const start = performance.now();
-        const method = c.req.method;
-        const path = c.req.path;
-
-        // Skip noisy endpoints
-        if (skipPaths.has(path)) {
-            return next();
-        }
-
-        await next();
-
-        const latencyMs = Math.round(performance.now() - start);
-        const status = c.res.status;
-        const contentLength = c.res.headers.get("content-length");
-
-        const data: Record<string, unknown> = {
-            method,
-            path,
-            status,
-            latencyMs
-        };
-
-        // Include request correlation ID if available
-        const reqId = c.get("requestId");
-        if (reqId) {
-            data.requestId = reqId;
-        }
-
-        if (contentLength) {
-            data.contentLength = parseInt(contentLength, 10);
-        }
-
-        // Extract user ID from context if auth middleware ran
-        const userId = c.get("userId" as never) as string | undefined;
-        if (userId) {
-            data.userId = userId;
-        }
-
-        if (status >= 500) {
-            log.error("request", data);
-        } else if (status >= 400) {
-            log.warn("request", data);
-        } else {
-            log.info("request", data);
-        }
-    };
-}