@hailer/mcp 0.0.4 → 0.0.6

package/.claude/skills/MCP-scaffold-hailer-app-skill/SKILL.md

@@ -7,6 +7,61 @@ description: Complete guide to ONE-SHOT Hailer app creation - scaffolds project,
 
 Complete guide to using the `scaffold_hailer_app` tool - a ONE-SHOT solution that scaffolds your project, creates the dev app entry in Hailer, shares it with your workspace, updates manifest.json, and starts the dev server automatically.
 
+---
+
+## ⚠️ MANDATORY: SPAWN BUILDER AGENT AFTER SCAFFOLDING
+
+**THIS IS NOT OPTIONAL.** After `scaffold_hailer_app` completes successfully, you MUST:
+
+1. **IMMEDIATELY spawn the app builder agent** using the Task tool
+2. **DO NOT** start building components in the current session
+3. **DO NOT** skip this step
+
+### Why This Is Required
+
+- The builder agent has **isolated context** for focused work
+- It's **pre-loaded with TypeScript + SDK patterns**
+- Building in main session leads to **context overflow** and **mistakes**
+- The agent produces **higher quality code**
+
+### Exact Steps After Scaffold Succeeds
+
+```javascript
+// Step 1: Get workflow context (REQUIRED)
+list_workflows_minimal()
+
+// Step 2: Spawn the builder agent with Task tool
+Task({
+  subagent_type: "general-purpose",
+  description: "Build Hailer app components",
+  prompt: `You are building a Hailer app.
+
+PROJECT: <project-path>
+DESCRIPTION: <from scaffold description>
+WORKFLOWS: <paste list_workflows_minimal output>
+
+Load these skills FIRST:
+1. Skill("building-hailer-apps-skill")
+2. Skill("hailer-app-builder")
+
+Then build the app components following the patterns in those skills.
+
+Requirements:
+- Use Chakra UI for components
+- Follow TypeScript strict mode
+- Use hailer.activity.list(workflowId, phaseId, options) - 3 params
+- Access fields via activity.fields?.[fieldId]
+- Build full CRUD: list, create, edit, delete
+`
+})
+```
+
+### DO NOT PROCEED WITHOUT SPAWNING
+
+If you find yourself writing React components after scaffolding WITHOUT spawning an agent first, **STOP** and spawn the agent.
+
+---
+
 ## Table of Contents
 - [Quick Reference](#quick-reference)
 - [Overview](#overview)
@@ -583,6 +638,42 @@ npm run dev
 
 App is already created in Hailer, just needs server running.
 
+### Infinite Loop When Loading Data
+
+**Problem:** App keeps re-fetching data infinitely, causing performance issues.
+
+**Cause:** Using `hailer` object in useEffect dependencies. The `hailer` object from `useHailer()` changes reference on every render.
+
+**Solution:**
+```typescript
+// ❌ WRONG - causes infinite loop
+useEffect(() => {
+  if (!hailer) return;
+  hailer.activity.list(...);
+}, [hailer]); // hailer changes every render!
+
+// ✅ CORRECT - use `inside` and access hailer from window
+useEffect(() => {
+  if (!inside) return;
+  const hailer = (window as any).hailerApiInstance;
+  if (!hailer) return;
+  hailer.activity.list(...);
+}, [inside]); // inside is a stable boolean
+```
+
+### Chakra UI Table Not Showing Text
+
+**Problem:** Table rows render but text is invisible/white.
+
+**Cause:** CSS inheritance issues when running inside Hailer iframe.
+
+**Solution:** Add explicit `color="black"` to Td components:
+```typescript
+<Tr key={activity._id} bg="white">
+  <Td color="black">{value}</Td>
+</Tr>
+```
+
 ### CORS Error When Opening App in Hailer
 
 **Problem:** Browser console shows "Access to fetch at 'http://localhost:3000/manifest.json' from origin 'https://next.hailer.com' has been blocked by CORS policy"
@@ -682,10 +773,10 @@ const activities = await hailer.activity.list(
   options     // Third parameter: options object
 );
 
-// Example with real IDs
+// Example with generic IDs (replace with actual IDs from your workspace)
 const activities = await hailer.activity.list(
-  '69087299c0e0b9944c620172',  // Matches workflow
-  '69087299c0e0b9944c620173',  // Scheduled phase
+  workflowId,  // Get from list_workflows_minimal() or hailer.workflow.list()
+  phaseId,     // Get from hailer.workflow.get(workflowId).phases
   {
     sortBy: 'created',
     sortOrder: 'asc',
@@ -752,43 +843,56 @@ const competition = match.competition;  // undefined
 
 ### Complete Working Example
 
+**⚠️ CRITICAL: Do NOT use `hailer` in useEffect dependencies - it causes infinite loops!**
+
 ```typescript
-import { useEffect, useState } from 'react';
+import { useEffect, useState, useRef } from 'react';
 import useHailer from './hailer/use-hailer';
 
-interface Match {
+// Define your activity interface based on workflow fields
+interface Activity {
   _id: string;
   name: string;
   fields?: {
-    opponent?: { _id: string; name: string };
-    matchDate?: number;
-    competition?: string;
-    venue?: string;
+    [fieldId: string]: { type: string; value: unknown };  // Fields have type and value
   };
 }
 
-export default function MatchesList() {
+interface Props {
+  workflowId: string;
+  phaseId: string;
+}
+
+export default function ActivityList({ workflowId, phaseId }: Props) {
   const { hailer, inside } = useHailer();
-  const [matches, setMatches] = useState<Match[]>([]);
+  const [activities, setActivities] = useState<Activity[]>([]);
   const [loading, setLoading] = useState(true);
+  const loadedRef = useRef(false);
 
   useEffect(() => {
-    if (!hailer || !inside) return;
+    // ✅ Use `inside` as trigger - it's stable
+    if (!inside) return;
+    if (loadedRef.current) return;
 
-    async function fetchMatches() {
+    // ✅ Access hailer from window to avoid reference changes
+    const hailerApi = (window as any).hailerApiInstance;
+    if (!hailerApi) return;
+
+    async function fetchActivities() {
       try {
         // ✅ CORRECT: activity.list with separate parameters
-        const activities = await hailer.activity.list(
-          '69087299c0e0b9944c620172',  // processId
-          '69087299c0e0b9944c620173',  // phaseId
+        const result = await hailerApi.activity.list(
+          workflowId,
+          phaseId,
           {
             sortBy: 'created',
             sortOrder: 'asc',
-            limit: 20
+            limit: 50
           }
         );
 
-        setMatches(activities || []);
+        setActivities(result || []);
+        loadedRef.current = true;
       } catch (err) {
         console.error('Failed to fetch:', err);
       } finally {
@@ -796,19 +900,17 @@ export default function MatchesList() {
       }
     }
 
-    fetchMatches();
-  }, [hailer, inside]);
+    fetchActivities();
+  }, [inside, workflowId, phaseId]); // ✅ NO hailer in deps!
 
   if (loading) return <div>Loading...</div>;
 
   return (
     <div>
-      {matches.map((match) => (
-        <div key={match._id}>
-          {/* ✅ CORRECT: Access via fields */}
-          <h3>{match.fields?.opponent?.name || match.name}</h3>
-          <p>Competition: {match.fields?.competition}</p>
-          <p>Venue: {match.fields?.venue}</p>
+      {activities.map((activity) => (
+        <div key={activity._id}>
+          <h3>{activity.name}</h3>
+          {/* Access fields: activity.fields?.[fieldId]?.value */}
         </div>
       ))}
     </div>
@@ -846,14 +948,16 @@ await hailer.activity.update(
 await hailer.activity.remove(['activity-id-1', 'activity-id-2']);
 ```
 
-#### Workflow/Process Operations
+#### Workflow Operations
 
 ```typescript
-// Get workflow phases
-const phases = await hailer.process.getPhases(processId);
+// Get workflow with fields and phases
+const workflow = await hailer.workflow.get(workflowId);
+// workflow.fields = { fieldId: { label, type, key, ... } }
+// workflow.phases = { phaseId: { name, fields: [...] } }
 
-// Get workflow fields
-const fields = await hailer.process.getFields(processId, phaseId);
+// List all workflows
+const workflows = await hailer.workflow.list();
 ```
 
 #### User Operations
@@ -1007,28 +1111,204 @@ That's it! The one-shot approach eliminates all manual setup steps.
 
 ---
 
-## Next Steps: Building Your App
+## Next Steps: SPAWN THE BUILDER AGENT (MANDATORY)
 
-After scaffolding, you need to load data from Hailer workflows. **IMPORTANT:** The Hailer App SDK has specific patterns you must follow!
+**⚠️ DO NOT BUILD IN CURRENT SESSION.** After scaffolding completes:
 
-### ⚠️ Critical: Load the Building Hailer Apps Skill
+### Step 1: Get Workflow Context
 
-```typescript
-// Load comprehensive guide for data loading
-await get_skill({ skillName: "building-hailer-apps-skill" })
+```javascript
+list_workflows_minimal()
 ```
 
-**This skill covers:**
-- ✅ How to properly call `hailer.activity.list()` (3 positional params)
-- ✅ How field access works (fields are keyed by IDs, not readable keys)
-- ✅ How to use MCP tools to get workflow schema
-- ✅ Complete working examples with TypeScript
-- ✅ Common pitfalls and how to avoid them
-- ✅ Debugging techniques when data won't load
+### Step 2: Spawn the Builder Agent
+
+```javascript
+Task({
+  subagent_type: "general-purpose",
+  description: "Build Hailer app components",
+  prompt: `You are building a Hailer app.
+
+PROJECT PATH: /path/to/project
+DESCRIPTION: <description from scaffold>
+APP TYPE: Full CRUD application
+
+WORKFLOWS IN WORKSPACE:
+<paste list_workflows_minimal output here>
+
+## MANDATORY: Load Skills First
+
+Before writing ANY code, load these skills:
+1. Skill("building-hailer-apps-skill") - SDK API patterns
+2. Skill("hailer-app-builder") - TypeScript standards
+
+## ⚠️ CRITICAL FIRST STEP: Fix main.tsx
+
+**THE TEMPLATE IS MISSING ChakraProvider!** You MUST fix this FIRST or styles won't work:
+
+\`\`\`typescript
+// src/main.tsx - REPLACE the entire file with this:
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { ChakraProvider } from '@chakra-ui/react'
+import App from './App.tsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <ChakraProvider>
+      <App />
+    </ChakraProvider>
+  </React.StrictMode>,
+)
+\`\`\`
+
+**If you skip this, the app will render with NO STYLES!**
+
+## Data Loading Pattern (CRITICAL - PREVENTS INFINITE LOOPS)
+
+**⚠️ THE `hailer` OBJECT CHANGES ON EVERY RENDER!** Using `hailer` in useEffect dependencies causes infinite loops.
+
+Use `inside` boolean as the trigger and access hailer from window:
+
+\`\`\`typescript
+import { useState, useEffect, useRef } from 'react';
+
+// Hook takes `inside` boolean, NOT hailer object
+function useMyData(inside: boolean) {
+  const [data, setData] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [refreshTrigger, setRefreshTrigger] = useState(0);
+  const loadedRef = useRef(false);
+
+  useEffect(() => {
+    // Use `inside` as trigger - it's a stable boolean
+    if (!inside) return;
+    if (loadedRef.current && refreshTrigger === 0) return;
+
+    // Access hailer from window to avoid reference changes
+    const hailer = (window as any).hailerApiInstance;
+    if (!hailer) return;
+
+    async function loadData() {
+      try {
+        setLoading(true);
+        setError(null);
+
+        // 3 positional params: workflowId, phaseId, options
+        const result = await hailer.activity.list(
+          WORKFLOW_ID,
+          PHASE_ID,
+          { limit: 100 }
+        );
+
+        setData(result || []);
+        loadedRef.current = true;
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to load');
+      } finally {
+        setLoading(false);
+      }
+    }
+
+    loadData();
+  }, [inside, refreshTrigger]); // ✅ inside is stable, hailer is NOT
+
+  const refresh = () => {
+    loadedRef.current = false;
+    setRefreshTrigger(prev => prev + 1);
+  };
+
+  return { data, loading, error, refresh };
+}
+\`\`\`
+
+**In App.tsx, pass `inside` not `hailer`:**
+\`\`\`typescript
+export default function App() {
+  const { hailer, inside } = useHailer();
+  const { data, loading, error } = useMyData(inside); // ✅ Pass inside, not hailer
+
+  if (!hailer || !inside) {
+    return <Spinner />;
+  }
+  // ...
+}
+\`\`\`
+
+**KEY RULES:**
+1. ❌ NEVER use `hailer` in useEffect dependencies - causes infinite loops
+2. ✅ Use `inside` boolean as the stable trigger
+3. ✅ Access hailer via `(window as any).hailerApiInstance` inside useEffect
+4. ✅ Use `loadedRef` to prevent duplicate loads
+
+## Field Access Pattern
+
+Fields are keyed by FIELD IDs, not readable names:
+
+\`\`\`typescript
+// Get field IDs from get_workflow_schema() first!
+const FIELDS = {
+  PLAYER_NAME: '691ffdf84217e9e8434e5694',  // From schema
+  JERSEY_NUMBER: '691ffdf84217e9e8434e5695',
+};
+
+// Helper function
+function getFieldValue<T>(fields: Record<string, {value: unknown}> | undefined, fieldId: string): T | null {
+  return (fields?.[fieldId]?.value as T) ?? null;
+}
+
+// Usage
+const name = getFieldValue<string>(activity.fields, FIELDS.PLAYER_NAME);
+\`\`\`
+
+## Requirements
+
+Build a functional app with:
+- Dashboard showing overview stats
+- List view with data from workflows
+- Proper error handling and loading states
+- Styled with Chakra UI (AFTER fixing main.tsx!)
+
+## Technical Requirements
+
+- Fix main.tsx with ChakraProvider FIRST
+- Chakra UI components for all UI
+- TypeScript strict mode (no 'any')
+- hailer.activity.list(workflowId, phaseId, options) - 3 params
+- Access fields via getFieldValue helper with field IDs
+- Simple useEffect pattern (no useCallback/useRef for data loading)
+
+## Deliverables
+
+1. **FIRST**: Fix src/main.tsx with ChakraProvider
+2. Create src/constants.ts with workflow/field IDs
+3. Create src/hooks/ with data fetching hooks
+4. Create src/components/ with UI components
+5. Update src/App.tsx with the dashboard
+
+## Verification
+
+After building, the app should:
+1. Show styled UI (not plain HTML) - confirms ChakraProvider works
+2. Load data without infinite loops - confirms useEffect pattern works
+3. Display field values correctly - confirms field access works
+
+Report back what was created and confirm the 3 checks above pass.
+`
+})
+```
+
+### Why Spawn Is Required
+
+| Current Session | Spawned Agent |
+|-----------------|---------------|
+| Context gets cluttered | Clean, focused context |
+| May forget patterns | Skills pre-loaded |
+| Easier to make mistakes | Follows patterns strictly |
+| Can't see full picture | Dedicated to this task |
 
-**Why you need it:** The Hailer App SDK is different from the MCP API. Without this knowledge, you'll get errors like:
-- `Cannot read properties of undefined (reading 'activity')`
-- `"processId" must be a string`
-- Fields showing as `undefined` even though data loads
+### DO NOT Skip This Step
 
-**Load it before writing any data-loading code!**
+If you catch yourself writing components without spawning, **STOP** and spawn the agent first.