kavoru 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# kavoru (CLI)
+
+Scaffold a new [Kavoru](https://github.com/mertthesamael/Kavoru) backend — ElysiaJS, Bun, TypeScript, Prisma, and the full production starter stack.
+
+## Usage
+
+After publishing to npm:
+
+```bash
+bunx kavoru my-api
+cd my-api
+bun run dev
+```
+
+Equivalent to `bunx --bun kavoru` (Bun runs the `kavoru` binary from the npm package).
+
+### Options
+
+| Flag | Description |
+| --- | --- |
+| `-h, --help` | Show help |
+| `-V, --version` | Show CLI version |
+| `-f, --force` | Scaffold into a non-empty directory |
+| `--no-install` | Skip `bun install` |
+| `--repo owner/name` | Override template repo (default: `mertthesamael/Kavoru`) |
+| `--branch name` | Template branch (default: `master`) |
+
+### Examples
+
+```bash
+# Interactive (prompts for project name)
+bunx kavoru
+
+# Current directory
+bunx kavoru .
+
+# Custom template fork (local dev)
+bunx kavoru demo --repo your-user/Kavoru --no-install
+```
+
+## Development
+
+```bash
+cd elysia-template-initializer
+bun install
+bun test
+
+# Run locally without publishing
+bun run src/index.ts my-test-app
+# or
+bun link
+bunx kavoru my-test-app
+```
+
+## Publish to npm
+
+1. Ensure the [Kavoru](https://github.com/mertthesamael/Kavoru) template repo is public on `master`.
+2. Create a **Granular Access Token** at [npm → Access Tokens](https://www.npmjs.com/settings/~/tokens) with:
+   - **Bypass two-factor authentication** — checked (required for first publish without 2FA)
+   - **Packages** — All packages, **Read and write**
+3. Configure auth (do not commit the token):
+
+   ```bash
+   echo "//registry.npmjs.org/:_authToken=YOUR_TOKEN" > ~/.npmrc
+   unset NPM_CONFIG_TOKEN
+   npm whoami
+   ```
+
+4. Publish: `npm publish` (or `bun publish`)
+
+The `bin/kavoru.js` shim uses `#!/usr/bin/env bun` so `bunx kavoru` runs with Bun.
+
+## What the CLI does
+
+1. Shallow-clones the GitHub template (or downloads a zip if `git` is missing)
+2. Removes `.git` so the new project starts fresh
+3. Sets `package.json` `name`, copies `.env` from `.env.example`, and adjusts default service IDs
+4. Runs `bun install` (unless `--no-install`)
+
+## License
+
+MIT

package/bin/kavoru.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+
+import "../src/index.ts";

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "kavoru",
+  "version": "0.1.0",
+  "description": "Scaffold a new Kavoru (Elysia + Bun) backend from the official template",
+  "type": "module",
+  "bin": {
+    "kavoru": "bin/kavoru.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "test": "bun test"
+  },
+  "keywords": [
+    "elysia",
+    "elysiajs",
+    "bun",
+    "scaffold",
+    "template",
+    "kavoru"
+  ],
+  "author": "https://github.com/mertthesamael",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mertthesamael/kavoru-cli.git"
+  },
+  "homepage": "https://github.com/mertthesamael/Kavoru",
+  "bugs": {
+    "url": "https://github.com/mertthesamael/Kavoru/issues"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/src/args.ts

@@ -0,0 +1,100 @@
+import { PACKAGE_VERSION } from "./constants";
+
+export type CliOptions = {
+  targetDir: string | undefined;
+  help: boolean;
+  version: boolean;
+  install: boolean;
+  force: boolean;
+  repo: string;
+  branch: string;
+};
+
+const HELP = `\
+Usage: kavoru [options] [directory]
+
+Create a new project from the Kavoru Elysia + Bun template.
+
+Arguments:
+  directory          Project folder (use "." for current directory)
+
+Options:
+  -h, --help         Show help
+  -V, --version      Show version
+  -f, --force        Overwrite / use a non-empty target directory
+  --no-install       Skip "bun install" after scaffolding
+  --repo <owner/name>  GitHub template repo (default: mertthesamael/Kavoru)
+  --branch <name>    Template branch (default: master)
+
+Examples:
+  bunx kavoru my-api
+  bunx kavoru .
+`;
+
+export function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = {
+    targetDir: undefined,
+    help: false,
+    version: false,
+    install: true,
+    force: false,
+    repo: "mertthesamael/Kavoru",
+    branch: "master",
+  };
+
+  const positional: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg) continue;
+
+    switch (arg) {
+      case "-h":
+      case "--help":
+        options.help = true;
+        break;
+      case "-V":
+      case "--version":
+        options.version = true;
+        break;
+      case "-f":
+      case "--force":
+        options.force = true;
+        break;
+      case "--no-install":
+        options.install = false;
+        break;
+      case "--repo": {
+        const value = argv[++i];
+        if (!value) throw new Error("--repo requires a value (owner/name).");
+        options.repo = value;
+        break;
+      }
+      case "--branch": {
+        const value = argv[++i];
+        if (!value) throw new Error("--branch requires a value.");
+        options.branch = value;
+        break;
+      }
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`Unknown option: ${arg}`);
+        }
+        positional.push(arg);
+    }
+  }
+
+  if (positional[0]) {
+    options.targetDir = positional[0];
+  }
+
+  return options;
+}
+
+export function printHelp(): void {
+  console.log(HELP.trim());
+}
+
+export function printVersion(): void {
+  console.log(PACKAGE_VERSION);
+}

