shokupan 0.12.0 → 0.13.0

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

@@ -27,11 +27,10 @@ export interface MCPServerPluginOptions {
 export declare class MCPServerPlugin implements ShokupanPlugin {
     private options;
     private router;
-    private mcpServer;
-    private transport;
     private analyzer;
     constructor(options?: MCPServerPluginOptions);
     onInit(app: Shokupan): void;
+    private collectAppMcpItems;
     private setupRoutes;
     private registerTools;
     private registerResources;

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/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,5 +1,6 @@
 import { ShokupanContext } from './context';
 import { Shokupan } from './shokupan';
+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>>;
@@ -104,6 +105,7 @@ 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;
@@ -173,12 +175,13 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
                 spec_url: string;
             }>;
         };
-        securityHeaders?: boolean | any;
+        defaultSecurityHeaders?: boolean | any;
     }>;
     get root(): Shokupan<any>;
     [$routes]: ShokupanRoute[];
     private trie;
     metadata?: RouteMetadata;
+    mcpProtocol: McpProtocol;
     private currentGuards;
     private eventHandlers;
     /**
@@ -239,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.
      */
@@ -324,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/util/decorators.d.ts

@@ -94,3 +94,41 @@ export declare function Event(eventName: string): (target: any, propertyKey: str
  * Decorator: Applies a rate limit to a class or method.
  */
 export declare function RateLimit(options: RateLimitOptions): (target: any, propertyKey?: string, indexOrDescriptor?: PropertyDescriptor | number) => void;
+/**
+ * Decorator: Registers a method as an MCP Tool.
+ * @param name The name of the tool (defaults to method name if not provided)
+ * @param description Optional description
+ * @param inputSchema Optional JSON Schema for input arguments
+ */
+export declare function Tool(options?: {
+    name?: string;
+    description?: string;
+    inputSchema?: any;
+}): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Decorator: Registers a method as an MCP Prompt.
+ * @param name The name of the prompt
+ * @param description Optional description
+ * @param args Optional list of arguments
+ */
+export declare function Prompt(options?: {
+    name?: string;
+    description?: string;
+    arguments?: {
+        name: string;
+        description?: string;
+        required?: boolean;
+    }[];
+}): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Decorator: Registers a method as an MCP Resource handler.
+ * @param uri The URI pattern for the resource
+ * @param name Optional name
+ * @param description Optional description
+ * @param mimeType Optional MIME type
+ */
+export declare function Resource(uri: string, options?: {
+    name?: string;
+    description?: string;
+    mimeType?: string;
+}): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;

package/dist/util/env-loader.d.ts

@@ -0,0 +1,99 @@
+export type EnvLoaderOptions = {
+    /**
+     * If provided, k8s secrets will be loaded from the given paths
+     * @default []
+     */
+    k8sSecretMountPaths?: string[];
+    /**
+     * If provided, k8s config maps will be loaded from the given paths
+     * @default []
+     */
+    k8sConfigMapMountPaths?: string[];
+};
+type Listener<T> = (value: T) => void;
+/**
+ * A subject that emits values to listeners.
+ *
+ * This is used to emit values to listeners when they change.
+ */
+export declare class EmitterSubject<T> {
+    private _value;
+    private _listeners;
+    constructor(initialValue: T);
+    get value(): T;
+    next(newValue: T): void;
+    subscribe(callback: Listener<T>): {
+        unsubscribe: () => void;
+    };
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * Extend this class with a class of your own. The extended class static properties will then
+ * be dynamically loaded from environment variables (additionally .env files).
+ * Values will be trimmed then parsed to the type of the property.
+ *
+ * Secrets should be loaded using the getSecret method -- this prevents them from being logged
+ * or otherwise leaked, and enables the use of environment variables to load secrets from
+ * k8s secrets, vault, etc.
+ *
+ * ```typescript
+ * class myEnv extends EnvLoader {
+ *     readonly prop = 123; // loads env variable PROP or PROP (mapped)
+ *     readonly prop_time = 123; // loads env variable PROP_TIME
+ *     readonly propTime = 123; // loads env variable PROP_TIME
+ * }
+ * ```
+ */
+declare const $secretsCache: unique symbol;
+declare const $secretSubjects: unique symbol;
+declare const $options: unique symbol;
+declare const $watchers: unique symbol;
+declare const $watchersStarted: unique symbol;
+declare const $getSecretValueInternal: unique symbol;
+declare const $getOrCreateSubject: unique symbol;
+declare const $loadSecrets: unique symbol;
+declare const $setupWatchers: unique symbol;
+declare const $updateSubject: unique symbol;
+declare const $updateMappedProperty: unique symbol;
+declare const $mapProperties: unique symbol;
+declare const $assignProperty: unique symbol;
+declare const $toSnakeCase: unique symbol;
+export declare abstract class EnvLoader {
+    private [$secretsCache];
+    private [$secretSubjects];
+    private [$options];
+    private [$watchers];
+    private [$watchersStarted];
+    constructor(options?: EnvLoaderOptions);
+    /**
+     * Initialize the loader: read secrets.
+     * This must be called after the constructor.
+     */
+    init(): Promise<void>;
+    /**
+     * Loads a secret from the environment asynchronously.
+     */
+    getSecret(key: string): Promise<string | undefined>;
+    getSecret(key: string, observer: true): Promise<EmitterSubject<string | undefined>>;
+    /**
+     * Loads a secret from the environment synchronously.
+     */
+    getSecretSync(key: string): string | undefined;
+    getSecretSync(key: string, observer: true): EmitterSubject<string | undefined>;
+    /**
+     * Loads a variable from the environment synchronously.
+     */
+    getVar(key: string): string | undefined;
+    getVar(key: string, observer: true): EmitterSubject<string | undefined>;
+    private [$getSecretValueInternal];
+    private [$getOrCreateSubject];
+    private [$loadSecrets];
+    private [$setupWatchers];
+    private [$updateSubject];
+    private [$updateMappedProperty];
+    private [$mapProperties];
+    private [$assignProperty];
+    private [$toSnakeCase];
+}
+export {};

package/dist/util/mcp-protocol.d.ts

@@ -0,0 +1,52 @@
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id?: string | number | null;
+    method: string;
+    params?: any;
+}
+export interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result?: any;
+    error?: {
+        code: number;
+        message: string;
+        data?: any;
+    };
+}
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema?: any;
+    handler: (args: any) => Promise<any> | any;
+}
+export interface McpPrompt {
+    name: string;
+    description?: string;
+    arguments?: {
+        name: string;
+        description?: string;
+        required?: boolean;
+    }[];
+    handler: (args: any) => Promise<any> | any;
+}
+export interface McpResource {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+    handler: (uri: string, args?: any) => Promise<any> | any;
+}
+export declare class McpProtocol {
+    private tools;
+    private prompts;
+    private resources;
+    constructor(tools?: McpTool[], prompts?: McpPrompt[], resources?: McpResource[]);
+    addTool(tool: McpTool): void;
+    addPrompt(prompt: McpPrompt): void;
+    addResource(resource: McpResource): void;
+    merge(other: McpProtocol): void;
+    handleMessage(message: JsonRpcRequest): Promise<JsonRpcResponse | null>;
+    private success;
+    private error;
+}

