@hailer/mcp 1.2.1 → 2.0.0-beta.3

package/.claude/commands/onboard-squad.md

@@ -1,130 +0,0 @@
----
-description: Bootstrap a new Hailer project end-to-end
-argument-hint: "project description or PRD path"
-allowed-tools: Task, Bash, Read
----
-# Onboard Squad
-
-Sequential pipeline: Create workspace infrastructure, scaffold the app, and verify everything is wired correctly.
-
-**Roles:**
-1. **Workflow Config** - Workflow configuration (create workflows, fields, phases, teams, groups)
-2. **Function Fields** - Calculated fields and nameFunction
-3. **App Builder** - Scaffold first app with basic CRUD interface
-4. **Config Auditor** - Audit configuration accuracy and field references
-
-**Goal:** $ARGUMENTS
-
-## Protocol
-
-### Step 1: Parse Requirements
-
-Parse `$ARGUMENTS` to determine input type:
-
-- **If it's a file path** (e.g., `docs/prd-onboarding.md`): Read it for requirements
-- **Otherwise:** Use it as a project description
-
-If `$ARGUMENTS` is a file path, read it first before proceeding to Workflow Config.
-
-### Step 2: Workflow Config
-
-Spawn a workflow config agent to create workspace infrastructure:
-
-```
-Task(prompt="Load sdk-ws-config-skill for workspace setup.\n\nBootstrap a new Hailer project: $ARGUMENTS\n\nCreate: workflows (at least 1), fields for each workflow, phases, teams, and groups as needed.")
-```
-
-Wait for result. If the agent returns `"status": "ready_to_push"`:
-- Run the push commands provided (e.g., `npm run fields-push:force`)
-- Then run `npm run pull` to refresh local workspace with new IDs
-- **Important:** Workflow config ALWAYS spawns a function fields agent for nameFunction. Check if the result indicates it was spawned and created nameFunction. If yes, function fields work is done - skip to Step 3.
-
-### Step 3: Function Fields - Conditional
-
-Only spawn if workflow config indicates additional function fields are needed beyond what was created by the auto-spawn.
-
-If needed, spawn a function fields agent:
-
-```
-Task(prompt="Load sdk-function-fields and sdk-ws-config-skill skills for creating calculated fields.\n\nCreate additional function fields for workflows created in: [INSERT WORKFLOW CONFIG GOAL].\n\nWorkflow config created these workflows: [SUMMARIZE WORKFLOW CONFIG RESULT - workflow names, IDs, field counts].\n\nFunction fields already created by workflow config: [FROM WORKFLOW CONFIG RESULT].")
-```
-
-Wait for result. If `"status": "ready_to_push"`:
-- Run the push commands
-- Run `npm run pull` to refresh workspace
-
-### Step 4: App Scaffold
-
-Spawn an app builder to build the first app using the new workspace:
-
-```
-Task(prompt="Load hailer-app-builder and hailer-design-system skills for app development.\n\nScaffold the first Hailer app for this new project: $ARGUMENTS\n\nWorkspace created by workflow config: [SUMMARIZE WORKFLOW CONFIG RESULT - workflow names, IDs, field counts]. You: read workspace/ directly to discover exact field IDs, types, and team configurations. Do not guess IDs.\n\nBuild a basic CRUD interface using @hailer/app-sdk and Chakra UI. Start with the primary workflow. Use the Hailer Design System.\n\nNote: Assume Local Dev app exists (orchestrator checks this before spawning you). Build for local development at http://localhost:3000.")
-```
-
-Wait for result. If the builder returns `"status": "ready_to_push"`:
-- Run the push commands
-
-### Step 5: Config Audit
-
-Spawn a config auditor to verify everything is configured correctly:
-
-```
-Task(prompt="Audit this new Hailer project setup:\n\n1. Verify CLAUDE.md accuracy (check that project type detection works)\n2. Verify workspace configuration: workflows, fields, phases, teams all match workspace/ files\n3. Verify field references in the new app match workspace/ field definitions\n4. Check for missing imports, incorrect IDs, or type mismatches\n5. Verify that nameFunction is set on the primary workflow\n\nProject goal: $ARGUMENTS\n\nReport any misconfigurations. If iteration <= 1, recommend fixes to the orchestrator.")
-```
-
-**Loop Control:**
-- If config auditor finds no critical issues: proceed to Step 6 (report)
-- If config auditor finds issues AND `iteration <= 1`:
-  - Increment `iteration`
-  - Determine which agent to fix it (usually Workflow Config or App Builder)
-  - Run appropriate agent with the issues to fix
-  - Return to Step 5 (config audit re-checks)
-- If config auditor finds issues AND `iteration > 1`: escalate to user in Step 6
-
-### Step 6: Report
-
-```markdown
-## Onboard Squad Complete
-
-**Project Goal:** $ARGUMENTS
-
-### Workspace Setup
-- Workflows created: [list with IDs]
-- Fields created: [count]
-- Phases: [count]
-- Teams: [count]
-- Function fields auto-spawn: [nameFunction created? Y/N]
-
-### Function Fields
-- Additional function fields created: [list or "None needed"]
-- Skipped: [reason if skipped]
-
-### App Scaffold
-- App path: [path to new app]
-- Build status: Pass/Fail
-- Files created: [count/list]
-- Local dev setup: [check local dev app name]
-
-### Config Audit
-- Critical issues found: [count] or "None"
-- Status: VERIFIED / NEEDS FIXES (if iteration > 1, see below)
-
-[If iteration > 1 - escalated:]
-### Remaining Issues
-[List issues config auditor found that weren't resolved in 1 fix iteration]
-- Manual fixes recommended: [hints]
-
-### Next Steps
-1. Run `npm run dev` to test the app locally
-2. Ensure "Local Dev" app exists in Hailer workspace
-3. Test the app inside Hailer iframe at http://localhost:3000
-4. Run `npm run pull` to ensure workspace/ is fully up to date
-```
-
-## Notes
-
-- Each agent in the pipeline needs IDs from the previous step. Always `npm run pull` between Workflow Config→Function Fields→App Builder to refresh local workspace.
-- Workflow config auto-spawns function fields agent for nameFunction. Check the result - only spawn function fields separately in Step 3 if additional function fields are needed.
-- App builder needs real workflow and field IDs from workspace/ - always read the files and paste actual IDs, never let it guess.
-- Config auditor's audit is the quality gate. If issues are found and you've iterated once, escalate remaining issues to the user rather than looping infinitely.
-- Set `iteration = 1` at the start. Increment after each config audit if fixes are attempted.

