@anhlp/alp-daemon 0.0.0-beta.2 → 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 (104) hide show
  1. package/README.md +4 -0
  2. package/dist/THIRD-PARTY-NOTICES.txt +27 -2
  3. package/dist/alpd.js +39374 -17503
  4. package/dist/attachments.d.ts +187 -0
  5. package/dist/attachments.js +856 -0
  6. package/dist/build-manifest.json +41 -2
  7. package/dist/conversation.d.ts +119 -0
  8. package/dist/conversation.js +688 -0
  9. package/dist/disk.d.ts +67 -0
  10. package/dist/disk.js +152 -0
  11. package/dist/files.d.ts +156 -3
  12. package/dist/files.js +402 -59
  13. package/dist/git.d.ts +98 -0
  14. package/dist/git.js +1246 -0
  15. package/dist/gitignore.d.ts +5 -0
  16. package/dist/gitignore.js +26 -7
  17. package/dist/history.d.ts +24 -0
  18. package/dist/history.js +149 -0
  19. package/dist/index.d.ts +7 -0
  20. package/dist/index.js +21 -1
  21. package/dist/lifecycle.d.ts +101 -0
  22. package/dist/lifecycle.js +239 -0
  23. package/dist/main.js +146 -21
  24. package/dist/model-catalog.d.ts +2 -0
  25. package/dist/model-catalog.js +44 -0
  26. package/dist/native-entry.d.ts +2 -0
  27. package/dist/native-entry.js +3 -0
  28. package/dist/native-register.d.ts +1 -0
  29. package/dist/native-register.js +13 -0
  30. package/dist/native-terminal.d.ts +45 -0
  31. package/dist/native-terminal.js +201 -0
  32. package/dist/operations.d.ts +20 -3
  33. package/dist/operations.js +62 -21
  34. package/dist/registry.d.ts +89 -0
  35. package/dist/registry.js +343 -0
  36. package/dist/scheduler.d.ts +96 -0
  37. package/dist/scheduler.js +298 -0
  38. package/dist/schedules.d.ts +70 -0
  39. package/dist/schedules.js +246 -0
  40. package/dist/server.d.ts +14 -2
  41. package/dist/server.js +903 -97
  42. package/dist/store.d.ts +72 -2
  43. package/dist/store.js +111 -4
  44. package/dist/terminal-native/README.md +201 -0
  45. package/dist/terminal-native/prebuilt/darwin-arm64/manifest.json +11 -0
  46. package/dist/terminal-native/prebuilt/darwin-arm64/terminal-owner +0 -0
  47. package/dist/terminal-native/prebuilt/darwin-x64/manifest.json +11 -0
  48. package/dist/terminal-native/prebuilt/darwin-x64/terminal-owner +0 -0
  49. package/dist/terminal-native/prebuilt/linux-arm64-glibc/manifest.json +10 -0
  50. package/dist/terminal-native/prebuilt/linux-arm64-glibc/terminal-owner +0 -0
  51. package/dist/terminal-native/prebuilt/linux-arm64-musl/manifest.json +10 -0
  52. package/dist/terminal-native/prebuilt/linux-arm64-musl/terminal-owner +0 -0
  53. package/dist/terminal-native/prebuilt/linux-x64-glibc/manifest.json +10 -0
  54. package/dist/terminal-native/prebuilt/linux-x64-glibc/terminal-owner +0 -0
  55. package/dist/terminal-native/prebuilt/linux-x64-musl/manifest.json +10 -0
  56. package/dist/terminal-native/prebuilt/linux-x64-musl/terminal-owner +0 -0
  57. package/dist/terminal-native/terminal-owner.c +389 -0
  58. package/dist/terminal-screen.d.ts +24 -0
  59. package/dist/terminal-screen.js +99 -0
  60. package/dist/terminals.d.ts +203 -0
  61. package/dist/terminals.js +570 -0
  62. package/dist/windows-terminal.d.ts +32 -0
  63. package/dist/windows-terminal.js +79 -0
  64. package/dist/worktrees.d.ts +65 -0
  65. package/dist/worktrees.js +318 -0
  66. package/native/README.md +201 -0
  67. package/native/prebuilt/darwin-arm64/manifest.json +11 -0
  68. package/native/prebuilt/darwin-arm64/terminal-owner +0 -0
  69. package/native/prebuilt/darwin-x64/manifest.json +11 -0
  70. package/native/prebuilt/darwin-x64/terminal-owner +0 -0
  71. package/native/prebuilt/linux-arm64-glibc/manifest.json +10 -0
  72. package/native/prebuilt/linux-arm64-glibc/terminal-owner +0 -0
  73. package/native/prebuilt/linux-arm64-musl/manifest.json +10 -0
  74. package/native/prebuilt/linux-arm64-musl/terminal-owner +0 -0
  75. package/native/prebuilt/linux-x64-glibc/manifest.json +10 -0
  76. package/native/prebuilt/linux-x64-glibc/terminal-owner +0 -0
  77. package/native/prebuilt/linux-x64-musl/manifest.json +10 -0
  78. package/native/prebuilt/linux-x64-musl/terminal-owner +0 -0
  79. package/native/terminal-owner.c +389 -0
  80. package/package.json +71 -8
  81. package/src/attachments.ts +908 -0
  82. package/src/conversation.ts +857 -0
  83. package/src/disk.ts +175 -0
  84. package/src/files.ts +535 -71
  85. package/src/git.ts +1220 -0
  86. package/src/gitignore.ts +25 -8
  87. package/src/history.ts +118 -0
  88. package/src/index.ts +7 -0
  89. package/src/lifecycle.ts +283 -0
  90. package/src/main.ts +154 -23
  91. package/src/model-catalog.ts +36 -0
  92. package/src/native-entry.ts +5 -0
  93. package/src/native-register.ts +21 -0
  94. package/src/native-terminal.ts +127 -0
  95. package/src/operations.ts +53 -22
  96. package/src/registry.ts +238 -0
  97. package/src/scheduler.ts +438 -0
  98. package/src/schedules.ts +297 -0
  99. package/src/server.ts +1019 -109
  100. package/src/store.ts +117 -4
  101. package/src/terminal-screen.ts +74 -0
  102. package/src/terminals.ts +653 -0
  103. package/src/windows-terminal.ts +74 -0
  104. package/src/worktrees.ts +382 -0
