@hailer/mcp 0.0.4 → 0.0.6

package/.claude/skills/building-hailer-apps-skill/SKILL.md

@@ -7,6 +7,35 @@ description: Complete guide for building Hailer apps with the @hailer/app-sdk -
 
 Complete guide for building Hailer apps using the `@hailer/app-sdk` package. This skill covers critical patterns and gotchas that prevent data loading issues.
 
+---
+
+## ⚠️ CRITICAL FIRST STEP: Fix main.tsx with ChakraProvider
+
+**THE SCAFFOLD TEMPLATE IS MISSING ChakraProvider!** You MUST fix this FIRST or styles won't render:
+
+```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>,
+)
+```
+
+**Symptom if missing:** App renders with plain HTML, no styling, no colors, no layout.
+
+**Fix:** Wrap `<App />` with `<ChakraProvider>`.
+
+---
+
 ## ⚠️ CRITICAL: Hailer App SDK vs MCP API
 
 **IMPORTANT:** The Hailer App SDK (used in React/frontend apps) is DIFFERENT from the MCP API (used by Claude Code tools).
@@ -94,7 +123,133 @@ hailer.activity.list(
 
 ---
 
-## 2. Field Access - The Critical Issue
+## 2. Loading Workflow Schema (Field Definitions)
+
+### ⚠️ CRITICAL: No `hailer.process.getFields()` - Use `hailer.workflow.get()`
+
+The SDK does NOT have `hailer.process.getFields()`. This is a common mistake!
+
+### ✅ CORRECT: Load Schema with `hailer.workflow.get()`
+
+```typescript
+// Load workflow with all field definitions
+const workflow = await hailer.workflow.get(workflowId);
+
+// workflow.fields is an object keyed by field ID:
+// {
+//   "691ffdf84217e9e8434e5694": { label: "Player Name", type: "text", key: "playerName", ... },
+//   "691ffdf84217e9e8434e5695": { label: "Jersey Number", type: "numeric", key: "jerseyNumber", ... }
+// }
+
+// workflow.phases is an object with phase-specific field lists:
+// {
+//   "691ffdf84217e9e8434e569f": { name: "Active", fields: ["field1", "field2", ...] }
+// }
+```
+
+### Complete Schema Loading Pattern
+
+```typescript
+import { useState, useEffect, useCallback } from 'react';
+
+interface FieldSchema {
+  _id: string;
+  key?: string;
+  label: string;
+  type: string;
+  required?: boolean;
+  data?: string[];  // For dropdown options
+}
+
+function WorkflowView({ hailer, workflowId, phaseId }) {
+  const [schema, setSchema] = useState<FieldSchema[]>([]);
+
+  const loadSchema = useCallback(async () => {
+    try {
+      // ✅ CORRECT: Use hailer.workflow.get()
+      const workflowData = await hailer.workflow.get(workflowId);
+
+      if (workflowData?.fields) {
+        // Get field IDs for this phase, or all fields if phase not specified
+        const fieldIds = workflowData.phases?.[phaseId]?.fields
+          || Object.keys(workflowData.fields);
+
+        // Convert fields object to array
+        const fieldsArray = fieldIds.map((fieldId: string) => {
+          const field = workflowData.fields[fieldId];
+          return {
+            _id: fieldId,
+            key: field?.key,
+            label: field?.label || fieldId,
+            type: field?.type || 'text',
+            required: field?.required,
+            data: field?.data,  // Dropdown options
+          };
+        }).filter(f => f.label);
+
+        setSchema(fieldsArray);
+      }
+    } catch (err) {
+      console.error('Failed to load schema:', err);
+    }
+  }, [hailer, workflowId, phaseId]);
+
+  useEffect(() => {
+    loadSchema();
+  }, [loadSchema]);
+
+  // ... rest of component
+}
+```
+
+### ❌ WRONG: These Don't Exist
+
+```typescript
+// ❌ WRONG: hailer.process.getFields() doesn't exist!
+await hailer.process.getFields(workflowId, phaseId);
+
+// ❌ WRONG: hailer.workflow.getFields() doesn't exist!
+await hailer.workflow.getFields(workflowId);
+
+// ❌ WRONG: hailer.workflow.getSchema() doesn't exist!
+await hailer.workflow.getSchema(workflowId);
+```
+
+### SDK Workflow API Reference
+
+```typescript
+// Available workflow methods:
+hailer.workflow.list()                    // List all workflows
+hailer.workflow.get(workflowId: string)   // Get single workflow with fields
+
+// Workflow object structure:
+interface Workflow {
+  _id: string;
+  name: string;
+  fields: {
+    [fieldId: string]: {
+      _id: string;
+      label: string;
+      type: string;
+      key?: string;
+      required?: boolean;
+      data?: string[];  // For textpredefinedoptions
+    };
+  };
+  phases: {
+    [phaseId: string]: {
+      _id: string;
+      name: string;
+      fields?: string[];  // Field IDs visible in this phase
+    };
+  };
+  phasesOrder: string[];
+}
+```
+
+---
+
+## 3. Field Access - The Critical Issue
 
 ### Understanding Field Structure
 
@@ -186,7 +341,7 @@ function PlayerCard({ player }) {
 
 ---
 
-## 3. Complete Working Example
+## 4. Complete Working Example
 
 ### Full Component with Proper Data Loading
 
@@ -256,7 +411,7 @@ export default function PlayerList({ hailer }) {
 
 ---
 
-## 4. Common Field Types
+## 5. Common Field Types
 
 ### Field Type Reference
 
@@ -307,7 +462,7 @@ console.log(team?.name);
 
 ---
 
-## 5. Development Workflow
+## 6. Development Workflow
 
 ### Step-by-Step: Building a Hailer App Component
 
@@ -347,7 +502,7 @@ console.log(team?.name);
 
 ---
 
-## 6. Debugging Data Loading Issues
+## 7. Debugging Data Loading Issues
 
 ### Quick Diagnostics
 
@@ -383,13 +538,14 @@ async function loadPlayers() {
 | Issue | Symptom | Solution |
 |-------|---------|----------|
 | `Cannot read properties of undefined (reading 'activity')` | `hailer.api` doesn't exist | Use `hailer.activity`, NOT `hailer.api.activity` |
+| `hailer.process.getFields is not a function` | Method doesn't exist | Use `hailer.workflow.get(workflowId)` to get fields |
 | `"processId" must be a string` | Passing object instead of positional params | Use 3 positional params: `list(workflowId, phaseId, options)` |
 | Fields showing as `undefined` | Using readable keys like `fields.playerName` | Use field IDs: `fields['691ffdf...']` or `getFieldValue()` |
 | Empty data displayed | Data loads but doesn't render | Check field access - use correct field IDs |
 
 ---
 
-## 7. Loading Data from Multiple Phases
+## 8. Loading Data from Multiple Phases
 
 ```typescript
 async function loadAllPlayers() {
@@ -426,7 +582,116 @@ async function loadAllPlayers() {
 
 ---
 
-## 8. Best Practices
+## 8b. Loading Activity Counts for Sidebar Navigation
+
+When building a data manager app with a sidebar showing all workflows, you want to display activity counts immediately without requiring the user to click each workflow first.
+
+### ✅ CORRECT: Load counts on app initialization
+
+```typescript
+import { useState, useCallback, useEffect } from 'react';
+
+export default function App() {
+  const { hailer, inside } = useHailer();
+  const [activityCounts, setActivityCounts] = useState<Record<string, number>>({});
+  const [countsLoaded, setCountsLoaded] = useState(false);
+
+  // Load activity counts for all workflows on initial load
+  useEffect(() => {
+    if (!hailer || !inside || countsLoaded) return;
+
+    async function loadWorkflowCount(workflowId: string): Promise<[string, number]> {
+      try {
+        // Get workflow to find all phases
+        const workflowData = await hailer.workflow.get(workflowId);
+        if (!workflowData?.phases) return [workflowId, 0];
+
+        // Count activities across all phases in parallel
+        const phaseIds = Object.keys(workflowData.phases);
+        const phaseCounts = await Promise.all(
+          phaseIds.map(async (phaseId) => {
+            try {
+              const activities = await hailer.activity.list(workflowId, phaseId, { limit: 500 });
+              return activities?.length || 0;
+            } catch {
+              return 0;
+            }
+          })
+        );
+
+        const totalCount = phaseCounts.reduce((sum, count) => sum + count, 0);
+        return [workflowId, totalCount];
+      } catch {
+        return [workflowId, 0];
+      }
+    }
+
+    async function loadAllCounts() {
+      // Load all workflow counts in parallel
+      const workflows = Object.values(WORKFLOWS);
+      const results = await Promise.all(
+        workflows.map((workflow) => loadWorkflowCount(workflow.id))
+      );
+
+      const counts: Record<string, number> = {};
+      for (const [workflowId, count] of results) {
+        counts[workflowId] = count;
+      }
+
+      setActivityCounts(counts);
+      setCountsLoaded(true);
+    }
+
+    loadAllCounts();
+  }, [hailer, inside, countsLoaded]);
+
+  // ... rest of component
+}
+```
+
+### Sidebar Component with Counts
+
+```typescript
+interface SidebarProps {
+  selectedWorkflow: WorkflowKey | null;
+  onSelectWorkflow: (key: WorkflowKey) => void;
+  activityCounts: Record<string, number>;
+}
+
+export default function Sidebar({ selectedWorkflow, onSelectWorkflow, activityCounts }: SidebarProps) {
+  return (
+    <aside className="sidebar">
+      <nav className="sidebar-nav">
+        {Object.entries(WORKFLOWS).map(([key, workflow]) => (
+          <button
+            key={key}
+            className={`nav-item ${selectedWorkflow === key ? 'active' : ''}`}
+            onClick={() => onSelectWorkflow(key as WorkflowKey)}
+          >
+            <span className="nav-icon">{workflow.icon}</span>
+            <span className="nav-label">{workflow.name}</span>
+            {activityCounts[workflow.id] !== undefined && (
+              <span className="nav-count">{activityCounts[workflow.id]}</span>
+            )}
+          </button>
+        ))}
+      </nav>
+    </aside>
+  );
+}
+```
+
+### Key Points
+
+1. **Load on initialization** - Use `useEffect` to load counts when `hailer` and `inside` are ready
+2. **Parallel loading** - Use `Promise.all` to load all workflows simultaneously
+3. **Count all phases** - A workflow may have activities in multiple phases
+4. **Show in sidebar** - Display counts next to workflow names
+5. **Update on changes** - Optionally refresh counts when activities are created/updated
+
+---
+
+## 9. Best Practices
 
 ### ✅ DO
 
@@ -448,7 +713,7 @@ async function loadAllPlayers() {
 
 ---
 
-## 9. TypeScript Definitions
+## 10. TypeScript Definitions
 
 ```typescript
 // src/types.ts
@@ -502,7 +767,7 @@ export interface HailerClient {
 
 ---
 
-## 10. Testing Checklist
+## 11. Testing Checklist
 
 Before deploying your Hailer app:
 

package/.claude/skills/hailer-app-builder/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: Hailer App Builder
+description: TypeScript standards and clean code patterns for building Hailer apps - proper types, no any, error handling, and SDK patterns
+---
+
+# Hailer App Builder Agent
+
+Specialized agent for writing clean, type-safe code for Hailer apps. This agent is launched after scaffolding an app.
+
+## Agent Identity
+
+You are a **Hailer App Builder** - a specialized TypeScript developer focused on building Hailer apps with the @hailer/app-sdk.
+
+## TypeScript Standards (MANDATORY)
+
+### Type Safety Rules
+
+1. **Never use `any`** - Always define proper interfaces
+2. **Always type function parameters and returns**
+3. **Use generics where appropriate**
+4. **Prefer `unknown` over `any` when type is truly unknown**
+
+```typescript
+// ❌ WRONG
+const handleData = (data: any) => { ... }
+const [items, setItems] = useState<any[]>([]);
+
+// ✅ CORRECT
+interface Activity {
+  _id: string;
+  name: string;
+  fields: Record<string, unknown>;
+}
+const handleData = (data: Activity): void => { ... }
+const [items, setItems] = useState<Activity[]>([]);
+```
+
+### Interface Definitions
+
+Always define interfaces for:
+- API responses
+- Component props
+- State objects
+- Field schemas
+
+```typescript
+// Define interfaces at the top of the file or in a types.ts file
+interface WorkflowField {
+  _id: string;
+  label: string;
+  type: 'text' | 'numeric' | 'date' | 'textpredefinedoptions' | 'activitylink' | 'users';
+  key?: string;
+  data?: string[];
+  required?: boolean;
+}
+
+interface Workflow {
+  _id: string;
+  name: string;
+  fields: Record<string, WorkflowField>;
+  phases: Record<string, Phase>;
+}
+
+interface Phase {
+  name: string;
+  fields: string[];
+}
+
+interface Activity {
+  _id: string;
+  name: string;
+  fields: Record<string, FieldValue>;
+  created: number;
+  updated: number;
+}
+
+type FieldValue = string | number | string[] | null;
+```
+
+### Clean Code Practices
+
+1. **Small, focused functions** - Each function does one thing
+2. **Meaningful names** - Variables and functions describe their purpose
+3. **Early returns** - Avoid deep nesting
+4. **Const by default** - Only use let when reassignment is needed
+5. **Destructure props** - Makes dependencies clear
+
+```typescript
+// ❌ WRONG
+function doStuff(x: any) {
+  if (x) {
+    if (x.items) {
+      let result = [];
+      for (let i = 0; i < x.items.length; i++) {
+        result.push(x.items[i].name);
+      }
+      return result;
+    }
+  }
+  return [];
+}
+
+// ✅ CORRECT
+function extractActivityNames(response: { items?: Activity[] } | null): string[] {
+  if (!response?.items) {
+    return [];
+  }
+  return response.items.map(item => item.name);
+}
+```
+
+## Hailer SDK Patterns (CRITICAL)
+
+### Loading Workflow Schema
+
+```typescript
+// ✅ CORRECT - Use hailer.workflow.get()
+const loadSchema = async (workflowId: string): Promise<WorkflowField[]> => {
+  const workflow = await hailer.workflow.get(workflowId);
+
+  if (!workflow?.fields) {
+    throw new Error(`Workflow ${workflowId} not found`);
+  }
+
+  return Object.entries(workflow.fields).map(([id, field]) => ({
+    _id: id,
+    ...field
+  }));
+};
+
+// ❌ WRONG - These methods don't exist!
+// await hailer.process.getFields(workflowId, phaseId);
+// await hailer.workflow.getFields(workflowId);
+```
+
+### Loading Activities
+
+```typescript
+const loadActivities = async (
+  workflowId: string,
+  phaseId: string
+): Promise<Activity[]> => {
+  const response = await hailer.activity.list({
+    workflowId,
+    phaseId,
+    limit: 100
+  });
+
+  return response?.items ?? [];
+};
+```
+
+### Creating Activities
+
+```typescript
+interface CreateActivityParams {
+  workflowId: string;
+  name: string;
+  fields: Record<string, FieldValue>;
+  phaseId?: string;
+}
+
+const createActivity = async (params: CreateActivityParams): Promise<Activity> => {
+  const result = await hailer.activity.create(params);
+
+  if (!result?._id) {
+    throw new Error('Failed to create activity');
+  }
+
+  return result;
+};
+```
+
+### Updating Activities
+
+```typescript
+const updateActivity = async (
+  activityId: string,
+  updates: Partial<Activity>
+): Promise<Activity> => {
+  const result = await hailer.activity.update({
+    activityId,
+    ...updates
+  });
+
+  return result;
+};
+```
+
+## React Component Structure
+
+### Standard Component Template
+
+```typescript
+import React, { useState, useEffect, useCallback } from 'react';
+import { useHailer } from '@hailer/app-sdk';
+
+// Types
+interface Props {
+  workflowId: string;
+  phaseId: string;
+}
+
+interface Activity {
+  _id: string;
+  name: string;
+  fields: Record<string, unknown>;
+}
+
+// Component
+export const ActivityList: React.FC<Props> = ({ workflowId, phaseId }) => {
+  const hailer = useHailer();
+
+  // State with proper types
+  const [activities, setActivities] = useState<Activity[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // Memoized data loader
+  const loadData = useCallback(async () => {
+    try {
+      setLoading(true);
+      setError(null);
+
+      const response = await hailer.activity.list({
+        workflowId,
+        phaseId,
+        limit: 100
+      });
+
+      setActivities(response?.items ?? []);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Failed to load';
+      setError(message);
+    } finally {
+      setLoading(false);
+    }
+  }, [hailer, workflowId, phaseId]);
+
+  // Load on mount
+  useEffect(() => {
+    loadData();
+  }, [loadData]);
+
+  // Render states
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error}</div>;
+  if (activities.length === 0) return <div>No activities found</div>;
+
+  return (
+    <ul>
+      {activities.map(activity => (
+        <li key={activity._id}>{activity.name}</li>
+      ))}
+    </ul>
+  );
+};
+```
+
+## File Organization
+
+```
+src/
+├── types/
+│   ├── index.ts          # Re-exports all types
+│   ├── activity.ts       # Activity-related types
+│   ├── workflow.ts       # Workflow/field types
+│   └── api.ts            # API response types
+├── hooks/
+│   ├── useActivities.ts  # Activity loading hook
+│   ├── useWorkflow.ts    # Workflow schema hook
+│   └── useForm.ts        # Form state management
+├── components/
+│   ├── ActivityList.tsx
+│   ├── ActivityForm.tsx
+│   └── FieldRenderer.tsx
+├── utils/
+│   ├── formatters.ts     # Date, number formatting
+│   └── validators.ts     # Form validation
+└── App.tsx
+```
+
+## Error Handling Pattern
+
+```typescript
+class HailerAppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly details?: unknown
+  ) {
+    super(message);
+    this.name = 'HailerAppError';
+  }
+}
+
+const handleApiError = (error: unknown): never => {
+  if (error instanceof Error) {
+    throw new HailerAppError(
+      error.message,
+      'API_ERROR',
+      error
+    );
+  }
+  throw new HailerAppError(
+    'Unknown error occurred',
+    'UNKNOWN_ERROR',
+    error
+  );
+};
+```
+
+## Checklist Before Writing Code
+
+Before writing any component:
+
+1. [ ] Define all interfaces/types
+2. [ ] Identify which SDK methods needed (workflow.get, activity.list, etc.)
+3. [ ] Plan error handling
+4. [ ] Consider loading states
+5. [ ] Plan state management (local vs lifted)
+
+## Do NOT
+
+- ❌ Use `any` type
+- ❌ Use `hailer.process.getFields()` (doesn't exist)
+- ❌ Use `hailer.workflow.getFields()` (doesn't exist)
+- ❌ Skip error handling
+- ❌ Forget loading states
+- ❌ Use inline types for complex objects
+- ❌ Mix business logic with rendering
+
+## DO
+
+- ✅ Use `hailer.workflow.get(workflowId)` for schema
+- ✅ Define interfaces for all data structures
+- ✅ Handle loading/error/empty states
+- ✅ Use proper TypeScript generics
+- ✅ Keep components small and focused
+- ✅ Use early returns for cleaner code