package/.claude/commands/swarm.md

@@ -1,210 +0,0 @@
----
-description: Orchestrator-driven parallel swarm for large-scale tasks
-argument-hint: "description of what to do across many items"
-allowed-tools: Task, Bash, Read, Glob
----
-
-# Swarm
-
-Orchestrator-driven parallel execution: analyze the task, discover work items, pick agents, split into chunks, dispatch workers, aggregate results.
-
-**Goal:** $ARGUMENTS
-
-## Protocol
-
-### Step 1: Analyze the Task
-
-Read `$ARGUMENTS` and determine:
-
-- **What needs to be done?** (review, edit, check, migrate, update, clean up)
-- **What are the work items?** (files, activities, workflows, agents, skills, configs)
-- **What scope?** (explicit path/glob from user, or infer from task description)
-
-If the scope is unclear, use Glob or Bash to discover items:
-
-```
-# Files
-Glob("src/**/*.ts")
-Glob(".claude/agents/*.md")
-Glob("workspace/*/fields.ts")
-
-# Activities (use data reader to count/list)
-Task(prompt="Count and list activity IDs for [workflow]")
-```
-
-If fewer than 5 items are discovered, **abort swarm** and suggest running a regular squad or single agent instead. Swarm is for scale.
-
-### Step 2: Pick Agent(s)
-
-Based on the task type, select the right agent(s):
-
-| Task Type | Role | Examples |
-|-----------|-------|---------|
-| Code review, security audit | **Code Reviewer** | "review for bugs", "security check", "find vulnerabilities" |
-| Dead code, unused imports, type errors | **Code Inspector** | "find dead code", "check types", "unused imports" |
-| Small edits, string replacements, rule additions | **Code Fixer** | "add header to each file", "replace X with Y", "update rule" |
-| Code cleanup, simplification | **Code Simplifier** | "clean up", "simplify", "refactor for clarity" |
-| Config audit, structure validation | **Config Auditor** | "check config", "validate structure", "audit settings" |
-| Data state checks, field validation | **Data Reader** | "check all activities", "verify field values", "find missing data" |
-| Query patterns, data analysis | **Data Analyzer** | "analyze patterns", "find anomalies across workflows" |
-| Activity updates, bulk mutations | **Activity Writer** | "update all activities", "move to phase", "set field values" |
-
-**Multi-agent swarms:** If the task spans multiple domains, assign different agent types to different items. For example, "clean up the project" might use Code Inspector for `.ts` files, Config Auditor for config files, and Code Simplifier for app components.
-
-### Step 3: Calculate Workers
-
-```
-items_count = total discovered items
-items_per_worker = 10 (default)
-max_workers = 5
-
-worker_count = min(ceil(items_count / items_per_worker), max_workers)
-```
-
-Split items into `worker_count` chunks. Try to keep chunks roughly equal size.
-
-For multi-agent swarms, group items by agent type first, then chunk within each type.
-
-### Step 4: Dispatch Workers
-
-Launch all workers in parallel using multiple Task tool calls in a single message. All workers run in background (`run_in_background: true`).
-
-Each worker gets:
-
-```
-Task(
-  run_in_background: true,
-  prompt="SWARM WORKER [N] of [TOTAL]
-
-TASK: [User's description from $ARGUMENTS]
-
-YOUR ITEMS ([count]):
-- [item 1]
-- [item 2]
-- [item 3]
-...
-
-Process each item and report results in this format:
-
-RESULTS:
-- [item]: [status] - [details]
-- [item]: [status] - [details]
-
-SUMMARY:
-- Processed: [count]
-- Passed: [count]
-- Issues found: [count]
-- Failed: [count]")
-```
-
-Tell the user:
-```
-Launched [worker_count] workers across [items_count] items.
-Running in background - what else do you want to work on?
-```
-
-### Step 5: Collect Results
-
-When workers complete (check via Read on output files or TaskOutput), aggregate all results.
-
-If any worker failed or timed out:
-- Report which items were in the failed worker's batch
-- Offer to retry just those items
-
-### Step 6: Report
-
-```markdown
-## Swarm Report
-
-### Task
-[User's description]
-
-### Execution
-- **Items:** [total count]
-- **Workers:** [worker count] x [role type(s)]
-- **Duration:** [time from dispatch to last worker completion]
-
----
-
-### Results by Worker
-
-#### Worker 1 ([role type]) - [X items]
-- [item]: [status] - [details]
-- [item]: [status] - [details]
-...
-
-#### Worker 2 ([role type]) - [X items]
-...
-
----
-
-### Aggregate Summary
-
-| Status | Count |
-|--------|-------|
-| Passed / Clean | X |
-| Issues Found | X |
-| Failed / Error | X |
-
-### Issues Found
-[Grouped and deduplicated list of all issues across all workers]
-
-1. **[item]**: [issue description]
-2. **[item]**: [issue description]
-...
-
-### Failed Items
-[If any workers failed, list their items for retry]
-
-### Next Steps
-- [Suggested follow-up based on results]
-- [If issues found: suggest /hotfix-squad or /review-squad to fix]
-- [If edits made: suggest /review-squad to verify]
-```
-
-## Options
-
-| Flag | Effect |
-|------|--------|
-| `--workers=N` | Override worker count (default: auto-calculated, max 5) |
-| `--dry-run` | Show what would be dispatched without actually running |
-| `--no-bg` | Run workers in foreground (wait for all to complete) |
-
-## Examples
-
-```
-# Review all source files for security
-/swarm "review all TypeScript files in src/ for security vulnerabilities"
-→ Discovers 47 .ts files, spawns 5 code reviewer workers
-
-# Bulk edit agent files
-/swarm "add a '## Version History' section to every agent file"
-→ Discovers 27 agent .md files, spawns 3 code fixer workers
-
-# Validate workspace configs
-/swarm "check all workflow field definitions for missing descriptions"
-→ Discovers 12 fields.ts files, spawns 2 data reader workers
-
-# Multi-agent cleanup
-/swarm "clean up the entire apps/ directory"
-→ Discovers 34 files: 20 .tsx → Code Simplifier workers, 8 .ts → Code Inspector workers, 6 configs → Config Auditor workers
-→ Spawns 5 workers across 3 roles
-
-# Data validation
-/swarm "verify all Customer activities have a valid email field"
-→ Data Reader counts 200 customers, spawns 5 data reader workers (40 each)
-
-# Dry run to preview
-/swarm "update all skills to use consistent headers" --dry-run
-→ Shows: "Would dispatch 4 code fixer workers across 32 skill files"
-```
-
-## Notes
-
-- Minimum 5 items to trigger swarm (below that, use a regular agent)
-- Default max 5 workers to avoid overwhelming the system
-- Workers run in background by default so user can keep working
-- Multi-agent swarms naturally emerge from the role-based routing logic
-- For write operations (Activity Writer, Code Fixer), consider running --dry-run first
-- Swarm vs Squad: Swarm is raw parallel execution without quality gates. Workers operate independently. Squads have convergence, synthesis, and loops. Use swarm for bulk independent items, squads for coordinated workflows.
-- Swarm + squad can combine: `/swarm "review src/"` finds issues, then user can run `/hotfix-squad` on results. This is a manual handoff - user confirms.