package/src/files.ts CHANGED
@@ -1,8 +1,10 @@
1
- import { constants } from 'node:fs';
2
- import { lstat, open, opendir, realpath, stat } from 'node:fs/promises';
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';
3
5
  import path from 'node:path';
4
6
  import { ERROR, RPC_ERROR, WORKSPACE_FILES, blockedFilePath } from '@anhlp/alp-protocol';
5
- import { gitIgnored, IgnoreUnknown, type GitCheckOptions } from './gitignore.js';
7
+ import { gitIgnored, IgnoreUnknown, GIT_CHECK, type GitCheckOptions } from './gitignore.js';
6
8
 
7
9
  // For tests: which git alpd would run, and how many run now.
8
10
  export { gitChecksRunning, resolveGit, GIT_CHECK } from './gitignore.js';
@@ -93,65 +95,196 @@ const compare = (a: Rank, b: Rank) =>
93
95
 
94
96
  export class FilesError extends Error {}
95
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
+
96
111
  /**
97
- * The files under `projectRoot` matching `query`, best first. `projectRoot` must be an absolute path
98
- * of a directory; anything else throws FilesError.
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.
99
116
  */
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[] = [];
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[] = [];
113
122
  let scanned = 0;
114
123
  let truncated = false;
115
- // Breadth first: shallow files are found before the limits stop the walk.
124
+ // Known after the first level Git was asked about; no rules at the root means none below it.
125
+ let repository: boolean | undefined;
116
126
  let level: string[] = [''];
