@awesomate/hosting-mcp 0.22.0 → 0.22.2

package/dist/index.js

@@ -41224,7 +41224,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_site_create",
   {
-    description: "Create a WordPress site on the user's hosting. Plan limits are enforced server-side (429/403 with an upgrade hint if they're at their cap \u2014 relay it). Ask 'live or dev?' first per the awesomate-hosting skill. Returns the new site's admin details.",
+    description: "Create a WordPress site on the user's hosting. Plan limits are enforced server-side (429/403 with an upgrade hint if they're at their cap \u2014 relay it; 409 means WordPress already exists at that domain). Ask 'live or dev?' first per the awesomate-hosting skill. Omit `domain` and the next free siteN.{primary} subdomain is chosen for you. ASYNC and returns only {success:true} \u2014 no domain, no admin details: poll awesomate_list_sites to learn the name, and expect HTTPS to refuse connections for a minute or two while AutoSSL issues even though the site is already serving over http. See 'After creating a site' in the skill.",
     inputSchema: {
       domain: external_exports.string().optional().describe("Custom domain if they have one; omit for a default *.awesomate.site subdomain"),
       siteTitle: external_exports.string().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.22.0",
+  "version": "0.22.2",
   "description": "Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases",
   "license": "UNLICENSED",
   "type": "module",

package/skill/awesomate-hosting/SKILL.md

@@ -88,6 +88,24 @@ wrong account) · `references/connect-troubleshooting.md` (bootstrap, sandbox/
 proxy failures, resuming a connect, support report) ·
 `references/rest-fallback.md` (no `awesomate_*` tools — serve over REST) ·
 `references/voice.md` (how to talk to a non-technical owner).
+`references/wordpress-launch-checks.md` (what to MEASURE in a real browser after any theme,
+template or page deploy — boxed sections, missing logo/favicon, the post-domain re-key, http asset
+URLs — every item a defect an owner reported before the agent noticed).
+
+## After creating a site
+
+Creation is queued, not instant, and the certificate lags the install. For a
+minute or two afterwards `https://` refuses the connection while `http://`
+already returns real WordPress HTML — and `sslActive` in the site list may
+already read `true`, because it reports intent rather than the live cert.
+
+That combination is the expected intermediate state, not a contradiction and
+not a failed build. Confirm over plain HTTP, say the certificate is still
+issuing, and poll until HTTPS answers. Never delete and recreate the site or
+start debugging DNS on the strength of it.
+
+New sites come up on the host's default theme (`hello-elementor`). A fresh
+install is not evidence that a custom theme shipped.
 
 ## 0a. Tool map — reach for it when
 
@@ -100,7 +118,7 @@ proxy failures, resuming a connect, support report) ·
 | `awesomate_get_hosting_status` | Is hosting provisioned at all — eligible/provisioned flags, in-progress step, primary domain, DNS targets. Check before suggesting any site action |
 | `awesomate_get_hosting_account` | cPanel account details: package, server, provisioned-at, masked username |
 | `awesomate_list_sites` | What WordPress sites exist on this account |
-| `awesomate_site_create` | Spin up a new WordPress site (check limits first) |
+| `awesomate_site_create` | Spin up a new WordPress site (check limits first). Async — poll `awesomate_list_sites` for the name, and expect HTTPS to fail for a minute or two while AutoSSL issues; see **After creating a site** below |
 | `awesomate_list_domains` | What domains are attached, and to which site |
 | `awesomate_domain_add` | Attach a custom domain to a site |
 | `awesomate_dns_check` | Live answer to "where does this domain actually point" — before and after any DNS change |
@@ -295,6 +313,11 @@ scripts/deploy.sh --from ~/Studio/mysite --domain mysite.awesomate.site --with-d
 Never deploy without confirming with the user first, and always report the
 snapshot id and the verified live status.
 
+**"Verified live status" means a real browser at 390px and 1440px, not a 200 from curl.**
+Run the checklist in `references/wordpress-launch-checks.md` — full-bleed sections, gutters,
+logo and favicon present, fonts loaded, no broken images, a real 404 — before saying done. Every
+item on it was reported by a site owner after an agent had already said done.
+
 ## 5a. Staging on awesomate.dev (Support Plus+)
 
 The middle tier between "edit live" and "local Studio": a private full copy of

package/skill/awesomate-hosting/references/rest-fallback.md

@@ -26,5 +26,50 @@ GET with `Authorization: Bearer <pat>`:
 | `awesomate_list_domains` | `GET {apiBase}/api/client-hosting/domains` |
 | `awesomate_get_limits` | `GET {apiBase}/api/client-hosting/limits` |
 
