@dypai-ai/mcp 1.4.2 → 1.4.5

package/src/tools/deploy.js

@@ -1,22 +1,28 @@
 /**
- * deploy_frontend — delta deploy engine.
+ * deploy_frontend — full-project deploy with "skip if identical" optimization.
  *
- * 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.
+ * Architecture (deliberately simple, InsForge-style):
+ *   1. Walk the project, hash every file.
+ *   2. Compute a single project-wide hash (SHA-256 of sorted path+hash pairs).
+ *   3. If this hash matches the last-deploy hash on disk → skip entirely.
+ *   4. Otherwise send ALL files to the API (full deploy, replace_all=True).
+ *   5. Poll build-status to confirm GitHub commit happened.
+ *   6. On confirmation, persist the new project hash locally.
  *
- * Manifest lives at `dypai/.dypai/deploy-manifest.json`:
- *   { "src/app/page.tsx": "a1b2c3...", "public/logo.png": "d4e5f6..." }
+ * Why not delta? A previous delta-based implementation (incremental commits,
+ * per-file manifest, deleted_paths list) generated too many edge cases:
+ *   - Manifest drift after walk-rule changes (ghost "deletions")
+ *   - Optimistic manifest updates on HTTP 202 where async commit failed
+ *   - Migration triggers on deletion-only deploys
+ * Each required a new defensive hack. The failure mode was always the same:
+ * client-side state drifted from remote truth. Full deploys make drift
+ * impossible: every deploy is a self-contained snapshot of project state.
+ * GitHub's blob dedup handles unchanged-content efficiency at the server
+ * side — we don't need to reinvent it client-side.
  *
- * 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
+ * Trade-off: ~10s extra per deploy when only one file changed (because we
+ * send the whole project over gzip-compressed wire instead of just that
+ * file). For production reliability, that trade is the right one.
  */
 
 import { createHash } from "crypto"
@@ -33,10 +39,16 @@ const MAX_BUNDLED_FILE = 25 * 1024 * 1024
 
 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",
+  // DYPAI backend metadata — handled by dypai_pull/push, not shipped to the
+  // frontend build.
+  "dypai",
 ])
 
 // ─── Accepted file extensions ───────────────────────────────────────────────
@@ -109,33 +121,53 @@ function mediaCategory(ext) {
   return "other"
 }
 
-// ─── Deploy manifest ────────────────────────────────────────────────────────
-//
-// Tracks SHA-256 of each file at last successful deploy.
-// Path: <sourceDirectory>/dypai/.dypai/deploy-manifest.json
+// ─── Last-deploy hash (single value, no per-file tracking) ──────────────────
 //
-// Format: { "src/app/page.tsx": "a1b2c3...", ... }
+// Replaces the old per-file manifest. Stores ONE hash representing the entire
+// project state at last successful deploy. Drift is impossible: either the
+// recomputed project hash matches (skip) or it doesn't (full deploy).
 