117
127
  for (let depth = 0; level.length && !truncated; depth++) {
118
- const next: string[] = [];
128
+ const levelEntries: Walked[] = [];
119
129
  for (const relative of level) {
120
- if (scanned >= LIMITS.scanned || now() > deadline) { truncated = true; break; }
130
+ if (scanned >= options.scanned || now() > deadline) { truncated = true; break; }
121
131
  // Reached by names alone from the real root, so it is inside it unless a link took its place.
122
132
  const directory = relative ? path.join(root, ...relative.split('/')) : root;
123
- const files: Rank[] = [];
124
- const directories: string[] = [];
133
+ const entries: Walked[] = [];
125
134
  try {
126
135
  const before = await identity(directory);
127
136
  if (!before) continue;
128
137
  // Iterated, not read whole: the limits hold inside one large directory too.
129
138
  for await (const entry of await opendir(directory)) {
130
- if (++scanned > LIMITS.scanned || now() > deadline) { truncated = true; break; }
139
+ if (++scanned > options.scanned || now() > deadline) { truncated = true; break; }
131
140
  const name = entry.name;
132
141
  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
+ 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 } : {}) });
142
147
  }
143
148
  if ((await identity(directory)) !== before) continue;
144
149
  } catch {
145
150
  continue;
146
151
  }
147
- found.push(...files);
148
- next.push(...directories);
152
+ levelEntries.push(...entries);
149
153
  if (truncated) break;
150
154
  }
151
- level = next;
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 };
152
192
  }
193
+ const found = walked.entries.filter(entry => entry.kind === 'file').map(entry => rank(entry.path, wanted)!);
153
194
  found.sort(compare);
154
- return { files: found.slice(0, count).map(entry => ({ path: entry.path })), ...(truncated ? { truncated: true as const } : {}) };
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
+ };
155
288
  }
156
289
 
157
290
  // ---- workspace.files.list and workspace.files.read (docs/protocol/alp-json-rpc-v1.md §12.4) ----
@@ -174,6 +307,53 @@ const OPEN_FLAGS = process.platform === 'win32' ? constants.O_RDONLY : constants
174
307
 
175
308
  const notFound = (relative: string) => new FileAccessError(`No readable file or directory at ${relative}`, ERROR.notFound, 'not_found');
176
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
+ }
177
357
 
178
358
  /** The real path of a workspace root that is a directory, else FilesError. */
