@mastra/factory 0.2.2-alpha.0 → 0.2.2-alpha.2

package/dist/routes/fs.js

@@ -1,394 +1,446 @@
-// src/routes/fs.ts
+import { registerApiRoute } from "@mastra/core/server";
+import { isAbsolute, join, posix, resolve, sep } from "path";
 import { lstat, open, readdir, realpath, stat } from "fs/promises";
 import { homedir } from "os";
-import { isAbsolute, join, posix as posixPath, resolve, sep } from "path";
 import { SandboxFilesystem } from "@mastra/code-sdk/agents/sandbox-filesystem";
 import { detectProject, getResourceIdOverride } from "@mastra/code-sdk/utils/project";
-import { registerApiRoute } from "@mastra/core/server";
-var MAX_TEXT_FILE_BYTES = 512 * 1024;
-var TEXT_DECODER = new TextDecoder("utf-8", { fatal: true });
-var APPROVED_RENDERED_ROOTS = /* @__PURE__ */ new Set([".artifacts"]);
+//#region src/routes/fs.ts
+const MAX_TEXT_FILE_BYTES = 512 * 1024;
+const TEXT_DECODER = new TextDecoder("utf-8", { fatal: true });
+const APPROVED_RENDERED_ROOTS = /* @__PURE__ */ new Set([".artifacts"]);
+/** Erase a route handler's path-parameterized context to a plain `Context`. */
 function loose(c) {
-  return c;
+	return c;
 }
+/** Resolve the browsable root, defaulting to the user's home directory. */
 function resolveFsRoot(root) {
-  return resolve(root && root.trim() ? root : homedir());
+	return resolve(root && root.trim() ? root : homedir());
 }
+/** True when `candidate` is `root` or nested under it. */
 function isWithinRoot(candidate, root) {
-  if (candidate === root) return true;
-  const rootWithSep = root.endsWith(sep) ? root : root + sep;
-  return candidate.startsWith(rootWithSep);
+	if (candidate === root) return true;
+	const rootWithSep = root.endsWith(sep) ? root : root + sep;
+	return candidate.startsWith(rootWithSep);
 }
 async function realOrResolved(path) {
-  try {
-    return await realpath(path);
-  } catch {
-    return path;
-  }
+	try {
+		return await realpath(path);
+	} catch {
+		return path;
+	}
 }