package/src/cli.ts

@@ -0,0 +1,111 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, readdir, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import type { CliOptions } from "./args";
+import { log } from "./log";
+import {
+  customizeProject,
+  fetchTemplate,
+  installDependencies,
+  removeGitMetadata,
+  resolveTemplateSource,
+} from "./template";
+import {
+  assertValidPackageName,
+  isDirectoryEmpty,
+  toPackageName,
+} from "./validate";
+
+async function promptProjectName(): Promise<string> {
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question("Project name: ");
+    const name = toPackageName(answer);
+    if (!name) {
+      throw new Error("Project name cannot be empty.");
+    }
+    return name;
+  } finally {
+    rl.close();
+  }
+}
+
+async function copyTemplateIntoTarget(
+  tempDir: string,
+  targetDir: string,
+): Promise<void> {
+  await mkdir(targetDir, { recursive: true });
+  const entries = await readdir(tempDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    await cp(
+      path.join(tempDir, entry.name),
+      path.join(targetDir, entry.name),
+      { recursive: true, force: true },
+    );
+  }
+}
+
+export async function runCli(options: CliOptions): Promise<void> {
+  let targetArg = options.targetDir;
+
+  if (!targetArg) {
+    const interactive = process.stdin.isTTY && process.stdout.isTTY;
+    if (!interactive) {
+      throw new Error("Missing project directory. Usage: bunx kavoru <directory>");
+    }
+    targetArg = await promptProjectName();
+  }
+
+  const isCurrentDir = targetArg === ".";
+  const packageName = isCurrentDir
+    ? toPackageName(path.basename(process.cwd()))
+    : toPackageName(path.basename(targetArg));
+
+  assertValidPackageName(packageName);
+
+  const targetDir = isCurrentDir
+    ? process.cwd()
+    : path.resolve(process.cwd(), targetArg);
+
+  if (existsSync(targetDir) && !options.force && !isDirectoryEmpty(targetDir)) {
+    throw new Error(
+      `Target directory "${targetDir}" is not empty. Use --force to scaffold anyway.`,
+    );
+  }
+
+  const source = resolveTemplateSource(options.repo, options.branch);
+  const tempDir = path.join(os.tmpdir(), `kavoru-${Date.now()}`);
+
+  log.info(`Creating Kavoru project "${packageName}"`);
+
+  try {
+    await fetchTemplate(source, tempDir);
+    await removeGitMetadata(tempDir);
+    await customizeProject(tempDir, packageName);
+    await copyTemplateIntoTarget(tempDir, targetDir);
+
+    if (options.install) {
+      await installDependencies(targetDir);
+    }
+  } finally {
+    await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+  }
+
+  log.success(`Project ready at ${targetDir}`);
+  console.log();
+  console.log("Next steps:");
+  if (!isCurrentDir) {
+    console.log(`  cd ${targetArg}`);
+  }
+  if (!options.install) {
+    console.log("  bun install");
+  }
+  console.log("  bun run dev");
+  console.log();
+  console.log("  API:     http://localhost:3131");
+  console.log("  OpenAPI: http://localhost:3131/help");
+}

