rapidkit 0.40.1 → 0.41.1

package/templates/kits/fastapi-standard/src/cli.py.j2

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Project CLI wrapper for {{ project_name }}.
+
+This file prefers a per-project CLI (generated at `.rapidkit/cli.py`) when
+available. If not present it prints helpful guidance directing users to
+`rapidkit init` and does not attempt to make assumptions about a packaging
+environment.
+"""
+
+import importlib.util
+import sys
+import argparse
+from pathlib import Path
+from typing import Optional
+
+
+def _missing_cli(name: str) -> None:
+    print(f"❌ Missing project-local CLI (.rapidkit/cli.py) - can't run '{name}'")
+    print("💡 If you're a new user run: rapidkit init  # create venv + install deps")
+    sys.exit(127)
+
+
+def _load_project_cli_module() -> Optional[object]:
+    project_root = Path(__file__).resolve().parents[1]
+    cli_file = project_root / ".rapidkit" / "cli.py"
+    if not cli_file.exists():
+        return None
+    spec = importlib.util.spec_from_file_location("project_cli", str(cli_file))
+    if spec is None or spec.loader is None:
+        return None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)  # type: ignore
+    return module
+
+
+_mod = _load_project_cli_module()
+
+
+# Default placeholders -- call `_missing_cli` if the project-local CLI isn't
+# available. These are real functions so linters don't complain.
+def init() -> None:
+    _missing_cli("init")
+
+
+def dev() -> None:
+    _missing_cli("dev")
+
+
+def start() -> None:
+    _missing_cli("start")
+
+
+def build() -> None:
+    _missing_cli("build")
+
+
+def test() -> None:
+    _missing_cli("test")
+
+
+def lint() -> None:
+    _missing_cli("lint")
+
+
+def format() -> None:  # type: ignore[misc]
+    _missing_cli("format")
+
+
+def help_cmd() -> None:
+    print("Usage: poetry run <command>  # (init|dev|start|build|test|lint|format)")
+
+
+if _mod is not None:
+    # prefer project-provided implementations when available
+    init = getattr(_mod, "init", init)
+    dev = getattr(_mod, "dev", dev)
+    start = getattr(_mod, "start", start)
+    build = getattr(_mod, "build", build)
+    test = getattr(_mod, "test", test)
+    lint = getattr(_mod, "lint", lint)
+    format = getattr(_mod, "format", format)
+    help_cmd = getattr(_mod, "help_cmd", help_cmd)
+
+
+_dev_impl = dev
+_start_impl = start
+
+
+def _runtime_kwargs_from_argv(argv: list[str]) -> dict:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("-p", "--port", type=int, dest="port")
+    parser.add_argument("--host", dest="host")
+    parser.add_argument("--allow-global-runtime", action="store_true", dest="allow_global_runtime")
+    ns, _ = parser.parse_known_args(argv)
+
+    kwargs = {}
+    if ns.port is not None:
+        kwargs["port"] = ns.port
+    if ns.host is not None:
+        kwargs["host"] = ns.host
+    if ns.allow_global_runtime:
+        kwargs["allow_global_runtime"] = True
+    return kwargs
+
+
+def dev() -> None:  # type: ignore[no-redef]
+    kwargs = _runtime_kwargs_from_argv(sys.argv[1:])
+    try:
+        _dev_impl(**kwargs)
+    except TypeError:
+        _dev_impl()
+
+
+def start() -> None:  # type: ignore[no-redef]
+    kwargs = _runtime_kwargs_from_argv(sys.argv[1:])
+    try:
+        _start_impl(**kwargs)
+    except TypeError:
+        _start_impl()
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        help_cmd()
+        return
+
+    command = sys.argv[1]
+    commands = {
+        "init": init,
+        "dev": dev,
+        "start": start,
+        "build": build,
+        "test": test,
+        "lint": lint,
+        "format": format,
+        "help": help_cmd,
+    }
+
+    if command in commands:
+        if command in ("dev", "start"):
+            parser = argparse.ArgumentParser(prog=f"poetry run {command}", add_help=False)
+            parser.add_argument("-p", "--port", type=int, dest="port")
+            parser.add_argument("--host", dest="host")
+            parser.add_argument("--allow-global-runtime", action="store_true", dest="allow_global_runtime")
+            ns, _ = parser.parse_known_args(sys.argv[2:])
+
+            kwargs = {}
+            if ns.port is not None:
+                kwargs["port"] = ns.port
+            if ns.host is not None:
+                kwargs["host"] = ns.host
+            if ns.allow_global_runtime:
+                kwargs["allow_global_runtime"] = True
+
+            try:
+                commands[command](**kwargs)
+            except TypeError:
+                commands[command]()
+        else:
+            commands[command]()
+    else:
+        print(f"Unknown command: {command}")
+        print("Run 'poetry run help' to see available commands.")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/templates/kits/fastapi-standard/src/main.py.j2

@@ -0,0 +1,66 @@
+"""{{ project_name }} application entrypoint."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+# <<<inject:imports>>>
+
+try:
+    # canonical health package
+    from src.health import register_health_routes as _core_register_health_routes
+except ImportError:  # pragma: no cover - health package not generated yet
+
+    def _register_health_routes(_: FastAPI) -> None:
+        return None
+
+else:
+
+    def _register_health_routes(app: FastAPI) -> None:
+        try:
+            _core_register_health_routes(app)
+        except Exception:  # pragma: no cover - defensive best-effort registration
+            return None
+
+
+from .routing import api_router
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Coordinate startup/shutdown hooks contributed by RapidKit modules."""
+
+    _ = app  # ensure the app reference stays available for injected hooks
+    # <<<inject:startup>>>
+    try:
+        yield
+    finally:
+        # <<<inject:shutdown>>>
+        pass
+
+
+app = FastAPI(
+    title="{{ project_name }}",
+    description="{{ description }}",
+    version="{{ app_version }}",
+    docs_url="/docs",
+    redoc_url="/redoc",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(api_router, prefix="/api")
+# Expose module-provided health routers under /api/health/module/*
+_register_health_routes(app)
+# <<<inject:routes>>>

package/templates/kits/fastapi-standard/src/modules/__init__.py.j2

@@ -0,0 +1,3 @@
+"""Module bootstrap namespace."""
+
+# <<<inject:module-init>>>

package/templates/kits/fastapi-standard/src/routing/__init__.py.j2

@@ -0,0 +1,16 @@
+"""API router assembly."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from .health import router as health_router
+from .examples import router as examples_router
+
+# <<<inject:router-imports>>>
+
+api_router = APIRouter()
+
+api_router.include_router(health_router, prefix="/health", tags=["health"])
+api_router.include_router(examples_router, prefix="/examples", tags=["examples"])
+# <<<inject:router-mount>>>

