scaffly-cli 1.0.0

package/src/extras/github-actions.js

@@ -0,0 +1,71 @@
+/**
+ * Scaffly — GitHub Actions CI/CD extra
+ * Adds a CI workflow that runs on every push/PR to main.
+ *
+ * Steps:
+ *  1. Checkout code
+ *  2. Set up Node.js with npm cache
+ *  3. Install dependencies (npm ci)
+ *  4. Run linter (if a lint script is present)
+ *  5. Run tests (if a test script is present)
+ *  6. Build the project (if a build script is present)
+ */
+
+import path from 'path';
+import { writeFile } from '../utils/index.js';
+
+const CI_WORKFLOW = `name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  ci:
+    name: Lint, Test & Build
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js \${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: \${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint --if-present
+
+      - name: Run tests
+        run: npm test --if-present
+
+      - name: Build
+        run: npm run build --if-present
+`;
+
+/**
+ * Adds a GitHub Actions CI workflow to the project.
+ *
+ * @param {string} projectPath - Absolute path to the project root
+ * @param {string} stack       - Selected stack identifier (unused but kept for API consistency)
+ */
+export async function apply(projectPath, stack) {
+  await writeFile(
+    path.join(projectPath, '.github/workflows/ci.yml'),
+    CI_WORKFLOW
+  );
+}

package/src/extras/husky.js

@@ -0,0 +1,50 @@
+/**
+ * Scaffly — Husky + lint-staged extra
+ * Sets up pre-commit Git hooks that run linting and formatting before each commit.
+ *
+ * Requires ESLint + Prettier to be installed to fully leverage lint-staged.
+ * If the ESLint extra was not selected, the hooks will still run but may warn
+ * about missing binaries.
+ */
+
+import path from 'path';
+import { writeFile, updatePackageJson, runCommand } from '../utils/index.js';
+
+/**
+ * Applies Husky + lint-staged configuration to the project.
+ *
+ * @param {string} projectPath - Absolute path to the project root
+ * @param {string} stack       - Selected stack identifier (unused but kept for API consistency)
+ */
+export async function apply(projectPath, stack) {
+  // ── Install packages ──────────────────────────────────────────────────────
+  await runCommand(
+    'npm',
+    ['install', '--save-dev', 'husky', 'lint-staged'],
+    projectPath
+  );
+
+  // ── Initialize Husky ──────────────────────────────────────────────────────
+  // Creates .husky/ directory and wires up git hooks via the prepare script.
+  // Note: requires an initialised git repository to take full effect.
+  await runCommand('npx', ['husky', 'init'], projectPath);
+
+  // ── Update package.json ───────────────────────────────────────────────────
+  // husky init already adds "prepare": "husky"; we add lint-staged config here.
+  await updatePackageJson(projectPath, {
+    'lint-staged': {
+      // JS/JSX files: lint then format
+      '*.{js,jsx}': ['eslint --fix --max-warnings 0', 'prettier --write'],
+      // Other files: format only
+      '*.{json,md,css,html}': ['prettier --write'],
+    },
+  });
+
+  // ── Write pre-commit hook ─────────────────────────────────────────────────
+  // Override the default hook created by `husky init` (which runs `npm test`)
+  // with our lint-staged runner.
+  await writeFile(
+    path.join(projectPath, '.husky/pre-commit'),
+    'npx lint-staged\n'
+  );
+}

package/src/extras/tailwind.js

