create-listablelabs-api 1.0.1

package/bin/commands/create.js

@@ -0,0 +1,481 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const ora = require('ora');
+const { execSync } = require('child_process');
+
+const TEMPLATE_DIR = path.join(__dirname, '..', '..', 'templates', 'base');
+
+async function create(projectName, options) {
+  console.log(chalk.cyan(`
+  ╦  ╦╔═╗╔╦╗╔═╗╔╗ ╦  ╔═╗╦  ╔═╗╔╗ ╔═╗
+  ║  ║╚═╗ ║ ╠═╣╠╩╗║  ║╣ ║  ╠═╣╠╩╗╚═╗
+  ╩═╝╩╚═╝ ╩ ╩ ╩╚═╝╩═╝╚═╝╩═╝╩ ╩╚═╝╚═╝
+  `));
+  console.log(chalk.gray('  Microservice Generator\n'));
+
+  // Validate project name
+  const validName = projectName
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+
+  if (validName !== projectName) {
+    console.log(chalk.yellow(`  Project name normalized to: ${validName}\n`));
+  }
+
+  const targetDir = path.resolve(options.directory, validName);
+
+  // Check if directory exists
+  if (fs.existsSync(targetDir)) {
+    const { overwrite } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'overwrite',
+        message: `Directory ${validName} already exists. Overwrite?`,
+        default: false,
+      },
+    ]);
+
+    if (!overwrite) {
+      console.log(chalk.red('  Aborted.'));
+      process.exit(1);
+    }
+    fs.removeSync(targetDir);
+  }
+
+  // Get project configuration
+  let config;
+  if (options.yes) {
+    config = {
+      serviceName: validName,
+      description: `${validName} microservice`,
+      port: 3000,
+      features: ['logging', 'validation', 'rate-limiting', 'error-handling'],
+      mongodbUri: '',
+    };
+  } else {
+    config = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'serviceName',
+        message: 'Service name:',
+        default: validName,
+      },
+      {
+        type: 'input',
+        name: 'description',
+        message: 'Description:',
+        default: `${validName} microservice`,
+      },
+      {
+        type: 'number',
+        name: 'port',
+        message: 'Port:',
+        default: 3000,
+      },
+      {
+        type: 'input',
+        name: 'mongodbUri',
+        message: 'MongoDB Atlas URI (leave blank to configure later):',
+        default: '',
+      },
+      {
+        type: 'checkbox',
+        name: 'features',
+        message: 'Select additional features:',
+        choices: [
+          { name: 'JWT Authentication', value: 'auth', checked: false },
+          { name: 'Swagger/OpenAPI Docs', value: 'swagger', checked: false },
+        ],
+      },
+    ]);
+  }
+
+  // Create project
+  const spinner = ora('Creating project structure...').start();
+
+  try {
+    // Copy template files
+    await fs.copy(TEMPLATE_DIR, targetDir);
+
+    // Update package.json
+    const pkgPath = path.join(targetDir, 'package.json');
+    const pkg = await fs.readJson(pkgPath);
+    pkg.name = config.serviceName;
+    pkg.description = config.description;
+
+    // Add auth dependencies if selected
+    if (config.features.includes('auth')) {
+      pkg.dependencies.jsonwebtoken = '^9.0.2';
+      pkg.dependencies.bcryptjs = '^2.4.3';
+    }
+
+    // Add swagger if selected
+    if (config.features.includes('swagger')) {
+      pkg.dependencies['swagger-jsdoc'] = '^6.2.8';
+      pkg.dependencies['swagger-ui-express'] = '^5.0.0';
+    }
+
+    await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+
+    // Update .env.example and create .env
+    const envPath = path.join(targetDir, '.env.example');
+    let envContent = await fs.readFile(envPath, 'utf8');
+    envContent = envContent.replace('SERVICE_NAME=your-service-name', `SERVICE_NAME=${config.serviceName}`);
+    envContent = envContent.replace('PORT=3000', `PORT=${config.port}`);
+    
+    // Set MongoDB URI if provided
+    if (config.mongodbUri) {
+      envContent = envContent.replace(
+        'MONGODB_URI=mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<database>?retryWrites=true&w=majority',
+        `MONGODB_URI=${config.mongodbUri}`
+      );
+    }
+
+    // Add JWT env vars if auth selected
+    if (config.features.includes('auth')) {
+      envContent += `
+# JWT Authentication
+JWT_SECRET=your-super-secret-key-change-in-production
+JWT_EXPIRES_IN=7d
+`;
+    }
+
+    await fs.writeFile(envPath, envContent);
+    await fs.copy(envPath, path.join(targetDir, '.env'));
+
+    // Add auth middleware if selected
+    if (config.features.includes('auth')) {
+      await createAuthMiddleware(targetDir);
+    }
+
+    // Add swagger if selected
+    if (config.features.includes('swagger')) {
+      await createSwaggerSetup(targetDir);
+    }
+
+    spinner.succeed('Project structure created');
+
+    // Initialize git
+    if (!options.skipGit) {
+      const gitSpinner = ora('Initializing git repository...').start();
+      try {
+        execSync('git init', { cwd: targetDir, stdio: 'ignore' });
+        execSync('git add -A', { cwd: targetDir, stdio: 'ignore' });
+        execSync('git commit -m "Initial commit from @listablelabs/create-api"', {
+          cwd: targetDir,
+          stdio: 'ignore',
+        });
+        gitSpinner.succeed('Git repository initialized');
+      } catch (err) {
+        gitSpinner.warn('Git initialization failed (git may not be installed)');
+      }
+    }
+
+    // Install dependencies
+    if (!options.skipInstall) {
+      const installSpinner = ora('Installing dependencies...').start();
+      try {
+        execSync('npm install', { cwd: targetDir, stdio: 'ignore' });
+        installSpinner.succeed('Dependencies installed');
+      } catch (err) {
+        installSpinner.fail('Failed to install dependencies. Run npm install manually.');
+      }
+    }
+
+    // Success message
+    console.log(chalk.green('\n  ✔ Project created successfully!\n'));
+    console.log(chalk.white('  Stack: Express + Zod + Pino + MongoDB Atlas\n'));
+    console.log(chalk.white('  Next steps:\n'));
+    console.log(chalk.cyan(`    cd ${validName}`));
+    if (options.skipInstall) {
+      console.log(chalk.cyan('    npm install'));
+    }
+    if (!config.mongodbUri) {
+      console.log(chalk.yellow('    # Add your MongoDB Atlas URI to .env'));
+    }
+    console.log(chalk.cyan('    npm run dev\n'));
+    console.log(chalk.gray(`  Your API will be running at http://localhost:${config.port}`));
+    console.log(chalk.gray('  Health check: GET /health'));
+    console.log(chalk.gray('  API routes:   GET /api/v1/examples\n'));
+
+  } catch (err) {
+    spinner.fail('Failed to create project');
+    console.error(chalk.red(err.message));
+    process.exit(1);
+  }
+}
+
+async function createAuthMiddleware(targetDir) {
+  const authContent = `const jwt = require('jsonwebtoken');
+const { UnauthorizedError } = require('./errorHandler');
+
+/**
+ * JWT Authentication middleware
+ * Verifies JWT token from Authorization header
+ */
+const authenticate = (req, res, next) => {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    throw new UnauthorizedError('No token provided');
+  }
+
+  const token = authHeader.split(' ')[1];
+
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    req.user = decoded;
+    next();
+  } catch (err) {
+    throw new UnauthorizedError('Invalid or expired token');
+  }
+};
+
+/**
+ * Optional authentication - sets req.user if valid token exists
+ */
+const optionalAuth = (req, res, next) => {
+  const authHeader = req.headers.authorization;
+
+  if (authHeader && authHeader.startsWith('Bearer ')) {
+    const token = authHeader.split(' ')[1];
+    try {
+      req.user = jwt.verify(token, process.env.JWT_SECRET);
+    } catch (err) {
+      // Token invalid, but that's okay for optional auth
+    }
+  }
+
+  next();
+};
+
+/**
+ * Generate JWT token
+ */
+const generateToken = (payload) => {
+  return jwt.sign(payload, process.env.JWT_SECRET, {
+    expiresIn: process.env.JWT_EXPIRES_IN || '7d',
+  });
+};
+
+module.exports = { authenticate, optionalAuth, generateToken };
+`;
+
+  await fs.writeFile(path.join(targetDir, 'src', 'middlewares', 'auth.js'), authContent);
+
+  // Update middleware index
+  const indexPath = path.join(targetDir, 'src', 'middlewares', 'index.js');
+  let indexContent = await fs.readFile(indexPath, 'utf8');
+  indexContent = indexContent.replace(
+    "const { defaultLimiter, strictLimiter, createLimiter } = require('./rateLimiter');",
+    `const { defaultLimiter, strictLimiter, createLimiter } = require('./rateLimiter');
+const { authenticate, optionalAuth, generateToken } = require('./auth');`
+  );
+  indexContent = indexContent.replace(
+    '  createLimiter,\n};',
+    `  createLimiter,
+
+  // Authentication
+  authenticate,
+  optionalAuth,
+  generateToken,
+};`
+  );
+  await fs.writeFile(indexPath, indexContent);
+}
+
+async function createDatabaseConnection(targetDir, dbType) {
+  let dbContent;
+
+  if (dbType === 'postgres') {
+    dbContent = `const { Pool } = require('pg');
+const { logger } = require('../utils/logger');
+const config = require('../config');
+
+const pool = new Pool({
+  host: process.env.DB_HOST,
+  port: process.env.DB_PORT,
+  database: process.env.DB_NAME,
+  user: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+  max: 20, // Max connections in pool
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+});
+
+pool.on('connect', () => {
+  logger.debug('New database connection established');
+});
+
+pool.on('error', (err) => {
+  logger.error({ err }, 'Unexpected database error');
+});
+
+/**
+ * Query helper with logging
+ */
+const query = async (text, params) => {
+  const start = Date.now();
+  try {
+    const result = await pool.query(text, params);
+    const duration = Date.now() - start;
+    logger.debug({ query: text, duration, rows: result.rowCount }, 'Database query executed');
+    return result;
+  } catch (err) {
+    logger.error({ err, query: text }, 'Database query failed');
+    throw err;
+  }
+};
+
+/**
+ * Get a client from the pool for transactions
+ */
+const getClient = () => pool.connect();
+
+/**
+ * Health check for database
+ */
+const healthCheck = async () => {
+  try {
+    await pool.query('SELECT 1');
+    return true;
+  } catch (err) {
+    return false;
+  }
+};
+
+module.exports = { pool, query, getClient, healthCheck };
+`;
+  } else if (dbType === 'mongodb') {
+    dbContent = `const mongoose = require('mongoose');
+const { logger } = require('../utils/logger');
+
+const connectDB = async () => {
+  try {
+    const conn = await mongoose.connect(process.env.MONGODB_URI, {
+      maxPoolSize: 10,
+    });
+    logger.info({ host: conn.connection.host }, 'MongoDB connected');
+  } catch (err) {
+    logger.fatal({ err }, 'MongoDB connection failed');
+    process.exit(1);
+  }
+};
+
+mongoose.connection.on('disconnected', () => {
+  logger.warn('MongoDB disconnected');
+});
+
+mongoose.connection.on('error', (err) => {
+  logger.error({ err }, 'MongoDB error');
+});
+
+/**
+ * Health check for database
+ */
+const healthCheck = async () => {
+  return mongoose.connection.readyState === 1;
+};
+
+module.exports = { connectDB, healthCheck };
+`;
+  } else if (dbType === 'mysql') {
+    dbContent = `const mysql = require('mysql2/promise');
+const { logger } = require('../utils/logger');
+
+const pool = mysql.createPool({
+  host: process.env.DB_HOST,
+  port: process.env.DB_PORT,
+  database: process.env.DB_NAME,
+  user: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+  waitForConnections: true,
+  connectionLimit: 20,
+  queueLimit: 0,
+});
+
+/**
+ * Query helper with logging
+ */
+const query = async (sql, params) => {
+  const start = Date.now();
+  try {
+    const [rows] = await pool.execute(sql, params);
+    const duration = Date.now() - start;
+    logger.debug({ query: sql, duration }, 'Database query executed');
+    return rows;
+  } catch (err) {
+    logger.error({ err, query: sql }, 'Database query failed');
+    throw err;
+  }
+};
+
+/**
+ * Health check for database
+ */
+const healthCheck = async () => {
+  try {
+    await pool.query('SELECT 1');
+    return true;
+  } catch (err) {
+    return false;
+  }
+};
+
+module.exports = { pool, query, healthCheck };
+`;
+  }
+
+  await fs.ensureDir(path.join(targetDir, 'src', 'database'));
+  await fs.writeFile(path.join(targetDir, 'src', 'database', 'index.js'), dbContent);
+}
+
+async function createSwaggerSetup(targetDir) {
+  const swaggerContent = `const swaggerJsdoc = require('swagger-jsdoc');
+const swaggerUi = require('swagger-ui-express');
+const config = require('../config');
+
+const options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: \`\${config.serviceName} API\`,
+      version: '1.0.0',
+      description: \`API documentation for \${config.serviceName}\`,
+    },
+    servers: [
+      {
+        url: \`http://localhost:\${config.port}\`,
+        description: 'Development server',
+      },
+    ],
+    components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT',
+        },
+      },
+    },
+  },
+  apis: ['./src/routes/**/*.js'],
+};
+
+const specs = swaggerJsdoc(options);
+
+const setupSwagger = (app) => {
+  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
+};
+
+module.exports = { setupSwagger, specs };
+`;
+
+  await fs.writeFile(path.join(targetDir, 'src', 'utils', 'swagger.js'), swaggerContent);
+}
+
+module.exports = create;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "create-listablelabs-api",
+  "version": "1.0.1",
+  "description": "CLI to scaffold ListableLabs microservices",
+  "bin": {
+    "create-listablelabs-api": "./bin/cli.js",
+    "listablelabs": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "templates"
+  ],
+  "keywords": [
+    "listablelabs",
+    "microservice",
+    "api",
+    "scaffold",
+    "cli",
+    "express",
+    "mongodb",
+    "zod"
+  ],
+  "author": "ListableLabs",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^8.2.6",
+    "ora": "^5.4.1"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/listablelabs/create-api.git"
+  }
+}

