@anhlp/alp-daemon 0.0.1-beta.4 → 0.0.1-beta.5

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 (82) hide show
  1. package/dist/THIRD-PARTY-NOTICES.txt +26 -1
  2. package/dist/alpd.js +11047 -3021
  3. package/dist/attachments.d.ts +25 -49
  4. package/dist/attachments.js +45 -8
  5. package/dist/build-manifest.json +14 -1
  6. package/dist/conversation.js +18 -2
  7. package/dist/disk.d.ts +67 -0
  8. package/dist/disk.js +152 -0
  9. package/dist/files.d.ts +141 -2
  10. package/dist/files.js +377 -68
  11. package/dist/git.d.ts +8 -2
  12. package/dist/git.js +111 -12
  13. package/dist/index.d.ts +1 -0
  14. package/dist/index.js +3 -0
  15. package/dist/main.js +37 -11
  16. package/dist/native-terminal.d.ts +45 -0
  17. package/dist/native-terminal.js +198 -0
  18. package/dist/operations.d.ts +8 -2
  19. package/dist/operations.js +20 -10
  20. package/dist/registry.js +1 -1
  21. package/dist/scheduler.js +8 -2
  22. package/dist/schedules.d.ts +2 -1
  23. package/dist/schedules.js +6 -4
  24. package/dist/server.d.ts +4 -2
  25. package/dist/server.js +166 -42
  26. package/dist/store.d.ts +3 -1
  27. package/dist/store.js +4 -3
  28. package/dist/terminal-native/README.md +201 -0
  29. package/dist/terminal-native/prebuilt/darwin-arm64/manifest.json +11 -0
  30. package/dist/terminal-native/prebuilt/darwin-arm64/terminal-owner +0 -0
  31. package/dist/terminal-native/prebuilt/darwin-x64/manifest.json +11 -0
  32. package/dist/terminal-native/prebuilt/darwin-x64/terminal-owner +0 -0
  33. package/dist/terminal-native/prebuilt/linux-arm64-glibc/manifest.json +10 -0
  34. package/dist/terminal-native/prebuilt/linux-arm64-glibc/terminal-owner +0 -0
  35. package/dist/terminal-native/prebuilt/linux-arm64-musl/manifest.json +10 -0
  36. package/dist/terminal-native/prebuilt/linux-arm64-musl/terminal-owner +0 -0
  37. package/dist/terminal-native/prebuilt/linux-x64-glibc/manifest.json +10 -0
  38. package/dist/terminal-native/prebuilt/linux-x64-glibc/terminal-owner +0 -0
  39. package/dist/terminal-native/prebuilt/linux-x64-musl/manifest.json +10 -0
  40. package/dist/terminal-native/prebuilt/linux-x64-musl/terminal-owner +0 -0
  41. package/dist/terminal-native/terminal-owner.c +389 -0
  42. package/dist/terminal-screen.d.ts +24 -0
  43. package/dist/terminal-screen.js +99 -0
  44. package/dist/terminals.d.ts +43 -7
  45. package/dist/terminals.js +222 -139
  46. package/dist/windows-terminal.d.ts +29 -0
  47. package/dist/windows-terminal.js +122 -0
  48. package/dist/worktrees.d.ts +25 -1
  49. package/dist/worktrees.js +74 -2
  50. package/native/README.md +201 -0
  51. package/native/prebuilt/darwin-arm64/manifest.json +11 -0
  52. package/native/prebuilt/darwin-arm64/terminal-owner +0 -0
  53. package/native/prebuilt/darwin-x64/manifest.json +11 -0
  54. package/native/prebuilt/darwin-x64/terminal-owner +0 -0
  55. package/native/prebuilt/linux-arm64-glibc/manifest.json +10 -0
  56. package/native/prebuilt/linux-arm64-glibc/terminal-owner +0 -0
  57. package/native/prebuilt/linux-arm64-musl/manifest.json +10 -0
  58. package/native/prebuilt/linux-arm64-musl/terminal-owner +0 -0
  59. package/native/prebuilt/linux-x64-glibc/manifest.json +10 -0
  60. package/native/prebuilt/linux-x64-glibc/terminal-owner +0 -0
  61. package/native/prebuilt/linux-x64-musl/manifest.json +10 -0
  62. package/native/prebuilt/linux-x64-musl/terminal-owner +0 -0
  63. package/native/terminal-owner.c +389 -0
  64. package/package.json +11 -7
  65. package/src/attachments.ts +46 -8
  66. package/src/conversation.ts +22 -2
  67. package/src/disk.ts +175 -0
  68. package/src/files.ts +505 -80
  69. package/src/git.ts +113 -18
  70. package/src/index.ts +1 -0
  71. package/src/main.ts +30 -11
  72. package/src/native-terminal.ts +122 -0
  73. package/src/operations.ts +27 -11
  74. package/src/registry.ts +1 -1
  75. package/src/scheduler.ts +13 -3
  76. package/src/schedules.ts +5 -2
  77. package/src/server.ts +157 -35
  78. package/src/store.ts +2 -1
  79. package/src/terminal-screen.ts +74 -0
  80. package/src/terminals.ts +205 -155
  81. package/src/windows-terminal.ts +123 -0
  82. package/src/worktrees.ts +97 -2