package/.claude/commands/tool-builder.md

@@ -1,39 +0,0 @@
----
-description: Activate tool-builder mode to implement a new MCP tool
----
-
-# Tool Builder Mode
-
-Loading `tool-builder` skill for MCP tool patterns...
-
-**What tool should I build?**
-
-Please provide:
-
-- **Tool Name**: `tool_name` (snake_case)
-- **Purpose**: What does it do?
-- **API Endpoint**: `v3.endpoint.method`
-- **Request Format**: `[arg1, arg2]`
-- **Response Format**: What the API returns
-- **Target File**: Which file in `src/mcp/tools/`?
-- **Tool Group**: READ | WRITE | PLAYGROUND
-
----
-
-**Example:**
-```
-Tool Name: list_insights
-Purpose: List all insights in workspace
-API Endpoint: v3.insight.list
-Request: [workspaceId]
-Response: { insights: [{_id, name, query, sources}] }
-Target File: insight.ts
-Tool Group: PLAYGROUND
-```
-
-I'll:
-1. Load tool-builder skill
-2. Read existing patterns in target file
-3. Implement the tool
-4. Register in src/app.ts
-5. Report what was created

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

@@ -1,280 +0,0 @@
----
-name: publish-hailer-app
-description: Guide for publishing Hailer apps to production
-version: 1.3.0
-triggers:
-  - publish app
-  - deploy app
-  - production app
----
-
-# Publish Hailer App Skill
-
-Guide for publishing Hailer apps to production using MCP tools.
-
-<warning>
-## ⚠️ Publishing Requires Explicit User Request
-
-**Default is local development** — scaffold creates a dev app at `http://localhost:3000` automatically.
-
-**Only use this skill when the user explicitly asks to publish or deploy to production.**
-
-Before publishing: validate manifest.json (see below), then `publish_hailer_app` (auto-updates URL to production).
-</warning>
-
-<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: 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 2: Publish
-
-```javascript
-publish_hailer_app({
-  projectDirectory: "/path/to/app"
-})
-```
-
-This does everything in one call:
-- **Auto-derives app name** from project directory (e.g., `upcoming-matches` → "Upcoming Matches")
-- **Auto-sets description** from `versionDescription` in manifest.json
-- **Auto-generates and uploads a colored icon** with initials (e.g., green "UM" circle)
-- **Auto-shares** with the entire workspace
-- Copies manifest.json into dist/
-- Creates .tgz with `package/` prefix (matches npm pack format)
-- Uploads to S3 via POST /app/publish
-- **Auto-updates app URL** to `https://apps.hailer.com/{workspaceId}/{appId}/`
-
-No manual `update_app` calls needed after publish — name, description, icon, and sharing are all automatic.
-
-### Step 3: 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 | Purpose |
-|------|-----|------------|---------|
-| Dev | `http://localhost:3000` | `scaffold_hailer_app` (reuses existing) | Local development, always stays at localhost |
-| Prod | `https://apps.hailer.com/{workspaceId}/{appId}/` | `publish_hailer_app` (auto-created) | Published production app |
-
-**Flow:**
-1. `scaffold_hailer_app` checks for existing dev app at localhost:3000 — reuses it instead of creating duplicates
-2. Dev app stays at localhost forever — it's your development slot
-3. When user says "publish": `publish_hailer_app` detects the dev app URL, auto-creates a NEW production app with:
-   - Name derived from project directory (e.g., `upcoming-matches` → "Upcoming Matches")
-   - Description from `versionDescription` in manifest.json
-   - Colored icon with initials (auto-generated, uploaded as public)
-   - Shared with entire workspace
-   - URL pointing to production CDN
-
-**No manual `update_app` or `create_app` needed.** The publish tool handles name, description, icon, sharing, and URL automatically.
-</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.
-
-**Marketplace apps:** If `manifest.json` contains a `targetId`, the publish automatically updates the marketplace listing version too. No separate `publish_app` call needed for version updates.
-</updating>
-
-<marketplace>
-## Marketplace Publishing
-
-**Two different things:**
-1. **App publish** (`publish_hailer_app`) — uploads files to CDN, updates app URL. If manifest has `targetId`, also updates the marketplace version.
-2. **Marketplace metadata** (`publish_app`) — updates title, description, icon, images on the marketplace listing. Does NOT upload app files.
-
-**First-time marketplace publish:**
-1. Publish app with `publish_hailer_app` — server returns a `targetId`, auto-saved to manifest
-2. Create marketplace listing with `publish_app` using `versionId` (= targetId from manifest)
-3. Note the `productId` returned — that's the marketplace listing ID (different from targetId)
-
-**Updating marketplace version:**
-Just run `publish_hailer_app` — if manifest has `targetId`, the marketplace version updates automatically.
-
-**Updating marketplace metadata (description, icon, images):**
-Use `publish_app` with `productId` (the marketplace listing ID, NOT the targetId).
-
-**Key IDs:**
-| ID | What | Where |
-|----|------|-------|
-| `appId` | The app itself | manifest.json `appId` |
-| `targetId` | Version entry for marketplace | manifest.json `targetId` |
-| `productId` | Marketplace listing | Returned by first `publish_app` call, find via `list_templates` |
-</marketplace>
-
-<sharing>
-## Sharing Apps
-
-Workspace sharing is automatic on first publish. For manual sharing:
-
-```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>
-
-<gotchas>
-## Gotchas
-
-**App icons MUST be uploaded with `isPublic: true`.**
-Files uploaded without this flag are private — the Hailer frontend can't load them and shows a broken/transparent image. The publish tool handles this automatically, but if you manually upload an icon via `upload_files`, always include `isPublic: true`:
-```javascript
-upload_files({ files: [{ path: "/tmp/icon.png", isPublic: true }] })
-```
-
-**SVG images don't work as app icons.**
-Hailer's backend image pipeline uses sharp for resizing and doesn't serve SVGs correctly. Always use PNG or JPEG.
-
-**Don't use SVG gradients in icon generation.**
-Sharp's `flatten()` with SVG `linearGradient` produces transparency. Use `sharp.create()` with solid RGB background + composite for text.
-</gotchas>
-
-<vite-config>
-## CRITICAL: Vite Base Path
-
-Vite apps MUST have `base: './'` in vite.config.ts for production deployment.
-
-```typescript
-// vite.config.ts
-export default defineConfig({
-  base: './',  // REQUIRED for production
-  // ... other config
-});
-```
-
-**Without this:**
-- Asset paths resolve to root domain instead of app folder
-- Production app returns 403/404 errors
-- Works in localhost but fails in production
-
-**Also verify:** The .tgz package must have files at `package/dist/` path structure.
-</vite-config>
-
-<cache-busting>
-## CRITICAL: Browser Cache for Published Apps
-
-Published Hailer apps serve stale versions from browser cache. Vite's hashed JS/CSS filenames handle asset cache-busting, but `index.html` itself needs no-cache headers.
-
-**Add these meta tags to `index.html` `<head>` before publishing:**
-
-```html
-<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate" />
-<meta http-equiv="Pragma" content="no-cache" />
-<meta http-equiv="Expires" content="0" />
-```
-
-**Without these:**
-- Users see old app version after publish
-- Hard refresh (Ctrl+Shift+R) works but users won't know to do it
-- Particularly bad for bug fix deploys where users expect changes immediately
-
-**Why meta tags not server headers?**
-Hailer apps are served from `apps.hailer.com` static hosting - we can't control server headers. Meta tags are the only client-side cache control available.
-</cache-busting>
-
-<checklist>
-## Pre-Publish Checklist
-
-- [ ] manifest.json `appId` is 24 chars (dev app ID is fine — publish auto-creates prod app)
-- [ ] manifest.json `version` is set (e.g., "1.0.0")
-- [ ] manifest.json `versionDescription` is set (not empty — also used as app description)
-- [ ] vite.config.ts has `base: './'`
-- [ ] index.html has no-cache meta tags (see cache-busting section)
-- [ ] node_modules exists (dependencies installed)
-- [ ] After publish: verify URL auto-updated to production format (check with `list_apps`)
-
-**Automatic on first publish** (no action needed): app name, description, colored icon, workspace sharing.
-</checklist>