@hailer/mcp 1.2.1 → 1.3.9

package/.claude/skills/hailer-ui-guide/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: hailer-ui-guide
+description: Hailer UI structure and navigation guide for AI Helper
+version: 1.0.0
+triggers:
+  - hailer ui
+  - hailer interface
+  - onboarding
+---
+
+# Hailer UI Guide
+
+Complete guide to Hailer's user interface for providing accurate navigation assistance.
+
+<layout>
+## Main Layout Structure
+
+Hailer uses a three-column layout:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Top Toolbar (mobile only)            │
+├────────┬────────────────────────────┬───────────────────┤
+│        │                            │                   │
+│  Left  │       Main Content         │     Sidenav       │
+│  Nav   │       (router-outlet)      │    (400px)        │
+│ (56px) │                            │                   │
+│        │                            │                   │
+├────────┴────────────────────────────┴───────────────────┤
+│                 Mobile Navigation (mobile only)         │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Desktop (>600px):**
+- Left sidebar: 56px vertical icon menu
+- Main content: fills remaining space
+- Right sidenav: 400px panel for activity/discussion details
+
+**Mobile (<=600px):**
+- Top toolbar visible
+- Full-screen sidenav (100vw)
+- Bottom navigation bar
+</layout>
+
+<left-nav>
+## Left Navigation Menu
+
+Vertical icon menu on the left side (always visible on desktop).
+
+**Menu items from top to bottom:**
+1. **Discussions** (icon: hailer-discussion) - Chat and team discussions
+2. **Feed** (icon: hailer-feed) - Activity feed and updates
+3. **Calendar** (icon: hailer-calendar) - Events and schedules
+4. **Activities** (icon: hailer-activity) - Workflows and kanban boards
+5. **Apps** (icon: hailer-apps) - Custom applications
+6. **People** (icon: hailer-people) - User directory
+
+**Bottom section:**
+- **Settings** (icon: hailer-settings) - Workspace settings (admins only)
+- **User profile** - Opens user menu with:
+  - Profile settings
+  - Language selection
+  - Dark/light mode toggle
+  - Logout
+
+**Navigation instruction example:**
+"Click the 'Activities' icon in the left menu (4th from top, looks like a kanban board)"
+</left-nav>
+
+<activities-section>
+## Activities Section (Workflows)
+
+When user navigates to `/activities`:
+
+**Workflow List View:**
+- Shows all available workflows as cards
+- Each card shows workflow name and icon
+- Click a workflow to open it
+
+**Workflow View (Kanban):**
+URL: `/activities/{workflowId}`
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Workflow Name                    [+ Add] [View Toggle] │
+├──────────┬──────────┬──────────┬──────────┬────────────┤
+│  Phase 1 │  Phase 2 │  Phase 3 │  Phase 4 │  Phase 5   │
+│  (New)   │ (Active) │(Review)  │ (Done)   │ (Archive)  │
+├──────────┼──────────┼──────────┼──────────┼────────────┤
+│ [Card]   │ [Card]   │ [Card]   │          │            │
+│ [Card]   │ [Card]   │          │          │            │
+│ [Card]   │          │          │          │            │
+└──────────┴──────────┴──────────┴──────────┴────────────┘
+```
+
+**View modes** (toggle in top-right):
+- **Kanban** - Cards in columns by phase (default)
+- **Table** - List view with sortable columns
+- **Calendar** - Timeline/calendar view
+- **Map** - Location-based view (if enabled)
+
+**Actions:**
+- **Create activity:** Click [+ Add] button top-right, or click empty area in phase column
+- **Open activity:** Click any card to open in sidenav
+- **Move activity:** Drag card to another phase column, OR open card and use phase selector
+- **Filter:** Use search bar or filter controls at top
+</activities-section>
+
+<activity-sidenav>
+## Activity Sidenav (Right Panel)
+
+Opens when user clicks an activity card. Width: 400px on desktop, fullscreen on mobile.
+
+**Header section:**
+- Activity name (large text)
+- Workspace badge (colored tag)
+- Workflow badge (colored tag, clickable - navigates to workflow)
+- Copy tag button (mentions activity in discussions)
+- Call button (if video calls enabled)
+
+**Tab bar** (icons below header):
+1. **Detail** (icon: hailer-activity) - Main fields and info
+2. **Participants** (icon: hailer-group) - Followers with badge count
+3. **Discussion** (icon: hailer-discussion) - Activity chat with unread badge
+4. **Files** (icon: hailer-attach) - Attachments with count badge
+5. **Location** (icon: hailer-location) - Map view (if enabled)
+6. **Linked** (icon: hailer-linked-activity) - Related activities with count
+7. **Options** (icon: hailer-settings) - Activity settings (if permitted)
+
+**Control buttons** (bottom, visible in edit/create mode):
+- **Cancel** - Discard changes
+- **Save** (with checkmark icon) - Save changes
+
+**Modes:**
+- **View mode:** Read-only display of activity
+- **Edit mode:** Fields become editable, Save/Cancel buttons appear
+- **Create mode:** Empty form for new activity
+
+**Instruction examples:**
+- "Click the 'Detail' tab (first icon) to see all fields"
+- "Click the 'Discussion' tab (chat bubble icon) to see comments"
+- "Click 'Save' in the bottom right to save your changes"
+</activity-sidenav>
+
+<phase-transitions>
+## Moving Activities Between Phases
+
+**Method 1: Drag and Drop (Kanban view)**
+"Drag the card from the '{current phase}' column and drop it in the '{target phase}' column"
+
+**Method 2: Phase Selector (in activity sidenav)**
+"Open the activity, click the phase dropdown near the top, and select '{target phase}'"
+
+**Phase order:**
+Phases are displayed left-to-right in the order defined by workflow.
+First phase = leftmost column (usually "New" or "Draft")
+Last phase = rightmost column (usually "Done" or "Archived")
+</phase-transitions>
+
+<discussions-section>
+## Discussions Section
+
+URL: `/discussions`
+
+**Discussion list:**
+- Shows all discussions user is part of
+- Unread count badges on each discussion
+- Search bar at top
+
+**Discussion view:**
+- Message list (chronological)
+- Input field at bottom
+- File attachment button
+- Emoji picker
+- @mention support
+
+**Activity discussions:**
+- Activities can have linked discussions
+- Access via "Discussion" tab in activity sidenav
+- Must "Join" discussion to see messages
+</discussions-section>
+
+<common-patterns>
+## Common UI Patterns
+
+**Buttons:**
+- Primary action: Blue filled button (e.g., "Save", "Create")
+- Secondary action: Outlined button (e.g., "Cancel")
+- Icon buttons: Small circular buttons with icons
+
+**Cards:**
+- White background (light mode) / Dark gray (dark mode)
+- Rounded corners
+- Subtle shadow
+- Click to select/open
+
+**Badges:**
+- Small colored pills showing counts or status
+- Red badge = requires attention
+- Gray badge = informational
+
+**Tooltips:**
+- Hover over icon buttons to see label
+- Useful for understanding unclear icons
+
+**Color coding:**
+- Phases have assigned colors (visible in kanban columns)
+- Workflow badges use workflow color
+- Workspace badges use workspace color
+</common-patterns>
+
+<context-to-instruction>
+## Translating Context to Instructions
+
+When you receive user context, use these patterns:
+
+**Context:** `section: 'activities', view.mode: 'kanban', view.workflowName: 'Sales'`
+**Know:** User is looking at Sales workflow kanban board
+
+**Context:** `sidenav.open: true, sidenav.type: 'activity', sidenav.activeTab: 'detail'`
+**Know:** User has an activity open and is viewing the detail tab
+
+**Context:** `sidenav.mode: 'edit', sidenav.buttons: ['save', 'cancel']`
+**Know:** User is editing an activity, Save and Cancel buttons are visible
+
+**Context:** `user.role: 'admin'`
+**Know:** User can access Settings and admin features
+
+**Instruction patterns by context:**
+
+| User location | They want to... | Say... |
+|--------------|-----------------|--------|
+| Kanban view | Create activity | "Click the '+ Add' button in the top right, or click the '+' at the bottom of any phase column" |
+| Kanban view | Open activity | "Click on the card you want to open" |
+| Activity sidenav | Edit fields | "Click the 'Edit' button (pencil icon) to enable editing, make your changes, then click 'Save'" |
+| Activity sidenav | See comments | "Click the 'Discussion' tab (speech bubble icon, 3rd from left)" |
+| Activity sidenav | Move to phase | "Click the phase badge at the top and select the new phase from the dropdown" |
+| Activity edit | Save changes | "Click the 'Save' button in the bottom right corner" |
+| Activity edit | Cancel changes | "Click 'Cancel' on the left to discard changes" |
+</context-to-instruction>
+
+<troubleshooting>
+## Common User Issues
+
+**"I can't see the workflow"**
+- Check if user has permission to the workflow
+- Admin may need to grant access in workflow settings
+
+**"I can't edit this activity"**
+- Check if user has edit permission for this phase
+- Some phases may be read-only for certain users
+
+**"I can't move the card"**
+- Phase transitions may be restricted
+- Check workflow settings for allowed transitions
+
+**"Where are my discussions?"**
+- User must be a member of the discussion
+- Check "Discussions" in left menu
+- For activity discussions, must "Join" first
+
+**"I can't see the Settings"**
+- Settings is admin-only
+- Regular users don't see this menu item
+</troubleshooting>

package/.env.example

@@ -81,6 +81,18 @@ MCP_SERVER_URL=http://localhost:3030/api/mcp
 # MCP Agent User IDs (required for agent tagging - get these from Hailer)
 MCP_CLIENT_AGENT_IDS='[]'
 
+# Hailer REST API base URL — every authenticated REST call (incl. the
+# public-chat graduation handler's apiKey validation via v2.core.init)
+# is sent to ${BOT_API_BASE_URL}/api/<dotted/method>. Defaults to
+# https://api.hailer.com.
+#
+# In local dev the Hailer API process typically listens on
+# http://localhost:1337 (NOT the frontend port — the frontend at 9443
+# doesn't expose /api/v2/* routes and will return Express's "Cannot POST"
+# 404 HTML which then bubbles up through the graduation popup as
+# "API key validation failed: REST API request failed: 404 …").
+# BOT_API_BASE_URL=http://localhost:1337
+
 # Bot Features (optional, defaults to true)
 TOKEN_USAGE_BOT_ENABLED=false
 AGENT_ACTIVITY_BOT_ENABLED=false
@@ -90,4 +102,41 @@ 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
+
+# ==============================================
+# PUBLIC CHAT GRADUATION (Studio pre-warm)
+# ==============================================
+
+# Hailer frontend URL — origin the public-chat authorize popup is
+# redirected back to on success/error (e.g. https://<host>/#/authorize/complete).
+# Also used as the Origin header for the Studio prewarm.
+#
+# The /api/public-chat/authorize handler first tries the inbound
+# Origin/Referer header and only falls back to this value when the
+# browser sends `Origin: null` (cross-scheme form POSTs do this) or no
+# usable Referer. In local dev with the Hailer frontend on
+# https://localhost:9443, set this to https://localhost:9443 so the
+# popup closes itself instead of bouncing the user to app.hailer.com.
+# HAILER_APP_URL=https://app.hailer.com
+
+# Hailer Studio backend URL. When set, public-chat graduation pre-warms a
+# Studio session for the newly graduated user. Leave unset to disable.
+# STUDIO_URL=https://studio.hailer.com
+
+# Origin header sent on the Studio WS upgrade + HTTP POST. Must match one
+# of Studio's WHITELISTED_ORIGINS. Defaults to HAILER_APP_URL.
+# STUDIO_ORIGIN=https://app.hailer.com
+
+# Headless Studio session-create endpoint. When set, public-chat graduation
+# creates a one-shot Studio "builder" session for the new workspace via a
+# single server-to-server POST (apiKey + workspaceId required; systemMessage +
+# initialPrompt optional). This is what auto-builds the graduated user's
+# workflows + app and triggers the Hailer Helper tour handoff. Takes precedence
+# over the legacy STUDIO_URL WS prewarm.
+#
+# REQUIRED for the Studio build/tour flow to run — if unset, createStudioSession
+# silently skips and no workspace is built (the Helper then greets without
+# promising a build). Point it at the Studio sessions endpoint for THIS
+# environment, e.g. for next.k8s use the next proxy host:
+# STUDIO_SESSIONS_CREATE_URL=https://next.k8s.hailer.com/proxy/studio/api/sessions/create

package/CLAUDE.md

@@ -1,17 +1,148 @@
-# Hailer MCP Server
+# Hailer SDK + MCP Project
 
-MCP tools for Hailer workspaces: workflows, activities, insights, and apps.
+You're working in a project scaffolded by `@hailer/sdk`. The `workspace/` directory IS the source of truth for all workflow configuration; the MCP server (remote or local) exposes runtime tools.
 
-## Quick Start
+## The One Rule
+
+**If it can be done locally, do it locally. MCP tools are ONLY for things that require a server call.**
+
+Local = read `workspace/` files, run `npm run …` SDK commands, use `npx @hailer/create-app`, run vitest.
+Remote = MCP tools for activities, discussions, calendar, insights, files, permissions, marketplace.
+
+Before any MCP call, ask: "Is this answerable from `workspace/` files or a CLI?" If yes, do that instead. (SDK-profile connections don't even serve the shadowed tools; if you can see them, you're on a general connection — the rule still applies.)
+
+## What Goes Where
+
+| Need | Do this | Don't |
+|------|---------|-------|
+| Find workflow / field / phase IDs | Read `workspace/enums.ts` | `describe_workflows` |
+| See field types, labels, options | Read `workspace/<Name>_<id>/fields.ts` | `describe_workflows` |
+| See phases | Read `workspace/<Name>_<id>/phases.ts` | `describe_workflows` |
+| See all workflows | Read `workspace/workflows.ts` | `describe_workflows` |
+| Create / modify fields or phases | Edit `fields.ts` / `phases.ts` → `npm run fields-push:force` / `phases-push:force` | `update_workflow_structure` |
+| Create / modify workflows | Edit `workflows.ts` → `npm run workflows-sync:force` | `install_workflow` |
+| Create / modify teams / groups | Edit `teams.ts` / `groups.ts` → `npm run teams-push:force` / `groups-push:force` | — |
+| Create / modify insights config | Edit `insights.ts` → `npm run insights-push:force` | — (runtime `run_insight` is fine) |
+| Create / modify document templates | Edit `templates/` → `npm run templates-sync:force` | — |
+| Test function field code | vitest locally | `test_function_field` |
+| Scaffold an app | `npx @hailer/create-app <name> --template react-ts` then `npx hailer-mcp prep-app <name>` (name POSITIONAL not `--name`; bare command PROMPTS and hangs agents; prep-app fixes scaffold papercuts) | — (script-only; no MCP tool exists) |
+| Publish an app | `cd app && npm run publish-production -- --force` (add `--market` for marketplace versions) | — (script-only; no MCP tool exists) |
+| Share / edit EXISTING app metadata | Edit `workspace/apps.ts` → `npx hailer-sdk ws-config apps push --force` | `manage_app` |
+| Create an app entry | NEVER via apps.ts — first publish with `--create` does it (correct URL included) | never invent placeholder URLs |
+| Create / update activities | MCP `create_activity`, `update_activity` | — |
+| List / read / count activities | MCP `list_activities` (`countOnly: true` for counts), `show_activity_by_id` | — |
+| Query data (SQL reports) | MCP `run_insight`, `save_insight` | — |
+| Discussions, calendar, files, users | MCP runtime tools | — |
+| Workflow permissions | MCP `set_workflow_permission`, `list_workflow_permissions`, `check_user_permissions` | — |
+| Live activity counts / orientation | MCP `core_init` (once per session) | — |
+
+## How to Read workspace/ Files
+
+**Never read workspace/ files in main context** — they're large and fill context permanently.
+
+1. Spawn a fast sub-agent (haiku-class) to read the files
+2. It extracts what you need (IDs, field types, phase names) and returns a short summary
+3. Use that summary for MCP runtime calls
+
+Sub-agent habits: fast models read/search, capable models write code; load Skills in sub-agents, not main context; delegate anything beyond ~20 lines of code.
+
+## workspace/ Structure
 
-```bash
-npm init @hailer/sdk              # Scaffold project with workspace/ config
-npm run pull                      # Pull latest workflow schemas from Hailer
-npm run generate                  # Generate TypeScript types
 ```
+workspace/
+├── enums.ts           # ALL IDs: WorkflowIds, FieldIds, PhaseIds, TeamIds, GroupIds
+├── workflows.ts       # Workflow registry
+├── teams.ts           # Team definitions
+├── groups.ts          # Group definitions
+├── insights.ts        # Insight definitions
+├── apps.ts            # App registry (name, url, image, members)
+├── templates/         # Document templates
+└── <WorkflowName>_<id>/
+    ├── fields.ts      # Field definitions (type, label, key, options, required)
+    ├── phases.ts      # Phases (name, key, isInitial, isEndpoint, nextPhases)
+    ├── main.ts        # Workflow config
+    └── functions/     # Function field code (one file per function)
+```
+
+`npm run pull` refreshes everything from Hailer → local files.
+
+## SDK Push Commands
+
+| Command | Effect |
+|---------|--------|
+| `npm run pull` | Pull latest from Hailer → local files |
+| `npm run push:force` | Push everything |
+| `npm run fields-push:force` | Fields only |
+| `npm run phases-push:force` | Phases only |
+| `npm run workflows-sync:force` | Workflow registry (create / delete) |
+| `npm run teams-push:force` | Teams |
+| `npm run groups-push:force` | Groups |
+| `npm run insights-push:force` | Insights |
+| `npm run templates-sync:force` | Document templates |
+| `npx hailer-sdk ws-config apps push --force` | App registry + members |
+
+Always use `:force` — the non-force variants prompt interactively.
+
+## Push / Pull Gotchas
+
+| Gotcha | Correct | Wrong |
+|--------|---------|-------|
+| New entities | Omit `_id` — server assigns it | Don't add `_id` manually |
+| After push | `npm run pull` to get server-assigned IDs | Don't assume local IDs are final |
+| Function fields | `npm run fields-push:force` only (non-force skips `functionVariables`) | Don't use non-force |
+| Enum imports | Verify after pull — identical hex suffixes can collide | Don't blindly trust auto-generated imports |
+| `linkedfrom` fields | Don't work in isolated-vm; use `<` backlink dependency | Don't use in function fields |
+| Function field code | Plain JavaScript only | Not TypeScript |
+| Phase transitions | Exact string match on phase name | Don't guess phase names |
+| Activity field values (MCP) | Date: Unix ms (`1730937600000`); Dropdown: exact string; ActivityLink: string ID; fields keyed by field ID, never label | Not ISO dates, not arrays, not field names |
+
+## App Lifecycle
+
+| Step | How |
+|------|-----|
+| Scaffold | `npx @hailer/create-app <name> --template react-ts` then `npx hailer-mcp prep-app <name>` — scaffold fresh, never copy an existing app (prep-app clears the placeholder appId + fixes the StoreSet tsc error) |
+| Local dev | `cd app && npm run dev` |
+| Publish | `cd app && npm run publish-production -- --force` (add `--market` for marketplace; `--force` skips the overwrite prompt that hangs agents); then share via `manage_app` add_member |
+| Share (after publish) | `npm run pull`, then edit members in `workspace/apps.ts` → `npx hailer-sdk ws-config apps push --force`. NEVER create app entries in apps.ts — `--create` publish makes them |
+
+Publish auth: works flag-free once the local `npx hailer-mcp` server has run once — it mints a user API key from the project bot creds into `~/.env`, mirroring Studio. Exit 10 = no auth yet → start the server once, or pass `-- --user-api-key <key>`; NEVER read passwords or probe login endpoints. Details: `create-and-publish-app` skill.
+
+## When MCP Tools Are the Answer
+
+The MCP server exposes a curated runtime surface the SDK can't replicate locally:
+
+- **Activities**: `create_activity`, `update_activity`, `list_activities` (+ `countOnly`), `show_activity_by_id`
+- **Discussions**: `list_my_discussions`, `fetch_discussion_messages` (cursor + linked-activity lookup), `add_discussion_message`, `join_discussion`, `leave_discussion`, `invite_discussion_members`
+- **Calendar**: `query_events` (single / range / upcoming), `manage_calendar`, `create_event`, `update_event` (incl. attendee removal), `delete_event`, `respond_to_invite`
+- **Insights (runtime)**: `run_insight` (saved or ad-hoc SQL), `save_insight`, `list_insights`
+- **Files**: `upload_files`, `download_file`
+- **Workflow permissions**: `set_workflow_permission` (level `none` revokes), `list_workflow_permissions`, `check_user_permissions`
+- **Marketplace**: `browse_marketplace`, `install_marketplace`, `publish_marketplace`
+- **Server-only mutations**: `auto_set_keys` (transactional key generation), `core_init` (live activity counts)
+
+Tools not in this list are either SDK-shadowed (see matrix above) or admin/dangerous (handled outside this environment).
+
+## Skills
+
+Load in sub-agents via the Skill tool. Never in main context.
+
+| Skill | When |
+|-------|------|
+| `sdk-ws-config-skill` | Workflows, fields, phases, teams, groups |
+| `sdk-function-fields` | Calculated fields, nameFunction |
+| `sdk-activity-patterns` | Creating/updating activities via MCP |
+| `sdk-insight-queries` | SQL insight queries |
+| `hailer-app-builder` | Building Hailer apps (React/Chakra) |
+| `hailer-design-system` | Theme, colors, icons, layout |
+| `create-and-publish-app` | Scaffolding + publishing apps (dev/prod/marketplace) |
+| `testing-patterns` | Vitest/playwright tests |
+
+## Commands
+
+`/command <param>` — angle brackets = required
 
