@oscharko-dev/keiko-server 0.2.0

package/dist/files.js

@@ -0,0 +1,733 @@
+// Read-only filesystem browser for the desktop Files widget. The browser receives
+// preview or editor content; every request is contained inside a selected root after
+// realpath resolution.
+import { createHash } from "node:crypto";
+import { lstat, opendir, open, readFile, realpath, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, parse as parsePath, posix as pathPosix, relative, resolve, } from "node:path";
+import { redact } from "@oscharko-dev/keiko-security";
+import { EDITOR_SESSION_SCHEMA_VERSION, parseEditorDocumentVersion, } from "@oscharko-dev/keiko-contracts";
+import { DENIED_MESSAGE, pathIsDenied } from "./files-deny.js";
+import { errorBody } from "./routes.js";
+const MAX_DIRECTORY_ENTRIES = 1_000;
+const MAX_TEXT_PREVIEW_BYTES = 1_000_000;
+const MAX_IMAGE_PREVIEW_BYTES = 3_000_000;
+const STABLE_CONTENT_READ_ATTEMPTS = 3;
+const staticFilesMetadataRedactor = (value) => typeof value === "string" ? redact(value) : value;
+class BodyTooLargeError extends Error {
+    constructor() {
+        super("request body too large");
+        this.name = "BodyTooLargeError";
+    }
+}
+// Exported for reuse by the editor language-service route (#1198) so denied/invalid roots map to the
+// same status + content-free code envelope as the files routes.
+export class FilesError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "FilesError";
+    }
+}
+function filesErrorResult(error) {
+    return { status: error.status, body: errorBody(error.code, error.message) };
+}
+export async function runFilesHandler(work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (error instanceof FilesError)
+            return filesErrorResult(error);
+        throw error;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRouteResult(value) {
+    return isRecord(value) && typeof value.status === "number" && "body" in value;
+}
+async function resolveDirectory(candidate) {
+    let resolved;
+    try {
+        resolved = await realpath(candidate);
+    }
+    catch {
+        throw new FilesError(400, "INVALID_DIRECTORY", "The directory does not exist.");
+    }
+    const info = await stat(resolved);
+    if (!info.isDirectory()) {
+        throw new FilesError(400, "INVALID_DIRECTORY", "The selected path must be a directory.");
+    }
+    return resolved;
+}
+function projectFor(store, projectId) {
+    return store.listProjects().find((project) => project.path === projectId);
+}
+function rootPathIsDenied(rootPath) {
+    return pathIsDenied(rootPath);
+}
+function assertMetadataSafe(value, redactor) {
+    const redacted = redactor(value);
+    if (typeof redacted === "string" && redacted !== value) {
+        throw new FilesError(403, "DENIED", DENIED_MESSAGE);
+    }
+}
+function metadataIsSafe(value, redactor) {
+    const redacted = redactor(value);
+    return typeof redacted !== "string" || redacted === value;
+}
+async function resolveRegisteredRoot(project, redactor) {
+    assertMetadataSafe(project.path, redactor);
+    if (rootPathIsDenied(project.path)) {
+        throw new FilesError(403, "DENIED", DENIED_MESSAGE);
+    }
+    const realRoot = await resolveDirectory(project.path);
+    assertMetadataSafe(realRoot, redactor);
+    if (rootPathIsDenied(realRoot)) {
+        throw new FilesError(403, "DENIED", DENIED_MESSAGE);
+    }
+    return { root: project.path, realRoot };
+}
+// Epic #532 — Keiko is a workspace for EVERYONE, not only devs: a Files window may browse ANY folder
+// on the machine, not just a registered project. An arbitrary input becomes its own root, gated by
+// the SAME realpath + FULL-PATH deny-list the grounded connect path enforces (deny matches on every
+// segment, so a root inside `.ssh`/`.aws`/credential dirs is rejected even when its basename is
+// innocuous). Browse and connect therefore accept the identical set of roots. The deny check runs
+// once on the raw input and again on the realpath, so a symlink whose target lands in a denied
+// location is caught after resolution.
+async function resolveArbitraryRoot(rootInput, redactor) {
+    if (!isAbsolute(rootInput)) {
+        throw new FilesError(400, "BAD_ROOT", "The root must be an absolute directory path.");
+    }
+    assertMetadataSafe(rootInput, redactor);
+    if (pathIsDenied(rootInput)) {
+        throw new FilesError(403, "DENIED", DENIED_MESSAGE);
+    }
+    const realRoot = await resolveDirectory(rootInput);
+    assertMetadataSafe(realRoot, redactor);
+    if (pathIsDenied(realRoot)) {
+        throw new FilesError(403, "DENIED", DENIED_MESSAGE);
+    }
+    return { root: rootInput, realRoot };
+}
+export async function resolveRoot(store, rootInput, redactor) {
+    if (rootInput === null || rootInput.trim().length === 0) {
+        throw new FilesError(400, "BAD_REQUEST", "The root query parameter is required.");
+    }
+    const project = projectFor(store, rootInput);
+    return project === undefined
+        ? resolveArbitraryRoot(rootInput.trim(), redactor)
+        : resolveRegisteredRoot(project, redactor);
+}
+function directoryRoots(projectRoot) {
+    return [{ label: "Project root", path: projectRoot }];
+}
+function parentPath(pathValue, projectRoot) {
+    if (pathValue === projectRoot)
+        return null;
+    const parsed = parsePath(pathValue);
+    return pathValue === parsed.root ? null : dirname(pathValue);
+}
+function normalizeRelativePath(pathInput) {
+    const raw = pathInput ?? "";
+    if (raw.includes("\0") || isAbsolute(raw)) {
+        throw new FilesError(400, "BAD_PATH", "The path must be relative to the selected root.");
+    }
+    const normalized = pathPosix.normalize(raw.replaceAll("\\", "/"));
+    if (normalized === ".")
+        return "";
+    if (normalized === ".." || normalized.startsWith("../")) {
+        throw new FilesError(400, "PATH_ESCAPE", "The requested path is outside the selected root.");
+    }
+    return normalized;
+}
+function nativePath(root, relativePath) {
+    if (relativePath.length === 0)
+        return root;
+    return resolve(root, ...relativePath.split("/").filter((part) => part.length > 0));
+}
+function isContained(root, target) {
+    const rootCmp = process.platform === "win32" ? root.toLowerCase() : root;
+    const targetCmp = process.platform === "win32" ? target.toLowerCase() : target;
+    const rel = relative(rootCmp, targetCmp);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function rootRelativePosixPath(root, target) {
+    const rel = relative(root, target);
+    return rel.replaceAll("\\", "/");
+}
+function normalizeDirectoryPath(pathInput, registeredRoot, realRoot) {
+    const raw = pathInput?.trim();
+    if (raw === undefined || raw.length === 0)
+        return realRoot;
+    if (raw.includes("\0")) {
+        throw new FilesError(400, "BAD_PATH", "The path must stay inside the selected project.");
+    }
+    const candidate = isAbsolute(raw) ? resolve(raw) : resolve(realRoot, raw);
+    if (!isContained(realRoot, candidate) && !isContained(registeredRoot, candidate)) {
+        throw new FilesError(403, "PATH_ESCAPE", "The requested path is outside the selected project.");
+    }
+    return candidate;
+}
+async function resolveDirectoryInsideRoot(store, rootInput, pathInput, redactor) {
+    const root = await resolveRoot(store, rootInput, redactor);
+    const candidate = normalizeDirectoryPath(pathInput, root.root, root.realRoot);
+    const pathValue = await resolveDirectory(candidate);
+    assertMetadataSafe(pathValue, redactor);
+    if (!isContained(root.realRoot, pathValue)) {
+        throw new FilesError(403, "PATH_ESCAPE", "The requested path is outside the selected project.");
+    }
+    const relativePath = rootRelativePosixPath(root.realRoot, pathValue);
+    assertMetadataSafe(relativePath, redactor);
+    if (pathIsDenied(relativePath)) {
+        throw new FilesError(403, "DENIED", DENIED_MESSAGE);
+    }
+    return { ...root, path: pathValue, relativePath };
+}
+async function resolveInsideRoot(store, rootInput, pathInput, redactor) {
+    const root = await resolveRoot(store, rootInput, redactor);
+    const relativePath = normalizeRelativePath(pathInput);
+    assertMetadataSafe(relativePath, redactor);
+    // Deny check runs BEFORE realpath so existence of a denied path is not
+    // observable via the 403/404 status-code difference. A non-existent denied
+    // path returns 403, identical to an existing denied path.
+    if (pathIsDenied(relativePath)) {
+        throw new FilesError(403, "DENIED", DENIED_MESSAGE);
+    }
+    const candidate = nativePath(root.realRoot, relativePath);
+    let target;
+    try {
+        target = await realpath(candidate);
+    }
+    catch {
+        throw new FilesError(404, "NOT_FOUND", "The requested path was not found.");
+    }
+    if (!isContained(root.realRoot, target)) {
+        throw new FilesError(403, "PATH_ESCAPE", "The requested path is outside the selected root.");
+    }
+    const targetRelativePath = rootRelativePosixPath(root.realRoot, target);
+    assertMetadataSafe(targetRelativePath, redactor);
+    if (pathIsDenied(targetRelativePath)) {
+        throw new FilesError(403, "DENIED", DENIED_MESSAGE);
+    }
+    const linkStats = await lstat(candidate);
+    const targetStats = await stat(target);
+    return {
+        root: root.root,
+        realRoot: root.realRoot,
+        relativePath,
+        path: target,
+        stats: targetStats,
+        symlink: linkStats.isSymbolicLink(),
+    };
+}
+async function directoryEntries(root, pathValue, redactor) {
+    const entries = [];
+    const dir = await opendir(pathValue);
+    try {
+        for await (const entry of dir) {
+            if (!entry.isDirectory())
+                continue;
+            const entryPath = join(pathValue, entry.name);
+            const relativePath = rootRelativePosixPath(root, entryPath);
+            if (!metadataIsSafe(relativePath, redactor))
+                continue;
+            if (pathIsDenied(relativePath))
+                continue;
+            entries.push({ name: entry.name, path: entryPath });
+        }
+    }
+    finally {
+        await dir.close().catch(() => undefined);
+    }
+    return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function listFilesDirectories(store, rootInput, pathInput, redactor = staticFilesMetadataRedactor) {
+    const target = await resolveDirectoryInsideRoot(store, rootInput, pathInput, redactor);
+    return {
+        path: target.path,
+        parent: parentPath(target.path, target.realRoot),
+        entries: await directoryEntries(target.realRoot, target.path, redactor),
+        roots: directoryRoots(target.root),
+    };
+}
+function extensionOf(name) {
+    const lower = name.toLowerCase();
+    if (lower === "dockerfile")
+        return "dockerfile";
+    if (lower === ".env" || lower.startsWith(".env."))
+        return "env";
+    const ext = extname(lower).replace(/^\./u, "");
+    return ext.length > 0 ? ext : null;
+}
+async function classifyEntry(root, parentRelativePath, parentNativePath, entry, redactor) {
+    const childRelativePath = parentRelativePath.length === 0 ? entry.name : `${parentRelativePath}/${entry.name}`;
+    assertMetadataSafe(childRelativePath, redactor);
+    const entryPath = join(parentNativePath, entry.name);
+    const linkStats = await lstat(entryPath);
+    const symlink = linkStats.isSymbolicLink();
+    const base = {
+        name: entry.name,
+        path: childRelativePath,
+        sizeBytes: linkStats.size,
+        modifiedAt: linkStats.mtimeMs,
+        extension: extensionOf(entry.name),
+        symlink,
+    };
+    if (!symlink) {
+        const kind = linkStats.isDirectory() ? "directory" : "file";
+        return { ...base, kind, readable: true };
+    }
+    try {
+        const target = await realpath(entryPath);
+        const targetStats = await stat(target);
+        const contained = isContained(root, target);
+        const denied = contained && pathIsDenied(rootRelativePosixPath(root, target));
+        const kind = targetStats.isDirectory()
+            ? "directory"
+            : targetStats.isFile()
+                ? "file"
+                : "symlink";
+        return { ...base, kind, readable: contained && !denied };
+    }
+    catch {
+        return { ...base, kind: "symlink", readable: false };
+    }
+}
+function entryRank(entry) {
+    if (entry.kind === "directory")
+        return 0;
+    if (entry.kind === "file")
+        return 1;
+    return 2;
+}
+function childRelative(parentRelativePath, name) {
+    return parentRelativePath.length === 0 ? name : `${parentRelativePath}/${name}`;
+}
+function skipEntry(rel) {
+    return pathIsDenied(rel);
+}
+async function listTreeEntries(root, relativePath, pathValue, redactor) {
+    const entries = [];
+    const dir = await opendir(pathValue);
+    let truncated = false;
+    try {
+        for await (const entry of dir) {
+            // Deny filtering happens BEFORE the truncation counter so a directory packed with denied
+            // entries (e.g. node_modules/**) cannot exhaust the 1000-entry budget and hide real files
+            // behind `truncated: true`. .gitignore is intentionally not a Files visibility filter:
+            // safe dotfiles and generated files must remain visible and connectable.
+            const rel = childRelative(relativePath, entry.name);
+            if (!metadataIsSafe(rel, redactor))
+                continue;
+            if (skipEntry(rel))
+                continue;
+            if (entries.length >= MAX_DIRECTORY_ENTRIES) {
+                truncated = true;
+                break;
+            }
+            entries.push(await classifyEntry(root, relativePath, pathValue, entry, redactor));
+        }
+    }
+    finally {
+        await dir.close().catch(() => undefined);
+    }
+    entries.sort((a, b) => entryRank(a) - entryRank(b) || a.name.localeCompare(b.name));
+    return { entries, truncated };
+}
+export async function readFilesTree(store, rootInput, pathInput, redactor = staticFilesMetadataRedactor) {
+    const target = await resolveInsideRoot(store, rootInput, pathInput, redactor);
+    if (!target.stats.isDirectory()) {
+        throw new FilesError(400, "NOT_DIRECTORY", "The requested path is not a directory.");
+    }
+    const listed = await listTreeEntries(target.realRoot, target.relativePath, target.path, redactor);
+    return {
+        root: target.root,
+        path: target.relativePath,
+        entries: listed.entries,
+        truncated: listed.truncated,
+    };
+}
+const IMAGE_MIME = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+};
+const TEXT_EXTENSIONS = new Set([
+    "bash",
+    "c",
+    "cjs",
+    "css",
+    "csv",
+    "dockerfile",
+    "env",
+    "go",
+    "graphql",
+    "gql",
+    "gradle",
+    "html",
+    "java",
+    "js",
+    "json",
+    "jsx",
+    "kt",
+    "kts",
+    "md",
+    "mjs",
+    "properties",
+    "py",
+    "rs",
+    "sh",
+    "sql",
+    "toml",
+    "ts",
+    "tsx",
+    "txt",
+    "xml",
+    "yaml",
+    "yml",
+]);
+function mimeOf(extension) {
+    if (extension !== null && IMAGE_MIME[extension] !== undefined)
+        return IMAGE_MIME[extension];
+    if (extension === "json")
+        return "application/json";
+    if (extension === "md")
+        return "text/markdown";
+    if (extension === "html")
+        return "text/html";
+    if (extension === "css")
+        return "text/css";
+    if (isKnownTextExtension(extension))
+        return "text/plain";
+    return "application/octet-stream";
+}
+function isImageExtension(extension) {
+    return extension !== null && IMAGE_MIME[extension] !== undefined;
+}
+function isKnownTextExtension(extension) {
+    return extension !== null && TEXT_EXTENSIONS.has(extension);
+}
+function isLikelyUtf8Text(buffer) {
+    if (buffer.length === 0)
+        return true;
+    if (buffer.includes(0))
+        return false;
+    const decoded = buffer.toString("utf8");
+    if (decoded.includes("\uFFFD"))
+        return false;
+    let printable = 0;
+    for (const char of decoded) {
+        const code = char.charCodeAt(0);
+        if (code === 9 || code === 10 || code === 13 || code >= 32)
+            printable += 1;
+    }
+    return printable / decoded.length > 0.85;
+}
+async function readPrefix(pathValue, maxBytes) {
+    const file = await open(pathValue, "r");
+    try {
+        const buffer = Buffer.allocUnsafe(maxBytes + 1);
+        const result = await file.read(buffer, 0, maxBytes + 1, 0);
+        return {
+            buffer: buffer.subarray(0, Math.min(result.bytesRead, maxBytes)),
+            truncated: result.bytesRead > maxBytes,
+        };
+    }
+    finally {
+        await file.close();
+    }
+}
+async function readBody(req, maxBytes) {
+    return new Promise((resolveBody, reject) => {
+        const chunks = [];
+        let total = 0;
+        let capped = false;
+        req.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > maxBytes) {
+                if (!capped) {
+                    capped = true;
+                    chunks.length = 0;
+                    reject(new BodyTooLargeError());
+                    req.resume();
+                }
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (!capped)
+                resolveBody(Buffer.concat(chunks).toString("utf8"));
+        });
+        req.on("error", reject);
+    });
+}
+export async function readJsonObject(req, maxBytes) {
+    let raw;
+    try {
+        raw = await readBody(req, maxBytes);
+    }
+    catch (error) {
+        if (error instanceof BodyTooLargeError) {
+            return {
+                status: 413,
+                body: errorBody("PAYLOAD_TOO_LARGE", "Request body exceeds the size limit."),
+            };
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = raw.length === 0 ? {} : JSON.parse(raw);
+    }
+    catch {
+        return { status: 400, body: errorBody("BAD_REQUEST", "Request body is not valid JSON.") };
+    }
+    if (!isRecord(parsed)) {
+        return { status: 400, body: errorBody("BAD_REQUEST", "Request body must be a JSON object.") };
+    }
+    return parsed;
+}
+function basePreview(target) {
+    const name = basename(target.relativePath);
+    const extension = extensionOf(name);
+    return {
+        root: target.root,
+        path: target.relativePath,
+        name,
+        sizeBytes: target.stats.size,
+        modifiedAt: target.stats.mtimeMs,
+        extension,
+        mime: mimeOf(extension),
+        symlink: target.symlink,
+    };
+}
+async function imagePreview(target, base) {
+    if (target.stats.size > MAX_IMAGE_PREVIEW_BYTES) {
+        return { ...base, kind: "binary", reason: "too_large", maxBytes: MAX_IMAGE_PREVIEW_BYTES };
+    }
+    const buffer = await readFile(target.path);
+    return {
+        ...base,
+        kind: "image",
+        dataUrl: `data:${base.mime};base64,${buffer.toString("base64")}`,
+        maxBytes: MAX_IMAGE_PREVIEW_BYTES,
+    };
+}
+async function textPreview(target, base, redactor) {
+    const prefix = await readPrefix(target.path, MAX_TEXT_PREVIEW_BYTES);
+    const content = prefix.buffer.toString("utf8");
+    const redacted = redactor(content);
+    return {
+        ...base,
+        kind: "text",
+        content: typeof redacted === "string" ? redacted : content,
+        truncated: prefix.truncated,
+        maxBytes: MAX_TEXT_PREVIEW_BYTES,
+    };
+}
+// Issue #1197: content-free document version. The hash is a one-way SHA-256 of the editable
+// UTF-8 content — it never echoes the content itself.
+function sha256Hex(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+function documentVersion(content, stats) {
+    return { sizeBytes: stats.size, modifiedAt: stats.mtimeMs, contentHash: sha256Hex(content) };
+}
+function editorSession(version) {
+    return { schemaVersion: EDITOR_SESSION_SCHEMA_VERSION, version };
+}
+function statsMatch(left, right) {
+    return left.size === right.size && left.mtimeMs === right.mtimeMs;
+}
+async function readStableEditableContent(target) {
+    let before = target.stats;
+    for (let attempt = 0; attempt < STABLE_CONTENT_READ_ATTEMPTS; attempt += 1) {
+        if (before.size > MAX_TEXT_PREVIEW_BYTES) {
+            throw new FilesError(413, "FILE_TOO_LARGE", `This file is too large to edit here (limit ${String(MAX_TEXT_PREVIEW_BYTES)} bytes).`);
+        }
+        const content = await readFile(target.path, "utf8");
+        const after = await stat(target.path);
+        if (statsMatch(before, after))
+            return { content, stats: after };
+        before = after;
+    }
+    throw new FilesError(409, "STALE_SESSION", "This file changed while it was being opened. Reload it before editing.");
+}
+// Issue #1197: version-aware optimistic concurrency. Rejects a save when the on-disk document no
+// longer matches the revision the editor opened. Size/mtime are compared first so the content is
+// only re-read (bounded by the editable size limit) when those cheap signals match.
+async function assertSessionNotStale(target, baseVersion) {
+    const sizeMatches = target.stats.size === baseVersion.sizeBytes;
+    const mtimeMatches = Math.abs(target.stats.mtimeMs - baseVersion.modifiedAt) <= 1;
+    let hashMatches = false;
+    if (sizeMatches && mtimeMatches && target.stats.size <= MAX_TEXT_PREVIEW_BYTES) {
+        // Bounded re-read (mirrors the content-classification read): if the file grew past the editable
+        // limit between the stat and this read, treat the truncated result as a mismatch.
+        const current = await readPrefix(target.path, MAX_TEXT_PREVIEW_BYTES);
+        hashMatches =
+            !current.truncated && sha256Hex(current.buffer.toString("utf8")) === baseVersion.contentHash;
+    }
+    if (!sizeMatches || !mtimeMatches || !hashMatches) {
+        throw new FilesError(409, "STALE_SESSION", "This file changed since it was opened. Reload it before saving again.");
+    }
+}
+// Optimistic-concurrency gate for a save. The version-aware baseVersion check (Issue #1197)
+// supersedes the legacy mtime-only `expectedModifiedAt` check; either may be absent (forced save).
+async function assertNoWriteConflict(target, baseVersion, expectedModifiedAt) {
+    if (baseVersion !== undefined) {
+        await assertSessionNotStale(target, baseVersion);
+        return;
+    }
+    if (expectedModifiedAt !== undefined && Math.abs(target.stats.mtimeMs - expectedModifiedAt) > 1) {
+        throw new FilesError(409, "WRITE_CONFLICT", "This file changed on disk. Reload it before saving again.");
+    }
+}
+async function editableTextContent(target) {
+    const snapshot = await readStableEditableContent(target);
+    const stableTarget = { ...target, stats: snapshot.stats };
+    const base = basePreview(stableTarget);
+    return {
+        ...base,
+        content: snapshot.content,
+        maxBytes: MAX_TEXT_PREVIEW_BYTES,
+        session: editorSession(documentVersion(snapshot.content, snapshot.stats)),
+    };
+}
+export async function readFilesContent(store, rootInput, pathInput, redactor = staticFilesMetadataRedactor) {
+    const target = await resolveInsideRoot(store, rootInput, pathInput, redactor);
+    if (!target.stats.isFile()) {
+        throw new FilesError(400, "NOT_FILE", "The requested path is not a file.");
+    }
+    const base = basePreview(target);
+    const prefix = await readPrefix(target.path, Math.min(target.stats.size, 4096));
+    if (!isKnownTextExtension(base.extension) && !isLikelyUtf8Text(prefix.buffer)) {
+        throw new FilesError(400, "UNSUPPORTED_FILE", "This file cannot be edited in the workspace.");
+    }
+    return editableTextContent(target);
+}
+async function writeResolvedFilesContent(args) {
+    if (!args.target.stats.isFile()) {
+        throw new FilesError(400, "NOT_FILE", "The requested path is not a file.");
+    }
+    const base = basePreview(args.target);
+    const prefix = await readPrefix(args.target.path, Math.min(args.target.stats.size, 4096));
+    if (!isKnownTextExtension(base.extension) && !isLikelyUtf8Text(prefix.buffer)) {
+        throw new FilesError(400, "UNSUPPORTED_FILE", "This file cannot be edited in the workspace.");
+    }
+    await assertNoWriteConflict(args.target, args.baseVersion, args.expectedModifiedAt);
+    if (Buffer.byteLength(args.content, "utf8") > MAX_TEXT_PREVIEW_BYTES) {
+        throw new FilesError(413, "FILE_TOO_LARGE", `This file is too large to edit here (limit ${String(MAX_TEXT_PREVIEW_BYTES)} bytes).`);
+    }
+    await writeFile(args.target.path, args.content, "utf8");
+    const updatedStats = await stat(args.target.path);
+    return {
+        ...base,
+        sizeBytes: updatedStats.size,
+        modifiedAt: updatedStats.mtimeMs,
+        content: args.content,
+        maxBytes: MAX_TEXT_PREVIEW_BYTES,
+        session: editorSession(documentVersion(args.content, updatedStats)),
+    };
+}
+export async function writeFilesContent(args) {
+    const target = await resolveInsideRoot(args.store, args.rootInput, args.pathInput, args.redactor ?? staticFilesMetadataRedactor);
+    return writeResolvedFilesContent({
+        target,
+        content: args.content,
+        expectedModifiedAt: args.expectedModifiedAt,
+        baseVersion: args.baseVersion,
+    });
+}
+export async function readFilesPreview(store, rootInput, pathInput, redactor = staticFilesMetadataRedactor) {
+    const target = await resolveInsideRoot(store, rootInput, pathInput, redactor);
+    if (!target.stats.isFile()) {
+        throw new FilesError(400, "NOT_FILE", "The requested path is not a file.");
+    }
+    const base = basePreview(target);
+    if (isImageExtension(base.extension))
+        return imagePreview(target, base);
+    const prefix = await readPrefix(target.path, Math.min(target.stats.size, 4096));
+    if (isKnownTextExtension(base.extension) || isLikelyUtf8Text(prefix.buffer)) {
+        return textPreview(target, base, redactor);
+    }
+    return { ...base, kind: "binary", reason: "unsupported" };
+}
+export async function handleFilesDirectories(ctx, deps) {
+    return runFilesHandler(async () => {
+        const requestedRoot = ctx.url.searchParams.get("root");
+        const requestedPath = ctx.url.searchParams.get("path") ?? undefined;
+        return {
+            status: 200,
+            body: await listFilesDirectories(deps.store, requestedRoot, requestedPath, deps.redactor),
+        };
+    });
+}
+export async function handleFilesTree(ctx, deps) {
+    return runFilesHandler(async () => ({
+        status: 200,
+        body: await readFilesTree(deps.store, ctx.url.searchParams.get("root"), ctx.url.searchParams.get("path"), deps.redactor),
+    }));
+}
+export async function handleFilesPreview(ctx, deps) {
+    return runFilesHandler(async () => ({
+        status: 200,
+        body: await readFilesPreview(deps.store, ctx.url.searchParams.get("root"), ctx.url.searchParams.get("path"), deps.redactor),
+    }));
+}
+function readFilesWriteFields(body) {
+    const rootInput = typeof body.root === "string" ? body.root : null;
+    const pathInput = typeof body.path === "string" ? body.path : null;
+    const content = body.content;
+    if (rootInput === null || pathInput === null || typeof content !== "string") {
+        return null;
+    }
+    return { rootInput, pathInput, content };
+}
+async function readFilesContentRoute(ctx, deps) {
+    return {
+        status: 200,
+        body: await readFilesContent(deps.store, ctx.url.searchParams.get("root"), ctx.url.searchParams.get("path"), deps.redactor),
+    };
+}
+async function writeFilesContentRoute(ctx, deps) {
+    const body = await readJsonObject(ctx.req, MAX_TEXT_PREVIEW_BYTES * 2 + 16_384);
+    if (isRouteResult(body))
+        return body;
+    const fields = readFilesWriteFields(body);
+    if (fields === null) {
+        const message = "root, path, and content are required for a file save request.";
+        return { status: 400, body: errorBody("BAD_REQUEST", message) };
+    }
+    const target = await resolveInsideRoot(deps.store, fields.rootInput, fields.pathInput, deps.redactor);
+    let baseVersion;
+    if (body.baseVersion !== undefined) {
+        const parsed = parseEditorDocumentVersion(body.baseVersion);
+        if (!parsed.ok) {
+            return { status: 400, body: errorBody("BAD_REQUEST", "baseVersion is not a valid version.") };
+        }
+        baseVersion = parsed.value;
+    }
+    return {
+        status: 200,
+        body: await writeResolvedFilesContent({
+            target,
+            content: fields.content,
+            expectedModifiedAt: typeof body.expectedModifiedAt === "number" ? body.expectedModifiedAt : undefined,
+            baseVersion,
+        }),
+    };
+}
+export async function handleFilesContent(ctx, deps) {
+    return runFilesHandler(async () => (ctx.req.method ?? "GET").toUpperCase() === "GET"
+        ? readFilesContentRoute(ctx, deps)
+        : writeFilesContentRoute(ctx, deps));
+}