stackkit 0.2.7 → 0.2.9

package/README.md

@@ -1,34 +1,113 @@
 # StackKit CLI
 
-CLI for scaffolding and composing modular JavaScript applications.
+Production-ready full-stack project generator.
 
-## Quick Start
+## Installation
 
-Create a new project without installing globally:
+No installation required. Use npx to get the latest version:
 
 ```bash
+npx stackkit@latest <command>
+```
+
+## Commands
+
+### create
+
+Generate a new project:
+
+```bash
+# Interactive mode
 npx stackkit@latest create my-app
+
+# With options
+npx stackkit@latest create my-app \
+  --framework nextjs \
+  --database prisma-postgresql \
+  --auth better-auth \
+  --language typescript
 ```
 
-Add features to an existing project:
+**Options:**
+
+- `--framework, -f` - nextjs, express, react
+- `--database, -d` - prisma-postgresql, prisma-mysql, prisma-sqlite, prisma-mongodb, mongoose, none
+- `--auth, -a` - better-auth, authjs, none
+- `--language, -l` - typescript, javascript
+- `--package-manager, -p` - pnpm, npm, yarn, bun
+- `--yes, -y` - Use defaults
+- `--skip-install` - Don't install dependencies
+- `--no-git` - Don't initialize git
+
+### add
+
+Add features to existing project:
 
 ```bash
-npx stackkit@latest add <module>
+npx stackkit@latest add
 ```
 
-Check project health:
+Interactively select and install modules.
+
+### doctor
+
+Diagnose project health:
 
 ```bash
 npx stackkit@latest doctor
+
+# Verbose output
+npx stackkit@latest doctor --verbose
+
+# JSON output (for CI/CD)
+npx stackkit@latest doctor --json
+```
+
+### list
+
+Show available options:
+
+```bash
+npx stackkit@latest list
 ```
 
-## Supported technologies
+## Supported Technologies
+
+**Frameworks:**
+
+- Next.js (App Router)
+- Express (TypeScript API)
+- React (Vite SPA)
+
+**Databases:**
+
+- Prisma (PostgreSQL, MySQL, SQLite, MongoDB)
+- Mongoose (MongoDB)
+
+**Authentication:**
 
-- Frameworks: Next.js, React, Express
-- Databases: Prisma, Mongoose
-- Auth: Auth.js / Better Auth
+- Better Auth (All frameworks)
+- Auth.js (Next.js only)
+
+## Examples
+
+```bash
+# Full-stack Next.js
+npx stackkit@latest create my-app --framework nextjs --database prisma-postgresql --auth better-auth
+
+# Express API
+npx stackkit@latest create my-api --framework express --database mongoose
+
+# React frontend
+npx stackkit@latest create my-spa --framework react --auth better-auth
+```
 
 ## Links
 