+/**
+* Resolve a path's real location (following symlinks) and confirm it stays
+* within `root`. Returns the real path when confined, or `null` when it escapes
+* the root or does not exist. Used so a symlink inside the root that points
+* outside it cannot be browsed or selected.
+*/
 async function realPathWithinRoot(candidate, root) {
-  try {
-    const real = await realpath(candidate);
-    return isWithinRoot(real, root) ? real : null;
-  } catch {
-    return null;
-  }
+	try {
+		const real = await realpath(candidate);
+		return isWithinRoot(real, root) ? real : null;
+	} catch {
+		return null;
+	}
 }
 function assertRelativePath(path, label) {
-  const trimmed = path.trim();
-  if (!trimmed) throw new Error(`Missing required query param: ${label}`);
-  if (isAbsolute(trimmed)) throw new Error(`${label} must be relative`);
-  if (trimmed.split(/[\\/]+/).includes("..")) throw new Error(`${label} escapes workspace`);
-  const normalized = resolve("/", trimmed).slice(1);
-  if (!normalized || normalized === ".." || normalized.startsWith(`..${sep}`))
-    throw new Error(`${label} escapes workspace`);
-  return normalized;
+	const trimmed = path.trim();
+	if (!trimmed) throw new Error(`Missing required query param: ${label}`);
+	if (isAbsolute(trimmed)) throw new Error(`${label} must be relative`);
+	if (trimmed.split(/[\\/]+/).includes("..")) throw new Error(`${label} escapes workspace`);
+	const normalized = resolve("/", trimmed).slice(1);
+	if (!normalized || normalized === ".." || normalized.startsWith(`..${sep}`)) throw new Error(`${label} escapes workspace`);
+	return normalized;
 }
 function assertApprovedRenderedRoot(renderedRoot) {
-  const safeRoot = assertRelativePath(renderedRoot, "root");
-  if (!APPROVED_RENDERED_ROOTS.has(safeRoot)) throw new Error("Root is not approved for rendered workspace access");
-  return safeRoot;
+	const safeRoot = assertRelativePath(renderedRoot, "root");
+	if (!APPROVED_RENDERED_ROOTS.has(safeRoot)) throw new Error("Root is not approved for rendered workspace access");
+	return safeRoot;
 }
 async function confinedWorkspacePath(root, workspacePath) {
-  const resolvedRoot = await realOrResolved(resolveFsRoot(root));
-  const candidate = isAbsolute(workspacePath) ? resolve(workspacePath) : resolve(resolvedRoot, workspacePath);
-  const workspace = await realPathWithinRoot(candidate, resolvedRoot);
-  if (!workspace) throw new Error("Path is outside the browsable root");
-  return { resolvedRoot, workspace };
+	const resolvedRoot = await realOrResolved(resolveFsRoot(root));
+	const workspace = await realPathWithinRoot(isAbsolute(workspacePath) ? resolve(workspacePath) : resolve(resolvedRoot, workspacePath), resolvedRoot);
+	if (!workspace) throw new Error("Path is outside the browsable root");
+	return {
+		resolvedRoot,
+		workspace
+	};
 }
 async function confinedWorkspaceRelativePath(root, workspacePath, relativePath) {
-  const safeRelativePath = assertRelativePath(relativePath, "path");
-  const { workspace } = await confinedWorkspacePath(root, workspacePath);
-  const candidate = resolve(workspace, safeRelativePath);
-  if (!isWithinRoot(candidate, workspace)) throw new Error("Path escapes workspace");
-  const confinedPath = await realPathWithinRoot(candidate, workspace);
-  if (!confinedPath) throw new Error("Path is outside the workspace");
-  return { workspace, path: confinedPath, relativePath: safeRelativePath };
+	const safeRelativePath = assertRelativePath(relativePath, "path");
+	const { workspace } = await confinedWorkspacePath(root, workspacePath);
+	const candidate = resolve(workspace, safeRelativePath);
+	if (!isWithinRoot(candidate, workspace)) throw new Error("Path escapes workspace");
+	const confinedPath = await realPathWithinRoot(candidate, workspace);
+	if (!confinedPath) throw new Error("Path is outside the workspace");
+	return {
+		workspace,
+		path: confinedPath,
+		relativePath: safeRelativePath
+	};
 }
