bazis 0.99.5 → 0.100.0

package/core/infra/connectors/llm.ts

@@ -2,7 +2,7 @@ import type { AppConfig, ConfigRegistry, Secret } from "../../kernel";
 import { AGENT_MODEL_PROVIDER, AGENT_RUNTIME_OPTIONS, AgentRuntime, type AgentModelProvider } from "../../agent";
 import { DI, DiError, HOSTED_SERVICE, SERVICE_PROVIDER, type ProviderDefinition } from "../../di";
 import { LOGGER } from "../../kernel/logging/Logger";
-import { reader, requireValue } from "../connectorConfig";
+import { reader, requireValue, settingNames } from "../connectorConfig";
 import { InfraError, type InfraConnector } from "../InfraConnector";
 import { identifyConnector } from "../connectorIdentity";
 
@@ -28,6 +28,12 @@ export interface LlmConnectionOptions {
 export interface LlmConnectorOptions {
   /** Request timeout. Defaults to 60s; `0` explicitly disables it. */
   readonly timeoutMs?: number;
+  /**
+   * Check the provider at start (the adapter's `connect`: `GET /models` for an
+   * OpenAI-compatible API, five seconds), so a wrong key or address stops the
+   * start instead of the first agent request. Default `true`.
+   */
+  readonly checkOnStart?: boolean;
 }
 
 export interface LlmProviderAdapter {
@@ -86,17 +92,32 @@ export function llmConnect<T extends LlmConfigShape>(
   adapter: LlmProviderAdapter,
   options: LlmConnectorOptions = {},
 ): InfraConnector<AgentModelProvider> {
+  const described = new WeakMap<AgentModelProvider, { connection: LlmConnectionOptions; settings: string[] }>();
   return identifyConnector({
     token: AGENT_MODEL_PROVIDER,
     config,
     providers: agentRuntimeProviders,
     exports: [AgentRuntime],
     create(configs) {
-      return adapter.create(resolveLlmConnectionOptions(config, options, configs));
+      const connection = resolveLlmConnectionOptions(config, options, configs);
+      const provider = adapter.create(connection);
+      described.set(provider, { connection, settings: settingNames(config, configs, ["baseUrl", "apiKey"]) });
+      return provider;
     },
     connect(provider, signal) {
+      if (options.checkOnStart === false) return;
       return adapter.connect?.(provider, signal);
     },
+    describe(provider, { connected }) {
+      const known = described.get(provider);
+      if (known === undefined) return {};
+      return {
+        kind: `${known.connection.provider} · ${known.connection.model}`,
+        address: known.connection.baseUrl,
+        details: connected && options.checkOnStart !== false && adapter.connect !== undefined ? ["checked"] : [],
+        settings: known.settings,
+      };
+    },
     dispose(provider) {
       return adapter.dispose?.(provider);
     },

package/core/infra/connectors/openaiCompatible.ts

@@ -22,10 +22,14 @@ import {
   type LlmProviderAdapter,
 } from "./llm";
 import { readOpenAiTextStream } from "./openaiTextStream";
+import { InfraError } from "../InfraConnector";
+import { redactSensitiveText } from "../../../library/redaction";
 
 const DEFAULT_CHAT_COMPLETIONS_PATH = "/chat/completions";
 const DEFAULT_HEALTH_PATH = "/models";
 const DEFAULT_MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+/** The start check is short: a provider that does not answer in five seconds is not ready. */
+const START_CHECK_TIMEOUT_MS = 5_000;
 
 export interface OpenAiCompatibleAdapterOptions {
   readonly fetch?: OpenAiCompatibleFetch;
@@ -390,13 +394,23 @@ export class OpenAiCompatibleModelProvider implements AgentModelProvider {
 
   public async ping(signal?: AbortSignal): Promise<boolean> {
     try {
-      await this.request(this.healthPath, "GET", undefined, signal);
+      await this.probe(signal);
       return true;
     } catch {
       return false;
     }
   }
 
+  /** Base URL of the provider, for diagnostics. */
+  public get address(): string {
+    return this.baseUrl;
+  }
+
+  /** The health request that rejects with the reason: wrong key, address, no answer. */
+  public async probe(signal?: AbortSignal): Promise<void> {
+    await this.request(this.healthPath, "GET", undefined, signal);
+  }
+
   /** End active requests and reject subsequent calls through this provider. */
   public dispose(): void {
     this.lifetime.abort(new OpenAiCompatibleProviderError("OpenAI-compatible provider is disposed."));
@@ -581,6 +595,17 @@ export function openAiCompatibleAdapter(options: OpenAiCompatibleAdapterOptions
     create(connection) {
       return new OpenAiCompatibleModelProvider(connection, options);
     },
+    async connect(provider, signal) {
+      if (!healthCheckEnabled || !(provider instanceof OpenAiCompatibleModelProvider)) return;
+      const deadline = AbortSignal.timeout(START_CHECK_TIMEOUT_MS);
+      try {
+        await provider.probe(signal === undefined ? deadline : AbortSignal.any([signal, deadline]));
+      } catch (error) {
+        if (signal?.aborted) throw error;
+        const reason = deadline.aborted ? `no answer within ${START_CHECK_TIMEOUT_MS} ms` : error instanceof Error ? error.message : String(error);
+        throw new InfraError(`Infra connector "llm": ${provider.address} is not available — ${redactSensitiveText(reason)}`);
+      }
+    },
     dispose(provider) {
       if (provider instanceof OpenAiCompatibleModelProvider) provider.dispose();
     },

package/core/infra/connectors/opensearch.ts

@@ -1,7 +1,7 @@
 import { createToken, type InjectionToken } from "../../di";
 import type { AppConfig, ConfigRegistry, Secret } from "../../kernel";
-import { reader, requireValue } from "../connectorConfig";
-import { InfraError, type InfraConnector } from "../InfraConnector";
+import { reader, requireValue, settingNames } from "../connectorConfig";
+import { errorMessage, InfraError, type InfraConnector } from "../InfraConnector";
 import { redactSensitive, redactSensitiveText } from "../../../library/redaction";
 
 /** Default cluster request timeout (ms): fail fast instead of hanging. */
@@ -124,6 +124,11 @@ export class OpenSearchClient {
   }
 
   /** Healthy only for explicitly accepted cluster states. */
+  /** Cluster address without credentials. */
+  public get url(): string {
+    return this.base;
+  }
+
   public async ping(signal?: AbortSignal): Promise<boolean> {
     try {
       const health = await this.clusterHealth(signal);
@@ -134,8 +139,12 @@ export class OpenSearchClient {
   }
 }
 
-/** OpenSearch client token for injection into application services. */
-export const OPENSEARCH: InjectionToken<OpenSearchClient> = createToken<OpenSearchClient>("OpenSearch");
+/**
+ * OpenSearch client of the `openSearchConnect()` connector, injected by type:
+ * `constructor(private readonly search: IOpenSearch)`.
+ */
+export interface IOpenSearch extends OpenSearchClient {}
+export const IOpenSearch = createToken<IOpenSearch>("IOpenSearch") as InjectionToken<OpenSearchClient>;
 
 /**
  * Config interface required by the OpenSearch connector. The search subsystem
@@ -278,25 +287,47 @@ async function readBoundedText(response: Response, maxBytes: number, label: stri
  * });
  * @Infra({ search: openSearchConnect(searchConfig) })
  * export class AppInfra {}
- * // injection by token: scoped(ISearchService, SearchService, [OPENSEARCH] as const)
+ * // by type: class SearchService { constructor(private readonly search: IOpenSearch) {} }
  * ```
  */
 export function openSearchConnect<T extends OpenSearchConfigShape>(
   config: AppConfig<T>,
   options: OpenSearchConnectorOptions = {},
 ): InfraConnector<OpenSearchClient> {
+  const settings = new WeakMap<OpenSearchClient, string[]>();
   return {
-    token: options.token ?? OPENSEARCH,
+    token: options.token ?? IOpenSearch,
     config,
     create(configs) {
-      return new OpenSearchClient(buildOpenSearchOptions(config, options, configs));
+      const client = new OpenSearchClient(buildOpenSearchOptions(config, options, configs));
+      settings.set(client, settingNames(config, configs, ["url", "username", "password"]));
+      return client;
     },
     async connect(client, signal) {
-      const alive = await client.ping(signal);
-      if (!alive) {
-        throw new InfraError(`Infra connector "opensearch": cluster is not reachable or unhealthy.`);
+      let status: string | undefined;
+      try {
+        status = (await client.clusterHealth(signal))?.status;
+      } catch (error) {
+        throw new InfraError(`Infra connector "opensearch": cannot reach ${client.url} — ${errorMessage(error)}`);
+      }
+      if (status !== "green" && status !== "yellow") {
+        throw new InfraError(`Infra connector "opensearch": cluster ${client.url} is unhealthy (status ${status ?? "unknown"}).`);
       }
     },
+    async describe(client, { connected, signal }) {
+      if (!connected) return { kind: "OpenSearch", address: client.url, settings: settings.get(client) ?? [] };
+      const [info, health] = await Promise.all([
+        client.request<{ version?: { number?: string; distribution?: string } }>("GET", "/", undefined, signal),
+        client.clusterHealth(signal),
+      ]);
+      const product = info.version?.distribution === "opensearch" || info.version?.distribution === undefined ? "OpenSearch" : info.version.distribution;
+      return {
+        kind: info.version?.number ? `${product} ${info.version.number}` : product,
+        address: client.url,
+        details: [health.status],
+        settings: settings.get(client) ?? [],
+      };
+    },
     dispose(client) {
       client.dispose();
     },

package/core/infra/connectors/postgres.ts

@@ -1,11 +1,16 @@
 import { SQL } from "bun";
 import { createToken, type InjectionToken } from "../../di";
 import type { AppConfig, ConfigRegistry, Secret } from "../../kernel";
-import { reader, requireValue } from "../connectorConfig";
+import { reader, requireValue, settingNames } from "../connectorConfig";
 import { errorMessage, InfraError, type InfraConnector } from "../InfraConnector";
 
-/** PostgreSQL client (native Bun `SQL`, no external dependencies). */
-export const POSTGRES: InjectionToken<SQL> = createToken<SQL>("Postgres");
+/**
+ * PostgreSQL client (native Bun `SQL`, no external dependencies) of the
+ * `postgres()` connector, injected by type:
+ * `constructor(private readonly sql: IPostgres)`.
+ */
+export interface IPostgres extends SQL {}
+export const IPostgres = createToken<IPostgres>("IPostgres") as InjectionToken<SQL>;
 
 /**
  * Config interface required by the PostgreSQL connector. The database subsystem
@@ -69,7 +74,7 @@ export function postgresConnectionOptions(config: AppConfig<PostgresConfigShape>
  * });
  * @Infra({ db: postgres(dbConfig) })
  * export class AppInfra {}
- * // injection by token: scoped(IReportsService, ReportsService, [POSTGRES] as const)
+ * // by type: class ReportsService { constructor(private readonly sql: IPostgres) {} }
  * ```
  */
 export function postgres<T extends PostgresConfigShape>(config: AppConfig<T>, options: PostgresConnectorOptions = {}): InfraConnector<SQL> {
@@ -77,11 +82,23 @@ export function postgres<T extends PostgresConfigShape>(config: AppConfig<T>, op
   if (!Number.isSafeInteger(shutdownTimeoutMs) || shutdownTimeoutMs < 0 || shutdownTimeoutMs > 2147483647) {
     throw new InfraError("postgres shutdownTimeoutMs must be an integer 0..2147483647");
   }
+  const described = new WeakMap<SQL, { options: { hostname?: string; port?: number; database?: string; username?: string; max?: number }; settings: string[] }>();
   return {
-    token: options.token ?? POSTGRES,
+    token: options.token ?? IPostgres,
     config,
     create(configs) {
-      return new SQL(postgresConnectionOptions(config, configs));
+      const connection = postgresConnectionOptions(config, configs);
+      const client = new SQL(connection);
+      described.set(client, { options: connection as { hostname?: string; port?: number; database?: string; username?: string; max?: number }, settings: settingNames(config, configs, ["host", "port", "database", "username", "password"]) });
+      return client;
+    },
+    async describe(client, { connected }) {
+      const known = described.get(client);
+      const version = connected ? await serverVersion((sql) => client.unsafe(sql)) : undefined;
+      return {
+        kind: version === undefined ? "PostgreSQL" : `PostgreSQL ${version}`,
+        ...(known === undefined ? {} : { address: postgresAddress(known.options), details: [`pool ${known.options.max ?? 10}`], settings: known.settings }),
+      };
     },
     async connect(client) {
       try {
@@ -103,3 +120,15 @@ export function postgres<T extends PostgresConfigShape>(config: AppConfig<T>, op
     },
   };
 }
+
+/** `postgres@127.0.0.1:5432/app`: user, host, port and database, never the password. */
+export function postgresAddress(options: { readonly hostname?: string; readonly port?: number | string; readonly database?: string; readonly username?: string }): string {
+  return `${options.username ?? ""}${options.username ? "@" : ""}${options.hostname ?? "localhost"}:${options.port ?? 5432}/${options.database ?? ""}`;
+}
+
+/** `17.6` from `SHOW server_version`; undefined when the server does not say. */
+export async function serverVersion(query: (sql: string) => Promise<unknown>): Promise<string | undefined> {
+  const rows = await query("SHOW server_version") as readonly Record<string, unknown>[];
+  const value = rows[0]?.server_version;
+  return typeof value === "string" ? value.split(" ")[0] : undefined;
+}

package/core/infra/connectors/redis.ts

@@ -9,11 +9,19 @@ import {
 import { createToken, DI, type InjectionToken, type ProviderDefinition } from "../../di";
 import type { AppConfig, Secret } from "../../kernel";
 import { RedisDistributedCacheBackend, type RedisDistributedCacheTuning } from "../cache/RedisDistributedCacheBackend";
-import { reader, requireValue } from "../connectorConfig";
+import { reader, requireValue, settingNames } from "../connectorConfig";
 import { errorMessage, InfraError, type InfraConnector } from "../InfraConnector";
+import { redactSensitiveText } from "../../../library/redaction";
 
-/** Redis/Valkey client (native Bun `RedisClient`, no external dependencies). */
-export const REDIS: InjectionToken<RedisClient> = createToken<RedisClient>("Redis");
+const DEFAULT_REDIS_CONNECT_TIMEOUT_MS = 5_000;
+
+/**
+ * Redis/Valkey client (native Bun `RedisClient`, no external dependencies) of
+ * the `redisConnect()` connector, injected by type:
+ * `constructor(private readonly redis: IRedis)`.
+ */
+export interface IRedis extends RedisClient {}
+export const IRedis = createToken<IRedis>("IRedis") as InjectionToken<RedisClient>;
 
 /**
  * Config interface required by the Redis connector. The subsystem config
@@ -30,6 +38,12 @@ export type RedisConnectorCacheMode =
 
 export interface RedisConnectorOptions {
   readonly token?: InjectionToken<RedisClient>;
+  /**
+   * How long the start waits for the first connection, ms (default 5000).
+   * The Bun client keeps retrying a refused connection; without a bound an
+   * unreachable Redis held the whole start until its timeout.
+   */
+  readonly connectTimeoutMs?: number;
   /**
    * Publishes a distributed cache backend on top of the client: `{ cache: "distributed" }`.
    * For fine tuning use `{ cache: { mode: "distributed", keyPrefix, ... } }`.
@@ -81,7 +95,7 @@ function distributedCacheProviders(tuning: RedisDistributedCacheTuning, token: I
  * export const redisConfig = defineConfig("redis", { default: { url: "redis://localhost:6379" } });
  * @Infra({ cache: redisConnect(redisConfig, { cache: "distributed" }) })
  * export class AppInfra {}
- * // injection by token: scoped(ISessionsService, SessionsService, [REDIS] as const)
+ * // by type: class SessionsService { constructor(private readonly redis: IRedis) {} }
  * ```
  */
 export function redisConnect<T extends RedisConfigShape>(
@@ -89,7 +103,13 @@ export function redisConnect<T extends RedisConfigShape>(
   options: RedisConnectorOptions = {},
 ): InfraConnector<RedisClient> {
   const cache = options.cache;
-  const token = options.token ?? REDIS;
+  const token = options.token ?? IRedis;
+  const connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_REDIS_CONNECT_TIMEOUT_MS;
+  if (!Number.isSafeInteger(connectTimeoutMs) || connectTimeoutMs <= 0) {
+    throw new InfraError("redisConnect connectTimeoutMs must be a positive integer.");
+  }
+  const urls = new WeakMap<RedisClient, string>();
+  const settings = new WeakMap<RedisClient, string[]>();
   const cacheProviders =
     cache === undefined
       ? undefined
@@ -101,13 +121,39 @@ export function redisConnect<T extends RedisConfigShape>(
     providers: cacheProviders,
     exports: cacheProviders ? [DISTRIBUTED_CACHE_BACKEND, DISTRIBUTED_OUTPUT_CACHE, DISTRIBUTED_SERVICE_CACHE, IDistributedCache] : undefined,
     create(configs) {
-      return new RedisClient(redisUrl(reader(config, configs).get("url")));
+      const url = redisUrl(reader(config, configs).get("url"));
+      const client = new RedisClient(url);
+      urls.set(client, url);
+      settings.set(client, settingNames(config, configs, ["url"]));
+      return client;
+    },
+    async describe(client, { connected }) {
+      const info = connected ? String(await client.send("INFO", ["server"])) : "";
+      const valkey = /valkey_version:([^\r\n]+)/.exec(info)?.[1];
+      const redis = /redis_version:([^\r\n]+)/.exec(info)?.[1];
+      return {
+        kind: valkey ? `Valkey ${valkey}` : redis ? `Redis ${redis}` : "Redis",
+        address: redisAddress(urls.get(client) ?? ""),
+        settings: settings.get(client) ?? [],
+      };
     },
     async connect(client) {
+      // The address without a password: it names the server in the error.
+      const target = redactSensitiveText(urls.get(client) ?? "redis");
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const deadline = new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => reject(new InfraError(`Infra connector "redis": failed to connect to ${target} within ${connectTimeoutMs} ms.`)), connectTimeoutMs);
+      });
       try {
-        await client.connect();
+        await Promise.race([client.connect(), deadline]);
       } catch (error) {
-        throw new InfraError(`Infra connector "redis": failed to connect — ${errorMessage(error)}`);
+        if (error instanceof InfraError) {
+          client.close();
+          throw error;
+        }
+        throw new InfraError(`Infra connector "redis": failed to connect to ${target} — ${errorMessage(error)}`);
+      } finally {
+        clearTimeout(timer);
       }
     },
     dispose(client) {
@@ -138,3 +184,13 @@ function withoutMode(cache: { readonly mode: "distributed" } & RedisDistributedC
   const { mode: _mode, ...tuning } = cache;
   return tuning;
 }
+
+/** `127.0.0.1:6379/0` without the scheme, user and password. */
+function redisAddress(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.hostname}:${parsed.port || "6379"}${parsed.pathname === "/" ? "" : parsed.pathname}`;
+  } catch {
+    return redactSensitiveText(url);
+  }
+}

package/core/infra/index.ts

@@ -4,16 +4,16 @@
 // (`SQL`, `RedisClient`) and `fetch`, with zero external dependencies.
 
 export { Infra, infraModule, type InfraManifest } from "./Infra";
-export { InfraError, errorMessage, type InfraConnector } from "./InfraConnector";
+export { InfraError, errorMessage, type ConnectionDescription, type InfraConnector } from "./InfraConnector";
 export { InfraLifecycle } from "./InfraLifecycle";
-export { reader, requireValue, type ConfigReader } from "./connectorConfig";
+export { reader, requireValue, settingNames, type ConfigReader } from "./connectorConfig";
 export { codexAppServerConnect, CODEX_APP_SERVER } from "./connectors/codex";
 export { CodexError, RU_CODEX_MESSAGES, type CodexErrorCode, CODEX_MODEL_ID, CODEX_REASONING_EFFORT, type CodexClient, type CodexConfigShape, type CodexLogin, type CodexLoginMethod, type CodexModel, type CodexStatus, type CodexRunInput, type CodexChatMessage, type CodexTool, type CodexToolCall, type CodexToolResult } from "./connectors/codex/contracts";
 
-export { postgres, POSTGRES, postgresConnectionOptions, type PostgresConfigShape, type PostgresSslMode, type PostgresConnectorOptions } from "./connectors/postgres";
+export { postgres, IPostgres, postgresConnectionOptions, type PostgresConfigShape, type PostgresSslMode, type PostgresConnectorOptions } from "./connectors/postgres";
 export {
   redisConnect,
-  REDIS,
+  IRedis,
   type RedisConfigShape,
   type RedisConnectorCacheMode,
   type RedisConnectorOptions,
@@ -26,7 +26,7 @@ export {
 } from "./cache";
 export {
   openSearchConnect,
-  OPENSEARCH,
+  IOpenSearch,
   OpenSearchClient,
   type OpenSearchClientOptions,
   type OpenSearchConfigShape,

package/core/kernel/Bazis.ts

@@ -5,6 +5,7 @@ import { KernelError, ShutdownTimeoutError } from "./errors";
 import type { KernelOptions } from "./types";
 import { redactSensitiveText } from "../../library/redaction";
 import { formatStartupFailure } from "./startupFailure";
+import { StartupScreen, startupScreenEnabled } from "./report/StartupScreen";
 
 /**
  * Entry-point facade.
@@ -31,12 +32,26 @@ export class Bazis {
     if (options) {
       builder.useOptions(options);
     }
+    // On a terminal the start is a screen: what started, or what failed and why.
+    const screen = startupScreenEnabled() ? new StartupScreen() : undefined;
+    let stopWaiting: (() => void) | undefined;
+    if (screen !== undefined && options?.startupReport !== false) {
+      builder.useStartupScreen((started) => {
+        stopWaiting?.();
+        screen.started(started);
+      });
+    }
     configure?.(builder);
 
     let kernel: Kernel;
     try {
       kernel = await builder.build();
     } catch (error) {
+      if (screen !== undefined && !(error instanceof ShutdownTimeoutError)) {
+        screen.failed(error, undefined, builder.report);
+        process.exitCode = 1;
+        return 1;
+      }
       if (error instanceof DiError || error instanceof KernelError) {
         console.error(`[bazis] configuration error: ${redactSensitiveText(error.message)}`);
         process.exitCode = 1;
@@ -46,10 +61,13 @@ export class Bazis {
     }
 
     try {
+      if (kernel.report.screen) stopWaiting = screen?.waiting(kernel);
       const exitCode = await kernel.run();
+      stopWaiting?.();
       process.exitCode = exitCode;
       return exitCode;
     } catch (error) {
+      stopWaiting?.();
       if (error instanceof ShutdownTimeoutError) {
         // Graceful shutdown is stuck: hanging handles would keep the process
         // alive forever, so this is the one place a hard exit is correct.
@@ -58,7 +76,9 @@ export class Bazis {
       }
       // Configuration problems surfacing at start (e.g. options fail-fast)
       // deserve the same friendly output as build-time ones.
-      if (error instanceof DiError || error instanceof KernelError) {
+      if (screen !== undefined) {
+        screen.failed(error, kernel);
+      } else if (error instanceof DiError || error instanceof KernelError) {
         console.error(`[bazis] configuration error: ${redactSensitiveText(error.message)}`);
       } else {
         console.error(`[bazis] application failed: ${formatStartupFailure(error)}`);

package/core/kernel/Kernel.ts

@@ -15,6 +15,9 @@ import { validateTimeout } from "./internal/validateTimeout";
 import { awaitShutdown } from "./internal/awaitShutdown";
 import { awaitAbortable } from "./internal/awaitAbortable";
 import { reportDiagnosticFailure } from "./internal/reportDiagnosticFailure";
+import { StartupReport } from "./report/StartupReport";
+import type { BazisModuleRef } from "../di";
+import type { StartupBatchTiming } from "./LifecycleCoordinator";
 
 export interface KernelTimings {
   readonly configMs: number;
@@ -30,6 +33,12 @@ export interface KernelRuntimeOptions {
   readonly startupReport: boolean;
   /** Start the infrastructure and the schema only, then stop (BAZIS_SCHEMA_ONLY). */
   readonly schemaOnly?: boolean;
+  /** Facts for the startup screen; a fresh one when absent. */
+  readonly report?: StartupReport;
+  /** The application root module, for the module tree of the startup screen. */
+  readonly root?: BazisModuleRef;
+  /** Renders the startup screen in place of the `bazis started` log line. */
+  readonly onStarted?: (kernel: Kernel) => void;
 }
 
 interface StopRequest {
@@ -56,6 +65,7 @@ export class Kernel {
   private shutdownPromise?: Promise<void>;
   private startupCleanupFailure?: unknown;
   private startupAbort?: AbortController;
+  private ownReport?: StartupReport;
 
   public constructor(
     public readonly container: DiContainer,
@@ -76,6 +86,42 @@ export class Kernel {
     return this.state === "started";
   }
 
+  /** What subsystems recorded while starting: connections, schema, routes. */
+  public get report(): StartupReport {
+    this.ownReport ??= this.options.report ?? new StartupReport();
+    return this.ownReport;
+  }
+
+  /** The application root module, when the builder knows it. */
+  public get rootModule(): BazisModuleRef | undefined {
+    return this.options.root;
+  }
+
+  /** Configuration and container build time, and the moment the build began. */
+  public get buildTimings(): KernelTimings {
+    return this.timings;
+  }
+
+  /** Wall time of every started group of hosted services. */
+  public get startTimings(): readonly StartupBatchTiming[] {
+    return this.coordinator.startTimings;
+  }
+
+  /** Hosted services whose start failed. */
+  public get failedServices(): readonly string[] {
+    return this.coordinator.failedServiceNames;
+  }
+
+  /** Hosted services whose start is running now. */
+  public get startingServices(): readonly string[] {
+    return this.coordinator.startingServiceNames;
+  }
+
+  /** From the start of the build to a started application, ms; 0 before. */
+  public get startupDurationMs(): number {
+    return this.startupMs;
+  }
+
   public start(): Promise<void> {
     if (this.startPromise !== undefined) {
       return this.startPromise;
@@ -95,7 +141,7 @@ export class Kernel {
     let startupDisposal: Promise<void> | undefined;
     if (this.options.startupTimeoutMs > 0) {
       startupTimer = setTimeout(
-        () => abortController.abort(new StartupTimeoutError(this.options.startupTimeoutMs)),
+        () => abortController.abort(new StartupTimeoutError(this.options.startupTimeoutMs, this.coordinator.startingServiceName)),
         this.options.startupTimeoutMs,
       );
     }
@@ -396,6 +442,14 @@ export class Kernel {
   }
 
   private printStartupReport(): void {
+    if (this.options.onStarted !== undefined) {
+      try {
+        this.options.onStarted(this);
+        return;
+      } catch {
+        // A broken screen falls back to the log line below.
+      }
+    }
     const logger = this.container.tryResolve(LOGGER);
     const fields = {
       environment: this.environment.name,

package/core/kernel/KernelBuilder.ts

@@ -13,6 +13,7 @@ import { ConsoleLogger } from "./logging/ConsoleLogger";
 import { LOGGER, type Logger } from "./logging/Logger";
 import type { ConfigSource, EnvironmentName, KernelOptions, UnhandledErrorPolicy } from "./types";
 import { validateTimeout } from "./internal/validateTimeout";
+import { StartupReport } from "./report/StartupReport";
 
 /** Root module or a profile factory (Spring profiles, but explicit). */
 export type RootModuleInput = BazisModuleRef | ((environment: Environment) => BazisModuleRef);
@@ -49,6 +50,14 @@ export class KernelBuilder {
   private startupReport?: boolean;
   private schemaOnly?: boolean;
   private logger?: Logger;
+  private startupScreen?: (kernel: Kernel) => void;
+  private applicationRoot?: BazisModuleRef;
+  private builtReport?: StartupReport;
+
+  /** Facts of the last {@link build}, also when it failed after the configuration was read. */
+  public get report(): StartupReport | undefined {
+    return this.builtReport;
+  }
 
   public constructor(private readonly rootModule: RootModuleInput) {}
 
@@ -104,6 +113,25 @@ export class KernelBuilder {
     return this;
   }
 
+  /**
+   * Renders the startup screen instead of the `bazis started` log line, and
+   * makes subsystems record their facts for it rather than print them.
+   * `Bazis.run` sets it on an interactive terminal.
+   */
+  public useStartupScreen(render: (kernel: Kernel) => void): this {
+    this.startupScreen = render;
+    return this;
+  }
+
+  /**
+   * @internal The application's own root module, inside the hosts `runApp`
+   * wraps it in: the module tree of the startup screen starts from it.
+   */
+  public useApplicationRoot(root: BazisModuleRef): this {
+    this.applicationRoot = root;
+    return this;
+  }
+
   /**
    * Replacements for registered providers, for tests (see `createContainer`
    * `overrides`): registered after the whole graph and visible to every module.
@@ -138,6 +166,12 @@ export class KernelBuilder {
     const userRoot = resolveUserRoot(this.rootModule, environment);
     const configs = collectModuleConfigs([userRoot]);
     const configRegistry = new ConfigRegistry(configs, environment.name, configuration);
+    const startupReport = this.startupReport ?? !environment.isProduction;
+    // The screen replaces the report line, so it follows the same switch.
+    const screen = this.startupScreen !== undefined && startupReport;
+    const report = new StartupReport(screen);
+    report.configuration(configRegistry.inspect());
+    this.builtReport = report;
 
     // Kernel infrastructure is a global module: any user module can depend on
     // Environment / Configuration / ApplicationLifetime / EventBus without
@@ -146,6 +180,7 @@ export class KernelBuilder {
     @Module({
       providers: [
         DI.singleton(DI.valueProvider(ConfigRegistry, configRegistry)),
+        DI.singleton(DI.valueProvider(StartupReport, report)),
         ...configRegistry.providers,
         DI.singleton(DI.valueProvider(Environment, environment)),
         DI.singleton(DI.valueProvider(Configuration, configuration)),
@@ -179,8 +214,11 @@ export class KernelBuilder {
       shutdownTimeoutMs: this.shutdownTimeoutMs,
       signals: this.signals,
       unhandledErrorPolicy: this.unhandledErrorPolicy,
-      startupReport: this.startupReport ?? !environment.isProduction,
+      startupReport,
       schemaOnly: this.schemaOnly ?? schemaOnlyFromProcess(),
+      report,
+      root: this.applicationRoot ?? userRoot,
+      ...(screen ? { onStarted: this.startupScreen } : {}),
     });
   }
 }