@hostinger/mcp 3.38.1 → 3.38.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/build-release.yaml +12 -11
- package/CHANGELOG.md +17 -0
- package/gemini-extension.json +1 -1
- package/package.json +1 -1
- package/server.json +2 -2
- package/skills/headless/VERSION +2 -2
- package/skills/headless/steps/08-deploy/SKILL.md +7 -2
- package/src/core/oauth.js +9 -2
- package/src/core/oauth.ts +9 -2
- package/src/core/runtime.js +16 -3
- package/src/core/runtime.ts +16 -3
- package/src/core/skills.js +3 -3
- package/src/core/skills.ts +3 -3
- package/src/servers/agency-hosting.js +1 -1
- package/src/servers/agency-hosting.ts +1 -1
- package/src/servers/agent-readiness.js +1 -1
- package/src/servers/agent-readiness.ts +1 -1
- package/src/servers/all.js +1 -1
- package/src/servers/all.ts +1 -1
- package/src/servers/billing.js +1 -1
- package/src/servers/billing.ts +1 -1
- package/src/servers/dns.js +1 -1
- package/src/servers/dns.ts +1 -1
- package/src/servers/domains.js +1 -1
- package/src/servers/domains.ts +1 -1
- package/src/servers/ecommerce.js +1 -1
- package/src/servers/ecommerce.ts +1 -1
- package/src/servers/gpu.js +1 -1
- package/src/servers/gpu.ts +1 -1
- package/src/servers/horizons.js +1 -1
- package/src/servers/horizons.ts +1 -1
- package/src/servers/hosting.js +1 -1
- package/src/servers/hosting.ts +1 -1
- package/src/servers/mail.js +1 -1
- package/src/servers/mail.ts +1 -1
- package/src/servers/reach.js +1 -1
- package/src/servers/reach.ts +1 -1
- package/src/servers/vps.js +1 -1
- package/src/servers/vps.ts +1 -1
- package/src/servers/wordpress.js +1 -1
- package/src/servers/wordpress.ts +1 -1
|
@@ -7,10 +7,13 @@ on:
|
|
|
7
7
|
- main
|
|
8
8
|
|
|
9
9
|
jobs:
|
|
10
|
+
# npm trusted publishing trusts this whole workflow file, so any job here holding id-token: write can publish
|
|
11
|
+
# the package. Only the publish jobs hold it, and besides GitHub's own actions they run no downloaded code:
|
|
12
|
+
# no npm update and no dependency install (npm publish packs the files and runs no scripts), and a pinned,
|
|
13
|
+
# checksummed mcp-publisher.
|
|
10
14
|
release:
|
|
11
15
|
runs-on: ubuntu-latest
|
|
12
16
|
permissions:
|
|
13
|
-
id-token: write
|
|
14
17
|
contents: write
|
|
15
18
|
outputs:
|
|
16
19
|
new_version: ${{ steps.version.outputs.version }}
|
|
@@ -77,12 +80,6 @@ jobs:
|
|
|
77
80
|
node-version: '24.x'
|
|
78
81
|
registry-url: 'https://registry.npmjs.org'
|
|
79
82
|
|
|
80
|
-
- name: Update NPM
|
|
81
|
-
run: npm install -g npm@latest
|
|
82
|
-
|
|
83
|
-
- name: Install dependencies
|
|
84
|
-
run: npm install
|
|
85
|
-
|
|
86
83
|
- name: Publish package
|
|
87
84
|
run: npm publish --provenance --access public
|
|
88
85
|
|
|
@@ -119,9 +116,6 @@ jobs:
|
|
|
119
116
|
registry-url: 'https://npm.pkg.github.com'
|
|
120
117
|
scope: '@hostinger'
|
|
121
118
|
|
|
122
|
-
- name: Install dependencies
|
|
123
|
-
run: npm install
|
|
124
|
-
|
|
125
119
|
- name: Publish package
|
|
126
120
|
run: |
|
|
127
121
|
sed -i 's+"name": ".*+"name": "@${{ github.repository }}",+gI' ./package.json
|
|
@@ -145,9 +139,16 @@ jobs:
|
|
|
145
139
|
with:
|
|
146
140
|
node-version: '24.x'
|
|
147
141
|
|
|
142
|
+
# Pinned and checksummed: this job can mint the npm publishing identity. To upgrade, take the
|
|
143
|
+
# sha256 digest of mcp-publisher_linux_amd64.tar.gz from the registry release's assets.
|
|
148
144
|
- name: Install MCP Publisher
|
|
145
|
+
env:
|
|
146
|
+
MCP_PUBLISHER_VERSION: v1.8.7
|
|
147
|
+
MCP_PUBLISHER_SHA256: 00b21004149a4ce66f0782508ae4a2bce67d1bea395a8da0bd8028159fb59579
|
|
149
148
|
run: |
|
|
150
|
-
curl -
|
|
149
|
+
curl -fsSL -o mcp-publisher.tar.gz "https://github.com/modelcontextprotocol/registry/releases/download/$MCP_PUBLISHER_VERSION/mcp-publisher_linux_amd64.tar.gz"
|
|
150
|
+
echo "$MCP_PUBLISHER_SHA256 mcp-publisher.tar.gz" | sha256sum -c -
|
|
151
|
+
tar xzf mcp-publisher.tar.gz mcp-publisher
|
|
151
152
|
chmod +x ./mcp-publisher
|
|
152
153
|
|
|
153
154
|
- name: Login to MCP Registry using GitHub OIDC
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,23 @@ Generated at release time from the diff between the previous and current
|
|
|
4
4
|
build. Tool changes are listed individually; everything else is summarised
|
|
5
5
|
by area.
|
|
6
6
|
|
|
7
|
+
## v3.38.3 — 2026-11-11
|
|
8
|
+
|
|
9
|
+
### Also in this release
|
|
10
|
+
|
|
11
|
+
- Bundled agent skills: `skills/headless/VERSION`, `skills/headless/steps/08-deploy/SKILL.md`
|
|
12
|
+
- Request handling and authentication: `src/core/runtime.js`, `src/core/runtime.ts`
|
|
13
|
+
- Other files: `src/core/skills.js`, `src/core/skills.ts`
|
|
14
|
+
|
|
15
|
+
## v3.38.2 — 2026-11-11
|
|
16
|
+
|
|
17
|
+
### Also in this release
|
|
18
|
+
|
|
19
|
+
- Release automation: `.github/workflows/build-release.yaml`
|
|
20
|
+
- Bundled agent skills: `skills/headless/VERSION`
|
|
21
|
+
- OAuth sign-in flow: `src/core/oauth.js`, `src/core/oauth.ts`
|
|
22
|
+
- Request handling and authentication: `src/core/runtime.js`, `src/core/runtime.ts`
|
|
23
|
+
|
|
7
24
|
## v3.38.1 — 2026-11-11
|
|
8
25
|
|
|
9
26
|
### Also in this release
|
package/gemini-extension.json
CHANGED
package/package.json
CHANGED
package/server.json
CHANGED
|
@@ -17,12 +17,12 @@
|
|
|
17
17
|
"url": "https://github.com/hostinger/api-mcp-server",
|
|
18
18
|
"source": "github"
|
|
19
19
|
},
|
|
20
|
-
"version": "3.38.
|
|
20
|
+
"version": "3.38.3",
|
|
21
21
|
"packages": [
|
|
22
22
|
{
|
|
23
23
|
"registryType": "npm",
|
|
24
24
|
"identifier": "@hostinger/mcp",
|
|
25
|
-
"version": "3.38.
|
|
25
|
+
"version": "3.38.3",
|
|
26
26
|
"transport": {
|
|
27
27
|
"type": "stdio"
|
|
28
28
|
},
|
package/skills/headless/VERSION
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
version=3.38.
|
|
2
|
-
commit=
|
|
1
|
+
version=3.38.3
|
|
2
|
+
commit=9b497d4052aa
|
|
3
3
|
built=2026-11-11
|
|
@@ -96,6 +96,9 @@ Zip the project **source** with `package.json` at the archive root. **Include**
|
|
|
96
96
|
`public/`, the framework config (`next.config.mjs` / `astro.config.mjs`), `tsconfig.json`,
|
|
97
97
|
`package.json`, `package-lock.json`, `.nvmrc`. **Exclude** `node_modules/`, the build output
|
|
98
98
|
(`.next/`, `dist/`, `out/`), `.git/`, and any `.htaccess` — the server installs and builds from source.
|
|
99
|
+
**Never archive secrets:** the commands below also leave out `.env*` files, `.npmrc` and key/certificate
|
|
100
|
+
files (`*.pem`, `*.key`, `*.p12`, `*.pfx`). A brought-in project often has a `.env.local`; its values go in
|
|
101
|
+
as environment variables (Step 1), never in the archive.
|
|
99
102
|
|
|
100
103
|
> ## ⚠️ Write the archive outside `~/.hostinger/` (the deploy refuses it there)
|
|
101
104
|
> `hosting_deploy` refuses any `path` under a hidden folder at the top of the home directory
|
|
@@ -110,7 +113,8 @@ Zip the project **source** with `package.json` at the archive root. **Include**
|
|
|
110
113
|
# macOS/Linux — the OS temp dir is outside the home directory
|
|
111
114
|
cd ~/.hostinger/<domain>/src
|
|
112
115
|
DEPLOY_DIR=$(mktemp -d)
|
|
113
|
-
zip -r -X "$DEPLOY_DIR/app.zip" . -x 'node_modules/*' '.next/*' 'dist/*' 'out/*' '.git/*' '**/.htaccess'
|
|
116
|
+
zip -r -X "$DEPLOY_DIR/app.zip" . -x 'node_modules/*' '.next/*' 'dist/*' 'out/*' '.git/*' '**/.htaccess' \
|
|
117
|
+
'.env*' '*/.env*' '.npmrc' '*/.npmrc' '*.pem' '*.key' '*.p12' '*.pfx'
|
|
114
118
|
echo "$DEPLOY_DIR/app.zip" # the absolute path to pass as `path` in Step 3
|
|
115
119
|
```
|
|
116
120
|
|
|
@@ -119,7 +123,8 @@ echo "$DEPLOY_DIR/app.zip" # the absolute path to pass as `path` in Step 3
|
|
|
119
123
|
# profile, which only you can write to (never a folder under C:\, which every local account can write into)
|
|
120
124
|
cd $HOME\.hostinger\<domain>\src
|
|
121
125
|
$DeployDir = Join-Path $HOME "hostinger-deploy\<domain>"; New-Item -ItemType Directory -Force $DeployDir | Out-Null
|
|
122
|
-
tar -a -cf "$DeployDir\app.zip" --exclude=node_modules --exclude=.next --exclude=dist --exclude=out --exclude=.git --exclude=.htaccess
|
|
126
|
+
tar -a -cf "$DeployDir\app.zip" --exclude=node_modules --exclude=.next --exclude=dist --exclude=out --exclude=.git --exclude=.htaccess `
|
|
127
|
+
--exclude=.env* --exclude=.npmrc --exclude=*.pem --exclude=*.key --exclude=*.p12 --exclude=*.pfx .
|
|
123
128
|
"$DeployDir\app.zip" # the absolute path to pass as `path` in Step 3
|
|
124
129
|
```
|
|
125
130
|
|
package/src/core/oauth.js
CHANGED
|
@@ -348,8 +348,15 @@ export class OAuthProvider {
|
|
|
348
348
|
_listenForCallback(expectedState, port) {
|
|
349
349
|
return new Promise((resolve, reject) => {
|
|
350
350
|
const server = createServer((req, res) => {
|
|
351
|
-
|
|
352
|
-
|
|
351
|
+
// Any local process or web page can reach this port: a request target that does not parse (GET //)
|
|
352
|
+
// gets a 404 instead of an exception, which would crash the server.
|
|
353
|
+
let url;
|
|
354
|
+
try {
|
|
355
|
+
url = new URL(req.url, `http://127.0.0.1:${port}`);
|
|
356
|
+
} catch {
|
|
357
|
+
url = null;
|
|
358
|
+
}
|
|
359
|
+
if (url?.pathname !== CALLBACK_PATH) {
|
|
353
360
|
res.writeHead(404);
|
|
354
361
|
res.end();
|
|
355
362
|
return;
|
package/src/core/oauth.ts
CHANGED
|
@@ -320,8 +320,15 @@ export class OAuthProvider {
|
|
|
320
320
|
private _listenForCallback(expectedState: string, port: number): Promise<{ code: string; port: number }> {
|
|
321
321
|
return new Promise((resolve, reject) => {
|
|
322
322
|
const server: Server = createServer((req, res) => {
|
|
323
|
-
|
|
324
|
-
|
|
323
|
+
// Any local process or web page can reach this port: a request target that does not parse (GET //)
|
|
324
|
+
// gets a 404 instead of an exception, which would crash the server.
|
|
325
|
+
let url: URL | null;
|
|
326
|
+
try {
|
|
327
|
+
url = new URL(req.url || '/', `http://127.0.0.1:${port}`);
|
|
328
|
+
} catch {
|
|
329
|
+
url = null;
|
|
330
|
+
}
|
|
331
|
+
if (!url || url.pathname !== CALLBACK_PATH) {
|
|
325
332
|
res.writeHead(404);
|
|
326
333
|
res.end();
|
|
327
334
|
return;
|
package/src/core/runtime.js
CHANGED
|
@@ -350,7 +350,9 @@ class MCPServer {
|
|
|
350
350
|
// Container secrets (Docker's /run/secrets, the Kubernetes service-account token under /var/run/secrets) and runtime state.
|
|
351
351
|
'/run', '/var/run', '/private/var/run',
|
|
352
352
|
// Every user's home directory, whatever the current home is (root's is /root, a container's can be /).
|
|
353
|
-
'/home', '/Users',
|
|
353
|
+
'/home', '/Users',
|
|
354
|
+
// Windows: the profiles, the system, installed programs and their machine-wide data.
|
|
355
|
+
...(process.platform === 'win32' ? [path.join(process.env.SystemDrive || 'C:', 'Users'), process.env.SystemRoot, process.env.ProgramData, process.env.ProgramFiles, process.env['ProgramFiles(x86)']].filter(Boolean) : [])];
|
|
354
356
|
|
|
355
357
|
// A deploy publishes what it reads, and the path comes from the model, so prompt-injected arguments could
|
|
356
358
|
// publish any readable file. Refused, before anything is read or sent: the home directory and every directory
|
|
@@ -360,6 +362,11 @@ class MCPServer {
|
|
|
360
362
|
// os is imported by deploy.template: the JS generator dedupes import blocks by their whole text, and this block
|
|
361
363
|
// must stay identical to agency-hosting/shared's, or tus and fs are imported twice.
|
|
362
364
|
assertDeployablePath(localPath) {
|
|
365
|
+
// A UNC or device path (\\host\share, //host/share, \\?\UNC\…) is opened over SMB by the realpath below, which on
|
|
366
|
+
// Windows sends the user's NTLM credentials to that host: refused before anything touches it.
|
|
367
|
+
if (/^[\\/]{2}/.test(localPath)) {
|
|
368
|
+
throw new Error('Refusing to deploy ' + localPath + ': it is a network path. Pass a local project directory or archive.');
|
|
369
|
+
}
|
|
363
370
|
let real;
|
|
364
371
|
try {
|
|
365
372
|
real = fs.realpathSync.native(localPath);
|
|
@@ -413,7 +420,8 @@ class MCPServer {
|
|
|
413
420
|
const inSystem = !inHome && this.systemDirectories.some((dir) => inside(dir, real) || inside(real, dir));
|
|
414
421
|
// Windows drops trailing dots and spaces from a name: .ssh. is .ssh.
|
|
415
422
|
const inCredentials = real.split(path.sep).some((segment) => this.credentialDirectories.includes((process.platform === 'win32' ? segment.replace(/[. ]+$/, '') : segment).toLowerCase()));
|
|
416
|
-
|
|
423
|
+
// A drive or filesystem root (D:\ on Windows) holds everything on it.
|
|
424
|
+
if (real === path.parse(real).root || /^[\\/]{2}/.test(real) || inside(real, home) || otherHome || inHomeData || inProfile || inSystem || inCredentials || (fs.statSync(real).isFile() && this.isSecretFile(path.basename(real)))) {
|
|
417
425
|
throw new Error('Refusing to deploy ' + localPath + ': it is, or contains, a home, system or credentials location. Pass the project directory or archive.');
|
|
418
426
|
}
|
|
419
427
|
}
|
|
@@ -2471,7 +2479,12 @@ class MCPServer {
|
|
|
2471
2479
|
Object.entries(requestParams).forEach(([key, value]) => {
|
|
2472
2480
|
const placeholder = `{${key}}`;
|
|
2473
2481
|
if (path.includes(placeholder)) {
|
|
2474
|
-
|
|
2482
|
+
// Encoding keeps dot segments and new URL() resolves them away, which would call another endpoint.
|
|
2483
|
+
const segment = String(value);
|
|
2484
|
+
if (segment === '' || segment === '.' || segment === '..') {
|
|
2485
|
+
throw new Error(`Invalid value for path parameter ${key}.`);
|
|
2486
|
+
}
|
|
2487
|
+
path = path.replace(placeholder, encodeURIComponent(segment));
|
|
2475
2488
|
delete requestParams[key]; // Remove used parameter
|
|
2476
2489
|
}
|
|
2477
2490
|
});
|
package/src/core/runtime.ts
CHANGED
|
@@ -384,7 +384,9 @@ class MCPServer {
|
|
|
384
384
|
// Container secrets (Docker's /run/secrets, the Kubernetes service-account token under /var/run/secrets) and runtime state.
|
|
385
385
|
'/run', '/var/run', '/private/var/run',
|
|
386
386
|
// Every user's home directory, whatever the current home is (root's is /root, a container's can be /).
|
|
387
|
-
'/home', '/Users',
|
|
387
|
+
'/home', '/Users',
|
|
388
|
+
// Windows: the profiles, the system, installed programs and their machine-wide data.
|
|
389
|
+
...(process.platform === 'win32' ? [path.join(process.env.SystemDrive || 'C:', 'Users'), process.env.SystemRoot, process.env.ProgramData, process.env.ProgramFiles, process.env['ProgramFiles(x86)']].filter((dir): dir is string => !!dir) : [])];
|
|
388
390
|
|
|
389
391
|
// A deploy publishes what it reads, and the path comes from the model, so prompt-injected arguments could
|
|
390
392
|
// publish any readable file. Refused, before anything is read or sent: the home directory and every directory
|
|
@@ -394,6 +396,11 @@ class MCPServer {
|
|
|
394
396
|
// os is imported by deploy.template: the JS generator dedupes import blocks by their whole text, and this block
|
|
395
397
|
// must stay identical to agency-hosting/shared's, or tus and fs are imported twice.
|
|
396
398
|
private assertDeployablePath(localPath: string): void {
|
|
399
|
+
// A UNC or device path (\\host\share, //host/share, \\?\UNC\…) is opened over SMB by the realpath below, which on
|
|
400
|
+
// Windows sends the user's NTLM credentials to that host: refused before anything touches it.
|
|
401
|
+
if (/^[\\/]{2}/.test(localPath)) {
|
|
402
|
+
throw new Error('Refusing to deploy ' + localPath + ': it is a network path. Pass a local project directory or archive.');
|
|
403
|
+
}
|
|
397
404
|
let real: string;
|
|
398
405
|
try {
|
|
399
406
|
real = fs.realpathSync.native(localPath);
|
|
@@ -447,7 +454,8 @@ class MCPServer {
|
|
|
447
454
|
const inSystem = !inHome && this.systemDirectories.some((dir: string) => inside(dir, real) || inside(real, dir));
|
|
448
455
|
// Windows drops trailing dots and spaces from a name: .ssh. is .ssh.
|
|
449
456
|
const inCredentials = real.split(path.sep).some((segment: string) => this.credentialDirectories.includes((process.platform === 'win32' ? segment.replace(/[. ]+$/, '') : segment).toLowerCase()));
|
|
450
|
-
|
|
457
|
+
// A drive or filesystem root (D:\ on Windows) holds everything on it.
|
|
458
|
+
if (real === path.parse(real).root || /^[\\/]{2}/.test(real) || inside(real, home) || otherHome || inHomeData || inProfile || inSystem || inCredentials || (fs.statSync(real).isFile() && this.isSecretFile(path.basename(real)))) {
|
|
451
459
|
throw new Error('Refusing to deploy ' + localPath + ': it is, or contains, a home, system or credentials location. Pass the project directory or archive.');
|
|
452
460
|
}
|
|
453
461
|
}
|
|
@@ -2527,7 +2535,12 @@ class MCPServer {
|
|
|
2527
2535
|
Object.entries(requestParams).forEach(([key, value]) => {
|
|
2528
2536
|
const placeholder = `{${key}}`;
|
|
2529
2537
|
if (path.includes(placeholder)) {
|
|
2530
|
-
|
|
2538
|
+
// Encoding keeps dot segments and new URL() resolves them away, which would call another endpoint.
|
|
2539
|
+
const segment = String(value);
|
|
2540
|
+
if (segment === '' || segment === '.' || segment === '..') {
|
|
2541
|
+
throw new Error(`Invalid value for path parameter ${key}.`);
|
|
2542
|
+
}
|
|
2543
|
+
path = path.replace(placeholder, encodeURIComponent(segment));
|
|
2531
2544
|
delete requestParams[key]; // Remove used parameter
|
|
2532
2545
|
}
|
|
2533
2546
|
});
|
package/src/core/skills.js
CHANGED
|
@@ -274,10 +274,10 @@ export default [
|
|
|
274
274
|
},
|
|
275
275
|
{
|
|
276
276
|
"uri": "skill://hostinger-headless/steps/08-deploy/SKILL.md",
|
|
277
|
-
"digest": "sha256:
|
|
278
|
-
"size":
|
|
277
|
+
"digest": "sha256:6c0c41be0a808cea047eb6bb8922787ee1fe0594c6a69fb85a771af827488124",
|
|
278
|
+
"size": 16786,
|
|
279
279
|
"mimeType": "text/markdown",
|
|
280
|
-
"text": "---\nname: headless-step-deploy\ndescription: \"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.\"\n---\n\n# headless-step-deploy\n\nShip the frontend to the live domain through the Hostinger connector. You hand the connector a zip of\nthe project **source** and it uploads it, runs `npm install` + the build script on the server, and\nserves the result. **Out:** `deploy.json`.\n\nThis is an **instance-barrier** step: run it only after `provision.status == \"completed\"` and validate\n(if run) has passed. All operations go through the connector (`execute`).\n\n> **Connected to the hosted server (`mcp.hostinger.com`)?** Its `hosting_deploy` deploys Git\n> repositories only and cannot read a local `path`. Run this step through the local\n> `hostinger-api-mcp` server instead (see the connect step:\n> `<command> <launcher>`).\n\n> **With a shell and the Hostinger CLI installed**, the same deploy is one command, with the build\n> settings passed exactly as the table below says. Run it from the project, since it links the current directory:\n> `cd ~/.hostinger/<domain>/src && hostinger up --domain <domain> --type nodejs --app-type <appType> --output-directory <dir> --build-script build --node-version 22 --package-manager npm --yes --format json`.\n> It uploads, builds, waits and returns `data.buildUuid` and `data.buildState`; add `--no-wait` to\n> return at once and wait with `cd \"$HOME\" && node <skill>/wait.mjs build <domain> <uuid>`. Then continue at\n> \"Verify\" below. Recent CLI versions see that the site is headless (`data.headless: true`) and\n> deploy only its Node.js frontend, leaving `/cms` alone; still pass the settings above.\n\n**In:** the project in `~/.hostinger/<domain>/src/`, `site.json` (`username`, `urls`), `state.json`\n(`frontend.framework`, `frontend.rendering`).\n\n> ## ⚠️ The one rule that makes this work: pass build settings explicitly\n> If you let `hosting_deploy` **auto-detect** build settings, for a headless site that detection returns\n> **null** (`appType:null`, `outputDirectory:null`, Node 20) — the build \"completes\" but the **root\n> serves 403** (no `appType`/output → the vhost serves a directory with no entry). This is reproducible.\n> **Always pass `appType`, `outputDirectory`, `nodeVersion`, `buildScript`, `packageManager` and\n> `rootDirectory` on the `hosting_deploy` call** with the framework's values; the deploy then resolves\n> them and serves correctly, and `/cms` is preserved.\n\n## Build configurations\n\nMap `frontend.framework` (from `state.json`) to its `appType` + build output directory, and pass those\non the `hosting_deploy` call. `appType` is the framework's value, e.g. `next`, `nuxt`, `astro`,\n`svelte-kit`, `nest`, `express`, `fastify`, `react`, `create-react-app`, `gatsby`, `vite`, `vue`,\n`angular`, `parcel`, `svelte`, `other`.\n\nCommon cases (all `nodeVersion: 22`, `buildScript: \"build\"`, `packageManager: \"npm\"`, `rootDirectory: \".\"`):\n\n| Framework / mode | Local config | `appType` | `outputDirectory` |\n|---|---|---|---|\n| **Next.js — SSR** *(default)* | `output: 'standalone'` | `next` | `.next` |\n| **Nuxt — SSR** | default | `nuxt` | `.output` |\n| **SvelteKit — SSR** | node adapter | `svelte-kit` | `build` |\n| **Astro — static** | `output: 'static'` | `astro` | `dist` |\n| **Vite / React / Vue — static (SPA)** | — | `vite` (or `react`/`vue`) | `dist` |\n| **Express / NestJS / Fastify — server** | — | `express`/`nest`/`fastify` | build output dir |\n\nSSR/server frameworks run a persistent Node process (root sends `x-powered-by` / `cache-control: no-store`);\nstatic frameworks serve their output dir as files. If unsure of a framework's output dir, check the\nframework's own build output, but **always pass `appType`/`outputDirectory` on the deploy call with the\nframework's correct values** — don't rely on auto-detection (it returns null → 403).\n\n> ## ⚠️ Next.js 16+: build with webpack, not Turbopack (recurring deploy failure)\n> Next.js 16 makes **Turbopack** the default bundler for `next build`. Turbopack's native (Rust)\n> compiler needs a newer **glibc** than the Hostinger build server ships, so the server build aborts\n> with a \"glibc too old\" error — and Turbopack **does not fall back** to webpack on its own, so the\n> deploy fails every time. **Fix: build with webpack.** On **Next.js 16+** the project's `build` script\n> in `package.json` must be `next build --webpack` (not plain `next build`); `buildScript` on the deploy\n> call stays `\"build\"` — that's what runs it. The `--webpack` flag exists only on Next.js 16+; on\n> **Next.js 15.x** leave the build script as plain `next build` (it already defaults to webpack).\n> **Confirm this in `package.json` before deploying** (the frontend step scaffolds it this way — see\n> `../06-frontend`). Alternative, only if you must avoid the `--webpack` flag: pin Next.js to `15.x`\n> (keeping plain `next build`), whose `next build` still defaults to webpack. Next.js only — other\n> frameworks are unaffected.\n\n## Step 1 — Pre-flight\n\n1. **Instance live (the deploy gate).** `provision.status == \"completed\"`, re-verified with\n `hosting_websites_list-setups { \"domain\": \"<domain>\" }`: deploy overwrites the site root, so it never\n trusts `state.json` alone.\n2. **Build output exists locally** (the framework's output dir — e.g. `.next/`, `dist/`, `.output/`) and\n the project builds clean (frontend/validate already did this). If not, go back.\n - **Next.js 16+:** `package.json`'s `build` script is `next build --webpack`, not plain `next build` —\n the server's glibc can't run Turbopack's native compiler (see the box above). On Next.js 15.x leave it\n as plain `next build`. Fix it here if it isn't.\n3. **Env vars (only if used).** Build-time vars (e.g. `NEXT_PUBLIC_*`) must be set **before** the build\n with `hosting_nodejs_replace-environment-variables` (full replace). Never put secrets in the repo or\n the archive. **Webapp with a database:** that full replace wipes the `DB_*`/`DATABASE_URL` that\n `hosting_databases_setup-website` injected (the generated password reads back masked), so set all app\n vars in the same replace and, if you can't, first reset the password with\n `hosting_databases_change-password` and resend every `DB_*`/`DATABASE_URL` — see\n `../03-provision/webapp/SKILL.md` Step 3.\n\n## Step 2 — Archive the source\n\nZip the project **source** with `package.json` at the archive root. **Include** the app/source,\n`public/`, the framework config (`next.config.mjs` / `astro.config.mjs`), `tsconfig.json`,\n`package.json`, `package-lock.json`, `.nvmrc`. **Exclude** `node_modules/`, the build output\n(`.next/`, `dist/`, `out/`), `.git/`, and any `.htaccess` — the server installs and builds from source.\n\n> ## ⚠️ Write the archive outside `~/.hostinger/` (the deploy refuses it there)\n> `hosting_deploy` refuses any `path` under a hidden folder at the top of the home directory\n> (`~/.hostinger`, `~/.config`, …) with *\"it is, or contains, a home, system or credentials location\"*:\n> a deploy publishes what it reads, so the connector protects dotfolders that can hold tokens. That\n> covers both `~/.hostinger/<domain>/app.zip` **and** the `~/.hostinger/<domain>/src/` directory\n> itself, so neither can be passed as `path`. Keep the source in the workspace as usual, but write the\n> archive to a fresh temp directory and pass that. Don't copy the archive somewhere else after a\n> refusal, and don't move `src/` out of the workspace.\n\n```bash\n# macOS/Linux — the OS temp dir is outside the home directory\ncd ~/.hostinger/<domain>/src\nDEPLOY_DIR=$(mktemp -d)\nzip -r -X \"$DEPLOY_DIR/app.zip\" . -x 'node_modules/*' '.next/*' 'dist/*' 'out/*' '.git/*' '**/.htaccess'\necho \"$DEPLOY_DIR/app.zip\" # the absolute path to pass as `path` in Step 3\n```\n\n```powershell\n# Windows PowerShell — %TEMP% sits under AppData, which the deploy also refuses; use a plain folder in your\n# profile, which only you can write to (never a folder under C:\\, which every local account can write into)\ncd $HOME\\.hostinger\\<domain>\\src\n$DeployDir = Join-Path $HOME \"hostinger-deploy\\<domain>\"; New-Item -ItemType Directory -Force $DeployDir | Out-Null\ntar -a -cf \"$DeployDir\\app.zip\" --exclude=node_modules --exclude=.next --exclude=dist --exclude=out --exclude=.git --exclude=.htaccess .\n\"$DeployDir\\app.zip\" # the absolute path to pass as `path` in Step 3\n```\n\nDelete the temp directory once the build in Step 4 is `completed`.\n\n## Step 3 — Deploy (one shot: settings + upload + build)\n\nPass the framework's build settings **inline** on the deploy call — there is no separate settings step.\n`path` is the absolute path of the archive from Step 2, in its temp directory. Never pass a path under\n`~/.hostinger/`, the `src/` directory included: the deploy refuses it (see Step 2).\n\n```json\n{ \"operation\": \"hosting_deploy\",\n \"params\": {\n \"domain\": \"<domain>\",\n \"path\": \"<absolute path printed in Step 2, e.g. /var/folders/…/tmp.XXXX/app.zip>\",\n \"type\": \"nodejs\",\n \"appType\": \"<framework appType, e.g. next>\",\n \"outputDirectory\": \"<framework output dir, e.g. .next>\",\n \"nodeVersion\": 22,\n \"buildScript\": \"build\",\n \"packageManager\": \"npm\",\n \"rootDirectory\": \".\" } }\n```\n\n`hosting_deploy` uploads the source and triggers `npm install` + the build **end-to-end** — do not call\nany upload or build operation yourself. It returns a build `buildUuid` at once. This **overwrites the\nwebsite root** (expected) and keeps `/cms` intact. `type` is always `\"nodejs\"` for a headless site —\n**never `\"static\"`** (see the gate below). Passing `appType`/`outputDirectory` explicitly is what\nkeeps the root from serving 403 (see the rule above).\n\n## Step 4 — Wait for the build and the live root\n\nWait for it in one command (see *Waiting on Hostinger* in the top-level `SKILL.md`):\n\n```bash\ncd \"$HOME\" && node <skill>/wait.mjs build <domain> <buildUuid>\n```\n\nIt waits for `hosting_get-deployment` to report the build `completed`, then up to 5 minutes for\n`https://<domain>/` (or `http://` while the certificate is pending) to serve 200. What its result means here:\n\n- `ok: true`: the build is done and the root serves 200. Go on to Step 5.\n- `ok: true` with `https_pending: true`: the build is done and `http://<domain>/` serves 200, but the\n new domain's SSL certificate is still installing (this can take the better part of an hour). The\n deploy worked: tell the user HTTPS will follow on its own, run Step 5 over `http://`, and don't\n wait for the certificate.\n- `ok: false` with `build.state: failed`: read `log_tail` (the end of the build log) and `analysis`, fix\n locally, re-archive and redeploy (pass `fromLine` to `hosting_get-deployment` to read only new log\n output).\n- `ok: false` with `build settings missing`: the settings didn't take (the root would 403 for good). Fix\n the deploy call and redeploy.\n- `ok: false` with `timed_out`: `last_status` says whether the build was still running or the root\n wasn't serving 200 yet (see Step 5's note on a 403). For an SSR app that built but hangs,\n `hosting_nodejs_restart-application { username, domain }` recovers the server without a rebuild.\n\n## Step 5 — Verify the live site (all must pass)\n\n| Check | How | Expect |\n|---|---|---|\n| Root serves | `GET https://<domain>/` | **200** (not 403 / 404) |\n| SSR is live *(server frameworks)* | response headers | `x-powered-by` present, `cache-control: no-store` |\n| Static serves *(static frameworks)* | `GET https://<domain>/` | 200 HTML with real home content |\n| Key routes | a couple of planned routes + one deep route | 200, real content |\n| **Backend survived** *(WordPress / WooCommerce)* | `GET https://<domain>/cms/wp-json/wp/v2/posts?per_page=1` | 200 |\n\n> **Only WordPress (including WordPress + WooCommerce) has a `/cms` on the domain**, so the *Backend\n> survived* check is WordPress-only.\n> - **WordPress + WooCommerce:** also confirm the store survived the deploy —\n> `GET https://<domain>/cms/wp-json/wc/store/v1/products?per_page=1` → 200. There is nothing external to\n> link (no sales-channel step — that's Ecommerce only). **Checkout** stays owner-completed: when\n> `site.json → woocommerce.payment_enabled` is `false`, don't test `/checkout`; a catalog that serves 200\n> is a passing, complete deploy.\n> - **Ecommerce:** the backend is the **Hostinger Ecommerce store**, read over the external Storefront API\n> (`api-ecommerce.hostinger.com`) — nothing a deploy touches lives on this domain. There is no `/cms`;\n> confirm the storefront still fetches products as a frontend check if you like. **Only check that\n> checkout can be reached when `site.json → ecommerce.payment_enabled` is `true`** — on a free account\n> (`payment_enabled: false`) there is no checkout, so **skip that check entirely**; a catalog that serves\n> 200 is a passing, complete deploy. Never fail or hold the deploy because checkout is unavailable.\n> - **Webapp:** no content backend at all — the whole root is the app. Skip the check; `/cms` won't resolve.\n\nThe root check is already done when `wait.mjs build` returned `ok: true`; check the rest in one shell\ncommand (`curl` each URL). A `completed` build whose root 403s almost always means the build settings\nweren't passed to `hosting_deploy` (null settings) — pass them and redeploy. Caching can briefly serve a\nstale root; re-check after ~30 s.\n\n## Step 6 — Record `deploy.json`\n\n```json\n{\n \"build_uuid\": \"…\",\n \"stack\": \"nextjs\",\n \"rendering\": \"ssr\",\n \"app_type\": \"next\",\n \"output_directory\": \".next\",\n \"node_version\": 22,\n \"method\": \"hosting_deploy (type: nodejs, settings passed inline)\",\n \"deployed_at\": \"…\",\n \"verified_at\": \"…\",\n \"urls\": { \"live\": \"https://<domain>\", \"cms\": \"https://<domain>/cms\" },\n \"checks\": { \"root\": 200, \"ssr_headers\": true, \"backend_preserved\": true }\n}\n```\n\nNo secrets in `deploy.json`. The `urls.cms` field and the `backend_preserved` check above are\n**WordPress-only** — adjust the record to the backend:\n\n- **WordPress:** keep `urls.cms` and `checks.backend_preserved` as shown.\n- **WordPress + WooCommerce:** keep `urls.cms` + `checks.backend_preserved` (it *is* WordPress), and add\n `urls.store_api` from `site.json`; no external link step.\n- **Ecommerce:** omit `urls.cms`/`backend_preserved`; record the store URLs instead (`urls.storefront_api`,\n `urls.store_admin` from `site.json`) and link the custom sales channel to the live domain —\n `ecommerce_sales-channels_update { store_id, sales_channel_id, url }` (see the ecommerce provision step).\n- **Webapp:** omit `urls.cms` and `backend_preserved` entirely — `urls` is just `{ \"live\": \"https://<domain>\" }`.\n\nUpdate `state.json` (`stage` → `done`), then continue to Step 9 (done).\n\n---\n\n## Gate — a headless deploy is always `type: \"nodejs\"`, never `type: \"static\"`\n\n**Hard rule, check it before every deploy:** a headless site is deployed **only** with\n`type: \"nodejs\"` plus the explicit `appType`/`outputDirectory`/`nodeVersion`/`buildScript`/\n`packageManager`/`rootDirectory` from the table. **Never pass `type: \"static\"` on a headless site** — it\nserves the build as plain files over the document root and **overwrites `/cms`**, destroying the\nWordPress backend (this is the \"accidentally cleared cms\" failure). A static-built SPA (Vite/React/Vue)\nstill deploys as `type: \"nodejs\"` with its `appType` — the framework's static output is served correctly\nthat way, and `/cms` is preserved. If a flow ever tells you to deploy a headless site as `type:\n\"static\"`, you are on a stale/legacy skill copy — stop and update the skill (`npx skills update` or the plugin update for an installed skill, or connect's Phase 1 npm install for a web-installed `headless/` folder).\n\n`hosting_deploy` on the local server is the only path: give its `path` a local **archive** (`zip`, `tar`,\n`tar.gz`, `tgz`, `7z`) written outside `~/.hostinger/` as in Step 2. There is no separate upload or\nbuild step to fall back to.\n"
|
|
280
|
+
"text": "---\nname: headless-step-deploy\ndescription: \"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.\"\n---\n\n# headless-step-deploy\n\nShip the frontend to the live domain through the Hostinger connector. You hand the connector a zip of\nthe project **source** and it uploads it, runs `npm install` + the build script on the server, and\nserves the result. **Out:** `deploy.json`.\n\nThis is an **instance-barrier** step: run it only after `provision.status == \"completed\"` and validate\n(if run) has passed. All operations go through the connector (`execute`).\n\n> **Connected to the hosted server (`mcp.hostinger.com`)?** Its `hosting_deploy` deploys Git\n> repositories only and cannot read a local `path`. Run this step through the local\n> `hostinger-api-mcp` server instead (see the connect step:\n> `<command> <launcher>`).\n\n> **With a shell and the Hostinger CLI installed**, the same deploy is one command, with the build\n> settings passed exactly as the table below says. Run it from the project, since it links the current directory:\n> `cd ~/.hostinger/<domain>/src && hostinger up --domain <domain> --type nodejs --app-type <appType> --output-directory <dir> --build-script build --node-version 22 --package-manager npm --yes --format json`.\n> It uploads, builds, waits and returns `data.buildUuid` and `data.buildState`; add `--no-wait` to\n> return at once and wait with `cd \"$HOME\" && node <skill>/wait.mjs build <domain> <uuid>`. Then continue at\n> \"Verify\" below. Recent CLI versions see that the site is headless (`data.headless: true`) and\n> deploy only its Node.js frontend, leaving `/cms` alone; still pass the settings above.\n\n**In:** the project in `~/.hostinger/<domain>/src/`, `site.json` (`username`, `urls`), `state.json`\n(`frontend.framework`, `frontend.rendering`).\n\n> ## ⚠️ The one rule that makes this work: pass build settings explicitly\n> If you let `hosting_deploy` **auto-detect** build settings, for a headless site that detection returns\n> **null** (`appType:null`, `outputDirectory:null`, Node 20) — the build \"completes\" but the **root\n> serves 403** (no `appType`/output → the vhost serves a directory with no entry). This is reproducible.\n> **Always pass `appType`, `outputDirectory`, `nodeVersion`, `buildScript`, `packageManager` and\n> `rootDirectory` on the `hosting_deploy` call** with the framework's values; the deploy then resolves\n> them and serves correctly, and `/cms` is preserved.\n\n## Build configurations\n\nMap `frontend.framework` (from `state.json`) to its `appType` + build output directory, and pass those\non the `hosting_deploy` call. `appType` is the framework's value, e.g. `next`, `nuxt`, `astro`,\n`svelte-kit`, `nest`, `express`, `fastify`, `react`, `create-react-app`, `gatsby`, `vite`, `vue`,\n`angular`, `parcel`, `svelte`, `other`.\n\nCommon cases (all `nodeVersion: 22`, `buildScript: \"build\"`, `packageManager: \"npm\"`, `rootDirectory: \".\"`):\n\n| Framework / mode | Local config | `appType` | `outputDirectory` |\n|---|---|---|---|\n| **Next.js — SSR** *(default)* | `output: 'standalone'` | `next` | `.next` |\n| **Nuxt — SSR** | default | `nuxt` | `.output` |\n| **SvelteKit — SSR** | node adapter | `svelte-kit` | `build` |\n| **Astro — static** | `output: 'static'` | `astro` | `dist` |\n| **Vite / React / Vue — static (SPA)** | — | `vite` (or `react`/`vue`) | `dist` |\n| **Express / NestJS / Fastify — server** | — | `express`/`nest`/`fastify` | build output dir |\n\nSSR/server frameworks run a persistent Node process (root sends `x-powered-by` / `cache-control: no-store`);\nstatic frameworks serve their output dir as files. If unsure of a framework's output dir, check the\nframework's own build output, but **always pass `appType`/`outputDirectory` on the deploy call with the\nframework's correct values** — don't rely on auto-detection (it returns null → 403).\n\n> ## ⚠️ Next.js 16+: build with webpack, not Turbopack (recurring deploy failure)\n> Next.js 16 makes **Turbopack** the default bundler for `next build`. Turbopack's native (Rust)\n> compiler needs a newer **glibc** than the Hostinger build server ships, so the server build aborts\n> with a \"glibc too old\" error — and Turbopack **does not fall back** to webpack on its own, so the\n> deploy fails every time. **Fix: build with webpack.** On **Next.js 16+** the project's `build` script\n> in `package.json` must be `next build --webpack` (not plain `next build`); `buildScript` on the deploy\n> call stays `\"build\"` — that's what runs it. The `--webpack` flag exists only on Next.js 16+; on\n> **Next.js 15.x** leave the build script as plain `next build` (it already defaults to webpack).\n> **Confirm this in `package.json` before deploying** (the frontend step scaffolds it this way — see\n> `../06-frontend`). Alternative, only if you must avoid the `--webpack` flag: pin Next.js to `15.x`\n> (keeping plain `next build`), whose `next build` still defaults to webpack. Next.js only — other\n> frameworks are unaffected.\n\n## Step 1 — Pre-flight\n\n1. **Instance live (the deploy gate).** `provision.status == \"completed\"`, re-verified with\n `hosting_websites_list-setups { \"domain\": \"<domain>\" }`: deploy overwrites the site root, so it never\n trusts `state.json` alone.\n2. **Build output exists locally** (the framework's output dir — e.g. `.next/`, `dist/`, `.output/`) and\n the project builds clean (frontend/validate already did this). If not, go back.\n - **Next.js 16+:** `package.json`'s `build` script is `next build --webpack`, not plain `next build` —\n the server's glibc can't run Turbopack's native compiler (see the box above). On Next.js 15.x leave it\n as plain `next build`. Fix it here if it isn't.\n3. **Env vars (only if used).** Build-time vars (e.g. `NEXT_PUBLIC_*`) must be set **before** the build\n with `hosting_nodejs_replace-environment-variables` (full replace). Never put secrets in the repo or\n the archive. **Webapp with a database:** that full replace wipes the `DB_*`/`DATABASE_URL` that\n `hosting_databases_setup-website` injected (the generated password reads back masked), so set all app\n vars in the same replace and, if you can't, first reset the password with\n `hosting_databases_change-password` and resend every `DB_*`/`DATABASE_URL` — see\n `../03-provision/webapp/SKILL.md` Step 3.\n\n## Step 2 — Archive the source\n\nZip the project **source** with `package.json` at the archive root. **Include** the app/source,\n`public/`, the framework config (`next.config.mjs` / `astro.config.mjs`), `tsconfig.json`,\n`package.json`, `package-lock.json`, `.nvmrc`. **Exclude** `node_modules/`, the build output\n(`.next/`, `dist/`, `out/`), `.git/`, and any `.htaccess` — the server installs and builds from source.\n**Never archive secrets:** the commands below also leave out `.env*` files, `.npmrc` and key/certificate\nfiles (`*.pem`, `*.key`, `*.p12`, `*.pfx`). A brought-in project often has a `.env.local`; its values go in\nas environment variables (Step 1), never in the archive.\n\n> ## ⚠️ Write the archive outside `~/.hostinger/` (the deploy refuses it there)\n> `hosting_deploy` refuses any `path` under a hidden folder at the top of the home directory\n> (`~/.hostinger`, `~/.config`, …) with *\"it is, or contains, a home, system or credentials location\"*:\n> a deploy publishes what it reads, so the connector protects dotfolders that can hold tokens. That\n> covers both `~/.hostinger/<domain>/app.zip` **and** the `~/.hostinger/<domain>/src/` directory\n> itself, so neither can be passed as `path`. Keep the source in the workspace as usual, but write the\n> archive to a fresh temp directory and pass that. Don't copy the archive somewhere else after a\n> refusal, and don't move `src/` out of the workspace.\n\n```bash\n# macOS/Linux — the OS temp dir is outside the home directory\ncd ~/.hostinger/<domain>/src\nDEPLOY_DIR=$(mktemp -d)\nzip -r -X \"$DEPLOY_DIR/app.zip\" . -x 'node_modules/*' '.next/*' 'dist/*' 'out/*' '.git/*' '**/.htaccess' \\\n '.env*' '*/.env*' '.npmrc' '*/.npmrc' '*.pem' '*.key' '*.p12' '*.pfx'\necho \"$DEPLOY_DIR/app.zip\" # the absolute path to pass as `path` in Step 3\n```\n\n```powershell\n# Windows PowerShell — %TEMP% sits under AppData, which the deploy also refuses; use a plain folder in your\n# profile, which only you can write to (never a folder under C:\\, which every local account can write into)\ncd $HOME\\.hostinger\\<domain>\\src\n$DeployDir = Join-Path $HOME \"hostinger-deploy\\<domain>\"; New-Item -ItemType Directory -Force $DeployDir | Out-Null\ntar -a -cf \"$DeployDir\\app.zip\" --exclude=node_modules --exclude=.next --exclude=dist --exclude=out --exclude=.git --exclude=.htaccess `\n --exclude=.env* --exclude=.npmrc --exclude=*.pem --exclude=*.key --exclude=*.p12 --exclude=*.pfx .\n\"$DeployDir\\app.zip\" # the absolute path to pass as `path` in Step 3\n```\n\nDelete the temp directory once the build in Step 4 is `completed`.\n\n## Step 3 — Deploy (one shot: settings + upload + build)\n\nPass the framework's build settings **inline** on the deploy call — there is no separate settings step.\n`path` is the absolute path of the archive from Step 2, in its temp directory. Never pass a path under\n`~/.hostinger/`, the `src/` directory included: the deploy refuses it (see Step 2).\n\n```json\n{ \"operation\": \"hosting_deploy\",\n \"params\": {\n \"domain\": \"<domain>\",\n \"path\": \"<absolute path printed in Step 2, e.g. /var/folders/…/tmp.XXXX/app.zip>\",\n \"type\": \"nodejs\",\n \"appType\": \"<framework appType, e.g. next>\",\n \"outputDirectory\": \"<framework output dir, e.g. .next>\",\n \"nodeVersion\": 22,\n \"buildScript\": \"build\",\n \"packageManager\": \"npm\",\n \"rootDirectory\": \".\" } }\n```\n\n`hosting_deploy` uploads the source and triggers `npm install` + the build **end-to-end** — do not call\nany upload or build operation yourself. It returns a build `buildUuid` at once. This **overwrites the\nwebsite root** (expected) and keeps `/cms` intact. `type` is always `\"nodejs\"` for a headless site —\n**never `\"static\"`** (see the gate below). Passing `appType`/`outputDirectory` explicitly is what\nkeeps the root from serving 403 (see the rule above).\n\n## Step 4 — Wait for the build and the live root\n\nWait for it in one command (see *Waiting on Hostinger* in the top-level `SKILL.md`):\n\n```bash\ncd \"$HOME\" && node <skill>/wait.mjs build <domain> <buildUuid>\n```\n\nIt waits for `hosting_get-deployment` to report the build `completed`, then up to 5 minutes for\n`https://<domain>/` (or `http://` while the certificate is pending) to serve 200. What its result means here:\n\n- `ok: true`: the build is done and the root serves 200. Go on to Step 5.\n- `ok: true` with `https_pending: true`: the build is done and `http://<domain>/` serves 200, but the\n new domain's SSL certificate is still installing (this can take the better part of an hour). The\n deploy worked: tell the user HTTPS will follow on its own, run Step 5 over `http://`, and don't\n wait for the certificate.\n- `ok: false` with `build.state: failed`: read `log_tail` (the end of the build log) and `analysis`, fix\n locally, re-archive and redeploy (pass `fromLine` to `hosting_get-deployment` to read only new log\n output).\n- `ok: false` with `build settings missing`: the settings didn't take (the root would 403 for good). Fix\n the deploy call and redeploy.\n- `ok: false` with `timed_out`: `last_status` says whether the build was still running or the root\n wasn't serving 200 yet (see Step 5's note on a 403). For an SSR app that built but hangs,\n `hosting_nodejs_restart-application { username, domain }` recovers the server without a rebuild.\n\n## Step 5 — Verify the live site (all must pass)\n\n| Check | How | Expect |\n|---|---|---|\n| Root serves | `GET https://<domain>/` | **200** (not 403 / 404) |\n| SSR is live *(server frameworks)* | response headers | `x-powered-by` present, `cache-control: no-store` |\n| Static serves *(static frameworks)* | `GET https://<domain>/` | 200 HTML with real home content |\n| Key routes | a couple of planned routes + one deep route | 200, real content |\n| **Backend survived** *(WordPress / WooCommerce)* | `GET https://<domain>/cms/wp-json/wp/v2/posts?per_page=1` | 200 |\n\n> **Only WordPress (including WordPress + WooCommerce) has a `/cms` on the domain**, so the *Backend\n> survived* check is WordPress-only.\n> - **WordPress + WooCommerce:** also confirm the store survived the deploy —\n> `GET https://<domain>/cms/wp-json/wc/store/v1/products?per_page=1` → 200. There is nothing external to\n> link (no sales-channel step — that's Ecommerce only). **Checkout** stays owner-completed: when\n> `site.json → woocommerce.payment_enabled` is `false`, don't test `/checkout`; a catalog that serves 200\n> is a passing, complete deploy.\n> - **Ecommerce:** the backend is the **Hostinger Ecommerce store**, read over the external Storefront API\n> (`api-ecommerce.hostinger.com`) — nothing a deploy touches lives on this domain. There is no `/cms`;\n> confirm the storefront still fetches products as a frontend check if you like. **Only check that\n> checkout can be reached when `site.json → ecommerce.payment_enabled` is `true`** — on a free account\n> (`payment_enabled: false`) there is no checkout, so **skip that check entirely**; a catalog that serves\n> 200 is a passing, complete deploy. Never fail or hold the deploy because checkout is unavailable.\n> - **Webapp:** no content backend at all — the whole root is the app. Skip the check; `/cms` won't resolve.\n\nThe root check is already done when `wait.mjs build` returned `ok: true`; check the rest in one shell\ncommand (`curl` each URL). A `completed` build whose root 403s almost always means the build settings\nweren't passed to `hosting_deploy` (null settings) — pass them and redeploy. Caching can briefly serve a\nstale root; re-check after ~30 s.\n\n## Step 6 — Record `deploy.json`\n\n```json\n{\n \"build_uuid\": \"…\",\n \"stack\": \"nextjs\",\n \"rendering\": \"ssr\",\n \"app_type\": \"next\",\n \"output_directory\": \".next\",\n \"node_version\": 22,\n \"method\": \"hosting_deploy (type: nodejs, settings passed inline)\",\n \"deployed_at\": \"…\",\n \"verified_at\": \"…\",\n \"urls\": { \"live\": \"https://<domain>\", \"cms\": \"https://<domain>/cms\" },\n \"checks\": { \"root\": 200, \"ssr_headers\": true, \"backend_preserved\": true }\n}\n```\n\nNo secrets in `deploy.json`. The `urls.cms` field and the `backend_preserved` check above are\n**WordPress-only** — adjust the record to the backend:\n\n- **WordPress:** keep `urls.cms` and `checks.backend_preserved` as shown.\n- **WordPress + WooCommerce:** keep `urls.cms` + `checks.backend_preserved` (it *is* WordPress), and add\n `urls.store_api` from `site.json`; no external link step.\n- **Ecommerce:** omit `urls.cms`/`backend_preserved`; record the store URLs instead (`urls.storefront_api`,\n `urls.store_admin` from `site.json`) and link the custom sales channel to the live domain —\n `ecommerce_sales-channels_update { store_id, sales_channel_id, url }` (see the ecommerce provision step).\n- **Webapp:** omit `urls.cms` and `backend_preserved` entirely — `urls` is just `{ \"live\": \"https://<domain>\" }`.\n\nUpdate `state.json` (`stage` → `done`), then continue to Step 9 (done).\n\n---\n\n## Gate — a headless deploy is always `type: \"nodejs\"`, never `type: \"static\"`\n\n**Hard rule, check it before every deploy:** a headless site is deployed **only** with\n`type: \"nodejs\"` plus the explicit `appType`/`outputDirectory`/`nodeVersion`/`buildScript`/\n`packageManager`/`rootDirectory` from the table. **Never pass `type: \"static\"` on a headless site** — it\nserves the build as plain files over the document root and **overwrites `/cms`**, destroying the\nWordPress backend (this is the \"accidentally cleared cms\" failure). A static-built SPA (Vite/React/Vue)\nstill deploys as `type: \"nodejs\"` with its `appType` — the framework's static output is served correctly\nthat way, and `/cms` is preserved. If a flow ever tells you to deploy a headless site as `type:\n\"static\"`, you are on a stale/legacy skill copy — stop and update the skill (`npx skills update` or the plugin update for an installed skill, or connect's Phase 1 npm install for a web-installed `headless/` folder).\n\n`hosting_deploy` on the local server is the only path: give its `path` a local **archive** (`zip`, `tar`,\n`tar.gz`, `tgz`, `7z`) written outside `~/.hostinger/` as in Step 2. There is no separate upload or\nbuild step to fall back to.\n"
|
|
281
281
|
},
|
|
282
282
|
{
|
|
283
283
|
"uri": "skill://hostinger-headless/steps/09-done/SKILL.md",
|
package/src/core/skills.ts
CHANGED
|
@@ -288,10 +288,10 @@ const skills: Skill[] = [
|
|
|
288
288
|
},
|
|
289
289
|
{
|
|
290
290
|
"uri": "skill://hostinger-headless/steps/08-deploy/SKILL.md",
|
|
291
|
-
"digest": "sha256:
|
|
292
|
-
"size":
|
|
291
|
+
"digest": "sha256:6c0c41be0a808cea047eb6bb8922787ee1fe0594c6a69fb85a771af827488124",
|
|
292
|
+
"size": 16786,
|
|
293
293
|
"mimeType": "text/markdown",
|
|
294
|
-
"text": "---\nname: headless-step-deploy\ndescription: \"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.\"\n---\n\n# headless-step-deploy\n\nShip the frontend to the live domain through the Hostinger connector. You hand the connector a zip of\nthe project **source** and it uploads it, runs `npm install` + the build script on the server, and\nserves the result. **Out:** `deploy.json`.\n\nThis is an **instance-barrier** step: run it only after `provision.status == \"completed\"` and validate\n(if run) has passed. All operations go through the connector (`execute`).\n\n> **Connected to the hosted server (`mcp.hostinger.com`)?** Its `hosting_deploy` deploys Git\n> repositories only and cannot read a local `path`. Run this step through the local\n> `hostinger-api-mcp` server instead (see the connect step:\n> `<command> <launcher>`).\n\n> **With a shell and the Hostinger CLI installed**, the same deploy is one command, with the build\n> settings passed exactly as the table below says. Run it from the project, since it links the current directory:\n> `cd ~/.hostinger/<domain>/src && hostinger up --domain <domain> --type nodejs --app-type <appType> --output-directory <dir> --build-script build --node-version 22 --package-manager npm --yes --format json`.\n> It uploads, builds, waits and returns `data.buildUuid` and `data.buildState`; add `--no-wait` to\n> return at once and wait with `cd \"$HOME\" && node <skill>/wait.mjs build <domain> <uuid>`. Then continue at\n> \"Verify\" below. Recent CLI versions see that the site is headless (`data.headless: true`) and\n> deploy only its Node.js frontend, leaving `/cms` alone; still pass the settings above.\n\n**In:** the project in `~/.hostinger/<domain>/src/`, `site.json` (`username`, `urls`), `state.json`\n(`frontend.framework`, `frontend.rendering`).\n\n> ## ⚠️ The one rule that makes this work: pass build settings explicitly\n> If you let `hosting_deploy` **auto-detect** build settings, for a headless site that detection returns\n> **null** (`appType:null`, `outputDirectory:null`, Node 20) — the build \"completes\" but the **root\n> serves 403** (no `appType`/output → the vhost serves a directory with no entry). This is reproducible.\n> **Always pass `appType`, `outputDirectory`, `nodeVersion`, `buildScript`, `packageManager` and\n> `rootDirectory` on the `hosting_deploy` call** with the framework's values; the deploy then resolves\n> them and serves correctly, and `/cms` is preserved.\n\n## Build configurations\n\nMap `frontend.framework` (from `state.json`) to its `appType` + build output directory, and pass those\non the `hosting_deploy` call. `appType` is the framework's value, e.g. `next`, `nuxt`, `astro`,\n`svelte-kit`, `nest`, `express`, `fastify`, `react`, `create-react-app`, `gatsby`, `vite`, `vue`,\n`angular`, `parcel`, `svelte`, `other`.\n\nCommon cases (all `nodeVersion: 22`, `buildScript: \"build\"`, `packageManager: \"npm\"`, `rootDirectory: \".\"`):\n\n| Framework / mode | Local config | `appType` | `outputDirectory` |\n|---|---|---|---|\n| **Next.js — SSR** *(default)* | `output: 'standalone'` | `next` | `.next` |\n| **Nuxt — SSR** | default | `nuxt` | `.output` |\n| **SvelteKit — SSR** | node adapter | `svelte-kit` | `build` |\n| **Astro — static** | `output: 'static'` | `astro` | `dist` |\n| **Vite / React / Vue — static (SPA)** | — | `vite` (or `react`/`vue`) | `dist` |\n| **Express / NestJS / Fastify — server** | — | `express`/`nest`/`fastify` | build output dir |\n\nSSR/server frameworks run a persistent Node process (root sends `x-powered-by` / `cache-control: no-store`);\nstatic frameworks serve their output dir as files. If unsure of a framework's output dir, check the\nframework's own build output, but **always pass `appType`/`outputDirectory` on the deploy call with the\nframework's correct values** — don't rely on auto-detection (it returns null → 403).\n\n> ## ⚠️ Next.js 16+: build with webpack, not Turbopack (recurring deploy failure)\n> Next.js 16 makes **Turbopack** the default bundler for `next build`. Turbopack's native (Rust)\n> compiler needs a newer **glibc** than the Hostinger build server ships, so the server build aborts\n> with a \"glibc too old\" error — and Turbopack **does not fall back** to webpack on its own, so the\n> deploy fails every time. **Fix: build with webpack.** On **Next.js 16+** the project's `build` script\n> in `package.json` must be `next build --webpack` (not plain `next build`); `buildScript` on the deploy\n> call stays `\"build\"` — that's what runs it. The `--webpack` flag exists only on Next.js 16+; on\n> **Next.js 15.x** leave the build script as plain `next build` (it already defaults to webpack).\n> **Confirm this in `package.json` before deploying** (the frontend step scaffolds it this way — see\n> `../06-frontend`). Alternative, only if you must avoid the `--webpack` flag: pin Next.js to `15.x`\n> (keeping plain `next build`), whose `next build` still defaults to webpack. Next.js only — other\n> frameworks are unaffected.\n\n## Step 1 — Pre-flight\n\n1. **Instance live (the deploy gate).** `provision.status == \"completed\"`, re-verified with\n `hosting_websites_list-setups { \"domain\": \"<domain>\" }`: deploy overwrites the site root, so it never\n trusts `state.json` alone.\n2. **Build output exists locally** (the framework's output dir — e.g. `.next/`, `dist/`, `.output/`) and\n the project builds clean (frontend/validate already did this). If not, go back.\n - **Next.js 16+:** `package.json`'s `build` script is `next build --webpack`, not plain `next build` —\n the server's glibc can't run Turbopack's native compiler (see the box above). On Next.js 15.x leave it\n as plain `next build`. Fix it here if it isn't.\n3. **Env vars (only if used).** Build-time vars (e.g. `NEXT_PUBLIC_*`) must be set **before** the build\n with `hosting_nodejs_replace-environment-variables` (full replace). Never put secrets in the repo or\n the archive. **Webapp with a database:** that full replace wipes the `DB_*`/`DATABASE_URL` that\n `hosting_databases_setup-website` injected (the generated password reads back masked), so set all app\n vars in the same replace and, if you can't, first reset the password with\n `hosting_databases_change-password` and resend every `DB_*`/`DATABASE_URL` — see\n `../03-provision/webapp/SKILL.md` Step 3.\n\n## Step 2 — Archive the source\n\nZip the project **source** with `package.json` at the archive root. **Include** the app/source,\n`public/`, the framework config (`next.config.mjs` / `astro.config.mjs`), `tsconfig.json`,\n`package.json`, `package-lock.json`, `.nvmrc`. **Exclude** `node_modules/`, the build output\n(`.next/`, `dist/`, `out/`), `.git/`, and any `.htaccess` — the server installs and builds from source.\n\n> ## ⚠️ Write the archive outside `~/.hostinger/` (the deploy refuses it there)\n> `hosting_deploy` refuses any `path` under a hidden folder at the top of the home directory\n> (`~/.hostinger`, `~/.config`, …) with *\"it is, or contains, a home, system or credentials location\"*:\n> a deploy publishes what it reads, so the connector protects dotfolders that can hold tokens. That\n> covers both `~/.hostinger/<domain>/app.zip` **and** the `~/.hostinger/<domain>/src/` directory\n> itself, so neither can be passed as `path`. Keep the source in the workspace as usual, but write the\n> archive to a fresh temp directory and pass that. Don't copy the archive somewhere else after a\n> refusal, and don't move `src/` out of the workspace.\n\n```bash\n# macOS/Linux — the OS temp dir is outside the home directory\ncd ~/.hostinger/<domain>/src\nDEPLOY_DIR=$(mktemp -d)\nzip -r -X \"$DEPLOY_DIR/app.zip\" . -x 'node_modules/*' '.next/*' 'dist/*' 'out/*' '.git/*' '**/.htaccess'\necho \"$DEPLOY_DIR/app.zip\" # the absolute path to pass as `path` in Step 3\n```\n\n```powershell\n# Windows PowerShell — %TEMP% sits under AppData, which the deploy also refuses; use a plain folder in your\n# profile, which only you can write to (never a folder under C:\\, which every local account can write into)\ncd $HOME\\.hostinger\\<domain>\\src\n$DeployDir = Join-Path $HOME \"hostinger-deploy\\<domain>\"; New-Item -ItemType Directory -Force $DeployDir | Out-Null\ntar -a -cf \"$DeployDir\\app.zip\" --exclude=node_modules --exclude=.next --exclude=dist --exclude=out --exclude=.git --exclude=.htaccess .\n\"$DeployDir\\app.zip\" # the absolute path to pass as `path` in Step 3\n```\n\nDelete the temp directory once the build in Step 4 is `completed`.\n\n## Step 3 — Deploy (one shot: settings + upload + build)\n\nPass the framework's build settings **inline** on the deploy call — there is no separate settings step.\n`path` is the absolute path of the archive from Step 2, in its temp directory. Never pass a path under\n`~/.hostinger/`, the `src/` directory included: the deploy refuses it (see Step 2).\n\n```json\n{ \"operation\": \"hosting_deploy\",\n \"params\": {\n \"domain\": \"<domain>\",\n \"path\": \"<absolute path printed in Step 2, e.g. /var/folders/…/tmp.XXXX/app.zip>\",\n \"type\": \"nodejs\",\n \"appType\": \"<framework appType, e.g. next>\",\n \"outputDirectory\": \"<framework output dir, e.g. .next>\",\n \"nodeVersion\": 22,\n \"buildScript\": \"build\",\n \"packageManager\": \"npm\",\n \"rootDirectory\": \".\" } }\n```\n\n`hosting_deploy` uploads the source and triggers `npm install` + the build **end-to-end** — do not call\nany upload or build operation yourself. It returns a build `buildUuid` at once. This **overwrites the\nwebsite root** (expected) and keeps `/cms` intact. `type` is always `\"nodejs\"` for a headless site —\n**never `\"static\"`** (see the gate below). Passing `appType`/`outputDirectory` explicitly is what\nkeeps the root from serving 403 (see the rule above).\n\n## Step 4 — Wait for the build and the live root\n\nWait for it in one command (see *Waiting on Hostinger* in the top-level `SKILL.md`):\n\n```bash\ncd \"$HOME\" && node <skill>/wait.mjs build <domain> <buildUuid>\n```\n\nIt waits for `hosting_get-deployment` to report the build `completed`, then up to 5 minutes for\n`https://<domain>/` (or `http://` while the certificate is pending) to serve 200. What its result means here:\n\n- `ok: true`: the build is done and the root serves 200. Go on to Step 5.\n- `ok: true` with `https_pending: true`: the build is done and `http://<domain>/` serves 200, but the\n new domain's SSL certificate is still installing (this can take the better part of an hour). The\n deploy worked: tell the user HTTPS will follow on its own, run Step 5 over `http://`, and don't\n wait for the certificate.\n- `ok: false` with `build.state: failed`: read `log_tail` (the end of the build log) and `analysis`, fix\n locally, re-archive and redeploy (pass `fromLine` to `hosting_get-deployment` to read only new log\n output).\n- `ok: false` with `build settings missing`: the settings didn't take (the root would 403 for good). Fix\n the deploy call and redeploy.\n- `ok: false` with `timed_out`: `last_status` says whether the build was still running or the root\n wasn't serving 200 yet (see Step 5's note on a 403). For an SSR app that built but hangs,\n `hosting_nodejs_restart-application { username, domain }` recovers the server without a rebuild.\n\n## Step 5 — Verify the live site (all must pass)\n\n| Check | How | Expect |\n|---|---|---|\n| Root serves | `GET https://<domain>/` | **200** (not 403 / 404) |\n| SSR is live *(server frameworks)* | response headers | `x-powered-by` present, `cache-control: no-store` |\n| Static serves *(static frameworks)* | `GET https://<domain>/` | 200 HTML with real home content |\n| Key routes | a couple of planned routes + one deep route | 200, real content |\n| **Backend survived** *(WordPress / WooCommerce)* | `GET https://<domain>/cms/wp-json/wp/v2/posts?per_page=1` | 200 |\n\n> **Only WordPress (including WordPress + WooCommerce) has a `/cms` on the domain**, so the *Backend\n> survived* check is WordPress-only.\n> - **WordPress + WooCommerce:** also confirm the store survived the deploy —\n> `GET https://<domain>/cms/wp-json/wc/store/v1/products?per_page=1` → 200. There is nothing external to\n> link (no sales-channel step — that's Ecommerce only). **Checkout** stays owner-completed: when\n> `site.json → woocommerce.payment_enabled` is `false`, don't test `/checkout`; a catalog that serves 200\n> is a passing, complete deploy.\n> - **Ecommerce:** the backend is the **Hostinger Ecommerce store**, read over the external Storefront API\n> (`api-ecommerce.hostinger.com`) — nothing a deploy touches lives on this domain. There is no `/cms`;\n> confirm the storefront still fetches products as a frontend check if you like. **Only check that\n> checkout can be reached when `site.json → ecommerce.payment_enabled` is `true`** — on a free account\n> (`payment_enabled: false`) there is no checkout, so **skip that check entirely**; a catalog that serves\n> 200 is a passing, complete deploy. Never fail or hold the deploy because checkout is unavailable.\n> - **Webapp:** no content backend at all — the whole root is the app. Skip the check; `/cms` won't resolve.\n\nThe root check is already done when `wait.mjs build` returned `ok: true`; check the rest in one shell\ncommand (`curl` each URL). A `completed` build whose root 403s almost always means the build settings\nweren't passed to `hosting_deploy` (null settings) — pass them and redeploy. Caching can briefly serve a\nstale root; re-check after ~30 s.\n\n## Step 6 — Record `deploy.json`\n\n```json\n{\n \"build_uuid\": \"…\",\n \"stack\": \"nextjs\",\n \"rendering\": \"ssr\",\n \"app_type\": \"next\",\n \"output_directory\": \".next\",\n \"node_version\": 22,\n \"method\": \"hosting_deploy (type: nodejs, settings passed inline)\",\n \"deployed_at\": \"…\",\n \"verified_at\": \"…\",\n \"urls\": { \"live\": \"https://<domain>\", \"cms\": \"https://<domain>/cms\" },\n \"checks\": { \"root\": 200, \"ssr_headers\": true, \"backend_preserved\": true }\n}\n```\n\nNo secrets in `deploy.json`. The `urls.cms` field and the `backend_preserved` check above are\n**WordPress-only** — adjust the record to the backend:\n\n- **WordPress:** keep `urls.cms` and `checks.backend_preserved` as shown.\n- **WordPress + WooCommerce:** keep `urls.cms` + `checks.backend_preserved` (it *is* WordPress), and add\n `urls.store_api` from `site.json`; no external link step.\n- **Ecommerce:** omit `urls.cms`/`backend_preserved`; record the store URLs instead (`urls.storefront_api`,\n `urls.store_admin` from `site.json`) and link the custom sales channel to the live domain —\n `ecommerce_sales-channels_update { store_id, sales_channel_id, url }` (see the ecommerce provision step).\n- **Webapp:** omit `urls.cms` and `backend_preserved` entirely — `urls` is just `{ \"live\": \"https://<domain>\" }`.\n\nUpdate `state.json` (`stage` → `done`), then continue to Step 9 (done).\n\n---\n\n## Gate — a headless deploy is always `type: \"nodejs\"`, never `type: \"static\"`\n\n**Hard rule, check it before every deploy:** a headless site is deployed **only** with\n`type: \"nodejs\"` plus the explicit `appType`/`outputDirectory`/`nodeVersion`/`buildScript`/\n`packageManager`/`rootDirectory` from the table. **Never pass `type: \"static\"` on a headless site** — it\nserves the build as plain files over the document root and **overwrites `/cms`**, destroying the\nWordPress backend (this is the \"accidentally cleared cms\" failure). A static-built SPA (Vite/React/Vue)\nstill deploys as `type: \"nodejs\"` with its `appType` — the framework's static output is served correctly\nthat way, and `/cms` is preserved. If a flow ever tells you to deploy a headless site as `type:\n\"static\"`, you are on a stale/legacy skill copy — stop and update the skill (`npx skills update` or the plugin update for an installed skill, or connect's Phase 1 npm install for a web-installed `headless/` folder).\n\n`hosting_deploy` on the local server is the only path: give its `path` a local **archive** (`zip`, `tar`,\n`tar.gz`, `tgz`, `7z`) written outside `~/.hostinger/` as in Step 2. There is no separate upload or\nbuild step to fall back to.\n"
|
|
294
|
+
"text": "---\nname: headless-step-deploy\ndescription: \"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.\"\n---\n\n# headless-step-deploy\n\nShip the frontend to the live domain through the Hostinger connector. You hand the connector a zip of\nthe project **source** and it uploads it, runs `npm install` + the build script on the server, and\nserves the result. **Out:** `deploy.json`.\n\nThis is an **instance-barrier** step: run it only after `provision.status == \"completed\"` and validate\n(if run) has passed. All operations go through the connector (`execute`).\n\n> **Connected to the hosted server (`mcp.hostinger.com`)?** Its `hosting_deploy` deploys Git\n> repositories only and cannot read a local `path`. Run this step through the local\n> `hostinger-api-mcp` server instead (see the connect step:\n> `<command> <launcher>`).\n\n> **With a shell and the Hostinger CLI installed**, the same deploy is one command, with the build\n> settings passed exactly as the table below says. Run it from the project, since it links the current directory:\n> `cd ~/.hostinger/<domain>/src && hostinger up --domain <domain> --type nodejs --app-type <appType> --output-directory <dir> --build-script build --node-version 22 --package-manager npm --yes --format json`.\n> It uploads, builds, waits and returns `data.buildUuid` and `data.buildState`; add `--no-wait` to\n> return at once and wait with `cd \"$HOME\" && node <skill>/wait.mjs build <domain> <uuid>`. Then continue at\n> \"Verify\" below. Recent CLI versions see that the site is headless (`data.headless: true`) and\n> deploy only its Node.js frontend, leaving `/cms` alone; still pass the settings above.\n\n**In:** the project in `~/.hostinger/<domain>/src/`, `site.json` (`username`, `urls`), `state.json`\n(`frontend.framework`, `frontend.rendering`).\n\n> ## ⚠️ The one rule that makes this work: pass build settings explicitly\n> If you let `hosting_deploy` **auto-detect** build settings, for a headless site that detection returns\n> **null** (`appType:null`, `outputDirectory:null`, Node 20) — the build \"completes\" but the **root\n> serves 403** (no `appType`/output → the vhost serves a directory with no entry). This is reproducible.\n> **Always pass `appType`, `outputDirectory`, `nodeVersion`, `buildScript`, `packageManager` and\n> `rootDirectory` on the `hosting_deploy` call** with the framework's values; the deploy then resolves\n> them and serves correctly, and `/cms` is preserved.\n\n## Build configurations\n\nMap `frontend.framework` (from `state.json`) to its `appType` + build output directory, and pass those\non the `hosting_deploy` call. `appType` is the framework's value, e.g. `next`, `nuxt`, `astro`,\n`svelte-kit`, `nest`, `express`, `fastify`, `react`, `create-react-app`, `gatsby`, `vite`, `vue`,\n`angular`, `parcel`, `svelte`, `other`.\n\nCommon cases (all `nodeVersion: 22`, `buildScript: \"build\"`, `packageManager: \"npm\"`, `rootDirectory: \".\"`):\n\n| Framework / mode | Local config | `appType` | `outputDirectory` |\n|---|---|---|---|\n| **Next.js — SSR** *(default)* | `output: 'standalone'` | `next` | `.next` |\n| **Nuxt — SSR** | default | `nuxt` | `.output` |\n| **SvelteKit — SSR** | node adapter | `svelte-kit` | `build` |\n| **Astro — static** | `output: 'static'` | `astro` | `dist` |\n| **Vite / React / Vue — static (SPA)** | — | `vite` (or `react`/`vue`) | `dist` |\n| **Express / NestJS / Fastify — server** | — | `express`/`nest`/`fastify` | build output dir |\n\nSSR/server frameworks run a persistent Node process (root sends `x-powered-by` / `cache-control: no-store`);\nstatic frameworks serve their output dir as files. If unsure of a framework's output dir, check the\nframework's own build output, but **always pass `appType`/`outputDirectory` on the deploy call with the\nframework's correct values** — don't rely on auto-detection (it returns null → 403).\n\n> ## ⚠️ Next.js 16+: build with webpack, not Turbopack (recurring deploy failure)\n> Next.js 16 makes **Turbopack** the default bundler for `next build`. Turbopack's native (Rust)\n> compiler needs a newer **glibc** than the Hostinger build server ships, so the server build aborts\n> with a \"glibc too old\" error — and Turbopack **does not fall back** to webpack on its own, so the\n> deploy fails every time. **Fix: build with webpack.** On **Next.js 16+** the project's `build` script\n> in `package.json` must be `next build --webpack` (not plain `next build`); `buildScript` on the deploy\n> call stays `\"build\"` — that's what runs it. The `--webpack` flag exists only on Next.js 16+; on\n> **Next.js 15.x** leave the build script as plain `next build` (it already defaults to webpack).\n> **Confirm this in `package.json` before deploying** (the frontend step scaffolds it this way — see\n> `../06-frontend`). Alternative, only if you must avoid the `--webpack` flag: pin Next.js to `15.x`\n> (keeping plain `next build`), whose `next build` still defaults to webpack. Next.js only — other\n> frameworks are unaffected.\n\n## Step 1 — Pre-flight\n\n1. **Instance live (the deploy gate).** `provision.status == \"completed\"`, re-verified with\n `hosting_websites_list-setups { \"domain\": \"<domain>\" }`: deploy overwrites the site root, so it never\n trusts `state.json` alone.\n2. **Build output exists locally** (the framework's output dir — e.g. `.next/`, `dist/`, `.output/`) and\n the project builds clean (frontend/validate already did this). If not, go back.\n - **Next.js 16+:** `package.json`'s `build` script is `next build --webpack`, not plain `next build` —\n the server's glibc can't run Turbopack's native compiler (see the box above). On Next.js 15.x leave it\n as plain `next build`. Fix it here if it isn't.\n3. **Env vars (only if used).** Build-time vars (e.g. `NEXT_PUBLIC_*`) must be set **before** the build\n with `hosting_nodejs_replace-environment-variables` (full replace). Never put secrets in the repo or\n the archive. **Webapp with a database:** that full replace wipes the `DB_*`/`DATABASE_URL` that\n `hosting_databases_setup-website` injected (the generated password reads back masked), so set all app\n vars in the same replace and, if you can't, first reset the password with\n `hosting_databases_change-password` and resend every `DB_*`/`DATABASE_URL` — see\n `../03-provision/webapp/SKILL.md` Step 3.\n\n## Step 2 — Archive the source\n\nZip the project **source** with `package.json` at the archive root. **Include** the app/source,\n`public/`, the framework config (`next.config.mjs` / `astro.config.mjs`), `tsconfig.json`,\n`package.json`, `package-lock.json`, `.nvmrc`. **Exclude** `node_modules/`, the build output\n(`.next/`, `dist/`, `out/`), `.git/`, and any `.htaccess` — the server installs and builds from source.\n**Never archive secrets:** the commands below also leave out `.env*` files, `.npmrc` and key/certificate\nfiles (`*.pem`, `*.key`, `*.p12`, `*.pfx`). A brought-in project often has a `.env.local`; its values go in\nas environment variables (Step 1), never in the archive.\n\n> ## ⚠️ Write the archive outside `~/.hostinger/` (the deploy refuses it there)\n> `hosting_deploy` refuses any `path` under a hidden folder at the top of the home directory\n> (`~/.hostinger`, `~/.config`, …) with *\"it is, or contains, a home, system or credentials location\"*:\n> a deploy publishes what it reads, so the connector protects dotfolders that can hold tokens. That\n> covers both `~/.hostinger/<domain>/app.zip` **and** the `~/.hostinger/<domain>/src/` directory\n> itself, so neither can be passed as `path`. Keep the source in the workspace as usual, but write the\n> archive to a fresh temp directory and pass that. Don't copy the archive somewhere else after a\n> refusal, and don't move `src/` out of the workspace.\n\n```bash\n# macOS/Linux — the OS temp dir is outside the home directory\ncd ~/.hostinger/<domain>/src\nDEPLOY_DIR=$(mktemp -d)\nzip -r -X \"$DEPLOY_DIR/app.zip\" . -x 'node_modules/*' '.next/*' 'dist/*' 'out/*' '.git/*' '**/.htaccess' \\\n '.env*' '*/.env*' '.npmrc' '*/.npmrc' '*.pem' '*.key' '*.p12' '*.pfx'\necho \"$DEPLOY_DIR/app.zip\" # the absolute path to pass as `path` in Step 3\n```\n\n```powershell\n# Windows PowerShell — %TEMP% sits under AppData, which the deploy also refuses; use a plain folder in your\n# profile, which only you can write to (never a folder under C:\\, which every local account can write into)\ncd $HOME\\.hostinger\\<domain>\\src\n$DeployDir = Join-Path $HOME \"hostinger-deploy\\<domain>\"; New-Item -ItemType Directory -Force $DeployDir | Out-Null\ntar -a -cf \"$DeployDir\\app.zip\" --exclude=node_modules --exclude=.next --exclude=dist --exclude=out --exclude=.git --exclude=.htaccess `\n --exclude=.env* --exclude=.npmrc --exclude=*.pem --exclude=*.key --exclude=*.p12 --exclude=*.pfx .\n\"$DeployDir\\app.zip\" # the absolute path to pass as `path` in Step 3\n```\n\nDelete the temp directory once the build in Step 4 is `completed`.\n\n## Step 3 — Deploy (one shot: settings + upload + build)\n\nPass the framework's build settings **inline** on the deploy call — there is no separate settings step.\n`path` is the absolute path of the archive from Step 2, in its temp directory. Never pass a path under\n`~/.hostinger/`, the `src/` directory included: the deploy refuses it (see Step 2).\n\n```json\n{ \"operation\": \"hosting_deploy\",\n \"params\": {\n \"domain\": \"<domain>\",\n \"path\": \"<absolute path printed in Step 2, e.g. /var/folders/…/tmp.XXXX/app.zip>\",\n \"type\": \"nodejs\",\n \"appType\": \"<framework appType, e.g. next>\",\n \"outputDirectory\": \"<framework output dir, e.g. .next>\",\n \"nodeVersion\": 22,\n \"buildScript\": \"build\",\n \"packageManager\": \"npm\",\n \"rootDirectory\": \".\" } }\n```\n\n`hosting_deploy` uploads the source and triggers `npm install` + the build **end-to-end** — do not call\nany upload or build operation yourself. It returns a build `buildUuid` at once. This **overwrites the\nwebsite root** (expected) and keeps `/cms` intact. `type` is always `\"nodejs\"` for a headless site —\n**never `\"static\"`** (see the gate below). Passing `appType`/`outputDirectory` explicitly is what\nkeeps the root from serving 403 (see the rule above).\n\n## Step 4 — Wait for the build and the live root\n\nWait for it in one command (see *Waiting on Hostinger* in the top-level `SKILL.md`):\n\n```bash\ncd \"$HOME\" && node <skill>/wait.mjs build <domain> <buildUuid>\n```\n\nIt waits for `hosting_get-deployment` to report the build `completed`, then up to 5 minutes for\n`https://<domain>/` (or `http://` while the certificate is pending) to serve 200. What its result means here:\n\n- `ok: true`: the build is done and the root serves 200. Go on to Step 5.\n- `ok: true` with `https_pending: true`: the build is done and `http://<domain>/` serves 200, but the\n new domain's SSL certificate is still installing (this can take the better part of an hour). The\n deploy worked: tell the user HTTPS will follow on its own, run Step 5 over `http://`, and don't\n wait for the certificate.\n- `ok: false` with `build.state: failed`: read `log_tail` (the end of the build log) and `analysis`, fix\n locally, re-archive and redeploy (pass `fromLine` to `hosting_get-deployment` to read only new log\n output).\n- `ok: false` with `build settings missing`: the settings didn't take (the root would 403 for good). Fix\n the deploy call and redeploy.\n- `ok: false` with `timed_out`: `last_status` says whether the build was still running or the root\n wasn't serving 200 yet (see Step 5's note on a 403). For an SSR app that built but hangs,\n `hosting_nodejs_restart-application { username, domain }` recovers the server without a rebuild.\n\n## Step 5 — Verify the live site (all must pass)\n\n| Check | How | Expect |\n|---|---|---|\n| Root serves | `GET https://<domain>/` | **200** (not 403 / 404) |\n| SSR is live *(server frameworks)* | response headers | `x-powered-by` present, `cache-control: no-store` |\n| Static serves *(static frameworks)* | `GET https://<domain>/` | 200 HTML with real home content |\n| Key routes | a couple of planned routes + one deep route | 200, real content |\n| **Backend survived** *(WordPress / WooCommerce)* | `GET https://<domain>/cms/wp-json/wp/v2/posts?per_page=1` | 200 |\n\n> **Only WordPress (including WordPress + WooCommerce) has a `/cms` on the domain**, so the *Backend\n> survived* check is WordPress-only.\n> - **WordPress + WooCommerce:** also confirm the store survived the deploy —\n> `GET https://<domain>/cms/wp-json/wc/store/v1/products?per_page=1` → 200. There is nothing external to\n> link (no sales-channel step — that's Ecommerce only). **Checkout** stays owner-completed: when\n> `site.json → woocommerce.payment_enabled` is `false`, don't test `/checkout`; a catalog that serves 200\n> is a passing, complete deploy.\n> - **Ecommerce:** the backend is the **Hostinger Ecommerce store**, read over the external Storefront API\n> (`api-ecommerce.hostinger.com`) — nothing a deploy touches lives on this domain. There is no `/cms`;\n> confirm the storefront still fetches products as a frontend check if you like. **Only check that\n> checkout can be reached when `site.json → ecommerce.payment_enabled` is `true`** — on a free account\n> (`payment_enabled: false`) there is no checkout, so **skip that check entirely**; a catalog that serves\n> 200 is a passing, complete deploy. Never fail or hold the deploy because checkout is unavailable.\n> - **Webapp:** no content backend at all — the whole root is the app. Skip the check; `/cms` won't resolve.\n\nThe root check is already done when `wait.mjs build` returned `ok: true`; check the rest in one shell\ncommand (`curl` each URL). A `completed` build whose root 403s almost always means the build settings\nweren't passed to `hosting_deploy` (null settings) — pass them and redeploy. Caching can briefly serve a\nstale root; re-check after ~30 s.\n\n## Step 6 — Record `deploy.json`\n\n```json\n{\n \"build_uuid\": \"…\",\n \"stack\": \"nextjs\",\n \"rendering\": \"ssr\",\n \"app_type\": \"next\",\n \"output_directory\": \".next\",\n \"node_version\": 22,\n \"method\": \"hosting_deploy (type: nodejs, settings passed inline)\",\n \"deployed_at\": \"…\",\n \"verified_at\": \"…\",\n \"urls\": { \"live\": \"https://<domain>\", \"cms\": \"https://<domain>/cms\" },\n \"checks\": { \"root\": 200, \"ssr_headers\": true, \"backend_preserved\": true }\n}\n```\n\nNo secrets in `deploy.json`. The `urls.cms` field and the `backend_preserved` check above are\n**WordPress-only** — adjust the record to the backend:\n\n- **WordPress:** keep `urls.cms` and `checks.backend_preserved` as shown.\n- **WordPress + WooCommerce:** keep `urls.cms` + `checks.backend_preserved` (it *is* WordPress), and add\n `urls.store_api` from `site.json`; no external link step.\n- **Ecommerce:** omit `urls.cms`/`backend_preserved`; record the store URLs instead (`urls.storefront_api`,\n `urls.store_admin` from `site.json`) and link the custom sales channel to the live domain —\n `ecommerce_sales-channels_update { store_id, sales_channel_id, url }` (see the ecommerce provision step).\n- **Webapp:** omit `urls.cms` and `backend_preserved` entirely — `urls` is just `{ \"live\": \"https://<domain>\" }`.\n\nUpdate `state.json` (`stage` → `done`), then continue to Step 9 (done).\n\n---\n\n## Gate — a headless deploy is always `type: \"nodejs\"`, never `type: \"static\"`\n\n**Hard rule, check it before every deploy:** a headless site is deployed **only** with\n`type: \"nodejs\"` plus the explicit `appType`/`outputDirectory`/`nodeVersion`/`buildScript`/\n`packageManager`/`rootDirectory` from the table. **Never pass `type: \"static\"` on a headless site** — it\nserves the build as plain files over the document root and **overwrites `/cms`**, destroying the\nWordPress backend (this is the \"accidentally cleared cms\" failure). A static-built SPA (Vite/React/Vue)\nstill deploys as `type: \"nodejs\"` with its `appType` — the framework's static output is served correctly\nthat way, and `/cms` is preserved. If a flow ever tells you to deploy a headless site as `type:\n\"static\"`, you are on a stale/legacy skill copy — stop and update the skill (`npx skills update` or the plugin update for an installed skill, or connect's Phase 1 npm install for a web-installed `headless/` folder).\n\n`hosting_deploy` on the local server is the only path: give its `path` a local **archive** (`zip`, `tar`,\n`tar.gz`, `tgz`, `7z`) written outside `~/.hostinger/` as in Step 2. There is no separate upload or\nbuild step to fall back to.\n"
|
|
295
295
|
},
|
|
296
296
|
{
|
|
297
297
|
"uri": "skill://hostinger-headless/steps/09-done/SKILL.md",
|
|
@@ -4,4 +4,4 @@ import { startServer } from '../core/runtime.js';
|
|
|
4
4
|
import tools from '../core/tools/agency-hosting.js';
|
|
5
5
|
import instructions from '../core/instructions.agency-hosting.js';
|
|
6
6
|
|
|
7
|
-
startServer({ name: 'hostinger-agency-hosting-mcp', version: '3.38.
|
|
7
|
+
startServer({ name: 'hostinger-agency-hosting-mcp', version: '3.38.3', tools, instructions });
|
|
@@ -4,4 +4,4 @@ import { startServer } from '../core/runtime.js';
|
|
|
4
4
|
import tools from '../core/tools/agency-hosting.js';
|
|
5
5
|
import instructions from '../core/instructions.agency-hosting.js';
|
|
6
6
|
|
|
7
|
-
startServer({ name: 'hostinger-agency-hosting-mcp', version: '3.38.
|
|
7
|
+
startServer({ name: 'hostinger-agency-hosting-mcp', version: '3.38.3', tools, instructions });
|
|
@@ -3,4 +3,4 @@
|
|
|
3
3
|
import { startServer } from '../core/runtime.js';
|
|
4
4
|
import tools from '../core/tools/agent-readiness.js';
|
|
5
5
|
|
|
6
|
-
startServer({ name: 'hostinger-agent-readiness-mcp', version: '3.38.
|
|
6
|
+
startServer({ name: 'hostinger-agent-readiness-mcp', version: '3.38.3', tools });
|
|
@@ -3,4 +3,4 @@
|
|
|
3
3
|
import { startServer } from '../core/runtime.js';
|
|
4
4
|
import tools from '../core/tools/agent-readiness.js';
|
|
5
5
|
|
|
6
|
-
startServer({ name: 'hostinger-agent-readiness-mcp', version: '3.38.
|
|
6
|
+
startServer({ name: 'hostinger-agent-readiness-mcp', version: '3.38.3', tools });
|
package/src/servers/all.js
CHANGED
|
@@ -5,4 +5,4 @@ import tools from '../core/tools/all.js';
|
|
|
5
5
|
import instructions from '../core/instructions.js';
|
|
6
6
|
import skills from '../core/skills.js';
|
|
7
7
|
|
|
8
|
-
startServer({ name: 'hostinger-api-mcp', version: '3.38.
|
|
8
|
+
startServer({ name: 'hostinger-api-mcp', version: '3.38.3', tools, instructions, skills });
|
package/src/servers/all.ts
CHANGED
|
@@ -5,4 +5,4 @@ import tools from '../core/tools/all.js';
|
|
|
5
5
|
import instructions from '../core/instructions.js';
|
|
6
6
|
import skills from '../core/skills.js';
|
|
7
7
|
|
|
8
|
-
startServer({ name: 'hostinger-api-mcp', version: '3.38.
|
|
8
|
+
startServer({ name: 'hostinger-api-mcp', version: '3.38.3', tools, instructions, skills });
|
package/src/servers/billing.js
CHANGED
package/src/servers/billing.ts
CHANGED
package/src/servers/dns.js
CHANGED
package/src/servers/dns.ts
CHANGED
package/src/servers/domains.js
CHANGED
package/src/servers/domains.ts
CHANGED
package/src/servers/ecommerce.js
CHANGED
package/src/servers/ecommerce.ts
CHANGED
package/src/servers/gpu.js
CHANGED
package/src/servers/gpu.ts
CHANGED
package/src/servers/horizons.js
CHANGED
package/src/servers/horizons.ts
CHANGED
package/src/servers/hosting.js
CHANGED
|
@@ -4,4 +4,4 @@ import { startServer } from '../core/runtime.js';
|
|
|
4
4
|
import tools from '../core/tools/hosting.js';
|
|
5
5
|
import instructions from '../core/instructions.js';
|
|
6
6
|
|
|
7
|
-
startServer({ name: 'hostinger-hosting-mcp', version: '3.38.
|
|
7
|
+
startServer({ name: 'hostinger-hosting-mcp', version: '3.38.3', tools, instructions });
|
package/src/servers/hosting.ts
CHANGED
|
@@ -4,4 +4,4 @@ import { startServer } from '../core/runtime.js';
|
|
|
4
4
|
import tools from '../core/tools/hosting.js';
|
|
5
5
|
import instructions from '../core/instructions.js';
|
|
6
6
|
|
|
7
|
-
startServer({ name: 'hostinger-hosting-mcp', version: '3.38.
|
|
7
|
+
startServer({ name: 'hostinger-hosting-mcp', version: '3.38.3', tools, instructions });
|
package/src/servers/mail.js
CHANGED
package/src/servers/mail.ts
CHANGED
package/src/servers/reach.js
CHANGED
package/src/servers/reach.ts
CHANGED
package/src/servers/vps.js
CHANGED
package/src/servers/vps.ts
CHANGED
package/src/servers/wordpress.js
CHANGED
package/src/servers/wordpress.ts
CHANGED