create-listablelabs-api 1.0.1

package/README.md

@@ -0,0 +1,142 @@
+# @listablelabs/create-api
+
+CLI tool to scaffold standardized ListableLabs microservices.
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @listablelabs/create-api
+
+# Or use npx (no install required)
+npx @listablelabs/create-api create my-service
+```
+
+## Usage
+
+### Create a New Service
+
+```bash
+# Interactive mode (recommended)
+listablelabs create my-service
+
+# Quick mode with defaults
+listablelabs create my-service -y
+
+# Specify directory
+listablelabs create my-service -d ./services
+
+# Skip npm install
+listablelabs create my-service --skip-install
+
+# Skip git initialization
+listablelabs create my-service --skip-git
+```
+
+### Add Components to Existing Project
+
+```bash
+# Add a new route + controller
+listablelabs add route
+listablelabs add route -n users
+
+# Add just a controller
+listablelabs add controller -n payment
+
+# Add a service
+listablelabs add service -n email
+
+# Add a middleware
+listablelabs add middleware -n cache
+
+# Add a model (auto-detects MongoDB/SQL)
+listablelabs add model -n user
+```
+
+## Features
+
+When creating a new service, you can choose:
+
+- **Logging** - Pino with pretty printing in dev
+- **Validation** - Joi request validation
+- **Rate Limiting** - Express rate limit
+- **Error Handling** - Centralized error handling with typed errors
+- **JWT Authentication** - Optional auth middleware
+- **Swagger/OpenAPI** - Optional API documentation
+- **Database** - PostgreSQL, MongoDB, or MySQL support
+
+## Project Structure
+
+```
+my-service/
+├── src/
+│   ├── config/           # Environment configuration
+│   ├── controllers/      # Request handlers
+│   ├── middlewares/      # Express middlewares
+│   ├── routes/v1/        # API routes
+│   ├── services/         # Business logic
+│   ├── models/           # Data models
+│   ├── utils/            # Utilities (logger, response)
+│   ├── app.js           # Express setup
+│   └── server.js        # Entry point
+├── tests/
+├── Dockerfile
+└── docker-compose.yml
+```
+
+## Publishing (Internal)
+
+```bash
+# Login to npm (or your private registry)
+npm login
+
+# Publish
+npm publish --access public
+```
+
+## Examples
+
+### Create a user service with PostgreSQL and auth:
+
+```bash
+$ listablelabs create user-service
+
+? Service name: user-service
+? Description: User management microservice
+? Port: 3001
+? Select features:
+  ◉ Pino Logging
+  ◉ Joi Validation
+  ◉ Rate Limiting
+  ◉ Error Handling
+  ◉ JWT Authentication
+  ◯ Swagger/OpenAPI Docs
+? Database: PostgreSQL
+
+✔ Project structure created
+✔ Git repository initialized
+✔ Dependencies installed
+
+✔ Project created successfully!
+
+Next steps:
+  cd user-service
+  npm run dev
+```
+
+### Add a products route:
+
+```bash
+$ cd user-service
+$ listablelabs add route -n products
+
+✔ Created products route and controller
+
+Files created:
+  - src/routes/v1/productsRoutes.js
+  - src/controllers/productsController.js
+
+Add to src/routes/v1/index.js:
+  const productsRoutes = require('./productsRoutes');
+  router.use('/products', productsRoutes);
+```

package/bin/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const packageJson = require('../package.json');
+
+program
+  .name('listablelabs')
+  .description('CLI to scaffold ListableLabs microservices')
+  .version(packageJson.version);
+
+program
+  .command('create <project-name>')
+  .description('Create a new ListableLabs API service')
+  .option('-d, --directory <dir>', 'Directory to create project in', '.')
+  .option('--skip-install', 'Skip npm install')
+  .option('--skip-git', 'Skip git initialization')
+  .option('-y, --yes', 'Skip prompts and use defaults')
+  .action(require('./commands/create'));
+
+program
+  .command('add <component>')
+  .description('Add a component to existing project (route, controller, model)')
+  .option('-n, --name <name>', 'Name of the component')
+  .action(require('./commands/add'));
+
+program.parse();
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  console.log(chalk.cyan(`
+  ╦  ╦╔═╗╔╦╗╔═╗╔╗ ╦  ╔═╗╦  ╔═╗╔╗ ╔═╗
+  ║  ║╚═╗ ║ ╠═╣╠╩╗║  ║╣ ║  ╠═╣╠╩╗╚═╗
+  ╩═╝╩╚═╝ ╩ ╩ ╩╚═╝╩═╝╚═╝╩═╝╩ ╩╚═╝╚═╝
+  `));
+  program.help();
+}

package/bin/commands/add.js

@@ -0,0 +1,460 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const ora = require('ora');
+
+async function add(component, options) {
+  // Check if we're in a listablelabs project
+  const pkgPath = path.join(process.cwd(), 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    console.log(chalk.red('  Error: Not in a Node.js project directory'));
+    process.exit(1);
+  }
+
+  const pkg = await fs.readJson(pkgPath);
+  if (!pkg.name || !pkg.name.includes('@listablelabs')) {
+    console.log(chalk.yellow('  Warning: This may not be a ListableLabs project'));
+  }
+
+  const componentType = component.toLowerCase();
+
+  switch (componentType) {
+    case 'route':
+    case 'routes':
+      await addRoute(options);
+      break;
+    case 'controller':
+      await addController(options);
+      break;
+    case 'model':
+      await addModel(options);
+      break;
+    case 'middleware':
+      await addMiddleware(options);
+      break;
+    case 'service':
+      await addService(options);
+      break;
+    default:
+      console.log(chalk.red(`  Unknown component type: ${component}`));
+      console.log(chalk.gray('  Available: route, controller, model, middleware, service'));
+      process.exit(1);
+  }
+}
+
+async function addRoute(options) {
+  let name = options.name;
+
+  if (!name) {
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Route name (e.g., users, products):',
+        validate: (input) => input.length > 0 || 'Name is required',
+      },
+    ]);
+    name = answers.name;
+  }
+
+  const routeName = name.toLowerCase().replace(/[^a-z0-9]/g, '');
+  const routeDir = path.join(process.cwd(), 'src', 'routes', 'v1');
+  const controllerDir = path.join(process.cwd(), 'src', 'controllers');
+
+  // Ensure directories exist
+  await fs.ensureDir(routeDir);
+  await fs.ensureDir(controllerDir);
+
+  const spinner = ora(`Creating ${routeName} route...`).start();
+
+  // Create route file
+  const routeContent = `const { Router } = require('express');
+const ${routeName}Controller = require('../../controllers/${routeName}Controller');
+const { validate, Joi } = require('../../middlewares');
+
+const router = Router();
+
+/**
+ * Validation schemas
+ */
+const schemas = {
+  getById: {
+    params: Joi.object({
+      id: Joi.string().required(),
+    }),
+  },
+  create: {
+    body: Joi.object({
+      // Add your fields here
+      name: Joi.string().min(1).max(255).required(),
+    }),
+  },
+  update: {
+    params: Joi.object({
+      id: Joi.string().required(),
+    }),
+    body: Joi.object({
+      name: Joi.string().min(1).max(255),
+    }),
+  },
+};
+
+/**
+ * @route   GET /api/v1/${routeName}
+ * @desc    Get all ${routeName}
+ */
+router.get('/', ${routeName}Controller.getAll);
+
+/**
+ * @route   GET /api/v1/${routeName}/:id
+ * @desc    Get ${routeName} by ID
+ */
+router.get('/:id', validate(schemas.getById), ${routeName}Controller.getById);
+
+/**
+ * @route   POST /api/v1/${routeName}
+ * @desc    Create new ${routeName}
+ */
+router.post('/', validate(schemas.create), ${routeName}Controller.create);
+
+/**
+ * @route   PUT /api/v1/${routeName}/:id
+ * @desc    Update ${routeName}
+ */
+router.put('/:id', validate(schemas.update), ${routeName}Controller.update);
+
+/**
+ * @route   DELETE /api/v1/${routeName}/:id
+ * @desc    Delete ${routeName}
+ */
+router.delete('/:id', validate(schemas.getById), ${routeName}Controller.remove);
+
+module.exports = router;
+`;
+
+  // Create controller file
+  const controllerContent = `const { asyncHandler, NotFoundError } = require('../middlewares');
+const { sendSuccess, sendCreated, sendPaginated, sendNoContent } = require('../utils/response');
+const { createChildLogger } = require('../utils/logger');
+
+const log = createChildLogger({ module: '${routeName}Controller' });
+
+/**
+ * Get all ${routeName}
+ */
+const getAll = asyncHandler(async (req, res) => {
+  const { page = 1, limit = 20 } = req.query;
+  log.info({ page, limit }, 'Fetching ${routeName}');
+
+  // TODO: Replace with actual database query
+  const items = [];
+  const total = 0;
+
+  sendPaginated(res, items, { page: +page, limit: +limit, total });
+});
+
+/**
+ * Get ${routeName} by ID
+ */
+const getById = asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  log.info({ id }, 'Fetching ${routeName} by ID');
+
+  // TODO: Replace with actual database query
+  const item = null;
+
+  if (!item) {
+    throw new NotFoundError(\`${routeName} with ID \${id} not found\`);
+  }
+
+  sendSuccess(res, item);
+});
+
+/**
+ * Create new ${routeName}
+ */
+const create = asyncHandler(async (req, res) => {
+  const data = req.body;
+  log.info({ data }, 'Creating ${routeName}');
+
+  // TODO: Replace with actual database insert
+  const newItem = { id: '1', ...data, createdAt: new Date() };
+
+  sendCreated(res, newItem);
+});
+
+/**
+ * Update ${routeName}
+ */
+const update = asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const data = req.body;
+  log.info({ id, data }, 'Updating ${routeName}');
+
+  // TODO: Replace with actual database update
+  const updatedItem = { id, ...data, updatedAt: new Date() };
+
+  sendSuccess(res, updatedItem, 200, '${routeName} updated');
+});
+
+/**
+ * Delete ${routeName}
+ */
+const remove = asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  log.info({ id }, 'Deleting ${routeName}');
+
+  // TODO: Replace with actual database delete
+
+  sendNoContent(res);
+});
+
+module.exports = {
+  getAll,
+  getById,
+  create,
+  update,
+  remove,
+};
+`;
+
+  await fs.writeFile(path.join(routeDir, `${routeName}Routes.js`), routeContent);
+  await fs.writeFile(path.join(controllerDir, `${routeName}Controller.js`), controllerContent);
+
+  spinner.succeed(`Created ${routeName} route and controller`);
+
+  console.log(chalk.gray(`
+  Files created:
+    - src/routes/v1/${routeName}Routes.js
+    - src/controllers/${routeName}Controller.js
+
+  Add to src/routes/v1/index.js:
+`));
+  console.log(chalk.cyan(`    const ${routeName}Routes = require('./${routeName}Routes');`));
+  console.log(chalk.cyan(`    router.use('/${routeName}', ${routeName}Routes);`));
+}
+
+async function addController(options) {
+  let name = options.name;
+
+  if (!name) {
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Controller name:',
+        validate: (input) => input.length > 0 || 'Name is required',
+      },
+    ]);
+    name = answers.name;
+  }
+
+  const controllerName = name.toLowerCase().replace(/[^a-z0-9]/g, '');
+  const controllerDir = path.join(process.cwd(), 'src', 'controllers');
+  await fs.ensureDir(controllerDir);
+
+  const spinner = ora(`Creating ${controllerName} controller...`).start();
+
+  const content = `const { asyncHandler, NotFoundError } = require('../middlewares');
+const { sendSuccess } = require('../utils/response');
+const { createChildLogger } = require('../utils/logger');
+
+const log = createChildLogger({ module: '${controllerName}Controller' });
+
+// Add your controller methods here
+
+module.exports = {
+  // export methods
+};
+`;
+
+  await fs.writeFile(path.join(controllerDir, `${controllerName}Controller.js`), content);
+  spinner.succeed(`Created ${controllerName}Controller.js`);
+}
+
+async function addService(options) {
+  let name = options.name;
+
+  if (!name) {
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Service name:',
+        validate: (input) => input.length > 0 || 'Name is required',
+      },
+    ]);
+    name = answers.name;
+  }
+
+  const serviceName = name.toLowerCase().replace(/[^a-z0-9]/g, '');
+  const serviceDir = path.join(process.cwd(), 'src', 'services');
+  await fs.ensureDir(serviceDir);
+
+  const spinner = ora(`Creating ${serviceName} service...`).start();
+
+  const content = `const { createChildLogger } = require('../utils/logger');
+
+const log = createChildLogger({ module: '${serviceName}Service' });
+
+/**
+ * ${serviceName} service
+ * Business logic layer
+ */
+class ${serviceName.charAt(0).toUpperCase() + serviceName.slice(1)}Service {
+  // Add your service methods here
+}
+
+module.exports = new ${serviceName.charAt(0).toUpperCase() + serviceName.slice(1)}Service();
+`;
+
+  await fs.writeFile(path.join(serviceDir, `${serviceName}Service.js`), content);
+  spinner.succeed(`Created ${serviceName}Service.js`);
+}
+
+async function addMiddleware(options) {
+  let name = options.name;
+
+  if (!name) {
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Middleware name:',
+        validate: (input) => input.length > 0 || 'Name is required',
+      },
+    ]);
+    name = answers.name;
+  }
+
+  const middlewareName = name.toLowerCase().replace(/[^a-z0-9]/g, '');
+  const middlewareDir = path.join(process.cwd(), 'src', 'middlewares');
+
+  const spinner = ora(`Creating ${middlewareName} middleware...`).start();
+
+  const content = `const { createChildLogger } = require('../utils/logger');
+
+const log = createChildLogger({ module: '${middlewareName}Middleware' });
+
+/**
+ * ${middlewareName} middleware
+ */
+const ${middlewareName} = (req, res, next) => {
+  // Add your middleware logic here
+  next();
+};
+
+module.exports = { ${middlewareName} };
+`;
+
+  await fs.writeFile(path.join(middlewareDir, `${middlewareName}.js`), content);
+  spinner.succeed(`Created ${middlewareName}.js middleware`);
+
+  console.log(chalk.gray(`
+  Don't forget to export in src/middlewares/index.js
+`));
+}
+
+async function addModel(options) {
+  let name = options.name;
+
+  if (!name) {
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Model name:',
+        validate: (input) => input.length > 0 || 'Name is required',
+      },
+    ]);
+    name = answers.name;
+  }
+
+  const modelName = name.toLowerCase().replace(/[^a-z0-9]/g, '');
+  const modelDir = path.join(process.cwd(), 'src', 'models');
+  await fs.ensureDir(modelDir);
+
+  // Check if mongoose is installed (MongoDB)
+  const pkgPath = path.join(process.cwd(), 'package.json');
+  const pkg = await fs.readJson(pkgPath);
+  const isMongoose = pkg.dependencies && pkg.dependencies.mongoose;
+
+  const spinner = ora(`Creating ${modelName} model...`).start();
+
+  let content;
+
+  if (isMongoose) {
+    const className = modelName.charAt(0).toUpperCase() + modelName.slice(1);
+    content = `const mongoose = require('mongoose');
+
+const ${modelName}Schema = new mongoose.Schema(
+  {
+    name: {
+      type: String,
+      required: true,
+      trim: true,
+    },
+    // Add more fields here
+  },
+  {
+    timestamps: true,
+  }
+);
+
+// Add indexes
+${modelName}Schema.index({ name: 1 });
+
+// Add methods
+${modelName}Schema.methods.toJSON = function () {
+  const obj = this.toObject();
+  delete obj.__v;
+  return obj;
+};
+
+module.exports = mongoose.model('${className}', ${modelName}Schema);
+`;
+  } else {
+    content = `/**
+ * ${modelName} model
+ * Define your data structure and database interactions here
+ */
+
+const ${modelName}Model = {
+  // Add your model methods here
+  
+  async findAll() {
+    // TODO: Implement database query
+    return [];
+  },
+
+  async findById(id) {
+    // TODO: Implement database query
+    return null;
+  },
+
+  async create(data) {
+    // TODO: Implement database insert
+    return { id: '1', ...data };
+  },
+
+  async update(id, data) {
+    // TODO: Implement database update
+    return { id, ...data };
+  },
+
+  async delete(id) {
+    // TODO: Implement database delete
+    return true;
+  },
+};
+
+module.exports = ${modelName}Model;
+`;
+  }
+
+  await fs.writeFile(path.join(modelDir, `${modelName}.js`), content);
+  spinner.succeed(`Created ${modelName} model`);
+}
+
+module.exports = add;