@dypai-ai/mcp 1.3.0 → 1.4.0

package/src/tools/deploy.js

@@ -1,109 +1,383 @@
 /**
- * deploy_frontend — Reads source files from disk and deploys to DYPAI.
+ * deploy_frontend — delta deploy engine.
  *
- * This is the key tool that requires local filesystem access.
- * The AI passes sourceDirectory, this tool reads all source files,
- * sends them to the API, which commits to GitHub → CF Pages builds.
+ * Like InsForge/Vercel, uses SHA-256 hashing + a local manifest to send only
+ * the files that actually changed since the last deploy. Typical second deploy
+ * goes from ~30 MB to a few KB.
+ *
+ * Manifest lives at `dypai/.dypai/deploy-manifest.json`:
+ *   { "src/app/page.tsx": "a1b2c3...", "public/logo.png": "d4e5f6..." }
+ *
+ * Flow:
+ *   1. Walk directory, hash each accepted file (SHA-256)
+ *   2. Diff against manifest → new, changed, unchanged, deleted
+ *   3. If nothing changed → skip deploy ("No changes detected")
+ *   4. Send only new+changed files + deleted_paths to API (incremental mode)
+ *   5. API commits via GitHub Trees API with base_tree (preserves unchanged)
+ *   6. Update local manifest
+ *
+ * Files > 25 MB → surfaced in `assets_requiring_action` with upload_file cmd
  */
 
-import { readFileSync, readdirSync, statSync, existsSync } from "fs"
-import { join, relative } from "path"
+import { createHash } from "crypto"
+import { readFileSync, readdirSync, statSync, existsSync, writeFileSync, mkdirSync } from "fs"
+import { join, basename, dirname, resolve } from "path"
 import { api } from "../api.js"
 
+// ─── Limits ─────────────────────────────────────────────────────────────────
+
 const MAX_SOURCE_SIZE = 50 * 1024 * 1024
+const MAX_BUNDLED_FILE = 25 * 1024 * 1024
+
+// ─── Directories to skip ────────────────────────────────────────────────────
 
-// Directories to skip — build outputs, caches, package managers
 const IGNORE_DIRS = new Set([
   "node_modules", ".git",
-  // Build outputs
   "dist", "build", "out", ".output", ".vercel", ".netlify",
-  // Framework caches
   ".next", ".nuxt", ".svelte-kit", ".astro", ".angular", ".docusaurus",
   ".cache", ".turbo", ".vite", ".parcel-cache", ".wrangler",
-  // Test / misc
   "coverage", "storybook-static", "__pycache__", ".idea", ".vscode",
 ])
 
-// Source file extensions to include
-const SOURCE_EXTS = new Set([
-  // JavaScript / TypeScript
+// ─── Accepted file extensions ───────────────────────────────────────────────
+
+const CODE_EXTS = new Set([
   ".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts", ".cjs", ".cts",
-  // Styles
   ".css", ".scss", ".less", ".sass", ".styl",
-  // Markup / templates
   ".html", ".htm",
-  // Framework-specific SFCs
   ".vue", ".svelte", ".astro",
-  // Data / config
   ".json", ".toml", ".yaml", ".yml",
-  // Content
   ".md", ".mdx", ".txt",
-  // Assets metadata
-  ".svg", ".ico", ".webmanifest",
-  // Schema / query
   ".graphql", ".gql", ".prisma",
-  // Misc
   ".xml", ".csv",
 ])
 
-const IMAGE_EXTS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".ico", ".svg"])
-const BLOCKED = new Set([".env", ".env.local", ".env.production", ".env.development", ".DS_Store", "Thumbs.db"])
-const MAX_IMAGE = 2 * 1024 * 1024
+const IMAGE_EXTS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".ico", ".svg", ".bmp", ".tiff"])
+const VIDEO_EXTS = new Set([".mp4", ".webm", ".mov", ".mkv", ".avi"])
+const AUDIO_EXTS = new Set([".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac"])
+const DOC_EXTS = new Set([".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx"])
+const FONT_EXTS = new Set([".woff", ".woff2", ".ttf", ".otf", ".eot"])
+const ARCHIVE_EXTS = new Set([".zip", ".gz", ".tar", ".rar", ".7z"])
+const MISC_STATIC_EXTS = new Set([".webmanifest", ".lottie"])
+
+const ALL_ACCEPTED_EXTS = new Set([
+  ...CODE_EXTS, ...IMAGE_EXTS, ...VIDEO_EXTS, ...AUDIO_EXTS,
+  ...DOC_EXTS, ...FONT_EXTS, ...ARCHIVE_EXTS, ...MISC_STATIC_EXTS,
+])
+
+const CODE_SEARCH_EXTS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts", ".cjs", ".cts",
+  ".vue", ".svelte", ".astro",
+  ".html", ".htm", ".css", ".scss", ".less",
+  ".json", ".md", ".mdx",
+])
+
+const BLOCKED = new Set([
+  ".env", ".env.local", ".env.production", ".env.development",
+  ".DS_Store", "Thumbs.db",
+])
 
