@hwip/cli 0.0.1 → 0.1.0

package/dist/file-crypto.js

@@ -0,0 +1,272 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveStream = exports.DOWNLOAD_MAX_BYTES = exports.withIdleTimeout = exports.createChunkedFileDecryptStream = exports.chunkOf = exports.FILE_CHUNK_CAPABILITY = exports.FILE_CHUNK_PREFIX_BYTES = exports.FILE_CHUNK_BYTES = exports.createFileDecryptStream = exports.GCM_IV_BYTES = exports.GCM_TAG_BYTES = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_stream_1 = require("node:stream");
+const promises_2 = require("node:stream/promises");
+const private_files_js_1 = require("./private-files.js");
+/**
+ * Streaming decrypt of a file the web / MCP side produced with
+ * `libs/crypto` `encryptFile` (WebCrypto AES-256-GCM, 12-byte IV). That
+ * API is one-shot; a 1 GiB attachment would sit in memory here, so this
+ * is the same wire format on `node:crypto`'s incremental cipher:
+ * WebCrypto appends the 16-byte GCM tag to the ciphertext, and the stream
+ * holds back the last 16 bytes of whatever it is fed as that tag.
+ *
+ * The key is the raw per-file AES key, already unwrapped from the
+ * attachment's `deviceKeyMap` slot (see `unwrapDeviceKey` in crypto.ts).
+ */
+exports.GCM_TAG_BYTES = 16;
+exports.GCM_IV_BYTES = 12;
+const createFileDecryptStream = (rawKey, iv) => {
+    if (rawKey.length !== 32)
+        throw new Error(`file key must be 32 bytes, got ${rawKey.length}`);
+    if (iv.length !== exports.GCM_IV_BYTES)
+        throw new Error(`file iv must be ${exports.GCM_IV_BYTES} bytes, got ${iv.length}`);
+    const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', rawKey, iv);
+    let tail = Buffer.alloc(0);
+    return new node_stream_1.Transform({
+        transform(chunk, _enc, done) {
+            const joined = tail.length ? Buffer.concat([tail, chunk]) : chunk;
+            if (joined.length <= exports.GCM_TAG_BYTES) {
+                tail = joined;
+                done();
+                return;
+            }
+            const body = joined.subarray(0, joined.length - exports.GCM_TAG_BYTES);
+            tail = Buffer.from(joined.subarray(joined.length - exports.GCM_TAG_BYTES));
+            done(null, decipher.update(body));
+        },
+        flush(done) {
+            if (tail.length < exports.GCM_TAG_BYTES) {
+                done(new Error('ciphertext shorter than the GCM tag'));
+                return;
+            }
+            try {
+                decipher.setAuthTag(tail);
+                done(null, decipher.final()); // throws on a bad tag: tampered, truncated, wrong key
+            }
+            catch (err) {
+                done(err instanceof Error ? err : new Error(String(err)));
+            }
+        },
+    });
+};
+exports.createFileDecryptStream = createFileDecryptStream;
+/**
+ * A file sealed in chunks (`file-chunk-v1`), the format a phone seals a file
+ * in that is too large to hold in memory. The padded plaintext is cut into
+ * `FILE_CHUNK_BYTES` pieces — the last one shorter or equal, never empty —
+ * and each is sealed alone with AES-256-GCM under the file key, no AAD:
+ *
+ *   nonce = prefix[7] ‖ piece index (u32 big-endian) ‖ 0x01 on the last piece, else 0x00
+ *   file  = every `ciphertext ‖ tag[16]`, in order
+ *
+ * The index in the nonce refuses a piece moved or repeated; the last-piece
+ * flag refuses a file cut at a piece's end, and bytes added after it. The
+ * prefix travels where a whole-sealed file's IV does (`iv`), and the sealed
+ * message says `chunk` next to it — see `chunkOf`. Vectors:
+ * `file-chunk.vectors.json` (scripts/gen-file-chunk-vectors.py).
+ */
+exports.FILE_CHUNK_BYTES = 1_048_576;
+exports.FILE_CHUNK_PREFIX_BYTES = 7;
+/** What a listener tells senders it opens (`capabilities` on its device record). */
+exports.FILE_CHUNK_CAPABILITY = 'file-chunk-v1';
+/** Feeds the reader keeps apart before it joins them. */
+const MAX_HELD_FEEDS = 1024;
+/**
+ * The `chunk` a sender wrote beside a file's `iv`: absent for a file sealed
+ * whole, `FILE_CHUNK_BYTES` for one sealed in chunks. Any other value is a
+ * format this build does not open — `ok: false`, and the file is left alone.
+ */
+const chunkOf = (said) => {
+    if (said === undefined)
+        return { ok: true };
+    return said === exports.FILE_CHUNK_BYTES ? { ok: true, chunk: exports.FILE_CHUNK_BYTES } : { ok: false };
+};
+exports.chunkOf = chunkOf;
+/**
+ * Streaming decrypt of a file sealed in chunks. A piece is opened only once
+ * a byte past it has arrived, because whether it is the last one is in its
+ * nonce: what is left when the stream ends is the last piece, and it has to
+ * open as one. Pieces already opened have reached the `.part` file by then;
+ * `saveStream` removes it on any failure, so nothing a later piece disowns
+ * is ever linked into place.
+ */
+const createChunkedFileDecryptStream = (rawKey, prefix, chunk = exports.FILE_CHUNK_BYTES) => {
+    if (rawKey.length !== 32)
+        throw new Error(`file key must be 32 bytes, got ${rawKey.length}`);
+    if (prefix.length !== exports.FILE_CHUNK_PREFIX_BYTES)
+        throw new Error(`chunked file prefix must be ${exports.FILE_CHUNK_PREFIX_BYTES} bytes, got ${prefix.length}`);
+    if (!Number.isSafeInteger(chunk) || chunk <= 0)
+        throw new Error(`chunk size must be a whole number of bytes above zero, got ${chunk}`);
+    const sealedPiece = chunk + exports.GCM_TAG_BYTES;
+    // What has arrived and is not opened yet, joined only once it holds a whole
+    // piece: joining at every feed would copy up to a chunk each time.
+    let held = [];
+    let heldBytes = 0;
+    let index = 0;
+    const open = (piece, last) => {
+        const nonce = Buffer.alloc(exports.GCM_IV_BYTES);
+        prefix.copy(nonce);
+        nonce.writeUInt32BE(index++, exports.FILE_CHUNK_PREFIX_BYTES);
+        nonce[exports.GCM_IV_BYTES - 1] = last ? 1 : 0;
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', rawKey, nonce);
+        decipher.setAuthTag(piece.subarray(piece.length - exports.GCM_TAG_BYTES));
+        const plain = decipher.update(piece.subarray(0, piece.length - exports.GCM_TAG_BYTES));
+        decipher.final(); // checks the tag; GCM has no bytes left to give here
+        return plain;
+    };
+    return new node_stream_1.Transform({
+        transform(fed, _enc, done) {
+            held.push(fed);
+            heldBytes += fed.length;
+            // A peer that sends a byte at a time does not get to pile up a million buffers.
+            if (held.length > MAX_HELD_FEEDS)
+                held = [Buffer.concat(held)];
+            if (heldBytes <= sealedPiece) {
+                done();
+                return;
+            }
+            try {
+                let rest = Buffer.concat(held);
+                while (rest.length > sealedPiece) {
+                    this.push(open(rest.subarray(0, sealedPiece), false));
+                    rest = rest.subarray(sealedPiece);
+                }
+                held = [rest];
+                heldBytes = rest.length;
+                done();
+            }
+            catch (err) {
+                done(err instanceof Error ? err : new Error(String(err)));
+            }
+        },
+        flush(done) {
+            if (heldBytes <= exports.GCM_TAG_BYTES) {
+                done(new Error('chunked file ends without a last piece'));
+                return;
+            }
+            try {
+                done(null, open(Buffer.concat(held), true)); // throws on a piece that is not the last: cut short, or more was sealed after it
+            }
+            catch (err) {
+                done(err instanceof Error ? err : new Error(String(err)));
+            }
+        },
+    });
+};
+exports.createChunkedFileDecryptStream = createChunkedFileDecryptStream;
+/**
+ * Abort `controller` when `source` goes quiet for `idleMs`. A stalled S3
+ * connection would otherwise park a download — and its part file — for
+ * the life of the daemon with nothing in the log. Bytes still flowing,
+ * however slowly, never trip it: a 1 GiB file on a bad link is not a stall.
+ * More than `maxBytes` fails the stream: a body that never ends is not a
+ * stall either, and would fill the disk.
+ */
+const withIdleTimeout = (source, idleMs, controller, maxBytes = Infinity) => {
+    let timer = null;
+    let seen = 0;
+    const arm = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => controller.abort(new Error(`no bytes for ${idleMs} ms`)), idleMs);
+        timer.unref();
+    };
+    const guard = new node_stream_1.Transform({
+        transform(chunk, _enc, done) {
+            arm();
+            seen += chunk.length;
+            if (seen <= maxBytes)
+                return done(null, chunk);
+            if (timer)
+                clearTimeout(timer);
+            done(new Error(`download passed the ${maxBytes}-byte limit`));
+        },
+        flush(done) { if (timer)
+            clearTimeout(timer); done(); },
+    });
+    arm();
+    // `pipeline`, not `pipe`: a failure downstream (bad tag, disk, name cap)
+    // must destroy the source too, or the response body sits open until the
+    // idle timer fires. Errors surface through the returned stream.
+    void (0, promises_2.pipeline)(source, guard).catch(() => undefined);
+    return guard;
+};
+exports.withIdleTimeout = withIdleTimeout;
+/**
+ * The most bytes one download may carry: the largest file any tier may send
+ * (1 GiB, `fileMaxBytes`), plus the Padmé padding (at most about 12%) and
+ * the GCM tag a sealed file adds. The record's `fileSize` is the relay's
+ * word, so it cannot be the limit; without one, a URL that streams forever
+ * fills the disk.
+ */
+exports.DOWNLOAD_MAX_BYTES = 1.25 * 1024 ** 3;
+/** How many `nextDest()` candidates `saveStream` tries before giving up. */
+const MAX_LINK_ATTEMPTS = 100;
+const isErrno = (err, code) => typeof err === 'object' && err !== null && 'code' in err && err.code === code;
+/**
+ * Stream `source` to the path `nextDest()` names, optionally decrypting
+ * on the way — a file sealed whole, or with `chunk` one sealed in chunks
+ * (`iv` is then its 7-byte prefix). The bytes go to a private `.part` file first (a per-call
+ * random name, so two saves of the same file cannot touch each other's
+ * temp) and are fsynced before being linked into place — a reader never
+ * sees a half file, and an authentication failure (which GCM only reports
+ * at the very end) leaves nothing behind. `link` refuses an existing dest
+ * where `rename` would replace it; on that collision `nextDest()` is asked
+ * again, so a name taken between the caller's check and here costs a
+ * ` (n)` suffix, never the download. Resolves with the path written and
+ * the plaintext byte count.
+ */
+const saveStream = async (source, nextDest, decrypt) => {
+    const first = nextDest();
+    const dir = (0, node_path_1.dirname)(first);
+    (0, private_files_js_1.mkdirHandedBack)(dir);
+    const part = (0, node_path_1.join)(dir, `.hwip-${(0, node_crypto_1.randomBytes)(6).toString('hex')}.part`);
+    let bytes = 0;
+    const counter = new node_stream_1.Transform({
+        transform(chunk, _enc, done) { bytes += chunk.length; done(null, chunk); },
+    });
+    try {
+        // Before the part file exists: a key or an iv the format refuses throws here.
+        const opened = !decrypt ? null : decrypt.chunk === undefined
+            ? (0, exports.createFileDecryptStream)(decrypt.rawKey, decrypt.iv)
+            : (0, exports.createChunkedFileDecryptStream)(decrypt.rawKey, decrypt.iv, decrypt.chunk);
+        const sink = (0, node_fs_1.createWriteStream)(part, { flags: 'wx' });
+        if (opened)
+            await (0, promises_2.pipeline)(source, opened, counter, sink);
+        else
+            await (0, promises_2.pipeline)(source, counter, sink);
+        const fh = await (0, promises_1.open)(part, 'r+');
+        try {
+            await fh.sync();
+        }
+        finally {
+            await fh.close();
+        }
+        let dest = first;
+        for (let attempt = 1;; attempt++) {
+            try {
+                await (0, promises_1.link)(part, dest);
+                break;
+            }
+            catch (err) {
+                if (!isErrno(err, 'EEXIST') || attempt >= MAX_LINK_ATTEMPTS)
+                    throw err;
+                dest = nextDest();
+            }
+        }
+        // The file is in place; a temp that will not go is not a failed save.
+        await (0, promises_1.unlink)(part).catch(() => undefined);
+        return { path: dest, bytes };
+    }
+    catch (err) {
+        (0, node_fs_1.rmSync)(part, { force: true });
+        throw err;
+    }
+};
+exports.saveStream = saveStream;

