@nitrostack/cli 1.0.0

package/templates/typescript-pizzaz/README.md

@@ -0,0 +1,252 @@
+# 🍕 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.
+
+## 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
+
+### 🗺️ **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
+
+```bash
+# Create a new project
+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:
+
+```bash
+NEXT_PUBLIC_MAPBOX_TOKEN=your_mapbox_token_here
+```
+
+> **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
+
+```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
+
+### 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
+
+```
+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
+```
+
+## 🎨 Widget Features
+
+### 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)
+
+### 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
+
+```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
+
+```bash
+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/)
+
+## License
+
+MIT
+
+---
+
+**Built with ❤️ using NitroStack**

package/templates/typescript-pizzaz/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "nitrostack-pizzaz",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "NitroStack Pizza Shop Finder - Interactive map widgets with Mapbox integration",
+  "scripts": {
+    "dev": "nitrostack-cli dev",
+    "build": "nitrostack-cli build",
+    "start": "npm run build && nitrostack-cli start",
+    "start:prod": "nitrostack-cli start",
+    "upgrade": "nitrostack-cli upgrade",
+    "install:all": "nitrostack-cli install",
+    "widget": "npm --prefix src/widgets"
+  },
+  "keywords": [
+    "nitrostack",
+    "mcp",
+    "pizza",
+    "map",
+    "widgets"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "nitrostack": "^1",
+    "zod": "^3.22.4",
+    "dotenv": "^16.3.1"
+  },
+  "devDependencies": {
+    "@nitrostack/cli": "^1",
+    "typescript": "^5.3.3"
+  }
+}

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

@@ -0,0 +1,28 @@
+import { McpApp, Module, ConfigModule } from 'nitrostack';
+import { PizzazModule } from './modules/pizzaz/pizzaz.module.js';
+
+/**
+ * Root Application Module
+ * 
+ * Pizza shop finder with interactive maps.
+ * Showcases NitroStack Widget SDK features.
+ */
+@McpApp({
+    module: AppModule,
+    server: {
+        name: 'pizzaz-finder',
+        version: '1.0.0'
+    },
+    logging: {
+        level: 'info'
+    }
+})
+@Module({
+    name: 'pizzaz',
+    description: 'Pizza shop finder with interactive maps',
+    imports: [
+        ConfigModule.forRoot(),
+        PizzazModule
+    ],
+})
+export class AppModule { }

package/templates/typescript-pizzaz/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Pizzaz MCP Server
+ * 
+ * Pizza shop finder with interactive map widgets.
+ * Showcases NitroStack Widget SDK features including:
+ * - useTheme() for dark mode
+ * - useWidgetState() for persistent favorites
+ * - useDisplayMode() for fullscreen support
+ * - useMaxHeight() for responsive layouts
+ * - useWidgetSDK() for tool calling and navigation
+ */
+
+import 'dotenv/config';
+import { McpApplicationFactory } from 'nitrostack';
+import { AppModule } from './app.module.js';
+
+/**
+ * Bootstrap the application
+ */
+async function bootstrap() {
+    // Create and start the MCP server
+    const server = await McpApplicationFactory.create(AppModule);
+    await server.start();
+}
+
+// Start the application
+bootstrap().catch((error) => {
+    console.error('❌ Failed to start server:', error);
+    process.exit(1);
+});

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

