@wix/mcp 1.0.94 → 1.0.95

package/build/dts/api-call/headless-release.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A Wix Astro build among the files UploadHeadlessWebsiteFiles received (the output
+ * of `astro build` with the Wix hosting adapter, zipped from the project root):
+ * recognised here, released by headless-business-setup's bundle routes (the tool
+ * PUTs the zip and calls `release-bundle`), not dropped as static files.
+ *
+ * The build is recognised by `.wix/build-metadata.json`, which the adapter writes
+ * beside `dist/`: it names the client folder (served as static files), the server
+ * folder (run on the hosting runtime) and the app manifest. The folder that holds
+ * `.wix/` is the project root; the project's other files there are its source.
+ *
+ * Runs in the MCP server (a Cloudflare Worker): no `node:` imports, only web APIs.
+ */
+import type { SiteFile } from './site-files.js';
+export declare const BUILD_METADATA_SUFFIX = ".wix/build-metadata.json";
+export interface BuildMetadata {
+    appManifestPath: string;
+    clientDir?: string;
+    serverDir?: string;
+    staticsUrlPlaceholder?: string;
+    serverUrlPlaceholder?: string;
+    generateAppDeploymentGroupId?: boolean;
+}
+export interface HeadlessBuild {
+    metadata: BuildMetadata;
+    /** The project root in the upload: `''`, or the one folder that wraps the project (`proj/`). */
+    root: string;
+    /** The manifest as the build wrote it (`{ appId, components }`). */
+    manifestText: string;
+    clientFiles: SiteFile[];
+    serverFiles: SiteFile[];
+    /** The client folder in the upload (`dist/client/`), when the metadata names one. */
+    clientDir?: string;
+}
+/**
+ * The upload without the build's empty static files: the hosting refuses a static file
+ * of size 0 (`size got 0, expected 1 or more`), and an empty file serves nothing.
+ */
+export declare function withoutEmptyStatics(files: SiteFile[], build: HeadlessBuild): {
+    files: SiteFile[];
+    dropped: string[];
+};
+/**
+ * Recognise a Wix Astro build among the uploaded files: the file set holds
+ * `.wix/build-metadata.json` (at the root, or under one folder that wraps the project).
+ * Returns null for a static site, so the caller drops it as before. Throws an agent-facing
+ * error for a build whose metadata or files are not usable.
+ */
+export declare function findHeadlessBuild(files: SiteFile[]): HeadlessBuild | null;
+/**
+ * The project's source among the uploaded files: every file under the build's
+ * project root outside `dist/`, `.wix/`, `.astro/`, `.agents/`, `node_modules/` and
+ * `.env*`, with paths relative to the root. Empty when only the build was uploaded.
+ */
+export declare function buildSourceFiles(files: SiteFile[], build: HeadlessBuild): SiteFile[];
+//# sourceMappingURL=headless-release.d.ts.map

package/build/dts/api-call/headless-release.js

