@adriankulik/create-fullstack-app 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrian Kulik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# create-fullstack-app
+
+A CLI tool for scaffolding a full-stack web application with your choice of frontend and backend technologies. The generated projects use `npm ci` and pinned Python dependencies to ensure fully deterministic and reproducible installations.
+
+## Prerequisites
+
+Before running the CLI or the scaffolded applications, ensure you have the following installed on your system:
+- **Node.js**: v20 or newer
+- **npm**: v10 or newer
+- **Python**: v3.11 or newer
+
+## Quickstart
+
+Run the CLI tool directly using Node.js:
+
+```bash
+cd cli
+npm install
+node index.js
+```
+
+You will be prompted to choose a project name, your preferred frontend, and backend framework.
+
+## Features
+
+- **Frontend Options**:
+  - Next.js (v16.2.4)
+  - Angular (v21.0.0) - *Configured with Zone.js*
+  - Vue (v3.5.33)
+  - Svelte (v5.55.5)
+- **Backend Options**: 
+  - FastAPI (v0.136.1)
+  - Flask (v3.1.3)
+- **Opinionated Defaults**: We bake in sensible, predefined choices (e.g., Angular uses `zone.js`, testing is unified under Playwright and framework-native test runners).
+- **Unified Scripts**: `start.sh`, `test.sh`, and `lint.sh` available out of the box to manage both frontend and backend seamlessly.
+- **CI/CD Ready**: Includes a pre-configured `.github/workflows/cli-e2e.yml` that tests both ends. *Tip: To enforce this, enable branch protection in your GitHub repository settings and require the "test" status check to pass.*
+- **Developer Experience**: Includes `.vscode/extensions.json` recommending the necessary linters and formatters, and a `GEMINI.md` file providing behavioral guidelines for AI agents (based on [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)).
+
+## Generated Project
+
+The generated application will look like this:
+
+```
+my-app/
+├── .github/
+├── .vscode/
+├── backend/
+│   ├── main.py
+│   ├── test_main.py
+│   └── requirements.txt
+├── frontend/
+│   ├── app/ (or src/)
+│   └── package.json
+├── start.sh
+├── test.sh
+└── lint.sh
+```
+
+*Note: Depending on your environment, you may need to ensure the generated shell scripts are executable by running `chmod +x *.sh` inside your new project directory.*
+
+## Local E2E Testing
+
+You can automatically test all frontend and backend permutations locally via **Playwright** integration tests using the provided script in the root directory.
+
+Ensure you make the script executable first:
+
+```bash
+chmod +x run_e2e.sh
+```
+
+Then run it:
+
+```bash
+./run_e2e.sh
+```
+
+**Note for Windows Users:** The `run_e2e.sh` script utilizes Unix commands (like `lsof` and `kill -9`) for process teardown. You must run this script inside a **WSL** (Windows Subsystem for Linux) or **Git Bash** terminal.
+
+## Roadmap
+
+Future plans for this CLI include:
+
+- Adding frontend framework-specific component libraries during the scaffold step.
+- Tackling **.NET** as a new backend option.

