nitrostack 1.0.54 → 1.0.56

package/templates/typescript-auth/README.md

@@ -1,402 +0,0 @@
-# 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** (dual transport: STDIO + HTTP on port 3002) - Hot reloads on code changes
-- **Studio** on http://localhost:3000 - Visual testing environment
-- **Widget Dev Server** on http://localhost:3001 - Hot module replacement
-
-> 💡 **Dual Transport**: Your server exposes tools via both STDIO (for direct connections) and HTTP (for remote access on port 3002). Switch between transports in Studio → Settings.
-
-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

@@ -1,36 +0,0 @@
-{
-  "name": "typescript-auth",
-  "version": "1.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "nitrostack dev",
-    "build": "nitrostack build",
-    "start": "npm run build && nitrostack start",
-    "start:prod": "nitrostack start",
-    "widget": "npm --prefix src/widgets",
-    "setup-db": "node --loader ts-node/esm src/db/setup.ts"
-  },
-  "dependencies": {
-    "nitrostack": "^1",
-    "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"
-  }
-}
-

package/templates/typescript-auth/src/app.module.ts

@@ -1,103 +0,0 @@
-import { McpApp, Module, ConfigModule, JWTModule } from 'nitrostack';
-
-// Services
-import { DatabaseService } from './services/database.service.js';
-
-// Modules
-import { AuthModule } from './modules/auth/auth.module.js';
-import { ProductsModule } from './modules/products/products.module.js';
-import { CartModule } from './modules/cart/cart.module.js';
-import { OrdersModule } from './modules/orders/orders.module.js';
-import { AddressesModule } from './modules/addresses/addresses.module.js';
-
-// Middleware
-import { LoggingMiddleware } from './middleware/logging.middleware.js';
-
-// Interceptors
-import { TransformInterceptor } from './interceptors/transform.interceptor.js';
-
-// Pipes
-import { ValidationPipe } from './pipes/validation.pipe.js';
-
-// Filters
-import { GlobalExceptionFilter } from './filters/global-exception.filter.js';
-
-// Events
-import { AnalyticsService } from './events/analytics.service.js';
-import { NotificationService } from './events/notification.service.js';
-
-// Health
-import { DatabaseHealthCheck } from './health/database.health.js';
-
-/**
- * Root Application Module
- * 
- * This is the main module that bootstraps the MCP server.
- * It registers all feature modules, services, and global providers.
- */
-@McpApp({
-  module: AppModule,
-  server: {
-    name: 'E-commerce MCP Server',
-    version: '3.0.0',
-  },
-  logging: {
-    level: (process.env.LOG_LEVEL as any) || 'info',
-  },
-})
-@Module({
-  name: 'app',
-  description: 'Root application module',
-  imports: [
-    // Configuration
-    ConfigModule.forRoot({
-      envFilePath: '.env',
-      defaults: {
-        DATABASE_PATH: './data/ecommerce.db',
-        LOG_LEVEL: 'info',
-      },
-    }),
-    
-    // JWT Authentication
-    JWTModule.forRoot({
-      secret: process.env.JWT_SECRET || 'your-secret-key',
-      expiresIn: '7d',
-      issuer: process.env.JWT_ISSUER || 'ecommerce-app',
-      audience: process.env.JWT_AUDIENCE || 'ecommerce-mcp-server',
-    }),
-    
-    // Feature Modules
-    AuthModule,
-    ProductsModule,
-    CartModule,
-    OrdersModule,
-    AddressesModule,
-  ],
-  controllers: [],
-  providers: [
-    // Global Services
-    DatabaseService,
-    
-    // Global Middleware
-    LoggingMiddleware,
-    
-    // Global Interceptors
-    TransformInterceptor,
-    
-    // Global Pipes
-    ValidationPipe,
-    
-    // Global Filters
-    GlobalExceptionFilter,
-    
-    // Event Handlers
-    AnalyticsService,
-    NotificationService,
-    
-    // Health Checks
-    DatabaseHealthCheck,
-  ],
-  exports: [DatabaseService],
-})
-export class AppModule {}
-

package/templates/typescript-auth/src/db/database.ts

