create-charcole 2.1.0 → 2.2.1

package/bin/lib/pkgManager.js

@@ -1,49 +1,49 @@
-const { execSync } = require("child_process");
-const fs = require("fs");
-const path = require("path");
-
-/**
- * Detect which package manager the user is using
- * Priority: pnpm > yarn > npm
- */
-function detectPackageManager() {
-  const userAgent = process.env.npm_config_user_agent;
-
-  if (userAgent) {
-    if (userAgent.includes("pnpm")) return "pnpm";
-    if (userAgent.includes("yarn")) return "yarn";
-    if (userAgent.includes("npm")) return "npm";
-  }
-
-  const lockFiles = {
-    "pnpm-lock.yaml": "pnpm",
-    "yarn.lock": "yarn",
-    "package-lock.json": "npm",
-  };
-
-  for (const [lockFile, manager] of Object.entries(lockFiles)) {
-    if (fs.existsSync(path.join(process.cwd(), lockFile))) {
-      return manager;
-    }
-  }
-
-  return "npm";
-}
-
-/**
- * Install dependencies
- */
-function installDependencies(targetDir, pkgManager) {
-  const installCmd =
-    pkgManager === "yarn" ? "yarn install" : `${pkgManager} install`;
-
-  execSync(installCmd, {
-    cwd: targetDir,
-    stdio: "inherit",
-  });
-}
-
-module.exports = {
-  detectPackageManager,
-  installDependencies,
-};
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Detect which package manager the user is using
+ * Priority: pnpm > yarn > npm
+ */
+function detectPackageManager() {
+  const userAgent = process.env.npm_config_user_agent;
+
+  if (userAgent) {
+    if (userAgent.includes("pnpm")) return "pnpm";
+    if (userAgent.includes("yarn")) return "yarn";
+    if (userAgent.includes("npm")) return "npm";
+  }
+
+  const lockFiles = {
+    "pnpm-lock.yaml": "pnpm",
+    "yarn.lock": "yarn",
+    "package-lock.json": "npm",
+  };
+
+  for (const [lockFile, manager] of Object.entries(lockFiles)) {
+    if (fs.existsSync(path.join(process.cwd(), lockFile))) {
+      return manager;
+    }
+  }
+
+  return "npm";
+}
+
+/**
+ * Install dependencies
+ */
+function installDependencies(targetDir, pkgManager) {
+  const installCmd =
+    pkgManager === "yarn" ? "yarn install" : `${pkgManager} install`;
+
+  execSync(installCmd, {
+    cwd: targetDir,
+    stdio: "inherit",
+  });
+}
+
+module.exports = {
+  detectPackageManager,
+  installDependencies,
+};

package/bin/lib/templateHandler.js

@@ -1,33 +1,33 @@
-const fs = require("fs");
-const path = require("path");
-
-/**
- * Recursively copy directory contents, excluding specific files
- */
-function copyDir(src, dest, excludeFiles = []) {
-  if (!fs.existsSync(dest)) {
-    fs.mkdirSync(dest, { recursive: true });
-  }
-
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-
-    // Skip excluded files
-    if (excludeFiles.includes(entry.name)) {
-      continue;
-    }
-
-    if (entry.isDirectory()) {
-      copyDir(srcPath, destPath, excludeFiles);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
-  }
-}
-
-module.exports = {
-  copyDir,
-};
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Recursively copy directory contents, excluding specific files
+ */
+function copyDir(src, dest, excludeFiles = []) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    // Skip excluded files
+    if (excludeFiles.includes(entry.name)) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, excludeFiles);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+module.exports = {
+  copyDir,
+};

package/package.json

