@maintainer-pro/ai-cli 0.1.5 → 0.1.7

package/dist/index.js

@@ -109,7 +109,7 @@ function buildUserFacingPrompt(systemPrompt, messages, context, attachmentPaths,
   );
   const attachmentsSection = wrapSection(
     PROMPT_SECTION.attachments,
-    attachmentPaths && attachmentPaths.length > 0 ? `Screenshots / images attached by the user (open and inspect these image files):
+    attachmentPaths && attachmentPaths.length > 0 ? `Screenshots / images attached by the user (open and inspect these image files; they are stored under ~/.maintainer-pro for this project, not in the host app, and you are allowed to read them):
 ${attachmentPaths.map((p) => `- ${p}`).join("\n")}` : "",
     "user attachments"
   );
@@ -263,6 +263,7 @@ async function callClaudeCli(command, messages, context, options) {
     resolved,
     [
       "--print",
+      "--dangerously-skip-permissions",
       "--system-prompt",
       options.systemPrompt,
       "--no-session-persistence",
@@ -380,8 +381,8 @@ async function resolveCommandPath(command) {
     }
     const result = await execa2("which", [command], { reject: false });
     if (result.exitCode !== 0) return null;
-    const path6 = result.stdout.trim().split(/\r?\n/)[0]?.trim();
-    return path6 || null;
+    const path9 = result.stdout.trim().split(/\r?\n/)[0]?.trim();
+    return path9 || null;
   } catch {
     return null;
   }
@@ -528,7 +529,7 @@ Only use those runtime tools for live state. Never invent runtime tools.` : "";
 - You may only read or edit files inside the current project workspace directory.
 - Never read, write, move, or delete files outside that workspace.
 - Never touch paths that match this ignore list (relative to the workspace):
-${input.ignorePaths.length ? input.ignorePaths.map((p) => `- ${p}`).join("\n") : "- (none beyond staying inside the workspace)"}
+${(input.ignorePaths ?? []).filter((p) => !p.startsWith("!")).length ? (input.ignorePaths ?? []).filter((p) => !p.startsWith("!")).map((p) => `- ${p}`).join("\n") : "- (none beyond staying inside the workspace)"}
 - If a request requires something outside the workspace or on the ignore list, refuse that part and explain you can only change allowed project files.` : "";
   return `You are a helpful product assistant for an app the user is looking at right now.
 
@@ -654,10 +655,11 @@ function isPathAllowed(workspaceDir, targetPath, ignorePaths) {
   return !isIgnoredRelative(rel, ignorePaths);
 }
 function formatAccessPolicyPromptSection(input) {
-  const ignores = input.ignorePaths.length ? input.ignorePaths.map((p) => `- ${p}`).join("\n") : "- (none beyond staying inside the workspace)";
+  const ignores = input.ignorePaths.filter((p) => !p.startsWith("!")).length ? input.ignorePaths.filter((p) => !p.startsWith("!")).map((p) => `- ${p}`).join("\n") : "- (none beyond staying inside the workspace)";
   return `## File access boundaries (mandatory)
 - You may only read or edit files inside the current project workspace directory.
-- Never read, write, move, or delete files outside that workspace.
+- Never write, move, or delete files outside that workspace.
+- You may read screenshot files listed in the attachments section (those live in the Maintainer Pro data folder, not in the project).
 - Never touch paths that match this ignore list (relative to the workspace):
 ${ignores}
 - If a request requires something outside the workspace or on the ignore list, refuse that part and explain you can only change allowed project files.`;
@@ -741,13 +743,73 @@ function previewText(text, max = 160) {
 }
 
 // src/http/attachments.ts
-import fs2 from "fs/promises";
+import fs3 from "fs/promises";
+import path4 from "path";
+
+// src/project-data.ts
+import { createHash } from "crypto";
+import fs2 from "fs";
+import os from "os";
 import path3 from "path";
+var MAINTAINER_PRO_HOME_DIR = ".maintainer-pro";
+var HOST_APPS_FILE = "apps.json";
+function maintainerProHome() {
+  const override = process.env.MAINTAINER_PRO_HOME?.trim();
+  if (override) return path3.resolve(override);
+  return path3.join(os.homedir(), MAINTAINER_PRO_HOME_DIR);
+}
+function projectIdForFolder(folder) {
+  const resolved = path3.resolve(folder || "");
+  const key = process.platform === "win32" ? resolved.toLowerCase() : resolved;
+  return createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+function sanitizeProjectId(id) {
+  return String(id || "").trim().replace(/[^\w.-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 80);
+}
+function resolveProjectDataDir(input) {
+  const override = String(input.dataDir || "").trim();
+  if (override) return path3.resolve(override);
+  const sandbox = sanitizeProjectId(String(input.sandboxId || ""));
+  const id = sandbox || projectIdForFolder(input.workspaceDir);
+  return path3.join(maintainerProHome(), "projects", id);
+}
+function projectUploadsDir(input) {
+  return path3.join(resolveProjectDataDir(input), "uploads");
+}
+function hostAppsCachePath(input) {
+  return path3.join(resolveProjectDataDir(input), HOST_APPS_FILE);
+}
+function ensureProjectDataDir(input) {
+  const dir = resolveProjectDataDir(input);
+  fs2.mkdirSync(dir, { recursive: true });
+  fs2.mkdirSync(path3.join(dir, "uploads"), { recursive: true });
+  try {
+    fs2.writeFileSync(
+      path3.join(dir, "workspace.json"),
+      `${JSON.stringify(
+        {
+          workspaceDir: path3.resolve(input.workspaceDir || ""),
+          sandboxId: input.sandboxId ? String(input.sandboxId) : null,
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        null,
+        2
+      )}
+`,
+      "utf8"
+    );
+  } catch {
+  }
+  return dir;
+}
+
+// src/http/attachments.ts
 var MAX_ATTACHMENTS = 5;
 var MAX_BYTES = 4 * 1024 * 1024;
 var ALLOWED = /* @__PURE__ */ new Set(["image/png", "image/jpeg", "image/jpg", "image/webp", "image/gif"]);
 function extForMime(mime) {
-  switch (mime) {
+  const normalized = mime.split(";")[0]?.trim().toLowerCase() || "";
+  switch (normalized) {
     case "image/jpeg":
     case "image/jpg":
       return ".jpg";
@@ -759,11 +821,31 @@ function extForMime(mime) {
       return ".png";
   }
 }
-async function saveChatAttachments(attachments, workspaceDir) {
+function attachmentIdFromRef(ref) {
+  const trimmed = String(ref || "").trim();
+  if (!trimmed) return null;
+  const m = /^maintainer-pro:\/\/(.+)$/i.exec(trimmed);
+  if (m?.[1]) return m[1];
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+    trimmed
+  )) {
+    return trimmed;
+  }
+  return null;
+}
+function uploadsRoot(input) {
+  ensureProjectDataDir(input);
+  return projectUploadsDir(input);
+}
+async function saveChatAttachments(attachments, workspaceDir, extra) {
   if (!attachments?.length) return [];
   const selected = attachments.slice(0, MAX_ATTACHMENTS);
-  const dir = path3.join(workspaceDir, ".maintainer-pro", "uploads");
-  await fs2.mkdir(dir, { recursive: true });
+  const loc = {
+    workspaceDir,
+    dataDir: extra?.dataDir,
+    sandboxId: extra?.sandboxId
+  };
+  const dir = uploadsRoot(loc);
   const paths = [];
   const stamp = Date.now();
   for (let i = 0; i < selected.length; i++) {
@@ -781,11 +863,11 @@ async function saveChatAttachments(attachments, workspaceDir) {
     }
     const safeBase = (item.name || `screenshot-${i + 1}`).replace(/[^\w.\-]+/g, "_").slice(0, 64);
     const fileName = `${stamp}-${i + 1}-${safeBase}${extForMime(mime)}`;
-    const filePath = path3.resolve(dir, fileName);
-    if (!isInsideWorkspace(workspaceDir, filePath)) {
-      throw new Error("Attachment path escaped the project workspace");
+    const filePath = path4.resolve(dir, fileName);
+    if (!isInsideWorkspace(dir, filePath)) {
+      throw new Error("Attachment path escaped the project data folder");
     }
-    await fs2.writeFile(filePath, buffer);
+    await fs3.writeFile(filePath, buffer);
     paths.push(filePath);
   }
   return paths;
@@ -936,6 +1018,8 @@ function createChatHandler(options) {
   const logger = options.logger ?? createLogger("ai-cli:chat");
   const validate = options.tools ? createToolValidator(options.tools) : null;
   const workspaceDir = options.workspaceDir ?? process.env.AI_CLI_WORKSPACE ?? process.cwd();
+  const dataDir = options.dataDir;
+  const sandboxId = options.sandboxId;
   const baseCallOptions = {
     systemPrompt: options.systemPrompt,
     workspaceDir,
@@ -1092,20 +1176,37 @@ function createChatHandler(options) {
         }
         let attachmentPaths = [];
         let persistAttachmentPaths = [];
-        if (options.db?.uploadAttachments) {
+        if (options.db?.uploadAttachments && attachments?.length) {
           const uploaded = await options.db.uploadAttachments(
             conversationId,
             attachments
           );
           attachmentPaths = uploaded.localPaths;
           persistAttachmentPaths = uploaded.refs;
-        } else {
+        } else if (attachments?.length) {
           attachmentPaths = await saveChatAttachments(
             attachments,
-            workspaceDir
+            workspaceDir,
+            { dataDir, sandboxId }
           );
           persistAttachmentPaths = attachmentPaths;
         }
+        const storedUserId = typeof body.userMessageId === "string" && body.userMessageId ? body.userMessageId : void 0;
+        if (!attachmentPaths.length && conversationId && options.db?.materializeMessageAttachments) {
+          attachmentPaths = await options.db.materializeMessageAttachments(
+            conversationId,
+            storedUserId,
+            workspaceDir
+          );
+        }
+        logger.debug(
+          {
+            conversationId,
+            userMessageId: storedUserId,
+            attachmentCount: attachmentPaths.length
+          },
+          "cli attachments"
+        );
         const turn = beginConversationTurn(conversationId ?? SHARED_CONVERSATION_ID);
         trackedTurn = turn;
         const signal = request.signal;
@@ -1200,6 +1301,7 @@ function createChatHandler(options) {
             turn,
             parentUserMessageId,
             historyLength: messages.length,
+            attachmentCount: attachmentPaths.length,
             hasParentChain: Boolean(parentChainContext),
             preview: previewText(
               [...messages].reverse().find((m) => m.role === "user")?.content
@@ -1358,8 +1460,8 @@ function toNextRoute(handlers) {
 }
 
 // src/http/local-store.ts
-import fs3 from "fs/promises";
-import path4 from "path";
+import fs4 from "fs/promises";
+import path5 from "path";
 import { randomUUID as randomUUID2 } from "crypto";
 function userHasAiReply(rows, workingId) {
   return rows.some(
@@ -1368,7 +1470,7 @@ function userHasAiReply(rows, workingId) {
 }
 async function readConversation(filePath) {
   try {
-    const raw = await fs3.readFile(filePath, "utf8");
+    const raw = await fs4.readFile(filePath, "utf8");
     return JSON.parse(raw);
   } catch (err) {
     if (err.code === "ENOENT") return null;
@@ -1376,11 +1478,11 @@ async function readConversation(filePath) {
   }
 }
 async function writeConversation(filePath, data) {
-  await fs3.mkdir(path4.dirname(filePath), { recursive: true });
-  await fs3.writeFile(filePath, JSON.stringify(data, null, 2), "utf8");
+  await fs4.mkdir(path5.dirname(filePath), { recursive: true });
+  await fs4.writeFile(filePath, JSON.stringify(data, null, 2), "utf8");
 }
 function createLocalDirectoryStore(baseDir) {
-  const fileFor = (id) => path4.join(baseDir, `${id}.json`);
+  const fileFor = (id) => path5.join(baseDir, `${id}.json`);
   return {
     async ensureConversation(id) {
       const existing = await readConversation(fileFor(id));
@@ -1681,12 +1783,12 @@ function createLocalDirectoryStore(baseDir) {
       return existing?.messages ?? [];
     },
     async listConversations() {
-      await fs3.mkdir(baseDir, { recursive: true });
-      const entries = await fs3.readdir(baseDir);
+      await fs4.mkdir(baseDir, { recursive: true });
+      const entries = await fs4.readdir(baseDir);
       const conversations = [];
       for (const entry of entries) {
         if (!entry.endsWith(".json")) continue;
-        const filePath = path4.join(baseDir, entry);
+        const filePath = path5.join(baseDir, entry);
         const existing = await readConversation(filePath);
         if (!existing?.id) continue;
         conversations.push({
@@ -1703,7 +1805,7 @@ function createLocalDirectoryStore(baseDir) {
       if (events.length === 0) return;
       const existing = await readConversation(fileFor(conversationId));
       if (!existing) return;
-      const toolFile = path4.join(baseDir, `${conversationId}.tools.jsonl`);
+      const toolFile = path5.join(baseDir, `${conversationId}.tools.jsonl`);
       const lines = events.map(
         (e) => JSON.stringify({
           conversationId,
@@ -1711,16 +1813,15 @@ function createLocalDirectoryStore(baseDir) {
           createdAt: (/* @__PURE__ */ new Date()).toISOString()
         })
       ).join("\n");
-      await fs3.appendFile(toolFile, `${lines}
+      await fs4.appendFile(toolFile, `${lines}
 `, "utf8");
     }
   };
 }
 
 // src/http/maintainer-pro-store.ts
-import fs4 from "fs/promises";
-import os from "os";
-import path5 from "path";
+import fs5 from "fs/promises";
+import path6 from "path";
 
 // src/http/synced-store.ts
 function userHasAiReply2(rows, workingId) {
@@ -1747,7 +1848,7 @@ function asCachedMessage(raw) {
     content: typeof raw.content === "string" ? raw.content : "",
     provider: typeof raw.provider === "string" ? raw.provider : null,
     createdAt: typeof raw.createdAt === "string" ? raw.createdAt : void 0,
-    attachmentPaths: Array.isArray(raw.attachmentPaths) ? raw.attachmentPaths.filter((p) => typeof p === "string") : void 0,
+    attachmentPaths: Array.isArray(raw.attachmentPaths) ? raw.attachmentPaths.filter((p) => typeof p === "string") : Array.isArray(raw.attachmentIds) ? raw.attachmentIds.filter((id2) => typeof id2 === "string").map((id2) => `maintainer-pro://${id2}`) : void 0,
     senderType: raw.senderType === "client" || raw.senderType === "developer" || raw.senderType === "ai" ? raw.senderType : null,
     senderName: typeof raw.senderName === "string" ? raw.senderName : null,
     parentMessageId: typeof raw.parentMessageId === "string" ? raw.parentMessageId : null,
@@ -2061,6 +2162,14 @@ function createSyncedChatStore(options) {
         return { refs: [], localPaths: [] };
       }
       return remote.uploadAttachments(conversationId, attachments);
+    },
+    async materializeMessageAttachments(conversationId, messageId, workspaceDir) {
+      if (!remote.materializeMessageAttachments) return [];
+      return remote.materializeMessageAttachments(
+        conversationId,
+        messageId,
+        workspaceDir
+      );
     }
   };
   return store;
@@ -2093,7 +2202,8 @@ function createMaintainerProStore(options) {
   const baseUrl = options.baseUrl;
   const apiKey = options.apiKey;
   const fetchImpl = options.fetchImpl ?? fetch;
-  const tempDir = options.tempDir ?? path5.join(os.tmpdir(), "maintainer-pro-store");
+  const logger = options.logger;
+  const tempDir = options.tempDir ?? projectUploadsDir({ workspaceDir: process.cwd() });
   const store = {
     async ensureConversation(id) {
       await mpFetch(
@@ -2221,7 +2331,7 @@ function createMaintainerProStore(options) {
       if (!attachments?.length) {
         return { refs: [], localPaths: [], attachmentIds: [] };
       }
-      await fs4.mkdir(tempDir, { recursive: true });
+      await fs5.mkdir(tempDir, { recursive: true });
       const refs = [];
       const localPaths = [];
       const attachmentIds = [];
@@ -2244,15 +2354,89 @@ function createMaintainerProStore(options) {
         const id = data.attachment.id;
         attachmentIds.push(id);
         refs.push(data.attachment.ref || `maintainer-pro://${id}`);
-        const ext = item.mimeType.includes("jpeg") || item.mimeType.includes("jpg") ? ".jpg" : item.mimeType.includes("webp") ? ".webp" : item.mimeType.includes("gif") ? ".gif" : ".png";
-        const localPath = path5.join(
+        const localPath = path6.join(
           tempDir,
-          `${conversationId}-${id}${ext}`
+          `${conversationId}-${id}${extForMime(item.mimeType)}`
         );
-        await fs4.writeFile(localPath, Buffer.from(item.data, "base64"));
+        await fs5.mkdir(path6.dirname(localPath), { recursive: true });
+        await fs5.writeFile(localPath, Buffer.from(item.data, "base64"));
         localPaths.push(localPath);
       }
       return { refs, localPaths, attachmentIds };
+    },
+    async materializeMessageAttachments(conversationId, messageId, workspaceDir) {
+      if (!conversationId || !workspaceDir) return [];
+      const data = await mpFetch(
+        baseUrl,
+        apiKey,
+        `/api/v1/store/conversations/${encodeURIComponent(conversationId)}/messages`,
+        { method: "GET" },
+        fetchImpl
+      );
+      const messages = data.messages ?? [];
+      const byId = new Map(messages.map((row) => [row.id, row]));
+      const refs = [];
+      const fromMessageIds = [];
+      const seenMsg = /* @__PURE__ */ new Set();
+      const pushRow = (row) => {
+        if (!row || seenMsg.has(row.id)) return;
+        seenMsg.add(row.id);
+        const before = refs.length;
+        refs.push(...row.attachmentPaths ?? []);
+        refs.push(
+          ...(row.attachmentIds ?? []).map((id) => `maintainer-pro://${id}`)
+        );
+        if (refs.length > before) fromMessageIds.push(row.id);
+      };
+      let current = messageId ? byId.get(messageId) : void 0;
+      while (current && !seenMsg.has(current.id)) {
+        pushRow(current);
+        const parentId = current.parentMessageId?.trim();
+        current = parentId ? byId.get(parentId) : void 0;
+      }
+      for (const row of messages) {
+        if (row.role && row.role !== "user") continue;
+        pushRow(row);
+      }
+      const seen = /* @__PURE__ */ new Set();
+      const ids = [];
+      for (const ref of refs) {
+        const id = attachmentIdFromRef(ref);
+        if (!id || seen.has(id)) continue;
+        seen.add(id);
+        ids.push(id);
+      }
+      const localPaths = [];
+      for (const id of ids.slice(0, 5)) {
+        const url = `${baseUrl.replace(/\/$/, "")}/api/v1/store/attachments/${encodeURIComponent(id)}`;
+        const res = await fetchImpl(url, {
+          headers: { Authorization: `Bearer ${apiKey}` }
+        });
+        if (!res.ok) {
+          continue;
+        }
+        const mime = res.headers.get("content-type") || "image/png";
+        const buffer = Buffer.from(await res.arrayBuffer());
+        if (!buffer.byteLength) continue;
+        const localPath = path6.join(
+          tempDir,
+          `${id}${extForMime(mime)}`
+        );
+        await fs5.mkdir(tempDir, { recursive: true });
+        await fs5.writeFile(localPath, buffer);
+        localPaths.push(localPath);
+      }
+      logger?.debug(
+        {
+          conversationId,
+          messageId,
+          fromMessageIds,
+          stored: ids.length,
+          written: localPaths.length
+        },
+        "materialize attachments"
+      );
+      return localPaths;
     }
   };
   if (options.sync === false) {
@@ -2278,6 +2462,11 @@ function createMaintainerProStoreFromEnv(options) {
   return createMaintainerProStore({
     baseUrl,
     apiKey,
+    tempDir: projectUploadsDir({
+      workspaceDir: process.env.AI_CLI_WORKSPACE || process.cwd(),
+      sandboxId: process.env.MAINTAINER_PRO_SANDBOX_ID,
+      dataDir: process.env.MAINTAINER_PRO_DATA_DIR
+    }),
     logger: options?.logger,
     log: options?.log,
     sync: options?.sync,
@@ -2286,7 +2475,10 @@ function createMaintainerProStoreFromEnv(options) {
 }
 
 // src/workspace-inspect.ts
+import fs6 from "fs";
+import path7 from "path";
 import { z } from "zod";
+var CONFIG_INSPECT_TIMEOUT_MS = 18e3;
 var inspectJsonSchema = z.object({
   kind: z.enum(["next", "vite", "html", "empty", "other"]).optional(),
   name: z.string().max(200).optional(),
@@ -2356,6 +2548,154 @@ ${input.extraContext ? `${input.extraContext.trim()}
 
 ` : ""}Inspect this project, fix any setup gaps you can, and return the JSON report.`;
 }
+function readSnippet(file, max = 4e3) {
+  try {
+    const text = fs6.readFileSync(file, "utf8");
+    return text.length > max ? `${text.slice(0, max)}
+\u2026` : text;
+  } catch {
+    return null;
+  }
+}
+function envKeysOnly(file) {
+  try {
+    const keys = fs6.readFileSync(file, "utf8").split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("#") && line.includes("=")).map((line) => line.slice(0, line.indexOf("=")).trim()).filter(Boolean);
+    return keys.length ? keys.join("\n") : null;
+  } catch {
+    return null;
+  }
+}
+function gatherConfigSnippets(workspaceDir) {
+  const folder = path7.resolve(workspaceDir);
+  const parts = [];
+  const pkg = readSnippet(path7.join(folder, "package.json"));
+  if (pkg) parts.push(`### package.json
+\`\`\`json
+${pkg}
+\`\`\``);
+  for (const lock of [
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lockb"
+  ]) {
+    if (fs6.existsSync(path7.join(folder, lock))) {
+      parts.push(`### lockfile
+${lock}`);
+      break;
+    }
+  }
+  for (const rel of [
+    "vite.config.ts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "next.config.js",
+    "next.config.mjs",
+    "next.config.ts"
+  ]) {
+    const body = readSnippet(path7.join(folder, rel), 2500);
+    if (body) parts.push(`### ${rel}
+\`\`\`
+${body}
+\`\`\``);
+  }
+  for (const rel of [".env.example", ".env", ".env.local", ".env.development"]) {
+    const keys = envKeysOnly(path7.join(folder, rel));
+    if (keys) parts.push(`### ${rel} keys (values omitted)
+\`\`\`
+${keys}
+\`\`\``);
+  }
+  return parts.join("\n\n") || "(no config files found)";
+}
+function configOnlySystemPrompt(input) {
+  return `You are Maintainer Pro's read-only setup advisor.
+
+Workspace: ${input.workspaceDir}
+App name: ${input.appName || "the app"}
+
+You are given configuration file excerpts only.
+DO NOT edit, create, or delete any files.
+DO NOT run shell commands, install packages, or start servers.
+Only infer how this project runs locally from the excerpts.
+
+Script names you report MUST appear in package.json scripts. Omit chat/ai-server scripts.
+
+Reply with a short human summary AND one \`\`\`json fence with:
+
+{
+  "kind": "next" | "vite" | "html" | "empty" | "other",
+  "name": "package or folder name",
+  "summary": "one sentence about this project",
+  "scripts": { "ui": "dev:client", "backend": "dev:server" },
+  "ports": { "ui": 5173, "backend": 4100 },
+  "issues": ["uncertainties"],
+  "fixes": [],
+  "ready": true
+}`;
+}
+function configOnlyUserMessage(input, snippets) {
+  return `${input.extraContext ? `${input.extraContext.trim()}
+
+` : ""}Analyze these config excerpts and suggest local apps/ports/scripts. Do not change anything on disk.
+
+${snippets}`;
+}
+function toInspectResult(input, text, providerId) {
+  const parsed = extractInspectJson(text);
+  return {
+    kind: parsed?.kind ?? "other",
+    name: parsed?.name?.trim() || input.appName || "",
+    summary: parsed?.summary?.trim() || text.replace(/```json[\s\S]*```/i, "").trim().slice(0, 400),
+    scripts: parsed?.scripts ?? {},
+    ports: parsed?.ports ?? {},
+    issues: parsed?.issues ?? [],
+    fixes: parsed?.fixes ?? [],
+    ready: parsed?.ready ?? parsed?.issues?.length === 0,
+    provider: providerId,
+    rawText: text
+  };
+}
+async function inspectConfigOnly(input, opts = {}) {
+  const workspaceDir = path7.resolve(input.workspaceDir);
+  const timeoutMs = opts.timeoutMs ?? CONFIG_INSPECT_TIMEOUT_MS;
+  const provider = await resolveProvider({ preference: "auto" });
+  const snippets = gatherConfigSnippets(workspaceDir);
+  const call = callAi(
+    [{ role: "user", content: configOnlyUserMessage(input, snippets) }],
+    {
+      route: "/local-setup-propose",
+      pageTitle: input.appName || "Setup suggestions",
+      relevantFiles: ["package.json", ".env.example"],
+      data: {
+        workspaceDir,
+        readOnly: true
+      }
+    },
+    {
+      systemPrompt: configOnlySystemPrompt(input),
+      workspaceDir,
+      technical: true
+    }
+  );
+  const timed = await Promise.race([
+    call.then((response) => ({ ok: true, response })),
+    new Promise(
+      (resolve) => setTimeout(
+        () => resolve({ ok: false, error: `Config inspect timed out after ${timeoutMs}ms` }),
+        timeoutMs
+      )
+    )
+  ]);
+  if (!timed.ok) {
+    throw new Error(timed.error);
+  }
+  return toInspectResult(
+    input,
+    timed.response.text,
+    timed.response.provider || provider.id
+  );
+}
 async function inspectAndRepairWorkspace(input) {
   const workspaceDir = input.workspaceDir;
   const provider = await resolveProvider({ preference: "auto" });
@@ -2376,24 +2716,670 @@ async function inspectAndRepairWorkspace(input) {
       technical: true
     }
   );
-  const parsed = extractInspectJson(response.text);
+  return toInspectResult(
+    input,
+    response.text,
+    response.provider || provider.id
+  );
+}
+
+// src/host-apps.ts
+import fs7 from "fs";
+import path8 from "path";
+import { createHash as createHash2 } from "crypto";
+var COLLABORATER_DIR = ".collaborater";
+var AI_SERVER_APP_ID = "ai-server";
+var AI_SERVER_DEFAULT_PORT = 3100;
+var ENV_FILES = [".env", ".env.local", ".env.development", ".env.example"];
+function isPort(value) {
+  return Number.isInteger(value) && Number(value) >= 1024 && Number(value) <= 65535;
+}
+function parsePort(value, fallback = 0) {
+  if (typeof value === "number" && isPort(value)) return value;
+  const text = String(value ?? "").trim();
+  if (!text) return fallback;
+  if (/^\d{2,5}$/.test(text)) {
+    const n = Number(text);
+    return isPort(n) ? n : fallback;
+  }
+  try {
+    const port = Number(new URL(text).port);
+    return isPort(port) ? port : fallback;
+  } catch {
+    const match = text.match(/--port(?:\s+|=)(\d{2,5})/i) || text.match(/\bPORT[=:]\s*(\d{2,5})/i) || text.match(/:(\d{2,5})\b/);
+    const n = match ? Number(match[1]) : 0;
+    return isPort(n) ? n : fallback;
+  }
+}
+function dataInput(folder, extra) {
   return {
-    kind: parsed?.kind ?? "other",
-    name: parsed?.name?.trim() || input.appName || "",
-    summary: parsed?.summary?.trim() || response.text.replace(/```json[\s\S]*```/i, "").trim().slice(0, 400),
-    scripts: parsed?.scripts ?? {},
-    ports: parsed?.ports ?? {},
-    issues: parsed?.issues ?? [],
-    fixes: parsed?.fixes ?? [],
-    ready: parsed?.ready ?? parsed?.issues?.length === 0,
-    provider: response.provider || provider.id,
-    rawText: response.text
+    workspaceDir: folder,
+    sandboxId: extra?.sandboxId,
+    dataDir: extra?.dataDir
+  };
+}
+function hostAppsCachePath2(folder, extra) {
+  return hostAppsCachePath(dataInput(folder, extra));
+}
+function defaultAiServerApp(port = AI_SERVER_DEFAULT_PORT) {
+  return {
+    id: AI_SERVER_APP_ID,
+    name: "AI server",
+    role: "ai-server",
+    port: parsePort(port, AI_SERVER_DEFAULT_PORT),
+    startCommand: null,
+    source: "default",
+    locked: true
+  };
+}
+function normalizeHostApp(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const row = raw;
+  const port = parsePort(row.port);
+  if (!port) return null;
+  const role = String(row.role || "custom");
+  const allowed = ["ai-server", "ui", "backend", "app", "custom"];
+  const id = String(row.id || "").trim() || (role === "ai-server" ? AI_SERVER_APP_ID : "");
+  if (!id) return null;
+  return {
+    id: id.slice(0, 64),
+    name: String(row.name || id).trim().slice(0, 80) || id,
+    role: allowed.includes(role) ? role : "custom",
+    port,
+    startCommand: typeof row.startCommand === "string" && row.startCommand.trim() ? row.startCommand.trim().slice(0, 200) : null,
+    source: ["default", "env", "package", "ai", "manual"].includes(
+      row.source
+    ) ? row.source : "manual",
+    locked: row.locked === true || id === AI_SERVER_APP_ID || role === "ai-server",
+    host: role !== "ai-server" && id !== AI_SERVER_APP_ID && row.host === true,
+    envMaps: normalizeEnvMaps(row.envMaps)
+  };
+}
+function normalizeEnvMaps(raw) {
+  if (!Array.isArray(raw)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const row = item;
+    const key = String(row.key || "").trim();
+    const sourceAppId = String(row.sourceAppId || "").trim().slice(0, 64);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || key.length > 80) continue;
+    if (!sourceAppId || seen.has(key)) continue;
+    seen.add(key);
+    out.push({ key, sourceAppId });
+  }
+  return out.slice(0, 30);
+}
+function ensureSingleHost(apps) {
+  const next = apps.map((app) => ({
+    ...app,
+    host: app.role !== "ai-server" && app.id !== AI_SERVER_APP_ID && app.host === true
+  }));
+  const marked = next.filter((app) => app.host);
+  if (marked.length === 1) return next;
+  if (marked.length > 1) {
+    let kept = false;
+    return next.map((app) => {
+      if (!app.host) return app;
+      if (kept) return { ...app, host: false };
+      kept = true;
+      return app;
+    });
+  }
+  const fallback = next.find((app) => app.role === "ui" || app.role === "app") || next.find((app) => app.role !== "ai-server");
+  return next.map(
+    (app) => fallback && app.id === fallback.id ? { ...app, host: true } : app
+  );
+}
+function normalizeHostApps(raw) {
+  if (!Array.isArray(raw)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const apps = [];
+  for (const item of raw) {
+    const app = normalizeHostApp(item);
+    if (!app || seen.has(app.id)) continue;
+    seen.add(app.id);
+    apps.push(app);
+  }
+  return apps;
+}
+function ensureAiServerApp(apps, preferredPort = AI_SERVER_DEFAULT_PORT) {
+  const next = normalizeHostApps(apps);
+  const existing = next.find((app) => app.id === AI_SERVER_APP_ID || app.role === "ai-server");
+  if (existing) {
+    existing.id = AI_SERVER_APP_ID;
+    existing.role = "ai-server";
+    existing.locked = true;
+    existing.host = false;
+    existing.name = existing.name || "AI server";
+    return ensureSingleHost([existing, ...next.filter((app) => app !== existing)]);
+  }
+  return ensureSingleHost([defaultAiServerApp(preferredPort), ...next]);
+}
+function readText(file) {
+  try {
+    return fs7.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+function readEnvFileMap(file) {
+  const text = readText(file);
+  if (!text) return {};
+  const map = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    if (key) map[key] = value;
+  }
+  return map;
+}
+function readProjectEnvLayers(folder) {
+  const resolved = path8.resolve(folder);
+  const layers = [];
+  const merged = {};
+  for (const name of ENV_FILES) {
+    const file = path8.join(resolved, name);
+    const values = readEnvFileMap(file);
+    if (!Object.keys(values).length) continue;
+    layers.push({ file: name, values });
+    if (name === ".env.example") continue;
+    Object.assign(merged, values);
+  }
+  return { merged, layers };
+}
+function readPackageJson(folder) {
+  try {
+    return JSON.parse(fs7.readFileSync(path8.join(folder, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isChatScript(name, command) {
+  return /\b(ai-server|ai-cli|dev:chat|start:chat)\b/i.test(`${name} ${command}`);
+}
+function isUiCommand(command) {
+  return /\b(vite|next|nuxt|astro|remix|react-scripts|webpack-dev-server|parcel)\b/i.test(
+    command
+  );
+}
+function configPort(folder, files) {
+  for (const rel of files) {
+    const text = readText(path8.join(folder, rel));
+    if (!text) continue;
+    const match = text.match(/\bport\s*[:=]\s*(\d{2,5})/i) || text.match(/--port(?:\s+|=)(\d{2,5})/i);
+    const port = parsePort(match?.[1]);
+    if (port) return port;
+  }
+  return 0;
+}
+function hostAppsFingerprint(folder) {
+  const resolved = path8.resolve(folder);
+  const parts = [];
+  for (const rel of [
+    "package.json",
+    ...ENV_FILES,
+    "vite.config.ts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "next.config.js",
+    "next.config.mjs",
+    "next.config.ts"
+  ]) {
+    const file = path8.join(resolved, rel);
+    if (!fs7.existsSync(file)) continue;
+    try {
+      const st = fs7.statSync(file);
+      parts.push(`${rel}:${st.size}:${Math.floor(st.mtimeMs)}`);
+    } catch {
+    }
+  }
+  return createHash2("sha256").update(parts.join("|") || resolved).digest("hex").slice(0, 32);
+}
+function pickScript(scripts, names) {
+  return names.find((name) => scripts[name] && !isChatScript(name, scripts[name])) || null;
+}
+function detectHostAppsFromFiles(folder, opts = {}) {
+  const resolved = path8.resolve(folder);
+  const reasons = [];
+  const { merged, layers } = readProjectEnvLayers(resolved);
+  const pkg = readPackageJson(resolved);
+  const scripts = pkg?.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+  const apps = [];
+  const envAi = parsePort(merged.AI_SERVER_PORT) || parsePort(merged.AI_SERVER_URL);
+  const aiPort = envAi || parsePort(opts.preferredAiPort, AI_SERVER_DEFAULT_PORT);
+  apps.push({
+    ...defaultAiServerApp(aiPort),
+    source: envAi ? "env" : "default"
+  });
+  const envPorts = {
+    PORT: layers.filter((layer) => layer.file !== ".env.example").map((layer) => ({ file: layer.file, port: parsePort(layer.values.PORT) })).filter((row) => row.port),
+    APP_URL: parsePort(merged.APP_URL || merged.NEXT_PUBLIC_APP_URL || merged.PUBLIC_URL),
+    API_PORT: parsePort(merged.API_PORT || merged.API_URL || merged.VITE_API_URL)
+  };
+  const portValues = [...new Set(envPorts.PORT.map((row) => row.port))];
+  if (portValues.length > 1) {
+    reasons.push(
+      `PORT differs across env files: ${envPorts.PORT.map((row) => `${row.file}=${row.port}`).join(", ")}`
+    );
+  }
+  if (envPorts.PORT[0] && envPorts.APP_URL && envPorts.PORT[0].port !== envPorts.APP_URL) {
+    reasons.push(
+      `PORT=${envPorts.PORT[0].port} does not match APP_URL port ${envPorts.APP_URL}`
+    );
+  }
+  const uiScript = pickScript(scripts, [
+    "dev:client",
+    "dev:ui",
+    "dev:web",
+    "dev:frontend",
+    "client",
+    "start:client"
+  ]) || (scripts.dev && !isChatScript("dev", scripts.dev) ? "dev" : null);
+  const apiScript = pickScript(scripts, [
+    "dev:server",
+    "dev:backend",
+    "dev:api",
+    "server",
+    "start:server"
+  ]);
+  const vitePort = configPort(resolved, ["vite.config.ts", "vite.config.js", "vite.config.mjs"]) || 5173;
+  const nextPort = configPort(resolved, ["next.config.js", "next.config.mjs", "next.config.ts"]) || 3e3;
+  const portFromEnv = parsePort(merged.PORT);
+  const hostFromEnv = parsePort(merged.HOST_PORT) || parsePort(merged.HOST_URL) || parsePort(merged.CORS_ORIGIN);
+  const uiFromEnv = hostFromEnv || envPorts.APP_URL || (portFromEnv && portFromEnv !== aiPort ? portFromEnv : 0);
+  if (uiScript) {
+    const command = scripts[uiScript] || "";
+    const scriptPort = parsePort(command);
+    const fallback = isUiCommand(command) && /vite/i.test(command) ? vitePort : nextPort;
+    const port = uiFromEnv || scriptPort || fallback;
+    apps.push({
+      id: "ui",
+      name: opts.appName || pkg?.name || "App",
+      role: isUiCommand(command) ? "ui" : "app",
+      port,
+      startCommand: `npm run ${uiScript}`,
+      source: uiFromEnv ? "env" : scriptPort ? "package" : "package",
+      host: true
+    });
+  } else if (uiFromEnv) {
+    apps.push({
+      id: "ui",
+      name: opts.appName || pkg?.name || "App",
+      role: "ui",
+      port: uiFromEnv,
+      startCommand: scripts.dev ? "npm run dev" : null,
+      source: "env",
+      host: true
+    });
+  }
+  if (apiScript && apiScript !== uiScript) {
+    const command = scripts[apiScript] || "";
+    const port = envPorts.API_PORT || parsePort(command) || configPort(resolved, []) || 4100;
+    apps.push({
+      id: "backend",
+      name: "Backend",
+      role: "backend",
+      port,
+      startCommand: `npm run ${apiScript}`,
+      source: envPorts.API_PORT ? "env" : "package"
+    });
+  }
+  const hostApps = apps.filter((app) => app.role !== "ai-server");
+  if (pkg && Object.keys(scripts).length && hostApps.length === 0) {
+    reasons.push("Found package.json scripts but no host app port in env or config");
+  }
+  return {
+    apps: ensureAiServerApp(apps, aiPort),
+    reasons,
+    confused: reasons.length > 0
+  };
+}
+function readHostAppsCache(folder, extra) {
+  try {
+    const raw = JSON.parse(
+      fs7.readFileSync(hostAppsCachePath2(folder, extra), "utf8")
+    );
+    const apps = ensureAiServerApp(normalizeHostApps(raw.apps));
+    if (!apps.length) return null;
+    return {
+      apps,
+      fingerprint: typeof raw.fingerprint === "string" ? raw.fingerprint : void 0,
+      updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : void 0
+    };
+  } catch {
+    return null;
+  }
+}
+var readCollaboraterApps = readHostAppsCache;
+function writeHostAppsCache(folder, apps, extra = {}, loc) {
+  const resolved = path8.resolve(folder);
+  ensureProjectDataDir(dataInput(resolved, loc));
+  const payload = {
+    version: 1,
+    fingerprint: hostAppsFingerprint(resolved),
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    apps: ensureAiServerApp(apps),
+    ...extra
+  };
+  fs7.writeFileSync(
+    hostAppsCachePath2(resolved, loc),
+    `${JSON.stringify(payload, null, 2)}
+`,
+    "utf8"
+  );
+}
+var writeCollaboraterApps = writeHostAppsCache;
+function mergeDesiredHostApps(desired, detected) {
+  const byId = new Map(detected.map((app) => [app.id, app]));
+  const byRole = new Map(detected.map((app) => [app.role, app]));
+  const merged = desired.map((app) => {
+    const local = byId.get(app.id) || (app.role !== "custom" ? byRole.get(app.role) : void 0);
+    return {
+      ...local,
+      ...app,
+      startCommand: app.startCommand || local?.startCommand || null,
+      locked: app.locked || app.id === AI_SERVER_APP_ID || app.role === "ai-server",
+      host: app.role === "ai-server" || app.id === AI_SERVER_APP_ID ? false : app.host === true || app.host !== false && local?.host === true,
+      envMaps: app.envMaps && app.envMaps.length ? app.envMaps : local?.envMaps || []
+    };
+  });
+  return ensureAiServerApp(merged);
+}
+function appsFromInspectPorts(ports, scripts, name) {
+  const apps = [];
+  if (ports.ui || scripts.ui) {
+    apps.push({
+      id: "ui",
+      name,
+      role: "ui",
+      port: parsePort(ports.ui, 5173),
+      startCommand: scripts.ui ? `npm run ${scripts.ui}` : null,
+      source: "ai"
+    });
+  }
+  if (ports.backend || scripts.backend) {
+    apps.push({
+      id: "backend",
+      name: "Backend",
+      role: "backend",
+      port: parsePort(ports.backend, 4100),
+      startCommand: scripts.backend ? `npm run ${scripts.backend}` : null,
+      source: "ai"
+    });
+  }
+  if (!apps.length && (ports.app || scripts.app)) {
+    apps.push({
+      id: "app",
+      name,
+      role: "app",
+      port: parsePort(ports.app, 3e3),
+      startCommand: scripts.app ? `npm run ${scripts.app}` : null,
+      source: "ai"
+    });
+  }
+  return apps;
+}
+function collectScriptAlternatives(folder, primary, opts = {}) {
+  const pkg = readPackageJson(folder);
+  const scripts = pkg?.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+  const usedCommands = new Set(
+    primary.map((app) => app.startCommand?.trim()).filter((cmd) => Boolean(cmd))
+  );
+  const alternatives = [];
+  const hostApp = primary.find((app) => app.role === "ui" || app.role === "app") || primary.find((app) => app.role !== "ai-server");
+  const backendApp = primary.find((app) => app.role === "backend");
+  for (const [name, command] of Object.entries(scripts)) {
+    if (isChatScript(name, command)) continue;
+    if (!/^(dev|start|serve)/i.test(name) && !isUiCommand(command)) continue;
+    const startCommand = `npm run ${name}`;
+    if (usedCommands.has(startCommand)) continue;
+    const scriptPort = parsePort(command);
+    const looksBackend = /\b(server|api|backend)\b/i.test(`${name} ${command}`) && !isUiCommand(command);
+    const target = looksBackend ? backendApp || hostApp : hostApp;
+    if (!target) continue;
+    const fallbackPort = scriptPort || (looksBackend ? 4100 : isUiCommand(command) && /vite/i.test(command) ? 5173 : 3e3);
+    alternatives.push({
+      appId: target.id,
+      port: fallbackPort,
+      startCommand,
+      label: `${name} \u2192 ${fallbackPort}`,
+      source: "package"
+    });
+    if (alternatives.length >= 8) break;
+  }
+  const { layers } = readProjectEnvLayers(folder);
+  if (hostApp) {
+    for (const layer of layers) {
+      if (layer.file === ".env.example") continue;
+      const port = parsePort(layer.values.PORT);
+      if (!port || port === hostApp.port) continue;
+      if (alternatives.some(
+        (alt) => alt.appId === hostApp.id && alt.port === port && !alt.startCommand
+      )) {
+        continue;
+      }
+      alternatives.push({
+        appId: hostApp.id,
+        port,
+        startCommand: hostApp.startCommand || null,
+        label: `${layer.file} PORT=${port}`,
+        source: "env"
+      });
+    }
+  }
+  void opts;
+  return alternatives;
+}
+function proposalConfidence(apps, reasons, usedAi) {
+  const hostApps = apps.filter((app) => app.role !== "ai-server");
+  if (!hostApps.length) return "low";
+  if (reasons.length === 0 && hostApps.every((app) => app.startCommand)) {
+    return usedAi ? "medium" : "high";
+  }
+  if (reasons.some((reason) => /differ|does not match|no host app/i.test(reason))) {
+    return "low";
+  }
+  return "medium";
+}
+function projectSummaryFromDetect(folder, apps, opts = {}) {
+  const pkg = readPackageJson(folder);
+  const name = opts.appName || pkg?.name || path8.basename(path8.resolve(folder));
+  const hostApps = apps.filter((app) => app.role !== "ai-server");
+  if (!hostApps.length) {
+    return `${name}: no UI/backend ports detected from config yet.`;
+  }
+  return `${name}: ${hostApps.map((app) => `${app.name} on ${app.port}${app.startCommand ? ` (${app.startCommand})` : ""}`).join(", ")}.`;
+}
+async function proposeHostAppsFromConfig(input) {
+  const folder = path8.resolve(input.workspaceDir);
+  const preferredAi = parsePort(input.preferredAiPort, AI_SERVER_DEFAULT_PORT);
+  const fingerprint = hostAppsFingerprint(folder);
+  const allowAi = input.allowAi !== false;
+  const detected = detectHostAppsFromFiles(folder, {
+    preferredAiPort: preferredAi,
+    appName: input.appName
+  });
+  let apps = ensureAiServerApp(detected.apps, preferredAi);
+  let reasons = [...detected.reasons];
+  let usedAi = false;
+  let projectSummary = projectSummaryFromDetect(folder, apps, {
+    appName: input.appName
+  });
+  const hostCount = apps.filter((app) => app.role !== "ai-server").length;
+  const needsAi = allowAi && (detected.confused || hostCount === 0 || reasons.some((reason) => /differ|does not match/i.test(reason)));
+  if (needsAi) {
+    try {
+      const inspected = await inspectConfigOnly({
+        workspaceDir: folder,
+        appName: input.appName,
+        extraContext: [
+          "File-based detection was uncertain or incomplete.",
+          ...reasons
+        ].join("\n")
+      });
+      usedAi = true;
+      const fromAi = appsFromInspectPorts(
+        inspected.ports,
+        inspected.scripts,
+        inspected.name || input.appName || "App"
+      );
+      if (fromAi.length) {
+        apps = ensureAiServerApp(
+          [defaultAiServerApp(preferredAi), ...fromAi],
+          preferredAi
+        );
+      }
+      if (inspected.summary) projectSummary = inspected.summary;
+      if (inspected.issues?.length) {
+        reasons = [...reasons, ...inspected.issues];
+      }
+    } catch (err) {
+      reasons.push(
+        `AI suggest skipped: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  const alternatives = collectScriptAlternatives(folder, apps, {
+    appName: input.appName
+  });
+  const confidence = proposalConfidence(apps, reasons, usedAi);
+  const needsReview = confidence !== "high" || detected.confused || apps.filter((app) => app.role !== "ai-server").length === 0;
+  return {
+    apps,
+    alternatives,
+    reasons,
+    confidence,
+    projectSummary,
+    usedAi,
+    needsReview,
+    fingerprint
+  };
+}
+async function resolveHostApps(input) {
+  const folder = path8.resolve(input.workspaceDir);
+  const loc = { sandboxId: input.sandboxId, dataDir: input.dataDir };
+  const fingerprint = hostAppsFingerprint(folder);
+  const preferredAi = parsePort(input.preferredAiPort, AI_SERVER_DEFAULT_PORT);
+  const detected = detectHostAppsFromFiles(folder, {
+    preferredAiPort: preferredAi,
+    appName: input.appName
+  });
+  const desired = normalizeHostApps(input.desired);
+  if (desired.length) {
+    const apps2 = mergeDesiredHostApps(desired, detected.apps);
+    try {
+      writeHostAppsCache(folder, apps2, { source: "desired" }, loc);
+    } catch {
+    }
+    return {
+      apps: apps2,
+      source: "desired",
+      cached: false,
+      usedAi: false,
+      confused: false,
+      reasons: [],
+      fingerprint
+    };
+  }
+  if (!input.force) {
+    const cached = readHostAppsCache(folder, loc);
+    if (cached && cached.fingerprint === fingerprint) {
+      return {
+        apps: ensureAiServerApp(cached.apps, preferredAi),
+        source: "cache",
+        cached: true,
+        usedAi: false,
+        confused: false,
+        reasons: [],
+        fingerprint
+      };
+    }
+  }
+  const needsAi = Boolean(input.allowAi) && (Boolean(input.force && detected.confused) || detected.confused && detected.apps.filter((app) => app.role !== "ai-server").length === 0 || detected.reasons.some((reason) => /differ|does not match/i.test(reason)));
+  if (needsAi) {
+    try {
+      const inspected = await inspectConfigOnly({
+        workspaceDir: folder,
+        appName: input.appName,
+        extraContext: `Port detection was uncertain:
+${detected.reasons.join("\n")}
+Return the real local ports and npm script names.`
+      });
+      const fromAi = appsFromInspectPorts(
+        inspected.ports,
+        inspected.scripts,
+        inspected.name || input.appName || "App"
+      );
+      const apps2 = ensureAiServerApp(
+        [defaultAiServerApp(preferredAi), ...fromAi],
+        preferredAi
+      );
+      writeHostAppsCache(
+        folder,
+        apps2,
+        {
+          source: "ai",
+          reasons: detected.reasons,
+          summary: inspected.summary
+        },
+        loc
+      );
+      return {
+        apps: apps2,
+        source: "ai",
+        cached: false,
+        usedAi: true,
+        confused: detected.confused,
+        reasons: detected.reasons,
+        fingerprint
+      };
+    } catch (err) {
+      detected.reasons.push(
+        `AI inspect skipped: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  const apps = ensureAiServerApp(detected.apps, preferredAi);
+  try {
+    writeHostAppsCache(
+      folder,
+      apps,
+      {
+        source: detected.confused ? "env" : "env",
+        reasons: detected.reasons
+      },
+      loc
+    );
+  } catch {
+  }
+  return {
+    apps,
+    source: apps.some((app) => app.source === "env") ? "env" : "default",
+    cached: false,
+    usedAi: false,
+    confused: detected.confused,
+    reasons: detected.reasons,
+    fingerprint
   };
 }
 export {
   ACCESS_IGNORE_BEGIN,
   ACCESS_IGNORE_END,
+  AI_SERVER_APP_ID,
+  AI_SERVER_DEFAULT_PORT,
+  COLLABORATER_DIR,
   DEFAULT_AI_IGNORE_PATHS,
+  HOST_APPS_FILE,
+  MAINTAINER_PRO_HOME_DIR,
   PROMPT_SECTION,
   WORKING_PROVIDER,
   buildClaudeUserPrompt,
@@ -2416,27 +3402,53 @@ export {
   createMaintainerProStoreFromEnv,
   createSyncedChatStore,
   createToolValidator,
+  defaultAiServerApp,
+  detectHostAppsFromFiles,
+  ensureAiServerApp,
+  ensureProjectDataDir,
+  ensureSingleHost,
   formatAccessPolicyPromptSection,
   formatClientContext,
   formatParentChainContext,
   getProviderPreference,
+  hostAppsCachePath2 as hostAppsCachePath,
+  hostAppsFingerprint,
   inspectAndRepairWorkspace,
+  inspectConfigOnly,
   isDevMode,
   isIgnoredRelative,
   isInsideWorkspace,
   isPathAllowed,
+  maintainerProHome,
+  mergeDesiredHostApps,
+  normalizeEnvMaps,
+  normalizeHostApp,
+  normalizeHostApps,
   normalizeIgnorePaths,
   parentChainForTurn,
   parseAiResponse,
   parseIgnorePathsEnv,
+  parsePort,
   previewText,
+  hostAppsCachePath as projectHostAppsPath,
+  projectIdForFolder,
+  projectUploadsDir,
+  proposeHostAppsFromConfig,
   providerLabel,
+  readCollaboraterApps,
+  readHostAppsCache,
+  readProjectEnvLayers,
   renderManagedIgnoreBlock,
   resolveCliBinary,
+  resolveHostApps,
   resolveIgnorePaths,
   resolveLogLevel,
+  resolveProjectDataDir,
   resolveProvider,
+  sanitizeProjectId,
   saveChatAttachments,
   toNextRoute,
-  upsertManagedIgnoreFile
+  upsertManagedIgnoreFile,
+  writeCollaboraterApps,
+  writeHostAppsCache
 };