xypriss-swagger 1.0.0

package/src/configs/Logger.ts

@@ -0,0 +1,211 @@
+import { meta } from "./meta";
+
+/**
+ * ANSI color codes for terminal output
+ */
+const ANSI = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+
+    // Foreground colors
+    black: "\x1b[30m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    blue: "\x1b[34m",
+    magenta: "\x1b[35m",
+    cyan: "\x1b[36m",
+    white: "\x1b[37m",
+    gray: "\x1b[90m",
+
+    // Bright foreground
+    brightRed: "\x1b[91m",
+    brightGreen: "\x1b[92m",
+    brightYellow: "\x1b[93m",
+    brightBlue: "\x1b[94m",
+    brightMagenta: "\x1b[95m",
+    brightCyan: "\x1b[96m",
+    brightWhite: "\x1b[97m",
+
+    // Background colors
+    bgRed: "\x1b[41m",
+    bgGreen: "\x1b[42m",
+    bgYellow: "\x1b[43m",
+    bgBlue: "\x1b[44m",
+    bgMagenta: "\x1b[45m",
+    bgCyan: "\x1b[46m",
+} as const;
+
+type LogLevel =
+    | "info"
+    | "success"
+    | "warn"
+    | "error"
+    | "debug"
+    | "http"
+    | "swagger"
+    | "db"
+    | "auth";
+
+interface LogConfig {
+    icon: string;
+    color: string;
+    label: string;
+    labelColor: string;
+}
+
+const LOG_CONFIGS: Record<LogLevel, LogConfig> = {
+    info: {
+        icon: "ℹ️ ",
+        color: ANSI.brightCyan,
+        label: "INFO",
+        labelColor: `${ANSI.bgCyan}${ANSI.black}`,
+    },
+    success: {
+        icon: "✅",
+        color: ANSI.brightGreen,
+        label: "OK",
+        labelColor: `${ANSI.bgGreen}${ANSI.black}`,
+    },
+    warn: {
+        icon: "⚠️ ",
+        color: ANSI.brightYellow,
+        label: "WARN",
+        labelColor: `${ANSI.bgYellow}${ANSI.black}`,
+    },
+    error: {
+        icon: "❌",
+        color: ANSI.brightRed,
+        label: "ERROR",
+        labelColor: `${ANSI.bgRed}${ANSI.white}`,
+    },
+    debug: {
+        icon: "🐛",
+        color: ANSI.gray,
+        label: "DEBUG",
+        labelColor: `${ANSI.bgMagenta}${ANSI.white}`,
+    },
+    http: {
+        icon: "🌐",
+        color: ANSI.brightBlue,
+        label: "HTTP",
+        labelColor: `${ANSI.bgBlue}${ANSI.white}`,
+    },
+    swagger: {
+        icon: "🛡️ ",
+        color: ANSI.brightMagenta,
+        label: "SWAGGER",
+        labelColor: `${ANSI.bgMagenta}${ANSI.white}`,
+    },
+    db: {
+        icon: "🗄️ ",
+        color: ANSI.yellow,
+        label: "DB",
+        labelColor: `${ANSI.bgYellow}${ANSI.black}`,
+    },
+    auth: {
+        icon: "🔐",
+        color: ANSI.brightYellow,
+        label: "AUTH",
+        labelColor: `${ANSI.bgYellow}${ANSI.black}`,
+    },
+};
+
+export class Logger {
+    private context: string;
+    private static showTimestamp = true;
+
+    constructor(context: string) {
+        this.context = context;
+    }
+
+    // ─── Static factory ───────────────────────────────────────────────────────
+
+    static for(context: string): Logger {
+        return new Logger(context);
+    }
+
+    static disableTimestamp(): void {
+        Logger.showTimestamp = false;
+    }
+
+    // ─── Core log method ──────────────────────────────────────────────────────
+
+    private log(level: LogLevel, ...args: unknown[]): void {
+        const cfg = LOG_CONFIGS[level];
+        const timestamp = Logger.showTimestamp
+            ? `${ANSI.dim}${ANSI.gray}${new Date().toISOString()}${ANSI.reset} `
+            : "";
+        const label = `${cfg.labelColor}${ANSI.bold} ${cfg.label} ${ANSI.reset}`;
+        const ctx = `${ANSI.dim}${ANSI.cyan}[${this.context}]${ANSI.reset}`;
+
+        // First arg gets the level color + icon, rest are passed raw so Node.js
+        // pretty-prints objects/arrays/Errors natively (no JSON.stringify needed).
+        const [first, ...rest] = args;
+        const prefix = `${timestamp}${label} ${ctx} ${cfg.color}${cfg.icon}  ${String(first)}${ANSI.reset}`;
+
+        const consoleFn =
+            level === "error"
+                ? console.error
+                : level === "warn"
+                  ? console.warn
+                  : console.log;
+
+        rest.length > 0 ? consoleFn(prefix, ...rest) : consoleFn(prefix);
+    }
+
+    // ─── Public methods ───────────────────────────────────────────────────────
+
+    info(...args: unknown[]): void {
+        this.log("info", ...args);
+    }
+
+    success(...args: unknown[]): void {
+        this.log("success", ...args);
+    }
+
+    warn(...args: unknown[]): void {
+        this.log("warn", ...args);
+    }
+
+    error(...args: unknown[]): void {
+        this.log("error", ...args);
+    }
+
+    debug(...args: unknown[]): void {
+        this.log("debug", ...args);
+    }
+
+    http(...args: unknown[]): void {
+        this.log("http", ...args);
+    }
+
+    swagger(...args: unknown[]): void {
+        this.log("swagger", ...args);
+    }
+
+    db(...args: unknown[]): void {
+        this.log("db", ...args);
+    }
+
+    auth(...args: unknown[]): void {
+        this.log("auth", ...args);
+    }
+
+    // ─── Convenience: banner / separator ─────────────────────────────────────
+
+    banner(title: string): void {
+        const line = `${ANSI.cyan}${"─".repeat(60)}${ANSI.reset}`;
+        const centered = title
+            .padStart(30 + Math.floor(title.length / 2))
+            .padEnd(60);
+        console.log(`\n${line}`);
+        console.log(`${ANSI.bold}${ANSI.brightCyan}${centered}${ANSI.reset}`);
+        console.log(`${line}\n`);
+    }
+}
+
+// ─── Default singleton logger ──────────────────────────────────────────────
+
+export const logger = Logger.for(meta.name);

