bazis 0.96.1

package/cli/generateProject.ts

@@ -0,0 +1,183 @@
+import path from "node:path";
+import { copyFile, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { parseModuleName } from "./naming";
+
+export interface GenerateProjectOptions {
+  readonly name: string;
+  /** Exact destination directory; defaults to ./<kebab-name>. */
+  readonly outputPath?: string;
+  /** Local Bazis package source; defaults to this checkout's src/bazis. */
+  readonly frameworkPath?: string;
+  /** Opt into a live link to the source checkout instead of a portable snapshot. */
+  readonly linkFramework?: boolean;
+  readonly dryRun?: boolean;
+}
+
+export interface GenerateProjectResult {
+  readonly projectDir: string;
+  /** Application scaffold files; framework sources are summarized separately. */
+  readonly files: readonly string[];
+  readonly dryRun: boolean;
+  readonly frameworkMode: "snapshot" | "link";
+  readonly frameworkFileCount: number;
+}
+
+/** Create a separate application without mutating the framework checkout. */
+export async function generateProject(options: GenerateProjectOptions): Promise<GenerateProjectResult> {
+  const name = parseModuleName(options.name).folder;
+  const requested = path.resolve(options.outputPath ?? name);
+  const parent = await realpath(path.dirname(requested)).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") throw new Error(`Parent directory does not exist: ${path.dirname(requested)}. Create it first or choose another --path.`);
+    throw error;
+  });
+  const parentInfo = await lstat(parent);
+  if (!parentInfo.isDirectory()) throw new Error(`Project parent is not a directory: ${parent}`);
+  const projectDir = path.join(parent, path.basename(requested));
+  if (await exists(projectDir)) throw new Error(`Project path already exists: ${projectDir}`);
+
+  const frameworkDir = await resolveFramework(options.frameworkPath);
+  if (projectDir.startsWith(`${frameworkDir}${path.sep}`)) {
+    throw new Error("Project directory must be outside the Bazis package.");
+  }
+  const dependencyPath = path.relative(projectDir, frameworkDir).replaceAll("\\", "/");
+  const frameworkMode = options.linkFramework ? "link" : "snapshot";
+  const frameworkFiles = options.linkFramework ? [] : await collectFrameworkFiles(frameworkDir);
+  const dependency = options.linkFramework
+    ? `file:${dependencyPath.startsWith(".") ? dependencyPath : `./${dependencyPath}`}`
+    : "file:./vendor/bazis";
+  const files = buildProjectFiles(name, dependency, frameworkMode);
+  if (!options.dryRun) {
+    const staged = await mkdtemp(path.join(parent, `.${name}.bazis-`));
+    try {
+      for (const [relative, content] of files) {
+        const output = path.join(staged, relative);
+        await mkdir(path.dirname(output), { recursive: true });
+        await writeFile(output, content, { encoding: "utf8", flag: "wx" });
+      }
+      for (const relative of frameworkFiles) {
+        const output = path.join(staged, "vendor/bazis", relative);
+        await mkdir(path.dirname(output), { recursive: true });
+        await copyFile(path.join(frameworkDir, relative), output);
+      }
+      if (await exists(projectDir)) throw new Error(`Project path appeared during generation: ${projectDir}`);
+      await rename(staged, projectDir);
+    } catch (error) {
+      await rm(staged, { recursive: true, force: true });
+      throw error;
+    }
+  }
+  return { projectDir, files: files.map(([relative]) => path.join(projectDir, relative)), dryRun: options.dryRun === true,
+    frameworkMode, frameworkFileCount: frameworkFiles.length };
+}
+
+/** Package sources only: do not carry checkout state, dependencies or test fixtures. */
+async function collectFrameworkFiles(directory: string): Promise<string[]> {
+  const files: string[] = [];
+  const excluded = new Set(["node_modules", "test", "tests", "__tests__"]);
+  const visit = async (relative: string): Promise<void> => {
+    const file = path.join(directory, relative);
+    const info = await lstat(file);
+    if (info.isSymbolicLink()) throw new Error(`Framework snapshot cannot include a symbolic link: ${relative}`);
+    if (info.isDirectory()) {
+      for (const entry of (await readdir(file)).sort()) {
+        // Same contents as the npm package: no tests, fixtures or internal passports.
+        if (entry.startsWith(".") || excluded.has(entry) || entry === "MODULE.md" || /\.(test|spec)\.[^.]+$/.test(entry) || entry.endsWith(".bun-build")) continue;
+        await visit(path.join(relative, entry));
+      }
+    } else if (info.isFile()) files.push(relative);
+    else throw new Error(`Unsupported framework package entry: ${relative}`);
+  };
+  for (const entry of ["index.ts", "package.json", "core", "library", "cli"]) await visit(entry);
+  // MIT requires the license text to travel with every copy of the package.
+  for (const entry of ["LICENSE", "README.md"]) if (await exists(path.join(directory, entry))) await visit(entry);
+  return files;
+}
+
+async function resolveFramework(requested?: string): Promise<string> {
+  const candidates = requested === undefined
+    ? [path.resolve("src/bazis"), path.resolve(import.meta.dir, "..")]
+    : [path.resolve(requested)];
+  for (const candidate of candidates) {
+    let directory: string;
+    try { directory = await realpath(candidate); } catch { continue; }
+    const info = await lstat(path.join(directory, "package.json")).catch(() => undefined);
+    if (!info?.isFile()) continue;
+    try {
+      const manifest = JSON.parse(await readFile(path.join(directory, "package.json"), "utf8"));
+      const required = await Promise.all(["index.ts", "cli/main.ts", "core/scripts/di-generate.ts"]
+        .map((file) => lstat(path.join(directory, file)).then((entry) => entry.isFile()).catch(() => false)));
+      if (manifest.name === "bazis" && required.every(Boolean)) {
+        return directory;
+      }
+    } catch { /* Try the next candidate. */ }
+  }
+  throw new Error("Local Bazis package not found. Pass --framework <path-to-src/bazis>.");
+}
+
+async function exists(file: string): Promise<boolean> {
+  try { await lstat(file); return true; }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function buildProjectFiles(name: string, dependency: string, frameworkMode: "snapshot" | "link"): readonly (readonly [string, string])[] {
+  const manifest = {
+    name, version: "0.1.0", private: true, type: "module",
+    scripts: {
+      "codegen": "bazis codegen",
+      "dev": "bazis dev",
+      "test": "bazis test",
+      "build": "bazis build",
+      "build:bin": "bazis build --bin",
+      "start": `./bin/${name}`,
+    },
+    dependencies: { bazis: dependency },
+    devDependencies: { "@types/bun": "1.4.0", typescript: "^5" },
+  };
+  const tsconfig = {
+    compilerOptions: {
+      target: "ESNext", module: "ESNext", moduleResolution: "bundler", lib: ["ESNext"],
+      types: ["bun"], strict: true, noUncheckedIndexedAccess: true, noImplicitOverride: true,
+      skipLibCheck: true, noEmit: true,
+    },
+    include: ["src/**/*"],
+  };
+  const codegen = { version: 1, defaultTarget: "production", targets: { production: { entrypoints: ["src/index.ts"] } } };
+  return [
+    ["package.json", `${JSON.stringify(manifest, null, 2)}\n`],
+    ["tsconfig.json", `${JSON.stringify(tsconfig, null, 2)}\n`],
+    ["bazis.config.json", `${JSON.stringify(codegen, null, 2)}\n`],
+    [".gitignore", "node_modules/\nbin/\nsrc/generated/\n.env\n"],
+    [".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"],
+    ["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\nAn [bazis](https://www.npmjs.com/package/bazis) application. ${frameworkMode === "snapshot"
+      ? "The framework package is copied to `vendor/bazis`; keep it in Git and move it with the project. The framework checkout is no longer needed. Framework updates do not reach this copy automatically."
+      : "The `bazis` dependency links an external local checkout (`--link-framework`). Moving the project needs the same package and an updated path in `package.json`."}\nRead the [local architecture](docs/architecture/MODULE_ARCHITECTURE.md) before changing modules.\n\nNeeds Bun ≥ 1.4.0. Settings go to \`.env\` (example: \`.env.example\`).\n\n\`\`\`sh\nbun install\nbunx bazis dev\n# GET http://127.0.0.1:3000/health\n# If the port is busy: PORT=3100 bunx bazis dev\n\`\`\`\n\nAdd an atomic module from the project root: \`bunx bazis g module Task --empty\`.\nAfter filling in its passport and implementation, run \`bunx bazis codegen\`.\nTests: \`bunx bazis test\`. Typecheck: \`bunx bazis build\`. Binary: \`bunx bazis build --bin\`, run it with \`bun run start\`.\n\n\`--minimal\` creates a sample CRUD with paging (20 records by default, at most 100 over HTTP); it needs a database provider and a schema to run. The service returns \`PageResult\`; the HTTP controller builds JSON:API. \`DbContext.saveChanges()\` saves every change of its context. In ORM predicates combine conditions with \`.and()\` and \`.or()\`; codegen rejects \`&&\` and \`||\` between predicates.\n`],
+  ];
+}
+
+const HEALTH_TEST = `import { expect, test } from "bun:test";
+
+// Starts the app from source exactly as \`bazis dev\` does and checks /health.
+test("app starts and answers /health", async () => {
+  const port = String(20000 + Math.floor(Math.random() * 20000));
+  const app = Bun.spawn([process.execPath, "run", "src/index.ts"], { env: { ...process.env, HOST: "127.0.0.1", PORT: port }, stdout: "ignore", stderr: "inherit" });
+  try {
+    let status = 0;
+    for (let attempt = 0; attempt < 100 && status !== 200; attempt++) {
+      await Bun.sleep(100);
+      status = await fetch(\`http://127.0.0.1:\${port}/health\`).then((response) => response.status, () => 0);
+    }
+    expect(status).toBe(200);
+  } finally {
+    app.kill();
+    await app.exited;
+  }
+});
+`;

