@stackwright-pro/otters 0.3.0-alpha.0 → 1.0.0-alpha.2

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@stackwright-pro/otters",
-  "version": "0.3.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "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": "^1.4.0",
+    "zod": "^3.22.4"
+  },
   "exports": {
     "./src": "./src",
     "./pro-foreman": "./src/stackwright-pro-foreman-otter.json"
@@ -16,10 +20,12 @@
     "src"
   ],
   "peerDependencies": {
-    "@stackwright-pro/mcp": "*"
+    "@stackwright-pro/mcp": "0.2.0-alpha.0"
   },
   "scripts": {
     "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/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,23 +23,23 @@ 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++;
       }
     }
 
     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');
     }
@@ -51,4 +49,4 @@ async function installAgents() {
   }
 }
 
-installAgents();
+installAgents();

package/src/question-adapter.ts

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

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

@@ -3,7 +3,13 @@
   "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"],
+  "tools": [
+    "agent_run_shell_command",
+    "list_files",
+    "cp_list_files",
+    "cp_read_file",
+    "invoke_agent"
+  ],
   "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,6 +33,67 @@
     "- Base URL: {url}",
     "",
     "## PASS TO DATA OTTER",
-    "After analysis, invoke pro-data-otter to wire collections."
+    "After analysis, invoke pro-data-otter to wire collections.",
+    "",
+    "---",
+    "",
+    "## QUESTION_COLLECTION_MODE",
+    "",
+    "When invoked with QUESTION_COLLECTION_MODE=true, return questions for the user INSTEAD of doing work.",
+    "",
+    "If the prompt contains \"QUESTION_COLLECTION_MODE=true\", respond ONLY with this JSON (no other text):",
+    "",
+    "**IMPORTANT**: Your response MUST include a `requiredPackages` field alongside the `questions` array. This tells the Foreman which npm packages this otter needs — it is how we do inversion of control for dependency management.",
+    "",
+    "{",
+    "  \"questions\": [",
+    "    {",
+    "      \"id\": \"api-1\",",
+    "      \"question\": \"Do you have an existing OpenAPI spec?\",",
+    "      \"type\": \"confirm\",",
+    "      \"required\": true,",
+    "      \"default\": \"no\"",
+    "    },",
+    "    {",
+    "      \"id\": \"api-2\",",
+    "      \"question\": \"What is the URL or path to your OpenAPI spec?\",",
+    "      \"type\": \"text\",",
+    "      \"required\": true,",
+    "      \"dependsOn\": { \"questionId\": \"api-1\", \"value\": \"yes\" }",
+    "    },",
+    "    {",
+    "      \"id\": \"api-3\",",
+    "      \"question\": \"What is your API authentication method?\",",
+    "      \"type\": \"select\",",
+    "      \"options\": [",
+    "        { \"label\": \"No auth\", \"value\": \"none\" },",
+    "        { \"label\": \"API Key\", \"value\": \"api-key\" },",
+    "        { \"label\": \"OAuth2\", \"value\": \"oauth2\" },",
+    "        { \"label\": \"OIDC/SAML\", \"value\": \"oidc\" },",
+    "        { \"label\": \"CAC/PIV (DoD)\", \"value\": \"cac\" }",
+    "      ],",
+    "      \"required\": true",
+    "    },",
+    "    {",
+    "      \"id\": \"api-4\",",
+    "      \"question\": \"Which entities from the spec do you need?\",",
+    "      \"type\": \"multi-select\",",
+    "      \"options\": [",
+    "        { \"label\": \"I will tell you after you parse it\", \"value\": \"discover\" }",
+    "      ],",
+    "      \"required\": false,",
+    "      \"help\": \"You can select specific entities or let me discover them after parsing the spec.\"",
+    "    }",
+    "  ],",
+    "  \"requiredPackages\": {",
+    "    \"dependencies\": {",
+    "      \"@stackwright-pro/openapi\": \"latest\",",
+    "      \"zod\": \"^3.23.0\"",
+    "    },",
+    "    \"devPackages\": {",
+    "      \"@stoplight/prism-cli\": \"^5.14.2\"",
+    "    }",
+    "  }",
+    "}"
   ]
 }

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

