@stackwright-pro/otters 1.0.0-alpha.2 → 1.0.0-alpha.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackwright-pro/otters",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.20",
   "description": "Stackwright Pro Otter Raft - AI agents for enterprise features (CAC auth, API dashboards, government use cases)",
   "license": "MIT",
   "repository": {
@@ -8,21 +8,27 @@
     "url": "https://github.com/Per-Aspera-LLC/stackwright-pro"
   },
   "devDependencies": {
-    "vitest": "^1.4.0",
+    "vitest": "^4.0.18",
     "zod": "^3.22.4"
   },
   "exports": {
     "./src": "./src",
-    "./pro-foreman": "./src/stackwright-pro-foreman-otter.json"
+    "./pro-foreman": "./src/stackwright-pro-foreman-otter.json",
+    "./pro-workflow": "./src/stackwright-pro-workflow-otter.json"
   },
   "files": [
     "scripts",
     "src"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "peerDependencies": {
-    "@stackwright-pro/mcp": "0.2.0-alpha.0"
+    "@stackwright-pro/mcp": "^0.2.0-alpha.15"
   },
   "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",

package/scripts/generate-checksums.js

@@ -0,0 +1,52 @@
+#!/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',
+    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

@@ -37,6 +37,14 @@ async function installAgents() {
       }
     }
 
