@hailer/mcp 0.1.8 → 0.1.9

package/.claude/agents/agent-dmitri-activity-crud.md

@@ -25,7 +25,9 @@ Load `hailer-api` for field type reference.
 2. **STRING for activitylink/dropdown** - Never arrays.
 3. **Timestamps for dates** - Unix ms, not strings.
 4. **Orchestrator provides IDs** - I don't fetch schema.
-5. **JSON ONLY** - Output closing brace, then STOP. Zero prose after JSON.
+5. **BULK: `_id` not `activityId`** - In activities array, use `_id` key.
+6. **OMIT unused params** - Don't pass empty `[]` or `""`, just omit.
+7. **JSON ONLY** - Output closing brace, then STOP. Zero prose after JSON.
 </rules>
 
 <field-types>

package/.claude/agents/agent-giuseppe-app-builder.md

@@ -14,27 +14,26 @@ Orchestrator MUST provide: Workflow ID(s), Phase ID(s), Field IDs + types.
 If missing: STOP and request.
 </pre-flight>
 
-<skills>
-Load `hailer-app-builder` for full templates and patterns.
-</skills>
-
 <execution>
+**STEP 0 - MANDATORY:** Read `.claude/skills/hailer-app-builder/SKILL.md` FIRST. This contains critical patterns. Do NOT skip.
+
 1. Enable: node .claude/hooks/app-edit-guard.cjs --agent-on
 2. Scaffold: scaffold_hailer_app({ projectName, template: "react-ts-style" })
 3. Create: src/types/index.ts, src/utils/fields.ts, src/constants/fields.ts
-4. Modify: src/App.tsx (NEVER main.tsx)
+4. Modify: src/App.tsx (NEVER main.tsx) - FOLLOW SKILL PATTERNS EXACTLY
 5. BUILD LOOP: npm run build → fix → repeat until pass
 6. Disable: node .claude/hooks/app-edit-guard.cjs --agent-off
 </execution>
 
 <rules>
-1. **NEVER FABRICATE** - Must call tools.
-2. **Import**: `import useHailer from './hailer/use-hailer'` (local, default!)
-3. **useEffect dep**: `[inside]` NEVER `[hailer]` (infinite loop)
-4. **Hooks at TOP**: Before any early returns.
-5. **Fields optional**: `fields?: Record<string, { value: unknown }>`
-6. **Theme**: `useColorModeValue('white', 'gray.700')` - no fake tokens.
-7. **JSON ONLY** - Output closing brace, then STOP. Zero prose after JSON.
+1. **READ SKILL FIRST** - Use Read tool on `.claude/skills/hailer-app-builder/SKILL.md` before ANY code. No exceptions.
+2. **NEVER FABRICATE** - Must call tools.
+3. **Import**: `import useHailer from './hailer/use-hailer'` (local, default!)
+4. **useEffect dep**: `[inside]` ONLY. NEVER include `hailer` or `config` (causes infinite loops)
+5. **Hooks at TOP**: Before any early returns.
+6. **Fields optional**: `fields?: Record<string, { value: unknown }>`
+7. **Theme**: `useColorModeValue('white', 'gray.700')` - no fake tokens.
+8. **JSON ONLY** - Output closing brace, then STOP. Zero prose after JSON.
 </rules>
 
 <sdk-api>

package/.claude/agents/agent-kenji-data-reader.md

@@ -2,7 +2,7 @@
 name: agent-kenji-data-reader
 description: LOCAL-FIRST data retrieval for SDK v0.8.4 - reads workspace/ before API. Knows about workflows, fields, phases, templates, functions, teams, groups, and insights.\n\n<example>\nuser: "What fields does Tasks have?"\nassistant: {"status":"success","result":{"fields":["taskName","project","dueDate"]},"source":"local","summary":"Read fields.ts"}\n</example>
 model: haiku
-tools: Read, Glob, mcp__hailer__list_workflows_minimal, mcp__hailer__count_activities, mcp__hailer__list_activities, mcp__hailer__list_workflow_phases
+tools: Read, Glob, mcp__hailer__list_workflows_minimal, mcp__hailer__count_activities, mcp__hailer__list_activities, mcp__hailer__list_workflow_phases, mcp__hailer__get_workflow_schema
 ---
 
 <identity>
@@ -28,7 +28,8 @@ Load `json-only-output` to avoid prose after JSON responses.
 <rules>
 1. **NEVER FABRICATE** - Must call tools.
 2. **LOCAL FIRST** - Check workspace/ before API.
-3. **JSON ONLY** - Output closing brace, then STOP. Zero prose after JSON.
+3. **VERIFY FIELD IDS** - If local files missing/stale, use get_workflow_schema to confirm field IDs before passing to other agents.
+4. **JSON ONLY** - Output closing brace, then STOP. Zero prose after JSON.
 </rules>
 
 <local-paths>