+/**
+* List the directories inside `requestedPath`, confined to `root`. An absent or
+* out-of-root path is clamped to the root, so the worst a malicious client can
+* do is browse within the allowed root.
+*/
 async function listDirectory(root, requestedPath) {
-  const resolvedRoot = await realOrResolved(resolveFsRoot(root));
-  let target = resolvedRoot;
-  if (requestedPath && requestedPath.trim()) {
-    const candidate = isAbsolute(requestedPath) ? resolve(requestedPath) : resolve(resolvedRoot, requestedPath);
-    target = await realPathWithinRoot(candidate, resolvedRoot) ?? resolvedRoot;
-  }
-  try {
-    const info = await stat(target);
-    if (!info.isDirectory()) target = resolvedRoot;
-  } catch {
-    target = resolvedRoot;
-  }
-  const dirents = await readdir(target, { withFileTypes: true });
-  const entries = [];
-  for (const dirent of dirents) {
-    if (dirent.name.startsWith(".")) continue;
-    const entryPath = join(target, dirent.name);
-    let isDir = dirent.isDirectory();
-    if (dirent.isSymbolicLink()) {
-      const real = await realPathWithinRoot(entryPath, resolvedRoot);
-      isDir = real ? (await stat(real).catch(() => null))?.isDirectory() === true : false;
-    }
-    if (isDir) entries.push({ name: dirent.name, path: entryPath });
-  }
-  entries.sort((a, b) => a.name.localeCompare(b.name));
-  const parent = target === resolvedRoot ? null : resolve(target, "..");
-  return { root: resolvedRoot, path: target, parent, entries };
+	const resolvedRoot = await realOrResolved(resolveFsRoot(root));
+	let target = resolvedRoot;
+	if (requestedPath && requestedPath.trim()) target = await realPathWithinRoot(isAbsolute(requestedPath) ? resolve(requestedPath) : resolve(resolvedRoot, requestedPath), resolvedRoot) ?? resolvedRoot;
+	try {
+		if (!(await stat(target)).isDirectory()) target = resolvedRoot;
+	} catch {
+		target = resolvedRoot;
+	}
+	const dirents = await readdir(target, { withFileTypes: true });
+	const entries = [];
+	for (const dirent of dirents) {
+		if (dirent.name.startsWith(".")) continue;
+		const entryPath = join(target, dirent.name);
+		let isDir = dirent.isDirectory();
+		if (dirent.isSymbolicLink()) {
+			const real = await realPathWithinRoot(entryPath, resolvedRoot);
+			isDir = real ? (await stat(real).catch(() => null))?.isDirectory() === true : false;
+		}
+		if (isDir) entries.push({
+			name: dirent.name,
+			path: entryPath
+		});
+	}
+	entries.sort((a, b) => a.name.localeCompare(b.name));
+	const parent = target === resolvedRoot ? null : resolve(target, "..");
+	return {
+		root: resolvedRoot,
+		path: target,
+		parent,
+		entries
+	};
 }
 async function listRenderedEntries(rootPath, currentPath = rootPath) {
-  const dirents = await readdir(currentPath, { withFileTypes: true });
-  const entries = [];
-  for (const dirent of dirents) {
-    const entryPath = join(currentPath, dirent.name);
-    const info = await lstat(entryPath);
-    const relativePath = entryPath.slice(rootPath.length + 1);
-    if (info.isDirectory()) {
-      entries.push({
-        name: dirent.name,
-        path: relativePath,
-        type: "directory",
-        size: info.size,
-        updatedAt: info.mtime.toISOString()
-      });
-      entries.push(...await listRenderedEntries(rootPath, entryPath));
-      continue;
-    }
-    if (info.isFile()) {
-      entries.push({
-        name: dirent.name,
-        path: relativePath,
-        type: "file",
-        size: info.size,
-        updatedAt: info.mtime.toISOString()
-      });
-    }
-  }
-  return entries.sort((a, b) => a.path.localeCompare(b.path));
+	const dirents = await readdir(currentPath, { withFileTypes: true });
+	const entries = [];
+	for (const dirent of dirents) {
+		const entryPath = join(currentPath, dirent.name);
+		const info = await lstat(entryPath);
+		const relativePath = entryPath.slice(rootPath.length + 1);
+		if (info.isDirectory()) {
+			entries.push({
+				name: dirent.name,
+				path: relativePath,
+				type: "directory",
+				size: info.size,
+				updatedAt: info.mtime.toISOString()
+			});
+			entries.push(...await listRenderedEntries(rootPath, entryPath));
+			continue;
+		}
+		if (info.isFile()) entries.push({
+			name: dirent.name,
+			path: relativePath,
+			type: "file",
+			size: info.size,
+			updatedAt: info.mtime.toISOString()
+		});
+	}
+	return entries.sort((a, b) => a.path.localeCompare(b.path));
 }
 async function listWorkspaceRenderedPath(root, workspacePath, renderedRoot) {
-  const safeRoot = assertApprovedRenderedRoot(renderedRoot);
-  const { workspace } = await confinedWorkspacePath(root, workspacePath);
-  const renderedPath = resolve(workspace, safeRoot);
-  if (!isWithinRoot(renderedPath, workspace)) throw new Error("Root escapes workspace");
-  const confinedRootPath = await realPathWithinRoot(renderedPath, workspace);
-  if (!confinedRootPath) return { workspacePath: workspace, root: safeRoot, rootPath: renderedPath, entries: [] };
-  const info = await stat(confinedRootPath);
-  if (!info.isDirectory()) return { workspacePath: workspace, root: safeRoot, rootPath: confinedRootPath, entries: [] };
-  return {
-    workspacePath: workspace,
-    root: safeRoot,
-    rootPath: confinedRootPath,
-    entries: await listRenderedEntries(confinedRootPath)
-  };
+	const safeRoot = assertApprovedRenderedRoot(renderedRoot);
+	const { workspace } = await confinedWorkspacePath(root, workspacePath);
+	const renderedPath = resolve(workspace, safeRoot);
+	if (!isWithinRoot(renderedPath, workspace)) throw new Error("Root escapes workspace");
+	const confinedRootPath = await realPathWithinRoot(renderedPath, workspace);
+	if (!confinedRootPath) return {
+		workspacePath: workspace,
+		root: safeRoot,
+		rootPath: renderedPath,
+		entries: []
+	};
+	if (!(await stat(confinedRootPath)).isDirectory()) return {
+		workspacePath: workspace,
+		root: safeRoot,
+		rootPath: confinedRootPath,
+		entries: []
+	};
+	return {
+		workspacePath: workspace,
+		root: safeRoot,
+		rootPath: confinedRootPath,
+		entries: await listRenderedEntries(confinedRootPath)
+	};
 }
 async function readWorkspaceFile(root, workspacePath, path) {
-  const safePath = assertRelativePath(path, "path");
-  const relativeRoot = safePath.split("/")[0] ?? "";
-  assertApprovedRenderedRoot(relativeRoot);
-  const {
-    workspace,
-    path: confinedPath,
-    relativePath
-  } = await confinedWorkspaceRelativePath(root, workspacePath, path);
-  const info = await lstat(confinedPath);
-  if (info.isDirectory()) throw new Error("Path is a directory");
-  if (!info.isFile()) throw new Error("Unsupported file type");
-  const bytesToRead = Math.min(info.size, MAX_TEXT_FILE_BYTES);
-  const contentBuffer = Buffer.alloc(bytesToRead);
-  const handle = await open(confinedPath, "r");
-  try {
-    await handle.read(contentBuffer, 0, bytesToRead, 0);
-  } finally {
-    await handle.close();
-  }
-  try {
-    const content = TEXT_DECODER.decode(contentBuffer);
-    return {
-      workspacePath: workspace,
-      path: relativePath,
-      name: relativePath.split("/").pop() ?? relativePath,
-      size: info.size,
-      updatedAt: info.mtime.toISOString(),
-      contentType: "text",
-      content,
-      truncated: info.size > MAX_TEXT_FILE_BYTES
-    };
-  } catch {
-    return {
-      workspacePath: workspace,
-      path: relativePath,
-      name: relativePath.split("/").pop() ?? relativePath,
-      size: info.size,
-      updatedAt: info.mtime.toISOString(),
-      contentType: "unsupported"
-    };
-  }
+	assertApprovedRenderedRoot(assertRelativePath(path, "path").split("/")[0] ?? "");
+	const { workspace, path: confinedPath, relativePath } = await confinedWorkspaceRelativePath(root, workspacePath, path);
+	const info = await lstat(confinedPath);
+	if (info.isDirectory()) throw new Error("Path is a directory");
+	if (!info.isFile()) throw new Error("Unsupported file type");
+	const bytesToRead = Math.min(info.size, MAX_TEXT_FILE_BYTES);
+	const contentBuffer = Buffer.alloc(bytesToRead);
+	const handle = await open(confinedPath, "r");
+	try {
+		await handle.read(contentBuffer, 0, bytesToRead, 0);
+	} finally {
+		await handle.close();
+	}
+	try {
+		const content = TEXT_DECODER.decode(contentBuffer);
+		return {
+			workspacePath: workspace,
+			path: relativePath,
+			name: relativePath.split("/").pop() ?? relativePath,
+			size: info.size,
+			updatedAt: info.mtime.toISOString(),
+			contentType: "text",
+			content,
+			truncated: info.size > MAX_TEXT_FILE_BYTES
+		};
+	} catch {
+		return {
+			workspacePath: workspace,
+			path: relativePath,
+			name: relativePath.split("/").pop() ?? relativePath,
+			size: info.size,
+			updatedAt: info.mtime.toISOString(),
+			contentType: "unsupported"
+		};
+	}
 }
 async function listArtifacts(root, workspacePath) {
-  const listing = await listWorkspaceRenderedPath(root, workspacePath, ".artifacts");
-  return {
-    rootPath: listing.workspacePath,
-    artifactsPath: listing.rootPath,
-    entries: listing.entries
-  };
+	const listing = await listWorkspaceRenderedPath(root, workspacePath, ".artifacts");
+	return {
+		rootPath: listing.workspacePath,
+		artifactsPath: listing.rootPath,
+		entries: listing.entries
+	};
 }
