@hailer/mcp 0.0.5 → 0.1.0

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

@@ -1,340 +0,0 @@
----
-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