@hailer/mcp 0.1.6 → 0.1.9

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>

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

@@ -0,0 +1,169 @@
+---
+name: publish-hailer-app
+description: Guide for publishing Hailer apps to production
+---
+
+# Publish Hailer App Skill
+
+Guide for publishing Hailer apps to production using MCP tools.
+
+<critical>
+## MANDATORY: Validate Before Publishing
+
+The `publish_hailer_app` tool will SILENTLY FAIL if manifest.json is misconfigured.
+
+**YOU MUST validate these before calling publish_hailer_app:**
+
+1. Read `public/manifest.json` in the project
+2. Check `appId` exists and is 24 characters
+3. Check `version` exists and is NOT empty (e.g., "1.0.0")
+4. Check `versionDescription` exists and is NOT empty
+
+If ANY are missing/empty, FIX THEM FIRST before publishing.
+</critical>
+
+<validation-code>
+## Validation Steps (DO THIS FIRST)
+
+```
+1. Read({file_path: "{projectDir}/public/manifest.json"})
+
+2. Verify JSON contains:
+   - "appId": "24-char-id"        ← If missing: use create_app first
+   - "version": "1.0.0"           ← If empty: set to "1.0.0"
+   - "versionDescription": "..."  ← If empty: set to "Initial release"
+
+3. If any field missing/empty → Edit manifest.json to fix
+
+4. ONLY THEN call publish_hailer_app
+```
+</validation-code>
+
+<workflow>
+## Full Publishing Workflow
+
+### Step 1: Check if Production App Exists
+
+```javascript
+list_apps()
+```
+Look for your app with a `https://apps.hailer.com/...` URL (NOT localhost).
+
+### Step 2: Create Production App (if needed)
+
+If app doesn't exist or only has localhost URL:
+```javascript
+create_app({
+  name: "My App Name",
+  description: "What the app does"
+})
+```
+Returns new appId with production URL.
+
+### Step 3: Validate & Fix manifest.json
+
+Read the manifest:
+```javascript
+Read({file_path: "{projectDir}/public/manifest.json"})
+```
+
+Required structure:
+```json
+{
+  "appId": "695816e2ba1d8bef3af7e018",
+  "version": "1.0.0",
+  "versionDescription": "Initial production release"
+}
+```
+
+**If appId missing:** Add the ID from Step 2
+**If version empty:** Set to "1.0.0"
+**If versionDescription empty:** Set to "Initial release"
+
+### Step 4: Publish
+
+```javascript
+publish_hailer_app({
+  projectDirectory: "/path/to/app"
+})
+```
+
+### Step 5: Verify
+
+```javascript
+list_apps()
+```
+Confirm URL is `https://apps.hailer.com/...` (not localhost).
+</workflow>
+
+<silent-failure>
+## Why Silent Failures Happen
+
+The SDK publish script requires `version` and `versionDescription` in manifest.json.
+If missing/empty, the tool returns "Success" but files are NOT uploaded.
+
+**Symptoms of silent failure:**
+- Tool says "App Published Successfully!"
+- But app URL is still `http://localhost:3000`
+- Or production URL returns 403/404
+
+**Always validate manifest BEFORE publishing.**
+</silent-failure>
+
+<dev-vs-prod>
+## Dev vs Production Apps
+
+| Type | URL | Created By | Can Publish To |
+|------|-----|------------|----------------|
+| Dev | `http://localhost:3000` | `scaffold_hailer_app` | NO - stays localhost |
+| Prod | `https://apps.hailer.com/...` | `create_app` | YES |
+
+**Key insight:** Dev apps (scaffolded) will ALWAYS use localhost.
+To deploy to production, create a NEW app with `create_app`.
+</dev-vs-prod>
+
+<updating>
+## Updating Published Apps
+
+1. Bump version in manifest.json:
+```json
+{
+  "version": "1.0.1",
+  "versionDescription": "Fixed data loading bug"
+}
+```
+
+2. Publish:
+```javascript
+publish_hailer_app({
+  projectDirectory: "/path/to/app"
+})
+```
+
+New version replaces old at same URL.
+</updating>
+
+<sharing>
+## Sharing Apps
+
+```javascript
+// Entire workspace
+add_app_member({ appId: "...", member: "network_{workspaceId}" })
+
+// Team
+add_app_member({ appId: "...", member: "team_{teamId}" })
+
+// User
+add_app_member({ appId: "...", member: "user_{userId}" })
+```
+</sharing>
+
+<checklist>
+## Pre-Publish Checklist
+
+- [ ] Production app exists (`create_app`, not scaffold)
+- [ ] manifest.json `appId` is 24 chars (not empty)
+- [ ] manifest.json `version` is set (e.g., "1.0.0")
+- [ ] manifest.json `versionDescription` is set (not empty)
+- [ ] node_modules exists (dependencies installed)
+</checklist>