+/**
+* Resolve a `workspacePath` query param as a Factory session id. Returns the
+* session when one exists and the caller owns it, `null` when no session
+* matches (the caller should fall back to local-path handling), and throws
+* when a session exists but belongs to another tenant.
+*/
 async function resolveAuthorizedSession(c, deps, workspacePath) {
-  if (!deps) return null;
-  const session = await deps.sessions.getBySessionId(workspacePath);
-  if (!session) return null;
-  if (deps.auth.enabled()) {
-    await deps.auth.ensureUser(c);
-    const tenant = deps.auth.tenant(c);
-    if (!tenant || tenant.orgId !== session.orgId || tenant.userId !== session.userId) {
-      throw new Error("Session is not available to the current user");
-    }
-  }
-  return session;
+	if (!deps) return null;
+	const session = await deps.sessions.getBySessionId(workspacePath);
+	if (!session) return null;
+	if (deps.auth.enabled()) {
+		await deps.auth.ensureUser(c);
+		const tenant = deps.auth.tenant(c);
+		if (!tenant || tenant.orgId !== session.orgId || tenant.userId !== session.userId) throw new Error("Session is not available to the current user");
+	}
+	return session;
 }
+/**
+* Reattach to the session's sandbox and wrap its workdir in a
+* `SandboxFilesystem`. Returns `null` when the session has no provisioned
+* sandbox yet (nothing materialized → nothing to list), or when the sandbox
+* can no longer be reattached (e.g. torn down by the provider's idle GC).
+* This is a passive read path, so it never re-provisions: the session's
+* filesystem is preserved in its provider checkpoint and comes back the next
+* time the workspace is actually opened (e.g. by sending a message).
+*/
 async function sessionSandbox(fleet, session) {
-  if (!fleet.enabled || !session.sandboxId || !session.sandboxWorkdir) return null;
-  let sandbox;
-  try {
-    sandbox = await fleet.reattachSandbox(session.sandboxId, { workingDirectory: session.sandboxWorkdir });
-  } catch {
-    return null;
-  }
-  return {
-    sandbox,
-    filesystem: new SandboxFilesystem({ sandbox, workdir: session.sandboxWorkdir }),
-    workdir: session.sandboxWorkdir
-  };
+	if (!fleet.enabled || !session.sandboxId || !session.sandboxWorkdir) return null;
+	let sandbox;
+	try {
+		sandbox = await fleet.reattachSandbox(session.sandboxId, { workingDirectory: session.sandboxWorkdir });
+	} catch {
+		return null;
+	}
+	return {
+		sandbox,
+		filesystem: new SandboxFilesystem({
+			sandbox,
+			workdir: session.sandboxWorkdir
+		}),
+		workdir: session.sandboxWorkdir
+	};
 }
