@vincemakes/kiso-web 0.0.0-stage → 0.53.0

package/dist/main/desk-api.js

@@ -0,0 +1,249 @@
+import { realpathSync, statSync } from "node:fs";
+import { basename } from "node:path";
+import { canonicalPath, claimProjectDir, projectDirFor } from "@vincemakes/kiso-code/config";
+import { atFiles, deskRead, SAFE_ID } from "./fs-routes.js";
+import { contextParts } from "./context.js";
+import { rename } from "./names.js";
+import { forkWork } from "./fork.js";
+import { WORK_ACTS, workAct } from "./works.js";
+import { commit, gitOf, openPr, prDraft } from "./git.js";
+import { existing, Refusal, resolveInside } from "./files.js";
+import { artifactKind } from "./artifacts.js";
+import { listDirs, validateFolder } from "./folders.js";
+import { folderInfo } from "./folder-info.js";
+const json = (status, body) => ({ status, body });
+const BODY_CAP = 16 * 1024;
+async function readJson(req) {
+    let text = "";
+    for await (const chunk of req) {
+        text += chunk;
+        if (text.length > BODY_CAP)
+            throw new Refusal(413, "too large");
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed))
+            return parsed;
+    }
+    catch {
+        // fall through
+    }
+    throw new Refusal(400, "a JSON object is expected");
+}
+const str = (v) => (typeof v === "string" ? v : undefined);
+export async function deskApi(ctx, req, url) {
+    const path = url.pathname;
+    const where = url.searchParams.get("key");
+    const space = where === null || where === "" ? ctx.current : ctx.spaceFor(where);
+    const post = req.method === "POST";
+    try {
+        if (path === "/desk/at-files") {
+            if (space === null)
+                return json(404, {});
+            return req.method === "GET" ? json(200, atFiles(space)) : json(405, {});
+        }
+        if (path === "/desk/context") {
+            if (space === null)
+                return json(404, {});
+            const session = url.searchParams.get("session") ?? undefined;
+            let window = null;
+            try {
+                const m = ctx.settings.model(session === undefined ? undefined : { sessionId: session, sessionsDir: space.dir });
+                window = m.kind === "profile" ? (m.contextWindow ?? null) : null;
+            }
+            catch {
+                // no model: the parts are still known, the compaction sizes are not
+            }
+            return req.method === "GET" ? json(200, contextParts(space.workspace, ctx.settings.tierOf(session), window)) : json(405, {});
+        }
+        if (path === "/desk/git") {
+            if (space === null)
+                return json(404, {});
+            return req.method === "GET" ? json(200, url.searchParams.has("draft") ? await prDraft(space.workspace) : await gitOf(space.workspace)) : json(405, {});
+        }
+        if (path === "/desk/commit" || path === "/desk/pr") {
+            if (!post)
+                return json(405, {});
+            if (space === null)
+                return json(404, {});
+            const body = await readJson(req);
+            if (path === "/desk/commit")
+                return json(200, await commit(space.workspace, str(body["message"]) ?? "", Array.isArray(body["paths"]) ? body["paths"].filter((p) => typeof p === "string") : []));
+            return json(200, await openPr(space.workspace, str(body["title"]) ?? "", str(body["body"]) ?? ""));
+        }
+        if (path === "/desk/rename") {
+            if (!post)
+                return json(405, {});
+            if (space === null)
+                return json(404, {});
+            const body = await readJson(req);
+            const session = str(body["session"]) ?? "";
+            if (!SAFE_ID.test(session) || !space.store.ids().includes(session))
+                return json(404, {});
+            return json(200, { name: rename(space.dir, session, str(body["name"]) ?? "") });
+        }
+        if (path === "/desk/fork") {
+            if (!post)
+                return json(405, {});
+            if (space === null)
+                return json(404, {});
+            const body = await readJson(req);
+            const session = str(body["session"]) ?? "";
+            if (!SAFE_ID.test(session))
+                return json(404, {});
+            const atSeq = typeof body["atSeq"] === "number" ? body["atSeq"] : undefined;
+            return json(200, { id: forkWork(space, ctx.settings, session, atSeq).id });
+        }
+        if (path === "/desk/work") {
+            if (!post)
+                return json(405, {});
+            if (space === null)
+                return json(404, {});
+            const body = await readJson(req);
+            const session = str(body["session"]) ?? "";
+            const act = str(body["act"]) ?? "";
+            if (!SAFE_ID.test(session) || !WORK_ACTS.includes(act))
+                return json(404, {});
+            workAct(space, ctx.settings, session, act);
+            return json(200, { ok: true });
+        }
+        if (path === "/desk/task-stop") {
+            if (!post)
+                return json(405, {});
+            if (space === null)
+                return json(404, {});
+            const body = await readJson(req);
+            const session = str(body["session"]) ?? "";
+            const task = str(body["task"]) ?? "";
+            if (!SAFE_ID.test(session) || !SAFE_ID.test(task) || !space.store.ids().includes(session))
+                return json(404, {});
+            return json(200, { stopped: space.tasks.managerFor(session).stop(task, "person") });
+        }
+        if (path === "/desk/fs/tree" || path === "/desk/fs/file" || path === "/desk/task-log") {
+            if (space === null)
+                return json(404, {});
+            return req.method === "GET" ? deskRead(url, space) : json(405, {});
+        }
+        if (path === "/desk/exists") {
+            if (space === null)
+                return json(404, {});
+            return post ? json(200, { found: existing(realpathSync(space.workspace), (await readJson(req))["paths"]) }) : json(405, {});
+        }
+        // an image block of a result, from the Work's log: its bytes, or an https address passed on
+        const image = /^\/desk\/image\/([A-Za-z0-9._-]+)\/(\d+)\/(\d+|k\d+)$/.exec(path);
+        if (image !== null) {
+            if (space === null || req.method !== "GET" || !space.store.ids().includes(image[1]))
+                return json(404, {});
+            const b = space.images.block(image[1], Number(image[2]), image[3].startsWith("k") ? image[3] : Number(image[3]));
+            if (b === null)
+                return json(404, {});
+            return "url" in b ? { status: 302, body: null, headers: { location: b.url } } : { status: 200, body: b.bytes, headers: { "content-type": b.type, "x-content-type-options": "nosniff", "cache-control": "private, max-age=86400" } };
+        }
+        // a page, a pdf or media of the folder on its own preview server (preview.ts); the address it answers
+        if (path === "/desk/preview" && post) {
+            if (space === null)
+                return json(404, {});
+            const entry = resolveInside(realpathSync(space.workspace), String((await readJson(req))["path"] ?? ""));
+            if (!statSync(entry).isFile() || artifactKind(entry) === undefined)
+                throw new Refusal(400, "not a page, a document or media");
+            const host = req.headers.host ?? "";
+            return json(200, { url: await ctx.previews.open(entry, host, `http://${host}`) });
+        }
+        if (path === "/desk/preview-close" && post) {
+            ctx.previews.close(String((await readJson(req))["url"] ?? ""));
+            return json(200, { ok: true });
+        }
+        // the line the person may send next after the run that ended at `seq` (asked once, after that run; "" for none)
+        if (path === "/desk/followup") {
+            if (space === null)
+                return json(404, {});
+            if (req.method !== "GET")
+                return json(405, {});
+            const session = url.searchParams.get("session") ?? "";
+            const seq = Number(url.searchParams.get("seq"));
+            if (!space.store.ids().includes(session) || !Number.isInteger(seq))
+                return json(404, {});
+            return json(200, { line: await space.followUp(session, seq) });
+        }
+        if (path === "/desk/env") {
+            if (space === null)
+                return json(404, {});
+            if (req.method !== "GET")
+                return json(405, {});
+            const session = url.searchParams.get("session") ?? undefined;
+            const fork = session === undefined ? undefined : ctx.settings.forkOf(session);
+            return json(200, { ...folderInfo(space.workspace, ctx.settings.tierOf(session)), ...(fork === undefined ? {} : { fork: { parent: fork.parent, title: fork.title, at: fork.at } }) });
+        }
+        if (path === "/desk/history")
+            return req.method === "GET" ? json(200, await ctx.history.snapshot({ key: ctx.current.key, dir: ctx.current.dir }, url.searchParams.get("fresh") ?? undefined)) : json(405, {});
+        if (path === "/desk/settings") {
+            let session = url.searchParams.get("session") ?? undefined;
+            if (post) {
+                const patch = (await readJson(req));
+                // a patch for one Work is answered with that Work's settings
+                session ??= patch.session;
+                const before = patch.session === undefined ? undefined : ctx.settings.workOf(patch.session);
+                const work = ctx.settings.apply(patch);
+                // a Work's model changed: rebuild it from its log so its next run uses it; a run in flight refuses, and the choice is put back
+                if (work !== null && space !== null && space.opened().has(work)) {
+                    try {
+                        await space.service.reopen(work);
+                    }
+                    catch {
+                        ctx.settings.restoreWork(work, before);
+                        return json(409, { message: "a run is going: switch the model when it ends" });
+                    }
+                }
+            }
+            else if (req.method !== "GET")
+                return json(405, {});
+            return json(200, ctx.settings.snapshot(session));
+        }
+        if (path === "/desk/folder" && post) {
+            const workspace = validateFolder((await readJson(req))["path"]);
+            const dir = projectDirFor(ctx.home, workspace);
+            claimProjectDir(dir, workspace);
+            ctx.settings.addRecent(workspace);
+            ctx.settings.write({ lastFolder: workspace });
+            const opened = ctx.spaceFor(basename(dir));
+            return opened === null ? json(500, {}) : json(200, { key: opened.key, folder: basename(workspace) });
+        }
+        if (path === "/desk/recent" && req.method === "GET") {
+            const rows = ctx.settings.recents().flatMap((p) => {
+                try {
+                    const real = validateFolder(p);
+                    return [{ folder: basename(real), path: real, key: basename(projectDirFor(ctx.home, canonicalPath(real))) }];
+                }
+                catch {
+                    return [];
+                }
+            });
+            return json(200, { recent: rows });
+        }
+        if (path === "/desk/login" && post) {
+            const b = await readJson(req);
+            ctx.settings.saveKey(str(b["profile"]) ?? "", b["key"]);
+            return json(200, { ok: true });
+        }
+        if (path === "/desk/demo" && post) {
+            await ctx.settings.startDemo();
+            return json(200, { ok: true });
+        }
+        if (path === "/desk/notices" && req.method === "GET")
+            return json(200, ctx.notices(Number(url.searchParams.get("after") ?? "0") || 0));
+        if (path === "/desk/dirs" && req.method === "GET")
+            return json(200, listDirs(url.searchParams.get("root"), url.searchParams.get("path") ?? ""));
+        if (path === "/desk/presence" && post) {
+            const b = await readJson(req);
+            const key = str(b["key"]) ?? "";
+            ctx.setPresence({ key: key === "" ? ctx.current.key : key, session: str(b["session"]) ?? "", focused: b["focused"] === true, at: Date.now() });
+            return json(200, { ok: true });
+        }
+        return json(404, {});
+    }
+    catch (error) {
+        if (error instanceof Refusal)
+            return json(error.status, { code: "refused", message: error.message });
+        return json(500, { code: "internal", message: "failed" });
+    }
+}