package/cli/index.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+const prompts = require('prompts');
+const pc = require('picocolors');
+const fs = require('fs-extra');
+const path = require('path');
+const { execSync } = require('child_process');
+
+async function main() {
+  console.log(pc.cyan('\nWelcome to create-fullstack-app!\n'));
+
+  // Simple argument parsing
+  const args = process.argv.slice(2);
+  let argProjectName = args[0] && !args[0].startsWith('--') ? args[0] : null;
+  let argFrontend = null;
+  let argBackend = null;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--frontend' && args[i + 1]) argFrontend = args[i + 1];
+    if (args[i] === '--backend' && args[i + 1]) argBackend = args[i + 1];
+  }
+
+  const questions = [];
+  if (!argProjectName) {
+    questions.push({
+      type: 'text',
+      name: 'projectName',
+      message: 'What is your project named?',
+      initial: 'my-fullstack-app',
+      validate: value => value.trim().length > 0 ? true : 'Project name cannot be empty'
+    });
+  }
+
+  if (!argFrontend) {
+    questions.push({
+      type: 'select',
+      name: 'frontend',
+      message: 'Which frontend framework would you like to use?',
+      choices: [
+        { title: 'Next.js', value: 'nextjs', description: 'React framework' },
+        { title: 'Angular', value: 'angular', description: 'Enterprise-grade platform' },
+        { title: 'Vue', value: 'vue', description: 'Progressive JavaScript framework' },
+        { title: 'Svelte', value: 'svelte', description: 'Cybernetically enhanced web apps' }
+      ],
+      initial: 0
+    });
+  }
+
+  if (!argBackend) {
+    questions.push({
+      type: 'select',
+      name: 'backend',
+      message: 'Which backend framework would you like to use?',
+      choices: [
+        { title: 'FastAPI', value: 'fastapi', description: 'Modern, fast Python web framework' },
+        { title: 'Flask', value: 'flask', description: 'Lightweight WSGI web application framework' }
+      ],
+      initial: 0
+    });
+  }
+
+  const response = await prompts(questions);
+
+  const projectName = argProjectName || response.projectName;
+  const frontend = argFrontend || response.frontend;
+  const backend = argBackend || response.backend;
+
+  if (!projectName || !frontend || !backend) {
+    console.log(pc.red('Setup cancelled.'));
+    process.exit(1);
+  }
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(targetDir)) {
+    console.log(pc.red(`Directory ${projectName} already exists.`));
+    process.exit(1);
+  }
+
+  console.log(pc.blue(`\nScaffolding project in ${targetDir}...`));
+
+  // Determine paths to templates relative to the CLI script
+  const templatesDir = path.resolve(__dirname, '../templates');
+  const baseDir = path.join(templatesDir, 'base');
+  const frontendDir = path.join(templatesDir, 'frontend', frontend);
+  const backendDir = path.join(templatesDir, 'backend', backend);
+
+  try {
+    // 1. Copy base template
+    await fs.copy(baseDir, targetDir);
+    if (fs.existsSync(path.join(targetDir, 'gitignore'))) {
+      await fs.rename(path.join(targetDir, 'gitignore'), path.join(targetDir, '.gitignore'));
+    }
+
+    // 2. Copy frontend
+    const targetFrontend = path.join(targetDir, 'frontend');
+    await fs.copy(frontendDir, targetFrontend);
+
+    // 3. Copy backend
+    const targetBackend = path.join(targetDir, 'backend');
+    await fs.copy(backendDir, targetBackend);
+
+    // 4. Update package.json name for the frontend
+    const pkgPath = path.join(targetFrontend, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = await fs.readJson(pkgPath);
+      pkg.name = `${projectName}-frontend`;
+      await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+    }
+
+    // 5. Make all shell scripts executable
+    const makeExecutable = (dir) => {
+      const files = fs.readdirSync(dir);
+      files.forEach(file => {
+        const filePath = path.join(dir, file);
+        if (fs.statSync(filePath).isDirectory()) {
+          makeExecutable(filePath);
+        } else if (file.endsWith('.sh')) {
+          fs.chmodSync(filePath, 0o755);
+        }
+      });
+    };
+    makeExecutable(targetDir);
+
+    // 6. Install dependencies
+    console.log(pc.blue('\nInstalling dependencies (this may take a minute)...'));
+
+    // Frontend installation
+    console.log(pc.cyan('  Installing frontend dependencies...'));
+    execSync('npm ci', { cwd: targetFrontend, stdio: 'inherit' });
+
+    // Backend installation
+    console.log(pc.cyan('  Setting up backend virtual environment...'));
+    const pythonCmd = process.platform === 'win32' ? 'python' : 'python3';
+    try {
+      execSync(`${pythonCmd} -m venv venv`, { cwd: targetBackend, stdio: 'inherit' });
+      
+      const pipPath = process.platform === 'win32' 
+        ? path.join('venv', 'Scripts', 'pip') 
+        : path.join('venv', 'bin', 'pip');
+      
+      console.log(pc.cyan('  Installing backend dependencies...'));
+      execSync(`${pipPath} install -r requirements.txt`, { cwd: targetBackend, stdio: 'inherit' });
+    } catch (e) {
+      console.log(pc.yellow('  Could not set up Python virtual environment automatically. Please set it up manually.'));
+    }
+
+    console.log(pc.green(`\nSuccess! Created ${projectName} at ${targetDir}`));
+    console.log('\nInside that directory, you can run several commands:\n');
+
+    console.log(`  ${pc.cyan('./start.sh')}`);
+    console.log('    Starts both the backend and frontend development servers.\n');
+
+    console.log(`  ${pc.cyan('./test.sh')}`);
+    console.log('    Runs tests for both frontend and backend.\n');
+
+    console.log(`  ${pc.cyan('./lint.sh')}`);
+    console.log('    Lints and formats both frontend and backend code.\n');
+
+    console.log('\nWe suggest that you begin by typing:\n');
+    console.log(pc.cyan(`  cd ${projectName}`));
+    console.log(pc.cyan('  ./start.sh'));
+    console.log('\nHappy coding!');
+
+  } catch (error) {
+    console.error(pc.red('Error scaffolding project:'), error);
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);