package/cli/main.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env bun
+import { generateModule, generateModulePack } from "./generateModule";
+import { parseCliArgs } from "./parseCli";
+import { runCodegen } from "./codegen";
+import { generateProject } from "./generateProject";
+import { runBuild, runDev, runTest } from "./build";
+
+export const USAGE = `Usage:
+  bazis new <Name> [options]                  Create a new application project
+  bazis g module <Name> [options]             Atomic module (alias: m)
+  bazis g pack <Name> --parts <a,b> [options] Composite module (aliases: p, module-pack)
+  bazis codegen [--target <name|all>]         Generate DI wiring into src/generated/bazis
+  bazis dev [--watch]                         Codegen, then run the app from source with
+                                             BAZIS_ENV=development (unless set);
+                                             --watch reruns both when src/ changes
+  bazis test [<bun test args>]                Codegen, then bun test
+  bazis build                                 Codegen and typecheck
+  bazis build --bin [--outfile <path>]        Also compile a standalone executable (default bin/<name>)
+  bazis --help
+  g can also be written as generate.
+
+Generation options:
+  --path <directory>    Exact project directory (new only; default: ./<name>)
+  --framework <path>    Local bazis package directory (new only)
+  --link-framework      Link that checkout instead of copying vendor/bazis (new only)
+  --modules-root <path>  Modules root (default: src/app/modules)
+  --app-module <path>    Host module (default: {modules-root}/App.module.ts)
+  --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;
+                        uses src/app/modules/auth helpers when the project has them.
+                        To run, the host needs a cache (runApp({ cache: memory() }))
+                        and a database provider. Legacy alias: --enterprise
+  --parts <a,b,...>      Independent empty atomic parts; pack only, at least two
+  --dry-run             Validate and list planned changes without writing
+  --no-register         Skip host registration and automatic codegen
+  --no-codegen          Generate and register without running codegen
+  --target <name|all>    Codegen target (default: project's default target)
+  --force               Overwrite scaffold files, including MODULE.md
+  -h, --help            Show help at any position without changing files
+
+Examples (from the project root):
+  bunx bazis new MyApp --dry-run
+  bunx bazis new MyApp
+  bunx bazis g module Task --dry-run
+  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 codegen --target production
+  bunx bazis dev --watch
+  bunx bazis test
+  bunx bazis build --bin
+
+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>;
+}
+
+const defaultRuntime: CliRuntime = {
+  log: (message) => console.log(message),
+  error: (message) => console.error(message),
+  codegen: runCodegen,
+};
+
+export async function runCli(argv: readonly string[], runtime: CliRuntime = defaultRuntime): Promise<number> {
+  const parsed = parseCliArgs(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;
+  }
+  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 }, runtime.codegen, runtime.log);
+    if (parsed.kind === "new") {
+      const result = await generateProject({ name: parsed.name, outputPath: parsed.outputPath, frameworkPath: parsed.frameworkPath, linkFramework: parsed.linkFramework, 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 === "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,
+    };
+    const result = args.generator === "pack"
+      ? await generateModulePack({ ...options, parts: args.parts })
+      : await generateModule({ ...options, profile: args.profile });
+    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 di:generate...");
+    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;
+  } catch (error) {
+    runtime.error(`[bazis] ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}
+
+if (import.meta.main) process.exitCode = await runCli(Bun.argv.slice(2));

