@stackwright-pro/otters 0.1.0

package/.code-puppy.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": [
+    {
+      "name": "stackwright-pro-mcp",
+      "command": "pnpm",
+      "args": ["exec", "stackwright-pro-mcp"],
+      "autoStart": true,
+      "workingDirectory": "${PROJECT_ROOT}"
+    }
+  ]
+}

package/MCP_TOOLS.md

@@ -0,0 +1,264 @@
+# Stackwright Pro MCP Tools Reference
+
+This document defines the MCP tools available for Pro Otters.
+
+## Tool Naming Convention
+
+All Pro tools use the `stackwright_pro_` prefix to distinguish from OSS tools:
+- `stackwright_pro_*` — Pro-specific tools
+- `stackwright_*` — OSS Stackwright tools
+
+## Available Tools
+
+### API Discovery Tools
+
+#### `stackwright_pro_list_entities`
+
+Lists available entities from an OpenAPI spec or Zod schemas.
+
+**Arguments:**
+```typescript
+{
+  specPath?: string;      // Path to OpenAPI spec (YAML/JSON)
+  schemaPath?: string;    // Path to compiled Zod schemas
+  projectRoot?: string;   // Project root (auto-detected if omitted)
+}
+```
+
+**Returns:**
+```typescript
+{
+  success: boolean;
+  entities: {
+    name: string;         // "Equipment", "Supplies"
+    slug: string;         // "equipment", "supplies"
+    endpoint: string;     // "/equipment", "/supplies/{id}"
+    fieldCount: number;   // Number of fields
+    fields: {
+      name: string;
+      type: string;
+      required: boolean;
+      description?: string;
+    }[];
+    sourceFile: string;
+  }[];
+  errors?: string[];
+}
+```
+
+**Example:**
+```
+stackwright_pro_list_entities --specPath ./api.yaml
+```
+
+---
+
+#### `stackwright_pro_generate_filter`
+
+Generates endpoint filter configuration from selected entities.
+
+**Arguments:**
+```typescript
+{
+  selectedEntities: string[];  // Entity slugs to include
+  projectRoot?: string;       // Project root
+  outputFormat?: 'yaml' | 'json';
+}
+```
+
+**Returns:**
+```typescript
+{
+  success: boolean;
+  filter: {
+    include?: string[];   // Endpoint patterns to include
+    exclude?: string[];   // Endpoint patterns to exclude
+  };
+  yaml?: string;          // YAML snippet for stackwright.yml
+  errors?: string[];
+}
+```
+
+**Example:**
+```
+stackwright_pro_generate_filter --selectedEntities equipment,supplies
+```
+
+---
+
+#### `stackwright_pro_validate_spec`
+
+Validates an OpenAPI spec against approved-specs configuration.
+
+**Arguments:**
+```typescript
+{
+  specPath: string;
+  configPath?: string;     // Path to stackwright.yml with prebuild.security config
+}
+```
+
+**Returns:**
+```typescript
+{
+  valid: boolean;
+  specUrl: string;
+  errorCode?: 'SPEC_NOT_ON_ALLOWLIST' | 'SPEC_MODIFIED' | 'DOWNLOAD_FAILED';
+  error?: string;
+}
+```
+
+---
+
+#### `stackwright_pro_discover_and_filter`
+
+Convenience wrapper: list entities, let user select, generate filter.
+
+**Arguments:**
+```typescript
+{
+  specPath: string;
+  projectRoot?: string;
+}
+```
+
+**Returns:**
+```typescript
+{
+  success: boolean;
+  entities: Entity[];           // All discovered entities
+  selectedEntities: string[];   // User-selected slugs
+  filter: FilterConfig;         // Generated filter
+  yaml: string;                 // Ready-to-use YAML snippet
+}
+```
+
+---
+
+### ISR Configuration Tools
+
+#### `stackwright_pro_configure_isr`
+
+Configures ISR (Incremental Static Regeneration) for API-backed collections.
+
+**Arguments:**
+```typescript
+{
+  collection: string;           // Collection name
+  revalidateSeconds?: number;   // Revalidation interval (default: 60)
+  fallback?: 'blocking' | 'true' | 'false';
+  projectRoot?: string;
+}
+```
+
+**Returns:**
+```typescript
+{
+  success: boolean;
+  collection: string;
+  config: {
+    revalidate: number;
+    fallback: 'blocking' | 'true' | 'false';
+  };
+  yaml: string;  // YAML snippet to add to stackwright.yml
+}
+```
+
+---
+
+### Dashboard Generation Tools
+
+#### `stackwright_pro_generate_dashboard`
+
+Generates a dashboard page configuration from API entities.
+
+**Arguments:**
+```typescript
+{
+  entities: string[];            // Entity slugs to include
+  layout: 'grid' | 'table' | 'mixed';
+  projectRoot?: string;
+}
+```
+
+**Returns:**
+```typescript
+{
+  success: boolean;
+  pageConfig: {
+    slug: string;
+    content: YAMLContent;
+  };
+  validationResult: ValidationResult;
+}
+```
+
+---
+
+### Enterprise Security Tools
+
+#### `stackwright_pro_add_approved_spec`
+
+Adds a spec to the approved-specs allowlist.
+
+**Arguments:**
+```typescript
+{
+  name: string;
+  url: string;
+  sha256: string;
+  configPath?: string;     // Path to stackwright.yml
+}
+```
+
+**Returns:**
+```typescript
+{
+  success: boolean;
+  message: string;
+  config: PrebuildSecurityConfig;
+}
+```
+
+---
+
+#### `stackwright_pro_list_approved_specs`
+
+Lists all approved specs in the configuration.
+
+**Arguments:**
+```typescript
+{
+  configPath?: string;     // Path to stackwright.yml
+}
+```
+
+**Returns:**
+```typescript
+{
+  specs: {
+    name: string;
+    url: string;
+    sha256: string;
+  }[];
+  securityEnabled: boolean;
+}
+```
+
+---
+
+## Usage by Otter
+
+| Otter | Tools Used |
+|-------|------------|
+| API Otter | `stackwright_pro_list_entities`, `stackwright_pro_validate_spec` |
+| Data Otter | `stackwright_pro_generate_filter`, `stackwright_pro_configure_isr` |
+| Dashboard Otter | `stackwright_pro_generate_dashboard`, `stackwright_render_page` |
+| Foreman Pro Otter | All of the above + `stackwright_scaffold_project` |
+
+## Future Tools (Phase 2)
+
+- `stackwright_pro_test_api_connection` — Test API connectivity
+- `stackwright_pro_generate_types` — Generate TypeScript types from spec
+- `stackwright_pro_generate_zod_schemas` — Generate Zod schemas
+- `stackwright_pro_export_collection` — Export API data to file