@@ -0,0 +1,135 @@
+export const BUILD_METADATA_SUFFIX = '.wix/build-metadata.json';
+/**
+ * The upload without the build's empty static files: the hosting refuses a static file
+ * of size 0 (`size got 0, expected 1 or more`), and an empty file serves nothing.
+ */
+export function withoutEmptyStatics(files, build) {
+    const dir = build.clientDir;
+    if (dir === undefined)
+        return { files, dropped: [] };
+    const dropped = [];
+    const kept = files.filter((f) => {
+        const path = normalizePath(f.path);
+        if (f.bytes.byteLength === 0 && path.startsWith(dir)) {
+            dropped.push(path.slice(dir.length));
+            return false;
+        }
+        return true;
+    });
+    return { files: kept, dropped };
+}
+const normalizePath = (p) => p.replace(/\\/g, '/').replace(/^\.?\//, '');
+/**
+ * Recognise a Wix Astro build among the uploaded files: the file set holds
+ * `.wix/build-metadata.json` (at the root, or under one folder that wraps the project).
+ * Returns null for a static site, so the caller drops it as before. Throws an agent-facing
+ * error for a build whose metadata or files are not usable.
+ */
+export function findHeadlessBuild(files) {
+    const entries = new Map(files.map((f) => [normalizePath(f.path), f.bytes]));
+    const metadataEntry = [...entries.keys()].find((name) => name === BUILD_METADATA_SUFFIX ||
+        name.endsWith(`/${BUILD_METADATA_SUFFIX}`));
+    if (metadataEntry === undefined)
+        return null;
+    const zipRoot = metadataEntry.slice(0, metadataEntry.length - BUILD_METADATA_SUFFIX.length);
+    let metadata;
+    try {
+        metadata = JSON.parse(new TextDecoder().decode(entries.get(metadataEntry)));
+    }
+    catch {
+        throw new Error(`${BUILD_METADATA_SUFFIX} is not valid JSON.`);
+    }
+    if (typeof metadata.appManifestPath !== 'string') {
+        throw new Error(`${BUILD_METADATA_SUFFIX} has no appManifestPath; send the build as the Wix hosting adapter wrote it (.wix/ and dist/ zipped from the project root).`);
+    }
+    // The metadata holds the builder's absolute paths; the files in the zip are relative to the
+    // project root. The manifest is found by the longest tail of its path that exists, and the
+    // part of the path before that tail is the builder's project root.
+    const manifestPath = resolveZipPath(metadata.appManifestPath, zipRoot, entries);
+    if (manifestPath === undefined) {
+        throw new Error(`The build's app manifest (${metadata.appManifestPath}) is not in the upload; zip .wix/ and dist/ together from the project root after \`astro build\`.`);
+    }
+    const builderRoot = metadata.appManifestPath.slice(0, metadata.appManifestPath.length - (manifestPath.length - zipRoot.length));
+    const clientDir = metadata.clientDir === undefined
+        ? undefined
+        : toZipDir(metadata.clientDir, builderRoot, zipRoot);
+    const serverDir = metadata.serverDir === undefined
+        ? undefined
+        : toZipDir(metadata.serverDir, builderRoot, zipRoot);
+    const clientFiles = [];
+    const serverFiles = [];
+    for (const [name, bytes] of entries) {
+        if (name === manifestPath)
+            continue;
+        if (serverDir !== undefined && name.startsWith(serverDir)) {
+            serverFiles.push({ path: name.slice(serverDir.length), bytes });
+        }
+        else if (clientDir !== undefined && name.startsWith(clientDir)) {
+            clientFiles.push({ path: name.slice(clientDir.length), bytes });
+        }
+    }
+    if (clientFiles.length + serverFiles.length === 0) {
+        throw new Error('The build has no client or server output files; run `astro build` first and zip .wix/ and dist/ from the project root.');
+    }
+    if (serverFiles.length > 0 &&
+        !serverFiles.some((f) => f.path === 'entry.mjs')) {
+        throw new Error("The server build has no entry.mjs, which the Wix hosting adapter (@wix/astro-wix-hosting-adapter) writes into the server folder on every build. Build with the project's own `astro build` (the adapter in astro.config) and zip .wix/ and dist/ from the project root as the build left them.");
+    }
+    const manifestText = new TextDecoder().decode(entries.get(manifestPath));
+    return {
+        metadata,
+        root: zipRoot,
+        manifestText,
+        clientFiles,
+        serverFiles,
+        clientDir
+    };
+}
+// What the source zip leaves out, relative to the project root: the build output, the
+// adapter's and Astro's caches, the agent's own folder at the top; dependencies and
+// environment files at any depth.
+const NOT_SOURCE_TOP = new Set(['dist', '.wix', '.astro', '.agents']);
+const isSourcePath = (relative) => {
+    const segments = relative.split('/');
+    return (!NOT_SOURCE_TOP.has(segments[0]) &&
+        !segments.some((s) => s === 'node_modules' || s.startsWith('.env')));
+};
+/**
+ * The project's source among the uploaded files: every file under the build's
+ * project root outside `dist/`, `.wix/`, `.astro/`, `.agents/`, `node_modules/` and
+ * `.env*`, with paths relative to the root. Empty when only the build was uploaded.
+ */
+export function buildSourceFiles(files, build) {
+    return files.flatMap((f) => {
+        const path = normalizePath(f.path);
+        if (!path.startsWith(build.root))
+            return [];
+        const relative = path.slice(build.root.length);
+        return relative && isSourcePath(relative)
+            ? [{ path: relative, bytes: f.bytes }]
+            : [];
+    });
+}
+function resolveZipPath(builderPath, zipRoot, entries) {
+    const segments = normalizePath(builderPath)
+        .split('/')
+        .filter((s) => s.length > 0);
+    for (let k = 0; k < segments.length; k++) {
+        const candidate = zipRoot + segments.slice(k).join('/');
+        if (entries.has(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function toZipDir(builderDir, builderRoot, zipRoot) {
+    const normalized = normalizePath(builderDir);
+    const normalizedRoot = normalizePath(builderRoot);
+    const relative = builderDir.startsWith(builderRoot)
+        ? builderDir.slice(builderRoot.length)
+        : normalized.startsWith(normalizedRoot)
+            ? normalized.slice(normalizedRoot.length)
+            : normalized;
+    const dir = zipRoot + normalizePath(relative);
+    return dir.endsWith('/') ? dir : `${dir}/`;
+}
+//# sourceMappingURL=headless-release.js.map

package/build/dts/api-call/index.d.ts

@@ -6,5 +6,13 @@ export interface ToolHintsConfig {
     openWorldHint?: boolean;
 }
 export { addUploadImageTool } from './upload-image-tool.js';
-export declare function addApiCallTool(server: WixMcpServer, strategy: McpAuthenticationStrategy, allowedTools?: string[], disableTools?: string[], enableTools?: string[], toolDescriptions?: Record<string, string>, toolHints?: Record<string, ToolHintsConfig>, maxResponseSize?: number): void;
+export declare function addApiCallTool(server: WixMcpServer, strategy: McpAuthenticationStrategy, allowedTools?: string[], disableTools?: string[], enableTools?: string[], toolDescriptions?: Record<string, string>, toolHints?: Record<string, ToolHintsConfig>, maxResponseSize?: number, options?: {
+    imagePickerToolName?: string;
+    /**
+     * This server serves ExecuteWixAPI. Only then does CallWixSiteAPI tell the user to reconnect when
+     * the client lists no ExecuteWixAPI (an old or cached tool list); where it is off on purpose, the
+     * agent just uses CallWixSiteAPI.
+     */
+    executeWixAPIServed?: boolean;
+}): void;
 //# sourceMappingURL=index.d.ts.map

package/build/dts/api-call/index.js

@@ -5,8 +5,8 @@ import { handleWixAPIResponse } from '../tool-utils.js';
 import { rethrowIfUnauthorized } from '../auth/index.js';
 import { isApiUrlAllowed } from './validation.js';
 import { addUploadImageTool } from './upload-image-tool.js';
-import { defaultToolDescriptions } from '../config/default-config.js';
-import { desc } from '../config/param-descriptions.js';
+import { CALL_WIX_SITE_API_NO_EXECUTE_LINE, CALL_WIX_SITE_API_RECONNECT_LINE, defaultToolDescriptions } from '../config/default-config.js';
+import { desc, WHY_NOT_EXECUTE_NO_EXECUTE, WHY_NOT_EXECUTE_RECONNECT } from '../config/param-descriptions.js';
 import { MAX_ALLOWED_RESPONSE_CHARS } from '../infra/response-size-limits.js';
 export { addUploadImageTool } from './upload-image-tool.js';
 const DEFAULT_MAX_RESPONSE_SIZE = 50000; // ~50KB cap
@@ -56,7 +56,8 @@ function formatApiResponse(responseData, maxResponseSize = DEFAULT_MAX_RESPONSE_
     }
     return { text: responseText, isError: false, originalLength, returnedRows };
 }
-export function addApiCallTool(server, strategy, allowedTools = ['CallWixSiteAPI', 'ListWixSites', 'ManageWixSite'], disableTools = [], enableTools = [], toolDescriptions, toolHints, maxResponseSize) {
+export function addApiCallTool(server, strategy, allowedTools = ['CallWixSiteAPI', 'ListWixSites', 'ManageWixSite'], disableTools = [], enableTools = [], toolDescriptions, toolHints, maxResponseSize, options) {
+    const executeAdvice = (text, reconnect, plain) => options?.executeWixAPIServed ? text : text.replace(reconnect, plain);
     // Compute effective allowed tools: (default + enableTools) - disableTools
     const effectiveAllowedTools = [
         ...new Set([...allowedTools, ...enableTools])
@@ -71,7 +72,7 @@ export function addApiCallTool(server, strategy, allowedTools = ['CallWixSiteAPI
     const getDescription = (toolName, defaultDesc) => toolDescriptions?.[toolName] ?? defaultDesc;
     if (effectiveAllowedTools.includes('CallWixSiteAPI') &&
         !disableTools.includes('CallWixSiteAPI')) {
-        server.tool('CallWixSiteAPI', getDescription('CallWixSiteAPI', defaultToolDescriptions.CallWixSiteAPI), (() => {
+        server.tool('CallWixSiteAPI', executeAdvice(getDescription('CallWixSiteAPI', defaultToolDescriptions.CallWixSiteAPI), CALL_WIX_SITE_API_RECONNECT_LINE, CALL_WIX_SITE_API_NO_EXECUTE_LINE), (() => {
             const d = desc('CallWixSiteAPI');
             return {
                 siteId: z.string().describe(d.siteId),
@@ -82,6 +83,10 @@ export function addApiCallTool(server, strategy, allowedTools = ['CallWixSiteAPI
                     .optional()
                     .describe(d.body),
                 reason: z.string().describe(d.reason),
+                whyNotExecuteWixAPI: z
+                    .string()
+                    .optional()
+                    .describe(executeAdvice(d.whyNotExecuteWixAPI, WHY_NOT_EXECUTE_RECONNECT, WHY_NOT_EXECUTE_NO_EXECUTE)),
                 sourceDocUrl: z.string().describe(d.sourceDocUrl)
             };
         })(), 
@@ -91,8 +96,8 @@ export function addApiCallTool(server, strategy, allowedTools = ['CallWixSiteAPI
             readOnlyHint: false,
             destructiveHint: true,
             openWorldHint: true
-        }), async ({ url, body, method, siteId, reason, sourceDocUrl }, { httpClient, setToolBiParams }) => {
-            logger.log(`[CallWixSiteAPI] siteId=${siteId}, method=${method}, url=${url}, sourceDocUrl=${sourceDocUrl}, reason="${reason}", body=${JSON.stringify(body)}`);
+        }), async ({ url, body, method, siteId, reason, whyNotExecuteWixAPI, sourceDocUrl }, { httpClient, setToolBiParams }) => {
+            logger.log(`[CallWixSiteAPI] siteId=${siteId}, method=${method}, url=${url}, sourceDocUrl=${sourceDocUrl}, reason="${reason}", whyNotExecuteWixAPI="${whyNotExecuteWixAPI ?? ''}", body=${JSON.stringify(body)}`);
             const requestHeaders = {
                 // Ask the Wix API edge for JSON error bodies (it serves a branded HTML
                 // error page on 4xx otherwise); */* keeps non-JSON responses working.
@@ -328,7 +333,8 @@ export function addApiCallTool(server, strategy, allowedTools = ['CallWixSiteAPI
         !disableTools.includes('UploadImageToWixSite')) {
         addUploadImageTool(server, strategy, {
             description: getDescription('UploadImageToWixSite', ''),
-            hints: toolHints?.['UploadImageToWixSite']
+            hints: toolHints?.['UploadImageToWixSite'],
+            imagePickerToolName: options?.imagePickerToolName
         });
     }
 }

package/build/dts/api-call/site-files.d.ts

@@ -16,12 +16,26 @@ export declare function base64ToBytes(b64: string): Uint8Array;
 export declare function parseFileBundle(bundle: string | undefined): SiteFile[];
 /** Unzip (stored + deflate entries) into raw bytes. Validates the EOCD and the declared sizes. */
 export declare function unzip(z: Uint8Array): Promise<SiteFile[]>;
+export declare function crc32(bytes: Uint8Array): number;
+/** A zip of the files, every entry stored (no compression), names in UTF-8. No zip64: under 4 GB and 65,535 entries. */
+export declare function zipStored(files: SiteFile[]): Uint8Array;
 export declare const isZip: (f: SiteFile) => boolean;
+/**
+ * The file set as uploaded: zips unpacked, paths cleaned, junk dropped, within the file
+ * count and the byte budget for the whole upload. No site-shape rule yet: a Wix Astro
+ * build is told apart from a static site on this list.
+ */
+export declare function expandSiteFiles(input: SiteFile[]): Promise<SiteFile[]>;
 /**
  * Turn the raw inputs into the file set to drop: unpack zips, drop junk, strip a
  * single wrapping folder, require a root index.html. Throws an agent-facing error.
  */
 export declare function normalizeSiteFiles(input: SiteFile[]): Promise<SiteFile[]>;
+/**
+ * The static-site rules on a list `expandSiteFiles` already made (its zips are not
+ * unpacked again): strip a single wrapping folder, require a root index.html.
+ */
+export declare function staticSiteFiles(expanded: SiteFile[]): SiteFile[];
 export declare function guessContentType(path: string): string;
 /** The drop endpoint's body: one `files` part per file, the path as the filename. */
 export declare function buildFormData(files: SiteFile[]): FormData;

package/build/dts/api-call/site-files.js

@@ -58,7 +58,11 @@ export async function unzip(z) {
     let p = u32(end + 16);
     let total = 0;
     const decoder = new TextDecoder();
-    for (let i = 0, n = u16(end + 10); i < n; i++) {
+    const n = u16(end + 10);
+    if (n > MAX_SITE_FILES) {
+        throw new Error(`zip holds ${n} entries; a site upload is at most ${MAX_SITE_FILES} files`);
+    }
+    for (let i = 0; i < n; i++) {
         const path = decoder.decode(z.slice(p + 46, p + 46 + u16(p + 28)));
         const method = u16(p + 10);
         const size = u32(p + 24);
@@ -89,6 +93,77 @@ export async function unzip(z) {
     }
     return out;
 }
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+export function crc32(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++)
+        c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** A zip of the files, every entry stored (no compression), names in UTF-8. No zip64: under 4 GB and 65,535 entries. */
+export function zipStored(files) {
+    const encoder = new TextEncoder();
+    const entries = files.map((f) => ({
+        name: encoder.encode(f.path),
+        bytes: f.bytes,
+        crc: crc32(f.bytes)
+    }));
+    const localSize = entries.reduce((sum, e) => sum + 30 + e.name.length + e.bytes.length, 0);
+    const centralSize = entries.reduce((sum, e) => sum + 46 + e.name.length, 0);
+    const out = new Uint8Array(localSize + centralSize + 22);
+    const view = new DataView(out.buffer);
+    const UTF8_FLAG = 0x0800;
+    let p = 0;
+    const offsets = [];
+    for (const e of entries) {
+        offsets.push(p);
+        view.setUint32(p, 0x04034b50, true);
+        view.setUint16(p + 4, 20, true); // version needed
+        view.setUint16(p + 6, UTF8_FLAG, true);
+        view.setUint16(p + 8, 0, true); // stored
+        view.setUint32(p + 10, 0, true); // time, date
+        view.setUint32(p + 14, e.crc, true);
+        view.setUint32(p + 18, e.bytes.length, true);
+        view.setUint32(p + 22, e.bytes.length, true);
+        view.setUint16(p + 26, e.name.length, true);
+        view.setUint16(p + 28, 0, true);
+        out.set(e.name, p + 30);
+        out.set(e.bytes, p + 30 + e.name.length);
+        p += 30 + e.name.length + e.bytes.length;
+    }
+    const centralStart = p;
+    entries.forEach((e, i) => {
+        view.setUint32(p, 0x02014b50, true);
+        view.setUint16(p + 4, 20, true); // version made by
+        view.setUint16(p + 6, 20, true); // version needed
+        view.setUint16(p + 8, UTF8_FLAG, true);
+        view.setUint16(p + 10, 0, true);
+        view.setUint32(p + 12, 0, true);
+        view.setUint32(p + 16, e.crc, true);
+        view.setUint32(p + 20, e.bytes.length, true);
+        view.setUint32(p + 24, e.bytes.length, true);
+        view.setUint16(p + 28, e.name.length, true);
+        // extra, comment, disk, internal attrs, external attrs: zero
+        view.setUint32(p + 42, offsets[i], true);
+        out.set(e.name, p + 46);
+        p += 46 + e.name.length;
+    });
+    view.setUint32(p, 0x06054b50, true);
+    view.setUint16(p + 8, entries.length, true);
+    view.setUint16(p + 10, entries.length, true);
+    view.setUint32(p + 12, p - centralStart, true);
+    view.setUint32(p + 16, centralStart, true);
+    return out;
+}
 // A zip is recognised by its bytes (local-file-header or empty-archive signature), not its name:
 // an attachment can arrive without a file name, and a zip's path then carries no extension.
 export const isZip = (f) => (f.bytes.length >= 4 &&
@@ -99,18 +174,25 @@ export const isZip = (f) => (f.bytes.length >= 4 &&
     /\.zip$/i.test(f.path);
 const isRootIndex = (p) => /^index\.html?$/i.test(p);
 /**
- * Turn the raw inputs into the file set to drop: unpack zips, drop junk, strip a
- * single wrapping folder, require a root index.html. Throws an agent-facing error.
+ * The file set as uploaded: zips unpacked, paths cleaned, junk dropped, within the file
+ * count and the byte budget for the whole upload. No site-shape rule yet: a Wix Astro
+ * build is told apart from a static site on this list.
  */
-export async function normalizeSiteFiles(input) {
-    let list = [];
+export async function expandSiteFiles(input) {
+    const list = [];
+    let bytes = 0;
     for (const f of input) {
-        if (isZip(f))
-            list.push(...(await unzip(f.bytes)));
-        else
-            list.push(f);
+        const added = isZip(f) ? await unzip(f.bytes) : [f];
+        list.push(...added);
+        bytes += added.reduce((sum, a) => sum + a.bytes.byteLength, 0);
+        if (list.length > MAX_SITE_FILES) {
+            throw new Error(`Too many files (more than ${MAX_SITE_FILES}); a site upload is at most ${MAX_SITE_FILES}.`);
+        }
+        if (bytes > MAX_UNZIP_BYTES) {
+            throw new Error(`The upload expands past ${MAX_UNZIP_BYTES} bytes; send only the site's files.`);
+        }
     }
-    list = list
+    return list
         .map((f) => ({
         ...f,
         path: f.path.replace(/\\/g, '/').replace(/^\.?\//, '')
@@ -119,6 +201,20 @@ export async function normalizeSiteFiles(input) {
         !f.path.startsWith('__MACOSX/') &&
         !/(^|\/)\.DS_Store$/.test(f.path) &&
         !f.path.split('/').includes('..'));
+}
+/**
+ * Turn the raw inputs into the file set to drop: unpack zips, drop junk, strip a
+ * single wrapping folder, require a root index.html. Throws an agent-facing error.
+ */
+export async function normalizeSiteFiles(input) {
+    return staticSiteFiles(await expandSiteFiles(input));
+}
+/**
+ * The static-site rules on a list `expandSiteFiles` already made (its zips are not
+ * unpacked again): strip a single wrapping folder, require a root index.html.
+ */
+export function staticSiteFiles(expanded) {
+    let list = expanded;
     if (list.length === 0) {
         throw new Error('No files to upload: pass the site in `files` or `attachments`.');
     }

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

@@ -1,6 +1,9 @@
+import { type SiteFile } from './site-files.js';
 import { WixMcpServer } from '../wix-mcp-server.js';
 import { type McpAuthenticationStrategy } from '../auth/index.js';
 export declare const UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME = "UploadHeadlessWebsiteFiles";
+/** The largest site zip `bundle-upload-url` presigns (headless-business-setup's MAX_BUNDLE_BYTES). */
+export declare const MAX_BUNDLE_BYTES: number;
 /**
  * Attribution the drop endpoint stamps on its upload BI event (`source` from
  * `campaign`, `agent` from `agent`, both ≤ 64 chars) — the same parser as the
@@ -17,12 +20,18 @@ export interface UploadHeadlessWebsiteFilesOptions {
     clientName?: string;
 }
 export declare const UPLOAD_HEADLESS_WEBSITE_FILES_PARAM_DESCRIPTIONS: {
-    readonly 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.";
-    readonly 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.";
-    readonly 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.";
+    readonly 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.";
+    readonly attachments: string;
+    readonly 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.";
+    readonly size: "Phase one, with `prepare: true` only, and required there: the build zip's length in bytes (`wc -c < build.zip`), 1 to 104857600 (100 MB). The upload URL takes a body of exactly this length; a zip changed after the prepare needs a new prepare.";
+    readonly 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`.";
+    readonly 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.";
+    readonly 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.";
+    readonly 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.";
+    readonly 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.";
     readonly calledStartDeployWebsite: "Whether you called StartDeployWebsite earlier in this conversation and are following the recipe it returned. Answer truthfully; it is recorded, not checked.";
-    readonly agentIdentity: "Which agent or product you are and the harness you run in.";
-    readonly reason: "One sentence: the user request that led here and what is being published.";
+    readonly agentIdentity: "Which agent or product you are, which model if you know it, and the harness you run in. No personal data: no names, emails, phones, passwords, keys or local paths.";
+    readonly reason: "One sentence: the user request that led here and what is being published. No personal data: no names, emails, phones, passwords, keys or local paths.";
 };
 export interface DropResult {
     metaSiteId: string;
@@ -31,5 +40,79 @@ export interface DropResult {
     files: string[];
 }
 export declare function formatDropResult(r: DropResult): string;
+/** One presigned PUT: where the zip goes and the headers the storage requires on it. */
+interface PresignedPut {
+    putUrl: string;
+    headers?: Record<string, string>;
+    expiresAt?: string;
+}
+/** `POST /{siteId}/bundle-upload-url`: the site half, plus the Code Store half when the site has a source repository. */
+export interface BundleUploadUrls extends PresignedPut {
+    uploadKey: string;
+    source?: PresignedPut & {
+        uploadId: string;
+        headRevisionId?: string;
+    };
+}
+/** `POST /{siteId}/release-bundle`. */
+/**
+ * What the tool BI event records about an upload, beside the result text: the path it
+ * took (`drop` static pages, `build` an attached Astro build over the bundle routes,
+ * `prepare` and `release-bundle` the two calls) and whether the source was stored.
+ */
+export interface UploadBiFields {
+    path: 'drop' | 'build' | 'prepare' | 'release-bundle';
+    sourceOffered?: boolean;
+    sourceStored?: boolean;
+    sourceFiles?: number;
+    emptyStaticsDropped?: number;
+    files?: number;
+}
+export interface BundleReleaseResult {
+    deploymentId?: string;
+    siteUrl?: string;
+    revision?: {
+        id?: string;
+    };
+}
+/** The prepare reply: what the agent runs, verbatim, and the exact second call. */
+export declare function formatPrepareResult(siteId: string, urls: BundleUploadUrls, size?: number, given?: {
+    expectedHeadRevisionId?: string;
+    releaseNotes?: string;
+}): string;
+/** The release-bundle reply, for both the two-call form and a build uploaded as files. */
+export declare function formatBundleReleaseResult(siteId: string, r: BundleReleaseResult, notes?: string[]): string;
+/**
+ * How the agent starts over: in the two-call form a new `prepare`, after a build
+ * uploaded as files the same call again (the tool asks for new URLs itself).
+ */
+export type BundleRetry = 'prepare' | 'resend';
+/** The bundle-upload-url route's errors, as the agent should act on them. */
+export declare function describeBundleUploadUrlError(err: unknown): string;
+/** The deployment label the service keeps is 200 characters; longer notes are cut, not refused. */
+export declare const RELEASE_NOTES_MAX_CHARS = 200;
+export declare function releaseNotesForService(notes: string): string;
+/** The release-bundle route's errors, as the agent should act on them. */
+export declare function describeBundleReleaseError(err: unknown, uploadKey: string, retry?: BundleRetry): string;
+/**
+ * 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 declare function releaseBuildByUrl(o: {
+    siteId: string;
+    siteZip: Uint8Array;
+    sourceFiles: SiteFile[];
+    siteHeaders: Record<string, string>;
+    fetchImpl: typeof fetch;
+    /** The revision the agent's project started from; never the head read here, which would replace work committed since. */
+    expectedHeadRevisionId?: string;
+    /** One line kept with the deployment; cut to the service's limit. */
+    releaseNotes?: string;
+    onStaged?: (uploadKey: string) => void;
+    log?: (line: string) => void;
+}): Promise<BundleReleaseResult>;
 export declare function addUploadHeadlessWebsiteFilesTool(server: WixMcpServer, options: UploadHeadlessWebsiteFilesOptions): void;
+export {};
 //# sourceMappingURL=upload-headless-website-files.d.ts.map