@wix/mcp 1.0.94 → 1.0.95

package/build/dts/api-call/upload-headless-website-files.js

@@ -5,22 +5,44 @@
  * `/headless-business/{msid}/drop`. Provisioning the site is NOT done here —
  * the recipe's step 1 (StartDeployWebsite → provision) stays with the agent.
  *
+ * A Wix Astro build among the files (`.wix/build-metadata.json` beside `dist/`,
+ * zipped from the project root) takes headless-business-setup's bundle routes
+ * instead, server-side in this handler: `bundle-upload-url` with the zip's size, a
+ * PUT of the zip, a PUT of the project's source zip when the upload holds the
+ * source and the site's repository takes it, then `release-bundle`. The service
+ * provisions the site's managed project and deploys. Same inputs, same siteId.
+ *
  * Takes the same file inputs as ExecuteWixAPI — the `files` text bundle and
  * ChatGPT `attachments` (openai/fileParams) — and does the work directly: parse,
- * unzip, check the site shape, POST, return the live URL. No sandbox, no
+ * unzip, check the site shape, upload, return the live URL. No sandbox, no
  * agent-written code, no runtime dependency.
+ *
+ * A Wix Astro build from a client that cannot hand a file to the tool (no attachment
+ * swap, bytes only as text) has a third form, in two calls over the same routes:
+ * `prepare: true` with the build zip's `size` returns presigned PUT URLs for the
+ * build zip and the project's source zip (the agent uploads them with curl from its
+ * sandbox), and a second call with the `uploadKey` releases the uploaded build
+ * server-side. A static site keeps the drop: `files`, `attachments`, or the
+ * StartDeployWebsite recipe's own drop. Same schema for every client; the
+ * description speaks in capabilities, not names.
  */
 import { z } from 'zod';
 import { AttachmentError, resolveAttachments } from '../code-mode/attachments.js';
-import { base64ToBytes, buildFormData, normalizeSiteFiles, parseFileBundle } from './site-files.js';
-import { HEADLESS_GUIDE_URL } from '../docs/start-headless-build.js';
+import { base64ToBytes, buildFormData, expandSiteFiles, isZip, staticSiteFiles, parseFileBundle, zipStored } from './site-files.js';
+import { buildSourceFiles, findHeadlessBuild, withoutEmptyStatics } from './headless-release.js';
+import { fileParamNote } from '../config/file-params.js';
+import { WIX_BUSINESS_FEATURES } from '../site-widget-tools/constants.js';
+import { NO_PERSONAL_DATA } from '../docs/start-deploy-website.js';
 import { logger } from '../infra/logger.js';
+import { redactPersonalData } from '../infra/redact-personal-data.js';
 import { defaultToolDescriptions } from '../config/default-config.js';
 import { rethrowIfUnauthorized } from '../auth/index.js';
 import { WixFetchError } from '../wix-fetch-error.js';
-import { START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS, START_DEPLOY_WEBSITE_RECIPE_URL as RECIPE_URL } from '../docs/start-deploy-website.js';
+import { START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS } from '../docs/start-deploy-website.js';
 export const UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME = 'UploadHeadlessWebsiteFiles';
 const HEADLESS_BUSINESS = 'https://www.wixapis.com/headless-business-setup/v1/headless-business';
