@hostinger/mcp 3.2.2 → 3.3.1

package/skills/headless/steps/05-design/logo-kit.mjs

@@ -0,0 +1,201 @@
+// Hostinger Headless — logo kit (step 05-design).
+//
+// Primitives for building a designed logo as outlined SVG: the letters become vector paths, so the
+// logo needs no web font and renders identically everywhere. The agent composes the design; this
+// file only does the parts that are easy to get wrong.
+//
+// Workflow (from ~/.hostinger/<domain>/brand/, so packages and this kit sit next to the build):
+//   cp <installed skill>/steps/05-design/logo-kit.mjs .
+//   npm init -y && npm i opentype.js @fontsource/<display-family-slug>
+//   node logo-build.mjs          // your script: import { … } from './logo-kit.mjs'
+//   rm -rf node_modules          // package.json keeps the deps; a redesign runs `npm i` again
+//
+// Packages resolve from the current working directory, so run the build from brand/.
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const requireFromCwd = createRequire(join(process.cwd(), 'logo-build.js'));
+const opentype = requireFromCwd('opentype.js');
+
+// @fontsource splits each weight into unicode subsets; `latin` alone has no ą č ę ė į š ų ū ž,
+// ő, ł, đ… so load every subset that exists and look each character up across them.
+const SUBSETS = ['latin', 'latin-ext', 'vietnamese', 'cyrillic', 'cyrillic-ext', 'greek', 'greek-ext'];
+
+function parseWoff(file) {
+  const buf = readFileSync(file);
+  return opentype.parse(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+}
+
+/**
+ * Load a static @fontsource weight (the static packages ship .woff, which opentype.js reads;
+ * variable packages ship only .woff2, which it can't). The returned font is the `latin` subset
+ * with `charToGlyph` widened to every other subset in the package, so accented letters resolve.
+ * @param {string} slug  family slug, e.g. "unbounded"
+ * @param {number} weight e.g. 900
+ */
+export function loadFont(slug, weight = 400, style = 'normal') {
+  const fonts = [];
+  for (const subset of SUBSETS) {
+    let file;
+    try {
+      file = requireFromCwd.resolve(`@fontsource/${slug}/files/${slug}-${subset}-${weight}-${style}.woff`);
+    } catch {
+      continue;
+    }
+    fonts.push(parseWoff(file));
+  }
+  if (!fonts.length) throw new Error(`logo-kit: @fontsource/${slug} has no ${weight} ${style} .woff files`);
+  const [primary] = fonts;
+  const own = primary.charToGlyph.bind(primary);
+  primary.charToGlyph = (ch) => {
+    for (const font of fonts) {
+      const glyph = font === primary ? own(ch) : font.charToGlyph(ch);
+      if (glyph.index) {
+        glyph.kitFont = font;
+        return glyph;
+      }
+    }
+    return own(ch);
+  };
+  return primary;
+}
+
+const num = (v) => {
+  if (!Number.isFinite(v)) throw new Error(`logo-kit: non-finite coordinate ${v}`);
+  return +v.toFixed(2);
+};
+
+/**
+ * Serialize an opentype Path to SVG path data. Use this instead of path.toPathData():
+ * opentype.js 2.0 emits "NaN" when a coordinate's fraction is a tiny float residue
+ * (its roundDecimal builds strings like "5.6e-14e+2"), and the browser silently stops drawing
+ * the path at the first NaN.
+ */
+export function toD(path) {
+  return path.commands
+    .map((c) => {
+      switch (c.type) {
+        case 'Z':
+          return 'Z';
+        case 'Q':
+          return `Q${num(c.x1)} ${num(c.y1)} ${num(c.x)} ${num(c.y)}`;
+        case 'C':
+          return `C${num(c.x1)} ${num(c.y1)} ${num(c.x2)} ${num(c.y2)} ${num(c.x)} ${num(c.y)}`;
+        default:
+          return `${c.type}${num(c.x)} ${num(c.y)}`;
+      }
+    })
+    .join('');
+}
+
+/**
+ * Lay out a string with kerning. Positions are relative to x = 0 on the baseline.
+ * One glyph per character: no ligatures or other substitutions, so `char` always matches its glyph
+ * (and fonts whose substitution tables opentype.js can't run still work).
+ * @returns {{ glyphs: { glyph, char: string, x: number, width: number }[], width: number, ascent: number, capHeight: number, xHeight: number }}
+ */
+export function layout(font, text, size, { tracking = 0 } = {}) {
+  const scale = size / font.unitsPerEm;
+  const chars = [...text];
+  const glyphs = chars.map((ch) => font.charToGlyph(ch));
+  glyphs.forEach((glyph, i) => {
+    if (!glyph.index && chars[i].trim()) {
+      throw new Error(`logo-kit: "${chars[i]}" is not in this font (it would render as an empty box); pick a font that has it`);
+    }
+  });
+  let x = 0;
+  const out = glyphs.map((glyph, i) => {
+    // Kerning pairs only exist inside one subset file; across subsets the indexes don't match.
+    if (i && (glyphs[i - 1].kitFont ?? font) === (glyph.kitFont ?? font)) {
+      const kern = font.getKerningValue(glyphs[i - 1], glyph);
+      x += (Number.isFinite(kern) ? kern : 0) * scale + tracking;
+    }
+    const item = { glyph, char: chars[i] ?? '', x, width: glyph.advanceWidth * scale };
+    x += item.width;
+    return item;
+  });
+  const capHeight = (font.tables.os2?.sCapHeight || font.ascender * 0.7) * scale;
+  const xHeight = (font.tables.os2?.sxHeight || font.ascender * 0.5) * scale;
+  return { glyphs: out, width: x, ascent: font.ascender * scale, capHeight, xHeight };
+}
+
+/**
+ * Tight bounding box of a word's outlines at (x, baselineY), before any transform. Use it to size
+ * the viewBox; add room for outlines, shadows and rotations yourself.
+ * @returns {{ x1: number, y1: number, x2: number, y2: number }}
+ */
+export function pathBox(font, text, x, baselineY, size, opts) {
+  const path = new opentype.Path();
+  for (const g of layout(font, text, size, opts).glyphs) path.extend(g.glyph.getPath(x + g.x, baselineY, size));
+  return path.getBoundingBox();
+}
+
+/** Path data for one glyph with its origin at (x, baselineY). */
+export const glyphPath = (glyph, x, baselineY, size) => toD(glyph.getPath(x, baselineY, size));
+
+/** Path data for a whole string starting at (x, baselineY). */
+export function textPath(font, text, x, baselineY, size, opts) {
+  return layout(font, text, size, opts)
+    .glyphs.map((g) => glyphPath(g.glyph, x + g.x, baselineY, size))
+    .join('');
+}
+
+/**
+ * Set text around a circle (seals, badges). Each glyph is centred on its arc position and rotated
+ * to stand on the circle. `fill: true` stretches the spacing so the text closes the full ring.
+ * @returns {{ d: string, transform: string, char: string }[]} style each glyph however you like
+ */
+export function arcText(font, text, { cx, cy, r, size, startDeg = -90, fill = true }) {
+  const { glyphs, width, capHeight } = layout(font, text, size);
+  const k = fill ? (2 * Math.PI * r) / width : 1;
+  const offset = fill ? 0 : -width / 2; // centred on startDeg when not filling
+  return glyphs.map((g) => {
+    const along = (g.x + g.width / 2 + offset) * k;
+    const angle = along / r + (startDeg * Math.PI) / 180;
+    const px = cx + r * Math.cos(angle);
+    const py = cy + r * Math.sin(angle);
+    const deg = (angle * 180) / Math.PI + 90;
+    return {
+      d: glyphPath(g.glyph, -g.width / 2, capHeight / 2, size),
+      transform: `translate(${num(px)} ${num(py)}) rotate(${num(deg)})`,
+      char: g.char,
+    };
+  });
+}
+
+/**
+ * The outlined "cut-out" treatment: an ink outline drawn behind the fill (paint-order) plus an
+ * optional hard offset shadow. `shadowColor` defaults to the ink; set it separately on dark
+ * backgrounds, where a dark ink outline vanishes but a coloured shadow still reads.
+ * Returns SVG markup.
+ */
+export function sticker(d, { fill, ink = '#000', strokeWidth = 8, shadow = 8, shadowColor = ink, transform = '' }) {
+  const t = transform ? ` transform="${transform}"` : '';
+  const shade = shadow
+    ? `<path d="${d}" fill="${shadowColor}" stroke="${shadowColor}" stroke-width="${strokeWidth}" stroke-linejoin="round" transform="translate(${shadow} ${shadow})"/>`
+    : '';
+  return `<g${t}>${shade}<path d="${d}" fill="${fill}" stroke="${ink}" stroke-width="${strokeWidth}" stroke-linejoin="round" paint-order="stroke"/></g>`;
+}
+
+/** Root SVG with an accessible name. Pass a distinct `id` if two logos are inlined on one page. */
+export function svgDoc({ width, height, title, body, id = 'logo-title' }) {
+  const esc = String(title).replace(/&/g, '&amp;').replace(/</g, '&lt;');
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${num(width)} ${num(height)}" role="img" aria-labelledby="${id}"><title id="${id}">${esc}</title>${body}</svg>`;
+}
+
+/**
+ * Validate a finished SVG string before writing it. Throws on: NaN/undefined/Infinity in the
+ * markup, live <text> (the logo must be outlined), a missing <title>, or a missing viewBox.
+ * @returns {{ bytes: number }}
+ */
+export function check(svg) {
+  const problems = [];
+  if (/NaN|undefined|Infinity/.test(svg)) problems.push('contains NaN/undefined/Infinity');
+  if (/<text[\s>]/.test(svg)) problems.push('contains <text>; outline the letters with textPath/glyphPath');
+  if (!/<title[^>]*>[^<]+<\/title>/.test(svg)) problems.push('missing <title>');
+  if (!/viewBox="0 0 [\d.]+ [\d.]+"/.test(svg)) problems.push('missing or invalid viewBox');
+  if (problems.length) throw new Error(`logo-kit check failed: ${problems.join('; ')}`);
+  return { bytes: Buffer.byteLength(svg) };
+}

package/skills/headless/steps/06-frontend/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: headless-step-frontend
+description: "Step 6 (frontend) of the Hostinger Headless flow. Builds the website that renders the backend's content. Figures out (or confirms) the framework — defaulting to Next.js SSR — implements the look already chosen in design.md (the design step's contract), and builds the source into src/. Only ask for the clarifications you actually need."
+---
+
+# headless-step-frontend
+
+Build the site's frontend against the backend from `site.json`, implementing the look the design step
+already chose and wrote to **`design.md`** (plus the logo in `brand/`). The design is decided; this step
+is where it becomes real code. There's no per-framework recipe — use good judgement, follow `design.md`
+as the contract, and ask only for the clarifications you genuinely need. **Out:** source in the site
+workspace `~/.hostinger/<domain>/src/`.
+
+> ## ⚠️ Build mode: "Bring your own frontend"? Read this first (any backend)
+> Read `brief.md` → **Build mode**. When it is **Bring your own frontend**, the user already has a
+> frontend (the project in the folder the command was run in) and this step **wires it to the backend
+> from `site.json` — it does not scaffold a new project and there is usually no `design.md` to
+> implement** (the design step deferred to the user). **Use their project as the source**: copy or
+> point `~/.hostinger/<domain>/src/` at it, keep its framework and UI, and collaborate on changes at
+> the user's direction (vibe-code with them). Your job is to connect it to the live backend (WordPress
+> `wp/v2` reads, the WooCommerce/Ecommerce Store API, env/keys) and make it deployable (set
+> `engines.node` to `22`, remove any `.htaccess`), then hand off to deploy. This generalises the Webapp
+> "existing app" case below to WordPress and Ecommerce too. When **Build mode is "Agent designs and
+> builds"**, ignore this box and proceed normally (scaffold + implement `design.md`).
+
+> ## ⚠️ Webapp backend? Read this first
+> A `webapp` brief has **no CMS/store and no `content-model.md`** — the app owns its own data (its own
+> API, or the MySQL database recorded in `site.json → database`). It comes in two shapes, decided back in
+> **refine**:
+>
+> - **An existing app the user brought to deploy** (refine routes "deploy my app" here). **Use their
+>   project as the source** — copy/point `~/.hostinger/<domain>/src/` at it and keep its own framework and
+>   UI. **Do not scaffold a new project, and do not re-implement `design.md` over it** (so **the design
+>   step does not apply** to an app that brings its own UI). Your job is only to make it deployable: set
+>   `engines.node` to `22`, remove any `.htaccess`, wire its data/env, then hand off to deploy. **Skip the
+>   Step 2 design pass**, and ignore the `content-model.md` requirement in Step 3.
+> - **A new app built from the brief.** Scaffold and build it from `brief.md` (and `design.md` if the
+>   design step produced one — design *does* run for a from-scratch app). Its data is owned by the app, so
+>   there is still **no `content-model.md`** to bind against.
+>
+> Framework choice (Step 1), the build, and hand-off (Step 4) apply to both. The per-backend bullets in
+> Step 3 are **WordPress / WooCommerce / Ecommerce only** — for a webapp follow the Webapp bullet there.
+
+## Step 1 — Pick the framework (guess → default → confirm)
+
+**The rendering is already decided in `brief.md` → Rendering** (SSR or SSG, set during refine). Honour
+it, and the backend constraint:
+
+- **Ecommerce → SSR required** (carts/search need per-request rendering). Any SSR framework works —
+  Next.js is the default, not a requirement (Express, Nuxt, SvelteKit, etc. are all fine).
+- **WordPress + WooCommerce → SSR required** (same reason — cart/checkout need per-request rendering).
+- **WordPress → SSG (Astro)** when the brief says SSG, otherwise **SSR (Next.js default)**.
+- **Webapp → the app's own stack.** An **existing app** keeps its current framework (don't impose one); a
+  **new app** uses whatever fits the brief (SSR or SPA). Either way it deploys as a Node.js app (Step 8) —
+  an SSR app runs a server, a SPA builds to static output.
+- Map rendering → framework: **`ssr` → Next.js**, **`ssg` → Astro** — unless the brief/prompt explicitly
+  names another supported framework, in which case use that.
+
+Supported frameworks (what the Hostinger build pipeline can deploy — the `app_type` in Step 8 deploy):
+
+- **Server/SSR-capable:** Next.js, Nuxt.js, Astro, SvelteKit, Express, NestJS, Fastify.
+- **Static / SPA:** React, Vue, Angular, Vite, Parcel, Preact, Svelte, (Astro / SvelteKit static too).
+
+Confirm the framework with the user in one line only if the brief left it open. Record the choice in
+`state.json`:
+
+```json
+{ "frontend": { "framework": "nextjs", "rendering": "ssr" } }
+```
+
+If the brief is silent, default to **Next.js SSR**. Ecommerce must be SSR (never SSG) — but the SSR
+framework itself is free to be any supported one, not just Next.js.
+
+## Step 2 — Implement `design.md` (don't re-design)
+
+The look was already chosen and written by the design step. **Read `~/.hostinger/<domain>/design.md` and
+implement it faithfully** — tokens (colour, type, spacing), components, per-page composition, imagery and
+accessibility — plus the logo files in `brand/`. Don't re-run design questions or invent a new direction here.
+
+- Treat `design.md` as the contract: the built pages should match its tokens, type scale, components and
+  per-page composition, and the 8-point grid / WCAG 2.2 AA rules it carries.
+- Use the **logo** from `brand/` as-is (wordmark, icon mark, favicon); never recolour or redraw it.
+- If `design.md` is **missing** (e.g. a resumed older build), fall back to `brief.md → Design direction`
+  (reference site, colours, brand, adjectives) and a tasteful, accessible default — but prefer `design.md`
+  whenever it exists.
+- **Don't gate on approval here** — the result is shown at **validate** (Step 7).
+
+**Only ask about the code, and only if it matters** (design decisions belong in the design step):
+- Where the **source should live** — default `~/.hostinger/<domain>/src/`; ask only if they want a
+  specific folder or an existing repo.
+- **Git** — initialise / connect / push (default: a local project, no remote).
+- A specific **component library** or technical must-have, if they implied one.
+
+## Step 3 — Build against the backend
+
+Two phases around the instance barrier (see the top-level `SKILL.md`): scaffold + build the shell while
+provision settles, then wire live data once `provision.status == "completed"`.
+
+Read the backend from `site.json`:
+
+- **WordPress** → `urls.rest_api` (`wp/v2`), public read. Content is in the posts/pages/categories/media
+  the content-model push created; nav/plan come from `content-model.md`. Map each item's **SEO** from its
+  `yoast_head_json` into the page `<head>` (title, description, Open Graph, JSON-LD schema) — Yoast is
+  installed by default at provision (`site.json → seo.enabled: true`). If `seo.enabled` is `false`
+  (Yoast absent), fall back to generating per-page title/description/OG tags from each item's content.
+- **WordPress + WooCommerce** (`site.json → woocommerce.enabled: true`) → the WordPress bullet above **plus**
+  the store. Read the catalog over the **public WooCommerce Store API** (`site.json → urls.store_api`,
+  `/cms/wp-json/wc/store/v1`, no auth, open CORS): `GET /products` (prices are **integer minor units** on
+  `prices.price` with `prices.currency_minor_unit` — divide to display), `GET /products/categories`. Cart,
+  coupons and checkout are **client-side** against the Store API with the `Nonce` + `Cart-Token` headers
+  (`GET /cart`, `POST /cart/add-item`, `/cart/apply-coupon`, `POST /checkout`) — see
+  `../04-content-model/wordpress/woocommerce.md`. **Never embed a consumer key client-side**; the
+  storefront is fully public. Blog/pages on the same site still come from `urls.rest_api` (`wp/v2`) + Yoast.
+  - **Honour `site.json → woocommerce.payment_enabled`.** It is `false` until the owner enables a payment
+    gateway + shipping in wp-admin (that config isn't reachable headlessly — see the provision note). While
+    `false`, build the full catalog, product pages and the client-side cart as normal, but render a
+    graceful disabled-checkout state (e.g. a disabled "Checkout" with "Checkout isn't set up yet"), **don't
+    call `/checkout`**, and don't treat it as a build error. When `true`, wire checkout (`payment_method`
+    `"cod"` works out of the box).
+- **Ecommerce** → the **public Hostinger Storefront Core V2 API** (`https://api-ecommerce.hostinger.com/v2`,
+  no auth, open CORS), keyed on the **custom sales channel** (`site.json → ecommerce.sales_channel.id`):
+  `GET /channels/<scha_*>/products` (prices are **minor units** on variants), `POST /channels/<scha_*>/checkout`
+  for buying. Cart is client-side; never embed a token. Read
+  `ecommerce_miscellaneous_custom-storefront-setup-instructions` for the authoritative, current guide.
+  - **Honour `site.json → ecommerce.payment_enabled`.** When it is `false` (free account / no paid
+    Ecommerce plan — see the provision gate), there is **no checkout**: build the full catalog, product
+    pages and the client-side cart as normal, but **do not call the checkout endpoint**. Instead render
+    a clear, graceful state at the checkout step — e.g. a disabled "Checkout" button with a short note
+    like "Online checkout isn't available on this plan yet" (and/or a contact/enquiry fallback). A
+    missing checkout is **not** a build error here — never leave the storefront half-built, throw, or
+    retry checkout because payment is off. When `payment_enabled` is `true`, wire checkout normally.
+- **Webapp** → **no `content-model.md` and no headless backend to read**. The app uses its own data source:
+  the MySQL database from `site.json → database` (through the `DB_*` / `DATABASE_URL` env vars — set at
+  provision/deploy, see `../03-provision/webapp/SKILL.md` Step 3; `127.0.0.1` only resolves on the server,
+  not locally), or whatever external API the app calls. For an existing app, keep its data layer as-is.
+
+Guidelines (framework-agnostic):
+
+- **One data module** is the single place that talks to the backend (e.g. `src/lib/data.ts`) — one file
+  to inspect, one base URL to switch. Keep it swappable so the shell can build against stubs first.
+- **Fetch at request time for SSR** (fresh content, no rebuild); a static build fetches at build time.
+- **A failed or incomplete fetch is an error, not a silent empty/placeholder.** Planned content missing
+  from the API is a build error too — a site that builds with holes ships with holes. *(WordPress/Ecommerce;
+  a webapp has no planned content to check.)*
+- **`content-model.md` is the source for what should exist** (pages, nav, collections mapping) — for
+  WordPress/Ecommerce only; a **webapp has no `content-model.md`**.
+- **No `.htaccess`** in the project (deploy would overwrite the live one); don't commit `node_modules`
+  or build output.
+- Set `engines.node` to `22` (the deploy builds on Node 22).
+
+## Step 4 — Hand off
+
+Confirm the project builds clean locally against the live backend, no placeholder/fixture content
+remains, and `state.json → frontend` matches what you built. Update `state.json` (`stage: "validate"`).
+Validate (Step 7) owns the clean rebuild + user preview; deploy (Step 8) ships it with the `app_type`
+and output directory that match the chosen framework + rendering.
+
+> **Webapp:** just confirm the app builds clean and `state.json → frontend` is right — there's no
+> `content-model.md` or headless backend to check. A DB-backed app can't reach its database locally
+> (`127.0.0.1` is server-only), so its data layer is verified **after** deploy, not here.

