bazis 0.99.6 → 0.100.0

package/cli/main.ts

@@ -1,9 +1,12 @@
 #!/usr/bin/env bun
+import path from "node:path";
 import { useTypeScriptCompilerApi } from "../core/scripts/typescriptApi";
-import { parseCliArgs } from "./parseCli";
-import { runCodegen } from "./codegen";
+import { detectLanguage, formatDuration, padEnd, PALETTE, type Language, type ScreenOutput } from "../library/terminal";
+import { parseCliArgs, type ParsedGenerateArgs } from "./parseCli";
+import { runCodegen, type CodegenOptions } from "./codegen";
 import { generateProject } from "./generateProject";
 import { runBuild, runDev, runTest } from "./build";
+import { commandFailed, commandHeader, createScreens, lineOutput, type CliOutput } from "./ui";
 
 export const USAGE = `Usage:
   bazis new <Name> [options]                  Create a new application project
@@ -19,6 +22,7 @@ export const USAGE = `Usage:
   bazis build --bin --dotenv                  The executable also reads .env files from its working directory
   bazis --help
   g can also be written as generate.
+  --lang <en|ru> sets the output language (also BAZIS_LANG, "language" in bazis.config.json).
 
 Generation options:
   --path <directory>    Exact project directory (new only; default: ./<name>)
@@ -62,75 +66,154 @@ Read AGENTS.md and docs/architecture/MODULE_ARCHITECTURE.md before implementing.
 export interface CliRuntime {
   readonly log: (message: string) => void;
   readonly error: (message: string) => void;
-  readonly codegen: (cwd: string, target?: string) => Promise<number>;
+  readonly codegen: (cwd: string, target?: string, options?: CodegenOptions) => Promise<number>;
+  /** Terminal outputs for colour and spinners; without them `log`/`error` get plain lines. */
+  readonly stdout?: ScreenOutput;
+  readonly stderr?: ScreenOutput;
+  /** Output language when `--lang` is not given; detected from the environment otherwise. */
+  readonly language?: Language;
 }
 
 const defaultRuntime: CliRuntime = {
   log: (message) => console.log(message),
   error: (message) => console.error(message),
   codegen: runCodegen,
+  stdout: process.stdout,
+  stderr: process.stderr,
 };
 
