nitrostack 1.0.0

package/templates/typescript-auth/README.md

@@ -0,0 +1,400 @@
+# NitroStack E-Commerce Template
+
+**The official NitroStack starter template** - A full-featured e-commerce MCP server with authentication, products, cart, orders, and beautiful UI widgets.
+
+## 🎯 What's Inside
+
+This template demonstrates NitroStack v3.0 capabilities:
+
+- **Authentication** - JWT, API Keys, OAuth 2.1 support
+- **Products** - Browse, search, view details
+- **Shopping Cart** - Add, update, remove items
+- **Orders** - Create orders, view history
+- **Addresses** - Manage delivery addresses
+- **UI Widgets** - Beautiful Next.js components for all tools
+- **Database** - SQLite with seed data
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+```bash
+# Install NitroStack CLI globally
+npm install -g nitrostack
+
+# Or use npx
+npx nitrostack --version
+```
+
+### Step 1: Initialize Project
+
+```bash
+nitrostack init my-ecommerce --template typescript-auth
+cd my-ecommerce
+```
+
+The CLI automatically:
+- ✅ Installs all dependencies
+- ✅ Installs widget dependencies
+- ✅ Builds the widgets
+- ✅ Sets up the project structure
+
+### Step 2: Setup Database
+
+```bash
+npm run setup-db
+```
+
+This creates the SQLite database and seeds it with sample data including:
+- Users (Emily Johnson, Michael Chen, Sarah Williams)
+- Products (Electronics, Fashion, Home & Garden)
+- Sample orders and addresses
+
+### Step 3: Start Development Server
+
+```bash
+npm run dev
+```
+
+This starts:
+- **MCP Server** (stdio mode) - Hot reloads on code changes
+- **Studio** on http://localhost:3000 - Visual testing environment
+- **Widget Dev Server** on http://localhost:3001 - Hot module replacement
+
+The `nitrostack dev` command handles everything automatically:
+- ✅ Auto-detects widget directory
+- ✅ Installs dependencies (if needed)
+- ✅ Builds widgets (on first run)
+- ✅ Starts all services concurrently
+- ✅ Hot reload for TypeScript and widgets
+
+### Step 4: Login
+
+In Studio, go to **Tools** page and execute the `login` tool:
+
+```json
+{
+  "email": "emily.johnson@x.dummyjson.com",
+  "password": "password123"
+}
+```
+
+**Test Users:**
+- Emily Johnson: `emily.johnson@x.dummyjson.com` / `password123`
+- Michael Chen: `michael.chen@x.dummyjson.com` / `password123`
+- Sarah Williams: `sarah.williams@x.dummyjson.com` / `password123`
+
+The JWT token will be automatically saved in your browser.
+
+### Step 5: Refresh the Page
+
+After login, refresh the page to load your session.
+
+### Step 6: Setup AI Chat
+
+1. Go to the **Chat** page
+2. Select **Gemini** as the provider
+3. Enter Gemini API key: `AIzaSyApKc********_65cABcg2U`
+4. The key will be saved in your browser for future sessions
+
+### Step 7: Enjoy!
+
+Now you can:
+- Chat with AI to browse products
+- Add items to cart
+- Create orders
+- Manage addresses
+- See beautiful UI widgets rendered inline
+
+**Note:** If you get a token error, just re-login using the `login` tool. Both the Gemini API key and JWT token are saved in your browser.
+
+---
+
+## 📁 Project Structure
+
+```
+templates/typescript-auth/
+├── src/
+│   ├── modules/           # Feature modules
+│   │   ├── auth/         # Authentication (JWT, login, whoami)
+│   │   ├── products/     # Product catalog
+│   │   ├── cart/         # Shopping cart
+│   │   ├── orders/       # Order management
+│   │   └── addresses/    # Address management
+│   ├── guards/           # Auth guards (JWT)
+│   ├── services/         # Business logic
+│   ├── db/              # Database setup & seed
+│   ├── app.module.ts    # Root application module
+│   └── index.ts         # Application entry point
+│
+├── widgets/             # Next.js UI components
+│   ├── app/            # Widget pages
+│   │   ├── whoami/
+│   │   ├── products-grid/
+│   │   ├── product-card/
+│   │   ├── cart/
+│   │   ├── order-confirmation/
+│   │   └── ... (20+ widgets)
+│   └── styles/         # Shared styles
+│
+├── data/               # SQLite database
+├── .env.example       # Environment variables template
+└── package.json
+```
+
+---
+
+## 🔧 Configuration
+
+### Environment Variables
+
+Copy `.env.example` to `.env`:
+
+```env
+# JWT Configuration
+JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
+
+# Database
+DATABASE_PATH=./data/ecommerce.db
+
+# Server
+PORT=3000
+NODE_ENV=development
+```
+
+**Important:** Change `JWT_SECRET` in production!
+
+---
+
+## 🛠️ Available Commands
+
+```bash
+# Development
+npm run dev              # Start dev server with Studio (auto-builds everything)
+npm run build            # Build TypeScript and widgets for production
+npm start                # Run production server
+
+# Database
+npm run setup-db         # Initialize database with seed data
+npm run reset-db         # Reset database (WARNING: deletes all data)
+npm run seed             # Reseed database
+
+# Widget Management
+npm run widget <command> # Run npm command in widgets directory
+npm run widget add <pkg> # Add a widget dependency (e.g., @mui/material)
+```
+
+**Note:** The NitroStack CLI automatically handles building, installing dependencies, and hot reload. You don't need separate commands for widgets anymore!
+
+---
+
+## 🎨 Features Demonstrated
+
+### 1. **Decorator-Based Architecture**
+
+```typescript
+@Tool({
+  name: 'browse_products',
+  description: 'Browse products with filters',
+  inputSchema: z.object({
+    category: z.string().optional(),
+    page: z.number().default(1)
+  })
+})
+@Widget('products-grid')
+@Cache({ ttl: 300 })
+async browseProducts(input: any, ctx: ExecutionContext) {
+  return await this.productService.browse(input);
+}
+```
+
+### 2. **Modular Organization**
+
+```typescript
+@Module({
+  name: 'products',
+  controllers: [ProductsTools, ProductsResources, ProductsPrompts],
+  providers: [ProductService],
+  exports: [ProductService]
+})
+export class ProductsModule {}
+```
+
+### 3. **Authentication Guards**
+
+```typescript
+@Tool({ name: 'create_order' })
+@UseGuards(JWTGuard)  // Requires authentication
+async createOrder(input: any, ctx: ExecutionContext) {
+  const userId = ctx.auth?.subject;
+  // Create order for authenticated user
+}
+```
+
+### 4. **UI Widgets**
+
+Beautiful Next.js components automatically render tool responses:
+
+- Product grids with images
+- Shopping cart with item management
+- Order confirmations
+- User profile cards
+- Address management
+
+### 5. **Type Generation**
+
+```bash
+nitrostack generate types
+```
+
+Auto-generates TypeScript types for widgets from tool definitions.
+
+---
+
+## 📚 Learning Resources
+
+### Core Concepts
+
+- **Tools** - Functions AI can call (`@Tool` decorator)
+- **Resources** - Data AI can read (`@Resource` decorator)
+- **Prompts** - Conversation templates (`@Prompt` decorator)
+- **Guards** - Authentication/authorization (`@UseGuards`)
+- **Modules** - Logical organization (`@Module`)
+
+### Key Files to Study
+
+1. **`src/app.module.ts`** - Application bootstrap with `@McpApp`
+2. **`src/modules/auth/auth.tools.ts`** - JWT authentication
+3. **`src/modules/products/products.tools.ts`** - Product tools with caching
+4. **`src/modules/cart/cart.tools.ts`** - Stateful cart management
+5. **`src/guards/jwt.guard.ts`** - Guard implementation
+
+---
+
+## 🐛 Troubleshooting
+
+### Tools not loading
+
+```bash
+# Check if build is up to date
+npm run build
+
+# Check database exists
+ls -la data/ecommerce.db
+
+# Reset if needed
+npm run reset-db
+```
+
+### Token expired errors
+
+Just re-login:
+1. Go to Tools page
+2. Execute `login` tool
+3. Refresh the page
+
+### Widgets not rendering
+
+```bash
+# The CLI handles widgets automatically, but if needed:
+npm run widget install   # Install widget dependencies
+npm run dev              # Restart (rebuilds everything)
+```
+
+### Database errors
+
+```bash
+# Reset and reseed
+npm run reset-db
+```
+
+### Port already in use
+
+```bash
+# Kill processes on ports 3000 and 3001
+lsof -ti:3000 | xargs kill -9
+lsof -ti:3001 | xargs kill -9
+```
+
+---
+
+## 🚀 Extending the Template
+
+### Add a New Module
+
+```bash
+nitrostack generate module payments
+```
+
+### Add a New Tool
+
+```bash
+nitrostack generate tool process-payment --module payments
+```
+
+### Add a New Widget
+
+1. Create `src/widgets/app/payment-success/page.tsx`
+2. Implement your component
+3. Link to tool with `@Widget('payment-success')`
+
+### Generate Types
+
+```bash
+nitrostack generate types
+```
+
+---
+
+## 📖 Documentation
+
+- **NitroStack Docs**: `../../docs/`
+- **Quick Start**: `../../docs/getting-started/02-quick-start.md`
+- **Tools Guide**: `../../docs/sdk/typescript/04-tools-guide.md`
+- **Widgets Guide**: `../../docs/sdk/typescript/16-ui-widgets-guide.md`
+- **Authentication**: `../../docs/sdk/typescript/09-authentication-overview.md`
+
+---
+
+## 🎯 What You Can Build
+
+This template is a starting point for:
+
+- **E-commerce platforms** - Already set up!
+- **Content management** - Replace products with articles
+- **Task management** - Replace products with tasks
+- **CRM systems** - Manage customers and contacts
+- **Booking systems** - Replace products with services
+- **Inventory management** - Track stock and orders
+
+---
+
+## 💡 Tips
+
+1. **Check the seed data** in `src/db/seed.ts` to understand the schema
+2. **Study the widget styles** in `src/widgets/styles/ecommerce.ts`
+3. **Use Studio's chat** to test your tools interactively
+4. **Generate types** after adding new tools
+5. **Keep JWT_SECRET secure** in production
+
+---
+
+## 🤝 Support
+
+- **Documentation**: Full docs in `../../docs/`
+- **Examples**: This template is a complete example
+- **Issues**: Report bugs on GitHub
+- **Community**: Join our Discord
+
+---
+
+## 📄 License
+
+MIT License - See LICENSE file in repository root
+
+---
+
+**Happy Building! 🎉**
+
+Create amazing AI-powered applications with NitroStack!
+

package/templates/typescript-auth/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ecommerce-mcp-server",
+  "version": "3.0.0",
+  "description": "E-commerce MCP server with JWT authentication - NitroStack V3 Template",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "dev": "nitrostack dev",
+    "build": "nitrostack build",
+    "start": "nitrostack start",
+    "widget": "npm --prefix src/widgets",
+    "setup-db": "node --loader ts-node/esm src/db/setup.ts"
+  },
+  "keywords": [
+    "mcp",
+    "ecommerce",
+    "jwt-auth",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "nitrostack": "^1.0.0",
+    "dotenv": "^16.3.1",
+    "better-sqlite3": "^9.2.2",
+    "uuid": "^9.0.1",
+    "bcryptjs": "^2.4.3",
+    "jsonwebtoken": "^9.0.2",
+    "zod": "^3.22.4",
+    "reflect-metadata": "^0.2.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.8",
+    "@types/node": "^20.10.5",
+    "@types/uuid": "^9.0.7",
+    "@types/bcryptjs": "^2.4.6",
+    "@types/jsonwebtoken": "^9.0.5",
+    "typescript": "^5.3.3",
+    "ts-node": "^10.9.2",
+    "prettier": "^3.1.1",
+    "eslint": "^8.56.0"
+  }
+}
+