@@ -0,0 +1,97 @@
+/**
+ * Scaffly — Tailwind CSS extra
+ * Adds Tailwind CSS (with PostCSS and Autoprefixer) to frontend projects.
+ * Only applicable to Next.js and React + Vite stacks.
+ */
+
+import path from 'path';
+import fse from 'fs-extra';
+import { writeFile, runCommand } from '../utils/index.js';
+
+// ── Tailwind config content per stack ─────────────────────────────────────────
+
+const TAILWIND_CONFIGS = {
+  nextjs: `/** @type {import('tailwindcss').Config} */
+const config = {
+  content: [
+    './pages/**/*.{js,ts,jsx,tsx,mdx}',
+    './components/**/*.{js,ts,jsx,tsx,mdx}',
+    './app/**/*.{js,ts,jsx,tsx,mdx}',
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};
+
+export default config;
+`,
+  vite: `/** @type {import('tailwindcss').Config} */
+const config = {
+  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};
+
+export default config;
+`,
+};
+
+// ── CSS file paths per stack ──────────────────────────────────────────────────
+
+const CSS_PATHS = {
+  nextjs: 'app/globals.css',
+  vite: 'src/index.css',
+};
+
+// ── Tailwind directives to prepend ────────────────────────────────────────────
+
+const TAILWIND_DIRECTIVES = `@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+`;
+
+/**
+ * Applies Tailwind CSS configuration to the project.
+ *
+ * @param {string} projectPath - Absolute path to the project root
+ * @param {string} stack       - Selected stack ('nextjs' or 'vite')
+ */
+export async function apply(projectPath, stack) {
+  // ── tailwind.config.js ────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, 'tailwind.config.js'),
+    TAILWIND_CONFIGS[stack]
+  );
+
+  // ── postcss.config.js ─────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, 'postcss.config.js'),
+    `export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+`
+  );
+
+  // ── Prepend Tailwind directives to the main CSS file ─────────────────────
+  const cssFilePath = path.join(projectPath, CSS_PATHS[stack]);
+  const existingCss = await fse.readFile(cssFilePath, 'utf-8').catch(() => '');
+
+  // Only prepend if directives aren't already present
+  if (!existingCss.includes('@tailwind base')) {
+    await fse.writeFile(cssFilePath, TAILWIND_DIRECTIVES + existingCss, 'utf-8');
+  }
+
+  // ── Install packages ──────────────────────────────────────────────────────
+  await runCommand(
+    'npm',
+    ['install', '--save-dev', 'tailwindcss', 'postcss', 'autoprefixer'],
+    projectPath
+  );
+}

package/src/generators/express.js

@@ -0,0 +1,165 @@
+/**
+ * Scaffly — Express generator
+ * Creates a Node.js REST API using Express with a layered folder structure.
+ */
+
+import path from 'path';
+import { writeFile, writeJson, runCommand } from '../utils/index.js';
+
+/**
+ * Generates a complete Express REST API project at the given path.
+ *
+ * @param {string} projectName - Used as the package name and in welcome messages
+ * @param {string} projectPath - Absolute path where the project will be created
+ */
+export async function generate(projectName, projectPath) {
+  // ── package.json ───────────────────────────────────────────────────────────
+  await writeJson(path.join(projectPath, 'package.json'), {
+    name: projectName,
+    version: '1.0.0',
+    type: 'module',
+    description: 'A REST API built with Express',
+    main: 'src/index.js',
+    scripts: {
+      start: 'node src/index.js',
+      dev: 'node --watch src/index.js',
+      test: 'echo "No tests yet" && exit 0',
+    },
+    dependencies: {
+      express: '^4.19.2',
+    },
+    devDependencies: {},
+  });
+
+  // ── src/index.js ──────────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, 'src/index.js'),
+    `import express from 'express';
+import { router } from './routes/index.js';
+import { errorHandler } from './middleware/error-handler.js';
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+
+// ── Middleware ─────────────────────────────────────────────────────────────
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+
+// ── Routes ─────────────────────────────────────────────────────────────────
+app.use('/api', router);
+
+// ── Error handling (must be the last middleware) ───────────────────────────
+app.use(errorHandler);
+
+// ── Start server ───────────────────────────────────────────────────────────
+app.listen(PORT, () => {
+  console.log(\`Server running at http://localhost:\${PORT}\`);
+});
+
+export default app;
+`
+  );
+
+  // ── src/routes/index.js ───────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, 'src/routes/index.js'),
+    `import { Router } from 'express';
+
+export const router = Router();
+
+/**
+ * GET /api/health
+ * Health-check endpoint — used by load balancers and uptime monitors.
+ */
+router.get('/health', (req, res) => {
+  res.json({ status: 'ok', timestamp: new Date().toISOString() });
+});
+
+/**
+ * GET /api/hello
+ * Example endpoint — replace or remove this in your real project.
+ */
+router.get('/hello', (req, res) => {
+  res.json({ message: 'Hello from ${projectName}!' });
+});
+`
+  );
+
+  // ── src/middleware/error-handler.js ───────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, 'src/middleware/error-handler.js'),
+    `/**
+ * Global error-handling middleware.
+ * Must have exactly 4 parameters so Express recognises it as an error handler.
+ *
+ * @param {Error}                err
+ * @param {import('express').Request}  req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ */
+export function errorHandler(err, req, res, next) {
+  const status = err.status || err.statusCode || 500;
+  const message = err.message || 'Internal Server Error';
+
+  console.error(\`[Error] \${req.method} \${req.path} → \${status}: \${message}\`);
+
+  res.status(status).json({
+    error: {
+      message,
+      // Include stack trace in development only
+      ...(process.env.NODE_ENV !== 'production' && { stack: err.stack }),
+    },
+  });
+}
+`
+  );
+
+  // ── .env ──────────────────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, '.env'),
+    `# Local environment variables — do NOT commit this file
+NODE_ENV=development
+PORT=3000
+`
+  );
+
+  // ── .env.example ─────────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, '.env.example'),
+    `# Copy this file to .env and fill in your own values
+NODE_ENV=development
+PORT=3000
+`
+  );
+
+  // ── .gitignore ────────────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, '.gitignore'),
+    `# Dependencies
+node_modules/
+
+# Environment — never commit secrets
+.env
+.env.local
+.env.*.local
+
+# Build artifacts
+dist/
+build/
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+
+# Editor
+.vscode/
+.idea/
+
+# Misc
+.DS_Store
+`
+  );
+
+  // ── Install dependencies ──────────────────────────────────────────────────
+  await runCommand('npm', ['install'], projectPath);
+}

