rapidkit 0.11.2 → 0.12.0

package/README.md

@@ -5,435 +5,161 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![GitHub Stars](https://img.shields.io/github/stars/getrapidkit/rapidkit-npm.svg?style=flat-square)](https://github.com/getrapidkit/rapidkit-npm/stargazers)
 
-> ⚠️ **BETA VERSION** - This is a companion tool for RapidKit Python framework.  
-> The stable production version of RapidKit will be released soon on PyPI.  
-> Until then, use `--demo` mode to create demo workspaces with bundled templates, or `--test-mode` to try the full RapidKit installation locally.
+> ⚠️ **PRE-RELEASE VERSION** - This is a companion tool for RapidKit framework.  
+> The stable production version of RapidKit Python will be released soon on PyPI.
 
-🚀 The easiest way to get started with RapidKit! This CLI tool creates development workspaces with two modes:
+🚀 The easiest way to create FastAPI and NestJS projects with RapidKit templates!
 
-1. **Demo Mode** (`--demo`) - Create a workspace with bundled FastAPI templates (no Python RapidKit required)
-2. **Full Mode** - Set up a Python environment with RapidKit installed (requires RapidKit on PyPI - coming soon!)
-
-**💡 Tip:** Use the [RapidKit VS Code Extension](https://marketplace.visualstudio.com/items?itemName=rapidkit.rapidkit-vscode) for a visual interface to create workspaces and projects!
+**💡 Tip:** Use the [RapidKit VS Code Extension](https://marketplace.visualstudio.com/items?itemName=rapidkit.rapidkit-vscode) for a visual interface!
 
 ## Quick Start
 
-### 🎨 Demo Mode (Available Now!)
-
-Create a demo workspace and generate multiple FastAPI projects instantly:
+### Create a FastAPI Project
 
 ```bash
-# Create demo workspace
-npx rapidkit my-workspace --demo
-cd my-workspace
-
-# Generate your first project
-node generate-demo.js api-project
-cd api-project
-poetry install
-poetry run dev
-
-# Go back and create more projects
-cd ..
-node generate-demo.js auth-service
-node generate-demo.js data-service
+npx rapidkit my-api --template fastapi
+cd my-api
+source .rapidkit/activate   # Enable rapidkit commands
+rapidkit init               # Install dependencies
+rapidkit dev                # Start dev server at http://localhost:8000
 ```
 
-**Perfect for:**
-- Quick prototyping and demos
-- Learning FastAPI and RapidKit project structure
-- Testing multiple microservices in one workspace
-- No Python RapidKit dependency required
-- **Try now while waiting for stable RapidKit release!**
-
-### 🚀 Full Mode (Coming Soon with Stable Release)
-
-Once RapidKit is published on PyPI, install for full features and modules:
+### Create a NestJS Project
 
 ```bash
-npx rapidkit my-workspace
-cd my-workspace
-source $(poetry env info --path)/bin/activate
-rapidkit create my-project
-```
-
-**Note:** Full mode requires RapidKit Python package on PyPI.  
-For now, use `--test-mode` flag if you have local RapidKit installation, or use `--demo` for workspace with bundled templates.
-
-## Understanding Workspaces
-
-**create-rapidkit** follows a workspace-based architecture:
-
-- **Workspace** = Container directory with development environment
-- **Projects** = Individual FastAPI/NestJS applications inside workspace
-
-### Demo Workspace Structure
-```
-my-workspace/              # Workspace (container)
-├── generate-demo.js       # Project generator script
-├── package.json          # npm configuration
-├── README.md             # Workspace instructions
-├── api-project/          # Project 1
-│   ├── src/
-│   ├── tests/
-│   └── pyproject.toml
-├── auth-service/         # Project 2
-│   ├── src/
-│   ├── tests/
-│   └── pyproject.toml
-└── data-service/         # Project 3
-    ├── src/
-    ├── tests/
-    └── pyproject.toml
+npx rapidkit my-api --template nestjs
+cd my-api
+source .rapidkit/activate   # Enable rapidkit commands
+rapidkit dev                # Start dev server at http://localhost:8000
 ```
 
-### Full Workspace Structure
-```
-my-workspace/              # Workspace (container)
-├── .venv/                 # Virtual environment
-├── pyproject.toml        # Poetry config
-├── README.md             # Workspace instructions
-├── api-project/          # Project 1
-├── auth-service/         # Project 2
-└── data-service/         # Project 3
-```
+Your API will be available at `http://localhost:8000` with Swagger docs at `/docs`
 
-**Benefits:**
-- Multiple projects share same environment
-- Easy microservices development
-- Organized monorepo structure
-- Isolated from system Python
+## Two Modes of Operation
 
-## Installation Methods
+### 1. Direct Project Creation (with `--template`)
 
-### 🎯 Poetry (Recommended)
-```bash
-npx rapidkit my-workspace
-# Choose: Poetry
-cd my-workspace
-source $(poetry env info --path)/bin/activate
-rapidkit create my-project
-```
-
-### 📦 Python venv + pip
-```bash
-npx rapidkit my-workspace
-# Select "venv + pip" when prompted
-cd my-workspace
-source .venv/bin/activate
-rapidkit create my-project
-```
+Create a standalone project directly:
 
-### 🔧 pipx (Global)
 ```bash
-npx rapidkit my-workspace
-# Select "pipx (global install)" when prompted
-cd my-workspace
-rapidkit create my-project
+npx rapidkit my-api --template fastapi   # Create FastAPI project
+npx rapidkit my-api --template nestjs    # Create NestJS project
 ```
 
-## What Gets Installed?
+### 2. Workspace Mode (without `--template`)
 
-`rapidkit` creates a directory with:
-- Python virtual environment (Poetry or venv)
-- RapidKit package installed
-- README with usage instructions
-- Git repository (optional)
-
-## Using RapidKit Commands
-
-Once your environment is activated, you can use all native RapidKit commands:
+Create a workspace that can contain multiple projects:
 
 ```bash
-# Create a new project (interactive)
-rapidkit create
-
-# Or create non-interactively:
-rapidkit create project fastapi.standard my-api
-
-# Add modules to existing project
-cd my-api
-rapidkit add settings
-rapidkit add auth
-rapidkit add database
-rapidkit add caching
-
-# List available kits and modules
-rapidkit list
-rapidkit modules
-
-# Check system requirements
-rapidkit doctor
-
-# Upgrade RapidKit
-rapidkit upgrade
-
-# Get help
-rapidkit --help
+npx rapidkit my-workspace                     # Create workspace
+cd my-workspace
+rapidkit create my-api --template fastapi     # Create FastAPI project in workspace
+rapidkit create admin-api --template nestjs   # Create NestJS project in workspace
 ```
 
-## Available Kits
+## Templates
 
-RapidKit supports multiple project templates:
-- `fastapi.standard` - FastAPI with basic features
-- `fastapi.advanced` - FastAPI with advanced features
-- `nestjs.standard` - NestJS with basic features
-- `nestjs.advanced` - NestJS with advanced features
+| Template | Framework | Description |
+|----------|-----------|-------------|
+| `fastapi` | FastAPI | Python async web framework with automatic API docs |
+| `nestjs` | NestJS | TypeScript Node.js framework with modular architecture |
 
 ## CLI Options
 
 ```bash
-npx rapidkit [workspace-name] [options]
+npx rapidkit [project-name] [options]
 ```
 
 ### Arguments
-- `workspace-name` - Name of workspace directory to create (default: `rapidkit-workspace`)
+- `project-name` - Name of project/workspace directory to create
 
 ### Options
-- `--demo` - **[Available Now]** Create workspace with bundled FastAPI templates (no Python RapidKit required)
-- `--demo-only` - **[Internal]** Generate a single project in current directory (used by demo workspace script)
+- `-t, --template <template>` - Template to use: `fastapi` or `nestjs` (creates direct project)
 - `--skip-git` - Skip git initialization  
-- `--test-mode` - **[Beta Testing]** Install from local RapidKit path (for development/testing only)
+- `--skip-install` - Skip installing dependencies (for NestJS)
 - `--debug` - Enable verbose debug logging
 - `--dry-run` - Preview what would be created without creating it
 - `--no-update-check` - Skip checking for newer versions
 - `--help` - Display help information
 - `--version` - Show version number
 
-> **Note:** Full installation mode (without `--demo`) will be available once RapidKit is published on PyPI.
+## Project Commands
 
-## Examples
+After creating a project, activate the local CLI and use these commands:
 
-### Demo Workspace
 ```bash
-# Create demo workspace
-npx rapidkit my-workspace --demo
-cd my-workspace
+cd my-api
+source .rapidkit/activate   # Enable rapidkit commands (run once per terminal)
 
-# Generate projects inside
-node generate-demo.js api-service
-node generate-demo.js auth-service
+rapidkit init      # Install dependencies
+rapidkit dev       # Start dev server with hot reload (port 8000)
+rapidkit start     # Start production server
+rapidkit build     # Build for production
+rapidkit test      # Run tests
+rapidkit lint      # Lint code
+rapidkit format    # Format code
+rapidkit --help    # Show all commands
 ```
 
-### Full RapidKit Workspace
-```bash
-# Create workspace with RapidKit installed
-npx rapidkit my-workspace
-cd my-workspace
+### Alternative: Without Activation
 
-# Create projects using RapidKit CLI
-rapidkit create api-service
-rapidkit create auth-service
-```
+You can also run commands directly without activation:
 
-### Default workspace
 ```bash
-npx rapidkit --demo
-# Creates ./rapidkit-workspace/ directory
+./rapidkit dev          # Using the wrapper script
+make dev                # Using Makefile (FastAPI)
+poetry run dev          # Using Poetry directly (FastAPI)
+npm run start:dev       # Using npm directly (NestJS)
 ```
 
-### Skip git initialization
-```bash
-npx rapidkit my-workspace --demo --skip-git
-```
+## Project Structure
 
-### Debug mode
-```bash
-npx rapidkit my-workspace --debug
-```
+### FastAPI Project
 
-### Dry-run (preview without creating)
-```bash
-npx rapidkit my-workspace --dry-run
-npx rapidkit my-workspace --demo --dry-run
 ```
-
-## Configuration
-
-### User Configuration File
-
-Create `~/.rapidkitrc.json` in your home directory to set default values:
-
-```json
-{
-  "defaultKit": "fastapi.standard",
-  "defaultInstallMethod": "poetry",
-  "pythonVersion": "3.11",
-  "author": "Your Name",
-  "license": "MIT",
-  "skipGit": false
-}
+my-api/
+├── .rapidkit/
+│   ├── activate         # Activation script
+│   ├── cli.py           # Python CLI module
+│   └── rapidkit         # Bash wrapper
+├── rapidkit             # Main CLI entry point
+├── src/
+│   ├── main.py          # FastAPI application
+│   ├── cli.py           # CLI commands
+│   ├── routing/         # API routes
+│   └── modules/         # Module system
+├── tests/               # Test suite
+├── pyproject.toml       # Poetry configuration
+├── Makefile             # Make commands
+└── README.md
 ```
 
-### Environment Variables
-
-For test mode with local RapidKit installation:
+### NestJS Project
 
-```bash
-export RAPIDKIT_DEV_PATH=/path/to/local/rapidkit
-npx rapidkit my-workspace --test-mode
 ```
-
-**Priority:** CLI options > Environment variables > Config file > Defaults
+my-api/
+├── .rapidkit/
+│   ├── activate         # Activation script
+│   └── rapidkit         # Bash CLI wrapper
+├── rapidkit             # Main CLI entry point
+├── src/
+│   ├── main.ts              # Application entry point
+│   ├── app.module.ts        # Root module
+│   ├── config/              # Configuration
+│   └── examples/            # Example module
+├── test/                    # Test files
+├── package.json             # Dependencies
+├── tsconfig.json            # TypeScript config
+└── README.md
+```
 
 ## Requirements
 
 - **Node.js**: 18+ (for running npx)
-- **Python**: 3.10+ (required by RapidKit)
-- **Optional**: Poetry or pipx (depending on installation method)
-
-## Typical Workflow
-
-### Demo Mode
-1. **Create demo workspace**:
-   ```bash
-   npx rapidkit my-workspace --demo
-   cd my-workspace
-   ```
-
-2. **Generate your first project**:
-   ```bash
-   node generate-demo.js api-service
-   cd api-service
-   ```
-
-3. **Install dependencies and run**:
-   ```bash
-   poetry install
-   poetry run dev
-   ```
-
-4. **Create more projects** (go back to workspace):
-   ```bash
-   cd ..
-   node generate-demo.js auth-service
-   node generate-demo.js data-service
-   ```
-
-### Full Mode (After RapidKit PyPI Release)
-1. **Create RapidKit workspace**:
-   ```bash
-   npx rapidkit my-workspace
-   cd my-workspace
-   ```
-
-2. **Activate environment**:
-   ```bash
-   source $(poetry env info --path)/bin/activate
-   # Or: poetry shell
-   ```
-
-3. **Create your first project**:
-   ```bash
-   # Interactive mode (recommended)
-   rapidkit create
-   
-   # Or specify directly:
-   rapidkit create project fastapi.standard api-service
-   ```
-
-4. **Navigate and run**:
-   ```bash
-   cd api-service
-   rapidkit dev
-   ```
-
-5. **Create more projects** (from workspace root):
-   ```bash
-   cd ..
-   rapidkit create project fastapi.standard auth-service
-   rapidkit create project nestjs.standard data-service
-   ```
-
-## Troubleshooting
-
-### Python not found
-```bash
-# Check Python version
-python3 --version
-
-# Install Python 3.10+
-# Visit: https://www.python.org/downloads/
-```
-
-### Poetry not found
-```bash
-# Install Poetry
-curl -sSL https://install.python-poetry.org | python3 -
-
-# Or visit: https://python-poetry.org/docs/#installation
-```
-
-### pipx not found
-```bash
-# Install pipx
-python3 -m pip install --user pipx
-python3 -m pipx ensurepath
-
-# Or visit: https://pypa.github.io/pipx/installation/
-```
-
-### Check RapidKit installation
-```bash
-# Activate environment first
-poetry shell  # or: source .venv/bin/activate
-
-# Verify RapidKit
-rapidkit --version
-rapidkit doctor
-```
-
-## What's Next?
-
-After setting up your RapidKit environment:
-
-## What's Next?
-
-After setting up your demo project:
-
-1. Explore the generated FastAPI structure
-2. Customize routes and add your business logic
-3. **Stay tuned for RapidKit stable release on PyPI**
-4. Upgrade to full RapidKit for modules and advanced features
-
-## Roadmap
-
-### ✅ Current (Beta)
-- ✅ Demo workspace with bundled FastAPI templates
-- ✅ Multiple projects per workspace
-- ✅ Interactive project generation
-- ✅ Full FastAPI project structure
-
-### 🚧 Coming Soon
-- **RapidKit Python package on PyPI** (main blocker)
-- Full installation mode with all kits
-- Module ecosystem integration (`rapidkit add module`)
-- NestJS standard kit demos
-- Advanced kit templates
-- Workspace sharing and templates
-
-### 🔮 Future
-- More framework support
-- Custom kit marketplace
-- Cloud deployment integrations
-- CI/CD templates
+- **For FastAPI**: Python 3.11+ with Poetry
+- **For NestJS**: Node.js 20+ with npm/yarn/pnpm
 
-## Related Projects
-
-- **RapidKit Python** - The core framework (coming soon to PyPI)
-- **RapidKit Marketplace** - Browse and share modules (https://rapidkit.top)
-- **GitHub**: https://github.com/getrapidkit
-
-## Contributing
-
-Contributions welcome! This NPM package is a companion tool for RapidKit.
-
-To contribute:
-1. Fork the repository
-2. Create a feature branch
-3. Submit a pull request
-
-### Development
+## Development
 
 ```bash
 # Clone the repository
@@ -443,36 +169,21 @@ cd rapidkit-npm
 # Install dependencies
 npm install
 
-# Build the project (optimized with tsup)
+# Build
 npm run build
 
-# Run in watch mode during development
-npm run dev
-
 # Run tests
 npm test
 
-# Type checking
-npm run typecheck
-
-# Linting
-npm run lint
-
-# Format code
-npm run format
-
-# Full validation (typecheck + lint + format + test)
-npm run validate
-
-# Check bundle size
-npm run bundle-size
+# Watch mode
+npm run dev
 ```
 
-**Bundle Optimization:**
-- Built with [tsup](https://github.com/egoist/tsup) for optimal performance
-- Minified and tree-shaked for smallest bundle size
-- ~40KB total bundle size (80% reduction from unoptimized)
-- No source maps in production
+## Related Projects
+
+- **RapidKit Python** - The core framework (coming soon to PyPI)
+- **RapidKit Docs** - https://rapidkit.top
+- **GitHub**: https://github.com/getrapidkit
 
 ## License
 
@@ -482,27 +193,7 @@ MIT
 
 - 🐛 Report issues: [GitHub Issues](https://github.com/getrapidkit/rapidkit-npm/issues)
 - 📚 Docs: https://rapidkit.top
-- 💬 Community: Coming soon
 
 ---
 
-### About This Beta
-
-**rapidkit** (npm package) is currently in beta version 1.0.0-beta.9. The `--demo` mode is fully functional for creating workspaces with bundled FastAPI templates. You can generate multiple projects within the same workspace without needing Python RapidKit installed.
-
-**New in beta.9:**
-- ✅ E2E integration tests for reliability
-- ✅ CI/CD pipeline with GitHub Actions
-- ✅ Enhanced error messages with troubleshooting steps
-- ✅ Security audit automation
-- ✅ Bundle size monitoring
-- ✅ Multi-platform testing (Ubuntu, macOS, Windows)
-
-Install with:
-```bash
-npx rapidkit my-workspace --demo
-```
-
-**Full RapidKit integration** (with `rapidkit create` and `rapidkit add module` commands) will be available once the Python package is published on PyPI.
-
-**Timeline**: RapidKit stable release expected soon. Follow [@getrapidkit](https://github.com/getrapidkit) for updates!
+**v0.12.0** - Added NestJS template, workspace mode, and unified CLI with `source .rapidkit/activate`