package/templates/base/.dockerignore

@@ -0,0 +1,19 @@
+node_modules
+npm-debug.log
+.env
+.env.local
+.git
+.gitignore
+.dockerignore
+Dockerfile
+docker-compose*.yml
+README.md
+.nyc_output
+coverage
+.vscode
+.idea
+*.md
+tests
+__tests__
+*.test.js
+*.spec.js

package/templates/base/.env.example

@@ -0,0 +1,18 @@
+# Application
+NODE_ENV=development
+PORT=3000
+SERVICE_NAME=your-service-name
+
+# Logging
+LOG_LEVEL=info
+
+# Rate Limiting
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX_REQUESTS=100
+
+# MongoDB Atlas
+MONGODB_URI=mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<database>?retryWrites=true&w=majority
+
+# JWT (uncomment and configure as needed)
+# JWT_SECRET=your-super-secret-key
+# JWT_EXPIRES_IN=1d

package/templates/base/.eslintrc.js

@@ -0,0 +1,31 @@
+module.exports = {
+  env: {
+    node: true,
+    es2022: true,
+    jest: true,
+  },
+  extends: ['eslint:recommended'],
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+  },
+  rules: {
+    // Error prevention
+    'no-console': 'warn', // Use logger instead
+    'no-unused-vars': ['error', { argsIgnorePattern: '^_|next' }],
+    'no-return-await': 'error',
+
+    // Style consistency
+    'semi': ['error', 'always'],
+    'quotes': ['error', 'single', { avoidEscape: true }],
+    'comma-dangle': ['error', 'always-multiline'],
+    'indent': ['error', 2],
+
+    // Best practices
+    'eqeqeq': ['error', 'always'],
+    'curly': ['error', 'all'],
+    'no-var': 'error',
+    'prefer-const': 'error',
+    'prefer-arrow-callback': 'error',
+  },
+};

package/templates/base/Dockerfile

@@ -0,0 +1,48 @@
+# Build stage
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies (including devDependencies for build)
+RUN npm ci
+
+# Copy source code
+COPY . .
+
+# Production stage
+FROM node:20-alpine AS production
+
+# Create non-root user for security
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install only production dependencies
+RUN npm ci --only=production && \
+    npm cache clean --force
+
+# Copy application code
+COPY --from=builder /app/src ./src
+
+# Set ownership to non-root user
+RUN chown -R nodejs:nodejs /app
+
+# Switch to non-root user
+USER nodejs
+
+# Expose port
+EXPOSE 3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"
+
+# Start the application
+CMD ["node", "src/server.js"]