@hailer/mcp 0.0.2 → 0.0.4

package/.claude/skills/SDK-ws-config-skill/SKILL.md

@@ -0,0 +1,435 @@
+---
+name: Workspace Configuration Management
+description: Complete guide to managing Hailer workspace configurations using ws-config commands - pull/push workflows, fields, phases, groups, teams, and insights
+---
+
+# `hailer-sdk ws-config`
+
+Manage workspace configuration - pull and push workflow configurations between Hailer and your local repository.
+
+**Alias:** `workspace-config`
+
+## Commands Overview
+
+| Command | Purpose | Creates | Deletes | Updates |
+|---------|---------|---------|---------|---------|
+| [`pull`](#pull) | Fetch workflows from Hailer | - | - | - |
+| [`push`](#push) | Sync all configurations | ✅ | ✅ | ✅ |
+| [`workflows push`](#workflows-push) | Update workflow configs only | ❌ | ❌ | ✅ |
+| [`workflows sync`](#workflows-sync) | Manage workflow lifecycle | ✅ | ✅ | ❌ |
+| [`phases push`](#phases-push) | Manage phase configs | ✅ | ✅ | ✅ |
+| [`fields push`](#fields-push) | Manage field configs | ✅ | ✅ | ✅ |
+| [`groups push`](#groups-push) | Manage group configs | ✅ | ✅ | ✅ |
+| [`teams push`](#teams-push) | Manage team configs | ✅ | ✅ | ✅ |
+| [`insights push`](#insights-push) | Manage insights configs | ✅ | ✅ | ✅ |
+
+## Common Options
+
+All subcommands support these options:
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--email <email>` | `-e` | Hailer account email |
+| `--password <password>` | `-p` | Hailer account password |
+| `--workspace <id>` | `-w` | Workspace ID |
+| `--verbose` | | Show detailed logging |
+
+---
+
+## `pull`
+
+Pull workflows from Hailer workspace to local files.
+
+### Usage
+
+```bash
+hailer-sdk ws-config pull -e <email> -p <password> -w <workspace-id>
+```
+
+### What it Does
+
+Fetches all workflows from your Hailer workspace and generates local TypeScript files:
+
+```
+workspace/
+├── workflows.ts                    # Registry of all workflows
+├── groups.ts                       # Group definitions
+├── teams.ts                        # Team definitions
+├── insights.ts                     # Insights configuration
+├── enums.ts                        # All enums (workflows, fields, phases, members)
+├── hailer.d.ts                     # Hailer SDK types
+└── WorkflowName_id/                # Individual workflow folders
+    ├── main.ts                     # Workflow configuration
+    ├── fields.ts                   # Field definitions
+    └── phases.ts                   # Phase definitions
+```
+
+### Generated Enums
+
+The `enums.ts` file includes:
+
+- **WorkflowIds** - All workflow IDs mapped to workflow names
+- **[Workflow]_FieldIds** - Field IDs for each workflow
+- **[Workflow]_PhaseIds** - Phase IDs for each workflow
+- **WorkspaceMembers** - Workspace member IDs mapped to user names
+- **WorkspaceTeams** - Workspace team IDs mapped to team names
+- **WorkspaceGroups** - Workspace group IDs mapped to group names
+- **HailerMembers** - All member types in Hailer ID format ex. user_${id}, team_${id}, group_${id}
+
+### ID Replacement
+
+The pull command automatically replaces hardcoded IDs with enum references:
+
+```typescript
+// Instead of:
+assignedTo: "681b0ef24d80238fd472cc19"
+
+// You get:
+assignedTo: WorkspaceMembers.Jari_Jarkov_c19
+```
+
+### Notes
+
+- Enum keys contain the sanitized names of fields, phases, workflows, members, teams, groups plus `_id` 3 characters suffixed to avoid name collisions
+- **Automatically cleans up old workflow directories** that no longer exist remotely
+- IDs are automatically replaced with readable enum references
+- Multiline strings are formatted with template literals
+
+### ⚠️ IMPORTANT: Workspace Directory Management
+
+**NEVER manually create or delete workflow directories** in the `workspace/` folder:
+
+```bash
+# ❌ WRONG - Don't manually delete
+rm -rf workspace/MyWorkflow_12345/
+
+# ✅ CORRECT - Let pull command manage it
+hailer-sdk ws-config pull
+```
+
+**The SDK automatically manages workflow directories:**
+- Creates new directories when workflows are added remotely
+- Removes directories when workflows are deleted remotely
+- Manual changes can cause sync conflicts
+
+**Proper workflow lifecycle:**
+1. **Create workflow**: Add to `workflows.ts`, create directory, then `workflows sync`
+2. **Delete workflow**: Use `workflows sync` or delete in Hailer UI, then `pull` to clean up locally
+
+---
+
+## `push`
+
+Push ALL local configurations to Hailer workspace (workflows + fields + phases).
+
+### Usage
+
+```bash
+hailer-sdk ws-config push -e <email> -p <password> -w <workspace-id>
+```
+
+### What it Does
+
+Syncs all local configurations with Hailer:
+
+1. **Workflows** - Updates workflow configurations
+2. **Fields** - Creates, updates, or deletes fields
+3. **Phases** - Creates, updates, or deletes phases
+
+### Important
+
+After pushing, **always pull** to sync your local repository:
+
+```bash
+hailer-sdk ws-config pull
+```
+
+### When to Use
+
+Use `push` when you've made changes to:
+- Workflow configurations in `main.ts`
+- Field definitions in `fields.ts`
+- Phase definitions in `phases.ts`
+
+---
+
+## `workflows push`
+
+Update workflow configurations only (does not create or delete workflows).
+
+### Usage
+
+```bash
+hailer-sdk ws-config workflows push -e <email> -p <password> -w <workspace-id>
+```
+
+### What it Does
+
+Updates existing workflow configurations from `main.ts` files without:
+- Creating new workflows
+- Deleting workflows
+- Modifying fields or phases
+
+### When to Use
+
+Use when you've only changed workflow-level settings like:
+- Workflow name
+- Phases or fields order
+- Permissions
+- Default
+
+---
+
+## `workflows sync`
+
+Manage workflow lifecycle - create and delete workflows.
+
+### Usage
+
+```bash
+hailer-sdk ws-config workflows sync -e <email> -p <password> -w <workspace-id>
+```
+
+### What it Does
+
+- **Creates** new workflows that exist locally but not remotely
+- **Deletes** workflows that exist remotely but not locally
+- **Does NOT update** existing workflow configurations
+
+### When to Use
+
+Use when you:
+- Added new workflow directories locally
+- Removed workflow directories you want deleted remotely
+
+### Important
+
+This command performs destructive operations. Always:
+1. Review what will be created/deleted
+2. Pull after syncing: `hailer-sdk ws-config pull`
+
+---
+
+## `phases push`
+
+Push phase configurations to Hailer workspace.
+
+### Usage
+
+```bash
+hailer-sdk ws-config phases push -e <email> -p <password> -w <workspace-id>
+```
+
+### What it Does
+
+For each workflow:
+- **Creates** new phases defined in `phases.ts`
+- **Updates** existing phase configurations
+- **Deletes** phases that exist remotely but not in `phases.ts` (with confirmation)
+
+### User Confirmation
+
+When phases exist remotely but not locally, you'll be prompted:
+
+```
+Delete 2 phase(s) from workflow 'Sales Pipeline'? (Y/n)
+```
+
+### When to Use
+
+Use when you've:
+- Added new phases
+- Modified phase configurations
+- Removed phases from `phases.ts`
+
+---
+
+## `fields push`
+
+Push field configurations to Hailer workspace.
+
+### Usage
+
+```bash
+hailer-sdk ws-config fields push -e <email> -p <password> -w <workspace-id>
+```
+
+### What it Does
+
+For each workflow:
+- **Creates** new fields defined in `fields.ts`
+- **Updates** existing field configurations
+- **Deletes** fields that exist remotely but not in `fields.ts` (with confirmation)
+
+### Important Notes
+
+- Field `key` cannot be updated via API (read-only)
+- Changes to field types may require data migration
+- Always test in a non-production workspace first
+-
+**⚠️ NOTE:** Fields shouldn't have same name, `label`, if they do one field will be removed during push
+
+### When to Use
+
+Use when you've:
+- Added new fields
+- Modified field configurations
+- Removed fields from `fields.ts`
+
+---
+
+## `groups push`
+
+Push group configurations to Hailer workspace.
+
+### Usage
+
+```bash
+hailer-sdk ws-config groups push -e <email> -p <password> -w <workspace-id>
+```
+
+### What it Does
+
+For the workspace:
+- **Creates** new groups defined in `groups.ts`
+- **Updates** existing group configurations
+- **Deletes** groups that exist remotely but not in `groups.ts` (with confirmation)
+
+### User Confirmation
+
+When groups exist remotely but not locally, you'll be prompted:
+
+```
+Delete 2 group(s) from workspace? (Y/n)
+```
+
+### When to Use
+
+Use when you've:
+- Added new groups
+- Modified group configurations (name, members, permissions)
+- Removed groups from `groups.ts`
+
+---
+
+## `teams push`
+
+Push team configurations to Hailer workspace.
+
+### Usage
+
+```bash
+hailer-sdk ws-config teams push -e <email> -p <password> -w <workspace-id>
+```
+
+### What it Does
+
+For the workspace:
+- **Creates** new teams defined in `teams.ts`
+- **Updates** existing team configurations
+- **Deletes** teams that exist remotely but not in `teams.ts` (with confirmation)
+
+### User Confirmation
+
+When teams exist remotely but not locally, you'll be prompted:
+
+```
+Delete 2 team(s) from workspace? (Y/n)
+```
+
+### When to Use
+
+Use when you've:
+- Added new teams
+- Modified team configurations (name, members, permissions)
+- Removed teams from `teams.ts`
+
+---
+
+## `insights push`
+
+Push insights configurations to Hailer workspace.
+
+### Usage
+
+```bash
+hailer-sdk ws-config insights push -e <email> -p <password> -w <workspace-id>
+```
+
+### What it Does
+
+For the workspace:
+- **Creates** new insights defined in `insights.ts`
+- **Updates** existing insight configurations (query, sources, members, permissions)
+- **Deletes** insights that exist remotely but not in `insights.ts` (with confirmation)
+
+### User Confirmation
+
+When insights exist remotely but not locally, you'll be prompted:
+
+```
+Delete 2 insight(s) from workspace? (Y/n)
+```
+
+### When to Use
+
+Use when you've:
+- Added new insights
+- Modified insight queries or data sources
+- Changed insight members or permissions
+- Removed insights from `insights.ts`
+
+### Notes
+
+- Insights are workspace-level resources
+- Members are managed separately from insight properties
+- Insight queries use SQLite3 syntax
+
+---
+
+## Typical Workflow
+
+Here's the recommended workflow for managing configurations:
+
+### 1. Initial Setup
+
+```bash
+# Pull existing configuration
+hailer-sdk ws-config pull
+```
+
+### 2. Make Changes
+
+Edit the TypeScript files in `workspace/`:
+- Modify `main.ts` for workflow settings
+- Edit `fields.ts` to add/update fields
+- Edit `phases.ts` to add/update phases
+
+### 3. Push Changes
+
+```bash
+# Push all changes at once
+hailer-sdk ws-config push
+
+# Or push specific components
+hailer-sdk ws-config workflows push
+hailer-sdk ws-config fields push
+hailer-sdk ws-config phases push
+hailer-sdk ws-config groups push
+hailer-sdk ws-config teams push
+```
+
+### 4. Sync Local Repository
+
+```bash
+# Always pull after pushing to stay in sync
+hailer-sdk ws-config pull
+```
+
+## Tips
+
+- **Use enums** - Reference IDs using the generated enums for type safety
+- **Version control** - Commit your `workspace/` directory to git
+- **Test first** - Test changes in a development workspace before production
+- **Pull often** - Pull before making changes to avoid conflicts
+- **Push incrementally** - Push specific components instead of everything at once

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.4] - 28-11-2025
+
+### Added
+
+- CHANGELOG.md for version tracking
+- Release scripts (`npm run release:patch/minor/major`) with auto npm publish
+
+## [0.0.3] - 28-11-2025
+
+### Added
+
+- **Claude Code Hooks**: Auto-loading system for skills and safety guards
+  - `PreToolUse.sh` - Auto-loads SDK skills before bash commands
+  - `sdk-delete-guard.cjs` - Blocks destructive SDK commands, requires user confirmation
+  - `prompt-skill-loader.cjs` - Keyword-based disambiguation for ambiguous prompts
+  - `skill-loader.cjs` - Auto-loads skills before MCP tool calls
+
+- Discussion tools: Find activity from discussion ID and vice versa
+- Nuclear tool safety with opt-in access model
+- Safety confirmations for destructive operations
+- Configurable paths for workspace configs and dev apps
+
+### Changed
+
+- Skills renamed to `MCP-*`/`SDK-*` prefix for clarity
+- Skills optimized for Sonnet model token usage
+- Default port changed from 3000 to 3030
+- Documentation updates
+
+### Removed
+
+- Template tools (moved to hailer-sdk)
+- `/generate-types` command
+
+### Fixed
+
+- Config import in app tools
+
+## [0.0.2] - 28-11-2025
+
+### Changed
+
+- Updated README for npm package usage
+- npm package readiness updates
+
+## [0.0.1] - 20-11-2025
+
+### Added
+
+- Initial release
+- 34+ MCP tools for Hailer integration with Claude Code
+  - Activity tools (create, read, update, delete with bulk support)
+  - Workflow tools (manage workflows, fields, phases, schemas)
+  - Discussion tools (chat/messaging within activities)
+  - Insight tools (SQL-like reporting over workflow data)
+  - App tools (Hailer app management and deployment)
+- HTTP MCP server with SSE support
+- Automated agent responding to @mentions
+- Per-agent access control via tool groups
+- Multi-workspace support with caching
+- Skill documentation system