+/** The largest site zip `bundle-upload-url` presigns (headless-business-setup's MAX_BUNDLE_BYTES). */
+export const MAX_BUNDLE_BYTES = 100 * 1024 * 1024;
 /**
  * Attribution the drop endpoint stamps on its upload BI event (`source` from
  * `campaign`, `agent` from `agent`, both ≤ 64 chars) — the same parser as the
@@ -36,13 +58,23 @@ export function dropAttribution(clientName) {
     return `?campaign=mcp&agent=${encodeURIComponent(slug || 'wix-mcp')}`;
 }
 export const UPLOAD_HEADLESS_WEBSITE_FILES_PARAM_DESCRIPTIONS = {
-    files: 'The site files as text, so file bytes never pass through a code string. Sections delimited by a line `=== FILE: <path> ===` (text, raw) or `=== FILE: <path> base64 ===` (binary, base64); `<path>` is relative to the site root and must include `index.html`. Use base64 for small binaries (icons, logos, fonts); large images/video belong behind a URL in the HTML, not in the bundle. Optional when `attachments` carries the files.',
-    attachments: 'ChatGPT only. Files attached in the chat or created in your sandbox — any type: a zip of the whole site, HTML, CSS, JS, images. Pass each file as you have it, its file id or its /mnt/data path, and ChatGPT swaps it for { download_url, file_id, file_name?, mime_type? } before the call reaches Wix. No other client does this swap, so outside ChatGPT a path or file:// URL here fails at once; leave this out and use `files`, or, with a shell that reaches the internet, drop the files with curl as the StartDeployWebsite recipe shows. A zip is unpacked; a top-level folder wrapping the site is stripped. Prefer this over base64 in `files` whenever you have a file handle. Up to 10 MB per call.',
-    siteId: 'The metaSiteId of the Wix Headless site to upload into: the one returned by the provision call of the StartDeployWebsite recipe for a new site, or of a site deployed earlier to replace its files. Every upload replaces the whole file set, so send all files; the URL stays the same.',
+    files: "The site files as text, so file bytes never pass through a code string. Sections delimited by a line `=== FILE: <path> ===` (text, raw) or `=== FILE: <path> base64 ===` (binary, base64); `<path>` is relative to the site root; a static site must include `index.html`. Use base64 for small binaries (icons, logos, fonts); large images/video belong behind a URL in the HTML, not in the bundle. Optional when `attachments` carries the files. A Wix Astro build (`.wix/build-metadata.json` and `dist/` as `astro build` with the Wix hosting adapter wrote them, zipped from the project root) needs no `index.html`: it is released to the site's Wix hosting instead of dropped, and the project's other files in the upload are stored as its source when the site's repository accepts it.",
+    attachments: fileParamNote('for a static site use `files`, or drop the files as the StartDeployWebsite recipe shows; for a Wix Astro build from a shell that reaches the internet, zip it, call with `prepare: true` and its `size` and PUT the zips with curl') +
+        " Any type: a zip of the whole site, HTML, CSS, JS, images. A zip is unpacked; a top-level folder wrapping the site is stripped. A Wix Astro build zipped with the whole project (minus `node_modules`) is released with its source stored when the site's repository accepts it. Prefer this over base64 in `files` whenever you have a file handle. Up to 10 MB per call.",
+    prepare: "Phase one of the two-call upload of a Wix Astro build, for a shell that reaches the internet and no file handle (a sandbox whose network is limited to a few hosts cannot upload to the URLs): zip the build first, then `true` with its `size` returns presigned upload URLs for the build zip and, when the site's repository takes it, the project source zip, as `curl` commands to run verbatim, with the exact second call. The two calls: {siteId, prepare: true, size}, then {siteId, uploadKey, sourceUploadId?, expectedHeadRevisionId?, releaseNotes?}. No `files`, `attachments`, `uploadKey` or `sourceUploadId` on the first; `expectedHeadRevisionId` and `releaseNotes` given on the first are echoed into the second. Not for a static site: send its files in `files` or `attachments`, or drop them as the StartDeployWebsite recipe shows.",
+    size: `Phase one, with \`prepare: true\` only, and required there: the build zip's length in bytes (\`wc -c < build.zip\`), 1 to ${MAX_BUNDLE_BYTES} (100 MB). The upload URL takes a body of exactly this length; a zip changed after the prepare needs a new prepare.`,
+    uploadKey: 'Phase two of the two-call upload: the `uploadKey` the `prepare` call returned, after the build zip was PUT to its URL. Releases that build to the site: {siteId, uploadKey, sourceUploadId?, expectedHeadRevisionId?, releaseNotes?}. Excludes `files` and `attachments`.',
+    sourceUploadId: 'Phase two: the `sourceUploadId` the `prepare` call returned, after the source zip was PUT to its URL. Stores the project source with the release. Needs `uploadKey`; leave it out when the prepare returned no source upload.',
+    expectedHeadRevisionId: 'The repository revision your project started from, so the source replaces only that and a commit made since (another chat, a Dev Machine) is never dropped unseen: the revision you downloaded the project at; for a project started here, the `headRevisionId` the `prepare` call returned. Leave it out only for a repository with nothing in it yet. Goes with `uploadKey`, or with `files`/`attachments` holding a build.',
+    releaseNotes: 'Optional: one line on what this release changes, at most 200 characters, kept with the deployment of a Wix Astro build, whether it comes in `files`/`attachments` or as the second call with `uploadKey` (given on the `prepare` call it is echoed into the second). A static drop keeps no notes.',
+    siteId: 'The metaSiteId of the Wix Headless site to upload into: the one returned by the provision call of the StartDeployWebsite recipe for a new site, or of a site deployed earlier to replace its files. Every upload replaces the whole file set, so send all files; the URL stays the same. A build released here replaces static pages dropped earlier, at the same URL.',
     calledStartDeployWebsite: 'Whether you called StartDeployWebsite earlier in this conversation and are following the recipe it returned. Answer truthfully; it is recorded, not checked.',
     agentIdentity: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.agentIdentity,
-    reason: 'One sentence: the user request that led here and what is being published.'
+    reason: `One sentence: the user request that led here and what is being published. ${NO_PERSONAL_DATA}`
 };
+// The wix-manage skill's recipes, which the success reply points to for what comes next.
+const UPLOAD_RECIPE_SKILL_URL = 'https://www.wix.com/skills/wix-manage/references/sites/upload-static-site.md';
+const DOMAIN_RECIPE_SKILL_URL = 'https://www.wix.com/skills/wix-manage/references/domains/domain-search-purchase-and-connect.md';
 export function formatDropResult(r) {
     const shown = r.files.slice(0, 60);
     return [
@@ -52,10 +84,195 @@ export function formatDropResult(r) {
         `Dashboard: https://manage.wix.com/dashboard/${r.metaSiteId}`,
         `${r.files.length} file(s): ${shown.join(', ')}${r.files.length > shown.length ? ', …' : ''}`,
         '',
-        'Give the user the live URL and the dashboard link.',
-        `The upload step is done. For what comes next — changing the site later, connecting a domain, or adding a Wix backend (forms, bookings, a store) to this same site — continue with the guide you are following, from where it left off: the StartDeployWebsite recipe (${RECIPE_URL}) or, for a site built through StartHeadlessBuild, the headless guide (${HEADLESS_GUIDE_URL}).`
+        `Give the user both links, each on its own line and named for what it is: the live site, and the site's dashboard. Then offer a custom domain, bought through Wix or one they already own (${DOMAIN_RECIPE_SKILL_URL}).`,
+        '',
+        `- To change this site later: "Change it later" in ${UPLOAD_RECIPE_SKILL_URL}, with this metaSiteId (${r.metaSiteId}). The same site every time, never a new one.`,
+        `- Wix business features (${WIX_BUSINESS_FEATURES}): call StartHeadlessBuild with startingPoint "an existing Wix Headless site"; this site is one.`
+    ].join('\n');
+}
+/** The curl that PUTs a zip to its presigned URL, with the headers the route returned. */
+function curlPut(zipName, put, fallback) {
+    const headers = Object.entries(put.headers && Object.keys(put.headers).length ? put.headers : fallback);
+    return [
+        'curl -X PUT',
+        ...headers.map(([k, v]) => `-H "${k}: ${v}"`),
+        `--data-binary @${zipName} "${put.putUrl}"`
+    ].join(' ');
+}
+const BUILD_ZIP_CONTENTS = 'Build zip, from the project root after `astro build` with the Wix hosting adapter: `dist/` (with `dist/_wix/app-manifest.json`) and `.wix/build-metadata.json`.';
+const SOURCE_ZIP_CONTENTS = 'Source zip, from the project root: the project minus `node_modules`, `dist`, `.wix`, `.astro`, `.env*` and `.agents`.';
+/** The prepare reply: what the agent runs, verbatim, and the exact second call. */
+export function formatPrepareResult(siteId, urls, size, given = {}) {
+    const expiry = urls.expiresAt ? ` They expire at ${urls.expiresAt}.` : '';
+    const secondCall = {
+        siteId,
+        uploadKey: urls.uploadKey
+    };
+    const zipHeaders = {
+        'content-type': 'application/zip',
+        ...(size ? { 'content-length': String(size) } : {})
+    };
+    const lines = [
+        `Upload URLs ready for site ${siteId}.${expiry} Two steps, then call this tool again.`,
+        '',
+        `1. ${BUILD_ZIP_CONTENTS} Upload the zip you measured${size ? ` (${size} bytes)` : ''}; the URL takes a body of exactly that length, so a zip changed since needs a new prepare with its size:`,
+        `   ${curlPut('build.zip', urls, zipHeaders)}`
+    ];
+    // The agent's own revision wins: it is the one its project started from. Given, it is echoed
+    // whether or not a source half came back.
+    if (given.expectedHeadRevisionId)
+        secondCall.expectedHeadRevisionId = given.expectedHeadRevisionId;
+    if (urls.source) {
+        const s = urls.source;
+        secondCall.sourceUploadId = s.uploadId;
+        if (!secondCall.expectedHeadRevisionId && s.headRevisionId)
+            secondCall.expectedHeadRevisionId = s.headRevisionId;
+        lines.push('', `2. ${SOURCE_ZIP_CONTENTS} Upload it:`, `   ${curlPut('source.zip', s, { 'content-type': 'application/zip' })}`, ...(s.expiresAt && s.expiresAt !== urls.expiresAt
+            ? [`   This URL expires at ${s.expiresAt}.`]
+            : []), ...(s.headRevisionId
+            ? [
+                `   The repository's head revision is ${s.headRevisionId}. The second call passes \`expectedHeadRevisionId\`: this head for a project started here; if you downloaded the project from the repository, the revision you downloaded it at instead, so a commit made since is never dropped.`
+            ]
+            : []));
+    }
+    else {
+        lines.push('', "2. The site's repository takes no source this time: the project's source is not uploaded, and the second call carries no `sourceUploadId`.");
+    }
+    if (given.releaseNotes)
+        secondCall.releaseNotes = releaseNotesForService(given.releaseNotes);
+    lines.push('', `3. Call UploadHeadlessWebsiteFiles again with ${JSON.stringify(secondCall)} (plus \`calledStartDeployWebsite\`, \`agentIdentity\`, \`reason\`). No \`files\` or \`attachments\` on that call.`);
+    return lines.join('\n');
+}
+/** The release-bundle reply, for both the two-call form and a build uploaded as files. */
+export function formatBundleReleaseResult(siteId, r, notes = []) {
+    return [
+        'Released; the site is live.',
+        `Live URL: ${r.siteUrl ?? '(not returned)'}`,
+        `metaSiteId: ${siteId} — pass it as \`siteId\` to release this site again, the same way. The URL stays.`,
+        `Dashboard: https://manage.wix.com/dashboard/${siteId}`,
+        `Deployment ${r.deploymentId ?? '(id not returned)'}.${r.revision?.id ? ` Source stored as revision ${r.revision.id}.` : ''}`,
+        ...notes,
+        '',
+        'This release replaced whatever the site served before, at the same URL. A change to the site is a change to the project: edit, build if it is an Astro project, upload again.',
+        "Give the user both links, each on its own line and named for what it is: the live site, and the site's dashboard."
     ].join('\n');
 }
