rapidkit 0.14.1 → 0.15.1

package/README.md

@@ -5,65 +5,170 @@
 [![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)
 
-> ⚠️ **PRE-RELEASE VERSION** - This is a companion tool for RapidKit framework.  
-> The stable production version of RapidKit Python will be released soon on PyPI.
+This is the official RapidKit CLI on npm.
 
-🚀 The easiest way to create FastAPI and NestJS projects with RapidKit templates!
+> 🔮 **Coming Soon:** AI-powered module recommendations when Core modules are released!
+>
+> _Note: The AI recommender feature is complete in the `feature/ai-recommender` branch but not yet released. We will announce it when Core module support is available._
+
+RapidKit's single source of truth for kits and global commands is **RapidKit Core (Python)**.
+This npm package is a **bridge/wrapper** that:
+
+- Delegates project commands (e.g. `init`, `dev`, `test`) to the project-local launcher when you are inside a RapidKit project.
+- Forwards global/core commands (e.g. `list`, `info`, `create`, `add`, `doctor`, `--tui`, `--json`) to `python -m rapidkit ...`.
+- If `rapidkit-core` is not available in your system Python, it can bootstrap a cached virtualenv and install Core there.
 
 **💡 Tip:** Use the [RapidKit VS Code Extension](https://marketplace.visualstudio.com/items?itemName=rapidkit.rapidkit-vscode) for a visual interface!
 
 ## Quick Start
 
-### Create a FastAPI Project
+### Create a Project (FastAPI)
 
 ```bash
-npx rapidkit my-api --template fastapi
+npx rapidkit create project fastapi.standard my-api --output .
 cd my-api
 npx rapidkit init           # Install dependencies
 npx rapidkit dev            # Start dev server at http://localhost:8000
 ```
 
-### Create a NestJS Project
+### Create a Project (NestJS)
 
 ```bash
-npx rapidkit my-api --template nestjs
+npx rapidkit create project nestjs.standard my-api --output .
 cd my-api
 npx rapidkit init           # Install dependencies
 npx rapidkit dev            # Start dev server at http://localhost:8000
 ```
 
-Your API will be available at `http://localhost:8000` with Swagger docs at `/docs`
+### Interactive mode (recommended)
+
+```bash
+npx rapidkit create
+```
+
+This runs the RapidKit Core wizard (`python -m rapidkit create`) and guides you through kit selection and project creation.
 
 ## Two Modes of Operation
 
-### 1. Direct Project Creation (with `--template`)
+### 1. Direct Project Creation (Core-first)
 
-Create a standalone project directly:
+Create a standalone project directly via Core:
 
 ```bash
-npx rapidkit my-api --template fastapi   # Create FastAPI project
-npx rapidkit my-api --template nestjs    # Create NestJS project
+npx rapidkit create project fastapi.standard my-api --output .
+npx rapidkit create project nestjs.standard my-api --output .
 ```
 
-### 2. Workspace Mode (without `--template`)
+### 2. RapidKit Environment Mode (without `--template`)
 
 Create a workspace to organize multiple projects:
 
 ```bash
-npx rapidkit my-workspace                     # Create workspace
+npx rapidkit my-workspace                     # Create a RapidKit environment (installs python core)
 cd my-workspace
-npx rapidkit my-api --template fastapi        # Create FastAPI project
-npx rapidkit admin-api --template nestjs      # Create NestJS project
+
+# Interactive project creation (recommended)
+rapidkit create
+
+# Or non-interactive via kit slug
+rapidkit create project fastapi.standard my-api --output .
+rapidkit create project nestjs.standard admin-api --output .
+```
+
+This mode creates a "RapidKit environment" directory (Poetry/venv/pipx) and installs the Python Core there, so you can create/manage projects from the same CLI.
+
+Note: when you choose Poetry, the virtualenv is typically created in Poetry's cache (not as a local `.venv` folder). Activate it via:
+
+```bash
+source "$(poetry env info --path)/bin/activate"
+```
+
+## Kits / Templates
+
+Kits/templates are provided by the Python Core. This npm package is not limited to two templates.
+
+List kits:
+
+```bash
+rapidkit list
+rapidkit list --json
+```
+
+Create a project with any kit slug:
+
+```bash
+npx rapidkit create project <kit-slug> my-service --output .
 ```
 
-> **Note:** The same `npx rapidkit <name> --template <type>` command works everywhere - in any directory or inside a workspace!
+Examples:
+
+```bash
+npx rapidkit create project fastapi.standard my-service --output .
+npx rapidkit create project nestjs.standard my-service --output .
+```
+
+### Offline fallback (deprecated, last resort)
+
+**Deprecated:** With the Python Core (PyPI `rapidkit-core`) now providing dynamic kits and the interactive wizard, the npm package no longer relies on static embedded templates. The offline fallback remains available only as an absolute last-resort for environments where Python/Core cannot be used, but it is not recommended for normal usage.
+
+If you still need the fallback it supports:
+
+- `fastapi.standard` (and `fastapi` shorthand)
+- `nestjs.standard` (and `nestjs` shorthand)
+
+Example (deprecated fallback):
+
+```bash
+npx rapidkit create project fastapi.standard my-api --output .
+```
+
+Limitations of the offline fallback (deprecated):
+
+- Only FastAPI/NestJS embedded templates are supported.
+- The full kit catalog (`rapidkit list`) and the interactive wizard (`rapidkit create`) require Python Core.
+- `--json` output is not supported for fallback `create`.
+
+---
+
+### Bootstrapping Python Core into a workspace
+
+The recommended flow is to use the Python Core (`rapidkit-core` on PyPI) as the single source of truth for kits and modules. The npm CLI will bootstrap the Python Core into a workspace virtual environment so you can create and manage projects even on a fresh machine.
+
+Example: create a workspace and verify Core is bootstrapped
+
+```bash
+# Create a RapidKit workspace non-interactively (workspace .venv will be created)
+npx rapidkit my-workspace --yes --skip-git
+
+# Activate the workspace environment
+cd my-workspace
+source .venv/bin/activate
+
+# Confirm rapidkit-core is installed inside the workspace venv
+python -m pip show rapidkit-core
+# -> Name: rapidkit-core
+# -> Version: 0.2.1rc1 (or newer)
+```
 
-## Templates
+## Install Python Core (optional) 🐍🔧
 
-| Template | Framework | Description |
-|----------|-----------|-------------|
-| `fastapi` | FastAPI | Python async web framework with automatic API docs |
-| `nestjs` | NestJS | TypeScript Node.js framework with modular architecture |
+RapidKit's engine is provided by the Python package `rapidkit-core` on PyPI. If you prefer to install the engine manually (for development or testing), you can do so:
+
+```bash
+# Install for current user
+pip install --user rapidkit-core
+
+# Or install into an active virtual environment / system
+pip install rapidkit-core
+```
+
+Project page: https://pypi.org/project/rapidkit-core/
+
+Notes:
+
+- The CLI will prefer system Python with `rapidkit-core` if available. If not present it bootstraps `rapidkit-core` into the workspace `.venv` (or a cached bridge venv as a fallback for some global flows).
+- To emulate a clean system in CI/QA, ensure `rapidkit-core` is not installed in the global/system Python before running the workspace creation script.
+- If you prefer Poetry to create in-project virtualenvs (`.venv`), enable it via `poetry config virtualenvs.in-project true` or let the workspace installer configure Poetry for you.
 
 ## CLI Options
 
@@ -72,11 +177,12 @@ npx rapidkit [project-name] [options]
 ```
 
 ### Arguments
+
 - `project-name` - Name of project/workspace directory to create
 
 ### Options
-- `-t, --template <template>` - Template to use: `fastapi` or `nestjs` (creates direct project)
-- `--skip-git` - Skip git initialization  
+
+- `--skip-git` - Skip git initialization
 - `--skip-install` - Skip installing dependencies (for NestJS)
 - `--debug` - Enable verbose debug logging
 - `--dry-run` - Preview what would be created without creating it
@@ -100,6 +206,43 @@ npx rapidkit format    # Format code
 npx rapidkit --help    # Show all commands
 ```
 
+### Adding Modules to Your Project
+
+RapidKit's modular architecture lets you extend your project with pre-built modules. Install modules using:
+
+```bash
+npx rapidkit add module <module-slug>
+```
+
+**Examples:**
+
+```bash
+# Add authentication module
+npx rapidkit add module auth
+
+# Add caching module (Redis)
+npx rapidkit add module redis
+
+# Add database module (PostgreSQL)
+npx rapidkit add module db_postgres
+```
+
+**List available modules:**
+
+```bash
+npx rapidkit list modules
+npx rapidkit list modules --json
+```
+
+**View module details:**
+
+```bash
+npx rapidkit info module auth
+npx rapidkit info module db_postgres
+```
+
+> **💡 Tip:** Use the [RapidKit VS Code Extension](https://marketplace.visualstudio.com/items?itemName=rapidkit.rapidkit-vscode) for a visual interface to browse and install modules!
+
 > **Note:** `npx rapidkit` automatically detects when you're inside a RapidKit project and delegates to the local CLI. Works everywhere without any setup!
 
 > **💡 Tip:** Install globally with `npm i -g rapidkit` to use `rapidkit` directly without `npx`.
@@ -158,9 +301,37 @@ my-api/
 
 ## Requirements
 
-- **Node.js**: 18+ (for running npx)
-- **For FastAPI**: Python 3.11+ with Poetry
-- **For NestJS**: Node.js 20+ with npm/yarn/pnpm
+- **Node.js**: 20.19.6+ (LTS recommended)
+- **Python**: Required for RapidKit Core commands (e.g. `list/info/create/add/...`). If Python is missing, the bridge fails with a clear error message.
+- For FastAPI projects: Python + Poetry (as required by the generated project)
+- For NestJS projects: Node + a package manager (npm/yarn/pnpm)
+- **Git**: For version control
+
+> 💡 **Tip:** Use [RapidKit VS Code Extension](https://marketplace.visualstudio.com/items?itemName=rapidkit.rapidkit-vscode) - includes system checker to verify all requirements!
+
+## How It Works (Under the Hood)
+
+This CLI runs a Node entrypoint (`dist/index.js`) that makes these decisions:
+
+1. If you're inside a RapidKit project:
+
+- It detects the project (via `.rapidkit/project.json` or other signals).
+- It delegates `rapidkit init/dev/test/...` to the project-local launcher (`./rapidkit` or `.rapidkit/rapidkit`).
+
+2. If you're not inside a project and run a global/core command (e.g. `rapidkit list --json`):
+
+- It forwards the request to the Python Core via `python -m rapidkit ...`.
+- If Core is not installed in system Python, it bootstraps a cached venv and installs `rapidkit-core` there.
+
+3. If you run `npx rapidkit <name>` without `--template`:
+
+- It creates a "RapidKit environment" directory (Poetry/venv/pipx) so you're ready to create and run real projects.
+
+### Bridge controls
+
+- Override Core install target (dev/test): `RAPIDKIT_CORE_PYTHON_PACKAGE=/path/to/core`
+- Cache location: `XDG_CACHE_HOME=...`
+- Upgrade pip during bootstrap (optional): `RAPIDKIT_BRIDGE_UPGRADE_PIP=1`
 
 ## Development
 
@@ -184,7 +355,7 @@ npm run dev
 
 ## Related Projects
 
-- **RapidKit Python** - The core framework (coming soon to PyPI)
+- **RapidKit Core (Python)** - The engine (PyPI: `rapidkit-core`)
 - **RapidKit Docs** - https://getrapidkit.com
 - **GitHub**: https://github.com/getrapidkit
 
@@ -196,13 +367,3 @@ MIT
 
 - 🐛 Report issues: [GitHub Issues](https://github.com/getrapidkit/rapidkit-npm/issues)
 - 📚 Docs: https://getrapidkit.com
-
----
-
-**v0.13.0** - NestJS test coverage boost (75%→90%), demo-kit improvements
-
-**v0.12.4** - Friendly shell activation UX with green headers and robust fallback logic
-
-**v0.12.2** - Simplified CLI: `rapidkit init` now handles environment activation automatically
-
-**v0.12.0** - Added NestJS template, workspace mode, and unified CLI

package/dist/index.d.ts

@@ -1 +1,4 @@
 #!/usr/bin/env node
+declare function handleCreateOrFallback(args: string[]): Promise<number>;
+
+export { handleCreateOrFallback };