+/** `--lang ru` / `--lang=ru` anywhere in the arguments; the rest goes to the parser. */
+export function extractLanguage(argv: readonly string[]): { readonly argv: readonly string[]; readonly lang?: string } {
+  const rest: string[] = [];
+  let lang: string | undefined;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    // After `test`, arguments belong to bun test.
+    if (rest[0] === "test") { rest.push(arg); continue; }
+    if (arg === "--lang") { lang = argv[++index]; continue; }
+    if (arg.startsWith("--lang=")) { lang = arg.slice("--lang=".length); continue; }
+    rest.push(arg);
+  }
+  return { argv: rest, ...(lang === undefined ? {} : { lang }) };
+}
+
 export async function runCli(argv: readonly string[], runtime: CliRuntime = defaultRuntime): Promise<number> {
-  const parsed = parseCliArgs(argv);
+  const extracted = extractLanguage(argv);
+  const language = detectLanguage({ flag: extracted.lang ?? runtime.language });
+  const ui = createScreens(runtime.stdout ?? lineOutput(runtime.log), runtime.stderr ?? lineOutput(runtime.error), language);
+  const codegen = (cwd: string, target?: string, options?: CodegenOptions) => runtime.codegen(cwd, target, { ui, ...options });
+  const parsed = parseCliArgs(extracted.argv);
   if (parsed.kind === "help") {
     runtime.log(USAGE.trim());
     return parsed.help ? 0 : 1;
   }
   if (parsed.kind === "error") {
-    runtime.error(`[bazis] ${parsed.message}`);
-    runtime.error("Use bazis --help to list commands and options.");
-    return 1;
+    return commandFailed(ui.err, ui.err.t.failure.command, [{ tag: "CLI", where: "bazis", cause: parsed.message, fixes: [ui.err.t.errors.unknown] }], 1);
   }
+  const cwd = process.cwd();
   try {
-    if (parsed.kind === "codegen") return await runtime.codegen(process.cwd(), parsed.target);
-    if (parsed.kind === "dev") return await runDev(process.cwd(), runtime.codegen, runtime.log, { watch: parsed.watch });
-    if (parsed.kind === "test") return await runTest(process.cwd(), parsed.args, runtime.codegen);
-    if (parsed.kind === "build") return await runBuild(process.cwd(), { bin: parsed.bin, outfile: parsed.outfile, dotenv: parsed.dotenv }, runtime.codegen, runtime.log);
-    if (parsed.kind === "new") {
-      const result = await generateProject({ name: parsed.name, outputPath: parsed.outputPath, frameworkPath: parsed.frameworkPath, linkFramework: parsed.linkFramework, vendor: parsed.vendor, dryRun: parsed.dryRun });
-      runtime.log(`[bazis] ${result.dryRun ? "planned" : "created"} project: ${result.projectDir}`);
-      for (const file of result.files) runtime.log(`  + ${file}`);
-      runtime.log(result.frameworkMode === "registry"
-        ? `[bazis] Framework dependency: "bazis": "${result.dependency}" from npm.`
-        : result.frameworkMode === "snapshot"
-        ? `[bazis] vendor/bazis: ${result.frameworkFileCount} package files${result.dryRun ? " planned" : " copied"}. Keep this directory in version control.`
-        : "[bazis] Framework is linked to an external checkout (--link-framework).");
-      if (!result.dryRun) runtime.log(`[bazis] Next: cd ${result.projectDir} && bun install && bunx bazis dev`);
-      return 0;
-    }
-    const args = parsed.args;
-    const options = {
-      name: args.name, modulesRoot: args.modulesRoot, appModulePath: args.appModule,
-      register: args.register, force: args.force, dryRun: args.dryRun,
-    };
+    if (parsed.kind === "codegen") return await runCodegenCommand(cwd, parsed.target, codegen, ui);
+    if (parsed.kind === "dev") return await runDev(cwd, codegen, ui, { watch: parsed.watch });
+    if (parsed.kind === "test") return await runTest(cwd, parsed.args, codegen, ui);
+    if (parsed.kind === "build") return await runBuild(cwd, { bin: parsed.bin, outfile: parsed.outfile, dotenv: parsed.dotenv }, codegen, ui);
+    if (parsed.kind === "new") return await runNew(parsed, ui);
     // Module registration parses the host module with the TypeScript API: load it
     // only after switching TypeScript 7 to @typescript/typescript6.
-    useTypeScriptCompilerApi(process.cwd());
-    const { generateModule, generateModulePack } = await import("./generateModule");
-    const result = args.generator === "pack"
-      ? await generateModulePack({ ...options, parts: args.parts })
-      : await generateModule({ ...options, profile: args.profile, pack: args.pack });
-    runtime.log(`[bazis] ${result.dryRun ? "planned" : "generated"} ${args.generator}: ${result.moduleDir}`);
-    for (const change of result.changes) runtime.log(`  ${change.action === "create" ? "+" : "~"} ${change.path}`);
-    for (const warning of result.warnings) runtime.log(`[bazis] ${warning}`);
-    if (result.dryRun) {
-      runtime.log("[bazis] dry-run: no files written; codegen not run.");
-      return 0;
-    }
-    if (result.registered) runtime.log("[bazis] connected in host module.");
-    if (!args.codegen || !result.registered) {
-      runtime.log(`[bazis] codegen skipped: ${!args.codegen ? "--no-codegen" : "module is not connected by this command"}.`);
-      return 0;
-    }
-    runtime.log("[bazis] running codegen...");
-    const exitCode = await runtime.codegen(process.cwd(), args.target);
-    if (exitCode !== 0) runtime.error("[bazis] codegen failed; scaffold files were kept. Fix the error and run bazis codegen.");
-    return exitCode;
+    useTypeScriptCompilerApi(cwd);
+    return await runGenerate(cwd, parsed.args, codegen, ui);
   } catch (error) {
-    runtime.error(`[bazis] ${error instanceof Error ? error.message : String(error)}`);
-    return 1;
+    return commandFailed(ui.err, ui.err.t.failure.command, [{ tag: "CLI", where: parsed.kind === "generate" ? `g ${parsed.args.generator}` : parsed.kind, cause: error instanceof Error ? error.message : String(error) }], 1);
+  }
+}
+
+async function runCodegenCommand(cwd: string, target: string | undefined, codegen: CliRuntime["codegen"], ui: CliOutput): Promise<number> {
+  const s = ui.out;
+  const t = s.t;
+  const startedAt = performance.now();
+  commandHeader(s, "codegen", cwd, [s.kv(t.meta.target, s.text(target ?? "default"))]);
+  s.section(t.section.build);
+  const exitCode = await codegen(cwd, target, { ui });
+  if (exitCode !== 0) return exitCode;
+  s.line();
+  s.banner("success", t.codegen.done(formatDuration(performance.now() - startedAt)));
+  return 0;
+}
+
+async function runNew(parsed: Extract<ReturnType<typeof parseCliArgs>, { kind: "new" }>, ui: CliOutput): Promise<number> {
+  const s = ui.out;
+  const t = s.t;
+  const result = await generateProject({ name: parsed.name, outputPath: parsed.outputPath, frameworkPath: parsed.frameworkPath, linkFramework: parsed.linkFramework, vendor: parsed.vendor, dryRun: parsed.dryRun });
+  const relative = path.relative(process.cwd(), result.projectDir) || ".";
+  commandHeader(s, "new", process.cwd(), [s.kv(t.meta.path, s.text(relative)), ...(result.dryRun ? [s.fg(PALETTE.yellow, t.common.dryRun)] : [])], { name: parsed.name, version: "0.1.0" });
+  s.section(t.section.project, s.muted(relative));
+  s.step("ok", t.step.files, s.num(result.files.length, t.noun("file", result.files.length)));
+  s.tree(result.files.map((file) => ({ text: `${s.strong("+", PALETTE.lime)} ${s.text(path.relative(result.projectDir, path.resolve(result.projectDir, file)))}` })), s.style.color ? 9 : 4);
+  s.line();
+  s.line(`  ${s.strong("◆", PALETTE.service)}  ${s.text(result.frameworkMode === "registry"
+    ? t.project.dependency(result.dependency)
+    : result.frameworkMode === "snapshot" ? t.project.vendor(result.frameworkFileCount) : t.project.linked)}`);
+  s.line();
+  s.banner("success", result.dryRun ? t.project.planned(parsed.name) : t.project.created(parsed.name));
+  if (!result.dryRun) {
+    const step = (number: number, command: string, note: string) => `${s.strong(String(number), PALETTE.lime)}  ${padEnd(command, 32)}${s.muted(note)}`;
+    s.panel([
+      step(1, s.code(`cd ${relative}`), ""),
+      step(2, s.code("bun install"), t.project.install),
+      step(3, s.code("bunx bazis dev"), t.project.dev),
+      step(4, s.link("http://127.0.0.1:3000/health"), t.project.open),
+    ]);
+    s.line();
+  }
+  return 0;
+}
+
+async function runGenerate(cwd: string, args: ParsedGenerateArgs, codegen: CliRuntime["codegen"], ui: CliOutput): Promise<number> {
+  const s = ui.out;
+  const t = s.t;
+  const { generateModule, generateModulePack } = await import("./generateModule");
+  const options = {
+    name: args.name, modulesRoot: args.modulesRoot, appModulePath: args.appModule,
+    register: args.register, force: args.force, dryRun: args.dryRun,
+  };
+  const kind = t.module.kind[args.generator];
+  commandHeader(s, "gen", cwd, [
+    s.kv(kind, s.strong(args.name)),
+    ...(args.generator === "module" ? [s.kv("profile", s.text(args.profile))] : [s.kv("parts", s.text(args.parts.join(", ")))]),
+    ...(args.dryRun ? [s.fg(PALETTE.yellow, t.common.dryRun)] : []),
+  ]);
+  const result = args.generator === "pack"
+    ? await generateModulePack({ ...options, parts: args.parts })
+    : await generateModule({ ...options, profile: args.profile, pack: args.pack });
+  s.section(t.section.files, s.muted(path.relative(cwd, result.moduleDir) || result.moduleDir));
+  s.step("ok", t.step.files, s.num(result.changes.length, t.noun("change", result.changes.length)));
+  s.tree(result.changes.map((change) => ({ text: `${change.action === "create" ? s.strong("+", PALETTE.lime) : s.strong("~", PALETTE.yellow)} ${s.text(change.path)}` })), s.style.color ? 9 : 4);
+  for (const warning of result.warnings) s.warning(warning);
+  s.line();
+  const host = result.changes.find((change) => change.action === "update")?.path;
+  if (result.registered) s.line(`  ${s.strong("↗", PALETTE.export)}  ${s.text(t.module.registered(host ?? "App.module.ts"))}`);
+  else s.warning(t.module.notRegistered);
+  // What the module needs from the application to run.
+  if (args.generator === "module" && args.profile !== "empty") s.line(`  ${s.strong("◆", PALETTE.service)}  ${s.muted(t.module.needsDb)}`);
+  if (args.generator === "module" && args.profile === "full") s.line(`  ${s.strong("◆", PALETTE.service)}  ${s.muted(t.module.needsCache)}`);
+  s.line();
+  if (result.dryRun) {
+    s.banner("success", t.module.planned(kind, args.name));
+    return 0;
+  }
+  if (result.registered && args.codegen) {
+    s.section(t.section.build);
+    const exitCode = await codegen(cwd, args.target);
+    if (exitCode !== 0) {
+      ui.err.footer(t.module.keptOnFailure);
+      return exitCode;
+    }
+    s.line();
+  } else if (result.registered) {
+    s.line(`  ${s.muted(t.module.codegenSkipped)}`);
+    s.line();
   }
+  s.banner("success", t.module.created(kind, args.name));
+  return 0;
 }
 
 if (import.meta.main) process.exitCode = await runCli(Bun.argv.slice(2));