package/dist/file-view-budget.d.ts

@@ -0,0 +1,15 @@
+/** D6: the most file content one session may read in a window. Only a blob's text pages count; a listing carries no content. */
+export declare const FILE_VIEW_WINDOW_BYTES: number;
+export declare const FILE_VIEW_WINDOW_MS: number;
+export interface ByteBudget {
+    /** Has `key` already read its share in the current window? A request that finds it spent is refused before it reads. */
+    spent: (key: string, now?: number) => boolean;
+    /** Count `bytes` against `key`. The window opens at the first byte counted after the last one closed. */
+    charge: (key: string, bytes: number, now?: number) => void;
+}
+/**
+ * A fixed window per key. Keys are session names a relay can make up, so a window that has run out is
+ * dropped whenever any key is looked at — the map holds only sessions that read something recently.
+ */
+export declare const createByteBudget: (limitBytes: number, windowMs: number) => ByteBudget;
+//# sourceMappingURL=file-view-budget.d.ts.map

package/dist/file-view-budget.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createByteBudget = exports.FILE_VIEW_WINDOW_MS = exports.FILE_VIEW_WINDOW_BYTES = void 0;
+/** D6: the most file content one session may read in a window. Only a blob's text pages count; a listing carries no content. */
+exports.FILE_VIEW_WINDOW_BYTES = 32 * 1024 * 1024;
+exports.FILE_VIEW_WINDOW_MS = 10 * 60_000;
+/**
+ * A fixed window per key. Keys are session names a relay can make up, so a window that has run out is
+ * dropped whenever any key is looked at — the map holds only sessions that read something recently.
+ */
+const createByteBudget = (limitBytes, windowMs) => {
+    const windows = new Map();
+    const prune = (now) => {
+        for (const [key, w] of windows)
+            if (now - w.opened >= windowMs)
+                windows.delete(key);
+    };
+    return {
+        spent: (key, now = Date.now()) => {
+            prune(now);
+            return (windows.get(key)?.bytes ?? 0) >= limitBytes;
+        },
+        charge: (key, bytes, now = Date.now()) => {
+            prune(now);
+            // Nothing counted opens no window.
+            if (bytes <= 0)
+                return;
+            const w = windows.get(key) ?? { opened: now, bytes: 0 };
+            w.bytes += bytes;
+            windows.set(key, w);
+        },
+    };
+};
+exports.createByteBudget = createByteBudget;

