@hailer/mcp 0.0.6 → 0.1.1

package/.claude/hooks/src-edit-guard.cjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * Claude Code PreToolUse Hook - Source Code Edit Guard
+ *
+ * Blocks direct edits to src/ directory files.
+ * Forces the main agent to spawn subagents for code changes.
+ * This saves context in the main agent for orchestration.
+ *
+ * Edits are ONLY allowed when:
+ * - Running inside a subagent (builder mode active)
+ * - File is outside src/ directory
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// UNIFIED: Use same builder mode file as app-edit-guard.cjs
+const BUILDER_MODE_FILE = '/tmp/.claude-builder-agent-active';
+
+// Read hook input from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    processHook(data);
+  } catch (e) {
+    // Invalid JSON - allow to avoid blocking legitimate operations
+    outputAllow();
+  }
+});
+
+function outputAllow() {
+  console.log(JSON.stringify({ decision: 'allow' }));
+  process.exit(0);
+}
+
+function outputBlock(message) {
+  console.log(JSON.stringify({
+    decision: 'block',
+    reason: message
+  }));
+  process.exit(0);
+}
+
+/**
+ * Check if builder mode is active (subagent editing)
+ */
+function isBuilderModeActive() {
+  try {
+    return fs.existsSync(BUILDER_MODE_FILE);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Enable builder mode
+ */
+function enableBuilderMode() {
+  fs.writeFileSync(BUILDER_MODE_FILE, JSON.stringify({
+    enabledAt: new Date().toISOString(),
+    pid: process.pid
+  }));
+}
+
+/**
+ * Disable builder mode
+ */
+function disableBuilderMode() {
+  if (fs.existsSync(BUILDER_MODE_FILE)) {
+    fs.unlinkSync(BUILDER_MODE_FILE);
+    return true;
+  }
+  return false;
+}
+
+function processHook(data) {
+  const { tool_name, tool_input } = data;
+
+  // Only guard Write and Edit tools
+  if (tool_name !== 'Write' && tool_name !== 'Edit') {
+    outputAllow();
+    return;
+  }
+
+  const filePath = tool_input?.file_path;
+  if (!filePath) {
+    outputAllow();
+    return;
+  }
+
+  // Normalize and get relative path
+  const normalizedPath = path.resolve(filePath);
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const relativePath = path.relative(projectRoot, normalizedPath);
+
+  // Check if file is in src/ directory
+  const isInSrc = relativePath.startsWith('src/') || relativePath.startsWith('src\\');
+
+  if (!isInSrc) {
+    // Not in src/ directory - allow
+    outputAllow();
+    return;
+  }
+
+  // Check if builder mode is active - ALLOW
+  if (isBuilderModeActive()) {
+    outputAllow();
+    return;
+  }
+
+  // BLOCK with helpful message
+  outputBlock(`
+🚫 BLOCKED: Direct edit to source file
+
+File: ${relativePath}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+WHY: Use a subagent to save your context for orchestration
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+TO PROCEED: Spawn a general-purpose agent with detailed instructions:
+
+Task({
+  subagent_type: "general-purpose",
+  description: "Fix issue #XX",
+  prompt: \`
+    [Detailed instructions for the change]
+
+    File to modify: ${relativePath}
+
+    [Explain what to change and why]
+  \`
+})
+
+The agent will:
+1. Make the code changes
+2. Verify the build passes
+3. Report back results
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OR: Enable builder mode temporarily (if you need to edit directly)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Bash: node .claude/hooks/src-edit-guard.cjs --on
+[Make your edits]
+Bash: node .claude/hooks/src-edit-guard.cjs --off
+`);
+}
+
+// CLI: Enable builder mode
+if (process.argv[2] === '--on') {
+  enableBuilderMode();
+  console.log('🔧 Builder mode ENABLED - src/ edits now allowed');
+  process.exit(0);
+}
+
+// CLI: Disable builder mode
+if (process.argv[2] === '--off') {
+  if (disableBuilderMode()) {
+    console.log('🔒 Builder mode DISABLED - src/ edits blocked again');
+  } else {
+    console.log('ℹ️  Builder mode was not active');
+  }
+  process.exit(0);
+}
+
+// CLI: Check status
+if (process.argv[2] === '--status') {
+  if (isBuilderModeActive()) {
+    const data = JSON.parse(fs.readFileSync(BUILDER_MODE_FILE, 'utf8'));
+    console.log(`🔧 Builder mode is ACTIVE (enabled at ${data.enabledAt})`);
+  } else {
+    console.log('🔒 Builder mode is OFF - src/ edits are blocked');
+  }
+  process.exit(0);
+}
+
+// CLI: Help
+if (process.argv[2] === '--help' || process.argv[2] === '-h') {
+  console.log(`
+Source Code Edit Guard - Blocks direct edits to src/ directory
+
+Usage:
+  node src-edit-guard.cjs --on       Enable builder mode (allow edits)
+  node src-edit-guard.cjs --off      Disable builder mode (block edits)
+  node src-edit-guard.cjs --status   Check current mode
+  node src-edit-guard.cjs --help     Show this help
+
+UNIFIED SYSTEM: This hook uses the same builder mode file as app-edit-guard.cjs.
+Enabling builder mode here also enables it for Hailer app edits, and vice versa.
+
+Preferred commands (via app-edit-guard.cjs):
+  node app-edit-guard.cjs --agent-on    Enable global builder mode
+  node app-edit-guard.cjs --agent-off   Disable global builder mode
+
+As a hook:
+  Reads JSON from stdin with tool_name and tool_input
+  Outputs JSON with decision: "allow" or "block"
+
+Purpose:
+  Forces the main Claude agent to spawn subagents for code changes.
+  This saves context in the main agent for orchestration tasks.
+`);
+  process.exit(0);
+}

package/.claude/settings.json

@@ -14,8 +14,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/prompt-skill-loader.cjs\"",
-            "timeout": 15
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/interactive-mode.cjs\"",
+            "timeout": 5
           }
         ]
       }