@@ -725,6 +725,79 @@
     "",
     "---",
     "",
-    "Ready to wire up some authentication? 🦦🔐"
+    "Ready to wire up some authentication? 🦦🔐",
+    "",
+    "---",
+    "",
+    "## QUESTION_COLLECTION_MODE",
+    "",
+    "When invoked with QUESTION_COLLECTION_MODE=true, return questions for the user INSTEAD of doing work.",
+    "",
+    "If the prompt contains \"QUESTION_COLLECTION_MODE=true\", respond ONLY with this JSON (no other text):",
+    "",
+    "**IMPORTANT**: Your response MUST include a `requiredPackages` field alongside the `questions` array. This tells the Foreman which npm packages this otter needs — this is the IoC pattern for dependency declaration.",
+    "",
+    "{",
+    "  \"questions\": [",
+    "    {",
+    "      \"id\": \"auth-1\",",
+    "      \"question\": \"Who needs to access this application?\",",
+    "      \"type\": \"select\",",
+    "      \"options\": [",
+    "        { \"label\": \"Everyone (public access)\", \"value\": \"public\" },",
+    "        { \"label\": \"Logged-in users only\", \"value\": \"authenticated\" },",
+    "        { \"label\": \"Government/military (CAC/PIV cards)\", \"value\": \"cac\" },",
+    "        { \"label\": \"Enterprise users (SSO)\", \"value\": \"oidc\" }",
+    "      ],",
+    "      \"required\": true",
+    "    },",
+    "    {",
+    "      \"id\": \"auth-2\",",
+    "      \"question\": \"What authentication provider do you use?\",",
+    "      \"type\": \"select\",",
+    "      \"options\": [",
+    "        { \"label\": \"Email/Password\", \"value\": \"email\" },",
+    "        { \"label\": \"Azure AD / Okta / Ping / Cognito\", \"value\": \"enterprise\" },",
+    "        { \"label\": \"DoD CAC/PIV (PKI)\", \"value\": \"cac\" }",
+    "      ],",
+    "      \"required\": false,",
+    "      \"dependsOn\": { \"questionId\": \"auth-1\", \"value\": [\"authenticated\", \"oidc\", \"cac\"] }",
+    "    },",
+    "    {",
+    "      \"id\": \"auth-3\",",
+    "      \"question\": \"Do you need role-based access control (RBAC)?\",",
+    "      \"type\": \"confirm\",",
+    "      \"required\": true,",
+    "      \"default\": \"yes\"",
+    "    },",
+    "    {",
+    "      \"id\": \"auth-4\",",
+    "      \"question\": \"Which roles do you need?\",",
+    "      \"type\": \"multi-select\",",
+    "      \"options\": [",
+    "        { \"label\": \"Admin (full access)\", \"value\": \"ADMIN\" },",
+    "        { \"label\": \"Analyst (read + export)\", \"value\": \"ANALYST\" },",
+    "        { \"label\": \"User (basic access)\", \"value\": \"USER\" }",
+    "      ],",
+    "      \"required\": false,",
+    "      \"dependsOn\": { \"questionId\": \"auth-3\", \"value\": \"yes\" }",
+    "    },",
+    "    {",
+    "      \"id\": \"auth-5\",",
+    "      \"question\": \"Do you need audit logging for compliance?\",",
+    "      \"type\": \"confirm\",",
+    "      \"required\": true,",
+    "      \"default\": \"yes\"",
+    "    }",
+    "  ],",
+    "  \"requiredPackages\": {",
+    "    \"dependencies\": {",
+    "      \"@stackwright-pro/auth\": \"latest\",",
+    "      \"@stackwright-pro/auth-nextjs\": \"latest\"",
+    "    },",
+    "    \"devPackages\": {",
+    "    }",
+    "  }",
+    "  }"
   ]
 }