+const startOver = (retry) => retry === 'prepare'
+    ? "call with `prepare: true` and the zip's `size` again, upload the zips to the new URLs, and release with the new `uploadKey`"
+    : 'call this tool again with the same files';
+const apiBody = (err) => err.response.data ? ` (${err.response.data.slice(0, 300)})` : '';
+/** The bundle-upload-url route's errors, as the agent should act on them. */
+export function describeBundleUploadUrlError(err) {
+    if (!(err instanceof WixFetchError)) {
+        return err instanceof Error ? err.message : String(err);
+    }
+    const body = apiBody(err);
+    switch (err.status) {
+        case 400:
+            return `The upload URL was refused: \`size\` is the build zip's length in bytes, an integer from 1 to ${MAX_BUNDLE_BYTES} (100 MB). A larger build: leave out what the site does not serve (source maps, unused assets).${body}`;
+        case 429:
+            return `Too many unreleased uploads are waiting for this site: release one with its \`uploadKey\`, or wait for a running release to finish, then ask again.${body}`;
+        default:
+            return err.message;
+    }
+}
+/**
+ * The site token, repeated in the release body: a build whose server code is over the
+ * service's gRPC limit is deployed over REST as the caller, the way the CLI deploys, and
+ * the gateway does not hand the Authorization header on to the service.
+ */
+function deployAuthorization(siteHeaders) {
+    const authorization = siteHeaders.Authorization ?? siteHeaders.authorization;
+    return authorization ? { deployAuthorization: authorization } : {};
+}
+/** The deployment label the service keeps is 200 characters; longer notes are cut, not refused. */
+export const RELEASE_NOTES_MAX_CHARS = 200;
+export function releaseNotesForService(notes) {
+    // Code points, not UTF-16 units, so an emoji at the boundary stays whole.
+    const chars = [...notes.replace(/\s+/g, ' ').trim()];
+    return chars.length <= RELEASE_NOTES_MAX_CHARS
+        ? chars.join('')
+        : `${chars
+            .slice(0, RELEASE_NOTES_MAX_CHARS - 1)
+            .join('')
+            .trimEnd()}…`;
+}
+/** The release-bundle route's errors, as the agent should act on them. */
+export function describeBundleReleaseError(err, uploadKey, retry = 'prepare') {
+    if (!(err instanceof WixFetchError)) {
+        return err instanceof Error ? err.message : String(err);
+    }
+    const body = apiBody(err);
+    const code = err.response.data ?? '';
+    switch (err.status) {
+        case 404:
+            return `Nothing uploaded for uploadKey ${uploadKey}: the build zip was not PUT to its URL, or the URL expired. To try again, ${startOver(retry)}.${body}`;
+        case 409:
+            return `The project's source repository moved since the upload URLs were made; nothing was released. ${retry === 'prepare' ? "Call with `prepare: true` and the zip's `size` again, re-upload the source zip to the new URL, and release with the new `uploadKey`, `sourceUploadId` and `expectedHeadRevisionId`." : 'Download the project again from the repository, carry your change over, and upload with `expectedHeadRevisionId` set to the revision you downloaded.'}${body}`;
+        case 403:
+            return `Wix refused to deploy this build onto the site's project; nothing was released, and the same call will be refused again. Do not call \`prepare\` again. Tell the user the release is blocked on Wix's side and give them the request id from the error.${body}`;
+        case 413:
+        case 428:
+            return `The build's server code is larger than the release can carry from here; nothing was released. Do not call \`prepare\` again. Tell the user the release is blocked on Wix's side and give them the request id from the error.${body}`;
+        case 400:
+            if (code.includes('EXPECTED_HEAD_REQUIRED')) {
+                return `The site's repository already holds work, and the source replaces only what you started from; nothing was released. ${retry === 'prepare' ? "Call with `prepare: true` and the zip's `size` again and pass the `headRevisionId` it returns as `expectedHeadRevisionId` (with its new `uploadKey` and `sourceUploadId`)." : 'Call again with `expectedHeadRevisionId`: the revision you downloaded the project at, so the source replaces only that. To replace the repository with this upload on purpose, pass its current head.'}${body}`;
+            }
+            if (code.includes('BUNDLE_TOO_LARGE')) {
+                return `The build zip is over ${MAX_BUNDLE_BYTES} bytes (100 MB): leave out what the site does not serve (source maps, unused assets), then ${startOver(retry)}.${body}`;
+            }
+            if (code.includes('INVALID_RELEASE')) {
+                return `The release was refused by Wix's deployment service; nothing was released. The staged upload is kept: call again with the same \`uploadKey\` and the field the message names fixed (release notes are cut to ${RELEASE_NOTES_MAX_CHARS} characters here).${body}`;
+            }
+            if (code.includes('INVALID_UPLOAD_KEY')) {
+                return `\`uploadKey\` is the lowercase UUID the \`prepare\` call returned; pass it as it came.${body}`;
+            }
+            return `The uploaded zip was not accepted. Zip \`dist/\` and \`.wix/build-metadata.json\` from the project root after \`astro build\` with the Wix hosting adapter, then ${startOver(retry)}. A static site goes in \`files\` or \`attachments\` instead, or is dropped as the StartDeployWebsite recipe shows.${body}`;
+        default:
+            if (err.status >= 500) {
+                const what = err.status === 503
+                    ? 'The release could not hold its upload'
+                    : `Wix's release step failed on its side (HTTP ${err.status})`;
+                // Both forms retry the staged upload itself: the two-call form with its uploadKey, the
+                // one-call form by switching to that key instead of sending the files again, which would
+                // stage another upload. One retry, then the user hears the request id.
+                return `${what}; nothing was released. The staged upload is kept under uploadKey ${uploadKey}, so do not call \`prepare\` again and do not send the files again: every upload staged and not released counts against the site, which refuses new ones after a few. Retry once, after a minute, by calling with \`uploadKey: "${uploadKey}"\`${retry === 'resend' ? ' (plus the `expectedHeadRevisionId` and `releaseNotes` you passed, if any; the source is stored with the next release)' : ' and the same ids and `releaseNotes`'}. If that fails too, stop and tell the user the release is blocked on Wix's side, with the request id from the error.${body}`;
+            }
+            return err.message;
+    }
+}
+/** The inputs of the two-call form against each other and against the one-call form. */
+function validateBundleArgs(a) {
+    const hasContent = !!a.files?.trim() || !!(a.attachments && a.attachments.length);
+    if (a.prepare) {
+        if (hasContent || a.uploadKey || a.sourceUploadId) {
+            return '`prepare: true` goes with `siteId` and `size`: no `files`, `attachments`, `uploadKey` or `sourceUploadId` on that call. Example: {siteId, prepare: true, size}, then {siteId, uploadKey, sourceUploadId?, expectedHeadRevisionId?, releaseNotes?}.';
+        }
+        if (a.size === undefined) {
+            return "`prepare: true` needs `size`: zip the build first and pass the zip's length in bytes (`wc -c < build.zip`).";
+        }
+        if (!Number.isInteger(a.size) || a.size < 1 || a.size > MAX_BUNDLE_BYTES) {
+            return `\`size\` is the build zip's length in bytes, an integer from 1 to ${MAX_BUNDLE_BYTES} (100 MB); got ${a.size}.`;
+        }
+        return null;
+    }
+    if (a.size !== undefined) {
+        return '`size` goes only with `prepare: true`: it is the length of the build zip that call makes an upload URL for.';
+    }
+    if (a.uploadKey) {
+        if (hasContent) {
+            return '`uploadKey` releases a build zip already uploaded to its URL: pass no `files` or `attachments` with it.';
+        }
+        return null;
+    }
+    if (a.sourceUploadId) {
+        return '`sourceUploadId` goes with the `uploadKey` the `prepare` call returned.';
+    }
+    if (a.expectedHeadRevisionId && !hasContent) {
+        return '`expectedHeadRevisionId` goes with `uploadKey`, or with `files`/`attachments` holding a build.';
+    }
+    return null;
+}
 async function readJson(res, what) {
     const text = await res.text();
     if (!res.ok)
@@ -67,6 +284,63 @@ async function readJson(res, what) {
         throw new Error(`${what} returned a non-JSON body: ${text.slice(0, 200)}`);
     }
 }