package/src/constants.ts

@@ -0,0 +1,8 @@
+export const PACKAGE_VERSION = "0.1.0";
+
+export const TEMPLATE_REPO = "mertthesamael/Kavoru";
+export const TEMPLATE_BRANCH = "master";
+
+export const TEMPLATE_GIT_URL = `https://github.com/${TEMPLATE_REPO}.git`;
+
+export const TEMPLATE_ZIP_URL = `https://github.com/${TEMPLATE_REPO}/archive/refs/heads/${TEMPLATE_BRANCH}.zip`;

package/src/index.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env bun
+
+import { parseArgs, printHelp, printVersion } from "./args";
+import { runCli } from "./cli";
+import { log } from "./log";
+
+async function main(): Promise<void> {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+
+    if (options.help) {
+      printHelp();
+      return;
+    }
+
+    if (options.version) {
+      printVersion();
+      return;
+    }
+
+    await runCli(options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    log.error(message);
+    process.exit(1);
+  }
+}
+
+await main();

package/src/log.ts

@@ -0,0 +1,24 @@
+const reset = "\x1b[0m";
+const dim = "\x1b[2m";
+const cyan = "\x1b[36m";
+const green = "\x1b[32m";
+const yellow = "\x1b[33m";
+const red = "\x1b[31m";
+
+export const log = {
+  info(message: string) {
+    console.log(`${cyan}◆${reset} ${message}`);
+  },
+  step(message: string) {
+    console.log(`${dim}…${reset} ${message}`);
+  },
+  success(message: string) {
+    console.log(`${green}✔${reset} ${message}`);
+  },
+  warn(message: string) {
+    console.warn(`${yellow}!${reset} ${message}`);
+  },
+  error(message: string) {
+    console.error(`${red}✖${reset} ${message}`);
+  },
+};

package/src/template.ts

