@hailer/mcp 0.0.1

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

@@ -0,0 +1,453 @@
+---
+name: Publishing Hailer Apps
+description: Complete guide for creating, developing, and publishing Hailer apps - use when building or deploying Hailer applications
+---
+
+# Publishing Hailer Apps - Complete Guide
+
+Complete reference for creating, developing, and publishing Hailer apps using the MCP tools and @hailer/app-sdk.
+
+## Table of Contents
+1. [Quick Reference](#quick-reference)
+2. [Overview](#overview)
+3. [Prerequisites](#prerequisites)
+4. [Creating a New App](#creating-a-new-app)
+5. [Development Workflow](#development-workflow)
+6. [Publishing Process](#publishing-process)
+7. [Sharing Apps](#sharing-apps)
+8. [Troubleshooting](#troubleshooting)
+
+## Quick Reference
+
+**Exact commands to publish every time (after initial setup):**
+
+```bash
+# 1. Navigate to app directory
+cd /path/to/your-app
+
+# 2. Build
+npm run build
+
+# 3. Package
+npm pack
+
+# 4. Publish to production
+echo "Y" | EMAIL=your-email@example.com PASSWORD=your-password node node_modules/@hailer/app-sdk/lib/tools/publish.cjs ./your-app-name-0.0.0.tgz --production
+```
+
+**First-time setup requirements:**
+1. Create app entry with `create_app()` MCP tool
+2. Update `public/manifest.json` with returned appId
+3. Patch `node_modules/@hailer/app-sdk/lib/tools/publish.cjs` line 44 to add PASSWORD support
+
+## Overview
+
+Hailer apps are React/TypeScript applications that run inside the Hailer workspace. They can interact with workflows, activities, and other Hailer data using the `@hailer/app-sdk`.
+
+**Key Concepts:**
+- **Development App**: Points to localhost, used during development
+- **Published App**: Hosted on Hailer servers, accessible to workspace users
+- **manifest.json**: Configuration file linking app code to Hailer app entry
+- **App Entry**: Database record in Hailer identifying the app
+
+## Prerequisites
+
+- Node.js 18+ installed
+- Access to Hailer workspace
+- Workspace administrator privileges (for publishing)
+- Hailer account credentials
+
+## Creating a New App
+
+### Step 1: Scaffold the App
+
+Use the `scaffold_hailer_app` MCP tool:
+
+```javascript
+scaffold_hailer_app({
+  projectName: "my-app",
+  template: "react-ts",  // Options: react-ts, react-swc-ts, vanilla
+  installDependencies: true
+})
+```
+
+**What Gets Created:**
+- Complete React/TypeScript project structure
+- `src/` directory with app code
+- `public/manifest.json` for app configuration
+- Vite configuration for dev server and builds
+- Package.json with dev/build/publish scripts
+
+### Step 2: Create Development App Entry
+
+Create a development app entry pointing to localhost:
+
+```javascript
+create_app({
+  name: "My App (Dev)",
+  description: "Development version",
+  url: "http://localhost:3000"
+})
+```
+
+**Update manifest.json:**
+```json
+{
+  "author": "Your Name",
+  "appId": "APP_ID_FROM_CREATE_APP",
+  "config": {
+    "fields": {
+      "workflowId": {
+        "type": "string",
+        "default": "your-workflow-id"
+      }
+    }
+  }
+}
+```
+
+## Development Workflow
+
+### Running Development Server
+
+```bash
+cd your-app-directory
+npm run dev
+```
+
+The app will be available at `http://localhost:3000` (or 3001 if 3000 is in use).
+
+### Accessing Hailer Data
+
+Use the `useHailer` hook to access Hailer API:
+
+```typescript
+import useHailer from './hailer/use-hailer';
+
+export default function App() {
+  const { hailer, inside } = useHailer();
+
+  useEffect(() => {
+    if (!hailer || !inside) return;
+
+    // Fetch data from Hailer workflows
+    const fetchData = async () => {
+      const activities = await hailer.activity.list(
+        workflowId,
+        phaseId,
+        { limit: 50 }
+      );
+      console.log('Activities:', activities);
+    };
+
+    fetchData();
+  }, [hailer, inside]);
+}
+```
+
+### Testing in Hailer
+
+1. Start dev server: `npm run dev`
+2. Open Hailer workspace
+3. Navigate to Apps menu
+4. Open your development app
+5. The app loads from localhost with hot-reload
+
+## Publishing Process
+
+### Step 1: Create Published App Entry
+
+Create a published app entry (no URL - Hailer generates it):
+
+```javascript
+create_app({
+  name: "My App",
+  description: "Production app description"
+  // No url parameter - auto-generated for published apps
+})
+```
+
+Save the returned `appId` - you'll need it for manifest.json.
+
+### Step 2: Update Manifest
+
+Update `public/manifest.json` with the published app ID:
+
+```json
+{
+  "author": "Your Name",
+  "appId": "PUBLISHED_APP_ID",
+  "config": {
+    "fields": {
+      "workflowId": {
+        "type": "string",
+        "default": "your-workflow-id"
+      }
+    }
+  }
+}
+```
+
+### Step 3: Build and Publish
+
+#### Option A: Using MCP Tool (Recommended)
+
+```javascript
+publish_hailer_app({
+  email: "your.email@example.com",
+  password: "your-password",
+  projectDirectory: "/path/to/your-app"
+})
+```
+
+**Note:** This may fail in non-interactive environments. If so, use Option B.
+
+#### Option B: Manual Publish with PASSWORD Env Var (RECOMMENDED - Works Every Time)
+
+**This is the proven, reliable method that works consistently.**
+
+1. **Patch the publish script** (one-time fix per project):
+
+```bash
+# Edit node_modules/@hailer/app-sdk/lib/tools/publish.cjs
+# Line 44, change from:
+let password = process.env.LOCAL || await (0, minimal_password_prompt_1.default)('enter password for ' + email + ': ');
+
+# To:
+let password = process.env.PASSWORD || process.env.LOCAL || await (0, minimal_password_prompt_1.default)('enter password for ' + email + ': ');
+```
+
+2. **Build and publish with EXACT commands:**
+
+```bash
+# Step 1: Navigate to app directory
+cd your-app-directory
+
+# Step 2: Build the app
+npm run build
+
+# Step 3: Package the app
+npm pack
+
+# Step 4: Publish to production with auto-confirmation
+echo "Y" | EMAIL=your-email@example.com PASSWORD=your-password node node_modules/@hailer/app-sdk/lib/tools/publish.cjs ./your-app-name-0.0.0.tgz --production
+```
+
+**IMPORTANT NOTES:**
+- Replace `your-app-name-0.0.0.tgz` with your actual package filename
+- The `echo "Y" |` automatically confirms the overwrite prompt
+- The PASSWORD env var bypasses interactive password prompt
+- Build output goes to `dist/` directory and is included in the .tgz file
+
+**Environment Options:**
+- `--production`: Publishes to api.hailer.com (REQUIRED for production)
+- `--staging`: Publishes to api.hailer.biz
+- `--development`: Publishes to testapi.hailer.biz
+- `--local`: Publishes to localhost:1337
+
+### Step 4: Verify Publication
+
+The publish script will show:
+
+```
+Publishing App
+  Id: your-app-id
+  Name: My App
+  Workspace: workspace-name (workspace-id)
+  Environment: https://api.hailer.com
+
+Overwrite the app? (Y/n): App info: { ... }
+
+Published successfully!
+```
+
+## Sharing Apps
+
+### Share with Entire Workspace
+
+```javascript
+add_app_member({
+  appId: "your-app-id",
+  member: "network_WORKSPACE_ID"
+})
+```
+
+### Share with Specific Team
+
+```javascript
+add_app_member({
+  appId: "your-app-id",
+  member: "team_TEAM_ID"
+})
+```
+
+### Share with Individual User
+
+```javascript
+add_app_member({
+  appId: "your-app-id",
+  member: "user_USER_ID"
+})
+```
+
+### Remove Access
+
+```javascript
+remove_app_member({
+  appId: "your-app-id",
+  member: "network_WORKSPACE_ID"
+})
+```
+
+## Troubleshooting
+
+### Issue: "stdin.setRawMode is not a function"
+
+**Cause:** Publish script trying to prompt for password in non-interactive environment.
+
+**Solution:** Patch publish script to support PASSWORD env var (see Option B above).
+
+### Issue: "appId mismatch" or "App not found"
+
+**Cause:** manifest.json has wrong appId.
+
+**Solution:**
+1. Use `list_apps()` to find correct app ID
+2. Update `public/manifest.json` with correct appId
+3. Rebuild: `npm run build-production`
+4. Republish
+
+### Issue: "Permission denied"
+
+**Cause:** User is not workspace administrator.
+
+**Solution:** Only workspace admins can create and publish apps. Contact your workspace admin.
+
+### Issue: App shows blank screen
+
+**Cause:** Various - check browser console.
+
+**Common fixes:**
+1. Ensure manifest.json is in `public/` directory (gets copied to `dist/`)
+2. Check Hailer API initialization in useHailer hook
+3. Verify workflow IDs in manifest.json match actual workflows
+4. Check browser console for CORS errors
+
+### Issue: Changes not appearing after publish
+
+**Cause:** Browser cache or outdated build.
+
+**Solution:**
+1. Clear browser cache
+2. Hard refresh (Ctrl+Shift+R)
+3. Verify build completed: `ls dist/` should show updated files
+4. Check npm pack created new tarball with recent timestamp
+
+### Issue: "Network error" during publish
+
+**Cause:** Cannot connect to Hailer API servers.
+
+**Solution:**
+1. Check internet connectivity
+2. Verify correct environment flag (--production, --staging, --development)
+3. For local development: Check NODE_TLS_REJECT_UNAUTHORIZED=0 if using self-signed certs
+
+## Complete Example: Football Lineup App
+
+Real-world example from our implementation:
+
+```bash
+# 1. Scaffold app
+scaffold_hailer_app({
+  projectName: "football-lineup-app",
+  template: "react-ts"
+})
+
+# 2. Develop app
+cd football-lineup-app
+npm run dev
+# ... build app features ...
+
+# 3. Create published app entry
+create_app({
+  name: "Football Lineup Manager",
+  description: "Interactive football team lineup manager"
+})
+# Returns: appId: 690988024ecaf7fb6baded60
+
+# 4. Update manifest.json
+{
+  "author": "Football Team Management",
+  "appId": "690988024ecaf7fb6baded60",
+  "config": {
+    "fields": {
+      "workflowId": {
+        "type": "string",
+        "default": "69087299c0e0b9944c620168"
+      }
+    }
+  }
+}
+
+# 5. Patch publish script (one-time)
+# Add PASSWORD support to publish.cjs line 44
+
+# 6. Build and Publish (exact working commands)
+npm run build
+npm pack
+echo "Y" | EMAIL=your-email@example.com PASSWORD=your-password node node_modules/@hailer/app-sdk/lib/tools/publish.cjs ./football-lineup-app-0.0.0.tgz --production
+
+# 7. Share with workspace
+add_app_member({
+  appId: "690988024ecaf7fb6baded60",
+  member: "network_6901c67b4e80fecb6fd7b38a"
+})
+```
+
+## Best Practices
+
+1. **Separate Dev and Production Apps**: Always maintain separate app entries for development and production
+2. **Version Your Apps**: Update version in package.json for each release
+3. **Test Before Publishing**: Thoroughly test in development mode before publishing
+4. **Document Config Fields**: Add clear descriptions for config fields in manifest.json
+5. **Use Environment Variables**: Don't hardcode workflow IDs - use manifest.json config
+6. **Handle Loading States**: Always check `if (!hailer || !inside)` before accessing Hailer API
+7. **Error Handling**: Wrap Hailer API calls in try-catch blocks
+
+## Available MCP Tools
+
+- `scaffold_hailer_app`: Create new app from template
+- `create_app`: Create app entry in Hailer
+- `update_app`: Modify app properties
+- `remove_app`: Delete app entry
+- `list_apps`: View all workspace apps
+- `add_app_member`: Share app with users/teams
+- `remove_app_member`: Revoke app access
+- `publish_hailer_app`: Build and publish app (may require workaround)
+
+## Package.json Scripts Reference
+
+Standard scripts in scaffolded apps:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "build-development": "vite build --mode development",
+    "build-staging": "vite build --mode staging",
+    "build-production": "vite build --mode production",
+    "publish-development": "npm run build-development && node node_modules/@hailer/app-sdk/lib/tools/publish.cjs ./`npm pack` --development",
+    "publish-staging": "npm run build-staging && node node_modules/@hailer/app-sdk/lib/tools/publish.cjs ./`npm pack` --staging",
+    "publish-production": "npm run build-production && node node_modules/@hailer/app-sdk/lib/tools/publish.cjs ./`npm pack` --production"
+  }
+}
+```
+
+## Additional Resources
+
+- Hailer App SDK documentation
+- React + TypeScript best practices
+- Vite build configuration
+- Hailer API reference (use `hailer-api` skill for comprehensive API docs)