@stackwright-pro/otters 0.3.0-alpha.1 → 1.0.0-alpha.11

package/package.json

@@ -1,25 +1,37 @@
 {
   "name": "@stackwright-pro/otters",
-  "version": "0.3.0-alpha.1",
+  "version": "1.0.0-alpha.11",
   "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"
+    "./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": "*"
+    "@stackwright-pro/mcp": "^0.2.0-alpha.3"
   },
   "scripts": {
+    "generate-checksums": "node scripts/generate-checksums.js",
+    "verify-checksums": "node scripts/verify-checksums.js",
     "postinstall": "node scripts/install-agents.js",
-    "test": "echo 'Pro otters are configuration-only'"
+    "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

@@ -12,12 +12,10 @@ 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
+const packageRoot = path.resolve(scriptDir, '..');
 
 // All Pro otters are in the src/ directory
-const OTTERS_DIR = path.join(packageRoot, 'src');
+const srcDir = path.join(packageRoot, 'src');
 
 async function installAgents() {
   try {
@@ -25,29 +23,37 @@ async function installAgents() {
     await fs.promises.mkdir(AGENTS_DIR, { recursive: true });
 
     // Copy all JSON files from src/ to ~/.code_puppy/agents/
-    const files = await fs.promises.readdir(OTTERS_DIR);
+    const files = await fs.promises.readdir(srcDir);
 
     let installedCount = 0;
     for (const file of files) {
       if (file.endsWith('-otter.json')) {
-        const srcPath = path.join(OTTERS_DIR, file);
+        const srcPath = path.join(srcDir, file);
         const destPath = path.join(AGENTS_DIR, file);
 
         await fs.promises.copyFile(srcPath, destPath);
-        console.log(`✅ Installed Pro agent: ${file}`);
+        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}`);
-      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}`);
+    console.error(`❌  FATAL: Failed to install Pro otters: ${error.message}`);
+    process.exit(1);  // Fail the npm install — surface it early
   }
 }
 

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,16 @@
+{
+  "version": "1.0",
+  "algorithm": "sha256",
+  "generated": "2026-04-21T13:37:04.418Z",
+  "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": "2e4a13443a8c6bf55d02ab6c0301fa840f63f1df6baaebf14fab06a72d6cc8ca",
+    "stackwright-pro-page-otter.json": "0973f1b75a481fd177c5ada1a965f8c32e07f97fc28bbbf03b51d9e6d2af2f74",
+    "stackwright-pro-theme-otter.json": "faa100f0530af75a64ae6e9d0ac8adb370542e5d980468e2d129223cb4aa85d7",
+    "stackwright-pro-workflow-otter.json": "814305e9d170d28b7215ca63730b9fbeb7b9605113d2070cd5925cf92a9e30d3"
+  }
+}

package/src/python-bridge.ts

@@ -0,0 +1,391 @@
+/**
+ * Python Bridge - Spawns Python server and communicates via JSON over stdio
+ *
+ * This module provides the interface between Node.js CLI and the Python
+ * Clarification Protocol server.
+ *
+ * Architecture:
+ * - Node.js CLI spawns Python server (unix socket + HTTP)
+ * - Communication via JSON over stdio or HTTP
+ * - Supports both blocking (TUI) and non-blocking (API) modes
+ */
+
+import { spawn, ChildProcess, execSync } from 'child_process';
+import { existsSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+
+// Types
+export interface ClarificationRequest {
+  context: string;
+  question_type: 'closed_choice' | 'open_text' | 'conditional' | 'multi_step' | 'reconciliation';
+  question: string;
+  choices?: string[];
+  priority?: 'blocking' | 'preferred' | 'optional';
+  target_field?: string;
+  partial_result?: Record<string, unknown>;
+}
+
+export interface ClarificationResponse {
+  request_id: string;
+  decision: {
+    value: unknown;
+    explicit: boolean;
+    source: string;
+  };
+  fallback_used: boolean;
+  fallback_reason?: string;
+}
+
+export interface ConflictCheck {
+  stated_preference: string;
+  selected_values: Record<string, string>;
+}
+
+export interface ConflictResult {
+  conflict: boolean;
+  data?: {
+    description: string;
+    stated: string;
+    options: string[];
+  };
+}
+
+export interface SessionInfo {
+  id: string;
+  phase: string;
+  context: Record<string, unknown>;
+}
+
+// Constants
+const DEFAULT_SOCKET_PATH = join(tmpdir(), `otter-raft-${randomUUID()}.sock`);
+const DEFAULT_HTTP_PORT = 8765;
+
+/**
+ * PythonBridge - Communicates with Python Clarification Protocol server
+ */
+export class PythonBridge {
+  private socketPath: string;
+  private httpPort: number;
+  private pythonProcess: ChildProcess | null = null;
+  private useHttp: boolean;
+  private baseUrl: string;
+
+  constructor(options?: { socketPath?: string; httpPort?: number }) {
+    this.socketPath = options?.socketPath || DEFAULT_SOCKET_PATH;
+    this.httpPort = options?.httpPort || DEFAULT_HTTP_PORT;
+    this.useHttp = true; // Prefer HTTP for reliability
+    this.baseUrl = `http://127.0.0.1:${this.httpPort}`;
+  }
+
+  /**
+   * Start the Python server
+   */
+  async start(): Promise<void> {
+    // Find Python executable
+    const pythonPath = this.findPython();
+
+    // Find the Python package
+    const packageRoot = this.findPackageRoot();
+    const serverModule = 'stackwright_pro.raft.server';
+
+    return new Promise((resolve, reject) => {
+      // Clean up old socket
+      if (existsSync(this.socketPath)) {
+        try {
+          unlinkSync(this.socketPath);
+        } catch {
+          // Ignore
+        }
+      }
+
+      this.pythonProcess = spawn(
+        pythonPath,
+        ['-m', serverModule, '--socket', this.socketPath, '--port', String(this.httpPort)],
+        {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          env: {
+            ...process.env,
+            PYTHONPATH: packageRoot,
+          },
+        }
+      );
+
+      let startupOutput = '';
+
+      this.pythonProcess.stdout?.on('data', (data: Buffer) => {
+        startupOutput += data.toString();
+        // Look for "Server ready" message
+        if (startupOutput.includes('Server ready') || startupOutput.includes('Starting')) {
+          // Give it a moment to fully start
+          setTimeout(() => resolve(), 500);
+        }
+      });
+
+      this.pythonProcess.stderr?.on('data', (data: Buffer) => {
+        console.error('[Python]', data.toString().trim());
+      });
+
+      this.pythonProcess.on('error', (err) => {
+        reject(new Error(`Failed to start Python server: ${err.message}`));
+      });
+
+      this.pythonProcess.on('exit', (code) => {
+        if (code !== 0 && code !== null) {
+          reject(new Error(`Python server exited with code ${code}`));
+        }
+      });
+
+      // Timeout after 10 seconds
+      setTimeout(() => {
+        reject(new Error('Python server startup timeout'));
+      }, 10000);
+    });
+  }
+
+  /**
+   * Stop the Python server
+   */
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.pythonProcess) {
+        this.pythonProcess.on('exit', () => resolve());
+        this.pythonProcess.kill('SIGTERM');
+
+        // Force kill after 5 seconds
+        setTimeout(() => {
+          if (this.pythonProcess) {
+            this.pythonProcess.kill('SIGKILL');
+          }
+          resolve();
+        }, 5000);
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  /**
+   * Health check
+   */
+  async health(): Promise<{ status: string; version: string }> {
+    return this.httpRequest('/health');
+  }
+
+  /**
+   * Create a new clarification session
+   */
+  async createSession(): Promise<{ session_id: string }> {
+    return this.httpRequest('/sessions', {
+      method: 'POST',
+    });
+  }
+
+  /**
+   * Get session info
+   */
+  async getSession(sessionId: string): Promise<SessionInfo> {
+    return this.httpRequest(`/sessions/${sessionId}`);
+  }
+
+  /**
+   * Set session phase
+   */
+  async setPhase(sessionId: string, phase: string): Promise<{ phase: string }> {
+    return this.httpRequest(`/sessions/${sessionId}/phase`, {
+      method: 'POST',
+      body: { phase },
+    });
+  }
+
+  /**
+   * Update session context
+   */
+  async updateContext(
+    sessionId: string,
+    context: Record<string, unknown>
+  ): Promise<{ context: Record<string, unknown> }> {
+    return this.httpRequest(`/sessions/${sessionId}/context`, {
+      method: 'POST',
+      body: { context },
+    });
+  }
+
+  /**
+   * Ask for clarification within a session
+   */
+  async sessionClarify(
+    sessionId: string,
+    request: ClarificationRequest
+  ): Promise<ClarificationResponse> {
+    return this.httpRequest(`/sessions/${sessionId}/clarify`, {
+      method: 'POST',
+      body: { request },
+    });
+  }
+
+  /**
+   * Quick clarify (no session)
+   */
+  async clarify(request: ClarificationRequest): Promise<ClarificationResponse> {
+    return this.httpRequest('/clarify', {
+      method: 'POST',
+      body: { request },
+    });
+  }
+
+  /**
+   * Detect preference conflict
+   */
+  async detectConflict(check: ConflictCheck): Promise<ConflictResult> {
+    return this.httpRequest('/conflict', {
+      method: 'POST',
+      body: check,
+    });
+  }
+
+  // --------------------------------------------------------------------------
+  // Private methods
+  // --------------------------------------------------------------------------
+
+  private findPython(): string {
+    // Try python3 first, fall back to python
+    try {
+      execSync('python3 --version', { stdio: 'pipe' });
+      return 'python3';
+    } catch {
+      return 'python';
+    }
+  }
+
+  private findPackageRoot(): string {
+    // Look for the Python package in common locations
+    const candidates = [
+      join(__dirname, '../../python/src'),
+      join(__dirname, '../../../python/src'),
+      join(process.cwd(), 'python/src'),
+    ];
+
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+
+    // Default to current directory
+    return process.cwd();
+  }
+
+  private async httpRequest<T>(
+    path: string,
+    options?: {
+      method?: string;
+      body?: unknown;
+    }
+  ): Promise<T> {
+    const http = await import('http');
+
+    return new Promise((resolve, reject) => {
+      const url = new URL(path, this.baseUrl);
+
+      const reqOptions = {
+        hostname: url.hostname,
+        port: url.port,
+        path: url.pathname,
+        method: options?.method || 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      };
+
+      const req = http.request(reqOptions, (res) => {
+        let data = '';
+
+        res.on('data', (chunk: Buffer) => {
+          data += chunk.toString();
+        });
+
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(data);
+
+            if (res.statusCode && res.statusCode >= 400) {
+              reject(new Error(parsed.detail || parsed.error || `HTTP ${res.statusCode}`));
+            } else {
+              resolve(parsed);
+            }
+          } catch (e) {
+            reject(new Error(`Failed to parse response: ${data}`));
+          }
+        });
+      });
+
+      req.on('error', (e) => {
+        reject(new Error(`HTTP request failed: ${e.message}`));
+      });
+
+      if (options?.body) {
+        req.write(JSON.stringify(options.body));
+      }
+
+      req.end();
+    });
+  }
+}
+
+/**
+ * Create a bridge instance and auto-start it
+ */
+export async function createBridge(options?: {
+  socketPath?: string;
+  httpPort?: number;
+}): Promise<PythonBridge> {
+  const bridge = new PythonBridge(options);
+  await bridge.start();
+  return bridge;
+}
+
+/**
+ * Run a single clarification in stdio mode (no server)
+ *
+ * Usage:
+ *   echo '{"type":"clarify","request":{...}}' | python -m stackwright_pro.raft.server --stdio
+ */
+export async function runStdioClarify(
+  request: ClarificationRequest
+): Promise<ClarificationResponse> {
+  const http = await import('http');
+
+  // For stdio mode, we communicate directly via stdin/stdout
+  // This is handled by the Python server in --stdio mode
+  return new Promise((resolve, reject) => {
+    const input = JSON.stringify({
+      type: 'clarify',
+      request,
+    });
+
+    const proc = spawn('python', ['-m', 'stackwright_pro.raft.server', '--stdio'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let output = '';
+
+    proc.stdout?.on('data', (data: Buffer) => {
+      output += data.toString();
+    });
+
+    proc.on('close', () => {
+      try {
+        resolve(JSON.parse(output));
+      } catch {
+        reject(new Error(`Failed to parse response: ${output}`));
+      }
+    });
+
+    proc.on('error', reject);
+
+    proc.stdin?.write(input);
+    proc.stdin?.end();
+  });
+}