@nitrostack/cli 1.0.10 → 1.0.13

package/templates/typescript-oauth/src/guards/oauth.guard.ts

@@ -41,6 +41,25 @@ export class OAuthGuard implements Guard {
     } else if (metaToken) {
       token = metaToken as string;
     }
+
+    // Enforcement gate: when OAuth is not required (OAUTH_REQUIRED not "true"),
+    // do not reject. Best-effort: if a valid token happens to be present, attach
+    // its identity; otherwise allow the request through unauthenticated.
+    if (!OAuthModule.isAuthRequired()) {
+      if (token) {
+        const result = await OAuthModule.validateToken(token);
+        if (result.valid) {
+          const payload = result.payload as OAuthTokenPayload;
+          context.auth = {
+            subject: payload.sub,
+            scopes: this.extractScopes(payload),
+            clientId: payload.client_id,
+            tokenPayload: payload,
+          };
+        }
+      }
+      return true;
+    }
     
     if (!token) {
       throw new Error(

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

@@ -28,26 +28,24 @@ async function bootstrap() {
   try {
     console.error('🔐 Starting Calculator MCP Server with OAuth 2.1...\\n');
 
-    // Validate required environment variables for OAuth
-    const requiredEnvVars = ['RESOURCE_URI', 'AUTH_SERVER_URL'];
-    const missing = requiredEnvVars.filter(v => !process.env[v]);
-
-    if (missing.length > 0) {
-      console.error('❌ Missing required OAuth environment variables:');
-      missing.forEach(v => console.error(`   - ${v}`));
-      console.error('\\n💡 Copy .env.example to .env and configure your OAuth provider');
-      console.error('   Or check the test-oauth/.env for reference\\n');
-      process.exit(1);
+    // Validate required environment variables for OAuth, set defaults if missing
+    if (!process.env.RESOURCE_URI || !process.env.AUTH_SERVER_URL) {
+      console.error('⚠️  Warning: Missing RESOURCE_URI or AUTH_SERVER_URL environment variables.');
+      console.error('   Defaulting to local test endpoints. Copy .env.example to .env to configure.\n');
+      process.env.RESOURCE_URI = process.env.RESOURCE_URI || 'http://localhost:3000';
+      process.env.AUTH_SERVER_URL = process.env.AUTH_SERVER_URL || 'http://localhost:8080/auth';
     }
 
     // Create the MCP application
     const server = await McpApplicationFactory.create(AppModule);
 
+    const authEnforced = process.env.OAUTH_REQUIRED === 'true';
     console.error('✅ OAuth 2.1 Module configured');
     console.error(`   Resource URI: ${process.env.RESOURCE_URI}`);
     console.error(`   Auth Server: ${process.env.AUTH_SERVER_URL}`);
     console.error(`   Scopes: read, write, admin`);
-    console.error(`   Audience: ${process.env.TOKEN_AUDIENCE || process.env.RESOURCE_URI}\\n`);
+    console.error(`   Audience: ${process.env.TOKEN_AUDIENCE || process.env.RESOURCE_URI}`);
+    console.error(`   Enforcement: ${authEnforced ? 'ON (OAUTH_REQUIRED=true)' : 'OFF (dev mode — set OAUTH_REQUIRED=true to enforce)'}\\n`);
 
     // Start the server
     await server.start();

package/templates/typescript-oauth/src/modules/flights/flights.prompts.ts

@@ -79,8 +79,26 @@ Respond to EXACTLY what the user asked - nothing more.`;
         ]
     })
     async flightComparison(input: any, ctx: ExecutionContext) {
+        let ids: string[] = [];
+        if (Array.isArray(input.offerIds)) {
+            ids = input.offerIds;
+        } else if (typeof input.offerIds === 'string') {
+            const trimmed = input.offerIds.trim();
+            if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    ids = Array.isArray(parsed) ? parsed : [parsed];
+                } catch {
+                    ids = trimmed.split(',').map((s: string) => s.trim());
+                }
+            } else {
+                ids = trimmed.split(',').map((s: string) => s.trim());
+            }
+        }
+        ids = ids.filter(Boolean);
+
         const offers = await Promise.all(
-            input.offerIds.map((id: string) => this.duffelService.getOffer(id))
+            ids.map((id: string) => this.duffelService.getOffer(id))
         );
 
         const comparisonData = offers.map((offer: any) => {

package/templates/typescript-oauth/src/services/duffel.service.ts

@@ -12,9 +12,11 @@ export class DuffelService {
     private duffel: Duffel;
 
     constructor() {
-        const apiKey = process.env.DUFFEL_API_KEY;
+        let apiKey = process.env.DUFFEL_API_KEY;
         if (!apiKey) {
-            throw new Error('DUFFEL_API_KEY environment variable is required');
+            console.error('⚠️  Warning: DUFFEL_API_KEY environment variable is missing.');
+            console.error('   Running with a dummy key for testing/dry-run mode.\n');
+            apiKey = 'duffel_test_dummy_key';
         }
 
         this.duffel = new Duffel({

package/templates/typescript-oauth/src/widgets/package.json

@@ -12,7 +12,8 @@
     "next": "^14.2.5",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "@nitrostack/widgets": "^1"
+    "@nitrostack/widgets": "^1",
+    "@modelcontextprotocol/ext-apps": ">=0.1.0"
   },
   "devDependencies": {
     "@types/node": "^20",

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

@@ -1,3 +1,17 @@
+# NitroStack Configuration
+NITRO_LOG_LEVEL=info
+NITROSTACK_APP_MODE=openai
+
+# Server Transport Configuration (Optional)
+# =============================================================================
+# MCP_TRANSPORT_TYPE: Toggles transport mode. Values: stdio | http | dual.
+# Defaults to 'stdio' in development and 'dual' in production/NODE_ENV=production.
+# =============================================================================
+# MCP_TRANSPORT_TYPE=stdio
+# PORT=3000
+# HOST=localhost
+# ENABLE_CORS=true
+
 # Mapbox Configuration (Optional)
 # =============================================================================
 # The map widget uses Mapbox GL for interactive maps. 

package/templates/typescript-pizzaz/README.md

@@ -1,79 +1,54 @@
-# 🍕 NitroStack Pizza Shop Finder
+# NitroStack Pizzaz Template
 
-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.
+Template focused on rich, interactive widget experiences (map/list/detail flows)
+using the NitroStack widget SDK patterns.
 
-## ✨ Features
+## What This Template Includes
 
-- **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.
+- Widget-heavy module and UI structure
+- Interactive examples for advanced frontends
+- Optional map provider integration pattern
+- Studio-friendly development workflow
 
----
-
-## 🚀 Quick Start
-
-### 1. Initialize Your Project
-
-```bash
-npx nitrostack init my-pizza-app --template typescript-pizzaz
-cd my-pizza-app
-```
-
-### 2. Install Dependencies
+## Quick Start
 
 ```bash
-npm run install:all
+npx @nitrostack/cli init my-pizzaz-app --template typescript-pizzaz
+cd my-pizzaz-app
+npm run dev
 ```
 
-### 3. Step Up NitroStudio
-
-NitroStudio provides the best experience for visual testing of widgets and maps.
-
-![NitroStudio](../../../../assets/gif/nitrostudio-main.gif)
-
-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.
-
----
+## Optional Configuration
 
-## ⚙️ Configuration
+If this project uses a map provider, configure API tokens in widget `.env` files
+as documented in the template source.
 
-### Mapbox (Optional)
-
-To enable the interactive map, add your Mapbox token:
-
-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
-   ```
-
----
-
-## 🛠️ Commands
+## Common Commands
 
 ```bash
-# Start dev server with Studio integration
 npm run dev
-
-# Build for production
 npm run build
-
-# Manage widgets directly
+npm start
 npm run widget <command>
 ```
 
-## 📁 Structure
+## NitroStudio
+
+NitroStudio is the fastest way to test and debug interactive widget output.
+
+- Download: <https://nitrostack.ai/studio>
+- Studio: <https://nitrostack.ai/studio>
+
+## Links
+
+- Docs: <https://docs.nitrostack.ai>
+- Widgets docs: <https://docs.nitrostack.ai/sdk/typescript/ui/widgets>
+- Main repository: <https://github.com/nitrocloudofficial/nitrostack>
 
-- `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.
+## Community
 
----
-**Official Resources**
-- [Website](https://nitrostack.ai)
-- [Docs](https://docs.nitrostack.ai)
-- [Download Studio](https://nitrostack.ai/studio)
+- Discord: <https://discord.gg/uVWey6UhuD>
+- X: <https://x.com/nitrostackai>
+- YouTube: <https://www.youtube.com/@nitrostackai>
+- LinkedIn: <https://linkedin.com/company/nitrostack-ai/>
+- GitHub: <https://github.com/nitrostackai>

package/templates/typescript-pizzaz/package.json

@@ -25,7 +25,8 @@
   "dependencies": {
     "@nitrostack/core": "^1",
     "zod": "^3.22.4",
-    "dotenv": "^16.3.1"
+    "dotenv": "^16.3.1",
+    "@modelcontextprotocol/ext-apps": ">=0.1.0"
   },
   "devDependencies": {
     "@nitrostack/cli": "^1",

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

@@ -1,6 +1,20 @@
 import { ToolDecorator as Tool, Widget, ExecutionContext, Injectable, z } from '@nitrostack/core';
 import { PizzazService } from './pizzaz.service.js';
 
+/**
+ * Pizzaz widget metadata for ChatGPT / MCP Apps (CSP for Unsplash images, optional border).
+ * For production ChatGPT submission, set `domain` to your app HTTPS origin per OpenAI Apps SDK docs.
+ */
+function pizzazWidget(route: string) {
+    return {
+        route,
+        prefersBorder: true,
+        csp: {
+            resourceDomains: ['https://images.unsplash.com'],
+        },
+    };
+}
+
 const ShowMapSchema = z.object({
     filter: z.enum(['open_now', 'top_rated', 'all']).optional().describe('Filter to apply'),
 });
@@ -67,7 +81,7 @@ export class PizzazTools {
             }
         }
     })
-    @Widget('pizza-map')
+    @Widget(pizzazWidget('pizza-map'))
     async showPizzaMap(args: z.infer<typeof ShowMapSchema>, ctx: ExecutionContext) {
         let shops;
 
@@ -122,7 +136,7 @@ export class PizzazTools {
             }
         }
     })
-    @Widget('pizza-list')
+    @Widget(pizzazWidget('pizza-list'))
     async showPizzaList(args: z.infer<typeof ShowListSchema>, ctx: ExecutionContext) {
         const shops = this.pizzazService.getShopsFiltered(args);
 
@@ -180,7 +194,7 @@ export class PizzazTools {
             }
         }
     })
-    @Widget('pizza-shop')
+    @Widget(pizzazWidget('pizza-shop'))
     async showPizzaShop(args: z.infer<typeof ShowShopSchema>, ctx: ExecutionContext) {
         const shop = this.pizzazService.getShopById(args.shopId);
 

package/templates/typescript-pizzaz/src/widgets/package.json

@@ -13,6 +13,7 @@
         "react": "^18.3.1",
         "react-dom": "^18.3.1",
         "@nitrostack/widgets": "^1",
+        "@modelcontextprotocol/ext-apps": ">=0.1.0",
         "mapbox-gl": "^3.0.1",
         "framer-motion": "^10.16.16",
         "lucide-react": "^0.294.0"

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

@@ -1,7 +1,13 @@
-# NitroStack Starter Environment
+# NitroStack Configuration
+NITRO_LOG_LEVEL=info
+NITROSTACK_APP_MODE=openai
+
+# Server Transport Configuration (Optional)
 # =============================================================================
-# Add your environment variables here.
+# MCP_TRANSPORT_TYPE: Toggles transport mode. Values: stdio | http | dual.
+# Defaults to 'stdio' in development and 'dual' in production/NODE_ENV=production.
 # =============================================================================
-
-# Example:
-# API_KEY=your_api_key_here
+# MCP_TRANSPORT_TYPE=stdio
+# PORT=3000
+# HOST=localhost
+# ENABLE_CORS=true

package/templates/typescript-starter/README.md

@@ -1,89 +1,49 @@
-# ⚡ NitroStack Starter Template
+# NitroStack Starter Template
 
-**The definitive starter template** — Learn the fundamentals of the NitroStack MCP framework with a clean, well-documented calculator example.
+Minimal template for learning NitroStack fundamentals with a calculator-focused
+MCP server and basic widgets.
 
-## 🎯 What's Inside
+## What This Template Includes
 
-This template is designed to showcase core NitroStack features with zero friction:
+- `calculator` module with tools, resources, and prompts
+- TypeScript + Zod validation setup
+- Widget-ready project structure
+- Production-friendly npm scripts
 
-- **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
-
-### 1. Initialize Your Project
-
-If you haven't already, scaffold your project using the NitroStack CLI:
+## Quick Start
 
 ```bash
-npx nitrostack init my-server --template typescript-starter
+npx @nitrostack/cli init my-server --template typescript-starter
 cd my-server
+npm run dev
 ```
 
-### 2. Install Dependencies
-
-Install all project dependencies (including the visual widget SDK) in one step:
-
-```bash
-npm run install:all
-```
-
-### 3. Get NitroStudio
-
-NitroStudio is the recommended visual client for running, testing, and managing your NitroStack projects.
-
-![NitroStudio](../../../../assets/gif/nitrostudio-main.gif)
-
-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!
-
----
-
-## 🛠️ Development
-
-If you prefer using the command line:
+## Common Commands
 
 ```bash
-# Start development server (Server + Widgets + Studio)
 npm run dev
-
-# Build for production
 npm run build
-
-# Start production server
 npm start
 ```
 
-## 📁 Project Structure
+## NitroStudio
 
-```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
-```
+NitroStudio is the recommended way to test and debug this template during
+development.
+
+- Download: <https://nitrostack.ai/studio>
+- Studio: <https://nitrostack.ai/studio>
 
-## 🎨 Next Generation MCP
+## Links
 
-NitroStack is more than just a server; it's a full-stack MCP ecosystem.
+- Docs: <https://docs.nitrostack.ai>
+- Templates docs: <https://docs.nitrostack.ai/templates/01-starter-template>
+- Main repository: <https://github.com/nitrocloudofficial/nitrostack>
 
-- **Website**: [nitrostack.ai](https://nitrostack.ai)
-- **Documentation**: [docs.nitrostack.ai](https://docs.nitrostack.ai)
-- **Discord**: [Join our community](https://nitrostack.ai/discord)
+## Community
 
----
-**Happy Coding! 🎉**
-Build something amazing with NitroStack.
+- Discord: <https://discord.gg/uVWey6UhuD>
+- X: <https://x.com/nitrostackai>
+- YouTube: <https://www.youtube.com/@nitrostackai>
+- LinkedIn: <https://linkedin.com/company/nitrostack-ai/>
+- GitHub: <https://github.com/nitrostackai>

package/templates/typescript-starter/package.json

@@ -16,7 +16,8 @@
   "dependencies": {
     "dotenv": "^16.3.1",
     "@nitrostack/core": "^1",
-    "zod": "^3.22.4"
+    "zod": "^3.22.4",
+    "@modelcontextprotocol/ext-apps": ">=0.1.0"
   },
   "devDependencies": {
     "@nitrostack/cli": "^1",

package/templates/typescript-starter/src/widgets/package.json

@@ -12,7 +12,8 @@
     "next": "^14.2.5",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "@nitrostack/widgets": "^1"
+    "@nitrostack/widgets": "^1",
+    "@modelcontextprotocol/ext-apps": ">=0.1.0"
   },
   "devDependencies": {
     "@types/node": "^20",