-function manifestPath(sourceDirectory) {
+function lastDeployPath(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")
+  if (existsSync(join(sourceDirectory, "dypai"))) return join(dypaiDir, "last-deploy.json")
+  return join(sourceDirectory, ".dypai", "last-deploy.json")
 }
 
-function readDeployManifest(sourceDirectory) {
-  const path = manifestPath(sourceDirectory)
+function readLastDeployHash(sourceDirectory) {
+  const path = lastDeployPath(sourceDirectory)
   if (!existsSync(path)) return null
-  try { return JSON.parse(readFileSync(path, "utf-8")) } catch { return null }
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf-8"))
+    return raw && typeof raw.hash === "string" ? raw.hash : null
+  } catch { return null }
 }
 
-function writeDeployManifest(sourceDirectory, manifest) {
-  const path = manifestPath(sourceDirectory)
+function writeLastDeployHash(sourceDirectory, hash) {
+  const path = lastDeployPath(sourceDirectory)
   const dir = dirname(path)
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
-  writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n")
+  writeFileSync(path, JSON.stringify({ hash, at: new Date().toISOString() }, null, 2) + "\n")
 }
 
-// ─── Media manifest (for bucket-uploaded files) ─────────────────────────────
+/**
+ * Produce a single SHA-256 fingerprint that uniquely identifies the set of
+ * files about to be deployed. Files are sorted by path for determinism;
+ * path and per-file hash are joined with a NUL byte (which can't appear in
+ * either) to avoid any ambiguity between e.g. "foo"+"bar" and "foob"+"ar".
+ */
+function computeProjectHash(files) {
+  const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path))
+  const h = createHash("sha256")
+  for (const f of sorted) {
+    h.update(f.path)
+    h.update("\0")
+    h.update(f.hash)
+    h.update("\0")
+  }
+  return h.digest("hex")
+}
+
+// ─── Media manifest (kept — tracks bucket uploads for the upload_file tool) ─
 
 function mediaManifestPath(sourceDirectory) {
   const dypaiDir = join(sourceDirectory, "dypai", ".dypai")
@@ -188,18 +220,9 @@ function classifySkip(path, ext, size) {
   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 allFiles = []
   const skipped = []
-  const hashMap = {}
   const textByPath = new Map()
   let total = 0
 
@@ -251,7 +274,6 @@ function collectSource(dir) {
 
         total += content.length
         const hash = sha256(content)
-        hashMap[path] = hash
         allFiles.push({ path, content: content.toString("base64"), hash })
 
         if (CODE_SEARCH_EXTS.has(ext)) {
@@ -262,36 +284,10 @@ function collectSource(dir) {
   }
 
   walk(dir, "")
-  return { allFiles, total, skipped, hashMap, textByPath }
+  return { allFiles, total, skipped, textByPath }
 }
 
-// ─── 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 ─────────────────────────────────────────────────────────
+// ─── Reference grep for assets_requiring_action ─────────────────────────────
 
 function grepReferences(skipped, textByPath) {
   if (skipped.length === 0) return skipped
@@ -403,9 +399,36 @@ function detectFramework(dir) {
   } catch { return null }
 }
 
+// ─── Post-deploy confirmation ───────────────────────────────────────────────
+//
+// Polls /build-status after the API accepts the deploy. The API returns 202
+// queued immediately but the GitHub commit happens in a background task; we
+// only persist the new "last deploy" hash once the commit has clearly
+// happened (status moved past "queued"). If the background task fails, we
+// leave the hash untouched — the next deploy will re-send everything.
+
+async function confirmDeploySucceeded(project_id) {
+  const MAX_POLLS = 6
+  const INTERVAL_MS = 2000
+
+  for (let i = 0; i < MAX_POLLS; i++) {
+    await new Promise(r => setTimeout(r, INTERVAL_MS))
+    try {
+      const res = await api.get(`/api/engine/${project_id}/frontend/build-status`)
+      const status = res?.status || res?.build_status || null
+      if (status === "failed") return { confirmed: false, status, reason: "build_failed" }
+      if (status === "building" || status === "success") return { confirmed: true, status, reason: null }
+    } catch {
+      // Transient — keep polling
+    }
+  }
+  // Never left "queued" — treat as unconfirmed (safer to re-deploy next time)
+  return { confirmed: false, status: "queued", reason: "confirmation_timeout" }
+}
+
 // ─── Public entrypoint ──────────────────────────────────────────────────────
 
-export async function deployFromSource({ sourceDirectory, project_id }) {
+export async function deployFromSource({ sourceDirectory, project_id, force = false }) {
   if (!existsSync(sourceDirectory)) {
     return { error: `Directory not found: ${sourceDirectory}` }
   }
@@ -416,81 +439,69 @@ export async function deployFromSource({ sourceDirectory, project_id }) {
   _lastSourceDirectory = resolve(sourceDirectory)
 
   const framework = detectFramework(sourceDirectory)
-  const { allFiles, total, skipped, hashMap, textByPath } = collectSource(sourceDirectory)
+  const { allFiles, total, skipped, textByPath } = collectSource(sourceDirectory)
 
   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.`,
+  // ── Skip-if-identical check ─────────────────────────────────────────────
+  // One hash represents the whole project state. Same hash → nothing to do.
+  // Different hash (or no previous hash) → full deploy.
+  const projectHash = computeProjectHash(allFiles)
+
+  if (!force) {
+    const lastHash = readLastDeployHash(sourceDirectory)
+    if (lastHash && lastHash === projectHash) {
+      return {
+        success: true,
+        deployed: false,
+        skipped_reason: "no_changes",
+        files_total: allFiles.length,
+        project_hash: projectHash,
+        message: `No changes since last deploy (${allFiles.length} files match). Pass force:true to re-deploy anyway.`,
+      }
     }
   }
 
-  // ── Build payload (delta or full) ───────────────────────────────────────
-  const isIncremental = !delta.isFirstDeploy && delta.unchanged.length > 0
-  let filesToSend, payloadSize
-
-  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
-  }
-
+  // ── Build payload (always full) ────────────────────────────────────────
   grepReferences(skipped, textByPath)
   const mediaManifest = readMediaManifest(sourceDirectory)
 
   try {
     const body = {
-      files: filesToSend.map(f => ({ path: f.path, content: f.content })),
+      files: allFiles.map(f => ({ path: f.path, content: f.content })),
       framework: framework?.id ?? null,
     }
 
-    // Signal incremental mode to the API
-    if (isIncremental) {
-      body.incremental = true
-      if (delta.deleted.length > 0) {
-        body.deleted_paths = delta.deleted
-      }
-    }
-
     const result = await api.post(
       `/api/engine/${project_id}/frontend/deploy/source`,
       body,
     )
 
-    // ── Update manifest on success ──────────────────────────────────────
-    writeDeployManifest(sourceDirectory, hashMap)
+    // ── Confirm the background task actually committed ──────────────────
+    const confirmation = await confirmDeploySucceeded(project_id)
+    if (confirmation.confirmed) {
+      writeLastDeployHash(sourceDirectory, projectHash)
+    }
 
     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 quota = result.build_quota || null
+    const quotaWarning = buildQuotaWarning(quota)
 
     const baseMessage =
-      `Deploy accepted — ${deltaInfo}. ` +
+      `Deploy accepted — ${allFiles.length} files (${formatBytes(total)}). ` +
       `Build running (${label}, ~20-60s). Poll manage_frontend({operation:"build_status"}) every ~5s.`
 
     let message = baseMessage
+    if (quotaWarning) {
+      message = `${quotaWarning}\n\n${message}`
+    }
     if (hasUnresolvedAssets) {
-      message = `${assetsAction.message}\n\n${baseMessage}`
+      message = `${assetsAction.message}\n\n${message}`
     }
 
     return {
@@ -498,31 +509,25 @@ export async function deployFromSource({ sourceDirectory, project_id }) {
       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)",
-      },
+      build_status: confirmation.status || "queued",
+      files_total: allFiles.length,
+      bytes_total: total,
+      project_hash: projectHash,
+      last_deploy_hash_updated: confirmation.confirmed,
+      ...(confirmation.reason ? { confirmation_warning: confirmation.reason } : {}),
 
       ...(hasUnresolvedAssets ? { assets_requiring_action: assetsAction } : {}),
       ...(assetsAction?.all_synced ? { assets_synced: assetsAction.already_in_bucket } : {}),
 
+      ...(quota ? { build_quota: quota } : {}),
+
       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.",
+              "3. Re-deploy.",
               "4. Poll build_status until terminal.",
             ],
             terminal_statuses: ["success", "failure"],
@@ -539,6 +544,46 @@ export async function deployFromSource({ sourceDirectory, project_id }) {
       message,
     }
   } catch (e) {
+    if (e.statusCode === 429 && e.detail && e.detail.error === "build_quota_exceeded") {
+      return {
+        success: false,
+        error: e.detail.message || "Monthly build minutes limit reached.",
+        error_code: "build_quota_exceeded",
+        build_quota: {
+          minutes_used: e.detail.minutes_used,
+          minutes_limit: e.detail.minutes_limit,
+          resets_at: e.detail.resets_at,
+        },
+        upgrade_url: e.detail.upgrade_url,
+        advice: "Do not retry this deploy. Inform the user that the monthly build minute quota is exhausted and suggest upgrading the project plan.",
+      }
+    }
+    if (e.statusCode === 429 && e.detail && e.detail.error === "concurrent_builds_limit") {
+      return {
+        success: false,
+        error: e.detail.message || "Concurrent build limit reached.",
+        error_code: "concurrent_builds_limit",
+        concurrent_active: e.detail.concurrent_active,
+        concurrent_limit: e.detail.concurrent_limit,
+        advice: "Wait for the active build to finish (poll manage_frontend({operation:'build_status'})) before re-deploying.",
+      }
+    }
     return { error: `Deploy failed: ${e.message}` }
   }
 }
+
+/**
+ * Human-readable warning when the project is near its monthly build quota.
+ * Returns null when plan is unlimited or usage is below 80%.
+ */
+function buildQuotaWarning(quota) {
+  if (!quota) return null
+  const { minutes_used, minutes_limit, minutes_remaining } = quota
+  if (minutes_limit == null) return null
+  const pct = minutes_limit > 0 ? (minutes_used / minutes_limit) : 0
+  if (pct < 0.8) return null
+  if (pct >= 1) {
+    return `⚠️ Monthly build minutes exhausted (${minutes_used}/${minutes_limit} min). This deploy used your last minutes — upgrade your plan to deploy again.`
+  }
+  return `⚠️ Build quota at ${Math.round(pct * 100)}% (${minutes_used}/${minutes_limit} min, ${minutes_remaining} remaining). Consider upgrading soon.`
+}

package/src/tools/frontend.js

@@ -14,11 +14,13 @@
 import { api } from "../api.js"
 import { deployFromSource } from "./deploy.js"
 import { syncFromRemote } from "./sync.js"
+import { proxyToolCall } from "./proxy.js"
 
 export const manageFrontendTool = {
   name: "manage_frontend",
   description:
-    "Manage the project's frontend: download the source code to disk AND the deploy lifecycle.\n\n" +
+    "FRONTEND ONLY — manages the project's static frontend (HTML/CSS/JS bundle). For BACKEND endpoints/workflows use dypai_push + manage_drafts; never use this tool for backend work.\n\n" +
+    "Two phases: download source to local disk (`sync`), then ship changes back (`deploy`).\n\n" +
     "Use `sync` FIRST whenever you start working on a project whose frontend code isn't already on this machine — " +
     "without it you have no React/Vite source to read or edit. Call `deploy` to ship your changes.\n\n" +
     "Operations:\n" +
@@ -28,19 +30,25 @@ export const manageFrontendTool = {
     "Writes only; does NOT delete local files that were removed upstream — you may have stale files after sync (call them out to the user). " +
     "By default refuses to overwrite a directory that already has a package.json — pass overwrite:true to allow it (local-only files like .env, node_modules, .vscode are always preserved). " +
     "AFTER SYNC: .env is gitignored so it's NOT included in the download. If the target directory has no .env, the response sets `env_file_missing: true` and adds a `next_steps` line with the exact VITE_DYPAI_URL / NEXT_PUBLIC_DYPAI_URL value to write. Follow it — without .env the SDK can't reach the engine.\n" +
-    "  - deploy: Upload source files from a local directory and queue a build. Returns immediately with build_status=\"queued\" — poll with `build_status` until \"success\" or \"failure\".\n" +
+    "  - deploy: Upload source files from a local directory and queue a build. **DESTRUCTIVE: replaces the LIVE site immediately, no draft stage, no rollback button.** " +
+    "Requires `confirm: true` — without it the tool returns a confirmation_required hint instead of deploying. " +
+    "If backend drafts are pending, the hint includes a warning to publish backend FIRST (otherwise the new frontend may call endpoints that don't exist yet). " +
+    "Returns immediately with build_status=\"queued\" — poll with `build_status` until \"success\" or \"failure\". " +
+    "The response includes `build_quota` with remaining monthly build minutes. If minutes_remaining is low, tell the user. If 0, DO NOT retry — suggest upgrading the plan.\n" +
     "  - status: Current live deploy info (URL, last deploy time, size).\n" +
     "  - build_status: Progress of the current/latest build (queued/building/success/failure + stage + %).\n" +
+    "  - usage: Full frontend usage snapshot including build_quota (minutes used/limit/remaining, deploy counts, resets_at). Call BEFORE deploy if unsure how much quota is left.\n" +
     "  - list_deployments: Recent deploy history (status, commit, duration, URL).\n" +
     "  - logs: Build logs for a specific deployment (needs deployment_id from list_deployments).\n\n" +
-    "Related: `dypai_pull` brings BACKEND state (YAML endpoints, SQL, prompts). The two are independent — run both when starting fresh on a full-stack project.",
+    "Related: `dypai_pull` brings BACKEND state (YAML endpoints, SQL, prompts). The two are independent — run both when starting fresh on a full-stack project.\n\n" +
+    "Order rule when both backend AND frontend changed: 1) dypai_push (saves backend as draft) → 2) manage_drafts(publish, confirm:true) → 3) manage_frontend(deploy, confirm:true). Inverting steps 2 and 3 may serve a frontend that calls non-existent endpoints.",
 
   inputSchema: {
     type: "object",
     properties: {
       operation: {
         type: "string",
-        enum: ["deploy", "sync", "status", "build_status", "list_deployments", "logs"],
+        enum: ["deploy", "sync", "status", "build_status", "usage", "list_deployments", "logs"],
         description: "Which action to run.",
       },
       project_id: {
@@ -60,6 +68,16 @@ export const manageFrontendTool = {
         description: "sync only. When true, allows writing into a directory that already has a project. Local-only files (.env, node_modules, etc.) are NOT touched. Default: false.",
         default: false,
       },
+      force: {
+        type: "boolean",
+        description: "deploy only. Bypass the delta manifest and re-send ALL files (full deploy). Use when the previous deploy's remote build FAILED — the manifest says 'synced' but the remote never built, so a normal delta incorrectly reports no_changes. Default: false.",
+        default: false,
+      },
+      confirm: {
+        type: "boolean",
+        description: "Required `true` for `deploy`. Without it the tool returns a confirmation_required hint (with a ready-to-call next_call) instead of replacing the live site. The agent MUST get explicit user approval before passing confirm:true.",
+        default: false,
+      },
       deployment_id: {
         type: "string",
         description: "logs only. Deployment UUID obtained from list_deployments.",
@@ -72,7 +90,7 @@ export const manageFrontendTool = {
     required: ["operation"],
   },
 
-  async execute({ operation, project_id, sourceDirectory, targetDirectory, overwrite, deployment_id, limit } = {}) {
+  async execute({ operation, project_id, sourceDirectory, targetDirectory, overwrite, force, confirm, deployment_id, limit } = {}) {
     if (!operation) {
       return { success: false, error: "operation is required (deploy | sync | status | build_status | list_deployments | logs)." }
     }
@@ -86,7 +104,44 @@ export const manageFrontendTool = {
           if (!sourceDirectory) {
             return { success: false, error: "operation 'deploy' requires 'sourceDirectory' (absolute path to your frontend project root)." }
           }
-          return await deployFromSource({ sourceDirectory, project_id })
+          // Defense-in-depth gate: deploy replaces the live site immediately
+          // with no rollback. Without explicit confirm we return a structured
+          // hint (with ready-to-execute next_call). We also surface any
+          // pending backend drafts as warnings — the agent should ALWAYS
+          // publish backend drafts before deploying frontend, otherwise the
+          // new frontend may call endpoints that don't exist yet on live.
+          if (confirm !== true) {
+            const warnings = []
+            try {
+              const draftsResult = await proxyToolCall("manage_drafts", { project_id, operation: "list" })
+              const draftsTotal = draftsResult?.total || 0
+              if (draftsTotal > 0) {
+                warnings.push(
+                  `${draftsTotal} backend draft(s) pending. Publish them BEFORE deploying the frontend with manage_drafts(operation:'publish', confirm:true) — otherwise the new frontend may call endpoints that don't exist on live yet.`,
+                )
+              }
+            } catch {
+              // Soft-fail — drafts check is advisory, not gating.
+            }
+            return {
+              confirmation_required: true,
+              summary: `About to replace the LIVE frontend at this project's public URL with the contents of '${sourceDirectory}'. This is IMMEDIATE and there is NO automatic rollback.`,
+              warnings: warnings.length > 0 ? warnings : undefined,
+              next_call: {
+                tool: "manage_frontend",
+                operation: "deploy",
+                project_id,
+                sourceDirectory,
+                ...(force ? { force: true } : {}),
+                confirm: true,
+              },
+              hint:
+                "Summarize the change to the user (what visual/functional changes are about to go live, " +
+                "and any pending backend drafts) and wait for explicit user approval. Then re-call this " +
+                "tool with confirm:true.",
+            }
+          }
+          return await deployFromSource({ sourceDirectory, project_id, force: !!force })
 
         case "sync":
           if (!targetDirectory) {
@@ -100,6 +155,9 @@ export const manageFrontendTool = {
         case "build_status":
           return await api.get(`/api/engine/${project_id}/frontend/build-status`)
 
+        case "usage":
+          return await api.get(`/api/engine/${project_id}/frontend/usage`)
+
         case "list_deployments":
           return await api.get(`/api/engine/${project_id}/frontend/deployments?limit=${limit || 10}`)
 
@@ -110,7 +168,7 @@ export const manageFrontendTool = {
           return await api.get(`/api/engine/${project_id}/frontend/deployments/${deployment_id}/logs`)
 
         default:
-          return { success: false, error: `Unknown operation '${operation}'. Use deploy | sync | status | build_status | list_deployments | logs.` }
+          return { success: false, error: `Unknown operation '${operation}'. Use deploy | sync | status | build_status | usage | list_deployments | logs.` }
       }
     } catch (e) {
       return { success: false, error: e.message, operation }

package/src/tools/scaffold.js

@@ -47,9 +47,13 @@ Or use "blank" for an empty starter project.`,
       return { error: `Directory already has a package.json. Pick an empty directory or a new name.` }
     }
 
-    // Production engine URL: https://<project-id>.dypai.app (NOT .dypai.dev — that's the dev tier).
+    // Engine base URL — `<project_id>.dypai.dev` serves LIVE traffic; the
+    // local-development URL `dev-<project_id>.dypai.dev` (Layer 2.5 draft
+    // overlay) is written into `.env.local` separately by `sync` once the
+    // user has the frontend on disk. Scaffold writes the production URL
+    // because at scaffold-time we expect the user to deploy soon.
     // Override with DYPAI_ENGINE_BASE for self-hosted / staging setups.
-    const engineBase = process.env.DYPAI_ENGINE_BASE || "dypai.app"
+    const engineBase = process.env.DYPAI_ENGINE_BASE || "dypai.dev"
     const engineUrl = `https://${project_id}.${engineBase}`
 
     // Try to download template from API