npm package: @masteryhub-its/cli
Description: CLI tool for generating project skeletons and boilerplates
Author: MasteryHub ITS
Latest version: 1.0.3

# MasteryHub ITS CLI

A CLI tool for generating project skeletons and boilerplates for various frameworks and stacks.

## Installation

### From npm (Public Registry)

The package is published to the public npm registry.

```bash
# Install globally
npm install -g @masteryhub-its/cli

# Or using yarn
yarn global add @masteryhub-its/cli

# Or using pnpm
pnpm add -g @masteryhub-its/cli
```

### Verify Installation

```bash
masteryhub --version
masteryhub --help
masteryhub list
```

### Local Development

For local development and contribution:

```bash
git clone https://gitlab.com/masteryhub-its/masteryhub-its-cli.git
cd masteryhub-its-cli
npm install
npm run build
npm link  # Link globally for development
```

## Usage

### Quick Start

```bash
# Interactive project creation (recommended)
masteryhub init

# This will guide you through:
# 1. Select project category (API, Frontend, Mobile, etc.)
# 2. Choose template (NestJS, React, Flutter, etc.)
# 3. Configure features (Database, Auth, Swagger, etc.)
# 4. Set up project details
```

### List Available Templates

```bash
masteryhub list
# or
masteryhub ls
```

### Generate a New Project

```bash
# Interactive mode (recommended)
masteryhub generate nestjs my-api

# Quick mode (uses defaults)
masteryhub generate nestjs my-api --yes

# Skip dependency installation
masteryhub generate nestjs my-api --yes --no-install

# Use specific package manager
masteryhub generate nestjs my-api --package-manager yarn
masteryhub generate nestjs my-api --package-manager pnpm
```

### Available Commands

- `masteryhub init [name]` - **Interactive project initialization** (recommended for first-time users)
- `masteryhub generate <type> [name]` - Generate a new project from a template
- `masteryhub list` or `masteryhub ls` - List all available templates and categories
- `masteryhub info <template>` - Show detailed information about a template
- `masteryhub --help` - Show help information
- `masteryhub --version` - Show version

### Quick Examples

```bash
# Interactive mode (best for beginners)
masteryhub init

# Quick generation
masteryhub generate nestjs my-api
masteryhub generate react my-app
masteryhub generate flutter my-mobile-app

# With options
masteryhub generate nestjs my-api --yes --package-manager yarn
```

📖 **For detailed usage guide, see [USAGE.md](./USAGE.md)**

### Command Options

#### `generate` command:

- `-y, --yes` - Skip prompts and use defaults
- `--no-install` - Skip dependency installation
- `--package-manager <pm>` - Package manager to use (npm, yarn, pnpm). Default: npm

## Available Templates

### API Frameworks

#### NestJS
Full-featured NestJS boilerplate with TypeScript, testing, and optional features:
- Database support (PostgreSQL, MongoDB, MySQL, SQLite)
- ORM (TypeORM, Prisma, Mongoose, Sequelize)
- GraphQL support
- JWT Authentication
- Swagger/OpenAPI documentation
- Docker configuration
- Validation
- Logging (Winston)
- Caching (Redis, In-Memory)
- Monitoring and Health Checks
- CI/CD pipelines (GitHub Actions, GitLab CI)

```bash
masteryhub generate nestjs my-api
```

#### Express
Express.js API with TypeScript:
- TypeScript configuration
- Optional database and ORM support
- Swagger documentation
- JWT authentication

```bash
masteryhub generate express my-api
```

#### Fastify
Fastify API with TypeScript:
- High-performance HTTP server
- TypeScript configuration
- Optional database and ORM support
- Swagger documentation
- JWT authentication
- Structured logging with Pino

```bash
masteryhub generate fastify my-api
```

### Frontend Frameworks

#### React
Modern React application with Vite:
- TypeScript
- Vite for fast development
- Modern React patterns

```bash
masteryhub generate react my-app
```

#### Vue
Vue 3 application with Vite:
- TypeScript
- Composition API
- Vite build tool

```bash
masteryhub generate vue my-app
```

### Full-Stack Frameworks

#### Next.js
Next.js 15 application with App Router:
- TypeScript
- App Router
- Tailwind CSS
- Server and Client Components
- Testing setup

```bash
masteryhub generate nextjs my-app
```

### Mobile

#### Flutter
Flutter mobile application:
- Dart language
- Material Design
- Cross-platform support

```bash
masteryhub generate flutter my-app
```

### PWA (Progressive Web Apps)

#### React PWA
React Progressive Web App:
- Service Worker
- Offline support
- Installable
- Vite PWA plugin

```bash
masteryhub generate react-pwa my-pwa
```

## Creating Custom Templates

Templates are stored in `src/templates/`. To create a new template:

1. Create a new directory in `src/templates/` with your template name
2. Add your template files
3. Use Handlebars syntax (`{{variable}}`) for dynamic content
4. Files ending with `.hbs` will be processed as templates
5. Add a `README.md` in the template directory for description

### Template Variables

The following variables are available in templates:

- `{{name}}` - Project name
- `{{description}}` - Project description
- `{{author}}` - Author name
- `{{version}}` - Project version
- `{{license}}` - License type

## Quick Start

Get started in 5 minutes:

```bash
# 1. List all available templates
masteryhub list

# 2. Interactive initialization (recommended for first-time users)
masteryhub init my-project

# 3. Or generate directly
masteryhub generate nestjs my-api

# 4. Get information about a template
masteryhub info nestjs

# 5. Generate with defaults (non-interactive)
masteryhub generate react my-app --yes

# 6. Use different package manager
masteryhub generate vue my-app --package-manager pnpm
```

### Your First Project

**Generate a NestJS API:**
```bash
masteryhub generate nestjs my-first-api
# Follow prompts: select database, ORM, features
cd my-first-api
cp .env.example .env
npm run start:dev
# API: http://localhost:3000
```

**Generate a React App:**
```bash
masteryhub generate react my-app
cd my-app
npm run dev
```

**Generate a Flutter App:**
```bash
masteryhub generate flutter my-app
cd my-app
flutter pub get
flutter run
```

## Examples

### New Features

The CLI now includes enhanced features:

- **New Commands**: `init` for interactive setup, `info` for template details
- **Enhanced Features**: Logging, caching (Redis/Memory), monitoring, CI/CD pipelines
- **Post-Generation**: Automatic Git initialization, `.env.example` creation, CI/CD setup
- **Progress Indicators**: Visual feedback during project generation
- **Better Error Handling**: Improved error messages and validation
- **Type-Safe Structures**: All projects follow company-standard folder structures with strict TypeScript typing
- **Automatic Folder Creation**: Standard folder structures are automatically created for each template type

### Standard Folder Structures

All generated projects follow company-standard folder structures defined with strict TypeScript types. Folders are automatically created during project generation.

**Key benefits:**
- **Consistency**: All projects follow the same organization
- **Type Safety**: Structures are defined with TypeScript types
- **Automatic Creation**: Folders are created automatically during project generation

**Example structures:**
- **NestJS**: `src/common/`, `src/modules/`, `src/config/`, `src/database/`
- **Express/Fastify**: `src/api/`, `src/common/`, `src/services/`, `src/config/`
- **Next.js/React/Vue**: `src/components/`, `src/lib/`, `src/hooks/`, `src/types/`
- **Flutter**: `lib/core/`, `lib/features/`, `lib/shared/`

### Detailed Examples

See [EXAMPLES.md](./EXAMPLES.md) for comprehensive examples including:
- API projects with different databases and ORMs
- Frontend applications
- Mobile apps
- PWAs
- Full-stack setups
- Microservices architectures

## Development

### Building

```bash
npm run build
```

### Running in Development

```bash
npm run dev generate nestjs test-project
```

### Project Structure

```text
masteryhub-its-cli/
├── src/
│   ├── commands/        # CLI commands
│   ├── templates/       # Project templates
│   ├── utils/           # Utility functions
│   └── index.ts         # Entry point
├── dist/                # Compiled output
├── package.json
└── tsconfig.json
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add your template or feature
4. Submit a merge request

## Deployment

This package is deployed to MasteryHub ITS private npm registry. See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed deployment instructions.

### Quick Deploy

```bash
# Build
npm run build

# Publish to private registry
npm run publish:private

# Bump version
npm run version:patch
```

## License

MIT

## Troubleshooting

### Authentication Issues

**Error:** `npm ERR! 401 Unauthorized`
- Verify token in `~/.npmrc`
- Check token hasn't expired
- Test: `npm whoami --registry=https://gitlab.com/api/v4/packages/npm/`

**Error:** `npm ERR! 404 Not Found`
- Check Package Registry is enabled in GitLab project settings
- Verify registry URL is correct
- Ensure token has `read_package_registry` and `write_package_registry` permissions

### Installation Issues

**Error:** `Command not found: masteryhub`
- Verify global installation: `npm list -g @masteryhub-its/cli`
- Try: `npm install -g @masteryhub-its/cli --force`

**Error:** Template not found
- Run `masteryhub list` to see available templates
- Check template name spelling

### Generation Issues

**Error:** Permission denied
- Check write permissions in target directory
- Try running with `sudo` (not recommended) or fix permissions

**Error:** Dependencies installation fails
- Check internet connection
- Try different package manager: `--package-manager yarn`
- Skip installation: `--no-install` and install manually

## Documentation

- [DEPLOYMENT.md](./DEPLOYMENT.md) - Deployment and publishing guide
- [EXAMPLES.md](./EXAMPLES.md) - Comprehensive usage examples