-- Website: https://stackkit.tariqul.dev
-- Repo: https://github.com/tariqul420/stackkit
+- **Documentation**: https://stackkit.tariqul.dev
+- **GitHub**: https://github.com/tariqul420/stackkit
+- **Issues**: https://github.com/tariqul420/stackkit/issues
+
+## License
+
+MIT © [Tariqul Islam](https://github.com/tariqul420)

package/dist/lib/fs/files.js

@@ -19,7 +19,7 @@ async function copyBaseFramework(templatesDir, targetDir, framework) {
         throw new Error(`Base template not found for framework: ${framework}\n` + `Expected at: ${baseDir}`);
     }
     await fs_extra_1.default.copy(baseDir, targetDir, {
-        filter: (src) => !constants_1.EXCLUDE_FROM_COPY.includes(path_1.default.basename(src)),
+        filter: (src) => !constants_1.EXCLUDE_FROM_COPY.some((entry) => entry === path_1.default.basename(src)),
     });
 }
 async function mergePackageJson(targetDir, config) {

package/dist/lib/generation/code-generator.d.ts

@@ -74,16 +74,14 @@ export declare class AdvancedCodeGenerator {
     private copyTemplate;
     private processOperationTemplates;
     private executeCreateFile;
+    private parsePathPattern;
+    private collectFilesRecursively;
     private executePatchFile;
     private executeAddDependency;
     private executeAddScript;
     private executeAddEnv;
     private executeRunCommand;
     private generatePackageJson;
-    /**
-     * Apply generators to an existing project directory instead of creating a new template.
-     * This executes applicable operations and updates package.json in-place.
-     */
     applyToProject(selectedModules: {
         framework: string;
         database?: string;
@@ -95,8 +93,5 @@ export declare class AdvancedCodeGenerator {
         databases: string[];
         auths: string[];
     };
-    /**
-     * Register a generator config dynamically (used for modules that only provide module.json patches).
-     */
     registerGenerator(type: "framework" | "database" | "auth", name: string, config: GeneratorConfig): void;
 }

package/dist/lib/generation/code-generator.js

@@ -128,8 +128,7 @@ class AdvancedCodeGenerator {
             const varNameMatch = result.substring(varStart + 7, equalsIndex).trim();
             if (!varNameMatch)
                 break;
-            // Find the end of the variable value by counting braces
-            // Start with braceCount = 1 because {{#var is already open
+            // Find the closing }} for the variable definition, accounting for nested {{#var}}...{{/var}}
             let braceCount = 1;
             const valueStart = equalsIndex + 1;
             let valueEnd = valueStart;
@@ -400,20 +399,6 @@ class AdvancedCodeGenerator {
                         !relativePath.startsWith("node_modules/"));
                 },
             });
-            // If template provides a .env.example, create a .env from it when
-            // the target project does not already have a .env file.
-            try {
-                const envExampleSrc = path.join(templatePath, ".env.example");
-                const envDest = path.join(outputPath, ".env");
-                if ((await fs.pathExists(envExampleSrc)) && !(await fs.pathExists(envDest))) {
-                    await fs.copy(envExampleSrc, envDest);
-                }
-            }
-            catch {
-                // ignore (not critical)
-            }
-            // Ensure gitignore is present in target even if template authors
-            // renamed it to avoid npm/package issues (e.g. 'gitignore' or '_gitignore')
             try {
                 const gitCandidates = [".gitignore", "gitignore", "_gitignore"];
                 for (const g of gitCandidates) {
@@ -430,7 +415,6 @@ class AdvancedCodeGenerator {
             catch {
                 // ignore
             }
-            // Ensure any top-level dotfiles declared in template.json are created
             try {
                 const templateJsonPath = path.join(templatePath, "template.json");
                 if (await fs.pathExists(templateJsonPath)) {
@@ -454,9 +438,7 @@ class AdvancedCodeGenerator {
                                     }
                                     continue;
                                 }
-                                // For other dotfiles (e.g. .env.example), only create if the template
-                                // actually contains a dotfile source. Don't synthesize from non-dot fallbacks
-                                // to avoid creating files unintentionally.
+                                // For other dotfiles, only copy if the exact dotfile exists in the template to avoid unintended fallbacks
                                 const srcDot = path.join(templatePath, f);
                                 if (await fs.pathExists(srcDot)) {
                                     await fs.copy(srcDot, targetDest);
@@ -505,6 +487,17 @@ class AdvancedCodeGenerator {
             catch {
                 // ignore
             }
+            // Handle .env.example -> .env copying if .env doesn't already exist
+            try {
+                const envExampleDest = path.join(outputPath, ".env.example");
+                const envDest = path.join(outputPath, ".env");
+                if ((await fs.pathExists(envExampleDest)) && !(await fs.pathExists(envDest))) {
+                    await fs.copy(envExampleDest, envDest);
+                }
+            }
+            catch {
+                // ignore (not critical)
+            }
         }
     }
     processOperationTemplates(operation, context) {
@@ -559,28 +552,88 @@ class AdvancedCodeGenerator {
     async executeCreateFile(operation, context, outputPath) {
         if (!operation.destination)
             return;
-        const destinationPath = path.join(outputPath, this.processTemplate(operation.destination, context));
-        // Ensure directory exists
-        await fs.ensureDir(path.dirname(destinationPath));
-        let content;
+        const processedDestination = this.processTemplate(operation.destination, context);
+        const { basePath: destinationBasePath, mode: destinationMode } = this.parsePathPattern(processedDestination);
         if (operation.content) {
-            // Use content directly
-            content = this.processTemplate(operation.content, context);
-        }
-        else if (operation.source) {
-            const sourcePath = (0, generator_utils_1.locateOperationSource)(operation.generatorType, operation.generator, operation.source || "");
-            if (sourcePath && (await fs.pathExists(sourcePath))) {
-                content = await fs.readFile(sourcePath, "utf-8");
-                content = this.processTemplate(content, context);
+            const destinationPath = path.join(outputPath, processedDestination);
+            await fs.ensureDir(path.dirname(destinationPath));
+            const content = this.processTemplate(operation.content, context);
+            await fs.writeFile(destinationPath, content, "utf-8");
+            try {
+                const rel = path.relative(outputPath, destinationPath);
+                if (rel && !this.createdFiles.includes(rel))
+                    this.createdFiles.push(rel);
             }
-            else {
-                throw new Error(`Source file not found: ${sourcePath}`);
+            catch {
+                // ignore logging failures
             }
+            return;
         }
-        else {
+        if (!operation.source) {
             throw new Error(`Create file operation must have either 'content' or 'source' field`);
         }
-        // Write destination file
+        const processedSource = this.processTemplate(operation.source, context);
+        const { basePath: sourceBasePathRel, mode: sourceMode } = this.parsePathPattern(processedSource);
+        const sourcePath = (0, generator_utils_1.locateOperationSource)(operation.generatorType, operation.generator, sourceBasePathRel);
+        if (!sourcePath || !(await fs.pathExists(sourcePath))) {
+            throw new Error(`Source file not found: ${sourcePath}`);
+        }
+        const sourceStat = await fs.stat(sourcePath);
+        const shouldCreateMultipleFiles = sourceStat.isDirectory() || sourceMode !== "single";
+        if (shouldCreateMultipleFiles) {
+            if (!sourceStat.isDirectory()) {
+                throw new Error(`Source path must be a directory for wildcard copy: ${processedSource}`);
+            }
+            let sourceFiles = [];
+            if (sourceMode === "flat") {
+                const entries = await fs.readdir(sourcePath);
+                for (const entry of entries) {
+                    const candidatePath = path.join(sourcePath, entry);
+                    const candidateStat = await fs.stat(candidatePath);
+                    if (candidateStat.isFile()) {
+                        sourceFiles.push(candidatePath);
+                    }
+                }
+            }
+            else {
+                sourceFiles = await this.collectFilesRecursively(sourcePath);
+            }
+            for (const sourceFilePath of sourceFiles) {
+                let relativeDestinationPath;
+                if (destinationMode === "recursive") {
+                    relativeDestinationPath = path.relative(sourcePath, sourceFilePath);
+                }
+                else if (destinationMode === "flat") {
+                    relativeDestinationPath = path.basename(sourceFilePath);
+                }
+                else {
+                    relativeDestinationPath =
+                        sourceMode === "flat"
+                            ? path.basename(sourceFilePath)
+                            : path.relative(sourcePath, sourceFilePath);
+                }
+                const destinationPath = path.join(outputPath, destinationBasePath, relativeDestinationPath);
+                await fs.ensureDir(path.dirname(destinationPath));
+                let content = await fs.readFile(sourceFilePath, "utf-8");
+                content = this.processTemplate(content, context);
+                await fs.writeFile(destinationPath, content, "utf-8");
+                try {
+                    const rel = path.relative(outputPath, destinationPath);
+                    if (rel && !this.createdFiles.includes(rel))
+                        this.createdFiles.push(rel);
+                }
+                catch {
+                    // ignore logging failures
+                }
+            }
+            return;
+        }
+        const destinationPath = destinationMode === "single"
+            ? path.join(outputPath, processedDestination)
+            : path.join(outputPath, destinationBasePath, path.basename(sourcePath));
+        await fs.ensureDir(path.dirname(destinationPath));
+        let content = await fs.readFile(sourcePath, "utf-8");
+        content = this.processTemplate(content, context);
         await fs.writeFile(destinationPath, content, "utf-8");
         try {
             const rel = path.relative(outputPath, destinationPath);
@@ -591,6 +644,31 @@ class AdvancedCodeGenerator {
             // ignore logging failures
         }
     }
+    parsePathPattern(inputPath) {
+        const normalizedPath = inputPath.replace(/\\/g, "/");
+        if (normalizedPath.endsWith("/**")) {
+            return { basePath: normalizedPath.slice(0, -3), mode: "recursive" };
+        }
+        if (normalizedPath.endsWith("/*")) {
+            return { basePath: normalizedPath.slice(0, -2), mode: "flat" };
+        }
+        return { basePath: normalizedPath, mode: "single" };
+    }
+    async collectFilesRecursively(rootDirPath) {
+        const files = [];
+        const entries = await fs.readdir(rootDirPath);
+        for (const entry of entries) {
+            const fullPath = path.join(rootDirPath, entry);
+            const stat = await fs.stat(fullPath);
+            if (stat.isDirectory()) {
+                files.push(...(await this.collectFilesRecursively(fullPath)));
+            }
+            else if (stat.isFile()) {
+                files.push(fullPath);
+            }
+        }
+        return files;
+    }
     async executePatchFile(operation, context, outputPath) {
         if (!operation.destination)
             return;
@@ -608,14 +686,12 @@ class AdvancedCodeGenerator {
                 switch (patchOp.type) {
                     case "add-import":
                         if (patchOp.imports) {
-                            // Process imports and trim any accidental surrounding blank lines
                             const imports = patchOp.imports
                                 .map((imp) => this.processTemplate(imp, context))
                                 .join("\n")
                                 .replace(/^\n+/, "")
                                 .replace(/\n+$/, "");
-                            // Add imports at the top, after existing imports without introducing
-                            // extra blank lines.
+                            // Split content into lines for easier manipulation
                             const lines = content.split("\n");
                             // Find the last import line index
                             let lastImportIndex = -1;
@@ -623,9 +699,7 @@ class AdvancedCodeGenerator {
                                 if (lines[i].trim().startsWith("import"))
                                     lastImportIndex = i;
                             }
-                            // Insert right after the last import. If there's a blank line
-                            // immediately after the imports, overwrite that blank line to
-                            // avoid introducing an extra empty line above the inserted imports.
+                            // Determine where to insert new imports: after the last existing import, or at the top if no imports exist
                             const insertIndex = lastImportIndex === -1 ? 0 : lastImportIndex + 1;
                             // Only add imports that don't already exist in the file
                             const importLines = imports
@@ -641,8 +715,7 @@ class AdvancedCodeGenerator {
                                 else {
                                     lines.splice(insertIndex, 0, ...newImportLines);
                                 }
-                                // After insertion, ensure exactly one blank line after the import block
-                                // Find last import line index again
+                                // After adding imports, ensure there is exactly one blank line after the last import statement (if there are any imports)
                                 let lastIdx = -1;
                                 for (let i = 0; i < lines.length; i++) {
                                     if (lines[i].trim().startsWith("import"))
@@ -650,7 +723,6 @@ class AdvancedCodeGenerator {
                                 }
                                 const nextIdx = lastIdx + 1;
                                 if (lastIdx !== -1) {
-                                    // Remove multiple blank lines after imports
                                     let j = nextIdx;
                                     while (j < lines.length && lines[j].trim() === "") {
                                         j++;
@@ -685,7 +757,6 @@ class AdvancedCodeGenerator {
                                     // Normalize code: trim surrounding newlines and ensure single trailing newline
                                     let codeNormalized = processedCode.replace(/^\n+|\n+$/g, "") + "\n";
                                     // If right already starts with a newline, avoid double-blank by
-                                    // removing trailing newline from codeNormalized so only one newline remains
                                     const rightStartsWithNewline = right.startsWith("\n");
                                     if (rightStartsWithNewline && codeNormalized.endsWith("\n")) {
                                         codeNormalized = codeNormalized.replace(/\n+$/, "");
@@ -704,7 +775,6 @@ class AdvancedCodeGenerator {
                                     // Normalize code: trim surrounding newlines and ensure single trailing newline
                                     let codeNormalized = processedCode.replace(/^\n+|\n+$/g, "") + "\n";
                                     // If right already starts with a newline, avoid double-blank by
-                                    // removing trailing newline from codeNormalized so only one newline remains
                                     const rightStartsWithNewline = right.startsWith("\n");
                                     if (rightStartsWithNewline && codeNormalized.endsWith("\n")) {
                                         codeNormalized = codeNormalized.replace(/\n+$/, "");
@@ -840,8 +910,7 @@ class AdvancedCodeGenerator {
             if ((type === "framework" && name === selectedModules.framework) ||
                 (type === "database" && name === selectedModules.database) ||
                 (type === "auth" && name === selectedModules.auth)) {
-                // Dependencies and devDependencies are now provided via `add-dependency`
-                // operations. Keep merging scripts from generator configs for now.
+                // Merge dependencies, devDependencies, and scripts from the generator into the cumulative objects
                 Object.assign(allScripts, generator.scripts);
             }
         }
@@ -860,10 +929,7 @@ class AdvancedCodeGenerator {
         };
         await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
     }
-    /**
-     * Apply generators to an existing project directory instead of creating a new template.
-     * This executes applicable operations and updates package.json in-place.
-     */
+    // Public method to apply generators to an existing project (used for "Add to existing project" flow)
     async applyToProject(selectedModules, features, projectPath) {
         const context = {
             ...selectedModules,
@@ -934,9 +1000,7 @@ class AdvancedCodeGenerator {
         }
         return { frameworks, databases, auths };
     }
-    /**
-     * Register a generator config dynamically (used for modules that only provide module.json patches).
-     */
+    // Method to register a generator configuration
     registerGenerator(type, name, config) {
         this.generators.set(`${type}:${name}`, config);
     }

package/dist/lib/utils/fs-helpers.d.ts

@@ -7,6 +7,6 @@ export declare function writeFile(filePath: string, content: string): Promise<vo
 export declare function copyDir(source: string, destination: string, options?: CopyFilterFunction): Promise<void>;
 export declare function readDir(dirPath: string): Promise<string[]>;
 export declare function isDirectory(dirPath: string): Promise<boolean>;
-export declare function findFilesInDir(dirPath: string, predicate: (file: string) => boolean): Promise<string[]>;
+export declare function findFilesInDir(dirPath: string, predicate: (fileName: string) => boolean): Promise<string[]>;
 export declare function getEnvFilePath(projectRoot: string): Promise<string | null>;
 export {};

package/modules/auth/authjs/generator.json

@@ -3,11 +3,6 @@
   "type": "auth",
   "priority": 10,
   "operations": [
-    {
-      "type": "create-file",
-      "source": "shared/lib/auth.ts",
-      "destination": "server/auth/auth.ts"
-    },
     {
       "type": "create-file",
       "source": "nextjs/api/auth/[...nextauth]/route.ts",
@@ -18,6 +13,11 @@
       "source": "nextjs/proxy.ts",
       "destination": "proxy.ts"
     },
+    {
+      "type": "create-file",
+      "source": "shared/lib/auth.ts",
+      "destination": "server/auth/auth.ts"
+    },
     {
       "type": "patch-file",
       "destination": "prisma/schema.prisma",
@@ -36,6 +36,17 @@
         "@auth/prisma-adapter": "^2.11.1"
       }
     },
+    {
+      "type": "add-dependency",
+      "dependencies": {
+        "bcryptjs": "^3.0.3",
+        "next-auth": "^5.0.0-beta.30",
+        "nodemailer": "^7.0.12"
+      },
+      "devDependencies": {
+        "@types/nodemailer": "^7.0.5"
+      }
+    },
     {
       "type": "add-env",
       "envVars": {
@@ -48,17 +59,6 @@
         "EMAIL_PASS": "",
         "EMAIL_FROM": "noreply@yourapp.com"
       }
-    },
-    {
-      "type": "add-dependency",
-      "dependencies": {
-        "next-auth": "^5.0.0-beta.30",
-        "bcryptjs": "^3.0.3",
-        "nodemailer": "^7.0.12"
-      },
-      "devDependencies": {
-        "@types/nodemailer": "^7.0.5"
-      }
     }
   ]
 }