-// Root-level config files to always include (regex)
 const ROOT_CONFIG_RE = /^(package\.json|package-lock\.json|pnpm-lock\.yaml|bun\.lockb|yarn\.lock|vite\.config|vitest\.config|tsconfig|tailwind\.config|postcss\.config|next\.config|vinext\.config|astro\.config|nuxt\.config|svelte\.config|remix\.config|gatsby-config|angular\.json|docusaurus\.config|wrangler\.toml|wrangler\.json|vercel\.json|netlify\.toml|turbo\.json|components\.json|uno\.config|eslint\.config|prettier\.config|jest\.config|playwright\.config|\.prettierrc|\.eslintrc|\.browserslistrc|\.nvmrc|\.node-version|index\.html)/
 
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function extOf(entry) {
+  return entry.includes(".") ? `.${entry.split(".").pop().toLowerCase()}` : ""
+}
+
+function formatBytes(n) {
+  if (n < 1024) return `${n} B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`
+  return `${(n / 1024 / 1024).toFixed(1)} MB`
+}
+
+function formatMb(bytes) {
+  return +(bytes / (1024 * 1024)).toFixed(1)
+}
+
+function sha256(buf) {
+  return createHash("sha256").update(buf).digest("hex")
+}
+
+function mediaCategory(ext) {
+  if (IMAGE_EXTS.has(ext)) return "image"
+  if (VIDEO_EXTS.has(ext)) return "video"
+  if (AUDIO_EXTS.has(ext)) return "audio"
+  if (DOC_EXTS.has(ext)) return "document"
+  if (FONT_EXTS.has(ext)) return "font"
+  if (ARCHIVE_EXTS.has(ext)) return "archive"
+  return "other"
+}
+
+// ─── Deploy manifest ────────────────────────────────────────────────────────
+//
+// Tracks SHA-256 of each file at last successful deploy.
+// Path: <sourceDirectory>/dypai/.dypai/deploy-manifest.json
+//
+// Format: { "src/app/page.tsx": "a1b2c3...", ... }
+
+function manifestPath(sourceDirectory) {
+  const dypaiDir = join(sourceDirectory, "dypai", ".dypai")
+  if (existsSync(join(sourceDirectory, "dypai"))) return join(dypaiDir, "deploy-manifest.json")
+  return join(sourceDirectory, ".dypai", "deploy-manifest.json")
+}
+
+function readDeployManifest(sourceDirectory) {
+  const path = manifestPath(sourceDirectory)
+  if (!existsSync(path)) return null
+  try { return JSON.parse(readFileSync(path, "utf-8")) } catch { return null }
+}
+
+function writeDeployManifest(sourceDirectory, manifest) {
+  const path = manifestPath(sourceDirectory)
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n")
+}
+
+// ─── Media manifest (for bucket-uploaded files) ─────────────────────────────
+
+function mediaManifestPath(sourceDirectory) {
+  const dypaiDir = join(sourceDirectory, "dypai", ".dypai")
+  if (existsSync(join(sourceDirectory, "dypai"))) return join(dypaiDir, "media-manifest.json")
+  return join(sourceDirectory, ".dypai", "media-manifest.json")
+}
+
+function readMediaManifest(sourceDirectory) {
+  const path = mediaManifestPath(sourceDirectory)
+  if (!existsSync(path)) return {}
+  try { return JSON.parse(readFileSync(path, "utf-8")) } catch { return {} }
+}
+
+export function updateMediaManifest(sourceDirectory, localPath, entry) {
+  const path = mediaManifestPath(sourceDirectory)
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  const manifest = existsSync(path)
+    ? (() => { try { return JSON.parse(readFileSync(path, "utf-8")) } catch { return {} } })()
+    : {}
+  manifest[localPath] = entry
+  writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n")
+}
+
+export function removeFromMediaManifest(sourceDirectory, localPath) {
+  const path = mediaManifestPath(sourceDirectory)
+  if (!existsSync(path)) return
+  try {
+    const manifest = JSON.parse(readFileSync(path, "utf-8"))
+    delete manifest[localPath]
+    writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n")
+  } catch {}
+}
+
+// ─── Collection ─────────────────────────────────────────────────────────────
+
+function classifySkip(path, ext, size) {
+  if (ALL_ACCEPTED_EXTS.has(ext) && size > MAX_BUNDLED_FILE) {
+    return {
+      reason_code: "file_too_large",
+      reason_human: `${mediaCategory(ext)} file is ${formatMb(size)} MB (max ${formatMb(MAX_BUNDLED_FILE)} MB per file). Upload to the 'public' storage bucket instead.`,
+    }
+  }
+  if (ext && ![".lock", ".log"].includes(ext) && !ALL_ACCEPTED_EXTS.has(ext)) {
+    return {
+      reason_code: "unsupported_file_type",
+      reason_human: `Files of type ${ext} aren't recognized. Upload to the 'public' storage bucket if needed.`,
+    }
+  }
+  return null
+}
+
+/**
+ * Walk directory. Returns:
+ *   allFiles:   [{ path, content (base64), hash (sha256) }]
+ *   skipped:    [{ local_path, ext, size_bytes, ... }]
+ *   total:      bytes of accepted files
+ *   hashMap:    { path: sha256 }
+ *   textByPath: Map<path, string>
+ */
 function collectSource(dir) {
-  const files = []
+  const allFiles = []
   const skipped = []
+  const hashMap = {}
+  const textByPath = new Map()
   let total = 0
 
   function walk(d, rel) {
     if (total > MAX_SOURCE_SIZE) return
-    for (const entry of readdirSync(d)) {
+    let entries
+    try { entries = readdirSync(d) } catch { return }
+    for (const entry of entries) {
       if (IGNORE_DIRS.has(entry)) continue
-      if (entry.startsWith(".") && statSync(join(d, entry)).isDirectory()) continue
-      if (BLOCKED.has(entry)) continue
       const full = join(d, entry)
-      const path = rel ? `${rel}/${entry}` : entry
       try {
         const stat = statSync(full)
-        if (stat.isDirectory()) { walk(full, path); continue }
+        if (stat.isDirectory()) {
+          if (entry.startsWith(".")) continue
+          walk(full, rel ? `${rel}/${entry}` : entry)
+          continue
+        }
         if (!stat.isFile()) continue
-        const ext = entry.includes(".") ? `.${entry.split(".").pop().toLowerCase()}` : ""
-        let ok = SOURCE_EXTS.has(ext)
+      } catch { continue }
+      if (BLOCKED.has(entry)) continue
+
+      const path = rel ? `${rel}/${entry}` : entry
+      try {
+        const stat = statSync(full)
+        const ext = extOf(entry)
+
+        let ok = false
         if (!rel && ROOT_CONFIG_RE.test(entry)) ok = true
-        if (IMAGE_EXTS.has(ext) && stat.size <= MAX_IMAGE) ok = true
+        else if (CODE_EXTS.has(ext)) ok = true
+        else if (ALL_ACCEPTED_EXTS.has(ext) && stat.size <= MAX_BUNDLED_FILE) ok = true
 
-        // Track skipped files so the user knows what was excluded
         if (!ok) {
-          if (IMAGE_EXTS.has(ext) && stat.size > MAX_IMAGE) {
-            skipped.push({ path, reason: `Image too large (${(stat.size / (1024 * 1024)).toFixed(1)}MB, max ${MAX_IMAGE / (1024 * 1024)}MB)` })
-          } else if (ext && ![".lock", ".log"].includes(ext)) {
-            skipped.push({ path, reason: `Unsupported file type (${ext})` })
+          const classified = classifySkip(path, ext, stat.size)
+          if (classified) {
+            skipped.push({ local_path: path, ext, size_bytes: stat.size, size_mb: formatMb(stat.size), ...classified })
           }
           continue
         }
 
         const content = readFileSync(full)
         if (total + content.length > MAX_SOURCE_SIZE) {
-          skipped.push({ path, reason: "Total upload size limit reached" })
+          skipped.push({
+            local_path: path, ext, size_bytes: stat.size, size_mb: formatMb(stat.size),
+            reason_code: "bundle_size_limit_reached",
+            reason_human: `Total upload size limit (${formatMb(MAX_SOURCE_SIZE)} MB) reached.`,
+          })
           return
         }
+
         total += content.length
-        files.push({ path, content: content.toString("base64") })
+        const hash = sha256(content)
+        hashMap[path] = hash
+        allFiles.push({ path, content: content.toString("base64"), hash })
+
+        if (CODE_SEARCH_EXTS.has(ext)) {
+          textByPath.set(path, content.toString("utf-8"))
+        }
       } catch {}
     }
   }
 
   walk(dir, "")
-  return { files, total, skipped }
+  return { allFiles, total, skipped, hashMap, textByPath }
 }
 
-/**
- * Detect framework for display AND for API build config.
- * Returns { label, id } where id matches pages_service.py FRAMEWORK_PRESETS.
- */
+// ─── Delta computation ──────────────────────────────────────────────────────
+
+function computeDelta(hashMap, prevManifest) {
+  if (!prevManifest) return { isFirstDeploy: true, changed: Object.keys(hashMap), deleted: [], unchanged: [] }
+
+  const changed = []
+  const unchanged = []
+  const deleted = []
+
+  for (const [path, hash] of Object.entries(hashMap)) {
+    if (prevManifest[path] === hash) {
+      unchanged.push(path)
+    } else {
+      changed.push(path)
+    }
+  }
+
+  for (const path of Object.keys(prevManifest)) {
+    if (!(path in hashMap)) {
+      deleted.push(path)
+    }
+  }
+
+  return { isFirstDeploy: false, changed, deleted, unchanged }
+}
+
+// ─── Reference grep ─────────────────────────────────────────────────────────
+
+function grepReferences(skipped, textByPath) {
+  if (skipped.length === 0) return skipped
+
+  const needles = skipped.map(s => {
+    const name = basename(s.local_path)
+    const variants = new Set([name, `/${name}`, s.local_path])
+    if (s.local_path.startsWith("public/")) {
+      const stripped = s.local_path.slice("public/".length)
+      variants.add(`/${stripped}`)
+      variants.add(stripped)
+    }
+    return { entry: s, variants: [...variants] }
+  })
+
+  for (const [path, text] of textByPath) {
+    const lines = text.split("\n")
+    for (const { entry, variants } of needles) {
+      if ((entry.referenced_in_code?.length || 0) >= 5) continue
+      for (let i = 0; i < lines.length; i++) {
+        if (variants.some(v => lines[i].includes(v))) {
+          entry.referenced_in_code = entry.referenced_in_code || []
+          entry.referenced_in_code.push({ file: path, line: i + 1, snippet: lines[i].trim().slice(0, 160) })
+          if (entry.referenced_in_code.length >= 5) break
+        }
+      }
+    }
+  }
+  for (const s of skipped) { if (!s.referenced_in_code) s.referenced_in_code = [] }
+  return skipped
+}
+
+// ─── Assets requiring action ────────────────────────────────────────────────
+
+let _lastSourceDirectory = null
+
+function buildAssetsRequiringAction(skipped, mediaManifest, project_id) {
+  const actionable = skipped.filter(s => s.reason_code === "file_too_large" || s.reason_code === "unsupported_file_type")
+  if (actionable.length === 0) return null
+
+  const needsUpload = []
+  const alreadyUploaded = []
+
+  for (const s of actionable) {
+    const prev = mediaManifest[s.local_path]
+    if (prev && prev.size === s.size_bytes) {
+      alreadyUploaded.push({ local_path: s.local_path, bucket: prev.bucket, object_name: prev.object_name, status: "already_uploaded" })
+    } else {
+      needsUpload.push(s)
+    }
+  }
+
+  if (needsUpload.length === 0) {
+    return { count: 0, all_synced: true, already_in_bucket: alreadyUploaded,
+      message: `All ${alreadyUploaded.length} large asset(s) already in storage bucket.` }
+  }
+
+  const files = needsUpload.map(s => {
+    const objectName = basename(s.local_path)
+    return {
+      local_path: s.local_path, size_mb: s.size_mb, category: mediaCategory(s.ext),
+      reason_code: s.reason_code, reason_human: s.reason_human, referenced_in_code: s.referenced_in_code,
+      suggested_action: {
+        tool: "manage_storage",
+        args: {
+          operation: "upload_file", project_id, bucket: "public",
+          local_path: s.local_path, object_name: objectName,
+          ensure_bucket: true, bucket_public: true, source_directory: _lastSourceDirectory,
+        },
+        after_upload: s.referenced_in_code.length > 0
+          ? `Replace references in: ${s.referenced_in_code.map(r => `${r.file}:${r.line}`).join(", ")}`
+          : `No code references found for '${objectName}'.`,
+      },
+    }
+  })
+
+  return {
+    count: files.length,
+    message: `⚠️ ${files.length} asset(s) too large to bundle (>${formatMb(MAX_BUNDLED_FILE)} MB). Upload to 'public' bucket.`,
+    files,
+    ...(alreadyUploaded.length > 0 ? { already_in_bucket: alreadyUploaded } : {}),
+  }
+}
+
+// ─── Framework detection ────────────────────────────────────────────────────
+
 function detectFramework(dir) {
   const pkgPath = join(dir, "package.json")
   if (!existsSync(pkgPath)) return null
@@ -129,69 +403,142 @@ function detectFramework(dir) {
   } catch { return null }
 }
 
-/**
- * Pure deploy function — used by the consolidated `manage_frontend` tool.
- * Reads the source directory, uploads to the API, returns a structured
- * response the caller can hand back to the agent.
- */
+// ─── Public entrypoint ──────────────────────────────────────────────────────
+
 export async function deployFromSource({ sourceDirectory, project_id }) {
-    if (!existsSync(sourceDirectory)) {
-      return { error: `Directory not found: ${sourceDirectory}` }
-    }
+  if (!existsSync(sourceDirectory)) {
+    return { error: `Directory not found: ${sourceDirectory}` }
+  }
+  if (!existsSync(join(sourceDirectory, "package.json"))) {
+    return { error: `No package.json found in ${sourceDirectory}. Is this a frontend project?` }
+  }
+
+  _lastSourceDirectory = resolve(sourceDirectory)
+
+  const framework = detectFramework(sourceDirectory)
+  const { allFiles, total, skipped, hashMap, textByPath } = collectSource(sourceDirectory)
 
-    if (!existsSync(join(sourceDirectory, "package.json"))) {
-      return { error: `No package.json found in ${sourceDirectory}. Is this a frontend project?` }
+  if (!allFiles.length) {
+    return { error: "No source files found." }
+  }
+
+  // ── Delta computation ───────────────────────────────────────────────────
+  const prevManifest = readDeployManifest(sourceDirectory)
+  const delta = computeDelta(hashMap, prevManifest)
+
+  // Nothing changed at all → skip deploy entirely
+  if (!delta.isFirstDeploy && delta.changed.length === 0 && delta.deleted.length === 0) {
+    return {
+      success: true,
+      deployed: false,
+      skipped_reason: "no_changes",
+      files_total: allFiles.length,
+      message: `No changes detected since last deploy (${allFiles.length} files, all hashes match). Deploy skipped.`,
     }
+  }
 
-    const framework = detectFramework(sourceDirectory)
-    const { files, total, skipped } = collectSource(sourceDirectory)
+  // ── Build payload (delta or full) ───────────────────────────────────────
+  const isIncremental = !delta.isFirstDeploy && delta.unchanged.length > 0
+  let filesToSend, payloadSize
 
-    if (!files.length) {
-      return { error: "No source files found." }
+  if (isIncremental) {
+    // Only send new + changed files
+    const changedSet = new Set(delta.changed)
+    filesToSend = allFiles.filter(f => changedSet.has(f.path))
+    payloadSize = filesToSend.reduce((sum, f) => sum + Buffer.byteLength(f.content, "base64") * 0.75, 0)
+  } else {
+    filesToSend = allFiles
+    payloadSize = total
+  }
+
+  grepReferences(skipped, textByPath)
+  const mediaManifest = readMediaManifest(sourceDirectory)
+
+  try {
+    const body = {
+      files: filesToSend.map(f => ({ path: f.path, content: f.content })),
+      framework: framework?.id ?? null,
     }
 
-    try {
-      const result = await api.post(
-        `/api/engine/${project_id}/frontend/deploy/source`,
-        { files, framework: framework?.id ?? null }
-      )
-
-      const label = framework?.label ?? "Project"
-
-      // Fire-and-forget: return immediately with "queued" status. The agent
-      // is expected to call `get_build_status` to poll progress until the
-      // terminal "success" / "failure" is reached. Blocking here would stall
-      // the agent for up to 2 minutes and prevent it from doing anything
-      // else in parallel.
-      const skippedMsg = skipped.length > 0
-        ? `\n\nSkipped ${skipped.length} file(s):\n${skipped.map(s => `  - ${s.path}: ${s.reason}`).join("\n")}`
-        : ""
-
-      return {
-        success: true,
-        deployed: false,  // explicit: not live yet, still building
-        url: result.url,  // final URL once success
-        files_pushed: files.length,
-        files_skipped: skipped.length,
-        skipped_files: skipped.length > 0 ? skipped : undefined,
-        size_bytes: total,
-        framework: label,
-        build_status: "queued",
-        next_step: {
-          action: "poll_build_status",
-          tool: "manage_frontend",
-          arg: { operation: "build_status", project_id },
-          interval_seconds: 5,
-          expected_total_seconds: 60,
-          terminal_statuses: ["success", "failure"],
-        },
-        message:
-          `Deploy accepted — ${files.length} files (${Math.round(total / 1024)} KB) queued. ` +
-          `The build is running in the cloud (${label}, typically 20–60s). ` +
-          `Call manage_frontend({operation:"build_status", project_id:"${project_id}"}) every ~5s until status is "success" or "failure" ` +
-          `before reporting completion to the user. The site is NOT live yet.${skippedMsg}`,
+    // Signal incremental mode to the API
+    if (isIncremental) {
+      body.incremental = true
+      if (delta.deleted.length > 0) {
+        body.deleted_paths = delta.deleted
       }
-    } catch (e) {
-      return { error: `Deploy failed: ${e.message}` }
     }
+
+    const result = await api.post(
+      `/api/engine/${project_id}/frontend/deploy/source`,
+      body,
+    )
+
+    // ── Update manifest on success ──────────────────────────────────────
+    writeDeployManifest(sourceDirectory, hashMap)
+
+    const label = framework?.label ?? "Project"
+    const assetsAction = buildAssetsRequiringAction(skipped, mediaManifest, project_id)
+    const hasUnresolvedAssets = assetsAction && assetsAction.count > 0
+
+    const deltaInfo = isIncremental
+      ? `Delta deploy: ${delta.changed.length} changed, ${delta.deleted.length} deleted, ${delta.unchanged.length} unchanged (sent ${formatBytes(payloadSize)} instead of ${formatBytes(total)})`
+      : `Full deploy: ${allFiles.length} files (${formatBytes(total)})`
+
+    const baseMessage =
+      `Deploy accepted — ${deltaInfo}. ` +
+      `Build running (${label}, ~20-60s). Poll manage_frontend({operation:"build_status"}) every ~5s.`
+
+    let message = baseMessage
+    if (hasUnresolvedAssets) {
+      message = `${assetsAction.message}\n\n${baseMessage}`
+    }
+
+    return {
+      success: true,
+      deployed: false,
+      url: result.url,
+      framework: label,
+      build_status: "queued",
+
+      // Delta stats — shows the agent (and user) how much we saved
+      delta: {
+        mode: isIncremental ? "incremental" : "full",
+        files_sent: filesToSend.length,
+        files_total: allFiles.length,
+        files_changed: delta.changed.length,
+        files_deleted: delta.deleted.length,
+        files_unchanged: delta.unchanged.length,
+        bytes_sent: Math.round(payloadSize),
+        bytes_total: total,
+        savings: isIncremental ? `${Math.round((1 - payloadSize / total) * 100)}%` : "0% (first deploy)",
+      },
+
+      ...(hasUnresolvedAssets ? { assets_requiring_action: assetsAction } : {}),
+      ...(assetsAction?.all_synced ? { assets_synced: assetsAction.already_in_bucket } : {}),
+
+      next_step: hasUnresolvedAssets
+        ? {
+            action: "resolve_pending_assets_then_poll_build",
+            priority_order: [
+              "1. Execute each suggested_action in assets_requiring_action.files.",
+              "2. Edit source files to use the returned URL.",
+              "3. Re-deploy. Delta deploy will only send the edited files.",
+              "4. Poll build_status until terminal.",
+            ],
+            terminal_statuses: ["success", "failure"],
+          }
+        : {
+            action: "poll_build_status",
+            tool: "manage_frontend",
+            arg: { operation: "build_status", project_id },
+            interval_seconds: 5,
+            expected_total_seconds: 60,
+            terminal_statuses: ["success", "failure"],
+          },
+
+      message,
+    }
+  } catch (e) {
+    return { error: `Deploy failed: ${e.message}` }
+  }
 }