@awesomate/hosting-mcp 0.8.3 → 0.10.0

package/dist/index.js

@@ -40108,7 +40108,7 @@ readTool(
 );
 readTool(
   "awesomate_get_limits",
-  "Usage vs plan limits across every dimension (sites, custom domains, workflow credits, AI-editor credits) plus a nudges[] array. Call BEFORE any create action; when a nudge has severity 'approaching' or 'exceeded', surface it to the user with the recommended plan \u2014 never execute an upgrade without preview + explicit confirmation (upgrade tools ship in a later release; for now deep-link to the hub billing page).",
+  "Usage vs plan limits across every dimension (sites, custom domains, apps, database provisions today, workflow credits, AI-editor credits) plus a nudges[] array. Call BEFORE any create action; when a nudge has severity 'approaching' or 'exceeded', surface it to the user with the recommended plan \u2014 never execute an upgrade without preview + explicit confirmation (upgrade tools ship in a later release; for now deep-link to the hub billing page). pgProvisionsToday is a flat daily cap that resets within 24h \u2014 no plan raises it, so don't pitch an upgrade for it.",
   "/api/client-hosting/limits"
 );
 server.registerTool(
@@ -40207,12 +40207,12 @@ server.registerTool(
 server.registerTool(
   "awesomate_app_create",
   {
-    description: "Provision a new app on the client's cPanel account. Choose the stack deliberately (see the awesomate-app-builder skill): kind 'static' = a single fast landing/lead page served straight from the docroot (no DB, no server process \u2014 pick this for brochure/landing/lead-capture); kind 'node' = a dynamic app with a backend + database (logins, custom logic, an API). For node, dbEngine 'postgres' suits relational/JSON/AI-heavy data, 'mysql' is the simple default. Returns 202 immediately with an appId + subdomain(s); poll awesomate_app_get until status=active. Requires apps:write (Support Plus+) \u2014 a 403 means offer an upgrade. Get the user's confirmation on the stack + name before calling.",
+    description: "Provision a new app on the client's cPanel account. Choose the stack deliberately (see the awesomate-app-builder skill): kind 'static' = a single fast landing/lead page served straight from the docroot (no DB, no server process \u2014 pick this for brochure/landing/lead-capture); kind 'node' = a dynamic app with a backend + database (logins, custom logic, an API). Pick the template by job \u2014 'node-auth-sync' (user accounts/logins, MySQL), 'node-crud-postgres' (structured data without logins: trackers/dashboards \u2014 ready-made CRUD + UI, Postgres), 'node-api-only' (webhooks/integrations/glue, no DB wiring), 'static-landing' (marketing/lead page). If dbEngine is omitted the template's native engine is used (node-crud-postgres \u2192 postgres). Returns 202 immediately with an appId + subdomain(s); poll awesomate_app_get until status=active, then fetch the starter files with awesomate_app_scaffold. Requires apps:write (Support Plus+) \u2014 a 403 means offer an upgrade. Get the user's confirmation on the stack + name before calling.",
     inputSchema: {
       appSlug: external_exports.string().regex(/^[a-z][a-z0-9]{1,15}$/).describe("2-16 chars, starts with a letter, lowercase alphanumeric \u2014 used for subdomains + db names"),
       kind: external_exports.enum(["node", "static"]).default("node").describe("'static' for a landing/lead page (no DB); 'node' for a dynamic app"),
-      dbEngine: external_exports.enum(["mysql", "postgres"]).default("mysql").describe("node only \u2014 the database engine to provision"),
-      template: external_exports.string().optional().describe("Starter template (defaults: node \u2192 'node-auth-sync', static \u2192 'static-landing')")
+      dbEngine: external_exports.enum(["mysql", "postgres"]).optional().describe("node only \u2014 omit to use the template's native engine"),
+      template: external_exports.string().optional().describe("Starter template: node-auth-sync | node-crud-postgres | node-api-only | static-landing (defaults: node \u2192 'node-auth-sync', static \u2192 'static-landing'; full catalog in awesomate_app_context.templates)")
     }
   },
   async ({ appSlug, kind, dbEngine, template }) => {
@@ -40225,10 +40225,24 @@ server.registerTool(
     }
   }
 );
+server.registerTool(
+  "awesomate_app_scaffold",
+  {
+    description: "Fetch the app's starter files (its template rendered against the live app metadata \u2014 subdomains, control-plane URL, repo \u2014 with placeholders already substituted). Call after awesomate_app_create reaches status=active: write each returned file into a fresh local project folder at its relative path, then run npm install (Node apps) and follow the bundled CLAUDE.md. This is how the starter code gets onto the user's machine \u2014 don't reconstruct templates by hand.",
+    inputSchema: { appId: external_exports.number().int().positive().describe("The app id from awesomate_app_create / _list") }
+  },
+  async ({ appId }) => {
+    try {
+      return textResult(await hubGet(requireConfig(), `/api/my-apps/apps/${appId}/scaffold`));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
 server.registerTool(
   "awesomate_app_deploy",
   {
-    description: "Report how to deploy an app and its per-env targets. Node apps deploy via git push (dev/staging/main \u2192 GitHub Actions \u2192 cPanel); this returns the branch\u2192env map and subdomains. Use the awesomate-github skill to wire push-to-deploy the first time.",
+    description: "Report how to deploy an app, its per-env targets, last-deploy/health state, and how to promote (dev\u2192staging\u2192main) or roll back (git revert + push). Node apps deploy via git push (dev/staging/main \u2192 GitHub Actions \u2192 cPanel). Use the awesomate-github skill to wire push-to-deploy the first time.",
     inputSchema: { appId: external_exports.number().int().positive().describe("The app id") }
   },
   async ({ appId }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.8.3",
+  "version": "0.10.0",
   "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-app-builder/SKILL.md

@@ -70,21 +70,37 @@ target; never touch prod without an explicit ask.**
    you recommend. Get a yes.
 3. **Confirmation gate** — confirm the **name** (2–16 lowercase letters/digits,
    starts with a letter — becomes the subdomain + db names) and the **stack**,
-   then call `awesomate_app_create` (`appSlug`, `kind`, and for node `dbEngine`).
+   then call `awesomate_app_create` (`appSlug`, `kind`, `template`, and for
+   node optionally `dbEngine` — omit it to use the template's native engine).
+   Pick the template by job (stack-decision.md has the table): logins →
+   `node-auth-sync`; structured data, no logins → `node-crud-postgres`;
+   webhooks/integrations → `node-api-only`; landing page → `static-landing`.
    It returns **202** with an `appId` + subdomain(s); poll `awesomate_app_get`
    until `status` is `active` (or `failed` — read `provision_error`, explain
    plainly).
-4. **Implementation** — build the actual code/content locally against the
-   template. Handle **secrets** only via the **awesomate-credentials** skill
+4. **Scaffold** — call `awesomate_app_scaffold` and write each returned file
+   into a fresh local project folder at its relative path (placeholders are
+   already substituted), then `npm install` (Node) and read the bundled
+   `CLAUDE.md` — it's the app's own manual. Never reconstruct the starter by
+   hand.
+5. **Implementation** — build the actual code/content on top of the scaffold.
+   [references/node-recipes.md](references/node-recipes.md) has the recipes
+   (add a table/endpoint, env vars, connection strings, promote/rollback).
+   Handle **secrets** only via the **awesomate-credentials** skill
    (encrypted + injected, never committed/echoed). Wire **version control**
    from the first commit via **awesomate-github**. If it needs email/lookup/AI,
    attach n8n (§"when to use n8n").
-5. **Testing** — deploy to **dev** (`git push` to `dev`), then
+6. **Testing** — deploy to **dev** (`git push` to `dev`), then
    `awesomate_app_health` to confirm it came up (Node: `/api/ready`). Show the
    user the live dev URL and let them try it. Iterate on dev until they're happy.
-6. **Wrap-up / promote** — only when the user approves, promote **dev → staging
+7. **Wrap-up / promote** — only when the user approves, promote **dev → staging
    → main** (merge + push per branch). `awesomate_app_deploy` reports the
-   branch→env map. Prod is `main`.
+   branch→env map + last-deploy state. Prod is `main`. **Before merging to
+   main**, walk [references/security-checklist.md](references/security-checklist.md)
+   — the deploy workflow's automated gate blocks prod on high-severity
+   findings (secrets, injectable SQL, eval…), and the checklist covers what
+   a scanner can't (authorization, webhook secrets, data minimization).
+   Never remove the gate step to make a deploy pass — fix the finding.
 
 **Promote / rollback (git-based):** promoting is merging the tested branch
 forward (`dev`→`staging`→`main`); rolling back is `git revert` of the bad

package/skill/awesomate-app-builder/references/node-recipes.md

@@ -0,0 +1,83 @@
+# Node app recipes — the moves you'll make over and over
+
+Every scaffolded app carries its own `CLAUDE.md` (the authoritative manual for
+THAT app — read it first). These are the cross-app recipes, kept in the user's
+plain language.
+
+## Add a table / change the schema
+
+Never edit an already-deployed migration. Add a new file:
+
+```
+migrations/002_add_customers.sql
+```
+
+```sql
+CREATE TABLE IF NOT EXISTS customers (...);
+-- or: ALTER TABLE records ADD COLUMN amount NUMERIC NOT NULL DEFAULT 0;
+```
+
+Push it — the deploy workflow runs `npm run migrate` before restarting the
+app. Postgres templates apply each file in a transaction (a failure rolls
+back and retries next deploy); MySQL applies statement-by-statement, so keep
+MySQL migrations small.
+
+## Add an endpoint
+
+Copy the closest existing route in `src/index.ts` and keep its three habits:
+
+1. **zod-validate the input** before touching the DB or doing work.
+2. **Parameterized SQL only** — `$1`/`$2` (Postgres) or `?` (MySQL). Never
+   template user input into a SQL string.
+3. **Escape on render** — `textContent` in browser code, never `innerHTML`
+   with user data.
+
+## Connection strings / DB access
+
+Provisioning writes the server-side `.env` per env: `DATABASE_URL` +
+`DB_ENGINE`/`DB_HOST`/`DB_PORT`/`DB_NAME`/`DB_USER`/`DB_PASS`. The starters'
+lazy pool means local dev works with a blank `.env` (DB routes return 503
+with a clear reason). Postgres code should prefer `DATABASE_URL`.
+
+## Env vars & secrets
+
+- Runtime secret for the app → `awesomate_app_set_env` (encrypted in the hub,
+  injected into the server `.env`, pm2 restarted). Per-env; `dev` default.
+- Never commit `.env`, never echo a stored value, and per the
+  awesomate-credentials skill: a key pasted in chat gets stored AND flagged
+  for rotation.
+
+## Attach n8n as the backend
+
+Job needs email / a lookup in their connected apps / AI → build the webhook
+workflow with the awesomate-n8n skill, then `awesomate_n8n_attach_to_app`
+(stores `N8N_WEBHOOK_URL` + secret; returns the secret ONCE — add the
+matching `X-Awesomate-Webhook-Secret` header check to the workflow). The app
+calls `callWorkflow(payload)` from `src/lib/n8n.ts`; it no-ops when unset and
+never throws — check `result.ok` and degrade gracefully.
+
+## Deploy, promote, roll back
+
+- **Deploy** = `git push origin dev` (that's the whole mechanism). Watch with
+  `gh run watch`; verify with `awesomate_app_health`.
+- **Promote** = merge forward: `dev → staging → main`. Prod is `main`; go
+  through a PR from staging.
+- **Roll back** = `git revert <bad-sha>` on the affected branch + push — the
+  workflow redeploys the previous good state. Re-check health after.
+- `awesomate_app_deploy` reports the branch→env map, last-deploy SHA/time,
+  and last health per env.
+
+## Health semantics (don't mix these up)
+
+- `/api/health` — lenient, always 200, DB state in the body. For humans.
+- `/api/ready` — strict; 503 until the DB is reachable AND migrations ran
+  (DB templates). CI's post-deploy gate and what `awesomate_app_health`
+  probes. An app that was created but never pushed reports unreachable —
+  that's expected, not broken.
+
+## When something's off
+
+1. `gh run view --log-failed` — the deploy step that broke.
+2. `awesomate_app_health` — live per-env probe with a plain reason.
+3. The app's own `CLAUDE.md` troubleshooting section — engine-specific
+   diagnostics live there.

package/skill/awesomate-app-builder/references/security-checklist.md

@@ -0,0 +1,57 @@
+# Security checklist — walk this before promoting to prod
+
+Two layers guard prod. The **automated gate** runs in every app's deploy
+workflow (`scripts/security-check.mjs` — report-only on dev/staging,
+BLOCKING on `main`, plus `npm audit --audit-level=critical`). This checklist
+is the **human layer**: the things a scanner cannot see. Walk it with the
+user in plain language before merging staging → main.
+
+## What the automated gate already catches (don't re-litigate)
+
+Committed secrets / a tracked `.env` / private keys · SQL built by
+interpolation or concatenation · `eval` / `new Function` · shell exec with
+interpolated input · critical dependency advisories. If the prod deploy
+fails on the gate, read the Actions log — every finding prints its fix.
+**Never remove or bypass the gate step to make a deploy pass.**
+
+## The human checks (scanner-blind spots)
+
+1. **Authorization, not just authentication.** Logged-in is not allowed.
+   For every route that reads/writes data: could user A pass user B's id and
+   touch B's data? Filter by the session's user id server-side, never trust
+   an id from the request body.
+2. **Every input validated at the edge.** Each POST/PATCH handler starts
+   with a zod `safeParse`, with sane max lengths. No handler touches
+   `await c.req.json()` raw.
+3. **Secrets flow one way.** Values live in env vars (set via
+   `awesomate_app_set_env`), are never logged, never echoed in responses,
+   never sent to the browser.
+4. **Rendering is escape-safe.** Browser code uses `textContent` /
+   `createElement` for user data; server HTML never string-interpolates
+   user input without escaping.
+5. **The n8n webhook is not world-callable.** If n8n is attached, the
+   workflow checks the `X-Awesomate-Webhook-Secret` header (set during
+   attach). Test: call the webhook without the header — it must refuse.
+6. **Public API surface is intentional.** api-only starter: is `API_KEY`
+   set for prod, or is a public API genuinely intended? CORS open on
+   purpose?
+7. **Sensitive data is minimized.** Only collect what the app needs; if it
+   stores personal data, tell the user plainly: connections are TLS and
+   secrets are encrypted, but the DATABASE is not blanket-encrypted at
+   rest — sensitive fields deserve app-level encryption (ask before adding).
+8. **Errors don't leak.** 500 responses return a generic message, not stack
+   traces or SQL (the starters already do this — keep it).
+
+## Static sites
+
+No server code, so the gate doesn't run — the risks are the lead form's
+webhook (point 5) and third-party scripts (don't add any that aren't
+needed). Never put an API key in page JavaScript: anything in a static page
+is public.
+
+## How to talk about it
+
+Non-technical user — say what you checked, not the jargon: *"Before making
+it live I checked that people can only see their own data, that the contact
+form can't be abused, and that your API key never appears anywhere public.
+The deploy pipeline also scans every release automatically."*

package/skill/awesomate-app-builder/references/stack-decision.md

@@ -8,18 +8,30 @@ confirm before building. **Never default to WordPress.**
 
 | What the user is really trying to do | Stack | Why / how |
 |---|---|---|
-| "I already have a WordPress site" / a blog / publishes content regularly / **wants to rank on Google & AI** | **WordPress** | Best CMS for indexable content, sitemaps, schema. Hand to the awesomate-hosting skill to provision, then run **awesomate-seo**. |
+| "I already have a WordPress site" / a blog / publishes content regularly / **wants to rank on Google & AI** | **WordPress** | Best CMS for indexable content, sitemaps, schema. Hand to the awesomate-hosting skill to provision, then run **awesomate-seo**. Existing WP elsewhere → migrate it, don't rebuild: [wp-migrate.md](wp-migrate.md) (also covers WP ↔ app coexistence on subdomains). |
 | Sell products / online shop | **WordPress + WooCommerce** | Reuse the `woo-agent-storefront` (AI-shopping feeds + `llms.txt`) and `woo-catalog-perfection` skills. |
 | A landing page / capture leads / a one-pager / "just needs to look good and be found" | **static site** (`kind: 'static'`) | Served straight from the cPanel docroot — no database, no server process, fastest load. Add SEO + a lead form (below). The right default for marketing pages. |
 | A tool/app with **logins, custom logic, a dashboard, or an API** | **Node app** (`kind: 'node'`) | A real backend + database. |
 
+### Within a Node app: which starter template?
+Pick by the job (full catalog with descriptions: `awesomate_app_context.templates`):
+
+| Job | `template` | Ships with |
+|---|---|---|
+| People **sign in** / per-user data | `node-auth-sync` | signup/login (JWT + bcrypt), MySQL migrations |
+| Stores **structured data, no logins** — trackers, dashboards, internal tools | `node-crud-postgres` | ready-made records CRUD API + tiny UI, Postgres migrations (transactional) |
+| **Webhooks / integrations / glue** — receives or serves JSON, little state | `node-api-only` | versioned `/api/v1` routes, CORS, optional `x-api-key` gate, no DB wiring |
+
+All three include `src/lib/n8n.ts` and the same push-to-deploy workflow.
+
 ### Within a Node app: which database?
 - **postgres** — relational data with relationships, concurrency, JSON columns,
   or analytics/AI features. The modern default for a real app.
 - **mysql** — simple/legacy needs, or when they already know MySQL.
-- Provisioned automatically by `awesomate_app_create`; the app's `.env` gets
-  `DB_ENGINE`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASS`, and a
-  ready-to-use `DATABASE_URL`.
+- Omit `dbEngine` and `awesomate_app_create` uses the template's native engine
+  (`node-crud-postgres` → postgres). The app's `.env` gets `DB_ENGINE`,
+  `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASS`, and a ready-to-use
+  `DATABASE_URL` — even `node-api-only` gets one, sitting idle until wired.
 
 ## Questions that resolve the choice fast
 1. "Is this mainly a **page people read** (marketing, blog, shop) or a **tool

package/skill/awesomate-app-builder/references/wp-migrate.md

@@ -0,0 +1,60 @@
+# Moving an existing WordPress site to Awesomate (and WP ↔ app coexistence)
+
+When the stack decision lands on WordPress **and the user already has a WP
+site elsewhere**, don't rebuild it — migrate it. Plain-language framing:
+*"We'll make an exact copy of your current site on your Awesomate hosting,
+check it works, then point your domain at it. Your old site stays untouched
+until you're happy."*
+
+## The migration path
+
+1. **Provision WP on Awesomate first** — the awesomate-hosting skill's
+   normal WP install (their plan's site limit applies; check
+   `awesomate_get_limits`). This gives a working target with SSL.
+2. **Export from the old host.** Preference order:
+   - **A full-copy plugin** (Duplicator / All-in-One WP Migration): the user
+     installs it on their OLD site and downloads the archive — the only step
+     that happens outside Awesomate, so give them click-by-click guidance.
+   - **Host export**: many hosts offer a backup download (files + a `.sql`).
+   - **WP admin export (XML)**: last resort — content only (posts/pages/
+     media), loses theme/plugins/settings; expect to reassemble the look.
+3. **Import on Awesomate.** With shell access (Support Plus+) prefer
+   `wp-cli` over the target install: unpack files into the docroot, import
+   the DB, then `wp search-replace 'https://old-domain.com'
+   'https://new-domain.com' --all-tables` (serialized-data-safe — never do
+   this with raw SQL). Plugin archives restore through the same plugin
+   installed on the new site.
+4. **Verify before DNS.** Browse the copy on its Awesomate URL: pages,
+   images, forms, admin login, HTTPS. Run **awesomate-seo** (sitemap,
+   robots, meta) and offer the **wp-security-review** skill — a migrated
+   site imports its old plugins, and stale plugins are the top WP risk.
+5. **Cut over DNS** — point the domain at Awesomate (add it as a custom
+   domain first; plan limits apply). Old site stays live as the fallback
+   until the user confirms; propagation can take up to a day and both
+   copies serve during it (avoid content edits that day).
+6. **After cutover:** confirm SSL issued for the domain, re-run the SEO
+   check on the final URL, and remind them to cancel the old hosting only
+   once everything's verified.
+
+## WP ↔ app coexistence (they want both)
+
+The platform already separates them cleanly — **WordPress owns the main
+domain; every app lives on its own subdomain** (`app.domain.com`,
+`dev-app.domain.com`, …). No conflict: Apache routes the main site to WP's
+docroot and each subdomain to its app.
+
+- Marketing/blog/shop stays in WP; the tool their customers log into is the
+  Node app on a subdomain. Link between them with plain links.
+- Don't try to serve an app *under a WP path* (`domain.com/app`) — that
+  fights WP's rewrites. A subdomain is the supported shape.
+- Shared look: reuse the WP site's colors/logo in the app's UI rather than
+  loading WP themes into the app.
+- Shared backend jobs (a form on either side emailing/CRM-ing): both can
+  call the same n8n webhook — one workflow, two callers.
+
+## When NOT to migrate
+
+If the old "WP site" is really one landing page and they don't blog or
+sell: recommend rebuilding it as a **static site** on Awesomate instead
+(faster, nothing to update) — see stack-decision.md. Migration is for sites
+with real content, plugins, or a shop.