@@ -0,0 +1,172 @@
+import { cp, mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { TEMPLATE_BRANCH } from "./constants";
+import { log } from "./log";
+
+export type TemplateSource = {
+  repo: string;
+  branch: string;
+};
+
+function gitUrl(repo: string): string {
+  return `https://github.com/${repo}.git`;
+}
+
+function zipUrl(repo: string, branch: string): string {
+  return `https://github.com/${repo}/archive/refs/heads/${branch}.zip`;
+}
+
+async function commandExists(command: string): Promise<boolean> {
+  const which = process.platform === "win32" ? "where" : "which";
+  const proc = Bun.spawn([which, command], { stdout: "pipe", stderr: "ignore" });
+  const code = await proc.exited;
+  return code === 0;
+}
+
+async function runCommand(cmd: string[], cwd?: string): Promise<void> {
+  const proc = Bun.spawn(cmd, {
+    cwd,
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  const code = await proc.exited;
+  if (code !== 0) {
+    throw new Error(`Command failed (${code}): ${cmd.join(" ")}`);
+  }
+}
+
+async function cloneWithGit(
+  source: TemplateSource,
+  targetDir: string,
+): Promise<void> {
+  await runCommand([
+    "git",
+    "clone",
+    "--depth",
+    "1",
+    "--branch",
+    source.branch,
+    gitUrl(source.repo),
+    targetDir,
+  ]);
+}
+
+async function downloadZip(
+  source: TemplateSource,
+  targetDir: string,
+): Promise<void> {
+  const url = zipUrl(source.repo, source.branch);
+  const repoName = source.repo.split("/")[1] ?? "template";
+  const extractedFolder = `${repoName}-${source.branch}`;
+
+  log.step(`Downloading ${url}`);
+
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download template (${response.status}): ${url}`);
+  }
+
+  const buffer = await response.arrayBuffer();
+  const stamp = Date.now();
+  const zipPath = path.join(path.dirname(targetDir), `.kavoru-${stamp}.zip`);
+  const extractDir = path.join(path.dirname(targetDir), `.kavoru-${stamp}-extract`);
+
+  await mkdir(path.dirname(targetDir), { recursive: true });
+  await Bun.write(zipPath, buffer);
+
+  try {
+    await mkdir(extractDir, { recursive: true });
+
+    if (process.platform === "win32") {
+      await runCommand([
+        "powershell",
+        "-NoProfile",
+        "-Command",
+        `Expand-Archive -Path '${zipPath.replace(/'/g, "''")}' -DestinationPath '${extractDir.replace(/'/g, "''")}' -Force`,
+      ]);
+    } else {
+      await runCommand(["tar", "-xf", zipPath, "-C", extractDir]);
+    }
+
+    const extractedRoot = path.join(extractDir, extractedFolder);
+    await cp(extractedRoot, targetDir, { recursive: true });
+  } finally {
+    await rm(zipPath, { force: true }).catch(() => undefined);
+    await rm(extractDir, { recursive: true, force: true }).catch(() => undefined);
+  }
+}
+
+export async function fetchTemplate(
+  source: TemplateSource,
+  targetDir: string,
+): Promise<void> {
+  await mkdir(path.dirname(targetDir), { recursive: true });
+
+  if (await commandExists("git")) {
+    log.step(`Cloning ${source.repo} (${source.branch})`);
+    await cloneWithGit(source, targetDir);
+    return;
+  }
+
+  log.warn("git not found — downloading template as zip");
+  await downloadZip(source, targetDir);
+}
+
+export async function removeGitMetadata(projectDir: string): Promise<void> {
+  await rm(path.join(projectDir, ".git"), { recursive: true, force: true });
+}
+
+export async function customizeProject(
+  projectDir: string,
+  packageName: string,
+): Promise<void> {
+  const pkgPath = path.join(projectDir, "package.json");
+  const pkgFile = Bun.file(pkgPath);
+  if (!(await pkgFile.exists())) {
+    throw new Error("Template is missing package.json");
+  }
+
+  const pkg = (await pkgFile.json()) as Record<string, unknown>;
+  pkg.name = packageName;
+  await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+
+  const envExamplePath = path.join(projectDir, ".env.example");
+  const envExample = Bun.file(envExamplePath);
+  if (await envExample.exists()) {
+    let envText = await envExample.text();
+    envText = envText
+      .replace(/^OTEL_SERVICE_NAME=kavoru$/m, `OTEL_SERVICE_NAME=${packageName}`)
+      .replace(/^KAFKA_CLIENT_ID=kavoru$/m, `KAFKA_CLIENT_ID=${packageName}`)
+      .replace(
+        /^KAFKA_GROUP_ID=kavoru-consumer$/m,
+        `KAFKA_GROUP_ID=${packageName}-consumer`,
+      );
+    await Bun.write(envExamplePath, envText);
+    await Bun.write(path.join(projectDir, ".env"), envText);
+  }
+
+  const modulesIndex = path.join(projectDir, "src", "modules", "index.ts");
+  const modulesFile = Bun.file(modulesIndex);
+  if (await modulesFile.exists()) {
+    const text = await modulesFile.text();
+    const title = packageName
+      .replace(/-/g, " ")
+      .replace(/\b\w/g, (char) => char.toUpperCase());
+    await Bun.write(
+      modulesIndex,
+      text.replace('title: "🦊 Kavoru"', `title: "🦊 ${title}"`),
+    );
+  }
+}
+
+export async function installDependencies(projectDir: string): Promise<void> {
+  log.step("Installing dependencies (bun install)");
+  await runCommand(["bun", "install"], projectDir);
+}
+
+export function resolveTemplateSource(
+  repo: string,
+  branch: string,
+): TemplateSource {
+  return { repo, branch: branch || TEMPLATE_BRANCH };
+}

package/src/validate.ts

@@ -0,0 +1,34 @@
+import { readdirSync } from "node:fs";
+
+const NPM_NAME_RE = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9][a-z0-9-._~]*$/;
+
+export function toPackageName(input: string): string {
+  return input
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-._~@/]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function assertValidPackageName(name: string): void {
+  if (!name) {
+    throw new Error("Project name cannot be empty.");
+  }
+  if (!NPM_NAME_RE.test(name)) {
+    throw new Error(
+      `"${name}" is not a valid package name. Use lowercase letters, numbers, hyphens, or dots.`,
+    );
+  }
+}
+
+export function isDirectoryEmpty(dir: string): boolean {
+  try {
+    const entries = readdirSync(dir);
+    const ignored = new Set([".git", ".gitignore"]);
+    return entries.every((entry) => ignored.has(entry));
+  } catch {
+    return true;
+  }
+}