@anhlp/alp-daemon 0.0.0-stage → 0.0.1-beta.10

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.
Files changed (115) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +7 -0
  3. package/README.md +14 -2
  4. package/dist/THIRD-PARTY-NOTICES.txt +456 -0
  5. package/dist/alp-templates.d.ts +5 -0
  6. package/dist/alpd.js +64050 -0
  7. package/dist/attachments.d.ts +187 -0
  8. package/dist/attachments.js +856 -0
  9. package/dist/build-manifest.json +150 -0
  10. package/dist/conversation.d.ts +119 -0
  11. package/dist/conversation.js +688 -0
  12. package/dist/disk.d.ts +67 -0
  13. package/dist/disk.js +152 -0
  14. package/dist/files.d.ts +262 -0
  15. package/dist/files.js +674 -0
  16. package/dist/git.d.ts +98 -0
  17. package/dist/git.js +1246 -0
  18. package/dist/gitignore.d.ts +62 -0
  19. package/dist/gitignore.js +254 -0
  20. package/dist/history.d.ts +24 -0
  21. package/dist/history.js +149 -0
  22. package/dist/index.d.ts +11 -0
  23. package/dist/index.js +28 -0
  24. package/dist/lifecycle.d.ts +101 -0
  25. package/dist/lifecycle.js +239 -0
  26. package/dist/lock.d.ts +21 -0
  27. package/dist/lock.js +42 -0
  28. package/dist/main.d.ts +1 -0
  29. package/dist/main.js +363 -0
  30. package/dist/model-catalog.d.ts +2 -0
  31. package/dist/model-catalog.js +44 -0
  32. package/dist/native-entry.d.ts +2 -0
  33. package/dist/native-entry.js +3 -0
  34. package/dist/native-register.d.ts +1 -0
  35. package/dist/native-register.js +13 -0
  36. package/dist/native-terminal.d.ts +45 -0
  37. package/dist/native-terminal.js +201 -0
  38. package/dist/operations.d.ts +40 -0
  39. package/dist/operations.js +313 -0
  40. package/dist/registry.d.ts +89 -0
  41. package/dist/registry.js +343 -0
  42. package/dist/rpc-error.d.ts +6 -0
  43. package/dist/rpc-error.js +11 -0
  44. package/dist/scheduler.d.ts +96 -0
  45. package/dist/scheduler.js +298 -0
  46. package/dist/schedules.d.ts +70 -0
  47. package/dist/schedules.js +246 -0
  48. package/dist/server.d.ts +60 -0
  49. package/dist/server.js +1958 -0
  50. package/dist/store.d.ts +178 -0
  51. package/dist/store.js +386 -0
  52. package/dist/terminal-native/README.md +201 -0
  53. package/dist/terminal-native/prebuilt/darwin-arm64/manifest.json +11 -0
  54. package/dist/terminal-native/prebuilt/darwin-arm64/terminal-owner +0 -0
  55. package/dist/terminal-native/prebuilt/darwin-x64/manifest.json +11 -0
  56. package/dist/terminal-native/prebuilt/darwin-x64/terminal-owner +0 -0
  57. package/dist/terminal-native/prebuilt/linux-arm64-glibc/manifest.json +10 -0
  58. package/dist/terminal-native/prebuilt/linux-arm64-glibc/terminal-owner +0 -0
  59. package/dist/terminal-native/prebuilt/linux-arm64-musl/manifest.json +10 -0
  60. package/dist/terminal-native/prebuilt/linux-arm64-musl/terminal-owner +0 -0
  61. package/dist/terminal-native/prebuilt/linux-x64-glibc/manifest.json +10 -0
  62. package/dist/terminal-native/prebuilt/linux-x64-glibc/terminal-owner +0 -0
  63. package/dist/terminal-native/prebuilt/linux-x64-musl/manifest.json +10 -0
  64. package/dist/terminal-native/prebuilt/linux-x64-musl/terminal-owner +0 -0
  65. package/dist/terminal-native/terminal-owner.c +389 -0
  66. package/dist/terminal-screen.d.ts +24 -0
  67. package/dist/terminal-screen.js +99 -0
  68. package/dist/terminals.d.ts +203 -0
  69. package/dist/terminals.js +570 -0
  70. package/dist/windows-terminal.d.ts +32 -0
  71. package/dist/windows-terminal.js +79 -0
  72. package/dist/worktrees.d.ts +65 -0
  73. package/dist/worktrees.js +318 -0
  74. package/native/README.md +201 -0
  75. package/native/prebuilt/darwin-arm64/manifest.json +11 -0
  76. package/native/prebuilt/darwin-arm64/terminal-owner +0 -0
  77. package/native/prebuilt/darwin-x64/manifest.json +11 -0
  78. package/native/prebuilt/darwin-x64/terminal-owner +0 -0
  79. package/native/prebuilt/linux-arm64-glibc/manifest.json +10 -0
  80. package/native/prebuilt/linux-arm64-glibc/terminal-owner +0 -0
  81. package/native/prebuilt/linux-arm64-musl/manifest.json +10 -0
  82. package/native/prebuilt/linux-arm64-musl/terminal-owner +0 -0
  83. package/native/prebuilt/linux-x64-glibc/manifest.json +10 -0
  84. package/native/prebuilt/linux-x64-glibc/terminal-owner +0 -0
  85. package/native/prebuilt/linux-x64-musl/manifest.json +10 -0
  86. package/native/prebuilt/linux-x64-musl/terminal-owner +0 -0
  87. package/native/terminal-owner.c +389 -0
  88. package/package.json +163 -4
  89. package/src/alp-templates.d.ts +5 -0
  90. package/src/attachments.ts +908 -0
  91. package/src/conversation.ts +857 -0
  92. package/src/disk.ts +175 -0
  93. package/src/files.ts +884 -0
  94. package/src/git.ts +1220 -0
  95. package/src/gitignore.ts +277 -0
  96. package/src/history.ts +118 -0
  97. package/src/index.ts +12 -0
  98. package/src/lifecycle.ts +283 -0
  99. package/src/lock.ts +53 -0
  100. package/src/main.ts +381 -0
  101. package/src/model-catalog.ts +36 -0
  102. package/src/native-entry.ts +5 -0
  103. package/src/native-register.ts +21 -0
  104. package/src/native-terminal.ts +127 -0
  105. package/src/operations.ts +329 -0
  106. package/src/registry.ts +238 -0
  107. package/src/rpc-error.ts +4 -0
  108. package/src/scheduler.ts +438 -0
  109. package/src/schedules.ts +297 -0
  110. package/src/server.ts +2238 -0
  111. package/src/store.ts +449 -0
  112. package/src/terminal-screen.ts +74 -0
  113. package/src/terminals.ts +653 -0
  114. package/src/windows-terminal.ts +74 -0
  115. package/src/worktrees.ts +382 -0