package/templates/kits/fastapi-standard/src/routing/examples.py.j2

@@ -0,0 +1,71 @@
+"""Sample in-memory notes endpoints to demonstrate RapidKit routing."""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from fastapi import APIRouter, HTTPException, status
+from pydantic import BaseModel, Field
+
+router = APIRouter(tags=["examples"])
+
+
+class NoteCreate(BaseModel):
+    """Payload for creating a note."""
+
+    title: str = Field(..., max_length=80)
+    body: str = Field(..., max_length=500)
+
+
+class Note(NoteCreate):
+    """Serialized note returned by the API."""
+
+    id: int
+
+
+_STORE: Dict[int, Note] = {}
+_NEXT_ID = 1
+
+
+@router.post(
+    "/notes",
+    response_model=Note,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a note",
+)
+def create_note(payload: NoteCreate) -> Note:
+    """Persist a note in memory and return it."""
+
+    global _NEXT_ID  # noqa: PLW0603 - intentional in-memory auto increment
+    note = Note(id=_NEXT_ID, **payload.model_dump())
+    _STORE[_NEXT_ID] = note
+    _NEXT_ID += 1
+    return note
+
+
+@router.get(
+    "/notes",
+    response_model=List[Note],
+    summary="List all notes",
+)
+def list_notes() -> List[Note]:
+    """Return all notes stored so far."""
+
+    return list(_STORE.values())
+
+
+@router.get(
+    "/notes/{note_id}",
+    response_model=Note,
+    summary="Retrieve a single note",
+)
+def get_note(note_id: int) -> Note:
+    """Retrieve a note by identifier or raise 404."""
+
+    note = _STORE.get(note_id)
+    if not note:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Note not found",
+        )
+    return note