package/cli/moduleRegistration.ts

@@ -0,0 +1,127 @@
+import path from "node:path";
+import ts from "typescript";
+
+interface Edit { readonly at: number; readonly text: string }
+
+export function moduleImportPath(fromFile: string, moduleFile: string): string {
+  const relative = path.relative(path.dirname(fromFile), moduleFile).split(path.sep).join("/").replace(/\.ts$/, "");
+  return relative.startsWith(".") ? relative : `./${relative}`;
+}
+
+/** Edits only the import and the selected @Module metadata, preserving other source text. */
+export function registerModuleInSource(content: string, appFile: string, moduleFile: string, moduleClass: string): string {
+  const diagnostics = ts.transpileModule(content, { fileName: appFile, reportDiagnostics: true }).diagnostics ?? [];
+  if (diagnostics.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)) {
+    throw new Error(`Cannot register a module in invalid TypeScript: ${appFile}`);
+  }
+  const source = ts.createSourceFile(appFile, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const importPath = moduleImportPath(appFile, moduleFile);
+  const eol = content.includes("\r\n") ? "\r\n" : "\n";
+  const imports = source.statements.filter(ts.isImportDeclaration);
+  const decoratorNames = new Set(["Module"]);
+  const decoratorNamespaces = new Set<string>();
+  let binding = moduleClass;
+  let imported = false;
+  const otherBindings = new Set<string>();
+  for (const declaration of imports) {
+    const clause = declaration.importClause;
+    if (!clause || !ts.isStringLiteral(declaration.moduleSpecifier)) continue;
+    const specifier = declaration.moduleSpecifier.text;
+    const isDI = /(?:bazis|bazis|@)\/core\/di$/.test(specifier);
+    if (clause.name) otherBindings.add(clause.name.text);
+    const named = clause.namedBindings;
+    if (named && ts.isNamespaceImport(named)) {
+      otherBindings.add(named.name.text);
+      if (isDI) decoratorNamespaces.add(named.name.text);
+    }
+    if (!named || !ts.isNamedImports(named)) continue;
+    for (const item of named.elements) {
+      const exported = item.propertyName?.text ?? item.name.text;
+      if (isDI && exported === "Module") decoratorNames.add(item.name.text);
+      const sameFile = specifier.startsWith(".") && path.resolve(path.dirname(appFile), specifier.replace(/\.(?:ts|js)$/, "")) === moduleFile.replace(/\.ts$/, "");
+      if (sameFile && exported === moduleClass) {
+        if (clause.isTypeOnly || item.isTypeOnly) throw new Error(`${moduleClass} has a type-only import; use a value import before registration.`);
+        binding = item.name.text;
+        imported = true;
+      } else {
+        otherBindings.add(item.name.text);
+      }
+    }
+  }
+  for (const statement of source.statements) {
+    if ((ts.isClassDeclaration(statement) || ts.isFunctionDeclaration(statement) || ts.isEnumDeclaration(statement)) && statement.name) {
+      otherBindings.add(statement.name.text);
+    }
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name)) otherBindings.add(declaration.name.text);
+      }
+    }
+  }
+  if (otherBindings.has(binding)) throw new Error(`Cannot register ${moduleClass}: local name ${binding} is already in use.`);
+
+  const candidates: { name?: string; metadata: ts.ObjectLiteralExpression }[] = [];
+  for (const statement of source.statements.filter(ts.isClassDeclaration)) {
+    for (const decorator of ts.getDecorators(statement) ?? []) {
+      const call = decorator.expression;
+      if (!ts.isCallExpression(call)) continue;
+      const expression = call.expression;
+      const isModule = (ts.isIdentifier(expression) && decoratorNames.has(expression.text))
+        || (ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.expression)
+          && decoratorNamespaces.has(expression.expression.text) && expression.name.text === "Module");
+      if (!isModule) continue;
+      const metadata = call.arguments[0];
+      if (!metadata || !ts.isObjectLiteralExpression(metadata)) throw new Error("@Module metadata must be an object literal for automatic registration.");
+      candidates.push({ name: statement.name?.text, metadata });
+    }
+  }
+  const candidate = candidates.find((item) => item.name === "AppModule") ?? (candidates.length === 1 ? candidates[0] : undefined);
+  if (!candidate) throw new Error("Could not select a unique @Module class for registration in App.module.ts.");
+  const metadata = candidate.metadata;
+  if (metadata.properties.some(ts.isSpreadAssignment)) throw new Error("Automatic registration does not support spread @Module metadata; register the module explicitly.");
+  if (metadata.properties.some((property) => property.name && ts.isComputedPropertyName(property.name))) throw new Error("Automatic registration does not support computed @Module properties; register the module explicitly.");
+  const importProperties = metadata.properties.filter((property) => property.name && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) && property.name.text === "imports");
+  if (importProperties.length > 1) throw new Error("Duplicate imports properties in @Module metadata.");
+  const property = importProperties[0];
+  const edits: Edit[] = [];
+  if (property) {
+    if (!ts.isPropertyAssignment(property) || !ts.isArrayLiteralExpression(property.initializer)) {
+      throw new Error("@Module imports must be an array literal for automatic registration.");
+    }
+    const array = property.initializer;
+    if (array.elements.some(ts.isOmittedExpression)) throw new Error("@Module imports contains an empty element; fix the array before registration.");
+    if (!array.elements.some((element) => ts.isIdentifier(element) && element.text === binding)) {
+      appendMember(content, array, array.elements, binding, edits, eol);
+    }
+  } else {
+    appendMember(content, metadata, metadata.properties, `imports: [${binding}]`, edits, eol);
+  }
+  if (!imported) {
+    const lastImport = imports.at(-1);
+    const end = lastImport?.end ?? 0;
+    const nextLine = content.indexOf("\n", end);
+    const hasLineEnd = lastImport && nextLine >= 0 && /^\s*(?:\/\/.*)?$/.test(content.slice(end, nextLine));
+    const at = hasLineEnd ? nextLine + 1 : end;
+    edits.push({ at, text: `${at > 0 && content[at - 1] !== "\n" ? eol : ""}import { ${moduleClass} } from "${importPath}";${eol}` });
+  }
+  return edits.reverse().sort((left, right) => right.at - left.at).reduce((text, edit) => text.slice(0, edit.at) + edit.text + text.slice(edit.at), content);
+}
+
+function appendMember(content: string, node: ts.Node, members: ts.NodeArray<ts.Node>, member: string, edits: Edit[], eol: string): void {
+  const close = node.end - 1;
+  const last = members.at(-1);
+  if (last && !members.hasTrailingComma) edits.push({ at: last.end, text: "," });
+  const inner = content.slice(node.getStart() + 1, close);
+  if (!inner.includes("\n")) {
+    edits.push({ at: close, text: `${last || inner.trim() ? " " : ""}${member}${members.hasTrailingComma ? "," : ""}` });
+    return;
+  }
+  const lineStart = content.lastIndexOf("\n", close) + 1;
+  const closingIndent = content.slice(lineStart, close);
+  if (/^\s*$/.test(closingIndent)) {
+    edits.push({ at: lineStart, text: `${closingIndent}  ${member},${eol}` });
+  } else {
+    const indent = content.slice(content.lastIndexOf("\n", node.getStart()) + 1, node.getStart()).match(/^\s*/)?.[0] ?? "";
+    edits.push({ at: close, text: `${eol}${indent}  ${member},${eol}${indent}` });
+  }
+}

