@hearsay-tools/squawk 0.0.0-stage → 0.17.0-pr3058.5683

package/dist/server/forge/types.d.ts

@@ -0,0 +1,278 @@
+import type { GithubData, GithubProjectsData, GithubItemResponse, GithubCommentCountsData } from '../../contract/index.js';
+import type { ArchivePullRequestIdentity, MergedPullRequest } from '../../contract/index.js';
+import type { GithubChecksData, GithubRefStatusData, ReferenceStatus, RepoHandleDiscovery } from './github.ts';
+import type { RunRecord } from '../../runs/store.ts';
+/**
+ * Forge-driver seam (cockpit-ui redesign spec §"Forge-driver seam"): every
+ * code-forge integration (GitHub today, GitLab later) implements `ForgeDriver`.
+ * The interface is shaped strictly around what the cockpit already does via
+ * `gh` — issue/PR listing for the GitHub tab, draft-PR creation for the review
+ * gate, a per-branch PR probe, and web-URL building. Adding a forge = one new
+ * driver file behind `resolveForge`, no route or UI changes.
+ */
+export type ForgeKind = 'github';
+/** Availability probe result — mirrors the tab's quiet degradation contract:
+ *  no CLI, no remote, offline all land on `available:false` + a human hint. */
+export interface ForgeAvailability {
+    available: boolean;
+    /** Human-readable hint when unavailable (`gh` missing, no remote, offline…). */
+    reason?: string;
+}
+/** One issue or pull request, flattened for the cockpit. `/api/github` serves
+ *  exactly this shape (BACKWARD_COMPATIBILITY.md — do not reshape). */
+export type ForgeItem = import('../../contract/index.js').GithubItem;
+/** One comment (or PR review summary) in an issue/PR conversation thread (#499). Served by the
+ *  new `GET /api/github/comments/:kind/:number` endpoint; additive, no impact on `ForgeItem`. */
+export interface ForgeComment {
+    id: number;
+    /** Author login, `'?'` fallback when gh omits the user. */
+    author: string;
+    /** https://avatars.githubusercontent.com/…, when known. */
+    avatarUrl?: string;
+    /** ISO timestamp. */
+    createdAt: string;
+    /** Markdown body, sliced to the same 8 000-char cap as item bodies. */
+    body: string;
+    /** `review` = a submitted PR review summary; `comment` = a conversation comment. */
+    kind: 'comment' | 'review';
+    /** For reviews only — drives the state chip. */
+    reviewState?: 'approved' | 'changes_requested' | 'commented' | 'dismissed';
+    /** html_url deep link back to the comment/review on GitHub. */
+    url: string;
+}
+/** The timeline event kinds the thread renders (#525). An allowlist, not a denylist: a new
+ *  GitHub event type is dropped rather than rendered, so it can never crash or clutter the
+ *  thread. `reviewed` is deliberately absent — reviews stay sourced from `/pulls/{n}/reviews`,
+ *  which is already normalized and chipped; sourcing both would render each review twice. */
+export type ForgeTimelineEventKind = 'committed' | 'labeled' | 'unlabeled' | 'assigned' | 'unassigned' | 'merged' | 'closed' | 'reopened' | 'head_ref_force_pushed' | 'cross-referenced' | 'renamed';
+/** One non-comment row in an issue/PR timeline (#525) — a commit, label change, assignment,
+ *  merge, force-push, cross-reference or rename. Additive: `ForgeComment` is untouched and its
+ *  `kind` deliberately does NOT widen to cover these (widening breaks client narrowing). */
+export interface ForgeTimelineEvent {
+    /** `evt-${id ?? sha ?? node_id ?? index}`. Prefixed so it cannot collide with the thread's
+     *  `${kind}-${id}` comment keys. `sha` sits ahead of `node_id` because `committed` rows carry
+     *  both and the SHA is the natural, debuggable identifier — it is also the rollup key. */
+    id: string;
+    kind: ForgeTimelineEventKind;
+    /** Login — or the git author name for `committed`, which carries no GitHub actor. */
+    actor: string;
+    /** Absent for `committed` (a git author has no avatar). */
+    avatarUrl?: string;
+    /** ISO-8601. Resolved per kind: `committed` reads `author.date`, everything else
+     *  `created_at` — `committed` rows return `created_at: null`, and mapping it naively
+     *  string-sorts every commit to the top of the thread. */
+    createdAt: string;
+    url?: string;
+    /** `committed` — full 40-char SHA (the rollup query rejects abbreviated ones). */
+    sha?: string;
+    /** `committed` — first line of the message, capped at 120 chars. */
+    message?: string;
+    /** `committed` — rolled-up CI state. **Absent** (query failed or skipped) and **`null`** (no CI
+     *  configured) both render no glyph but stay distinct values for diagnosis. */
+    checks?: 'passing' | 'failing' | 'pending' | null;
+    /** `labeled` / `unlabeled`. */
+    label?: {
+        name: string;
+        color?: string;
+    };
+    /** `assigned`/`unassigned` login, or the new title for `renamed`. */
+    subject?: string;
+    /** `cross-referenced`. */
+    refNumber?: number;
+    refTitle?: string;
+    refIsPr?: boolean;
+}
+/** The `GET /api/github/comments/:kind/:number` payload — mirrors the tab's quiet-degrade
+ *  contract (`available: false` + a hint, never a 5xx). */
+export interface ForgeCommentsData {
+    available: boolean;
+    /** Human-readable hint when unavailable. */
+    reason?: string;
+    /** Chronological, oldest first. */
+    comments: ForgeComment[];
+    /** True when either stream hit its cap, or the timeline fetch stopped short. Means "not
+     *  showing you everything" — not specifically "comments were cut". */
+    truncated?: boolean;
+    /** Timeline events (#525) — additive and optional; absent when the timeline fetch degraded to
+     *  the legacy comments-only call. Capped independently of `comments`, which keeps its exact
+     *  pre-#525 shape, contents and cap (BACKWARD_COMPATIBILITY.md). */
+    events?: ForgeTimelineEvent[];
+    /** The item's own body (and a PR's diffstat), fetched with the thread
+     *  (hearsay-tools/cezarion#1183). Absent when that lookup failed. */
+    detail?: {
+        body: string;
+        additions?: number;
+        deletions?: number;
+    };
+}
+export interface ForgeListOptions {
+    /** Bypass the driver's short cache. */
+    refresh?: boolean;
+    /** Max items to fetch (driver-capped). */
+    limit?: number;
+    /** Opaque cursors from a previous page's `issuesNextCursor`/`prsNextCursor`. */
+    issuesCursor?: string | undefined;
+    prsCursor?: string | undefined;
+    /** That side answered `nextCursor: null`: fetch none of its rows, only its total. */
+    issuesDone?: boolean;
+    prsDone?: boolean;
+}
+/** The `GET /api/github/search` payload (#730). The list tier (`listIssues`/`listPRs`) only ever
+ *  returns OPEN items, so the tab's in-memory filter structurally cannot find a closed or merged
+ *  item — this is the seam that asks the forge instead of re-filtering what we already have.
+ *  Mirrors the tab's quiet-degrade contract (`available: false` + a hint, never a throw/5xx). */
+export type ForgeSearchData = import('../../contract/index.js').GithubSearchData;
+/** Where an existing branch's PR stands — feeds the Create PR → View PR flip. */
+export interface ForgePrStatus {
+    number: number;
+    url: string;
+    state: 'open' | 'merged' | 'closed';
+    isDraft: boolean;
+    checks: 'passing' | 'failing' | 'pending' | null;
+}
+export type ForgeMergeMethod = 'merge' | 'squash' | 'rebase';
+export interface ForgePrCheck {
+    name: string;
+    state: 'passing' | 'failing' | 'pending' | 'unknown';
+    required: boolean | null;
+    url?: string;
+}
+export type ForgePrMergeState = import('../../contract/index.js').GithubPrMergeState;
+export type ForgePrMergeStateResult = {
+    available: true;
+    mergeState: ForgePrMergeState;
+} | {
+    available: false;
+    reason: string;
+};
+export interface ForgeMergeInput {
+    method: ForgeMergeMethod;
+    expectedHeadSha: string;
+    overrideRules?: boolean;
+    /** Automated completion requires at least one check and every check passing; forbids overrides. */
+    requirePassingChecks?: boolean;
+    /** Confirm this PR still belongs to the task branch before mutation. */
+    expectedHeadRef?: string;
+    /** Internal coordinator guard; rechecked after reads and before mutation. Never serialized. */
+    canProceed?: () => boolean;
+}
+export type ForgeMergeResult = {
+    merged: true;
+    number: number;
+    url: string;
+    method: ForgeMergeMethod;
+    mergeCommitSha?: string;
+} | {
+    merged: false;
+    status: 403 | 404 | 409 | 502;
+    error: string;
+    code?: string;
+    current?: ForgePrMergeState;
+};
+export interface ForgePrChange {
+    path: string;
+    previousPath?: string;
+    status: 'added' | 'modified' | 'removed' | 'renamed' | 'copied' | 'changed';
+    additions: number;
+    deletions: number;
+    patch?: string;
+    patchUnavailableReason?: 'binary' | 'too-large' | 'not-provided';
+    truncated?: boolean;
+}
+export type ForgePrDiffResult = {
+    available: true;
+    number: number;
+    headSha: string;
+    files: ForgePrChange[];
+    additions: number;
+    deletions: number;
+    truncated: boolean;
+    reason?: string;
+} | {
+    available: false;
+    reason: string;
+};
+export type ForgeRefKind = 'repo' | 'issue' | 'pr' | 'branch' | 'commit';
+export type DraftPrOutcome = {
+    ok: true;
+    url: string;
+    dryRun: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+export interface DraftPrInput {
+    repoRoot: string;
+    run: RunRecord;
+    /** The task's handoff.md — becomes the PR body (goal + progress skim). */
+    handoffText: string;
+}
+export interface ForgeDriver {
+    discoverRepository(signal?: AbortSignal): Promise<RepoHandleDiscovery>;
+    resolveRepository(signal?: AbortSignal): Promise<{
+        owner: string;
+        name: string;
+    } | null>;
+    mergedPullRequests(identities: ArchivePullRequestIdentity[], signal: AbortSignal): Promise<MergedPullRequest[]>;
+    /** Combined list envelope preserves pagination, totals and quiet degradation. */
+    list(opts?: ForgeListOptions): Promise<GithubData>;
+    projects(generation: string): Promise<GithubProjectsData>;
+    item(kind: 'issue' | 'pr', number: number, opts?: {
+        refresh?: boolean;
+    }): Promise<GithubItemResponse>;
+    comments(kind: 'issue' | 'pr', number: number, opts?: {
+        refresh?: boolean;
+    }): Promise<ForgeCommentsData>;
+    commentCounts(kind: 'issue' | 'pr', numbers: number[], opts?: {
+        refresh?: boolean;
+    }): Promise<GithubCommentCountsData>;
+    checks(numbers: number[]): Promise<GithubChecksData>;
+    refStatus(input: {
+        prs?: number[];
+        issues?: number[];
+    }): Promise<GithubRefStatusData>;
+    cachedRefStatuses(numbers: Iterable<number>): {
+        prs: Record<number, ReferenceStatus>;
+        issues: Record<number, ReferenceStatus>;
+    };
+    /** Invalidate only the task's own pull requests after a successful push. */
+    branchPushed(numbers: readonly number[]): void;
+    readonly kind: ForgeKind;
+    /** Cheap, cached availability probe. May shell out (used by the GitHub tab). */
+    detect(): Promise<ForgeAvailability>;
+    /** Non-blocking availability for the health path: cached result, or null while warming — never
+     *  shells out on the read (keeps /api/health under the bookmarklet's latency budget). */
+    detectCached(): ForgeAvailability | null;
+    listIssues(opts?: ForgeListOptions): Promise<ForgeItem[]>;
+    listPRs(opts?: ForgeListOptions): Promise<ForgeItem[]>;
+    /** Search the forge for issues/PRs in ANY state (#730) — the escape hatch from the open-only
+     *  list tier. Optional so the seam stays additive: a driver without it simply has no search
+     *  fallback, and the route degrades to `available: false`. Never throws. */
+    searchItems?(kind: 'issue' | 'pr', query: string, opts?: {
+        limit?: number;
+    }): Promise<ForgeSearchData>;
+    /** One issue/PR by number, in any state (#692). `null` when the forge has no such item;
+     *  throws on transport failure. Optional like `searchItems`. */
+    viewItem?(kind: 'issue' | 'pr', number: number): Promise<ForgeItem | null>;
+    /** Draft-PR creation for the review gate (spec 009). Never throws. */
+    createPR(input: DraftPrInput): Promise<DraftPrOutcome>;
+    /** The branch's open/merged PR, or null when none (or the forge is down). */
+    prStatus(branch: string): Promise<ForgePrStatus | null>;
+    prMergeState?(number: number, opts?: {
+        refresh?: boolean;
+    }): Promise<ForgePrMergeStateResult>;
+    readyPR?(number: number, input: {
+        expectedHeadSha: string;
+        expectedHeadRef: string;
+        canProceed?: () => boolean;
+    }): Promise<ForgePrMergeStateResult>;
+    mergePR?(number: number, input: ForgeMergeInput): Promise<ForgeMergeResult>;
+    /** Bounded, read-only file changes for a pull request. */
+    prDiff?(number: number, opts?: {
+        refresh?: boolean;
+    }): Promise<ForgePrDiffResult>;
+    /** Web URL for a ref on the forge, or null when the remote isn't parseable. */
+    viewUrl(kind: ForgeRefKind, ref: string | number): string | null;
+}
+export type { GithubData } from '../../contract/index.js';
+export type { GithubChecksData, GithubRefStatusData, ReferenceStatus, RepoHandleDiscovery } from './github.ts';

package/dist/server/forge/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/server/forge/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/server/forge/types.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,82 @@
+/**
+ * Directory browsing confined to the browse root. Check lexical containment before I/O, then
+ * realpath containment for the requested path and every returned entry. Never disclose escaping
+ * targets.
+ */
+/** 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 | 403 | 404;
+    error: string;
+};
+/** The 403 a macOS privacy denial answers with; the picker offers System Settings beside it. */
+export declare const MACOS_PRIVACY_BLOCKED: 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,217 @@
+import { productName } from '../home/display.js';
+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;
+/**
+ * Home folders macOS guards with a privacy prompt (Files & Folders, Media & Apple Music,
+ * Photos, Full Disk Access). Opening the picker at `~` must not LOOK INSIDE them: the `.git`
+ * probe below is a read inside the folder, and in the desktop app it made macOS ask "Cezar
+ * would like to access Apple Music…" (and Documents, Desktop, Downloads…) before the user
+ * clicked anything. They are still listed; opening one is the user's choice, and so is the
+ * prompt that follows. Their `isRepo` is simply `false`.
+ */
+const PRIVACY_PROTECTED_HOME_DIRS = new Set(['Desktop', 'Documents', 'Downloads', 'Library', 'Movies', 'Music', 'Pictures']);
+/** The 403 a macOS privacy denial answers with; the picker offers System Settings beside it. */
+export const MACOS_PRIVACY_BLOCKED = `macOS privacy settings do not allow ${productName('cezar')} to read this folder.`;
+/**
+ * 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 readEntries(real);
+    if (!Array.isArray(entries))
+        return entries;
+    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 inHome = real === (await realpathOrNull(expandTilde('~')));
+    const dirs = await listDirs(root, real, candidates.slice(0, MAX_ENTRIES), inHome);
+    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,
+        },
+    };
+}
+/** The entries of `real`, or the failure to answer when it cannot be read. */
+async function readEntries(real) {
+    let readError = null;
+    const entries = await readdir(real, { withFileTypes: true }).catch((error) => {
+        readError = error;
+        return null;
+    });
+    if (entries === null) {
+        // macOS privacy (TCC) refuses with EPERM — a folder the parent listing already showed, that
+        // the user can unblock in System Settings. Saying "no such directory" there left them stuck.
+        if (process.platform === 'darwin' && readError?.code === 'EPERM') {
+            return { ok: false, status: 403, error: MACOS_PRIVACY_BLOCKED };
+        }
+        // Unreadable otherwise (mode 0300, permission-denied mount) — indistinguishable from
+        // absent, on purpose.
+        return { ok: false, status: 404, error: 'no such directory' };
+    }
+    return entries;
+}
+/** The listed directories among `entries`, each with whether it is a git repository. */
+async function listDirs(root, real, entries, inHome) {
+    const dirs = [];
+    for (const entry of 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: inHome && PRIVACY_PROTECTED_HOME_DIRS.has(entry.name) ? false : await exists(join(childPath, '.git')),
+        });
+    }
+    return dirs;
+}
+//# 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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"}