package/src/files.ts CHANGED
@@ -1,5 +1,7 @@
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
7
  import { gitIgnored, IgnoreUnknown, GIT_CHECK, type GitCheckOptions } from './gitignore.js';
@@ -93,83 +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, git }: { query?: string; limit?: number; now?: () => number; git?: GitCheckOptions } = {}): 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 realDeadline = Date.now() + LIMITS.ms;
113
- 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[] = [];
114
122
  let scanned = 0;
115
123
  let truncated = false;
116
- // 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;
117
126
  let level: string[] = [''];
118
127
  for (let depth = 0; level.length && !truncated; depth++) {
119
- const next: string[] = [];
120
- const levelFiles: Rank[] = [];
128
+ const levelEntries: Walked[] = [];
121
129
  for (const relative of level) {
122
- if (scanned >= LIMITS.scanned || now() > deadline) { truncated = true; break; }
130
+ if (scanned >= options.scanned || now() > deadline) { truncated = true; break; }
123
131
  // Reached by names alone from the real root, so it is inside it unless a link took its place.
124
132
  const directory = relative ? path.join(root, ...relative.split('/')) : root;
125
- const files: Rank[] = [];
126
- const directories: string[] = [];
133
+ const entries: Walked[] = [];
127
134
  try {
128
135
  const before = await identity(directory);
129
136
  if (!before) continue;
130
137
  // Iterated, not read whole: the limits hold inside one large directory too.
131
138
  for await (const entry of await opendir(directory)) {
132
- if (++scanned > LIMITS.scanned || now() > deadline) { truncated = true; break; }
139
+ if (++scanned > options.scanned || now() > deadline) { truncated = true; break; }
133
140
  const name = entry.name;
134
141
  const child = relative ? `${relative}/${name}` : name;
135
142
  if (name.includes('\\') || blockedFilePath(child)) continue;
136
- if (entry.isFile()) {
137
- if (name.startsWith('.')) continue;
138
- const ranked = rank(child, wanted);
139
- if (ranked) files.push(ranked);
140
- } else if (entry.isDirectory()) {
141
- if (IGNORED_DIRECTORIES.has(name) || (name.startsWith('.') && !HIDDEN_DIRECTORIES.has(name))) continue;
142
- if (depth < LIMITS.depth) directories.push(child);
143
- }
144
- // Links, sockets, devices: neither listed nor entered.
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 } : {}) });
145
147
  }
146
148
  if ((await identity(directory)) !== before) continue;
147
149
  } catch {
148
150
  continue;
149
151
  }