package/dist/main/env.js

@@ -0,0 +1,104 @@
+import { appendFileSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { canonicalPath, projectDirFor } from "@vincemakes/kiso-code/config";
+import { kisoHome } from "@vincemakes/kiso-runtime";
+import { fauxSkip } from "./faux.js";
+import { startHost } from "./host.js";
+import { Settings } from "./settings.js";
+/**
+ * The host's configuration from the environment (the `kiso-web` command
+ * reads its flags in headless.ts), so a credential never rides argv:
+ *
+ *   KISO_WEB_DATA        the kiso home: `projects/<enc>/` under it holds the Works (default: the terminal's own home)
+ *   KISO_WEB_WORKSPACE   the folder a new task starts in (default: the folder used last, else the working directory)
+ *   KISO_WEB_FAUX        path to a JSON FauxScript (the keyless model)
+ *   KISO_WEB_FAUX_SKIP   a session id: skip the script turns its log already consumed
+ *   KISO_WEB_MODE        the permission tier: default | accept-edits | plan | full-access
+ *   KISO_WEB_NOTIFY_LOG  a file: notices (an approval waits, a run ended) are also appended to it, as JSON lines (the proofs)
+ *   KISO_WEB_REQUEST_LOG, KISO_WEB_PREVIEW_LOG  files: each request the host, or a preview server, received (the proofs)
+ *   KISO_WEB_SANITIZER   "default" | "web"
+ *   KISO_WEB_THINKING    0: leave reasoning text off the wire (default: on)
+ *   KISO_WEB_KEEPALIVE   keepalive period in ms
+ *   KISO_WEB_MIN_FG_MS   the shell's least foreground wait (0 keeps the model's value)
+ *   KISO_WEB_PORT        the port (default 4317; 0: the system picks), and KISO_WEB_TOKEN the scripts' bearer
+ *                            token (default: a fresh one per launch, never printed) — the crash script restarts
+ *                            the host where a live client expects it
+ *
+ */
+/** A scripted model, for the proofs; otherwise null: the model comes from the shared configuration (settings.ts). */
+async function fauxFromEnv(sessionsDir) {
+    const fauxPath = process.env["KISO_WEB_FAUX"];
+    if (fauxPath === undefined || fauxPath === "")
+        return null;
+    const { createFauxProvider } = await import("@vincemakes/kiso-evals");
+    const script = JSON.parse(readFileSync(fauxPath, "utf8"));
+    const skipFor = process.env["KISO_WEB_FAUX_SKIP"];
+    const skip = skipFor === undefined || skipFor === "" ? 0 : fauxSkip(sessionsDir, skipFor);
+    return { kind: "adapter", adapter: createFauxProvider(script.slice(skip)), model: "faux", route: "adapter" };
+}
+const MODES = ["default", "accept-edits", "plan", "full-access"];
+function modeFromEnv() {
+    const raw = process.env["KISO_WEB_MODE"];
+    if (raw === undefined || raw === "")
+        return "default";
+    const mode = MODES.find((m) => m === raw);
+    if (mode === undefined)
+        throw new Error(`KISO_WEB_MODE must be one of ${MODES.join(", ")}`);
+    return mode;
+}
+const isFolder = (path) => {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/** The folder a new task starts in: named by the environment, else the one used last while it still exists, else where the command was started. */
+function workspaceFor(settings) {
+    const named = process.env["KISO_WEB_WORKSPACE"];
+    if (named !== undefined && named !== "")
+        return named;
+    // a remembered folder can be gone (a deleted scratch folder); "/" is never a place to work: both fall back to the home folder
+    const last = settings.lastFolder();
+    if (last !== undefined && isFolder(last))
+        return last;
+    const cwd = process.cwd();
+    return cwd === "/" || last !== undefined ? homedir() : cwd;
+}
+/** A copy of every notice in a file, for the proofs. */
+function noticeLog() {
+    const log = process.env["KISO_WEB_NOTIFY_LOG"];
+    return log === undefined || log === "" ? undefined : (n) => appendFileSync(log, `${JSON.stringify(n)}\n`);
+}
+export async function startFromEnv(options = {}) {
+    const home = process.env["KISO_WEB_DATA"] ?? kisoHome();
+    // the terminal's configuration and sign-in are read from the one root the terminal uses
+    process.env["KISO_HOME"] ??= home;
+    const keepalive = Number(process.env["KISO_WEB_KEEPALIVE"] ?? "");
+    const minFg = Number(process.env["KISO_WEB_MIN_FG_MS"] ?? "");
+    // settings first: its saved tier and folder memory are read before anything is opened
+    const probe = new Settings(home, null, modeFromEnv());
+    const workspace = canonicalPath(workspaceFor(probe));
+    const faux = await fauxFromEnv(projectDirFor(home, workspace));
+    const settings = faux === null ? probe : new Settings(home, faux, modeFromEnv());
+    // the folder used last is only ever one the person chose (POST /desk/folder): a folder named by the environment, a proof's or a
+    // scratch run's, is not remembered for them
+    return startHost({
+        home,
+        workspace,
+        settings,
+        ...(noticeLog() !== undefined ? { notify: noticeLog() } : {}),
+        exposeThinking: process.env["KISO_WEB_THINKING"] !== "0",
+        requestLog: process.env["KISO_WEB_REQUEST_LOG"] || undefined,
+        previewLog: process.env["KISO_WEB_PREVIEW_LOG"] || undefined,
+        ...(options.port !== undefined ? { port: options.port } : {}),
+        ...(process.env["KISO_WEB_TOKEN"] !== undefined ? { token: process.env["KISO_WEB_TOKEN"] } : {}),
+        sanitizer: process.env["KISO_WEB_SANITIZER"] === "default" ? "default" : "web",
+        followUps: process.env["KISO_WEB_FOLLOWUP"] !== "off",
+        titles: process.env["KISO_AUTO_TITLE"] !== "off",
+        ...(Number.isFinite(keepalive) && keepalive > 0 ? { keepaliveMs: keepalive } : {}),
+        ...(process.env["KISO_WEB_MIN_FG_MS"] !== undefined && Number.isFinite(minFg) ? { toolLimits: { minForegroundMs: minFg } } : {}),
+    });
+}

package/dist/main/faux.js

@@ -0,0 +1,12 @@
+import { SessionStore } from "@vincemakes/kiso-runtime";
+/** How many faux-script turns a session's log has consumed (the same rule the terminal's fauxSkip states: a turn is consumed by a tool
+ *  result or an end_turn stop, or by an unfinished call the recovery completes). */
+export function fauxSkip(sessionsDir, sessionId) {
+    const store = new SessionStore(sessionsDir);
+    const events = store.load(sessionId).map((r) => r.event);
+    store.closeAll();
+    const results = new Set(events.filter((e) => e.type === "tool_result").map((e) => e.callId));
+    return (events.filter((e) => e.type === "tool_result").length +
+        events.filter((e) => e.type === "stop" && e.reason === "end_turn").length +
+        events.filter((e) => e.type === "tool_call_end" && !results.has(e.callId)).length);
+}

package/dist/main/files.js

@@ -0,0 +1,156 @@
+import { closeSync, fstatSync, lstatSync, openSync, readdirSync, readSync, realpathSync, statSync } from "node:fs";
+import { extname, isAbsolute, join, resolve, sep } from "node:path";
+import { canonicalPath } from "@vincemakes/kiso-code/config";
+import { kisoHome } from "@vincemakes/kiso-runtime";
+import { protectedFiles } from "./agent.js";
+/**
+ * The read-only doors to a Work's folder, for the Files and Changes panels.
+ *
+ * What may be read is decided here, never by the page: a path is relative to
+ * the folder's real path; it is resolved through every symbolic link and must
+ * land inside the folder; the kiso home (credentials, sessions) and the
+ * files the policy protects are refused even when they sit inside the folder;
+ * a file is read up to a size cap and a file with a NUL byte is never read as
+ * text. A link that leads outside is listed as such and never followed.
+ */
+export const TEXT_CAP = 256 * 1024;
+export const IMAGE_CAP = 2 * 1024 * 1024;
+const LIST_CAP = 500;
+const LOG_CAP = 64 * 1024;
+const IMAGES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml" };
+/** A refusal with the status the host answers. */
+export class Refusal extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const inside = (root, real) => real === root || real.startsWith(root + sep);
+const folded = (name, dir) => dir && (name === "node_modules" || name.startsWith("."));
+/** Places no door reads: the kiso home and the policy's protected files, by real path. */
+function protectedPaths() {
+    return { dirs: [canonicalPath(kisoHome())], files: protectedFiles().map(canonicalPath) };
+}
+function isProtected(real) {
+    const p = protectedPaths();
+    return p.dirs.some((d) => inside(d, real)) || p.files.includes(real);
+}
+/** The real path of `rel` inside `root` (a real path), or a Refusal. */
+export function resolveInside(root, rel) {
+    if (rel.includes("\0") || isAbsolute(rel))
+        throw new Refusal(400, "the path must be relative to the folder");
+    const target = resolve(root, rel);
+    if (!inside(root, target))
+        throw new Refusal(403, "outside the folder");
+    // a folder the listing does not open is not read through either (a dot folder can hold credentials)
+    const parts = rel.split("/").filter((p) => p !== "" && p !== ".");
+    if (parts.slice(0, -1).some((p) => folded(p, true)))
+        throw new Refusal(403, "not listed");
+    let real;
+    try {
+        real = realpathSync(target);
+    }
+    catch {
+        throw new Refusal(404, "no such file");
+    }
+    if (!inside(root, real))
+        throw new Refusal(403, "outside the folder");
+    if (isProtected(real))
+        throw new Refusal(403, "protected");
+    return real;
+}
+export function listDir(root, rel) {
+    const dir = resolveInside(root, rel);
+    if (!statSync(dir).isDirectory())
+        throw new Refusal(400, "not a folder");
+    const last = rel.split("/").filter((p) => p !== "" && p !== ".").at(-1);
+    if (last !== undefined && folded(last, true))
+        throw new Refusal(403, "not listed");
+    const entries = [];
+    let more = 0;
+    const names = readdirSync(dir, { withFileTypes: true }).sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name));
+    for (const ent of names) {
+        const full = join(dir, ent.name);
+        let real;
+        try {
+            real = realpathSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (isProtected(real))
+            continue;
+        if (entries.length >= LIST_CAP) {
+            more += 1;
+            continue;
+        }
+        const link = lstatSync(full).isSymbolicLink();
+        if (!inside(root, real)) {
+            entries.push({ name: ent.name, kind: "link", size: 0, outside: true });
+            continue;
+        }
+        const stat = statSync(real);
+        const isDir = stat.isDirectory();
+        entries.push({ name: ent.name, kind: link && !isDir ? "link" : isDir ? "dir" : "file", size: isDir ? 0 : stat.size, ...(folded(ent.name, isDir) ? { folded: true } : {}) });
+    }
+    return { root, path: rel, entries, more };
+}
+function readHead(path, length) {
+    const fd = openSync(path, "r");
+    try {
+        const buf = Buffer.alloc(Math.min(length, fstatSync(fd).size));
+        readSync(fd, buf, 0, buf.length, 0);
+        return buf;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function readPreview(root, rel) {
+    const file = resolveInside(root, rel);
+    const stat = statSync(file);
+    if (!stat.isFile())
+        throw new Refusal(400, "not a file");
+    const mime = IMAGES[extname(file).toLowerCase()];
+    if (mime !== undefined)
+        return stat.size > IMAGE_CAP ? { kind: "toolarge", size: stat.size } : { kind: "image", size: stat.size, dataUrl: `data:${mime};base64,${readHead(file, IMAGE_CAP).toString("base64")}` };
+    const head = readHead(file, TEXT_CAP);
+    // a NUL byte in the first 8 KB: not text, however it is named
+    if (head.subarray(0, 8192).includes(0))
+        return { kind: "binary", size: stat.size };
+    const markdown = /\.(md|markdown)$/i.test(file);
+    return { kind: markdown ? "markdown" : "text", size: stat.size, text: head.toString("utf8"), truncated: stat.size > TEXT_CAP };
+}
+/** Which of the paths name a file inside the folder (the stream's chips): each judged as a read would be; a refusal is "no". */
+export function existing(root, paths) {
+    if (!Array.isArray(paths) || paths.length > 64)
+        throw new Refusal(400, "at most 64 paths");
+    return paths.filter((p) => typeof p === "string" && p.length <= 512).filter((rel) => {
+        try {
+            return statSync(resolveInside(root, rel)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** The last part of a task's output file, as lines. */
+export function readTaskLog(outputPath) {
+    try {
+        const size = statSync(outputPath).size;
+        const fd = openSync(outputPath, "r");
+        try {
+            const length = Math.min(size, LOG_CAP);
+            const buf = Buffer.alloc(length);
+            readSync(fd, buf, 0, length, size - length);
+            return { lines: buf.toString("utf8").split("\n").filter((l, i, all) => l !== "" || i < all.length - 1), truncated: size > LOG_CAP };
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return { lines: [], truncated: false };
+    }
+}

package/dist/main/folder-info.js

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+/** The git directory of a folder (it or the nearest parent holding `.git`, a directory or a worktree's pointer file). */
+function gitDir(from) {
+    for (let dir = from;; dir = dirname(dir)) {
+        const dot = join(dir, ".git");
+        if (existsSync(dot)) {
+            if (statSync(dot).isDirectory())
+                return dot;
+            const pointer = /^gitdir:\s*(.+)$/m.exec(readFileSync(dot, "utf8"));
+            return pointer === null ? null : join(dir, pointer[1].trim());
+        }
+        if (dirname(dir) === dir)
+            return null;
+    }
+}
+/** The branch a folder is on (a short commit when detached); null outside a git folder. */
+function branchOf(workspace) {
+    try {
+        const git = gitDir(workspace);
+        if (git === null)
+            return null;
+        const head = readFileSync(join(git, "HEAD"), "utf8").trim();
+        const ref = /^ref: refs\/heads\/(.+)$/.exec(head);
+        return ref !== null ? ref[1] : head.slice(0, 7);
+    }
+    catch {
+        return null;
+    }
+}
+/** What the rail's footer says about a Work's folder: its name, its path (the home shortened), its branch. */
+export function folderInfo(workspace, mode) {
+    const home = homedir();
+    return { folder: basename(workspace), path: workspace.startsWith(`${home}/`) ? `~${workspace.slice(home.length)}` : workspace, root: workspace, branch: branchOf(workspace), mode };
+}

package/dist/main/folders.js

@@ -0,0 +1,102 @@
+import { accessSync, constants, readdirSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, parse, relative, sep } from "node:path";
+import { canonicalPath } from "@vincemakes/kiso-code/config";
+import { kisoHome } from "@vincemakes/kiso-runtime";
+import { Refusal } from "./files.js";
+/** A folder the person picked, judged here and never trusted from the page: absolute, there, a folder, and not the kiso home or inside it. Returns its real path. */
+export function validateFolder(raw) {
+    if (typeof raw !== "string" || raw === "" || raw.includes("\0") || !isAbsolute(raw))
+        throw new Refusal(400, "pick a folder");
+    let real;
+    try {
+        real = canonicalPath(raw);
+        if (!statSync(real).isDirectory())
+            throw new Error("not a folder");
+    }
+    catch {
+        throw new Refusal(400, "that is not a folder that exists");
+    }
+    if (real === parse(real).root)
+        throw new Refusal(400, "the whole disk is not a project folder");
+    const home = canonicalPath(kisoHome());
+    if (real === home || real.startsWith(home + sep))
+        throw new Refusal(400, "the kiso home holds credentials and sessions: pick a project folder");
+    return real;
+}
+const DIRS_CAP = 500;
+const inside = (root, path) => path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
+/** A root of the folder browser: the home folder, or a typed absolute path that exists, is a readable folder, is not the whole disk and not the kiso home. */
+function browseRoot(raw) {
+    if (raw === null || raw === "")
+        return realpathSync(homedir());
+    if (raw.includes("\0") || !isAbsolute(raw))
+        throw new Refusal(400, "type a full path, starting with /");
+    let real;
+    try {
+        real = realpathSync(raw);
+        if (!statSync(real).isDirectory())
+            throw new Error("not a folder");
+        accessSync(real, constants.R_OK | constants.X_OK);
+    }
+    catch {
+        throw new Refusal(400, "that is not a folder that exists and can be read");
+    }
+    if (real === parse(real).root)
+        throw new Refusal(400, "the whole disk is not a place to browse: type a folder in it");
+    if (inside(realpathSync(kisoHome()), real))
+        throw new Refusal(400, "the kiso home holds credentials and sessions");
+    return real;
+}
+/**
+ * One folder of the in-page folder browser: the folders in it, by name, nothing else (no files, no contents). The path is relative to
+ * the root and resolved through every link; it must stay inside the root, so a link never leads the browsing out of it (such a link is
+ * listed as `outside`). Dot folders and the kiso home are not listed.
+ */
+export function listDirs(rootRaw, rel) {
+    const root = browseRoot(rootRaw);
+    if (rel.includes("\0") || isAbsolute(rel) || rel.split(/[\\/]/).includes(".."))
+        throw new Refusal(400, "a path inside the root is expected");
+    let full;
+    try {
+        full = realpathSync(join(root, rel));
+        if (!statSync(full).isDirectory())
+            throw new Error("not a folder");
+    }
+    catch {
+        throw new Refusal(404, "no such folder");
+    }
+    const home = realpathSync(kisoHome());
+    if (!inside(root, full) || inside(home, full))
+        throw new Refusal(403, "outside the folder you are browsing");
+    const dirs = [];
+    let entries;
+    try {
+        entries = readdirSync(full, { withFileTypes: true });
+    }
+    catch {
+        throw new Refusal(403, "that folder cannot be read");
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        const path = join(full, entry.name);
+        if (entry.isDirectory()) {
+            if (!inside(home, path))
+                dirs.push({ name: entry.name });
+        }
+        else if (entry.isSymbolicLink()) {
+            try {
+                const target = realpathSync(path);
+                if (!statSync(target).isDirectory() || inside(home, target))
+                    continue;
+                dirs.push(inside(root, target) ? { name: entry.name } : { name: entry.name, outside: true });
+            }
+            catch {
+                // a broken link is not a folder
+            }
+        }
+    }
+    dirs.sort((a, b) => a.name.localeCompare(b.name));
+    return { root, path: relative(root, full), full, dirs: dirs.slice(0, DIRS_CAP), more: Math.max(0, dirs.length - DIRS_CAP) };
+}