@nitrostack/cli 1.0.6 → 1.0.7

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 { }

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

@@ -0,0 +1,294 @@
+/**
+ * Pizzaz Task Tools
+ *
+ * Demonstrates the MCP Tasks feature — long-running, async tool execution
+ * with progress reporting and cancellation support.
+ *
+ * To test via MCP Inspector (or any MCP client that supports tasks):
+ *
+ *   tools/call  name="audit_pizza_shops"  task={}
+ *   → returns { task: { taskId, status: "working", ... } }
+ *
+ *   tasks/get   taskId=<id>
+ *   → returns current status & progress message
+ *
+ *   tasks/result  taskId=<id>
+ *   → blocks until done, then returns the full audit report
+ *
+ *   tasks/cancel  taskId=<id>
+ *   → cancels the running audit
+ */
+
+import { ToolDecorator as Tool, ExecutionContext, Injectable, z } from '@nitrostack/core';
+import { PizzazService } from './pizzaz.service.js';
+
+// ─── Input Schemas ─────────────────────────────────────────────────────────
+
+const AuditSchema = z.object({
+    /** Number of shops to audit. Defaults to all shops. */
+    maxShops: z
+        .number()
+        .int()
+        .min(1)
+        .max(20)
+        .optional()
+        .describe('Maximum number of pizza shops to audit (default: all)'),
+    /** Simulate a slow audit by adding a delay per shop in ms. */
+    delayPerShopMs: z
+        .number()
+        .int()
+        .min(0)
+        .max(5000)
+        .optional()
+        .default(800)
+        .describe('Simulated processing time per shop in milliseconds (default: 800ms)'),
+});
+
+const OrderPizzaSchema = z.object({
+    shopId: z.string().describe('ID of the pizza shop to order from'),
+    pizzaName: z.string().describe('Name of the pizza to order'),
+    quantity: z.number().int().min(1).max(10).default(1).describe('Number of pizzas to order'),
+});
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Score a shop 0–100 based on rating and review count */
+function scoreShop(shop: { rating: number; reviews: number; openNow: boolean }): number {
+    const ratingScore = (shop.rating / 5) * 60;       // 60% weight
+    const reviewScore = Math.min(shop.reviews / 500, 1) * 30; // 30% weight
+    const openBonus = shop.openNow ? 10 : 0;           // 10% bonus
+    return Math.round(ratingScore + reviewScore + openBonus);
+}
+
+function grade(score: number): string {
+    if (score >= 90) return 'A+';
+    if (score >= 80) return 'A';
+    if (score >= 70) return 'B';
+    if (score >= 60) return 'C';
+    return 'D';
+}
+
+// ─── Task Tools Controller ───────────────────────────────────────────────────
+
+@Injectable({ deps: [PizzazService] })
+export class PizzazTaskTools {
+    constructor(private readonly pizzazService: PizzazService) { }
+
+    /**
+     * audit_pizza_shops
+     *
+     * A long-running tool that audits every pizza shop in the database.
+     * It processes each shop one-by-one (with a configurable delay) so you
+     * can watch the progress messages update via tasks/get, then fetch the
+     * full report via tasks/result.
+     *
+     * taskSupport: 'optional' — works normally (sync) OR as a task.
+     * When invoked without `task: {}`, returns the audit immediately.
+     * When invoked with `task: {}`, returns a task handle immediately and
+     * runs the audit in the background.
+     */
+    @Tool({
+        name: 'audit_pizza_shops',
+        description:
+            'Runs a quality audit across all pizza shops. ' +
+            'This is a long-running operation — use task augmentation to run it asynchronously. ' +
+            'Pass `task: {}` in your tools/call request to get a task handle, ' +
+            'then poll with tasks/get and retrieve the report with tasks/result.',
+        inputSchema: AuditSchema,
+        taskSupport: 'optional',
+        examples: {
+            request: { maxShops: 3, delayPerShopMs: 0 },
+            response: {
+                summary: {
+                    totalAudited: 3,
+                    averageScore: 82,
+                    topShop: 'Bella Napoli',
+                    completedAt: '2025-01-01T00:00:00.000Z',
+                },
+                results: [
+                    {
+                        shopId: 'bella-napoli',
+                        shopName: 'Bella Napoli',
+                        score: 92,
+                        grade: 'A+',
+                        notes: 'Exceptional rating and review volume. Currently open.',
+                    },
+                ],
+            },
+        },
+    })
+    async auditPizzaShops(
+        args: z.infer<typeof AuditSchema>,
+        ctx: ExecutionContext,
+    ) {
+        const allShops = this.pizzazService.getAllShops();
+        const shops = args.maxShops ? allShops.slice(0, args.maxShops) : allShops;
+        const delayMs = args.delayPerShopMs ?? 800;
+
+        ctx.logger.info('Starting pizza shop audit', {
+            totalShops: shops.length,
+            delayPerShopMs: delayMs,
+            isTask: !!ctx.task,
+        });
+
+        const results: Array<{
+            shopId: string;
+            shopName: string;
+            score: number;
+            grade: string;
+            notes: string;
+        }> = [];
+
+        for (let i = 0; i < shops.length; i++) {
+            const shop = shops[i];
+
+            // ── Cooperative cancellation check ──────────────────────────────
+            // If the client called tasks/cancel, we stop gracefully here
+            // instead of wasting time completing the rest of the audit.
+            if (ctx.task) {
+                ctx.task.throwIfCancelled();
+                ctx.task.updateProgress(
+                    `🔍 Auditing "${shop.name}" (${i + 1}/${shops.length})…`,
+                );
+            }
+
+            // Simulate I/O-bound work (DB queries, external API calls, etc.)
+            await sleep(delayMs);
+
+            // Check again after the async work — client may have cancelled
+            if (ctx.task?.isCancelled) {
+                ctx.task.throwIfCancelled();
+            }
+
+            const score = scoreShop(shop);
+            const shopGrade = grade(score);
+
+            const notes: string[] = [];
+            if (score >= 90) notes.push('Exceptional rating and review volume.');
+            if (!shop.openNow) notes.push('Currently closed — may affect customer reach.');
+            if (shop.rating >= 4.7) notes.push('One of the highest-rated shops.');
+            if (shop.reviews < 100) notes.push('Low review count — still building reputation.');
+
+            results.push({
+                shopId: shop.id,
+                shopName: shop.name,
+                score,
+                grade: shopGrade,
+                notes: notes.join(' ') || 'Solid performer.',
+            });
+
+            ctx.logger.info(`Audited ${shop.name}: score=${score} (${shopGrade})`);
+        }
+
+        // Final progress update before completing
+        if (ctx.task) {
+            ctx.task.updateProgress(`✅ Audit complete! Compiling report for ${results.length} shops…`);
+        }
+
+        const averageScore =
+            results.length > 0
+                ? Math.round(results.reduce((sum, r) => sum + r.score, 0) / results.length)
+                : 0;
+
+        const topShop = results.sort((a, b) => b.score - a.score)[0];
+
+        return {
+            summary: {
+                totalAudited: results.length,
+                averageScore,
+                topShop: topShop?.shopName ?? 'N/A',
+                completedAt: new Date().toISOString(),
+            },
+            results,
+        };
+    }
+
+    /**
+     * order_pizza
+     *
+     * A task-REQUIRED tool — it MUST always be called with task: {} because
+     * orders involve payment processing and confirmation steps that take time.
+     * This demonstrates the 'required' task support level.
+     *
+     * Invoke: tools/call  name="order_pizza"  task={}
+     *   arguments: { shopId: "bella-napoli", pizzaName: "Margherita", quantity: 2 }
+     */
+    @Tool({
+        name: 'order_pizza',
+        description:
+            'Places an order at a pizza shop. This tool REQUIRES task augmentation — ' +
+            'you must pass `task: {}` in your tools/call request. ' +
+            'Poll with tasks/get and retrieve your order confirmation via tasks/result.',
+        inputSchema: OrderPizzaSchema,
+        taskSupport: 'required',
+        examples: {
+            request: { shopId: 'bella-napoli', pizzaName: 'Margherita', quantity: 1 },
+            response: {
+                orderId: 'ORD-12345',
+                status: 'confirmed',
+                estimatedMinutes: 30,
+                total: '$18.00',
+                items: [{ name: 'Margherita', quantity: 1, price: '$18.00' }],
+            },
+        },
+    })
+    async orderPizza(
+        args: z.infer<typeof OrderPizzaSchema>,
+        ctx: ExecutionContext,
+    ) {
+        const shop = this.pizzazService.getShopById(args.shopId);
+        if (!shop) {
+            throw new Error(`Pizza shop not found: ${args.shopId}`);
+        }
+
+        ctx.logger.info('Processing pizza order', {
+            shopId: args.shopId,
+            pizza: args.pizzaName,
+            quantity: args.quantity,
+        });
+
+        // Step 1 — validate stock
+        ctx.task?.updateProgress(`🛒 Checking availability of "${args.pizzaName}" at ${shop.name}…`);
+        await sleep(600);
+        ctx.task?.throwIfCancelled();
+
+        // Step 2 — process payment
+        ctx.task?.updateProgress(`💳 Processing payment…`);
+        await sleep(1000);
+        ctx.task?.throwIfCancelled();
+
+        // Step 3 — confirm with kitchen
+        ctx.task?.updateProgress(`🍕 Confirming order with kitchen…`);
+        await sleep(700);
+        ctx.task?.throwIfCancelled();
+
+        // Step 4 — dispatch
+        ctx.task?.updateProgress(`🚴 Order dispatched! Generating confirmation…`);
+        await sleep(300);
+
+        const pricePerPizza = shop.priceLevel * 9;
+        const total = pricePerPizza * args.quantity;
+
+        ctx.logger.info('Order confirmed', { shopId: args.shopId, total });
+
+        return {
+            orderId: `ORD-${Date.now().toString(36).toUpperCase()}`,
+            status: 'confirmed',
+            shop: shop.name,
+            estimatedMinutes: 25 + Math.floor(Math.random() * 15),
+            total: `$${total.toFixed(2)}`,
+            items: [
+                {
+                    name: args.pizzaName,
+                    quantity: args.quantity,
+                    price: `$${(pricePerPizza * args.quantity).toFixed(2)}`,
+                },
+            ],
+            placedAt: new Date().toISOString(),
+        };
+    }
+}

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

@@ -0,0 +1,7 @@
+# NitroStack Starter Environment
+# =============================================================================
+# Add your environment variables here.
+# =============================================================================
+
+# Example:
+# API_KEY=your_api_key_here