scaffly-cli 1.0.0

package/README.md

@@ -0,0 +1,150 @@
+# Scaffly
+
+[![npm version](https://img.shields.io/npm/v/scaffly.svg?style=flat-square)](https://www.npmjs.com/package/scaffly)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![GitHub Stars](https://img.shields.io/github/stars/ViniLF/scaffly?style=flat-square)](https://github.com/ViniLF/scaffly/stargazers)
+[![Node.js Version](https://img.shields.io/node/v/scaffly.svg?style=flat-square)](https://nodejs.org)
+
+> A fast, interactive CLI tool for scaffolding modern web and Node.js projects.
+
+---
+
+## Features
+
+- **Interactive prompts** — beautiful terminal UI powered by `@clack/prompts`
+- **4 supported stacks** — Next.js, React + Vite, Express, and Fastify
+- **Optional extras** — pick and choose: ESLint, Prettier, Husky, Tailwind CSS, Docker, GitHub Actions
+- **Production-ready boilerplate** — sensible defaults, clean folder structure
+- **Zero config required** — just run and go
+
+---
+
+## Usage
+
+Run without installing (always uses the latest version):
+
+```bash
+npx scaffly
+```
+
+Or install globally for repeated use:
+
+```bash
+npm install -g scaffly
+scaffly
+```
+
+### What happens next
+
+1. Enter your **project name**
+2. Choose a **stack**
+3. Pick any **extras**
+4. Scaffly creates the project, installs dependencies, and configures your tooling
+
+---
+
+## Supported Stacks
+
+| Stack | Language | Best For |
+|---|---|---|
+| **Next.js** | React / JSX | Full-stack web applications, SSR, SSG |
+| **React + Vite** | React / JSX | SPAs, client-side frontends |
+| **Node.js + Express** | JavaScript (ESM) | REST APIs, microservices |
+| **Fastify** | JavaScript (ESM) | High-performance APIs |
+
+---
+
+## Extras
+
+| Extra | Description | Stacks |
+|---|---|---|
+| **ESLint + Prettier** | Linting and code formatting with zero-config defaults | All |
+| **Husky + lint-staged** | Pre-commit hooks that run linting before each commit | All |
+| **Tailwind CSS** | Utility-first CSS framework with PostCSS | Next.js, Vite |
+| **Docker** | `Dockerfile` + `docker-compose.yml` optimised per stack | All |
+| **GitHub Actions CI/CD** | Workflow that runs lint, test, and build on push/PR | All |
+
+---
+
+## Generated Project Structure
+
+### Next.js
+```
+my-app/
+├── app/
+│   ├── layout.js
+│   ├── page.js
+│   └── globals.css
+├── next.config.mjs
+├── package.json
+└── .gitignore
+```
+
+### React + Vite
+```
+my-app/
+├── src/
+│   ├── App.jsx
+│   ├── App.css
+│   ├── main.jsx
+│   └── index.css
+├── index.html
+├── vite.config.js
+├── package.json
+└── .gitignore
+```
+
+### Express / Fastify
+```
+my-app/
+├── src/
+│   ├── index.js
+│   ├── routes/
+│   └── middleware/     (Express only)
+├── .env
+├── .env.example
+├── package.json
+└── .gitignore
+```
+
+---
+
+## Requirements
+
+- **Node.js** `>= 18.0.0`
+- **npm** `>= 8.0.0`
+
+---
+
+## Contributing
+
+Contributions are welcome! Here's how to get started:
+
+1. **Fork** the repository
+2. **Clone** your fork: `git clone https://github.com/ViniLF/scaffly.git`
+3. **Install** dependencies: `npm install`
+4. **Create** a feature branch: `git checkout -b feat/your-feature`
+5. **Make** your changes and test them: `node bin/scaffly.js`
+6. **Commit** using [Conventional Commits](https://www.conventionalcommits.org/): `git commit -m "feat: add awesome feature"`
+7. **Push** to your branch: `git push origin feat/your-feature`
+8. **Open** a Pull Request
+
+### Adding a new stack
+
+1. Create `src/generators/your-stack.js` and export a `generate(projectName, projectPath)` function
+2. Register it in `bin/scaffly.js` under `GENERATORS`
+3. Add a prompt option in `src/prompts/index.js`
+4. Update this README
+
+### Adding a new extra
+
+1. Create `src/extras/your-extra.js` and export an `apply(projectPath, stack)` function
+2. Register it in `bin/scaffly.js` under `EXTRAS`
+3. Add a prompt option in `src/prompts/index.js`
+4. Update this README
+
+---
+
+## License
+
+[MIT](./LICENSE) © ViniLF

package/bin/scaffly.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+/**
+ * Scaffly — CLI entry point
+ *
+ * Flow:
+ *  1. Display intro banner
+ *  2. Collect project configuration via interactive prompts
+ *  3. Validate the target directory doesn't already exist
+ *  4. Run the selected stack generator (creates files + installs base deps)
+ *  5. Apply each selected extra (adds tooling on top)
+ *  6. Display a success message with next steps
+ */
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import path from 'path';
+import fse from 'fs-extra';
+
+import { collectAnswers } from '../src/prompts/index.js';
+import { generate as generateNextjs } from '../src/generators/nextjs.js';
+import { generate as generateVite } from '../src/generators/vite.js';
+import { generate as generateExpress } from '../src/generators/express.js';
+import { generate as generateFastify } from '../src/generators/fastify.js';
+import { apply as applyEslint } from '../src/extras/eslint.js';
+import { apply as applyHusky } from '../src/extras/husky.js';
+import { apply as applyTailwind } from '../src/extras/tailwind.js';
+import { apply as applyDocker } from '../src/extras/docker.js';
+import { apply as applyGithubActions } from '../src/extras/github-actions.js';
+
+// ── Registry maps ─────────────────────────────────────────────────────────────
+
+const GENERATORS = {
+  nextjs: generateNextjs,
+  vite: generateVite,
+  express: generateExpress,
+  fastify: generateFastify,
+};
+
+const EXTRAS = {
+  eslint: applyEslint,
+  husky: applyHusky,
+  tailwind: applyTailwind,
+  docker: applyDocker,
+  'github-actions': applyGithubActions,
+};
+
+const STACK_LABELS = {
+  nextjs: 'Next.js',
+  vite: 'React + Vite',
+  express: 'Node.js + Express',
+  fastify: 'Fastify',
+};
+
+const DEV_COMMANDS = {
+  nextjs: 'npm run dev',
+  vite: 'npm run dev',
+  express: 'npm run dev',
+  fastify: 'npm run dev',
+};
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.clear();
+
+  // Welcome banner
+  p.intro(
+    `${chalk.bgCyan.black(' scaffly ')} ${chalk.dim('— scaffold modern projects in seconds')}`
+  );
+
+  // ── Step 1: Collect answers ───────────────────────────────────────────────
+  const { projectName, stack, extras } = await collectAnswers();
+
+  const projectPath = path.resolve(process.cwd(), projectName);
+
+  // ── Step 2: Guard against existing directory ──────────────────────────────
+  if (await fse.pathExists(projectPath)) {
+    p.cancel(
+      `Directory ${chalk.cyan(projectName)} already exists. Choose a different project name.`
+    );
+    process.exit(1);
+  }
+
+  const s = p.spinner();
+
+  // ── Step 3: Generate base project ────────────────────────────────────────
+  s.start(`Scaffolding ${chalk.cyan(STACK_LABELS[stack])} project...`);
+
+  try {
+    await GENERATORS[stack](projectName, projectPath);
+  } catch (err) {
+    s.stop(chalk.red('Failed to scaffold project'));
+    p.cancel(`Generator error: ${err.message}`);
+    process.exit(1);
+  }
+
+  // ── Step 4: Apply extras ──────────────────────────────────────────────────
+  for (const extra of extras) {
+    s.message(`Applying ${chalk.cyan(extra)}...`);
+
+    try {
+      await EXTRAS[extra](projectPath, stack);
+    } catch (err) {
+      // Extras are non-fatal — warn and continue
+      s.message(chalk.yellow(`Warning: ${extra} could not be fully applied`));
+      p.log.warn(`${extra} failed: ${err.message}`);
+    }
+  }
+
+  s.stop(chalk.green('Done!'));
+
+  // ── Step 5: Show next steps ───────────────────────────────────────────────
+  const note = buildNextSteps(projectName, stack, extras);
+  p.note(note, chalk.bold('Next steps'));
+
+  p.outro(
+    `Built something cool? Give Scaffly a star on GitHub! ${chalk.dim('github.com/ViniLF/scaffly')}`
+  );
+}
+
+/**
+ * Builds the formatted "next steps" message shown after a successful scaffold.
+ *
+ * @param {string}   projectName
+ * @param {string}   stack
+ * @param {string[]} extras
+ * @returns {string}
+ */
+function buildNextSteps(projectName, stack, extras) {
+  const steps = [
+    `${chalk.dim('1.')} cd ${chalk.cyan(projectName)}`,
+    `${chalk.dim('2.')} ${chalk.cyan(DEV_COMMANDS[stack])}`,
+  ];
+
+  if (stack === 'nextjs' || stack === 'vite') {
+    steps.push(`${chalk.dim('3.')} Open ${chalk.cyan('http://localhost:3000')}`);
+  } else {
+    steps.push(`${chalk.dim('3.')} Test: ${chalk.cyan('curl http://localhost:3000/api/health')}`);
+  }
+
+  if (extras.includes('husky')) {
+    steps.push('');
+    steps.push(
+      `${chalk.dim('Tip:')} Run ${chalk.cyan('git init && npm run prepare')} to activate Husky hooks`
+    );
+  }
+
+  if (extras.includes('docker')) {
+    steps.push('');
+    steps.push(`${chalk.dim('Docker:')} ${chalk.cyan('docker compose up --build')}`);
+  }
+
+  return steps.join('\n');
+}
+
+// ── Run ───────────────────────────────────────────────────────────────────────
+
+main().catch((err) => {
+  console.error(chalk.red('\nUnexpected error:'), err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "scaffly-cli",
+  "version": "1.0.0",
+  "description": "A fast, interactive CLI tool for scaffolding modern web and Node.js projects",
+  "type": "module",
+  "bin": {
+    "scaffly": "./bin/scaffly.js"
+  },
+  "scripts": {
+    "start": "node bin/scaffly.js",
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "keywords": [
+    "cli",
+    "scaffold",
+    "boilerplate",
+    "nextjs",
+    "react",
+    "vite",
+    "express",
+    "fastify"
+  ],
+  "author": "ViniLF",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "chalk": "^5.3.0",
+    "execa": "^9.3.0",
+    "fs-extra": "^11.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/extras/docker.js

@@ -0,0 +1,185 @@
+/**
+ * Scaffly — Docker extra
+ * Adds a Dockerfile, docker-compose.yml, and .dockerignore tailored to the stack.
+ *
+ * Strategy:
+ *  - Next.js / Vite: multi-stage build (build → serve)
+ *  - Express / Fastify: single-stage Node.js image (production deps only)
+ */
+
+import path from 'path';
+import { writeFile } from '../utils/index.js';
+
+// ── Dockerfiles per stack ─────────────────────────────────────────────────────
+
+const DOCKERFILES = {
+  nextjs: `# ── Stage 1: Install dependencies ────────────────────────────────────────
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+
+# ── Stage 2: Build the application ────────────────────────────────────────
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+# ── Stage 3: Production image ──────────────────────────────────────────────
+FROM node:20-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+# Copy only what's needed to run the app
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+
+EXPOSE 3000
+ENV PORT=3000
+
+CMD ["node", "server.js"]
+`,
+
+  vite: `# ── Stage 1: Build the app ────────────────────────────────────────────────
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# ── Stage 2: Serve with Nginx ──────────────────────────────────────────────
+FROM nginx:alpine AS runner
+COPY --from=builder /app/dist /usr/share/nginx/html
+
+# Optional: custom Nginx config for SPA routing
+# COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+EXPOSE 80
+
+CMD ["nginx", "-g", "daemon off;"]
+`,
+
+  express: `FROM node:20-alpine
+WORKDIR /app
+
+# Install production dependencies only
+COPY package*.json ./
+RUN npm ci --omit=dev
+
+# Copy application source
+COPY . .
+
+EXPOSE 3000
+ENV NODE_ENV=production
+
+CMD ["npm", "start"]
+`,
+
+  fastify: `FROM node:20-alpine
+WORKDIR /app
+
+# Install production dependencies only
+COPY package*.json ./
+RUN npm ci --omit=dev
+
+# Copy application source
+COPY . .
+
+EXPOSE 3000
+ENV NODE_ENV=production
+
+CMD ["npm", "start"]
+`,
+};
+
+// ── docker-compose.yml per stack ─────────────────────────────────────────────
+
+const COMPOSE_FILES = {
+  nextjs: `services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+    restart: unless-stopped
+`,
+
+  vite: `services:
+  app:
+    build: .
+    ports:
+      - "80:80"
+    restart: unless-stopped
+`,
+
+  express: `services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+    restart: unless-stopped
+`,
+
+  fastify: `services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+    restart: unless-stopped
+`,
+};
+
+// ── .dockerignore (shared across stacks) ──────────────────────────────────────
+
+const DOCKERIGNORE = `# Source control
+.git
+.gitignore
+
+# Dependencies (will be re-installed inside the container)
+node_modules
+
+# Build output (re-built inside the container)
+dist
+build
+.next
+
+# Environment files — never bake secrets into an image
+.env
+.env.local
+.env.*.local
+
+# Dev tooling
+.eslintrc*
+.prettierrc*
+.husky
+
+# OS artifacts
+.DS_Store
+Thumbs.db
+
+# Docs
+README.md
+`;
+
+/**
+ * Adds Docker support files to the project.
+ *
+ * @param {string} projectPath - Absolute path to the project root
+ * @param {string} stack       - Selected stack identifier
+ */
+export async function apply(projectPath, stack) {
+  await writeFile(path.join(projectPath, 'Dockerfile'), DOCKERFILES[stack]);
+  await writeFile(path.join(projectPath, 'docker-compose.yml'), COMPOSE_FILES[stack]);
+  await writeFile(path.join(projectPath, '.dockerignore'), DOCKERIGNORE);
+}

package/src/extras/eslint.js

@@ -0,0 +1,145 @@
+/**
+ * Scaffly — ESLint + Prettier extra
+ * Adds code linting (ESLint) and formatting (Prettier) to the generated project.
+ * Config is tailored to the selected stack.
+ */
+
+import path from 'path';
+import { writeFile, writeJson, updatePackageJson, runCommand } from '../utils/index.js';
+
+// ── ESLint configs per stack ──────────────────────────────────────────────────
+
+const ESLINT_CONFIGS = {
+  nextjs: {
+    env: { browser: true, es2021: true, node: true },
+    extends: ['next/core-web-vitals', 'plugin:prettier/recommended'],
+    rules: {},
+  },
+  vite: {
+    env: { browser: true, es2021: true },
+    extends: [
+      'eslint:recommended',
+      'plugin:react/recommended',
+      'plugin:react-hooks/recommended',
+      'plugin:prettier/recommended',
+    ],
+    settings: {
+      react: { version: 'detect' },
+    },
+    rules: {
+      'react/react-in-jsx-scope': 'off', // Not needed in React 17+
+      'react/prop-types': 'off',
+    },
+  },
+  express: {
+    env: { node: true, es2021: true },
+    extends: ['eslint:recommended', 'plugin:prettier/recommended'],
+    parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+    rules: {},
+  },
+  fastify: {
+    env: { node: true, es2021: true },
+    extends: ['eslint:recommended', 'plugin:prettier/recommended'],
+    parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+    rules: {},
+  },
+};
+
+// ── Packages to install per stack ─────────────────────────────────────────────
+
+const PACKAGES = {
+  nextjs: [
+    'eslint',
+    'eslint-config-next',
+    'prettier',
+    'eslint-config-prettier',
+    'eslint-plugin-prettier',
+  ],
+  vite: [
+    'eslint',
+    'prettier',
+    'eslint-config-prettier',
+    'eslint-plugin-prettier',
+    'eslint-plugin-react',
+    'eslint-plugin-react-hooks',
+  ],
+  express: ['eslint', 'prettier', 'eslint-config-prettier', 'eslint-plugin-prettier'],
+  fastify: ['eslint', 'prettier', 'eslint-config-prettier', 'eslint-plugin-prettier'],
+};
+
+// ── Lint scripts per stack ────────────────────────────────────────────────────
+
+const LINT_SCRIPTS = {
+  nextjs: {
+    lint: 'next lint',
+    'lint:fix': 'next lint --fix',
+  },
+  vite: {
+    lint: 'eslint . --ext .js,.jsx --max-warnings 0',
+    'lint:fix': 'eslint . --ext .js,.jsx --fix',
+  },
+  express: {
+    lint: 'eslint . --ext .js --max-warnings 0',
+    'lint:fix': 'eslint . --ext .js --fix',
+  },
+  fastify: {
+    lint: 'eslint . --ext .js --max-warnings 0',
+    'lint:fix': 'eslint . --ext .js --fix',
+  },
+};
+
+/**
+ * Applies ESLint + Prettier configuration to the project.
+ *
+ * @param {string} projectPath - Absolute path to the project root
+ * @param {string} stack       - Selected stack identifier
+ */
+export async function apply(projectPath, stack) {
+  // Write .eslintrc.json
+  await writeJson(path.join(projectPath, '.eslintrc.json'), ESLINT_CONFIGS[stack]);
+
+  // Write .prettierrc
+  await writeJson(path.join(projectPath, '.prettierrc'), {
+    semi: true,
+    singleQuote: true,
+    tabWidth: 2,
+    trailingComma: 'es5',
+    printWidth: 80,
+    arrowParens: 'always',
+  });
+
+  // Write .eslintignore
+  await writeFile(
+    path.join(projectPath, '.eslintignore'),
+    `node_modules
+dist
+build
+.next
+out
+`
+  );
+
+  // Write .prettierignore
+  await writeFile(
+    path.join(projectPath, '.prettierignore'),
+    `node_modules
+dist
+build
+.next
+out
+package-lock.json
+`
+  );
+
+  // Add lint and format scripts to package.json
+  await updatePackageJson(projectPath, {
+    scripts: {
+      ...LINT_SCRIPTS[stack],
+      format: 'prettier --write .',
+      'format:check': 'prettier --check .',
+    },
+  });
+
+  // Install ESLint + Prettier packages as dev dependencies
+  await runCommand('npm', ['install', '--save-dev', ...PACKAGES[stack]], projectPath);
+}