@anhlp/alp-daemon 0.0.0-beta.1 → 0.0.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/files.ts ADDED
@@ -0,0 +1,420 @@
1
+ import { constants } from 'node:fs';
2
+ import { lstat, open, opendir, realpath, stat } from 'node:fs/promises';
3
+ import path from 'node:path';
4
+ import { ERROR, RPC_ERROR, WORKSPACE_FILES, blockedFilePath } from '@anhlp/alp-protocol';
5
+ import { gitIgnored, IgnoreUnknown, type GitCheckOptions } from './gitignore.js';
6
+
7
+ // For tests: which git alpd would run, and how many run now.
8
+ export { gitChecksRunning, resolveGit, GIT_CHECK } from './gitignore.js';
9
+
10
+ /**
11
+ * `workspace.files.search` (docs/protocol/alp-json-rpc-v1.md §12.3): the files of a workspace whose
12
+ * path matches a query, as Paseo's command center finds them (server/utils/directory-suggestions.ts
13
+ * at b63a325, with its workspace settings: relative paths, hidden and heavy directories skipped).
14
+ *
15
+ * Read-only and confined to the workspace: the walk starts at the root's real path and never
16
+ * follows a symbolic link (a link is neither listed nor entered). Each directory is checked before
17
+ * and after it is read: a real directory (not a link), at the real path it was reached by, the same
18
+ * one (device and inode) both times; otherwise what was read is dropped. Only names are read, never
19
+ * contents. A link swapped in and back out between those checks, by a writer racing inside the
20
+ * workspace, can still expose names of the directory it pointed to (Node has no openat/O_NOFOLLOW
21
+ * walk); docs/protocol/alp-json-rpc-v1.md §12.3. The walk stops at {@link LIMITS}, checked per
22
+ * entry; the answer then says `truncated`.
23
+ */
24
+
25
+ export const LIMITS = Object.freeze({
26
+ /** Directory levels below the root that are entered (Paseo's DEFAULT_MAX_DEPTH). */
27
+ depth: 12,
28
+ /** Directory entries looked at (Paseo's DEFAULT_MAX_ENTRIES_SCANNED). */
29
+ scanned: 20_000,
30
+ /** Wall time of one search. */
31
+ ms: 3_000,
32
+ /** Results by default and at most (Paseo's DEFAULT_LIMIT, MAX_LIMIT). */
33
+ defaultLimit: 30,
34
+ maxLimit: 100,
35
+ });
36
+
37
+ /** Hidden directories that are still searched (Paseo's WORKSPACE_SEARCH_HIDDEN_DIRECTORIES, with ALP's own). */
38
+ const HIDDEN_DIRECTORIES = new Set(['.agents', '.alp', '.claude', '.codex', '.github', '.opencode', '.paseo', '.vscode']);
39
+ /** Directories never searched (Paseo's IGNORED_DIRECTORY_NAMES). */
40
+ const IGNORED_DIRECTORIES = new Set(['node_modules', 'venv', 'env', 'virtualenv', 'dist', 'build', 'target', 'out', 'coverage', 'vendor', '__pycache__', '.git']);
41
+
42
+ const NONE = Number.MAX_SAFE_INTEGER;
43
+
44
+ type Rank = { path: string; tier: number; segment: number; offset: number; fuzzy: number; depth: number };
45
+
46
+ /** The directory at `directory` as reached by name: a real directory there, not a link, or null. */
47
+ async function identity(directory: string): Promise<string | null> {
48
+ const info = await lstat(directory, { bigint: true });
49
+ if (!info.isDirectory() || (await realpath(directory)) !== directory) return null;
50
+ return `${info.dev}:${info.ino}`;
51
+ }
52
+
53
+ /** Paseo's scoreFuzzySubsequence: the query's letters in order; the first offset plus the gaps, or null. */
54
+ function fuzzy(query: string, candidate: string): number | null {
55
+ let at = 0;
56
+ let first = -1;
57
+ let previous = -1;
58
+ let gaps = 0;
59
+ for (let index = 0; index < candidate.length && at < query.length; index++) {
60
+ if (candidate[index] !== query[at]) continue;
61
+ if (first < 0) first = index;
62
+ if (previous >= 0) gaps += index - previous - 1;
63
+ previous = index;
64
+ at++;
65
+ }
66
+ return at === query.length && first >= 0 ? first + gaps : null;
67
+ }
68
+
69
+ /** Paseo's rankTextMatch (a word) and rankPathMatch (a query with a slash), simplified; null: no match. */
70
+ function rank(relative: string, query: string): Rank | null {
71
+ const lower = relative.toLowerCase();
72
+ const segments = lower.split('/');
73
+ const depth = segments.length;
74
+ if (!query) return { path: relative, tier: 3, segment: NONE, offset: NONE, fuzzy: NONE, depth };
75
+ const offset = lower.indexOf(query);
76
+ if (query.includes('/')) {
77
+ if (offset >= 0) return { path: relative, tier: lower.startsWith(query) ? 1 : 3, segment: NONE, offset, fuzzy: NONE, depth };
78
+ const spread = fuzzy(query, lower);
79
+ return spread === null ? null : { path: relative, tier: 4, segment: NONE, offset: NONE, fuzzy: spread, depth };
80
+ }
81
+ const last = fuzzy(query, segments.at(-1) ?? '');
82
+ const tiers: Array<(segment: string) => boolean> = [segment => segment === query, segment => segment.startsWith(query), segment => segment.includes(query)];
83
+ for (const [tier, test] of tiers.entries()) {
84
+ const segment = segments.findIndex(test);
85
+ if (segment >= 0) return { path: relative, tier, segment, offset: offset >= 0 ? offset : NONE, fuzzy: last ?? NONE, depth };
86
+ }
87
+ if (last !== null) return { path: relative, tier: 4, segment: NONE, offset: NONE, fuzzy: last, depth };
88
+ return null;
89
+ }
90
+
91
+ const compare = (a: Rank, b: Rank) =>
92
+ a.tier - b.tier || a.segment - b.segment || a.offset - b.offset || a.fuzzy - b.fuzzy || a.depth - b.depth || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
93
+
94
+ export class FilesError extends Error {}
95
+
96
+ /**
97
+ * The files under `projectRoot` matching `query`, best first. `projectRoot` must be an absolute path
98
+ * of a directory; anything else throws FilesError.
99
+ */
100
+ export async function searchWorkspaceFiles(projectRoot: string, { query = '', limit = LIMITS.defaultLimit, now = Date.now }: { query?: string; limit?: number; now?: () => number } = {}): Promise<{ files: Array<{ path: string }>; truncated?: true }> {
101
+ if (!path.isAbsolute(projectRoot)) throw new FilesError('projectRoot must be an absolute path');
102
+ let root: string;
103
+ try {
104
+ root = await realpath(projectRoot);
105
+ if (!(await stat(root)).isDirectory()) throw new Error('not a directory');
106
+ } catch {
107
+ throw new FilesError('projectRoot is not a directory alpd can read');
108
+ }
109
+ const wanted = query.trim().replace(/\\/g, '/').replace(/^\.?\/+/, '').toLowerCase();
110
+ const count = Math.max(1, Math.min(LIMITS.maxLimit, Math.trunc(limit)));
111
+ const deadline = now() + LIMITS.ms;
112
+ const found: Rank[] = [];
113
+ let scanned = 0;
114
+ let truncated = false;
115
+ // Breadth first: shallow files are found before the limits stop the walk.
116
+ let level: string[] = [''];
117
+ for (let depth = 0; level.length && !truncated; depth++) {
118
+ const next: string[] = [];
119
+ for (const relative of level) {
120
+ if (scanned >= LIMITS.scanned || now() > deadline) { truncated = true; break; }
121
+ // Reached by names alone from the real root, so it is inside it unless a link took its place.
122
+ const directory = relative ? path.join(root, ...relative.split('/')) : root;
123
+ const files: Rank[] = [];
124
+ const directories: string[] = [];
125
+ try {
126
+ const before = await identity(directory);
127
+ if (!before) continue;
128
+ // Iterated, not read whole: the limits hold inside one large directory too.
129
+ for await (const entry of await opendir(directory)) {
130
+ if (++scanned > LIMITS.scanned || now() > deadline) { truncated = true; break; }
131
+ const name = entry.name;
132
+ const child = relative ? `${relative}/${name}` : name;
133
+ if (entry.isFile()) {
134
+ if (name.startsWith('.')) continue;
135
+ const ranked = rank(child, wanted);
136
+ if (ranked) files.push(ranked);
137
+ } else if (entry.isDirectory()) {
138
+ if (IGNORED_DIRECTORIES.has(name) || (name.startsWith('.') && !HIDDEN_DIRECTORIES.has(name))) continue;
139
+ if (depth < LIMITS.depth) directories.push(child);
140
+ }
141
+ // Links, sockets, devices: neither listed nor entered.
142
+ }
143
+ if ((await identity(directory)) !== before) continue;
144
+ } catch {
145
+ continue;
146
+ }
147
+ found.push(...files);
148
+ next.push(...directories);
149
+ if (truncated) break;
150
+ }
151
+ level = next;
152
+ }
153
+ found.sort(compare);
154
+ return { files: found.slice(0, count).map(entry => ({ path: entry.path })), ...(truncated ? { truncated: true as const } : {}) };
155
+ }
156
+
157
+ // ---- workspace.files.list and workspace.files.read (docs/protocol/alp-json-rpc-v1.md §12.4) ----
158
+
159
+ /**
160
+ * A refusal of workspace.files.list or workspace.files.read: the JSON-RPC code and `data.reason`
161
+ * alpd answers with. Messages are fixed or name only the client's own relative path, never a host
162
+ * path or anything read from a file.
163
+ */
164
+ export class FileAccessError extends Error {
165
+ constructor(message: string, readonly code: number, readonly reason: string) {
166
+ super(message);
167
+ }
168
+ }
169
+
170
+ /** Extra bounds of one listing: entries looked at, and wall time. */
171
+ const LIST_LIMITS = Object.freeze({ scanned: 20_000, ms: 3_000 });
172
+ /** Opening never follows a final link nor waits on a FIFO; Windows has neither flag. */
173
+ const OPEN_FLAGS = process.platform === 'win32' ? constants.O_RDONLY : constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
174
+
175
+ const notFound = (relative: string) => new FileAccessError(`No readable file or directory at ${relative}`, ERROR.notFound, 'not_found');
176
+ const linked = (relative: string) => new FileAccessError(`${relative} is reached through a link, has more than one name, or changed while it was read; alpd does not follow links`, ERROR.forbidden, 'linked');
177
+
178
+ /** The real path of a workspace root that is a directory, else FilesError. */
179
+ async function realRoot(projectRoot: string): Promise<string> {
180
+ if (!path.isAbsolute(projectRoot)) throw new FilesError('projectRoot must be an absolute path');
181
+ try {
182
+ const root = await realpath(projectRoot);
183
+ if (!(await stat(root)).isDirectory()) throw new Error('not a directory');
184
+ return root;
185
+ } catch {
186
+ throw new FilesError('projectRoot is not a directory alpd can read');
187
+ }
188
+ }
189
+
190
+ /**
191
+ * A path relative to the workspace as a client may send it, its segments, or a refusal: '/'
192
+ * separated, no leading slash, drive or backslash, no `.`, `..` or empty segment, no NUL, at most
193
+ * WORKSPACE_FILES.maxPathLength characters. A blocked path (blockedFilePath) is refused as such.
194
+ */
195
+ export function relativeSegments(relative: unknown): string[] {
196
+ if (typeof relative !== 'string' || !relative || [...relative].length > WORKSPACE_FILES.maxPathLength || relative.includes('\0') || relative.includes('\\') || relative.startsWith('/') || /^[A-Za-z]:/.test(relative)) {
197
+ throw new FileAccessError('path must be a relative path inside the workspace, with / between names and no . or .. segment', RPC_ERROR.invalidParams, 'invalid_path');
198
+ }
199
+ const segments = relative.split('/');
200
+ if (segments.some(segment => segment === '' || segment === '.' || segment === '..')) {
201
+ throw new FileAccessError('path must be a relative path inside the workspace, with / between names and no . or .. segment', RPC_ERROR.invalidParams, 'invalid_path');
202
+ }
203
+ if (blockedFilePath(relative)) throw new FileAccessError(`${relative} is not readable remotely: .git, .env files, ALP configuration and key or credential files are always refused`, ERROR.forbidden, 'blocked_path');
204
+ return segments;
205
+ }
206
+
207
+ /**
208
+ * The directories from the root to `segments` (the root first), each checked as reached by name:
209
+ * a real directory, not a link, at its own real path. Their identities (device and inode) are
210
+ * returned so the caller can check them again after reading.
211
+ */
212
+ async function directoryChain(root: string, segments: string[], relative: string): Promise<{ paths: string[]; identities: string[] }> {
213
+ const paths = [root];
214
+ for (let index = 0; index < segments.length; index++) paths.push(path.join(root, ...segments.slice(0, index + 1)));
215
+ const identities: string[] = [];
216
+ for (const directory of paths) identities.push(await directoryIdentity(directory, relative));
217
+ return { paths, identities };
218
+ }
219
+
220
+ /** The identity of a directory reached by name, or the refusal: missing or not a directory, or a link. */
221
+ async function directoryIdentity(directory: string, relative: string): Promise<string> {
222
+ let info;
223
+ try {
224
+ info = await lstat(directory, { bigint: true });
225
+ } catch {
226
+ throw notFound(relative);
227
+ }
228
+ if (info.isSymbolicLink()) throw linked(relative);
229
+ if (!info.isDirectory()) throw notFound(relative);
230
+ let real;
231
+ try {
232
+ real = await realpath(directory);
233
+ } catch {
234
+ throw notFound(relative);
235
+ }
236
+ if (real !== directory) throw linked(relative);
237
+ return `${info.dev}:${info.ino}`;
238
+ }
239
+
240
+ /** The chain checked again: the same directories, else the read is refused. */
241
+ async function sameChain(chain: { paths: string[]; identities: string[] }, relative: string): Promise<void> {
242
+ for (const [index, directory] of chain.paths.entries()) {
243
+ let now;
244
+ try {
245
+ now = await directoryIdentity(directory, relative);
246
+ } catch {
247
+ throw linked(relative);
248
+ }
249
+ if (now !== chain.identities[index]) throw linked(relative);
250
+ }
251
+ }
252
+
253
+ /**
254
+ * Which of `paths` .gitignore hides (gitignore.ts, Git's own answer), failing closed: when Git
255
+ * cannot answer, every path counts as ignored. No repository or no Git: none is.
256
+ */
257
+ async function ignoredOf(root: string, paths: string[], git?: GitCheckOptions): Promise<(path: string) => boolean> {
258
+ try {
259
+ const ignored = await gitIgnored(root, paths, git);
260
+ return ignored ? entry => ignored.has(entry) : () => false;
261
+ } catch (error) {
262
+ if (!(error instanceof IgnoreUnknown)) throw error;
263
+ return () => true;
264
+ }
265
+ }
266
+
267
+ /**
268
+ * The bytes of a regular file reached by name, or undefined when it is larger than `maxBytes`;
269
+ * throws when it is missing, not a regular file, a link, has more than one name, or is not the
270
+ * file it was a moment before. The file is opened without following a final link and checked by
271
+ * its handle (same device and inode as by name, before and after).
272
+ */
273
+ /** Test probes: called between the checks of a read, where a racing writer could change the file. */
274
+ export type FileProbe = (step: 'checked' | 'read' | 'listed') => Promise<void> | void;
275
+
276
+ async function readConfined(file: string, maxBytes: number, probe?: FileProbe): Promise<{ bytes: Buffer; modifiedAt: Date } | undefined> {
277
+ const before = await lstat(file, { bigint: true });
278
+ if (before.isSymbolicLink()) throw Object.assign(new Error('link'), { linked: true });
279
+ if (!before.isFile()) throw new Error('not a file');
280
+ if (before.nlink > 1n) throw Object.assign(new Error('hard link'), { linked: true });
281
+ if ((await realpath(file)) !== file) throw Object.assign(new Error('real path differs'), { linked: true });
282
+ if (before.size > BigInt(maxBytes)) return undefined;
283
+ await probe?.('checked');
284
+ let handle;
285
+ try {
286
+ handle = await open(file, OPEN_FLAGS);
287
+ } catch (error) {
288
+ if ((error as NodeJS.ErrnoException).code === 'ELOOP') throw Object.assign(new Error('link'), { linked: true });
289
+ throw error;
290
+ }
291
+ try {
292
+ const opened = await handle.stat({ bigint: true });
293
+ if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.nlink > 1n) throw Object.assign(new Error('changed'), { linked: true });
294
+ // One byte more than allowed tells a file that grew from one that fits.
295
+ const buffer = Buffer.alloc(maxBytes + 1);
296
+ let length = 0;
297
+ while (length < buffer.length) {
298
+ const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
299
+ if (!bytesRead) break;
300
+ length += bytesRead;
301
+ }
302
+ if (length > maxBytes) return undefined;
303
+ await probe?.('read');
304
+ const after = await lstat(file, { bigint: true });
305
+ if (after.dev !== before.dev || after.ino !== before.ino) throw Object.assign(new Error('changed'), { linked: true });
306
+ return { bytes: buffer.subarray(0, length), modifiedAt: opened.mtime };
307
+ } finally {
308
+ await handle.close();
309
+ }
310
+ }
311
+
312
+ /** Paseo's isLikelyBinary (file-explorer/service.ts at b63a325): a NUL byte, or over 30% control characters. */
313
+ function likelyBinary(buffer: Buffer): boolean {
314
+ if (!buffer.length) return false;
315
+ let suspicious = 0;
316
+ for (const byte of buffer) {
317
+ if (byte === 0) return true;
318
+ if ((byte < 32 && byte !== 9 && byte !== 10 && byte !== 13) || byte === 127) suspicious++;
319
+ }
320
+ return suspicious / buffer.length > 0.3;
321
+ }
322
+
323
+ // The BOM is kept: the content is the file's bytes, decoded.
324
+ /** PEM, OpenSSH and PuTTY private-key headers: a file holding one is refused whatever its name. */
325
+ const PRIVATE_KEY = /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----|PuTTY-User-Key-File-\d+:/;
326
+
327
+ const UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
328
+
329
+ export type ListedEntry = { name: string; path: string; kind: 'file' | 'directory'; size?: number; modifiedAt?: string };
330
+
331
+ /**
332
+ * The entries of a directory under `projectRoot` (its root without `relative`): regular files and
333
+ * directories only (links, sockets, devices are left out), never a blocked one (blockedFilePath)
334
+ * and, unless `includeIgnored`, none .gitignore'd. Directories first, then by name. Each directory
335
+ * on the way is checked (real directory, real path, same device and inode) before and after the
336
+ * read. At most WORKSPACE_FILES.maxListEntries entries; then `truncated`.
337
+ */
338
+ export async function listWorkspaceDirectory(projectRoot: string, { path: relative, includeIgnored = false, now = Date.now, probe, git }: { path?: string; includeIgnored?: boolean; now?: () => number; probe?: FileProbe; git?: GitCheckOptions } = {}): Promise<{ entries: ListedEntry[]; truncated?: true }> {
339
+ const root = await realRoot(projectRoot);
340
+ const segments = relative === undefined ? [] : relativeSegments(relative);
341
+ const shown = relative ?? '.';
342
+ const chain = await directoryChain(root, segments, shown);
343
+ const directory = chain.paths.at(-1)!;
344
+ const prefix = segments.length ? `${relative}/` : '';
345
+ const deadline = now() + LIST_LIMITS.ms;
346
+ // Regular files and directories that are not blocked, before .gitignore is asked about them.
347
+ const candidates: Array<{ name: string; child: string; kind: 'file' | 'directory' }> = [];
348
+ let scanned = 0;
349
+ let truncated = false;
350
+ try {
351
+ for await (const entry of await opendir(directory)) {
352
+ if (++scanned > LIST_LIMITS.scanned || now() > deadline) { truncated = true; break; }
353
+ const kind = entry.isFile() ? 'file' : entry.isDirectory() ? 'directory' : undefined;
354
+ if (!kind) continue;
355
+ const child = `${prefix}${entry.name}`;
356
+ if (entry.name.includes('\\') || blockedFilePath(child)) continue;
357
+ candidates.push({ name: entry.name, child, kind });
358
+ }
359
+ } catch {
360
+ throw notFound(shown);
361
+ }
362
+ // One Git process for the directory and every candidate: Git also says a path inside an
363
+ // ignored directory is ignored, and a `!` rule can bring one back.
364
+ if (!includeIgnored) {
365
+ const ignored = await ignoredOf(root, [...(segments.length ? [relative!] : []), ...candidates.map(entry => entry.child)], git);
366
+ if (segments.length && ignored(relative!)) throw new FileAccessError(`${relative} is ignored by .gitignore; ask with includeIgnored to see it`, ERROR.forbidden, 'ignored');
367
+ for (let index = candidates.length - 1; index >= 0; index--) if (ignored(candidates[index]!.child)) candidates.splice(index, 1);
368
+ }
369
+ const entries: ListedEntry[] = [];
370
+ for (const { name, child, kind } of candidates) {
371
+ if (entries.length >= WORKSPACE_FILES.maxListEntries) { truncated = true; break; }
372
+ let info;
373
+ try {
374
+ info = await lstat(path.join(directory, name));
375
+ } catch {
376
+ continue;
377
+ }
378
+ // Replaced by something else since it was listed: left out.
379
+ if (kind === 'file' ? !info.isFile() : !info.isDirectory()) continue;
380
+ entries.push({ name, path: child, kind, ...(kind === 'file' ? { size: info.size } : {}), modifiedAt: info.mtime.toISOString() });
381
+ }
382
+ await probe?.('listed');
383
+ await sameChain(chain, shown);
384
+ entries.sort((a, b) => (a.kind === b.kind ? 0 : a.kind === 'directory' ? -1 : 1) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
385
+ return { entries, ...(truncated ? { truncated: true as const } : {}) };
386
+ }
387
+
388
+ /**
389
+ * The content of a UTF-8 text file under `projectRoot`, read-only: refused when it is blocked
390
+ * (blockedFilePath), .gitignore'd (unless `includeIgnored`), missing or not a regular file,
391
+ * reached through a link (any directory on the way or the file), has more than one name (a hard
392
+ * link may share a file from anywhere), changes while it is read, is over
393
+ * WORKSPACE_FILES.maxReadBytes, or is not UTF-8 text.
394
+ */
395
+ export async function readWorkspaceFile(projectRoot: string, { path: relative, includeIgnored = false, probe, git }: { path: string; includeIgnored?: boolean; probe?: FileProbe; git?: GitCheckOptions }): Promise<{ path: string; content: string; size: number; modifiedAt: string }> {
396
+ const root = await realRoot(projectRoot);
397
+ const segments = relativeSegments(relative);
398
+ const chain = await directoryChain(root, segments.slice(0, -1), relative);
399
+ if (!includeIgnored && (await ignoredOf(root, [relative], git))(relative)) throw new FileAccessError(`${relative} is ignored by .gitignore; ask with includeIgnored to read it`, ERROR.forbidden, 'ignored');
400
+ const file = path.join(root, ...segments);
401
+ let read: { bytes: Buffer; modifiedAt: Date } | undefined;
402
+ try {
403
+ read = await readConfined(file, WORKSPACE_FILES.maxReadBytes, probe);
404
+ } catch (error) {
405
+ if ((error as { linked?: boolean }).linked) throw linked(relative);
406
+ throw notFound(relative);
407
+ }
408
+ if (read === undefined) throw new FileAccessError(`${relative} is larger than ${WORKSPACE_FILES.maxReadBytes} bytes`, ERROR.failed, 'too_large');
409
+ await sameChain(chain, relative);
410
+ let content: string;
411
+ try {
412
+ if (likelyBinary(read.bytes)) throw new Error('binary');
413
+ content = UTF8.decode(read.bytes);
414
+ } catch {
415
+ throw new FileAccessError(`${relative} is not a UTF-8 text file`, ERROR.failed, 'binary');
416
+ }
417
+ // A private key under any name (id_work, a service account's JSON) is refused as a blocked path.
418
+ if (PRIVATE_KEY.test(content)) throw new FileAccessError(`${relative} holds a private key; such files are never readable remotely`, ERROR.forbidden, 'blocked_path');
419
+ return { path: relative, content, size: read.bytes.length, modifiedAt: read.modifiedAt.toISOString() };
420
+ }
@@ -0,0 +1,260 @@
1
+ import { spawn } from 'node:child_process';
2
+ import { accessSync, constants, lstatSync, realpathSync, statSync, type BigIntStats } from 'node:fs';
3
+ import path from 'node:path';
4
+
5
+ /**
6
+ * Which paths of a workspace `.gitignore` hides, for workspace.files.list and workspace.files.read
7
+ * (docs/protocol/alp-json-rpc-v1.md §12.4), as Git itself says: `git check-ignore`, so its rules
8
+ * are Git's exactly (every `.gitignore` on the way, `.git/info/exclude`, `core.excludesFile`).
9
+ *
10
+ * The workspace is not trusted, so Git runs boxed in:
11
+ * - the Git found on the absolute entries of PATH, by its real path: never a `git` the workspace
12
+ * holds (a relative or empty PATH entry, or Windows searching the working directory first, would
13
+ * run one), whatever the spelling of the entry or a link on the way (see resolveGit);
14
+ * - spawned with an argument list, never a shell, in the workspace's real path;
15
+ * - `--no-index`: the index is not read (no fsmonitor or index extension runs; a tracked file a
16
+ * rule matches is hidden too), and `core.fsmonitor` is turned off besides;
17
+ * - an environment without any GIT_* variable of alpd's own, no prompts, no optional locks;
18
+ * - paths on stdin separated by NUL (`-z`), each as `./<path>` so that Git reads none as pathspec
19
+ * magic (`:(glob)…`, `:!…`) and none is ever an argument;
20
+ * - at most MAX_CONCURRENT at once in alpd, a bounded queue, a hard timeout that kills its whole
21
+ * process group, and a cap on what it may print.
22
+ * A timeout, a crash, a refusal, a full queue or an answer that is not plainly a list of the paths
23
+ * asked fails closed: the caller treats the paths as ignored. Git missing, or a workspace in no
24
+ * repository (no `.git` in it or above it): no rules apply, and only the block list hides anything.
25
+ */
26
+
27
+ export const GIT_CHECK = Object.freeze({
28
+ /** Git gets this long per request, waiting for a turn included, then is killed. */
29
+ timeoutMs: 2_000,
30
+ /** Git processes alpd runs at once, and requests that may wait for one. */
31
+ maxConcurrent: 4,
32
+ maxQueued: 64,
33
+ maxErrorBytes: 64 * 1024,
34
+ });
35
+
36
+ /** Git's answer could not be had: whether the paths are ignored is not known, so they count as ignored. */
37
+ export class IgnoreUnknown extends Error {
38
+ constructor(why: string) { super(`git check-ignore failed: ${why}`); }
39
+ }
40
+
41
+ export type GitCheckOptions = { binary?: string; timeoutMs?: number };
42
+
43
+ /** alpd's environment without Git's variables (GIT_DIR, GIT_WORK_TREE, GIT_CONFIG_*…), which would point Git elsewhere. */
44
+ function gitEnvironment(): NodeJS.ProcessEnv {
45
+ const env: NodeJS.ProcessEnv = {};
46
+ for (const [key, value] of Object.entries(process.env)) if (!/^GIT_/i.test(key)) env[key] = value;
47
+ return { ...env, GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0', LC_ALL: 'C' };
48
+ }
49
+
50
+ const executable = (file: string) => {
51
+ try {
52
+ if (!statSync(file).isFile()) return false;
53
+ if (process.platform !== 'win32') accessSync(file, constants.X_OK);
54
+ return true;
55
+ } catch {
56
+ return false;
57
+ }
58
+ };
59
+
60
+ /** The file system's identity of a directory: one per directory, whatever path names it. */
61
+ type Identity = Pick<BigIntStats, 'dev' | 'ino'>;
62
+ const identity = (file: string): Identity => { const { dev, ino } = statSync(file, { bigint: true }); return { dev, ino }; };
63
+ // macOS and Windows file systems compare names without case, mostly: a name compare there folds it.
64
+ const foldCase = process.platform === 'darwin' || process.platform === 'win32';
65
+ const comparable = (file: string) => (foldCase ? file.toLowerCase() : file);
66
+
67
+ /**
68
+ * Whether `file` is `root` or inside it, however either is spelled: a case-insensitive file
69
+ * system's other case, a Windows drive letter's case or 8.3 short name, a link, a bind mount. Both
70
+ * are made real paths by the system (realpath(3), which spells names as they are stored), and then
71
+ * each directory from `file` up to the file system's root is compared with `root` by device and
72
+ * inode, and by its name (case-folded where names are, for a file system without inode numbers).
73
+ * Anything that cannot be resolved or examined counts as inside: the caller skips it.
74
+ */
75
+ function insideRoot(file: string, root: { path: string; id: Identity }): boolean {
76
+ let directory;
77
+ try { directory = realpathSync.native(file); } catch { return true; }
78
+ const rootName = comparable(root.path.endsWith(path.sep) && root.path.length > 1 ? root.path.slice(0, -1) : root.path);
79
+ for (;;) {
80
+ const name = comparable(directory);
81
+ if (name === rootName || name.startsWith(rootName.endsWith(path.sep) ? rootName : `${rootName}${path.sep}`)) return true;
82
+ let id;
83
+ try { id = identity(directory); } catch { return true; }
84
+ if (root.id.ino !== 0n && id.dev === root.id.dev && id.ino === root.id.ino) return true;
85
+ const parent = path.dirname(directory);
86
+ if (parent === directory) return false;
87
+ directory = parent;
88
+ }
89
+ }
90
+
91
+ /** The workspace as insideRoot compares it, or undefined if it cannot be examined. */
92
+ function rootOf(root: string): { path: string; id: Identity } | undefined {
93
+ try {
94
+ const real = realpathSync.native(root);
95
+ return { path: real, id: identity(real) };
96
+ } catch {
97
+ return undefined;
98
+ }
99
+ }
100
+
101
+ /**
102
+ * The absolute path of `name` on the absolute entries of PATH (Windows: with .exe or .com), or
103
+ * undefined. An absolute `name` (tests) is taken when it is an executable file. Relative and empty
104
+ * PATH entries are skipped: they name the working directory, which is the workspace.
105
+ *
106
+ * With `root`, nothing in the workspace is ever the answer (alpd started by npm or npx has
107
+ * `<project>/node_modules/.bin` on PATH): a PATH entry inside `root` is skipped, and so is a
108
+ * binary that is, or links to, a file inside it; both by insideRoot, which no other spelling of
109
+ * the path fools. The answer is then the binary's real path, so a link swapped later changes
110
+ * nothing. A workspace that cannot be examined finds no Git at all (IgnoreUnknown).
111
+ */
112
+ export function resolveGit(name = 'git', searchPath = process.env.PATH ?? process.env.Path ?? '', root?: string): string | undefined {
113
+ const box = root === undefined ? undefined : rootOf(root);
114
+ if (root !== undefined && !box) throw new IgnoreUnknown('the workspace cannot be examined');
115
+ /** `file` as the answer, or undefined: not executable, or in the workspace. */
116
+ const accept = (file: string) => {
117
+ if (!executable(file)) return undefined;
118
+ if (!box) return file;
119
+ let real;
120
+ try { real = realpathSync.native(file); } catch { return undefined; }
121
+ return insideRoot(path.dirname(real), box) || !executable(real) ? undefined : real;
122
+ };
123
+ if (path.isAbsolute(name)) return accept(name);
124
+ if (name.includes('/') || name.includes('\\')) return undefined;
125
+ const names = process.platform === 'win32' ? [`${name}.exe`, `${name}.com`] : [name];
126
+ for (const directory of searchPath.split(path.delimiter)) {
127
+ if (!directory || !path.isAbsolute(directory)) continue;
128
+ if (box && insideRoot(directory, box)) continue;
129
+ for (const candidate of names) {
130
+ const file = accept(path.join(directory, candidate));
131
+ if (file) return file;
132
+ }
133
+ }
134
+ return undefined;
135
+ }
136
+
137
+ /** Whether `root` or a directory above it holds a `.git` entry: Git saying "not a git repository" there is a broken repository, not none. */
138
+ function hasGitEntry(root: string): boolean {
139
+ for (let directory = root; ; directory = path.dirname(directory)) {
140
+ try {
141
+ lstatSync(path.join(directory, '.git'));
142
+ return true;
143
+ } catch {
144
+ // none here
145
+ }
146
+ if (path.dirname(directory) === directory) return false;
147
+ }
148
+ }
149
+
150
+ // The slots: at most maxConcurrent Git processes; others wait in a bounded queue.
151
+ let running = 0;
152
+ const waiting: Array<() => void> = [];
153
+ function acquire(deadline: number): Promise<() => void> {
154
+ const release = () => { running--; waiting.shift()?.(); };
155
+ if (running < GIT_CHECK.maxConcurrent) { running++; return Promise.resolve(release); }
156
+ if (waiting.length >= GIT_CHECK.maxQueued) return Promise.reject(new IgnoreUnknown('too many waiting'));
157
+ return new Promise((resolve, reject) => {
158
+ const turn = () => { clearTimeout(timer); running++; resolve(release); };
159
+ const timer = setTimeout(() => {
160
+ const index = waiting.indexOf(turn);
161
+ if (index >= 0) waiting.splice(index, 1);
162
+ reject(new IgnoreUnknown('timed out waiting for a turn'));
163
+ }, Math.max(0, deadline - Date.now()));
164
+ waiting.push(turn);
165
+ });
166
+ }
167
+
168
+ /** Git processes running now, for tests. */
169
+ export const gitChecksRunning = () => running;
170
+
171
+ /**
172
+ * The paths among `paths` (relative to `root`, '/'-separated, already checked) that Git ignores;
173
+ * null when no rules apply (Git is not installed, or `root` is in no repository). Throws
174
+ * IgnoreUnknown on anything else.
175
+ */
176
+ export async function gitIgnored(root: string, paths: readonly string[], { binary = 'git', timeoutMs = GIT_CHECK.timeoutMs }: GitCheckOptions = {}): Promise<Set<string> | null> {
177
+ if (!paths.length) return new Set();
178
+ const git = resolveGit(binary, undefined, root);
179
+ if (!git) return null;
180
+ const deadline = Date.now() + timeoutMs;
181
+ const release = await acquire(deadline);
182
+ try {
183
+ return await check(git, root, paths, deadline, timeoutMs);
184
+ } finally {
185
+ release();
186
+ }
187
+ }
188
+
189
+ function check(git: string, root: string, paths: readonly string[], deadline: number, timeoutMs: number): Promise<Set<string> | null> {
190
+ const input = `${paths.map(entry => `./${entry}`).join('\0')}\0`;
191
+ // Git echoes only what it was asked, so what it prints never exceeds what it was sent.
192
+ const maxOutputBytes = Buffer.byteLength(input) + 1024;
193
+ return new Promise((resolve, reject) => {
194
+ let settled = false;
195
+ let timer: ReturnType<typeof setTimeout> | undefined;
196
+ let child: ReturnType<typeof spawn>;
197
+ // POSIX: its own process group, so a timeout kills whatever it started too.
198
+ const group = process.platform !== 'win32';
199
+ const kill = () => {
200
+ try {
201
+ if (group && child.pid) process.kill(-child.pid, 'SIGKILL');
202
+ else child.kill('SIGKILL');
203
+ } catch {
204
+ // already gone
205
+ }
206
+ };
207
+ const finish = (outcome: () => void) => {
208
+ if (settled) return;
209
+ settled = true;
210
+ if (timer) clearTimeout(timer);
211
+ outcome();
212
+ };
213
+ try {
214
+ child = spawn(git, ['-c', 'core.fsmonitor=false', 'check-ignore', '--no-index', '--stdin', '-z'], {
215
+ cwd: root, env: gitEnvironment(), shell: false, windowsHide: true, detached: group, stdio: ['pipe', 'pipe', 'pipe'],
216
+ });
217
+ } catch (error) {
218
+ reject(new IgnoreUnknown(String((error as Error).message)));
219
+ return;
220
+ }
221
+ timer = setTimeout(() => finish(() => { kill(); reject(new IgnoreUnknown('timed out')); }), Math.max(1, Math.min(timeoutMs, deadline - Date.now())));
222
+ const out: Buffer[] = [];
223
+ let outBytes = 0;
224
+ let err = '';
225
+ child.stdout!.on('data', (chunk: Buffer) => {
226
+ outBytes += chunk.length;
227
+ if (outBytes > maxOutputBytes) finish(() => { kill(); reject(new IgnoreUnknown('more output than input')); });
228
+ else out.push(chunk);
229
+ });
230
+ child.stderr!.on('data', (chunk: Buffer) => { if (err.length < GIT_CHECK.maxErrorBytes) err += chunk.toString('utf8'); });
231
+ child.on('error', error => finish(() => {
232
+ // Removed since it was found: no rules to apply.
233
+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') resolve(null);
234
+ else reject(new IgnoreUnknown(error.message));
235
+ }));
236
+ child.on('close', code => finish(() => {
237
+ // No repository: no rules. A `.git` that Git cannot use (a worktree whose repository moved)
238
+ // is not "no repository": fail closed.
239
+ if (code === 128 && /not a git repository/i.test(err)) {
240
+ if (hasGitEntry(root)) reject(new IgnoreUnknown('a .git Git cannot use'));
241
+ else resolve(null);
242
+ return;
243
+ }
244
+ // 0: some paths are ignored; 1: none is.
245
+ if (code !== 0 && code !== 1) { reject(new IgnoreUnknown(`exit ${code}`)); return; }
246
+ const asked = new Set(paths);
247
+ const ignored = new Set<string>();
248
+ for (const entry of Buffer.concat(out).toString('utf8').split('\0')) {
249
+ if (!entry) continue;
250
+ const relative = entry.startsWith('./') ? entry.slice(2) : undefined;
251
+ if (relative === undefined || !asked.has(relative)) { reject(new IgnoreUnknown('an answer for a path not asked')); return; }
252
+ ignored.add(relative);
253
+ }
254
+ resolve(ignored);
255
+ }));
256
+ // A Git that exits before reading everything closes the pipe: its exit decides.
257
+ child.stdin!.on('error', () => {});
258
+ child.stdin!.end(input);
259
+ });
260
+ }