package/cli/naming.ts

@@ -43,6 +43,9 @@ export function parseModuleName(raw: string): ModuleNaming {
   if (input.length === 0) {
     throw new Error("Module name is required.");
   }
+  if (!/^[a-zA-Z]/.test(input)) {
+    throw new Error(`Invalid module name "${input}": it must start with a letter (then letters, digits and hyphens).`);
+  }
   if (!/^[a-zA-Z][a-zA-Z0-9]*(?:-[a-zA-Z0-9]+)*$/.test(input)) {
     throw new Error(`Invalid module name "${input}". Use letters, digits, and hyphens only.`);
   }

package/cli/ui.ts

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MODE, PALETTE, Screen, formatDuration, type Language, type Problem, type ScreenOutput } from "../library/terminal";
+
+/** Where the CLI writes: the terminal, or a test buffer of lines. */
+export interface CliOutput {
+  readonly out: Screen;
+  readonly err: Screen;
+}
+
+/** A line sink (`console.log`, a test array) as a screen output without colour. */
+export function lineOutput(sink: (line: string) => void): ScreenOutput {
+  let pending = "";
+  return {
+    isTTY: false,
+    write(text: string) {
+      const lines = (pending + text).split("\n");
+      pending = lines.pop() ?? "";
+      for (const line of lines) sink(line.trimEnd());
+    },
+  };
+}
+
+export function createScreens(stdout: ScreenOutput, stderr: ScreenOutput, language?: Language): CliOutput {
+  const out = new Screen(stdout, { language });
+  return { out, err: new Screen(stderr, { language: out.language, style: stderr === stdout ? out.style : undefined }) };
+}
+
+/** The project of the working directory: name and version from `package.json`. */
+export function projectInfo(cwd: string): { name?: string; version?: string } {
+  try {
+    const json = JSON.parse(readFileSync(path.join(cwd, "package.json"), "utf8")) as { name?: unknown; version?: unknown };
+    return { ...(typeof json.name === "string" ? { name: json.name } : {}), ...(typeof json.version === "string" ? { version: json.version } : {}) };
+  } catch {
+    return {};
+  }
+}
+
+/** Version of the bazis package this CLI belongs to. */
+export function bazisVersion(): string {
+  try {
+    const file = fileURLToPath(new URL("../package.json", import.meta.url));
+    if (!existsSync(file)) return "?";
+    const version = (JSON.parse(readFileSync(file, "utf8")) as { version?: unknown }).version;
+    return typeof version === "string" ? version : "?";
+  } catch {
+    return "?";
+  }
+}
+
+/** The logo with the command badge: project, versions, and the command's own facts. */
+export function commandHeader(screen: Screen, mode: keyof typeof MODE, cwd: string, facts: readonly string[], project = projectInfo(cwd)): void {
+  screen.header(mode, MODE[mode], [
+    project.name ? `${screen.strong(project.name)}${project.version ? ` ${screen.muted(project.version)}` : ""}` : screen.muted(path.basename(cwd)),
+    [screen.kv("bazis", screen.text(bazisVersion())), screen.kv("bun", screen.text(Bun.version))].join(screen.dot),
+    facts.join(screen.dot),
+  ]);
+}
+
+/** A failed command: the banner, its problems and the exit code. */
+export function commandFailed(screen: Screen, title: string, problems: readonly Problem[], exitCode: number, footer?: string): number {
+  screen.banner("failed", title);
+  screen.problems(problems);
+  screen.footer(footer ?? screen.t.failure.exit(exitCode));
+  return exitCode;
+}
+
+/** Lines `from..to` of a file around `line` (1-based) for a code frame. */
+export function readFrameLines(file: string, line: number, around = 2): (readonly [number, string])[] {
+  try {
+    const lines = readFileSync(file, "utf8").split("\n");
+    const from = Math.max(1, line - around), to = Math.min(lines.length, line + around);
+    const result: (readonly [number, string])[] = [];
+    for (let number = from; number <= to; number += 1) result.push([number, lines[number - 1] ?? ""]);
+    return result;
+  } catch {
+    return [];
+  }
+}
+
+export function took(screen: Screen, ms: number): string {
+  return screen.muted(formatDuration(ms));
+}
+
+export { PALETTE };