package/src/generators/fastify.js

@@ -0,0 +1,160 @@
+/**
+ * Scaffly — Fastify generator
+ * Creates a high-performance Node.js REST API using Fastify with plugin architecture.
+ */
+
+import path from 'path';
+import { writeFile, writeJson, runCommand } from '../utils/index.js';
+
+/**
+ * Generates a complete Fastify REST API project at the given path.
+ *
+ * @param {string} projectName - Used as the package name and in welcome messages
+ * @param {string} projectPath - Absolute path where the project will be created
+ */
+export async function generate(projectName, projectPath) {
+  // ── package.json ───────────────────────────────────────────────────────────
+  await writeJson(path.join(projectPath, 'package.json'), {
+    name: projectName,
+    version: '1.0.0',
+    type: 'module',
+    description: 'A REST API built with Fastify',
+    main: 'src/index.js',
+    scripts: {
+      start: 'node src/index.js',
+      dev: 'node --watch src/index.js',
+      test: 'echo "No tests yet" && exit 0',
+    },
+    dependencies: {
+      fastify: '^4.28.1',
+      '@fastify/cors': '^9.0.1',
+    },
+    devDependencies: {},
+  });
+
+  // ── src/index.js ──────────────────────────────────────────────────────────
+  // Uses top-level await (available in ES modules, Node 18+)
+  await writeFile(
+    path.join(projectPath, 'src/index.js'),
+    `import Fastify from 'fastify';
+import cors from '@fastify/cors';
+import { healthRoutes } from './routes/health.js';
+import { helloRoutes } from './routes/hello.js';
+
+const fastify = Fastify({
+  // Enable built-in logger (pretty-prints in development)
+  logger: process.env.NODE_ENV !== 'production',
+});
+
+// ── Plugins ────────────────────────────────────────────────────────────────
+await fastify.register(cors, { origin: true });
+
+// ── Routes ─────────────────────────────────────────────────────────────────
+await fastify.register(healthRoutes, { prefix: '/api' });
+await fastify.register(helloRoutes, { prefix: '/api' });
+
+// ── Start server ───────────────────────────────────────────────────────────
+try {
+  const PORT = Number(process.env.PORT) || 3000;
+  await fastify.listen({ port: PORT, host: '0.0.0.0' });
+  console.log(\`Server running at http://localhost:\${PORT}\`);
+} catch (err) {
+  fastify.log.error(err);
+  process.exit(1);
+}
+`
+  );
+
+  // ── src/routes/health.js ──────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, 'src/routes/health.js'),
+    `/**
+ * Health-check route — used by load balancers and uptime monitors.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export async function healthRoutes(fastify) {
+  fastify.get('/health', async () => {
+    return { status: 'ok', timestamp: new Date().toISOString() };
+  });
+}
+`
+  );
+
+  // ── src/routes/hello.js ───────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, 'src/routes/hello.js'),
+    `/**
+ * Example route — replace or extend this in your real project.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export async function helloRoutes(fastify) {
+  // Schema validates the response and enables Fastify's fast serialization
+  const schema = {
+    response: {
+      200: {
+        type: 'object',
+        properties: {
+          message: { type: 'string' },
+        },
+      },
+    },
+  };
+
+  fastify.get('/hello', { schema }, async () => {
+    return { message: 'Hello from ${projectName}!' };
+  });
+}
+`
+  );
+
+  // ── .env ──────────────────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, '.env'),
+    `# Local environment variables — do NOT commit this file
+NODE_ENV=development
+PORT=3000
+`
+  );
+
+  // ── .env.example ─────────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, '.env.example'),
+    `# Copy this file to .env and fill in your own values
+NODE_ENV=development
+PORT=3000
+`
+  );
+
+  // ── .gitignore ────────────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, '.gitignore'),
+    `# Dependencies
+node_modules/
+
+# Environment — never commit secrets
+.env
+.env.local
+.env.*.local
+
+# Build artifacts
+dist/
+build/
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+
+# Editor
+.vscode/
+.idea/
+
+# Misc
+.DS_Store
+`
+  );
+
+  // ── Install dependencies ──────────────────────────────────────────────────
+  await runCommand('npm', ['install'], projectPath);
+}