+/** A PUT to a presigned URL; content-length is left to fetch, which sends the body's own length. */
+async function putZip(fetchImpl, put, bytes, what) {
+    const headers = Object.fromEntries(Object.entries(put.headers ?? { 'content-type': 'application/zip' }).filter(([k]) => k.toLowerCase() !== 'content-length'));
+    const res = await fetchImpl(put.putUrl, {
+        method: 'PUT',
+        headers,
+        body: bytes
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`The ${what} upload was refused (${res.status}${text ? `: ${text.slice(0, 200)}` : ''}); call this tool again with the same files.`);
+    }
+}
+/**
+ * A build that came as files, released over the bundle routes: an upload URL for the
+ * site zip's size, the zip PUT there, the source zip PUT to the repository's URL when
+ * the service offered one and the upload holds source files, then the release with
+ * the ids. `onStaged` hears the uploadKey once the site zip is staged.
+ */
+export async function releaseBuildByUrl(o) {
+    const log = o.log ?? (() => { });
+    const headers = { ...o.siteHeaders, 'Content-Type': 'application/json' };
+    const urls = (await readJson(await o.fetchImpl(`${HEADLESS_BUSINESS}/${o.siteId}/bundle-upload-url`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ size: o.siteZip.byteLength })
+    }), 'bundle-upload-url'));
+    if (!urls.uploadKey || !urls.putUrl) {
+        throw new Error('bundle-upload-url returned no uploadKey or putUrl.');
+    }
+    await putZip(o.fetchImpl, urls, o.siteZip, 'site zip');
+    o.onStaged?.(urls.uploadKey);
+    log(`staged ${urls.uploadKey} (${o.siteZip.byteLength} bytes), source ${urls.source ? `offered, ${o.sourceFiles.length} file(s)` : 'not offered'}`);
+    const source = urls.source && o.sourceFiles.length > 0 ? urls.source : undefined;
+    if (source) {
+        await putZip(o.fetchImpl, source, zipStored(o.sourceFiles), 'source zip');
+    }
+    return (await readJson(await o.fetchImpl(`${HEADLESS_BUSINESS}/${o.siteId}/release-bundle`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+            uploadKey: urls.uploadKey,
+            ...deployAuthorization(o.siteHeaders),
+            ...(o.releaseNotes
+                ? { releaseNotes: releaseNotesForService(o.releaseNotes) }
+                : {}),
+            ...(source
+                ? {
+                    sourceUploadId: source.uploadId,
+                    ...(o.expectedHeadRevisionId
+                        ? { expectedHeadRevisionId: o.expectedHeadRevisionId }
+                        : {})
+                }
+                : {})
+        })
+    }), 'release-bundle'));
+}
 function errorResult(message) {
     return {
         isError: true,
@@ -97,6 +371,16 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
         }))
             .optional()
             .describe(d.attachments),