@@ -1,160 +0,0 @@
-import Database from 'better-sqlite3';
-import path from 'path';
-import fs from 'fs';
-
-/**
- * Database connection and utilities
- */
-
-let db: Database.Database | null = null;
-
-export function getDatabase(): Database.Database {
-  if (!db) {
-    const envPath = process.env.DATABASE_PATH || './data/ecommerce.db';
-    
-    // Resolve relative paths from the project root (process.cwd())
-    // Absolute paths are used as-is
-    const dbPath = path.isAbsolute(envPath) 
-      ? envPath 
-      : path.resolve(process.cwd(), envPath);
-    
-    const dbDir = path.dirname(dbPath);
-    
-    // Ensure data directory exists
-    if (!fs.existsSync(dbDir)) {
-      fs.mkdirSync(dbDir, { recursive: true });
-    }
-    
-    db = new Database(dbPath);
-    db.pragma('journal_mode = WAL');
-    db.pragma('foreign_keys = ON');
-  }
-  
-  return db;
-}
-
-export function closeDatabase(): void {
-  if (db) {
-    db.close();
-    db = null;
-  }
-}
-
-/**
- * Initialize database schema
- */
-export function initializeSchema(): void {
-  const db = getDatabase();
-  
-  // Users table
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS users (
-      id TEXT PRIMARY KEY,
-      email TEXT UNIQUE NOT NULL,
-      password_hash TEXT NOT NULL,
-      name TEXT NOT NULL,
-      profile_picture TEXT,
-      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-    )
-  `);
-  
-  // Products table
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS products (
-      id TEXT PRIMARY KEY,
-      name TEXT NOT NULL,
-      description TEXT,
-      price REAL NOT NULL,
-      category TEXT NOT NULL,
-      stock INTEGER NOT NULL DEFAULT 0,
-      image_url TEXT,
-      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-    )
-  `);
-  
-  // Addresses table
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS addresses (
-      id TEXT PRIMARY KEY,
-      user_id TEXT NOT NULL,
-      full_name TEXT NOT NULL,
-      street TEXT NOT NULL,
-      city TEXT NOT NULL,
-      state TEXT NOT NULL,
-      zip_code TEXT NOT NULL,
-      country TEXT NOT NULL DEFAULT 'USA',
-      phone TEXT NOT NULL,
-      is_default INTEGER DEFAULT 0,
-      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-      FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-    )
-  `);
-  
-  // Carts table
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS carts (
-      id TEXT PRIMARY KEY,
-      user_id TEXT NOT NULL,
-      product_id TEXT NOT NULL,
-      quantity INTEGER NOT NULL DEFAULT 1,
-      added_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-      FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
-      FOREIGN KEY (product_id) REFERENCES products(id) ON DELETE CASCADE,
-      UNIQUE(user_id, product_id)
-    )
-  `);
-  
-  // Orders table
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS orders (
-      id TEXT PRIMARY KEY,
-      user_id TEXT NOT NULL,
-      shipping_address_id TEXT NOT NULL,
-      total REAL NOT NULL,
-      status TEXT NOT NULL DEFAULT 'pending',
-      payment_method TEXT NOT NULL DEFAULT 'credit_card',
-      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-      FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
-      FOREIGN KEY (shipping_address_id) REFERENCES addresses(id)
-    )
-  `);
-  
-  // Order items table
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS order_items (
-      id TEXT PRIMARY KEY,
-      order_id TEXT NOT NULL,
-      product_id TEXT NOT NULL,
-      quantity INTEGER NOT NULL,
-      price REAL NOT NULL,
-      FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE,
-      FOREIGN KEY (product_id) REFERENCES products(id)
-    )
-  `);
-  
-  // Create indexes
-  db.exec(`
-    CREATE INDEX IF NOT EXISTS idx_carts_user_id ON carts(user_id);
-    CREATE INDEX IF NOT EXISTS idx_orders_user_id ON orders(user_id);
-    CREATE INDEX IF NOT EXISTS idx_order_items_order_id ON order_items(order_id);
-    CREATE INDEX IF NOT EXISTS idx_addresses_user_id ON addresses(user_id);
-  `);
-}
-
-/**
- * Clear all data (for testing)
- */
-export function clearAllData(): void {
-  const db = getDatabase();
-  
-  db.exec(`
-    DELETE FROM order_items;
-    DELETE FROM orders;
-    DELETE FROM carts;
-    DELETE FROM addresses;
-    DELETE FROM products;
-    DELETE FROM users;
-  `);
-}
-
-