deploy-bbc 1.0.0 → 1.2.0

package/CLAUDE.md

@@ -105,20 +105,86 @@ This document outlines the coding conventions and guidelines for the `create-bac
 
 ---
 
-## 📦 Type & Interface Naming
+## 📦 Type Naming & Usage
 
-### Use `PascalCase` for types, interfaces, enums, and classes
+### Use `PascalCase` for types, enums, and classes
 
 ```typescript
-✅ interface CliResults { }
+✅ type CliResults = { }
 ✅ type InstallerOptions = { }
 ✅ enum AvailablePackages { }
 ✅ class ProjectScaffold { }
 
-❌ interface cli_results { }
+❌ type cli_results = { }
 ❌ type installer_options = { }
 ```
 
+### ⚠️ ALWAYS use `type` instead of `interface`
+
+```typescript
+✅ type CliResults = {
+  appName: string;
+  flags: {
+    noGit: boolean;
+    noInstall: boolean;
+  };
+  packages: string[];
+}
+
+✅ type ScaffoldOptions = {
+  projectDir: string;
+  appName: string;
+  packages: string[];
+}
+
+❌ interface CliResults {
+  appName: string;
+  flags: {
+    noGit: boolean;
+    noInstall: boolean;
+  };
+  packages: string[];
+}
+
+❌ interface ScaffoldOptions {
+  projectDir: string;
+  appName: string;
+  packages: string[];
+}
+```
+
+**Why `type` over `interface`?**
+
+- **Consistency**: Single way to define object shapes
+- **Flexibility**: Types support unions, intersections, and mapped types more naturally
+- **Composability**: Better for complex type operations and transformations
+- **Simplicity**: One less concept to remember
+- **Modern practice**: Aligns with contemporary TypeScript patterns
+
+**Extending types:**
+
+```typescript
+✅ type BaseOptions = {
+  projectDir: string;
+  appName: string;
+}
+
+✅ type ExtendedOptions = BaseOptions & {
+  packages: string[];
+  flags: Record<string, boolean>;
+}
+
+❌ interface BaseOptions {
+  projectDir: string;
+  appName: string;
+}
+
+❌ interface ExtendedOptions extends BaseOptions {
+  packages: string[];
+  flags: Record<string, boolean>;
+}
+```
+
 ---
 
 ## 🗂️ Import/Export Conventions
@@ -163,7 +229,7 @@ import { install_dependencies } from "./install-dependencies.js";
 const DEFAULT_PROJECT_DIR = process.cwd();
 const TEMPLATE_BASE_PATH = "../templates/base";
 
-interface ScaffoldOptions {
+type ScaffoldOptions = {
   projectDir: string;
   appName: string;
   packages: string[];
@@ -247,7 +313,9 @@ To enforce these conventions, configure ESLint:
         "selector": "typeLike",
         "format": ["PascalCase"]
       }
-    ]
+    ],
+    "@typescript-eslint/consistent-type-definitions": ["error", "type"],
+    "@typescript-eslint/no-empty-interface": "error"
   }
 }
 ```
@@ -262,6 +330,7 @@ To enforce these conventions, configure ESLint:
 ❌ function createProject() { }  // camelCase function
 ❌ const project_dir = "";       // snake_case variable
 ❌ src/CreateProject.ts          // PascalCase file
+❌ interface CliResults { }      // Using interface
 ```
 
 ### ✅ Do stick to the rules
@@ -270,6 +339,7 @@ To enforce these conventions, configure ESLint:
 ✅ function create_project() { }  // snake_case function
 ✅ const projectDir = "";         // camelCase variable
 ✅ src/create-project.ts          // kebab-case file
+✅ type CliResults = { }          // Using type
 ```
 
 ---
@@ -283,9 +353,10 @@ To enforce these conventions, configure ESLint:
 | **Functions** | `snake_case` | `function create_project()` |
 | **Variables** | `camelCase` | `const projectDir` |
 | **Constants** | `SCREAMING_SNAKE_CASE` | `const MAX_RETRIES` |