package/src/files.ts ADDED
@@ -0,0 +1,884 @@
1
+ import { createHash, randomBytes } from 'node:crypto';
2
+ import { constants, type BigIntStats } from 'node:fs';
3
+ import { lstat, open, opendir, realpath, stat, type FileHandle } from 'node:fs/promises';
4
+ import os from 'node:os';
5
+ import path from 'node:path';
6
+ import { ERROR, RPC_ERROR, WORKSPACE_FILES, blockedFilePath } from '@anhlp/alp-protocol';
7
+ import { gitIgnored, IgnoreUnknown, GIT_CHECK, type GitCheckOptions } from './gitignore.js';
8
+
9
+ // For tests: which git alpd would run, and how many run now.
10
+ export { gitChecksRunning, resolveGit, GIT_CHECK } from './gitignore.js';
11
+
12
+ /**
13
+ * `workspace.files.search` (docs/protocol/alp-json-rpc-v1.md §12.3): the files of a workspace whose
14
+ * path matches a query, as Paseo's command center finds them (server/utils/directory-suggestions.ts
15
+ * at b63a325, with its workspace settings: relative paths, hidden and heavy directories skipped).
16
+ *
17
+ * Read-only and confined to the workspace: the walk starts at the root's real path and never
18
+ * follows a symbolic link (a link is neither listed nor entered). Each directory is checked before
19
+ * and after it is read: a real directory (not a link), at the real path it was reached by, the same
20
+ * one (device and inode) both times; otherwise what was read is dropped. Only names are read, never
21
+ * contents. A link swapped in and back out between those checks, by a writer racing inside the
22
+ * workspace, can still expose names of the directory it pointed to (Node has no openat/O_NOFOLLOW
23
+ * walk); docs/protocol/alp-json-rpc-v1.md §12.3. The walk stops at {@link LIMITS}, checked per
24
+ * entry; the answer then says `truncated`.
25
+ */
26
+
27
+ export const LIMITS = Object.freeze({
28
+ /** Directory levels below the root that are entered (Paseo's DEFAULT_MAX_DEPTH). */
29
+ depth: 12,
30
+ /** Directory entries looked at (Paseo's DEFAULT_MAX_ENTRIES_SCANNED). */
31
+ scanned: 20_000,
32
+ /** Wall time of one search. */
33
+ ms: 3_000,
34
+ /** Results by default and at most (Paseo's DEFAULT_LIMIT, MAX_LIMIT). */
35
+ defaultLimit: 30,
36
+ maxLimit: 100,
37
+ });
38
+
39
+ /** Hidden directories that are still searched (Paseo's WORKSPACE_SEARCH_HIDDEN_DIRECTORIES, with ALP's own). */
40
+ const HIDDEN_DIRECTORIES = new Set(['.agents', '.alp', '.claude', '.codex', '.github', '.opencode', '.paseo', '.vscode']);
41
+ /** Directories never searched (Paseo's IGNORED_DIRECTORY_NAMES). */
42
+ const IGNORED_DIRECTORIES = new Set(['node_modules', 'venv', 'env', 'virtualenv', 'dist', 'build', 'target', 'out', 'coverage', 'vendor', '__pycache__', '.git']);
43
+
44
+ const NONE = Number.MAX_SAFE_INTEGER;
45
+
46
+ type Rank = { path: string; tier: number; segment: number; offset: number; fuzzy: number; depth: number };
47
+
48
+ /** The directory at `directory` as reached by name: a real directory there, not a link, or null. */
49
+ async function identity(directory: string): Promise<string | null> {
50
+ const info = await lstat(directory, { bigint: true });
51
+ if (!info.isDirectory() || (await realpath(directory)) !== directory) return null;
52
+ return `${info.dev}:${info.ino}`;
53
+ }
54
+
55
+ /** Paseo's scoreFuzzySubsequence: the query's letters in order; the first offset plus the gaps, or null. */
56
+ function fuzzy(query: string, candidate: string): number | null {
57
+ let at = 0;
58
+ let first = -1;
59
+ let previous = -1;
60
+ let gaps = 0;
61
+ for (let index = 0; index < candidate.length && at < query.length; index++) {
62
+ if (candidate[index] !== query[at]) continue;
63
+ if (first < 0) first = index;
64
+ if (previous >= 0) gaps += index - previous - 1;
65
+ previous = index;
66
+ at++;
67
+ }
68
+ return at === query.length && first >= 0 ? first + gaps : null;
69
+ }
70
+
71
+ /** Paseo's rankTextMatch (a word) and rankPathMatch (a query with a slash), simplified; null: no match. */
72
+ function rank(relative: string, query: string): Rank | null {
73
+ const lower = relative.toLowerCase();
74
+ const segments = lower.split('/');
75
+ const depth = segments.length;
76
+ if (!query) return { path: relative, tier: 3, segment: NONE, offset: NONE, fuzzy: NONE, depth };
77
+ const offset = lower.indexOf(query);
78
+ if (query.includes('/')) {
79
+ if (offset >= 0) return { path: relative, tier: lower.startsWith(query) ? 1 : 3, segment: NONE, offset, fuzzy: NONE, depth };
80
+ const spread = fuzzy(query, lower);
81
+ return spread === null ? null : { path: relative, tier: 4, segment: NONE, offset: NONE, fuzzy: spread, depth };
82
+ }
83
+ const last = fuzzy(query, segments.at(-1) ?? '');
84
+ const tiers: Array<(segment: string) => boolean> = [segment => segment === query, segment => segment.startsWith(query), segment => segment.includes(query)];
85
+ for (const [tier, test] of tiers.entries()) {
86
+ const segment = segments.findIndex(test);
87
+ if (segment >= 0) return { path: relative, tier, segment, offset: offset >= 0 ? offset : NONE, fuzzy: last ?? NONE, depth };
88
+ }
89
+ if (last !== null) return { path: relative, tier: 4, segment: NONE, offset: NONE, fuzzy: last, depth };
90
+ return null;
91
+ }
92
+
93
+ const compare = (a: Rank, b: Rank) =>
94
+ 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);
95
+
96
+ export class FilesError extends Error {}
97
+
98
+ type Kind = 'file' | 'directory';
99
+ /** An entry a walk found: '/'-separated from the root, at the breadth-first level of its directory; a link is never entered. */
100
+ type Walked = { path: string; name: string; kind: Kind; depth: number; link?: true };
101
+ type WalkOptions = {
102
+ depth: number; scanned: number; ms: number; now: () => number; git?: GitCheckOptions;
103
+ /** Before Git is asked: whether the entry is kept (a directory: also entered while `depth` allows). Blocked paths never are. */
104
+ keep: (child: string, name: string, kind: Kind, depth: number) => boolean;
105
+ /** After Git answered; `repository` is false when no .gitignore rules apply (no Git, or no repository). */
106
+ admit?: (entry: Walked, repository: boolean) => boolean;
107
+ /** Links whose real path is inside the root (internalTarget) are kept as their target's kind, never entered. */
108
+ links?: boolean;
109
+ };
110
+
111
+ /**
112
+ * The entries under the real root `root`, as workspace.files.search walks (above): breadth first,
113
+ * no link entered, each directory checked before and after it is read, one bounded Git request per
114
+ * level before its directories are entered. `truncated` when a bound stopped it. Throws
115
+ * IgnoreUnknown when Git cannot say what is ignored.
116
+ */
117
+ async function walk(root: string, options: WalkOptions): Promise<{ entries: Walked[]; truncated: boolean }> {
118
+ const { now, git } = options;
119
+ const deadline = now() + options.ms;
120
+ const realDeadline = Date.now() + options.ms;
121
+ const found: Walked[] = [];
122
+ let scanned = 0;
123
+ let truncated = false;
124
+ // Known after the first level Git was asked about; no rules at the root means none below it.
125
+ let repository: boolean | undefined;
126
+ let level: string[] = [''];
127
+ for (let depth = 0; level.length && !truncated; depth++) {
128
+ const levelEntries: Walked[] = [];
129
+ for (const relative of level) {
130
+ if (scanned >= options.scanned || now() > deadline) { truncated = true; break; }
131
+ // Reached by names alone from the real root, so it is inside it unless a link took its place.
132
+ const directory = relative ? path.join(root, ...relative.split('/')) : root;
133
+ const entries: Walked[] = [];
134
+ try {
135
+ const before = await identity(directory);
136
+ if (!before) continue;
137
+ // Iterated, not read whole: the limits hold inside one large directory too.
138
+ for await (const entry of await opendir(directory)) {
139
+ if (++scanned > options.scanned || now() > deadline) { truncated = true; break; }
140
+ const name = entry.name;
141
+ const child = relative ? `${relative}/${name}` : name;
142
+ if (name.includes('\\') || blockedFilePath(child)) continue;
143
+ // Sockets, devices and (unless asked) links: neither listed nor entered.
144
+ const kind: Kind | undefined = entry.isFile() ? 'file' : entry.isDirectory() ? 'directory' : options.links && entry.isSymbolicLink() ? (await internalTarget(root, path.join(directory, name)))?.kind : undefined;
145
+ if (!kind || !options.keep(child, name, kind, depth)) continue;
146
+ entries.push({ path: child, name, kind, depth, ...(entry.isSymbolicLink() ? { link: true as const } : {}) });
147
+ }
148
+ if ((await identity(directory)) !== before) continue;
149
+ } catch {
150
+ continue;
151
+ }
152
+ levelEntries.push(...entries);
153
+ if (truncated) break;
154
+ }
155
+ // One bounded Git request per breadth-first level, before entering its directories or
156
+ // ranking its files. Git evaluates nested rules and ignored ancestors itself.
157
+ const remaining = Math.min(deadline - now(), realDeadline - Date.now());
158
+ if (remaining <= 0) { truncated = true; break; }
159
+ let ignored: Set<string> | null = null;
160
+ if (repository !== false) {
161
+ const asked = levelEntries.map(entry => entry.path);
162
+ ignored = await gitIgnored(root, asked, { ...git, timeoutMs: Math.min(git?.timeoutMs ?? GIT_CHECK.timeoutMs, remaining) });
163
+ if (asked.length) repository = ignored !== null;
164
+ }
165
+ const admitted = levelEntries.filter(entry => !ignored?.has(entry.path) && (options.admit?.(entry, repository === true) ?? true));
166
+ found.push(...admitted);
167
+ level = admitted.filter(entry => entry.kind === 'directory' && !entry.link && depth < options.depth).map(entry => entry.path);
168
+ }
169
+ return { entries: found, truncated };
170
+ }
171
+
172
+ /**
173
+ * The files under `projectRoot` matching `query`, best first. `projectRoot` must be an absolute path
174
+ * of a directory; anything else throws FilesError.
175
+ */
176
+ export async function searchWorkspaceFiles(projectRoot: string, { query = '', limit = LIMITS.defaultLimit, now = Date.now, git }: { query?: string; limit?: number; now?: () => number; git?: GitCheckOptions } = {}): Promise<{ files: Array<{ path: string }>; truncated?: true }> {
177
+ const root = await realRoot(projectRoot);
178
+ const wanted = query.trim().replace(/\\/g, '/').replace(/^\.?\/+/, '').toLowerCase();
179
+ const count = Math.max(1, Math.min(LIMITS.maxLimit, Math.trunc(limit)));
180
+ let walked;
181
+ try {
182
+ walked = await walk(root, {
183
+ depth: LIMITS.depth, scanned: LIMITS.scanned, ms: LIMITS.ms, now, git,
184
+ keep: (child, name, kind, depth) => kind === 'file'
185
+ ? !name.startsWith('.') && rank(child, wanted) !== null
186
+ : !IGNORED_DIRECTORIES.has(name) && (!name.startsWith('.') || HIDDEN_DIRECTORIES.has(name)) && depth < LIMITS.depth,
187
+ });
188
+ } catch (error) {
189
+ if (!(error instanceof IgnoreUnknown)) throw error;
190
+ // No partial result may reveal paths whose ignore status could not be established.
191
+ return { files: [], truncated: true };
192
+ }
193
+ const found = walked.entries.filter(entry => entry.kind === 'file').map(entry => rank(entry.path, wanted)!);
194
+ found.sort(compare);
195
+ return { files: found.slice(0, count).map(entry => ({ path: entry.path })), ...(walked.truncated ? { truncated: true as const } : {}) };
196
+ }
197
+
198
+ // ---- workspace.files.find (docs/protocol/alp-json-rpc-v1.md §12.11) ----
199
+
200
+ /**
201
+ * Bounds of one workspace.files.find walk, deeper and larger than search's: as complete as
202
+ * `git ls-files` is for the Paseo bridge, which ranks the whole set itself. A snapshot of the
203
+ * names it found is kept `ttlMs` after its last page, at most `snapshots` of them in alpd.
204
+ */
205
+ export const FIND_LIMITS = Object.freeze({ depth: 64, scanned: 100_000, ms: 10_000, ttlMs: 60_000, snapshots: 16 });
206
+ /** Outside a repository, what the Paseo bridge's own walks skipped: big, generated, or (on macOS) behind a consent prompt. */
207
+ const SKIPPED_FOLDERS = new Set(['node_modules', 'Library', '.git', 'dist', 'build', '.cache', 'target', '.venv', 'venv', '__pycache__']);
208
+
209
+ export type FoundEntry = { path: string; kind: Kind };
210
+ export type FindOptions = { query?: string; kinds?: readonly Kind[]; matchMode?: 'subsequence' | 'suffix'; now?: () => number; git?: GitCheckOptions };
211
+
212
+ /** Whether `candidate` holds the characters of `query` in order (the Paseo bridge's last ranking tier). */
213
+ export function inOrder(query: string, candidate: string): boolean {
214
+ let at = 0;
215
+ for (const char of candidate) if (char === query[at]) at += 1;
216
+ return at >= query.length;
217
+ }
218
+
219
+ /**
220
+ * Every file and directory under `projectRoot` whose path, case-insensitively, holds `query`'s
221
+ * characters in order (`subsequence`, every name the Paseo bridge's ranking can match) or is it or
222
+ * ends with `/query` (`suffix`); every name for an empty query. In path order (code units).
223
+ *
224
+ * As `git ls-files --cached --others --exclude-standard` lists a repository: dot names included,
225
+ * .gitignore'd ones left out (Git's answer, failing closed as search does), and links whose real
226
+ * path is inside the root listed as their target's kind, never entered. Outside a repository,
227
+ * names starting with `.` and SKIPPED_FOLDERS are skipped. Blocked paths never appear. Bounded by
228
+ * FIND_LIMITS; `truncated` when a bound stopped the walk.
229
+ */
230
+ export async function findWorkspaceEntries(projectRoot: string, { query = '', kinds = ['file'], matchMode = 'subsequence', now = Date.now, git }: FindOptions = {}): Promise<{ entries: FoundEntry[]; truncated?: true }> {
231
+ const root = await realRoot(projectRoot);
232
+ const wanted = query.trim().replace(/^\.\//, '').toLowerCase();
233
+ const matches = (candidate: string) => !wanted || (matchMode === 'suffix' ? candidate === wanted || candidate.endsWith(`/${wanted}`) : inOrder(wanted, candidate));
234
+ let walked;
235
+ try {
236
+ walked = await walk(root, {
237
+ depth: FIND_LIMITS.depth, scanned: FIND_LIMITS.scanned, ms: FIND_LIMITS.ms, now, git, links: true,
238
+ keep: () => true,
239
+ admit: (entry, repository) => repository || !(entry.name.startsWith('.') || SKIPPED_FOLDERS.has(entry.name)),
240
+ });
241
+ } catch (error) {
242
+ if (!(error instanceof IgnoreUnknown)) throw error;
243
+ return { entries: [], truncated: true };
244
+ }
245
+ const entries = walked.entries
246
+ .filter(entry => kinds.includes(entry.kind) && matches(entry.path.toLowerCase()))
247
+ .map(entry => ({ path: entry.path, kind: entry.kind }))
248
+ .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
249
+ return { entries, ...(walked.truncated ? { truncated: true as const } : {}) };
250
+ }
251
+
252
+ const invalidCursor = () => new FileAccessError('cursor is not one alpd gave for these params, or it expired; ask again without it', RPC_ERROR.invalidParams, 'invalid_cursor');
253
+
254
+ /**
255
+ * workspace.files.find in pages: the first call (no cursor) walks and keeps the snapshot; each
256
+ * `nextCursor` names the snapshot and where the next page starts, for the connection (`owner`) that
257
+ * asked and the same params only. A snapshot is dropped after its last page, FIND_LIMITS.ttlMs
258
+ * after its last use, or when more than FIND_LIMITS.snapshots are kept (the oldest first).
259
+ */
260
+ export function createFindPages({ now = Date.now, git }: { now?: () => number; git?: GitCheckOptions } = {}) {
261
+ const snapshots = new Map<string, { owner: unknown; key: string; entries: FoundEntry[]; truncated: boolean; at: number }>();
262
+ return async function page(owner: unknown, projectRoot: string, { query = '', kinds = ['file'], matchMode = 'subsequence', limit = WORKSPACE_FILES.maxFindEntries, cursor }: Omit<FindOptions, 'now' | 'git'> & { limit?: number; cursor?: string } = {}): Promise<{ entries: FoundEntry[]; nextCursor?: string; truncated?: true }> {
263
+ const count = Math.max(1, Math.min(WORKSPACE_FILES.maxFindEntries, Math.trunc(limit)));
264
+ const key = JSON.stringify([projectRoot, query, [...new Set(kinds)].sort(), matchMode]);
265
+ for (const [id, snapshot] of snapshots) if (now() - snapshot.at > FIND_LIMITS.ttlMs) snapshots.delete(id);
266
+ let id: string;
267
+ let offset: number;
268
+ let snapshot;
269
+ if (cursor !== undefined) {
270
+ const named = /^([A-Za-z0-9_-]{22})\.(\d{1,7})$/.exec(cursor);
271
+ snapshot = named ? snapshots.get(named[1]!) : undefined;
272
+ if (!named || !snapshot || snapshot.owner !== owner || snapshot.key !== key || Number(named[2]) > snapshot.entries.length) throw invalidCursor();
273
+ [id, offset] = [named[1]!, Number(named[2])];
274
+ } else {
275
+ const found = await findWorkspaceEntries(projectRoot, { query, kinds, matchMode, now, git });
276
+ snapshot = { owner, key, entries: found.entries, truncated: found.truncated === true, at: now() };
277
+ [id, offset] = [randomBytes(16).toString('base64url'), 0];
278
+ }
279
+ const entries = snapshot.entries.slice(offset, offset + count);
280
+ const end = offset + entries.length;
281
+ if (end < snapshot.entries.length) {
282
+ snapshot.at = now();
283
+ snapshots.set(id, snapshot);
284
+ for (const old of snapshots.keys()) { if (snapshots.size <= FIND_LIMITS.snapshots) break; snapshots.delete(old); }
285
+ } else snapshots.delete(id);
286
+ return { entries, ...(end < snapshot.entries.length ? { nextCursor: `${id}.${end}` } : {}), ...(snapshot.truncated ? { truncated: true as const } : {}) };
287
+ };
288
+ }
289
+
290
+ // ---- workspace.files.list and workspace.files.read (docs/protocol/alp-json-rpc-v1.md §12.4) ----
291
+
292
+ /**
293
+ * A refusal of workspace.files.list or workspace.files.read: the JSON-RPC code and `data.reason`
294
+ * alpd answers with. Messages are fixed or name only the client's own relative path, never a host
295
+ * path or anything read from a file.
296
+ */
297
+ export class FileAccessError extends Error {
298
+ constructor(message: string, readonly code: number, readonly reason: string) {
299
+ super(message);
300
+ }
301
+ }
302
+
303
+ /** Extra bounds of one listing: entries looked at, and wall time. */
304
+ const LIST_LIMITS = Object.freeze({ scanned: 20_000, ms: 3_000 });
305
+ /** Opening never follows a final link nor waits on a FIFO; Windows has neither flag. */
306
+ const OPEN_FLAGS = process.platform === 'win32' ? constants.O_RDONLY : constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
307
+
308
+ const notFound = (relative: string) => new FileAccessError(`No readable file or directory at ${relative}`, ERROR.notFound, 'not_found');
309
+ 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');
310
+ const outside = (relative: string) => new FileAccessError(`${relative} is a link that leads outside the workspace; alpd follows only links that stay inside it`, ERROR.forbidden, 'outside');
311
+
312
+ /** `real` as a '/'-separated path inside `root`, or undefined when it is the root itself, outside it or holds a backslash. */
313
+ function insideRoot(root: string, real: string): string | undefined {
314
+ const relative = path.relative(root, real);
315
+ if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return undefined;
316
+ const inside = relative.split(path.sep).join('/');
317
+ return inside.includes('\\') ? undefined : inside;
318
+ }
319
+
320
+ /**
321
+ * With internalLinks (workspace.files.browse): the segments of the real path `segments` lead to
322
+ * when it goes through links, provided that real path is inside the root and not blocked; the
323
+ * root itself is []. Only that real path is then read, checked as any other (no link on the way).
324
+ * `via` is the path as asked up to its first link, the last of it Git can judge (Git refuses a
325
+ * path beyond a link), so .gitignore is asked about it and about the real path.
326
+ */
327
+ async function internalSegments(root: string, segments: string[], relative: string): Promise<{ segments: string[]; via?: string }> {
328
+ let real;
329
+ try {
330
+ real = await realpath(path.join(root, ...segments));
331
+ } catch {
332
+ throw notFound(relative);
333
+ }
334
+ let via: string | undefined;
335
+ for (let index = 1; index <= segments.length && via === undefined; index++) {
336
+ if ((await lstat(path.join(root, ...segments.slice(0, index))).catch(() => undefined))?.isSymbolicLink()) via = segments.slice(0, index).join('/');
337
+ }
338
+ if (real === root) return { segments: [], via };
339
+ const inside = insideRoot(root, real);
340
+ if (inside === undefined) throw outside(relative);
341
+ if (blockedFilePath(inside)) throw new FileAccessError(`${relative} leads to a path that is not readable remotely: .git, .env files, ALP configuration and key or credential files are always refused`, ERROR.forbidden, 'blocked_path');
342
+ return { segments: inside.split('/'), via };
343
+ }
344
+
345
+ /** Where the link `file` leads, when its real path is inside `root`, not blocked, and a regular file or a directory. */
346
+ async function internalTarget(root: string, file: string): Promise<{ kind: 'file' | 'directory'; target: string } | undefined> {
347
+ try {
348
+ const real = await realpath(file);
349
+ const target = insideRoot(root, real);
350
+ if (target === undefined || blockedFilePath(target)) return undefined;
351
+ const info = await lstat(real);
352
+ return info.isFile() ? { kind: 'file', target } : info.isDirectory() ? { kind: 'directory', target } : undefined;
353
+ } catch {
354
+ return undefined;
355
+ }
356
+ }
357
+
358
+ /** The real path of a workspace root that is a directory, else FilesError. */
359
+ async function realRoot(projectRoot: string): Promise<string> {
360
+ if (!path.isAbsolute(projectRoot)) throw new FilesError('projectRoot must be an absolute path');
361
+ try {
362
+ const root = await realpath(projectRoot);
363
+ if (!(await stat(root)).isDirectory()) throw new Error('not a directory');
364
+ return root;
365
+ } catch {
366
+ throw new FilesError('projectRoot is not a directory alpd can read');
367
+ }
368
+ }
369
+
370
+ /**
371
+ * A path relative to the workspace as a client may send it, its segments, or a refusal: '/'
372
+ * separated, no leading slash, drive or backslash, no `.`, `..` or empty segment, no NUL, at most
373
+ * WORKSPACE_FILES.maxPathLength characters. A blocked path (blockedFilePath) is refused as such.
374
+ */
375
+ export function relativeSegments(relative: unknown): string[] {
376
+ if (typeof relative !== 'string' || !relative || [...relative].length > WORKSPACE_FILES.maxPathLength || relative.includes('\0') || relative.includes('\\') || relative.startsWith('/') || /^[A-Za-z]:/.test(relative)) {
377
+ throw new FileAccessError('path must be a relative path inside the workspace, with / between names and no . or .. segment', RPC_ERROR.invalidParams, 'invalid_path');
378
+ }
379
+ const segments = relative.split('/');
380
+ if (segments.some(segment => segment === '' || segment === '.' || segment === '..')) {
381
+ throw new FileAccessError('path must be a relative path inside the workspace, with / between names and no . or .. segment', RPC_ERROR.invalidParams, 'invalid_path');
382
+ }
383
+ 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');
384
+ return segments;
385
+ }
386
+
387
+ /**
388
+ * The directories from the root to `segments` (the root first), each checked as reached by name:
389
+ * a real directory, not a link, at its own real path. Their identities (device and inode) are
390
+ * returned so the caller can check them again after reading.
391
+ */
392
+ async function directoryChain(root: string, segments: string[], relative: string): Promise<{ paths: string[]; identities: string[] }> {
393
+ const paths = [root];
394
+ for (let index = 0; index < segments.length; index++) paths.push(path.join(root, ...segments.slice(0, index + 1)));
395
+ const identities: string[] = [];
396
+ for (const directory of paths) identities.push(await directoryIdentity(directory, relative));
397
+ return { paths, identities };
398
+ }
399
+
400
+ /** The identity of a directory reached by name, or the refusal: missing or not a directory, or a link. */
401
+ async function directoryIdentity(directory: string, relative: string): Promise<string> {
402
+ let info;
403
+ try {
404
+ info = await lstat(directory, { bigint: true });
405
+ } catch {
406
+ throw notFound(relative);
407
+ }
408
+ if (info.isSymbolicLink()) throw linked(relative);
409
+ if (!info.isDirectory()) throw notFound(relative);
410
+ let real;
411
+ try {
412
+ real = await realpath(directory);
413
+ } catch {
414
+ throw notFound(relative);
415
+ }
416
+ if (real !== directory) throw linked(relative);
417
+ return `${info.dev}:${info.ino}`;
418
+ }
419
+
420
+ /** The chain checked again: the same directories, else the read is refused. */
421
+ async function sameChain(chain: { paths: string[]; identities: string[] }, relative: string): Promise<void> {
422
+ for (const [index, directory] of chain.paths.entries()) {
423
+ let now;
424
+ try {
425
+ now = await directoryIdentity(directory, relative);
426
+ } catch {
427
+ throw linked(relative);
428
+ }
429
+ if (now !== chain.identities[index]) throw linked(relative);
430
+ }
431
+ }
432
+
433
+ /**
434
+ * Which of `paths` .gitignore hides (gitignore.ts, Git's own answer), failing closed: when Git
435
+ * cannot answer, every path counts as ignored. No repository or no Git: none is.
436
+ */
437
+ async function ignoredOf(root: string, paths: string[], git?: GitCheckOptions): Promise<(path: string) => boolean> {
438
+ try {
439
+ const ignored = await gitIgnored(root, paths, git);
440
+ return ignored ? entry => ignored.has(entry) : () => false;
441
+ } catch (error) {
442
+ if (!(error instanceof IgnoreUnknown)) throw error;
443
+ return () => true;
444
+ }
445
+ }
446
+
447
+ /**
448
+ * The bytes of a regular file reached by name, or undefined when it is larger than `maxBytes`;
449
+ * throws when it is missing, not a regular file, a link, has more than one name, or is not the
450
+ * file it was a moment before. The file is opened without following a final link and checked by
451
+ * its handle (same device and inode as by name, before and after).
452
+ */
453
+ /** Test probes: called between the checks of a read, where a racing writer could change the file. */
454
+ export type FileProbe = (step: 'checked' | 'read' | 'listed') => Promise<void> | void;
455
+
456
+ async function readConfined(file: string, maxBytes: number, probe?: FileProbe): Promise<{ bytes: Buffer; modifiedAt: Date } | undefined> {
457
+ const confined = await openConfined(file, maxBytes, probe);
458
+ if (!confined) return undefined;
459
+ const { handle, before, opened } = confined;
460
+ try {
461
+ // One byte more than allowed tells a file that grew from one that fits.
462
+ const buffer = Buffer.alloc(maxBytes + 1);
463
+ let length = 0;
464
+ while (length < buffer.length) {
465
+ const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
466
+ if (!bytesRead) break;
467
+ length += bytesRead;
468
+ }
469
+ if (length > maxBytes) return undefined;
470
+ await probe?.('read');
471
+ const after = await lstat(file, { bigint: true });
472
+ if (after.dev !== before.dev || after.ino !== before.ino) throw Object.assign(new Error('changed'), { linked: true });
473
+ return { bytes: buffer.subarray(0, length), modifiedAt: opened.mtime };
474
+ } finally {
475
+ await handle.close();
476
+ }
477
+ }
478
+
479
+ /**
480
+ * A regular file reached by name, opened as readConfined reads it: not a link, one name, at its
481
+ * own real path, opened without following a final link and the same file by its handle; undefined
482
+ * when it is larger than `maxBytes`. The caller reads, closes the handle and checks the name again.
483
+ */
484
+ async function openConfined(file: string, maxBytes: number, probe?: FileProbe): Promise<{ handle: FileHandle; before: BigIntStats; opened: BigIntStats } | undefined> {
485
+ const before = await lstat(file, { bigint: true });
486
+ if (before.isSymbolicLink()) throw Object.assign(new Error('link'), { linked: true });
487
+ if (!before.isFile()) throw new Error('not a file');
488
+ if (before.nlink > 1n) throw Object.assign(new Error('hard link'), { linked: true });
489
+ if ((await realpath(file)) !== file) throw Object.assign(new Error('real path differs'), { linked: true });
490
+ if (before.size > BigInt(maxBytes)) return undefined;
491
+ await probe?.('checked');
492
+ let handle;
493
+ try {
494
+ handle = await open(file, OPEN_FLAGS);
495
+ } catch (error) {
496
+ if ((error as NodeJS.ErrnoException).code === 'ELOOP') throw Object.assign(new Error('link'), { linked: true });
497
+ throw error;
498
+ }
499
+ try {
500
+ const opened = await handle.stat({ bigint: true });
501
+ if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.nlink > 1n) throw Object.assign(new Error('changed'), { linked: true });
502
+ return { handle, before, opened };
503
+ } catch (error) {
504
+ await handle.close();
505
+ throw error;
506
+ }
507
+ }
508
+
509
+ /**
510
+ * The bytes of the file at `segments` under the real root `root`, confined as readWorkspaceFile
511
+ * confines a read (every directory on the way a real directory reached by name and the same after
512
+ * the read; the file a regular file with one name, opened without following a link, the same by
513
+ * handle and by name), or `too_large` past `maxBytes`. Throws FileAccessError `linked` or
514
+ * `not_found` (its message names only `relative`). No block list or .gitignore check: the caller
515
+ * decides what may be read (workspace.git.diff, docs/protocol/alp-json-rpc-v1.md §12.5).
516
+ */
517
+ export async function readConfinedFile(root: string, segments: readonly string[], relative: string, maxBytes: number): Promise<Buffer | 'too_large'> {
518
+ const chain = await directoryChain(root, segments.slice(0, -1), relative);
519
+ let read: { bytes: Buffer } | undefined;
520
+ try {
521
+ read = await readConfined(path.join(root, ...segments), maxBytes);
522
+ } catch (error) {
523
+ if ((error as { linked?: boolean }).linked) throw linked(relative);
524
+ throw notFound(relative);
525
+ }
526
+ await sameChain(chain, relative);
527
+ return read === undefined ? 'too_large' : read.bytes;
528
+ }
529
+
530
+ /** Paseo's isLikelyBinary (file-explorer/service.ts at b63a325): a NUL byte, or over 30% control characters. */
531
+ export function likelyBinary(buffer: Buffer): boolean {
532
+ if (!buffer.length) return false;
533
+ let suspicious = 0;
534
+ for (const byte of buffer) {
535
+ if (byte === 0) return true;
536
+ if ((byte < 32 && byte !== 9 && byte !== 10 && byte !== 13) || byte === 127) suspicious++;
537
+ }
538
+ return suspicious / buffer.length > 0.3;
539
+ }
540
+
541
+ // The BOM is kept: the content is the file's bytes, decoded.
542
+ /** PEM, OpenSSH and PuTTY private-key headers: a file holding one is refused whatever its name. */
543
+ export const PRIVATE_KEY = /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----|PuTTY-User-Key-File-\d+:/;
544
+
545
+ const UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
546
+
547
+ export type ListedEntry = { name: string; path: string; kind: 'file' | 'directory'; size?: number; modifiedAt?: string; target?: string };
548
+
549
+ /** The order of a listing: directories first, then by name (code units). */
550
+ const listOrder = (a: { kind: string; name: string }, b: { kind: string; name: string }) => (a.kind === b.kind ? 0 : a.kind === 'directory' ? -1 : 1) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
551
+ /** A listing's `nextCursor`: the last entry answered, which the next page starts after. */
552
+ const listCursor = (entry: { kind: 'file' | 'directory'; name: string }) => Buffer.from(JSON.stringify([entry.kind === 'directory' ? 0 : 1, entry.name])).toString('base64url');
553
+ function afterCursor(cursor: string): { kind: 'file' | 'directory'; name: string } {
554
+ let value: unknown;
555
+ try { value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')); } catch { value = undefined; }
556
+ if (!Array.isArray(value) || value.length !== 2 || (value[0] !== 0 && value[0] !== 1) || typeof value[1] !== 'string' || !value[1]) {
557
+ throw new FileAccessError('cursor is not one alpd gave for a listing', RPC_ERROR.invalidParams, 'invalid_cursor');
558
+ }
559
+ return { kind: value[0] === 0 ? 'directory' : 'file', name: value[1] };
560
+ }
561
+
562
+ /**
563
+ * The entries of a directory under `projectRoot` (its root without `relative`): regular files and
564
+ * directories only (links, sockets, devices are left out), never a blocked one (blockedFilePath)
565
+ * and, unless `includeIgnored`, none .gitignore'd. Directories first, then by name. Each directory
566
+ * on the way is checked (real directory, real path, same device and inode) before and after the
567
+ * read. At most WORKSPACE_FILES.maxListEntries entries; then `truncated` and `nextCursor`, which
568
+ * `cursor` takes to answer the entries after them.
569
+ *
570
+ * With `internalLinks` (workspace.files.browse): a link whose real path is inside the root and not
571
+ * blocked is listed as what it leads to, with that path as `target`, and `relative` may go through
572
+ * such links (the answer's `target` then names the directory listed, and entries are under it).
573
+ * Both the link's path and its target must pass .gitignore. A link leading outside is left out,
574
+ * and refused (`outside`) as `relative`.
575
+ */
576
+ export async function listWorkspaceDirectory(projectRoot: string, { path: relative, includeIgnored = false, cursor, internalLinks = false, now = Date.now, probe, git }: { path?: string; includeIgnored?: boolean; cursor?: string; internalLinks?: boolean; now?: () => number; probe?: FileProbe; git?: GitCheckOptions } = {}): Promise<{ entries: ListedEntry[]; truncated?: true; nextCursor?: string; target?: string }> {
577
+ const root = await realRoot(projectRoot);
578
+ const requested = relative === undefined ? [] : relativeSegments(relative);
579
+ const shown = relative ?? '.';
580
+ const after = cursor === undefined ? undefined : afterCursor(cursor);
581
+ const { segments, via } = internalLinks && requested.length ? await internalSegments(root, requested, shown) : { segments: requested, via: undefined };
582
+ const real = segments.join('/');
583
+ const target = real !== requested.join('/') ? real || '.' : undefined;
584
+ const chain = await directoryChain(root, segments, shown);
585
+ const directory = chain.paths.at(-1)!;
586
+ const prefix = segments.length ? `${real}/` : '';
587
+ const deadline = now() + LIST_LIMITS.ms;
588
+ // Regular files and directories that are not blocked, before .gitignore is asked about them.
589
+ const candidates: Array<{ name: string; child: string; kind: 'file' | 'directory'; target?: string }> = [];
590
+ let scanned = 0;
591
+ let truncated = false;
592
+ try {
593
+ for await (const entry of await opendir(directory)) {
594
+ if (++scanned > LIST_LIMITS.scanned || now() > deadline) { truncated = true; break; }
595
+ const child = `${prefix}${entry.name}`;
596
+ if (entry.name.includes('\\') || blockedFilePath(child)) continue;
597
+ const kind = entry.isFile() ? 'file' : entry.isDirectory() ? 'directory' : undefined;
598
+ if (kind) candidates.push({ name: entry.name, child, kind });
599
+ else if (internalLinks && entry.isSymbolicLink()) {
600
+ const link = await internalTarget(root, path.join(directory, entry.name));
601
+ if (link) candidates.push({ name: entry.name, child, ...link });
602
+ }
603
+ }
604
+ } catch {
605
+ throw notFound(shown);
606
+ }
607
+ // One Git process for the directory and every candidate: Git also says a path inside an
608
+ // ignored directory is ignored, and a `!` rule can bring one back.
609
+ if (!includeIgnored) {
610
+ // The directory as asked (up to its first link, beyond which Git judges nothing) and as it is.
611
+ const listed = [...new Set([...(requested.length ? [via ?? relative!] : []), ...(segments.length ? [real] : [])])];
612
+ const ignored = await ignoredOf(root, [...listed, ...candidates.flatMap(entry => entry.target ? [entry.child, entry.target] : [entry.child])], git);
613
+ if (listed.some(ignored)) throw new FileAccessError(`${relative} is ignored by .gitignore; ask with includeIgnored to see it`, ERROR.forbidden, 'ignored');
614
+ for (let index = candidates.length - 1; index >= 0; index--) {
615
+ const candidate = candidates[index]!;
616
+ if (ignored(candidate.child) || (candidate.target !== undefined && ignored(candidate.target))) candidates.splice(index, 1);
617
+ }
618
+ }
619
+ candidates.sort(listOrder);
620
+ const start = after ? candidates.findIndex(candidate => listOrder(candidate, after) > 0) : 0;
621
+ const entries: ListedEntry[] = [];
622
+ let nextCursor: string | undefined;
623
+ for (const { name, child, kind, target: leadsTo } of start < 0 ? [] : candidates.slice(start)) {
624
+ if (entries.length >= WORKSPACE_FILES.maxListEntries) { truncated = true; nextCursor = listCursor(entries.at(-1)!); break; }
625
+ let info;
626
+ try {
627
+ // A link's target is a real path inside the root: what it leads to is described.
628
+ info = await lstat(leadsTo === undefined ? path.join(directory, name) : path.join(root, ...leadsTo.split('/')));
629
+ } catch {
630
+ continue;
631
+ }
632
+ // Replaced by something else since it was listed: left out.
633
+ if (kind === 'file' ? !info.isFile() : !info.isDirectory()) continue;
634
+ entries.push({ name, path: child, kind, ...(kind === 'file' ? { size: info.size } : {}), modifiedAt: info.mtime.toISOString(), ...(leadsTo === undefined ? {} : { target: leadsTo }) });
635
+ }
636
+ await probe?.('listed');
637
+ await sameChain(chain, shown);
638
+ return { entries, ...(truncated ? { truncated: true as const } : {}), ...(nextCursor ? { nextCursor } : {}), ...(target ? { target } : {}) };
639
+ }
640
+
641
+ /**
642
+ * The content of a UTF-8 text file under `projectRoot`, read-only: refused when it is blocked
643
+ * (blockedFilePath), .gitignore'd (unless `includeIgnored`), missing or not a regular file,
644
+ * reached through a link (any directory on the way or the file), has more than one name (a hard
645
+ * link may share a file from anywhere), changes while it is read, is over
646
+ * WORKSPACE_FILES.maxReadBytes, or is not UTF-8 text.
647
+ */
648
+ 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 }> {
649
+ const root = await realRoot(projectRoot);
650
+ const segments = relativeSegments(relative);
651
+ const chain = await directoryChain(root, segments.slice(0, -1), relative);
652
+ 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');
653
+ const file = path.join(root, ...segments);
654
+ let read: { bytes: Buffer; modifiedAt: Date } | undefined;
655
+ try {
656
+ read = await readConfined(file, WORKSPACE_FILES.maxReadBytes, probe);
657
+ } catch (error) {
658
+ if ((error as { linked?: boolean }).linked) throw linked(relative);
659
+ throw notFound(relative);
660
+ }
661
+ if (read === undefined) throw new FileAccessError(`${relative} is larger than ${WORKSPACE_FILES.maxReadBytes} bytes`, ERROR.failed, 'too_large');
662
+ await sameChain(chain, relative);
663
+ let content: string;
664
+ try {
665
+ if (likelyBinary(read.bytes)) throw new Error('binary');
666
+ content = UTF8.decode(read.bytes);
667
+ } catch {
668
+ throw new FileAccessError(`${relative} is not a UTF-8 text file`, ERROR.failed, 'binary');
669
+ }
670
+ // A private key under any name (id_work, a service account's JSON) is refused as a blocked path.
671
+ if (PRIVATE_KEY.test(content)) throw new FileAccessError(`${relative} holds a private key; such files are never readable remotely`, ERROR.forbidden, 'blocked_path');
672
+ return { path: relative, content, size: read.bytes.length, modifiedAt: read.modifiedAt.toISOString() };
673
+ }
674
+
675
+ // ---- workspace.files.preview (docs/protocol/alp-json-rpc-v1.md §12.11) ----
676
+
677
+ /** Images a preview answers as such, by extension (the Paseo bridge's own list). */
678
+ export const PREVIEW_IMAGES: Readonly<Record<string, string>> = Object.freeze({ '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml' });
679
+ /** Bytes before a chunk also searched for a private-key header, so none hides across a chunk's edge. */
680
+ const KEY_OVERLAP = 256;
681
+ /** What a preview reads at once while it decides whether a file is text. */
682
+ const CLASSIFY_BLOCK = 1024 * 1024;
683
+
684
+ export type FilePreview = {
685
+ path: string; target?: string; kind: 'text' | 'image' | 'binary'; mimeType: string; size: number; modifiedAt: string; revision: string;
686
+ encoding: 'base64' | 'none'; content?: string; offset?: number; nextOffset?: number;
687
+ };
688
+
689
+ /** A file's version as a preview names it: its identity, size, times and kind, hashed (no host detail leaves alpd). */
690
+ const revisionOf = (info: BigIntStats, kind: string) => `r${createHash('sha256').update(`${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}:${kind}`).digest('base64url').slice(0, 22)}`;
691
+
692
+ /**
693
+ * Whether the open file is text as the Paseo bridge judged it (textOf): no NUL byte, at most 30%
694
+ * control characters in its first 16 KiB, valid UTF-8 throughout; read in blocks, never whole.
695
+ * `key` when it is text holding a private-key header.
696
+ */
697
+ async function classify(handle: FileHandle, size: number): Promise<'text' | 'binary' | 'key'> {
698
+ const decoder = new TextDecoder('utf-8', { fatal: true });
699
+ const block = Buffer.alloc(Math.max(1, Math.min(CLASSIFY_BLOCK, size)));
700
+ let tail = '';
701
+ let key = false;
702
+ for (let position = 0; position < size;) {
703
+ const { bytesRead } = await handle.read(block, 0, Math.min(block.length, size - position), position);
704
+ if (!bytesRead) throw Object.assign(new Error('shrank'), { linked: true });
705
+ const bytes = block.subarray(0, bytesRead);
706
+ if (bytes.includes(0)) return 'binary';
707
+ if (position === 0) {
708
+ const head = bytes.subarray(0, 16 * 1024);
709
+ let control = 0;
710
+ for (const byte of head) if (byte < 9 || (byte > 13 && byte < 32)) control++;
711
+ if (control / head.length > 0.3) return 'binary';
712
+ }
713
+ try { decoder.decode(bytes, { stream: true }); } catch { return 'binary'; }
714
+ const text = tail + bytes.toString('latin1');
715
+ key ||= PRIVATE_KEY.test(text);
716
+ tail = text.slice(-KEY_OVERLAP);
717
+ position += bytesRead;
718
+ }
719
+ try { decoder.decode(); } catch { return 'binary'; }
720
+ return key ? 'key' : 'text';
721
+ }
722
+
723
+ /** Bytes `from` to `end` of the open file; throws when it holds fewer (it shrank while read). */
724
+ async function readRange(handle: FileHandle, from: number, end: number): Promise<Buffer> {
725
+ const buffer = Buffer.alloc(end - from);
726
+ let length = 0;
727
+ while (length < buffer.length) {
728
+ const { bytesRead } = await handle.read(buffer, length, buffer.length - length, from + length);
729
+ if (!bytesRead) throw Object.assign(new Error('shrank'), { linked: true });
730
+ length += bytesRead;
731
+ }
732
+ return buffer;
733
+ }
734
+
735
+ /**
736
+ * A preview of a file under `projectRoot`, as the Paseo bridge's Files panel showed one: `image`
737
+ * by extension (PREVIEW_IMAGES), else `text` when the whole file is (classify), else `binary`
738
+ * (metadata only, no content). Text and image bytes come as base64 in chunks of at most
739
+ * WORKSPACE_FILES.maxPreviewChunkBytes: the first from `offset` 0, each next one from the
740
+ * `nextOffset` before with the `revision` the first answered (a file that changed since is
741
+ * refused `changed`, so the chunks are of one file). At most `maxBytes` (and
742
+ * WORKSPACE_FILES.maxPreviewBytes), else `too_large`.
743
+ *
744
+ * Refused as workspace.files.read refuses: a blocked path, a .gitignore'd one (unless
745
+ * `includeIgnored`), missing or not a regular file, reached through a link, more than one name, a
746
+ * change while it is read; a text file holding a private key (and any chunk holding one) is
747
+ * refused `blocked_path`. With `internalLinks`, `relative` may go through links whose real path is
748
+ * inside the root (internalSegments): that real path, answered as `target`, is what is read, and
749
+ * both paths must pass .gitignore.
750
+ */
751
+ export async function previewWorkspaceFile(projectRoot: string, { path: relative, includeIgnored = false, internalLinks = false, maxBytes = WORKSPACE_FILES.maxPreviewBytes, offset = 0, revision, probe, git }: { path: string; includeIgnored?: boolean; internalLinks?: boolean; maxBytes?: number; offset?: number; revision?: string; probe?: FileProbe; git?: GitCheckOptions }): Promise<FilePreview> {
752
+ const root = await realRoot(projectRoot);
753
+ const requested = relativeSegments(relative);
754
+ const { segments, via } = internalLinks ? await internalSegments(root, requested, relative) : { segments: requested, via: undefined };
755
+ if (!segments.length) throw notFound(relative);
756
+ const real = segments.join('/');
757
+ const target = real !== relative ? real : undefined;
758
+ const limit = Math.max(1, Math.min(WORKSPACE_FILES.maxPreviewBytes, Math.trunc(maxBytes)));
759
+ const chain = await directoryChain(root, segments.slice(0, -1), relative);
760
+ if (!includeIgnored) {
761
+ // The path as asked (up to its first link, beyond which Git judges nothing) and as it is.
762
+ const asked = [...new Set([via ?? relative, real])];
763
+ if (asked.some(await ignoredOf(root, asked, git))) throw new FileAccessError(`${relative} is ignored by .gitignore; ask with includeIgnored to read it`, ERROR.forbidden, 'ignored');
764
+ }
765
+ const file = path.join(root, ...segments);
766
+ const extension = path.extname(file).toLowerCase();
767
+ let preview: FilePreview;
768
+ try {
769
+ const confined = await openConfined(file, limit, probe);
770
+ if (!confined) throw new FileAccessError(`${relative} is larger than ${limit} bytes`, ERROR.failed, 'too_large');
771
+ const { handle, before, opened } = confined;
772
+ try {
773
+ const size = Number(opened.size);
774
+ if (offset > 0 && revision === undefined) throw new FileAccessError('a chunk past offset 0 needs the revision its first chunk answered', RPC_ERROR.invalidParams, 'invalid_params');
775
+ const image = PREVIEW_IMAGES[extension];
776
+ // A later chunk is of the file and kind its revision names: text as offset 0 found it, or an image.
777
+ const kind: FilePreview['kind'] | 'key' = image ? 'image' : offset > 0 ? 'text' : await classify(handle, size);
778
+ if (kind === 'key') throw new FileAccessError(`${relative} holds a private key; such files are never readable remotely`, ERROR.forbidden, 'blocked_path');
779
+ const current = revisionOf(opened, kind);
780
+ if (revision !== undefined && revision !== current) throw new FileAccessError(`${relative} changed since its first chunk was read; read it again from offset 0`, ERROR.conflict, 'changed');
781
+ if (offset > 0 && offset >= size) throw new FileAccessError(`offset is past the end of ${relative}`, RPC_ERROR.invalidParams, 'invalid_params');
782
+ const mimeType = image ?? (kind === 'binary' ? 'application/octet-stream' : extension === '.json' ? 'application/json' : 'text/plain');
783
+ // To the nearest millisecond, as fs.Stats and so workspace.files.list give it.
784
+ const modifiedAt = new Date(Number(opened.mtimeNs / 1_000_000n) + (opened.mtimeNs % 1_000_000n >= 500_000n ? 1 : 0)).toISOString();
785
+ const base = { path: relative, ...(target === undefined ? {} : { target }), kind, mimeType, size, modifiedAt, revision: current };
786
+ if (kind === 'binary') preview = { ...base, encoding: 'none' };
787
+ else {
788
+ const end = Math.min(size, offset + WORKSPACE_FILES.maxPreviewChunkBytes);
789
+ const from = Math.max(0, offset - KEY_OVERLAP);
790
+ const bytes = await readRange(handle, from, end);
791
+ if (PRIVATE_KEY.test(bytes.toString('latin1'))) throw new FileAccessError(`${relative} holds a private key; such files are never readable remotely`, ERROR.forbidden, 'blocked_path');
792
+ preview = { ...base, encoding: 'base64', content: bytes.subarray(offset - from).toString('base64'), offset, ...(end < size ? { nextOffset: end } : {}) };
793
+ }
794
+ await probe?.('read');
795
+ const after = await lstat(file, { bigint: true });
796
+ if (after.dev !== before.dev || after.ino !== before.ino) throw Object.assign(new Error('changed'), { linked: true });
797
+ } finally {
798
+ await handle.close();
799
+ }
800
+ } catch (error) {
801
+ if (error instanceof FileAccessError) throw error;
802
+ if ((error as { linked?: boolean }).linked) throw linked(relative);
803
+ throw notFound(relative);
804
+ }
805
+ await sameChain(chain, relative);
806
+ return preview;
807
+ }
808
+
809
+ // ---- host.directories.search (docs/protocol/alp-json-rpc-v1.md §12.11) ----
810
+
811
+ /** Bounds of host.directories.search: home's directories `depth` levels down, `scanned` looked at; a typed path's parent read up to `listed` entries. */
812
+ export const HOST_DIRECTORIES = Object.freeze({ depth: 4, scanned: 5_000, listed: 20_000, defaultLimit: 30, maxLimit: 100 });
813
+
814
+ /** How well a name matches a query, as the Paseo bridge ranks names: 0 equal, 1 starts with it, 2 holds it, 3 its letters in order, undefined none; case-insensitive. */
815
+ export function nameRank(candidate: string, query: string): number | undefined {
816
+ const name = candidate.toLowerCase();
817
+ const wanted = query.toLowerCase();
818
+ if (name === wanted) return 0;
819
+ if (name.startsWith(wanted)) return 1;
820
+ if (name.includes(wanted)) return 2;
821
+ return inOrder(wanted, name) ? 3 : undefined;
822
+ }
823
+
824
+ /** The directories in `directory` (not links), up to `max` entries looked at; none when it cannot be read. */
825
+ async function subdirectories(directory: string, max: number): Promise<{ names: string[]; truncated: boolean }> {
826
+ const names: string[] = [];
827
+ let looked = 0;
828
+ try {
829
+ for await (const entry of await opendir(directory)) {
830
+ if (++looked > max) return { names, truncated: true };
831
+ if (entry.isDirectory()) names.push(entry.name);
832
+ }
833
+ } catch {
834
+ // Unreadable or gone: nothing to suggest there.
835
+ }
836
+ return { names, truncated: false };
837
+ }
838
+
839
+ /**
840
+ * The daemon host's directories for the folder a user adds as a project, as the Paseo bridge
841
+ * suggested them: a `query` that is a path (absolute, or `~` and `~/…` under `home`) answers the
842
+ * directories of its parent whose name starts with what follows the last separator (dot names only
843
+ * when that starts with `.`), by name; any other word answers the directories under `home`, up to
844
+ * HOST_DIRECTORIES.depth levels and .scanned of them (no dot names, none of SKIPPED_FOLDERS), whose
845
+ * name matches it (nameRank), best, then nearest, first. Names only; a link is neither listed nor
846
+ * entered. Absolute paths: the caller is the host's owner (never remote).
847
+ */
848
+ export async function searchHostDirectories(query: unknown, { limit = HOST_DIRECTORIES.defaultLimit, home = os.homedir() }: { limit?: number; home?: string } = {}): Promise<{ entries: Array<{ path: string }>; truncated?: true }> {
849
+ const typed = typeof query === 'string' ? query.trim() : '';
850
+ const count = Math.max(1, Math.min(HOST_DIRECTORIES.maxLimit, Math.trunc(limit)));
851
+ const done = (paths: string[], truncated: boolean) => ({ entries: paths.slice(0, count).map(entry => ({ path: entry })), ...(truncated ? { truncated: true as const } : {}) });
852
+ if (!typed) return done([], false);
853
+ if (path.isAbsolute(typed) || typed.startsWith('~')) {
854
+ const expanded = typed === '~' ? home : typed.startsWith('~/') ? path.join(home, typed.slice(2)) : typed;
855
+ if (!path.isAbsolute(expanded)) return done([], false);
856
+ const folder = expanded.endsWith('/') || expanded.endsWith(path.sep);
857
+ const parent = folder ? expanded : path.dirname(expanded);
858
+ const prefix = folder ? '' : path.basename(expanded).toLowerCase();
859
+ const { names, truncated } = await subdirectories(parent, HOST_DIRECTORIES.listed);
860
+ const matching = names.filter(name => name.toLowerCase().startsWith(prefix) && (!name.startsWith('.') || prefix.startsWith('.'))).sort((a, b) => a.localeCompare(b));
861
+ return done(matching.map(name => path.join(parent, name)), truncated);
862
+ }
863
+ const found: Array<{ path: string; score: number; depth: number }> = [];
864
+ let queue = [home];
865
+ let scanned = 0;
866
+ for (let depth = 1; depth <= HOST_DIRECTORIES.depth && queue.length && scanned < HOST_DIRECTORIES.scanned; depth += 1) {
867
+ const next: string[] = [];
868
+ for (const directory of queue) {
869
+ for (const name of (await subdirectories(directory, HOST_DIRECTORIES.listed)).names) {
870
+ if (name.startsWith('.') || SKIPPED_FOLDERS.has(name)) continue;
871
+ const full = path.join(directory, name);
872
+ scanned += 1;
873
+ const score = nameRank(name, typed);
874
+ if (score !== undefined) found.push({ path: full, score, depth });
875
+ next.push(full);
876
+ if (scanned >= HOST_DIRECTORIES.scanned) break;
877
+ }
878
+ if (scanned >= HOST_DIRECTORIES.scanned) break;
879
+ }
880
+ queue = next;
881
+ }
882
+ found.sort((a, b) => a.score - b.score || a.depth - b.depth || a.path.localeCompare(b.path));
883
+ return done(found.map(entry => entry.path), scanned >= HOST_DIRECTORIES.scanned);
884
+ }