@hailer/mcp 1.2.0 → 1.2.1

package/.claude/skills/create-and-publish-app/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: create-and-publish-app
 description: How to scaffold, create and publish Hailer apps using @hailer/create-app npm package (CLI-based alternative to scaffold_hailer_app MCP tool)
-version: 1.0.0
+version: 1.1.0
 triggers:
   - create-app
   - npx create-app
@@ -25,6 +25,8 @@ Scaffold, create and publish Hailer apps using `@hailer/create-app` npm package.
 | `scaffold_hailer_app` MCP tool | MCP-based scaffolding, `publish_hailer_app` MCP tool for publishing |
 
 Both create valid Hailer apps. This skill covers the npm CLI path.
+
+**IMPORTANT: The `scaffold_hailer_app` MCP tool uses `/bin/sh` internally. In Hailer Studio (cluster environment), `/bin/sh` is not at the standard path and the MCP tool will fail with `spawnSync /bin/sh ENOENT`. Always use `npx @hailer/create-app` in Hailer Studio.**
 </when-to-use>
 
 <step-1>
@@ -34,9 +36,10 @@ Both create valid Hailer apps. This skill covers the npm CLI path.
 npx @hailer/create-app <project-name> --template react-ts
 ```
 
-- Run from the `apps/` directory (create it first if it doesn't exist: `mkdir -p apps`)
+- Run from a parent directory (e.g. project root or an `apps/` subfolder — create it first if needed: `mkdir -p apps`)
 - `react-ts` is the recommended template
 - **CRITICAL:** The CLI is interactive-only when called via `npm create` — always use `npx @hailer/create-app` with the name and template as arguments to avoid prompts
+- **Hailer Studio only:** Do NOT use `scaffold_hailer_app` MCP tool — it fails with `spawnSync /bin/sh ENOENT` in the cluster environment
 </step-1>
 
 <step-2>
@@ -61,67 +64,141 @@ Replace `src/App.tsx` and add components. Key patterns:
 </step-3>
 
 <step-4>
-## Step 4 — Create and Publish (First Time)
+## Step 4 — Publish Dev Version
+
+**Do NOT publish as production yet WHEN IN HAILER STUDIO.** Publish the app under the name `<App Name> - Dev` so it can be tested inside Hailer. This is the dev iteration loop — build, publish as Dev, test, fix, repeat.
+
+### Hailer Studio (cluster)
+
+```bash
+npm run publish-production -- --host http://hailer-api:1337 --create --app-name "<App Name> - Dev" --workspace <workspaceId> --force
+```
+
+After the first publish, `public/manifest.json` is updated with the dev app's `appId`. Subsequent dev publishes just need `--force` — no `--create` or `--app-name` needed.
+
+Then share it with the workspace:
+
+```javascript
+add_app_member({ appId: "<devAppId>", member: "network_<workspaceId>" })
+```
+
+**Why not localhost:3000?** In Hailer Studio the sandbox is not reachable from outside — `localhost:3000` is inaccessible to the user. Publishing is the only way to test the app inside Hailer.
+
+**Only proceed to Step 5 when the user explicitly says they are happy and want to publish to production.**
+</step-4>
+
+<step-5>
+## Step 5 — Publish to Production (Only When User Explicitly Asks)
+
+When the user confirms they are happy with the dev version and explicitly asks to publish:
+
+Update `public/manifest.json` — clear the `appId` (or use a different one) so `--create` makes a new separate production app entry. Then:
+
+### On a developer's local machine (can reach api.hailer.com)
 
 ```bash
 npm run publish-production -- --create --app-name "<App Name>" --workspace <workspaceId> --force
 ```
 
+### In Hailer Studio (cluster environment — cannot reach api.hailer.com)
+
+```bash
+npm run publish-production -- --host http://hailer-api:1337 --create --app-name "<App Name>" --workspace <workspaceId> --force
+```
+
+The `--host` flag overrides the hardcoded `https://api.hailer.com` default. Credentials are picked up automatically from `~/.env`.
+
 | Flag | Purpose |
 |------|---------|
 | `--create` | Creates a brand new app entry in Hailer |
 | `--app-name` | Name shown in Hailer |
 | `--workspace` | Workspace ID from `config.json` at project root |
 | `--force` | Skips confirmation prompt |
+| `--host` | API URL — required in cluster environments |
+| `--user-api-key` | API key — read from `~/.env` if not provided as flag |
 
-**No `--user-api-key` needed** — the publish script automatically picks up credentials from the `~/.env` file injected by Hailer Studio. Credential resolution order:
+**Credential resolution order:**
 1. `--user-api-key` or `--email` flags
 2. `USER_API_KEY` or `HAILER_USER_API_KEY` environment variables