+        prepare: z.boolean().optional().describe(d.prepare),
+        size: z.number().int().optional().describe(d.size),
+        uploadKey: z.string().min(1).optional().describe(d.uploadKey),
+        sourceUploadId: z.string().min(1).optional().describe(d.sourceUploadId),
+        expectedHeadRevisionId: z
+            .string()
+            .min(1)
+            .optional()
+            .describe(d.expectedHeadRevisionId),
+        releaseNotes: z.string().optional().describe(d.releaseNotes),
         siteId: z
             .string()
             .uuid('siteId must be a Wix metaSiteId (UUID)')
@@ -110,25 +394,187 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
     // openWorldHint true: it fetches agent-supplied attachment URLs and publishes a
     // public website.
     { readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async (rawArgs, extra) => {
-        const { files, attachments, siteId, calledStartDeployWebsite, agentIdentity, reason } = rawArgs;
-        logger.log(`[UploadHeadlessWebsiteFiles] siteId=${siteId} calledStartDeployWebsite=${calledStartDeployWebsite} agent="${agentIdentity}" files=${files?.length ?? 0} chars attachments=${attachments?.length ?? 0} reason="${reason}"`);
+        const { files, attachments, prepare, size, uploadKey, sourceUploadId, expectedHeadRevisionId, releaseNotes, siteId, calledStartDeployWebsite, agentIdentity, reason } = rawArgs;
+        const phase = prepare
+            ? 'prepare'
+            : uploadKey
+                ? 'release-bundle'
+                : 'files';
+        logger.log(`[UploadHeadlessWebsiteFiles] siteId=${siteId} phase=${phase} calledStartDeployWebsite=${calledStartDeployWebsite} agent="${redactPersonalData(agentIdentity)}" files=${files?.length ?? 0} chars attachments=${attachments?.length ?? 0} reason="${redactPersonalData(reason)}"`);
+        const invalid = validateBundleArgs(rawArgs);
+        if (invalid)
+            return errorResult(invalid);
+        if (prepare || uploadKey) {
+            // The two-call form: both routes take the site token (outside the try so
+            // UnauthorizedError reaches the wrapper).
+            const siteHeaders = await authStrategy.getSiteAuthHeaders(siteId);
+            const headers = {
+                ...siteHeaders,
+                'Content-Type': 'application/json'
+            };
+            try {
+                extra?.setToolBiParams?.({ siteId });
+                if (prepare) {
+                    const urls = (await readJson(await fetchImpl(`${HEADLESS_BUSINESS}/${siteId}/bundle-upload-url`, {
+                        method: 'POST',
+                        headers,
+                        body: JSON.stringify({ size })
+                    }), 'bundle-upload-url'));
+                    if (!urls.uploadKey || !urls.putUrl) {
+                        throw new Error('bundle-upload-url returned no uploadKey or putUrl.');
+                    }
+                    extra?.setToolBiParams?.({
+                        siteId,
+                        upload: { path: 'prepare', sourceOffered: Boolean(urls.source) }
+                    });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: formatPrepareResult(siteId, urls, size, {
+                                    expectedHeadRevisionId,
+                                    releaseNotes
+                                })
+                            }
+                        ]
+                    };
+                }
+                const released = (await readJson(await fetchImpl(`${HEADLESS_BUSINESS}/${siteId}/release-bundle`, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({
+                        uploadKey,
+                        ...deployAuthorization(siteHeaders),
+                        ...(sourceUploadId ? { sourceUploadId } : {}),
+                        ...(expectedHeadRevisionId ? { expectedHeadRevisionId } : {}),
+                        ...(releaseNotes
+                            ? { releaseNotes: releaseNotesForService(releaseNotes) }
+                            : {})
+                    })
+                }), 'release-bundle'));
+                extra?.setToolBiParams?.({
+                    siteId,
+                    upload: {
+                        path: 'release-bundle',
+                        sourceStored: Boolean(released.revision?.id)
+                    }
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: formatBundleReleaseResult(siteId, released)
+                        }
+                    ]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.log(`[UploadHeadlessWebsiteFiles] ${phase} error: ${message}`);
+                rethrowIfUnauthorized(err);
+                await authStrategy.enforceValidWixToken?.(err);
+                return errorResult(uploadKey
+                    ? describeBundleReleaseError(err, uploadKey)
+                    : describeBundleUploadUrlError(err));
+            }
+        }
         if (!files?.trim() && !(attachments && attachments.length)) {
-            return errorResult('Nothing to publish: pass the site in `files` (text bundle) or `attachments` (files from this chat or your sandbox).');
+            return errorResult('Nothing to publish: pass the site in `files` (text bundle) or `attachments` (files from this chat or your sandbox), or, for a Wix Astro build from a shell that reaches the internet, zip it and call with `prepare: true` and its `size`.');
         }
