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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +7 -0
  3. package/README.md +14 -2
  4. package/dist/THIRD-PARTY-NOTICES.txt +456 -0
  5. package/dist/alp-templates.d.ts +5 -0
  6. package/dist/alpd.js +64050 -0
  7. package/dist/attachments.d.ts +187 -0
  8. package/dist/attachments.js +856 -0
  9. package/dist/build-manifest.json +150 -0
  10. package/dist/conversation.d.ts +119 -0
  11. package/dist/conversation.js +688 -0
  12. package/dist/disk.d.ts +67 -0
  13. package/dist/disk.js +152 -0
  14. package/dist/files.d.ts +262 -0
  15. package/dist/files.js +674 -0
  16. package/dist/git.d.ts +98 -0
  17. package/dist/git.js +1246 -0
  18. package/dist/gitignore.d.ts +62 -0
  19. package/dist/gitignore.js +254 -0
  20. package/dist/history.d.ts +24 -0
  21. package/dist/history.js +149 -0
  22. package/dist/index.d.ts +11 -0
  23. package/dist/index.js +28 -0
  24. package/dist/lifecycle.d.ts +101 -0
  25. package/dist/lifecycle.js +239 -0
  26. package/dist/lock.d.ts +21 -0
  27. package/dist/lock.js +42 -0
  28. package/dist/main.d.ts +1 -0
  29. package/dist/main.js +363 -0
  30. package/dist/model-catalog.d.ts +2 -0
  31. package/dist/model-catalog.js +44 -0
  32. package/dist/native-entry.d.ts +2 -0
  33. package/dist/native-entry.js +3 -0
  34. package/dist/native-register.d.ts +1 -0
  35. package/dist/native-register.js +13 -0
  36. package/dist/native-terminal.d.ts +45 -0
  37. package/dist/native-terminal.js +201 -0
  38. package/dist/operations.d.ts +40 -0
  39. package/dist/operations.js +313 -0
  40. package/dist/registry.d.ts +89 -0
  41. package/dist/registry.js +343 -0
  42. package/dist/rpc-error.d.ts +6 -0
  43. package/dist/rpc-error.js +11 -0
  44. package/dist/scheduler.d.ts +96 -0
  45. package/dist/scheduler.js +298 -0
  46. package/dist/schedules.d.ts +70 -0
  47. package/dist/schedules.js +246 -0
  48. package/dist/server.d.ts +60 -0
  49. package/dist/server.js +1958 -0
  50. package/dist/store.d.ts +178 -0
  51. package/dist/store.js +386 -0
  52. package/dist/terminal-native/README.md +201 -0
  53. package/dist/terminal-native/prebuilt/darwin-arm64/manifest.json +11 -0
  54. package/dist/terminal-native/prebuilt/darwin-arm64/terminal-owner +0 -0
  55. package/dist/terminal-native/prebuilt/darwin-x64/manifest.json +11 -0
  56. package/dist/terminal-native/prebuilt/darwin-x64/terminal-owner +0 -0
  57. package/dist/terminal-native/prebuilt/linux-arm64-glibc/manifest.json +10 -0
  58. package/dist/terminal-native/prebuilt/linux-arm64-glibc/terminal-owner +0 -0
  59. package/dist/terminal-native/prebuilt/linux-arm64-musl/manifest.json +10 -0
  60. package/dist/terminal-native/prebuilt/linux-arm64-musl/terminal-owner +0 -0
  61. package/dist/terminal-native/prebuilt/linux-x64-glibc/manifest.json +10 -0
  62. package/dist/terminal-native/prebuilt/linux-x64-glibc/terminal-owner +0 -0
  63. package/dist/terminal-native/prebuilt/linux-x64-musl/manifest.json +10 -0
  64. package/dist/terminal-native/prebuilt/linux-x64-musl/terminal-owner +0 -0
  65. package/dist/terminal-native/terminal-owner.c +389 -0
  66. package/dist/terminal-screen.d.ts +24 -0
  67. package/dist/terminal-screen.js +99 -0
  68. package/dist/terminals.d.ts +203 -0
  69. package/dist/terminals.js +570 -0
  70. package/dist/windows-terminal.d.ts +32 -0
  71. package/dist/windows-terminal.js +79 -0
  72. package/dist/worktrees.d.ts +65 -0
  73. package/dist/worktrees.js +318 -0
  74. package/native/README.md +201 -0
  75. package/native/prebuilt/darwin-arm64/manifest.json +11 -0
  76. package/native/prebuilt/darwin-arm64/terminal-owner +0 -0
  77. package/native/prebuilt/darwin-x64/manifest.json +11 -0
  78. package/native/prebuilt/darwin-x64/terminal-owner +0 -0
  79. package/native/prebuilt/linux-arm64-glibc/manifest.json +10 -0
  80. package/native/prebuilt/linux-arm64-glibc/terminal-owner +0 -0
  81. package/native/prebuilt/linux-arm64-musl/manifest.json +10 -0
  82. package/native/prebuilt/linux-arm64-musl/terminal-owner +0 -0
  83. package/native/prebuilt/linux-x64-glibc/manifest.json +10 -0
  84. package/native/prebuilt/linux-x64-glibc/terminal-owner +0 -0
  85. package/native/prebuilt/linux-x64-musl/manifest.json +10 -0
  86. package/native/prebuilt/linux-x64-musl/terminal-owner +0 -0
  87. package/native/terminal-owner.c +389 -0
  88. package/package.json +163 -4
  89. package/src/alp-templates.d.ts +5 -0
  90. package/src/attachments.ts +908 -0
  91. package/src/conversation.ts +857 -0
  92. package/src/disk.ts +175 -0
  93. package/src/files.ts +884 -0
  94. package/src/git.ts +1220 -0
  95. package/src/gitignore.ts +277 -0
  96. package/src/history.ts +118 -0
  97. package/src/index.ts +12 -0
  98. package/src/lifecycle.ts +283 -0
  99. package/src/lock.ts +53 -0
  100. package/src/main.ts +381 -0
  101. package/src/model-catalog.ts +36 -0
  102. package/src/native-entry.ts +5 -0
  103. package/src/native-register.ts +21 -0
  104. package/src/native-terminal.ts +127 -0
  105. package/src/operations.ts +329 -0
  106. package/src/registry.ts +238 -0
  107. package/src/rpc-error.ts +4 -0
  108. package/src/scheduler.ts +438 -0
  109. package/src/schedules.ts +297 -0
  110. package/src/server.ts +2238 -0
  111. package/src/store.ts +449 -0
  112. package/src/terminal-screen.ts +74 -0
  113. package/src/terminals.ts +653 -0
  114. package/src/windows-terminal.ts +74 -0
  115. package/src/worktrees.ts +382 -0
