feat: Image Upload and Test Hardening

[davideast]

This PR adds two handwritten Project extensions for operations the codegen pipeline cannot express, a virtual tool layer for the MCP proxy, and test/workflow cleanup.

Usage

Image Upload

import { stitch } from "@google/stitch-sdk";

const project = stitch.project("4044680601076201931");

// Upload an image and get back Screen objects
const [screen] = await project.uploadImage("path/to/mockup.png", {
  title: "Source Mockup"
});

const html = await screen.getHtml();

Asset Download

// Download all screens and assets to a local folder
const traces = await project.downloadAssets("./dist/preview");

// Each trace tells you exactly where the files landed
for (const t of traces) {
  console.log(`${t.screenSlug} → ${t.filePath}`);
}

With options:

await project.downloadAssets("./dist/preview", {
  fileMode: 0o644,         // default: 0o600
  tempDir: "/tmp",         // default: outputDir (same-fs for atomic rename)
  assetsSubdir: "static",  // default: "assets"
});

API Surface

Project.uploadImage(filePath, opts?): Promise<Screen[]>

Uploads an image file to the project via the private BatchCreateScreens REST endpoint and returns Screen objects. Supports PNG, JPEG, and WebP.

Parameter	Type	Description
filePath	string	Path to the image file on disk
opts.title	string?	Display title for the created screen
opts.createScreenInstances	boolean?	Create canvas instances (default: true)

Errors are thrown as StitchError with codes NOT_FOUND, AUTH_FAILED, or UNKNOWN_ERROR.

Project.downloadAssets(outputDir, opts?): Promise<DownloadedScreenTrace[]>

Downloads all screens and referenced assets to a local directory. Rewrites URLs in HTML to produce self-contained output. Uses atomic temp-file renames, hash-based filenames, and path-traversal guards.

Parameter	Type	Description
outputDir	string	Target directory
opts.fileMode	number?	Unix permission bits (default: 0o600)
opts.tempDir	string?	Temp file directory (default: outputDir)
opts.assetsSubdir	string?	Asset subdirectory name (default: "assets")

Returns DownloadedScreenTrace[]:

interface DownloadedScreenTrace {
  screenId: string;    // Original screen ID
  screenSlug: string;  // Slugified directory name
  filePath: string;    // Relative path to HTML, e.g. "my-screen/code.html"
}

Errors are thrown as StitchError with codes NOT_FOUND, NETWORK_ERROR, or VALIDATION_ERROR.

Virtual Tools (MCP Proxy)

The SDK exposes download_assets as a virtual tool through StitchProxy, allowing MCP-connected agents to download project assets without direct SDK access.

Changes

Handwritten Extensions (src/project-ext.ts)

• Project.uploadImage — REST upload of image assets (PNG, JPEG, WebP) via BatchCreateScreens, returning domain Screen objects.
• Project.downloadAssets — Downloads all screens and assets, rewriting URLs to be self-contained. Returns a trace array for CLI integration.

Typed Service Contracts (src/spec/)

• upload.ts — Zod-validated input schema, UploadImageResult discriminated union, UploadImageSpec interface.
• download.ts — Zod-validated input schema with defaults, DownloadedScreenTrace type, DownloadAssetsSpec interface.

Handlers

• upload-handler.ts — File reading, base64 encoding, MIME validation, multipart upload orchestration.
• download-handler.ts — Atomic temp-file writes, hash-based asset filenames (truncated to 100 chars), Cheerio-based URL rewriting, EXDEV fallback, path-traversal detection.

MCP Proxy

• proxy/virtual-tools.ts — download_assets virtual tool definition for agent-side asset downloading.
• proxy/handlers/callTool.ts — Routes virtual tool calls to SDK methods, forwards all others to Stitch.
• proxy/handlers/listTools.ts — Merges virtual tools into the remote tool list.

Test Suite

• upload.test.ts — 16 tests covering happy path, unsupported formats, missing files, auth failures, and edge cases.
• download.test.ts — 15 tests covering HTML rewriting, asset hashing, design system export, path traversal, and trace results.
• proxy.test.ts — 3 unit tests + 10 integration tests for virtual tool routing and forwarding.
• Mock hygiene — Clean ArrayBuffer construction in mocks (no shared pool leaks), zero as any assertions.

Workflow Cleanup

• Removed fleet-analyze.yml, fleet-dispatch.yml, fleet-label.yml, fleet-merge.yml, and jules-merge-conflicts.yml. Only ci.yml remains.

[davideast]

Fixed.