@stackwright-pro/otters 1.0.0-alpha.4 → 1.0.0-alpha.43

package/src/python-bridge.ts

@@ -1,391 +0,0 @@
-/**
- * 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();
-  });
-}

package/src/question-adapter.ts

@@ -1,296 +0,0 @@
-/**
- * Question Adapter - Converts between Question Manifest format and ask_user_question format
- *
- * The ask_user_question MCP tool requires:
- *   - question: string (full text)
- *   - header: string (max 12 chars, short label)
- *   - multi_select: boolean
- *   - options: {label, description}[] (REQUIRED, min 2)
- *
- * Our Question Manifest format has:
- *   - id: string (e.g., "api-1")
- *   - question: string
- *   - type: 'text' | 'select' | 'multi-select' | 'confirm'
- *   - options?: {label, value}[]  (optional for text/confirm)
- *   - required?: boolean
- *   - default?: string | boolean | string[]
- *   - dependsOn?: {questionId, value}
- */
-
-export interface QuestionManifestQuestion {
-  id: string;
-  question: string;
-  type: 'text' | 'select' | 'multi-select' | 'confirm';
-  required?: boolean;
-  options?: { label: string; value: string }[];
-  default?: string | boolean | string[];
-  help?: string;
-  dependsOn?: {
-    questionId: string;
-    value: string | string[];
-  };
-}
-
-export interface AskUserQuestionOption {
-  label: string;
-  description?: string;
-}
-
-export interface AskUserQuestion {
-  question: string;
-  header: string;
-  multi_select: boolean;
-  options: AskUserQuestionOption[];
-}
-
-/**
- * Truncate string to max length, adding ellipsis if needed
- */
-function truncate(str: string, maxLength: number): string {
-  if (str.length <= maxLength) return str;
-  return str.substring(0, maxLength - 1) + '…';
-}
-
-/**
- * Generate a valid header from a question ID
- * Headers must be max 12 chars, alphanumeric with hyphens
- */
-function generateHeader(id: string): string {
-  // Remove numbers and prefix, keep meaningful part
-  // e.g., "api-1" -> "API-1", "auth-3" -> "AUTH-3"
-  const parts = id.split('-');
-  if (parts.length >= 2) {
-    const prefix = parts[0].toUpperCase().substring(0, 4);
-    const num = parts[1];
-    return truncate(`${prefix}-${num}`, 12);
-  }
-  return truncate(
-    id
-      .toUpperCase()
-      .replace(/[^A-Z0-9]/g, '')
-      .substring(0, 12),
-    12
-  );
-}
-
-/**
- * Generate default options for question types that don't have options
- */
-function generateDefaultOptions(type: string): AskUserQuestionOption[] {
-  switch (type) {
-    case 'confirm':
-      return [
-        { label: 'Yes', description: 'Enable or confirm this option' },
-        { label: 'No', description: 'Disable or decline this option' },
-      ];
-    case 'text':
-      return [
-        { label: 'Specify', description: 'I will provide a specific value' },
-        { label: 'Skip', description: 'Use default or skip this question' },
-      ];
-    default:
-      return [
-        { label: 'Option 1', description: 'First option' },
-        { label: 'Option 2', description: 'Second option' },
-      ];
-  }
-}
-
-/**
- * Convert a single QuestionManifest question to ask_user_question format
- */
-export function adaptQuestion(q: QuestionManifestQuestion): AskUserQuestion {
-  // Generate header from ID
-  const header = generateHeader(q.id);
-
-  // Determine multi_select
-  const multiSelect = q.type === 'multi-select';
-
-  // Handle options - use provided or generate defaults
-  let options: AskUserQuestionOption[];
-
-  if (q.options && q.options.length >= 2) {
-    // Use provided options, adapt format
-    options = q.options.map((opt) => ({
-      label: truncate(opt.label, 50),
-      description: opt.value !== opt.label ? opt.value : undefined,
-    }));
-  } else if (q.options && q.options.length === 1) {
-    // Single option - add a default
-    options = [
-      ...q.options.map((opt) => ({ label: truncate(opt.label, 50), description: opt.value })),
-      { label: 'Other', description: 'Specify a different value' },
-    ];
-  } else {
-    // No options - generate defaults based on type
-    options = generateDefaultOptions(q.type);
-  }
-
-  // Ensure minimum 2 options (MCP tool requirement)
-  if (options.length < 2) {
-    options.push({ label: 'Other', description: 'Alternative option' });
-  }
-
-  // Limit to 6 options (MCP tool max)
-  options = options.slice(0, 6);
-
-  return {
-    question: q.question + (q.help ? `\n\n${q.help}` : ''),
-    header,
-    multi_select: multiSelect,
-    options,
-  };
-}
-
-/**
- * Adapt multiple questions, filtering by dependsOn
- *
- * @param questions - All questions from manifest
- * @param answers - Previously answered questions (for filtering conditionals)
- * @returns Questions adapted for ask_user_question, with conditionals resolved
- */
-export function adaptQuestions(
-  questions: QuestionManifestQuestion[],
-  answers: Record<string, string | string[] | boolean> = {}
-): AskUserQuestion[] {
-  const adapted: AskUserQuestion[] = [];
-
-  for (const q of questions) {
-    // Check dependsOn condition
-    if (q.dependsOn) {
-      const dependsAnswer = answers[q.dependsOn.questionId];
-      if (dependsAnswer === undefined) {
-        // Parent question not answered yet - skip this conditional question
-        continue;
-      }
-
-      // Check if the answer matches the condition
-      const expectedValues = Array.isArray(q.dependsOn.value)
-        ? q.dependsOn.value
-        : [q.dependsOn.value];
-
-      const answerValue = Array.isArray(dependsAnswer) ? dependsAnswer[0] : dependsAnswer;
-
-      if (!expectedValues.includes(answerValue as string)) {
-        // Condition not met - skip this question
-        continue;
-      }
-    }
-
-    adapted.push(adaptQuestion(q));
-  }
-
-  return adapted;
-}
-
-/**
- * Parse JSON response from LLM (handles various formats)
- */
-export function parseLLMQuestionsResponse(text: string): QuestionManifestQuestion[] {
-  // Try to extract JSON from the response
-  let jsonStr = text;
-
-  // Remove markdown code blocks
-  jsonStr = jsonStr.replace(/```(?:json|javascript)?\s*/gi, '');
-  jsonStr = jsonStr.replace(/```\s*$/gm, '');
-
-  // Find JSON object or array
-  const firstBrace = jsonStr.indexOf('{');
-  const firstBracket = jsonStr.indexOf('[');
-
-  let start = -1;
-  if (firstBrace !== -1 && firstBracket !== -1) {
-    start = Math.min(firstBrace, firstBracket);
-  } else if (firstBrace !== -1) {
-    start = firstBrace;
-  } else if (firstBracket !== -1) {
-    start = firstBracket;
-  }
-
-  if (start === -1) {
-    throw new Error('No JSON found in response');
-  }
-
-  jsonStr = jsonStr.substring(start);
-
-  // Handle trailing text after JSON
-  const lastBrace = jsonStr.lastIndexOf('}');
-  const lastBracket = jsonStr.lastIndexOf(']');
-  const end = Math.max(lastBrace, lastBracket);
-
-  if (end === -1) {
-    throw new Error('Invalid JSON structure');
-  }
-
-  jsonStr = jsonStr.substring(0, end + 1);
-
-  // Fix common issues
-  jsonStr = jsonStr.replace(/,(\s*[}\]])/g, '$1'); // Remove trailing commas
-  jsonStr = jsonStr.replace(/'/g, '"'); // Single quotes to double
-
-  const parsed = JSON.parse(jsonStr);
-
-  // Handle various JSON structures
-  let questions: unknown[];
-
-  if (Array.isArray(parsed)) {
-    questions = parsed;
-  } else if (parsed.questions && Array.isArray(parsed.questions)) {
-    questions = parsed.questions;
-  } else if (parsed.data && Array.isArray((parsed.data as Record<string, unknown>).questions)) {
-    questions = (parsed.data as Record<string, unknown>).questions as unknown[];
-  } else {
-    throw new Error('No questions array found in response');
-  }
-
-  return questions as QuestionManifestQuestion[];
-}
-
-/**
- * Convert ask_user_question answers back to manifest format
- */
-export function answersToManifestFormat(
-  answers: { question_header: string; selected_options: string[]; other_text?: string | null }[],
-  questions: QuestionManifestQuestion[]
-): Record<string, string | string[] | boolean> {
-  const result: Record<string, string | string[] | boolean> = {};
-
-  for (const answer of answers) {
-    // Find matching question by header
-    const headerLower = answer.question_header.toLowerCase();
-    const question = questions.find((q) => {
-      const qHeader = generateHeader(q.id).toLowerCase();
-      return qHeader === headerLower || q.id.toLowerCase().includes(headerLower);
-    });
-
-    if (!question) {
-      // Try to match by header prefix
-      const matched = questions.find((q) => {
-        const qHeader = generateHeader(q.id).toLowerCase();
-        return qHeader.startsWith(headerLower.split('-')[0]);
-      });
-      if (matched) {
-        result[matched.id] = answer.selected_options[0] || '';
-      }
-      continue;
-    }
-
-    // Handle multi-select vs single select
-    if (question.type === 'multi-select' || answer.selected_options.length > 1) {
-      result[question.id] = answer.selected_options;
-    } else if (question.type === 'confirm') {
-      result[question.id] = answer.selected_options[0] === 'Yes';
-    } else {
-      // For text or single select, use first option or other_text
-      if (answer.other_text) {
-        result[question.id] = answer.other_text;
-      } else if (answer.selected_options.length > 0) {
-        // Map label back to value if possible
-        const option = question.options?.find((o) => o.label === answer.selected_options[0]);
-        result[question.id] = option?.value ?? answer.selected_options[0];
-      }
-    }
-  }
-
-  return result;
-}