A local-first multi-agent app development platform, built on PenguinHarness
/**
* Server directory browsing:
* GET /api/projects/:p/dirs?path=<absolute>.
*
* Lets the user interactively pick a Workspace directory (the Workspace picker). Defaults to
* the home directory of the account running the service, and can be browsed all the way up
* to the root `/` — reachability is governed by OS file permissions; the server does not
* restrict browsing to within the Project directory tree (same convention as
* workspace-guard). Lists folders and files alike, each with its kind and modification time:
* the picker shows files dimmed so a folder reads as what it holds, and only folders can be
* picked.
*
* A folder the service account may not read is an error with its own code
* (`dir_permission_denied`), never an empty listing: on macOS an unanswered privacy prompt
* (Desktop, Documents, Downloads) looks exactly like that, and an empty list sent people
* looking for files that were there all along.
*
* The home request (no `path`) with `places=1` also answers what the picker's sidebar needs
* and only this machine knows: the standard folders as this machine resolves them (a Desktop
* redirected into OneDrive, a localized `~/桌面`) and its storage locations — Windows drives
* with labels and kinds, macOS volumes, the Linux root and its mounts. Discovery is the
* dir-places service's: time-boxed and cached, so a disconnected network drive never holds a
* listing. The picker asks for places on the request that builds its sidebar and leaves the
* flag off the one that fills its list, so the list never waits on discovery either.
*
* On Windows every listing marks the entries Explorer hides (`hidden: true`): the hidden
* attribute is what keeps `AppData`, `NTUSER.DAT` and the legacy profile junctions — which
* are also access-denied, so a click on one only fails — out of the way, and no Node API reads
* it. A bare drive `D:` is accepted there as `D:\`, as Explorer's address bar does; to Node a
* bare drive is drive-relative and would otherwise be refused as not absolute.
*
* POST /api/projects/:p/dirs makes one folder inside the folder being browsed, which is the
* picker's "New folder": see the route for what it refuses.
*
* DELETE /api/projects/:p/dirs removes one empty folder, the picker's "Delete": see the route
* for what it refuses. It is the picker's only destructive verb, so it takes a folder, never a
* file, and never a whole tree: a folder with anything in it is a refusal, not a walk.
*
* POST /api/projects/:p/dirs/access is the picker's way out of that refusal in the desktop
* app: see the route.
*
* `projectId` remains the authorization anchor: the caller must have access to that Project.
*/
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { Hono } from "hono";
import { projectDir } from "@adelie/core";
import type {
DirAccessResponse,
DirCreateResponse,
DirDeleteResponse,
DirEntryInfo,
DirListResponse,
} from "../../api/types.js";
import type { AppEnv } from "../../auth/middleware.js";
import { HttpError } from "../errors.js";
import { requireValidId } from "../validate.js";
import { Bind, Component, Use } from "@adelie/core/kernel";
import { directorySkillsRoutes } from "./directory-skills.js";
import type { Desktop, DesktopApi, Paths } from "../../hmr/capabilities.js";
import type { Access } from "../../mechanisms/projects.js";
import { discoverLocalPlaces, windowsHiddenNames } from "../../services/dir-places.js";
/** What this route group reaches — bound by its module (src/modules). */
export interface DirsRouteDeps {
access: Access;
/**
* The data root, which holds every Project's own directory: what the delete route refuses to
* remove (a Project's directory, and anything above it).
*/
root: string;
/** The desktop shell's service; null when this server was not started by the desktop shell. */
desktop: Pick<DesktopApi, "requestFolderAccess"> | null;
}
export function dirsRoutes(deps: DirsRouteDeps): Hono<AppEnv> {
const app = new Hono<AppEnv>();
app.get("/", async (c) => {
const projectId = requireValidId(c, "projectId");
deps.access.requireProjectAccess(c.var.user.userId, projectId);
// Default starting point: home directory; an explicit path must be absolute (the frontend always sends back the realpath result).
const raw = c.req.query("path");
const requested = normalizeRequestedDir(raw?.trim() ?? "", process.platform);
const home = requested === "";
// Places answer the home request alone: that is the one the picker makes to build its
// sidebar, and discovering drives on every folder change would be waste.
const places = home && c.req.query("places") === "1";
const real = await resolveBrowsableDir(home ? os.homedir() : requested);
let dirents: import("node:fs").Dirent[];
try {
dirents = await fs.readdir(real, { withFileTypes: true });
} catch (err) {
throw dirReadError(err, real);
}
// The attribute pass and the discovery run beside the per-entry stats, not after them.
const [described, hidden, found] = await Promise.all([
describeEntries(real, dirents),
process.platform === "win32"
? windowsHiddenNames(
real,
dirents.map((d) => d.name),
)
: null,
places ? discoverLocalPlaces() : null,
]);
const entries = described
.map((e): DirEntryInfo => (hidden?.has(e.name) ? { ...e, hidden: true } : e))
.sort((a, b) => a.name.localeCompare(b.name));
const parent = path.dirname(real);
return c.json({
path: real,
parent: parent === real ? null : parent,
entries,
platform: process.platform,
// `standardFolders` stays absent when discovery could not ask the machine, so the
// picker finds them by name; present and empty means there are none.
...(found !== null ? found : {}),
} satisfies DirListResponse);
});
/**
* The picker's "New folder": `parent` is the folder on screen, `name` the single segment to
* make inside it. The name is joined here rather than taken as a path, so a caller cannot
* walk out of the folder it is looking at with a separator or a `..` — the whole point of
* putting the box in the picker is that what it makes lands where the user can see it.
*
* It makes exactly one folder: `recursive` is off, so a typo in `parent` is a 404 rather than
* a silent tree of new folders, and a name already taken is a 409 the picker can point at
* rather than a silent success. 201 with the path made, which is what the picker selects.
*/
app.post("/", async (c) => {
const projectId = requireValidId(c, "projectId");
deps.access.requireProjectAccess(c.var.user.userId, projectId);
const body = (await c.req.json().catch(() => null)) as {
parent?: unknown;
name?: unknown;
} | null;
const parent = typeof body?.parent === "string" ? body.parent.trim() : "";
const name = typeof body?.name === "string" ? body.name.trim() : "";
if (!path.isAbsolute(parent)) {
throw new HttpError(400, "dir_not_absolute", "Directory must be an absolute path.");
}
const bad = dirNameError(name);
if (bad !== null) throw bad;
const target = path.join(parent, name);
try {
await fs.mkdir(target);
} catch (err) {
throw dirCreateError(err, target);
}
return c.json({ path: target } satisfies DirCreateResponse, 201);
});
/**
* The picker's "Delete": removes ONE empty folder, the one `path` names. Removal is the only
* destructive thing the picker can ask of a filesystem it may browse anywhere on, so the
* route is deliberately narrow. The folder must be empty — a folder with anything in it is a
* refusal (`dir_not_empty`), never a walk: no recursive delete exists here. A root, the
* Project's own directory and anything above it are refused outright, and so is a path that
* names a file: this route removes folders.
*
* Every decision reads the resolved path (`realpath`), so a symlink cannot name a forbidden
* folder indirectly, and the answer names the resolved folder — which is the one that was
* removed, and the one a picker standing on a link should re-read.
*/
app.delete("/", async (c) => {
const projectId = requireValidId(c, "projectId");
deps.access.requireProjectAccess(c.var.user.userId, projectId);
const body = (await c.req.json().catch(() => null)) as { path?: unknown } | null;
const requested = typeof body?.path === "string" ? body.path.trim() : "";
if (!path.isAbsolute(requested)) {
throw new HttpError(400, "dir_not_absolute", "Directory must be an absolute path.");
}
let real: string;
let isDir: boolean;
try {
real = await fs.realpath(requested);
isDir = (await fs.stat(real)).isDirectory();
} catch (err) {
throw dirDeleteError(err, requested);
}
if (!isDir) throw new HttpError(400, "not_a_dir", "Not a directory.");
// A root's own parent is itself (`/` on POSIX, `C:\` on Windows). There is nothing above a
// root to stand in afterwards, and every path is under one: a root is never a folder to go.
if (path.dirname(real) === real) {
throw new HttpError(
403,
"dir_root_protected",
`The root directory cannot be deleted: ${real}.`,
);
}
// The Project's own directory holds its config, its Agents and their Sessions, and every
// folder above it holds this Project beside others: neither is the picker's to remove.
if (isSameOrAbove(real, await resolveProjectDir(deps.root, projectId))) {
throw new HttpError(
403,
"dir_project_protected",
`The Project's directory, or one that contains it, cannot be deleted: ${real}.`,
);
}
try {
// Emptiness is asked before the removal, so "not empty" is one answer on every platform
// (Windows reports a folder that still holds something as a permission failure); rmdir
// stays the operation itself, so a folder that fills up in between still fails.
if ((await fs.readdir(real)).length > 0) {
throw new HttpError(409, "dir_not_empty", `The folder is not empty: ${real}.`);
}
await fs.rmdir(real);
} catch (err) {
if (err instanceof HttpError) throw err;
throw dirDeleteError(err, real);
}
return c.json({ path: real } satisfies DirDeleteResponse);
});
/**
* The picker's "Allow access" for a folder macOS refused: the desktop shell's main process
* reads it once in the app's own name, which is what makes macOS ask the user — a read from
* this server, the shell's child, has been seen to fail silently instead. Once the app is
* allowed, this server reads the folder too. Only this server's own shell can be asked, so
* the route has no machine form, and only the desktop app's own window may call it (403
* `desktop_shell_only`, like the reveal route): a browser tab on the same server has no shell
* of its own to ask on the user's behalf. Without a shell there is nothing to ask (503
* `shell_unreachable`); a shell that has not answered within FOLDER_ACCESS_TIMEOUT_MS is a
* 504 `timeout`. The member is optional: a layer older than the picker's box has none.
*/
app.post("/access", async (c) => {
const projectId = requireValidId(c, "projectId");
deps.access.requireProjectAccess(c.var.user.userId, projectId);
if (c.var.sessionVia !== "desktop") {
throw new HttpError(
403,
"desktop_shell_only",
"Asking macOS for a folder is available from the desktop app's own window.",
);
}
const body = (await c.req.json().catch(() => null)) as { path?: unknown } | null;
const target = typeof body?.path === "string" ? body.path.trim() : "";
if (!path.isAbsolute(target)) {
throw new HttpError(400, "dir_not_absolute", "Directory must be an absolute path.");
}
const asked = deps.desktop?.requestFolderAccess?.(target) ?? null;
if (asked === null) {
throw new HttpError(503, "shell_unreachable", "The desktop shell is not listening.");
}
const result = await asked;
if (result === null) {
throw new HttpError(504, "timeout", "The desktop shell did not answer in time.");
}
return c.json({
granted: result.granted,
packaged: result.packaged,
} satisfies DirAccessResponse);
});
return app;
}
/**
* The HTTP answer for a filesystem call that failed on `dir`. A refusal (EACCES, or EPERM —
* what macOS privacy protection returns for a folder the user has not allowed) gets its own
* code so the picker can say so and name where to allow it; a missing path stays the 404 it
* always was.
*/
export function dirReadError(err: unknown, dir: string): HttpError {
const code = (err as NodeJS.ErrnoException | null)?.code;
if (code === "EACCES" || code === "EPERM") {
return new HttpError(
403,
"dir_permission_denied",
`The server is not allowed to read this directory: ${dir}.`,
);
}
if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP") {
return new HttpError(404, "dir_not_found", `Directory does not exist: ${dir}.`);
}
return new HttpError(500, "dir_read_failed", `Could not read this directory: ${dir}.`);
}
/**
* Why a folder name cannot be made, or null when it can. A name is ONE segment: a separator
* (either spelling — a name travels between machines), `.`/`..`, or the empty string would
* either escape the folder on screen or name nothing, and a NUL is not a path at all. What is
* left is checked by the filesystem, not here: a name the platform dislikes (`*` on Windows)
* comes back as a create error, not as this route's own opinion.
*/
export function dirNameError(name: string): HttpError | null {
if (name === "") {
return new HttpError(400, "dir_name_empty", "Enter a folder name.");
}
if (name === "." || name === ".." || /[\\/]/.test(name) || name.includes("\0")) {
return new HttpError(400, "dir_name_invalid", "A folder name cannot be a path, `.` or `..`.");
}
return null;
}
/**
* The HTTP answer for a `mkdir` that failed. "Already there" is its own code so the picker can
* say the name is taken and keep the box open with what was typed; a name the platform refuses
* (a reserved one, a character its filesystem will not hold) is a 400 rather than a 500, since
* it is the input and not the server that is wrong.
*/
export function dirCreateError(err: unknown, target: string): HttpError {
const code = (err as NodeJS.ErrnoException | null)?.code;
if (code === "EEXIST") {
return new HttpError(409, "dir_exists", `Something is already there: ${target}.`);
}
if (code === "EACCES" || code === "EPERM") {
return new HttpError(
403,
"dir_permission_denied",
`The server is not allowed to write here: ${path.dirname(target)}.`,
);
}
if (code === "ENOENT" || code === "ENOTDIR") {
return new HttpError(
404,
"dir_not_found",
`Directory does not exist: ${path.dirname(target)}.`,
);
}
if (code === "EINVAL" || code === "ENAMETOOLONG") {
return new HttpError(400, "dir_name_invalid", `That folder name cannot be used: ${target}.`);
}
return new HttpError(500, "dir_create_failed", `Could not create this folder: ${target}.`);
}
/**
* The HTTP answer for a `rmdir` (or the emptiness check before it) that failed on `dir`. The
* same shape as `dirCreateError`; the one refusal a removal has of its own is a folder that
* still holds something, which is a 409 with its own code because the user's next step differs
* (empty it, or delete nothing at all) — never a retry of the same request.
*/
export function dirDeleteError(err: unknown, target: string): HttpError {
const code = (err as NodeJS.ErrnoException | null)?.code;
if (code === "ENOTEMPTY" || code === "EEXIST") {
return new HttpError(409, "dir_not_empty", `The folder is not empty: ${target}.`);
}
if (code === "EACCES" || code === "EPERM") {
return new HttpError(
403,
"dir_permission_denied",
`The server is not allowed to write here: ${path.dirname(target)}.`,
);
}
if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP") {
return new HttpError(404, "dir_not_found", `Directory does not exist: ${target}.`);
}
return new HttpError(500, "dir_delete_failed", `Could not delete this folder: ${target}.`);
}
/**
* Whether `above` is `below` itself or one of the folders holding it — what the Project
* directory's protection is made of. Both sides are resolved first, so a trailing separator,
* a `.`/`..` in the middle and a doubled separator all compare as the folder they name.
*/
export function isSameOrAbove(above: string, below: string): boolean {
const a = path.resolve(above);
const b = path.resolve(below);
return a === b || b.startsWith(a.endsWith(path.sep) ? a : `${a}${path.sep}`);
}
/**
* The Project's own directory, resolved where it exists. The data root itself may be reached
* through a symlink (`/tmp` and `/var` are on macOS, and an operator may point `ADELIE_HOME`
* at one), so comparing a caller's path against the spelling `<root>/<projectId>` alone would
* mistake a link to that folder for somewhere else.
*/
async function resolveProjectDir(root: string, projectId: string): Promise<string> {
const dir = projectDir(root, projectId);
try {
return await fs.realpath(dir);
} catch {
return path.resolve(dir);
}
}
/**
* `requireProjectDir` with the refusal told apart from absence. That helper folds every
* failure into "does not exist or is inaccessible", which is the right answer where a path is
* being validated; here it is the question being asked.
*/
async function resolveBrowsableDir(target: string): Promise<string> {
if (!path.isAbsolute(target)) {
throw new HttpError(400, "dir_not_absolute", "Directory must be an absolute path.");
}
let real: string;
let isDir: boolean;
try {
real = await fs.realpath(target);
isDir = (await fs.stat(real)).isDirectory();
} catch (err) {
throw dirReadError(err, target);
}
if (!isDir) throw new HttpError(400, "not_a_dir", "Not a directory.");
return real;
}
/**
* Past this many entries only the dirent is read: a stat per entry is what gives a symlink
* its target's kind and every row its time, and a folder of tens of thousands of files would
* otherwise hold the listing for seconds. Beyond it, a symlink to a folder reads as a file.
*/
const STAT_LIMIT = 5000;
/**
* Kind and modification time for each entry. stat follows symlinks, so a link to a folder is
* browsable like one; an entry stat cannot reach (a dangling link, a refused one) keeps the
* dirent's kind and no time rather than failing the whole folder.
*/
async function describeEntries(
dir: string,
dirents: import("node:fs").Dirent[],
): Promise<DirEntryInfo[]> {
return Promise.all(
dirents.map(async (d, index): Promise<DirEntryInfo> => {
const full = path.join(dir, d.name);
let isDir = d.isDirectory();
let mtime: number | undefined;
if (index < STAT_LIMIT) {
try {
const st = await fs.stat(full);
isDir = st.isDirectory();
mtime = Math.round(st.mtimeMs);
} catch {
// Keep the dirent's answer.
}
}
return {
name: d.name,
path: full,
kind: isDir ? "dir" : "file",
...(mtime !== undefined ? { mtime } : {}),
};
}),
);
}
/**
* A bare drive (`D:`, `d:`) typed on Windows means that drive's root, as it does in Explorer's
* address bar. To Node it is drive-relative — `path.isAbsolute("D:")` is false — so without
* this it would be refused as not absolute. Pure; exported for the unit test.
*/
export function normalizeRequestedDir(requested: string, platform: string): string {
return platform === "win32" && /^[A-Za-z]:$/.test(requested) ? `${requested}\\` : requested;
}
/** The Project-scoped directory routes; the repos and the access check are components of their own. */
@Component({
contributes: {
"HttpModule.routes": [
{
id: "projects.dirs",
prefix: "/api/projects/:projectId/dirs",
auth: "user",
order: 150,
},
{
id: "projects.dir-skills",
prefix: "/api/projects/:projectId/dir-skills",
auth: "user",
order: 160,
},
],
},
})
export class ProjectsRoutes {
@Use() private readonly access!: Access;
@Use() private readonly desktop!: Desktop;
@Use() private readonly paths!: Paths;
@Bind("projects.dirs") dirsRoutes!: Hono<AppEnv>;
@Bind("projects.dir-skills") dirSkillsRoutes!: Hono<AppEnv>;
setup() {
this.dirsRoutes = dirsRoutes({
access: this.access,
root: this.paths.root,
desktop: this.desktop.current(),
});
this.dirSkillsRoutes = directorySkillsRoutes({ access: this.access });
}
}