package/PRO_OTTER_ARCHITECTURE.md

@@ -0,0 +1,179 @@
+# Pro Otter Architecture
+
+## Overview
+
+The Pro Otter Raft builds on the OSS Stackwright Otter Raft to add live API integration. While OSS otters build static content pages, Pro otters connect pages to real-time API data.
+
+## The Pro Raft
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                    PRO OTTER RAFT                                    │
+├────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  🦦🔧 Foreman Pro Otter                                            │
+│  ├── Entry point for Pro projects                                   │
+│  ├── Orchestrates: API → Data → Dashboard pipeline                  │
+│  └── Invokes child otters via agent_share_your_reasoning          │
+│                                                                     │
+│  🦦🔍 API Otter                                                    │
+│  ├── Discovers entities from OpenAPI specs                          │
+│  ├── Validates specs against approved-specs (enterprise)             │
+│  └── Outputs: Entity list + spec validation                        │
+│                                                                     │
+│  🦦📊 Data Otter                                                   │
+│  ├── Generates endpoint filters from selected entities              │
+│  ├── Configures ISR revalidation intervals                          │
+│  └── Outputs: stackwright.yml API configuration                     │
+│                                                                     │
+│  🦦📈 Dashboard Otter                                               │
+│  ├── Builds pages displaying live API data                          │
+│  ├── Uses collection_listing, data_table, stats_grid content types  │
+│  └── Outputs: Validated pages/*.yml files                          │
+│                                                                     │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+## Data Flow
+
+```
+1. FOREMAN PRO OTTER
+   │
+   ├─► "What API should we connect to?"
+   │
+   ▼
+2. API OTTER
+   │
+   ├─► stackwright_pro_list_entities --specPath <url>
+   │
+   ├─► "Found 47 entities: Equipment, Supplies, Personnel..."
+   │
+   ├─► User selects: equipment, supplies
+   │
+   ▼
+3. DATA OTTER
+   │
+   ├─► stackwright_pro_generate_filter --selectedEntities equipment,supplies
+   │
+   ├─► Generates: endpoints.include: ["/equipment/**", "/supplies/**"]
+   │
+   ├─► stackwright_pro_configure_isr --collection equipment --revalidateSeconds 60
+   │
+   ├─► stackwright_pro_configure_isr --collection supplies --revalidateSeconds 120
+   │
+   ▼
+4. DASHBOARD OTTER
+   │
+   ├─► Reads: stackwright.yml (API config)
+   │
+   ├─► Designs: Equipment listing + detail views
+   │
+   ├─► Writes: pages/equipment/content.yml
+   │
+   ├─► Validates: stackwright_validate_pages
+   │
+   └─► Renders: stackwright_render_page --slug /equipment
+```
+
+## MCP Tool Categories
+
+### Discovery Tools
+- `stackwright_pro_list_entities` — Find entities in OpenAPI spec
+- `stackwright_pro_validate_spec` — Check against approved specs
+
+### Configuration Tools
+- `stackwright_pro_generate_filter` — Create endpoint filters
+- `stackwright_pro_configure_isr` — Set revalidation intervals
+
+### Generation Tools
+- `stackwright_pro_generate_dashboard` — Create dashboard pages
+- `stackwright_pro_add_approved_spec` — Add to allowlist
+
+## Enterprise Mode
+
+When `prebuild.security.enabled: true` in stackwright.yml:
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                    ENTERPRISE MODE                                   │
+├────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  User provides: https://api.gov.mil/logistics/v1/openapi.yaml       │
+│                                                                     │
+│  API OTTER:                                                          │
+│  ├─► stackwright_pro_validate_spec --specPath <url>                 │
+│  │                                                                  │
+│  │   Validates:                                                     │
+│  │   ├─► URL is on approved-specs allowlist                        │
+│  │   ├─► SHA-256 hash matches approved version                      │
+│  │   └─► No SSRF risk (redirects blocked)                          │
+│  │                                                                  │
+│  └─► ✓ Spec approved OR ✗ Security rejection                       │
+│                                                                     │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+## Dashboard Page Types
+
+| Content Type | Use Case | API Binding |
+|--------------|----------|-------------|
+| `collection_listing` | Paginated list of items | `collection: equipment` |
+| `data_table` | Sortable/filterable table | `collection: equipment` + `params: {sort, filter}` |
+| `stats_grid` | KPI cards | `collection: equipment` + `aggregate: count` |
+| `detail_view` | Single item detail | `collection: equipment` + `slug_field: id` |
+
+## File Outputs
+
+After a full Pro build:
+
+```
+project/
+├── stackwright.yml              # API integrations + ISR config
+├── src/
+│   └── generated/
+│       └── equipment/
+│           ├── client.ts        # Typed API client
+│           ├── types.ts         # TypeScript types
+│           └── schemas.ts       # Zod validation schemas
+└── pages/
+    └── equipment/
+        └── content.yml          # Dashboard page definition
+```
+
+## Dependencies
+
+### OSS MCP Server
+Pro otters depend on the OSS Stackwright MCP server for:
+- `stackwright_scaffold_project`
+- `stackwright_render_page`
+- `stackwright_validate_pages`
+
+### Pro MCP Server (packages/mcp/)
+Pro otters use the Pro MCP server for:
+- `stackwright_pro_list_entities`
+- `stackwright_pro_generate_filter`
+- `stackwright_pro_configure_isr`
+- etc.
+
+## Security Model
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                    SECURITY MODEL                                    │
+├────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  1. ENDPOINT FILTERING                                               │
+│     ├─► SME selects entities → only those endpoints generated        │
+│     └─► Prevents unauthorized API access                           │
+│                                                                     │
+│  2. APPROVED-SPECS (Enterprise)                                     │
+│     ├─► SHA-256 hash verification                                  │
+│     ├─► URL allowlist                                               │
+│     └─► Fails build if spec modified                               │
+│                                                                     │
+│  3. ISR REVALIDATION                                                │
+│     ├─► Stale-while-revalidate pattern                             │
+│     └─► Fails gracefully, never serves broken data                  │
+│                                                                     │
+└────────────────────────────────────────────────────────────────────┘
+```

package/README.md

@@ -0,0 +1,108 @@
+# Stackwright Pro Otter Raft 🦦
+
+AI agents for building Stackwright Pro projects with live API integration.
+
+## The Pro Raft
+
+| Otter | Role | What it does |
+|-------|------|--------------|
+| **Foreman Pro Otter** | Coordinator | Orchestrates API → Data → Dashboard pipeline |
+| **API Otter** | API Explorer | Discovers entities from OpenAPI specs |
+| **Data Otter** | Configuration | Generates endpoint filters, configures ISR |
+| **Dashboard Otter** | Page Builder | Builds pages displaying live API data |
+
+## Quick Start
+
+```bash
+# Start with Foreman Pro Otter
+code-puppy invoke stackwright-pro-foreman-otter
+
+# Or individual otters
+code-puppy invoke stackwright-pro-api-otter
+code-puppy invoke stackwright-pro-data-otter
+code-puppy invoke stackwright-pro-dashboard-otter
+```
+
+## What Pro Adds
+
+| Feature | OSS Stackwright | Pro Stackwright |
+|---------|-----------------|-----------------|
+| Content source | YAML files | Live API data |
+| Data freshness | Build-time | Real-time (ISR) |
+| API integration | None | OpenAPI → typed client |
+| Enterprise security | None | Approved-specs validation |
+
+## Prerequisites
+
+1. **Stackwright Pro packages installed:**
+   ```bash
+   pnpm add @stackwright-pro/openapi
+   ```
+
+2. **Pro MCP server running:**
+   ```bash
+   # The .code-puppy.json auto-starts the Pro MCP server
+   code-puppy invoke stackwright-pro-foreman-otter
+   ```
+
+3. **OpenAPI spec** (URL or local file):
+   - Government: `https://api.gov.mil/logistics/v1/openapi.yaml`
+   - Enterprise: `https://api.internal.com/openapi.json`
+   - Local: `./specs/my-api.yaml`
+
+## Example Workflow
+
+```
+> "Build me a logistics dashboard from our government API"
+
+FOREMAN PRO OTTER:
+├─► API OTTER: What spec should I use?
+│   
+│   "Here's the approved government API: https://api.gov.mil/logistics/v1/openapi.yaml"
+│
+├─► API OTTER: *discovers 47 entities*
+│   └─► Found: Equipment, Supplies, Personnel, Vehicles, Facilities...
+│   
+│   "Which entities do you want to display?"
+│   
+│   "Equipment, Supplies, and Vehicles"
+│
+├─► DATA OTTER: *generates endpoint filters*
+│   └─► Configured: /equipment/**, /supplies/**, /vehicles/**
+│   
+│   *configures ISR*
+│   └─► Equipment: revalidate=60s, Supplies: revalidate=120s
+│
+├─► DASHBOARD OTTER: *builds pages*
+│   └─► Created: /equipment, /supplies, /vehicles
+│   
+└─► "Done! Your logistics dashboard is ready."
+```
+
+## Enterprise Mode
+
+For government/defense environments, enable approved-specs validation:
+
+```yaml
+# stackwright.yml
+prebuild:
+  security:
+    enabled: true
+    allowlist:
+      - name: Logistics API
+        url: https://api.gov.mil/logistics/v1/openapi.yaml
+        sha256: a1b2c3d4e5f6...
+```
+
+This ensures:
+- Only pre-approved API specs are used
+- Spec integrity verified via SHA-256
+- SSRF attacks blocked
+
+## MCP Tools
+
+See [MCP_TOOLS.md](./MCP_TOOLS.md) for full reference.
+
+## Architecture
+
+See [PRO_OTTER_ARCHITECTURE.md](./PRO_OTTER_ARCHITECTURE.md) for detailed architecture.

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@stackwright-pro/otters",
+  "version": "0.1.0",
+  "description": "Pro Otter Raft - AI agents for building full-stack Stackwright Pro projects with live API integration",
+  "license": "PROPRIETARY",
+  "files": [
+    "*.json",
+    "*.md"
+  ],
+  "peerDependencies": {
+    "@stackwright-pro/mcp": "0.1.0"
+  }
+}