@banzhe/dsh-devcontainer 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -2
- package/README.zh-CN.md +80 -0
- package/cordis.patch.yml +71 -0
- package/lib/client.js +789 -0
- package/lib/client.js.map +1 -0
- package/lib/exec-CKAAz2zz.js +241 -0
- package/lib/exec-CKAAz2zz.js.map +1 -0
- package/lib/exec-_8g5fdSx.d.ts +26 -0
- package/lib/exec-_8g5fdSx.d.ts.map +1 -0
- package/lib/fs.d.ts +530 -0
- package/lib/fs.d.ts.map +1 -0
- package/lib/fs.js +1737 -0
- package/lib/fs.js.map +1 -0
- package/lib/helper/main.mjs +1008 -0
- package/lib/index.d.ts +88 -0
- package/lib/index.d.ts.map +1 -0
- package/lib/index.js +927 -0
- package/lib/index.js.map +1 -0
- package/lib/sbx-1GsFjQBk.js +1489 -0
- package/lib/sbx-1GsFjQBk.js.map +1 -0
- package/lib/shell.d.ts +175 -0
- package/lib/shell.d.ts.map +1 -0
- package/lib/shell.js +454 -0
- package/lib/shell.js.map +1 -0
- package/lib/types-DsF9Hz5P.d.ts +33 -0
- package/lib/types-DsF9Hz5P.d.ts.map +1 -0
- package/package.json +116 -3
package/lib/fs.d.ts
ADDED
|
@@ -0,0 +1,530 @@
|
|
|
1
|
+
import { t as ContainerRun } from "./exec-_8g5fdSx.js";
|
|
2
|
+
import { t as ContainerOptions } from "./types-DsF9Hz5P.js";
|
|
3
|
+
import z from "@deepseek-ai/schemastery";
|
|
4
|
+
import { Context } from "@deepseek-ai/cordis";
|
|
5
|
+
import { FsDirEntry, FsEditOutcome, FsEditRequest, FsInfo, FsPathInfo, FsTarget, FsVersion, FsWriteIntent, FsWriteOutcome } from "@deepseek-ai/dsh-fs";
|
|
6
|
+
import { SandboxedFileSystem } from "@deepseek-ai/dsh-fs-sandbox";
|
|
7
|
+
import { Config as Config$1 } from "@deepseek-ai/dsh-fs-local";
|
|
8
|
+
import { Readable, Writable } from "node:stream";
|
|
9
|
+
//#region src/rpc/client.d.ts
|
|
10
|
+
/** One long-lived child process with piped stdio. */
|
|
11
|
+
interface ContainerChild {
|
|
12
|
+
/** The channel's request bytes. */
|
|
13
|
+
readonly stdin: Writable;
|
|
14
|
+
/** The helper's frame bytes. */
|
|
15
|
+
readonly stdout: Readable;
|
|
16
|
+
/** Diagnostics; never framed. */
|
|
17
|
+
readonly stderr: Readable;
|
|
18
|
+
/** Resolves once the process is gone, however it went. */
|
|
19
|
+
readonly exited: Promise<{
|
|
20
|
+
readonly code: number | null;
|
|
21
|
+
readonly signal: string | null;
|
|
22
|
+
}>;
|
|
23
|
+
/** Request termination. */
|
|
24
|
+
kill(signal?: NodeJS.Signals): void;
|
|
25
|
+
}
|
|
26
|
+
/** Starts one child process for the container; replaced in tests. */
|
|
27
|
+
type ContainerChildSpawn = (argv: readonly string[], options?: {
|
|
28
|
+
readonly cwd?: string;
|
|
29
|
+
}) => ContainerChild;
|
|
30
|
+
/** What the helper reports about itself once the handshake completes. */
|
|
31
|
+
interface RpcHandshake {
|
|
32
|
+
/** The wire version it speaks. */
|
|
33
|
+
readonly protocol: number;
|
|
34
|
+
/** Its `process.platform`; expected to be the container's. */
|
|
35
|
+
readonly platform: string;
|
|
36
|
+
/** Its `process.version`. */
|
|
37
|
+
readonly nodeVersion: string;
|
|
38
|
+
/** The workspace the channel was opened for. */
|
|
39
|
+
readonly workspace: string;
|
|
40
|
+
/** That workspace's realpath inside the container. */
|
|
41
|
+
readonly workspaceReal: string;
|
|
42
|
+
}
|
|
43
|
+
/** Which runtime a channel speaks to, and the directory it treats as home. */
|
|
44
|
+
type ChannelTarget = {
|
|
45
|
+
readonly kind: 'docker';
|
|
46
|
+
readonly containerId: string;
|
|
47
|
+
readonly workspace: string;
|
|
48
|
+
} | {
|
|
49
|
+
readonly kind: 'sbx';
|
|
50
|
+
readonly sandboxName: string;
|
|
51
|
+
readonly workspace: string;
|
|
52
|
+
};
|
|
53
|
+
/** Options for one channel. */
|
|
54
|
+
interface ChannelOptions {
|
|
55
|
+
/** The runtime the helper runs in, and its workspace. */
|
|
56
|
+
readonly target: ChannelTarget;
|
|
57
|
+
/** The process starter; the Docker / sandbox CLI by default. */
|
|
58
|
+
readonly spawn?: ContainerChildSpawn;
|
|
59
|
+
/** Budget for staging, the handshake, and each later request. */
|
|
60
|
+
readonly timeoutMs?: number;
|
|
61
|
+
/** In-flight request ceiling. */
|
|
62
|
+
readonly maxPending?: number;
|
|
63
|
+
}
|
|
64
|
+
/** Options for one request. */
|
|
65
|
+
interface RequestOptions {
|
|
66
|
+
/** Cancels the request; the channel tells the helper to stop, it does not roll back. */
|
|
67
|
+
readonly signal?: AbortSignal;
|
|
68
|
+
/** Overrides the channel's per-request budget. */
|
|
69
|
+
readonly timeoutMs?: number;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* One live request/response pipe to a container's filesystem helper.
|
|
73
|
+
*
|
|
74
|
+
* A channel is single-use in the sense that matters: once the pipe fails, every
|
|
75
|
+
* later call rejects, and the pool that owns it opens a fresh one. Nothing is
|
|
76
|
+
* replayed, because a mutation that died mid-flight has an unknown outcome.
|
|
77
|
+
*/
|
|
78
|
+
declare class ContainerRpcChannel {
|
|
79
|
+
private readonly pending;
|
|
80
|
+
private readonly decoder;
|
|
81
|
+
private readonly child;
|
|
82
|
+
private readonly label;
|
|
83
|
+
private readonly timeoutMs;
|
|
84
|
+
private readonly maxPending;
|
|
85
|
+
private readonly closed;
|
|
86
|
+
private writeTail;
|
|
87
|
+
private stderrTail;
|
|
88
|
+
private preface;
|
|
89
|
+
private proseOnly;
|
|
90
|
+
private framesStarted;
|
|
91
|
+
private failure;
|
|
92
|
+
private handshakeValue;
|
|
93
|
+
private constructor();
|
|
94
|
+
/**
|
|
95
|
+
* Stage the helper, start its process, and complete the handshake.
|
|
96
|
+
* @param options - the container, its workspace, and the process starter.
|
|
97
|
+
* @returns the open channel.
|
|
98
|
+
* @throws Error when staging, the process start, or the handshake fails.
|
|
99
|
+
*/
|
|
100
|
+
static open(options: ChannelOptions): Promise<ContainerRpcChannel>;
|
|
101
|
+
/** What the helper reported during the handshake. */
|
|
102
|
+
get handshake(): RpcHandshake;
|
|
103
|
+
/** Whether the pipe failed or was closed; a closed channel never recovers. */
|
|
104
|
+
get isClosed(): boolean;
|
|
105
|
+
/** Resolves once the channel is unusable. */
|
|
106
|
+
get closedPromise(): Promise<void>;
|
|
107
|
+
/**
|
|
108
|
+
* Send one request and settle with the helper's answer.
|
|
109
|
+
*
|
|
110
|
+
* The frame is written under the same scope as the answer, so the budget and
|
|
111
|
+
* the caller's cancellation end a write that is still waiting for a pipe that
|
|
112
|
+
* will not take the bytes. A pipe that stays wedged is reset rather than left
|
|
113
|
+
* to block every later request behind the same write.
|
|
114
|
+
* @param method - the helper operation, for example `fs.readText`.
|
|
115
|
+
* @param params - JSON parameters.
|
|
116
|
+
* @param options - cancellation and a per-request budget.
|
|
117
|
+
* @returns the validated remote value.
|
|
118
|
+
* @throws RpcOperationError for a remote failure, Error for transport, cancellation and timeouts.
|
|
119
|
+
*/
|
|
120
|
+
request<T>(method: string, params: unknown, options?: RequestOptions): Promise<T>;
|
|
121
|
+
/**
|
|
122
|
+
* Probe the helper's liveness.
|
|
123
|
+
* @param options - cancellation and a per-request budget.
|
|
124
|
+
* @returns the helper's clock, once it answered.
|
|
125
|
+
*/
|
|
126
|
+
ping(options?: RequestOptions): Promise<{
|
|
127
|
+
readonly pong: boolean;
|
|
128
|
+
readonly now: number;
|
|
129
|
+
}>;
|
|
130
|
+
/**
|
|
131
|
+
* Stop the helper and fail everything still pending.
|
|
132
|
+
* @param reason - the failure reported to pending callers; a closure message by default.
|
|
133
|
+
*/
|
|
134
|
+
close(reason?: Error): Promise<void>;
|
|
135
|
+
private consume;
|
|
136
|
+
private receive;
|
|
137
|
+
/**
|
|
138
|
+
* Put one frame on the pipe.
|
|
139
|
+
* @param frame - the frame to write.
|
|
140
|
+
* @param interruption - ends the write when the caller behind it gives up; omitted for the frames the channel writes on its own behalf.
|
|
141
|
+
* @throws Error when the channel is broken, or when the interruption ended the write.
|
|
142
|
+
*/
|
|
143
|
+
private send;
|
|
144
|
+
/**
|
|
145
|
+
* Wait for the pipe to take buffered bytes.
|
|
146
|
+
* @param scope - ends the wait when the caller gives up.
|
|
147
|
+
* @returns true when the pipe drained, false when the wait ended another way.
|
|
148
|
+
* @throws Error when the pipe died during the wait.
|
|
149
|
+
*/
|
|
150
|
+
private awaitDrain;
|
|
151
|
+
/** Re-read the channel state, which an awaited step may have changed. */
|
|
152
|
+
private throwIfBroken;
|
|
153
|
+
private transportFailure;
|
|
154
|
+
/**
|
|
155
|
+
* The failure of a pipe that answered with prose instead of frames.
|
|
156
|
+
*
|
|
157
|
+
* A runtime without the `node` the helper needs replies with its own exec
|
|
158
|
+
* diagnostic, so the first four bytes of `exec: ...` decode as a length header
|
|
159
|
+
* of 1702389091 bytes. Reporting the frame size hides the cause; the collected
|
|
160
|
+
* text is what the reader can act on.
|
|
161
|
+
*/
|
|
162
|
+
private proseFailure;
|
|
163
|
+
private fail;
|
|
164
|
+
}
|
|
165
|
+
//#endregion
|
|
166
|
+
//#region src/fs.d.ts
|
|
167
|
+
/** Plugin name used by the Loader row. */
|
|
168
|
+
declare const name = "devcontainer-fs";
|
|
169
|
+
/** The local backend's knobs plus this Bundle's container options. */
|
|
170
|
+
interface Config extends Config$1, ContainerOptions {
|
|
171
|
+
/** Budget for one container filesystem request, in milliseconds. */
|
|
172
|
+
rpcTimeoutMs?: number;
|
|
173
|
+
}
|
|
174
|
+
/** The row's schema, typed for callers; the loader reads the class's static copy. */
|
|
175
|
+
declare const Config: z<Config>;
|
|
176
|
+
/**
|
|
177
|
+
* The filesystem seam for container-bound sessions: host behaviour for ordinary
|
|
178
|
+
* presets, full remote delegation for `(devContainer)` ones.
|
|
179
|
+
*/
|
|
180
|
+
declare class DevcontainerFileSystem extends SandboxedFileSystem {
|
|
181
|
+
/**
|
|
182
|
+
* The schema the Loader resolves this row's config through; a static because
|
|
183
|
+
* the module's `default` export is this class (see
|
|
184
|
+
* `DevcontainerShellExecutor.Config` for the same reason).
|
|
185
|
+
*/
|
|
186
|
+
static Config: z<Schemastery.ObjectS<NoInfer<{
|
|
187
|
+
shell: z<string, string, "defined">;
|
|
188
|
+
cli: z<"devcontainer" | "auto" | "docker" | "sbx", "devcontainer" | "auto" | "docker" | "sbx", "defined">;
|
|
189
|
+
ensureUp: z<boolean, boolean, "defined">;
|
|
190
|
+
containerTimeoutMs: z<number, number, "defined">;
|
|
191
|
+
requireContainer: z<boolean, boolean, "defined">;
|
|
192
|
+
cwd: z<string, string, "defined">;
|
|
193
|
+
diffBasisMaxBytes: z<number, number, "defined">;
|
|
194
|
+
rpcTimeoutMs: z<number, number, "defined">;
|
|
195
|
+
}>>, Schemastery.ObjectT<NoInfer<{
|
|
196
|
+
shell: z<string, string, "defined">;
|
|
197
|
+
cli: z<"devcontainer" | "auto" | "docker" | "sbx", "devcontainer" | "auto" | "docker" | "sbx", "defined">;
|
|
198
|
+
ensureUp: z<boolean, boolean, "defined">;
|
|
199
|
+
containerTimeoutMs: z<number, number, "defined">;
|
|
200
|
+
requireContainer: z<boolean, boolean, "defined">;
|
|
201
|
+
cwd: z<string, string, "defined">;
|
|
202
|
+
diffBasisMaxBytes: z<number, number, "defined">;
|
|
203
|
+
rpcTimeoutMs: z<number, number, "defined">;
|
|
204
|
+
}>>, "plain">;
|
|
205
|
+
/** Test seam: replaces the host CLI runner, the container process starter, and the channel. */
|
|
206
|
+
containerInternals: {
|
|
207
|
+
run?: ContainerRun;
|
|
208
|
+
spawn?: ContainerChildSpawn;
|
|
209
|
+
channel?: (target: ChannelTarget) => Promise<ContainerRpcChannel>;
|
|
210
|
+
};
|
|
211
|
+
/** The container options this row was configured with (the inherited `config` is typed by the local backend). */
|
|
212
|
+
private readonly options;
|
|
213
|
+
/** Budget for one RPC round trip. */
|
|
214
|
+
private readonly rpcTimeoutMs;
|
|
215
|
+
/** Whether the configured directory has been walked for a declaration yet. */
|
|
216
|
+
private warmed;
|
|
217
|
+
/** Whether this composition has learned where its sandbox mounts the workspace. */
|
|
218
|
+
private sbxProbed;
|
|
219
|
+
/** One channel per container, shared by every call of this composition. */
|
|
220
|
+
private readonly pool;
|
|
221
|
+
/** One resolved runtime per repository, so a burst of calls probes the CLI once. */
|
|
222
|
+
private readonly containers;
|
|
223
|
+
constructor(ctx: Context, config: Config);
|
|
224
|
+
/**
|
|
225
|
+
* Resolve a model-supplied path inside the container, or translate it onto the
|
|
226
|
+
* host bind mount for an ordinary preset.
|
|
227
|
+
* @param path - the path to resolve; relative paths resolve against `opts.cwd`.
|
|
228
|
+
* @param opts - optional cwd override and cancellation signal.
|
|
229
|
+
* @returns the stable target.
|
|
230
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this path is outside the repository's mount.
|
|
231
|
+
*/
|
|
232
|
+
resolve(path: string, opts?: {
|
|
233
|
+
cwd?: string;
|
|
234
|
+
signal?: AbortSignal;
|
|
235
|
+
}): Promise<FsTarget>;
|
|
236
|
+
/**
|
|
237
|
+
* The host path a target stands for, when the container's spelling is not one.
|
|
238
|
+
*
|
|
239
|
+
* A container path names a directory inside the runtime. On a POSIX host that
|
|
240
|
+
* namespace is still the host's own root, so the container spelling is a usable
|
|
241
|
+
* host path and the inherited identity — the target key, which the wire also
|
|
242
|
+
* carries — is the right answer. A Windows host has no such root: `/f/personal/repo`
|
|
243
|
+
* is a drive-relative path there, and `path.resolve('/f/personal/repo', '.git')`
|
|
244
|
+
* yields `F:\f\personal\repo\.git`, a directory no repository contains.
|
|
245
|
+
*
|
|
246
|
+
* Host-bound consumers read this value as a HOST path — `WorkingDirectoryService`
|
|
247
|
+
* commits it as the Session directory, the project-root walk appends `.git` to
|
|
248
|
+
* it, and `ctx.subprocess` starts a process in it — so a container spelling that
|
|
249
|
+
* no host path module can resolve would fail them all. A Windows-rooted
|
|
250
|
+
* repository therefore answers the host path of its mount; the container spelling
|
|
251
|
+
* keeps the two jobs it owns, the argv a runtime is started with
|
|
252
|
+
* (`buildExecArgv`) and the payload of an RPC request (`wireTargetOf`).
|
|
253
|
+
* @param target - the resolved target.
|
|
254
|
+
* @returns its host path, or the inherited identity outside a Windows-rooted repository.
|
|
255
|
+
*/
|
|
256
|
+
processPath(target: FsTarget): string;
|
|
257
|
+
/**
|
|
258
|
+
* Probe a path inside the container without following its final symlink.
|
|
259
|
+
* @param path - the path to inspect.
|
|
260
|
+
* @param opts - `cwd` overrides the base for relative paths.
|
|
261
|
+
* @param signal - aborts the metadata round-trip.
|
|
262
|
+
* @returns metadata only, or undefined when the path is absent.
|
|
263
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this path is outside the repository's mount.
|
|
264
|
+
*/
|
|
265
|
+
lstat(path: string, opts?: {
|
|
266
|
+
cwd?: string;
|
|
267
|
+
}, signal?: AbortSignal): Promise<FsPathInfo | undefined>;
|
|
268
|
+
/**
|
|
269
|
+
* Read metadata of a resolved target.
|
|
270
|
+
* @param target - the resolved target.
|
|
271
|
+
* @param signal - aborts the metadata round-trip.
|
|
272
|
+
* @returns metadata only, or undefined when the target is absent.
|
|
273
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this target is not in a container repository.
|
|
274
|
+
*/
|
|
275
|
+
stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>;
|
|
276
|
+
/**
|
|
277
|
+
* Read a whole text file inside the container.
|
|
278
|
+
* @param target - the resolved target.
|
|
279
|
+
* @param signal - aborts the read.
|
|
280
|
+
* @returns the file's text.
|
|
281
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this target is not in a container repository.
|
|
282
|
+
*/
|
|
283
|
+
readText(target: FsTarget, signal?: AbortSignal): Promise<string>;
|
|
284
|
+
/**
|
|
285
|
+
* Stream a text file through the container helper's iterator.
|
|
286
|
+
*
|
|
287
|
+
* Only the refusal is decided here; the `fs.stream` request belongs to the
|
|
288
|
+
* first iteration, so an iterator nobody reads holds no helper slot.
|
|
289
|
+
* @param target - the resolved target.
|
|
290
|
+
* @param signal - aborts the stream.
|
|
291
|
+
* @returns the text stream.
|
|
292
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this target is not in a container repository.
|
|
293
|
+
*/
|
|
294
|
+
streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>;
|
|
295
|
+
/**
|
|
296
|
+
* Read a file as bytes inside the container.
|
|
297
|
+
* @param target - the resolved target.
|
|
298
|
+
* @param signal - aborts the read.
|
|
299
|
+
* @param maxBytes - the exclusive size limit.
|
|
300
|
+
* @returns the file's bytes.
|
|
301
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this target is not in a container repository.
|
|
302
|
+
*/
|
|
303
|
+
readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>;
|
|
304
|
+
/**
|
|
305
|
+
* Read a bounded byte range inside the container.
|
|
306
|
+
* @param target - the resolved target.
|
|
307
|
+
* @param range - offset and length of the window.
|
|
308
|
+
* @param signal - aborts the read.
|
|
309
|
+
* @returns the bytes of that window.
|
|
310
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this target is not in a container repository.
|
|
311
|
+
*/
|
|
312
|
+
readByteRange(target: FsTarget, range: {
|
|
313
|
+
offset: number;
|
|
314
|
+
length: number;
|
|
315
|
+
}, signal?: AbortSignal): Promise<Uint8Array>;
|
|
316
|
+
/**
|
|
317
|
+
* List one directory inside the container.
|
|
318
|
+
* @param target - the resolved directory target.
|
|
319
|
+
* @param signal - aborts the listing.
|
|
320
|
+
* @returns the direct children with their resolved targets.
|
|
321
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this target is not in a container repository.
|
|
322
|
+
*/
|
|
323
|
+
listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>;
|
|
324
|
+
/**
|
|
325
|
+
* Watch one target for the GUI.
|
|
326
|
+
*
|
|
327
|
+
* A host watcher would have to open a host path, which is exactly the
|
|
328
|
+
* penetration this row exists to prevent, so a container-backed watcher
|
|
329
|
+
* re-probes the target over RPC and reports a change when its version token
|
|
330
|
+
* moves.
|
|
331
|
+
* @param target - the resolved target to watch.
|
|
332
|
+
* @param changed - reports each change, or a watcher failure.
|
|
333
|
+
* @param signal - aborts the watch: aborting stops the polling even when the caller never calls the disposer.
|
|
334
|
+
* @returns the disposer of the watcher.
|
|
335
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this target is not in a container repository.
|
|
336
|
+
*/
|
|
337
|
+
watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>;
|
|
338
|
+
/**
|
|
339
|
+
* Write a whole file inside the container.
|
|
340
|
+
*
|
|
341
|
+
* The per-call sandbox policy is deliberately not applied: it describes host
|
|
342
|
+
* paths and a host mode, while the container is the confinement here.
|
|
343
|
+
* @param target - the resolved target to write.
|
|
344
|
+
* @param content - the full new file content.
|
|
345
|
+
* @param expected - the write intent guarding the write; omit for unconditional.
|
|
346
|
+
* @param signal - aborts before atomic publication takes effect.
|
|
347
|
+
* @param _sandboxPolicy - the host policy, unused for a container target.
|
|
348
|
+
* @returns the write outcome from the container helper.
|
|
349
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this target is not in a container repository.
|
|
350
|
+
*/
|
|
351
|
+
writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, _sandboxPolicy?: Parameters<SandboxedFileSystem['writeText']>[4]): Promise<FsWriteOutcome>;
|
|
352
|
+
/**
|
|
353
|
+
* Apply a literal edit inside the container.
|
|
354
|
+
* @param target - the resolved target to edit.
|
|
355
|
+
* @param edit - the literal search/replace request.
|
|
356
|
+
* @param expected - the version guard; omit for an unconditional edit.
|
|
357
|
+
* @param signal - aborts before atomic publication takes effect.
|
|
358
|
+
* @param _sandboxPolicy - the host policy, unused for a container target.
|
|
359
|
+
* @returns the edit outcome from the container helper.
|
|
360
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this target is not in a container repository.
|
|
361
|
+
*/
|
|
362
|
+
editText(target: FsTarget, edit: FsEditRequest, expected?: {
|
|
363
|
+
version: FsVersion;
|
|
364
|
+
}, signal?: AbortSignal, _sandboxPolicy?: Parameters<SandboxedFileSystem['editText']>[4]): Promise<FsEditOutcome>;
|
|
365
|
+
/** The container channel for one route, translated into the seam's error vocabulary. */
|
|
366
|
+
private remoteChannel;
|
|
367
|
+
/**
|
|
368
|
+
* Run one operation against a live channel, mapping its failures.
|
|
369
|
+
* @param spec - the repository whose container is used.
|
|
370
|
+
* @param signal - the caller's cancellation.
|
|
371
|
+
* @param operation - the work to run with the channel.
|
|
372
|
+
* @returns what the operation produced.
|
|
373
|
+
* @throws FsError for every transport and remote failure.
|
|
374
|
+
*/
|
|
375
|
+
private withChannel;
|
|
376
|
+
/** Send one request with this row's budget. */
|
|
377
|
+
private request;
|
|
378
|
+
/**
|
|
379
|
+
* One text stream, opened by its first iteration and closed however it ends.
|
|
380
|
+
*
|
|
381
|
+
* Opening inside the generator is what makes the lifecycle airtight: an
|
|
382
|
+
* iterator the caller drops without reading never sends `fs.stream`, and
|
|
383
|
+
* every way an iteration can stop — completion, `break`, a throw, a cancelled
|
|
384
|
+
* scope — runs the `finally` that sends `fs.streamClose`. The helper holds 64
|
|
385
|
+
* streams at most, so a leaked slot is a permanent loss for the session.
|
|
386
|
+
* A broken pipe drops the cached container too.
|
|
387
|
+
* @param channel - the live container channel.
|
|
388
|
+
* @param target - the target to stream, as the helper names it.
|
|
389
|
+
* @param spec - the repository whose container is used.
|
|
390
|
+
* @param signal - aborts the stream.
|
|
391
|
+
* @returns the text stream.
|
|
392
|
+
*/
|
|
393
|
+
private iterate;
|
|
394
|
+
/** The version token of one target, for the polling watcher. */
|
|
395
|
+
private versionOf;
|
|
396
|
+
/**
|
|
397
|
+
* The runtime filesystem calls are delegated to.
|
|
398
|
+
* @param spec - the repository container specification.
|
|
399
|
+
* @param signal - cancels the Docker / sandbox probe.
|
|
400
|
+
* @returns the resolved target the channel speaks to.
|
|
401
|
+
* @throws FsError `FS_IO_ERROR` when the runtime has no stdio endpoint for the helper.
|
|
402
|
+
*/
|
|
403
|
+
private runtimeTarget;
|
|
404
|
+
/** The cache key of one repository's container. */
|
|
405
|
+
private containerKey;
|
|
406
|
+
/** Drop one cached runtime, so the next call probes again. */
|
|
407
|
+
private forgetContainer;
|
|
408
|
+
/** Probe where the repository's container is, requiring an endpoint the helper can be started in. */
|
|
409
|
+
private probeContainer;
|
|
410
|
+
/** Translate one path for a container-bound call, refusing anything outside the mount. */
|
|
411
|
+
private remotePath;
|
|
412
|
+
/** Refuse a container path that leaves every spelling of the repository's mount. */
|
|
413
|
+
private assertInsideMount;
|
|
414
|
+
/** Refuse an already-resolved target that leaves the repository's mount. */
|
|
415
|
+
private assertTargetInsideMount;
|
|
416
|
+
/**
|
|
417
|
+
* Install the target-taking mutations this build's base class may not declare.
|
|
418
|
+
*
|
|
419
|
+
* An own property shadows the inherited method, so the wrapper is what every
|
|
420
|
+
* caller reaches: a container-bound call becomes an RPC, and an ordinary one
|
|
421
|
+
* still runs the inherited implementation — read from the prototype it was
|
|
422
|
+
* reached through — or reports a typed failure when this backend has none.
|
|
423
|
+
*/
|
|
424
|
+
private installTargetMutations;
|
|
425
|
+
/** Run one installed mutation over RPC. */
|
|
426
|
+
private remoteMutation;
|
|
427
|
+
/**
|
|
428
|
+
* Route one path-taking call.
|
|
429
|
+
* @param path - the path the caller named.
|
|
430
|
+
* @param cwd - the directory relative paths resolve against.
|
|
431
|
+
* @returns the container route, or undefined when this call keeps the host backend.
|
|
432
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and nothing declares a container for the path.
|
|
433
|
+
*/
|
|
434
|
+
private route;
|
|
435
|
+
/**
|
|
436
|
+
* Route one already-resolved call.
|
|
437
|
+
* @param target - the target the caller holds.
|
|
438
|
+
* @returns the container route, or undefined when this call keeps the host backend.
|
|
439
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this target is not in a container repository.
|
|
440
|
+
*/
|
|
441
|
+
private routeTarget;
|
|
442
|
+
/** Translate one path and its base directory onto the host, refusing a host-only call when the caller is container-bound. */
|
|
443
|
+
private mapPath;
|
|
444
|
+
/**
|
|
445
|
+
* The repository whose container governs one path.
|
|
446
|
+
* @param path - a host path, a container path, a sandbox path, or a relative path.
|
|
447
|
+
* @param cwd - the directory relative paths resolve against; the row's configured one when absent.
|
|
448
|
+
* @returns the governing specification, or undefined when the path belongs to no Dev Container repository.
|
|
449
|
+
*/
|
|
450
|
+
private repositoryFor;
|
|
451
|
+
/**
|
|
452
|
+
* The specification a sandbox-spelled path names, reversed onto the host.
|
|
453
|
+
*
|
|
454
|
+
* A path a sandbox mounts is attributed from the mount itself: the host
|
|
455
|
+
* directory it reported, and the workspace root that directory names — enough
|
|
456
|
+
* even for a workspace that declares no container, which is exactly what a
|
|
457
|
+
* `(sbx)` session mounts. The drive convention names no workspace root, only the
|
|
458
|
+
* spelling this host gives such a path, so it decides only when a repository
|
|
459
|
+
* declares a container above the directory it spells: `/f/…` cannot claim
|
|
460
|
+
* whatever host path it happens to name, and a sandbox path outside every mount
|
|
461
|
+
* stays refused locally.
|
|
462
|
+
* @param path - the path the call named.
|
|
463
|
+
* @param adopt - the calling track's view of a declared specification.
|
|
464
|
+
* @returns the governing specification, or undefined when nothing attributes the path.
|
|
465
|
+
*/
|
|
466
|
+
private specForSandboxPath;
|
|
467
|
+
/**
|
|
468
|
+
* Whether the fallback repository may claim one path.
|
|
469
|
+
*
|
|
470
|
+
* A container path of that repository, a host path under its root, or a
|
|
471
|
+
* relative path that resolves — against the same base the fallback names —
|
|
472
|
+
* to somewhere inside it. Anything else is a host path the repository does
|
|
473
|
+
* not own: `..` traversal and absolute paths elsewhere on the machine
|
|
474
|
+
* included.
|
|
475
|
+
* @param path - the path the call named.
|
|
476
|
+
* @param base - the directory relative paths resolve against.
|
|
477
|
+
* @param spec - the fallback repository specification.
|
|
478
|
+
* @returns true when that repository owns the path.
|
|
479
|
+
*/
|
|
480
|
+
private belongsTo;
|
|
481
|
+
/**
|
|
482
|
+
* Learn where the sandbox really mounts this workspace, before a path is
|
|
483
|
+
* attributed to it.
|
|
484
|
+
*
|
|
485
|
+
* A `(sbx)` session names paths in its sandbox's spelling, while a
|
|
486
|
+
* specification built from a host directory carries the host spelling until a
|
|
487
|
+
* listing reports the mount. Routing therefore asks the runtime once — the same
|
|
488
|
+
* probe the first call would run anyway — so `/f/personal/repo` is measured
|
|
489
|
+
* against the folder the sandbox reports instead of the drive path the host
|
|
490
|
+
* named. A probe that fails is not reported here: the call that needs the
|
|
491
|
+
* container reports it with the runtime's own diagnostic.
|
|
492
|
+
* @param kind - the runtime the calling preset selects, when one does.
|
|
493
|
+
* @param base - the directory this call resolves relative paths against.
|
|
494
|
+
*/
|
|
495
|
+
private prepareSbxMount;
|
|
496
|
+
/**
|
|
497
|
+
* The container requirement governing this call.
|
|
498
|
+
*
|
|
499
|
+
* A `(devContainer)` preset promises container execution, so its filesystem
|
|
500
|
+
* calls must not reach the host either; `requireContainer` asks for the same
|
|
501
|
+
* guarantee from every preset. Both are read per call, so switching presets
|
|
502
|
+
* mid-session needs no reload.
|
|
503
|
+
* @returns the requirement and the preset that states it, or undefined when this call may use the host.
|
|
504
|
+
*/
|
|
505
|
+
private containerRequirement;
|
|
506
|
+
/**
|
|
507
|
+
* Refuse a call that would leave the container's repository.
|
|
508
|
+
* @param path - the path the call names, for the diagnostic.
|
|
509
|
+
* @param resolved - the resolved path the helper would use for I/O, when it differs from `path`.
|
|
510
|
+
* @throws FsError `FS_PERMISSION_DENIED` when nothing in that path's ancestry declares a container.
|
|
511
|
+
*/
|
|
512
|
+
private refuseHostAccess;
|
|
513
|
+
/**
|
|
514
|
+
* Fence one already-resolved target for a host call.
|
|
515
|
+
*
|
|
516
|
+
* A target can outlive the state it was resolved under — a preset switched
|
|
517
|
+
* between the read and the write, a declaration deleted mid-session — so the
|
|
518
|
+
* requirement is re-read here rather than trusted from the ingress check. Both
|
|
519
|
+
* spellings a target carries are fenced, because they answer different
|
|
520
|
+
* questions: `displayPath` is the path the caller named, while `targetKey` is
|
|
521
|
+
* the realpath the backend actually opens.
|
|
522
|
+
* @param target - the target the operation would use.
|
|
523
|
+
* @returns the same target, so callers fence in place.
|
|
524
|
+
* @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and either spelling belongs to no container repository.
|
|
525
|
+
*/
|
|
526
|
+
private fenced;
|
|
527
|
+
}
|
|
528
|
+
//#endregion
|
|
529
|
+
export { Config, DevcontainerFileSystem, DevcontainerFileSystem as default, name };
|
|
530
|
+
//# sourceMappingURL=fs.d.ts.map
|
package/lib/fs.d.ts.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"fs.d.ts","names":[],"sources":["../src/rpc/client.ts","../src/fs.ts"],"mappings":";;;;;;;;;;UAgCiB;;WAEN,OAAO;;WAEP,QAAQ;;WAER,QAAQ;;WAER,QAAQ;aAAmB;aAA8B;;;EAElE,KAAK,SAAS,OAAO;;;KAIX,uBAAuB,yBAAyB;WAAqB;MAAmB;;UA6BnF;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;;KAIC;WACG;WAAyB;WAA8B;;WACvD;WAAsB;WAA8B;;;UA4BlD;;WAEN,QAAQ;;WAER,QAAQ;;WAER;;WAEA;;;UAIM;;WAEN,SAAS;;WAET;;;;;;;;;cAoHE;mBACM;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;UACT;UACA;UACA;UACA;UACA;UACA;UACA;UAED;;;;;;;SAoBM,KAAK,SAAS,iBAAiB,QAAQ;;MAiChD,aAAa;;MAMb;;MAKA,iBAAiB;;;;;;;;;;;;;;EAiBf,QAAQ,GAAG,gBAAgB,iBAAiB,UAAS,iBAAsB,QAAQ;;;;;;EA2CnF,KAAK,UAAS,iBAAsB;aAAmB;aAAwB;;;;;;EAQ/E,MAAM,SAAS,QAAQ;UAKrB;UAsBA;;;;;;;UAmBM;;;;;;;UA2CA;;UA0BN;UAKA;;;;;;;;;UAiBA;UASA;;;;;cC1bG;;UAGI,eAAe,UAAe;;EAE7C;;;cAqBW,QAAoC,EAAE;;;;;cAsEtC,+BAA+B;;;;;;SAM1B,QAAM,EAAA,YAAA,QAAA;;;;;;;;;;;;;;;;;;;;EAGtB;IACE,MAAM;IACN,QAAQ;IACR,WAAW,QAAQ,kBAAkB,QAAQ;;;mBAI9B;;mBAGA;;UAGT;;UAGA;;mBAGS;;mBAGA;EAEL,YAAA,KAAK,SAAS,QAAQ;;;;;;;;;EAqBnB,QAAQ,cAAc;IAAS;IAAc,SAAS;MAAgB,QAAQ;;;;;;;;;;;;;;;;;;;;;EAqCpF,YAAY,QAAQ;;;;;;;;;EAcd,MAAM,cAAc;IAAS;KAAgB,SAAS,cAAc,QAAQ;;;;;;;;EAsB5E,KAAK,QAAQ,UAAU,SAAS,cAAc,QAAQ;;;;;;;;EAiBtD,SAAS,QAAQ,UAAU,SAAS,cAAc;;;;;;;;;;;EAmBlD,WAAW,QAAQ,UAAU,SAAS,cAAc,QAAQ;;;;;;;;;EAgB5D,UAAU,QAAQ,UAAU,QAAQ,yBAAyB,mBAAmB,QAAQ;;;;;;;;;EAoBxF,cACb,QAAQ,UAAU;IAAS;IAAgB;KAAkB,SAAS,cACrE,QAAQ;;;;;;;;EAmBI,QAAQ,QAAQ,UAAU,SAAS,cAAc,QAAQ;;;;;;;;;;;;;;EAyBzD,MACb,QAAQ,UAAU,UAAU,QAAQ,gBAAgB,QAAQ,cAC3D,cAAc;;;;;;;;;;;;;;EA6DF,UACb,QAAQ,UAAU,iBAAiB,WAAW,eAAe,SAAS,aACtE,iBAAiB,WAAW,uCAC3B,QAAQ;;;;;;;;;;;EAwBI,SACb,QAAQ,UAAU,MAAM,eAAe;IAAa,SAAS;KAAa,SAAS,aACnF,iBAAiB,WAAW,sCAC3B,QAAQ;;UAeG;;;;;;;;;UAmBA;;UAiBA;;;;;;;;;;;;;;;;UAwBN;;UAgCM;;;;;;;;UAYN;;UAcA;;UAOA;;UAKM;;UAgBN;;UAUA;;UAUA;;;;;;;;;UAYA;;UAyBM;;;;;;;;UA2DA;;;;;;;UAkBA;;UAaN;;;;;;;UAkBA;;;;;;;;;;;;;;;;UAuDA;;;;;;;;;;;;;;UAwBA;;;;;;;;;;;;;;;UAyBM;;;;;;;;;;UAmBN;;;;;;;UAYA;;;;;;;;;;;;;;UAsBA"}
|