kavoru 0.8.8 → 0.8.10

package/README.md

@@ -47,7 +47,7 @@ During setup you can pick which integrations to scaffold. Core is always include
 | ID          | Feature                |
 | ----------- | ---------------------- |
 | `auth`      | JWT authentication     |
-| `prisma`    | Prisma + PostgreSQL    |
+| `postgres`  | PostgreSQL + Prisma (includes Docker Postgres) |
 | `otel`      | OpenTelemetry          |
 | `sentry`    | Sentry + Spotlight     |
 | `kafka`     | Kafka producer/consumer|
@@ -55,6 +55,7 @@ During setup you can pick which integrations to scaffold. Core is always include
 | `resend`    | Resend email           |
 | `cron`      | Cron jobs              |
 | `docker`    | Dockerfile + Compose     |
+| `cli`       | Project CLI (`kavoru module`, bin, scaffolds) |
 
 Interactive mode (TTY) shows a checkbox menu (↑↓ move, Space toggle, Enter confirm). Non-interactive runs use the full stack unless you pass flags.
 
@@ -71,7 +72,7 @@ bunx kavoru@latest .
 bunx kavoru@latest my-api --minimal
 
 # Pick specific features
-bunx kavoru@latest my-api --features auth,prisma,otel,sentry
+bunx kavoru@latest my-api --features auth,postgres,otel,sentry
 
 # Full stack minus Kafka and Docker
 bunx kavoru@latest my-api --no-features kafka,docker

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kavoru",
-  "version": "0.8.8",
+  "version": "0.8.10",
   "description": "Scaffold a new Kavoru (Elysia + Bun) backend from the official template",
   "type": "module",
   "bin": {

package/src/args.ts

@@ -15,9 +15,13 @@ export type CliOptions = {
 
 const HELP = `\
 Usage: kavoru [options] [directory]
+       kavoru module <module-name> [options]
 
 Create a new project from the Kavoru Elysia + Bun template.
 
+Commands:
+  module <name>      Generate src/modules/<name> (routes, service, types)
+
 Arguments:
   directory          Project folder (use "." for current directory)
 
@@ -33,13 +37,15 @@ Options:
   --no-features <list>  Comma-separated features to exclude
 
 Features:
-  auth, prisma, otel, sentry, kafka, websocket, resend, cron, docker
+  auth, postgres, otel, sentry, kafka, websocket, resend, cron, docker, cli
+  (prisma is accepted as an alias for postgres; kavoru-cli for cli)
 
 Examples:
   bunx kavoru@latest my-api
   bunx kavoru@latest my-api --minimal
-  bunx kavoru@latest my-api --features auth,prisma,otel
+  bunx kavoru@latest my-api --features auth,postgres,otel
   bunx kavoru@latest my-api --no-features kafka,docker,resend
+  bunx kavoru@latest module users
 `;
 
 export function parseArgs(argv: string[]): CliOptions {

package/src/cli.ts

@@ -10,6 +10,7 @@ import {
   MINIMAL_FEATURES,
   applyFeatures,
   formatFeatureSelection,
+  normalizeFeatureSelection,
   parseFeatureExcludeList,
   parseFeatureIncludeList,
   type FeatureSelection,
@@ -72,7 +73,7 @@ export function resolveFeatureSelection(options: CliOptions): FeatureSelection {
     return parseFeatureExcludeList(options.noFeatures, ALL_FEATURES);
   }
 
-  return { ...ALL_FEATURES };
+  return normalizeFeatureSelection({ ...ALL_FEATURES });
 }
 
 async function resolveFeatureSelectionInteractive(
@@ -88,7 +89,7 @@ async function resolveFeatureSelectionInteractive(
     return fromFlags;
   }
 
-  return promptFeatureSelection(fromFlags);
+  return normalizeFeatureSelection(await promptFeatureSelection(fromFlags));
 }
 
 export async function runCli(options: CliOptions): Promise<void> {

package/src/features.ts

@@ -4,14 +4,20 @@ import { log } from "./log";
 
 export type FeatureId =
   | "auth"
-  | "prisma"
+  | "postgres"
   | "otel"
   | "sentry"
   | "kafka"
   | "websocket"
   | "resend"
   | "cron"
-  | "docker";
+  | "docker"
+  | "cli";
+
+const FEATURE_ALIASES: Record<string, FeatureId> = {
+  prisma: "postgres",
+  "kavoru-cli": "cli",
+};
 
 export type FeatureSelection = Record<FeatureId, boolean>;
 
@@ -28,9 +34,9 @@ export const FEATURES: FeatureDef[] = [
     description: "Bearer auth, sign-in route, protected routes",
   },
   {
-    id: "prisma",
-    label: "Prisma + PostgreSQL",
-    description: "Prisma 7 config, migrations, seed scripts",
+    id: "postgres",
+    label: "PostgreSQL",
+    description: "Docker Postgres, Prisma 7, migrations, and seed",
   },
   {
     id: "otel",
@@ -67,6 +73,11 @@ export const FEATURES: FeatureDef[] = [
     label: "Docker",
     description: "Dockerfile and Docker Compose stack",
   },
+  {
+    id: "cli",
+    label: "Project CLI",
+    description: "kavoru module command, bin, and module scaffolds",
+  },
 ];
 
 export const FEATURE_IDS = FEATURES.map((feature) => feature.id);
@@ -88,7 +99,7 @@ const FEATURE_PATHS: Record<FeatureId, string[]> = {
     "src/constants/jwt.ts",
     "src/models/schemas/signin.ts",
   ],
-  prisma: ["prisma.config.ts", "src/infra/prisma"],
+  postgres: ["prisma.config.ts", "src/infra/prisma"],
   otel: ["src/infra/telemetry"],
   sentry: [
     "src/infra/sentry",
@@ -109,13 +120,20 @@ const FEATURE_PATHS: Record<FeatureId, string[]> = {
   resend: ["src/infra/resend"],
   cron: ["src/schedules"],
   docker: ["docker-compose.yaml", "docker"],
+  cli: [
+    "bin/kavoru.js",
+    "scripts/kavoru-cli.ts",
+    "scripts/generate-module.ts",
+    "__tests__/generate-module.test.ts",
+    "__tests__/kavoru-cli.test.ts",
+  ],
 };
 
 const FEATURE_DEPENDENCIES: Partial<
   Record<FeatureId, { dependencies?: string[]; devDependencies?: string[] }>
 > = {
   auth: { dependencies: ["@elysiajs/bearer", "@elysiajs/jwt"] },
-  prisma: {
+  postgres: {
     dependencies: ["@prisma/adapter-pg", "@prisma/client"],
     devDependencies: ["prisma"],
   },
@@ -136,9 +154,43 @@ const FEATURE_DEPENDENCIES: Partial<
 const FEATURE_SCRIPTS: Partial<Record<FeatureId, string[]>> = {
   otel: ["otel:view", "otel:tui"],
   sentry: ["sentry:spotlight"],
-  prisma: ["seed"],
+  postgres: ["seed"],
+  cli: ["kavoru", "module"],
 };
 
+function resolveFeatureId(raw: string): FeatureId | null {
+  const id = FEATURE_ALIASES[raw] ?? raw;
+  return FEATURE_IDS.includes(id as FeatureId) ? (id as FeatureId) : null;
+}
+
+export function toPostgresName(packageName: string): string {
+  const normalized = packageName
+    .replace(/-/g, "_")
+    .replace(/[^a-z0-9_]/gi, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_|_$/g, "");
+  return normalized || "app";
+}
+
+export function buildDatabaseUrl(
+  packageName: string,
+  host: string,
+  port = 5432,
+): string {
+  const name = toPostgresName(packageName);
+  return `postgresql://${name}:${name}@${host}:${port}/${name}`;
+}
+
+export function normalizeFeatureSelection(
+  selection: FeatureSelection,
+): FeatureSelection {
+  const next = { ...selection };
+  if (next.postgres) {
+    next.docker = true;
+  }
+  return next;
+}
+
 function enabledFeatures(selection: FeatureSelection): FeatureId[] {
   return FEATURE_IDS.filter((id) => selection[id]);
 }
@@ -159,9 +211,7 @@ export function parseFeatureIncludeList(input: string): FeatureSelection {
     .map((part) => part.trim())
     .filter(Boolean);
 
-  const unknown = requested.filter(
-    (id) => !FEATURE_IDS.includes(id as FeatureId),
-  );
+  const unknown = requested.filter((part) => resolveFeatureId(part) === null);
   if (unknown.length > 0) {
     throw new Error(
       `Unknown feature(s): ${unknown.join(", ")}. Valid: ${FEATURE_IDS.join(", ")}`,
@@ -169,8 +219,12 @@ export function parseFeatureIncludeList(input: string): FeatureSelection {
   }
 
   const selection = { ...MINIMAL_FEATURES };
-  for (const id of requested) {
-    selection[id as FeatureId] = true;
+  for (const part of requested) {
+    const id = resolveFeatureId(part);
+    if (id) selection[id] = true;
+  }
+  if (selection.postgres) {
+    selection.docker = true;
   }
   return selection;
 }
@@ -183,13 +237,14 @@ export function parseFeatureExcludeList(
   const unknown: string[] = [];
 
   for (const raw of excluded) {
-    const id = raw.trim().toLowerCase();
-    if (!id) continue;
-    if (!FEATURE_IDS.includes(id as FeatureId)) {
-      unknown.push(id);
+    const part = raw.trim().toLowerCase();
+    if (!part) continue;
+    const id = resolveFeatureId(part);
+    if (!id) {
+      unknown.push(part);
       continue;
     }
-    selection[id as FeatureId] = false;
+    selection[id] = false;
   }
 
   if (unknown.length > 0) {
@@ -198,6 +253,10 @@ export function parseFeatureExcludeList(
     );
   }
 
+  if (!selection.docker) {
+    selection.postgres = false;
+  }
+
   return selection;
 }
 
@@ -349,11 +408,17 @@ export function buildEntryIndex(selection: FeatureSelection): string {
   return [...imports, ...body].join("\n");
 }
 
-async function patchEntryIndex(projectDir: string, selection: FeatureSelection) {
+async function patchEntryIndex(
+  projectDir: string,
+  selection: FeatureSelection,
+) {
   await writeText(projectDir, "src/index.ts", buildEntryIndex(selection));
 }
 
-async function patchServerIndex(projectDir: string, selection: FeatureSelection) {
+async function patchServerIndex(
+  projectDir: string,
+  selection: FeatureSelection,
+) {
   const relativePath = "src/server/index.ts";
   const current = await readText(projectDir, relativePath);
   if (!current) return;
@@ -396,6 +461,7 @@ async function patchPackageJson(
   if (!(await pkgFile.exists())) return;
 
   const pkg = (await pkgFile.json()) as {
+    bin?: Record<string, string>;
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;
     scripts?: Record<string, string>;
@@ -422,10 +488,14 @@ async function patchPackageJson(
     }
   }
 
-  if (!selection.prisma && pkg.scripts) {
+  if (!selection.postgres && pkg.scripts) {
     pkg.scripts.start = "bun run src/index.ts";
   }
 
+  if (!selection.cli) {
+    delete pkg.bin;
+  }
+
   await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 }
 
@@ -435,9 +505,11 @@ export function buildEnvExample(
 ): string {
   const lines = ["NODE_ENV=development", "PORT=3131", ""];
 
-  if (selection.prisma) {
+  if (selection.postgres) {
     lines.push(
-      "DATABASE_URL=postgresql://user:password@localhost:5432/your_database",
+      "# Start database: docker compose up -d postgres",
+      "# Host dev uses published port; Docker app overrides host in docker/app/.env",
+      `DATABASE_URL=${buildDatabaseUrl(packageName, "localhost")}`,
       "",
     );
   }
@@ -507,7 +579,10 @@ async function patchEnvExample(
   await writeText(projectDir, ".env", content);
 }
 
-async function patchDockerfile(projectDir: string, selection: FeatureSelection) {
+async function patchDockerfile(
+  projectDir: string,
+  selection: FeatureSelection,
+) {
   if (!selection.docker) return;
 
   const relativePath = "docker/app/Dockerfile";
@@ -515,14 +590,19 @@ async function patchDockerfile(projectDir: string, selection: FeatureSelection)
   if (!current) return;
 
   let content = current;
-  if (!selection.prisma) {
+  if (!selection.postgres) {
     content = content.replace(/^\s*COPY prisma\.config\.ts \.\/.*\n/m, "");
+    content = content.replace(/^\s*RUN bunx prisma generate\n/m, "");
     content = content.replace(
-      /^\s*# generate only needs the schema on disk, not a live database\n/m,
+      /^COPY docker\/app\/docker-entrypoint\.sh .*$\n/m,
       "",
     );
     content = content.replace(
-      /^\s*RUN if \[ -f src\/infra\/prisma\/schemas\/schema\.prisma \]; then bunx prisma generate; fi\n/m,
+      /^RUN sed -i 's\/\\r\$\/\/' \/app\/docker-entrypoint\.sh && chmod \+x \/app\/docker-entrypoint\.sh\n/m,
+      "",
+    );
+    content = content.replace(
+      /^ENTRYPOINT \["\/bin\/sh", "\/app\/docker-entrypoint\.sh"\]\n/m,
       "",
     );
   }
@@ -552,11 +632,25 @@ const DOCKER_OTEL_ENV =
 const DOCKER_SPOTLIGHT_ENV =
   "# Official Spotlight image; add overrides here if needed.\n";
 
-function buildDockerAppEnv(selection: FeatureSelection): string {
+function buildDockerPostgresEnv(packageName: string): string {
+  const name = toPostgresName(packageName);
+  return `POSTGRES_USER=${name}
+POSTGRES_PASSWORD=${name}
+POSTGRES_DB=${name}
+`;
+}
+
+function buildDockerAppEnv(
+  selection: FeatureSelection,
+  packageName: string,
+): string {
   const lines = [
     "# Docker-only overrides (loaded after root .env)",
     "NODE_ENV=production",
   ];
+  if (selection.postgres) {
+    lines.push(`DATABASE_URL=${buildDatabaseUrl(packageName, "postgres")}`);
+  }
   if (selection.kafka) {
     lines.push("KAFKA_BROKERS=kafka:9092");
   }
@@ -569,11 +663,45 @@ function buildDockerAppEnv(selection: FeatureSelection): string {
   return `${lines.join("\n")}\n`;
 }
 
+function buildAppDependsOn(selection: FeatureSelection): string {
+  const deps: string[] = [];
+  if (selection.postgres) {
+    deps.push(`      postgres:
+        condition: service_healthy`);
+  }
+  if (selection.kafka) {
+    deps.push(`      kafka:
+        condition: service_started`);
+  }
+  if (deps.length === 0) return "";
+  return `    depends_on:
+${deps.join("\n")}
+`;
+}
+
 function generateDockerCompose(selection: FeatureSelection): string {
-  const appDependsOn = selection.kafka
-    ? `    depends_on:
-      kafka:
-        condition: service_started
+  const appDependsOn = buildAppDependsOn(selection);
+
+  const postgresService = selection.postgres
+    ? `
+  postgres:
+    build:
+      context: docker/postgres
+    hostname: postgres
+    ports:
+      - "\${POSTGRES_PORT:-5432}:5432"
+    env_file:
+      - docker/postgres/.env
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    networks:
+      - app_network
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
 `
     : "";
 
@@ -631,7 +759,7 @@ function generateDockerCompose(selection: FeatureSelection): string {
       target: build
       args:
         PORT: \${PORT:-3131}
-    command: /app/server
+    command: ./server
     volumes:
       - ./src:/app/src
     networks:
@@ -644,27 +772,35 @@ function generateDockerCompose(selection: FeatureSelection): string {
       - "\${PORT:-3131}:\${PORT:-3131}"
     restart: unless-stopped
     env_file:
-      - .env
+      - path: .env
+        required: false
       - docker/app/.env
 ${appDependsOn}    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:\${PORT}/healthz"]
+      test: ["CMD", "curl", "-f", "http://localhost:\${PORT:-3131}/healthz"]
       interval: 600s
       timeout: 300s
       retries: 1
-      start_period: 40s
-${kafkaService}${otelService}${spotlightService}
+      start_period: 90s
+${postgresService}${kafkaService}${otelService}${spotlightService}
 networks:
   app_network:
     driver: bridge
-`;
+${selection.postgres ? "\nvolumes:\n  postgres_data:\n" : ""}`;
 }
 
 async function patchDockerCompose(
   projectDir: string,
   selection: FeatureSelection,
+  packageName: string,
 ) {
   if (!selection.docker) return;
 
+  if (!selection.postgres) {
+    await removePaths(projectDir, [
+      "docker/postgres",
+      "docker/app/docker-entrypoint.sh",
+    ]);
+  }
   if (!selection.kafka) {
     await removePaths(projectDir, ["docker/kafka"]);
   }
@@ -678,8 +814,15 @@ async function patchDockerCompose(
   await writeText(
     projectDir,
     "docker/app/.env",
-    buildDockerAppEnv(selection),
+    buildDockerAppEnv(selection, packageName),
   );
+  if (selection.postgres) {
+    await writeText(
+      projectDir,
+      "docker/postgres/.env",
+      buildDockerPostgresEnv(packageName),
+    );
+  }
   if (selection.kafka) {
     await writeText(projectDir, "docker/kafka/.env", DOCKER_KAFKA_ENV);
   }
@@ -689,7 +832,11 @@ async function patchDockerCompose(
   if (selection.sentry) {
     await writeText(projectDir, "docker/spotlight/.env", DOCKER_SPOTLIGHT_ENV);
   }
-  await writeText(projectDir, "docker-compose.yaml", generateDockerCompose(selection));
+  await writeText(
+    projectDir,
+    "docker-compose.yaml",
+    generateDockerCompose(selection),
+  );
 }
 
 export async function applyFeatures(
@@ -710,7 +857,7 @@ export async function applyFeatures(
   await patchPackageJson(projectDir, selection);
   await patchEnvExample(projectDir, selection, packageName);
   await patchDockerfile(projectDir, selection);
-  await patchDockerCompose(projectDir, selection);
+  await patchDockerCompose(projectDir, selection, packageName);
 
   if (disabled.length > 0) {
     log.success("Feature selection applied");

package/src/index.ts

@@ -3,10 +3,23 @@
 import { parseArgs, printHelp, printVersion } from "./args";
 import { runCli } from "./cli";
 import { log } from "./log";
+import { printModuleHelp, runModuleCommand } from "./module-cli";
 
 async function main(): Promise<void> {
   try {
-    const options = parseArgs(process.argv.slice(2));
+    const argv = process.argv.slice(2);
+
+    if (argv[0] === "module") {
+      if (argv.includes("-h") || argv.includes("--help")) {
+        printModuleHelp();
+        return;
+      }
+
+      await runModuleCommand(argv.slice(1));
+      return;
+    }
+
+    const options = parseArgs(argv);
 
     if (options.help) {
       printHelp();

package/src/module-cli.ts

@@ -0,0 +1,79 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { log } from "./log";
+
+function findProjectRoot(cwd: string): string {
+  let current = path.resolve(cwd);
+
+  while (true) {
+    const packageJson = path.join(current, "package.json");
+    const localCli = path.join(current, "scripts/kavoru-cli.ts");
+    const moduleScript = path.join(current, "scripts/generate-module.ts");
+    if (
+      existsSync(packageJson) &&
+      (existsSync(localCli) || existsSync(moduleScript))
+    ) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+
+  throw new Error(
+    "Could not find a Kavoru project with the Project CLI enabled. Scaffold with the cli feature or run from a project that includes scripts/kavoru-cli.ts.",
+  );
+}
+
+export async function runModuleCommand(argv: string[]): Promise<void> {
+  const force = argv.includes("--force") || argv.includes("-f");
+  const name = argv.find((arg) => !arg.startsWith("-"));
+
+  if (!name) {
+    throw new Error("Usage: kavoru module <module-name> [--force]");
+  }
+
+  const projectDir = findProjectRoot(process.cwd());
+  const localCli = path.join(projectDir, "scripts/kavoru-cli.ts");
+  const scriptPath = existsSync(localCli)
+    ? localCli
+    : path.join(projectDir, "scripts/generate-module.ts");
+  const cmd = existsSync(localCli)
+    ? ["bun", scriptPath, "module", name]
+    : ["bun", scriptPath, name];
+  if (force) cmd.push("--force");
+
+  log.info(`Generating module "${name}" in ${projectDir}`);
+
+  const proc = Bun.spawn(cmd, {
+    cwd: projectDir,
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    process.exit(exitCode ?? 1);
+  }
+}
+
+export function printModuleHelp(): void {
+  console.log(`\
+Usage: kavoru module <module-name> [options]
+
+Generate a feature module under src/modules/<module-name>/ with:
+  routes.ts, service.ts, types.ts
+
+Options:
+  -f, --force   Overwrite an existing module folder
+  -h, --help    Show help
+
+Examples:
+  kavoru module users
+  kavoru module user-profile --force
+  bun run kavoru module billing
+`);
+}

package/src/prompts.ts

@@ -3,6 +3,7 @@ import {
   ALL_FEATURES,
   FEATURES,
   MINIMAL_FEATURES,
+  normalizeFeatureSelection,
   type FeatureId,
   type FeatureSelection,
   formatFeatureSelection,
@@ -154,6 +155,12 @@ export async function promptFeatureSelection(
           const feature = FEATURES[activeIndex];
           if (!feature) break;
           selection[feature.id as FeatureId] = !selection[feature.id as FeatureId];
+          if (feature.id === "postgres" && selection.postgres) {
+            selection.docker = true;
+          }
+          if (feature.id === "docker" && !selection.docker) {
+            selection.postgres = false;
+          }
           lineCount = renderCheckboxMenu(selection, activeIndex, lineCount);
           break;
         }
@@ -166,6 +173,7 @@ export async function promptFeatureSelection(
           lineCount = renderCheckboxMenu(selection, activeIndex, lineCount);
           break;
         case "confirm":
+          Object.assign(selection, normalizeFeatureSelection(selection));
           restoreTerminal(onData);
           stdout.write("\n");
           resolve(selection);