@expressots/adapter-express 4.0.0-preview.1 → 4.0.0-preview.3

package/lib/cjs/adapter-express/studio/studio-integration.js

@@ -32,27 +32,56 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initializeStudio = initializeStudio;
 exports.reportStudioRuntimeInfo = reportStudioRuntimeInfo;
+exports.rescanStudioRoutes = rescanStudioRoutes;
 exports.stopStudio = stopStudio;
 exports.isStudioEnabled = isStudioEnabled;
 exports.getStudioAgent = getStudioAgent;
+const core_1 = require("@expressots/core");
+// Lazy logger accessor so `new Logger()` only fires the first time we
+// actually emit a Studio message. Routing through Logger means the
+// framework's log-level configuration (e.g. `LOG_LEVEL=WARN`) silences
+// the "listening" line as expected, instead of `console.log` always
+// printing it. Lazy construction also keeps consumers that mock
+// `@expressots/core` (test environments) from blowing up at module
+// load when their Logger mock omits `.withContext`.
+let _studioLogger = null;
+function logger() {
+    if (!_studioLogger) {
+        _studioLogger = new core_1.Logger().withContext("studio");
+    }
+    return _studioLogger;
+}
 let studioAgent = null;
 let studioEnabled = false;
 /**
- * Check if @expressots/studio-agent is installed
+ * Check if `@expressots/studio-agent` is installed and importable from the
+ * current process. Uses a dynamic `import()` rather than `require.resolve`
+ * because the latter is unavailable in pure-ESM consumers — adapter-express
+ * is published as a dual CJS/ESM build and this helper is exercised by both
+ * targets.
+ *
+ * The result is cached on first hit (success) so we avoid paying for the
+ * import twice. On failure we always retry, since the user may install the
+ * package mid-session in `expressots dev` workflows.
  */
+let _studioAgentModule = null;
 async function isStudioAgentInstalled() {
     const debug = process.env.EXPRESSOTS_STUDIO_DEBUG === "true";
+    if (_studioAgentModule !== null)
+        return true;
     try {
-        // Try to resolve the module first (works for both CJS and ESM)
-        const resolved = require.resolve("@expressots/studio-agent");
+        // Dynamic import works for both CJS (returns module.exports) and ESM
+        // (returns the ESM namespace). If the package isn't installed, Node
+        // throws ERR_MODULE_NOT_FOUND / MODULE_NOT_FOUND, which we treat as
+        // "agent not present" — adapter-express continues without Studio.
+        _studioAgentModule = await Promise.resolve().then(() => __importStar(require("@expressots/studio-agent")));
         if (debug)
-            console.log("[Studio] Resolved studio-agent at:", resolved);
+            console.log("[Studio] Loaded studio-agent successfully");
         return true;
     }
     catch (error) {
         if (debug)
-            console.log("[Studio] Cannot resolve studio-agent:", error instanceof Error ? error.message : error);
-        // Module not installed
+            console.log("[Studio] Cannot load studio-agent:", error instanceof Error ? error.message : error);
         return false;
     }
 }
