@loutrejs/loutre 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,69 @@
+# @loutrejs/loutre
+
+LoutreのCore packageです。Application Definition、Contract、DI、Pipeline、Task、Trigger、Environment、Arguments、Runtime bindingなど、Loutre Applicationを構成するpublic APIを提供します。
+
+> Loutreは現在v0.xです。Public APIには破壊的変更が入る可能性があります。
+
+## Install
+
+```sh
+npm install @loutrejs/loutre
+```
+
+新しいApplicationを始める場合はinitializerも利用できます。
+
+```sh
+npm create loutre@latest my-app
+```
+
+## Application model
+
+LoutreはHTTP endpointだけを中心にせず、Applicationが実行する処理を同じmodelへ載せます。
+
+- **Contract / Implementation** — protocolごとのinterfaceと実装
+- **Module / DI** — dependencyとApplication構成
+- **Pipeline / Layer** — requestやexecution contextの処理
+- **Task / Trigger / Queue** — 明示実行、schedule、queue consumer
+- **Environment / Arguments** — Hostから渡されるtyped input
+- **Application Graph** — Application構造をRuntimeとToolingで共有
+
+## Example
+
+```ts
+import { defineApplication, task } from '@loutrejs/loutre'
+
+export const hello = task<void, string>({
+  name: 'hello',
+  factory: () => () => 'Hello, Loutre!',
+})
+
+export default defineApplication({
+  modules: [],
+  tasks: [hello],
+})
+```
+
+## Entry points
+
+主なsubpath exportは次のとおりです。
+
+| Entry point                     | Role                     |
+| ------------------------------- | ------------------------ |
+| `@loutrejs/loutre/http`         | HTTP Contract / Pipeline |
+| `@loutrejs/loutre/host`         | Application bootstrap    |
+| `@loutrejs/loutre/binding`      | Host / Queue binding     |
+| `@loutrejs/loutre/runtime`      | Runtime capability       |
+| `@loutrejs/loutre/graph`        | Application Graph        |
+| `@loutrejs/loutre/openapi`      | OpenAPI generation       |
+| `@loutrejs/loutre/presentation` | startup presentation     |
+| `@loutrejs/loutre/message-port` | MessagePort protocol     |
+
+## Documentation
+
+- [Getting Started](https://github.com/come25136/loutrejs/blob/main/docs/getting-started.md)
+- [Architecture](https://github.com/come25136/loutrejs/blob/main/docs/architecture.md)
+- [Examples](https://github.com/come25136/loutrejs/tree/main/examples)
+
+## License
+
+[MIT](https://github.com/come25136/loutrejs/blob/main/LICENSE)

package/dist/adapters/aws-lambda.js

@@ -1,4 +1,5 @@
 import { binding, } from '../application/index.js';
+import { assertRuntimeEngine } from '../runtime/engine.js';
 export const awsLambdaRuntime = {
     runtime: 'aws-lambda',
     capabilities: new Set([
@@ -12,6 +13,7 @@ export const awsLambdaRuntime = {
     bind,
 };
 function bind(options) {
+    assertRuntimeEngine('aws-lambda');
     const invocation = binding.invocation({
         application: options.application,
         environment: 'environment' in options ? options.environment : process.env,

package/dist/adapters/bun.d.ts

@@ -3,12 +3,14 @@ type IsAny<TValue> = 0 extends 1 & TValue ? true : false;
 type HttpApplication<TDefinition extends ApplicationDefinition> = IsAny<TDefinition> extends true ? TDefinition : HasHttp<TDefinition> extends true ? TDefinition : never;
 export type BunServeOptions<TDefinition extends ApplicationDefinition> = {
     readonly application: HttpApplication<TDefinition>;
-    readonly port: number;
+    readonly port?: number;
     readonly hostname?: string;
+    readonly shutdownHooks?: boolean;
     readonly environment?: unknown;
 } & BootstrapArguments<TDefinition>;
 export interface BunServeHandle<TDefinition extends ApplicationDefinition = ApplicationDefinition> {
     readonly application: HostBindingApplication<TDefinition>;
+    readonly port: number;
     close(signal?: string): Promise<void>;
 }
 export declare const bunRuntime: {

package/dist/adapters/bun.js

@@ -1,4 +1,7 @@
 import { binding, } from '../application/index.js';
+import { LOUTRE_VERSION, detectPresentationTerminal, startStartupPresentation, } from '../presentation.js';
+import { assertRuntimeEngine } from '../runtime/engine.js';
+import { serverUrl } from '../runtime/server-url.js';
 export const bunRuntime = {
     runtime: 'bun',
     capabilities: new Set([
@@ -15,13 +18,20 @@ export const bunRuntime = {
     serve,
 };
 async function serve(options) {
+    assertRuntimeEngine('bun');
     const bun = bunGlobal();
     if (!bun?.serve) {
         throw new Error('LUTRE_BUN_UNAVAILABLE: Bun.serve() is not available.');
     }
+    const startedAt = performance.now();
+    const environment = bun.env ?? {};
+    const presentation = startStartupPresentation({ version: LOUTRE_VERSION }, {
+        terminal: detectPresentationTerminal(process.stdout, environment),
+        write: (value) => console.log(value),
+    });
     const host = binding.host({
         application: options.application,
-        environment: 'environment' in options ? options.environment : (bun.env ?? undefined),
+        environment: 'environment' in options ? options.environment : environment,
         ...('arguments' in options ? { arguments: options.arguments } : {}),
     });
     const http = 'http' in host ? host.http : undefined;
@@ -33,41 +43,88 @@ async function serve(options) {
     if ('triggers' in host.application)
         await host.application.triggers.start();
     let server;
-    try {
-        server = bun.serve({
-            port: options.port,
-            ...(options.hostname === undefined ? {} : { hostname: options.hostname }),
-            fetch: createBunFetchDriver(http),
-        });
-    }
-    catch (error) {
-        await host.application.close().catch(() => undefined);
-        throw error;
+    const requestedPort = options.port;
+    let port = requestedPort ?? 3000;
+    while (true) {
+        try {
+            server = bun.serve({
+                port,
+                ...(options.hostname === undefined
+                    ? {}
+                    : { hostname: options.hostname }),
+                fetch: createBunFetchDriver(http),
+            });
+            break;
+        }
+        catch (error) {
+            if (requestedPort !== undefined || !canRetryOnNextPort(error, port)) {
+                await host.application.close().catch(() => undefined);
+                throw error;
+            }
+            port += 1;
+        }
     }
+    presentation.ready({
+        server: serverUrl(options.hostname, port),
+        runtime: `Bun ${bun.version ?? 'unknown'}`,
+        environment: environment.NODE_ENV ?? 'development',
+        startupDurationMs: performance.now() - startedAt,
+    });
     let closed = false;
-    return {
-        application: host.application,
-        async close(signal) {
-            if (closed)
-                return;
-            closed = true;
-            const errors = [];
-            try {
-                await server.stop(true);
-            }
-            catch (error) {
-                errors.push(error);
-            }
-            try {
-                await host.application.close(signal);
-            }
-            catch (error) {
-                errors.push(error);
-            }
-            if (errors.length > 0)
-                throw new AggregateError(errors, 'Bun runtime shutdown failed');
-        },
+    const closeRuntime = async (signal) => {
+        if (closed)
+            return;
+        closed = true;
+        const errors = [];
+        try {
+            await server.stop(true);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await host.application.close(signal);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length > 0)
+            throw new AggregateError(errors, 'Bun runtime shutdown failed');
+    };
+    const removeShutdownHooks = options.shutdownHooks === false
+        ? undefined
+        : registerBunShutdownHooks(closeRuntime);
+    const close = async (signal) => {
+        removeShutdownHooks?.();
+        await closeRuntime(signal);
+    };
+    return { application: host.application, port, close };
+}
+function registerBunShutdownHooks(close) {
+    const handlers = new Map();
+    const remove = () => {
+        for (const [signal, handler] of handlers)
+            process.off(signal, handler);
+        handlers.clear();
     };
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        const handler = () => {
+            remove();
+            void close(signal);
+        };
+        handlers.set(signal, handler);
+        process.once(signal, handler);
+    }
+    return remove;
+}
+function canRetryOnNextPort(error, port) {
+    return port < 65_535 && isAddressInUseError(error);
+}
+function isAddressInUseError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'EADDRINUSE');
 }
 function createBunFetchDriver(application) {
     let initialization;

package/dist/adapters/cloudflare-workers.js

@@ -1,4 +1,5 @@
 import { binding, } from '../application/index.js';
+import { assertRuntimeEngine } from '../runtime/engine.js';
 export const cloudflareWorkersRuntime = {
     runtime: 'cloudflare-workers',
     compatibilityDateMinimum: '2026-08-04',
@@ -15,6 +16,7 @@ export const cloudflareWorkersRuntime = {
     bind,
 };
 function bind(options) {
+    assertRuntimeEngine('cloudflare-workers');
     let invocation;
     let fetch;
     const resolve = (environment) => {

package/dist/adapters/deno.d.ts

@@ -6,8 +6,9 @@ export type DenoRuntimeOptions<TDefinition extends ApplicationDefinition> = {
     readonly environment?: unknown;
 } & BootstrapArguments<TDefinition>;
 export type DenoServeOptions<TDefinition extends ApplicationDefinition> = DenoRuntimeOptions<TDefinition> & {
-    readonly port: number;
+    readonly port?: number;
     readonly hostname?: string;
+    readonly shutdownHooks?: boolean;
 };
 export interface DenoBinding {
     fetch(request: Request): Promise<Response>;
@@ -15,6 +16,7 @@ export interface DenoBinding {
 }
 export interface DenoServeHandle<TDefinition extends ApplicationDefinition = ApplicationDefinition> {
     readonly application: HostBindingApplication<TDefinition>;
+    readonly port: number;
     close(signal?: string): Promise<void>;
 }
 export declare const denoRuntime: {

package/dist/adapters/deno.js

@@ -1,4 +1,7 @@
 import { binding, } from '../application/index.js';
+import { LOUTRE_VERSION, startStartupPresentation } from '../presentation.js';
+import { assertRuntimeEngine } from '../runtime/engine.js';
+import { serverUrl } from '../runtime/server-url.js';
 export const denoRuntime = {
     runtime: 'deno',
     capabilities: new Set([
@@ -16,6 +19,7 @@ export const denoRuntime = {
     serve,
 };
 function bind(options) {
+    assertRuntimeEngine('deno');
     const invocation = binding.invocation(bindingOptions(options, denoEnvironment()));
     const http = 'http' in invocation
         ? invocation.http
@@ -31,10 +35,20 @@ function bind(options) {
     };
 }
 async function serve(options) {
+    assertRuntimeEngine('deno');
     const deno = denoGlobal();
     if (!deno?.serve) {
         throw new Error('LUTRE_DENO_UNAVAILABLE: Deno.serve() is not available.');
     }
+    const startedAt = performance.now();
+    const isTTY = deno.stdout?.isTerminal?.() === true;
+    const presentation = startStartupPresentation({ version: LOUTRE_VERSION }, {
+        terminal: {
+            isTTY,
+            color: isTTY && deno.env?.get?.('NO_COLOR') === undefined,
+        },
+        write: (value) => console.log(value),
+    });
     const host = binding.host(bindingOptions(options, denoEnvironment()));
     const http = 'http' in host ? host.http : undefined;
     if (!http) {
@@ -45,42 +59,94 @@ async function serve(options) {
     if ('triggers' in host.application)
         await host.application.triggers.start();
     let server;
-    try {
-        server = deno.serve({
-            port: options.port,
-            ...(options.hostname === undefined
-                ? {}
-                : { hostname: options.hostname }),
-        }, createDenoFetchDriver(http));
-    }
-    catch (error) {
-        await host.application.close().catch(() => undefined);
-        throw error;
+    const requestedPort = options.port;
+    let port = requestedPort ?? 3000;
+    while (true) {
+        try {
+            server = deno.serve({
+                port,
+                ...(options.hostname === undefined
+                    ? {}
+                    : { hostname: options.hostname }),
+                onListen: () => undefined,
+            }, createDenoFetchDriver(http));
+            break;
+        }
+        catch (error) {
+            if (requestedPort !== undefined || !canRetryOnNextPort(error, port)) {
+                await host.application.close().catch(() => undefined);
+                throw error;
+            }
+            port += 1;
+        }
     }
+    presentation.ready({
+        server: serverUrl(options.hostname, port),
+        runtime: `Deno ${deno.version?.deno ?? 'unknown'}`,
+        environment: deno.env?.get?.('DENO_ENV') ??
+            deno.env?.get?.('NODE_ENV') ??
+            'development',
+        startupDurationMs: performance.now() - startedAt,
+    });
     let closed = false;
-    return {
-        application: host.application,
-        async close(signal) {
-            if (closed)
-                return;
-            closed = true;
-            const errors = [];
-            try {
-                await server.shutdown();
-            }
-            catch (error) {
-                errors.push(error);
-            }
-            try {
-                await host.application.close(signal);
-            }
-            catch (error) {
-                errors.push(error);
-            }
-            if (errors.length > 0)
-                throw new AggregateError(errors, 'Deno runtime shutdown failed');
-        },
+    const closeRuntime = async (signal) => {
+        if (closed)
+            return;
+        closed = true;
+        const errors = [];
+        try {
+            await server.shutdown();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await host.application.close(signal);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length > 0)
+            throw new AggregateError(errors, 'Deno runtime shutdown failed');
+    };
+    const removeShutdownHooks = options.shutdownHooks === false
+        ? undefined
+        : registerDenoShutdownHooks(deno, closeRuntime);
+    const close = async (signal) => {
+        removeShutdownHooks?.();
+        await closeRuntime(signal);
+    };
+    return { application: host.application, port, close };
+}
+function registerDenoShutdownHooks(deno, close) {
+    if (!deno.addSignalListener || !deno.removeSignalListener) {
+        return undefined;
+    }
+    const handlers = new Map();
+    const remove = () => {
+        for (const [signal, handler] of handlers) {
+            deno.removeSignalListener?.(signal, handler);
+        }
+        handlers.clear();
     };
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        const handler = () => {
+            remove();
+            void close(signal);
+        };
+        handlers.set(signal, handler);
+        deno.addSignalListener(signal, handler);
+    }
+    return remove;
+}
+function canRetryOnNextPort(error, port) {
+    return port < 65_535 && isAddressInUseError(error);
+}
+function isAddressInUseError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'EADDRINUSE');
 }
 function createDenoFetchDriver(application) {
     let initialization;

package/dist/adapters/electron.js

@@ -1,5 +1,6 @@
 import { binding, } from '../application/index.js';
 import { attachMessagePort, } from '../message-port/index.js';
+import { assertRuntimeEngine } from '../runtime/engine.js';
 export const electronRuntime = {
     runtime: 'electron',
     capabilities: new Set([
@@ -15,6 +16,7 @@ export const electronRuntime = {
     attach,
 };
 function attach(options) {
+    assertRuntimeEngine('electron');
     const invocation = binding.invocation({
         application: options.application,
         environment: 'environment' in options

package/dist/generated/version.d.ts

@@ -0,0 +1 @@
+export declare const LOUTRE_VERSION = "0.2.0";

package/dist/generated/version.js

@@ -0,0 +1,2 @@
+// package manifestとのずれを避けるため、scripts/generate-version.mjsがbuild前に更新する。
+export const LOUTRE_VERSION = '0.2.0';

package/dist/graph/graph.js

@@ -465,7 +465,7 @@ function buildDependencyGraph(modules, descriptors, targets, tasks, diagnostics)
                     diagnostic.message.includes(token.id))) {
                 diagnostics.push({
                     code: 'LUTRE_TOKEN_001',
-                    message: `Token ID ${token.id}が異なるtoken declarationで重複しています`,
+                    message: `Token ID ${token.id} is duplicated across different token declarations`,
                     path: `dependency:${token.id}`,
                 });
             }
@@ -803,7 +803,7 @@ function validateDuplicateProviders(modules, diagnostics) {
                 }
                 diagnostics.push({
                     code: 'LUTRE_DI_003',
-                    message: `Provider ${tokenName(provider.provide)}が${existing.module}と${moduleName}で重複しています`,
+                    message: `Provider ${tokenName(provider.provide)} is duplicated in ${existing.module} and ${moduleName}`,
                     path: `${moduleName}.providers.${tokenName(provider.provide)}`,
                 });
                 continue;
@@ -827,7 +827,7 @@ function collectCustomTokens(providers, targets, diagnostics) {
         if (existing && existing !== candidate) {
             diagnostics.push({
                 code: 'LUTRE_TOKEN_001',
-                message: `Token ID ${candidate.id}が異なるtoken declarationで重複しています`,
+                message: `Token ID ${candidate.id} is duplicated across different token declarations`,
                 path,
             });
             return;
@@ -856,7 +856,7 @@ function collectContextKeys(targets, diagnostics) {
                 if (existing && existing !== key) {
                     diagnostics.push({
                         code: 'LUTRE_CONTEXT_002',
-                        message: `Context Key ${key.name}が異なる宣言で重複しています`,
+                        message: `Context Key ${key.name} is duplicated across different declarations`,
                         path,
                     });
                     continue;
@@ -964,7 +964,7 @@ function validatePipeline(target, diagnostics) {
             if (!validated.has(required)) {
                 diagnostics.push({
                     code: 'LUTRE_VALIDATION_001',
-                    message: `${item.name}にはvalidation済みの${required}が必要ですが、validate.${required}より前に配置されています`,
+                    message: `${item.name} requires validated ${required} but appears before validate.${required}`,
                     path,
                 });
             }
@@ -973,7 +973,7 @@ function validatePipeline(target, diagnostics) {
             if (!available.has(required)) {
                 diagnostics.push({
                     code: 'LUTRE_PIPELINE_004',
-                    message: `${item.name}が必要とするContext Key ${contextKeyName(required)}は利用できません`,
+                    message: `Context Key ${contextKeyName(required)} required by ${item.name} is unavailable`,
                     path,
                 });
             }
@@ -982,7 +982,7 @@ function validatePipeline(target, diagnostics) {
             if (available.has(provided)) {
                 diagnostics.push({
                     code: 'LUTRE_CONTEXT_003',
-                    message: `${item.name}は既存のContext Key ${contextKeyName(provided)}を暗黙に上書きできません`,
+                    message: `${item.name} cannot implicitly overwrite existing Context Key ${contextKeyName(provided)}`,
                     path,
                 });
             }
@@ -995,7 +995,7 @@ function validatePipeline(target, diagnostics) {
             if (!response) {
                 diagnostics.push({
                     code: 'LUTRE_SHORT_CIRCUIT_001',
-                    message: `${item.name}のshort circuit variant ${shortCircuit.variant}がresponseに宣言されていません`,
+                    message: `Short-circuit variant ${shortCircuit.variant} from ${item.name} is not declared in the response`,
                     path,
                 });
                 continue;
@@ -1005,7 +1005,7 @@ function validatePipeline(target, diagnostics) {
                 response.status !== expectedStatus) {
                 diagnostics.push({
                     code: 'LUTRE_SHORT_CIRCUIT_002',
-                    message: `${item.name}のshort circuit variant ${shortCircuit.variant}はHTTP ${expectedStatus}である必要があります`,
+                    message: `Short-circuit variant ${shortCircuit.variant} from ${item.name} must use HTTP ${expectedStatus}`,
                     path,
                 });
             }

package/dist/http/application.js

@@ -301,7 +301,7 @@ async function finalizeResponse(definition, result, signal) {
     const responseHeaders = await validateResponseHeaders(response.headers, result.headers);
     if (response.stream === 'server') {
         if (!isAsyncIterable(result.body)) {
-            throw new Error('server-stream responseにはAsyncIterableが必要です');
+            throw new Error('Server-stream response requires an AsyncIterable');
         }
         const encoder = new TextEncoder();
         const iterator = result.body[Symbol.asyncIterator]();
@@ -315,7 +315,7 @@ async function finalizeResponse(definition, result, signal) {
                     finished = true;
                     signal.removeEventListener('abort', abort);
                     void iterator.return?.(signal.reason).finally(() => {
-                        controller.error(signal.reason ?? new Error('HTTP requestが中断されました'));
+                        controller.error(signal.reason ?? new Error('HTTP request was aborted'));
                     });
                 };
                 if (signal.aborted)
@@ -368,7 +368,7 @@ async function finalizeResponse(definition, result, signal) {
 async function validateResponseHeaders(schema, headers) {
     if (!schema) {
         if (headers !== undefined) {
-            throw new Error('未宣言のHTTP response headerが返されました');
+            throw new Error('Undeclared HTTP response header was returned');
         }
         return undefined;
     }
@@ -376,7 +376,7 @@ async function validateResponseHeaders(schema, headers) {
     if (validated === undefined)
         return undefined;
     if (!isHttpHeaders(validated)) {
-        throw new Error('HTTP response header schemaの出力が不正です');
+        throw new Error('HTTP response header schema produced an invalid value');
     }
     return validated;
 }
@@ -458,7 +458,7 @@ async function mapDeclaredError(definition, error) {
             if (typeof result !== 'object' ||
                 result === null ||
                 !('body' in result)) {
-                throw new Error('HTTP error mappingはbodyを返す必要があります');
+                throw new Error('HTTP error mapping must return a body');
             }
             return {
                 kind: 'http-result',

package/dist/http/basic-auth.js

@@ -40,7 +40,7 @@ function unauthorizedResult(unauthorized, challenge) {
 }
 function formatBasicChallenge(realm) {
     if (realm.length === 0 || /[\u0000-\u001f\u007f]/.test(realm)) {
-        throw new TypeError('Basic認証のrealmには空文字列または制御文字を使用できません');
+        throw new TypeError('Basic authentication realm cannot be empty or contain control characters');
     }
     const escaped = realm.replace(/[\\"]/g, '\\$&');
     return `Basic realm="${escaped}", charset="UTF-8"`;

package/dist/http/cors.js

@@ -123,12 +123,12 @@ function normalizeOrigin(origin, credentials) {
     }
     for (const value of origins) {
         if (value.length === 0 || /[\u0000-\u001f\u007f]/.test(value)) {
-            throw new TypeError('CORS originには空文字列または制御文字を使用できません');
+            throw new TypeError('CORS origin cannot be empty or contain control characters');
         }
     }
     if (origins.includes('*')) {
         if (credentials) {
-            throw new TypeError('credentialsを有効にする場合、CORS originにワイルドカードは使用できません');
+            throw new TypeError('CORS origin cannot be a wildcard when credentials are enabled');
         }
         return Object.freeze({ kind: 'wildcard' });
     }
@@ -141,7 +141,7 @@ function normalizeTokens(values, option, uppercase) {
     return Object.freeze(values.map((value) => {
         const token = value.trim();
         if (!httpToken.test(token)) {
-            throw new TypeError(`CORS ${option}に不正なHTTP tokenが含まれています`);
+            throw new TypeError(`CORS ${option} contains an invalid HTTP token`);
         }
         return uppercase ? token.toUpperCase() : token;
     }));
@@ -150,7 +150,7 @@ function normalizeMaxAge(maxAge) {
     if (maxAge === undefined)
         return undefined;
     if (!Number.isSafeInteger(maxAge) || maxAge < 0) {
-        throw new TypeError('CORS maxAgeには0以上の安全な整数を指定してください');
+        throw new TypeError('CORS maxAge must be a non-negative safe integer');
     }
     return maxAge;
 }

package/dist/message-port/index.js

@@ -41,7 +41,7 @@ export function createMessagePortExecution(options) {
                 return await runtime.execute(async () => {
                     const route = routes.find((candidate) => candidate.procedure === procedure);
                     if (!route)
-                        throw new Error(`MessagePort procedureがありません: ${procedure}`);
+                        throw new Error(`MessagePort procedure not found: ${procedure}`);
                     invocationLogger = invocationLogger.child({
                         source: `${route.implementation.name}.${route.procedure}`,
                     });
@@ -66,7 +66,7 @@ export function createMessagePortExecution(options) {
                             const target = runtime.container.implementationRuntime(route.implementation);
                             const method = target[route.procedure];
                             if (typeof method !== 'function')
-                                throw new Error('Handler methodがありません');
+                                throw new Error('Handler method is missing');
                             return Reflect.apply(method, target, [
                                 terminalContext,
                             ]);
@@ -106,10 +106,10 @@ export function createMessagePortExecution(options) {
 async function finalize(definition, result) {
     const response = definition.responses[result.variant];
     if (!response)
-        throw new Error(`未宣言variantです: ${result.variant}`);
+        throw new Error(`Undeclared variant: ${result.variant}`);
     if (response.stream === 'server') {
         if (!isAsyncIterable(result.value)) {
-            throw new Error('server-stream resultにはAsyncIterableが必要です');
+            throw new Error('Server-stream result requires an AsyncIterable');
         }
         const source = result.value;
         return {

package/dist/presentation.d.ts

@@ -0,0 +1,33 @@
+import { LOUTRE_VERSION } from './generated/version.js';
+export interface StartupPresentationInfo {
+    readonly version: string;
+}
+export interface StartupStatusInfo {
+    readonly server: string;
+    readonly runtime: string;
+    readonly environment: string;
+    readonly startupDurationMs: number;
+}
+export interface StartupPresentationSession {
+    ready(info: StartupStatusInfo): void;
+}
+export interface StartupPresentationStartOptions {
+    readonly terminal: PresentationRenderOptions;
+    readonly write: (value: string) => void;
+}
+export { LOUTRE_VERSION };
+export interface PresentationRenderOptions {
+    readonly isTTY: boolean;
+    readonly color: boolean;
+    readonly columns?: number;
+}
+export interface PresentationTerminalOutput {
+    readonly isTTY?: boolean;
+    readonly columns?: number;
+    readonly getColorDepth: (environment?: Readonly<Record<string, string | undefined>>) => number;
+}
+export declare function detectPresentationTerminal(output: PresentationTerminalOutput, environment: Readonly<Record<string, string | undefined>>): PresentationRenderOptions;
+export declare function startStartupPresentation(info: StartupPresentationInfo, options: StartupPresentationStartOptions): StartupPresentationSession;
+export declare function renderLoutreBrand(options: PresentationRenderOptions): string;
+export declare function renderStartupPrelude(info: StartupPresentationInfo, options: PresentationRenderOptions): string;
+export declare function renderStartupStatus(info: StartupStatusInfo, options: PresentationRenderOptions): string;

package/dist/presentation.js

@@ -0,0 +1,233 @@
+import { LOUTRE_VERSION } from './generated/version.js';
+export { LOUTRE_VERSION };
+export function detectPresentationTerminal(output, environment) {
+    const isTTY = output.isTTY === true;
+    const colorDisabled = environment.NO_COLOR !== undefined ||
+        environment.NODE_DISABLE_COLORS !== undefined;
+    const columns = output.columns;
+    return {
+        isTTY,
+        color: isTTY && !colorDisabled && output.getColorDepth(environment) >= 24,
+        ...(columns !== undefined && columns > 0 ? { columns } : {}),
+    };
+}
+export function startStartupPresentation(info, options) {
+    options.write(renderStartupPrelude(info, options.terminal));
+    return {
+        ready(status) {
+            options.write(renderStartupStatus(status, options.terminal));
+        },
+    };
+}
+const colors = {
+    otterLight: [244, 211, 164],
+    otterSand: [224, 179, 119],
+    otterCaramel: [198, 139, 75],
+    otterBrown: [167, 105, 58],
+    otterDeep: [112, 66, 45],
+    lavender: [192, 132, 252],
+    lavenderSoft: [196, 181, 253],
+    label: [103, 232, 249],
+    value: [74, 222, 128],
+    text: [148, 163, 184],
+    frame: [71, 85, 105],
+};
+const logoGlyphs = [
+    ['██╗     ', '██║     ', '██║     ', '██║     ', '███████╗', '╚══════╝'],
+    [
+        ' ██████╗ ',
+        '██╔═══██╗',
+        '██║   ██║',
+        '██║   ██║',
+        '╚██████╔╝',
+        ' ╚═════╝ ',
+    ],
+    [
+        '██╗   ██╗',
+        '██║   ██║',
+        '██║   ██║',
+        '██║   ██║',
+        '╚██████╔╝',
+        ' ╚═════╝ ',
+    ],
+    [
+        '████████╗',
+        '╚══██╔══╝',
+        '   ██║   ',
+        '   ██║   ',
+        '   ██║   ',
+        '   ╚═╝   ',
+    ],
+    ['██████╗ ', '██╔══██╗', '██████╔╝', '██╔══██╗', '██║  ██║', '╚═╝  ╚═╝'],
+    ['███████╗', '██╔════╝', '█████╗  ', '██╔══╝  ', '███████╗', '╚══════╝'],
+];
+const logoColors = [
+    colors.otterLight,
+    colors.otterSand,
+    colors.otterCaramel,
+    colors.otterBrown,
+    colors.otterDeep,
+    colors.otterCaramel,
+];
+const minimumContentWidth = 68;
+const metadataIndent = '        ';
+const mascot = 'ʕ•ᴥ•ʔ';
+export function renderLoutreBrand(options) {
+    if (!options.isTTY)
+        return 'Loutre';
+    if (options.columns !== undefined && options.columns < logoWidth()) {
+        return `${mascot} Loutre`;
+    }
+    const logo = renderLogo(options.color);
+    const brand = options.color
+        ? `${paint(colors.lavender, mascot)} ${paint(colors.lavenderSoft, 'Loutre')}`
+        : `${mascot} Loutre`;
+    return [...logo.styled, '', brand].join('\n');
+}
+export function renderStartupPrelude(info, options) {
+    if (!options.isTTY)
+        return renderCompactPrelude(info);
+    const layout = createStartupLayout(info);
+    if (options.columns !== undefined && options.columns < layout.frameWidth) {
+        return renderCompactPrelude(info);
+    }
+    return renderRichPrelude(info, layout.contentWidth, options.color);
+}
+export function renderStartupStatus(info, options) {
+    if (!options.isTTY)
+        return renderCompactStatus(info);
+    const layout = createStartupLayout(info);
+    if (options.columns !== undefined && options.columns < layout.frameWidth) {
+        return renderCompactStatus(info);
+    }
+    return renderRichStatus(info, layout.contentWidth, options.color);
+}
+function renderCompactPrelude(info) {
+    return `Loutre ${info.version}`;
+}
+function renderCompactStatus(info) {
+    return [
+        `Server: ${info.server}`,
+        `Runtime: ${info.runtime}`,
+        `Environment: ${info.environment}`,
+        `Ready in ${formatDuration(info.startupDurationMs)}`,
+    ].join('\n');
+}
+function renderRichPrelude(info, contentWidth, color) {
+    const layout = createFrameLayout(contentWidth, color);
+    const logo = renderLogo(color);
+    const brand = `${mascot}  version ${info.version}`;
+    const styledBrand = `${paintWhen(color, colors.lavender, mascot)}  ${paintWhen(color, colors.lavenderSoft, `version ${info.version}`)}`;
+    return [
+        layout.topBorder,
+        layout.row(''),
+        ...logo.plain.map((line, index) => layout.centered(line, logo.styled[index])),
+        layout.row(''),
+        layout.centered(brand, styledBrand),
+        layout.row(''),
+    ].join('\n');
+}
+function renderRichStatus(info, contentWidth, color) {
+    const layout = createFrameLayout(contentWidth, color);
+    const labels = ['Server', 'Runtime', 'Environment'];
+    const labelWidth = Math.max(...labels.map(displayWidth));
+    const metadata = [
+        ['Server', info.server],
+        ['Runtime', info.runtime],
+        ['Environment', info.environment],
+    ];
+    return [
+        ...metadata.map(([label, value]) => {
+            const gap = ' '.repeat(labelWidth - displayWidth(label) + 3);
+            const plain = `${metadataIndent}${label}${gap}${value}`;
+            const styled = `${metadataIndent}${paintWhen(color, colors.label, label)}${gap}${paintWhen(color, colors.value, value)}`;
+            return layout.row(plain, styled);
+        }),
+        layout.row(''),
+        layout.bottomBorder,
+        '',
+        `  ${paintWhen(color, colors.value, '✓ Ready')} ${paintWhen(color, colors.text, `in ${formatDuration(info.startupDurationMs)}`)}`,
+    ].join('\n');
+}
+function createStartupLayout(info) {
+    const labelWidth = displayWidth('Environment');
+    const metadata = ('server' in info ? [info.server, info.runtime, info.environment] : []).map((value) => displayWidth(metadataIndent) + labelWidth + 3 + displayWidth(value));
+    const contentWidth = Math.max(minimumContentWidth, logoWidth(), 'version' in info
+        ? displayWidth(`${mascot}  version ${info.version}`)
+        : minimumContentWidth, ...metadata);
+    return { contentWidth, frameWidth: contentWidth + 4 };
+}
+function createFrameLayout(contentWidth, color) {
+    const frame = (value) => paintWhen(color, colors.frame, value);
+    const row = (plain, styled = plain) => `${frame('│')} ${styled}${' '.repeat(contentWidth - displayWidth(plain))} ${frame('│')}`;
+    const centered = (plain, styled = plain) => {
+        const remaining = contentWidth - displayWidth(plain);
+        const left = Math.floor(remaining / 2);
+        return row(`${' '.repeat(left)}${plain}`, `${' '.repeat(left)}${styled}`);
+    };
+    const border = frame('─'.repeat(contentWidth + 2));
+    return {
+        topBorder: `${frame('╭')}${border}${frame('╮')}`,
+        bottomBorder: `${frame('╰')}${border}${frame('╯')}`,
+        row,
+        centered,
+    };
+}
+function renderLogo(color) {
+    const widths = logoGlyphs.map((glyph) => Math.max(...glyph.map(displayWidth)));
+    const plain = [];
+    const styled = [];
+    for (let row = 0; row < logoGlyphs[0].length; row += 1) {
+        const plainParts = [];
+        const styledParts = [];
+        for (let letter = 0; letter < logoGlyphs.length; letter += 1) {
+            const value = logoGlyphs[letter][row];
+            const padded = `${value}${' '.repeat(widths[letter] - displayWidth(value))}`;
+            const rgb = logoColors[letter];
+            plainParts.push(padded);
+            styledParts.push(paintWhen(color, rgb, padded));
+        }
+        plain.push(plainParts.join(' '));
+        styled.push(styledParts.join(' '));
+    }
+    return { plain, styled };
+}
+function logoWidth() {
+    const widths = logoGlyphs.map((glyph) => Math.max(...glyph.map(displayWidth)));
+    return widths.reduce((sum, width) => sum + width, logoGlyphs.length - 1);
+}
+function paintWhen(color, rgb, value) {
+    return color ? paint(rgb, value) : value;
+}
+function paint(rgb, value) {
+    return `\u001B[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${value}\u001B[0m`;
+}
+function formatDuration(durationMs) {
+    return `${Math.max(0, Math.round(durationMs))} ms`;
+}
+function displayWidth(value) {
+    let width = 0;
+    const ansiControlSequence = new RegExp(`${String.fromCodePoint(0x1b)}\\[[0-?]*[ -/]*[@-~]`, 'g');
+    for (const character of value.replace(ansiControlSequence, '')) {
+        const codePoint = character.codePointAt(0);
+        if (/\p{Mark}/u.test(character))
+            continue;
+        width += isFullWidth(codePoint) ? 2 : 1;
+    }
+    return width;
+}
+function isFullWidth(codePoint) {
+    return (codePoint >= 0x1100 &&
+        (codePoint <= 0x115f ||
+            codePoint === 0x2329 ||
+            codePoint === 0x232a ||
+            (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f) ||
+            (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+            (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+            (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+            (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+            (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+            (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+            (codePoint >= 0x1b000 && codePoint <= 0x1ffff) ||
+            (codePoint >= 0x20000 && codePoint <= 0x3fffd)));
+}

package/dist/runtime/capability.js

@@ -11,7 +11,7 @@ export function checkCapabilities(required, runtime) {
 export class MissingCapabilitiesError extends Error {
     check;
     constructor(check) {
-        super(`Runtimeに必要なCapabilityがありません: ${check.missing.join(', ')}`);
+        super(`Runtime is missing required capabilities: ${check.missing.join(', ')}`);
         this.check = check;
         this.name = 'MissingCapabilitiesError';
     }

package/dist/runtime/di.js

@@ -222,7 +222,7 @@ export class Container {
             const cycle = [...lineage.slice(cycleStart), token]
                 .map(tokenName)
                 .join(' -> ');
-            throw new DependencyResolutionError(`LUTRE_DI_CYCLE: 循環依存を検出しました: ${cycle}`);
+            throw new DependencyResolutionError(`LUTRE_DI_CYCLE: Circular dependency detected: ${cycle}`);
         }
         const provider = this.#providers.get(token);
         if (!provider) {
@@ -286,7 +286,7 @@ export class Container {
                     const selected = input[provider.select.key];
                     const implementation = provider.mapping[selected];
                     if (!implementation) {
-                        throw new DependencyResolutionError(`${provider.select.key}=${String(selected)}に対応するconditional Providerがありません`);
+                        throw new DependencyResolutionError(`No conditional Provider matches ${provider.select.key}=${String(selected)}`);
                     }
                     return this.#instantiate(implementation, lineage);
                 }

package/dist/runtime/engine.d.ts

@@ -0,0 +1,3 @@
+export type RuntimeEngine = 'node' | 'bun' | 'deno' | 'cloudflare-workers' | 'aws-lambda' | 'electron' | 'unknown';
+export declare function detectRuntimeEngine(): RuntimeEngine;
+export declare function assertRuntimeEngine(expected: Exclude<RuntimeEngine, 'unknown'>): void;

package/dist/runtime/engine.js

@@ -0,0 +1,38 @@
+const runtimeLabels = {
+    node: 'Node.js',
+    bun: 'Bun',
+    deno: 'Deno',
+    'cloudflare-workers': 'Cloudflare Workers',
+    'aws-lambda': 'AWS Lambda',
+    electron: 'Electron',
+    unknown: 'an unknown runtime',
+};
+export function detectRuntimeEngine() {
+    const globals = globalThis;
+    if (globals.Bun !== undefined ||
+        globals.process?.versions?.bun !== undefined) {
+        return 'bun';
+    }
+    if (globals.Deno !== undefined)
+        return 'deno';
+    if (globals.navigator?.userAgent === 'Cloudflare-Workers' ||
+        globals.WebSocketPair !== undefined) {
+        return 'cloudflare-workers';
+    }
+    if (globals.process?.versions?.electron !== undefined)
+        return 'electron';
+    if (globals.process?.env?.AWS_EXECUTION_ENV?.startsWith('AWS_Lambda_nodejs')) {
+        return 'aws-lambda';
+    }
+    if (globals.process?.release?.name === 'node' ||
+        globals.process?.versions?.node !== undefined) {
+        return 'node';
+    }
+    return 'unknown';
+}
+export function assertRuntimeEngine(expected) {
+    const actual = detectRuntimeEngine();
+    if (actual === expected)
+        return;
+    throw new Error(`LUTRE_RUNTIME_MISMATCH: Expected ${runtimeLabels[expected]}, detected ${runtimeLabels[actual]}.`);
+}

package/dist/runtime/index.d.ts

@@ -2,6 +2,8 @@ export * from './application.js';
 export * from './capability.js';
 export * from './di.js';
 export * from './error.js';
+export * from './engine.js';
 export * from './logger.js';
 export * from './pipeline.js';
 export * from './node-capabilities.js';
+export * from './server-url.js';

package/dist/runtime/index.js

@@ -2,6 +2,8 @@ export * from './application.js';
 export * from './capability.js';
 export * from './di.js';
 export * from './error.js';
+export * from './engine.js';
 export * from './logger.js';
 export * from './pipeline.js';
 export * from './node-capabilities.js';
+export * from './server-url.js';

package/dist/runtime/pipeline.js

@@ -9,7 +9,7 @@ export async function executePipeline(pipeline, hooks) {
     const context = hooks.context;
     const flow = await executeSegment(pipeline, 0, hooks, context, new Set());
     if (flow.kind === 'continue') {
-        throw new Error('Pipelineがresultを生成しませんでした');
+        throw new Error('Pipeline did not produce a result');
     }
     return flow.result;
 }
@@ -48,7 +48,7 @@ async function executeLayer(layer, runtime, continuation, context, availableKeys
     const next = (...arguments_) => {
         calls += 1;
         if (calls > 1) {
-            contractError = new LayerContractError(`LUTRE_LAYER_NEXT_REENTRY: Layer ${layer.name}のnext()は1回だけ実行できます`);
+            contractError = new LayerContractError(`LUTRE_LAYER_NEXT_REENTRY: Layer ${layer.name} can call next() only once`);
             return Promise.reject(contractError);
         }
         applyProvidedContext(layer, context, availableKeys, arguments_);
@@ -90,7 +90,7 @@ async function executeLayer(layer, runtime, continuation, context, availableKeys
         throw runtimeError;
     if (isShortCircuit(runtimeResult)) {
         if (calls > 0) {
-            throw new LayerContractError(`LUTRE_LAYER_SHORT_CIRCUIT_AFTER_NEXT: Layer ${layer.name}はnext()後にshortCircuitできません`);
+            throw new LayerContractError(`LUTRE_LAYER_SHORT_CIRCUIT_AFTER_NEXT: Layer ${layer.name} cannot shortCircuit after next()`);
         }
         return {
             kind: 'complete',
@@ -98,28 +98,28 @@ async function executeLayer(layer, runtime, continuation, context, availableKeys
         };
     }
     if (calls === 0) {
-        throw new LayerContractError(`LUTRE_LAYER_NEXT_SKIPPED: Layer ${layer.name}はnext()を1回実行する必要があります`);
+        throw new LayerContractError(`LUTRE_LAYER_NEXT_SKIPPED: Layer ${layer.name} must call next() exactly once`);
     }
     return continuationFlow;
 }
 function assertRequiredContext(layerName, requiredKeys, availableKeys) {
     for (const required of requiredKeys) {
         if (!availableKeys.has(required)) {
-            throw new LayerContractError(`${layerName}が必要とするContext Key ${contextKeyName(required)}は利用できません`);
+            throw new LayerContractError(`Context Key ${contextKeyName(required)} required by ${layerName} is unavailable`);
         }
     }
 }
 function applyProvidedContext(layer, context, availableKeys, arguments_) {
     if (arguments_.length > 1) {
-        throw new LayerContractError(`${layer.name}のnext()へ渡せるContext objectは1つだけです`);
+        throw new LayerContractError(`Layer ${layer.name} can pass only one Context object to next()`);
     }
     if (layer.provides.length === 0) {
         if (arguments_.length > 0) {
             const provided = arguments_[0];
             const property = firstProperty(provided);
             throw new LayerContractError(property === undefined
-                ? `${layer.name}はContextをprovideすると宣言していません`
-                : `${layer.name}が未宣言のContext property ${property}をprovideしました`);
+                ? `Layer ${layer.name} does not declare any provided Context`
+                : `Layer ${layer.name} provided undeclared Context property ${property}`);
         }
         return;
     }
@@ -127,26 +127,26 @@ function applyProvidedContext(layer, context, availableKeys, arguments_) {
     if (typeof provided !== 'object' ||
         provided === null ||
         Array.isArray(provided)) {
-        throw new LayerContractError(`${layer.name}はprovidesで宣言したContextをnext(object)で渡す必要があります`);
+        throw new LayerContractError(`Layer ${layer.name} must pass its declared Context to next(object)`);
     }
     const additions = provided;
     const declaredNames = new Set(layer.provides.map((key) => key.name));
     for (const property of Object.keys(additions)) {
         if (!declaredNames.has(property)) {
-            throw new LayerContractError(`${layer.name}が未宣言のContext property ${property}をprovideしました`);
+            throw new LayerContractError(`Layer ${layer.name} provided undeclared Context property ${property}`);
         }
     }
     const providedNames = new Set();
     for (const key of layer.provides) {
         if (providedNames.has(key.name)) {
-            throw new LayerContractError(`${layer.name}がContext property ${key.name}を重複して宣言しました`);
+            throw new LayerContractError(`Layer ${layer.name} declared duplicate Context property ${key.name}`);
         }
         providedNames.add(key.name);
         if (!Object.hasOwn(additions, key.name)) {
-            throw new LayerContractError(`${layer.name}が宣言したContext Key ${contextKeyName(key)}をprovideしませんでした`);
+            throw new LayerContractError(`Layer ${layer.name} did not provide declared Context Key ${contextKeyName(key)}`);
         }
         if (Object.hasOwn(context, key.name)) {
-            throw new LayerContractError(`${layer.name}は既存のContext property ${key.name}を上書きできません`);
+            throw new LayerContractError(`Layer ${layer.name} cannot overwrite existing Context property ${key.name}`);
         }
     }
     Object.assign(context, additions);

package/dist/runtime/server-url.d.ts

@@ -0,0 +1 @@
+export declare function serverUrl(hostname: string | undefined, port: number): string;

package/dist/runtime/server-url.js

@@ -0,0 +1,5 @@
+export function serverUrl(hostname, port) {
+    const host = hostname ?? 'localhost';
+    const formattedHost = host.includes(':') ? `[${host}]` : host;
+    return `http://${formattedHost}:${port}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loutrejs/loutre",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "files": [
@@ -24,6 +24,10 @@
       "types": "./dist/application/openapi.d.ts",
       "import": "./dist/application/openapi.js"
     },
+    "./presentation": {
+      "types": "./dist/presentation.d.ts",
+      "import": "./dist/presentation.js"
+    },
     "./graph": {
       "types": "./dist/graph/index.d.ts",
       "import": "./dist/graph/index.js"