package/dist/file-view-switch.d.ts

@@ -0,0 +1,28 @@
+import { type SwitchOffBy } from './project-switch.js';
+/** Why the file view is off for the project at `dir`, or `null` when it is on. A switch file that cannot be read counts as off. */
+export declare const fileViewOffBy: (dir: string, env?: NodeJS.ProcessEnv) => SwitchOffBy | null;
+export declare const setFileView: (dir: string, on: boolean, scope: import("./project-switch.js").SwitchScope) => void;
+export declare const describeFileView: (offBy: SwitchOffBy | null) => string;
+/** How many reads `log` shows: the most recent. */
+export declare const FILE_VIEW_LOG_LINES = 50;
+export declare const escapeLogUnsafe: (text: string) => string;
+/**
+ * The most recent reads in a listener log, oldest first, without the stamp (the line carries its own date).
+ * `older` is the log the listener keeps when it rotates; it is read only when the current one has too few.
+ */
+export declare const recentFileViewReads: (current: string, older: string, limit?: number) => string[];
+export interface FileViewCommandDeps {
+    cwd: () => string;
+    out: (line: string) => void;
+    err: (line: string) => void;
+    env: NodeJS.ProcessEnv;
+    repoRoot: (cwd: string) => string | null;
+    /** The listener log and the one it rotated out, as text; '' for a log that is not there. Throws for one that cannot be read. */
+    readLogs: () => {
+        current: string;
+        older: string;
+    };
+}
+export declare const runFileView: (sub: string | undefined, global: boolean, deps: FileViewCommandDeps) => number;
+export declare const handleFileView: (args: Record<string, string | boolean>) => Promise<number>;
+//# sourceMappingURL=file-view-switch.d.ts.map

