bazis 0.96.1

package/cli/parseCli.ts

@@ -0,0 +1,151 @@
+import { parseModuleName } from "./naming";
+
+export type GenerateProfile = "empty" | "minimal" | "full";
+
+export interface ParsedGenerateArgs {
+  readonly generator: "module" | "pack";
+  readonly name: string;
+  readonly parts: readonly string[];
+  readonly modulesRoot?: string;
+  readonly appModule?: string;
+  readonly register: boolean;
+  readonly force: boolean;
+  readonly profile: GenerateProfile;
+  readonly dryRun: boolean;
+  readonly codegen: boolean;
+  readonly target?: string;
+}
+
+export type ParseCliResult =
+  | { readonly kind: "help"; readonly help: boolean }
+  | { readonly kind: "new"; readonly name: string; readonly outputPath?: string; readonly frameworkPath?: string; readonly linkFramework: boolean; readonly dryRun: boolean }
+  | { readonly kind: "generate"; readonly args: ParsedGenerateArgs }
+  | { readonly kind: "codegen"; readonly target?: string }
+  | { readonly kind: "dev"; readonly watch: boolean }
+  | { readonly kind: "test"; readonly args: readonly string[] }
+  | { readonly kind: "build"; readonly bin: boolean; readonly outfile?: string }
+  | { readonly kind: "error"; readonly message: string };
+
+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 FLAG_OPTIONS = new Set(["--no-register", "--force", "--full", "--enterprise", "--minimal", "--empty", "--dry-run", "--no-codegen", "--link-framework", "--bin", "--watch"]);
+
+/** Parsing is pure: help and invalid input can never start generation. */
+export function parseCliArgs(argv: readonly string[]): ParseCliResult {
+  if (argv.some((arg) => arg === "--help" || arg === "-h")) return { kind: "help", help: true };
+  if (argv.length === 0) return { kind: "help", help: false };
+  // Everything after `test` (or `test --`) belongs to `bun test`.
+  if (argv[0] === "test") return { kind: "test", args: argv[1] === "--" ? argv.slice(2) : argv.slice(1) };
+
+  const positional: string[] = [];
+  const options = new Map<string, string>();
+  const error = (message: string): ParseCliResult => ({ kind: "error", message });
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    if (VALUE_OPTIONS.has(arg)) {
+      const value = argv[++index];
+      if (value === undefined || value.startsWith("-") || value.trim() === "") {
+        return error(`Option ${arg} requires a value.`);
+      }
+      if (options.has(arg)) return error(`Option ${arg} may only be specified once.`);
+      options.set(arg, value);
+    } else if (FLAG_OPTIONS.has(arg)) {
+      options.set(arg, "true");
+    } else if (arg.startsWith("-")) {
+      return error(`Unknown option: ${arg}`);
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  const [command, generatorToken, name] = positional;
+  const target = options.get("--target");
+  if (command === "new") {
+    if (positional.length !== 2) return error("Use: bazis new <Name> [--path <directory>] [--framework <directory>] [--link-framework] [--dry-run]");
+    for (const option of options.keys()) {
+      if (option !== "--path" && option !== "--framework" && option !== "--link-framework" && option !== "--dry-run") {
+        return error(`Option ${option} is not supported by new.`);
+      }
+    }
+    try {
+      parseModuleName(generatorToken!);
+    } catch (cause) {
+      return error(cause instanceof Error ? cause.message : String(cause));
+    }
+    return { kind: "new", name: generatorToken!, outputPath: options.get("--path"), frameworkPath: options.get("--framework"), linkFramework: options.has("--link-framework"), dryRun: options.has("--dry-run") };
+  }
+  if (target !== undefined && !/^[a-z][a-z0-9-]*$/.test(target)) {
+    return error("Target must be a codegen target name or all.");
+  }
+  if (command === "dev") {
+    if (positional.length !== 1 || [...options.keys()].some((option) => option !== "--watch")) return error("Use: bazis dev [--watch]");
+    return { kind: "dev", watch: options.has("--watch") };
+  }
+  if (options.has("--watch")) return error("--watch is only supported by dev.");
+  if (command === "build") {
+    if (positional.length !== 1) return error("Use: bazis build [--bin [--outfile <path>]]");
+    for (const option of options.keys()) {
+      if (option !== "--bin" && option !== "--outfile") return error(`Option ${option} is not supported by build.`);
+    }
+    if (options.has("--outfile") && !options.has("--bin")) return error("--outfile requires --bin.");
+    return { kind: "build", bin: options.has("--bin"), outfile: options.get("--outfile") };
+  }
+  if (options.has("--bin") || options.has("--outfile")) return error("--bin and --outfile are only supported by build.");
+  if (command === "codegen") {
+    if (positional.length !== 1) return error("Use: bazis codegen [--target <name|all>]");
+    for (const option of options.keys()) {
+      if (option !== "--target") return error(`Option ${option} is not supported by codegen.`);
+    }
+    return { kind: "codegen", target };
+  }
+  if (command !== "g" && command !== "generate") {
+    return error(`Unknown command: ${command ?? "(missing)"}. Use: bazis --help`);
+  }
+  if (generatorToken === undefined) return error("Generator is required: module (m) or pack (p).");
+  if (options.has("--path") || options.has("--framework") || options.has("--link-framework")) return error("--path, --framework and --link-framework are only supported by new.");
+  const generator = GENERATOR_ALIASES.get(generatorToken);
+  if (generator === undefined) return error(`Unknown generator: ${generatorToken}. Supported: module (m), pack (p)`);
+  if (name === undefined) return error("Module name is required.");
+  if (positional.length !== 3) return error(`Unexpected argument: ${positional[3]}`);
+
+  const profiles: GenerateProfile[] = [];
+  if (options.has("--minimal")) profiles.push("minimal");
+  if (options.has("--full") || options.has("--enterprise")) profiles.push("full");
+  if (options.has("--empty")) profiles.push("empty");
+  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 (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 (generator === "pack") validatePackParts(parts);
+  } catch (cause) {
+    return error(cause instanceof Error ? cause.message : String(cause));
+  }
+  return {
+    kind: "generate",
+    args: {
+      generator, name, parts,
+      modulesRoot: options.get("--modules-root"), appModule: options.get("--app-module"),
+      register: !options.has("--no-register"), force: options.has("--force"),
+      profile: profiles[0] ?? "minimal", dryRun: options.has("--dry-run"),
+      codegen: !options.has("--no-codegen"), target,
+    },
+  };
+}
+
+export function validatePackParts(parts: readonly string[]): void {
+  if (parts.length < 2) throw new Error("A pack needs at least two independent parts. Use --parts tables,records.");
+  const names = parts.map(parseModuleName);
+  // `records` and `record` are distinct modules but name one entity: reject the confusion.
+  if (new Set(names.map((name) => name.folder)).size !== names.length
+    || new Set(names.map((name) => name.entity)).size !== names.length) {
+    throw new Error("Pack parts must have distinct names (also in singular form).");
+  }
+}

package/cli/templates/module.ts

@@ -0,0 +1,497 @@
+import type { ModuleNaming } from "../naming";
+import { modulePassport } from "./passport";
+
+export type ModuleTemplateProfile = "empty" | "minimal" | "full";
+
+export interface ModuleTemplateFiles {
+  readonly relativePath: string;
+  readonly content: string;
+}
+
+/**
+ * Feature module scaffold.
+ *
+ * `minimal` (default): a compact CRUD that is easy to read and adapt.
+ * `empty`: the entry point and passport. `full`: a showcase with
+ * auth/cache/background/JSON:API list and an AI entry in the same feature.
+ */
+export function buildModuleTemplates(
+  naming: ModuleNaming,
+  profile: ModuleTemplateProfile = "minimal",
+  /** null: the host has no auth helpers, so `full` emits no @Authorize. */
+  authImportPath: string | null = "../../auth",
+): 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) },
+    ];
+  }
+
+  const base: ModuleTemplateFiles[] = [
+    { relativePath: `${naming.module}.module.ts`, content: moduleFile(naming, profile) },
+    { relativePath: `model/${naming.module}.model.ts`, content: ormModelFile(naming, profile) },
+    { relativePath: `model/${naming.module}.dbContext.ts`, content: dbContextFile(naming) },
+    { relativePath: `services/I${naming.module}.service.ts`, content: serviceInterfaceFile(naming) },
+    { relativePath: `services/${naming.module}.service.ts`, content: serviceFile(naming, profile) },
+    { relativePath: `http/${naming.module}.controller.ts`, content: controllerFile(naming, profile, authImportPath) },
+    { 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) },
+  ];
+
+  if (profile === "minimal") {
+    return base;
+  }
+
+  return [
+    ...base,
+    { relativePath: `background/${naming.module}.reporter.ts`, content: statsReporterFile(naming) },
+    { relativePath: `ai/agents/${naming.module}Analyst.agent.ts`, content: agentFile(naming) },
+    { relativePath: `ai/contracts/${naming.module}.brief.ts`, content: aiContractsFile(naming) },
+    { relativePath: `ai/tools/${naming.module}Summary.tool.ts`, content: aiToolFile(naming) },
+  ];
+}
+
+function moduleFile(n: ModuleNaming, profile: ModuleTemplateProfile): string {
+  const cacheImport = profile === "full" ? "import { cachedScoped } from \"bazis/core/cache\";\n" : "";
+  const moduleImport = "import { Module, scoped } from \"bazis/core/di\";";
+  const providerFactory = profile === "full" ? "cachedScoped" : "scoped";
+  const backgroundImport = profile === "full" ? `import { ${n.module}Reporter } from "./background/${n.module}.reporter";\n` : "";
+  const aiImports = profile === "full"
+    ? `import { ${n.module}AnalystAgent } from "./ai/agents/${n.module}Analyst.agent";
+import { ${n.module}SummaryTool } from "./ai/tools/${n.module}Summary.tool";
+`
+    : "";
+  const backgroundLine = profile === "full" ? `  background: [${n.module}Reporter],\n` : "";
+  const aiLines = profile === "full"
+    ? `  agents: [${n.module}AnalystAgent],
+  tools: [${n.module}SummaryTool],
+`
+    : "";
+
+  return `${cacheImport}${moduleImport}
+${aiImports}${backgroundImport}import { ${n.module}Controller } from "./http/${n.module}.controller";
+import { ${n.entity} } from "./model/${n.module}.model";
+import { ${n.module}DbContext } from "./model/${n.module}.dbContext";
+import { I${n.module}Service } from "./services/I${n.module}.service";
+import { ${n.module}Service } from "./services/${n.module}.service";
+
+@Module({
+  ormBazis: {
+    context: ${n.module}DbContext,
+    entities: [${n.entity}],
+  },
+  controllers: [${n.module}Controller],
+  providers: [
+    ${providerFactory}(I${n.module}Service, ${n.module}Service),
+  ],
+${backgroundLine}${aiLines}  exports: [I${n.module}Service],
+})
+export class ${n.moduleClass} {}
+`;
+}
+
+function controllerFile(n: ModuleNaming, profile: ModuleTemplateProfile, authImportPath: string | null): string {
+  const auth = profile === "full" && authImportPath !== null;
+  const fullImports = profile !== "full"
+    ? "import { Controller, Created, Delete, Get, HttpContext, NoContent, NotFound, Ok, Post, Put } from \"bazis/core/http\";\n"
+    : auth
+      ? `import { OutputCache } from "bazis/core/cache";
+import { Authorize, Controller, Created, Delete, Get, HttpContext, NoContent, NotFound, Ok, Post, Put } from "bazis/core/http";
+import { TokenKind } from "${authImportPath}/tokenKinds";
+import { requireTokenKind } from "${authImportPath}/jwtAuth";
+`
+      : `import { OutputCache } from "bazis/core/cache";
+import { Controller, Created, Delete, Get, HttpContext, NoContent, NotFound, Ok, Post, Put } from "bazis/core/http";
+// No host auth helpers (src/app/modules/auth) were found: these routes are public.
+// Add @Authorize(...) from "bazis/core/http" with your policy before exposing them.
+`;
+  const authList = profile === "full"
+    ? `${auth ? "  @Authorize(requireTokenKind(TokenKind.Admin, TokenKind.Client))\n" : ""}  @OutputCache({ seconds: 30, varyByQuery: "*", varyByUser: true, tags: ["${n.route}"] })
+`
+    : "";
+  const authRead = auth ? "  @Authorize(requireTokenKind(TokenKind.Admin, TokenKind.Client))\n" : "";
+  const authWrite = auth ? "  @Authorize(requireTokenKind(TokenKind.Admin))\n" : "";
+
+  return `${fullImports}import { buildListDocument } from "bazis/library/jsonapi";
+import { ${n.module}ListQuery } from "./contracts/${n.module}List.query";
+import { Create${n.entity}Request, Update${n.entity}Request } from "./contracts/${n.module}.requests";
+import type { I${n.module}Service } from "../services/I${n.module}.service";
+
+@Controller("${n.route}")
+export class ${n.module}Controller {
+  constructor(private readonly ${n.collection}: I${n.module}Service) {}
+
+${authList}  @Get()
+  async list(query: ${n.module}ListQuery, ctx: HttpContext) {
+    const { items, total } = await this.${n.collection}.getAll(query);
+    return buildListDocument(items, query, total, { basePath: ctx.path });
+  }
+
+${authRead}  @Get(":id(uuid)")
+  async getById(id: string) {
+    const item = await this.${n.collection}.getById(id);
+    return item ? Ok(item) : NotFound({ error: \`${n.entity.toLowerCase()} \${id} not found\` });
+  }
+
+${authWrite}  @Post()
+  async create(body: Create${n.entity}Request, ctx: HttpContext) {
+    const item = await this.${n.collection}.create(body);
+    return Created(\`\${ctx.path.replace(/\\/$/, "")}/\${item.id}\`, item);
+  }
+
+${authWrite}  @Put(":id(uuid)")
+  async update(id: string, body: Update${n.entity}Request) {
+    const item = await this.${n.collection}.update(id, body);
+    return item ? Ok(item) : NotFound({ error: \`${n.entity.toLowerCase()} \${id} not found\` });
+  }
+
+${authWrite}  @Delete(":id(uuid)")
+  async delete(id: string) {
+    const removed = await this.${n.collection}.delete(id);
+    return removed ? NoContent() : NotFound({ error: \`${n.entity.toLowerCase()} \${id} not found\` });
+  }
+}
+`;
+}
+
+function ormModelFile(n: ModuleNaming, profile: ModuleTemplateProfile): string {
+  const schemaImport = profile === "full" ? ", Schema" : "";
+  const schemaDecorator = profile === "full" ? `@Schema("${n.dbSchema}")\n` : "";
+  return `import { Column, Entity, Index, UUID${schemaImport} } from "bazis/core/orm";
+
+${schemaDecorator}@Entity({ table: "${n.route}" })
+export class ${n.entity} {
+  @UUID()
+  id = "";
+
+  @Column({ type: "text" })
+  name = "";
+
+  @Index({ unique: true })
+  @Column({ type: "text" })
+  email = "";
+
+  @Column({ type: "createdAt" })
+  createdAt = new Date(0);
+
+  @Column({ type: "updatedAt" })
+  updatedAt = new Date(0);
+}
+`;
+}
+
+function dbContextFile(n: ModuleNaming): string {
+  return `import { DbContext } from "bazis/core/orm";
+import { ${n.entity} } from "./${n.module}.model";
+
+export class ${n.module}DbContext extends DbContext {
+  readonly ${n.collection} = this.set(${n.entity});
+}
+`;
+}
+
+function serviceInterfaceFile(n: ModuleNaming): string {
+  return `import { createToken } from "bazis/core/di";
+import type { PageResult } from "bazis/core/orm";
+import type { ListQuery } from "bazis/library/jsonapi";
+import type { Create${n.entity}Request, Update${n.entity}Request } from "../http/contracts/${n.module}.requests";
+import type { ${n.entity}Response, ${n.module}Summary } from "../http/contracts/${n.module}.responses";
+
+export interface I${n.module}Service {
+  getAll(query: ListQuery): Promise<PageResult<${n.entity}Response>>;
+  summary(): Promise<${n.module}Summary>;
+  count(): Promise<number>;
+  getById(id: string): Promise<${n.entity}Response | null>;
+  create(body: Create${n.entity}Request): Promise<${n.entity}Response>;
+  update(id: string, body: Update${n.entity}Request): Promise<${n.entity}Response | null>;
+  delete(id: string): Promise<boolean>;
+}
+
+export const I${n.module}Service = createToken<I${n.module}Service>("I${n.module}Service");
+`;
+}
+
+function serviceFile(n: ModuleNaming, profile: ModuleTemplateProfile): string {
+  const imports = profile === "full"
+    ? `import { Cacheable, type ICache } from "bazis/core/cache";\n`
+    : "";
+  const cacheDecorator = profile === "full"
+    ? `  @Cacheable({ seconds: 60, key: (id) => \`${n.route}:\${String(id)}\`, tags: ["${n.route}"] })
+`
+    : "";
+  const invalidateCache = profile === "full" ? `\n    this.cache.evictByTag("${n.route}");` : "";
+
+  return `${imports}import { paginate, type PageResult } from "bazis/core/orm";
+import type { ListQuery } from "bazis/library/jsonapi";
+import type { Create${n.entity}Request, Update${n.entity}Request } from "../http/contracts/${n.module}.requests";
+import { to${n.entity}Response, type ${n.entity}Response, type ${n.module}Summary } from "../http/contracts/${n.module}.responses";
+import { ${n.entity} } from "../model/${n.module}.model";
+import { ${n.module}DbContext } from "../model/${n.module}.dbContext";
+import type { I${n.module}Service } from "./I${n.module}.service";
+
+export class ${n.module}Service implements I${n.module}Service {
+  constructor(private readonly db: ${n.module}DbContext${profile === "full" ? ", private readonly cache: ICache" : ""}) {}
+
+  async getAll(query: ListQuery): Promise<PageResult<${n.entity}Response>> {
+    const { items, total } = await paginate(this.db.${n.collection}.asNoTracking(), query);
+    return { items: items.map(to${n.entity}Response), total };
+  }
+
+  async summary(): Promise<${n.module}Summary> {
+    const count = await this.count();
+    const items = await this.db.${n.collection}.asNoTracking().orderBy(item => item.id).take(20)
+      .select(item => ({ name: item.name })).toList();
+    return {
+      count,
+      names: items.map((item) => item.name),
+    };
+  }
+
+  count(): Promise<number> {
+    return this.db.${n.collection}.count();
+  }
+
+${cacheDecorator}  async getById(id: string): Promise<${n.entity}Response | null> {
+    const item = await this.db.${n.collection}.find(id);
+    return item ? to${n.entity}Response(item) : null;
+  }
+
+  async create(body: Create${n.entity}Request): Promise<${n.entity}Response> {
+    const item = Object.assign(new ${n.entity}(), {
+      name: body.name,
+      email: body.email,
+    });
+    this.db.${n.collection}.add(item);
+    await this.db.saveChanges();${invalidateCache}
+    return to${n.entity}Response(item);
+  }
+
+  async update(id: string, body: Update${n.entity}Request): Promise<${n.entity}Response | null> {
+    const item = await this.db.${n.collection}.find(id);
+    if (!item) {
+      return null;
+    }
+    if (body.name !== undefined) {
+      item.name = body.name;
+    }
+    if (body.email !== undefined) {
+      item.email = body.email;
+    }
+    await this.db.saveChanges();${invalidateCache}
+    return to${n.entity}Response(item);
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const item = await this.db.${n.collection}.find(id);
+    if (!item) {
+      return false;
+    }
+    this.db.${n.collection}.remove(item);
+    await this.db.saveChanges();${invalidateCache}
+    return true;
+  }
+}
+`;
+}
+
+function requestFile(n: ModuleNaming): string {
+  return `import { RequestModel } from "bazis/core/http";
+import { Validator } from "bazis/library/validation";
+
+@RequestModel()
+export class Create${n.entity}Request {
+  @Validator({ required: true, minLength: 2, maxLength: 100 })
+  name!: string;
+
+  @Validator({ required: true, email: true, minLength: 3, maxLength: 120 })
+  email!: string;
+}
+
+@RequestModel()
+export class Update${n.entity}Request {
+  @Validator({ minLength: 2, maxLength: 100 })
+  name?: string;
+
+  @Validator({ email: true, minLength: 3, maxLength: 120 })
+  email?: string;
+}
+`;
+}
+
+function responseFile(n: ModuleNaming): string {
+  return `import type { ${n.entity} } from "../../model/${n.module}.model";
+
+export interface ${n.entity}Response {
+  readonly id: string;
+  readonly name: string;
+  readonly email: string;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+}
+
+export interface ${n.module}Summary {
+  readonly count: number;
+  readonly names: readonly string[];
+}
+
+export function to${n.entity}Response(entity: ${n.entity}): ${n.entity}Response {
+  return {
+    id: entity.id,
+    name: entity.name,
+    email: entity.email,
+    createdAt: entity.createdAt,
+    updatedAt: entity.updatedAt,
+  };
+}
+`;
+}
+
+function listQueryFile(n: ModuleNaming): string {
+  return `import { Filterable, ListOptions, ListRequest, Sortable } from "bazis/core/http";
+import type { ${n.entity} } from "../../model/${n.module}.model";
+
+@ListOptions({ defaultSize: 20, maxSize: 100 })
+export class ${n.module}ListQuery extends ListRequest<${n.entity}> {
+  @Sortable()
+  @Filterable("eq", "contains", "startsWith")
+  name!: string;
+
+  @Sortable()
+  @Filterable("eq", "contains")
+  email!: string;
+
+  @Sortable()
+  createdAt!: Date;
+}
+`;
+}
+
+function statsReporterFile(n: ModuleNaming): string {
+  return `import { Background, PeriodicBackgroundService } from "bazis/core/background";
+import type { ServiceProvider } from "bazis/core/di";
+import type { Logger } from "bazis/core/kernel";
+import { I${n.module}Service } from "../services/I${n.module}.service";
+
+@Background({ intervalMs: 60_000, runImmediately: false })
+export class ${n.module}Reporter extends PeriodicBackgroundService {
+  constructor(
+    private readonly provider: ServiceProvider,
+    private readonly logger: Logger,
+  ) {
+    super();
+  }
+
+  protected override async tick(signal: AbortSignal): Promise<void> {
+    const scope = this.provider.createScope();
+    try {
+      const service = scope.resolve(I${n.module}Service);
+      const count = await service.count();
+      if (!signal.aborted) {
+        this.logger.info("${n.route}: records in database", { count });
+      }
+    } finally {
+      await scope.dispose();
+    }
+  }
+}
+`;
+}
+
+function aiContractsFile(n: ModuleNaming): string {
+  return `import { Validator } from "bazis/library/validation";
+
+export class Prepare${n.module}BriefRequest {
+  @Validator({ required: true, minLength: 3 })
+  topic!: string;
+
+  @Validator({ required: true, minLength: 3 })
+  audience = "operators";
+}
+
+export class ${n.module}BriefDocument {
+  title = "";
+  bullets: string[] = [];
+}
+`;
+}
+
+function aiToolFile(n: ModuleNaming): string {
+  return `import { Tool, type AgentToolExecutionContext } from "bazis/core/agent";
+import { Validator } from "bazis/library/validation";
+import type { I${n.module}Service } from "../../services/I${n.module}.service";
+
+export class ${n.module}SummaryToolInput {
+  @Validator({ required: true, minLength: 3 })
+  topic!: string;
+}
+
+export class ${n.module}SummaryToolOutput {
+  topic = "";
+  count = 0;
+  names: string[] = [];
+  agentName = "";
+}
+
+@Tool({
+  name: "${n.route}.summary",
+  description: "Reads the ${n.route} summary through ${n.module}Service.",
+  input: ${n.module}SummaryToolInput,
+  output: ${n.module}SummaryToolOutput,
+  sideEffect: "read",
+})
+export class ${n.module}SummaryTool {
+  constructor(private readonly ${n.collection}: I${n.module}Service) {}
+
+  async execute(input: ${n.module}SummaryToolInput, context: AgentToolExecutionContext): Promise<${n.module}SummaryToolOutput> {
+    const summary = await this.${n.collection}.summary();
+    return Object.assign(new ${n.module}SummaryToolOutput(), {
+      topic: input.topic,
+      count: summary.count,
+      names: [...summary.names],
+      agentName: context.agentName ?? "",
+    });
+  }
+}
+`;
+}
+
+function agentFile(n: ModuleNaming): string {
+  return `import { Agent, Task, agentOutput } from "bazis/core/agent";
+import { Prepare${n.module}BriefRequest, ${n.module}BriefDocument } from "../contracts/${n.module}.brief";
+import { ${n.module}SummaryTool } from "../tools/${n.module}Summary.tool";
+
+@Agent({
+  name: "${n.route}-analyst",
+  role: "${n.route} analyst",
+  sections: [
+    {
+      kind: "developer",
+      content: "Write short, concrete operational summaries of the ${n.route} domain.",
+    },
+    {
+      kind: "tool-policy",
+      content: "Use read tools before the final summary. Do not make up data.",
+    },
+  ],
+  tools: [${n.module}SummaryTool],
+  modelProfile: "reasoning",
+  maxSteps: 3,
+})
+export class ${n.module}AnalystAgent {
+  @Task({
+    name: "prepare-${n.route}-brief",
+    description: "Prepare a short ${n.route} summary from the current module data.",
+    input: Prepare${n.module}BriefRequest,
+    output: ${n.module}BriefDocument,
+    modelProfile: "reasoning",
+    maxSteps: 3,
+  })
+  prepareBrief(_input: Prepare${n.module}BriefRequest): ${n.module}BriefDocument {
+    return agentOutput();
+  }
+}
+`;
+}