@wjarka/cezarion 0.10.0-pr30.54

package/dist/server/fs-browse.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `GET /api/fs/browse` — the directory picker behind "Add project → open local
+ * folder" (spec 2026-07-20-multi-project-workspace, step 4.1).
+ *
+ * This is the one route that hands the operator's filesystem shape to a
+ * browser, so the whole module is written around a single containment rule and
+ * nothing else:
+ *
+ *   **every path this route answers about — the one browsed and every entry
+ *   listed — must be the browse root itself or live strictly beneath it, as
+ *   judged AFTER `realpath()` resolved the whole symlink chain.**
+ *
+ * Why realpath and not `resolve()`: `resolve()` only normalizes `..` textually.
+ * It cannot see that `~/tmp/escape` is a symlink to `/etc`, so a lexical-only
+ * check happily lists `/etc` under a path that spells as being inside home.
+ * The lexical check is still done FIRST (it rejects `..` traversal and absolute
+ * escapes without touching the disk at all, and it keeps a probe for
+ * "does /root exist" from ever reaching the filesystem), and the realpath check
+ * is done SECOND as the authoritative one.
+ *
+ * Two more deliberate choices:
+ *
+ * - **Directories only.** Files are never listed, never stat-reported, never
+ *   read. The picker's job is to name a folder; a file name is already more of
+ *   the operator's disk than the caller needs.
+ * - **Errors never echo a resolved path.** `{ error }` says what the caller did
+ *   wrong, never where they landed — an error string carrying the realpath of
+ *   an escape attempt would be the very leak the containment prevents (same
+ *   reasoning as the `/api/health` `repoRoot` trim, #431).
+ */
+/** One listed subdirectory. `path` is absolute — this route is same-origin and
+ *  behind the cockpit, exactly like `GET /api/projects`' `root`s (health, the
+ *  CORS-open route, is the one that must never carry absolute paths). */
+export interface FsBrowseDir {
+    name: string;
+    path: string;
+    /** Has a `.git` entry — file or dir, so linked worktrees count. Drives the
+     *  "repo" badge in the picker; a non-repo folder is still selectable. */
+    isRepo: boolean;
+}
+/** `GET /api/fs/browse?path=` — the spec's shape plus `truncated`. */
+export interface FsBrowseResponse {
+    /** The realpath'd directory actually listed (never the spelling asked for —
+     *  the picker's breadcrumb should show where it really is). */
+    path: string;
+    /** `null` AT the browse root: there is no "up" out of the root, and the UI
+     *  needs that to be a shape it cannot mis-navigate. */
+    parent: string | null;
+    dirs: FsBrowseDir[];
+    /** True when `dirs` was capped — an honest signal beats a silently short
+     *  list in a directory with tens of thousands of children. */
+    truncated: boolean;
+}
+export type BrowseResult = {
+    ok: true;
+    body: FsBrowseResponse;
+} | {
+    ok: false;
+    status: 400 | 404;
+    error: string;
+};
+/**
+ * Expand the configured browse root. The workspace owns this independently
+ * from the checkout root, so browsing never follows a clone-destination edit.
+ */
+export declare function resolveBrowseRoot(browseRoot: string): string;
+/**
+ * Is `candidate` the browse root or strictly beneath it — the same containment
+ * question `browseDirectory` asks, exported for the ONE other route that must
+ * ask it: `POST /api/projects` (step 4.2).
+ *
+ * Configuring the browse root only limits what the picker
+ * can SEE. A register call naming an arbitrary absolute path would walk around
+ * that in one request — and a registered project's panes read its whole tree.
+ * So the register route re-asks containment for itself, against the same root,
+ * with the same realpath-based rule. Both paths are realpath'd here (unlike
+ * `contains`, which trusts its callers) because neither is guaranteed resolved.
+ */
+/**
+ * The LEXICAL half of the containment question: does `candidate` spell as being inside `root`,
+ * judged without asking whether it exists?
+ *
+ * `isInsideBrowseRoot` below realpaths both sides, which makes it answer `false` for a path that
+ * is inside the root but simply not there — so using it alone as the first gate would tell a
+ * hosted user who typo'd a folder under their own checkout root that it is "outside the browsable
+ * root". This split lets the register route reject out-of-root paths UNIFORMLY (the existence
+ * oracle stays shut, because a spelling outside the root is refused whether or not it exists),
+ * then answer honestly about existence, then still catch symlink escapes with the realpath gate.
+ */
+export declare function isLexicallyInsideBrowseRoot(root: string, candidate: string): Promise<boolean>;
+export declare function isInsideBrowseRoot(root: string, candidate: string): Promise<boolean>;
+/**
+ * List the directories inside `path`, contained within `root`.
+ *
+ * `path` is the raw query value: absent/empty means the root itself, `~`
+ * spellings are expanded, and a relative value resolves against the root (so
+ * the route is usable without the caller knowing the absolute root, and a
+ * relative `../..` is still caught by the same containment check as everything
+ * else).
+ */
+export declare function browseDirectory(opts: {
+    root: string;
+    path?: string | undefined;
+    showHidden?: boolean;
+}): Promise<BrowseResult>;

package/dist/server/fs-browse.js

@@ -0,0 +1,182 @@
+import { readdir, realpath, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { expandTilde } from '../paths.js';
+/**
+ * Entry cap. A picker cannot usefully render more, and an unbounded listing
+ * turns one request into a per-entry `stat` storm (`isRepo` + symlink
+ * resolution) on e.g. a node_modules parent.
+ */
+const MAX_ENTRIES = 1000;
+/**
+ * Expand the configured browse root. The workspace owns this independently
+ * from the checkout root, so browsing never follows a clone-destination edit.
+ */
+export function resolveBrowseRoot(browseRoot) {
+    return expandTilde(browseRoot);
+}
+/** `candidate` is `root` or strictly beneath it. Both must already be
+ *  realpath'd for this to mean anything. The explicit separator suffix is what
+ *  stops `/home/bob-evil` from passing as inside `/home/bob`; the `endsWith`
+ *  guard keeps a root of `/` from becoming the prefix `//`. */
+function contains(root, candidate) {
+    if (candidate === root)
+        return true;
+    return candidate.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+/**
+ * Is `candidate` the browse root or strictly beneath it — the same containment
+ * question `browseDirectory` asks, exported for the ONE other route that must
+ * ask it: `POST /api/projects` (step 4.2).
+ *
+ * Configuring the browse root only limits what the picker
+ * can SEE. A register call naming an arbitrary absolute path would walk around
+ * that in one request — and a registered project's panes read its whole tree.
+ * So the register route re-asks containment for itself, against the same root,
+ * with the same realpath-based rule. Both paths are realpath'd here (unlike
+ * `contains`, which trusts its callers) because neither is guaranteed resolved.
+ */
+/**
+ * The LEXICAL half of the containment question: does `candidate` spell as being inside `root`,
+ * judged without asking whether it exists?
+ *
+ * `isInsideBrowseRoot` below realpaths both sides, which makes it answer `false` for a path that
+ * is inside the root but simply not there — so using it alone as the first gate would tell a
+ * hosted user who typo'd a folder under their own checkout root that it is "outside the browsable
+ * root". This split lets the register route reject out-of-root paths UNIFORMLY (the existence
+ * oracle stays shut, because a spelling outside the root is refused whether or not it exists),
+ * then answer honestly about existence, then still catch symlink escapes with the realpath gate.
+ */
+export async function isLexicallyInsideBrowseRoot(root, candidate) {
+    const realRoot = await realpathOrNull(root);
+    if (realRoot === null)
+        return false;
+    return contains(realRoot, resolve(candidate));
+}
+export async function isInsideBrowseRoot(root, candidate) {
+    const realRoot = await realpathOrNull(root);
+    if (realRoot === null)
+        return false;
+    const real = await realpathOrNull(candidate);
+    if (real === null)
+        return false;
+    return contains(realRoot, real);
+}
+/** realpath or null — every "does it exist / where does it really point"
+ *  question in this module is best-effort and answered without throwing. */
+async function realpathOrNull(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return null;
+    }
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * List the directories inside `path`, contained within `root`.
+ *
+ * `path` is the raw query value: absent/empty means the root itself, `~`
+ * spellings are expanded, and a relative value resolves against the root (so
+ * the route is usable without the caller knowing the absolute root, and a
+ * relative `../..` is still caught by the same containment check as everything
+ * else).
+ */
+export async function browseDirectory(opts) {
+    // The root is realpath'd ONCE, up front: it is the yardstick every later
+    // comparison uses, and comparing a resolved candidate against an
+    // unresolved root would reject legitimate paths on any machine whose home
+    // sits behind a symlink (macOS `/tmp`, NFS automounts, `/home` → `/usr/home`).
+    const root = await realpathOrNull(opts.root);
+    // A configured browse root that does not exist yet lands here. There
+    // is nothing to browse and nothing informative to say about a path the
+    // caller cannot see anyway.
+    if (root === null)
+        return { ok: false, status: 404, error: 'browse root is not available' };
+    const requested = (opts.path ?? '').trim();
+    // A NUL byte would make the fs calls throw `ERR_INVALID_ARG_VALUE` instead of
+    // failing containment; reject it as malformed input before it gets that far.
+    if (requested.includes('\0'))
+        return { ok: false, status: 400, error: 'invalid path' };
+    const expanded = requested === '' ? root : expandTilde(requested);
+    // `resolve` handles both spellings: an absolute value stands alone, a
+    // relative one is taken from the root. Either way `..` is folded away here,
+    // so the lexical check below sees the real intent.
+    const target = isAbsolute(expanded) ? resolve(expanded) : resolve(root, expanded);
+    // Lexical gate: `..` traversal and absolute escapes die here, before any
+    // syscall — so an escape attempt cannot even be used to probe which paths
+    // outside the root exist (the timing/`404`-vs-`400` difference would tell).
+    if (!contains(root, target))
+        return { ok: false, status: 400, error: 'path is outside the browsable root' };
+    const real = await realpathOrNull(target);
+    if (real === null)
+        return { ok: false, status: 404, error: 'no such directory' };
+    // Authoritative gate: `target` spelled as inside the root, but the symlink
+    // chain may land anywhere. This is the check that catches a symlink planted
+    // inside home pointing at `/etc` (or, in hosted mode, at the rest of the
+    // host's disk).
+    if (!contains(root, real))
+        return { ok: false, status: 400, error: 'path is outside the browsable root' };
+    const info = await stat(real).catch(() => null);
+    // Not a directory ⇒ same answer as "not there". The picker only navigates
+    // directories, and distinguishing "this is a file" would confirm the
+    // existence of a file the caller was never shown.
+    if (!info?.isDirectory())
+        return { ok: false, status: 404, error: 'no such directory' };
+    const entries = await readdir(real, { withFileTypes: true }).catch(() => null);
+    // Unreadable (mode 0300, permission-denied mount) — indistinguishable from
+    // absent, on purpose.
+    if (entries === null)
+        return { ok: false, status: 404, error: 'no such directory' };
+    const showHidden = opts.showHidden === true;
+    const candidates = entries
+        .filter((entry) => showHidden || !entry.name.startsWith('.'))
+        // Symlinks are resolved below (a symlinked project dir is a normal setup);
+        // everything that is neither a directory nor a symlink is not our business.
+        .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const truncated = candidates.length > MAX_ENTRIES;
+    const dirs = [];
+    for (const entry of candidates.slice(0, MAX_ENTRIES)) {
+        const childPath = join(real, entry.name);
+        if (entry.isSymbolicLink()) {
+            const childReal = await realpathOrNull(childPath);
+            // A symlink is listed only when it resolves to a directory that is
+            // ITSELF inside the root. Listing an escaping link and rejecting it on
+            // click would leak the same fact one step later — that a path outside
+            // the root exists.
+            if (childReal === null || !contains(root, childReal))
+                continue;
+            const childInfo = await stat(childReal).catch(() => null);
+            if (!childInfo?.isDirectory())
+                continue;
+        }
+        dirs.push({
+            name: entry.name,
+            // The link's own path, not its target: the breadcrumb should read the
+            // way the operator's filesystem reads, and navigating into it re-runs
+            // the containment check from scratch.
+            path: childPath,
+            isRepo: await exists(join(childPath, '.git')),
+        });
+    }
+    return {
+        ok: true,
+        body: {
+            path: real,
+            // Never above the root, even when the real parent exists — `dirname('/')`
+            // is `/`, and the root's parent is simply not part of this surface.
+            parent: real === root ? null : dirname(real),
+            dirs,
+            truncated,
+        },
+    };
+}
+//# sourceMappingURL=fs-browse.js.map

package/dist/server/fs-browse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-browse.js","sourceRoot":"","sources":["../../src/server/fs-browse.ts"],"names":[],"mappings":"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"}

package/dist/server/git-changes.d.ts

@@ -0,0 +1,213 @@
+import { type RepointedHead } from '../git-diff-base.ts';
+export interface ChangedFile {
+    path: string;
+    /** Rename/copy source — present only when `status` is renamed/copied. */
+    oldPath?: string;
+    status: 'added' | 'modified' | 'deleted' | 'renamed' | 'copied';
+    adds: number;
+    dels: number;
+    binary: boolean;
+    /** True when `path`'s extension is one the raw-bytes route (`/files?raw=1`) will serve as an
+     *  `<img>` (#365) — lets the diff pane preview it inline instead of the "Binary file" note,
+     *  even for extensions (SVG) git itself doesn't flag `binary`. Present only when true. */
+    image?: boolean;
+    patch: string;
+}
+export interface ChangesPayload {
+    files: ChangedFile[];
+    stat: {
+        adds: number;
+        dels: number;
+        files: number;
+    };
+    /** Present when a run worktree was repointed away from the task branch (#591). In that case the
+     *  payload is intentionally limited to uncommitted changes instead of attributing the
+     *  checked-out branch's history to this task. */
+    repointedHead?: RepointedHead;
+}
+export type ChangesResult = {
+    ok: true;
+    changes: ChangesPayload;
+} | {
+    ok: false;
+    error: string;
+};
+interface NumstatEntry {
+    adds: number;
+    dels: number;
+    binary: boolean;
+    path: string;
+    oldPath?: string;
+}
+/** Parse `git diff --numstat -z -M`: `adds TAB dels TAB path NUL`, or for a
+ *  rename/copy `adds TAB dels TAB NUL old NUL new NUL`. Binary files report
+ *  `-` for both counters. Exported for tests. */
+export declare function parseNumstatZ(out: string): NumstatEntry[];
+interface NameStatusEntry {
+    status: string;
+    path: string;
+    oldPath?: string;
+}
+/** Parse `git diff --name-status -z -M`: `X NUL path NUL`, renames/copies
+ *  `Rnnn NUL old NUL new NUL`. Exported for tests. */
+export declare function parseNameStatusZ(out: string): NameStatusEntry[];
+/** Split one `git diff --patch` blob into per-file sections, in git's file
+ *  order (the same order `--numstat`/`--name-status` use). Exported for tests. */
+export declare function splitPatch(patch: string): string[];
+/** Map each `git diff --patch` section to the file path it describes, so a file's
+ *  patch is looked up by path rather than by position. This is robust to the two
+ *  listings (`--name-status` and `--patch`) disagreeing on file count — the case
+ *  where positional matching used to blank *every* file's patch. Exported for tests. */
+export declare function patchByPath(sections: string[]): Map<string, string>;
+/**
+ * Structured "what changed here" for a directory vs its base branch:
+ * committed + uncommitted + untracked (via `add -N`), anchored by the shared
+ * `resolveTaskDiffBase` rule (`src/git-diff-base.ts`) — the merge-base against
+ * the freshest base ref, so the diff stays *this task's* changes even after the
+ * base moves on, and the branch's state at `runStartedAt` when the agent
+ * repointed the worktree onto another branch (#591, #751).
+ * `worktreeShortstat` resolves through the same helper; the text-blob `/diff`
+ * endpoint (`worktreeDiff`) deliberately does not — see its own note.
+ */
+export declare function collectChanges(dir: string, baseBranch: string, opts?: {
+    patchCap?: number;
+    intentToAdd?: boolean;
+    taskBranch?: string;
+    runStartedAt?: string;
+}): Promise<ChangesResult>;
+/** The three raw `git diff` listings (name-status, numstat, patch) → the `{files, stat}`
+ *  payload. Shared by the working-tree diff above and the commit diff below. Each file's
+ *  patch is matched by path (`patchByPath`), so a mismatch between the name-status and
+ *  patch file counts — a typechange, submodule, or any entry that emits no `diff --git`
+ *  block — drops at most that one file's patch instead of blanking every file's. Positional
+ *  matching remains the fallback for a section whose path can't be parsed, but only when the
+ *  counts agree (the same condition the old all-or-nothing guard required). Exported for tests. */
+export declare function assemblePayload(nameStatusOut: string, numstatOut: string, patchOut: string, patchCap: number): ChangesPayload;
+export interface RunCommit {
+    sha: string;
+    subject: string;
+    author: string;
+    /** Relative time ("3 hours ago"), git's `%cr`. */
+    when: string;
+}
+export type RunCommitsResult = {
+    ok: true;
+    commits: RunCommit[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The commits reachable from the worktree's current HEAD after its base, newest first. A review
+ * task may deliberately repoint HEAD to the reviewed branch, so this list retains that useful
+ * history even though `collectChanges` narrows its payload to uncommitted work in that case.
+ * Empty (not an error) when the branch has no commits past base.
+ */
+export declare function collectRunCommits(dir: string, baseBranch: string): Promise<RunCommitsResult>;
+/** `GET /api/repo/commit/:sha?structured=1` — one commit's metadata plus the same
+ *  structured `{files, stat}` shape the working-tree routes serve (R5 Step 1.7). The
+ *  legacy text-blob answer of that route is a protected surface and stays untouched. */
+export interface CommitPayload {
+    sha: string;
+    subject: string;
+    author: string;
+    /** Relative time ("3 hours ago") — same `%cr` format the /api/repo log uses. */
+    when: string;
+    files: ChangedFile[];
+    stat: {
+        adds: number;
+        dels: number;
+        files: number;
+    };
+}
+export type CommitChangesResult = {
+    ok: true;
+    commit: CommitPayload;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Structured diff of ONE commit vs its first parent (`--root` covers the initial commit).
+ * A merge commit honestly answers zero files — `git diff-tree` shows no diff for merges
+ * without `-m`/`-c`, and inventing one side's diff would misattribute the changes.
+ * Unknown/invalid shas degrade to `{ ok:false, error }` for the route's 409.
+ */
+export declare function collectCommitChanges(dir: string, sha: string, patchCap?: number): Promise<CommitChangesResult>;
+/** Max file content served to the Files tab — past this the GUI shows an
+ *  honest "too large" state instead of the bytes. */
+export declare const FILE_CONTENT_CAP = 512000;
+export interface DirEntry {
+    name: string;
+    type: 'dir' | 'file';
+    size?: number;
+}
+export type FilesResult = {
+    kind: 'dir';
+    path: string;
+    entries: DirEntry[];
+} | {
+    kind: 'file';
+    path: string;
+    size: number;
+    binary: boolean;
+    tooLarge: boolean;
+    content?: string;
+} | {
+    kind: 'invalid';
+    error: string;
+} | {
+    kind: 'missing';
+    error: string;
+};
+/** The image MIME type for a path, or null when it is not an image we serve raw. */
+export declare function imageMimeType(path: string): string | null;
+/** True when `path` is an image safe to hand to the OS's default handler — see OS_OPENABLE_EXT. */
+export declare function isOsOpenableImage(path: string): boolean;
+/**
+ * Directory listing or file content from inside `root`, traversal-safe:
+ * anything resolving outside the root (dot-segments, absolute paths, NUL) is
+ * rejected — same "not a file we serve" stance as `isSafeAssetFilename` in
+ * src/server/static-ui.ts. `.git` and symlinks are off-limits too.
+ */
+export declare function readWorktreePath(root: string, relPath: string, contentCap?: number): Promise<FilesResult>;
+export type BranchResult = {
+    ok: true;
+    branch: string;
+    created: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Repo-view branch action (`POST /api/repo/branch`): switch to `name` when it
+ * already exists locally, otherwise create it from `from` (or HEAD) and switch.
+ * Name validation is delegated to `git check-ref-format --branch` — git's own
+ * rules, not a reimplementation — behind an explicit dash-guard (#431).
+ * Predictable failures (invalid name, unknown `from`, dirty-tree checkout
+ * conflict) come back as `{ ok:false, error }`.
+ */
+export declare function createOrSwitchBranch(dir: string, name: string, from?: string): Promise<BranchResult>;
+export type CommitResult = {
+    ok: true;
+    sha: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** `git add -A && git commit -m <message>` in `dir`. A clean tree, a failing
+ *  hook or missing identity all come back as `{ ok:false, error }`. */
+export declare function commitAll(dir: string, message: string): Promise<CommitResult>;
+export type PushResult = {
+    ok: true;
+    branch: string;
+    remote: string;
+    upstreamSet: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/** Push the current branch, setting upstream when it has none. No remote,
+ *  detached HEAD and rejected pushes all degrade to `{ ok:false, error }`. */
+export declare function pushCurrentBranch(dir: string): Promise<PushResult>;
+export {};