-| **Types/Interfaces** | `PascalCase` | `interface CliResults` |
+| **Types** | `PascalCase` + `type` keyword | `type CliResults = { }` |
 | **Enums** | `PascalCase` | `enum AvailablePackages` |
 | **Classes** | `PascalCase` | `class ProjectScaffold` |
+| **Object Shapes** | Use `type`, NOT `interface` | `type Config = { }` |
 
 ---
 
@@ -294,10 +365,11 @@ To enforce these conventions, configure ESLint:
 When contributing to this project, please:
 
 1. ✅ Follow ALL conventions outlined in this document
-2. ✅ Run linting before committing: `bun run lint`
-3. ✅ Format code: `bun run format`
-4. ✅ Use descriptive commit messages
-5. ✅ Add JSDoc comments for exported functions
+2. ✅ Use `type` instead of `interface` for all object type definitions
+3. ✅ Run linting before committing: `bun run lint`
+4. ✅ Format code: `bun run format`
+5. ✅ Use descriptive commit messages
+6. ✅ Add JSDoc comments for exported functions
 
 ---
 
@@ -310,6 +382,7 @@ These conventions are chosen to:
 - **Reduce cognitive load** when working with multiple languages
 - **Follow industry standards** where applicable
 - **Enable better tooling support**
+- **Simplify type definitions** by using only `type` declarations
 
 ---
 