+## Creating a site over REST
+
+`POST {apiBase}/api/client-hosting/sites` (JSON, same bearer) is the fallback
+for `awesomate_site_create`. Three things about it trip people up:
+
+- **The body field is `siteTitle`, not `title`.** An unknown key is ignored
+  silently, so the site ends up titled after its domain. `domain`, `themeSlug`,
+  `adminEmail` and `intent` are the other accepted keys; all are optional.
+- **Omit `domain` and the server picks the next free `siteN.{primary}`** —
+  the first install takes the bare primary domain, then `site2`, `site3`, and
+  so on. Pass `domain` explicitly if the user named one.
+- **The response is bare `{"success":true}`** — no domain, no id. It does not
+  tell you what got built, so read the name back from `GET /sites`.
+
+Refusals are specific and worth relaying verbatim: `403` means the plan's site
+cap is reached (staging clones are excluded from the count), `409` means
+WordPress already exists at that domain.
+
+## Provisioning is async — do not call it broken
+
+The POST returns as soon as the install is queued. Poll
+`GET {apiBase}/api/client-hosting/sites` until the new hostname appears rather
+than assuming the call failed.
+
+Then expect a **gap of a minute or two where HTTPS does not answer at all**
+while AutoSSL issues the certificate. During that window the symptom looks
+alarming but is normal and self-resolving:
+
+| Check | During issuance | Meaning |
+|---|---|---|
+| `curl https://…` | `000` / connection failed | Cert not issued **yet** |
+| `curl http://…` | `200`, real WordPress HTML | The site is genuinely built |
+| `dig +short` | resolves to the hosting IP | DNS is fine |
+| `/sites` `sslActive` | may already say `true` | Reports intent, not the live cert |
+
+So: an HTTPS failure straight after creation is not a failed build. Confirm
+over plain HTTP, tell the user the certificate is still issuing, and poll
+HTTPS until it answers. Do not delete and recreate the site, and do not go
+hunting through DNS or Cloudflare — `sslActive: true` alongside a dead HTTPS
+port is the expected intermediate state, not a contradiction.
+
+New sites come up on the host's default theme (currently
+`hello-elementor`). If the user asked for a custom theme, that is still ahead
+of you — the fresh install is not evidence their theme shipped.
+
 Serve the request with these now, then suggest restarting Claude Code at a
 natural break so the richer MCP integration loads.

package/skill/awesomate-hosting/references/wordpress-launch-checks.md