-        // 1. Gather bytes: bundle + resolved attachments. All agent-facing errors.
-        let siteFiles;
+        // 1. Gather bytes: bundle + resolved attachments, zips unpacked. A Wix Astro build
+        //    among them is released (below); anything else is a static site and is dropped.
+        //    All agent-facing errors.
+        let siteFiles = [];
+        let uploaded = [];
+        let given = [];
+        let build = null;
         try {
             const fromAttachments = (await resolveAttachments(attachments, fetchImpl)).map((a) => ({ path: a.path, bytes: base64ToBytes(a.content) }));
-            siteFiles = await normalizeSiteFiles([
-                ...parseFileBundle(files),
-                ...fromAttachments
-            ]);
+            given = [...parseFileBundle(files), ...fromAttachments];
+            uploaded = await expandSiteFiles(given);
+            build = findHeadlessBuild(uploaded);
+            if (!build)
+                siteFiles = staticSiteFiles(uploaded);
         }
         catch (e) {
             if (e instanceof AttachmentError || e instanceof Error)
                 return errorResult(e.message);
             throw e;
         }
+        if (!build && expectedHeadRevisionId) {
+            return errorResult("`expectedHeadRevisionId` applies to a Wix Astro build, whose source is stored in the site's repository; these files are a static site, which has none. Call again without it.");
+        }
+        if (build) {
+            // 2. Site auth (outside the try so UnauthorizedError reaches the wrapper).
+            const siteHeaders = await authStrategy.getSiteAuthHeaders(siteId);
+            let stagedKey;
+            try {
+                extra?.setToolBiParams?.({ siteId });
+                // 3. The bundle routes, as the two-call form runs them, from here. The hosting
+                //    refuses an empty static file, so a build with one is zipped again without it.
+                const sourceFiles = buildSourceFiles(uploaded, build);
+                const statics = withoutEmptyStatics(uploaded, build);
+                const released = await releaseBuildByUrl({
+                    siteId,
+                    // One zip as given goes as is; anything else is zipped from the expanded files.
+                    siteZip: given.length === 1 &&
+                        isZip(given[0]) &&
+                        statics.dropped.length === 0
+                        ? given[0].bytes
+                        : zipStored(statics.files),
+                    sourceFiles,
+                    expectedHeadRevisionId,
+                    releaseNotes,
+                    siteHeaders,
+                    fetchImpl,
+                    onStaged: (key) => {
+                        stagedKey = key;
+                    },
+                    log: (line) => logger.log(`[UploadHeadlessWebsiteFiles] release ${line}`)
+                });
+                const sourceStored = Boolean(released.revision?.id);
+                extra?.setToolBiParams?.({
+                    siteId,
+                    upload: {
+                        path: 'build',
+                        sourceStored,
+                        sourceFiles: sourceFiles.length,
+                        emptyStaticsDropped: statics.dropped.length
+                    }
+                });
+                const notes = [
+                    ...(statics.dropped.length
+                        ? [
+                            `Left out, empty: ${statics.dropped.slice(0, 20).join(', ')} (the hosting serves no file of size 0).`
+                        ]
+                        : []),
+                    ...(sourceStored
+                        ? []
+                        : [
+                            sourceFiles.length
+                                ? "The project's source was not stored: the site's repository took none this time."
+                                : "The project's source was not stored: the upload held only the build. A later chat can continue this site only from its source; next time zip the whole project from its root, leaving out node_modules, .env files and the caches."
+                        ])
+                ];
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: formatBundleReleaseResult(siteId, released, notes)
+                        }
+                    ]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.log(`[UploadHeadlessWebsiteFiles] release error: ${message}`);
+                rethrowIfUnauthorized(err);
+                await authStrategy.enforceValidWixToken?.(err);
+                return errorResult(stagedKey
+                    ? describeBundleReleaseError(err, stagedKey, 'resend')
+                    : describeBundleUploadUrlError(err));
+            }
+        }
         // 2. Account auth (outside the try so UnauthorizedError reaches the wrapper).
         const authHeaders = await authStrategy.getAccountAuthHeaders();
         try {
@@ -140,6 +586,10 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
                 headers: { ...authHeaders }, // fetch sets the multipart boundary itself
                 body: buildFormData(siteFiles)
             }), 'drop');