package/dist/util/promise.d.ts

@@ -0,0 +1,16 @@
+import { RequestContextStore } from './async-hooks';
+export declare const kContext: unique symbol;
+export interface PatchedPromise extends Promise<any> {
+    [kContext]?: {
+        store?: RequestContextStore;
+        stack: string;
+    };
+}
+/**
+ * Monkeypatches the global Promise constructor to attach the current AsyncLocalStorage store
+ * and a snapshot of the stack trace to every new Promise instance.
+ *
+ * This enables the application to trace unhandled rejections back to the original request
+ * and see where the dangling promise was created.
+ */
+export declare function enablePromisePatch(): void;

package/dist/util/symbol.d.ts

@@ -33,3 +33,7 @@ export declare const $cachedCookies: unique symbol;
 export declare const $ws: unique symbol;
 export declare const $socket: unique symbol;
 export declare const $io: unique symbol;
+export declare const $mcpTools: unique symbol;
+export declare const $mcpPrompts: unique symbol;
+export declare const $mcpResources: unique symbol;
+export declare const $resilienceConfig: unique symbol;

package/dist/util/types.d.ts

@@ -385,6 +385,14 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * @default true
      */
     enableOpenApiGen: boolean;
+    /**
+     * Whether to enable monkeypatching of the global Promise constructor.
+     * When enabled, Promises created within an async context will carry that context
+     * (including `requestId`) and the creation stack trace. This increases memory and
+     * cpu usage, but provides richer logging for unhandled rejections.
+     * @default false
+     */
+    enablePromiseMonkeypatch: boolean;
     /**
      * Whether to block server startup until OpenAPI generation completes.
      * Only applies when enableOpenApiGen is true.
@@ -635,9 +643,9 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
     /**
      * Configuration for Security Headers.
      * Can be a boolean to enable/disable defaults, or an object options.
-     * @default true
+     * @default false
      */