150
- levelFiles.push(...files);
151
- next.push(...directories);
152
+ levelEntries.push(...entries);
152
153
  if (truncated) break;
153
154
  }
154
155
  // One bounded Git request per breadth-first level, before entering its directories or
155
156
  // ranking its files. Git evaluates nested rules and ignored ancestors itself.
156
157
  const remaining = Math.min(deadline - now(), realDeadline - Date.now());
157
158
  if (remaining <= 0) { truncated = true; break; }
158
- let ignored: Set<string> | null;
159
- try {
160
- ignored = await gitIgnored(root, [...levelFiles.map(file => file.path), ...next], {
161
- ...git, timeoutMs: Math.min(git?.timeoutMs ?? GIT_CHECK.timeoutMs, remaining),
162
- });
163
- } catch (error) {
164
- if (!(error instanceof IgnoreUnknown)) throw error;
165
- // No partial result may reveal paths whose ignore status could not be established.
166
- return { files: [], truncated: true };
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;
167
164
  }
168
- found.push(...levelFiles.filter(file => !ignored?.has(file.path)));
169
- level = next.filter(directory => !ignored?.has(directory));
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 };
170
192
  }
193
+ const found = walked.entries.filter(entry => entry.kind === 'file').map(entry => rank(entry.path, wanted)!);
171
194
  found.sort(compare);
172
- 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
+ };
173
288
  }
174
289
 
175
290
  // ---- workspace.files.list and workspace.files.read (docs/protocol/alp-json-rpc-v1.md §12.4) ----
@@ -192,6 +307,53 @@ const OPEN_FLAGS = process.platform === 'win32' ? constants.O_RDONLY : constants
192
307
 
193
308
  const notFound = (relative: string) => new FileAccessError(`No readable file or directory at ${relative}`, ERROR.notFound, 'not_found');
194
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
+ }
195
357
 
196
358
  /** The real path of a workspace root that is a directory, else FilesError. */
197
359
  async function realRoot(projectRoot: string): Promise<string> {
@@ -292,6 +454,34 @@ async function ignoredOf(root: string, paths: string[], git?: GitCheckOptions):
292
454
  export type FileProbe = (step: 'checked' | 'read' | 'listed') => Promise<void> | void;
293
455
 
294
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> {
295
485
  const before = await lstat(file, { bigint: true });
296
486
  if (before.isSymbolicLink()) throw Object.assign(new Error('link'), { linked: true });
297
487
  if (!before.isFile()) throw new Error('not a file');
@@ -309,21 +499,10 @@ async function readConfined(file: string, maxBytes: number, probe?: FileProbe):
309
499
  try {
310
500
  const opened = await handle.stat({ bigint: true });
311
501
  if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.nlink > 1n) throw Object.assign(new Error('changed'), { linked: true });
312
- // One byte more than allowed tells a file that grew from one that fits.
313
- const buffer = Buffer.alloc(maxBytes + 1);
314
- let length = 0;
315
- while (length < buffer.length) {
316
- const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
317
- if (!bytesRead) break;
318
- length += bytesRead;
319
- }
320
- if (length > maxBytes) return undefined;
321
- await probe?.('read');
322
- const after = await lstat(file, { bigint: true });
323
- if (after.dev !== before.dev || after.ino !== before.ino) throw Object.assign(new Error('changed'), { linked: true });
324
- return { bytes: buffer.subarray(0, length), modifiedAt: opened.mtime };
325
- } finally {
502
+ return { handle, before, opened };
503
+ } catch (error) {
326
504
  await handle.close();
505
+ throw error;
327
506
  }
328
507
  }
329
508
 
@@ -365,35 +544,62 @@ export const PRIVATE_KEY = /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?----
365
544
 
366
545
  const UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
367
546
 
368
- 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
+ }
369
561
 
