@hailer/mcp 0.0.1

package/.claude/skills/list-apps-skill/SKILL.md

@@ -0,0 +1,1010 @@
+---
+name: Listing Hailer Apps
+description: Complete guide for viewing and managing Hailer apps in workspace - use when discovering or auditing apps
+---
+
+# Listing Hailer Apps - Complete Guide
+
+Complete reference for viewing Hailer apps in your workspace using the `list_apps` MCP tool.
+
+## Table of Contents
+1. [Quick Reference](#quick-reference)
+2. [Overview](#overview)
+3. [Response Structure](#response-structure)
+4. [Basic Usage](#basic-usage)
+5. [Filtering and Finding](#filtering-and-finding)
+6. [App Properties](#app-properties)
+7. [Common Scenarios](#common-scenarios)
+8. [Working with Results](#working-with-results)
+9. [Best Practices](#best-practices)
+10. [Troubleshooting](#troubleshooting)
+
+## Quick Reference
+
+**List All Apps:**
+
+```javascript
+list_apps()
+```
+
+**List in Specific Workspace:**
+
+```javascript
+list_apps({
+  workspaceId: 'workspace-id'
+})
+```
+
+**Response Format:**
+```javascript
+[
+  {
+    _id: 'app-id',
+    name: 'My App',
+    description: 'App description',
+    url: 'http://localhost:3000',  // Dev apps only
+    image: 'image-id',
+    config: { ... },
+    created: '2024-01-15T10:30:00Z',
+    owner: 'user-id',
+    members: ['network_workspace-id'],
+    isOwner: true
+  },
+  // ... more apps
+]
+```
+
+**Key Features:**
+- Lists all apps in workspace
+- Shows dev and published apps
+- Includes app metadata
+- Shows ownership and permissions
+- Can filter by workspace
+
+## Overview
+
+**What does list_apps do?**
+
+Returns an array of all Hailer apps in your current workspace (or specified workspace). Shows both development and published apps that you have access to.
+
+**Think of it as:**
+- Directory of workspace apps
+- App inventory
+- App discovery tool
+- Access control viewer
+
+**When to Use:**
+- Find app IDs for other operations
+- Discover available apps
+- Audit app access
+- Check app configurations
+- Verify app creation
+- Find dev vs published apps
+- Identify app owners
+
+**When NOT to Use:**
+- Looking for workflows (use list_workflows)
+- Need app usage statistics (not provided)
+- Want to execute app (open in Hailer UI)
+
+## Response Structure
+
+### App Object
+
+Each app in the response contains:
+
+```javascript
+{
+  // Identification
+  _id: 'app-id',                    // App ID (use for other operations)
+  name: 'My App',                   // Display name
+  description: 'App description',   // Optional description
+
+  // Configuration
+  url: 'http://localhost:3000',     // Dev apps only, published apps omit
+  image: 'image-id',                // Optional app icon
+  config: {                          // Custom configuration
+    workflowId: 'workflow-id',
+    theme: 'dark'
+  },
+
+  // Metadata
+  created: '2024-01-15T10:30:00Z', // Creation timestamp
+  updated: '2024-01-20T14:00:00Z', // Last update timestamp
+  owner: 'user-id',                 // App creator
+
+  // Access control
+  members: [                         // Who has access
+    'network_workspace-id',          // Whole workspace
+    'team_team-id',                  // Specific team
+    'user_user-id'                   // Specific user
+  ],
+
+  // Permissions (your access)
+  isOwner: true,                    // You created this app
+  isAdmin: true,                    // You're workspace admin
+  canEdit: true,                    // You can modify app
+  canDelete: true                   // You can remove app
+}
+```
+
+### Response Array
+
+```javascript
+const apps = list_apps()
+
+// Array of app objects
+console.log(`Found ${apps.length} apps`)
+
+// Iterate through apps
+apps.forEach(app => {
+  console.log(`${app.name}: ${app._id}`)
+})
+```
+
+## Basic Usage
+
+### Example 1: List All Apps
+
+```javascript
+// Get all apps in current workspace
+const apps = list_apps()
+
+console.log(`Total apps: ${apps.length}`)
+
+// Display app names
+apps.forEach(app => {
+  console.log(`- ${app.name}`)
+})
+```
+
+### Example 2: List with Details
+
+```javascript
+const apps = list_apps()
+
+apps.forEach(app => {
+  console.log('---')
+  console.log('Name:', app.name)
+  console.log('ID:', app._id)
+  console.log('Type:', app.url ? 'Development' : 'Published')
+  console.log('Owner:', app.isOwner ? 'You' : 'Someone else')
+  console.log('Created:', app.created)
+})
+```
+
+### Example 3: List in Specific Workspace
+
+```javascript
+// List apps in different workspace
+const apps = list_apps({
+  workspaceId: 'specific-workspace-id'
+})
+
+console.log(`Apps in workspace: ${apps.length}`)
+```
+
+### Example 4: Find Specific App
+
+```javascript
+const apps = list_apps()
+
+// Find by name
+const myApp = apps.find(app => app.name === 'Task Manager')
+
+if (myApp) {
+  console.log('Found app:', myApp._id)
+} else {
+  console.log('App not found')
+}
+```
+
+## Filtering and Finding
+
+### Find by Name
+
+```javascript
+const apps = list_apps()
+
+// Exact match
+const app = apps.find(a => a.name === 'My App')
+
+// Partial match
+const matches = apps.filter(a =>
+  a.name.toLowerCase().includes('task')
+)
+
+console.log(`Found ${matches.length} task-related apps`)
+```
+
+### Find Development Apps
+
+```javascript
+const apps = list_apps()
+
+// Dev apps have URL property
+const devApps = apps.filter(app => app.url)
+
+console.log('Development apps:')
+devApps.forEach(app => {
+  console.log(`- ${app.name}: ${app.url}`)
+})
+```
+
+### Find Published Apps
+
+```javascript
+const apps = list_apps()
+
+// Published apps have no URL or empty URL
+const publishedApps = apps.filter(app => !app.url)
+
+console.log('Published apps:')
+publishedApps.forEach(app => {
+  console.log(`- ${app.name}`)
+})
+```
+
+### Find Apps You Own
+
+```javascript
+const apps = list_apps()
+
+const myApps = apps.filter(app => app.isOwner)
+
+console.log(`You own ${myApps.length} apps:`)
+myApps.forEach(app => {
+  console.log(`- ${app.name}`)
+})
+```
+
+### Find Apps by Configuration
+
+```javascript
+const apps = list_apps()
+
+// Find apps using specific workflow
+const workflowId = 'target-workflow-id'
+const appsUsingWorkflow = apps.filter(app =>
+  app.config?.workflowId === workflowId
+)
+
+console.log(`Apps using workflow: ${appsUsingWorkflow.length}`)
+```
+
+### Sort Apps
+
+```javascript
+const apps = list_apps()
+
+// Sort by name
+const byName = [...apps].sort((a, b) =>
+  a.name.localeCompare(b.name)
+)
+
+// Sort by creation date (newest first)
+const byDate = [...apps].sort((a, b) =>
+  new Date(b.created) - new Date(a.created)
+)
+
+console.log('Newest apps:')
+byDate.slice(0, 5).forEach(app => {
+  console.log(`- ${app.name} (${app.created})`)
+})
+```
+
+## App Properties
+
+### Identification Properties
+
+**_id** - App ID
+```javascript
+const app = apps[0]
+console.log('App ID:', app._id)
+// Use for: update_app, remove_app, add_app_member
+```
+
+**name** - Display name
+```javascript
+console.log('Name:', app.name)
+// Shown in Hailer UI
+```
+
+**description** - Optional description
+```javascript
+console.log('Description:', app.description || 'None')
+```
+
+### Configuration Properties
+
+**url** - App URL (dev apps only)
+```javascript
+if (app.url) {
+  console.log('Development app:', app.url)
+} else {
+  console.log('Published app')
+}
+```
+
+**image** - App icon ID
+```javascript
+if (app.image) {
+  console.log('Has custom icon:', app.image)
+}
+```
+
+**config** - Custom configuration object
+```javascript
+if (app.config) {
+  console.log('Configuration:', app.config)
+  console.log('Workflow ID:', app.config.workflowId)
+}
+```
+
+### Metadata Properties
+
+**created** - Creation timestamp
+```javascript
+const created = new Date(app.created)
+console.log('Created:', created.toLocaleDateString())
+```
+
+**updated** - Last update timestamp
+```javascript
+const updated = new Date(app.updated)
+console.log('Updated:', updated.toLocaleDateString())
+```
+
+**owner** - Creator user ID
+```javascript
+console.log('Owner:', app.owner)
+```
+
+### Access Control Properties
+
+**members** - Who has access
+```javascript
+console.log('Shared with:', app.members.length, 'members')
+
+app.members.forEach(member => {
+  if (member.startsWith('network_')) {
+    console.log('- Workspace access')
+  } else if (member.startsWith('team_')) {
+    console.log('- Team:', member)
+  } else if (member.startsWith('user_')) {
+    console.log('- User:', member)
+  }
+})
+```
+
+**isOwner** - You created the app
+```javascript
+if (app.isOwner) {
+  console.log('You own this app')
+}
+```
+
+**isAdmin** - You're workspace admin
+```javascript
+if (app.isAdmin) {
+  console.log('You have admin access')
+}
+```
+
+**canEdit** - You can modify
+```javascript
+if (app.canEdit) {
+  console.log('You can update this app')
+}
+```
+
+**canDelete** - You can remove
+```javascript
+if (app.canDelete) {
+  console.log('You can delete this app')
+}
+```
+
+## Common Scenarios
+
+### Scenario 1: Audit All Apps
+
+**Goal:** Review all apps in workspace.
+
+```javascript
+const apps = list_apps()
+
+console.log('=== Workspace Apps Audit ===\n')
+console.log(`Total apps: ${apps.length}\n`)
+
+// Group by type
+const devApps = apps.filter(a => a.url)
+const publishedApps = apps.filter(a => !a.url)
+
+console.log(`Development apps: ${devApps.length}`)
+console.log(`Published apps: ${publishedApps.length}\n`)
+
+// Show details
+apps.forEach((app, i) => {
+  console.log(`${i + 1}. ${app.name}`)
+  console.log(`   ID: ${app._id}`)
+  console.log(`   Type: ${app.url ? 'Dev' : 'Published'}`)
+  console.log(`   Owner: ${app.isOwner ? 'You' : app.owner}`)
+  console.log(`   Created: ${app.created}`)
+  console.log(`   Shared: ${app.members.length} members`)
+  console.log()
+})
+```
+
+### Scenario 2: Find App ID for Operations
+
+**Goal:** Get app ID to use in other operations.
+
+```javascript
+// Find app by name
+const apps = list_apps()
+const targetApp = apps.find(a => a.name === 'Task Manager')
+
+if (!targetApp) {
+  console.error('App not found')
+  return
+}
+
+console.log('Found app ID:', targetApp._id)
+
+// Use in other operations
+update_app({
+  appId: targetApp._id,
+  name: 'Task Manager v2'
+})
+
+add_app_member({
+  appId: targetApp._id,
+  member: 'team_team-id'
+})
+```
+
+### Scenario 3: Clean Up Dev Apps
+
+**Goal:** Remove old development apps.
+
+```javascript
+const apps = list_apps()
+
+// Find dev apps
+const devApps = apps.filter(a => a.url && a.isOwner)
+
+console.log(`Found ${devApps.length} dev apps you own`)
+
+// Identify old apps
+devApps.forEach(app => {
+  const created = new Date(app.created)
+  const daysOld = (Date.now() - created) / 1000 / 60 / 60 / 24
+
+  console.log(`${app.name}: ${daysOld.toFixed(0)} days old`)
+
+  if (daysOld > 30) {
+    console.log(`  ⚠️ Consider removing`)
+    // remove_app({ appId: app._id })
+  }
+})
+```
+
+### Scenario 4: Find Apps Using Workflow
+
+**Goal:** Find all apps that use specific workflow.
+
+```javascript
+const workflowId = 'target-workflow-id'
+const apps = list_apps()
+
+const usingWorkflow = apps.filter(app =>
+  app.config?.workflowId === workflowId ||
+  JSON.stringify(app.config).includes(workflowId)
+)
+
+console.log(`Apps using workflow ${workflowId}:`)
+usingWorkflow.forEach(app => {
+  console.log(`- ${app.name} (${app._id})`)
+})
+
+if (usingWorkflow.length === 0) {
+  console.log('No apps use this workflow')
+}
+```
+
+### Scenario 5: Compare Dev and Prod Apps
+
+**Goal:** Match development and published versions.
+
+```javascript
+const apps = list_apps()
+
+// Group by base name
+const pairs = {}
+
+apps.forEach(app => {
+  // Remove (Dev) suffix to find base name
+  const baseName = app.name.replace(/\s*\(Dev\)\s*$/i, '')
+
+  if (!pairs[baseName]) {
+    pairs[baseName] = { dev: null, prod: null }
+  }
+
+  if (app.url) {
+    pairs[baseName].dev = app
+  } else {
+    pairs[baseName].prod = app
+  }
+})
+
+// Show pairs
+console.log('App Pairs:')
+Object.entries(pairs).forEach(([name, { dev, prod }]) => {
+  console.log(`\n${name}:`)
+  console.log('  Dev:', dev ? dev._id : 'Missing')
+  console.log('  Prod:', prod ? prod._id : 'Missing')
+})
+```
+
+### Scenario 6: Export App List
+
+**Goal:** Export app inventory to file.
+
+```javascript
+const apps = list_apps()
+
+// Create export data
+const exportData = apps.map(app => ({
+  name: app.name,
+  id: app._id,
+  type: app.url ? 'development' : 'published',
+  url: app.url || 'N/A',
+  created: app.created,
+  owner: app.isOwner ? 'You' : app.owner,
+  members: app.members.length,
+  config: app.config
+}))
+
+// Export as JSON
+const json = JSON.stringify(exportData, null, 2)
+console.log(json)
+
+// Or as CSV
+console.log('name,id,type,created,members')
+exportData.forEach(app => {
+  console.log(`"${app.name}",${app.id},${app.type},${app.created},${app.members}`)
+})
+```
+
+## Working with Results
+
+### Count Apps
+
+```javascript
+const apps = list_apps()
+
+console.log('Statistics:')
+console.log('- Total apps:', apps.length)
+console.log('- Dev apps:', apps.filter(a => a.url).length)
+console.log('- Published apps:', apps.filter(a => !a.url).length)
+console.log('- Apps you own:', apps.filter(a => a.isOwner).length)
+console.log('- Shared workspace:', apps.filter(a =>
+  a.members.some(m => m.startsWith('network_'))
+).length)
+```
+
+### Group Apps
+
+```javascript
+const apps = list_apps()
+
+// Group by owner
+const byOwner = {}
+apps.forEach(app => {
+  const owner = app.isOwner ? 'You' : app.owner
+  if (!byOwner[owner]) byOwner[owner] = []
+  byOwner[owner].push(app)
+})
+
+console.log('Apps by owner:')
+Object.entries(byOwner).forEach(([owner, apps]) => {
+  console.log(`${owner}: ${apps.length} apps`)
+})
+
+// Group by type
+const grouped = {
+  development: apps.filter(a => a.url),
+  published: apps.filter(a => !a.url)
+}
+
+console.log('\nApps by type:')
+Object.entries(grouped).forEach(([type, apps]) => {
+  console.log(`${type}: ${apps.length} apps`)
+})
+```
+
+### Create Index
+
+```javascript
+const apps = list_apps()
+
+// Create lookup by ID
+const byId = {}
+apps.forEach(app => {
+  byId[app._id] = app
+})
+
+// Create lookup by name
+const byName = {}
+apps.forEach(app => {
+  byName[app.name.toLowerCase()] = app
+})
+
+// Use lookups
+console.log('Lookup by ID:', byId['app-id-here']?.name)
+console.log('Lookup by name:', byName['task manager']?._id)
+```
+
+### Filter by Date
+
+```javascript
+const apps = list_apps()
+
+// Apps created in last 7 days
+const recent = apps.filter(app => {
+  const created = new Date(app.created)
+  const daysAgo = (Date.now() - created) / 1000 / 60 / 60 / 24
+  return daysAgo <= 7
+})
+
+console.log(`${recent.length} apps created in last 7 days`)
+
+// Apps updated recently
+const recentlyUpdated = apps.filter(app => {
+  const updated = new Date(app.updated)
+  const daysAgo = (Date.now() - updated) / 1000 / 60 / 60 / 24
+  return daysAgo <= 7
+})
+
+console.log(`${recentlyUpdated.length} apps updated in last 7 days`)
+```
+
+## Best Practices
+
+### 1. Cache Results When Appropriate
+
+```javascript
+// Don't call list_apps repeatedly
+// Bad:
+for (let i = 0; i < 10; i++) {
+  const apps = list_apps()  // Called 10 times!
+  const app = apps.find(a => a.name === names[i])
+}
+
+// Good:
+const apps = list_apps()  // Called once
+for (let i = 0; i < 10; i++) {
+  const app = apps.find(a => a.name === names[i])
+}
+```
+
+### 2. Check App Exists Before Operations
+
+```javascript
+// Always verify app exists
+const apps = list_apps()
+const app = apps.find(a => a.name === 'My App')
+
+if (!app) {
+  console.error('App not found')
+  return
+}
+
+// Safe to proceed
+update_app({
+  appId: app._id,
+  name: 'New Name'
+})
+```
+
+### 3. Handle Empty Results
+
+```javascript
+const apps = list_apps()
+
+if (apps.length === 0) {
+  console.log('No apps found in workspace')
+  return
+}
+
+// Process apps
+apps.forEach(app => {
+  // ...
+})
+```
+
+### 4. Use Descriptive Filters
+
+```javascript
+// Good: Clear intent
+const devApps = apps.filter(app => app.url)
+const myApps = apps.filter(app => app.isOwner)
+const sharedApps = apps.filter(app =>
+  app.members.some(m => m.startsWith('network_'))
+)
+
+// Not as clear:
+const filtered = apps.filter(a => a.url && a.isOwner)
+```
+
+### 5. Validate Permissions Before Actions
+
+```javascript
+const apps = list_apps()
+const app = apps.find(a => a.name === 'Target App')
+
+// Check before updating
+if (app.canEdit) {
+  update_app({ appId: app._id, name: 'New Name' })
+} else {
+  console.error('No permission to edit this app')
+}
+
+// Check before deleting
+if (app.canDelete) {
+  remove_app({ appId: app._id })
+} else {
+  console.error('No permission to delete this app')
+}
+```
+
+### 6. Use Type Checks
+
+```javascript
+const apps = list_apps()
+
+apps.forEach(app => {
+  // Check properties exist
+  const name = app.name || 'Unnamed'
+  const description = app.description || 'No description'
+  const config = app.config || {}
+
+  console.log(`${name}: ${description}`)
+})
+```
+
+### 7. Document App Discovery Logic
+
+```javascript
+// Clear documentation of search logic
+function findProductionApp(baseName) {
+  const apps = list_apps()
+
+  // Look for app without (Dev) suffix
+  return apps.find(app =>
+    app.name === baseName &&
+    !app.url  // Published apps have no URL
+  )
+}
+
+const prodApp = findProductionApp('Task Manager')
+```
+
+## Troubleshooting
+
+### No Apps Returned
+
+**Causes:**
+1. Wrong workspace
+2. No apps created yet
+3. No permission to view apps
+
+**Solutions:**
+
+```javascript
+// 1. Check current workspace
+const workspace = get_current_workspace()
+console.log('Current workspace:', workspace.name)
+
+// 2. Try listing
+const apps = list_apps()
+console.log('Apps found:', apps.length)
+
+// 3. Create test app if needed
+if (apps.length === 0) {
+  console.log('No apps found - create one')
+  create_app({
+    name: 'Test App',
+    url: 'http://localhost:3000'
+  })
+}
+```
+
+### App Not in List
+
+**Causes:**
+1. App in different workspace
+2. No permission to view app
+3. App recently deleted
+4. Cache not refreshed
+
+**Solutions:**
+
+```javascript
+// 1. List apps
+const apps = list_apps()
+
+// 2. Search thoroughly
+const found = apps.find(a =>
+  a.name.toLowerCase().includes('search term') ||
+  a._id === 'app-id'
+)
+
+// 3. Check workspace
+if (!found) {
+  console.log('App not found in current workspace')
+  console.log('Current workspace:', get_current_workspace().name)
+}
+```
+
+### Duplicate App Names
+
+**Problem:** Multiple apps with same name.
+
+**Solution:**
+
+```javascript
+const apps = list_apps()
+
+// Find duplicates
+const names = {}
+apps.forEach(app => {
+  if (!names[app.name]) names[app.name] = []
+  names[app.name].push(app)
+})
+
+// Show duplicates
+Object.entries(names).forEach(([name, apps]) => {
+  if (apps.length > 1) {
+    console.log(`\nDuplicate name: ${name}`)
+    apps.forEach(app => {
+      console.log(`- ID: ${app._id}`)
+      console.log(`  Type: ${app.url ? 'Dev' : 'Published'}`)
+      console.log(`  Created: ${app.created}`)
+    })
+  }
+})
+```
+
+### Cannot Identify Dev vs Prod
+
+**Problem:** Both apps have similar names.
+
+**Solution:**
+
+```javascript
+const apps = list_apps()
+
+// Clear identification
+apps.forEach(app => {
+  const type = app.url ? 'DEVELOPMENT' : 'PUBLISHED'
+  const url = app.url || 'Hailer-hosted'
+
+  console.log(`${app.name}:`)
+  console.log(`  Type: ${type}`)
+  console.log(`  URL: ${url}`)
+  console.log(`  ID: ${app._id}`)
+  console.log()
+})
+```
+
+## Integration with Other Tools
+
+### With create_app
+
+Create and verify:
+
+```javascript
+// 1. Create app
+const newApp = create_app({
+  name: 'My New App',
+  url: 'http://localhost:3000'
+})
+
+// 2. Verify it appears in list
+const apps = list_apps()
+const found = apps.find(a => a._id === newApp.appId)
+
+console.log('Verified:', !!found)
+```
+
+### With update_app
+
+Find and update:
+
+```javascript
+// 1. Find app
+const apps = list_apps()
+const app = apps.find(a => a.name === 'Old Name')
+
+// 2. Update app
+if (app) {
+  update_app({
+    appId: app._id,
+    name: 'New Name',
+    description: 'Updated description'
+  })
+}
+```
+
+### With remove_app
+
+Find and remove:
+
+```javascript
+// 1. List apps
+const apps = list_apps()
+
+// 2. Find test apps
+const testApps = apps.filter(a =>
+  a.name.includes('Test') && a.isOwner
+)
+
+// 3. Remove each
+testApps.forEach(app => {
+  console.log('Removing:', app.name)
+  remove_app({ appId: app._id })
+})
+```
+
+### With add_app_member
+
+Find and share:
+
+```javascript
+// 1. Find app
+const apps = list_apps()
+const app = apps.find(a => a.name === 'Dashboard')
+
+// 2. Share with workspace
+if (app && app.isOwner) {
+  add_app_member({
+    appId: app._id,
+    member: 'network_workspace-id'
+  })
+}
+```
+
+## Summary
+
+**Key Takeaways:**
+1. 📋 **Lists all apps** - In current or specified workspace
+2. 🔍 **Filterable** - Find by name, type, owner, config
+3. ℹ️ **Rich metadata** - Name, type, config, permissions
+4. 🔑 **Returns IDs** - Use for other operations
+5. 🏷️ **Shows types** - Dev (has URL) vs Published (no URL)
+6. 🔒 **Access info** - Shows what you can do with each app
+7. 📊 **No limits** - Returns all apps you have access to
+
+**Quick Decision Tree:**
+
+```
+Need app information?
+│
+├─ Find app ID? → list_apps, filter by name
+├─ Count apps? → list_apps, check length
+├─ Find dev apps? → filter by app.url
+├─ Find your apps? → filter by app.isOwner
+├─ Audit workspace? → list_apps, iterate all
+└─ Before operations? → list_apps, verify exists
+```
+
+## Additional Resources
+
+- See `create-app-skill` for creating apps
+- See `update-app-skill` for modifying apps
+- See `remove-app-skill` for deleting apps
+- See `add-app-member-skill` for sharing apps
+- See `remove-app-member-skill` for revoking access
+- See `app-api` skill for comprehensive App API documentation