179
359
  async function realRoot(projectRoot: string): Promise<string> {
@@ -274,6 +454,34 @@ async function ignoredOf(root: string, paths: string[], git?: GitCheckOptions):
274
454
  export type FileProbe = (step: 'checked' | 'read' | 'listed') => Promise<void> | void;
275
455
 
276
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> {
277
485
  const before = await lstat(file, { bigint: true });
278
486
  if (before.isSymbolicLink()) throw Object.assign(new Error('link'), { linked: true });
279
487
  if (!before.isFile()) throw new Error('not a file');
@@ -291,26 +499,36 @@ async function readConfined(file: string, maxBytes: number, probe?: FileProbe):
291
499
  try {
292
500
  const opened = await handle.stat({ bigint: true });
293
501
  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 {
502
+ return { handle, before, opened };
503
+ } catch (error) {
308
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);
309
525
  }
526
+ await sameChain(chain, relative);
527
+ return read === undefined ? 'too_large' : read.bytes;
310
528
  }
311
529
 
312
530
  /** Paseo's isLikelyBinary (file-explorer/service.ts at b63a325): a NUL byte, or over 30% control characters. */
313
- function likelyBinary(buffer: Buffer): boolean {
531
+ export function likelyBinary(buffer: Buffer): boolean {
314
532
  if (!buffer.length) return false;
315
533
  let suspicious = 0;
316
534
  for (const byte of buffer) {
@@ -322,39 +540,66 @@ function likelyBinary(buffer: Buffer): boolean {
322
540
 
323
541
  // The BOM is kept: the content is the file's bytes, decoded.
324
542
  /** 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+:/;
543
+ export const PRIVATE_KEY = /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----|PuTTY-User-Key-File-\d+:/;
326
544
 
327
545
  const UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
328
546
 
329
- export type ListedEntry = { name: string; path: string; kind: 'file' | 'directory'; size?: number; modifiedAt?: string };
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
+ }
330
561
 
331
562
  /**
332
563
  * The entries of a directory under `projectRoot` (its root without `relative`): regular files and
333
564
  * directories only (links, sockets, devices are left out), never a blocked one (blockedFilePath)
334
565
  * and, unless `includeIgnored`, none .gitignore'd. Directories first, then by name. Each directory
335
566
  * 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`.
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`.
337
575
  */
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 }> {
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 }> {
339
577
  const root = await realRoot(projectRoot);
340
- const segments = relative === undefined ? [] : relativeSegments(relative);
578
+ const requested = relative === undefined ? [] : relativeSegments(relative);
341
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;
342
584
  const chain = await directoryChain(root, segments, shown);
343
585
  const directory = chain.paths.at(-1)!;
344
- const prefix = segments.length ? `${relative}/` : '';
586
+ const prefix = segments.length ? `${real}/` : '';
345
587
  const deadline = now() + LIST_LIMITS.ms;
346
588
  // 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' }> = [];
589
+ const candidates: Array<{ name: string; child: string; kind: 'file' | 'directory'; target?: string }> = [];
348
590
  let scanned = 0;
349
591
  let truncated = false;
350
592
  try {
351
593
  for await (const entry of await opendir(directory)) {
352
594
  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
595
  const child = `${prefix}${entry.name}`;
356
596
  if (entry.name.includes('\\') || blockedFilePath(child)) continue;
357
- candidates.push({ name: entry.name, child, kind });
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
+ }
358
603
  }
359
604
  } catch {
360
605
  throw notFound(shown);
@@ -362,27 +607,35 @@ export async function listWorkspaceDirectory(projectRoot: string, { path: relati
362
607
  // One Git process for the directory and every candidate: Git also says a path inside an
363
608
  // ignored directory is ignored, and a `!` rule can bring one back.
364
609
  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);
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
+ }
368
618
  }
619
+ candidates.sort(listOrder);
620
+ const start = after ? candidates.findIndex(candidate => listOrder(candidate, after) > 0) : 0;
369
621
  const entries: ListedEntry[] = [];
370
- for (const { name, child, kind } of candidates) {
371
- if (entries.length >= WORKSPACE_FILES.maxListEntries) { truncated = true; break; }
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; }
372
625
  let info;
373
626
  try {
374
- info = await lstat(path.join(directory, name));
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('/')));
375
629
  } catch {
376
630
  continue;
377
631
  }
378
632
  // Replaced by something else since it was listed: left out.
379
633
  if (kind === 'file' ? !info.isFile() : !info.isDirectory()) continue;
380
- entries.push({ name, path: child, kind, ...(kind === 'file' ? { size: info.size } : {}), modifiedAt: info.mtime.toISOString() });
634
+ entries.push({ name, path: child, kind, ...(kind === 'file' ? { size: info.size } : {}), modifiedAt: info.mtime.toISOString(), ...(leadsTo === undefined ? {} : { target: leadsTo }) });
381
635
  }
382
636
  await probe?.('listed');
383
637
  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 } : {}) };
638
+ return { entries, ...(truncated ? { truncated: true as const } : {}), ...(nextCursor ? { nextCursor } : {}), ...(target ? { target } : {}) };
386
639
  }
387
640
 
388
641
  /**
@@ -418,3 +671,214 @@ export async function readWorkspaceFile(projectRoot: string, { path: relative, i
418
671
  if (PRIVATE_KEY.test(content)) throw new FileAccessError(`${relative} holds a private key; such files are never readable remotely`, ERROR.forbidden, 'blocked_path');
419
672
  return { path: relative, content, size: read.bytes.length, modifiedAt: read.modifiedAt.toISOString() };
420
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
+ }