@@ -108,9 +137,9 @@ async function initializeStudio(app, config = {}, appContainer) {
         const studioAgentModuleAny = studioAgentModule;
         const StudioAgent = studioAgentModuleAny.StudioAgent || studioAgentModuleAny.default?.StudioAgent;
         if (!StudioAgent) {
-            console.warn("⚠️  Studio Agent module found but StudioAgent class not exported");
+            logger().warn("Studio Agent module found but StudioAgent class not exported");
             if (debug)
-                console.log("[Studio] Module contents:", studioAgentModule);
+                logger().debug(`Module contents: ${Object.keys(studioAgentModule).join(", ")}`);
             return false;
         }
         if (debug)
@@ -133,7 +162,7 @@ async function initializeStudio(app, config = {}, appContainer) {
         // Start the agent (this also scans routes)
         await studioAgent.start();
         studioEnabled = true;
-        console.log(`[ExpressoTS] Studio Agent listening on ws://localhost:${agentOptions.port}`);
+        logger().info(`Studio Agent listening on ws://localhost:${agentOptions.port}`);
         return true;
     }
     catch (error) {
@@ -161,12 +190,12 @@ async function initializeStudio(app, config = {}, appContainer) {
         // Friendlier message for the most common failure mode: hot-reload
         // race left the port in TIME_WAIT.
         if (errorCode === "EADDRINUSE") {
-            console.warn(`⚠️  Studio Agent could not bind its WebSocket port ` +
+            logger().warn(`Studio Agent could not bind its WebSocket port ` +
                 `(${errorMessage}). The host app will continue without Studio. ` +
                 `If this happened during hot-reload, the next restart should recover.`);
             return false;
         }
-        console.warn("⚠️  Failed to initialize Studio Agent:", errorMessage);
+        logger().warn(`Failed to initialize Studio Agent: ${errorMessage}`);
         return false;
     }
 }
@@ -190,6 +219,30 @@ function reportStudioRuntimeInfo(patch) {
         // Best-effort — never break the host on a status-page update.
     }
 }
+/**
+ * Re-trigger the Studio Agent's route discovery. Used by the host
+ * after `app.listen()` so that the agent's runtime route scanner sees
+ * the fully-populated Express `_router` stack (controllers are bound
+ * by `InversifyExpressServer.build()` AFTER `initializeStudio()` runs,
+ * so the agent's first scan only catches static-source routes).
+ *
+ * No-ops when:
+ *   - Studio isn't enabled, or
+ *   - the installed agent is too old to expose `scanRoutes()`.
+ */
+async function rescanStudioRoutes() {
+    if (!studioAgent)
+        return;
+    if (typeof studioAgent.scanRoutes !== "function")
+        return;
+    try {
+        await studioAgent.scanRoutes();
+    }
+    catch (error) {
+        // Best-effort — never break the host on a Studio rescan.
+        logger().warn(`Studio route rescan failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 /**
  * Stop the Studio Agent
  */

package/lib/cjs/types/adapter-express/application-express.d.ts

@@ -1,5 +1,5 @@
 import { Server as HTTPServer } from "http";
-import { AppContainer, IConsoleMessage, IMiddleware, ProviderManager, BannerConfig } from "@expressots/core";
+import { AppContainer, IConsoleMessage, IMiddleware, Logger, ProviderManager, BannerConfig } from "@expressots/core";
 import { IWebServerPublic, RenderEngine, Server } from "@expressots/shared";
 import { interfaces } from "@expressots/core";
 /**
@@ -14,7 +14,7 @@ import { interfaces } from "@expressots/core";
  * @method isDevelopment - Verifies if the current environment is development.
  */
 export declare class AppExpress implements Server.IWebServer {
-    private logger;
+    protected logger: Logger;
     private console;
     private app;
     private serverInstance;
@@ -51,9 +51,7 @@ export declare class AppExpress implements Server.IWebServer {
     private static originalStderrWrite;
     private static logBuffer;
     private static isBuffering;
-    private static bufferingInitialized;
     private static originalGlobalConsole;
-    private static initBuffering;
     /**
      * Disable log buffering. Called by micro() to restore normal console output
      * since micro API doesn't use the banner system.
@@ -61,11 +59,17 @@ export declare class AppExpress implements Server.IWebServer {
      */
     static disableBuffering(): void;
     /**
-     * Start buffering all console output.
-     * This captures both console.log and direct process.stdout.write calls.
-     * @private
+     * Start buffering all console output for the banner-first display flow.
+     * Captures both `console.*` and direct `process.stdout.write` / `process.stderr.write`
+     * calls so they can be flushed in the correct order after the banner displays.
+     *
+     * Idempotent: calling this multiple times is safe.
+     *
+     * @public API — called by `bootstrap()` so logs emitted during container
+     * setup are captured before the `AppExpress` instance exists. Also called
+     * automatically inside the constructor as a safety net.
      */
-    private static startLogBuffering;
+    static startLogBuffering(): void;
     /**
      * Stop buffering but keep the buffered logs for later flushing.
      * This restores normal console/stdout output.
@@ -390,9 +394,47 @@ export declare class AppExpress implements Server.IWebServer {
      * harvested (keeps the WS payload small).
      */
     private collectStudioRuntimeItems;
+    /**
+     * Harvest controller- and route-scoped middleware bindings from
+     * Reflect metadata. Each entry describes a single edge the Studio
+     * architecture map should draw, e.g. "AuthMiddleware → UserController
+     * (route POST /users/:id)".
+     *
+     * The middleware values stored on `ControllerMetadata.middleware` are
+     * a polymorphic union (class, function, registered name, conditional
+     * config, …). We normalise each to a display name; entries we can't
+     * name (anonymous arrow functions, plain object configs without a
+     * `name` field) are omitted. The agent's static scan picks up the
+     * remaining named cases via decorator parsing — between the two
+     * sources Studio sees a complete graph for the common patterns.
+     */
+    private collectMiddlewareBindings;
+    /**
+     * Combine a controller's base path with a route path, normalising
+     * leading/trailing slashes. Mirrors the simpler logic Studio uses to
+     * build `RouteInfo.path` so the bindings line up with route entries.
+     */
+    private joinRoutePath;
+    /**
+     * Collect the ordered middleware pipeline from the Middleware service
+     * for forwarding to Studio. Uses feature-detection so older core
+     * versions that lack `getPipelineInfo()` won't break.
+     */
+    private collectMiddlewarePipelineItems;
+    /**
+     * Build the middleware preset info snapshot for Studio. Reads the
+     * last applied preset from the Middleware service and transforms it
+     * into the shape Studio expects.
+     */
+    private collectMiddlewarePresetInfo;
     /**
      * Display middleware startup logs after the banner.
-     * This makes startup logging transparent to the user - no need for manual code in postServerInitialization().
+     *
+     * Warnings (e.g. missing optional packages like `helmet`) are always surfaced
+     * so the developer can act on them. Informational entries (e.g. "Security
+     * configured", "Applied preset: api") are demoted to `debug` since the
+     * dashboard already shows the active middleware count; set `LOG_LEVEL=DEBUG`
+     * to see the full breakdown.
      * @private
      */
     private displayMiddlewareStartupLogs;

package/lib/cjs/types/adapter-express/express-utils/path-pattern-compat.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Express 5 / path-to-regexp v8 compatibility for the `:name(regex)`
+ * inline-constraint syntax.
+ *
+ * `path-to-regexp` v8 (the parser Express 5 ships with) removed the
+ * inline regex form entirely — `/users/:id(\\d+)` now throws
+ *
+ *   Unexpected ( at index 10: /users/:id(\\d+)
+ *
+ * That breaks two things we ship as public API:
+ *
+ *   1. The {@link Patterns} / {@link pattern} helpers in
+ *      `route-constraints.ts`, which were introduced specifically to
+ *      encourage that pattern.
+ *   2. Hand-written controller routes upgraded from v3, where users
+ *      relied on Express 4 inline regex.
+ *
+ * Rather than break those at the surface of preview-3, we keep the
+ * authoring-time syntax and translate it at decorator time:
+ *
+ *   - {@link splitPathConstraints} parses the path into a
+ *     plain-`:name`-only form plus a list of `(name, regex)` pairs.
+ *   - {@link createPathConstraintMiddleware} returns a middleware that
+ *     runs at request time and 404s when any captured `req.params[name]`
+ *     fails to match its constraint.
+ *
+ * The middleware emits an HTTP 404 (not 400) so the behaviour matches
+ * Express 4's "no route matched" semantics — under v6 of path-to-regexp,
+ * a non-matching `:id(\\d+)` simply meant the route wasn't selected and
+ * the request fell through to the framework's NotFound handler.
+ */
+import type { RequestHandler } from "express";
+export interface PathConstraint {
+    /** The `:name` placeholder, without the leading colon. */
+    paramName: string;
+    /** Compiled regex. Anchored with `^...$` to match the whole segment. */
+    regex: RegExp;
+    /** The original raw regex text, for diagnostics. */
+    rawPattern: string;
+}
+export interface SplitPath {
+    /** Path string ready to hand to Express 5 / path-to-regexp v8. */
+    path: string;
+    /** Param-level regex constraints, in path declaration order. */
+    constraints: Array<PathConstraint>;
+}
+/**
+ * Split `:name(regex)` segments out of an Express-style route path.
+ *
+ * The walker honours balanced parens inside the regex (e.g.
+ * `(\\d{4})` or `((a|b)+)`), which is more forgiving than a naive
+ * single-pass regex match would be. Returns the original path and an
+ * empty constraints list when no inline patterns are found, so this is
+ * a no-op for the common case.
+ */
+export declare function splitPathConstraints(path: string): SplitPath;
+/**
+ * Build a middleware that enforces the given param-level regex
+ * constraints on `req.params`. Returns `null` when the list is empty
+ * (so callers can avoid wiring an unnecessary middleware).
+ *
+ * When a constraint fails, the middleware delegates to `next()` without
+ * a value; the framework's NotFound handler then converts that into a
+ * 404 — same observable behaviour as Express 4's "no route matched".
+ */
+export declare function createPathConstraintMiddleware(constraints: Array<PathConstraint>): RequestHandler | null;

package/lib/cjs/types/adapter-express/express-utils/route-constraints.d.ts

@@ -1,6 +1,15 @@
 /**
  * Route parameter patterns for common use cases.
- * These are Express regex patterns that can be used in route paths.
+ *
+ * Express 5 / path-to-regexp v8 dropped the inline-regex form
+ * (`:id(\\d+)`), so the framework no longer hands these patterns to
+ * the underlying matcher verbatim. Instead, the HTTP-method decorators
+ * (`@Get`, `@Post`, …) parse the constraint out of the path at decorator
+ * time, register the route under a plain `:id` placeholder, and inject
+ * a small validator middleware that 404s when the captured value
+ * doesn't match. The user-facing semantics are unchanged: a path that
+ * uses `Patterns.NUMERIC_ID` still rejects `/users/abc` and only
+ * dispatches the handler for matches like `/users/123`.
  *
  * @example
  * ```typescript
@@ -8,12 +17,12 @@
  *
  * @Get(`/users/${pattern("id", Patterns.NUMERIC_ID)}`)
  * getUserById(@param("id") id: number) {
- *   // Only matches numeric IDs like /users/123
+ *   // Only dispatches for numeric IDs like /users/123
  * }
  *
  * @Get(`/documents/${pattern("uuid", Patterns.UUID)}`)
  * getDocument(@param("uuid") uuid: string) {
- *   // Only matches valid UUIDs
+ *   // Only dispatches for valid UUIDs
  * }
  * ```
  *

package/lib/cjs/types/adapter-express/micro-api/micro.d.ts

@@ -12,6 +12,19 @@ export interface MicroConfig {
     globalPrefix?: string;
     /** Show startup banner (default: true) */
     showBanner?: boolean;
+    /** Application environment. Auto-detected from NODE_ENV if not provided. */
+    environment?: string;
+    /** Studio Agent configuration. Auto-enabled in development when the package is installed. */
+    studio?: {
+        /** Explicitly enable/disable Studio (default: auto-detect in development) */
+        enabled?: boolean;
+        /** WebSocket port for the Studio Agent (default: 3334) */
+        port?: number;
+        /** Path to the SQLite database (default: ".studio/studio.db") */
+        dbPath?: string;
+        /** Service name shown in Studio (default: "expressots-micro") */
+        serviceName?: string;
+    };
 }
 /**
  * Route handler that can return a value or use res directly
@@ -43,10 +56,14 @@ export interface MicroApp {
     setErrorHandler(handler: express.ErrorRequestHandler): this;
     /** Start listening for requests */
     listen(port: number | string, appInfo?: IConsoleMessage): Promise<void>;
-    /** Get the underlying HTTP server (available after listen) */
-    getHttpServer(): Server;
+    /** Get the underlying HTTP server (null before listen resolves) */
+    getHttpServer(): Server | null;
     /** Get the Express app instance (for advanced use) */
     getApp(): express.Application;
+    /** Configure Studio integration (call before listen) */
+    setStudio(config: NonNullable<MicroConfig["studio"]>): this;
+    /** Check if Studio Agent is currently enabled */
+    isStudioEnabled(): boolean;
 }
 /**
  * Create a new micro API instance

package/lib/cjs/types/adapter-express/studio/index.d.ts

@@ -1 +1 @@
-export { initializeStudio, stopStudio, isStudioEnabled, getStudioAgent, reportStudioRuntimeInfo, } from "./studio-integration.js";
+export { initializeStudio, stopStudio, isStudioEnabled, getStudioAgent, reportStudioRuntimeInfo, rescanStudioRoutes, } from "./studio-integration.js";

package/lib/cjs/types/adapter-express/studio/studio-integration.d.ts

@@ -23,6 +23,7 @@ interface StudioAgentInstance {
         providerCount?: number;
         middlewareCount?: number;
         runtimeItems?: StudioRuntimeItems;
+        middlewarePreset?: StudioMiddlewarePresetInfo;
     }): void;
 }
 /**
@@ -45,6 +46,70 @@ export interface StudioRuntimeItems {
         priority?: number;
         source?: string;
     }>;
+    middleware?: Array<{
+        name: string;
+        category: string;
+        type: "built-in" | "custom";
+        order: number;
+        path?: string;
+    }>;
+    /**
+     * Controller- and route-scoped middleware bindings, harvested from
+     * `ControllerMetadata.middleware` Reflect entries after
+     * `app.listen()`. Used by the agent to draw scope-aware
+     * "middleware → controller / route" edges on the architecture map.
+     *
+     * Mirrors `MiddlewareBinding` in `@expressots/studio-agent`.
+     */
+    middlewareBindings?: Array<{
+        middlewareName: string;
+        scope: "controller" | "route";
+        controllerName: string;
+        controllerMethod?: string;
+        httpMethod?: string;
+        routePath?: string;
+    }>;
+}
+/**
+ * Middleware preset info forwarded to the Studio Agent. Mirrors
+ * `MiddlewarePresetInfo` in `@expressots/studio-agent` so the adapter
+ * doesn't need to import from the studio package.
+ */
+export interface StudioMiddlewarePresetInfo {
+    name: string;
+    hasOverrides: boolean;
+    parse?: {
+        json?: {
+            limit?: string;
+        };
+        urlencoded?: {
+            limit?: string;
+            extended?: boolean;
+        };
+        cookies?: boolean;
+    };
+    security?: {
+        tier?: string;
+        helmet?: boolean;
+        cors?: {
+            origin?: boolean | string;
+            credentials?: boolean;
+            methods?: Array<string>;
+            allowedHeaders?: Array<string>;
+        };
+        rateLimit?: {
+            windowMs?: number;
+            max?: number;
+        } | false;
+    };
+    compress?: {
+        enabled: boolean;
+        level?: number;
+    };
+    logger?: {
+        enabled: boolean;
+        implementation?: string;
+    };
 }
 interface StudioIntegrationConfig {
     enabled?: boolean;
@@ -76,7 +141,20 @@ export declare function reportStudioRuntimeInfo(patch: {
     providerCount?: number;
     middlewareCount?: number;
     runtimeItems?: StudioRuntimeItems;
+    middlewarePreset?: StudioMiddlewarePresetInfo;
 }): void;
+/**
+ * Re-trigger the Studio Agent's route discovery. Used by the host
+ * after `app.listen()` so that the agent's runtime route scanner sees
+ * the fully-populated Express `_router` stack (controllers are bound
+ * by `InversifyExpressServer.build()` AFTER `initializeStudio()` runs,
+ * so the agent's first scan only catches static-source routes).
+ *
+ * No-ops when:
+ *   - Studio isn't enabled, or
+ *   - the installed agent is too old to expose `scanRoutes()`.
+ */
+export declare function rescanStudioRoutes(): Promise<void>;
 /**
  * Stop the Studio Agent
  */