@evandu/super-pi 0.0.0-stage → 0.1.0

package/dist/server/files.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Above this a read is refused rather than served. 5MB is roughly a large source file or a long document,
+ * and it is deliberately far below the point where an editor tab stops being useful: this panel is for
+ * reading and editing code and markdown, and a file too big for that has not become more editable by
+ * being loaded whole. The size is checked from `stat` BEFORE the read, so an oversized file costs one
+ * `stat` rather than a full buffer.
+ */
+export declare const MAX_FILE_BYTES: number;
+/** Cap on one directory listing, so a `node_modules` or a generated assets folder cannot produce a
+ *  multi-megabyte response. The count is reported as `truncated` rather than applied silently. */
+export declare const MAX_DIR_ENTRIES = 2000;
+/** Cap on a recursive filename search, for the same reason: a scan of a large repository has to end
+ *  somewhere. The UI says the list was cut rather than pretending it is complete. */
+export declare const MAX_SEARCH_RESULTS = 500;
+/** How deep the recursive search walks. Twelve levels is past any real source tree; the cap is what
+ *  turns a pathologically deep dependency tree from a hang into a result. */
+export declare const MAX_SEARCH_DEPTH = 12;
+/**
+ * Extensions this panel OPENS without needing a sniff. It is a hint used only to label a file in the tree
+ * before it is read, and never as a permission: a `.png` is refused by name even if a sniffing pass would
+ * have liked it, and a `.txt` holding PNG bytes is still refused by the sniff.
+ */
+export declare const TEXT_EXTENSIONS: Set<string>;
+/** The HTTP failure, carried as a status so the route can render it without a second switch. `details` is
+ *  for the cases where the CLIENT can act on more than the sentence - today that is a conflict, where the
+ *  current etag is what lets the UI offer a deliberate "overwrite anyway" instead of a blind one. */
+export declare class FilesError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly details?: unknown;
+    constructor(status: number, message: string, code?: string | undefined, details?: unknown);
+}
+/**
+ * Whether `candidate` is `root` itself or something under it.
+ *
+ * THE COMPARISON IS NOT `startsWith(root)`, because that is the traversal bug this whole file exists to
+ * avoid: with root `/home/u/proj`, the string `/home/u/proj-secrets` also starts with `/home/u/proj`.
+ * `relative()` asks the question in the form that can be answered exactly - it returns a path RELATIVE to
+ * the root, so "escaped" becomes "the relative path begins by going up", which is true for
+ * `/home/u/proj/../etc` and false for `/home/u/proj/etc`. `isAbsolute(relative)` catches the case
+ * `relative` cannot express: two different Windows drives, where there is no relative path between them
+ * and it hands back an absolute one.
+ */
+export declare function contains(root: string, candidate: string): boolean;
+/** A guard bound to one workspace root. `resolveInsideRoot` is the one-shot form and is what callers are
+ *  meant to use; the factory exists for the two places that check many paths against the SAME root in one
+ *  request, so the canonical form of the root is resolved once instead of once per entry. */
+export declare function createRootGuard(root: string): (requested: string | null | undefined) => Promise<string>;
+/**
+ * THE CONTAINMENT CHECK. Every read, write, listing and search in this file goes through it, and the
+ * route layer is not allowed to do its own path arithmetic.
+ *
+ * `requested` arrives already percent-decoded, because `URLSearchParams` decodes once when the query is
+ * parsed. That is the right number of decodes: `%2e%2e%2f` is `../` by the time it gets here and is
+ * refused by the lexical test, while decoding a SECOND time would turn the harmless literal `%2e%2e%2f`
+ * into a live traversal - inventing an attack the URL parser does not actually have. The route decodes
+ * nothing further and never passes the raw query string down.
+ */
+export declare function resolveInsideRoot(root: string, requested: string | null | undefined): Promise<string>;
+/**
+ * The identity of a file's CURRENT bytes, as far as a filesystem can cheaply say.
+ *
+ * Built from size and the nanosecond modification time rather than a content hash: hashing every file on
+ * every read would make opening a tab cost a full pass over the file, and the two fields together already
+ * change on any edit a human would call an edit. `bigint: true` is what makes this exact - the
+ * millisecond float `stat` reports by default rounds two edits inside the same millisecond into one
+ * value, and an external-change check that misses a change is worse than no check at all, because the
+ * user has been told it is safe to save.
+ */
+export declare function fileEtag(path: string): Promise<string>;
+export type FileMeta = {
+    etag: string;
+    size: number;
+    modifiedAt: string;
+};
+export declare function fileMeta(path: string): Promise<FileMeta>;
+export declare function looksBinary(sample: Uint8Array): boolean;
+/**
+ * Whether the NAME alone says this is binary.
+ *
+ * `endsWith` is the whole test, and the dot is what makes it a suffix test rather than a substring one:
+ * `"tool.bin".endsWith(".bin")` is true and `"foobin".endsWith(".bin")` is false, because the dot has to be
+ * one of the characters being matched. An earlier version added a "the character before the suffix must be
+ * a dot" guard on top of this, which was wrong - it compared the index of the dot AGAINST ITSELF minus
+ * one, so `"photo.png"` was checked at the `o` and came back false. Every binary file was therefore
+ * reaching the byte sniff instead of being refused by name, and the tests only ever passed because the
+ * fixture binaries also contained NUL bytes. A check that is dead code while a second check quietly does
+ * its job is exactly the kind of thing that survives review, which is why `files-api.test.mjs` asserts
+ * the extension path with a fixture whose CONTENT is text.
+ */
+export declare function hasBinaryExtension(name: string): boolean;
+/** Whether a file is worth putting in an editor tab at all, decided from its NAME alone, for the tree's
+ *  own labelling. The authoritative answer comes from `readWorkspaceFile`, which reads bytes. */
+export declare function isTextName(name: string): boolean;
+/** What a caller is told about one entry in a directory. */
+export type DirEntry = {
+    /** The path RELATIVE to the workspace root, always `/`-separated, never with a leading slash. This is
+     *  the form every client sends back, so there is exactly one spelling of "a file" on the wire and no
+     *  round trip can invent a second one. */
+    path: string;
+    name: string;
+    kind: "directory" | "file" | "symlink";
+    /** Whether a file is worth opening, decided from its name. `null` for a directory. */
+    text: boolean | null;
+    /** Set when this entry is a link, and `kind` becomes `symlink` when it points OUT of the workspace. The
+     *  tree can then say "cannot be opened" before the request comes back 403 rather than after. */
+    symlink?: boolean;
+    /** Set when a link points outside: the containment check's own verdict, surfaced rather than swallowed. */
+    outside?: boolean;
+};
+export type DirListing = {
+    /** The directory that was listed, relative to the root. `""` is the root itself. */
+    path: string;
+    /** Its parent, or `null` at the root - the tree uses this to decide whether to draw an "up" affordance. */
+    parent: string | null;
+    entries: DirEntry[];
+    truncated: boolean;
+};
+/** The `/`-separated relative form used on the wire and in every comparison. */
+export declare function toRelative(root: string, absolute: string): string;
+/** One directory's contents. Directories sort before files, then case-insensitively by name with numeric
+ *  ordering, so `src2` lands between `src` and `src10` rather than after every `srcN`. */
+export declare function listDirectory(root: string, requested: string | null | undefined): Promise<DirListing>;
+export type SearchHit = {
+    path: string;
+    name: string;
+    directory: string;
+};
+export type SearchResult = {
+    hits: SearchHit[];
+    truncated: boolean;
+    skipped: string[];
+};
+/**
+ * A recursive FILENAME search. Filename only, on purpose: content search is a different feature with
+ * different costs - it reads every candidate file, honours the size cap on each one, and it is the thing
+ * that turns a panel into a hang - and the requirement is explicit that this round does not need it.
+ *
+ * Every directory it descends into goes through the SAME guard as every other path here, so the search
+ * cannot be walked out of the workspace by a link, and it stops at `MAX_SEARCH_DEPTH` and
+ * `MAX_SEARCH_RESULTS` so a repository with a vendored dependency tree returns a truncated answer rather
+ * than never returning.
+ */
+export declare function searchByName(root: string, query: string): Promise<SearchResult>;
+export type FileContents = {
+    path: string;
+    content: string;
+    meta: FileMeta;
+    /** Newline convention read off the bytes, so a CRLF file is saved back as CRLF instead of silently
+     *  rewritten to LF - which on Windows is a whole-file diff the user did not ask for. */
+    eol: "\n" | "\r\n";
+};
+/**
+ * Read one file, or refuse it with a reason a person can act on.
+ *
+ * ORDER MATTERS and is the whole reason the refusals are trustworthy: extension, then SIZE from `stat`,
+ * then a sniff, then a fatal decode. The size check precedes the read so an oversized file costs a `stat`
+ * rather than a buffer, and the sniff precedes the decode so binary bytes are never handed to
+ * `TextDecoder` as if they were text - a decode that "succeeds" on binary produces U+FFFD throughout,
+ * which is mojibake, and mojibake that then gets SAVED is how a text editor destroys a binary file.
+ */
+export declare function readWorkspaceFile(root: string, requested: string): Promise<FileContents>;
+export type WriteOutcome = {
+    path: string;
+    meta: FileMeta;
+    created: false;
+};
+/**
+ * Write one EXISTING text file. No creation, no deletion, no rename, no directories.
+ *
+ * THE SCOPE CALL, with its reasoning, because it is a decision and not an omission:
+ *
+ * This panel's stated job is to BROWSE and EDIT what is in the workspace. Creation is refused even though
+ * the brief leaves it open, because creation is the operation where a mistake has no undo: a bad `path`
+ * parameter or a bug that loses one character writes a file the user never asked for and never has to
+ * clean up, whereas a refused write leaves nothing behind. Deletion is deferred by the brief and is
+ * deferred here for the same reason plus the one that matters more - it is irreversible.
+ *
+ * The symmetry is deliberate: create and delete are the two ends of the same axis, and shipping one
+ * without the other is how a "conservative, no surprises" surface becomes a half-built file manager.
+ *
+ * What IS refused regardless: a write to a file that does not exist (428), a write with no `baseEtag` at
+ * all (428 - without one the server cannot tell a save from a blind overwrite, and "may I overwrite" is
+ * not a question this endpoint is allowed to skip), a write whose `baseEtag` no longer matches the file
+ * on disk (409 `stale`), and a write that would push the file past the size cap.
+ *
+ * The write itself is a whole-file replace through a temporary file in the SAME directory and a rename,
+ * so an interrupted save cannot leave a half-written file where a whole one used to be. The temporary name
+ * is derived from the target's OWN name rather than living in the system temp directory, because a rename
+ * across filesystems is not atomic and would silently become a copy.
+ */
+export declare function writeWorkspaceFile(root: string, requested: string, content: string, baseEtag: string | null | undefined): Promise<WriteOutcome>;
+/** Every `FilesError` carries the status it should be rendered with; anything else is a real fault and
+ *  becomes a 500 rather than being dressed up as a refusal the user is asked to understand. */
+export declare function describe(error: unknown): {
+    status: number;
+    body: {
+        error: string;
+        code?: string;
+        [key: string]: unknown;
+    };
+};