package/src/generators/nextjs.js

@@ -0,0 +1,153 @@
+/**
+ * Scaffly — Next.js generator
+ * Creates a Next.js project using the App Router with sensible defaults.
+ */
+
+import path from 'path';
+import { writeFile, writeJson, runCommand } from '../utils/index.js';
+
+/**
+ * Generates a complete Next.js (App Router) project at the given path.
+ *
+ * @param {string} projectName - Used as the package name and page title
+ * @param {string} projectPath - Absolute path where the project will be created
+ */
+export async function generate(projectName, projectPath) {
+  // ── package.json ───────────────────────────────────────────────────────────
+  await writeJson(path.join(projectPath, 'package.json'), {
+    name: projectName,
+    version: '0.1.0',
+    private: true,
+    scripts: {
+      dev: 'next dev',
+      build: 'next build',
+      start: 'next start',
+    },
+    dependencies: {
+      next: '^14.2.5',
+      react: '^18.3.1',
+      'react-dom': '^18.3.1',
+    },
+    devDependencies: {},
+  });
+
+  // ── next.config.mjs ────────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, 'next.config.mjs'),
+    `/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+export default nextConfig;
+`
+  );
+
+  // ── app/layout.js ─────────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, 'app/layout.js'),
+    `import './globals.css';
+
+export const metadata = {
+  title: '${projectName}',
+  description: 'Generated by Scaffly',
+};
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+`
+  );
+
+  // ── app/page.js ───────────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, 'app/page.js'),
+    `export default function Home() {
+  return (
+    <main className="container">
+      <h1>Welcome to ${projectName}</h1>
+      <p>Built with Next.js &mdash; scaffolded by Scaffly</p>
+    </main>
+  );
+}
+`
+  );
+
+  // ── app/globals.css ───────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, 'app/globals.css'),
+    `*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen,
+    Ubuntu, sans-serif;
+  background: #ffffff;
+  color: #111111;
+  line-height: 1.6;
+}
+
+.container {
+  max-width: 960px;
+  margin: 4rem auto;
+  padding: 0 1.5rem;
+}
+
+h1 {
+  font-size: 2.5rem;
+  margin-bottom: 1rem;
+}
+`
+  );
+
+  // ── .env.local ────────────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, '.env.local'),
+    `# Local environment variables — do NOT commit this file
+# EXAMPLE_API_KEY=your_key_here
+`
+  );
+
+  // ── .gitignore ────────────────────────────────────────────────────────────
+  await writeFile(
+    path.join(projectPath, '.gitignore'),
+    `# Dependencies
+node_modules/
+
+# Next.js build output
+.next/
+out/
+
+# Production
+build/
+dist/
+
+# Environment variables — never commit secrets
+.env
+.env.local
+.env.*.local
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Vercel
+.vercel
+
+# Misc
+.DS_Store
+*.pem
+`
+  );
+
+  // ── Install dependencies ──────────────────────────────────────────────────
+  await runCommand('npm', ['install'], projectPath);
+}