+    // 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}`);
@@ -44,9 +52,9 @@ async function installAgents() {
       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}`);
+    console.error(`❌  FATAL: Failed to install Pro otters: ${error.message}`);
+    process.exit(1);  // Fail the npm install — surface it early
   }
 }
 
-installAgents();
+installAgents();

package/scripts/launch-raft.cjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/* global console, process */
+
+// ⚠️ DEPRECATED — This launcher has been replaced by @stackwright-pro/raft.
+// Run: npx @stackwright-pro/raft
+// This file is kept for users who may have cached a previous install.
+// It will be removed in a future release.
+
+console.error('⚠️  launch-raft in @stackwright-pro/otters is deprecated.');
+console.error('   Use: npx @stackwright-pro/raft');
+console.error('');
+console.error('   Install: npm install -g @stackwright-pro/raft');
+console.error('   Or run directly: npx @stackwright-pro/raft');
+process.exit(1);

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",
+  "files": {
+    "stackwright-pro-api-otter.json": "f1cc9edf2dd1df3ebcea1d0ab33d17a358faaf8aa97ee232cd7994042f2eac0d",
+    "stackwright-pro-auth-otter.json": "a19e06c503209a8a35fe321d30448623545b36b48c47a6ec064d13406ad1f725",
+    "stackwright-pro-dashboard-otter.json": "b3cb3d7554f2e9eed3b57d5e0e3bf85d6ba5b4db5d3af5514391cf0575fcc001",
+    "stackwright-pro-data-otter.json": "bfacb87ae82867472a75982215554336a105a658d6cd3dd2c8b819fa1e11d7ac",
+    "stackwright-pro-designer-otter.json": "c58fa7c7ead9e6398074e1c7ce3f31a8ef4eb3679f5fa18cc03cae3a87878c88",
+    "stackwright-pro-foreman-otter.json": "f52264c1f6297b72f3da6d92d41b6d63356db776242caeab25571e6a8df628e4",
+    "stackwright-pro-page-otter.json": "65bec3a3a0dda6b7591bba2de9399f1e3a4fb99cfe1075342f4f4be98d917b67",
+    "stackwright-pro-theme-otter.json": "1f182326f1acd3d4091a38c7012085cbb4945893e95be4ca3de72318ad092767",
+    "stackwright-pro-workflow-otter.json": "0eec9d6a731678cf547c2a7b0b6fc338ca143c35501365a1e4e5dd2779dd5510"
+  }
+}

package/src/stackwright-pro-api-otter.json

@@ -3,13 +3,7 @@
   "name": "stackwright-pro-api-otter",
   "display_name": "Stackwright Pro API Otter 🦦",
   "description": "Analyzes API specs and extracts entity definitions",
-  "tools": [
-    "agent_run_shell_command",
-    "list_files",
-    "cp_list_files",
-    "cp_read_file",
-    "invoke_agent"
-  ],
+  "tools": ["agent_run_shell_command", "list_files", "cp_list_files", "cp_read_file"],
   "user_prompt": "Hey! 🦦 I'm the API Otter. Give me an OpenAPI spec path and I'll extract what entities and endpoints it exposes.",
   "system_prompt": [
     "## YOUR JOB",
@@ -27,13 +21,78 @@
     "4. List available entities for user selection",
     "",
     "## OUTPUT FORMAT",
-    "Report findings as a simple list:",
-    "- Entities: {list}",
-    "- Auth: {type}",
-    "- Base URL: {url}",
     "",
-    "## PASS TO DATA OTTER",
-    "After analysis, invoke pro-data-otter to wire collections.",
+    "**You return a JSON artifact to the Foreman. You do NOT create files.**",
+    "",
+    "Return ONLY valid JSON \u2014 no markdown fences, no prose, no comments. Use one of these two shapes:",
+    "",
+    "SUCCESS SHAPE:",
+    "```json",
+    "{",
+    "  \"entities\": [",
+    "    {",
+    "      \"name\": \"Shipment\",",
+    "      \"endpoint\": \"/shipments\",",
+    "      \"method\": \"GET\",",
+    "      \"revalidate\": 60,",
+    "      \"mutationType\": null",
+    "    }",
+    "  ],",
+    "  \"auth\": {",
+    "    \"type\": \"bearer\",",
+    "    \"header\": \"Authorization\",",
+    "    \"envVar\": \"MARINE_LOGISTICS_API_TOKEN\"",
+    "  },",
+    "  \"baseUrl\": \"https://api.marine-logistics.mil/v2\",",
+    "  \"specPath\": \"./specs/marine-combat-logistics.yaml\"",
+    "}",
+    "```",
+    "",
+    "ERROR SHAPE (use if spec is missing, unreadable, or unsupported format):",
+    "```json",
+    "{",
+    "  \"error\": \"Spec file not found at ./specs/missing.yaml\",",
+    "  \"specPath\": \"./specs/missing.yaml\"",
+    "}",
+    "```",
+    "",
+    "Field notes:",
+    "- entities[].revalidate: seconds for ISR cache (from x-revalidate extension), or null",
+    "- entities[].mutationType: \"create\"|\"update\"|\"delete\" for mutations, null for GET",
+    "- auth.type: one of \"none\" | \"api-key\" | \"bearer\" | \"oauth2\" | \"cac\"",
+    "  (cac = DoD Common Access Card / PKI certificate authentication)",
+    "- auth.envVar: environment variable name that will hold the credential",
+    "",
+    "---",
+    "",
+    "## SCOPE BOUNDARIES",
+    "",
+    "✅ **You DO:**",
+    "- Read and parse OpenAPI/GraphQL/AsyncAPI specs",
+    "- Extract entity names, endpoint paths, auth schemes, and base URLs",
+    "- Return a structured JSON artifact to the Foreman",
+    "",
+    "❌ **You DON'T:**",
+    "- Create any files (no .ts, no .js, no .json files on disk)",
+    "- Write TypeScript types, interfaces, or classes",
+    "- Write Zod schemas",
+    "- Generate API client classes (BaseApiClient, etc.)",
+    "- Write to src/generated/ or any other directory",
+    "",
+    "**WHY:** TypeScript type generation is @stackwright-pro/openapi's job at build time.",
+    "The otter's job is discovery and configuration — not code generation.",
+    "You have no file-write tools. If you find yourself constructing a file path or file content to write, STOP — return your JSON artifact as response text instead. The Foreman will handle validation and persistence.",
+    "Return your JSON artifact to the Foreman instead.",
+    "---",
+    "",
+    "## TERMINATION",
+    "",
+    "Once you have returned your JSON artifact, your job is complete.",
+    "Do NOT invoke other agents. Do NOT create files. Do NOT send follow-up messages.",
+    "The Foreman handles all routing after receiving your artifact.",
+    "",
+    "You are invoked ONE TIME by the Foreman with full context in this prompt.",
+    "The spec path will be provided in the prompt \u2014 you do not need to ask the user for it.",
     "",
     "---",
     "",