mcp-stitch 0.1.2 → 0.1.4

package/dist/tools/stitchExport.js

@@ -1,5 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { lstat, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
 import { getStitchConfig } from "../config/stitch.js";
@@ -23,6 +23,9 @@ const ARTIFACT_FILES = [
     "manifest.json",
 ];
 const DEFAULT_ARTIFACT_ROOT = ".artifacts/stitch";
+const DEFAULT_MAX_LINKED_ASSETS = 50;
+const DEFAULT_MAX_DOWNLOAD_BYTES = 25 * 1024 * 1024;
+const VERSION_DIR_PATTERN = /^v(\d{3})$/;
 function isSafeRelativePathInput(value) {
     const trimmed = value.trim();
     if (!trimmed)
@@ -46,6 +49,206 @@ function nowStamp() {
 function toPrettyJson(value) {
     return JSON.stringify(value, null, 2);
 }
+function safeUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "https:")
+            return null;
+        const hostname = parsed.hostname.toLowerCase();
+        if (hostname === "localhost" ||
+            hostname.endsWith(".localhost") ||
+            hostname.endsWith(".local") ||
+            hostname === "0.0.0.0" ||
+            hostname === "127.0.0.1" ||
+            hostname === "::1" ||
+            hostname.startsWith("10.") ||
+            hostname.startsWith("192.168.") ||
+            /^172\.(1[6-9]|2\d|3[0-1])\./.test(hostname)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function extensionFromContentType(contentType) {
+    const normalized = contentType?.split(";")[0]?.trim().toLowerCase();
+    switch (normalized) {
+        case "text/html":
+            return ".html";
+        case "image/jpeg":
+            return ".jpg";
+        case "image/png":
+            return ".png";
+        case "image/webp":
+            return ".webp";
+        case "image/gif":
+            return ".gif";
+        case "image/svg+xml":
+            return ".svg";
+        case "image/avif":
+            return ".avif";
+        case "font/woff":
+            return ".woff";
+        case "font/woff2":
+            return ".woff2";
+        case "text/css":
+            return ".css";
+        case "application/javascript":
+        case "text/javascript":
+            return ".js";
+        default:
+            return ".bin";
+    }
+}
+function extensionFromUrl(url) {
+    const extension = path.extname(url.pathname).toLowerCase();
+    return /^[a-z0-9.]{2,12}$/.test(extension) ? extension : "";
+}
+function fileNameWithExtension(stem, url, contentType) {
+    const extension = extensionFromUrl(url) || extensionFromContentType(contentType);
+    return `${stem}${extension}`;
+}
+function assetFileNameStem(prefix, index) {
+    return `${prefix}-${String(index).padStart(3, "0")}`;
+}
+function dedupeUrls(urls) {
+    const seen = new Set();
+    const result = [];
+    for (const url of urls) {
+        if (seen.has(url))
+            continue;
+        seen.add(url);
+        result.push(url);
+    }
+    return result;
+}
+function extractLinkedAssetUrls(html, baseUrl) {
+    const candidates = [];
+    const attrPattern = /\b(?:src|href)=["']([^"']+)["']/gi;
+    const cssUrlPattern = /url\(["']?([^"')]+)["']?\)/gi;
+    for (const match of html.matchAll(attrPattern)) {
+        if (match[1])
+            candidates.push(match[1]);
+    }
+    for (const match of html.matchAll(cssUrlPattern)) {
+        if (match[1])
+            candidates.push(match[1]);
+    }
+    const urls = candidates
+        .map((candidate) => {
+        try {
+            return new URL(candidate, baseUrl).toString();
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((url) => Boolean(url))
+        .filter((url) => safeUrl(url) !== null);
+    return dedupeUrls(urls);
+}
+function isLikelyLinkedAsset(contentType) {
+    const normalized = contentType?.split(";")[0]?.trim().toLowerCase();
+    return Boolean(normalized &&
+        (normalized.startsWith("image/") ||
+            normalized.startsWith("font/") ||
+            normalized === "text/css" ||
+            normalized === "application/javascript" ||
+            normalized === "text/javascript"));
+}
+async function downloadUrl(options) {
+    const parsed = safeUrl(options.url);
+    if (!parsed) {
+        return {
+            asset: {
+                kind: options.kind,
+                sourceUrl: options.url,
+                status: "skipped",
+                reason: "Only safe https URLs are downloaded.",
+            },
+        };
+    }
+    try {
+        const response = await fetch(parsed);
+        const contentType = response.headers.get("content-type") ?? undefined;
+        const contentLength = response.headers.get("content-length");
+        if (!response.ok) {
+            return {
+                asset: {
+                    kind: options.kind,
+                    sourceUrl: options.url,
+                    contentType,
+                    status: "failed",
+                    reason: `HTTP ${response.status}`,
+                },
+            };
+        }
+        if (options.requireLinkedAssetType && !isLikelyLinkedAsset(contentType)) {
+            return {
+                asset: {
+                    kind: options.kind,
+                    sourceUrl: options.url,
+                    contentType,
+                    status: "skipped",
+                    reason: "Response content type is not a linked asset type.",
+                },
+            };
+        }
+        if (contentLength && Number(contentLength) > options.maxBytes) {
+            return {
+                asset: {
+                    kind: options.kind,
+                    sourceUrl: options.url,
+                    contentType,
+                    status: "skipped",
+                    reason: `Content length exceeds ${options.maxBytes} bytes.`,
+                },
+            };
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        if (arrayBuffer.byteLength > options.maxBytes) {
+            return {
+                asset: {
+                    kind: options.kind,
+                    sourceUrl: options.url,
+                    contentType,
+                    bytes: arrayBuffer.byteLength,
+                    status: "skipped",
+                    reason: `Downloaded content exceeds ${options.maxBytes} bytes.`,
+                },
+            };
+        }
+        const buffer = Buffer.from(arrayBuffer);
+        const fileName = options.forcedFileName ?? fileNameWithExtension(options.fileNameStem, parsed, contentType);
+        const relativePath = path.join(options.relativeDir, fileName);
+        const outputPath = await prepareSafeOutputPath(options.baseRoot, relativePath);
+        await writeFile(outputPath, buffer);
+        return {
+            asset: {
+                kind: options.kind,
+                sourceUrl: options.url,
+                path: outputPath,
+                relativePath,
+                contentType,
+                bytes: buffer.byteLength,
+                status: "saved",
+            },
+            text: contentType?.startsWith("text/") ? buffer.toString("utf8") : undefined,
+        };
+    }
+    catch (error) {
+        return {
+            asset: {
+                kind: options.kind,
+                sourceUrl: options.url,
+                status: "failed",
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+}
 function defaultArtifactName(screenId) {
     const suffix = screenId ? sanitizeFileName(screenId) : "screen";
     return `stitch-${suffix}-${nowStamp()}`;
@@ -82,6 +285,26 @@ async function getBaseRoot(configOutputDir) {
     }
     return { ok: true, baseRoot: path.resolve(configOutputDir), source: "STITCH_OUTPUT_DIR" };
 }
+async function nextVersionedArtifactPath(options) {
+    const basePath = await prepareSafeOutputPath(options.baseRoot, path.join(options.artifactPath, ".version-probe"));
+    const versionBaseDir = path.dirname(basePath);
+    await mkdir(versionBaseDir, { recursive: true });
+    let maxVersion = 0;
+    const entries = await readdir(versionBaseDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const match = entry.name.match(VERSION_DIR_PATTERN);
+        if (!match?.[1])
+            continue;
+        maxVersion = Math.max(maxVersion, Number(match[1]));
+    }
+    const version = `v${String(maxVersion + 1).padStart(3, "0")}`;
+    return {
+        artifactPath: path.join(options.artifactPath, version),
+        version,
+    };
+}
 function defaultArtifactPath(payload, screenId) {
     const screen = getScreen(payload);
     const title = getString(screen, "title");
@@ -672,6 +895,14 @@ function createManifest(options) {
             mode: options.outputMode,
         },
         paths: options.paths,
+        downloadedAssets: options.downloadedAssets,
+        version: options.versionInfo.enabled
+            ? {
+                enabled: true,
+                baseArtifactPath: options.versionInfo.baseArtifactPath,
+                version: options.versionInfo.version,
+            }
+            : { enabled: false },
     };
 }
 export function registerStitchExportTool(server) {
@@ -708,8 +939,47 @@ export function registerStitchExportTool(server) {
                 .describe("Legacy workspace-relative artifact bundle directory, for example exports/my-screen."),
             rawGetScreenInput: z.record(z.string(), z.unknown()).optional(),
             screenData: z.unknown().optional(),
+            versioned: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("When true, writes into the next nested version folder such as artifactPath/v001, then v002."),
+            includeHtml: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe("Download the screen htmlCode.downloadUrl into screen.html when present."),
+            includeScreenshot: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe("Download the screen screenshot.downloadUrl into screenshot.* when present."),
+            includeLinkedAssets: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Download safe HTTPS assets referenced by the exported HTML into assets/."),
+            rewriteHtmlAssetUrls: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Rewrite saved screen.html to point at downloaded local asset files."),
+            maxLinkedAssets: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .optional()
+                .default(DEFAULT_MAX_LINKED_ASSETS),
+            maxDownloadBytes: z
+                .number()
+                .int()
+                .min(1024)
+                .max(100 * 1024 * 1024)
+                .optional()
+                .default(DEFAULT_MAX_DOWNLOAD_BYTES),
         },
-    }, async ({ screenId, projectId, artifactPath, artifactName, relativePath, rawGetScreenInput, screenData }) => {
+    }, async ({ screenId, projectId, artifactPath, artifactName, relativePath, rawGetScreenInput, screenData, versioned = false, includeHtml = true, includeScreenshot = true, includeLinkedAssets = false, rewriteHtmlAssetUrls = false, maxLinkedAssets = DEFAULT_MAX_LINKED_ASSETS, maxDownloadBytes = DEFAULT_MAX_DOWNLOAD_BYTES, }) => {
         if (!screenData && !screenId && !rawGetScreenInput) {
             return {
                 content: [
@@ -807,11 +1077,38 @@ export function registerStitchExportTool(server) {
             };
         }
         const outputMode = artifactPath || relativePath ? "artifactPath" : artifactName ? "artifactName" : "default";
-        const relativeDir = artifactPath ??
+        const baseRelativeDir = artifactPath ??
             relativePath ??
             (artifactName
                 ? path.join("exports", sanitizeFileName(artifactName))
                 : defaultArtifactPath(payload, screenId));
+        let relativeDir = baseRelativeDir;
+        let versionInfo = { enabled: false };
+        if (versioned) {
+            try {
+                const versionedPath = await nextVersionedArtifactPath({
+                    baseRoot: baseRootInfo.baseRoot,
+                    artifactPath: baseRelativeDir,
+                });
+                relativeDir = versionedPath.artifactPath;
+                versionInfo = {
+                    enabled: true,
+                    baseArtifactPath: baseRelativeDir,
+                    version: versionedPath.version,
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Invalid versioned output path.\n\n${message}`,
+                        },
+                    ],
+                };
+            }
+        }
         const outputPaths = {
             "raw.json": "",
             "screen-summary.md": "",
@@ -855,6 +1152,107 @@ export function registerStitchExportTool(server) {
             const acceptanceCriteria = buildAcceptanceCriteria(payload);
             const testPlan = buildTestPlan(payload);
             const questions = buildQuestions(payload);
+            const allOutputPaths = { ...outputPaths };
+            const downloadedAssets = [];
+            const screen = getScreen(payload);
+            const htmlCode = getNestedRecord(screen, "htmlCode");
+            const screenshot = getNestedRecord(screen, "screenshot");
+            const htmlUrl = getString(htmlCode, "downloadUrl");
+            const screenshotUrl = getString(screenshot, "downloadUrl");
+            let savedHtmlPath;
+            let savedHtmlText;
+            if (includeHtml && htmlUrl) {
+                const htmlDownload = await downloadUrl({
+                    url: htmlUrl,
+                    baseRoot: baseRootInfo.baseRoot,
+                    relativeDir,
+                    fileNameStem: "screen",
+                    forcedFileName: "screen.html",
+                    kind: "html",
+                    maxBytes: maxDownloadBytes,
+                });
+                downloadedAssets.push(htmlDownload.asset);
+                if (htmlDownload.asset.status === "saved") {
+                    savedHtmlPath = htmlDownload.asset.path;
+                    savedHtmlText = htmlDownload.text;
+                    if (htmlDownload.asset.relativePath) {
+                        allOutputPaths["screen.html"] = htmlDownload.asset.path ?? "";
+                    }
+                }
+            }
+            if (includeScreenshot && screenshotUrl) {
+                const screenshotDownload = await downloadUrl({
+                    url: screenshotUrl,
+                    baseRoot: baseRootInfo.baseRoot,
+                    relativeDir,
+                    fileNameStem: "screenshot",
+                    kind: "screenshot",
+                    maxBytes: maxDownloadBytes,
+                });
+                downloadedAssets.push(screenshotDownload.asset);
+                if (screenshotDownload.asset.status === "saved" && screenshotDownload.asset.path) {
+                    allOutputPaths[path.basename(screenshotDownload.asset.path)] = screenshotDownload.asset.path;
+                }
+            }
+            if (includeLinkedAssets && htmlUrl) {
+                if (!savedHtmlText) {
+                    const htmlDownload = await downloadUrl({
+                        url: htmlUrl,
+                        baseRoot: baseRootInfo.baseRoot,
+                        relativeDir,
+                        fileNameStem: "screen",
+                        forcedFileName: "screen.html",
+                        kind: "html",
+                        maxBytes: maxDownloadBytes,
+                    });
+                    downloadedAssets.push(htmlDownload.asset);
+                    if (htmlDownload.asset.status === "saved") {
+                        savedHtmlPath = htmlDownload.asset.path;
+                        savedHtmlText = htmlDownload.text;
+                        if (htmlDownload.asset.path) {
+                            allOutputPaths["screen.html"] = htmlDownload.asset.path;
+                        }
+                    }
+                }
+                const linkedUrls = savedHtmlText
+                    ? extractLinkedAssetUrls(savedHtmlText, htmlUrl).slice(0, maxLinkedAssets)
+                    : [];
+                const rewriteMap = new Map();
+                for (const [index, linkedUrl] of linkedUrls.entries()) {
+                    const linkedAsset = await downloadUrl({
+                        url: linkedUrl,
+                        baseRoot: baseRootInfo.baseRoot,
+                        relativeDir: path.join(relativeDir, "assets"),
+                        fileNameStem: assetFileNameStem("asset", index + 1),
+                        kind: "linked-asset",
+                        maxBytes: maxDownloadBytes,
+                        requireLinkedAssetType: true,
+                    });
+                    downloadedAssets.push(linkedAsset.asset);
+                    if (linkedAsset.asset.status === "saved" && linkedAsset.asset.path) {
+                        allOutputPaths[`assets/${path.basename(linkedAsset.asset.path)}`] = linkedAsset.asset.path;
+                        if (savedHtmlPath) {
+                            const localReference = path
+                                .relative(path.dirname(savedHtmlPath), linkedAsset.asset.path)
+                                .split(path.sep)
+                                .join("/");
+                            rewriteMap.set(linkedUrl, localReference.startsWith(".") ? localReference : `./${localReference}`);
+                        }
+                    }
+                }
+                if (rewriteHtmlAssetUrls && savedHtmlPath && savedHtmlText && rewriteMap.size > 0) {
+                    let rewrittenHtml = savedHtmlText;
+                    for (const [remoteUrl, localReference] of rewriteMap) {
+                        rewrittenHtml = rewrittenHtml.split(remoteUrl).join(localReference);
+                    }
+                    await writeFile(savedHtmlPath, rewrittenHtml, "utf8");
+                }
+            }
+            if (downloadedAssets.length > 0) {
+                const assetManifestPath = await prepareSafeOutputPath(baseRootInfo.baseRoot, path.join(relativeDir, "asset-manifest.json"));
+                allOutputPaths["asset-manifest.json"] = assetManifestPath;
+                await writeFile(assetManifestPath, `${toPrettyJson({ generatedAt, assets: downloadedAssets })}\n`, "utf8");
+            }
             const manifest = createManifest({
                 payload,
                 input: {
@@ -866,10 +1264,19 @@ export function registerStitchExportTool(server) {
                     ...(rawGetScreenInput ? { rawGetScreenInput } : {}),
                     ...(screenData ? { screenDataProvided: true } : {}),
                     ...(fetchInput ? { fetchInput } : {}),
+                    versioned,
+                    includeHtml,
+                    includeScreenshot,
+                    includeLinkedAssets,
+                    rewriteHtmlAssetUrls,
+                    maxLinkedAssets,
+                    maxDownloadBytes,
                 },
                 resolver: resolverInfo,
                 generatedAt,
-                paths: outputPaths,
+                paths: allOutputPaths,
+                downloadedAssets,
+                versionInfo,
                 artifactPath: relativeDir,
                 resolvedOutputDir: path.dirname(outputPaths["manifest.json"]),
                 baseRoot: baseRootInfo.baseRoot,
@@ -888,9 +1295,11 @@ export function registerStitchExportTool(server) {
             await writeFile(outputPaths["test-plan.md"], `${testPlan}\n`, "utf8");
             await writeFile(outputPaths["questions.md"], `${questions}\n`, "utf8");
             await writeFile(outputPaths["manifest.json"], `${toPrettyJson(manifest)}\n`, "utf8");
-            const screen = getScreen(payload);
             const title = getString(screen, "title") ?? "(untitled)";
             const screenName = getString(screen, "name") ?? "(unknown)";
+            const savedCount = downloadedAssets.filter((asset) => asset.status === "saved").length;
+            const skippedCount = downloadedAssets.filter((asset) => asset.status === "skipped").length;
+            const failedCount = downloadedAssets.filter((asset) => asset.status === "failed").length;
             return {
                 content: [
                     {
@@ -899,10 +1308,14 @@ export function registerStitchExportTool(server) {
                             `Title: ${title}\n` +
                             `Screen: ${screenName}\n` +
                             `Artifact path: ${relativeDir}\n` +
+                            (versionInfo.enabled
+                                ? `Version: ${versionInfo.version} (${versionInfo.baseArtifactPath})\n`
+                                : "") +
                             `Base root: ${baseRootInfo.baseRoot} (${baseRootInfo.source})\n` +
                             `Output directory: ${path.dirname(outputPaths["manifest.json"])}\n\n` +
+                            `Downloaded assets: ${savedCount} saved, ${skippedCount} skipped, ${failedCount} failed\n\n` +
                             "Files:\n" +
-                            ARTIFACT_FILES.map((fileName) => `- ${fileName}: ${outputPaths[fileName]}`).join("\n"),
+                            Object.entries(allOutputPaths).map(([fileName, filePath]) => `- ${fileName}: ${filePath}`).join("\n"),
                     },
                 ],
             };