@@ -48,7 +49,7 @@ workspace/[Workflow]_[id]/main.test.ts → function field tests
 </local-paths>
 
 <decision-tree>
-Field schema? → Read workspace/[workflow]/fields.ts
+Field schema? → Read workspace/[workflow]/fields.ts → IF MISSING: get_workflow_schema (API)
 Phase names? → Read workspace/[workflow]/phases.ts
 Workflow list? → Read workspace/workflows.ts
 Workflow settings? → Read workspace/[workflow]/main.ts
@@ -63,6 +64,7 @@ Workflow counts? → list_workflows_minimal (API)
 Phase IDs for API? → list_workflow_phases (API)
 Activity data? → list_activities (API)
 Activity counts? → count_activities (API)
+Field IDs (no local)? → get_workflow_schema (API)
 </decision-tree>
 
 <protocol>

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

@@ -0,0 +1,506 @@
+---
+name: hailer-app-builder
+description: Patterns for building Hailer apps with @hailer/app-sdk
+---
+
+# Hailer App Builder Skill
+
+Patterns and templates for building Hailer apps with @hailer/app-sdk.
+
+<sdk-setup>
+## Hook Import (CRITICAL)
+
+```typescript
+// CORRECT - local default import
+import useHailer from './hailer/use-hailer';
+
+// WRONG - will fail build
+import { useHailer } from '@hailer/app-sdk';
+```
+
+## Hook Usage
+
+```typescript
+function App() {
+  const { inside, hailer } = useHailer();
+
+  // CORRECT dependency array
+  useEffect(() => {
+    // fetch data
+  }, [inside]);  // Use [inside] NOT [hailer]
+
+  // Early return AFTER hooks
+  if (!inside) return <Text>Open this app inside Hailer</Text>;
+
+  return <Box>...</Box>;
+}
+```
+</sdk-setup>
+
+<sdk-api>
+## Activity API
+
+```typescript
+// List activities from workflow phase
+const activities = await hailer.activity.list(workflowId, phaseId, {
+  limit: 100,
+  fields: ['fieldId1', 'fieldId2'],  // Optional: specific fields only
+});
+
+// Get single activity
+const activity = await hailer.activity.get(activityId);
+
+// Activity structure
+interface Activity {
+  _id: string;
+  name: string;
+  fields?: Record<string, { value: unknown }>;
+  created?: number;
+  updated?: number;
+}
+```
+
+## Insight API
+
+```typescript
+// Get insight data (SQL query results)
+const data = await hailer.insight.get(insightId, { update: true });
+
+// Response structure
+interface InsightResponse {
+  columns: string[];
+  rows: any[][];
+}
+```
+
+## Workflow API
+
+```typescript
+// List all workflows
+const workflows = await hailer.workflow.list();
+
+// Get single workflow
+const workflow = await hailer.workflow.get(workflowId);
+```
+</sdk-api>
+
+<field-patterns>
+## Extracting Field Values
+
+```typescript
+// Fields are optional and nested
+interface Activity {
+  fields?: Record<string, { value: unknown }>;
+}
+
+// Safe extraction helper
+function getFieldValue<T>(activity: Activity, fieldId: string, defaultValue: T): T {
+  return (activity.fields?.[fieldId]?.value as T) ?? defaultValue;
+}
+
+// Usage
+const name = getFieldValue(activity, 'fieldId123', '');
+const count = getFieldValue(activity, 'fieldId456', 0);
+const date = getFieldValue(activity, 'fieldId789', null);
+```
+
+## Field Types
+
+```typescript
+// Text field
+const text = activity.fields?.['fieldId']?.value as string;
+
+// Number field
+const num = activity.fields?.['fieldId']?.value as number;
+
+// Date field (timestamp)
+const date = activity.fields?.['fieldId']?.value as number;
+const formatted = new Date(date).toLocaleDateString();
+
+// Enum/Select field
+const status = activity.fields?.['fieldId']?.value as string;
+
+// ActivityLink field (reference to another activity)
+interface ActivityLinkValue {
+  _id: string;
+  name: string;
+}
+const linked = activity.fields?.['fieldId']?.value as ActivityLinkValue;
+const linkedName = linked?.name || 'Unknown';
+
+// User field
+interface UserValue {
+  _id: string;
+  firstname: string;
+  lastname: string;
+}
+const user = activity.fields?.['fieldId']?.value as UserValue;
+const userName = user ? `${user.firstname} ${user.lastname}` : 'Unknown';
+```
+</field-patterns>
+
+<component-templates>
+## Activity Table
+
+```typescript
+import { Table, Thead, Tbody, Tr, Th, Td, Box, Spinner, Text } from '@chakra-ui/react';
+
+interface Activity {
+  _id: string;
+  name: string;
+  fields?: Record<string, { value: unknown }>;
+}
+
+interface Props {
+  activities: Activity[];
+  loading: boolean;
+  columns: { fieldId: string; label: string }[];
+}
+
+function ActivityTable({ activities, loading, columns }: Props) {
+  if (loading) return <Spinner />;
+  if (activities.length === 0) return <Text>No data</Text>;
+
+  return (
+    <Table variant="simple" size="sm">
+      <Thead>
+        <Tr>
+          <Th>Name</Th>
+          {columns.map(col => (
+            <Th key={col.fieldId}>{col.label}</Th>
+          ))}
+        </Tr>
+      </Thead>
+      <Tbody>
+        {activities.map(activity => (
+          <Tr key={activity._id}>
+            <Td>{activity.name}</Td>
+            {columns.map(col => (
+              <Td key={col.fieldId}>
+                {String(activity.fields?.[col.fieldId]?.value ?? '-')}
+              </Td>
+            ))}
+          </Tr>
+        ))}
+      </Tbody>
+    </Table>
+  );
+}
+```
+
+## Activity Card
+
+```typescript
+import { Box, Heading, Text, VStack, useColorModeValue } from '@chakra-ui/react';
+
+interface Props {
+  activity: Activity;
+  fieldId: string;
+  fieldLabel: string;
+}
+
+function ActivityCard({ activity, fieldId, fieldLabel }: Props) {
+  const bg = useColorModeValue('white', 'gray.700');
+  const borderColor = useColorModeValue('gray.200', 'gray.600');
+
+  return (
+    <Box
+      p={4}
+      bg={bg}
+      borderRadius="md"
+      border="1px"
+      borderColor={borderColor}
+    >
+      <VStack align="start" spacing={2}>
+        <Heading size="sm">{activity.name}</Heading>
+        <Text fontSize="sm" color="gray.500">
+          {fieldLabel}: {String(activity.fields?.[fieldId]?.value ?? '-')}
+        </Text>
+      </VStack>
+    </Box>
+  );
+}
+```
+
+## Stats Card
+
+```typescript
+import { Stat, StatLabel, StatNumber, StatHelpText, Box, useColorModeValue } from '@chakra-ui/react';
+
+interface Props {
+  label: string;
+  value: number | string;
+  helpText?: string;
+}
+
+function StatsCard({ label, value, helpText }: Props) {
+  const bg = useColorModeValue('white', 'gray.700');
+
+  return (
+    <Box p={4} bg={bg} borderRadius="md" shadow="sm">
+      <Stat>
+        <StatLabel>{label}</StatLabel>
+        <StatNumber>{value}</StatNumber>
+        {helpText && <StatHelpText>{helpText}</StatHelpText>}
+      </Stat>
+    </Box>
+  );
+}
+```
+</component-templates>
+
+<app-template>
+## Full App Template
+
+```typescript
+import { useEffect, useState } from 'react';
+import {
+  Box,
+  Heading,
+  Text,
+  Spinner,
+  Table,
+  Thead,
+  Tbody,
+  Tr,
+  Th,
+  Td,
+  VStack,
+  useColorModeValue,
+} from '@chakra-ui/react';
+import useHailer from './hailer/use-hailer';
+
+// Field IDs from workflow schema (provided by orchestrator)
+const FIELDS = {
+  NAME_FIELD: 'fieldId123',
+  STATUS_FIELD: 'fieldId456',
+} as const;
+
+interface Activity {
+  _id: string;
+  name: string;
+  fields?: Record<string, { value: unknown }>;
+}
+
+function App() {
+  const { inside, hailer } = useHailer();
+  const [activities, setActivities] = useState<Activity[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const bg = useColorModeValue('gray.50', 'gray.800');
+
+  // Fetch data when inside Hailer
+  useEffect(() => {
+    if (!inside) return;
+
+    async function fetchData() {
+      try {
+        setLoading(true);
+        const data = await hailer.activity.list(
+          'workflowId',  // Replace with actual workflow ID
+          'phaseId',      // Replace with actual phase ID
+          { limit: 100 }
+        );
+        setActivities(data);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to load data');
+      } finally {
+        setLoading(false);
+      }
+    }
+
+    fetchData();
+  }, [inside]);  // IMPORTANT: [inside] not [hailer]
+
+  // Early return AFTER hooks
+  if (!inside) {
+    return (
+      <Box p={8} textAlign="center">
+        <Text>Please open this app inside Hailer</Text>
+      </Box>
+    );
+  }
+
+  if (loading) {
+    return (
+      <Box p={8} textAlign="center">
+        <Spinner size="xl" />
+      </Box>
+    );
+  }
+
+  if (error) {
+    return (
+      <Box p={8} textAlign="center">
+        <Text color="red.500">{error}</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box p={4} bg={bg} minH="100vh">
+      <VStack spacing={4} align="stretch">
+        <Heading size="lg">Dashboard</Heading>
+
+        <Table variant="simple" size="sm">
+          <Thead>
+            <Tr>
+              <Th>Name</Th>
+              <Th>Status</Th>
+            </Tr>
+          </Thead>
+          <Tbody>
+            {activities.map(activity => (
+              <Tr key={activity._id}>
+                <Td>{activity.name}</Td>
+                <Td>{String(activity.fields?.[FIELDS.STATUS_FIELD]?.value ?? '-')}</Td>
+              </Tr>
+            ))}
+          </Tbody>
+        </Table>
+      </VStack>
+    </Box>
+  );
+}
+
+export default App;
+```
+</app-template>
+
+<theme-patterns>
+## Hailer Theme Colors
+
+```typescript
+// Dark mode support
+const bg = useColorModeValue('white', 'gray.700');
+const borderColor = useColorModeValue('gray.200', 'gray.600');
+const textColor = useColorModeValue('gray.800', 'white');
+const mutedColor = useColorModeValue('gray.500', 'gray.400');
+
+// Valid color tokens (DO NOT invent tokens)
+// gray.50, gray.100, ..., gray.900
+// white, black
+// red.500, green.500, blue.500, yellow.500, purple.500
+```
+
+## Common UI Patterns
+
+```typescript
+// Page container
+<Box p={4} bg={useColorModeValue('gray.50', 'gray.800')} minH="100vh">
+
+// Card
+<Box p={4} bg={useColorModeValue('white', 'gray.700')} borderRadius="md" shadow="sm">
+
+// Section with border
+<Box p={4} border="1px" borderColor={useColorModeValue('gray.200', 'gray.600')} borderRadius="md">
+```
+</theme-patterns>
+
+<build-fixes>
+## Common Build Errors
+
+### Cannot find module '@hailer/app-sdk'
+```typescript
+// WRONG
+import { useHailer } from '@hailer/app-sdk';
+
+// CORRECT
+import useHailer from './hailer/use-hailer';
+```
+
+### has no exported member 'useHailer'
+```typescript
+// WRONG - named import
+import { useHailer } from './hailer/use-hailer';
+
+// CORRECT - default import
+import useHailer from './hailer/use-hailer';
+```
+
+### fields possibly undefined
+```typescript
+// WRONG
+const value = activity.fields[fieldId].value;
+
+// CORRECT
+const value = activity.fields?.[fieldId]?.value;
+```
+
+### Infinite re-render loop
+```typescript
+// WRONG - hailer changes every render
+useEffect(() => { ... }, [hailer]);
+
+// CORRECT - inside is stable
+useEffect(() => { ... }, [inside]);
+```
+
+### Hooks order error
+```typescript
+// WRONG - early return before hook
+if (!inside) return <Text>Error</Text>;
+const [data, setData] = useState([]);  // Error!
+
+// CORRECT - hooks first, then early return
+const [data, setData] = useState([]);
+if (!inside) return <Text>Error</Text>;
+```
+</build-fixes>
+
+<file-structure>
+## Required Files
+
+```
+src/
+  App.tsx           # Main component (EDIT THIS)
+  main.tsx          # Entry point (NEVER EDIT)
+  hailer/
+    use-hailer.ts   # SDK hook (generated)
+  types/
+    index.ts        # Type definitions (CREATE)
+  utils/
+    fields.ts       # Field helpers (CREATE)
+  constants/
+    fields.ts       # Field ID constants (CREATE)
+```
+
+## Constants File Pattern
+
+```typescript
+// src/constants/fields.ts
+export const WORKFLOW_ID = 'workflowId123';
+export const PHASE_ID = 'phaseId456';
+
+export const FIELDS = {
+  NAME: 'fieldId001',
+  STATUS: 'fieldId002',
+  DATE: 'fieldId003',
+} as const;
+```
+
+## Types File Pattern
+
+```typescript
+// src/types/index.ts
+export interface Activity {
+  _id: string;
+  name: string;
+  fields?: Record<string, { value: unknown }>;
+  created?: number;
+  updated?: number;
+}
+
+export interface ActivityLinkValue {
+  _id: string;
+  name: string;
+}
+
+export interface UserValue {
+  _id: string;
+  firstname: string;
+  lastname: string;
+}
+```
+</file-structure>