@nitrostack/cli 1.0.6 → 1.0.8

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

package/templates/typescript-starter/README.md

@@ -1,320 +1,87 @@
-# NitroStack Starter Template
+# ⚡ NitroStack Starter Template
 
-**The simple starter template** - Learn NitroStack fundamentals with a clean calculator example.
+**The definitive starter template** — Learn the fundamentals of the NitroStack MCP framework with a clean, well-documented calculator example.
 
 ## 🎯 What's Inside
 
-This template demonstrates core NitroStack features:
+This template is designed to showcase core NitroStack features with zero friction:
 
-- **One Module** - Calculator module with all features
-- **One Tool** - `calculate` - Perform arithmetic operations
-- **One Resource** - `calculator://operations` - List of operations
-- **One Prompt** - `calculator_help` - Get usage help
-- **Two Widgets** - Beautiful UI for results and operations list
-- **No Authentication** - Focus on learning the basics
-- **No Database** - Pure computation example
+- **Modular Architecture** — Clean separation of concerns with a dedicated Calculator module.
+- **Interactive Tools** — A `calculate` tool for performing arithmetic operations.
+- **Dynamic Resources** — A `calculator://operations` resource for discovering capabilities.
+- **Prompt Library** — Context-aware prompts for guiding users.
+- **Pre-built UI Widgets** — Beautiful, high-performance UI components for results and listings.
+- **Production-Ready** — Uses TypeScript, Zod for validation, and best-in-class logging.
 
-## 🚀 Quick Start
-
-### Prerequisites
+---
 
-```bash
-# Install NitroStack CLI globally
-npm install -g nitrostack
+## 🚀 Quick Start
 
-# Or use npx
-npx nitrostack --version
-```
+### 1. Initialize Your Project
 
-### Setup Your Project
+If you haven't already, scaffold your project using the NitroStack CLI:
 
 ```bash
-# Create a new project
-nitrostack init my-calculator --template typescript-starter
-cd my-calculator
-
-# Install all dependencies (root + widgets)
-nitrostack install
+npx nitrostack init my-server --template typescript-starter
+cd my-server
 ```
 
-That's it! The CLI automatically:
-- ✅ Installs all root dependencies  
-- ✅ Installs widget dependencies
-- ✅ Sets up the project structure
+### 2. Install Dependencies
 
-### Run the Project
+Install all project dependencies (including the visual widget SDK) in one step:
 
 ```bash
-npm run dev
-```
-
-This starts:
-- **MCP Server** (dual transport: STDIO + HTTP) - 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). 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
-
-## 📁 Project Structure
-
+npm run install:all
 ```
-src/
-├── modules/
-│   └── calculator/
-│       ├── calculator.module.ts       # @Module definition
-│       ├── calculator.tools.ts        # @Tool with examples
-│       ├── calculator.resources.ts    # @Resource
-│       └── calculator.prompts.ts      # @Prompt
-├── widgets/                           # Next.js UI widgets
-│   └── app/
-│       ├── calculator-result/         # Tool result widget
-│       └── calculator-operations/     # Resource widget
-├── app.module.ts                      # Root @McpApp module
-└── index.ts                           # Application bootstrap
-```
-
-## 🛠️ Available Features
-
-### Health Check: `system`
 
-Monitors server health and resources:
+### 3. Get NitroStudio
 
-- **Uptime**: Server running time
-- **Memory Usage**: Heap memory consumption
-- **Process Info**: PID and Node.js version
-- **Status**: `up`, `degraded`, or `down`
+NitroStudio is the recommended visual client for running, testing, and managing your NitroStack projects.
 