package/dist/disk.d.ts ADDED
@@ -0,0 +1,67 @@
1
+ /** Whether `error` (or the error it wraps) says the disk cannot take writes. */
2
+ export declare function isDiskError(error: unknown): boolean;
3
+ export declare const GiB: number;
4
+ export type DiskRuntime = {
5
+ holdForDisk(reason: string): unknown;
6
+ releaseDisk(by: string): unknown;
7
+ diskHeld(): boolean;
8
+ diskLow(free: string): void;
9
+ };
10
+ export type DiskGuardOptions = {
11
+ /** The directory whose disk alpd writes: ALP_HOME. */
12
+ home: string;
13
+ runtime: DiskRuntime;
14
+ log: {
15
+ warn(message: string, fields?: Record<string, unknown>): void;
16
+ info(message: string, fields?: Record<string, unknown>): void;
17
+ };
18
+ /** How often space is checked; ALP checks every minute. */
19
+ intervalMs?: number;
20
+ /** Below this, alpd warns once that space runs low (2 GiB). */
21
+ lowBytes?: number;
22
+ /** Below this, alpd holds work before writes fail (100 MiB). */
23
+ criticalBytes?: number;
24
+ /** Free space alpd needs to resume work it held (256 MiB); above criticalBytes, so it does not flap. */
25
+ resumeBytes?: number;
26
+ /** How long one statfs or probe may take (10 s). */
27
+ checkTimeoutMs?: number;
28
+ /** Free bytes on the disk of a directory; undefined when unknown. */
29
+ free?: (directory: string) => Promise<number | undefined>;
30
+ /** Writes and removes a small file; rejects when the disk takes no writes. */
31
+ probe?: (directory: string) => Promise<void>;
32
+ };
33
+ export declare function formatBytes(bytes: number): string;
34
+ /**
35
+ * Keeps alpd running when its disk fills (t-2831): a write failing with ENOSPC, EDQUOT or
36
+ * EROFS pauses all of ALP and parks running assignments (as a usage limit does), instead of
37
+ * stopping alpd. Reads go on. Every minute alpd checks free space and probes a write; when
38
+ * the disk takes writes again it lifts the pause it made and parked work continues. A pause
39
+ * the user made, and their alp resume, stay theirs. alpd deletes nothing to make room.
40
+ */
41
+ export declare function createDiskGuard(options: DiskGuardOptions): {
42
+ report: (error: unknown) => boolean;
43
+ check: () => Promise<void>;
44
+ status: () => {
45
+ last?: {
46
+ at: string;
47
+ free?: number;
48
+ writable: boolean;
49
+ } | undefined;
50
+ held: boolean;
51
+ full: boolean;
52
+ };
53
+ start(): void;
54
+ stop(): void;
55
+ };
56
+ /**
57
+ * Makes process.stdout and stderr survive a full disk when they are files (alpd's log, as the
58
+ * detached launcher opens it): a failed write is dropped, not thrown later as an 'error' event
59
+ * that would end alpd, and logging continues once space returns. Other streams (a terminal,
60
+ * a pipe) keep Node's own writes but no longer turn a write error into a crash.
61
+ */
62
+ export declare function guardOutput(onError: (error: unknown) => void, fs: {
63
+ fstatSync(fd: number): {
64
+ isFile(): boolean;
65
+ };
66
+ writeSync(fd: number, data: string | Uint8Array): number;
67
+ }): void;
package/dist/disk.js ADDED
@@ -0,0 +1,152 @@
1
+ // packages/daemon/src/disk.ts
2
+ import { statfs, unlink, writeFile } from "node:fs/promises";
3
+ import path from "node:path";
4
+ var DISK_CODES = /* @__PURE__ */ new Set(["ENOSPC", "EDQUOT", "EROFS"]);
5
+ function isDiskError(error) {
6
+ for (let current = error, depth = 0; current && depth < 4; current = current.cause, depth++) {
7
+ if (typeof current.code === "string" && DISK_CODES.has(current.code)) return true;
8
+ }
9
+ return false;
10
+ }
11
+ var GiB = 1024 ** 3;
12
+ var MiB = 1024 ** 2;
13
+ async function freeBytes(directory) {
14
+ try {
15
+ const info = await statfs(directory);
16
+ return Number(info.bavail) * Number(info.bsize);
17
+ } catch {
18
+ return void 0;
19
+ }
20
+ }
21
+ async function probeWrite(directory) {
22
+ const file = path.join(directory, `.alpd-disk-probe-${process.pid}`);
23
+ try {
24
+ await writeFile(file, "x".repeat(4096), { mode: 384 });
25
+ } finally {
26
+ await unlink(file).catch(() => {
27
+ });
28
+ }
29
+ }
30
+ function formatBytes(bytes) {
31
+ return bytes >= GiB ? `${(bytes / GiB).toFixed(1)} GB` : `${Math.max(0, Math.round(bytes / MiB))} MB`;
32
+ }
33
+ function createDiskGuard(options) {
34
+ const { home, runtime, log } = options;
35
+ const lowBytes = options.lowBytes ?? 2 * GiB;
36
+ const criticalBytes = options.criticalBytes ?? 100 * MiB;
37
+ const resumeBytes = Math.max(options.resumeBytes ?? 256 * MiB, criticalBytes);
38
+ const free = options.free ?? freeBytes;
39
+ const probe = options.probe ?? probeWrite;
40
+ let warnedLow = false;
41
+ let timer;
42
+ let checking;
43
+ let last;
44
+ let full = false;
45
+ let good = 0;
46
+ function hold(reason) {
47
+ good = 0;
48
+ if (full && runtime.diskHeld()) return;
49
+ const first = !full;
50
+ full = true;
51
+ runtime.holdForDisk(reason);
52
+ if (first) log.warn(`${reason}; ALP pauses its work until the disk takes writes again`, { code: "ALP_DISK_FULL" });
53
+ }
54
+ function report(error) {
55
+ if (!isDiskError(error)) return false;
56
+ const code = error?.code ?? error?.cause?.code;
57
+ hold(code === "EROFS" ? "the disk is read-only" : "the disk is full");
58
+ return true;
59
+ }
60
+ async function checkOnce() {
61
+ const bytes = await bounded(free(home), void 0);
62
+ const writable = await bounded(probe(home).then(() => true, (error) => isDiskError(error) ? false : true), !full);
63
+ last = { at: (/* @__PURE__ */ new Date()).toISOString(), ...bytes === void 0 ? {} : { free: bytes }, writable };
64
+ const shown = bytes === void 0 ? "unknown" : formatBytes(bytes);
65
+ if (full) {
66
+ if (!writable || bytes !== void 0 && bytes < resumeBytes) {
67
+ good = 0;
68
+ if (!runtime.diskHeld()) runtime.holdForDisk(writable ? `the disk is almost full (${shown} free)` : "the disk is full");
69
+ return;
70
+ }
71
+ if (++good < 2) return;
72
+ full = false;
73
+ good = 0;
74
+ warnedLow = false;
75
+ runtime.releaseDisk("alpd, after disk space returned");
76
+ log.info(`the disk takes writes again (${shown} free); ALP resumes its work`, { code: "ALP_DISK_BACK", free: bytes });
77
+ return;
78
+ }
79
+ if (!writable) {
80
+ hold("the disk is full");
81
+ return;
82
+ }
83
+ if (bytes !== void 0 && bytes < criticalBytes) {
84
+ hold(`the disk is almost full (${shown} free)`);
85
+ return;
86
+ }
87
+ if (bytes !== void 0 && bytes < lowBytes) {
88
+ if (!warnedLow) {
89
+ warnedLow = true;
90
+ log.warn(`disk space is low: ${shown} free`, { code: "ALP_DISK_LOW", free: bytes });
91
+ runtime.diskLow(shown);
92
+ }
93
+ } else if (bytes !== void 0 && bytes >= lowBytes * 1.25) warnedLow = false;
94
+ }
95
+ function bounded(work, fallback) {
96
+ let timer2;
97
+ const late = new Promise((resolve) => {
98
+ timer2 = setTimeout(() => resolve(fallback), options.checkTimeoutMs ?? 1e4);
99
+ });
100
+ return Promise.race([work, late]).finally(() => clearTimeout(timer2));
101
+ }
102
+ function check() {
103
+ checking ??= checkOnce().catch(() => {
104
+ }).finally(() => {
105
+ checking = void 0;
106
+ });
107
+ return checking;
108
+ }
109
+ return {
110
+ report,
111
+ check,
112
+ status: () => ({ held: runtime.diskHeld(), full, ...last ? { last } : {} }),
113
+ start() {
114
+ if (timer) return;
115
+ timer = setInterval(() => void check(), options.intervalMs ?? 6e4);
116
+ timer.unref?.();
117
+ void check();
118
+ },
119
+ stop() {
120
+ if (timer) clearInterval(timer);
121
+ timer = void 0;
122
+ }
123
+ };
124
+ }
125
+ function guardOutput(onError, fs) {
126
+ for (const [stream, fd] of [[process.stdout, 1], [process.stderr, 2]]) {
127
+ stream.on("error", onError);
128
+ let file = false;
129
+ try {
130
+ file = fs.fstatSync(fd).isFile();
131
+ } catch {
132
+ }
133
+ if (!file) continue;
134
+ stream.write = ((chunk, encoding, callback) => {
135
+ try {
136
+ fs.writeSync(fd, chunk);
137
+ } catch (error) {
138
+ onError(error);
139
+ }
140
+ const done = typeof encoding === "function" ? encoding : callback;
141
+ if (typeof done === "function") done();
142
+ return true;
143
+ });
144
+ }
145
+ }
146
+ export {
147
+ GiB,
148
+ createDiskGuard,
149
+ formatBytes,
150
+ guardOutput,
151
+ isDiskError
152
+ };
@@ -0,0 +1,262 @@
1
+ import { type GitCheckOptions } from './gitignore.js';
2
+ export { gitChecksRunning, resolveGit, GIT_CHECK } from './gitignore.js';
3
+ /**
4
+ * `workspace.files.search` (docs/protocol/alp-json-rpc-v1.md §12.3): the files of a workspace whose
5
+ * path matches a query, as Paseo's command center finds them (server/utils/directory-suggestions.ts
6
+ * at b63a325, with its workspace settings: relative paths, hidden and heavy directories skipped).
7
+ *
8
+ * Read-only and confined to the workspace: the walk starts at the root's real path and never
9
+ * follows a symbolic link (a link is neither listed nor entered). Each directory is checked before
10
+ * and after it is read: a real directory (not a link), at the real path it was reached by, the same
11
+ * one (device and inode) both times; otherwise what was read is dropped. Only names are read, never
12
+ * contents. A link swapped in and back out between those checks, by a writer racing inside the
13
+ * workspace, can still expose names of the directory it pointed to (Node has no openat/O_NOFOLLOW
14
+ * walk); docs/protocol/alp-json-rpc-v1.md §12.3. The walk stops at {@link LIMITS}, checked per
15
+ * entry; the answer then says `truncated`.
16
+ */
17
+ export declare const LIMITS: Readonly<{
18
+ /** Directory levels below the root that are entered (Paseo's DEFAULT_MAX_DEPTH). */
19
+ depth: 12;
20
+ /** Directory entries looked at (Paseo's DEFAULT_MAX_ENTRIES_SCANNED). */
21
+ scanned: 20000;
22
+ /** Wall time of one search. */
23
+ ms: 3000;
24
+ /** Results by default and at most (Paseo's DEFAULT_LIMIT, MAX_LIMIT). */
25
+ defaultLimit: 30;
26
+ maxLimit: 100;
27
+ }>;
28
+ export declare class FilesError extends Error {
29
+ }
30
+ type Kind = 'file' | 'directory';
31
+ /**
32
+ * The files under `projectRoot` matching `query`, best first. `projectRoot` must be an absolute path
33
+ * of a directory; anything else throws FilesError.
34
+ */
35
+ export declare function searchWorkspaceFiles(projectRoot: string, { query, limit, now, git }?: {
36
+ query?: string;
37
+ limit?: number;
38
+ now?: () => number;
39
+ git?: GitCheckOptions;
40
+ }): Promise<{
41
+ files: Array<{
42
+ path: string;
43
+ }>;
44
+ truncated?: true;
45
+ }>;
46
+ /**
47
+ * Bounds of one workspace.files.find walk, deeper and larger than search's: as complete as
48
+ * `git ls-files` is for the Paseo bridge, which ranks the whole set itself. A snapshot of the
49
+ * names it found is kept `ttlMs` after its last page, at most `snapshots` of them in alpd.
50
+ */
51
+ export declare const FIND_LIMITS: Readonly<{
52
+ depth: 64;
53
+ scanned: 100000;
54
+ ms: 10000;
55
+ ttlMs: 60000;
56
+ snapshots: 16;
57
+ }>;
58
+ export type FoundEntry = {
59
+ path: string;
60
+ kind: Kind;
61
+ };
62
+ export type FindOptions = {
63
+ query?: string;
64
+ kinds?: readonly Kind[];
65
+ matchMode?: 'subsequence' | 'suffix';
66
+ now?: () => number;
67
+ git?: GitCheckOptions;
68
+ };
69
+ /** Whether `candidate` holds the characters of `query` in order (the Paseo bridge's last ranking tier). */
70
+ export declare function inOrder(query: string, candidate: string): boolean;
71
+ /**
72
+ * Every file and directory under `projectRoot` whose path, case-insensitively, holds `query`'s
73
+ * characters in order (`subsequence`, every name the Paseo bridge's ranking can match) or is it or
74
+ * ends with `/query` (`suffix`); every name for an empty query. In path order (code units).
75
+ *
76
+ * As `git ls-files --cached --others --exclude-standard` lists a repository: dot names included,
77
+ * .gitignore'd ones left out (Git's answer, failing closed as search does), and links whose real
78
+ * path is inside the root listed as their target's kind, never entered. Outside a repository,
79
+ * names starting with `.` and SKIPPED_FOLDERS are skipped. Blocked paths never appear. Bounded by
80
+ * FIND_LIMITS; `truncated` when a bound stopped the walk.
81
+ */
82
+ export declare function findWorkspaceEntries(projectRoot: string, { query, kinds, matchMode, now, git }?: FindOptions): Promise<{
83
+ entries: FoundEntry[];
84
+ truncated?: true;
85
+ }>;
86
+ /**
87
+ * workspace.files.find in pages: the first call (no cursor) walks and keeps the snapshot; each
88
+ * `nextCursor` names the snapshot and where the next page starts, for the connection (`owner`) that
89
+ * asked and the same params only. A snapshot is dropped after its last page, FIND_LIMITS.ttlMs
90
+ * after its last use, or when more than FIND_LIMITS.snapshots are kept (the oldest first).
91
+ */
92
+ export declare function createFindPages({ now, git }?: {
93
+ now?: () => number;
94
+ git?: GitCheckOptions;
95
+ }): (owner: unknown, projectRoot: string, { query, kinds, matchMode, limit, cursor }?: Omit<FindOptions, "now" | "git"> & {
96
+ limit?: number;
97
+ cursor?: string;
98
+ }) => Promise<{
99
+ entries: FoundEntry[];
100
+ nextCursor?: string;
101
+ truncated?: true;
102
+ }>;
103
+ /**
104
+ * A refusal of workspace.files.list or workspace.files.read: the JSON-RPC code and `data.reason`
105
+ * alpd answers with. Messages are fixed or name only the client's own relative path, never a host
106
+ * path or anything read from a file.
107
+ */
108
+ export declare class FileAccessError extends Error {
109
+ readonly code: number;
110
+ readonly reason: string;
111
+ constructor(message: string, code: number, reason: string);
112
+ }
113
+ /**
114
+ * A path relative to the workspace as a client may send it, its segments, or a refusal: '/'
115
+ * separated, no leading slash, drive or backslash, no `.`, `..` or empty segment, no NUL, at most
116
+ * WORKSPACE_FILES.maxPathLength characters. A blocked path (blockedFilePath) is refused as such.
117
+ */
118
+ export declare function relativeSegments(relative: unknown): string[];
119
+ /**
120
+ * The bytes of a regular file reached by name, or undefined when it is larger than `maxBytes`;
121
+ * throws when it is missing, not a regular file, a link, has more than one name, or is not the
122
+ * file it was a moment before. The file is opened without following a final link and checked by
123
+ * its handle (same device and inode as by name, before and after).
124
+ */
125
+ /** Test probes: called between the checks of a read, where a racing writer could change the file. */
126
+ export type FileProbe = (step: 'checked' | 'read' | 'listed') => Promise<void> | void;
127
+ /**
128
+ * The bytes of the file at `segments` under the real root `root`, confined as readWorkspaceFile
129
+ * confines a read (every directory on the way a real directory reached by name and the same after
130
+ * the read; the file a regular file with one name, opened without following a link, the same by
131
+ * handle and by name), or `too_large` past `maxBytes`. Throws FileAccessError `linked` or
132
+ * `not_found` (its message names only `relative`). No block list or .gitignore check: the caller
133
+ * decides what may be read (workspace.git.diff, docs/protocol/alp-json-rpc-v1.md §12.5).
134
+ */
135
+ export declare function readConfinedFile(root: string, segments: readonly string[], relative: string, maxBytes: number): Promise<Buffer | 'too_large'>;
136
+ /** Paseo's isLikelyBinary (file-explorer/service.ts at b63a325): a NUL byte, or over 30% control characters. */
137
+ export declare function likelyBinary(buffer: Buffer): boolean;
138
+ /** PEM, OpenSSH and PuTTY private-key headers: a file holding one is refused whatever its name. */
139
+ export declare const PRIVATE_KEY: RegExp;
140
+ export type ListedEntry = {
141
+ name: string;
142
+ path: string;
143
+ kind: 'file' | 'directory';
144
+ size?: number;
145
+ modifiedAt?: string;
146
+ target?: string;
147
+ };
148
+ /**
149
+ * The entries of a directory under `projectRoot` (its root without `relative`): regular files and
150
+ * directories only (links, sockets, devices are left out), never a blocked one (blockedFilePath)
151
+ * and, unless `includeIgnored`, none .gitignore'd. Directories first, then by name. Each directory
152
+ * on the way is checked (real directory, real path, same device and inode) before and after the
153
+ * read. At most WORKSPACE_FILES.maxListEntries entries; then `truncated` and `nextCursor`, which
154
+ * `cursor` takes to answer the entries after them.
155
+ *
156
+ * With `internalLinks` (workspace.files.browse): a link whose real path is inside the root and not
157
+ * blocked is listed as what it leads to, with that path as `target`, and `relative` may go through
158
+ * such links (the answer's `target` then names the directory listed, and entries are under it).
159
+ * Both the link's path and its target must pass .gitignore. A link leading outside is left out,
160
+ * and refused (`outside`) as `relative`.
161
+ */
162
+ export declare function listWorkspaceDirectory(projectRoot: string, { path: relative, includeIgnored, cursor, internalLinks, now, probe, git }?: {
163
+ path?: string;
164
+ includeIgnored?: boolean;
165
+ cursor?: string;
166
+ internalLinks?: boolean;
167
+ now?: () => number;
168
+ probe?: FileProbe;
169
+ git?: GitCheckOptions;
170
+ }): Promise<{
171
+ entries: ListedEntry[];
172
+ truncated?: true;
173
+ nextCursor?: string;
174
+ target?: string;
175
+ }>;
176
+ /**
177
+ * The content of a UTF-8 text file under `projectRoot`, read-only: refused when it is blocked
178
+ * (blockedFilePath), .gitignore'd (unless `includeIgnored`), missing or not a regular file,
179
+ * reached through a link (any directory on the way or the file), has more than one name (a hard
180
+ * link may share a file from anywhere), changes while it is read, is over
181
+ * WORKSPACE_FILES.maxReadBytes, or is not UTF-8 text.
182
+ */
183
+ export declare function readWorkspaceFile(projectRoot: string, { path: relative, includeIgnored, probe, git }: {
184
+ path: string;
185
+ includeIgnored?: boolean;
186
+ probe?: FileProbe;
187
+ git?: GitCheckOptions;
188
+ }): Promise<{
189
+ path: string;
190
+ content: string;
191
+ size: number;
192
+ modifiedAt: string;
193
+ }>;
194
+ /** Images a preview answers as such, by extension (the Paseo bridge's own list). */
195
+ export declare const PREVIEW_IMAGES: Readonly<Record<string, string>>;
196
+ export type FilePreview = {
197
+ path: string;
198
+ target?: string;
199
+ kind: 'text' | 'image' | 'binary';
200
+ mimeType: string;
201
+ size: number;
202
+ modifiedAt: string;
203
+ revision: string;
204
+ encoding: 'base64' | 'none';
205
+ content?: string;
206
+ offset?: number;
207
+ nextOffset?: number;
208
+ };
209
+ /**
210
+ * A preview of a file under `projectRoot`, as the Paseo bridge's Files panel showed one: `image`
211
+ * by extension (PREVIEW_IMAGES), else `text` when the whole file is (classify), else `binary`
212
+ * (metadata only, no content). Text and image bytes come as base64 in chunks of at most
213
+ * WORKSPACE_FILES.maxPreviewChunkBytes: the first from `offset` 0, each next one from the
214
+ * `nextOffset` before with the `revision` the first answered (a file that changed since is
215
+ * refused `changed`, so the chunks are of one file). At most `maxBytes` (and
216
+ * WORKSPACE_FILES.maxPreviewBytes), else `too_large`.
217
+ *
218
+ * Refused as workspace.files.read refuses: a blocked path, a .gitignore'd one (unless
219
+ * `includeIgnored`), missing or not a regular file, reached through a link, more than one name, a
220
+ * change while it is read; a text file holding a private key (and any chunk holding one) is
221
+ * refused `blocked_path`. With `internalLinks`, `relative` may go through links whose real path is
222
+ * inside the root (internalSegments): that real path, answered as `target`, is what is read, and
223
+ * both paths must pass .gitignore.
224
+ */
225
+ export declare function previewWorkspaceFile(projectRoot: string, { path: relative, includeIgnored, internalLinks, maxBytes, offset, revision, probe, git }: {
226
+ path: string;
227
+ includeIgnored?: boolean;
228
+ internalLinks?: boolean;
229
+ maxBytes?: number;
230
+ offset?: number;
231
+ revision?: string;
232
+ probe?: FileProbe;
233
+ git?: GitCheckOptions;
234
+ }): Promise<FilePreview>;
235
+ /** Bounds of host.directories.search: home's directories `depth` levels down, `scanned` looked at; a typed path's parent read up to `listed` entries. */
236
+ export declare const HOST_DIRECTORIES: Readonly<{
237
+ depth: 4;
238
+ scanned: 5000;
239
+ listed: 20000;
240
+ defaultLimit: 30;
241
+ maxLimit: 100;
242
+ }>;
243
+ /** 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. */
244
+ export declare function nameRank(candidate: string, query: string): number | undefined;
245
+ /**
246
+ * The daemon host's directories for the folder a user adds as a project, as the Paseo bridge
247
+ * suggested them: a `query` that is a path (absolute, or `~` and `~/…` under `home`) answers the
248
+ * directories of its parent whose name starts with what follows the last separator (dot names only
249
+ * when that starts with `.`), by name; any other word answers the directories under `home`, up to
250
+ * HOST_DIRECTORIES.depth levels and .scanned of them (no dot names, none of SKIPPED_FOLDERS), whose
251
+ * name matches it (nameRank), best, then nearest, first. Names only; a link is neither listed nor
252
+ * entered. Absolute paths: the caller is the host's owner (never remote).
253
+ */
254
+ export declare function searchHostDirectories(query: unknown, { limit, home }?: {
255
+ limit?: number;
256
+ home?: string;
257
+ }): Promise<{
258
+ entries: Array<{
259
+ path: string;
260
+ }>;
261
+ truncated?: true;
262
+ }>;