package/templates/kits/fastapi-standard/src/routing/health.py.j2

@@ -0,0 +1,22 @@
+"""Health endpoints."""
+
+from __future__ import annotations
+
+from time import monotonic
+
+from fastapi import APIRouter
+
+router = APIRouter(tags=["health"])
+
+_START_TIME = monotonic()
+
+
+@router.get("/", summary="Health check")
+async def heartbeat() -> dict[str, object]:
+    """Return basic service heartbeat."""
+    return {
+        "status": "ok",
+        "version": "{{ app_version }}",
+        "uptime": monotonic() - _START_TIME,
+        "module": "app",
+    }

package/templates/kits/fastapi-standard/tests/__init__.py.j2

@@ -0,0 +1 @@
+"""Test package placeholder."""

package/templates/kits/fastapi-standard/tests/test_examples.py.j2

@@ -0,0 +1,29 @@
+"""Example feature tests exercising the in-memory notes API."""
+
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from src.main import app
+
+client = TestClient(app)
+
+
+def test_create_and_list_notes() -> None:
+    payload = {"title": "First note", "body": "Documented via RapidKit."}
+    create_response = client.post("/api/examples/notes", json=payload)
+    assert create_response.status_code == 201
+    data = create_response.json()
+    assert data["title"] == payload["title"]
+    assert data["body"] == payload["body"]
+
+    list_response = client.get("/api/examples/notes")
+    assert list_response.status_code == 200
+    notes = list_response.json()
+    assert any(note["title"] == payload["title"] for note in notes)
+
+
+def test_get_missing_note_returns_404() -> None:
+    response = client.get("/api/examples/notes/999")
+    assert response.status_code == 404
+    assert response.json()["detail"] == "Note not found"

package/templates/kits/fastapi-standard/tests/test_health.py.j2

@@ -0,0 +1,17 @@
+"""Health-check tests for generated FastAPI standard projects."""
+
+from fastapi.testclient import TestClient
+
+from src.main import app
+
+client = TestClient(app)
+
+
+def test_health_endpoint() -> None:
+    response = client.get("/api/health/")
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["status"] == "ok"
+    assert "version" in payload
+    assert "uptime" in payload
+    assert "module" in payload

package/templates/kits/nestjs-standard/Dockerfile.j2

@@ -0,0 +1,41 @@
+# syntax=docker/dockerfile:1.6
+ARG NODE_VERSION=20.19.0-alpine
+FROM node:${NODE_VERSION} as builder
+
+WORKDIR /usr/src/app
+
+COPY package*.json ./
+COPY . .
+
+RUN set -eux; \
+  if [ "{{ package_manager }}" = "pnpm" ]; then \
+    corepack enable pnpm && pnpm install --frozen-lockfile; \
+    pnpm build; \
+  elif [ "{{ package_manager }}" = "yarn" ]; then \
+    corepack enable yarn && yarn install --frozen-lockfile; \
+    yarn build; \
+  else \
+    if [ -f package-lock.json ]; then npm ci; else npm install; fi; \
+    npm run build; \
+  fi
+
+FROM node:${NODE_VERSION}
+ENV NODE_ENV=production
+WORKDIR /usr/src/app
+
+COPY package*.json ./
+
+RUN set -eux; \
+  if [ "{{ package_manager }}" = "pnpm" ]; then \
+    corepack enable pnpm && pnpm install --prod --frozen-lockfile; \
+  elif [ "{{ package_manager }}" = "yarn" ]; then \
+    corepack enable yarn && yarn install --production --frozen-lockfile; \
+  else \
+    if [ -f package-lock.json ]; then npm ci --omit=dev; else npm install --omit=dev; fi; \
+  fi
+
+COPY --from=builder /usr/src/app/dist ./dist
+
+
+EXPOSE 8000
+CMD ["node", "dist/main"]

package/templates/kits/nestjs-standard/README.md.j2

