@nitrostack/cli 1.0.6 → 1.0.8

package/templates/typescript-oauth/.env.example

@@ -0,0 +1,27 @@
+# OAuth 2.1 MCP Server Configuration
+# =============================================================================
+# TRANSPORT MODE (AUTO-CONFIGURED)
+# =============================================================================
+# When OAuth is configured, the server automatically runs in DUAL mode:
+# - STDIO: For MCP proto¯col communication with Studio/Claude
+# - HTTP: For OAuth metadata endpoints (/.well-known/oauth-protected-resource)
+# Both transports run simultaneously on different channels.
+# =============================================================================
+# REQUIRED: Server Configuration
+# =============================================================================
+# =============================================================================
+# Auth0 Configuration
+# =============================================================================
+# After creating your API and Application in Auth0, fill in these values:
+# Your Auth0 API Identifier (from APIs → MCP Server → Identifier)
+# This MUST match exactly what you set when creating the API
+# This MUST match exactly what you set when creating the API
+RESOURCE_URI=https://mcplocal
+# Your Auth0 tenant domain (authorization server)
+AUTH_SERVER_URL=https://dev-5dt0utuk315713tjm.us.auth0.com
+# Expected token audience (should match RESOURCE_URI)
+TOKEN_AUDIENCE=https://mcplocal
+# Expected token issuer (your Auth0 tenant domain with trailing slash)
+TOKEN_ISSUER=https://dev-5dt0utuk315713tjm.us.auth0.com
+
+DUFFEL_API_KEY=duffel_test_-w0wGDHB0M3DU9k-sBeUbxLqwcibUQqfEbjWDTKNnly

package/templates/typescript-oauth/README.md

@@ -1,263 +1,68 @@
 # ✈️ NitroStack Flight Booking
 
-A production-ready NitroStack template showcasing real-time flight search and booking with **Duffel API** integration. Search flights, view details, select seats, and book - all through beautiful interactive widgets.
+A production-ready template showcasing real-time flight search and booking with **Duffel API** integration. Learn how to build complex, authenticated MCP servers with high-impact visual widgets.
 
 ## ✨ Features
 
-### 🔌 **Duffel API Integration**
-- Real-time flight search across 300+ airlines
-- Live pricing and availability
-- Seat selection with cabin maps
-- Booking and order management
+- **Real-time Search** — Powered by the Duffel API (300+ airlines).
+- **Seat Selection** — Interactive visual cabin maps with seat pickers.
+- **Secure Payments** — Simulated secure booking and confirmation flows.
+- **Advanced Auth** — Optional OAuth 2.1 support for protected MCP servers.
 
-### 🎨 **Interactive Widgets**
-- **Airport Search** - Autocomplete airport selection
-- **Flight Search Results** - Compare flights with prices
-- **Flight Details** - Comprehensive flight information
-- **Seat Selection** - Visual cabin map with seat picker
-- **Order Summary** - Complete booking overview
-- **Payment Confirmation** - Secure payment flow
-
-### 🛠️ **MCP Tools**
-- `search_airports` - Find airports by name/code
-- `search_flights` - Search available flights
-- `show_flight_details` - Detailed flight information
-- `select_seats` - Interactive seat selection
-- `create_booking` - Book flights
-- `get_order` - Retrieve booking details
+---
 
 ## 🚀 Quick Start
 
-### Prerequisites
-
-```bash
-# Install NitroStack CLI globally
-npm install -g nitrostack
-
-# Or use npx
-npx nitrostack --version
-```
-
-### 1. Create Your Project
+### 1. Initialize Your Project
 
 ```bash
-# Create a new project
-nitrostack init my-flight-app --template typescript-oauth
+npx nitrostack init my-flight-app --template typescript-oauth
 cd my-flight-app
-
-# Install all dependencies (root + widgets)
-nitrostack install
 ```
 
