@stackwright-pro/otters 0.2.0 → 0.2.2

package/README.md

@@ -1,108 +1,132 @@
-# Stackwright Pro Otter Raft 🦦
+# @stackwright-pro/otters
 
-AI agents for building Stackwright Pro projects with live API integration.
+🦦🦦 **Stackwright Pro Otter Raft** — AI agents for full-stack API integration.
 
-## The Pro Raft
+A coordinated team of specialized AI agents (otters) that extend the OSS otter raft with API-first capabilities, live data dashboards, and enterprise auth integration.
 
-| 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
+## Installation
 
 ```bash
-# Start with Foreman Pro Otter
-code-puppy invoke stackwright-pro-foreman-otter
+npm install @stackwright-pro/otters
+# or
+pnpm add @stackwright-pro/otters
+```
+
+The postinstall script automatically installs Pro otters to `~/.code_puppy/agents/` for code-puppy discovery.
 
-# Or individual otters
-code-puppy invoke stackwright-pro-api-otter
-code-puppy invoke stackwright-pro-data-otter
-code-puppy invoke stackwright-pro-dashboard-otter
+If you need to re-run the installation:
+
+```bash
+node node_modules/@stackwright-pro/otters/scripts/install-agents.js
 ```
 
-## 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 |
+## The Pro Otter Raft
 
-## Prerequisites
+| Otter | Role | Output |
+|-------|------|--------|
+| 🦦🦦 **Foreman Otter** | Project coordinator | Orchestrates full-stack builds |
+| 🦦📡 **API Otter** | OpenAPI discovery | API entity types, endpoints |
+| 🦦📊 **Dashboard Otter** | Live data views | Typed API components |
+| 🦦🔗 **Data Otter** | Endpoint integration | ISR config, filters |
 
-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
-   ```
+## Pro vs OSS Otters
 
-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`
+| Feature | OSS | Pro |
+|---------|-----|-----|
+| Static site generation | ✅ | ✅ |
+| OpenAPI integration | ❌ | ✅ |
+| Live data dashboards | ❌ | ✅ |
+| Zod schema generation | ❌ | ✅ |
+| Typed API clients | ❌ | ✅ |
+| ISR configuration | ❌ | ✅ |
 
-## Example Workflow
+---
+
+## How It Works
+
+### The Pro Pipeline
 
 ```
-> "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."
+User Request (with OpenAPI spec)
+     │
+     ▼
+┌────────────────────────┐
+│  Pro Foreman Otter     │ ◄── Entry point (extends OSS Foreman)
+│  "Starting API build..."│
+└───────┬────────────────┘
+        │
+        ▼
+┌────────────────────────┐
+│  API Otter             │ ◄── OpenAPI → typed client
+│  (entity discovery)   │
+└───────┬────────────────┘
+        │ creates src/generated/*
+        ▼
+┌────────────────────────┐
+│  Dashboard Otter       │ ◄── Live API data views
+│  (components)          │
+└───────┬────────────────┘
+        │ creates pages/api/*
+        ▼
+┌────────────────────────┐
+│  Data Otter            │ ◄── ISR + endpoint config
+│  (filters, refresh)    │
+└───────┬────────────────┘
+        ▼
+     USER
+```
+
+### Invoking Pro Otters
+
+```bash
+# Full-stack API build
+code-puppy -i -a stackwright-pro-foreman-otter
+
+# API entity discovery
+code-puppy -i -a stackwright-pro-api-otter
+
+# Live dashboard generation
+code-puppy -i -a stackwright-pro-dashboard-otter
+
+# ISR configuration
+code-puppy -i -a stackwright-pro-data-otter
 ```
 
-## Enterprise Mode
+---
 
-For government/defense environments, enable approved-specs validation:
+## Package Structure
 
-```yaml
-# stackwright.yml
-prebuild:
-  security:
-    enabled: true
-    allowlist:
-      - name: Logistics API
-        url: https://api.gov.mil/logistics/v1/openapi.yaml
-        sha256: a1b2c3d4e5f6...
 ```
