jru-express 1.0.0 → 1.0.2

package/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish JruExpress
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Publish
+        run: npm publish

package/CONTRIBUTING.md

@@ -0,0 +1,237 @@
+# Contributing to JruExpress
+
+Thank you for your interest in contributing to JruExpress. Contributions are welcome and appreciated. JruExpress is an evolving project, and there are many ways to help it improve.
+
+## What You Can Contribute
+
+- Bug fixes
+- New features
+- CLI improvements
+- Template improvements
+- Documentation
+- Tests
+- Developer experience improvements
+
+## Before You Start
+
+Please take a moment to review the following before contributing:
+
+1. **Read the [README.md](README.md).** Understand what JruExpress does and how it works.
+2. **Check existing issues and pull requests.** Search the issue tracker to see if your idea or bug has already been reported or is being worked on.
+3. **Avoid duplicate issues.** If a similar issue already exists, add a comment to it rather than creating a new one.
+4. **Open an issue first for large changes.** If you are planning a significant new feature, architectural change, or major improvement, open an issue first to discuss it with the maintainers. This helps avoid wasted effort and ensures the change aligns with the project's direction.
+
+Small documentation fixes, obvious bug fixes, or minor improvements generally do not require an issue.
+
+## How to Contribute
+
+### 1. Fork the Repository
+
+Go to the JruExpress repository on GitHub and click the **Fork** button to create your own copy of the repository.
+
+### 2. Clone Your Fork
+
+Clone your fork to your local machine:
+
+```bash
+git clone <your-fork-url>
+cd jru-express
+npm install
+```
+
+### 3. Create a Separate Branch
+
+**This is important.** Never work directly on the `main` branch. Every change must be developed in its own branch. This keeps `main` stable and makes it easier to manage pull requests.
+
+Create a descriptive branch based on the type of change you are making:
+
+```bash
+git checkout -b feature/add-typescript-template
+```
+
+For bug fixes:
+
+```bash
+git checkout -b fix/preserve-empty-directories
+```
+
+For documentation:
+
+```bash
+git checkout -b docs/improve-readme
+```
+
+### 4. Branch Naming Convention
+
+Use the following prefixes to name your branches clearly:
+
+| Prefix | Purpose | Example |
+|---|---|---|
+| `feature/` | New functionality | `feature/add-docker-template` |
+| `fix/` | Bug fixes | `fix/missing-gitkeep` |
+| `docs/` | Documentation changes | `docs/update-contributing` |
+| `refactor/` | Code restructuring without behavior change | `refactor/simplify-cli-parsing` |
+| `test/` | Adding or updating tests | `test/add-generator-tests` |
+| `chore/` | Maintenance, CI, config, etc. | `chore/update-dependencies` |
+
+Choose descriptive names that explain the purpose of the branch at a glance.
+
+### 5. Make Your Changes
+
+When making changes, keep the following in mind:
+
+- **Keep changes focused.** Each branch and pull request should address a single concern. Do not mix unrelated changes.
+- **Follow existing code style.** Match the formatting, naming conventions, and patterns already present in the codebase.
+- **Keep the CLI simple.** JruExpress is intentionally lightweight. Avoid introducing unnecessary complexity or heavy dependencies.
+- **Update documentation.** If your change affects how the tool is used, update the README or other relevant documentation.
+- **Add or update tests.** If applicable, include tests for your changes.
+
+### 6. Test Your Changes
+
+Before submitting a pull request, test your changes thoroughly.
+
+Link the package locally:
+
+```bash
+npm install
+npm link
+```
+
+Then test the generator from a different directory:
+
+```bash
+cd /tmp
+jru-express test-project
+cd test-project
+npm install
+npm run dev
+```
+
+Verify the following:
+
+- Project directories are created correctly.
+- All template files are generated.
+- `package.json` contains the correct scripts.
+- Express is installed and works.
+- Nodemon is installed and works.
+- `npm run dev` starts the server without errors.
+- `npm start` starts the server without errors.
+- Existing functionality is not broken.
+
+When you are done testing, unlink the global package:
+
+```bash
+npm uninstall -g jru-express
+```
+
+### 7. Commit Guidelines
+
+Write clear, meaningful commit messages. Each commit message should describe what was changed and why.
+
+Use this format:
+
+```
+<type>: <short description>
+```
+
+Examples:
+
+```
+feat: add TypeScript template
+fix: preserve empty template directories
+docs: improve installation instructions
+refactor: simplify template generation
+test: add generator integration tests
+chore: update commander dependency
+```
+
+Avoid meaningless commit messages such as:
+
+- `update`
+- `changes`
+- `stuff`
+- `final final`
+- `wip`
+
+### 8. Keep Commits Focused
+
+Each commit should represent a single logical change. Do not bundle unrelated modifications into the same commit. If you are fixing a bug and also refactoring nearby code, create separate commits for each.
+
+### 9. Push Your Branch
+
+When your changes are ready:
+
+```bash
+git push origin <your-branch-name>
+```
+
+### 10. Create a Pull Request
+
+Go to the JruExpress repository on GitHub and create a new Pull Request from your branch into the `main` branch.
+
+Your pull request should include:
+
+- A clear title that describes the change.
+- A description explaining **what** changed and **why**.
+- What testing you performed.
+- Screenshots or terminal output if applicable.
+
+### 11. Pull Request Checklist
+
+Before submitting, confirm the following:
+
+- [ ] I created a separate branch for my changes.
+- [ ] I tested my changes locally.
+- [ ] I did not modify unrelated files.
+- [ ] I updated documentation where necessary.
+- [ ] I used clear, descriptive commit messages.
+- [ ] I verified the generated project works correctly.
+- [ ] I have described my changes clearly in the pull request.
+
+### 12. Code Review
+
+After submitting a pull request, a maintainer will review it. You may be asked to make changes or improvements. Please address review feedback by pushing additional commits to the same branch. Do not close the pull request and open a new one.
+
+Once the pull request is approved, it will be merged into `main`.
+
+## Versioning and Publishing
+
+**Do not manually publish the npm package.** Package releases and npm publishing are managed by the project maintainer through the repository's release workflow.
+
+If the project uses automated publishing through GitHub Actions, your changes will be included in a future release after the pull request is merged. Submit your work through a Pull Request and the maintainer will handle the release process.
+
+## Reporting Bugs
+
+If you find a bug, please open an issue with the following information:
+
+- **Description.** A clear explanation of the problem.
+- **Steps to reproduce.** Exact commands or actions that trigger the bug.
+- **Expected behavior.** What you expected to happen.
+- **Actual behavior.** What actually happened.
+- **Node.js version.** Run `node --version` to find this.
+- **npm version.** Run `npm --version` to find this.
+- **Operating system.** (e.g., Windows 11, macOS, Ubuntu 22.04)
+- **JruExpress version.** Check your installed version.
+- **Terminal output.** Paste any relevant error messages or output.
+
+The more detail you provide, the easier it is to identify and fix the issue.
+
+## Feature Requests
+
+If you have an idea for a new feature or improvement, open an issue with:
+
+- **Description.** What you would like to see added.
+- **Use case.** Why this would be useful.
+- **Possible implementation.** If you have ideas on how it could work, share them.
+
+Not all feature requests will be implemented, but thoughtful suggestions are always reviewed and considered.
+
+## Code of Conduct
+
+Contributors are expected to communicate respectfully and constructively. Be kind in discussions, reviews, and issue comments. Disagreements are natural, but personal attacks, harassment, or dismissive behavior are not acceptable.
+
+## Final Note
+
+JruExpress is still at the beginning of its development. Every contribution, no matter how small, helps the project grow and improve. Whether it is a typo fix in the documentation, a bug report, or a new feature, it is valued.
+
+Thank you for taking the time to contribute.

