kavoru 0.8.12 → 0.9.2

package/README.md

@@ -51,6 +51,7 @@ During setup you can pick which integrations to scaffold. Core is always include
 | `otel`      | OpenTelemetry          |
 | `sentry`    | Sentry + Spotlight     |
 | `kafka`     | Kafka producer/consumer|
+| `redis`     | Redis cache + CRUD API |
 | `websocket` | WebSocket realtime     |
 | `resend`    | Resend email           |
 | `cron`      | Cron jobs              |

package/package.json

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

package/src/args.ts

@@ -37,7 +37,7 @@ Options:
   --no-features <list>  Comma-separated features to exclude
 
 Features:
-  auth, postgres, otel, sentry, kafka, websocket, resend, cron, docker, cli
+  auth, postgres, otel, sentry, kafka, redis, websocket, resend, cron, docker, cli
   (prisma is accepted as an alias for postgres; kavoru-cli for cli)
 
 Examples:

package/src/cli.ts

@@ -155,10 +155,12 @@ export async function runCli(options: CliOptions): Promise<void> {
     console.log("  bun install");
   }
   if (featureSelection.cli) {
+    console.log("  ./kavoru module <name>        # Git Bash / macOS / Linux");
+    console.log("  .\\kavoru.cmd module <name>   # Windows cmd / PowerShell");
     if (!options.install) {
-      console.log("  bun run link-cli       # optional: put kavoru on PATH");
+      console.log("  bun run link-cli              # bare kavoru on PATH (~/.bun/bin)");
     }
-    console.log("  kavoru module <name>   # generate modules");
+    console.log("  bunx kavoru@latest module <name>  # works without PATH setup");
   }
   console.log("  bunx kavoru@latest <dir>  # scaffold another project");
   console.log("  bun run dev");

package/src/features.ts

@@ -8,6 +8,7 @@ export type FeatureId =
   | "otel"
   | "sentry"
   | "kafka"
+  | "redis"
   | "websocket"
   | "resend"
   | "cron"
@@ -53,6 +54,11 @@ export const FEATURES: FeatureDef[] = [
     label: "Kafka",
     description: "Producer, consumer, and example HTTP endpoints",
   },
+  {
+    id: "redis",
+    label: "Redis",
+    description: "Cache client and CRUD HTTP endpoints",
+  },
   {
     id: "websocket",
     label: "WebSockets",
@@ -112,6 +118,12 @@ const FEATURE_PATHS: Record<FeatureId, string[]> = {
     "src/models/schemas/kafka.ts",
     "__tests__/kafka.test.ts",
   ],
+  redis: [
+    "src/modules/redis",
+    "src/infra/redis",
+    "src/models/schemas/redis.ts",
+    "__tests__/redis.test.ts",
+  ],
   websocket: [
     "src/modules/realtime",
     "src/models/schemas/realtime.ts",
@@ -126,8 +138,10 @@ const FEATURE_PATHS: Record<FeatureId, string[]> = {
     "kavoru.cmd",
     "scripts/kavoru-cli.ts",
     "scripts/generate-module.ts",
+    "scripts/generate-repository.ts",
     "scripts/link-cli.ts",
     "__tests__/generate-module.test.ts",
+    "__tests__/generate-repository.test.ts",
     "__tests__/kavoru-cli.test.ts",
     "__tests__/link-cli.test.ts",
   ],
@@ -151,6 +165,7 @@ const FEATURE_DEPENDENCIES: Partial<
   },
   sentry: { dependencies: ["@sentry/elysia"] },
   kafka: { dependencies: ["kafkajs"] },
+  redis: { dependencies: ["ioredis"] },
   resend: { dependencies: ["resend"] },
   cron: { dependencies: ["@elysiajs/cron"] },
 };
@@ -185,6 +200,14 @@ export function buildDatabaseUrl(
   return `postgresql://${name}:${name}@${host}:${port}/${name}`;
 }
 
