@rebasepro/server-core 0.0.1-canary.09e5ec5

package/src/utils/dev-port.ts

@@ -0,0 +1,176 @@
+/**
+ * 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;
+    }
+): Promise<number> {
+    const host = options?.host ?? "0.0.0.0";
+    const maxAttempts = options?.maxAttempts ?? MAX_PORT_ATTEMPTS;
+    const portFileDir = options?.portFileDir;
+
+    // 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);
+                }
+
+                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
+ *
+ * @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): 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 = {
+            port,
+            baseUrl: `http://localhost:${port}`,
+            pid: process.pid,
+            startedAt: new Date().toISOString()
+        };
+        fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), "utf-8");
+    } catch {
+        // Non-fatal
+    }
+}

package/src/utils/logger.ts

@@ -0,0 +1,143 @@
+/**
+ * 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

@@ -0,0 +1,38 @@
+/**
+ * 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 = () => { };
+}
+
+/**
+ * Reset console methods to their original state
+ */
+export function resetConsole() {
+    // Store original methods if not already stored
+    if (!(global as unknown as Record<string, unknown>).__originalConsole) {
+        (global as unknown as Record<string, unknown>).__originalConsole = {
+            log: console.log,
+            warn: console.warn,
+            error: console.error,
+            debug: console.debug
+        };
+    }
+
+    const original = (global as unknown as Record<string, unknown>).__originalConsole as Console;
+    console.log = original.log;
+    console.warn = original.warn;
+    console.error = original.error;
+    console.debug = original.debug;
+}

package/src/utils/request-logger.ts

@@ -0,0 +1,66 @@
+/**
+ * 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
+        };
+
+        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);
+        }
+    };
+}

package/src/utils/sql.ts

@@ -0,0 +1,38 @@
+import { sql, SQL } from "drizzle-orm";
+
+/**
+ * Returns a SQL chunk calling `auth.uid()` — the current user's ID.
+ * This is a Supabase-style helper function created in the `auth` schema
+ * that reads `app.user_id` set per-transaction by `withAuth()`.
+ *
+ * @example
+ * sql`${table.user_id} = ${authUid()}`
+ */
+export const authUid = (): SQL => {
+    return sql`auth.uid()`;
+};
+
+/**
+ * Returns a SQL chunk calling `auth.roles()` — the current user's roles
+ * as a comma-separated string.
+ * Reads `app.user_roles` set per-transaction by `withAuth()`.
+ *
+ * @example
+ * sql`auth.roles() ~ 'admin'`
+ */
+export const authRoles = (): SQL => {
+    return sql`auth.roles()`;
+};
+
+/**
+ * Returns a SQL chunk calling `auth.jwt()` — the full JWT claims as JSONB.
+ * Reads `app.jwt` set per-transaction by `withAuth()`.
+ *
+ * @example
+ * sql`auth.jwt()->>'sub'`
+ */
+export const authJwt = (): SQL => {
+    return sql`auth.jwt()`;
+};
+
+