-3. `HAILER_USER_API_KEY` from `~/.env` ← this is what Hailer Studio provides automatically
+3. `HAILER_USER_API_KEY` from `~/.env` ← auto-injected by Hailer Studio
 
 After running, `public/manifest.json` is auto-updated with the new `appId`.
-</step-4>
 
-<step-5>
-## Step 5 — Subsequent Publishes
+### After publishing — share with workspace
+
+The CLI publish does NOT auto-share. Share manually via MCP:
+
+```javascript
+add_app_member({ appId: "<appId>", member: "network_<workspaceId>" })
+```
+</step-5>
+
+<step-6>
+## Step 6 — Subsequent Publishes
+
+### Local machine
 
 ```bash
 npm run publish-production -- --force
 ```
 
-The `appId` in `manifest.json` determines which app gets updated. No API key needed — `~/.env` is picked up automatically.
-</step-5>
+### Hailer Studio (cluster)
+
+```bash
+npm run publish-production -- --host http://hailer-api:1337 --force
+```
+
+The `appId` in `manifest.json` determines which app gets updated.
+</step-6>
 
 <dev-vs-prod>
 ## Dev vs Production Strategy
 
-Maintain two separate published apps:
+Always maintain two separate published app entries in Hailer:
 
-| App | Purpose |
-|-----|---------|
-| My App Dev | Publish here during iteration |
-| My App | Publish here only when ready for users |
+| App | Name convention | Purpose |
+|-----|----------------|---------|
+| Dev | `My App - Dev` | Publish here repeatedly during development and testing |
+| Production | `My App` | Publish here only when user confirms they are happy |
 
-Switch between them by changing `appId` in `public/manifest.json` before publishing.
+**In Hailer Studio, `localhost:3000` is not accessible to the user — publishing is the only way to test inside Hailer. This means the dev app gets published and re-published on every iteration.**
+
+To switch between dev and production app entries, keep track of both `appId` values. Before publishing production, set `appId` in `public/manifest.json` to the production app's ID (or use `--create` to make a new one).
 </dev-vs-prod>
 
 <environments>
 ## Environments
 
-| Command | Target |
-|---------|--------|
-| `npm run publish-production` | Production (https://api.hailer.com) |
-| `npm run publish-development` | Development (https://testapi.hailer.biz) |
-| `npm run publish-staging` | Staging (https://api.hailer.biz) |
+| Command | Default target |
+|---------|---------------|
+| `npm run publish-production` | https://api.hailer.com |
+| `npm run publish-development` | https://testapi.hailer.biz |
+| `npm run publish-staging` | https://api.hailer.biz |
+
+**In Hailer Studio**, append `-- --host http://hailer-api:1337` to any of the above to override the default host:
+
+```bash
+npm run publish-production -- --host http://hailer-api:1337 --force
+```
 </environments>
 
 <checklist>
-## Checklist Before Publishing
+## Dev App Checklist (Step 4 — do this first)
+
+- [ ] Published as `<App Name> - Dev` using `--create --app-name "<App Name> - Dev"`
+- [ ] Shared dev app with workspace via MCP `add_app_member`
+- [ ] App opens and works correctly inside Hailer
+- [ ] Iterate: fix → `npm run publish-production -- --host ... --force` → test in Hailer → repeat
+
+## Production Publish Checklist (Step 5 — only when user asks to publish)
 
-- [ ] Read `apps/<project-name>/README.md` — it always has the latest commands for that version
+- [ ] User has explicitly requested publishing/deploying
+- [ ] Read `<project-name>/README.md` — it always has the latest commands for that version
 - [ ] Verify `public/manifest.json` has the correct `appId` for the target app
 - [ ] `version` and `versionDescription` in manifest are only required for marketplace publishes
 - [ ] Build runs automatically as part of the publish script — no separate build step needed
 - [ ] Workspace ID is in `config.json` at the project root
-- [ ] No API key needed — `~/.env` is picked up automatically by the publish script
+- [ ] Fixed `StoreSet` type error in `src/hailer/use-app.ts` (`replace?: false` not `boolean`)
+- [ ] **Hailer Studio:** Append `-- --host http://hailer-api:1337` to `npm run publish-*`
+- [ ] **After first publish:** Manually share via MCP `add_app_member` — CLI does not auto-share
 </checklist>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hailer/mcp",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "config": {
     "docker": {
       "registry": "registry.gitlab.com/hailer-repos/hailer-mcp"