bazis 0.99.6 → 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);
@@ -289,17 +294,39 @@ export function openSearchConnect<T extends OpenSearchConfigShape>(
   config: AppConfig<T>,
   options: OpenSearchConnectorOptions = {},
 ): InfraConnector<OpenSearchClient> {
+  const settings = new WeakMap<OpenSearchClient, string[]>();
   return {
     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,7 +1,7 @@
 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";
 
 /**
@@ -82,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 ?? 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 {
@@ -108,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,7 +9,7 @@ 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";
 
@@ -109,6 +109,7 @@ export function redisConnect<T extends RedisConfigShape>(
     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
@@ -123,8 +124,19 @@ export function redisConnect<T extends RedisConfigShape>(
       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");
@@ -172,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,9 +4,9 @@
 // (`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";
 

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;
@@ -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 } : {}),
     });
   }
 }