@@ -318,6 +391,7 @@ These conventions are chosen to:
 - [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)
 - [TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)
 - [File Naming Conventions](https://github.com/kettanaito/naming-cheatsheet)
+- [Types vs Interfaces](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#differences-between-type-aliases-and-interfaces)
 
 ---
 

package/cli/package.json

@@ -1,6 +1,6 @@
 {
     "name": "deploy-bbc",
-    "version": "1.0.0",
+    "version": "1.2.0",
     "description": "CLI to bootstrap production-ready backends with Bun (Best Backend Code)",
     "type": "module",
     "bin": {
@@ -38,17 +38,17 @@
         "url": "https://github.com/aritra69/deploy-bbc/issues"
     },
     "dependencies": {
-        "@clack/prompts": "^0.7.0",
-        "chalk": "^5.3.0",
-        "commander": "^11.1.0",
-        "execa": "^8.0.1",
-        "fs-extra": "^11.2.0",
-        "ora": "^7.0.1"
+        "@clack/prompts": "^0.11.0",
+        "chalk": "^5.6.2",
+        "commander": "^14.0.2",
+        "execa": "^9.6.1",
+        "fs-extra": "^11.3.3",
+        "ora": "^9.1.0"
     },
     "devDependencies": {
         "@types/bun": "latest",
         "@types/fs-extra": "^11.0.4",
-        "@types/node": "^20.10.6",
-        "typescript": "^5.3.3"
+        "@types/node": "^25.0.10",
+        "typescript": "^5.9.3"
     }
 }

package/cli/src/cli/index.ts

@@ -100,12 +100,17 @@ export const run_cli = async (): Promise<CliResults> => {
       projectName: () =>
         p.text({
           message: "What will your project be called?",
-          placeholder: "my-awesome-api",
+          placeholder: "my-awesome-api (or . for current directory)",
           defaultValue: cliProvidedName || "my-backend",
           validate: (value) => {
             if (!value) return "Please enter a project name";
-            if (!/^[a-z0-9-_]+$/i.test(value))
-              return "Only letters, numbers, dashes and underscores";
+            // Allow '.' for current directory or paths
+            if (value === "." || value.startsWith("./") || value.startsWith("../") || value.startsWith("~/")) {
+              return; // Valid path
+            }
+            // Otherwise check for valid name format
+            if (!/^[a-z0-9-_/]+$/i.test(value))
+              return "Only letters, numbers, dashes, underscores, and slashes";
           },
         }),
 

package/cli/src/helpers/log-next-steps.ts

@@ -14,22 +14,31 @@ export function log_next_steps(
   options: InstallerOptions,
   _cliResults: CliResults
 ): void {
-  const { appName, packages } = options;
+  const { appName, packages, projectDir } = options;
+
+  // Check if project was created in current directory
+  const isCurrentDirectory = projectDir === process.cwd();
 
   console.log("\n" + chalk.bold.green("✨ Project created successfully!"));
   console.log("\n" + chalk.bold("Next steps:"));
   console.log();
 
-  // Step 1: Navigate to project
-  console.log(chalk.cyan("1.") + " Navigate to your project:");
-  console.log(`   ${chalk.gray("cd")} ${appName}`);
-  console.log();
+  let stepNumber = 1;
+
+  // Step 1: Navigate to project (skip if current directory)
+  if (!isCurrentDirectory) {
+    console.log(chalk.cyan(`${stepNumber}.`) + " Navigate to your project:");
+    console.log(`   ${chalk.gray("cd")} ${appName}`);
+    console.log();
+    stepNumber++;
+  }
 
-  // Step 2: Environment variables
-  console.log(chalk.cyan("2.") + " Set up environment variables:");
+  // Step: Environment variables
+  console.log(chalk.cyan(`${stepNumber}.`) + " Set up environment variables:");
   console.log(`   ${chalk.gray("cp")} .env.example .env`);
   console.log(`   ${chalk.gray("# Edit .env with your configuration")}`);
   console.log();
+  stepNumber++;
 
   // Step 3: Docker (if database or redis selected)
   const hasDocker =
@@ -39,9 +48,10 @@ export function log_next_steps(
     packages.includes(AvailablePackages.redis);
 
   if (hasDocker) {
-    console.log(chalk.cyan("3.") + " Start Docker services:");
+    console.log(chalk.cyan(`${stepNumber}.`) + " Start Docker services:");
     console.log(`   ${chalk.gray("docker-compose up -d")}`);
     console.log();
+    stepNumber++;
   }
 
   // Step 4: Database migrations (if postgres or mysql)
@@ -50,21 +60,14 @@ export function log_next_steps(
     packages.includes(AvailablePackages.mysql);
 
   if (needsMigration) {
-    const stepNum = hasDocker ? "4" : "3";
-    console.log(chalk.cyan(`${stepNum}.`) + " Run database migrations:");
+    console.log(chalk.cyan(`${stepNumber}.`) + " Run database migrations:");
     console.log(`   ${chalk.gray("bun run db:migrate")}`);
     console.log();
+    stepNumber++;
   }
 
-  // Step 5: Start development server
-  const lastStepNum = needsMigration
-    ? hasDocker
-      ? "5"
-      : "4"
-    : hasDocker
-    ? "4"
-    : "3";
-  console.log(chalk.cyan(`${lastStepNum}.`) + " Start the development server:");
+  // Step: Start development server
+  console.log(chalk.cyan(`${stepNumber}.`) + " Start the development server:");
   console.log(`   ${chalk.gray("bun run dev")}`);
   console.log();
 

package/cli/src/helpers/scaffold-project.ts

@@ -9,10 +9,14 @@ const __dirname = path.dirname(__filename);
 
 /**
  * Scaffolds the base project structure by copying template files.
- * Creates the project directory and copies all files from templates/base/
+ * Creates the project directory and copies all files from the selected template.
+ *
+ * Special handling:
+ * - If projectDir is current directory: allows scaffolding but checks for conflicts (src/, package.json)
+ * - If projectDir is a new directory: creates it and requires it to be empty
  *
  * @param options - Installer options containing projectDir and other config
- * @throws Error if project directory already exists and is not empty
+ * @throws Error if project directory already exists and is not empty, or if conflicts detected in current directory
  */
 export async function scaffold_project(
   options: InstallerOptions
@@ -21,8 +25,10 @@ export async function scaffold_project(
   const spinner = ora("Scaffolding project...").start();
 
   try {
-    // Check if directory exists and is not empty
-    if (await fs.pathExists(projectDir)) {
+    const isCurrentDirectory = projectDir === process.cwd();
+
+    // Check if directory exists and is not empty (skip for current directory)
+    if (!isCurrentDirectory && await fs.pathExists(projectDir)) {
       const files = await fs.readdir(projectDir);
       if (files.length > 0) {
         spinner.fail(`Directory ${projectDir} already exists and is not empty`);
@@ -32,6 +38,26 @@ export async function scaffold_project(
       }
     }
 
+    // If scaffolding in current directory, check for conflicts
+    if (isCurrentDirectory) {
+      const conflictingPaths = ["src", "package.json"];
+      const conflicts = [];
+
+      for (const pathToCheck of conflictingPaths) {
+        if (await fs.pathExists(path.join(projectDir, pathToCheck))) {
+          conflicts.push(pathToCheck);
+        }
+      }
+
+      if (conflicts.length > 0) {
+        spinner.fail("Cannot scaffold in current directory");
+        throw new Error(
+          `The following files/folders already exist: ${conflicts.join(", ")}\n` +
+          "Please use an empty directory or choose a different location."
+        );
+      }
+    }
+
     // Ensure project directory exists
     await fs.ensureDir(projectDir);
 

package/cli/src/templates/base/package.json

@@ -10,8 +10,9 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
+    "dotenv": "^16.3.1",
     "hono": "^4.0.0",
-    "dotenv": "^16.3.1"
+    "zod": "^3.22.4"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/cli/src/templates/base/src/controllers/user/create-user.controller.ts

@@ -0,0 +1,84 @@
+import type { Context } from "hono";
+import { z } from "zod";
+import { user_model } from "../../models/user.model.js";
+import type { ApiResponse, ApiError } from "../../types/common/api-response.types.js";
+import type { UserResponse } from "../../types/models/user.types.js";
+
+/**
+ * Validation schema
+ */
+const create_user_schema = z.object({
+  email: z.string().email("Invalid email address"),
+  name: z.string().min(2, "Name must be at least 2 characters").max(100, "Name must not exceed 100 characters"),
+});
+
+/**
+ * Helper to format user response
+ */
+function format_user_response(user: any): UserResponse {
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    createdAt: user.createdAt.toISOString(),
+    updatedAt: user.updatedAt.toISOString(),
+  };
+}
+
+/**
+ * Create a new user
+ * POST /users
+ */
+export async function create_user(c: Context) {
+  try {
+    const body = await c.req.json();
+
+    // Validate request body
+    const validation = create_user_schema.safeParse(body);
+    if (!validation.success) {
+      return c.json<ApiError>(
+        {
+          success: false,
+          error: "Validation failed",
+          details: validation.error.errors.map((err) => ({
+            field: err.path.join("."),
+            message: err.message,
+          })),
+        },
+        400
+      );
+    }
+
+    // Check if email already exists
+    const existing_user = await user_model.find_by_email(validation.data.email);
+    if (existing_user) {
+      return c.json<ApiError>(
+        {
+          success: false,
+          error: "User with this email already exists",
+        },
+        409
+      );
+    }
+
+    // Create user
+    const user = await user_model.create(validation.data);
+
+    return c.json<ApiResponse<UserResponse>>(
+      {
+        success: true,
+        data: format_user_response(user),
+        message: "User created successfully",
+      },
+      201
+    );
+  } catch (error) {
+    return c.json<ApiError>(
+      {
+        success: false,
+        error: "Failed to create user",
+      },
+      500
+    );
+  }
+}

package/cli/src/templates/base/src/controllers/user/delete-user.controller.ts

@@ -0,0 +1,60 @@
+import type { Context } from "hono";
+import { z } from "zod";
+import { user_model } from "../../models/user.model.js";
+import type { ApiResponse, ApiError } from "../../types/common/api-response.types.js";
+
+/**
+ * Validation schema
+ */
+const user_id_schema = z.string().uuid("Invalid user ID format");
+
+/**
+ * Delete user by ID
+ * DELETE /users/:id
+ */
+export async function delete_user(c: Context) {
+  try {
+    const id = c.req.param("id");
+
+    // Validate ID format
+    const validation = user_id_schema.safeParse(id);
+    if (!validation.success) {
+      return c.json<ApiError>(
+        {
+          success: false,
+          error: "Invalid user ID",
+          details: validation.error.errors.map((err) => ({
+            field: err.path.join("."),
+            message: err.message,
+          })),
+        },
+        400
+      );
+    }
+
+    const deleted = await user_model.delete(id);
+
+    if (!deleted) {
+      return c.json<ApiError>(
+        {
+          success: false,
+          error: "User not found",
+        },
+        404
+      );
+    }
+
+    return c.json<ApiResponse>({
+      success: true,
+      message: "User deleted successfully",
+    });
+  } catch (error) {
+    return c.json<ApiError>(
+      {
+        success: false,
+        error: "Failed to delete user",
+      },
+      500
+    );
+  }
+}

package/cli/src/templates/base/src/controllers/user/get-user.controller.ts

@@ -0,0 +1,74 @@
+import type { Context } from "hono";
+import { z } from "zod";
+import { user_model } from "../../models/user.model.js";
+import type { ApiResponse, ApiError } from "../../types/common/api-response.types.js";
+import type { UserResponse } from "../../types/models/user.types.js";
+
+/**
+ * Validation schema
+ */
+const user_id_schema = z.string().uuid("Invalid user ID format");
+
+/**
+ * Helper to format user response
+ */
+function format_user_response(user: any): UserResponse {
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    createdAt: user.createdAt.toISOString(),
+    updatedAt: user.updatedAt.toISOString(),
+  };
+}
+
+/**
+ * Get user by ID
+ * GET /users/:id
+ */
+export async function get_user(c: Context) {
+  try {
+    const id = c.req.param("id");
+
+    // Validate ID format
+    const validation = user_id_schema.safeParse(id);
+    if (!validation.success) {
+      return c.json<ApiError>(
+        {
+          success: false,
+          error: "Invalid user ID",
+          details: validation.error.errors.map((err) => ({
+            field: err.path.join("."),
+            message: err.message,
+          })),
+        },
+        400
+      );
+    }
+
+    const user = await user_model.find_by_id(id);
+
+    if (!user) {
+      return c.json<ApiError>(
+        {
+          success: false,
+          error: "User not found",
+        },
+        404
+      );
+    }
+
+    return c.json<ApiResponse<UserResponse>>({
+      success: true,
+      data: format_user_response(user),
+    });
+  } catch (error) {
+    return c.json<ApiError>(
+      {
+        success: false,
+        error: "Failed to fetch user",
+      },
+      500
+    );
+  }
+}

package/cli/src/templates/base/src/controllers/user/get-users.controller.ts

@@ -0,0 +1,41 @@
+import type { Context } from "hono";
+import { user_model } from "../../models/user.model.js";
+import type { ApiResponse, ApiError } from "../../types/common/api-response.types.js";
+import type { UserResponse } from "../../types/models/user.types.js";
+
+/**
+ * Helper to format user response
+ */
+function format_user_response(user: any): UserResponse {
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    createdAt: user.createdAt.toISOString(),
+    updatedAt: user.updatedAt.toISOString(),
+  };
+}
+
+/**
+ * Get all users
+ * GET /users
+ */
+export async function get_users(c: Context) {
+  try {
+    const users = await user_model.find_all();
+    const formatted_users = users.map(format_user_response);
+
+    return c.json<ApiResponse<UserResponse[]>>({
+      success: true,
+      data: formatted_users,
+    });
+  } catch (error) {
+    return c.json<ApiError>(
+      {
+        success: false,
+        error: "Failed to fetch users",
+      },
+      500
+    );
+  }
+}