bazis 0.97.7 → 0.97.9

package/cli/generateModule.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { lstat, mkdir, readFile, realpath, rename, rm, rmdir, writeFile } from "node:fs/promises";
 import { buildModuleTemplates, type ModuleTemplateFiles, type ModuleTemplateProfile } from "./templates/module";
-import { buildPackTemplates } from "./templates/pack";
+import { buildPackTemplates, packPartFolder } from "./templates/pack";
 import { parseModuleName, type ModuleNaming } from "./naming";
 import { moduleImportPath, registerModuleInSource } from "./moduleRegistration";
 
@@ -16,11 +16,16 @@ export interface GenerateModuleOptions {
   readonly register?: boolean;
   readonly force?: boolean;
   readonly profile?: ModuleTemplateProfile;
+  /**
+   * Composite module to add this module to as a part: `Catalog` puts it into
+   * `{modulesRoot}/catalog_modules/<name>_module` and connects it in the pack root.
+   */
+  readonly pack?: string;
   /** Validate and return the plan without writing files. */
   readonly dryRun?: boolean;
 }
 
-export interface GenerateModulePackOptions extends Omit<GenerateModuleOptions, "profile"> {
+export interface GenerateModulePackOptions extends Omit<GenerateModuleOptions, "profile" | "pack"> {
   readonly parts: readonly string[];
 }
 
@@ -44,7 +49,14 @@ export async function generateModule(options: GenerateModuleOptions): Promise<Ge
   const naming = parseModuleName(options.name);
   const profile = options.profile ?? "minimal";
   if (!["empty", "minimal", "full"].includes(profile)) throw new Error(`Unknown profile: ${profile}`);
+  const command = creationCommand("module", options, [`--${profile}`]);
   const modulesRoot = await canonicalDirectory(path.resolve(options.modulesRoot ?? "src/app/modules"));
+  // A part of a composite module lives in its pack and is connected in the pack root.
+  const pack = options.pack === undefined ? undefined : await findPack(modulesRoot, options.pack);
+  if (pack && options.appModulePath !== undefined) throw new Error("--pack connects the part in the pack root; do not combine it with --app-module.");
+  const targetRoot = pack?.dir ?? modulesRoot;
+  const folder = pack ? packPartFolder(naming) : naming.folder;
+  const target: GenerateModuleOptions = pack ? { ...options, modulesRoot: targetRoot, appModulePath: pack.entry } : options;
   let authImportPath: string | null | undefined;
   if (profile === "full") {
     // The host's auth helpers are optional: without them the controller is
@@ -52,18 +64,46 @@ export async function generateModule(options: GenerateModuleOptions): Promise<Ge
     const authDir = path.resolve("src/app/modules/auth");
     const helpers = await Promise.all(["tokenKinds.ts", "jwtAuth.ts"].map(async (helper) => (await fileInfo(path.join(authDir, helper)))?.isFile() === true));
     authImportPath = helpers.every(Boolean)
-      ? moduleImportPath(path.join(modulesRoot, naming.folder, "http", `${naming.module}.controller.ts`), await canonicalDirectory(authDir))
+      ? moduleImportPath(path.join(targetRoot, folder, "http", `${naming.module}.controller.ts`), await canonicalDirectory(authDir))
       : null;
   }
-  const result = await generateFiles(options, naming, naming.folder, buildModuleTemplates(naming, profile, authImportPath));
-  return authImportPath === null
-    ? { ...result, warnings: [...result.warnings, "No auth helpers in src/app/modules/auth: the full profile controller has no @Authorize. Protect its routes before exposing them."] }
-    : result;
+  const templates = buildModuleTemplates(naming, profile, authImportPath, { command, pack: pack?.moduleClass });
+  const result = await generateFiles(target, naming, folder, templates);
+  const warnings = [...result.warnings];
+  if (authImportPath === null) warnings.push("No auth helpers in src/app/modules/auth: the full profile controller has no @Authorize. Protect its routes before exposing them.");
+  if (pack) warnings.push(`Add ${naming.moduleClass} to the parts table in ${path.relative(process.cwd(), path.join(pack.dir, "MODULE.md"))}.`);
+  return { ...result, warnings };
 }
 
 export async function generateModulePack(options: GenerateModulePackOptions): Promise<GenerateModuleResult> {
   const naming = parseModuleName(options.name);
-  return generateFiles(options, naming, `${naming.folder}_modules`, buildPackTemplates(naming, options.parts));
+  const command = creationCommand("pack", options, ["--parts", options.parts.join(",")]);
+  return generateFiles(options, naming, `${naming.folder}_modules`, buildPackTemplates(naming, options.parts, command));
+}
+
+/** The existing composite module `name` under `modulesRoot`: `Catalog` → `catalog_modules/Catalog.module.ts`. */
+async function findPack(modulesRoot: string, name: string): Promise<{ readonly dir: string; readonly entry: string; readonly moduleClass: string }> {
+  const naming = parseModuleName(name);
+  const dir = path.join(modulesRoot, `${naming.folder}_modules`);
+  const entry = path.join(dir, `${naming.module}.module.ts`);
+  if ((await fileInfo(entry))?.isFile() !== true) {
+    throw new Error(`Pack ${naming.moduleClass} not found: ${path.relative(process.cwd(), entry)}. Create it with bazis g pack ${naming.module} --parts <a,b>.`);
+  }
+  return { dir, entry, moduleClass: naming.moduleClass };
+}
+
+/**
+ * The command recorded in the passport, as the architecture rules require. It is
+ * rebuilt from the options in a canonical form, so the passport shows the same
+ * text however the flags were ordered or aliased.
+ */
+function creationCommand(generator: "module" | "pack", options: GenerateModuleOptions, extra: readonly string[]): string {
+  const parts = ["bunx bazis g", generator, options.name, ...extra];
+  if (options.pack !== undefined) parts.push("--pack", options.pack);
+  if (options.modulesRoot !== undefined) parts.push("--modules-root", options.modulesRoot);
+  if (options.appModulePath !== undefined) parts.push("--app-module", options.appModulePath);
+  if (options.register === false) parts.push("--no-register");
+  return parts.join(" ");
 }
 
 async function generateFiles(options: GenerateModuleOptions, naming: ModuleNaming, folder: string, templates: readonly ModuleTemplateFiles[]): Promise<GenerateModuleResult> {

package/cli/generateProject.ts

@@ -168,7 +168,7 @@ function buildProjectFiles(name: string, dependency: string, frameworkMode: Fram
     [".env.example", "# Copy to .env (Bun loads it automatically).\nBAZIS_ENV=development\nHOST=127.0.0.1\nPORT=3000\n"],
     ["src/app/test/health.test.ts", HEALTH_TEST],
     ["AGENTS.md", "# Working on this bazis project\n\nBefore changing the application, read the [module architecture](docs/architecture/MODULE_ARCHITECTURE.md). Create new modules only with `bunx bazis g module` or `bunx bazis g pack`; fill in the generated `MODULE.md` afterwards. Only codegen updates `src/generated/`.\n"],
-    ["docs/architecture/MODULE_ARCHITECTURE.md", "# Application module architecture\n\n`src/index.ts` calls `runApp`; `src/app/modules/App.module.ts` composes feature modules through `imports`. The application root owns no domain logic.\n\nOne self-contained function is an atomic module. It owns its data, services, HTTP and background handlers. A composite module is only for several independent functions; its root does composition. Layers and file counts alone do not create submodules.\n\nCreate new modules only with `bunx bazis g module <Name> --empty|--minimal|--full` or `bunx bazis g pack <Name> --parts <a,b>`. Before implementing, define the responsibility and public entries, then fill in the generated `MODULE.md`: fields, errors, dependencies, exports and checks. Use the public APIs of the `bazis` package and its DI and ORM. Do not edit `src/generated/` by hand; run `bunx bazis codegen`.\n\n`--minimal` creates a sample CRUD with the ORM. To run it the application needs a database provider and a ready schema. For a first function without a database use `--empty`. Check types and the binary build after changes that affect startup.\n"],
+    ["docs/architecture/MODULE_ARCHITECTURE.md", "# Application module architecture\n\n`src/index.ts` calls `runApp`; `src/app/modules/App.module.ts` composes feature modules through `imports`. The application root owns no domain logic.\n\nOne self-contained function is an atomic module. It owns its data, services, HTTP and background handlers. A composite module is only for several independent functions; its root does composition. Layers and file counts alone do not create submodules.\n\nCreate new modules only with `bunx bazis g module <Name> --empty|--minimal|--full` or `bunx bazis g pack <Name> --parts <a,b>`; add a part to an existing composite with `bunx bazis g module <Name> --pack <Pack>`. The generated `MODULE.md` records the creation command. Before implementing, define the responsibility and public entries, then fill in the generated `MODULE.md`: fields, errors, dependencies, exports and checks. Use the public APIs of the `bazis` package and its DI and ORM. Do not edit `src/generated/` by hand; run `bunx bazis codegen`.\n\n`--minimal` creates a sample CRUD with the ORM. To run it the application needs a database provider and a ready schema. For a first function without a database use `--empty`. Check types and the binary build after changes that affect startup.\n"],
     ["src/app/modules/App.module.ts", 'import { Module } from "bazis/core/di";\n\n@Module({ imports: [], exports: [] })\nexport class AppModule {}\n'],
     ["src/index.ts", 'import { runApp } from "bazis/core/app";\nimport { AppModule } from "./app/modules/App.module";\nimport { registerBazisGeneratedRuntime } from "./generated/bazis/runtime";\n\nawait registerBazisGeneratedRuntime();\nawait runApp(AppModule, { http: { hostname: process.env.HOST ?? "127.0.0.1", port: Number(process.env.PORT ?? 3000), health: true } });\n'],
     ["README.md", `# ${name}\n\nA [bazis](https://www.npmjs.com/package/bazis) application. ${frameworkMode === "registry"

package/cli/main.ts

@@ -26,6 +26,8 @@ Generation options:
   --link-framework      Depend on that local checkout through a file: link (new only)
   --modules-root <path>  Modules root (default: src/app/modules)
   --app-module <path>    Host module (default: {modules-root}/App.module.ts)
+  --pack <Name>          Module only: add it as a part of the composite <Name>
+                         ({modules-root}/<name>_modules/<module>_module)
   --empty               Module entry and MODULE.md only
   --minimal             Compact example CRUD and MODULE.md (default)
   --full                Example CRUD/list/cache/auth/background/AI and MODULE.md;
@@ -47,6 +49,7 @@ Examples (from the project root):
   bunx bazis g m Guest --no-codegen
   bunx bazis g module Mailer --empty --no-register
   bunx bazis g pack DataManager --parts tables,fields,validators,records
+  bunx bazis g module Prices --empty --pack Catalog
   bunx bazis codegen --target production
   bunx bazis dev --watch
   bunx bazis test
@@ -106,7 +109,7 @@ export async function runCli(argv: readonly string[], runtime: CliRuntime = defa
     const { generateModule, generateModulePack } = await import("./generateModule");
     const result = args.generator === "pack"
       ? await generateModulePack({ ...options, parts: args.parts })
-      : await generateModule({ ...options, profile: args.profile });
+      : 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}`);

package/cli/parseCli.ts

@@ -8,6 +8,8 @@ export interface ParsedGenerateArgs {
   readonly parts: readonly string[];
   readonly modulesRoot?: string;
   readonly appModule?: string;
+  /** Composite module to add the new module to as a part (module generator only). */
+  readonly pack?: string;
   readonly register: boolean;
   readonly force: boolean;
   readonly profile: GenerateProfile;
@@ -30,7 +32,7 @@ const GENERATOR_ALIASES = new Map<string, "module" | "pack">([
   ["module", "module"], ["m", "module"],
   ["pack", "pack"], ["p", "pack"], ["module-pack", "pack"],
 ]);
-const VALUE_OPTIONS = new Set(["--modules-root", "--app-module", "--parts", "--target", "--path", "--framework", "--outfile"]);
+const VALUE_OPTIONS = new Set(["--modules-root", "--app-module", "--pack", "--parts", "--target", "--path", "--framework", "--outfile"]);
 const FLAG_OPTIONS = new Set(["--no-register", "--force", "--full", "--enterprise", "--minimal", "--empty", "--dry-run", "--no-codegen", "--link-framework", "--vendor", "--bin", "--watch"]);
 
 /** Parsing is pure: help and invalid input can never start generation. */
@@ -119,12 +121,15 @@ export function parseCliArgs(argv: readonly string[]): ParseCliResult {
   if (profiles.length > 1) return error("Choose only one profile: --empty, --minimal or --full.");
   if (generator === "pack" && profiles.length > 0) return error("Pack parts start empty; module profile flags are not supported by pack.");
   if (generator === "module" && options.has("--parts")) return error("--parts is only supported by pack.");
+  if (generator === "pack" && options.has("--pack")) return error("--pack adds a part with g module; a pack is created with --parts.");
+  if (options.has("--pack") && options.has("--app-module")) return error("--pack connects the part in the pack root; do not combine it with --app-module.");
   if (options.has("--no-codegen") && target !== undefined) return error("--target cannot be used with --no-codegen.");
   if (options.has("--no-register") && target !== undefined) return error("Use bazis codegen --target separately after connecting the module.");
 
   const parts = options.get("--parts")?.split(",").map((part) => part.trim()) ?? [];
   try {
     parseModuleName(name);
+    if (options.has("--pack")) parseModuleName(options.get("--pack")!);
     if (generator === "pack") validatePackParts(parts);
   } catch (cause) {
     return error(cause instanceof Error ? cause.message : String(cause));
@@ -133,7 +138,7 @@ export function parseCliArgs(argv: readonly string[]): ParseCliResult {
     kind: "generate",
     args: {
       generator, name, parts,
-      modulesRoot: options.get("--modules-root"), appModule: options.get("--app-module"),
+      modulesRoot: options.get("--modules-root"), appModule: options.get("--app-module"), pack: options.get("--pack"),
       register: !options.has("--no-register"), force: options.has("--force"),
       profile: profiles[0] ?? "minimal", dryRun: options.has("--dry-run"),
       codegen: !options.has("--no-codegen"), target,

package/cli/templates/module.ts

@@ -1,5 +1,5 @@
 import type { ModuleNaming } from "../naming";
-import { modulePassport } from "./passport";
+import { modulePassport, type PassportOrigin } from "./passport";
 
 export type ModuleTemplateProfile = "empty" | "minimal" | "full";
 
@@ -20,11 +20,12 @@ export function buildModuleTemplates(
   profile: ModuleTemplateProfile = "minimal",
   /** null: the host has no auth helpers, so `full` emits no @Authorize. */
   authImportPath: string | null = "../../auth",
+  origin: PassportOrigin = {},
 ): readonly ModuleTemplateFiles[] {
   if (profile === "empty") {
     return [
       { relativePath: `${naming.module}.module.ts`, content: `import { Module } from "bazis/core/di";\n\n@Module({ imports: [], exports: [] })\nexport class ${naming.moduleClass} {}\n` },
-      { relativePath: "MODULE.md", content: modulePassport(naming, profile) },
+      { relativePath: "MODULE.md", content: modulePassport(naming, profile, origin) },
     ];
   }
 
@@ -38,7 +39,7 @@ export function buildModuleTemplates(
     { relativePath: `http/contracts/${naming.module}.requests.ts`, content: requestFile(naming) },
     { relativePath: `http/contracts/${naming.module}.responses.ts`, content: responseFile(naming) },
     { relativePath: `http/contracts/${naming.module}List.query.ts`, content: listQueryFile(naming) },
-    { relativePath: "MODULE.md", content: modulePassport(naming, profile) },
+    { relativePath: "MODULE.md", content: modulePassport(naming, profile, origin) },
   ];
 
   if (profile === "minimal") {

package/cli/templates/pack.ts

@@ -2,12 +2,17 @@ import { parseModuleName, type ModuleNaming } from "../naming";
 import { validatePackParts } from "../parseCli";
 import { buildModuleTemplates, type ModuleTemplateFiles } from "./module";
 
-export function buildPackTemplates(naming: ModuleNaming, partNames: readonly string[]): readonly ModuleTemplateFiles[] {
+/** The folder of a pack part: `prices` → `prices_module`. */
+export function packPartFolder(part: ModuleNaming): string {
+  return `${part.folder}_module`;
+}
+
+export function buildPackTemplates(naming: ModuleNaming, partNames: readonly string[], command?: string): readonly ModuleTemplateFiles[] {
   validatePackParts(partNames);
   const parts = partNames.map((name) => {
     const part = parseModuleName(name);
     // A part names a responsibility (Tables), not a CRUD entity (Table).
-    return { ...part, entity: part.module, folder: `${part.folder}_module` };
+    return { ...part, entity: part.module, folder: packPartFolder(part) };
   });
   if (parts.some((part) => part.moduleClass === naming.moduleClass)) {
     throw new Error("A pack and its parts must have distinct module class names.");
@@ -32,7 +37,7 @@ export class ${naming.moduleClass} {}
 Passport version: 1.0. Type: composite.
 Status: composition scaffold generated; the parts are not implemented yet.
 Entry: [${naming.module}.module.ts](${naming.module}.module.ts).
-Before changing it, read AGENTS.md and docs/architecture/MODULE_ARCHITECTURE.md.
+${command === undefined ? "" : `Created with: \`${command}\`.\n`}Before changing it, read AGENTS.md and docs/architecture/MODULE_ARCHITECTURE.md.
 
 ## Responsibility and parts
 
@@ -69,7 +74,7 @@ exports, no cycles or duplicate registrations, the parts' tests.
 A generated scaffold does not prove the pack is ready.
 `,
     },
-    ...parts.flatMap((part) => buildModuleTemplates(part, "empty").map((file) => ({
+    ...parts.flatMap((part) => buildModuleTemplates(part, "empty", undefined, { command, pack: naming.moduleClass }).map((file) => ({
       relativePath: `${part.folder}/${file.relativePath}`, content: file.content,
     }))),
   ];

package/cli/templates/passport.ts

@@ -1,13 +1,22 @@
 import type { ModuleNaming } from "../naming";
 import type { ModuleTemplateProfile } from "./module";
 
-export function modulePassport(n: ModuleNaming, profile: ModuleTemplateProfile): string {
+/** Facts the generator knows about how the module was created. */
+export interface PassportOrigin {
+  /** The CLI command that created the module, recorded as the architecture rules require. */
+  readonly command?: string;
+  /** Module class of the composite module this one is a part of. */
+  readonly pack?: string;
+}
+
+export function modulePassport(n: ModuleNaming, profile: ModuleTemplateProfile, origin: PassportOrigin = {}): string {
+  const type = origin.pack === undefined ? "atomic" : `atomic, a part of the composite ${origin.pack} ([passport](../MODULE.md))`;
   const header = `# ${n.moduleClass}
 
-Passport version: 1.0. Type: atomic. CLI profile: ${profile}.
+Passport version: 1.0. Type: ${type}. CLI profile: ${profile}.
 Status: scaffold generated; the domain implementation and checks are not done.
 Entry: [${n.module}.module.ts](${n.module}.module.ts), class ${n.moduleClass}, no arguments.
-
+${origin.command === undefined ? "" : `Created with: \`${origin.command}\`.\n`}
 Before changing it, read AGENTS.md and docs/architecture/MODULE_ARCHITECTURE.md.
 This passport covers the scaffold files. The author defines the responsibility
 and fields before implementing the domain function and updates this passport

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.97.7" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.97.9" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/kernel/config/defineConfig.ts

@@ -90,6 +90,19 @@ export function processConfiguration(): Configuration {
   }
   return new Configuration(values, origins);
 }
+/**
+ * Why an environment variable name cannot be used for a key, or undefined.
+ * Aliases are read from the same BAZIS_* variables as the generated names,
+ * so they share the prefix.
+ */
+function environmentNameProblem(name: string, claimed: ReadonlySet<string>): string | undefined {
+  if (!name.startsWith(ENV_PREFIX)) return `must start with ${ENV_PREFIX}: configuration reads only ${ENV_PREFIX}* variables (for example ${ENV_PREFIX}${name.replace(/^[^A-Za-z0-9]+/, "").toUpperCase() || "NAME"})`;
+  if (name.length === ENV_PREFIX.length) return `needs a name after ${ENV_PREFIX}`;
+  if (!/^[A-Z0-9_-]+$/.test(name)) return "may contain only A-Z, 0-9, _ and -";
+  if (claimed.has(name)) return "is already used by another key of this configuration";
+  return undefined;
+}
+
 function isSecret(cell: Cell): cell is SecretSpec { return typeof cell === "object" && cell !== null && "__secret" in cell; }
 function isEnum(cell: Cell): cell is ConfigEnum { return typeof cell === "object" && cell !== null && "__enum" in cell; }
 function copyCell(cell: Cell): Cell {
@@ -127,7 +140,8 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
     const alias = input.env?.[key];
     const env = [...new Set([`${ENV_PREFIX}${fullKey(key).replaceAll(".", "__").toUpperCase()}`, ...(typeof alias === "string" ? [alias] : alias ?? [])])];
     for (const name of env) {
-      if (!name.startsWith(ENV_PREFIX) || name.length === ENV_PREFIX.length || !/^[A-Z0-9_-]+$/.test(name) || claimed.has(name)) throw new KernelError(`Invalid or duplicate configuration environment name: ${name}.`);
+      const problem = environmentNameProblem(name, claimed);
+      if (problem) throw new KernelError(`Configuration key "${fullKey(key)}": environment variable "${name}" ${problem}.`);
       claimed.add(name);
     }
     names.set(key, Object.freeze(env));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.97.7",
+  "version": "0.97.9",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",