@awesomate/hosting-mcp 0.8.3 → 0.9.0

package/dist/index.js

@@ -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.9.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,32 @@ 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`.
 
 **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/stack-decision.md

@@ -13,13 +13,25 @@ confirm before building. **Never default to WordPress.**
 | 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