+/** List an approved rendered root inside a Factory session's sandbox workdir. */
 async function listSessionRenderedPath(fleet, session, renderedRoot) {
-  const safeRoot = assertApprovedRenderedRoot(renderedRoot);
-  const rootPath = posixPath.join(session.sandboxWorkdir ?? "", safeRoot);
-  const empty = { workspacePath: session.sessionId, root: safeRoot, rootPath, entries: [] };
-  const handle = await sessionSandbox(fleet, session);
-  if (!handle) return empty;
-  const quotedRoot = `'${rootPath.replace(/'/g, `'\\''`)}'`;
-  const result = await handle.sandbox.executeCommand(
-    "sh",
-    [
-      "-c",
-      `test -d ${quotedRoot} && find ${quotedRoot} -mindepth 1 -printf '%y\\t%s\\t%T@\\t%p\\n' 2>/dev/null || true`
-    ],
-    { timeout: 3e4 }
-  );
-  if (result.exitCode !== 0) return empty;
-  const entries = [];
-  for (const line of result.stdout.split("\n")) {
-    if (!line) continue;
-    const [type, sizeStr, mtimeStr, ...pathParts] = line.split("	");
-    const fullPath = pathParts.join("	");
-    if (!fullPath || !fullPath.startsWith(`${rootPath}/`)) continue;
-    const relativePath = fullPath.slice(rootPath.length + 1);
-    entries.push({
-      name: posixPath.basename(relativePath),
-      path: relativePath,
-      type: type === "d" ? "directory" : "file",
-      size: type === "d" ? 0 : Number(sizeStr) || 0,
-      updatedAt: new Date((Number(mtimeStr) || 0) * 1e3).toISOString()
-    });
-  }
-  entries.sort((a, b) => a.path.localeCompare(b.path));
-  return { workspacePath: session.sessionId, root: safeRoot, rootPath, entries };
+	const safeRoot = assertApprovedRenderedRoot(renderedRoot);
+	const rootPath = posix.join(session.sandboxWorkdir ?? "", safeRoot);
+	const empty = {
+		workspacePath: session.sessionId,
+		root: safeRoot,
+		rootPath,
+		entries: []
+	};
+	const handle = await sessionSandbox(fleet, session);
+	if (!handle) return empty;
+	const quotedRoot = `'${rootPath.replace(/'/g, `'\\''`)}'`;
+	const result = await handle.sandbox.executeCommand("sh", ["-c", `test -d ${quotedRoot} && find ${quotedRoot} -mindepth 1 -printf '%y\\t%s\\t%T@\\t%p\\n' 2>/dev/null || true`], { timeout: 3e4 });
+	if (result.exitCode !== 0) return empty;
+	const entries = [];
+	for (const line of result.stdout.split("\n")) {
+		if (!line) continue;
+		const [type, sizeStr, mtimeStr, ...pathParts] = line.split("	");
+		const fullPath = pathParts.join("	");
+		if (!fullPath || !fullPath.startsWith(`${rootPath}/`)) continue;
+		const relativePath = fullPath.slice(rootPath.length + 1);
+		entries.push({
+			name: posix.basename(relativePath),
+			path: relativePath,
+			type: type === "d" ? "directory" : "file",
+			size: type === "d" ? 0 : Number(sizeStr) || 0,
+			updatedAt: (/* @__PURE__ */ new Date((Number(mtimeStr) || 0) * 1e3)).toISOString()
+		});
+	}
+	entries.sort((a, b) => a.path.localeCompare(b.path));
+	return {
+		workspacePath: session.sessionId,
+		root: safeRoot,
+		rootPath,
+		entries
+	};
 }