package/skills/headless/steps/07-validate/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: headless-step-validate
+description: "Step 7 (validate) of the Hostinger Headless flow. OPTIONAL quick gate before deploy: every prior stage already self-verifies, so this is a fast confirmation (instance live + backend API answers with seeded content) plus optional local preview and user sign-off. Skip the heavy parts when nobody needs to approve."
+---
+
+# headless-step-validate
+
+> **Optional / fast.** Every stage before this one already verifies its own work (provision checks the
+> backend, content-model push checks the REST counts, frontend builds clean), and **deploy verifies the
+> live result**. So validate is **not** a re-run of all that — it's a quick confirmation, plus the
+> optional human preview/sign-off. **Skip Steps 3–4 (rebuild + approval) entirely** on an autonomous or
+> temp-domain run where no one is signing off; just do the two 10-second checks below and move on. Spend
+> time here only when a person wants to see it before it goes live.
+
+**In:** project in `~/.hostinger/<domain>/src/`, `site.json`, `state.json`.
+
+## 1 — Instance status (always, quick)
+
+`provision.status == "completed"` **and** re-verify against the connector:
+`hosting_websites_list-setups { "domain": "<domain>" }`, exact-match the row → `completed`. Anything
+else → not ready; return to the instance barrier, don't deploy.
+
+## 2 — Backend API status (WordPress / WooCommerce / Ecommerce, always, quick)
+
+Hit the live API from `site.json` and confirm it answers **with the content the push created** — a 200
+with an empty catalog means the push didn't land:
+
+- **WordPress:** `GET {urls.rest_api}/posts?per_page=1` → 200 JSON array; check `X-WP-Total` against the
+  planned post count, and `GET {urls.rest_api}/media?per_page=1` → `X-WP-Total` matches the planned
+  image count (more = duplicates).
+- **WordPress + WooCommerce** (`site.json → woocommerce.enabled`): the WordPress check above **plus**
+  `GET {urls.store_api}/products?per_page=100` → 200 with the seeded products and `prices` (minor units);
+  count matches the plan. Don't test checkout while `woocommerce.payment_enabled` is `false`.
+- **Ecommerce:** query `urls.storefront_api` for the sales channel → 200 with the seeded products and
+  prices *(confirm against the store)*.
+
+Fail or counts off → fix content-model push before building against live data.
+
+## 3 — Clean rebuild against the live API (optional — skip unless signing off)
+
+Frontend already produced a clean build; only redo this if you want a from-scratch guarantee before a
+human sign-off. Remove the build output and rebuild; a failed or incomplete build is a stop (no
+fixtures, placeholder copy or `.htaccess` in the output).
+
+- **Astro (SSG):** `rm -rf dist && npm run build && npm run check:dist`.
+- **Next.js (SSR):** `rm -rf .next && npm run check && npm run build`.
+
+## 4 — Preview & approval (optional — only when a person is signing off)
+
+When someone wants to see it first: start the local preview (Astro: `npm run preview`; Next.js:
+`npx next start`), check desktop and mobile widths, navigation and a couple of key routes, and present
+it for **explicit approval**. If preview tooling is unavailable, give the user the command and URL.
+On an autonomous or temp-domain run, skip this — deploy will verify the live result anyway.
+
+Then (after approval, or immediately if 3–4 were skipped): `state.json` → `stage: "deploy"`, fresh
+`updated_at`; leave `provision` unchanged.