370
562
  /**
371
563
  * The entries of a directory under `projectRoot` (its root without `relative`): regular files and
372
564
  * directories only (links, sockets, devices are left out), never a blocked one (blockedFilePath)
373
565
  * and, unless `includeIgnored`, none .gitignore'd. Directories first, then by name. Each directory
374
566
  * on the way is checked (real directory, real path, same device and inode) before and after the
375
- * 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`.
376
575
  */
377
- 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 }> {
378
577
  const root = await realRoot(projectRoot);
379
- const segments = relative === undefined ? [] : relativeSegments(relative);
578
+ const requested = relative === undefined ? [] : relativeSegments(relative);
380
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;
381
584
  const chain = await directoryChain(root, segments, shown);
382
585
  const directory = chain.paths.at(-1)!;
383
- const prefix = segments.length ? `${relative}/` : '';
586
+ const prefix = segments.length ? `${real}/` : '';
384
587
  const deadline = now() + LIST_LIMITS.ms;
385
588
  // Regular files and directories that are not blocked, before .gitignore is asked about them.
386
- const candidates: Array<{ name: string; child: string; kind: 'file' | 'directory' }> = [];
589
+ const candidates: Array<{ name: string; child: string; kind: 'file' | 'directory'; target?: string }> = [];
387
590
  let scanned = 0;
388
591
  let truncated = false;
389
592
  try {
390
593
  for await (const entry of await opendir(directory)) {
391
594
  if (++scanned > LIST_LIMITS.scanned || now() > deadline) { truncated = true; break; }
392
- const kind = entry.isFile() ? 'file' : entry.isDirectory() ? 'directory' : undefined;
393
- if (!kind) continue;
394
595
  const child = `${prefix}${entry.name}`;
395
596
  if (entry.name.includes('\\') || blockedFilePath(child)) continue;
396
- 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
+ }
397
603
  }
398
604
  } catch {
399
605
  throw notFound(shown);
@@ -401,27 +607,35 @@ export async function listWorkspaceDirectory(projectRoot: string, { path: relati
401
607
  // One Git process for the directory and every candidate: Git also says a path inside an
402
608
  // ignored directory is ignored, and a `!` rule can bring one back.
403
609
  if (!includeIgnored) {
404
- const ignored = await ignoredOf(root, [...(segments.length ? [relative!] : []), ...candidates.map(entry => entry.child)], git);
405
- if (segments.length && ignored(relative!)) throw new FileAccessError(`${relative} is ignored by .gitignore; ask with includeIgnored to see it`, ERROR.forbidden, 'ignored');
406
- 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
+ }
407
618
  }
619
+ candidates.sort(listOrder);
620
+ const start = after ? candidates.findIndex(candidate => listOrder(candidate, after) > 0) : 0;
408
621
  const entries: ListedEntry[] = [];
409
- for (const { name, child, kind } of candidates) {
410
- 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; }
411
625
  let info;
412
626
  try {
413
- 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('/')));
414
629
  } catch {
415
630
  continue;
416
631
  }
417
632
  // Replaced by something else since it was listed: left out.
418
633
  if (kind === 'file' ? !info.isFile() : !info.isDirectory()) continue;
419
- 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 }) });
420
635
  }
421
636
  await probe?.('listed');
422
637
  await sameChain(chain, shown);
423
- 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));
424
- return { entries, ...(truncated ? { truncated: true as const } : {}) };
638
+ return { entries, ...(truncated ? { truncated: true as const } : {}), ...(nextCursor ? { nextCursor } : {}), ...(target ? { target } : {}) };
425
639
  }
426
640
 
427
641
  /**
@@ -457,3 +671,214 @@ export async function readWorkspaceFile(projectRoot: string, { path: relative, i
457
671
  if (PRIVATE_KEY.test(content)) throw new FileAccessError(`${relative} holds a private key; such files are never readable remotely`, ERROR.forbidden, 'blocked_path');
458
672
  return { path: relative, content, size: read.bytes.length, modifiedAt: read.modifiedAt.toISOString() };
459
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
+ }