+/** Read a file under an approved rendered root inside a session's sandbox. */
 async function readSessionWorkspaceFile(fleet, session, path) {
-  const safePath = assertRelativePath(path, "path");
-  assertApprovedRenderedRoot(safePath.split("/")[0] ?? "");
-  const handle = await sessionSandbox(fleet, session);
-  if (!handle) throw new Error("Session workspace is not available");
-  const { filesystem } = handle;
-  const info = await filesystem.stat(safePath);
-  if (info.type === "directory") throw new Error("Path is a directory");
-  const buffer = await filesystem.readFile(safePath);
-  const truncated = buffer.length > MAX_TEXT_FILE_BYTES;
-  const base = {
-    workspacePath: session.sessionId,
-    path: safePath,
-    name: posixPath.basename(safePath),
-    size: buffer.length,
-    updatedAt: info.modifiedAt.toISOString()
-  };
-  try {
-    const content = TEXT_DECODER.decode(truncated ? buffer.subarray(0, MAX_TEXT_FILE_BYTES) : buffer);
-    return { ...base, contentType: "text", content, truncated };
-  } catch {
-    return { ...base, contentType: "unsupported" };
-  }
+	const safePath = assertRelativePath(path, "path");
+	assertApprovedRenderedRoot(safePath.split("/")[0] ?? "");
+	const handle = await sessionSandbox(fleet, session);
+	if (!handle) throw new Error("Session workspace is not available");
+	const { filesystem } = handle;
+	const info = await filesystem.stat(safePath);
+	if (info.type === "directory") throw new Error("Path is a directory");
+	const buffer = await filesystem.readFile(safePath);
+	const truncated = buffer.length > MAX_TEXT_FILE_BYTES;
+	const base = {
+		workspacePath: session.sessionId,
+		path: safePath,
+		name: posix.basename(safePath),
+		size: buffer.length,
+		updatedAt: info.modifiedAt.toISOString()
+	};
+	try {
+		const content = TEXT_DECODER.decode(truncated ? buffer.subarray(0, MAX_TEXT_FILE_BYTES) : buffer);
+		return {
+			...base,
+			contentType: "text",
+			content,
+			truncated
+		};
+	} catch {
+		return {
+			...base,
+			contentType: "unsupported"
+		};
+	}
 }