package/skills/headless/steps/08-deploy/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: headless-step-deploy
+description: "Step 8 (deploy) of the Hostinger Headless flow. Archives the frontend source, then deploys through the connector's one-shot hosting_deploy (type nodejs — it uploads the source, runs npm install and the build on the server) with the chosen framework's build settings (appType + output dir) passed explicitly, polls to completion with hosting_get-deployment, verifies the live site and that the backend survived, then writes deploy.json."
+---
+
+# headless-step-deploy
+
+Ship the frontend to the live domain through the Hostinger connector. You hand the connector a zip of
+the project **source** and it uploads it, runs `npm install` + the build script on the server, and
+serves the result. **Out:** `deploy.json`.
+
+This is an **instance-barrier** step: run it only after `provision.status == "completed"` and validate
+(if run) has passed. All operations go through the connector (`execute`).
+
+**In:** the project in `~/.hostinger/<domain>/src/`, `site.json` (`username`, `urls`), `state.json`
+(`frontend.framework`, `frontend.rendering`).
+
+> ## ⚠️ The one rule that makes this work: pass build settings explicitly
+> If you let `hosting_deploy` **auto-detect** build settings, for a headless site that detection returns
+> **null** (`appType:null`, `outputDirectory:null`, Node 20) — the build "completes" but the **root
+> serves 403** (no `appType`/output → the vhost serves a directory with no entry). This is reproducible.
+> **Always pass `appType`, `outputDirectory`, `nodeVersion`, `buildScript`, `packageManager` and
+> `rootDirectory` on the `hosting_deploy` call** with the framework's values; the deploy then resolves
+> them and serves correctly, and `/cms` is preserved.
+
+## Build configurations
+
+Map `frontend.framework` (from `state.json`) to its `appType` + build output directory, and pass those
+on the `hosting_deploy` call. `appType` is the framework's value, e.g. `next`, `nuxt`, `astro`,
+`svelte-kit`, `nest`, `express`, `fastify`, `react`, `create-react-app`, `gatsby`, `vite`, `vue`,
+`angular`, `parcel`, `svelte`, `other`.
+
+Common cases (all `nodeVersion: 22`, `buildScript: "build"`, `packageManager: "npm"`, `rootDirectory: "."`):
+
+| Framework / mode | Local config | `appType` | `outputDirectory` |
+|---|---|---|---|
+| **Next.js — SSR** *(default)* | `output: 'standalone'` | `next` | `.next` |
+| **Nuxt — SSR** | default | `nuxt` | `.output` |
+| **SvelteKit — SSR** | node adapter | `svelte-kit` | `build` |
+| **Astro — static** | `output: 'static'` | `astro` | `dist` |
+| **Vite / React / Vue — static (SPA)** | — | `vite` (or `react`/`vue`) | `dist` |
+| **Express / NestJS / Fastify — server** | — | `express`/`nest`/`fastify` | build output dir |
+
+SSR/server frameworks run a persistent Node process (root sends `x-powered-by` / `cache-control: no-store`);
+static frameworks serve their output dir as files. If unsure of a framework's output dir, check the
+framework's own build output, but **always pass `appType`/`outputDirectory` on the deploy call with the
+framework's correct values** — don't rely on auto-detection (it returns null → 403).
+
+## Step 1 — Pre-flight
+
+1. **Instance live.** `provision.status == "completed"`, re-verified with
+   `hosting_websites_list-setups { "domain": "<domain>" }`.
+2. **Build output exists locally** (the framework's output dir — e.g. `.next/`, `dist/`, `.output/`) and
+   the project builds clean (frontend/validate already did this). If not, go back.
+3. **Env vars (only if used).** Build-time vars (e.g. `NEXT_PUBLIC_*`) must be set **before** the build
+   with `hosting_nodejs_replace-environment-variables` (full replace). Never put secrets in the repo or
+   the archive. **Webapp with a database:** that full replace wipes the `DB_*`/`DATABASE_URL` that
+   `hosting_databases_setup-website` injected (the generated password reads back masked), so set all app
+   vars in the same replace and, if you can't, first reset the password with
+   `hosting_databases_change-password` and resend every `DB_*`/`DATABASE_URL` — see
+   `../03-provision/webapp/SKILL.md` Step 3.
+
+## Step 2 — Archive the source
+
+Zip the project **source** with `package.json` at the archive root. **Include** the app/source,
+`public/`, the framework config (`next.config.mjs` / `astro.config.mjs`), `tsconfig.json`,
+`package.json`, `package-lock.json`, `.nvmrc`. **Exclude** `node_modules/`, the build output
+(`.next/`, `dist/`, `out/`), `.git/`, and any `.htaccess` — the server installs and builds from source.
+
+```bash
+cd ~/.hostinger/<domain>/src
+zip -r -X ../app.zip . -x 'node_modules/*' '.next/*' 'dist/*' 'out/*' '.git/*' '**/.htaccess'
+```
+
+## Step 3 — Deploy (one shot: settings + upload + build)
+
+Pass the framework's build settings **inline** on the deploy call — there is no separate settings step.
+`path` is the archive from Step 2 (or the source directory itself; `hosting_deploy` archives a directory
+for you, skipping `node_modules/`, `.git/` and `.env`, but it does **not** read `.gitignore`, so the
+build output must already be absent).
+
+```json
+{ "operation": "hosting_deploy",
+  "params": {
+    "domain": "<domain>",
+    "path": "/absolute/path/to/.hostinger/<domain>/app.zip",
+    "type": "nodejs",
+    "appType": "<framework appType, e.g. next>",
+    "outputDirectory": "<framework output dir, e.g. .next>",
+    "nodeVersion": 22,
+    "buildScript": "build",
+    "packageManager": "npm",
+    "rootDirectory": "." } }
+```
+
+`hosting_deploy` uploads the source and triggers `npm install` + the build **end-to-end** — do not call
+any upload or build operation yourself. It returns a build `buildUuid` at once. This **overwrites the
+website root** (expected) and keeps `/cms` intact. Passing `appType`/`outputDirectory` explicitly is what
+keeps the root from serving 403 (see the rule above).
+
+## Step 4 — Poll to completion
+
+Poll `hosting_get-deployment { "domain": "<domain>", "buildUuid": "<buildUuid>" }` with backoff until
+`build.state` is `completed`. On `failed`, the same response carries the end of the build log and the
+failure analysis — read it, fix locally, re-archive and redeploy (pass `fromLine`, the line count from
+the previous call, to read only new log output). `hosting_get-deployment` also returns the build settings
+stored for the site: `appType`/`outputDirectory`/`nodeVersion` should echo what you passed; if they read
+`null`, the settings didn't take — fix the deploy call before continuing. For an SSR app that built but
+hangs, `hosting_nodejs_restart-application { username, domain }` recovers the server without a rebuild.
+
+## Step 5 — Verify the live site (all must pass)
+
+| Check | How | Expect |
+|---|---|---|
+| Root serves | `GET https://<domain>/` | **200** (not 403 / 404) |
+| SSR is live *(server frameworks)* | response headers | `x-powered-by` present, `cache-control: no-store` |
+| Static serves *(static frameworks)* | `GET https://<domain>/` | 200 HTML with real home content |
+| Key routes | a couple of planned routes + one deep route | 200, real content |
+| **Backend survived** *(WordPress / WooCommerce)* | `GET https://<domain>/cms/wp-json/wp/v2/posts?per_page=1` | 200 |
+
+> **Only WordPress (including WordPress + WooCommerce) has a `/cms` on the domain**, so the *Backend
+> survived* check is WordPress-only.
+> - **WordPress + WooCommerce:** also confirm the store survived the deploy —
+>   `GET https://<domain>/cms/wp-json/wc/store/v1/products?per_page=1` → 200. There is nothing external to
+>   link (no sales-channel step — that's Ecommerce only). **Checkout** stays owner-completed: when
+>   `site.json → woocommerce.payment_enabled` is `false`, don't test `/checkout`; a catalog that serves 200
+>   is a passing, complete deploy.
+> - **Ecommerce:** the backend is the **Hostinger Ecommerce store**, read over the external Storefront API
+>   (`api-ecommerce.hostinger.com`) — nothing a deploy touches lives on this domain. There is no `/cms`;
+>   confirm the storefront still fetches products as a frontend check if you like. **Only check that
+>   checkout can be reached when `site.json → ecommerce.payment_enabled` is `true`** — on a free account
+>   (`payment_enabled: false`) there is no checkout, so **skip that check entirely**; a catalog that serves
+>   200 is a passing, complete deploy. Never fail or hold the deploy because checkout is unavailable.
+> - **Webapp:** no content backend at all — the whole root is the app. Skip the check; `/cms` won't resolve.
+
+A `completed` build whose root 403s almost always means the build settings weren't passed to
+`hosting_deploy` (null settings) — pass them and redeploy. Caching can briefly serve a stale root;
+re-check after ~30 s.
+
+## Step 6 — Record `deploy.json`
+
+```json
+{
+  "build_uuid": "…",
+  "stack": "nextjs",
+  "rendering": "ssr",
+  "app_type": "next",
+  "output_directory": ".next",
+  "node_version": 22,
+  "method": "hosting_deploy (type: nodejs, settings passed inline)",
+  "deployed_at": "…",
+  "verified_at": "…",
+  "urls": { "live": "https://<domain>", "cms": "https://<domain>/cms" },
+  "checks": { "root": 200, "ssr_headers": true, "backend_preserved": true }
+}
+```
+
+No secrets in `deploy.json`. The `urls.cms` field and the `backend_preserved` check above are
+**WordPress-only** — adjust the record to the backend:
+
+- **WordPress:** keep `urls.cms` and `checks.backend_preserved` as shown.
+- **WordPress + WooCommerce:** keep `urls.cms` + `checks.backend_preserved` (it *is* WordPress), and add
+  `urls.store_api` from `site.json`; no external link step.
+- **Ecommerce:** omit `urls.cms`/`backend_preserved`; record the store URLs instead (`urls.storefront_api`,
+  `urls.store_admin` from `site.json`) and link the custom sales channel to the live domain —
+  `ecommerce_sales-channels_update { store_id, sales_channel_id, url }` (see the ecommerce provision step).
+- **Webapp:** omit `urls.cms` and `backend_preserved` entirely — `urls` is just `{ "live": "https://<domain>" }`.
+
+Update `state.json` (`stage` → `done`), then continue to Step 9 (done).
+
+---
+
+## Note — one deploy path, and never `type: "static"`
+
+`hosting_deploy` is the only path: give its `path` either the source **directory** (it archives it for
+you) or a local **archive** (`zip`, `tar`, `tar.gz`, `tgz`, `7z`) — there is no separate upload or build
+step to fall back to. Either way pass the explicit `appType`/`outputDirectory`/`nodeVersion`/
+`buildScript`/`packageManager`/`rootDirectory` from the table. Never deploy a headless site with
+`type: "static"` — it serves the directory as plain files and can overwrite `/cms`.