@hailer/mcp 1.3.14 → 1.3.23

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

@@ -0,0 +1,211 @@
+---
+name: publish-hailer-app
+description: Publishing Hailer apps to production — load when asked to publish, deploy, or switch a live app URL; covers manifest validation, CLI publish command, URL switch, sharing, cache busting, and publish gotchas
+version: 3.4.0
+triggers:
+  - publish app
+  - deploy app
+  - production app
+  - manifest
+  - appId
+---
+
+# Publish Hailer App
+
+Guide for publishing Hailer apps to production.
+
+<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.**
+</warning>
+
+<primary-path>
+## Primary Publish Path: CLI Script
+
+**`npm run publish-production -- --force` is the publish path.** The MCP server does NOT publish apps — it only covers the app registry (`manage_app`, `list_apps`, `remove_app`) and marketplace listings.
+
+`npm run publish-production -- --force` appends `--force` to the scaffold's script (which builds, packs, and calls `publish.cjs`), so no manual `npm pack` step is needed — the `--force` is what skips the interactive overwrite prompt that hangs agents.
+
+Auth comes from `HAILER_USER_API_KEY` in `~/.env` (auto-minted by `hailer-mcp` on boot). See `create-and-publish-app` skill `<credentials>` for the full auth chain and fallback options.
+</primary-path>
+
+<precondition>
+## Precondition: Verify @hailer/app-sdk Version Before Publishing
+
+**Concrete failure signature (v1.0.3):** Stale `@hailer/app-sdk` v1.0.3 makes publish fail — v1's `publish.cjs` ignores `--user-api-key`, requires interactive password (crashes non-TTY). Bumping to `^2.5.0` + `npm install` resolves this.
+
+```bash
+npm view @hailer/app-sdk version   # get latest from registry
+cat package.json | grep app-sdk    # check installed version
+```
+</precondition>
+
+<manifest-validation>
+## Validate manifest.json Before Publishing
+
+Check these before publishing:
+
+1. Read `public/manifest.json`
+2. `appId` exists and is 24 characters — if empty/missing or equals `65143728d2bd678b13daf289`, this is a first publish (use `--create`)
+3. `version` exists and is not empty (e.g., `"1.0.0"`)
+4. `versionDescription` exists and is not empty
+5. `vite.config.ts` has `base: './'` — without it assets 403/404 in production while localhost works
+</manifest-validation>
+
+<version-bump>
+## Updating Published Apps (version bump every publish)
+
+Every publish must bump the version and update the description.
+
+### Version format: `MAJOR.MINOR.PATCH`
+
+| Bump | When |
+|------|------|
+| `0.0.X` | Small fixes, typos, minor tweaks |
+| `0.X.0` | Bigger fixes, improvements, new minor features |
+| `X.0.0` | Major features, redesigns, breaking changes |
+
+Update both `version` AND `versionDescription` in `public/manifest.json` before each publish.
+</version-bump>
+
+<url-switch>
+## Switching the App URL to Production
+
+Publishing uploads files but does NOT update the app registry entry's URL. After publishing, switch the URL via MCP:
+
+```javascript
+manage_app({
+  action: 'update',
+  appId: "695816e2ba1d8bef3af7e018",
+  name: "My App Name",  // REQUIRED even when only updating URL — without it: code 191 "\"[1].name\" is required"
+  url: "https://apps.hailer.com/{workspaceId}/{appId}/"
+})
+```
+
+Verify with `list_apps()` — URL should be `https://apps.hailer.com/...`, not localhost.
+</url-switch>
+
+<sharing>
+## Sharing Apps
+
+```javascript
+// Entire workspace
+manage_app({ action: 'add_member', appId: "...", member: "network_{workspaceId}" })
+
+// Team
+manage_app({ action: 'add_member', appId: "...", member: "team_{teamId}" })
+
+// User
+manage_app({ action: 'add_member', appId: "...", member: "user_{userId}" })
+```
+
+**Pre-created app entry gotcha:** Apps published against a pre-created entry (via `manage_app({ action: 'create', ... })` before first publish) do NOT get the auto-share that `--create` performs. Members stay `[bot user]` only — the app is invisible in everyone's app list. After publishing to a pre-created entry, run `manage_app add_member` with `network_<wsId>` manually.
+
+**`"public": true` in the manifest** is required for `hailer.public.*` API methods and standalone loading. Without it the app won't load when accessed via a direct URL.
+</sharing>
+
+<vite-config>
+## Vite Base Path
+
+Required for production deployment:
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  base: './',  // required for production
+  // ... other config
+});
+```
+
+Without this, asset paths resolve to root domain — production returns 403/404 while localhost works fine.
+</vite-config>
+
+<cache-busting>
+## Browser Cache for Published Apps
+
+Published Hailer apps can serve stale versions from browser cache. Vite hashes JS/CSS filenames but `index.html` itself gets cached. Meta tags do NOT work in iframes — use a Vite plugin instead:
+
+```typescript
+// vite.config.ts
+function cacheBustPlugin(): Plugin {
+  return {
+    name: 'cache-bust-html',
+    enforce: 'post',
+    transformIndexHtml(html) {
+      const timestamp = Date.now();
+      return html.replace(
+        /(src|href)="([^"]+\.(js|css))"/g,
+        (match, attr, url) => `${attr}="${url}?v=${timestamp}"`
+      );
+    },
+  };
+}
+```
+
+Without this, users see old versions after publish — especially bad for bug fix deploys.
+</cache-busting>
+
+<gotchas>
+## Publish Gotchas
+
+### "The app was not found using: the provided API key" — Wrong-Workspace Key
+
+This error fires **after auth succeeds** — the key is valid but belongs to a different workspace. Root cause: `publish.cjs` resolves the key in order — `--user-api-key` flag → `HAILER_USER_API_KEY` env → `~/.env` via dotenv. Switching projects can leave a valid-but-wrong-workspace key in `~/.env`.
+
+**Primary fix — pass the project key file directly:**
+
+```bash
+npm run publish-production -- --env-file /absolute/path/to/project/.env --force
+```
+
+`publish.cjs` loads `--env-file` before `~/.env`; dotenv strips surrounding double quotes itself — fleet `.env` files store `HAILER_USER_API_KEY` double-quoted, and manual extraction without stripping sends a malformed key, which fails auth with **exit 8** and "Failed to authenticate. Check that your API key is valid and has access to this app." Caveat: if `HAILER_USER_API_KEY` is already exported in the shell, dotenv won't replace it — unset it first, or use `--user-api-key <key>` explicitly.
+
+### SvelteKit Manifest Path
+
+The CLI publish hardcodes `public/manifest.json`. SvelteKit apps use `static/manifest.json` — the CLI silently rejects them.
+
+### `manage_app update` Requires `name` Even for URL-Only Changes
+
+`manage_app({ action: 'update', appId, url })` without `name` fails loudly: `code 191, "\"[1].name\" is required"`.
+
+### `manage_app update` Config Shape
+
+The canonical shape the platform writes (and readers expect) is nested:
+
+```javascript
+manage_app({
+  action: 'update', appId, name, url,
+  config: { fields: { myKey: { value: "...", type: "string" } } }
+})
+```
+
+A flat `{ key: "value" }` config is accepted but readers looking for `config.fields.<key>.value` see nothing.
+
+### Sibling App Lint Failure Blocks Publish
+
+The lint gate runs across **all** apps before uploading. A broken lint script in a sibling app blocks publishing an unrelated app.
+
+### Hailer Caches Published Bundles Aggressively
+
+After publishing, hard refresh is often not enough. DevTools → Application → Clear storage → reload, then verify via the Network tab that the bundle response contains the new version string.
+
+### Directory URL Returns 403 — Not a Publish Failure
+
+`https://apps.hailer.com/<wsId>/<appId>/` returns 403 for the bare directory URL even for correctly published apps. `…/index.html` returns 200 and loads correctly. Inside the Hailer iframe this is never seen.
+</gotchas>
+
+<checklist>
+## Pre-Publish Checklist
+
+- [ ] manifest.json `appId` is 24 chars (not the placeholder — if placeholder, use `--create`)
+- [ ] manifest.json `version` is bumped from previous
+- [ ] manifest.json `versionDescription` describes what changed
+- [ ] vite.config.ts has `base: './'`
+- [ ] vite.config.ts has cache-bust plugin (see cache-busting section)
+- [ ] node_modules exists (dependencies installed)
+- [ ] `@hailer/app-sdk` is on latest version (`npm view @hailer/app-sdk version`)
+- [ ] After publish: `manage_app update` called to switch URL to production format
+</checklist>