+/**
+* Resolve a project path to the same resourceId the TUI uses. Mirrors
+* `createMastraCode`: detect the project, then apply any resourceId override
+* (MASTRA_RESOURCE_ID env var or `.mastracode/database.json`). This is the
+* shared continuity point — start in the TUI, continue on the web, same path
+* → same resourceId → same session.
+*/
 function resolveCodebase(projectPath) {
-  const info = detectProject(projectPath);
-  const override = getResourceIdOverride(info.rootPath);
-  return {
-    resourceId: override ?? info.resourceId,
-    name: info.name,
-    rootPath: info.rootPath,
-    gitUrl: info.gitUrl,
-    gitBranch: info.gitBranch
-  };
+	const info = detectProject(projectPath);
+	return {
+		resourceId: getResourceIdOverride(info.rootPath) ?? info.resourceId,
+		name: info.name,
+		rootPath: info.rootPath,
+		gitUrl: info.gitUrl,
+		gitBranch: info.gitBranch
+	};
 }
+/**
+* Build the web filesystem routes as Mastra `apiRoutes`:
+*   - `GET /web/fs/list?path=...`        — browse directories (confined to root)
+*   - `GET /web/codebase/resolve?path=...` — TUI-compatible codebase resourceId
+*/
 function buildFsRoutes(options = {}) {
-  const root = resolveFsRoot(options.root);
-  const sessionFs = options.sessionFs;
-  return [
-    registerApiRoute("/web/fs/list", {
-      method: "GET",
-      requiresAuth: false,
-      handler: async (c) => {
-        const path = c.req.query("path");
-        try {
-          const listing = await listDirectory(root, path);
-          return c.json(listing);
-        } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          return c.json({ error: message }, 500);
-        }
-      }
-    }),
-    registerApiRoute("/web/artifacts/list", {
-      method: "GET",
-      requiresAuth: false,
-      handler: async (c) => {
-        const path = c.req.query("path");
-        if (!path) return c.json({ error: "Missing required query param: path" }, 400);
-        try {
-          return c.json(await listArtifacts(root, path));
-        } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          const status = message === "Path is outside the browsable root" ? 403 : 500;
-          return c.json({ error: message }, status);
-        }
-      }
-    }),
-    registerApiRoute("/web/workspace/rendered/list", {
-      method: "GET",
-      requiresAuth: false,
-      handler: async (c) => {
-        const workspacePath = c.req.query("workspacePath");
-        const renderedRoot = c.req.query("root");
-        if (!workspacePath) return c.json({ error: "Missing required query param: workspacePath" }, 400);
-        if (!renderedRoot) return c.json({ error: "Missing required query param: root" }, 400);
-        try {
-          const session = await resolveAuthorizedSession(loose(c), sessionFs, workspacePath);
-          if (session && sessionFs) {
-            return c.json(await listSessionRenderedPath(sessionFs.fleet, session, renderedRoot));
-          }
-          return c.json(await listWorkspaceRenderedPath(root, workspacePath, renderedRoot));
-        } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          const status = message.includes("outside") || message.includes("relative") || message.includes("escapes") || message.includes("not approved") || message.includes("not available") ? 403 : 500;
-          return c.json({ error: message }, status);
-        }
-      }
-    }),
-    registerApiRoute("/web/workspace/file", {
-      method: "GET",
-      requiresAuth: false,
-      handler: async (c) => {
-        const workspacePath = c.req.query("workspacePath");
-        const path = c.req.query("path");
-        if (!workspacePath) return c.json({ error: "Missing required query param: workspacePath" }, 400);
-        if (!path) return c.json({ error: "Missing required query param: path" }, 400);
-        try {
-          const session = await resolveAuthorizedSession(loose(c), sessionFs, workspacePath);
-          if (session && sessionFs) {
-            return c.json(await readSessionWorkspaceFile(sessionFs.fleet, session, path));
-          }
-          return c.json(await readWorkspaceFile(root, workspacePath, path));
-        } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          const status = message.includes("outside") || message.includes("relative") || message.includes("escapes") || message.includes("not approved") || message.includes("not available") ? 403 : message.includes("directory") ? 400 : message.includes("not found") ? 404 : 500;
-          return c.json({ error: message }, status);
-        }
-      }
-    }),
-    registerApiRoute("/web/codebase/resolve", {
-      method: "GET",
-      requiresAuth: false,
-      handler: async (c) => {
-        const path = c.req.query("path");
-        if (!path) return c.json({ error: "Missing required query param: path" }, 400);
-        const confined = await realPathWithinRoot(isAbsolute(path) ? resolve(path) : resolve(root, path), root);
-        if (!confined) return c.json({ error: "Path is outside the browsable root" }, 403);
-        try {
-          return c.json(resolveCodebase(confined));
-        } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          return c.json({ error: message }, 500);
-        }
-      }
-    })
-  ];
+	const root = resolveFsRoot(options.root);
+	const sessionFs = options.sessionFs;
+	return [
+		registerApiRoute("/web/fs/list", {
+			method: "GET",
+			requiresAuth: false,
+			handler: async (c) => {
+				const path = c.req.query("path");
+				try {
+					const listing = await listDirectory(root, path);
+					return c.json(listing);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					return c.json({ error: message }, 500);
+				}
+			}
+		}),
+		registerApiRoute("/web/artifacts/list", {
+			method: "GET",
+			requiresAuth: false,
+			handler: async (c) => {
+				const path = c.req.query("path");
+				if (!path) return c.json({ error: "Missing required query param: path" }, 400);
+				try {
+					return c.json(await listArtifacts(root, path));
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					const status = message === "Path is outside the browsable root" ? 403 : 500;
+					return c.json({ error: message }, status);
+				}
+			}
+		}),
+		registerApiRoute("/web/workspace/rendered/list", {
+			method: "GET",
+			requiresAuth: false,
+			handler: async (c) => {
+				const workspacePath = c.req.query("workspacePath");
+				const renderedRoot = c.req.query("root");
+				if (!workspacePath) return c.json({ error: "Missing required query param: workspacePath" }, 400);
+				if (!renderedRoot) return c.json({ error: "Missing required query param: root" }, 400);
+				try {
+					const session = await resolveAuthorizedSession(loose(c), sessionFs, workspacePath);
+					if (session && sessionFs) return c.json(await listSessionRenderedPath(sessionFs.fleet, session, renderedRoot));
+					return c.json(await listWorkspaceRenderedPath(root, workspacePath, renderedRoot));
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					const status = message.includes("outside") || message.includes("relative") || message.includes("escapes") || message.includes("not approved") || message.includes("not available") ? 403 : 500;
+					return c.json({ error: message }, status);
+				}
+			}
+		}),
+		registerApiRoute("/web/workspace/file", {
+			method: "GET",
+			requiresAuth: false,
+			handler: async (c) => {
+				const workspacePath = c.req.query("workspacePath");
+				const path = c.req.query("path");
+				if (!workspacePath) return c.json({ error: "Missing required query param: workspacePath" }, 400);
+				if (!path) return c.json({ error: "Missing required query param: path" }, 400);
+				try {
+					const session = await resolveAuthorizedSession(loose(c), sessionFs, workspacePath);
+					if (session && sessionFs) return c.json(await readSessionWorkspaceFile(sessionFs.fleet, session, path));
+					return c.json(await readWorkspaceFile(root, workspacePath, path));
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					const status = message.includes("outside") || message.includes("relative") || message.includes("escapes") || message.includes("not approved") || message.includes("not available") ? 403 : message.includes("directory") ? 400 : message.includes("not found") ? 404 : 500;
+					return c.json({ error: message }, status);
+				}
+			}
+		}),
+		registerApiRoute("/web/codebase/resolve", {
+			method: "GET",
+			requiresAuth: false,
+			handler: async (c) => {
+				const path = c.req.query("path");
+				if (!path) return c.json({ error: "Missing required query param: path" }, 400);
+				const confined = await realPathWithinRoot(isAbsolute(path) ? resolve(path) : resolve(root, path), root);
+				if (!confined) return c.json({ error: "Path is outside the browsable root" }, 403);
+				try {
+					return c.json(resolveCodebase(confined));
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					return c.json({ error: message }, 500);
+				}
+			}
+		})
+	];
 }
-export {
-  buildFsRoutes,
-  listArtifacts,
-  listDirectory,
-  listSessionRenderedPath,
-  listWorkspaceRenderedPath,
-  readSessionWorkspaceFile,
-  readWorkspaceFile,
-  resolveCodebase,
-  resolveFsRoot
-};
+//#endregion
+export { buildFsRoutes, listArtifacts, listDirectory, listSessionRenderedPath, listWorkspaceRenderedPath, readSessionWorkspaceFile, readWorkspaceFile, resolveCodebase, resolveFsRoot };
+
 //# sourceMappingURL=fs.js.map