shokupan 0.11.0 → 0.13.0

package/dist/plugins/application/dashboard/static/tabulator.css

@@ -16,6 +16,21 @@
     font-weight: bold;
 }
 
+.tabulator-menu .tabulator-menu-separator {
+    border-color: var(--card-border);
+}
+
+.tabulator-popup-container {
+    background-color: var(--bg-card);
+    border: 1px solid var(--card-border);
+    border-radius: 4px;
+    color: var(--text-primary);
+}
+
+.tabulator-menu .tabulator-menu-item:not(.tabulator-menu-item-disabled):hover {
+    background-color: var(--bg-primary);
+}
+
 .tabulator .tabulator-header .tabulator-col {
     background-color: var(--bg-card);
     border-right: 1px solid var(--card-border);
@@ -58,6 +73,7 @@
     border-bottom: 1px solid var(--card-border);
     color: var(--text-primary);
     transition: background-color 100ms ease;
+    min-height: unset !important;
 }
 
 /* Higher specificity to override Tabulator default themes */
@@ -72,12 +88,12 @@
 }
 
 .tabulator .tabulator-row.tabulator-selected {
-    background-color: var(--bg-primary) !important;
+    background-color: var(--table-row-selected-color) !important;
     color: var(--text-primary);
 }
 
 .tabulator .tabulator-row:hover {
-    background-color: var(--bg-primary) !important;
+    background-color: var(--table-row-hover-color) !important;
     color: var(--text-primary);
     cursor: pointer;
 }
@@ -85,7 +101,7 @@
 /* Cells */
 .tabulator .tabulator-row .tabulator-cell {
     border-right: 1px solid var(--card-border);
-    padding: 10px;
+    padding: 6px;
     align-content: center;
 }
 
@@ -115,4 +131,8 @@
 /* Sorting Icons */
 .tabulator .tabulator-header .tabulator-col .tabulator-col-content .tabulator-arrow {
     border-bottom-color: var(--text-secondary);
+}
+
+.tabulator [tabulator-field="timestamp"] {
+    padding: 0 4px !important;
 }

package/dist/plugins/application/dashboard/static/theme.css

@@ -24,6 +24,7 @@
 
     --text-primary: #F0F0F0;
     --text-secondary: var(--palette-dark-accent);
+    --text-flavor: #ffcc80;
     --text-muted: rgba(214, 211, 209, 0.5);
 
     --primary: var(--palette-dark-primary);
@@ -34,12 +35,15 @@
     --card-border: rgba(214, 211, 209, 0.2);
 
     --table-header-border-color: rgba(214, 211, 209, 0.2);
+    --table-row-hover-color: #382818;
+    --table-row-selected-color: #48331e;
 
     --link-color: var(--palette-dark-primary);
     --link-hover: #FFCBA0;
 
     --button-bg: var(--palette-dark-primary);
     --button-text: #1A1614;