-    securityHeaders?: boolean | any;
+    defaultSecurityHeaders?: boolean | any;
     /**
      * Any other config options are allowed, but will be ignored.
      * @deprecated

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "shokupan",
-    "version": "0.12.0",
+    "version": "0.13.0",
     "description": "Shokupan is a low-lift modern web framework for Bun.",
     "author": "Andrew G. Knackstedt",
     "publishConfig": {
@@ -59,22 +59,16 @@
     },
     "dependencies": {
         "@clack/prompts": "^0.11.0",
-        "@modelcontextprotocol/sdk": "^1.25.2",
-        "@opentelemetry/api": "^1.9.0",
-        "@opentelemetry/exporter-trace-otlp-proto": "^0.208.0",
-        "@opentelemetry/resources": "^2.3.0",
-        "@opentelemetry/sdk-trace-base": "^2.3.0",
-        "@opentelemetry/sdk-trace-node": "^2.3.0",
-        "@opentelemetry/semantic-conventions": "^1.38.0",
-        "@scalar/openapi-types": "^0.5.3",
-        "js-yaml": "^4.1.1",
+        "cockatiel": "^3.2.1",
         "nanoid": "^5.1.6",
-        "socket.io": "^4.8.3",
         "tslib": "^2.8.1"
     },
     "peerDependencies": {
         "@apollo/server": "^5.2.0",
+        "@modelcontextprotocol/sdk": "^1.25.2",
+        "@opentelemetry/api": "^1.9.0",
         "@scalar/api-reference": "^1.0.0",
+        "@scalar/openapi-types": "^0.5.3",
         "@surrealdb/node": "^2.4.0",
         "ajv": "^8.0.0",
         "ajv-formats": "^3.0.0",
@@ -85,9 +79,11 @@
         "graphql": "^16.12.0",
         "graphql-yoga": "^5.18.0",
         "jose": "^6.0.0",
+        "js-yaml": "^4.1.1",
         "parse-json": "^8.0.0",
         "reflect-metadata": "^0.2.0",
         "secure-json-parse": "^4.0.0",
+        "socket.io": "^4.8.3",
         "surrealdb": "^2.0.0-alpha.16"
     },
     "peerDependenciesMeta": {
@@ -138,11 +134,38 @@
         },
         "surrealdb": {
             "optional": true
+        },
+        "@modelcontextprotocol/sdk": {
+            "optional": true
+        },
+        "@opentelemetry/api": {
+            "optional": true
+        },
+        "@scalar/openapi-types": {
+            "optional": true
+        },
+        "js-yaml": {
+            "optional": true
+        },
+        "socket.io": {
+            "optional": true
+        },
+        "youch": {
+            "optional": true
         }
     },
     "devDependencies": {
         "@apollo/server": "^5.2.0",
+        "@modelcontextprotocol/sdk": "^1.25.2",
+        "@opentelemetry/api": "^1.9.0",
+        "@opentelemetry/exporter-trace-otlp-proto": "^0.208.0",
+        "@opentelemetry/resources": "^2.3.0",
+        "@opentelemetry/sdk-trace-base": "^2.3.0",
+        "@opentelemetry/sdk-trace-node": "^2.3.0",
+        "@opentelemetry/semantic-conventions": "^1.38.0",
         "@scalar/api-reference": "^1.0.0",
+        "@scalar/openapi-types": "^0.5.3",
+        "@sentry/node": "^10.36.0",
         "@sinclair/typebox": "^0.34.47",
         "@surrealdb/node": "^2.4.0",
         "@tsconfig/bun": "^1.0.10",
@@ -163,11 +186,13 @@
         "graphql": "^16.12.0",
         "graphql-yoga": "^5.18.0",
         "jose": "^6.0.0",
+        "js-yaml": "^4.1.1",
         "parse-json": "^8.0.0",
         "preact": "^10.28.2",
         "preact-render-to-string": "^6.6.5",
         "reflect-metadata": "^0.2.0",
         "secure-json-parse": "^4.0.0",
+        "socket.io": "^4.8.3",
         "supertest": "^7.2.2",
         "surrealdb": "^2.0.0-alpha.14",
         "typescript": "~5.9.3",