-Then ask Claude Code to build features. Load relevant skills for domain context.
+**Essential:** `/save`, `/handoff`, `/prd`, `/autoplan`, `/ws-pull`
 
-## Project-Level Instructions
+**Squads** (drive the native Workflow tool): `/review-squad [target]`, `/debug-squad "<bug>"`
 
-See `.claude/CLAUDE.md` for full project configuration — skills, hooks, commands, gotchas.
+Build apps with a single agent + the `hailer-app-builder` / `create-and-publish-app` skills — faster than fanning out a squad (no shared-contract prep, no cross-agent integration fixups).

package/dist/app-prep.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Post-scaffold prep for freshly created Hailer apps.
+ *
+ * @hailer/create-app's templates ship two defaults that make every app build
+ * dance (and we can't change create-app). This neutralizes them from the
+ * @hailer/mcp side, deterministically, right after scaffold:
+ *
+ *   1. public/manifest.json ships a placeholder appId ("65143728…", the
+ *      "Magic Apps" demo) + fake author. The placeholder makes first-publish
+ *      detection ambiguous and the demo author/ids leak into the published
+ *      bundle. → clear appId to "" (empty == first publish) and drop the
+ *      fake author/contributors.
+ *   2. src/hailer/use-app.ts types StoreSet `replace?: boolean`, which fails
+ *      `tsc` under zustand v5. → `replace?: false`.
+ *
+ * Idempotent and best-effort: missing files are warned, not fatal.
+ * Invoked via `npx hailer-mcp prep-app <dir>` (see cli.ts).
+ */
+interface PrepResult {
+    appDir: string;
+    changes: string[];
+    warnings: string[];
+}
+/** Run all post-scaffold fixes against an app directory. */
+export declare function prepScaffoldedApp(input: string): PrepResult;
+export {};
+//# sourceMappingURL=app-prep.d.ts.map

package/dist/app-prep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-prep.d.ts","sourceRoot":"","sources":["../src/app-prep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,UAAU,UAAU;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACtB;AAgED,4DAA4D;AAC5D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAS3D"}

package/dist/app-prep.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Post-scaffold prep for freshly created Hailer apps.
+ *
+ * @hailer/create-app's templates ship two defaults that make every app build
+ * dance (and we can't change create-app). This neutralizes them from the
+ * @hailer/mcp side, deterministically, right after scaffold:
+ *
+ *   1. public/manifest.json ships a placeholder appId ("65143728…", the
+ *      "Magic Apps" demo) + fake author. The placeholder makes first-publish
+ *      detection ambiguous and the demo author/ids leak into the published
+ *      bundle. → clear appId to "" (empty == first publish) and drop the
+ *      fake author/contributors.
+ *   2. src/hailer/use-app.ts types StoreSet `replace?: boolean`, which fails
+ *      `tsc` under zustand v5. → `replace?: false`.
+ *
+ * Idempotent and best-effort: missing files are warned, not fatal.
+ * Invoked via `npx hailer-mcp prep-app <dir>` (see cli.ts).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepScaffoldedApp = prepScaffoldedApp;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/** Resolve the app dir from a user-supplied path: as-given, else under apps/. */
+function resolveAppDir(input) {
+    const candidates = [
+        (0, path_1.isAbsolute)(input) ? input : (0, path_1.resolve)(process.cwd(), input),
+        (0, path_1.resolve)(process.cwd(), 'apps', input),
+    ];
+    return candidates.find(dir => (0, fs_1.existsSync)((0, path_1.join)(dir, 'package.json')));
+}
+/** Clear the placeholder appId + fake author from public/manifest.json. */
+function fixManifest(appDir, result) {
+    const manifestPath = (0, path_1.join)(appDir, 'public', 'manifest.json');
+    if (!(0, fs_1.existsSync)(manifestPath)) {
+        result.warnings.push('public/manifest.json not found — skipped');
+        return;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse((0, fs_1.readFileSync)(manifestPath, 'utf-8'));
+    }
+    catch {
+        result.warnings.push('public/manifest.json is not valid JSON — skipped');
+        return;
+    }
+    const PLACEHOLDER_APP_ID = '65143728d2bd678b13daf289';
+    let touched = false;
+    if (manifest.appId === PLACEHOLDER_APP_ID || !manifest.appId) {
+        manifest.appId = '';
+        touched = true;
+    }
+    if (manifest.author === 'Magic Apps Ltd.') {
+        manifest.author = '';
+        touched = true;
+    }
+    if ('contributors' in manifest) {
+        delete manifest.contributors;
+        touched = true;
+    }
+    if (!touched) {
+        result.changes.push('manifest already clean');
+        return;
+    }
+    (0, fs_1.writeFileSync)(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    result.changes.push('manifest: cleared placeholder appId + fake author');
+}
+/** Fix the StoreSet replace type so `tsc` passes under zustand v5. */
+function fixUseAppTypes(appDir, result) {
+    const useAppPath = (0, path_1.join)(appDir, 'src', 'hailer', 'use-app.ts');
+    if (!(0, fs_1.existsSync)(useAppPath)) {
+        result.warnings.push('src/hailer/use-app.ts not found — skipped');
+        return;
+    }
+    const source = (0, fs_1.readFileSync)(useAppPath, 'utf-8');
+    if (!source.includes('replace?: boolean')) {
+        result.changes.push('use-app.ts already clean');
+        return;
+    }
+    (0, fs_1.writeFileSync)(useAppPath, source.replace('replace?: boolean', 'replace?: false'));
+    result.changes.push('use-app.ts: StoreSet replace?: boolean → false');
+}
+/** Run all post-scaffold fixes against an app directory. */
+function prepScaffoldedApp(input) {
+    const appDir = resolveAppDir(input);
+    if (!appDir) {
+        return { appDir: input, changes: [], warnings: [`No app project found at "${input}" or "apps/${input}"`] };
+    }
+    const result = { appDir, changes: [], warnings: [] };
+    fixManifest(appDir, result);
+    fixUseAppTypes(appDir, result);
+    return result;
+}
+//# sourceMappingURL=app-prep.js.map

package/dist/app-prep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-prep.js","sourceRoot":"","sources":["../src/app-prep.ts"],"names":[],"mappings":"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"}

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAO9B,QAAA,MAAM,IAAI,MAAa,CAAC;AAwBxB,eAAe,IAAI,CAAC"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAQ9B,QAAA,MAAM,IAAI,MAAa,CAAC;AA2BxB,eAAe,IAAI,CAAC"}

package/dist/app.js

@@ -4,6 +4,7 @@ const core_1 = require("./core");
 const config_1 = require("./config");
 const logger_1 = require("./lib/logger");
 const tools_1 = require("./mcp/tools");
+const aliases_1 = require("./mcp/tools/aliases");
 const vipunen_1 = require("./plugins/vipunen");
 const logger = (0, logger_1.createLogger)({ component: 'app' });
 const core = new core_1.Core();
@@ -11,6 +12,8 @@ const core = new core_1.Core();
 for (const tool of tools_1.allTools) {
     core.addTool(tool);
 }
+// v1 → v2 deprecation aliases: old names execute but aren't listed
+core.addToolAliases(aliases_1.TOOL_ALIASES);
 // Register Vipunen tools (conditional on WEAVIATE_HOST)
 for (const tool of (0, vipunen_1.registerVipunenTools)({
     weaviateHost: config_1.environment.WEAVIATE_HOST,

package/dist/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":";;AAAA,iCAA8B;AAC9B,qCAAuC;AACvC,yCAA4C;AAC5C,uCAAuC;AACvC,+CAAyD;AAEzD,MAAM,MAAM,GAAG,IAAA,qBAAY,EAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AAClD,MAAM,IAAI,GAAG,IAAI,WAAI,EAAE,CAAC;AAExB,4BAA4B;AAC5B,KAAK,MAAM,IAAI,IAAI,gBAAQ,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,wDAAwD;AACxD,KAAK,MAAM,IAAI,IAAI,IAAA,8BAAoB,EAAC;IACtC,YAAY,EAAE,oBAAW,CAAC,aAAa;IACvC,cAAc,EAAE,oBAAW,CAAC,gBAAgB;IAC5C,cAAc,EAAE,oBAAW,CAAC,gBAAgB;CAC7C,CAAC,EAAE,CAAC;IACH,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;AAErC,QAAQ;AACR,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC3B,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE,KAAK,CAAC,CAAC;IAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,kBAAe,IAAI,CAAC"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":";;AAAA,iCAA8B;AAC9B,qCAAuC;AACvC,yCAA4C;AAC5C,uCAAuC;AACvC,iDAAmD;AACnD,+CAAyD;AAEzD,MAAM,MAAM,GAAG,IAAA,qBAAY,EAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AAClD,MAAM,IAAI,GAAG,IAAI,WAAI,EAAE,CAAC;AAExB,4BAA4B;AAC5B,KAAK,MAAM,IAAI,IAAI,gBAAQ,EAAE,CAAC;IAC1B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAED,mEAAmE;AACnE,IAAI,CAAC,cAAc,CAAC,sBAAY,CAAC,CAAC;AAElC,wDAAwD;AACxD,KAAK,MAAM,IAAI,IAAI,IAAA,8BAAoB,EAAC;IACpC,YAAY,EAAE,oBAAW,CAAC,aAAa;IACvC,cAAc,EAAE,oBAAW,CAAC,gBAAgB;IAC5C,cAAc,EAAE,oBAAW,CAAC,gBAAgB;CAC/C,CAAC,EAAE,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;AAErC,QAAQ;AACR,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACzB,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE,KAAK,CAAC,CAAC;IAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC;AAEH,kBAAe,IAAI,CAAC"}