+            extra?.setToolBiParams?.({
+                siteId: metaSiteId,
+                upload: { path: 'drop', files: siteFiles.length }
+            });
             return {
                 content: [
                     {
@@ -149,7 +599,10 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
                             siteUrl: dropped.siteUrl,
                             uploadId: dropped.uploadId,
                             files: siteFiles.map((f) => f.path)
-                        })
+                        }) +
+                            (releaseNotes
+                                ? '\n\nRelease notes are kept for a Wix Astro build only; a static drop has none, so yours were not stored.'
+                                : '')
                     }
                 ]
             };

package/build/dts/api-call/upload-image-tool.d.ts

@@ -5,5 +5,7 @@ export declare const UPLOAD_IMAGE_TOOL_NAME = "UploadImageToWixSite";
 export declare function addUploadImageTool(server: WixMcpServer, strategy: McpAuthenticationStrategy, options?: {
     description?: string;
     hints?: ToolHintsConfig;
+    /** Set when the session also has the image picker (Claude clients). */
+    imagePickerToolName?: string;
 }): void;
 //# sourceMappingURL=upload-image-tool.d.ts.map

package/build/dts/api-call/upload-image-tool.js

@@ -51,7 +51,7 @@ function errorResponse(text) {
 // ---------------------------------------------------------------------------
 // Upload flows
 // ---------------------------------------------------------------------------
-async function uploadFromUrl(item, authHeaders, displayName) {
+async function uploadFromUrl(item, authHeaders, displayName, imagePickerToolName) {
     if (!item.download_url) {
         return {
             success: false,
@@ -61,7 +61,7 @@ async function uploadFromUrl(item, authHeaders, displayName) {
     if (!/^https?:\/\//i.test(item.download_url)) {
         return {
             success: false,
-            error: `download_url must be a publicly accessible http(s) URL, not a local or sandbox file path (got: "${item.download_url}"). For a user-attached file, pass the file so the platform resolves it to a real download_url; if you only have the raw bytes, use imageBase64 instead.`
+            error: `This server can't read files on your machine or sandbox (got: "${item.download_url}"). Send this image as imageBase64 (the whole file, one per call) or as a public URL in imageUrls${imagePickerToolName ? `, or call ${imagePickerToolName} so the user picks it` : ''}.`
         };
     }
     try {
@@ -165,7 +165,11 @@ function formatBatchResults(results) {
 // Tool registration
 // ---------------------------------------------------------------------------
 export function addUploadImageTool(server, strategy, options) {
-    const description = options?.description ?? defaultToolDescriptions.UploadImageToWixSite;
+    const imagePickerToolName = options?.imagePickerToolName;
+    const baseDescription = options?.description || defaultToolDescriptions.UploadImageToWixSite;
+    const description = imagePickerToolName
+        ? `${baseDescription}\nIf you can't deliver the image any of these ways, call ${imagePickerToolName} so the user picks it.`
+        : baseDescription;
     const hints = {
         readOnlyHint: options?.hints?.readOnlyHint ?? false,
         destructiveHint: options?.hints?.destructiveHint ?? false,
@@ -226,7 +230,7 @@ export function addUploadImageTool(server, strategy, options) {
         logger.log(`[WixMCP] Uploading ${total} image(s) to Wix site: ${siteId}`);
         try {
             const authHeaders = await strategy.getSiteAuthHeaders(siteId);
-            const urlResults = await Promise.all(urlItems.map((item) => uploadFromUrl(item, authHeaders, displayName)));
+            const urlResults = await Promise.all(urlItems.map((item) => uploadFromUrl(item, authHeaders, displayName, imagePickerToolName)));
             let base64Result = null;
             if (imageBase64) {
                 const result = await uploadFromBase64(imageBase64, mimeType, authHeaders, displayName);

package/build/dts/bin.d.ts

@@ -1,5 +1,5 @@
 import './infra/sentry.js';
-declare const PUBLIC_TOOLS: readonly ["WDS", "REST", "SDK", "BUILD_APPS", "WIX_HEADLESS", "VELO", "BUSINESS_SOLUTIONS", "CLI", "OVERVIEW"];
+declare const PUBLIC_TOOLS: readonly ["WDS", "REST", "SDK", "BUILD_APPS", "WIX_HEADLESS", "VELO", "BUSINESS_SOLUTIONS", "CLI", "OVERVIEW", "HELP_CENTER"];
 declare const EXPERIMENTAL_TOOLS: readonly ["WIX_API", "CLI_COMMAND", "GET_TO_KNOW_WIX", "CREATE_WIX_BUSINESS_GUIDE", "VELO_README", "WIX_API_THROUGH_FS", "GRAPHQL"];
 type Tool = (typeof PUBLIC_TOOLS)[number] | (typeof EXPERIMENTAL_TOOLS)[number];
 export declare const DEFAULT_TOOLS: Tool[];