@@ -0,0 +1,139 @@
+# {{ project_name | replace('-', ' ') | title }}
+
+A production-ready NestJS 11 application generated with RapidKit's **NestJS Standard Kit**.
+
+## Getting Started
+> Recommended Node version: `{{ node_version }}` (`.nvmrc` and `.node-version` are included for your toolchain)
+
+```bash
+# Load the project-aware RapidKit CLI (adds .rapidkit/rapidkit to PATH)
+source .rapidkit/activate
+
+# Bootstrap dependencies using the local CLI
+rapidkit init  # use make init if you prefer a Make target
+
+# Copy env templates + install hooks/tooling
+./bootstrap.sh
+
+# Run the dev server with hot reload
+make dev
+
+# Or rely on the project-aware RapidKit CLI helpers:
+rapidkit dev
+
+# Run linting, type-checking, tests, and supply-chain audits
+make lint
+make typecheck
+make test
+make audit
+rapidkit lint
+rapidkit test
+```
+
+> Open a new shell? Run `source .rapidkit/activate` again so the project-local `rapidkit` launcher stays on your PATH.
+
+> Use `rapidkit init` (or `make init`) whenever dependencies change. Pass `SKIP_INIT=1` (for example `SKIP_INIT=1 make install`) if you only need to refresh tooling/hooks.
+
+> Lockfiles are generated automatically during scaffolding. Set `RAPIDKIT_SKIP_LOCKS=1` (or `RAPIDKIT_GENERATE_LOCKS=0`) before running `rapidkit create` if you need to skip this step.
+
+> Need the entire RapidKit command list? Run `rapidkit --help` or open the CLI reference in the docs for a complete breakdown.
+
+---
+
+## Quick start (developer)
+
+1. `rapidkit init` (after `source .rapidkit/activate`) bootstraps dependencies through the project-local RapidKit CLI and enforces lockfile flags for your chosen package manager.
+2. `make init` remains available as an alias to `rapidkit init` when you prefer Make targets.
+3. `./bootstrap.sh` copies `.env.example` to `.env` (when missing) and runs `SKIP_INIT=1 make install` so git hooks and tooling stay current without reinstalling packages.
+4. `make dev` wraps `{{ package_manager if package_manager != 'pnpm' else 'pnpm' }} run start:dev` and centralizes env loading; use it for day-to-day development.
+5. `make lint`, `make typecheck`, and `make test` proxy to the underlying package scripts or `tsc` so local changes match CI expectations.
+6. `make audit` executes `{{ package_manager }}`'s security audit (falling back to dev dependencies if needed) to surface vulnerable packages early.
+
+`make install` is still available; it re-runs `rapidkit init` unless you set `SKIP_INIT=1`, so prefer `SKIP_INIT=1 make install` when you only need to refresh tooling.
+
+Prefer `rapidkit dev`, `rapidkit test`, or `rapidkit lint` when you want the RapidKit CLI to auto-detect the right runtime; they call into the same project scripts wrapped by the Make targets.
+
+Prefer the Make targets for consistency, but you can always fall back to native commands if needed:
+
+```bash
+{{ package_manager if package_manager != 'pnpm' else 'pnpm' }} install
+{{ package_manager if package_manager != 'pnpm' else 'pnpm' }} run start:dev
+{{ package_manager if package_manager != 'pnpm' else 'pnpm' }} test
+{{ package_manager if package_manager != 'pnpm' else 'pnpm' }} run lint
+```
+
+If you see engine compatibility errors during `{{ package_manager }} install`, update your Node runtime (nvm/asdf) or use the provided Dockerfile which targets `NODE_VERSION={{ node_version }}`.
+
+## Features
+
+- Modular architecture with configuration hooks
+- {{ 'JWT/OAuth2 authentication scaffolding' if auth_type != 'none' else 'Authentication ready' }}
+- Optional integrations:
+  - Database: {{ database_type | default('postgresql') | upper }}
+  - Redis caching
+  - Structured logging and telemetry
+  - Monitoring endpoints
+
+## Project Structure
+
+- `src/main.ts` – Bootstraps the NestJS application
+- `src/app.module.ts` – Core application module with injection anchors
+- `src/modules/` – Container for RapidKit modules (`// <<<inject:module-init>>>`)
+- `src/config/` – Centralized configuration module and validation
+- `test/` – Unit and e2e testing with Jest
+
+## RapidKit Modules
+
+Install additional modules as needed:
+
+```bash
+rapidkit add module settings
+rapidkit add module logging
+rapidkit add module auth
+```
+
+<!-- <<<inject:module-snippet>>> -->
+
+## Example feature
+
+The scaffold ships with an `ExamplesModule` exposing a tiny in-memory notes API under `/examples/notes`. Use it to validate request/response flows or to demo module structure before wiring real adapters:
+
+```bash
+# Create a note
+curl -s -X POST http://localhost:3000/examples/notes \
+  -H "Content-Type: application/json" \
+  -d '{"title":"hello","body":"documented via RapidKit"}'
+
+# List all notes
+curl -s http://localhost:3000/examples/notes | jq
+```
+
+Replace the in-memory service with a proper repository once you add RapidKit database modules.
+
+## Docker
+
+```bash
+docker-compose up -d
+docker-compose down
+```
+
+## Scripts
+
+| Command | Description |
+| --- | --- |
+| `{{ package_manager if package_manager != 'pnpm' else 'pnpm' }} start:dev` | Start development server |
+| `{{ package_manager if package_manager != 'pnpm' else 'pnpm' }} build` | Build production artifacts |
+| `{{ package_manager if package_manager != 'pnpm' else 'pnpm' }} test` | Run tests |
+
+---
+Generated with ❤️ by RapidKit.
+
+## 📄 License
+
+This project is licensed under the **{{ license }}** License - see the `LICENSE` file included at the project root for details.
+
+## 🔒 Security & secrets
+
+- Copy `.env.example` to `.env` and populate secrets (`SECRET_KEY`, DB credentials, etc.) before deploying.
+- **Do not** commit real secrets or `.env` to git; `.gitignore` already contains `.env` to protect accidental commits.
+- For production, tighten CORS and allowed hosts rather than using wildcard settings provided for convenience in dev.