+@stackwright-pro/otters/
+├── package.json
+├── README.md
+├── MCP_TOOLS.md              # MCP tool documentation
+├── PRO_OTTER_ARCHITECTURE.md # Architecture details
+├── scripts/
+│   └── install-agents.js     # Postinstall script
+├── stackwright-pro-foreman-otter.json
+├── stackwright-pro-api-otter.json
+├── stackwright-pro-dashboard-otter.json
+└── stackwright-pro-data-otter.json
+```
+
+---
+
+## Dependencies
 
-This ensures:
-- Only pre-approved API specs are used
-- Spec integrity verified via SHA-256
-- SSRF attacks blocked
+Pro otters require:
 
-## MCP Tools
+- **@stackwright-pro/mcp** — MCP server for API tooling
+- **@stackwright/otters** — OSS otters (installed automatically)
 
-See [MCP_TOOLS.md](./MCP_TOOLS.md) for full reference.
+---
 
-## Architecture
+## License
 
-See [PRO_OTTER_ARCHITECTURE.md](./PRO_OTTER_ARCHITECTURE.md) for detailed architecture.
+MIT

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@stackwright-pro/otters",
-  "version": "0.2.0",
-  "description": "Pro Otter Raft - AI agents for building full-stack Stackwright Pro projects with live API integration",
-  "license": "PROPRIETARY",
+  "version": "0.2.2",
+  "description": "Stackwright Pro Otter Raft - AI agents for full-stack API integration",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Per-Aspera-LLC/stackwright-pro"
+  },
   "files": [
-    "*.json",
-    "*.md"
+    "scripts"
   ],
   "peerDependencies": {
-    "@stackwright-pro/mcp": "0.1.1"
+    "@stackwright-pro/mcp": "*"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install-agents.js"
   }
 }

package/scripts/install-agents.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Post-install script for @stackwright-pro/otters
+ * Copies Pro agent JSON files to ~/.code_puppy/agents/ for code-puppy discovery
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const AGENTS_DIR = path.join(os.homedir(), '.code_puppy', 'agents');
+
+// Resolve package root relative to this script's location
+const scriptDir = __dirname;
+const packageRoot = scriptDir.endsWith('/scripts') 
+  ? path.dirname(scriptDir)  // Running from within the package
+  : path.join(scriptDir, 'packages', 'otters');  // Running from monorepo root
+
+async function installAgents() {
+  try {
+    // Ensure ~/.code_puppy/agents/ exists
+    await fs.promises.mkdir(AGENTS_DIR, { recursive: true });
+
+    // Copy all JSON files from package root to ~/.code_puppy/agents/
+    const files = await fs.promises.readdir(packageRoot);
+
+    let installedCount = 0;
+    for (const file of files) {
+      if (file.endsWith('-otter.json')) {
+        const srcPath = path.join(packageRoot, file);
+        const destPath = path.join(AGENTS_DIR, file);
+
+        await fs.promises.copyFile(srcPath, destPath);
+        console.log(`✅ Installed Pro agent: ${file}`);
+        installedCount++;
+      }
+    }
+
+    if (installedCount > 0) {
+      console.log(`\n🦦🦦 Pro otters installed to ${AGENTS_DIR}`);
+      console.log('   Run "code-puppy -i -a stackwright-pro-foreman-otter" to start!');
+    } else {
+      console.log('⚠️  No Pro otter files found to install');
+    }
+  } catch (error) {
+    // Don't fail the install if this script has issues
+    console.warn(`⚠️  Failed to install Pro otters: ${error.message}`);
+  }
+}
+
+installAgents();

package/.code-puppy.json

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

package/CHANGELOG.md

@@ -1,18 +0,0 @@
-# @stackwright-pro/otters
-
-## 0.2.0
-
-### Minor Changes
-
-- 7c0e91f: ### `@stackwright-pro/display-components` (patch)
-  - **JSX type fix**: Fixed JSX type definitions for improved React compatibility
-
-  ### `@stackwright-pro/launch-stackwright-pro` (minor)
-  - **Otters as packages refactor**: Moved otter templates from inline to separate packages, updated template references
-
-  ### `@stackwright-pro/otters` (minor)
-  - **New package**: Created dedicated otters package with StackHawk brand otters (API, dashboard, data, foreman), MCP tools, and architecture documentation
-
-### Patch Changes
-
-- @stackwright-pro/mcp@0.1.1

package/MCP_TOOLS.md

@@ -1,264 +0,0 @@
-# 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