+export function buildRedisCredentials(packageName: string): {
+  username: string;
+  password: string;
+} {
+  const name = toPostgresName(packageName);
+  return { username: name, password: name };
+}
+
 export function normalizeFeatureSelection(
   selection: FeatureSelection,
 ): FeatureSelection {
@@ -340,6 +363,8 @@ async function patchModulesIndex(
 }
 
 export function buildEntryIndex(selection: FeatureSelection): string {
+  const needsAsyncStartup = selection.kafka || selection.redis;
+
   const imports = [
     selection.sentry
       ? 'import { initSentry, flushSentry } from "./infra/sentry";'
@@ -350,9 +375,12 @@ export function buildEntryIndex(selection: FeatureSelection): string {
     selection.kafka
       ? 'import { startKafka, stopKafka } from "./infra/kafka";'
       : null,
+    selection.redis
+      ? 'import { connectRedis, stopRedis } from "./infra/redis";'
+      : null,
     'import { HttpServer } from "./server/index";',
     'import { logger } from "./common/logger";',
-    selection.kafka ? 'import { InternalServerError } from "elysia";' : null,
+    needsAsyncStartup ? 'import { InternalServerError } from "elysia";' : null,
   ].filter(Boolean) as string[];
 
   const body: string[] = [];
@@ -366,14 +394,18 @@ export function buildEntryIndex(selection: FeatureSelection): string {
 
   body.push("", "const server = new HttpServer();", "");
 
-  if (selection.kafka) {
+  if (needsAsyncStartup) {
+    const startupCalls: string[] = [];
+    if (selection.kafka) startupCalls.push("    await startKafka();");
+    if (selection.redis) startupCalls.push("    await connectRedis();");
+
     body.push(
       "void server.start().then(async () => {",
       "  try {",
-      "    await startKafka();",
+      ...startupCalls,
       "  } catch (error) {",
-      '    logger.error("Failed to start Kafka", { error });',
-      '    throw new InternalServerError("Failed to start Kafka");',
+      '    logger.error("Failed to start infrastructure", { error });',
+      '    throw new InternalServerError("Failed to start infrastructure");',
       "  }",
       "});",
     );
@@ -392,6 +424,9 @@ export function buildEntryIndex(selection: FeatureSelection): string {
   if (selection.kafka) {
     body.push("    await stopKafka();");
   }
+  if (selection.redis) {
+    body.push("    await stopRedis();");
+  }
   if (selection.sentry) {
     body.push("    await flushSentry();");
   }
@@ -498,8 +533,13 @@ async function patchPackageJson(
 
   if (!selection.cli) {
     delete pkg.bin;
+    if (pkg.scripts?.postinstall === "bun scripts/link-cli.ts") {
+      delete pkg.scripts.postinstall;
+    }
   } else {
     pkg.bin = { kavoru: "./bin/kavoru.js" };
+    pkg.scripts ??= {};
+    pkg.scripts.postinstall = "bun scripts/link-cli.ts";
   }
 
   await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
@@ -561,6 +601,19 @@ export function buildEnvExample(
     );
   }
 
+  if (selection.redis) {
+    const { username, password } = buildRedisCredentials(packageName);
+    lines.push(
+      "# Redis (enabled by default in development; disabled in test)",
+      "# Start server: docker compose up -d redis",
+      "# REDIS_ENABLED=false",
+      "REDIS_URL=redis://localhost:6379",
+      `REDIS_USERNAME=${username}`,
+      `REDIS_PASSWORD=${password}`,
+      "",
+    );
+  }
+
   if (selection.resend) {
     lines.push(
       "# Resend (disabled when RESEND_API_KEY is unset; always disabled in test)",
@@ -613,9 +666,25 @@ async function patchDockerfile(
     );
   }
 
+  if (!selection.cli) {
+    content = content.replace(/^COPY bin \.\/bin\n/m, "");
+    content = content.replace(
+      /^COPY scripts\/link-cli\.ts \.\/scripts\/link-cli\.ts\n/m,
+      "",
+    );
+    content = content.replace(/^ENV PATH="\/root\/\.bun\/bin:\$\{PATH\}"\n/m, "");
+  }
+
   await writeText(projectDir, relativePath, content);
 }
 
+function buildDockerRedisEnv(packageName: string): string {
+  const { username, password } = buildRedisCredentials(packageName);
+  return `REDIS_USERNAME=${username}
+REDIS_PASSWORD=${password}
+`;
+}
+
 const DOCKER_KAFKA_ENV = `# KRaft broker config (Confluent cp-kafka 7.6.1)
 CLUSTER_ID=MkU3OEVBNTcwNTJENDM2Qk
 KAFKA_NODE_ID=0
@@ -660,6 +729,12 @@ function buildDockerAppEnv(
   if (selection.kafka) {
     lines.push("KAFKA_BROKERS=kafka:9092");
   }
+  if (selection.redis) {
+    const { username, password } = buildRedisCredentials(packageName);
+    lines.push("REDIS_URL=redis://redis:6379");
+    lines.push(`REDIS_USERNAME=${username}`);
+    lines.push(`REDIS_PASSWORD=${password}`);
+  }
   if (selection.otel) {
     lines.push("OTEL_EXPORTER_OTLP_ENDPOINT=http://otel:4318/v1/traces");
   }
@@ -679,6 +754,10 @@ function buildAppDependsOn(selection: FeatureSelection): string {
     deps.push(`      kafka:
         condition: service_started`);
   }
+  if (selection.redis) {
+    deps.push(`      redis:
+        condition: service_healthy`);
+  }
   if (deps.length === 0) return "";
   return `    depends_on:
 ${deps.join("\n")}
@@ -727,6 +806,31 @@ function generateDockerCompose(selection: FeatureSelection): string {
 `
     : "";
 
+  const redisService = selection.redis
+    ? `
+  redis:
+    build:
+      context: docker/redis
+    hostname: redis
+    ports:
+      - "\${REDIS_PORT:-6379}:6379"
+    env_file:
+      - docker/redis/.env
+    networks:
+      - app_network
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "redis-cli --user $$REDIS_USERNAME -a $$REDIS_PASSWORD ping | grep -q PONG",
+        ]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+    restart: unless-stopped
+`
+    : "";
+
   const otelService = selection.otel
     ? `
   otel:
@@ -787,7 +891,7 @@ ${appDependsOn}    healthcheck:
       timeout: 300s
       retries: 1
       start_period: 90s
-${postgresService}${kafkaService}${otelService}${spotlightService}
+${postgresService}${kafkaService}${redisService}${otelService}${spotlightService}
 networks:
   app_network:
     driver: bridge
@@ -810,6 +914,9 @@ async function patchDockerCompose(
   if (!selection.kafka) {
     await removePaths(projectDir, ["docker/kafka"]);
   }
+  if (!selection.redis) {
+    await removePaths(projectDir, ["docker/redis"]);
+  }
   if (!selection.otel) {
     await removePaths(projectDir, ["docker/otel"]);
   }
@@ -832,6 +939,13 @@ async function patchDockerCompose(
   if (selection.kafka) {
     await writeText(projectDir, "docker/kafka/.env", DOCKER_KAFKA_ENV);
   }
+  if (selection.redis) {
+    await writeText(
+      projectDir,
+      "docker/redis/.env",
+      buildDockerRedisEnv(packageName),
+    );
+  }
   if (selection.otel) {
     await writeText(projectDir, "docker/otel/.env", DOCKER_OTEL_ENV);
   }

package/src/index.ts

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

package/src/module-cli.ts

@@ -9,9 +9,15 @@ function findProjectRoot(cwd: string): string {
     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");
+    const repositoryScript = path.join(
+      current,
+      "scripts/generate-repository.ts",
+    );
     if (
       existsSync(packageJson) &&
-      (existsSync(localCli) || existsSync(moduleScript))
+      (existsSync(localCli) ||
+        existsSync(moduleScript) ||
+        existsSync(repositoryScript))
     ) {
       return current;
     }
@@ -28,26 +34,24 @@ function findProjectRoot(cwd: string): string {
   );
 }
 
-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());
+async function runProjectScript(
+  projectDir: string,
+  command: "module" | "repository",
+  name: string,
+  force: boolean,
+): Promise<void> {
   const localCli = path.join(projectDir, "scripts/kavoru-cli.ts");
-  const scriptPath = existsSync(localCli)
-    ? localCli
-    : path.join(projectDir, "scripts/generate-module.ts");
+  const fallbackScript =
+    command === "module"
+      ? path.join(projectDir, "scripts/generate-module.ts")
+      : path.join(projectDir, "scripts/generate-repository.ts");
+
+  const scriptPath = existsSync(localCli) ? localCli : fallbackScript;
   const cmd = existsSync(localCli)
-    ? ["bun", scriptPath, "module", name]
+    ? ["bun", scriptPath, command, 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",
@@ -60,6 +64,39 @@ export async function runModuleCommand(argv: string[]): Promise<void> {
   }
 }
 
+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());
+  log.info(`Generating module "${name}" in ${projectDir}`);
+  await runProjectScript(projectDir, "module", name, force);
+}
+
+export async function runRepositoryCommand(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 repository <repository-name> [--force]");
+  }
+
+  const projectDir = findProjectRoot(process.cwd());
+  const prismaConfig = path.join(projectDir, "prisma.config.ts");
+  if (!existsSync(prismaConfig)) {
+    throw new Error(
+      "PostgreSQL/Prisma is not enabled in this project. Scaffold with the postgres feature first.",
+    );
+  }
+
+  log.info(`Generating repository "${name}" in ${projectDir}`);
+  await runProjectScript(projectDir, "repository", name, force);
+}
+
 export function printModuleHelp(): void {
   console.log(`\
 Usage: kavoru module <module-name> [options]
@@ -77,3 +114,23 @@ Examples:
   kavoru module user-profile --force
 `);
 }
+
+export function printRepositoryHelp(): void {
+  console.log(`\
+Usage: kavoru repository <repository-name> [options]
+
+Generate Prisma model + repository (requires postgres/prisma feature):
+  src/infra/prisma/schemas/<name>.prisma
+  src/infra/prisma/repositories/<name>.ts
+
+Runs bunx prisma generate when finished.
+
+Options:
+  -f, --force   Overwrite existing schema/repository files
+  -h, --help    Show help
+
+Examples:
+  kavoru repository user
+  kavoru repository billing --force
+`);
+}