package/core/agent/index.ts

@@ -1,4 +1,12 @@
 import type { Class } from "../di";
+import { registerModuleDescriber } from "../kernel/report/moduleTree";
+import { toolMetadataOf } from "./metadata";
+
+// The module tree of the startup screen: `orders.summary · read`.
+registerModuleDescriber((metadata) => (metadata.tools ?? []).map((tool) => {
+  const meta = toolMetadataOf(tool);
+  return { kind: "tool" as const, text: meta === undefined ? tool.name : `${meta.name} · ${meta.sideEffect}` };
+}));
 
 export { Tool } from "./decorators/Tool";
 export { describeTool } from "./Tool.contract";

package/core/app/runApp.ts

@@ -259,7 +259,10 @@ function normalizeAbsolutePath(path: string): string {
  */
 export async function runApp(root: BazisModuleRef, options: RunAppOptions = {}): Promise<number> {
   await loadBazisGeneratedRuntime();
-  return Bazis.run(composeApp(root, options), options.kernel, options.configure);
+  return Bazis.run(composeApp(root, options), options.kernel, (builder) => {
+    builder.useApplicationRoot(root);
+    options.configure?.(builder);
+  });
 }
 
 /**

package/core/di/extensions/hosted-service.ts

@@ -40,6 +40,12 @@ export interface HostedService {
   useDiagnostics?(diagnostics: HostedServiceDiagnostics): void;
   /** Name in startup diagnostics, such as `infra:db`; the class name by default. */
   readonly diagnosticName?: string;
+  /**
+   * Starts together with neighbouring `concurrentStart` services of the same
+   * phase instead of one by one, and their failures are reported together.
+   * For independent work such as connections of the infrastructure manifest.
+   */
+  readonly concurrentStart?: boolean;
   start(signal?: AbortSignal): void | Promise<void>;
   stop(): void | Promise<void>;
   /**

package/core/http/HttpServer.ts

@@ -1,6 +1,6 @@
 import type { Class, HostedService, ServiceProvider, ServiceResolver, ServiceScope } from "../di";
 import { loadBazisGeneratedRuntime } from "../generatedRuntime";
-import { Environment, HealthService, LOGGER, type HealthReport } from "../kernel";
+import { Environment, HealthService, LOGGER, StartupReport, type HealthReport } from "../kernel";
 import { redactSensitive } from "../../library/redaction";
 import { HttpContext } from "./HttpContext/HttpContext";
 import { holdResponseScope } from "./HttpContext/responseLifetime";
@@ -182,6 +182,7 @@ export class HttpServer implements HostedService {
       this.collectRouteComposer(),
     );
     this.router = builder.build(this.options.controllers);
+    const routes = builder.routes;
     this.readVersion = createVersionReader(this.options.versioning);
     this.docs = prepareOpenApiDocs({
       option: this.options.docs,
@@ -230,7 +231,37 @@ export class HttpServer implements HostedService {
           error: (error) => this.transportError(error),
         }),
       );
-    }
+    }    this.reportStarted(routes);
+  }
+
+  /** Routes and the address for the startup screen. */
+  private reportStarted(routes: readonly import("./Routing/RouterBuilder").RegisteredRoute[]): void {
+    const report = this.resolver.tryResolve(StartupReport);
+    const server = this.server;
+    if (report === undefined || server === undefined) return;
+    report.routes(routes.map((route) => ({
+      method: route.method,
+      path: route.path.startsWith("/") ? route.path : `/${route.path}`,
+      handler: route.handler,
+      open: route.open,
+      ...(route.anonymous ? { access: "anonymous" } : {}),
+    })));
+    const builtIn = [
+      ...(this.healthPath === undefined ? [] : [{ method: "GET", path: this.healthPath }]),
+      ...(this.docs === undefined ? [] : [{ method: "GET", path: this.docs.uiPath }, { method: "GET", path: this.docs.specPath }]),
+    ];
+    report.routes(builtIn.map((route) => ({ ...route, handler: "", open: true, builtIn: true })));
+    const hostname = server.hostname ?? "0.0.0.0";
+    const shown = hostname === "0.0.0.0" || hostname === "::" ? "localhost" : hostname.includes(":") ? `[${hostname}]` : hostname;
+    const url = `http://${shown}:${server.port}`;
+    report.listener({
+      protocol: "http",
+      url,
+      hostname,
+      port: server.port ?? 0,
+      ...(this.healthPath === undefined ? {} : { health: `${url}${this.healthPath}` }),
+      ...(this.docs === undefined ? {} : { docs: `${url}${this.docs.uiPath}` }),
+    });
   }
 
   private async startBunServer(create: (listen: ListenOptions) => ReturnType<typeof Bun.serve>): Promise<ReturnType<typeof Bun.serve>> {

package/core/http/Routing/RouterBuilder.ts

@@ -10,6 +10,17 @@ import { corsOptionsOf } from "../Middleware/cors";
 import { normalizeResult } from "../Results/normalize";
 import type { ApiVersioningOptions, RouteMiddlewareComposer } from "../options";
 import { createAuthorizeComposer } from "../Authorization/authorizeComposer";
+import { resolveAuthorizeMeta } from "../Authorization/metadata";
+
+/** A registered route as the startup screen lists it. */
+export interface RegisteredRoute {
+  readonly method: string;
+  readonly path: string;
+  readonly handler: string;
+  /** No `@Authorize`, or `@AllowAnonymous`. */
+  readonly open: boolean;
+  readonly anonymous: boolean;
+}
 import { Router, type RouteAction } from "./Router";
 import { joinPaths, parseTemplate } from "./template";
 
@@ -29,6 +40,8 @@ interface ActionPipeline {
  */
 export class RouterBuilder {
   private readonly authorizeComposer = createAuthorizeComposer();
+  /** Every route of the last {@link build}, in registration order. */
+  readonly routes: RegisteredRoute[] = [];
 
   constructor(
     /** Middleware prepended to every route: [logger?, cors?, errorHandler, ...global]. */
@@ -92,6 +105,14 @@ export class RouterBuilder {
         const fullPath = joinPaths(this.globalPrefix, versionSegment, meta.prefix, declaration.template);
         const versionKey = useUrlVersioning ? "" : (version ?? "");
         router.register(parseTemplate(fullPath), declaration.httpMethod, versionKey, routeAction);
+        const access = resolveAuthorizeMeta(controllerClass, methodName);
+        this.routes.push(Object.freeze({
+          method: declaration.httpMethod,
+          path: fullPath,
+          handler: routeAction.name,
+          open: access.allowAnonymous === true || access.authorize === undefined,
+          anonymous: access.allowAnonymous === true,
+        }));
       }
     }
   }

package/core/infra/Infra.ts

@@ -11,7 +11,7 @@ import {
   type BazisModuleRef,
   type ProviderDefinition,
 } from "../di";
-import { ConfigRegistry, HEALTH_CHECK } from "../kernel";
+import { ConfigRegistry, HEALTH_CHECK, StartupReport } from "../kernel";
 import { InfraError, type InfraConnector } from "./InfraConnector";
 import { InfraLifecycle } from "./InfraLifecycle";
 
@@ -83,7 +83,13 @@ function buildInfraDefinitions(manifest: InfraManifest): {
     // a failing factory elsewhere cannot leave a created resource without cleanup.
     const ownerToken = createToken<InfraLifecycle<unknown>>(`infra:${name}:lifetime`);
     const owner = DI.singleton(DI.factoryProviderWithResolver(ownerToken, [], (resolver) =>
-      new InfraLifecycle(name, connector, undefined, resolver.has(ConfigRegistry) ? resolver.resolve(ConfigRegistry) : undefined)));
+      new InfraLifecycle(
+        name,
+        connector,
+        undefined,
+        resolver.has(ConfigRegistry) ? resolver.resolve(ConfigRegistry) : undefined,
+        resolver.has(StartupReport) ? resolver.resolve(StartupReport) : undefined,
+      )));
     instances.set(owner, { name, token: connector.token });
     providers.push(owner);
     providers.push(

package/core/infra/InfraConnector.ts

@@ -1,6 +1,9 @@
 import type { InjectionToken, ModuleConfig, ModuleExport, ProviderDefinition } from "../di";
 import { redactSensitiveText } from "../../library/redaction";
 import type { ConfigRegistry } from "../kernel/config/ConfigRegistry";
+import type { ConnectionDescription } from "../kernel/report/StartupReport";
+
+export type { ConnectionDescription };
 
 /**
  * Infrastructure connector contract: one shape for "a connection to something
@@ -60,6 +63,16 @@ export interface InfraConnector<TClient = unknown> {
    */
   healthCheck?(client: TClient, signal?: AbortSignal): Promise<boolean> | boolean;
 
+  /**
+   * What the startup screen and a startup failure show about the connection:
+   * product and version, the address without credentials, short facts, and
+   * the settings that change the address. Called after a successful
+   * {@link connect} with `connected: true` (it may ask the server for its
+   * version) and after a failed one with `connected: false` (from the config
+   * only). Its errors are ignored, and it has one second.
+   */
+  describe?(client: TClient, state: { readonly connected: boolean; readonly signal?: AbortSignal }): ConnectionDescription | Promise<ConnectionDescription>;
+
   /**
    * Extra providers the connector adds to the infrastructure module besides
    * the client itself (for example `redisConnect(cfg, { cache: "distributed" })`

package/core/infra/InfraLifecycle.ts

@@ -3,6 +3,9 @@ import { InfraError, type InfraConnector } from "./InfraConnector";
 import { bindConnectorLifecycle } from "./connectorIdentity";
 import { awaitAbortable } from "../kernel/internal/awaitAbortable";
 import type { ConfigRegistry } from "../kernel/config/ConfigRegistry";
+import type { ConnectionDescription, StartupReport } from "../kernel/report/StartupReport";
+
+const DESCRIBE_TIMEOUT_MS = 1_000;
 
 const DEFAULT_INFRA_PHASE = -100;
 
@@ -19,6 +22,8 @@ export class InfraLifecycle<TClient> implements HostedService {
   public readonly phase: number;
   /** The manifest key, as in `/health`: `infra:db`. */
   public readonly diagnosticName: string;
+  /** Connections of one manifest are independent: they start together and fail together. */
+  public readonly concurrentStart = true;
   private client?: TClient;
   private created = false;
   private disposed = false;
@@ -31,6 +36,7 @@ export class InfraLifecycle<TClient> implements HostedService {
     private readonly connector: InfraConnector<TClient>,
     client?: TClient,
     private readonly configs?: ConfigRegistry,
+    private readonly report?: StartupReport,
   ) {
     this.client = client;
     this.created = client !== undefined;
@@ -66,11 +72,21 @@ export class InfraLifecycle<TClient> implements HostedService {
   }
 
   private async connect(signal?: AbortSignal): Promise<void> {
+    const startedAt = performance.now();
     try {
       signal?.throwIfAborted();
       const client = this.getClient();
+      this.report?.connection({ name: this.name, status: "wait" });
       await awaitAbortable(Promise.resolve(this.connector.connect(client, signal)), signal);
+      const ms = performance.now() - startedAt;
+      this.report?.connection({ name: this.name, status: "up", ms, ...(await this.describe(client, true, signal)) });
     } catch (error) {
+      const ms = performance.now() - startedAt;
+      if (this.report !== undefined) {
+        const description = this.created ? await this.describe(this.client as TClient, false) : {};
+        // A start cut short by the timeout is still waiting, not refused.
+        this.report.connection({ name: this.name, status: signal?.aborted ? "wait" : "down", ms, error, ...description });
+      }
       try {
         await this.dispose();
       } catch (cleanupError) {
@@ -83,6 +99,17 @@ export class InfraLifecycle<TClient> implements HostedService {
     }
   }
 
+  private async describe(client: TClient, connected: boolean, signal?: AbortSignal): Promise<ConnectionDescription> {
+    if (this.connector.describe === undefined) return {};
+    const timeout = AbortSignal.timeout(DESCRIBE_TIMEOUT_MS);
+    const combined = signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
+    try {
+      return await awaitAbortable(Promise.resolve(this.connector.describe(client, { connected, signal: combined })), combined);
+    } catch {
+      return {};
+    }
+  }
+
   public stop(): Promise<void> {
     return this.dispose();
   }

package/core/infra/connectorConfig.ts

@@ -27,3 +27,13 @@ export function requireValue(value: unknown, field: string, kind: string): strin
   }
   return value;
 }
+
+/**
+ * Environment variables that set the given keys of a config, for the fix
+ * hints of a connection failure: `BAZIS_DB__HOST`.
+ */
+export function settingNames(config: object, configs: ConfigRegistry | undefined, keys: readonly string[]): string[] {
+  const view = configs?.get(config as AppConfig<object>) as { inspect?: () => readonly { key: string; env: readonly string[] }[] } | undefined;
+  const rows = view?.inspect?.() ?? [];
+  return keys.flatMap((key) => rows.find((row) => row.key === key || row.key.endsWith(`.${key}`))?.env.slice(0, 1) ?? []);
+}

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.99.6" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.100.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");