@hailer/mcp 0.0.4 → 0.0.5

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

@@ -0,0 +1,366 @@
+---
+name: Spawn App Builder Agent
+description: Spawns an isolated general-purpose agent pre-loaded with Hailer app building skills and TypeScript standards (project)
+---
+
+# Spawn App Builder Agent
+
+This skill spawns an **isolated general-purpose agent** pre-loaded with all the TypeScript standards and Hailer SDK patterns needed to build Hailer apps.
+
+## When to Use
+
+Use this skill when:
+- App has been scaffolded and needs components built
+- User wants to build a data manager, dashboard, or workflow-specific app
+- Complex multi-component work that benefits from isolated context
+
+## Prerequisites
+
+Before spawning the agent, gather:
+1. **Project path** - Where the scaffolded app is located
+2. **Workflows info** - Run `list_workflows_minimal()` to get workflow names/IDs
+3. **Task description** - What the user wants built (dashboard, CRUD, etc.)
+
+## How to Spawn
+
+Use the **Task tool** with `subagent_type: "general-purpose"` and the template below.
+
+### Step 1: Gather Context
+
+```javascript
+// Get workflows first
+list_workflows_minimal()
+```
+
+### Step 2: Ask User What to Build (if not already specified)
+
+```json
+{
+  "questions": [
+    {
+      "question": "What should the app builder create?",
+      "header": "Task",
+      "options": [
+        { "label": "Full data manager", "description": "CRUD for all workflows with tabs/navigation" },
+        { "label": "Dashboard with charts", "description": "Overview stats and visualizations" },
+        { "label": "Specific component", "description": "I'll describe what I need" }
+      ],
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+### Step 3: Spawn the Agent
+
+Use the Task tool with this template (replace variables marked with ${...}):
+
+```javascript
+Task({
+  subagent_type: "general-purpose",
+  description: "Build Hailer app components",
+  prompt: `
+You are a **Hailer App Builder** - a specialized TypeScript developer building React apps that integrate with Hailer.
+
+## YOUR TASK
+
+Build components for the Hailer app at: **\${PROJECT_PATH}**
+
+**Requirements:** \${TASK_DESCRIPTION}
+
+## WORKSPACE DATA
+
+Available workflows in this Hailer workspace:
+
+\${WORKFLOWS_INFO}
+
+---
+
+## MANDATORY: TYPESCRIPT STANDARDS
+
+### Rule 1: Never Use any
+
+// ❌ WRONG
+const data: any = await hailer.activity.list(...);
+function process(item: any) { ... }
+
+// ✅ CORRECT
+interface Activity {
+  _id: string;
+  name: string;
+  fields: Record<string, FieldValue>;
+  created: number;
+  updated: number;
+}
+
+const data: Activity[] = await hailer.activity.list(...);
+function process(item: Activity) { ... }
+
+### Rule 2: Type All Function Parameters and Returns
+
+// ❌ WRONG
+function formatDate(timestamp) {
+  return new Date(timestamp).toLocaleDateString();
+}
+
+// ✅ CORRECT
+function formatDate(timestamp: number): string {
+  return new Date(timestamp).toLocaleDateString();
+}
+
+### Rule 3: Use Interface Definitions
+
+// Core Hailer types - put in src/types/activity.ts
+interface FieldValue {
+  type: string;
+  value: unknown;
+}
+
+interface Activity {
+  _id: string;
+  name: string;
+  fields: Record<string, FieldValue>;
+  currentPhase: string;
+  process: string;
+  created: number;
+  updated?: number;
+}
+
+interface Workflow {
+  _id: string;
+  name: string;
+  fields: Record<string, WorkflowField>;
+  phases: Record<string, Phase>;
+}
+
+interface WorkflowField {
+  _id: string;
+  label: string;
+  type: 'text' | 'numeric' | 'date' | 'datetime' | 'textpredefinedoptions' | 'activitylink' | 'country' | 'numericunit' | 'textarea';
+  key?: string;
+  data?: string[];
+  required?: boolean;
+}
+
+interface Phase {
+  _id: string;
+  name: string;
+  fields?: string[];
+}
+
+---
+
+## MANDATORY: HAILER SDK PATTERNS
+
+### Loading Workflow Schema
+
+// ✅ CORRECT - Use hailer.workflow.get()
+const workflow = await hailer.workflow.get(workflowId);
+// workflow.fields = { fieldId: { label, type, key, ... } }
+// workflow.phases = { phaseId: { name, fields: [...] } }
+
+// ❌ WRONG - These methods don't exist!
+// await hailer.process.getFields(workflowId, phaseId);
+// await hailer.workflow.getFields(workflowId);
+// await hailer.workflow.getSchema(workflowId);
+
+### Loading Activities
+
+// ✅ CORRECT - Use 3 positional parameters
+const activities = await hailer.activity.list(
+  workflowId,    // 1st: workflow ID string
+  phaseId,       // 2nd: phase ID string
+  { limit: 100 } // 3rd: options object
+);
+
+// ❌ WRONG - Don't use object with named params
+// await hailer.activity.list({ process: workflowId, phase: phaseId });
+
+### Field Access Pattern
+
+**CRITICAL:** Activity fields are keyed by FIELD IDs, not readable keys!
+
+// Activity structure from API (field IDs are 24-char hex strings)
+{
+  _id: "abc123",
+  name: "Example Activity",
+  fields: {
+    "<field-id-1>": { type: "text", value: "Some text" },
+    "<field-id-2>": { type: "numeric", value: 10 }
+  }
+}
+
+// ✅ CORRECT - Create field ID constants from workflow schema
+// Get IDs from hailer.workflow.get(workflowId).fields
+const FIELD_IDS = {
+  // Map readable names to actual field IDs from your workspace
+  FIELD_NAME: '<actual-field-id-from-workflow>',
+  ANOTHER_FIELD: '<another-field-id>',
+};
+
+// ✅ CORRECT - Helper function to extract field values
+function getFieldValue<T>(
+  fields: Record<string, FieldValue> | undefined,
+  fieldId: string
+): T | undefined {
+  return fields?.[fieldId]?.value as T;
+}
+
+const value1 = getFieldValue<string>(activity.fields, FIELD_IDS.FIELD_NAME);
+const value2 = getFieldValue<number>(activity.fields, FIELD_IDS.ANOTHER_FIELD);
+
+// ❌ WRONG - Don't use readable keys directly
+// activity.fields.playerName.value  // undefined!
+// activity.fields['playerName']     // undefined!
+
+---
+
+## CLEAN CODE PRACTICES
+
+1. **Small, Focused Functions** - Each function does one thing
+2. **Early Returns** - Avoid deep nesting
+3. **Const by Default** - Only use let when reassignment is needed
+4. **Handle All States** - Loading, error, empty, success
+
+### Example Component Pattern
+
+function ActivityList({ hailer, workflowId, phaseId }: Props) {
+  const [activities, setActivities] = useState<Activity[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    loadData();
+  }, [workflowId, phaseId]);
+
+  async function loadData() {
+    try {
+      setLoading(true);
+      setError(null);
+      const result = await hailer.activity.list(workflowId, phaseId, { limit: 100 });
+      setActivities(result || []);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  // Loading state
+  if (loading) return <Spinner />;
+
+  // Error state
+  if (error) return <Alert status="error">{error}</Alert>;
+
+  // Empty state
+  if (activities.length === 0) return <Text>No activities found</Text>;
+
+  // Success state
+  return <ActivityTable data={activities} />;
+}
+
+---
+
+## WHAT TO BUILD
+
+Based on the task requirements, create these files:
+
+1. **src/types/activity.ts** - All TypeScript interfaces
+2. **src/config/workflows.ts** - Workflow IDs, field IDs, phase IDs
+3. **src/utils/fieldHelpers.ts** - getFieldValue() and other helpers
+4. **src/components/** - React components based on task
+5. **Update src/App.tsx** - Wire everything together
+
+## DO NOT
+
+- ❌ Use any type anywhere
+- ❌ Use hailer.process.getFields() (doesn't exist)
+- ❌ Access fields by readable keys (use field IDs)
+- ❌ Skip loading/error/empty states
+- ❌ Forget to type function parameters
+
+## DO
+
+- ✅ Define interfaces for all data structures
+- ✅ Use hailer.workflow.get(workflowId) for schema
+- ✅ Use hailer.activity.list(workflowId, phaseId, options) for data
+- ✅ Access fields via field IDs with helper function
+- ✅ Handle all UI states (loading, error, empty, success)
+- ✅ Use Chakra UI components (already installed)
+- ✅ Use Chart.js + react-chartjs-2 for charts (already installed)
+
+---
+
+## REPORT BACK
+
+When done, report:
+1. What files you created/modified
+2. What components are available
+3. How to use them
+4. Any issues or next steps needed
+`
+})
+```
+
+## Template Variables
+
+Replace these placeholders in the prompt:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `${PROJECT_PATH}` | Absolute path to scaffolded app | `/home/user/dev-apps/fc-dashboard` |
+| `${TASK_DESCRIPTION}` | What user wants built | `Full data manager with View + Edit + Create for all workflows` |
+| `${WORKFLOWS_INFO}` | Formatted workflow list | `- Players (abc123): 31 activities\n- Teams (def456): 15 activities` |
+
+## Complete Example
+
+```javascript
+// After scaffold completes and user confirms they want to spawn agent:
+
+// 1. Gather workflow context from list_workflows_minimal()
+// Format the output into a string for the agent prompt
+const workflowsInfo = `
+- Workflow Name 1 (<workflow-id-1>): X activities
+- Workflow Name 2 (<workflow-id-2>): Y activities
+- Workflow Name 3 (<workflow-id-3>): Z activities
+`;
+// Replace with actual data from list_workflows_minimal()
+
+// 2. Spawn the agent with Task tool
+Task({
+  subagent_type: "general-purpose",
+  description: "Build app-name components",
+  prompt: `
+You are a **Hailer App Builder**...
+
+## YOUR TASK
+Build components for: /path/to/your/scaffolded/app
+Requirements: Dashboard/Data manager/Custom (based on user request)
+
+## WORKSPACE DATA
+${workflowsInfo}
+
+... (rest of embedded template from above) ...
+`
+})
+```
+
+## Why Spawn an Agent?
+
+| Benefit | Description |
+|---------|-------------|
+| **Isolated context** | Agent gets fresh context without conversation noise |
+| **Pre-loaded knowledge** | All TypeScript + SDK patterns embedded in prompt |
+| **Focused execution** | Single task without distractions |
+| **Better code quality** | Standards enforced from the start |
+
+## Alternative: Load Skills in Current Session
+
+If user prefers not to spawn an agent, load both skills in the current session:
+
+```javascript
+Skill("building-hailer-apps-skill")
+Skill("hailer-app-builder")
+```
+
+Then continue building in the current conversation.

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.5] - 01-12-2025
+
+### Added
+
+- **New Skills**:
+  - `hailer-app-builder` - TypeScript standards and clean code patterns
+  - `spawn-app-builder` - Isolated agent spawning for app development
+  - `MCP-build-data-app-skill` - Data app building patterns
+  - `MCP-publish-template-skill` - Marketplace template publishing guide
+
+- **New Hooks**:
+  - `post-scaffold-hook.cjs` - Auto-spawns builder agent after scaffolding
+  - `publish-template-guard.cjs` - Validates required fields before publishing
+
+### Changed
+
+- Updated `scaffold-hailer-app-skill` with mandatory agent spawn documentation
+- Updated `building-hailer-apps-skill` with improved field access patterns
+- Enhanced `prompt-skill-loader` with new skill keywords
+
+### Fixed
+
+- App tools configuration imports
+
 ## [0.0.4] - 28-11-2025
 
 ### Added

package/dist/app.js

@@ -61,6 +61,14 @@ core.addTool(app_1.addAppMemberTool);
 core.addTool(app_1.removeAppMemberTool);
 core.addTool(app_1.scaffoldHailerAppTool);
 core.addTool(app_1.publishHailerAppTool);
+// Marketplace template tools
+core.addTool(app_1.listTemplatesTool);
+core.addTool(app_1.createTemplateTool);
+core.addTool(app_1.installTemplateTool);
+core.addTool(app_1.getTemplateTool);
+core.addTool(app_1.publishTemplateTool);
+core.addTool(app_1.getProductTool);
+core.addTool(app_1.getProductManifestTool);
 core.addTool(skill_1.listSkillsTool);
 core.addTool(skill_1.getSkillTool);
 console.log('All tools registered successfully!');

package/dist/mcp/tools/app.d.ts

@@ -17,4 +17,11 @@ export declare const addAppMemberTool: Tool;
 export declare const removeAppMemberTool: Tool;
 export declare const scaffoldHailerAppTool: Tool;
 export declare const publishHailerAppTool: Tool;
+export declare const listTemplatesTool: Tool;
+export declare const createTemplateTool: Tool;
+export declare const installTemplateTool: Tool;
+export declare const getTemplateTool: Tool;
+export declare const publishTemplateTool: Tool;
+export declare const getProductTool: Tool;
+export declare const getProductManifestTool: Tool;
 //# sourceMappingURL=app.d.ts.map