@stackwright-pro/otters 0.0.0-beta-20260417191149

package/README.md

@@ -0,0 +1,271 @@
+# @stackwright-pro/otters
+
+🦦🦦 **Pro Otter Ecosystem** — Enterprise features that emerge when Pro otters join the raft.
+
+Pro otters don't replace the OSS raft — they extend it. When a Pro otter joins, the entire ecosystem adapts. Page Otter discovers Dashboard Otter and offers live data. Theme Otter discovers CAC requirements and suggests secure variants. The raft self-organizes.
+
+---
+
+## Dynamic Discovery
+
+All Pro otters use `list_agents()` for dynamic discovery at startup. This pattern ensures:
+
+- **Automatic coordination** — Pro otters find each other and OSS counterparts
+- **Graceful degradation** — Fall back to MCP tools if an otter is missing
+- **Context-aware behavior** — Adapt based on available teammates
+
+```typescript
+// Every Pro otter discovers at startup
+const agents = await list_agents();
+const proOtters = agents.filter((a) => a.name.includes('pro-'));
+const ossOtters = agents.filter((a) => a.name.includes('-otter') && !a.name.includes('pro-'));
+```
+
+### Pro + OSS Integration
+
+When Pro otters join an OSS raft, the following capabilities emerge:
+
+| OSS Otter     | Pro Enhancement | What Emerges                           |
+| ------------- | --------------- | -------------------------------------- |
+| Brand Otter   | Pro Specs       | Brand validation against approved APIs |
+| Theme Otter   | Pro Auth        | CAC-enabled secure themes              |
+| Page Otter    | Pro Dashboard   | Live data page generation              |
+| Foreman Otter | Pro Delegation  | Enterprise orchestration with fallback |
+
+### How Pro Otters Discover the OSS Raft
+
+```
+┌────────────────────────────────────────────────────────┐
+│                   DISCOVERY SEQUENCE                    │
+├────────────────────────────────────────────────────────┤
+│                                                         │
+│  code-puppy -i -a stackwright-pro-foreman-otter         │
+│                                                         │
+│  1. Pro Foreman starts                                   │
+│                                                         │
+│  2. list_agents() scans for otters:                     │
+│     ├─► OSS Foreman detected: stackwright-foreman-otter  │
+│     ├─► Pro specialists detected:                        │
+│     │   ├─► stackwright-pro-api-otter                    │
+│     │   ├─► stackwright-pro-data-otter                   │
+│     │   └─► stackwright-pro-dashboard-otter              │
+│     └─► OSS raft detected:                               │
+│         ├─► stackwright-brand-otter                      │
+│         ├─► stackwright-theme-otter                      │
+│         └─► stackwright-page-otter                      │
+│                                                         │
+│  3. Pro Foreman delegates to OSS Foreman:                 │
+│     "Delegating Brand → Theme → Pages to OSS Foreman"    │
+│                                                         │
+│  4. Pro capabilities available for addition:              │
+│     "API dashboards, CAC auth, OIDC ready"               │
+│                                                         │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+```bash
+# Install Pro otters
+npm install @stackwright-pro/otters
+
+# Or with pnpm
+pnpm add @stackwright-pro/otters
+```
+
+The postinstall script automatically installs Pro otters to `~/.code_puppy/agents/` for code-puppy discovery.
+
+```bash
+# User has OSS otters installed
+code-puppy -i -a stackwright-foreman-otter
+# Found: Brand ✓, Theme ✓, Page ✓
+
+# User installs Pro otters
+npm install @stackwright-pro/otters
+
+# Now with Pro discovery
+code-puppy -i -a stackwright-foreman-otter
+# Found: Brand ✓, Theme ✓, Page ✓
+# Pro detected: API Otter ✓, Data Otter ✓, Dashboard Otter ✓
+# "Live API dashboards now available - want some?"
+```
+
+The OSS Foreman Otter orchestrates the base pipeline. When Pro otters are present, they extend it silently — offering capabilities without overwhelming users who don't need them.
+
+If you need to re-run the installation:
+
+```bash
+node node_modules/@stackwright-pro/otters/scripts/install-agents.js
+```
+
+---
+
+## The Pro + OSS Raft: What Emerges
+
+When Pro otters combine with the OSS raft, these capabilities emerge:
+
+| Combined Otters              | Emergent Capability                     |
+| ---------------------------- | --------------------------------------- |
+| Page Otter + Dashboard Otter | "Add live data to this page?"           |
+| Theme Otter + Pro Auth       | "Enable CAC on this theme?"             |
+| Brand Otter + Pro Specs      | "Validate brand against approved APIs?" |
+| Foreman + All Pro Otters     | Enterprise orchestration                |
+| All Otters + Enterprise Mode | Security posture auto-detected          |
+
+---
+
+## The Pro Otter Raft
+
+| Otter                    | Role                 | Output                                                        |
+| ------------------------ | -------------------- | ------------------------------------------------------------- |
+| 🦦🦦 **Foreman Otter**   | Project coordinator  | Orchestrates full-stack builds (delegates to unified Foreman) |
+| 🦦📡 **API Otter**       | OpenAPI discovery    | API entity types, endpoints                                   |
+| 🦦📊 **Dashboard Otter** | Live data views      | Typed API components                                          |
+| 🦦🔗 **Data Otter**      | Endpoint integration | ISR config, filters                                           |
+
+---
+
+## Pro vs OSS Integration
+
+| Feature                | OSS          | Pro Integration                |
+| ---------------------- | ------------ | ------------------------------ |
+| Brand discovery        | ✅ OSS Otter | ✅ Pro can extend              |
+| Theme design           | ✅ OSS Otter | ✅ Enterprise themes available |
+| Page building          | ✅ OSS Otter | ✅ Live data pages emerge      |
+| API dashboards         | ❌           | ✅ Discovered dynamically      |
+| CAC auth               | ❌           | ✅ Suggested when available    |
+| Static site generation | ✅           | ✅ Extended with ISR           |
+
+The key insight: **Pro doesn't replace OSS — it amplifies it.** The OSS raft handles static content, SEO, and standard pages. Pro otters discover gaps in the raft and fill them with enterprise capabilities.
+
+---
+
+## How Pro Integrates
+
+### The Discovery Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                      CODE-PUPPY DISCOVERY                            │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  code-puppy -i -a stackwright-foreman-otter                           │
+│                                                                      │
+│  1. Lists all available agents                                       │
+│                                                                      │
+│  2. Filters for OSS raft:                                            │
+│     ├─► Brand Otter ✓                                                │
+│     ├─► Theme Otter ✓                                                │
+│     ├─► Page Otter ✓                                                 │
+│     └─► Foreman Otter ✓                                              │
+│                                                                      │
+│  3. Pro Foreman extends OSS Foreman:                                 │
+│     ├─► Adds API discovery hooks                                      │
+│     ├─► Adds ISR configuration                                       │
+│     └─► Adds Dashboard Otter coordination                            │
+│                                                                      │
+│  4. Emergent suggestions:                                             │
+│     "API spec detected → Generate dashboard?"                        │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Invoking Pro Otters
+
+```bash
+# Full-stack API build (via Foreman delegation)
+code-puppy -i -a stackwright-foreman-otter
+
+# API entity discovery (Pro otters work alongside OSS)
+code-puppy -i -a stackwright-pro-api-otter
+
+# Live dashboard generation (extends Page Otter)
+code-puppy -i -a stackwright-pro-dashboard-otter
+
+# ISR configuration (extends Data layer)
+code-puppy -i -a stackwright-pro-data-otter
+```
+
+---
+
+## The Pro Pipeline
+
+When a Pro otter joins an active OSS build:
+
+```
+User Request (with OpenAPI spec)
+     │
+     ▼
+┌────────────────────────┐
+│  OSS Foreman Otter     │ ◄── Base coordinator
+│  (Pro-aware)           │
+└───────┬────────────────┘
+        │ discovers Pro capabilities
+        ▼
+┌────────────────────────┐
+│  Pro API Otter          │ ◄── OpenAPI → typed client
+│  (entity discovery)    │   (extends OSS build)
+└───────┬────────────────┘
+        │ creates src/generated/*
+        ▼
+┌────────────────────────┐
+│  Pro Dashboard Otter   │ ◄── Live API data views
+│  (emerges with data)   │
+└───────┬────────────────┘
+        │ creates pages/api/*
+        ▼
+┌────────────────────────┐
+│  Pro Data Otter        │ ◄── ISR + endpoint config
+│  (configures refresh)  │
+└───────┬────────────────┘
+        ▼
+     USER
+```
+
+---
+
+## Package Structure
+
+```
+@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
+
+Pro otters require:
+
+- **@stackwright-pro/mcp** — MCP server for API tooling
+- **@stackwright/otters** — OSS otters (installed automatically)
+
+---
+
+## Emergent Capabilities
+
+When Pro otters join the raft, unexpected capabilities emerge:
+
+| Discovery                    | Emergent Feature                        |
+| ---------------------------- | --------------------------------------- |
+| Page Otter + Dashboard Otter | "Add live data to this page?"           |
+| Theme Otter + Pro Auth       | "Enable CAC on this theme?"             |
+| Brand Otter + Pro Specs      | "Validate brand against approved APIs?" |
+| All otters + Enterprise      | Security posture auto-detected          |
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@stackwright-pro/otters",
+  "version": "0.0.0-beta-20260417191149",
+  "description": "Stackwright Pro Otter Raft - AI agents for enterprise features (CAC auth, API dashboards, government use cases)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Per-Aspera-LLC/stackwright-pro"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18",
+    "zod": "^3.22.4"
+  },
+  "exports": {
+    "./src": "./src",
+    "./pro-foreman": "./src/stackwright-pro-foreman-otter.json"
+  },
+  "files": [
+    "scripts",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@stackwright-pro/mcp": "0.0.0-beta-20260417191149"
+  },
+  "scripts": {
+    "generate-checksums": "node scripts/generate-checksums.js",
+    "verify-checksums": "node scripts/verify-checksums.js",
+    "postinstall": "node scripts/install-agents.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/scripts/generate-checksums.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * generate-checksums.js
+ * Computes SHA-256 for every *-otter.json in src/ and writes src/checksums.json
+ * Run: node scripts/generate-checksums.js
+ * Auto-run: npm prepare (before publish), npm pretest (before tests)
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const scriptDir = __dirname;
+const packageRoot = path.resolve(scriptDir, '..');
+const srcDir = path.join(packageRoot, 'src');
+const outputFile = path.join(srcDir, 'checksums.json');
+
+async function generateChecksums() {
+  const entries = await fs.promises.readdir(srcDir);
+
+  const otterFiles = entries
+    .filter((f) => f.endsWith('-otter.json'))
+    .sort(); // alphabetical — deterministic output, no excuses
+
+  const files = {};
+  for (const filename of otterFiles) {
+    const filePath = path.join(srcDir, filename);
+    const raw = await fs.promises.readFile(filePath); // raw Buffer → utf-8 bytes, no funny business
+    const digest = crypto.createHash('sha256').update(raw).digest('hex');
+    files[filename] = digest;
+  }
+
+  const manifest = {
+    version: '1.0',
+    algorithm: 'sha256',
+    generated: new Date().toISOString(),
+    files,
+  };
+
+  await fs.promises.writeFile(outputFile, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+
+  console.log(`✅ checksums.json written with ${otterFiles.length} entr${otterFiles.length === 1 ? 'y' : 'ies'}:`);
+  for (const [name, hash] of Object.entries(files)) {
+    console.log(`   ${name}: ${hash}`);
+  }
+}
+
+generateChecksums().catch((err) => {
+  console.error('❌ generate-checksums failed:', err.message);
+  process.exit(1);
+});

package/scripts/install-agents.js

@@ -0,0 +1,60 @@
+#!/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 = path.resolve(scriptDir, '..');
+
+// All Pro otters are in the src/ directory
+const srcDir = path.join(packageRoot, 'src');
+
+async function installAgents() {
+  try {
+    // Ensure ~/.code_puppy/agents/ exists
+    await fs.promises.mkdir(AGENTS_DIR, { recursive: true });
+
+    // Copy all JSON files from src/ to ~/.code_puppy/agents/
+    const files = await fs.promises.readdir(srcDir);
+
+    let installedCount = 0;
+    for (const file of files) {
+      if (file.endsWith('-otter.json')) {
+        const srcPath = path.join(srcDir, file);
+        const destPath = path.join(AGENTS_DIR, file);
+
+        await fs.promises.copyFile(srcPath, destPath);
+        console.log(`✅ Installed: ${file}`);
+        installedCount++;
+      }
+    }
+
+    // Also install checksums manifest (informational — Python coordinator uses hardcoded constants)
+    const checksumsSource = path.join(packageRoot, 'src', 'checksums.json');
+    const checksumsDest = path.join(AGENTS_DIR, 'otter-checksums.REFERENCE-ONLY.json');
+    if (fs.existsSync(checksumsSource)) {
+      await fs.promises.copyFile(checksumsSource, checksumsDest);
+      console.log('✅ Installed: otter-checksums.REFERENCE-ONLY.json');
+    }
+
+    if (installedCount > 0) {
+      console.log(`Installing otters from: ${srcDir}`);
+      console.log(`\n🦦🦦 Pro otters installed to ${AGENTS_DIR}`);
+    } else {
+      console.log('⚠️  No Pro otter files found to install');
+    }
+  } catch (error) {
+    console.error(`❌  FATAL: Failed to install Pro otters: ${error.message}`);
+    process.exit(1);  // Fail the npm install — surface it early
+  }
+}
+
+installAgents();

package/scripts/verify-checksums.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * verify-checksums.js
+ * Read-only: verifies that *-otter.json files match the committed checksums.json
+ * Does NOT regenerate. For regeneration: node scripts/generate-checksums.js
+ *
+ * Exit codes:
+ *   0 = all checksums match
+ *   1 = one or more mismatches detected (tamper detected or file missing)
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const packageRoot = path.resolve(__dirname, '..');
+const srcDir = path.join(packageRoot, 'src');
+const checksumsPath = path.join(srcDir, 'checksums.json');
+
+// Read checksums manifest
+let manifest;
+try {
+  manifest = JSON.parse(fs.readFileSync(checksumsPath, 'utf8'));
+} catch (err) {
+  console.error(`❌  Cannot read checksums.json: ${err.message}`);
+  console.error('Run: node scripts/generate-checksums.js');
+  process.exit(1);
+}
+
+const expected = manifest.files || {};
+let failures = 0;
+let verified = 0;
+
+for (const [filename, expectedHash] of Object.entries(expected)) {
+  const filePath = path.join(srcDir, filename);
+  try {
+    const raw = fs.readFileSync(filePath);
+    const actual = crypto.createHash('sha256').update(raw).digest('hex');
+    if (actual !== expectedHash) {
+      console.error(`❌  MISMATCH: ${filename}`);
+      console.error(`   Expected: ${expectedHash.substring(0, 16)}...`);
+      console.error(`   Actual:   ${actual.substring(0, 16)}...`);
+      failures++;
+    } else {
+      console.log(`✅  ${filename}`);
+      verified++;
+    }
+  } catch (err) {
+    console.error(`❌  MISSING: ${filename} — ${err.message}`);
+    failures++;
+  }
+}
+
+if (failures > 0) {
+  console.error(`\n🚨  ${failures} checksum failure(s) detected. Run \`npm install @stackwright-pro/otters\` to restore.`);
+  process.exit(1);
+} else {
+  console.log(`\n✅  All ${verified} otter checksums verified.`);
+}

package/src/checksums.json

@@ -0,0 +1,15 @@
+{
+  "version": "1.0",
+  "algorithm": "sha256",
+  "generated": "2026-04-16T15:32:31.051Z",
+  "files": {
+    "stackwright-pro-api-otter.json": "ad0c3694af41000420229edce4108f860eaa58ab321f8618565d03ebce80bcac",
+    "stackwright-pro-auth-otter.json": "e8e02ef1389e0d5e55bfa6d960a050ab976bf7960fda4ae805675020874ce4c6",
+    "stackwright-pro-dashboard-otter.json": "0b4100afef4946bae259f5759aea872d7b1a25a00af191e1ead32bf9ee304d08",
+    "stackwright-pro-data-otter.json": "38ae3a26f064499a5f9773dfea1e2c21f9f358207110224a8e94c19443d236f1",
+    "stackwright-pro-designer-otter.json": "46c9fd94a46f1a3f5267f4cb70c3db0adfc28dc7d4ac50256cbe40ea5363b4f0",
+    "stackwright-pro-foreman-otter.json": "73f0913de78dfd3da726d9a32c63d84961985109c3ffc5c7522f6c63559609e7",
+    "stackwright-pro-page-otter.json": "0973f1b75a481fd177c5ada1a965f8c32e07f97fc28bbbf03b51d9e6d2af2f74",
+    "stackwright-pro-theme-otter.json": "2cca6eab4d7ee226d3fca488e908be6ace28dbaea9dae1b111cb76608f0747e6"
+  }
+}