@@ -28,6 +28,11 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/sdk-delete-guard.cjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/mcp-server-guard.cjs\"",
+            "timeout": 5
           }
         ]
       },
@@ -40,6 +45,36 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/app-edit-guard.cjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/src-edit-guard.cjs\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/app-edit-guard.cjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/src-edit-guard.cjs\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -52,6 +87,16 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/agent-failure-detector.cjs\"",
+            "timeout": 5
+          }
+        ]
       }
     ]
   }

package/.claude/skills/insight-join-patterns/SKILL.md

@@ -0,0 +1,209 @@
+# Insight JOIN Patterns
+
+## Pattern
+When joining workflows with ActivityLink fields in Hailer insights, you must:
+1. Include `_id` meta field in BOTH source definitions
+2. Join ON the activitylink field value equals target _id
+3. Use the activitylink fieldId (NOT the key) for the JOIN condition
+
+## Critical Rules
+
+**Always Required:**
+- Both workflows need `{ name: 'id', meta: '_id' }` in their fields array
+- JOIN condition: `source1.activityLinkFieldName = source2.id`
+- Use LEFT JOIN for optional relationships (activitylink can be null)
+- Use INNER JOIN only when relationship must exist
+
+## Correct Examples
+
+### Basic ActivityLink JOIN
+```javascript
+// Players workflow has "club" field (activitylink to Clubs workflow)
+{
+  sources: [
+    {
+      name: 'p',
+      workflowId: '68446dc05b30685f67c6fcd4',
+      fields: [
+        { name: 'player_name', meta: 'name' },
+        { name: 'id', meta: '_id' },              // Required!
+        { name: 'club', fieldId: '684d5e45...' }  // ActivityLink field
+      ]
+    },
+    {
+      name: 'c',
+      workflowId: '691ea936ccb6bdeebc0cbf77',
+      fields: [
+        { name: 'club_name', meta: 'name' },
+        { name: 'id', meta: '_id' }               // Required!
+      ]
+    }
+  ],
+  query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.id'
+}
+```
+
+### Three-Way JOIN (Tasks -> Topics -> Projects)
+```javascript
+{
+  sources: [
+    {
+      name: 't',
+      workflowId: 'tasks-workflow-id',
+      fields: [
+        { name: 'task_name', meta: 'name' },
+        { name: 'id', meta: '_id' },
+        { name: 'topic', fieldId: 'topic-field-id' }  // Links to Topics
+      ]
+    },
+    {
+      name: 'top',
+      workflowId: 'topics-workflow-id',
+      fields: [
+        { name: 'topic_name', meta: 'name' },
+        { name: 'id', meta: '_id' },
+        { name: 'project', fieldId: 'project-field-id' }  // Links to Projects
+      ]
+    },
+    {
+      name: 'p',
+      workflowId: 'projects-workflow-id',
+      fields: [
+        { name: 'project_name', meta: 'name' },
+        { name: 'id', meta: '_id' }
+      ]
+    }
+  ],
+  query: `
+    SELECT
+      t.task_name,
+      top.topic_name,
+      p.project_name
+    FROM t
+    LEFT JOIN top ON t.topic = top.id
+    LEFT JOIN p ON top.project = p.id
+  `
+}
+```
+
+### Aggregation with JOIN
+```javascript
+{
+  sources: [
+    {
+      name: 'matches',
+      workflowId: 'matches-workflow-id',
+      fields: [
+        { name: 'match_date', fieldId: 'date-field-id' },
+        { name: 'id', meta: '_id' },
+        { name: 'home_team', fieldId: 'home-team-field-id' }
+      ]
+    },
+    {
+      name: 'teams',
+      workflowId: 'teams-workflow-id',
+      fields: [
+        { name: 'team_name', meta: 'name' },
+        { name: 'id', meta: '_id' }
+      ]
+    }
+  ],
+  query: `
+    SELECT
+      teams.team_name,
+      COUNT(*) as match_count
+    FROM matches
+    LEFT JOIN teams ON matches.home_team = teams.id
+    GROUP BY teams.team_name
+  `
+}
+```
+
+## Wrong Examples
+
+### Missing _id Field
+```javascript
+// ❌ WRONG - Missing _id in clubs source
+{
+  sources: [
+    {
+      name: 'p',
+      workflowId: 'players-id',
+      fields: [
+        { name: 'player_name', meta: 'name' },
+        { name: 'id', meta: '_id' },
+        { name: 'club', fieldId: 'club-field-id' }
+      ]
+    },
+    {
+      name: 'c',
+      workflowId: 'clubs-id',
+      fields: [
+        { name: 'club_name', meta: 'name' }
+        // Missing: { name: 'id', meta: '_id' }
+      ]
+    }
+  ],
+  query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.id'
+}
+// Error: "no such column: c.id"
+```
+
+### Using Key Instead of FieldId
+```javascript
+// ❌ WRONG - Using field key instead of fieldId
+{
+  sources: [
+    {
+      name: 'p',
+      workflowId: 'players-id',
+      fields: [
+        { name: 'player_name', meta: 'name' },
+        { name: 'id', meta: '_id' },
+        { name: 'club', key: 'club' }  // Wrong! Use fieldId
+      ]
+    }
+  ]
+}
+```
+
+### Wrong JOIN Syntax
+```javascript
+// ❌ WRONG - Trying to join on name instead of id
+query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.club_name'
+
+// ❌ WRONG - Using field key in JOIN instead of column name
+query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.clubId = c.id'
+// (Should use column name from sources definition: p.club = c.id)
+```
+
+## Troubleshooting
+
+**Error: "no such column: c.id"**
+- Missing `{ name: 'id', meta: '_id' }` in target workflow source
+
+**Error: "no such column: p.club"**
+- ActivityLink field not included in source fields array
+- Check you used correct fieldId from `get_workflow_schema`
+
+**NULL results for joined data**
+- ActivityLink field is empty/null for some activities (expected with LEFT JOIN)
+- Use INNER JOIN if you only want activities with relationships
+
+## Workflow
+
+1. Get schema: `get_workflow_schema({ workflowId, phaseId })`
+2. Find ActivityLink field ID and target workflow ID
+3. Build sources with BOTH _id fields
+4. Preview query: `preview_insight({ sources, query })`
+5. Fix errors, re-preview
+6. Create insight when preview succeeds
+
+## Quick Checklist
+
+Before creating an insight with JOINs:
+- [ ] Both workflow sources include `{ name: 'id', meta: '_id' }`
+- [ ] ActivityLink field uses `fieldId` (NOT `key`)
+- [ ] JOIN condition uses column names from sources (e.g., `p.club = c.id`)
+- [ ] Using LEFT JOIN (unless relationship required)
+- [ ] Tested with `preview_insight` first