package/templates/kits/nestjs-standard/docker-compose.yml.j2

@@ -0,0 +1,94 @@
+version: '3.8'
+services:
+  app:
+    build: .
+    container_name: {{ project_name | replace('_', '-') }}
+    ports:
+      - "8000:8000"
+    env_file:
+      - .env
+    environment:
+      NODE_ENV: development
+    command: {{ ('pnpm' if package_manager == 'pnpm' else (package_manager if package_manager in ['npm', 'yarn'] else 'npm')) }} run start:dev
+    volumes:
+      - .:/usr/src/app
+      - /usr/src/app/node_modules
+    {% if database_type in ['postgresql', 'mysql', 'mongodb'] or include_caching %}
+    depends_on:
+      {% if database_type == 'postgresql' %}
+      postgres:
+        condition: service_healthy
+      {% elif database_type == 'mysql' %}
+      mysql:
+        condition: service_healthy
+      {% elif database_type == 'mongodb' %}
+      mongodb:
+        condition: service_started
+      {% endif %}
+      {% if include_caching %}
+      redis:
+        condition: service_started
+      {% endif %}
+    {% endif %}
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+
+{% if database_type == 'postgresql' %}
+  postgres:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: password
+      POSTGRES_DB: {{ project_name | replace('-', '_') }}
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U user"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+
+{% elif database_type == 'mysql' %}
+  mysql:
+    image: mysql:8.1
+    environment:
+      MYSQL_ROOT_PASSWORD: password
+      MYSQL_DATABASE: {{ project_name | replace('-', '_') }}
+      MYSQL_USER: user
+      MYSQL_PASSWORD: password
+    ports:
+      - "3306:3306"
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+{% elif database_type == 'mongodb' %}
+  mongodb:
+    image: mongo:7
+    ports:
+      - "27017:27017"
+    volumes:
+      - mongodb_data:/data/db
+
+{% endif %}
+{% if include_caching %}
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    command: ["redis-server", "--appendonly", "yes"]
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+{% endif %}
+
+volumes:
+  mongodb_data:
+    driver: local

package/templates/kits/nestjs-standard/docs/README.md.j2

@@ -0,0 +1,15 @@
+# Documentation
+
+Welcome to the documentation portal for **{{ project_name | replace('-', ' ') | title }}**.
+
+## Contents
+
+- `architecture/` – System design documents and decisions
+- `operations/` – Runbooks and operational procedures
+- `modules/` – Documentation for installed RapidKit modules
+
+## Getting Started
+
+1. Update this documentation with project-specific details.
+2. Document any architectural decisions in `architecture/adr-000-template.md`.
+3. Keep module docs in sync with installed RapidKit modules.