@@ -1,27 +1,42 @@
-{
-  "name": "create-charcole",
-  "version": "2.1.0",
-  "description": "CLI to create production-ready Node.js Express APIs with TypeScript/JavaScript, JWT auth, and repository pattern",
-  "license": "MIT",
-  "author": {
-    "name": "Sheraz Manzoor",
-    "email": "sheraz.dev121@gmail.com"
-  },
-  "bin": {
-    "create-charcole": "bin/index.js"
-  },
-  "keywords": [
-    "express",
-    "backend",
-    "starter",
-    "boilerplate",
-    "production",
-    "charcole"
-  ],
-  "engines": {
-    "node": ">=16"
-  },
-  "dependencies": {
-    "prompts": "^2.4.2"
-  }
-}
+{
+  "name": "create-charcole",
+  "version": "2.2.1",
+  "description": "CLI to create production-ready Node.js Express APIs with TypeScript/JavaScript, JWT auth, auto-generated Swagger docs, and repository pattern",
+  "license": "MIT",
+  "author": {
+    "name": "Sheraz Manzoor",
+    "email": "sheraz.dev121@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sheraz4196/create-charcole.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sheraz4196/create-charcole/issues"
+  },
+  "homepage": "https://www.charcole.site/",
+  "bin": {
+    "create-charcole": "bin/index.js"
+  },
+  "keywords": [
+    "express",
+    "backend",
+    "starter",
+    "boilerplate",
+    "production",
+    "charcole",
+    "nodejs starter",
+    "express starter",
+    "typescript backend",
+    "swagger",
+    "backend template",
+    "api-boilerplate",
+    "zod validation"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {
+    "prompts": "^2.4.2"
+  }
+}

package/packages/swagger/BACKWARD_COMPATIBILITY.md

@@ -0,0 +1,145 @@
+# @charcoles/swagger v2.0.0 - Backward Compatibility Test
+
+## Test Cases
+
+### ✅ Old JSDoc Approach (Still Works)
+
+The traditional manual schema approach still works without any changes:
+
+```typescript
+/**
+ * @swagger
+ * /api/old-endpoint:
+ *   post:
+ *     summary: Old style endpoint
+ *     requestBody:
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - name
+ *             properties:
+ *               name:
+ *                 type: string
+ *     responses:
+ *       200:
+ *         description: Success
+ */
+```
+
+**Status:** ✅ Fully compatible
+
+### ✅ Minimal Setup (Still Works)
+
+Old setup without new options:
+
+```typescript
+setupSwagger(app, {
+  title: "My API",
+  version: "1.0.0",
+});
+```
+
+**Status:** ✅ Fully compatible (new options are optional)
+
+### ✅ Mixed Approach (Old + New)
+
+You can mix manual schemas and auto-generated ones:
+
+```typescript
+setupSwagger(app, {
+  schemas: {
+    createUserSchema, // New: auto-generated from Zod
+  },
+});
+
+// Old manual approach
+/**
+ * @swagger
+ * /api/manual:
+ *   get:
+ *     responses:
+ *       200:
+ *         description: Success
+ */
+
+// New reference approach
+/**
+ * @swagger
+ * /api/auto:
+ *   post:
+ *     requestBody:
+ *       content:
+ *         application/json:
+ *           schema:
+ *             $ref: '#/components/schemas/createUserSchema'
+ */
+```
+
+**Status:** ✅ Fully compatible
+
+### ✅ No Zod (Non-Charcole Projects)
+
+Works fine without Zod schemas:
+
+```typescript
+import { setupSwagger } from "@charcoles/swagger";
+
+setupSwagger(app, {
+  title: "My API",
+  // No schemas - just use manual JSDoc approach
+});
+```
+
+**Status:** ✅ Fully compatible
+
+### ✅ Disable Common Responses
+
+Can disable built-in responses if not wanted:
+
+```typescript
+setupSwagger(app, {
+  includeCommonResponses: false, // Opt-out
+});
+```
+
+**Status:** ✅ Fully compatible
+
+## Migration Path
+
+### No Breaking Changes
+
+All existing code continues to work:
+
+1. **Don't want to use new features?**
+   - No changes needed
+   - Everything works as before
+
+2. **Want to gradually adopt?**
+   - Start using schema references one endpoint at a time
+   - Mix old and new approaches
+
+3. **Want full benefits?**
+   - Register schemas in config
+   - Update JSDoc to use `$ref`
+   - Enjoy 60-80% less code
+
+## Compatibility Matrix
+
+| Feature                  | v1.0.0 | v2.0.0 | Notes                          |
+| ------------------------ | ------ | ------ | ------------------------------ |
+| Manual JSDoc             | ✅     | ✅     | No changes needed              |
+| Basic setup              | ✅     | ✅     | All old options work           |
+| Security schemes         | ✅     | ✅     | bearerAuth still auto-included |
+| File scanning            | ✅     | ✅     | Same directories scanned       |
+| TypeScript detection     | ✅     | ✅     | Same auto-detection            |
+| Zod schemas (new)        | ❌     | ✅     | Optional new feature           |
+| Response templates (new) | ❌     | ✅     | Optional new feature           |
+| Helper functions (new)   | ❌     | ✅     | Optional new feature           |
+
+## Conclusion
+
+**100% backward compatible** ✅
+
+No breaking changes. All new features are additive and optional.