@@ -0,0 +1,108 @@
+# WordPress launch checks — what to verify after deploying a theme or content
+
+Every item here was a real defect that shipped to a live client site and was reported by the
+owner, not caught by the agent. Each one looked fine in the generated code and was only visible
+in a browser — so the rule is: **after any theme, template or page deploy, load the live site in a
+real browser at 390px and 1440px and MEASURE, before telling the user it is done.**
+
+## 1. Sections boxed with white strips at the sides (the "margins are off" report)
+
+**Symptom:** coloured section backgrounds stop short of the viewport edges, leaving white strips;
+on a phone the text sits hard against the coloured band with no gutter. The home page often looks
+fine while every inner page is wrong.
+
+**Cause:** the inner-page template gives the **post-content block its own `layout`**:
+`<!-- wp:post-content {"layout":{"type":"constrained"}} /-->`. That boxes every child group to
+`contentSize` and strips its side padding. A front page written as `<!-- wp:post-content /-->`
+(no layout) does not have the problem — which is why only some pages break.
+
+**Fix:** post-content carries **no layout attribute** in templates whose content is built from
+full-bleed section groups. Each section group is `{"layout":{"type":"constrained"}}` itself, so its
+background runs edge to edge while its content is constrained. Keep a constrained post-content
+only for deliberately narrow long-form templates (legal, single post), where every section is white
+anyway.
+
+**Measure it (Playwright, or DevTools console):**
+```js
+const g = document.querySelector('main .wp-block-group.has-background');
+const r = g.getBoundingClientRect();
+const fullBleed = r.left <= 1 && r.width >= innerWidth - 1;      // must be true
+const inset = g.querySelector('h1,h2,p').getBoundingClientRect().left - r.left; // ≥16 on a phone
+```
+
+Two related spacing faults usually travel with it:
+- **Every `<section>` converted to a 96px-top-and-bottom group.** A page header flowing into its
+  content then stacks 192px of dead space. Padding must follow the design's section types (a full
+  section, a page header, a bare container), not one flat value.
+- **WordPress's block gap opens a white line between two coloured bands.** Give section groups
+  `"margin":{"top":"0","bottom":"0"}`.
+- **A fixed root gutter** (`styles.spacing.padding` = 40px) is far too wide on a phone. Use a
+  responsive value, e.g. `min(40px, 5vw)`.
+
+## 2. Logo missing, no favicon
+
+**Symptom:** the header and footer show no logo at all; the browser tab has no icon.
+
+**Cause:** `<!-- wp:site-logo /-->` renders **nothing** until a logo is set in Site Identity
+(`custom_logo` theme mod), and no `<link rel="icon">` is emitted until `site_icon` is set. A fresh
+install has neither, and the media library is empty. On these hosts **SVG uploads are disabled**
+(`image/svg+xml` is not an allowed mime type), so the brand's SVGs cannot be uploaded as media.
+
+**Fix, both halves:**
+- Header/footer logos from the **theme's own files**, not media: make the header and footer
+  *patterns* (PHP) included from the parts —
+  `<!-- wp:pattern {"slug":"<theme>/header"} /-->` in `parts/header.html` — so the pattern can use
+  `get_theme_file_uri('assets/logos/logo.svg')`. This also lets the footer use the on-dark variant
+  while the header uses the primary, which a single Site Identity logo cannot do.
+- Still set Site Identity, because WordPress uses it elsewhere:
+  `wp media import logo.png --porcelain` → `wp theme mod set custom_logo <id>`;
+  `wp media import icon-512.png --porcelain` → `wp option update site_icon <id>`.
+  The site icon must be a **PNG, square, ≥512px** — make one from the brand emblem with
+  transparent padding rather than uploading a rectangular PNG.
+
+**Verify:** the live HTML contains an `<img alt="…">` in the header and `<link rel="icon"`, and both
+URLs return 200 with an image content type.
+
+## 3. The hub re-keys a site when a custom domain becomes its primary
+
+After a custom domain is attached and made primary, `GET /api/client-hosting/sites` reports the
+site under **the new domain** (`domain: example.com`), and per-site endpoints keyed by the old
+`siteN.<slug>.awesomate.site` name return **404** — including the snapshot call, which will abort a
+snapshot-first deploy that worked yesterday. Read `/sites` and use the `domain` it reports.
+
+## 4. Content seeded over WP-CLI stores `http://` asset URLs
+
+Pages created with `wp eval-file` / `wp post create` while the install is still on its
+`*.awesomate.site` address store theme asset URLs as `http://<install host>/...`. A later
+`wp search-replace https://<install host> https://example.com` misses every one of them because of
+the scheme. Replace on the **bare host**: `wp search-replace <install-host> example.com --all-tables
+--precise`, then recount with `LIKE '%<install-host>%'`.
+
+## 5. New pattern files render as nothing until the theme Version changes
+
+**Symptom:** you add `patterns/header.php` (or any new pattern) to a live theme, deploy it, and
+`<!-- wp:pattern {"slug":"theme/header"} /-->` renders an empty string — no error, no logo, nothing.
+Patterns that already existed keep working, which makes the new one look broken rather than
+unregistered.
+
+**Cause:** WordPress caches the theme's `patterns/` directory listing in a transient keyed by the
+theme's `Version:` header (`style.css`). A new file is not seen until that key changes.
+
+**Fix:** bump `Version:` in `style.css` on every deploy that adds, removes or renames a pattern
+file. Verified: the same deploy with `0.1.0 → 0.2.0` registered the patterns instantly. Treat the
+version bump as part of the deploy, not a release ceremony.
+
+## The launch checklist
+
+Run in a real browser against the LIVE domain, at 390 and 1440, before reporting done:
+
+1. Every coloured section is full-bleed (`getBoundingClientRect().left <= 1`) with text inset ≥16px.
+2. No horizontal overflow (`documentElement.scrollWidth <= clientWidth + 1`).
+3. Header shows the logo; `<link rel="icon">` is present; both URLs return 200.
+4. `document.fonts` reports the brand faces `loaded` (self-hosted fonts actually shipped).
+5. Zero broken images (`img.complete && naturalWidth > 0`), and zero assets still on the install host.
+6. A nonsense URL returns **404** with the theme's 404 template, not a 200 page.
+7. Section order matches the design (read the `h1,h2` sequence), and neither nav nor decorative
+   marks appear inside page content.
+8. If the deploy added pattern files, the theme `Version:` was bumped and every `wp:pattern`
+   in the parts actually rendered (an unregistered slug renders as empty, silently).