-Check health status in Studio's Health Checks tab!
+1. **Download NitroStudio**: [nitrostack.ai/studio](https://nitrostack.ai/studio)
+2. **Open Project**: Launch NitroStudio and open this project folder.
+3. **Run**: NitroStudio handles the rest!
 
-### Tool: `calculate`
-
-Perform basic arithmetic operations:
-
-```typescript
-@Tool({
-  name: 'calculate',
-  description: 'Perform basic arithmetic calculations',
-  inputSchema: z.object({
-    operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
-    a: z.number(),
-    b: z.number()
-  }),
-  examples: {
-    request: { operation: 'add', a: 5, b: 3 },
-    response: { result: 8, expression: '5 + 3 = 8' }
-  }
-})
-```
-
-**Usage:**
-```
-User: "Calculate 5 + 3"
-AI: [Calls calculate tool]
-Result: Beautiful widget showing "5 + 3 = 8"
-```
-
-### Resource: `calculator://operations`
-
-Lists all available operations with examples.
-
-### Prompt: `calculator_help`
-
-Get help on how to use the calculator.
-
-## 🎨 Widgets
-
-### Calculator Result Widget
-- Gradient background
-- Operation icon
-- Breakdown of numbers
-- Beautiful animations
-
-### Calculator Operations Widget
-- Grid of all operations
-- Color-coded by type
-- Examples for each operation
-
-## 💡 Learning Path
-
-This template is perfect for learning:
+---
 
-1. **Module Organization** - How to structure a feature module
-2. **Tools** - How to create a tool with `@Tool` decorator
-3. **Resources** - How to expose data with `@Resource`
-4. **Prompts** - How to create conversation templates
-5. **Widgets** - How to build UI components
-6. **Examples** - How to include request/response examples
-7. **Validation** - How to use Zod schemas
+## 🛠️ Development
 
-## 🔧 Commands
+If you prefer using the command line:
 
 ```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 (e.g., @mui/material)
-```
-
-## 📝 Example Interactions
-
-### Basic Calculation
-```
-User: "What's 12 times 8?"
-AI: Calls calculate(operation="multiply", a=12, b=8)
-Result: Widget showing "12 × 8 = 96"
-```
-
-### Get Help
-```
-User: "How do I use the calculator?"
-AI: Uses calculator_help prompt
-Result: Complete usage instructions
-```
-
-### List Operations
-```
-User: "What operations are available?"
-AI: Fetches calculator://operations resource
-Result: Widget showing all 4 operations with examples
-```
-
-## 🎓 Code Walkthrough
-
-### 1. Tool Definition
-
-```typescript
-@Tool({
-  name: 'calculate',
-  description: 'Perform basic arithmetic calculations',
-  inputSchema: z.object({...}),
-  examples: {...}
-})
-@Widget('calculator-result')  // Link UI widget
-async calculate(input: any, ctx: ExecutionContext) {
-  // Your logic here
-  return { result, expression };
-}
-```
-
-**Key Points:**
-- `@Tool` decorator defines the tool
-- `inputSchema` validates input with Zod
-- `examples` help AI understand usage
-- `@Widget` links the UI component
-- `ExecutionContext` provides logger, metadata
-
-### 2. Resource Definition
-
-```typescript
-@Resource({
-  uri: 'calculator://operations',
-  name: 'Calculator Operations',
-  mimeType: 'application/json',
-  examples: {...}
-})
-@Widget('calculator-operations')
-async getOperations(uri: string, ctx: ExecutionContext) {
-  return { contents: [{...}] };
-}
-```
-
-### 3. Prompt Definition
-
-```typescript
-@Prompt({
-  name: 'calculator_help',
-  arguments: [...]
-})
-async getHelp(args: any, ctx: ExecutionContext) {
-  return { messages: [...] };
-}
-```
-
-### 4. Module Definition
-
-```typescript
-@Module({
-  name: 'calculator',
-  controllers: [CalculatorTools, CalculatorResources, CalculatorPrompts]
-})
-export class CalculatorModule {}
-```
+# Start development server (Server + Widgets + Studio)
+npm run dev
 
-### 5. Root Module
+# Build for production
+npm run build
 
-```typescript
-@McpApp({
-  server: { name: 'calculator-server', version: '1.0.0' }
-})
-@Module({
-  imports: [ConfigModule.forRoot(), CalculatorModule]
-})
-export class AppModule {}
+# Start production server
+npm start
 ```
 
-## 🚀 Extend This Template
-
-### Add More Operations
-
-Edit `calculator.tools.ts` and add new operations to the enum and switch statement.
-
-### Add History Feature
-
-1. Create a service to store calculations
-2. Add a `get_history` tool
-3. Create a history widget
-
-### Add More Modules
+## 📁 Project Structure
 
-```bash
-nitrostack generate module converter
+```text
+src/
+├── modules/
+│   └── calculator/
+│       ├── calculator.module.ts       # @Module definition
+│       ├── calculator.tools.ts        # @Tool implementations
+│       ├── calculator.resources.ts    # @Resource definitions
+│       └── calculator.prompts.ts      # @Prompt templates
+├── widgets/                           # Visual SDK UI components
+├── app.module.ts                      # Root application module
+└── index.ts                           # Server entry point
 ```
 
-## 📚 Next Steps
-
-Once you understand this template:
-
-1. Try the **Pizza Shop Template** - Interactive maps and widgets
-2. Try the **Flight Booking Template** - API integration with Duffel
-3. Read the [NitroStack Documentation](https://nitrostack.ai/docs)
+## 🎨 Next Generation MCP
 
-## 💡 Tips
+NitroStack is more than just a server; it's a full-stack MCP ecosystem.
 
-- **Keep it Simple** - This template shows the minimum needed
-- **Study the Code** - Each file has clear examples
-- **Test in Studio** - Use the chat to test your tools
-- **Check Examples** - The `examples` field helps AI understand your tools
-
-## 🎉 What to Build
-
-Use this as a starting point for:
-
-- **Unit Converters** - Temperature, currency, etc.
-- **Text Tools** - String manipulation, formatting
-- **Data Processors** - JSON, CSV, XML parsing
-- **Simple APIs** - Weather, jokes, facts
-- **Utilities** - Date/time, UUID generation
+- **Website**: [nitrostack.ai](https://nitrostack.ai)
+- **Documentation**: [docs.nitrostack.ai](https://docs.nitrostack.ai)
+- **Discord**: [Join our community](https://nitrostack.ai/discord)
 
 ---
-
-**Happy Learning! 📖**
-
-Start simple, learn the patterns, then build something amazing!
+**Happy Coding! 🎉**
+Build something amazing with NitroStack.