package/cli/naming.ts

@@ -0,0 +1,124 @@
+/** Parsed module name for scaffold file/class naming. */
+export interface ModuleNaming {
+  /** CLI input as given (trimmed). */
+  readonly input: string;
+  /** Folder under `modules/` — lowercase as given (`users`, `order-items`). */
+  readonly folder: string;
+  /** PascalCase name as given (`Users`, `OrderItems`): module class and file. */
+  readonly module: string;
+  /** PascalCase singular entity (`User`, `OrderItem`). */
+  readonly entity: string;
+  /** HTTP route segment, usually plural (`users`, `order-items`). */
+  readonly route: string;
+  /** DbContext collection property (`users`, `orderItems`). */
+  readonly collection: string;
+  /** `{Module}Module` class name (`UsersModule`). */
+  readonly moduleClass: string;
+  /** API list base path segment (`/api/users`). */
+  readonly apiBasePath: string;
+  /** PostgreSQL schema (module folder name, `-` → `_`). */
+  readonly dbSchema: string;
+}
+
+const SINGULAR_TO_PLURAL: Readonly<Record<string, string>> = {
+  person: "people",
+  child: "children",
+  man: "men",
+  woman: "women",
+  status: "statuses",
+  bus: "buses",
+  analysis: "analyses",
+};
+
+const PLURAL_TO_SINGULAR: Readonly<Record<string, string>> = Object.freeze(
+  Object.fromEntries(Object.entries(SINGULAR_TO_PLURAL).map(([singular, plural]) => [plural, singular])),
+);
+
+/**
+ * Converts the CLI name into scaffold names. The module keeps the name as given
+ * (`Users` → `UsersModule`, `Users.module.ts`); the CRUD entity is singular (`User`).
+ */
+export function parseModuleName(raw: string): ModuleNaming {
+  const input = raw.trim();
+  if (input.length === 0) {
+    throw new Error("Module name is required.");
+  }
+  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.`);
+  }
+
+  const parts = input
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .toLowerCase()
+    .split("-")
+    .filter((part) => part.length > 0);
+
+  const folder = parts.join("-");
+  const module = pascal(parts);
+  const singular = toSingular(parts);
+  const entity = pascal(singular);
+  const route = toRoute(singular);
+  const collection = toCamelPlural(singular);
+
+  return {
+    input,
+    folder,
+    module,
+    entity,
+    route,
+    collection,
+    moduleClass: `${module}Module`,
+    apiBasePath: `/api/${route}`,
+    dbSchema: folder.replace(/-/g, "_"),
+  };
+}
+
+function pascal(parts: readonly string[]): string {
+  return parts.map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+
+function toSingular(parts: readonly string[]): readonly string[] {
+  if (parts.length === 0) {
+    return parts;
+  }
+  const last = parts[parts.length - 1] as string;
+  const lower = last.toLowerCase();
+
+  if (Object.hasOwn(PLURAL_TO_SINGULAR, lower)) {
+    return [...parts.slice(0, -1), PLURAL_TO_SINGULAR[lower] as string];
+  }
+  if (lower.endsWith("ies") && lower.length > 3) {
+    return [...parts.slice(0, -1), `${lower.slice(0, -3)}y`];
+  }
+  if (/(?:ches|shes|xes|zes|sses)$/.test(lower)) {
+    return [...parts.slice(0, -1), lower.slice(0, -2)];
+  }
+  if (lower.endsWith("s") && lower.length > 1 && !/(?:ss|us|is)$/.test(lower)) {
+    return [...parts.slice(0, -1), lower.slice(0, -1)];
+  }
+  return parts;
+}
+
+function toRoute(parts: readonly string[]): string {
+  const last = parts[parts.length - 1] as string;
+  const lower = last.toLowerCase();
+
+  if (Object.hasOwn(SINGULAR_TO_PLURAL, lower)) {
+    return [...parts.slice(0, -1), SINGULAR_TO_PLURAL[lower] as string].join("-");
+  }
+  if (/[^aeiou]y$/.test(lower)) {
+    return [...parts.slice(0, -1), `${lower.slice(0, -1)}ies`].join("-");
+  }
+  if (/(?:s|x|z|ch|sh)$/.test(lower)) {
+    return [...parts.slice(0, -1), `${lower}es`].join("-");
+  }
+  return [...parts.slice(0, -1), `${lower}s`].join("-");
+}
+
+function toCamelPlural(parts: readonly string[]): string {
+  const routeParts = toRoute(parts).split("-");
+  return routeParts
+    .map((part, index) => (index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)))
+    .join("");
+}