@hailer/mcp 0.0.5 → 0.1.0

package/.claude/skills/MCP-build-data-app-skill/SKILL.md

@@ -1,372 +0,0 @@
-# Build Data App Skill
-
-Complete guide for building Hailer data visualization and management apps based on workspace workflows.
-
-> **Important:** For comprehensive SDK API documentation, load `building-hailer-apps-skill` which covers all SDK patterns, field access, and common pitfalls in detail.
-
-## When to Use This Skill
-
-Use this skill when:
-- Building apps to visualize workspace data
-- Creating data management dashboards
-- Building CRUD interfaces for workflows
-- User says "build me an app", "visualize data", "create dashboard"
-
-## Prerequisites
-
-Before building, you need:
-1. **Scaffolded app** - Use `scaffold_hailer_app` first
-2. **Workspace info** - Run `list_workflows_minimal()` to see available data
-3. **Requirements** - App type, features, and workflow selection
-
-## The Build Flow
-
-### Step 0: Discovery (Auto)
-
-```javascript
-// Always run this first to understand the workspace
-list_workflows_minimal()
-```
-
-Shows:
-- All workflows (like database tables)
-- Activity counts (row counts)
-- Workflow IDs for API calls
-
-### Step 1: Gather Requirements
-
-Use AskUserQuestion to collect:
-
-| Question | Options | Purpose |
-|----------|---------|---------|
-| App Type | Dashboard / Full Manager / Specific Workflows | Determines layout |
-| Features | View / Edit / Create | Determines UI components |
-| Workflows | All or specific selection | Determines data scope |
-| App Name | Project folder name | Used for scaffolding |
-
-### Step 2: Scaffold
-
-```javascript
-scaffold_hailer_app({
-  projectName: "<app-name>",
-  template: "react-ts",
-  description: "<generated from requirements>"
-})
-```
-
-### Step 3: Build Components
-
-Based on requirements, create appropriate React components.
-
-## App Architecture Patterns
-
-### Dashboard Overview
-
-**Layout:** Grid of cards showing workflow stats
-
-```
-+------------------+------------------+------------------+
-|   Players (31)   |   Matches (15)   |   Teams (15)    |
-|   View Details   |   View Details   |   View Details  |
-+------------------+------------------+------------------+
-|   Injuries (9)   |  Training (17)   |   Stats (8)     |
-|   View Details   |   View Details   |   View Details  |
-+------------------+------------------+------------------+
-```
-
-**Components needed:**
-- `WorkflowCard` - Shows workflow name, count, link
-- `Dashboard` - Grid layout of cards
-- `useWorkflows` - Hook to fetch workflow list
-
-### Full Data Manager
-
-**Layout:** Sidebar navigation + main content area
-
-```
-+----------+----------------------------------------+
-| Players  |  [Search]  [Filter]  [+ New Activity] |
-| Matches  +----------------------------------------+
-| Teams    |  Name         Status      Date        |
-| Training |  Player 1     Active      2024-01-15  |
-| Stats    |  Player 2     Injured     2024-01-10  |
-| ...      |  Player 3     Active      2024-01-08  |
-+----------+----------------------------------------+
-```
-
-**Components needed:**
-- `Sidebar` - Workflow navigation
-- `ActivityList` - Table/list of activities
-- `ActivityRow` - Individual activity display
-- `SearchFilter` - Search and filter controls
-- `ActivityForm` - Create/Edit form (if features include Edit/Create)
-
-### Specific Workflow Focus
-
-**Layout:** Tabs or focused views for selected workflows
-
-```
-+--------------------------------------------------+
-|  [Players]  [Contracts]  [Stats]  [Injuries]     |
-+--------------------------------------------------+
-|  Player Details View with Related Data           |
-|  - Contract info                                 |
-|  - Stats history                                 |
-|  - Injury records                                |
-+--------------------------------------------------+
-```
-
-**Components needed:**
-- `TabNav` - Tab navigation between workflows
-- `WorkflowView` - Main view for each workflow
-- `RelatedData` - Shows linked activities
-
-## Hailer SDK API Patterns
-
-### CRITICAL: Correct API Usage
-
-```typescript
-// CORRECT - Use hailer.activity (singular)
-const activities = await hailer.activity.list(
-  processId,  // Workflow ID
-  phaseId,    // Phase ID
-  options     // { sortBy, sortOrder, limit, filters }
-);
-
-// WRONG - This will fail
-const activities = await hailer.activities.list({...})  // undefined!
-```
-
-### Fetching Activities
-
-```typescript
-import useHailer from './hailer/use-hailer';
-
-export function useActivities(workflowId: string, phaseId: string) {
-  const { hailer, inside } = useHailer();
-  const [activities, setActivities] = useState([]);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    if (!hailer || !inside) return;
-
-    async function fetch() {
-      try {
-        const data = await hailer.activity.list(
-          workflowId,
-          phaseId,
-          { sortBy: 'updated', sortOrder: 'desc', limit: 50 }
-        );
-        setActivities(data || []);
-      } catch (err) {
-        console.error('Failed to fetch:', err);
-      } finally {
-        setLoading(false);
-      }
-    }
-
-    fetch();
-  }, [hailer, inside, workflowId, phaseId]);
-
-  return { activities, loading };
-}
-```
-
-### Accessing Custom Fields
-
-```typescript
-// Fields are in activity.fields object, NOT directly on activity
-interface Activity {
-  _id: string;
-  name: string;
-  fields?: {
-    [fieldKey: string]: any;
-  };
-}
-
-// CORRECT
-const playerName = activity.fields?.playerName;
-const status = activity.fields?.status;
-
-// WRONG - These are undefined
-const playerName = activity.playerName;  // undefined!
-```
-
-### Creating Activities
-
-```typescript
-async function createActivity(workflowId: string, data: any) {
-  const created = await hailer.activity.create(
-    workflowId,
-    [{ name: data.name, fields: data.fields }]
-  );
-  return created[0];
-}
-```
-
-### Updating Activities
-
-```typescript
-async function updateActivity(activityId: string, updates: any) {
-  await hailer.activity.update(
-    [{ _id: activityId, ...updates }],
-    {}
-  );
-}
-```
-
-## Feature Implementation
-
-### View Only
-
-Components:
-- Activity list with sorting
-- Search/filter
-- Click to view details (read-only)
-
-### View + Edit
-
-Additional components:
-- Edit button on each row
-- Edit form/modal
-- Save/Cancel buttons
-- Optimistic updates
-
-### View + Edit + Create
-
-Additional components:
-- "New Activity" button
-- Create form/modal
-- Validation
-- Success/error feedback
-
-## Getting Workflow Metadata
-
-### Option 1: From SDK (in React components)
-
-```typescript
-// Use hailer.workflow.get() - NOT hailer.process.getFields()!
-const workflow = await hailer.workflow.get(workflowId);
-
-// workflow.fields = { fieldId: { label, type, key, data, required } }
-// workflow.phases = { phaseId: { name, fields: [...] } }
-
-// Extract field schema as array
-const fieldIds = workflow.phases?.[phaseId]?.fields || Object.keys(workflow.fields);
-const schema = fieldIds.map(id => ({
-  _id: id,
-  ...workflow.fields[id]
-}));
-```
-
-### Option 2: From MCP Tools (before building)
-
-```javascript
-// Get phases for a workflow
-list_workflow_phases({ workflowId: "xxx" })
-
-// Get field schema
-get_workflow_schema({ workflowId: "xxx", phaseId: "yyy" })
-```
-
-This tells you:
-- Available phases (like statuses)
-- Field types (text, numeric, date, dropdown, etc.)
-- Field keys for API access
-
-### ⚠️ Common Mistake
-
-```typescript
-// ❌ WRONG - These methods don't exist!
-await hailer.process.getFields(workflowId, phaseId);
-await hailer.workflow.getFields(workflowId);
-
-// ✅ CORRECT
-const workflow = await hailer.workflow.get(workflowId);
-const fields = workflow.fields;
-```
-
-## Example: Complete Dashboard Component
-
-```typescript
-import { useEffect, useState } from 'react';
-import useHailer from './hailer/use-hailer';
-
-interface WorkflowSummary {
-  id: string;
-  name: string;
-  count: number;
-}
-
-export default function Dashboard() {
-  const { hailer, inside } = useHailer();
-  const [workflows, setWorkflows] = useState<WorkflowSummary[]>([]);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    if (!hailer || !inside) return;
-
-    async function fetchWorkflows() {
-      try {
-        // Get workspace workflows
-        const ws = await hailer.workspace.get();
-        const summaries: WorkflowSummary[] = [];
-
-        for (const [id, workflow] of Object.entries(ws.processes || {})) {
-          summaries.push({
-            id,
-            name: workflow.name,
-            count: workflow.activityCount || 0
-          });
-        }
-
-        setWorkflows(summaries);
-      } catch (err) {
-        console.error('Failed to load:', err);
-      } finally {
-        setLoading(false);
-      }
-    }
-
-    fetchWorkflows();
-  }, [hailer, inside]);
-
-  if (loading) return <div>Loading...</div>;
-
-  return (
-    <div className="dashboard">
-      <h1>Workspace Overview</h1>
-      <div className="workflow-grid">
-        {workflows.map(wf => (
-          <div key={wf.id} className="workflow-card">
-            <h3>{wf.name}</h3>
-            <p>{wf.count} activities</p>
-            <button onClick={() => navigate(`/workflow/${wf.id}`)}>
-              View Details
-            </button>
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-}
-```
-
-## Related Skills
-
-- **building-hailer-apps-skill** - Comprehensive app SDK guide
-- **scaffold-hailer-app-skill** - One-shot app scaffolding
-- **hailer-api** - Complete API reference
-
-## Checklist
-
-Before considering the app complete:
-
-- [ ] App scaffolded and running
-- [ ] All required workflows accessible
-- [ ] View functionality working
-- [ ] Edit functionality working (if required)
-- [ ] Create functionality working (if required)
-- [ ] Error handling in place
-- [ ] Loading states shown
-- [ ] Responsive layout