package/src/configs/meta.ts

@@ -0,0 +1,12 @@
+import "xypriss";
+import { ISwaggerJSONStructure } from "../types";
+
+export const meta = __sys__.fs.readJsonSync(
+    __sys__.fs.join(__sys__.__root__, "package.json"),
+) as ISwaggerJSONStructure;
+
+export const toPascalCase = (str: string, spliter = "-") =>
+    str
+        .split(spliter)
+        .map((n) => n[0].toUpperCase() + n.slice(1))
+        .join(" ");

package/src/index.ts

@@ -0,0 +1,35 @@
+import { logger, Logger } from "./configs/Logger";
+import { meta } from "./configs/meta";
+import { SwaggerServer } from "./server";
+import { SwaggerConfig } from "./types";
+import { Plugin } from "xypriss";
+
+export function SwaggerPlugin(config: SwaggerConfig): any {
+    return Plugin.create({
+        name: meta.name,
+        version: meta.version,
+        description: meta.description,
+
+        onRegister(server) {
+            const log = Logger.for("Bootstrap");
+            log.info("Starting swagger plugin...");
+        },
+        onServerReady(server) {
+            logger.success("Swagger plugin is ready");
+
+        },
+        onServerStart(server) {
+            logger.success("Swagger plugin has started");
+
+            server.app.get("/swagger", (_req: any, res: any) => {
+                res.redirect(`http://localhost:${config.port}`);
+            });
+        },
+        onAuxiliaryServerDeploy(ops, server) {
+            SwaggerServer(config, ops, server);
+        },
+    });
+}
+
+
+

package/src/openapi.ts