package/dist/file-view-switch.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleFileView = exports.runFileView = exports.recentFileViewReads = exports.escapeLogUnsafe = exports.FILE_VIEW_LOG_LINES = exports.describeFileView = exports.setFileView = exports.fileViewOffBy = void 0;
+const node_fs_1 = require("node:fs");
+const args_js_1 = require("./args.js");
+const listener_process_js_1 = require("./listener-process.js");
+const project_switch_js_1 = require("./project-switch.js");
+const session_diff_js_1 = require("./session-diff.js");
+/**
+ * The switch for the phone's file view (V13): one state file per project (`file-view-off-<hash>`) and one for
+ * every project (`file-view-off-default`), local to this machine. On unless turned off — the default is on (D10).
+ * `HWIP_FILE_VIEW=0` in the listener's environment turns it off for that run. The listener asks with the
+ * repository root of the session the request names, which is the directory `hwip file-view off` writes under.
+ */
+const fileView = (0, project_switch_js_1.projectSwitch)('file-view', 'HWIP_FILE_VIEW');
+/** Why the file view is off for the project at `dir`, or `null` when it is on. A switch file that cannot be read counts as off. */
+exports.fileViewOffBy = fileView.offBy;
+exports.setFileView = fileView.set;
+const REASON = {
+    env: 'HWIP_FILE_VIEW is set to off here; a running listener reads its own environment',
+    project: 'turned off for this project',
+    global: 'turned off for every project',
+    unreadable: 'the switch file cannot be read, so it is treated as off',
+};
+const describeFileView = (offBy) => offBy === null ? 'file view: on' : `file view: off (${REASON[offBy]})`;
+exports.describeFileView = describeFileView;
+const USAGE = 'Usage: hwip file-view [status | on | off | log] [--global]';
+/** How many reads `log` shows: the most recent. */
+exports.FILE_VIEW_LOG_LINES = 50;
+/**
+ * What a terminal or a reader obeys that must not reach a log line as itself: control characters (ESC, CR), DEL, C1
+ * controls (U+009B is CSI), zero-width and direction marks, line and paragraph separators, bidi overrides and isolates,
+ * the byte-order mark, interlinear annotation marks and the tag characters. Written by the listener after JSON quoting
+ * and applied again when the line is read back: a log is a file other lines also land in.
+ */
+const LOG_UNSAFE = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2060-\u2064\u2066-\u2069\ufeff\ufff9-\ufffb\u{e0000}-\u{e007f}]/gu;
+const escapeLogUnsafe = (text) => text.replace(LOG_UNSAFE, (c) => {
+    const code = c.codePointAt(0);
+    return code > 0xffff ? `\\u{${code.toString(16)}}` : `\\u${code.toString(16).padStart(4, '0')}`;
+});
+exports.escapeLogUnsafe = escapeLogUnsafe;
+/**
+ * The log line a read leaves (`listener.ts`, `logFileView`): the stamp, then `file-view: ` and the fields, in that
+ * shape. A line that only starts like one is not a read — the log also holds lines that carry names a relay chose.
+ */
+const READ_LINE = /^\[[^\]]*\] file-view: (at=\S+ device=".*" session=".*" op=(?:tree|blob) path=".*" bytes=\d+ masked=\d+ result=[a-z_]+)$/;
+/**
+ * The most recent reads in a listener log, oldest first, without the stamp (the line carries its own date).
+ * `older` is the log the listener keeps when it rotates; it is read only when the current one has too few.
+ */
+const recentFileViewReads = (current, older, limit = exports.FILE_VIEW_LOG_LINES) => {
+    const reads = (text) => text.split('\n').flatMap((line) => {
+        const match = READ_LINE.exec(line);
+        return match ? [(0, exports.escapeLogUnsafe)(match[1])] : [];
+    });
+    const now = reads(current);
+    return (now.length >= limit ? now : [...reads(older), ...now]).slice(-limit);
+};
+exports.recentFileViewReads = recentFileViewReads;
+/** A log that is not there is empty; one that is there and cannot be read is an error, not "no reads". */
+const readIfThere = (path) => {
+    try {
+        return (0, node_fs_1.readFileSync)(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return '';
+        throw err;
+    }
+};
+const runFileView = (sub, global, deps) => {
+    const word = sub ?? 'status';
+    if (word !== 'status' && word !== 'on' && word !== 'off' && word !== 'log') {
+        deps.err(`hwip file-view: unknown subcommand '${word}'. ${USAGE}`);
+        return 2;
+    }
+    if (global && (word === 'status' || word === 'log')) {
+        deps.err(`hwip file-view: --global goes with on or off. ${USAGE}`);
+        return 2;
+    }
+    if (word === 'log') {
+        let reads;
+        try {
+            const { current, older } = deps.readLogs();
+            reads = (0, exports.recentFileViewReads)(current, older);
+        }
+        catch (err) {
+            deps.err(`hwip file-view: could not read the listener log: ${err.message}`);
+            return 1;
+        }
+        if (reads.length === 0) {
+            deps.out('file view: no reads on record');
+            // A listener run in the foreground writes to its terminal, so an empty log proves nothing about it.
+            deps.out('(only a listener started by hwip cc or as a service writes ~/.hwip/listener.log; one run in the foreground prints to its own terminal)');
+        }
+        for (const read of reads)
+            deps.out(read);
+        return 0;
+    }
+    const dir = (0, project_switch_js_1.projectDirOf)(deps.cwd(), deps.repoRoot);
+    if (word !== 'status') {
+        try {
+            (0, exports.setFileView)(dir, word === 'on', global ? 'global' : 'project');
+        }
+        catch (err) {
+            deps.err(`hwip file-view: could not change the switch: ${err.message}`);
+            return 1;
+        }
+    }
+    deps.out((0, exports.describeFileView)((0, exports.fileViewOffBy)(dir, deps.env)));
+    return 0;
+};
+exports.runFileView = runFileView;
+const handleFileView = async (args) => (0, exports.runFileView)(typeof args._arg1 === 'string' && args._arg1 ? args._arg1 : undefined, (0, args_js_1.flagOn)(args, 'global'), {
+    cwd: () => process.cwd(),
+    out: (line) => console.log(line),
+    err: (line) => console.error(line),
+    env: process.env,
+    repoRoot: session_diff_js_1.repoRootOf,
+    readLogs: () => ({ current: readIfThere(listener_process_js_1.LISTENER_LOG_FILE), older: readIfThere(`${listener_process_js_1.LISTENER_LOG_FILE}.old`) }),
+});
+exports.handleFileView = handleFileView;

package/dist/file-view.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Reading a session's repository for the phone's file view (F5): the one place
+ * the working tree is opened for it. Design: hwip `docs/file-view.md` (V1~V14,
+ * D1~D13); this module is V6, V7, V9, V10, V11, D4 and D5.
+ *
+ * What a path may be and what the phone may see of the tree is decided here and
+ * nowhere else. Nothing here knows about sealing, the wire or who asked — the
+ * listener decides that; this decides what is read and what is never opened.
+ *
+ * git is run only through `gitIn`, with constant arguments. What this module adds
+ * is `ls-files` (twice) for the visible set and `check-attr` (through `filteredPaths`)
+ * for `filter=`; `resolveBase` and `filteredPaths` bring their own `rev-parse` and
+ * `hash-object`. None of them runs a filter. One caller path goes to git, after `--`.
+ */
+import { type DiffResult } from './session-diff.js';
+/** Most entries in one page of a directory listing. */
+export declare const TREE_PAGE_MAX_ENTRIES = 500;
+/** A file past this is not read. Same value as an untracked file's line count limit in the diff. */
+export declare const FILE_VIEW_MAX_BYTES: number;
+/**
+ * V7 ①, the string rules. A path is repo-relative and names one thing: not empty
+ * (a directory request's `""` for the root is the tree handler's to allow), no NUL
+ * or other control character, not absolute, at most 1,024 UTF-8 bytes, and no
+ * segment that is empty, `.`, `..` or — at any depth, in any case — `.git` (a
+ * case-insensitive file system opens `.GIT` as `.git`, D11). A leading `-` is fine:
+ * the path only ever follows `--`.
+ */
+export declare const isViewablePath: (path: string) => boolean;
+/** What kind of thing git lists at a path. `nested` is an untracked repository (`ls-files --others` prints it as `dir/`). */
+export interface VisibleEntry {
+    /** The tracked mode (`100644`, `120000`, `160000`, …); absent for an untracked path. */
+    mode?: string;
+    /** The tracked object id (a gitlink's commit); absent for an untracked path. */
+    oid?: string;
+    nested?: true;
+}
+/**
+ * V6, the visible set: what git lists as tracked (`ls-files --stage`) plus what it lists as
+ * untracked and not ignored (`ls-files --others --exclude-standard`), under `scope` (the
+ * whole repository when absent). An ignored path is simply not there, so asking for it by
+ * name answers like a path that does not exist. The caller matches a path against the keys
+ * exactly; the pathspec only narrows what git has to print. A path the phone could never
+ * ask for (`isViewablePath`) or whose bytes are not UTF-8 is left out, so a listing never
+ * shows a name that cannot be opened.
+ */
+export declare const visibleSet: (root: string, scope: string | undefined, deadline?: number) => DiffResult<{
+    entries: Map<string, VisibleEntry>;
+}>;
+export type TreeEntryType = 'file' | 'dir' | 'symlink' | 'submodule';
+export interface TreeEntry {
+    name: string;
+    type: TreeEntryType;
+}
+/** `absent` is a path outside the visible set, ignored, or not a directory — the three look the same (V6). */
+export type TreeResult = DiffResult<{
+    body: 'entries';
+    entries: TreeEntry[];
+    truncated: boolean;
+    cursor?: string;
+} | {
+    body: 'absent';
+}>;
+/**
+ * One page of the entries directly under `dir` (`""` is the repository root), by
+ * name in UTF-8 byte order. `cursor` is the last name of the page before; the page is
+ * at most `TREE_PAGE_MAX_ENTRIES` and `truncated` says there is more. A directory is
+ * only a name some visible path continues under, so an empty one, an ignored one and
+ * one that is not there are all `absent`.
+ */
+export declare const listTree: (root: string, dir: string, cursor?: string, deadline?: number) => TreeResult;
+export type BlobBody = {
+    body: 'text';
+    text: string;
+    masked: number;
+} | {
+    body: 'binary';
+    size: number;
+} | {
+    body: 'symlink';
+    target: string;
+} | {
+    body: 'filtered';
+} | {
+    body: 'submodule';
+    commit?: string;
+} | {
+    body: 'absent';
+};
+export type BlobResult = DiffResult<BlobBody>;
+/** Test seams: where an agent could swap the file — after the symlink walk (V7 ③) and before the `lstat` that judges it, and between that `lstat` and the `open` that reads it. */
+export interface ReadBlobOptions {
+    deadline?: number;
+    beforeLstat?: () => void;
+    beforeOpen?: () => void;
+}
+/**
+ * What a file looks like to the phone. The order is the design's V7: ① the string rules
+ * (`bad_path`) · ② the visible set, exact match · ③ no symlink on the way · ④ `lstat`: a
+ * symlink is shown as its target string and never followed, a gitlink or nested repository
+ * is shown as a submodule and never entered, anything but a regular file is `absent` ·
+ * D4 and V9 (`filter=`) say `filtered` · ⑤ open with `O_NOFOLLOW | O_NONBLOCK`, `fstat`
+ * the descriptor and compare it with ④ — a different file is `absent`, a hard link is
+ * `filtered` (D5) · V11: past 1 MiB is `too_large`, a NUL in the first 8,000 bytes is
+ * `binary` · V10: the whole text is masked before the caller pages it. A path outside the
+ * set, ignored, deleted or swapped is `absent`, never an error: the phone cannot tell them apart.
+ */
+export declare const readBlob: (root: string, path: string, options?: ReadBlobOptions) => BlobResult;
+//# sourceMappingURL=file-view.d.ts.map