package/.env.example

@@ -1,6 +1,18 @@
 # Hailer MCP Server Configuration
 # Copy this file to .env.local and update with your own credentials
 
+# ==============================================
+# ENVIRONMENT
+# ==============================================
+
+# NODE_ENV controls multiple behaviors:
+# - 'development': TLS bypass for local URLs, console logging, file tracking
+# - 'production': Strict TLS, OpenTelemetry logging, no file tracking
+#
+# Set to 'development' when using local Hailer cluster (*.local.gd)
+# Leave unset or 'production' for api.hailer.com
+# NODE_ENV=development
+
 # ==============================================
 # MCP SERVER CONFIGURATION (for external clients)
 # ==============================================
@@ -78,4 +90,4 @@ ADAPTIVE_DOCUMENTATION_BOT_ENABLED=false
 ADAPTIVE_AUTO_UPDATE=false
 ADAPTIVE_UPDATE_INTERVAL=60000
 ADAPTIVE_MIN_ERROR_COUNT=3
-ADAPTIVE_SKILL_GENERATION=false
+ADAPTIVE_SKILL_GENERATION=false

package/CLAUDE.md

@@ -0,0 +1,135 @@
+# Hailer SDK
+
+MCP tools for Hailer workspaces: workflows, activities, insights, and apps.
+
+**Core features:**
+- MCP Tools: Direct Hailer API access
+- Local Config: Synced workspace in `workspace/` directory
+- Type Generation: TypeScript enums for IDs
+
+---
+
+# Default Agent System (Customizable)
+
+Ships with pre-configured agents. **These are defaults - modify, replace, or remove them.**
+
+| Action | How |
+|--------|-----|
+| Create custom | `agent-builder` or add to `.claude/agents/` |
+| Modify defaults | Edit `.claude/agents/*.md` |
+| Disable agents | Move to `docs/agents/`, update this file |
+
+## Orchestrator Role
+
+You route requests to agents. Do trivial things directly; delegate everything else.
+
+**Do directly:** Answer from context, summarize results, opinions, confirmations
+**Delegate:** Any file read, API call, creation, update, or complex reasoning
+
+## Default Agents
+
+> Customize by editing `.claude/agents/` files.
+
+| Pattern | Agent | Model |
+|---------|-------|-------|
+| Read data/schema | `kenji` | Haiku |
+| Activity CRUD | `dmitri` | Haiku |
+| Discussions/chat | `yevgeni` | Haiku |
+| Config audit | `bjorn` | Haiku |
+| Workspace config | `helga` | Sonnet |
+| SQL insights | `viktor` | Sonnet |
+| Function fields | `alejandro` | Sonnet |
+| MCP tools | `gunther` | Sonnet |
+| Hailer apps | `giuseppe` | Sonnet |
+| Code review | `svetlana` | Sonnet |
+| New agents | `agent-builder` | Sonnet |
+| Create/update skills, improve agents | `ada` | Sonnet |
+| Document templates | `ingrid` | Sonnet |
+
+## Delegation Protocol
+
+```
+Task(subagent_type="agent-name", prompt="JSON task spec", model="haiku")
+```
+
+**Task spec:**
+```json
+{ "task": "action", "context": { "workflow_id": "...", "field_ids": {} }, "requirements": {}, "output": [] }
+```
+
+**Response (JSON only, no prose):**
+```json
+{ "status": "success", "result": {}, "summary": "max 50 chars" }
+```
+
+**Critical:** Get IDs first (via kenji), then pass to execution agents.
+
+---
+
+# Local-First Principle
+
+**Check local files BEFORE API calls.**
+
+After `npm run pull`:
+```
+workspace/
+├── workflows.ts          # Workflow IDs, names
+├── enums.ts              # Type-safe ID constants
+├── teams.ts, groups.ts   # Team/group definitions
+└── [Workflow]_[id]/
+    ├── fields.ts         # Field definitions
+    └── phases.ts         # Phase definitions
+```
+
+| Use Local | Use API |
+|-----------|---------|
+| Workflow/field/phase IDs | Activity data (live) |
+| Field types, labels, options | Activity counts |
+| Team/group definitions | Discussion messages |
+
+**Refresh:** `npm run pull` (after changes, start of session, before building apps)
+
+---
+
+# Safety Rules
+
+**Protected (hooks confirm):** `npm run push`, `*-push`, `*-sync`
+**Safe:** `npm run pull`, `npm run generate`
+
+---
+
+# Directory Structure
+
+```
+workspace/              # Local config (check FIRST)
+.claude/
+  agents/               # Agent definitions
+  hooks/                # Safety hooks
+  skills/               # Documentation
+  commands/             # Slash commands
+  settings.json         # Permissions
+```
+
+---
+
+# Customization
+
+## Create Agent
+```yaml
+# .claude/agents/your-agent.md
+---
+name: your-agent
+description: What it does.\n\n<example>...</example>
+model: haiku
+---
+[Agent body with responsibilities]
+```
+
+## Modify Agents
+Edit `.claude/agents/*.md` - change personality, responsibilities, model, tools.
+
+## Disable Agents
+Move from `.claude/agents/` to `docs/agents/`, remove from delegation table.
+
+## Without Agents
+Use MCP tools directly: `list_workflows`, `create_activity`, `get_workflow_schema`, etc.

