@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/routes/fs/read.ts

@@ -0,0 +1,324 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { json, type LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { listDirectoryEntries } from '@/server/lib/fs/listing';
+import { errorResponse } from '@/server/lib/route-adapter';
+import { homedir } from 'os';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import fs from 'fs';
+import path from 'path';
+import { isMockMode } from '@/server/mock.server';
+import { getDefaultFsRoot, resolveReferencedPath, resolveRoot, resolveWithinRoot } from '@/server/lib/fs/root';
+import {
+  BINARY_SNIFF_BYTES,
+  classifyEditorFile,
+  unsupportedEditorMessage,
+  type EditorFileKind,
+} from '@/shared/lib/fs/file-kind';
+
+/**
+ * Classify a file the way the editor will, reading only as many bytes as the
+ * sniff needs.
+ *
+ * The head is sliced rather than the whole file read, so the check costs 8 KiB
+ * on a 4 GiB archive. `size` is passed in because the caller already has the
+ * stat, and a file refused for size must not be read at all.
+ */
+async function classifyForEditor(fullPath: string, displayPath: string, size: number): Promise<EditorFileKind> {
+  // An image and an oversize file are both settled by path and size alone; only
+  // a candidate TEXT file needs its head.
+  const provisional = classifyEditorFile({ path: displayPath, size });
+  if (provisional !== 'text') return provisional;
+  const head = await Bun.file(fullPath).slice(0, BINARY_SNIFF_BYTES).bytes();
+  return classifyEditorFile({ path: displayPath, size, head });
+}
+
+/**
+ * GET /api/fs/browse?path=<abs> — list subdirectories of a folder for the
+ * workspace folder picker.
+ *
+ * Starts from the OS home directory when `path` is omitted. Only directories
+ * are returned (a workspace is bound to a project root folder). Navigation is
+ * confined to real absolute paths; entries that cannot be read are skipped so
+ * one permission-denied folder does not break the whole listing.
+ *
+ * Response: { path, parentPath, directories: [{ name, path }] }
+ */
+const HIDDEN_ENTRY_PREFIXES = ['.', 'node_modules', 'Library'];
+
+export async function browseDirectories({ request }: LoaderFunctionArgs) {
+  const url = new URL(request.url);
+  const rawPath = url.searchParams.get('path');
+  const home = homedir();
+
+  let current: string;
+  if (rawPath) {
+    const candidate = rawPath.startsWith('~/')
+      ? join(home, rawPath.slice(2))
+      : rawPath === '~'
+        ? home
+        : rawPath;
+    if (!isAbsolute(candidate)) {
+      return json({ error: 'Path must be absolute', code: 'not_absolute' }, { status: 400 });
+    }
+    current = resolve(candidate);
+  } else {
+    current = home;
+  }
+
+  let names: string[] = [];
+  try {
+    // `isDirectory()` on the dirent is the whole test: `readdir` fills it from
+    // the entry's own type, and it is false for a symlink (even one pointing at
+    // a directory), which is the "real directories only" rule. Re-statting each
+    // survivor through `Bun.file().stat()` answered the same question a second
+    // time for 34 µs per listing (measured 0.067 ms → 0.033 ms per 200 calls).
+    names = (await fs.promises.readdir(current, { withFileTypes: true }))
+      .filter((d) => d.isDirectory() && !HIDDEN_ENTRY_PREFIXES.some((p) => d.name.startsWith(p)))
+      .map((d) => d.name);
+  } catch {
+    return json({ error: `Cannot read directory: ${current}`, code: 'unreadable' }, { status: 400 });
+  }
+
+  const directories = names
+    .map((name) => ({ name, path: join(current, name) }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  const parent = current === home ? null : dirname(current);
+  return json({
+    path: current,
+    parentPath: parent === current ? null : parent,
+    directories,
+  });
+}
+
+/**
+ * Names never listed in the Files panel: dependency/build output and the git
+ * object database. Skipped for being noise, not for being hidden — every other
+ * entry is listed, dot-prefixed files and folders included.
+ */
+
+// Lazy listing: return only the immediate children of a directory. Folders are
+// emitted with `children: null` meaning "not loaded yet" so the client can
+// fetch them on demand — directories are NOT recursed here (keeps the initial
+// payload tiny for deep workspaces). Hidden (dot-prefixed) entries are part of
+// the listing: lazy children keep `.github`, `.config`, `.env`, … cheap.
+// Entries git would refuse to track carry `ignored: true` so the panel can dim
+// them; that is one `git check-ignore` per listing, never one per entry.
+export async function listDirectory({ request }: LoaderFunctionArgs) {
+  const url = new URL(request.url);
+  const mock = isMockMode();
+  let baseDir = await resolveRoot(url.searchParams.get('root'), await getDefaultFsRoot(mock));
+
+  // Browse inside a nested git repo; emitted paths are repo-relative to match GitPanel.
+  const repo = url.searchParams.get('repo');
+  if (repo && repo !== '.') {
+    const repoDir = resolveWithinRoot(baseDir, repo);
+    if (!repoDir) {
+      return json({ error: 'Invalid repo path' }, { status: 403 });
+    }
+    baseDir = repoDir;
+  }
+
+  const targetPath = url.searchParams.get('path') || '.';
+  const fullPath = resolveWithinRoot(baseDir, targetPath);
+
+  // Security check to prevent traversing outside the scoped root
+  if (!fullPath) {
+    return json({ error: 'Invalid path' }, { status: 403 });
+  }
+
+  try {
+    const files = await listDirectoryEntries(fullPath, baseDir);
+    return json({ files, isMock: mock, root: baseDir, path: targetPath });
+  } catch (error) {
+    console.error(error);
+    return json({ error: 'Failed to read directory', isMock: mock }, { status: 500 });
+  }
+}
+
+/** Hard cap on emitted files so a huge tree cannot stall the request. */
+const MAX_FILES = 3000;
+
+/** Directory names that are never recursed into. */
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', 'coverage']);
+
+interface ListFileEntry {
+  name: string;
+  path: string;
+}
+
+/**
+ * Recursively collect files under `dir`, emitting each as a workspace-relative
+ * path from `baseDir`. Hidden entries, skip-listed dirs, and symlinks (which
+ * could cycle) are ignored; unreadable directories are skipped silently.
+ */
+async function walk(dir: string, baseDir: string, out: ListFileEntry[]): Promise<void> {
+  if (out.length >= MAX_FILES) return;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = await fs.promises.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (out.length >= MAX_FILES) return;
+
+    if (entry.name.startsWith('.')) continue;
+
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      await walk(path.join(dir, entry.name), baseDir, out);
+      continue;
+    }
+
+    // Emit only regular files: symlinks (to files or dirs) are skipped so a
+    // directory symlink cannot introduce a cycle.
+    if (!entry.isFile()) continue;
+
+    const rel = path.relative(baseDir, path.join(dir, entry.name)).split(path.sep).join('/');
+    out.push({ name: entry.name, path: rel });
+  }
+}
+
+export async function listFiles({ request }: LoaderFunctionArgs) {
+  const url = new URL(request.url);
+  const mock = isMockMode();
+  const baseDir = await resolveRoot(url.searchParams.get('root'), await getDefaultFsRoot(mock));
+
+  try {
+    const files: ListFileEntry[] = [];
+    await walk(baseDir, baseDir, files);
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return json({ files, root: baseDir, truncated: files.length >= MAX_FILES });
+  } catch (error) {
+    console.error(error);
+    return json({ error: 'Failed to list files' }, { status: 500 });
+  }
+}
+
+export async function readFile({ request }: LoaderFunctionArgs) {
+  const url = new URL(request.url);
+  const filePath = url.searchParams.get('path');
+
+  if (!filePath) {
+    return json({ error: 'Missing path' }, { status: 400 });
+  }
+  let baseDir = await resolveRoot(url.searchParams.get('root'), await getDefaultFsRoot(isMockMode()));
+
+  // If repo is specified (e.g. nested git project), resolve inside the repo
+  const repo = url.searchParams.get('repo');
+  if (repo && repo !== '.') {
+    const repoDir = resolveWithinRoot(baseDir, repo);
+    if (repoDir) {
+      baseDir = repoDir;
+    }
+  }
+
+  const cleanPath = filePath.replace(/^\/+/, '');
+  const fullPath = resolveWithinRoot(baseDir, cleanPath);
+
+  if (!fullPath) {
+    return json({ error: 'Invalid path' }, { status: 403 });
+  }
+
+  try {
+    const file = Bun.file(fullPath);
+    if (!(await file.exists())) {
+      return json({ error: 'File not found' }, { status: 404 });
+    }
+    const stat = await file.stat();
+    if (stat.isDirectory()) {
+      return json({ error: 'Cannot read a directory' }, { status: 400 });
+    }
+
+    // An image has no text: decoding its bytes here returned replacement
+    // characters, which every reader painted as mojibake. Every in-repo reader
+    // branches on the extension first and takes `/api/fs/raw`, so this answers
+    // the remaining callers with the real reason instead of garbage.
+    //
+    // A document (PDF/DOCX/XLSX) is the same answer for the same reason — its
+    // viewer fetches the bytes from the raw route — but a DIFFERENT sentence:
+    // "served by /api/fs/raw" tells the caller where to look, and a document is
+    // not an image.
+    //
+    // A binary or oversized file is refused the same way, and the refusal is
+    // the point rather than a nicety: the editor's buffer is empty on a failed
+    // read, and Save is only disabled by `loadError`. Answering with mojibake
+    // left a buffer the next save wrote straight back over the real file.
+    const kind = await classifyForEditor(fullPath, cleanPath, stat.size);
+    if (kind === 'image' || kind === 'document') {
+      return json({ error: 'This file is served by /api/fs/raw' }, { status: 400 });
+    }
+    if (kind !== 'text') {
+      return json(
+        { error: unsupportedEditorMessage(kind, stat.size, cleanPath), kind },
+        { status: 415 },
+      );
+    }
+
+    const content = await file.text();
+    return json({ content });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}
+
+/**
+ * GET /api/fs/read-reference?path=<abs path or URL> — read a file a drop or a
+ * link pointed at.
+ *
+ * A download dragged out of a web page (WhatsApp Web, Gmail, Slack) carries no
+ * bytes, only a reference, and the page cannot fetch a `file://` path itself.
+ * The path is therefore resolved against the same allow-list that governs a
+ * client-supplied `root` — the app root, a path beneath it, or a registered
+ * workspace — so this cannot be used to read an arbitrary file.
+ *
+ * Text only: an image or binary has no string form to return, and the drop's
+ * own `File` is the path that carries those.
+ */
+export async function readReferencedFile({ request }: LoaderFunctionArgs) {
+  const url = new URL(request.url);
+  const reference = url.searchParams.get('path');
+  if (!reference) {
+    return json({ error: 'Missing path' }, { status: 400 });
+  }
+
+  // A remote reference is not fetched here: Kabmo has no policy for
+  // outbound requests and a drag from a page is not a reason to add one.
+  if (/^https?:\/\//i.test(reference)) {
+    return json({ error: 'Remote references are not supported' }, { status: 400 });
+  }
+
+  const filePath = await resolveReferencedPath(reference.replace(/^file:\/\//, ''));
+  if (!filePath) {
+    return json({ error: 'File not found' }, { status: 404 });
+  }
+
+  try {
+    const file = Bun.file(filePath);
+    const stat = await file.stat();
+    if (stat.isDirectory()) {
+      return json({ error: 'Cannot read a directory' }, { status: 400 });
+    }
+    // Same classification as `/api/fs/read`: a binary or oversized reference is
+    // refused with its reason rather than handed back as mojibake. A document
+    // has no text form either — its viewer takes the bytes from the drop's own
+    // `File`, not from this route.
+    const kind = await classifyForEditor(filePath, filePath, stat.size);
+    if (kind === 'image' || kind === 'document') {
+      return json({ error: 'This file is served by /api/fs/raw' }, { status: 400 });
+    }
+    if (kind !== 'text') {
+      return json({ error: unsupportedEditorMessage(kind, stat.size, filePath), kind }, { status: 415 });
+    }
+    return json({ content: await file.text(), name: path.basename(filePath) });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}

package/src/server/routes/fs/replace.ts

@@ -0,0 +1,69 @@
+import { json, type ActionFunctionArgs } from '@/server/lib/remix-compat';
+import path from 'path';
+import { isMockMode } from '@/server/mock.server';
+import { getDefaultFsRoot, resolveRoot } from '@/server/lib/fs/root';
+import { scopeToRepo } from '@/server/lib/fs/repo-scope';
+
+export async function action({ request }: ActionFunctionArgs) {
+  const formData = await request.formData();
+  const q = formData.get('q') as string;
+  const replaceWith = formData.get('replaceWith') as string;
+  const matchCase = formData.get('matchCase') === 'true';
+  const wholeWord = formData.get('wholeWord') === 'true';
+  const useRegex = formData.get('useRegex') === 'true';
+  const fileToReplace = formData.get('file') as string; // Optional: specific file to replace in
+  const filesString = formData.get('files') as string; // Comma separated list of files to replace in
+
+  if (!q) {
+    return json({ error: 'Query is required' }, { status: 400 });
+  }
+
+  try {
+    const baseDir = await resolveRoot(formData.get('root') as string, await getDefaultFsRoot(isMockMode()));
+    const targetDir = await scopeToRepo(baseDir, formData.get('repo') as string);
+    let filesToProcess: string[] = [];
+
+    if (fileToReplace) {
+      filesToProcess = [fileToReplace];
+    } else if (filesString) {
+      filesToProcess = JSON.parse(filesString);
+    } else {
+       return json({ error: 'No files provided for replacement' }, { status: 400 });
+    }
+
+    // Build the regex for replacement
+    let regexStr = useRegex ? q : q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // Escape regex if not using regex
+    if (wholeWord) {
+      regexStr = `\\b${regexStr}\\b`;
+    }
+    
+    const flags = matchCase ? 'g' : 'gi';
+    const regex = new RegExp(regexStr, flags);
+
+    const results = [];
+
+    for (const relFile of filesToProcess) {
+      // Prevent directory traversal
+      if (relFile.includes('..') || relFile.startsWith('/')) continue;
+      
+      const fullPath = path.join(targetDir, relFile);
+      
+      try {
+        const content = await Bun.file(fullPath).text();
+        if (regex.test(content)) {
+          const newContent = content.replace(regex, replaceWith || '');
+          await Bun.write(fullPath, newContent);
+          results.push({ file: relFile, status: 'success' });
+        }
+      } catch (err) {
+        console.error(`Failed to replace in ${relFile}:`, err);
+        results.push({ file: relFile, status: 'error' });
+      }
+    }
+
+    return json({ success: true, results });
+  } catch (error: any) {
+    console.error(error);
+    return json({ error: String(error) }, { status: 500 });
+  }
+}

package/src/server/routes/fs/scope.test.ts

@@ -0,0 +1,171 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The scope route: turning an absolute path (a drop, a `file://` URL) into the
+ * `root` + relative path the editor panel speaks.
+ *
+ * The load-bearing claims are about the ALLOW-LIST and about the deepest-root
+ * rule: a path outside every registered workspace is refused by name rather
+ * than answered with a scope the reader would then reject, and a path inside a
+ * NESTED workspace resolves against that workspace instead of the directory
+ * that contains it (otherwise the relative path names a file no panel is
+ * scoped to).
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import path from 'path';
+import { testPosix } from '@/test-support/platform';
+import { resolveFileScope } from '@/server/routes/fs/scope';
+import { DOCUMENT_MAX_FILE_BYTES, PDF_MAX_FILE_BYTES } from '@/shared/lib/fs/file-kind';
+
+const APP = process.cwd();
+const DIR = path.join(APP, 'tmp-scope-probe');
+
+afterEach(() => {
+  fs.rmSync(DIR, { recursive: true, force: true });
+});
+
+async function scope(rawPath: string) {
+  const url = new URL('http://localhost/api/fs/scope');
+  url.searchParams.set('path', rawPath);
+  const res = await resolveFileScope({ request: new Request(url) } as never);
+  return { status: res.status, body: (await res.json()) as { root?: string; path?: string; name?: string; kind?: string; error?: string } };
+}
+
+function write(relPath: string, content: string | Uint8Array) {
+  const target = path.join(DIR, relPath);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content);
+  return target;
+}
+
+describe('fs scope route', () => {
+  test('an absolute path inside the app root resolves to a relative scope', async () => {
+    const target = write('notes.md', '# hi\n');
+    const { status, body } = await scope(target);
+
+    expect(status).toBe(200);
+    expect(body.root).toBe(APP);
+    expect(body.path).toBe('tmp-scope-probe/notes.md');
+    expect(body.name).toBe('notes.md');
+    expect(body.kind).toBe('text');
+  });
+
+  // A `file://` reference decodes to a `/`-rooted pathname (`pathFromReference`
+  // returns `new URL(reference).pathname`); on Windows that `/` is resolved
+  // against the current drive, so a dropped `C:\…` path never lands under the
+  // app root and the route answers 403 rather than the scope it means.
+  testPosix('a file:// URL is decoded, spaces and all', async () => {
+    const target = write('My Notes.md', '# spaced\n');
+    const { status, body } = await scope(`file://${target.replace(/ /g, '%20')}`);
+
+    expect(status).toBe(200);
+    expect(body.path).toBe('tmp-scope-probe/My Notes.md');
+    expect(body.name).toBe('My Notes.md');
+  });
+
+  test('a binary file is classified as binary, with the reason', async () => {
+    const target = write('blob.bin', new Uint8Array([0x00, 0x01, 0x02, 0x03]));
+    const { status, body } = await scope(target);
+
+    expect(status).toBe(200);
+    expect(body.kind).toBe('binary');
+    expect(body.error).toContain('not text');
+  });
+
+  test('an image is classified as an image, which is openable', async () => {
+    const target = write('shot.png', new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+    const { status, body } = await scope(target);
+
+    expect(status).toBe(200);
+    expect(body.kind).toBe('image');
+    expect(body.error).toBeUndefined();
+  });
+
+  test('a path outside every workspace is refused by name', async () => {
+    const { status, body } = await scope('/etc/hosts');
+
+    expect(status).toBe(403);
+    expect(body.error).toContain('outside every workspace');
+  });
+
+  test('a folder is refused as a folder, not resolved', async () => {
+    const dir = path.join(DIR, 'sub');
+    fs.mkdirSync(dir, { recursive: true });
+    const { status, body } = await scope(dir);
+
+    expect(status).toBe(400);
+    expect(body.error).toContain('folder');
+  });
+
+  test('a missing file is a 404, not a scope with no file behind it', async () => {
+    const { status } = await scope(path.join(DIR, 'ghost.ts'));
+
+    expect(status).toBe(404);
+  });
+
+  test('a missing path parameter is a 400', async () => {
+    const url = new URL('http://localhost/api/fs/scope');
+    const res = await resolveFileScope({ request: new Request(url) } as never);
+
+    expect(res.status).toBe(400);
+  });
+
+  // The drop target refuses a file the editor cannot open, using this route's
+  // `kind`. A PDF past the text ceiling must come back `document` — refusing it
+  // is what made a dropped 6 MB PDF report "larger than the 5.00 MB the editor
+  // opens" instead of opening, even though its viewer streams the bytes.
+  test('a PDF past the text ceiling is still openable, not refused', async () => {
+    const target = write('big.pdf', new Uint8Array(6 * 1024 * 1024).fill(0x25));
+    const { status, body } = await scope(target);
+
+    expect(status).toBe(200);
+    expect(body.kind).toBe('document');
+    expect(body.error).toBeUndefined();
+  });
+
+  test('a PDF past the PDF ceiling is refused against 30 MB', async () => {
+    const target = write('huge.pdf', new Uint8Array(PDF_MAX_FILE_BYTES + 1).fill(0x25));
+    const { status, body } = await scope(target);
+
+    expect(status).toBe(200);
+    expect(body.kind).toBe('too-large');
+    expect(body.error).toContain('30.00 MB');
+  });
+
+  // The document ceiling is not the text ceiling: a DOCX is parsed in the page,
+  // but only for the conversion, so it opens well past 5 MB and is refused
+  // against 20 MB.
+  test('a DOCX past the text ceiling is still openable', async () => {
+    const target = write('big.docx', new Uint8Array(6 * 1024 * 1024).fill(0x50));
+    const { status, body } = await scope(target);
+
+    expect(status).toBe(200);
+    expect(body.kind).toBe('document');
+    expect(body.error).toBeUndefined();
+  });
+
+  test('a DOCX past the document ceiling is refused against 20 MB', async () => {
+    const target = write('huge.docx', new Uint8Array(DOCUMENT_MAX_FILE_BYTES + 1).fill(0x50));
+    const { status, body } = await scope(target);
+
+    expect(status).toBe(200);
+    expect(body.kind).toBe('too-large');
+    expect(body.error).toContain('20.00 MB');
+  });
+
+  // Plain text keeps the text ceiling: a textarea holds that buffer for the
+  // life of the tab, which is why its limit did not move with the documents'.
+  test('a text file past the text ceiling is still refused', async () => {
+    const target = write('big.log', new Uint8Array(6 * 1024 * 1024).fill(0x61));
+    const { status, body } = await scope(target);
+
+    expect(status).toBe(200);
+    expect(body.kind).toBe('too-large');
+    expect(body.error).toContain('5.00 MB');
+  });
+});

package/src/server/routes/fs/scope.ts

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * GET /api/fs/scope?path=<abs path or file:// URL> — turn an absolute path into
+ * the scope the editor panel speaks.
+ *
+ * A file dropped on the editor is named absolutely: a file manager cannot know
+ * which workspace the page considers active, and the same is true of a path
+ * handed over by the OS. Every other surface in Kabmo works from
+ * `root` + a path RELATIVE to it, and the read and save routes resolve that
+ * pair back through the same allow-list this route applies. So a drop has to be
+ * translated once, here, rather than teaching the editor a second path shape it
+ * would then have to keep in sync with every save.
+ *
+ * The allow-list is the point, not an obstacle: `/api/fs/read` refuses a `root`
+ * it does not recognise, so answering with a scope the reader will reject is
+ * worse than refusing now — the refusal can name the reason.
+ *
+ * The file's KIND travels with the answer so the drop target can decline a
+ * binary or oversized file before opening a tab that would only report it.
+ */
+
+import { json, type LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { resolveScopeForAbsolutePath } from '@/server/lib/fs/root';
+import { BINARY_SNIFF_BYTES, classifyEditorFile, unsupportedEditorMessage } from '@/shared/lib/fs/file-kind';
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * A `file://` URL to the path it names.
+ *
+ * The pathname is percent-encoded (a space is `%20`, and a Finder drop of
+ * `My Notes.md` is exactly that), so decoding is not optional. `decodeURIComponent`
+ * can throw on a malformed escape, which is answered as "not a path" rather
+ * than surfacing as a 500.
+ */
+function pathFromReference(reference: string): string | null {
+  if (!/^file:\/\//i.test(reference)) return reference;
+  try {
+    const url = new URL(reference);
+    return decodeURIComponent(url.pathname);
+  } catch {
+    return null;
+  }
+}
+
+export async function resolveFileScope({ request }: LoaderFunctionArgs) {
+  const url = new URL(request.url);
+  const raw = url.searchParams.get('path');
+  if (!raw) {
+    return json({ error: 'Missing path' }, { status: 400 });
+  }
+
+  const reference = pathFromReference(raw);
+  if (!reference) {
+    return json({ error: 'Malformed file URL' }, { status: 400 });
+  }
+
+  const scope = await resolveScopeForAbsolutePath(reference);
+  if (!scope) {
+    return json(
+      { error: 'That file is outside every workspace this console can read.' },
+      { status: 403 },
+    );
+  }
+
+  const fullPath = path.resolve(scope.root, scope.path);
+  // `Bun.file().exists()` is false for a directory, so a folder dropped on the
+  // editor would be answered "File not found" — true as far as the file is
+  // concerned, and useless to the user. `statSync` sees either shape, so the
+  // refusal can name the folder it actually is.
+  const stat = await fs.promises.stat(fullPath).catch(() => null);
+  if (!stat) {
+    return json({ error: 'File not found' }, { status: 404 });
+  }
+  if (stat.isDirectory()) {
+    return json({ error: 'That is a folder, not a file.' }, { status: 400 });
+  }
+
+  // The same classification the read route applies, so the drop can refuse what
+  // the reader would: a binary or oversized file is answered as such here
+  // instead of opening a tab whose whole content is a refusal message.
+  const file = Bun.file(fullPath);
+  const provisional = classifyEditorFile({ path: scope.path, size: stat.size });
+  const kind = provisional === 'text'
+    ? classifyEditorFile({
+        path: scope.path,
+        size: stat.size,
+        head: await file.slice(0, BINARY_SNIFF_BYTES).bytes(),
+      })
+    : provisional;
+
+  return json({
+    root: scope.root,
+    path: scope.path,
+    name: path.basename(scope.path),
+    kind,
+    size: stat.size,
+    ...(kind === 'binary' || kind === 'too-large'
+      ? { error: unsupportedEditorMessage(kind, stat.size, scope.path) }
+      : {}),
+  });
+}