@@ -0,0 +1,106 @@
+export interface PizzaShop {
+    id: string;
+    name: string;
+    description: string;
+    address: string;
+    coords: [number, number]; // [lng, lat]
+    rating: number;
+    reviews: number;
+    priceLevel: 1 | 2 | 3;
+    cuisine: string[];
+    hours: {
+        open: string;
+        close: string;
+    };
+    phone: string;
+    website?: string;
+    image: string;
+    specialties: string[];
+    openNow: boolean;
+}
+
+export const PIZZA_SHOPS: PizzaShop[] = [
+    {
+        id: 'tonys-pizza',
+        name: "Tony's New York Pizza",
+        description: "Authentic New York-style pizza with a crispy thin crust and fresh toppings",
+        address: "123 Main St, San Francisco, CA 94102",
+        coords: [-122.4194, 37.7749],
+        rating: 4.5,
+        reviews: 342,
+        priceLevel: 2,
+        cuisine: ['Italian', 'Pizza', 'New York Style'],
+        hours: { open: '11:00 AM', close: '10:00 PM' },
+        phone: '(415) 555-0123',
+        website: 'https://tonyspizza.example.com',
+        image: 'https://images.unsplash.com/photo-1513104890138-7c749659a591',
+        specialties: ['Margherita', 'Pepperoni', 'White Pizza'],
+        openNow: true,
+    },
+    {
+        id: 'bella-napoli',
+        name: 'Bella Napoli',
+        description: "Traditional Neapolitan pizza baked in a wood-fired oven",
+        address: "456 Market St, San Francisco, CA 94103",
+        coords: [-122.4089, 37.7858],
+        rating: 4.8,
+        reviews: 521,
+        priceLevel: 3,
+        cuisine: ['Italian', 'Pizza', 'Neapolitan'],
+        hours: { open: '12:00 PM', close: '11:00 PM' },
+        phone: '(415) 555-0456',
+        website: 'https://bellanapoli.example.com',
+        image: 'https://images.unsplash.com/photo-1574071318508-1cdbab80d002',
+        specialties: ['Marinara', 'Quattro Formaggi', 'Diavola'],
+        openNow: true,
+    },
+    {
+        id: 'slice-house',
+        name: 'The Slice House',
+        description: "Casual spot for creative pizza slices and craft beer",
+        address: "789 Valencia St, San Francisco, CA 94110",
+        coords: [-122.4216, 37.7599],
+        rating: 4.3,
+        reviews: 289,
+        priceLevel: 1,
+        cuisine: ['Pizza', 'American', 'Casual'],
+        hours: { open: '11:30 AM', close: '9:00 PM' },
+        phone: '(415) 555-0789',
+        image: 'https://images.unsplash.com/photo-1565299624946-b28f40a0ae38',
+        specialties: ['BBQ Chicken', 'Hawaiian', 'Veggie Supreme'],
+        openNow: true,
+    },
+    {
+        id: 'pizzeria-delfina',
+        name: 'Pizzeria Delfina',
+        description: "Upscale pizzeria with seasonal ingredients and house-made mozzarella",
+        address: "3611 18th St, San Francisco, CA 94110",
+        coords: [-122.4252, 37.7615],
+        rating: 4.6,
+        reviews: 678,
+        priceLevel: 3,
+        cuisine: ['Italian', 'Pizza', 'Fine Dining'],
+        hours: { open: '5:00 PM', close: '10:00 PM' },
+        phone: '(415) 555-3611',
+        website: 'https://pizzeriadelfina.example.com',
+        image: 'https://images.unsplash.com/photo-1571997478779-2adcbbe9ab2f',
+        specialties: ['Salsiccia', 'Funghi', 'Prosciutto e Rucola'],
+        openNow: false,
+    },
+    {
+        id: 'golden-boy',
+        name: 'Golden Boy Pizza',
+        description: "North Beach institution serving thick Sicilian-style squares",
+        address: "542 Green St, San Francisco, CA 94133",
+        coords: [-122.4102, 37.7999],
+        rating: 4.4,
+        reviews: 445,
+        priceLevel: 1,
+        cuisine: ['Pizza', 'Sicilian', 'Italian'],
+        hours: { open: '11:30 AM', close: '11:30 PM' },
+        phone: '(415) 555-0542',
+        image: 'https://images.unsplash.com/photo-1628840042765-356cda07504e',
+        specialties: ['Clam & Garlic', 'Pesto', 'Classic Cheese'],
+        openNow: true,
+    },
+];

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

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

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

@@ -0,0 +1,60 @@
+import { Injectable } from 'nitrostack';
+import { PIZZA_SHOPS, type PizzaShop } from './pizzaz.data.js';
+
+@Injectable()
+export class PizzazService {
+    /**
+     * Get all pizza shops
+     */
+    getAllShops(): PizzaShop[] {
+        return PIZZA_SHOPS;
+    }
+
+    /**
+     * Get a specific pizza shop by ID
+     */
+    getShopById(id: string): PizzaShop | undefined {
+        return PIZZA_SHOPS.find(shop => shop.id === id);
+    }
+
+    /**
+     * Get pizza shops filtered by criteria
+     */
+    getShopsFiltered(filters: {
+        openNow?: boolean;
+        minRating?: number;
+        maxPrice?: number;
+        cuisine?: string;
+    }): PizzaShop[] {
+        let shops = [...PIZZA_SHOPS];
+
+        if (filters.openNow) {
+            shops = shops.filter(shop => shop.openNow);
+        }
+
+        if (filters.minRating !== undefined) {
+            shops = shops.filter(shop => shop.rating >= filters.minRating!);
+        }
+
+        if (filters.maxPrice !== undefined) {
+            shops = shops.filter(shop => shop.priceLevel <= filters.maxPrice!);
+        }
+
+        if (filters.cuisine) {
+            shops = shops.filter(shop =>
+                shop.cuisine.some(c => c.toLowerCase().includes(filters.cuisine!.toLowerCase()))
+            );
+        }
+
+        return shops;
+    }
+
+    /**
+     * Get shops sorted by rating
+     */
+    getTopRatedShops(limit: number = 5): PizzaShop[] {
+        return [...PIZZA_SHOPS]
+            .sort((a, b) => b.rating - a.rating)
+            .slice(0, limit);
+    }
+}