@stackwright-pro/otters 1.0.0-alpha.11 → 1.0.0-alpha.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackwright-pro/otters",
-  "version": "1.0.0-alpha.11",
+  "version": "1.0.0-alpha.12",
   "description": "Stackwright Pro Otter Raft - AI agents for enterprise features (CAC auth, API dashboards, government use cases)",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@stackwright-pro/mcp": "^0.2.0-alpha.3"
+    "@stackwright-pro/mcp": "^0.2.0-alpha.4"
   },
   "scripts": {
     "generate-checksums": "node scripts/generate-checksums.js",

package/src/checksums.json

@@ -1,14 +1,14 @@
 {
   "version": "1.0",
   "algorithm": "sha256",
-  "generated": "2026-04-21T13:37:04.418Z",
+  "generated": "2026-04-21T15:16:26.700Z",
   "files": {
     "stackwright-pro-api-otter.json": "ad0c3694af41000420229edce4108f860eaa58ab321f8618565d03ebce80bcac",
-    "stackwright-pro-auth-otter.json": "e8e02ef1389e0d5e55bfa6d960a050ab976bf7960fda4ae805675020874ce4c6",
+    "stackwright-pro-auth-otter.json": "53da8d8fd7e922dfaec1f4c8f7a047c81f31fcfed48fd1414a8d4998dac9f826",
     "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-foreman-otter.json": "d6bf6b316c73d47c4a2c6136c46317eb0853b87189e63bb21e16f11ac4b908de",
     "stackwright-pro-page-otter.json": "0973f1b75a481fd177c5ada1a965f8c32e07f97fc28bbbf03b51d9e6d2af2f74",
     "stackwright-pro-theme-otter.json": "faa100f0530af75a64ae6e9d0ac8adb370542e5d980468e2d129223cb4aa85d7",
     "stackwright-pro-workflow-otter.json": "814305e9d170d28b7215ca63730b9fbeb7b9605113d2070cd5925cf92a9e30d3"

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

@@ -805,6 +805,7 @@
     "    },",
     "    \"devPackages\": {",
     "    }",
-    "  }"
+    "  }",
+    "}"
   ]
 }

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

@@ -24,7 +24,8 @@
     "stackwright_pro_configure_auth",
     "stackwright_pro_clarify",
     "stackwright_pro_detect_conflict",
-    "stackwright_pro_get_defaults"
+    "stackwright_pro_get_defaults",
+    "stackwright_pro_present_phase_questions"
   ],
   "user_prompt": "",
   "system_prompt": [
@@ -264,53 +265,35 @@
     "",
     "Show the user what packages will be added, then call the tool. Do NOT block on install failures — the user’s workflow should not be interrupted by package plumbing.",
     "",
-    "### Step 3: Adapt Questions for ask_user_question",
+    "### Step 3: Present Questions to User",
     "",
-    "**CRITICAL:** ask_user_question requires options for ALL questions. You MUST adapt:",
+    "For each phase, call `stackwright_pro_present_phase_questions` with the raw manifest questions.",
+    "The tool handles all adaptation (label truncation, header generation, confirm/text defaults).",
     "",
     "```",
-    "function adaptQuestion(q) {",
-    "  // Generate header from ID (max 12 chars)",
-    "  const parts = q.id.split('-');",
-    "  const prefix = parts[0].toUpperCase().substring(0, 3);",
-    "  const num = parts[1] || '';",
-    "  const header = (prefix + '-' + num).substring(0, 12);",
-    "  ",
-    "  // Determine multi_select",
-    "  const multiSelect = q.type === 'multi-select';",
-    "  ",
-    "  // Handle options - ALWAYS REQUIRED",
-    "  let options;",
-    "  if (q.options && q.options.length >= 2) {",
-    "    // Use provided options",
-    "    options = q.options.map(o => ({ label: o.label.substring(0, 50), description: o.value }));",
-    "    // IMPORTANT: The ask_user_question tool returns label text, not the original value.",
-    "    // Store the value in description so you can reverse-map it later.",
-    "    // When specialist otters receive answers, translate labels back to values:",
-    "    // e.g., user selected label 'Near real-time (minute-level freshness)' → value is in description → 'isr-fast'",
-    "  } else if (q.type === 'confirm') {",
-    "    // Generate Yes/No for confirm",
-    "    options = [",
-    "      { label: 'Yes', description: 'Enable or confirm' },",
-    "      { label: 'No', description: 'Disable or decline' }",
-    "    ];",
-    "  } else {",
-    "    // Generate defaults for text/select without options",
-    "    options = [",
-    "      { label: 'Specify', description: 'I will provide a value' },",
-    "      { label: 'Skip', description: 'Use default or skip' }",
-    "    ];",
-    "  }",
-    "  ",
-    "  return {",
-    "    question: q.question + (q.help ? '\\n\\n' + q.help : ''),",
-    "    header: header,",
-    "    multi_select: multiSelect,",
-    "    options: options.slice(0, 6)  // Max 6 options",
-    "  };",
-    "}",
+    "const result = await stackwright_pro_present_phase_questions({",
+    "  phase: phase.phase,",
+    "  questions: phase.questions,  // Pass verbatim from manifest \u2014 no adaptation needed",
+    "  answers: previousAnswers     // Optional: pass collected answers for dependsOn filtering",
+    "});",
+    "",
+    "// result.adapted_questions is a pre-validated array ready for ask_user_question",
+    "const response = await ask_user_question({",
+    "  questions: result.adapted_questions  // Native array \u2014 never stringify this",
+    "});",
     "```",
     "",
+    "\u26a0\ufe0f CRITICAL: Pass result.adapted_questions directly as the questions parameter.",
+    "Do NOT JSON.stringify() it. Do NOT rebuild it. Pass the value as-is.",
+    "",
+    "The tool guarantees:",
+    "- All labels truncated to \u226450 chars",
+    "- All headers truncated to \u226412 chars",
+    "- confirm type questions have Yes/No options",
+    "- text type questions have Specify/Skip options",
+    "- Options capped at 6",
+    "- dependsOn conditions resolved",
+    "",
     "### Step 4: Write Manifest",
     "",
     "```",
@@ -338,17 +321,15 @@
     "const manifest = JSON.parse(read_file('.stackwright/question-manifest.json'));",
     "",
     "for (const phase of manifest.phases) {",
-    "  // Adapt questions for this phase",
-    "  const adaptedQuestions = phase.questions.map(adaptQuestion);",
-    "  ",
-    "  if (adaptedQuestions.length === 0) {",
-    "    // No questions for this phase - skip",
-    "    continue;",
-    "  }",
-    "  ",
-    "  // Present to user",
+    "  const result = await stackwright_pro_present_phase_questions({",
+    "    phase: phase.phase,",
+    "    questions: phase.questions,  // Pass verbatim from manifest \u2014 no adaptation needed",
+    "    answers: previousAnswers     // Optional: pass collected answers for dependsOn filtering",
+    "  });",
+    "",
+    "  // result.adapted_questions is a pre-validated array ready for ask_user_question",
     "  const response = await ask_user_question({",
-    "    questions: adaptedQuestions",
+    "    questions: result.adapted_questions  // Native array \u2014 never stringify this",
     "  });",
     "  ",
     "  if (response.cancelled) {",

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;
-}