package/dist/app.js

@@ -9,7 +9,6 @@ const user_1 = require("./mcp/tools/user");
 const workflow_1 = require("./mcp/tools/workflow");
 const insight_1 = require("./mcp/tools/insight");
 const app_1 = require("./mcp/tools/app");
-const skill_1 = require("./mcp/tools/skill");
 const core = new core_1.Core();
 console.log('Registering tools...');
 console.log(`Nuclear tools ${config_1.environment.ENABLE_NUCLEAR_TOOLS ? 'ENABLED' : 'DISABLED'} (set ENABLE_NUCLEAR_TOOLS=true in .env.local to enable)`);
@@ -47,6 +46,7 @@ core.addTool(workflow_1.countActivitiesTool);
 core.addTool(insight_1.createInsightTool);
 core.addTool(insight_1.previewInsightTool);
 core.addTool(insight_1.getInsightDataTool);
+core.addTool(insight_1.updateInsightTool);
 if (config_1.environment.ENABLE_NUCLEAR_TOOLS) {
     core.addTool(insight_1.removeInsightTool);
 }
@@ -69,8 +69,9 @@ 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);
+// Marketplace app tools
+core.addTool(app_1.publishAppTool);
+core.addTool(app_1.installMarketplaceAppTool);
 console.log('All tools registered successfully!');
 // Start the application
 core.start().catch((error) => {

package/dist/client/adaptive-documentation-bot.d.ts

@@ -15,7 +15,6 @@ import { ToolCallError, ErrorPattern, AdaptiveBotConfig } from './adaptive-docum
 export declare class AdaptiveDocumentationBot {
     private logParser;
     private descriptionUpdater;
-    private skillGenerator;
     private llmCaller;
     private config;
     private errorPatterns;
@@ -83,7 +82,6 @@ export declare class AdaptiveDocumentationBot {
         monitoring: boolean;
         errorPatterns: number;
         improvements: any;
-        skills: any;
     };
     /**
      * Get error patterns for a specific tool