@@ -0,0 +1,104 @@
+export interface OpenAPIConfig {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    paths: Record<string, any>;
+    components: {
+        securitySchemes?: Record<string, any>;
+    };
+}
+
+export function generateOpenAPI(registry: any[], config: any): OpenAPIConfig {
+    const doc: OpenAPIConfig = {
+        openapi: "3.0.0",
+        info: {
+            title:
+                __sys__.vars.__name__ ||
+                config.title ||
+                "XyPriss API Documentation",
+            version: config.version || "1.0.0",
+            description: config.description || "Generated by @xypriss/swagger",
+        },
+        paths: {},
+        components: {
+            securitySchemes: {
+                BearerAuth: {
+                    type: "http",
+                    scheme: "bearer",
+                },
+            },
+        },
+    };
+
+    for (const route of registry) {
+        if (!route.path || !route.method) continue;
+
+        // Convert Express-like path /users/:id to Swagger-like path /users/{id}
+        const openApiPath = route.path.replace(
+            /:([a-zA-Z0-9_]+)(\([^)]+\))?/g,
+            "{$1}",
+        );
+
+        if (!doc.paths[openApiPath]) {
+            doc.paths[openApiPath] = {};
+        }
+
+        const methodStr = (
+            Array.isArray(route.method) ? route.method[0] : route.method
+        ).toLowerCase();
+
+        // Base operation object
+        const operation: any = {
+            summary: route.meta?.summary || `${route.method} ${route.path}`,
+            description: route.meta?.description || "",
+            tags: route.meta?.tags || ["Default"],
+            parameters: [],
+            responses: {
+                "200": {
+                    description: "Successful response",
+                },
+            },
+        };
+
+        // If guards are detected, optionally assume it requires Auth
+        if (route.hasGuards) {
+            operation.security = [{ BearerAuth: [] }];
+        }
+
+        // Add Path Parameters
+        if (route.paramNames && route.paramNames.length > 0) {
+            for (const param of route.paramNames) {
+                // Determine if there is a Regex constraint
+                const constraintMatch = route.path.match(
+                    new RegExp(`:${param}\\\\(([^)]+)\\\\)`),
+                );
+                const pattern = constraintMatch
+                    ? constraintMatch[1]
+                    : undefined;
+
+                operation.parameters.push({
+                    name: param,
+                    in: "path",
+                    required: true,
+                    schema: {
+                        type: "string", // fallback, precise type could depend on regex
+                        pattern,
+                    },
+                });
+            }
+        }
+
+        // Add additional meta (like requestBody, query params) if defined by user within meta.openapi
+        if (route.meta?.openapi) {
+            Object.assign(operation, route.meta.openapi);
+        }
+
+        doc.paths[openApiPath][methodStr] = operation;
+    }
+
+    return doc;
+}
+

package/src/server.ts

@@ -0,0 +1,94 @@
+import { logger } from "./configs/Logger";
+import { meta, toPascalCase } from "./configs/meta";
+import { generateOpenAPI } from "./openapi";
+import { SwaggerConfig } from "./types";
+import { getSwaggerUIHtml } from "./ui";
+import { Plugin } from "xypriss";
+
+type auxis = NonNullable<
+    ReturnType<typeof Plugin.create>["onAuxiliaryServerDeploy"]
+>;
+export type OpsServerManager = Parameters<auxis>["0"] & {
+    getRouteRegistry?: () => any[];
+};
+export type XyPrissServer = Parameters<auxis>["1"];
+
+export function SwaggerServer(
+    config: SwaggerConfig,
+    ops: OpsServerManager,
+    _XServer: XyPrissServer,
+) {
+    const docPath = config.path || "/docs";
+    const specPath = `${docPath}/swagger.json`;
+    // console.log("plugin root path: ", __sys__.__root__);
+    // console.log(
+    //     "😇 env de HELLO depuis le plugin: ",
+    //     __sys__.__env__.get("HELLO"),
+    // );
+    // console.log(
+    //     "🤧 env de COMMON_VAR du root du project (devrait être undefined): ",
+    //     __sys__.__env__.get("COMMON_VAR"),
+    // );
+    const workspaceSYS = __sys__.plugins.get(meta.name);
+
+    // console.log("workspaceFS: ", workspaceFS);
+
+    if (!workspaceSYS) {
+        throw new Error(
+            toPascalCase(meta.name, "-") +
+                " is not authorized in your xypriss.config.jsonc or xypriss.config.json. Please add ",
+        );
+    }
+
+    const port = config.port || 7070;
+    const server = ops.createAuxiliaryServer({
+        server: { port },
+        security: {
+            enabled: false,
+        },
+    });
+
+    // Serve the raw OpenAPI JSON specification
+    server.get(specPath, (_req, res) => {
+        try {
+            let registry: any[] = [];
+
+            if (ops.getRouteRegistry) {
+                registry = ops.getRouteRegistry();
+            }
+
+            const spec = generateOpenAPI(registry, config);
+            res.json(spec);
+        } catch (error) {
+            logger.error("Error generating OpenAPI spec:", error);
+            res.status(500).json({
+                error: "Failed to generate documentation",
+            });
+        }
+    });
+
+    // Serve the Swagger HTML Viewer
+    server.get(docPath, (_req, res) => {
+        const html = getSwaggerUIHtml(
+            specPath,
+            config.title || workspaceSYS?.vars?.__name__ || "API Documentation",
+        );
+        res.html(html);
+    });
+
+    // Redirect root path of the sub-server to docPath
+    server.redirect("/", docPath, 301);
+
+    // Boot the auxiliary server immediately
+    const url = `http://localhost:${port}${docPath}`;
+    server.start(() => {
+        logger.swagger(
+            `${toPascalCase(meta.name)} Server isolated on port ${port}`,
+        );
+        logger.http(`GET ${url}`);
+
+    });
+}
+
+
+