@hailer/mcp 0.0.1

package/.claude/skills/update-app-skill/SKILL.md

@@ -0,0 +1,970 @@
+---
+name: Updating Hailer Apps
+description: Complete guide for modifying Hailer app properties - use when changing app names, descriptions, or configurations
+---
+
+# Updating Hailer Apps - Complete Guide
+
+Complete reference for modifying Hailer app properties using the `update_app` MCP tool.
+
+## Table of Contents
+1. [Quick Reference](#quick-reference)
+2. [Overview](#overview)
+3. [Core Concepts](#core-concepts)
+4. [Basic Usage](#basic-usage)
+5. [Updatable Properties](#updatable-properties)
+6. [Common Scenarios](#common-scenarios)
+7. [Configuration Updates](#configuration-updates)
+8. [Best Practices](#best-practices)
+9. [Troubleshooting](#troubleshooting)
+
+## Quick Reference
+
+**Update App Name:**
+
+```javascript
+update_app({
+  appId: 'app-id',
+  name: 'New App Name'
+})
+```
+
+**Update Multiple Properties:**
+
+```javascript
+update_app({
+  appId: 'app-id',
+  name: 'Updated Name',
+  description: 'Updated description',
+  config: {
+    workflowId: 'new-workflow-id',
+    theme: 'dark'
+  }
+})
+```
+
+**Update in Specific Workspace:**
+
+```javascript
+update_app({
+  workspaceId: 'workspace-id',
+  appId: 'app-id',
+  name: 'New Name'
+})
+```
+
+**Key Requirements:**
+- Must be app owner OR workspace administrator
+- App ID is required
+- At least one property to update
+- Cannot change app type (dev to published or vice versa)
+- Changes take effect immediately
+
+## Overview
+
+**What does update_app do?**
+
+Modifies properties of an existing Hailer app entry without affecting the app's code or deployment. This updates the app metadata stored in Hailer's database.
+
+**Think of it as:**
+- Editing app settings
+- Updating app metadata
+- Reconfiguring app parameters
+- Changing app display properties
+
+**What it Updates:**
+- App name
+- App description
+- App configuration
+- App icon/image
+- App URL (dev apps only)
+
+**What it Does NOT Update:**
+- App code (use publish_hailer_app)
+- App permissions (use add_app_member/remove_app_member)
+- App type (dev to published conversion not supported)
+- App ID (immutable)
+- manifest.json (manually edit and republish)
+
+## Core Concepts
+
+### Non-Destructive Updates
+
+**Updates are safe:**
+- Doesn't affect deployed app code
+- Doesn't break existing functionality
+- Changes are immediate
+- Can be reverted by updating again
+
+### App Type Restrictions
+
+**Cannot change app type:**
+```javascript
+// ❌ Cannot do this:
+// Convert dev app to published
+update_app({
+  appId: 'dev-app-id',
+  url: ''  // Remove URL doesn't make it published
+})
+
+// ❌ Cannot do this:
+// Convert published app to dev
+update_app({
+  appId: 'published-app-id',
+  url: 'http://localhost:3000'  // Adding URL doesn't work
+})
+
+// ✅ Solution: Create separate app entries
+```
+
+### Update vs Republish
+
+**When to use update_app:**
+- Change app display name
+- Update app description
+- Modify configuration parameters
+- Change app icon
+- Update dev app URL
+
+**When to republish (publish_hailer_app):**
+- Update app code
+- Deploy new features
+- Fix bugs in app
+- Change app behavior
+- Update dependencies
+
+## Basic Usage
+
+### Example 1: Update Name
+
+```javascript
+// 1. Find app
+const apps = list_apps()
+const app = apps.find(a => a.name === 'Old Name')
+
+// 2. Update name
+update_app({
+  appId: app._id,
+  name: 'New Name'
+})
+
+console.log('✅ App name updated')
+```
+
+### Example 2: Update Description
+
+```javascript
+update_app({
+  appId: 'app-id',
+  description: 'Updated app description with more details about functionality'
+})
+```
+
+### Example 3: Update Multiple Properties
+
+```javascript
+update_app({
+  appId: 'app-id',
+  name: 'Task Manager Pro',
+  description: 'Advanced task management with kanban boards',
+  config: {
+    workflowId: 'tasks-workflow-id',
+    defaultView: 'kanban',
+    theme: 'dark'
+  }
+})
+```
+
+### Example 4: Update Dev App URL
+
+```javascript
+// Change dev app port
+update_app({
+  appId: 'dev-app-id',
+  url: 'http://localhost:3001'  // Changed from 3000
+})
+
+console.log('✅ Dev app URL updated to 3001')
+```
+
+### Example 5: Update in Specific Workspace
+
+```javascript
+update_app({
+  workspaceId: 'workspace-id',
+  appId: 'app-id',
+  name: 'Updated Name'
+})
+```
+
+## Updatable Properties
+
+### name (string)
+
+**App display name in Hailer:**
+
+```javascript
+update_app({
+  appId: 'app-id',
+  name: 'Customer Portal'
+})
+```
+
+**Tips:**
+- Shown in Apps menu
+- Should be descriptive
+- Can include version (e.g., "App v2.0")
+- Use "(Dev)" suffix for dev apps
+
+### description (string)
+
+**App description/purpose:**
+
+```javascript
+update_app({
+  appId: 'app-id',
+  description: 'Manage customer accounts, orders, and support tickets'
+})
+```
+
+**Tips:**
+- Explain app purpose
+- List key features
+- Include usage instructions
+- Can be longer text
+
+### url (string, dev apps only)
+
+**Development app URL:**
+
+```javascript
+update_app({
+  appId: 'dev-app-id',
+  url: 'http://localhost:3001'
+})
+```
+
+**Notes:**
+- Only for development apps
+- Published apps ignore this property
+- Must be localhost URL
+- Changes where Hailer loads app from
+
+### image (string)
+
+**App icon/image ID:**
+
+```javascript
+update_app({
+  appId: 'app-id',
+  image: 'image-id-24-chars'
+})
+```
+
+**Notes:**
+- Must be 24 characters
+- References uploaded image
+- Optional
+
+### config (object)
+
+**Custom app configuration:**
+
+```javascript
+update_app({
+  appId: 'app-id',
+  config: {
+    workflowId: 'workflow-id',
+    theme: 'dark',
+    features: {
+      exportEnabled: true,
+      notificationsEnabled: false
+    }
+  }
+})
+```
+
+**Notes:**
+- App-specific settings
+- Passed to app at runtime
+- Can be any JSON structure
+- Completely replaces old config (not merged)
+
+### workspaceId (string, optional)
+
+**Target workspace:**
+
+```javascript
+update_app({
+  workspaceId: 'workspace-id',
+  appId: 'app-id',
+  name: 'New Name'
+})
+```
+
+**Notes:**
+- Defaults to current workspace
+- Use when managing multiple workspaces
+
+## Common Scenarios
+
+### Scenario 1: Rename App
+
+**Goal:** Change app display name.
+
+```javascript
+// 1. Find app
+const apps = list_apps()
+const app = apps.find(a => a.name === 'Task Manager')
+
+if (!app) {
+  console.error('App not found')
+  return
+}
+
+// 2. Update name
+update_app({
+  appId: app._id,
+  name: 'Task Manager Pro'
+})
+
+// 3. Verify update
+const updatedApps = list_apps()
+const updated = updatedApps.find(a => a._id === app._id)
+console.log('New name:', updated.name)
+// Output: New name: Task Manager Pro
+```
+
+### Scenario 2: Update Configuration
+
+**Goal:** Change workflow ID or settings.
+
+```javascript
+// Update app to use different workflow
+update_app({
+  appId: 'app-id',
+  config: {
+    workflowId: 'new-workflow-id',
+    defaultView: 'table',
+    refreshInterval: 30
+  }
+})
+
+console.log('✅ App configuration updated')
+console.log('⚠️ Users may need to refresh to see changes')
+```
+
+### Scenario 3: Fix Dev App Port
+
+**Goal:** Change dev app port after conflict.
+
+```javascript
+// Port 3000 is in use, switch to 3001
+
+// 1. Update dev app URL
+update_app({
+  appId: 'dev-app-id',
+  url: 'http://localhost:3001'
+})
+
+// 2. Update dev server config
+// Edit vite.config.ts or package.json
+// Change port to 3001
+
+// 3. Restart dev server
+// npm run dev
+
+console.log('✅ Dev app now using port 3001')
+```
+
+### Scenario 4: Add Description to Existing App
+
+**Goal:** Add helpful description to app created without one.
+
+```javascript
+const apps = list_apps()
+const appsWithoutDescription = apps.filter(a => !a.description)
+
+console.log(`Found ${appsWithoutDescription.length} apps without descriptions`)
+
+appsWithoutDescription.forEach(app => {
+  // Add description based on app name
+  let description = ''
+
+  if (app.name.includes('Task')) {
+    description = 'Task management and tracking application'
+  } else if (app.name.includes('Dashboard')) {
+    description = 'Real-time dashboard for metrics and analytics'
+  } else {
+    description = 'Hailer application'
+  }
+
+  update_app({
+    appId: app._id,
+    description: description
+  })
+
+  console.log(`✅ Added description to ${app.name}`)
+})
+```
+
+### Scenario 5: Update All Dev Apps with Consistent Naming
+
+**Goal:** Add "(Dev)" suffix to all development apps.
+
+```javascript
+const apps = list_apps()
+const devApps = apps.filter(a => a.url && !a.name.includes('(Dev)'))
+
+console.log(`Found ${devApps.length} dev apps without (Dev) suffix`)
+
+devApps.forEach(app => {
+  update_app({
+    appId: app._id,
+    name: `${app.name} (Dev)`
+  })
+
+  console.log(`✅ Updated: ${app.name} → ${app.name} (Dev)`)
+})
+```
+
+### Scenario 6: Sync Configuration Across Environments
+
+**Goal:** Keep dev and prod config in sync.
+
+```javascript
+// Production config
+const prodConfig = {
+  workflowId: 'tasks-workflow-id',
+  theme: 'light',
+  refreshInterval: 60,
+  features: {
+    exportEnabled: true,
+    notificationsEnabled: true
+  }
+}
+
+// Find dev and prod apps
+const apps = list_apps()
+const devApp = apps.find(a => a.name === 'My App (Dev)')
+const prodApp = apps.find(a => a.name === 'My App')
+
+// Update both with same config
+if (devApp) {
+  update_app({
+    appId: devApp._id,
+    config: prodConfig
+  })
+  console.log('✅ Dev app config updated')
+}
+
+if (prodApp) {
+  update_app({
+    appId: prodApp._id,
+    config: prodConfig
+  })
+  console.log('✅ Prod app config updated')
+}
+```
+
+## Configuration Updates
+
+### Complete Replacement
+
+**Config updates replace entire object:**
+
+```javascript
+// Original config
+const app = list_apps().find(a => a.name === 'My App')
+console.log('Original config:', app.config)
+// { workflowId: 'wf1', theme: 'dark', refreshInterval: 30 }
+
+// Update config
+update_app({
+  appId: app._id,
+  config: {
+    workflowId: 'wf2'
+  }
+})
+
+// New config (other properties lost!)
+const updated = list_apps().find(a => a._id === app._id)
+console.log('New config:', updated.config)
+// { workflowId: 'wf2' }  // theme and refreshInterval gone!
+```
+
+### Merge Strategy
+
+**To preserve existing config, merge manually:**
+
+```javascript
+// 1. Get current config
+const app = list_apps().find(a => a.name === 'My App')
+const currentConfig = app.config || {}
+
+// 2. Merge with updates
+const updatedConfig = {
+  ...currentConfig,           // Keep existing
+  workflowId: 'new-wf-id',   // Update this
+  newProperty: 'new-value'    // Add this
+}
+
+// 3. Update app
+update_app({
+  appId: app._id,
+  config: updatedConfig
+})
+```
+
+### Nested Configuration
+
+**Handle nested objects carefully:**
+
+```javascript
+const app = list_apps().find(a => a.name === 'My App')
+
+// Current config
+const currentConfig = app.config || {}
+
+// Update nested features
+const updatedConfig = {
+  ...currentConfig,
+  features: {
+    ...(currentConfig.features || {}),  // Keep existing features
+    exportEnabled: true                  // Update this feature
+  }
+}
+
+update_app({
+  appId: app._id,
+  config: updatedConfig
+})
+```
+
+### Configuration Schema Example
+
+**Typical app configuration:**
+
+```javascript
+update_app({
+  appId: 'app-id',
+  config: {
+    // Workflow references
+    workflowId: 'primary-workflow-id',
+    secondaryWorkflowId: 'secondary-workflow-id',
+
+    // Display settings
+    defaultView: 'kanban',  // 'table', 'kanban', 'calendar'
+    theme: 'dark',          // 'light', 'dark', 'auto'
+    locale: 'en',           // 'en', 'fi', 'sv'
+
+    // Behavior settings
+    refreshInterval: 60,    // seconds
+    autoSave: true,
+    confirmDeletes: true,
+
+    // Feature flags
+    features: {
+      exportEnabled: true,
+      importEnabled: false,
+      notificationsEnabled: true,
+      advancedFilters: true
+    },
+
+    // Custom settings
+    customSettings: {
+      maxItems: 100,
+      defaultPriority: 'medium',
+      sortBy: 'dueDate'
+    }
+  }
+})
+```
+
+## Best Practices
+
+### 1. Verify App Exists and Permissions
+
+```javascript
+// Always verify before updating
+const apps = list_apps()
+const app = apps.find(a => a._id === 'target-id')
+
+if (!app) {
+  console.error('App not found')
+  return
+}
+
+if (!app.canEdit) {
+  console.error('No permission to edit this app')
+  return
+}
+
+// Safe to update
+update_app({
+  appId: app._id,
+  name: 'New Name'
+})
+```
+
+### 2. Preserve Existing Config
+
+```javascript
+// Don't lose existing config
+const app = list_apps().find(a => a._id === 'app-id')
+
+// Bad: Replaces entire config
+update_app({
+  appId: app._id,
+  config: { workflowId: 'new-id' }  // Loses other settings
+})
+
+// Good: Merge with existing
+update_app({
+  appId: app._id,
+  config: {
+    ...app.config,
+    workflowId: 'new-id'  // Updates this, keeps others
+  }
+})
+```
+
+### 3. Use Descriptive Names
+
+```javascript
+// Good names
+update_app({
+  appId: 'app-id',
+  name: 'Task Manager (Dev)'
+})
+
+update_app({
+  appId: 'app-id',
+  name: 'Customer Portal - Production'
+})
+
+// Bad names
+update_app({
+  appId: 'app-id',
+  name: 'App 1'  // Not descriptive
+})
+```
+
+### 4. Update After Workflow Changes
+
+```javascript
+// Workflow was replaced, update apps using it
+const oldWorkflowId = 'old-workflow-id'
+const newWorkflowId = 'new-workflow-id'
+
+const apps = list_apps()
+const appsUsingOldWorkflow = apps.filter(a =>
+  a.config?.workflowId === oldWorkflowId
+)
+
+appsUsingOldWorkflow.forEach(app => {
+  update_app({
+    appId: app._id,
+    config: {
+      ...app.config,
+      workflowId: newWorkflowId
+    }
+  })
+  console.log(`✅ Updated ${app.name}`)
+})
+```
+
+### 5. Document Configuration Changes
+
+```javascript
+// Log configuration updates
+console.log('Updating app configuration:')
+console.log('App:', app.name)
+console.log('Old config:', JSON.stringify(app.config, null, 2))
+
+update_app({
+  appId: app._id,
+  config: newConfig
+})
+
+console.log('New config:', JSON.stringify(newConfig, null, 2))
+console.log('Updated:', new Date().toISOString())
+```
+
+### 6. Test After Configuration Updates
+
+```javascript
+// Update config
+update_app({
+  appId: 'app-id',
+  config: {
+    workflowId: 'new-workflow-id'
+  }
+})
+
+console.log('✅ Configuration updated')
+console.log('⚠️ Test app in Hailer to verify changes')
+console.log('⚠️ Users may need to refresh browser')
+```
+
+### 7. Separate Dev and Prod Configs
+
+```javascript
+// Different configs for different environments
+const devConfig = {
+  workflowId: 'test-workflow-id',
+  apiUrl: 'http://localhost:1337',
+  debugMode: true
+}
+
+const prodConfig = {
+  workflowId: 'prod-workflow-id',
+  apiUrl: 'https://api.hailer.com',
+  debugMode: false
+}
+
+// Update dev app
+update_app({
+  appId: 'dev-app-id',
+  config: devConfig
+})
+
+// Update prod app
+update_app({
+  appId: 'prod-app-id',
+  config: prodConfig
+})
+```
+
+## Troubleshooting
+
+### Error: "Permission Denied"
+
+**Cause:** Not app owner or workspace administrator.
+
+**Solution:**
+
+```javascript
+// Check permissions
+const app = list_apps().find(a => a._id === 'app-id')
+
+console.log('Owner:', app.isOwner)
+console.log('Admin:', app.isAdmin)
+console.log('Can edit:', app.canEdit)
+
+if (!app.canEdit) {
+  console.error('No permission to edit this app')
+  console.log('Contact app owner:', app.owner)
+}
+```
+
+### Error: "App Not Found"
+
+**Cause:** Invalid app ID or app doesn't exist.
+
+**Solution:**
+
+```javascript
+// Verify app ID
+const apps = list_apps()
+const app = apps.find(a => a._id === 'target-id')
+
+if (!app) {
+  console.error('App not found')
+  console.log('Available apps:')
+  apps.forEach(a => console.log(`- ${a.name}: ${a._id}`))
+}
+```
+
+### Changes Not Visible
+
+**Causes:**
+1. Browser cache
+2. App needs refresh
+3. Wrong app updated
+
+**Solutions:**
+
+```javascript
+// 1. Verify update
+const apps = list_apps()
+const app = apps.find(a => a._id === 'app-id')
+console.log('Current name:', app.name)
+console.log('Current config:', app.config)
+
+// 2. Refresh browser
+console.log('⚠️ Refresh Hailer in browser to see changes')
+
+// 3. Check correct app
+console.log('App ID:', app._id)
+console.log('Type:', app.url ? 'Dev' : 'Published')
+```
+
+### Config Lost After Update
+
+**Cause:** Config was replaced, not merged.
+
+**Solution:**
+
+```javascript
+// Get app before update
+const app = list_apps().find(a => a._id === 'app-id')
+console.log('Original config:', app.config)
+
+// If config was lost, restore it
+const restoredConfig = {
+  workflowId: 'workflow-id',
+  theme: 'dark',
+  // ... restore other properties
+}
+
+update_app({
+  appId: app._id,
+  config: restoredConfig
+})
+```
+
+### Cannot Change App Type
+
+**Problem:** Want to convert dev to published or vice versa.
+
+**Solution:**
+
+```javascript
+// Cannot convert - must create new app
+
+// 1. Get current app config
+const devApp = list_apps().find(a => a.name === 'My App (Dev)')
+
+// 2. Create new published app
+const prodApp = create_app({
+  name: 'My App',
+  config: devApp.config  // Use same config
+})
+
+// 3. Update manifest.json with new appId
+// 4. Republish
+
+console.log('New published app ID:', prodApp.appId)
+console.log('⚠️ Update manifest.json and republish')
+```
+
+## Integration with Other Tools
+
+### With create_app
+
+Create then update:
+
+```javascript
+// 1. Create basic app
+const app = create_app({
+  name: 'My App'
+})
+
+// 2. Update with full details
+update_app({
+  appId: app.appId,
+  description: 'Complete app description',
+  config: {
+    workflowId: 'workflow-id',
+    theme: 'dark'
+  }
+})
+```
+
+### With list_apps
+
+Find and update:
+
+```javascript
+// 1. List apps
+const apps = list_apps()
+
+// 2. Find target
+const app = apps.find(a => a.name === 'Old Name')
+
+// 3. Update
+if (app) {
+  update_app({
+    appId: app._id,
+    name: 'New Name'
+  })
+}
+```
+
+### With publish_hailer_app
+
+Update config then republish:
+
+```javascript
+// 1. Update app config
+update_app({
+  appId: 'app-id',
+  config: {
+    workflowId: 'new-workflow-id'
+  }
+})
+
+// 2. App code may need to use new config
+// Edit app code if needed
+
+// 3. Republish
+publish_hailer_app({
+  email: 'your@email.com',
+  password: 'password',
+  projectDirectory: '/path/to/app'
+})
+```
+
+### With remove_app
+
+Update vs remove decision:
+
+```javascript
+const app = list_apps().find(a => a.name === 'Old App')
+
+// Option 1: Update to repurpose
+update_app({
+  appId: app._id,
+  name: 'New Purpose App',
+  description: 'Repurposed for new use case',
+  config: { ... }
+})
+
+// Option 2: Remove and create new
+remove_app({ appId: app._id })
+create_app({ name: 'Brand New App' })
+```
+
+## Summary
+
+**Key Takeaways:**
+1. ✏️ **Updates metadata** - Name, description, config
+2. 🔒 **Owner/admin only** - Requires permissions
+3. ⚡ **Immediate effect** - Changes apply right away
+4. ⚠️ **Config replacement** - Entire config replaced, merge manually
+5. 🔄 **Non-destructive** - Doesn't affect app code
+6. 🚫 **Cannot change type** - Dev stays dev, published stays published
+7. 📱 **May need refresh** - Users should refresh browser
+
+**Quick Decision Tree:**
+
+```
+Need to modify app?
+│
+├─ Change name/description? → update_app
+├─ Update configuration? → update_app (merge with existing)
+├─ Change dev URL? → update_app
+├─ Update app code? → publish_hailer_app (not update_app)
+├─ Change permissions? → add_app_member/remove_app_member
+└─ Convert type? → Create new app (can't convert)
+```
+
+## Additional Resources
+
+- See `create-app-skill` for creating apps
+- See `list-apps-skill` for viewing apps
+- See `remove-app-skill` for deleting apps
+- See `publish-hailer-app-skill` for publishing app code
+- See `add-app-member-skill` for sharing apps
+- See `app-api` skill for comprehensive App API documentation