+
 }
 
 * {

package/dist/plugins/application/error-view/index.d.ts

@@ -0,0 +1,14 @@
+import { Shokupan } from '../../../shokupan';
+import { ShokupanPlugin } from '../../../util/types';
+export interface ErrorViewConfig {
+    /**
+     * Theme for syntax highlighting (default 'dark')
+     */
+    theme?: 'light' | 'dark';
+}
+export declare class ErrorView implements ShokupanPlugin {
+    private config;
+    name: string;
+    constructor(config?: ErrorViewConfig);
+    onInit(app: Shokupan): Promise<void>;
+}

package/dist/plugins/application/error-view/monkeypatch.d.ts

@@ -0,0 +1,9 @@
+declare global {
+    interface Error {
+        timestamp?: number;
+        id?: string;
+        scope?: any;
+        structuredStack?: NodeJS.CallSite[];
+    }
+}
+export declare function applyMonkeyPatch(): void;

package/dist/plugins/application/error-view/util/source-reader.d.ts

@@ -0,0 +1,10 @@
+export interface SourceContext {
+    lines: {
+        line: number;
+        code: string;
+        isTarget: boolean;
+    }[];
+    startLine: number;
+    file: string;
+}
+export declare function readSourceContext(filePath: string | undefined, line: number, contextLines?: number): Promise<SourceContext | null>;

package/dist/plugins/application/error-view/views/error.d.ts

@@ -0,0 +1,2 @@
+import { ShokupanContext } from '../../../../context';
+export declare function renderErrorView(ctx: ShokupanContext, error: any): Promise<string>;

package/dist/plugins/application/error-view/views/status.d.ts

@@ -0,0 +1,2 @@
+import { ShokupanContext } from '../../../../context';
+export declare function renderStatusView(ctx: ShokupanContext, status: number, error: Error): string;

package/dist/plugins/application/htmx/index.d.ts

@@ -0,0 +1,39 @@
+import { Shokupan } from '../../../shokupan';
+import { Middleware, ShokupanPlugin } from '../../../util/types';
+/**
+ * Extends the ShokupanContext interface with HTMX specific helpers.
+ */
+declare module "../../../context" {
+    interface ShokupanContext {
+        /**
+         * Checks if the request is an HTMX request.
+         */
+        isHtmx: boolean;
+        /**
+         * Checks if the request is boosting.
+         */
+        isHtmxBoosted: boolean;
+        /**
+         * Sets the HX-Trigger header.
+         */
+        trigger(event: string | Record<string, any>, options?: {
+            after?: 'receive' | 'settle' | 'swap';
+        }): void;
+        /**
+         * Sets the HX-Push-Url header.
+         */
+        pushUrl(url: string | false): void;
+        /**
+         * Sets the HX-Redirect header.
+         */
+        htmxRedirect(url: string): void;
+        /**
+         * Sets the HX-Refresh header.
+         */
+        refresh(): void;
+    }
+}
+export declare class HtmxPlugin implements ShokupanPlugin {
+    onInit(app: Shokupan): Promise<void>;
+    middleware(): Middleware;
+}

package/dist/plugins/application/mcp-server/plugin.d.ts

@@ -0,0 +1,38 @@
+import { Shokupan } from '../../../shokupan';
+import { ShokupanPlugin } from '../../../util/types';
+export interface MCPServerPluginOptions {
+    /**
+     * The path to mount the MCP server to.
+     */
+    path?: string;
+    /**
+     * The root directory to scan for OpenAPI documents.
+     */
+    rootDir?: string;
+    /**
+     * Whether to allow the introspection tool.
+     */
+    allowIntrospection?: boolean;
+    /**
+     * Whether to allow tool execution.
+     */
+    allowToolExecution?: boolean;
+}
+/**
+ * Attaches an MCP server to the application.
+ * This MCP server is focus-designed to provide introspection and tool execution capabilities.
+ *
+ * If your application design requires anything custom, implement your own MCP server.
+ */
+export declare class MCPServerPlugin implements ShokupanPlugin {
+    private options;
+    private router;
+    private analyzer;
+    constructor(options?: MCPServerPluginOptions);
+    onInit(app: Shokupan): void;
+    private collectAppMcpItems;
+    private setupRoutes;
+    private registerTools;
+    private registerResources;
+    private registerPrompts;
+}

package/dist/plugins/application/openapi/analyzer.impl.d.ts

@@ -109,6 +109,10 @@ export declare class OpenAPIAnalyzer {
     /**
      * Main analysis entry point
      */
+    /**
+     * Main analysis entry point
+     */
+    private cachedResult?;
     /**
      * Main analysis entry point
      */

package/dist/plugins/application/openapi/test-setup.d.ts

@@ -0,0 +1 @@
+export declare function getSharedSpec(): Promise<any>;

package/dist/plugins/application/opentelemetry/index.d.ts

@@ -0,0 +1,33 @@
+import { Shokupan } from '../../../shokupan';
+import { Middleware, ShokupanHandler, ShokupanPlugin } from '../../../util/types';
+export interface OpenTelemetryOptions {
+    /**
+     * Service name for traces
+     */
+    serviceName?: string;
+    /**
+     * Enable auto-instrumentation
+     * @default true
+     */
+    enableAutoInstrumentation?: boolean;
+    /**
+     * OTLP Endpoint (e.g. http://localhost:4318)
+     */
+    otlpEndpoint?: string;
+}
+export declare class OpenTelemetryPlugin implements ShokupanPlugin {
+    private options;
+    private api;
+    private sdk;
+    constructor(options?: OpenTelemetryOptions);
+    onInit(app: Shokupan): Promise<void>;
+    middleware(): Middleware;
+}
+/**
+ * Wraps a middleware function with an OpenTelemetry span.
+ */
+export declare function traceMiddleware(fn: Middleware, name?: string): Middleware;
+/**
+ * Wraps a route handler with an OpenTelemetry span.
+ */
+export declare function traceHandler(fn: ShokupanHandler | ((...args: any[]) => any), name: string): ShokupanHandler;

package/dist/plugins/middleware/compression.d.ts

@@ -1,13 +1,23 @@
 import { Middleware } from '../../util/types';
 export interface CompressionOptions {
     /**
-     * Minimum byte size to compress
+     * Minimum byte size to compress responses
      */
     threshold?: number;
     /**
-     * Allowed algorithms
+     * Allowed algorithms for response compression
      */
     allowedAlgorithms?: string[];
+    /**
+     * Enable request decompression
+     * @default true
+     */
+    decompress?: boolean;
+    /**
+     * Maximum size of decompressed request body in bytes to prevent zipbomb style attacks
+     * @default 10485760 (10MB)
+     */
+    maxDecompressedSize?: number;
 }
 /**
  * Compression middleware.

package/dist/plugins/middleware/rate-limit.d.ts

@@ -49,6 +49,11 @@ export interface RateLimitOptions {
      * List of trusted proxy IPs
      */
     trustedProxies?: string[];
+    /**
+     * Interval in milliseconds to clean up expired entries.
+     * Defaults to windowMs.
+     */
+    cleanupInterval?: number;
 }
 /**
  * Rate limit middleware.

package/dist/plugins/middleware/session.d.ts

@@ -148,10 +148,10 @@ export declare class MemoryStore extends EventEmitter implements Store {
 export interface SessionContext {
     session: SessionData & {
         id: string;
-        regenerate(callback: (err: any) => void): void;
-        destroy(callback: (err: any) => void): void;
-        reload(callback: (err: any) => void): void;
-        save(callback: (err: any) => void): void;
+        regenerate(): Promise<void>;
+        destroy(): Promise<void>;
+        reload(): Promise<void>;
+        save(): Promise<void>;
         touch(): void;
     };
     sessionID: string;

package/dist/plugins/resilience/decorators.d.ts

@@ -0,0 +1,23 @@
+export interface RetryOptions {
+    attempts?: number;
+    backoff?: 'constant' | 'exponential';
+    delay?: number;
+    maxDelay?: number;
+}
+export interface CircuitBreakerOptions {
+    threshold?: number;
+    windowDuration?: number;
+    resetTimeout?: number;
+}
+export interface ResilienceConfig {
+    retry?: RetryOptions;
+    circuitBreaker?: CircuitBreakerOptions;
+    timeout?: number;
+    bulkhead?: number;
+    fallback?: any | ((...args: any[]) => any);
+}
+export declare function Retry(options?: RetryOptions): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare function CircuitBreaker(options?: CircuitBreakerOptions): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare function Timeout(duration: number): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare function Bulkhead(limit: number): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare function Fallback(valueOrFn: any): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;

package/dist/plugins/resilience/factory.d.ts

@@ -0,0 +1,5 @@
+import { IPolicy } from 'cockatiel';
+import { ResilienceConfig } from './decorators';
+export declare class ResilienceFactory {
+    static createPolicy(config: ResilienceConfig): IPolicy;
+}

package/dist/plugins/resilience/index.d.ts

@@ -0,0 +1,2 @@
+export * from './decorators';
+export * from './factory';

package/dist/router.d.ts

@@ -1,6 +1,6 @@
 import { ShokupanContext } from './context';
 import { Shokupan } from './shokupan';
-import { SurrealDatastore } from './util/datastore';
+import { McpProtocol, McpPrompt } from './util/mcp-protocol';
 import { $appRoot, $childControllers, $childRouters, $isApplication, $isMounted, $isRouter, $mountPath, $parent, $routes } from './util/symbol';
 import { GuardAPISpec, HeadersInit, JSXRenderer, Method, MethodAPISpec, Middleware, OpenAPIOptions, ProcessResult, RequestOptions, RouteMetadata, RouteParams, ShokupanController, ShokupanHandler, ShokupanHooks, ShokupanRoute, ShokupanRouteConfig, StaticServeOptions } from './util/types';
 export declare const RouterRegistry: Map<string, ShokupanRouter<any>>;
@@ -95,7 +95,6 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
     get hasBeforeValidateHook(): boolean;
     get hasAfterValidateHook(): boolean;
     requestTimeout?: number;
-    get db(): SurrealDatastore | undefined;
     private hookCache;
     private hooksInitialized;
     middleware: Middleware[];
@@ -106,12 +105,14 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
         development: boolean;
         enableAsyncLocalStorage: boolean;
         enableOpenApiGen: boolean;
+        enablePromiseMonkeypatch: boolean;
         blockOnOpenApiGen: boolean;
         enableAsyncApiGen: boolean;
         blockOnAsyncApiGen: boolean;
         reusePort: boolean;
         controllersOnly: boolean;
         enableTracing?: boolean;
+        queryParserMode?: "extended" | "simple" | "strict";
         jsonParser?: "native" | "parse-json" | "secure-json-parse";
         autoBackpressureFeedback?: boolean;
         autoBackpressureLevel?: number;
@@ -131,11 +132,12 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
             fatal: (msg: string, props: Record<string, any>) => void;
         };
         readTimeout: number;
+        maxBodySize?: number;
         requestTimeout: number;
         writeTimeout: number;
         renderer: JSXRenderer;
         serverFactory: import('.').ServerFactory;
-        adapter?: "bun" | "node" | "wintercg" | import('./util/adapter/adapters').ServerAdapter;
+        adapter?: "bun" | "node" | "wintercg" | import('./util/adapter').ServerAdapter;
         fileSystem?: import('./util/adapter/filesystem').FileSystemAdapter;
         hooks: ShokupanHooks<Record<string, any>> | ShokupanHooks<Record<string, any>>[];
         validateStatusCodes: boolean;
@@ -173,11 +175,13 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
                 spec_url: string;
             }>;
         };
+        defaultSecurityHeaders?: boolean | any;
     }>;
     get root(): Shokupan<any>;
     [$routes]: ShokupanRoute[];
     private trie;
     metadata?: RouteMetadata;
+    mcpProtocol: McpProtocol;
     private currentGuards;
     private eventHandlers;
     /**
@@ -185,7 +189,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * Middleware will run for all routes matched by this router.
      */
     use(middleware: Middleware): this;
-    getComponentRegistry(): {
+    get registry(): {
         metadata: RouteMetadata;
         middleware: {
             name: string;
@@ -238,6 +242,22 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * Registers a lifecycle hook dynamically.
      */
     hook(name: keyof ShokupanHooks, handler: Function): this;
+    /**
+     * Registers an MCP Tool.
+     */
+    tool(name: string, schema: any, handler: Function): this;
+    /**
+     * Registers an MCP Prompt.
+     */
+    prompt(name: string, args: McpPrompt['arguments'], handler: Function): this;
+    /**
+     * Registers an MCP Resource.
+     */
+    resource(uri: string, options: {
+        name?: string;
+        description?: string;
+        mimeType?: string;
+    }, handler: Function): this;
     /**
      * Finds an event handler(s) by name.
      */
@@ -245,7 +265,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
     /**
      * Registers a controller instance to the router.
      */
-    registerControllerInstance(controller: any): void;
+    bindController(controller: any): void;
     /**
      * Returns all registered event handlers.
      */
@@ -323,10 +343,6 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
         requestTimeout?: number;
         renderer?: JSXRenderer;
         controller?: any;
-        metadata?: {
-            file: string;
-            line: number;
-        };
         middleware?: Middleware[];
     }): this;
     /**

package/dist/server.d.ts

@@ -0,0 +1,22 @@
+import { Shokupan } from './shokupan';
+/**
+ * Shokupan Server
+ *
+ * Responsible for the lifecycle of the HTTP server (listen, stop)
+ * and managing the underlying adapter (Bun, Node, etc).
+ */
+export declare class ShokupanServer {
+    private app;
+    private server?;
+    private adapter?;
+    constructor(app: Shokupan);
+    /**
+     * Starts the application server.
+     * @param port The port to listen on.
+     */
+    listen(port?: number): Promise<any>;
+    /**
+     * Stops the server.
+     */
+    stop(closeActiveConnections?: boolean): Promise<void>;
+}

package/dist/shokupan.d.ts

@@ -76,9 +76,11 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
     private asyncApiSpecPromise?;
     private composedMiddleware?;
     private cpuMonitor?;
-    private server?;
+    server?: Server<any>;
+    private httpServer?;
     private datastore?;
     dbPromise?: Promise<any>;
+    private rootTrie?;
     get db(): SurrealDatastore | undefined;
     get logger(): {
         verbose: boolean;
@@ -114,6 +116,17 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
      * This happens after generateOpenApi() but before the server starts listening (or at least before it finishes startup if async).
      */
     onSpecAvailable(callback: (spec: any) => void | Promise<void>): this;
+    /**
+     * Starts the application server.
+     *
+     * @param port - The port to listen on. If not specified, the port from the configuration is used. If that is not specified, port 3000 is used.
+     * @returns The server instance.
+     */
+    /**
+     * Prepare the application for listening.
+     * Use this if you want to initialize the app without starting the server immediately.
+     */
+    start(): Promise<void>;
     /**
      * Starts the application server.
      *
@@ -155,4 +168,14 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
      */
     fetch(req: Request, server?: Server<any>): Promise<Response>;
     private handleRequest;
+    /**
+     * Compiles all routes into a master Trie for O(1) router lookup.
+     * Use this if adding routes dynamically after start (not recommended but possible).
+     */
+    compile(): void;
+    private flattenRoutes;
+    find(method: string, path: string): {
+        handler: import('.').ShokupanHandler<T>;
+        params: Record<string, string>;
+    };
 }

package/dist/util/adapter/bun.d.ts

@@ -0,0 +1,8 @@
+import { Server } from 'bun';
+import { Shokupan } from '../../shokupan';
+import { ServerAdapter } from './interface';
+export declare class BunAdapter implements ServerAdapter {
+    private server?;
+    listen(port: number, app: Shokupan): Promise<Server<any>>;
+    stop(): Promise<void>;
+}

package/dist/util/adapter/index.d.ts

@@ -0,0 +1,4 @@
+export * from './bun';
+export * from './interface';
+export * from './node';
+export * from './wintercg';

package/dist/util/adapter/interface.d.ts

@@ -0,0 +1,12 @@
+import { Server } from 'bun';
+import { Shokupan } from '../../shokupan';
+export interface ServerAdapter {
+    /**
+     * Start listening on the specified port.
+     */
+    listen(port: number, app: Shokupan): Promise<Server<any>>;
+    /**
+     * Stop the server.
+     */
+    stop?(): Promise<void>;
+}

package/dist/util/adapter/node.d.ts

@@ -0,0 +1,8 @@
+import { Server } from 'bun';
+import { Shokupan } from '../../shokupan';
+import { ServerAdapter } from './interface';
+export declare class NodeAdapter implements ServerAdapter {
+    private server?;
+    listen(port: number, app: Shokupan): Promise<Server<any>>;
+    stop(): Promise<void>;
+}

package/dist/util/adapter/wintercg.d.ts

@@ -0,0 +1,5 @@
+import { Shokupan } from '../../shokupan';
+import { ServerAdapter } from './interface';
+export declare class WinterCGAdapter implements ServerAdapter {
+    listen(port: number, app: Shokupan): Promise<any>;
+}

package/dist/util/body-parser.d.ts

@@ -0,0 +1,30 @@
+import { ShokupanRequest } from './request';
+import { ShokupanConfig } from './types';
+/**
+ * Utility class for parsing request bodies.
+ * Handles size limits, parsing, and caching logic detached from the Context.
+ */
+export declare class BodyParser {
+    /**
+     * Parses the body of a request based on Content-Type header.
+     * @param req The ShokupanRequest object
+     * @param config Application configuration for limits and parser options
+     * @returns The parsed body or throws an error
+     */
+    static parse(req: ShokupanRequest<any>, config?: ShokupanConfig): Promise<{
+        type: string;
+        body: any;
+    }>;
+    /**
+     * Parsing helper for JSON
+     */
+    static parseJson(req: ShokupanRequest<any>, parserType: 'native' | 'parse-json' | 'secure-json-parse', maxBodySize: number): Promise<any>;
+    /**
+     * Parsing helper for FormData
+     */
+    static parseFormData(req: ShokupanRequest<any>, maxBodySize: number): Promise<FormData>;
+    /**
+     * Reads raw body as string with size enforcement
+     */
+    static readRawBody(req: ShokupanRequest<any>, maxBodySize: number): Promise<string>;
+}