package/README.md

@@ -0,0 +1,250 @@
+# JruExpress
+
+> A lightweight Express.js backend scaffolding CLI for quickly creating a clean and practical backend structure.
+
+## Introduction
+
+Starting a new Express.js backend project often involves the same repetitive steps: creating folders, setting up `package.json`, installing dependencies, writing boilerplate server code, and configuring scripts. While these tasks are simple individually, they add up every time you begin a new project.
+
+JruExpress solves this by generating a complete, ready-to-run Express.js backend project with a single command. It provides a sensible default folder structure, installs the necessary dependencies, and configures your scripts so you can start building immediately.
+
+JruExpress is designed to be a starting point, not a rigid framework. The generated project is plain JavaScript with no hidden magic, making it easy to understand, modify, and extend to fit your own preferences.
+
+## Current Status
+
+JruExpress is currently in its early stage. The core scaffolding functionality is working and available for use. This is just the beginning. JruExpress is being developed with the goal of becoming a more useful and flexible backend scaffolding tool, with more features, improvements, templates, and developer conveniences planned for the future.
+
+## Features
+
+### Current
+
+- Express project scaffolding via a single CLI command
+- Standard backend folder structure (`controllers`, `services`, `models`, `routes`, `middleware`, `config`, `utils`)
+- Automatic npm initialization
+- Automatic Express installation
+- Automatic Nodemon installation (as a dev dependency)
+- Development script (`npm run dev`) using Nodemon with file watching
+- Production/start script (`npm start`) using Node
+- Basic Express server boilerplate with JSON parsing and a health-check route
+- `.gitignore` preconfigured for `node_modules` and `.env`
+- Project README included in the generated structure
+
+### Future Ideas
+
+- Multiple project templates (e.g., REST API, GraphQL, microservice)
+- TypeScript support
+- Database connection templates (MongoDB, PostgreSQL, MySQL)
+- Authentication boilerplate
+- Docker and Docker Compose support
+- Environment configuration templates
+- Interactive CLI prompts for selecting options
+- Custom project configuration files
+- Testing setup and boilerplate
+- Improved error handling templates
+
+## Installation / Usage
+
+The primary way to use JruExpress is through `npx`:
+
+```bash
+npx jru-express <project-name>
+```
+
+Replace `<project-name>` with whatever you want your project directory to be called. For example:
+
+```bash
+npx jru-express backend
+```
+
+This will create a `backend/` directory in your current location with a fully scaffolded Express.js project.
+
+You can name the project anything you like:
+
+```bash
+npx jru-express my-api
+npx jru-express ecommerce-server
+npx jru-express auth-service
+```
+
+### What happens after running the command
+
+1. A new directory is created with the name you provided.
+2. The backend folder structure is generated inside it.
+3. npm is initialized automatically.
+4. Express is installed as a production dependency.
+5. Nodemon is installed as a development dependency.
+6. `npm start` and `npm run dev` scripts are configured in `package.json`.
+7. A basic Express server is ready to run.
+
+## Generated Structure
+
+After running the command, your project will contain the following structure:
+
+```text
+<project-name>/
+├── src/
+│   ├── config/
+│   ├── controllers/
+│   ├── middleware/
+│   ├── models/
+│   ├── routes/
+│   ├── services/
+│   ├── utils/
+│   └── app.js
+│
+├── server.js
+├── package.json
+├── .gitignore
+└── README.md
+```
+
+### Directory purposes
+
+| Directory | Purpose |
+|---|---|
+| `src/config/` | Configuration files such as database connections, API keys, and environment-specific settings. |
+| `src/controllers/` | Request handlers that receive incoming requests and return responses. |
+| `src/middleware/` | Custom middleware functions for authentication, validation, error handling, logging, etc. |
+| `src/models/` | Data models and schema definitions for your database or data layer. |
+| `src/routes/` | Route definitions that map HTTP endpoints to controller functions. |
+| `src/services/` | Business logic and reusable service functions separated from controllers. |
+| `src/utils/` | Utility functions, helpers, and shared small modules. |
+
+### File purposes
+
+| File | Purpose |
+|---|---|
+| `src/app.js` | Creates and configures the Express application. Exports the `app` instance. |
+| `server.js` | Entry point that imports the app and starts the HTTP server. |
+| `package.json` | Project metadata, dependencies, and scripts. |
+| `.gitignore` | Prevents `node_modules/` and `.env` from being committed to version control. |
+| `README.md` | Basic instructions for the generated project. |
+
+## Running the Generated Project
+
+After scaffolding, navigate into your project and start the development server:
+
+```bash
+cd backend
+npm run dev
+```
+
+The server will start on port 3000 by default. You will see output indicating the server is running. Nodemon will automatically restart the server whenever you change a file.
+
+To run the project without file watching (production-style):
+
+```bash
+npm start
+```
+
+### Development vs Production
+
+| Command | Tool | File watching | Use case |
+|---|---|---|---|
+| `npm run dev` | Nodemon | Yes | Active development with automatic restarts |
+| `npm start` | Node | No | Running the server in production or preview |
+
+The server listens on port 3000 by default. You can change this by setting the `PORT` environment variable.
+
+## Example
+
+A complete workflow from creation to running:
+
+```bash
+npx jru-express ecommerce-api
+cd ecommerce-api
+npm run dev
+```
+
+Expected output:
+
+```text
+Server running on port https://localhost:3000
+```
+
+You can then open `http://localhost:3000` in your browser or use a tool like `curl` to verify:
+
+```bash
+curl http://localhost:3000
+```
+
+This will return:
+
+```json
+{
+  "message": "JruExpress API is running"
+}
+```
+
+## Development
+
+If you want to work on JruExpress itself (the CLI generator), you can clone the repository and set it up locally:
+
+```bash
+git clone <repository-url>
+cd jru-express
+npm install
+```
+
+To test your changes locally, link the package:
+
+```bash
+npm link
+```
+
+This makes the `jru-express` command available globally using your local copy. You can then run it from any directory:
+
+```bash
+jru-express test-project
+```
+
+When you are done testing, you can unlink:
+
+```bash
+npm uninstall -g jru-express
+```
+
+## Project Philosophy
+
+JruExpress is built around a few straightforward principles:
+
+- **Simple scaffolding.** Generate a working project with one command. No complex configuration required.
+- **Minimal configuration.** The generated project uses sensible defaults. You are free to change anything.
+- **Familiar architecture.** The folder structure follows conventions that most Express developers already know.
+- **Easy customization.** Since everything is plain JavaScript with no hidden layers, you can modify any part of the generated project without fighting the tool.
+- **No unnecessary abstraction.** JruExpress generates code you can read, understand, and own.
+
+## Roadmap
+
+The following are potential improvements planned or being considered for future versions of JruExpress:
+
+- More project templates (REST API, GraphQL, microservice architectures)
+- TypeScript template support
+- Database connection templates (MongoDB, PostgreSQL, MySQL)
+- Authentication boilerplate with JWT or session-based options
+- Docker and Docker Compose configuration templates
+- Environment configuration with `.env` examples
+- Interactive CLI prompts for selecting project options
+- Custom project configuration through a config file
+- Testing setup with boilerplate test files
+- Improved error handling middleware templates
+- Logging configuration templates
+- API documentation setup (e.g., Swagger/OpenAPI)
+
+These are future directions and not all of them will necessarily be implemented. They represent areas where JruExpress could grow.
+
+## Contributing
+
+Contributions, suggestions, bug reports, and improvements are welcome. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guidelines before submitting changes.
+
+## License
+
+This project is licensed under the MIT License. See the [package.json](package.json) for details.
+
+## Closing
+
+JruExpress is at the beginning of its development. It aims to make starting an Express.js project a little faster and a little cleaner. The project will continue to evolve based on feedback and real-world use. If you find it useful, contributions and suggestions are always appreciated.
+
+---
+
+Made with ❤️ by Ruturaj

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jru-express",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "My basic Express backend generator",
   "main": "index.js",
   "bin": {
@@ -20,4 +20,4 @@
   "dependencies": {
     "commander": "^14.0.0"
   }
-}
+}