-### 2. Get Your Duffel API Key (Free)
-
-[Duffel](https://duffel.com/) provides a free API for flight search and booking:
-
-1. **Sign up** at [duffel.com](https://duffel.com/) (click "Start now" - it's free!)
-2. Create a free account (no credit card required)
-3. Go to your **Dashboard** → **Developers** → **Access tokens**
-4. Click **"Create token"** to generate your API key
-5. Copy the token (starts with `duffel_test_` for sandbox)
-
-> 💡 **Tip**: The test mode (`duffel_test_*` tokens) gives you access to realistic mock data for development. Production tokens (`duffel_live_*`) connect to real airlines.
-
-### 3. Configure Environment
-
-Copy the example environment file and add your Duffel API key:
+### 2. Install Dependencies
 
 ```bash
-cp .env.example .env
+npm run install:all
 ```
 
-Edit `.env` and update:
-
-```env
-# Duffel API Configuration
-DUFFEL_API_KEY=duffel_test_your_api_key_here
-```
-
-### 4. Run Development Server
-
-```bash
-npm run dev
-```
-
-This starts:
-- **MCP Server** - Hot reloads on code changes
-- **Studio** on http://localhost:3000 - Visual testing environment  
-- **Widget Dev Server** on http://localhost:3001 - Hot module replacement
-
-### 5. Test in Studio
-
-Try these prompts in Studio chat:
-- "Search flights from London to New York for next week"
-- "Show me flight details"
-- "I want to select seats"
-- "Show me flights from JFK to LAX"
-
-## 📁 Project Structure
-
-```
-typescript-oauth/
-├── src/
-│   ├── index.ts                 # Main server entry
-│   ├── app.module.ts            # App module
-│   ├── services/
-│   │   └── duffel.service.ts    # Duffel API client
-│   └── modules/
-│       └── flights/
-│           ├── flights.module.ts    # Module definition
-│           ├── flights.tools.ts     # Search & display tools
-│           ├── flights.prompts.ts   # AI prompts
-│           ├── flights.resources.ts # Static resources
-│           └── booking.tools.ts     # Booking tools
-│   └── widgets/
-│       ├── app/
-│       │   ├── airport-search/      # Airport autocomplete
-│       │   ├── flight-search-results/ # Results list
-│       │   ├── flight-details/      # Flight info
-│       │   ├── seat-selection/      # Seat picker
-│       │   ├── order-summary/       # Booking summary
-│       │   └── payment-confirmation/ # Payment widget
-├── .env.example                 # Environment template
-├── OAUTH_SETUP.md              # OAuth configuration guide
-├── package.json
-└── README.md
-```
-
-## 🔧 Commands
-
-```bash
-# Installation
-npm install              # Install all dependencies (root + widgets)
-nitrostack install       # Same as above
+### 3. Get NitroStudio
 
-# Development
-npm run dev              # Start dev server with Studio
-npm run build            # Build TypeScript and widgets for production
-npm start                # Run production server
+Experience the visual seat selection and flight search as your users would see it.
 
-# Upgrade
-npm run upgrade          # Upgrade nitrostack to latest version
+1. **Download NitroStudio**: [nitrostack.ai/studio](https://nitrostack.ai/studio)
+2. **Open Project**: Launch NitroStudio and select your project folder.
 
-# Widget Management
-npm run widget <command> # Run npm command in widgets directory
-npm run widget add <pkg> # Add a widget dependency
-```
-
-## 🔐 OAuth Setup (Optional)
-
-This template includes OAuth 2.1 authentication support. If you want to protect your MCP server with authentication:
-
-1. Read the detailed guide: **[OAUTH_SETUP.md](./OAUTH_SETUP.md)**
-2. Configure Auth0 (or your OAuth provider)
-3. Update your `.env` with OAuth credentials
-
-> **Note**: OAuth is optional for local development. The template works without it using Duffel's test API.
-
-## 📊 Duffel API Features
-
-### Test Mode vs Live Mode
-
-| Feature | Test Mode (`duffel_test_*`) | Live Mode (`duffel_live_*`) |
-|---------|----------------------------|----------------------------|
-| API Access | ✅ Full access | ✅ Full access |
-| Pricing | Mock data | Real prices |
-| Bookings | Simulated | Real bookings |
-| Credit Card | Not charged | Charged |
-| Rate Limits | Generous | Production limits |
-
-### Supported Airlines
-
-Duffel provides access to 300+ airlines including:
-- Major carriers (British Airways, Lufthansa, Emirates, etc.)
-- Low-cost carriers (Ryanair, EasyJet, Spirit, etc.)
-- Regional airlines
-
-### API Capabilities
-
-- **Search**: Real-time availability and pricing
-- **Ancillaries**: Seats, bags, meals
-- **Booking**: Create and manage orders
-- **Changes**: Modify existing bookings
-- **Cancellations**: Cancel and refund
-
-## 🎨 Widget Features
-
-### Airport Search Widget
-- Autocomplete with IATA codes
-- City and airport name search
-- Recent searches
-
-### Flight Search Results Widget
-- Compare multiple flights
-- Filter by stops, price, time
-- Sort options
-- Airline logos
-
-### Flight Details Widget
-- Complete itinerary
-- Fare breakdown
-- Baggage allowance
-- Flight duration and stops
-
-### Seat Selection Widget
-- Visual cabin map
-- Seat categories (standard, extra legroom, etc.)
-- Price per seat
-- Real-time availability
-
-## 🛠️ Customization
-
-### Adding New Airlines
-
-Duffel handles airline integrations automatically. You don't need to configure individual airlines.
-
-### Modifying Search Parameters
-
-Edit `src/modules/flights/flights.tools.ts` to customize:
-- Default passenger counts
-- Cabin class options
-- Date ranges
-- Result limits
-
-### Styling Widgets
-
-Each widget in `src/widgets/app/` can be customized:
-- Edit page.tsx for layout
-- Add custom CSS
-- Modify component styles
+---
 
-## 📚 Resources
+## ⚙️ Configuration
 
-### Duffel Documentation
-- [Duffel API Docs](https://duffel.com/docs/api)
-- [Duffel SDK (Node.js)](https://github.com/duffel/duffel-api-javascript)
-- [Duffel Postman Collection](https://duffel.com/docs/postman)
+### 1. Duffel API Key
 
-### NitroStack Documentation
-- [NitroStack Docs](https://nitrostack.ai/docs)
-- [Widget Development Guide](https://nitrostack.ai/docs/widgets)
+You need a free Duffel API key to see live flight data:
 
-## 💡 Tips
+1. Sign up at [duffel.com](https://duffel.com/).
+2. Copy your **Test Token** from the dashboard.
+3. Create `.env` from the example:
+   ```bash
+   cp .env.example .env
+   ```
+4. Update `DUFFEL_API_KEY` in your `.env`.
 
-- **Use Test Mode**: Start with `duffel_test_*` tokens for development
-- **Check Rate Limits**: Duffel has rate limits - cache searches when possible
-- **Error Handling**: The template includes comprehensive error handling
-- **Responsive Design**: Widgets are mobile-friendly out of the box
+### 2. OAuth (Optional)
 
-## 📚 Next Steps
+For production scenarios requiring user authentication, refer to [OAUTH_SETUP.md](./OAUTH_SETUP.md).
 
-- Try the **Starter Template** - Learn NitroStack basics
-- Try the **Pizza Shop Template** - Interactive maps with Mapbox
-- Read the [Duffel Getting Started Guide](https://duffel.com/docs/guides/getting-started)
+---
 
-## License
+## 🛠️ Commands
 
-MIT
+- `npm run dev` — Start the development ecosystem.
+- `npm run build` — Bundle TypeScript and widgets for deployment.
+- `npm run upgrade` — Keep NitroStack core up to date.
 
 ---
-
-**Built with ❤️ using NitroStack + Duffel API**
-
-Need help? Check [Duffel Support](https://duffel.com/docs) or [NitroStack Docs](https://nitrostack.ai/docs)
+**Official Resources**
+- [Website](https://nitrostack.ai)
+- [Docs](https://docs.nitrostack.ai)
+- [Duffel API](https://duffel.com/docs)

package/templates/typescript-pizzaz/.env.example

@@ -0,0 +1,8 @@
+# Mapbox Configuration (Optional)
+# =============================================================================
+# The map widget uses Mapbox GL for interactive maps. 
+# Get a free API key at: https://www.mapbox.com/
+# =============================================================================
+
+# Your Mapbox Public Token (starts with pk.)
+NEXT_PUBLIC_MAPBOX_TOKEN=pk.your_mapbox_token_here

package/templates/typescript-pizzaz/README.md

@@ -1,252 +1,77 @@
 # 🍕 NitroStack Pizza Shop Finder
 
-A comprehensive NitroStack template showcasing interactive pizza shop discovery with maps, lists, and detailed views. This template demonstrates the NitroStack Widget SDK for building beautiful, interactive widgets.
+A high-performance interactive template showcasing discovery with maps, lists, and detailed views. This template demonstrates the **NitroStack Widget SDK** for building beautiful, tool-driven visual experiences.
 
-## Features
+## ✨ Features
 
-### 🎨 **Widget SDK Features**
-- ✅ `useTheme()` - Automatic dark mode support
-- ✅ `useWidgetState()` - Persistent favorites and view preferences
-- ✅ `useMaxHeight()` - Responsive height-aware layouts
-- ✅ `useDisplayMode()` - Fullscreen mode adaptation
-- ✅ `useWidgetSDK()` - Tool calling, navigation, and external links
-- ✅ `<WidgetLayout>` - Automatic RPC setup
+- **Mapbox Integration** — Interactive maps with custom markers.
+- **Real-time State** — Shared state between server and widgets.
+- **Responsive Layouts** — Auto-adapting heights and display modes (Inline, PiP, Fullscreen).
+- **Interactive UI** — Sorting, filtering, and favorites persistence.
 
-### 🗺️ **Three Interactive Widgets**
-1. **Pizza Map** - Interactive Mapbox map with markers and shop selection
-2. **Pizza List** - Grid/list view with sorting, filtering, and favorites
-3. **Pizza Shop** - Detailed shop information with contact actions
-
-### 📊 **MCP Tools**
-- `show_pizza_map` - Display shops on an interactive map
-- `show_pizza_list` - Show filterable list of shops
-- `show_pizza_shop` - Display detailed shop information
+---
 
 ## 🚀 Quick Start
 
-### Prerequisites
-
-```bash
-# Install NitroStack CLI globally
-npm install -g nitrostack
-
-# Or use npx
-npx nitrostack --version
-```
-
-### Setup Your Project
+### 1. Initialize Your Project
 
 ```bash
-# Create a new project
-nitrostack init my-pizza-app --template typescript-pizzaz
+npx nitrostack init my-pizza-app --template typescript-pizzaz
 cd my-pizza-app
-
-# Install all dependencies (root + widgets)
-nitrostack install
 ```
 
-### Configure Mapbox (Optional but Recommended)
-
-The map widget uses Mapbox GL for beautiful interactive maps:
-
-1. Get a **free** API key from [Mapbox](https://www.mapbox.com/) (sign up takes 1 minute)
-2. Create `src/widgets/.env` file:
+### 2. Install Dependencies
 
 ```bash
-NEXT_PUBLIC_MAPBOX_TOKEN=your_mapbox_token_here
+npm run install:all
 ```
 
-> **Note**: The template works without Mapbox, but the map widget will show a placeholder. You can still use the list and shop detail widgets.
-
-### Run Development Server
+### 3. Step Up NitroStudio
 
-```bash
-npm run dev
-```
+NitroStudio provides the best experience for visual testing of widgets and maps.
 
-This starts:
-- **MCP Server** - Hot reloads on code changes
-- **Studio** on http://localhost:3000 - Visual testing environment
-- **Widget Dev Server** on http://localhost:3001 - Hot module replacement
+1. **Download NitroStudio**: [nitrostack.ai/studio](https://nitrostack.ai/studio)
+2. **Open Project**: Launch NitroStudio and select your project folder.
+3. **View Maps**: Use the chat or visual tools to explore your pizza shops.
 
-### Test in Studio
-
-Try these prompts in Studio chat:
-- "Show me pizza shops on a map"
-- "List all pizza shops"
-- "Show me details for Tony's New York Pizza"
-- "Find pizza shops with high ratings"
+---
 
-## 📁 Project Structure
+## ⚙️ Configuration
 
-```
-typescript-pizzaz/
-├── src/
-│   ├── index.ts                 # Main server entry
-│   ├── app.module.ts            # App module
-│   └── modules/
-│       └── pizzaz/
-│           ├── pizzaz.data.ts   # Pizza shop data
-│           ├── pizzaz.service.ts # Business logic
-│           ├── pizzaz.tools.ts  # MCP tools
-│           └── pizzaz.module.ts # Module definition
-│   └── widgets/
-│       ├── app/
-│       │   ├── pizza-map/       # Map widget
-│       │   ├── pizza-list/      # List widget
-│       │   └── pizza-shop/      # Shop detail widget
-│       └── components/
-│           └── PizzaCard.tsx    # Reusable card component
-├── package.json
-└── README.md
-```
+### Mapbox (Optional)
 
-## 🎨 Widget Features
+To enable the interactive map, add your Mapbox token:
 
-### Pizza Map Widget
-- **Interactive Mapbox map** with custom markers
-- **Shop sidebar** with quick selection
-- **Fullscreen mode** for better exploration
-- **Persistent favorites** using `useWidgetState()`
-- **Theme-aware** map styles (light/dark)
+1. Get a free token at [mapbox.com](https://www.mapbox.com/).
+2. Create `src/widgets/.env` and add:
+   ```env
+   NEXT_PUBLIC_MAPBOX_TOKEN=pk.your_token_here
+   ```
 
-### Pizza List Widget
-- **Grid/List view toggle** with state persistence
-- **Sorting** by rating, name, or price
-- **Favorites tracking** across sessions
-- **Responsive layout** using `useMaxHeight()`
-- **Filter panel** for advanced search
-
-### Pizza Shop Widget
-- **Hero image** with overlay information
-- **Contact actions** (call, directions, website)
-- **Specialties showcase**
-- **Related shops** recommendations
-- **External link handling** via `useWidgetSDK()`
+---
 
-## 🔧 Commands
+## 🛠️ Commands
 
 ```bash
-# Installation
-npm install              # Install all dependencies (root + widgets)
-nitrostack install       # Same as above
-
-# Development
-npm run dev              # Start dev server with Studio
-npm run build            # Build TypeScript and widgets for production
-npm start                # Run production server
-
-# Upgrade
-npm run upgrade          # Upgrade nitrostack to latest version
-
-# Widget Management
-npm run widget <command> # Run npm command in widgets directory
-npm run widget add <pkg> # Add a widget dependency
-```
-
-## 🛠️ Customization
-
-### Adding More Shops
-
-Edit `src/modules/pizzaz/pizzaz.data.ts`:
-
-```typescript
-export const PIZZA_SHOPS: PizzaShop[] = [
-  {
-    id: 'my-pizza-shop',
-    name: 'My Pizza Shop',
-    description: 'Amazing pizza!',
-    address: '123 Main St, City, State 12345',
-    coords: [-122.4194, 37.7749], // [lng, lat]
-    rating: 4.5,
-    reviews: 100,
-    priceLevel: 2,
-    cuisine: ['Italian', 'Pizza'],
-    hours: { open: '11:00 AM', close: '10:00 PM' },
-    phone: '(555) 123-4567',
-    website: 'https://example.com',
-    image: 'https://images.unsplash.com/photo-...',
-    specialties: ['Margherita', 'Pepperoni'],
-    openNow: true,
-  },
-  // ... more shops
-];
-```
-
-### Changing Map Style
-
-Edit `src/widgets/app/pizza-map/page.tsx`:
-
-```typescript
-style: isDark 
-  ? 'mapbox://styles/mapbox/dark-v11'  // Dark mode style
-  : 'mapbox://styles/mapbox/streets-v12' // Light mode style
-```
-
-### Adding New Filters
-
-Edit `src/modules/pizzaz/pizzaz.service.ts` to add more filter options.
-
-## 📚 SDK Features Demonstrated
-
-### Theme Awareness
-```typescript
-const theme = useTheme(); // 'light' | 'dark'
-const bgColor = theme === 'dark' ? '#000' : '#fff';
-```
-
-### State Persistence
-```typescript
-const [state, setState] = useWidgetState(() => ({
-  favorites: [],
-  viewMode: 'grid',
-}));
-
-// State persists across widget reloads
-setState({ ...state, favorites: [...state.favorites, shopId] });
-```
-
-### Responsive Layouts
-```typescript
-const maxHeight = useMaxHeight();
-return <div style={{ maxHeight }}>{content}</div>;
-```
-
-### Display Mode Adaptation
-```typescript
-const displayMode = useDisplayMode(); // 'inline' | 'pip' | 'fullscreen'
-const showSidebar = displayMode === 'fullscreen';
-```
-
-### External Links
-```typescript
-const { openExternal } = useWidgetSDK();
-openExternal('https://example.com');
-```
-
-## 🚀 Deployment
-
-### Build for Production
+# Start dev server with Studio integration
+npm run dev
 
-```bash
+# Build for production
 npm run build
-```
-
-### Deploy Widgets
-
-Widget HTML files will be generated in `src/widgets/out/` - these work identically in any MCP-compatible client including OpenAI ChatGPT.
 
-## 📚 Next Steps
-
-- Try the **Starter Template** - Learn the basics
-- Try the **Flight Booking Template** - API integration with Duffel
-- Read the [NitroStack Documentation](https://nitrostack.ai/docs)
-- Check out [Mapbox GL JS Documentation](https://docs.mapbox.com/mapbox-gl-js/)
+# Manage widgets directly
+npm run widget <command>
+```
 
-## License
+## 📁 Structure
 
-MIT
+- `src/modules/pizzaz/` — Core logic and pizza shop data.
+- `src/widgets/app/pizza-map/` — Next.js Map widget.
+- `src/widgets/app/pizza-list/` — Filterable shop list.
+- `src/widgets/app/pizza-shop/` — Detail view with actions.
 
 ---
-
-**Built with ❤️ using NitroStack**
+**Official Resources**
+- [Website](https://nitrostack.ai)
+- [Docs](https://docs.nitrostack.ai)
+- [Download Studio](https://nitrostack.ai/studio)

package/templates/typescript-pizzaz/src/modules/pizzaz/pizzaz.module.ts

@@ -1,11 +1,12 @@
 import { Module } from '@nitrostack/core';
 import { PizzazService } from './pizzaz.service.js';
 import { PizzazTools } from './pizzaz.tools.js';
+import { PizzazTaskTools } from './pizzaz.tasks.js';
 
 @Module({
     name: 'pizzaz',
     description: 'Pizza shop finder module',
-    controllers: [PizzazTools],
+    controllers: [PizzazTools, PizzazTaskTools],
     providers: [PizzazService],
 })
 export class PizzazModule { }